3. Alphabetical Listing of all Routines

luaL_addlstring

Syntax:
Description:



luaL_addstring

Syntax:
Description:



luaL_addvalue

Syntax:
Description:



luaL_argerror

Syntax:
Description:



luaL_buffinit

Syntax:
Description:



luaL_callmeta

Syntax:
Description:



luaL_checkany

Syntax:
Description:



luaL_checklstring

Syntax:
Description:



luaL_checknumber

Syntax:
Description:



luaL_checkstack

Syntax:
Description:



luaL_checktype

Syntax:
Description:



luaL_checkudata

Syntax:
Description:



luaL_error

Syntax:
Description:



luaL_findstring

Syntax:
Description:



luaL_getmetafield

Syntax:
Description:



luaL_getmetatable

Syntax:
Description:



luaL_getn

Syntax:
Description:



luaL_loadbuffer

Syntax:
Description:



luaL_loadfile

Syntax:
Description:



luaL_newmetatable

Syntax:
Description:



luaL_openlib

Syntax:
Description:



luaL_optlstring

Syntax:
Description:



luaL_optnumber

Syntax:
Description:



luaL_prepbuffer

Syntax:
Description:



luaL_pushresult

Syntax:
Description:



luaL_ref

Syntax:
Description:



luaL_setn

Syntax:
Description:



luaL_typerror

Syntax:
Description:



luaL_unref

Syntax:
Description:



luaL_where

Syntax:
Description:



lua_atpanic

Syntax: atom a = lua_atpanic(atom L, atom panicf)
Description: Changes the panic function. If an error happens outside any protected environment, Lua calls a panic function, and then calls exit(EXIT_FAILURE).



lua_call

Syntax: lua_call(atom L, integer nargs, integer nresults)
Description: Functions defined in Lua and C functions registered in Lua can be called from the host program. This is done using the following protocol: First, the function to be called is pushed onto the stack; then, the arguments to the function are pushed in direct order, that is, the first argument is pushed first. Finally, the function is called using nargs is the number of arguments that you pushed onto the stack. All arguments and the function value are popped from the stack, and the function results are pushed. The number of results are adjusted to nresults, unless nresults is LUA_MULTRET. In that case, all results from the function are pushed. Lua takes care that the returned values fit into the stack space. The function results are pushed onto the stack in direct order (the first result is pushed first), so that after the call the last result is on the top.



lua_checkstack

Syntax: atom a = lua_checkstack(atom L, integer sz)
Description: When you interact with Lua API, you are responsible for controlling stack overflow. This function grows the stack size to top + extra elements; it returns false if it cannot grow the stack to that size. This function never shrinks the stack; if the stack is already larger than the new size, it is left unchanged. The minimum size is 20.



lua_close

Syntax: lua_close(atom L)
Description: Releases a state created with lua_open.
Comments: This function destroys all objects in the given Lua state (calling the corresponding garbage-collection metamethods, if any) and frees all dynamic memory used by that state. On several platforms, you may not need to call this function, because all resources are naturally released when the host program ends. On the other hand, long-running programs, such as a daemon or a web server, might need to release states as soon as they are not needed, to avoid growing too large.
See Also: lua_open



lua_concat

Syntax: lua_concat(atom L, integer n)
Description: The function lua_concat concatenates the n values at the top of the stack, pops them, and leaves the result at the top. If n is 1, the result is that single string (that is, the function does nothing); if n is 0, the result is the empty string. Concatenation is done following the usual semantics of Lua



lua_cpcall

Syntax: atom a = lua_cpcall(atom L, atom func, atom ud)
Description: lua_cpcall calls func in protected mode. func starts with only one element in its stack, a light userdata containing ud. In case of errors, lua_cpcall returns the same error codes as lua_pcall, plus the error object on the top of the stack; otherwise, it returns zero, and does not change the stack. Any value returned by func is dicarded.



lua_dobuffer

Syntax:
Description:



lua_dofile

Syntax:
Description:



lua_dostring

Syntax:
Description:



lua_dump

Syntax: atom a = lua_dump(atom L, atom writer, atom data)
Description:



lua_equal

Syntax: atom a = lua_equal(atom L, integer idx1, integer idx2)
Description: Test the equality of the two values at the index's passed.



