Documentation ¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Enumerator ¶
Enumerator is a Value from an enumerable short set of distinct values. Its main use is for the equivalent of an enum of strings.
type Env ¶
type Env struct {
// contains filtered or unexported fields
}
Env is a configuration environment grouped by a common variable prefix.
func Environment ¶
func (Env) WithParameters ¶
func (e Env) WithParameters(name string) Parameters
WithParameters creates a group of managed parameters.
type Parameter ¶
type Parameter struct { // Key identifies the parameter. // It is unique per Parameter managed by a FlagManager. Key string `json:"key"` // Type is the type of the parameter. Type reflect.Type `json:"type"` // EnvKey is the name of the environment variable configuring this parameter. EnvKey string `json:"env"` // The ArgKey is the name of the command line argument configuring this parameter. ArgKey string `json:"arg"` // ArgAliases are alternatives for ArgKey. ArgAliases []string `json:"argalt"` // Value is the current value in string form. Value string `json:"value"` // DefaultValue is the default value in string form. DefaultValue string `json:"default"` // Options contains all values the parameter can take. // If the value is not an Enumerator, it is empty. Options []ParameterValue `json:"options"` // Tag is an optional tag for this parameter. // It can be used to only show important parameters in short help texts. Tag string `json:"tag"` Description string `json:"desc"` }
Parameter describes a configurable part of the application.
type ParameterValue ¶
ParameterValue describes one possible value a Parameter can take.
type Parameters ¶
type Parameters interface { // Register registers struct fields as configuration parameters. // // It must be called with a non-nil struct pointer and panics otherwise. // The current values of each field are used as default values. Register(vars Vars) // Keys retrieves a slice of parameter keys for all managed parameters. Keys() []string // ArgKey retrieves the command line argument used to configure the parameter // identified by the given key. ArgKey(key string) string // ArgAliases retrives a slice of alternative command line arguments also useable // to configure the parameter identified by the given key. ArgAliases(key string) []string // EnvKey retrieves the name of the environment variable used to configure the // parameter identified by the given key. EnvKey(key string) string // SetValues calls a function for every managed parameter with its EnvKey. // It sets the parameter to the value returned by the function if the call to // Set on the Value does not return an error. // // To set the default values from environment variables, the argument should be // os.Getenv SetValues(func(string) string) error // Parse parses parameter definitions from the argument list, which should not // include the command name. // // Must be called after all parameters are registered and before they are accessed // by the program. Parse(args []string) error // ArgRest retrieves all unparsed parameters. ArgRest() []string // Explore retrieves a slice of all managed parameters with additional information. // Use Explore as the central source to generate documentation. Explore() []Parameter }
Parameters manages struct fields as configuration parameters and enables their configuration from different sources, e.g. command line arguments and environment variables.
Each parameter is represented by a key. The key name is provided with a struct tag or matches the field name.
A parameter may be modified by command line arguments (ARG) or an environment variable (ENV). The key is used to derive the primary ARG and the ENV:
ARG and ENV can only contain English letters, digits and a separator (ENV: '_', ARG: '-'). All other characters in the key are replaced with separators. Upper case letters are downcased and prefixed with a separator. ENV is prefixed with the Environment prefix. Multiple adjacent separators are reduced to one. Leading separators are removed, ARG may be used prefixed with one or two separators. ENV is upcased.
Examples for Environment prefix "myapp":
Key ARG ENV -------|----------|-------------- MyKey my-key MYAPP_MY_KEY Val val MYAPP_VAL Über ber MYAPPBER
Usage:
# -ARG myapp -my-key=Value # --ARG myapp --my-key=Value2 # ENV export MYAPP_VAL=value myapp
type Value ¶
Value is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)
type Vars ¶
type Vars any
Vars is a pointer to a struct containing configuration variables. Struct tags can be used to configure the behavior of parameters, all tags are optional.
type Config struct { a string `key:"override the key, otherwise it is the field name"` b string `args:"comma separated alternative command line arg representations"` c string `desc:"a description of what the parameter does"` d string `tag:"a tag useable for filtering, e.g. when generating documentation"` }
In addition to the tag based configuration, the field name and type are used and the current value on registration is used as the default value.