E-MailRelay

Classes | Public Member Functions | Static Public Member Functions | List of all members
G::MapFile Class Reference

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

## Detailed Description

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.

## Constructor & Destructor Documentation

## ◆ MapFile() [1/5]

G::MapFile::MapFile | ( | const StringMap & | map | ) |
| explicit

Constructor that initialises from a string map.

Definition at line 59 of file gmapfile.cpp.

## ◆ MapFile() [2/5]

G::MapFile::MapFile | ( | const OptionMap & | map,
|  | std::string_view | yes = `{}`
| ) |  |
| 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.

## ◆ MapFile() [3/5]

G::MapFile::MapFile | ( | const Path & | path,
|  | std::string_view | kind = `{}`
| ) |  |
| 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.

## ◆ MapFile() [4/5]

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.

## ◆ MapFile() [5/5]

G::MapFile::MapFile | ( | std::istream & | stream | ) |
| explicit

Constructor that reads from a stream.

Definition at line 54 of file gmapfile.cpp.

## Member Function Documentation

## ◆ add()

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.

## ◆ booleanValue()

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.

## ◆ contains()

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.

## ◆ editInto()

G::Path G::MapFile::editInto | ( | const Path & | path,
|  | bool | make_backup,
|  | bool | do_throw = `true`
| ) |  | const

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.

## ◆ expand()

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.

## ◆ expandedPathValue() [1/2]

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.

## ◆ expandedPathValue() [2/2]

G::Path G::MapFile::expandedPathValue | ( | std::string_view | key,
|  | const Path & | default_
| ) |  | const

Returns a path value from the map with expand().

Definition at line 322 of file gmapfile.cpp.

## ◆ keys()

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.

## ◆ log()

void G::MapFile::log | ( | const std::string & | prefix = `{}` | ) | const

Logs the contents.

Definition at line 191 of file gmapfile.cpp.

## ◆ map()

const G::StringMap & G::MapFile::map | ( |  | ) | const

Returns a reference to the internal map.

Definition at line 490 of file gmapfile.cpp.

## ◆ numericValue()

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.

## ◆ pathValue() [1/2]

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.

## ◆ pathValue() [2/2]

G::Path G::MapFile::pathValue | ( | std::string_view | key,
|  | const Path & | default_
| ) |  | const

Returns a path value from the map.

Definition at line 332 of file gmapfile.cpp.

## ◆ remove()

bool G::MapFile::remove | ( | std::string_view | key | ) |

Removes a value (if it exists).

Definition at line 357 of file gmapfile.cpp.

## ◆ update()

bool G::MapFile::update | ( | std::string_view | key,
|  | std::string_view | value
| ) |  |

Updates an existing value.

Returns false if not found.

Definition at line 461 of file gmapfile.cpp.

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

## ◆ valueContains()

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.

## ◆ writeItem() [1/2]

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.

## ◆ writeItem() [2/2]

void G::MapFile::writeItem | ( | std::ostream & | stream,
|  | std::string_view | key,
|  | std::string_view | value
| ) |  |
| static

Writes an arbitrary item to the stream.

Definition at line 216 of file gmapfile.cpp.

The documentation for this class was generated from the following files:

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gmapfile.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/gmapfile.cpp