LIMITATIONS

LIMITATIONS
===========

We list here functionality from Lua 5.2 that has not been backported, and a few
cases where functionality from Lua 5.1 has not been forward-ported.

Where `[patch]` is indicated, patches exist to incorporate some or all of Lua
5.2's behavior into a custom compile of Lua 5.1. See the accompanying
patches/README for more information.


Differences affecting only the Lua API
--------------------------------------

    1.  os.exit honors optional `close` argument [patch]
        this will call lua_close before exiting, so finalizers will run.
        The Lua interpreter already calls lua_close when exiting normally,
        but other applications embedding Lua may not; and you may want this
        behavior when using os.exit (to force non-zero exit statuses).

    2.  Lua interpreter honors __tostring on error objects [patch]

    3.  string.format's "%s" applies tostring() [patch], and "%q" now also
        escapes control chars

    4.  5.2 accepts hex float literals, and "%a" and "%A" options to
        string.format

    5.  5.2 permits "\xff" escapes in strings
        5.1 merely permits "\255"

    6.  in 5.2 only, "\z" skips any following whitespace in strings
        "\" followed by newline inserts a literal newline, which otherwise
        gives syntax error for unterminated string

    7.  in 5.2 only, patterns may contain "\0"
        "%z" is deprecated but still works

    8.  new pattern "%g" matches all printable chars except space
        like POSIX's [:graph:]

    9.  in 5.2 only, string.gsub complains if replacement has %c
        where c not in [%0-9]

   10.  in 5.2 only, os.date complains if format string is invalid

   11.  in 5.2, can print "\0" [patch]
        io.write does this in both versions

   12.  in 5.2 only, the Lua interpreter accepts a -E option to ignore
        LUA_INIT, LUA_PATH, LUA_CPATH, and so on

   13.  empty statements (;;)

   14.  ::labels:: and gotos
        can jump to any visible label that doesn't involve entering a local
        variable's scope

   15.  in 5.2 only, breaks can appear mid-block
        so too can gotos, but not returns

   16.  in 5.2, debug.getupvalue and debug.setupvalue also have access to
        upvalues of C functions

   17.  in 5.2, coroutines can have C functions as their entry point:
        for example: coroutine.wrap(print)(...)

   18.  in 5.2, package.loadlib(path, openfuncname) restricts itself to only
        linking when `openfuncname` is "*"



Differences affecting only the C API
------------------------------------

Some of Lua's API functions have a different signature in 5.2; if your code
depends on the differences you'll need to add conditional compilation
directives like:

        #if LUA_VERSION_NUM == 501
        ...
        #elif LUA_VERSION_NUM == 502
        ...
        #endif

These functions include:

   19.  all three of:

        *   the macro lua_pushliteral(L, "string")
        *   lua_pushstring(L, nulterminated_string)
        *   lua_pushlstring(L, string, len)

        In Lua 5.2 these return a const char *, pointing to Lua's internal
        copy of the string, instead of void
        lua_pushfstring always behaved this way

   20.  int lua_resume(L, lua_State *from, int narg) expects an addtional `from`
        parameter in 5.2, which should be NULL or the thread doing the
        call

   21.  lua_load expects an additional `mode` parameter, which can be any of
        "t", "b", "bt" or NULL (which is treated as "bt")
        Pass "t" to disable loading of bytecode; or NULL for the old behavior.

        Also, only in 5.2, single upvalues are assigned the value of
        registry[LUA_RIDX_GLOBALS].

Other differences are:

   22.  lua_version and luaL_checkversion have not been backported.

   23.  the new-style handling of luaL_Buffer has not been backported, and
        luaL_prepbuffsize and luaL_buffinitsize are not present.

   24.  bool lua_checkstack(L, addl) never raises error in 5.2;
        also, void luaL_checkstack(L, addl, "message") now permits NULL message

   25.  luaL_execresult and luaL_fileresult are implemented and used in
        src/io.c, but aren't exposed in fiveq.h.

   26.  in 5.2 only, lua_pushfstring raises errors about invalid format strings.

   27.  lua_getfenv and lua_setfenv are not available in 5.2. However,
        some of their functionality is replaced by lua_getuservalue and
        lua_setuservalue. And when LUA_FIVEQ_PLUS is defined, we also export:

            extern void luaQ_getfenv(lua_State *L, int level, const char *fname);
            extern void luaQ_setfenv(lua_State *L, int level, const char *fname);

        which provide a different part of the functionality; see the BENEFITS-C
        file.

   28.  LUA_ENVIRONINDEX and LUA_GLOBALSINDEX are not available in 5.2.

        LUA_RIDX_MAINTHREAD and LUA_RIDX_GLOBALS *are* backported to Lua 5.1,
        but with the following differences:

        * These macros expand to different literal values.

        * If fiveq isn't first required from the main thread, LUA_RIDX_MAINTHREAD
          won't be set (there's no error, this step is just silently omitted).

        * In 5.1, one can reassign a thread's environment, and that
          affects subsequent use of LUA_GLOBALSINDEX. However, any such
          reassignments aren't propagated to the registry. Unless you manually
          change it, registry[LUA_RIDX_GLOBALS] will always
          hold what was the global thread table when fiveq was required.

        * In 5.2 only, the current value of registry[LUA_RIDX_GLOBALS] is assigned
          as the upvalue of any loaded chunks (which serves as their initial _ENV)
          In 5.1, the current thread's global env, which may have been reassigned,
          is used instead.


