NAME

       Ast_mapper - The interface of a -ppx rewriter

Module

       Module   Ast_mapper

Documentation

       Module Ast_mapper
        : sig end

       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.

       Ast_mapper.mapper allows to implement AST  rewriting  using  open  recursion.   A  typical
       mapper would be based on Ast_mapper.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.

       === Apply mappers to compilation units ===

       val tool_name : unit -> string

       Can be used within a ppx preprocessor to know which tool is calling it ocamlc , ocamlopt ,
       ocamldoc , ocamldep , ocaml , ...  Some global variables that reflect command-line options
       are  automatically  synchronized  between  the  calling  tool  and  the  ppx preprocessor:
       Clflags.include_dirs , Config.load_path ,  Clflags.open_modules  ,  Clflags.for_package  ,
       Clflags.debug .

       val apply : source:string -> target:string -> mapper -> unit

       Apply  a  mapper (parametrized by the unit name) to a dumped parsetree found in the source
       file and put the result in the target file. The structure or signature field of the mapper
       is applied to the implementation or interface.

       val run_main : (string list -> mapper) -> unit

       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
       Location.input_name  .   This  function  implements  proper  error  reporting for uncaught
       exceptions.

       === Registration API ===

       val register_function : (string -> (string list -> mapper) -> unit) Pervasives.ref

       val register : string -> (string list -> mapper) -> unit

       Apply the register_function .  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.

       It is possible to overwrite the register_function to define "-ppx drivers", which  combine
       several   mappers   in   a  single  process.   Typically,  a  driver  starts  by  defining
       register_function 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.

       The first argument to register is a symbolic name to be used by the ppx driver.

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

       === Helper functions to call external mappers ===

       val add_ppx_context_str : tool_name:string -> Parsetree.structure -> Parsetree.structure

       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.

       val add_ppx_context_sig : tool_name:string -> Parsetree.signature -> Parsetree.signature

       Same as add_ppx_context_str , but for signatures.

       val drop_ppx_context_str : restore:bool -> Parsetree.structure -> Parsetree.structure

       Drop the ocaml.ppx.context attribute from a structure.  If restore is true,  also  restore
       the associated data in the current process.

       val drop_ppx_context_sig : restore:bool -> Parsetree.signature -> Parsetree.signature

       Same as drop_ppx_context_str , but for signatures.

       === Cookies ===

       ===  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). ===

       val set_cookie : string -> Parsetree.expression -> unit

       val get_cookie : string -> Parsetree.expression option