The problem I've with the Lua stack API is that you have to make all the mental gym about the current stack layout. And consider that I'm a fan of FORTH and Joy and other stack based languages... But when you have N parameters on the stack, you call a function from Lua, and then you have a different layout based on what such function yields, and so forth, you basically need to comment the state of the stack in order to be able to quickly understand what's going on six months later. An example is the Redis scripting.c code where we call a Lua function to sort the Lua array result.

Another problem I've with the stack API is that it's insecure by default. If you push too many things it will result in a C stack overflow. I'm not sure how much performance this gives, I mean, the inability to grow the stack automatically looks like an optimization matter... But at least, panic when we reach the max stack instead of smashing the C stack.

I believe the Lua creators' claim on this is not that it's necessarily a good API, but rather that it's "just" a better one than any other they know of :) (Or at least knew of at the time when they created Lua. But I think if they learnt of a better one in the meantime, there's a high probability they would try it, given that they're not afraid to break backwards compatibility when they see value in a change.)

for Hammerspoon, we ended up building a fairly large abstraction layer that takes care of all of the repetitive/fragile stack operations for us, and it's improved our productivity significantly. Wiring up new Objective C objects to Lua is now very simple, but we can still fall back to the Lua C API when we need it.

There are still quite a few places in the code though, where some complex stack operation is happening and each line of C/ObjC is surrounded by a lot of comments that describe the expected state of the stack at each step, and there have been a lot of situations where I've ended up having to sketch the stack on paper as I'm reading code, to figure out why something isn't working.

So, I think I'd say that the C API is not comfortable to use, but it's also not very complicated. It's somehow managed to be simple, but hard, if that makes any sense.

Edit: If anyone cares, our Lua abstraction is all written in ObjC and is called LuaSkin. It lives in the Hammerspoon git repo, but doesn't actually depend on Hammerspoon at all, so could be extracted and used by others (it's MIT licensed). The API docs are: http://www.hammerspoon.org/docs/LuaSkin/Classes/LuaSkin/inde...

I used Lua's C API a couple of years ago to write some lightweight JNI code to use Torch from Java. The API documentation was so clear that it was relatively easy to write. Since the API is stack-based the project ended up being a good learning experience. The only thing that was a little annoying was needing a few if/else statements to return the desired type.