Blame - docs/CommandLine.html - fp2-dev/platform/external/llvm

blob: 7fcd66caf142e33a7d9b1b5e6c6a931d0e371bd9 [file] [log] [blame]

Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
				2	"http://www.w3.org/TR/html4/strict.dtd">
				3	<html>
				4	<head>
				5	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
				6	<title>CommandLine 2.0 Library Manual</title>
				7	<link rel="stylesheet" href="llvm.css" type="text/css">
				8	</head>
				9	<body>
				10
				11	<div class="doc_title">
				12	CommandLine 2.0 Library Manual
				13	</div>
				14
				15	<ol>
				16	<li><a href="#introduction">Introduction</a></li>
				17
				18	<li><a href="#quickstart">Quick Start Guide</a>
				19	<ol>
				20	<li><a href="#bool">Boolean Arguments</a></li>
				21	<li><a href="#alias">Argument Aliases</a></li>
				22	<li><a href="#onealternative">Selecting an alternative from a
				23	set of possibilities</a></li>
				24	<li><a href="#namedalternatives">Named alternatives</a></li>
				25	<li><a href="#list">Parsing a list of options</a></li>
				26	<li><a href="#bits">Collecting options as a set of flags</a></li>
				27	<li><a href="#description">Adding freeform text to help output</a></li>
				28	</ol></li>
				29
				30	<li><a href="#referenceguide">Reference Guide</a>
				31	<ol>
				32	<li><a href="#positional">Positional Arguments</a>
				33	<ul>
				34	<li><a href="#--">Specifying positional options with hyphens</a></li>
				35	<li><a href="#getPosition">Determining absolute position with
				36	getPosition</a></li>
				37	<li><a href="#cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt>
				38	modifier</a></li>
				39	</ul></li>
				40
				41	<li><a href="#storage">Internal vs External Storage</a></li>
				42
				43	<li><a href="#attributes">Option Attributes</a></li>
				44
				45	<li><a href="#modifiers">Option Modifiers</a>
				46	<ul>
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	47	<li><a href="#hiding">Hiding an option from <tt>--help</tt>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	48	output</a></li>
				49	<li><a href="#numoccurrences">Controlling the number of occurrences
				50	required and allowed</a></li>
				51	<li><a href="#valrequired">Controlling whether or not a value must be
				52	specified</a></li>
				53	<li><a href="#formatting">Controlling other formatting options</a></li>
				54	<li><a href="#misc">Miscellaneous option modifiers</a></li>
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	55	<li><a href="#response">Response files</a></li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	56	</ul></li>
				57
				58	<li><a href="#toplevel">Top-Level Classes and Functions</a>
				59	<ul>
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	60	<li><a href="#cl::ParseCommandLineOptions">The
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	61	<tt>cl::ParseCommandLineOptions</tt> function</a></li>
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	62	<li><a href="#cl::ParseEnvironmentOptions">The
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	63	<tt>cl::ParseEnvironmentOptions</tt> function</a></li>
Chris Lattner	7b14b98	2007-12-19 19:48:49 +0000	[diff] [blame]	64	<li><a href="#cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	65	function</a></li>
				66	<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
				67	<li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
				68	<li><a href="#cl::bits">The <tt>cl::bits</tt> class</a></li>
				69	<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
				70	<li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
				71	</ul></li>
				72
				73	<li><a href="#builtinparsers">Builtin parsers</a>
				74	<ul>
				75	<li><a href="#genericparser">The Generic <tt>parser<t></tt>
				76	parser</a></li>
				77	<li><a href="#boolparser">The <tt>parser<bool></tt>
				78	specialization</a></li>
				79	<li><a href="#boolOrDefaultparser">The <tt>parser<boolOrDefault></tt>
				80	specialization</a></li>
				81	<li><a href="#stringparser">The <tt>parser<string></tt>
				82	specialization</a></li>
				83	<li><a href="#intparser">The <tt>parser<int></tt>
				84	specialization</a></li>
				85	<li><a href="#doubleparser">The <tt>parser<double></tt> and
				86	<tt>parser<float></tt> specializations</a></li>
				87	</ul></li>
				88	</ol></li>
				89	<li><a href="#extensionguide">Extension Guide</a>
				90	<ol>
				91	<li><a href="#customparser">Writing a custom parser</a></li>
				92	<li><a href="#explotingexternal">Exploiting external storage</a></li>
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	93	<li><a href="#dynamicopts">Dynamically adding command line
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	94	options</a></li>
				95	</ol></li>
				96	</ol>
				97
				98	<div class="doc_author">
				99	<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
				100	</div>
				101
				102	<!-- *********************************************************************** -->
				103	<div class="doc_section">
				104	<a name="introduction">Introduction</a>
				105	</div>
				106	<!-- *********************************************************************** -->
				107
				108	<div class="doc_text">
				109
				110	<p>This document describes the CommandLine argument processing library. It will
				111	show you how to use it, and what it can do. The CommandLine library uses a
				112	declarative approach to specifying the command line options that your program
				113	takes. By default, these options declarations implicitly hold the value parsed
				114	for the option declared (of course this <a href="#storage">can be
				115	changed</a>).</p>
				116
				117	<p>Although there are a <b>lot</b> of command line argument parsing libraries
				118	out there in many different languages, none of them fit well with what I needed.
				119	By looking at the features and problems of other libraries, I designed the
				120	CommandLine library to have the following features:</p>
				121
				122	<ol>
				123	<li>Speed: The CommandLine library is very quick and uses little resources. The
				124	parsing time of the library is directly proportional to the number of arguments
				125	parsed, not the the number of options recognized. Additionally, command line
				126	argument values are captured transparently into user defined global variables,
				127	which can be accessed like any other variable (and with the same
				128	performance).</li>
				129
				130	<li>Type Safe: As a user of CommandLine, you don't have to worry about
				131	remembering the type of arguments that you want (is it an int? a string? a
				132	bool? an enum?) and keep casting it around. Not only does this help prevent
				133	error prone constructs, it also leads to dramatically cleaner source code.</li>
				134
				135	<li>No subclasses required: To use CommandLine, you instantiate variables that
				136	correspond to the arguments that you would like to capture, you don't subclass a
				137	parser. This means that you don't have to write <b>any</b> boilerplate
				138	code.</li>
				139
				140	<li>Globally accessible: Libraries can specify command line arguments that are
				141	automatically enabled in any tool that links to the library. This is possible
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	142	because the application doesn't have to keep a list of arguments to pass to
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	143	the parser. This also makes supporting <a href="#dynamicopts">dynamically
				144	loaded options</a> trivial.</li>
				145
				146	<li>Cleaner: CommandLine supports enum and other types directly, meaning that
				147	there is less error and more security built into the library. You don't have to
				148	worry about whether your integral command line argument accidentally got
				149	assigned a value that is not valid for your enum type.</li>
				150
				151	<li>Powerful: The CommandLine library supports many different types of
				152	arguments, from simple <a href="#boolparser">boolean flags</a> to <a
				153	href="#cl::opt">scalars arguments</a> (<a href="#stringparser">strings</a>, <a
				154	href="#intparser">integers</a>, <a href="#genericparser">enums</a>, <a
				155	href="#doubleparser">doubles</a>), to <a href="#cl::list">lists of
				156	arguments</a>. This is possible because CommandLine is...</li>
				157
				158	<li>Extensible: It is very simple to add a new argument type to CommandLine.
				159	Simply specify the parser that you want to use with the command line option when
				160	you declare it. <a href="#customparser">Custom parsers</a> are no problem.</li>
				161
				162	<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
				163	that you, the user, have to do. For example, it automatically provides a
				164	<tt>--help</tt> option that shows the available command line options for your
				165	tool. Additionally, it does most of the basic correctness checking for
				166	you.</li>
				167
				168	<li>Capable: The CommandLine library can handle lots of different forms of
				169	options often found in real programs. For example, <a
				170	href="#positional">positional</a> arguments, <tt>ls</tt> style <a
				171	href="#cl::Grouping">grouping</a> options (to allow processing '<tt>ls
				172	-lad</tt>' naturally), <tt>ld</tt> style <a href="#cl::Prefix">prefix</a>
				173	options (to parse '<tt>-lmalloc -L/usr/lib</tt>'), and <a
				174	href="#cl::ConsumeAfter">interpreter style options</a>.</li>
				175
				176	</ol>
				177
				178	<p>This document will hopefully let you jump in and start using CommandLine in
				179	your utility quickly and painlessly. Additionally it should be a simple
				180	reference manual to figure out how stuff works. If it is failing in some area
				181	(or you want an extension to the library), nag the author, <a
				182	href="mailto:sabre@nondot.org">Chris Lattner</a>.</p>
				183
				184	</div>
				185
				186	<!-- *********************************************************************** -->
				187	<div class="doc_section">
				188	<a name="quickstart">Quick Start Guide</a>
				189	</div>
				190	<!-- *********************************************************************** -->
				191
				192	<div class="doc_text">
				193
				194	<p>This section of the manual runs through a simple CommandLine'ification of a
				195	basic compiler tool. This is intended to show you how to jump into using the
				196	CommandLine library in your own program, and show you some of the cool things it
				197	can do.</p>
				198
				199	<p>To start out, you need to include the CommandLine header file into your
				200	program:</p>
				201
				202	<div class="doc_code"><pre>
				203	#include "llvm/Support/CommandLine.h"
				204	</pre></div>
				205
				206	<p>Additionally, you need to add this as the first line of your main
				207	program:</p>
				208
				209	<div class="doc_code"><pre>
				210	int main(int argc, char **argv) {
				211	<a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv);
				212	...
				213	}
				214	</pre></div>
				215
				216	<p>... which actually parses the arguments and fills in the variable
				217	declarations.</p>
				218
				219	<p>Now that you are ready to support command line arguments, we need to tell the
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	220	system which ones we want, and what type of arguments they are. The CommandLine
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	221	library uses a declarative syntax to model command line arguments with the
				222	global variable declarations that capture the parsed values. This means that
				223	for every command line option that you would like to support, there should be a
				224	global variable declaration to capture the result. For example, in a compiler,
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	225	we would like to support the Unix-standard '<tt>-o <filename></tt>' option
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	226	to specify where to put the output. With the CommandLine library, this is
				227	represented like this:</p>
				228
				229	<a name="value_desc_example"></a>
				230	<div class="doc_code"><pre>
				231	<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>"));
				232	</pre></div>
				233
				234	<p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
				235	capture the result of the "<tt>o</tt>" argument (first parameter). We specify
				236	that this is a simple scalar option by using the "<tt><a
				237	href="#cl::opt">cl::opt</a></tt>" template (as opposed to the <a
				238	href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
				239	that the data type that we are parsing is a string.</p>
				240
				241	<p>The second and third parameters (which are optional) are used to specify what
				242	to output for the "<tt>--help</tt>" option. In this case, we get a line that
				243	looks like this:</p>
				244
				245	<div class="doc_code"><pre>
				246	USAGE: compiler [options]
				247
				248	OPTIONS:
				249	-help - display available options (--help-hidden for more)
				250	<b>-o <filename> - Specify output filename</b>
				251	</pre></div>
				252
				253	<p>Because we specified that the command line option should parse using the
				254	<tt>string</tt> data type, the variable declared is automatically usable as a
				255	real string in all contexts that a normal C++ string object may be used. For
				256	example:</p>
				257
				258	<div class="doc_code"><pre>
				259	...
