mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-06 11:15:31 -05:00
2 lines
24 KiB
HTML
2 lines
24 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Containers_pp (containers.Containers_pp)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../odoc.support/odoc.css"/><meta name="generator" content="odoc 2.4.3"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../odoc.support/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">containers</a> » Containers_pp</nav><header class="odoc-preamble"><h1>Module <code><span>Containers_pp</span></code></h1><p>Pretty printing of documents.</p><p>A document is a structured tree of text with formatting instructions.</p><p>It can be rendered into a string ("pretty printed"), see <a href="Pretty/index.html"><code>Pretty</code></a>.</p><p>This follows Wadler's paper "A prettier printer", but with some changes in the rendering part because we can't rely on lazyness to make the algebraic implementation efficient.</p><p>Some general considerations: the type <code>t</code> is the type of documents, a tree with text leaves that is pretty printed within a given width.</p><p>Layout is controlled via the combination of a few primitives:</p><ul><li><code>newline</code> will either print a space or a newline. It is similar to <code>Format</code>'s <code>"@ "</code> in that sense. A big difference with <code>Format</code> is that by default <code>newline</code> is actually a newline. It only becomes a space if it's in a <code>group</code> small enough to fit in the remainder of the current line.</li><li><code>group d</code> tries to write <code>d</code> on a single line if there's room. If not, it has no effect.</li><li><code>nest n d</code> increases the indentation level inside <code>d</code>. Any newline that is rendered as a new line is indented by <code>n</code> more spaces (which are cumulative with surrounding <code>nest</code> calls).</li><li><code>append a b</code> (or <code>a ^ b</code>) just prints <code>a</code> followed by <code>b</code>.</li><li><code>fill d</code> is a bit like <code>group</code> but it will try to cram as much as possible on each line. It is not all-or-nothing like <code>group</code>.</li></ul></header><nav class="odoc-toc"><ul><li><a href="#core">Core</a></li><li><a href="#output-device">Output device</a></li><li><a href="#extensibility">Extensibility</a></li><li><a href="#pretty-print-and-rendering">Pretty print and rendering</a></li><li><a href="#convenience-functions">Convenience functions</a></li></ul></nav><div class="odoc-content"><h3 id="core"><a href="#core" class="anchor"></a>Core</h3><div class="odoc-spec"><div class="spec type anchored" id="type-iter"><a href="#type-iter" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a iter</span></span><span> = <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit</span></code></div></div><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> t</span></code></div><div class="spec-doc"><p>The type of documents</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nil"><a href="#val-nil" class="anchor"></a><code><span><span class="keyword">val</span> nil : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Empty document</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-char"><a href="#val-char" class="anchor"></a><code><span><span class="keyword">val</span> char : <span>char <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Single char.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-text"><a href="#val-text" class="anchor"></a><code><span><span class="keyword">val</span> text : <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Text. The string will be split on <code>'\n'</code>, which are replaced by <a href="#val-newline"><code>newline</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-textpf"><a href="#val-textpf" class="anchor"></a><code><span><span class="keyword">val</span> textpf : <span><span><span>(<span class="type-var">'a</span>, unit, string, <a href="#type-t">t</a>)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Text, with a <code>Printf</code>-compatible format.</p><p>For example, <code>textpf "%d-%d" 4 2</code> is like <code>text "4-2"</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-textf"><a href="#val-textf" class="anchor"></a><code><span><span class="keyword">val</span> textf : <span><span><span>(<span class="type-var">'a</span>, <span class="xref-unresolved">Stdlib</span>.Format.formatter, unit, <a href="#type-t">t</a>)</span> <span class="xref-unresolved">Stdlib</span>.format4</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Text, with a <code>Format</code>-compatible format.</p><p>Note that this will bake-in any formatting done by <code>Format</code>. Newlines introduced by format will become hard newlines in the resulting document.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nest"><a href="#val-nest" class="anchor"></a><code><span><span class="keyword">val</span> nest : <span>int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>nest n d</code> increases indentation by <code>n</code> inside <code>d</code>. If current indentation is <code>m</code>, then every newline inside <code>d</code> will be followed by <code>n + m</code> leading spaces.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-group"><a href="#val-group" class="anchor"></a><code><span><span class="keyword">val</span> group : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Group the documents inside this.</p><p>Newlines immediately inside this group will either render as new lines or as spaces, depending on the width available.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-append"><a href="#val-append" class="anchor"></a><code><span><span class="keyword">val</span> append : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Concatenation.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-newline"><a href="#val-newline" class="anchor"></a><code><span><span class="keyword">val</span> newline : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>A line break.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-newline_or_spaces"><a href="#val-newline_or_spaces" class="anchor"></a><code><span><span class="keyword">val</span> newline_or_spaces : <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>newline_or_spaces n</code> either prints a newline (respecting indentation), or prints <code>n</code> spaces. <a href="#val-newline"><code>newline</code></a> is basically <code>newline_or_spaces 1</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if <code>n < 0</code>.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.13</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-nl"><a href="#val-nl" class="anchor"></a><code><span><span class="keyword">val</span> nl : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Alias for <a href="#val-newline"><code>newline</code></a></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fill"><a href="#val-fill" class="anchor"></a><code><span><span class="keyword">val</span> fill : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>fill sep l</code> resembles <code>group (append_l ~sep l)</code>, except it tries to put as many items of <code>l</code> as possible on each line.</p><p>In terms of <code>Format</code>, this is like the hov box.</p></div></div><h3 id="output-device"><a href="#output-device" class="anchor"></a>Output device</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Out"><a href="#module-Out" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Out/index.html">Out</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Arbitrary output.</p></div></div><h3 id="extensibility"><a href="#extensibility" class="anchor"></a>Extensibility</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Ext"><a href="#module-Ext" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Ext/index.html">Ext</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Extension node.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-ext"><a href="#val-ext" class="anchor"></a><code><span><span class="keyword">val</span> ext : <span><span><span class="type-var">'a</span> <a href="Ext/index.html#type-t">Ext.t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>ext e v d</code> wraps <code>d</code> with value <code>v</code>.</p><p>It is a document that has the same shape (and size) as <code>d</code>, except that additional data will be output when it is rendered using extension <code>e</code>.</p><p>When this is rendered, first <code>e.pre out v</code> is called; then <code>d</code> is printed; then <code>e.post out v</code> is called. Here <code>out</code> is the output buffer/stream for rendering.</p></div></div><h3 id="pretty-print-and-rendering"><a href="#pretty-print-and-rendering" class="anchor"></a>Pretty print and rendering</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Pretty"><a href="#module-Pretty" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Pretty/index.html">Pretty</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Pretty-printing.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Flatten"><a href="#module-Flatten" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Flatten/index.html">Flatten</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Trivial printing, on a single line.</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><span class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Pretty-print, using <a href="Pretty/index.html"><code>Pretty</code></a> and an unspecified margin.</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 class="xref-unresolved">Stdlib</span>.Format.formatter <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Debug printer. This prints the structure of the document, it does <b>not</b> pretty-print it. See <a href="#val-pp"><code>pp</code></a> or <a href="Pretty/index.html"><code>Pretty</code></a>.</p></div></div><h3 id="convenience-functions"><a href="#convenience-functions" class="anchor"></a>Convenience functions</h3><div class="odoc-spec"><div class="spec module anchored" id="module-Infix"><a href="#module-Infix" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Infix/index.html">Infix</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-include"><details open="open"><summary class="spec include"><code><span><span class="keyword">include</span> <span class="keyword">module</span> <span class="keyword">type</span> <span class="keyword">of</span> <a href="Infix/index.html">Infix</a></span></code></summary><div class="odoc-spec"><div class="spec value anchored" id="val-(^)"><a href="#val-(^)" class="anchor"></a><code><span><span class="keyword">val</span> (^) : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Alias of <a href="#val-append"><code>append</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(^+)"><a href="#val-(^+)" class="anchor"></a><code><span><span class="keyword">val</span> (^+) : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>x ^+ y</code> is <code>x ^ text " " ^ y</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-(^/)"><a href="#val-(^/)" class="anchor"></a><code><span><span class="keyword">val</span> (^/) : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>x ^/ y</code> is <code>x ^ newline ^ y</code></p></div></div></details></div><div class="odoc-spec"><div class="spec value anchored" id="val-sp"><a href="#val-sp" class="anchor"></a><code><span><span class="keyword">val</span> sp : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>A single space</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-append_l"><a href="#val-append_l" class="anchor"></a><code><span><span class="keyword">val</span> append_l : <span><span class="optlabel">?sep</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>append_l ?sep l</code> is the concatenation of elements of <code>l</code>, separated by <code>sep</code> (default <code>nil</code>)</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-append_sp"><a href="#val-append_sp" class="anchor"></a><code><span><span class="keyword">val</span> append_sp : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>append_sp l</code> is the concatenation of elements of <code>l</code>, separated by <code>' '</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-append_nl"><a href="#val-append_nl" class="anchor"></a><code><span><span class="keyword">val</span> append_nl : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Same as <a href="#val-append_l"><code>append_l</code></a> with <code>sep=nl</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fill_map"><a href="#val-fill_map" class="anchor"></a><code><span><span class="keyword">val</span> fill_map : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <a href="#type-t">t</a>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>fill_map sep f l</code> is <code>fill sep (List.map f l)</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-bool"><a href="#val-bool" class="anchor"></a><code><span><span class="keyword">val</span> bool : <span>bool <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-int"><a href="#val-int" class="anchor"></a><code><span><span class="keyword">val</span> int : <span>int <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-float"><a href="#val-float" class="anchor"></a><code><span><span class="keyword">val</span> float : <span>float <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-float_hex"><a href="#val-float_hex" class="anchor"></a><code><span><span class="keyword">val</span> float_hex : <span>float <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-text_quoted"><a href="#val-text_quoted" class="anchor"></a><code><span><span class="keyword">val</span> text_quoted : <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>text_quoted s</code> is <code>text (spf "%S" s)</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-text_zero_width"><a href="#val-text_zero_width" class="anchor"></a><code><span><span class="keyword">val</span> text_zero_width : <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Text but we assume it takes no space on screen.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_list"><a href="#val-of_list" class="anchor"></a><code><span><span class="keyword">val</span> of_list : <span><span class="optlabel">?sep</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <a href="#type-t">t</a>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>of_list f l</code> maps each element of <code>l</code> to a document and concatenates them.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">sep</span> <p>separator inserted between elements (default <code>nil</code>)</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_seq"><a href="#val-of_seq" class="anchor"></a><code><span><span class="keyword">val</span> of_seq : <span><span class="optlabel">?sep</span>:<a href="#type-t">t</a> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <a href="#type-t">t</a>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <span class="xref-unresolved">Stdlib</span>.Seq.t</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Same as <a href="#val-of_list"><code>of_list</code></a> but with sequences.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-bracket"><a href="#val-bracket" class="anchor"></a><code><span><span class="keyword">val</span> bracket : <span>string <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>bracket l d r</code> groups <code>d</code>, between brackets <code>l</code> and <code>r</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-bracket2"><a href="#val-bracket2" class="anchor"></a><code><span><span class="keyword">val</span> bracket2 : <span>string <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>bracket2 l d r</code> groups <code>d</code>, indented by 2, between brackets <code>l</code> and <code>r</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-sexp_apply"><a href="#val-sexp_apply" class="anchor"></a><code><span><span class="keyword">val</span> sexp_apply : <span>string <span class="arrow">-></span></span> <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>sexp_apply a l</code> is the S-expr <code>"(text a …l)"</code>, pretty-printed</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-sexp_l"><a href="#val-sexp_l" class="anchor"></a><code><span><span class="keyword">val</span> sexp_l : <span><span><a href="#type-t">t</a> list</span> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>sexp_l [l1;…ln]</code> is the S-expr <code>"(l1 l2…ln)"</code>, pretty-printed</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Dump"><a href="#module-Dump" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Dump/index.html">Dump</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Printers that correspond closely to OCaml's syntax.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Term_color"><a href="#module-Term_color" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Term_color/index.html">Term_color</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>Simple colors in terminals</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Char"><a href="#module-Char" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Char/index.html">Char</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-surround"><a href="#val-surround" class="anchor"></a><code><span><span class="keyword">val</span> surround : <span><span class="optlabel">?width</span>:int <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p>Generalization of <a href="#val-bracket"><code>bracket</code></a></p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.13.1</li></ul></div></div></div></body></html>
|