update README.md to reflect the wiki documentation

1 files changed, 3 insertions, 265 deletions

diff --git a/README.md b/README.md
index 57a2f84..df29673 100644
--- a/README.md
+++ b/README.md
@@ -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
 -----------