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