79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
|
# 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
|