github.com/richshaffer/go-config
A Configuration Package for Go
go-config provides a convenient way to scan configuration settings from command line flags and environment variables into structs. Its aim is to provide logical organization of configuration parameters with minimal developer overhead.
It also provides for basic validation of configuration values by using struct tags, and parsing of single values.
type Auth struct {
User string
Password string
}
type Options struct {
Auth *Auth
URLs []*url.URL `scheme:"^(http|https)$"`
Verbose int `min:"0" max:"8"`
}
opts := Options{Verbose: 1}
if err := config.Configure(&opts); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
if opts.Auth != nil {
fmt.Printf("Auth: %+v\n", *opts.Auth)
}
fmt.Printf("URLs: %s\nVerbose: %d\n", opts.URLs, opts.Verbose)
Running the program with -h demonstrates the generated command-line flags and environment variable settings:
Command Line Flags:
-auth-password string
-auth-user string
-urls url
-verbose int
(default 1)
Environment Variables:
AUTH_PASSWORD=string
AUTH_USER=string
URLS=url
VERBOSE=int
(default 1)
Help requested
Running the program with supported flags demonstrates how values are set:
prog -urls http://www.google.com/ -urls http://www.yahoo.com/ -auth-user user1
Auth: {User:user1 Password:}
URLs: [http://www.google.com/ http://www.yahoo.com/]
Verbose: 1
To set a default value, simply set the value in the struct before calling
Configure. Struct tags can be used to specify permitted values. See the
Validation section for details.
The following types are supported:
Types that are pointer and/or slice types of a supported type are also supported. For example, []int, *int, *[]*int, or any other combination of slice and pointer indirection can be set.
int, int8, int16, int32, and int64, uint, uint8, uint16, uint32 and uint64 types are parsed as base 10, unless they have a leading zero or 0x, in which case they are parsed as, respectively, base 8 or base 16 values. Values which would overflow the type or discard a sign are considered invalid. For example, assigning a value larger than 255 to int8, or assigning a negative value to a uint.
float32 and float64 types are parsed using strconv.ParseFloat using the correct size (bits).
bool values are parsed using strconv.ParseBool. 1, t, T, TRUE, true,
and True are parsed as true. 0, f, F, FALSE, false, and False
evaluate to false. Any other value is an error.
url.URL values are parsed using url.Parse.
net.IP values are are parsed with net.ParseIP and accept, e.g., 192.168.1.1 or 2600:1700:5fa0:ef90:85e:79dc:5ea7:c711. net.IPNet values are parsed with net.ParseCIDR as address/bits, such as 169.254.0.0/16 or 2001:cdba:9abc:5678::/64. A value provided as a network address need not necessarily specify the 0 network address: 169.254.1.1/16 will be understood as 169.254.0.0/16.
time.Duration values are parsed using time.ParseDuration, e.g., 0.75s or 1h37m27s.
A best effort is made to parse a time based on a static list of layouts:
If the time can not be parsed using any of the given layouts, it is an error.
go-config attempts to generate human-friendly names by parsing the names of struct fields in a hierarchical way. For example, given
type UserAccount struct {
Network struct {
IPv6FriendlyName string
}
}
go-config will generate the command line flag -user-account-network-ip-v6-friendly-name. See the section Overriding Names for details on how to change this behavior.
Note than for types in the below section, the validations also apply to other types that are pointer and/or slice types of the base type. For example, if a validation applies to int, it also applies to []int, *int, *[]*int, or any other combination of slice and pointer indirection.
Number types int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64 as well as time.Duration and time.Time support a number of struct tags for validation.
ge and min have the same meaning, and indicate a value must be greater than or equal to the argument. le and max similarly indicate a value must be less than or equal to a given value. Tags lt and gt indicate a strict less than or greater than comparison (not equal to).
All arguments to the above tags should be given in a valid string for the type. For example, 1s for a duration, 2001-01-01 11:59:59Z for a time, etc. The special value now may be used for time.Time values.
The above tags can be combined to require values within a range.
Examples:
type Example struct {
Ratio float64 `min:"0" lt:"1"`
Timeout time.Duration `min:"0s"`
}
Fields of string type support the regexp tag. Only values that match the given regular expression will be accepted.
Similarly, url.URL fields support scheme, host and path struct tags to require that the URL scheme, host or path, respectively, match the given regular expression.
Go's regular expression matching will match any part of a string. To match the
entire string, anchor the expression with ^ and $.
Struct tag values use quoted strings. This means that double quotes and backslahes must be backslash-escaped.
Examples:
type Example struct {
BaseURL *url.URL `scheme:"^(http|https)$"`
Username string `regexp:"^\\pL"` // usernames must start with a letter.
}
net.IP and net.IPNet types support tags to validate a particular address.
The is tag can be used with values global unicast,
interface local multicast, link local multicast, link local unicast,
loopback, multicast, and unspecified. Each value matches the corresponding
range of IP addresses. A negative match can be specified by prefixing with a
!, and multiple values can be separated by commas. Validation succeeds if any
non-negated term matches the value being set. Validation fails, however, if any
negated term is matched.
Example:
type Example struct {
IP net.IP `is:"multicast,!interface local multicast"`
}
The above field will accept a multicast address, but not if it is an interface local multicast.
The net tag can be used to specify restrictions for which networks an IP
address can be part of. Network addresses are specified in address/bits
notation, e.g., 169.254.0.0/16 or 2001:cdba:9abc:5678::/64. As with the
net tag, a ! negates the match term, and multiple terms can be seprated by
commas. Validation succeeds if any non-negated term matches, and fails if any
negated term is matched.
Example:
type Example struct {
IP net.IP `net:"192.168.0.0/16,!192.168.254.0/24"`
}
The version tag accepts values 4 or 6 to indicate that an address must be an IPv4 or IPv6 address.
By default, values are parsed first from environment variables and then from command line flags. If a value is set by both an environment variable and a command line flag, the command line flag will overwrite the value set from the environment variable.
The from struct tag can be used to control where values are loaded from. The
default is from:"flag,env". To prevent a field from being set from an
environment variable, one could use from:"flag" in its struct tag.
The default loaders can also be overridden, either to change the order or to exclude defaults. For example, to cause environment variables to overwrite command line flags:
loaders := config.Loaders{new(config.FlagLoader), new(config.EnvLoader)}
config.DefaultConfig.SetLoaders(loaders)
The Configuration function is convenient for scanning values from a single struct and then loading them. However, functions are also provided for loading values into more than one struct, or for setting individual variables. The functions Scan, Var and Load are available.
To scan more than one struct, simply call Scan for each struct. Call Var to add an individual variable. When finished, call Load to parse and set values from the command line and/or environment.
Note, however, that name collisions will cause a panic.
For some cases, it may be desirable to avoid using the package global DefaultConfig. In order to support standalone or multiple configurations, simply use the config.Config type. The zero value is ready to use.
The config struct tag can be used to skip fields or change the names that
are generated for them. config:"-" will cause a field to be skipped.
config:"OtherName" will cause go-config to use OtherName as the name for
this field, which will be used in generating command line flag and environment
variable names.
Using prefix:"-" will cause a child struct to use the same prefix as the
parent struct. For example:
type Auth struct {
User string
Password string
}
type Options struct {
Auth *Auth `prefix:"-"`
URLs []*url.URL `scheme:"^(http|https)$"`
Verbose int `min:"0" max:"8"`
}
In this case, the command line flag for the User field will be simply -user, instead of -auth-user.
For even more control of naming, a struct can be passed to the Var function. See the documentation of that function for details.
Supports Go >= 1.10. go-config does not currently rely on any external packages.
go-config uses the MIT License.
Pull requests and bug requests are welcome.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.