Penlight Documentation

# Module `pl.compat`

Lua 5.1/5.2/5.3 compatibility.

Injects table.pack, table.unpack, and package.searchpath in the global environment, to make sure they are available for Lua 5.1 and LuaJIT.

All other functions are exported as usual in the returned module table.

NOTE: everything in this module is also available in pl.utils.

## Functions

execute (cmd) | execute a shell command, in a compatible and platform independent way.
load (ld[, source[, mode[, env]]]) | Load Lua code as a text or binary chunk (in a Lua 5.2 compatible way).
getfenv (f) | Get environment of a function (in a Lua 5.1 compatible way).
setfenv (f, env) | Set environment of a function (in a Lua 5.1 compatible way).

## Fields

lua51 | boolean flag this is Lua 5.1 (or LuaJIT).
jit | boolean flag this is LuaJIT.
jit52 | boolean flag this is LuaJIT with 5.2 compatibility compiled in.
dir_separator | the directory separator character for the current platform.
is_windows | boolean flag this is a Windows platform.

## Global exported functions (for Lua 5.1 & LuaJIT)

table.pack (...) | pack an argument list into a table.
table.unpack (t[, i[, j]]) | unpack a table and return the elements.
package.searchpath (name, path[, sep[, rep]]) | return the full path where a file name would be matched.

## Global exported functions (for Lua < 5.4)

warn (...) | raise a warning message.

## Functions

execute (cmd)
  execute a shell command, in a compatible and platform independent way. This is a compatibility function that returns the same for Lua 5.1 and Lua 5.2+.

  NOTE: Windows systems can use signed 32bit integer exitcodes. Posix systems only use exitcodes 0-255, anything else is undefined.

  NOTE2: In Lua 5.2 and 5.3 a Windows exitcode of -1 would not properly be returned, this function will return it properly for all versions.

  ### Parameters:

  - cmd a shell command

  ### Returns:

  1. true if successful
  2. actual return code
load (ld[, source[, mode[, env]]])
  Load Lua code as a text or binary chunk (in a Lua 5.2 compatible way).

  ### Parameters:

  - ld code string or loader
  - source name of chunk for errors (optional)
  - mode 'b', 't' or 'bt' (optional)
  - env environment to load the chunk in (optional)
getfenv (f)
  Get environment of a function (in a Lua 5.1 compatible way). Not 100% compatible, so with Lua 5.2 it may return nil for a function with no global references! Based on code by Sergey Rozhenko

  ### Parameters:

  - f a function or a call stack reference
setfenv (f, env)
  Set environment of a function (in a Lua 5.1 compatible way).

  ### Parameters:

  - f a function or a call stack reference
  - env a table that becomes the new environment of `f`

## Fields

lua51
  boolean flag this is Lua 5.1 (or LuaJIT).
  - lua51
jit
  boolean flag this is LuaJIT.
  - jit
jit52
  boolean flag this is LuaJIT with 5.2 compatibility compiled in.
  - jit52
dir_separator
  the directory separator character for the current platform.
  - dir_separator
is_windows
  boolean flag this is a Windows platform.
  - is_windows

## Global exported functions (for Lua 5.1 & LuaJIT)

table.pack (...)
  pack an argument list into a table.

  ### Parameters:

  - ... any arguments

  ### Returns:

  a table with field n set to the length
table.unpack (t[, i[, j]])
  unpack a table and return the elements.

  NOTE: this version does NOT honor the n field, and hence it is not nil-safe. See utils.unpack for a version that is nil-safe.

  ### Parameters:

  - t table to unpack
  - i index from which to start unpacking, defaults to 1 (optional)
  - j index of the last element to unpack, defaults to #t (optional)

  ### Returns:

  multiple return values from the table

  ### See also:

  utils.unpack
package.searchpath (name, path[, sep[, rep]])
  return the full path where a file name would be matched. This function was introduced in Lua 5.2, so this compatibility version will be injected in Lua 5.1 engines.

  ### Parameters:

  - name string file name, possibly dotted
  - path string a path-template in the same form as package.path or package.cpath
  - sep string template separate character to be replaced by path separator. Default: "." (optional)
  - rep string the path separator to use, defaults to system separator. Default; "/" on Unixes, "\" on Windows. (optional)

  ### Returns:

  1. on success: path of the file
  2. on failure: nil, error string listing paths tried

  ### See also:

  path.package_path

## Global exported functions (for Lua < 5.4)

warn (...)
  raise a warning message. This functions mimics the warn function added in Lua 5.4.

  ### Parameters:

  - ... any arguments

generated by LDoc 1.5.0