lua_error

Syntax: lua_error(atom L)
Description: Your code can generate a Lua error by calling this function. The error message (which actually can be any type of object) must be on the stack top. This function does a long jump, and therefore never returns.



lua_getfenv

Syntax: lua_getfenv(atom L, integer index)
Description: lua_getfenv pushes on the stack the environment table of the function at index index in the stack. If the function is a C function, lua_getfenv pushes the global environment.



lua_getgccount

Syntax: atom a = lua_getgccount(atom L)
Description: You can access the count described below with lua_getgccount.
Comments: Lua uses two numbers to control its garbage collection: the count and the threshold. The first counts the amount of memory in use by Lua; when the count reaches the threshold, Lua runs its garbage collector. After the collection, the count is updated and the threshold is set to twice the count value.



lua_getgcthreshhold

Syntax: atom a = lua_getgcthreshold(atom L)
Description: You can access the threshold number described below with lua_getgcthreshold.
Comments: Lua uses two numbers to control its garbage collection: the count and the threshold. The first counts the amount of memory in use by Lua; when the count reaches the threshold, Lua runs its garbage collector. After the collection, the count is updated and the threshold is set to twice the count value.
See Also: lua_getgccount



lua_gethook

Syntax:
Description:



lua_gethookcount

Syntax:
Description:



lua_gethookmask

Syntax:
Description:



lua_getinfo

Syntax: atom a = lua_getinfo(atom L, sequence what, atom ar)
Description: To fill the other fields of lua_Debug with useful information, call lua_getinfo. This function returns 0 on error (for instance, an invalid option in what). Each character in the string what selects some fields of the structure ar to be filled, as indicated by the letter in parentheses in the definition of lua_Debug above: `S´ fills in the fields source, linedefined, and what; `l´ fills in the field currentline, etc. Moreover, `f´ pushes onto the stack the function that is running at the given level. To get information about a function that is not active (that is, not in the stack), you push it onto the stack and start the what string with the character `>´.



lua_getlocal

Syntax: sequence s = lua_getlocal(atom L, atom ar, integer n)
Description: This function allows the manipulation of the local variables of a given activation record. The parameter ar must be a valid activation record that was filled by a previous call to lua_getstack or given as argument to a hook (see 4.3). lua_getlocal gets the index n of a local variable, pushes the variable's value onto the stack, and returns its name.
See Also: lua_setlocal



lua_getmetatable

Syntax: atom a = lua_getmetatable(atom L, integer objectindex)
Description: If the object does not have a metatable, returns nil. Otherwise, if the object's metatable has a "__metatable" field, returns the associated value. Otherwise, returns the metatable of the given object.



lua_getstack

Syntax: atom a = lua_getstack(atom L, integer level, atom ar)
Description: The main function to get information about the interpreter runtime stack is lua_getstack. This function fills parts of a lua_Debug structure with an identification of the activation record of the function executing at a given level. Level 0 is the current running function, whereas level n+1 is the function that has called level n. When there is no errors, lua_getstack returns 1; when called with a level greater than the stack depth, it returns 0.



lua_gettable

Syntax: lua_gettable(atom L, integer idx)
Description: Reads a value from a table that resides somewhere in the stack; where idx points to the table. lua_gettable pops a key from the stack and returns (on the stack) the contents of the table at that key. The table is left where it was in the stack. As in Lua, this function may trigger a metamethod for the "index" event. To get the real value of any table key, without invoking any metamethod, use lua_rawget.



lua_gettop

Syntax: atom a = lua_gettop(atom L)
Description: You get the index of the top element of the stack by calling this function.



lua_getupvalue

Syntax: sequence s = lua_getupvalue(atom L, integer funcindex, integer n)
Description: The following function allows the manipulation of the upvalues of a given function (unlike local variables, the upvalues of a function are accessible even when the function is not active). funcindex points to a function in the stack. lua_getpuvalue gets the index n of an upvalue, pushes the upvalue's value onto the stack, and returns its name. Returns NULL when the index is greater than the number of upvalues.



lua_insert

Syntax: lua_insert(atom L, integer idx)
Description: lua_remove removes the element at the given position, shifting down the elements above that position to fill the gap.



lua_iscfunction

