1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>CommandLine 2.0 Library Manual</title></head>
<body bgcolor=white>
<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<tr><td> <font size=+4 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>CommandLine 2.0 Library Manual</b></font></td>
</tr></table>
<ol>
<li><a href="#introduction">Introduction</a>
<li><a href="#quickstart">Quick Start Guide</a>
<ol>
<li><a href="#bool">Boolean Arguments</a>
<li><a href="#alias">Argument Aliases</a>
<li><a href="#onealternative">Selecting an alternative from a set of possibilities</a>
<li><a href="#namedalternatives">Named alternatives</a>
<li><a href="#list">Parsing a list of options</a>
</ol>
<li><a href="#referenceguide">Reference Guide</a>
<ol>
<li>Option Modifiers:
<ul>
<li>Controlling whether or not the option is shown by <tt>--help</tt>
<li>Controlling the number of occurances required and allowed
<li>Controlling whether or not a value must be specified
<li>Controlling other formatting options
</ul>
<li>Positional Arguments
<li>Internal vs External Storage
<li>The option classes
<ul>
<li>The <tt>opt<></tt> class
<li>The <tt>list<></tt> class
<li>The <tt>alias</tt> class
</ul>
</ol>
<li><a href="#extensionguide">Extension Guide</a>
<ol>
<li>Writing a custom parser
<li>Exploiting external storage
<li>Dynamically adding command line options
</ol>
</ol><p>
<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
<a name="introduction">Introduction
</b></font></td></tr></table><ul>
<!-- *********************************************************************** -->
This document describes the CommandLine argument processing library. It will
show you how to use it, and what it can do.<p>
Although there are a <b>lot</b> of command line argument parsing libraries out
there in many different languages, none of them fit well with what I needed. By
looking at the features and problems of other libraries, I designed the
CommandLine library to have the following features:<p>
<ol>
<li>Speed: The CommandLine library is very quick and uses little resources. The
parsing time of the library is directly proportional to the number of arguments
parsed, not the the number of options recognized. Additionally, command line
argument values are captured transparently into user defined variables, which
can be accessed like any other variable (and with the same performance).<p>
<li>Type Safe: As a user of CommandLine, you don't have to worry about
remembering the type of arguments that you want (is it an int? a string? a
bool? an enum?) and keep casting it around. Not only does this help prevent
error prone constructs, it also leads to dramatically cleaner source code.<p>
<li>No subclasses required: To use CommandLine, you instantiate variables that
correspond to the arguments that you would like to capture, you don't subclass a
parser. This leads to much less boilerplate code.<p>
<li>Globally accessible: Libraries can specify command line arguments that are
automatically enabled in any tool that links to the library. This is possible
because the application doesn't have to keep a "list" of arguments to pass to
the parser.<p>
<li>More Clean: CommandLine supports enum types directly, meaning that there is
less error and more security built into the library. You don't have to worry
about whether your integral command line argument accidentally got assigned a
value that is not valid for your enum type.<p>
<li>Powerful: The CommandLine library supports many different types of
arguments, from simple boolean flags to scalars arguments (strings, integers,
enums, doubles), to lists of arguments. This is possible because CommandLine
is...<p>
<li>Extensible: It is very simple to add a new argument type to CommandLine.
Simply specify the parser that you want to use with the command line option when
you declare it. Custom parsers are no problem.<p>
<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
that you, the user, have to do. For example, it automatically provides a --help
option that shows the available command line options for your tool.<p>
</ol>
This document will hopefully let you jump in and start using CommandLine in your
utility quickly and painlessly. Additionally it should be a simple reference
manual to figure out how stuff works. If it is failing in some area, nag the
author, <a href="mailto:sabre@nondot.org">Chris Lattner</a>.<p>
<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
<a name="quickstart">Quick Start Guide
</b></font></td></tr></table><ul>
<!-- *********************************************************************** -->
This section of the manual runs through a simple CommandLine'ification of a
basic compiler tool. This is intended to show you how to jump into using the
CommandLine library in your own program, and show you some of the cool things it
can do.<p>
To start out, you need to include the CommandLine header file into your
program:<p>
<pre>
#include "Support/CommandLine.h"
</pre><p>
Additionally, you need to add this as the first line of your main program:<p>
<pre>
int main(int argc, char **argv) {
cl::ParseCommandLineOptions(argc, argv);
...
}
</pre><p>
... which actually parses the arguments and fills in the variable
declarations.<p>
Now that you are ready to support command line arguments, we need to tell the
system which ones we want, and what type of argument they are. The CommandLine
library uses a declarative syntax to model cammand line arguments with the
variable declarations that capture the parsed values. This means that for every
command line option that you would like to support, there should be a variable
declaration to capture the result. For example, in a compiler, we would like to
support the unix standard '<tt>-o <filename></tt>' option to specify where
to put the output. With the CommandLine library, this is represented like
this:<p>
<pre>
cl::opt<string> OutputFilename("<i>o</i>", cl::desc("<i>Specify output filename</i>"), cl::value_desc("<i>filename</i>"));
</pre><p>
This declares a variable "<tt>OutputFilename</tt>" that is used to capture the
result of the "<tt>o</tt>" argument (first parameter). We specify that this is
a simple scalar option by using the "<tt>opt<></tt>" template (as opposed
to the <a href="#list">"<tt>list<></tt> template</a>), and tell the
CommandLine library that the data type that we are parsing is a string.<p>
The second and third parameters (which are optional) are used to specify what to
output for the "<tt>--help</tt>" option. In this case, we get a line that looks
like this:<p>
<pre>
USAGE: compiler [options]
OPTIONS:
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
</pre>
Because we specified that the command line option should parse using the
<tt>string</tt> data type, the variable declared is automatically usable as a
real string in all contexts that a normal C++ string object may be used. For
example:<p>
<pre>
...
ofstream Output(OutputFilename.c_str());
if (Out.good()) ...
...
</pre><p>
There are many different options that you can use to customize the command line
option handling library, but the above example shows the general interface to
these options. The options can be specified in any order, and are specified
with helper functions like <tt>cl::desc(...)</tt>, so there are no positional
dependencies to have to remember. We will discuss the options you can use later
in this document. Also note that if your compiler supports Koenig lookup (gcc
2.95.x doesn't), that you don't have to specify as many <tt>cl::</tt> namespace
qualifiers to use the library.<p>
Continuing the example, we would like to have our compiler take an input
filename as well as an output filename, but we do not want the input filename to
be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
style of argument, the CommandLine library allows for positional arguments to be
specified for the program. These positional arguments are filled with command
line parameters that are not in option form. We use this feature like this:<p>
<pre>
cl::opt<string> InputFilename(cl::Positional, cl::desc("<i><input file></i>"), cl::init("<i>-</i>"));
</pre>
This declaration indicates that the first positional argument should be treated
as the input filename. Here we use the <tt>cl::init</tt> option to specify an
initial value for the command line option, which is used if the option is not
specified (if you do not specify a <tt>cl::init</tt> modifier for an option,
then the default constructor for the data type is used to initialize the value).
Command line options default to being optional, so if we would like to require
that the user always specify an input filename, we would add the
<tt>cl::Required</tt> flag, and we could eliminate the <tt>cl::init</tt>
modifier, like this:<p>
<pre>
cl::opt<string> InputFilename(cl::Positional, cl::desc("<i><input file></i>"), <b>cl::Required</b>);
</pre>
Again, the CommandLine library does not require the options to be specified in
any particular order, so the above declaration is equivalent to:<p>
<pre>
cl::opt<string> InputFilename(cl::Positional, cl::Required, cl::desc("<i><input file></i>"));
</pre>
By simply adding the <tt>cl::Required</tt> flag, the CommandLine library will
automatically issue an error if the argument is not specified, which shifts all
of the command line option verification code out of your application into the
library. This is just one example of how using flags can alter the default
behaviour of the library, on a per-option basis. By adding one of the
declarations above, the <tt>--help</tt> option synopsis is now extended to:<p>
<pre>
USAGE: compiler [options] <input file>
OPTIONS:
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
</pre>
... indicating that an input filename is expected.<p>
<!-- ======================================================================= -->
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
<a name="bool">Boolean Arguments
</b></font></td></tr></table><ul>
In addition to input and output filenames, we would like the compiler example to
support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
compatibility with some of our users. We can support these by declaring options
of boolean type like this:<p>
<pre>
cl::opt<bool> Force ("<i>f</i>", cl::desc("<i>Overwrite output files</i>"));
cl::opt<bool> Quiet ("<i>quiet</i>", cl::desc("<i>Don't print informational messages</i>"));
cl::opt<bool> Quiet2("<i>q</i>", cl::desc("<i>Don't
|
