Module std.normalize

Normalize API differences between supported Lua implementations.

Respecting the values set in the std.debug_init module and the _G._DEBUG variable, inject deterministic identically behaving cross-implementation low-level functions into the callers environment.

Writing Lua libraries that target several Lua implementations can be a frustrating exercise in working around lots of small differences in APIs and semantics they share (or rename, or omit). normalize provides the means to simply access deterministic implementations of those APIs that have the the same semantics across all supported host Lua implementations. Each function is as thin and fast an implementation as is possible within that host Lua environment, evaluating to the Lua C implmentation with no overhead where host semantics allow.

The core of this module is to transparently set the environment up with a single API (as opposed to requiring caching functions from a module table into module locals):

local _ENV = require "std.normalize" {
  "package",
  "std.prototype",
  strict = "std.strict",
}

It is not yet complete, and in contrast to the kepler project lua-compat libraries, neither does it attempt to provide you with as nearly compatible an API as is possible relative to some specific Lua implementation - rather it provides a variation of the "lowest common denominator" that can be implemented relatively efficiently in the supported Lua implementations, all in pure Lua.

At the moment, only the functionality used by stdlib is implemented.

Functions

argerror (name, i[, extramsg[, level=1]]) Raise a bad argument error.
getfenv (fn) Get a function or functor environment.
getmetamethod (x, n) Return named metamethod, if callable, otherwise nil.
ipairs (t) Iterate over elements of a sequence, until the first nil value.
len (x) Deterministic, functional version of core Lua # operator.
load (ld, source) Load a string or a function, just like Lua 5.2+.
math.tointeger (x) Convert to an integer and return if possible, otherwise nil.
math.type (x) Return "integer", "float" or nil according to argument type.
opairs (t) Ordered pairs iterator, respecting __pairs metamethod.
os.exit (status) Exit the program.
pack (...) Return a list of given arguments, with field n set to the length.
package.searchpath (name, path[, sep="."[, rep=`package.dirsep`]]) Searches for a named file in a given path.
pairs (t) Like Lua pairs iterator, but respect __pairs even in Lua 5.1.
rawlen (x) Length of a string or table object without using any metamethod.
setfenv (fn, env) Set a function or functor environment.
str (x) Return a compact stringified representation of argument.
unpack (t[, i=1[, j=len(t)]]) Either table.unpack in newer-, or unpack in older Lua implementations.
xpcall (f, errh, ...) Support arguments to a protected function call, even on Lua 5.1.

Tables

package Package module constants for package.config substrings.

Metamethods

__call (env[, level=1]) Normalize caller's lexical environment.
__index (name) Lazy loading of normalize modules.


Functions

argerror (name, i[, extramsg[, level=1]])
Raise a bad argument error. Equivalent to luaL_argerror in the Lua C API. This function does not return. The level argument behaves just like the core error function.

Parameters:

  • name string function to callout in error message
  • i int argument number
  • extramsg string additional text to append to message inside parentheses (optional)
  • level int call stack level to blame for the error (default 1)

Usage:

       local function slurp (file)
     local h, err = input_handle (file)
     if h == nil then argerror ("std.io.slurp", 1, err, 2) end
     ...
getfenv (fn)
Get a function or functor environment.

