642 lines
13 KiB
HTML
642 lines
13 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Ast_mapper</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Ast_mapper</H1>
|
|
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Ast_mapper - The interface of a -ppx rewriter
|
|
<A NAME="lbAC"> </A>
|
|
<H2>Module</H2>
|
|
|
|
Module Ast_mapper
|
|
<A NAME="lbAD"> </A>
|
|
<H2>Documentation</H2>
|
|
|
|
<P>
|
|
Module
|
|
<B>Ast_mapper</B>
|
|
|
|
<BR> :
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
The interface of a -ppx rewriter
|
|
<P>
|
|
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.
|
|
<P>
|
|
<P>
|
|
<B>Ast_mapper.mapper</B>
|
|
|
|
enables AST rewriting using open recursion.
|
|
A typical mapper would be based on
|
|
<B>Ast_mapper.default_mapper</B>
|
|
|
|
, a deep
|
|
identity mapper, and will fall back on it for handling the syntax it
|
|
does not modify. For example:
|
|
<P>
|
|
<P>
|
|
<B>open Asttypes</B>
|
|
|
|
|
|
|
|
<B>open Parsetree</B>
|
|
|
|
<B>open Ast_mapper</B>
|
|
|
|
<B>let test_mapper argv =</B>
|
|
|
|
|
|
|
|
<B>{ default_mapper with</B>
|
|
|
|
<B>expr = fun mapper expr -></B>
|
|
|
|
<B>match expr with</B>
|
|
|
|
<B>| { pexp_desc = Pexp_extension ({ txt = test }, PStr [])} -></B>
|
|
|
|
<B>Ast_helper.Exp.constant (Const_int 42)</B>
|
|
|
|
<B>| other -> default_mapper.expr mapper other; }</B>
|
|
|
|
<B>let () =</B>
|
|
|
|
|
|
|
|
<B>register ppx_test test_mapper</B>
|
|
|
|
<P>
|
|
This -ppx rewriter, which replaces
|
|
<B>[%test]</B>
|
|
|
|
in expressions with
|
|
the constant
|
|
<B>42</B>
|
|
|
|
, can be compiled using
|
|
<B>ocamlc -o ppx_test -I +compiler-libs ocamlcommon.cma ppx_test.ml</B>
|
|
|
|
.
|
|
<P>
|
|
Warning: this module is unstable and part of
|
|
<B>Compiler_libs</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>A generic Parsetree mapper</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type mapper </I>
|
|
|
|
= {
|
|
<BR> attribute :
|
|
<B>mapper -> Parsetree.attribute -> Parsetree.attribute</B>
|
|
|
|
;
|
|
<BR> attributes :
|
|
<B>mapper -> Parsetree.attribute list -> Parsetree.attribute list</B>
|
|
|
|
;
|
|
<BR> binding_op :
|
|
<B>mapper -> Parsetree.binding_op -> Parsetree.binding_op</B>
|
|
|
|
;
|
|
<BR> case :
|
|
<B>mapper -> Parsetree.case -> Parsetree.case</B>
|
|
|
|
;
|
|
<BR> cases :
|
|
<B>mapper -> Parsetree.case list -> Parsetree.case list</B>
|
|
|
|
;
|
|
<BR> class_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.class_declaration -> Parsetree.class_declaration</B>
|
|
|
|
;
|
|
<BR> class_description :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.class_description -> Parsetree.class_description</B>
|
|
|
|
;
|
|
<BR> class_expr :
|
|
<B>mapper -> Parsetree.class_expr -> Parsetree.class_expr</B>
|
|
|
|
;
|
|
<BR> class_field :
|
|
<B>mapper -> Parsetree.class_field -> Parsetree.class_field</B>
|
|
|
|
;
|
|
<BR> class_signature :
|
|
<B>mapper -> Parsetree.class_signature -> Parsetree.class_signature</B>
|
|
|
|
;
|
|
<BR> class_structure :
|
|
<B>mapper -> Parsetree.class_structure -> Parsetree.class_structure</B>
|
|
|
|
;
|
|
<BR> class_type :
|
|
<B>mapper -> Parsetree.class_type -> Parsetree.class_type</B>
|
|
|
|
;
|
|
<BR> class_type_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.class_type_declaration -> Parsetree.class_type_declaration</B>
|
|
|
|
;
|
|
<BR> class_type_field :
|
|
<B>mapper -> Parsetree.class_type_field -> Parsetree.class_type_field</B>
|
|
|
|
;
|
|
<BR> constructor_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.constructor_declaration -> Parsetree.constructor_declaration</B>
|
|
|
|
;
|
|
<BR> expr :
|
|
<B>mapper -> Parsetree.expression -> Parsetree.expression</B>
|
|
|
|
;
|
|
<BR> extension :
|
|
<B>mapper -> Parsetree.extension -> Parsetree.extension</B>
|
|
|
|
;
|
|
<BR> extension_constructor :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.extension_constructor -> Parsetree.extension_constructor</B>
|
|
|
|
;
|
|
<BR> include_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.include_declaration -> Parsetree.include_declaration</B>
|
|
|
|
;
|
|
<BR> include_description :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.include_description -> Parsetree.include_description</B>
|
|
|
|
;
|
|
<BR> label_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.label_declaration -> Parsetree.label_declaration</B>
|
|
|
|
;
|
|
<BR> location :
|
|
<B>mapper -> Location.t -> Location.t</B>
|
|
|
|
;
|
|
<BR> module_binding :
|
|
<B>mapper -> Parsetree.module_binding -> Parsetree.module_binding</B>
|
|
|
|
;
|
|
<BR> module_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.module_declaration -> Parsetree.module_declaration</B>
|
|
|
|
;
|
|
<BR> module_substitution :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.module_substitution -> Parsetree.module_substitution</B>
|
|
|
|
;
|
|
<BR> module_expr :
|
|
<B>mapper -> Parsetree.module_expr -> Parsetree.module_expr</B>
|
|
|
|
;
|
|
<BR> module_type :
|
|
<B>mapper -> Parsetree.module_type -> Parsetree.module_type</B>
|
|
|
|
;
|
|
<BR> module_type_declaration :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.module_type_declaration -> Parsetree.module_type_declaration</B>
|
|
|
|
;
|
|
<BR> open_declaration :
|
|
<B>mapper -> Parsetree.open_declaration -> Parsetree.open_declaration</B>
|
|
|
|
;
|
|
<BR> open_description :
|
|
<B>mapper -> Parsetree.open_description -> Parsetree.open_description</B>
|
|
|
|
;
|
|
<BR> pat :
|
|
<B>mapper -> Parsetree.pattern -> Parsetree.pattern</B>
|
|
|
|
;
|
|
<BR> payload :
|
|
<B>mapper -> Parsetree.payload -> Parsetree.payload</B>
|
|
|
|
;
|
|
<BR> signature :
|
|
<B>mapper -> Parsetree.signature -> Parsetree.signature</B>
|
|
|
|
;
|
|
<BR> signature_item :
|
|
<B>mapper -> Parsetree.signature_item -> Parsetree.signature_item</B>
|
|
|
|
;
|
|
<BR> structure :
|
|
<B>mapper -> Parsetree.structure -> Parsetree.structure</B>
|
|
|
|
;
|
|
<BR> structure_item :
|
|
<B>mapper -> Parsetree.structure_item -> Parsetree.structure_item</B>
|
|
|
|
;
|
|
<BR> typ :
|
|
<B>mapper -> Parsetree.core_type -> Parsetree.core_type</B>
|
|
|
|
;
|
|
<BR> type_declaration :
|
|
<B>mapper -> Parsetree.type_declaration -> Parsetree.type_declaration</B>
|
|
|
|
;
|
|
<BR> type_extension :
|
|
<B>mapper -> Parsetree.type_extension -> Parsetree.type_extension</B>
|
|
|
|
;
|
|
<BR> type_exception :
|
|
<B>mapper -> Parsetree.type_exception -> Parsetree.type_exception</B>
|
|
|
|
;
|
|
<BR> type_kind :
|
|
<B>mapper -> Parsetree.type_kind -> Parsetree.type_kind</B>
|
|
|
|
;
|
|
<BR> value_binding :
|
|
<B>mapper -> Parsetree.value_binding -> Parsetree.value_binding</B>
|
|
|
|
;
|
|
<BR> value_description :
|
|
<B>mapper -></B>
|
|
|
|
<B>Parsetree.value_description -> Parsetree.value_description</B>
|
|
|
|
;
|
|
<BR> with_constraint :
|
|
<B>mapper -> Parsetree.with_constraint -> Parsetree.with_constraint</B>
|
|
|
|
;
|
|
<BR> }
|
|
<P>
|
|
<P>
|
|
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.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val default_mapper </I>
|
|
|
|
:
|
|
<B>mapper</B>
|
|
|
|
<P>
|
|
A default mapper, which implements a "deep identity" mapping.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Apply mappers to compilation units</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val tool_name </I>
|
|
|
|
:
|
|
<B>unit -> string</B>
|
|
|
|
<P>
|
|
Can be used within a ppx preprocessor to know which tool is
|
|
calling it
|
|
<B>ocamlc</B>
|
|
|
|
,
|
|
<B>ocamlopt</B>
|
|
|
|
,
|
|
<B>ocamldoc</B>
|
|
|
|
,
|
|
<B>ocamldep</B>
|
|
|
|
,
|
|
<B>ocaml</B>
|
|
|
|
, ... Some global variables that reflect command-line
|
|
options are automatically synchronized between the calling tool
|
|
and the ppx preprocessor:
|
|
<B>Clflags.include_dirs</B>
|
|
|
|
,
|
|
<B>Load_path</B>
|
|
|
|
,
|
|
<B>Clflags.open_modules</B>
|
|
|
|
,
|
|
<B>Clflags.for_package</B>
|
|
|
|
,
|
|
<B>Clflags.debug</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val apply </I>
|
|
|
|
:
|
|
<B>source:string -> target:string -> mapper -> unit</B>
|
|
|
|
<P>
|
|
Apply a mapper (parametrized by the unit name) to a dumped
|
|
parsetree found in the
|
|
<B>source</B>
|
|
|
|
file and put the result in the
|
|
<B>target</B>
|
|
|
|
file. The
|
|
<B>structure</B>
|
|
|
|
or
|
|
<B>signature</B>
|
|
|
|
field of the mapper
|
|
is applied to the implementation or interface.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val run_main </I>
|
|
|
|
:
|
|
<B>(string list -> mapper) -> unit</B>
|
|
|
|
<P>
|
|
Entry point to call to implement a standalone -ppx rewriter from a
|
|
mapper, parametrized by the command line arguments. The current
|
|
unit name can be obtained from
|
|
<B>Location.input_name</B>
|
|
|
|
. This
|
|
function implements proper error reporting for uncaught
|
|
exceptions.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Registration API</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val register_function </I>
|
|
|
|
:
|
|
<B>(string -> (string list -> mapper) -> unit) ref</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val register </I>
|
|
|
|
:
|
|
<B>string -> (string list -> mapper) -> unit</B>
|
|
|
|
<P>
|
|
Apply the
|
|
<B>register_function</B>
|
|
|
|
. The default behavior is to run the
|
|
mapper immediately, taking arguments from the process command
|
|
line. This is to support a scenario where a mapper is linked as a
|
|
stand-alone executable.
|
|
<P>
|
|
It is possible to overwrite the
|
|
<B>register_function</B>
|
|
|
|
to define
|
|
"-ppx drivers", which combine several mappers in a single process.
|
|
Typically, a driver starts by defining
|
|
<B>register_function</B>
|
|
|
|
to a
|
|
custom implementation, then lets ppx rewriters (linked statically
|
|
or dynamically) register themselves, and then run all or some of
|
|
them. It is also possible to have -ppx drivers apply rewriters to
|
|
only specific parts of an AST.
|
|
<P>
|
|
The first argument to
|
|
<B>register</B>
|
|
|
|
is a symbolic name to be used by
|
|
the ppx driver.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Convenience functions to write mappers</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val map_opt </I>
|
|
|
|
:
|
|
<B>('a -> 'b) -> 'a option -> 'b option</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val extension_of_error </I>
|
|
|
|
:
|
|
<B>Location.error -> Parsetree.extension</B>
|
|
|
|
<P>
|
|
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.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val attribute_of_warning </I>
|
|
|
|
:
|
|
<B>Location.t -> string -> Parsetree.attribute</B>
|
|
|
|
<P>
|
|
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.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Helper functions to call external mappers</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val add_ppx_context_str </I>
|
|
|
|
:
|
|
<B>tool_name:string -> Parsetree.structure -> Parsetree.structure</B>
|
|
|
|
<P>
|
|
Extract information from the current environment and encode it
|
|
into an attribute which is prepended to the list of structure
|
|
items in order to pass the information to an external
|
|
processor.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val add_ppx_context_sig </I>
|
|
|
|
:
|
|
<B>tool_name:string -> Parsetree.signature -> Parsetree.signature</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>add_ppx_context_str</B>
|
|
|
|
, but for signatures.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val drop_ppx_context_str </I>
|
|
|
|
:
|
|
<B>restore:bool -> Parsetree.structure -> Parsetree.structure</B>
|
|
|
|
<P>
|
|
Drop the ocaml.ppx.context attribute from a structure. If
|
|
<B>restore</B>
|
|
|
|
is true, also restore the associated data in the current
|
|
process.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val drop_ppx_context_sig </I>
|
|
|
|
:
|
|
<B>restore:bool -> Parsetree.signature -> Parsetree.signature</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>drop_ppx_context_str</B>
|
|
|
|
, but for signatures.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Cookies</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
Cookies are used to pass information from a ppx processor to
|
|
a further invocation of itself, when called from the OCaml
|
|
toplevel (or other tools that support cookies).
|
|
<P>
|
|
|
|
<P>
|
|
<I>val set_cookie </I>
|
|
|
|
:
|
|
<B>string -> Parsetree.expression -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_cookie </I>
|
|
|
|
:
|
|
<B>string -> Parsetree.expression option</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">Module</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
|
|
<DL>
|
|
<DT id="4"><A HREF="#lbAE">A generic Parsetree mapper</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">Apply mappers to compilation units</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">Registration API</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">Convenience functions to write mappers</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">Helper functions to call external mappers</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">Cookies</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:36 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|