mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-06 11:15:31 -05:00
22 lines
No EOL
12 KiB
HTML
22 lines
No EOL
12 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>CCIO (containers.CCIO)</title><link rel="stylesheet" href="../../odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 1.5.2"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div class="content"><header><nav><a href="../index.html">Up</a> – <a href="../index.html">containers</a> » CCIO</nav><h1>Module <code>CCIO</code></h1><h2 id="io-utils"><a href="#io-utils" class="anchor"></a>IO Utils</h2><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><code class="ml"># let l = CCIO.(with_in "/tmp/some_file" read_lines_l);;</code></pre><ul><li>transfer one file into another:</li></ul><pre><code class="ml"># 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><code class="ml"># 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><dl><dt>since</dt><dd>0.6</dd></dl><dl><dt>before 0.12</dt><dd><p>was in 'containers.io', now moved into 'containers'</p></dd></dl><nav class="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></header><dl><dt class="spec type" id="type-or_error"><a href="#type-or_error" class="anchor"></a><code><span class="keyword">type</span> <span>'a or_error</span></code><code> = <span><span>(<span class="type-var">'a</span>, string)</span> Stdlib.result</span></code></dt><dt class="spec type" id="type-gen"><a href="#type-gen" class="anchor"></a><code><span class="keyword">type</span> <span>'a gen</span></code><code> = unit <span>-></span> <span><span class="type-var">'a</span> option</span></code></dt><dd><p>See <code>Gen</code> in the <a href="https://github.com/c-cube/gen">gen library</a>.</p></dd></dl><section><header><h3 id="input"><a href="#input" class="anchor"></a>Input</h3></header><dl><dt class="spec value" id="val-with_in"><a href="#val-with_in" class="anchor"></a><code><span class="keyword">val</span> with_in : <span>?⁠mode:int</span> <span>-></span> <span>?⁠flags:<span>Stdlib.open_flag list</span></span> <span>-></span> string <span>-></span> <span>(Stdlib.in_channel <span>-></span> <span class="type-var">'a</span>)</span> <span>-></span> <span class="type-var">'a</span></code></dt><dd><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><dl><dt>raises Sys_error</dt><dd><p>in case of error (same as <code>open_in</code> and <code>close_in</code>).</p></dd></dl><dl><dt>parameter flags</dt><dd><p>opening flags (default <code>[Open_text]</code>). <code>Open_rdonly</code> is used in any cases.</p></dd></dl></dd></dl><dl><dt class="spec value" id="val-read_chunks_gen"><a href="#val-read_chunks_gen" class="anchor"></a><code><span class="keyword">val</span> read_chunks_gen : <span>?⁠size:int</span> <span>-></span> Stdlib.in_channel <span>-></span> <span>string <a href="index.html#type-gen">gen</a></span></code></dt><dd><p>Read the channel's content into chunks of size <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></dd></dl><dl><dt class="spec value" id="val-read_line"><a href="#val-read_line" class="anchor"></a><code><span class="keyword">val</span> read_line : Stdlib.in_channel <span>-></span> <span>string option</span></code></dt><dd><p>Read a line from the channel. Returns <code>None</code> if the input is terminated. The "\n" is removed from the line.</p></dd></dl><dl><dt class="spec value" id="val-read_lines_gen"><a href="#val-read_lines_gen" class="anchor"></a><code><span class="keyword">val</span> read_lines_gen : Stdlib.in_channel <span>-></span> <span>string <a href="index.html#type-gen">gen</a></span></code></dt><dd><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></dd></dl><dl><dt class="spec value" id="val-read_lines_l"><a href="#val-read_lines_l" class="anchor"></a><code><span class="keyword">val</span> read_lines_l : Stdlib.in_channel <span>-></span> <span>string list</span></code></dt><dd><p>Read all lines into a list.</p></dd></dl><dl><dt class="spec value" id="val-read_all"><a href="#val-read_all" class="anchor"></a><code><span class="keyword">val</span> read_all : <span>?⁠size:int</span> <span>-></span> Stdlib.in_channel <span>-></span> string</code></dt><dd><p>Read the whole channel into a buffer, then converted into a string.</p><dl><dt>parameter size</dt><dd><p>the internal buffer size.</p></dd></dl><dl><dt>since</dt><dd>0.7</dd></dl></dd></dl><dl><dt class="spec value" id="val-read_all_bytes"><a href="#val-read_all_bytes" class="anchor"></a><code><span class="keyword">val</span> read_all_bytes : <span>?⁠size:int</span> <span>-></span> Stdlib.in_channel <span>-></span> Stdlib.Bytes.t</code></dt><dd><p>Read the whole channel into a mutable byte array.</p><dl><dt>parameter size</dt><dd><p>the internal buffer size.</p></dd></dl><dl><dt>since</dt><dd>0.12</dd></dl></dd></dl></section><section><header><h3 id="output"><a href="#output" class="anchor"></a>Output</h3></header><dl><dt class="spec value" id="val-with_out"><a href="#val-with_out" class="anchor"></a><code><span class="keyword">val</span> with_out : <span>?⁠mode:int</span> <span>-></span> <span>?⁠flags:<span>Stdlib.open_flag list</span></span> <span>-></span> string <span>-></span> <span>(Stdlib.out_channel <span>-></span> <span class="type-var">'a</span>)</span> <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Like <a href="index.html#val-with_in"><code>with_in</code></a> but for an output channel.</p><dl><dt>parameter flags</dt><dd><p>opening flags (default <code>[Open_creat; Open_trunc; Open_text]</code>).</p></dd></dl><dl><dt>raises Sys_error</dt><dd><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></dd></dl></dd></dl><dl><dt class="spec value" id="val-with_out_a"><a href="#val-with_out_a" class="anchor"></a><code><span class="keyword">val</span> with_out_a : <span>?⁠mode:int</span> <span>-></span> <span>?⁠flags:<span>Stdlib.open_flag list</span></span> <span>-></span> string <span>-></span> <span>(Stdlib.out_channel <span>-></span> <span class="type-var">'a</span>)</span> <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Like <a href="index.html#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><dl><dt>raises Sys_error</dt><dd><p>in case of error (same as <code>open_out</code> and <code>close_out</code>).</p></dd></dl></dd></dl><dl><dt class="spec value" id="val-write_line"><a href="#val-write_line" class="anchor"></a><code><span class="keyword">val</span> write_line : Stdlib.out_channel <span>-></span> string <span>-></span> unit</code></dt><dd><p>Write the given string on the channel, followed by "\n".</p></dd></dl><dl><dt class="spec value" id="val-write_gen"><a href="#val-write_gen" class="anchor"></a><code><span class="keyword">val</span> write_gen : <span>?⁠sep:string</span> <span>-></span> Stdlib.out_channel <span>-></span> <span>string <a href="index.html#type-gen">gen</a></span> <span>-></span> unit</code></dt><dd><p>Write the given strings on the output. If provided, add <code>sep</code> between every two strings (but not at the end).</p></dd></dl><dl><dt class="spec value" id="val-write_lines"><a href="#val-write_lines" class="anchor"></a><code><span class="keyword">val</span> write_lines : Stdlib.out_channel <span>-></span> <span>string <a href="index.html#type-gen">gen</a></span> <span>-></span> unit</code></dt><dd><p>Write every string on the output, followed by "\n".</p></dd></dl><dl><dt class="spec value" id="val-write_lines_l"><a href="#val-write_lines_l" class="anchor"></a><code><span class="keyword">val</span> write_lines_l : Stdlib.out_channel <span>-></span> <span>string list</span> <span>-></span> unit</code></dt></dl></section><section><header><h3 id="both"><a href="#both" class="anchor"></a>Both</h3></header><dl><dt class="spec value" id="val-with_in_out"><a href="#val-with_in_out" class="anchor"></a><code><span class="keyword">val</span> with_in_out : <span>?⁠mode:int</span> <span>-></span> <span>?⁠flags:<span>Stdlib.open_flag list</span></span> <span>-></span> string <span>-></span> <span>(Stdlib.in_channel <span>-></span> Stdlib.out_channel <span>-></span> <span class="type-var">'a</span>)</span> <span>-></span> <span class="type-var">'a</span></code></dt><dd><p>Combines <a href="index.html#val-with_in"><code>with_in</code></a> and <a href="index.html#val-with_out"><code>with_out</code></a>.</p><dl><dt>parameter flags</dt><dd><p>opening flags (default <code>[Open_creat]</code>).</p></dd></dl><dl><dt>raises Sys_error</dt><dd><p>in case of error.</p></dd></dl><dl><dt>since</dt><dd>0.12</dd></dl></dd></dl><dl><dt class="spec value" id="val-copy_into"><a href="#val-copy_into" class="anchor"></a><code><span class="keyword">val</span> copy_into : <span>?⁠bufsize:int</span> <span>-></span> Stdlib.in_channel <span>-></span> Stdlib.out_channel <span>-></span> unit</code></dt><dd><p><code>copy_into ic oc</code> writes the content of <code>ic</code> into <code>oc</code>. It is a blocking call.</p><dl><dt>since</dt><dd>3.0</dd></dl></dd></dl></section><section><header><h3 id="misc-for-generators"><a href="#misc-for-generators" class="anchor"></a>Misc for Generators</h3></header><dl><dt class="spec value" id="val-tee"><a href="#val-tee" class="anchor"></a><code><span class="keyword">val</span> tee : <span><span>(<span class="type-var">'a</span> <span>-></span> unit)</span> list</span> <span>-></span> <span><span class="type-var">'a</span> <a href="index.html#type-gen">gen</a></span> <span>-></span> <span><span class="type-var">'a</span> <a href="index.html#type-gen">gen</a></span></code></dt><dd><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></dd></dl></section><section><header><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><code class="ml"># 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><code class="ml"># let content = CCIO.File.walk (CCIO.File.make "/tmp");;
|
||
# Gen.map CCIO.File.show_walk_item content |> CCIO.write_lines stdout;;</code></pre></header><div class="spec module" id="module-File"><a href="#module-File" class="anchor"></a><code><span class="keyword">module</span> <a href="File/index.html">File</a> : <span class="keyword">sig</span> ... <span class="keyword">end</span></code></div></section></div></body></html> |