conf

Documentation

Overview

This package implements a parser for configuration files. This allows easy reading and writing of structured configuration files.

Given the configuration file:

[default]
host = example.com
port = 443
php = on

[service-1]
host = s1.example.com
allow-writing = false

To read this configuration file, do:

c, err := conf.ReadConfigFile("server.conf")
c.GetString("default", "host")               // returns example.com
c.GetInt("", "port")                         // returns 443 (assumes "default")
c.GetBool("", "php")                         // returns true
c.GetString("service-1", "host")             // returns s1.example.com
c.GetBool("service-1","allow-writing")       // returns false
c.GetInt("service-1", "port")                // returns 0 and a GetError

Note that all section and option names are case insensitive. All values are case sensitive.

Goconfig's string substitution syntax has not been removed. However, it may be taken out or modified in the future.

Index

• Constants
• Variables
• type ConfigFile
  • func NewConfigFile() *ConfigFile
  • func ReadConfigBytes(conf []byte) (c *ConfigFile, err error)
  • func ReadConfigFile(fname string) (c *ConfigFile, err error)
  • func (c *ConfigFile) AddOption(section string, option string, value string) bool
  • func (c *ConfigFile) AddSection(section string) bool
  • func (c *ConfigFile) GetBool(section string, option string) (value bool, err error)
  • func (c *ConfigFile) GetFloat64(section string, option string) (value float64, err error)
  • func (c *ConfigFile) GetInt(section string, option string) (value int, err error)
  • func (c *ConfigFile) GetOptions(section string) (options []string, err error)
  • func (c *ConfigFile) GetRawString(section string, option string) (value string, err error)
  • func (c *ConfigFile) GetSections() (sections []string)
  • func (c *ConfigFile) GetString(section string, option string) (value string, err error)
  • func (c *ConfigFile) HasOption(section string, option string) bool
  • func (c *ConfigFile) HasSection(section string) bool
  • func (c *ConfigFile) Read(reader io.Reader) (err error)
  • func (c *ConfigFile) RemoveOption(section string, option string) bool
  • func (c *ConfigFile) RemoveSection(section string) bool
  • func (c *ConfigFile) Write(writer io.Writer, header string) (err error)
  • func (c *ConfigFile) WriteConfigBytes(header string) (config []byte)
  • func (c *ConfigFile) WriteConfigFile(fname string, perm uint32, header string) (err error)
• type GetError
  • func (err GetError) Error() string
• type ReadError
  • func (err ReadError) Error() string

Constants

const (
	// Get Errors
	SectionNotFound = iota
	OptionNotFound
	MaxDepthReached

	// Read Errors
	BlankSection

	// Get and Read Errors
	CouldNotParse
)

Variables

var (
	DefaultSection = "default" // Default section name (must be lower-case).
	DepthValues    = 200       // Maximum allowed depth when recursively substituing variable names.

	// Strings accepted as bool.
	BoolStrings = map[string]bool{
		"t":     true,
		"true":  true,
		"y":     true,
		"yes":   true,
		"on":    true,
		"1":     true,
		"f":     false,
		"false": false,
		"n":     false,
		"no":    false,
		"off":   false,
		"0":     false,
	}
)

Types

type ConfigFile

type ConfigFile struct {
	// contains filtered or unexported fields
}

ConfigFile is the representation of configuration settings. The public interface is entirely through methods.

func NewConfigFile

func NewConfigFile() *ConfigFile

NewConfigFile creates an empty configuration representation. This representation can be filled with AddSection and AddOption and then saved to a file using WriteConfigFile.

func ReadConfigBytes

func ReadConfigBytes(conf []byte) (c *ConfigFile, err error)

func ReadConfigFile

func ReadConfigFile(fname string) (c *ConfigFile, err error)

ReadConfigFile reads a file and returns a new configuration representation. This representation can be queried with GetString, etc.

func (*ConfigFile) AddOption

