]>
Dogcows Code - chaz/yoink/blob - src/stlplus/subsystems/ini_manager.hpp
1 #ifndef STLPLUS_INI_MANAGER
2 #define STLPLUS_INI_MANAGER
3 ////////////////////////////////////////////////////////////////////////////////
5 // Author: Andy Rushton
6 // Copyright: (c) Southampton University 1999-2004
7 // (c) Andy Rushton 2004-2009
8 // License: BSD License, see ../docs/license.html
10 // A subsystem for managing INI (i.e. .ini) files
11 // An INI file has the following format
13 // file ::= header { section }*
14 // header ::= { comment | blank }*
15 // section ::= section_header { declaration | comment | blank }*
16 // section_header ::= '[' title ']' '\n'
17 // declaration ::= variable '=' value '\n'
18 // comment ::= ';' text '\n'
21 // variable ::= [~'=']*
25 // Whitespace is trimmed from the leading and trailing ends of title, variable and value
26 // Note: a header is represented internally as a Clint section (i.e. a section with no name)
28 ////////////////////////////////////////////////////////////////////////////////
29 #include "subsystems_fixes.hpp"
37 ////////////////////////////////////////////////////////////////////////////////
40 class ini_manager_body
;
42 ////////////////////////////////////////////////////////////////////////////////
43 // Ini-file manager class
51 explicit ini_manager(const std::vector
<std::string
>& filenames
);
53 ini_manager(const ini_manager
&);
54 ini_manager
& operator= (const ini_manager
&);
58 //////////////////////////////////////////////////////////////////////////////
61 // add files starting with the most local file (e.g. the current project) which has depth 0
62 // and working back to the most global (e.g. the installation settings) which has a depth of size()-1
63 // This does nothing if the file has already been loaded - it is not permitted to manage the same file twice.
64 // Returns true if the file loaded okay or was already loaded (it is counted as successful if the file did
65 // not exist, only read errors cause a failure)
66 bool add_file(const std::string
& filename
);
68 // as above, returns false if *none* of the files were added
69 // filenames[0] is the local file, and so on
70 bool add_files(const std::vector
<std::string
>& filenames
);
72 // saves modified ini files - returns true if all modified files were written successfully
75 // get the number of files being managed
76 unsigned size(void) const;
78 // get the ini filename associated with a depth
79 std::string
filename(unsigned depth
= 0) const;
81 // test whether a file in the ini manager is writable
82 bool writable(unsigned depth
= 0) const;
84 // test whether a file is empty
85 // An ini file is considered empty if it has no named sections and the header is empty or missing
86 bool empty(unsigned depth
= 0) const;
88 // erase the ini file from the ini manager and from the disk
89 bool erase(unsigned depth
= 0);
91 // remove the file from the ini manager but do not erase it from the disk
92 bool remove(unsigned depth
= 0);
94 //////////////////////////////////////////////////////////////////////////////
97 // returns the union of all section names in all of the ini files
98 std::vector
<std::string
> section_names(void) const;
100 // returns the section names in one of the ini files
101 std::vector
<std::string
> section_names(unsigned depth
) const;
103 // tests whether a section is found in any of the ini files
104 bool section_exists(const std::string
& title
) const;
106 // tests whether the section is found in the specific ini file
107 bool section_exists(const std::string
& title
, unsigned depth
) const;
109 // adds a section to the specified ini file - does nothing if it is already present
110 bool add_section(const std::string
& section
, unsigned depth
= 0);
112 // test whether a section is empty
113 bool empty_section(const std::string
& section
, unsigned depth
= 0);
115 // removes a section from the specified ini file if it exists there but cannot remove it from any other file
116 bool erase_section(const std::string
& section
, unsigned depth
= 0);
118 // removes all the contents of a section from the specified ini file but keeps the empty section
119 bool clear_section(const std::string
& section
, unsigned depth
= 0);
121 //////////////////////////////////////////////////////////////////////////////
122 // variable management
124 // test whether a variable exists in any of the ini files
125 bool variable_exists(const std::string
& section
, const std::string variable
) const;
127 // test whether a variable exists in specified ini file
128 bool variable_exists(const std::string
& section
, const std::string variable
, unsigned depth
) const;
130 // get the union of all variables declared in all ini files
131 std::vector
<std::string
> variable_names(const std::string
& section
) const;
133 // get the set of all varaibale names from one file
134 std::vector
<std::string
> variable_names(const std::string
& section
, unsigned depth
) const;
136 // get the depth of the first ini file to define a variable
137 // returns 0 if defined in the local ini file, etc. Returns (unsigned)-1 if the variable doesn't exist
138 unsigned variable_depth(const std::string
& section
, const std::string variable
) const;
140 // get the filename that first defines the variable
141 std::string
variable_filename(const std::string
& section
, const std::string variable
) const;
142 // ditto for its linenumber within that file
143 unsigned variable_linenumber(const std::string
& section
, const std::string variable
) const;
145 // get the value of a variable as a single unprocessed string
146 // if the variable does not exist the string will be empty, but beware that
147 // you also get an empty string if a variable exists but has no value
148 // you can differentiate between the two cases by using variable_exists_all above
149 std::string
variable_value(const std::string
& section
, const std::string variable
) const;
151 // get the value from the specified file
152 std::string
variable_value(const std::string
& section
, const std::string variable
, unsigned depth
) const;
154 // get the value of a variable as a processed string
155 // processing splits the value at commas and furthermore supports quoted strings (so that values can contain commas for example)
156 // quoted strings are dequoted before they are added to the result
157 // the result is a vector of dequoted strings, one per value in the comma-separated list
158 std::vector
<std::string
> variable_values(const std::string
& section
, const std::string variable
) const;
160 // get the processed variable from the specified file
161 std::vector
<std::string
> variable_values(const std::string
& section
, const std::string variable
, unsigned depth
) const;
163 // add a variable to the specified file
164 bool add_variable(const std::string
& section
, const std::string
& variable
, const std::string
& value
, unsigned depth
= 0);
166 // add a variable as a processed string
167 // processing means that the values in the string vector are converted into a comma-separated list
168 // values containing reserved characters are automatically quoted - so you should not even try to quote them yourself
169 bool add_variable(const std::string
& section
, const std::string
& variable
, const std::vector
<std::string
>& values
, unsigned depth
= 0);
171 // erase a variable from the specified file
172 // this does not remove the variable from other ini files, so the variable may still exist
173 // to mask a global variable, set the variable to an empty string instead
174 bool erase_variable(const std::string
& section
, const std::string
& variable
, unsigned depth
= 0);
176 //////////////////////////////////////////////////////////////////////////////
177 // sundry line-entry management
179 // add a comment to the specified ini file
180 bool add_comment(const std::string
& section
, const std::string
& comment
, unsigned depth
= 0);
182 // add a blank line to the specified ini file
183 bool add_blank(const std::string
& section
, unsigned depth
= 0);
185 bool print(std::ostream
&) const;
188 friend class ini_manager_body
;
189 ini_manager_body
* m_body
;
192 ////////////////////////////////////////////////////////////////////////////////
193 // diagnostic print routine
195 std::ostream
& operator << (std::ostream
&, const ini_manager
&);
197 ////////////////////////////////////////////////////////////////////////////////
199 } // end namespace stlplus
This page took 0.038561 seconds and 4 git commands to generate.