# Module Ppx_deriving

    module Ppx_deriving: sig .. end

Public API of `ppx_deriving` executable.

## Registration

    type deriver = {

`` | `name : `string`;`
`` | `core_type : `(Parsetree.core_type -> Parsetree.expression) option`;`
`` | `type_decl_str : `options:(string * Parsetree.expression) list -> path:string list -> Parsetree.type_declaration list -> Parsetree.structure`;`
`` | `type_ext_str : `options:(string * Parsetree.expression) list -> path:string list -> Parsetree.type_extension -> Parsetree.structure`;`
`` | `module_type_decl_str : `options:(string * Parsetree.expression) list -> path:string list -> Parsetree.module_type_declaration -> Parsetree.structure`;`
`` | `type_decl_sig : `options:(string * Parsetree.expression) list -> path:string list -> Parsetree.type_declaration list -> Parsetree.signature`;`
`` | `type_ext_sig : `options:(string * Parsetree.expression) list -> path:string list -> Parsetree.type_extension -> Parsetree.signature`;`
`` | `module_type_decl_sig : `options:(string * Parsetree.expression) list -> path:string list -> Parsetree.module_type_declaration -> Parsetree.signature`;`

}
A type of deriving plugins.

A structure or signature deriving function accepts a list of `~options`, a `~path` of modules for the type declaration currently being processed (with `[]` for toplevel phrases), and a type declaration item (`type t = .. and t' = ..`), and returns a list of items to be appended after the type declaration item in structure and signature. It is invoked by `[@@deriving]` annotations.

A type deriving function accepts a type and returns a corresponding derived expression. It is invoked by `[%derive.foo:]` and `[%foo:]` annotations. If this function is missing, the corresponding `[%foo:]` annotation is ignored.

The structure and signature deriving functions are invoked in the order in which they appear in the source code.

    val register : deriver -> unit

`register deriver` registers `deriver` according to its `name` field.

    val add_register_hook : (deriver -> unit) -> unit

`add_register_hook hook` adds `hook` to be executed whenever a new deriver is registered.

    val derivers : unit -> deriver list

`derivers ()` returns all currently registered derivers.

    val create : string ->
           ?core_type:(Parsetree.core_type -> Parsetree.expression) ->
           ?type_ext_str:(options:(string * Parsetree.expression) list ->
                          path:string list ->
                          Parsetree.type_extension -> Parsetree.structure) ->
           ?type_ext_sig:(options:(string * Parsetree.expression) list ->
                          path:string list ->
                          Parsetree.type_extension -> Parsetree.signature) ->
           ?type_decl_str:(options:(string * Parsetree.expression) list ->
                           path:string list ->
                           Parsetree.type_declaration list -> Parsetree.structure) ->
           ?type_decl_sig:(options:(string * Parsetree.expression) list ->
                           path:string list ->
                           Parsetree.type_declaration list -> Parsetree.signature) ->
           ?module_type_decl_str:(options:(string * Parsetree.expression) list ->
                                  path:string list ->
                                  Parsetree.module_type_declaration ->
                                  Parsetree.structure) ->
           ?module_type_decl_sig:(options:(string * Parsetree.expression) list ->
                                  path:string list ->
                                  Parsetree.module_type_declaration ->
                                  Parsetree.signature) ->
           unit -> deriver

Creating `Ppx_deriving.deriver` structure.

    val lookup : string -> deriver option

`lookup name` looks up a deriver called `name`.

## Error handling

    val raise_errorf : ?sub:Location.error list ->
           ?if_highlight:string ->
           ?loc:Location.t -> ('a, unit, string, 'b) Pervasives.format4 -> 'a

`raise_error` is a shorthand for raising `Location.Error` with the result of `Location.errorf`.

    val string_of_core_type : Parsetree.core_type -> string

`string_of_core_type typ` unparses `typ`, omitting any attributes.

## Option parsing

    module Arg: sig .. end

`Ppx_deriving.Arg` contains convenience functions that extract constants from AST fragments, to be used when parsing options or `[@attributes]` attached to types, fields or constructors.

## Hygiene

    type quoter

A `quoter` remembers a set of expressions.

    val create_quoter : unit -> quoter

`quoter ()` creates an empty quoter.

    val quote : quoter:quoter -> Parsetree.expression -> Parsetree.expression

