aboutsummaryrefslogtreecommitdiff
path: root/luaT/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'luaT/README.md')
-rw-r--r--luaT/README.md239
1 files changed, 0 insertions, 239 deletions
diff --git a/luaT/README.md b/luaT/README.md
deleted file mode 100644
index 6e9cf0d..0000000
--- a/luaT/README.md
+++ /dev/null
@@ -1,239 +0,0 @@
-<a name="luat.dok"/>
-# Lua Torch C API #
-
-luaT provides an API to interface Lua and C in Torch packages. It defines a
-concept of _classes_ to Lua for Torch, and provides a mechanism to easily
-handle these Lua classes from C.
-
-It additionally provides few functions that `luaL` should have defined, and
-defines several functions similar to `luaL` ones for better type error printing when using
-`luaT` classes.
-
-<a name="luat.memory.dok"/>
-## Memory functions ##
-
-Classical memory allocation functions which generate a Lua error in case of
-problem.
-
-<a name="luaT_alloc"/>
-### void* luaT_alloc(lua_State *L, long size) ###
-
-Allocates `size` bytes, and return a pointer on the allocated
-memory. A Lua error will be generated if running out of memory.
-
-<a name="luaT_realloc"/>
-### void* luaT_realloc(lua_State *L, void *ptr, long size) ###
-
-Realloc `ptr` to `size` bytes. `ptr` must have been previously
-allocated with [luaT_alloc](#luaT_alloc) or
-[luaT_realloc](#luaT_realloc), or the C `malloc` or `realloc`
-functions. A Lua error will be generated if running out of memory.
-
-<a name="luaT_free"/>
-### void luaT_free(lua_State *L, void *ptr) ###
-
-Free memory allocated at address `ptr`. The memory must have been
-previously allocated with [luaT_alloc](#luaT_alloc) or
-[luaT_realloc](#luaT_realloc), or the C `malloc` or `realloc`
-functions.
-
-<a name="luat.classcreate"/>
-## Class creation and basic handling ##
-
-A `luaT` class is basically either a Lua _table_ or _userdata_ with
-an appropriate _metatable_. This appropriate metatable is created with
-[luaT_newmetatable](#luaT_newmetatable). Contrary to luaL userdata
-functions, luaT mechanism handles inheritance. If the class inherit from
-another class, then the metatable will itself have a metatable
-corresponding to the _parent metatable_: the metatables are cascaded
-according to the class inheritance. Multiple inheritance is not supported.
-
-<a name="luat.operatoroverloading"/>
-### Operator overloading ###
-
-The metatable of a `luaT` object contains `Lua` operators like
-`__index`, `__newindex`, `__tostring`, `__add`
-(etc...). These operators will respectively look for `__index__`,
-`__newindex__`, `__tostring__`, `__add__` (etc...) in the
-metatable. If found, the corresponding function or value will be returned,
-else a Lua error will be raised.
-
-If one wants to provide `__index__` or `__newindex__` in the
-metaclass, these operators must follow a particular scheme:
-
- * `__index__` must either return a value _and_ `true` or return `false` only. In the first case, it means `__index__` was able to handle the given argument (for e.g., the type was correct). The second case means it was not able to do anything, so `__index` in the root metatable can then try to see if the metaclass contains the required value.
-
- * `__newindex__` must either return `true` or `false`. As for `__index__`, `true` means it could handle the argument and `false` not. If not, the root metatable `__newindex` will then raise an error if the object was a userdata, or apply a rawset if the object was a Lua table.
-
-Other metaclass operators like `__tostring__`, `__add__`, etc... do not have any particular constraint.
-
-<a name="luat_newmetatable"/>
-### const char* luaT_newmetatable(lua_State *L, const char *tname, const char *parenttname, lua_CFunction constructor, lua_CFunction destructor, lua_CFunction factory) ###
-
-This function creates a new metatable, which is the Lua way to define a new
-object class. As for `luaL_newmetatable`, the metatable is registered in
-the Lua registry table, with the key `tname`. In addition, `tname` is
-also registered in the Lua registry, with the metatable as key (the
-typename of a given object can be thus easily retrieved).
-
-The class name `tname` must be of the form `modulename.classname`. The module name
-If not NULL, `parenttname` must be a valid typename corresponding to the
-parent class of the new class.
-
-If not NULL, `constructor`, a function `new` will be added to the metatable, pointing to this given function. The constructor might also
-be called through `modulename.classname()`, which is an alias setup by `luaT_metatable`.
-
-If not NULL, `destructor` will be called when garbage collecting the object.
-
-If not NULL, `factory` must be a Lua C function creating an empty object
-instance of the class. This functions are used in Torch for serialization.
-
-Note that classes can be partly defined in C and partly defined in Lua:
-once the metatable is created in C, it can be filled up with additional
-methods in Lua.
-
-The return value is the value returned by [luaT_typenameid](#luat_typenameid).
-
-<a name="luat_pushmetatable"/>
-### int luaT_pushmetatable(lua_State *L, const name *tname) ###
-
-Push the metatable with type name `tname` on the stack, it `tname` is a
-valid Torch class name (previously registered with luaT_newmetatable).
-
-On success, returns 1. If `tname` is invalid, nothing is pushed and it
-returns 0.
-
-<a name="luat_typenameid"/>
-### const char* luaT_typenameid(lua_State *L, const char *tname) ###
-
-If `tname` is a valid Torch class name, then returns a unique string (the
-contents will be the same than `tname`) pointing on the string registered
-in the Lua registry. This string is thus valid as long as Lua is
-running. The returned string shall not be freed.
-
-If `tname` is an invalid class name, returns NULL.
-
-<a name="luat_typename"/>
-### const char* luaT_typename(lua_State *L, int ud) ###
-
-Returns the typename of the object at index `ud` on the stack. If it is
-not a valid Torch object, returns NULL.
-
-<a name="luat_pushudata"/>
-### void luaT_pushudata(lua_State *L, void *udata, const char *tname) ###
-
-Given a C structure `udata`, push a userdata object on the stack with
-metatable corresponding to `tname`. Obviously, `tname` must be a valid
-Torch name registered with [luaT_newmetatable](#luat_newmetatable).
-
-<a name="luat_toudata"/>
-### void *luaT_toudata(lua_State *L, int ud, const char *tname) ###
-
-Returns a pointer to the original C structure previously pushed on the
-stack with [luaT_pushudata](#luat_pushudata), if the object at index
-`ud` is a valid Torch class name. Returns NULL otherwise.
-
-<a name="luat_isudata"/>
-### int luaT_isudata(lua_State *L, int ud, const char *tname) ###
-
-Returns 1 if the object at index `ud` on the stack is a valid Torch class name `tname`.
-Returns 0 otherwise.
-
-<a name="luat_getfield"/>
-### Checking fields of a table ###
-
-This functions check that the table at the given index `ud` on the Lua
-stack has a field named `field`, and that it is of the specified type.
-These function raises a Lua error on failure.
-
-<a name="luat_getfieldcheckudata"/>
-## void *luaT_getfieldcheckudata(lua_State *L, int ud, const char *field, const char *tname) ##
-
-Checks that the field named `field` of the table at index `ud` is a
-Torch class name `tname`. Returns the pointer of the C structure
-previously pushed on the stack with [luaT_pushudata](#luat_pushudata) on
-success. The function raises a Lua error on failure.
-
-<a name="luat_getfieldchecklightudata"/>
-## void *luaT_getfieldchecklightudata(lua_State *L, int ud, const char *field) ##
-
-Checks that the field named `field` of the table at index `ud` is a
-lightuserdata. Returns the lightuserdata pointer on success. The function
-raises a Lua error on failure.
-
-<a name="luat_getfieldcheckint"/>
-## int luaT_getfieldcheckint(lua_State *L, int ud, const char *field) ##
-
-Checks that the field named `field` of the table at index `ud` is an
-int. Returns the int value pointer on success. The function raises a Lua
-error on failure.
-
-<a name="luat_getfieldcheckstring"/>
-## const char* luaT_getfieldcheckstring(lua_State *L, int ud, const char *field) ##
-
-Checks that the field named `field` of the table at index `ud` is a
-string. Returns a pointer to the string on success. The function raises a
-Lua error on failure.
-
-<a name="luat_getfieldcheckboolean"/>
-## int luaT_getfieldcheckboolean(lua_State *L, int ud, const char *field) ##
-
-Checks that the field named `field` of the table at index `ud` is a
-boolean. On success, returns 1 if the boolean is `true`, 0 if it is
-`false`. The function raises a Lua error on failure.
-
-<a name="luat_getfieldchecktable"/>
-## void luaT_getfieldchecktable(lua_State *L, int ud, const char *field) ##
-
-Checks that the field named `field` of the table at index `ud` is a
-table. On success, push the table on the stack. The function raises a Lua
-error on failure.
-
-<a name="luat_typerror"/>
-### int luaT_typerror(lua_State *L, int ud, const char *tname) ###
-
-Raises a `luaL_argerror` (and returns its value), claiming that the
-object at index `ud` on the stack is not of type `tname`. Note that
-this function does not check the type, it only raises an error.
-
-<a name="luat_checkboolean"/>
-### int luaT_checkboolean(lua_State *L, int ud) ###
-
-Checks that the value at index `ud` is a boolean. On success, returns 1
-if the boolean is `true`, 0 if it is `false`. The function raises a Lua
-error on failure.
-
-<a name="luat_optboolean"/>
-### int luaT_optboolean(lua_State *L, int ud, int def) ###
-
-Checks that the value at index `ud` is a boolean. On success, returns 1
-if the boolean is `true`, 0 if it is `false`. If there is no value at
-index `ud`, returns `def`. In any other cases, raises an error.
-
-<a name="luat_registeratname"/>
-### void luaT_registeratname(lua_State *L, const struct luaL_Reg *methods, const char *name) ###
-
-This function assume a table is on the stack. It creates a table field
-`name` in the table (if this field does not exist yet), and fill up
-`methods` in this table field.
-
-<a name="luat_classrootname"/>
-### const char *luaT_classrootname(const char *tname) ###
-
-Assuming `tname` is of the form `modulename.classname`, returns
-`classname`. The returned value shall not be freed. It is a pointer
-inside `tname` string.
-
-<a name="luat_classmodulename"/>
-### const char *luaT_classmodulename(const char *tname) ###
-
-Assuming `tname` is of the form `modulename.classname`, returns
-`modulename`. The returned value shall not be freed. It is valid until the
-next call to `luaT_classrootname`.
-
-<a name="luat_stackdump"/>
-### void luaT_stackdump(lua_State *L) ###
-
-This function print outs the state of the Lua stack. It is useful for debug
-purposes.
-