1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
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
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- pcaml.html,v -->
<!-- Copyright (c) INRIA 2007-2017 -->
<title>Pcaml</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link rel="stylesheet" type="text/css" href="styles/base.css"
title="Normal" />
</head>
<body>
<div id="menu">
</div>
<div id="content">
<h1 class="top">The Pcaml module</h1>
<p>All about language parsing entries, language printing functions,
quotation management at parsing time, extensible directives, extensible
options, and generalities about Camlp5.</p>
<div id="tableofcontents">
</div>
<h2>Language parsing</h2>
<h3>Main parsing functions</h3>
<p>The two functions below are called when parsing an interface (.mli
file) or an implementation (.ml file) to build the syntax tree; the
returned list contains the phrases (signature items or structure
items) and their locations; the boolean tells whether the parser has
encountered a directive; in this case, since the directive may
change the syntax, the parsing stops, the directive is evaluated,
and this function is called again.<br/>These functions are
references, because they can be changed to use another technology
than the Camlp5 extended grammars. By default, they use the grammars
entries [implem] and [interf] defined below.</p>
<pre style="border:0; margin-left: 1cm">
value parse_interf :
ref (Stream.t char -> (list (MLast.sig_item * MLast.loc) * bool));
</pre>
<dl><dd>
Function called when parsing an interface (".mli") file
</dd></dl>
<pre style="border:0; margin-left: 1cm">
value parse_implem :
ref (Stream.t char -> (list (MLast.str_item * MLast.loc) * bool));
</pre>
<dl><dd>
Function called when parsing an implementation (".ml") file
</dd></dl>
<h3>Grammar</h3>
<dl>
<dt><tt>value gram : Grammar.g;</tt></dt>
<dd>Grammar variable of the language.</dd>
</dl>
<h3>Entries</h3>
<p>Grammar entries which return <a href="ml_ast.html">syntax
trees</a>. These are set by the parsing kit of the current syntax,
through the statement <a href="grammars.html">EXTEND</a>. They
are usable by other possible user syntax extensions.</p>
<dl>
<dt><tt>value expr : Grammar.Entry.e MLast.expr;</tt></dt>
<dd>Expressions.</dd>
<dt><tt>value patt : Grammar.Entry.e MLast.patt;</tt></dt>
<dd>Patterns.</dd>
<dt><tt>value ctyp : Grammar.Entry.e MLast.ctyp;</tt></dt>
<dd>Types.</dd>
</dl>
<dl>
<dt><tt>value sig_item : Grammar.Entry.e MLast.sig_item;</tt></dt>
<dd>Signature items, i.e. items between "<tt>sig</tt>" and
"<tt>end</tt>", or inside an interface (".mli") file.</dd>
<dt><tt>value str_item : Grammar.Entry.e MLast.str_item;</tt></dt>
<dd>Structure items, i.e. items between "<tt>struct</tt>" and
"<tt>end</tt>", or inside an implementation (".ml") file.</dd>
</dl>
<dl>
<dt><tt>value module_type : Grammar.Entry.e MLast.module_type;</tt></dt>
<dd>Module types, e.g. signatures, functors, identifiers.</dd>
<dt><tt>value module_expr : Grammar.Entry.e MLast.module_expr;</tt></dt>
<dd>Module expressions, e.g. structures, functors, identifiers.</dd>
</dl>
<dl>
<dt><tt>value let_binding : Grammar.Entry.e (MLast.patt *
MLast.expr);</tt></dt>
<dd>Specific entry for the "let binding", i.e. the association
"let pattern = expression".</dd>
<dt><tt>value type_declaration : Grammar.Entry.e
MLast.type_decl;</tt></dt>
<dd>Specific entry for the "type declaration", i.e. the association
"type name = type-expression"</dd>
</dl>
<dl>
<dt><tt>value class_sig_item : Grammar.Entry.e
MLast.class_sig_item;</tt></dt>
<dd>Class signature items, i.e. items of class objects types.</dd>
<dt><tt>value class_str_item : Grammar.Entry.e
MLast.class_str_item;</tt></dt>
<dd>Class structure items, i.e. items of class objects.</dd>
<dt><tt>value class_type : Grammar.Entry.e MLast.class_type;</tt></dt>
<dd>Class types, e.g. object types, class types functions,
identifiers. </dd>
<dt><tt>value class_expr : Grammar.Entry.e MLast.class_expr;</tt></dt>
<dd>Class expressions, e.g. objects, class functions, identifiers.</dd>
</dl>
<dl>
<dt><tt>value interf : Grammar.Entry.e (list (MLast.sig_item * MLast.loc) * bool);</tt></dt>
<dd>Interface, i.e. files with extension ".mli". The location is the
top of the tree. The boolean says whether the parsing stopped
because of the presence of a directive (which potentially could
change the syntax).</dd>
<dt><tt>value implem : Grammar.Entry.e (list (MLast.str_item * MLast.loc) * bool);</tt></dt>
<dd>Implementation, i.e. files with extension ".ml". Same remark
about the location and the boolean.</dd>
<dt><tt>value top_phrase : Grammar.Entry.e (option
MLast.str_item);</tt></dt>
<dd>Phrases of the OCaml interactive toplevel. Return "None" in case
of end of file.</dd>
<dt><tt>value use_file : Grammar.Entry.e (list MLast.str_item *
bool);</tt></dt>
<dd>Phrases in files included by the directive "<tt>#use</tt>". The
boolean indicates whether the parsing stopped because of a
directive (as for "<tt>interf</tt>" above).</dd>
</dl>
<h2>Language printing</h2>
<h3>Main printing functions</h3>
<p>The two function below are called when printing an interface (.mli
file) of an implementation (.ml file) from the syntax tree; the list
is the result of the corresponding parsing function.<br/>These
functions are references, to allow using other technologies than the
Camlp5 extended printers.</p>
<pre style="border:0; margin-left: 1cm">
value print_interf :
ref (list (MLast.sig_item * MLast.loc) -> unit);
</pre>
<dl><dd>
Function called when printing an interface (".mli") file
</dd></dl>
<pre style="border:0; margin-left: 1cm">
value print_implem :
ref (list (MLast.str_item * MLast.loc) -> unit);
</pre>
<dl><dd>
Function called when printing an implementation (".ml") file
</dd></dl>
<p>By default, these functions fail. The printer kit
"<tt>pr_dump.cmo</tt>" (loaded by most Camlp5 commands) sets them to
functions dumping the syntax tree in binary (for the OCaml
compiler). The pretty printer kits, such as "<tt>pr_r.cmo</tt>" and
"<tt>pr_o.cmo</tt>" set them to functions calling the predefined
printers (see next section).</p>
<h3>Printers</h3>
<p>Printers taking <a href="ml_ast.html">syntax trees</a> as
parameters and returning pretty printed strings. These are set by
the printing kits, through the
statement <a href="printers.html">EXTEND_PRINTER</a>. They are
usable by other possible user printing extensions.</p>
<dl>
<dt><tt>value pr_expr : Eprinter.t MLast.expr;</tt></dt>
<dd>Expressions.</dd>
<dt><tt>value pr_patt : Eprinter.t MLast.patt;</tt></dt>
<dd>Patterns.</dd>
<dt><tt>value pr_ctyp : Eprinter.t MLast.ctyp;</tt></dt>
<dd>Types.</dd>
</dl>
<dl>
<dt><tt>value pr_sig_item : Eprinter.t MLast.sig_item;</tt></dt>
<dd>Signature items, i.e. items between "<tt>sig</tt>" and
"<tt>end</tt>", or inside an interface (".mli") file.</dd>
<dt><tt>value pr_str_item : Eprinter.t MLast.str_item;</tt></dt>
<dd>Structure items, i.e. items between "<tt>struct</tt>" and
"<tt>end</tt>", or inside an implementation (".ml") file.</dd>
</dl>
<dl>
<dt><tt>value pr_module_type : Eprinter.t MLast.module_type;</tt></dt>
<dd>Module types, e.g. signatures, functors, identifiers.</dd>
<dt><tt>value pr_module_expr : Eprinter.t MLast.module_expr;</tt></dt>
<dd>Module expressions, e.g. structures, functors, identifiers.</dd>
</dl>
<dl>
<dt><tt>value pr_class_sig_item : Eprinter.t
MLast.class_sig_item;</tt></dt>
<dd>Class signature items, i.e. items of class objects types.</dd>
<dt><tt>value pr_class_str_item : Eprinter.t
MLast.class_str_item;</tt></dt>
<dd>Class structure items, i.e. items of class objects.</dd>
<dt><tt>value pr_class_type : Eprinter.t MLast.class_type;</tt></dt>
<dd>Class types, e.g. object types, class types functions,
identifiers. </dd>
<dt><tt>value pr_class_expr : Eprinter.t MLast.class_expr;</tt></dt>
<dd>Class expressions, e.g. objects, class functions, identifiers.</dd>
</dl>
<h2>Quotation management</h2>
<dl>
<dt><tt>value handle_expr_quotation : MLast.loc -> (string * string)
-> MLast.expr;</tt></dt>
<dd>Called in the semantic actions of the rules parsing a quotation
in position of expression.</dd>
<dt><tt>value handle_patt_quotation : MLast.loc -> (string * string)
-> MLast.patt;</tt></dt>
<dd>Called in the semantic actions of the rules parsing a quotation
in position of pattern.</dd>
</dl>
<dl>
<dt><tt>value quotation_dump_file : ref (option string);</tt></dt>
<dd>"<tt>Pcaml.quotation_dump_file</tt>" optionally tells the
compiler to dump the result of an expander (of kind "generating a
string") if this result is syntactically incorrect. If
"<tt>None</tt>" (default), this result is not dumped. If "<tt>Some
fname</tt>", the result is dumped in the file "<tt>fname</tt>".
The same effect can be done with the option "<tt>-QD</tt>" of
Camlp5 commands.</dd>
<dt><tt>value quotation_location : unit -> Ploc.t;</tt></dt>
<dd>While expanding a quotation, returns the location of the
quotation text (between the quotation quotes) in the source;
raises "<tt>Failure</tt>" if not in the context of a quotation
expander.</dd>
</dl>
<h2>Extensible directives and options</h2>
<dl>
<dt><tt>type directive_fun = option MLast.expr -> unit;</tt></dt>
<dd>The type of functions called to treat a directive with its
syntactic parameter. Directives act by side effect.</dd>
<dt><tt>value add_directive : string -> directive_fun -> unit;</tt></dt>
<dd>Add a new directive.</dd>
<dt><tt>value find_directive : string -> directive_fun;</tt></dt>
<dd>Find the function associated with a directive. Raises
"<tt>Not_found</tt>" if the directive does not exists.</dd>
</dl>
<dl>
<dt><tt>value add_option : string -> Arg.spec -> string -> unit;</tt></dt>
<dd>Add an option to the command line of the Camlp5 command.</dd>
</dl>
<h2>Equalities over syntax trees</h2>
<p>These equalities skip the locations.</p>
<pre style="border:0; margin-left: 1cm">
value eq_expr : MLast.expr -> MLast.expr -> bool;
value eq_patt : MLast.patt -> MLast.patt -> bool;
value eq_ctyp : MLast.ctyp -> MLast.ctyp -> bool;
value eq_str_item : MLast.str_item -> MLast.str_item -> bool;
value eq_sig_item : MLast.sig_item -> MLast.sig_item -> bool;
value eq_module_expr : MLast.module_expr -> MLast.module_expr -> bool;
value eq_module_type : MLast.module_type -> MLast.module_type -> bool;
value eq_class_sig_item : MLast.class_sig_item -> MLast.class_sig_item -> bool;
value eq_class_str_item : MLast.class_str_item -> MLast.class_str_item -> bool;
value eq_class_type : MLast.class_type -> MLast.class_type -> bool;
value eq_class_expr : MLast.class_expr -> MLast.class_expr -> bool;
</pre>
<h2>Generalities</h2>
<dl>
<dt><tt>value version : string;</tt></dt>
<dd>The current version of Camlp5.</dd>
</dl>
<dl>
<dt><tt>value syntax_name : ref string;</tt></dt>
<dd>The name of the current syntax. Set by the loaded syntax kit.</dd>
</dl>
<dl>
<dt><tt>value input_file : ref string;</tt></dt>
<dd>The file currently being parsed.</dd>
</dl>
<dl>
<dt><tt>value output_file : ref (option string);</tt></dt>
<dd>The output file, stdout if None (default).</dd>
</dl>
<dl>
<dt><tt>value no_constructors_arity : ref bool;</tt></dt>
<dd>True if the current syntax does not generate constructor arity,
which is the case of the normal syntax, and not of the revised
one. This has an impact when converting Camlp5 syntax tree into
OCaml compiler syntax tree.</dd>
</dl>
<div class="trailer">
</div>
</div>
</body>
</html>
|
