Overview

Camlp5 is a preprocessor and pretty-printer for ocaml programs.

As a preprocessor, it allows to:

As a pretty printer, it allows to:

Camlp5 also provides some parsing and pretty printing tools.

It works as a shell command and can also be used in the ocaml toplevel.

Shell usage

The main shell commands are:

These commands can be given as parameters of the option -pp of the ocaml compiler. Examples:

  ocamlc -pp camlp5o foo.ml
  ocamlc -pp camlp5r bar.ml

This way, the parsing is done by camlp5. In case of syntax errors, the parsing fails with an error message and the compilation is aborted. Otherwise, the ocaml compiler continues with the syntax tree provided by camlp5.

In the toplevel, it is possible to preprocess the input phrases by loading one of the files "camlp5o.cma" or "camlp5r.cma". The common usage is:

  ocaml -I +camlp5 camlp5o.cma
  ocaml -I +camlp5 camlp5r.cma

Parsing and Printing kits

Parsing and printing extensions are ocaml object files, i.e. files with the extension ".cmo" or ".cma. They are the result of the compilation of ocaml source files containing what is necessary to do the parsing or printing extensions. These object files are named parsing or printing kits.

These files cannot be linked to produce executables because they generally call functions and use variables defined only in camlp5 core, typically belonging to the module "Pcaml". The kits are destinated to be loaded by the camlp5 commands, either by their command arguments or by the source files using them through the directive "#load".

It is therefore important to compile the kits with the option "-c" of the ocaml compiler (i.e. just compilation, do not produce executable) and with the option "-I +camlp5" to inform the compiler to find module interfaces in installed camlp5 library.

In the ocaml toplevel, it is possible to use a kit by simply loading it with the directive "#load".

Extending syntax

A syntax extension is a camlp5 parsing kit. There are two ways to use a syntax extension:

Several syntax extensions can be used for a single file. The way to create one's own syntax extensions is explained further.

Pretty printing

Like for syntax extensions, the pretty printing are defined or extended through camlp5 printing kits. The main pretty printing kits provided by camlp5 are:

Examples: if we have a file, foo.ml, written in normal syntax and and another one, bar.ml, written in revised syntax, here are the commands to pretty print them in their own syntax:

  camlp5o pr_o.cmo foo.ml
  camlp5r pr_r.cmo bar.ml

And how to convert them into the other syntax:

  camlp5o pr_r.cmo foo.ml
  camlp5r pr_o.cmo foo.ml

The way to create one's own pretty printing extensions is explained further.

Note: the revised syntax

The revised syntax is a specific syntax whose aim is to resolve some syntax problems and inconsistencies of the normal ocaml syntax. A chapter will explain the differences between the normal and the revised syntax.

All examples of this documentation are written in revised syntax. Even if you don't know it, it is not difficult to understand. The same examples can be written in normal syntax. In case of problems, refer to the chapter describing it.