Module std.io
Additions to the core io module.
The module table returned by `std.io` also contains all of the entries from the core `io` module table. An hygienic way to import this module, then, is simply to override core `io` locally:
local io = require "std.io"
Functions
| catdir (...) | Concatenate directory names into a path. |
| catfile (...) | Concatenate one or more directories and a filename into a path. |
| die (msg, ...) | Die with error. |
| dirname (path) | Remove the last dirsep delimited element from a path. |
| monkey_patch ([namespace=_G]) | Overwrite core `io` methods with `std` enhanced versions. |
| process_files (fn) | Process files specified on the command-line. |
| readlines ([file=io.input()]) | Read a file or file handle into a list of lines. |
| shell (c) | Perform a shell command and return its output. |
| slurp ([file=io.input()]) | Slurp a file handle. |
| splitdir (path) | Split a directory path into components. |
| warn (msg, ...) | Give warning with the name of program and file (if any). |
| writelines ([h=io.output()], ...) | Write values adding a newline after each. |
Types
| fileprocessor (filename, i) | Signature of process_files callback function. |
Functions
Methods- catdir (...)
-
Concatenate directory names into a path.
Parameters:
- ... string path components
Returns:
-
path without trailing separator
See also:
Usage:
dirpath = catdir ("", "absolute", "directory")
- catfile (...)
-
Concatenate one or more directories and a filename into a path.
Parameters:
- ... string path components
Returns:
-
string
path
See also:
Usage:
filepath = catfile ("relative", "path", "filename")
- die (msg, ...)
-
Die with error.
This function uses the same rules to build a message prefix
as warn.
Parameters:
- msg string format string
- ... additional arguments to plug format string specifiers
See also:
Usage:
die ("oh noes! (%s)", tostring (obj))
- dirname (path)
-
Remove the last dirsep delimited element from a path.
Parameters:
- path string file path
Returns:
-
string
a new path with the last dirsep and following
truncated
Usage:
dir = dirname "/base/subdir/filename"
- monkey_patch ([namespace=_G])
-
Overwrite core `io` methods with `std` enhanced versions.
Also adds readlines and writelines metamethods to core file objects.
Parameters:
- namespace table where to install global functions (default _G)
Returns:
-
table
the `std.io` module table
Usage:
local io = require "std.io".monkey_patch ()
- process_files (fn)
-
Process files specified on the command-line.
Each filename is made the default input source with `io.input`, and
then the filename and argument number are passed to the callback
function. In list of filenames, `-` means `io.stdin`. If no
filenames were given, behave as if a single `-` was passed.
Parameters:
- fn fileprocessor function called for each file argument
Usage:
#! /usr/bin/env lua -- minimal cat command local io = require "std.io" io.process_files (function () io.write (io.slurp ()) end)
- readlines ([file=io.input()])
-
Read a file or file handle into a list of lines.
The lines in the returned list are not `\n` terminated.
Parameters:
- file fileprocessor or string file handle or name; if file is a file handle, that file is closed after reading (default io.input())
Returns:
-
list
lines
Usage:
list = readlines "/etc/passwd"
- shell (c)
-
Perform a shell command and return its output.
Parameters:
- c string command
Returns:
-
string
output, or nil if error
See also:
Usage:
users = shell [[cat /etc/passwd | awk -F: '{print $1;}']]
- slurp ([file=io.input()])
-
Slurp a file handle.
Parameters:
- file string or string file handle or name; if file is a file handle, that file is closed after reading (default io.input())
Returns:
-
contents of file or handle, or nil if error
See also:
Usage:
contents = slurp (filename) - splitdir (path)
-
Split a directory path into components.
Empty components are retained: the root directory becomes `{"", ""}`.
Parameters:
- path path
Returns:
-
list of path components
See also:
Usage:
dir_components = splitdir (filepath) - warn (msg, ...)
-
Give warning with the name of program and file (if any).
If there is a global `prog` table, prefix the message with
`prog.name` or `prog.file`, and `prog.line` if any. Otherwise
if there is a global `opts` table, prefix the message with
`opts.program` and `opts.line` if any. std.optparse:parse
returns an `opts` table that provides the required `program`
field, as long as you assign it back to `_G.opts`.
Parameters:
- msg string format string
- ... additional arguments to plug format string specifiers
See also:
Usage:
local OptionParser = require "std.optparse" local parser = OptionParser "eg 0\nUsage: eg\n" _G.arg, _G.opts = parser:parse (_G.arg) if not _G.opts.keep_going then require "std.io".warn "oh noes!" end
- writelines ([h=io.output()], ...)
-
Write values adding a newline after each.
Parameters:
- h string open writable file handle; the file is **not** closed after writing (default io.output())
- ... string or string values to write (as for write)
Usage:
writelines (io.stdout, "first line", "next line")
Types
- fileprocessor (filename, i)
-
Signature of process_files callback function.
Parameters:
- filename string filename
- i string argument number of *filename*
Usage:
local fileprocessor = function (filename, i) io.write (tostring (i) .. ":\n===\n" .. io.slurp (filename) .. "\n") end io.process_files (fileprocessor)