### Example Usage of Deriving.Args Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Deriving/Args/index.html An example demonstrating how to use `Deriving.Args` functions and the `+>` operator to define a sequence of arguments. ```APIDOC Deriving.Args.(<0xC2><0xA0> empty +> arg_option "foo" (estring __) +> arg_option "bar" (pack2 (eint __ ** eint __)) +> flag "dotdotdot") ``` -------------------------------- ### Example: Collecting String Constants Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_traverse/index.html An example demonstrating how to use `Ast_traverse.fold` to collect all string constants from an AST. ```APIDOC ## Example: Collecting String Constants This example shows how to inherit from `Ast_traverse.fold` to traverse an AST and collect all string constants. ```ocaml let string_constants_of = object inherit [string list] Ast_traverse.fold as super method! expression e acc = let acc = super#expression e acc in match e.pexp_desc with | Pexp_constant (Const_string (s, _)) -> s :: acc | _ -> acc method! pattern p acc = let acc = super#pattern p acc in match p.ppat_desc with | Ppat_constant (Const_string (s, _)) -> s :: acc | _ -> acc end let string_constants_of_structure = string_constants_of#structure ``` ``` -------------------------------- ### Function f Usage Example Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/matching-code.html Example of calling the composed function 'f' with a string 'name' and an expression, showing the successful result. ```ocaml f "name" [%expr ()] ;; ``` -------------------------------- ### Example of estring with __' Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Demonstrates the usage of `__'` pattern to capture a string constant along with its location. ```ocaml estring __' ``` -------------------------------- ### Pexp_unreachable Example Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/index.html Represents an unreachable code path in the AST. ```ocaml | Pexp_unreachable ``` -------------------------------- ### Example of attribute matching with longest match rule Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Attribute/index.html Illustrates how Ppxlib selects the longest matching attribute when multiple are possible. This example shows a specific `@foo.default 0` attribute being matched. ```ocaml type t = { x : int [@default 42] [@foo.default 0] } ``` -------------------------------- ### Extender Example with [%yojson] Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/driver.html Demonstrates an extender transformation that rewrites a DSL-like syntax within an extension node into OCaml code. This is useful for generating values from custom syntaxes. ```ocaml let json = [%yojson [ { name = "Anne"; grades = ["A"; "B-"; "B+"] } ; { name = "Bernard"; grades = ["B+"; "A"; "B-"] } ] ] ``` ```ocaml let json = `List [ `Assoc [ ("name", `String "Anne") ; ("grades", `List [`String "A"; `String "B-"; `String "B+"]) ] ; `Assoc [ ("name", `String "Bernard") ; ("grades", `List [`String "B+"; `String "A"; `String "B-"]) ] ] ``` -------------------------------- ### Pexp_extension Example Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/index.html Illustrates the `Pexp_extension` constructor for representing extension nodes in the AST, typically used for ppx syntax like `[%id]`. ```ocaml | Pexp_extension of extension ``` -------------------------------- ### Example of pair with eint and __' Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Illustrates a case where using `__'` with `pair` and `eint` might not yield the expected result, suggesting alternatives like using `pexp_loc`. ```ocaml pair (eint (int 42)) __' ``` -------------------------------- ### Apply an Extender Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/writing-ppxs.html An example of applying a custom extender using the `[%add_suffix ...]` syntax. This demonstrates how the registered extender transforms the code. ```ocaml let () = print_endline [%add_suffix "helloworld"] ``` -------------------------------- ### Lift Traversal Example Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/ast-traversal.html Illustrates a 'lift' traversal for a simple tree structure, transforming a Parsetree value into one of another type in a bottom-up manner. ```ocaml let lift ~f = function Leaf a -> f.leaf a | Node(a,x,y) -> f.node a (lift ~f x) (lift ~f y) ``` -------------------------------- ### create Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/Out_channel/index.html Creates a new output channel. Allows configuration of binary mode, append mode, existence check, and permissions. ```APIDOC ## create ### Description Creates a new output channel with customizable options. ### Signature `val create : ?binary:bool -> ?append:bool -> ?fail_if_exists:bool -> ?perm:int -> string -> Stdlib.out_channel` ### Parameters - `?binary` (bool) - Optional: If true, opens the channel in binary mode. - `?append` (bool) - Optional: If true, appends to the file if it exists. - `?fail_if_exists` (bool) - Optional: If true, raises an error if the file already exists. - `?perm` (int) - Optional: File permissions. - `string` - The filename to open. ### Returns `Stdlib.out_channel` - The created output channel. ``` -------------------------------- ### Multiple Newtype Parameters Example Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/index.html Shows how multiple `Pparam_newtype` nodes are used to represent multiple type parameters in a function signature, such as `(type a b c)`. Each parameter gets its own node with associated location information. ```ocaml [ { pparam_kind = Pparam_newtype a; pparam_loc = loc1 }; { pparam_kind = Pparam_newtype b; pparam_loc = loc2 }; { pparam_kind = Pparam_newtype c; pparam_loc = loc3 }; ] ``` -------------------------------- ### Expand Environment Variables with ppx_get_env Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/examples.html This PPX extension expands `[%get_env "VAR_NAME"]` into the string value of the environment variable `VAR_NAME` at compile time. It's a toy example and has limitations with build systems like Dune due to its reliance on environment variables. ```ocaml let () = print_string [%get_env "foo"] ``` ```ocaml let () = print_string "foo" ``` ```ocaml open Ppxlib let expand ~ctxt env_var = let loc = Expansion_context.Extension.extension_point_loc ctxt in match Sys.getenv env_var with | value -> Ast_builder.Default.estring ~loc value | exception Not_found -> let ext = Location.error_extensionf ~loc "The environment variable %s is unbound" env_var in Ast_builder.Default.pexp_extension ~loc ext let my_extension = Extension.V3.declare "get_env" Extension.Context.expression Ast_pattern.(single_expr_payload (estring __)) expand let rule = Ppxlib.Context_free.Rule.extension my_extension let () = Driver.register_transformation ~rules:[ rule ] "get_env" ``` -------------------------------- ### Basic AST Map Traversal Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/ast-traversal.html Demonstrates the basic usage of the Ast_traverse.map class to create an identity map for a payload. This serves as a starting point for custom traversals. ```ocaml let f payload = let map = new Ppxlib.Ast_traverse.map in map#payload ;; ``` -------------------------------- ### Create a Quoter in OCaml Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/good-practices.html Initialize a quoter instance using `Quoter.create`. This is the first step in using ppxlib's quoting mechanism. ```ocaml # open Expansion_helper ;; #s let quoter = Quoter.create () ;; val quoter : Quoter.t = ``` -------------------------------- ### Implement a Debug Rewriter with Quoting Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/good-practices.html An example of a `debug` rewriter that uses `ppxlib`'s quoting mechanism to handle variable names safely. It includes creating a quoter, an AST mapper to replace variables with quoted versions, and sanitizing the final expression. ```ocaml # let rewrite expr = (* Create a quoter *) let quoter = Quoter.create () in (* An AST mapper to log and replace variables with quoted ones *) let replace_var = object (* See the chapter on AST traverse *) inherit Ast_traverse.map as super (* in case of expression *) method! expression expr = match expr.pexp_desc with (* in case of identifier (not "+") *) | Pexp_ident { txt = Lident var_name; loc } when not (String.equal "+" var_name) -> (* quote the var *) let quoted_var = Quoter.quote quoter expr in let name = Ast_builder.Default.estring ~loc var_name in (* and rewrite the expression *) [%expr debug [%e name] [%e quoted_var]; [%e quoted_var]] (* otherwise, continue inside recursively *) | _ -> super#expression expr end in let quoted_rewrite = replace_var#expression expr in let loc = expr.pexp_loc in (* Sanitize the whole thing *) Quoter.sanitize quoter [%expr let debug = Printf.printf "%s = %d; " in [%e quoted_rewrite]] ;; val rewrite : expression -> expression = ``` -------------------------------- ### create Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/In_channel/index.html Creates an input channel from a string. Optionally, it can be opened in binary mode. ```APIDOC ## create ### Description Creates an input channel from a string. Optionally, it can be opened in binary mode. ### Signature `val create : ?binary:bool -> string -> Stdlib.in_channel` ### Parameters - `binary` (bool) - Optional. If true, opens the channel in binary mode. - `string` (string) - The string to create the input channel from. ``` -------------------------------- ### Example of a non-recursive type approximated as recursive Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/class-type_is_recursive/index.html This example demonstrates a scenario where a type `t` is defined using a module alias, leading `type_is_recursive` to incorrectly identify it as recursive. This highlights the approximation nature of the class. ```ocaml module M = struct type t = Foo end type t = M.(t) ``` -------------------------------- ### set_filename Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Location/index.html Updates the filename in both the start and end positions of a location. ```APIDOC val set_filename : t -> string -> t ``` -------------------------------- ### Get Location Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/Located/index.html Extracts the `Location.t` associated with a located value. ```APIDOC val loc : _ t -> Location.t ``` -------------------------------- ### init Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Location/index.html Initializes a lexer buffer with the filename and line number of a given file. ```APIDOC val init : Stdlib.Lexing.lexbuf -> string -> unit ``` -------------------------------- ### Pp_ast.Config.make Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Pp_ast/Config/index.html Creates a custom configuration for pretty-printing ASTs. Allows customization of attribute visibility, location display, and location formatting. ```APIDOC ## Pp_ast.Config.make ### Description Creates a custom pretty-printing configuration for ASTs. This function allows fine-grained control over how ASTs are displayed, including whether attributes and locations are shown, and how locations are formatted. ### Signature `val make : ?show_attrs:bool -> ?show_locs:bool -> ?loc_mode:[ `Short | `Full ] -> ?printer:repr pp -> unit -> t` ### Parameters #### Optional Parameters - **?show_attrs** (bool) - Controls whether attributes are shown or hidden. Defaults to `false`. - **?show_locs** (bool) - Controls whether locations are shown or hidden. Defaults to `false`. - **?loc_mode** (`Short` | `Full`) - Controls how locations are displayed if they are shown. Defaults to ``Short`. - ``Short`: Displays locations as `"l1c6..l2c2"` for multiline, `"l1c6..12"` for single line. Ghost locations are suffixed with `"(g)"`. - ``Full`: Displays locations like any other record. - **?printer** (repr pp) - A custom printer function. ### Returns - **t** - A pretty-printing configuration object. ``` -------------------------------- ### Get Extension Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Extension/Context/index.html Retrieves the extension associated with a given AST node. ```APIDOC val get_extension : 'a t -> 'a -> ((string Astlib.Location.loc * Astlib.Ast_502.Parsetree.payload) * Astlib.Ast_502.Parsetree.attribute list) option ``` -------------------------------- ### location Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Matches a location by its start position, end position, and ghost flag. ```APIDOC ## location ### Description Matches a location by its start position, end position, and ghost flag. ### Signature ``` val location : start:(Stdlib.Lexing.position, 'a, 'b) Ppxlib__.Ast_pattern0.t -> end_:(Stdlib.Lexing.position, 'b, 'c) Ppxlib__.Ast_pattern0.t -> ghost:(bool, 'c, 'd) Ppxlib__.Ast_pattern0.t -> (Astlib.Location.t, 'a, 'd) Ppxlib__.Ast_pattern0.t ``` ``` -------------------------------- ### Get Head Element (hd) Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/NonEmptyList/index.html Retrieves the head element of a non-empty list. ```APIDOC val hd : ('a * 'b) -> 'a ``` -------------------------------- ### standalone Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Driver/index.html Configures the driver to be suitable for use with `-pp` or as a standalone command-line tool. ```APIDOC ## standalone ### Description Suitable for -pp and also usable as a standalone command line tool. ### Signature `val standalone : unit -> unit` ``` -------------------------------- ### Generated Pattern Structure Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/matching-code.html This is an example of the OCaml AST structure generated by Metaquot for a pattern. ```ocaml { pexp_desc = (Pexp_apply ({ pexp_desc = (Pexp_ident { txt = (Lident "+"); loc = _ }); pexp_loc = _; pexp_attributes = _ }, [(Nolabel, { pexp_desc = (Pexp_constant (Pconst_integer ("1", None))); pexp_loc = _; pexp_attributes = _ }); (Nolabel, { pexp_desc = (Pexp_constant (Pconst_integer ("1", None))); pexp_loc = _; pexp_attributes = _ })])); pexp_loc = _; pexp_attributes = _ } ``` -------------------------------- ### Deriving.Args.empty Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Deriving/Args/index.html Represents an empty set of arguments, serving as a starting point for argument definitions. ```APIDOC val empty : ('m, 'm) t ``` -------------------------------- ### apply_keyword_edition Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Keyword/index.html Processes keyword settings from environment variables and CLI options, initializing the compiler's lexer. ```APIDOC ## apply_keyword_edition ### Description Processes any keywords= sections from the OCAMLPARAM environment variable and CLI option and initialises the compiler's lexer with the correct keyword set. ### Signature `val apply_keyword_edition : cli:string option -> unit -> unit` ``` -------------------------------- ### Error Message Access and Modification Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Location/Error/index.html Functions to get and set the message associated with an error. ```APIDOC ## `Location.Error.message` ### Description Retrieves the primary message string from an error. ### Signature `val message : t -> string` ## `Location.Error.set_message` ### Description Updates the primary message string of an existing error. ### Signature `val set_message : t -> string -> t` ``` -------------------------------- ### Construct Open Infos: Fresh Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `open_infos` with `Fresh` to construct an `Ast.open_infos` node representing `open X`, creating a fresh namespace. ```ocaml open X ``` -------------------------------- ### get Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Caller_id/index.html Retrieves the location of the caller, optionally skipping specified strings in the call stack. ```APIDOC ## get ### Description Retrieves the location of the caller, optionally skipping specified strings in the call stack. ### Signature `val get : skip:string list -> Stdlib__Printexc.location option` ### Parameters #### skip - **skip** (string list) - A list of strings to filter out from the call stack when determining the caller's location. ### Returns - `Stdlib__Printexc.location option` - An option containing the caller's location if found, otherwise `None`. ``` -------------------------------- ### Getting the Name of a Floating Attribute Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Attribute/Floating/index.html Retrieves the string name of a declared floating attribute. ```APIDOC ## `name` ### Description Returns the name of the floating attribute. ### Signature `val name : (_, _) t -> string` ``` -------------------------------- ### Constructor Argument Patterns Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Patterns for matching constructor arguments. ```APIDOC ## pcstr_tuple ### Description Pattern for matching a tuple constructor argument. ### Signature ``` val pcstr_tuple : (Astlib.Ast_502.Parsetree.core_type list, 'a, 'b) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.constructor_arguments, 'a, 'b) Ppxlib__.Ast_pattern0.t ``` ``` ```APIDOC ## pcstr_record ### Description Pattern for matching a record constructor argument. ### Signature ``` val pcstr_record : (Astlib.Ast_502.Parsetree.label_declaration list, 'a, 'b) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.constructor_arguments, 'a, 'b) Ppxlib__.Ast_pattern0.t ``` ``` -------------------------------- ### Get Name of Longident Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Longident/index.html Extracts the string name from a `Longident.t`. For `Ldot (t, s)`, it returns `s`. For `Lident s`, it returns `s`. ```APIDOC val name : t -> string ``` -------------------------------- ### String Creation and Initialization Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/String/index.html Functions for creating and initializing strings. ```APIDOC ## String Creation and Initialization ### `make` Creates a string of a given length, filled with a specified character. - **Signature**: `val make : int -> char -> string` ### `init` Creates a string of a given length by applying a function to each index. - **Signature**: `val init : int -> f:(int -> char) -> string` ### `empty` Represents an empty string. - **Signature**: `val empty : string` ``` -------------------------------- ### pexp_letmodule Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Matches a let-module binding. ```APIDOC ## pexp_letmodule ### Description Matches a let-module binding. ### Signature `val pexp_letmodule : (string option, 'a, 'b) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.module_expr, 'b, 'c) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.expression, 'c, 'd) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.expression, 'a, 'd) Ppxlib__.Ast_pattern0.t` ``` -------------------------------- ### Prefix and Suffix Checks Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/Bytes/index.html Functions for checking if a bytes sequence starts or ends with a given prefix or suffix. ```APIDOC ## starts_with ### Description Checks if a bytes sequence starts with a given prefix. ### Parameters #### Path Parameters - **prefix** (bytes) - The prefix to check for. ### Method val starts_with : prefix:bytes -> bytes -> bool ## ends_with ### Description Checks if a bytes sequence ends with a given suffix. ### Parameters #### Path Parameters - **suffix** (bytes) - The suffix to check for. ### Method val ends_with : suffix:bytes -> bytes -> bool ``` -------------------------------- ### Extension and Extension Constructor Conversions Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Migrate_504_503/index.html Functions for copying extensions and extension constructors. ```APIDOC ## copy_extension ### Description Copies an extension from Ast_504 to Ast_503. ### Signature `val copy_extension : Ast_504.Parsetree.extension -> Ast_503.Parsetree.extension` ## copy_extension_constructor ### Description Copies an extension constructor from Ast_504 to Ast_503. ### Signature `val copy_extension_constructor : Ast_504.Parsetree.extension_constructor -> Ast_503.Parsetree.extension_constructor` ## copy_extension_constructor_kind ### Description Copies the kind of an extension constructor from Ast_504 to Ast_503. ### Signature `val copy_extension_constructor_kind : Ast_504.Parsetree.extension_constructor_kind -> Ast_503.Parsetree.extension_constructor_kind` ``` -------------------------------- ### Location Type Definition Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Location/index.html Defines the structure of a location, including start and end positions and a ghost flag. ```APIDOC type t = Astlib.Location.t = { loc_start : Stdlib.Lexing.position; loc_end : Stdlib.Lexing.position; loc_ghost : bool; } ``` -------------------------------- ### plist Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Builds a pattern for a list. ```APIDOC ## plist ### Description `plist ~loc [pat1; pat2; pat3]` produces the list pattern `[pat1; pat2; pat3]`. ### Signature `val plist : loc:Location.t -> Astlib.Ast_502.Parsetree.pattern list -> Astlib.Ast_502.Parsetree.pattern` ``` -------------------------------- ### Attribute Retrieval Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Attribute/index.html Functions for getting attribute values, with options for error handling and marking attributes as seen. ```APIDOC ## `get_res` ### Description Retrieves the value of an attribute. Returns a `result` type, which can be `Ok` with the attribute's value or `Error` with a list of location errors if the attribute is duplicated. ### Signature `val get_res : ('a, 'b) t -> ?mark_as_seen:bool -> 'a -> ('b option, Location.Error.t Stdppx.NonEmptyList.t) Stdlib.result` ### Parameters - `?mark_as_seen` (bool): If true (default), marks the attribute as seen. If false, it does not. - The first argument is the attribute to retrieve. - The second argument is the item to search for the attribute on. ``` ```APIDOC ## `get` ### Description Retrieves the value of an attribute. Similar to `get_res`, but raises a located error if the attribute is duplicated. ### Signature `val get : ('a, 'b) t -> ?mark_as_seen:bool -> 'a -> 'b option` ``` ```APIDOC ## `has_flag_res` ### Description Checks if a flag attribute is present. Returns a `result` type indicating success or a list of location errors. ### Signature `val has_flag_res : 'a flag -> ?mark_as_seen:bool -> 'a -> (bool, Location.Error.t Stdppx.NonEmptyList.t) Stdlib.result` ``` ```APIDOC ## `has_flag` ### Description Checks if a flag attribute is present. Raises a located error if the attribute is duplicated. ### Signature `val has_flag : 'a flag -> ?mark_as_seen:bool -> 'a -> bool` ``` -------------------------------- ### Module Type Constraints in Ppxlib Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/index.html Illustrates different ways to specify module type constraints using Ppxlib's syntax, including `Pwith_modtype`, `Pwith_modtypesubst`, `Pwith_typesubst`, and `Pwith_modsubst`. ```ocaml (* `with module type X.Y = Z` *) ``` ```ocaml (* `with module type X.Y := sig end` *) ``` ```ocaml (* `with type X.t := ..., same format as [Pwith_type]` *) ``` ```ocaml (* `with module X.Y := Z` *) ``` -------------------------------- ### add_simple_handler Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Driver/Cookies/index.html A shorthand for registering a handler that gets a specific cookie and passes its parsed value to a callback function. ```APIDOC ## add_simple_handler ### Description A shorthand for registering a handler that gets a specific cookie and passes its parsed value to a callback function. ### Signature `val add_simple_handler : string -> (Astlib.Ast_502.Parsetree.expression, 'a -> 'a, 'b) Ast_pattern.t -> f:('b option -> unit) -> unit` ### Parameters - `name` (string): The name of the cookie to retrieve. - `pattern` ((Astlib.Ast_502.Parsetree.expression, 'a -> 'a, 'b) Ast_pattern.t): The pattern to parse the cookie value. - `f` (('b option -> unit)): The callback function that receives the parsed cookie value (or None if not found). ``` -------------------------------- ### with_file Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/Out_channel/index.html Opens a file, performs an action with the output channel, and ensures the channel is closed afterward. ```APIDOC ## with_file ### Description Opens a file, applies a function to its output channel, and ensures proper closure. ### Signature `val with_file : ?binary:bool -> ?append:bool -> ?fail_if_exists:bool -> ?perm:int -> string -> f:(Stdlib.out_channel -> 'a) -> 'a` ### Parameters - `?binary` (bool) - Optional: If true, opens the channel in binary mode. - `?append` (bool) - Optional: If true, appends to the file if it exists. - `?fail_if_exists` (bool) - Optional: If true, raises an error if the file already exists. - `?perm` (int) - Optional: File permissions. - `string` - The filename to open. - `f` (Stdlib.out_channel -> 'a) - The function to apply to the output channel. ### Returns `'a` - The result of the function `f`. ``` -------------------------------- ### Construct Ptyp_alias Core Type Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `ptyp_alias` to construct a `Ptyp_alias` node, representing type aliases. Example: `T as 'a`. ```ocaml val ptyp_alias : loc:Location.t -> Astlib.Ast_502.Parsetree.core_type -> string Astlib.Location.loc -> Astlib.Ast_502.Parsetree.core_type ``` -------------------------------- ### Driver.Create_file_property.set Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Driver/Create_file_property/index.html Sets a file property. If the `-output-metadata FILE` option is used, this information will be written to the specified file. ```APIDOC ## `val set : T.t -> unit` ### Description Sets a file property. This function is used to record a piece of information about a file that can be passed to the build system via metadata output. ### Parameters - `T.t`: The file property to set. ``` -------------------------------- ### Create Unit Expression and Pattern AST Nodes Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Make/index.html Use `eunit` to create an AST node for the unit expression `()` and `punit` for the unit pattern. ```ocaml val eunit : Astlib.Ast_502.Parsetree.expression val punit : Astlib.Ast_502.Parsetree.pattern ``` -------------------------------- ### Define Empty Deriver Dependencies Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/writing-ppxs.html An example of initializing deriver dependencies as an empty list. This indicates that the deriver has no prerequisites. ```ocaml let deps = [] ;; ``` -------------------------------- ### Standalone Driver Usage Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/driver.html This is the general command-line format for a standalone driver. It accepts extra arguments and can process one or more OCaml files. ```bash driver.exe [extra_args] [] ``` -------------------------------- ### Construct OCaml Location Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Make/index.html Use `location` to construct an Ast location with start and end positions and a ghost flag. ```OCaml Stdlib.Lexing.dummy_pos, Stdlib.Lexing.dummy_pos, false ``` -------------------------------- ### Construct Open Infos: Override Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `open_infos` with `Override` to construct an `Ast.open_infos` node representing `open! X`, which silences shadowing warnings. ```ocaml open! X ``` -------------------------------- ### Location Type Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Location/index.html Defines the structure for source code locations, including start and end positions and a ghost flag. ```APIDOC ## type t ### Description Represents a source code location, defined by start and end positions, and a boolean indicating if it's a ghost location. ### Fields - **loc_start** (Stdlib.Lexing.position) - The starting position of the location. - **loc_end** (Stdlib.Lexing.position) - The ending position of the location. - **loc_ghost** (bool) - A flag indicating if the location is a ghost location. ``` -------------------------------- ### fresh Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Pattern for matching a fresh override flag. ```APIDOC ## fresh ### Description Matches a fresh override flag. ### Type Signature ``` (Astlib.Ast_502.Asttypes.override_flag, 'a, 'a) Ppxlib__.Ast_pattern0.t ``` ``` -------------------------------- ### get Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Driver/Cookies/index.html Looks for a cookie by name and parses its value using a provided pattern. Raises an error if parsing fails. ```APIDOC ## get ### Description Looks for a cookie by name and parses its value using a provided pattern. Raises an error if parsing fails. ### Signature `val get : t -> string -> (Astlib.Ast_502.Parsetree.expression, 'a -> 'a, 'b) Ast_pattern.t -> 'b option` ### Parameters - `cookies` (t): The cookie collection to search within. - `name` (string): The name of the cookie to find. - `pattern` ((Astlib.Ast_502.Parsetree.expression, 'a -> 'a, 'b) Ast_pattern.t): The pattern to use for parsing the cookie's value. ``` -------------------------------- ### Construct Ptyp_package Core Type Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `ptyp_package` to construct a `Ptyp_package` node for type package declarations. Example: `(module S)`. ```ocaml val ptyp_package : loc:Location.t -> (Astlib.Longident.t Astlib.Location.loc * (Astlib.Longident.t Astlib.Location.loc * Astlib.Ast_502.Parsetree.core_type) list) -> Astlib.Ast_502.Parsetree.core_type ``` -------------------------------- ### make Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Deriving/Generator/V2/index.html Creates a generator that has access to the expansion context. This allows the generator to query information about the current expansion, such as the compiler's version or the target environment. ```APIDOC ## make ### Description Creates a generator with access to the expansion context. ### Signature `val make : ?attributes:Attribute.packed list -> ?deps:t list -> ?unused_code_warnings:bool -> ('f, 'output_ast) Args.t -> (ctxt:Expansion_context.Deriver.t -> 'input_ast -> 'f) -> ('output_ast, 'input_ast) t` ``` -------------------------------- ### Constructor Declaration Patterns Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Patterns for matching constructor declarations. ```APIDOC ## constructor_declaration_attributes ### Description Pattern for matching the attributes of a constructor declaration. ### Signature ``` val constructor_declaration_attributes : (Astlib.Ast_502.Parsetree.attribute list, 'a, 'b) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.constructor_declaration, 'b, 'c) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.constructor_declaration, 'a, 'c) Ppxlib__.Ast_pattern0.t ``` ``` ```APIDOC ## constructor_declaration ### Description Pattern for matching a full constructor declaration. ### Signature ``` val constructor_declaration : name:(string, 'a, 'b) Ppxlib__.Ast_pattern0.t -> vars:(string Astlib.Location.loc list, 'b, 'c) Ppxlib__.Ast_pattern0.t -> args: (Astlib.Ast_502.Parsetree.constructor_arguments, 'c, 'd) Ppxlib__.Ast_pattern0.t -> res: (Astlib.Ast_502.Parsetree.core_type option, 'd, 'e) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.constructor_declaration, 'a, 'e) Ppxlib__.Ast_pattern0.t ``` ``` -------------------------------- ### Construct Ptyp_extension Core Type Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `ptyp_extension` to construct a `Ptyp_extension` node in the OCaml type system. Example: `[%id]`. ```ocaml val ptyp_extension : loc:Location.t -> (string Astlib.Location.loc * Astlib.Ast_502.Parsetree.payload) -> Astlib.Ast_502.Parsetree.core_type ``` -------------------------------- ### copy_extension_constructor Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Migrate_409_408/index.html Copies an extension constructor from Ast_409.Parsetree to Ast_408.Parsetree. ```APIDOC ## copy_extension_constructor ### Description Copies an extension constructor from OCaml 4.09 AST to 4.08 AST. ### Parameters - `ec`: The `Ast_409.Parsetree.extension_constructor` to copy. ### Returns A `Ast_408.Parsetree.extension_constructor` representing the copied structure. ``` -------------------------------- ### Get Last Component of Longident Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Longident/index.html Retrieves the last string component of a longident. Raises an exception if the longident is empty or invalid. ```APIDOC val last_exn : t -> string ``` -------------------------------- ### Construct Ptyp_open Core Type Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `ptyp_open` to construct a `Ptyp_open` node, representing module type openings. Example: `M.(T)`. ```ocaml val ptyp_open : loc:Location.t -> Astlib.Longident.t Astlib.Location.loc -> Astlib.Ast_502.Parsetree.core_type -> Astlib.Ast_502.Parsetree.core_type ``` -------------------------------- ### Class `Ast.lift_map_with_context` Methods Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib_ast/Ast/class-lift_map_with_context/index.html The `Ast.lift_map_with_context` class provides methods to traverse and transform Abstract Syntax Tree (AST) nodes while carrying a context. Each method takes a context and an AST node, returning the transformed AST node and the updated context. ```APIDOC ## Class `Ast.lift_map_with_context` This class provides methods for traversing and transforming AST nodes with a context. ### Methods - `class_field : 'ctx -> class_field -> class_field * 'res` - `class_field_desc : 'ctx -> class_field_desc -> class_field_desc * 'res` - `class_field_kind : 'ctx -> class_field_kind -> class_field_kind * 'res` - `class_declaration : 'ctx -> class_declaration -> class_declaration * 'res` - `module_type : 'ctx -> module_type -> module_type * 'res` - `module_type_desc : 'ctx -> module_type_desc -> module_type_desc * 'res` - `functor_parameter : 'ctx -> functor_parameter -> functor_parameter * 'res` - `signature : 'ctx -> signature -> signature * 'res` - `signature_item : 'ctx -> signature_item -> signature_item * 'res` - `signature_item_desc : 'ctx -> signature_item_desc -> signature_item_desc * 'res` - `module_declaration : 'ctx -> module_declaration -> module_declaration * 'res` - `module_substitution : 'ctx -> module_substitution -> module_substitution * 'res` - `module_type_declaration : 'ctx -> module_type_declaration -> module_type_declaration * 'res` - `open_infos : 'a. ('ctx -> 'a -> 'a * 'res) -> 'ctx -> 'a open_infos -> 'a open_infos * 'res` - `open_description : 'ctx -> open_description -> open_description * 'res` - `open_declaration : 'ctx -> open_declaration -> open_declaration * 'res` - `include_infos : 'a. ('ctx -> 'a -> 'a * 'res) -> 'ctx -> 'a include_infos -> 'a include_infos * 'res` - `include_description : 'ctx -> include_description -> include_description * 'res` - `include_declaration : 'ctx -> include_declaration -> include_declaration * 'res` - `with_constraint : 'ctx -> with_constraint -> with_constraint * 'res` - `module_expr : 'ctx -> module_expr -> module_expr * 'res` - `module_expr_desc : 'ctx -> module_expr_desc -> module_expr_desc * 'res` - `structure : 'ctx -> structure -> structure * 'res` - `structure_item : 'ctx -> structure_item -> structure_item * 'res` - `structure_item_desc : 'ctx -> structure_item_desc -> structure_item_desc * 'res` - `value_constraint : 'ctx -> value_constraint -> value_constraint * 'res` - `value_binding : 'ctx -> value_binding -> value_binding * 'res` - `module_binding : 'ctx -> module_binding -> module_binding * 'res` - `toplevel_phrase : 'ctx -> toplevel_phrase -> toplevel_phrase * 'res` - `toplevel_directive : 'ctx -> toplevel_directive -> toplevel_directive * 'res` - `directive_argument : 'ctx -> directive_argument -> directive_argument * 'res` - `directive_argument_desc : 'ctx -> directive_argument_desc -> directive_argument_desc * 'res` - `cases : 'ctx -> cases -> cases * 'res` ``` -------------------------------- ### Deriver with Standard Attributes Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/writing-ppxs.html Example of using the `deriving` attribute to automatically generate implementations for standard functions like `show` and `yojson`. ```ocaml type tree = Leaf | Node of tree * tree [@@deriving show, yojson] ``` -------------------------------- ### Class Ast_traverse.map_with_expansion_context_and_errors Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_traverse/class-map_with_expansion_context_and_errors/index.html This class inherits from `Ppxlib_traverse_builtins.std_lift_mappers_with_context` and `Ppxlib_ast.Ast.lift_map_with_context`, providing a framework for AST mapping operations that manage expansion contexts and accumulate errors. ```APIDOC ## Class `Ast_traverse.map_with_expansion_context_and_errors` This class provides functionality for traversing and mapping Abstract Syntax Trees (ASTs) while managing expansion contexts and collecting errors. It inherits from standard traversal utilities to offer a robust mechanism for complex transformations. ### Inheritance - `inherit [Ppxlib__.Expansion_context.Base.t, Ppxlib__.Location.Error.t list] Ppxlib_traverse_builtins.std_lift_mappers_with_context` - `inherit [Ppxlib__.Expansion_context.Base.t, Ppxlib__.Location.Error.t list] Ppxlib_ast.Ast.lift_map_with_context` ### Purpose The primary purpose of this class is to facilitate AST transformations where each step of the traversal needs to be aware of the current expansion context and where errors encountered during the transformation should be collected and reported. ``` -------------------------------- ### Basic Patterns Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/index.html Core patterns for capturing, dropping, and creating alternatives. ```APIDOC ## `__` ### Description Pattern that captures its input. ### Signature val __ : ('a, 'a -> 'b, 'b) t ## `__'` ### Description Same as `__` but also captures the location. Should only be used for types that do not embed a location. ### Signature val __' : ('a, 'a Loc.t -> 'b, 'b) t ## `drop` ### Description Useful when some part of the AST is irrelevant. The captured value is ignored. ### Signature val drop : ('a, 'b, 'b) t ## `alt` ### Description Matches either the first pattern or the second one. ### Signature val alt : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> ('a, 'b, 'c) t ## `(|||)` ### Description Same as `alt`. ### Signature val (|||) : ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> ('a, 'b, 'c) t ## `alt_option` ### Description Same as `alt`, for the common case where the left-hand-side captures a value but not the right-hand-side. ### Signature val alt_option : ('a, 'v -> 'b, 'c) t -> ('a, 'b, 'c) t -> ('a, 'v option -> 'b, 'c) t ``` -------------------------------- ### Extension Constructor Migration Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Migrate_414_413/index.html Copies an extension constructor from OCaml 4.14 AST to 4.13 AST. ```APIDOC ## copy_extension_constructor ### Description Copies an extension constructor from OCaml 4.14 AST to 4.13 AST. ### Signature `val copy_extension_constructor : Ast_414.Parsetree.extension_constructor -> Ast_413.Parsetree.extension_constructor` ``` -------------------------------- ### Construct Location AST Node Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_builder/Default/index.html Use `location` to construct an `Ast.location` node, specifying start and end positions and a ghost flag. ```ocaml val location : start:Stdlib.Lexing.position -> end_:Stdlib.Lexing.position -> ghost:bool -> Astlib.Location.t ``` -------------------------------- ### create Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Ast_pattern/Packed/index.html Creates a packed AST pattern. It takes a base pattern and a value, returning a new packed pattern. ```APIDOC ## create ### Description Creates a packed AST pattern. ### Signature `val create : ('a, 'b, 'c) t -> 'b -> ('a, 'c) t` ``` -------------------------------- ### Get attribute value Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Attribute/index.html A convenience function over `get_res` that raises a located error if the attribute is duplicated. Returns `None` if the attribute is not found. ```ocaml val get : ('a, 'b) t -> ?mark_as_seen:bool -> 'a -> 'b option ``` -------------------------------- ### UTF-8 Character Handling Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/Bytes/index.html Functions for getting and setting UTF-8 encoded characters within bytes sequences, and checking for valid UTF-8 encoding. ```APIDOC ## get_utf_8_uchar ### Description Gets a UTF-8 encoded Unicode character from a bytes sequence at a given byte offset. ### Parameters #### Path Parameters - **offset** (int) - The byte offset in the bytes sequence. ### Method val get_utf_8_uchar : bytes -> int -> Stdlib.Uchar.utf_decode ## set_utf_8_uchar ### Description Sets a UTF-8 encoded Unicode character in a bytes sequence at a given byte offset. ### Parameters #### Path Parameters - **offset** (int) - The byte offset in the bytes sequence. - **uchar** (Stdlib.Uchar.t) - The Unicode character to set. ### Method val set_utf_8_uchar : bytes -> int -> Stdlib.Uchar.t -> int ## is_valid_utf_8 ### Description Checks if a bytes sequence contains valid UTF-8 encoded data. ### Method val is_valid_utf_8 : bytes -> bool ``` -------------------------------- ### Add Metaquot to Dune Preprocess Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/generating-code.html Include `ppxlib.metaquot` in your Dune stanza's `preprocess` to enable Metaquot functionality. ```dune (preprocess (pps ppxlib.metaquot)) ``` -------------------------------- ### Deriver Example with @@deriving Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/driver.html Illustrates how a deriver attribute is used to generate appended code for a type definition. The original type definition remains unmodified. ```ocaml type t = Int of int | Float of float [@@deriving yojson] let x = ... ``` ```ocaml type ty = Int of int | Float of float [@@deriving yojson] let ty_of_yojson = ... let ty_to_yojson = ... let x = ... ``` -------------------------------- ### with_file Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/In_channel/index.html Opens a file, applies a function to its input channel, and ensures the channel is closed afterward. Supports binary mode. ```APIDOC ## with_file ### Description Opens a file, applies a function to its input channel, and ensures the channel is closed afterward. Supports binary mode. ### Signature `val with_file : ?binary:bool -> string -> f:(Stdlib.in_channel -> 'a) -> 'a` ### Parameters - `binary` (bool) - Optional. If true, opens the channel in binary mode. - `string` (string) - The path to the file. - `f` (Stdlib.in_channel -> 'a) - A function that takes an input channel and returns a value of type 'a. ``` -------------------------------- ### Extension Constructor Copy Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Migrate_503_502/index.html Copies an extension constructor from Ast_503.Parsetree to Ast_502.Parsetree. ```APIDOC ## copy_extension_constructor ### Description Copies an extension constructor from OCaml 5.03 AST to OCaml 5.02 AST. ### Signature ``` val copy_extension_constructor : Ast_503.Parsetree.extension_constructor -> Ast_502.Parsetree.extension_constructor ``` ``` -------------------------------- ### pexp_for Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/Deriving/Args/index.html Represents a for loop in the OCaml AST. It takes a pattern for the loop variable, a start expression, an end expression, a direction flag, and the loop body. ```APIDOC ## pexp_for ### Description Represents a for loop in the OCaml AST. ### Signature `val pexp_for : (Astlib.Ast_502.Parsetree.pattern, 'a, 'b) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.expression, 'b, 'c) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.expression, 'c, 'd) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Asttypes.direction_flag, 'd, 'e) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.expression, 'e, 'f) Ppxlib__.Ast_pattern0.t -> (Astlib.Ast_502.Parsetree.expression, 'a, 'f) Ppxlib__.Ast_pattern0.t` ``` -------------------------------- ### Get Type Parameter Name Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Ppxlib/index.html Safely retrieve the string identifier of a type parameter. `get_type_param_name_res` returns a result, while `get_type_param_name` raises an error on failure. ```ocaml get_type_param_name_res tp ``` ```ocaml get_type_param_name tp ``` -------------------------------- ### UTF-16LE Character Handling Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Stdppx/Bytes/index.html Functions for getting and setting UTF-16 Little-Endian encoded characters within bytes sequences, and checking for valid UTF-16LE encoding. ```APIDOC ## get_utf_16le_uchar ### Description Gets a UTF-16 Little-Endian encoded Unicode character from a bytes sequence at a given byte offset. ### Parameters #### Path Parameters - **offset** (int) - The byte offset in the bytes sequence. ### Method val get_utf_16le_uchar : bytes -> int -> Stdlib.Uchar.utf_decode ## set_utf_16le_uchar ### Description Sets a UTF-16 Little-Endian encoded Unicode character in a bytes sequence at a given byte offset. ### Parameters #### Path Parameters - **offset** (int) - The byte offset in the bytes sequence. - **uchar** (Stdlib.Uchar.t) - The Unicode character to set. ### Method val set_utf_16le_uchar : bytes -> int -> Stdlib.Uchar.t -> int ## is_valid_utf_16le ### Description Checks if a bytes sequence contains valid UTF-16 Little-Endian encoded data. ### Method val is_valid_utf_16le : bytes -> bool ``` -------------------------------- ### copy_extension_constructor Source: https://ocaml-ppx.github.io/ppxlib/ppxlib/Astlib/Migrate_411_412/index.html Copies an extension constructor from Ast_411.Parsetree to Ast_412.Parsetree. ```APIDOC ## copy_extension_constructor ### Description Copies an extension constructor from Ast_411.Parsetree to Ast_412.Parsetree. ### Signature `val copy_extension_constructor : Ast_411.Parsetree.extension_constructor -> Ast_412.Parsetree.extension_constructor` ```