diff options
| -rw-r--r-- | simpleconf.go | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/simpleconf.go b/simpleconf.go index ad13f11..3dd6ef6 100644 --- a/simpleconf.go +++ b/simpleconf.go @@ -1,3 +1,27 @@ +// Package simpleconf implements a parser for a very simple configuration file format. +// +// The format is inspired by INI files. A file consists of lines. A line is one of: +// +// Comment: The Line starts with an '#', or an ';'. Comments can only be on their own line. +// +// Section header: A section header names the current section. The Section named is wrapped in '[' and ']'. +// Section names must not be empty. +// +// Key-Value Pair: A value assigned to a key. The pair must belong to a section. +// Key and value are separated by '='. Everything after the '=' is the value. +// Keys must not be empty. +// Leading and trailing whitespace in key and value will be deleted. +// +// Example: +// +// [foo] +// test = Hello, World! +// answer = 42 +// +// ; I am a comment. +// # I am also a comment +// [bar] +// trololo = bla.. ; I am NOT A comment, I belong to value bar.trololo! package simpleconf import ( @@ -10,6 +34,7 @@ import ( "strings" ) +// Config contains a loaded config file. You can access the values by simply using the map or by using the `Get...` functions. type Config map[string]Section type Section map[string]string @@ -19,6 +44,10 @@ func (c Config) addSection(section Section, name string) { } } +// Load loads a config file. See package description for the file format. +// +// If outerr != nil, either an I/O error occurred, or the file was not a valid config file. +// In both cases, the error will describe what went wrong. func Load(r io.Reader) (config Config, outerr error) { config = make(Config) scanner := bufio.NewScanner(r) @@ -78,11 +107,13 @@ func Load(r io.Reader) (config Config, outerr error) { return } +// Errors of the `Get...` functions. var ( NotFound = errors.New("Section or key not found.") NotBool = errors.New("Could not interpret value as bool.") ) +// GetString gets the string assigned to [section] key. It will return NotFound, if no such key exists. func (c Config) GetString(section, key string) (string, error) { s, ok := c[section] if !ok { @@ -95,6 +126,7 @@ func (c Config) GetString(section, key string) (string, error) { return rv, nil } +// GetStringDefault is like GetString, but will return d, if the key was not found. func (c Config) GetStringDefault(d, section, key string) (string, error) { rv, err := c.GetString(section, key) if err == NotFound { @@ -103,6 +135,7 @@ func (c Config) GetStringDefault(d, section, key string) (string, error) { return rv, err } +// GetInt is like GetString, but will additionally parse the value as an integer. See strconv.ParseInt for possible errors. func (c Config) GetInt(section, key string) (int64, error) { s, err := c.GetString(section, key) if err != nil { @@ -119,6 +152,7 @@ func (c Config) GetIntDefault(d int64, section, key string) (int64, error) { return rv, err } +// GetFloat is like GetString, but will additionally parse the value as a float. See strconv.ParseFloat for possible errors. func (c Config) GetFloat(section, key string) (float64, error) { s, err := c.GetString(section, key) if err != nil { @@ -135,6 +169,9 @@ func (c Config) GetFloatDefault(d float64, section, key string) (float64, error) return rv, err } +// GetBool is like GetString, but will additionally parse the value as a boolean value. +// +// true, on, yes, y and 1 are all true, false, off, no, n, 0 are all false. Other values will result in a NotBool error. func (c Config) GetBool(section, key string) (bool, error) { s, err := c.GetString(section, key) if err != nil { @@ -158,6 +195,8 @@ func (c Config) GetBoolDefault(d bool, section, key string) (bool, error) { return rv, err } +// GetFile is like GetString, but will additionally open the file with that name. +// See os.OpenFile for flag and perm values and additional error values. func (c Config) GetFile(flag int, perm os.FileMode, section, key string) (*os.File, error) { s, err := c.GetString(section, key) if err != nil { @@ -167,6 +206,7 @@ func (c Config) GetFile(flag int, perm os.FileMode, section, key string) (*os.Fi return os.OpenFile(s, flag, perm) } +// GetFileReadonly is like GetFile, but with default values for flag and perm that will open the file in read-only mode. func (c Config) GetFileReadonly(section, key string) (*os.File, error) { return c.GetFile(os.O_RDONLY, 0, section, key) } |