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

blob: 013ff27d1921c3ee7e5c7206bea2b17201209a1a [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
Mikhail Glushenkov	ad6fc7f	2009-01-16 22:54:19 +0000	[diff] [blame]	1149	<li><a name="cl::multi_val">The <b><tt>cl::multi_val</tt></b></a>
				1150	attribute specifies that this option takes has multiple values
				1151	(example: <tt>-sectalign segname sectname sectvalue</tt>). This
				1152	attribute takes one unsigned argument - the number of values for the
				1153	option. This attribute is valid only on <tt>cl::list</tt> options (and
				1154	will fail with compile error if you try to use it with other option
				1155	types). It is allowed to use all of the usual modifiers on
				1156	multi-valued options (besides <tt>cl::ValueDisallowed</tt>,
				1157	obviously).</li>
				1158
				1159
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1160	</ol>
				1161
				1162	You will get a compile time error if you try to use cl::values with a parser
				1163	that does not support it.</li>
				1164
				1165	</ul>
				1166
				1167	</div>
				1168
				1169	<!-- ======================================================================= -->
				1170	<div class="doc_subsection">
				1171	<a name="modifiers">Option Modifiers</a>
				1172	</div>
				1173
				1174	<div class="doc_text">
				1175
				1176	<p>Option modifiers are the flags and expressions that you pass into the
				1177	constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				1178	href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
				1179	tweak how options are parsed and how <tt>--help</tt> output is generated to fit
				1180	your application well.</p>
				1181
				1182	<p>These options fall into five main catagories:</p>
				1183
				1184	<ol>
				1185	<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
				1186	<li><a href="#numoccurrences">Controlling the number of occurrences
				1187	required and allowed</a></li>
				1188	<li><a href="#valrequired">Controlling whether or not a value must be
				1189	specified</a></li>
				1190	<li><a href="#formatting">Controlling other formatting options</a></li>
				1191	<li><a href="#misc">Miscellaneous option modifiers</a></li>
				1192	</ol>
				1193
				1194	<p>It is not possible to specify two options from the same catagory (you'll get
				1195	a runtime error) to a single option, except for options in the miscellaneous
				1196	catagory. The CommandLine library specifies defaults for all of these settings
				1197	that are the most useful in practice and the most common, which mean that you
				1198	usually shouldn't have to worry about these.</p>
				1199
				1200	</div>
				1201
				1202	<!-- _______________________________________________________________________ -->
				1203	<div class="doc_subsubsection">
				1204	<a name="hiding">Hiding an option from <tt>--help</tt> output</a>
				1205	</div>
				1206
				1207	<div class="doc_text">
				1208
				1209	<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
				1210	<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
				1211	appears in the <tt>--help</tt> and <tt>--help-hidden</tt> output for the
				1212	compiled program:</p>
				1213
				1214	<ul>
				1215
				1216	<li><a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b></a> modifier
				1217	(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]	1218	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]	1219	in both help listings.</li>
				1220
				1221	<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]	1222	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]	1223	the option should not appear in the <tt>--help</tt> output, but should appear in
				1224	the <tt>--help-hidden</tt> output.</li>
				1225
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1226	<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]	1227	indicates that the option should not appear in any help output.</li>
				1228
				1229	</ul>
				1230
				1231	</div>
				1232
				1233	<!-- _______________________________________________________________________ -->
				1234	<div class="doc_subsubsection">
				1235	<a name="numoccurrences">Controlling the number of occurrences required and
				1236	allowed</a>
				1237	</div>
				1238
				1239	<div class="doc_text">
				1240
				1241	<p>This group of options is used to control how many time an option is allowed
				1242	(or required) to be specified on the command line of your program. Specifying a
				1243	value for this setting allows the CommandLine library to do error checking for
				1244	you.</p>
				1245
				1246	<p>The allowed values for this option group are:</p>
				1247
				1248	<ul>
				1249
				1250	<li><a name="cl::Optional">The <b><tt>cl::Optional</tt></b></a> modifier (which
				1251	is the default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				1252	href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will
				1253	allow either zero or one occurrence of the option to be specified.</li>
				1254
				1255	<li><a name="cl::ZeroOrMore">The <b><tt>cl::ZeroOrMore</tt></b></a> modifier
				1256	(which is the default for the <tt><a href="#cl::list">cl::list</a></tt> class)
				1257	indicates that your program will allow the option to be specified zero or more
				1258	times.</li>
				1259
				1260	<li><a name="cl::Required">The <b><tt>cl::Required</tt></b></a> modifier
				1261	indicates that the specified option must be specified exactly one time.</li>
				1262
				1263	<li><a name="cl::OneOrMore">The <b><tt>cl::OneOrMore</tt></b></a> modifier
				1264	indicates that the option must be specified at least one time.</li>
				1265
				1266	<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]	1267	href="#positional">Positional arguments section</a>.</li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1268
				1269	</ul>
				1270
				1271	<p>If an option is not specified, then the value of the option is equal to the
				1272	value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute. If
				1273	the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the
				1274	option value is initialized with the default constructor for the data type.</p>
				1275
				1276	<p>If an option is specified multiple times for an option of the <tt><a
				1277	href="#cl::opt">cl::opt</a></tt> class, only the last value will be
				1278	retained.</p>
				1279
				1280	</div>
				1281
				1282	<!-- _______________________________________________________________________ -->
				1283	<div class="doc_subsubsection">
				1284	<a name="valrequired">Controlling whether or not a value must be specified</a>
				1285	</div>
				1286
				1287	<div class="doc_text">
				1288
				1289	<p>This group of options is used to control whether or not the option allows a
				1290	value to be present. In the case of the CommandLine library, a value is either
				1291	specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing
				1292	string (e.g. '<tt>-o a.out</tt>').</p>
				1293
				1294	<p>The allowed values for this option group are:</p>
				1295
				1296	<ul>
				1297
				1298	<li><a name="cl::ValueOptional">The <b><tt>cl::ValueOptional</tt></b></a> modifier
				1299	(which is the default for <tt>bool</tt> typed options) specifies that it is
				1300	acceptable to have a value, or not. A boolean argument can be enabled just by
				1301	appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'.
				1302	If an option is specified with this mode, it is illegal for the value to be
				1303	provided without the equal sign. Therefore '<tt>-foo true</tt>' is illegal. To
				1304	get this behavior, you must use the <a
				1305	href="#cl::ValueRequired">cl::ValueRequired</a> modifier.</li>
				1306
				1307	<li><a name="cl::ValueRequired">The <b><tt>cl::ValueRequired</tt></b></a> modifier
				1308	(which is the default for all other types except for <a
				1309	href="#onealternative">unnamed alternatives using the generic parser</a>)
				1310	specifies that a value must be provided. This mode informs the command line
				1311	library that if an option is not provides with an equal sign, that the next
				1312	argument provided must be the value. This allows things like '<tt>-o
				1313	a.out</tt>' to work.</li>
				1314
				1315	<li><a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b></a>
				1316	modifier (which is the default for <a href="#onealternative">unnamed
				1317	alternatives using the generic parser</a>) indicates that it is a runtime error
				1318	for the user to specify a value. This can be provided to disallow users from
				1319	providing options to boolean options (like '<tt>-foo=true</tt>').</li>
				1320
				1321	</ul>
				1322
				1323	<p>In general, the default values for this option group work just like you would
				1324	want them to. As mentioned above, you can specify the <a
				1325	href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean
				1326	argument to restrict your command line parser. These options are mostly useful
				1327	when <a href="#extensionguide">extending the library</a>.</p>
				1328
				1329	</div>
				1330
				1331	<!-- _______________________________________________________________________ -->
				1332	<div class="doc_subsubsection">
				1333	<a name="formatting">Controlling other formatting options</a>
				1334	</div>
				1335
				1336	<div class="doc_text">
				1337
				1338	<p>The formatting option group is used to specify that the command line option
				1339	has special abilities and is otherwise different from other command line
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1340	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]	1341
				1342	<ul>
				1343
				1344	<li><a name="cl::NormalFormatting">The <b><tt>cl::NormalFormatting</tt></b></a>
				1345	modifier (which is the default all options) specifies that this option is
				1346	"normal".</li>
				1347
				1348	<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]	1349	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]	1350	option associated with it. See the <a href="#positional">Positional
				1351	Arguments</a> section for more information.</li>
				1352
				1353	<li>The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier
				1354	specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
				1355
				1356	<li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
				1357	that this option prefixes its value. With 'Prefix' options, the equal sign does
				1358	not separate the value from the option name specified. Instead, the value is
				1359	everything after the prefix, including any equal sign if present. This is useful
				1360	for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
				1361	linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
				1362	'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
				1363	options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
				1364	modifier added to allow the CommandLine library to recognize them. Note that
				1365	<b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
				1366	<b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
				1367	specified.</li>
				1368
				1369	<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]	1370	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]	1371	arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
				1372	command actually enables four different options, all of which are single
				1373	letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
				1374	options cannot have values.</li>
				1375
				1376	</ul>
				1377
				1378	<p>The CommandLine library does not restrict how you use the <b><tt><a
				1379	href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
				1380	href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
				1381	specify ambiguous argument settings. Thus, it is possible to have multiple
				1382	letter options that are prefix or grouping options, and they will still work as
				1383	designed.</p>
				1384
				1385	<p>To do this, the CommandLine library uses a greedy algorithm to parse the
				1386	input option into (potentially multiple) prefix and grouping options. The
				1387	strategy basically looks like this:</p>
				1388
				1389	<div class="doc_code"><tt>parse(string OrigInput) {</tt>
				1390
				1391	<ol>
				1392	<li><tt>string input = OrigInput;</tt>
				1393	<li><tt>if (isOption(input)) return getOption(input).parse();</tt>    <i>// Normal option</i>
				1394	<li><tt>while (!isOption(input) && !input.empty()) input.pop_back();</tt>    <i>// Remove the last letter</i>
				1395	<li><tt>if (input.empty()) return error();</tt>    <i>// No matching option</i>
				1396	<li><tt>if (getOption(input).isPrefix())<br>
				1397	return getOption(input).parse(input);</tt>
				1398	<li><tt>while (!input.empty()) {    <i>// Must be grouping options</i><br>
				1399	getOption(input).parse();<br>
				1400	OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());<br>
				1401	input = OrigInput;<br>
				1402	while (!isOption(input) && !input.empty()) input.pop_back();<br>
				1403	}</tt>
				1404	<li><tt>if (!OrigInput.empty()) error();</tt></li>
				1405	</ol>
				1406
				1407	<p><tt>}</tt></p>
				1408	</div>
				1409
				1410	</div>
				1411
				1412	<!-- _______________________________________________________________________ -->
				1413	<div class="doc_subsubsection">
				1414	<a name="misc">Miscellaneous option modifiers</a>
				1415	</div>
				1416
				1417	<div class="doc_text">
				1418
				1419	<p>The miscellaneous option modifiers are the only flags where you can specify
				1420	more than one flag from the set: they are not mutually exclusive. These flags
				1421	specify boolean properties that modify the option.</p>
				1422
				1423	<ul>
				1424
				1425	<li><a name="cl::CommaSeparated">The <b><tt>cl::CommaSeparated</tt></b></a> modifier
				1426	indicates that any commas specified for an option's value should be used to
				1427	split the value up into multiple values for the option. For example, these two
				1428	options are equivalent when <tt>cl::CommaSeparated</tt> is specified:
				1429	"<tt>-foo=a -foo=b -foo=c</tt>" and "<tt>-foo=a,b,c</tt>". This option only
				1430	makes sense to be used in a case where the option is allowed to accept one or
				1431	more values (i.e. it is a <a href="#cl::list">cl::list</a> option).</li>
				1432
				1433	<li><a name="cl::PositionalEatsArgs">The
				1434	<b><tt>cl::PositionalEatsArgs</tt></b></a> modifier (which only applies to
				1435	positional arguments, and only makes sense for lists) indicates that positional
				1436	argument should consume any strings after it (including strings that start with
				1437	a "-") up until another recognized positional argument. For example, if you
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1438	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]	1439	string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
				1440	-baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
				1441	"<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</li>
				1442
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1443	<li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is
				1444	used to handle unknown options. If there is at least one option with
				1445	<b><tt>cl::Sink</tt></b></a> modifier specified, the parser passes
				1446	unrecognized option strings to it as values instead of signaling an
				1447	error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier
				1448	only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
				1449
