- Camlp5 -

Version 7.12

• Introduction
• Transitional and Strict
• Parsing and printing tools

• Parsing tools
  • Stream parsers
  • Stream lexers
  • Functional parsers
  • Backtracking parsers
  • Extensible grammars
• Printing tools
  • Extensible printers
  • Pprintf
  • Pretty print
• Language extensions
  • Locations
  • Syntax tree
  • Syntax tree - transi
  • Syntax tree - strict
  • Quotation kit q_ast.cmo
  • The Pcaml module
  • Directives
  • Extensions of syntax
  • Extensions of printing
  • Redefining OCaml syntax
  • Quotations
  • Revised syntax
  • Scheme syntax
  • Macros
  • Pragma directive
  • Extensible functions
• Appendix
  • Commands and Files
  • Library
  • Camlp5 sources
  • About Camlp5

Commands and Files

The main command of Camlp5 is "camlp5". It is an OCaml program in bytecode (compiled with ocamlc, not ocamlopt), able to dynamically load OCaml object files (ending with ".cmo" and ".cma").

Most other Camlp5 commands derive from that one: they are the command "camlp5" with some implicitely applied parameters.

Two other commands are provided: "mkcamlp5" and "mkcamlp5.opt". They allow to create camlp5 executables with already loaded kits.

All commands have an option "-help" which display all possible command parameters and options. Notice that some parameters (the parsing and pretting kits) may add new options. For example, the command:

  camlp5 pr_r.cmo -help

prints more lines than just:

  camlp5 -help

The first parameter ("load options") allows to specify parsing and printing kits (".cmo" and ".cma" files) which are loaded inside the "camlp5" core before any action. Other options may follow.

Parsing and Printing Kits

Parsing kits

language parsing kits

pa_r.cmo

Revised syntax (without parsers).

pa_rp.cmo

Add revised syntax parsers.

pa_o.cmo

Normal syntax (without parsers). Option added:

-no_quot

don't parse quotations, allowing to use, e.g. "<:>" as token.

pa_op.cmo

Add normal syntax parsers.

pa_oop.cmo

Add normal syntax parsers without code optimization.

pa_lexer.cmo

Add stream lexers.

extensible grammars

pa_extend.cmo

Add the EXTEND statement. Options added:

-split_ext

split EXTEND by functions to turn around a PowerPC problem.

-quotify

generate code for quotations (internally used to synchronize q_MLast and pa_r)

-meta_action

undocumented (internally used for compiled version)

pa_extfold.cmo

Add the specific symbols FOLD0 and FOLD1 to the EXTEND statement.

extensible functions and printers

pa_extfun.cmo

Add the extensible function ("extfun" statement).

pa_extprint.cmo

Add the EXTEND_PRINTER statement.

functional parsers

pa_fstream.cmo

Add the functional parsers ("fparser" statement) and the backtracking parsers ("bparser" statement).

other languages

pa_lisp.cmo

Lisp syntax.

pa_scheme.cmo

Scheme syntax.

pa_sml.cmo

SML syntax.

other parsing kits

pa_lefteval.cmo

Add guarantee of left evaluation in functions calls.

pa_macro.cmo

Add macros. Options added:

-D <string>

define for IFDEF statement

-U <string>

undefine for IFDEF statement

-defined

print the defined macros and exit

pa_pragma.cmo

Add pragma directive: evaluations at parse time

Printing kits

language printing kits

pr_r.cmo

Display in revised syntax. Added options:

-flag <str>

Change pretty printing behaviour according to "<str>":
A/a enable/disable all flags
C/c enable/disable comments in phrases
D/d enable/disable allowing expanding 'declare'
E/e enable/disable equilibrate cases
L/l enable/disable allowing printing 'let..in' horizontally
S/s enable/disable printing sequences beginners at end of lines
default setting is "aS".

-wflag <str>

Change displaying 'where' statements instead of 'let':
A/a enable/disable all flags
I/i enable/disable 'where' after 'in'
L/l enable/disable 'where' after 'let..='
M/m enable/disable 'where' after 'match' and 'try'
P/p enable/disable 'where' after left parenthesis
R/r enable/disable 'where' after 'record_field..='
S/s enable/disable 'where' in sequences
T/t enable/disable 'where' after 'then' or 'else'
V/v enable/disable 'where' after 'value..='
W/w enable/disable 'where' after '->'
default setting is "Ars".

-l <length>

Maximum line length for pretty printing (default 78)

-sep_src

Read source file for text between phrases (default).

-sep <string>

Use this string between phrases instead of reading source.

pr_ro.cmo

Add display objects, labels and variants in revised syntax.

pr_rp.cmo

Add display parsers with their (revised) syntax.

pr_o.cmo

Display in normal syntax. Added options:

-flag <str>

