E-MailRelay
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 ///
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
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
const G::StringArray & keys() const
Returns a reference to the ordered list of keys.
Definition: gmapfile.cpp:426
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:33
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
static void check(const G::Path &)
Throws if the file is invalid.
Definition: gmapfile.cpp:139
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:39
G::Path pathValue(const std::string &key) const
Returns a mandatory path value from the map.
Definition: gmapfile.cpp:305
bool contains(const std::string &key) const
Returns true if the map contains the given key.
Definition: gmapfile.cpp:416
const G::StringMap & map() const
Returns a reference to the internal map.
Definition: gmapfile.cpp:421
G::Path expandedPathValue(const std::string &key) const
Returns a mandatory path value from the map with expand().
Definition: gmapfile.cpp:310
Low-level classes.
Definition: garg.h:29
A class for reading and editing key=value files, supporting comments, creation of backup files...
Definition: gmapfile.h:45
unsigned int numericValue(const std::string &key, unsigned int default_) const
Returns a numeric value from the map.
Definition: gmapfile.cpp:325
void add(const std::string &key, const std::string &value)
Adds or updates a single item in the map.
Definition: gmapfile.cpp:409
std::string expand(const std::string &value) const
Does one-pass variable substitution for the given string.
Definition: gmapfile.cpp:342
MapFile()
Constructor for an empty map.
Definition: gmapfile.cpp:36
bool booleanValue(const std::string &key, bool default_) const
Returns a boolean value from the map.
Definition: gmapfile.cpp:269
void writeItem(std::ostream &, const std::string &key) const
Writes a single item from this map to the stream.
Definition: gmapfile.cpp:167
std::map< std::string, std::string > StringMap
A std::map of std::strings.
Definition: gstrings.h:34
A Path object represents a file system path.
Definition: gpath.h:72
void log() const
Logs the contents.
Definition: gmapfile.cpp:146