Warning: This is a legacy page that is only available for historical reasons. I stopped developing OCamlp5 (called OCamlp4 at that time) in spring 2007 when Nicolas Pouillard announced a rewrite of Camlp5 on the OCaml list.

Warning II: This page describes version 0.2. It has not been updated for version 0.3 yet (and history proved that this was the right decision).

Page Navigation

• Conventions
• A not on syntactic sugar
• Module expressions
• Expressions
• Patterns
• Type and exception definitions
• Type expressions
• Module types
• Class expressions
• Class types
• Names
• Lexical conventions
• Identifiers
• Literals (integers, floats, chars, strings)
• Constants
• Class definitions
• Class specification
• Class type definitions
• Compilation units
• Toplevel

Conventions

	|	pattern as  value-name
		<:patt< $patt$ as $[lid]:id$ >>; id : string

The form of the quotation is given below the grammar rule. I hope it is mostly self-explanatory. Of course you can fill the place of the anti-quotation with more concrete syntax. The type of the anti-quotation is given after the semicolon if it is not obvious, like for $patt$. For the second anti-quotation the anti-quotation name lid is given in brackets because the name is optional. In many cases the anti-quotation name is required and without it the quotation parser will fail.

A note on syntactic sugar

This has some consequences for the quotation expander:

• There are different quotations that produce the same ast nodes. For instance, both <:exp< 2 + 3 >> and <:expr< (+) 2 3 >> are expanded into the same code.
• When you use quotations as patterns to match and destruct the internal ast (for instance in a pretty printer) you cannot distinguish the different forms of syntactic sugar. Therefore

  echo "let f = fun a -> fun b -> (+) a b" | camlp4o pr_o.cmo -impl -
  

  outputs

  let f a b = a + b
  

• Obviously, after matching against an application with

  <:expr< $fun$ $arg$ >>
  

  a match against an infix application with

  <:expr< $arg1$ + $arg2$ >>
  

  is superfluous. Similarly for other variants of syntactic sugar.
• All forms of syntactic sugar are documented below in the notes that follow the grammar rules.

Syntactic sugar is also responsible for the most prominent quotation inconvenience: There is no quotation like <:expr< [ $list:els$ ] >>. The reason is, that a list like [ 1; 2 ] is expanded into 1 :: 2 :: [], which is internally represented like (::)(1, (::)(2, [])) (the last expression gives a syntax error because :: is a keyword and not an infix operator).

6.11 Module expressions (module implementations)

• In addition to the original syntax there is also the declare quotation from the revised syntax:

  <<:str_item< declare $list:str_items$ end >>
  <<:str_item< declare $[stri:]str_item$ [;;] ... end >>
  

  with str_items : str_item list
• The external quotation with an infix operator is internally mapped to the first form (in the ast infix operators are lower case identifiers). There is no anti-quotation syntax for infix operators (use the first form instead).
• Class definitions with parameters are syntactic sugar for (curried) class fun-bindings. The expander translates

  <:str_item< class $id$ $p1$ $p2 = $cexpr$ >>
  

  into

  <:str_item< class $id$ = fun $p1$ -> fun $p2 -> $cexpr$ >>
  

