Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.in-
       clude_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 in-
       serted 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 ===

       === 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			  2017-04-30			 Ast_mapper(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Ast_mapper&sektion=3o&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help