|
From: <rom...@us...> - 2006-10-12 14:59:42
|
Revision: 660
http://svn.sourceforge.net/pygccxml/?rev=660&view=rev
Author: roman_yakovenko
Date: 2006-10-12 07:59:28 -0700 (Thu, 12 Oct 2006)
Log Message:
-----------
adding documentation
Added Paths:
-----------
pyplusplus_dev/docs/documentation/functions/
pyplusplus_dev/docs/documentation/functions/call_policies.rest
pyplusplus_dev/docs/documentation/functions/functions.rest
pyplusplus_dev/docs/documentation/functions/www_configuration.py
Added: pyplusplus_dev/docs/documentation/functions/call_policies.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/call_policies.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/call_policies.rest 2006-10-12 14:59:28 UTC (rev 660)
@@ -0,0 +1,157 @@
+=============
+Call policies
+=============
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Boost.Python`_ has a `nice introduction`__ in the tutorials about call policies.
+Also you can find more formal definition - `CallPolicies Concept`_ .
+
+.. __ : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.call_policies
+.. _`CallPolicies Concept` : http://boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept
+
+------
+Syntax
+------
+
+The call policies in `Py++`_ are named exactly as in `Boost.Python`_, only the
+syntax is slightly different. For instance, this call policy:
+
+.. code-block:: C++
+
+ return_internal_reference< 1, with_custodian_and_ward<1, 2> >()
+
+becomes in `Py++`_
+
+.. code-block:: Python
+
+ return_internal_reference( 1, with_custodian_and_ward(1, 2) )
+
+`Py++`_ supports all call policies presented in `Boost.Python`_.
+
+-------------
+Usage example
+-------------
+
+Every "callable" object in `Py++`_ has ``call_policies`` property.
+
+C++ code:
+
+ .. code-block:: C++
+
+ struct data{...};
+ const data& do_smth( const data& d, int x );
+
+ void return_second_arg( int x, int y );
+
+ typedef struct opaque_ *opaque_pointer;
+ opaque_pointer get_opaque();
+
+Python code:
+
+ .. code-block:: Python
+
+ from pyplusplus import module_builder
+ from pyplusplus.module_builder import call_policies
+
+ mb = module_builder.module_builder_t( ... )
+ mb.free_function( 'return_second_arg' ).call_policies = call_policies.return_arg( 2 )
+
+ mb.member_function( 'do_smth' ).call_policies = call_policies.return_self()
+
+ mb.calldef( 'get_opaque' ).call_policies \
+ = call_policies.return_value_policy( call_policies.return_opaque_pointer )
+
+--------
+Defaults
+--------
+
+`Py++`_ is able to "guess" few call policies, base on analysis of return type:
+
+* ``default_call_policies``:
+
+ * `Python`_ immutable type by value: C++ fundamental types, ``std::string``, enumerations
+
+ * user defined type ( class ) by value
+
+ * ``const char*``
+
+* ``return_value_policy``
+
+ * ``return_opaque_pointer``
+
+ * ``void*``
+
+ * ``const void*``
+
+ * ``copy_const_reference``
+
+ * ``const T&``
+
+ * for member ``operator[]`` that returns const reference to immutable type
+
+ * ``return_by_value``
+
+ * ``const wchar_t*``
+
+ * ``copy_non_const_reference``
+
+ * ``T&``, for member ``operator[]`` that returns reference to immutable type
+
+ * ``return_internal_reference``
+
+ * ``T&``, for member ``operator[]``
+
+---------------------
+Missing call policies
+---------------------
+
+If you don't specify call policy for a function and it needs one, few things will
+happen:
+
+* `Py++`_ prints a warning message
+
+* `Py++`_ generates code with
+
+ .. code-block:: C++
+
+ /* undefined call policies */
+
+ comment, in place of call policy. If `Py++`_ was wrong and function doesn't
+ need call policy the generate code will compile fine, otherwise you will get a
+ compilation error.
+
+
+------------
+Special case
+------------
+
+``return_value_policy( return_opaque_pointer )`` is a special policy for `Boost.Python`_.
+In this case, it requieres from an user to define specializations for the
+``boost::python::type_id`` function on the type pointed to by returned pointer.
+`Py++`_ will generate the requiered code.
+
+For more information about the call policy please refer to `Boost.Python`_
+`documentation`_.
+
+.. _`documentation` : http://boost.org/libs/python/doc/v2/return_opaque_pointer.html
+
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Added: pyplusplus_dev/docs/documentation/functions/functions.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/functions.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/functions.rest 2006-10-12 14:59:28 UTC (rev 660)
@@ -0,0 +1,27 @@
+=====================
+Functions & operators
+=====================
+
+.. contents:: Table of contents
+
+--------
+Preamble
+--------
+
+`Boost.Python`_ provides very rich interface to expose functions and operators.
+This section of documentation will explain how to configure `Py++`_ in order
+to export your code using desired `Boost.Python`_ functionality.
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Added: pyplusplus_dev/docs/documentation/functions/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/www_configuration.py (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/www_configuration.py 2006-10-12 14:59:28 UTC (rev 660)
@@ -0,0 +1,5 @@
+name = 'functions & operators'
+#main_html_file = 'index.html'
+
+names = { 'call_policies' : 'call policies'
+}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
