| blob | bf80ec07d458ad575b0420acc78f2094edd35e38 |
3 <html>
4 <head>
8 </head>
9 <body>
12 CommandLine 2.0 Library Manual
13 </div>
15 <ol>
19 <ol>
23 set of possibilities</a></li>
28 </ol></li>
31 <ol>
33 <ul>
36 getPosition</a></li>
38 modifier</a></li>
39 </ul></li>
46 <ul>
48 output</a></li>
50 required and allowed</a></li>
52 specified</a></li>
55 </ul></li>
58 <ul>
64 function</a></li>
70 </ul></li>
73 <ul>
75 parser</a></li>
77 specialization</a></li>
79 specialization</a></li>
81 specialization</a></li>
83 specialization</a></li>
86 </ul></li>
87 </ol></li>
89 <ol>
93 options</a></li>
94 </ol></li>
95 </ol>
99 </div>
101 <!-- *********************************************************************** -->
104 </div>
105 <!-- *********************************************************************** -->
109 <p>This document describes the CommandLine argument processing library. It will
110 show you how to use it, and what it can do. The CommandLine library uses a
111 declarative approach to specifying the command line options that your program
112 takes. By default, these options declarations implicitly hold the value parsed
117 out there in many different languages, none of them fit well with what I needed.
118 By looking at the features and problems of other libraries, I designed the
119 CommandLine library to have the following features:</p>
121 <ol>
122 <li>Speed: The CommandLine library is very quick and uses little resources. The
123 parsing time of the library is directly proportional to the number of arguments
124 parsed, not the the number of options recognized. Additionally, command line
125 argument values are captured transparently into user defined global variables,
126 which can be accessed like any other variable (and with the same
127 performance).</li>
129 <li>Type Safe: As a user of CommandLine, you don't have to worry about
130 remembering the type of arguments that you want (is it an int? a string? a
131 bool? an enum?) and keep casting it around. Not only does this help prevent
132 error prone constructs, it also leads to dramatically cleaner source code.</li>
134 <li>No subclasses required: To use CommandLine, you instantiate variables that
135 correspond to the arguments that you would like to capture, you don't subclass a
137 code.</li>
139 <li>Globally accessible: Libraries can specify command line arguments that are
140 automatically enabled in any tool that links to the library. This is possible
141 because the application doesn't have to keep a "list" of arguments to pass to
145 <li>Cleaner: CommandLine supports enum and other types directly, meaning that
146 there is less error and more security built into the library. You don't have to
147 worry about whether your integral command line argument accidentally got
148 assigned a value that is not valid for your enum type.</li>
150 <li>Powerful: The CommandLine library supports many different types of
157 <li>Extensible: It is very simple to add a new argument type to CommandLine.
158 Simply specify the parser that you want to use with the command line option when
161 <li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
162 that you, the user, have to do. For example, it automatically provides a
164 tool. Additionally, it does most of the basic correctness checking for
165 you.</li>
167 <li>Capable: The CommandLine library can handle lots of different forms of
168 options often found in real programs. For example, <a
175 </ol>
177 <p>This document will hopefully let you jump in and start using CommandLine in
178 your utility quickly and painlessly. Additionally it should be a simple
179 reference manual to figure out how stuff works. If it is failing in some area
180 (or you want an extension to the library), nag the author, <a
183 </div>
185 <!-- *********************************************************************** -->
188 </div>
189 <!-- *********************************************************************** -->
193 <p>This section of the manual runs through a simple CommandLine'ification of a
194 basic compiler tool. This is intended to show you how to jump into using the
195 CommandLine library in your own program, and show you some of the cool things it
196 can do.</p>
198 <p>To start out, you need to include the CommandLine header file into your
199 program:</p>
202 #include "llvm/Support/CommandLine.h"
203 </pre></div>
205 <p>Additionally, you need to add this as the first line of your main
206 program:</p>
209 int main(int argc, char **argv) {
211 ...
212 }
213 </pre></div>
215 <p>... which actually parses the arguments and fills in the variable
216 declarations.</p>
218 <p>Now that you are ready to support command line arguments, we need to tell the
219 system which ones we want, and what type of argument they are. The CommandLine
220 library uses a declarative syntax to model command line arguments with the
221 global variable declarations that capture the parsed values. This means that
222 for every command line option that you would like to support, there should be a
223 global variable declaration to capture the result. For example, in a compiler,
225 to specify where to put the output. With the CommandLine library, this is
226 represented like this:</p>
230 <a href="#cl::opt">cl::opt</a><string> OutputFilename("<i>o</i>", <a href="#cl::desc">cl::desc</a>("<i>Specify output filename</i>"), <a href="#cl::value_desc">cl::value_desc</a>("<i>filename</i>"));
231 </pre></div>
234 capture the result of the "<tt>o</tt>" argument (first parameter). We specify
235 that this is a simple scalar option by using the "<tt><a
238 that the data type that we are parsing is a string.</p>
240 <p>The second and third parameters (which are optional) are used to specify what
242 looks like this:</p>
245 USAGE: compiler [options]
247 OPTIONS:
248 -help - display available options (--help-hidden for more)
249 <b>-o <filename> - Specify output filename</b>
250 </pre></div>
252 <p>Because we specified that the command line option should parse using the
253 <tt>string</tt> data type, the variable declared is automatically usable as a
254 real string in all contexts that a normal C++ string object may be used. For
255 example:</p>
258 ...
259 ofstream Output(OutputFilename.c_str());
260 if (Out.good()) ...
261 ...
262 </pre></div>
264 <p>There are many different options that you can use to customize the command
265 line option handling library, but the above example shows the general interface
266 to these options. The options can be specified in any order, and are specified
268 there are no positional dependencies to remember. The available options are
271 <p>Continuing the example, we would like to have our compiler take an input
272 filename as well as an output filename, but we do not want the input filename to
273 be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
274 style of argument, the CommandLine library allows for <a
276 These positional arguments are filled with command line parameters that are not
277 in option form. We use this feature like this:</p>
280 <a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
281 </pre></div>
283 <p>This declaration indicates that the first positional argument should be
284 treated as the input filename. Here we use the <tt><a
286 command line option, which is used if the option is not specified (if you do not
288 the default constructor for the data type is used to initialize the value).
289 Command line options default to being optional, so if we would like to require
290 that the user always specify an input filename, we would add the <tt><a
295 <a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <b><a href="#cl::Required">cl::Required</a></b>);
296 </pre></div>
298 <p>Again, the CommandLine library does not require the options to be specified
299 in any particular order, so the above declaration is equivalent to:</p>
302 <a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::Required">cl::Required</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"));
303 </pre></div>
306 the CommandLine library will automatically issue an error if the argument is not
307 specified, which shifts all of the command line option verification code out of
308 your application into the library. This is just one example of how using flags
309 can alter the default behaviour of the library, on a per-option basis. By
310 adding one of the declarations above, the <tt>--help</tt> option synopsis is now
311 extended to:</p>
314 USAGE: compiler [options] <b><input file></b>
316 OPTIONS:
317 -help - display available options (--help-hidden for more)
318 -o <filename> - Specify output filename
319 </pre></div>
321 <p>... indicating that an input filename is expected.</p>
323 </div>
325 <!-- ======================================================================= -->
328 </div>
332 <p>In addition to input and output filenames, we would like the compiler example
335 compatibility with some of our users. We can support these by declaring options
336 of boolean type like this:</p>
339 <a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
340 <a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
341 <a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>);
342 </pre></div>
344 <p>This does what you would expect: it declares three boolean variables
352 for different data types. For example, in the string case, the argument passed
353 to the option is copied literally into the content of the string variable... we
354 obviously cannot do that in the boolean case, however, so we must use a smarter
355 parser. In the case of the boolean parser, it allows no options (in which case
356 it assigns the value of true to the variable), or it allows the values
358 following inputs:</p>
361 compiler -f # No value, 'Force' == true
362 compiler -f=true # Value specified, 'Force' == true
363 compiler -f=TRUE # Value specified, 'Force' == true
364 compiler -f=FALSE # Value specified, 'Force' == false
365 </pre></div>
368 the string values into boolean values, and rejects things like '<tt>compiler
371 like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
372 library calls to parse the string value into the specified data type.</p>
377 USAGE: compiler [options] <input file>
379 OPTIONS:
380 <b>-f - Overwrite output files</b>
381 -o - Override output filename
382 <b>-quiet - Don't print informational messages</b>
383 -help - display available options (--help-hidden for more)
384 </pre></div>
389 USAGE: compiler [options] <input file>
391 OPTIONS:
392 -f - Overwrite output files
393 -o - Override output filename
394 <b>-q - Don't print informational messages</b>
395 -quiet - Don't print informational messages
396 -help - display available options (--help-hidden for more)
397 </pre></div>
399 <p>This brief example has shown you how to use the '<tt><a
401 arguments. In addition to simple scalar arguments, the CommandLine library also
405 </div>
407 <!-- ======================================================================= -->
410 </div>
414 <p>So far, the example works well, except for the fact that we need to check the
415 quiet condition like this now:</p>
418 ...
419 if (!Quiet && !Quiet2) printInformationalMessage(...);
420 ...
421 </pre></div>
423 <p>... which is a real pain! Instead of defining two values for the same
424 condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
426 a value itself:</p>
429 <a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
430 <a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
431 <a href="#cl::alias">cl::alias</a> QuietA("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Alias for -quiet</i>"), <a href="#cl::aliasopt">cl::aliasopt</a>(Quiet));
432 </pre></div>
434 <p>The third line (which is the only one we modified from above) defines a
437 specified. Because aliases do not hold state, the only thing the program has to
440 (although, again, they are still visible in the <tt>--help-hidden
446 ...
447 if (!Quiet) printInformationalMessage(...);
448 ...
449 </pre></div>
452 can be used to specify an alternative name for any variable type, and has many
453 uses.</p>
455 </div>
457 <!-- ======================================================================= -->
460 possibilities</a>
461 </div>
465 <p>So far, we have seen how the CommandLine library handles builtin types like
469 <p>The answer is that it uses a table driven generic parser (unless you specify
471 Guide</a>). This parser maps literal strings to whatever type is required, and
472 requires you to tell it what this mapping should be.</p>
474 <p>Lets say that we would like to add four optimization levels to our
477 options like above, but there are several problems with this strategy:</p>
479 <ol>
480 <li>A user could specify more than one of the options at a time, for example,
481 "<tt>opt -O3 -O2</tt>". The CommandLine library would not be able to catch this
482 erroneous input for us.</li>
486 <li>This doesn't map to the numeric levels that we want... so we cannot easily
489 </ol>
491 <p>To cope with these problems, we can use an enum value, and have the
492 CommandLine library fill it in with the appropriate level directly, which is
493 used like this:</p>
496 enum OptLevel {
497 g, O1, O2, O3
498 };
500 <a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
502 clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
503 clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
504 clEnumVal(O2, "<i>Enable default optimizations</i>"),
505 clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
506 clEnumValEnd));
508 ...
509 if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
510 ...
511 </pre></div>
514 "<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
515 that are listed in the declaration (Note that the declaration list must be
516 terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
517 library enforces
518 that the user can only specify one of the options, and it ensure that only valid
519 enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
520 command line arguments matched the enum values. With this option added, our
521 help output now is:</p>
526 OPTIONS:
527 <b>Choose optimization level:
528 -g - No optimizations, enable debugging
529 -O1 - Enable trivial optimizations
530 -O2 - Enable default optimizations
531 -O3 - Enable expensive optimizations</b>
532 -f - Overwrite output files
533 -help - display available options (--help-hidden for more)
535 -quiet - Don't print informational messages
536 </pre></div>
538 <p>In this case, it is sort of awkward that flag names correspond directly to
539 enum names, because we probably don't want a enum definition named "<tt>g</tt>"
540 in our program. Because of this, we can alternatively write this example like
541 this:</p>
544 enum OptLevel {
545 Debug, O1, O2, O3
546 };
548 <a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
551 clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
552 clEnumVal(O2 , "<i>Enable default optimizations</i>"),
553 clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
554 clEnumValEnd));
556 ...
557 if (OptimizationLevel == Debug) outputDebugInfo(...);
558 ...
559 </pre></div>
562 can directly specify the name that the flag should get. In general a direct
563 mapping is nice, but sometimes you can't or don't want to preserve the mapping,
564 which is when you would use it.</p>
566 </div>
568 <!-- ======================================================================= -->
571 </div>
575 <p>Another useful argument form is a named alternative style. We shall use this
576 style in our compiler to specify different debug levels that can be used.
577 Instead of each debug level being its own switch, we want to support the
578 following options, of which only one can be specified at a time:
580 "<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
581 our optimization level flags, but we also specify an option name. For this
582 case, the code looks like this:</p>
585 enum DebugLev {
586 nodebuginfo, quick, detailed
587 };
589 // Enable Debug Options to be specified on the command line
590 <a href="#cl::opt">cl::opt</a><DebugLev> DebugLevel("<i>debug_level</i>", <a href="#cl::desc">cl::desc</a>("<i>Set the debugging level:</i>"),
593 clEnumVal(quick, "<i>enable quick debug information</i>"),
594 clEnumVal(detailed, "<i>enable detailed debug information</i>"),
595 clEnumValEnd));
596 </pre></div>
599 DebugLev</tt>", which works exactly the same way as before. The difference here
600 is just the interface exposed to the user of your program and the help output by
606 OPTIONS:
607 Choose optimization level:
608 -g - No optimizations, enable debugging
609 -O1 - Enable trivial optimizations
610 -O2 - Enable default optimizations
611 -O3 - Enable expensive optimizations
612 <b>-debug_level - Set the debugging level:
613 =none - disable debug information
614 =quick - enable quick debug information
615 =detailed - enable detailed debug information</b>
616 -f - Overwrite output files
617 -help - display available options (--help-hidden for more)
619 -quiet - Don't print informational messages
620 </pre></div>
622 <p>Again, the only structural difference between the debug level declaration and
623 the optimization level declaration is that the debug level declaration includes
625 library processes the argument. The CommandLine library supports both forms so
626 that you can choose the form most appropriate for your application.</p>
628 </div>
630 <!-- ======================================================================= -->
633 </div>
637 <p>Now that we have the standard run of the mill argument types out of the way,
638 lets get a little wild and crazy. Lets say that we want our optimizer to accept
640 might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
641 this case, the order of the arguments and the number of appearances is very
643 template is for. First, start by defining an enum of the optimizations that you
644 would like to perform:</p>
647 enum Opts {
648 // 'inline' is a C++ keyword, so name it 'inlining'
649 dce, constprop, inlining, strip
650 };
651 </pre></div>
656 <a href="#cl::list">cl::list</a><Opts> OptimizationList(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
658 clEnumVal(dce , "<i>Dead Code Elimination</i>"),
659 clEnumVal(constprop , "<i>Constant Propagation</i>"),
661 clEnumVal(strip , "<i>Strip Symbols</i>"),
662 clEnumValEnd));
663 </pre></div>
665 <p>This defines a variable that is conceptually of the type
666 "<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
667 vector methods:</p>
670 for (unsigned i = 0; i != OptimizationList.size(); ++i)
671 switch (OptimizationList[i])
672 ...
673 </pre></div>
678 completely general and may be used with any data types or other arguments that
680 especially useful way to use a list is to capture all of the positional
681 arguments together if there may be more than one specified. In the case of a
683 capture them into a list. This is naturally specified as:</p>
686 ...
687 <a href="#cl::list">cl::list</a><std::string> InputFilenames(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<Input files>"), <a href="#cl::OneOrMore">cl::OneOrMore</a>);
688 ...
689 </pre></div>
692 such, accessing the list is simple, just like above. In this example, we used
694 CommandLine library that it is an error if the user does not specify any
696 checking we have to do.</p>
698 </div>
700 <!-- ======================================================================= -->
703 </div>
707 <p>Instead of collecting sets of options in a list, it is also possible to
712 specified value is parsed, the resulting enum's bit is set in the option's bit
713 vector:</p>
717 </pre></div>
719 <p>Options that are specified multiple times are redundant. Any instances after
720 the first are discarded.</p>
726 <a href="#cl::bits">cl::bits</a><Opts> OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
728 clEnumVal(dce , "<i>Dead Code Elimination</i>"),
729 clEnumVal(constprop , "<i>Constant Propagation</i>"),
731 clEnumVal(strip , "<i>Strip Symbols</i>"),
732 clEnumValEnd));
733 </pre></div>
739 if (OptimizationBits.isSet(constprop)) {
740 ...
741 }
742 </pre></div>
744 <p>It's also possible to get the raw bit vector using the
748 unsigned bits = OptimizationBits.getBits();
749 </pre></div>
751 <p>Finally, if external storage is used, then the location specified must be of
756 </div>
759 <!-- ======================================================================= -->
762 </div>
766 <p>As our program grows and becomes more mature, we may decide to put summary
767 information about what it does into the help output. The help output is styled
770 the program does. To add this to your CommandLine program, simply pass a third
771 argument to the <a
773 call in main. This additional argument is then printed as the overview
774 information for your program, allowing you to include any additional information
775 that you want. For example:</p>
778 int main(int argc, char **argv) {
779 <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv, " CommandLine compiler example\n\n"
780 " This program blah blah blah...\n");
781 ...
782 }
783 </pre></div>
788 <b>OVERVIEW: CommandLine compiler example
790 This program blah blah blah...</b>
794 OPTIONS:
795 ...
796 -help - display available options (--help-hidden for more)
798 </pre></div>
800 </div>
803 <!-- *********************************************************************** -->
806 </div>
807 <!-- *********************************************************************** -->
811 <p>Now that you know the basics of how to use the CommandLine library, this
812 section will give you the detailed information you need to tune how command line
813 options work, as well as information on more "advanced" command line option
814 processing capabilities.</p>
816 </div>
818 <!-- ======================================================================= -->
821 </div>
825 <p>Positional arguments are those arguments that are not named, and are not
826 specified with a hyphen. Positional arguments should be used when an option is
828 tool takes a regular expression argument, and an optional filename to search
829 through (which defaults to standard input if a filename is not specified).
830 Using the CommandLine library, this would be specified as:</p>
833 <a href="#cl::opt">cl::opt</a><string> Regex (<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><regular expression></i>"), <a href="#cl::Required">cl::Required</a>);
834 <a href="#cl::opt">cl::opt</a><string> Filename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
835 </pre></div>
838 replacement would look like this:</p>
843 OPTIONS:
844 -help - display available options (--help-hidden for more)
845 </pre></div>
847 <p>... and the resultant program could be used just like the standard
850 <p>Positional arguments are sorted by their order of construction. This means
851 that command line options will be ordered according to how they are listed in a
852 .cpp file, but will not have an ordering defined if the positional arguments
853 are defined in multiple .cpp files. The fix for this problem is simply to
854 define all of your positional arguments in one .cpp file.</p>
856 </div>
859 <!-- _______________________________________________________________________ -->
862 </div>
866 <p>Sometimes you may want to specify a value to your positional argument that
868 first, you will have trouble doing this, because it will try to find an argument
873 $ spiffygrep '-foo' test.txt
874 Unknown command line argument '-foo'. Try: spiffygrep --help'
876 $ grep '-foo' test.txt
877 grep: illegal option -- f
878 grep: illegal option -- o
879 grep: illegal option -- o
880 Usage: grep -hblcnsviw pattern file . . .
881 </pre></div>
883 <p>The solution for this problem is the same for both your tool and the system
885 the command line, it is telling the program that all options after the
887 can use it like this:</p>
890 $ spiffygrep -- -foo test.txt
891 ...output...
892 </pre></div>
894 </div>
896 <!-- _______________________________________________________________________ -->
899 </div>
901 <p>Sometimes an option can affect or modify the meaning of another option. For
904 the file to be interpreted as if it contained source code in language
906 absolute position of each argument, especially those in lists, so their
907 interaction(s) can be applied correctly. This is also useful for options like
909 a dash.</p>
911 that interact in some way. To ensure the correct interaction, you can use the
921 int main(int argc, char**argv) {
922 // ...
926 while ( 1 ) {
927 if ( libIt != Libraries.end() )
928 libPos = Libraries.getPosition( libIt - Libraries.begin() );
929 else
930 libPos = 0;
931 if ( fileIt != Files.end() )
932 filePos = Files.getPosition( fileIt - Files.begin() );
933 else
934 filePos = 0;
937 // Source File Is next
938 ++fileIt;
939 }
941 // Library is next
942 ++libIt;
943 }
944 else
945 break; // we're done with the list
946 }
947 }</pre></div>
951 of that option. You can apply the same approach as above with a
953 </div>
955 <!-- _______________________________________________________________________ -->
958 </div>
963 used to construct programs that use "interpreter style" option processing. With
964 this style of option processing, all arguments specified after the last
965 positional argument are treated as special interpreter arguments that are not
966 interpreted by the command line argument.</p>
968 <p>As a concrete example, lets say we are developing a replacement for the
971 output), then you specify the name of the script to run, then you specify
972 arguments to the script. These arguments to the script are parsed by the bourne
973 shell command line option processor, but are not interpreted as options to the
974 shell itself. Using the CommandLine library, we would specify this as:</p>
977 <a href="#cl::opt">cl::opt</a><string> Script(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input script></i>"), <a href="#cl::init">cl::init</a>("-"));
978 <a href="#cl::list">cl::list</a><string> Argv(<a href="#cl::ConsumeAfter">cl::ConsumeAfter</a>, <a href="#cl::desc">cl::desc</a>("<i><program arguments>...</i>"));
979 <a href="#cl::opt">cl::opt</a><bool> Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
980 </pre></div>
987 OPTIONS:
988 -help - display available options (--help-hidden for more)
990 </pre></div>
996 were specified after the last positional argument (which is the script
997 name).</p>
1006 </div>
1008 <!-- ======================================================================= -->
1011 </div>
1015 <p>By default, all command line options automatically hold the value that they
1016 parse from the command line. This is very convenient in the common case,
1017 especially when combined with the ability to define command line options in the
1018 files that use them. This is called the internal storage model.</p>
1020 <p>Sometimes, however, it is nice to separate the command line option processing
1021 code from the storage of the value parsed. For example, lets say that we have a
1023 across the entire body of our program. In this case, the boolean value
1024 controlling the debug code should be globally accessable (in a header file, for
1025 example) yet the command line option processing code should not be exposed to
1026 all of these clients (requiring lots of .cpp files to #include
1032 <pre>
1033 <i>// DebugFlag.h - Get access to the '-debug' command line option
1034 //
1036 // DebugFlag - This boolean is set to true if the '-debug' command line option
1037 // is specified. This should probably not be referenced directly, instead, use
1038 // the DEBUG macro below.
1039 //</i>
1040 extern bool DebugFlag;
1042 <i>// DEBUG macro - This macro should be used by code to emit debug information.
1043 // In the '-debug' option is specified on the command line, and if this is a
1044 // debug build, then the code specified as the option to the macro will be
1045 // executed. Otherwise it will not be. Example:
1046 //
1048 //</i>
1050 #define DEBUG(X)
1051 #else
1054 </pre>
1055 </div>
1060 an additial argument to our command line argument processor, and we specify
1062 attribute:</p>
1065 <pre>
1068 Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>"), <a href="#cl::Hidden">cl::Hidden</a>, <a href="#cl::location">cl::location</a>(DebugFlag));
1069 </pre>
1070 </div>
1074 template should not maintain a copy of the value itself. In addition to this,
1078 </div>
1080 <!-- ======================================================================= -->
1083 </div>
1087 <p>This section describes the basic attributes that you can specify on
1088 options.</p>
1090 <ul>
1094 This option is specified in simple double quotes:
1096 <pre>
1098 </pre>
1100 </li>
1104 program.</li>
1109 example.</li>
1113 not specified then the command line option value defaults to the value created
1118 initial value. (You will get an error at runtime if you don't put them in
1119 the right order.)</li>
1122 store the value for a parsed command line option if using external storage. See
1124 information.</li>
1128 an alias for.</li>
1131 the string-to-value mapping to be used by the generic parser. It takes a
1133 that
1134 specify the option name, the value mapped to, and the description shown in the
1136 frequently with enum values, two macros are often useful:
1138 <ol>
1141 nice simple way to specify a triplet for an enum. This macro automatically
1142 makes the option name be the same as the enum name. The first option to the
1143 macro is the enum, the second is the description for the command line
1144 option.</li>
1147 specify macro options where the option name doesn't equal the enum name. For
1148 this macro, the first argument is the enum value, the second is the flag name,
1149 and the second is the description.</li>
1151 </ol>
1153 You will get a compile time error if you try to use cl::values with a parser
1154 that does not support it.</li>
1156 </ul>
1158 </div>
1160 <!-- ======================================================================= -->
1163 </div>
1167 <p>Option modifiers are the flags and expressions that you pass into the
1171 your application well.</p>
1175 <ol>
1178 required and allowed</a></li>
1180 specified</a></li>
1183 </ol>
1185 <p>It is not possible to specify two options from the same catagory (you'll get
1186 a runtime error) to a single option, except for options in the miscellaneous
1187 catagory. The CommandLine library specifies defaults for all of these settings
1188 that are the most useful in practice and the most common, which mean that you
1189 usually shouldn't have to worry about these.</p>
1191 </div>
1193 <!-- _______________________________________________________________________ -->
1196 </div>
1203 compiled program:</p>
1205 <ul>
1210 in both help listings.</li>
1218 indicates that the option should not appear in any help output.</li>
1220 </ul>
1222 </div>
1224 <!-- _______________________________________________________________________ -->
1227 allowed</a>
1228 </div>
1232 <p>This group of options is used to control how many time an option is allowed
1233 (or required) to be specified on the command line of your program. Specifying a
1234 value for this setting allows the CommandLine library to do error checking for
1235 you.</p>
1239 <ul>
1244 allow either zero or one occurrence of the option to be specified.</li>
1248 indicates that your program will allow the option to be specified zero or more
1249 times.</li>
1252 indicates that the specified option must be specified exactly one time.</li>
1255 indicates that the option must be specified at least one time.</li>
1260 </ul>
1262 <p>If an option is not specified, then the value of the option is equal to the
1265 option value is initialized with the default constructor for the data type.</p>
1269 retained.</p>
1271 </div>
1273 <!-- _______________________________________________________________________ -->
1276 </div>
1280 <p>This group of options is used to control whether or not the option allows a
1281 value to be present. In the case of the CommandLine library, a value is either
1287 <ul>
1291 acceptable to have a value, or not. A boolean argument can be enabled just by
1293 If an option is specified with this mode, it is illegal for the value to be
1295 get this behavior, you must use the <a
1299 (which is the default for all other types except for <a
1301 specifies that a value must be provided. This mode informs the command line
1302 library that if an option is not provides with an equal sign, that the next
1303 argument provided must be the value. This allows things like '<tt>-o
1308 alternatives using the generic parser</a>) indicates that it is a runtime error
1309 for the user to specify a value. This can be provided to disallow users from
1312 </ul>
1314 <p>In general, the default values for this option group work just like you would
1315 want them to. As mentioned above, you can specify the <a
1317 argument to restrict your command line parser. These options are mostly useful
1320 </div>
1322 <!-- _______________________________________________________________________ -->
1325 </div>
1329 <p>The formatting option group is used to specify that the command line option
1330 has special abilities and is otherwise different from other command line
1331 arguments. As usual, you can only specify at most one of these arguments.</p>
1333 <ul>
1336 modifier (which is the default all options) specifies that this option is
1340 specifies that this is a positional argument, that does not have a command line
1345 specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
1348 that this option prefixes its value. With 'Prefix' options, the equal sign does
1349 not separate the value from the option name specified. Instead, the value is
1350 everything after the prefix, including any equal sign if present. This is useful
1355 modifier added to allow the CommandLine library to recognize them. Note that
1358 specified.</li>
1363 command actually enables four different options, all of which are single
1365 options cannot have values.</li>
1367 </ul>
1372 specify ambiguous argument settings. Thus, it is possible to have multiple
1373 letter options that are prefix or grouping options, and they will still work as
1374 designed.</p>
1376 <p>To do this, the CommandLine library uses a greedy algorithm to parse the
1377 input option into (potentially multiple) prefix and grouping options. The
1378 strategy basically looks like this:</p>
1382 <ol>
1384 <li><tt>if (isOption(input)) return getOption(input).parse();</tt> <i>// Normal option</i>
1385 <li><tt>while (!isOption(input) && !input.empty()) input.pop_back();</tt> <i>// Remove the last letter</i>
1386 <li><tt>if (input.empty()) return error();</tt> <i>// No matching option</i>
1394 }</tt>
1396 </ol>
1399 </div>
1401 </div>
1403 <!-- _______________________________________________________________________ -->
1406 </div>
1410 <p>The miscellaneous option modifiers are the only flags where you can specify
1411 more than one flag from the set: they are not mutually exclusive. These flags
1412 specify boolean properties that modify the option.</p>
1414 <ul>
1417 indicates that any commas specified for an option's value should be used to
1418 split the value up into multiple values for the option. For example, these two
1421 makes sense to be used in a case where the option is allowed to accept one or
1426 positional arguments, and only makes sense for lists) indicates that positional
1427 argument should consume any strings after it (including strings that start with
1428 a "-") up until another recognized positional argument. For example, if you
1434 </ul>
1438 </div>
1440 <!-- ======================================================================= -->
1443 </div>
1447 <p>Despite all of the built-in flexibility, the CommandLine option library
1448 really only consists of one function (<a
1453 classes in detail.</p>
1455 </div>
1457 <!-- _______________________________________________________________________ -->
1460 function</a>
1461 </div>
1468 available.</p>
1475 </div>
1477 <!-- _______________________________________________________________________ -->
1480 function</a>
1481 </div>
1486 as <a
1488 except that it is designed to take values for options from an environment
1489 variable, for those cases in which reading the command line is not convenient or
1490 not desired. It fills in the values of all the command line option variables
1491 just like <a
1493 does.</p>
1495 <p>It takes three parameters: first, the name of the program (since
1497 second, the name of the environment variable to examine, and third, the optional
1502 variable's value up into words and then process them using
1507 which is different from what you would get from the shell with the same
1508 input.</p>
1510 </div>
1512 <!-- _______________________________________________________________________ -->
1515 function</a>
1516 </div>
1525 for LLVM. This is useful for programs that are not part of LLVM but wish to use
1528 whatever version information is appropriate for the program. Pass the address
1532 </div>
1533 <!-- _______________________________________________________________________ -->
1536 </div>
1541 options, and is the one used most of the time. It is a templated class which
1542 can take up to three arguments (all except for the first have default values
1543 though):</p>
1550 }
1551 </pre></div>
1553 <p>The first template argument specifies what underlying data type the command
1554 line argument is, and is used to select a default parser implementation. The
1555 second template argument is used to specify whether the option should contain
1556 the storage for the option (the default) or whether external storage should be
1560 <p>The third template argument specifies which parser to use. The default value
1562 data type of the option. In general, this default works well for most
1563 applications, so this option is only used when using a <a
1566 </div>
1568 <!-- _______________________________________________________________________ -->
1571 </div>
1576 line options. It too is a templated class which can take up to three
1577 arguments:</p>
1584 }
1585 </pre></div>
1591 be used.</p>
1593 </div>
1595 <!-- _______________________________________________________________________ -->
1598 </div>
1603 line options in the form of a bit vector. It is also a templated class which
1604 can take up to three arguments:</p>
1611 }
1612 </pre></div>
1618 </div>
1620 <!-- _______________________________________________________________________ -->
1623 </div>
1628 aliases for other arguments.</p>
1633 }
1634 </pre></div>
1637 used to specify which option this is an alias for. Alias arguments default to
1639 the conversion from string to data.</p>
1641 </div>
1643 <!-- _______________________________________________________________________ -->
1646 </div>
1656 }
1657 </pre></div>
1660 parameter to the constructor. The text passed to the constructor will be printed
1661 at the bottom of the help message, verbatim. Note that multiple
1663 your tool needs to print additional help information, put all that help into a
1667 cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
1668 </pre></div>
1669 </div>
1671 <!-- ======================================================================= -->
1674 </div>
1678 <p>Parsers control how the string value taken from the command line is
1679 translated into a typed value, suitable for use in a C++ program. By default,
1682 Because of this, custom option processing is specified with specializations of
1685 <p>The CommandLine library provides the following builtin parser
1686 specializations, which are sufficient for most applications. It can, however,
1687 also be extended to work with new data types and new ways of interpreting the
1689 details on this type of library extension.</p>
1691 <ul>
1694 can be used to map strings values to any data type, through the use of the <a
1696 information. The most common use of this parser is for parsing enum values,
1697 which allows you to use the CommandLine library for all of the error checking to
1698 make sure that only valid enum values are specified (as opposed to accepting
1699 arbitrary strings). Despite this, however, the generic parser class can be used
1700 for any data type.</li>
1703 is used to convert boolean strings to a boolean value. Currently accepted
1708 specialization</b></a> is used for cases where the value is boolean,
1709 but we also need to know whether the option was specified at all. boolOrDefault
1710 is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
1714 specialization</b></a> simply stores the parsed string into the string value
1715 specified. No conversion or modification of the data is performed.</li>
1719 accept a decimal number (with an optional '+' or '-' prefix) which must start
1720 with a non-zero digit. It accepts octal numbers, which are identified with a
1727 values. As such, a broad range of string formats is supported, including
1729 </li>
1731 </ul>
1733 </div>
1735 <!-- *********************************************************************** -->
1738 </div>
1739 <!-- *********************************************************************** -->
1743 <p>Although the CommandLine library has a lot of functionality built into it
1744 already (as discussed previously), one of its true strengths lie in its
1745 extensibility. This section discusses how the CommandLine library works under
1746 the covers and illustrates how to do some simple, common, extensions.</p>
1748 </div>
1750 <!-- ======================================================================= -->
1753 </div>
1757 <p>One of the simplest and most common extensions is the use of a custom parser.
1759 of the CommandLine library that turns string input from the user into a
1760 particular parsed data type, validating the input in the process.</p>
1764 <ol>
1766 <li>
1769 your custom data type.<p>
1771 <p>This approach has the advantage that users of your custom data type will
1772 automatically use your custom parser whenever they define an option with a value
1773 type of your data type. The disadvantage of this approach is that it doesn't
1774 work if your fundamental data type is something that is already supported.</p>
1776 </li>
1778 <li>
1780 <p>Write an independent class, using it explicitly from options that need
1781 it.</p>
1783 <p>This approach works well in situations where you would line to parse an
1784 option using special syntax for a not-very-special data-type. The drawback of
1785 this approach is that users of your parser have to be aware that they are using
1786 your parser, instead of the builtin ones.</p>
1788 </li>
1790 </ol>
1792 <p>To guide the discussion, we will discuss a custom parser that accepts file
1793 sizes, specified with an optional unit after the numeric size. For example, we
1795 this case, the underlying data type we want to parse into is
1804 <b>bool</b> parse(cl::Option &O, <b>const char</b> *ArgName, <b>const</b> std::string &ArgValue,
1806 };
1807 </pre></div>
1810 fill in the default, boiler plate, code for us. We give it the data type that
1812 our custom parser know what object type to pass in to the parse method (here we
1815 <p>For most purposes, the only method that must be implemented in a custom
1817 whenever the option is invoked, passing in the option itself, the option name,
1818 the string to parse, and a reference to a return value. If the string to parse
1819 is not well formed, the parser should output an error message and return true.
1843 default:
1846 }
1847 }
1848 }
1849 </pre></div>
1851 <p>This function implements a very simple parser for the kinds of strings we are
1852 interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for
1853 example), it is good enough for this example. Note that we use the option
1855 true) in order to get a nice error message (shown below). Now that we have our
1856 parser class, we can use it like this:</p>
1859 <b>static</b> <a href="#cl::opt">cl::opt</a><<b>unsigned</b>, <b>false</b>, FileSizeParser>
1860 MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
1862 </pre></div>
1867 OPTIONS:
1868 -help - display available options (--help-hidden for more)
1869 ...
1871 </pre></div>
1873 <p>And we can test that our parse works correctly now (the test program just
1874 prints out the max-file-size argument value):</p>
1877 $ ./test
1878 MFS: 0
1879 $ ./test -max-file-size=123MB
1880 MFS: 128974848
1881 $ ./test -max-file-size=3G
1882 MFS: 3221225472
1883 $ ./test -max-file-size=dog
1884 -max-file-size option: 'dog' value invalid for file size argument!
1885 </pre></div>
1887 <p>It looks like it works. The error message that we get is nice and helpful,
1888 and we seem to accept reasonable file sizes. This wraps up the "custom parser"
1889 tutorial.</p>
1891 </div>
1893 <!-- ======================================================================= -->
1896 </div>
1900 will automatically be included in any program that links with that library.
1901 This is a feature. However, sometimes it is necessary to know the value of the
1902 command line option outside of the library. In these cases the library does or
1903 should provide an external storage location that is accessible to users of the
1910 </div>
1912 <!-- ======================================================================= -->
1915 </div>
1921 </div>
1923 <!-- *********************************************************************** -->
1925 <hr>
1926 <address>
1934 Last modified: $Date$
1935 </address>
1937 </body>
1938 </html>