staert

README

Stært

Stært is a Go library for loading and merging a program configuration structure from many sources.

Overview

Stært was born in order to merge two sources of Configuration (Flæg, Toml). We developed flaeg and staert in order to simplify configuration maintenance on traefik.

Features

• Load your Configuration structure from many sources
• Keep your Configuration structure values unchanged if no overwriting (support defaults values)
• Two native sources :
  • Flæg
  • Toml
• An Interface to add your own sources
• Handle pointers field :
  • You can give a structure of default values for pointers
  • Same comportment as Flæg
• Stært is Command oriented
  • It use flaeg.Command
  • Same comportment as Flæg commands

Getting Started

The configuration

It works on your own Configuration structure, like this one :

package example

import (
	"fmt"
	"github.com/containous/flaeg"
	"github.com/containous/staert"
	"os"
)

//Configuration is a struct which contains all differents type to field
type Configuration struct {
	IntField     int                      `description:"An integer field"`
	StringField  string                   `description:"A string field"`
	PointerField *PointerSubConfiguration `description:"A pointer field"`
}

//PointerSubConfiguration is a SubStructure Configuration
type PointerSubConfiguration struct {
	BoolField  bool    `description:"A boolean field"`
	FloatField float64 `description:"A float field"`
}

Let's initialize it:

 func main() {
	//Init with default value
	config := &Configuration{
		IntField:    1,
		StringField: "init",
		PointerField: &PointerSubConfiguration{
			FloatField: 1.1,
		},
	}
	//Set default pointers value
	defaultPointersConfig := &Configuration{
		PointerField: &PointerSubConfiguration{
			BoolField:  true,
			FloatField: 99.99,
		},
	}

The command

Stært uses flaeg.Command Structure, like this :

    //Create Command
    command:=&flaeg.Command{
        Name:"example",
        Description:"This is an example of description",
        Config:config,
        DefaultPointersConfig:defaultPointersConfig,
        Run: func() error {
            fmt.Printf("Run example with the config :\n%+v\n",config)
 			fmt.Printf("PointerField contains:%+v\n", config.PointerField)
            return nil
        }
    }

Use stært with sources

Init Stært

    s:=staert.NewStaert(command)

Init TOML source

     toml:=staert.NewTomlSource("example", []string{"./toml/", "/any/other/path"})

Init Flæg source

     f:=flaeg.New(command, os.Args[1:])

Add sources

Add TOML and flæg sources

    s.AddSource(toml)
    s.AddSource(f)

NB : You can change order, so that, flaeg configuration will overwrite toml one

Load your configuration

Just call LoadConfig function :

	loadedConfig, err := s.LoadConfig();
    if err != nil {
		//OOPS
	}
	//DO WATH YOU WANT WITH loadedConfig 
	//OR CALL RUN FUNC

You can call Run

Run function will call the func run() from the command :

    if err := s.Run(); err != nil {
		//OOPS
	}
 }

NB : If you didn't call LoadConfig() before, your func run() will use your original configuration

Let's run example

TOML file ./toml/example.toml :

IntField= 2
[PointerField]

We can run the example program using folowing CLI arguments :

$ ./example --stringfield=owerwrittenFromFlag --pointerfield.floatfield=55.55
Run example with the config :
&{IntField:2 StringField:owerwrittenFromFlag PointerField:0xc82000ec80}
PointerField contains:&{BoolField:true FloatField:55.55}

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Documentation

Index

• type Source
• type Staert
  • func NewStaert(rootCommand *flaeg.Command) *Staert
  • func (s *Staert) AddSource(src Source)
  • func (s *Staert) LoadConfig() (interface{}, error)
  • func (s *Staert) Run() error
• type TomlSource
  • func NewTomlSource(filename string, dirNfullpath []string) *TomlSource
  • func (ts *TomlSource) ConfigFileUsed() string
  • func (ts *TomlSource) Parse(cmd *flaeg.Command) (*flaeg.Command, error)

Types

type Source

type Source interface {
	Parse(cmd *flaeg.Command) (*flaeg.Command, error)
}

Source interface must be satisfy to Add any kink of Source to Staert as like as TomlFile or Flaeg

type Staert

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

Staert contains the struct to configure, thee default values inside structs and the sources

func NewStaert

func NewStaert(rootCommand *flaeg.Command) *Staert

NewStaert creats and return a pointer on Staert. Need defaultConfig and defaultPointersConfig given by references

func (*Staert) AddSource

func (s *Staert) AddSource(src Source)

AddSource adds new Source to Staert, give it by reference

func (*Staert) LoadConfig

func (s *Staert) LoadConfig() (interface{}, error)

LoadConfig check which command is called and parses config It returns the the parsed config or an error if it fails

func (*Staert) Run

func (s *Staert) Run() error

Run calls the Run func of the command Warning, Run doesn't parse the config

type TomlSource

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

TomlSource impement Source

func NewTomlSource

func NewTomlSource(filename string, dirNfullpath []string) *TomlSource

NewTomlSource creats and return a pointer on TomlSource. Parameter filename is the file name (without extension type, ".toml" will be added) dirNfullpath may contain directories or fullpath to the file.

func (*TomlSource) ConfigFileUsed

func (ts *TomlSource) ConfigFileUsed() string

ConfigFileUsed return config file used

func (*TomlSource) Parse

func (ts *TomlSource) Parse(cmd *flaeg.Command) (*flaeg.Command, error)

Parse calls Flaeg Load Function