package metapp

metapp: meta-preprocessor for OCaml

metapp is a PPX rewriter that provides a [%meta ...] extension, where the dots ... are arbitrary OCaml expressions that are substituted at compile-time by the AST nodes they evaluate into. These expressions build AST nodes either by quoting some code directly, or by using compiler-libs (Parsetree, Ast_helper, ...).

In particular, this preprocessor is easy to use for conditional compilation, and is an alternative to cppo and ppx_optcomp.

let option_get o =
  [%meta if Sys.ocaml_version >= "4.08.0" then
     [%e Option.get o]
  else
     [%e match o with
     | None -> invalid_arg "option_get"
     | Some x -> x]]

metapp can be used with dune by using the preprocess field.

(executable
  ...
  (preprocess (pps metapp.ppx))
  ...)

Inside [%meta ...] code, the [%e ...] extension quotes expressions (of type [Parsetree.expression]). There are other quotations available: the full list is given below.

Quoted expressions can in turn contain further [%meta ...] code. Moreover, [%meta ...] code can itself contain other levels of [%meta ...] code, for multi-stage programming.

In addition to this syntax extension, the Metapp module provided by the metapp package provides convenient functions for AST constructions. In particular, this module provides an OCaml-version-independent interface. Moveover, this module provides a common signature ValueS for constructing and transforming expressions (module Exp), patterns (module Pat) or both at the same time (module Value).

The Metapp module also provides a filter mapper, which handles [@if <bool>] attributes à la ppx_optcomp. The [@if <bool>] attribute can appear mostly everywhere syntax elements are enumerated, including tuples, function applications, arrays, etc.

[%%meta Metapp.include_structure (
  Metapp.filter.structure Metapp.filter [%str
    type t =
    | A of int
    | B of int * int
        [@if [%meta Metapp.Exp.of_bool (Sys.ocaml_version >= "4.04.0")]]
    ...

    match (v: t) with
    | A x -> something x
    | B (y,z)
      [@if [%meta Metapp.Exp.of_bool (Sys.ocaml_version >= "4.04.0")]] ->
        something' y z
    ... ])]

Global definitions for meta-code can be included with [%%metadef ...]. By default, the meta-code is compiled with the compiler-libs package. Other packages can be loaded with [%%metapackage ...]. More generally, flags can be passed to the compiler to compile meta-code with [%%metaflag ...] (there is another convenient notation for adding interface directories: [%%metadir ...]). [%%metaload ...] loads a particular compilation unit. For instance, [%%metapackage metapp] links the meta-code with the metapp package in order to use the Metapp module. All these notations can be applied to multiple arguments at once by using comma as separator.

Note that dynamic package loading is broken in PPX with dune (#3214). When packages are loaded with [%%metapackage ...], a workaround (see discussion) is used to load the packages correctly, but only with OCaml >=4.08. If you need to use [%%metapackage ...] with a prior version of OCaml, you still can statically link the packages you need by listing them in the (preprocess (pps ...)) list. You will still have to import them with [%%metapackage ...] to let the compiler see their interface when compiling the meta-code.

Compilation commands can be logged by adding [%%metaverbose] to the preprocessed file.