# 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: addIncludeFile, clear, getIncludeFiles, getSourceFile, getSourceFiles, load, removeIncludeFile, 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

explicit PropertyFileConfiguration(
AbstractConfiguration * pParentConfig = nullptr
);

Creates an empty PropertyFileConfiguration. If pParentConfig is not null, it is used to expand ${variable} references in !include directive paths. The parent configuration is not owned by this object; the caller must ensure it outlives this configuration.

### PropertyFileConfiguration

explicit PropertyFileConfiguration(
AbstractConfiguration::Ptr pParentConfig
);

Deprecated. Use the AbstractConfiguration* overload instead. Forwards to the raw-pointer constructor.

### PropertyFileConfiguration

explicit PropertyFileConfiguration(
std::istream & istr,
AbstractConfiguration * 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. The parent configuration is not owned by this object; the caller must ensure it outlives this configuration.

### PropertyFileConfiguration

explicit PropertyFileConfiguration(
const std::string & path,
AbstractConfiguration * 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. The parent configuration is not owned by this object; the caller must ensure it outlives this configuration.

### PropertyFileConfiguration

PropertyFileConfiguration(
std::istream & istr,
AbstractConfiguration::Ptr pParentConfig
);

Deprecated. Use the AbstractConfiguration* overload instead.

### PropertyFileConfiguration

PropertyFileConfiguration(
const std::string & path,
AbstractConfiguration::Ptr pParentConfig
);

Deprecated. Use the AbstractConfiguration* overload instead.

## Destructor

### ~PropertyFileConfiguration

~PropertyFileConfiguration();

## Member Functions

### addIncludeFile

void addIncludeFile(
const std::string & path
);

Adds an !include directive for the given file path to the root file. The path is written as-is to the file; internally it is resolved to absolute for duplicate detection. If the target file does not exist, it is created as an empty file. Any properties in the included file are loaded into memory immediately (no reload required). If the included file has invalid syntax or cyclic includes, the exception propagates and the root file is left untouched. This method performs file I/O while holding the configuration lock. Throws Poco::IllegalStateException if no root file is set. Throws Poco::FileExistsException if an !include directive for

    this file already exists in the root file.

### clear

void clear();

Clears the configuration, including provenance information.

### getIncludeFiles

std::vector < std::string > getIncludeFiles(
const std::string & path = ""
) const;

Returns the list of !include file paths (absolute) found in the given file. If path is empty, the file from which the configuration was originally loaded is scanned. Returns an empty vector if no root file is set.

### 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.

### getSourceFiles

std::map < std::string, std::string > getSourceFiles() const;

Returns a snapshot of the source file map (key -> file path).

### 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.

### removeIncludeFile

void removeIncludeFile(
const std::string & path,
bool removeKeys = false
);

Removes the !include directive for the given file path from the root file. Only removes the directive from the root file; nested includes within the removed file are not affected. The included file itself is not deleted from disk. If removeKeys is true, all keys whose provenance matches this file are also removed from the configuration. If removeKeys is false (default), keys remain in memory but their provenance is cleared. A subsequent save() will write those keys to the root file. This method performs file I/O while holding the configuration lock. Throws Poco::IllegalStateException if no root file is set. Throws Poco::NotFoundException if no matching !include directive exists.

### 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. Source files of removed keys are also rewritten so deleted properties do not linger on disk, even when the removal empties an included 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()