API Redesign

[gudzpoz]

Is your feature request related to a problem? Please describe.

Inspired by #168.

The current API can be rather alien to users unfamiliar with Lua C API. Moreover, using stack-based Lua API can be tedious and full of boilerplates. Maybe it is time for an API redesign now.

Describe the solution you'd like

Main idea:

• Most of the original stack-based API should be preserved to allow maximal flexibility. If there are any breaking changes, they should be detected by users' compilers, that is, any breaking change will invoke method signature changes.
• There are quite a lot Lua wrappers/implementations in other languages. We might as well just borrow their design. A few coming to mind:
  • C#: https://github.com/Tencent/xLua
  • JS: https://github.com/ceifa/wasmoon/
  • Python: https://github.com/scoder/lupa
  • Java: LuaJ

Improvements:

• Throw Lua-side errors as Java exceptions. They should be checked exceptions to remind users of this API change.
• LuaValue improvements.
• Lua interface improvements:
  • Global value manipulation API.
  • I do think the LuaJ approach feels OK: the Global state itself is a LuaTable (_G), and manipulating it can be quite intuitive for Java users, without involving a Lua stack.
• LuaNative clean up.
  • Some Lua C API functions are common between Lua versions, for example, luaL_gsub. Our bindings are mostly programmatically generated and include these functions. However, luaL_gsub is just doing C string substitution (no, it does not involve any Lua) and should be safe to remove.
  • Check LuaJNatives for more useless functions present in the LuaNative interface.
  • Consider making methods in LuaNative public.
• Remove the deprecated LuaValue#close and delegate the job fully to cleaners/finalizers.

Describe alternatives you've considered

Alternatively, we may also use another class for the new API. But it is not that straight forward and can be a medium if not huge breaking change.