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, std::string_view yes={}) | |
Constructor that initialises from an option value map, typically parsed out from a command-line. More... | |
MapFile (const Path &, std::string_view kind={}) | |
Constructor that reads from a file. More... | |
MapFile (const Path &, std::string_view kind, std::nothrow_t) | |
A non-throwing overload that reads from a file and ignores any errors. 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 (std::string_view key, std::string_view value, bool clear=false) |
Adds or updates a single item in the map. More... | |
bool | update (std::string_view key, std::string_view value) |
Updates an existing value. More... | |
bool | remove (std::string_view key) |
Removes a value (if it exists). More... | |
void | writeItem (std::ostream &, std::string_view key) const |
Writes a single item from this map to the stream. More... | |
Path | editInto (const Path &path, bool make_backup, bool do_throw=true) const |
Edits an existing file so that its contents reflect this map. More... | |
bool | contains (std::string_view key) const |
Returns true if the map contains the given key. More... | |
Path | pathValue (std::string_view key) const |
Returns a mandatory path value from the map. More... | |
Path | pathValue (std::string_view key, const Path &default_) const |
Returns a path value from the map. More... | |
unsigned int | numericValue (std::string_view key, unsigned int default_) const |
Returns a numeric value from the map. More... | |
std::string | value (std::string_view key, std::string_view default_={}) const |
Returns a string value from the map. More... | |
bool | valueContains (std::string_view key, std::string_view token, std::string_view default_={}) const |
Returns true if value(key,default_) contains the given comma-separated token. More... | |
bool | booleanValue (std::string_view key, bool default_) const |
Returns a boolean value from the map. 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 (std::string_view value) const |
Does one-pass variable substitution for the given string. More... | |
Path | expandedPathValue (std::string_view key) const |
Returns a mandatory path value from the map with expand(). More... | |
Path | expandedPathValue (std::string_view key, const Path &default_) const |
Returns a path value from the map with expand(). More... | |
Static Public Member Functions | |
static void | writeItem (std::ostream &, std::string_view key, std::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 59 of file gmapfile.h.
|
explicit |
Constructor that initialises from a string map.
Definition at line 59 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 68 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 38 of file gmapfile.cpp.
G::MapFile::MapFile | ( | const Path & | path, |
std::string_view | kind, | ||
std::nothrow_t | |||
) |
A non-throwing overload that reads from a file and ignores any errors.
Definition at line 46 of file gmapfile.cpp.
|
explicit |
Constructor that reads from a stream.
Definition at line 54 of file gmapfile.cpp.
void G::MapFile::add | ( | std::string_view | key, |
std::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 443 of file gmapfile.cpp.
bool G::MapFile::booleanValue | ( | std::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 280 of file gmapfile.cpp.
bool G::MapFile::contains | ( | std::string_view | key | ) | const |
Returns true if the map contains the given key.
Definition at line 485 of file gmapfile.cpp.
Edits an existing file so that its contents reflect this map.
Returns the path of the backup file, if created.
Definition at line 222 of file gmapfile.cpp.
std::string G::MapFile::expand | ( | std::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 373 of file gmapfile.cpp.
G::Path G::MapFile::expandedPathValue | ( | std::string_view | key | ) | const |
Returns a mandatory path value from the map with expand().
Throws if it does not exist.
Definition at line 327 of file gmapfile.cpp.
Returns a path value from the map with expand().
Definition at line 322 of file gmapfile.cpp.
const G::StringArray & G::MapFile::keys | ( | ) | const |
Returns a reference to the internal ordered list of keys.
Definition at line 495 of file gmapfile.cpp.
void G::MapFile::log | ( | const std::string & | prefix = {} | ) | const |
Logs the contents.
Definition at line 191 of file gmapfile.cpp.
const G::StringMap & G::MapFile::map | ( | ) | const |
Returns a reference to the internal map.
Definition at line 490 of file gmapfile.cpp.
unsigned int G::MapFile::numericValue | ( | std::string_view | key, |
unsigned int | default_ | ||
) | const |
Returns a numeric value from the map.
Definition at line 352 of file gmapfile.cpp.
G::Path G::MapFile::pathValue | ( | std::string_view | key | ) | const |
Returns a mandatory path value from the map.
Throws if it does not exist.
Definition at line 337 of file gmapfile.cpp.
Returns a path value from the map.
Definition at line 332 of file gmapfile.cpp.
bool G::MapFile::remove | ( | std::string_view | key | ) |
Removes a value (if it exists).
Definition at line 357 of file gmapfile.cpp.
bool G::MapFile::update | ( | std::string_view | key, |
std::string_view | value | ||
) |
std::string G::MapFile::value | ( | std::string_view | key, |
std::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 297 of file gmapfile.cpp.
bool G::MapFile::valueContains | ( | std::string_view | key, |
std::string_view | token, | ||
std::string_view | default_ = {} |
||
) | const |
Returns true if value(key,default_) contains the given comma-separated token.
Definition at line 303 of file gmapfile.cpp.
void G::MapFile::writeItem | ( | std::ostream & | stream, |
std::string_view | key | ||
) | const |
Writes a single item from this map to the stream.
Definition at line 207 of file gmapfile.cpp.
|
static |
Writes an arbitrary item to the stream.
Definition at line 216 of file gmapfile.cpp.