diff options
author | Ronan Collobert <ronan@collobert.com> | 2012-02-07 22:39:56 +0400 |
---|---|---|
committer | Ronan Collobert <ronan@collobert.com> | 2012-02-07 22:39:56 +0400 |
commit | 742b834090588af4e32015f44ee80f6fa2ed6c61 (patch) | |
tree | 841dfe6a863ad7b121e227dfec52c8dbb76c6b19 | |
parent | e79a02893ec9b8e0e49fbc08d5c79b9ed3f9a65c (diff) |
started wrap dok
-rw-r--r-- | CMakeLists.txt | 2 | ||||
-rw-r--r-- | dok/index.dok | 49 |
2 files changed, 50 insertions, 1 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index f5bda18..c359d44 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -2,4 +2,4 @@ SET(src) SET(luasrc init.lua types.lua) ADD_TORCH_PACKAGE(wrap "${src}" "${luasrc}") -#ADD_TORCH_DOK(dok gnuplot "Fundamentals" "Plotting with Gnuplot" 1.) +ADD_TORCH_DOK(dok wrap "Fundamentals" "Lua/C automatic wrapper generation" 1.) diff --git a/dok/index.dok b/dok/index.dok new file mode 100644 index 0000000..e5a503a --- /dev/null +++ b/dok/index.dok @@ -0,0 +1,49 @@ +====== Wrap package ====== + +The **wrap** package helps you to automate the generation of Lua/C wrappers +around existing C functions, such that these functions would be callable +from Lua. This package is used by the **torch** package, but does not depend on +anything, and could be used by anyone using Lua. + +**DISCLAIMER** Before going any further, we assume the reader has a good +knowledge of how to interface C functions with Lua. A good start would be +the [[http://www.lua.org/manual/5.1|Lua reference manual]], or the book +[[http://www.inf.puc-rio.br/~roberto/pil2|Programming in Lua]]. + +As an example is often better than lengthy explanations, let's consider the +case of a function +<file c> +int numel(THDoubleTensor *t); +</file> +which returns the number of elements of ''t''. +Writing a complete wrapper of this function would look like: +<file c> +int wrapper_numel(lua_State *L) +{ + THDoubleTensor *t; + + /* always good to check the number of arguments */ + if(lua_gettop(L) != 1) + error("invalid number of arguments: <tensor> expected"); + + /* check if we have a tensor on the stack */ + /* we use the luaT library, which deals with Torch objects */ + /* we assume the torch_DoubleTensor_id has been already initialized */ + t = luaT_checkudata(L, 1, torch_DoubleTensor_id); + + /* push result on stack */ + lua_pushnumber(L, numel(t)); + + /* the number of returned variables */ + return 1; +} +</file> + +For anybody familiar with the Lua C API, this should look very simple (and +//it is simple//, Lua has been designed for that!). Nevertheless, the +wrapper contains about 7 lines of C code, for a quite simple +function. Writing wrappers for C functions with multiple arguments, where +some of them might be optional, can become very quickly a tedious task. The +**wrap** package is here to help the process. Remember however that even +though you might be able to treat most complex cases with **wrap**, +sometimes it is also good to do everything by hand yourself! |