manpagez: man pages & more
man Ast_mapper(3)
Home | html | info | man
Ast_mapper(3)                    OCaml library                   Ast_mapper(3)




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, for-
       warding of command-line flags, and storing state.


       Ast_mapper.mapper  allows  to implement AST rewriting using open recur-
       sion.  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 con-
       stant  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 -> Parse-
       tree.class_declaration ;
        class_description : mapper ->  Parsetree.class_description  ->  Parse-
       tree.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  ->   Parse-
       tree.class_signature ;
        class_structure   :  mapper  ->  Parsetree.class_structure  ->  Parse-
       tree.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  -> Parse-
       tree.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  ->  Parse-
       tree.label_declaration ;
        location : mapper -> Location.t -> Location.t ;
        module_binding  : mapper -> Parsetree.module_binding -> Parsetree.mod-
       ule_binding ;
        module_declaration : mapper -> Parsetree.module_declaration ->  Parse-
       tree.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  ->  Parse-
       tree.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.sig-
       nature_item ;
        structure : mapper -> Parsetree.structure -> Parsetree.structure ;
        structure_item  :  mapper  ->   Parsetree.structure_item   ->   Parse-
       tree.structure_item ;
        typ : mapper -> Parsetree.core_type -> Parsetree.core_type ;
        type_declaration  :  mapper  ->  Parsetree.type_declaration  -> Parse-
       tree.type_declaration ;
        type_extension  :  mapper  ->   Parsetree.type_extension   ->   Parse-
       tree.type_extension ;
        type_kind : mapper -> Parsetree.type_kind -> Parsetree.type_kind ;
        value_binding   :   mapper   ->   Parsetree.value_binding   ->  Parse-
       tree.value_binding ;
        value_description : mapper ->  Parsetree.value_description  ->  Parse-
       tree.value_description ;
        with_constraint   :  mapper  ->  Parsetree.with_constraint  ->  Parse-
       tree.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  synchro-
       nized   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 implemen-
       tation or interface.



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

       Entry point to call to implement a standalone -ppx rewriter from a map-
       per, 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  map-
       per  immediately, taking arguments from the process command line.  This
       is to support a scenario where a mapper is linked as a stand-alone exe-
       cutable.

       It is possible to overwrite the register_function to define "-ppx driv-
       ers", 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 fur-
       ther  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






OCamldoc                          2014-10-18                     Ast_mapper(3)

ocaml 4.02.1 - Generated Sun Oct 19 06:36:38 CDT 2014
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.