Documentation

• 1: Overview
• 2: Simple Worship
• 2.1: Display Clients
• 2.2: Installing
• 3: Libraries
• 3.1:
• 3.2:
• 3.3: August
• 3.4: GoBible

1 - Overview

The Overview is where your users find out about your project. Depending on the size of your docset, you can have a separate overview page (like this one) or put your overview contents in the Documentation landing page (like in the Docsy User Guide).

Try answering these questions for your user in this page:

What is it?

Introduce your project, including what it does or lets you do, why you would use it, and its primary goal (and how it achieves it). This should be similar to your README description, though you can go into a little more detail here if you want.

Why do I want it?

Help your user know if your project will help them. Useful information can include:

• What is it good for?: What types of problems does your project solve? What are the benefits of using it?

• What is it not good for?: For example, point out situations that might intuitively seem suited for your project, but aren’t for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.

• What is it not yet good for?: Highlight any useful features that are coming soon.

Where should I go next?

Give your users next steps from the Overview. For example:

• Getting Started: Get started with $project
• Examples: Check out some example code!

2 - Simple Worship

View on Github{: .btn .btn-blue .float-right }

Simple Worship

SimpleWorship is a free, open source, church presentation software.

The end goal here is a simple, easy to use, and free church presentation software that is cheap to deploy, pluggable for easy extensibility, and easy to use for volunteers to might not be as tech savvy.

Our Motivation

This project was started for two main reasons:

• We were tired of walled garden, proprietary and hard to interact with software for churches.
  • As the “technology people” at our churches, we want to be able to automate and simplify workflows, and make it extremely easy for volenteers to use the software.
  • We wanted flexibility and cost savings whenever possible, not relying on proprietary software to have the feature we want, but instead having the ability to, with a little time, add it ourselves.
• We felt compelled to use our tallents to serve the local church, and this is one way we can do that.

2.1 - Display Clients

Simple Worship Display Clients

By default, simple worship does not actually display any of your slides on its own.

It instead hosts a “display server”, and various display clients can connect to it.

This allows you to have multiple displays, and even multiple types of displays, easily.

Display Clients

Simple Worship Display

solafide-dev/simpleworship-display

This is the most likely display client people coming from another church presentation software will use. When ran on the same machine running SimpleWorship, you can mimic the standard experience of other church presentation software.

It runs on MacOS, Windows, and Linux, and simply opens a window with your slides that can be full-screened.

It leverages the SSDP protocol to automatically find the display server, so you don’t have to configure anything.

Web Display

Because SimpleWorship is built on web technologies, it is possible to use any web browser as a display client.

Simply point your browser to http://<display-server-ip>:7777 to view the slides in your browser. (Replace <display-server-ip> with the IP address of the machine running SimpleWorship)

2.2 - Installing

Install instructions will be available here when there is a public release of SimpleWorship

3 - Libraries

3.1 -

August

August is a persistant data storage library that is based around folders and flat files (JSON, YAML, XML).

Its main purpose is to provide a data store that prioritizes human readability and portability.

Its initial conception was to provide a data store for the SimpleWorship software, since data sets won’t be massive there, but human readability and portability are important.

Usage

// Initialize August
aug := august.Init()

// Set some configs (see below for available configs)
aug.Config(august.Config_Format, "json") // Set the format to yaml (default json)
aug.Config(august.Config_StorageDir, "./storage") // Set the storage directory (default ./storage)

// Setup the optional event fuction. This is useful if you need to subscribe to
// mutations in the data set to update other parts of your application.
aug.SetEventFunc(func(event, store, id string) {
    // Event will be one of create, update, delete
    // store will be the name of the store
    // id will be the id of the item that was created, updated, or deleted

    log.Printf("Event: %s, Store: %s, ID: %s", event, store, id)
})

type Person struct {
    Name string `json:"name"`
    Age int `json:"age"`
}

type Car struct {
    Make string `json:"make"`
    Model string `json:"model"`
}

// Register a data store to a type
aug.Register("people", Person{})
aug.Register("cars", Car{})

// Initialize the data store (this initializes any registered data stores, and loads any existing data)
if err := aug.Run(); err != nil {
    panic(err)
}

// Get a reference to the store
people, err := aug.GetStore("people")
if err != nil {
    panic(err)
}

// Add a person, with the ID "john-doe" to the store.
// The Set function will create / update the data store file.
err := people.Set("john-doe", Person{Name: "John Doe", Age: 30})

// Alternatively, you can allow august to generate a unique ID for you, if you don't want to manage them yourself.
id, err := people.New(Person{Name: "Jane Doe", Age: 28}) // ID will contain the new unique ID that was created.


// You can load data from a set using the Get function.
person, err := people.Get("john-doe") // or person, err := people.Get(id) to get Jane Doe we just created
fmt.Println(person.(Person).Name) // John Doe (notice the type assertion -- this is because the Get function returns an interface{})

