Ast_mapper - The interface of a -ppx rewriter

       Module Ast_mapper
        : sigend

       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:

       openAsttypesopenParsetreeopenAst_mapperlettest_mapperargv={default_mapperwithexpr=funmapperexpr->matchexprwith|{pexp_desc=Pexp_extension({txt="test"},PStr[])}->Ast_helper.Exp.constant(Pconst_integer("42",None))|other->default_mapper.exprmapperother;}let()=register"ppx_test"test_mapper

       This -ppx rewriter, which replaces [%test] in expressions with the constant 42 , can  be  compiled  using
       ocamlc-oppx_test-I+compiler-libsocamlcommon.cmappx_test.ml .

       Warning: this module is unstable and part of Compiler_libs .

   AgenericParsetreemappertypemapper = {
        attribute : mapper->Parsetree.attribute->Parsetree.attribute ;
        attributes : mapper->Parsetree.attributelist->Parsetree.attributelist ;
        binding_op : mapper->Parsetree.binding_op->Parsetree.binding_op ;
        case : mapper->Parsetree.case->Parsetree.case ;
        cases : mapper->Parsetree.caselist->Parsetree.caselist ;
        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 ;
        directive_argument : mapper->Parsetree.directive_argument->Parsetree.directive_argument ;
        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 ;
        toplevel_directive : mapper->Parsetree.toplevel_directive->Parsetree.toplevel_directive ;
        toplevel_phrase : mapper->Parsetree.toplevel_phrase->Parsetree.toplevel_phrase ;
        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.

       valdefault_mapper : mapper

       A default mapper, which implements a "deep identity" mapping.

   Applymapperstocompilationunitsvaltool_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   ,
       Clflags.hidden_include_dirs , Load_path , Clflags.open_modules , Clflags.for_package , Clflags.debug .

       valapply : 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.

       valrun_main : (stringlist->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.

   RegistrationAPIvalregister_function : (string->(stringlist->mapper)->unit)refvalregister : string->(stringlist->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.

   Conveniencefunctionstowritemappersvalmap_opt : ('a->'b)->'aoption->'boptionvalextension_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.

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

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

       valadd_ppx_context_sig : tool_name:string->Parsetree.signature->Parsetree.signature

       Same as add_ppx_context_str , but for signatures.

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

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

       valset_cookie : string->Parsetree.expression->unitvalget_cookie : string->Parsetree.expressionoption

OCamldoc                                           2025-06-12                                     Ast_mapper(3o)

       Module   Ast_mapper

       Ast_mapper - The interface of a -ppx rewriter