Module justconfig::sources::text

Text source.

This sources parses a text representation of the configuration. The configuration format is as simple as possible to make it as easy to write and parse as possible.

Any struct that implements Read can be used as a source for configuration values. The text must be UTF-8 encoded.

use justconfig::Config;
use justconfig::sources::text::ConfigText;
use std::fs::File;
 
let mut conf = Config::default();
 
let file = File::open("myconfig.conf").expect("Could not open config file.");
let conf_file = ConfigText::new(file, "myconfig.conf").unwrap();
conf.add_source(conf_file);

The name of the configuration source must be passed as a second parameter. It is used to create nice error messages to show to the user.

Stacking configuration files

To search for configuration information in multiple directories the convenience function stack_config is provided. It merges all found configuration files allowing parts of a default configuration file to be overwritten by more specific configuration files in other directories.

Configuration Format

The configuration consists primarily of key-value-pairs. On a normal configuration line everything before the first equals sign (=) is considered a key. Everything after the equals sign is the value.

The configuration file format does not make any assumptions about the format of the value. The usage of quotes or validation can be declared by using processors or validators.

Just-Config allows configuration keys to be organized in a hierarchical manner. This is represented by a ConfPath structure. To represent hierarchical configuration values within the key value of the text configuration dot (.) is used as a delimiter.

key=value
section.subsection.key=value

This configuration file defines two values with the following ConfPath:

ConfPath::from(&["key"]);
ConfPath::from(&["section", "subsection", "key"]);

Leading white-spaces before the key and any white-space between the key and the equals sign are ignored. White spaces after the equals sign are significant.

Comments

Everything on a line after the first hash character (#) is ignored. Comments can be put in front of the line, making the whole line a comment or after non comment text:

## Complete comment
key=value # Comment
[Section] # Comment

To include a literal hash character into a value or key it has to be escaped by prepending it with a backslash (\):

key=value containing \#hash

Sections

Sections can be used to prevent typing the same prefixes for keys over and over. Every line where the first, non white-space character is a square bracket ([) is considered a section header. The section header can contain one or more prefixes to put in front of every key that follows the section header:

[section]
key=value
# Key is section.key=value
 
[section.subsection]
key=value
# Key is section.subsection.key=value
 
[section]
subsection.key=value
# Key is section.subsection.key=value

Multiple values per key

A key can have multiple values. Just assign multiple values to the same to use this feature. To make typing a little less tedious, the key can be omitted if subsequent values are assigned to the same key:

key=value1
key=value2
 
# is the same as
 
key=value1
   =value2

White-space characters before the equals sign are ignored. That way indentation is possible.

Beware: An empty line (or a line only containing a comment) resets the current key. The following configuration will return a NoPreviousKey error:

key=value1
# I'm a comment but an empty line will do, too.
=value2

Multi line values

Sometimes a value should span multiple lines. There are two possible methods to achieve this:

• Using the unescape Processor.
• Using line continuation.

The line continuation feature of the text parser allows lines to be continued. In contrast to other configuration file formats the line continuation has to be introduced on the continuing line, not on the line that is continued. To continue a line the first non white-space character must be the pipe character (|).

key=line1
   |line2

The continuation character can even be indented to make the multi-line configuration entry easier to read.

The second line is appended to the first line after a newline character (\n).

Structs

ConfigText	Implements the text configuration parser.
TextSourceLocation	Source location for the ConfigText configuration source. This value is used to store the source of every configuration value for use in error messages.

Enums

Error

Enumeration containing parse errors.

Functions

stack_config

Helper function for config file stacking.