From 7bbafcbda3208529b093b97a58b6c61ccd561d66 Mon Sep 17 00:00:00 2001
From: Kevin Chabowski <kevin@kch42.de>
Date: Sat, 29 Jun 2013 13:23:31 +0200
Subject: Some documentation.

---
 simpleconf.go | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

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)
 }
-- 
cgit v1.2.3-70-g09d2