Chris Lattner	b917bc9	2008-03-30 16:59:21 +0000	[diff] [blame]	260	std::ofstream Output(OutputFilename.c_str());
				261	if (Output.good()) ...
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	262	...
				263	</pre></div>
				264
				265	<p>There are many different options that you can use to customize the command
				266	line option handling library, but the above example shows the general interface
				267	to these options. The options can be specified in any order, and are specified
				268	with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so
				269	there are no positional dependencies to remember. The available options are
				270	discussed in detail in the <a href="#referenceguide">Reference Guide</a>.</p>
				271
				272	<p>Continuing the example, we would like to have our compiler take an input
				273	filename as well as an output filename, but we do not want the input filename to
				274	be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
				275	style of argument, the CommandLine library allows for <a
				276	href="#positional">positional</a> arguments to be specified for the program.
				277	These positional arguments are filled with command line parameters that are not
				278	in option form. We use this feature like this:</p>
				279
				280	<div class="doc_code"><pre>
				281	<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>"));
				282	</pre></div>
				283
				284	<p>This declaration indicates that the first positional argument should be
				285	treated as the input filename. Here we use the <tt><a
				286	href="#cl::init">cl::init</a></tt> option to specify an initial value for the
				287	command line option, which is used if the option is not specified (if you do not
				288	specify a <tt><a href="#cl::init">cl::init</a></tt> modifier for an option, then
				289	the default constructor for the data type is used to initialize the value).
				290	Command line options default to being optional, so if we would like to require
				291	that the user always specify an input filename, we would add the <tt><a
				292	href="#cl::Required">cl::Required</a></tt> flag, and we could eliminate the
				293	<tt><a href="#cl::init">cl::init</a></tt> modifier, like this:</p>
				294
				295	<div class="doc_code"><pre>
				296	<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>);
				297	</pre></div>
				298
				299	<p>Again, the CommandLine library does not require the options to be specified
				300	in any particular order, so the above declaration is equivalent to:</p>
				301
				302	<div class="doc_code"><pre>
				303	<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>"));
				304	</pre></div>
				305
				306	<p>By simply adding the <tt><a href="#cl::Required">cl::Required</a></tt> flag,
				307	the CommandLine library will automatically issue an error if the argument is not
				308	specified, which shifts all of the command line option verification code out of
				309	your application into the library. This is just one example of how using flags
				310	can alter the default behaviour of the library, on a per-option basis. By
				311	adding one of the declarations above, the <tt>--help</tt> option synopsis is now
				312	extended to:</p>
				313
				314	<div class="doc_code"><pre>
				315	USAGE: compiler [options] <b><input file></b>
				316
				317	OPTIONS:
				318	-help - display available options (--help-hidden for more)
				319	-o <filename> - Specify output filename
				320	</pre></div>
				321
				322	<p>... indicating that an input filename is expected.</p>
				323
				324	</div>
				325
				326	<!-- ======================================================================= -->
				327	<div class="doc_subsection">
				328	<a name="bool">Boolean Arguments</a>
				329	</div>
				330
				331	<div class="doc_text">
				332
				333	<p>In addition to input and output filenames, we would like the compiler example
				334	to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
				335	file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
				336	compatibility with some of our users. We can support these by declaring options
				337	of boolean type like this:</p>
				338
				339	<div class="doc_code"><pre>
				340	<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
				341	<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>"));
				342	<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>);
				343	</pre></div>
				344
				345	<p>This does what you would expect: it declares three boolean variables
				346	("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
				347	options. Note that the "<tt>-q</tt>" option is specified with the "<a
				348	href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it
				349	from being shown by the standard "<tt>--help</tt>" output (note that it is still
				350	shown in the "<tt>--help-hidden</tt>" output).</p>
				351
				352	<p>The CommandLine library uses a <a href="#builtinparsers">different parser</a>
				353	for different data types. For example, in the string case, the argument passed
				354	to the option is copied literally into the content of the string variable... we
				355	obviously cannot do that in the boolean case, however, so we must use a smarter
				356	parser. In the case of the boolean parser, it allows no options (in which case
				357	it assigns the value of true to the variable), or it allows the values
				358	"<tt>true</tt>" or "<tt>false</tt>" to be specified, allowing any of the
				359	following inputs:</p>
				360
				361	<div class="doc_code"><pre>
				362	compiler -f # No value, 'Force' == true
				363	compiler -f=true # Value specified, 'Force' == true
				364	compiler -f=TRUE # Value specified, 'Force' == true
				365	compiler -f=FALSE # Value specified, 'Force' == false
				366	</pre></div>
				367
				368	<p>... you get the idea. The <a href="#boolparser">bool parser</a> just turns
				369	the string values into boolean values, and rejects things like '<tt>compiler
				370	-f=foo</tt>'. Similarly, the <a href="#doubleparser">float</a>, <a
				371	href="#doubleparser">double</a>, and <a href="#intparser">int</a> parsers work
				372	like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
				373	library calls to parse the string value into the specified data type.</p>
				374
				375	<p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
				376
				377	<div class="doc_code"><pre>
				378	USAGE: compiler [options] <input file>
				379
				380	OPTIONS:
				381	<b>-f - Overwrite output files</b>
				382	-o - Override output filename
				383	<b>-quiet - Don't print informational messages</b>
				384	-help - display available options (--help-hidden for more)
				385	</pre></div>
				386
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	387	<p>and "<tt>compiler --help-hidden</tt>" prints this:</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	388
				389	<div class="doc_code"><pre>
				390	USAGE: compiler [options] <input file>
				391
				392	OPTIONS:
				393	-f - Overwrite output files
				394	-o - Override output filename
				395	<b>-q - Don't print informational messages</b>
				396	-quiet - Don't print informational messages
				397	-help - display available options (--help-hidden for more)
				398	</pre></div>
				399
				400	<p>This brief example has shown you how to use the '<tt><a
				401	href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line
				402	arguments. In addition to simple scalar arguments, the CommandLine library also
				403	provides primitives to support CommandLine option <a href="#alias">aliases</a>,
				404	and <a href="#list">lists</a> of options.</p>
				405
				406	</div>
				407
				408	<!-- ======================================================================= -->
				409	<div class="doc_subsection">
				410	<a name="alias">Argument Aliases</a>
				411	</div>
				412
				413	<div class="doc_text">
				414
				415	<p>So far, the example works well, except for the fact that we need to check the
				416	quiet condition like this now:</p>
				417
				418	<div class="doc_code"><pre>
				419	...
				420	if (!Quiet && !Quiet2) printInformationalMessage(...);
				421	...
				422	</pre></div>
				423
				424	<p>... which is a real pain! Instead of defining two values for the same
				425	condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
				426	option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
				427	a value itself:</p>
				428
				429	<div class="doc_code"><pre>
				430	<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
				431	<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>"));
				432	<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));
				433	</pre></div>
				434
				435	<p>The third line (which is the only one we modified from above) defines a
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	436	"<tt>-q</tt>" alias that updates the "<tt>Quiet</tt>" variable (as specified by
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	437	the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is
				438	specified. Because aliases do not hold state, the only thing the program has to
				439	query is the <tt>Quiet</tt> variable now. Another nice feature of aliases is
				440	that they automatically hide themselves from the <tt>-help</tt> output
				441	(although, again, they are still visible in the <tt>--help-hidden
				442	output</tt>).</p>
				443
				444	<p>Now the application code can simply use:</p>
				445
				446	<div class="doc_code"><pre>
				447	...
				448	if (!Quiet) printInformationalMessage(...);
				449	...
				450	</pre></div>
				451
				452	<p>... which is much nicer! The "<tt><a href="#cl::alias">cl::alias</a></tt>"
				453	can be used to specify an alternative name for any variable type, and has many
				454	uses.</p>
				455
				456	</div>
				457
				458	<!-- ======================================================================= -->
				459	<div class="doc_subsection">
				460	<a name="onealternative">Selecting an alternative from a set of
				461	possibilities</a>
				462	</div>
				463
				464	<div class="doc_text">
				465
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	466	<p>So far we have seen how the CommandLine library handles builtin types like
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	467	<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
				468	things it doesn't know about, like enums or '<tt>int*</tt>'s?</p>
				469
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	470	<p>The answer is that it uses a table-driven generic parser (unless you specify
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	471	your own parser, as described in the <a href="#extensionguide">Extension
				472	Guide</a>). This parser maps literal strings to whatever type is required, and
				473	requires you to tell it what this mapping should be.</p>
				474
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	475	<p>Let's say that we would like to add four optimization levels to our
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	476	optimizer, using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>",
				477	"<tt>-O1</tt>", and "<tt>-O2</tt>". We could easily implement this with boolean
				478	options like above, but there are several problems with this strategy:</p>
				479
				480	<ol>
				481	<li>A user could specify more than one of the options at a time, for example,
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	482	"<tt>compiler -O3 -O2</tt>". The CommandLine library would not be able to
				483	catch this erroneous input for us.</li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	484
				485	<li>We would have to test 4 different variables to see which ones are set.</li>
				486
				487	<li>This doesn't map to the numeric levels that we want... so we cannot easily
				488	see if some level >= "<tt>-O1</tt>" is enabled.</li>
				489
				490	</ol>
				491
				492	<p>To cope with these problems, we can use an enum value, and have the
				493	CommandLine library fill it in with the appropriate level directly, which is
				494	used like this:</p>
				495
				496	<div class="doc_code"><pre>
				497	enum OptLevel {
				498	g, O1, O2, O3
				499	};
				500
				501	<a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
				502	<a href="#cl::values">cl::values</a>(
				503	clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
				504	clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
				505	clEnumVal(O2, "<i>Enable default optimizations</i>"),
				506	clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
				507	clEnumValEnd));
				508
				509	...
				510	if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
				511	...
				512	</pre></div>
				513
				514	<p>This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
				515	"<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
				516	that are listed in the declaration (Note that the declaration list must be
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	517	terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	518	library enforces
				519	that the user can only specify one of the options, and it ensure that only valid
				520	enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
				521	command line arguments matched the enum values. With this option added, our
				522	help output now is:</p>
				523
				524	<div class="doc_code"><pre>
				525	USAGE: compiler [options] <input file>
				526
				527	OPTIONS:
				528	<b>Choose optimization level:
				529	-g - No optimizations, enable debugging
				530	-O1 - Enable trivial optimizations
				531	-O2 - Enable default optimizations
				532	-O3 - Enable expensive optimizations</b>
				533	-f - Overwrite output files
				534	-help - display available options (--help-hidden for more)
				535	-o <filename> - Specify output filename
				536	-quiet - Don't print informational messages
				537	</pre></div>
				538
				539	<p>In this case, it is sort of awkward that flag names correspond directly to
				540	enum names, because we probably don't want a enum definition named "<tt>g</tt>"
				541	in our program. Because of this, we can alternatively write this example like
				542	this:</p>
				543
				544	<div class="doc_code"><pre>
				545	enum OptLevel {
				546	Debug, O1, O2, O3
				547	};
				548
				549	<a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
				550	<a href="#cl::values">cl::values</a>(
				551	clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
				552	clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
				553	clEnumVal(O2 , "<i>Enable default optimizations</i>"),
				554	clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
				555	clEnumValEnd));
				556
				557	...
				558	if (OptimizationLevel == Debug) outputDebugInfo(...);
				559	...
				560	</pre></div>
				561
				562	<p>By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we
				563	can directly specify the name that the flag should get. In general a direct
				564	mapping is nice, but sometimes you can't or don't want to preserve the mapping,
				565	which is when you would use it.</p>
				566
				567	</div>
				568
				569	<!-- ======================================================================= -->
				570	<div class="doc_subsection">
				571	<a name="namedalternatives">Named Alternatives</a>
				572	</div>
				573
				574	<div class="doc_text">
				575
				576	<p>Another useful argument form is a named alternative style. We shall use this
				577	style in our compiler to specify different debug levels that can be used.
				578	Instead of each debug level being its own switch, we want to support the
				579	following options, of which only one can be specified at a time:
				580	"<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
				581	"<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
				582	our optimization level flags, but we also specify an option name. For this
				583	case, the code looks like this:</p>
				584
				585	<div class="doc_code"><pre>
				586	enum DebugLev {
				587	nodebuginfo, quick, detailed
				588	};
				589
				590	// Enable Debug Options to be specified on the command line
				591	<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>"),
				592	<a href="#cl::values">cl::values</a>(
				593	clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
				594	clEnumVal(quick, "<i>enable quick debug information</i>"),
				595	clEnumVal(detailed, "<i>enable detailed debug information</i>"),
				596	clEnumValEnd));
				597	</pre></div>
				598
				599	<p>This definition defines an enumerated command line variable of type "<tt>enum
				600	DebugLev</tt>", which works exactly the same way as before. The difference here
				601	is just the interface exposed to the user of your program and the help output by
				602	the "<tt>--help</tt>" option:</p>
				603
				604	<div class="doc_code"><pre>
				605	USAGE: compiler [options] <input file>
				606
				607	OPTIONS:
				608	Choose optimization level:
				609	-g - No optimizations, enable debugging
				610	-O1 - Enable trivial optimizations
				611	-O2 - Enable default optimizations
				612	-O3 - Enable expensive optimizations
				613	<b>-debug_level - Set the debugging level:
				614	=none - disable debug information
				615	=quick - enable quick debug information
				616	=detailed - enable detailed debug information</b>
				617	-f - Overwrite output files
				618	-help - display available options (--help-hidden for more)
				619	-o <filename> - Specify output filename
				620	-quiet - Don't print informational messages
				621	</pre></div>
				622
				623	<p>Again, the only structural difference between the debug level declaration and
				624	the optimization level declaration is that the debug level declaration includes
				625	an option name (<tt>"debug_level"</tt>), which automatically changes how the
				626	library processes the argument. The CommandLine library supports both forms so
				627	that you can choose the form most appropriate for your application.</p>
				628
				629	</div>
				630
				631	<!-- ======================================================================= -->
				632	<div class="doc_subsection">
				633	<a name="list">Parsing a list of options</a>
				634	</div>
				635
				636	<div class="doc_text">
				637
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	638	<p>Now that we have the standard run-of-the-mill argument types out of the way,
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	639	lets get a little wild and crazy. Lets say that we want our optimizer to accept
				640	a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
				641	might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
				642	this case, the order of the arguments and the number of appearances is very
				643	important. This is what the "<tt><a href="#cl::list">cl::list</a></tt>"
				644	template is for. First, start by defining an enum of the optimizations that you
				645	would like to perform:</p>
				646
				647	<div class="doc_code"><pre>
				648	enum Opts {
				649	// 'inline' is a C++ keyword, so name it 'inlining'
				650	dce, constprop, inlining, strip
				651	};
				652	</pre></div>
				653
				654	<p>Then define your "<tt><a href="#cl::list">cl::list</a></tt>" variable:</p>
				655
				656	<div class="doc_code"><pre>
				657	<a href="#cl::list">cl::list</a><Opts> OptimizationList(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
				658	<a href="#cl::values">cl::values</a>(
				659	clEnumVal(dce , "<i>Dead Code Elimination</i>"),
				660	clEnumVal(constprop , "<i>Constant Propagation</i>"),
				661	clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
				662	clEnumVal(strip , "<i>Strip Symbols</i>"),
				663	clEnumValEnd));
				664	</pre></div>
				665
				666	<p>This defines a variable that is conceptually of the type
				667	"<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
				668	vector methods:</p>
				669
				670	<div class="doc_code"><pre>
				671	for (unsigned i = 0; i != OptimizationList.size(); ++i)
				672	switch (OptimizationList[i])
				673	...
				674	</pre></div>
				675
				676	<p>... to iterate through the list of options specified.</p>
				677
				678	<p>Note that the "<tt><a href="#cl::list">cl::list</a></tt>" template is
				679	completely general and may be used with any data types or other arguments that
				680	you can use with the "<tt><a href="#cl::opt">cl::opt</a></tt>" template. One
				681	especially useful way to use a list is to capture all of the positional
				682	arguments together if there may be more than one specified. In the case of a
				683	linker, for example, the linker takes several '<tt>.o</tt>' files, and needs to
				684	capture them into a list. This is naturally specified as:</p>
				685
				686	<div class="doc_code"><pre>
				687	...
				688	<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>);
				689	...
				690	</pre></div>
				691
				692	<p>This variable works just like a "<tt>vector<string></tt>" object. As
				693	such, accessing the list is simple, just like above. In this example, we used
				694	the <tt><a href="#cl::OneOrMore">cl::OneOrMore</a></tt> modifier to inform the
				695	CommandLine library that it is an error if the user does not specify any
				696	<tt>.o</tt> files on our command line. Again, this just reduces the amount of
				697	checking we have to do.</p>
				698
				699	</div>
				700
				701	<!-- ======================================================================= -->
				702	<div class="doc_subsection">
				703	<a name="bits">Collecting options as a set of flags</a>
				704	</div>
				705
				706	<div class="doc_text">
				707
				708	<p>Instead of collecting sets of options in a list, it is also possible to
				709	gather information for enum values in a <b>bit vector</b>. The represention used by
				710	the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
				711	integer. An enum value is represented by a 0/1 in the enum's ordinal value bit
				712	position. 1 indicating that the enum was specified, 0 otherwise. As each
				713	specified value is parsed, the resulting enum's bit is set in the option's bit
				714	vector:</p>
				715
				716	<div class="doc_code"><pre>
				717	<i>bits</i> \|= 1 << (unsigned)<i>enum</i>;
				718	</pre></div>
				719
				720	<p>Options that are specified multiple times are redundant. Any instances after
				721	the first are discarded.</p>
				722
				723	<p>Reworking the above list example, we could replace <a href="#list">
				724	<tt>cl::list</tt></a> with <a href="#bits"><tt>cl::bits</tt></a>:</p>
				725
				726	<div class="doc_code"><pre>
				727	<a href="#cl::bits">cl::bits</a><Opts> OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
				728	<a href="#cl::values">cl::values</a>(
				729	clEnumVal(dce , "<i>Dead Code Elimination</i>"),
				730	clEnumVal(constprop , "<i>Constant Propagation</i>"),
				731	clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
				732	clEnumVal(strip , "<i>Strip Symbols</i>"),
				733	clEnumValEnd));
				734	</pre></div>
				735
				736	<p>To test to see if <tt>constprop</tt> was specified, we can use the
				737	<tt>cl:bits::isSet</tt> function:</p>
				738
				739	<div class="doc_code"><pre>
				740	if (OptimizationBits.isSet(constprop)) {
				741	...
				742	}
				743	</pre></div>
				744
				745	<p>It's also possible to get the raw bit vector using the
				746	<tt>cl::bits::getBits</tt> function:</p>
				747
				748	<div class="doc_code"><pre>
				749	unsigned bits = OptimizationBits.getBits();
				750	</pre></div>
				751
				752	<p>Finally, if external storage is used, then the location specified must be of
				753	<b>type</b> <tt>unsigned</tt>. In all other ways a <a
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	754	href="#bits"><tt>cl::bits</tt></a> option is equivalent to a <a
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	755	href="#list"> <tt>cl::list</tt></a> option.</p>
				756
				757	</div>
				758
				759
				760	<!-- ======================================================================= -->
				761	<div class="doc_subsection">
				762	<a name="description">Adding freeform text to help output</a>
				763	</div>
				764
				765	<div class="doc_text">
				766
				767	<p>As our program grows and becomes more mature, we may decide to put summary
				768	information about what it does into the help output. The help output is styled
				769	to look similar to a Unix <tt>man</tt> page, providing concise information about
				770	a program. Unix <tt>man</tt> pages, however often have a description about what
				771	the program does. To add this to your CommandLine program, simply pass a third
				772	argument to the <a
				773	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
				774	call in main. This additional argument is then printed as the overview
				775	information for your program, allowing you to include any additional information
				776	that you want. For example:</p>
				777
				778	<div class="doc_code"><pre>
				779	int main(int argc, char **argv) {
				780	<a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv, " CommandLine compiler example\n\n"
				781	" This program blah blah blah...\n");
				782	...
				783	}
				784	</pre></div>
				785
				786	<p>would yield the help output:</p>
				787
				788	<div class="doc_code"><pre>
				789	<b>OVERVIEW: CommandLine compiler example
				790
				791	This program blah blah blah...</b>
				792
				793	USAGE: compiler [options] <input file>
				794
				795	OPTIONS:
				796	...
				797	-help - display available options (--help-hidden for more)
				798	-o <filename> - Specify output filename
				799	</pre></div>
				800
				801	</div>
				802
				803
				804	<!-- *********************************************************************** -->
				805	<div class="doc_section">
				806	<a name="referenceguide">Reference Guide</a>
				807	</div>
				808	<!-- *********************************************************************** -->
				809
				810	<div class="doc_text">
				811
				812	<p>Now that you know the basics of how to use the CommandLine library, this
				813	section will give you the detailed information you need to tune how command line
				814	options work, as well as information on more "advanced" command line option
				815	processing capabilities.</p>
				816
				817	</div>
				818
				819	<!-- ======================================================================= -->
				820	<div class="doc_subsection">
				821	<a name="positional">Positional Arguments</a>
				822	</div>
				823
				824	<div class="doc_text">
				825
				826	<p>Positional arguments are those arguments that are not named, and are not
				827	specified with a hyphen. Positional arguments should be used when an option is
				828	specified by its position alone. For example, the standard Unix <tt>grep</tt>
				829	tool takes a regular expression argument, and an optional filename to search
				830	through (which defaults to standard input if a filename is not specified).
				831	Using the CommandLine library, this would be specified as:</p>
				832
				833	<div class="doc_code"><pre>
				834	<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>);
				835	<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>"));
				836	</pre></div>
				837
				838	<p>Given these two option declarations, the <tt>--help</tt> output for our grep
				839	replacement would look like this:</p>
				840
				841	<div class="doc_code"><pre>
				842	USAGE: spiffygrep [options] <b><regular expression> <input file></b>
				843
				844	OPTIONS:
				845	-help - display available options (--help-hidden for more)
				846	</pre></div>
				847
				848	<p>... and the resultant program could be used just like the standard
				849	<tt>grep</tt> tool.</p>
				850
				851	<p>Positional arguments are sorted by their order of construction. This means
				852	that command line options will be ordered according to how they are listed in a
				853	.cpp file, but will not have an ordering defined if the positional arguments
				854	are defined in multiple .cpp files. The fix for this problem is simply to
				855	define all of your positional arguments in one .cpp file.</p>
				856
				857	</div>
				858
				859
				860	<!-- _______________________________________________________________________ -->
				861	<div class="doc_subsubsection">
				862	<a name="--">Specifying positional options with hyphens</a>
				863	</div>
				864
				865	<div class="doc_text">
				866
				867	<p>Sometimes you may want to specify a value to your positional argument that
				868	starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
				869	first, you will have trouble doing this, because it will try to find an argument
				870	named '<tt>-foo</tt>', and will fail (and single quotes will not save you).
				871	Note that the system <tt>grep</tt> has the same problem:</p>
				872
				873	<div class="doc_code"><pre>
				874	$ spiffygrep '-foo' test.txt
				875	Unknown command line argument '-foo'. Try: spiffygrep --help'
				876
				877	$ grep '-foo' test.txt
				878	grep: illegal option -- f
				879	grep: illegal option -- o
				880	grep: illegal option -- o
				881	Usage: grep -hblcnsviw pattern file . . .
				882	</pre></div>
				883
				884	<p>The solution for this problem is the same for both your tool and the system
				885	version: use the '<tt>--</tt>' marker. When the user specifies '<tt>--</tt>' on
				886	the command line, it is telling the program that all options after the
				887	'<tt>--</tt>' should be treated as positional arguments, not options. Thus, we
				888	can use it like this:</p>
				889
				890	<div class="doc_code"><pre>
				891	$ spiffygrep -- -foo test.txt
				892	...output...
				893	</pre></div>
				894
				895	</div>
				896
				897	<!-- _______________________________________________________________________ -->
				898	<div class="doc_subsubsection">
				899	<a name="getPosition">Determining absolute position with getPosition()</a>
				900	</div>
				901	<div class="doc_text">
				902	<p>Sometimes an option can affect or modify the meaning of another option. For
				903	example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
				904	<tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
				905	the file to be interpreted as if it contained source code in language
