Documentation
¶
Overview ¶
Package options implements config options. This package is currently a bit of an experiment. Objectives:
- Options are key-value pairs.
- Options can come from default config, individual source config, and flags.
- Support the ability to edit config in $EDITOR, providing contextual information about the Opt instance.
- Values are strongly typed (e.g. int, time.Duration)
- An individual Opt instance can be specified near where it is used.
- New types of Opt can be defined, near where they are used.
It is noted that these requirements could probably largely be met using packages such as spf13/viper. AGain, this is largely an experiment.
Index ¶
- func NewContext(ctx context.Context, o Options) context.Context
- type BaseOpt
- func (op BaseOpt) DefaultAny() any
- func (op BaseOpt) Flag() string
- func (op BaseOpt) GetAny(_ Options) any
- func (op BaseOpt) Help() string
- func (op BaseOpt) IsSet(o Options) bool
- func (op BaseOpt) Key() string
- func (op BaseOpt) Process(o Options) (Options, error)
- func (op BaseOpt) Short() rune
- func (op BaseOpt) String() string
- func (op BaseOpt) Tags() []string
- func (op BaseOpt) Usage() string
- type Bool
- type Duration
- type Int
- type Opt
- type Options
- type Processor
- type Registry
- type String
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewContext ¶ added in v0.34.0
NewContext returns a context that contains the given Options. Use FromContext to retrieve the Options.
NOTE: It's questionable whether we need to engage in this context business with Options. This is a bit of an experiment.
Types ¶
type BaseOpt ¶ added in v0.34.0
type BaseOpt struct {
// contains filtered or unexported fields
}
BaseOpt is a partial implementation of options.Opt that concrete types can build on.
func NewBaseOpt ¶ added in v0.34.0
NewBaseOpt returns a new BaseOpt. If flag is empty string, key is used as the flag value.
func (BaseOpt) DefaultAny ¶ added in v0.34.0
DefaultAny implements options.Opt.
func (BaseOpt) GetAny ¶ added in v0.34.0
GetAny is required by options.Opt. It needs to be implemented by the concrete type.
type Bool ¶ added in v0.34.0
type Bool struct {
BaseOpt
// contains filtered or unexported fields
}
Bool is an options.Opt for type bool.
func NewBool ¶ added in v0.34.0
func NewBool(key, flag string, short rune, defaultVal bool, usage, help string, tags ...string) Bool
NewBool returns an options.Bool instance. If flag is empty, the value of key is used.
func (Bool) DefaultAny ¶ added in v0.34.0
DefaultAny implements options.Opt.
func (Bool) Get ¶ added in v0.34.0
Get returns op's value in o. If o is nil, or no value is set, op's default value is returned.
type Duration ¶ added in v0.34.0
type Duration struct {
BaseOpt
// contains filtered or unexported fields
}
Duration is an options.Opt for time.Duration.
func NewDuration ¶ added in v0.34.0
func NewDuration(key, flag string, short rune, defaultVal time.Duration, usage, help string, tags ...string) Duration
NewDuration returns an options.Duration instance. If flag is empty, the value of key is used.
func (Duration) DefaultAny ¶ added in v0.34.0
DefaultAny implements options.Opt.
func (Duration) Get ¶ added in v0.34.0
Get returns op's value in o. If o is nil, or no value is set, op's default value is returned.
type Int ¶ added in v0.34.0
type Int struct {
BaseOpt
// contains filtered or unexported fields
}
Int is an options.Opt for type int.
func NewInt ¶ added in v0.34.0
NewInt returns an options.Int instance. If flag is empty, the value of key is used.
func (Int) DefaultAny ¶ added in v0.34.0
DefaultAny implements options.Opt.
func (Int) Get ¶ added in v0.34.0
Get returns op's value in o. If o is nil, or no value is set, op's default value is returned.
type Opt ¶ added in v0.34.0
type Opt interface {
// Key returns the Opt key, such as "ping.timeout".
Key() string
// Flag is the long flag name to use, which is typically the same value
// as returned by Opt.Key. However, a distinct value can be supplied, such
// that flag usage and config usage have different keys. For example,
// an Opt might have a key "diff.num-lines", but a flag "lines".
Flag() string
// Short is the short key. The zero value indicates no short key.
// For example, if the key is "json", the short key could be 'j'.
Short() rune
// Usage is a one-line description of the Opt. Additional detail can be
// found in Help.
Usage() string
// Help returns the Opt's help text, which typically provides more detail
// than Usage. The text must be plaintext (not markdown). Linebreaks are
// recommended at 100 chars.
Help() string
// String returns a log/debug-friendly representation.
String() string
// IsSet returns true if this Opt is set in o.
IsSet(o Options) bool
// GetAny returns the value of this Opt in o. Generally, prefer
// use of the concrete strongly-typed Get method. If o is nil or
// empty, or the Opt is not in o, the Opt's default value is
// returned.
GetAny(o Options) any
// DefaultAny returns the default value of this Opt. Generally, prefer
// use of the concrete strongly-typed Default method.
DefaultAny() any
// Tags returns any tags on this Opt instance. For example, an Opt might
// have tags [source, csv].
Tags() []string
// Process processes o. The returned Options may be a new instance,
// with mutated values. This is typ
Process(o Options) (Options, error)
}
Opt is an option type. Concrete impls exist for various types, such as options.Int or options.Duration. Each concrete type must implement a "Get(o Options) T" method that returns the appropriate type T. The value returned by that Get method will be the same as that returned by the generic Opt.GetAny method. The impl should also provide a NewT(...) T constructor. The caller typically registers the new Opt in a options.Registry via Registry.Add.
An impl should implement the Process method to appropriately munge the backing value. For example, options.Duration converts a string such as "1m30s" into a time.Duration.
type Options ¶
Options is a map of Opt.Key to a value.
func Effective ¶ added in v0.34.0
Effective returns a new Options containing the effective values of each Opt. That is to say, the returned Options contains either the actual value of each Opt in o, or the default value for that Opt, but it will not contain values for any Opt not in opts.
func FromContext ¶ added in v0.34.0
FromContext returns the Options stored in ctx by NewContext, or nil if no such Options.
type Processor ¶ added in v0.34.0
type Processor interface {
// Process processes o. The returned Options may be a new instance,
// with mutated values.
Process(o Options) (Options, error)
}
Processor performs processing on o.
type Registry ¶ added in v0.34.0
type Registry struct {
// contains filtered or unexported fields
}
Registry is a registry of Opt instances.
func (*Registry) Add ¶ added in v0.34.0
Add adds opts to r. It panics if any element of opts is already registered.
func (*Registry) Opts ¶ added in v0.34.0
Opts returns a new slice containing each Opt registered with r.
func (*Registry) Process ¶ added in v0.34.0
Process processes o, returning a new Options. Process should be invoked after the Options has been loaded from config, but before it is used by the program. Process iterates over the registered Opts, and invokes Process for each Opt that implements Processor. This facilitates munging of backing values, e.g. for options.Duration, a string "1m30s" is converted to a time.Duration.
type String ¶ added in v0.34.0
type String struct {
BaseOpt
// contains filtered or unexported fields
}
String is an options.Opt for type string.
func NewString ¶ added in v0.34.0
NewString returns an options.String instance. If flag is empty, the value of key is used.
func (String) DefaultAny ¶ added in v0.34.0
DefaultAny implements options.Opt.
Source Files