where the 4.0 API isn't better

["John Belmonte" <jvb@...>]

Comparing the 4.0 API with the previous one in version 3.2, there are a few
points where I think 4.0 is a step backwards.

* ease of use *  With 3.2, there was a read-only array for function
arguments and simple stack for return values.  Once you got hold of a
lua_Object, it was quite hard to make semantical errors.  The most common
API functions operated on lua_Objects, some others on the top of the return
stack, and it was easy to understand.  In 4.0, there is no object structure:
objects can only exist on the "stack" (really an array) and so now the whole
API has to deal with this array.  It's very easy to make semantical errors
by specifying an incorrect array index.

Stacks are not fun.  That's why people stopped using Forth and started using
Pascal and C.  RPN calculators are for strange people (yes I use one and
it's fine for simple stuff... but if my spreadsheet program were stack-based
I'd be pulling my hair out).  Using an array for interfacing is even more
complicated than a stack.  The solution is to make an interface layer on top
of these things but...

* efficiency when wrapping Lua concepts in C/C++ *  Both API versions are
low level-- as they should be-- and this level of API often needs to be
wrapped.  An example would be representing a Lua table with a C++ class.  In
the 3.2 API this was simple because the API already had the notion of
objects for Lua values and functions for operating on these objects.  With
4.0 we've lost that, and even the simplest representation requires constant
referencing and dereferencing of objects in the array because the class
representation could never know when the array might be altered, changing
the index of the object it represents.

Here is a simple example.  Say there is an object on the host side that
represents a Lua value and provides just one method such as translating to a
number.  Let's look at the API calls as the object is instatiated, has its
sole method called, and destroyed.  An assumption is that the object is
local to the scope of the Lua C function (common case).

3.2 API
    // construction - given lua_Object
    //     no API calls - pointer to lua_Object simply stored in class
    // tonumber method call
    lua_getnumber
    // destruction
    //    no API calls - trivial

4.0 API
    // construction - given "stack" index
    lua_ref
    // tonumber method call
    lua_getref
    lua_tonumber
    lua_pop
    // destruction
    //    no API calls - trivial

Although the 4.0 API implementation is said to be faster, does it make up
for 1 call vs. 3 that would be required for implementing any method such as
"tonumber" in the example above?

-John