# Poco::Util

# class PropertyFileConfiguration

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;

See also: Poco::Util::MapConfiguration::removeRaw()