package module
v0.0.7 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jun 10, 2024 License: MIT Imports: 12 Imported by: 9


sconf - simple config files

See for documentation.

# todo
- deal better with unexpected types. need to use canset?



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
	# this is the A-field
	A: 321
	B: true
	# (optional)
	C: this is text
	- blah
	- blah
# nested structs work just as well
		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:

	Host: localhost
	DBName: myapp
	User: myuser
		TLS: true

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.



This section is empty.


This section is empty.


func Describe

func Describe(w io.Writer, v interface{}) error

Describe writes an example sconf file describing v to w. The file includes all fields, values and documentation on the fields as configured with the "sconf" and "sconf-doc" struct tags. Describe does not detect recursive values and will attempt to write them.

func Parse

func Parse(src io.Reader, dst interface{}) error

Parse reads an sconf file from a reader into dst.

func ParseFile

func ParseFile(path string, dst interface{}) error

ParseFile reads an sconf file from path into dst.

func Write

func Write(w io.Writer, v interface{}) error

Write writes a valid sconf file describing v to w, without comments, without zero values of optional fields. Write does not detect recursive values and will attempt to write them.

func WriteDocs added in v0.0.2

func WriteDocs(w io.Writer, v interface{}) error

WriteDocs is like Write, but does write comments.


This section is empty.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL