web/manual/interpreter.xml

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

<title>Compiler/interpreter/toplevel</title>

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

<p>
According to the command line arguments, 
the <code>cduce</code> command behaves
either as an interactive toplevel, an interpreter, a compiler, or
a loader.
</p>

<ul>
<li>
<sample>
cduce [OPTIONS ...]  [--arg ARGUMENT ...]
</sample>
<p>
The command operates as an interactive
toplevel. See the <a href="#toplevel">Toplevel</a> section below.
</p>
</li>

<li>
<sample>
cduce [OPTIONS ...] [ {{script}}.cd | --stdin ] [--arg ARGUMENT ...]
</sample>
<sample>
cduce [OPTIONS ...] --script {{script}}.cd [ ARGUMENT ...]
</sample>
<p>
The command runs the script <code>{{script}}.cd</code>.
</p>
</li>

<li>
<sample>
cduce [OPTIONS ...] --compile {{script}}.cd [--arg ARGUMENT ...]
</sample>
<p>
The command compiles the script <code>{{script}}.cd</code> and
produces <code>{{script}}.cdo</code>. If the OCaml/CDuce interface
is available and enabled, the compilers looks for a corresponding OCaml interface
<code>{{script}}.cmi</code>. See the <local
href="manual_interfacewithocaml"/> page for more information.
</p>
</li>

<li>
<sample>
cduce [OPTIONS ...] --run [ {{script}}.cd ... ] [--arg ARGUMENT ...]
</sample>
<p>
The command runs one or several pre-compiled scripts.
</p>
</li>
</ul>

<p>
The arguments that follow the <code>--arg</code> option 
are the scripts' command line. They can be accessed within
CDuce using the <code>argv</code> operator 
(of type <code>[] -> [ String* ]</code>).
</p>

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

<ul>

<li> <code>--verbose</code> (for <code>--compile</code> mode only).
 Display the type of values in the compiled unit.</li>

<li> <code>--obj-dir %%directory%%</code> (for <code>--compile</code>
mode only).
Specify where to put the <code>.cdo</code> file (default: same directory as the
source file).</li>

<li> <code>--I %%directory%%</code>
Add a directory to the search path for <code>.cdo</code>
and <code>.cmi</code> files. </li>

<li> <code>--stdin</code>. Read CDuce script from standard input. </li>

<li> <code>--no %%feature%%</code>. 
Disable one of the built-in optional features. The list of feature and
their symbolic name can be obtained with the <code>-v</code>
option. Can be used for instance to turn the Expat parser off, in
order to use PXP, if both have been included at compile time.
</li>

<li> <code>-v</code>, <code>--version</code>. Show version information
and built-in optional features, and exit.
</li>

<li> <code>--license</code>. Show license information and exit.
</li>

<li> <code>--help</code>. Show usage information about the command line.
</li>

<li> <code>--noquery-optim</code>. Do not optimize queries. </li>

</ul>

</box>

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

<p>
CDuce can be used for writing 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. The <code>--script</code> option can
be used to avoid <code>--arg</code> when calling the script. 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 --script

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

let src : Latin1 =
  match argv [] with
    | [ f ] -> f
    | _ -> raise "Invalid command line"
in
let filter : Filter = 
      match load_xml src 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>

<li>Schema declaration <code>schema %%name%% = "%%...%%"</code>
(see <local href="manual_schema">XML Schema</local>).</li>

<li>Alias for an external unit <code>using %%alias%% = "%%unit%%"</code>
or <code>using %%alias%% = %%unit%%</code>:
gives an alternative name for a pre-compiled unit. Values
and types from <code>%%unit%%.cdo</code> can be referred to either as
<code>%%alias%%:%%ident%%</code>
or as <code>%%unit%%:%%ident%%</code>.
</li>

</ul>

</box>

<box title="Comments" link="comment">

<p>
CDuce supports two style of comments: <code>(* ... *)</code>
and <code>/* ... */</code>. The first style allows the programmer
to put a piece a code apart. Nesting is allowed, and strings
within simple or double quotes are not searched for the end-marker
<code>*)</code>. In particular, simple quotes (and apostrophes)
have to be balanced inside a <code>(* ... *)</code> comment.
The other style <code>/* ... */</code> is more adapted to textual
comments. They cannot be nested and quotes are not treated
specially inside the comment.
</p>

</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>. 
</p>

<p>
  The toplevel directive <code>#help</code> prints an help message about
  the available toplevel directives.
</p>
<p>
  The toplevel directive <code>#dump_value</code> dump an XML-like
  representation of the internal CDuce representation of the resulting
  value of an expression. It should not be considered a normative
  representation for CDuce values.
</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 directive <code>#print_type</code> shows a representationo of a
  CDuce type including types imported from <local href="manual_schema">XML
    Schema</local> documents.
</p>

<p>
  The toplevel directive <code>#print_schema</code> shows the <local
    href="manual_schema">XML Schema</local> components contained in a given
  schema.
