config

Documentation

Overview

Package config provides an unified pattern for configuration structs.

Usage

Every configuration struct should implement the Config interface. There are three parts to a configuration: Initialization, validation and sample generation.

Initialization

A config struct is initialized by calling InitDefaults. This recursively initializes all uninitialized fields. Fields that should not be initialized to default must be set before calling InitDefaults.

Validation

A config struct is validated by calling Validate. This recursively validates all fields.

Sample Generation

A config struct can be used to generate a commented sample toml config by calling Sample. Unit tests guarantee the consistency between implementation and the generated sample. To this end, each config struct has to provide a composable unit test to check that the sample is parsable and consistent with the default values. See lib/envtest for an example.

Warning: The method Sample is allowed to panic if an error occurs during sample generation.

Index

• Constants
• func InitAll(defaulters ...Defaulter)
• func ValidateAll(validators ...Validator) error
• func WriteSample(dst io.Writer, path Path, ctx CtxMap, samplers ...Sampler)
• func WriteString(dst io.Writer, s string)
• type Config
• type CtxMap
• type Defaulter
• type NoDefaulter
  • func (NoDefaulter) InitDefaults()
• type NoValidator
  • func (NoValidator) Validate() error
• type Path
  • func (p Path) Extend(s string) Path
• type Sampler
• type StringSampler
  • func (s StringSampler) ConfigName() string
  • func (s StringSampler) Sample(dst io.Writer, _ Path, _ CtxMap)
• type Validator

Constants

const ID = "id"

Functions

func InitAll

func InitAll(defaulters ...Defaulter)

InitAll initializes all defaulters.

func ValidateAll

func ValidateAll(validators ...Validator) error

ValidateAll validates all validators. The first error encountered is returned.

func WriteSample

func WriteSample(dst io.Writer, path Path, ctx CtxMap, samplers ...Sampler)

WriteSample writes all sample config blocks in order of appearance with indentation and header to dst.

func WriteString

func WriteString(dst io.Writer, s string)

WriteString writes the string to dst. It panics if an error occurs.

Types

type Config

type Config interface {
	Sampler
	Validator
	Defaulter
}

Config is the interface that config structs should implement to allow for streamlined initialization, validation and sample generation.

type CtxMap

type CtxMap map[string]string

CtxMap contains the context for sample generation.

type Defaulter

type Defaulter interface {
	// InitDefaults recursively initializes the default values of all
	// uninitialized fields.
	InitDefaults()
}

Defaulter defines the initialization part of Config.

type NoDefaulter

type NoDefaulter struct{}

NoDefaulter implements a Defaulter that does a no-op on InitDefaults. It can be embedded in config structs that do not have any defaults.

func (NoDefaulter) InitDefaults

func (NoDefaulter) InitDefaults()

InitDefaults is a no-op.

type NoValidator

type NoValidator struct{}

NoValidator implements a Validator that never fails to validate. It can be embedded in config structs that do not need to validate.

func (NoValidator) Validate

func (NoValidator) Validate() error

Validate always returns nil.

type Path

type Path []string

Path is the header of a config block possibly consisting of multiple parts.

func (Path) Extend

func (p Path) Extend(s string) Path

Extend creates a copy of the path with string s appended.

type Sampler

type Sampler interface {
	// Sample creates a sample config and writes it to dst. Ctx provides
	// additional information. Sample is allowed to panic if an error
	// occurs.
	Sample(dst io.Writer, path Path, ctx CtxMap)
	// ConfigName returns the name of the config block. This forces
	// consistency between samples for different services for the same
	// config block.
	ConfigName() string
}

Sampler defines the sample generation part of Config.

type StringSampler

type StringSampler struct {
	// Text the sample string.
	Text string
	// Name the config name.
	Name string
}

StringSampler implements a Sampler that writes string Text and provides Name as ConfigName.

func (StringSampler) ConfigName

func (s StringSampler) ConfigName() string

ConfigName returns the name.

func (StringSampler) Sample

func (s StringSampler) Sample(dst io.Writer, _ Path, _ CtxMap)

Sample writes the text to dst.

type Validator

type Validator interface {
	// Validate recursively checks that all fields contain valid values.
	Validate() error
}

Validator defines the validation part of Config.