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

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