Previous Up Next
Chapter 1 Camlp4
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 .''.

1.1 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 operations: Some shortcut commands are provided:
1.2 Preprocessing OCaml

1.2.1 The compiler

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.

1.2.2 Remark

It is possible to use Camlp4 with ``pr_o.cmo'', instead of ``pr_dump.cmo'' for OCaml preprocessing, but it is not recommended, for: 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.

1.2.3 The toplevel

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 ``#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.

1.3 User syntax modifications

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.



Previous Up Next