config

Overview ¶

Package config provides types that allow loading, storing, retrieving, and removing arbitrary values that are referenced by keys.

The Config Type ¶

We can create instances of Config with New(). The zero valued &Config{} is not in a valid state and will likely cause panics if used. The New() func automatically sets Config's KeyParser to PeriodSeparatorKeyParser. This means that all string key parameters to Config methods will be converted to Key types in the manner of "a.b.c.d" -> Key([]string{"a", "b", "c", "d"}). A Config's KeyParser field can be changed before use to override this functionality.

Inserting values into a Config is simple and type agnostic. The Put*() methods all return whether or not the internal set of values changed.

c := New()
c.Put("foo", "bar") //true
c.Put("foo", "bar") //false
c.Put("foo", 1024)  //true

We can additionally use the Loader type to insert multiple values at once and from varying sources instead of calling individual Put*() methods.

type sliceLoader []interface{}

func (sl sliceLoader) Load() (*Values, error) {
	values := NewValues()
	for i, v := range sl {
		key := NewKey("slice", fmt.Sprint(i))
		values.Put(key, v)
	}
	return values, nil
}

loader := sliceLoader([]interface{}{"hello", "world", 234, true})
c := New()
c.MergeLoaders(loader) //true, nil

c.Get("slice.0") //hello
c.Get("slice.1") //world
c.Get("slice.2") //234
c.Get("slice.3") //true

See the Loader documentation and the loader subdirectory for information about pre-written loaders for common use cases.

The Values and Key Types ¶

Type Values provides the actaul storage and retrieval of interface{} values. The values stored in a Values type are referenced by the Key type. Values is implemented as a tree with possible multiple children at each node. Each individual string in a Key is the "pointer" to the subtree of possibly more values.

For example:

//the following code...

v := NewValues()
v.Put(NewKey("a", "b"), 1)
v.Put(NewKey("a", "c"), 2)
v.Put(NewKey("d"), 3)

//results in this structure.
//       __root__
//       |      |
//       a      d
//       |      |
//    b--+--c   3
//    |     |
//    1     2

Continuing from this example, if we were to call v.Put(NewKey("a"), true), that would completely remove the [a b] -> 1 and [a c] -> 2 associations from v.

If we were to call v.Put(NewKey("a", "e"), "foobar"), that would result in the [a b] and [a c] associations remaining and the new [a e] -> "foobar" within v.