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

       Warning: this module is unstable and part of Compiler_libs .

   A generic Parsetree mapper
       type mapper = {
        attribute : mapper -> Parsetree.attribute -> Parsetree.attribute ;
        attributes : mapper -> Parsetree.attribute list -> Parsetree.attribute list ;
        binding_op : mapper -> Parsetree.binding_op -> Parsetree.binding_op ;
        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_substitution      :      mapper      ->      Parsetree.module_substitution      ->
       Parsetree.module_substitution ;
        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_declaration : mapper -> Parsetree.open_declaration -> Parsetree.open_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_exception : mapper -> Parsetree.type_exception -> Parsetree.type_exception ;
        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   ,   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) 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