E-MailRelay
Public Member Functions | Static Public Member Functions | List of all members
G::MapFile Class Reference

A class for reading and editing key=value files, supporting comments, creation of backup files, variable expansion and logging. More...

#include <gmapfile.h>

Public Member Functions

 MapFile ()
 Constructor for an empty map.
 
 MapFile (const G::StringMap &map)
 Constructor that initialises from a string map.
 
 MapFile (const OptionMap &map, const std::string &yes=std::string())
 Constructor that initialises from an option value map, typically parsed out from a command-line. More...
 
 MapFile (const G::Path &)
 Constructor that reads from a file. More...
 
 MapFile (std::istream &)
 Constructor that reads from a stream.
 
const G::StringArray & keys () const
 Returns a reference to the ordered list of keys.
 
void add (const std::string &key, const std::string &value)
 Adds or updates a single item in the map.
 
void writeItem (std::ostream &, const std::string &key) const
 Writes a single item from this map to the stream.
 
void editInto (const G::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 (const std::string &key) const
 Returns true if the map contains the given key.
 
G::Path pathValue (const std::string &key) const
 Returns a mandatory path value from the map. More...
 
G::Path pathValue (const std::string &key, const G::Path &default_) const
 Returns a path value from the map.
 
unsigned int numericValue (const std::string &key, unsigned int default_) const
 Returns a numeric value from the map.
 
std::string value (const std::string &key, const std::string &default_=std::string()) const
 Returns a string value from the map. More...
 
std::string value (const std::string &key, const char *default_) const
 Returns a string value from the map.
 
bool booleanValue (const std::string &key, bool default_) const
 Returns a boolean value from the map. More...
 
void remove (const std::string &key)
 Removes a value (if it exists).
 
const G::StringMap & map () const
 Returns a reference to the internal map.
 
void log () const
 Logs the contents.
 
std::string expand (const std::string &value) const
 Does one-pass variable substitution for the given string. More...
 
G::Path expandedPathValue (const std::string &key) const
 Returns a mandatory path value from the map with expand(). More...
 
G::Path expandedPathValue (const std::string &key, const G::Path &default_) const
 Returns a path value from the map with expand().
 

Static Public Member Functions

static void check (const G::Path &)
 Throws if the file is invalid. More...
 
static void writeItem (std::ostream &, const std::string &key, const std::string &value)
 Writes an arbitrary item to the stream.
 

Detailed Description

A class for reading and editing key=value files, supporting comments, creation of backup files, variable expansion and logging.

See also
G::OptionValue

Definition at line 45 of file gmapfile.h.

Constructor & Destructor Documentation

G::MapFile::MapFile ( const OptionMap &  map,
const std::string &  yes = std::string() 
)
explicit

Constructor that initialises from an option value map, typically parsed out from a command-line.

Unvalued 'true' options in the option value map are loaded into this mapfile object with a value given by the 'yes' parameter, whereas unvalued 'false' options are not loaded. Multi-valued options are loaded as a comma-separated list.

Definition at line 64 of file gmapfile.cpp.

G::MapFile::MapFile ( const G::Path &  path)
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 trimmed, but can otherwise contain whitespace.

Definition at line 41 of file gmapfile.cpp.

Member Function Documentation

bool G::MapFile::booleanValue ( const std::string &  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 269 of file gmapfile.cpp.

void G::MapFile::check ( const G::Path &  path)
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 139 of file gmapfile.cpp.

void G::MapFile::editInto ( const G::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 185 of file gmapfile.cpp.

std::string G::MapFile::expand ( const std::string &  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 342 of file gmapfile.cpp.

G::Path G::MapFile::expandedPathValue ( const std::string &  key) const

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

Throws if it does not exist.

Definition at line 310 of file gmapfile.cpp.

G::Path G::MapFile::pathValue ( const std::string &  key) const

Returns a mandatory path value from the map.

Throws if it does not exist.

Definition at line 305 of file gmapfile.cpp.

std::string G::MapFile::value ( const std::string &  key,
const std::string &  default_ = std::string() 
) 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 286 of file gmapfile.cpp.


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