1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2
"http://www.w3.org/TR/REC-html40/loose.dtd">
6
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7
<META name="GENERATOR" content="hevea 1.06">
12
<BODY TEXT=black BGCOLOR=white>
13
<A HREF="tutorial007.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
14
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
16
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
17
<TR><TD BGCOLOR="#2de52d"><DIV ALIGN=center><TABLE>
18
<TR><TD><A NAME="htoc66"><B><FONT SIZE=6>Chapter 8</FONT></B></A></TD>
19
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=6>The camlp4 commands</FONT></B></TD>
20
</TR></TABLE></DIV></TD>
22
<A NAME="c:tutcomm"></A>
23
Camlp4 is a command which you can type from your shell. It has several
24
versions: <CODE>camlp4</CODE>, <CODE>camlp4o</CODE>, <CODE>camlp4r</CODE>. Actually, the
25
basic command is <CODE>camlp4</CODE>, the other ones being shortcuts for
26
this command with syntaxes previously loaded (see man page).<BR>
30
Its options are in two parts: the ``load'' options and the ``other''
31
options. The input file is among the ``other'' options, generally a
32
<CODE>.mli</CODE> interface file or <CODE>.ml</CODE> implementation file.<BR>
34
<A NAME="toc53"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
35
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
36
<TR><TD><A NAME="htoc67"><B><FONT SIZE=5>8.1</FONT></B></A></TD>
37
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>The load options</FONT></B></TD>
38
</TR></TABLE></DIV></TD>
40
The ``load'' options *must* come first. They are a list of OCaml
41
object files (cmo) or library file (cma) which are loaded in camlp4
42
core before any other operation. These files are found in a path. You
43
can use the option <CODE>-I</CODE> to add directories in this path. By
44
default, the path contains only the camlp4 library directory
45
(depending on the installation).<BR>
49
Notice that the current directory is *not* by default in the path: to
50
load a file belonging to the current directory, you have to use either
51
the option <CODE>-I .</CODE> or to type the object file prefixed by a dot
56
In fact, the command <CODE>camlp4</CODE> alone, without any load option does
57
nothing with the input file and fails. You need to specify at least
58
one parser and one printer. If you don't specify any parser, you get
59
the message ``Failure: no loaded parsing module'', if you don't
60
specify any printer, ``Failure: no printer''. When it runs,
61
<CODE>camlp4</CODE> applies the parser to the input file, which builds a
62
syntax tree and this syntax tree is printed using the printer.<BR>
64
<A NAME="toc54"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
65
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
66
<TR><TD><A NAME="htoc68"><B><FONT SIZE=5>8.2</FONT></B></A></TD>
67
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>The other options</FONT></B></TD>
68
</TR></TABLE></DIV></TD>
70
The other options follow. If there is a risk of ambiguities, you can
71
use <CODE>--</CODE> to separate the load options and the other ones: indeed,
72
the other options can be extended by the object files loaded in the
73
core: in particular, the provided object file <CODE>pr_depend.cmo</CODE>
74
adds <CODE>-I</CODE> among the other options.<BR>
78
To see the list of available options, type <CODE>camlp4 -help</CODE> or, since
79
the object files can extend the options, type
80
<CODE>camlp4 <load-options> -help</CODE> where <CODE><load-options></CODE> is
81
your load options. Type, for example, and compare the results:
84
camlp4 pa_r.cmo pa_extend.cmo -help
85
camlp4 pr_depend.cmo -help
87
<A NAME="toc55"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
88
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
89
<TR><TD><A NAME="htoc69"><B><FONT SIZE=5>8.3</FONT></B></A></TD>
90
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>The predefined object files</FONT></B></TD>
91
</TR></TABLE></DIV></TD>
93
The predefined object files, available in the camlp4 library
94
directory, are of two kinds:
95
<UL><LI>The parser files, which start with <CODE>"pa_"</CODE> for syntax
96
definitions or extensions (``pa'' like ``PArser''), or with <CODE>"q_"</CODE>
97
for quotations expanders.<BR>
99
<LI>The printer files, which start with <CODE>"pr_"</CODE> (``pr'' like
101
You can see the list of available parsers and printers in the camlp4
102
library directory or using the man page. The main one are:
103
<UL><LI><CODE>pa_o.cmo</CODE>: the parser with normal OCaml syntax<BR>
105
<LI><CODE>pa_r.cmo</CODE>: the parser with revised syntax<BR>
107
<LI><CODE>pr_dump.cmo</CODE>: the printer of the raw abstract syntax tree<BR>
109
<LI><CODE>pr_o.cmo</CODE>: the printer with normal OCaml syntax<BR>
111
<LI><CODE>pr_r.cmo</CODE>: the printer with revised syntax</UL>
112
Note that <CODE>pr_dump.cmo</CODE> displays the abstract syntax tree in
113
binary. By default, it is displayed in standard output (except if the
114
option <CODE>-o</CODE> is used). Thus, pay attention: it is binary material,
115
if you don't redirect the output to a file, you are likely to
116
perturb your terminal, because it may find escape sequences and
117
interpret them. This printer is used as input to the OCaml compiler.<BR>
121
The other printers are useful to display the result of a parsing, test
122
syntax extensions or quotations expanders. You can print either in
123
normal syntax or in revised syntax. This can be used also to convert
124
from normal to revised syntax and vice-versa.<BR>
128
Printers can also be extended. This is undocumented because the
129
printing facility is not perfected and is a little bit complicated to
130
use. But you can use the predefined printers. They rebuild the text in
131
the initial form. For example <CODE>pr_extend.cmo</CODE> rebuilds the
132
<CODE>EXTEND</CODE> statements.<BR>
136
An interesting predefined quotation expander is <CODE>q_phony.cmo</CODE>
137
which convert all quotations into phony variables. The quotations are
138
therefore printed as they are. Useful to pretty print your program
139
containing quotations without expanding them.<BR>
141
<A NAME="toc56"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
142
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
143
<TR><TD><A NAME="htoc70"><B><FONT SIZE=5>8.4</FONT></B></A></TD>
144
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Commands camlp4o and camlp4r</FONT></B></TD>
145
</TR></TABLE></DIV></TD>
147
The commands <CODE>camlp4o</CODE> and <CODE>camlp4r</CODE> are actually shortcuts
150
camlp4 pa_o.cmo pa_op.cmo pr_dump.cmo
151
camlp4 pa_r.cmo pa_rp.cmo pr_dump.cmo
153
You can add parsers and (other) printers to these commands also.<BR>
155
<A NAME="toc57"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
156
<TR><TD BGCOLOR="#66ff66"><DIV ALIGN=center><TABLE>
157
<TR><TD><A NAME="htoc71"><B><FONT SIZE=5>8.5</FONT></B></A></TD>
158
<TD WIDTH="100%" ALIGN=center><B><FONT SIZE=5>Toplevel</FONT></B></TD>
159
</TR></TABLE></DIV></TD>
161
To use Camlp4 in the toplevel, you have to first load the camlp4
162
machinery. Just loading <CODE>pa_r.cmo</CODE> or <CODE>pa_o.cmo</CODE> would not
163
work: the toplevel need a specific object file which contains 1/ a
164
plug-in to tell it to parse using the Camlp4 stuff 2/ the camlp4
165
library 3/ object files used by the camlp4 parsers (the camlp4 pretty
166
printing does not work in the toplevel).<BR>
170
There are two files which contain all of this: <CODE>camlp4r.cma</CODE>
171
starting with the revised syntax and <CODE>camlp4o.cma</CODE> starting with
172
the normal syntax. You must then load one of them by typing either:
174
#load "camlp4r.cma";;
176
#load "camlp4o.cma";;
178
From now, you are in the Camlp4 machinery. Everything you type is
179
parsed by Camlp4. In particular, if you chose the revised syntax,
180
any other <CODE>#load</CODE> statement must end with an alone semicolon,
181
as the revised syntax requires. To use the camlp4 grammar system, load
182
<CODE>pa_extend.cmo</CODE>, to use the predefined quotations for the OCaml
183
syntax tree, load <CODE>q_MLast.cmo</CODE>.
186
<I><FONT COLOR=maroon>
188
For remarks about Camlp4, write to:
189
<img src="http://cristal.inria.fr/~ddr/images/email.jpg" alt=email align=top>
191
<A HREF="tutorial007.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
192
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
added
removed
camlp4-tutorial.html/tutorial008.html
