Corrade::Utility::Configuration class
#include <Corrade/Utility/Configuration.h>

Parser and writer for configuration files.

Provides hierarchical configuration storage for key/value pairs with support for parsing and loading into an textual INI-style file format. Basic API usage example:

Utility::Configuration conf{"my.conf"};

/* Set value of third occurrence of the key from some deep group */
conf.addGroup("foo")->addGroup("bar")->setValue("myKey", "myValue");

/* Get a value back */
std::string value = conf.group("foo")->group("bar")->value("myKey");

/* Remove all groups named "bar" from root */
conf.removeAllGroups("bar");

/* Add three new integral values */
conf.addValue("a", 1);
conf.addValue("a", 2);
conf.addValue("a", 3);

conf.save();

File syntax and usage

File syntax is based on the well-known INI format, consisting of three basic elements:

group header
key/value pair
comment / empty line

Lines can have leading/trailing whitespace, which will be stripped on parsing and saving. Whitespace is preserved in values enclosed in " and in multi-line values. Comments and empty lines are preserved unless Flag::SkipComments is set in constructor or a group containing the comment gets deleted. It's not possible to add comments or empty lines programatically.

Comments begin with # or ; character and continue to the end of line. Each line of a multiline comment must begin with one of these characters.

# A comment
  # on
  # multiple
# lines

; Another type of comment

Key/value pairs

Key/value pair consist of key name string, zero or more whitespace characters, the = character, zero or more whitespace characters and the value. Whitespace around the key is always stripped. Whitespace around the value is stripped on parsing, if you want to preserve it, enclose the value in " characters. Calling setValue() with a string that contains leading/trailing whitespace will cause it to be automatically wrapped in quotes on save.

a=    a string with leading whitespace trimmed
b="    a string with leading whitespace preserved"

All values are internally stored as strings, parsing to and saving from custom types is done by calling an appropriate ConfigurationValue. See its documentation for a guide to integrating your own type, see Configuration value parsers and writers for custom types for a list of additional parsers implemented in Corrade itself.

Multi-line values are enclosed in """ alone on the line, first and last line break is ignored. Calling setValue() with a string that contains newline characters will cause it to be automatically enclosed in """ on save. The following value is parsed as two lines:

value="""
Here is the value.
Spanning multiple lines.
"""

It's allowed to have more than one value with the same key. You can access all values for given key name using values().

buy=bread
buy=milk
buy=apples
buy=onions

Value groups

Value group header is enclosed in [ and ]. Group name is a non-empty sequence of characters. As with values, it's allowed to have more than one group with the same name.

[customer]
name=John
buys=bread

[customer]
name=Jacqueline
buys=cookies

Hierarchic group names are separated with the / character. A group first contains all values and then optional subgroups. A group is a subgroup of the previous group if it has the previous group header as a prefix. In the following snippet, Jake has Mary and Max as parents, while Joanna and Ferdinand are his grandparents, Mary's parents.

name=Jake
likes=cycling

[parent]
name=Mary
likes=nature

[parent/parent]
name=Joanna
likes=cooking

[parent/parent]
name=Ferdinand
likes=smoking pipe

[parent]
name=Max
likes=books

For a shorter syntax, it's possible to omit names of parent groups if they contain only subgroups and given group is the first in the list. The following two snippets are equivalent:

[org]
[org/java]
[org/java/lang]
class=AbstractBeanFactoryListener
class=AbstractFactoryListenerProviderDelegate

[org/java/system]
[org/java/system/services]
class=BeanFactoryListenerProviderDelegateGarbageAllocator

[org/java/lang]
class=AbstractBeanFactoryListener
class=AbstractFactoryListenerProviderDelegate

[org/java/system/services]
class=BeanFactoryListenerProviderDelegateGarbageAllocator

Iteration through groups and values

Apart from accessing groups and values of known names using group(), value() and friends, it's also possible to groups through all groups and values in the configuration using groups() and values(). These functions return an iterable class that then returns key/value pairs (or, in case of groups, name/group). One possible use is to enumerate all group and value names in the file:

Utility::ConfigurationGroup conf{…};

