asp

README

asp — Automatic Settings Processor

asp, the Automatic Settings Provider, an opinionated companion for viper and cobra.

• Getting started
• Config processing
• Defaults
• Options
• Config tags

Why does this exist?

The cobra package provides excellent command-line flag functionality, and viper provides a rich configuration store and environment variable binding… but… there’s a lot of boilerplate and redundant code if you want to achieve the nirvana of CLI flags and environment variables and configuration file support for all flags/settings in your application. The asp package attempts to reduce this boilerplate by capturing it all from your “canonical” configure structure definition.

The goals of asp are to

1. reduce the redundant boilerplate by concisely defining all of the necessary information in the config struct itself;

2. encourage good practices by ensuring that every option has config, command-line and environment variable representation;

3. avoid possible typos that using string-based configuration lookups can cause—Go can’t tell that viper.Get("sommeSetting") is misspelled at compile time—but it can tell that config.sommeSetting is invalid if the struct defines the member as config.someSetting.

Documentation

Overview

asp, the Automatic Settings Provider, an opinionated companion for viper and cobra.

• Getting started
• Config processing
• Defaults
• Options
• Config tags

## Why does this exist?

The cobra package provides excellent command-line flag functionality, and viper provides a rich configuration store and environment variable binding… _but_… there’s a lot of boilerplate and redundant code if you want to achieve the nirvana of CLI flags and environment variables _and_ configuration file support for _**all**_ flags/settings in your application. The asp package attempts to reduce this boilerplate by capturing it all from your “canonical” configure structure definition.

### The goals of asp are to

1. reduce the redundant boilerplate by concisely defining all of the necessary information in the config struct itself;

2. encourage good practices by ensuring that _every_ option has config, command-line _and_ environment variable representation;

3. avoid possible typos that using string-based configuration lookups can cause—Go can’t tell that `viper.Get("sommeSetting")` is misspelled at compile time—but it _can_ tell that `config.sommeSetting` is invalid if the struct defines the member as `config.someSetting`.

Index

• Variables
• func Attach[T Config](cmd *cobra.Command, configDefaults T, options ...Option) error
• func Get[T Config](cmd *cobra.Command) (*T, error)
• func WithConfigFlag(a *aspBase) error
• func WithoutConfigFlag(a *aspBase) error
• type Asp
  • func AttachInstance[T Config](cmd *cobra.Command, configDefaults T, options ...Option) (Asp[T], error)
• type Config
• type Option
  • func WithDecodeHook(decodeHook mapstructure.DecodeHookFunc) Option
  • func WithDefaultConfigName(cfgName string) Option
  • func WithEnvPrefix(prefix string) Option

Variables

var (
	// ErrConfigMustBeStruct indicates that the (default) config value passed to
	// [asp.Attach] must be a struct (or pointer to struct) type.
	ErrConfigMustBeStruct = errors.New("config must be a struct or pointer to struct")

	// ErrConfigFieldUnsupported is returned when a member of the config struct
	// is an unsupported type.
	ErrConfigFieldUnsupported = errors.New("config struct field is of an unsupported type (pointer, array, channel or size-specific number)")
)

var ContextKey = contextKey{}

var DefaultDecodeHook = mapstructure.ComposeDecodeHookFunc(
	mapstructure.StringToTimeDurationHookFunc(),
	decoders.StringToTime(),
	decoders.StringToByteSlice(),
	decoders.StringToMapStringInt(),
	decoders.StringToMapStringString(),
	decoders.StringToSlice(","),
)

DefaultDecodeHook is the default set of decoders that [Asp[T IncomingConfig].Config] uses. See the WithDecodeHook option to provide your own list of decoders.

var ErrConfigTypeMismatch = errors.New("the asp.Asp instance uses a different type than was requested")

Functions

func Attach

func Attach[T Config](cmd *cobra.Command, configDefaults T, options ...Option) error

Attach[T] adds to a cobra.Command the command-line arguments, and environment variable and configuration file bindings inferred from `configDefaults`. If no Option arguments are provided, it effectively defaults to WithConfigFlag, WithEnvPrefix("APP"), and WithDecodeHook(DefaultDecodeHook).

Note that the cobra.Command's PersistentPreRun is set to stash away the [Asp[T]] instance, which the [Get[T]] method later makes use of.

func Get

func Get[T Config](cmd *cobra.Command) (*T, error)

Get[T] retrieves the asp instance from the cobra.Command's context and gets the current configuration from flags, environment variables, and config files.

func WithConfigFlag

func WithConfigFlag(a *aspBase) error

WithConfigFlag adds a `--config cfgFile` flag to the command being attached. Note that there is *not* an environment variable or config setting that mirrors this CLI-only flag. This is set by default.

func WithoutConfigFlag

func WithoutConfigFlag(a *aspBase) error

WithoutConfigFlag prevents the addition a `--config cfgFile` flag to the command being attached.

Types

type Asp

type Asp[T Config] interface {
	// Config returns the aggregated configuration values, pulling from CLI
	// flags, environment variables, and implicit or explicit config file.
	Config() (*T, error)

	// Command provides access to the [cobra.Command] that this instance of
	// [Asp] was attached to, in case additional Command customization is
	// needed.
	Command() *cobra.Command

	// Viper provides access to the [viper.Viper] that was created when this
	// instance of [Asp] was attached to the command, in case additional Viper
	// customization is needed.
	Viper() *viper.Viper
}

Asp[T IncomingConfig] is an interface that represents the interface for settings/options. After creating/initializing with a configuration structure (with default values), the methods on the interface allow for loading from command-line/config/environment, as well as lower-level access to the created viper instance and cobra command. (In most cases these should not be needed, though!)

func AttachInstance

func AttachInstance[T Config](cmd *cobra.Command, configDefaults T, options ...Option) (Asp[T], error)

AttachInstance[T] is identical to [Attach[T]], but also returns the [Asp[T]] instance itself, in case the default context-stashing doesn't suit your needs.

type Config

type Config interface {
	interface{}
}

Config is a placeholder generic type that exists only to allow us to define our inner and exposed value as strongly-typed to the originating configuration struct.

type Option

type Option func(*aspBase) error

Option represents an option to the asp.Attach method.

func WithDecodeHook

func WithDecodeHook(decodeHook mapstructure.DecodeHookFunc) Option

WithDecodeHook allows for customization of the default decode hooks used to unmarshal values into the configuration structure. Use mapstructure.ComposeDecodeHookFunc to include more than one decode hook, and also see asp.DefaultDecodeHook for the default decoders.

func WithDefaultConfigName

func WithDefaultConfigName(cfgName string) Option

WithDefaultConfigName specifies the filename to use when searching for a config file. This is typically the same as the app name. If no default config name is given, *no* config file will be loaded by default, and the `--config` command-line flag *must* be given to use a config file.

func WithEnvPrefix

func WithEnvPrefix(prefix string) Option

WithEnvPrefix specifies the prefix to use with environment variables. If not passed to Attach(), the prefix "APP" is assumed.