Chris Lattner	6604139	2008-04-01 18:02:36 +0000	[diff] [blame]	906	<tt>LANG</tt>. In order to handle this properly, you need to know the
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	907	absolute position of each argument, especially those in lists, so their
				908	interaction(s) can be applied correctly. This is also useful for options like
				909	<tt>-llibname</tt> which is actually a positional argument that starts with
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	910	a dash.</p>
				911	<p>So, generally, the problem is that you have two <tt>cl::list</tt> variables
				912	that interact in some way. To ensure the correct interaction, you can use the
				913	<tt>cl::list::getPosition(optnum)</tt> method. This method returns the
				914	absolute position (as found on the command line) of the <tt>optnum</tt>
				915	item in the <tt>cl::list</tt>.</p>
				916	<p>The idiom for usage is like this:</p>
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	917
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	918	<div class="doc_code"><pre>
				919	static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	920	static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	921
				922	int main(int argc, char**argv) {
				923	// ...
				924	std::vector<std::string>::iterator fileIt = Files.begin();
				925	std::vector<std::string>::iterator libIt = Libraries.begin();
				926	unsigned libPos = 0, filePos = 0;
				927	while ( 1 ) {
				928	if ( libIt != Libraries.end() )
				929	libPos = Libraries.getPosition( libIt - Libraries.begin() );
				930	else
				931	libPos = 0;
				932	if ( fileIt != Files.end() )
				933	filePos = Files.getPosition( fileIt - Files.begin() );
				934	else
				935	filePos = 0;
				936
				937	if ( filePos != 0 && (libPos == 0 \|\| filePos < libPos) ) {
				938	// Source File Is next
				939	++fileIt;
				940	}
				941	else if ( libPos != 0 && (filePos == 0 \|\| libPos < filePos) ) {
				942	// Library is next
				943	++libIt;
				944	}
				945	else
				946	break; // we're done with the list
				947	}
				948	}</pre></div>
				949
				950	<p>Note that, for compatibility reasons, the <tt>cl::opt</tt> also supports an
				951	<tt>unsigned getPosition()</tt> option that will provide the absolute position
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	952	of that option. You can apply the same approach as above with a
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	953	<tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
				954	</div>
				955
				956	<!-- _______________________________________________________________________ -->
				957	<div class="doc_subsubsection">
				958	<a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
				959	</div>
				960
				961	<div class="doc_text">
				962
				963	<p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
				964	used to construct programs that use "interpreter style" option processing. With
				965	this style of option processing, all arguments specified after the last
				966	positional argument are treated as special interpreter arguments that are not
				967	interpreted by the command line argument.</p>
				968
				969	<p>As a concrete example, lets say we are developing a replacement for the
				970	standard Unix Bourne shell (<tt>/bin/sh</tt>). To run <tt>/bin/sh</tt>, first
				971	you specify options to the shell itself (like <tt>-x</tt> which turns on trace
				972	output), then you specify the name of the script to run, then you specify
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	973	arguments to the script. These arguments to the script are parsed by the Bourne
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	974	shell command line option processor, but are not interpreted as options to the
				975	shell itself. Using the CommandLine library, we would specify this as:</p>
				976
				977	<div class="doc_code"><pre>
				978	<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>("-"));
				979	<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>"));
				980	<a href="#cl::opt">cl::opt</a><bool> Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
				981	</pre></div>
				982
				983	<p>which automatically provides the help output:</p>
				984
				985	<div class="doc_code"><pre>
				986	USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
				987
				988	OPTIONS:
				989	-help - display available options (--help-hidden for more)
				990	<b>-x - Enable trace output</b>
				991	</pre></div>
				992
				993	<p>At runtime, if we run our new shell replacement as `<tt>spiffysh -x test.sh
				994	-a -x -y bar</tt>', the <tt>Trace</tt> variable will be set to true, the
				995	<tt>Script</tt> variable will be set to "<tt>test.sh</tt>", and the
				996	<tt>Argv</tt> list will contain <tt>["-a", "-x", "-y", "bar"]</tt>, because they
				997	were specified after the last positional argument (which is the script
				998	name).</p>
				999
				1000	<p>There are several limitations to when <tt>cl::ConsumeAfter</tt> options can
				1001	be specified. For example, only one <tt>cl::ConsumeAfter</tt> can be specified
				1002	per program, there must be at least one <a href="#positional">positional
				1003	argument</a> specified, there must not be any <a href="#cl::list">cl::list</a>
				1004	positional arguments, and the <tt>cl::ConsumeAfter</tt> option should be a <a
				1005	href="#cl::list">cl::list</a> option.</p>
				1006
				1007	</div>
				1008
				1009	<!-- ======================================================================= -->
				1010	<div class="doc_subsection">
				1011	<a name="storage">Internal vs External Storage</a>
				1012	</div>
				1013
				1014	<div class="doc_text">
				1015
				1016	<p>By default, all command line options automatically hold the value that they
				1017	parse from the command line. This is very convenient in the common case,
				1018	especially when combined with the ability to define command line options in the
				1019	files that use them. This is called the internal storage model.</p>
				1020
				1021	<p>Sometimes, however, it is nice to separate the command line option processing
				1022	code from the storage of the value parsed. For example, lets say that we have a
				1023	'<tt>-debug</tt>' option that we would like to use to enable debug information
				1024	across the entire body of our program. In this case, the boolean value
				1025	controlling the debug code should be globally accessable (in a header file, for
				1026	example) yet the command line option processing code should not be exposed to
				1027	all of these clients (requiring lots of .cpp files to #include
				1028	<tt>CommandLine.h</tt>).</p>
				1029
				1030	<p>To do this, set up your .h file with your option, like this for example:</p>
				1031
				1032	<div class="doc_code">
				1033	<pre>
				1034	<i>// DebugFlag.h - Get access to the '-debug' command line option
				1035	//
				1036
				1037	// DebugFlag - This boolean is set to true if the '-debug' command line option
				1038	// is specified. This should probably not be referenced directly, instead, use
				1039	// the DEBUG macro below.
				1040	//</i>
				1041	extern bool DebugFlag;
				1042
				1043	<i>// DEBUG macro - This macro should be used by code to emit debug information.
				1044	// In the '-debug' option is specified on the command line, and if this is a
				1045	// debug build, then the code specified as the option to the macro will be
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1046	// executed. Otherwise it will not be.</i>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1047	<span class="doc_hilite">#ifdef NDEBUG
				1048	#define DEBUG(X)
				1049	#else
				1050	#define DEBUG(X)</span> do { if (DebugFlag) { X; } } while (0)
				1051	<span class="doc_hilite">#endif</span>
				1052	</pre>
				1053	</div>
				1054
				1055	<p>This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
				1056	<tt>DebugFlag</tt> explicitly if they want to. Now we just need to be able to
				1057	set the <tt>DebugFlag</tt> boolean when the option is set. To do this, we pass
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1058	an additional argument to our command line argument processor, and we specify
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1059	where to fill in with the <a href="#cl::location">cl::location</a>
				1060	attribute:</p>
				1061
				1062	<div class="doc_code">
				1063	<pre>
				1064	bool DebugFlag; <i>// the actual value</i>
				1065	static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
				1066	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));
				1067	</pre>
				1068	</div>
				1069
				1070	<p>In the above example, we specify "<tt>true</tt>" as the second argument to
				1071	the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the
				1072	template should not maintain a copy of the value itself. In addition to this,
				1073	we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so
				1074	that <tt>DebugFlag</tt> is automatically set.</p>
				1075
				1076	</div>
				1077
				1078	<!-- ======================================================================= -->
				1079	<div class="doc_subsection">
				1080	<a name="attributes">Option Attributes</a>
				1081	</div>
				1082
				1083	<div class="doc_text">
				1084
				1085	<p>This section describes the basic attributes that you can specify on
				1086	options.</p>
				1087
				1088	<ul>
				1089
				1090	<li>The option name attribute (which is required for all options, except <a
				1091	href="#positional">positional options</a>) specifies what the option name is.
				1092	This option is specified in simple double quotes:
				1093
				1094	<pre>
				1095	<a href="#cl::opt">cl::opt</a><<b>bool</b>> Quiet("<i>quiet</i>");
				1096	</pre>
				1097
				1098	</li>
				1099
				1100	<li><a name="cl::desc">The <b><tt>cl::desc</tt></b></a> attribute specifies a
				1101	description for the option to be shown in the <tt>--help</tt> output for the
				1102	program.</li>
				1103
				1104	<li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b></a> attribute
				1105	specifies a string that can be used to fine tune the <tt>--help</tt> output for
				1106	a command line option. Look <a href="#value_desc_example">here</a> for an
				1107	example.</li>
				1108
				1109	<li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an
				1110	inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is
				1111	not specified then the command line option value defaults to the value created
				1112	by the default constructor for the type. <b>Warning</b>: If you specify both
				1113	<b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
				1114	you must specify <b><tt>cl::location</tt></b> first, so that when the
				1115	command-line parser sees <b><tt>cl::init</tt></b>, it knows where to put the
				1116	initial value. (You will get an error at runtime if you don't put them in
				1117	the right order.)</li>
				1118
				1119	<li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where to
				1120	store the value for a parsed command line option if using external storage. See
				1121	the section on <a href="#storage">Internal vs External Storage</a> for more
				1122	information.</li>
				1123
				1124	<li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
				1125	specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is
				1126	an alias for.</li>
				1127
				1128	<li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies
				1129	the string-to-value mapping to be used by the generic parser. It takes a
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1130	<b>clEnumValEnd terminated</b> list of (option, value, description) triplets
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1131	that
				1132	specify the option name, the value mapped to, and the description shown in the
				1133	<tt>--help</tt> for the tool. Because the generic parser is used most
				1134	frequently with enum values, two macros are often useful:
				1135
				1136	<ol>
				1137
				1138	<li><a name="clEnumVal">The <b><tt>clEnumVal</tt></b></a> macro is used as a
				1139	nice simple way to specify a triplet for an enum. This macro automatically
				1140	makes the option name be the same as the enum name. The first option to the
				1141	macro is the enum, the second is the description for the command line
				1142	option.</li>
				1143
				1144	<li><a name="clEnumValN">The <b><tt>clEnumValN</tt></b></a> macro is used to
				1145	specify macro options where the option name doesn't equal the enum name. For
				1146	this macro, the first argument is the enum value, the second is the flag name,
				1147	and the second is the description.</li>
				1148
				1149	</ol>
				1150
				1151	You will get a compile time error if you try to use cl::values with a parser
				1152	that does not support it.</li>
				1153
				1154	</ul>
				1155
				1156	</div>
				1157
				1158	<!-- ======================================================================= -->
				1159	<div class="doc_subsection">
				1160	<a name="modifiers">Option Modifiers</a>
				1161	</div>
				1162
				1163	<div class="doc_text">
				1164
				1165	<p>Option modifiers are the flags and expressions that you pass into the
				1166	constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				1167	href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
				1168	tweak how options are parsed and how <tt>--help</tt> output is generated to fit
				1169	your application well.</p>
				1170
				1171	<p>These options fall into five main catagories:</p>
				1172
				1173	<ol>
				1174	<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
				1175	<li><a href="#numoccurrences">Controlling the number of occurrences
				1176	required and allowed</a></li>
				1177	<li><a href="#valrequired">Controlling whether or not a value must be
				1178	specified</a></li>
				1179	<li><a href="#formatting">Controlling other formatting options</a></li>
				1180	<li><a href="#misc">Miscellaneous option modifiers</a></li>
				1181	</ol>
				1182
				1183	<p>It is not possible to specify two options from the same catagory (you'll get
				1184	a runtime error) to a single option, except for options in the miscellaneous
				1185	catagory. The CommandLine library specifies defaults for all of these settings
				1186	that are the most useful in practice and the most common, which mean that you
				1187	usually shouldn't have to worry about these.</p>
				1188
				1189	</div>
				1190
				1191	<!-- _______________________________________________________________________ -->
				1192	<div class="doc_subsubsection">
				1193	<a name="hiding">Hiding an option from <tt>--help</tt> output</a>
				1194	</div>
				1195
				1196	<div class="doc_text">
				1197
				1198	<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
				1199	<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
				1200	appears in the <tt>--help</tt> and <tt>--help-hidden</tt> output for the
				1201	compiled program:</p>
				1202
				1203	<ul>
				1204
				1205	<li><a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b></a> modifier
				1206	(which is the default for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1207	href="#cl::list">cl::list</a></tt> options) indicates the option is to appear
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1208	in both help listings.</li>
				1209
				1210	<li><a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b></a> modifier (which is the
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1211	default for <tt><a href="#cl::alias">cl::alias</a></tt> options) indicates that
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1212	the option should not appear in the <tt>--help</tt> output, but should appear in
				1213	the <tt>--help-hidden</tt> output.</li>
				1214
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1215	<li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1216	indicates that the option should not appear in any help output.</li>
				1217
				1218	</ul>
				1219
				1220	</div>
				1221
				1222	<!-- _______________________________________________________________________ -->
				1223	<div class="doc_subsubsection">
				1224	<a name="numoccurrences">Controlling the number of occurrences required and
				1225	allowed</a>
				1226	</div>
				1227
				1228	<div class="doc_text">
				1229
				1230	<p>This group of options is used to control how many time an option is allowed
				1231	(or required) to be specified on the command line of your program. Specifying a
				1232	value for this setting allows the CommandLine library to do error checking for
				1233	you.</p>
				1234
				1235	<p>The allowed values for this option group are:</p>
				1236
				1237	<ul>
				1238
				1239	<li><a name="cl::Optional">The <b><tt>cl::Optional</tt></b></a> modifier (which
				1240	is the default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				1241	href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will
				1242	allow either zero or one occurrence of the option to be specified.</li>
				1243
				1244	<li><a name="cl::ZeroOrMore">The <b><tt>cl::ZeroOrMore</tt></b></a> modifier
				1245	(which is the default for the <tt><a href="#cl::list">cl::list</a></tt> class)
				1246	indicates that your program will allow the option to be specified zero or more
				1247	times.</li>
				1248
				1249	<li><a name="cl::Required">The <b><tt>cl::Required</tt></b></a> modifier
				1250	indicates that the specified option must be specified exactly one time.</li>
				1251
				1252	<li><a name="cl::OneOrMore">The <b><tt>cl::OneOrMore</tt></b></a> modifier
				1253	indicates that the option must be specified at least one time.</li>
				1254
				1255	<li>The <b><tt>cl::ConsumeAfter</tt></b> modifier is described in the <a
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1256	href="#positional">Positional arguments section</a>.</li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1257
				1258	</ul>
				1259
				1260	<p>If an option is not specified, then the value of the option is equal to the
				1261	value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute. If
				1262	the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the
				1263	option value is initialized with the default constructor for the data type.</p>
				1264
				1265	<p>If an option is specified multiple times for an option of the <tt><a
				1266	href="#cl::opt">cl::opt</a></tt> class, only the last value will be
				1267	retained.</p>
				1268
				1269	</div>
				1270
				1271	<!-- _______________________________________________________________________ -->
				1272	<div class="doc_subsubsection">
				1273	<a name="valrequired">Controlling whether or not a value must be specified</a>
				1274	</div>
				1275
				1276	<div class="doc_text">
				1277
				1278	<p>This group of options is used to control whether or not the option allows a
				1279	value to be present. In the case of the CommandLine library, a value is either
				1280	specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing
				1281	string (e.g. '<tt>-o a.out</tt>').</p>
				1282
				1283	<p>The allowed values for this option group are:</p>
				1284
				1285	<ul>
				1286
				1287	<li><a name="cl::ValueOptional">The <b><tt>cl::ValueOptional</tt></b></a> modifier
				1288	(which is the default for <tt>bool</tt> typed options) specifies that it is
				1289	acceptable to have a value, or not. A boolean argument can be enabled just by
				1290	appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'.
				1291	If an option is specified with this mode, it is illegal for the value to be
				1292	provided without the equal sign. Therefore '<tt>-foo true</tt>' is illegal. To
				1293	get this behavior, you must use the <a
				1294	href="#cl::ValueRequired">cl::ValueRequired</a> modifier.</li>
				1295
				1296	<li><a name="cl::ValueRequired">The <b><tt>cl::ValueRequired</tt></b></a> modifier
				1297	(which is the default for all other types except for <a
				1298	href="#onealternative">unnamed alternatives using the generic parser</a>)
				1299	specifies that a value must be provided. This mode informs the command line
				1300	library that if an option is not provides with an equal sign, that the next
				1301	argument provided must be the value. This allows things like '<tt>-o
				1302	a.out</tt>' to work.</li>
				1303
				1304	<li><a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b></a>
				1305	modifier (which is the default for <a href="#onealternative">unnamed
				1306	alternatives using the generic parser</a>) indicates that it is a runtime error
				1307	for the user to specify a value. This can be provided to disallow users from
				1308	providing options to boolean options (like '<tt>-foo=true</tt>').</li>
				1309
				1310	</ul>
				1311
				1312	<p>In general, the default values for this option group work just like you would
				1313	want them to. As mentioned above, you can specify the <a
				1314	href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean
				1315	argument to restrict your command line parser. These options are mostly useful
				1316	when <a href="#extensionguide">extending the library</a>.</p>
				1317
				1318	</div>
				1319
				1320	<!-- _______________________________________________________________________ -->
				1321	<div class="doc_subsubsection">
				1322	<a name="formatting">Controlling other formatting options</a>
				1323	</div>
				1324
				1325	<div class="doc_text">
				1326
				1327	<p>The formatting option group is used to specify that the command line option
				1328	has special abilities and is otherwise different from other command line
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1329	arguments. As usual, you can only specify one of these arguments at most.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1330
				1331	<ul>
				1332
				1333	<li><a name="cl::NormalFormatting">The <b><tt>cl::NormalFormatting</tt></b></a>
				1334	modifier (which is the default all options) specifies that this option is
				1335	"normal".</li>
				1336
				1337	<li><a name="cl::Positional">The <b><tt>cl::Positional</tt></b></a> modifier
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1338	specifies that this is a positional argument that does not have a command line
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1339	option associated with it. See the <a href="#positional">Positional
				1340	Arguments</a> section for more information.</li>
				1341
				1342	<li>The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier
				1343	specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
				1344
				1345	<li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
				1346	that this option prefixes its value. With 'Prefix' options, the equal sign does
				1347	not separate the value from the option name specified. Instead, the value is
				1348	everything after the prefix, including any equal sign if present. This is useful
				1349	for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
				1350	linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
				1351	'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
				1352	options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
				1353	modifier added to allow the CommandLine library to recognize them. Note that
				1354	<b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
				1355	<b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
				1356	specified.</li>
				1357
				1358	<li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1359	to implement Unix-style tools (like <tt>ls</tt>) that have lots of single letter
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1360	arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
				1361	command actually enables four different options, all of which are single
				1362	letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
				1363	options cannot have values.</li>
				1364
				1365	</ul>
				1366
				1367	<p>The CommandLine library does not restrict how you use the <b><tt><a
				1368	href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
				1369	href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
				1370	specify ambiguous argument settings. Thus, it is possible to have multiple
				1371	letter options that are prefix or grouping options, and they will still work as
				1372	designed.</p>
				1373
				1374	<p>To do this, the CommandLine library uses a greedy algorithm to parse the
				1375	input option into (potentially multiple) prefix and grouping options. The
				1376	strategy basically looks like this:</p>
				1377
				1378	<div class="doc_code"><tt>parse(string OrigInput) {</tt>
				1379
				1380	<ol>
				1381	<li><tt>string input = OrigInput;</tt>
				1382	<li><tt>if (isOption(input)) return getOption(input).parse();</tt>    <i>// Normal option</i>
				1383	<li><tt>while (!isOption(input) && !input.empty()) input.pop_back();</tt>    <i>// Remove the last letter</i>
				1384	<li><tt>if (input.empty()) return error();</tt>    <i>// No matching option</i>
				1385	<li><tt>if (getOption(input).isPrefix())<br>
				1386	return getOption(input).parse(input);</tt>
				1387	<li><tt>while (!input.empty()) {    <i>// Must be grouping options</i><br>
				1388	getOption(input).parse();<br>
				1389	OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());<br>
				1390	input = OrigInput;<br>
				1391	while (!isOption(input) && !input.empty()) input.pop_back();<br>
				1392	}</tt>
				1393	<li><tt>if (!OrigInput.empty()) error();</tt></li>
				1394	</ol>
				1395
				1396	<p><tt>}</tt></p>
				1397	</div>
				1398
				1399	</div>
				1400
				1401	<!-- _______________________________________________________________________ -->
				1402	<div class="doc_subsubsection">
				1403	<a name="misc">Miscellaneous option modifiers</a>
				1404	</div>
				1405
				1406	<div class="doc_text">
				1407
				1408	<p>The miscellaneous option modifiers are the only flags where you can specify
				1409	more than one flag from the set: they are not mutually exclusive. These flags
				1410	specify boolean properties that modify the option.</p>
				1411
				1412	<ul>
				1413
				1414	<li><a name="cl::CommaSeparated">The <b><tt>cl::CommaSeparated</tt></b></a> modifier
				1415	indicates that any commas specified for an option's value should be used to
				1416	split the value up into multiple values for the option. For example, these two
				1417	options are equivalent when <tt>cl::CommaSeparated</tt> is specified:
				1418	"<tt>-foo=a -foo=b -foo=c</tt>" and "<tt>-foo=a,b,c</tt>". This option only
				1419	makes sense to be used in a case where the option is allowed to accept one or
				1420	more values (i.e. it is a <a href="#cl::list">cl::list</a> option).</li>
				1421
				1422	<li><a name="cl::PositionalEatsArgs">The
				1423	<b><tt>cl::PositionalEatsArgs</tt></b></a> modifier (which only applies to
				1424	positional arguments, and only makes sense for lists) indicates that positional
				1425	argument should consume any strings after it (including strings that start with
				1426	a "-") up until another recognized positional argument. For example, if you
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1427	have two "eating" positional arguments, "<tt>pos1</tt>" and "<tt>pos2</tt>", the
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1428	string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
				1429	-baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
				1430	"<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</li>
				1431
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1432	<li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is
				1433	used to handle unknown options. If there is at least one option with
				1434	<b><tt>cl::Sink</tt></b></a> modifier specified, the parser passes
				1435	unrecognized option strings to it as values instead of signaling an
				1436	error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier
				1437	only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
				1438
				1439
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1440	</ul>
				1441
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1442	<p>So far, these are the only three miscellaneous option modifiers.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1443
				1444	</div>
				1445
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1446	<!-- _______________________________________________________________________ -->
				1447	<div class="doc_subsubsection">
				1448	<a name="response">Response files</a>
				1449	</div>
				1450
				1451	<div class="doc_text">
				1452
				1453	<p>Some systems, such as certain variants of Microsoft Windows and
				1454	some older Unices have a relatively low limit on command-line
				1455	length. It is therefore customary to use the so-called 'response
				1456	files' to circumvent this restriction. These files are mentioned on
				1457	the command-line (using the "@file") syntax. The program reads these
				1458	files and inserts the contents into argv, thereby working around the
				1459	command-line length limits. Response files are enabled by an optional
				1460	fourth argument to
				1461	<a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a>
				1462	and
				1463	<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
				1464	</p>
				1465
				1466	</div>
				1467
				1468
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1469	<!-- ======================================================================= -->
				1470	<div class="doc_subsection">
				1471	<a name="toplevel">Top-Level Classes and Functions</a>
				1472	</div>
				1473
				1474	<div class="doc_text">
				1475
				1476	<p>Despite all of the built-in flexibility, the CommandLine option library
				1477	really only consists of one function (<a
				1478	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>)
				1479	and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a
				1480	href="#cl::list"><tt>cl::list</tt></a>, and <a
				1481	href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
				1482	classes in detail.</p>
				1483
				1484	</div>
				1485
				1486	<!-- _______________________________________________________________________ -->
				1487	<div class="doc_subsubsection">
				1488	<a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
				1489	function</a>
				1490	</div>
				1491
				1492	<div class="doc_text">
				1493
				1494	<p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
				1495	directly from <tt>main</tt>, and is used to fill in the values of all of the
				1496	command line option variables once <tt>argc</tt> and <tt>argv</tt> are
				1497	available.</p>
				1498
				1499	<p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
				1500	(<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
				1501	which holds <a href="#description">additional extra text</a> to emit when the
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1502	<tt>--help</tt> option is invoked, and a fourth boolean parameter that enables
				1503	<a href="#response">response files</a>.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1504
				1505	</div>
				1506
				1507	<!-- _______________________________________________________________________ -->
				1508	<div class="doc_subsubsection">
				1509	<a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
				1510	function</a>
				1511	</div>
				1512
				1513	<div class="doc_text">
				1514
				1515	<p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
				1516	as <a
				1517	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
				1518	except that it is designed to take values for options from an environment
				1519	variable, for those cases in which reading the command line is not convenient or
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1520	desired. It fills in the values of all the command line option variables just
				1521	like <a
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1522	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
				1523	does.</p>
				1524
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1525	<p>It takes four parameters: the name of the program (since <tt>argv</tt> may
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1526	not be available, it can't just look in <tt>argv[0]</tt>), the name of the
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1527	environment variable to examine, the optional
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1528	<a href="#description">additional extra text</a> to emit when the
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1529	<tt>--help</tt> option is invoked, and the boolean
				1530	switch that controls whether <a href="#response">reponse files</a>
				1531	should be read.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1532
				1533	<p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
				1534	variable's value up into words and then process them using
				1535	<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
				1536	<b>Note:</b> Currently <tt>cl::ParseEnvironmentOptions</tt> does not support
				1537	quoting, so an environment variable containing <tt>-option "foo bar"</tt> will
				1538	be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>,
				1539	which is different from what you would get from the shell with the same
				1540	input.</p>
				1541
				1542	</div>
				1543
				1544	<!-- _______________________________________________________________________ -->
				1545	<div class="doc_subsubsection">
				1546	<a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
				1547	function</a>
				1548	</div>
				1549
				1550	<div class="doc_text">
				1551
				1552	<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1553	directly from <tt>main</tt> and <i>before</i>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1554	<tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
				1555	for a function to be called in response to the <tt>--version</tt> option instead
				1556	of having the <tt>CommandLine</tt> library print out the usual version string
				1557	for LLVM. This is useful for programs that are not part of LLVM but wish to use
				1558	the <tt>CommandLine</tt> facilities. Such programs should just define a small
				1559	function that takes no arguments and returns <tt>void</tt> and that prints out
				1560	whatever version information is appropriate for the program. Pass the address
				1561	of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
				1562	called when the <tt>--version</tt> option is given by the user.</p>
				1563
				1564	</div>
				1565	<!-- _______________________________________________________________________ -->
				1566	<div class="doc_subsubsection">
				1567	<a name="cl::opt">The <tt>cl::opt</tt> class</a>
				1568	</div>
				1569
				1570	<div class="doc_text">
				1571
				1572	<p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
				1573	options, and is the one used most of the time. It is a templated class which
				1574	can take up to three arguments (all except for the first have default values
				1575	though):</p>
				1576
				1577	<div class="doc_code"><pre>
				1578	<b>namespace</b> cl {
				1579	<b>template</b> <<b>class</b> DataType, <b>bool</b> ExternalStorage = <b>false</b>,
				1580	<b>class</b> ParserClass = parser<DataType> >
				1581	<b>class</b> opt;
				1582	}
				1583	</pre></div>
				1584
				1585	<p>The first template argument specifies what underlying data type the command
				1586	line argument is, and is used to select a default parser implementation. The
				1587	second template argument is used to specify whether the option should contain
				1588	the storage for the option (the default) or whether external storage should be
				1589	used to contain the value parsed for the option (see <a href="#storage">Internal
				1590	vs External Storage</a> for more information).</p>
				1591
				1592	<p>The third template argument specifies which parser to use. The default value
				1593	selects an instantiation of the <tt>parser</tt> class based on the underlying
				1594	data type of the option. In general, this default works well for most
				1595	applications, so this option is only used when using a <a
				1596	href="#customparser">custom parser</a>.</p>
				1597
				1598	</div>
				1599
				1600	<!-- _______________________________________________________________________ -->
				1601	<div class="doc_subsubsection">
				1602	<a name="cl::list">The <tt>cl::list</tt> class</a>
				1603	</div>
				1604
				1605	<div class="doc_text">
				1606
				1607	<p>The <tt>cl::list</tt> class is the class used to represent a list of command
				1608	line options. It too is a templated class which can take up to three
				1609	arguments:</p>
				1610
				1611	<div class="doc_code"><pre>
				1612	<b>namespace</b> cl {
				1613	<b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
				1614	<b>class</b> ParserClass = parser<DataType> >
				1615	<b>class</b> list;
				1616	}
				1617	</pre></div>
				1618
				1619	<p>This class works the exact same as the <a
				1620	href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is
				1621	the <b>type</b> of the external storage, not a boolean value. For this class,
				1622	the marker type '<tt>bool</tt>' is used to indicate that internal storage should
				1623	be used.</p>
				1624
				1625	</div>
				1626
				1627	<!-- _______________________________________________________________________ -->
				1628	<div class="doc_subsubsection">
				1629	<a name="cl::bits">The <tt>cl::bits</tt> class</a>
				1630	</div>
				1631
				1632	<div class="doc_text">
				1633
				1634	<p>The <tt>cl::bits</tt> class is the class used to represent a list of command
				1635	line options in the form of a bit vector. It is also a templated class which
				1636	can take up to three arguments:</p>
				1637
				1638	<div class="doc_code"><pre>
				1639	<b>namespace</b> cl {
				1640	<b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
				1641	<b>class</b> ParserClass = parser<DataType> >
				1642	<b>class</b> bits;
				1643	}
				1644	</pre></div>
				1645
				1646	<p>This class works the exact same as the <a
				1647	href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
				1648	must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
				1649
				1650	</div>
				1651
				1652	<!-- _______________________________________________________________________ -->
				1653	<div class="doc_subsubsection">
				1654	<a name="cl::alias">The <tt>cl::alias</tt> class</a>
				1655	</div>
				1656
				1657	<div class="doc_text">
				1658
				1659	<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
				1660	aliases for other arguments.</p>
				1661
				1662	<div class="doc_code"><pre>
				1663	<b>namespace</b> cl {
				1664	<b>class</b> alias;
				1665	}
				1666	</pre></div>
				1667
				1668	<p>The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be
				1669	used to specify which option this is an alias for. Alias arguments default to
				1670	being <a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do
				1671	the conversion from string to data.</p>
				1672
				1673	</div>
				1674
				1675	<!-- _______________________________________________________________________ -->
				1676	<div class="doc_subsubsection">
				1677	<a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
				1678	</div>
				1679
				1680	<div class="doc_text">
				1681
				1682	<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
				1683	help text to be printed out for the <tt>--help</tt> option.</p>
				1684
				1685	<div class="doc_code"><pre>
				1686	<b>namespace</b> cl {
				1687	<b>struct</b> extrahelp;
				1688	}
				1689	</pre></div>
				1690
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1691	<p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1692	parameter to the constructor. The text passed to the constructor will be printed
				1693	at the bottom of the help message, verbatim. Note that multiple
				1694	<tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
				1695	your tool needs to print additional help information, put all that help into a
				1696	single <tt>cl::extrahelp</tt> instance.</p>
				1697	<p>For example:</p>
				1698	<div class="doc_code"><pre>
				1699	cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
				1700	</pre></div>
				1701	</div>
				1702
				1703	<!-- ======================================================================= -->
				1704	<div class="doc_subsection">
				1705	<a name="builtinparsers">Builtin parsers</a>
				1706	</div>
				1707
				1708	<div class="doc_text">
				1709
				1710	<p>Parsers control how the string value taken from the command line is
				1711	translated into a typed value, suitable for use in a C++ program. By default,
				1712	the CommandLine library uses an instance of <tt>parser<type></tt> if the
				1713	command line option specifies that it uses values of type '<tt>type</tt>'.
				1714	Because of this, custom option processing is specified with specializations of
				1715	the '<tt>parser</tt>' class.</p>
				1716
				1717	<p>The CommandLine library provides the following builtin parser
				1718	specializations, which are sufficient for most applications. It can, however,
				1719	also be extended to work with new data types and new ways of interpreting the
				1720	same data. See the <a href="#customparser">Writing a Custom Parser</a> for more
				1721	details on this type of library extension.</p>
				1722
				1723	<ul>
				1724
				1725	<li><a name="genericparser">The <b>generic <tt>parser<t></tt> parser</b></a>
				1726	can be used to map strings values to any data type, through the use of the <a
				1727	href="#cl::values">cl::values</a> property, which specifies the mapping
				1728	information. The most common use of this parser is for parsing enum values,
				1729	which allows you to use the CommandLine library for all of the error checking to
				1730	make sure that only valid enum values are specified (as opposed to accepting
				1731	arbitrary strings). Despite this, however, the generic parser class can be used
				1732	for any data type.</li>
				1733
				1734	<li><a name="boolparser">The <b><tt>parser<bool></tt> specialization</b></a>
				1735	is used to convert boolean strings to a boolean value. Currently accepted
				1736	strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
				1737	"<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".</li>
				1738
				1739	<li><a name="boolOrDefaultparser">The <b><tt>parser<boolOrDefault></tt>
				1740	specialization</b></a> is used for cases where the value is boolean,
				1741	but we also need to know whether the option was specified at all. boolOrDefault
				1742	is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
				1743	the same strings as <b><tt>parser<bool></tt></b>.</li>
				1744
				1745	<li><a name="stringparser">The <b><tt>parser<string></tt>
				1746	specialization</b></a> simply stores the parsed string into the string value
				1747	specified. No conversion or modification of the data is performed.</li>
				1748
				1749	<li><a name="intparser">The <b><tt>parser<int></tt> specialization</b></a>
				1750	uses the C <tt>strtol</tt> function to parse the string input. As such, it will
				1751	accept a decimal number (with an optional '+' or '-' prefix) which must start
				1752	with a non-zero digit. It accepts octal numbers, which are identified with a
				1753	'<tt>0</tt>' prefix digit, and hexadecimal numbers with a prefix of
				1754	'<tt>0x</tt>' or '<tt>0X</tt>'.</li>
				1755
				1756	<li><a name="doubleparser">The <b><tt>parser<double></tt></b></a> and
				1757	<b><tt>parser<float></tt> specializations</b> use the standard C
				1758	<tt>strtod</tt> function to convert floating point strings into floating point
				1759	values. As such, a broad range of string formats is supported, including
				1760	exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
				1761	</li>
				1762
				1763	</ul>
				1764
				1765	</div>
				1766
				1767	<!-- *********************************************************************** -->
				1768	<div class="doc_section">
				1769	<a name="extensionguide">Extension Guide</a>
				1770	</div>
				1771	<!-- *********************************************************************** -->
				1772
				1773	<div class="doc_text">
				1774
				1775	<p>Although the CommandLine library has a lot of functionality built into it
				1776	already (as discussed previously), one of its true strengths lie in its
				1777	extensibility. This section discusses how the CommandLine library works under
				1778	the covers and illustrates how to do some simple, common, extensions.</p>
				1779
				1780	</div>
				1781
				1782	<!-- ======================================================================= -->
				1783	<div class="doc_subsection">
				1784	<a name="customparser">Writing a custom parser</a>
				1785	</div>
				1786
				1787	<div class="doc_text">
				1788
				1789	<p>One of the simplest and most common extensions is the use of a custom parser.
				1790	As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
				1791	of the CommandLine library that turns string input from the user into a
				1792	particular parsed data type, validating the input in the process.</p>
				1793
				1794	<p>There are two ways to use a new parser:</p>
				1795
				1796	<ol>
				1797
				1798	<li>
				1799
				1800	<p>Specialize the <a href="#genericparser"><tt>cl::parser</tt></a> template for
				1801	your custom data type.<p>
				1802
				1803	<p>This approach has the advantage that users of your custom data type will
				1804	automatically use your custom parser whenever they define an option with a value
				1805	type of your data type. The disadvantage of this approach is that it doesn't
				1806	work if your fundamental data type is something that is already supported.</p>
				1807
				1808	</li>
				1809
				1810	<li>
				1811
				1812	<p>Write an independent class, using it explicitly from options that need
				1813	it.</p>
				1814
				1815	<p>This approach works well in situations where you would line to parse an
				1816	option using special syntax for a not-very-special data-type. The drawback of
				1817	this approach is that users of your parser have to be aware that they are using
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1818	your parser instead of the builtin ones.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1819
				1820	</li>
				1821
				1822	</ol>
				1823
				1824	<p>To guide the discussion, we will discuss a custom parser that accepts file
				1825	sizes, specified with an optional unit after the numeric size. For example, we
				1826	would like to parse "102kb", "41M", "1G" into the appropriate integer value. In
				1827	this case, the underlying data type we want to parse into is
				1828	'<tt>unsigned</tt>'. We choose approach #2 above because we don't want to make
				1829	this the default for all <tt>unsigned</tt> options.</p>
				1830
				1831	<p>To start out, we declare our new <tt>FileSizeParser</tt> class:</p>
				1832
				1833	<div class="doc_code"><pre>
				1834	<b>struct</b> FileSizeParser : <b>public</b> cl::basic_parser<<b>unsigned</b>> {
				1835	<i>// parse - Return true on error.</i>
				1836	<b>bool</b> parse(cl::Option &O, <b>const char</b> *ArgName, <b>const</b> std::string &ArgValue,
				1837	<b>unsigned</b> &Val);
				1838	};
				1839	</pre></div>
				1840
				1841	<p>Our new class inherits from the <tt>cl::basic_parser</tt> template class to
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1842	fill in the default, boiler plate code for us. We give it the data type that
				1843	we parse into, the last argument to the <tt>parse</tt> method, so that clients of
				1844	our custom parser know what object type to pass in to the parse method. (Here we
				1845	declare that we parse into '<tt>unsigned</tt>' variables.)</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1846
				1847	<p>For most purposes, the only method that must be implemented in a custom
				1848	parser is the <tt>parse</tt> method. The <tt>parse</tt> method is called
				1849	whenever the option is invoked, passing in the option itself, the option name,
				1850	the string to parse, and a reference to a return value. If the string to parse
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1851	is not well-formed, the parser should output an error message and return true.
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1852	Otherwise it should return false and set '<tt>Val</tt>' to the parsed value. In
				1853	our example, we implement <tt>parse</tt> as:</p>
				1854
				1855	<div class="doc_code"><pre>
				1856	<b>bool</b> FileSizeParser::parse(cl::Option &O, <b>const char</b> *ArgName,
				1857	<b>const</b> std::string &Arg, <b>unsigned</b> &Val) {
				1858	<b>const char</b> *ArgStart = Arg.c_str();
				1859	<b>char</b> *End;
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1860
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1861	<i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
				1862	Val = (unsigned)strtol(ArgStart, &End, 0);
				1863
				1864	<b>while</b> (1) {
				1865	<b>switch</b> (*End++) {
				1866	<b>case</b> 0: <b>return</b> false; <i>// No error</i>
				1867	<b>case</b> 'i': <i>// Ignore the 'i' in KiB if people use that</i>
				1868	<b>case</b> 'b': <b>case</b> 'B': <i>// Ignore B suffix</i>
				1869	<b>break</b>;
				1870
				1871	<b>case</b> 'g': <b>case</b> 'G': Val = 10241024*1024; <b>break</b>;
				1872	<b>case</b> 'm': <b>case</b> 'M': Val = 10241024; <b>break</b>;
				1873	<b>case</b> 'k': <b>case</b> 'K': Val *= 1024; <b>break</b>;
				1874
				1875	default:
				1876	<i>// Print an error message if unrecognized character!</i>
				1877	<b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
				1878	}
				1879	}
				1880	}
				1881	</pre></div>
				1882
				1883	<p>This function implements a very simple parser for the kinds of strings we are
				1884	interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for
				1885	example), it is good enough for this example. Note that we use the option
				1886	itself to print out the error message (the <tt>error</tt> method always returns
				1887	true) in order to get a nice error message (shown below). Now that we have our
				1888	parser class, we can use it like this:</p>
				1889
				1890	<div class="doc_code"><pre>
				1891	<b>static</b> <a href="#cl::opt">cl::opt</a><<b>unsigned</b>, <b>false</b>, FileSizeParser>
				1892	MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
				1893	<a href="#cl::value_desc">cl::value_desc</a>("<i>size</i>"));
				1894	</pre></div>
				1895
				1896	<p>Which adds this to the output of our program:</p>
				1897
				1898	<div class="doc_code"><pre>
				1899	OPTIONS:
				1900	-help - display available options (--help-hidden for more)
				1901	...
				1902	<b>-max-file-size=<size> - Maximum file size to accept</b>
				1903	</pre></div>
				1904
				1905	<p>And we can test that our parse works correctly now (the test program just
				1906	prints out the max-file-size argument value):</p>
				1907
				1908	<div class="doc_code"><pre>
				1909	$ ./test
				1910	MFS: 0
				1911	$ ./test -max-file-size=123MB
				1912	MFS: 128974848
				1913	$ ./test -max-file-size=3G
				1914	MFS: 3221225472
				1915	$ ./test -max-file-size=dog
				1916	-max-file-size option: 'dog' value invalid for file size argument!
				1917	</pre></div>
				1918
				1919	<p>It looks like it works. The error message that we get is nice and helpful,
				1920	and we seem to accept reasonable file sizes. This wraps up the "custom parser"
				1921	tutorial.</p>
				1922
				1923	</div>
				1924
				1925	<!-- ======================================================================= -->
				1926	<div class="doc_subsection">
				1927	<a name="explotingexternal">Exploiting external storage</a>
				1928	</div>
				1929
				1930	<div class="doc_text">
				1931	<p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
				1932	will automatically be included in any program that links with that library.
				1933	This is a feature. However, sometimes it is necessary to know the value of the
				1934	command line option outside of the library. In these cases the library does or
				1935	should provide an external storage location that is accessible to users of the
				1936	library. Examples of this include the <tt>llvm::DebugFlag</tt> exported by the
				1937	<tt>lib/Support/Debug.cpp</tt> file and the <tt>llvm::TimePassesIsEnabled</tt>
				1938	flag exported by the <tt>lib/VMCore/Pass.cpp</tt> file.</p>
				1939
				1940	<p>TODO: complete this section</p>
				1941
				1942	</div>
				1943
				1944	<!-- ======================================================================= -->
				1945	<div class="doc_subsection">
				1946	<a name="dynamicopts">Dynamically adding command line options</a>
				1947	</div>
				1948
				1949	<div class="doc_text">
				1950
				1951	<p>TODO: fill in this section</p>
				1952
				1953	</div>
				1954
				1955	<!-- *********************************************************************** -->
				1956
				1957	<hr>
				1958	<address>
				1959	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman	947321d	2008-12-11 17:34:48 +0000	[diff] [blame^]	1960	src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1961	<a href="http://validator.w3.org/check/referer"><img
Misha Brukman	947321d	2008-12-11 17:34:48 +0000	[diff] [blame^]	1962	src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1963
				1964	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
				1965	<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
				1966	Last modified: $Date$
				1967	</address>
				1968
				1969	</body>
				1970	</html>