gofig

README

GoFig

Easy config parsing for server applications.

Features

• generates flags (command line options) by parsing a structure
• supports optional config file lookup in different path (JSON, TOML and YAML files)
• supports optional config file flag (JSON, TOML and YAML files)
• supports environment variables
• supports user-defined default values

Types supported for flags and environment variables:

type	env	flag
string	✔	✔
bool	✔	✔
int	✔	✔
int64	✔	✔
uint	✔	✔
uint64	✔	✔
float64	✔	✔
gofig.Duration	✔	✔

Other types except for the list above such as float32 are not supported.

For the usage of gofig.Duration, please refer to ParseDuration

Order of priority

Each item takes precedence (override) over the item below it:

• flag
• env
• config
• default (user-defined value)

Struct tags

• json:
  • json: custom configuration key name (- to disable this json key)
• toml:
  • toml: custom configuration key name (- to disable this toml key)
• yaml:
  • yaml: custom configuration key name (- to disable this yaml key)
• env:
  • env: custom environment variable name (- to disable this env var)
• flag:
  • flag: custom flag name (- to disable this flag)
  • desc: flag description

Example

package main

import (
	"fmt"
	"time"

	"github.com/curvegrid/gofig"
)

type Config struct {
	Debug       bool           `flag:"d" desc:"enable debugging"`
	Environment string         `json:"env" toml:"env" yaml:"env" env:"env" flag:"e" desc:"environment name"`
	Port        int            `desc:"port to listen on"`
	Timeout     gofig.Duration `desc:"server timeout"`
}

func main() {
	cfg := Config{}
	cfg.Port = 5243 // user-defined default value
	cfg.Timeout = gofig.Duration(30 * time.Second)

	gofig.SetEnvPrefix("GF")
	gofig.SetConfigFileFlag("c", "config file")
	gofig.AddConfigFile("default") // gofig will try to load default.json, default.toml and default.yaml
	gofig.Parse(&cfg)

	fmt.Printf("Config: %+v\n", cfg)
}

Documentation

Index

• func AddConfigFile(path ...string)
• func Parse(v interface{})
• func SetConfigFileFlag(name string, desc string)
• func SetEnvPrefix(prefix string)
• type Duration
  • func (d *Duration) Set(s string) error
  • func (d *Duration) String() string
  • func (d *Duration) UnmarshalText(text []byte) error
• type ErrHandling
• type Gofig
  • func New(errHandling ErrHandling) *Gofig
  • func (gf *Gofig) AddConfigFile(path ...string)
  • func (gf *Gofig) Parse(v interface{}) error
  • func (gf *Gofig) ParseWithArgs(v interface{}, args []string) error
  • func (gf *Gofig) SetConfigFileFlag(name string, desc string)
  • func (gf *Gofig) SetEnvPrefix(prefix string)

Functions

func AddConfigFile

func AddConfigFile(path ...string)

AddConfigFile adds one or more config file(s) (WITHOUT THE FILE EXTENTION) to try to load a startup. Supports JSON (.json), TOML (.toml) and YAML (.yaml) configuration files. Config files are tried in order they are added and the search stop at the first existing file.

func Parse

func Parse(v interface{})

Parse parses the struct to build the flags, parse/decode the optional config file, decode the environment variables and finally parse the arguments.

func SetConfigFileFlag

func SetConfigFileFlag(name string, desc string)

SetConfigFileFlag adds a config file flag

func SetEnvPrefix

func SetEnvPrefix(prefix string)

SetEnvPrefix defines a prefix that ENVIRONMENT variables will use. If the prefix is "xyz", environment variables must start with "XYZ_".

Types

type Duration

type Duration time.Duration

Duration wraps time.Duration so we can augment it with encoding.TextMarshaler and flag.Value interfaces.

func (*Duration) Set

func (d *Duration) Set(s string) error

Set parses the provided string into a Duration.

func (*Duration) String

func (d *Duration) String() string

String returns a Duration as a string.

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

UnmarshalText unmarshals a byte slice into a Duration value.

type ErrHandling

type ErrHandling int

ErrHandling defines how to handle parsing errors

const (
	// ContinueOnError will return an err from Parse() if an error is found
	ContinueOnError ErrHandling = iota
	// ExitOnError will call os.Exit(2) if an error is found when parsing
	ExitOnError
	// PanicOnError will panic() if an error is found when parsing flags
	PanicOnError
)

type Gofig

type Gofig struct {
	// contains filtered or unexported fields
}

Gofig is the main gofig structure

func New

func New(errHandling ErrHandling) *Gofig

New returns an initialized Gofig instance.

func (*Gofig) AddConfigFile

func (gf *Gofig) AddConfigFile(path ...string)

AddConfigFile adds one or more config file(s) (WITHOUT THE FILE EXTENTION) to try to load a startup. Supports JSON (.json), TOML (.toml) and YAML (.yaml) configuration files. Config files are tried in order they are added and the search stop at the first existing file.

func (*Gofig) Parse

func (gf *Gofig) Parse(v interface{}) error

Parse parses the struct to build the flags, parse/decode the optional config file, decode the environment variables and finally parse the arguments.

func (*Gofig) ParseWithArgs

func (gf *Gofig) ParseWithArgs(v interface{}, args []string) error

ParseWithArgs parses the struct to build the flags, parse/decode the optional config file, decode the environment variables and finally parse the arguments.

func (*Gofig) SetConfigFileFlag

func (gf *Gofig) SetConfigFileFlag(name string, desc string)

SetConfigFileFlag adds a config file flag

func (*Gofig) SetEnvPrefix

func (gf *Gofig) SetEnvPrefix(prefix string)

SetEnvPrefix defines a prefix that ENVIRONMENT variables will use. If the prefix is "xyz", environment variables must start with "XYZ_".