Re: Auxlib documentation

[Luiz Henrique de Figueiredo <lhf@...>]

>Is there any documentation on the functionality in lauxlib.h?

No. You have to read the code in src/lib to see how it's used. See also my
libraries for Lua 5.0 at http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/ .

One reason that there is no documentation for lauxlib is that it changes a
little with every release, depending on our needs to implement the standard
libraries. We hope that it will be sort of stable from now on; at least, only
new functions will be added, hopefully.

Let me try a very brief summary. Perhaps this could be added to lauxlib.h,
if no real documentation is written. Or to the site or wiki.

On the other hand, requests for documentation of lauxlib are very rare. Does
this mean that no one is using it? Or perhaps no one is really writing library
code by hand, relying instead on tolua or luabind or luna or whatever.

One important advantage of use lauxlib is that it provides uniform error
messages for type errors in arguments to C functions. Another one, introduced
in Lua 5.0, is the handling and checking of "typed" userdata values -- a basic
task in ensuring the integrity of pointers in C libraries. Finally, since the
introduction of lua_load and the removal of stdio from the core, lauxlib now
contains luaL_loadfile and luaL_loadbuffer and lua_do*.

--lhf

** Load and run Lua code -----------------------------------------------------

* luaL_loadfile(L,filename)
  A wrapper for lua_load that handles files.
  Reports errors on the stack as usual.

* luaL_loadbuffer(L,b,n,name)
  A wrapper for lua_load that handles buffers.

* lua_dofile(L,filename)
  Loads and runs a file. Reports errors on the stack as usual.

* lua_dobuffer(L,filename)
  Loads and runs a buffer. Reports errors on the stack as usual.

* lua_dostring(L,filename)
  Loads and runs a string. Reports errors on the stack as usual.

** Open Lua libraries --------------------------------------------------------

* luaL_openlib(L,M,R,n)
  Opens a Lua library into a global tabled named M. It registers the
  functions listed in the array R of pairs <name,function>. Each
  function gets n upvalues, which are the n top values on the stack.
  Each function gets the same n upvalue s. If M exists it is used.
  Otherwise, a new table named M is created and used.

** Check arguments -----------------------------------------------------------

* luaL_checklstring(L,n,&l)
  Checks that the value at stack position n is a string. If so, returns the
  string as the return value and its length in l, if l is not NULL. If the
  value is not a string, issues an error. If you don't care about l, use
  luaL_checkstring(L,n) instead.

* luaL_optlstring(L,n,s,&l)
  Similar to luaL_checklstring, except that is argument n is absent then s
  is used as a default value and returned. If you don't care about l, use
  luaL_optstring(L,n,s) instead.

* luaL_checknumber and luaL_optnumber do the same thing for numbers.
  luaL_checkint, luaL_optint, luaL_checklong, and luaL_optlong work on top
  of luaL_checknumber and luaL_optnumber and return int and long.

* luaL_checkany(L,n)
  Checks that argument n is present, issuing an error if not.

* luaL_checktype(L,n,t)
  Checks that argument n is of type t (LUA_T*), issuing an error if not.

* luaL_checkstack(L,n,message)
  A wrapper to lua_checkstack that issues an error if it fails.

* luaL_typerror(L,n,t)
  Issues an type error about argument n, whose type was expected to be t
  (a string, not a LUA_T*). A workhorse function for the functions above,
  but also useful in itself.

* luaL_argerror(L,n,message)
  Issues an error about argument n. If message is not NULL, it is
  appended to the error message. This is the real workhorse function for
  previous functions, but it is also useful in itself.

* luaL_argcheck(L,cond,n,message)
  If cond is false, call luaL_argerror(L,n,message).

** Issue errors --------------------------------------------------------------

* luaL_error(L,fmt,...)
  Issues an error whose message is formatted using a printf-like string fmt.
  It uses lua_pushfstring and so only handles `%d', `%c', %f, and `%s'.

* luaL_where(L,n)
  Tries to display the error location if the function at level n is a
  Lua function.

** Find string in list -------------------------------------------------------

* luaL_findstring(s,S)
  Tries to find the string s in the string array S. Returns the index if
  found and -1 if not. It performs a linear search. The array S must be
  terminated with a NULL string.

** Maintain size of table when used as an array ------------------------------

* luaL_getn(L,t)
  Gets the size of the table at stack position t.

* luaL_setn(L,t)
  Sets the size of the table at stack position t to be n.

** Maintain references to Lua values -----------------------------------------

* luaL_ref(L,t)
  Returns a reference to the value at the top of the stack into the
  table at stack position t.

* luaL_unref(L,t,r)
  Clears reference r in the table at stack position t.

** Maintain "type" userdata --------------------------------------------------

* luaL_newmetatable(L,name)
  Create a metatable for representing the named "type".

* luaL_getmetatable(L,name)
  Get the metatable representing the named "type".

* luaL_checkudata(L,n,name)
  Checks whether the value at stack position is userdata of the named type.
  If not, returns NULL (even if the value is not userdata).

** Manipulate metamethods ----------------------------------------------------

* luaL_getmetafield(L,n,e)
  Gets the metamethod corresponding to event e in the metatable of the value at
  position n.

* luaL_callmeta(L,n,e)
  Calls the metamethod corresponding to event e for the value at position n.

** String buffer manipulation ------------------------------------------------

lauxlib contains a set of functions to keep string buffers. Very handy for
creating arbitrarily long string in a piecewise way in a efficient way
(not the obvious quadratic algorithm). See lstrlib.c for examples.
The functions in this set could have better names...

* luaL_buffinit(L,B)
  Initializes a buffer. Must be called before using it. B is usually the
  address of an automatic (local) variable of type luaL_Buffer.

* luaL_prepbuffer(B)
  Leaves the current value of B on the stack and empties it for reuse.

* luaL_putchar(B,c)
  Add a single character to B.

* luaL_addsize(B,n)
  Adds n to the size of B.

* luaL_addlstring(B,s,l)
  Adds a string s of length l to B.

* luaL_addstring(B,s,l)
  Adds a string s to B. The string s must be terminated by '\0'.

* luaL_addvalue(B)
  Adds the value at the top of the stack to B. First converts the value ot
  a string using lua_tostring.

* luaL_pushresult(B)
  Leaves the whole contents of the buffer at the top of the stack.

(eof)