-
Notifications
You must be signed in to change notification settings - Fork 0
Pawn API
For use in Pawn, YALP exports the majority the Lua C API, adapted in some places to Pawn. Since most of the functions behave exactly like the original ones, it is better to read the Lua Reference Manual, or the include file. Only the functions which differ from the originals are listed in this section.
Since handling errors between Pawn and Lua code is tricky, you should only use these functions to create and destroy a Lua instance, and provide Pawn functions which cannot be ported to Lua. Public and native functions are usable from pure Lua as well (via the interop package). Pawn code operating with Lua should take care of handling all error situations and managing the validity of the Lua instance.
native Lua:lua_newstate(lua_lib:load=lua_baselibs, lua_lib:preload=lua_newlibs, memlimit=-1);Creates a new Lua instance, specifying optionally the base packages that should be loaded in the environment table, and other packages that are available via require. memlimit (kilobytes) may be specified as well to set the maximum memory capacity of the Lua instance (allocations past the limit will fail).
The result of this function is a Lua handle, or Lua:0 on failure.
native bool:lua_close(Lua:L);Closes the Lua instance and destroys all memory associated with it. Do not call this function when there is code running in the instance (i.e. when the stack contains a function called by Lua).
When the current script is bound to a Lua instance via lua_bind, calling this is not needed, as the instance is destroyed when the script is unloaded.
native lua_status:lua_load(Lua:L, const reader[], data, bufsize=-1, chunkname[]="");Repeatedly calls a Pawn function (whose name is in reader) to load a Lua chunk. YALP allocates a buffer of size bufsize on the heap and passes it to the function. The public function should have this signature:
forward lua_reader(Lua:L, buffer[], data, size);data is not used by YALP and only serves as an additional parameter to the function, and size is the size of the allocated buffer in cells. YALP will repeatedly call the function and expects it to provide pieces of a Lua chunk via buffer. Since a chunk can be stored in both binary and textual form, buffer should contain raw bytes of the chunk and not a string. The function can return a positive integer, indicating the size of the provided chunk in bytes, or 0, indicating the end of the chunk. If the function returns a negative integer, it represents the negated size of the final piece of the chunk (so the function will not be called again).
The resulting chunk is parsed and pushed on the stack as a Lua function.
native lua_stackdump(Lua:L, depth=-1);Prints depth elements from the Lua stack (top to bottom), useful for debug.
native lua_tostring(Lua:L, idx, buffer[], size=sizeof(buffer));Obtains the textual representation of a Lua value at idx on the stack. If it is not a number or a string, it calls tostring first on it.
native lua_pushpfunction(Lua:L, const f[]);Pushes a function to the Lua stack with its implementation in a public function whose name is passed in f. When the function is called from Lua, the public function is found and executed. The function should have the following signature:
forward lua_pfunction(Lua:L);Creating this function is similar to the C API. All passed arguments are present on the stack and must be marshalled via the API to Pawn values. The function should return an integer specifying the number of return values from the top of the stack that are returned.
native lua_bind(Lua:L);If a function is on top of the Lua stack, and the interop module has not been loaded yet, calling this function terminates the execution of the Pawn script and reroutes all AMX calls to the Lua instance. Its lifetime will be bound to the original Pawn program (filterscript or gamemode), which will be blocked from executing any other code.
This function makes it possible to run Lua code as a gamemode, and is useful if you want to decrease the number of used filterscripts (since the interop package must create a new one for it to work properly).
stock lua_status:lua_loadfile(Lua:L, const name[], lua_load_mode:mode=lua_load_text)
stock lua_status:lua_dofile(Lua:L, const name[], lua_load_mode:mode=lua_load_text)Opens a file (via fopen) and loads it as a Lua chunk, and (in case of lua_dofile) executes it. Returns the error code if an error occured during parsing or executing the chunk, or LUA_OK in case of no errors.
native lua_status:lua_loadstream(Lua:L, File:file, const chunkname[], lua_load_mode:mode=lua_load_text);Loads a Lua chunk from a stream represented by a file pointer. The file is not closed when the reading is done.
native LuaLoader:lua_loader(Lua:L, const chunkname[], lua_load_mode:mode=lua_load_text);This function is similar to lua_load, but instead of using a function to provide the respective chunk pieces, it creates a new instance of the parser which receives the pieces via lua_write.
native lua_status:lua_write(LuaLoader:stream, const data[], size=-1);Writes a piece of a Lua chunk to a parser instance. If size is equal to -1, it is computed as the string length of data. If the size of the data is 0, it represents the end of the stream and automatically closes the parser instance.
When more chunk fragments are expected, this function returns LUA_YIELD. Otherwise, it returns LUA_OK when the parsing is finished, or another error code on failure. In both these cases, the parser instance is automatically destroyed, and the resulting function (or error message) is placed on the Lua stack.
The stack should be left unmodified between calls to lua_write, since it may contain intermediate state of the parser.
native Pointer:lua_pushuserdata(Lua:L, const data[], size=sizeof(data));Allocates a new block of size cells in the Lua memory manager, and pushes it on the stack as a new userdata. This function returns a pointer that can be used to identify this userdata.
native lua_getuserdata(Lua:L, idx, data[], size=sizeof(data));Copies the contents of a userdata instance on the stack at idx to data. Returns the number of copied cells.
native lua_setuserdata(Lua:L, idx, const data[], size=sizeof(data));Copies the contents from data to a userdata instance on the stack at idx. The size of the userdata is not changed, hence if the size of data is larger than that of the userdata, the exceeding cells are not copied. Returns the number of copied cells.