interpreter.xml

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<page name="manual_interpreter">

<title>Interpreter</title>

<box title="Command-line" link="cmdline">

<p>
For performance reasons, it is advised to build the interpreter using OCaml 
native code compiler. The structure of the command line is:
</p>

<sample>
cduce [OPTIONS ...] [FILES ...] [--arg ARGUMENT ...]
</sample>

<p>
The options and arguments are:
</p>

<ul>

<li> All the arguments following <code>--arg</code> are passed to the
CDuce program, in the variable <code>argv</code> (of type <code>[
String* ]</code>, which means sequence of character strings).  </li>


<li> The option <code>--compile</code> produces a cduce object file
(suffix <code>.cdo</code>) that can be later executed by  <code>cduce --run</code>.  </li>


<li> The switch <code>--quiet</code> suppresses normal output (typing,
results).  This option is normally used when the CDuce interpreter is used in
the context of batch processing.  </li>

<li> The options <code>--save %%filename%%</code> and 
<code>--load %%filename%%</code> allows persistence
between several invocations of the interpreter, by saving and
restoring the current environment (defined types and values) to a
file. Note that only the arguments after
<code>--arg</code> on the first invocation in a session are passed to the
CDuce program(s).
</li>

<li> The option <code>--dump %%filename%%</code> is equivalent
to <code>--load %%filename%% --save %%filename%%</code>. </li>

<li> The options <code>-v</code> and <code>--version</code> make the
interpreter print its version number and exit immediately.
</li>

<li> The options <code>--pxp</code> and <code>--expat</code> allow
to choose the parser for XML files (available only when CDuce
is built with expat support; default is <code>--expat</code>).</li>

<li>All the other arguments on the command line are considered CDuce
scripts, which are executed successively. 
</li>

</ul>

</box>

<box title="Scripting" link="scripting">

<p>
CDuce can also be used for writing using scripts. As usual it suffices to start
the script file by <code> #!%%install_dir%%/cduce</code> to call in a batch way
the CDuce interpreter. Here is an example of a script file that prints all the
titles of the filters of an Evolution mail client.

</p>
<sample><![CDATA[
#!/usr/local/bin/cduce

type Filter = <filteroptions>[<ruleset> [(<rule>[<title>String _*])+]];;

let filter : Filter = 
      match load_xml "/home/beppe/evolution/filters.xml" with
       | x&Filter -> x
       | _ -> raise "Not a filter document"
 in print_xml(<filters>([filter]/<ruleset>_/<rule>_/<title>_)) ;;



]]></sample>

</box>

<box title="Phrases" link="phrases">

<p>
CDuce programs are sequences of phrases, which can
be juxtaposed or separated by <code>;;</code>. There are several kinds of
phrases:
</p>

<ul>

<li>Types declarations <code>type %%T%% = %%t%%</code>. Adjacent types declarations are mutually
recursive, e.g.:
<sample><![CDATA[
type T = <a>[ S* ]
type S = <b>[ T ]
]]></sample>
</li>

<li>Function declarations <code>let %%f%% %%...%%</code>. 
Adjacent function declarations are mutually recursive, e.g.:
<sample><![CDATA[
let f (x : Int) : Int = g x
let g (x : Int) : Int  = x + 1
]]></sample>
</li>

<li>Global bindings <code>let  %%p%% = %%e%%</code>
or <code>let %%p%% : %%t%% = %%e%%</code>.</li>

<li>Evaluation statements (an expression to evaluate).</li>

<li>Debugging statements:
<sample><![CDATA[
debug filter %%t%% %%p%%          {{ inference for pattern matching }}
debug accept %%p%%            {{ type accepted by a pattern }}
debug sample %%t%%            {{ compute a sample from a type }}
debug subtype %%t%%1 %%t2%%       {{ check subtyping }}
debug compile %%t%% %%p%%1 ... %%pn%% {{ compilation of pattern matching }}
]]></sample>
</li>

<li>Textual inclusion <code>include "%%other_cduce_script.cd%%"</code>;
note that cycle of inclusion are detected and automatically broken.
Filename are relative to the directory of the current file
(or the current directory in the toplevel).
</li>

<li>Global namespace binding <code>namespace %%p%% = "%%...%%"</code>
and global namespace default <code>namespace "%%...%%"</code>
(see <local href="namespaces"/>).
</li>

</ul>

</box>

<box title="Toplevel" link="toplevel">

<p>
If no CDuce file is given on the command line, the interpreter 
behaves as an interactive toplevel.
</p>

<p>
Toplevel phrases are processed after each <code>;;</code>.
Mutually recursive declarations of types or functions
must be contained in a single adjacent sequence of phrases
(without <code>;;</code> inbetween).
</p>

<p>
You can quit the toplevel with the toplevel directive
<code>#quit</code> but also with either  <code>Ctrl-C</code> or
<code>Ctrl-D</code>. In order to allow persistence 
(options <code>-save</code>,<code>--load</code> and 
<code>--dump</code>) to operate, you must quit the toplevel with <code>#quit</code>.
</p>

<p>
The toplevel directive <code>#env</code> prints the current
environment: the set of defined global types and values, and also 
the current sets of prefix-to-<local href="namespaces">namespace</local> bindings used
for parsing (as defined by the user) and
for pretty-printing (as computed by CDuce itself).
</p>

<p>
The toplevel directive <code>#reinit_ns</code> reinit the
table of prefix-to-namespace bindings used for pretty-printing
values and types with namespaces (see <local href="namespaces"/>).
</p>

<p>
The toplevel has no line editing facilities. 
You can use an external wrapper such as
<a href="http://pauillac.inria.fr/~ddr/">ledit</a>.
</p>

</box>

</page>