Documentation
¶
Overview ¶
cfg is a library to read config files. Structure is similar but not identical to ini files.
Features: comments, sections, multiline values, validation, reload, shell-out execution
This is not a database replacement. The whole cfg file is processed once on Load()/LoadExec() and returns a Config type.
Rules:
- A key/value database separated by colons (:). Processed from the beginning to the end.
- Multiline values need an indent of 2 spaces from the second line on until the last for that value.
- Comments need a # at the start of the line and is only valid for a key/value pair not as a comment for [main] or a custom section name.
- Sections need to start with [ and explicitly end with ] in a single line.
- The default section is called 'main'.
- Keys can be used in different sections distinctively. If the same key is used in the same section, then the keys last occurence value is set.
- Keys and Sections should not be longer than 32 chars. You can adjust this through MaxNameSize.
- Values of keys can not be longer than MaxValueSize (1024) chars. You can adjust this through MaxValueSize.
- If the data you load returns an empty config, you will receive an error. You can adjust this through EmptyConfig.
- ↓ as placeholder declaration:
- ↓ stands alone and is besides in main always the section name in which the reference happens.
- ↓NAME NAME can be any key in the main section (see rules above). NAME has to be placed before the key in which value the reference is used.
Index ¶
- Variables
- func Debug() bool
- type Comments
- type Config
- func (c *Config) Delete(section, key Name) error
- func (c *Config) DisableExec()
- func (c *Config) GetBool(section, key Name) (bool, error)
- func (c *Config) GetBytes(section, key Name) ([]byte, error)
- func (c *Config) GetFloat(section, key Name) (float64, error)
- func (c *Config) GetInt(section, key Name) (int64, error)
- func (c *Config) Keys(section Name) ([]Name, error)
- func (c *Config) Reload(r io.Reader) error
- func (c *Config) Sections() []Name
- func (c *Config) Set(section, key Name, value string) error
- func (c *Config) Store(w io.Writer) error
- func (c *Config) Validator(section, key Name, f Validation) error
- func (c *Config) Value(section, key Name) (string, error)
- type Data
- type Name
- type Sections
- type Validation
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( MaxValueSize int = 1024 MaxCommentLineSize int = 256 MaxNameSize int = 32 EmptyConfig bool )
var ( // Amount of seconds to run a shell until canceled on LoadExec() / Reload() calls. / 1 second = 1e+9 ShellExecTimeout time.Duration = 10 * time.Second ShellEnvVariables map[string]string = make(map[string]string) )
var EnableValidationOnLoad bool
EnableValidationOnLoad forces validation if true and if DefaultValidation is set.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// If DefaultValidation is set, you can explicitily exclude a key from validation. map[section]key
ValidationExclude map[Name][]Name
// contains filtered or unexported fields
}
Config holds all loaded data.
func Load ¶
Load takes data from a Reader and returns a pointer to Config and nil if successful. This function does not execute anything, it just reads.
Example ¶
package main
import (
"log"
"os"
"catinello.eu/cfg"
)
func main() {
f, err := os.Open("test/test.cfg")
if err != nil {
log.Fatal(err)
}
defer f.Close()
_, err = cfg.Load(f, false)
if err != nil {
log.Fatal(err)
}
}
Output:
func LoadExec ¶
Load takes data from a Reader just like Load() and adds limitation through the restrict value.
Restrict is a list of explicit command line application names (no absolute paths) that will be allowed to execute. Implicit usage is not blocked. If the list is empty, all available commands are potentially allowed!
$SHELL must be bash, zsh, ksh. Since a restricted shell is called. Used commands need to be looked up in $PATH.
func (*Config) Delete ¶
Delete removes the given key in that section. If the key is empty, the whole section gets wiped.
func (*Config) DisableExec ¶
func (c *Config) DisableExec()
DisableExec() disables the shell out execution on $(cmd) usage if config was created with LoadExec(). Convenience function for the special case that you need to load a config with execution for example just once and do not need it on Reload() calls.
func (*Config) Reload ¶
Reload takes data from a Reader and replaces *Config content with the new data.
func (*Config) Set ¶
Set makes it possible to set a new value to an existing key or a new key in a also potentially new section.
func (*Config) Validator ¶
func (c *Config) Validator(section, key Name, f Validation) error
Validator sets a specific Validation function for the given key in given section of config c. This validation is checked on Value() calls of that given key in section of the used config.
func (*Config) Value ¶
Value returns the value of key in section of c, if section and key exist.
Example ¶
package main
import (
"fmt"
"log"
"os"
"catinello.eu/cfg"
)
func main() {
f, err := os.Open("test/test.cfg")
if err != nil {
log.Fatal(err)
}
defer f.Close()
c, err := cfg.Load(f, false)
if err != nil {
log.Fatal(err)
}
fmt.Println(c.Value("main", "foo"))
}
Output: bar <nil>
type Data ¶
type Data struct {
Key Name
Value string
Comment Comments
Validator Validation
}
Data consists of a Key/Value combination and additional Comments.
type Validation ¶
Add your validation function to the appropiate objects to validate on Value calls.
var DefaultValidation Validation
DefaultValidation is set to all loaded Data objects and can be overwritten by Validator per Data on Value calls.
Source Files
Directories