config

Documentation

Overview

Package config is a flexible configuration framework.

This package defines a common interface for generic interaction with any structured configuration data. Configuration is organized by named sections that themselves contain values or other sections.

In addition, this package defines a mutable configuration definition API for defining options, sections, and validation for options and sections.

Underlying data for each section is stored in a map[string]interface{} or a struct with its exported fields being used as options. The underlying data is kept in sync when mutating with Config.Set() using reflection.

Use config.New or config.Wrap to create a root section and specify whatever options desired.

type Config struct {
    Name string
    Bio  *struct {
        Age int
    }
}
co := &Config{"veonik", &struct{Age int}{30}}
c, err := config.Wrap(co,
    config.WithRequiredOption("Name"),
    config.WithGenericSection("Bio", config.WithRequiredOption("Age")))
if err != nil {
    panic(err)
}
fmt.Printf("Hi, %s!\n", co.Name)
n, _ := c.String("Name")
b, _ := c.Section("Bio")
a, _ := b.Int("Age")
fmt.Printf("%s is %d.\n", n, a)
// Outputs:
// Hi, veonik!
// veonik is 30.

Index

• func ConfigurePlugin(m *plugin.Manager, opts ...SetupOption) error
• func Initialize(m *plugin.Manager) (plugin.Plugin, error)
• func ValidateRequired(o string, v Value) error
• type Config
  • func New(options ...SetupOption) (Config, error)
  • func Wrap(wrapped Value, options ...SetupOption) (Config, error)
• type Section
• type Setup
• type SetupOption
  • func WithFilteredOption(name string, fn func(string, Value) (Value, error)) SetupOption
  • func WithGenericSection(name string, options ...SetupOption) SetupOption
  • func WithInheritedOption(name string) SetupOption
  • func WithInheritedSection(name string) SetupOption
  • func WithInitPrototype(proto func() Value) SetupOption
  • func WithInitValue(value Value) SetupOption
  • func WithOption(name string) SetupOption
  • func WithOptions(names ...string) SetupOption
  • func WithRequiredOption(name string) SetupOption
  • func WithRequiredOptions(names ...string) SetupOption
  • func WithSection(sec Section, options ...SetupOption) SetupOption
  • func WithSingleton(singleton bool) SetupOption
  • func WithValidatedOption(name string, fn func(string, Value) error) SetupOption
  • func WithValuesFromFlagSet(fs *flag.FlagSet) SetupOption
  • func WithValuesFromMap(vs *map[string]interface{}) SetupOption
  • func WithValuesFromTOMLFile(filename string) SetupOption
• type Value

Functions

func ConfigurePlugin

func ConfigurePlugin(m *plugin.Manager, opts ...SetupOption) error

ConfigurePlugin applies the given options to the registered config plugin.

func Initialize

func Initialize(m *plugin.Manager) (plugin.Plugin, error)

Initialize is a plugin.Initializer that initializes a config plugin.

func ValidateRequired

func ValidateRequired(o string, v Value) error

ValidateRequired is a validator that ensures an option is not blank. Any nil value or string with length of zero is considered blank.

Types

type Config

type Config interface {
	// Self returns the Value stored for the Config itself.
	// This will be a map[string]interface{} unless otherwise set with an
	// initial value or prototype func.
	Self() Value
	// Get returns the Value stored with the given key.
	// The second return parameter will be false if the given key is unset.
	Get(key string) (Value, bool)
	// String returns the string stored with the given key.
	// The second return parameter will be false if the given key is unset
	// or not a string.
	String(key string) (string, bool)
	// Bool returns the bool stored with the given key.
	// The second return parameter will be false if the given key is unset
	// or not a bool.
	Bool(key string) (bool, bool)
	// Int returns the int stored with the given key.
	// The second return parameter will be false if the given key is unset
	// or not an int.
	Int(key string) (int, bool)
	// Set sets the given key to the given Value.
	Set(key string, val Value)

	// Section returns the nested configuration for the given key.
	// If the section does not exist, an error will be returned.
	Section(key string) (Config, error)
}

A Config represents a single, configured section. Configs are collections of Values each with one or more keys referencing each Value stored. Configs may be nested within other Configs by using sections.

func New

func New(options ...SetupOption) (Config, error)

New creates and populates a new Config using the given options.

func Wrap

func Wrap(wrapped Value, options ...SetupOption) (Config, error)

Wrap creates and populates a new Config using the given Value as the stored representation of the configuration.

type Section

type Section interface {
	// Name is used as the name of the section.
	Name() string
	// Prototype returns the zero value for the section.
	Prototype() Value
	// Singleton is true if the section may only exist once.
	Singleton() bool
}

A Section describes the pre-configured state of a nested configuration section.

type Setup

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

Setup is a container struct with information on how to setup a given Config.

type SetupOption

type SetupOption func(c *Setup) error

A SetupOption is a function that modifies the given Setup in some way.

func WithFilteredOption

func WithFilteredOption(name string, fn func(string, Value) (Value, error)) SetupOption

WithFilteredOption adds a filter that may modify the option's value. Filters are applied after

func WithGenericSection

func WithGenericSection(name string, options ...SetupOption) SetupOption

WithGenericSection will add a basic section with the given name and options.

func WithInheritedOption

func WithInheritedOption(name string) SetupOption

WithInheritedOption will inherit an option from the parent Config.

func WithInheritedSection

func WithInheritedSection(name string) SetupOption

WithInheritedSection will inherit a section from the parent Config. Alias for WithInheritedOption.

func WithInitPrototype

func WithInitPrototype(proto func() Value) SetupOption

WithInitPrototype sets the given func as the prototype. The prototype func will be invoked and its return value will be used to populate the initial value in the Config.

func WithInitValue

func WithInitValue(value Value) SetupOption

WithInitValue uses the given Value as the starting point for the section. Initial values are updated via reflection and kept in sync with changes made to the Config.

func WithOption

func WithOption(name string) SetupOption

WithOption adds an optional option to the Config.

func WithOptions

func WithOptions(names ...string) SetupOption

WithOptions adds multiple optional options to the Config.

func WithRequiredOption

func WithRequiredOption(name string) SetupOption

WithRequiredOption adds a required option to the Config.

func WithRequiredOptions

func WithRequiredOptions(names ...string) SetupOption

WithRequiredOptions adds multiple required options to the Config.

func WithSection

func WithSection(sec Section, options ...SetupOption) SetupOption

WithSection will add a Section with the given options.

func WithSingleton

func WithSingleton(singleton bool) SetupOption

WithSingleton will enable or disable a section's singleton property.

func WithValidatedOption

func WithValidatedOption(name string, fn func(string, Value) error) SetupOption

WithValidatedOption adds a value validator for the given option. Validator functions accept the name of the option and its value, and return an error if the value is not considered valid.

func WithValuesFromFlagSet

func WithValuesFromFlagSet(fs *flag.FlagSet) SetupOption

WithValuesFromFlagSet populates the Config using command-line flags.

func WithValuesFromMap

func WithValuesFromMap(vs *map[string]interface{}) SetupOption

WithValuesFromMap populates the Config using the given map.

func WithValuesFromTOMLFile

func WithValuesFromTOMLFile(filename string) SetupOption

WithValuesFromTOMLFile will populate the Config with values parsed from a TOML file.

type Value

type Value interface{}

A Value is some value stored in a configuration.