Mike Stump	3567d38	2009-02-02 22:48:49 +0000	[diff] [blame]	1450	<li><a name="cl::AllowInverse">The <b><tt>cl::AllowInverse</tt></b></a>
				1451	modifier can be used on options that have the form <tt>-fopt</tt> to
				1452	automatically create a corresponding
				1453	<tt>-fno-opt</tt> option. The <tt>f</tt> can be any single
				1454	character, and the <tt>opt</tt> can be any one or more characters.
				1455	The value of the created option is the logical complement of the value
				1456	that would have been used if the base form of the option was used.
				1457	This modifier only makes sense with an option that uses
				1458	a <a href="#boolparser">bool parser</a>.</li>
				1459
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1460
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1461	</ul>
				1462
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1463	<p>So far, these are the only three miscellaneous option modifiers.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1464
				1465	</div>
				1466
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1467	<!-- _______________________________________________________________________ -->
				1468	<div class="doc_subsubsection">
				1469	<a name="response">Response files</a>
				1470	</div>
				1471
				1472	<div class="doc_text">
				1473
				1474	<p>Some systems, such as certain variants of Microsoft Windows and
				1475	some older Unices have a relatively low limit on command-line
				1476	length. It is therefore customary to use the so-called 'response
				1477	files' to circumvent this restriction. These files are mentioned on
				1478	the command-line (using the "@file") syntax. The program reads these
				1479	files and inserts the contents into argv, thereby working around the
				1480	command-line length limits. Response files are enabled by an optional
				1481	fourth argument to
				1482	<a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a>
				1483	and
				1484	<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
				1485	</p>
				1486
				1487	</div>
				1488
				1489
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1490	<!-- ======================================================================= -->
				1491	<div class="doc_subsection">
				1492	<a name="toplevel">Top-Level Classes and Functions</a>
				1493	</div>
				1494
				1495	<div class="doc_text">
				1496
				1497	<p>Despite all of the built-in flexibility, the CommandLine option library
				1498	really only consists of one function (<a
				1499	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>)
				1500	and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a
				1501	href="#cl::list"><tt>cl::list</tt></a>, and <a
				1502	href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
				1503	classes in detail.</p>
				1504
				1505	</div>
				1506
				1507	<!-- _______________________________________________________________________ -->
				1508	<div class="doc_subsubsection">
				1509	<a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
				1510	function</a>
				1511	</div>
				1512
				1513	<div class="doc_text">
				1514
				1515	<p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
				1516	directly from <tt>main</tt>, and is used to fill in the values of all of the
				1517	command line option variables once <tt>argc</tt> and <tt>argv</tt> are
				1518	available.</p>
				1519
				1520	<p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
				1521	(<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
				1522	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]	1523	<tt>--help</tt> option is invoked, and a fourth boolean parameter that enables
				1524	<a href="#response">response files</a>.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1525
				1526	</div>
				1527
				1528	<!-- _______________________________________________________________________ -->
				1529	<div class="doc_subsubsection">
				1530	<a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
				1531	function</a>
				1532	</div>
				1533
				1534	<div class="doc_text">
				1535
				1536	<p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
				1537	as <a
				1538	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
				1539	except that it is designed to take values for options from an environment
				1540	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]	1541	desired. It fills in the values of all the command line option variables just
				1542	like <a
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1543	href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
				1544	does.</p>
				1545
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1546	<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]	1547	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]	1548	environment variable to examine, the optional
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1549	<a href="#description">additional extra text</a> to emit when the
Mikhail Glushenkov	7015ef8	2008-04-28 16:44:25 +0000	[diff] [blame]	1550	<tt>--help</tt> option is invoked, and the boolean
				1551	switch that controls whether <a href="#response">reponse files</a>
				1552	should be read.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1553
				1554	<p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
				1555	variable's value up into words and then process them using
				1556	<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
				1557	<b>Note:</b> Currently <tt>cl::ParseEnvironmentOptions</tt> does not support
				1558	quoting, so an environment variable containing <tt>-option "foo bar"</tt> will
				1559	be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>,
				1560	which is different from what you would get from the shell with the same
				1561	input.</p>
				1562
				1563	</div>
				1564
				1565	<!-- _______________________________________________________________________ -->
				1566	<div class="doc_subsubsection">
				1567	<a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
				1568	function</a>
				1569	</div>
				1570
				1571	<div class="doc_text">
				1572
				1573	<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
