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 ;
        constant : mapper -> Parsetree.constant -> Parsetree.constant ;
        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