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 ¶
- Constants
- func NewContext(ctx context.Context, o Options) context.Context
- type BaseOpt
- func (op BaseOpt) DefaultAny() any
- func (op BaseOpt) Flag() Flag
- func (op BaseOpt) GetAny(_ Options) any
- func (op BaseOpt) HasTag(tag string) bool
- 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) String() string
- func (op BaseOpt) Tags() []string
- func (op BaseOpt) Usage() string
- type Bool
- type Duration
- type Flag
- type Int
- type Opt
- type Options
- type Processor
- type Registry
- type String
Constants ¶
const ( // TagSource indicates that an Opt with this tag applies to source config // (as opposed to applying only to base config). An opt with this tag // typically applies to both base and source config. TagSource = "source" // TagTuning indicates that the Opt is related to tuning behavior. TagTuning = "tuning" // TagSQL indicates that the Opt is related to SQL interaction. TagSQL = "sql" // TagOutput indicates the Opt is related to output/formatting. TagOutput = "output" // TagIngestMutate indicates the Opt may result in mutated data, particularly // during ingestion. This tag is significant in that its value may affect // data realization, and thus affect program aspects such as caching behavior. TagIngestMutate = "mutate" )
Variables ¶
This section is empty.
Functions ¶
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.
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
NewBool returns an options.Bool instance. If arg flag is non-nil and [Flag.Invert] is true, the flag's boolean value is inverted to set the option. For example, if [Opt.Key] is progress, and [Flag.Name] is "--no-progress", then [Flag.Invert] should be true.
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 string, flag *Flag, defaultVal time.Duration, usage, help string, tags ...string, ) Duration
NewDuration returns an options.Duration instance.
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 Flag ¶ added in v0.47.4
type Flag struct {
// Name is the flag name to use. Defaults to [Opt.Key].
Name string
// Usage is the flag's usage text. Defaults to [Opt.Usage], but can be
// overridden if the flag usage text should differ from the [Opt] usage text.
// This is typically only the case when [Flag.Invert] is true.
Usage string
// Short is the short flag name, e.g. 'v' for "verbose". The zero value
// indicates no short name.
Short rune
// Invert indicates that the flag's boolean value is inverted vs the flag
// name. For example, if [Opt.Key] is "progress", but [Flag.Name] is
// "no-progress", then [Flag.Invert] should be true. This field is ignored for
// non-boolean [Opt] types.
Invert bool
}
Flag describe an Opt's behavior as a command-line flag. It can be passed to the "NewX" Opt constructor functions, e.g. NewBool, to override the Opt's flag configuration. The computed Flag value is available via Opt.Flag. It is common to pass a nil *Flag to the Opt constructors; the value returned by Opt.Flag will be appropriately populated with default values.
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 (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 computed flag config for the Opt.
Flag() Flag
// Usage is a one-line description of the Opt. Additional detail can be
// found in Help. It is typically the case that [Flag.Usage] is the same value
// as Usage, but it can be overridden if the flag usage text should differ
// from the Opt usage text.
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
// HasTag returns true if the result of Opt.Tags contains tag.
HasTag(tag string) bool
// 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.
func Merge ¶ added in v0.34.0
Merge overlays each of overlays onto base, returning a new Options. It is acceptable for base to be nil.
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
func NewString(key string, flag *Flag, defaultVal string, validFn func(string) error, usage, help string, tags ...string, ) String
NewString returns an options.String instance. If validFn is non-nil, it is called by String.Process.
func (String) DefaultAny ¶ added in v0.34.0
DefaultAny implements options.Opt.
func (String) 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.
Source Files