gofig

README

Gofig

Gofig simplifies external, runtime configuration of go programs.

Documentation

Overview

Package gofig simplifies external, runtime configuration of go programs.

Index

• Constants
• Variables
• func Register(r ConfigRegistration)
• func SetGlobalConfigPath(path string)
• func SetUserConfigPath(path string)
• func ValidateYAML(r io.Reader) (map[interface{}]interface{}, error)
• func ValidateYAMLString(s string) (map[interface{}]interface{}, error)
• type Config
  • func FromJSON(from string) (Config, error)
  • func New() Config
  • func NewConfig(loadGlobalConfig, loadUserConfig bool, configName, configType string) Config
• type ConfigRegistration
  • func NewRegistration(name string) ConfigRegistration
• type ConfigRegistrationKey

Constants

const (
	// String is a key with a string value
	String = iota // 0

	// Int is a key with an integer value
	Int // 1

	// Bool is a key with a boolean value
	Bool // 2

	// SecureString is a key with a string value that is not included when the
	// configuration is marshaled to JSON.
	SecureString // 3
)

Variables

var (
	// LogGetAndSet determines whether or not gettting and seetting values
	// is logged.
	LogGetAndSet, _ = strconv.ParseBool(os.Getenv("GOFIG_LOG_GETSET"))

	// LogSecureKey determines whether or not secure key attempts are logged.
	LogSecureKey, _ = strconv.ParseBool(os.Getenv("GOFIG_LOG_SECUREKEY"))

	// LogFlattenEnvVars determines whether or not flattening environment
	// variables is logged.
	LogFlattenEnvVars, _ = strconv.ParseBool(os.Getenv("GOFIG_LOG_FLATTEN"))

	// LogRegKey determines whether or not key registrations are logged.
	LogRegKey, _ = strconv.ParseBool(os.Getenv("GOFIG_LOG_REGKEY"))

	// DisableEnvVarSubstitution determines whether or not Gofig will replace
	// environment variables with their actual values. This transformation is
	// applied only to the values returned by the GetString and GetStringSlice
	// functions. Environment variable substitution is not applied to config
	// keys for example.
	//
	// New Config instances inherit this value at the time of the instance
	// creation. However, this value has no effect on existing config instances.
	// Those instances have a function named DisableEnvVarSubstitution that is
	// able to disable/enable the feature for that instance.
	DisableEnvVarSubstitution, _ = strconv.ParseBool(
		os.Getenv("GOFIG_DISABLE_ENVVAR_SUBSTITUTION"))
)

Functions

func Register

func Register(r ConfigRegistration)

Register registers a new configuration with the config package.

func SetGlobalConfigPath

func SetGlobalConfigPath(path string)

SetGlobalConfigPath sets the path of the directory from which the global configuration file is read.

func SetUserConfigPath

func SetUserConfigPath(path string)

SetUserConfigPath sets the path of the directory from which the user configuration file is read.

func ValidateYAML

func ValidateYAML(r io.Reader) (map[interface{}]interface{}, error)

ValidateYAML verifies the YAML in the stream is valid.

func ValidateYAMLString

func ValidateYAMLString(s string) (map[interface{}]interface{}, error)

ValidateYAMLString verifies the YAML string valid.

Types

type Config

type Config interface {

	// DisableEnvVarSubstitution is the same as the global flag,
	// DisableEnvVarSubstitution.
	DisableEnvVarSubstitution(disable bool)

	// Parent gets the configuration's parent (if set).
	Parent() Config

	// Scope returns a scoped view of the configuration. The specified scope
	// string will be used to prefix all property retrievals via the Get
	// and Set functions. Please note that the other functions will still
	// operate as they would for the non-scoped configuration instance. This
	// includes the AllSettings and AllKeys functions as well; they are *not*
	// scoped.
	Scope(scope interface{}) Config

	// GetScope returns the config's current scope (if any).
	GetScope() string

	// GetString returns the value associated with the key as a string
	GetString(k interface{}) string

	// GetBool returns the value associated with the key as a bool
	GetBool(k interface{}) bool

	// GetStringSlice returns the value associated with the key as a string
	// slice.
	GetStringSlice(k interface{}) []string

	// GetInt returns the value associated with the key as an int
	GetInt(k interface{}) int

	// Get returns the value associated with the key
	Get(k interface{}) interface{}

	// Set sets an override value
	Set(k interface{}, v interface{})

	// IsSet returns a flag indicating whether or not a key is set.
	IsSet(k interface{}) bool

	// Copy creates a copy of this Config instance
	Copy() (Config, error)

	// ToJSON exports this Config instance to a JSON string
	ToJSON() (string, error)

	// ToJSONCompact exports this Config instance to a compact JSON string
	ToJSONCompact() (string, error)

	// MarshalJSON implements the encoding/json.Marshaller interface. It allows
	// this type to provide its own marshalling routine.
	MarshalJSON() ([]byte, error)

	// ReadConfig reads a configuration stream into the current config instance
	ReadConfig(in io.Reader) error

	// ReadConfigFile reads a configuration files into the current config
	// instance
	ReadConfigFile(filePath string) error

	// EnvVars returns an array of the initialized configuration keys as
	// key=value strings where the key is configuration key's environment
	// variable key and the value is the current value for that key.
	EnvVars() []string

	// AllKeys gets a list of all the keys present in this configuration.
	AllKeys() []string

	// AllSettings gets a map of this configuration's settings.
	AllSettings() map[string]interface{}
}

Config is the interface that enables retrieving configuration information. The variations of the Get function, the Set, IsSet, and Scope functions all take an interface{} as their first parameter. However, the param must be either a string or a fmt.Stringer, otherwise the function will panic.

func FromJSON

func FromJSON(from string) (Config, error)

FromJSON initializes a new Config instance from a JSON string

func New

func New() Config

New initializes a new instance of a Config struct

func NewConfig

func NewConfig(
	loadGlobalConfig, loadUserConfig bool,
	configName, configType string) Config

NewConfig initialies a new instance of a Config object with the specified options.

type ConfigRegistration

type ConfigRegistration interface {

	// Name returns the name of the config registration.
	Name() string

	// YAML returns the registration's default yaml configuration.
	YAML() string

	// SetYAML sets the registration's default yaml configuration.
	SetYAML(y string)

	// Key adds a key to the registration.
	//
	// The first vararg argument is the yaml name of the key, using a '.' as
	// the nested separator. If the second two arguments are omitted they will
	// be generated from the first argument. The second argument is the explicit
	// name of the flag bound to this key. The third argument is the explicit
	// name of the environment variable bound to thie key.
	Key(
		keyType int,
		short string,
		defVal interface{},
		description string,
		keys ...interface{})

	// Keys returns a channel on which a listener can receive the config
	// registration's keys.
	Keys() <-chan ConfigRegistrationKey
}

ConfigRegistration is an interface that describes a configuration registration object.

func NewRegistration

func NewRegistration(name string) ConfigRegistration

NewRegistration creates a new registration with the given name.

type ConfigRegistrationKey

type ConfigRegistrationKey interface {
	KeyType() int
	DefaultValue() interface{}
	Short() string
	Description() string
	KeyName() string
	FlagName() string
	EnvVarName() string
}

ConfigRegistrationKey is an interfact that describes a cofniguration registration key object.