This repository is now archived. Consider using http://github.com/lunarmodules/lua-compat-5.3

lua-compat-5.2

Lua-5.2-style APIs for Lua 5.1.

What is it

This is a small module that aims to make it easier to write code in a Lua-5.2-style that is compatible with both Lua 5.1 and Lua 5.2. This does not make Lua 5.1 entirely compatible with Lua 5.2, but it brings the API closer to that of Lua 5.2.

It includes:

• For writing Lua: Lua modules, compat52 and compat52.strict, which can be require'd from Lua scripts and run in both Lua 5.1 and 5.2, plus a backport of bit32 straight from the Lua 5.2 sources, adapted to build as a Lua 5.1 module.
• For writing C: A C header and file which can be linked to your Lua module written in C, providing some functions from the C API of Lua 5.2 that do not exist in Lua 5.1, making it easier to write C code that compiles with both versions of liblua.

Both the Lua module and the C files should also work with LuaJIT.

How to use it

Lua module

require("compat52")

You have to launch it like this (instead of the usual idiom of storing the return of require in a local variable) because compat52 needs to make changes to your global environment.

When run under Lua 5.2, this module does nothing.

When run under Lua 5.1, it replaces some of your standard functions and adds new ones to bring your environment closer to that of Lua 5.2.

You may also use the "strict mode" which removes from Lua 5.1 functions that were deprecated in 5.2; that is the equivalent of running Lua 5.2 with the LUA_COMPAT_ALL flag disabled:

require("compat52.strict")

The "strict mode" changes the global environment, so it affects all loaded modules and chunks. If this is undesirable, you can use the "modular strict mode" which only replaces the environment of the current file. The usage is slightly different (you have to call the return value of require):

require("compat52.mstrict")()

The effects of compat52 are still in effect for all chunks, though.

C code

Add the files compat-5.2.c and compat-5.2.h to your project and link it with the rest of your code as usual.

What's implemented

Lua

• load and loadfile
• table.pack and table.unpack
• string patterns may contain embedded zeros (see here)
• string.rep accepts sep argument
• string.format calls tostring on arguments for %s
• math.log accepts base argument
• xpcall takes additional arguments
• pcall and xpcall can execute functions that yield
• metamethods for pairs and ipairs (see here, and here)
• rawlen (but # still doesn't respect __len for tables)
• collectgarbage (see here)
• package.searchers
• package.searchpath (see here)
• coroutine functions dealing with the main coroutine
• coroutine.create accepts functions written in C
• return code of os.execute (see here)
• io.write and file:write return file handle
• io.lines and file:lines accept format arguments (like io.read) (but see here, and here).
• bit32 (actual backport from the bit32 library from Lua 5.2, also available as a stand-alone rock in the LuaRocks repository)
• debug.setmetatable returns object
• debug.getuservalue (see here)
• debug.setuservalue (see here)
• optional strict mode which removes functions removed or deprecated in Lua 5.2, such as setfenv and getfenv

C

• luaL_Reg (for Lua 5.0)
• luaL_Unsigned
• luaL_addchar (for Lua 5.0)
• lua_absindex
• lua_arith
• lua_compare
• lua_tonumberx and lua_tointegerx
• lua_tounsignedx and lua_tounsigned
• luaL_checkunsigned and luaL_optunsigned
• lua_len, lua_rawlen, and luaL_len
• lua_rawgetp and lua_rawsetp
• lua_copy
• lua_getuservalue (see here)
• lua_setuservalue (see here)
• lua_pushglobaltable
• lua_pushunsigned
• luaL_testudata
• luaL_setfuncs and luaL_newlib
• luaL_setmetatable
• luaL_getsubtable
• luaL_traceback
• luaL_fileresult
• luaL_checkversion (see here)
• luaL_tolstring
• luaL_requiref (see here)
• luaL_buffinitsize, luaL_prepbuffsize, and luaL_pushresultsize (see here)

What's not implemented

• _ENV
• obviously, this does not turn Lua 5.1 into Lua 5.2: syntactic changes to the core language, such as the goto statement, and semantic changes such as ephemeron support for weak tables, remain unavailable.
• "*L" format flag for io.read, io.lines, file:read, file:lines
• second argument for os.exit
• return values of pipe:close if pipe has been opened by io.popen
• "*" as second argument for package.loadlib
• some functions in the debug library
• anything else missing in the Lua libraries?

See also

• For more information about compatibility between Lua versions, see Compatibility With Lua Five at the Lua-Users wiki
• For Lua-5.1-style APIs under Lua 5.0, see Compat-5.1
• for C support in the opposite direction (ie, loading C code using Lua-5.1-style APIs under Lua 5.2), see Twoface

Credits

This package contains code written by:

• The Lua Team
• Philipp Janda (@siffiejoe)
• Tomás Guisasola Gorham (@tomasguisasola)
• Hisham Muhammad (@hishamhm)
• Renato Maia (@renatomaia)