conf

README

====
conf
====

|image0|_ |image1|_ |image2|_

.. |image0| image:: https://godoc.org/github.com/eraclitux/conf?status.svg
.. _image0: https://godoc.org/github.com/eraclitux/conf

.. |image1| image:: https://travis-ci.org/eraclitux/conf.svg?branch=master
.. _image1: https://travis-ci.org/eraclitux/conf

.. |image2| image:: https://goreportcard.com/badge/github.com/eraclitux/conf
.. _image2: https://goreportcard.com/report/github.com/eraclitux/conf

.. contents::

Intro
=====
A go package for configuration parsing. Automagically populates a configuration ``struct`` using configuration files & command line arguments.

It aims to be modular and easily extendible to support other formats. Only INI format supported for now.

Usage and examples
==================
An example of utilization::

        type myConf struct {
                Address string
                Port    string
                // A command line flag "-users", which expects an int value,
                // will be created.
                // Same key name will be searched in configuration file.
                NumberOfUsers int `conf:"users,number of users,"`
                Daemon        bool
                Message       string
        }

        func Example() {
                // To create a dafault value for a flag
                // assign it when instantiate the conf struct.
                c := myConf{Message: "A default value"}
                conf.Path = "test_data/one.ini"
                err := conf.Parse(&c)
                if err != nil {
                        log.Fatal("Unable to parse configuration", err)
                }
                fmt.Println("address:", c.Address)
                fmt.Println("port:", c.Port)
                fmt.Println("number of users:", c.NumberOfUsers)
        }

See the flag arguments that are automagically created::

        go run main.go -h

See `godocs <http://godoc.org/github.com/eraclitux/conf>`_ for examples and documentation.

Pull requests that add new tests, features or fixes are welcome, encouraged, and credited.

Documentation

Overview

Package conf is a configuration parser that loads configuration in a struct from files and automatically creates cli flags.

Just define a struct with needed configuration. Values are then taken from multiple source in this order of precedence:

• command line arguments (which are automagically created and parsed)
• configuration file

Tags

Default is to use lower cased field names in struct to create command line arguments. Tags can be used to specify different names, command line help message and section in conf file.

Format is:

<name>,<help message>,<section in file>

Simplest configuration file

conf.Path variable can be set to the path of a configuration file. For default it is initialized to the value of environment variable:

CFGP_FILE_PATH

Files ending with:

ini|txt|cfg

will be parsed as INI informal standard:

https://en.wikipedia.org/wiki/INI_file

First letter of every key found is upper cased and than, a struct field with same name is searched:

user -> User
portNumber -> PortNumber

If such field name is not found than comparison is made against key specified as first element in tag.

conf tries to be modular and easily extensible to support different formats.

This is a work in progress, APIs can change.

Example

package main

import (
	"fmt"
	"log"

	"github.com/eraclitux/conf"
)

type myConf struct {
	Address string
	Port    string
	// A command line flag "-users", which expects an int value,
	// will be created.
	// Same key name will be searched in configuration file.
	NumberOfUsers int `conf:"users,number of users,"`
	Daemon        bool
	Message       string
}

func main() {
	// To create a dafault value for a flag
	// assign it when instantiate the conf struct.
	c := myConf{Message: "A default value"}
	conf.Path = "test_data/one.ini"
	err := conf.Parse(&c)
	if err != nil {
		log.Fatal("Unable to parse configuration", err)
	}
	fmt.Println("address:", c.Address)
	fmt.Println("port:", c.Port)
	fmt.Println("number of users:", c.NumberOfUsers)

}

Output:

address: localhost
port: 8080
number of users: 42

Index

• Variables
• func Parse(confPtr interface{}) error

Examples

• Package

Variables

var ErrFileFormat = errors.New("conf: unrecognized file format, only (ini|txt|cfg) supported")

var ErrNeedPointer = errors.New("conf: pointer to struct expected")

var ErrUnknownFlagType = errors.New("conf: unknown flag type")

var Path string

Path is the path to configuration file. For default is populated with env var CFGP_FILE_PATH. This could be left empty if no configuration file is needed.

Functions

func Parse

func Parse(confPtr interface{}) error

Parse populates passed struct (via pointer) with configuration from various source. It guesses configuration type by file extension and call specific parser. (.ini|.txt|.cfg) are evaluated as INI files which is to only format supported for now. path can be an empty string to disable file parsing.