Syntax: atom a = lua_iscfunction(atom L, integer idx)
Description: Use this to check if the value on the stack at idx is a cfunction.



lua_isnumber

Syntax: atom a = lua_isnumber(atom L, integer idx)
Description: Use this to check if the value on the stack at idx is a number.
Comments: The lua_is* functions return 1 if the object is compatible with the given type, and 0 otherwise.
See Also: lua_type, lua_isnil, lua_isboolean, lua_isstring, lua_istable, lua_isfunction, lua_iscfunction, lua_isuserdata, lua_islightuserdata



lua_isstring

Syntax: atom a = lua_isstring(atom L, integer idx)
Description: Use this to check if the value on the stack at idx is a string.



lua_isuserdata

Syntax: atom a = lua_isuserdata(atom L, integer idx)
Description: Use this to check if the value on the stack at idx is user data.



lua_lessthan

Syntax: atom a = lua_lessthan(atom L, integer idx1, integer idx2)
Description: Checks if the value at idx1 is less than the value at idx2.



lua_load

Syntax: atom a = lua_load(atom L, atom reader, atom dt, sequence chunkname)
Description: Since you cannot get pointers to functions in Euphoria, this routine is unusable at this time. You can load a Lua chunk with lua_load. The return values of lua_load are: 0 --- no errors; 1: LUA_ERRSYNTAX --- syntax error during pre-compilation. 2: LUA_ERRMEM --- memory allocation error. If there are no errors, lua_load pushes the compiled chunk as a Lua function on top of the stack. Otherwise, it pushes an error message. lua_load automatically detects whether the chunk is text or binary, and loads it accordingly. lua_load uses an user-supplied reader function to read the chunk. Everytime it needs another piece of the chunk, it calls the reader, passing along its data parameter. The reader must return a pointer to a block of memory with a new piece of the chunk and set size to the block size. To signal the end of the chunk, the reader returns NULL. The reader function may return pieces of any size greater than zero. In the current implementation, the reader function cannot call any Lua function; to ensure that, it always receives NULL as the Lua state. The chunkname is used for error messages and debug information.



lua_newtable

Syntax: lua_newtable(atom L)
Description: This function creates a new, empty table and pushes it onto the stack.



lua_newthread

Syntax: atom a = lua_newthread(atom L)
Description: This function pushes the thread on the stack and returns a pointer to a lua_State that represents this new thread. The new state returned by this function shares with the original state all global objects (such as tables), but has an independent run-time stack. Each thread has an independent global environment table. When you create a thread, this table is the same as that of the given state, but you can change each one independently.
Comments: Lua offers partial support for multiple threads of execution. If you have a C library that offers multi-threading, then Lua can cooperate with it to implement the equivalent facility in Lua. Also, Lua implements its own coroutine system on top of threads.



lua_newuserdata

Syntax: lua_newuserdata(atom L, atom sz)
Description: This function allocates a new block of memory with the given size, pushes on the stack a new userdata with the block address, and returns this address.



lua_next

Syntax: atom a = lua_next(atom L, integer index)
Description: You can traverse a table with the function lua_next; where index points to the table to be traversed. The function pops a key from the stack, and pushes a key-value pair from the table (the "next" pair after the given key). If there are no more elements, then lua_next returns 0 (and pushes nothing). Use a nil key to signal the start of a traversal.



lua_open

Syntax: atom a = lua_open()
Description: Creates a lua state, and returns a pointer to the state.
Comments: The Lua library is fully reentrant: it has no global variables. The whole state of the Lua interpreter (global variables, stack, etc.) is stored in a dynamically allocated structure of type lua_State. A pointer to this state must be passed as the first argument to every function in the library, except to lua_open, which creates a Lua state from scratch.
See Also: lua_close



lua_pcall

