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

blob: b3e9840b1fc2b2b877ba8cc5f7b6cd947c54b878 [file] [log] [blame]

Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	2	<html><head><title>CommandLine 2.0 Library Manual</title></head>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	3	<body bgcolor=white>
				4
				5	<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	6	<tr><td>  <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>CommandLine 2.0 Library Manual</b></font></td>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	7	</tr></table>
				8
				9	<ol>
				10	<li><a href="#introduction">Introduction</a>
				11	<li><a href="#quickstart">Quick Start Guide</a>
				12	<ol>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	13	<li><a href="#bool">Boolean Arguments</a>
				14	<li><a href="#alias">Argument Aliases</a>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	15	<li><a href="#onealternative">Selecting an alternative from a
				16	set of possibilities</a>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	17	<li><a href="#namedalternatives">Named alternatives</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	18	<li><a href="#list">Parsing a list of options</a>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	19	</ol>
				20	<li><a href="#referenceguide">Reference Guide</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	21	<ol>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	22	<li><a href="#positional">Positional Arguments</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	23	<ul>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	24	<li><a href="#--">Specifying positional options with hyphens</a>
				25	<li><a href="#cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt>
				26	modifier</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	27	</ul>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	28	<li><a href="#storage">Internal vs External Storage</a>
				29	<li><a href="#attributes">Option Attributes</a>
				30	<li><a href="#modifiers">Option Modifiers</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	31	<ul>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	32	<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a>
				33	<li><a href="#numoccurances">Controlling the number of occurances
				34	required and allowed</a>
				35	<li><a href="#valrequired">Controlling whether or not a value must be
				36	specified</a>
				37	<li><a href="#formatting">Controlling other formatting options</a>
				38	</ul>
				39	<li><a href="#optionclasses">Option Classes</a>
				40	<ul>
				41	<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a>
				42	<li><a href="#cl::list">The <tt>cl::list</tt> class</a>
				43	<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a>
				44	</ul>
				45	<li><a href="#builtinparsers">Builtin parsers</a>
				46	<ul>
				47	<li><a href="#genericparser">The Generic <tt>parser<t></tt>
				48	parser</a>
				49	<li><a href="#boolparser">The <tt>parser<bool></tt>
				50	specialization</a>
				51	<li><a href="#stringparser">The <tt>parser<string></tt>
				52	specialization</a>
				53	<li><a href="#intparser">The <tt>parser<int></tt>
				54	specialization</a>
				55	<li><a href="#doubleparser">The <tt>parser<double></tt> and
				56	<tt>parser<float></tt> specializations</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	57	</ul>
				58	</ol>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	59	<li><a href="#extensionguide">Extension Guide</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	60	<ol>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	61	<li><a href="#customparser">Writing a custom parser</a>
				62	<li><a href="#explotingexternal">Exploiting external storage</a>
				63	<li><a href="#dynamicopts">Dynamically adding command line options</a>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	64	</ol>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	65
				66	<p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b><p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	67	</ol><p>
				68
				69
				70	<!-- *********************************************************************** -->
				71	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				72	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				73	<a name="introduction">Introduction
				74	</b></font></td></tr></table><ul>
				75	<!-- *********************************************************************** -->
				76
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	77	This document describes the CommandLine argument processing library. It will
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	78	show you how to use it, and what it can do. The CommandLine library uses a
				79	declarative approach to specifying the command line options that your program
				80	takes. By default, these options declarations implicitly hold the value parsed
				81	for the option declared (of course this <a href="#storage">can be
				82	changed</a>).<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	83
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	84	Although there are a <b>lot</b> of command line argument parsing libraries out
				85	there in many different languages, none of them fit well with what I needed. By
				86	looking at the features and problems of other libraries, I designed the
				87	CommandLine library to have the following features:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	88
				89	<ol>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	90	<li>Speed: The CommandLine library is very quick and uses little resources. The
				91	parsing time of the library is directly proportional to the number of arguments
				92	parsed, not the the number of options recognized. Additionally, command line
				93	argument values are captured transparently into user defined variables, which
				94	can be accessed like any other variable (and with the same performance).<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	95
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	96	<li>Type Safe: As a user of CommandLine, you don't have to worry about
				97	remembering the type of arguments that you want (is it an int? a string? a
				98	bool? an enum?) and keep casting it around. Not only does this help prevent
				99	error prone constructs, it also leads to dramatically cleaner source code.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	100
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	101	<li>No subclasses required: To use CommandLine, you instantiate variables that
				102	correspond to the arguments that you would like to capture, you don't subclass a
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	103	parser. This means that you don't have to write <b>any</b> boilerplate code.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	104
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	105	<li>Globally accessible: Libraries can specify command line arguments that are
				106	automatically enabled in any tool that links to the library. This is possible
				107	because the application doesn't have to keep a "list" of arguments to pass to
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	108	the parser. This also makes supporting <a href="#dynamicopts">dynamically
				109	loaded options</a> trivial.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	110
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	111	<li>More Clean: CommandLine supports enum and other types directly, meaning that
				112	there is less error and more security built into the library. You don't have to
				113	worry about whether your integral command line argument accidentally got
				114	assigned a value that is not valid for your enum type.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	115
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	116	<li>Powerful: The CommandLine library supports many different types of
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	117	arguments, from simple <a href="#boolparser">boolean flags</a> to <a
				118	href="#cl::opt">scalars arguments</a> (<a href="#stringparser">strings</a>, <a
				119	href="#intparser">integers</a>, <a href="#genericparser">enums</a>, <a
				120	href="#doubleparser">doubles</a>), to <a href="#cl::list">lists of
				121	arguments</a>. This is possible because CommandLine is...<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	122
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	123	<li>Extensible: It is very simple to add a new argument type to CommandLine.
				124	Simply specify the parser that you want to use with the command line option when
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	125	you declare it. <a href="#customparser">Custom parsers</a> are no problem.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	126
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	127	<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	128	that you, the user, have to do. For example, it automatically provides a
				129	<tt>--help</tt> option that shows the available command line options for your
				130	tool. Additionally, it does most of the basic correctness checking for you.<p>
				131
				132	<li>Capable: The CommandLine library can handle lots of different forms of
				133	options often found in real programs. For example, <a
				134	href="#positional">positional</a> arguments, <tt>ls</tt> style <a
				135	href="#cl::Grouping">grouping</a> options (to allow processing '<tt>ls
				136	-lad</tt>' naturally), <tt>ld</tt> style <a href="#cl::Prefix">prefix</a>
				137	options (to parse '<tt>-lmalloc -L/usr/lib</tt>'), and <a
				138	href="#cl::ConsumeAfter">interpreter style options</a>.<p>
				139
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	140	</ol>
				141
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	142	This document will hopefully let you jump in and start using CommandLine in your
				143	utility quickly and painlessly. Additionally it should be a simple reference
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	144	manual to figure out how stuff works. If it is failing in some area (or you
				145	want an extension to the library), nag the author, <a
				146	href="mailto:sabre@nondot.org">Chris Lattner</a>.<p>
				147
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	148
				149
				150	<!-- *********************************************************************** -->
				151	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				152	<a name="quickstart">Quick Start Guide
				153	</b></font></td></tr></table><ul>
				154	<!-- *********************************************************************** -->
				155
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	156	This section of the manual runs through a simple CommandLine'ification of a
				157	basic compiler tool. This is intended to show you how to jump into using the
				158	CommandLine library in your own program, and show you some of the cool things it
				159	can do.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	160
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	161	To start out, you need to include the CommandLine header file into your
				162	program:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	163
				164	<pre>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	165	#include "Support/CommandLine.h"
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	166	</pre><p>
				167
				168	Additionally, you need to add this as the first line of your main program:<p>
				169
				170	<pre>
				171	int main(int argc, char **argv) {
				172	cl::ParseCommandLineOptions(argc, argv);
				173	...
				174	}
				175	</pre><p>
				176
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	177	... which actually parses the arguments and fills in the variable
				178	declarations.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	179
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	180	Now that you are ready to support command line arguments, we need to tell the
				181	system which ones we want, and what type of argument they are. The CommandLine
				182	library uses a declarative syntax to model cammand line arguments with the
				183	variable declarations that capture the parsed values. This means that for every
				184	command line option that you would like to support, there should be a variable
				185	declaration to capture the result. For example, in a compiler, we would like to
				186	support the unix standard '<tt>-o <filename></tt>' option to specify where
				187	to put the output. With the CommandLine library, this is represented like
				188	this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	189
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	190	<pre><a name="value_desc_example">
				191	<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>"));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	192	</pre><p>
				193
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	194	This declares a variable "<tt>OutputFilename</tt>" that is used to capture the
				195	result of the "<tt>o</tt>" argument (first parameter). We specify that this is
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	196	a simple scalar option by using the "<tt><a href="#cl::opt">cl::opt</a></tt>"
				197	template (as opposed to the <a href="#list">"<tt>cl::list</tt>
				198	template</a>), and tell the CommandLine library that the data type that we are
				199	parsing is a string.<p>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	200
				201	The second and third parameters (which are optional) are used to specify what to
				202	output for the "<tt>--help</tt>" option. In this case, we get a line that looks
				203	like this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	204
				205	<pre>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	206	USAGE: compiler [options]
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	207
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	208	OPTIONS:
				209	-help - display available options (--help-hidden for more)
				210	-o <filename> - Specify output filename
				211	</pre>
				212
				213	Because we specified that the command line option should parse using the
				214	<tt>string</tt> data type, the variable declared is automatically usable as a
				215	real string in all contexts that a normal C++ string object may be used. For
				216	example:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	217
				218	<pre>
				219	...
				220	ofstream Output(OutputFilename.c_str());
				221	if (Out.good()) ...
				222	...
				223	</pre><p>
				224
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	225	There are many different options that you can use to customize the command line
				226	option handling library, but the above example shows the general interface to
				227	these options. The options can be specified in any order, and are specified
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	228	with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so
				229	there are no positional dependencies to have to remember. The available options
				230	are discussed in detail in the <a href="#referenceguide">Reference Guide</a>.<p>
				231
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	232
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	233	Continuing the example, we would like to have our compiler take an input
				234	filename as well as an output filename, but we do not want the input filename to
				235	be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	236	style of argument, the CommandLine library allows for <a
				237	href="#positional">positional</a> arguments to be specified for the program.
				238	These positional arguments are filled with command line parameters that are not
				239	in option form. We use this feature like this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	240
				241	<pre>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	242	<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>"));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	243	</pre>
				244
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	245	This declaration indicates that the first positional argument should be treated
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	246	as the input filename. Here we use the <tt><a
				247	href="#cl::init">cl::init</a></tt> option to specify an initial value for the
				248	command line option, which is used if the option is not specified (if you do not
				249	specify a <tt><a href="#cl::init">cl::init</a></tt> modifier for an option, then
				250	the default constructor for the data type is used to initialize the value).
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	251	Command line options default to being optional, so if we would like to require
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	252	that the user always specify an input filename, we would add the <tt><a
				253	href="#cl::Required">cl::Required</a></tt> flag, and we could eliminate the
				254	<tt><a href="#cl::init">cl::init</a></tt> modifier, like this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	255
				256	<pre>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	257	<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>);
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	258	</pre>
				259
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	260	Again, the CommandLine library does not require the options to be specified in
				261	any particular order, so the above declaration is equivalent to:<p>
				262
				263	<pre>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	264	<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>"));
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	265	</pre>
				266
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	267	By simply adding the <tt><a href="#cl::Required">cl::Required</a></tt> flag, the
				268	CommandLine library will automatically issue an error if the argument is not
				269	specified, which shifts all of the command line option verification code out of
				270	your application into the library. This is just one example of how using flags
				271	can alter the default behaviour of the library, on a per-option basis. By
				272	adding one of the declarations above, the <tt>--help</tt> option synopsis is now
				273	extended to:<p>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	274
				275	<pre>
				276	USAGE: compiler [options] <input file>
				277
				278	OPTIONS:
				279	-help - display available options (--help-hidden for more)
				280	-o <filename> - Specify output filename
				281	</pre>
				282
				283	... indicating that an input filename is expected.<p>
				284
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	285
				286	<!-- ======================================================================= -->
				287	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	288	<a name="bool">Boolean Arguments
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	289	</b></font></td></tr></table><ul>
				290
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	291	In addition to input and output filenames, we would like the compiler example to
				292	support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
				293	file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
				294	compatibility with some of our users. We can support these by declaring options
				295	of boolean type like this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	296
				297	<pre>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	298	<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
				299	<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>"));
				300	<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>);
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	301	</pre><p>
				302
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	303	This does what you would expect: it declares three boolean variables
				304	("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	305	options. Note that the "<tt>-q</tt>" option is specified with the "<a
				306	href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it
				307	from being shown by the standard "<tt>--help</tt>" output (note that it is still
				308	shown in the "<tt>--help-hidden</tt>" output).<p>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	309
				310	The CommandLine library uses a different parser for different data types. For
				311	example, in the string case, the argument passed to the option is copied
				312	literally into the content of the string variable... we obviously cannot do that
				313	in the boolean case, however, so we must use a smarter parser. In the case of
				314	the boolean parser, it allows no options (in which case it assigns the value of
				315	true to the variable), or it allows the values "<tt>true</tt>" or
				316	"<tt>false</tt>" to be specified, allowing any of the following inputs:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	317
				318	<pre>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	319	compiler -f # No value, 'Force' == true
				320	compiler -f=true # Value specified, 'Force' == true
				321	compiler -f=TRUE # Value specified, 'Force' == true
				322	compiler -f=FALSE # Value specified, 'Force' == false
				323	</pre>
				324
				325	... you get the idea. The bool parser just turns the string values into boolean
				326	values, and rejects things like '<tt>compiler -f=foo</tt>'. Similarly, the
				327	float, double, and int parsers work like you would expect, using the
				328	'<tt>strtol</tt>' and '<tt>strtod</tt>' C library calls to parse the string
				329	value into the specified data type.<p>
				330
				331	With the declarations above, "<tt>compiler --help</tt>" emits this:<p>
				332
				333	<pre>
				334	USAGE: compiler [options] <input file>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	335
				336	OPTIONS:
				337	-f - Overwrite output files
				338	-o - Override output filename
				339	-quiet - Don't print informational messages
				340	-help - display available options (--help-hidden for more)
				341	</pre><p>
				342
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	343	and "<tt>opt --help-hidden</tt>" prints this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	344
				345	<pre>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	346	USAGE: opt [options] <input file>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	347
				348	OPTIONS:
				349	-f - Overwrite output files
				350	-o - Override output filename
				351	-q - Don't print informational messages
				352	-quiet - Don't print informational messages
				353	-help - display available options (--help-hidden for more)
				354	</pre><p>
				355
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	356	This brief example has shown you how to use the '<tt><a
				357	href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line
				358	arguments. In addition to simple scalar arguments, the CommandLine library also
				359	provides primitives to support CommandLine option <a href="#alias">aliases</a>,
				360	and <a href="#list">lists</a> of options.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	361
				362
				363	<!-- ======================================================================= -->
				364	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	365	<a name="alias">Argument Aliases
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	366	</b></font></td></tr></table><ul>
				367
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	368	So far, the example works well, except for the fact that we need to check the
				369	quiet condition like this now:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	370
				371	<pre>
				372	...
				373	if (!Quiet && !Quiet2) printInformationalMessage(...);
				374	...
				375	</pre><p>
				376
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	377	... which is a real pain! Instead of defining two values for the same
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	378	condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	379	option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
				380	a value itself:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	381
				382	<pre>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	383	<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
				384	<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>"));
				385	<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));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	386	</pre><p>
				387
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	388	The third line (which is the only one we modified from above) defines a
				389	"<tt>-q</tt> alias that updates the "<tt>Quiet</tt>" variable (as specified by
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	390	the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is
				391	specified. Because aliases do not hold state, the only thing the program has to
				392	query is the <tt>Quiet</tt> variable now. Another nice feature of aliases is
				393	that they automatically hide themselves from the <tt>-help</tt> output
				394	(although, again, they are still visible in the <tt>--help-hidden
				395	output</tt>).<p>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	396
				397	Now the application code can simply use:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	398
				399	<pre>
				400	...
				401	if (!Quiet) printInformationalMessage(...);
				402	...
				403	</pre><p>
				404
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	405	... which is much nicer! The "<tt><a href="#cl::alias">cl::alias</a></tt>" can be used to specify an
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	406	alternative name for any variable type, and has many uses.<p>
				407
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	408
				409
				410	<!-- ======================================================================= -->
				411	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	412	<a name="onealternative">Selecting an alternative from a set of possibilities
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	413	</b></font></td></tr></table><ul>
				414
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	415	So far, we have seen how the CommandLine library handles builtin types like
				416	<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
				417	things it doesn't know about, like enums or '<tt>int*</tt>'s?<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	418
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	419	The answer is that it uses a table driven generic parser (unless you specify
				420	your own parser, as described in the <a href="#extensionguide">Extension
				421	Guide</a>). This parser maps literal strings to whatever type is required, are
				422	requires you to tell it what this mapping should be.<p>
				423
				424	Lets say that we would like to add four optimizations levels to our optimizer,
				425	using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>", "<tt>-O1</tt>", and
				426	"<tt>-O2</tt>". We could easily implement this with boolean options like above,
				427	but there are several problems with this strategy:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	428
				429	<ol>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	430	<li>A user could specify more than one of the options at a time, for example,
				431	"<tt>opt -O3 -O2</tt>". The CommandLine library would not be able to catch this
				432	erroneous input for us.
				433
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	434	<li>We would have to test 4 different variables to see which ones are set.
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	435
				436	<li>This doesn't map to the numeric levels that we want... so we cannot easily
				437	see if some level >= "<tt>-O1</tt>" is enabled.
				438
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	439	</ol><p>
				440
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	441	To cope with these problems, we can use an enum value, and have the CommandLine
				442	library fill it in with the appropriate level directly, which is used like
				443	this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	444
				445	<pre>
				446	enum OptLevel {
				447	g, O1, O2, O3
				448	};
				449
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	450	<a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
				451	<a href="#cl::values">cl::values</a>(
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	452	clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
				453	clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
				454	clEnumVal(O2, "<i>Enable default optimizations</i>"),
				455	clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
				456	0));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	457
				458	...
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	459	if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	460	...
				461	</pre><p>
				462
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	463	This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
				464	"<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
				465	that are listed in the declaration (Note that the declaration list must be
				466	terminated with the "<tt>0</tt>" argument!). The CommandLine library enforces
				467	that the user can only specify one of the options, and it ensure that only valid
				468	enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	469	command line arguments matched the enum values. With this option added, our
				470	help output now is:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	471
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	472	<pre>
				473	USAGE: compiler [options] <input file>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	474
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	475	OPTIONS:
				476	Choose optimization level:
				477	-g - No optimizations, enable debugging
				478	-O1 - Enable trivial optimizations
				479	-O2 - Enable default optimizations
				480	-O3 - Enable expensive optimizations
				481	-f - Overwrite output files
				482	-help - display available options (--help-hidden for more)
				483	-o <filename> - Specify output filename
				484	-quiet - Don't print informational messages
				485	</pre>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	486
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	487	In this case, it is sort of awkward that flag names correspond directly to enum
				488	names, because we probably don't want a enum definition named "<tt>g</tt>" in
				489	our program. Because of this, we can alternatively write this example like
				490	this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	491
				492	<pre>
				493	enum OptLevel {
				494	Debug, O1, O2, O3
				495	};
				496
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	497	<a href="#cl::opt">cl::opt</a><OptLevel> OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
				498	<a href="#cl::values">cl::values</a>(
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	499	clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
				500	clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
				501	clEnumVal(O2 , "<i>Enable default optimizations</i>"),
				502	clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
				503	0));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	504
				505	...
				506	if (OptimizationLevel == Debug) outputDebugInfo(...);
				507	...
				508	</pre><p>
				509
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	510	By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we can
				511	directly specify the name that the flag should get. In general a direct mapping
				512	is nice, but sometimes you can't or don't want to preserve the mapping, which is
				513	when you would use it.<p>
				514
				515
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	516
				517	<!-- ======================================================================= -->
				518	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				519	<a name="namedalternatives">Named Alternatives
				520	</b></font></td></tr></table><ul>
				521
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	522	Another useful argument form is a named alternative style. We shall use this
				523	style in our compiler to specify different debug levels that can be used.
				524	Instead of each debug level being its own switch, we want to support the
				525	following options, of which only one can be specified at a time:
				526	"<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
				527	"<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
				528	our optimization level flags, but we also specify an option name. For this
				529	case, the code looks like this:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	530
				531	<pre>
				532	enum DebugLev {
				533	nodebuginfo, quick, detailed
				534	};
				535
				536	// Enable Debug Options to be specified on the command line
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	537	<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>"),
				538	<a href="#cl::values">cl::values</a>(
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	539	clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
				540	clEnumVal(quick, "<i>enable quick debug information</i>"),
				541	clEnumVal(detailed, "<i>enable detailed debug information</i>"),
				542	0));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	543	</pre>
				544
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	545	This definition defines an enumerated command line variable of type "<tt>enum
				546	DebugLev</tt>", which works exactly the same way as before. The difference here
				547	is just the interface exposed to the user of your program and the help output by
				548	the "<tt>--help</tt>" option:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	549
				550	<pre>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	551	USAGE: compiler [options] <input file>
				552
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	553	OPTIONS:
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	554	Choose optimization level:
				555	-g - No optimizations, enable debugging
				556	-O1 - Enable trivial optimizations
				557	-O2 - Enable default optimizations
				558	-O3 - Enable expensive optimizations
				559	-debug_level - Set the debugging level:
				560	=none - disable debug information
				561	=quick - enable quick debug information
				562	=detailed - enable detailed debug information
				563	-f - Overwrite output files
				564	-help - display available options (--help-hidden for more)
				565	-o <filename> - Specify output filename
				566	-quiet - Don't print informational messages
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	567	</pre><p>
				568
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	569	Again, the only structural difference between the debug level declaration and
				570	the optimiation level declaration is that the debug level declaration includes
				571	an option name (<tt>"debug_level"</tt>), which automatically changes how the
				572	library processes the argument. The CommandLine library supports both forms so
				573	that you can choose the form most appropriate for your application.<p>
				574
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	575
				576
				577	<!-- ======================================================================= -->
				578	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	579	<a name="list">Parsing a list of options
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	580	</b></font></td></tr></table><ul>
				581
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	582	Now that we have the standard run of the mill argument types out of the way,
				583	lets get a little wild and crazy. Lets say that we want our optimizer to accept
				584	a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
				585	might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
				586	this case, the order of the arguments and the number of appearances is very
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	587	important. This is what the "<tt><a href="#cl::list">cl::list</a></tt>"
				588	template is for. First, start by defining an enum of the optimizations that you
				589	would like to perform:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	590
				591	<pre>
				592	enum Opts {
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	593	// 'inline' is a C++ keyword, so name it 'inlining'
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	594	dce, constprop, inlining, strip
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	595	};
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	596	</pre><p>
				597
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	598	Then define your "<tt><a href="#cl::list">cl::list</a></tt>" variable:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	599
				600	<pre>
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	601	<a href="#cl::list">cl::list</a><Opts> OptimizationList(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
				602	<a href="#cl::values">cl::values</a>(
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	603	clEnumVal(dce , "<i>Dead Code Elimination</i>"),
				604	clEnumVal(constprop , "<i>Constant Propogation</i>"),
				605	clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
				606	clEnumVal(strip , "<i>Strip Symbols</i>"),
				607	0));
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	608	</pre><p>
				609
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	610	This defines a variable that is conceptually of the type
				611	"<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
				612	vector methods:<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	613
				614	<pre>
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	615	for (unsigned i = 0; i != OptimizationList.size(); ++i)
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	616	switch (OptimizationList[i])
				617	...
				618	</pre>
				619
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	620	... to iterate through the list of options specified.<p>
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	621
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	622	Note that the "<tt><a href="#cl::list">cl::list</a></tt>" template is completely general and may be used
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	623	with any data types or other arguments that you can use with the
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	624	"<tt><a href="#cl::opt">cl::opt</a></tt>" template. One especially useful way to use a list is to
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	625	capture all of the positional arguments together if there may be more than one
				626	specified. In the case of a linker, for example, the linker takes several
				627	'<tt>.o</tt>' files, and needs to capture them into a list. This is naturally
				628	specified as:<p>
