diff options
| -rw-r--r-- | README.md | 268 |
1 files changed, 3 insertions, 265 deletions
@@ -15,7 +15,7 @@ Table of contents ----------------- - [Installation](#installation) -- [Usage](#usage) +- [Documentation](#documentation) - [Development](#development) - [License](#license) - [Footer](#footer) @@ -38,272 +38,10 @@ To make the tests as well, do the above and then do `make test`. You should now be able to include `<honeysuckle.h>` into your C files for use. -Usage +Documentation ----- -[(Back to top)](#table-of-contents) - -- [Type constants](#type-constants) -- [Argument parsing](#argument-parsing) - - [Overloading](#overloading) -- [Table construction](#table-construction) - - [Enums](#enums) -- [Table processing](#table-processing) -- [Errors and error handling](#errors-and-error-handling) -- [String wrangling](#string-wrangling) -- [Registry values](#registry-values) - -### Type constants - -[(Back to top)](#table-of-contents) - -These constants are used when honeysuckle needs to know a type to -expect. - -- `HS_BOOL` - booleans -- `HS_INT` - lua_Integer (DO NOT use int, long int, or other types!) -- `HS_NUM` - lua_Number (DO NOT use float, double, or other types!) -- `HS_STR` - strings -- `HS_TBL` - tables -- `HS_FUNC` - any function -- `HS_CFUNC` - C functions specifically -- `HS_USER` - lua full userdata -- `HS_LIGHT` - lua light userdata -- `HS_NIL` - lua's nil -- `HS_ANY` - any type - -`hs_type_to_string()` takes as argument a single type constant and -returns a const string representing the type. - -For the numeric types (`HS_INT` and `HS_NUM`, using variables other -than `lua_Integer` and `lua_Number` may result in undefined behavior. - -### Argument parsing - -[(Back to top)](#table-of-contents) - -`hs_parse_args()` is the primary argument-parsing function. It -accepts as arguments a lua_State pointer, any number of -`struct hs_arg`s. These can either be constructed by hand or with -function-like macros identified by the lowercase version of the type -names from the section above. Use of the macros is recommended as -they will likely reduce type mismatch errors (e.g. giving HS_BOOL as -type but providing a pointer to a string). - -This function performs typechecking and in case of an error throws -with helpful error messages. - -`HS_TBL`, `HS_FUNC`, `HS_NIL`, and `HS_ANY` take a pointer to an -integer that will be filled with the stack index of the argument. - -Please note that, due to technical limitations, this function can -only parse up to 255 arguments. This function may mutate any -preexisting contents of the variables passed to contain the -arguments. - -```c -int some_lua_binding(lua_State *L) -{ - bool b; - lua_Integer i; - int tbl_index; - lua_Number n; - char *str; - void* user; - hs_parse_args(L, - // explicit initializer for struct - { HS_BOOL, .ptr.bool = &b }, - // macro initialization (recommended) - hs_int(i), - hs_tbl(tbl_index), - hs_num(n), - hs_str(str), - hs_user(user) - ); - // do something... - return 1; -} -``` - -#### Overloading - -There is another function, `hs_parse_overloaded()`, that permits -overloaded argument parsing. Its syntax is exactly as -`hs_parse_args()` except that each overload option must be wrapped -in the macro `hs_overload()`. This function returns an integer -containing the zero-indexed index of the overload option that was -actually used. - -Please note that because of Lua's type system, overloads that differ -only in an integer/number pair, function/c function pair, or -userdata/light userdata pair in the same position may not work as -expected. - -If none of the argument lists match the provided arguments, this -function throws an error. - -This function may mutate preexisting data in the variables passed to -store arguments. - -```c -int overloaded_lua_binding(lua_State *L) -{ - lua_Integer i; - lua_Number n; - char *str; - int choice = hs_parse_overloaded(L, - hs_overload( hs_int(i) ), - hs_overload( hs_str(str), hs_num(n) ) - ); - if (choice == 0) { - // do something with i - // str and n remain unassigned!! - } - else { - // choice == 1, do something with str and n - // i remains unassigned!! - } - return 0; -} -``` - -### Table construction - -[(Back to top)](#table-of-contents) - -`hs_create_table()` takes a lua_State pointer and then up to 255 ` -struct hs_tbl_entry`s. These can either be constructed by hand, or -via function-like macros identified by lowercase versions of the -typenames shown above (e.g. `hs_str_int` would create a string key -with integer value). Most of the type constants expect their -associated type (e.g. `HS_INT` expects a `lua_Integer`, `HS_CFUNC` expects ` -lua_CFunction`, etc.) but `HS_FUNC`, `HS_USER`, and `HS_TBL` expect -an integer stack index. You cannot use `HS_NIL` or `HS_ANY` with -this function. - -This function returns the stack index of the newly created table, -and automatically pops any stack indices provided to it. - -```c -int *ptr; // some pointer - -hs_create_table(L, - // manual struct initialization - { HS_STR, .key.string="intVal", HS_INT, .value.integer=4 }, - // macro initialization (recommended) - hs_str_num("numVal", 6.0f), - hs_int_tbl(12, hs_create_table(L, - hs_str_cfunc("subTableCFunc", some_lua_binding), - hs_int_bool(15, true), - ) -); -``` - -### Table processing - -[(Back to top)](#table-of-contents) - -`hs_process_table()` is intended for creating lua bindings that can -be called like `set_config{ debug=true, verbosity=2, -logfile='run.log' }`. It operates only on values with string keys -and boolean, number, or string types. `hs_process_table()` accepts a -lua_State pointer, a stack index for the table to operate on, and -then a series of `struct hs_table_processor`s. These can either be -constructed manually, or via function-like macros. This function -does not pop the table from the stack. - -honeysuckle provides the functions `hs_pt_set_bool`, -`hs_pt_set_int`, `hs_pt_set_num`, and `hs_pt_set_string` for the -very common operations of "set a variable to the provided value". -These can also be set via the function-like macros `hs_set_bool()`, -`hs_set_int()`, `hs_set_num()`, and `hs_set_str()`. - -User-defined functions should have signature -`void (function)([type], void *)`, where [type] is either -`lua_Boolean`, `lua_Integer`, `lua_Number`, or `const char *`, -depending on the expected value type. - - -```c -void open_logfile(const char *logfile, void *settings) { - // do something to open and configure the logfile -} - -// tbl_index comes from somewhere... - -struct settings { - bool debug; - lua_Integer verbosity; - float epsilon; -}; - -struct settings s; - -hs_process_table(L, tbl_index, - // manual struct initialization - { "verbosity", HS_INT, .func.integer=hs_pt_set_int, &(s.verbosity) }, - // macro initialization (recommended) - hs_process_bool("debug", hs_pt_set_bool, s.debug), - hs_process_str("logfile", set_logfile, s), - // alternative to explicitly specifying hs_pt_set_bool - hs_set_num("epsilon", s.epsilon) -); -``` - -### Errors and error handling - -[(Back to top)](#table-of-contents) - -`hs_throw_error()` constructs and throws error messages like -printf. - -```c -hs_throw_error(L, "ERROR: %d is not within range", 10); -``` - -`hs_traceback()` can be supplied to `lua_pcall()` to get a helpful -stack trace error message: - -```c -lua_pushcfunction(L, hs_traceback); -int tr_pos = lua_gettop(); - -// push function -// push n arguments -int result = lua_pcall(L, nargs, nret, tr_pos); -``` - -`hs_call()` performs the above, accepting simply a lua_State -pointer, int nargs, and int nret as arguments. - - -### String wrangling - -[(Back to top)](#table-of-contents) - -`hs_pushstring()` allows you to push string values using printf format -strings. - -```c -hs_pushstring(L, "hello there, %s. I hear the current time is %d:%02d", "dylan", 10, 5); -``` - -### Registry values - -[(Back to top)](#table-of-contents) - -honeysuckle provides three macros, `hs_rstore()`, `hs_rload()`, and `hs_ -rdel()` to make registry access easier. These are mostly just thin wrappers -around `luaL_ref()`, `luaL_unref()` and `lua_rawgeti()` but they come up -frequently enough that I think these are helpful. - -```c -lua_pushstring(L, "some string"); -int my_string_ref = hs_rstore(L); -// ... -hs_rload(L, my_string_ref); // load the value referenced by my_string_ref -hs_rdel(L, my_string_ref); // done with this reference, remove from the registry table -``` +You can view the honeysuckle documentation [on the honey wiki](https://honey3d.org/wiki/doku.php?id=honeysuckle). Development ----------- |