stdlib

• Index

Contents

• Deprecated Functions
• Diagnostic functions
• Path Functions
• IO Functions
• Types

Core Libraries

• std.debug
• std.io
• std.math
• std.package
• std.string
• std.table

Core Functions

• std

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'

Deprecated Functions

monkey_patch ([namespace=_G])

Overwrite core io functions with std enhanced versions.

Diagnostic functions

die (msg, ...)	Die with error.
warn (msg, ...)	Give warning with the name of program and file(if any).

Path Functions

catdir (...)	Concatenate directory names into a path.
catfile (...)	Concatenate one or more directories and a filename into a path.
dirname (path)	Remove the last dirsep delimited element from a path.
splitdir (path)	Split a directory path into components.

IO Functions

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.
writelines ([h=io.output()], ...)	Write values adding a newline after each.

Types

fileprocessor (filename, i)

Signature of process_files callback function.

Deprecated Functions

monkey_patch ([namespace=_G])

Overwrite core io functions with std enhanced versions.

Parameters:

• namespace table where to install global functions (default _G)

Returns:

table the module table

Usage:

require 'std.io'.monkey_patch()

Diagnostic functions

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

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.

Parameters:

• msg string format string
• ... additional arguments to plug format string specifiers

See also:

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

Path Functions

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')

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'

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)

IO Functions

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)

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 integer 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)