[pygccxml-commit] SF.net SVN: pygccxml: [794] pyplusplus_dev/docs
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [794] pyplusplus_dev/docs
|
From: <rom...@us...> - 2006-12-11 07:07:44
|
Revision: 794
http://svn.sourceforge.net/pygccxml/?rev=794&view=rev
Author: roman_yakovenko
Date: 2006-12-10 23:07:41 -0800 (Sun, 10 Dec 2006)
Log Message:
-----------
updating documentation
Modified Paths:
--------------
pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest
pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest
pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest
pyplusplus_dev/docs/peps/peps_index.rest
pyplusplus_dev/docs/pyplusplus.rest
Added Paths:
-----------
pyplusplus_dev/docs/documentation/functions/transformation/custom/
pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest
pyplusplus_dev/docs/documentation/functions/transformation/custom/www_configuration.py
Removed Paths:
-------------
pyplusplus_dev/docs/peps/function_transformation.rest
Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest 2006-12-10 20:42:12 UTC (rev 793)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -16,24 +16,29 @@
* ``inout``
-* ``input_array``
+* ``input_static_array``
-* ``output_array``
+* ``output_static_array``
The set doesn't cover all common use cases, but it will grow with every new
version of `Py++`_. If you created your own transformer consider to contribute
it to the project.
-I suggest you to start reading ``output`` transformer. It is pretty simple and
+I suggest you to start reading `output`_ transformer. It is pretty simple and
well explained.
+.. _`output` : ./output.html
+
All built-in transformers could be applied on any function, except constructors.
The support for constructors will be added in future releases.
You don't have to warry about call policies. You can set the call policy and
-`Py++`_ will generate correct code.
+`Py++`_ will generate the correct code.
+You don't have to warry about the number of arguments, transformers or return
+value. `Py++`_ handles pretty well such use cases.
+
.. _`Py++` : ./../pyplusplus.html
.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
.. _`Python`: http://www.python.org
Added: pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -0,0 +1,40 @@
+=========================
+User defined transformers
+=========================
+
+.. contents:: Table of contents
+
+----
+KISS
+----
+
+KISS - Keep It Simple Stupid!
+
+The main goal of the feature: to provide relatively simple way to implement
+custom transformers. More over, all `built-in transformers`_ implemented as is
+they were custom transformers.
+
+-----------
+How to ...?
+-----------
+
+Unfortunatelly I don't have enough time to write a complete documentation :-(.
+Meanwhile fill free to `contact me`_. You also can take a look on `built-in transformers`_
+implementation.
+
+.. _`contact me` : ../../../../links.html#id5
+.. _`built-in transformers` : ../built_in/built_in.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/transformation/custom/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/custom/www_configuration.py (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/custom/www_configuration.py 2006-12-11 07:07:41 UTC (rev 794)
@@ -0,0 +1,4 @@
+name = 'custom transformers'
+#main_html_file = 'index.html'
+
+names = { }
Modified: pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest 2006-12-10 20:42:12 UTC (rev 793)
+++ pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -59,7 +59,9 @@
function
The good news - they will not be changed between different runs of the code
-generator. If you are exposing an overloaded function, than `Py++`_ uses the ugly
+generator.
+
+If you are exposing an overloaded function, in that case `Py++`_ uses the ugly
function-wrapper name as an alias. It is up to you to change the alias:
.. code-block:: Python
Modified: pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest 2006-12-10 20:42:12 UTC (rev 793)
+++ pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -4,7 +4,7 @@
.. contents:: Table of contents
-* Function transformation
+**Function transformation**
`Py++`_ sub-system\\framework, which allows you to create function wrappers
and to keep smile.
@@ -12,21 +12,21 @@
The operation of changing one function into another in accordance with some
rules. Especially: a change of return type and\\or arguments and their mapping
to the original ones.
-
-* Function wrapper ( or just wrapper )
+**Function wrapper** ( or just wrapper )
+
C++ function, which calls some other function.
-* Immutable type
+**Immutable type**
An instance of this type could not be modified after construction
-* Transformer
+**Transformer**
An object that applies predefined set of rules on a function, during
function-wrapper construction process.
-* Function alias ( or just alias )
+**Function alias** ( or just alias )
Name under which `Python`_ users see the exposed function
Deleted: pyplusplus_dev/docs/peps/function_transformation.rest
===================================================================
--- pyplusplus_dev/docs/peps/function_transformation.rest 2006-12-10 20:42:12 UTC (rev 793)
+++ pyplusplus_dev/docs/peps/function_transformation.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -1,333 +0,0 @@
-========================
-Function transformation
-========================
-
-.. contents:: Table of contents
-
--------------------
-What is useful for?
--------------------
-
-https://realityforge.vrsource.org/view/PyppApi/CodeInserter gives a nice introduction
-and the problem description. Please read it.
-
------------
-Terminology
------------
-
-Lets say that we have a function ``f``:
-
-::
-
- f = R f( A0 a0, ..., AN an )
-
-``R`` and ``A*`` represent an arbitrary C++ types. What we want is to create
-another function ``ft`` (transformed):
-
-::
-
- ft = RT ft( AT0 at0, ..., ATM atm )
-
-such that will do an additional work before and after ``f`` call.
-
-Definitions
------------
-
-*Transformation* - process that defines how to create transformed function from the
-original one.
-
-For example - ``make function argument to be return value``:
-::
-
- f = void get_last_error( int& error );
-
-::
-
- ft = int get_last_error();
-
-The definition of ``ft`` could look like:
-
-.. code-block:: C++
-
- int get_last_error_transformed(){
- int error(0);
- get_last_error( error );
- return error;
- }
-
-I modified ``f`` signature and added some code before and after ``f`` call.
-
-*Function transformation* - group of transformations that should be applied at once
-on a function.
-
-For example a function could have two immutable arguments, passed by reference.
-Function transformation aggregates two transformations.
-
-A user will be able to define few function transformations for a single function.
-
------------------------
-Design & implementation
------------------------
-
-In the previous paragraph I introduced two new concepts: "transformation" and
-"function transformation". These concepts should be presented in the solution.
-
-
-Transformation
---------------
-
-Transformation class has two responsibilities:
-
-1. to modify function signature:
-
- * remove argument
- * change argument type
- * join arguments
- * change return type
-
-2. to implement the transformation
-
-It is important to distinct between the responsibilities. Function signature
-defines "interface" for a lot of services provided by `Py++`_. While the second
-one is "implementation details" and should be "hidden" from the rest of the world.
-
-In an ideal world we would have 2 classes, one class - one responsibility.
-In `Py++`_ it means that we would have ``transformation_t`` class:
-
-.. code-block:: Python
-
- class transformation_t( object ):
- def __init__( self ):
- pass
-
-.. code-block:: Python
-
- def check( self, function ):
- "checks whether the transformation could be applied on the function or not"
- raise NotImplementedError()
-
-.. code-block:: Python
-
- def signature_changes( self, function ):
- "returns a list of changes that should be done on function signature"
- raise NotImplementedError()
-
-The class logically belongs to the ``decl_wrappers`` package. The ``transformer_t``
-is the second class, which logically belongs to ``code_creators`` package:
-
-.. code-block:: Python
-
- class transformer_t( ast_visitor_t ):
- def __init__( self, function, transformation ):
- function is a reference to the declaration we want to apply transformation on
- transformation is an instance of "concrete" transformation
-
-.. code-block:: Python
-
- def apply( self, function_body_as_tree ):
- "integrates transformation code to function body"
- raise NotImplementedError()
-
-What is ``ast_visitor_t`` and ``function_body_as_tree``. In an ideal world
-concrete instance of ``transformer_t`` class would work with some kind of AST
-( Abstract Syntax Tree ). Thus transformer would travel on the tree and modify it.
-
-Get the job done!
------------------
-
-The previously described solution will not work in our, `Py++`_ developers and
-users, world. There are mainly two reasons:
-
-1. AST approach is tooooooo complex. We don't have time to develop an AST for
- representing, even limited subset of C++ expressions. Users will not have
- time to learn how to use it.
-
-2. Class separation approach will not work too. In order to introduce new
- transformation, user will have to understand the whole design of the `Py++`_
- package.
-
-Matthias Baas provided a "real world" solution for both problems. At first I did
-not understand it, but now I appreciate it very much. It does not meant that I
-agree with the his implementation. As for me he did not stress enough the
-concepts within the code and more over he mixed them in different classes.
-
-I am going to propose another solution, which will be based on existing code.
-Small re-factoring is needed. I don't expect changes in the user code.
-
-Proposed class:
-
-.. code-block:: Python
-
- class transformer_t( object ):
- "base class for all transformation classes"
- def __init__( self ):
- pass
-
-.. code-block:: Python
-
- def check( self, function ):
- "checks whether the transformation could be applied on the function or not"
- raise NotImplementedError()
-
-.. code-block:: Python
-
- def signature_changes( self, function ):
- "returns a list of changes that should be done on function signature"
- raise NotImplementedError()
-
-.. code-block:: Python
-
- def apply( self, sm ): #sm is an instance of the substitution manager
- "integrates transformation code into function transformation body"
- raise NotImplementedError()
-
-Comments:
-
-1. ``substituion_manager_t`` class allows us to achieve same result as with AST.
- he way it does it is pretty simple to explain and understand - string
- substitution.
-
-2. ``transformer_t`` class allows user to introduce new transformations, without
- understanding the whole `Py++`_ package.
-
-Function trasformation
-~~~~~~~~~~~~~~~~~~~~~~
-
-What is responcibility of the ``function_transformation_t`` class?
-
-1. To keep reference to transformations defined by the user.
-
-2. To apply every transformation on the function body. For this purpose this
- class will keep instance of ``substituion_manager_t`` class.
-
-3. To provide interface for ``mem_fun_v_transformed_t`` and
- ``mem_fun_v_transformed_wrapper_t`` code creators classes.
-
-4. [Nice to have]To check, whether the transformation defined by user is
- applicable or not.
-
-Somewhere we should put "function transformation" factory. This factory will
-create or give a hint to the user what transformation could\\should be applied
-on the function.
-
--------------------------------------
-output_arg transformation example
--------------------------------------
-
-.. code-block:: Python
-
- class output_arg_t( transformer_t ):
- def __init__( self, ordinal ):
- self.ordinal = ordinal
-
-.. code-block:: Python
-
- def check( self, decl ):
- if len( decl.arguments ) <= self.ordinal:
- return user message
- type_ = decl.arguments[self.ordinal].type
- if not reference to immutable type:
- raise user message
-
-.. code-block:: Python
-
- def signature_changes( self, decl ):
- assert not self.check( decl )
- return [ remove_arg( self.ordinal )
- , add_var_to_return_value( decl.arguments[ self.ordinal ].name ]
-
-.. code-block:: Python
-
- def apply( self, sm ):
- if sm is wrapper around C++ function:
- sm. add declaration of variable type = decl.arguments[ self.ordinal ].type
- and name = decl.arguments[ self.ordinal ].type and initial value
- sm. add variable to return expression.
- else: #sm is a wrapper around Python function
- sm. extract value from the tuple and assign it to the argument
-
-.. code-block:: Python
-
- def output_arg( ordinal ):
- return output_arg_t( ordinal )
-
------------------
-Problems to solve
------------------
-
-I don't have any solution to the next problems.
-
-Call policies
--------------
-
-I am going to change a little an example, from `Boost.Python`_ tutorials:
-http://www.boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.call_policies
-
-.. code-block:: C++
-
- //C++ code
- struct Y
- {
- X x; Z* z;
- int z_value() { return z->value(); }
- };
-
-.. code-block:: C++
-
- X& f(Y& y, Z* z, int& error)
- {
- y.z = z;
- return y.x;
- }
-
-.. code-block:: C++
-
- //Boost.Python code
- def("f", f, return_internal_reference<1, with_custodian_and_ward<1, 2> >() );
-
-What is the difference? Function ``f`` now takes 3rd argument - ``int&``. This
-function could not be called from `Python`_. (Hint: numbers are immutable
-objects in `Python`_ ). So in order to expose function ``f`` to `Python`_,
-an user need to create a wrapper. And now he has a problem: how to wrap the function?
-
-I see only one solution user have to change signature of function ``f``.
-Now some speculations:
-
-1. May be it is possible with `Boost.Python`_ library to set call policies on the
- part of the return value?
-
- .. code-block:: C++
-
- boost::tuple f_wrapper( Y& y, Z* z ){
- int error(0);
- X& x = f( y, z, error );
- return boost::tuple<X&, int>( x, error );
- }
-
- def("f", f_wrapper, smart call policies that will work only on first element within the tuple );
-
-2. May be it is possible to create Boost.Python ``object`` with life-time management
- hint?
-
- .. code-block:: C++
-
- boost::python::tuple f_wrapper( Y& y, Z* z ){
- int error(0);
- X& x = f( y, z, error );
- boost::python::object x_obj( x, x is internal reference of y );
- return boost::python::make_tuple( x_obj, error );
- }
-
-.. _`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:
-
Modified: pyplusplus_dev/docs/peps/peps_index.rest
===================================================================
--- pyplusplus_dev/docs/peps/peps_index.rest 2006-12-10 20:42:12 UTC (rev 793)
+++ pyplusplus_dev/docs/peps/peps_index.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -42,15 +42,6 @@
The coding itself should take something like 4 - 5 hours, including unit test.
----------------------
-Call wrapper policies
----------------------
-
-Not all functions could be exposed to Python as is. This `document`__ will
-explain how `Py++`_ will help users to create wrappers around those functions.
-
-.. __ : ./function_transformation.html
-
------------------------------------------
Domain Specific Language ( DSL ) challenge
------------------------------------------
Modified: pyplusplus_dev/docs/pyplusplus.rest
===================================================================
--- pyplusplus_dev/docs/pyplusplus.rest 2006-12-10 20:42:12 UTC (rev 793)
+++ pyplusplus_dev/docs/pyplusplus.rest 2006-12-11 07:07:41 UTC (rev 794)
@@ -127,9 +127,11 @@
-------------
* `Py++`_ support almost all features found in `Boost.Python`_ library
+
* `Py++`_ generates code, which will help you to understand compiler generated
error messages
+
* `Py++`_ has few modes of writing code into files:
@@ -148,13 +150,13 @@
* Your license is written at the top of every file
* `Py++`_ will check the "completeness" of the bindings. It will check for you
- that exposed declarations don't have references to unexposed ones.
+ that the exposed declarations don't have references to unexposed ones.
* `Py++`_ provides enough functionality to extract source code documentation
and write it as Python documentation string
-* `Py++`_ provides simple and powerful framework to create wraper for functions,
- which could not be exposed as is to `Python`_.
+* `Py++`_ provides simple and powerful framework to create a wrapper for
+ functions, which could not be exposed as is to `Python`_.
* ...
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
