|
From: Arvid N. <ar...@us...> - 2005-10-24 22:25:03
|
Update of /cvsroot/luabind/luabind/luabind/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1243/doc Modified Files: Tag: beta7-devel2 docs.html docs.rst Log Message: updated the documentation and added another test for the new property code Index: docs.html =================================================================== RCS file: /cvsroot/luabind/luabind/luabind/doc/docs.html,v retrieving revision 1.52.2.7 retrieving revision 1.52.2.8 diff -u -d -r1.52.2.7 -r1.52.2.8 --- docs.html 3 Aug 2005 14:41:14 -0000 1.52.2.7 +++ docs.html 24 Oct 2005 22:24:54 -0000 1.52.2.8 @@ -7,7 +7,7 @@ <title>luabind</title> <meta name="author" content="Daniel Wallin, Arvid Norberg" /> <meta name="copyright" content="Copyright Daniel Wallin, Arvid Norberg 2003." /> -<meta name="date" content="2005-07-29" /> +<meta name="date" content="2005-10-22" /> <link rel="stylesheet" href="style.css" type="text/css" /> </head> <body> @@ -22,9 +22,9 @@ <tr><th class="docinfo-name">Copyright:</th> <td>Copyright Daniel Wallin, Arvid Norberg 2003.</td></tr> <tr><th class="docinfo-name">Date:</th> -<td>2005-07-29</td></tr> +<td>2005-10-22</td></tr> <tr><th class="docinfo-name">Revision:</th> -<td>1.25.2.7</td></tr> +<td>1.25.2.9</td></tr> <tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><p class="first">Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation @@ -75,44 +75,45 @@ <li><a class="reference" href="#nested-scopes-and-static-functions" id="id60" name="id60">8.4 Nested scopes and static functions</a></li> <li><a class="reference" href="#derived-classes" id="id61" name="id61">8.5 Derived classes</a></li> <li><a class="reference" href="#smart-pointers" id="id62" name="id62">8.6 Smart pointers</a></li> +<li><a class="reference" href="#splitting-class-registrations" id="id63" name="id63">8.7 Splitting class registrations</a></li> </ul> </li> -<li><a class="reference" href="#object" id="id63" name="id63">9 Object</a><ul class="auto-toc"> -<li><a class="reference" href="#iterators" id="id64" name="id64">9.1 Iterators</a></li> -<li><a class="reference" href="#related-functions" id="id65" name="id65">9.2 Related functions</a></li> +<li><a class="reference" href="#object" id="id64" name="id64">9 Object</a><ul class="auto-toc"> +<li><a class="reference" href="#iterators" id="id65" name="id65">9.1 Iterators</a></li> +<li><a class="reference" href="#related-functions" id="id66" name="id66">9.2 Related functions</a></li> </ul> </li> -<li><a class="reference" href="#defining-classes-in-lua" id="id66" name="id66">10 Defining classes in Lua</a><ul class="auto-toc"> -<li><a class="reference" href="#deriving-in-lua" id="id67" name="id67">10.1 Deriving in lua</a></li> -<li><a class="reference" href="#overloading-operators" id="id68" name="id68">10.2 Overloading operators</a></li> -<li><a class="reference" href="#finalizers" id="id69" name="id69">10.3 Finalizers</a></li> -<li><a class="reference" href="#slicing" id="id70" name="id70">10.4 Slicing</a></li> +<li><a class="reference" href="#defining-classes-in-lua" id="id67" name="id67">10 Defining classes in Lua</a><ul class="auto-toc"> +<li><a class="reference" href="#deriving-in-lua" id="id68" name="id68">10.1 Deriving in lua</a></li> +<li><a class="reference" href="#overloading-operators" id="id69" name="id69">10.2 Overloading operators</a></li> +<li><a class="reference" href="#finalizers" id="id70" name="id70">10.3 Finalizers</a></li> +<li><a class="reference" href="#slicing" id="id71" name="id71">10.4 Slicing</a></li> </ul> </li> -<li><a class="reference" href="#exceptions" id="id71" name="id71">11 Exceptions</a></li> -<li><a class="reference" href="#policies" id="id72" name="id72">12 Policies</a><ul class="auto-toc"> -<li><a class="reference" href="#adopt" id="id73" name="id73">12.1 adopt</a></li> -<li><a class="reference" href="#dependency" id="id74" name="id74">12.2 dependency</a></li> -<li><a class="reference" href="#out-value" id="id75" name="id75">12.3 out_value</a></li> -<li><a class="reference" href="#pure-out-value" id="id76" name="id76">12.4 pure_out_value</a></li> -<li><a class="reference" href="#return-reference-to" id="id77" name="id77">12.5 return_reference_to</a></li> -<li><a class="reference" href="#copy" id="id78" name="id78">12.6 copy</a></li> -<li><a class="reference" href="#discard-result" id="id79" name="id79">12.7 discard_result</a></li> -<li><a class="reference" href="#return-stl-iterator" id="id80" name="id80">12.8 return_stl_iterator</a></li> -<li><a class="reference" href="#raw" id="id81" name="id81">12.9 raw</a></li> -<li><a class="reference" href="#yield" id="id82" name="id82">12.10 yield</a></li> +<li><a class="reference" href="#exceptions" id="id72" name="id72">11 Exceptions</a></li> +<li><a class="reference" href="#policies" id="id73" name="id73">12 Policies</a><ul class="auto-toc"> +<li><a class="reference" href="#adopt" id="id74" name="id74">12.1 adopt</a></li> +<li><a class="reference" href="#dependency" id="id75" name="id75">12.2 dependency</a></li> +<li><a class="reference" href="#out-value" id="id76" name="id76">12.3 out_value</a></li> +<li><a class="reference" href="#pure-out-value" id="id77" name="id77">12.4 pure_out_value</a></li> +<li><a class="reference" href="#return-reference-to" id="id78" name="id78">12.5 return_reference_to</a></li> +<li><a class="reference" href="#copy" id="id79" name="id79">12.6 copy</a></li> +<li><a class="reference" href="#discard-result" id="id80" name="id80">12.7 discard_result</a></li> +<li><a class="reference" href="#return-stl-iterator" id="id81" name="id81">12.8 return_stl_iterator</a></li> +<li><a class="reference" href="#raw" id="id82" name="id82">12.9 raw</a></li> +<li><a class="reference" href="#yield" id="id83" name="id83">12.10 yield</a></li> </ul> </li> -<li><a class="reference" href="#splitting-up-the-registration" id="id83" name="id83">13 Splitting up the registration</a></li> -<li><a class="reference" href="#configuration" id="id84" name="id84">14 Configuration</a><ul class="auto-toc"> -<li><a class="reference" href="#build-options" id="id85" name="id85">14.1 Build options</a></li> +<li><a class="reference" href="#splitting-up-the-registration" id="id84" name="id84">13 Splitting up the registration</a></li> +<li><a class="reference" href="#configuration" id="id85" name="id85">14 Configuration</a><ul class="auto-toc"> +<li><a class="reference" href="#build-options" id="id86" name="id86">14.1 Build options</a></li> </ul> </li> -<li><a class="reference" href="#implementation-notes" id="id86" name="id86">15 Implementation notes</a></li> -<li><a class="reference" href="#error-messages" id="id87" name="id87">16 Error messages</a></li> -<li><a class="reference" href="#faq" id="id88" name="id88">17 FAQ</a></li> -<li><a class="reference" href="#known-issues" id="id89" name="id89">18 Known issues</a></li> -<li><a class="reference" href="#acknowledgments" id="id90" name="id90">19 Acknowledgments</a></li> +<li><a class="reference" href="#implementation-notes" id="id87" name="id87">15 Implementation notes</a></li> +<li><a class="reference" href="#error-messages" id="id88" name="id88">16 Error messages</a></li> +<li><a class="reference" href="#faq" id="id89" name="id89">17 FAQ</a></li> +<li><a class="reference" href="#known-issues" id="id90" name="id90">18 Known issues</a></li> +<li><a class="reference" href="#acknowledgments" id="id91" name="id91">19 Acknowledgments</a></li> </ul> </div> <div class="section" id="introduction"> @@ -591,9 +592,24 @@ module(L) [ class_<A>("A") - .def_readonly("a", &A::a) + .def_readonly("a", &A::a) ]; </pre> +<p>When binding members that are a non-primitive type, the auto generated getter +function will return a reference to it. This is to allow chained .-operators. +For example, when having a struct containing another struct. Like this:</p> +<pre class="literal-block"> +struct A { int m; }; +struct B { A a; }; +</pre> +<p>When binding <tt class="docutils literal"><span class="pre">B</span></tt> to lua, the following expression code should work:</p> +<pre class="literal-block"> +b = B() +b.a.m = 1 +assert(b.a.m == 1) +</pre> +<p>This requires the first lookup (on <tt class="docutils literal"><span class="pre">a</span></tt>) to return a reference to <tt class="docutils literal"><span class="pre">A</span></tt>, and +not a copy.</p> <p>You can also register getter and setter functions and make them look as if they were a public data member. Consider the following class:</p> <pre class="literal-block"> @@ -647,6 +663,7 @@ </div> <div class="section" id="operators"> <h2><a name="operators">8.3 Operators</a></h2> +<p>To bind operators you have to include <tt class="docutils literal"><span class="pre"><luabind/operator.hpp></span></tt>.</p> <p>The mechanism for registering operators on your class is pretty simple. You use a global name <tt class="docutils literal"><span class="pre">luabind::self</span></tt> to refer to the class itself and then you just write the operator expression inside the <tt class="docutils literal"><span class="pre">def()</span></tt> call. This class:</p> @@ -666,7 +683,7 @@ </pre> <p>This will work regardless if your plus operator is defined inside your class or as a free function.</p> -<p>If you operator is const (or, when defined as a free function, takes a const +<p>If your operator is const (or, when defined as a free function, takes a const reference to the class itself) you have to use <tt class="docutils literal"><span class="pre">const_self</span></tt> instead of <tt class="docutils literal"><span class="pre">self</span></tt>. Like this:</p> <pre class="literal-block"> @@ -678,11 +695,15 @@ </pre> <p>The operators supported are those available in Lua:</p> <pre class="literal-block"> -+ - * / == != < <= > >= ++ - * / == < <= </pre> <p>This means, no in-place operators. The equality operator (<tt class="docutils literal"><span class="pre">==</span></tt>) has a little hitch; it will not be called if the references are equal. This means that the <tt class="docutils literal"><span class="pre">==</span></tt> operator has to do pretty much what's it's expected to do.</p> +<p>Lua does not support operators such as <tt class="docutils literal"><span class="pre">!=</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt> or <tt class="docutils literal"><span class="pre">>=</span></tt>. That's why you +can only register the operators listed above. When you invoke one of the +mentioned operators, lua will define it in terms of one of the avaliable +operators.</p> <p>In the above example the other operand type is instantiated by writing <tt class="docutils literal"><span class="pre">int()</span></tt>. If the operand type is a complex type that cannot easily be instantiated you can wrap the type in a class called <tt class="docutils literal"><span class="pre">other<></span></tt>. For example:</p> @@ -702,7 +723,7 @@ .def(self + <strong>other<std::string>()</strong>) ]; </pre> -<p>To register an application operator:</p> +<p>To register an application (function call-) operator:</p> <pre class="literal-block"> module(L) [ @@ -800,7 +821,7 @@ namespace luabind { template<class T> - T* get_pointer(boost::shared_ptr<T> const& p) + T* get_pointer(boost::shared_ptr<T>& p) { return p.get(); } @@ -927,13 +948,44 @@ <p>Internally, luabind will do the necessary conversions on the raw pointers, which are first extracted from the holder type.</p> </div> +<div class="section" id="splitting-class-registrations"> +<h2><a name="splitting-class-registrations">8.7 Splitting class registrations</a></h2> +<p>In some situations it may be desirable to split a registration of a class +across different compilation units. Partly to save rebuild time when changing +in one part of the binding, and in some cases compiler limits may force you +to split it. To do this is very simple. Consider the following sample code:</p> +<pre class="literal-block"> +void register_part1(class_<X>& x) +{ + x.def(/*...*/); +} + +void register_part2(class_<X>& x) +{ + x.def(/*...*/); +} + +void register_(lua_State* L) +{ + class_<X> x("x"); + + register_part1(x); + register_part2(x); + + module(L) [ x ]; +} +</pre> +<p>Here, the class <tt class="docutils literal"><span class="pre">X</span></tt> is registered in two steps. The two functions +<tt class="docutils literal"><span class="pre">register_part1</span></tt> and <tt class="docutils literal"><span class="pre">register_part2</span></tt> may be put in separate compilation +units.</p> +</div> </div> <div class="section" id="object"> <h1><a name="object">9 Object</a></h1> <p>Since functions have to be able to take Lua values (of variable type) we need a wrapper around them. This wrapper is called <tt class="docutils literal"><span class="pre">luabind::object</span></tt>. If the function you register takes an object, it will match any Lua value. To use it, -you need to include <tt class="docutils literal"><span class="pre">luabind/object.hpp</span></tt>.</p> +you need to include <tt class="docutils literal"><span class="pre"><luabind/object.hpp></span></tt>.</p> <div class="topic"> <p class="topic-title first">Synopsis</p> <pre class="literal-block"> @@ -960,9 +1012,6 @@ object& operator=(T const&); object& operator=(object const&); - <strong>COMPARISONS ARE NOT IMPLEMENTED YET</strong> - template<class T> - bool operator==(T const&) const; bool operator==(object const&) const; bool operator<(object const&) const; bool operator<=(object const&) const; @@ -970,6 +1019,9 @@ bool operator>=(object const&) const; bool operator!=(object const&) const; + template <class T> + <em>implementation-defined</em> operator[](T const& key) const + void swap(object&); <em>implementation-defined</em> operator()(); @@ -1061,7 +1113,7 @@ release its Lua object in its destructor.</p> <p>Here's an example of how a function can use a table:</p> <pre class="literal-block"> -void my_function(const object& table) +void my_function(object const& table) { if (table.type() == LUA_TTABLE) { @@ -1569,16 +1621,16 @@ <div class="contents topic" id="policies-currently-implemented"> <p class="topic-title first"><a name="policies-currently-implemented">Policies currently implemented</a></p> <ul class="auto-toc simple"> -<li><a class="reference" href="#adopt" id="id91" name="id91">12.1 adopt</a></li> -<li><a class="reference" href="#dependency" id="id92" name="id92">12.2 dependency</a></li> -<li><a class="reference" href="#out-value" id="id93" name="id93">12.3 out_value</a></li> -<li><a class="reference" href="#pure-out-value" id="id94" name="id94">12.4 pure_out_value</a></li> -<li><a class="reference" href="#return-reference-to" id="id95" name="id95">12.5 return_reference_to</a></li> -<li><a class="reference" href="#copy" id="id96" name="id96">12.6 copy</a></li> -<li><a class="reference" href="#discard-result" id="id97" name="id97">12.7 discard_result</a></li> -<li><a class="reference" href="#return-stl-iterator" id="id98" name="id98">12.8 return_stl_iterator</a></li> -<li><a class="reference" href="#raw" id="id99" name="id99">12.9 raw</a></li> -<li><a class="reference" href="#yield" id="id100" name="id100">12.10 yield</a></li> +<li><a class="reference" href="#adopt" id="id92" name="id92">12.1 adopt</a></li> +<li><a class="reference" href="#dependency" id="id93" name="id93">12.2 dependency</a></li> +<li><a class="reference" href="#out-value" id="id94" name="id94">12.3 out_value</a></li> +<li><a class="reference" href="#pure-out-value" id="id95" name="id95">12.4 pure_out_value</a></li> +<li><a class="reference" href="#return-reference-to" id="id96" name="id96">12.5 return_reference_to</a></li> +<li><a class="reference" href="#copy" id="id97" name="id97">12.6 copy</a></li> +<li><a class="reference" href="#discard-result" id="id98" name="id98">12.7 discard_result</a></li> +<li><a class="reference" href="#return-stl-iterator" id="id99" name="id99">12.8 return_stl_iterator</a></li> +<li><a class="reference" href="#raw" id="id100" name="id100">12.9 raw</a></li> +<li><a class="reference" href="#yield" id="id101" name="id101">12.10 yield</a></li> </ul> </div> <div class="section" id="adopt"> Index: docs.rst =================================================================== RCS file: /cvsroot/luabind/luabind/luabind/doc/docs.rst,v retrieving revision 1.25.2.9 retrieving revision 1.25.2.10 diff -u -d -r1.25.2.9 -r1.25.2.10 --- docs.rst 22 Oct 2005 10:42:33 -0000 1.25.2.9 +++ docs.rst 24 Oct 2005 22:24:54 -0000 1.25.2.10 @@ -569,9 +569,25 @@ module(L) [ class_<A>("A") - .def_readonly("a", &A::a) + .def_readonly("a", &A::a) ]; +When binding members that are a non-primitive type, the auto generated getter +function will return a reference to it. This is to allow chained .-operators. +For example, when having a struct containing another struct. Like this:: + + struct A { int m; }; + struct B { A a; }; + +When binding ``B`` to lua, the following expression code should work:: + + b = B() + b.a.m = 1 + assert(b.a.m == 1) + +This requires the first lookup (on ``a``) to return a reference to ``A``, and +not a copy. + You can also register getter and setter functions and make them look as if they were a public data member. Consider the following class:: @@ -630,6 +646,8 @@ Operators --------- +To bind operators you have to include ``<luabind/operator.hpp>``. + The mechanism for registering operators on your class is pretty simple. You use a global name ``luabind::self`` to refer to the class itself and then you just write the operator expression inside the ``def()`` call. This class:: @@ -652,7 +670,7 @@ This will work regardless if your plus operator is defined inside your class or as a free function. -If you operator is const (or, when defined as a free function, takes a const +If your operator is const (or, when defined as a free function, takes a const reference to the class itself) you have to use ``const_self`` instead of ``self``. Like this: @@ -668,12 +686,17 @@ .. parsed-literal:: - + - \* / == != < <= > >= + + - \* / == < <= This means, no in-place operators. The equality operator (``==``) has a little hitch; it will not be called if the references are equal. This means that the ``==`` operator has to do pretty much what's it's expected to do. +Lua does not support operators such as ``!=``, ``>`` or ``>=``. That's why you +can only register the operators listed above. When you invoke one of the +mentioned operators, lua will define it in terms of one of the avaliable +operators. + In the above example the other operand type is instantiated by writing ``int()``. If the operand type is a complex type that cannot easily be instantiated you can wrap the type in a class called ``other<>``. For example: @@ -698,7 +721,7 @@ .def(self + **other<std::string>()**) ]; -To register an application operator: +To register an application (function call-) operator: .. parsed-literal:: @@ -897,13 +920,46 @@ are first extracted from the holder type. +Splitting class registrations +----------------------------- + +In some situations it may be desirable to split a registration of a class +across different compilation units. Partly to save rebuild time when changing +in one part of the binding, and in some cases compiler limits may force you +to split it. To do this is very simple. Consider the following sample code:: + + void register_part1(class_<X>& x) + { + x.def(/*...*/); + } + + void register_part2(class_<X>& x) + { + x.def(/*...*/); + } + + void register_(lua_State* L) + { + class_<X> x("x"); + + register_part1(x); + register_part2(x); + + module(L) [ x ]; + } + +Here, the class ``X`` is registered in two steps. The two functions +``register_part1`` and ``register_part2`` may be put in separate compilation +units. + + Object ====== Since functions have to be able to take Lua values (of variable type) we need a wrapper around them. This wrapper is called ``luabind::object``. If the function you register takes an object, it will match any Lua value. To use it, -you need to include ``luabind/object.hpp``. +you need to include ``<luabind/object.hpp>``. .. topic:: Synopsis @@ -932,9 +988,6 @@ object& operator=(T const&); object& operator=(object const&); - **COMPARISONS ARE NOT IMPLEMENTED YET** - template<class T> - bool operator==(T const&) const; bool operator==(object const&) const; bool operator<(object const&) const; bool operator<=(object const&) const; @@ -942,6 +995,9 @@ bool operator>=(object const&) const; bool operator!=(object const&) const; + template <class T> + *implementation-defined* operator[](T const& key) const + void swap(object&); *implementation-defined* operator()(); @@ -1040,7 +1096,7 @@ Here's an example of how a function can use a table:: - void my_function(const object& table) + void my_function(object const& table) { if (table.type() == LUA_TTABLE) { |
