mirror of
https://github.com/ocaml-tracing/ocaml-trace.git
synced 2026-03-09 12:23:32 -04:00
47 lines
23 KiB
HTML
47 lines
23 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Attribute (ppxlib.Ppxlib.Attribute)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><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">Index</a> » <a href="../../index.html">ppxlib</a> » <a href="../index.html">Ppxlib</a> » Attribute</nav><header class="odoc-preamble"><h1>Module <code><span>Ppxlib.Attribute</span></code></h1><p>This module provides hygiene for attributes. The goal is to report misuses of attributes to the user as soon as possible so that no mistyped attribute get silently ignored.</p></header><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> <span>('context, 'payload) t</span></span></code></div><div class="spec-doc"><p>Type of declared attribute.</p><p>The <code>'context</code> type parameter describes where the attribute is expected and the <code>'payload</code> one what its payload should contain.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-packed"><a href="#type-packed" class="anchor"></a><code><span><span class="keyword">type</span> packed</span><span> = </span></code><ol><li id="type-packed.T" class="def variant constructor anchored"><a href="#type-packed.T" class="anchor"></a><code><span>| </span><span><span class="constructor">T</span> : <span><span>(<span class="type-var">_</span>, <span class="type-var">_</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span> <a href="#type-packed">packed</a></span></code></li></ol></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Context"><a href="#module-Context" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Context/index.html">Context</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-declare"><a href="#val-declare" class="anchor"></a><code><span><span class="keyword">val</span> declare :
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<a href="../../Astlib/Ast_502/Parsetree/index.html#type-payload">Astlib.Ast_502.Parsetree.payload</a>, <span class="type-var">'b</span>, <span class="type-var">'c</span>)</span> <a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'b</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span class="type-var">'a</span>, <span class="type-var">'c</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>declare fully_qualified_name context payload_pattern k</code> declares an attribute. <code>k</code> is used to build the value resulting from parsing the payload.</p><p>For instance if a rewriter named "foo" expect the attribute <code>@@default</code> on record field declaration with an expression as payload:</p><pre class="language-ocaml"><code> let default =
|
||
Attribute.declare "foo.default" Attribute.Context.label_declaration
|
||
Ast_pattern.(pstr (pstr_eval __ nil))
|
||
(fun x -> x)</code></pre><p><code>fully_qualified_name</code> is expected to be a dot-separated list of names. When matching, any full suffix will be accepted. So for instance an attribute declared with name "foo.bar.default" will match exactly these attribute names: "default", "bar.default" and "foo.bar.default".</p><p>Additionally it is possible to prevent a suffix to be shortened by prefixing it with '@'. So for instance an attribute declared with name "foo.@bar.default" will match exactly these attribute names: "bar.default" and "foo.bar.default".</p><p>When matching against a list of attributes on an item, if several matches are possible, the longest one is used. For instance using the attribute "foo.default" declared in the previous example, on this code it will match the <code>@foo.default 0</code> attribute:</p><pre class="language-ocaml"><code> type t = { x : int [@default 42] [@foo.default 0] }</code></pre><p>This is to allow the user to specify a <code>@default</code> attribute for all re-writers that use it but still put a specific one for one specific re-writer.</p><p>It is not allowed to declare an attribute with a name that matches a previously-defined one on the same context. For instance trying to declare the same attribute twice will fail.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-declare_with_name_loc"><a href="#val-declare_with_name_loc" class="anchor"></a><code><span><span class="keyword">val</span> declare_with_name_loc :
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<a href="../../Astlib/Ast_502/Parsetree/index.html#type-payload">Astlib.Ast_502.Parsetree.payload</a>, <span class="type-var">'b</span>, <span class="type-var">'c</span>)</span> <a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span class="label">name_loc</span>:<a href="../Location/index.html#type-t">Location.t</a> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span class="type-var">'a</span>, <span class="type-var">'c</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Same as <code>declare</code> but the callback receives the location of the name of the attribute.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-declare_with_attr_loc"><a href="#val-declare_with_attr_loc" class="anchor"></a><code><span><span class="keyword">val</span> declare_with_attr_loc :
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<a href="../../Astlib/Ast_502/Parsetree/index.html#type-payload">Astlib.Ast_502.Parsetree.payload</a>, <span class="type-var">'b</span>, <span class="type-var">'c</span>)</span> <a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span class="label">attr_loc</span>:<a href="../Location/index.html#type-t">Location.t</a> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span class="type-var">'a</span>, <span class="type-var">'c</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Same as <code>declare</code> but the callback receives the location of the attribute.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-flag"><a href="#type-flag" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a flag</span></span><span> = <span><span>(<span class="type-var">'a</span>, unit)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p>Types for attributes without payload.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-declare_flag"><a href="#val-declare_flag" class="anchor"></a><code><span><span class="keyword">val</span> declare_flag : <span>string <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-flag">flag</a></span></span></code></div><div class="spec-doc"><p>Same as <a href="#val-declare"><code>declare</code></a>, but the payload is expected to be empty. It is supposed to be used in conjunction with <a href="#val-has_flag"><code>has_flag</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-name"><a href="#val-name" class="anchor"></a><code><span><span class="keyword">val</span> name : <span><span><span>(<span class="type-var">_</span>, <span class="type-var">_</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> string</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-context"><a href="#val-context" class="anchor"></a><code><span><span class="keyword">val</span> context : <span><span><span>(<span class="type-var">'a</span>, <span class="type-var">_</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_res"><a href="#val-get_res" class="anchor"></a><code><span><span class="keyword">val</span> get_res :
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?mark_as_seen</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span class="type-var">'b</span> option</span>, <span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> <a href="../../Stdppx/NonEmptyList/index.html#type-t">Stdppx.NonEmptyList.t</a></span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span></span></code></div><div class="spec-doc"><p>Gets the associated attribute value. Marks the attribute as seen unless <code>mark_as_seen=false</code>. Returns an <code>Error</code> if the attribute is duplicated</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get"><a href="#val-get" class="anchor"></a><code><span><span class="keyword">val</span> get : <span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="optlabel">?mark_as_seen</span>:bool <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> option</span></span></code></div><div class="spec-doc"><p>See <a href="#val-get_res"><code>get_res</code></a>. Raises a located error if the attribute is duplicated</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-has_flag_res"><a href="#val-has_flag_res" class="anchor"></a><code><span><span class="keyword">val</span> has_flag_res :
|
||
<span><span><span class="type-var">'a</span> <a href="#type-flag">flag</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?mark_as_seen</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span>(bool, <span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> <a href="../../Stdppx/NonEmptyList/index.html#type-t">Stdppx.NonEmptyList.t</a></span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span></span></code></div><div class="spec-doc"><p>Answers whether the given flag is attached as an attribute. See <a href="#val-get_res"><code>get_res</code></a> for the meaning of <code>mark_as_seen</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-has_flag"><a href="#val-has_flag" class="anchor"></a><code><span><span class="keyword">val</span> has_flag : <span><span><span class="type-var">'a</span> <a href="#type-flag">flag</a></span> <span class="arrow">-></span></span> <span><span class="optlabel">?mark_as_seen</span>:bool <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>See <a href="#val-has_flag_res"><code>has_flag_res</code></a>. Raises a located error if the attribute is duplicated.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-consume_res"><a href="#val-consume_res" class="anchor"></a><code><span><span class="keyword">val</span> consume_res :
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span>)</span> option</span>, <span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> <a href="../../Stdppx/NonEmptyList/index.html#type-t">Stdppx.NonEmptyList.t</a></span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span></span></code></div><div class="spec-doc"><p><code>consume_res t x</code> returns the value associated to attribute <code>t</code> on <code>x</code> if present as well as <code>x</code> with <code>t</code> removed.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-consume"><a href="#val-consume" class="anchor"></a><code><span><span class="keyword">val</span> consume : <span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span>)</span> option</span></span></code></div><div class="spec-doc"><p>See <a href="#val-consume_res"><code>consume_res</code></a>. Raises a located exception in case of error.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-remove_seen_res"><a href="#val-remove_seen_res" class="anchor"></a><code><span><span class="keyword">val</span> remove_seen_res :
|
||
<span><span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><a href="#type-packed">packed</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span class="type-var">'a</span>, <span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> <a href="../../Stdppx/NonEmptyList/index.html#type-t">Stdppx.NonEmptyList.t</a></span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span></span></code></div><div class="spec-doc"><p><code>remove_seen x attrs</code> removes the set of attributes matched by elements of <code>attrs</code>. Only remove them if they where seen by <a href="#val-get"><code>get</code></a> or <a href="#val-consume"><code>consume</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-remove_seen"><a href="#val-remove_seen" class="anchor"></a><code><span><span class="keyword">val</span> remove_seen : <span><span><span class="type-var">'a</span> <a href="Context/index.html#type-t">Context.t</a></span> <span class="arrow">-></span></span> <span><span><a href="#type-packed">packed</a> list</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>See <a href="#val-remove_seen_res"><code>remove_seen_res</code></a>. Raises in case of error.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Floating"><a href="#module-Floating" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Floating/index.html">Floating</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-explicitly_drop"><a href="#val-explicitly_drop" class="anchor"></a><code><span><span class="keyword">val</span> explicitly_drop : <span class="xref-unresolved">Ppxlib__.Ast_traverse0.iter</span></span></code></div><div class="spec-doc"><p>Code that is voluntarily dropped by a rewriter needs to be given to this object. All attributes inside will be marked as handled.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-check_unused"><a href="#val-check_unused" class="anchor"></a><code><span><span class="keyword">val</span> check_unused : <span class="xref-unresolved">Ppxlib__.Ast_traverse0.iter</span></span></code></div><div class="spec-doc"><p>Raise if there are unused attributes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-collect_unused_attributes_errors"><a href="#val-collect_unused_attributes_errors" class="anchor"></a><code><span><span class="keyword">val</span> collect_unused_attributes_errors :
|
||
<span><span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> list</span> <span class="xref-unresolved">Ppxlib__.Ast_traverse0.fold</span></span></span></code></div><div class="spec-doc"><p>Collect all errors due to unused attributes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-collect"><a href="#val-collect" class="anchor"></a><code><span><span class="keyword">val</span> collect : <span class="xref-unresolved">Ppxlib__.Ast_traverse0.iter</span></span></code></div><div class="spec-doc"><p>Collect all attribute names. To be used in conjunction with <a href="#val-check_all_seen"><code>check_all_seen</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-collect_unseen_errors"><a href="#val-collect_unseen_errors" class="anchor"></a><code><span><span class="keyword">val</span> collect_unseen_errors : <span>unit <span class="arrow">-></span></span> <span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> list</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-check_all_seen"><a href="#val-check_all_seen" class="anchor"></a><code><span><span class="keyword">val</span> check_all_seen : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Check that all attributes collected by <a href="#val-collect_unseen_errors"><code>collect_unseen_errors</code></a> have been:</p><ul><li>matched at least once by one of: <a href="#val-get"><code>get</code></a>, <a href="#val-consume"><code>consume</code></a> or <a href="Floating/index.html#val-convert"><code>Floating.convert</code></a></li><li>seen by <code>check_unused</code> (to allow allowlisted attributed to pass through)</li></ul><p>This helps with faulty ppx rewriters that silently drop attributes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-mark_as_handled_manually"><a href="#val-mark_as_handled_manually" class="anchor"></a><code><span><span class="keyword">val</span> mark_as_handled_manually : <span><a href="../../Astlib/Ast_502/Parsetree/index.html#type-attribute">Astlib.Ast_502.Parsetree.attribute</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Mark an attribute as seen and handled. This is only to make ppx rewriters that don't use ppxlib works well with the ones that do use it.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-dropped_so_far_structure"><a href="#val-dropped_so_far_structure" class="anchor"></a><code><span><span class="keyword">val</span> dropped_so_far_structure :
|
||
<span><span><a href="../../Astlib/Ast_502/Parsetree/index.html#type-structure_item">Astlib.Ast_502.Parsetree.structure_item</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span>string <a href="../Loc/index.html#type-t">Loc.t</a></span> list</span></span></code></div><div class="spec-doc"><p>Return the list of attributes that have been dropped so far: attributes that haven't been marked and are not present in the given AST. This is used to debug extensions that drop attributes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-dropped_so_far_signature"><a href="#val-dropped_so_far_signature" class="anchor"></a><code><span><span class="keyword">val</span> dropped_so_far_signature :
|
||
<span><span><a href="../../Astlib/Ast_502/Parsetree/index.html#type-signature_item">Astlib.Ast_502.Parsetree.signature_item</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span>string <a href="../Loc/index.html#type-t">Loc.t</a></span> list</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-reset_checks"><a href="#val-reset_checks" class="anchor"></a><code><span><span class="keyword">val</span> reset_checks : <span>unit <span class="arrow">-></span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pattern"><a href="#val-pattern" class="anchor"></a><code><span><span class="keyword">val</span> pattern :
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'c</span>, <span class="type-var">'d</span>)</span> <a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span>(<span class="type-var">'a</span>, <span><span><span class="type-var">'b</span> option</span> <span class="arrow">-></span></span> <span class="type-var">'c</span>, <span class="type-var">'d</span>)</span> <a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pattern_res"><a href="#val-pattern_res" class="anchor"></a><code><span><span class="keyword">val</span> pattern_res :
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span class="type-var">'a</span>, <span class="type-var">'c</span>, <span class="type-var">'d</span>)</span> <a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span> <span class="arrow">-></span></span>
|
||
<span><span>(<span class="type-var">'a</span>, <span><span><span class="type-var">'b</span> option</span> <span class="arrow">-></span></span> <span class="type-var">'c</span>, <span><span>(<span class="type-var">'d</span>, <span><a href="../Location/Error/index.html#type-t">Location.Error.t</a> <a href="../../Stdppx/NonEmptyList/index.html#type-t">Stdppx.NonEmptyList.t</a></span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span>)</span>
|
||
<a href="../Ast_pattern/index.html#type-t">Ast_pattern.t</a></span></span></code></div></div></div></body></html>
|