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
with ``.cmo'' or ``.cma'').

The command ``camlp4'' runs the Camlp4 program. The first
options are objects (``.cmo'') or library (``.cma'')
files which are loaded, selecting different parsing and printing
operations. Among these first options, it is also possible to use the
option ``-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,
e.g. ``foo.cmo'' in the current directory, write
``./foo.cmo'' or add the option ``-I .''.

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:

Parsing syntax:

pa_o.cmo: OCaml.

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
option -l to the command line to specify a line length.

pr_r.cmo: Pretty print with revised syntax. Add this option
-l too.

pr_dump.cmo: Dump the syntax tree

Other predefined files allow to extend parsing and printing
operations:

Parsing extensions:

pa_oop.cmo: (to be loaded after ``pa_o.cmo'')
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 ``pa_o.cmo'')
Parsers and streams, with OCaml syntax, with code optimization.

pa_rp.cmo: (to be loaded after ``pa_r.cmo'')
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_macro.cmo: add macros and IFDEF statements
(conditional compilation) like C, in expressions or structure items. Add
the options -D and -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. ``foo.ml'', holding

Pa_macro.define "FOO";;

compile it and load its corresponding object file:

camlp4o pa_macro.cmo ./foo.cmo file.ml

To undefine the symbol FOO, use either ``-UFOO'' or
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:

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
command:

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
directory.

It is possible to use Camlp4 with ``pr_o.cmo'', instead of
``pr_dump.cmo'' for OCaml preprocessing, but it is not
recommended, for:

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 pr_dump.cmo)

In case of typing
errors, OCaml would show the error location in the resulting
file of Camlp4, what is not convenient.

However, there is a case where it is interesting to use
``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:

Either the file ``camlp4o.cma'' to continue with
OCaml syntax.

Or the file ``camlp4r.cma'' to continue with
the Revised syntax.

To change the behavior of Camlp4, just load the needed module with
the directives ``#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.

The next chapters explain the different ways to create files holding
syntax modifications. The simplest one is the quotations system
(chapter 3).

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.