rudeconfig(3)

1rudeconfig(3)                    User Manuals                    rudeconfig(3)
2
3
4

NAME

6       rudeconfig - read and manipulate .ini and config files
7

SYNOPSIS

9       #include <rude/config.h>
10
11       rude::Config myconfig;
12
13
14       STATIC METHODS
15       static const char *rude::version();
16
17       static void rude::setDefaultConfigFile(const char *filepath);
18
19       static const char *rude::getDefaultConfigFile();
20
21       static void rude::setDefaultCommentCharacter(char c);
22
23       static char rude::getDefaultCommentCharacter();
24
25       static void rude::setDefaultDelimiter(char c);
26
27       static char rude::getDefaultDelimiter();
28
29       static void rude::setDefaultPreserveDeleted(bool shouldPreserve);
30
31       static void rude::setDefaultPreserveDeleted(bool shouldPreserve);
32
33
34       REDEFINING INSTANCE BEHAVIOR
35       void setConfigFile(const char *filepath);
36
37       const char * getConfigFile();
38
39       void preserveDeletedData(bool shouldPreserve);
40
41       void setCommentCharacter(char commentchar);
42
43       void setDelimiter(char keyvaluedelimiter);
44
45
46       LOADING AND SAVING FILES
47       bool save();
48
49       bool save(const char *filepath);
50
51       void clear();
52
53       bool load();
54
55       bool load(const char *filename);
56
57       const char *getError();
58
59
60       SECTION METHODS
61       int getNumSections() const;
62
63       const char *getSectionNameAt(int index) const;
64
65       bool setSection(const char *sectionname, bool shouldCreate);
66
67       bool setSection(const char *sectionname);
68
69       bool deleteSection(const char *sectionname);
70
71
72       KEY/VALUE DISCOVERY METHODS
73       int getNumDataMembers() const;
74
75       const char *getDataNameAt(int index) const;
76
77       bool exists(const char *name) const;
78
79
80       DATA ACCESSORS
81       bool getBoolValue(const char *name) const;
82
83       int getIntValue(const char *name) const;
84
85       double getDoubleValue(const char *name) const;
86
87       const char * getValue(const char *name) const;
88
89       const char * getStringValue(const char *name) const;
90
91
92       DATA MUTATORS
93       void setBoolValue(const char *name, bool value);
94
95       void setIntValue(const char *name, int value);
96
97       void setDoubleValue(const char *name, double value");
98
99       void setValue(const char *name, const char *value);
100
101       void setStringValue(const char *name, const char *value);
102
103
104       KEY/VALUE DELETION
105       bool deleteData(const char *name);
106
107       DESTRUCTOR
108       ~Config();
109
110

DESCRIPTION

112       The rudeConfig library is used to read and manipulate .ini and configu‐
113       ration files.
114
115

CONFIGURATION/.INI FILE FORMAT

117       Configuration and .ini files have the following structure:
118
119       A configuration file contains one or more "sections".   Each  "section"
120       contains  0 or more "key=value" pairs.  Sections can also contain blank
121       lines and comments
122
123
124       Sections are identified by the section name surrounded by square brack‐
125       ets - like [example section].  The unnamed, or default section, is rep‐
126       resented by empty square brackets - as in [].   The  beginning  of  the
127       configuration  file,  up to the first named section, is also considered
128       part of the unnamed/default section.  White space surrounding the  sec‐
129       tion  name is ignored.  Quotes can be used in section names if desired.
130       As such, the following section names are identical:
131
132       [State Codes]
133       [  State Codes  ]
134       [ "State Codes" ]
135
136
137       The default delimiter for key/value pairs is the equals (=) sign.   The
138       default  comment  character  is the hash (#).  These can be changed via
139       the API to any character, with a few restrictions: The key/value delim‐
140       iter  cannot  be '\' (escape), '[' (left square bracket), or any end of
141       line character.  The comment character  cannot  be  '\'  (escape),  '['
142       (left   square  bracket)  or  '"'  (double  quote).   Furthermore,  the
143       key/value delimiter cannot be set to the  same  value  as  the  comment
144       character.
145
146
147       The key of each key/value pair within a section must be unique.  If the
148       same key appears more than once within a given  section,  all  but  the
149       last  key  will be ignored.  If more than one configuration file is are
150       loaded into the same rude::Config  object,  duplicate  key/value  pairs
151       will replace existing ones.
152
153       Although sections of a given name can be repeated in a physical config‐
154       uration file, they are logically combined when the  rude:Config  object
155       parses the file.  If the rude:Config object is subsequently saved, then
156       the sections will be merged- with all  key/value  pairs  occurring  one
157       section.   An  example of multiple sections with the same name is given
158       here:
159
160       # beginning of example .ini file
161       [State Codes]
162       AZ = Arizona
163       CO = Colorado
164       [State Codes]
165       NY = New York
166       CA = California
167       [State Codes]
168       PA = Pennsylvania
169       IL = Illinios
170       #end of example .ini file
171
172
173       Comments do not have to start at the beginning of  a  line.   They  can
174       appear  after  section  declarations  (on  the  same line) and they can
175       appear after key=value pairs.
176
177       # -- first line of config file --
178       # this is in the default section
179       # this is a comment
180       # the following line is a key=value pair
181       color=blue
182       [contact information]
183       # this is a new section
184       first name=Matthew
185       last name = Flood   # comments are allowed after key=value pairs
186       []
187       # since there is no section name, this is the default section again
188       size=large
189       [login info]
190       username=scruffy
191       password=$$324reeWrew65456
192       [contact information]
193       # this section is a continuation of contact information section listed earlier
194       #
195       # the following key=value pair demonstrates using quotes for multi-line values
196       address="111 example street
197       apartment Z"
198       city=boulder
199       # -- end of config file --
200
201
202

EXAMPLES

204       Examples, how-to's and  tutorials  can  also  be  found  at  the  rude‐
205       server.com website
206
207       Basic Usage
208
209        #include <rude/config.h>
210
211        int main(void)
212        {
213           // Create config object
214           //
215           rude::Config config;
216
217           // load a configuration/.ini file
218           config.load("myfile.ini");
219
220
221           // read information
222           //
223           config.setSection("General Info");
224           double cost = config.getDoubleValue("Cost");
225           const char *company = config.getStringValue("Company Name");
226
227
228           // create information
229           //
230           config.setSection("new section");
231           config.setStringValue("animal type", "giraffe");
232           config.setBoolValue("mammal", true);
233
234           // save changes
235           //
236           config.save();
237           return 0;
238        }
239

REPORTING PROBLEMS

245       Before reporting a problem, please check the rudeserver.com web site to
246       verify that you have  the  latest  version  of  rudeconfig;  otherwise,
247       obtain  the latest version and see if the problem still exists.  Please
248       read the  FAQ at:
249
250                     http://www.rudeserver.com/
251
252       before asking for help.  Send questions and/or comments to   matt@rude‐
253       server.com
254
255

AUTHORS

257       Copyright (C) 2000 Matthew Flood (matt@rudeserver.com)
258
259       This  software is provided "as-is," without any express or implied war‐
260       ranty.  In no event will the authors be held  liable  for  any  damages
261       arising  from the use of this software.  See the distribution directory
262       with respect  to  requirements  governing   redistribution.  Thanks  to
263       all the people who reported problems and suggested various improvements
264       in rudeconfig; who are too numerous to cite here.
265
266
267
268
269Version 5.0                    January 19, 2006                  rudeconfig(3)