<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>

<title>stdlib 41.2.2 Reference</title>

<link rel="stylesheet" href="../ldoc.css" type="text/css" />

<div id="container">

<div id="product">

<div id="product_logo"></div>

<div id="product_name"><big><b></b></big></div>

<div id="product_description"></div>

</div> <!-- id="product" -->

<div id="main">

<div id="navigation">

<h1>stdlib 41.2.2</h1>

<li><a href="../index.html">Index</a></li>

<h2>Contents</h2>

<li><a href="#Functions">Functions</a></li>

<li><a href="#Types">Types </a></li>

<h2>Modules</h2>

<ul class="nowrap">

<li><a href="../modules/std.html">std</a></li>

<li><a href="../modules/std.debug.html">std.debug</a></li>

<li><a href="../modules/std.functional.html">std.functional</a></li>

<li><strong>std.io</strong></li>

<li><a href="../modules/std.math.html">std.math</a></li>

<li><a href="../modules/std.operator.html">std.operator</a></li>

<li><a href="../modules/std.package.html">std.package</a></li>

<li><a href="../modules/std.strict.html">std.strict</a></li>

<li><a href="../modules/std.string.html">std.string</a></li>

<li><a href="../modules/std.table.html">std.table</a></li>

<h2>Classes</h2>

<ul class="nowrap">

<li><a href="../classes/std.tree.html">std.tree</a></li>

<li><a href="../classes/std.container.html">std.container</a></li>

<li><a href="../classes/std.object.html">std.object</a></li>

<li><a href="../classes/std.list.html">std.list</a></li>

<li><a href="../classes/std.optparse.html">std.optparse</a></li>

<li><a href="../classes/std.set.html">std.set</a></li>

<li><a href="../classes/std.strbuf.html">std.strbuf</a></li>

<div id="content">

<h1>Module <code>std.io</code></h1>

<p>Additions to the core io module.</p>

<p> The module table returned by <code>std.io</code> also contains all of the entries from

the core <code>io</code> module table. An hygienic way to import this module, then,

is simply to override core <code>io</code> locally:</p>

<span class="keyword">local</span> <span class="global">io</span> = <span class="global">require</span> <span class="string">"std.io"</span>

<h2><a href="#Functions">Functions</a></h2>

<table class="function_list">

<tr>

<td class="name" nowrap><a href="#catdir">catdir (...)</a></td>

<td class="summary">Concatenate directory names into a path.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#catfile">catfile (...)</a></td>

<td class="summary">Concatenate one or more directories and a filename into a path.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#die">die (msg, ...)</a></td>

<td class="summary">Die with error.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#dirname">dirname (path)</a></td>

<td class="summary">Remove the last dirsep delimited element from a path.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#monkey_patch">monkey_patch ([namespace=_G])</a></td>

<td class="summary">Overwrite core <code>io</code> methods with <code>std</code> enhanced versions.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#process_files">process_files (fn)</a></td>

<td class="summary">Process files specified on the command-line.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#readlines">readlines ([file=io.input()])</a></td>

<td class="summary">Read a file or file handle into a list of lines.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#shell">shell (c)</a></td>

<td class="summary">Perform a shell command and return its output.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#slurp">slurp ([file=io.input()])</a></td>

<td class="summary">Slurp a file handle.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#splitdir">splitdir (path)</a></td>

<td class="summary">Split a directory path into components.</td>

</tr>

<tr>

<td class="name" nowrap><a href="#warn">warn (msg, ...)</a></td>

<td class="summary">Give warning with the name of program and file (if any).</td>

</tr>

<tr>

<td class="name" nowrap><a href="#writelines">writelines ([h=io.output()], ...)</a></td>

<td class="summary">Write values adding a newline after each.</td>

</tr>

<h2><a href="#Types">Types </a></h2>

<table class="function_list">

<tr>

<td class="name" nowrap><a href="#fileprocessor">fileprocessor (filename, i)</a></td>

<td class="summary">Signature of <a href="../modules/std.io.html#process_files">process_files</a> callback function.</td>

</tr>

<h2 class="section-header "><a name="Functions"></a>Functions</h2>

Methods

<dl class="function">

<dt>

<a name = "catdir"></a>

<strong>catdir (...)</strong>

</dt>

<dd>

Concatenate directory names into a path.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">...</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

path components

</li>

</ul>

<h3>Returns:</h3>

<ol>

path without trailing separator

</ol>

<h3>See also:</h3>

<ul>

