# Module `std`

Lua Standard Libraries.

This module contains a selection of improved Lua core functions, among others.

Also, after requiring this module, simply referencing symbols in the submodule hierarchy will load the necessary modules on demand.

By default there are no changes to any global symbols, or monkey patching of core module tables and metatables. However, sometimes it's still convenient to do that: For example, when using stdlib from the REPL, or in a prototype where you want to throw caution to the wind and compatibility with other modules be damned. In that case, you can give `stdlib` permission to scribble all over your namespaces by using the various `monkey_patch` calls in the library.

## Functions

assert (expect[, f=""[, ...]]) | Enhance core `assert` to also allow formatted arguments.
barrel ([namespace=_G]) | A barrel of monkey_patches.
elems (t) | An iterator over all elements of a sequence.
eval (s) | Evaluate a string as Lua code.
getmetamethod (x, n) | Return named metamethod, if any, otherwise `nil`.
ielems (t) | An iterator over the integer keyed elements of a sequence.
ipairs (t) | An iterator over elements of a sequence, until the first `nil` value.
ireverse (t) | Return a new table with element order reversed.
monkey_patch ([namespace=_G]) | Overwrite core methods and metamethods with `std` enhanced versions.
npairs (t) | Ordered iterator for integer keyed values.
pairs (t) | Enhance core `pairs` to respect `__pairs` even in Lua 5.1.
require (module[, min[, too_big[, pattern]]]) | Enhance core `require` to assert version number compatibility.
ripairs (t) | An iterator like ipairs, but in reverse.
rnpairs (t) | An iterator like npairs, but in reverse.
tostring (x) | Enhance core `tostring` to render table contents as a string.

## Tables

std | Module table.

## Metamethods

__index (name) | Lazy loading of stdlib modules.

## Functions

Methods

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 (expected ~= nil, "100% unexpected!")
       std.assert (expected ~= nil, "%s unexpected!", expected)

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

elems (t)
  An iterator over all elements of a sequence. 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:

      for value in std.elems {a = 1, b = 2, c = 5} do process (value) end

eval (s)
  Evaluate a string as Lua code.

  ### Parameters:

  - s string string of Lua code

  ### Returns:

  result of evaluating `s`

  ### Usage:

      std.eval "math.min (2, 10)"

getmetamethod (x, n)
  Return named metamethod, if any, otherwise `nil`.

  ### Parameters:

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

  ### Returns:

  function or nil metamethod function, or `nil` if no metamethod

  ### Usage:

      lookup = std.getmetamethod (require "std.object", "__index")

ielems (t)
  An iterator over the integer keyed elements of a sequence. If t has a `__len` metamethod, iterate up to the index it returns.

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

      for v in std.ielems {"a", "b", "c"} do process (v) end

ipairs (t)
  An iterator over elements of a sequence, until the first `nil` value.

  Like Lua 5.1 and 5.3, but unlike Lua 5.2 (which looks for and uses the `__ipairs` metamethod), this iterator returns successive key-value pairs with integer keys starting at 1, up to the first `nil` valued pair.

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

       -- length of sequence
       args = {"first", "second", nil, "last"}
       --> 1=first
       --> 2=second
       for i, v in std.ipairs (args) do
         print (string.format ("%d=%s", i, v))
       end

ireverse (t)
  Return a new table with element order reversed. Apart from the order of the elments 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

  ### See also:

  - ielems
  - ipairs

  ### 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 and metamethods 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:

      local std = require "std".monkey_patch ()

npairs (t)
  Ordered iterator for integer keyed values. Like ipairs, but does not stop until the largest integer key.

  ### Parameters:

  - t table a table

  ### Returns:

  1. function iterator function
  2. table t

  ### See also:

  - ipairs
  - rnpairs

  ### Usage:

      for i,v in npairs {"one", nil, "three"} do ... end

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:

      for k, v in pairs {"a", b = "c", foo = 42} do process (k, v) end

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

ripairs (t)
  An iterator like ipairs, but in reverse. Apart from the order of the elments 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:

      for i, v = ripairs (t) do ... end

rnpairs (t)
  An iterator like npairs, but in reverse. Apart from the order of the elments 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:

      for i,v in rnpairs {"one", nil, "three"} do ... end

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

## Tables

std
  Module table.

  In addition to the functions documented on this page, and a `version` field, references to other submodule functions will be loaded on demand.

  ### Fields:

  - version release version string

## 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 prototype = std.object.prototype

generated by LDoc 1.4.3 Last updated 2018-09-03 17:48:42