Module Ppx_core.Ast_pattern

First class AST patterns

PPX rewriters often need to recognize fragments the OCaml AST, for instance to parse the payload of an attribute/expression. You can do that with a pattern matching and manual error reporting when the input is not what you expect but this has proven to quickly become extremely verbose and unreadable.

This module aims to help with that by providing first class AST patterns.

To understand how to use it, let's consider the example of ppx_inline_test. We want to recognize patterns of the form:

      let%test "name" = expr

Which is a syntactic sugar for:

      [%%test let "name" = expr]

If we wanted to write a function that recognizes the payload of %%test using normal pattern matching we would write:

      let match_payload = function
        | Pstr [ { pstr_desc = Pstr_value (Nonrecursive,
                                           [ { pvb_pat = Ppat_constant (Constant_string
                                                                          (name, None))
                                             ; pvb_expr = e
                                             ; _ } ])
                 ; _ } ] ->
          (name, e)
        | _ -> Location.raisef ...

This is quite cumbersome, and this is still not right: this function drops all attributes without notice.

Now let's imagine we wanted to construct the payload instead, using Ast_builder one would write:

      let build_payload ~loc name expr =
        let (module B) = Ast_builder.with_loc loc in
        let open B in
        pstr [ pstr_value Nonrecursive (value_binding ~pat:(pstring name) ~expr) ]

Constructing a first class pattern is almost as simple as replacing Ast_builder by Ast_pattern:

      let payload_pattern name expr =
        let open Ast_pattern in
        pstr (pstr_value nonrecursive (value_binding ~pat:(pstring __) ~expr:__) ^:: nil)

Notice that the place-holders for name and expr have been replaced by __. The following pattern with have type:

(payload, string -> expression -> 'a, 'a) Ast_pattern.t

which means that it matches values of type payload and captures a string and expression from it. The two captured elements comes from the use of __.

