Ast_mapper (ocaml-migrate-parsetree.Migrate_parsetree.Ast_406.Ast

The interface of a -ppx rewriter

A -ppx rewriter is a program that accepts a serialized abstract syntax tree and outputs another, possibly modified, abstract syntax tree. This module encapsulates the interface between the compiler and the -ppx rewriters, handling such details as the serialization format, forwarding of command-line flags, and storing state.

mapper allows to implement AST rewriting using open recursion. A typical mapper would be based on default_mapper, a deep identity mapper, and will fall back on it for handling the syntax it does not modify. For example:

open Asttypes
open Parsetree
open Ast_mapper

let test_mapper argv =
  { default_mapper with
    expr = fun mapper expr ->
      match expr with
      | { pexp_desc = Pexp_extension ({ txt = "test" }, PStr [])} ->
        Ast_helper.Exp.constant (Const_int 42)
      | other -> default_mapper.expr mapper other; }

let () =
  register "ppx_test" test_mapper

This -ppx rewriter, which replaces [%test] in expressions with the constant 42, can be compiled using ocamlc -o ppx_test -I +compiler-libs ocamlcommon.cma ppx_test.ml.

A generic Parsetree mapper

type mapper = { attribute : mapper -> Parsetree.attribute -> Parsetree.attribute; attributes : mapper -> Parsetree.attribute list -> Parsetree.attribute list; case : mapper -> Parsetree.case -> Parsetree.case; cases : mapper -> Parsetree.case list -> Parsetree.case list; class_declaration : mapper -> Parsetree.class_declaration -> Parsetree.class_declaration; class_description : mapper -> Parsetree.class_description -> Parsetree.class_description; class_expr : mapper -> Parsetree.class_expr -> Parsetree.class_expr; class_field : mapper -> Parsetree.class_field -> Parsetree.class_field; class_signature : mapper -> Parsetree.class_signature -> Parsetree.class_signature; class_structure : mapper -> Parsetree.class_structure -> Parsetree.class_structure; class_type : mapper -> Parsetree.class_type -> Parsetree.class_type; class_type_declaration : mapper -> Parsetree.class_type_declaration -> Parsetree.class_type_declaration; class_type_field : mapper -> Parsetree.class_type_field -> Parsetree.class_type_field; constructor_declaration : mapper -> Parsetree.constructor_declaration -> Parsetree.constructor_declaration; expr : mapper -> Parsetree.expression -> Parsetree.expression; extension : mapper -> Parsetree.extension -> Parsetree.extension; extension_constructor : mapper -> Parsetree.extension_constructor -> Parsetree.extension_constructor; include_declaration : mapper -> Parsetree.include_declaration -> Parsetree.include_declaration; include_description : mapper -> Parsetree.include_description -> Parsetree.include_description; label_declaration : mapper -> Parsetree.label_declaration -> Parsetree.label_declaration; location : mapper -> Location.t -> Location.t; module_binding : mapper -> Parsetree.module_binding -> Parsetree.module_binding; module_declaration : mapper -> Parsetree.module_declaration -> Parsetree.module_declaration; module_expr : mapper -> Parsetree.module_expr -> Parsetree.module_expr; module_type : mapper -> Parsetree.module_type -> Parsetree.module_type; module_type_declaration : mapper -> Parsetree.module_type_declaration -> Parsetree.module_type_declaration; open_description : mapper -> Parsetree.open_description -> Parsetree.open_description; pat : mapper -> Parsetree.pattern -> Parsetree.pattern; payload : mapper -> Parsetree.payload -> Parsetree.payload; signature : mapper -> Parsetree.signature -> Parsetree.signature; signature_item : mapper -> Parsetree.signature_item -> Parsetree.signature_item; structure : mapper -> Parsetree.structure -> Parsetree.structure; structure_item : mapper -> Parsetree.structure_item -> Parsetree.structure_item; typ : mapper -> Parsetree.core_type -> Parsetree.core_type; type_declaration : mapper -> Parsetree.type_declaration -> Parsetree.type_declaration; type_extension : mapper -> Parsetree.type_extension -> Parsetree.type_extension; type_kind : mapper -> Parsetree.type_kind -> Parsetree.type_kind; value_binding : mapper -> Parsetree.value_binding -> Parsetree.value_binding; value_description : mapper -> Parsetree.value_description -> Parsetree.value_description; with_constraint : mapper -> Parsetree.with_constraint -> Parsetree.with_constraint; }: A mapper record implements one "method" per syntactic category, using an open recursion style: each method takes as its first argument the mapper to be applied to children in the syntax tree.

val default_mapper : mapper: A default mapper, which implements a "deep identity" mapping.

Convenience functions to write mappers

val map_opt : ('a -> 'b) -> 'a option -> 'b option
val extension_of_error : Location.error -> Parsetree.extension: Encode an error into an 'ocaml.error' extension node which can be inserted in a generated Parsetree. The compiler will be responsible for reporting the error.

val attribute_of_warning : Location.t -> string -> Parsetree.attribute: Encode a warning message into an 'ocaml.ppwarning' attribute which can be inserted in a generated Parsetree. The compiler will be responsible for reporting the warning.

type nonrec location_error = Location.error

val error_of_exn : exn -> location_error option
val register_error_of_exn : (exn -> location_error option) -> unit
val report_exception : Stdlib.Format.formatter -> exn -> unit
val get_error_message : location_error -> string
val set_error_message : location_error -> string -> location_error
val make_error_of_message : loc:Location.t -> string -> sub:(Location.t * string) list -> location_error
val print_error : Stdlib.Format.formatter -> location_error -> unit
val raise_error : location_error -> 'a