set of possibilities</a></li>
<li><a href="#namedalternatives">Named alternatives</a></li>
<li><a href="#list">Parsing a list of options</a></li>
+ <li><a href="#bits">Collecting options as a set of flags</a></li>
<li><a href="#description">Adding freeform text to help output</a></li>
</ol></li>
<tt>cl::ParseCommandLineOptions</tt> function</a></li>
<li><a href="#cl::ParseEnvironmentOptions">The
<tt>cl::ParseEnvironmentOptions</tt> function</a></li>
+ <li><a href="#cl::SetVersionPrinter">The cl::SetVersionPrinter
+ function</a></li>
<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
<li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
+ <li><a href="#cl::bits">The <tt>cl::bits</tt> class</a></li>
<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
<li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
</ul></li>
parser</a></li>
<li><a href="#boolparser">The <tt>parser<bool></tt>
specialization</a></li>
+ <li><a href="#boolOrDefaultparser">The <tt>parser<boolOrDefault></tt>
+ specialization</a></li>
<li><a href="#stringparser">The <tt>parser<string></tt>
specialization</a></li>
<li><a href="#intparser">The <tt>parser<int></tt>
program:</p>
<div class="doc_code"><pre>
- #include "Support/CommandLine.h"
+ #include "llvm/Support/CommandLine.h"
</pre></div>
<p>Additionally, you need to add this as the first line of your main
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="bits">Collecting options as a set of flags</a>
+</div>
+
+<div class="doc_text">
+
+<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
+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
+specified value is parsed, the resulting enum's bit is set in the option's bit
+vector:</p>
+
+<div class="doc_code"><pre>
+ <i>bits</i> |= 1 << (unsigned)<i>enum</i>;
+</pre></div>
+
+<p>Options that are specified multiple times are redundant. Any instances after
+the first are discarded.</p>
+
+<p>Reworking the above list example, we could replace <a href="#list">
+<tt>cl::list</tt></a> with <a href="#bits"><tt>cl::bits</tt></a>:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::bits">cl::bits</a><Opts> OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(dce , "<i>Dead Code Elimination</i>"),
+ clEnumVal(constprop , "<i>Constant Propagation</i>"),
+ clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
+ clEnumVal(strip , "<i>Strip Symbols</i>"),
+ clEnumValEnd));
+</pre></div>
+
+<p>To test to see if <tt>constprop</tt> was specified, we can use the
+<tt>cl:bits::isSet</tt> function:</p>
+
+<div class="doc_code"><pre>
+ if (OptimizationBits.isSet(constprop)) {
+ ...
+ }
+</pre></div>
+
+<p>It's also possible to get the raw bit vector using the
+<tt>cl::bits::getBits</tt> function:</p>
+
+<div class="doc_code"><pre>
+ unsigned bits = OptimizationBits.getBits();
+</pre></div>
+
+<p>Finally, if external storage is used, then the location specified must be of
+<b>type</b> <tt>unsigned</tt>. In all other ways a <a
+href="#bits"><tt>cl::bits</tt></a> option is morally equivalent to a <a
+href="#list"> <tt>cl::list</tt></a> option.</p>
+
+</div>
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="description">Adding freeform text to help output</a>
// debug build, then the code specified as the option to the macro will be
// executed. Otherwise it will not be. Example:
//
-// DEBUG(std::cerr << "Bitset contains: " << Bitset << "\n");
+// DOUT << "Bitset contains: " << Bitset << "\n";
//</i>
<span class="doc_hilite">#ifdef NDEBUG
#define DEBUG(X)
not separate the value from the option name specified. Instead, the value is
everything after the prefix, including any equal sign if present. This is useful
for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
-linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
+linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
-options, that have the <a href="#cl::Prefix">cl::Prefix</a> modifier added to
-allow the CommandLine library to recognize them. Note that
-<a href="#cl::Prefix">cl::Prefix</a> options must not have the <a
-href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier specified.</li>
+options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
+modifier added to allow the CommandLine library to recognize them. Note that
+<b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
+<b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
+specified.</li>
<li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
to implement unix style tools (like <tt>ls</tt>) that have lots of single letter
arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
command actually enables four different options, all of which are single
-letters. Note that <a href="#cl::Grouping">cl::Grouping</a> options cannot have
-values.</li>
+letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
+options cannot have values.</li>
</ul>
-<p>The CommandLine library does not restrict how you use the <a
-href="#cl::Prefix">cl::Prefix</a> or <a href="#cl::Grouping">cl::Grouping</a>
-modifiers, but it is possible to specify ambiguous argument settings. Thus, it
-is possible to have multiple letter options that are prefix or grouping options,
-and they will still work as designed.</p>
+<p>The CommandLine library does not restrict how you use the <b><tt><a
+href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
+href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
+specify ambiguous argument settings. Thus, it is possible to have multiple
+letter options that are prefix or grouping options, and they will still work as
+designed.</p>
<p>To do this, the CommandLine library uses a greedy algorithm to parse the
input option into (potentially multiple) prefix and grouping options. The
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
+directly from <tt>main</tt>, and <i>before</i>
+<tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
+for a function to be called in response to the <tt>--version</tt> option instead
+of having the <tt>CommandLine</tt> library print out the usual version string
+for LLVM. This is useful for programs that are not part of LLVM but wish to use
+the <tt>CommandLine</tt> facilities. Such programs should just define a small
+function that takes no arguments and returns <tt>void</tt> and that prints out
+whatever version information is appropriate for the program. Pass the address
+of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
+called when the <tt>--version</tt> option is given by the user.</p>
+
+</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="cl::opt">The <tt>cl::opt</tt> class</a>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="cl::bits">The <tt>cl::bits</tt> class</a>
+</div>
+
+<div class="doc_text">
+
+<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
+can take up to three arguments:</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> bits;
+}
+</pre></div>
+
+<p>This class works the exact same as the <a
+href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
+must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
+
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="cl::alias">The <tt>cl::alias</tt> class</a>
strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
"<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".</li>
+<li><a name="boolOrDefaultparser">The <b><tt>parser<boolOrDefault></tt>
+ specialization</b></a> is used for cases where the value is boolean,
+but we also need to know whether the option was specified at all. boolOrDefault
+is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
+the same strings as <b><tt>parser<bool></tt></b>.</li>
+
<li><a name="stringparser">The <b><tt>parser<string></tt>
specialization</b></a> simply stores the parsed string into the string value
specified. No conversion or modification of the data is performed.</li>
<p>This approach has the advantage that users of your custom data type will
automatically use your custom parser whenever they define an option with a value
type of your data type. The disadvantage of this approach is that it doesn't
-work if your fundemental data type is something that is already supported.</p>
+work if your fundamental data type is something that is already supported.</p>
</li>
src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
- <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff