1[![Build Status](https://travis-ci.org/keplerproject/lua-compat-5.3.svg?branch=master)](https://travis-ci.org/keplerproject/lua-compat-5.3) 2 3# lua-compat-5.3 4 5Lua-5.3-style APIs for Lua 5.2 and 5.1. 6 7## What is it 8 9This is a small module that aims to make it easier to write code 10in a Lua-5.3-style that is compatible with Lua 5.1, Lua 5.2, and Lua 115.3. This does *not* make Lua 5.2 (or even Lua 5.1) entirely 12compatible with Lua 5.3, but it brings the API closer to that of Lua 135.3. 14 15It includes: 16 17* _For writing Lua_: The Lua module `compat53`, which can be require'd 18 from Lua scripts and run in Lua 5.1, 5.2, and 5.3, including a 19 backport of the `utf8` module, the 5.3 `table` module, and the 20 string packing functions straight from the Lua 5.3 sources. 21* _For writing C_: A C header and file which can be linked to your 22 Lua module written in C, providing some functions from the C API 23 of Lua 5.3 that do not exist in Lua 5.2 or 5.1, making it easier to 24 write C code that compiles with all three versions of liblua. 25 26## How to use it 27 28### Lua module 29 30```lua 31require("compat53") 32``` 33 34`compat53` makes changes to your global environment and does not return 35a meaningful return value, so the usual idiom of storing the return of 36`require` in a local variable makes no sense. 37 38When run under Lua 5.3, this module does nothing. 39 40When run under Lua 5.2 or 5.1, it replaces some of your standard 41functions and adds new ones to bring your environment closer to that 42of Lua 5.3. It also tries to load the backported `utf8`, `table`, and 43string packing modules automatically. If unsuccessful, pure Lua 44versions of the new `table` functions are used as a fallback, and 45[Roberto's struct library][1] is tried for string packing. 46 47#### Lua submodules 48 49```lua 50local _ENV = require("compat53.module") 51if setfenv then setfenv(1, _ENV) end 52``` 53 54The `compat53.module` module does not modify the global environment, 55and so it is safe to use in modules without affecting other Lua files. 56It is supposed to be set as the current environment (see above), i.e. 57cherry picking individual functions from this module is expressly 58*not* supported!). Not all features are available when using this 59module (e.g. yieldable (x)pcall support, string/file methods, etc.), 60so it is recommended to use plain `require("compat53")` whenever 61possible. 62 63### C code 64 65There are two ways of adding the C API compatibility functions/macros to 66your project: 67* If `COMPAT53_PREFIX` is *not* `#define`d, `compat-5.3.h` `#include`s 68 `compat-5.3.c`, and all functions are made `static`. You don't have to 69 compile/link/add `compat-5.3.c` yourself. This is useful for one-file 70 projects. 71* If `COMPAT53_PREFIX` is `#define`d, all exported functions are renamed 72 behind the scenes using this prefix to avoid linker conflicts with other 73 code using this package. This doesn't change the way you call the 74 compatibility functions in your code. You have to compile and link 75 `compat-5.3.c` to your project yourself. You can change the way the 76 functions are exported using the `COMPAT53_API` macro (e.g. if you need 77 some `__declspec` magic). While it is technically possible to use 78 the "lua" prefix (and it looks better in the debugger), this is 79 discouraged because LuaJIT has started to implement its own Lua 5.2+ 80 C API functions, and with the "lua" prefix you'd violate the 81 one-definition rule with recent LuaJIT versions. 82 83## What's implemented 84 85### Lua 86 87* the `utf8` module backported from the Lua 5.3 sources 88* `string.pack`, `string.packsize`, and `string.unpack` from the Lua 89 5.3 sources or from the `struct` module. (`struct` is not 100% 90 compatible to Lua 5.3's string packing!) (See [here][4]) 91* `math.maxinteger` and `math.mininteger`, `math.tointeger`, `math.type`, 92 and `math.ult` (see [here][5]) 93* `assert` accepts non-string error messages 94* `ipairs` respects `__index` metamethod 95* `table.move` 96* `table` library respects metamethods 97 98For Lua 5.1 additionally: 99* `load` and `loadfile` accept `mode` and `env` parameters 100* `table.pack` and `table.unpack` 101* string patterns may contain embedded zeros (but see [here][6]) 102* `string.rep` accepts `sep` argument 103* `string.format` calls `tostring` on arguments for `%s` 104* `math.log` accepts base argument 105* `xpcall` takes additional arguments 106* `pcall` and `xpcall` can execute functions that yield (see 107 [here][22] for a possible problem with `coroutine.running`) 108* `pairs` respects `__pairs` metamethod (see [here][7]) 109* `rawlen` (but `#` still doesn't respect `__len` for tables) 110* `package.searchers` as alias for `package.loaders` 111* `package.searchpath` (see [here][8]) 112* `coroutine` functions dealing with the main coroutine (see 113 [here][22] for a possible problem with `coroutine.running`) 114* `coroutine.create` accepts functions written in C 115* return code of `os.execute` (see [here][9]) 116* `io.write` and `file:write` return file handle 117* `io.lines` and `file:lines` accept format arguments (like `io.read`) 118 (see [here][10] and [here][11]) 119* `debug.setmetatable` returns object 120* `debug.getuservalue` (see [here][12]) 121* `debug.setuservalue` (see [here][13]) 122 123### C 124 125* `lua_KContext` (see [here][14]) 126* `lua_KFunction` (see [here][14]) 127* `lua_dump` (extra `strip` parameter, ignored, see [here][15]) 128* `lua_getfield` (return value) 129* `lua_geti` and `lua_seti` 130* `lua_getglobal` (return value) 131* `lua_getmetafield` (return value) 132* `lua_gettable` (return value) 133* `lua_getuservalue` (limited compatibility, see [here][16]) 134* `lua_setuservalue` (limited compatibility, see [here][17]) 135* `lua_isinteger` 136* `lua_numbertointeger` 137* `lua_callk` and `lua_pcallk` (limited compatibility, see [here][14]) 138* `lua_resume` 139* `lua_rawget` and `lua_rawgeti` (return values) 140* `lua_rawgetp` and `lua_rawsetp` 141* `luaL_requiref` (now checks `package.loaded` first) 142* `lua_rotate` 143* `lua_stringtonumber` (see [here][18]) 144 145For Lua 5.1 additionally: 146* `LUA_OK` 147* `LUA_ERRGCMM` 148* `LUA_OP*` macros for `lua_arith` and `lua_compare` 149* `LUA_FILEHANDLE` 150* `lua_Unsigned` 151* `luaL_Stream` (limited compatibility, see [here][19]) 152* `lua_absindex` 153* `lua_arith` (see [here][20]) 154* `lua_compare` 155* `lua_len`, `lua_rawlen`, and `luaL_len` 156* `lua_load` (mode argument) 157* `lua_pushstring`, `lua_pushlstring` (return value) 158* `lua_copy` 159* `lua_pushglobaltable` 160* `luaL_testudata` 161* `luaL_setfuncs`, `luaL_newlibtable`, and `luaL_newlib` 162* `luaL_setmetatable` 163* `luaL_getsubtable` 164* `luaL_traceback` 165* `luaL_execresult` 166* `luaL_fileresult` 167* `luaL_loadbufferx` 168* `luaL_loadfilex` 169* `luaL_checkversion` (with empty body, only to avoid compile errors, 170 see [here][21]) 171* `luaL_tolstring` 172* `luaL_buffinitsize`, `luaL_prepbuffsize`, and `luaL_pushresultsize` 173 (see [here][22]) 174* `lua_pushunsigned`, `lua_tounsignedx`, `lua_tounsigned`, 175 `luaL_checkunsigned`, `luaL_optunsigned`, if 176 `LUA_COMPAT_APIINTCASTS` is defined. 177 178## What's not implemented 179 180* bit operators 181* integer division operator 182* utf8 escape sequences 183* 64 bit integers 184* `coroutine.isyieldable` 185* Lua 5.1: `_ENV`, `goto`, labels, ephemeron tables, etc. See 186 [`lua-compat-5.2`][2] for a detailed list. 187* the following C API functions/macros: 188 * `lua_isyieldable` 189 * `lua_getextraspace` 190 * `lua_arith` (new operators missing) 191 * `lua_push(v)fstring` (new formats missing) 192 * `lua_upvalueid` (5.1) 193 * `lua_upvaluejoin` (5.1) 194 * `lua_version` (5.1) 195 * `lua_yieldk` (5.1) 196 197## See also 198 199* For Lua-5.2-style APIs under Lua 5.1, see [lua-compat-5.2][2], 200 which also is the basis for most of the code in this project. 201* For Lua-5.1-style APIs under Lua 5.0, see [Compat-5.1][3] 202 203## Credits 204 205This package contains code written by: 206 207* [The Lua Team](http://www.lua.org) 208* Philipp Janda ([@siffiejoe](http://github.com/siffiejoe)) 209* Tomás Guisasola Gorham ([@tomasguisasola](http://github.com/tomasguisasola)) 210* Hisham Muhammad ([@hishamhm](http://github.com/hishamhm)) 211* Renato Maia ([@renatomaia](http://github.com/renatomaia)) 212* [@ThePhD](http://github.com/ThePhD) 213* [@Daurnimator](http://github.com/Daurnimator) 214 215 216 [1]: http://www.inf.puc-rio.br/~roberto/struct/ 217 [2]: http://github.com/keplerproject/lua-compat-5.2/ 218 [3]: http://keplerproject.org/compat/ 219 [4]: https://github.com/keplerproject/lua-compat-5.3/wiki/string_packing 220 [5]: https://github.com/keplerproject/lua-compat-5.3/wiki/math.type 221 [6]: https://github.com/keplerproject/lua-compat-5.3/wiki/pattern_matching 222 [7]: https://github.com/keplerproject/lua-compat-5.3/wiki/pairs 223 [8]: https://github.com/keplerproject/lua-compat-5.3/wiki/package.searchpath 224 [9]: https://github.com/keplerproject/lua-compat-5.3/wiki/os.execute 225 [10]: https://github.com/keplerproject/lua-compat-5.3/wiki/io.lines 226 [11]: https://github.com/keplerproject/lua-compat-5.3/wiki/file.lines 227 [12]: https://github.com/keplerproject/lua-compat-5.3/wiki/debug.getuservalue 228 [13]: https://github.com/keplerproject/lua-compat-5.3/wiki/debug.setuservalue 229 [14]: https://github.com/keplerproject/lua-compat-5.3/wiki/yieldable_c_functions 230 [15]: https://github.com/keplerproject/lua-compat-5.3/wiki/lua_dump 231 [16]: https://github.com/keplerproject/lua-compat-5.3/wiki/lua_getuservalue 232 [17]: https://github.com/keplerproject/lua-compat-5.3/wiki/lua_setuservalue 233 [18]: https://github.com/keplerproject/lua-compat-5.3/wiki/lua_stringtonumber 234 [19]: https://github.com/keplerproject/lua-compat-5.3/wiki/luaL_Stream 235 [20]: https://github.com/keplerproject/lua-compat-5.3/wiki/lua_arith 236 [21]: https://github.com/keplerproject/lua-compat-5.3/wiki/luaL_checkversion 237 [22]: https://github.com/keplerproject/lua-compat-5.3/wiki/luaL_Buffer 238 [23]: https://github.com/keplerproject/lua-compat-5.3/wiki/coroutine.running 239 240