Camlp4 is a command which you can type from your shell. It has several
versions: camlp4, camlp4o, camlp4r. Actually, the
basic command is camlp4, the other ones being shortcuts for
this command with syntaxes previously loaded (see man page).
Its options are in two parts: the ``load'' options and the ``other''
options. The input file is among the ``other'' options, generally a
.mli interface file or .ml implementation file.
The ``load'' options *must* come first. They are a list of OCaml
object files (cmo) or library file (cma) which are loaded in camlp4
core before any other operation. These files are found in a path. You
can use the option -I to add directories in this path. By
default, the path contains only the camlp4 library directory
(depending on the installation).
Notice that the current directory is *not* by default in the path: to
load a file belonging to the current directory, you have to use either
the option -I . or to type the object file prefixed by a dot
and a slash.
In fact, the command camlp4 alone, without any load option does
nothing with the input file and fails. You need to specify at least
one parser and one printer. If you don't specify any parser, you get
the message ``Failure: no loaded parsing module'', if you don't
specify any printer, ``Failure: no printer''. When it runs,
camlp4 applies the parser to the input file, which builds a
syntax tree and this syntax tree is printed using the printer.
The other options follow. If there is a risk of ambiguities, you can
use -- to separate the load options and the other ones: indeed,
the other options can be extended by the object files loaded in the
core: in particular, the provided object file pr_depend.cmo
adds -I among the other options.
To see the list of available options, type camlp4 -help or, since
the object files can extend the options, type
camlp4 <load-options> -help where <load-options> is
your load options. Type, for example, and compare the results:
camlp4 -help
camlp4 pa_r.cmo pa_extend.cmo -help
camlp4 pr_depend.cmo -help
| 8.3 |
The predefined object files |
|
The predefined object files, available in the camlp4 library
directory, are of two kinds:
- The parser files, which start with
"pa_" for syntax
definitions or extensions (``pa'' like ``PArser''), or with "q_"
for quotations expanders.
- The printer files, which start with
"pr_" (``pr'' like
``PRinter'').
You can see the list of available parsers and printers in the camlp4
library directory or using the man page. The main one are:
pa_o.cmo: the parser with normal OCaml syntax
pa_r.cmo: the parser with revised syntax
pr_dump.cmo: the printer of the raw abstract syntax tree
pr_o.cmo: the printer with normal OCaml syntax
pr_r.cmo: the printer with revised syntax
Note that pr_dump.cmo displays the abstract syntax tree in
binary. By default, it is displayed in standard output (except if the
option -o is used). Thus, pay attention: it is binary material,
if you don't redirect the output to a file, you are likely to
perturb your terminal, because it may find escape sequences and
interpret them. This printer is used as input to the OCaml compiler.
The other printers are useful to display the result of a parsing, test
syntax extensions or quotations expanders. You can print either in
normal syntax or in revised syntax. This can be used also to convert
from normal to revised syntax and vice-versa.
Printers can also be extended. This is undocumented because the
printing facility is not perfected and is a little bit complicated to
use. But you can use the predefined printers. They rebuild the text in
the initial form. For example pr_extend.cmo rebuilds the
EXTEND statements.
An interesting predefined quotation expander is q_phony.cmo
which convert all quotations into phony variables. The quotations are
therefore printed as they are. Useful to pretty print your program
containing quotations without expanding them.
| 8.4 |
Commands camlp4o and camlp4r |
|
The commands camlp4o and camlp4r are actually shortcuts
for (respectively):
camlp4 pa_o.cmo pa_op.cmo pr_dump.cmo
camlp4 pa_r.cmo pa_rp.cmo pr_dump.cmo
You can add parsers and (other) printers to these commands also.
To use Camlp4 in the toplevel, you have to first load the camlp4
machinery. Just loading pa_r.cmo or pa_o.cmo would not
work: the toplevel need a specific object file which contains 1/ a
plug-in to tell it to parse using the Camlp4 stuff 2/ the camlp4
library 3/ object files used by the camlp4 parsers (the camlp4 pretty
printing does not work in the toplevel).
There are two files which contain all of this: camlp4r.cma
starting with the revised syntax and camlp4o.cma starting with
the normal syntax. You must then load one of them by typing either:
#load "camlp4r.cma";;
or
#load "camlp4o.cma";;
From now, you are in the Camlp4 machinery. Everything you type is
parsed by Camlp4. In particular, if you chose the revised syntax,
any other #load statement must end with an alone semicolon,
as the revised syntax requires. To use the camlp4 grammar system, load
pa_extend.cmo, to use the predefined quotations for the OCaml
syntax tree, load q_MLast.cmo.