Re: How close to C do you make your binding?

[Philipp Janda <siffiejoe@...>]

Am 18.06.2014 16:37 schröbte Andrew Starks:
> We have our nanomsg binding that we recently remade. It was very C heavy
> and now it's the opposite. We're making an "nml.core" that looks *pretty
> much* exactly like the C API. The higher level binding wraps it in a
> Lua-esque API.
>
> If you have made bindings this way, how far do you take the idea of
> sticking to the C API in your core layer?
>
> Do you strive for perfect adherence to the original C documentation? Do you
> change things like "-1" or "0" to "false", where appropriate? Do you use
> multiple returns where their API is using pointers?

I consider a C binding to be low-level if there is a one-to-one 
function/type mapping between the Lua API and the C API. I usually adapt 
the following:

*   use multiple return values (Lua doesn't have output parameters)
*   make some parameters optional and provide default values
*   if there is a single array parameter, I often support both a table 
and a vararg list in the Lua API
*   error handling (==> nil, error message, [extra info])
*   enums get replaced by strings or userdata
*   functions are renamed (usually to remove a redundant prefix)
*   some functions are additionally made available as methods
*   some functions don't get bound at all (e.g. if they can cause crashes)
*   some functions are called automatically (initializers, finalizers, 
cleanup functions (=> also to avoid crashes))

You can still reuse C tutorials, because the sequence of the API 
functions and the mental model are the same. The usual LDoc-like API 
documentation should be enough to handle the differences.

One thing I'm not sure about yet is whether to expose simple data 
structs/unions as userdata or as tables. So far I've used userdata ...

> -Andrew

Philipp