configo

README

Configo

Configo is a go library to parse toml configuration using struct tags

Features

• Configuring parser behaviour using struct tags
• Setting default value or as required
• Validating value using regex, range expression or named validator
• Generating toml template with human friendly information based on go struct and tags
• Building conf file generation tools using configo-build

Toml

shafreeck/toml is a modification version of naoina/toml, adding the abililty to parse complex struct tags and with bugs fixed.

Validation

configo has a builtin validator with regex and range support

> 1 //greater than 1
>=1 //greater than or equal to 1
>1 <10 //greater than 1 and less than 10, space indicates the "and" of rules

(1, ) //range expression, same as >1
(1, 10) // >1 <10
(1,10]  // >1 <=10

/[0-9]/ //regex matching

/[0-9]+/ (1, 10) // the value should satisfy both the regex and range expression

netaddr //named validator, used to validate a network address
numeric  >10 ( ,100)// mix different expressions, 'and' is used to combine all expressions

See the source code for all valid "named validators"

Struct tags

tags has a key 'cfg' and its value consists of four parts: "name; default value or required; rule; descripion". All four parts are splited by ";".

For example:

Listen `cfg:"listen; :8804; netaddr; The listen address of server"`

It looks like this when being marshaled to toml

#type:        string
#rules:       netaddr
#description: The listen address of server
#default:     :8804
#listen=":8804"

You can see that we have rich information about the option. And the option is commented out too because it has a default value.

configo-build

Configo comes with a util tool called configo-build to build a configration file generator for you.

You can use the generator to generate your toml file or update it when you changed your source code(the configuration struct).

configo-build ./conf.Config
#build a conf generator, the format of arg is "package.struct" package can be
#absolute or relative(golang takes it as an absolute package if it is without
#the prefix "./" or "../").

#the built program has a name with format:<package>.<struct>.cfg, for example
#"conf.config.cfg"

Generating your configuration file with the built generator

conf.config.cfg > conf.toml #generating
conf.config.cfg -patch conf.toml #updating if conf.toml has already existed

Example

Define a struct in package conf

package conf

type Config struct {
        Listen  string `cfg:"listen; :8804; netaddr; The address the server to listen"`
        MaxConn int    `cfg:"max-connection; 10000; numeric; Max number of concurrent connections"`
        Redis   struct {
                Cluster []string `cfg:"cluster; required; dialstring; The addresses of redis cluster"`
        }
}

Build the configuration file generator

First, install configo-build

go get github.com/shafreeck/configo/bin/configo-build

Then, build an executable program basing on your package and struct

configo-build ./conf.Config

or use the absolute path

configo-build github.com/shafreeck/configo/example/conf.Config

Finally, use the built program to generate a toml

conf.config.cfg > conf.toml

and you can patch you toml file if it is already existed

conf.config.cfg -patch conf.toml

Output

#type:        string
#rules:       netaddr
#description: The address the server to listen
#default:     :8804
#listen = ":8804"

#type:        int
#rules:       numeric
#description: Max number of concurrent connections
#default:     10000
#max-connection = 10000

[redis]

#type:        []string
#rules:       dialstring
#description: The addresses of redis cluster
#required
cluster = []

Documentation

Overview

Package configo is designed to handle configuration more easier.

Writing and parsing configuration is very easy with configo, there is not any pain to add more keys in conf because configo can generate the configuration file based on your struct definition.

Examples

Define struct with tags `cfg`

type Config struct {
	Listen  string `cfg:"listen; :8804; netaddr; The address the server to listen"`
	MaxConn int    `cfg:"max-connection; 10000; numeric; Max number of concurrent connections"`
	Redis   struct {
		Cluster []string `cfg:"cluster; required; dialstring; The addresses of redis cluster"`
	}
}

Marshal to configuration

c := conf.Config{}

data, err := configo.Marshal(c)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(string(data))

Unmarshal from file

c := &conf.Config{}

data, err := ioutil.ReadFile("conf/example.toml")
if err != nil {
		log.Fatalln(err)
}

err = configo.Unmarshal(data, c)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(c)

Dump to file

c := conf.Config{}

if err := configo.Dump("dump.toml", c); err != nil {
		log.Fatalln(err)
}
log.Println("Dumpped to dump.toml")

The dumpped content is configuration friendly like this

#type:        string
#rules:       netaddr
#description: The address the server to listen
#default:     :8804
#listen = ":8804"

#type:        int
#rules:       numeric
#description: Max number of concurrent connections
#default:     10000
#max-connection = 10000

[redis]

#type:        []string
#rules:       dialstring
#required
cluster = []

Load from file

c := &conf.Config{}

if err := configo.Load("conf/example.toml", c); err != nil {
		log.Fatalln(err)
}
log.Println(c)

Update an exist file This is really useful when you add new member of struct and want to preserve the content of your configuration file.

c := conf.Config{}

if err := configo.Update("conf/example.toml", c); err != nil {
	log.Fatalln(err)
}
log.Println("Update conf/example.toml with new struct")

Configo comes along with a command tool to help to generate and update configuration file for you.

Build a generator with configo-build

configo-build github.com/shafreeck/configo/example/conf.Config

or use relative package path if you are under configo directory

configo-build ./example/conf.Config

Run the built program(name with format "<package>.<struct>.cfg")

conf.config.cfg > example.toml

Update example.toml when you have updated struct conf.Configo

conf.config.cfg -patch example.toml

Index

• func Dump(file string, v interface{}) error
• func Load(file string, v interface{}) error
• func Marshal(v interface{}) ([]byte, error)
• func Patch(base []byte, v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• func Update(file string, v interface{}) error
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v interface{}) error

Functions

func Dump

func Dump(file string, v interface{}) error

Dump the object to file in toml format

func Load

func Load(file string, v interface{}) error

Load toml file and unmarshal to v, v shoud be a pointer

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal v to configuration in toml format

func Patch

func Patch(base []byte, v interface{}) ([]byte, error)

Patch the base using the value from v, the new bytes returned combines the base's value and v's default value

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal data into struct v, v shoud be a pointer to struct

func Update

func Update(file string, v interface{}) error

Update an exist file

Types

type Decoder

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

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) error

type Encoder

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

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

func (*Encoder) Encode

func (e *Encoder) Encode(v interface{}) error