stdlib

• Index

Contents

• Fields
• Core Functions
• Module Functions
• Iterator Functions
• Deprecated Functions
• Metamethods

Core Functions

• std

Core Libraries

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

Module std

Enhanced Lua core functions, and others.

After requiring this module, simply referencing symbols in the submodule hierarchy will load the necessary modules on demand. There are no changes to any global symbols, or monkey patching of core module tables and metatables.

Fields

version

Release version string.

Core Functions

assert (expect[, f=''[, ...]])	Enhance core assert to also allow formatted arguments.
eval (s)	Evaluate a string as Lua code.
getmetamethod (x, n)	Return named metamethod, if any, otherwise nil.

Module Functions

require (module[, min[, too_big[, pattern]]])

Enhance core require to assert version number compatibility.

Iterator Functions

elems (t)	An iterator over all values of a table.
ielems (t)	An iterator over the integer keyed elements of a table.
ipairs (t)	An iterator over integer keyed pairs of a sequence.
npairs (t)	Ordered iterator for integer keyed values.
pairs (t)	Enhance core pairs to respect __pairs even in Lua 5.1.
ripairs (t)	An iterator like ipairs, but in reverse.
rnpairs (t)	An iterator like npairs, but in reverse.

Deprecated Functions

barrel ([namespace=_G])	A barrel of monkey_patches.
ireverse (t)	Return a new table with element order reversed.
monkey_patch ([namespace=_G])	Overwrite core methods with std enhanced versions.
tostring (x)	Enhance core tostring to render table contents as a string.

Metamethods

__index (name)

Lazy loading of stdlib modules.

Fields

version

Release version string.

• version

Core Functions

assert (expect[, f=''[, ...]])

Enhance core assert to also allow formatted arguments.

Parameters:

• expect expression, expected to be truthy
• f string format string (default '')
• ... arguments to format (optional)

Returns:

value of expect, if truthy

Usage:

std.assert(expect == nil, '100% unexpected!')
std.assert(expect == 'expect', '%s the unexpected!', expect)

eval (s)

Evaluate a string as Lua code.

Parameters:

• s string string of Lua code

Returns:

result of evaluating s

Usage:

--> 2
std.eval 'math.min(2, 10)'

getmetamethod (x, n)

Return named metamethod, if any, otherwise nil. The value found at the given key in the metatable of x must be a function or have its own __call metamethod to qualify as a callable. Any other value found at key n will cause this function to return nil.

Parameters:

• x item to act on
• n string name of metamethod to lookup

Returns:

callable or nil callable metamethod, or nil if no metamethod

Usage:

clone = std.getmetamethod(std.object, '__call')

Module Functions

require (module[, min[, too_big[, pattern]]])

Enhance core require to assert version number compatibility. By default match against the last substring of(dot-delimited) digits in the module version string.

Parameters:

• module string module to require
• min string lowest acceptable version (optional)
• too_big string lowest version that is too big (optional)
• pattern string to match version in module.version or module._VERSION(default: '([%.%d]+)%D*$') (optional)

Usage:

-- posix.version == 'posix library for Lua 5.2 / 32'
posix = require('posix', '29')

Iterator Functions

elems (t)

An iterator over all values of a table. If t has a __pairs metamethod, use that to iterate.

Parameters:

• t table a table

Returns:

1. function iterator function
2. table t, the table being iterated over
3. key, the previous iteration key

See also:

• ielems
• pairs

Usage:

--> foo
--> bar
--> baz
--> 5
std.functional.map(print, std.ielems, {'foo', 'bar', [4]='baz', d=5})

ielems (t)

An iterator over the integer keyed elements of a table.

If t has a __len metamethod, iterate up to the index it returns, otherwise up to the first nil.

This function does not support the Lua 5.2 __ipairs metamethod.

Parameters:

• t table a table

Returns:

1. function iterator function
2. table t, the table being iterated over
3. int index, the previous iteration index

See also:

• elems
• ipairs

Usage:

