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 of a pattern:
'a
is the type of value matched by the pattern'b
is the continuation, for instance for a pattern that captures an int
and a string
, 'b
will be int -> string -> _
'c
is the result of the continuation.
Matches a value against a pattern.
val __ : ('a, 'a -> 'b, 'b) t
Pattern that captures its input.
val __' : ('a, 'a Loc.t -> 'b, 'b) t
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, 'c) t -> ('a, 'b, 'c) t -> ('a, 'b, 'c) t
alt
stands for `alternatives'. It matches either the first pattern or the second one.
val alt_option :
('a, 'v -> 'b, 'c) t ->
('a, 'b, 'c) t ->
('a, 'v Base.Option.t -> 'b, 'c) t
Same as alt
, for the common case where the left-hand-side captures a value but not the right-hand-side.
val (|||) : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> ('a, 'b, 'c) t
val map : ('a, 'b, 'c) t -> f:('d -> 'b) -> ('a, 'd, 'c) t
val map' : ('a, 'b, 'c) t -> f:(Location.t -> 'd -> 'b) -> ('a, 'd, 'c) t
val map_result : ('a, 'b, 'c) t -> f:('c -> 'd) -> ('a, 'b, 'd) t
val (>>|) : ('a, 'b, 'c) t -> ('d -> 'b) -> ('a, 'd, 'c) t
val map0 : ('a, 'b, 'c) t -> f:'v -> ('a, 'v -> 'b, 'c) t
val map1 : ('a, 'v1 -> 'b, 'c) t -> f:('v1 -> 'v) -> ('a, 'v -> 'b, 'c) t
val map2 :
('a, 'v1 -> 'v2 -> 'b, 'c) t ->
f:('v1 -> 'v2 -> 'v) ->
('a, 'v -> 'b, 'c) t
val map0' : ('a, 'b, 'c) t -> f:(Location.t -> 'v) -> ('a, 'v -> 'b, 'c) t
val map1' :
('a, 'v1 -> 'b, 'c) t ->
f:(Location.t -> 'v1 -> 'v) ->
('a, 'v -> 'b, 'c) t
val map2' :
('a, 'v1 -> 'v2 -> 'b, 'c) t ->
f:(Location.t -> 'v1 -> 'v2 -> 'v) ->
('a, 'v -> 'b, 'c) t
val pair : ('a1, 'b, 'c) t -> ('a2, 'c, 'd) t -> ('a1 * 'a2, 'b, 'd) t
val (**) : ('a1, 'b, 'c) t -> ('a2, 'c, 'd) t -> ('a1 * 'a2, 'b, 'd) t
val triple :
('a1, 'b, 'c) t ->
('a2, 'c, 'd) t ->
('a3, 'd, 'e) t ->
('a1 * 'a2 * 'a3, 'b, 'e) t
val loc : ('a, 'b, 'c) t -> ('a Loc.t, 'b, 'c) t
val pack2 : ('a, 'b -> 'c -> 'd, 'e) t -> ('a, ('b * 'c) -> 'd, 'e) t
val pack3 :
('a, 'b -> 'c -> 'd -> 'e, 'f) t ->
('a, ('b * 'c * 'd) -> 'e, 'f) t
AST patterns for each constructur/record of the parsetree are generated in the same way AST builders are generated. In addition, for every t 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
val pcl_fun :
(Migrate_parsetree.Ast_407.Asttypes.arg_label, 'a, 'b)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression option, 'b, 'c)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.pattern, 'c, 'd) Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.class_expr, 'd, 'e)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.class_expr, 'a, 'e)
Ppxlib__.Ast_pattern0.t
val class_infos :
virt:
(Migrate_parsetree.Ast_407.Asttypes.virtual_flag, 'a, 'b)
Ppxlib__.Ast_pattern0.t ->
params:
((Migrate_parsetree.Ast_407.Parsetree.core_type
* Migrate_parsetree.Ast_407.Asttypes.variance)
list,
'b,
'c)
Ppxlib__.Ast_pattern0.t ->
name:(string, 'c, 'd) Ppxlib__.Ast_pattern0.t ->
expr:('e, 'd, 'f) Ppxlib__.Ast_pattern0.t ->
('e Migrate_parsetree.Ast_407.Parsetree.class_infos, 'a, 'f)
Ppxlib__.Ast_pattern0.t
val pexp_fun :
(Migrate_parsetree.Ast_407.Asttypes.arg_label, 'a, 'b)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression option, 'b, 'c)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.pattern, 'c, 'd) Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression, 'd, 'e)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression, 'a, 'e)
Ppxlib__.Ast_pattern0.t
val pexp_for :
(Migrate_parsetree.Ast_407.Parsetree.pattern, 'a, 'b) Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression, 'b, 'c)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression, 'c, 'd)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Asttypes.direction_flag, 'd, 'e)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression, 'e, 'f)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.expression, 'a, 'f)
Ppxlib__.Ast_pattern0.t
val location :
start:(Lexing.position, 'a, 'b) Ppxlib__.Ast_pattern0.t ->
end_:(Lexing.position, 'b, 'c) Ppxlib__.Ast_pattern0.t ->
ghost:(bool, 'c, 'd) Ppxlib__.Ast_pattern0.t ->
(Warnings.loc, 'a, 'd) Ppxlib__.Ast_pattern0.t
val position :
fname:(string, 'a, 'b) Ppxlib__.Ast_pattern0.t ->
lnum:(int, 'b, 'c) Ppxlib__.Ast_pattern0.t ->
bol:(int, 'c, 'd) Ppxlib__.Ast_pattern0.t ->
cnum:(int, 'd, 'e) Ppxlib__.Ast_pattern0.t ->
(Lexing.position, 'a, 'e) Ppxlib__.Ast_pattern0.t
val rtag :
(string, 'a, 'b) Ppxlib__.Ast_pattern0.t ->
((string Location.loc * Migrate_parsetree.Ast_407.Parsetree.payload) list,
'b,
'c)
Ppxlib__.Ast_pattern0.t ->
(bool, 'c, 'd) Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.core_type list, 'd, 'e)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.row_field, 'a, 'e)
Ppxlib__.Ast_pattern0.t
val type_declaration :
name:(string, 'a, 'b) Ppxlib__.Ast_pattern0.t ->
params:
((Migrate_parsetree.Ast_407.Parsetree.core_type
* Migrate_parsetree.Ast_407.Asttypes.variance)
list,
'b,
'c)
Ppxlib__.Ast_pattern0.t ->
cstrs:
((Migrate_parsetree.Ast_407.Parsetree.core_type
* Migrate_parsetree.Ast_407.Parsetree.core_type
* Warnings.loc)
list,
'c,
'd)
Ppxlib__.Ast_pattern0.t ->
kind:
(Migrate_parsetree.Ast_407.Parsetree.type_kind, 'd, 'e)
Ppxlib__.Ast_pattern0.t ->
private_:
(Migrate_parsetree.Ast_407.Asttypes.private_flag, 'e, 'f)
Ppxlib__.Ast_pattern0.t ->
manifest:
(Migrate_parsetree.Ast_407.Parsetree.core_type option, 'f, 'g)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.type_declaration, 'a, 'g)
Ppxlib__.Ast_pattern0.t
val type_extension :
path:(Ocaml_common.Longident.t, 'a, 'b) Ppxlib__.Ast_pattern0.t ->
params:
((Migrate_parsetree.Ast_407.Parsetree.core_type
* Migrate_parsetree.Ast_407.Asttypes.variance)
list,
'b,
'c)
Ppxlib__.Ast_pattern0.t ->
constructors:
(Migrate_parsetree.Ast_407.Parsetree.extension_constructor list, 'c, 'd)
Ppxlib__.Ast_pattern0.t ->
private_:
(Migrate_parsetree.Ast_407.Asttypes.private_flag, 'd, 'e)
Ppxlib__.Ast_pattern0.t ->
(Migrate_parsetree.Ast_407.Parsetree.type_extension, 'a, 'e)
Ppxlib__.Ast_pattern0.t