cfg

Documentation

Overview

Package cfg provides a simple mechanism for creating and loading configuration files.

The configuration files are saved using the TOML file format.

Modules need not worry about dealing with configuration files. They simply need to implement the Configurable interface.

Index

• Constants
• Variables
• func Migrate(set Set, filename string, versionKey string, migrations []MigrateHandler, ...) error
• type ConfigSaveOpts
• type ConfigSet
  • func (cs ConfigSet) Save(filename string, perms os.FileMode, opts ConfigSaveOpts) error
• type Configurable
• type MigrateHandler
• type Migrator
• type Set
  • func NewSet(configurables []Configurable) Set
  • func (s Set) Configs() ConfigSet
  • func (s Set) Get(key string) (interface{}, error)
  • func (s Set) Load(filename string) error
  • func (s Set) Save(filename string, perms os.FileMode, opts ConfigSaveOpts) error
  • func (s Set) Set(key string, value string) error
  • func (s Set) Tree() (*Tree, error)
• type Tree
  • func TreeFromMap(m map[string]interface{}) (*Tree, error)
  • func (t *Tree) AddGroup(id, name, desc string) error
  • func (t *Tree) AddServiceToGroup(service, group string) error
  • func (t *Tree) Get(key string) interface{}
  • func (t *Tree) GetDefault(key string, def interface{}) interface{}
  • func (t *Tree) Set(key string, val interface{}) (err error)

Constants

const (
	// ConfZeroPID is the default PeerID set before any migration happens.
	// The real peerID will be generated to replace this one.
	ConfZeroPID = "QmRK6DGwgkzpHRG5rCgWUxTSKvQtmhZeMa5jdeHYTtxnNq"

	// ConfZeroPK is the default private key set before any migration happens.
	// The real private key will be generated to replace this one.
	ConfZeroPK = "" /* 1596-byte string literal not displayed */
)

Variables

var (

	// ErrUnexistingKey is the error returned when trying to get/set an unknown key.
	ErrUnexistingKey = errors.New("setting not found")

	// ErrEditGroupConfig is the error returned when trying to set
	// group of configuration attributes.
	ErrEditGroupConfig = errors.New("cannot edit a group of attribute")
)

var (
	// ErrInvalidVersion is returned when the config version is invalid.
	ErrInvalidVersion = errors.New("config version is invalid")

	// ErrInvalidSubtree is returned when a config subtree is invalid.
	ErrInvalidSubtree = errors.New("subtree is invalid")

	// ErrOutdatedExec is returned when the config version is more recent
	// than the executable.
	ErrOutdatedExec = errors.New("exec is out of date with config version")
)

var (
	// ErrInvalidGroup is returned when a configuration file contains
	// an invalid service group.
	ErrInvalidGroup = errors.New("the service group is invalid")
)

Functions

func Migrate

func Migrate(
	set Set,
	filename string,
	versionKey string,
	migrations []MigrateHandler,
	perms os.FileMode,
) error

Migrate loads a TOML file and sets the configurations of a set of configurables, applying migrations if needed.

The version key should point to the tree path that contains the int config file version for global migrations.

The migrations should be a slice of MigrateHandler that upgrade the configuration from the version corresponding to its index in the slice to the next version.

Each configurable can have its own migrations if it implements the Migrator interface.

Types

type ConfigSaveOpts

type ConfigSaveOpts struct {
	Overwrite bool
	Backup    bool
}

ConfigSaveOpts are the options passed to ConfigSet.Save().

type ConfigSet

type ConfigSet map[string]interface{}

ConfigSet represents a set of configurations.

func (ConfigSet) Save

func (cs ConfigSet) Save(filename string, perms os.FileMode, opts ConfigSaveOpts) error

Save saves a set of configurations to a file. It will return an error if the file already exists unless overwrite is true.

type Configurable

type Configurable interface {
	// ID returns the unique identifier of the configurable.
	ID() string

	// Config should return the current configuration or a default
	// configuration if it wasn't set.
	Config() interface{}

	// SetConfig should configure the configurable.
	SetConfig(interface{}) error
}

Configurable represents something that can be configured.

type MigrateHandler

type MigrateHandler func(*Tree) error

MigrateHandler mutates a TOML tree to update it from one version to the next.

type Migrator

type Migrator interface {
	// Version key returns the key containing the current int version relative
	// to the subtree of the configurable.
	VersionKey() string

	// Migrations returns all the migrations from first to last. Keys are
	// relative to the subtree of the configurable.
	Migrations() []MigrateHandler
}

Migrator declares migrations specific to a configurable.

type Set

type Set map[string]Configurable

Set represents a set of configurables.

func NewSet

func NewSet(configurables []Configurable) Set

NewSet returns a new set of configurables.

func (Set) Configs

func (s Set) Configs() ConfigSet

Configs returns the current configurations of a set of configurables.

func (Set) Get

func (s Set) Get(key string) (interface{}, error)

Get returns the value of the tree indexed by the provided key. The key is a dot-separated path (e.g. a.b.c) without single/double quoted strings.

func (Set) Load

func (s Set) Load(filename string) error

Load loads a TOML file and sets the configurations of a set of configurables.

func (Set) Save

func (s Set) Save(filename string, perms os.FileMode, opts ConfigSaveOpts) error

Save saves the configurations of a set of configurables to a TOML file.

func (Set) Set

func (s Set) Set(key string, value string) error

Set edits the value of the tree indexed by the provided key. The value must be convertible to the right type for this setting (int, bool, str or slice). It fails if the key does not exist.

func (Set) Tree

func (s Set) Tree() (*Tree, error)

Tree returns a toml tree filled with the configuration set's data.

type Tree

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

Tree is used to modify the configuration tree.

func TreeFromMap

func TreeFromMap(m map[string]interface{}) (*Tree, error)

TreeFromMap creates a tree from a map.

func (*Tree) AddGroup

func (t *Tree) AddGroup(id, name, desc string) error

AddGroup adds a group if it doesn't exist yet.

func (*Tree) AddServiceToGroup

func (t *Tree) AddServiceToGroup(service, group string) error

AddServiceToGroup adds a service to an existing group if it isn't already part of the group.

If the group is not found, it prints a warning and doesn't return an error. The user could have intentionally removed the group.

func (*Tree) Get

func (t *Tree) Get(key string) interface{}

Get returns the value of a key.

The key can be a path such as "core.boot_service".

func (*Tree) GetDefault

func (t *Tree) GetDefault(key string, def interface{}) interface{}

GetDefault returns the value of a key or a default value.

The key can be a path such as "core.boot_service".

func (*Tree) Set

func (t *Tree) Set(key string, val interface{}) (err error)

Set sets the value of a key.

The key can be a path such as "core.boot_service".