func (c *ConfigFile) AddOption(section string, option string, value string) bool

AddOption adds a new option and value to the configuration. It returns true if the option and value were inserted, and false if the value was overwritten. If the section does not exist in advance, it is created.

func (*ConfigFile) AddSection

func (c *ConfigFile) AddSection(section string) bool

AddSection adds a new section to the configuration. It returns true if the new section was inserted, and false if the section already existed.

func (*ConfigFile) GetBool

func (c *ConfigFile) GetBool(section string, option string) (value bool, err error)

GetBool has the same behaviour as GetString but converts the response to bool. See constant BoolStrings for string values converted to bool.

func (*ConfigFile) GetFloat64

func (c *ConfigFile) GetFloat64(section string, option string) (value float64, err error)

GetFloat has the same behaviour as GetString but converts the response to float.

func (*ConfigFile) GetInt

func (c *ConfigFile) GetInt(section string, option string) (value int, err error)

GetInt has the same behaviour as GetString but converts the response to int.

func (*ConfigFile) GetOptions

func (c *ConfigFile) GetOptions(section string) (options []string, err error)

GetOptions returns the list of options available in the given section. It returns an error if the section does not exist and an empty list if the section is empty. Options within the default section are also included.

func (*ConfigFile) GetRawString

func (c *ConfigFile) GetRawString(section string, option string) (value string, err error)

GetRawString gets the (raw) string value for the given option in the section. The raw string value is not subjected to unfolding, which was illustrated in the beginning of this documentation. It returns an error if either the section or the option do not exist.

func (*ConfigFile) GetSections

func (c *ConfigFile) GetSections() (sections []string)

GetSections returns the list of sections in the configuration. (The default section always exists.)

func (*ConfigFile) GetString

func (c *ConfigFile) GetString(section string, option string) (value string, err error)

GetString gets the string value for the given option in the section. If the value needs to be unfolded (see e.g. %(host)s example in the beginning of this documentation), then GetString does this unfolding automatically, up to DepthValues number of iterations. It returns an error if either the section or the option do not exist, or the unfolding cycled.

func (*ConfigFile) HasOption

func (c *ConfigFile) HasOption(section string, option string) bool

HasOption checks if the configuration has the given option in the section. It returns false if either the option or section do not exist.

func (*ConfigFile) HasSection

func (c *ConfigFile) HasSection(section string) bool

HasSection checks if the configuration has the given section. (The default section always exists.)

func (*ConfigFile) Read

func (c *ConfigFile) Read(reader io.Reader) (err error)

Read reads an io.Reader and returns a configuration representation. This representation can be queried with GetString, etc.

func (*ConfigFile) RemoveOption

func (c *ConfigFile) RemoveOption(section string, option string) bool

RemoveOption removes a option and value from the configuration. It returns true if the option and value were removed, and false otherwise, including if the section did not exist.

func (*ConfigFile) RemoveSection

func (c *ConfigFile) RemoveSection(section string) bool

RemoveSection removes a section from the configuration. It returns true if the section was removed, and false if section did not exist.

func (*ConfigFile) Write

func (c *ConfigFile) Write(writer io.Writer, header string) (err error)

Writes the configuration file to the io.Writer.

func (*ConfigFile) WriteConfigBytes

func (c *ConfigFile) WriteConfigBytes(header string) (config []byte)

WriteConfigBytes returns the configuration file.

func (*ConfigFile) WriteConfigFile

func (c *ConfigFile) WriteConfigFile(fname string, perm uint32, header string) (err error)

WriteConfigFile saves the configuration representation to a file. The desired file permissions must be passed as in os.Open. The header is a string that is saved as a comment in the first line of the file.

type GetError

type GetError struct {
	Reason    int
	ValueType string
	Value     string
	Section   string
	Option    string
}

func (GetError) Error

func (err GetError) Error() string

type ReadError

type ReadError struct {
	Reason int
	Line   string
}

func (ReadError) Error

func (err ReadError) Error() string