config

README

config

Package config provides a configuration system for applications.

Config File Location

Config files are stored in standard operating system locations. Each application has exactly one user-level config directory within the user-level config location, and a system-level subdirectory in each of the system-level config locations (if applicable). Each subdirectory bears the application's well-known name as specified in ApplicationDescription. Each subdirectory contains a file called config.conf, which is where the actual config data is stored.

The user-level configuration file takes precendence over system configuration files, and system configuration files take precedence over eachother depending on what order they are specified in. How they are specified depends on the operating system.

Linux, Most Unixes

In terms of the XDG Base Directory Specification, an application with the well-known name com.example.Example would have its config files stored at $XDG_CONFIG_DIRS/com.example.Example/config.conf. On most systems where this specification is applicable, this will result in a file at /etc/xdg/com.example.Example/config.conf and another at $HOME/.config/com.example.Example/config.conf. The location for config files on systems that do not make use of this specification is yet to be determined.

Config File Format

The general format of the file is as follows:

• Encoded in UTF-8
• Consists of lines, separated by \n, or \r\n
• Lines can be any of these:
  • Blank line: has only whitespace
  • Comment: begins with a '#'
  • Entry: a key/value pair separated by an '=' sign

Entries

For entries, all whitespace on either side of the '=' sign, the key, or the value is ignored. The key may contain any letter or digit, as well as '-' and '.'. The value is always identified by its first rune (after the preliminary whitespace of course) and can be one of:

• String
• Number
• Bool

String

A string can be either double-quoted, or any string of runes not identifiable as any other kind of value. Quoted strings are always unquoted when they are read. Either way, these escape sequences are supported, and resolved when they are read:

• '\\': a literal backslash
• '\a': alert, bell
• '\b': backspace
• '\t': horizontal tab
• '\n': line feed
• '\v': vertical tab
• '\f': form feed
• '\r': carriage return
• '\"': double quote

Be aware that some unquoted strings, within reason, are subject to being read as some other value in the future. For example, if there were suddenly a third boolean value called glorble, the unquoted string glorble would be read as a boolean value instead of a string.

Number

A number is a floating point value. It can be of the form:

• Inf: positive infinity
• -Inf: negative infinity
• NaN: "not a number"
• [0-9]+: a whole number
• [0-9]+.[0-9]*: a fractional number

Bool

A bool is a boolean value. It can be one of:

• true
• false

Documentation

Overview

Package config provides a configuration system for applications.

Index

• Constants
• func KeyValid(key string) bool
• type Config
• type ConfigCloser
  • func NewConfig(user string, system ...string) (ConfigCloser, error)
• type File
  • func NewFile() *File
  • func Parse(reader io.Reader) (*File, error)
  • func (this *File) Diff(other *File) map[string]struct{}
  • func (this *File) Get(key string) (Value, error)
  • func (this *File) Has(key string) (bool, error)
  • func (this *File) Map() map[string]Value
  • func (this *File) Reset(key string) error
  • func (this *File) Set(key string, value Value) error
  • func (this *File) WriteTo(writer io.Writer) (n int64, err error)
• type Value
  • func ParseValue(str string) (Value, error)
• type ValueBool
  • func (value ValueBool) Equals(other Value) bool
  • func (value ValueBool) String() string
• type ValueNumber
  • func (value ValueNumber) Equals(other Value) bool
  • func (value ValueNumber) String() string
• type ValueString
  • func (value ValueString) Equals(other Value) bool
  • func (value ValueString) String() string

Constants

const (
	// ErrClosed is returned when Get/Set/Reset is called after the config
	// has been closed.
	ErrClosed = configError("attempt to access a closed config")
	// ErrNonexistentEntry is returned when an entry was not found.
	ErrNonexistentEntry = configError("nonexistent entry")
	// ErrMalformedEntry is returned when a config entry could not be
	// parsed.
	ErrMalformedEntry = configError("malformed entry")
	// ErrMalformedKey is returned when a key has invalid runes.
	ErrMalformedKey = configError("malformed key")
	// ErrMalformedValue is returned when a value could not be parsed.
	ErrMalformedValue = configError("malformed value")
	// ErrMalformedString is returned when a string value could not be
	// parsed.
	ErrMalformedStringValue = configError("malformed string value")
	// ErrMalformedNumber is returned when a number value could not be
	// parsed.
	ErrMalformedNumberValue = configError("malformed number value")
	// ErrMalformedBool is returned when a boolean value could not be
	// parsed.
	ErrMalformedBoolValue = configError("malformed bool value")
	// ErrMalformedEscapeSequence us returned when an escape sequence could
	// not be parsed.
	ErrMalformedEscapeSequence = configError("malformed escape sequence")
)

Functions

func KeyValid

func KeyValid(key string) bool

KeyValid returns whether a key contains only valid runes. They are:

• Letters
• Digits
• '-'
• '.'

Types

type Config

