1 files changed, 124 insertions, 0 deletions
diff --git a/libs/python/pyste/doc/wrappers.html b/libs/python/pyste/doc/wrappers.html
new file mode 100644
index 000000000..534ae5529
--- /dev/null
+++ b/libs/python/pyste/doc/wrappers.html
@@ -0,0 +1,124 @@
+<html>
+<head>
+<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
+<title>Wrappers</title>
+<link rel="stylesheet" href="theme/style.css" type="text/css">
+<link rel="prev" href="templates.html">
+<link rel="next" href="exporting_an_entire_header.html">
+</head>
+<body>
+<table width="100%" height="48" border="0" cellspacing="2">
+  <tr>
+    <td><img src="../../../../boost.png">
+    </td>
+    <td width="85%">
+      <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Wrappers</b></font>
+    </td>
+  </tr>
+</table>
+<br>
+<table border="0">
+  <tr>
+    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
+    <td width="30"><a href="templates.html"><img src="theme/l_arr.gif" border="0"></a></td>
+    <td width="20"><a href="exporting_an_entire_header.html"><img src="theme/r_arr.gif" border="0"></a></td>
+   </tr>
+</table>
+<p>
+Suppose you have this function:</p>
+<code><pre>
+    <span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&gt; </span><span class=identifier>names</span><span class=special>();
+</span></pre></code>
+<p>
+But you don't want to <a href="../../doc/v2/faq.html#question2">
+to export std::vector&lt;std::string&gt;</a>, 
+you want this function to return a python list of strings. <a href="../../index.html">
+Boost.Python</a> has
+excellent support for things like that:</p>
+<code><pre>
+    <span class=identifier>list </span><span class=identifier>names_wrapper</span><span class=special>()
+    {
+        </span><span class=identifier>list </span><span class=identifier>result</span><span class=special>;
+        // </span><span class=identifier>call </span><span class=identifier>original </span><span class=identifier>function
+        </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt; </span><span class=identifier>v </span><span class=special>= </span><span class=identifier>names</span><span class=special>();
+        // </span><span class=identifier>put </span><span class=identifier>all </span><span class=identifier>the </span><span class=identifier>strings </span><span class=identifier>inside </span><span class=identifier>the </span><span class=identifier>python </span><span class=identifier>list
+        </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt;::</span><span class=identifier>iterator </span><span class=identifier>it</span><span class=special>;
+        </span><span class=keyword>for </span><span class=special>(</span><span class=identifier>it </span><span class=special>= </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(); </span><span class=identifier>it </span><span class=special>!= </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>end</span><span class=special>(); ++</span><span class=identifier>it</span><span class=special>){
+            </span><span class=identifier>result</span><span class=special>.</span><span class=identifier>append</span><span class=special>(*</span><span class=identifier>it</span><span class=special>);    
+        }
+        </span><span class=keyword>return </span><span class=identifier>result</span><span class=special>;
+    }
+    
+    </span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>test</span><span class=special>)
+    {
+        </span><span class=identifier>def</span><span class=special>(</span><span class=string>&quot;names&quot;</span><span class=special>, &amp;</span><span class=identifier>names_wrapper</span><span class=special>);
+    }
+</span></pre></code>
+<p>
+Nice heh? Pyste supports this mechanism too. You declare the <tt>names_wrapper</tt>
+function in a header named &quot;<tt>test_wrappers.h</tt>&quot; and in the interface file:</p>
+<code><pre>
+    <span class=identifier>Include</span><span class=special>(</span><span class=string>&quot;test_wrappers.h&quot;</span><span class=special>)
+    </span><span class=identifier>names </span><span class=special>= </span><span class=identifier>Function</span><span class=special>(</span><span class=string>&quot;names&quot;</span><span class=special>, </span><span class=string>&quot;test.h&quot;</span><span class=special>)
+    </span><span class=identifier>set_wrapper</span><span class=special>(</span><span class=identifier>names</span><span class=special>, </span><span class=string>&quot;names_wrapper&quot;</span><span class=special>)
+</span></pre></code>
+<p>
+You can optionally declare the function in the interface file itself:</p>
+<code><pre>
+    <span class=identifier>names_wrapper </span><span class=special>= </span><span class=identifier>Wrapper</span><span class=special>(</span><span class=string>&quot;names_wrapper&quot;</span><span class=special>,
+    </span><span class=string>&quot;&quot;</span><span class=string>&quot;
+    list names_wrapper()
+    {
+        // code to call name() and convert the vector to a list...
+    }
+    &quot;</span><span class=string>&quot;&quot;</span><span class=special>)
+    </span><span class=identifier>names </span><span class=special>= </span><span class=identifier>Function</span><span class=special>(</span><span class=string>&quot;names&quot;</span><span class=special>, </span><span class=string>&quot;test.h&quot;</span><span class=special>)
+    </span><span class=identifier>set_wrapper</span><span class=special>(</span><span class=identifier>names</span><span class=special>, </span><span class=identifier>names_wrapper</span><span class=special>)
+</span></pre></code>
+<p>
+The same mechanism can be used with member functions too. Just remember that
+the first parameter of wrappers for member functions is a pointer to the
+class, as in:</p>
+<code><pre>
+    <span class=keyword>struct </span><span class=identifier>C
+    </span><span class=special>{
+        </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&gt; </span><span class=identifier>names</span><span class=special>();
+    }
+
+    </span><span class=identifier>list </span><span class=identifier>names_wrapper</span><span class=special>(</span><span class=identifier>C</span><span class=special>* </span><span class=identifier>c</span><span class=special>)
+    {
+        // </span><span class=identifier>same </span><span class=identifier>as </span><span class=identifier>before</span><span class=special>, </span><span class=identifier>calling </span><span class=identifier>c</span><span class=special>-&gt;</span><span class=identifier>names</span><span class=special>() </span><span class=keyword>and </span><span class=identifier>converting </span><span class=identifier>result </span><span class=identifier>to </span><span class=identifier>a </span><span class=identifier>list 
+    </span><span class=special>}
+</span></pre></code>
+<p>
+And then in the interface file:</p>
+<code><pre>
+    <span class=identifier>C </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=string>&quot;C&quot;</span><span class=special>, </span><span class=string>&quot;test.h&quot;</span><span class=special>)
+    </span><span class=identifier>set_wrapper</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=identifier>names</span><span class=special>, </span><span class=string>&quot;names_wrapper&quot;</span><span class=special>)
+</span></pre></code>
+<table width="80%" border="0" align="center">
+  <tr>
+    <td class="note_box">
+
+<img src="theme/note.gif"></img>Even though <a href="../../index.html">
+Boost.Python</a> accepts either a pointer or a
+reference to the class in wrappers for member functions as the first parameter,
+Pyste expects them to be a <b>pointer</b>. Doing otherwise will prevent your
+code to compile when you set a wrapper for a virtual member function.
+    </td>
+  </tr>
+</table>
+<table border="0">
+  <tr>
+    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
+    <td width="30"><a href="templates.html"><img src="theme/l_arr.gif" border="0"></a></td>
+    <td width="20"><a href="exporting_an_entire_header.html"><img src="theme/r_arr.gif" border="0"></a></td>
+   </tr>
+</table>
+<br>
+<hr size="1"><p class="copyright">Copyright &copy; 2003 Bruno da Silva de Oliveira<br>Copyright &copy; 2002-2003 Joel de Guzman<br><br>
+<font size="2">Distributed under
+  the Boost Software License, Version 1.0. (See accompanying file
+  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) </font> </p>
+</body>
+</html>