configuration

Documentation

Overview

Package configuration provides a mechanism to load configuration from JSON or YAML files. The typical use will be to create a configuration object and then load one or more configuration sources:

// Load the configuration from a file:
cfg, err := configuration.New().
	Load("myconfig.yaml").
	Build()
if err != nil {
	...
}

Once the configuration is loaded it can be copied into an object containing the same tags used by the YAML library:

// Copy the configuration into our object:
type MyConfig struct {
	MyKey string `yaml:"mykey"`
	YouKey int `yaml:"yourkey"`
}
var myCfg MyConfig
err = cfg.Populate(&myCfg)
if err != nil {
	...
}

The advantage of using this configuration instead of using plain YAML is that configuration sources can use the tags to reference environment variables, files and scripts. For example:

mykey: !variable MYVARIABLE
yourkey: !file /my/file.txt

The following tags are supported:

!file /my/file.txt - Is replaced by the content of the file `/my/file.txt`.
!script myscript - Is replaced by the result of executing the `myscript` script.
!trim mytext - Is replaced by the result of trimming white space from `mytext`.
!variable MYVARIABLE - Is replaced by the content of the environment variable `MYVARIABLE`.
!yaml mytext - Is replaced by the result of parsing `mytext` as YAML.

Tag names can be abbreviated. For example these are all valid tags:

!f /my/file.txt - Replaced by the content of the `/my.file.txt` file.
!s myscript - Replaced by the result of execution the `myscript` script.
!v MYVARIABLE - Replaced by the content of the environment variablel `MYVARIABLE`.

By default the tags replace the value of node they are applied to with a string. This will not work for fields that are declared of other types in the configuration struct. In those cases it is possible to add a suffix to the tag to indicate the type of the replacmenet. For example:

# A configuration with an integer loaded from an environment variable and a boolean
# loaded from a file:
myid: !variable/integer MYID
myenabled: !file/boolean /my/enabled.txt

This can be used with the following Go code:

type MyConfig struct {
	MyId      int  `yaml:"myid"`
	MyEnabled bool `yaml:"myenabled"`
}
var myCfg MyConfig
err = cfg.Populate(&myCfg)
if err != nil {
	...
}

Tags can be chained. For example to read a value from a file and trim white space from the content:

mypassword: !file/trim mypassword.txt

When multiple sources are configured (calling the Load method multiple times) they will all be merged, and sources loaded later sources will override sources loaded earlier.

Index

• type Builder
  • func New() *Builder
  • func (b *Builder) Build() (object *Object, err error)
  • func (b *Builder) Load(sources ...interface{}) *Builder
• type Object
  • func (o *Object) Effective() (out []byte, err error)
  • func (o *Object) MarshalYAML() (result interface{}, err error)
  • func (o *Object) Populate(v interface{}) error
  • func (o *Object) UnmarshalYAML(value *yaml.Node) error

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder contains the data and logic needed to populate a configuration object. Don't create instances of this type directly, use the New function instead.

func New

func New() *Builder

New creates a new builder that can be use to populate a configuration object.

func (*Builder) Build

func (b *Builder) Build() (object *Object, err error)

Build uses the information stored in the builder to create and populate a configuration object.

func (*Builder) Load

func (b *Builder) Load(sources ...interface{}) *Builder

Load adds the given objects as sources where the configuration will be loaded from.

If a source is a string ending in `.yaml` or `.yml` it will be interpreted as the name of a file containing the YAML text.

If a source is a string ending in `.d` it will be interpreted as a directory containing YAML files. The `.yaml` or `.yml` files inside that directory will be loaded in alphabetical order.

Any string not ending in `.yaml`, `.yml` or `.d` will be interprested as actual YAML text. In order to simplify embedding these strings in Go programs leading tabs will be removed from all the lines of that YAML text.

If a source is an array of bytes it will be interpreted as actual YAML text.

If a source implements the io.Reader interface, then it will be used to read in memory the YAML text.

If the source can also be a yaml.Node or another configuration Object. In those cases the content of the source will be copied.

If the source is any other kind of object then it will be serialized as YAML and then loaded.

type Object

type Object struct {
	// contains filtered or unexported fields
}

Object contains configuration data.

func (*Object) Effective

func (o *Object) Effective() (out []byte, err error)

Effective returns an array of bytes containing the YAML representation of the configuration after processing all the tags.

func (*Object) MarshalYAML

func (o *Object) MarshalYAML() (result interface{}, err error)

MarshalYAML is the implementation of the yaml.Marshaller interface. This is intended to be able use the type for fields inside other structs. Refrain from calling this method for any other use.

func (*Object) Populate

func (o *Object) Populate(v interface{}) error

Populate populates the given destination object with the information stored in this configuration object. The destination object should be a pointer to a variable containing the same tags used by the yaml.Unmarshal method of the YAML library.

func (*Object) UnmarshalYAML

func (o *Object) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML is the implementation of the yaml.Unmarshaller interface. This is intended to be able to use the type for fields inside structs. Refraim from calling this method for any other use.