<li><a href="#valrequired">Controlling whether or not a value must be
specified</a>
<li><a href="#formatting">Controlling other formatting options</a>
+ <li><a href="#misc">Miscellaneous option modifiers</a>
</ul>
<li><a href="#toplevel">Top-Level Classes and Functions</a>
<ul>
<li><a href="#cl::ParseCommandLineOptions">The
<tt>cl::ParseCommandLineOptions</tt> function</a>
+ <li><a href="#cl::ParseEnvironmentOptions">The
+ <tt>cl::ParseEnvironmentOptions</tt> function</a>
<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a>
<li><a href="#cl::list">The <tt>cl::list</tt> class</a>
<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a>
<li>Speed: The CommandLine library is very quick and uses little resources. The
parsing time of the library is directly proportional to the number of arguments
parsed, not the the number of options recognized. Additionally, command line
-argument values are captured transparently into user defined variables, which
-can be accessed like any other variable (and with the same performance).<p>
+argument values are captured transparently into user defined global variables,
+which can be accessed like any other variable (and with the same
+performance).<p>
<li>Type Safe: As a user of CommandLine, you don't have to worry about
remembering the type of arguments that you want (is it an int? a string? a
Now that you are ready to support command line arguments, we need to tell the
system which ones we want, and what type of argument they are. The CommandLine
-library uses a declarative syntax to model cammand line arguments with the
-variable declarations that capture the parsed values. This means that for every
-command line option that you would like to support, there should be a variable
-declaration to capture the result. For example, in a compiler, we would like to
-support the unix standard '<tt>-o <filename></tt>' option to specify where
-to put the output. With the CommandLine library, this is represented like
-this:<p>
+library uses a declarative syntax to model command line arguments with the
+global variable declarations that capture the parsed values. This means that
+for every command line option that you would like to support, there should be a
+global variable declaration to capture the result. For example, in a compiler,
+we would like to support the unix standard '<tt>-o <filename></tt>' option
+to specify where to put the output. With the CommandLine library, this is
+
represented like this:<p>
<pre><a name="value_desc_example">
<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>"));
</pre><p>
-This declares a variable "<tt>OutputFilename</tt>" that is used to capture the
-result of the "<tt>o</tt>" argument (first parameter). We specify that this is
-a simple scalar option by using the "<tt><a href="#cl::opt">cl::opt</a></tt>"
-template (as opposed to the <a href="#list">"<tt>cl::list</tt>
-template</a>), and tell the CommandLine library that the data type that we are
-parsing is a string.<p>
+This declares a global variable "<tt>OutputFilename</tt>" that is used to
+capture the result of the "<tt>o</tt>" argument (first parameter). We specify
+that this is a simple scalar option by using the "<tt><a
+href="#cl::opt">cl::opt</a></tt>" template (as opposed to the <a
+href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
+
that the data type that we are parsing is a string.<p>
The second and third parameters (which are optional) are used to specify what to
output for the "<tt>--help</tt>" option. In this case, we get a line that looks
};
// Enable Debug Options to be specified on the command line
-<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>"),
+<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>"),
<a href="#cl::values">cl::values</a>(
clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
clEnumVal(quick, "<i>enable quick debug information</i>"),
<pre>
bool DebugFlag; <i>// the actual value</i>
-static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
+static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>")</a>, <a href="#cl::Hidden">cl::Hidden</a>,
<a href="#cl::location">cl::location</a>(DebugFlag));
</pre>
<li><a name="cl::init">The <b><tt>cl::init</tt></b> attribute specifies an
inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is
not specified then the command line option value defaults to the value created
-by the default constructor for the type.<p>
+by the default constructor for the type. <b>Warning</b>: If you specify both
+<b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
+you must specify <b><tt>cl::location</tt></b> first, so that when the
+command-line parser sees <b><tt>cl::init</tt></b>, it knows where to put the
+initial value. (You will get an error at runtime if you don't put them in
+the right order.)<p>
<li><a name="cl::location">The <b><tt>cl::location</tt></b> attribute where to
store the value for a parsed command line option if using external storage. See
tweak how options are parsed and how <tt>--help</tt> output is generated to fit
your application well.<p>
-These options
naturally fall into four main catagories:<p>
+These options
fall into five main catagories:<p>
<ol>
<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a>
<li><a href="#valrequired">Controlling whether or not a value must be
specified</a>
<li><a href="#formatting">Controlling other formatting options</a>
+<li><a href="#misc">Miscellaneous option modifiers</a>
</ol><p>
It is not possible to specify two options from the same catagory (you'll get a
-runtime error) to a single option. The CommandLine library specifies defaults
-for all of these settings that are the most useful in practice and the most
-common, which mean that you usually shouldn't have to worry about these.<p>
+runtime error) to a single option, except for options in the miscellaneous
+catagory. The CommandLine library specifies defaults for all of these settings
+that are the most useful in practice and the most common, which mean that you
+usually shouldn't have to worry about these.<p>
<!-- _______________________________________________________________________ -->
<a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b> modifier specifies that this
option prefixes its value. With 'Prefix' options, there is no equal sign that
-seperates the value from the option name specified. This is useful for
+separates the value from the option name specified. This is useful for
processing odd arguments like '<tt>-lmalloc -L/usr/lib'</tt> in a linker tool.
Here, the '<tt>l</tt>' and '<tt>L</tt>' options are normal string (list)
options, that have the <a href="#cl::Prefix">cl::Prefix</a> modifier added to
<tt>}</tt><p>
+
+<!-- _______________________________________________________________________ -->
+</ul><a name="misc"><h4><hr size=0>Miscellaneous option modifiers</h4><ul>
+
+The miscellaneous option modifiers are the only flags where you can specify more
+than one flag from the set: they are not mutually exclusive. These flags
+specify boolean properties that modify the option.<p>
+
+<ul>
+
+<a name="cl::CommaSeparated">The <b><tt>cl::CommaSeparated</tt></b> modifier
+indicates that any commas specified for an option's value should be used to
+split the value up into multiple values for the option. For example, these two
+options are equivalent when <tt>cl::CommaSeparated</tt> is specified:
+"<tt>-foo=a -foo=b -foo=c</tt>" and "<tt>-foo=a,b,c</tt>". This option only
+makes sense to be used in a case where the option is allowed to accept one or
+more values (i.e. it is a <a href="#cl::list">cl::list</a> option).<p>
+</ul>
+
+So far, the only miscellaneous option modifier is the
+<tt>cl::CommaSeparated</tt> modifier.<p>
+
+
<!-- ======================================================================= -->
</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>
<a name="toplevel">Top-Level Classes and Functions
<tt>--help</tt> option is invoked.<p>
+<!-- _______________________________________________________________________ -->
+</ul><a name="cl::ParseEnvironmentOptions"><h4><hr size=0>The
+<tt>cl::ParseEnvironmentOptions</tt> function</h4><ul>
+
+The <tt>cl::ParseEnvironmentOptions</tt>
+function has mostly the same effects as
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
+except that it is designed to take values for options from an
+environment variable, for those cases in which reading the
+command line is not convenient or not desired. It fills in
+the values of all the command line option variables just like
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
+does.<p>
+
+It takes three parameters: first, the name of the program (since <tt>argv</tt>
+may not be available, it can't just look in <tt>argv[0]</tt>), second,
+the name of the environment variable to examine, and third, the optional
+<a href="#description">additional extra text</a> to emit when the
+<tt>--help</tt> option is invoked.<p>
+
+<tt>cl::ParseEnvironmentOptions</tt> will break the environment
+variable's value up into words and then process them using
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+<b>Note:</b> Currently <tt>cl::ParseEnvironmentOptions</tt> does not support
+quoting, so an environment variable containing <tt>-option "foo bar"</tt> will
+be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>,
+which is different from what you would get from the shell with the same
+input.<p>
+
<!-- _______________________________________________________________________ -->
</ul><a name="cl::opt"><h4><hr size=0>The <tt>cl::opt</tt> class</h4><ul>
doesn't work if your fundemental data type is something that is already
supported.<p>
-<li>Write an independant class, using it explicitly from options that need
+<li>Write an independent class, using it explicitly from options that need
it.<p>
This approach works well in situations where you would line to parse an
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
<!-- hhmts start -->
-Last modified: Wed Aug 7 13:22:40 CDT 2002
+Last modified: Fri Aug 1 16:30:11 CDT 2003
<!-- hhmts end -->
</font>
</body></html>
projects / oota-llvm.git / blobdiff