goconfig

README

This project has been deprecated. Please use the fork at https://github.com/robfig/config.

Documentation

Overview

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

Given a sample configuration file:

[default]
host=www.example.com
protocol=http://
base-url=%(protocol)s%(host)s

[service-1]
url=%(base-url)s/some/path
delegation : on
maxclients=200 # do not set this higher
comments=This is a multi-line
	entry	; And this is a comment

To read this configuration file, do:

	c, err := configfile.ReadConfigFile("config.cfg");

 // result is string :http://www.example.com/some/path"
	c.GetString("service-1", "url");

	c.GetInt64("service-1", "maxclients"); // result is int 200
	c.GetBool("service-1", "delegation"); // result is bool true

 // result is string "This is a multi-line\nentry"
	c.GetString("service-1", "comments");

Note the support for unfolding variables (such as %(base-url)s), which are read from the special (reserved) section name [default].

A new configuration file can also be created with:

	c := configfile.NewConfigFile();
	c.AddSection("section");
	c.AddOption("section", "option", "value");
 // use 0644 as file permission
	c.WriteConfigFile("config.cfg", 0644, "A header for this file");

This results in the file:

# A header for this file
[section]
option=value

Note that sections and options are case-insensitive (values are case-sensitive) and are converted to lowercase when saved to a file.

The functionality and workflow is loosely based on the configparser.py package of the Python Standard Library.

Index

• Variables
• type ConfigFile
  • func NewConfigFile() *ConfigFile
  • func ReadConfigFile(fname string) (*ConfigFile, 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) (bool, error)
  • func (c *ConfigFile) GetFloat(section string, option string) (float64, error)
  • func (c *ConfigFile) GetInt64(section string, option string) (int64, error)
  • func (c *ConfigFile) GetOptions(section string) ([]string, error)
  • func (c *ConfigFile) GetRawString(section string, option string) (string, error)
  • func (c *ConfigFile) GetSections() (sections []string)
  • func (c *ConfigFile) GetString(section string, option string) (string, error)
  • func (c *ConfigFile) HasOption(section string, option string) bool
  • func (c *ConfigFile) HasSection(section string) bool
  • func (c *ConfigFile) RemoveOption(section string, option string) bool
  • func (c *ConfigFile) RemoveSection(section string) bool
  • func (c *ConfigFile) WriteConfigFile(fname string, perm uint32, header string) error

Variables

var (
	DefaultSection = "default" // Default section name (must be lower-case).

	// Maximum allowed depth when recursively substituing variable names.
	DepthValues = 200

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

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 ReadConfigFile

func ReadConfigFile(fname string) (*ConfigFile, 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) (bool, 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) GetFloat

func (c *ConfigFile) GetFloat(section string, option string) (float64, error)

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

func (*ConfigFile) GetInt64

func (c *ConfigFile) GetInt64(section string, option string) (int64, error)

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

func (*ConfigFile) GetOptions

func (c *ConfigFile) GetOptions(section string) ([]string, 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) (string, 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) (string, 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) 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) WriteConfigFile

func (c *ConfigFile) WriteConfigFile(fname string, perm uint32, header string) 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.