Lua Reference Manual Comments

wiki

There are some similar pages in the LuaTutorial, but this page is not intended as a tutorial, and some content in those similar pages are not necessarily organized in tutorial format and might be more appropriate here. This page is similar in nature and purpose to the user comments in the the MySQL reference [3].

2 - The Language

2.4.5 - For Statement

The apparent list of values in a numeric for statement is not actually a list, and the last value gets truncated. So, you can't say for i = f(x) do ... end where f(x) returns 2, 4, 1. This is unlike the non-numeric for, where it doesn't get truncated. (Noted by RiciLake)

2.8 - Metatables

Some metamethods are not listed here. These include __gc, __mode, and __metatable.

Note that __tostring is called only by tostring and not during automatic conversion to string. __gc is called only on full userdatas (which is one reason RAII on objects implemented in Lua won't work). (There's a useful chart on p. 268 of Beginning Lua Programming showing when certain metamethods are applicable.)

3 - The Application Program Interface

lua_getfenv

The "index" refers to the index on the stack, not the stack level (as is the case with getfenv). At least two users have noted this as unclear in the reference manual. You can obtain the function at the given stack level using lua_getinfo with "f".

luaL_dostring

By implication...On error, pushes error onto stack and returns error code (LUA_ERRSYNTAX or LUA_ERRMEM). On success, returns 0 and pushes function return values onto stack.

If you don't want the return values to accumulate on the stack, use this:

(luaL_loadstring(L, str) || lua_pcall(L, 0, 0, 0))

luaL_loadfile

By implication...On error, pushes error onto stack and returns error code (LUA_ERRSYNTAX, LUA_ERRMEM, or LUA_ERRFILE). On success, returns 0 and pushes function return values onto stack.

If you don't want the return values to accumulate on the stack, use this:

(luaL_loadfile(L, filename) || lua_pcall(L, 0, 0, 0))

luaL_register

It's undocumented that this function does call metamethods on inserting into table.

5 - Standard Libraries

After "Currently, Lua has the following standard libraries", it should list "coroutine manipulation."

5.1 - Basic Functions

ipairs

See GeneralizedPairsAndIpairs for a reimplementation that invokes metamethods.

next

See GeneralizedPairsAndIpairs for a reimplementation that invokes metamethods.

pairs

See GeneralizedPairsAndIpairs for a reimplementation that invokes metamethods.

select

Though not stated, a negative index passed to select indicates an offset relative to the end of .... An out-of-range index raises an error. This is clearly an intentional behavior as seen in luaB_select. It is demonstrated in the below test suite:

function test(...) return select(-1, ...) end
function test2(...) return select(-2, ...) end

assert(not pcall(function() assert(test() == nil) end))
assert(test(1) == 1)
assert(test(1,2) == 2)
assert(test(1,2,3) == 3)

local a,b,c = test2(1,2)
assert(a == 1 and b == 2 and c == nil)
local a,b,c = test2(1,2,3)
assert(a == 2 and b == 3 and c == nil)

xpcall

Why does xpcall not accept function arguments as does pcall? Below code was suggested by RiciLake.

/** better_xpcall(errfunc, func, ...) */
static int l_better_xpcall (lua_State *L) {
  luaL_checktype(L, 1, LUA_TFUNCTION);
  luaL_checkany(L, 2);
  lua_pushboolean(L, 0 == lua_pcall(L, lua_gettop(L)-2, LUA_MULTRET, 1));
  lua_replace(L, 1);
  return lua_gettop(L);
}

Note that errfunc and func arguments are switched compared to the standard xpcall. Below code by Sergey Rozhenko is compatible with the standard xpcall.

static int luaMy_xpcall (lua_State *L) {
  luaL_checktype(L, 2, LUA_TFUNCTION);

  // switch function & error function
  lua_pushvalue(L, 1);
  lua_pushvalue(L, 2);
  lua_replace(L, 1);
  lua_replace(L, 2);

  // call
  lua_pushboolean(L, 0 == lua_pcall(L, lua_gettop(L) - 2, LUA_MULTRET, 1));
  lua_replace(L, 1);
  return lua_gettop(L);
}

5.2 - Coroutine Manipulation

See also "Chapter 9: Handling Events Naturally with Coroutines" and "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming, "Chapter 9: Coroutines" in Programming in Lua, Second Edition [4], or CoroutinesTutorial.

5.3 - Modules

See also "Chapter 7: Using Modules" and "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming, "Chapter 15: Modules and Packages" in Programming in Lua, Second Edition [4], or ModulesTutorial.

5.4 - String Manipulation

The g in gmatch and gsub apparently stands for "global", meaning all matches are processed, not just the first one (Beginning Lua Programming, p.186). It's possibly inspired by Perl's /g "match globally" modifier [5].

