goconfig

README

goconfig

Tiered default/env/flag/json config loading in Go.

Installation

go get "github.com/LLKennedy/goconfig"

Forced Standards

This library assumes a few things about how you're loading and storing config. If you're not a fan of these assumptions, feel free to raise an issue, submit a pull request, fork the repository indefinitely, or just use a different config loading library.

Priority

You don't get to choose the order of priority. Defaults are used to begin, which are overwritten by environment variables, which are overwritten by values from a config file, which are overwritten by runtime executable flags.

Input Struct

The default struct can be used to load any value type supported by Go.

You must provide a pointer to a struct filled with default values. If you wish to load any fields from JSON or flags, you must tag these fields with JSON tags.

Environment Variables

Environment variables can only be used to load string and boolean values.

Environment variables are in the form APPNAME_FIELDNAME, where APPNAME is the all caps version of the application name passed into the Load function and FIELDNAME is the all caps version of a field in the struct passed into Load.

Config File Location

Config files can be used to load any value type supported by JSON.

Config files are located at %APPDATA%/AppName/config.json on windows, or ~/AppName/config.json on linux and mac. In this case, AppName is the exact case-sensitive name passed into Load.

Flag Formatting

Flags can only be used to load string and boolean values.

Flags must be in the form of matched string/interface pairs, which can be generated from the ParseArgs function. Flags passed into ParseArgs must be in matched pairs in the form -key value. Keys can be preceeded by any number of dashes, all of which will be stripped, except in the case of booleans. Boolean flags must be unpaired and may be followed immediately by another key so long as that key starts with at least two dashes. In this case the flag will be set to "true" and the next flag will be processed normally.

For example, the following line of args leads to the map below. -key1 value1 -key2 --key3 value3 ---key4 value4 -key5 --key6

map[string]interface{}{
    "key1": "value1",
    "key2": true,
    "key3": "value3",
    "key4": "value4",
    "key5": true,
    "key6": true,
}

Basic Usage

import "github.com/LLKennedy/goconfig"

// Use your custom config struct here
type myConfig struct{
    FieldA           string `json:"a"`
    FieldB           string `json:"b"`
    MoreComplexField string `json:"moreComplexString"`
}

...

config := myConfig {
    FieldA: "something",
    FieldB: "something else",
    MoreComplexFiled: "stuff",
}

// Leave nil to use defaults, results written to pointer
err := goconfig.Load(&config, "myApp", nil, nil, nil)

Testing

On windows, the simplest way to test is to use the powershell script.

./test.ps1

To emulate the testing which occurs in build pipelines for linux and mac, run the following:

go test ./... -race

Documentation

Index

• func DefaultConfigLocation(appName string) string
• func Load(defaults interface{}, appName string, flags map[string]interface{}, ...) (err error)
• func ParseArgs(args []string) map[string]interface{}

Functions

func DefaultConfigLocation

func DefaultConfigLocation(appName string) string

DefaultConfigLocation returns the expected config file location for a specific application.

func Load

func Load(defaults interface{}, appName string, flags map[string]interface{}, fs vfs.FileSystem, envAccess func(string) string) (err error)

Load loads the default config location on the provided file system, returning defaults for any keys not present in the config file. Options start as defaults, then load from environment variables, then a config file, then runtime flags, each overriding the previous.

func ParseArgs

func ParseArgs(args []string) map[string]interface{}

ParseArgs parses a list of strings as flags and values, assuming all remain as strings. It is assumed that you've already cleaned any OS wrapping of strings