Syntax: atom a = lua_pcall(atom L, integer nargs, integer nresults, integer errfunc)
Description: lua_pcall is similar to lua_call. Both nargs and nresults have the same meaning as in lua_call. If there are no errors during the call, lua_pcall behaves exactly like lua_call. However, if there is any error, lua_pcall catches it, pushes a single value at the stack (the error message), and returns an error code. Like lua_call, lua_pcall always removes the function and its arguments from the stack. If errfunc is 0, then the error message returned is exactly the original error message. Otherwise, errfunc gives the stack index for an error handler function. (In the current implementation, that index cannot be a pseudo-index.) In case of runtime errors, that function will be called with the error message and its return value will be the message returned by lua_pcall. Typically, the error handler function is used to add more debug information to the error message, such as a stack traceback. Such information cannot be gathered after the return of lua_pcall, since by then the stack has unwound. The lua_pcall function returns 0 in case of success or one of the following error codes: 1 : LUA_ERRRUN --- a runtime error. 2: LUA_ERRMEM --- memory allocation error. For such errors, Lua does not call the error handler function. 3: LUA_ERRERR --- error while running the error handler function.



lua_pop

Syntax: lua_pop(atom L, integer n)
Description: A macro used to pop n elements from the stack.



lua_pushboolean

Syntax: lua_pushboolean(atom L, integer b)
Description: Converts b into a lua value, and pushes the result onto the stack.



lua_pushcclosure

Syntax: lua_pushcclosure(atom L, atom fn, integer n)
Description: This function is used to push the C function onto the stack, with the argument n telling how many values should be associated with the function (lua_pushcclosure also pops these values from the stack).
Comments: When a C function is created, it is possible to associate some values with it, thus creating a C closure; these values are then accessible to the function whenever it is called. To associate values with a C function, first these values should be pushed onto the stack (when there are multiple values, the first value is pushed first).



lua_pushfstring

Syntax: atom a = lua_pushfstring(atom L, sequence fmt)
Description: Similar to lua_pushvfstring.
See Also: lua_pusvfstring



lua_pushlightuserdata

Syntax: lua_pushlightuserdata(atom L, atom p)
Description: lua_pushlightuserdata is used to push a light userdata into the stack.
See Also: lua_newuserdata, lua_touserdata



lua_pushlstring

Syntax: lua_pushlstring(atom L, sequence s, atom l)
Description: lua_pushlstring converts the string s of length l to a lua string then pushes the result onto the stack. It also makes an internal copy of the given string.



lua_pushnil

Syntax: lua_pushnil(atom L)
Description: Used mostly when traversing tables, the nil key signals the start of the traversal.
Comments: The lua_push functions receive a C value, convert it to a corresponding Lua value, and push the result onto the stack. In particular, lua_pushlstring and lua_pushstring make an internal copy of the given string. lua_pushstring can only be used to push proper C strings (that is, strings that end with a zero and do not contain embedded zeros); otherwise, you should use the more general lua_pushlstring, which accepts an explicit size.



lua_pushnumber

Syntax: lua_pushnumber(atom L, atom n)
Description: lua_pushnumber takes a value n, converts it to a lua value, and pushes the result onto the stack.



lua_pushstring

Syntax: lua_pushstring(atom L, sequence s)
Description: lua_pushstring converts string s into a lua string, then pushes it onto the stack. It also makes an internal copy of the given string.



lua_pushvalue

Syntax: lua_pushvalue(atom L, integer idx)
Description: lua_pushvalue pushes onto the stack a copy of the element at the given index.



lua_pushvfstring

Syntax: atom a = lua_pushvfstring(atom L, sequence fmt, sequence argp)
Description: lua_pushvfstring pushes onto the stack a formatted string and returns a pointer to that string. The conversion specifiers are contained in argp.
Comments: You do not have to allocate the space for the result: The result is a Lua string and Lua takes care of memory allocation (and deallocation, through garbage collection). The conversion specifiers are quite restricted. There are no flags, widths, or precisions. The conversion specifiers can be simply `%%´ (inserts a `%´ in the string), `%s´ (inserts a zero-terminated string, with no size restrictions), `%f´ (inserts a lua_Number), `%d´ (inserts an int), and `%c´ (inserts an int as a character).
See Also: lua_pushfstring



lua_rawequal

Syntax: atom a = lua_rawequal(atom L, integer idx1, integer idx2)
Description: lua_rawequal compares the values for primitive equality, without metamethods.



lua_rawget

Syntax: lua_rawget(atom L, integer idx)
Description: Use lua_rawget to get the real value of any table key, without invoking any metamethods.



lua_rawgeti