Differences affecting both Lua and C
------------------------------------

   29.  in 5.2, lua_pushcclosure(L, f, 0) (and so too lua_pushcfunction and
        lua_register) create light C functions. These behave like light
        userdata with respect to equality and weak tables.

        These still satisfy lua_iscfunction and have a lua_type of
        LUA_TFUNCTION.

   30.  in 5.2, weak-keyed tables are ephemerons

   31.  5.2 has emergency garbage collection [patch]

   32.  in 5.2, the Lua function collectgarbage also accepts "isrunning",
        "generational", and "incremental" commands; and the "count" command
        returns two values Similarly, the C function lua_gc also accepts
        LUA_GCISRUNNING, LUA_GCGEN and LUA_GCINC.

   33.  Requesting a GC step or collection won't restart a stopped GC.

   34.  in 5.2, some __gc element needs to be present in a metatable-to-be
        *before* calling lua_setmetatable/luaL_setmetatable (or in Lua,
        setmetatable/debug.setmetatable), else no finalizer will be called
        on that object. Afterwards, any *changes* to the __gc element are
        honored.

        The version of newproxy we provide in 5.2 fiveq (and also in 5.1
        fiveqplus) will accept a initial __gc argument.

        In 5.2, finalizers are called in the reverse order their objects were
        seen to have a __gc element, which needn't be the same as 5.1's reverse
        order of object construction.

   35.  in 5.2, tables honor __len [patch] and __gc

   36.  in 5.2, __lt and __le metamethods are also honored when operands are of
        different types [patch]

   37.  in 5.2, an iterator function can yield while being used by a `for k in
        ...` loop [patch]; you can also yield out of a [x]pcall or from a
        metamethod.
        The C functions lua_callk, lua_pcallk, lua_yieldk, and
        lua_getctx that enable this are not backported.

   38.  in 5.1, the stack `level` count used by the the Lua error() function
        and several functions in the debug library, and the C functions
        lua_getstack and luaL_where, increments for tail calls. In 5.2, tail
        calls don't increment the level.

   39.  None of: debug.upvalueid, debug.upvaluejoin, lua_upvalueid,
        lua_upvaluejoin have been backported.
        debug.upvalueid(func, idx) returns light userdatum, these can be
        compared to check for shared upvalues
        debug.upvaluejoin(lua_func1, idx1, lua_func2, idx2) makes
        func1's idx1 alias:= func2's idx2

   40.  in 5.2 only, debug.getlocal([thread], f, idx) with a -1,-2,... idx gets
        (names and) values of varargs. Implicit variable names start with '('.
        debug.setlocal([thread], flevel, idx, value) and the C functions
        lua_getlocal and lua_setlocal also handle negative idx.

   41.  in 5.2 only, debug.getlocal can retrieve names (only) when `f` is a
        function instead of a stack level; and lua_getlocal also accepts
        ar == NULL and a Lua function object at stack[-1].

   42.  in 5.1, debug.sethook honors a "tail return" hook, and LUA_HOOKTAILRET
        is a possible value for the ar->event argument of a lua_Hook function
        registered using lua_sethook. In 5.2, these are replaced by "tail call"
        and LUA_HOOKTAILCALL.

   43.  in 5.2, the lua_Debug struct has some new fields:
        * istailcall: use "t" in `what` arg to lua_getinfo or debug.getinfo
        * nparams and isvararg: use "u" in `what` arg
        also, field nups is now an unsigned char


For more information, see
-------------------------
<http://www.lua.org/manual/5.2/manual.html#8>
<http://www.luafaq.org/#T8>
<http://lua-users.org/wiki/LuaFiveTwo>
<http://www.corsix.org/content/look-lua-52-work3>
<http://www.corsix.org/lua/5.2-beta-annotated/manual.html>