E-MailRelay

gmapfile.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gmapfile.h
19///
20
21#ifndef G_MAP_FILE_H
22#define G_MAP_FILE_H
23
24#include "gdef.h"
25#include "gpath.h"
26#include "gstrings.h"
27#include "gexception.h"
28#include "goptions.h"
29#include "goptionvalue.h"
30#include "goptionmap.h"
31#include <map>
32#include <string>
33#include <iostream>
34
35 namespace G
36{
37 class MapFile ;
38}
39
40//| \class G::MapFile
41/// A class for reading, writing and editing key=value files,
42/// supporting variable expansion of percent-key-percent values,
43/// comments, creation of backup files, and logging.
44///
45/// Also supports initialisation from a G::OptionMap, containing
46/// G::OptionValue values. See also G::OptionParser.
47///
48/// Values containing whitespace are/can-be simply quoted with
49/// initial and terminal double-quote characters, but with no
50/// special handling of escapes or embedded quotes. For full
51/// transparency values must not start with whitespace or '=',
52/// must not end with whitespace, must not start-and-end with
53/// double-quotes, must not contain commas, and should not
54/// contain percent characters if using expand() methods.
55///
56 class G::MapFile
57{
58 public:
59 struct Error : public Exception /// Exception class for G::MapFile.
60 {
61 using Exception::Exception ;
62 } ;
63
64 MapFile() ;
65 ///< Constructor for an empty map.
66
67 explicit MapFile( const G::StringMap & map ) ;
68 ///< Constructor that initialises from a string map.
69
70 explicit MapFile( const OptionMap & map , const std::string & yes = std::string() ) ;
71 ///< Constructor that initialises from an option value map,
72 ///< typically parsed out from a command-line. Unvalued 'on'
73 ///< options in the option value map are loaded into this
74 ///< mapfile object with a value given by the 'yes' parameter,
75 ///< whereas unvalued 'off' options are not loaded at all.
76 ///< Multi-valued options are loaded as a comma-separated
77 ///< list.
78
79 explicit MapFile( const G::Path & , const std::string & kind = std::string() ) ;
80 ///< Constructor that reads from a file. Lines can have a key
81 ///< and no value (see booleanValue()). Comments must be at
82 ///< the start of the line. Values are left and right-trimmed,
83 ///< but can otherwise contain whitespace.
84
85 explicit MapFile( std::istream & ) ;
86 ///< Constructor that reads from a stream.
87
88 const G::StringArray & keys() const ;
89 ///< Returns a reference to the internal ordered list of keys.
90
91 static void check( const G::Path & , const std::string & kind = std::string() ) ;
92 ///< Throws if the file is invalid. This is equivalent to
93 ///< constructing a temporary MapFile object, but it
94 ///< specifically does not do any logging.
95
96 void add( const std::string & key , const std::string & value , bool clear = false ) ;
97 ///< Adds or updates a single item in the map.
98 ///< If updating then by default the new value
99 ///< is appended with a comma separator.
100
101 void writeItem( std::ostream & , const std::string & key ) const ;
102 ///< Writes a single item from this map to the stream.
103
104 static void writeItem( std::ostream & , const std::string & key , const std::string & value ) ;
105 ///< Writes an arbitrary item to the stream.
106
107 void editInto( const G::Path & path , bool make_backup ,
108 bool allow_read_error , bool allow_write_error ) const ;
109 ///< Edits an existing file so that its contents
110 ///< reflect this map.
111
112 bool contains( const std::string & key ) const ;
113 ///< Returns true if the map contains the given key.
114
115 G::Path pathValue( const std::string & key ) const ;
116 ///< Returns a mandatory path value from the map.
117 ///< Throws if it does not exist.
118
119 G::Path pathValue( const std::string & key , const G::Path & default_ ) const ;
120 ///< Returns a path value from the map.
121
122 unsigned int numericValue( const std::string & key , unsigned int default_ ) const ;
123 ///< Returns a numeric value from the map.
124
125 std::string value( const std::string & key , const std::string & default_ = std::string() ) const ;
126 ///< Returns a string value from the map. Returns the default
127 ///< if there is no such key or if the value is empty.
128
129 std::string value( const std::string & key , const char * default_ ) const ;
130 ///< Returns a string value from the map.
131
132 bool booleanValue( const std::string & key , bool default_ ) const ;
133 ///< Returns a boolean value from the map. Returns true if
134 ///< the key exists with an empty value. Returns the default
135 ///< if no such key.
136
137 void remove( const std::string & key ) ;
138 ///< Removes a value (if it exists).
139
140 const G::StringMap & map() const ;
141 ///< Returns a reference to the internal map.
142
143 void log( const std::string & prefix = std::string() ) const ;
144 ///< Logs the contents.
145
146 std::string expand( const std::string & value ) const ;
147 ///< Does one-pass variable substitution for the given string.
148 ///< Sub-strings like "%xyz%" are replaced by 'value("xyz")'
149 ///< and "%%" is replaced by "%". If there is no appropriate
150 ///< value in the map then the sub-string is left alone
151 ///< (so "%xyz%" remains as "%xyz%" if there is no "xyz"
152 ///< map item).
153
154 G::Path expandedPathValue( const std::string & key ) const ;
155 ///< Returns a mandatory path value from the map
156 ///< with expand(). Throws if it does not exist.
157
158 G::Path expandedPathValue( const std::string & key , const G::Path & default_ ) const ;
159 ///< Returns a path value from the map with expand().
160
161 private:
162 using List = std::list<std::string> ;
163 void readFrom( const G::Path & , const std::string & ) ;
164 void readFrom( std::istream & ss ) ;
165 static std::string quote( const std::string & ) ;
166 List read( const G::Path & , const std::string & , bool ) const ;
167 void commentOut( List & ) const ;
168 void replace( List & ) const ;
169 bool expand_( std::string & ) const ;
170 std::string expandAll( const std::string & ) const ;
171 static void backup( const G::Path & ) ;
172 static void save( const G::Path & , List & , bool ) ;
173 std::string mandatoryValue( const std::string & ) const ;
174 bool ignore( const std::string & ) const ;
175 static std::string ekind( const std::string & ) ;
176 static std::string epath( const G::Path & ) ;
177 static Error readError( const G::Path & , const std::string & ) ;
178 static Error writeError( const G::Path & , const std::string & = std::string() ) ;
179 static Error missingValueError( const G::Path & , const std::string & , const std::string & ) ;
180
181 private:
182 G::Path m_path ; // if any
183 std::string m_kind ;
184 G::StringMap m_map ;
185 G::StringArray m_keys ; // kept in input order
186} ;
187
188#endif
G::Exception
A general-purpose exception class derived from std::exception and containing an error message.
Definition: gexception.h:45
G::Exception::Exception
Exception(const char *what)
Constructor.
Definition: gexception.cpp:61
G::MapFile
A class for reading, writing and editing key=value files, supporting variable expansion of percent-ke...
Definition: gmapfile.h:57
G::MapFile::check
static void check(const G::Path &, const std::string &kind=std::string())
Throws if the file is invalid.
Definition: gmapfile.cpp:138
G::MapFile::expand
std::string expand(const std::string &value) const
Does one-pass variable substitution for the given string.
Definition: gmapfile.cpp:335
G::MapFile::editInto
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.
Definition: gmapfile.cpp:177
G::MapFile::booleanValue
bool booleanValue(const std::string &key, bool default_) const
Returns a boolean value from the map.
Definition: gmapfile.cpp:262
G::MapFile::numericValue
unsigned int numericValue(const std::string &key, unsigned int default_) const
Returns a numeric value from the map.
Definition: gmapfile.cpp:318
G::MapFile::add
void add(const std::string &key, const std::string &value, bool clear=false)
Adds or updates a single item in the map.
Definition: gmapfile.cpp:405
G::MapFile::map
const G::StringMap & map() const
Returns a reference to the internal map.
Definition: gmapfile.cpp:428
G::MapFile::remove
void remove(const std::string &key)
Removes a value (if it exists).
Definition: gmapfile.cpp:324
G::MapFile::pathValue
G::Path pathValue(const std::string &key) const
Returns a mandatory path value from the map.
Definition: gmapfile.cpp:298
G::MapFile::MapFile
MapFile()
Constructor for an empty map.
G::MapFile::contains
bool contains(const std::string &key) const
Returns true if the map contains the given key.
Definition: gmapfile.cpp:423
G::MapFile::expandedPathValue
G::Path expandedPathValue(const std::string &key) const
Returns a mandatory path value from the map with expand().
Definition: gmapfile.cpp:303
G::MapFile::keys
const G::StringArray & keys() const
Returns a reference to the internal ordered list of keys.
Definition: gmapfile.cpp:433
G::MapFile::log
void log(const std::string &prefix=std::string()) const
Logs the contents.
Definition: gmapfile.cpp:144
G::MapFile::writeItem
void writeItem(std::ostream &, const std::string &key) const
Writes a single item from this map to the stream.
Definition: gmapfile.cpp:160
G::MapFile::value
std::string value(const std::string &key, const std::string &default_=std::string()) const
Returns a string value from the map.
Definition: gmapfile.cpp:279
G::OptionMap
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:42
G::Path
A Path object represents a file system path.
Definition: gpath.h:72
gexception.h
goptionmap.h
goptions.h
goptionvalue.h
gpath.h
gstrings.h
G
Low-level classes.
Definition: galign.h:28
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:31
G::StringMap
std::map< std::string, std::string > StringMap
A std::map of std::strings.
Definition: gstrings.h:32
G::MapFile::Error
Exception class for G::MapFile.
Definition: gmapfile.h:60