diff options
Diffstat (limited to 'libs/python/pyste/doc')
27 files changed, 1989 insertions, 0 deletions
diff --git a/libs/python/pyste/doc/adding_new_methods.html b/libs/python/pyste/doc/adding_new_methods.html new file mode 100644 index 000000000..afa772bcc --- /dev/null +++ b/libs/python/pyste/doc/adding_new_methods.html @@ -0,0 +1,79 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Adding New Methods</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="global_variables.html"> +<link rel="next" href="inserting_code.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>Adding New Methods</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="global_variables.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="inserting_code.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +Suppose that you want to add a function to a class, turning it into a member +function:</p> +<code><pre> + <span class=keyword>struct </span><span class=identifier>World + </span><span class=special>{ + </span><span class=keyword>void </span><span class=identifier>set</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>) { </span><span class=keyword>this</span><span class=special>-></span><span class=identifier>msg </span><span class=special>= </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>; + }; + + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>greet</span><span class=special>(</span><span class=identifier>World</span><span class=special>& </span><span class=identifier>w</span><span class=special>) + { + </span><span class=keyword>return </span><span class=identifier>w</span><span class=special>.</span><span class=identifier>msg</span><span class=special>; + } +</span></pre></code> +<p> +Here, we want to make <tt>greet</tt> work as a member function of the class <tt>World</tt>. We do +that using the <tt>add_method</tt> construct:</p> +<code><pre> + <span class=identifier>W </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=string>"World"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>add_method</span><span class=special>(</span><span class=identifier>W</span><span class=special>, </span><span class=string>"greet"</span><span class=special>) +</span></pre></code> +<p> +Notice also that then you can rename it, set its policy, just like a regular +member function:</p> +<code><pre> + <span class=identifier>rename</span><span class=special>(</span><span class=identifier>W</span><span class=special>.</span><span class=identifier>greet</span><span class=special>, </span><span class=literal>'Greet'</span><span class=special>) +</span></pre></code> +<p> +Now from Python:</p> +<code><pre> + <span class=special>>>> </span><span class=identifier>import </span><span class=identifier>hello + </span><span class=special>>>> </span><span class=identifier>w </span><span class=special>= </span><span class=identifier>hello</span><span class=special>.</span><span class=identifier>World</span><span class=special>() + >>> </span><span class=identifier>w</span><span class=special>.</span><span class=identifier>set</span><span class=special>(</span><span class=literal>'Ni'</span><span class=special>) + >>> </span><span class=identifier>w</span><span class=special>.</span><span class=identifier>greet</span><span class=special>() + </span><span class=literal>'Ni' + </span><span class=special>>>> </span><span class=identifier>print </span><span class=literal>'Oh no! The knights who say Ni!' + </span><span class=identifier>Oh </span><span class=identifier>no</span><span class=special>! </span><span class=identifier>The </span><span class=identifier>knights </span><span class=identifier>who </span><span class=identifier>say </span><span class=identifier>Ni</span><span class=special>! +</span></pre></code> +<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="global_variables.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="inserting_code.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/exporting_an_entire_header.html b/libs/python/pyste/doc/exporting_an_entire_header.html new file mode 100644 index 000000000..db25325ca --- /dev/null +++ b/libs/python/pyste/doc/exporting_an_entire_header.html @@ -0,0 +1,85 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Exporting An Entire Header</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="wrappers.html"> +<link rel="next" href="smart_pointers.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>Exporting An Entire Header</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="wrappers.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="smart_pointers.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +Pyste also supports a mechanism to export all declarations found in a header +file. Suppose again our file, <tt>hello.h</tt>:</p> +<code><pre> + <span class=keyword>struct </span><span class=identifier>World + </span><span class=special>{ + </span><span class=identifier>World</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>): </span><span class=identifier>msg</span><span class=special>(</span><span class=identifier>msg</span><span class=special>) {} + </span><span class=keyword>void </span><span class=identifier>set</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>) { </span><span class=keyword>this</span><span class=special>-></span><span class=identifier>msg </span><span class=special>= </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>greet</span><span class=special>() { </span><span class=keyword>return </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>; + }; + + </span><span class=keyword>enum </span><span class=identifier>choice </span><span class=special>{ </span><span class=identifier>red</span><span class=special>, </span><span class=identifier>blue </span><span class=special>}; + + </span><span class=keyword>void </span><span class=identifier>show</span><span class=special>(</span><span class=identifier>choice </span><span class=identifier>c</span><span class=special>) { </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>cout </span><span class=special><< </span><span class=string>"value: " </span><span class=special><< (</span><span class=keyword>int</span><span class=special>)</span><span class=identifier>c </span><span class=special><< </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>endl</span><span class=special>; } +</span></pre></code> +<p> +You can just use the <tt>AllFromHeader</tt> construct:</p> +<code><pre> + <span class=identifier>hello </span><span class=special>= </span><span class=identifier>AllFromHeader</span><span class=special>(</span><span class=string>"hello.h"</span><span class=special>) +</span></pre></code> +<p> +this will export all the declarations found in <tt>hello.h</tt>, which is equivalent +to write:</p> +<code><pre> + <span class=identifier>Class</span><span class=special>(</span><span class=string>"World"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>Enum</span><span class=special>(</span><span class=string>"choice"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>Function</span><span class=special>(</span><span class=string>"show"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) +</span></pre></code> +<p> +Note that you can still use the functions <tt>rename</tt>, <tt>set_policy</tt>, <tt>exclude</tt>, etc. Just access +the members of the header object like this:</p> +<code><pre> + <span class=identifier>rename</span><span class=special>(</span><span class=identifier>hello</span><span class=special>.</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>greet</span><span class=special>, </span><span class=string>"Greet"</span><span class=special>) + </span><span class=identifier>exclude</span><span class=special>(</span><span class=identifier>hello</span><span class=special>.</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>set</span><span class=special>, </span><span class=string>"Set"</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> <b>AllFromHeader is broken</b> in some cases. Until it is fixed, +use at you own risk. + </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="wrappers.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="smart_pointers.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/global_variables.html b/libs/python/pyste/doc/global_variables.html new file mode 100644 index 000000000..0efd2950b --- /dev/null +++ b/libs/python/pyste/doc/global_variables.html @@ -0,0 +1,49 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Global Variables</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="smart_pointers.html"> +<link rel="next" href="adding_new_methods.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>Global Variables</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="smart_pointers.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="adding_new_methods.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +To export global variables, use the <tt>Var</tt> construct:</p> +<code><pre> + <span class=identifier>Var</span><span class=special>(</span><span class=string>"myglobal"</span><span class=special>, </span><span class=string>"foo.h"</span><span class=special>) +</span></pre></code> +<p> +Beware of non-const global variables: changes in Python won't reflect in C++! +If you really must change them in Python, you will have to write some accessor +functions, and export those.</p> +<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="smart_pointers.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="adding_new_methods.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/inserting_code.html b/libs/python/pyste/doc/inserting_code.html new file mode 100644 index 000000000..97eb70f38 --- /dev/null +++ b/libs/python/pyste/doc/inserting_code.html @@ -0,0 +1,72 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Inserting Code</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="adding_new_methods.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>Inserting Code</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="adding_new_methods.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td> + </tr> +</table> +<p> +You can insert arbitrary code in the generated cpps, just use the functions +<tt>declaration_code</tt> and <tt>module_code</tt>. This will insert the given string in the +respective sections. Example:</p> +<code><pre> + ##<span class=identifier>file </span><span class=identifier>A</span><span class=special>.</span><span class=identifier>pyste + </span><span class=identifier>Class</span><span class=special>(</span><span class=string>"A"</span><span class=special>, </span><span class=string>"A.h"</span><span class=special>) + </span><span class=identifier>declaration_code</span><span class=special>(</span><span class=string>"/* declaration_code() comes here */\n"</span><span class=special>) + </span><span class=identifier>module_code</span><span class=special>(</span><span class=string>"/* module_code() comes here */\n"</span><span class=special>) +</span></pre></code> +<p> +Will generate:</p> +<code><pre> + <span class=comment>// Includes ==================================================================== + </span><span class=preprocessor>#include </span><span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>python</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>> + + // </span><span class=identifier>Using </span><span class=special>======================================================================= + </span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>python</span><span class=special>; + + // </span><span class=identifier>Declarations </span><span class=special>================================================================ + + /* </span><span class=identifier>declaration_code</span><span class=special>() </span><span class=identifier>comes </span><span class=identifier>here </span><span class=special>*/ + + // </span><span class=identifier>Module </span><span class=special>====================================================================== + </span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>A</span><span class=special>) + { + </span><span class=identifier>class_</span><span class=special>< </span><span class=identifier>A </span><span class=special>>(</span><span class=string>"A"</span><span class=special>, </span><span class=identifier>init</span><span class=special>< >()) + .</span><span class=identifier>def</span><span class=special>(</span><span class=identifier>init</span><span class=special>< </span><span class=keyword>const </span><span class=identifier>A</span><span class=special>& >()) + ; + + /* </span><span class=identifier>module_code</span><span class=special>() </span><span class=identifier>comes </span><span class=identifier>here </span><span class=special>*/ + } +</span></pre></code> +<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="adding_new_methods.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/introduction.html b/libs/python/pyste/doc/introduction.html new file mode 100644 index 000000000..943884931 --- /dev/null +++ b/libs/python/pyste/doc/introduction.html @@ -0,0 +1,73 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Introduction</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="next" href="running_pyste.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>Introduction</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"><img src="theme/l_arr_disabled.gif" border="0"></td> + <td width="20"><a href="running_pyste.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<a name="what_is_pyste_"></a><h2>What is Pyste?</h2><p> +Pyste is a <a href="../../index.html"> +Boost.Python</a> code generator. The user specifies the classes and +functions to be exported using a simple <i>interface file</i>, which following the +<a href="../../index.html"> +Boost.Python</a>'s philosophy, is simple Python code. Pyste then uses <a href="http://www.gccxml.org"> +GCCXML</a> to +parse all the headers and extract the necessary information to automatically +generate C++ code.</p> +<a name="example"></a><h2>Example</h2><p> +Let's borrow the class <tt>World</tt> from the <a href="../../doc/tutorial/doc/html/python/exposing.html"> +tutorial</a>: </p> +<code><pre> + <span class=keyword>struct </span><span class=identifier>World + </span><span class=special>{ + </span><span class=keyword>void </span><span class=identifier>set</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>) { </span><span class=keyword>this</span><span class=special>-></span><span class=identifier>msg </span><span class=special>= </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>greet</span><span class=special>() { </span><span class=keyword>return </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>; + }; +</span></pre></code> +<p> +Here's the interface file for it, named <tt>world.pyste</tt>:</p> +<code><pre> + <span class=identifier>Class</span><span class=special>(</span><span class=string>"World"</span><span class=special>, </span><span class=string>"world.h"</span><span class=special>) +</span></pre></code> +<p> +and that's it!</p> +<p> +The next step is invoke Pyste in the command-line:</p> +<code><pre>python pyste.py --module=hello world.pyste</pre></code><p> +this will create a file "<tt>hello.cpp</tt>" in the directory where the command was +run. </p> +<p> +Pyste supports the following features:</p> +<ul><li>Functions</li><li>Classes</li><li>Class Templates</li><li>Virtual Methods</li><li>Overloading</li><li>Attributes </li><li>Enums (both "free" enums and class enums)</li><li>Nested Classes</li><li>Support for <tt>boost::shared_ptr</tt> and <tt>std::auto_ptr</tt></li><li>Global Variables</li></ul><table border="0"> + <tr> + <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> + <td width="30"><img src="theme/l_arr_disabled.gif" border="0"></td> + <td width="20"><a href="running_pyste.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/policies.html b/libs/python/pyste/doc/policies.html new file mode 100644 index 000000000..3628093bd --- /dev/null +++ b/libs/python/pyste/doc/policies.html @@ -0,0 +1,90 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Policies</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="renaming_and_excluding.html"> +<link rel="next" href="templates.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>Policies</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="renaming_and_excluding.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="templates.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +Even thought Pyste can identify various elements in the C++ code, like virtual +member functions, attributes, and so on, one thing that it can't do is to +guess the semantics of functions that return pointers or references. In this +case, the user must manually specify the policy. Policies are explained in the +<a href="../../doc/tutorial/doc/html/python/functions.html#python.call_policies"> +tutorial</a>.</p> +<p> +The policies in Pyste are named exactly as in <a href="../../index.html"> +Boost.Python</a>, only the syntax is +slightly different. For instance, this policy:</p> +<code><pre> + <span class=identifier>return_internal_reference</span><span class=special><</span><span class=number>1</span><span class=special>, </span><span class=identifier>with_custodian_and_ward</span><span class=special><</span><span class=number>1</span><span class=special>, </span><span class=number>2</span><span class=special>> >() +</span></pre></code> +<p> +becomes in Pyste: </p> +<code><pre> + <span class=identifier>return_internal_reference</span><span class=special>(</span><span class=number>1</span><span class=special>, </span><span class=identifier>with_custodian_and_ward</span><span class=special>(</span><span class=number>1</span><span class=special>, </span><span class=number>2</span><span class=special>)) +</span></pre></code> +<p> +The user can specify policies for functions and virtual member functions with +the <tt>set_policy</tt> function:</p> +<code><pre> + <span class=identifier>set_policy</span><span class=special>(</span><span class=identifier>f</span><span class=special>, </span><span class=identifier>return_internal_reference</span><span class=special>()) + </span><span class=identifier>set_policy</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=identifier>foo</span><span class=special>, </span><span class=identifier>return_value_policy</span><span class=special>(</span><span class=identifier>manage_new_object</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> <b>What if a function or member function needs a policy and +the user doesn't set one?</b><br><br> If a function needs a policy and one +was not set, Pyste will issue a error. The user should then go in the +interface file and set the policy for it, otherwise the generated cpp won't +compile. + </td> + </tr> +</table> +<table width="80%" border="0" align="center"> + <tr> + <td class="note_box"> + +<img src="theme/note.gif"></img> +Note that for functions that return <tt>const T&</tt>, the policy +<tt>return_value_policy<copy_const_reference>()</tt> wil be used by default, because +that's normally what you want. You can change it to something else if you need +to, though. + </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="renaming_and_excluding.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="templates.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/pyste.txt b/libs/python/pyste/doc/pyste.txt new file mode 100644 index 000000000..186a31cba --- /dev/null +++ b/libs/python/pyste/doc/pyste.txt @@ -0,0 +1,664 @@ +[doc Pyste Documentation] + +[/ Copyright 2003 Bruno da Silva de Oliveira and Joel de Guzman. +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) ] + +[def GCCXML [@http://www.gccxml.org GCCXML]] +[def Boost.Python [@../../index.html Boost.Python]] + +[page Introduction] + +[h2 What is Pyste?] + +Pyste is a Boost.Python code generator. The user specifies the classes and +functions to be exported using a simple ['interface file], which following the +Boost.Python's philosophy, is simple Python code. Pyste then uses GCCXML to +parse all the headers and extract the necessary information to automatically +generate C++ code. + +[h2 Example] + +Let's borrow the class [^World] from the [@../../doc/tutorial/doc/exposing_classes.html tutorial]: + + struct World + { + void set(std::string msg) { this->msg = msg; } + std::string greet() { return msg; } + std::string msg; + }; + +Here's the interface file for it, named [^world.pyste]: + + Class("World", "world.h") + +and that's it! + +The next step is invoke Pyste in the command-line: + +[pre python pyste.py --module=hello world.pyste] + +this will create a file "[^hello.cpp]" in the directory where the command was +run. + +Pyste supports the following features: + +* Functions +* Classes +* Class Templates +* Virtual Methods +* Overloading +* Attributes +* Enums (both "free" enums and class enums) +* Nested Classes +* Support for [^boost::shared_ptr] and [^std::auto_ptr] +* Global Variables + +[page Running Pyste] + +To run Pyste, you will need: + +* Python 2.2, available at [@http://www.python.org python's website]. +* The great [@http://effbot.org elementtree] library, from Fredrik Lundh. +* The excellent GCCXML, from Brad King. + +Installation for the tools is available in their respective webpages. + +[blurb +[$theme/note.gif] GCCXML must be accessible in the PATH environment variable, so +that Pyste can call it. How to do this varies from platform to platform. +] + +[h2 Ok, now what?] + +Well, now let's fire it up: + +[pre +''' +>python pyste.py + +Pyste version 0.9.26 + +Usage: + pyste [options] interface-files + +where options are: + --module=<name> The name of the module that will be generated; + defaults to the first interface filename, without + the extension. + -I <path> Add an include path + -D <symbol> Define symbol + --multiple Create various cpps, instead of only one + (useful during development) + --out=<name> Specify output filename (default: <module>.cpp) + in --multiple mode, this will be a directory + --no-using Do not declare "using namespace boost"; + use explicit declarations instead + --pyste-ns=<name> Set the namespace where new types will be declared; + default is the empty namespace + --debug Writes the xml for each file parsed in the current + directory + --cache-dir=<dir> Directory for cache files (speeds up future runs) + --only-create-cache Recreates all caches (doesn't generate code). + --generate-main Generates the _main.cpp file (in multiple mode) + --file-list A file with one pyste file per line. Use as a + substitute for passing the files in the command + line. + -h, --help Print this help and exit + -v, --version Print version information + +''' +] + +Options explained: + +The [^-I] and [^-D] are preprocessor flags, which are needed by GCCXML to parse +the header files correctly and by Pyste to find the header files declared in the +interface files. + +[^--out] names the output file (default: [^<module>.cpp]), or in multiple mode, +names a output directory for the files (default: [^<module>]). + +[^--no-using] tells Pyste to don't declare "[^using namespace boost;]" in the +generated cpp, using the namespace boost::python explicitly in all declarations. +Use only if you're having a name conflict in one of the files. + +Use [^--pyste-ns] to change the namespace where new types are declared (for +instance, the virtual wrappers). Use only if you are having any problems. By +default, Pyste uses the empty namespace. + +[^--debug] will write in the current directory a xml file as outputted by GCCXML +for each header parsed. Useful for bug reports. + +[^--file-list] names a file where each line points to a Pyste file. Use this instead +to pass the pyste files if you have a lot of them and your shell has some command line +size limit. + +The other options are explained below, in [@#multiple_mode [*Multiple Mode]] and +[@#cache [*Cache]]. + +[^-h, --help, -v, --version] are self-explaining, I believe. ;) + +So, the usage is simple enough: + +[pre >python pyste.py --module=mymodule file.pyste file2.pyste ...] + +will generate a file [^mymodule.cpp] in the same dir where the command was +executed. Now you can compile the file using the same instructions of the +[@../../doc/tutorial/doc/building_hello_world.html tutorial]. + +[h2 Wait... how do I set those I and D flags?] + +Don't worry: normally GCCXML is already configured correctly for your plataform, +so the search path to the standard libraries and the standard defines should +already be set. You only have to set the paths to other libraries that your code +needs, like Boost, for example. + +Plus, Pyste automatically uses the contents of the environment variable +[^INCLUDE] if it exists. Visual C++ users should run the [^Vcvars32.bat] file, +which for Visual C++ 6 is normally located at: + + C:\Program Files\Microsoft Visual Studio\VC98\bin\Vcvars32.bat + +with that, you should have little trouble setting up the flags. + +[blurb [$theme/note.gif][*A note about Psyco][br][br] +Although you don't have to install [@http://psyco.sourceforge.net/ Psyco] to +use Pyste, if you do, Pyste will make use of it to speed up the wrapper +generation. Speed ups of 30% can be achieved, so it's highly recommended. +] + + +[h2 Multiple Mode] + +The multiple mode is useful in large projects, where the presence of multiple +classes in a single file makes the compilation unpractical (excessive memory +usage, mostly). + +The solution is make Pyste generate multiple files, more specifically one cpp +file for each Pyste file. This files will contain a function named after the +file, for instance Export_MyPysteFile, which will contain all the code to export +the classes, enums, etc. You can pass as much files as you want this way: + +[pre >python pyste.py --module=mymodule file1.pyste file2.pyste] + +This will create the files [^mymodule/file1.cpp] and [^mymodule/file2.cpp]. You +can then later do: + +[pre >python pyste.py --module=mymodule file3.pyste] + +and [^mymodule/file3.cpp] will be generated. + +But compiling and linking this files won't be sufficient to generate your +extension. You have to also generate a file named [^main.cpp]; call pyste with +[*all] the Pyste files of your extension, and use the [^--generate-main] option: + +[pre >python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste] + +Now compile and link all this files together and your extension is ready for +use. + +[h2 Cache] + +Pyste now supports a form of cache, which is a way to speed up the code +generation. Most of the time that Pyste takes to generate the code comes from +having to execute GCCXML (since being a front-end to GCC, it has to compile the +header files) and reading back the XML generated. + +When you use the [^--cache-dir=<dir>] option, Pyste will dump in the specified +directory the generated XMLs to a file named after the Pyste file, with the +extension [^.pystec]. The next time you run with this option, Pyste will use +the cache, instead of calling GCCXML again: + +[pre >python pyste.py --module=mymodule --cache-dir=cache file1.pyste] + +Will generate [^file1.cpp] and [^cache/file1.pystec]. Next time you execute +this command, the cache file will be used. Note that Pyste doesn't do any check +to ensure that the cache is up to date, but you can configure your build system to do that for you. + +When you run Pyste with [^--only-create-cache], all the cache files will be +created again, but no code will be generated. + +[page The Interface Files] + +The interface files are the heart of Pyste. The user creates one or more +interface files declaring the classes and functions he wants to export, and then +invokes Pyste passing the interface files to it. Pyste then generates a single +cpp file with Boost.Python code, with all the classes and functions exported. + +Besides declaring the classes and functions, the user has a number of other +options, like renaming e excluding classes and member functionis. Those are +explained later on. + +[h2 Basics] + +Suppose we have a class and some functions that we want to expose to Python +declared in the header [^hello.h]: + + struct World + { + World(std::string msg): msg(msg) {} + void set(std::string msg) { this->msg = msg; } + std::string greet() { return msg; } + std::string msg; + }; + + enum choice { red, blue }; + + namespace test { + + void show(choice c) { std::cout << "value: " << (int)c << std::endl; } + + } + +We create a file named [^hello.pyste] and create instances of the classes +[^Function], [^Class] and [^Enum]: + + Function("test::show", "hello.h") + Class("World", "hello.h") + Enum("choice", "hello.h") + +That will expose the class, the free function and the enum found in [^hello.h]. + +[h2 Inheritance] + +Pyste automatically generates the correct code (specifying [^bases<>] in the +[^class_] declaration) [*if] the Class() function that exports the base classes +and their children are in the same Pyste file. If that's not the case, you have +to indicate that there's a relationship between the Pyste files using the +[^Import] function specifying the other Pyste file. + +Suppose we have two classes, [^A] and [^B], and A is a base class for B. We +create two Pyste files: + +[^A.pyste]: + + Class("A", "A.h") + +[^B.pyste]: + + Import("A.pyste") + Class("B", "B.h") + +Note that we specify that [^B] needs to know about [^A] to be properly exported. + +[page:1 Renaming and Excluding] + +You can easily rename functions, classes, member functions, attributes, etc. Just use the +function [^rename], like this: + + World = Class("World", "hello.h") + rename(World, "IWorld") + show = Function("choice", "hello.h") + rename(show, "Show") + +You can rename member functions and attributes using this syntax: + + rename(World.greet, "Greet") + rename(World.set, "Set") + choice = Enum("choice", "hello.h") + rename(choice.red, "Red") + rename(choice.blue, "Blue") + +You can exclude functions, classes, member functions, attributes, etc, in the same way, +with the function [^exclude]: + + exclude(World.greet) + exclude(World.msg) + +To access the operators of a class, access the member [^operator] like this +(supposing that [^C] is a class being exported): + + exclude(C.operator['+']) + exclude(C.operator['*']) + exclude(C.operator['<<']) + +The string inside the brackets is the same as the name of the operator in C++.[br] + +[h2 Virtual Member Functions] + +Pyste automatically generates wrappers for virtual member functions, but you may +want to disable this behaviour (for performance reasons, for instance) if you do +not plan to override the functions in Python. To do this, use the function +[^final]: + + C = Class('C', 'C.h') + final(C.foo) # C::foo is a virtual member function + +No virtual wrapper code will be generated for the virtual member function +C::foo that way. + +[page:1 Policies] + +Even thought Pyste can identify various elements in the C++ code, like virtual +member functions, attributes, and so on, one thing that it can't do is to +guess the semantics of functions that return pointers or references. In this +case, the user must manually specify the policy. Policies are explained in the +[@../../doc/tutorial/doc/call_policies.html tutorial]. + +The policies in Pyste are named exactly as in Boost.Python, only the syntax is +slightly different. For instance, this policy: + + return_internal_reference<1, with_custodian_and_ward<1, 2> >() + +becomes in Pyste: + + return_internal_reference(1, with_custodian_and_ward(1, 2)) + +The user can specify policies for functions and virtual member functions with +the [^set_policy] function: + + set_policy(f, return_internal_reference()) + set_policy(C.foo, return_value_policy(manage_new_object)) + +[blurb +[$theme/note.gif] [*What if a function or member function needs a policy and +the user doesn't set one?][br][br] If a function needs a policy and one +was not set, Pyste will issue a error. The user should then go in the +interface file and set the policy for it, otherwise the generated cpp won't +compile. +] + +[blurb +[$theme/note.gif] +Note that for functions that return [^const T&], the policy +[^return_value_policy<copy_const_reference>()] wil be used by default, because +that's normally what you want. You can change it to something else if you need +to, though. +] + +[page:1 Templates] + +Template classes can easily be exported too, but you can't export the template +itself... you have to export instantiations of it! So, if you want to export a +[^std::vector], you will have to export vectors of int, doubles, etc. + +Suppose we have this code: + + template <class T> + struct Point + { + T x; + T y; + }; + +And we want to export [^Point]s of int and double: + + Point = Template("Point", "point.h") + Point("int") + Point("double") + +Pyste will assign default names for each instantiation. In this example, those +would be "[^Point_int]" and "[^Point_double]", but most of the time users will want to +rename the instantiations: + + Point("int", "IPoint") // renames the instantiation + double_inst = Point("double") // another way to do the same + rename(double_inst, "DPoint") + +Note that you can rename, exclude, set policies, etc, in the [^Template] object +like you would do with a [^Function] or a [^Class]. This changes affect all +[*future] instantiations: + + Point = Template("Point", "point.h") + Point("float", "FPoint") // will have x and y as data members + rename(Point.x, "X") + rename(Point.y, "Y") + Point("int", "IPoint") // will have X and Y as data members + Point("double", "DPoint") // also will have X and Y as data member + +If you want to change a option of a particular instantiation, you can do so: + + Point = Template("Point", "point.h") + Point("int", "IPoint") + d_inst = Point("double", "DPoint") + rename(d_inst.x, "X") // only DPoint is affect by this renames, + rename(d_inst.y, "Y") // IPoint stays intact + +[blurb [$theme/note.gif] [*What if my template accepts more than one type?] +[br][br] +When you want to instantiate a template with more than one type, you can pass +either a string with the types separated by whitespace, or a list of strings +'''("int double" or ["int", "double"]''' would both work). +] + +[page:1 Wrappers] + +Suppose you have this function: + + std::vector<std::string> names(); + +But you don't want to [@../../doc/v2/faq.html#question2 to export std::vector<std::string>], +you want this function to return a python list of strings. Boost.Python has +excellent support for things like that: + + list names_wrapper() + { + list result; + // call original function + vector<string> v = names(); + // put all the strings inside the python list + vector<string>::iterator it; + for (it = v.begin(); it != v.end(); ++it){ + result.append(*it); + } + return result; + } + + BOOST_PYTHON_MODULE(test) + { + def("names", &names_wrapper); + } + +Nice heh? Pyste supports this mechanism too. You declare the [^names_wrapper] +function in a header named "[^test_wrappers.h]" and in the interface file: + + Include("test_wrappers.h") + names = Function("names", "test.h") + set_wrapper(names, "names_wrapper") + +You can optionally declare the function in the interface file itself: + + names_wrapper = Wrapper("names_wrapper", + """ + list names_wrapper() + { + // code to call name() and convert the vector to a list... + } + """) + names = Function("names", "test.h") + set_wrapper(names, names_wrapper) + +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: + + struct C + { + std::vector<std::string> names(); + } + + list names_wrapper(C* c) + { + // same as before, calling c->names() and converting result to a list + } + +And then in the interface file: + + C = Class("C", "test.h") + set_wrapper(C.names, "names_wrapper") + +[blurb +[$theme/note.gif]Even though Boost.Python 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 [*pointer]. Doing otherwise will prevent your +code to compile when you set a wrapper for a virtual member function. +] + +[page:1 Exporting An Entire Header] + +Pyste also supports a mechanism to export all declarations found in a header +file. Suppose again our file, [^hello.h]: + + struct World + { + World(std::string msg): msg(msg) {} + void set(std::string msg) { this->msg = msg; } + std::string greet() { return msg; } + std::string msg; + }; + + enum choice { red, blue }; + + void show(choice c) { std::cout << "value: " << (int)c << std::endl; } + +You can just use the [^AllFromHeader] construct: + + hello = AllFromHeader("hello.h") + +this will export all the declarations found in [^hello.h], which is equivalent +to write: + + Class("World", "hello.h") + Enum("choice", "hello.h") + Function("show", "hello.h") + +Note that you can still use the functions [^rename], [^set_policy], [^exclude], etc. Just access +the members of the header object like this: + + rename(hello.World.greet, "Greet") + exclude(hello.World.set, "Set") + +[blurb +[$theme/note.gif] [*AllFromHeader is broken] in some cases. Until it is fixed, +use at you own risk. +] + + +[page:1 Smart Pointers] + +Pyste for now has manual support for smart pointers. Suppose: + + struct C + { + int value; + }; + + boost::shared_ptr<C> newC(int value) + { + boost::shared_ptr<C> c( new C() ); + c->value = value; + return c; + } + + void printC(boost::shared_ptr<C> c) + { + std::cout << c->value << std::endl; + } + +To make [^newC] and [^printC] work correctly, you have to tell Pyste that a +convertor for [^boost::shared_ptr<C>] is needed. + + C = Class('C', 'C.h') + use_shared_ptr(C) + Function('newC', 'C.h') + Function('printC', 'C.h') + +For [^std::auto_ptr]'s, use the function [^use_auto_ptr]. + +This system is temporary, and in the future the converters will automatically be +exported if needed, without the need to tell Pyste about them explicitly. + +[h2 Holders] + +If only the converter for the smart pointers is not enough and you need to +specify the smart pointer as the holder for a class, use the functions +[^hold_with_shared_ptr] and [^hold_with_auto_ptr]: + + C = Class('C', 'C.h') + hold_with_shared_ptr(C) + Function('newC', 'C.h') + Function('printC', 'C.h') + +[page:1 Global Variables] + +To export global variables, use the [^Var] construct: + + Var("myglobal", "foo.h") + +Beware of non-const global variables: changes in Python won't reflect in C++! +If you really must change them in Python, you will have to write some accessor +functions, and export those. + + +[page:1 Adding New Methods] + +Suppose that you want to add a function to a class, turning it into a member +function: + + struct World + { + void set(std::string msg) { this->msg = msg; } + std::string msg; + }; + + std::string greet(World& w) + { + return w.msg; + } + +Here, we want to make [^greet] work as a member function of the class [^World]. We do +that using the [^add_method] construct: + + W = Class("World", "hello.h") + add_method(W, "greet") + +Notice also that then you can rename it, set its policy, just like a regular +member function: + + rename(W.greet, 'Greet') + +Now from Python: + + >>> import hello + >>> w = hello.World() + >>> w.set('Ni') + >>> w.greet() + 'Ni' + >>> print 'Oh no! The knights who say Ni!' + Oh no! The knights who say Ni! + + +[page:1 Inserting Code] + +You can insert arbitrary code in the generated cpps, just use the functions +[^declaration_code] and [^module_code]. This will insert the given string in the +respective sections. Example: + + # file A.pyste + Class("A", "A.h") + declaration_code("/* declaration_code() comes here */\n") + module_code("/* module_code() comes here */\n") + +Will generate: + + // Includes ==================================================================== + #include <boost/python.hpp> + + // Using ======================================================================= + using namespace boost::python; + + // Declarations ================================================================ + + /* declaration_code() comes here */ + + // Module ====================================================================== + BOOST_PYTHON_MODULE(A) + { + class_< A >("A", init< >()) + .def(init< const A& >()) + ; + + /* module_code() comes here */ + } diff --git a/libs/python/pyste/doc/renaming_and_excluding.html b/libs/python/pyste/doc/renaming_and_excluding.html new file mode 100644 index 000000000..ce6654c4a --- /dev/null +++ b/libs/python/pyste/doc/renaming_and_excluding.html @@ -0,0 +1,87 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Renaming and Excluding</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="the_interface_files.html"> +<link rel="next" href="policies.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>Renaming and Excluding</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="the_interface_files.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="policies.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +You can easily rename functions, classes, member functions, attributes, etc. Just use the +function <tt>rename</tt>, like this:</p> +<code><pre> + <span class=identifier>World </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=string>"World"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>World</span><span class=special>, </span><span class=string>"IWorld"</span><span class=special>) + </span><span class=identifier>show </span><span class=special>= </span><span class=identifier>Function</span><span class=special>(</span><span class=string>"choice"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>show</span><span class=special>, </span><span class=string>"Show"</span><span class=special>) +</span></pre></code> +<p> +You can rename member functions and attributes using this syntax:</p> +<code><pre> + <span class=identifier>rename</span><span class=special>(</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>greet</span><span class=special>, </span><span class=string>"Greet"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>set</span><span class=special>, </span><span class=string>"Set"</span><span class=special>) + </span><span class=identifier>choice </span><span class=special>= </span><span class=identifier>Enum</span><span class=special>(</span><span class=string>"choice"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>choice</span><span class=special>.</span><span class=identifier>red</span><span class=special>, </span><span class=string>"Red"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>choice</span><span class=special>.</span><span class=identifier>blue</span><span class=special>, </span><span class=string>"Blue"</span><span class=special>) +</span></pre></code> +<p> +You can exclude functions, classes, member functions, attributes, etc, in the same way, +with the function <tt>exclude</tt>:</p> +<code><pre> + <span class=identifier>exclude</span><span class=special>(</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>greet</span><span class=special>) + </span><span class=identifier>exclude</span><span class=special>(</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>msg</span><span class=special>) +</span></pre></code> +<p> +To access the operators of a class, access the member <tt>operator</tt> like this +(supposing that <tt>C</tt> is a class being exported):</p> +<code><pre> + <span class=identifier>exclude</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=keyword>operator</span><span class=special>[</span><span class=literal>'+'</span><span class=special>]) + </span><span class=identifier>exclude</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=keyword>operator</span><span class=special>[</span><span class=literal>'*'</span><span class=special>]) + </span><span class=identifier>exclude</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=keyword>operator</span><span class=special>[</span><span class=literal>'<<'</span><span class=special>]) +</span></pre></code> +<p> +The string inside the brackets is the same as the name of the operator in C++.<br></p> +<a name="virtual_member_functions"></a><h2>Virtual Member Functions</h2><p> +Pyste automatically generates wrappers for virtual member functions, but you may +want to disable this behaviour (for performance reasons, for instance) if you do +not plan to override the functions in Python. To do this, use the function +<tt>final</tt>:</p> +<code><pre> + <span class=identifier>C </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=literal>'C'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) + </span><span class=identifier>final</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=identifier>foo</span><span class=special>) </span>##<span class=identifier>C</span><span class=special>::</span><span class=identifier>foo </span><span class=identifier>is </span><span class=identifier>a </span><span class=keyword>virtual </span><span class=identifier>member </span><span class=identifier>function +</span></pre></code> +<p> +No virtual wrapper code will be generated for the virtual member function +C::foo that way.</p> +<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="the_interface_files.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="policies.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/running_pyste.html b/libs/python/pyste/doc/running_pyste.html new file mode 100644 index 000000000..9bd9a3aee --- /dev/null +++ b/libs/python/pyste/doc/running_pyste.html @@ -0,0 +1,200 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Running Pyste</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="introduction.html"> +<link rel="next" href="the_interface_files.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>Running Pyste</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="introduction.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="the_interface_files.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +To run Pyste, you will need:</p> +<ul><li>Python 2.2, available at <a href="http://www.python.org"> +python's website</a>.</li><li>The great <a href="http://effbot.org"> +elementtree</a> library, from Fredrik Lundh.</li><li>The excellent <a href="http://www.gccxml.org"> +GCCXML</a>, from Brad King.</li></ul><p> +Installation for the tools is available in their respective webpages.</p> +<table width="80%" border="0" align="center"> + <tr> + <td class="note_box"> + +<img src="theme/note.gif"></img> <a href="http://www.gccxml.org"> +GCCXML</a> must be accessible in the PATH environment variable, so +that Pyste can call it. How to do this varies from platform to platform. + </td> + </tr> +</table> +<a name="ok__now_what_"></a><h2>Ok, now what?</h2><p> +Well, now let's fire it up:</p> +<code><pre> + +>python pyste.py + +Pyste version 0.9.26 + +Usage: + pyste [options] interface-files + +where options are: + --module=<name> The name of the module that will be generated; + defaults to the first interface filename, without + the extension. + -I <path> Add an include path + -D <symbol> Define symbol + --multiple Create various cpps, instead of only one + (useful during development) + --out=<name> Specify output filename (default: <module>.cpp) + in --multiple mode, this will be a directory + --no-using Do not declare "using namespace boost"; + use explicit declarations instead + --pyste-ns=<name> Set the namespace where new types will be declared; + default is the empty namespace + --debug Writes the xml for each file parsed in the current + directory + --cache-dir=<dir> Directory for cache files (speeds up future runs) + --only-create-cache Recreates all caches (doesn't generate code). + --generate-main Generates the _main.cpp file (in multiple mode) + --file-list A file with one pyste file per line. Use as a + substitute for passing the files in the command + line. + -h, --help Print this help and exit + -v, --version Print version information + + +</pre></code><p> +Options explained:</p> +<p> +The <tt>-I</tt> and <tt>-D</tt> are preprocessor flags, which are needed by <a href="http://www.gccxml.org"> +GCCXML</a> to parse +the header files correctly and by Pyste to find the header files declared in the +interface files.</p> +<p> +<tt>--out</tt> names the output file (default: <tt><module>.cpp</tt>), or in multiple mode, +names a output directory for the files (default: <tt><module></tt>).</p> +<p> +<tt>--no-using</tt> tells Pyste to don't declare "<tt>using namespace boost;</tt>" in the +generated cpp, using the namespace boost::python explicitly in all declarations. +Use only if you're having a name conflict in one of the files.</p> +<p> +Use <tt>--pyste-ns</tt> to change the namespace where new types are declared (for +instance, the virtual wrappers). Use only if you are having any problems. By +default, Pyste uses the empty namespace.</p> +<p> +<tt>--debug</tt> will write in the current directory a xml file as outputted by <a href="http://www.gccxml.org"> +GCCXML</a> +for each header parsed. Useful for bug reports.</p> +<p> +<tt>--file-list</tt> names a file where each line points to a Pyste file. Use this instead +to pass the pyste files if you have a lot of them and your shell has some command line +size limit.</p> +<p> +The other options are explained below, in <a href="#multiple_mode"> +<b>Multiple Mode</b></a> and +<a href="#cache"> +<b>Cache</b></a>.</p> +<p> +<tt>-h, --help, -v, --version</tt> are self-explaining, I believe. ;)</p> +<p> +So, the usage is simple enough:</p> +<code><pre>>python pyste.py --module=mymodule file.pyste file2.pyste ...</pre></code><p> +will generate a file <tt>mymodule.cpp</tt> in the same dir where the command was +executed. Now you can compile the file using the same instructions of the +<a href="../../doc/tutorial/doc/html/python/hello.html"> +tutorial</a>. </p> +<a name="wait____how_do_i_set_those_i_and_d_flags_"></a><h2>Wait... how do I set those I and D flags?</h2><p> +Don't worry: normally <a href="http://www.gccxml.org"> +GCCXML</a> is already configured correctly for your plataform, +so the search path to the standard libraries and the standard defines should +already be set. You only have to set the paths to other libraries that your code +needs, like Boost, for example.</p> +<p> +Plus, Pyste automatically uses the contents of the environment variable +<tt>INCLUDE</tt> if it exists. Visual C++ users should run the <tt>Vcvars32.bat</tt> file, +which for Visual C++ 6 is normally located at:</p> +<code><pre> + <span class=identifier>C</span><span class=special>:\</span><span class=identifier>Program </span><span class=identifier>Files</span><span class=special>\</span><span class=identifier>Microsoft </span><span class=identifier>Visual </span><span class=identifier>Studio</span><span class=special>\</span><span class=identifier>VC98</span><span class=special>\</span><span class=identifier>bin</span><span class=special>\</span><span class=identifier>Vcvars32</span><span class=special>.</span><span class=identifier>bat +</span></pre></code> +<p> +with that, you should have little trouble setting up the flags.</p> +<table width="80%" border="0" align="center"> + <tr> + <td class="note_box"> +<img src="theme/note.gif"></img><b>A note about Psyco</b><br><br> +Although you don't have to install <a href="http://psyco.sourceforge.net/"> +Psyco</a> to +use Pyste, if you do, Pyste will make use of it to speed up the wrapper +generation. Speed ups of 30% can be achieved, so it's highly recommended. + </td> + </tr> +</table> +<a name="multiple_mode"></a><h2>Multiple Mode</h2><p> +The multiple mode is useful in large projects, where the presence of multiple +classes in a single file makes the compilation unpractical (excessive memory +usage, mostly). </p> +<p> +The solution is make Pyste generate multiple files, more specifically one cpp +file for each Pyste file. This files will contain a function named after the +file, for instance Export_MyPysteFile, which will contain all the code to export +the classes, enums, etc. You can pass as much files as you want this way:</p> +<code><pre>>python pyste.py --module=mymodule file1.pyste file2.pyste</pre></code><p> +This will create the files <tt>mymodule/file1.cpp</tt> and <tt>mymodule/file2.cpp</tt>. You +can then later do:</p> +<code><pre>>python pyste.py --module=mymodule file3.pyste</pre></code><p> +and <tt>mymodule/file3.cpp</tt> will be generated.</p> +<p> +But compiling and linking this files won't be sufficient to generate your +extension. You have to also generate a file named <tt>main.cpp</tt>; call pyste with +<b>all</b> the Pyste files of your extension, and use the <tt>--generate-main</tt> option:</p> +<code><pre>>python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste</pre></code><p> +Now compile and link all this files together and your extension is ready for +use.</p> +<a name="cache"></a><h2>Cache</h2><p> +Pyste now supports a form of cache, which is a way to speed up the code +generation. Most of the time that Pyste takes to generate the code comes from +having to execute <a href="http://www.gccxml.org"> +GCCXML</a> (since being a front-end to GCC, it has to compile the +header files) and reading back the XML generated. </p> +<p> +When you use the <tt>--cache-dir=<dir></tt> option, Pyste will dump in the specified +directory the generated XMLs to a file named after the Pyste file, with the +extension <tt>.pystec</tt>. The next time you run with this option, Pyste will use +the cache, instead of calling <a href="http://www.gccxml.org"> +GCCXML</a> again:</p> +<code><pre>>python pyste.py --module=mymodule --cache-dir=cache file1.pyste</pre></code><p> +Will generate <tt>file1.cpp</tt> and <tt>cache/file1.pystec</tt>. Next time you execute +this command, the cache file will be used. Note that Pyste doesn't do any check +to ensure that the cache is up to date, but you can configure your build system to do that for you.</p> +<p> +When you run Pyste with <tt>--only-create-cache</tt>, all the cache files will be +created again, but no code will be generated.</p> +<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="introduction.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="the_interface_files.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/smart_pointers.html b/libs/python/pyste/doc/smart_pointers.html new file mode 100644 index 000000000..cddc96f2f --- /dev/null +++ b/libs/python/pyste/doc/smart_pointers.html @@ -0,0 +1,84 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Smart Pointers</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="exporting_an_entire_header.html"> +<link rel="next" href="global_variables.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>Smart Pointers</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="exporting_an_entire_header.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="global_variables.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +Pyste for now has manual support for smart pointers. Suppose:</p> +<code><pre> + <span class=keyword>struct </span><span class=identifier>C + </span><span class=special>{ + </span><span class=keyword>int </span><span class=identifier>value</span><span class=special>; + }; + + </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>shared_ptr</span><span class=special><</span><span class=identifier>C</span><span class=special>> </span><span class=identifier>newC</span><span class=special>(</span><span class=keyword>int </span><span class=identifier>value</span><span class=special>) + { + </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>shared_ptr</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=keyword>new </span><span class=identifier>C</span><span class=special>() ); + </span><span class=identifier>c</span><span class=special>-></span><span class=identifier>value </span><span class=special>= </span><span class=identifier>value</span><span class=special>; + </span><span class=keyword>return </span><span class=identifier>c</span><span class=special>; + } + + </span><span class=keyword>void </span><span class=identifier>printC</span><span class=special>(</span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>shared_ptr</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>std</span><span class=special>::</span><span class=identifier>cout </span><span class=special><< </span><span class=identifier>c</span><span class=special>-></span><span class=identifier>value </span><span class=special><< </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>endl</span><span class=special>; + } +</span></pre></code> +<p> +To make <tt>newC</tt> and <tt>printC</tt> work correctly, you have to tell Pyste that a +convertor for <tt>boost::shared_ptr<C></tt> is needed.</p> +<code><pre> + <span class=identifier>C </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=literal>'C'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) + </span><span class=identifier>use_shared_ptr</span><span class=special>(</span><span class=identifier>C</span><span class=special>) + </span><span class=identifier>Function</span><span class=special>(</span><span class=literal>'newC'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) + </span><span class=identifier>Function</span><span class=special>(</span><span class=literal>'printC'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) +</span></pre></code> +<p> +For <tt>std::auto_ptr</tt>'s, use the function <tt>use_auto_ptr</tt>.</p> +<p> +This system is temporary, and in the future the converters will automatically be +exported if needed, without the need to tell Pyste about them explicitly.</p> +<a name="holders"></a><h2>Holders</h2><p> +If only the converter for the smart pointers is not enough and you need to +specify the smart pointer as the holder for a class, use the functions +<tt>hold_with_shared_ptr</tt> and <tt>hold_with_auto_ptr</tt>:</p> +<code><pre> + <span class=identifier>C </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=literal>'C'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) + </span><span class=identifier>hold_with_shared_ptr</span><span class=special>(</span><span class=identifier>C</span><span class=special>) + </span><span class=identifier>Function</span><span class=special>(</span><span class=literal>'newC'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) + </span><span class=identifier>Function</span><span class=special>(</span><span class=literal>'printC'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>) +</span></pre></code> +<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="exporting_an_entire_header.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="global_variables.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/templates.html b/libs/python/pyste/doc/templates.html new file mode 100644 index 000000000..a1c1cfefb --- /dev/null +++ b/libs/python/pyste/doc/templates.html @@ -0,0 +1,102 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>Templates</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="policies.html"> +<link rel="next" href="wrappers.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>Templates</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="policies.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="wrappers.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +Template classes can easily be exported too, but you can't export the template +itself... you have to export instantiations of it! So, if you want to export a +<tt>std::vector</tt>, you will have to export vectors of int, doubles, etc.</p> +<p> +Suppose we have this code:</p> +<code><pre> + <span class=keyword>template </span><span class=special><</span><span class=keyword>class </span><span class=identifier>T</span><span class=special>> + </span><span class=keyword>struct </span><span class=identifier>Point + </span><span class=special>{ + </span><span class=identifier>T </span><span class=identifier>x</span><span class=special>; + </span><span class=identifier>T </span><span class=identifier>y</span><span class=special>; + }; +</span></pre></code> +<p> +And we want to export <tt>Point</tt>s of int and double:</p> +<code><pre> + <span class=identifier>Point </span><span class=special>= </span><span class=identifier>Template</span><span class=special>(</span><span class=string>"Point"</span><span class=special>, </span><span class=string>"point.h"</span><span class=special>) + </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"int"</span><span class=special>) + </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"double"</span><span class=special>) +</span></pre></code> +<p> +Pyste will assign default names for each instantiation. In this example, those +would be "<tt>Point_int</tt>" and "<tt>Point_double</tt>", but most of the time users will want to +rename the instantiations:</p> +<code><pre> + <span class=identifier>Point</span><span class=special>(</span><span class=string>"int"</span><span class=special>, </span><span class=string>"IPoint"</span><span class=special>) // </span><span class=identifier>renames </span><span class=identifier>the </span><span class=identifier>instantiation + </span><span class=identifier>double_inst </span><span class=special>= </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"double"</span><span class=special>) // </span><span class=identifier>another </span><span class=identifier>way </span><span class=identifier>to </span><span class=keyword>do </span><span class=identifier>the </span><span class=identifier>same + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>double_inst</span><span class=special>, </span><span class=string>"DPoint"</span><span class=special>) +</span></pre></code> +<p> +Note that you can rename, exclude, set policies, etc, in the <tt>Template</tt> object +like you would do with a <tt>Function</tt> or a <tt>Class</tt>. This changes affect all +<b>future</b> instantiations:</p> +<code><pre> + <span class=identifier>Point </span><span class=special>= </span><span class=identifier>Template</span><span class=special>(</span><span class=string>"Point"</span><span class=special>, </span><span class=string>"point.h"</span><span class=special>) + </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"float"</span><span class=special>, </span><span class=string>"FPoint"</span><span class=special>) // </span><span class=identifier>will </span><span class=identifier>have </span><span class=identifier>x </span><span class=keyword>and </span><span class=identifier>y </span><span class=identifier>as </span><span class=identifier>data </span><span class=identifier>members + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>Point</span><span class=special>.</span><span class=identifier>x</span><span class=special>, </span><span class=string>"X"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>Point</span><span class=special>.</span><span class=identifier>y</span><span class=special>, </span><span class=string>"Y"</span><span class=special>) + </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"int"</span><span class=special>, </span><span class=string>"IPoint"</span><span class=special>) // </span><span class=identifier>will </span><span class=identifier>have </span><span class=identifier>X </span><span class=keyword>and </span><span class=identifier>Y </span><span class=identifier>as </span><span class=identifier>data </span><span class=identifier>members + </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"double"</span><span class=special>, </span><span class=string>"DPoint"</span><span class=special>) // </span><span class=identifier>also </span><span class=identifier>will </span><span class=identifier>have </span><span class=identifier>X </span><span class=keyword>and </span><span class=identifier>Y </span><span class=identifier>as </span><span class=identifier>data </span><span class=identifier>member +</span></pre></code> +<p> +If you want to change a option of a particular instantiation, you can do so:</p> +<code><pre> + <span class=identifier>Point </span><span class=special>= </span><span class=identifier>Template</span><span class=special>(</span><span class=string>"Point"</span><span class=special>, </span><span class=string>"point.h"</span><span class=special>) + </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"int"</span><span class=special>, </span><span class=string>"IPoint"</span><span class=special>) + </span><span class=identifier>d_inst </span><span class=special>= </span><span class=identifier>Point</span><span class=special>(</span><span class=string>"double"</span><span class=special>, </span><span class=string>"DPoint"</span><span class=special>) + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>d_inst</span><span class=special>.</span><span class=identifier>x</span><span class=special>, </span><span class=string>"X"</span><span class=special>) // </span><span class=identifier>only </span><span class=identifier>DPoint </span><span class=identifier>is </span><span class=identifier>affect </span><span class=identifier>by </span><span class=keyword>this </span><span class=identifier>renames</span><span class=special>, + </span><span class=identifier>rename</span><span class=special>(</span><span class=identifier>d_inst</span><span class=special>.</span><span class=identifier>y</span><span class=special>, </span><span class=string>"Y"</span><span class=special>) // </span><span class=identifier>IPoint </span><span class=identifier>stays </span><span class=identifier>intact +</span></pre></code> +<table width="80%" border="0" align="center"> + <tr> + <td class="note_box"> +<img src="theme/note.gif"></img> <b>What if my template accepts more than one type?</b> +<br><br> +When you want to instantiate a template with more than one type, you can pass +either a string with the types separated by whitespace, or a list of strings +("int double" or ["int", "double"] would both work). + </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="policies.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="wrappers.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/the_interface_files.html b/libs/python/pyste/doc/the_interface_files.html new file mode 100644 index 000000000..9c0200432 --- /dev/null +++ b/libs/python/pyste/doc/the_interface_files.html @@ -0,0 +1,102 @@ +<html> +<head> +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> +<title>The Interface Files</title> +<link rel="stylesheet" href="theme/style.css" type="text/css"> +<link rel="prev" href="running_pyste.html"> +<link rel="next" href="renaming_and_excluding.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>The Interface Files</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="running_pyste.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="renaming_and_excluding.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<p> +The interface files are the heart of Pyste. The user creates one or more +interface files declaring the classes and functions he wants to export, and then +invokes Pyste passing the interface files to it. Pyste then generates a single +cpp file with <a href="../../index.html"> +Boost.Python</a> code, with all the classes and functions exported.</p> +<p> +Besides declaring the classes and functions, the user has a number of other +options, like renaming e excluding classes and member functionis. Those are +explained later on.</p> +<a name="basics"></a><h2>Basics</h2><p> +Suppose we have a class and some functions that we want to expose to Python +declared in the header <tt>hello.h</tt>:</p> +<code><pre> + <span class=keyword>struct </span><span class=identifier>World + </span><span class=special>{ + </span><span class=identifier>World</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>): </span><span class=identifier>msg</span><span class=special>(</span><span class=identifier>msg</span><span class=special>) {} + </span><span class=keyword>void </span><span class=identifier>set</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>) { </span><span class=keyword>this</span><span class=special>-></span><span class=identifier>msg </span><span class=special>= </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>greet</span><span class=special>() { </span><span class=keyword>return </span><span class=identifier>msg</span><span class=special>; } + </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>msg</span><span class=special>; + }; + + </span><span class=keyword>enum </span><span class=identifier>choice </span><span class=special>{ </span><span class=identifier>red</span><span class=special>, </span><span class=identifier>blue </span><span class=special>}; + + </span><span class=keyword>namespace </span><span class=identifier>test </span><span class=special>{ + + </span><span class=keyword>void </span><span class=identifier>show</span><span class=special>(</span><span class=identifier>choice </span><span class=identifier>c</span><span class=special>) { </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>cout </span><span class=special><< </span><span class=string>"value: " </span><span class=special><< (</span><span class=keyword>int</span><span class=special>)</span><span class=identifier>c </span><span class=special><< </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>endl</span><span class=special>; } + + } +</span></pre></code> +<p> +We create a file named <tt>hello.pyste</tt> and create instances of the classes +<tt>Function</tt>, <tt>Class</tt> and <tt>Enum</tt>:</p> +<code><pre> + <span class=identifier>Function</span><span class=special>(</span><span class=string>"test::show"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>Class</span><span class=special>(</span><span class=string>"World"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) + </span><span class=identifier>Enum</span><span class=special>(</span><span class=string>"choice"</span><span class=special>, </span><span class=string>"hello.h"</span><span class=special>) +</span></pre></code> +<p> +That will expose the class, the free function and the enum found in <tt>hello.h</tt>. </p> +<a name="inheritance"></a><h2>Inheritance</h2><p> +Pyste automatically generates the correct code (specifying <tt>bases<></tt> in the +<tt>class_</tt> declaration) <b>if</b> the Class() function that exports the base classes +and their children are in the same Pyste file. If that's not the case, you have +to indicate that there's a relationship between the Pyste files using the +<tt>Import</tt> function specifying the other Pyste file.</p> +<p> +Suppose we have two classes, <tt>A</tt> and <tt>B</tt>, and A is a base class for B. We +create two Pyste files:</p> +<p> +<tt>A.pyste</tt>:</p> +<code><pre> + <span class=identifier>Class</span><span class=special>(</span><span class=string>"A"</span><span class=special>, </span><span class=string>"A.h"</span><span class=special>) +</span></pre></code> +<p> +<tt>B.pyste</tt>:</p> +<code><pre> + <span class=identifier>Import</span><span class=special>(</span><span class=string>"A.pyste"</span><span class=special>) + </span><span class=identifier>Class</span><span class=special>(</span><span class=string>"B"</span><span class=special>, </span><span class=string>"B.h"</span><span class=special>) +</span></pre></code> +<p> +Note that we specify that <tt>B</tt> needs to know about <tt>A</tt> to be properly exported.</p> +<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="running_pyste.html"><img src="theme/l_arr.gif" border="0"></a></td> + <td width="20"><a href="renaming_and_excluding.html"><img src="theme/r_arr.gif" border="0"></a></td> + </tr> +</table> +<br> +<hr size="1"><p class="copyright">Copyright © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> diff --git a/libs/python/pyste/doc/theme/alert.gif b/libs/python/pyste/doc/theme/alert.gif Binary files differnew file mode 100644 index 000000000..270764cc5 --- /dev/null +++ b/libs/python/pyste/doc/theme/alert.gif diff --git a/libs/python/pyste/doc/theme/arrow.gif b/libs/python/pyste/doc/theme/arrow.gif Binary files differnew file mode 100644 index 000000000..e33db0fb4 --- /dev/null +++ b/libs/python/pyste/doc/theme/arrow.gif diff --git a/libs/python/pyste/doc/theme/bkd.gif b/libs/python/pyste/doc/theme/bkd.gif Binary files differnew file mode 100644 index 000000000..dcabcb806 --- /dev/null +++ b/libs/python/pyste/doc/theme/bkd.gif diff --git a/libs/python/pyste/doc/theme/bkd2.gif b/libs/python/pyste/doc/theme/bkd2.gif Binary files differnew file mode 100644 index 000000000..b03d9ba97 --- /dev/null +++ b/libs/python/pyste/doc/theme/bkd2.gif diff --git a/libs/python/pyste/doc/theme/bulb.gif b/libs/python/pyste/doc/theme/bulb.gif Binary files differnew file mode 100644 index 000000000..74f3baac4 --- /dev/null +++ b/libs/python/pyste/doc/theme/bulb.gif diff --git a/libs/python/pyste/doc/theme/bullet.gif b/libs/python/pyste/doc/theme/bullet.gif Binary files differnew file mode 100644 index 000000000..da787e2ef --- /dev/null +++ b/libs/python/pyste/doc/theme/bullet.gif diff --git a/libs/python/pyste/doc/theme/l_arr.gif b/libs/python/pyste/doc/theme/l_arr.gif Binary files differnew file mode 100644 index 000000000..5b3cb1cbf --- /dev/null +++ b/libs/python/pyste/doc/theme/l_arr.gif diff --git a/libs/python/pyste/doc/theme/l_arr_disabled.gif b/libs/python/pyste/doc/theme/l_arr_disabled.gif Binary files differnew file mode 100644 index 000000000..ed58a605a --- /dev/null +++ b/libs/python/pyste/doc/theme/l_arr_disabled.gif diff --git a/libs/python/pyste/doc/theme/note.gif b/libs/python/pyste/doc/theme/note.gif Binary files differnew file mode 100644 index 000000000..bd92f0755 --- /dev/null +++ b/libs/python/pyste/doc/theme/note.gif diff --git a/libs/python/pyste/doc/theme/r_arr.gif b/libs/python/pyste/doc/theme/r_arr.gif Binary files differnew file mode 100644 index 000000000..2dcdad117 --- /dev/null +++ b/libs/python/pyste/doc/theme/r_arr.gif diff --git a/libs/python/pyste/doc/theme/r_arr_disabled.gif b/libs/python/pyste/doc/theme/r_arr_disabled.gif Binary files differnew file mode 100644 index 000000000..2100f78bf --- /dev/null +++ b/libs/python/pyste/doc/theme/r_arr_disabled.gif diff --git a/libs/python/pyste/doc/theme/smiley.gif b/libs/python/pyste/doc/theme/smiley.gif Binary files differnew file mode 100644 index 000000000..4c848f8fe --- /dev/null +++ b/libs/python/pyste/doc/theme/smiley.gif diff --git a/libs/python/pyste/doc/theme/style.css b/libs/python/pyste/doc/theme/style.css new file mode 100644 index 000000000..643df02a9 --- /dev/null +++ b/libs/python/pyste/doc/theme/style.css @@ -0,0 +1,178 @@ +/*============================================================================= + Copyright (c) 2003 Bruno da Silva de Oliveira + + Use, modification and distribution is subject to 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) +=============================================================================*/ + +body +{ + background-image: url(bkd.gif); + background-color: #FFFFFF; + margin: 1em 2em 1em 2em; +} + +h1 { font-family: Verdana, Arial, Helvetica, sans-serif; font-weight: bold; text-align: left; } +h2 { font: 140% sans-serif; font-weight: bold; text-align: left; } +h3 { font: 120% sans-serif; font-weight: bold; text-align: left; } +h4 { font: bold 100% sans-serif; font-weight: bold; text-align: left; } +h5 { font: italic 100% sans-serif; font-weight: bold; text-align: left; } +h6 { font: small-caps 100% sans-serif; font-weight: bold; text-align: left; } + +pre +{ + border-top: gray 1pt solid; + border-right: gray 1pt solid; + border-left: gray 1pt solid; + border-bottom: gray 1pt solid; + + padding-top: 2pt; + padding-right: 2pt; + padding-left: 2pt; + padding-bottom: 2pt; + + display: block; + font-family: "courier new", courier, mono; + background-color: #eeeeee; font-size: small +} + +code +{ + font-family: "Courier New", Courier, mono; + font-size: small +} + +tt +{ + display: inline; + font-family: "Courier New", Courier, mono; + color: #000099; + font-size: small +} + +p +{ + text-align: justify; + font-family: Georgia, "Times New Roman", Times, serif +} + +ul +{ + list-style-image: url(bullet.gif); + font-family: Georgia, "Times New Roman", Times, serif +} + +ol +{ + font-family: Georgia, "Times New Roman", Times, serif +} + +a +{ + font-weight: bold; + color: #003366; + text-decoration: none; +} + +a:hover { color: #8080FF; } + +.literal { color: #666666; font-style: italic} +.keyword { color: #000099} +.identifier {} +.comment { font-style: italic; color: #990000} +.special { color: #800040} +.preprocessor { color: #FF0000} +.string { font-style: italic; color: #666666} +.copyright { color: #666666; font-size: small} +.white_bkd { background-color: #FFFFFF} +.dk_grey_bkd { background-color: #999999} +.quotes { color: #666666; font-style: italic; font-weight: bold} + +.note_box +{ + display: block; + + border-top: gray 1pt solid; + border-right: gray 1pt solid; + border-left: gray 1pt solid; + border-bottom: gray 1pt solid; + + padding-right: 12pt; + padding-left: 12pt; + padding-bottom: 12pt; + padding-top: 12pt; + + font-family: Arial, Helvetica, sans-serif; + background-color: #E2E9EF; + font-size: small; text-align: justify +} + +.table_title +{ + background-color: #648CCA; + + font-family: Verdana, Arial, Helvetica, sans-serif; color: #FFFFFF; + font-weight: bold +; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px +} + +.table_cells +{ + background-color: #E2E9EF; + + font-family: Geneva, Arial, Helvetica, san-serif; + font-size: small +; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px +} + +.toc +{ + DISPLAY: block; + background-color: #E2E9EF + font-family: Arial, Helvetica, sans-serif; + + border-top: gray 1pt solid; + border-left: gray 1pt solid; + border-bottom: gray 1pt solid; + border-right: gray 1pt solid; + + padding-top: 24pt; + padding-right: 24pt; + padding-left: 24pt; + padding-bottom: 24pt; +} + +.toc_title +{ + background-color: #648CCA; + padding-top: 4px; + padding-right: 4px; + padding-bottom: 4px; + padding-left: 4px; + font-family: Geneva, Arial, Helvetica, san-serif; + color: #FFFFFF; + font-weight: bold +} + +.toc_cells +{ + background-color: #E2E9EF; + padding-top: 4px; + padding-right: 4px; + padding-bottom: 4px; + padding-left: 4px; + font-family: Geneva, Arial, Helvetica, san-serif; + font-size: small +} + +div.logo +{ + float: right; +} + +.toc_cells_L0 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small } +.toc_cells_L1 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 44px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small } +.toc_cells_L2 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 88px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small } +.toc_cells_L3 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 122px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small } +.toc_cells_L4 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 166px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small } diff --git a/libs/python/pyste/doc/theme/u_arr.gif b/libs/python/pyste/doc/theme/u_arr.gif Binary files differnew file mode 100644 index 000000000..ada3d6e04 --- /dev/null +++ b/libs/python/pyste/doc/theme/u_arr.gif 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><</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>> </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<std::string></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><</span><span class=identifier>string</span><span class=special>> </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><</span><span class=identifier>string</span><span class=special>>::</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>"names"</span><span class=special>, &</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 "<tt>test_wrappers.h</tt>" and in the interface file:</p> +<code><pre> + <span class=identifier>Include</span><span class=special>(</span><span class=string>"test_wrappers.h"</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>"names"</span><span class=special>, </span><span class=string>"test.h"</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>"names_wrapper"</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>"names_wrapper"</span><span class=special>, + </span><span class=string>""</span><span class=string>" + list names_wrapper() + { + // code to call name() and convert the vector to a list... + } + "</span><span class=string>""</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>"names"</span><span class=special>, </span><span class=string>"test.h"</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><</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>> </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>-></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>"C"</span><span class=special>, </span><span class=string>"test.h"</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>"names_wrapper"</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 © 2003 Bruno da Silva de Oliveira<br>Copyright © 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> |
