1Ast_mapper(3) OCaml library Ast_mapper(3)
2
6 Ast_mapper - The interface of a -ppx rewriter
7
9 Module Ast_mapper
10
12 Module Ast_mapper
13 : sig end
14 The interface of a -ppx rewriter
17 A -ppx rewriter is a program that accepts a serialized abstract syntax
19 tree and outputs another, possibly modified, abstract syntax tree.
20 This module encapsulates the interface between the compiler and the
21 -ppx rewriters, handling such details as the serialization format, for‐
22 warding of command-line flags, and storing state.
23 Ast_mapper.mapper enables AST rewriting using open recursion. A typi‐
26 cal mapper would be based on Ast_mapper.default_mapper , a deep iden‐
27 tity mapper, and will fall back on it for handling the syntax it does
28 not modify. For example:
29 open Asttypes open Parsetree open Ast_mapper let test_mapper argv = {
32 default_mapper with expr = fun mapper expr -> match expr with | {
33 pexp_desc = Pexp_extension ({ txt = test }, PStr [])} ->
34 Ast_helper.Exp.constant (Const_int 42) | other -> default_mapper.expr
35 mapper other; } let () = register ppx_test test_mapper
36 This -ppx rewriter, which replaces [%test] in expressions with the con‐
38 stant 42 , can be compiled using ocamlc -o ppx_test -I +compiler-libs
39 ocamlcommon.cma ppx_test.ml .
40 Warning: this module is unstable and part of Compiler_libs .
42 A generic Parsetree mapper
50 type mapper = {
51 attribute : mapper -> Parsetree.attribute -> Parsetree.attribute ;
52 attributes : mapper -> Parsetree.attribute list -> Parsetree.attribute
53 list ;
54 binding_op : mapper -> Parsetree.binding_op -> Parsetree.binding_op ;
55 case : mapper -> Parsetree.case -> Parsetree.case ;
56 cases : mapper -> Parsetree.case list -> Parsetree.case list ;
57 class_declaration : mapper -> Parsetree.class_declaration -> Parse‐
58 tree.class_declaration ;
59 class_description : mapper -> Parsetree.class_description -> Parse‐
60 tree.class_description ;
61 class_expr : mapper -> Parsetree.class_expr -> Parsetree.class_expr ;
62 class_field : mapper -> Parsetree.class_field -> Parsetree.class_field
63 ;
64 class_signature : mapper -> Parsetree.class_signature -> Parse‐
65 tree.class_signature ;
66 class_structure : mapper -> Parsetree.class_structure -> Parse‐
67 tree.class_structure ;
68 class_type : mapper -> Parsetree.class_type -> Parsetree.class_type ;
69 class_type_declaration : mapper -> Parsetree.class_type_declaration ->
70 Parsetree.class_type_declaration ;
71 class_type_field : mapper -> Parsetree.class_type_field -> Parse‐
72 tree.class_type_field ;
73 constructor_declaration : mapper -> Parsetree.constructor_declaration
74 -> Parsetree.constructor_declaration ;
75 expr : mapper -> Parsetree.expression -> Parsetree.expression ;
76 extension : mapper -> Parsetree.extension -> Parsetree.extension ;
77 extension_constructor : mapper -> Parsetree.extension_constructor ->
78 Parsetree.extension_constructor ;
79 include_declaration : mapper -> Parsetree.include_declaration ->
80 Parsetree.include_declaration ;
81 include_description : mapper -> Parsetree.include_description ->
82 Parsetree.include_description ;
83 label_declaration : mapper -> Parsetree.label_declaration -> Parse‐
84 tree.label_declaration ;
85 location : mapper -> Location.t -> Location.t ;
86 module_binding : mapper -> Parsetree.module_binding -> Parsetree.mod‐
87 ule_binding ;
88 module_declaration : mapper -> Parsetree.module_declaration -> Parse‐
89 tree.module_declaration ;
90 module_substitution : mapper -> Parsetree.module_substitution ->
91 Parsetree.module_substitution ;
92 module_expr : mapper -> Parsetree.module_expr -> Parsetree.module_expr
93 ;
94 module_type : mapper -> Parsetree.module_type -> Parsetree.module_type
95 ;
96 module_type_declaration : mapper -> Parsetree.module_type_declaration
97 -> Parsetree.module_type_declaration ;
98 open_declaration : mapper -> Parsetree.open_declaration -> Parse‐
99 tree.open_declaration ;
100 open_description : mapper -> Parsetree.open_description -> Parse‐
101 tree.open_description ;
102 pat : mapper -> Parsetree.pattern -> Parsetree.pattern ;
103 payload : mapper -> Parsetree.payload -> Parsetree.payload ;
104 signature : mapper -> Parsetree.signature -> Parsetree.signature ;
105 signature_item : mapper -> Parsetree.signature_item -> Parsetree.sig‐
106 nature_item ;
107 structure : mapper -> Parsetree.structure -> Parsetree.structure ;
108 structure_item : mapper -> Parsetree.structure_item -> Parse‐
109 tree.structure_item ;
110 typ : mapper -> Parsetree.core_type -> Parsetree.core_type ;
111 type_declaration : mapper -> Parsetree.type_declaration -> Parse‐
112 tree.type_declaration ;
113 type_extension : mapper -> Parsetree.type_extension -> Parse‐
114 tree.type_extension ;
115 type_exception : mapper -> Parsetree.type_exception -> Parse‐
116 tree.type_exception ;
117 type_kind : mapper -> Parsetree.type_kind -> Parsetree.type_kind ;
118 value_binding : mapper -> Parsetree.value_binding -> Parse‐
119 tree.value_binding ;
120 value_description : mapper -> Parsetree.value_description -> Parse‐
121 tree.value_description ;
122 with_constraint : mapper -> Parsetree.with_constraint -> Parse‐
123 tree.with_constraint ;
124 }
125 A mapper record implements one "method" per syntactic category, using
128 an open recursion style: each method takes as its first argument the
129 mapper to be applied to children in the syntax tree.
130 val default_mapper : mapper
134 A default mapper, which implements a "deep identity" mapping.
136 Apply mappers to compilation units
141 val tool_name : unit -> string
142 Can be used within a ppx preprocessor to know which tool is calling it
144 ocamlc , ocamlopt , ocamldoc , ocamldep , ocaml , ... Some global
145 variables that reflect command-line options are automatically synchro‐
146 nized between the calling tool and the ppx preprocessor:
147 Clflags.include_dirs , Load_path , Clflags.open_modules ,
148 Clflags.for_package , Clflags.debug .
149 val apply : source:string -> target:string -> mapper -> unit
153 Apply a mapper (parametrized by the unit name) to a dumped parsetree
155 found in the source file and put the result in the target file. The
156 structure or signature field of the mapper is applied to the implemen‐
157 tation or interface.
158 val run_main : (string list -> mapper) -> unit
162 Entry point to call to implement a standalone -ppx rewriter from a map‐
164 per, parametrized by the command line arguments. The current unit name
165 can be obtained from Location.input_name . This function implements
166 proper error reporting for uncaught exceptions.
167 Registration API
172 val register_function : (string -> (string list -> mapper) -> unit) ref
173 val register : string -> (string list -> mapper) -> unit
178 Apply the register_function . The default behavior is to run the map‐
180 per immediately, taking arguments from the process command line. This
181 is to support a scenario where a mapper is linked as a stand-alone exe‐
182 cutable.
183 It is possible to overwrite the register_function to define "-ppx driv‐
185 ers", which combine several mappers in a single process. Typically, a
186 driver starts by defining register_function to a custom implementation,
187 then lets ppx rewriters (linked statically or dynamically) register
188 themselves, and then run all or some of them. It is also possible to
189 have -ppx drivers apply rewriters to only specific parts of an AST.
190 The first argument to register is a symbolic name to be used by the ppx
192 driver.
193 Convenience functions to write mappers
198 val map_opt : ('a -> 'b) -> 'a option -> 'b option
199 val extension_of_error : Location.error -> Parsetree.extension
204 Encode an error into an 'ocaml.error' extension node which can be
206 inserted in a generated Parsetree. The compiler will be responsible
207 for reporting the error.
208 val attribute_of_warning : Location.t -> string -> Parsetree.attribute
212 Encode a warning message into an 'ocaml.ppwarning' attribute which can
214 be inserted in a generated Parsetree. The compiler will be responsible
215 for reporting the warning.
216 Helper functions to call external mappers
221 val add_ppx_context_str : tool_name:string -> Parsetree.structure ->
222 Parsetree.structure
223 Extract information from the current environment and encode it into an
225 attribute which is prepended to the list of structure items in order to
226 pass the information to an external processor.
227 val add_ppx_context_sig : tool_name:string -> Parsetree.signature ->
231 Parsetree.signature
232 Same as add_ppx_context_str , but for signatures.
234 val drop_ppx_context_str : restore:bool -> Parsetree.structure ->
238 Parsetree.structure
239 Drop the ocaml.ppx.context attribute from a structure. If restore is
241 true, also restore the associated data in the current process.
242 val drop_ppx_context_sig : restore:bool -> Parsetree.signature ->
246 Parsetree.signature
247 Same as drop_ppx_context_str , but for signatures.
249 Cookies
254 Cookies are used to pass information from a ppx processor to a further
255 invocation of itself, when called from the OCaml toplevel (or other
256 tools that support cookies).
257 val set_cookie : string -> Parsetree.expression -> unit
259 val get_cookie : string -> Parsetree.expression option
264OCamldoc 2019-07-30 Ast_mapper(3)