drewoko / comfyconf Goto Github PK

#ComfyConf

Yet another configuration framework for GO, inspired by different existing frameworks and with additional functionality, like parsing arrays, parameter existence and structure assembly. This framework uses middleware conception for allowing to make complex applications with different configuration sources.

Note! This library is not production ready, API may change soon.

• Simple in use, API is quite similar to standard flags library
• Middleware model with already existing JSON, Command Line (flags) and Environment middlewares
• Parsing strings, integers, booleans and slices from configuration sources
• Parameter existence in middleware
• Custom help printer

For downloading latest version:

go get github.com/drewoko/comfyconf

gopkg.in link will be available when API will be freezed.

For creating ComfyConf instance need to call New function from package, defining middlewares.

conf := comfyconf.New(comfyconf.NewFlags(), comfyconf.NewEnv())

alternatively middlewares can be defined separately by calling AddMiddleware

conf.AddMiddleware(comfyconf.NewFlags())

For performing parameter parsing, need to call Parse function after parameter declaration.

conf := comfyconf.New(comfyconf.NewFlags(), comfyconf.NewEnv())
//Parameter declaration here
conf.Parse()

ComfyConf package have four types for configuration variables. These are Integer, String, Boolean and Interface Slice. For all variable types are two methods of declaration - declaration with passing existing variable or declaration with variable creation.

They have similar declaration signature (Except Existence)

val := conf.TYPE("shortName", "fullName", defaultValue, "Description string, that can be used for printing help")

or if you want to use own variable then

var type TYPE
conf.TYPEVar("shortName", "fullName", defaultValue, &type, "Description string, that can be used for printing help")

intParam := conf.Int("short", "FullName", 10, "Description for that parameter")

or

var intParam int
conf.IntVar("short", "FullName", 10, &intParam, "Description for that parameter")

strParam := conf.String("short", "FullName", "Default String", "Description for that parameter")

or

var strParam string
conf.StringVar("short", "FullName", "Default String", &strParam, "Description for that parameter")

boolParam := conf.Bool("short", "FullName", true, "Description for that parameter")

or

var boolParam bool
conf.BoolVar("short", "FullName", true, &boolParam, "Description for that parameter")

sliceParam := conf.Slice("short", "FullName", make([]interface{}, 0), "Description for that parameter")

or

var sliceParam []interface{}
conf.SliceVar("short", "FullName", make([]interface{}, 0), &sliceParam, "Description for that parameter")

Parameter that returns true if parameter with selected name exists in configuration source

boolParam := conf.Exist("short", "FullName", "Description for that parameter")

or

var boolParam bool
conf.ExistVar("short", "FullName", &boolParam, "Description for that parameter")

All middlewares should implement Middleware interface, so you can make own middleware.

Order of adding middlewares is important. Latest added middleware have higher priority. That means that if same parameter exists for Env and Flags, and Flags is defined last, then value will be taken from Flags middleware.

Command line flags middleware are Flags struct, that implements Middleware interface. For making developers life easier we have functions that prepares struct for work.

NewFlags()

will make Flags struct with = assignment, what means that --full=Test -s=t will be parsed.

NewFlagsWithCustomAssignment(" ")

Same NewFlags, but with custom assignment, which makes possible to parse --full=val -s val flags.

NewFlagsWithCustomParser(func(arg string) (string, string) {
    return "key", "value"
})

Another possibility for command line flags parsing. You can provide own function, that will parameter one by one returning key-value pair.

Environment middleware are Env struct, that implements Middleware interface.

NewEnv()

will return Environment middleware with ENV_ prefix for environment parameters. That means, all environment parameters with name starting on ENV_ will be taken in account.

For setting custom prefix function NewEnvWithPrefix can be used.

NewEnvWithPrefix("TEST_")

JSON middleware (struct) allows to read configuration parameters from JSON files. FullName in that environment is used as JSON path.

For example we have JSON

{
  "level1": {
    "level2": "Value"
  }
}

then full name (path) to "Value" in json will be level1.level2 and short name will be level2.

For creating JSON middleware with predefined path NewJSON function should be used

NewJSON("path/to/config.json")

Also can be provided custom file reader using NewJSONWithCustomReader. It receives function, that returns tuple with byte array and error.

NewJSONWithCustomReader(func(j *JSON) ([]byte, error) {
    return []byte(`
        {}
    `), nil
})

NewJSONWithCustomFileMiddleware powerful function, that receives middlewares, that used for obtaining JSON configuration path.

NewJSONWithCustomFileMiddleware("shortName", "fullName", "/path/to/config.json", NewFlags(), NewEnv())

Library tries to map configuration parameters to predefined struct using comfyname tag by it value. It can work with referenced and with direct values.

var testStruct struct {
    TestString string        `comfyname:"test"`
    TestPrtString *string    `comfyname:"t2"`
}

conf := comfyconf.New(comfyconf.NewFlags(), comfyconf.NewEnv())

conf.String("t", "test", "", "Basic description")
conf.String("t2", "test2", "", "Basic description")

conf.ToStruct(&testStruct)

Function for printing help. It receives function, that get as parameter options map[OptionKey]*Option. ComfyConf have default help printer called DefaultHelpPrinter

conf.PrintHelp(DefaultHelpPrinter)