mirror of
https://github.com/mjl-/mox.git
synced 2024-12-28 17:33:47 +03:00
106 lines
3.3 KiB
Go
106 lines
3.3 KiB
Go
/*
|
|
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.
|
|
*/
|
|
package sconf
|