E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

gmapfile.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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 and editing key=value files, supporting comments,
42 /// creation of backup files, variable expansion and logging.
43 /// \see G::OptionValue
44 ///
45 class G::MapFile
46 {
47 public:
48 G_EXCEPTION( ReadError , "cannot open map file" ) ;
49 G_EXCEPTION( WriteError , "cannot write map file" ) ;
50 G_EXCEPTION( Missing , "cannot find map file item" ) ;
51
52 MapFile() ;
53 ///< Constructor for an empty map.
54
55 explicit MapFile( const G::StringMap & map ) ;
56 ///< Constructor that initialises from a string map.
57
58 explicit MapFile( const OptionMap & map , const std::string & yes = std::string() ) ;
59 ///< Constructor that initialises from an option value map,
60 ///< typically parsed out from a command-line. Unvalued 'true'
61 ///< options in the option value map are loaded into this
62 ///< mapfile object with a value given by the 'yes' parameter,
63 ///< whereas unvalued 'false' options are not loaded.
64 ///< Multi-valued options are loaded as a comma-separated
65 ///< list.
66
67 explicit MapFile( const G::Path & ) ;
68 ///< Constructor that reads from a file. Lines can have a key
69 ///< and no value (see booleanValue()). Comments must be at
70 ///< the start of the line. Values are trimmed, but can
71 ///< otherwise contain whitespace.
72
73 explicit MapFile( std::istream & ) ;
74 ///< Constructor that reads from a stream.
75
76 const G::StringArray & keys() const ;
77 ///< Returns a reference to the ordered list of keys.
78
79 static void check( const G::Path & ) ;
80 ///< Throws if the file is invalid. This is equivalent to
81 ///< constructing a temporary MapFile object, but it
82 ///< specifically does not do any logging.
83
84 void add( const std::string & key , const std::string & value ) ;
85 ///< Adds or updates a single item in the map.
86
87 void writeItem( std::ostream & , const std::string & key ) const ;
88 ///< Writes a single item from this map to the stream.
89
90 static void writeItem( std::ostream & , const std::string & key , const std::string & value ) ;
91 ///< Writes an arbitrary item to the stream.
92
93 void editInto( const G::Path & path , bool make_backup ,
94 bool allow_read_error , bool allow_write_error ) const ;
95 ///< Edits an existing file so that its contents
96 ///< reflect this map.
97
98 bool contains( const std::string & key ) const ;
99 ///< Returns true if the map contains the given key.
100
101 G::Path pathValue( const std::string & key ) const ;
102 ///< Returns a mandatory path value from the map.
103 ///< Throws if it does not exist.
104
105 G::Path pathValue( const std::string & key , const G::Path & default_ ) const ;
106 ///< Returns a path value from the map.
107
108 unsigned int numericValue( const std::string & key , unsigned int default_ ) const ;
109 ///< Returns a numeric value from the map.
110
111 std::string value( const std::string & key , const std::string & default_ = std::string() ) const ;
112 ///< Returns a string value from the map. Returns the default
113 ///< if there is no such key or if the value is empty.
114
115 std::string value( const std::string & key , const char * default_ ) const ;
116 ///< Returns a string value from the map.
117
118 bool booleanValue( const std::string & key , bool default_ ) const ;
119 ///< Returns a boolean value from the map. Returns true if
120 ///< the key exists with an empty value. Returns the default
121 ///< if no such key.
122
123 void remove( const std::string & key ) ;
124 ///< Removes a value (if it exists).
125
126 const G::StringMap & map() const ;
127 ///< Returns a reference to the internal map.
128
129 void log() const ;
130 ///< Logs the contents.
131
132 std::string expand( const std::string & value ) const ;
133 ///< Does one-pass variable substitution for the given string.
134 ///< Sub-strings like "%xyz%" are replaced by 'value("xyz")'
135 ///< and "%%" is replaced by "%". If there is no appropriate
136 ///< value in the map then the sub-string is left alone
137 ///< (so "%xyz%" remains as "%xyz%" if there is no "xyz"
138 ///< map item).
139
140 G::Path expandedPathValue( const std::string & key ) const ;
141 ///< Returns a mandatory path value from the map
142 ///< with expand(). Throws if it does not exist.
143
144 G::Path expandedPathValue( const std::string & key , const G::Path & default_ ) const ;
145 ///< Returns a path value from the map with expand().
146
147 private:
148 typedef std::list<std::string> List ;
149 void readFrom( const G::Path & ) ;
150 void readFrom( std::istream & ss ) ;
151 static std::string quote( const std::string & ) ;
152 List read( const G::Path & , bool ) const ;
153 void commentOut( List & ) const ;
154 void replace( List & ) const ;
155 bool expand_( std::string & ) const ;
156 std::string expandAll( const std::string & ) const ;
157 static void backup( const G::Path & ) ;
158 static void save( const G::Path & , List & , bool ) ;
159 void log( const std::string & , const std::string & ) const ;
160 static void log( bool , const std::string & , const std::string & ) ;
161 std::string mandatoryValue( const std::string & ) const ;
162 bool ignore( const std::string & ) const ;
163
164 private:
165 bool m_logging ;
166 G::StringMap m_map ;
167 G::StringArray m_keys ; // kept in input order
168 } ;
169
170 #endif
goptions.h
gstrings.h
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:286
goptionmap.h
G::MapFile::keys
const G::StringArray & keys() const
Returns a reference to the ordered list of keys.
Definition: gmapfile.cpp:426
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:33
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:185
goptionvalue.h
G::MapFile::check
static void check(const G::Path &)
Throws if the file is invalid.
Definition: gmapfile.cpp:139
G::OptionMap
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:39
G::MapFile::pathValue
G::Path pathValue(const std::string &key) const
Returns a mandatory path value from the map.
Definition: gmapfile.cpp:305
G::MapFile::contains
bool contains(const std::string &key) const
Returns true if the map contains the given key.
Definition: gmapfile.cpp:416
G::MapFile::map
const G::StringMap & map() const
Returns a reference to the internal map.
Definition: gmapfile.cpp:421
G::MapFile::expandedPathValue
G::Path expandedPathValue(const std::string &key) const
Returns a mandatory path value from the map with expand().
Definition: gmapfile.cpp:310
G
Low-level classes.
Definition: garg.h:29
G::MapFile
A class for reading and editing key=value files, supporting comments, creation of backup files...
Definition: gmapfile.h:45
G::MapFile::numericValue
unsigned int numericValue(const std::string &key, unsigned int default_) const
Returns a numeric value from the map.
Definition: gmapfile.cpp:325
G::MapFile::add
void add(const std::string &key, const std::string &value)
Adds or updates a single item in the map.
Definition: gmapfile.cpp:409
G::MapFile::expand
std::string expand(const std::string &value) const
Does one-pass variable substitution for the given string.
Definition: gmapfile.cpp:342
G::MapFile::MapFile
MapFile()
Constructor for an empty map.
Definition: gmapfile.cpp:36
G::MapFile::booleanValue
bool booleanValue(const std::string &key, bool default_) const
Returns a boolean value from the map.
Definition: gmapfile.cpp:269
gexception.h
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:167
gpath.h
G::StringMap
std::map< std::string, std::string > StringMap
A std::map of std::strings.
Definition: gstrings.h:34
G::Path
A Path object represents a file system path.
Definition: gpath.h:72
G::MapFile::log
void log() const
Logs the contents.
Definition: gmapfile.cpp:146