// You can also optionally query all of the IDs in a set.
ids := people.GetIds()

for _, id := range ids {
    p, _ := people.Get(id)
    // Do something wich each data set item
}

This would result in a folder structure like this:

storage
├── people
│   ├── john-doe.json
│   └── f48929fa-8a8a-4af5-9511-a1c0794f9681.json
└── cars

You’ll notice cars is empty, as we never created any data in that set.

As an example, the contents of storage/people/john-doe.json would be:

{
    "name": "John Doe",
    "age": 30
}

If we have Config_FSNotify set to true, we can modify this file on disk and have the changes reflected in our datasets automatically.

# In Bash
jq '.age = 20' ./storage/people/john-doe.json | tee ./storage/people/john-doe.json

// Back in our Go program
person, _ := people.Get("john-doe")
fmt.Println(person.(Person).Age) // 20

Available Configs

Why the name August?

At Sola Fide, we like for anything we make to echo our Christianity, as all the work we do is for Christ’s Kingdom.

In the case of August, it is named after Saint Augustine of Hippo.

Saint Augustine was a philosopher and theologian who lived from 354 to 430 AD. He is considered one of the most important figures in the development of Western Christianity and was a major figure in bringing Christianity to dominance in the previously pagan Roman Empire.

3.2 -

Go Bible

Gobible is a library for interacting with the Bible in Go.

Bible Formats

Initially, Gobible was created as an effort to support an easy to use JSON format for the Bible for use in other projects, but through development has grown to instead be a library for working with that format, as well and importing other formats into the Gobible format.

Supported Formats

• Gobible JSON Example
• OSIS XML Example

Please note that since Gobible works around a data structure defined by the Gobible JSON format, some features of other formats may not be supported.

Usage

Initialization

There are a few ways to initialize a bible:

// Initialize an empty GoBible object
b := NewGoBible()

// Load a GoBible formatted JSON file
b.Load("KJV.json")

// Load an alternate support format
b.LoadFormat("WEB.xml", "osis")

One you have a Bible object with some translations loaded into it, you can use this object in a few ways.

Interacting with Individual Translations

You can load an individual translation, and use it similarly to this:

// Load the KJV translation
kjv := bible.GetTranslation("KJV")

// get a verse
verse := kjv.GetBook("Genesis").GetChapter(1).GetVerse(1)

fmt.Println("Genesis 1:1 - " + verse.Text)
// Genesis 1:1 - In the beginning God created the heaven and the earth.

You can also use this to generate GoBible format JSON files from other formats:

b := NewGoBible()
// Load an OSIS XML file
b.LoadFormat("WEB.xml", "osis")

// Save the translation as GoBible JSON
goBibleJson := b.GetBibleJSON("WEB")

// Save the translation as GoBible JSON to a file
os.WriteFile("WEB.json", []byte(goBibleJson), 0644)

Interacting by Reference

Once you have 1 or multiple translations loaded, you can interact with them by reference notation.

(If you have multiple translations loaded, the first translation loaded will be used as the default)

// Examples of some valid references:
//   John 3:16
//   John 3:16-18
//   1 Cor 1:2-5
//   1 Cor 1:2-2:5 
// You can also tag the translation at the end of the reference
//   John 3:16 WEB 
//   John 3:16 KJV

// Lookup by reference
refs, _ := b.ParseReference("Gen 1:31-2:1")
for _, r := range refs {
    fmt.Printf("%s %d:%d %s", r.Book, r.Chapter, r.Verse, r.VerseRef.Text)
}
// Genesis 1:31 God saw everything that he had made, and, behold, it was very good. There was evening and there was morning, the sixth day.
// Genesis 2:1 The heavens and the earth were finished, and all the host of them.

Looking for Bibles?

We have published a few Public Domain bibles, as well as a Go program to generate additional ones in the gobible-gen repo.

3.3 - August

August

August is a persistant data storage library that is based around folders and flat files (JSON, YAML, XML).

Its main purpose is to provide a data store that prioritizes human readability and portability.

Its initial conception was to provide a data store for the SimpleWorship software, since data sets won’t be massive there, but human readability and portability are important.

Usage

// Initialize August
aug := august.Init()

// Set some configs (see below for available configs)
aug.Config(august.Config_Format, "json") // Set the format to yaml (default json)
aug.Config(august.Config_StorageDir, "./storage") // Set the storage directory (default ./storage)

// Setup the optional event fuction. This is useful if you need to subscribe to
// mutations in the data set to update other parts of your application.
aug.SetEventFunc(func(event, store, id string) {
    // Event will be one of create, update, delete
    // store will be the name of the store
    // id will be the id of the item that was created, updated, or deleted

    log.Printf("Event: %s, Store: %s, ID: %s", event, store, id)
})

type Person struct {
    Name string `json:"name"`
    Age int `json:"age"`
}

