From 6181f8bb8d288066d6328258f5f9416da21c24ee Mon Sep 17 00:00:00 2001 From: satoren Date: Mon, 8 Aug 2016 17:38:55 +0900 Subject: [PATCH] writing documents --- docs/api_reference/index.rst | 3 + docs/api_reference/luaref.rst | 6 +- docs/api_reference/metatable.rst | 7 ++ docs/api_reference/preprocessor_option.rst | 67 +++++++++++++++ docs/api_reference/standard.rst | 35 ++++++++ docs/api_reference/state.rst | 4 + docs/getting_started/class_bindings.rst | 99 ++++++++++++++++++++++ docs/getting_started/index.rst | 1 + docs/getting_started/tutorial.rst | 10 +-- include/kaguya/metatable.hpp | 2 + include/kaguya/state.hpp | 2 +- 11 files changed, 227 insertions(+), 9 deletions(-) create mode 100644 docs/api_reference/metatable.rst create mode 100644 docs/api_reference/preprocessor_option.rst create mode 100644 docs/api_reference/standard.rst create mode 100644 docs/getting_started/class_bindings.rst diff --git a/docs/api_reference/index.rst b/docs/api_reference/index.rst index 8700940..a2b79ec 100644 --- a/docs/api_reference/index.rst +++ b/docs/api_reference/index.rst @@ -5,5 +5,8 @@ API Reference .. toctree:: :maxdepth: 2 + preprocessor_option state + metatable luaref + standard diff --git a/docs/api_reference/luaref.rst b/docs/api_reference/luaref.rst index f71d7f2..b82660a 100644 --- a/docs/api_reference/luaref.rst +++ b/docs/api_reference/luaref.rst @@ -2,8 +2,8 @@ LuaRef ================================== -LuaRef is referenceto lua value. -and retain reference count in Lua.It means not collect by gc. +LuaRef has strong reference to lua value. +It means not collect by gc. LuaRef has specialized 4 types. @@ -26,7 +26,7 @@ example state.dostring("mytable.value = 6");//assign new value state.dostring("mytable=nil");//remove from global table state.dostring("collectgarbage()");//run fullgc - v = table["value"];//v is 6. + v = table["value"];//v is 6. .. toctree:: :maxdepth: 1 diff --git a/docs/api_reference/metatable.rst b/docs/api_reference/metatable.rst new file mode 100644 index 0000000..dab9def --- /dev/null +++ b/docs/api_reference/metatable.rst @@ -0,0 +1,7 @@ + +UserdataMetatable +======================== + + +.. doxygenclass:: kaguya::UserdataMetatable + :members: diff --git a/docs/api_reference/preprocessor_option.rst b/docs/api_reference/preprocessor_option.rst new file mode 100644 index 0000000..6af7282 --- /dev/null +++ b/docs/api_reference/preprocessor_option.rst @@ -0,0 +1,67 @@ + +Preprocessor Options +================================== + +This option must be same between translation units. + +.. _preprocessor-use-cpp11: +* KAGUYA_USE_CPP11 + + | If defined 1, kaguya use C++11 feature. + | If defined 0, kaguya use C++03 only (need boost library). + | default is auto detect (using _MSC_VER or __cplusplus). + +| + +* KAGUYA_NO_USERDATA_TYPE_CHECK + + If defined 1, Skip type check for userdata created without kaguya. + + .. warning:: + + This option is dangerous to be used in conjunction with other Lua library. + + example: + + .. code-block:: lua + + --io.stdin is created by lua standard libray. + kaguya_binded_receive_userdata_fn(io.stdin) -- Error not detected. this is undefined behavior. + +| + +* KAGUYA_NO_VECTOR_AND_MAP_TO_TABLE + + If difined, std::map and std::vector will not be converted to a lua-table + +| + +* KAGUYA_NO_STD_VECTOR_TO_TABLE + + If difined, std::vector will not be converted to a lua-table + +| + +* KAGUYA_NO_STD_MAP_TO_TABLE + + If difined, std::map will not be converted to a lua-table + +| + +* KAGUYA_FUNCTION_MAX_ARGS + + Define max argument count for binding function. default is 9. + + .. note:: + + Effect in the C++03 only + +| + +* KAGUYA_FUNCTION_MAX_OVERLOADS + + Define max overloads function count for binding functions. default is 9. + + .. note:: + + Effect in the C++03 only diff --git a/docs/api_reference/standard.rst b/docs/api_reference/standard.rst new file mode 100644 index 0000000..1fe624f --- /dev/null +++ b/docs/api_reference/standard.rst @@ -0,0 +1,35 @@ + +kaguya::standard namespace +================================== + +This namespace store standard libraries. + +using boost library for not enough in C++03. + +In this way it has been defined in kaguya/config.hpp + +.. code-block:: c++ + + namespace kaguya + { + namespace standard + { + #if KAGUYA_USE_CPP11 + using namespace std; + #else + using namespace boost; + #endif + } + } + + +Used switched types +----------------------------- + +* tuple + + using multiple return value. + +* shared_ptr + + using shared_ptr assign. see :ref:`smartpointers`. diff --git a/docs/api_reference/state.rst b/docs/api_reference/state.rst index e954eaa..e2e999f 100644 --- a/docs/api_reference/state.rst +++ b/docs/api_reference/state.rst @@ -1,3 +1,7 @@ State ================================== +State is lua_State* wrapper class + +.. doxygenclass:: kaguya::State + :members: diff --git a/docs/getting_started/class_bindings.rst b/docs/getting_started/class_bindings.rst new file mode 100644 index 0000000..6eb80b4 --- /dev/null +++ b/docs/getting_started/class_bindings.rst @@ -0,0 +1,99 @@ + +Class Bindings +================================== +C++ classes binding use :doc:`/api_reference/metatable`. + + +A quick example +------------------------- + +Exposing classes to Lua + +.. code-block:: c++ + + //C++ + struct MyClass + { + MyClass():x(0),y() {} + MyClass(int x,const std::string& y):x(x),y(y) {} + void setX(int v){x=v;} + int getX()const{return x;} + void setY(const char* v){y=v;} + const std::string& getY()const{return y;} + private: + int x; + std::string y; + }; + + ... + state["MyClass"] = kaguya::UserdataMetatable() + .setConstructors() + .addFunction("setX", &MyClass::setX) + .addFunction("getX", &MyClass::getX) + .addProperty("y", &MyClass::getY, &MyClass::setY) + ; + + +Usage in Lua + +.. code-block:: lua + + local v = MyClass.new(4,'text') + print(v:getX()) -- output 4 + print(v.y) -- output 'text' + + + +Object lifetime +------------------------- + +Copy assign +^^^^^^^^^^^^^^^^^^^^^^ + + Basic assign. + Copy object and managing lifetime by Lua. + + example: + + .. code-block:: c++ + + { + MyClass myobj; + state["a"] = myobj; + } + state.dostring("print(a.y)");//myobj is destroyed, but a is living. + state["a"] = 0;//override a. + state.gc().collect(); //copied object is garbage collected. + +Pointer assign +^^^^^^^^^^^^^^^^^^^^^^ + + You need managing object lifetime by yourself. + + broken code example: + + .. code-block:: c++ + + MyClass* myptr = new MyClass(); + state["a"] = myptr; + delete myptr; + state.dostring("print(a.y)")// a is destroyed. This is undefined behavior as dangling pointer. + + +Smartpointers +^^^^^^^^^^^^^^^^^^^^^^ +.. _class-bindings-smartpointers: + + If you think troublesome for managing lifetime, can use shared_ptr. + + .. code-block:: c++ + + kaguya::standard::shared_ptr mysptr = kaguya::standard::make_shared(); + state["a"] = mysptr; + state.dostring("print(a.y)"); + + .. note:: + + If :ref:`KAGUYA_USE_CPP11` is 0, + std::shared_ptr(and std::tr1::shared_ptr) is unrecognized, and vice versa. + see :doc:`/api_reference/standard` diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 58fb56d..85234f5 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -7,3 +7,4 @@ Getting Started requirements tutorial + class_bindings diff --git a/docs/getting_started/tutorial.rst b/docs/getting_started/tutorial.rst index 16bee00..e293aaf 100644 --- a/docs/getting_started/tutorial.rst +++ b/docs/getting_started/tutorial.rst @@ -10,7 +10,7 @@ Installation ---------------------------------- add "kaguya/include" directory to "header search path" of your project. -Or generate single header file and copy to your project. +Or generate single header file and add it to your project. .. code-block:: bash @@ -142,28 +142,28 @@ basic .. code-block:: c++ - int ret = state["math"]["abs"](-32);//call math.abs of Lua function + int ret = state["math"]["abs"](-32); assert(ret == 32); Specified result type .. code-block:: c++ - auto ret = state["math"]["abs"].call(-32);//call math.abs of Lua function + auto ret = state["math"]["abs"].call(-32); assert(ret == 32); Optional result value .. code-block:: c++ - kaguya::optional ret = state["math"]["abs"](-32);//call math.abs of Lua function + kaguya::optional ret = state["math"]["abs"](-32); assert(ret && *ret == 32); Multiple results .. code-block:: c++ - state("multresfun =function() return 1,2,4 end");//registering multiple results function + state("multresfun =function() return 1,2,4 end"); int a, b, c; kaguya::tie(a, b, c) = state["multresfun"](); std::cout << a << "," << b << "," << c << std::endl;//1,2,4 diff --git a/include/kaguya/metatable.hpp b/include/kaguya/metatable.hpp index 6293abe..73b8a08 100644 --- a/include/kaguya/metatable.hpp +++ b/include/kaguya/metatable.hpp @@ -178,6 +178,8 @@ namespace kaguya } } + + /// class binding interface. template class UserdataMetatable { diff --git a/include/kaguya/state.hpp b/include/kaguya/state.hpp index ea0d303..ece8bc7 100644 --- a/include/kaguya/state.hpp +++ b/include/kaguya/state.hpp @@ -74,7 +74,7 @@ namespace kaguya } }; - ///@ lua_State wrap class + /// lua_State wrap class class State { standard::shared_ptr allocator_holder_;