configurature

README

Configurature

Configurature is a Go library that provides declarative app configuration using structs. Configuration values can be specified (in value precedence order) on the command line, using environment variables, and/or in a config file (yaml or json).

Configuration structs can be composed in a way that your application's entry points do not need to be aware of the structure of other packages' configurations in order to initialize them.

See the complete documentation at http://configurature-docs.readthedocs.io.

Basic Usage

Basic usage consists of defining your configuration structs and running configurature.Configure().

package main

import (
    "fmt"
    "net"

    co "github.com/imoore76/configurature"
)

type Config struct {
    ListenIP   net.IP `desc:"IP address on which to listen" default:"127.0.0.1"`
    ListenPort uint   `desc:"port on which to listen" default:"8080"`
}

func main() {

    conf := co.Configure[Config](&co.Options{
        EnvPrefix: "MYAPP_",
    })

    fmt.Printf("IP: %s\n", conf.ListenIP)
    fmt.Printf("Port: %d\n", conf.ListenPort)
}

Running this app with --help displays the app usage:

user@host $ myapp --help
Command usage:
  -h, --help               show help and exit
      --listen_ip ip       IP address on which to listen (default 127.0.0.1)
      --listen_port uint   port on which to listen (default 8080)

CLI option and environment variable example:

user@host $ MYAPP_LISTEN_IP=0.0.0.0 myapp --listen_port 80
IP: 0.0.0.0
Port: 80

Configuration values can be specified on the command line, using environment variables, and/or in a config file.

Configurature also supports

• Custom types
• Validation
• Nested configurations

See the complete documentation at http://configurature-docs.readthedocs.io.

Contributing

See CONTRIBUTING.md for details.

License

Apache 2.0; see LICENSE for details.

Disclaimer

This project is not an official Google project. It is not supported by Google and Google specifically disclaims all warranties as to its quality, merchantability, or fitness for a particular purpose.

Documentation

Overview

This file contains the ConfigFile type helpers

This file contains the Value interface implementation for the ConfigFile type which is used to specify a configuration file field on a configurature struct

This file provides the Configure function and its helpers

This file contains the AddMapValueType[T] factory function and its helpers

This file contains config package's handlers for reflect types encountered in configuration parsing and handling

Index

• Variables
• func AddMapValueType[T any](typeName string, keys []string, values []T)
• func AddType[structFieldType any]()
• func Configure[T any](opts *Options) *T
• func Get[T any]() (*T, error)
• type ConfigFile
  • func (f *ConfigFile) Set(v string) error
  • func (f *ConfigFile) String() string
  • func (f *ConfigFile) Type() string
• type Options
• type Value

Variables

var (

	// ErrConfigNotLoaded is returned when the last loaded configuration is nil
	ErrConfigNotLoaded = errors.New("configuration not loaded - did you run Configure[]()?")

	// For disabling type caching
	DisableGetTypeCache = false
)

Functions

func AddMapValueType

func AddMapValueType[T any](typeName string, keys []string, values []T)

AddMapValueType takes a slice of string keys and values and registers it as a string->value map Configurature type.

func AddType

func AddType[structFieldType any]()

AddType adds a custom type to the customFlagMap. You can also use this to replace the behavior of existing types.

Parameters: - structFieldType: The type of struct field

func Configure

func Configure[T any](opts *Options) *T

Configure will populate the supplied struct with options specified on the command line or by environment variables prefixed by the specified envPrefix

func Get

func Get[T any]() (*T, error)

Get returns a pointer to the configuration of type T found anywhere in the last loaded configuration. Returns (nil, ErrConfigNotLoaded) if the last loaded configuration is nil. Returns (nil, nil) if no configuration of type T is found

Types

type ConfigFile

type ConfigFile string

Type representing a config file setting

func (*ConfigFile) Set

func (f *ConfigFile) Set(v string) error

func (*ConfigFile) String

func (f *ConfigFile) String() string

func (*ConfigFile) Type

func (f *ConfigFile) Type() string

type Options

type Options struct {
	EnvPrefix         string               // Prefix for environment variables
	Args              []string             // Arguments to parse
	NilPtrs           bool                 // Leave pointers set to nil if values aren't specified
	Usage             func(*pflag.FlagSet) // Usage function called when configuration is incorrect or for --help
	NoRecover         bool                 // Don't recover from panic
	ShowInternalFlags bool                 // Show hidden internal flags
	NoShortHelp       bool                 // Don't add "h" as a short help flag
}

Configure options

type Value

type Value interface {
	Set(string) error // Set the internal value based on the string. If invalid, return error
	String() string   // Internal value as a string
	Type() string     // Type of the value. Appears in Usage() help
}

Value interface for config types