From 8297598336b3248fd1d8be778f62b641121b98a0 Mon Sep 17 00:00:00 2001 From: Marcelo Lira Date: Mon, 16 Nov 2009 17:12:45 -0300 Subject: Shiboken documentation updated with type system variables information Reviewed by Hugo Lima --- doc/_templates/index.html | 6 ++- doc/contents.rst | 1 + doc/sequenceprotocol.rst | 3 +- doc/typesystemvariables.rst | 105 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 111 insertions(+), 4 deletions(-) create mode 100644 doc/typesystemvariables.rst (limited to 'doc') diff --git a/doc/_templates/index.html b/doc/_templates/index.html index ef2e9a610..2accb5d2e 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -11,12 +11,14 @@

Contents
for a complete overview

+

Type System Variables
+ describes the type system variables that could be used in user custom code

Code Injection Semantics
explains how custom code injection is interpreted by {{ project }}

-

Sequence Protocol
- support for python sequence protocol

+

Sequence Protocol
+ support for python sequence protocol

Compiling/Installing
how to compile and install {{ project }}

FAQ
diff --git a/doc/contents.rst b/doc/contents.rst index 4e0a5e9e5..f6735ee83 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -5,6 +5,7 @@ Table of contents :maxdepth: 3 faq.rst + typesystemvariables.rst codeinjectionsemantics.rst sequenceprotocol.rst compiling.rst diff --git a/doc/sequenceprotocol.rst b/doc/sequenceprotocol.rst index 2ac48588e..587c0f95b 100644 --- a/doc/sequenceprotocol.rst +++ b/doc/sequenceprotocol.rst @@ -17,8 +17,7 @@ The special function names are: You just need to inform the function name to the add-function tag, without any parameter or return type information, when you do it, |project| will create a C function with parameters and return type definied by the table above. -The function needs to follow the same semantics of the *CPython equivalent* function, the only way to do it is using the inject-code tag. +The function needs to follow the same semantics of the *CPython equivalent* function, the only way to do it is using the :doc:`inject-code ` tag. A concrete exemple how to add sequence protocol support to a class can be found on shiboken tests, more precisely in the definition of the Str class in ``tests/samplebinding/typesystem_sample.xml``. - diff --git a/doc/typesystemvariables.rst b/doc/typesystemvariables.rst new file mode 100644 index 000000000..63177569d --- /dev/null +++ b/doc/typesystemvariables.rst @@ -0,0 +1,105 @@ +********************* +Type System Variables +********************* + +User written code can be placed in arbitrary places using the +:doc:`inject-code ` tag. To ease the binding developer +work, the injected code can make use of special variables that will be replaced +by the correct values. This also shields the developer from some |project| +implementation specifics. + + +Variables +========= + +**%0** + + Replaced by the name of the return variable of the Python method/function wrapper. + + +**%#** + + Replaced by the name of a C++ argument in the position indicated by ``#``. + The argument counting starts with ``%1``, since ``%0`` represents the return + variable name. + + +**%ARGUMENT_NAMES** + + Replaced by a comma separated list with the names of all arguments that were + not removed on the type system description for the method/function. + + +**%CONVERTTOPYTHON[CPPTYPE]** + + Replaced by a |project| conversion call that converts a C++ variable of the + type indicated by ``CPPTYPE`` to the proper Python object. + + +**%CPPSELF** + + Replaced by the wrapped C++ object instance that owns the method in which the + code with this variable was inserted. + + +**%FUNCTION_NAME** + + Replaced by the name of a function or method. + + +**%PYARG_#** + + Similar to ``%#``, but is replaced by the Python arguments (PyObjects) + received by the Python wrapper method. + + +**%PYSELF** + + Replaced by the Python wrapper variable (a PyObject) representing the instance + bounded to the Python wrapper method which receives the custom code. + + +**%RETURN_TYPE** + + Replaced by the type returned by a function or method. + + +**%TYPE** + + Replaced by the name of the class to which a function belongs. Should be used + in code injected to methods. + + +Example +======= + +Just to illustrate the usage of the variables described in the previous +sections, below is an excerpt from the type system description of a |project| +test. It changes a method that received ``argc/argv`` arguments into something +that expects a Python sequence instead. + + .. code-block:: xml + + + + + + + + + + int argc; + char** argv; + if (!PySequence_to_argc_argv(%PYARG_1, &argc, &argv)) { + PyErr_SetString(PyExc_TypeError, "error"); + return 0; + } + %RETURN_TYPE foo = %CPPSELF.%FUNCTION_NAME(argc, argv); + %0 = %CONVERTTOPYTHON[%RETURN_TYPE](foo); + + for (int i = 0; i < argc; ++i) + delete[] argv[i]; + delete[] argv; + + + -- cgit v1.2.3