Commands and Files

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:

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