Syntax: lua_rawgeti(atom L, integer index, integer n)
Description: lua_rawgeti pushes the value of the n-th element of the table at stack position index.



lua_rawset

Syntax: lua_rawset(atom L, integer idx)
Description: Sets the real value of any table index, without invoking any metamethod.



lua_rawseti

Syntax: lua_rawseti(atom L, integer index, integer n)
Description: lua_rawseti sets the value of the n-th element of the table at stack position index to the value at the top of the stack, removing this value from the stack.



lua_remove

Syntax:
Description:



lua_replace

Syntax: lua_replace(atom L, integer idx)
Description: lua_replace moves the top element into the given position, without shifting any element (therefore replacing the value at the given position).



lua_resume

Syntax: atom a = lua_resume(atom L, integer narg)
Description: To start a coroutine, you first create a new thread; then you push on its stack the body function plus any eventual arguments; then you call lua_resume, with narg being the number of arguments. This call returns when the coroutine suspends or finishes its execution.



lua_setfenv

Syntax: atom a = lua_setfenv(atom L, integer index)
Description: lua_setfenv pops a table from the stack and sets it as the new environment for the function at index index in the stack. If the object at the given index is not a Lua function, lua_setfenv returns 0.



lua_setgcthreshold

Syntax: lua_setgcthreshold(atom L, integer newthreshold)
Description: You can change the threshold value with lua_setgcthreshold. Again, the newthreshold value is given in Kbytes. When you call this function, Lua sets the new threshold and checks it against the byte counter. If the new threshold is less than the byte counter, then Lua immediately runs the garbage collector. In particular lua_setgcthreshold(L,0) forces a garbage collection. After the collection, a new threshold is set according to the previous rule.



lua_sethook

Syntax:
Description:



lua_setlocal

Syntax: sequence s = lua_setlocal(atom L, atom ar, integer n)
Description: This function allows the manipulation of the local variables of a given activation record. lua_setlocal assigns the value at the top of the stack to the variable and returns its name.
See Also: lua_getlocal



lua_setmetatable

Syntax: atom a = lua_setmetatable(atom L, integer objectindex)
Description: lua_setmetatable pops a table from the stack and sets it as the new metatable for the given object. lua_setmetatable returns 0 when it cannot set the metatable of the given object (that is, when the object is neither a userdata nor a table); even then it pops the table from the stack.



lua_settable

Syntax: lua_settable(atom L, integer index)
Description: Use this to store a value into a table that resides somewhere in the stack, but first you must push the key and then the value onto the stack. Then call lua_settable; where index points to the table. lua_settable pops from the stack both the key and the value. The table is left where it was in the stack. As in Lua, this operation may trigger a metamethod for the "settable" or "newindex" events.



lua_settop

Syntax: lua_settop(atom L, integer idx)
Description: lua_settop accepts any acceptable index, or 0, and sets the stack top to that index. If the new top is larger than the old one, then the new elements are filled with nil. If index is 0, then all stack elements are removed.



lua_setupvalue

Syntax: sequence s = lua_setupvalue(atom L, integer funcindex, integer n)
Description: The following function allows the manipulation of the upvalues of a given function (unlike local variables, the upvalues of a function are accessible even when the function is not active). lua_setupvalue assigns the value at the top of the stack to the upvalue and returns its name. Returns NULL when the index is greater than the number of upvalues.



lua_strlen

Syntax: atom a = lua_strlen(atom L, integer idx)
Description: lua_strlen returns the length of the string at idx.



lua_toboolean

Syntax: atom a lua_toboolean(atom L, integer idx)
Description: lua_toboolean converts the Lua value at the given index to a C "boolean" value (0 or 1). Like all tests in Lua, lua_toboolean returns 1 for any Lua value different from false and nil; otherwise it returns 0. It also returns 0 when called with a non-valid index. (If you want to accept only real boolean values, use lua_isboolean to test the type of the value.)



lua_tocfunction

Syntax: atom a = lua_tocfunction(atom L, integer idx)
Description: lua_tocfunction converts a value in the stack to a C function. This value must be a C function; otherwise, lua_tocfunction returns NULL. Because in Euphoria you cannot get a pointer to functions written in Euphoria, this function and others involving use of the lua_CFunction type are unusable for now.