<a href="../modules/std.io.html#catfile">catfile</a>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">dirpath = catdir (<span class="string">""</span>, <span class="string">"absolute"</span>, <span class="string">"directory"</span>)</pre>

</ul>

<dt>

<a name = "catfile"></a>

<strong>catfile (...)</strong>

</dt>

<dd>

Concatenate one or more directories and a filename into a path.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">...</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

path components

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

path

</ol>

<h3>See also:</h3>

<ul>

<li><a href="../modules/std.io.html#catdir">catdir</a></li>

<li><a href="../modules/std.io.html#splitdir">splitdir</a></li>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">filepath = catfile (<span class="string">"relative"</span>, <span class="string">"path"</span>, <span class="string">"filename"</span>)</pre>

</ul>

<dt>

<a name = "die"></a>

<strong>die (msg, ...)</strong>

</dt>

<dd>

Die with error.

This function uses the same rules to build a message prefix

as <a href="../modules/std.io.html#warn">warn</a>.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">msg</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

format string

</li>

<li><span class="parameter">...</span>

additional arguments to plug format string specifiers

</li>

</ul>

<h3>See also:</h3>

<ul>

<a href="../modules/std.io.html#warn">warn</a>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">die (<span class="string">"oh noes! (%s)"</span>, <span class="global">tostring</span> (obj))</pre>

</ul>

<dt>

<a name = "dirname"></a>

<strong>dirname (path)</strong>

</dt>

<dd>

Remove the last dirsep delimited element from a path.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">path</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

file path

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

a new path with the last dirsep and following

truncated

</ol>

<h3>Usage:</h3>

<ul>

<pre class="example">dir = dirname <span class="string">"/base/subdir/filename"</span></pre>

</ul>

<dt>

<a name = "monkey_patch"></a>

<strong>monkey_patch ([namespace=_G])</strong>

</dt>

<dd>

Overwrite core <code>io</code> methods with <code>std</code> enhanced versions. </p>

<p> Also adds <a href="../modules/std.io.html#readlines">readlines</a> and <a href="../modules/std.io.html#writelines">writelines</a> metamethods to core file objects.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">namespace</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.6">table</a></span>

where to install global functions

(<em>default</em> _G)

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.6">table</a></span>

the <code>std.io</code> module table

</ol>

<h3>Usage:</h3>

<ul>

<pre class="example"><span class="keyword">local</span> <span class="global">io</span> = <span class="global">require</span> <span class="string">"std.io"</span>.monkey_patch ()</pre>

</ul>

<dt>

<a name = "process_files"></a>

<strong>process_files (fn)</strong>

</dt>

<dd>

Process files specified on the command-line.

Each filename is made the default input source with <code>io.input</code>, and

then the filename and argument number are passed to the callback

function. In list of filenames, <code>-</code> means <code>io.stdin</code>. If no

filenames were given, behave as if a single <code>-</code> was passed.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">fn</span>

<span class="types"><a class="type" href="../modules/std.io.html#fileprocessor">fileprocessor</a></span>

function called for each file argument

</li>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">#! /usr/bin/env lua

<span class="comment">-- minimal cat command

</span><span class="keyword">local</span> <span class="global">io</span> = <span class="global">require</span> <span class="string">"std.io"</span>

<span class="global">io</span>.process_files (<span class="keyword">function</span> () <span class="global">io</span>.write (<span class="global">io</span>.slurp ()) <span class="keyword">end</span>)</pre>

</ul>

<dt>

<a name = "readlines"></a>

<strong>readlines ([file=io.input()])</strong>

</dt>

<dd>

Read a file or file handle into a list of lines.

The lines in the returned list are not <code>\n</code> terminated.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">file</span>

<span class="types"><span class="type">file</span> or <a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

file handle or name;

if file is a file handle, that file is closed after reading

(<em>default</em> io.input())

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="../classes/std.list.html">list</a></span>

lines

</ol>

<h3>Usage:</h3>

<ul>

<pre class="example">list = readlines <span class="string">"/etc/passwd"</span></pre>

</ul>

<dt>

<a name = "shell"></a>

<strong>shell (c)</strong>

</dt>

<dd>

Perform a shell command and return its output.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">c</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

command

</li>

</ul>

<h3>Returns:</h3>

<ol>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

output, or nil if error

</ol>

<h3>See also:</h3>

<ul>

<a href="https://www.lua.org/manual/5.3/manual.html#pdf-os.execute">os.execute</a>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">users = shell <span class="string">[[cat /etc/passwd | awk -F: '{print $1;}']]</span></pre>

</ul>

<dt>