--> foo
--> bar
std.functional.map(print, std.ielems, {'foo', 'bar', [4]='baz', d=5})

ipairs (t)

An iterator over integer keyed pairs of a sequence.

Like Lua 5.1 and 5.3, this iterator returns successive key-value pairs with integer keys starting at 1, up to the first nil valued pair.

If there is a _len metamethod, keep iterating up to and including that element, regardless of any intervening nil values.

This function does not support the Lua 5.2 __ipairs metamethod.

Parameters:

• t table a table

Returns:

1. function iterator function
2. table t, the table being iterated over
3. int index, the previous iteration index

See also:

• ielems
• npairs
• pairs

Usage:

--> 1	foo
--> 2	bar
std.functional.map(print, std.ipairs, {'foo', 'bar', [4]='baz', d=5})

npairs (t)

Ordered iterator for integer keyed values. Like ipairs, but does not stop until the __len or maxn of t.

Parameters:

• t table a table

Returns:

1. function iterator function
2. table t

See also:

• ipairs
• rnpairs

Usage:

--> 1	foo
--> 2	bar
--> 3	nil
--> 4	baz
std.functional.map(print, std.npairs, {'foo', 'bar', [4]='baz', d=5})

pairs (t)

Enhance core pairs to respect __pairs even in Lua 5.1.

Parameters:

• t table a table

Returns:

1. function iterator function
2. table t, the table being iterated over
3. key, the previous iteration key

See also:

• elems
• ipairs

Usage:

--> 1	foo
--> 2	bar
--> 4	baz
--> d	5
std.functional.map(print, std.pairs, {'foo', 'bar', [4]='baz', d=5})

ripairs (t)

An iterator like ipairs, but in reverse. Apart from the order of the elements returned, this function follows the same rules as ipairs for determining first and last elements.

Parameters:

• t table any table

Returns:

1. function iterator function
2. table t
3. number #t + 1

See also:

• ipairs
• rnpairs

Usage:

--> 2	bar
--> 1	foo
std.functional.map(print, std.ripairs, {'foo', 'bar', [4]='baz', d=5})

rnpairs (t)

An iterator like npairs, but in reverse. Apart from the order of the elements returned, this function follows the same rules as npairs for determining first and last elements.

Parameters:

• t table a table

Returns:

1. function iterator function
2. table t

See also:

• npairs
• ripairs

Usage:

--> 4	baz
--> 3	nil
--> 2	bar
--> 1	foo
std.functional.map(print, std.rnpairs, {'foo', 'bar', [4]='baz', d=5})

Deprecated Functions

barrel ([namespace=_G])

A barrel of monkey_patches.

Apply all monkey_patch functions. Additionally, for backwards compatibility only, write a selection of sub-module functions into the given namespace.

Parameters:

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

Returns:

table module table

Usage:

local std = require 'std'.barrel()

ireverse (t)

Return a new table with element order reversed. Apart from the order of the elements returned, this function follows the same rules as ipairs for determining first and last elements.

Parameters:

• t table a table

Returns:

table

a new table with integer keyed elements in reverse

order with respect to *t*

Usage:

local rielems = std.functional.compose(std.ireverse, std.ielems)
for e in rielems(l) do process(e) end

monkey_patch ([namespace=_G])

Overwrite core methods with std enhanced versions.

Write all functions from this module, except std.barrel and std.monkey_patch, into the given namespace.

Parameters:

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

Returns:

table the module table

Usage:

require 'std'.monkey_patch()

tostring (x)

Enhance core tostring to render table contents as a string.

Parameters:

• x object to convert to string

Returns:

string compact string rendering of x

Usage:

-- {1=baz,foo=bar}
print(std.tostring {foo='bar', 'baz'})

Metamethods

__index (name)

Lazy loading of stdlib modules. Don't load everything on initial startup, wait until first attempt to access a submodule, and then load it on demand.

Parameters:

• name string submodule name

Returns:

table or nil

the submodule that was loaded to satisfy the missing

`name`, otherwise `nil` if nothing was found

Usage:

local std = require 'std'
local Object = std.object