mirror of
https://github.com/mjl-/mox.git
synced 2025-07-10 08:34:40 +03:00
mox!
This commit is contained in:
106
vendor/github.com/mjl-/sconf/doc.go
generated
vendored
Normal file
106
vendor/github.com/mjl-/sconf/doc.go
generated
vendored
Normal file
@ -0,0 +1,106 @@
|
||||
/*
|
||||
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
|
Reference in New Issue
Block a user