Change pretty printing behaviour according to <str>:
A/a enable/disable all flags
C/c enable/disable comments in phrases
E/e enable/disable equilibrate cases
L/l enable/disable allowing printing 'let..in' horizontally
M/m enable/disable printing double semicolons
default setting is "Am".

-l <length>

Maximum line length for pretty printing (default 78)

-sep_src

Read source file for text between phrases (default).

-sep <string>

Use this string between phrases instead of reading source.

pr_op.cmo

Add displaying parsers with their (normal) syntax.

extensible parsers

pr_extend.cmo

Add the displaying of EXTEND statements in their initial syntax.Option added:

-no_slist

Don't reconstruct SLIST, SOPT, SFLAG

extensible functions and printers

pr_extfun.cmo

Add displaying extensible functions ("extfun" statement) in their initial syntax.

pr_extprint.cmo

Add displaying extensible printers ("EXTEND_PRINTER" statement) in their initial syntax.

other language

pr_scheme.cmo

Display in Scheme syntax. Option added:

-l <length>

Maximum line length for pretty printing (default 78)

-sep <string>

Use this string between phrases instead of reading source.

pr_schemep.cmo

Add display parsers with their (Scheme) syntax.

other printing kits

pr_depend.cmo

Display dependencies. Option added:

-I dir

Add "dir" to the list of search directories.

pr_dump.cmo

Dump the syntax tree in binary (for the OCaml compiler)

pr_null.cmo

No output.

Quotations expanders

q_MLast.cmo

Syntax tree quotations. Define the quotations named: "expr", "patt", "ctyp", "str_item", "sig_item", "module_type", "module_expr", "class_type", "class_expr", "class_sig_item", "class_str_item", "with_constr" and "poly_variant".

q_phony.cmo

Transform quotations into phony variables to be able to pretty print the quotations in their initial form (not suitable for compilation)

Commands

camlp5r

Shortcut for "camlp5 pa_r.cmo pa_rp.cmo pr_dump.cmo"

camlp5r.opt

Same as previous, but in native code instead of bytecode, therefore faster. But not extensible: it is not possible to add other parsing or printing kits neither in command arguments nor with the "load" directive inside sources. Suitable for compiling sources not using other syntax extensions.

camlp5o

Shortcut for "camlp5 pa_o.cmo pa_op.cmo pr_dump.cmo"

camlp5o.opt

Same as previous, and like "camlp5r.opt", faster and not extensible. Moreover, this has been produced by compilation of Camlp5 grammars, resulting in a still faster executable.

camlp5sch

Shortcut for "camlp5 pa_scheme.cmo pr_dump.cmo"

mkcamlp5

creates camlp5 executables with almost the same options than ocamlmktop. The interfaces to be visible must be explicitly added in the command line as ".cmi" files. For example, how to add the the OCaml module "str": "mkcamlp5 -custom str.cmi str.cma -cclib -lstr -o camlp5str"

mkcamlp5.opt

creates camlp5 executables like mkcamlp5, except that it is in native code, therefore faster, but not extensible; the added kits must be cmx or cmxa files

Environment variable

When running a program using extensible grammars (in particular, the camlp5 commands), the environment variable "CAMLP5PARAM" is consulted. It sets the grammar parsing algoritm parameters.

This variable must be a sequence of parameter specifications. A parameter specification is a letter optionally followed by an = and a value, with any separator. There are four possible parameters:

b

Set the full backtrack algorithm as default.

f

Set the limited backtrack algorithm as default.

t

Trace symbols (terminals and non-terminals) while parsing with backtracking.

y

In backtracking, trace the advance in the input stream (number of unfrozen tokens) and the possible stalling (number of tokens tests).

l=value

Set the maximum stalling value.

OCaml toplevel files

These object files can be loaded in the OCaml toplevel to make Camlp5 parse the input. It is possible to load them either by putting them as parameters of the toplevel, or by using the directive "load". The option "-I +camlp5" (or "-I `camlp5 -where`") must be added to the "ocaml" command (the OCaml toplevel).

camlp5r.cma

Read phrases and display results in revised syntax

camlp5o.cma

Read phrases and display results in normal syntax

camlp5sch.cma

Read phrases in Scheme syntax

Library files

The Camlp5 library is named "gramlib.cma" and its native code version is "gramlib.cmxa". They contain the modules:

• Ploc : building and combining locations
• Plexing : lexing for Camlp5 grammars
• Plexer : lexer used in revised and normal syntax
• Gramext : implementation of extensible grammars
• Grammar : extensible grammars
• Extfold : functions for grammar extensions FOLD0 and FOLD1
• Extfun : functions for extensible functions
• Eprinter : extensible printers
• Fstream : functional streams
• Pretty : pretty printing on strings

This is a pure library : when linking with it, the Camlp5 program is not included.

↑