root/misc/configparse.html

Revision 97, 9.4 kB (checked in by KirkMcDonald, 5 years ago)

configparse doc update

Line 
1 <html><head>
2     <META http-equiv="content-type" content="text/html; charset=utf-8">
3     <title>configparse</title>
4     </head><body>
5     <h1>configparse</h1>
6     <!-- Generated by Ddoc from configparse.d -->
7 Configuration file parsing, in the style of Python's ConfigParser.
8 <br><br>
9 Config files are divided into sections, which contain options. Section headers
10 are in the form "[section name]". Options may be in either the form "key=value"
11 or "key: value". A given line may only contain a single option or section
12 header. Whitespace is stripped from the beginnings and ends of keys and values.
13 <br><br>
14
15 Options existing before any section headers are said to be in the global
16 section. This is treated as a section named "General". It is entirely possible
17 to use config files only containing options that are in the global section, and
18 to write code which doesn't even seem to know about the ability to divide
19 options into sections.
20 <br><br>
21
22 Lines beginning with '#' or ';' are treated as comments and ignored.
23 <br><br>
24
25 <dl><dt><big>class <u>ConfigParseError</u>: object.Exception;
26 </big></dt>
27 <dd>Thrown when configparse is unable to parse a file.
28 <br><br>
29
30 <dl></dl>
31 </dd>
32 <dt><big>class <u>ConfigConvertError</u>: object.Exception;
33 </big></dt>
34 <dd>Thrown when configparse is unable to coerce a value to a requested type.
35 <br><br>
36
37 <dl></dl>
38 </dd>
39 <dt><big>class <u>DuplicateSectionError</u>: object.Exception;
40 </big></dt>
41 <dd>Thrown when user adds already-existing section to parser.
42 <br><br>
43
44 <dl></dl>
45 </dd>
46 <dt><big>class <u>SectionNotFoundError</u>: object.Exception;
47 </big></dt>
48 <dd>Thrown when a section is not found.
49 <br><br>
50
51 <dl></dl>
52 </dd>
53 <dt><big>class <u>OptionNotFoundError</u>: object.Exception;
54 </big></dt>
55 <dd>Thrown when an option is not found.
56 <br><br>
57
58 <dl></dl>
59 </dd>
60 <dt><big>const char[] <u>GLOBAL_SECTION</u>;
61 </big></dt>
62 <dd>The name of the global section. This is currently "General".
63 <br><br>
64
65 </dd>
66 <dt><big>char[] <u>same_dir</u>(char[] <i>arg0</i>, char[] <i>filename</i>);
67 </big></dt>
68 <dd>Returns the path of a config file (<i>filename</i>) in the same directory as the
69 executable (<i>arg0</i>).
70 <br><br>
71
72 </dd>
73 <dt><big>char[][] <u>config_files</u>(char[] <i>arg0</i>, char[] <i>name</i> = null);
74 </big></dt>
75 <dd>Returns a nice "default" list of config files. <i>arg0</i> should be the first element
76 of the args array passed to main(). The optional <i>name</i> parameter should be the name of the config file,
77 minus any extension. It defaults to the executable's name, minus any directory
78 or extension.
79 <br><br>
80 On Windows, the returned filenames are:
81 <ul>   <li><i>name</i>.ini alongside the .exe</li>
82     <li>%HOMEDRIVE%%HOMEPATH%\<i>name</i>.ini</li>
83     <li>.\<i>name</i>.ini</li>
84 </ul>
85 <br><br>
86
87 On all other platforms (e.g. Linux), the returned filenames are:
88 <ul>   <li>/etc/<i>name</i>.conf</li>
89     <li><i>name</i>.ini alongside the binary</li>
90     <li>~/.namerc</li>
91     <li>./<i>name</i>.conf</li>
92 </ul>
93 <br><br>
94
95 </dd>
96 <dt><big>class <u>ConfigParser</u>;
97 </big></dt>
98 <dd>The <u>ConfigParser</u> class represents a config file.
99 <br><br>
100
101 <dl><dt><big>char[][] <u>sections</u>();
102 </big></dt>
103 <dd>Returns a list of the sections in the parser, including the global
104     section. ("General" by default.)
105    
106 <br><br>
107
108 </dd>
109 <dt><big>void <u>add_section</u>(char[] <i>name</i>);
110 </big></dt>
111 <dd>Adds a section named <i>name</i> to the parser.
112 <br><br>
113 <b>Throws:</b><br>
114 DuplicateSectionError if the section already exists.
115    
116 <br><br>
117
118 </dd>
119 <dt><big>bool <u>has_section</u>(char[] <i>name</i>);
120 </big></dt>
121 <dd>Requests if a section exists in the parser.
122 <br><br>
123
124 </dd>
125 <dt><big>char[][] <u>options</u>(char[] <i>section</i> = "General");
126 </big></dt>
127 <dd>Returns a list of options in the given <i>section</i>.
128 <br><br>
129 <b>Throws:</b><br>
130 SectionNotFoundError
131    
132 <br><br>
133
134 </dd>
135 <dt><big>char[][] <u>values</u>(char[] <i>section</i> = "General");
136 </big></dt>
137 <dd>Returns a list of values in the given <i>section</i>.
138 <br><br>
139 <b>Throws:</b><br>
140 SectionNotFoundError
141    
142 <br><br>
143
144 </dd>
145 <dt><big>bool <u>has_option</u>(char[] <i>section</i>, char[] <i>option</i> = null);
146 </big></dt>
147 <dd>Returns whether the given <i>option</i> exists in the given <i>section</i>. This method
148     (and all of the others in this form) will set <i>option</i> to <i>section</i>, and
149     <i>section</i> to the global section, when only one argument is provided. (In
150     other words, providing only one argument will check for options in the
151     global section.) This will silently return <b>false</b> if the <i>section</i> does not
152     exist.
153    
154 <br><br>
155
156 </dd>
157 <dt><big>char[][] <u>read</u>(char[][] <i>filenames</i>...);
158 </big></dt>
159 <dd>Reads a series of files into the parser, in the order provided. Files that
160     don't exist will be silently skipped. Options specified in later files will
161     override those specified in earlier files.
162 <br><br>
163 <b>Returns:</b><br>
164 A list of files read in.
165 <br><br>
166 <b>Throws:</b><br>
167 ConfigParseError if a file contains errors.
168    
169 <br><br>
170
171 </dd>
172 <dt><big>void <u>read</u>(Stream <i>file</i>, char[] <i>filename</i> = "");
173 </big></dt>
174 <dd>Reads in any Stream as a config file.
175 <br><br>
176 <b>Params:</b><br>
177 <table><tr><td>char[] <i>filename</i></td>
178 <td>An optional argument for clarifying error output.</td></tr>
179 </table><br>
180 <b>Throws:</b><br>
181 ConfigParseError if the stream contains errors.
182    
183 <br><br>
184
185 </dd>
186 <dt><big>char[] <u>opIndex</u>(char[] <i>section</i>, char[] <i>option</i> = null);
187 </big></dt>
188 <dd>Retrieves the value of an <i>option</i> in the given <i>section</i>. If only one argument
189     is supplied, it is treated as an option in the global section.
190 <br><br>
191 <b>Throws:</b><br>
192 SectionNotFoundError if the <i>section</i> doesn't exist.
193         OptionNotFoundError if the <i>option</i> doesn't exist.
194    
195 <br><br>
196
197 </dd>
198 <dt><big>alias <u>get</u>;
199 </big></dt>
200 <dd>An alias of opIndex.
201 <br><br>
202
203 </dd>
204 <dt><big>int <u>getint</u>(char[] <i>section</i>, char[] <i>option</i> = null);
205 </big></dt>
206 <dd>Retrieves the value of an <i>option</i> in the given <i>section</i> in a manner identical
207     to opIndex, and attempts to convert it to an integer.
208 <br><br>
209 <b>Throws:</b><br>
210 ConfigConvertError if the value cannot be converted.
211    
212 <br><br>
213
214 </dd>
215 <dt><big>real <u>getreal</u>(char[] <i>section</i>, char[] <i>option</i> = null);
216 </big></dt>
217 <dd>Retrieves the value of an <i>option</i> in the given <i>section</i> in a manner identical
218     to opIndex, and attempts to convert it to a real.
219 <br><br>
220 <b>Throws:</b><br>
221 ConfigConvertError if the value cannot be converted.
222    
223 <br><br>
224
225 </dd>
226 <dt><big>bool <u>getbool</u>(char[] <i>section</i>, char[] <i>option</i> = null);
227 </big></dt>
228 <dd>Retrieves the value of an <i>option</i> in the given <i>section</i> in a manner identical
229     to opIndex, and attempts to convert it to a boolean. The value is first
230     converted to lower-case. The accepted values for <b>true</b> are "yes," "true,"
231     "on," and "1." The accepted values for <b>false</b> are "no," "false," "off," and
232     "0."
233 <br><br>
234 <b>Throws:</b><br>
235 ConfigConvertError if the value cannot be converted.
236    
237 <br><br>
238
239 </dd>
240 <dt><big>void <u>opIndexAssign</u>(char[] <i>value</i>, char[] <i>section</i>, char[] <i>option</i> = null);
241 </big></dt>
242 <dd>Stores <i>value</i> to <i>option</i> in <i>section</i>. If <i>option</i> is not supplied, <i>section</i> is
243     treated like an option in the global section.
244 <br><br>
245 <b>Throws:</b><br>
246 SectionNotFoundError if <i>section</i> does not exist.
247    
248 <br><br>
249
250 </dd>
251 <dt><big>void <u>opIndexAssign</u>(int <i>value</i>, char[] <i>section</i>, char[] <i>option</i> = null);
252 </big></dt>
253 <dd>Calls <u>opIndexAssign</u> after converting <i>value</i> to a string.
254    
255 <br><br>
256
257 </dd>
258 <dt><big>void <u>opIndexAssign</u>(real <i>value</i>, char[] <i>section</i>, char[] <i>option</i> = null);
259 </big></dt>
260 <dd>Calls <u>opIndexAssign</u> after converting <i>value</i> to a string.
261    
262 <br><br>
263
264 </dd>
265 <dt><big>void <u>opIndexAssign</u>(bool <i>value</i>, char[] <i>section</i>, char[] <i>option</i> = null);
266 </big></dt>
267 <dd>Calls <u>opIndexAssign</u> after converting <i>value</i> to a string.
268    
269 <br><br>
270
271 </dd>
272 <dt><big>void <u>remove_option</u>(char[] <i>section</i>, char[] <i>option</i> = null);
273 </big></dt>
274 <dd>Removes the specified <i>option</i> in <i>section</i>. Silently does nothing if <i>option</i>
275     does not exist.
276 <br><br>
277 <b>Throws:</b><br>
278 SectionNotFoundError if the <i>section</i> does not exist.
279    
280 <br><br>
281
282 </dd>
283 <dt><big>void <u>remove_section</u>(char[] <i>section</i>);
284 </big></dt>
285 <dd>Removes <i>section</i>. Silently does nothing if <i>section</i> does not exist.
286    
287 <br><br>
288
289 </dd>
290 <dt><big>void <u>write</u>(Stream <i>file</i>);
291 </big></dt>
292 <dd>Writes the config file to <i>file</i>. Note that ConfigParser does not preserve
293     the ordering of options or sections, although it will always write the
294     global section first.
295    
296 <br><br>
297
298 </dd>
299 <dt><big>void <u>write</u>(char[] <i>filename</i>);
300 </big></dt>
301 <dd>Writes the config file to the file specified by <i>filename</i>. If the file
302     already exists, it is erased and written over. If it does not exist, it is
303     created.
304    
305 <br><br>
306
307 </dd>
308 </dl>
309 </dd>
310 </dl>
311
312     <hr><small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>. </small>
313     </body></html>
Note: See TracBrowser for help on using the browser.