README
¶
Go Settings in YAML
The go-settings library implements a settings library on top of YAML. It is meant to provide ease of use without resorting to type conversions and custom YAML parsing.
Usage
The library provides two functions for reading settings from YAML: Read and
Load. The Read function reads data from an io.Reader instance while the
Load function will load data from the provided file path.
Using Read:
import (
"fmt"
"github.com/BlueDragonX/go-settings"
"os"
)
var file *os.File
var err error
var s *settings.Settings
if file, err = os.Open; err != nil {
fmt.Println(err)
os.Exit(1)
}
if s, err = settings.Read(rdr); err != nil {
fmt.Println(err)
os.Exit(1)
}
fmt.Println("got settings from reader")
Using Load:
import (
"fmt"
"github.com/BlueDragonX/go-settings"
"os"
)
if s, err = settings.Load("settings.yml"); if err == nil {
fmt.Println(err)
os.Exit(1)
}
fmt.Println("got settings from file")
There is also LoadOrExit which does not return an error. It will call Load
and if it fails will print the error to stderr and exit. For example:
import (
"fmt"
"github.com/BlueDragonX/go-settings"
)
s = settings.LoadOrExit("settings.yml")
fmt.Println("got settings from file")
There are a handful of methods on the settings object which can be used to retrieve values. All methods take a key string as the first argument. The key string itself is a dot (.) separated list of object names. The different methods will handle conversion to different types. With a few exceptions they are self explanatory. These methods are:
Raw: Return the raw value as an interface{}.Object: Return a settings object.ObjectArray: Return an array of settings objects.ObjectMap: Return a string index map of settings objects.StringStringArrayStringMapIntIntArrayIntMapFloatFloatArrayFloatMapBoolBoolArrayBoolMap
The get methods may return a predefined error value to indicate failure. These are:
KeyError: The key was not found.TypeError: Conversion to the requested type failed.
Each get method has a corresponding Dflt method which takes a second
parameter containing a default value to return should an error occur. You may
append Dflt to the name of any get function
for this functionality.
There are two methods used to set values. They will replace any values at the provide key with the ones provided. Both objects and arrays are supported. These are:
Set: Set an object key to the provided value.Append: Append a value to the array at the given key.Delete: Delete a value at the given key.
Thee set methods may return a predefined error value to indicate failure. These are:
ObjectError: A child object has an invalid type.IndexError: A key cannot be converted to an integer for a child array.RangeError: The index is out of range for a child array.
License
Copyright (c) 2014 Ryan Bourgeois. Licensed under BSD-Modified. See the LICENSE file for a copy of the license.
Documentation
¶
Index ¶
- Variables
- func ParseSize(s string) (int64, error)
- type Settings
- func (s *Settings) Append(key string, value interface{}) error
- func (s *Settings) Bool(key string) (bool, error)
- func (s *Settings) BoolArray(key string) ([]bool, error)
- func (s *Settings) BoolArrayDflt(key string, dflt []bool) []bool
- func (s *Settings) BoolDflt(key string, dflt bool) bool
- func (s *Settings) BoolMap(key string) (map[string]bool, error)
- func (s *Settings) BoolMapDflt(key string, dflt map[string]bool) map[string]bool
- func (s *Settings) Delete(key string) error
- func (s *Settings) Duration(key string) (time.Duration, error)
- func (s *Settings) DurationArray(key string) ([]time.Duration, error)
- func (s *Settings) DurationArrayDflt(key string, dflt []time.Duration) []time.Duration
- func (s *Settings) DurationDflt(key string, dflt time.Duration) time.Duration
- func (s *Settings) DurationMap(key string) (map[string]time.Duration, error)
- func (s *Settings) DurationMapDflt(key string, dflt map[string]time.Duration) map[string]time.Duration
- func (s *Settings) Float(key string) (float64, error)
- func (s *Settings) FloatArray(key string) ([]float64, error)
- func (s *Settings) FloatArrayDflt(key string, dflt []float64) []float64
- func (s *Settings) FloatDflt(key string, dflt float64) float64
- func (s *Settings) FloatMap(key string) (map[string]float64, error)
- func (s *Settings) FloatMapDflt(key string, dflt map[string]float64) map[string]float64
- func (s *Settings) Has(key string) bool
- func (s *Settings) Int(key string) (int, error)
- func (s *Settings) IntArray(key string) ([]int, error)
- func (s *Settings) IntArrayDflt(key string, dflt []int) []int
- func (s *Settings) IntDflt(key string, dflt int) int
- func (s *Settings) IntMap(key string) (map[string]int, error)
- func (s *Settings) IntMapDflt(key string, dflt map[string]int) map[string]int
- func (s *Settings) Object(key string) (*Settings, error)
- func (s *Settings) ObjectArray(key string) ([]*Settings, error)
- func (s *Settings) ObjectArrayDflt(key string, dflt []*Settings) []*Settings
- func (s *Settings) ObjectDflt(key string, dflt *Settings) *Settings
- func (s *Settings) ObjectMap(key string) (map[string]*Settings, error)
- func (s *Settings) ObjectMapDflt(key string, dflt map[string]*Settings) map[string]*Settings
- func (s *Settings) Raw(key string) (interface{}, error)
- func (s *Settings) RawDflt(key string, dflt interface{}) interface{}
- func (s *Settings) Set(key string, value interface{}) error
- func (s *Settings) Size(key string) (int64, error)
- func (s *Settings) SizeArray(key string) ([]int64, error)
- func (s *Settings) SizeArrayDflt(key string, dflt []int64) []int64
- func (s *Settings) SizeDflt(key string, dflt int64) int64
- func (s *Settings) SizeMap(key string) (map[string]int64, error)
- func (s *Settings) SizeMapDflt(key string, dflt map[string]int64) map[string]int64
- func (s *Settings) String(key string) (string, error)
- func (s *Settings) StringArray(key string) ([]string, error)
- func (s *Settings) StringArrayDflt(key string, dflt []string) []string
- func (s *Settings) StringDflt(key string, dflt string) string
- func (s *Settings) StringMap(key string) (map[string]string, error)
- func (s *Settings) StringMapDflt(key string, dflt map[string]string) map[string]string
Constants ¶
This section is empty.
Variables ¶
var IndexError error = errors.New("invalid index")
var KeyError error = errors.New("key not found")
var ObjectError error = errors.New("invalid object")
var RangeError error = errors.New("index out of range")
var TypeError error = errors.New("invalid type conversion")
Functions ¶
Types ¶
type Settings ¶
type Settings struct {
Key string
Values map[interface{}]interface{}
}
func LoadOrExit ¶
Load and parse settings from the file at the provided path. If an error occurs print it to stderr and call os.Exit(1).
func (*Settings) Append ¶
Append a value to an array. Creates an array at that location if it does not exist. The following errors may be returned:
ObjectError - a child object is not a `map[interface{}]interface{}` or `[]interface{}` IndexError - a key cannot be converted to an integer for a child array
func (*Settings) BoolArrayDflt ¶
Get an array of bool values. Return `dflt` if an error occurs.
func (*Settings) BoolMapDflt ¶
Get a map of bool values. Return `dflt` if an error occurs.
func (*Settings) Delete ¶
Delete a key. May return an error on failure. A non-existent key is not an error case.
ObjectError - a child object is not a `map[interface{}]interface{}` or `[]interface{}` IndexError - a key cannot be converted to an integer for a child array
func (*Settings) DurationArray ¶
Get an array of durations values.
func (*Settings) DurationArrayDflt ¶
Get an array of duration values. Return `dflt` if an error occurs.
func (*Settings) DurationDflt ¶
Get a duration value. Return `dflt` if an error occurs.
func (*Settings) DurationMap ¶
Get a map of durations.
func (*Settings) DurationMapDflt ¶
func (s *Settings) DurationMapDflt(key string, dflt map[string]time.Duration) map[string]time.Duration
Get a map of duration values. Return `dflt` if an error occurs.
func (*Settings) FloatArray ¶
Get an array of float values.
func (*Settings) FloatArrayDflt ¶
Get an array of float values. Return `dflt` if an error occurs.
func (*Settings) FloatMapDflt ¶
Get a map of float values. Return `dflt` if an error occurs.
func (*Settings) IntArrayDflt ¶
Get an array of integer values. Return `dflt` if an error occurs.
func (*Settings) IntMapDflt ¶
Get a map of integer values. Return `dflt` if an error occurs.
func (*Settings) ObjectArray ¶
Get an array of settings objects.
func (*Settings) ObjectArrayDflt ¶
Get an array of settings objects. Return `dflt` if an error occurs.
func (*Settings) ObjectDflt ¶
Get a settings object. Return `dflt` if an error occurs.
func (*Settings) ObjectMapDflt ¶
Get a map of settings objects. Return `dflt` if an error occurs.
func (*Settings) Set ¶
Set a value in the settings object. This overrides all keys in the path that are not already objects. The following errors may be returned:
ObjectError - a child object is not a `map[interface{}]interface{}` or `[]interface{}` IndexError - a key cannot be converted to an integer for a child array RangeError - the index is out of range for a child array
func (*Settings) SizeArrayDflt ¶
Get an array of size values. Return `dflt` if an error occurs.
func (*Settings) SizeMapDflt ¶
Get a map of size values. Return `dflt` if an error occurs.
func (*Settings) StringArray ¶
Get an array of string values.
func (*Settings) StringArrayDflt ¶
Get an array of string values. Return `dflt` if an error occurs.
func (*Settings) StringDflt ¶
Get a string value. Return `dflt` if an error occurs.
Source Files