E-MailRelay
|
A class for reading, writing and editing key=value files, supporting variable expansion of percent-key-percent values, comments, creation of backup files, and logging. More...
#include <gmapfile.h>
Classes | |
struct | Error |
Exception class for G::MapFile. More... | |
Public Member Functions | |
MapFile () | |
Constructor for an empty map. | |
MapFile (const StringMap &map) | |
Constructor that initialises from a string map. More... | |
MapFile (const OptionMap &map, string_view yes={}) | |
Constructor that initialises from an option value map, typically parsed out from a command-line. More... | |
MapFile (const Path &, string_view kind={}) | |
Constructor that reads from a file. More... | |
MapFile (std::istream &) | |
Constructor that reads from a stream. More... | |
const StringArray & | keys () const |
Returns a reference to the internal ordered list of keys. More... | |
void | add (string_view key, string_view value, bool clear=false) |
Adds or updates a single item in the map. More... | |
void | writeItem (std::ostream &, string_view key) const |
Writes a single item from this map to the stream. More... | |
void | editInto (const Path &path, bool make_backup, bool allow_read_error, bool allow_write_error) const |
Edits an existing file so that its contents reflect this map. More... | |
bool | contains (string_view key) const |
Returns true if the map contains the given key. More... | |
Path | pathValue (string_view key) const |
Returns a mandatory path value from the map. More... | |
Path | pathValue (string_view key, const Path &default_) const |
Returns a path value from the map. More... | |
unsigned int | numericValue (string_view key, unsigned int default_) const |
Returns a numeric value from the map. More... | |
std::string | value (string_view key, string_view default_={}) const |
Returns a string value from the map. More... | |
bool | booleanValue (string_view key, bool default_) const |
Returns a boolean value from the map. More... | |
void | remove (string_view key) |
Removes a value (if it exists). More... | |
const StringMap & | map () const |
Returns a reference to the internal map. More... | |
void | log (const std::string &prefix={}) const |
Logs the contents. More... | |
std::string | expand (string_view value) const |
Does one-pass variable substitution for the given string. More... | |
Path | expandedPathValue (string_view key) const |
Returns a mandatory path value from the map with expand(). More... | |
Path | expandedPathValue (string_view key, const Path &default_) const |
Returns a path value from the map with expand(). More... | |
Static Public Member Functions | |
static void | check (const Path &, string_view kind={}) |
Throws if the file is invalid. More... | |
static void | writeItem (std::ostream &, string_view key, string_view value) |
Writes an arbitrary item to the stream. More... | |
A class for reading, writing and editing key=value files, supporting variable expansion of percent-key-percent values, comments, creation of backup files, and logging.
Also supports initialisation from a G::OptionMap, containing G::OptionValue values. See also G::OptionParser.
Values containing whitespace are/can-be simply quoted with initial and terminal double-quote characters, but with no special handling of escapes or embedded quotes. For full transparency values must not start with whitespace or '=', must not end with whitespace, must not start-and-end with double-quotes, must not contain commas, and should not contain percent characters if using expand() methods.
Definition at line 56 of file gmapfile.h.
|
explicit |
Constructor that initialises from a string map.
Definition at line 56 of file gmapfile.cpp.
|
explicit |
Constructor that initialises from an option value map, typically parsed out from a command-line.
Unvalued 'on' options in the option value map are loaded into this mapfile object with a value given by the 'yes' parameter, whereas unvalued 'off' options are not loaded at all. Multi-valued options are loaded as a comma-separated list.
Definition at line 64 of file gmapfile.cpp.
|
explicit |
Constructor that reads from a file.
Lines can have a key and no value (see booleanValue()). Comments must be at the start of the line. Values are left and right-trimmed, but can otherwise contain whitespace. The trailing parameter is used in error messages to describe the kind of file, defaulting to "map".
Definition at line 41 of file gmapfile.cpp.
|
explicit |
Constructor that reads from a stream.
Definition at line 51 of file gmapfile.cpp.
void G::MapFile::add | ( | string_view | key, |
string_view | value, | ||
bool | clear = false |
||
) |
Adds or updates a single item in the map.
If updating then by default the new value is appended with a comma separator.
Definition at line 397 of file gmapfile.cpp.
bool G::MapFile::booleanValue | ( | string_view | key, |
bool | default_ | ||
) | const |
Returns a boolean value from the map.
Returns true if the key exists with an empty value. Returns the default if no such key.
Definition at line 261 of file gmapfile.cpp.
|
static |
Throws if the file is invalid.
This is equivalent to constructing a temporary MapFile object, but it specifically does not do any logging.
Definition at line 134 of file gmapfile.cpp.
bool G::MapFile::contains | ( | string_view | key | ) | const |
Returns true if the map contains the given key.
Definition at line 426 of file gmapfile.cpp.
void G::MapFile::editInto | ( | const Path & | path, |
bool | make_backup, | ||
bool | allow_read_error, | ||
bool | allow_write_error | ||
) | const |
Edits an existing file so that its contents reflect this map.
Definition at line 176 of file gmapfile.cpp.
std::string G::MapFile::expand | ( | string_view | value | ) | const |
Does one-pass variable substitution for the given string.
Sub-strings like "%xyz%" are replaced by 'value("xyz")' and "%%" is replaced by "%". If there is no appropriate value in the map then the sub-string is left alone (so "%xyz%" remains as "%xyz%" if there is no "xyz" map item).
Definition at line 327 of file gmapfile.cpp.
G::Path G::MapFile::expandedPathValue | ( | string_view | key | ) | const |
Returns a mandatory path value from the map with expand().
Throws if it does not exist.
Definition at line 296 of file gmapfile.cpp.
G::Path G::MapFile::expandedPathValue | ( | string_view | key, |
const Path & | default_ | ||
) | const |
Returns a path value from the map with expand().
Definition at line 291 of file gmapfile.cpp.
const G::StringArray & G::MapFile::keys | ( | ) | const |
Returns a reference to the internal ordered list of keys.
Definition at line 436 of file gmapfile.cpp.
void G::MapFile::log | ( | const std::string & | prefix = {} | ) | const |
Logs the contents.
Definition at line 140 of file gmapfile.cpp.
const G::StringMap & G::MapFile::map | ( | ) | const |
Returns a reference to the internal map.
Definition at line 431 of file gmapfile.cpp.
unsigned int G::MapFile::numericValue | ( | string_view | key, |
unsigned int | default_ | ||
) | const |
Returns a numeric value from the map.
Definition at line 311 of file gmapfile.cpp.
G::Path G::MapFile::pathValue | ( | string_view | key | ) | const |
Returns a mandatory path value from the map.
Throws if it does not exist.
Definition at line 306 of file gmapfile.cpp.
G::Path G::MapFile::pathValue | ( | string_view | key, |
const Path & | default_ | ||
) | const |
Returns a path value from the map.
Definition at line 301 of file gmapfile.cpp.
void G::MapFile::remove | ( | string_view | key | ) |
Removes a value (if it exists).
Definition at line 316 of file gmapfile.cpp.
std::string G::MapFile::value | ( | string_view | key, |
string_view | default_ = {} |
||
) | const |
Returns a string value from the map.
Returns the default if there is no such key or if the value is empty.
Definition at line 278 of file gmapfile.cpp.
void G::MapFile::writeItem | ( | std::ostream & | stream, |
string_view | key | ||
) | const |
Writes a single item from this map to the stream.
Definition at line 156 of file gmapfile.cpp.
|
static |
Writes an arbitrary item to the stream.
Definition at line 165 of file gmapfile.cpp.