This chapter describes language extensions and convenience features that are implemented in OCaml, but not described in the OCaml reference manual.
(Introduced in Objective Caml 3.07)
|
An integer literal can be followed by one of the letters l, L or n to indicate that this integer has type int32, int64 or nativeint respectively, instead of the default type int for integer literals. The library modules Int32[Int32], Int64[Int64] and Nativeint[Nativeint] provide operations on these integer types.
(Removed in Objective Caml 3.03)
The syntax for streams and stream parsers is no longer part of the
OCaml language, but available through a Camlp4 syntax
extension. See the Camlp4 reference manual for more information.
Support for basic operations on streams is still available through the
Stream[Stream] module of the standard library.
OCaml programs
that use the stream parser syntax should be compiled with the
-pp camlp4o option to ocamlc and ocamlopt. For interactive use,
run ocaml and issue the #load "dynlink.cma";; command,
followed by the #load "camlp4o.cma";; command.
(Introduced in Objective Caml 1.00)
As mentioned in section 6.7.1, the let rec binding construct, in addition to the definition of recursive functions, also supports a certain class of recursive definitions of non-functional values, such as
which binds name1 to the cyclic list 1::2::1::2::…, and name2 to the cyclic list 2::1::2::1::…Informally, the class of accepted definitions consists of those definitions where the defined names occur only inside function bodies or as argument to a data constructor.
More precisely, consider the expression:
It will be accepted if each one of expr1 … exprn is statically constructive with respect to name1 … namen, is not immediately linked to any of name1 … namen, and is not an array constructor whose arguments have abstract type.
An expression e is said to be statically constructive with respect to the variables name1 … namen if at least one of the following conditions is true:
An expression e is said to be immediately linked to the variable name in the following cases:
(Introduced in Objective Caml 1.00)
|
In patterns, OCaml recognizes the form ' c ' .. ' d ' as shorthand for the pattern
where c1, c2, …, cn are the characters that occur between c and d in the ASCII character set. For instance, the pattern '0'..'9' matches all characters that are digits.
(Introduced in Objective Caml 1.06)
|
OCaml supports the assert construct to check debugging assertions. The expression assert expr evaluates the expression expr and returns () if expr evaluates to true. If it evaluates to false the exception Assert_failure is raised with the source file name and the location of expr as arguments. Assertion checking can be turned off with the -noassert compiler option. In this case, expr is not evaluated at all.
As a special case, assert false is reduced to raise (Assert_failure ...), which gives it a polymorphic type. This means that it can be used in place of any expression (for example as a branch of any pattern-matching). It also means that the assert false “assertions” cannot be turned off by the -noassert option.
(Introduced in Objective Caml 1.06)
|
The expression lazy expr returns a value v of type Lazy.t that encapsulates the computation of expr. The argument expr is not evaluated at this point in the program. Instead, its evaluation will be performed the first time the function Lazy.force is applied to the value v, returning the actual value of expr. Subsequent applications of Lazy.force to v do not evaluate expr again. Applications of Lazy.force may be implicit through pattern matching (see below).
(Introduced in Objective Caml 3.11)
|
The pattern lazy pattern matches a value v of type Lazy.t, provided pattern matches the result of forcing v with Lazy.force. A successful match of a pattern containing lazy sub-patterns forces the corresponding parts of the value being matched, even those that imply no test such as lazy value-name or lazy _. Matching a value with a pattern-matching where some patterns contain lazy sub-patterns may imply forcing parts of the value, even when the pattern selected in the end has no lazy sub-pattern.
For more information, see the description of module Lazy in the standard library ( Module Lazy).
(Introduced in Objective Caml 2.00)
|
The expression let module module-name = module-expr in expr locally binds the module expression module-expr to the identifier module-name during the evaluation of the expression expr. It then returns the value of expr. For example:
let remove_duplicates comparison_fun string_list =
let module StringSet =
Set.Make(struct type t = string
let compare = comparison_fun end) in
StringSet.elements
(List.fold_right StringSet.add string_list StringSet.empty)
(Introduced in Objective Caml 3.07)
|
Recursive module definitions, introduced by the module rec …and … construction, generalize regular module definitions module module-name = module-expr and module specifications module module-name : module-type by allowing the defining module-expr and the module-type to refer recursively to the module identifiers being defined. A typical example of a recursive module definition is:
module rec A : sig
type t = Leaf of string | Node of ASet.t
val compare: t -> t -> int
end
= struct
type t = Leaf of string | Node of ASet.t
let compare t1 t2 =
match (t1, t2) with
(Leaf s1, Leaf s2) -> Pervasives.compare s1 s2
| (Leaf _, Node _) -> 1
| (Node _, Leaf _) -> -1
| (Node n1, Node n2) -> ASet.compare n1 n2
end
and ASet : Set.S with type elt = A.t
= Set.Make(A)
It can be given the following specification:
module rec A : sig
type t = Leaf of string | Node of ASet.t
val compare: t -> t -> int
end
and ASet : Set.S with type elt = A.t
This is an experimental extension of OCaml: the class of recursive definitions accepted, as well as its dynamic semantics are not final and subject to change in future releases.
Currently, the compiler requires that all dependency cycles between the recursively-defined module identifiers go through at least one “safe” module. A module is “safe” if all value definitions that it contains have function types typexpr1 -> typexpr2. Evaluation of a recursive module definition proceeds by building initial values for the safe modules involved, binding all (functional) values to fun _ -> raise Undefined_recursive_module. The defining module expressions are then evaluated, and the initial values for the safe modules are replaced by the values thus computed. If a function component of a safe module is applied during this computation (which corresponds to an ill-founded recursive definition), the Undefined_recursive_module exception is raised.
Note that, in the specification case, the module-types must be parenthesized if they use the with mod-constraint construct.
Private type declarations in module signatures, of the form type t = private ..., enable libraries to reveal some, but not all aspects of the implementation of a type to clients of the library. In this respect, they strike a middle ground between abstract type declarations, where no information is revealed on the type implementation, and data type definitions and type abbreviations, where all aspects of the type implementation are publicized. Private type declarations come in three flavors: for variant and record types (section 7.9.1), for type abbreviations (section 7.9.2), and for row types (section 7.9.3).
(Introduced in Objective Caml 3.07)
|
Values of a variant or record type declared private can be de-structured normally in pattern-matching or via the expr . field notation for record accesses. However, values of these types cannot be constructed directly by constructor application or record construction. Moreover, assignment on a mutable field of a private record type is not allowed.
The typical use of private types is in the export signature of a module, to ensure that construction of values of the private type always go through the functions provided by the module, while still allowing pattern-matching outside the defining module. For example:
module M : sig
type t = private A | B of int
val a : t
val b : int -> t
end
= struct
type t = A | B of int
let a = A
let b n = assert (n > 0); B n
end
Here, the private declaration ensures that in any value of type M.t, the argument to the B constructor is always a positive integer.
With respect to the variance of their parameters, private types are handled like abstract types. That is, if a private type has parameters, their variance is the one explicitly given by prefixing the parameter by a ‘+’ or a ‘-’, it is invariant otherwise.
(Introduced in Objective Caml 3.11)
|
Unlike a regular type abbreviation, a private type abbreviation declares a type that is distinct from its implementation type typexpr. However, coercions from the type to typexpr are permitted. Moreover, the compiler “knows” the implementation type and can take advantage of this knowledge to perform type-directed optimizations. For ambiguity reasons, typexpr cannot be an object or polymorphic variant type, but a similar behaviour can be obtained through private row types.
The following example uses a private type abbreviation to define a module of nonnegative integers:
module N : sig
type t = private int
val of_int: int -> t
val to_int: t -> int
end
= struct
type t = int
let of_int n = assert (n >= 0); n
let to_int n = n
end
The type N.t is incompatible with int, ensuring that nonnegative integers and regular integers are not confused. However, if x has type N.t, the coercion (x :> int) is legal and returns the underlying integer, just like N.to_int x. Deep coercions are also supported: if l has type N.t list, the coercion (l :> int list) returns the list of underlying integers, like List.map N.to_int l but without copying the list l.
Note that the coercion ( expr :> typexpr ) is actually an abbreviated form, and will only work in presence of private abbreviations if neither the type of expr nor typexpr contain any type variables. If they do, you must use the full form ( expr : typexpr1 :> typexpr2 ) where typexpr1 is the expected type of expr. Concretely, this would be (x : N.t :> int) and (l : N.t list :> int list) for the above examples.
(Introduced in Objective Caml 3.09)
|
Private row types are type abbreviations where part of the structure of the type is left abstract. Concretely typexpr in the above should denote either an object type or a polymorphic variant type, with some possibility of refinement left. If the private declaration is used in an interface, the corresponding implementation may either provide a ground instance, or a refined private type.
module M : sig type c = private < x : int; .. > val o : c end =
struct
class c = object method x = 3 method y = 2 end
let o = new c
end
This declaration does more than hiding the y method, it also makes the type c incompatible with any other closed object type, meaning that only o will be of type c. In that respect it behaves similarly to private record types. But private row types are more flexible with respect to incremental refinement. This feature can be used in combination with functors.
module F(X : sig type c = private < x : int; .. > end) =
struct
let get_x (o : X.c) = o#x
end
module G(X : sig type c = private < x : int; y : int; .. > end) =
struct
include F(X)
let get_y (o : X.c) = o#y
end
Polymorphic variant types can be refined in two ways, either to allow the addition of new constructors, or to allow the disparition of declared constructors. The second case corresponds to private variant types (one cannot create a value of the private type), while the first case requires default cases in pattern-matching to handle addition.
type t = [ `A of int | `B of bool ] type u = private [< t > `A ] type v = private [> t ]
With type u, it is possible to create values of the form (`A n), but not (`B b). With type v, construction is not restricted but pattern-matching must have a default case.
Similarly to abstract types, the variance of type parameters is not inferred, and must be given explicitly.
(Introduced in OCaml 3.12)
|
The expressions let open module-path in expr and module-path.( expr) are strictly equivalent. They locally open the module referred to by the module path module-path in the scope of the expression expr.
Restricting opening to the scope of a single expression instead of a whole structure allows one to benefit from shorter syntax to refer to components of the opened module, without polluting the global scope. Also, this can make the code easier to read (the open statement is closer to where it is used) and to refactor (because the code fragment is more self-contained).
(Introduced in OCaml 3.12)
|
In a record pattern or a record construction expression, a single identifier id stands for id = id, and a qualified identifier module-path . id stands for module-path . id = id. For example, assuming the record type
type point = { x: float; y: float }
has been declared, the following expressions are equivalent:
let x = 1 and y = 2 in { x = x; y = y }
let x = 1 and y = 2 in { x; y }
let x = 1 and y = 2 in { x = x; y }
Likewise, the following functions are equivalent:
fun {x = x; y = y} -> x + y
fun {x; y} -> x + y
Optionally, a record pattern can be terminated by ; _ to convey the fact that not all fields of the record type are listed in the record pattern and that it is intentional. By default, the compiler ignores the ; _ annotation. If warning 9 is turned on, the compiler will warn when a record pattern fails to list all fields of the corresponding record type and is not terminated by ; _. Continuing the point example above,
fun {x} -> x + 1
will warn if warning 9 is on, while
fun {x; _} -> x + 1
will not warn. This warning can help spot program points where record patterns may need to be modified after new fields are added to a record type.
(Introduced in OCaml 3.12)
|
Polymorphic type annotations in let-definitions behave in a way similar to polymorphic methods: they explicitly require the defined value to be polymorphic, and allow one to use this polymorphism in recursive occurrences (when using let rec). Note however that this is a normal polymorphic type, unifiable with any instance of itself.
There are two possible applications of this feature. One is polymorphic recursion:
type 'a t = Leaf of 'a | Node of ('a * 'a) t
let rec depth : 'a. 'a t -> 'b = function
Leaf _ -> 1
| Node x -> 1 + depth x
Note that 'b is not explicitly polymorphic here, and it will actually be unified with int.
The other application is to ensure that some definition is sufficiently polymorphic.
# let id : 'a. 'a -> 'a = fun x -> x+1 ;; Error: This definition has type int -> int which is less general than 'a. 'a -> 'a
(Introduced in OCaml 3.12)
|
The expression fun ( type typeconstr-name ) -> expr introduces a type constructor named typeconstr-name which is considered abstract in the scope of the sub-expression, but then replaced by a fresh type variable. Note that contrary to what the syntax could suggest, the expression fun ( type typeconstr-name ) -> expr itself does not suspend the evaluation of expr as a regular abstraction would. The syntax has been chosen to fit nicely in the context of function declarations, where it is generally used. It is possible to freely mix regular function parameters with pseudo type parameters, as in:
let f = fun (type t) (foo : t list) -> ...
and even use the alternative syntax for declaring functions:
let f (type t) (foo : t list) = ...
This construction is useful because the type constructor it introduces can be used in places where a type variable is not allowed. For instance, one can use it to define an exception in a local module within a polymorphic function.
let f (type t) () =
let module M = struct exception E of t end in
(fun x -> M.E x), (function M.E x -> Some x | _ -> None)
Here is another example:
let sort_uniq (type s) (cmp : s -> s -> int) =
let module S = Set.Make(struct type t = s let compare = cmp end) in
fun l ->
S.elements (List.fold_right S.add l S.empty)
It is also extremely useful for first-class modules and GADTs.
(Introduced in OCaml 4.00)
|
The (type typeconstr-name) syntax construction by itself does not make polymorphic the type variable it introduces, but it can be combined with explicit polymorphic annotations where needed. The above rule is provided as syntactic sugar to make this easier:
let rec f : type t1 t2. t1 * t2 list -> t1 = ...
is automatically expanded into
let rec f : 't1 't2. 't1 * 't2 list -> 't1 =
fun (type t1) (type t2) -> (... : t1 * t2 list -> t1)
The same feature is provided for method definitions. The method! form combines this extension with the “explicit overriding” extension described in section 7.18.
(Introduced in OCaml 3.12; pattern syntax and package type inference introduced in 4.00; structural comparison of package types introduced in 4.02.)
|
Modules are typically thought of as static components. This extension makes it possible to pack a module as a first-class value, which can later be dynamically unpacked into a module.
The expression ( module module-expr : package-type ) converts the module (structure or functor) denoted by module expression module-expr to a value of the core language that encapsulates this module. The type of this core language value is ( module package-type ). The package-type annotation can be omitted if it can be inferred from the context.
Conversely, the module expression ( val expr : package-type ) evaluates the core language expression expr to a value, which must have type module package-type, and extracts the module that was encapsulated in this value. Again package-type can be omitted if the type of expr is known.
The pattern ( module module-name : package-type ) matches a package with type package-type and binds it to module-name. It is not allowed in toplevel let bindings. Again package-type can be omitted if it can be inferred from the enclosing pattern.
The package-type syntactic class appearing in the ( module package-type ) type expression and in the annotated forms represents a subset of module types. This subset consists of named module types with optional constraints of a limited form: only non-parametrized types can be specified.
For type-checking purposes (and starting from OCaml 4.02), package types are compared using the structural comparison of module types.
In general, the module expression ( val expr : package-type ) cannot be used in the body of a functor, because this could cause unsoundness in conjunction with applicative functors. Since OCaml 4.02, this is relaxed in two ways: if package-type does not contain nominal type declarations (i.e. types that are created with a proper identity), then this expression can be used anywhere, and even if it contains such types it can be used inside the body of a generative functor, described in section 7.27. It can also be used anywhere in the context of a local module binding let module module-name = ( val expr1 : package-type ) in expr2.
A typical use of first-class modules is to select at run-time among several implementations of a signature. Each implementation is a structure that we can encapsulate as a first-class module, then store in a data structure such as a hash table:
module type DEVICE = sig ... end
let devices : (string, (module DEVICE)) Hashtbl.t = Hashtbl.create 17
module SVG = struct ... end
let _ = Hashtbl.add devices "SVG" (module SVG : DEVICE)
module PDF = struct ... end
let _ = Hashtbl.add devices "PDF" (module PDF: DEVICE)
We can then select one implementation based on command-line arguments, for instance:
module Device =
(val (try Hashtbl.find devices (parse_cmdline())
with Not_found -> eprintf "Unknown device %s\n"; exit 2)
: DEVICE)
Alternatively, the selection can be performed within a function:
let draw_using_device device_name picture =
let module Device =
(val (Hashtbl.find_devices device_name) : DEVICE)
in
Device.draw picture
With first-class modules, it is possible to parametrize some code over the implementation of a module without using a functor.
let sort (type s) (module Set : Set.S with type elt = s) l =
Set.elements (List.fold_right Set.add l Set.empty)
val sort : (module Set.S with type elt = 'a) -> 'a list -> 'a list
To use this function, one can wrap the Set.Make functor:
let make_set (type s) cmp =
let module S = Set.Make(struct
type t = s
let compare = cmp
end) in
(module S : Set.S with type elt = s)
val make_set : ('a -> 'a -> int) -> (module Set.S with type elt = 'a)
(Introduced in OCaml 3.12)
|
The construction module type of module-expr expands to the module type (signature or functor type) inferred for the module expression module-expr. To make this module type reusable in many situations, it is intentionally not strengthened: abstract types and datatypes are not explicitly related with the types of the original module. For the same reason, module aliases in the inferred type are expanded.
A typical use, in conjunction with the signature-level include construct, is to extend the signature of an existing structure. In that case, one wants to keep the types equal to types in the original module. This can done using the following idiom.
module type MYHASH = sig
include module type of struct include Hashtbl end
val replace: ('a, 'b) t -> 'a -> 'b -> unit
end
The signature MYHASH then contains all the fields of the signature of the module Hashtbl (with strengthened type definitions), plus the new field replace. An implementation of this signature can be obtained easily by using the include construct again, but this time at the structure level:
module MyHash : MYHASH = struct
include Hashtbl
let replace t k v = remove t k; add t k v
end
Another application where the absence of strengthening comes handy, is to provide an alternative implementation for an existing module.
module MySet : module type of Set = struct
...
end
This idiom guarantees that Myset is compatible with Set, but allows it to represent sets internally in a different way.
(Introduced in OCaml 3.12)
|
“Destructive” substitution (with ... := ...) behaves essentially like normal signature constraints (with ... = ...), but it additionally removes the redefined type or module from the signature. There are a number of restrictions: one can only remove types and modules at the outermost level (not inside submodules), and in the case of with type the definition must be another type constructor with the same type parameters.
A natural application of destructive substitution is merging two signatures sharing a type name.
module type Printable = sig
type t
val print : Format.formatter -> t -> unit
end
module type Comparable = sig
type t
val compare : t -> t -> int
end
module type PrintableComparable = sig
include Printable
include Comparable with type t := t
end
One can also use this to completely remove a field:
# module type S = Comparable with type t := int;;
module type S = sig val compare : int -> int -> int end
or to rename one:
# module type S = sig
type u
include Comparable with type t := u
end;;
module type S = sig type u val compare : u -> u -> int end
Note that you can also remove manifest types, by substituting with the same type.
# module type ComparableInt = Comparable with type t = int ;; module type ComparableInt = sig type t = int val compare : t -> t -> int end # module type CompareInt = ComparableInt with type t := int ;; module type CompareInt = sig val compare : int -> int -> int end
(Introduced in OCaml 4.02)
|
The above specification, inside a signature, only matches a module definition equal to module-path. Conversely, a type-level module alias can be matched by itself, or by any supertype of the type of the module it references.
There are several restrictions on module-path:
Such specifications are also inferred. Namely, when P is a path satisfying the above constraints,
# module N = P
has type
module N = P
Type-level module aliases are used when checking module path equalities. That is, in a context where module name N is known to be an alias for P, not only these two module paths check as equal, but F (N) and F (P) are also recognized as equal. In the default compilation mode, this is the only difference with the previous approach of module aliases having just the same module type as the module they reference.
When the compiler flag -no-alias-deps is enabled, type-level module aliases are also exploited to avoid introducing dependencies between compilation units. Namely, a module alias referring to a module inside another compilation unit does not introduce a link-time dependency on that compilation unit, as long as it is not dereferenced; it still introduces a compile-time dependency if the interface needs to be read, i.e. if the module is a submodule of the compilation unit, or if some type components are referred to. Additionally, accessing a module alias introduces a link-time dependency on the compilation unit containing the module referenced by the alias, rather than the compilation unit containing the alias. Note that these differences in link-time behavior may be incompatible with the previous behavior, as some compilation units might not be extracted from libraries, and their side-effects ignored.
These weakened dependencies make possible to use module aliases in place of the -pack mechanism. Suppose that you have a library Mylib composed of modules A and B. Using -pack, one would issue the command line
ocamlc -pack a.cmo b.cmo -o mylib.cmo
and as a result obtain a Mylib compilation unit, containing physically A and B as submodules, and with no dependencies on their respective compilation units. Here is a concrete example of a possible alternative approach:
module A = Mylib_A
module B = Mylib_B
ocamlc -c -no-alias-deps Mylib.ml
ocamlc -c -no-alias-deps -open Mylib Mylib_*.mli Mylib_*.ml
ocamlc -a Mylib*.cmo -o Mylib.cma
This approach lets you access A and B directly inside the library, and as Mylib.A and Mylib.B from outside. It also has the advantage that Mylib is no longer monolithic: if you use Mylib.A, only Mylib_A will be linked in, not Mylib_B.
(Introduced in OCaml 3.12)
|
The keywords inherit!, val! and method! have the same semantics as inherit, val and method, but they additionally require the definition they introduce to be an overriding. Namely, method! requires method-name to be already defined in this class, val! requires inst-var-name to be already defined in this class, and inherit! requires class-expr to override some definitions. If no such overriding occurs, an error is signaled.
As a side-effect, these 3 keywords avoid the warnings 7 (method override) and 13 (instance variable override). Note that warning 7 is disabled by default.
(Introduced in OCaml 4.01)
|
Since OCaml 4.01, open statements shadowing an existing identifier (which is later used) trigger the warning 44. Adding a ! character after the open keyword indicates that such a shadowing is intentional and should not trigger the warning.
(Introduced in OCaml 4.00)
|
Generalized algebraic datatypes, or GADTs, extend usual sum types in two ways: constraints on type parameters may change depending on the value constructor, and some type variables may be existentially quantified. Adding constraints is done by giving an explicit return type (the rightmost typexpr in the above syntax), where type parameters are instantiated. This return type must use the same type constructor as the type being defined, and have the same number of parameters. Variables are made existential when they appear inside a constructor’s argument, but not in its return type.
Since the use of a return type often eliminates the need to name type parameters in the left-hand side of a type definition, one can replace them with anonymous types _ in that case.
The constraints associated to each constructor can be recovered through pattern-matching. Namely, if the type of the scrutinee of a pattern-matching contains a locally abstract type, this type can be refined according to the constructor used. These extra constraints are only valid inside the corresponding branch of the pattern-matching. If a constructor has some existential variables, fresh locally abstract types are generated, and they must not escape the scope of this branch.
Here is a concrete example:
type _ term =
| Int : int -> int term
| Add : (int -> int -> int) term
| App : ('b -> 'a) term * 'b term -> 'a term
let rec eval : type a. a term -> a = function
| Int n -> n (* a = int *)
| Add -> (fun x y -> x+y) (* a = int -> int -> int *)
| App(f,x) -> (eval f) (eval x)
(* eval called at types (b->a) and b for fresh b *)
let two = eval (App (App (Add, Int 1), Int 1))
val two : int = 2
Type inference for GADTs is notoriously hard. This is due to the fact some types may become ambiguous when escaping from a branch. For instance, in the Int case above, n could have either type int or a, and they are not equivalent outside of that branch. As a first approximation, type inference will always work if a pattern-matching is annotated with types containing no free type variables (both on the scrutinee and the return type). This is the case in the above example, thanks to the type annotation containing only locally abstract types.
In practice, type inference is a bit more clever than that: type annotations do not need to be immediately on the pattern-matching, and the types do not have to be always closed. As a result, it is usually enough to only annotate functions, as in the example above. Type annotations are propagated in two ways: for the scrutinee, they follow the flow of type inference, in a way similar to polymorphic methods; for the return type, they follow the structure of the program, they are split on functions, propagated to all branches of a pattern matching, and go through tuples, records, and sum types. Moreover, the notion of ambiguity used is stronger: a type is only seen as ambiguous if it was mixed with incompatible types (equated by constraints), without type annotations between them. For instance, the following program types correctly.
let rec sum : type a. a term -> _ = fun x ->
let y =
match x with
| Int n -> n
| Add -> 0
| App(f,x) -> sum f + sum x
in y + 1
val sum : 'a term -> int = <fun>
Here the return type int is never mixed with a, so it is seen as non-ambiguous, and can be inferred. When using such partial type annotations we strongly suggest specifying the -principal mode, to check that inference is principal.
The exhaustiveness check is aware of GADT constraints, and can automatically infer that some cases cannot happen. For instance, the following pattern matching is correctly seen as exhaustive (the Add case cannot happen).
let get_int : int term -> int = function
| Int n -> n
| App(_,_) -> 0
The term type we have defined above is an indexed type, where a type parameter reflects a property of the value contents. Another use of GADTs is singleton types, where a GADT value represents exactly one type. This value can be used as runtime representation for this type, and a function receiving it can have a polytypic behavior.
Here is an example of a polymorphic function that takes the runtime representation of some type t and a value of the same type, then pretty-prints the value as a string:
type _ typ =
| Int : int typ
| String : string typ
| Pair : 'a typ * 'b typ -> ('a * 'b) typ
let rec to_string: type t. t typ -> t -> string =
fun t x ->
match t with
| Int -> string_of_int x
| String -> Printf.sprintf "%S" x
| Pair(t1,t2) ->
let (x1, x2) = x in
Printf.sprintf "(%s,%s)" (to_string t1 x1) (to_string t2 x2)
Another frequent application of GADTs is equality witnesses.
type (_,_) eq = Eq : ('a,'a) eq
let cast : type a b. (a,b) eq -> a -> b = fun Eq x -> x
Here type eq has only one constructor, and by matching on it one adds a local constraint allowing the conversion between a and b. By building such equality witnesses, one can make equal types which are syntactically different.
Here is an example using both singleton types and equality witnesses to implement dynamic types.
let rec eq_type : type a b. a typ -> b typ -> (a,b) eq option =
fun a b ->
match a, b with
| Int, Int -> Some Eq
| String, String -> Some Eq
| Pair(a1,a2), Pair(b1,b2) ->
begin match eq_type a1 b1, eq_type a2 b2 with
| Some Eq, Some Eq -> Some Eq
| _ -> None
end
| _ -> None
type dyn = Dyn : 'a typ * 'a -> dyn
let get_dyn : type a. a typ -> dyn -> a option =
fun a (Dyn(b,x)) ->
match eq_type a b with
| None -> None
| Some Eq -> Some x
(Introduced in Objective Caml 3.00)
|
This extension provides syntactic sugar for getting and setting elements in the arrays provided by the Bigarray[Bigarray] library.
The short expressions are translated into calls to functions of the Bigarray module as described in the following table.
| expression | translation |
| expr0.{ expr1} | Bigarray.Array1.get expr0 expr1 |
| expr0.{ expr1} <- expr | Bigarray.Array1.set expr0 expr1 expr |
| expr0.{ expr1, expr2} | Bigarray.Array2.get expr0 expr1 expr2 |
| expr0.{ expr1, expr2} <- expr | Bigarray.Array2.set expr0 expr1 expr2 expr |
| expr0.{ expr1, expr2, expr3} | Bigarray.Array3.get expr0 expr1 expr2 expr3 |
| expr0.{ expr1, expr2, expr3} <- expr | Bigarray.Array3.set expr0 expr1 expr2 expr3 expr |
| expr0.{ expr1, …, exprn} | Bigarray.Genarray.get expr0 [| expr1, … , exprn |] |
| expr0.{ expr1, …, exprn} <- expr | Bigarray.Genarray.set expr0 [| expr1, … , exprn |] expr |
The last two entries are valid for any n > 3.
(Introduced in OCaml 4.02)
Attributes are “decorations” of the syntax tree which are mostly ignored by the type-checker but can be used by external tools. An attribute is made of an identifier and a payload, which can be a structure, a type expression (prefixed with :) or a pattern (prefixed with ?) optionally followed by a when clause:
|
The first form of attributes is attached with a postfix notation on “algebraic” categories:
|
This form of attributes can also be inserted after the `tag-name in polymorphic variant type expressions (tag-spec-first, tag-spec, tag-spec-full) or after the method-name in method-type.
The same syntactic form is also used to attach attributes to labels and constructors in type declarations:
|
The second form of attributes are attached to “blocks” such as type declarations, class fields, etc:
A third form of attributes appears as stand-alone structure or signature items in the module or class sub-languages. They are not attached to any specific node in the syntax tree:
|
(Note: contrary to what the grammar above describes, item-attributes cannot be attached to these floating attributes in class-field-spec and class-field.)
It is also possible to specify attributes on expressions using an infix syntax. This applies to all expressions starting with one or two keywords: assert, begin, for, fun, function, if, lazy, let, let module, let open, match, new, object, try, while. Those expressions supports adding one or several attributes just after those initial keyword(s). For instance:
let [@foo][@bar x] x = 2 in x + 1 === (let x = 2 in x + 1)[@foo][@bar x] begin[@foo] ... end === (begin ... end)[@foo]
Some attributes are understood by the type-checker:
module X = struct [@@warning "+9"] (* locally enable warning 9 in this structure *) ... end let x = begin[@warning "+9] ... end in .... type t = A | B [@@deprecated "Please use type 's' instead.] let f x = assert (x >= 0) [@ppwarning "TODO: remove this later"]; ....
(Introduced in OCaml 4.02)
Extension nodes are generic placeholders in the syntax tree. They are rejected by the type-checker and are intended to be “expanded” by external tools such as -ppx rewriters.
Extension nodes share the same notion of identifier and payload as attributes 7.22.
The first form of extension node is used for “algebraic” categories:
|
A second form of extension node can be used in structures and signatures, both in the module and object languages:
|
An infix form is available for extension nodes as expressions, when the payload is a single expression. This form applies to all expressions starting with one or two keywords: the percent sign and then and extension identifier follow immediately the initial keyword(s).
Examples:
let%foo x = 2 in x + 1 === [%foo let x = 2 in x + 1] begin%foo ... end === [%foo begin ... end]
When this form is used together with the infix syntax for attributes, the attributes are considered to apply to the payload:
begin%foo[@bar] ... end === [%foo (let x = 2 in x + 1) [@bar]]
(Introduced in OCaml 4.02)
Quoted strings provide a different lexical syntax to write string literals in OCaml code. This can be used to embed pieces of foreign syntax fragments in OCaml code, to be interpret by a -ppx filter or just a library.
|
The opening delimiter has the form {id| where id is a (possibly empty) sequence of lowercase letters and underscores. The corresponding closing delimiter is |id} (with the same identifier). Unlike regular OCaml string literals, quoted strings do not interpret any character in a special way.
Example:
String.length {|\"|} (* returns 2 *)
String.length {foo|\"|foo} (* returns 2 *)
(Introduced in OCaml 4.02)
A new form of exception patterns is allowed, only as a toplevel pattern under a match...with pattern-matching (other occurrences are rejected by the type-checker).
|
Cases with such a toplevel pattern are called “exception cases”, as opposed to regular “value cases”. Exception cases are applied when the evaluation of the matched expression raises an exception. The exception value is then matched against all the exception cases and re-raised if none of them accept the exception (as for a try...with block). Since the bodies of all exception and value cases is outside the scope of the exception handler, they are all considered to be in tail-position: if the match...with block itself is in tail position in the current function, any function call in tail position in one of the case bodies results in an actual tail call.
It is an error if all cases are exception cases in a given pattern matching.
(Introduced in OCaml 4.02)
|
Extensible variant types are variant types which can be extended with new variant constructors. Extensible variant types are defined using ... New variant constructors are added using +=.
type attr = ..
type attr += Str of string
type attr +=
| Int of int
| Float of float
Pattern matching on an extensible variant type requires a default case to handle unknown variant constructors:
let to_string = function
| Str s -> s
| Int i -> string_of_int i
| Float f -> string_of_float f
| _ -> "?"
A preexisting example of an extensible variant type is the built-in exn type used for exceptions. Indeed, exception constructors can be declared using the type extension syntax:
type exn += Exc of int
Extensible variant constructors can be rebound to a different name. This allows exporting variants from another module.
type Expr.attr += Str = Expr.Str
Extensible variant constructors can be declared private. As with regular variants, this prevents them from being constructed directly by constructor application while still allowing them to be de-structured in pattern-matching.
(Introduced in OCaml 4.02)
|
A generative functor takes a unit () argument. In order to use it, one must necessarily apply it to this unit argument, ensuring that all type components in the result of the functor behave in a generative way, i.e. they are different from types obtained by other applications of the same functor. This is equivalent to taking an argument of signature sig end, and always applying to struct end, but not to some defined module (in the latter case, applying twice to the same module would return identical types).
As a side-effect of this generativity, one is allowed to unpack first-class modules in the body of generative functors.