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
iomethods withstdenhanced 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.iomodule tableUsage:
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,-meansio.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
\nterminated.Parameters:
- file file 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 file 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
progtable, prefix the message withprog.nameorprog.file, andprog.lineif any. Otherwise if there is a globaloptstable, prefix the message withopts.programandopts.lineif any. std.optparse:parse returns anoptstable that provides the requiredprogramfield, 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 file open writable file handle; the file is not closed after writing (default io.output())
- ... string or number 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 int 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)