</head>
<body>
-<div class="doc_title">
+<h1>
CommandLine 2.0 Library Manual
-</div>
+</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="introduction">Introduction</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This document describes the CommandLine argument processing library. It will
show you how to use it, and what it can do. The CommandLine library uses a
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="quickstart">Quick Start Guide</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This section of the manual runs through a simple CommandLine'ification of a
basic compiler tool. This is intended to show you how to jump into using the
<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></div>
-<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
+<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>
<p>The second and third parameters (which are optional) are used to specify what
<p>... indicating that an input filename is expected.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="bool">Boolean Arguments</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>In addition to input and output filenames, we would like the compiler example
to support three boolean flags: "<tt>-f</tt>" to force writing binary output to
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="alias">Argument Aliases</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>So far, the example works well, except for the fact that we need to check the
quiet condition like this now:</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="onealternative">Selecting an alternative from a set of
possibilities</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>So far we have seen how the CommandLine library handles builtin types like
<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="namedalternatives">Named Alternatives</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Another useful argument form is a named alternative style. We shall use this
style in our compiler to specify different debug levels that can be used.
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="list">Parsing a list of options</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Now that we have the standard run-of-the-mill argument types out of the way,
lets get a little wild and crazy. Lets say that we want our optimizer to accept
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="bits">Collecting options as a set of flags</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Instead of collecting sets of options in a list, it is also possible to
-gather information for enum values in a <b>bit vector</b>. The represention used by
+gather information for enum values in a <b>bit vector</b>. The representation used by
the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
integer. An enum value is represented by a 0/1 in the enum's ordinal value bit
position. 1 indicating that the enum was specified, 0 otherwise. As each
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="description">Adding freeform text to help output</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>As our program grows and becomes more mature, we may decide to put summary
information about what it does into the help output. The help output is styled
</div>
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="referenceguide">Reference Guide</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Now that you know the basics of how to use the CommandLine library, this
section will give you the detailed information you need to tune how command line
options work, as well as information on more "advanced" command line option
processing capabilities.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="positional">Positional Arguments</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Positional arguments are those arguments that are not named, and are not
specified with a hyphen. Positional arguments should be used when an option is
are defined in multiple .cpp files. The fix for this problem is simply to
define all of your positional arguments in one .cpp file.</p>
-</div>
-
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="--">Specifying positional options with hyphens</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>Sometimes you may want to specify a value to your positional argument that
starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="getPosition">Determining absolute position with getPosition()</a>
-</div>
-<div class="doc_text">
+</h4>
+<div>
<p>Sometimes an option can affect or modify the meaning of another option. For
example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
<tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
used to construct programs that use "interpreter style" option processing. With
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="storage">Internal vs External Storage</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>By default, all command line options automatically hold the value that they
parse from the command line. This is very convenient in the common case,
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="attributes">Option Attributes</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>This section describes the basic attributes that you can specify on
options.</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="modifiers">Option Modifiers</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Option modifiers are the flags and expressions that you pass into the
constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
that are the most useful in practice and the most common, which mean that you
usually shouldn't have to worry about these.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="hiding">Hiding an option from <tt>-help</tt> output</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="numoccurrences">Controlling the number of occurrences required and
allowed</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>This group of options is used to control how many time an option is allowed
(or required) to be specified on the command line of your program. Specifying a
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="valrequired">Controlling whether or not a value must be specified</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>This group of options is used to control whether or not the option allows a
value to be present. In the case of the CommandLine library, a value is either
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="formatting">Controlling other formatting options</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The formatting option group is used to specify that the command line option
has special abilities and is otherwise different from other command line
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="misc">Miscellaneous option modifiers</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>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
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="response">Response files</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>Some systems, such as certain variants of Microsoft Windows and
some older Unices have a relatively low limit on command-line
</div>
+</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="toplevel">Top-Level Classes and Functions</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Despite all of the built-in flexibility, the CommandLine option library
really only consists of one function (<a
href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
classes in detail.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
function</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
directly from <tt>main</tt>, and is used to fill in the values of all of the
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
function</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
as <a
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
function</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
directly from <tt>main</tt> and <i>before</i>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::opt">The <tt>cl::opt</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
options, and is the one used most of the time. It is a templated class which
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::list">The <tt>cl::list</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::list</tt> class is the class used to represent a list of command
line options. It too is a templated class which can take up to three
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::bits">The <tt>cl::bits</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::bits</tt> class is the class used to represent a list of command
line options in the form of a bit vector. It is also a templated class which
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::alias">The <tt>cl::alias</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
aliases for other arguments.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
help text to be printed out for the <tt>-help</tt> option.</p>
</pre></div>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="builtinparsers">Builtin parsers</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Parsers control how the string value taken from the command line is
translated into a typed value, suitable for use in a C++ program. By default,
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="extensionguide">Extension Guide</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Although the CommandLine library has a lot of functionality built into it
already (as discussed previously), one of its true strengths lie in its
extensibility. This section discusses how the CommandLine library works under
the covers and illustrates how to do some simple, common, extensions.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="customparser">Writing a custom parser</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>One of the simplest and most common extensions is the use of a custom parser.
As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="explotingexternal">Exploiting external storage</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
will automatically be included in any program that links with that library.
This is a feature. However, sometimes it is necessary to know the value of the
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="dynamicopts">Dynamically adding command line options</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>TODO: fill in this section</p>
</div>
+</div>
+
<!-- *********************************************************************** -->
<hr>
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
- <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff