Documentation
¶
Overview ¶
Package configutil contains helpers for configuration.
The intent of this package is to allow you to compose configuration types found throughout `sdk/` and elsewhere into a single configuration type for a given program.
An example configuration type might be:
type Config struct { DB db.Config `yaml:"db"` Logger logger.Config `yaml:"logger"` Web web.Config `yaml:"web"` }
On start, you may want to read from a yaml configuration file into this type, deserializing the configuration.
var cfg Config paths, err := configutil.Read(&cfg) // `err` is the first error returned from reading files // `paths` are the paths read from to populate the config
If we want to also read from the environment, we can do so by adding a resolver, and using the `configutil.Resolve`, `configutil.SetXYZ` helpers.
func (c *Config) Resolve(ctx context.Context) error { // NOTE: the pointer receiver is critical to modify the fields of the config return configutil.Resolve(ctx, (&c.DB).Resolve, // we use the (&foo) form here because we want to call the pointer receiver for `Resolve` (&c.Logger).Resolve, (&c.Web).Resolve, configutil.SetString(&c.Web.BindAddr, configutil.Env("BIND_ADDR"), configutil.String(c.Web.BindAddr)), ) }
In the above, the environment variable `BIND_ADDR` takes precedence over the string value found in any configuration file(s).
Note, we also "resolve" each of the attached configs first, in case they also have environment variables they read from etc.
Index ¶
- Constants
- Variables
- func GetConfigPaths(ctx context.Context) []string
- func IsConfigPathUnset(err error) bool
- func IsIgnored(err error) bool
- func IsInvalidConfigExtension(err error) bool
- func IsNotExist(err error) bool
- func MaybeDebugf(log Logger, format string, args ...interface{})
- func MaybeErrorf(log Logger, format string, args ...interface{})
- func MaybeInfof(log Logger, format string, args ...interface{})
- func MaybeWarningf(log Logger, format string, args ...interface{})
- func MustRead(ref Any, options ...Option) (filePaths []string)
- func Read(ref Any, options ...Option) (paths []string, err error)
- func Resolve(ctx context.Context, steps ...ResolveAction) (err error)
- func WithConfigPaths(ctx context.Context, paths []string) context.Context
- type Any
- type BoolFunc
- type BoolSource
- type BoolValue
- type ConfigContents
- type ConfigOptions
- type Duration
- type DurationFunc
- type DurationPtrSource
- type DurationSource
- type EnvVars
- func (e EnvVars) Bool(ctx context.Context) (*bool, error)
- func (e EnvVars) Duration(ctx context.Context) (*time.Duration, error)
- func (e EnvVars) Float64(ctx context.Context) (*float64, error)
- func (e EnvVars) Int(ctx context.Context) (*int, error)
- func (e EnvVars) Int32(ctx context.Context) (*int32, error)
- func (e EnvVars) Int64(ctx context.Context) (*int64, error)
- func (e EnvVars) String(ctx context.Context) (*string, error)
- func (e EnvVars) Strings(ctx context.Context) ([]string, error)
- type File
- type Float64
- type Float64Func
- type Float64PtrSource
- type Float64Source
- type Int
- type Int32
- type Int32PtrSource
- type Int32Source
- type Int64
- type Int64Func
- type Int64PtrSource
- type Int64Source
- type IntFunc
- type IntPtrSource
- type IntSource
- type Labels
- type Logger
- type Option
- func OptAddContent(ext string, content io.Reader) Option
- func OptAddContentString(ext string, contents string) Option
- func OptAddFilePaths(paths ...string) Option
- func OptAddPaths(paths ...string) Option
- func OptAddPreferredPaths(paths ...string) Option
- func OptContents(contents []ConfigContents) Option
- func OptContext(ctx context.Context) Option
- func OptEnv(vars env.Vars) Option
- func OptLog(log Logger) Option
- func OptPaths(paths ...string) Option
- func OptUnsetPaths() Option
- type Parser
- type ResolveAction
- func ResolveIf(branch bool, resolver ResolveAction) ResolveAction
- func ResolveIfFunc(branchFunc func(context.Context) bool, resolver ResolveAction) ResolveAction
- func SetBool(destination **bool, sources ...BoolSource) ResolveAction
- func SetDuration(destination *time.Duration, sources ...DurationSource) ResolveAction
- func SetDurationPtr(destination **time.Duration, sources ...DurationSource) ResolveAction
- func SetFloat64(destination *float64, sources ...Float64Source) ResolveAction
- func SetFloat64Ptr(destination **float64, sources ...Float64Source) ResolveAction
- func SetInt(destination *int, sources ...IntSource) ResolveAction
- func SetInt32(destination *int32, sources ...Int32Source) ResolveAction
- func SetInt32Ptr(destination **int32, sources ...Int32Source) ResolveAction
- func SetInt64(destination *int64, sources ...Int64Source) ResolveAction
- func SetInt64Ptr(destination **int64, sources ...Int64Source) ResolveAction
- func SetIntPtr(destination **int, sources ...IntSource) ResolveAction
- func SetString(destination *string, sources ...StringSource) ResolveAction
- func SetStringPtr(destination **string, sources ...StringSource) ResolveAction
- func SetStrings(destination *[]string, sources ...StringsSource) ResolveAction
- type Resolver
- type String
- type StringFunc
- type StringSource
- type Strings
- type StringsFunc
- type StringsSource
- type Vars
Constants ¶
const ( // EnvVarConfigPath is the env var for configs. EnvVarConfigPath = "CONFIG_PATH" // ExtensionJSON is a file extension. ExtensionJSON = ".json" // ExtensionYAML is a file extension. ExtensionYAML = ".yaml" // ExtensionYML is a file extension. ExtensionYML = ".yml" )
const ( // ErrConfigPathUnset is a common error. ErrConfigPathUnset = ex.Class("config path unset") // ErrInvalidConfigExtension is a common error. ErrInvalidConfigExtension = ex.Class("config extension invalid") )
Variables ¶
var ( // DefaultPaths are default path locations. // They are tested and read in order, so the later // paths will override data found in the earlier ones. DefaultPaths = []string{ "/var/secrets/config.yml", "/var/secrets/config.yaml", "/var/secrets/config.json", "./_config/config.yml", "./_config/config.yaml", "./_config/config.json", "./config.yml", "./config.yaml", "./config.json", } )
Functions ¶
func GetConfigPaths ¶ added in v1.20210103.1
GetConfigPaths gets the config file paths from a context..
func IsConfigPathUnset ¶
IsConfigPathUnset returns if an error is an ErrConfigPathUnset.
func IsInvalidConfigExtension ¶
IsInvalidConfigExtension returns if an error is an ErrInvalidConfigExtension.
func IsNotExist ¶
IsNotExist returns if an error is an os.ErrNotExist.
Read will never return a not found error, instead it will simply skip over that file, `IsNotExist` should be used in other situations like in resolvers.
func MaybeDebugf ¶ added in v1.20201204.1
MaybeDebugf writes a debug message if the logger is set.
func MaybeErrorf ¶ added in v1.20201204.1
MaybeErrorf writes an error message if the logger is set.
func MaybeInfof ¶ added in v1.20201204.1
MaybeInfof writes an info message if the logger is set.
func MaybeWarningf ¶ added in v1.20201204.1
MaybeWarningf writes a debug message if the logger is set.
func MustRead ¶ added in v1.20210103.1
MustRead reads a config from optional path(s) and panics on error.
It is functionally equivalent to `Read` outside error handling; see this function for more information.
func Read ¶
Read reads a config from optional path(s), returning the paths read from (in the order visited), and an error if there were any issues.
If the ref type is a `Resolver` the `Resolve(context.Context) error` method will be called on the ref and passed a context configured from the given options.
By default, a well known set of paths will be read from (including a path read from the environment variable `CONFIG_PATH`).
You can override this by providing options to specify which paths will be read from:
paths, err := configutil.Read(&cfg, configutil.OptPaths("foo.yml"))
The above will _only_ read from `foo.yml` to populate the `cfg` reference.
Types ¶
type BoolFunc ¶ added in v1.20201204.1
BoolFunc is a bool value source. It can be used with configutil.SetBool
type BoolSource ¶ added in v1.20201204.1
type BoolSource interface { // Bool should return a bool if the source has a given value. // It should return nil if the value is not found. // It should return an error if there was a problem fetching the value. Bool(context.Context) (*bool, error) }
BoolSource is a type that can return a value.
type BoolValue ¶ added in v1.20201204.1
type BoolValue bool
BoolValue implements value provider.
type ConfigContents ¶ added in v1.20210103.1
ConfigContents are literal contents to read from.
type ConfigOptions ¶ added in v1.20201204.1
type ConfigOptions struct { Log Logger Context context.Context Contents []ConfigContents FilePaths []string Env env.Vars }
ConfigOptions are options built for reading configs.
func (ConfigOptions) Background ¶ added in v1.20201204.1
func (co ConfigOptions) Background() context.Context
Background yields a context for a config options set.
type Duration ¶ added in v1.20201204.1
Duration implements value provider.
If the value is zero, a nil is returned by the implementation indicating the value was not present.
If you want 0 to be a valid value, you must use DurationPtr.
type DurationFunc ¶ added in v1.20201204.1
DurationFunc is a value source from a function.
type DurationPtrSource ¶ added in v1.20201204.1
DurationPtrSource is a DurationSource that wraps a duration pointer.
type DurationSource ¶ added in v1.20201204.1
type DurationSource interface { // Duration should return a time.Duration if the source has a given value. // It should return nil if the value is not present. // It should return an error if there was a problem fetching the value. Duration(context.Context) (*time.Duration, error) }
DurationSource is a type that can return a time.Duration value.
func DurationPtr ¶ added in v1.20201204.1
func DurationPtr(value *time.Duration) DurationSource
DurationPtr returns a DurationSource for a given duration pointer.
type EnvVars ¶ added in v1.20201204.1
type EnvVars struct {
Key string
}
EnvVars is a value provider where the string represents the environment variable name. It can be used with *any* config.Set___ type.
func (EnvVars) Duration ¶ added in v1.20201204.1
Duration returns a given environment variable as a time.Duration.
func (EnvVars) Float64 ¶ added in v1.20201204.1
Float64 returns a given environment variable as a float64.
func (EnvVars) Int32 ¶ added in v1.20201204.1
Int32 returns a given environment variable as an int32.
func (EnvVars) Int64 ¶ added in v1.20201204.1
Int64 returns a given environment variable as an int64.
type File ¶ added in v1.20201204.1
type File string
File reads the string contents of a file as a literal config value.
type Float64 ¶ added in v1.20201204.1
type Float64 float64
Float64 implements value provider.
Note: this will treat 0 as unset, if 0 is a valid value you must use configutil.FloatPtr.
type Float64Func ¶ added in v1.20201204.1
Float64Func is a float value source from a commandline flag.
type Float64PtrSource ¶ added in v1.20201204.1
type Float64PtrSource struct {
Value *float64
}
Float64PtrSource is a Float64Source that wraps a float64 pointer.
type Float64Source ¶ added in v1.20201204.1
type Float64Source interface { // Float should return a float64 if the source has a given value. // It should return nil if the value is not found. // It should return an error if there was a problem fetching the value. Float64(context.Context) (*float64, error) }
Float64Source is a type that can return a value.
func Float64Ptr ¶ added in v1.20201204.1
func Float64Ptr(value *float64) Float64Source
Float64Ptr returns an Float64Source for a given float64 pointer.
type Int ¶ added in v1.20201204.1
type Int int
Int implements value provider.
Note: Int treats 0 as unset, if 0 is a valid value you must use configutil.IntPtr.
type Int32 ¶ added in v1.20201204.1
type Int32 int32
Int32 implements value provider.
Note: Int32 treats 0 as unset, if 0 is a valid value you must use configutil.Int32Ptr.
type Int32PtrSource ¶ added in v1.20201204.1
type Int32PtrSource struct {
Value *int32
}
Int32PtrSource is a Int32Source that wraps an int32 pointer.
type Int32Source ¶ added in v1.20201204.1
type Int32Source interface { // Int32 should return an int32 if the source has a given value. // It should return nil if the value is not found. // It should return an error if there was a problem fetching the value. Int32(ctx context.Context) (*int32, error) }
Int32Source is a type that can return a value.
func Int32Ptr ¶ added in v1.20201204.1
func Int32Ptr(value *int32) Int32Source
Int32Ptr returns an Int32Source for a given int32 pointer.
type Int64 ¶ added in v1.20201204.1
type Int64 int64
Int64 implements value provider.
Note: Int64 treats 0 as unset, if 0 is a valid value you must use configutil.Int64Ptr.
type Int64PtrSource ¶ added in v1.20201204.1
type Int64PtrSource struct {
Value *int64
}
Int64PtrSource is a Int64Source that wraps an Int64 poInt64er.
type Int64Source ¶ added in v1.20201204.1
type Int64Source interface { // Int should return a int if the source has a given value. // It should return nil if the value is not found. // It should return an error if there was a problem fetching the value. Int64(ctx context.Context) (*int64, error) }
Int64Source is a type that can return a value.
func Int64Ptr ¶ added in v1.20201204.1
func Int64Ptr(value *int64) Int64Source
Int64Ptr returns an Int64Source for a given Int64 poInt64er.
type IntPtrSource ¶ added in v1.20201204.1
type IntPtrSource struct {
Value *int
}
IntPtrSource is a IntSource that wraps an int pointer.
type IntSource ¶ added in v1.20201204.1
type IntSource interface { // Int should return a int if the source has a given value. // It should return nil if the value is not found. // It should return an error if there was a problem fetching the value. Int(ctx context.Context) (*int, error) }
IntSource is a type that can return a value.
type Logger ¶ added in v1.20201204.1
type Logger interface { Infof(string, ...interface{}) Debugf(string, ...interface{}) Warningf(string, ...interface{}) Errorf(string, ...interface{}) }
Logger is a type that can satisfy the configutil logger interface.
type Option ¶ added in v1.20201204.1
type Option func(*ConfigOptions) error
Option is a modification of config options.
func OptAddContent ¶ added in v1.20210103.1
OptAddContent adds contents to the options as a reader.
func OptAddContentString ¶ added in v1.20210103.1
OptAddContentString adds contents to the options as a string.
func OptAddFilePaths ¶ added in v1.20201204.1
OptAddFilePaths is deprecated; use `OptAddPaths`
func OptAddPaths ¶ added in v1.20210103.1
OptAddPaths adds paths to search for the config file.
These paths will be added after the default paths.
func OptAddPreferredPaths ¶ added in v1.20210103.1
OptAddPreferredPaths adds paths to search first for the config file.
func OptContents ¶ added in v1.20201204.1
func OptContents(contents []ConfigContents) Option
OptContents sets config contents on the options.
func OptContext ¶ added in v1.20201204.1
OptContext sets the context on the options.
func OptEnv ¶ added in v1.20201204.1
OptEnv sets the config options environment variables. If unset, will default to the current global environment variables.
func OptUnsetPaths ¶ added in v1.20210103.1
func OptUnsetPaths() Option
OptUnsetPaths removes default paths from the paths set.
type Parser ¶ added in v1.20201204.1
type Parser struct {
Source StringSource
}
Parser parses an int.
func Parse ¶ added in v1.20201204.1
func Parse(source StringSource) Parser
Parse returns an int parser.
type ResolveAction ¶ added in v1.20201204.1
ResolveAction is a step in resolution.
func ResolveIf ¶ added in v1.20201204.1
func ResolveIf(branch bool, resolver ResolveAction) ResolveAction
ResolveIf wraps a resolver in a branch.
func ResolveIfFunc ¶ added in v1.20201204.1
func ResolveIfFunc(branchFunc func(context.Context) bool, resolver ResolveAction) ResolveAction
ResolveIfFunc wraps a resolver in a branch returned from a function.
func SetBool ¶ added in v1.20201204.1
func SetBool(destination **bool, sources ...BoolSource) ResolveAction
SetBool coalesces a given list of sources into a variable.
func SetDuration ¶ added in v1.20201204.1
func SetDuration(destination *time.Duration, sources ...DurationSource) ResolveAction
SetDuration coalesces a given list of sources into a variable.
func SetDurationPtr ¶ added in v1.20201204.1
func SetDurationPtr(destination **time.Duration, sources ...DurationSource) ResolveAction
SetDurationPtr coalesces a given list of sources into a variable.
func SetFloat64 ¶ added in v1.20201204.1
func SetFloat64(destination *float64, sources ...Float64Source) ResolveAction
SetFloat64 coalesces a given list of sources into a variable.
func SetFloat64Ptr ¶ added in v1.20201204.1
func SetFloat64Ptr(destination **float64, sources ...Float64Source) ResolveAction
SetFloat64Ptr coalesces a given list of sources into a variable.
func SetInt ¶ added in v1.20201204.1
func SetInt(destination *int, sources ...IntSource) ResolveAction
SetInt coalesces a given list of sources into a variable.
func SetInt32 ¶ added in v1.20201204.1
func SetInt32(destination *int32, sources ...Int32Source) ResolveAction
SetInt32 coalesces a given list of sources into a variable.
func SetInt32Ptr ¶ added in v1.20201204.1
func SetInt32Ptr(destination **int32, sources ...Int32Source) ResolveAction
SetInt32Ptr coalesces a given list of sources into a variable.
func SetInt64 ¶ added in v1.20201204.1
func SetInt64(destination *int64, sources ...Int64Source) ResolveAction
SetInt64 coalesces a given list of sources into a variable.
func SetInt64Ptr ¶ added in v1.20201204.1
func SetInt64Ptr(destination **int64, sources ...Int64Source) ResolveAction
SetInt64Ptr coalesces a given list of sources into a variable.
func SetIntPtr ¶ added in v1.20201204.1
func SetIntPtr(destination **int, sources ...IntSource) ResolveAction
SetIntPtr coalesces a given list of sources into a variable.
func SetString ¶ added in v1.20201204.1
func SetString(destination *string, sources ...StringSource) ResolveAction
SetString coalesces a given list of sources into a variable.
func SetStringPtr ¶ added in v1.20201204.1
func SetStringPtr(destination **string, sources ...StringSource) ResolveAction
SetStringPtr coalesces a given list of sources into a variable.
func SetStrings ¶ added in v1.20201204.1
func SetStrings(destination *[]string, sources ...StringsSource) ResolveAction
SetStrings coalesces a given list of sources into a variable.
type String ¶ added in v1.20201204.1
type String string
String implements value provider. An empty string is treated as unset, and will cause `String(context.Context) (*string, error)` to return nil for the string.
type StringFunc ¶ added in v1.20201204.1
StringFunc is a value source from a function.
type StringSource ¶ added in v1.20201204.1
type StringSource interface { // String should return a string if the source has a given value. // It should return nil if the value is not present. // It should return an error if there was a problem fetching the value. String(context.Context) (*string, error) }
StringSource is a type that can return a value.
func StringPtr ¶ added in v1.20201204.1
func StringPtr(value *string) StringSource
StringPtr returns a StringSource for a given string pointer.
type StringsFunc ¶ added in v1.20201204.1
StringsFunc is a value source from a function.
type StringsSource ¶ added in v1.20201204.1
type StringsSource interface { // Strings should return a string array if the source has a given value. // It should return nil if the value is not present. // It should return an error if there was a problem fetching the value. Strings(context.Context) ([]string, error) }
StringsSource is a type that can return a value.
Source Files
¶
- bool.go
- bool_func.go
- config_options.go
- constants.go
- context.go
- doc.go
- duration.go
- duration_func.go
- duration_ptr.go
- env.go
- errors.go
- file.go
- float64.go
- float64_func.go
- float64_ptr.go
- int.go
- int32_ptr_source.go
- int32_source.go
- int64.go
- int64_func.go
- int64_ptr.go
- int_func.go
- int_ptr.go
- logger.go
- option.go
- parse.go
- read.go
- resolve.go
- resolve_if.go
- resolver.go
- set.go
- string.go
- string_func.go
- string_ptr.go
- strings.go
- strings_func.go
- types.go
- value_source.go