mirror of
https://github.com/ocaml-tracing/ocaml-trace.git
synced 2026-03-09 12:23:32 -04:00
78 lines
No EOL
22 KiB
HTML
78 lines
No EOL
22 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>generating-code (ppxlib.generating-code)</title><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.2.2"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">ppxlib</a> » generating-code</nav><header class="odoc-preamble"><p> <div style="display: flex; justify-content:space-between"><div><a href="writing-ppxs.html">< Writing PPXs</a> </div><div><a href="matching-code.html">Destructing AST nodes ></a> </div></div></p><h1 id="generating-ast-nodes"><a href="#generating-ast-nodes" class="anchor"></a>Generating AST Nodes</h1><p>The rewriter's core is a function that outputs code in the form of an AST. However, there are some issues with generating AST values when using the constructors directly:</p><ul><li>The type is <a href="Astlib/Ast_500/Parsetree/index.html">pretty verbose</a>, with many fields rarely used.</li><li>The AST type might change at a version bump. In this case, the types used in the PPX would become incompatible with the types of the new OCaml version.</li></ul><p>The second point is important: since <code>ppxlib</code> <a href="driver.html#compat_mult_ver">translates</a> the AST to the newest OCaml AST available before rewriting, your PPX would not only become incompatible with the new OCaml version, but also with all <code>ppxlib</code> versions released after the new AST type is introduced.</p><p>For this reason, <code>ppxlib</code> provides abstractions over the OCaml AST, with a focus on usability and stability.</p></header><nav class="odoc-toc"><ul><li><a href="#the-different-options">The Different Options</a></li><li><a href="#ast_builder">The <code>AST_builder</code> Module</a><ul><li><a href="#general-presentation">General Presentation</a><ul><li><a href="#low-level-builders">Low-Level Builders</a></li><li><a href="#high-level-builders">High-Level Builders</a></li></ul></li><li><a href="#dealing-with-locations">Dealing With Locations</a></li><li><a href="#compatibility">Compatibility</a></li></ul></li><li><a href="#metaquot"><code>Metaquot</code> Metaprogramming</a><ul><li><a href="#general-presentation_2">General Presentation</a></li><li><a href="#usage">Usage</a></li><li><a href="#antiquotations">Anti-Quotations</a></li></ul></li></ul></nav><div class="odoc-content"><h2 id="the-different-options"><a href="#the-different-options" class="anchor"></a>The Different Options</h2><p>The two main options are:</p><ul><li><a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a>,</li><li><a href="Ppxlib_metaquot/index.html"><code>Ppxlib_metaquot</code></a>.</li></ul><p><a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> provides an API to generate AST nodes for the latest OCaml version in a backward-compatible way. <a href="Ppxlib_metaquot/index.html"><code>Ppxlib_metaquot</code></a> is different: it is a PPX that lets you generate OCaml AST nodes by writing OCaml code, using quotations and anti-quotations.</p><p>Using <a href="Ppxlib_metaquot/index.html"><code>Ppxlib_metaquot</code></a> requires less knowledge of the OCaml AST than <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> as it only uses natural OCaml syntax; however, it's more restrictive than `Ast_builder` for two reasons: first, it's less flexible, since on its own it lacks the ability to generate nodes dynamically from other kind of data: e.g. it's not possible to build an expression containing a string, given the string as input. Second, it's less general because it only allows users to generate few different nodes such as structure items, expressions, patterns, etc., but it is not possible to generate a value of type <a href="Astlib/Ast_500/Parsetree/index.html#type-row_field_desc"><code>row_field_desc</code></a>! A typical workflow is to use `metaquot` for the constant skeleton of the node, and to use the `metaquot` anti-quotation workflow (see below) together with `Ast_builder` to fill in the dynamic parts.</p><p>Note: `Ppxlib` also re-exports the OCaml compiler API `Ast_helper` for historic reasons. It might get deprecated at some point, though. Please, use `Ast_builder` instead. manipulate the AST. This module is in <code>ppxlib</code> for compatiblity reasons and it is recommended to use <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> instead.</p><h2 id="ast_builder"><a href="#ast_builder" class="anchor"></a>The <code>AST_builder</code> Module</h2><h3 id="general-presentation"><a href="#general-presentation" class="anchor"></a>General Presentation</h3><p>The <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> module provides several kinds of functions to generate AST nodes. The first kind are ones whose name matches closely the <a href="Astlib/Ast_500/Parsetree/index.html"><code>Parsetree</code></a> type names. equivalents, but there are also "higher level" wrappers around those basic blocks for common patterns such as creating an integer or string constant.</p><h4 id="low-level-builders"><a href="#low-level-builders" class="anchor"></a>Low-Level Builders</h4><p>The function names match the <a href="Astlib/Ast_500/Parsetree/index.html"><code>Parsetree</code></a> names closely, which makes it easy to build AST fragments by just knowing the <a href="Astlib/Ast_500/Parsetree/index.html"><code>Parsetree</code></a>.</p><p>For types wrapped in a record's <code>_desc</code> field, helpers are generated for each constructor that generates the record wrapper, e.g., for the type <a href="Astlib/Ast_500/Parsetree/index.html#type-expression"><code>Parsetree.expression</code></a>:</p><pre class="language-ocaml"><code>type expression =
|
||
{ pexp_desc : expression_desc
|
||
; pexp_loc : Location.t
|
||
; pexp_attributes : attributes
|
||
}
|
||
and expression_desc =
|
||
| Pexp_ident of Longident.t loc
|
||
| Pexp_constant of constant
|
||
| Pexp_let of rec_flag * value_binding list * expression
|
||
...</code></pre><p>The following helpers are created:</p><pre class="language-ocaml"><code>val pexp_ident : loc:Location.t -> Longident.t loc -> expression
|
||
val pexp_constant : loc:Location.t -> constant -> expression
|
||
val pexp_let : loc:Location.t -> rec_flag -> value_binding list -> expression -> expression
|
||
...</code></pre><p>For other record types, such as <code>type_declaration</code>, we have the following helper:</p><pre class="language-ocaml"><code>type type_declaration =
|
||
{ ptype_name : string Located.t
|
||
; ptype_params : (core_type * variance) list
|
||
; ptype_cstrs : (core_type * core_type * Location.t) list
|
||
; ptype_kind : type_kind
|
||
; ptype_private : private_flag
|
||
; ptype_manifest : core_type option
|
||
; ptype_attributes : attributes
|
||
; ptype_loc : Location.t
|
||
}
|
||
|
||
val type_declaration
|
||
: loc : Location.t
|
||
-> name : string Located.t
|
||
-> params : (core_type * variance) list
|
||
-> cstrs : (core_type * core_type * Location.t) list
|
||
-> kind : type_kind
|
||
-> private : private_flag
|
||
-> manifest : core_type option
|
||
-> type_declaration</code></pre><p>Attributes are always set to the empty list. If you want to set them, you have to override the field with the <code>{ e with pexp_attributes = ... }</code> notation.</p><h4 id="high-level-builders"><a href="#high-level-builders" class="anchor"></a>High-Level Builders</h4><p>Those functions are just wrappers on the low-level functions for simplifying the most common use. For instance, to simply create a <code>1</code> integer constant with the low-level building block, it would look like:</p><pre class="language-ocaml"><code>Ast_builder.Default.pexp_constant ~loc (Parsetree.Pconst_integer ("1", None))</code></pre><p>This seems a lot for such a simple node. So, in addition to the low-level building blocks, <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> provides higher level-building blocks, such as <a href="Ppxlib/Ast_builder/Default/index.html#val-eint"><code>Ast_builder.Default.eint</code></a>, to create integer constants:</p><pre class="language-ocaml"><code>Ast_builder.Default.eint ~loc 1</code></pre><p>Those functions also follow a pattern in their name to make them easier to use. Functions that generate an expression start with an <code>e</code>, followed by what they build, such as <code>eint</code>, <code>echar</code>, <code>estring</code>, <code>eapply</code>, <code>elist</code>, etc. Similarly, names that start with a <code>p</code> define a pattern, such as <code>pstring</code>, <code>pconstruct</code>, <code>punit</code>, etc.</p><h3 id="dealing-with-locations"><a href="#dealing-with-locations" class="anchor"></a>Dealing With Locations</h3><p>As explained in the <a href="good-practices.html#resp_loc">dedicated section</a>, it is crucial to correctly deal with locations. For this, <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> can be used in several ways, depending on the context:</p><p><a href="Ppxlib/Ast_builder/Default/index.html"><code>Ast_builder.Default</code></a> contains functions which take the location as a named argument. This is the strongly recommended workflow and lets you control locations in a fine-grained way.</p><p>If you have a concrete reason to specify the location once and for all, and always use this specific one later in AST constructions, you can use the <a href="Ppxlib/Ast_builder/Make/index.html"><code>Ast_builder.Make</code></a> functor or the <a href="Ppxlib/Ast_builder/index.html#val-make"><code>Ast_builder.make</code></a> function (outputing a first order module). Notice that this is quite a rare use case.</p><h3 id="compatibility"><a href="#compatibility" class="anchor"></a>Compatibility</h3><p>In order to stay as compatible as possible when a new option appears in the AST, <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> always integrates the new option in a retro-compatible way (this is the case since the AST bump from 4.13 to 4.14). So, the signature of each function won't change, and <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> will choose a retrocompatible way of generating an updated type’s AST node.</p><p>However, sometimes you might want to use a feature that was introduced recently in OCaml and is not integrated in <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a>. For instance, OCaml 4.14 introduced the possibility to explicitly introduce type variables in a constructor declaration. This modified the AST type, and for backwards compatibility, <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> did not modify the signature of the function. It is thus impossible to generate code using this new feature via the `Ast_module` directly.</p><p>In the case you need to access a new feature, you can use the <code>Latest</code> submodule (e.g., <a href="Ppxlib/Ast_builder/Default/Latest/index.html"><code>Ast_builder.Default.Latest</code></a> when specifying the locations). This module includes new functions, letting you control all features introduced, at the cost of potentially breaking changes when a new feature modifies the function in use.</p><p>If a feature that was introduced in some recent version of OCaml is essential for your PPX to work, it might imply that you need to restrict the OCaml version on your opam dependencies. <a href="driver.html#compat_mult_ver">Remember</a> that <code>ppxlib</code> will rewrite using the latest <code>Parsetree</code> version, <em>but</em> it will then migrate the <code>Parsetree</code> back to the OCaml version of the switch, possibly losing the information given by the new feature.</p><h2 id="metaquot"><a href="#metaquot" class="anchor"></a><code>Metaquot</code> Metaprogramming</h2><h3 id="general-presentation_2"><a href="#general-presentation_2" class="anchor"></a>General Presentation</h3><p>As you have seen, defining code with <a href="Ppxlib/Ast_builder/index.html"><code>Ast_builder</code></a> does not feel perfectly natural. Some knowledge of the <code>Parsetree</code> types is needed. Yet, every part of a program we write corresponds to a specific AST node, so there is no need for AST generation to be more difficult than that.</p><p><code>Metaquot</code> is a very useful PPX that allows users to define values of a <code>Parsetree</code> type by writing natural code, using the quotations and antiquotations mechanism of metaprogramming.</p><p>Simplifying a bit, <a href="Ppxlib_metaquot/index.html"><code>Metaquot</code></a> rewrites an expression extension point directly with its payload. Since the payload was parsed by the OCaml parser to a <code>Parsetree</code> type's value, this rewriting turns naturally written code into AST values.</p><h3 id="usage"><a href="#usage" class="anchor"></a>Usage</h3><p>First, in order to use <code>Metaquot</code>, add it in your <code>preprocess</code> Dune stanza:</p><pre class="language-ocaml"><code>(preprocess (pps ppxlib.metaquot))</code></pre><p>Using Metaquot to generate code is simple: any <code>Metaquot</code> extension node in an expression context will be rewritten into the <code>Parsetree</code> value that lies in its payload. Notice that you'll need the <code>Ppxlib</code> opened, and a <code>loc</code> value of type <a href="Ppxlib/Location/index.html#type-t">Location.t</a> in scope when using metaquot. That location will be attached to the <code>Parsetree</code> nodes your metaquot invokation produces. Getting the location right is extremely important for error messages.</p><p>However, the <a href="Astlib/Ast_500/Parsetree/index.html#type-payload"><code>Parsetree.payload</code></a> of an extension node can only take few forms: a <a href="Astlib/Ast_500/Parsetree/index.html#type-structure"><code>structure</code></a>, a <a href="Astlib/Ast_500/Parsetree/index.html#type-signature"><code>signature</code></a>, a <a href="Astlib/Ast_500/Parsetree/index.html#type-core_type"><code>core type</code></a>, or a <a href="Astlib/Ast_500/Parsetree/index.html#type-pattern"><code>pattern</code></a>. We might want to generate other kind of nodes, such as <a href="Astlib/Ast_500/Parsetree/index.html#type-expression"><code>expressions</code></a> or <a href="Astlib/Ast_500/Parsetree/index.html#type-structure_item"><code>structure items</code></a>, for instance. <a href="Ppxlib_metaquot/index.html"><code>Ppxlib_metaquot</code></a> provides different extension nodes for this:</p><ul><li><p>The <code>expr</code> extension node to generate <a href="Astlib/Ast_500/Parsetree/index.html#type-expression"><code>expressions</code></a>:</p><pre class="language-ocaml"><code>let e = [%expr 1 + 1]</code></pre></li><li><p>The <code>pat</code> extension node to generate <a href="Astlib/Ast_500/Parsetree/index.html#type-pattern"><code>patterns</code></a>:</p><pre class="language-ocaml"><code>let p = [%pat? ("", _)]</code></pre></li><li><p>The <code>type</code> extension node to generate <a href="Astlib/Ast_500/Parsetree/index.html#type-core_type"><code>core types</code></a>:</p><pre class="language-ocaml"><code>let t = [%type: int -> string]</code></pre></li><li><p>The <code>stri</code> extension node to generate <a href="Astlib/Ast_500/Parsetree/index.html#type-structure_item"><code>structure_item</code></a>, with its <code>sigi</code> counterpart for <a href="Astlib/Ast_500/Parsetree/index.html#type-signature_item"><code>signature_item</code></a>::</p><pre class="language-ocaml"><code>let stri = [%stri let a = 1]
|
||
let sigi = [%sigi: val i : int]</code></pre></li><li><p>The <code>str</code> and <code>sig</code> extension nodes to respectively generate <a href="Astlib/Ast_500/Parsetree/index.html#type-structure"><code>structure</code></a> and <a href="Astlib/Ast_500/Parsetree/index.html#type-signature"><code>signature</code></a>.</p><pre class="language-ocaml"><code>let str =
|
||
[%str
|
||
let x = 5
|
||
let y = 6.3]
|
||
|
||
let sig_ =
|
||
[%sig:
|
||
val x : int
|
||
val y : float]</code></pre></li></ul><p>Note the replacement work when the extension node is an "expression" extension node: Indeed, the <code>payload</code> is a <em>value</em> (of <code>Parsetree</code> type) that would not fit elsewhere in the AST. So, <code>let x : [%str "incoherent"]</code> would not be rewritten by <code>metaquot</code>. (Actually, it also rewrites "pattern" extension nodes, as you'll see in the chapter on <a href="matching-code.html#metaquot">matching AST nodes</a>.)</p><p>Also note the <code>:</code> and <code>?</code> in the <code>sigi</code>, <code>type</code>, and <code>pat</code> cases: they are needed for the payload to be parsed as the right kind of node.</p><p>Consider now the extension node <code>[%expr 1 + 1]</code> in an expression context. <code>Metaquot</code> will actually expand it into the following code:</p><pre class="language-ocaml"><code>{
|
||
pexp_desc =
|
||
(Pexp_apply
|
||
({
|
||
pexp_desc = (Pexp_ident { txt = (Lident "+"); loc });
|
||
pexp_loc = loc;
|
||
pexp_attributes = []
|
||
},
|
||
[(Nolabel,
|
||
{
|
||
pexp_desc = (Pexp_constant (Pconst_integer ("1", None)));
|
||
pexp_loc = loc;
|
||
pexp_attributes = []
|
||
});
|
||
(Nolabel,
|
||
{
|
||
pexp_desc = (Pexp_constant (Pconst_integer ("1", None)));
|
||
pexp_loc = loc;
|
||
pexp_attributes = []
|
||
})]));
|
||
pexp_loc = loc;
|
||
pexp_attributes = []
|
||
}</code></pre><p>Looking at the example, you might notice two things:</p><ul><li>The AST types are used without a full path to the module.</li><li>There is a free variable named <code>loc</code> and of type <code>Location.t</code> in the code.</li></ul><p>So for this to compile, you need both to open <code>ppxlib</code> and to have a <code>loc : Location.t</code> variable in scope. The produced AST node value, and every other node within it, will be located in this <code>loc</code>. You should therefore make sure that <code>loc</code> is the location you want for your generated code when using <code>metaquot</code>.</p><h3 id="antiquotations"><a href="#antiquotations" class="anchor"></a>Anti-Quotations</h3><p>Using these extensions alone, you can only produce constant/static AST nodes. <code>metaquot</code> has a solution for that: anti-quotation. You can use anti-quotation to insert any expression representing an AST node. That way, you can include dynamically generated nodes inside a <code>metaquot</code> expression extension point.</p><p>Consider the following example:</p><pre class="language-ocaml"><code>let with_suffix_expr ~loc s =
|
||
let dynamic_node = Ast_builder.Default.estring ~loc s in
|
||
[%expr [%e dynamic_node] ^ "some_fixed_suffix"]</code></pre><p>The <code>with_suffix_expr</code> function will create an <code>expression</code> which represents the concatenation of the <code>s</code> argument and the fixed suffix, i.e., <code>with_suffix_expr "some_dynamic_stem"</code> is equivalent to <code>[%expr "some_dynamic_stem" ^ "some_fixed_suffix"]</code>.</p><p>The syntax for anti-quotation depends on the type of the node you wish to insert (which must also correspond to the context of the anti-quotation extension node):</p><ul><li><p><code>e</code> is the extension point used to anti-quote values of type <a href="Astlib/Ast_500/Parsetree/index.html#type-expression"><code>expression</code></a>:</p><pre class="language-ocaml"><code>let f some_expr_node = [%expr 1 + [%e some_expr_node]]</code></pre></li><li><p><code>p</code> is the extension point used to anti-quote values of type <a href="Astlib/Ast_500/Parsetree/index.html#type-pattern"><code>pattern</code></a>:</p><pre class="language-ocaml"><code>let f some_pat_node = [%pat? (1, [%p some_pat_node])]</code></pre></li><li><p><code>t</code> is the extension point used to anti-quote values of type <a href="Astlib/Ast_500/Parsetree/index.html#type-core_type"><code>core_type</code></a>:</p><pre class="language-ocaml"><code>let f some_core_type_node [%type: int -> [%t some_core_type_node]]</code></pre></li><li><p><code>m</code> is the extension point used to anti-quote values of type <a href="Astlib/Ast_500/Parsetree/index.html#type-module_expr"><code>module_expr</code></a> or <a href="Astlib/Ast_500/Parsetree/index.html#type-module_type"><code>module_type</code></a>:</p><pre class="language-ocaml"><code>let f some_module_expr_node = [%expr let module M = [%m some_module_expr_node] in M.x]
|
||
let f some_module_type_node = [%sigi: module M : [%m some_module_type_node]]</code></pre></li><li><p><code>i</code> is the extension point used to anti-quote values of type <a href="Astlib/Ast_500/Parsetree/index.html#type-structure_item"><code>structure_item</code></a> or <a href="Astlib/Ast_500/Parsetree/index.html#type-signature_item"><code>signature_item</code></a>. Note that the syntax for structure/signature item extension nodes uses two <code>%%</code>:</p><pre class="language-ocaml"><code>let f some_structure_item_node =
|
||
[%str
|
||
let a = 1
|
||
|
||
[%%i some_structure_item_node]]
|
||
|
||
let f some_signature_item_node =
|
||
[%sig:
|
||
val a : int
|
||
|
||
[%%i some_signature_item_node]]</code></pre></li></ul><p>If an anti-quote extension node is in the wrong context, it won't be rewritten by <a href="Ppxlib_metaquot/index.html"><code>Metaquot</code></a>. For instance, in <code>[%expr match [] with [%e some_value] -> 1]</code> the anti-quote extension node for expressions is put in a pattern context, and it won't be rewritten.</p><p>On the contrary, you should use anti-quotes whose kind (<code>[%e ...]</code>, <code>[%p ...]</code>) match the context. For example, you should write:</p><pre class="language-ocaml"><code>let let_generator pat type_ expr =
|
||
[%stri let [%p pat] : [%t type_] = [%e expr]] ;;</code></pre><p>Finally, remember that we are inserting values, so we never use patterns in the payloads of anti-quotations. Those will be used for <a href="matching-code.html#antiquotations">matching</a>.</p><p> <div style="display: flex; justify-content:space-between"><div><a href="writing-ppxs.html">< Writing PPXs</a> </div><div><a href="matching-code.html">Destructing AST nodes ></a> </div></div></p></div></body></html> |