Preprocessing in OCaml

The compiler pipeline

#define PI 3

return PI;

return 3;

#if OCAML_VERSION >= (4,13)
  | Type_variant (tll,_) ->  
#else
  | Type_variant tll ->
#endif
        do_something

# 764 "src/loader/cmi.ml"
  | Type_variant (tll,_) ->  

# 768 "src/loader/cmi.ml"
        do_something

module Pretty = struct
  #include "prettyprint.ml"
end

module Pretty = struct
# 1 "prettyprint.ml"
< content of the file >
# 1 "prettyprint.ml"
end

(x + 0) * (2 + 3)

List.map
  (fun x -> expr)
  (1 :: [])

float -> int option

module X = struct
  let n : float -> int option =
    expr
  let n2 : t = expr
end

What could go wrong?

Attributes, an attached Joker 🃏

Attributes are extra named Parsetree nodes that can be attached to a Parsetree node.

Expressions/types/...

g[@inlined] x

Structure/signature items

val f : int -> int
[@@ocaml.deprecated
  "Please use function g instead"]

Standalone

[@@@ocaml.warnings "-42"]

Extension nodes, a replacing Joker 🃏

Extension nodes are named Parsetree nodes that can replace a Parsetree node.

Expressions/types/...

1 + [%hello "world"]

Structure/signature items

module M = struct
  [%%rewrite_me let f x = x]

  let%rewrite_me f x = x
end

Back to restricting

We are going to restrict the transformation in:

• Their input: No full Parsetree as input. Context-free.

• Their effect: No full Parsetree as output. Local.

Examples

let before = 1

type foo = Bar of int | Baz [@@deriving show]

let after = 1

rewritten into

let before = 1

type foo =
  | Bar of int
  | Baz [@@deriving show]
let rec pp_foo : Format.formatter -> foo -> unit =
  fun fmt -> function
   | Bar a0 ->
       Format.fprintf fmt "(@[<2>Bar@ ";
       Format.fprintf fmt "%d" a0;
       Format.fprintf fmt "@])"
   | Baz -> Format.pp_print_string fmt "Baz"
and show_foo : foo -> string =
  fun x -> Format.asprintf "%a" pp_foo x

let after = 1

Examples

let before = 1

let to_ocaml = [%html "<a href='ocaml.org'>OCaml!</a>"]

let after = 1

rewritten into

let before = 1

let to_ocaml =
  Html.a ~a:[Html.a_href (Html.Xml.W.return "ocaml.org")]
    (Html.Xml.W.cons
       (Html.Xml.W.return (Html.txt (Html.Xml.W.return "OCaml!")))
       (Html.Xml.W.nil ()))

let after = 1

Derivers:

• ppx_deriving.show for deriving pretty printers.
• ppx_deriving.eq for deriving equality
• ppx_deriving.ord for deriving comparison
• ppx_deriving.enum for deriving enumerators
• ppx_deriving.iter for deriving iters
• ppx_deriving.map for deriving maps
• ppx_deriving.fold for deriving folds
• ppx_deriving.make for deriving constructors
• ppx_show for deriving pretty-printers
• ppx_yojson_conv for deriving json converters
• ppx_deriving_yaml for deriving yaml converters
• ppx_sexp_conv for deriving sexp converters
• ppx_accessor for deriving record accessors

Extenders:

Let's use some of them:

Let's write a deriver now 😱

Some comments:

• ppxlib has a documentation.

• Remembering how ppxlib and dune cooperate can help.

• The Parsetree is a big and unstable type.

• Ppxlib provides some stability (at the expense of a little complexity, especially for pattern-matching).

• Be careful with locations. Having them wrong can harm the user experience, with Merlin being confused.

• Be careful with shadowing. If you access a module, do not expect anymodule to be open, qualify everything completely, and do not shadow existing definition.