sconf

Overview ¶

Package sconf parses simple configuration files and generates commented example config files.

Sconf is the name of this package and of the config file format. The file format is inspired by JSON and yaml, but easier to write and use correctly.

Sconf goals:

• Make the application self-documenting about its configuration requirements.
• Require full configuration of an application via a config file, finding mistakes by the operator.
• Make it easy to write a correct config file, no surprises.

Workflow for using this package:

• Write a Go struct with the config for your application.
• Simply parse a config into that struct with Parse() or ParseFile().
• Write out an example config file with all fields that need to be set with Describe(), and associated comments that you configured in struct tags.

Features of sconf as file format:

• Types similar to JSON, mapping naturally to types in programming languages.
• Requires far fewer type-describing tokens. no "" for map keys, strings don't require "", no [] for arrays or {} for maps (like in JSON). Sconf uses the Go types to guide parsing the config.
• Can have comments (JSON cannot).
• Is simple, does not allow all kinds of syntaxes you would not ever want to use.
• Uses indenting for nested structures (with the indent character).

An example config file:

# comment for stringKey (optional)
StringKey: value1
IntKey: 123
BoolKey: true
Struct:
	# this is the A-field
	A: 321
	B: true
	# (optional)
	C: this is text
StringArray:
	- blah
	- blah
# nested structs work just as well
Nested:
	-
		A: 1
		B: false
		C: hoi
	-
		A: -1
		B: true
		C: hallo

The top-level is always a map, typically parsed into a Go struct. Maps start with a key, followed by a colon, followed by a value. Basic values like strings, ints, bools run to the end of the line. The leading space after a colon or dash is removed. Other values like maps and lists start on a new line, with an additional level of indenting. List values start with a dash. Empty lines are allowed. Multiline strings are not possible. Strings do not have escaped characters.

And the struct that generated this:

var config struct {
	StringKey string `sconf-doc:"comment for stringKey" sconf:"optional"`
	IntKey    int64
	BoolKey   bool
	Struct    struct {
		A int `sconf-doc:"this is the A-field"`
		B bool
		C string `sconf:"optional"`
	}
	StringArray []string
	Nested      []struct {
		A int
		B bool
		C string
	} `sconf-doc:"nested structs work just as well"`
}

See cmd/sconfexample/main.go for more details.

In practice, you will mostly have nested maps:

Database:
	Host: localhost
	DBName: myapp
	User: myuser
Mail:
	SMTP:
		TLS: true
		Host: mail.example.org

Sconf only parses config files. It does not deal with command-line flags or environment variables. Flags and environment variables are too limiting in data types. Especially environment variables are error prone: Applications typically have default values they fall back to, so will not notice typo's or unrecognized variables. Config files also have the nice property of being easy to diff, copy around, store in a VCS. In practice, command-line flags and environment variables are commonly stored in config files. Sconf goes straight to the config files.