Chris Lattner	00e02f6	2008-01-09 19:28:50 +0000	[diff] [blame]	1574	directly from <tt>main</tt> and <i>before</i>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1575	<tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
				1576	for a function to be called in response to the <tt>--version</tt> option instead
				1577	of having the <tt>CommandLine</tt> library print out the usual version string
				1578	for LLVM. This is useful for programs that are not part of LLVM but wish to use
				1579	the <tt>CommandLine</tt> facilities. Such programs should just define a small
				1580	function that takes no arguments and returns <tt>void</tt> and that prints out
				1581	whatever version information is appropriate for the program. Pass the address
				1582	of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
				1583	called when the <tt>--version</tt> option is given by the user.</p>
				1584
				1585	</div>
				1586	<!-- _______________________________________________________________________ -->
				1587	<div class="doc_subsubsection">
				1588	<a name="cl::opt">The <tt>cl::opt</tt> class</a>
				1589	</div>
				1590
				1591	<div class="doc_text">
				1592
				1593	<p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
				1594	options, and is the one used most of the time. It is a templated class which
				1595	can take up to three arguments (all except for the first have default values
				1596	though):</p>
				1597
				1598	<div class="doc_code"><pre>
				1599	<b>namespace</b> cl {
				1600	<b>template</b> <<b>class</b> DataType, <b>bool</b> ExternalStorage = <b>false</b>,
				1601	<b>class</b> ParserClass = parser<DataType> >
				1602	<b>class</b> opt;
				1603	}
				1604	</pre></div>
				1605
				1606	<p>The first template argument specifies what underlying data type the command
				1607	line argument is, and is used to select a default parser implementation. The
				1608	second template argument is used to specify whether the option should contain
				1609	the storage for the option (the default) or whether external storage should be
				1610	used to contain the value parsed for the option (see <a href="#storage">Internal
				1611	vs External Storage</a> for more information).</p>
				1612
				1613	<p>The third template argument specifies which parser to use. The default value
				1614	selects an instantiation of the <tt>parser</tt> class based on the underlying
				1615	data type of the option. In general, this default works well for most
				1616	applications, so this option is only used when using a <a
				1617	href="#customparser">custom parser</a>.</p>
				1618
				1619	</div>
				1620
				1621	<!-- _______________________________________________________________________ -->
				1622	<div class="doc_subsubsection">
				1623	<a name="cl::list">The <tt>cl::list</tt> class</a>
				1624	</div>
				1625
				1626	<div class="doc_text">
				1627
				1628	<p>The <tt>cl::list</tt> class is the class used to represent a list of command
				1629	line options. It too is a templated class which can take up to three
				1630	arguments:</p>
				1631
				1632	<div class="doc_code"><pre>
				1633	<b>namespace</b> cl {
				1634	<b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
				1635	<b>class</b> ParserClass = parser<DataType> >
				1636	<b>class</b> list;
				1637	}
				1638	</pre></div>
				1639
				1640	<p>This class works the exact same as the <a
				1641	href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is
				1642	the <b>type</b> of the external storage, not a boolean value. For this class,
				1643	the marker type '<tt>bool</tt>' is used to indicate that internal storage should
				1644	be used.</p>
				1645
				1646	</div>
				1647
				1648	<!-- _______________________________________________________________________ -->
				1649	<div class="doc_subsubsection">
				1650	<a name="cl::bits">The <tt>cl::bits</tt> class</a>
				1651	</div>
				1652
				1653	<div class="doc_text">
				1654
				1655	<p>The <tt>cl::bits</tt> class is the class used to represent a list of command
				1656	line options in the form of a bit vector. It is also a templated class which
				1657	can take up to three arguments:</p>
				1658
				1659	<div class="doc_code"><pre>
				1660	<b>namespace</b> cl {
				1661	<b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
				1662	<b>class</b> ParserClass = parser<DataType> >
				1663	<b>class</b> bits;
				1664	}
				1665	</pre></div>
				1666
				1667	<p>This class works the exact same as the <a
				1668	href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
				1669	must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
				1670
				1671	</div>
				1672
				1673	<!-- _______________________________________________________________________ -->
				1674	<div class="doc_subsubsection">
				1675	<a name="cl::alias">The <tt>cl::alias</tt> class</a>
				1676	</div>
				1677
				1678	<div class="doc_text">
				1679
				1680	<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
				1681	aliases for other arguments.</p>
				1682
				1683	<div class="doc_code"><pre>
				1684	<b>namespace</b> cl {
				1685	<b>class</b> alias;
				1686	}
				1687	</pre></div>
				1688
				1689	<p>The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be
				1690	used to specify which option this is an alias for. Alias arguments default to
				1691	being <a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do
				1692	the conversion from string to data.</p>
				1693
				1694	</div>
				1695
				1696	<!-- _______________________________________________________________________ -->
				1697	<div class="doc_subsubsection">
				1698	<a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
				1699	</div>
				1700
				1701	<div class="doc_text">
				1702
				1703	<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
				1704	help text to be printed out for the <tt>--help</tt> option.</p>
				1705
				1706	<div class="doc_code"><pre>
				1707	<b>namespace</b> cl {
				1708	<b>struct</b> extrahelp;
				1709	}
				1710	</pre></div>
				1711
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1712	<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]	1713	parameter to the constructor. The text passed to the constructor will be printed
				1714	at the bottom of the help message, verbatim. Note that multiple
				1715	<tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
				1716	your tool needs to print additional help information, put all that help into a
				1717	single <tt>cl::extrahelp</tt> instance.</p>
				1718	<p>For example:</p>
				1719	<div class="doc_code"><pre>
				1720	cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
				1721	</pre></div>
				1722	</div>
				1723
				1724	<!-- ======================================================================= -->
				1725	<div class="doc_subsection">
				1726	<a name="builtinparsers">Builtin parsers</a>
				1727	</div>
				1728
				1729	<div class="doc_text">
				1730
				1731	<p>Parsers control how the string value taken from the command line is
				1732	translated into a typed value, suitable for use in a C++ program. By default,
				1733	the CommandLine library uses an instance of <tt>parser<type></tt> if the
				1734	command line option specifies that it uses values of type '<tt>type</tt>'.
				1735	Because of this, custom option processing is specified with specializations of
				1736	the '<tt>parser</tt>' class.</p>
				1737
				1738	<p>The CommandLine library provides the following builtin parser
				1739	specializations, which are sufficient for most applications. It can, however,
				1740	also be extended to work with new data types and new ways of interpreting the
				1741	same data. See the <a href="#customparser">Writing a Custom Parser</a> for more
				1742	details on this type of library extension.</p>
				1743
				1744	<ul>
				1745
				1746	<li><a name="genericparser">The <b>generic <tt>parser<t></tt> parser</b></a>
				1747	can be used to map strings values to any data type, through the use of the <a
				1748	href="#cl::values">cl::values</a> property, which specifies the mapping
				1749	information. The most common use of this parser is for parsing enum values,
				1750	which allows you to use the CommandLine library for all of the error checking to
				1751	make sure that only valid enum values are specified (as opposed to accepting
				1752	arbitrary strings). Despite this, however, the generic parser class can be used
				1753	for any data type.</li>
				1754
				1755	<li><a name="boolparser">The <b><tt>parser<bool></tt> specialization</b></a>
				1756	is used to convert boolean strings to a boolean value. Currently accepted
				1757	strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
