stdlib 41.2.2

• Index

Contents

• Functions
• Types

Modules

• std
• std.debug
• std.functional
• std.io
• std.math
• std.operator
• std.package
• std.strict
• std.string
• std.table

Classes

• std.tree
• std.container
• std.object
• std.list
• std.optparse
• std.set
• std.strbuf

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:

catfile

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:

• catdir
• splitdir

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:

warn

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 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:

os.execute

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:

process_files

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:

catdir

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:

• std.optparse:parse
• die

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)