type ('a, 'b, 'c) t = ('a'b'cPpx_core__.Ast_pattern0.t

Type of a pattern:

val parse : ('a'b'ct ‑> Location.t ‑> ?⁠on_error:(Ppx_core__.Import.unit ‑> 'c) ‑> 'a ‑> 'b ‑> 'c

Matches a value against a pattern.

module Packed : sig ... end with type (a, b, c) pattern := (a, b, c) t
val __ : ('a'a ‑> 'b'bt

Pattern that captures its input.

val __' : ('a'a Loc.t ‑> 'b'bt

Same as __ but also captures the location.

Note: this should only be used for types that do not embed a location. For instance you can use it to capture a string constant:

      estring __'

but using it to capture an expression would not yield the expected result:

      pair (eint (int 42)) __'

In the latter case you should use the pexp_loc field of the captured expression instead.

val alt : ('a'b'ct ‑> ('a'b'ct ‑> ('a'b'ct

alt stands for `alternatives'. It matches either the first pattern or the second one.

val alt_option : ('a'v ‑> 'b'ct ‑> ('a'b'ct ‑> ('a'v Ppx_core__.Import.option ‑> 'b'ct

Same as alt, for the common case where the left-hand-side captures a value but not the right-hand-side.

val (|||) : ('a'b'ct ‑> ('a'b'ct ‑> ('a'b'ct

Same as alt

val map : ('a'b'ct ‑> f:('d ‑> 'b) ‑> ('a'd'ct
val map' : ('a'b'ct ‑> f:(Location.t ‑> 'd ‑> 'b) ‑> ('a'd'ct
val map_result : ('a'b'ct ‑> f:('c ‑> 'd) ‑> ('a'b'dt
val (>>|) : ('a'b'ct ‑> ('d ‑> 'b) ‑> ('a'd'ct

Same as map

val map0 : ('a'b'ct ‑> f:'v ‑> ('a'v ‑> 'b'ct
val map1 : ('a'v1 ‑> 'b'ct ‑> f:('v1 ‑> 'v) ‑> ('a'v ‑> 'b'ct
val map2 : ('a'v1 ‑> 'v2 ‑> 'b'ct ‑> f:('v1 ‑> 'v2 ‑> 'v) ‑> ('a'v ‑> 'b'ct
val map0' : ('a'b'ct ‑> f:(Location.t ‑> 'v) ‑> ('a'v ‑> 'b'ct
val map1' : ('a'v1 ‑> 'b'ct ‑> f:(Location.t ‑> 'v1 ‑> 'v) ‑> ('a'v ‑> 'b'ct
val map2' : ('a'v1 ‑> 'v2 ‑> 'b'ct ‑> f:(Location.t ‑> 'v1 ‑> 'v2 ‑> 'v) ‑> ('a'v ‑> 'b'ct
val nil : (_ Ppx_core__.Import.list'a'at
val (^::) : ('a'b'ct ‑> ('a Ppx_core__.Import.list'c'dt ‑> ('a Ppx_core__.Import.list'b'dt
val many : ('a'b ‑> 'b'ct ‑> ('a Ppx_core__.Import.list'c Ppx_core__.Import.list ‑> 'd'dt
val int : Ppx_core__.Import.int ‑> (Ppx_core__.Import.int'a'at
val char : Ppx_core__.Import.char ‑> (Ppx_core__.Import.char'a'at
val string : Ppx_core__.Import.string ‑> (Ppx_core__.Import.string'a'at
val float : Ppx_core__.Import.float ‑> (Ppx_core__.Import.float'a'at
val int32 : Ppx_core__.Import.int32 ‑> (Ppx_core__.Import.int32'a'at
val int64 : Ppx_core__.Import.int64 ‑> (Ppx_core__.Import.int64'a'at
val nativeint : Ppx_core__.Import.nativeint ‑> (Ppx_core__.Import.nativeint'a'at
val bool : Ppx_core__.Import.bool ‑> (Ppx_core__.Import.bool'a'at
val cst : to_string:('a ‑> Ppx_core__.Import.string) ‑> ?⁠equal:('a ‑> 'a ‑> Ppx_core__.Import.bool) ‑> 'a ‑> ('a'b'bt
val none : (_ Ppx_core__.Import.option'a'at
val some : ('a'b'ct ‑> ('a Ppx_core__.Import.option'b'ct
val pair : ('a1'b'ct ‑> ('a2'c'dt ‑> ('a1 * 'a2'b'dt
val (**) : ('a1'b'ct ‑> ('a2'c'dt ‑> ('a1 * 'a2'b'dt
val triple : ('a1'b'ct ‑> ('a2'c'dt ‑> ('a3'd'et ‑> ('a1 * 'a2 * 'a3'b'et
val loc : ('a'b'ct ‑> ('a Loc.t'b'ct
val pack0 : ('a'b'ct ‑> ('aPpx_core__.Import.unit ‑> 'b'ct
val pack2 : ('a'b ‑> 'c ‑> 'd'et ‑> ('a, ('b * 'c) ‑> 'd'et
val pack3 : ('a'b ‑> 'c ‑> 'd ‑> 'e'ft ‑> ('a, ('b * 'c * 'd) ‑> 'e'ft

AST patterns for each constructur/record of the parsetree are generated in the same way AST builders are generated. In addition, for every wrapper we generate a pattern to match the loc and attributes fields. For instanct for the expression type:

      val pexp_loc
        :  (Location.t, 'a, 'b) t
        -> (expression, 'b, 'c) t
        -> (expression, 'a, 'c) t

      val pexp_attributes
        :  (attributes, 'a, 'b) t
        -> (expression, 'b, 'c) t
        -> (expression, 'a, 'c) t
include module type of Ppx_core__.Ast_pattern_generated
val labelled : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.arg_label'a'bPpx_core__.Ast_pattern0.t
val optional : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.arg_label'a'bPpx_core__.Ast_pattern0.t
val pconst_integer : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (char option, 'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.constant'a'cPpx_core__.Ast_pattern0.t
val pconst_char : (char, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.constant'a'bPpx_core__.Ast_pattern0.t
val pconst_string : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (string option, 'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.constant'a'cPpx_core__.Ast_pattern0.t
val pconst_float : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (char option, 'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.constant'a'cPpx_core__.Ast_pattern0.t
val ptyp_var : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.core_type'a'bPpx_core__.Ast_pattern0.t
val pdir_string : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.directive_argument'a'bPpx_core__.Ast_pattern0.t
val pdir_int : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (char option, 'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.directive_argument'a'cPpx_core__.Ast_pattern0.t
val pexp_unreachable : (Ppx_core__.Import.expression'a'aPpx_core__.Ast_pattern0.t
val include_infos : mod_:('a'b'cPpx_core__.Ast_pattern0.t ‑> ('a Ppx_core__.Import.include_infos'b'cPpx_core__.Ast_pattern0.t
val lident : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.longident'a'bPpx_core__.Ast_pattern0.t
val module_binding : name:(string, 'a'bPpx_core__.Ast_pattern0.t ‑> expr:(Ppx_core__.Import.module_expr'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.module_binding'a'cPpx_core__.Ast_pattern0.t
val module_declaration : name:(string, 'a'bPpx_core__.Ast_pattern0.t ‑> type_:(Ppx_core__.Import.module_type'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.module_declaration'a'cPpx_core__.Ast_pattern0.t
val module_type_declaration : name:(string, 'a'bPpx_core__.Ast_pattern0.t ‑> type_:(Ppx_core__.Import.module_type option, 'b'cPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.module_type_declaration'a'cPpx_core__.Ast_pattern0.t
val ppat_var : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.pattern'a'bPpx_core__.Ast_pattern0.t
val ppat_unpack : (string, 'a'bPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.pattern'a'bPpx_core__.Ast_pattern0.t
val position : fname:(string, 'a'bPpx_core__.Ast_pattern0.t ‑> lnum:(int, 'b'cPpx_core__.Ast_pattern0.t ‑> bol:(int, 'c'dPpx_core__.Ast_pattern0.t ‑> cnum:(int, 'd'ePpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.position'a'ePpx_core__.Ast_pattern0.t
val ptype_abstract : (Ppx_core__.Import.type_kind'a'aPpx_core__.Ast_pattern0.t
val value_description : name:(string, 'a'bPpx_core__.Ast_pattern0.t ‑> type_:(Ppx_core__.Import.core_type'b'cPpx_core__.Ast_pattern0.t ‑> prim:(string list, 'c'dPpx_core__.Ast_pattern0.t ‑> (Ppx_core__.Import.value_description'a'dPpx_core__.Ast_pattern0.t
val contravariant : (Ppx_core__.Import.variance'a'aPpx_core__.Ast_pattern0.t
val true_ : (Ppx_core__.Import.bool'a'at
val false_ : (Ppx_core__.Import.bool'a'at
val eint : (Ppx_core__.Import.int'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val echar : (Ppx_core__.Import.char'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val estring : (Ppx_core__.Import.string'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val efloat : (Ppx_core__.Import.string'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val eint32 : (Ppx_core__.Import.int32'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val eint64 : (Ppx_core__.Import.int64'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val enativeint : (Ppx_core__.Import.nativeint'a'bt ‑> (Ppx_core__.Import.expression'a'bt
val pint : (Ppx_core__.Import.int'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val pchar : (Ppx_core__.Import.char'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val pstring : (Ppx_core__.Import.string'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val pfloat : (Ppx_core__.Import.string'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val pint32 : (Ppx_core__.Import.int32'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val pint64 : (Ppx_core__.Import.int64'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val pnativeint : (Ppx_core__.Import.nativeint'a'bt ‑> (Ppx_core__.Import.pattern'a'bt
val single_expr_payload : (Ppx_core__.Import.expression'a'bt ‑> (Ppx_core__.Import.payload'a'bt
val no_label : (Ppx_core__.Import.expression'a'bt ‑> (Ppx_core__.Import.Asttypes.arg_label * Ppx_core__.Import.expression'a'bt
val attribute : (Ppx_core__.Import.string'a'bt ‑> (Ppx_core__.Import.payload'b'ct ‑> (Ppx_core__.Import.attribute'a'ct
val extension : (Ppx_core__.Import.string'a'bt ‑> (Ppx_core__.Import.payload'b'ct ‑> (Ppx_core__.Import.attribute'a'ct
val elist : (Ppx_core__.Import.expression'a ‑> 'a'bt ‑> (Ppx_core__.Import.expression'b Ppx_core__.Import.list ‑> 'c'ct
type context
val of_func : (context ‑> Location.t ‑> 'a ‑> 'b ‑> 'c) ‑> ('a'b'ct
val to_func : ('a'b'ct ‑> context ‑> Location.t ‑> 'a ‑> 'b ‑> 'c