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:57]
sanine [hs_traceback] 		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 176: Line 176:
 === Stack Modifications === === Stack Modifications ===
  
-[-0, +0, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>+[-0, +0, e]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
  
 === Parameters === === Parameters ===
Line 199: 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 236: Line 238:
 === Stack Modifications === === Stack Modifications ===
  
-[-0, +1, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>+[-0, +1, m]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
  
 === Parameters === === Parameters ===
Line 243: Line 245:
   * ''format_string'': A printf format string to construct the string to push.   * ''format_string'': A printf format string to construct the string to push.
   * ''...'': printf format options.   * ''...'': printf format options.
 +
 +=== Return Value ===
 +
 +None.
  
 === Description === === Description ===
Line 268: Line 274:
 === Stack Modifications === === Stack Modifications ===
  
-[-0, +0, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>+[-0, +0, m]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
  
 === Parameters === === Parameters ===
Line 275: Line 281:
   * ''format_string'': A printf format string to construct the string to push.   * ''format_string'': A printf format string to construct the string to push.
   * ''args'': List of printf options in a variadic argument list.   * ''args'': List of printf options in a variadic argument list.
 +
 +=== Return Value ===
 +
 +None.
  
 === Description === === Description ===
Line 291: Line 301:
 === Stack Modifications === === Stack Modifications ===
  
-[-0, +0, -]<sup>[//[[Stack Modification Indicator|?]]//]</sup>+[-0, +0, v]<sup>[//[[Stack Modification Indicator|?]]//]</sup>
  
 === Parameters === === Parameters ===
Line 298: Line 308:
   * ''format_string'': A printf format string to construct the string to push.   * ''format_string'': A printf format string to construct the string to push.
   * ''...'': printf options.   * ''...'': 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 === === Description ===
  
-Similar to ''hs_pushstring()'' above, but pushes the string and then immediately throws an error with it. Useful for constructing complex error messages.+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 ===== ===== hs_traceback =====
Line 316: Line 330:
  
   * ''L'': the Lua state to inspect   * ''L'': the Lua state to inspect
 +
 +
 +=== Return Value ===
 +
 +None.
  
 === Description === === Description ===
Line 339: Line 358:
   * ''nargs'': the number of arguments to pop from the stack.   * ''nargs'': the number of arguments to pop from the stack.
   * ''nret'': the number of return values to push to 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 === === 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. 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.1631649448.txt.gz ยท Last modified: 2021/09/14 19:57 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