The name gsub was taken from AWK, way back in Lua 2.5. --lhf

See also "Chapter 5: Using Strings" and "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming, "Chapter 20: The String Library" in Programming in Lua, Second Edition [4], or LuaTypesTutorial + StringsTutorial + StringLibraryTutorial.

string.dump

Beginning Lua Programming (p.302) notes that an undocumented (subject to change) behavior of string.dump: "a function with upvalues may be dumped, but in the dumped version, all the upvalues will be private to the function (even if the original shared them with another function) and they'll be nil until assigned to from within the function. (In Lua 5.0, string.dump triggered an error if given a function with upvalues.)"

5.5 - Table Manipulation

See also "Chapter 4: Working with Tables" and "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming, "Chapter 19: The Table Library" in Programming in Lua, Second Edition [4], or TableLibraryTutorial.

5.6 - Mathematical Functions

See also "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming, "Chapter 18: The Mathematical Library" in Programming in Lua, Second Edition [4], or MathLibraryTutorial.

math.atan2

[6] [7]

5.7 - Input and Output Facilities

See also "Chapter 5: Using Strings" and "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming or "Chapter 21: The I/O Library" in Programming in Lua, Second Edition [4].

file:close

See also the corresponding C fclose function [8].

file:flush

See also the corresponding C fflush function [9].

file:read

.

file:seek

See also the corresponding C fseek function [10].

file:setvbuf

See also the corresponding C setvfbuf function [11].

file:write

.

io.open

See also the corresponding C fopen function [12]. That helps on modes.

io.read

The text could more precisely say "Equivalent to io.input():read(...)" (instead of "io.input():read" -- see also io.write).

io.write

The text could more precisely say "Equivalent to io.input():write(...)" (instead of "io.input():write" -- see also io.read).

5.8 - Operating System Facilities

See also "Chapter 11: Exploring Lua's Libraries" and "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming, "Chapter 22: The Operating System Library" in Programming in Lua, Second Edition [4], and the OsLibraryTutorial.

os.clock

See also the corresponding C clock function [13].

os.date

See also the corresponding C date function [14].

For a portable os.date("%z") replacement, see TimeZone.

os.difftime

See also the corresponding C difftime function [15].

os.execute

See also the corresponding C system function [16]

In Windows, you can run a non-blocking process via os.execute by prefixing the command with "start ". On UNIX-like operating systems, you can postfix it with "&". Both methods of course are non-portable. Example:

os.execute("start notepad")  -- Windows
os.execute("emacs &")  -- UNIX

os.exit

See also the corresponding C exit function [17].

os.getenv

See also the corresponding C getenv function [18].

The Lua standard library does not provide access to the C setenv function defined by POSIX, because it isn't defined in ASCI C.

os.remove

See also the corresponding C remove function [19].

os.rename

See also the corresponding C rename function [20].

os.setlocale

See also the corresponding C setlocale function [21] and Wikipedia:Locale [22].

Various functions and operations are affected by the current locale. These include: os.date, string.lower, string.upper, string comparison, and pattern matching.

os.time

See also the corresponding C time function [23].

os.tmpname

See also the corresponding C tmpnam function [24].

5.9 - The Debug Library

See also "Chapter 11: Exploring Lua's Libraries" in Beginning Lua Programming or "Chapter 23: The Debug Library" in Programming in Lua, Second Edition[4].

debug.getfenv

Note: the getfenv function is not identical to debug.getfenv.

debug.getlocal

Related notes: LuaList:2007-01/msg00214.html.

Examples: StringInterpolation.

debug.getmetatable

This function is like getmetatable except it ignores the __metatable metafunction when retrieving the metatable. This function might alternately be called rawgetmetatable. Since some objects may have the __metatable metafunction set for security (to prevent the client gaining access to the metatable) you might want to prevent access to debug.getmetatable.

debug.setmetatable

This function is like setmetatable except it can work on objects other than tables. You can even use it on nil.

Undocumented note: The function returns true on success or false on failure, though currently is seems to always return true. (Caution: Undocumented behavior is subject to change in the future.)

7 - Incompatibilities with the Previous Version

See also MigratingToFiveOne, LuaFiveFeatures, and LuaFiveAlphaToBeta.

8 - The Complete Syntax of Lua

See also LuaGrammar.

Additional Author Notes and User Comments

I think the "3. The Application Program Interface" chapter would be better placed near the end so that people who only use Lua via the Lua language rather than C (which would include most users) would not need to bother as much with it. This is a more advanced topic. --DavidManura

Alternative Browser for the 5.1 Manual: I dislike the way the Lua manual is all in one page, and made a little browser / searcher for myself which I use all the time and would like to share with others: [Luai] --McFin

The above page was reviewed against the 5.1.3 reference manual. --DavidManura