etc

Documentation

Overview

The Tideland Go Library etc configuration package provides the reading, parsing, and accessing of configuration data. Different readers can be passed as sources for the SML formatted input.

{etc
    {global
        {base-directory /var/lib/myserver}
        {host-address localhost:1234}
        {max-users 50}
    }
    {service-a
        {url http://[global/host-address]/service-a}
        {directory [global/base-directory||.]/service-a}
    }
}

After reading this from a file, reader, or string the number of users can be retrieved with a default value of 10 by calling

maxUsers := cfg.ValueAsInt("global/max-users", 10)

The leading "etc" node of the path is set by default.

If values contain templates formatted [path||default] the configuration tries to read the value out of the given path and replace the template. The default value is optional. It will be used, if the path cannot be found. If the path is invalid and has no default the template will stay inside the value. So accessing the directory of service-a by

svcDir := cfg.ValueAsString("service-a/directory", ".")

leads to "/var/lib/myserver/service-a" and if the base directory isn't set to "./service-a". If nothing is set the default value is ".".

Index

• Constants
• func IsInvalidPathError(err error) bool
• func NewContext(ctx context.Context, cfg Etc) context.Context
• func Version() version.Version
• type Application
• type Etc
  • func FromContext(ctx context.Context) (Etc, bool)
  • func Read(source io.Reader) (Etc, error)
  • func ReadFile(filename string) (Etc, error)
  • func ReadString(source string) (Etc, error)

Constants

const (
	ErrIllegalSourceFormat = iota + 1
	ErrIllegalConfigSource
	ErrCannotReadFile
	ErrCannotPostProcess
	ErrInvalidPath
	ErrCannotSplit
	ErrCannotApply
)

Functions

func IsInvalidPathError

func IsInvalidPathError(err error) bool

IsInvalidPathError checks if a path cannot be found.

func NewContext

func NewContext(ctx context.Context, cfg Etc) context.Context

NewContext returns a new context that carries a configuration.

func Version

func Version() version.Version

Version returns the version of the SML package.

Types

type Application

type Application map[string]string

Application is used to apply values to a configurtation.

type Etc

type Etc interface {
	fmt.Stringer

	// HasPath checks if the configurations has the defined path
	// regardles of the value or possible subconfigurations.
	HasPath(path string) bool

	// ValueAsString retrieves the string value at a given path. If it
	// doesn't exist the default value dv is returned.
	ValueAsString(path, dv string) string

	// ValueAsBool retrieves the bool value at a given path. If it
	// doesn't exist the default value dv is returned.
	ValueAsBool(path string, dv bool) bool

	// ValueAsInt retrieves the int value at a given path. If it
	// doesn't exist the default value dv is returned.
	ValueAsInt(path string, dv int) int

	// ValueAsFloat64 retrieves the float64 value at a given path. If it
	// doesn't exist the default value dv is returned.
	ValueAsFloat64(path string, dv float64) float64

	// ValueAsTime retrieves the string value at a given path and
	// interprets it as time with the passed format. If it
	// doesn't exist the default value dv is returned.
	ValueAsTime(path, layout string, dv time.Time) time.Time

	// ValueAsDuration retrieves the duration value at a given path.
	// If it doesn't exist the default value dv is returned.
	ValueAsDuration(path string, dv time.Duration) time.Duration

	// Spit produces a subconfiguration below the passed path.
	// The last path part will be the new root, all values below
	// that configuration node will be below the created root.
	Split(path string) (Etc, error)

	// Dunp creates a map of paths and their values to apply
	// them into other configurations.
	Dump() (Application, error)

	// Apply creates a new configuration by adding of overwriting
	// the passed values. The keys of the map have to be slash
	// separated configuration paths without the leading "etc".
	Apply(appl Application) (Etc, error)
}

Etc contains the read etc configuration and provides access to it. ThetcRoot node "etc" is automatically preceded to the path. The node name have to consist out of 'a' to 'z', '0' to '9', and '-'. The nodes of a path are separated by '/'.

func FromContext

func FromContext(ctx context.Context) (Etc, bool)

FromContext returns the configuration stored in ctx, if any.

func Read

func Read(source io.Reader) (Etc, error)

Read reads the SML source of the configuration from a reader, parses it, and returns the etc instance.

func ReadFile

func ReadFile(filename string) (Etc, error)

ReadFile reads the SML source of a configuration file, parses it, and returns the etc instance.

func ReadString

func ReadString(source string) (Etc, error)

ReadString reads the SML source of the configuration from a string, parses it, and returns the etc instance.