#### refl

`refl`

provides runtime representations for most OCaml types, and a

"one size fits all" deriving plugin.

This plugin automatically derives runtime type

representations from type declarations, allowing most other deriving

plugins to be rewritten as regular OCaml functions parametized by

these runtime representations.

The library also provides such functions which provides flexible

alternatives to `ppx_deriving`

standard plugins: `show`

, `compare`

,`eq`

, `map`

, `iter`

, `fold`

, `enum`

, `make`

.

Once `refl`

is derived for a given type, values of this type can be

used on all (compatible) functions. This is the main motivation behind`refl`

: instead of having to decide which derivers to use at the

type declaration point, it is sufficient to derive only `refl`

, and

then this type can be used with all functions operating on such

runtime representations, even functions that are defined after the

type declaration.

`refl`

can be used with `dune`

by using the `preprocess`

field.

```
(executable
...
(preprocess (pps refl.ppx))
(libraries ... refl ...))
```

## Basic usage

The following example declares a type for binary trees along with its

runtime representation.

```
type 'a binary_tree =
| Leaf
| Node of { left : 'a binary_tree; label : 'a; right : 'a binary_tree }
[@@deriving refl]
```

The function `Refl.show`

can be used to print such trees, the function`Refl.compare`

can be used to compare two binary trees, the function`Refl.map`

can be used to change labels, etc. For instance:

```
# Refl.show [%refl: string binary_tree] []
(Node { left = Leaf; label = "root"; right = Leaf });;
- : string = "Node { left = Leaf; label = \"root\"; right = Leaf }"
```

Built-in types can be used directly without prior declaration.

```
# Refl.show [%refl: (string * int) list] [] ["a", 1; "b", 2];;
- : string = "[(\"a\", 1); (\"b\", 2)]"
```

When a type contains type variables, custom printers for these

variables should be listed in the second argument of `Refl.show`

.

```
# Refl.show [%refl: _ list] [Some Format.pp_print_string] ["a"; "b"; "c"];;
- : string = "[a; b; c]"
```

The custom printers are optional for skipping "shadow" type variables,

that is to say type variables that are not used to type

sub-values. This will be particularly useful for GADTs.

Typically, shadow type variables appear in GADTs as

indexes. For instance, consider the following definition for

fixed-length vector.

```
type ('a, 'length) vector =
| [] : ('a, [`Zero]) vector
| (::) : 'a * ('a, 'length) vector -> ('a, [`Succ of 'length]) vector
[@@deriving refl]
```

When applying `Refl.show`

to vectors, `None`

can be passed for the printer

of the second parameter (`'length`

), since it will never be used.

```
# Refl.show [%refl: (_, _) vector] [Some Format.pp_print_string; None]
["a"; "b"; "c"];;
- : string = "[a; b; c]"
```

Another example of function is `Refl.map`

, that applies a given

function for each type variables.

```
# Refl.map [%refl: _ binary_tree] [%refl: _ binary_tree] [P string_of_int]
(Node { left = Leaf; label = 1; right = Leaf });;
- : string binary_tree = Node {left = Leaf; label = "1"; right = Leaf}
```

Note that the reflexive representation keeps track whether type variables

occur positively or negatively.

The `P`

constructor above marks functions appliable to type variables that

appear positively (outside arrow types or at the right-hand side of arrow types).

For types that appear negatively, functions in the reverse direction should be

provided, marked with `N`

.

For types that appear both positively and negatively, a pair of functions for

both directions should be provided, marked with `PN`

.

## Type constraints

Functions can require constraints to be satisfied by the type to be

applicable: for instance, the function `compare`

requires that the

type contains no arrows unless they are hidden by an `[@opaque]`

attribute.

sha512=c158970749c1b7bacb8af1f88f0304d8d6cb0f532d3f876734489c3c4220d00f4d5aac6066e6d385ee70e1810ec65ffd47f0197bd5a6080f4d688cb3a386dc0a

with-doc & >= "1.5.1"

>= "0.3.0"

>= "0.4.0"

>= "0.4.0"

>= "0.18.0" & < "0.26.0"

>= "20200131"

>= "14"

>= "1.11.0"

>= "4.08.0"