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, 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 StringArraykeys () 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 StringMapmap () 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...
 

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 56 of file gmapfile.h.

Constructor & Destructor Documentation

◆ MapFile() [1/4]

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

Constructor that initialises from a string map.

Definition at line 56 of file gmapfile.cpp.

◆ MapFile() [2/4]

G::MapFile::MapFile ( const OptionMap map,
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 64 of file gmapfile.cpp.

◆ MapFile() [3/4]

G::MapFile::MapFile ( const Path path,
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 41 of file gmapfile.cpp.

◆ MapFile() [4/4]

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

Constructor that reads from a stream.

Definition at line 51 of file gmapfile.cpp.

Member Function Documentation

◆ add()

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.

◆ booleanValue()

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.

◆ check()

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

◆ contains()

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.

◆ editInto()

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.

◆ expand()

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.

◆ expandedPathValue() [1/2]

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.

◆ expandedPathValue() [2/2]

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.

◆ keys()

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.

◆ log()

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

Logs the contents.

Definition at line 140 of file gmapfile.cpp.

◆ map()

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

Returns a reference to the internal map.

Definition at line 431 of file gmapfile.cpp.

◆ numericValue()

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.

◆ pathValue() [1/2]

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.

◆ pathValue() [2/2]

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.

◆ remove()

void G::MapFile::remove ( string_view  key)

Removes a value (if it exists).

Definition at line 316 of file gmapfile.cpp.

◆ value()

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.

◆ writeItem() [1/2]

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.

◆ writeItem() [2/2]

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

Writes an arbitrary item to the stream.

Definition at line 165 of file gmapfile.cpp.


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