root/misc/tango/optparse.html

Revision 83, 30.9 kB (checked in by KirkMcDonald, 2 years ago)

Added Tango port of optparse.

Line 
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4     <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
5     <title>Kirk McDonald's optparse</title>
6 </head>
7
8 <body>
9 <h1>optparse</h1>
10
11 <h2>Table of Contents</h2>
12
13 <ul>
14 <li><a href="#intro">Introduction</a></li>
15 <li><a href="#actions">Actions</a>
16     <ul>
17     <li><a href="#ActionStore">Store</a></li>
18     <li><a href="#ActionAppend">Append</a></li>
19     <li><a href="#ActionStoreConst">StoreConst</a></li>
20     <li><a href="#ActionAppendConst">AppendConst</a></li>
21     <li><a href="#ActionSetTrueFalse">SetTrue and SetFalse</a></li>
22     <li><a href="#ActionCount">Count</a></li>
23     <li><a href="#ActionCallback">Callback</a></li>
24     <li><a href="#ActionCallbackFancy">CallbackFancy</a></li>
25     <li><a href="#ActionHelp">Help</a></li>
26     </ul>
27 </li>
28 <li><a href="#api">API Reference</a>
29     <ul>
30     <li><a href="#misc">Miscellaneous</a></li>
31     <li><a href="#OptionParser"><tt>class OptionParser</tt></a></li>
32     <li><a href="#Option"><tt>class Option</tt></a></li>
33     <li><a href="#Options"><tt>class Options</tt></a></li>
34     </ul>
35 </li>
36 </ul>
37
38 <hr />
39
40 <h2><a name="intro">Introduction</a></h2>
41
42 <p>Parsing command-line options with <tt>optparse</tt> begins with defining the options the program can accept. This starts with creating an instance of the <tt>OptionParser</tt> class, whose constructor is defined like this:</p>
43
44 <blockquote><tt>OptionParser(char[] desc="")</tt></blockquote>
45
46 <p>The <i>desc</i> parameter should be a short description of your program. It is used by the built-in help features, described later. <tt>OptionParser</tt> has a number of methods, the most important of which is <tt>add_option</tt>. The <tt>add_option</tt> method has a large number of overloads, representing the large number of kinds of options that <tt>optparse</tt> supports. Before going over these overloads, it is necessary to go over some of <tt>optparse</tt>'s concepts.</p>
47
48 <p>First, this documentation makes the distinction between an <i>option</i> and an <i>argument</i>. An <i>option</i> is a literal string supplied by client code, such as "<tt>-f</tt>" or "<tt>--file</tt>". An <i>argument</i> is supplied by the end-user on the command-line. Some options accept arguments. If the user supplies "<tt>myapp --file=somefile.txt</tt>" to your program, then "<tt>--file</tt>" is an option, and "<tt>somefile.txt</tt>" is an argument to it. Arguments not associated with any particular option are called <i>leftover arguments</i>.</p>
49
50 <p>Options of the form "<tt>-f</tt>" are called <i>short options</i>. They start with a dash and are followed by any single non-dash character. Options of the form "<tt>--file</tt>" are called <i>long options</i>. They start with two dashes and may be of any length, and contain any characters, so long as they don't start with a third dash.</p>
51
52 <p>Every option has an <i>action</i> associated with it. The actions supported by <tt>optparse</tt> are:</p>
53
54 <ul>
55 <li>Store</li>
56 <li>Append</li>
57 <li>StoreConst</li>
58 <li>AppendConst</li>
59 <li>SetTrue</li>
60 <li>SetFalse</li>
61 <li>Count</li>
62 <li>Callback</li>
63 <li>CallbackFancy</li>
64 <li>Help</li>
65 </ul>
66
67 <p>The meaning of these actions will be discussed later. (Users of Python's optparse will probably find them familiar.) Certain actions accept arguments, and others do not. If an option's action accepts an argument, then that option also has a <i>type</i>. Types are represented by the <tt>ArgType</tt> enumerated type. Currently, the only types supported by <tt>optparse</tt> are <tt>ArgType.String</tt> and <tt>ArgType.Integer</tt>, which represent the D types <tt>char[]</tt> and <tt>int</tt>, respectively.</p>
68
69 <p>Options also have a <i>name</i>, which is used in a number of contexts. The name defaults to the first long option specified, without the dashes. If no long options are specified, it uses the first short option. An option's name is mainly used when retrieving its results, after parsing the arguments. Occasionally, it is useful to give multiple options the same name. Examples of this are given later.</p>
70
71 <p>For completeness' sake, here are all of the overloads of <tt>add_option</tt>:</p>
72
73 <ul>
74 <li><tt>Option add_option(char[][] options ...)</tt></li>
75 <li><tt>Option add_option(char[][] options, char[] name)</tt></li>
76 <li><tt>Option add_option(char[][] options, Action action)</tt></li>
77 <li><tt>Option add_option(char[][] options, ArgType type)</tt></li>
78 <li><tt>Option add_option(char[][] options, Action action, ArgType type)</tt></li>
79 <li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li>
80 <li><tt>Option add_option(char[][] options, char[] name, Action action, ArgType type)</tt></li>
81 <li><tt>Option add_option(char[][] options, Action action, char[] const_value)</tt></li>
82 <li><tt>Option add_option(char[][] options, char[] name, char[] const_value)</tt></li>
83 <li><tt>Option add_option(char[][] options, char[] name, Action action, char[] const_value)</tt></li>
84 <li><tt>Option add_option(char[][] options, void delegate() dg)</tt></li>
85 <li><tt>Option add_option(char[][] options, void delegate(char[]) dg)</tt></li>
86 <li><tt>Option add_option(char[][] options, void delegate(int) dg)</tt></li>
87 <li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li>
88 <li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li>
89 <li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li>
90 <li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li>
91 <li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li>
92 <li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li>
93 </ul>
94
95 <p>As I describe each action, I will also list the relevant <tt>add_option</tt> overloads to that action. Not all of these apply to all of the actions.</p>
96
97 <p>A very simple use of optparse looks like this:</p>
98
99 <blockquote><pre>void main(char[][] args) {
100     auto parser = new OptionParser();
101     parser.add_option("-o", "--option");
102     auto options = parser.parse_args(args);
103 }</pre></blockquote>
104
105 <p>Once the command-line has been parsed, the results are stored in an instance of the <tt>Options</tt> class. How you retrieve the results depends on the action.</p>
106
107 <hr />
108
109 <h2><a name="actions">Actions</a></h2>
110 <p>Actions in <tt>optparse</tt> are represented by the <tt>Action</tt> enumerated type. Each of the following is a member of this enum.</p>
111
112 <h3><a name="ActionStore">Action.Store</a></h3>
113 <p>This is the default action. An option with the <tt>Store</tt> action accepts an argument, and stores it. If the option is specified multiple times, then the last one is the one captured.</p>
114
115 <h4>Methods</h4>
116 <ul>
117 <li><tt>Option add_option(char[][] options ...)</tt></li>
118 <li><tt>Option add_option(char[][] options, char[] name)</tt></li>
119 <li><tt>Option add_option(char[][] options, Action action)</tt></li>
120 <li><tt>Option add_option(char[][] options, ArgType type)</tt></li>
121 <li><tt>Option add_option(char[][] options, Action action, ArgType type)</tt></li>
122 <li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li>
123 <li><tt>Option add_option(char[][] options, char[] name, Action action, ArgType type)</tt></li>
124 </ul>
125
126 <h4>Results</h4>
127 <p>Retrieving the results of <tt>Store</tt> differs based on the option's type. <tt>Store</tt>'s default type is <tt>String</tt>.</p>
128
129 <p>To retrieve a string argument, simply index the <tt>Options</tt> object with the option's name:</p>
130
131 <blockquote><tt>char[] filename = options["file"];</tt></blockquote>
132
133 <p>To retrieve an integer argument, pass the option's name to the <tt>value</tt> method of <tt>Options</tt>:</p>
134
135 <blockquote><tt>int num = options.value("number");</tt></blockquote>
136
137 <p>If the option was not provided on the command line, <tt>opIndex</tt> will return the empty string, and <tt>value</tt> will return 0.</p>
138
139 <h4>Example</h4>
140 <blockquote><pre>void main(char[][] args) {
141     auto parser = new OptionParser();
142     parser.add_option("-f", "--file");
143     parser.add_option(["-n", "--number"], ArgType.Integer);
144     auto options = parser.parse_args(args);
145     writefln("file: %s", options["file"]);
146     writefln("number: %s", options.value("number"));
147 }</pre></blockquote>
148
149 <p>This produces the following on the command-line:</p>
150
151 <blockquote><pre>$ myapp --file foo.txt -n28
152 file: foo.txt
153 number: 28
154 $ myapp
155 file:
156 number: 0</pre></blockquote>
157
158 <h3><a name="ActionAppend">Action.Append</a></h3>
159 <p><tt>Append</tt> behaves much like <tt>Store</tt>. Instead of simply storing its arguments, however, it appends them to a list.</p>
160
161 <h4>Methods</h4>
162 <ul>
163 <li><tt>Option add_option(char[][] options, Action action)</tt></li>
164 <li><tt>Option add_option(char[][] options, Action action, ArgType type)</tt></li>
165 <li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li>
166 <li><tt>Option add_option(char[][] options, char[] name, Action action, ArgType type)</tt></li>
167 </ul>
168
169 <h4>Results</h4>
170 <p>Also as with <tt>Store</tt>, <tt>Append</tt>'s default type is <tt>String</tt>. If the type of the option is string, pass its name to the <tt>list</tt> method of <tt>Options</tt>:</p>
171
172 <blockquote><tt>char[][] imports = options.list("import");</tt></blockquote>
173
174 <p>If the type is <tt>Integer</tt>, use the <tt>value_list</tt> method:</p>
175
176 <blockquote><tt>int[] values = options.value_list("value");</tt></blockquote>
177
178 <p>If the option is not provided on the command line, these will both return an empty array.</p>
179
180 <h4>Example</h4>
181 <blockquote><pre>void main(char[][] args) {
182     auto parser = new OptionParser();
183     parser.add_option(["-I", "--import"], Action.Append);
184     parser.add_option(["-V", "--value"], Action.Append, ArgType.Integer);
185     auto options = parser.parse_args(args);
186     writefln("imports: %s", options.list("import"));
187     writefln("values: %s", options.value_list("value"));
188 }</pre></blockquote>
189
190 <p>This produces the following on the command-line:</p>
191
192 <blockquote><pre>$ myapp -Isome/path -Ianother/path -V20 --value=30
193 imports: [some/path,another/path]
194 values: [20,30]
195 $ myapp
196 imports: []
197 values: []</pre></blockquote>
198
199 <h3><a name="ActionStoreConst">Action.StoreConst</a></h3>
200 <p>When an option with the <tt>StoreConst</tt> action is found, it stores some constant value provided by the client code. This is one way to implement a simple flag.</p>
201
202 <p>It is worth pointing out that you can have two different <tt>StoreConst</tt> options with the same name, but different constant values. This is one way of implementing a pair of "<tt>--enable</tt>" and "<tt>--disable</tt>" flags. (Even better would be using the <tt>SetTrue</tt> and <tt>SetFalse</tt> actions.)</p>
203
204 <h4>Methods</h4>
205 <ul>
206 <li><tt>Option add_option(char[][] options, Action action, char[] const_value)</tt></li>
207 <li><tt>Option add_option(char[][] options, char[] name, char[] const_value)</tt></li>
208 <li><tt>Option add_option(char[][] options, char[] name, Action action, char[] const_value)</tt></li>
209 </ul>
210
211 <h4>Results</h4>
212 <p>Accessing the results of a <tt>StoreConst</tt> option is exactly like accessing those of a <tt>Store</tt> action with a <tt>String</tt> type. (Using opIndex.) If the option was specified, the constant value will be returned. If it wasn't, it will return an empty string.</p>
213
214 <p>At this time, only strings are supported as constant values.</p>
215
216 <h4>Example</h4>
217 <blockquote><pre>void main(char[][] args) {
218     auto parser = new OptionParser();
219     parser.add_option(["--enable"], "flag", Action.StoreConst, "on");
220     parser.add_option(["--disable"], "flag", Action.StoreConst, "off");
221     auto options = parser.parse_args(args);
222     writefln("flag: %s", options["flag"]);
223 }</pre></blockquote>
224
225 <p>This produces the following on the command-line:</p>
226
227 <blockquote><pre>$ myapp --enable
228 flag: on
229 $ myapp --disable
230 flag: off
231 $ myapp
232 flag: </pre></blockquote>
233
234 <h3><a name="ActionAppendConst">Action.AppendConst</a></h3>
235 <p>Similar to <tt>StoreConst</tt>, this will append the supplied constant to a list whenever the option is found on the command-line.</p>
236
237 <h4>Methods</h4>
238 <ul>
239 <li><tt>Option add_option(char[][] options, Action action, char[] const_value)</tt></li>
240 <li><tt>Option add_option(char[][] options, char[] name, Action action, char[] const_value)</tt></li>
241 </ul>
242
243 <h4>Results</h4>
244 <p>Accessing the results of <tt>AppendConst</tt> works just like accessing those of an <tt>Append</tt> action with the <tt>String</tt> type, using the <tt>list</tt> method.</p>
245
246 <h4>Example</h4>
247 <blockquote><pre>void main(char[][] args) {
248     auto parser = new OptionParser();
249     parser.add_option(["--blue"], "color", Action.AppendConst, "blue");
250     parser.add_option(["--green"], "color", Action.AppendConst, "green");
251     auto options = parser.parse_args(args);
252     writefln("colors: %s", options.list("color"));
253 }</pre></blockquote>
254
255 <p>This produces the following on the command-line:</p>
256
257 <blockquote><pre>$ myapp --blue --green --blue
258 colors: [blue,green,blue]
259 $ myapp
260 colors: []</pre></blockquote>
261
262 <h3><a name="ActionSetTrueFalse">Action.SetTrue and Action.SetFalse</a></h3>
263 <p>Flag options may be implemented with these actions. The <tt>SetTrue</tt> action will set a flag to true, and <tt>SetFalse</tt> will set it to false.</p>
264
265 <h4>Methods</h4>
266 <ul>
267 <li><tt>Option add_option(char[][] options, Action action)</tt></li>
268 <li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li>
269 </ul>
270
271 <h4>Results</h4>
272 <p>The flag is retrieved using the <tt>flag</tt> method of the <tt>Options</tt> class.</p>
273
274 <blockquote><tt>bool flag = options.flag("flag");</tt></blockquote>
275
276 <p>If the flag was not specified, it defaults to false.</p>
277
278 <h4>Example</h4>
279 <blockquote><pre>void main(char[][] args) {
280     auto parser = new OptionParser();
281     parser.add_option(["--enable"], "flag", Action.SetTrue);
282     parser.add_option(["--disable"], "flag", Action.SetFalse);
283     auto options = parser.parse_args(args);
284     writefln("flag: %s", options.flag("flag"));
285 }</pre></blockquote>
286
287 <p>This produces the following on the command-line:</p>
288
289 <blockquote><pre>$ myapp --enable
290 flag: true
291 $ myapp --enable --disable
292 flag: false
293 $ myapp
294 flag: false</pre></blockquote>
295
296 <h3><a name="ActionCount">Action.Count</a></h3>
297 <p>The <tt>Count</tt> action simply counts the number of times the option occurs on the command-line.</p>
298
299 <h4>Methods</h4>
300 <ul>
301 <li><tt>Option add_option(char[][] options, Action action)</tt></li>
302 <li><tt>Option add_option(char[][] options, char[] name, Action action)</tt></li>
303 </ul>
304
305 <h4>Results</h4>
306 <p>The count may be retrieved from the <tt>count</tt> method of <tt>Options</tt>.</p>
307
308 <blockquote><tt>int c = options.count("verbosity");</tt></blockquote>
309
310 <h4>Example</h4>
311 <blockquote><pre>void main(char[][] args) {
312     auto parser = new OptionParser();
313     parser.add_option(["-v", "--verbose"], "verbosity", Action.Count);
314     auto options = parser.parse_args(args);
315     writefln("verbosity: %s", options.count("verbosity"));
316 }</pre></blockquote>
317
318 <p>This produces the following on the command-line:</p>
319
320 <blockquote><pre>$ myapp -vvv
321 verbosity: 3
322 $ myapp -v --verbose
323 verbosity: 2
324 $ myapp
325 verbosity: 0</pre></blockquote>
326
327 <h3><a name="ActionCallback">Action.Callback</a></h3>
328 <p>Sometimes, the above actions aren't enough. To extend <tt>optparse</tt>, users may provide a callback as an option's action. A callback option may accept an argument. Whether it accepts an argument is determined by the type of the callback.</p>
329
330 <p><strong>Important note:</strong> A callback is called as soon as it is encountered in the argument list. This means that <tt>optparse</tt> may still exit with an error if it finds malformed or invalid options on the command line, after the callback is run. For this reason, users should not place actual program logic inside of callbacks, and should only use them to store option data for later use.</p>
331
332 <h4>Methods</h4>
333 <ul>
334 <li><tt>Option add_option(char[][] options, void delegate() dg)</tt></li>
335 <li><tt>Option add_option(char[][] options, void delegate(char[]) dg)</tt></li>
336 <li><tt>Option add_option(char[][] options, void delegate(int) dg)</tt></li>
337 </ul>
338 <h4>Results</h4>
339 <p>The results of a callback option are not stored anywhere by <tt>optparse</tt>. It is assumed the user will keep any information about the callback themselves.</p>
340
341 <h4>Example</h4>
342 <blockquote><pre>void main(char[][] args) {
343     auto parser = new OptionParser();
344     parser.add_option(["--callback"], {
345         writefln("Callback encountered!");
346     });
347     auto options = parser.parse_args(args);
348     writefln("Done.");
349 }</pre></blockquote>
350
351 <p>This produces the following on the command-line:</p>
352
353 <blockquote><pre>$ myapp --callback
354 Callback encountered!
355 Done.
356 $ myapp
357 Done.</pre></blockquote>
358
359 <h3><a name="ActionCallbackFancy">Action.CallbackFancy</a></h3>
360 <p>If client code wants to handle the parsing process at a lower level, <tt>optparse</tt> provides these advanced callbacks.</p>
361
362 <p>The first four arguments to these callbacks have the following types and meanings:</p>
363
364 <dl>
365 <dt><tt>Options</tt></dt> <dd>The current results of parsing the command-line, up to when the callback was encountered.</dd>
366
367 <dt><tt>inout char[][]</tt></dt> <dd>The args array. This is mostly identical to the array originally passed to <tt>parse_args</tt>, with the following differences:
368     <ol>
369     <li>The first element, with the executable name, has been removed.</li>
370     <li>Options of the form "<tt>--option=argument</tt>" preceeding (or including) this option have been parsed apart into two elements, as in <tt>[--option,argument]</tt>. Elements of the array after the current option have not been touched, yet.</li>
371     </ol>
372 It is useful to note that this argument is declared <tt>inout</tt>, meaning callbacks are free to modify the array.</dd>
373
374 <dt><tt>inout int</tt></dt> <dd>The index in the args array of this option; or, if this option accepts an argument, of the option's argument. Note that this is declared <tt>inout</tt>. When the callback returns, parsing will resume with the element of args following this <tt>int</tt>. If this argument is advanced beyond the end of the args array, parsing will quietly terminate.</dd>
375
376 <dt><tt>char[]</tt></dt> <dd>The name of this option.</dd>
377 </dl>
378
379 <p>The fifth argument to the callback, if it exists, controls the type of the argument to the option.</p>
380
381 <h4>Methods</h4>
382 <ul>
383 <li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li>
384 <li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li>
385 <li><tt>Option add_option(char[][] options, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li>
386 <li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[]) dg)</tt></li>
387 <li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], char[]) dg)</tt></li>
388 <li><tt>Option add_option(char[][] options, char[] name, void delegate(Options, inout char[][], inout int, char[], int) dg)</tt></li>
389 </ul>
390 <h4>Results</h4>
391 <p>As with regular callbacks, <tt>optparse</tt> does not store the results of advanced callbacks.</p>
392
393 <h4>Example</h4>
394 <blockquote><pre>void main(char[][] args) {
395     auto parser = new OptionParser();
396     parser.add_option(
397         ["--adv-callback"],
398         (Options o, inout char[][] a, inout int i, char[] name) {
399             // Skip the next argument, whatever it is.
400             ++i;
401         }
402     );
403     parser.add_option(["-c"], Action.Count);
404     auto options = parser.parse_args(args);
405     writefln("count: %s", options.count("c"));
406 }</pre></blockquote>
407
408 <p>This produces the following on the command-line:</p>
409
410 <blockquote><pre>$ myapp -c --adv-callback -cc
411 count: 1</pre></blockquote>
412
413 <h3><a name="ActionHelp">Action.Help</a></h3>
414 <p>The <tt>Help</tt> action prints out a listing of the options in the parser.</p>
415
416 <p>The listing begins with a header like the following:</p>
417
418 <blockquote><pre>Usage: myapp [options] args...
419 A short description of myapp.
420
421 Options:</pre></blockquote>
422
423 <p>This header is customizable in two ways:</p>
424 <ul>
425 <li>The "<tt>[options] args...</tt>" portion is contained in the <tt>argdesc</tt> member variable of the <tt>OptionParser</tt> class. Users may change this member to whatever they like in their instance.</li>
426 <li>The short description should be provided to the <tt>OptionParser</tt> constructor.</li>
427 </ul>
428
429 <p>Additionally, the name of the application is derived directly from the first element of the args array.</p>
430
431 <p>Options are printed in the following form. Given these options:</p>
432
433 <blockquote><pre>parser.add_option("-f", "--file").help("The file to operate on.")
434 parser.add_option(["--enable"], Action.SetTrue).help("Enables the option.")</pre></blockquote>
435
436 <p><tt>Help</tt> produces the following:</p>
437
438 <blockquote><pre>  -f, --file=FILE The file to operate on.
439   --enable        Enables the option.</pre></blockquote>
440
441 <p>The <tt>help</tt> method of the <tt>Option</tt> class provides the description used in the listing. Notice also the "<tt>=FILE</tt>" in the first option above. This indicates that the option accepts an argument. If you wanted to have this say "<tt>=FILENAME</tt>" instead, you would instead define the <tt>--file</tt> option as:</p>
442
443 <blockquote<tt>parser.add_option("-f", "--file").help("The file to operate on.").argName("filename");</tt></blockquote>
444
445 <p>The <tt>argName</tt> method of <tt>Option</tt> class defines this string, which otherwise defaults to the option's name. Note that it always converts the argument's name to all-caps.</p>
446
447 <h4>Methods</h4>
448 <ul>
449 <li><tt>Option add_option(char[][] options, Action action)</tt></li>
450 </ul>
451
452 <h4>Results</h4>
453 <p><tt>Help</tt> terminates the program when found.</p>
454
455 <h4>Example</h4>
456 <p>Bringing it all together, we get this:</p>
457
458 <blockquote><pre>void main(char[][] args) {
459     auto parser = new OptionParser("Testing the Help action.");
460     parser.argdesc = "[options]";
461     parser.add_option("-f", "--file").help("Defines the file to use.").argName("filename");
462     parser.add_option(["-n", "--number"], ArgType.Integer).help("Specifies the number.");
463     parser.add_option(["--blue"], "color", Action.AppendConst, "blue").help("Adds the color blue.");
464     parser.add_option(["--green"], "color", Action.AppendConst, "green").help("Adds the color green.");
465     parser.add_option(["--help"], Action.Help).help("Displays this help message.");
466     auto options = parser.parse_args(args);
467     writefln("Done.");
468 }</pre></blockquote>
469
470 <p>This produces the following on the command-line:</p>
471
472 <blockquote><pre>$ myapp --help
473 Usage: myapp [options]
474 Testing the Help action.
475
476 Options:
477   -f, --file=FILENAME Defines the file to use.
478   -n, --number=NUMBER Specifies the number.
479   --blue              Adds the color blue.
480   --green             Adds the color green.
481   --help              Displays this help message.
482 $ myapp
483 Done.</pre></blockquote>
484
485 <hr />
486
487 <h2><a name="api">API Reference</a></h2>
488
489 <h3><a name="misc">Miscellaneous</a></h3>
490 <p><tt>class OptionError : Exception;</tt></p>
491
492 <p>This exception is thrown by <tt>OptionParser</tt> when client code attempts to set up a malformed option.</p>
493
494 <p><tt>enum Action { Store, StoreConst, Append, AppendConst, Count, SetTrue, SetFalse, Callback, CallbackFancy, Help }</tt></p>
495 <p><tt>enum ArgType { None, String, Integer }</tt></p>
496
497 <p>The following delegate types define all the possible callback types used by <tt>optparse</tt>:</p>
498
499 <p><tt>alias void delegate(Options, inout char[][], inout int, char[], char[]) OptionCallbackFancyArg;<br />
500 alias void delegate(Options, inout char[][], inout int, char[], int)    OptionCallbackFancyInt;<br />
501 alias void delegate(Options, inout char[][], inout int, char[])         OptionCallbackFancy;</tt></p>
502
503 <p><tt>alias void delegate(char[]) OptionCallbackArg;<br />
504 alias void delegate(int)    OptionCallbackInt;<br />
505 alias void delegate()       OptionCallback;</tt></p>
506
507 <h3><a name="OptionParser">OptionParser</a></h3>
508 <p>Refer to the rest of this document for the meanings of <tt>parse_args</tt> and <tt>add_option</tt>.</p>
509
510 <pre>class OptionParser {
511     Option[] options;
512     char[] argdesc;
513     this(char[] desc="");
514     void set_error_callback(void delegate(char[]) dg);
515     void error(char[] err);
516     void help_text();
517     Options parse_args(char[][] args);
518     void leftover_callback(OptionCallbackArg dg);
519     Option add_option(Option option);
520     Option add_option(char[][] options ...);
521     Option add_option(char[][] options, char[] name);
522     Option add_option(char[][] options, Action action);
523     Option add_option(char[][] options, ArgType type);
524     Option add_option(char[][] options, Action action, ArgType type);
525     Option add_option(char[][] options, char[] name, Action action);
526     Option add_option(char[][] options, char[] name, Action action, ArgType type);
527     Option add_option(char[][] options, Action action, char[] const_value);
528     Option add_option(char[][] options, char[] name, char[] const_value);
529     Option add_option(char[][] options, char[] name, Action action, char[] const_value);
530     Option add_option(char[][] options, OptionCallback dg);
531     Option add_option(char[][] options, OptionCallbackArg dg);
532     Option add_option(char[][] options, OptionCallbackInt dg);
533     Option add_option(char[][] options, OptionCallbackFancy dg);
534     Option add_option(char[][] options, OptionCallbackFancyArg dg);
535     Option add_option(char[][] options, OptionCallbackFancyInt dg);
536     Option add_option(char[][] options, char[] name, OptionCallbackFancy dg);
537     Option add_option(char[][] options, char[] name, OptionCallbackFancyArg dg);
538     Option add_option(char[][] options, char[] name, OptionCallbackFancyInt dg);
539 }</pre>
540
541 <dl>
542 <dt><tt>void leftover_callback(OptionCallbackArg dg);</tt></dt> <dd>Normally, leftover arguments are simply added to an array in the <tt>Options</tt> object. By calling this, client code may get these arguments sent to this callback, instead.</dd>
543
544 <dt><tt>void error(char[] err);</tt></dt> <dd>When <tt>parse_args</tt> is unable to parse the arguments passed to it, this function is called. By default, it calls <tt>help_text</tt>, prints out the error message, and then terminates the program with a failure state.</dd>
545
546 <dt><tt>void set_error_callback(void delegate(char[]) dg);</tt> <dd>When client code supplies a delegate to this function, the behavior of <tt>error</tt> changes. Instead of calling <tt>help_text</tt> and printing out its error message, it calls the passed delegate with it, and then terminates the program with a failure state.</dd>
547
548 <dt><tt>void help_text();</tt></dt> <dd>This function is used by the <tt>Help</tt> action. It prints out a nice listing of all the options known by the <tt>OptionParser</tt>.</dd>
549
550 <dt><tt>char[] argdesc;</tt></dt> <dd>When <tt>help_text</tt> is called, it prints a message before the list of options in the following form:
551
552 <blockquote><tt>Usage: myapp [options] args...</tt></blockquote>
553
554 The "<tt>[options] args...</tt>" part of this message is contained in <tt>argdesc</tt>, and may be overidden by client code. (The "<tt>myapp</tt>" part of the message is automatically derived from the first element of the <tt>args</tt> array.)</dd>
555
556 <dt><tt>Option[] options;</tt></dt> <dd>This array holds all of the instances of <tt>Option</tt> known by the parser.</dd>
557 </dl>
558
559 <h3><a name="Option">Option</a></h3>
560 <p>Each option defined by the client code is represented by an instance of this class. Client code does not typically interact with or instantiate this class directly, although the <tt>help</tt> and <tt>argName</tt> methods are needed when using the <tt>Help</tt> action.</p>
561
562 <pre>class Option {
563     Option help(char[] helpstr);
564     Option argName(char[] argname);
565     bool hasArg();
566     char[] toString();
567 }</pre>
568
569 <dl>
570 <dt><tt>Option help(char[] helpstr);</tt></dt> <dd>The string passed to this method will be printed next to the option when the <tt>Help</tt> action is called. The easiest way to use this method is directly off of a call to <tt>add_option</tt>, as in:
571
572 <blockquote><tt>parser.add_option("--someopt").help("Does something.");</tt></blockquote></dd>
573
574 <dt><tt>Option argName(char[] argname);</tt></dt> <dd>When an option accepts an argument, the <tt>Help</tt> action will indicate this by putting something informative after the option. By default, it uses the all-caps form of the option's name. You can supply a different string to this method, which will be converted to all-caps.</dd>
575
576 <dt><tt>bool hasArg();</tt></dt> <dd>Returns whether this option accepts an argument.</dd>
577
578 <dt><tt>char[] toString();</tt></dt> <dd>Returns a string with all of the forms of the option, short and long, seperated by commas, and possibly ending with an indication of whether the option accepts an argument. (See also: <tt>argName</tt>.)</dd>
579 </dl>
580
581 <h3><a name="Options">Options</a></h3>
582 <p>When a command-line gets parsed by <tt>optparse</tt>, <tt>parse_args</tt> returns an instance of this class. All of the parsing results are stored here.</p>
583
584 <pre>class Options {
585     char[] opIndex(char[] name);
586     int value(char[] name);
587     char[][] list(char[] name);
588     int[] value_list(char[] name);
589     int count(char[] name);
590     bool flag(char[] name);
591     char[][] args;
592 }</pre>
593
594 <dl>
595 <dt><tt>char[] opIndex(char[] name);</tt></dt> <dd>The results of the <tt>Store</tt> and <tt>StoreConst</tt> actions may be retrieved from here. (<tt>Store</tt> only when the type is <tt>String</tt>.)</dd>
596
597 <dt><tt>int value(char[] name);</tt></dt> <dd>The results of the <tt>Store</tt> action may be retrieved here when the type is <tt>Integer</tt>.</dd>
598
599 <dt><tt>char[][] list(char[] name);</tt></dt> <dd>The results of the <tt>Append</tt> and <tt>AppendConst</tt> actions may be retrieved from here. (<tt>Append</tt> only when the type is <tt>String</tt>.)</dd>
600
601 <dt><tt>int[] value_list(char[] name);</tt></dt> <dd>The results of the <tt>Append</tt> action may be retrieved from here when its type is <tt>Integer</tt>.</dd>
602
603 <dt><tt>int count(char[] name);</tt></dt> <dd>The results of the <tt>Count</tt> action may be retrieved from here.</dd>
604
605 <dt><tt>bool flag(char[] name);</tt></dt> <dd>The results of the <tt>SetTrue</tt> and <tt>SetFalse</tt> actions may be retrieved from here.</dd>
606
607 <dt><tt>char[][] args;</tt></dt> <dd>By default, leftover args are simply added to this array when they are encountered. (See also the <tt>leftover_callback</tt> method of <tt>OptionParser</tt>, however.)</dd>
608 </dl>
609
610 </body>
611 </html>
Note: See TracBrowser for help on using the browser.