rconfig

README

Description

Package rconfig implements a CLI configuration reader with struct-embedded defaults, environment variables and posix compatible flag parsing using the pflag library.

Installation

Install by running:

go get -u github.com/henrix88/rixconfig

Run tests by running in the checkout folder:

go test -v -race -cover ./...

Usage

A very simple usecase is to just configure a struct inside the vars section of your main.go and to parse the commandline flags from the main() function:

package main

import (
  "fmt"
  "github.com/henrix88/rixconfig"
)

var (
  cfg = struct {
    Username string `default:"unknown" flag:"user" description:"Your name"`
    Details  struct {
      Age int `default:"25" flag:"age" env:"age" description:"Your age"`
    }
  }{}
)

func main() {
  rconfig.Parse(&cfg)

  fmt.Printf("Hello %s, happy birthday for your %dth birthday.",
    cfg.Username,
    cfg.Details.Age)
}

Provide variable defaults by using a file

Given you have a file ~/.myapp.yml containing some secrets or usernames (for the example below username is assumed to be "luzifer") as a default configuration for your application you can use this source code to load the defaults from that file using the vardefault tag in your configuration struct.

The order of the directives (lower number = higher precedence):

1. Flags provided in command line
2. Environment variables
3. Variable defaults (vardefault tag in the struct)
4. default tag in the struct

var cfg = struct {
  Username string `vardefault:"username" flag:"username" description:"Your username"`
}

func main() {
  rconfig.SetVariableDefaults(rconfig.VarDefaultsFromYAMLFile("~/.myapp.yml"))
  rconfig.Parse(&cfg)

  fmt.Printf("Username = %s", cfg.Username)
  // Output: Username = luzifer
}

More info

You can see the full reference documentation of the rconfig package at pkg.go.dev

Documentation

Overview

Package rconfig implements a CLI configuration reader with struct-embedded defaults, environment variables and posix compatible flag parsing using the pflag library.

Index

• func AddTimeParserFormats(f ...string)
• func ApplyEnvAndDefaults(config interface{}, flagSet *pflag.FlagSet) error
• func Args() []string
• func AutoEnv(enable bool)
• func Parse(config interface{}) error
• func ParseAndValidate(config interface{}) error
• func RegisterFlags(config interface{}, flagSet *pflag.FlagSet) error
• func SetVariableDefaults(defaults map[string]string)
• func Usage()
• func VarDefaultsFromYAML(in []byte, opts ...YAMLOption) (map[string]string, error)
• func VarDefaultsFromYAMLFile(filename string, opts ...YAMLOption) (map[string]string, error)
• type YAMLOption
  • func WithKeyToLower() YAMLOption
• type YAMLOptions

Examples

• Parse

Functions

func AddTimeParserFormats

func AddTimeParserFormats(f ...string)

AddTimeParserFormats adds custom formats to parse time.Time fields

func ApplyEnvAndDefaults

func ApplyEnvAndDefaults(config interface{}, flagSet *pflag.FlagSet) error

ApplyEnvAndDefaults applies environment variables and vardefaults to a config struct whose flags have already been registered and parsed by an external FlagSet (e.g., Cobra). This maintains the precedence: flag (if changed) > env > vardefault > default. Only fields where the flag was NOT explicitly set by the user will be updated.

func Args

func Args() []string

Args returns the non-flag command-line arguments.

func AutoEnv

func AutoEnv(enable bool)

AutoEnv enables or disables automated env variable guessing. If no `env` struct tag was set and AutoEnv is enabled the env variable name is derived from the name of the field: `MyFieldName` will get `MY_FIELD_NAME`

func Parse

func Parse(config interface{}) error

Parse takes the pointer to a struct filled with variables which should be read from ENV, default or flag. The precedence in this is flag > ENV > default. So if a flag is specified on the CLI it will overwrite the ENV and otherwise ENV overwrites the default specified.

For your configuration struct you can use the following struct-tags to control the behavior of rconfig:

default: Set a default value
vardefault: Read the default value from the variable defaults
env: Read the value from this environment variable
flag: Flag to read in format "long,short" (for example "listen,l")
description: A help text for Usage output to guide your users

The format you need to specify those values you can see in the example to this function.

Example

// We're building an example configuration with a sub-struct to be filled
// by the Parse command.
config := struct {
	Username string `default:"unknown" flag:"user,u" description:"Your name"`
	Details  struct {
		Age int `default:"25" flag:"age" description:"Your age"`
	}
}{}

// To have more relieable results we're setting os.Args to a known value.
// In real-life use cases you wouldn't do this but parse the original
// commandline arguments.
os.Args = []string{
	"example",
	"--user=Luzifer",
}

if err := rconfig.Parse(&config); err != nil {
	panic(err)
}

fmt.Printf("Hello %s, happy birthday for your %dth birthday.",
	config.Username,
	config.Details.Age)

// You can also show an usage message for your user
rconfig.Usage()

Output:
Hello Luzifer, happy birthday for your 25th birthday.

func ParseAndValidate

func ParseAndValidate(config interface{}) error

ParseAndValidate works exactly like Parse but implements an additional run of the go-validator package on the configuration struct. Therefore additional struct tags are supported like described in the readme file of the go-validator package:

https://github.com/go-validator/validator/tree/v2#usage

func RegisterFlags

func RegisterFlags(config interface{}, flagSet *pflag.FlagSet) error

RegisterFlags registers all flags from the config struct to the provided FlagSet. This is useful for integrating with Cobra or other CLI frameworks. The flags will be registered with their default values from the struct tags. After the framework parses the flags, call ApplyEnvAndDefaults to apply environment variables and vardefaults to flags that weren't explicitly set.

func SetVariableDefaults

func SetVariableDefaults(defaults map[string]string)

SetVariableDefaults presets the parser with a map of default values to be used when specifying the vardefault tag

func Usage

func Usage()

Usage prints a basic usage with the corresponding defaults for the flags to os.Stdout. The defaults are derived from the `default` struct-tag and the ENV.

func VarDefaultsFromYAML

func VarDefaultsFromYAML(in []byte, opts ...YAMLOption) (map[string]string, error)

VarDefaultsFromYAML creates a vardefaults map from YAML raw data, supporting nested YAML by flattening keys.

func VarDefaultsFromYAMLFile

func VarDefaultsFromYAMLFile(filename string, opts ...YAMLOption) (map[string]string, error)

VarDefaultsFromYAMLFile reads contents of a file and calls VarDefaultsFromYAML

Types

type YAMLOption

type YAMLOption func(*YAMLOptions)

YAMLOption functional option for YAML parsing

func WithKeyToLower

func WithKeyToLower() YAMLOption

WithKeyToLower validates keys are lower-cased

type YAMLOptions

type YAMLOptions struct {
	KeyToLower bool
}

YAMLOptions configuration for YAML parsing