deriving examples

Pretty printing

The deriving preprocessor and library provide common functionality which has an obvious definition at most types. For example, it's usually easy, although tedious, to write a to_string function for a new type you've defined; deriving will save you the trouble by writing the function for you automatically. To call a deriving function at a particular type you use a special notation:

Class.method<type> argument

(Note that the terms "Class" and "method" are taken from Haskell's type classes, and has nothing to do with OCaml's object-oriented class system.)

For example, to call the show method of the Show class to convert an integer to a string you would write:

Show.show<int> 3
=>
"3"

You can also specify more complex types:

let factors = [(10,[2;5]); (11, []);  12, [2;3;4;6]]

Show.show<(int * int list) list> factors
=>
"[(10,[2; 5]); (11, []);  12, [2; 3; 4; 6]]"

To use a deriving function at a type you've defined, you need to add the phrase deriving (Class) to the end of your type definition. For example,

type 'a tree = Leaf of 'a | Branch of 'a tree * 'a * 'a tree
     deriving (Show)

 type point = { x : float; y : float }
     deriving (Show)

 let points = Branch (Leaf {x=0.0;
                            y=0.0;},
                      {x=2.0; y=2.0},
                      Branch (Leaf {x=1.0; y=1.0},
                              {x=1.0; y=0.0},
                              Leaf {x=0.0; y=1.0}))

Show.show<point tree> points
=>
"Branch
   (Leaf {x =193.11; y =132.13}, {x =211.91; y =201.11},
    Branch
      (Leaf {x =113.12; y =1.}, {x =12.7; y =44.1}, Leaf {x =0.; y
      =13.41}))"

If you want to show values of an abstract type defined in a module outside the module you should add the deriving annotation to the signature as well:

module IntStack : sig
  type t
    deriving (Show)

  val empty : t
  val push : int -> t -> t
  val top : t -> int
  val pop : t -> t
end =
struct
  type t = Stack of int list
     deriving (Show)
  let empty = Stack []
  let push item (Stack list) = Stack (item::list)
  let top (Stack (top::_)) = top
  let pop (Stack (_::rest)) = Stack rest
end

Show.show<IntStack.t>
  (IntStack.push 3 (IntStack.push 4 (IntStack.push 5 IntStack.empty)))
=>
"Stack [3; 4; 5]"

You can derive Show for most types, including recursive (and mutually recursive) types, normal and polymorphic variants, records, tuples and types containing other types for which Show has been derived. You can't derive Show for functions because there's usually no meaningful way to display them. If you have a way to display values of a type for which Show cannot be derived then you can always write your own definition and make it available to deriving; see the section "Extending definitions".

Dynamic typing

The `Typeable' class provides operations for converting between a universal type `dynamic' and any other type. Converting from dynamic to another type succeeds only if the type specified in the conversion matches the type used to create the dynamic value. The upcast operation is called mk (or make_dynamic if you prefer to be verbose). The downcasts are cast, which returns an option value, and throwing_cast, which throws an exception if the downcast fails.

type 'a tree = Leaf of 'a | Branch of 'a tree * 'a * 'a tree
  deriving (Typeable)

let items =
   [Typeable.mk<int> 3;
    Typeable.mk<float> 3.0;
    Typeable.mk<string tree> (Leaf "three")]
=>
[<abstr>; <abstr>; <abstr>]

Typeable.cast<int> (List.hd items)
=>
Some 3

Typeable.throwing_cast<int> (List.hd items)
=>
3

Typeable.cast<float> (List.hd items)
=>
None

Typeable.throwing_cast<float> (List.hd items)
=>
Exception: Typeable.CastFailure "cast failed".

Casts also work between equivalent polymorphic variant types (even if the types used for the upcast and downcast are defined differently):

type 'a seq = [`Nil | `Cons of 'a * 'a seq]
    deriving (Typeable)

let l = `Cons (3, `Cons (2, `Cons (1, `Nil)))

Typeable.cast<[`Cons of int * 'a|`Nil] as 'a>
  (Typeable.mk<int seq> l)
=>
Some (`Cons (3, `Cons (2, `Cons (1, `Nil))))

Casts don't work between record or normal variant types which are defined separately, even if the definitions are identical.

type complex = {x : float; y : float}
  deriving (Typeable)


type point = {x : float; y : float}
  deriving (Typeable)

Typeable.cast<point> (Typeable.mk<complex> {x : -1.0; y : 0.0})
=>
None

However, abstraction using module signatures does not change whether types are interconvertible, so you can use Typeable to access the representation of an abstract type if you know it.

module T :
sig
  type t
    deriving (Typeable)
  val v : t
