mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-06 03:05:28 -05:00
42 lines
22 KiB
HTML
42 lines
22 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>CCIO (containers.CCIO)</title><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.3.1"/><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">containers</a> » CCIO</nav><header class="odoc-preamble"><h1>Module <code><span>CCIO</span></code></h1><p>IO Utils</p><p>Simple utilities to deal with basic Input/Output tasks in a resource-safe way. For advanced IO tasks, the user is advised to use something like Lwt or Async, that are far more comprehensive.</p><p>Examples:</p><ul><li>obtain the list of lines of a file:</li></ul><pre class="language-ocaml"><code># let l = CCIO.(with_in "/tmp/some_file" read_lines_l);;</code></pre><ul><li>transfer one file into another:</li></ul><pre class="language-ocaml"><code># CCIO.(
|
||
with_in "/tmp/input"
|
||
(fun ic ->
|
||
let chunks = read_chunks_gen ic in
|
||
with_out ~flags:[Open_binary; Open_creat] ~mode:0o644 "/tmp/output"
|
||
(fun oc ->
|
||
write_gen oc chunks
|
||
)
|
||
)
|
||
) ;;</code></pre><ul><li>Note that the lifetime of an IO generator is tied to the underlying channel. In the example above, <code>chunks</code> must be used in the scope of <code>ic</code>. This will raise an error:</li></ul><pre class="language-ocaml"><code># CCIO.(
|
||
let chunks =
|
||
with_in "/tmp/input"
|
||
(fun ic -> read_chunks_gen ic)
|
||
in
|
||
with_out ~flags:[Open_binary;Open_creat] ~mode:0o644 "/tmp/output"
|
||
(fun oc ->
|
||
write_gen oc chunks
|
||
)
|
||
) ;;</code></pre><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.6</li></ul><ul class="at-tags"><li class="before"><span class="at-tag">before</span> <span class="value">0.12</span> <p>was in 'containers.io', now moved into 'containers'</p></li></ul></header><nav class="odoc-toc"><ul><li><a href="#input">Input</a></li><li><a href="#output">Output</a></li><li><a href="#both">Both</a></li><li><a href="#misc-for-generators">Misc for Generators</a></li><li><a href="#file-and-file-names">File and file names</a></li></ul></nav><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-or_error"><a href="#type-or_error" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a or_error</span></span><span> = <span><span>(<span class="type-var">'a</span>, string)</span> <a href="../../ocaml/Stdlib/index.html#type-result">result</a></span></span></code></div></div><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-gen"><a href="#type-gen" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a gen</span></span><span> = <span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div><div class="spec-doc"><p>See <code>Gen</code> in the <a href="https://github.com/c-cube/gen">gen library</a>.</p></div></div><h3 id="input"><a href="#input" class="anchor"></a>Input</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_in"><a href="#val-with_in" class="anchor"></a><code><span><span class="keyword">val</span> with_in :
|
||
<span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?flags</span>:<span><a href="../../ocaml/Stdlib/index.html#type-open_flag">open_flag</a> list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span>(<span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <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>Open an input file with the given optional flag list, calls the function on the input channel. When the function raises or returns, the channel is closed.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Sys_error</code> <p>in case of error (same as <code>open_in</code> and <code>close_in</code>).</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">flags</span> <p>opening flags (default <code>[Open_text]</code>). <code>Open_rdonly</code> is used in any cases.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_chunks_gen"><a href="#val-read_chunks_gen" class="anchor"></a><code><span><span class="keyword">val</span> read_chunks_gen : <span><span class="optlabel">?size</span>:int <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string <a href="#type-gen">gen</a></span></span></code></div><div class="spec-doc"><p>Read the channel's content into chunks of size at most <code>size</code>. <b>NOTE</b> the generator must be used within the lifetime of the channel, see warning at the top of the file.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_chunks_seq"><a href="#val-read_chunks_seq" class="anchor"></a><code><span><span class="keyword">val</span> read_chunks_seq : <span><span class="optlabel">?size</span>:int <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string <a href="../../ocaml/Stdlib/Seq/index.html#type-t">Stdlib.Seq.t</a></span></span></code></div><div class="spec-doc"><p>Read the channel's content into chunks of size at most <code>size</code>. <b>NOTE</b> the generator must be used within the lifetime of the channel, see warning at the top of the file.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.5</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_chunks_iter"><a href="#val-read_chunks_iter" class="anchor"></a><code><span><span class="keyword">val</span> read_chunks_iter : <span><span class="optlabel">?size</span>:int <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string <a href="#type-iter">iter</a></span></span></code></div><div class="spec-doc"><p>Read the channel's content into chunks of size at most <code>size</code></p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.6</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_line"><a href="#val-read_line" class="anchor"></a><code><span><span class="keyword">val</span> read_line : <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string option</span></span></code></div><div class="spec-doc"><p>Read a line from the channel. Returns <code>None</code> if the input is terminated. The "\n" is removed from the line.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_lines_gen"><a href="#val-read_lines_gen" class="anchor"></a><code><span><span class="keyword">val</span> read_lines_gen : <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string <a href="#type-gen">gen</a></span></span></code></div><div class="spec-doc"><p>Read all lines. The generator should be traversed only once. <b>NOTE</b> the generator must be used within the lifetime of the channel, see warning at the top of the file.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_lines_seq"><a href="#val-read_lines_seq" class="anchor"></a><code><span><span class="keyword">val</span> read_lines_seq : <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string <a href="../../ocaml/Stdlib/Seq/index.html#type-t">Stdlib.Seq.t</a></span></span></code></div><div class="spec-doc"><p>Read all lines. <b>NOTE</b> the seq must be used within the lifetime of the channel, see warning at the top of the file.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.5</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_lines_iter"><a href="#val-read_lines_iter" class="anchor"></a><code><span><span class="keyword">val</span> read_lines_iter : <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string <a href="#type-iter">iter</a></span></span></code></div><div class="spec-doc"><p>Read all lines.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.6</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_lines_l"><a href="#val-read_lines_l" class="anchor"></a><code><span><span class="keyword">val</span> read_lines_l : <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p>Read all lines into a list.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_all"><a href="#val-read_all" class="anchor"></a><code><span><span class="keyword">val</span> read_all : <span><span class="optlabel">?size</span>:int <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Read the whole channel into a buffer, then converted into a string.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">size</span> <p>the internal buffer size.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.7</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-read_all_bytes"><a href="#val-read_all_bytes" class="anchor"></a><code><span><span class="keyword">val</span> read_all_bytes : <span><span class="optlabel">?size</span>:int <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <a href="../../ocaml/Stdlib/Bytes/index.html#type-t">Stdlib.Bytes.t</a></span></code></div><div class="spec-doc"><p>Read the whole channel into a mutable byte array.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">size</span> <p>the internal buffer size.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.12</li></ul></div></div><h3 id="output"><a href="#output" class="anchor"></a>Output</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_out"><a href="#val-with_out" class="anchor"></a><code><span><span class="keyword">val</span> with_out :
|
||
<span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?flags</span>:<span><a href="../../ocaml/Stdlib/index.html#type-open_flag">open_flag</a> list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span>(<span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <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>Like <a href="#val-with_in"><code>with_in</code></a> but for an output channel.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">flags</span> <p>opening flags (default <code>[Open_creat; Open_trunc; Open_text]</code>).</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Sys_error</code> <p>in case of error (same as <code>open_out</code> and <code>close_out</code>). <code>Open_wronly</code> is used in any cases.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_out_a"><a href="#val-with_out_a" class="anchor"></a><code><span><span class="keyword">val</span> with_out_a :
|
||
<span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?flags</span>:<span><a href="../../ocaml/Stdlib/index.html#type-open_flag">open_flag</a> list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span>(<span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <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>Like <a href="#val-with_out"><code>with_out</code></a> but with the <code>[Open_append; Open_creat; Open_wronly]</code> flags activated, to append to the file.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Sys_error</code> <p>in case of error (same as <code>open_out</code> and <code>close_out</code>).</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_line"><a href="#val-write_line" class="anchor"></a><code><span><span class="keyword">val</span> write_line : <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Write the given string on the channel, followed by "\n".</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_gen"><a href="#val-write_gen" class="anchor"></a><code><span><span class="keyword">val</span> write_gen : <span><span class="optlabel">?sep</span>:string <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span><span>string <a href="#type-gen">gen</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Write the given strings on the output. If provided, add <code>sep</code> between every two strings (but not at the end).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_seq"><a href="#val-write_seq" class="anchor"></a><code><span><span class="keyword">val</span> write_seq : <span><span class="optlabel">?sep</span>:string <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span><span>string <a href="../../ocaml/Stdlib/Seq/index.html#type-t">Stdlib.Seq.t</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Write the given strings on the output. If provided, add <code>sep</code> between every two strings (but not at the end).</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.5</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_lines"><a href="#val-write_lines" class="anchor"></a><code><span><span class="keyword">val</span> write_lines : <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span><span>string <a href="#type-gen">gen</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Write every string on the output, followed by "\n".</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_lines_iter"><a href="#val-write_lines_iter" class="anchor"></a><code><span><span class="keyword">val</span> write_lines_iter : <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span><span>string <a href="#type-iter">iter</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Write every string on the output, followed by "\n".</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.6</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_lines_seq"><a href="#val-write_lines_seq" class="anchor"></a><code><span><span class="keyword">val</span> write_lines_seq : <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span><span>string <a href="../../ocaml/Stdlib/Seq/index.html#type-t">Stdlib.Seq.t</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Write every string on the output, followed by "\n".</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.5</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-write_lines_l"><a href="#val-write_lines_l" class="anchor"></a><code><span><span class="keyword">val</span> write_lines_l : <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span><span>string list</span> <span class="arrow">-></span></span> unit</span></code></div></div><h3 id="both"><a href="#both" class="anchor"></a>Both</h3><div class="odoc-spec"><div class="spec value anchored" id="val-with_in_out"><a href="#val-with_in_out" class="anchor"></a><code><span><span class="keyword">val</span> with_in_out :
|
||
<span><span class="optlabel">?mode</span>:int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?flags</span>:<span><a href="../../ocaml/Stdlib/index.html#type-open_flag">open_flag</a> list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span>(<span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <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>Combines <a href="#val-with_in"><code>with_in</code></a> and <a href="#val-with_out"><code>with_out</code></a>.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">flags</span> <p>opening flags (default <code>[Open_creat]</code>).</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Sys_error</code> <p>in case of error.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 0.12</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-copy_into"><a href="#val-copy_into" class="anchor"></a><code><span><span class="keyword">val</span> copy_into : <span><span class="optlabel">?bufsize</span>:int <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span><a href="../../ocaml/Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>copy_into ic oc</code> writes the content of <code>ic</code> into <code>oc</code>. It is a blocking call.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.0</li></ul></div></div><h3 id="misc-for-generators"><a href="#misc-for-generators" class="anchor"></a>Misc for Generators</h3><div class="odoc-spec"><div class="spec value anchored" id="val-tee"><a href="#val-tee" class="anchor"></a><code><span><span class="keyword">val</span> tee : <span><span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit)</span> list</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-gen">gen</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-gen">gen</a></span></span></code></div><div class="spec-doc"><p><code>tee funs gen</code> behaves like <code>gen</code>, but each element is given to every function <code>f</code> in <code>funs</code> at the time the element is produced. The returned generator will raise any exception that <code>f</code> raises</p></div></div><h3 id="file-and-file-names"><a href="#file-and-file-names" class="anchor"></a>File and file names</h3><p>How to list recursively files in a directory:</p><pre class="language-ocaml"><code># let files = CCIO.File.read_dir ~recurse:true (CCIO.File.make "/tmp");;
|
||
# CCIO.write_lines stdout files;;</code></pre><p>See <a href="File/index.html#val-walk"><code>File.walk</code></a> if you also need to list directories:</p><pre class="language-ocaml"><code># let content = CCIO.File.walk (CCIO.File.make "/tmp");;
|
||
# Gen.map CCIO.File.show_walk_item content |> CCIO.write_lines stdout;;</code></pre><div class="odoc-spec"><div class="spec module anchored" id="module-File"><a href="#module-File" class="anchor"></a><code><span><span class="keyword">module</span> <a href="File/index.html">File</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div></div></body></html>
|