`quote quoter expr` records a pure expression `expr` within `quoter` and returns an expression which has the same value as `expr` in the context that `sanitize` provides.

    val sanitize : ?module_:Longident.t ->
           ?quoter:quoter -> Parsetree.expression -> Parsetree.expression

`sanitize module_ quoter expr` wraps `expr` in a way that ensures that the contents of `module_` and `Pervasives`, as well as the identifiers in expressions returned by `quote` are in scope, and returns the wrapped expression. `module_` defaults to ! if it's not provided

    val with_quoter : (quoter -> 'a -> Parsetree.expression) ->
           'a -> Parsetree.expression

`with_quoter fn` ≡ `fun fn a -> let quoter = create_quoter () in sanitize ~quoter (fn quoter a)`

## AST manipulation

    val expand_path : path:string list -> string -> string

`expand_path name` returns `name` with the `path` module path prepended, e.g. `expand_path ["Foo";"M"] "t"` = `"Foo.M.t"` and `expand_path [] "t"` = `"t"`

    val path_of_type_decl : path:string list -> Parsetree.type_declaration -> string list

`path_of_type_decl ~path type_` returns `path` if `type_` does not have a manifest or the manifest is not a constructor, and the module path of manifest otherwise.

`path_of_type_decl` is useful when determining the canonical path location of fields and constructors; e.g. for `type bar = M.foo = A | B`, it will return `["M"]`.

    val mangle_type_decl : ?fixpoint:string ->
           [ `Prefix of string | `PrefixSuffix of string * string | `Suffix of string ] ->
           Parsetree.type_declaration -> string

`mangle_type_decl ~fixpoint affix type_` derives a function name from `type_` name by doing nothing if `type_` is named `fixpoint` (`"t"` by default), or appending and/or prepending `affix` via an underscore.

    val mangle_lid : ?fixpoint:string ->
           [ `Prefix of string | `PrefixSuffix of string * string | `Suffix of string ] ->
           Longident.t -> Longident.t

`mangle_lid ~fixpoint affix lid` does the same as `Ppx_deriving.mangle_type_decl`, but for the last component of `lid`.

    val attr : deriver:string ->
           string -> Parsetree.attributes -> Parsetree.attribute option

`attr ~deriver name attrs` searches for an attribute `[@deriving.deriver.attr]` in `attrs` if any attribute with name starting with `@deriving.deriver` exists, or `[@deriver.attr]` if any attribute with name starting with `@deriver` exists, or `[@attr]` otherwise.

    val attr_warning : Parsetree.expression -> Parsetree.attribute

`attr_warning expr` builds the attribute `@ocaml.warning expr`

    val free_vars_in_core_type : Parsetree.core_type -> string list

`free_vars_in_core_type typ` returns unique free variables in `typ` in lexical order.

    val remove_pervasives : deriver:string -> Parsetree.core_type -> Parsetree.core_type

`remove_pervasives ~deriver typ` removes the leading "Pervasives." module name in longidents. Type expressions marked with `[@nobuiltin]` are ignored.

The name of the deriving plugin should be passed as `deriver`; it is used in error messages.

    val fresh_var : string list -> string

`fresh_var bound` returns a fresh variable name not present in `bound`. The name is selected in alphabetical succession.

    val fold_left_type_decl : ('a -> string -> 'a) -> 'a -> Parsetree.type_declaration -> 'a

`fold_left_type_decl fn accum type_` performs a left fold over all type variable (i.e. not wildcard) parameters in `type_`.

    val fold_right_type_decl : (string -> 'a -> 'a) -> Parsetree.type_declaration -> 'a -> 'a

`fold_right_type_decl fn accum type_` performs a right fold over all type variable (i.e. not wildcard) parameters in `type_`.

    val fold_left_type_ext : ('a -> string -> 'a) -> 'a -> Parsetree.type_extension -> 'a

`fold_left_type_ext fn accum type_` performs a left fold over all type variable (i.e. not wildcard) parameters in `type_`.

    val fold_right_type_ext : (string -> 'a -> 'a) -> Parsetree.type_extension -> 'a -> 'a

`fold_right_type_ext fn accum type_` performs a right fold over all type variable (i.e. not wildcard) parameters in `type_`.

    val poly_fun_of_type_decl : Parsetree.type_declaration -> Parsetree.expression -> Parsetree.expression

`poly_fun_of_type_decl type_ expr` wraps `expr` into `fun poly_N -> ...` for every type parameter `'N` present in `type_`. For example, if `type_` refers to `type ('a, 'b) map`, `expr` will be wrapped into `fun poly_a poly_b -> [%e expr]`.

`_` parameters are ignored.

    val poly_fun_of_type_ext : Parsetree.type_extension -> Parsetree.expression -> Parsetree.expression

Same as `Ppx_deriving.poly_fun_of_type_decl` but for type extension.

    val poly_apply_of_type_decl : Parsetree.type_declaration -> Parsetree.expression -> Parsetree.expression

`poly_apply_of_type_decl type_ expr` wraps `expr` into `expr poly_N` for every type parameter `'N` present in `type_`. For example, if `type_` refers to `type ('a, 'b) map`, `expr` will be wrapped into `[%e expr] poly_a poly_b`.

`_` parameters are ignored.

    val poly_apply_of_type_ext : Parsetree.type_extension -> Parsetree.expression -> Parsetree.expression

Same as `Ppx_deriving.poly_apply_of_type_decl` but for type extension.

    val poly_arrow_of_type_decl : (Parsetree.core_type -> Parsetree.core_type) ->
           Parsetree.type_declaration -> Parsetree.core_type -> Parsetree.core_type

`poly_arrow_of_type_decl fn type_ typ` wraps `typ` in an arrow with `fn [%type: 'N]` as argument for every type parameter `'N` present in `type_`. For example, if `type_` refers to `type ('a, 'b) map` and `fn` is `fun var -> [%type: [%t var] -> string]`, `typ` will be wrapped into `('a -> string) -> ('b -> string) -> [%t typ]`.

`_` parameters are ignored.

    val poly_arrow_of_type_ext : (Parsetree.core_type -> Parsetree.core_type) ->
           Parsetree.type_extension -> Parsetree.core_type -> Parsetree.core_type

Same as `Ppx_deriving.poly_arrow_of_type_decl` but for type extension.

    val core_type_of_type_decl : Parsetree.type_declaration -> Parsetree.core_type

`core_type_of_type_decl type_` constructs type `('a, 'b, ...) t` for type declaration `type ('a, 'b, ...) t = ...`.

    val core_type_of_type_ext : Parsetree.type_extension -> Parsetree.core_type

Same as `Ppx_deriving.core_type_of_type_decl` but for type extension.

    val instantiate : string list ->
           Parsetree.type_declaration -> Parsetree.core_type * string list * string list

`instantiate bound type_` returns `typ, vars, bound'` where `typ` is a type instantiated from type declaration `type_`, `vars` ≡ `free_vars_in_core_type typ` and `bound'` ≡ `bound @ vars`.

    val fold_exprs : ?unit:Parsetree.expression ->
           (Parsetree.expression -> Parsetree.expression -> Parsetree.expression) ->
           Parsetree.expression list -> Parsetree.expression

`fold_exprs ~unit fn exprs` folds `exprs` using head of `exprs` as initial accumulator value, or `unit` if `exprs = []`.

See also `Ppx_deriving.seq_reduce` and `Ppx_deriving.binop_reduce`.

    val seq_reduce : ?sep:Parsetree.expression ->
           Parsetree.expression -> Parsetree.expression -> Parsetree.expression

When `sep` is present: `seq_reduce` ≡ `fun x a b -> [%expr [%e a]; [%e x]; [%e b]]`. When `sep` is missing: `seq_reduce` ≡ `fun a b -> [%expr [%e a]; [%e b]]`.

    val binop_reduce : Parsetree.expression ->
           Parsetree.expression -> Parsetree.expression -> Parsetree.expression

`binop_reduce` ≡ `fun x a b -> [%expr [%e x] [%e a] [%e b]]`.

    val strong_type_of_type : Parsetree.core_type -> Parsetree.core_type

`strong_type_of_type ty` transform a type ty to `freevars . ty`, giving a strong polymorphic type

    val mapper : Ast_mapper.mapper

The mapper for the currently loaded deriving plugins. It is useful for recursively processing expression-valued attributes.

## Miscellanea

    val hash_variant : string -> int

`hash_variant x` ≡ `Btype.hash_variant x`.