Camlp4

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:

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_ocamllex.cma: (to be loaded after ``pa_o.cmo'' or ``pa_r.cmo'': ocamllex syntax (see section ??).
- 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:
```
        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 ``pa_r.cmo'' only) Add type constraints of type unit inside sequences.
Printing extensions:
- pr_op.cmo: 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.

Some shortcut commands are provided:

``camlp4o'' is equivalent to:

        camlp4 pa_o.cmo pa_op.cmo pr_dump.cmo

``camlp4r'' is equivalent to:

        camlp4 pa_r.cmo pa_rp.cmo pr_dump.cmo

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:

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.

1.2.3

The toplevel

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.

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.