Utility::Debug{} << "Available subgroups:";
for(Containers::Pair<Containers::StringView,
                     Containers::Reference<Utility::ConfigurationGroup>> g:
    conf.groups())
{
    Utility::Debug{} << g.first() << "with"
                     << g.second()->valueCount() << "values";
}

Utility::Debug{} << Utility::Debug::newline << "Available values:";
for(Containers::Pair<Containers::StringView, Containers::StringView> v:
    conf.values())
{
    Utility::Debug{} << v.first() << "is set to" << v.second();
}

Comments and empty lines are skipped when using values(). To access these as well, use valuesComments() instead — in case of comments and empty lines the first pair value is empty, and the second pair value contains the full line contents.

Base classes

class ConfigurationGroup: Group of values in a configuration file.

Public types

enum class Flag: std::uint32_t { PreserveBom = 1 << 0, ForceUnixEol = 1 << 1, ForceWindowsEol = 1 << 2, Truncate = 1 << 3, SkipComments = 1 << 4, ReadOnly = 1 << 5 }: Flag for opening configuration file.
using Flags = Containers::EnumSet<Flag>: Flags for opening configuration file.

Constructors, destructors, conversion operators

Configuration(Flags flags = Flags()) explicit: Default constructor.
Configuration(const std::string& filename, Flags flags = Flags()) explicit: Constructor.
Configuration(std::istream& in, Flags flags = Flags()) explicit: Constructor.
Configuration(const Configuration&) deleted: Copying is not allowed.
Configuration(Configuration&& other) noexcept: Move constructor.
~Configuration(): Destructor.

Public functions

auto operator=(const Configuration&) -> Configuration& deleted: Copying is not allowed.
auto operator=(Configuration&& other) -> Configuration& noexcept: Move assignment.
auto filename() const -> std::string: Filename in UTF-8.
void setFilename(std::string filename): Set filename.
auto isValid() const -> bool: Whether the file was successfully parsed.
auto save(const std::string& filename) -> bool: Save copy of the configuration to another file.
void save(std::ostream& out): Save configuration to stream.
auto save() -> bool: Save the configuration.

Enum documentation

enum class Corrade::Utility::Configuration::Flag: std::uint32_t

Flag for opening configuration file.

Enumerators
PreserveBom	Preserve Byte-Order-Mark in UTF-8 files, if present. Otherwise the BOM will not be saved back into the file.
ForceUnixEol	Force Unix line-endings (LF). Default behavior is to preserve original. If original EOL type cannot be distinguished, Unix is used.
ForceWindowsEol	Force Windows line endings (CR+LF).
Truncate	Don't load any configuration from the file. On saving writes only newly created values.
SkipComments	No comments or empty lines will be preserved on saving. Useful for memory saving and faster access. See also Flag::ReadOnly.
ReadOnly	Open the file read-only, which means faster access to elements and less memory used. Filename is not saved to avoid overwriting the file with save(). See also Flag::SkipComments.

Typedef documentation

typedef Containers::EnumSet<Flag> Corrade::Utility::Configuration::Flags

Flags for opening configuration file.

Function documentation

Corrade::Utility::Configuration::Configuration(Flags flags = Flags()) explicit

Default constructor.

Creates empty configuration with no filename.

Corrade::Utility::Configuration::Configuration(const std::string& filename, Flags flags = Flags()) explicit

Constructor.

Parameters
filename	Filename in UTF-8
flags	Flags

Opens the file and loads it according to specified flags. If file cannot be opened or parsed, the configuration is empty and filename is not saved to avoid overwriting the file with save().

Corrade::Utility::Configuration::Configuration(std::istream& in, Flags flags = Flags()) explicit

Constructor.

Parameters
in	Input stream
flags	Flags

Creates configuration from given input stream.

Corrade::Utility::Configuration::~Configuration()

Destructor.

If the configuration has been changed, calls save().

void Corrade::Utility::Configuration::setFilename(std::string filename)

Set filename.

The filename is used by save() and is expected to be UTF-8 encoded.

bool Corrade::Utility::Configuration::save(const std::string& filename)

Save copy of the configuration to another file.

Parameters
filename	Filename in UTF-8

The original filename() is left untouched. Returns true on success, false otherwise.

bool Corrade::Utility::Configuration::save()

Save the configuration.

If filename() is not empty, writes configuration back to the file. Returns true on success, false otherwise.