end =
struct
  type t = int
  val v = 12
end

Typeable.cast<int> (Typeable.mk<T.t> T.v)
=>
12

Equality

There are two polymorphic equality operators in OCaml:

= tests for structural equality. == tests for physical equality. Sometimes neither of these is appropriate. Instead, we want to test for structural equality at immutable types and physical equality (identity) at mutable types (as in SML). This sort of equality tests whether two values can be used interchangeably in a program.

Eq.eq<int ref> (ref 1) (ref 1)
=>
false

let x = ref 1 in Eq.eq<int ref> x x
=>
true

Eq.eq<int list> [1;2;3] [1;2;3]
=>
true

type mpoint = { mutable x : float; mutable y : float}
    deriving (Eq)

Eq.eq<mpoint> {x = 1.0; y = 2.0} {x = 1.0; y = 2.0}
=>
false

let p = {x = 1.0; y = 2.0} in Eq.eq<mpoint> p p
=>
true

type ipoint = { x : float; y : float}
    deriving (Eq)

Eq.eq<ipoint> {x = 1.0; y = 2.0} {x = 1.0; y = 2.0}
=>
true

Serialisation

The `Pickle' class provides operations for structure-sharing serialisation (marshalling). If any value to be serialised contains two equal subvalues then only one copy of the subvalue will be serialised. Cycles that are created by mutable record fields, including references, are preserved.

All "instances" of Pickle must also be "instances" of Eq and Typeable. (As in Haskell, we use "instance" to mean a set of functions that implement the methods of a class at a particular type.)

type 'a tree = Leaf of 'a | Branch of 'a tree * 'a * 'a tree
  deriving (Eq, Typeable, Pickle)

type point = { x : float; y : float }
    deriving (Eq, Typeable, Pickle)

Pickle.to_string<point tree> points
=>
"\007\003\t\128\128\128\128\128\128\128\248?\t\128\128\128\128\128\128\128\128@\001\000\005\000\001\008\000\001\n\001\003\004\t\003\000\001\012\001\003\006\011\005\005\002\002\000\002\000\002\002\000\000\002\001\001\002\002\002"

Pickle.from_string<point tree> (Pickle.to_string<point tree> points)
=>
Branch
  (Leaf {x =193.11; y =132.13}, {x =211.91; y =201.11},
   Branch
     (Leaf {x =113.12; y =1.}, {x =12.7; y =44.1}, Leaf {x =0.; y =13.41}))

You can supply a custom definition of equality (see the section "Extending definitions") to increase sharing: see the file tests/exp.ml in the distribution for an example.

There is another class, `Dump', that provides simpler value-oriented serialisation, but doesn't deal with references or cycles.

Map

Given a type ('a1,...,'an) t, the `Functor' class will derive a map operation:

val map : ('a1->'b1) -> ... ('an->'bn} -> ('a1,...,'an) t -> ('b1,...,'bn) t

For example,

type 'a tree = Leaf of 'a | Branch of 'a tree * 'a * 'a tree
  deriving (Functor)

Functor_tree.map ((+) 1) (Branch (Leaf 3, 4, Leaf 5))
=>
(Branch (Leaf 4, 5, Leaf 6))

The <t> notation is not currently available for Functor.

Enumerations

Enumerations provide several operations for dealing with variant types where all constructors have no argument.

Enum.enum_from_to<int> 0 10
=>
[0; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10]

type fruit = Apple | Orange | Banana | Kiwi
   deriving (Enum)

Enum.enum_from_to<fruit> Apple Kiwi
=>
[Apple; Orange; Banana; Kiwi]

Enum.succ<fruit> Orange
=>
Banana

Minimum and maximum values

Instances of bounded have maximum and minimum values:

type fruit = Apple | Orange | Banana | Kiwi
   deriving (Bounded)

(Bounded.min_bound<int * fruit>, Bounded.max_bound<int * fruit>)
=>
((-1073741824, Apple), (1073741823, Kiwi))

Extending definitions

Instead of deriving a definition automatically you can provide your own by writing a module with the same signature as the standard definitions with a name formed from the class name, an underscore, and the name of the type constructor for which you want to provide the definition.

module Eq_fruit
  : Eq.Eq with type a = fruit =
Eq.Defaults(struct
  type a = fruit
  let eq l r = match l, r with
   | Apple  , Orange
   | Orange , Apple
   | Apple  , Apple
   | Orange , Orange
   | Banana , Banana
   | Kiwi   , Kiwi   -> true
   | _               -> false
end)

Eq.eq<fruit list> [Apple; Orange; Banana] [Orange; Orange; Banana]
=>
true