• Ocamlc permits lower case module type names as in module type s = sig end, however, all camlp4 parsers require module type names to be upper case.
• There are no quotations for the type MLast.class_infos. It is a record defined as

  type loc = Lexing.position * Lexing.position
  type 'a class_infos =
    { ciLoc : loc;
      ciVir : bool;
      ciPrm : (loc * (string * (bool * bool)) list);
      ciNam : string;
      ciExp : 'a }
  

  The type parameter 'a is instanciated either with class_expr or class_type (for which quatations do exist).
• The last three forms of the module definition are syntactic sugar for the first one. Internally

  <:str_item< module $id$( $id$ : $mt) : $mt$ = $me$ >>
  

  is represented as

  <:str_item< module $id$ = functor( $id$ : $mt$) -< ( $me$ : $mt$ ) >>
  

• The grammar says that in functor application (module-expr(module-expr)) the parenthesis are mandatory. The Camlp4 parsers are a bit more relexed and do not always require the parenthesis, for instance when functor and module are both identifiers. (You still need the parenthesis if the argument is a struct.)

6.7 Expressions

• Internally true and false are represented as the upper case identifiers True and False. To avoid clashes, True is internally represented as <:expr< $uid: True$ >> (watch the space), similarly for False. The expander translates the different capitalisations of true and false accordingly.
• Internally lists are represented with a series of constructor applications of ::. The quotation expander expands the form <:expr<[ ... ] >> accordingly. There is no form like <:expr< [ $list:...$ ] >>.
• In the quotations for immediate records and record updates the fields are represented as patterns. However, these patterns are very basic: Only identifiers with a module-path are allowed there.
• Immediate records and record updates are internally represented with the same node. A quotation form with an OPT'ional expression for records updates should be possible (but has not been done yet).
• Both [], :: are constructors and are internally treated as uppercase identifiers.
• All terms with prefix and infix operators are internally represented as ordinary function application. The expander translates terms with prefix and infix operators to function application. (The prefix operator ! is a bit special: In Camlp4's ast dereferencing is record access. However, when the ast is dumped to ocaml then x.val is translated back to !x.)
• There is a quotations for every possible prefix and every possible infix symbol (including the ones that are not predefined). However, there is not anti-quotation for the prefix or infix symbol. Use function application, if you don't know the operator at compile time.
• For update of mutable values (record fields, strings, arrays, bigarrays and objects) there is only one anti-quotation:<:expr< $expr1$ <- $expr2$ >>. The different forms of update are distinguished by different expr1's.
• There are no ast nodes for bigarray expressions. The quotations expander translates bigarray access and bigarray update into appropriate applications of Bigarray.Array?.get/set. The part in between the braces {...} is parsed as a tuple. For one, two and three indices it uses Array1, Array2 and Array3, respectively. For more indices or in case of an anti-quotation { $tup:...$} it uses Genarray.
• The expander translates <:expr< if $expr$ then $expr$ >> to <:expr< if $expr$ then $expr$ else () >>
• The revised syntax uses <:expr< do { $list:...$ } >> for sequences. In the original syntax <:expr< $list:...$ >> would be ambiguous: it could stand for a tuple or a sequence. To avoid confusion this expander uses $tup:...$ for tuples and $seq:...$ for sequences.
• Internally there is no ast node for fun, only for function. The expander translates fun into curried function's with precisely one match and no when parts. More precisely <:expr< fun a b -> e >> is translated into <:expr< function a -> function b -> e >>.
• The expander translates <:expr< let f a b = ... >> into <:expr< let f = function a -> function b -> ... >>. A type annotation in let is translated into a type annotation of the right-hand side expression.
• The last three forms for local modules are syntactic sugar. The expander translates them into the first form, see a similar note on module definitions.
• The self pattern in objects is stored as patt option in the ast. The form patt : ptyp is stored as a type annotated pattern.
• assert false has a special ast node, therefore the special quotation <:expr< assert false >>.

6.6 Patterns

• Similarly to expressions there is quotation for every possible infix operator, but there is no anti-quotation for infix operators. The expander translates infix operators into lowercase identifiers.
• The internal representation of true and false follows the revised syntax. See the explanations for expressions below.
• Constructor arity is important in Ocaml. Unfortunately one needs the symbol table to find out if in C(a,b) the constructor C is applied to a tuple or to two arguments. ???
• The expander translates immediate list to a series of application of ::.

6.8 Type and exception definitions

6.8.1 Type definitions

• for type-parameters one can write
  •     (nothing)
  • [+/-] '$[lid:]id$  with id : string, for one type parameter
  • ( [+/-] '$[lid:]id$, ... )  with id : string, for a list of type parameters
  • ( $[list:]tpl$ )  with tpl : (string * (bool * bool)) list. Two booleans encode the variance: (false,false) for non-variant; (true,false) for positive; (false,true) for negative. tpl can of course be the empty list.
• for constraints one can write
  •     (nothing)
  • constraint $ptype$ = $ptype$ constraint $ptype$ = $ptype$ ... for an explicit list of constraints
  • $list:cl$    with cl : (ptype * ptype) list
• For variant types one can list the constructors explicitly as [|] $[uid:]uid$ [of $list:ptypes$] | ...
• For record types one can list the fields as { [mutable] $[lid:]lid$ : $[typ:]ptype$; ... }
• For the labels anti-quotation in record types the boolean in the third position encodes mutability: true for mutable and false for non-mutable fields
• For the name of the type one can use the form $locstr:ls$ with ls : location * string. This is probably not interesting for the normal user, however, it is used in paqo_o.ml (the ocaml parser) to create ast's identical with those of pa_o.ml. (With the form $[lid:]lid$ the location information is taken from the value loc, which must be defined at that point.)
• Type declarations in the revised syntax are quite different. This has some unpleasant consequences because Camlp4's internal representation mirrors the revised syntax.
• Internally there is no type of ast nodes for typedef's (and there is no typedef quotation for the revised syntax). Instead the typedef quotation builds expressions of type

  type_decl = (loc * string) * (string * (bool * bool)) list * ctyp * (ctyp * ctyp) list
  

  The different kinds of typdef's are encoded via different ctyp's (which are called ptype's in this document) in the third position.
• In the above type the location in the first position is the location of the identifier. There is no location information for the type parameters (which follow the identifier in the revised syntax).
• All the above typedef quotations are internally mapped to the first form. Private types and manifest types are represented as type expressions (ptype's) for which there is no original syntax. (Manifest types are those with two equations, like type a = b = { ... }.)
• Abstract types are internally represented as type equations, where the right hand side is a fresh type variable (which is chosen in the quotation expander). Therefore

  <:typedef< '$id$ $[lid:]lid$ [$list:cl$] >>
  

  raises an exception in the quotation expander (there is no way to access the anti-quotation id to choose an identifier different from it) and so do other variants where the type parameters involve anti-quotations. If you need anti-quotations for type parameters in an abstract type choose a fresh type variable yourself and use the first form. To pattern-match on an arbitrary abstract type use

  <:typedef< ( $list:tpl$ ) $lid$ = '$oid$ $list:cl$>> when not (List.exists (fun (id,_) -> id = oid) tpl) -> ...
  

Exception definitions

6.4 Type expressions

• For tuple types anti-quotations one must use $tup:...$. The form $list:...$ stands for a type variable list in polymorphic record/method types.
• Type constructor application is internally always curried. Therefore there is no form like <:ptyp< ( $list:...$ ) $constr$ >>.
  The form <:ptyp< ( $arg$, $arg$, ... ) $constr$ >> is expanded (curried) in the quotation expander.
• There is only one internal form for object types (< ... >), the other forms are translated by the expander.
• Internally #-types have their own representation. The grammar rules with type arguments describe a type application with a #-type. (See also the note on curried type application above.)

Variant types

6.10 Module types (module specifications)

• In addition to the original syntax there is also the declare quotation from the revised syntax:

  <<:sig_item< declare $list:sig_items$ end >>
  <<:sig_item< declare $[sigi:]sig_item$ [;;] ... end >>
  

  with sig_items : sig_item list
• Internally, prefix and infix operators are just lowercase identifiers. There is a quotation form for every prefix and infix operator. However, there is no antiquotation for operators.
• Comments on the class_infos type are above.
• The signature items class-specification and classtype-definition are internally both described by an element of type class_type. The difference is that for class-specifications class valued function types are permitted, where for classtype-definitions they are not.
• The abstract module type specification module type S is internally represented as module type S = 'abstract. However, the module type 'abstract cannot be written in the original syntax (the revised syntax permits these type variable module types).
• The second form of the module declaration is syntactic sugar for the first one. Internally

  <:sig_item< module $[uid:]id$( $[uid:]id$ : $[mtyp:]mt$ ) : $[mtyp:]mt$ >>
  

  is represented as

  <:sig_item< module $[uid:]id$ : functor( $[uid:]id$ : $[mtyp:]mt$ ) -> $[mtyp:]mt$ >>
  

• for type-parameters in the with constraint the same forms are permitted as for the type-parameters in type declarations:
  •     (nothing)
  • [+/-] '$[lid:]id$  with id : string, for one type parameter
  • ( [+/-] '$[lid:]id$, ... )  with id : string, for a list of type parameters
  • ( $[list:]tpl$ )  with tpl : (string * (bool * bool)) list. Two booleans encode the variance: (false,false) for non-variant; (true,false) for positive; (false,true) for negative. tpl can of course be the empty list.

6.9.2 Class expressions

• The class_longident should consist of upper case identifiers, except for a last lower case identifier.
• Internally monomorphic and polymorphic class names are treated the same. The expander translates

  <:class_expr< $list:ids$ >>
  

  into

  <:class_expr< [ $list:[]$ ] $list:ids$ >>
  

• Class fun-bindings are internally curried. The expander converts

  <:class_expr< fun $p1$ $p2 -> $cexpr$ >>
  

  into

  <:class_expr< fun $p1$ -> fun $p2 -> $cexpr$ >>
  

• The self pattern in objects is stored as patt option in the ast. The form patt : ptyp is stored as a type annotated pattern.

• The expander permits declare from the revised syntax in the following forms

  <:class_str_item< declare $[cli:]cli$ ... >>; cli : class_field
  <:class_str_item< declare $list:clis$ >>; clis : class_field list
  

• The first form for the inherit field is the most general one. The other two forms are internally translated into the first.
• Similarly for value fields: The first form is the most general one.
• Type annotations for values and methods are internally represented with a type annotation on the right hand site.
• The parameters in non-polymorphic methods are syntactic sugar. Similarly to let a form

  <:class_str_item< method $id$ $p1$ $p2$ = $expr$ >>
  

  is internally represented as

  <:class_str_item< method $id$ = fun $p1$ -> fun $p2$ -> $expr$ >>
  

• Polymorphic and non-polymorphic methods are internally represented in the same way. The first quotation form of polymorphic methods also covers non-polymorphic methods via optyp = None. With antiquotations one can even use the syntactic sugar of parameter bindings (which is impossible in concrete syntax):

  <:class_str_item< method $opt:priv$ $id$ $opt:optyp$ $pat:a$ = $body$ >>
  

• The standard syntax parsers are lax and permit to swap the private and virtual tags. This quotation expander requires the order private virtual.

6.9.1 Class types

• There is only one internal representation for both polymorphic and monomorphic named class types. The expander translates the form

  <:class_type< $list:ids$ >>
  

  into

  <:class_type< [ $list:[]$ ] $list:ids$ >>
  

• The expander permits declare from the revised syntax in the following forms

  <:class_str_item< declare $[clsi:]clsi$ ... >>; clsi : class_sig_item
  <:class_str_item< declare $list:clsis$ >>; clsis : class_sig_item list
  

• The standard syntax parsers are lax and permit to swap the private and virtual tags. This quotation expander requires the order private virtual.

6.3 Names

Naming objects

Referring to named objects

6.1 Lexical conventions

Identifiers

Integer literals

Extensions for int32, int64 and nativeint Integer literals

Floating-point literals

Character literals

String literals

Naming labels

Prefix and infix symbols

Line number directives

6.5 Constants

6.9 Classes

6.9.2 Class expressions

Method definition

6.9.3 Class definitions

6.9.4 Class specification

6.9.5 Class type definitions

6.12 Compilation units

9. The toplevel system (ocaml)