-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsection"><a name="overview"></a>Overview</div>
-<div class="doc_text">
-<p><tt>llvmc</tt> is highly configurable both on the command line and in
-configuration files. The options it understands are generic, consistent and
-simple by design. Furthermore, the <tt>llvmc</tt> options apply to the
-compilation of any LLVM enabled programming language. To be enabled as a
-supported source language compiler, a compiler writer must provide a
-configuration file that tells <tt>llvmc</tt> how to invoke the compiler
-and what its capabilities are. The purpose of the configuration files then
-is to allow compiler writers to specify to <tt>llvmc</tt> how the compiler
-should be invoked. Users may but are not advised to alter the compiler's
-<tt>llvmc</tt> configuration.</p>
-
-<p>Because <tt>llvmc</tt> just invokes other programs, it must deal with the
-available command line options for those programs regardless of whether they
-were written for LLVM or not. Furthermore, not all compilation front ends will
-have the same capabilities. Some front ends will simply generate LLVM assembly
-code, others will be able to generate fully optimized byte code. In general,
-<tt>llvmc</tt> doesn't make any assumptions about the capabilities or command
-line options of a sub-tool. It simply uses the details found in the configuration
-files and leaves it to the compiler writer to specify the configuration
-correctly.</p>
-
-<p>This approach means that new compiler front ends can be up and working very
-quickly. As a first cut, a front end can simply compile its source to raw
-(unoptimized) bytecode or LLVM assembly and <tt>llvmc</tt> can be configured
-to pick up the slack (translate LLVM assembly to bytecode, optimize the
-bytecode, generate native assembly, link, etc.). In fact, the front end need
-not use any LLVM libraries, and it could be written in any language (instead of
-C++). The configuration data will allow the full range of optimization,
-assembly, and linking capabilities that LLVM provides to be added to these kinds
-of tools. Enabling the rapid development of front-ends is one of the primary
-goals of <tt>llvmc</tt>.</p>
-
-<p>As a compiler front end matures, it may utilize the LLVM libraries and tools
-to more efficiently produce optimized bytecode directly in a single compilation
-and optimization program. In these cases, multiple tools would not be needed
-and the configuration data for the compiler would change.</p>
-
-<p>Configuring <tt>llvmc</tt> to the needs and capabilities of a source language
-compiler is relatively straight forward. A compiler writer must provide a
-definition of what to do for each of the five compilation phases for each of
-the optimization levels. The specification consists simply of prototypical
-command lines into which <tt>llvmc</tt> can substitute command line
-arguments and file names. Note that any given phase can be completely blank if
-the source language's compiler combines multiple phases into a single program.
-For example, quite often pre-processing, translation, and optimization are
-combined into a single program. The specification for such a compiler would have
-blank entries for pre-processing and translation but a full command line for
-optimization.</p>
+<div class="section" id="conditional-evaluation">
+<span id="case"></span><h1><a class="toc-backref" href="#id12">Conditional evaluation</a></h1>
+<p>The 'case' construct is the main means by which programmability is
+achieved in LLVMC. It can be used to calculate edge weights, program
+actions and modify the shell commands to be executed. The 'case'
+expression is designed after the similarly-named construct in
+functional languages and takes the form <tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(test_1),</span> <span class="pre">statement_1,</span>
+<span class="pre">(test_2),</span> <span class="pre">statement_2,</span> <span class="pre">...</span> <span class="pre">(test_N),</span> <span class="pre">statement_N)</span></tt>. The statements
+are evaluated only if the corresponding tests evaluate to true.</p>
+<p>Examples:</p>
+<pre class="literal-block">
+// Edge weight calculation
+
+// Increases edge weight by 5 if "-A" is provided on the
+// command-line, and by 5 more if "-B" is also provided.
+(case
+ (switch_on "A"), (inc_weight 5),
+ (switch_on "B"), (inc_weight 5))
+
+
+// Tool command line specification
+
+// Evaluates to "cmdline1" if the option "-A" is provided on the
+// command line; to "cmdline2" if "-B" is provided;
+// otherwise to "cmdline3".
+
+(case
+ (switch_on "A"), "cmdline1",
+ (switch_on "B"), "cmdline2",
+ (default), "cmdline3")
+</pre>
+<p>Note the slight difference in 'case' expression handling in contexts
+of edge weights and command line specification - in the second example
+the value of the <tt class="docutils literal"><span class="pre">"B"</span></tt> switch is never checked when switch <tt class="docutils literal"><span class="pre">"A"</span></tt> is
+enabled, and the whole expression always evaluates to <tt class="docutils literal"><span class="pre">"cmdline1"</span></tt> in
+that case.</p>
+<p>Case expressions can also be nested, i.e. the following is legal:</p>
+<pre class="literal-block">
+(case (switch_on "E"), (case (switch_on "o"), ..., (default), ...)
+ (default), ...)
+</pre>
+<p>You should, however, try to avoid doing that because it hurts
+readability. It is usually better to split tool descriptions and/or
+use TableGen inheritance instead.</p>
+<ul class="simple">
+<li>Possible tests are:<ul>
+<li><tt class="docutils literal"><span class="pre">switch_on</span></tt> - Returns true if a given command-line switch is provided by
+the user. Can be given a list as argument, in that case <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">["foo",</span>
+<span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(switch_on</span> <span class="pre">"foo"),</span> <span class="pre">(switch_on</span>
+<span class="pre">"bar"),</span> <span class="pre">(switch_on</span> <span class="pre">"baz"))</span></tt>.
+Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">"opt")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">any_switch_on</span></tt> - Given a list of switch options, returns true if any of
+the switches is turned on.
+Example: <tt class="docutils literal"><span class="pre">(any_switch_on</span> <span class="pre">["foo",</span> <span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(or</span>
+<span class="pre">(switch_on</span> <span class="pre">"foo"),</span> <span class="pre">(switch_on</span> <span class="pre">"bar"),</span> <span class="pre">(switch_on</span> <span class="pre">"baz"))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">parameter_equals</span></tt> - Returns true if a command-line parameter equals
+a given value.
+Example: <tt class="docutils literal"><span class="pre">(parameter_equals</span> <span class="pre">"W",</span> <span class="pre">"all")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">element_in_list</span></tt> - Returns true if a command-line parameter
+list contains a given value.
+Example: <tt class="docutils literal"><span class="pre">(parameter_in_list</span> <span class="pre">"l",</span> <span class="pre">"pthread")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">input_languages_contain</span></tt> - Returns true if a given language
+belongs to the current input language set.
+Example: <tt class="docutils literal"><span class="pre">(input_languages_contain</span> <span class="pre">"c++")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">in_language</span></tt> - Evaluates to true if the input file language is equal to
+the argument. At the moment works only with <tt class="docutils literal"><span class="pre">cmd_line</span></tt> and <tt class="docutils literal"><span class="pre">actions</span></tt> (on
+non-join nodes).
+Example: <tt class="docutils literal"><span class="pre">(in_language</span> <span class="pre">"c++")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">not_empty</span></tt> - Returns true if a given option (which should be either a
+parameter or a parameter list) is set by the user. Like <tt class="docutils literal"><span class="pre">switch_on</span></tt>, can
+be also given a list as argument.
+Example: <tt class="docutils literal"><span class="pre">(not_empty</span> <span class="pre">"o")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">any_not_empty</span></tt> - Returns true if <tt class="docutils literal"><span class="pre">not_empty</span></tt> returns true for any of
+the options in the list.
+Example: <tt class="docutils literal"><span class="pre">(any_not_empty</span> <span class="pre">["foo",</span> <span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(or</span>
+<span class="pre">(not_empty</span> <span class="pre">"foo"),</span> <span class="pre">(not_empty</span> <span class="pre">"bar"),</span> <span class="pre">(not_empty</span> <span class="pre">"baz"))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">empty</span></tt> - The opposite of <tt class="docutils literal"><span class="pre">not_empty</span></tt>. Equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(not_empty</span>
+<span class="pre">X))</span></tt>. Provided for convenience. Can be given a list as argument.</li>
+<li><tt class="docutils literal"><span class="pre">any_not_empty</span></tt> - Returns true if <tt class="docutils literal"><span class="pre">not_empty</span></tt> returns true for any of
+the options in the list.
+Example: <tt class="docutils literal"><span class="pre">(any_empty</span> <span class="pre">["foo",</span> <span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(and</span>
+<span class="pre">(not_empty</span> <span class="pre">"foo"),</span> <span class="pre">(not_empty</span> <span class="pre">"bar"),</span> <span class="pre">(not_empty</span> <span class="pre">"baz")))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">single_input_file</span></tt> - Returns true if there was only one input file
+provided on the command-line. Used without arguments:
+<tt class="docutils literal"><span class="pre">(single_input_file)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">multiple_input_files</span></tt> - Equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(single_input_file))</span></tt> (the
+case of zero input files is considered an error).</li>
+<li><tt class="docutils literal"><span class="pre">default</span></tt> - Always evaluates to true. Should always be the last
+test in the <tt class="docutils literal"><span class="pre">case</span></tt> expression.</li>
+<li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard binary logical combinator that returns true iff all of
+its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span>
+<span class="pre">...</span> <span class="pre">(testN))</span></tt>. Nesting of <tt class="docutils literal"><span class="pre">and</span></tt> and <tt class="docutils literal"><span class="pre">or</span></tt> is allowed, but not
+encouraged.</li>
+<li><tt class="docutils literal"><span class="pre">or</span></tt> - A binary logical combinator that returns true iff any of its
+arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">not</span></tt> - Standard unary logical combinator that negates its
+argument. Example: <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(or</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN)))</span></tt>.</li>
+</ul>
+</li>
+</ul>