Documentation
¶
Overview ¶
Package file provides a flagr.Parser that is able to read config files and set the appropriate flags.
Index ¶
Constants ¶
const KeyPathSeparator = "."
KeyPathSeparator is the value used to separate sub paths in path expressions. A typical KeyPath will look something like "root.inner.prop".
Variables ¶
This section is empty.
Functions ¶
func Parser ¶
Parser returns a flagr.FlagParser that parses the file stored in path and assigns the results to any flags that have not yet been set.
Flags cannot have complex values, only primitive values are allowed: strings, bools, ints etc. An exception is made for slices as flags can be repeatable.
This is a valid JSON declaration for a flag named "foo".
{
"foo": 42
}
So is this (assuming that foo is repeatable, otherwise it will be set to the last value of the array):
{
"foo": [1, 2, 3]
}
But this is not, as there is no way to map an object to a flag value:
{
"foo": {"bar": 42}
}
The file contents are read and decoded using the decoder mapped to the file's extension. If decoding fails it returns ErrDecode, if no suitable decoder is found it returns ErrUnsupported.
File decoding is controlled by WithDecoder. At least one mapping must be provided.
If the file cannot be read an error is returned. If it cannot be found and IgnoreMissingFile has been set, the error is omitted and parsing stops.
After decoding, we will go trough all the flags that have not yet been set, and try to find their values in the decoded result. Mapping flag names to the decoded properties is done using the given Normalizer. If no Normalizer is provided it'll use NoopNormalizer.
If no corresponding value can be found, the flag will remain unset. If a value is found it is converted back to a string and fed trough flag.Value.Set, if this fails we will return the error. If we are unable to convert the value to a string (for example, if it's an object) ErrVal will be returned containing the key that failed and the error.
Types ¶
type DecoderFunc ¶
DecoderFunc is a function that deserializes data into v. Functions like json.Unmarshal conform to this type.
type ErrDecode ¶
type ErrDecode struct {
Err error
}
ErrDecode is returned if deserialization fails.
type ErrUnsupported ¶
ErrUnsupported is returned when we could not find a DecoderFunc in the given Mux with the provided file's extension.
func (ErrUnsupported) Error ¶
func (e ErrUnsupported) Error() string
type Extension ¶
type Extension string
Extension represents a file extension. Values must include the leading dot.
type KeyPath ¶
type KeyPath string
KeyPath represents a path expression which is used to walk the values produced by the decoding of the config file. It is akin to jsonpath but we only support dot notation.
func NoopNormalizer ¶
NoopNormalizer returns the given flag name as is.
type Mux ¶
type Mux map[Extension]DecoderFunc
Mux maps Extensions to DecoderFuncs, it is valid for the same DecoderFunc to be used for multiple Extensions. For example, if unmarshaling yaml it is encouraged to map both ".yaml" and ".yml" to yaml.Unmarshal.
type Normalizer ¶
Normalizer converts a flag name into a KeyPath.
Sub paths must be separated by KeyPathSeparator and are not allowed to contain it within them.
Given a flag name like "api_http_address" and a json config file structured as
{
"api": {
"http": {
"address": "0.0.0.0"
}
}
}
the corresponding KeyPath should be "api.http.address".
If the json file were flat, no normalization would be necessary as long as the field name and the flag name are equal:
{
"api_http_address": "0.0.0.0"
}
the corresponding KeyPath should be "api_http_address".
type Option ¶
type Option func(*Options)
Option is a function that mutates Options.
func IgnoreMissingFile ¶
func IgnoreMissingFile() Option
IgnoreMissingFile makes it so that if the provided file doesn't exist, it is not considered an error.
func WithDecoder ¶
func WithDecoder(fn DecoderFunc, exts ...Extension) Option
WithDecoder maps the given DecoderFunc to the given Extensions.
It does not remove previous mappings but will replace any mapping that has the same Extension.
func WithFS ¶
With FS configures the Parser such that the file is retrieved from the given fs instead of the primary filesystem.
func WithNormalizer ¶
func WithNormalizer(n Normalizer) Option
WithNormalizer configures Parser to use the given Normalizer when mapping flag names to KeyPaths.
type Options ¶
type Options struct {
Mux Mux // Maps file extensions to decoders
Normalizer Normalizer // Maps flag names to property paths
IgnoreMissingFile bool // If true, we don't treat fs.ErrNotExist as an error.
FS fs.FS // If provided, this will be used instead of the primary filesystem.
}
Options contains all the options used to parse a config file.
Source Files