package module
Version: v1.5.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Aug 28, 2021 License: Apache-2.0 Imports: 12 Imported by: 55




Copyright 2018, 2019, 2020, 2021, Ardan Labs


Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

About The Project

Package conf provides support for using environmental variables and command line arguments for configuration.

All of the documentation can be found on the website.



Package conf provides support for using environmental variables and command line arguments for configuration.

It is compatible with the GNU extensions to the POSIX recommendations for command-line options. See

There are no hard bindings for this package. This package takes a struct value and parses it for both the environment and flags. It supports several tags to customize the flag options.

default  - Provides the default value for the help
env      - Allows for overriding the default variable name.
flag     - Allows for overriding the default flag name.
short    - Denotes a shorthand option for the flag.
noprint  - Denotes to not include the field in any display string.
mask     - Includes the field in any display string but masks out the value.
required - Denotes a value must be provided.
help     - Provides a description for the help.

The field name and any parent struct name will be used for the long form of the command name unless the name is overridden.

As an example, this config struct:

type ip struct {
	Name string `conf:"default:localhost,env:IP_NAME_VAR"`
	IP   string `conf:"default:"`
type Embed struct {
	Name     string        `conf:"default:bill"`
	Duration time.Duration `conf:"default:1s,flag:e-dur,short:d"`
type config struct {
	AnInt   int    `conf:"default:9"`
	AString string `conf:"default:B,short:s"`
	Bool    bool
	Skip    string `conf:"-"`
	IP      ip

Would produce the following usage output:

Usage: conf.test [options] [arguments]


--an-int/$CRUD_AN_INT         <int>       (default: 9)
--a-string/-s/$CRUD_A_STRING  <string>    (default: B)
--bool/$CRUD_BOOL             <bool>
--ip-name/$CRUD_IP_NAME_VAR   <string>    (default: localhost)
--ip-ip/$CRUD_IP_IP           <string>    (default:
--name/$CRUD_NAME             <string>    (default: bill)
--e-dur/-d/$CRUD_DURATION     <duration>  (default: 1s)
display this help message
display version information

The API is a single call to Parse

// Parse(args []string, namespace string, cfgStruct interface{}, sources ...Sourcer) error

if err := conf.Parse(os.Args, "CRUD", &cfg); err != nil {
	log.Fatalf("main : Parsing Config : %v", err)

Additionally, if the config struct has a field of the slice type conf.Args then it will be populated with any remaining arguments from the command line after flags have been processed.

For example a program with a config struct like this:

var cfg struct {
	Port int
	Args conf.Args

If that program is executed from the command line like this:

$ my-program --port=9000 serve http

Then the cfg.Args field will contain the string values ["serve", "http"]. The Args type has a method Num for convenient access to these arguments such as this:

arg0 := cfg.Args.Num(0) // "serve"
arg1 := cfg.Args.Num(1) // "http"
arg2 := cfg.Args.Num(2) // "" empty string: not enough arguments

You can add a version with a description by adding the Version type to your config type

type ConfExplicit struct {
	Version conf.Version
	Address string

type ConfImplicit struct {
	Address string

Then you can set these values at run time for display.

cfg := struct {
	Version conf.Version
	Version: conf.Version{
		SVN:  "v1.0.0",
		Desc: "Service Description",

if err := conf.Parse(os.Args[1:], "APP", &cfg); err != nil {
	if err == conf.ErrVersionWanted {
		version, err := conf.VersionString("APP", &cfg)
		if err != nil {
			return err
		return nil
	fmt.Println("parsing config", err)




This section is empty.


View Source
var ErrHelpWanted = errors.New("help wanted")

ErrHelpWanted provides an indication help was requested.

View Source
var ErrInvalidStruct = errors.New("configuration must be a struct pointer")

ErrInvalidStruct indicates that a configuration struct is not the correct type.

View Source
var ErrVersionWanted = errors.New("version wanted")

ErrVersionWanted provides an indication version was requested.


func Parse

func Parse(args []string, namespace string, cfgStruct interface{}, sources ...Sourcer) error

Parse parses configuration into the provided struct.

func ParseOSArgs added in v1.5.0

func ParseOSArgs(prefix string, cfg interface{}) (string, error)

ParseOSArgs parses the configuration allowing command line arguments to override settings. Function returns ErrHelpWanted for any information to be provided to the user.

func String

func String(v interface{}) (string, error)

String returns a stringified version of the provided conf-tagged struct, minus any fields tagged with `noprint`.

package main

import (


type ip struct {
	Name      string   `conf:"default:localhost,env:IP_NAME_VAR"`
	IP        string   `conf:"default:"`
	Endpoints []string `conf:"default:;"`
type Embed struct {
	Name     string        `conf:"default:bill"`
	Duration time.Duration `conf:"default:1s,flag:e-dur,short:d"`
type config struct {
	AnInt     int    `conf:"default:9"`
	AString   string `conf:"default:B,short:s"`
	Bool      bool
	Skip      string `conf:"-"`
	IP        ip
	DebugHost string `conf:"default:http://user:password@,mask"`
	Password  string `conf:"default:password,mask"`

func main() {
	tt := struct {
		name string
		envs map[string]string
		name: "one-example",
		envs: map[string]string{"TEST_AN_INT": "1", "TEST_S": "s", "TEST_BOOL": "TRUE", "TEST_SKIP": "SKIP", "TEST_IP_NAME": "local", "TEST_NAME": "andy", "TEST_DURATION": "1m"},

	for k, v := range tt.envs {
		os.Setenv(k, v)

	var cfg config
	if err := conf.Parse(nil, "TEST", &cfg); err != nil {

	out, err := conf.String(&cfg)
	if err != nil {




func Usage

func Usage(namespace string, v interface{}) (string, error)

Usage provides output to display the config usage on the command line.

func VersionString added in v1.3.2

func VersionString(namespace string, v interface{}) (string, error)

VersionString provides output to display the application version and description on the command line.


type Args

type Args []string

Args holds command line arguments after flags have been parsed.

func (Args) Num

func (a Args) Num(i int) string

Num returns the i'th argument in the Args slice. It returns an empty string the request element is not present.

type Field added in v1.2.0

type Field struct {
	Name    string
	FlagKey []string
	EnvKey  []string
	Field   reflect.Value
	Options FieldOptions

	// Important for flag parsing or any other source where
	// booleans might be treated specially.
	BoolField bool

Field maintains information about a field in the configuration struct.

type FieldError

type FieldError struct {
	// contains filtered or unexported fields

A FieldError occurs when an error occurs updating an individual field in the provided struct value.

func (*FieldError) Error

func (err *FieldError) Error() string

type FieldOptions added in v1.2.0

type FieldOptions struct {
	Help          string
	DefaultVal    string
	EnvName       string
	FlagName      string
	ShortFlagChar rune
	Noprint       bool
	Required      bool
	Mask          bool

FieldOptions maintain flag options for a given field.

type Setter

type Setter interface {
	Set(value string) error

Setter is implemented by types can self-deserialize values. Any type that implements flag.Value also implements Setter.

type Sourcer

type Sourcer interface {

	// Source takes the field key and attempts to locate that key in its
	// configuration data. Returns true if found with the value.
	Source(fld Field) (string, bool)

Sourcer provides the ability to source data from a configuration source. Consider the use of lazy-loading for sourcing large datasets or systems.

type Version added in v1.3.0

type Version struct {
	SVN  string
	Desc string

Version provides the abitily to add version and description to the application.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL