package ocamlformat

  1. Overview
  2. Docs
package ocamlformat
Legend:
Library
Module
Module type
Parameter
Class
Class type

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 enables 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.

Warning: this module is unstable and part of compiler-libs.

A generic Parsetree mapper

type mapper = {
  1. attribute : mapper -> Parsetree.attribute -> Parsetree.attribute;
  2. attributes : mapper -> Parsetree.attribute list -> Parsetree.attribute list;
  3. binding_op : mapper -> Parsetree.binding_op -> Parsetree.binding_op;
  4. case : mapper -> Parsetree.case -> Parsetree.case;
  5. cases : mapper -> Parsetree.case list -> Parsetree.case list;
  6. class_declaration : mapper -> Parsetree.class_declaration -> Parsetree.class_declaration;
  7. class_description : mapper -> Parsetree.class_description -> Parsetree.class_description;
  8. class_expr : mapper -> Parsetree.class_expr -> Parsetree.class_expr;
  9. class_field : mapper -> Parsetree.class_field -> Parsetree.class_field;
  10. class_signature : mapper -> Parsetree.class_signature -> Parsetree.class_signature;
  11. class_structure : mapper -> Parsetree.class_structure -> Parsetree.class_structure;
  12. class_type : mapper -> Parsetree.class_type -> Parsetree.class_type;
  13. class_type_declaration : mapper -> Parsetree.class_type_declaration -> Parsetree.class_type_declaration;
  14. class_type_field : mapper -> Parsetree.class_type_field -> Parsetree.class_type_field;
  15. constant : mapper -> Parsetree.constant -> Parsetree.constant;
  16. constructor_declaration : mapper -> Parsetree.constructor_declaration -> Parsetree.constructor_declaration;
  17. expr : mapper -> Parsetree.expression -> Parsetree.expression;
  18. extension : mapper -> Parsetree.extension -> Parsetree.extension;
  19. extension_constructor : mapper -> Parsetree.extension_constructor -> Parsetree.extension_constructor;
  20. include_declaration : mapper -> Parsetree.include_declaration -> Parsetree.include_declaration;
  21. include_description : mapper -> Parsetree.include_description -> Parsetree.include_description;
  22. label_declaration : mapper -> Parsetree.label_declaration -> Parsetree.label_declaration;
  23. location : mapper -> Ocaml_common.Location.t -> Ocaml_common.Location.t;
  24. module_binding : mapper -> Parsetree.module_binding -> Parsetree.module_binding;
  25. module_declaration : mapper -> Parsetree.module_declaration -> Parsetree.module_declaration;
  26. module_substitution : mapper -> Parsetree.module_substitution -> Parsetree.module_substitution;
  27. module_expr : mapper -> Parsetree.module_expr -> Parsetree.module_expr;
  28. module_type : mapper -> Parsetree.module_type -> Parsetree.module_type;
  29. module_type_declaration : mapper -> Parsetree.module_type_declaration -> Parsetree.module_type_declaration;
  30. open_declaration : mapper -> Parsetree.open_declaration -> Parsetree.open_declaration;
  31. open_description : mapper -> Parsetree.open_description -> Parsetree.open_description;
  32. pat : mapper -> Parsetree.pattern -> Parsetree.pattern;
  33. payload : mapper -> Parsetree.payload -> Parsetree.payload;
  34. signature : mapper -> Parsetree.signature -> Parsetree.signature;
  35. signature_item : mapper -> Parsetree.signature_item -> Parsetree.signature_item;
  36. structure : mapper -> Parsetree.structure -> Parsetree.structure;
  37. structure_item : mapper -> Parsetree.structure_item -> Parsetree.structure_item;
  38. typ : mapper -> Parsetree.core_type -> Parsetree.core_type;
  39. type_declaration : mapper -> Parsetree.type_declaration -> Parsetree.type_declaration;
  40. type_extension : mapper -> Parsetree.type_extension -> Parsetree.type_extension;
  41. type_exception : mapper -> Parsetree.type_exception -> Parsetree.type_exception;
  42. type_kind : mapper -> Parsetree.type_kind -> Parsetree.type_kind;
  43. value_binding : mapper -> Parsetree.value_binding -> Parsetree.value_binding;
  44. value_description : mapper -> Parsetree.value_description -> Parsetree.value_description;
  45. with_constraint : mapper -> Parsetree.with_constraint -> Parsetree.with_constraint;
  46. directive_argument : mapper -> Parsetree.directive_argument -> Parsetree.directive_argument;
  47. toplevel_directive : mapper -> Parsetree.toplevel_directive -> Parsetree.toplevel_directive;
  48. toplevel_phrase : mapper -> Parsetree.toplevel_phrase -> Parsetree.toplevel_phrase;
  49. repl_phrase : mapper -> Parsetree.repl_phrase -> Parsetree.repl_phrase;
}

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.