config

README

config package

The config package wraps the common viper methods and types but adds some custom processing.

This probably could be done using custom decode hooks for viper, but I have not had time to understand them in detail.

Using a wrapper also allows custom methods on config for further functionality.

Unless the file format is given to LoadConfig then all the viper formats are supported.

Expansion of values

The following package functions and type methods are overridden to add expansion of embedded strings of the form ${name} and $name:

• GetString
• GetStringSlice
• GetStringMapString

The string values are passed to ExpandString which supports a range of data substitutions.

Documentation

Index

• func GetString(s string, confmap ...map[string]string) string
• func GetStringMapString(s string, confmap ...map[string]string) map[string]string
• func GetStringSlice(s string, confmap ...map[string]string) []string
• type Config
  • func GetConfig() *Config
  • func LoadConfig(configName string, options ...Options) (c *Config, err error)
  • func New() *Config
  • func (c *Config) ExpandString(input string, confmap map[string]string) (value string)
  • func (c *Config) GetString(s string, confmap ...map[string]string) string
  • func (c *Config) GetStringMapString(s string, confmap ...map[string]string) (m map[string]string)
  • func (c *Config) GetStringSlice(s string, confmap ...map[string]string) (slice []string)
• type Options
  • func AddConfigDirs(paths ...string) Options
  • func IgnoreSystemDir() Options
  • func IgnoreUserConfDir() Options
  • func IgnoreWorkingDir() Options
  • func SetAppName(name string) Options
  • func SetConfigFile(path string) Options
  • func SetDefaults(defaults []byte, format string) Options
  • func UseGlobal() Options

Functions

func GetString

func GetString(s string, confmap ...map[string]string) string

Returns the configuration item as a string with ExpandString() applied, passing the first "confmap" if given

func GetStringMapString

func GetStringMapString(s string, confmap ...map[string]string) map[string]string

func GetStringSlice

func GetStringSlice(s string, confmap ...map[string]string) []string

Types

type Config

type Config struct {
	*viper.Viper
	Type string
}

Config embeds Viper and also exposes the config type used

func GetConfig

func GetConfig() *Config

func LoadConfig

func LoadConfig(configName string, options ...Options) (c *Config, err error)

LoadConfig loads configuration files from internal defaults, external defaults and the given configuration file. The configuration file can be passed as an option. Each layer is only loaded once, if given. Internal defaults are passed as a []byte intended to be loaded from an embedded file. External defaults and the main configuration file are passed as ordered slices of strings. The first match is loaded.

LoadConfig("geneos")

//go:embed somefile.json
var myDefaults []byte
LoadConfig("geneos", config.SetDefaults(myDefaults, "json"), )

Options can be passed to change the default behaviour and to pass any embedded defaults or an existing viper.

for defaults see: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html ... find windows equiv

func New

func New() *Config

func (*Config) ExpandString

func (c *Config) ExpandString(input string, confmap map[string]string) (value string)

ExpandString() returns input with any occurrences of the form ${name} or $name substituted using os.Expand for the supported formats in the order given below:

• '${path.to.config}' Any name containing one or more dots '.' will be looked up in the running configuration (which can include existing settings outside of any configuration file being read by the caller)
• '${name}' 'name' will be substituted with the corresponding value from the map 'confmap'. If 'confmap' is empty (as opposed to the key 'name' not being found) then name is looked up as an environment variable
• '${env:name}' 'name' will be substituted with the contents of the environment variable of the same name.
• '${file://path/to/file}' or '${file:~/path/to/file}' The contents of the referenced file will be read. Multiline files are used as-is so this can, for example, be used to read PEM certificate files or keys. As an enhancement to a conventional file url, if the first '/' is replaced with a tilde '~' then the path is relative to the home directory of the user running the process.
• '${https://host/path}' or '${http://host/path}' The contents of the URL are fetched and used similarly as for local files above. The URL is passed to http.Get and supports any embedded Basic Authentication and other features from that function.

The form $name is also supported, as per os.Expand but may be ambiguous and is not recommended.

Expansion is not recursive. Configuration values are read and stored as literals and are expanded each time they are used. For each substitution any leading and trailing whitespace are removed. External sources are fetched each time they are used and so there may be a performance impact as well as the value unexpectedly changing during a process lifetime.

Any errors (particularly from substitutions from external files or remote URLs) may result in an empty or corrupt string being returned. Error returns are intentionally discarded.

It is not currently possible to escape the syntax supported by os.Expand and if it is necessary to have a configuration value be of the form '${name}' or '$name' then set an otherwise unused item to the value and refer to it using the dotted syntax, e.g. for YAML

config:
  real: ${config.temp}
  temp: "${unchanged}"

In the above a reference to ${config.real} will return the literal string ${unchanged}

func (*Config) GetString

func (c *Config) GetString(s string, confmap ...map[string]string) string

Returns the configuration item as a string with ExpandString() applied, passing the first "confmap" if given

func (*Config) GetStringMapString

func (c *Config) GetStringMapString(s string, confmap ...map[string]string) (m map[string]string)

func (*Config) GetStringSlice

func (c *Config) GetStringSlice(s string, confmap ...map[string]string) (slice []string)

type Options

type Options func(*configOptions)

func AddConfigDirs

func AddConfigDirs(paths ...string) Options

AddConfigDirs() adds one or more directories to search for the configuration and defaults files. Directories are searched in FIFO order, so any directories given are checked before the built-in list.

func IgnoreSystemDir

func IgnoreSystemDir() Options

IgnoreSystemDir() tells LoadConfig() not to search in the system configuration directory. This only applies on UNIX-like systems and is normally /etc/[appName]

func IgnoreUserConfDir

func IgnoreUserConfDir() Options

IgnoreUserConfDir() tells LoadConfig() not to search in the user config directory (OS defined as per Go os.UserConfDir())

func IgnoreWorkingDir

func IgnoreWorkingDir() Options

IgnoreWorkingDir() tells LoadConfig not to search the working directory for configuration files. This should be used when the caller may be running in an unknown location.

func SetAppName

func SetAppName(name string) Options

SetAppName() overrides to mapping of the configName to the application name. Application name is used for the containing directories, while configName is used for the files in those directories.

func SetConfigFile

func SetConfigFile(path string) Options

SetConfigFile() allows the caller to override the searching for a config file in the given directories and instead loads only the given file (after defaults are loaded as normal).

func SetDefaults

func SetDefaults(defaults []byte, format string) Options

SetDefaults() takes a []byte slice and a format type to load embedded defaults

func UseGlobal

func UseGlobal() Options

UseGlobal() uses the global config instead of creating a new instance.