Chris Lattner	3e5fe17	2002-04-13 18:35:59 +0000	[diff] [blame]	629
				630	<pre>
				631	...
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	632	<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>);
Chris Lattner	3e5fe17	2002-04-13 18:35:59 +0000	[diff] [blame]	633	...
				634	</pre><p>
				635
Chris Lattner	ae85363	2002-07-25 19:27:01 +0000	[diff] [blame]	636	This variable works just like a "<tt>vector<string></tt>" object. As
				637	such, accessing the list is simple, just like above. In this example, we used
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	638	the <tt><a href="#cl::OneOrMore">cl::OneOrMore</a></tt> modifier to inform the
				639	CommandLine library that it is an error if the user does not specify any
				640	<tt>.o</tt> files on our command line. Again, this just reduces the amount of
				641	checking we have to do.<p>
Chris Lattner	3e5fe17	2002-04-13 18:35:59 +0000	[diff] [blame]	642
Chris Lattner	3e5fe17	2002-04-13 18:35:59 +0000	[diff] [blame]	643
				644
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	645	<!-- *********************************************************************** -->
				646	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				647	<a name="referenceguide">Reference Guide
				648	</b></font></td></tr></table><ul>
				649	<!-- *********************************************************************** -->
				650
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	651	Now that you know the basics of how to use the CommandLine library, this section
				652	will give you the detailed information you need to tune how command line options
				653	work, as well as information on more "advanced" command line option processing
				654	capabilities.<p>
				655
				656
				657	<!-- ======================================================================= -->
				658	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				659	<a name="positional">Positional Arguments
				660	</b></font></td></tr></table><ul>
				661
				662	Positional arguments are those arguments that are not named, and are not
				663	specified with a hyphen. Positional arguments should be used when an option is
				664	specified by its position alone. For example, the standard Unix <tt>grep</tt>
				665	tool takes a regular expression argument, and an optional filename to search
				666	through (which defaults to standard input if a filename is not specified).
				667	Using the CommandLine library, this would be specified as:<p>
				668
				669	<pre>
				670	<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>);
				671	<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>"));
				672	</pre>
				673
				674	Given these two option declarations, the <tt>--help</tt> output for our grep
				675	replacement would look like this:<p>
				676
				677	<pre>
				678	USAGE: spiffygrep [options] <regular expression> <input file>
				679
				680	OPTIONS:
				681	-help - display available options (--help-hidden for more)
				682	</pre>
				683
				684	... and the resultant program could be used just like the standard <tt>grep</tt>
				685	tool.<p>
				686
				687	Positional arguments are sorted by their order of construction. This means that
				688	command line options will be ordered according to how they are listed in a .cpp
				689	file, but will not have an ordering defined if they positional arguments are
				690	defined in multiple .cpp files. The fix for this problem is simply to define
				691	all of your positional arguments in one .cpp file.<p>
				692
				693
				694
				695	<!-- _______________________________________________________________________ -->
				696	</ul><a name="--"><h4><hr size=0>Specifying positional options with hyphens</h4><ul>
				697
				698	Sometimes you may want to specify a value to your positional argument that
				699	starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
				700	first, you will have trouble doing this, because it will try to find an argument
				701	named '<tt>-foo</tt>', and will fail (and single quotes will not save you).
				702	Note that the system <tt>grep</tt> has the same problem:<p>
				703
				704	<pre>
				705	$ spiffygrep '-foo' test.txt
				706	Unknown command line argument '-foo'. Try: spiffygrep --help'
				707
				708	$ grep '-foo' test.txt
				709	grep: illegal option -- f
				710	grep: illegal option -- o
				711	grep: illegal option -- o
				712	Usage: grep -hblcnsviw pattern file . . .
				713	</pre><p>
				714
				715	The solution for this problem is the same for both your tool and the system
				716	version: use the '<tt>--</tt>' marker. When the user specifies '<tt>--</tt>' on
				717	the command line, it is telling the program that all options after the
				718	'<tt>--</tt>' should be treated as positional arguments, not options. Thus, we
				719	can use it like this:<p>
				720
				721	<pre>
				722	$ spiffygrep -- -foo test.txt
				723	...output...
				724	</pre><p>
				725
				726
				727
				728	<!-- _______________________________________________________________________ -->
				729	</ul><a name="cl::ConsumeAfter"><h4><hr size=0>The <tt>cl::ConsumeAfter</tt> modifier</h4><ul>
				730
				731	The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
				732	used to construct programs that use "interpreter style" option processing. With
				733	this style of option processing, all arguments specified after the last
				734	positional argument are treated as special interpreter arguments that are not
				735	interpreted by the command line argument.<p>
				736
				737	As a concrete example, lets say we are developing a replacement for the standard
				738	Unix Bourne shell (<tt>/bin/sh</tt>). To run <tt>/bin/sh</tt>, first you
				739	specify options to the shell itself (like <tt>-x</tt> which turns on trace
				740	output), then you specify the name of the script to run, then you specify
				741	arguments to the script. These arguments to the script are parsed by the bourne
				742	shell command line option processor, but are not interpreted as options to the
				743	shell itself. Using the CommandLine library, we would specify this as:<p>
				744
				745	<pre>
				746	<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>("-"));
				747	<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>"));
				748	<a href="#cl::opt">cl::opt</a><bool> Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
				749	</pre><p>
				750
				751	which automatically provides the help output:<p>
				752
				753	<pre>
				754	USAGE: spiffysh [options] <input script> <program arguments>...
				755
				756	OPTIONS:
				757	-help - display available options (--help-hidden for more)
				758	-x - Enable trace output
				759	</pre><p>
				760
				761	At runtime, if we run our new shell replacement as '<tt>spiffysh -x test.sh -a
				762	-x -y bar</tt>', the <tt>Trace</tt> variable will be set to true, the
				763	<tt>Script</tt> variable will be set to "<tt>test.sh</tt>", and the
				764	<tt>Argv</tt> list will contain <tt>["-a", "-x", "-y", "bar"]</tt>, because
				765	they were specified after the last positional argument (which is the script
				766	name).<p>
				767
				768	There are several limitations to when <tt>cl::ConsumeAfter</tt> options can be
				769	specified. For example, only one <tt>cl::ConsumeAfter</tt> can be specified per
				770	program, there must be at least one <a href="#positional">positional
				771	argument</a> specified, and the <tt>cl::ConsumeAfter</tt> option should be a <a
				772	href="#cl::list">cl::list</a> option.<p>
				773
				774
				775
				776	<!-- ======================================================================= -->
				777	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				778	<a name="storage">Internal vs External Storage
				779	</b></font></td></tr></table><ul>
				780
				781	By default, all command line options automatically hold the value that they
				782	parse from the command line. This is very convenient in the common case,
				783	especially when combined with the ability to define command line options in the
				784	files that use them. This is called the internal storage model.<p>
				785
				786	Sometimes, however, it is nice to separate the command line option processing
				787	code from the storage of the value parsed. For example, lets say that we have a
				788	'<tt>-debug</tt>' option that we would like to use to enable debug information
				789	across the entire body of our program. In this case, the boolean value
				790	controlling the debug code should be globally accessable (in a header file, for
				791	example) yet the command line option processing code should not be exposed to
				792	all of these clients (requiring lots of .cpp files to #include
				793	<tt>CommandLine.h</tt>).<p>
				794
				795	To do this, set up your .h file with your option, like this for example:<p>
				796
				797	<pre>
				798	<i>// DebugFlag.h - Get access to the '-debug' command line option
				799	//
				800
				801	// DebugFlag - This boolean is set to true if the '-debug' command line option
				802	// is specified. This should probably not be referenced directly, instead, use
				803	// the DEBUG macro below.
				804	//</i>
				805	extern bool DebugFlag;
				806
				807	<i>// DEBUG macro - This macro should be used by code to emit debug information.
				808	// In the '-debug' option is specified on the command line, and if this is a
				809	// debug build, then the code specified as the option to the macro will be
				810	// executed. Otherwise it will not be. Example:
				811	//
				812	// DEBUG(cerr << "Bitset contains: " << Bitset << "\n");
				813	//</i>
				814	<font color=red>#ifdef NDEBUG
				815	#define DEBUG(X)
				816	#else
				817	#define DEBUG(X)</font> \
				818	do { if (DebugFlag) { X; } } while (0)
				819	<font color=red>#endif</font>
				820	</pre>
				821
				822	This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
				823	<tt>DebugFlag</tt> explicitly if they want to. Now we just need to be able to
				824	set the <tt>DebugFlag</tt> boolean when the option is set. To do this, we pass
				825	an additial argument to our command line argument processor, and we specify
				826	where to fill in with the <a href="#cl::location">cl::location</a> attribute:<p>
				827
				828	<pre>
				829	bool DebugFlag; <i>// the actual value</i>
				830	static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
				831	Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>")</a>, <a href="#cl::Hidden">cl::Hidden</a>,
				832	<a href="#cl::location">cl::location</a>(DebugFlag));
				833	</pre>
				834
				835	In the above example, we specify "<tt>true</tt>" as the second argument to the
				836	<a href="#cl::opt">cl::opt</a> template, indicating that the template should not
				837	maintain a copy of the value itself. In addition to this, we specify the <a
				838	href="#cl::location">cl::location</a> attribute, so that <tt>DebugFlag</tt> is
				839	automatically set.<p>
				840
				841
				842
				843	<!-- ======================================================================= -->
				844	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				845	<a name="attributes">Option Attributes
				846	</b></font></td></tr></table><ul>
				847
				848	This section describes the basic attributes that you can specify on options.<p>
				849
				850	<ul>
				851
				852	<li>The option name attribute (which is required for all options, except <a
				853	href="#positional">positional options</a>) specifies what the option name is.
				854	This option is specified in simple double quotes:<p>
				855
				856	<a href="#cl::opt">cl::opt</a><bool> Quiet("<i>quiet</i>");<p>
				857
				858	<li><a name="cl::desc">The <b><tt>cl::desc</tt></b> attribute specifies a
				859	description for the option to be shown in the <tt>--help</tt> output for the
				860	program.<p>
				861
				862	<li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b> attribute
				863	specifies a string that can be used to fine tune the <tt>--help</tt> output for
				864	a command line option. Look <a href="#value_desc_example">here</a> for an
				865	example.<p>
				866
				867	<li><a name="cl::init">The <b><tt>cl::init</tt></b> attribute specifies an
				868	inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is
				869	not specified then the command line option value defaults to the value created
				870	by the default constructor for the type.<p>
				871
				872	<li><a name="cl::location">The <b><tt>cl::location</tt></b> attribute where to
				873	store the value for a parsed command line option if using external storage. See
				874	the section on <a href="#storage">Internal vs External Storage</a> for more
				875	information.<p>
				876
				877	<li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b> attribute specifies
				878	which option a <a href="#cl::alias">cl::alias</a> option is an alias for.<p>
				879
				880	<li><a name="cl::values">The <b><tt>cl::values</tt></b> attribute specifies the
				881	string-to-value mapping to be used by the generic parser. It takes a <b>null
				882	terminated</b> list of (option, value, description) triplets that specify the
				883	option name, the value mapped to, and the description shown in the
				884	<tt>--help</tt> for the tool. Because the generic parser is used most frequently with enum values, two macros are often useful:<p>
				885	<ol>
				886	<li><a name="clEnumVal">The <b><tt>clEnumVal</tt></b> macro is used as a nice
				887	simple way to specify a triplet for an enum. This macro automatically makes the
				888	option name be the same as the enum name. The first option to the macro is the
				889	enum, the second is the description for the command line option.<p> <li><a
				890	name="clEnumValN">The <b><tt>clEnumValN</tt></b> macro is used to specify macro
				891	options where the option name doesn't equal the enum name. For this macro, the
				892	first argument is the enum value, the second is the flag name, and the second is
				893	the description.<p>
				894	</ol>
				895
				896	You will get a compile time error if you try to use cl::values with a parser
				897	that does not support it.<p>
				898
				899	</ul>
				900
				901
				902
				903	<!-- ======================================================================= -->
				904	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				905	<a name="modifiers">Option Modifiers
				906	</b></font></td></tr></table><ul>
				907
				908	Option modifiers are the flags and expressions that you pass into the
				909	constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				910	href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
				911	tweak how options are parsed and how <tt>--help</tt> output is generated to fit
				912	your application well.<p>
				913
				914	These options naturally fall into four main catagories:<p>
				915
				916	<ol>
				917	<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a>
				918	<li><a href="#numoccurances">Controlling the number of occurances
				919	required and allowed</a>
				920	<li><a href="#valrequired">Controlling whether or not a value must be
				921	specified</a>
				922	<li><a href="#formatting">Controlling other formatting options</a>
				923	</ol><p>
				924
				925	It is not possible to specify two options from the same catagory (you'll get a
				926	runtime error) to a single option. The CommandLine library specifies defaults
				927	for all of these settings that are the most useful in practice and the most
				928	common, which mean that you usually shouldn't have to worry about these.<p>
				929
				930
				931	<!-- _______________________________________________________________________ -->
				932	</ul><a name="hiding"><h4><hr size=0>Hiding an option from <tt>--help</tt> output</h4><ul>
				933
				934	The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and <tt>cl::ReallyHidden</tt>
				935	modifiers are used to control whether or not an option appears in the
				936	<tt>--help</tt> and <tt>--help-hidden</tt> output for the compiled program:<p>
				937
				938	<ul>
				939
				940	<a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b> modifier (which is the
				941	default for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				942	href="#cl::list">cl::list</a></tt> options), indicates the option is to appear
				943	in both help listings.<p>
				944
				945	<a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b> modifier (which is the
				946	default for <tt><a href="#cl::alias">cl::alias</a></tt> options), indicates that
				947	the option should not appear in the <tt>--help</tt> output, but should appear in
				948	the <tt>--help-hidden</tt> output.<p>
				949
				950	<a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b> modifier,
				951	indicates that the option should not appear in any help output.<p>
				952	</ul>
				953
				954	<!-- _______________________________________________________________________ -->
				955	</ul><a name="numoccurances"><h4><hr size=0>Controlling the number of occurances required and allowed</h4><ul>
				956
				957	This group of options is used to control how many time an option is allowed (or
				958	required) to be specified on the command line of your program. Specifying a
				959	value for this setting allows the CommandLine library to do error checking for
				960	you.<p>
				961
				962	The allowed values for this option group are:<p>
				963
				964	<ul>
				965	<a name="cl::Optional">The <b><tt>cl::Optional</tt></b> modifier (which is the
				966	default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
				967	href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will
				968	allow either zero or one occurance of the option to be specified.<p>
				969
				970	<a name="cl::ZeroOrMore">The <b><tt>cl::ZeroOrMore</tt></b> modifier (which is
				971	the default for the <tt><a href="#cl::list">cl::list</a></tt> class) indicates
				972	that your program will allow the option to be specified zero or more times.<p>
				973
				974	<a name="cl::Required">The <b><tt>cl::Required</tt></b> modifier indicates that
				975	the specified option must be specified exactly one time.<p>
				976
				977	<a name="cl::OneOrMore">The <b><tt>cl::OneOrMore</tt></b> modifier indicates
				978	that the option must be specified at least one time.<p>
				979
				980	The <b><tt>cl::ConsumeAfter</tt></b> modifier is described in the <a
				981	href="#positional">Positional arguments section</a><p>
				982
				983	</ul>
				984
				985	If an option is not specified, then the value of the option is equal to the
				986	value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute. If
				987	the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the
				988	option value is initialized with the default constructor for the data type.<p>
				989
				990	If an option is specified multiple times for an option of the <tt><a
				991	href="#cl::opt">cl::opt</a></tt> class, only the last value will be retained.<p>
				992
				993
				994	<!-- _______________________________________________________________________ -->
				995	</ul><a name="valrequired"><h4><hr size=0>Controlling whether or not a value must be specified</h4><ul>
				996
				997	This group of options is used to control whether or not the option allows a
				998	value to be present. In the case of the CommandLine library, a value is either
				999	specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing
				1000	string (e.g. '<tt>-o a.out</tt>').<p>
				1001
				1002	The allowed values for this option group are:<p>
				1003
				1004	<ul>
				1005	<a name="cl::ValueOptional">The <b><tt>cl::ValueOptional</tt></b> modifier
				1006	(which is the default for <tt>bool</tt> typed options) specifies that it is
				1007	acceptable to have a value, or not. A boolean argument can be enabled just by
				1008	appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'.
				1009	If an option is specified with this mode, it is illegal for the value to be
				1010	provided without the equal sign. Therefore '<tt>-foo true</tt>' is illegal. To
				1011	get this behavior, you must use the <a
				1012	href="#cl::ValueRequired">cl::ValueRequired</a> modifier.<p>
				1013
				1014	<a name="cl::ValueRequired">The <b><tt>cl::ValueRequired</tt></b> modifier
				1015	(which is the default for all other types except for <a
				1016	href="#onealternative">unnamed alternatives using the generic parser</a>)
				1017	specifies that a value must be provided. This mode informs the command line
				1018	library that if an option is not provides with an equal sign, that the next
				1019	argument provided must be the value. This allows things like '<tt>-o
				1020	a.out</tt>' to work.<p>
				1021
				1022	<a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b> modifier
				1023	(which is the default for <a href="#onealternative">unnamed alternatives using
				1024	the generic parser</a>) indicates that it is a runtime error for the user to specify a value. This can be provided to disallow users from providing options to boolean options (like '<tt>-foo=true</tt>').<p>
				1025
				1026	</ul>
				1027
				1028	In general, the default values for this option group work just like you would
				1029	want them to. As mentioned above, you can specify the <a
				1030	href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean
				1031	argument to restrict your command line parser. These options are mostly useful
				1032	when <a href="#extensionguide">extending the library</a>.<p>
				1033
				1034
				1035
				1036	<!-- _______________________________________________________________________ -->
				1037	</ul><a name="formatting"><h4><hr size=0>Controlling other formatting options</h4><ul>
				1038
				1039	The formatting option group is used to specify that the command line option has
				1040	special abilities and is otherwise different from other command line arguments.
				1041	As usual, you can only specify at most one of these arguments.<p>
				1042
				1043	<ul>
				1044	<a name="cl::NormalFormatting">The <b><tt>cl::NormalFormatting</tt></b> modifier
				1045	(which is the default all options) specifies that this option is "normal".<p>
				1046
				1047	<a name="cl::Positional">The <b><tt>cl::Positional</tt></b> modifier specifies
				1048	that this is a positional argument, that does not have a command line option
				1049	associated with it. See the <a href="#positional">Positional Arguments</a>
				1050	section for more information.<p>
				1051
				1052	The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier
				1053	specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.<p>
				1054
				1055
				1056	<a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b> modifier specifies that this
				1057	option prefixes its value. With 'Prefix' options, there is no equal sign that
				1058	seperates the value from the option name specified. This is useful for
				1059	processing odd arguments like '<tt>-lmalloc -L/usr/lib'</tt> in a linker tool.
				1060	Here, the '<tt>l</tt>' and '<tt>L</tt>' options are normal string (list)
				1061	options, that have the <a href="#cl::Prefix">cl::Prefix</a> modifier added to
				1062	allow the CommandLine library to recognize them. Note that <a
				1063	href="#cl::Prefix">cl::Prefix</a> options must not have the <a
				1064	href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier specified.<p>
				1065
				1066	<a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b> modifier is used to
				1067	implement unix style tools (like <tt>ls</tt>) that have lots of single letter
				1068	arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
				1069	command actually enables four different options, all of which are single
				1070	letters. Note that <a href="#cl::Grouping">cl::Grouping</a> options cannot have
				1071	values.<p>
				1072
				1073	</ul>
				1074
				1075	The CommandLine library does not restrict how you use the <a
				1076	href="#cl::Prefix">cl::Prefix</a> or <a href="#cl::Grouping">cl::Grouping</a>
				1077	modifiers, but it is possible to specify ambiguous argument settings. Thus, it
				1078	is possible to have multiple letter options that are prefix or grouping options,
				1079	and they will still work as designed.<p>
				1080
				1081	To do this, the CommandLine library uses a greedy algorithm to parse the input
				1082	option into (potentially multiple) prefix and grouping options. The strategy
				1083	basically looks like this:<p>
				1084
				1085	<tt>parse(string OrigInput) {</tt>
				1086	<ol>
				1087	<li><tt>string input = OrigInput;</tt>
				1088	<li><tt>if (isOption(input)) return getOption(input).parse();</tt>    <i>// Normal option</i>
				1089	<li><tt>while (!isOption(input) && !input.empty()) input.pop_back();</tt>    <i>// Remove the last letter</i>
				1090	<li><tt>if (input.empty()) return error();</tt>    <i>// No matching option</i>
				1091	<li><tt>if (getOption(input).isPrefix())<br>
				1092	return getOption(input).parse(input);</tt>
				1093	<li><tt>while (!input.empty()) {    <i>// Must be grouping options</i><br>
				1094	getOption(input).parse();<br>
				1095	OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());<br>
				1096	input = OrigInput;<br>
				1097	while (!isOption(input) && !input.empty()) input.pop_back();<br>
				1098	}</tt>
				1099	<li><tt>if (!OrigInput.empty()) error();</tt>
				1100	</tt>
				1101
				1102	</ol>
				1103	<tt>}</tt><p>
				1104
				1105
				1106	<!-- ======================================================================= -->
				1107	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				1108	<a name="optionclasses">Option Classes
				1109	</b></font></td></tr></table><ul>
				1110
				1111	Despite all of the builtin flexibility, the CommandLine option library really
				1112	only consists of three main classes: <a href="#cl::opt">cl::opt</a>, <a
				1113	href="#cl::list">cl::list</a>, and <a href="#cl::alias">cl::alias</a>. This
				1114	section describes these three classes in detail.<p>
				1115
				1116	<!-- _______________________________________________________________________ -->
				1117	</ul><a name="cl::opt"><h4><hr size=0>The <tt>cl::opt</tt> class</h4><ul>
				1118
				1119	The <tt>cl::opt</tt> class is the class used to represent scalar command line
				1120	options, and is the one used most of the time. It is a templated class which
				1121	can take up to three arguments (all except for the first have default values
				1122	though):<p>
				1123
				1124	<pre>
				1125	namespace cl {
				1126	template <class DataType, bool ExternalStorage = false,
				1127	class ParserClass = parser<DataType> >
				1128	class opt;
				1129	}
				1130	</pre><p>
				1131
				1132	The first template argument specifies what underlying data type the command line
				1133	argument is, and is used to select a default parser implementation. The second
				1134	template argument is used to specify whether the option should contain the
				1135	storage for the option (the default) or whether external storage should be used
				1136	to contain the value parsed for the option (see <a href="#storage">Internal vs
				1137	External Storage</a> for more information).<p>
				1138
				1139	The third template argument specifies which parser to use. The default value
				1140	selects an instantiation of the <tt>parser</tt> class based on the underlying
				1141	data type of the option. In general, this default works well for most
				1142	applications, so this option is only used when using a <a
				1143	href="#customparser">custom parser</a>.<p>
				1144
				1145
				1146	<!-- _______________________________________________________________________ -->
				1147	</ul><a name="cl::list"><h4><hr size=0>The <tt>cl::list</tt> class</h4><ul>
				1148
				1149	The <tt>cl::list</tt> class is the class used to represent a list of command
				1150	line options. It too is a templated class which can take up to three
				1151	arguments:<p>
				1152
				1153	<pre>
				1154	namespace cl {
				1155	template <class DataType, class Storage = bool,
				1156	class ParserClass = parser<DataType> >
				1157	class list;
				1158	}
				1159	</pre><p>
				1160
				1161	This class works the exact same as the <a href="#cl::opt"><tt>cl::opt</tt></a>
				1162	class, except that the second argument is the <b>type</b> of the external
				1163	storage, not a boolean value. For this class, the marker type '<tt>bool</tt>'
				1164	is used to indicate that internal storage should be used.<p>
				1165
				1166
				1167	<!-- _______________________________________________________________________ -->
				1168	</ul><a name="cl::alias"><h4><hr size=0>The <tt>cl::alias</tt> class</h4><ul>
				1169
				1170	The <tt>cl::alias</tt> class is a nontemplated class that is used to form
				1171	aliases for other arguments.<p>
				1172
				1173	<pre>
				1174	namespace cl {
				1175	class alias;
				1176	}
				1177	</pre></p>
				1178
				1179	The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be used
				1180	to specify which option this is an alias for. Alias arguments default to being
				1181	<a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do the
				1182	conversion from string to data.<p>
				1183
				1184
				1185	<!-- ======================================================================= -->
				1186	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				1187	<a name="builtinparsers">Builtin parsers
				1188	</b></font></td></tr></table><ul>
				1189
				1190	Parsers control how the string value taken from the command line is translated
				1191	into a typed value, suitable for use in a C++ program. By default, the
				1192	CommandLine library uses an instance of <tt>parser<type></tt> if the
				1193	command line option specifies that it uses values of type '<tt>type</tt>'.
				1194	Because of this, custom option processing is specified with specializations of
				1195	the '<tt>parser</tt>' class.<p>
				1196
				1197	The CommandLine library provides the following builtin parser specializations,
				1198	which are sufficient for most applications. It can, however, also be extended to
				1199	work with new data types and new ways of interpreting the same data. See the <a
				1200	href="#customparser">Writing a Custom Parser</a> for more details on this type
				1201	of library extension.<p>
				1202
				1203	<li><a name="genericparser">The <b>generic <tt>parser<t></tt> parser</b>
				1204	can be used to map strings values to any data type, through the use of the <a
				1205	href="#cl::values">cl::values</a> property, which specifies the mapping
				1206	information. The most common use of this parser is for parsing enum values,
				1207	which allows you to use the CommandLine library for all of the error checking to
				1208	make sure that only valid enum values are specified (as opposed to accepting
				1209	arbitrary strings). Despite this, however, the generic parser class can be used
				1210	for any data type.<p>
				1211
				1212	<li><a name="boolparser">The <b><tt>parser<bool></tt> specialization</b>
				1213	is used to convert boolean strings to a boolean value. Currently accepted
				1214	strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
				1215	"<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".<p>
				1216
				1217	<li><a name="stringparser">The <b><tt>parser<string></tt> specialization</b> simply stores the parsed string into the string value specified. No conversion or modification of the data is performed.<p>
				1218
				1219	<li><a name="intparser">The <b><tt>parser<int></tt> specialization</b>
				1220	uses the C <tt>strtol</tt> function to parse the string input. As such, it will
				1221	accept a decimal number (with an optional '+' or '-' prefix) which must start
				1222	with a non-zero digit. It accepts octal numbers, which are identified with a
				1223	'<tt>0</tt>' prefix digit, and hexadecimal numbers with a prefix of
				1224	'<tt>0x</tt>' or '<tt>0X</tt>'.<p>
				1225
				1226	<li><a name="doubleparser">The <b><tt>parser<double></tt></b> and
				1227	<b><tt>parser<float></tt> specializations</b> use the standard C
				1228	<tt>strtod</tt> function to convert floating point strings into floating point
				1229	values. As such, a broad range of string formats is supported, including
				1230	exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
				1231	<p>
				1232
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	1233
				1234
				1235	<!-- *********************************************************************** -->
				1236	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				1237	<a name="extensionguide">Extension Guide
				1238	</b></font></td></tr></table><ul>
				1239	<!-- *********************************************************************** -->
				1240
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	1241	TODO
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	1242
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	1243	<!-- ======================================================================= -->
				1244	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				1245	<a name="customparser">Writing a custom parser
				1246	</b></font></td></tr></table><ul>
				1247
				1248
				1249
				1250	<!-- ======================================================================= -->
				1251	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				1252	<a name="explotingexternal">Exploiting external storage
				1253	</b></font></td></tr></table><ul>
				1254
				1255
				1256
				1257	<!-- ======================================================================= -->
				1258	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				1259	<a name="dynamicopts">Dynamically adding command line options
				1260	</b></font></td></tr></table><ul>
				1261
				1262
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	1263
				1264
				1265
				1266	<!-- *********************************************************************** -->
				1267	</ul>
				1268	<!-- *********************************************************************** -->
				1269
				1270	<hr>
				1271	<font size=-1>
				1272	<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
				1273	<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
				1274	<!-- hhmts start -->
Chris Lattner	e76d4ab	2002-08-06 19:36:06 +0000	[diff] [blame^]	1275	Last modified: Tue Aug 6 14:34:47 CDT 2002
Chris Lattner	209c7f4	2001-07-23 23:03:12 +0000	[diff] [blame]	1276	<!-- hhmts end -->
				1277	</font>
				1278	</body></html>