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)
</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