aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--simpleconf.go40
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)
}