This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Libraries

Open Source Libraries developed for SimpleWorship, with the hope they will be useful to others.

1:
2:
3: August
4: GoBible

Libraries

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

Config	Description	Default	Acceptable Values
Config_Format	The format to use for the data store files.	`json`	`json`, `yaml`, `xml`
Config_StorageDir	The directory to store the data store files in.	`./storage`	Any valid directory path
Config_FSNotify	Whether or not to use fsnotify to watch for changes to the data store files, and update the data store when they are modified	`true`	`true`, `false`
Config_Verbose	Whether or not to log verbose output (consider calling `*August.Verbose()` after init instead)	`false`	`true`, `false`

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.

augustine-of-hippo

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 - August

A local json file data storage library with file monitoring

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

Config	Description	Default	Acceptable Values
Config_Format	The format to use for the data store files.	`json`	`json`, `yaml`, `xml`
Config_StorageDir	The directory to store the data store files in.	`./storage`	Any valid directory path
Config_FSNotify	Whether or not to use fsnotify to watch for changes to the data store files, and update the data store when they are modified	`true`	`true`, `false`
Config_Verbose	Whether or not to log verbose output (consider calling `*August.Verbose()` after init instead)	`false`	`true`, `false`

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.

augustine-of-hippo

4 - GoBible

A library and JSON file format for storing Bible data

Go Bible

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

Bible Formats

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.