Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 5acd166ff52fd34824fec046308631998e87626c / . / docs / CommandLine.html
blob: 7672ec44aca98258a354abc849b970d75680297c [file] [log] [blame]
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]2<html><head><title>CommandLine 2.0 Library Manual</title></head>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]3<body bgcolor=white>
4
5<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]6<tr><td>&nbsp; <font size=+4 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>CommandLine 2.0 Library Manual</b></font></td>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]7</tr></table>
8
9<ol>
10 <li><a href="#introduction">Introduction</a>
11 <li><a href="#quickstart">Quick Start Guide</a>
12 <ol>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]13 <li><a href="#bool">Boolean Arguments</a>
14 <li><a href="#alias">Argument Aliases</a>
15 <li><a href="#onealternative">Selecting an alternative from a set of possibilities</a>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]16 <li><a href="#namedalternatives">Named alternatives</a>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]17 <li><a href="#list">Parsing a list of options</a>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]18 </ol>
19 <li><a href="#referenceguide">Reference Guide</a>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]20 <ol>
21 <li>Option Modifiers:
22 <ul>
23 <li>Controlling whether or not the option is shown by <tt>--help</tt>
24 <li>Controlling the number of occurances required and allowed
25 <li>Controlling whether or not a value must be specified
26 <li>Controlling other formatting options
27 </ul>
28 <li>Positional Arguments
29 <li>Internal vs External Storage
30 <li>The option classes
31 <ul>
32 <li>The <tt>opt&lt;&gt;</tt> class
33 <li>The <tt>list&lt;&gt;</tt> class
34 <li>The <tt>alias</tt> class
35 </ul>
36 </ol>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]37 <li><a href="#extensionguide">Extension Guide</a>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]38 <ol>
39 <li>Writing a custom parser
40 <li>Exploiting external storage
41 <li>Dynamically adding command line options
42 </ol>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]43</ol><p>
44
45
46<!-- *********************************************************************** -->
47</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
48<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
49<a name="introduction">Introduction
50</b></font></td></tr></table><ul>
51<!-- *********************************************************************** -->
52
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]53This document describes the CommandLine argument processing library. It will
54show you how to use it, and what it can do.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]55
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]56Although there are a <b>lot</b> of command line argument parsing libraries out
57there in many different languages, none of them fit well with what I needed. By
58looking at the features and problems of other libraries, I designed the
59CommandLine library to have the following features:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]60
61<ol>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]62<li>Speed: The CommandLine library is very quick and uses little resources. The
63parsing time of the library is directly proportional to the number of arguments
64parsed, not the the number of options recognized. Additionally, command line
65argument values are captured transparently into user defined variables, which
66can be accessed like any other variable (and with the same performance).<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]67
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]68<li>Type Safe: As a user of CommandLine, you don't have to worry about
69remembering the type of arguments that you want (is it an int? a string? a
70bool? an enum?) and keep casting it around. Not only does this help prevent
71error prone constructs, it also leads to dramatically cleaner source code.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]72
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]73<li>No subclasses required: To use CommandLine, you instantiate variables that
74correspond to the arguments that you would like to capture, you don't subclass a
75parser. This leads to much less boilerplate code.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]76
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]77<li>Globally accessible: Libraries can specify command line arguments that are
78automatically enabled in any tool that links to the library. This is possible
79because the application doesn't have to keep a "list" of arguments to pass to
80the parser.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]81
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]82<li>More Clean: CommandLine supports enum types directly, meaning that there is
83less error and more security built into the library. You don't have to worry
84about whether your integral command line argument accidentally got assigned a
85value that is not valid for your enum type.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]86
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]87<li>Powerful: The CommandLine library supports many different types of
88arguments, from simple boolean flags to scalars arguments (strings, integers,
89enums, doubles), to lists of arguments. This is possible because CommandLine
90is...<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]91
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]92<li>Extensible: It is very simple to add a new argument type to CommandLine.
93Simply specify the parser that you want to use with the command line option when
94you declare it. Custom parsers are no problem.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]95
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]96<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
97that you, the user, have to do. For example, it automatically provides a --help
98option that shows the available command line options for your tool.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]99</ol>
100
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]101This document will hopefully let you jump in and start using CommandLine in your
102utility quickly and painlessly. Additionally it should be a simple reference
103manual to figure out how stuff works. If it is failing in some area, nag the
104author, <a href="mailto:sabre@nondot.org">Chris Lattner</a>.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]105
106
107<!-- *********************************************************************** -->
108</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>
109<a name="quickstart">Quick Start Guide
110</b></font></td></tr></table><ul>
111<!-- *********************************************************************** -->
112
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]113This section of the manual runs through a simple CommandLine'ification of a
114basic compiler tool. This is intended to show you how to jump into using the
115CommandLine library in your own program, and show you some of the cool things it
116can do.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]117
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]118To start out, you need to include the CommandLine header file into your
119program:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]120
121<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]122 #include "Support/CommandLine.h"
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]123</pre><p>
124
125Additionally, you need to add this as the first line of your main program:<p>
126
127<pre>
128int main(int argc, char **argv) {
129 cl::ParseCommandLineOptions(argc, argv);
130 ...
131}
132</pre><p>
133
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]134... which actually parses the arguments and fills in the variable
135declarations.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]136
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]137Now that you are ready to support command line arguments, we need to tell the
138system which ones we want, and what type of argument they are. The CommandLine
139library uses a declarative syntax to model cammand line arguments with the
140variable declarations that capture the parsed values. This means that for every
141command line option that you would like to support, there should be a variable
142declaration to capture the result. For example, in a compiler, we would like to
143support the unix standard '<tt>-o &lt;filename&gt;</tt>' option to specify where
144to put the output. With the CommandLine library, this is represented like
145this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]146
147<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]148cl::opt&lt;string&gt; OutputFilename("<i>o</i>", cl::desc("<i>Specify output filename</i>"), cl::value_desc("<i>filename</i>"));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]149</pre><p>
150
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]151This declares a variable "<tt>OutputFilename</tt>" that is used to capture the
152result of the "<tt>o</tt>" argument (first parameter). We specify that this is
153a simple scalar option by using the "<tt>opt&lt;&gt;</tt>" template (as opposed
154to the <a href="#list">"<tt>list&lt;&gt;</tt> template</a>), and tell the
155CommandLine library that the data type that we are parsing is a string.<p>
156
157The second and third parameters (which are optional) are used to specify what to
158output for the "<tt>--help</tt>" option. In this case, we get a line that looks
159like this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]160
161<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]162USAGE: compiler [options]
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]163
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]164OPTIONS:
165 -help - display available options (--help-hidden for more)
166 -o &lt;filename&gt; - Specify output filename
167</pre>
168
169Because we specified that the command line option should parse using the
170<tt>string</tt> data type, the variable declared is automatically usable as a
171real string in all contexts that a normal C++ string object may be used. For
172example:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]173
174<pre>
175 ...
176 ofstream Output(OutputFilename.c_str());
177 if (Out.good()) ...
178 ...
179</pre><p>
180
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]181There are many different options that you can use to customize the command line
182option handling library, but the above example shows the general interface to
183these options. The options can be specified in any order, and are specified
184with helper functions like <tt>cl::desc(...)</tt>, so there are no positional
185dependencies to have to remember. We will discuss the options you can use later
186in this document. Also note that if your compiler supports Koenig lookup (gcc
1872.95.x doesn't), that you don't have to specify as many <tt>cl::</tt> namespace
188qualifiers to use the library.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]189
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]190Continuing the example, we would like to have our compiler take an input
191filename as well as an output filename, but we do not want the input filename to
192be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
193style of argument, the CommandLine library allows for positional arguments to be
194specified for the program. These positional arguments are filled with command
195line parameters that are not in option form. We use this feature like this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]196
197<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]198cl::opt&lt;string&gt; InputFilename(cl::Positional, cl::desc("<i>&lt;input file&gt;</i>"), cl::init("<i>-</i>"));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]199</pre>
200
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]201This declaration indicates that the first positional argument should be treated
202as the input filename. Here we use the <tt>cl::init</tt> option to specify an
203initial value for the command line option, which is used if the option is not
204specified (if you do not specify a <tt>cl::init</tt> modifier for an option,
205then the default constructor for the data type is used to initialize the value).
206Command line options default to being optional, so if we would like to require
207that the user always specify an input filename, we would add the
208<tt>cl::Required</tt> flag, and we could eliminate the <tt>cl::init</tt>
209modifier, like this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]210
211<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]212cl::opt&lt;string&gt; InputFilename(cl::Positional, cl::desc("<i>&lt;input file&gt;</i>"), <b>cl::Required</b>);
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]213</pre>
214
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]215Again, the CommandLine library does not require the options to be specified in
216any particular order, so the above declaration is equivalent to:<p>
217
218<pre>
219cl::opt&lt;string&gt; InputFilename(cl::Positional, cl::Required, cl::desc("<i>&lt;input file&gt;</i>"));
220</pre>
221
222By simply adding the <tt>cl::Required</tt> flag, the CommandLine library will
223automatically issue an error if the argument is not specified, which shifts all
224of the command line option verification code out of your application into the
225library. This is just one example of how using flags can alter the default
226behaviour of the library, on a per-option basis. By adding one of the
227declarations above, the <tt>--help</tt> option synopsis is now extended to:<p>
228
229<pre>
230USAGE: compiler [options] &lt;input file&gt;
231
232OPTIONS:
233 -help - display available options (--help-hidden for more)
234 -o &lt;filename&gt; - Specify output filename
235</pre>
236
237... indicating that an input filename is expected.<p>
238
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]239
240<!-- ======================================================================= -->
241</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]242<a name="bool">Boolean Arguments
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]243</b></font></td></tr></table><ul>
244
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]245In addition to input and output filenames, we would like the compiler example to
246support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
247file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
248compatibility with some of our users. We can support these by declaring options
249of boolean type like this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]250
251<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]252cl::opt&lt;bool&gt; Force ("<i>f</i>", cl::desc("<i>Overwrite output files</i>"));
253cl::opt&lt;bool&gt; Quiet ("<i>quiet</i>", cl::desc("<i>Don't print informational messages</i>"));
254cl::opt&lt;bool&gt; Quiet2("<i>q</i>", cl::desc("<i>Don't print informational messages</i>"), cl::Hidden);
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]255</pre><p>
256
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]257This does what you would expect: it declares three boolean variables
258("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
259options. Note that the "<tt>-q</tt>" option is specified with the
260"<tt>cl::Hidden</tt>" flag. This modifier prevents it from being shown by the
261standard "<tt>--help</tt>" output (note that it is still shown in the
262"<tt>--help-hidden</tt>" output).<p>
263
264The CommandLine library uses a different parser for different data types. For
265example, in the string case, the argument passed to the option is copied
266literally into the content of the string variable... we obviously cannot do that
267in the boolean case, however, so we must use a smarter parser. In the case of
268the boolean parser, it allows no options (in which case it assigns the value of
269true to the variable), or it allows the values "<tt>true</tt>" or
270"<tt>false</tt>" to be specified, allowing any of the following inputs:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]271
272<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]273 compiler -f # No value, 'Force' == true
274 compiler -f=true # Value specified, 'Force' == true
275 compiler -f=TRUE # Value specified, 'Force' == true
276 compiler -f=FALSE # Value specified, 'Force' == false
277</pre>
278
279... you get the idea. The bool parser just turns the string values into boolean
280values, and rejects things like '<tt>compiler -f=foo</tt>'. Similarly, the
281float, double, and int parsers work like you would expect, using the
282'<tt>strtol</tt>' and '<tt>strtod</tt>' C library calls to parse the string
283value into the specified data type.<p>
284
285With the declarations above, "<tt>compiler --help</tt>" emits this:<p>
286
287<pre>
288USAGE: compiler [options] &lt;input file&gt;
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]289
290OPTIONS:
291 -f - Overwrite output files
292 -o - Override output filename
293 -quiet - Don't print informational messages
294 -help - display available options (--help-hidden for more)
295</pre><p>
296
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]297and "<tt>opt --help-hidden</tt>" prints this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]298
299<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]300USAGE: opt [options] &lt;input file&gt;
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]301
302OPTIONS:
303 -f - Overwrite output files
304 -o - Override output filename
305 -q - Don't print informational messages
306 -quiet - Don't print informational messages
307 -help - display available options (--help-hidden for more)
308</pre><p>
309
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]310This brief example has shown you how to use the '<tt>opt&lt;&gt;</tt>' class to
311parse simple scalar command line arguments. In addition to simple scalar
312arguments, the CommandLine library also provides primitives to support
313CommandLine option <a href="#alias">aliases</a>, and <a href="#list">lists</a>
314of options.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]315
316
317<!-- ======================================================================= -->
318</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]319<a name="alias">Argument Aliases
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]320</b></font></td></tr></table><ul>
321
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]322So far, the example works well, except for the fact that we need to check the
323quiet condition like this now:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]324
325<pre>
326...
327 if (!Quiet &amp;&amp; !Quiet2) printInformationalMessage(...);
328...
329</pre><p>
330
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]331... which is a real pain! Instead of defining two values for the same
332condition, we can use the "<tt>cl::alias</tt>" class to make the "<tt>-q</tt>"
333option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
334a value itself:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]335
336<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]337cl::opt&lt;bool&gt; Force ("<i>f</i>", cl::desc("<i>Overwrite output files</i>"));
338cl::opt&lt;bool&gt; Quiet ("<i>quiet</i>", cl::desc("<i>Don't print informational messages</i>"));
339cl::alias QuietA("<i>q</i>", cl::desc("<i>Alias for -quiet</i>"), cl::aliasopt(Quiet));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]340</pre><p>
341
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]342The third line (which is the only one we modified from above) defines a
343"<tt>-q</tt> alias that updates the "<tt>Quiet</tt>" variable (as specified by
344the <tt>cl::aliasopt</tt> modifier) whenever it is specified. Because aliases
345do not hold state, the only thing the program has to query is the <tt>Quiet</tt>
346variable now. Another nice feature of aliases is that they automatically hide
347themselves from the <tt>-help</tt> output (although, again, they are still
348visible in the <tt>--help-hidden output</tt>).<p>
349
350Now the application code can simply use:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]351
352<pre>
353...
354 if (!Quiet) printInformationalMessage(...);
355...
356</pre><p>
357
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]358... which is much nicer! The "<tt>cl::alias</tt>" can be used to specify an
359alternative name for any variable type, and has many uses.<p>
360
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]361
362
363<!-- ======================================================================= -->
364</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]365<a name="onealternative">Selecting an alternative from a set of possibilities
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]366</b></font></td></tr></table><ul>
367
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]368So far, we have seen how the CommandLine library handles builtin types like
369<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
370things it doesn't know about, like enums or '<tt>int*</tt>'s?<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]371
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]372The answer is that it uses a table driven generic parser (unless you specify
373your own parser, as described in the <a href="#extensionguide">Extension
374Guide</a>). This parser maps literal strings to whatever type is required, are
375requires you to tell it what this mapping should be.<p>
376
377Lets say that we would like to add four optimizations levels to our optimizer,
378using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>", "<tt>-O1</tt>", and
379"<tt>-O2</tt>". We could easily implement this with boolean options like above,
380but there are several problems with this strategy:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]381
382<ol>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]383<li>A user could specify more than one of the options at a time, for example,
384"<tt>opt -O3 -O2</tt>". The CommandLine library would not be able to catch this
385erroneous input for us.
386
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]387<li>We would have to test 4 different variables to see which ones are set.
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]388
389<li>This doesn't map to the numeric levels that we want... so we cannot easily
390see if some level &gt;= "<tt>-O1</tt>" is enabled.
391
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]392</ol><p>
393
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]394To cope with these problems, we can use an enum value, and have the CommandLine
395library fill it in with the appropriate level directly, which is used like
396this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]397
398<pre>
399enum OptLevel {
400 g, O1, O2, O3
401};
402
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]403cl::opt&lt;OptLevel&gt; OptimizationLevel(cl::desc("<i>Choose optimization level:</i>"),
404 cl::values(
405 clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
406 clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
407 clEnumVal(O2, "<i>Enable default optimizations</i>"),
408 clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
409 0));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]410
411...
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]412 if (OptimizationLevel &gt;= O2) doPartialRedundancyElimination(...);
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]413...
414</pre><p>
415
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]416This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
417"<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
418that are listed in the declaration (Note that the declaration list must be
419terminated with the "<tt>0</tt>" argument!). The CommandLine library enforces
420that the user can only specify one of the options, and it ensure that only valid
421enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
422command line arguments matche the enum values. With this option added, our help
423output now is:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]424
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]425<pre>
426USAGE: compiler [options] &lt;input file&gt;
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]427
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]428OPTIONS:
429 Choose optimization level:
430 -g - No optimizations, enable debugging
431 -O1 - Enable trivial optimizations
432 -O2 - Enable default optimizations
433 -O3 - Enable expensive optimizations
434 -f - Overwrite output files
435 -help - display available options (--help-hidden for more)
436 -o &lt;filename&gt; - Specify output filename
437 -quiet - Don't print informational messages
438</pre>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]439
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]440In this case, it is sort of awkward that flag names correspond directly to enum
441names, because we probably don't want a enum definition named "<tt>g</tt>" in
442our program. Because of this, we can alternatively write this example like
443this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]444
445<pre>
446enum OptLevel {
447 Debug, O1, O2, O3
448};
449
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]450cl::opt&lt;OptLevel&gt; OptimizationLevel(cl::desc("<i>Choose optimization level:</i>"),
451 cl::values(
452 clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
453 clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
454 clEnumVal(O2 , "<i>Enable default optimizations</i>"),
455 clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
456 0));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]457
458...
459 if (OptimizationLevel == Debug) outputDebugInfo(...);
460...
461</pre><p>
462
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]463By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we can
464directly specify the name that the flag should get. In general a direct mapping
465is nice, but sometimes you can't or don't want to preserve the mapping, which is
466when you would use it.<p>
467
468
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]469
470<!-- ======================================================================= -->
471</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
472<a name="namedalternatives">Named Alternatives
473</b></font></td></tr></table><ul>
474
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]475Another useful argument form is a named alternative style. We shall use this
476style in our compiler to specify different debug levels that can be used.
477Instead of each debug level being its own switch, we want to support the
478following options, of which only one can be specified at a time:
479"<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
480"<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
481our optimization level flags, but we also specify an option name. For this
482case, the code looks like this:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]483
484<pre>
485enum DebugLev {
486 nodebuginfo, quick, detailed
487};
488
489// Enable Debug Options to be specified on the command line
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]490cl::opt<DebugLev> DebugLevel("<i>debug_level</i>", cl::desc("<i>Set the debugging level:</i>"),
491 cl::values(
492 clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
493 clEnumVal(quick, "<i>enable quick debug information</i>"),
494 clEnumVal(detailed, "<i>enable detailed debug information</i>"),
495 0));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]496</pre>
497
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]498This definition defines an enumerated command line variable of type "<tt>enum
499DebugLev</tt>", which works exactly the same way as before. The difference here
500is just the interface exposed to the user of your program and the help output by
501the "<tt>--help</tt>" option:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]502
503<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]504USAGE: compiler [options] &lt;input file&gt;
505
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]506OPTIONS:
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]507 Choose optimization level:
508 -g - No optimizations, enable debugging
509 -O1 - Enable trivial optimizations
510 -O2 - Enable default optimizations
511 -O3 - Enable expensive optimizations
512 -debug_level - Set the debugging level:
513 =none - disable debug information
514 =quick - enable quick debug information
515 =detailed - enable detailed debug information
516 -f - Overwrite output files
517 -help - display available options (--help-hidden for more)
518 -o &lt;filename&gt; - Specify output filename
519 -quiet - Don't print informational messages
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]520</pre><p>
521
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]522Again, the only structural difference between the debug level declaration and
523the optimiation level declaration is that the debug level declaration includes
524an option name (<tt>"debug_level"</tt>), which automatically changes how the
525library processes the argument. The CommandLine library supports both forms so
526that you can choose the form most appropriate for your application.<p>
527
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]528
529
530<!-- ======================================================================= -->
531</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]532<a name="list">Parsing a list of options
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]533</b></font></td></tr></table><ul>
534
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]535Now that we have the standard run of the mill argument types out of the way,
536lets get a little wild and crazy. Lets say that we want our optimizer to accept
537a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
538might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
539this case, the order of the arguments and the number of appearances is very
540important. This is what the "<tt>cl::list</tt>" template is for. First,
541start by defining an enum of the optimizations that you would like to
542perform:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]543
544<pre>
545enum Opts {
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]546 // 'inline' is a C++ keyword, so name it 'inlining'
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]547 dce, constprop, inlining, strip
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]548};
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]549</pre><p>
550
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]551Then define your "<tt>cl::list</tt>" variable:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]552
553<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]554cl::list&lt;Opts&gt; OptimizationList(cl::desc("<i>Available Optimizations:</i>"),
555 cl::values(
556 clEnumVal(dce , "<i>Dead Code Elimination</i>"),
557 clEnumVal(constprop , "<i>Constant Propogation</i>"),
558 clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
559 clEnumVal(strip , "<i>Strip Symbols</i>"),
560 0));
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]561</pre><p>
562
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]563This defines a variable that is conceptually of the type
564"<tt>std::vector&lt;enum Opts&gt;</tt>". Thus, you can access it with standard
565vector methods:<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]566
567<pre>
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]568 for (unsigned i = 0; i != OptimizationList.size(); ++i)
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]569 switch (OptimizationList[i])
570 ...
571</pre>
572
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]573... to iterate through the list of options specified.<p>
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]574
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]575Note that the "<tt>cl::list</tt>" template is completely general and may be used
576with any data types or other arguments that you can use with the
577"<tt>cl::opt</tt>" template. One especially useful way to use a list is to
578capture all of the positional arguments together if there may be more than one
579specified. In the case of a linker, for example, the linker takes several
580'<tt>.o</tt>' files, and needs to capture them into a list. This is naturally
581specified as:<p>
Chris Lattner3e5fe172002-04-13 18:35:59 +0000[diff] [blame]582
583<pre>
584...
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]585cl::list&lt;std::string&gt; InputFilenames(cl::Positional, cl::desc("&lt;Input files&gt;"), cl::OneOrMore);
Chris Lattner3e5fe172002-04-13 18:35:59 +0000[diff] [blame]586...
587</pre><p>
588
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]589This variable works just like a "<tt>vector&lt;string&gt;</tt>" object. As
590such, accessing the list is simple, just like above. In this example, we used
591the <tt>cl::OneOrMore</tt> modifier to inform the CommandLine library that it is
592an error if the user does not specify any <tt>.o</tt> files on our command line.
593Again, this just reduces the amount of checking we have to do.<p>
Chris Lattner3e5fe172002-04-13 18:35:59 +0000[diff] [blame]594
Chris Lattner3e5fe172002-04-13 18:35:59 +0000[diff] [blame]595
596
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]597<!-- *********************************************************************** -->
598</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>
599<a name="referenceguide">Reference Guide
600</b></font></td></tr></table><ul>
601<!-- *********************************************************************** -->
602
603Reference Guide: TODO
604
605
606<!-- *********************************************************************** -->
607</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>
608<a name="extensionguide">Extension Guide
609</b></font></td></tr></table><ul>
610<!-- *********************************************************************** -->
611
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]612
Chris Lattner3e5fe172002-04-13 18:35:59 +0000[diff] [blame]613Look at the examples classes provided. This section is a TODO.
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]614
615
616
617<!-- *********************************************************************** -->
618</ul>
619<!-- *********************************************************************** -->
620
621<hr>
622<font size=-1>
623<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
624<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
625<!-- hhmts start -->
Chris Lattnerae853632002-07-25 19:27:01 +0000[diff] [blame]626Last modified: Thu Jul 25 14:25:50 CDT 2002
Chris Lattner209c7f42001-07-23 23:03:12 +0000[diff] [blame]627<!-- hhmts end -->
628</font>
629</body></html>