config

Documentation

Overview

Package config contains helpers for loading and dumping TOML config files

Index

• Constants
• Variables
• func Encoders() []string
• func LoadFile[T any](filename string, v *T, options ...func(*T) error) error
• func New[T any](options ...func(*T) error) (*T, error)
• func Prepare(v any) error
• type Autodetect
  • func (p *Autodetect) Decode(data string, v any) error
• type Decoder
  • func NewDecoder(name string) (Decoder, error)
  • func NewDecoderByFilename(filename string) (Decoder, error)
• type Encoder
  • func NewEncoder(name string) (Encoder, error)
• type JSON
  • func NewJSON() *JSON
  • func (JSON) Decode(data string, v any) error
  • func (p *JSON) SetIndent(indent string) bool
  • func (p *JSON) WriteTo(v any, w io.Writer) (int64, error)
• type Loader
  • func (l *Loader[T]) Last() string
  • func (l *Loader[T]) NewFromFile(configFile string, options ...func(*T) error) (*T, error)
  • func (l *Loader[T]) NewFromFlag(flag *pflag.Flag, options ...func(*T) error) (*T, error)
  • func (l *Loader[T]) NewFromKnownLocations(options ...func(*T) error) (*T, error)
  • func (l *Loader[T]) SetDefaults()
• type TOML
  • func NewTOML() *TOML
  • func (*TOML) Decode(data string, v any) error
  • func (p *TOML) SetIndent(indent string) bool
  • func (p *TOML) WriteTo(v any, w io.Writer) (int64, error)
• type YAML
  • func NewYAML() *YAML
  • func (*YAML) Decode(data string, v any) error
  • func (p *YAML) SetIndent(s string) bool
  • func (p *YAML) WriteTo(v any, w io.Writer) (int64, error)

Constants

const (
	// DefaultJSONIndent is the indentation used unless SetIndent
	// is called on the JSON Encoder
	DefaultJSONIndent = `  `
)

const (
	// DefaultTOMLIndent is the indentation used unless SetIndent
	// is called on the TOML Encoder
	DefaultTOMLIndent = `  `
)

Variables

var (
	// CmdName is the base name of default config files if none is
	// specified on the [Loader]
	CmdName = filepath.Base(os.Args[0])
	// DefaultDirectories is the list of directories to test when trying
	// to find a config file.
	DefaultDirectories = []string{".", "/etc", "/etc/" + CmdName}
	// DefaultExtensions is the list of extensions to test when trying
	// to find a config file.
	DefaultExtensions = []string{"conf", "json", "toml", "yaml", "yml"}
)

var (
	// ErrUnknownFormat indicates we failed to identify the format of the file
	ErrUnknownFormat = errors.New("file format not identified")
)

Functions

func Encoders

func Encoders() []string

Encoders returns all the formats we know to encode

func LoadFile

func LoadFile[T any](filename string, v *T,
	options ...func(*T) error) error

LoadFile loads a config file by name, expanding environment variables, filling gaps and validating its content. LoadFile uses the file extension to determine the format.

func New

func New[T any](options ...func(*T) error) (*T, error)

New creates a new config, applying the initialization functions, filling gaps and validating its content.

func Prepare

func Prepare(v any) error

Prepare fills any gap in the object and validates its content.

Types

type Autodetect

type Autodetect struct{}

Autodetect is a Decoder that tries all Decoders

func (*Autodetect) Decode

func (p *Autodetect) Decode(data string, v any) error

Decode takes encoded data and tries all registered decoders. Decode returns ErrUnknownFormat if all decoders fail.

type Decoder

type Decoder interface {
	Decode(data string, v any) error
}

A Decoder uses text to populate a data structure.

func NewDecoder

func NewDecoder(name string) (Decoder, error)

NewDecoder returns the decoder associated with a name or extension.

func NewDecoderByFilename

func NewDecoderByFilename(filename string) (Decoder, error)

NewDecoderByFilename uses the file extension to determine the decoder.

type Encoder

type Encoder interface {
	SetIndent(indent string) bool
	WriteTo(v any, w io.Writer) (int64, error)
}

Encoder serializes a data structure

func NewEncoder

func NewEncoder(name string) (Encoder, error)

NewEncoder returns a encoder for the specified format

type JSON

type JSON struct {
	Indent string
}

JSON is a Encoder/Decoder for JSON

func NewJSON

func NewJSON() *JSON

NewJSON creates a new JSON Encoder/Decoder with two space indentation.

func (JSON) Decode

func (JSON) Decode(data string, v any) error

Decode takes JSON encoded data to populate a data structure.

func (*JSON) SetIndent

func (p *JSON) SetIndent(indent string) bool

SetIndent specifies what to do for indenting the serialized JSON content.

func (*JSON) WriteTo

func (p *JSON) WriteTo(v any, w io.Writer) (int64, error)

WriteTo encodes data into a given io.Writer. If encoding fails, the writer won't be touched.

type Loader

type Loader[T any] struct {
	Base        string
	Directories []string
	Extensions  []string
	Others      []string
	// contains filtered or unexported fields
}

Loader helps finding and location configuration files

func (*Loader[T]) Last

func (l *Loader[T]) Last() string

Last returns the filename of the last config file to be used

func (*Loader[T]) NewFromFile

func (l *Loader[T]) NewFromFile(configFile string, options ...func(*T) error) (*T, error)

NewFromFile loads a config file by name, followed by initialization, filling gaps, and validation.

func (*Loader[T]) NewFromFlag

func (l *Loader[T]) NewFromFlag(flag *pflag.Flag, options ...func(*T) error) (*T, error)

NewFromFlag uses a cobra Flag for the config file name. if not specifies the known locations will be tried, and if all fails, it will create a default one.

func (*Loader[T]) NewFromKnownLocations

func (l *Loader[T]) NewFromKnownLocations(options ...func(*T) error) (*T, error)

NewFromKnownLocations scans locations specified in the Loader for a config file, if not possible it will create a default one.

func (*Loader[T]) SetDefaults

func (l *Loader[T]) SetDefaults()

SetDefaults fills the gaps in the Loader config. This is not required as LoadFileFlag() and LoadKnownLocations() will call it automatically before trying to find

type TOML

type TOML struct {
	Indent string
}

TOML is a Encoder/Decoder for TOML

func NewTOML

func NewTOML() *TOML

NewTOML creates a new TOML Encoder/Decoder with two space indentation.

func (*TOML) Decode

func (*TOML) Decode(data string, v any) error

Decode takes TOML encoded data to populate a data structure

func (*TOML) SetIndent

func (p *TOML) SetIndent(indent string) bool

SetIndent specifies what to do for indenting the serialized TOML content.

func (*TOML) WriteTo

func (p *TOML) WriteTo(v any, w io.Writer) (int64, error)

WriteTo encodes data into a given io.Writer. If encoding fails, the writer won't be touched.

type YAML

type YAML struct {
	Spaces int
}

YAML is a Encoder/Decoder for YAML

func NewYAML

func NewYAML() *YAML

NewYAML creates a new YAML Encoder/Decoder with two spaces as default indentation.

func (*YAML) Decode

func (*YAML) Decode(data string, v any) error

Decode takes YAML encoded data to populate a data structure

func (*YAML) SetIndent

func (p *YAML) SetIndent(s string) bool

SetIndent specifies what to use for indenting the serialized YAML content. Tabs are expanded to 8 spaces.

func (*YAML) WriteTo

func (p *YAML) WriteTo(v any, w io.Writer) (int64, error)

WriteTo encodes data into a given io.Writer. If encoding fails, the writer won't be touched.