package viper
Import Path
github.com/spf13/viper (on go.dev)
Dependency Relation
imports 29 packages, and imported by one package
Package-Level Type Names (total 21, in which 15 are exported)
ConfigFileAlreadyExistsError denotes failure to write new configuration file.
Error returns the formatted error when configuration already exists.
T : error
ConfigFileNotFoundError denotes failing to find configuration file.
locations string
name string
Error returns the formatted configuration error.
T : error
ConfigMarshalError happens when failing to marshal the configuration.
err error
Error returns the formatted configuration error.
T : error
ConfigParseError denotes failing to parse configuration file.
err error
Error returns the formatted configuration error.
T : error
A DecoderConfigOption can be passed to viper.Unmarshal to configure
mapstructure.DecoderConfig options
func DecodeHook(hook mapstructure.DecodeHookFunc) DecoderConfigOption
func Unmarshal(rawVal interface{}, opts ...DecoderConfigOption) error
func UnmarshalExact(rawVal interface{}, opts ...DecoderConfigOption) error
func UnmarshalKey(key string, rawVal interface{}, opts ...DecoderConfigOption) error
func (*Viper).Unmarshal(rawVal interface{}, opts ...DecoderConfigOption) error
func (*Viper).UnmarshalExact(rawVal interface{}, opts ...DecoderConfigOption) error
func (*Viper).UnmarshalKey(key string, rawVal interface{}, opts ...DecoderConfigOption) error
func defaultDecoderConfig(output interface{}, opts ...DecoderConfigOption) *mapstructure.DecoderConfig
FlagValue is an interface that users can implement
to bind different flags to viper.
( T) HasChanged() bool
( T) Name() string
( T) ValueString() string
( T) ValueType() string
pflagValue
func BindFlagValue(key string, flag FlagValue) error
func (*Viper).BindFlagValue(key string, flag FlagValue) error
func castMapFlagToMapInterface(src map[string]FlagValue) map[string]interface{}
FlagValueSet is an interface that users can implement
to bind a set of flags to viper.
( T) VisitAll(fn func(FlagValue))
pflagValueSet
func BindFlagValues(flags FlagValueSet) error
func (*Viper).BindFlagValues(flags FlagValueSet) (err error)
Option configures Viper using the functional options paradigm popularized by Rob Pike and Dave Cheney.
If you're unfamiliar with this style,
see https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html and
https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis.
( T) apply(v *Viper)
optionFunc
func EnvKeyReplacer(r StringReplacer) Option
func IniLoadOptions(in ini.LoadOptions) Option
func KeyDelimiter(d string) Option
func NewWithOptions(opts ...Option) *Viper
RemoteConfigError denotes encountering an error while trying to
pull the configuration from the remote provider.
Error returns the formatted remote provider error
T : error
RemoteProvider stores the configuration necessary
to connect to a remote key/value store.
Optional secretKeyring to unencrypt encrypted values
can be provided.
( T) Endpoint() string
( T) Path() string
( T) Provider() string
( T) SecretKeyring() string
defaultRemoteProvider
func (*Viper).getRemoteConfig(provider RemoteProvider) (map[string]interface{}, error)
func (*Viper).watchRemoteConfig(provider RemoteProvider) (map[string]interface{}, error)
StringReplacer applies a set of replacements to a string.
Replace returns a copy of s with all replacements performed.
*strings.Replacer
*strings.byteReplacer
*strings.byteStringReplacer
*strings.genericReplacer
strings.replacer (interface)
*strings.singleStringReplacer
func EnvKeyReplacer(r StringReplacer) Option
UnsupportedConfigError denotes encountering an unsupported
configuration filetype.
Error returns the formatted configuration error.
T : error
UnsupportedRemoteProviderError denotes encountering an unsupported remote
provider. Currently only etcd and Consul are supported.
Error returns the formatted remote provider error.
T : error
Viper is a prioritized configuration registry. It
maintains a set of configuration sources, fetches
values to populate those, and provides them according
to the source's priority.
The priority of the sources is the following:
1. overrides
2. flags
3. env. variables
4. config file
5. key/value store
6. defaults
For example, if values from the following sources were loaded:
Defaults : {
"secret": "",
"user": "default",
"endpoint": "https://localhost"
}
Config : {
"user": "root"
"secret": "defaultsecret"
}
Env : {
"secret": "somesecretkey"
}
The resulting config will have the following values:
{
"secret": "somesecretkey",
"user": "root",
"endpoint": "https://localhost"
}
Note: Vipers are not safe for concurrent Get() and Set() operations.
aliases map[string]string
allowEmptyEnv bool
automaticEnvApplied bool
config map[string]interface{}
configFile string
Name of file to look for inside the path
A set of paths to look for the config file in
configPermissions os.FileMode
configType string
defaults map[string]interface{}
env map[string][]string
envKeyReplacer StringReplacer
envPrefix string
The filesystem to read config from.
Specific commands for ini parsing
Delimiter that separates a list of keys
used to access a nested value in one go
kvstore map[string]interface{}
onConfigChange func(fsnotify.Event)
override map[string]interface{}
pflags map[string]FlagValue
Store read properties on the object so that we can write back in order with comments.
This will only be used if the configuration read is a properties file.
A set of remote providers to search for the configuration
typeByDefValue bool
(*T) AddConfigPath(in string)
(*T) AddRemoteProvider(provider, endpoint, path string) error
(*T) AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error
(*T) AllKeys() []string
(*T) AllSettings() map[string]interface{}
(*T) AllowEmptyEnv(allowEmptyEnv bool)
(*T) AutomaticEnv()
(*T) BindEnv(input ...string) error
(*T) BindFlagValue(key string, flag FlagValue) error
(*T) BindFlagValues(flags FlagValueSet) (err error)
(*T) BindPFlag(key string, flag *pflag.Flag) error
(*T) BindPFlags(flags *pflag.FlagSet) error
(*T) ConfigFileUsed() string
(*T) Debug()
(*T) Get(key string) interface{}
(*T) GetBool(key string) bool
(*T) GetDuration(key string) time.Duration
(*T) GetFloat64(key string) float64
(*T) GetInt(key string) int
(*T) GetInt32(key string) int32
(*T) GetInt64(key string) int64
(*T) GetIntSlice(key string) []int
(*T) GetSizeInBytes(key string) uint
(*T) GetString(key string) string
(*T) GetStringMap(key string) map[string]interface{}
(*T) GetStringMapString(key string) map[string]string
(*T) GetStringMapStringSlice(key string) map[string][]string
(*T) GetStringSlice(key string) []string
(*T) GetTime(key string) time.Time
(*T) GetUint(key string) uint
(*T) GetUint32(key string) uint32
(*T) GetUint64(key string) uint64
(*T) InConfig(key string) bool
(*T) IsSet(key string) bool
(*T) MergeConfig(in io.Reader) error
(*T) MergeConfigMap(cfg map[string]interface{}) error
(*T) MergeInConfig() error
(*T) OnConfigChange(run func(in fsnotify.Event))
(*T) ReadConfig(in io.Reader) error
(*T) ReadInConfig() error
(*T) ReadRemoteConfig() error
(*T) RegisterAlias(alias string, key string)
(*T) SafeWriteConfig() error
(*T) SafeWriteConfigAs(filename string) error
(*T) Set(key string, value interface{})
(*T) SetConfigFile(in string)
(*T) SetConfigName(in string)
(*T) SetConfigPermissions(perm os.FileMode)
(*T) SetConfigType(in string)
(*T) SetDefault(key string, value interface{})
(*T) SetEnvKeyReplacer(r *strings.Replacer)
(*T) SetEnvPrefix(in string)
(*T) SetFs(fs afero.Fs)
(*T) SetTypeByDefaultValue(enable bool)
(*T) Sub(key string) *Viper
(*T) Unmarshal(rawVal interface{}, opts ...DecoderConfigOption) error
(*T) UnmarshalExact(rawVal interface{}, opts ...DecoderConfigOption) error
(*T) UnmarshalKey(key string, rawVal interface{}, opts ...DecoderConfigOption) error
(*T) WatchConfig()
(*T) WatchRemoteConfig() error
(*T) WatchRemoteConfigOnChannel() error
(*T) WriteConfig() error
(*T) WriteConfigAs(filename string) error
Given a key, find the value.
Viper will check to see if an alias exists first.
Viper will then check in the following order:
flag, env, config file, key/value store.
Lastly, if no value was found and flagDefault is true, and if the key
corresponds to a flag, the flag's default value is returned.
Note: this assumes a lower-cased key given.
Search all configPaths for any config file.
Returns the first path that exists (and is a config file).
flattenAndMergeMap recursively flattens the given map into a map[string]bool
of key paths (used as a set, easier to manipulate than a []string):
- each path is merged into a single key string, delimited with v.keyDelim
- if a path is shadowed by an earlier value in the initial shadow map,
it is skipped.
The resulting set of paths is merged to the given shadow set at the same time.
(*T) getConfigFile() (string, error)
(*T) getConfigType() string
getEnv is a wrapper around os.Getenv which replaces characters in the original
key. This allows env vars which have different keys than the config object
keys.
Retrieve the first found remote configuration.
(*T) getRemoteConfig(provider RemoteProvider) (map[string]interface{}, error)
isPathShadowedInAutoEnv makes sure the given path is not shadowed somewhere
in the environment, when automatic env is on.
e.g., if "foo.bar" has a value in the environment, it “shadows”
"foo.bar.baz" in a lower-priority map
isPathShadowedInDeepMap makes sure the given path is not shadowed somewhere
on its path in the map.
e.g., if "foo.bar" has a value in the given map, it “shadows”
"foo.bar.baz" in a lower-priority map
isPathShadowedInFlatMap makes sure the given path is not shadowed somewhere
in a sub-path of the map.
e.g., if "foo.bar" has a value in the given map, it “shadows”
"foo.bar.baz" in a lower-priority map
Marshal a map into Writer.
mergeFlatMap merges the given maps, excluding values of the second map
shadowed by values from the first map.
(*T) mergeWithEnvPrefix(in string) string
(*T) providerPathExists(p *defaultRemoteProvider) bool
(*T) realKey(key string) string
(*T) registerAlias(alias string, key string)
(*T) searchInPath(in string) (filename string)
searchIndexableWithPathPrefixes recursively searches for a value for path in source map/slice.
While searchMap() considers each path element as a single map key or slice index, this
function searches for, and prioritizes, merged path elements.
e.g., if in the source, "foo" is defined with a sub-key "bar", and "foo.bar"
is also defined, this latter value is returned for path ["foo", "bar"].
This should be useful only at config level (other maps may not contain dots
in their keys).
Note: This assumes that the path entries and map keys are lower cased.
searchMap recursively searches for a value for path in source map.
Returns nil if not found.
Note: This assumes that the path entries and map keys are lower cased.
searchMapWithPathPrefixes searches for a value for path in sourceMap
This function is part of the searchIndexableWithPathPrefixes recurring search and
should not be called directly from functions other than searchIndexableWithPathPrefixes.
searchSliceWithPathPrefixes searches for a value for path in sourceSlice
This function is part of the searchIndexableWithPathPrefixes recurring search and
should not be called directly from functions other than searchIndexableWithPathPrefixes.
(*T) unmarshalReader(in io.Reader, c map[string]interface{}) error
Retrieve the first found remote configuration.
Retrieve the first found remote configuration.
(*T) watchRemoteConfig(provider RemoteProvider) (map[string]interface{}, error)
(*T) writeConfig(filename string, force bool) error
func GetViper() *Viper
func New() *Viper
func NewWithOptions(opts ...Option) *Viper
func Sub(key string) *Viper
func (*Viper).Sub(key string) *Viper
var v *Viper
Package-Level Functions (total 93, in which 70 are exported)
AddConfigPath adds a path for Viper to search for the config file in.
Can be called multiple times to define multiple search paths.
AddRemoteProvider adds a remote configuration source.
Remote Providers are searched in the order they are added.
provider is a string value: "etcd", "consul" or "firestore" are currently supported.
endpoint is the url. etcd requires http://ip:port consul requires ip:port
path is the path in the k/v store to retrieve configuration
To retrieve a config file called myapp.json from /configs/myapp.json
you should set path to /configs and set config name (SetConfigName()) to
"myapp"
AddSecureRemoteProvider adds a remote configuration source.
Secure Remote Providers are searched in the order they are added.
provider is a string value: "etcd", "consul" or "firestore" are currently supported.
endpoint is the url. etcd requires http://ip:port consul requires ip:port
secretkeyring is the filepath to your openpgp secret keyring. e.g. /etc/secrets/myring.gpg
path is the path in the k/v store to retrieve configuration
To retrieve a config file called myapp.json from /configs/myapp.json
you should set path to /configs and set config name (SetConfigName()) to
"myapp"
Secure Remote Providers are implemented with github.com/bketelsen/crypt
AllKeys returns all keys holding a value, regardless of where they are set.
Nested keys are returned with a v.keyDelim separator
AllowEmptyEnv tells Viper to consider set,
but empty environment variables as valid values instead of falling back.
For backward compatibility reasons this is false by default.
AllSettings merges all settings and returns them as a map[string]interface{}.
AutomaticEnv makes Viper check if environment variables match any of the existing keys
(config, default or flags). If matching env vars are found, they are loaded into Viper.
BindEnv binds a Viper key to a ENV variable.
ENV variables are case sensitive.
If only a key is provided, it will use the env key matching the key, uppercased.
If more arguments are provided, they will represent the env variable names that
should bind to this key and will be taken in the specified order.
EnvPrefix will be used when set when env name is not provided.
BindFlagValue binds a specific key to a FlagValue.
BindFlagValues binds a full FlagValue set to the configuration, using each flag's long
name as the config key.
BindPFlag binds a specific key to a pflag (as used by cobra).
Example (where serverCmd is a Cobra instance):
serverCmd.Flags().Int("port", 1138, "Port to run Application server on")
Viper.BindPFlag("port", serverCmd.Flags().Lookup("port"))
BindPFlags binds a full flag set to the configuration, using each flag's long
name as the config key.
ConfigFileUsed returns the file used to populate the config registry.
Debug prints all configuration registries for debugging
purposes.
DecodeHook returns a DecoderConfigOption which overrides the default
DecoderConfig.DecodeHook value, the default is:
mapstructure.ComposeDecodeHookFunc(
mapstructure.StringToTimeDurationHookFunc(),
mapstructure.StringToSliceHookFunc(","),
)
EnvKeyReplacer sets a replacer used for mapping environment variables to internal keys.
Get can retrieve any value given the key to use.
Get is case-insensitive for a key.
Get has the behavior of returning the value associated with the first
place from where it is set. Viper will check in the following order:
override, flag, env, config file, key/value store, default
Get returns an interface. For a specific value use one of the Get____ methods.
GetBool returns the value associated with the key as a boolean.
GetDuration returns the value associated with the key as a duration.
GetFloat64 returns the value associated with the key as a float64.
GetInt returns the value associated with the key as an integer.
GetInt32 returns the value associated with the key as an integer.
GetInt64 returns the value associated with the key as an integer.
GetIntSlice returns the value associated with the key as a slice of int values.
GetSizeInBytes returns the size of the value associated with the given key
in bytes.
GetString returns the value associated with the key as a string.
GetStringMap returns the value associated with the key as a map of interfaces.
GetStringMapString returns the value associated with the key as a map of strings.
GetStringMapStringSlice returns the value associated with the key as a map to a slice of strings.
GetStringSlice returns the value associated with the key as a slice of strings.
GetTime returns the value associated with the key as time.
GetUint returns the value associated with the key as an unsigned integer.
GetUint32 returns the value associated with the key as an unsigned integer.
GetUint64 returns the value associated with the key as an unsigned integer.
GetViper gets the global Viper instance.
InConfig checks to see if the given key (or an alias) is in the config file.
IniLoadOptions sets the load options for ini parsing.
IsSet checks to see if the key has been set in any of the data locations.
IsSet is case-insensitive for a key.
KeyDelimiter sets the delimiter used for determining key parts.
By default it's value is ".".
MergeConfig merges a new configuration with an existing config.
MergeConfigMap merges the configuration from the map given with an existing config.
Note that the map given may be modified.
MergeInConfig merges a new configuration with an existing config.
New returns an initialized Viper instance.
NewWithOptions creates a new Viper instance.
func OnConfigChange(run func(in fsnotify.Event))
ReadConfig will read a configuration file, setting existing keys to nil if the
key does not exist in the file.
ReadInConfig will discover and load the configuration file from disk
and key/value stores, searching in one of the defined paths.
ReadRemoteConfig attempts to get configuration from a remote source
and read it in the remote configuration registry.
RegisterAlias creates an alias that provides another accessor for the same key.
This enables one to change a name without breaking the application.
Reset is intended for testing, will reset all to default settings.
In the public interface for the viper package so applications
can use it in their testing as well.
SafeWriteConfig writes current configuration to file only if the file does not exist.
SafeWriteConfigAs writes current configuration to a given filename if it does not exist.
Set sets the value for the key in the override register.
Set is case-insensitive for a key.
Will be used instead of values obtained via
flags, config file, ENV, default, or key/value store.
SetConfigFile explicitly defines the path, name and extension of the config file.
Viper will use this and not check any of the config paths.
SetConfigName sets name for the config file.
Does not include extension.
SetConfigPermissions sets the permissions for the config file.
SetConfigType sets the type of the configuration returned by the
remote source, e.g. "json".
SetDefault sets the default value for this key.
SetDefault is case-insensitive for a key.
Default only used when no value is provided by the user via flag, config or ENV.
SetEnvKeyReplacer sets the strings.Replacer on the viper object
Useful for mapping an environmental variable to a key that does
not match it.
SetEnvPrefix defines a prefix that ENVIRONMENT variables will use.
E.g. if your prefix is "spf", the env registry will look for env
variables that start with "SPF_".
SetFs sets the filesystem to use to read configuration.
SetTypeByDefaultValue enables or disables the inference of a key value's
type when the Get function is used based upon a key's default value as
opposed to the value returned based on the normal fetch logic.
For example, if a key has a default value of []string{} and the same key
is set via an environment variable to "a b c", a call to the Get function
would return a string slice for the key if the key's type is inferred by
the default value and the Get function would return:
[]string {"a", "b", "c"}
Otherwise the Get function would return:
"a b c"
Sub returns new Viper instance representing a sub tree of this instance.
Sub is case-insensitive for a key.
Unmarshal unmarshals the config into a Struct. Make sure that the tags
on the fields of the structure are properly set.
UnmarshalExact unmarshals the config into a Struct, erroring if a field is nonexistent
in the destination struct.
UnmarshalKey takes a single key and unmarshals it into a Struct.
func WatchConfig() func WatchRemoteConfig() error
WriteConfig writes the current configuration to a file.
WriteConfigAs writes current configuration to a given filename.
Package-Level Variables (total 4, in which 3 are exported)
RemoteConfig is optional, see the remote package
SupportedExts are universally supported extensions.
SupportedRemoteProviders are universally supported remote providers.
 |
The pages are generated with Golds v0.3.2. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds. |