type Config interface {
	// Get gets a value, first considering the user-level config file, and
	// then falling back to system level config files. If the value could
	// not be found anywhere, the specified fallback value is returned. If
	// the key is invalid, it returns nil, ErrMalformedKey.
	Get(key string, fallback Value) (Value, error)
	// GetString is like Get, but will only return strings. If the value is
	// not a string, it will return fallback.
	GetString(key string, fallback string) (string, error)
	// GetNumber is like Get, but will only return numbers. If the value is
	// not a number, it will return fallback.
	GetNumber(key string, fallback float64) (float64, error)
	// GetBool is like Get, but will only return booleans. If the value is
	// not a boolean, it will return fallback.
	GetBool(key string, fallback bool) (bool, error)
	// Set sets a value in the user-level config file. If the key is
	// invalid, it returns ErrMalformedKey. Note that calling this behavior
	// *will* cause a write to disk, and a read from disk for whatever is
	// watching the user file.
	Set(key string, value Value) error
	// Reset removes the value from the user-level config file, resetting it
	// to what is described by the system-level config files. If the key is
	// invalid, it returns ErrMalformedKey. Note that calling this behavior
	// *will* cause a write to disk if successful , and a read from disk for
	// whatever is watching the user file.
	Reset(key string) error
	// OnChange specifies a function to be called whenever a value is
	// changed. The callback is always run within the backend's event loop
	// using tomo.Do. This could have been a channel but I didn't want to do
	// that to people.
	OnChange(func(key string)) event.Cookie
}

Config provides access to an application's configuration, and can notify an application of changes to it.

type ConfigCloser

type ConfigCloser interface {
	Config
	// Close closes the config, causing it to stop watching for changes.
	// Reads or writes to the config after this will return an error.
	Close() error
}

ConfigCloser is a config with a Close behavior, which stops watching the config file and causes any subsequent sets/gets to return errors. Anything that receives a ConfigCloser must close it when done.

func NewConfig

func NewConfig(user string, system ...string) (ConfigCloser, error)

NewConfig creates a new Config using paths to the user-level config file, and a set of system config files. These files need not exist: the user-level file will be created when Set is called for the first time if it does not exist already, and nonexistent system files are simply ignored (unless the Config finds them at any point to have been spontaneously created).

The user file is written to when Set is called, and the system files are only read from. Values in the user file override those in the system files, and system files specified nearer to the start of the vararg list will override those farther down.

type File

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

File represents a config file. It preserves the order of the lines, as well as blank lines and comments.

func NewFile

func NewFile() *File

NewFile creates a blank file with nothing in it.

func Parse

func Parse(reader io.Reader) (*File, error)

Parse parses a config file from a reader. This function operates on a best-effort basis: A file will always be returned, and any errors encountered will be joined together. For a description of the format, see the README.md of this package.

func (*File) Diff

func (this *File) Diff(other *File) map[string]struct{}

Diff returns a set of keys that are different from the other file.

func (*File) Get

func (this *File) Get(key string) (Value, error)

Get gets the keyed value. If the value is unspecified, it returns nil, ErrNonexistentEntry. If the key is invalid, it returns nil, ErrMalformedKey.

func (*File) Has

func (this *File) Has(key string) (bool, error)

Has returns whether the key exists. If the key is invalid, it returns false, ErrMalformedKey.

func (*File) Map

func (this *File) Map() map[string]Value

Map creates and returns a map of keys to values.

func (*File) Reset

func (this *File) Reset(key string) error

Reset removes the value from the file. If the value is set again, it will be added back at the same location. Note that because of this, the positions of lines are not forgotten until the file is written and reloaded. This is why the method is called Reset and not Remove. If the key is invalid, it returns ErrMalformedKey.

func (*File) Set

func (this *File) Set(key string, value Value) error

Set sets a value. If the key is invalid, it returns ErrMalformedKey.

func (*File) WriteTo

func (this *File) WriteTo(writer io.Writer) (n int64, err error)

WriteTo writes the data in this file to an io.Writer.

type Value

type Value interface {
	fmt.Stringer
	Equals(Value) bool
	// contains filtered or unexported methods
}

Value is a config value. Its String behavior produces a lossless and syntactically valid representation of the value.

func ParseValue

func ParseValue(str string) (Value, error)

ParseValue parses a value from a string. For any Value v, ParseValue(v.String()) should hold data exactly equal to v. This function does not trim whitespace.

type ValueBool

type ValueBool bool

func (ValueBool) Equals

func (value ValueBool) Equals(other Value) bool

func (ValueBool) String

func (value ValueBool) String() string

type ValueNumber

type ValueNumber float64

ValueNumber is a number value.

func (ValueNumber) Equals

func (value ValueNumber) Equals(other Value) bool

func (ValueNumber) String

func (value ValueNumber) String() string

type ValueString

type ValueString string

ValueString is a string value.

func (ValueString) Equals

func (value ValueString) Equals(other Value) bool

func (ValueString) String

func (value ValueString) String() string