lua_tonumber

Syntax: atom a = lua_tonumber(atom L, integer idx)
Description: Converts the value at idx to a number.



lua_topointer

Syntax: lua_topointer(atom L, integer idx)
Description: lua_topointer converts a value in the stack to a generic C pointer (void *). The value may be a userdata, a table, a thread, or a function; otherwise, lua_topointer returns NULL. Lua ensures that different objects of the same type return different pointers. There is no direct way to convert the pointer back to its original value. Typically this function is used for debug information.



lua_tostring

Syntax: atom a = lua_tostring(atom L, integer idx)
Description: lua_tostring converts the Lua value at the given index to a string (const char*). The Lua value must be a string or a number; otherwise, the function returns NULL. If the value is a number, then lua_tostring also changes the actual value in the stack to a string. (This change confuses lua_next when lua_tostring is applied to keys.) lua_tostring returns a fully aligned pointer to a string inside the Lua state. This string always has a zero ('\0') after its last character (as in C), but may contain other zeros in its body. If you do not know whether a string may contain zeros, you can use lua_strlen to get its actual length. Because Lua has garbage collection, there is no guarantee that the pointer returned by lua_tostring will be valid after the corresponding value is removed from the stack. If you need the string after the current function returns, then you should duplicate it or put it into the registry.



lua_tothread

Syntax: atom a = lua_tothread(atom L, integer idx)
Description: lua_tothread converts a value in the stack to a Lua thread (represented as atom L). This value must be a thread; otherwise, lua_tothread returns NULL.



lua_touserdata

Syntax: lua_touserdata(atom L, integer idx)
Description: lua_touserdata retrieves the value of a userdata. When applied on a full userdata, it returns the address of its block; when applied on a light userdata, it returns its pointer; when applied on a non-userdata value, it returns NULL.
Comments: Userdata represents C values in Lua. Lua supports two types of userdata: full userdata and light userdata. A full userdata represents a block of memory. It is an object (like a table): You must create it, it can have its own metatable, and you can detect when it is being collected. A full userdata is only equal to itself (under raw equality). A light userdata represents a pointer. It is a value (like a number): You do not create it, it has no metatables, it is not collected (as it was never created). A light userdata is equal to "any" light userdata with the same C address. In Lua code, there is no way to test whether a userdata is full or light; both have type userdata. In C code, lua_type returns LUA_TUSERDATA for full userdata, and LUA_TLIGHTUSERDATA for light userdata.
See Also: lua_newuserdata



lua_type

Syntax: atom a = lua_type(atom L, integer idx)
Description: Returns the type of a value in the stack. The types returned by lua_type are accessed using lua_typename, and passing the value received from lua_type.
See Also: lua_typename



lua_typename

Syntax: sequence s = lua_typename(atom L, integer type)
Description: Returns a string name for the value that is passed. The type value should be one gotten from lua_type.



lua_version

Syntax: sequence s = lua_version()
Description: Returns a string containing the lua version.



lua_xmove

Syntax: lua_xmove(atom from_state, atom to_state, integer n)
Description: To exchange values between different threads, you use lua_xmove. It pops n values from the stack from_state, and pushes them into the stack to_state.



lua_yield

Syntax: atom a = lua_yield(atom L, integer nresults)
Description: The lua_yield function can only be called as the return expression of a function, as follows: return lua_yield (L, nresults). When a C function calls lua_yield in that way, the running coroutine suspends its execution, and the call to lua_resume that started this coroutine returns. The parameter nresults is the number of values from the stack that are passed as results to lua_resume.



luaopen_base

Syntax: atom a = luaopen_base(atom L)
Description: Open base library.



luaopen_debug

Syntax: atom a = luaopen_debug(atom L)
Description: Open debug library.



luaopen_io

Syntax: atom a = luaopen_io(atom L)
Description: Open io library.



luaopen_loadlib

Syntax: atom a = luaopen_loadlib(atom L)
Description: Open loadlib library.



luaopen_math

Syntax: atom a = luaopen_math(atom L)
Description: Open math library.



luaopen_string

Syntax: atom a = luaopen_string(atom L)
Description: Open io library.



luaopen_table

Syntax: atom a = luaopen_table(atom L)
Description: Open table library.