cs

README

CS

This is a new library aiming to simplify runtime configuration for Go applications. Expect more updates shortly.

CS

CS - Config Source - Runtime library for flexible configuration.

Install

go get -u github.com/activatedio/cs

Usage

The following example shows how to create a new config, add sources, and retrieve values

cfg := cs.New()

cfg.AddSource(cs.FromYAMLFile("cs.yaml"))
// Can be strings, maps or structs
cfg.AddSource(cs.FromValue("prefix.key", "value"))
cfg.AddLateBindingSource(cs.FromEnvironmentVars())

// Read reads value
var val *string
err := cs.Read("prefix.key", val)

// MustRead does the same but panics on error
//var val *string
//cs.MustRead("prefix.key", val)


fmt.Println(val)

Documentation

Overview

Package cs is the main package for the cs library

Index

• Constants
• func AddDefaultSource(src Source)
• func AddLateBindingSource(src LateBindingSource)
• func AddSource(src Source)
• func Get[T any](c Config, key string) (*T, error)
• func MustGet[T any](c Config, key string) *T
• func MustRead(key string, into any)
• func Read(key string, into any) error
• type Config
  • func Global() Config
  • func New() Config
• type DumpOption
  • func WithDumpOut(out io.Writer) DumpOption
  • func WithOmitEmpty() DumpOption
• type Entry
• type Error
  • func (e Error) Error() string
• type LateBindingSource
• type Source
• type Validating

Constants

const (
	// DescriptionKey is a reserved key for a map source to provide a metadata description
	DescriptionKey = "_description"
	// DescriptionTagName name of the description tag
	DescriptionTagName = "description"
)

Functions

func AddDefaultSource

func AddDefaultSource(src Source)

AddDefaultSource adds a source of default configuration values to the global configuration instance.

func AddLateBindingSource

func AddLateBindingSource(src LateBindingSource)

AddLateBindingSource adds a source which is consulted at read time, meaning each property present on the underlying results are looked up again with provided keys

func AddSource

func AddSource(src Source)

AddSource adds a source to build the root cs object. Sources are invoked in the order they are added. Sources added later take precedent over sources added earlier

func Get

func Get[T any](c Config, key string) (*T, error)

Get retrieves the value of type T associated with the specified key from the provided Config. Returns an error if retrieval fails.

func MustGet

func MustGet[T any](c Config, key string) *T

MustGet retrieves the value of type T associated with the specified key from the provided Config. It panics on errors.

func MustRead

func MustRead(key string, into any)

MustRead reads and panics on error

func Read

func Read(key string, into any) error

Read reads value from the key and assigns it to the provided object, which must be a pointer to a supported value supported values are all primitives and a map

Types

type Config

type Config interface {

	// AddDefaultSource adds a source that provides default configuration values, used as a fallback if no other source provides a value.
	AddDefaultSource(src Source)

	// AddSource adds a source to build the root cs object. Sources are invoked in the order they are added.
	// Sources added later take precedent over sources added earlier
	AddSource(src Source)

	// AddLateBindingSource adds a source which is consulted at read time, meaning each property present on the
	// underlying results are looked up again with provided keys
	AddLateBindingSource(src LateBindingSource)

	// Read reads value from the key and assigns it to the provided object, which must be a pointer to a supported value
	// supported values are all primitives and a map
	Read(key string, into any) error

	// MustRead reads and panics on error
	MustRead(key string, into any)

	// SetValidatingHook sets a custom hook for validation. By default the struct is checked to implement Validating and
	// if so the method is invoked
	SetValidatingHook(func(in any) error)

	// Dump dumps out the config and metadata
	// Default dumps to stdout with descriptions and values
	Dump(opts ...DumpOption) error
}

Config is main interface for cs data. Keys are in dot format, `prefix.name`

func Global

func Global() Config

Global gets the global config instance

func New

func New() Config

New returns a new cs object

type DumpOption

type DumpOption func(o *dumpOptions)

DumpOption represents a functional option used to configure the behavior of the dump operation.

func WithDumpOut

func WithDumpOut(out io.Writer) DumpOption

WithDumpOut sets a custom io.Writer as the output destination for the dump process.

func WithOmitEmpty

func WithOmitEmpty() DumpOption

WithOmitEmpty instructs ths dumper to not show empty entries

type Entry

type Entry struct {
}

Entry allows for a description to be applied via a tag to this struct

type Error

type Error struct {
	// Key specifies the config key requested which produced the error
	Key string
	// TypeName indicates the type associated with the error.
	TypeName string
	// Detail contains the underlying error providing further information.
	Detail error
}

Error represents a structure for detailed error handling with config key metadata.

func (Error) Error

func (e Error) Error() string

type LateBindingSource

type LateBindingSource func(key string) (any, error)

LateBindingSource source returns a cs value for a given key at the time a csuration is read

type Source

type Source func() (string, any, error)

Source returns a key, the cs object, and an error

type Validating

type Validating interface {
	Validate() error
}

Validating marks a struct with the ability to validate itself after being unmarshalled