</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>
1	<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
2	<page name="manual_interpreter">
3
4	<title>Compiler/interpreter/toplevel</title>
5
6	<box title="Command-line" link="cmdline">
7
8	<p>
9	According to the command line arguments,
10	the <code>cduce</code> command behaves
11	either as an interactive toplevel, an interpreter, a compiler, or
12	a loader.
13	</p>
14
15	<ul>
16	<li>
17	<sample>
18	cduce [OPTIONS ...] [--arg ARGUMENT ...]
19	</sample>
20	<p>
21	The command operates as an interactive
22	toplevel. See the <a href="#toplevel">Toplevel</a> section below.
23	</p>
24	</li>
25
26	<li>
27	<sample>
28	cduce [OPTIONS ...] [ {{script}}.cd \| --stdin ] [--arg ARGUMENT ...]
29	</sample>
30	<sample>
31	cduce [OPTIONS ...] --script {{script}}.cd [ ARGUMENT ...]
32	</sample>
33	<p>
34	The command runs the script <code>{{script}}.cd</code>.
35	</p>
36	</li>
37
38	<li>
39	<sample>
40	cduce [OPTIONS ...] --compile {{script}}.cd [--arg ARGUMENT ...]
41	</sample>
42	<p>
43	The command compiles the script <code>{{script}}.cd</code> and
44	produces <code>{{script}}.cdo</code>. If the OCaml/CDuce interface
45	is available and enabled, the compilers looks for a corresponding OCaml interface
46	<code>{{script}}.cmi</code>. See the <local
47	href="manual_interfacewithocaml"/> page for more information.
48	</p>
49	</li>
50
51	<li>
52	<sample>
53	cduce [OPTIONS ...] --run [ {{script}}.cd ... ] [--arg ARGUMENT ...]
54	</sample>
55	<p>
56	The command runs one or several pre-compiled scripts.
57	</p>
58	</li>
59	</ul>
60
61	<p>
62	The arguments that follow the <code>--arg</code> option
63	are the scripts' command line. They can be accessed within
64	CDuce using the <code>argv</code> operator
65	(of type <code>[] -> [ String* ]</code>).
66	</p>
67
68	<p>
69	The options and arguments are:
70	</p>
71
72	<ul>
73
74	<li> <code>--verbose</code> (for <code>--compile</code> mode only).
75	Display the type of values in the compiled unit.</li>
76
77	<li> <code>--obj-dir %%directory%%</code> (for <code>--compile</code>
78	mode only).
79	Specify where to put the <code>.cdo</code> file (default: same directory as the
80	source file).</li>
81
82	<li> <code>--I %%directory%%</code>
83	Add a directory to the search path for <code>.cdo</code>
84	and <code>.cmi</code> files. </li>
85
86	<li> <code>--stdin</code>. Read CDuce script from standard input. </li>
87
88	<li> <code>--no %%feature%%</code>.
89	Disable one of the built-in optional features. The list of feature and
90	their symbolic name can be obtained with the <code>-v</code>
91	option. Can be used for instance to turn the Expat parser off, in
92	order to use PXP, if both have been included at compile time.
93	</li>
94
95	<li> <code>-v</code>, <code>--version</code>. Show version information
96	and built-in optional features, and exit.
97	</li>
98
99	<li> <code>--license</code>. Show license information and exit.
100	</li>
101
102	<li> <code>--help</code>. Show usage information about the command line.
103	</li>
104
105	<li> <code>--noquery-optim</code>. Do not optimize queries. </li>
106
107	</ul>
108
109	</box>
110
111	<box title="Scripting" link="scripting">
112
113	<p>
114	CDuce can be used for writing scripts. As usual it suffices to start
115	the script file by <code> #!%%install_dir%%/cduce</code> to call in a
116	batch way the CDuce interpreter. The <code>--script</code> option can
117	be used to avoid <code>--arg</code> when calling the script. Here is
118	an example of a script file that prints all the titles of the filters
119	of an Evolution mail client.
120
121	</p>
122	<sample><![CDATA[
123	#!/usr/local/bin/cduce --script
124
125	type Filter = <filteroptions>[<ruleset> [(<rule>[<title>String _*])+]];;
126
127	let src : Latin1 =
128	match argv [] with
129	\| [ f ] -> f
130	\| _ -> raise "Invalid command line"
131	in
132	let filter : Filter =
133	match load_xml src with
134	\| x&Filter -> x
135	\| _ -> raise "Not a filter document"
136	in
137	print_xml(<filters>([filter]/<ruleset>_/<rule>_/<title>_)) ;;
138
139
140	]]></sample>
141
142	</box>
143
144	<box title="Phrases" link="phrases">
145
146	<p>
147	CDuce programs are sequences of phrases, which can
148	be juxtaposed or separated by <code>;;</code>. There are several kinds of
149	phrases:
150	</p>
151
152	<ul>
153
154	<li>Types declarations <code>type %%T%% = %%t%%</code>. Adjacent types declarations are mutually
155	recursive, e.g.:
156	<sample><![CDATA[
157	type T = <a>[ S* ]
158	type S = <b>[ T ]
159	]]></sample>
160	</li>
161
162	<li>Function declarations <code>let %%f%% %%...%%</code>.
163	Adjacent function declarations are mutually recursive, e.g.:
164	<sample><![CDATA[
165	let f (x : Int) : Int = g x
166	let g (x : Int) : Int = x + 1
167	]]></sample>
168	</li>
169
170	<li>Global bindings <code>let %%p%% = %%e%%</code>
171	or <code>let %%p%% : %%t%% = %%e%%</code>.</li>
172
173	<li>Evaluation statements (an expression to evaluate).</li>
174
175	<li>Debugging statements:
176	<sample><![CDATA[
177	debug filter %%t%% %%p%% {{ inference for pattern matching }}
178	debug accept %%p%% {{ type accepted by a pattern }}
179	debug sample %%t%% {{ compute a sample from a type }}
180	debug subtype %%t%%1 %%t2%% {{ check subtyping }}
181	debug compile %%t%% %%p%%1 ... %%pn%% {{ compilation of pattern matching }}
182	]]></sample>
183	</li>
184
185	<li>Textual inclusion <code>include "%%other_cduce_script.cd%%"</code>;
186	note that cycle of inclusion are detected and automatically broken.
187	Filename are relative to the directory of the current file
188	(or the current directory in the toplevel).
189	</li>
190
191	<li>Global namespace binding <code>namespace %%p%% = "%%...%%"</code>
192	and global namespace default <code>namespace "%%...%%"</code>
193	(see <local href="namespaces"/>).
194	</li>
195
196	<li>Schema declaration <code>schema %%name%% = "%%...%%"</code>
197	(see <local href="manual_schema">XML Schema</local>).</li>
198
199	<li>Alias for an external unit <code>using %%alias%% = "%%unit%%"</code>
200	or <code>using %%alias%% = %%unit%%</code>:
201	gives an alternative name for a pre-compiled unit. Values
202	and types from <code>%%unit%%.cdo</code> can be referred to either as
203	<code>%%alias%%:%%ident%%</code>
204	or as <code>%%unit%%:%%ident%%</code>.
205	</li>
206
207	</ul>
208
209	</box>
210
211	<box title="Comments" link="comment">
212
213	<p>
214	CDuce supports two style of comments: <code>(* ... *)</code>
215	and <code>/* ... */</code>. The first style allows the programmer
216	to put a piece a code apart. Nesting is allowed, and strings
217	within simple or double quotes are not searched for the end-marker
218	<code>*)</code>. In particular, simple quotes (and apostrophes)
219	have to be balanced inside a <code>(* ... *)</code> comment.
220	The other style <code>/* ... */</code> is more adapted to textual
221	comments. They cannot be nested and quotes are not treated
222	specially inside the comment.
223	</p>
224
225	</box>
226
227	<box title="Toplevel" link="toplevel">
228
229	<p>
230	If no CDuce file is given on the command line, the interpreter
231	behaves as an interactive toplevel.
232	</p>
233
234	<p>
235	Toplevel phrases are processed after each <code>;;</code>.
236	Mutually recursive declarations of types or functions
237	must be contained in a single adjacent sequence of phrases
238	(without <code>;;</code> inbetween).
239	</p>
240
241	<p>
242	You can quit the toplevel with the toplevel directive
243	<code>#quit</code> but also with either <code>Ctrl-C</code> or
244	<code>Ctrl-D</code>.
245	</p>
246
247	<p>
248	The toplevel directive <code>#help</code> prints an help message about
249	the available toplevel directives.
250	</p>
251	<p>
252	The toplevel directive <code>#dump_value</code> dump an XML-like
253	representation of the internal CDuce representation of the resulting
254	value of an expression. It should not be considered a normative
255	representation for CDuce values.
256	</p>
257
258	<p>
259	The toplevel directive <code>#env</code> prints the current
260	environment: the set of defined global types and values, and also
261	the current sets of prefix-to-<local href="namespaces">namespace</local> bindings used
262	for parsing (as defined by the user) and
263	for pretty-printing (as computed by CDuce itself).
264	</p>
265
266	<p>
267	The toplevel directive <code>#reinit_ns</code> reinit the
268	table of prefix-to-namespace bindings used for pretty-printing
269	values and types with namespaces (see <local href="namespaces"/>).
270	</p>
271
272	<p>
273	The toplevel directive <code>#print_type</code> shows a representationo of a
274	CDuce type including types imported from <local href="manual_schema">XML
275	Schema</local> documents.
276	</p>
277
278	<p>
279	The toplevel directive <code>#print_schema</code> shows the <local
280	href="manual_schema">XML Schema</local> components contained in a given
281	schema.
282	</p>
283
284	<p>
285	The toplevel has no line editing facilities.
286	You can use an external wrapper such as
287	<a href="http://pauillac.inria.fr/~ddr/">ledit</a>.
288	</p>
289
290	</box>
291
292	</page>