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:
(The list below can be outdated. The planned improvements are now being tracked at the corresponding PR.)
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.
Rename java.catched to java.caught.
Make C APIs in LuaNatives public.
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.
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:
Improvements:
(The list below can be outdated. The planned improvements are now being tracked at the corresponding PR.)
LuaValueimprovements.Luainterface improvements:Globalstate itself is aLuaTable (_G), and manipulating it can be quite intuitive for Java users, without involving a Lua stack.LuaNativeclean up.luaL_gsub. Our bindings are mostly programmatically generated and include these functions. However,luaL_gsubis just doing C string substitution (no, it does not involve any Lua) and should be safe to remove.LuaJNativesfor more useless functions present in theLuaNativeinterface.LuaNativepublic.LuaValue#closeand delegate the job fully to cleaners/finalizers.java.catchedtojava.caught.LuaNativespublic.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.