honey3d Wiki

User Tools

Site Tools

Trace:
honeysuckle

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
honeysuckle [2021/09/14 19:33]
sanine [hs_pushstring] 		honeysuckle [2021/09/14 20:18] (current)
sanine [hs_process_table]
Line 1: Line 1:
 ====== honeysuckle ====== ====== honeysuckle ======
  
-honeysuckle is a C library intended to make creating Lua bindings simpler. It was originally a core part of the honey code, but was split out into its own library because it is useful in many other contexts. It provides functions for argument parsing, table creation and processing, error throwing and handling, and string wrangling.+honeysuckle is a C library intended to make creating Lua bindings simpler. It was originally a core part of the honey code, but was split out into its own library because it is useful in many other contexts. It provides functions for argument parsing, table creation and processing, error throwing and handling, string wrangling, and registry operations.
  
 ===== hs_parse_args ===== ===== hs_parse_args =====
Line 45: Line 45:
  
 === Example === === Example ===
 +
 +The following would be used to create a Lua function that expects arguments like ''(number, string, table)''.
  
 <code C> <code C>
Line 174: Line 176:
 === Stack Modifications === === Stack Modifications ===
  
-[-0, +0, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>+[-0, +0, e]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
  
 === Parameters === === Parameters ===
Line 197: Line 199:
  
 For the extremely common case of simply setting a variable, there are provided the functions ''hs_pt_set_bool'', ''hs_pt_set_int'', ''hs_pt_set_num'', and ''hs_pt_set_str'', which will cast the provided void pointer to ''bool'', ''lua_Integer'', ''lua_Number'', or ''const char *'', respectively, and then set that value to the value in the table. For the extremely common case of simply setting a variable, there are provided the functions ''hs_pt_set_bool'', ''hs_pt_set_int'', ''hs_pt_set_num'', and ''hs_pt_set_str'', which will cast the provided void pointer to ''bool'', ''lua_Integer'', ''lua_Number'', or ''const char *'', respectively, and then set that value to the value in the table.
 +
 +This function may throw an error if the provided index is not valid or is not a table. It may trigger metamethods in extracting values.
  
 === Example === === Example ===
Line 234: Line 238:
 === Stack Modifications === === Stack Modifications ===
  
-[-0, +1, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>+[-0, +1, m]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
  
 === Parameters === === Parameters ===
Line 240: Line 244:
   * ''L'': The Lua state to operate on.   * ''L'': The Lua state to operate on.
   * ''format_string'': A printf format string to construct the string to push.   * ''format_string'': A printf format string to construct the string to push.
-  * ''...'': List printf format options.+  * ''...'': printf format options. 
 + 
 +=== Return Value === 
 + 
 +None.
  
 === Description === === Description ===
Line 254: Line 262:
 hs_pushstring(L, "hello, %s. the current time is %d:%02d.", name, hours, minutes); hs_pushstring(L, "hello, %s. the current time is %d:%02d.", name, hours, minutes);
 </code> </code>
 +
 +===== hs_vpushstring =====
 +
 +<code C>
 +void hs_vpushstring(
 +    lua_State *L,
 +    const char *format_string,
 +    va_list args);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-0, +0, m]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': The Lua state to operate on.
 +  * ''format_string'': A printf format string to construct the string to push.
 +  * ''args'': List of printf options in a variadic argument list.
 +
 +=== Return Value ===
 +
 +None.
 +
 +=== Description ===
 +
 +Similar to ''hs_pushstring()'' above. Its syntax is exactly that of vsprintf, except the destination is a ''lua_State'' pointer, rather than a string buffer.
 +
 +===== hs_throw_error =====
 +
 +<code C>
 +void hs_vpushstring(
 +    lua_State *L,
 +    const char *format_string,
 +    ...);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-0, +0, v]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': The Lua state to operate on.
 +  * ''format_string'': A printf format string to construct the string to push.
 +  * ''...'': printf options.
 +
 +=== Return Value ===
 +
 +None, but by its nature this function will not return and instead makes a long jump to the current error handler.
 +
 +=== Description ===
 +
 +Similar to ''hs_pushstring()'' above, but pushes the string and then immediately throws an error with it. Useful for constructing complex error messages. This function may also throw a memory-related error if string creation fails.
 +
 +===== hs_traceback =====
 +
 +<code C>
 +void hs_traceback(lua_State *L);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-(0|1), +(0|1), -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': the Lua state to inspect
 +
 +
 +=== Return Value ===
 +
 +None.
 +
 +=== Description ===
 +
 +This function produces a call traceback string to go with an error message provided to it, or keeps the "error message" intact if it is not a string. It is generally not intended to be called manually, but rather provided to ''lua_pcall()'' as an error handler.
 +
 +===== hs_call =====
 +
 +<code C>
 +int hs_call(
 +    lua_State *L, 
 +    int nargs, 
 +    int nret);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-(nargs+1), +(nret|1), -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': the Lua state to call within.
 +  * ''nargs'': the number of arguments to pop from the stack.
 +  * ''nret'': the number of return values to push to the stack.
 +
 +=== Return Value ===
 +
 +0 on success, or else one of the Lua error codes: ''LUA_ERRRUN'', ''LUA_ERRMEM'', or ''LUA_ERRERR''.
 +
 +=== Description ===
 +
 +This function is exactly the same as ''lua_pcall'', with the same return values, except that it automatically pushes ''hs_traceback()'' to use as an error handler and does not accept a different error handler.
 +
 +===== hs_rstore =====
 +
 +<code C>
 +int hs_rstore(lua_State *L);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-1, +0, m]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': the Lua state to operate on.
 +
 +=== Return Value ===
 +
 +The reference key.
 +
 +=== Description ===
 +
 +This is a macro wrapper around ''luaL_ref()'' that always uses the Lua registry table. It is provided for convenience.
 +
 +===== hs_rload =====
 +
 +<code C>
 +void hs_rload(
 +    lua_State *L,
 +    int reference);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-0, +1, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': the Lua state to operate on.
 +  * ''reference'': A reference key returned by ''hs_rstore()''.
 +
 +=== Return Value ===
 +
 +None.
 +
 +=== Description ===
 +
 +This is a macro wrapper around ''lua_rawgeti()'' that always gets values from the Lua registry table. It is provided for convenience.
 +
 +===== hs_rdel =====
 +
 +<code C>
 +void hs_rdel(
 +    lua_State *L,
 +    int reference);
 +</code>
 +
 +=== Stack Modifications ===
 +
 +[-0, +0, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
 +
 +=== Parameters ===
 +
 +  * ''L'': the Lua state to operate on.
 +  * ''reference'': a reference key returned by ''hs_rstore()''.
 +
 +=== Return Value ===
 +
 +The reference key.
 +
 +=== Description ===
 +
 +This is a macro wrapper around ''luaL_unref()'' that always uses the Lua registry table. It is provided for convenience.
honeysuckle.1631647988.txt.gz · Last modified: 2021/09/14 19:33 by sanine

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki