interpreter.xml 8.46 KB
Newer Older
1
2
3
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<page name="manual_interpreter">

4
<title>Compiler/interpreter/toplevel</title>
5
6
7
8

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

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

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<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>
30
31
32
<sample>
cduce [OPTIONS ...] --script {{script}}.cd [ ARGUMENT ...]
</sample>
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
<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>
52
<sample>
53
cduce [OPTIONS ...] --run [ {{script}}.cd ... ] [--arg ARGUMENT ...]
54
</sample>
55
56
57
58
59
60
61
62
63
64
65
66
<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>
67
68

<p>
69
The options and arguments are:
70
71
72
73
</p>

<ul>

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

77
78
79
80
<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>
81

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

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

88
89
90
91
92
<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.
93
94
</li>

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

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

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

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

107
108
109
110
</ul>

</box>

111
112
113
<box title="Scripting" link="scripting">

<p>
114
CDuce can be used for writing scripts. As usual it suffices to start
115
116
117
118
119
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.
120
121
122

</p>
<sample><![CDATA[
123
#!/usr/local/bin/cduce --script
124
125
126

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

127
128
129
130
131
let src : Latin1 =
  match argv [] with
    | [ f ] -> f
    | _ -> raise "Invalid command line"
in
132
let filter : Filter = 
133
      match load_xml src with
134
135
       | x&Filter -> x
       | _ -> raise "Not a filter document"
136
137
in 
print_xml(<filters>([filter]/<ruleset>_/<rule>_/<title>_)) ;;
138
139
140
141
142
143


]]></sample>

</box>

144
145
146
147
<box title="Phrases" link="phrases">

<p>
CDuce programs are sequences of phrases, which can
148
be juxtaposed or separated by <code>;;</code>. There are several kinds of
149
150
151
152
153
154
phrases:
</p>

<ul>

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

162
<li>Function declarations <code>let %%f%% %%...%%</code>. 
163
Adjacent function declarations are mutually recursive, e.g.:
164
<sample><![CDATA[
165
166
let f (x : Int) : Int = g x
let g (x : Int) : Int  = x + 1
167
168
169
170
171
172
173
174
]]></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>

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

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

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

189
<li>Alias for an external unit <code>using %%alias%% = "%%unit%%"</code>
190
191
192
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
193
194
<code>%%alias%%.%%ident%%</code>
or as <code>%%unit%%.%%ident%%</code>.
195
196
</li>

197
198
199
200
</ul>

</box>

201
202
203
204
205
206
207
208
209
<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>.
210
Mutually recursive declarations of types or functions
211
212
213
214
must be contained in a single adjacent sequence of phrases
(without <code>;;</code> inbetween).
</p>

215
<p>
216
217
You can quit the toplevel with the toplevel directive
<code>#quit</code> but also with either  <code>Ctrl-C</code> or
218
219
<code>Ctrl-D</code>. Another option is to use the built-in
<code>exit</code>.
220
221
</p>

222
223
<p>
  The toplevel directive <code>#help</code> prints an help message about
224
  the available toplevel directives.
225
226
</p>

227
<p>
228
229
230
231
232
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).
233
234
</p>

235
236
237
238
239
240
<p>
The two toplevel directives <code>#silent</code> and
<code>#verbose</code> can be used to turn down and up toplevel
outputs (results of typing and evaluation).
</p>

241
242
243
244
245
246
<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>

247
248
<p>
  The toplevel directive <code>#print_type</code> shows a representationo of a
249
250
  CDuce type (including types imported from <local href="manual_schema">XML
    Schema</local> documents).
251
252
</p>

253
254
255
256
257
<p>
The toplevel directive <code>#builtins</code> prints the name
of embedded OCaml values (see <local href="manual_interfacewithocaml"/>).
</p>

258
259
260
261
262
263
264
265
<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>

266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
<box title="Lexical entities" link="lex">

<p>
The <b>identifiers</b> (for variables, types, recursive patterns)
are qualified names, in the sense of
<a
href="http://www.w3.org/TR/REC-xml-names/">XML Namespaces</a>.
The chapter <local href="namespaces"/> explains how to declare
namespace prefixes in CDuce. Identifiers are resolved as XML
attributes (which means that the default namespace does not apply).
</p>

<p>
The dot must be protected by a backslash in identifiers, to avoid
ambiguity with the dot notation.
</p>

<p>
The dot notation serves several purposes:
</p>
<ul>
<li>
to refer to values and types declared in a separate CDuce compilation unit;
</li>
<li>
to refer to values from OCaml compilation unit
(see <local href="manual_interfacewithocaml"/>);
</li>
<li>
to refer to schema components
(see <local href="manual_schema"/>);
</li>
<li>
to select a field from a record expression.
</li>
</ul>
<p>
CDuce supports two style of <b>comments</b>: <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>

316
</page>