iniflags

README

Hybrid configuration library

Combine standard go flags with ini files.

Usage:

go get -u -a github.com/vharitonsky/iniflags

main.go

package main

import (
	"flag"
	...
	"github.com/vharitonsky/iniflags"
	...
)

var (
	flag1 = flag.String("flag1", "default1", "Description1")
	...
	flagN = flag.Int("flagN", 123, "DescriptionN")
)

func main() {
	iniflags.Parse()  // use instead of flag.Parse()
}

dev.ini

    # comment1
    flag1 = "val1"  # comment2

    ...
    [section]
    flagN = 4  # comment3

    multilineFlag{,} = line1
    multilineFlag{,} = line2
    multilineFlag{|} = line3
    multilineFlag{} = line4
    # Now the multilineFlag equals to "line1,line2|line3line4"

go run main.go -config dev.ini -flagX=foobar

Now all unset flags obtain their value from .ini file provided in -config path. If value is not found in the .ini, flag will retain its' default value.

Flag value priority:

• value set via command-line
• value from ini file
• default value

Iniflags is compatible with real .ini config files with [sections] and #comments. Sections and comments are skipped during config file parsing.

Iniflags can #import another ini files. For example,

base.ini

flag1 = value1
flag2 = value2

dev.ini

# import "base.ini"
# Now flag1="value1", flag2="value2"

flag2 = foobar
# Now flag1="value1", while flag2="foobar"

Both -config path and imported ini files can be addressed via http or https links:

/path/to/app -config=https://google.com/path/to/config.ini

config.ini

# The following line will import configs from the given http link.
# import "http://google.com/path/to/config.ini"

All flags defined in the app can be dumped into stdout with ini-compatible sytax by passing -dumpflags flag to the app. The following command creates ini-file with all the flags defined in the app:

/path/to/the/app -dumpflags > initial-config.ini

Iniflags also supports two types of online config reload:

• Via SIGHUP signal:

kill -s SIGHUP <app_pid>

• Via -configUpdateInterval flag. The following line will re-read config every 5 seconds:

/path/to/app -config=/path/to/config.ini -configUpdateInterval=5s

Advanced usage.

package main

import (
	"flag"
	"iniflags"
	"log"
)

var listenPort = flag.Int("listenPort", 1234, "Port to listen to")

func init() {
	iniflags.OnFlagChange("listenPort", func() {
		startServerOnPort(*listenPort)
	})
}

func main() {
	// iniflags.Parse() starts the server on the -listenPort via OnFlagChange()
	// callback registered above.
	iniflags.Parse()
}

Documentation

Index

• Variables
• func OnFlagChange(flagName string, callback FlagChangeCallback)
• func Parse()
• func ReadIniFile(iniFilePath string) (args []flagArg, ok bool)
• func SetAllowMissingConfigFile(allowed bool)
• func SetAllowUnknownFlags(allowed bool)
• func SetConfigFile(path string)
• func SetConfigUpdateInterval(interval time.Duration)
• func SetLogger(l Logger)
• type FlagChangeCallback
• type Logger

Variables

var Generation int

Generation is flags' generation number.

It is modified on each flags' modification via either -configUpdateInterval or SIGHUP.

Functions

func OnFlagChange

func OnFlagChange(flagName string, callback FlagChangeCallback)

OnFlagChange registers the callback, which is called after the given flag value is initialized and/or changed.

Flag values are initialized during iniflags.Parse() call. Flag value can be changed on config re-read after obtaining SIGHUP signal or if periodic config re-read is enabled with -configUpdateInterval flag.

Note that flags set via command-line cannot be overriden via config file modifications.

func Parse

func Parse()

Parse obtains flag values from config file set via -config.

It obtains flag values from command line like flag.Parse(), then overrides them by values parsed from config file set via -config.

Path to config file can also be set via SetConfigFile() before Parse() call.

func ReadIniFile

func ReadIniFile(iniFilePath string) (args []flagArg, ok bool)

func SetAllowMissingConfigFile

func SetAllowMissingConfigFile(allowed bool)

func SetAllowUnknownFlags

func SetAllowUnknownFlags(allowed bool)

func SetConfigFile

func SetConfigFile(path string)

SetConfigFile sets path to config file.

Call this function before Parse() if you need default path to config file when -config command-line flag is not set.

func SetConfigUpdateInterval

func SetConfigUpdateInterval(interval time.Duration)

func SetLogger

func SetLogger(l Logger)

Types

type FlagChangeCallback

type FlagChangeCallback func()

FlagChangeCallback is called when the given flag is changed.

The callback may be registered for any flag via OnFlagChange().

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
	Fatalf(format string, v ...interface{})
	Panicf(format string, v ...interface{})
}

Logger is a slimmed-down version of the log.Logger interface, which only includes the methods we use. This interface is accepted by SetLogger() to redirect log output to another destination.