Camlp4 is a Pre-Processor-Pretty-Printer for OCaml, parsing a
source file and printing some result.
To run, Camlp4 needs to load files holding operations defining or
modifying parsing (how to read the input file) and printing (how to
print the result). Such files are OCaml object files (ending
.cmo'' or ``
The command ``
camlp4'' runs the Camlp4 program. The first
options are objects (``
.cmo'') or library (``
files which are loaded, selecting different parsing and printing
operations. Among these first options, it is also possible to use the
-I'' to select directories where objects and library
files are searched. But, important remark: by default, the system does not searches in the current directory: to select some object file,
foo.cmo'' in the current directory, write
./foo.cmo'' or add the option ``
||Camlp4 predefined files
The system provides some files, installed in Camlp4 library
directory (depending on the installation, usually
/usr/local/lib/camlp4: in the whole document, this
directory is named
camlp4-lib-dir). The provided files are:
Other predefined files allow to extend parsing and printing
pa_r.cmo: Revised: this is an alternative syntax for the
language (chapter 6).
- Printing syntax:
pr_o.cmo: Pretty print with OCaml syntax. Add an
-l to the command line to specify a line length.
pr_r.cmo: Pretty print with revised syntax. Add this option
pr_dump.cmo: Dump the syntax tree
Some shortcut commands are provided:
pa_oop.cmo: (to be loaded after ``
Parsers and streams, with OCaml syntax, without code
optimization, corresponding to what is internally generated by
the OCaml compiler.
pa_op.cmo: (to be loaded after ``
Parsers and streams, with OCaml syntax, with code optimization.
pa_rp.cmo: (to be loaded after ``
Parsers and streams, with revised syntax and code optimization.
pa_extend.cmo: (to be loaded either after
pa_o.cmo'' or ``
pa_r.cmo'') Syntax extensions for the
Camlp4 grammar system (Chapter 4).
pa_ocamllex.cma: (to be loaded after ``
pa_r.cmo'': ocamllex syntax (see section ??).
pa_macro.cmo: add macros and
(conditional compilation) like C, in expressions or structure items. Add
-U to the camlp4 command line. To
define the symbol
FOO, either use ``
-DFOO'' in the
camlp4 command line, e.g.:
camlp4o pa_macro.cmo -DFOO file.ml
or make a file, e.g. ``
compile it and load its corresponding object file:
camlp4o pa_macro.cmo ./foo.cmo file.ml
To undefine the symbol
FOO, use either ``
the function ``
Pa_macro.undef''. The statement
IFDEF'' can be used in a place of a structure item or an expression:
in this last case, ``
ELSE'' is mandatory:
IFDEF FOO THEN type t = A of int END;;
let f x = IFDEF FOO THEN x + 1 ELSE x - 1 END;;
pa_ru.cmo: (to be loaded after ``
Add type constraints of type
unit inside sequences.
- Printing extensions:
Try to rebuild parsers and streams in OCaml syntax.
pr_rp.cmo: Try to rebuild parsers and streams in revised syntax.
pr_extend.cmo: Try to rebuilt EXTEND instructions.
pr_depend.cmo: Print file dependencies.
The standard use of Camlp4 is as a preprocessor for OCaml
with the printer ``
pr_dump.cmo''. The OCaml compiler
ocamlc'' recognizes it as a dump, and does not apply another
parsing. In case of typing errors, the error is normally showed
in the input file.
We remind that the command ``
ocaml'' has an option
-pp'' for calling a preprocessor which automatically deals
with intermediate files (see the documentation of OCaml). So,
the normal use of the combination Camlp4-OCaml is done by the
ocamlc -pp "camlp4 camlp4-options" ocaml-options input-files
It is often necessary to add the Camlp4 library directory in
ocaml's path, using option ``
-I''. For information, the Camlp4
command has an option ``
-where'' echoing the full name of this
It is possible to use Camlp4 with ``
pr_o.cmo'', instead of
pr_dump.cmo'' for OCaml preprocessing, but it is not
However, there is a case where it is interesting to use
The parsing would be done twice: one of the user input file by
Camlp4, which pretty prints an intermediate file (which takes some
time), and one of the result of Camlp4 by the OCaml parser.
- OCaml may find more syntax errors, for Camlp4 with
pa_o.cmo accepts a syntax larger than OCaml's (some
syntax restriction is done in
- In case of typing
errors, OCaml would show the error location in the resulting
file of Camlp4, what is not convenient.
pr_o.cmo'' for OCaml preprocessing. When the error is located
in a quotation (chapter 3) or in a syntax extension
(chapter 5), it is not always obvious to understand where
the error is exactly located, and there may be no location for the
error. Using temporarily camlp4 with ``
pr_o.cmo'' allows to see
the exact location of the error, which can be understood by the
programmer of the quotation expander or the syntax extension.
The OCaml toplevel, ``
ocaml'' can use Camlp4. In the toplevel,
you can load:
To change the behavior of Camlp4, just load the needed module with
the directives ``
Either the file ``
camlp4o.cma'' to continue with
- Or the file ``
camlp4r.cma'' to continue with
the Revised syntax.
#load'' and ``
#use'': for example, each
load of ``
pa_o.cmo'' or ``
pa_r.cmo'' would change
the current input syntax to be used in the next sentences.
The files included by the directive ``
#use'' are treated by the
current Camlp4 syntax too. Important remark: a syntax modification
takes place after the complete load of a file, not after each sentence
inside the file.
It is not possible to load a Camlp4 printing syntax file in the
toplevel. The printing results are done by the OCaml toplevel
in standard OCaml syntax.
||User syntax modifications
The next chapters explain the different ways to create files holding
syntax modifications. The simplest one is the quotations system
To introduce other syntax extensions of the language, or to redefine
the complete language syntax, one must use the Camlp4 Grammar System
(chapter 4). The following chapter shows how to extend
or redefine the language syntax (chapter 5).
It is not possible for the user to extend the Camlp4 printing: its
main usage is through the file ``
pr_dump.cmo'', the other
printing files, displaying source text, are just provided for
convenience and their behaviors are not (yet) modifiable.