[llvm-commits] CVS: llvm/docs/CommandLine.html

[Jim Laskey]

Changes in directory llvm/docs:

CommandLine.html updated: 1.35 -> 1.36
---
Log message:

Documentation updated to include upcoming support for bit vector support
(flags.)



---
Diffs of the changes:  (+87 -1)

 CommandLine.html |   88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 87 insertions(+), 1 deletion(-)


Index: llvm/docs/CommandLine.html
diff -u llvm/docs/CommandLine.html:1.35 llvm/docs/CommandLine.html:1.36
--- llvm/docs/CommandLine.html:1.35	Mon Aug 22 11:24:25 2005
+++ llvm/docs/CommandLine.html	Thu Aug 25 17:52:43 2005
@@ -23,6 +23,7 @@
                                     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>
 
@@ -61,6 +62,7 @@
             <tt>cl::ParseEnvironmentOptions</tt> 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>
@@ -693,6 +695,65 @@
 
 <!-- ======================================================================= -->
 <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 bit vector.  The represention used by
+the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned long</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>An option specified more than once is redundant as far as the result is
+concerned. The argument position information is however updated.</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 long bits = OptimizationBits.getBits();
+</pre></div>
+
+<p>Finally, if external storage is used, then the location specified must be of
+type <tt>unsigned long</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>
 </div>
 
@@ -1508,6 +1569,31 @@
 
 <!-- _______________________________________________________________________ -->
 <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 long</tt> if external storage is used.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
   <a name="cl::alias">The <tt>cl::alias</tt> class</a>
 </div>
 
@@ -1814,7 +1900,7 @@
 
   <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
   <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
-  Last modified: $Date: 2005/08/22 16:24:25 $
+  Last modified: $Date: 2005/08/25 22:52:43 $
 </address>
 
 </body>