Library: Util
Package: Configuration
Header: Poco/Util/PropertyFileConfiguration.h
Description
This implementation of a Configuration reads properties from a Java-style properties file.
The file syntax is implemented as follows.
- a line starting with a hash '#' or exclamation mark '!' is treated as a comment and ignored (with the exception of the !include directive described below)
- every other line denotes a property assignment in the form <key> = <value> or <key> : <value>
Keys and values may contain special characters represented by the following escape sequences:
- \t: tab (0x09)
- \n: line feed (0x0a)
- \r: carriage return (0x0d)
- \f: form feed (0x0c)
For every other sequence that starts with a backslash, the backslash is removed. Therefore, the sequence \a would just yield an 'a'.
A value can spread across multiple lines if the last character in a line (the character immediately before the carriage return or line feed character) is a single backslash.
A line of the form
!include <path>
(where <path> is a relative or absolute file path) includes another properties file. Relative paths are resolved relative to the directory of the including file. ${variable} references in include paths are expanded, either from properties already loaded in the same file, or from an optional parent configuration passed via the constructor.
Property names are case sensitive. Leading and trailing whitespace is removed from both keys and values. A property name can neither contain a colon ':' nor an equal sign '=' character.
Inheritance
Direct Base Classes: MapConfiguration
All Base Classes: Poco::RefCountedObject, AbstractConfiguration, MapConfiguration
Member Summary
Member Functions: clear, getSourceFile, load, removeRaw, save, setSourceFile
Inherited Functions: begin, clear, copyTo, createLocalView, createView, duplicate, enableEvents, end, enumerate, eventsEnabled, expand, getBool, getDouble, getInt, getInt16, getInt32, getInt64, getRaw, getRawString, getString, getUInt, getUInt16, getUInt32, getUInt64, has, hasOption, hasProperty, keys, operator =, parseBool, parseInt, parseInt16, parseInt64, parseUInt, parseUInt16, parseUInt64, referenceCount, release, remove, removeRaw, setBool, setDouble, setInt, setInt16, setInt32, setInt64, setRaw, setRawWithEvent, setString, setUInt, setUInt16, setUInt32, setUInt64
Constructors
PropertyFileConfiguration
PropertyFileConfiguration(
AbstractConfiguration::Ptr pParentConfig = nullptr
);
Creates an empty PropertyFileConfiguration. If pParentConfig is not null, it is used to expand ${variable} references in !include directive paths.
PropertyFileConfiguration
PropertyFileConfiguration(
std::istream & istr,
AbstractConfiguration::Ptr pParentConfig = nullptr
);
Creates an PropertyFileConfiguration and loads the configuration data from the given stream, which must be in properties file format. If pParentConfig is not null, it is used to expand ${variable} references in !include directive paths.
PropertyFileConfiguration
PropertyFileConfiguration(
const std::string & path,
AbstractConfiguration::Ptr pParentConfig = nullptr
);
Creates an PropertyFileConfiguration and loads the configuration data from the given file, which must be in properties file format. If pParentConfig is not null, it is used to expand ${variable} references in !include directive paths.
Destructor
~PropertyFileConfiguration 
~PropertyFileConfiguration() = default;
Member Functions
clear
void clear();
Clears the configuration, including provenance information.
getSourceFile
std::string getSourceFile(
const std::string & key
) const;
Returns the file path the given key was loaded from, or an empty string if unknown.
load
void load(
std::istream & istr
);
Loads the configuration data from the given stream, which must be in properties file format.
load
void load(
const std::string & path
);
Loads the configuration data from the given file, which must be in properties file format.
save
void save(
std::ostream & ostr
) const;
Writes the configuration data to the given stream.
The data is written as a sequence of statements in the form <key>: <value> separated by a newline character.
save
void save(
const std::string & path
) const;
Writes the configuration data to the given file.
If the configuration was loaded from a file (and possibly includes), save preserves comments, blank lines, and
include directives. Changed values are written back to the
file they were originally loaded from. New keys are appended to the root file. If no provenance information is available, the file is written as a flat list of key-value pairs.
setSourceFile
void setSourceFile(
const std::string & key,
const std::string & path
);
Sets the source file for the given key. When save() is called with provenance-based saving, the key will be written to this file.
removeRaw
void removeRaw(
const std::string & key
) override;