<a name = "slurp"></a>

<strong>slurp ([file=io.input()])</strong>

</dt>

<dd>

Slurp a file handle.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">file</span>

<span class="types"><span class="type">file</span> or <a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

file handle or name;

if file is a file handle, that file is closed after reading

(<em>default</em> io.input())

</li>

</ul>

<h3>Returns:</h3>

<ol>

contents of file or handle, or nil if error

</ol>

<h3>See also:</h3>

<ul>

<a href="../modules/std.io.html#process_files">process_files</a>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">contents = slurp (filename)</pre>

</ul>

<dt>

<a name = "splitdir"></a>

<strong>splitdir (path)</strong>

</dt>

<dd>

Split a directory path into components.

Empty components are retained: the root directory becomes <code>{"", ""}</code>.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">path</span>

path

</li>

</ul>

<h3>Returns:</h3>

<ol>

list of path components

</ol>

<h3>See also:</h3>

<ul>

<a href="../modules/std.io.html#catdir">catdir</a>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">dir_components = splitdir (filepath)</pre>

</ul>

<dt>

<a name = "warn"></a>

<strong>warn (msg, ...)</strong>

</dt>

<dd>

Give warning with the name of program and file (if any).

If there is a global <code>prog</code> table, prefix the message with

<code>prog.name</code> or <code>prog.file</code>, and <code>prog.line</code> if any. Otherwise

if there is a global <code>opts</code> table, prefix the message with

<code>opts.program</code> and <code>opts.line</code> if any. <a href="../classes/std.optparse.html#std.optparse:parse">std.optparse:parse</a>

returns an <code>opts</code> table that provides the required <code>program</code>

field, as long as you assign it back to <code>_G.opts</code>.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">msg</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

format string

</li>

<li><span class="parameter">...</span>

additional arguments to plug format string specifiers

</li>

</ul>

<h3>See also:</h3>

<ul>

<li><a href="../classes/std.optparse.html#std.optparse:parse">std.optparse:parse</a></li>

<li><a href="../modules/std.io.html#die">die</a></li>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example"><span class="keyword">local</span> OptionParser = <span class="global">require</span> <span class="string">"std.optparse"</span>

<span class="keyword">local</span> parser = OptionParser <span class="string">"eg 0\nUsage: eg\n"</span>

_G.arg, _G.opts = parser:parse (_G.arg)

<span class="keyword">if</span> <span class="keyword">not</span> _G.opts.keep_going <span class="keyword">then</span>

<span class="global">require</span> <span class="string">"std.io"</span>.warn <span class="string">"oh noes!"</span>

<span class="keyword">end</span></pre>

</ul>

<dt>

<a name = "writelines"></a>

<strong>writelines ([h=io.output()], ...)</strong>

</dt>

<dd>

Write values adding a newline after each.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">h</span>

<span class="types"><span class="type">file</span></span>

open writable file handle;

the file is <strong>not</strong> closed after writing

(<em>default</em> io.output())

</li>

<li><span class="parameter">...</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a> or <span class="type">number</span></span>

values to write (as for write)

</li>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example">writelines (<span class="global">io</span>.stdout, <span class="string">"first line"</span>, <span class="string">"next line"</span>)</pre>

</ul>

<h2 class="section-header "><a name="Types"></a>Types </h2>

<dl class="function">

<dt>

<a name = "fileprocessor"></a>

<strong>fileprocessor (filename, i)</strong>

</dt>

<dd>

Signature of <a href="../modules/std.io.html#process_files">process_files</a> callback function.

<h3>Parameters:</h3>

<ul>

<li><span class="parameter">filename</span>

<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.4">string</a></span>

filename

</li>

<li><span class="parameter">i</span>

<span class="types"><span class="type">int</span></span>

argument number of <em>filename</em>

</li>

</ul>

<h3>Usage:</h3>

<ul>

<pre class="example"><span class="keyword">local</span> fileprocessor = <span class="keyword">function</span> (filename, i)

<span class="global">io</span>.write (<span class="global">tostring</span> (i) .. <span class="string">":\n===\n"</span> .. <span class="global">io</span>.slurp (filename) .. <span class="string">"\n"</span>)

<span class="keyword">end</span>

<span class="global">io</span>.process_files (fileprocessor)</pre>

</ul>

</div> <!-- id="content" -->

</div> <!-- id="main" -->

<div id="about">

<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>

<i style="float:right;">Last updated 2018-09-16 19:20:25 </i>

</div> <!-- id="about" -->

</div> <!-- id="container" -->