This version of getfenv works on all supported Lua versions, and knows how to unwrap functors (table's with a function valued __call metamethod).

Parameters:

  • fn function or int stack level, C or Lua function or functor to act on

Returns:

    table the execution environment of fn

Usage:

    callers_environment = getfenv (1)
getmetamethod (x, n)
Return named metamethod, if callable, otherwise nil.

Parameters:

  • x item to act on
  • n string name of metamethod to look up

Returns:

    function or nil metamethod function, or nil if no metamethod

Usage:

    normalize = getmetamethod (require "std.normalize", "__call")
ipairs (t)
Iterate over elements of a sequence, until the first nil value.

Returns successive key-value pairs with integer keys starting at 1, up to the last non-nil value. Unlike Lua 5.2+, any __ipairs metamethod is ignored! Unlike Lua 5.1, any __index metamethod is respected.

Parameters:

  • t table table to iterate on

Returns:

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

Usage:

       -- length of sequence
   args = {"first", "second", nil, "last"}
   --> 1=first
   --> 2=second
   for i, v in ipairs (args) do
     print (string.format ("%d=%s", i, v))
   end
len (x)
Deterministic, functional version of core Lua # operator.

Respects __len metamethod (like Lua 5.2+), or else if there is a __tostring metamethod return the length of the string it returns. Otherwise, always return one less than the lowest integer index with a nil value in x, where the # operator implementation might return the size of the array part of a table.

Parameters:

  • x item to act on

Returns:

    int the length of x

Usage:

       x = {1, 2, 3, nil, 5}
   --> 5	3
   print (#x, len (x))
load (ld, source)
Load a string or a function, just like Lua 5.2+.

Parameters:

  • ld string or function chunk to load
  • source string name of the source of ld

Returns:

    function a Lua function to execute ld in global scope.

Usage:

    assert (load 'print "woo"') ()
math.tointeger (x)
Convert to an integer and return if possible, otherwise nil.

Parameters:

  • x object to act on

Returns:

    integer x converted to an integer if possible

Or

    nil otherwise
math.type (x)
Return "integer", "float" or nil according to argument type.

To ensure the same behaviour on all host Lua implementations, this function returns "float" for integer-equivalent floating values, even on Lua 5.3.

Parameters:

  • x object to act on

Returns:

    string "integer", if x is a whole number

Or

    string "float", for other numbers

Or

    nil otherwise
opairs (t)
Ordered pairs iterator, respecting __pairs metamethod.

Although __pairs will be used to collect results, opairs always returns them in the same order as str.

Parameters:

  • t table table to act on

Returns:

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

Usage:

       --> 1        b
   --> 2        a
   --> foo      c
   for k, v in opairs {"b", foo = "c", "a"} do print (k, v) end
os.exit (status)
Exit the program.

Parameters:

  • status bool or number[opt=true] report back to parent process

Usage:

    exit (len (records.processed) > 0)
pack (...)
Return a list of given arguments, with field n set to the length.

Parameters:

  • ... tuple to act on

Returns:

    table packed list of ... values, with field n set to number of tuple elements (including any explicit nil elements)

See also:

Usage:

       --> {1, 2, "ax", n = 3}
   pack (("ax1"):find "(%D+)")
package.searchpath (name, path[, sep="."[, rep=`package.dirsep`]])
Searches for a named file in a given path.

For each package.pathsep delimited template in the given path, search for an readable file made by first substituting for sep with package.dirsep, and then replacing any package.pathmark with the result. The first such file, if any is returned.

Parameters:

  • name string name of search file
  • path string package.pathsep delimited list of full path templates
  • sep string name component separator (default ".")
  • rep string sep replacement in template (default `package.dirsep`)

Returns:

    string first template substitution that names a file that can be opened in read mode

Or

  1. nil
  2. string error message listing all failed paths
pairs (t)
Like Lua pairs iterator, but respect __pairs even in Lua 5.1.

Parameters:

  • t table table to act on

Returns:

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

Usage:

    for k, v in pairs {"a", b = "c", foo = 42} do process (k, v) end
rawlen (x)
Length of a string or table object without using any metamethod.

Parameters:

Returns:

    int raw length of x

Usage:

       --> 0
   rawlen (setmetatable ({}, {__len = function () return 42}))
setfenv (fn, env)
Set a function or functor environment.

This version of setfenv works on all supported Lua versions, and knows how to unwrap functors.

Parameters:

  • fn function or int stack level, C or Lua function or functor to act on
  • env table new execution environment for fn

Returns:

    function function acted upon

Usage:

    function clearenv (fn) return setfenv (fn, {}) end
str (x)
Return a compact stringified representation of argument.

Parameters:

  • x item to act on

Returns:

    string compact string representing x

Usage:

       -- {baz,5,foo=bar}
   print (str {foo="bar","baz", 5})
unpack (t[, i=1[, j=len(t)]])
Either table.unpack in newer-, or unpack in older Lua implementations.

Parameters:

  • t table table to act on
  • i int first index to unpack (default 1)
  • j int last index to unpack (default len(t))

Returns:

    ... values of numeric indices of t

See also:

Usage:

    return unpack (results_table)
xpcall (f, errh, ...)
Support arguments to a protected function call, even on Lua 5.1.

Parameters:

  • f function protect this function call
  • errh function error object handler callback if f raises an error
  • ... arguments to pass to f

Returns:

    ... all return values from f follow

Or

  1. boolean false when f (...) raised an error
  2. string error message

Or

    boolean true when f (...) succeeded

Usage:

       -- Use errh to get a backtrack after curses exits abnormally
   xpcall (main, errh, arg, opt)

Tables

package
Package module constants for package.config substrings.

Fields:

  • dirsep string directory separator in path elements
  • execdir string replaced by the executable's directory in a path
  • igmark string ignore everything before this when building luaopen_ function name
  • pathmark string mark substitution points in a path template
  • pathsep string element separator in a path template

Metamethods

__call (env[, level=1])

Normalize caller's lexical environment.

Using "std.strict" when available and selected, otherwise a (Lua 5.1 compatible) function to set the given environment.

With an empty table argument, the core (not-table) normalize functions are loaded into the callers environment. For consistent behaviour between supported host Lua implementations, the result must always be assigned back to _ENV. Additional core modules must be named to be loaded at all (i.e. no "debug" table unless it is explicitly listed in the argument table).

Additionally, external modules are loaded using require, with . separators in the module name translated to nested tables in the module environment. For example "std.prototype" in the usage below is equivalent to:

 local std = { prototype = require "std.prototype" }

And finally, you can assign a loaded module to a specific symbol with key=value syntax. For example "std.strict" in the usage below is equivalent to:

 local strict = require "std.strict"

Parameters:

  • env table environment table
  • level int stack level for setfenv, 1 means set caller's environment (default 1)

Returns:

    table env with this module's functions merge id. Assign back to _ENV

Usage:

       local _ENV = require "std.normalize" {
     "string",
     "std.prototype",
     strict = "std.strict",
   }
__index (name)
Lazy loading of normalize modules. Don't load everything on initial startup, wait until first attempt to access a submodule, and then load it on demand.

Parameters:

Returns:

    table or nil the submodule that was loaded to satisfy the missing name, otherwise nil if nothing was found

Usage:

    local version = require "std.normalize".version
generated by LDoc 1.4.3 Last updated 2016-05-28 16:24:36