mirror of
https://github.com/c-cube/tiny_httpd.git
synced 2026-01-21 16:56:40 -05:00
103 lines
22 KiB
HTML
103 lines
22 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Gprinttyp (ocaml.Gprinttyp)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.4"/><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">ocaml</a> » Gprinttyp</nav><header class="odoc-preamble"><h1>Module <code><span>Gprinttyp</span></code></h1><p>This module provides function for printing type expressions as digraph using graphviz format. This is mostly aimed at providing a better representation of type expressions during debugging session.</p></header><nav class="odoc-toc"><ul><li><a href="#digraph-construction-and-printing">Digraph construction and printing</a></li><li><a href="#debugging-helper-functions">Debugging helper functions</a><ul><li><a href="#generic-print-debugging-function">Generic print debugging function</a></li><li><a href="#node-tracking-functions">Node tracking functions</a></li></ul></li></ul></nav><div class="odoc-content"><p>A type node is printed as</p><pre class="language-ocaml"><code>.------------.
|
||
| <desc> id |---->
|
||
| |--->
|
||
.------------.</code></pre><p>where the description part might be:</p><ul><li>a path: <code>list/8!</code></li><li>a type variable: <code>'name</code>, <code>α</code>, <code>β</code>, <code>γ</code></li><li><code>*</code> for tuples</li><li><code>→</code> for arrows type</li><li>an universal type variable: <code>[β]∀</code>, <code>'name ∀</code>, ...</li><li><code>[mod X with ...]</code> for a first class module</li></ul><ul><li><code>∀</code> for a universal type binder</li></ul><p>The more complex encoding for polymorphic variants and object types uses nodes as head of the subgraph representing those types</p><ul><li><code>[obj...]</code> for the head of an object subgraph</li><li><code>[Nil]</code> for the end of an object subgraph</li><li><code>[Row...]</code> for the head of a polymorphic variant subgraph</li></ul><ul><li><code>[Subst]</code> for a temporary substitution node</li></ul><p>Then each nodes is relied by arrows to any of its children types.</p><ul><li>Type variables, universal type variables, <code>Nil</code>, and <code>Subst</code> nodes don't have children.</li></ul><ul><li><p>For tuples, the children types are the elements of the tuple. For instance, <code>int * float</code> is represented as</p><pre class="language-ocaml"><code>.------. 0 .-------.
|
||
| * 1 |-------->| int! 2|
|
||
.------. .-------.
|
||
|
|
||
| 1
|
||
v
|
||
.----------.
|
||
| float! 3 |
|
||
.----------.</code></pre></li></ul><ul><li><p>For arrows, the children types are the type of the argument and the result type. For instance, for <code>int -> float</code>:</p><pre class="language-ocaml"><code>.------. 0 .-------.
|
||
| → 4 |-------->| int! 2|
|
||
.------. .-------.
|
||
|
|
||
| 1
|
||
v
|
||
.----------.
|
||
| float! 3 |
|
||
.----------.</code></pre></li></ul><ul><li>For type constructor, like list the main children nodes are the argument types. For instance, <code>(int,float) result</code> is represented as:</li></ul><pre class="language-ocaml"><code>.-------------. 0 .-------.
|
||
| Result.t 5 |-------->| int! 2|
|
||
.-------------. .-------.
|
||
|
|
||
| 1
|
||
v
|
||
.----------.
|
||
| float! 3 |
|
||
.----------.</code></pre><p>Moreover, type abbreviations might be linked to the expanded nodes. If I define: <code>type 'a pair = 'a * 'a</code>, a type expression <code>int pair</code> might correspond to the nodes:</p><pre class="language-ocaml"><code>.--------. 0 .--------.
|
||
| pair 6 |------> | int! 2 |
|
||
.--------. .--------.
|
||
┆ ^
|
||
┆ expand |
|
||
┆ |
|
||
.------. 0 + 1 |
|
||
| * 7 |------>-------.
|
||
.------.</code></pre><ul><li><p>Universal type binders have two kind of children: bound variables, and the main body. For instance, <code>'a. 'a -> 'a</code> is represented as</p><pre class="language-ocaml"><code>.------. bind .-------.
|
||
| ∀ 8 |----------> | 𝛼 10 |
|
||
.------. .------.
|
||
| ^
|
||
| |
|
||
v |
|
||
.------. 0 + 1 |
|
||
| → 9 |------>-------.
|
||
.------.</code></pre></li></ul><ul><li><code>[Subst]</code> node are children are the type graph guarded by the substitution node, and an eventual link to the parent row variable.</li></ul><ul><li><p>The children of first-class modules are the type expressions that may appear in the right hand side of constraints. For instance, <code>module M with type t = 'a and type u = 'b</code> is represented as</p><pre class="language-ocaml"><code>.----------------------. 0 .-----.
|
||
| [mod M with t, u] 11 |-------->| 𝛼 12|
|
||
.----------------------. .-----
|
||
|
|
||
| 1
|
||
v
|
||
.------.
|
||
| 𝛽 13 |
|
||
.------.</code></pre></li></ul><ul><li>The children of <code>obj</code> (resp. <code>row</code>) are the methods (resp. constructor) of the object type (resp. polymorphic variant). Each method is then linked to its type. To make them easier to read they are grouped inside graphviz cluster. For instance, <code><a:int; m:'self; ..> as 'self</code> will be represented as:</li></ul><pre class="language-ocaml"><code>.----------------.
|
||
| .----------. |
|
||
| | [obj] 14 |<------<-----<-----.
|
||
| .----------. | |
|
||
| ┆ | |
|
||
| .-------------. | .------. | .-------.
|
||
| | a public 15 |----->| ∀ 18 |----->| int! 2 |
|
||
| .-------------. | .------. | .-------.
|
||
| ┆ | |
|
||
| .-------------. | .------. |
|
||
| | m public 16 |-----| ∀ 19 |>--|
|
||
| .------------. | .------.
|
||
| ┆ |
|
||
| ┆ row var |
|
||
| ┆ |
|
||
| .-------. |
|
||
| | '_ 17 | |
|
||
| .-------. |
|
||
.-----------------.</code></pre><div class="odoc-spec"><div class="spec type anchored" id="type-digraph"><a href="#type-digraph" class="anchor"></a><code><span><span class="keyword">type</span> digraph</span></code></div><div class="spec-doc"><p>Digraph with nodes, edges, hyperedges and subgraphes</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-params"><a href="#type-params" class="anchor"></a><code><span><span class="keyword">type</span> params</span></code></div><div class="spec-doc"><p>Various possible choices on how to represent types, see the <a href="#val-params"><code>params</code></a> functions for more detail.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-element"><a href="#type-element" class="anchor"></a><code><span><span class="keyword">type</span> element</span></code></div><div class="spec-doc"><p>Graph element, see the <a href="#val-node"><code>node</code></a>, <a href="#val-edge"><code>edge</code></a> and <a href="#val-hyperedge"><code>hyperedge</code></a> function</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-decoration"><a href="#type-decoration" class="anchor"></a><code><span><span class="keyword">type</span> decoration</span></code></div><div class="spec-doc"><p>Visual decoration on graph elements, see the <a href="Decoration/index.html"><code>Decoration</code></a> module.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-types"><a href="#val-types" class="anchor"></a><code><span><span class="keyword">val</span> types :
|
||
<span><span class="label">title</span>:string <span class="arrow">-></span></span>
|
||
<span><a href="#type-params">params</a> <span class="arrow">-></span></span>
|
||
<span><span><span>(<a href="#type-decoration">decoration</a> * <a href="../Types/index.html#type-type_expr">Types.type_expr</a>)</span> list</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p>Print a graph to the file <code>asprintf "%s/%04d-%s-%a.dot"
|
||
dump_dir
|
||
session_unique_id
|
||
title
|
||
pp_context context
|
||
</code></p><p>If the <code>dump_dir</code> flag is not set, the local directory is used. See the <a href="#type-context"><code>context</code></a> type on how and why to setup the context.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nodes"><a href="#val-nodes" class="anchor"></a><code><span><span class="keyword">val</span> nodes : <span><span class="label">title</span>:string <span class="arrow">-></span></span> <span><a href="#type-params">params</a> <span class="arrow">-></span></span> <span><span><span>(<a href="#type-decoration">decoration</a> * <a href="#type-element">element</a>)</span> list</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Full version of <a href="#val-types"><code>types</code></a> that allow to print any kind of graph element</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-params"><a href="#val-params" class="anchor"></a><code><span><span class="keyword">val</span> params :
|
||
<span><span class="optlabel">?elide_links</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?expansion_as_hyperedge</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?short_ids</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?colorize</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?follow_expansions</span>:bool <span class="arrow">-></span></span>
|
||
<span>unit <span class="arrow">-></span></span>
|
||
<a href="#type-params">params</a></span></code></div><div class="spec-doc"><p>Choice of details for printing type graphes:</p><ul><li>if <code>elide_links</code> is <code>true</code> link nodes are not displayed (default:<code>true</code>)</li><li>with <code>expansion_as_hyperedge</code>, memoized constructor expansion are displayed as a hyperedge between the node storing the memoized expansion, the expanded node and the expansion (default:<code>false</code>).</li><li>with <code>short_ids</code>, we use an independent counter for node ids, in order to have shorter ids for small digraphs (default:<code>true</code>).</li><li>with <code>colorize</code> nodes are colorized according to their typechecker ids (default:<code>true</code>).</li><li>with <code>follow_expansions</code>, we add memoized type constructor expansions to the digraph (default:<code>true</code>).</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-update_params"><a href="#val-update_params" class="anchor"></a><code><span><span class="keyword">val</span> update_params :
|
||
<span><span class="optlabel">?elide_links</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?expansion_as_hyperedge</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?short_ids</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?colorize</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?follow_expansions</span>:bool <span class="arrow">-></span></span>
|
||
<span><a href="#type-params">params</a> <span class="arrow">-></span></span>
|
||
<a href="#type-params">params</a></span></code></div><div class="spec-doc"><p>Update an existing <code>params</code> with new values.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-node"><a href="#val-node" class="anchor"></a><code><span><span class="keyword">val</span> node : <span><a href="../Types/index.html#type-type_expr">Types.type_expr</a> <span class="arrow">-></span></span> <a href="#type-element">element</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-edge"><a href="#val-edge" class="anchor"></a><code><span><span class="keyword">val</span> edge : <span><a href="../Types/index.html#type-type_expr">Types.type_expr</a> <span class="arrow">-></span></span> <span><a href="../Types/index.html#type-type_expr">Types.type_expr</a> <span class="arrow">-></span></span> <a href="#type-element">element</a></span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-dir"><a href="#type-dir" class="anchor"></a><code><span><span class="keyword">type</span> dir</span><span> = </span></code><ol><li id="type-dir.Toward" class="def variant constructor anchored"><a href="#type-dir.Toward" class="anchor"></a><code><span>| </span><span><span class="constructor">Toward</span></span></code></li><li id="type-dir.From" class="def variant constructor anchored"><a href="#type-dir.From" class="anchor"></a><code><span>| </span><span><span class="constructor">From</span></span></code></li></ol></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-hyperedge"><a href="#val-hyperedge" class="anchor"></a><code><span><span class="keyword">val</span> hyperedge : <span><span><span>(<a href="#type-dir">dir</a> * <a href="#type-decoration">decoration</a> * <a href="../Types/index.html#type-type_expr">Types.type_expr</a>)</span> list</span> <span class="arrow">-></span></span> <a href="#type-element">element</a></span></code></div><div class="spec-doc"><p>Edges between more than two elements.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Decoration"><a href="#module-Decoration" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Decoration/index.html">Decoration</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h2 id="digraph-construction-and-printing"><a href="#digraph-construction-and-printing" class="anchor"></a>Digraph construction and printing</h2><div class="odoc-spec"><div class="spec value anchored" id="val-make"><a href="#val-make" class="anchor"></a><code><span><span class="keyword">val</span> make : <span><a href="#type-params">params</a> <span class="arrow">-></span></span> <span><span><span>(<a href="#type-decoration">decoration</a> * <a href="#type-element">element</a>)</span> list</span> <span class="arrow">-></span></span> <a href="#type-digraph">digraph</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-add"><a href="#val-add" class="anchor"></a><code><span><span class="keyword">val</span> add : <span><a href="#type-params">params</a> <span class="arrow">-></span></span> <span><span><span>(<a href="#type-decoration">decoration</a> * <a href="#type-element">element</a>)</span> list</span> <span class="arrow">-></span></span> <span><a href="#type-digraph">digraph</a> <span class="arrow">-></span></span> <a href="#type-digraph">digraph</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-add_subgraph"><a href="#val-add_subgraph" class="anchor"></a><code><span><span class="keyword">val</span> add_subgraph :
|
||
<span><a href="#type-params">params</a> <span class="arrow">-></span></span>
|
||
<span><a href="#type-decoration">decoration</a> <span class="arrow">-></span></span>
|
||
<span><span><span>(<a href="#type-decoration">decoration</a> * <a href="#type-element">element</a>)</span> list</span> <span class="arrow">-></span></span>
|
||
<span><a href="#type-digraph">digraph</a> <span class="arrow">-></span></span>
|
||
<a href="#type-digraph">digraph</a></span></code></div><div class="spec-doc"><p>add a subgraph to a digraph, only fresh nodes are added to the subgraph</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-group_nodes"><a href="#val-group_nodes" class="anchor"></a><code><span><span class="keyword">val</span> group_nodes : <span><span>(<a href="#type-decoration">decoration</a> * <a href="#type-digraph">digraph</a>)</span> <span class="arrow">-></span></span> <span><a href="#type-digraph">digraph</a> <span class="arrow">-></span></span> <a href="#type-digraph">digraph</a></span></code></div><div class="spec-doc"><p>groups existing nodes inside a subgraph</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><a href="#type-digraph">digraph</a> <span class="arrow">-></span></span> unit</span></code></div></div><h2 id="debugging-helper-functions"><a href="#debugging-helper-functions" class="anchor"></a>Debugging helper functions</h2><h3 id="generic-print-debugging-function"><a href="#generic-print-debugging-function" class="anchor"></a>Generic print debugging function</h3><div class="odoc-spec"><div class="spec value anchored" id="val-debug_on"><a href="#val-debug_on" class="anchor"></a><code><span><span class="keyword">val</span> debug_on : <span><span>(<span>unit <span class="arrow">-></span></span> bool)</span> <a href="../Stdlib/index.html#type-ref">ref</a></span></span></code></div><div class="spec-doc"><p>Conditional graph printing</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-debug_off"><a href="#val-debug_off" class="anchor"></a><code><span><span class="keyword">val</span> debug_off : <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>debug_off f</code> switches off debugging before running <code>f</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-debug"><a href="#val-debug" class="anchor"></a><code><span><span class="keyword">val</span> debug : <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>debug f</code> runs <code>f</code> when <code>!debug_on ()</code></p></div></div><h3 id="node-tracking-functions"><a href="#node-tracking-functions" class="anchor"></a>Node tracking functions</h3><div class="odoc-spec"><div class="spec value anchored" id="val-register_type"><a href="#val-register_type" class="anchor"></a><code><span><span class="keyword">val</span> register_type : <span><span>(<a href="#type-decoration">decoration</a> * <a href="../Types/index.html#type-type_expr">Types.type_expr</a>)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>register_type (lbl,ty)</code> adds the type <code>t</code> to all graph printed until <a href="#val-forget"><code>forget</code></a> is called</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-register_subgraph"><a href="#val-register_subgraph" class="anchor"></a><code><span><span class="keyword">val</span> register_subgraph :
|
||
<span><a href="#type-params">params</a> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?decoration</span>:<a href="#type-decoration">decoration</a> <span class="arrow">-></span></span>
|
||
<span><span><a href="../Types/index.html#type-type_expr">Types.type_expr</a> list</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>register_subgraph params tys</code> groups together all types reachable from <code>tys</code> at this point in printed digraphs, until <a href="#val-forget"><code>forget</code></a> is called</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-forget"><a href="#val-forget" class="anchor"></a><code><span><span class="keyword">val</span> forget : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Forget all recorded context types</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-context"><a href="#type-context" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a context</span></span></code></div><div class="spec-doc"><p>Contextual information</p><p>Those functions can be used to modify the filename of the generated digraphs. Use those functions to provide contextual information on a graph emitted during an execution trace.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-global"><a href="#val-global" class="anchor"></a><code><span><span class="keyword">val</span> global : <span>string <a href="#type-context">context</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-loc"><a href="#val-loc" class="anchor"></a><code><span><span class="keyword">val</span> loc : <span><a href="../Warnings/index.html#type-loc">Warnings.loc</a> <a href="#type-context">context</a></span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set_context"><a href="#val-set_context" class="anchor"></a><code><span><span class="keyword">val</span> set_context : <span><span><span class="type-var">'a</span> <a href="#type-context">context</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit</span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_context"><a href="#val-with_context" class="anchor"></a><code><span><span class="keyword">val</span> with_context : <span><span><span class="type-var">'a</span> <a href="#type-context">context</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'b</span></span></code></div></div></div></body></html>
|