Mike Stump	3567d38	2009-02-02 22:48:49 +0000	[diff] [blame]	1758	"<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>". The
				1759	<b><tt>cl::AllowInverse</tt></b> modifier can be used on an option of the form
				1760	<tt>-fopt</tt> that uses the <tt>parser<bool></tt> specialization
				1761	to create a corresponding option with the form <tt>-fno-opt</tt>. See
				1762	<a href="#cl::AllowInverse"><tt>cl::AllowInverse</tt></a> for details.</li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1763
				1764	<li><a name="boolOrDefaultparser">The <b><tt>parser<boolOrDefault></tt>
				1765	specialization</b></a> is used for cases where the value is boolean,
				1766	but we also need to know whether the option was specified at all. boolOrDefault
				1767	is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
				1768	the same strings as <b><tt>parser<bool></tt></b>.</li>
				1769
				1770	<li><a name="stringparser">The <b><tt>parser<string></tt>
				1771	specialization</b></a> simply stores the parsed string into the string value
				1772	specified. No conversion or modification of the data is performed.</li>
				1773
				1774	<li><a name="intparser">The <b><tt>parser<int></tt> specialization</b></a>
				1775	uses the C <tt>strtol</tt> function to parse the string input. As such, it will
				1776	accept a decimal number (with an optional '+' or '-' prefix) which must start
				1777	with a non-zero digit. It accepts octal numbers, which are identified with a
				1778	'<tt>0</tt>' prefix digit, and hexadecimal numbers with a prefix of
				1779	'<tt>0x</tt>' or '<tt>0X</tt>'.</li>
				1780
				1781	<li><a name="doubleparser">The <b><tt>parser<double></tt></b></a> and
				1782	<b><tt>parser<float></tt> specializations</b> use the standard C
				1783	<tt>strtod</tt> function to convert floating point strings into floating point
				1784	values. As such, a broad range of string formats is supported, including
				1785	exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
				1786	</li>
				1787
				1788	</ul>
				1789
				1790	</div>
				1791
				1792	<!-- *********************************************************************** -->
				1793	<div class="doc_section">
				1794	<a name="extensionguide">Extension Guide</a>
				1795	</div>
				1796	<!-- *********************************************************************** -->
				1797
				1798	<div class="doc_text">
				1799
				1800	<p>Although the CommandLine library has a lot of functionality built into it
				1801	already (as discussed previously), one of its true strengths lie in its
				1802	extensibility. This section discusses how the CommandLine library works under
				1803	the covers and illustrates how to do some simple, common, extensions.</p>
				1804
				1805	</div>
				1806
				1807	<!-- ======================================================================= -->
				1808	<div class="doc_subsection">
				1809	<a name="customparser">Writing a custom parser</a>
				1810	</div>
				1811
				1812	<div class="doc_text">
				1813
				1814	<p>One of the simplest and most common extensions is the use of a custom parser.
				1815	As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
				1816	of the CommandLine library that turns string input from the user into a
				1817	particular parsed data type, validating the input in the process.</p>
				1818
				1819	<p>There are two ways to use a new parser:</p>
				1820
				1821	<ol>
				1822
				1823	<li>
				1824
				1825	<p>Specialize the <a href="#genericparser"><tt>cl::parser</tt></a> template for
				1826	your custom data type.<p>
				1827
				1828	<p>This approach has the advantage that users of your custom data type will
				1829	automatically use your custom parser whenever they define an option with a value
				1830	type of your data type. The disadvantage of this approach is that it doesn't
				1831	work if your fundamental data type is something that is already supported.</p>
				1832
				1833	</li>
				1834
				1835	<li>
				1836
				1837	<p>Write an independent class, using it explicitly from options that need
				1838	it.</p>
				1839
				1840	<p>This approach works well in situations where you would line to parse an
				1841	option using special syntax for a not-very-special data-type. The drawback of
				1842	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]	1843	your parser instead of the builtin ones.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1844
				1845	</li>
				1846
				1847	</ol>
				1848
				1849	<p>To guide the discussion, we will discuss a custom parser that accepts file
				1850	sizes, specified with an optional unit after the numeric size. For example, we
				1851	would like to parse "102kb", "41M", "1G" into the appropriate integer value. In
				1852	this case, the underlying data type we want to parse into is
				1853	'<tt>unsigned</tt>'. We choose approach #2 above because we don't want to make
				1854	this the default for all <tt>unsigned</tt> options.</p>
				1855
				1856	<p>To start out, we declare our new <tt>FileSizeParser</tt> class:</p>
				1857
				1858	<div class="doc_code"><pre>
				1859	<b>struct</b> FileSizeParser : <b>public</b> cl::basic_parser<<b>unsigned</b>> {
				1860	<i>// parse - Return true on error.</i>
				1861	<b>bool</b> parse(cl::Option &O, <b>const char</b> *ArgName, <b>const</b> std::string &ArgValue,
				1862	<b>unsigned</b> &Val);
				1863	};
				1864	</pre></div>
				1865
				1866	<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]	1867	fill in the default, boiler plate code for us. We give it the data type that
				1868	we parse into, the last argument to the <tt>parse</tt> method, so that clients of
				1869	our custom parser know what object type to pass in to the parse method. (Here we
				1870	declare that we parse into '<tt>unsigned</tt>' variables.)</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1871
				1872	<p>For most purposes, the only method that must be implemented in a custom
				1873	parser is the <tt>parse</tt> method. The <tt>parse</tt> method is called
				1874	whenever the option is invoked, passing in the option itself, the option name,
				1875	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]	1876	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]	1877	Otherwise it should return false and set '<tt>Val</tt>' to the parsed value. In
				1878	our example, we implement <tt>parse</tt> as:</p>
				1879
				1880	<div class="doc_code"><pre>
				1881	<b>bool</b> FileSizeParser::parse(cl::Option &O, <b>const char</b> *ArgName,
				1882	<b>const</b> std::string &Arg, <b>unsigned</b> &Val) {
				1883	<b>const char</b> *ArgStart = Arg.c_str();
				1884	<b>char</b> *End;
Anton Korobeynikov	1c1e900	2008-02-20 12:38:31 +0000	[diff] [blame]	1885
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1886	<i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
				1887	Val = (unsigned)strtol(ArgStart, &End, 0);
				1888
				1889	<b>while</b> (1) {
				1890	<b>switch</b> (*End++) {
				1891	<b>case</b> 0: <b>return</b> false; <i>// No error</i>
				1892	<b>case</b> 'i': <i>// Ignore the 'i' in KiB if people use that</i>
				1893	<b>case</b> 'b': <b>case</b> 'B': <i>// Ignore B suffix</i>
				1894	<b>break</b>;
				1895
				1896	<b>case</b> 'g': <b>case</b> 'G': Val = 10241024*1024; <b>break</b>;
				1897	<b>case</b> 'm': <b>case</b> 'M': Val = 10241024; <b>break</b>;
				1898	<b>case</b> 'k': <b>case</b> 'K': Val *= 1024; <b>break</b>;
				1899
				1900	default:
				1901	<i>// Print an error message if unrecognized character!</i>
				1902	<b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
				1903	}
				1904	}
				1905	}
				1906	</pre></div>
				1907
				1908	<p>This function implements a very simple parser for the kinds of strings we are
				1909	interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for
				1910	example), it is good enough for this example. Note that we use the option
				1911	itself to print out the error message (the <tt>error</tt> method always returns
				1912	true) in order to get a nice error message (shown below). Now that we have our
				1913	parser class, we can use it like this:</p>
				1914
				1915	<div class="doc_code"><pre>
				1916	<b>static</b> <a href="#cl::opt">cl::opt</a><<b>unsigned</b>, <b>false</b>, FileSizeParser>
				1917	MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
				1918	<a href="#cl::value_desc">cl::value_desc</a>("<i>size</i>"));
				1919	</pre></div>
				1920
				1921	<p>Which adds this to the output of our program:</p>
				1922
				1923	<div class="doc_code"><pre>
				1924	OPTIONS:
				1925	-help - display available options (--help-hidden for more)
				1926	...
				1927	<b>-max-file-size=<size> - Maximum file size to accept</b>
				1928	</pre></div>
				1929
				1930	<p>And we can test that our parse works correctly now (the test program just
				1931	prints out the max-file-size argument value):</p>
				1932
				1933	<div class="doc_code"><pre>
				1934	$ ./test
				1935	MFS: 0
				1936	$ ./test -max-file-size=123MB
				1937	MFS: 128974848
				1938	$ ./test -max-file-size=3G
				1939	MFS: 3221225472
				1940	$ ./test -max-file-size=dog
				1941	-max-file-size option: 'dog' value invalid for file size argument!
				1942	</pre></div>
				1943
				1944	<p>It looks like it works. The error message that we get is nice and helpful,
				1945	and we seem to accept reasonable file sizes. This wraps up the "custom parser"
				1946	tutorial.</p>
				1947
				1948	</div>
				1949
				1950	<!-- ======================================================================= -->
				1951	<div class="doc_subsection">
				1952	<a name="explotingexternal">Exploiting external storage</a>
				1953	</div>
				1954
				1955	<div class="doc_text">
				1956	<p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
				1957	will automatically be included in any program that links with that library.
				1958	This is a feature. However, sometimes it is necessary to know the value of the
				1959	command line option outside of the library. In these cases the library does or
				1960	should provide an external storage location that is accessible to users of the
				1961	library. Examples of this include the <tt>llvm::DebugFlag</tt> exported by the
				1962	<tt>lib/Support/Debug.cpp</tt> file and the <tt>llvm::TimePassesIsEnabled</tt>
				1963	flag exported by the <tt>lib/VMCore/Pass.cpp</tt> file.</p>
				1964
				1965	<p>TODO: complete this section</p>
				1966
				1967	</div>
				1968
				1969	<!-- ======================================================================= -->
				1970	<div class="doc_subsection">
				1971	<a name="dynamicopts">Dynamically adding command line options</a>
				1972	</div>
				1973
				1974	<div class="doc_text">
				1975
				1976	<p>TODO: fill in this section</p>
				1977
				1978	</div>
				1979
				1980	<!-- *********************************************************************** -->
				1981
				1982	<hr>
				1983	<address>
				1984	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman	947321d	2008-12-11 17:34:48 +0000	[diff] [blame]	1985	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]	1986	<a href="http://validator.w3.org/check/referer"><img
Misha Brukman	947321d	2008-12-11 17:34:48 +0000	[diff] [blame]	1987	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]	1988
				1989	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
				1990	<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
				1991	Last modified: $Date$
				1992	</address>
				1993
				1994	</body>
				1995	</html>