configulator

README

Configulator

A simple configuration manager for use in my apps

Features

• Supports configuration from:
  • YAML or JSON files
  • Environment variables
  • Command line arguments (spf13/pflag)

Supported types

Working:

• all scalars except complex
• structs
• arrays of scalars

Not working:

• maps
• arrays of maps
• arrays of structs
• multi-dimensional arrays
• complex scalars

Usage

[!NOTE] Because the configuration options are expressed as different cases (i.e. http.host in YAML would be HTTP__HOST in environment variables), this library cannot be used for configurations that contain the same field name in different cases.

Struct tags

This library uses the name, default, and description tags. Multiple values can be passed if they are comma separated. Fields without a name tag are not utilized. The field name can be inferred from json or yaml tags if present.

Examples of struct field tags and their meanings:

// Field appears in config files, environment variables, and command line arguments as key "myName".
Field int `name:"myName"`

// Field has a description if seen in the CLI's --help
Field int `name:"myName" description:"this text appears in the help section of the CLI"`

// Field has a default value of 1
Field int `name:"myName" default:"1"`

Documentation

Index

• Constants
• Variables
• type Config
• type Configulator
  • func FromContext[C Config](ctx context.Context) (*Configulator[C], error)
  • func New[C Config]() *Configulator[C]
  • func (c *Configulator[C]) Default() (C, error)
  • func (c *Configulator[C]) Load() (*C, error)
  • func (c *Configulator[C]) LoadWithoutValidation() (*C, error)
  • func (c *Configulator[C]) WithArraySeparator(sep string) *Configulator[C]
  • func (c *Configulator[C]) WithContext(ctx context.Context) context.Context
  • func (c *Configulator[C]) WithEnvironmentVariables(opts *EnvironmentVariableOptions) *Configulator[C]
  • func (c *Configulator[C]) WithFile(opts *FileOptions) *Configulator[C]
  • func (c *Configulator[C]) WithPFlags(flags *pflag.FlagSet, opts *PFlagOptions) *Configulator[C]
• type EnvironmentVariableOptions
• type FileFormat
• type FileOptions
• type PFlagOptions

Constants

const (
	ConfigFileKey = "config"
)

Variables

var (
	ErrConfigFileNotFound = fmt.Errorf("config file not found")
)

Types

type Config

type Config interface {
	// Validate validates the configuration. It will be called after loading the configuration.
	// If the configuration is invalid, it should return an error.
	Validate() error
}

Config is the interface that must be implemented by the configuration struct.

type Configulator

type Configulator[C Config] struct {
	// contains filtered or unexported fields
}

Configulator is a configuration loader. It loads configuration from environment variables, files, and flags. The configuration is loaded in the following order: 1. Files 2. Environment variables 3. Flags

func FromContext

func FromContext[C Config](ctx context.Context) (*Configulator[C], error)

func New

func New[C Config]() *Configulator[C]

New creates a new Configulator. The defaults are the default configuration values.

func (*Configulator[C]) Default

func (c *Configulator[C]) Default() (C, error)

Default returns the default configuration.

func (*Configulator[C]) Load

func (c *Configulator[C]) Load() (*C, error)

Load reads the configuration from the environment variables, files, and flags.

func (*Configulator[C]) LoadWithoutValidation

func (c *Configulator[C]) LoadWithoutValidation() (*C, error)

LoadWithoutValidation reads the configuration from the environment variables, files, and flags without validating it.

func (*Configulator[C]) WithArraySeparator

func (c *Configulator[C]) WithArraySeparator(sep string) *Configulator[C]

WithArraySeparator sets the separator for array values

func (*Configulator[C]) WithContext

func (c *Configulator[C]) WithContext(ctx context.Context) context.Context

func (*Configulator[C]) WithEnvironmentVariables

func (c *Configulator[C]) WithEnvironmentVariables(opts *EnvironmentVariableOptions) *Configulator[C]

WithEnvironmentVariables sets the options for loading configuration from environment variables.

func (*Configulator[C]) WithFile

func (c *Configulator[C]) WithFile(opts *FileOptions) *Configulator[C]

WithFile sets the options for loading configuration from files.

func (*Configulator[C]) WithPFlags

func (c *Configulator[C]) WithPFlags(flags *pflag.FlagSet, opts *PFlagOptions) *Configulator[C]

WithPFlags sets the options for loading configuration from pflags. If WithFile() is used first, a flag for the config file is added.

type EnvironmentVariableOptions

type EnvironmentVariableOptions struct {
	// Prefix is the prefix for the environment variables. If empty, no prefix is used.
	Prefix string
	// Separator is the separator for the environment variables if nested. If empty, "__" is used.
	Separator string
}

EnvironmentVariableOptions contains the options for loading configuration from environment variables.

type FileFormat

type FileFormat int

FileFormat are the valid formats of the config file.

type FileOptions

type FileOptions struct {
	// Paths is the list of paths to search for the configuration file.
	Paths []string
	// ErrorIfNotFound indicates if an error should be returned if no config file is found.
	ErrorIfNotFound bool
}

FileOptions contains the options for loading configuration from files.

type PFlagOptions

type PFlagOptions struct {
	// Separator is the separator for the pflags if nested. If empty, "." is used.
	Separator string
}

PFlagOptions contains the options for loading configuration from pflags.