type Car struct {
    Make string `json:"make"`
    Model string `json:"model"`
}

// Register a data store to a type
aug.Register("people", Person{})
aug.Register("cars", Car{})

// Initialize the data store (this initializes any registered data stores, and loads any existing data)
if err := aug.Run(); err != nil {
    panic(err)
}

// Get a reference to the store
people, err := aug.GetStore("people")
if err != nil {
    panic(err)
}

// Add a person, with the ID "john-doe" to the store.
// The Set function will create / update the data store file.
err := people.Set("john-doe", Person{Name: "John Doe", Age: 30})

// Alternatively, you can allow august to generate a unique ID for you, if you don't want to manage them yourself.
id, err := people.New(Person{Name: "Jane Doe", Age: 28}) // ID will contain the new unique ID that was created.


// You can load data from a set using the Get function.
person, err := people.Get("john-doe") // or person, err := people.Get(id) to get Jane Doe we just created
fmt.Println(person.(Person).Name) // John Doe (notice the type assertion -- this is because the Get function returns an interface{})

// You can also optionally query all of the IDs in a set.
ids := people.GetIds()

for _, id := range ids {
    p, _ := people.Get(id)
    // Do something wich each data set item
}

This would result in a folder structure like this:

storage
├── people
│   ├── john-doe.json
│   └── f48929fa-8a8a-4af5-9511-a1c0794f9681.json
└── cars

You’ll notice cars is empty, as we never created any data in that set.

As an example, the contents of storage/people/john-doe.json would be:

{
    "name": "John Doe",
    "age": 30
}

If we have Config_FSNotify set to true, we can modify this file on disk and have the changes reflected in our datasets automatically.

# In Bash
jq '.age = 20' ./storage/people/john-doe.json | tee ./storage/people/john-doe.json

// Back in our Go program
person, _ := people.Get("john-doe")
fmt.Println(person.(Person).Age) // 20

Available Configs

Why the name August?

At Sola Fide, we like for anything we make to echo our Christianity, as all the work we do is for Christ’s Kingdom.

In the case of August, it is named after Saint Augustine of Hippo.

Saint Augustine was a philosopher and theologian who lived from 354 to 430 AD. He is considered one of the most important figures in the development of Western Christianity and was a major figure in bringing Christianity to dominance in the previously pagan Roman Empire.

3.4 - GoBible

Go Bible

Gobible is a library for interacting with the Bible in Go.

Bible Formats

Initially, Gobible was created as an effort to support an easy to use JSON format for the Bible for use in other projects, but through development has grown to instead be a library for working with that format, as well and importing other formats into the Gobible format.

Supported Formats

• Gobible JSON Example
• OSIS XML Example

Please note that since Gobible works around a data structure defined by the Gobible JSON format, some features of other formats may not be supported.

Usage

Initialization

There are a few ways to initialize a bible:

// Initialize an empty GoBible object
b := NewGoBible()

// Load a GoBible formatted JSON file
b.Load("KJV.json")

// Load an alternate support format
b.LoadFormat("WEB.xml", "osis")

One you have a Bible object with some translations loaded into it, you can use this object in a few ways.

Interacting with Individual Translations

You can load an individual translation, and use it similarly to this:

// Load the KJV translation
kjv := bible.GetTranslation("KJV")

// get a verse
verse := kjv.GetBook("Genesis").GetChapter(1).GetVerse(1)

fmt.Println("Genesis 1:1 - " + verse.Text)
// Genesis 1:1 - In the beginning God created the heaven and the earth.

You can also use this to generate GoBible format JSON files from other formats:

b := NewGoBible()
// Load an OSIS XML file
b.LoadFormat("WEB.xml", "osis")

// Save the translation as GoBible JSON
goBibleJson := b.GetBibleJSON("WEB")

// Save the translation as GoBible JSON to a file
os.WriteFile("WEB.json", []byte(goBibleJson), 0644)

Interacting by Reference

Once you have 1 or multiple translations loaded, you can interact with them by reference notation.

(If you have multiple translations loaded, the first translation loaded will be used as the default)

// Examples of some valid references:
//   John 3:16
//   John 3:16-18
//   1 Cor 1:2-5
//   1 Cor 1:2-2:5 
// You can also tag the translation at the end of the reference
//   John 3:16 WEB 
//   John 3:16 KJV

// Lookup by reference
refs, _ := b.ParseReference("Gen 1:31-2:1")
for _, r := range refs {
    fmt.Printf("%s %d:%d %s", r.Book, r.Chapter, r.Verse, r.VerseRef.Text)
}
// Genesis 1:31 God saw everything that he had made, and, behold, it was very good. There was evening and there was morning, the sixth day.
// Genesis 2:1 The heavens and the earth were finished, and all the host of them.

Looking for Bibles?

We have published a few Public Domain bibles, as well as a Go program to generate additional ones in the gobible-gen repo.