Package Usage: go: go.uber.org/config
Package config is an encoding-agnostic configuration abstraction. It
supports merging multiple configuration files, expanding environment
variables, and a variety of other small niceties. It currently supports
YAML, but may be extended in the future to support more restrictive
encodings like JSON or TOML.
It's often convenient to separate configuration into multiple files; for
example, an application may want to first load some universally-applicable
configuration and then merge in some environment-specific overrides. This
package supports this pattern in a variety of ways, all of which use the
same merge logic.
Simple types (numbers, strings, dates, and anything else YAML would
consider a scalar) are merged by replacing lower-priority values with
higher-priority overrides. For example, consider this merge of base.yaml
and override.yaml:
Slices, arrays, and anything else YAML would consider a sequence are also
replaced. Again merging base.yaml and override.yaml:
Maps are recursively deep-merged, handling scalars and sequences as
described above. Consider a merge between a more complex set of YAML files:
In all cases, explicit nils (represented in YAML with a tilde) override any
pre-existing configuration. For example,
By default, the NewYAML constructor enables gopkg.in/yaml.v2's strict
unmarshalling mode. This prevents a variety of common programmer errors,
especially when deep-merging loosely-typed YAML files. In strict mode,
providers throw errors if keys are duplicated in the same configuration
source, all keys aren't used when populating a struct, or a merge
encounters incompatible data types. This behavior can be disabled with the
Permissive option.
To maintain backward compatibility, all other constructors default to
permissive unmarshalling.
YAML allows strings to appear quoted or unquoted, so these two lines are
identical:
However, the YAML specification special-cases some unquoted strings. Most
obviously, true and false are interpreted as Booleans (unless quoted). Less
obviously, yes, no, on, off, and many variants of these words are also
treated as Booleans (see http://yaml.org/type/bool.html for the complete
specification).
Correctly deep-merging sources requires this package to unmarshal and then
remarshal all YAML, which implicitly converts these special-cased unquoted
strings to their canonical representation. For example,
Quoting special-cased strings prevents this surprising behavior.
Unfortunately, this package was released with a variety of bugs and an
overly large API. The internals of the configuration provider have been
completely reworked and all known bugs have been addressed, but many
duplicative exported functions were retained to preserve backward
compatibility. New users should rely on the NewYAML constructor. In
particular, avoid NewValue - it's unnecessary, complex, and may panic.
Deprecated functions are documented in the format expected by the
staticcheck linter, available at https://staticcheck.io/.
12 versions
Latest release: over 5 years ago
145 dependent packages
View more package details: https://packages.ecosystem.code.gouv.fr/registries/proxy.golang.org/packages/go.uber.org/config