diff options
| -rw-r--r-- | doc/_templates/index.html | 6 | ||||
| -rw-r--r-- | doc/contents.rst | 1 | ||||
| -rw-r--r-- | doc/sequenceprotocol.rst | 3 | ||||
| -rw-r--r-- | doc/typesystemvariables.rst | 105 |
4 files changed, 111 insertions, 4 deletions
diff --git a/doc/_templates/index.html b/doc/_templates/index.html index ef2e9a61..2accb5d2 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -11,12 +11,14 @@ <td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> <span class="linkdescr">for a complete overview</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("typesystemvariables") }}">Type System Variables</a><br/> + <span class="linkdescr">describes the type system variables that could be used in user custom code</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("codeinjectionsemantics") }}">Code Injection Semantics</a><br/> <span class="linkdescr">explains how custom code injection is interpreted by {{ project }}</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/> - <span class="linkdescr">support for python sequence protocol</span></p> </td> <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/> + <span class="linkdescr">support for python sequence protocol</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("compiling") }}">Compiling/Installing</a><br/> <span class="linkdescr">how to compile and install {{ project }}</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQ</a><br/> diff --git a/doc/contents.rst b/doc/contents.rst index 4e0a5e9e..f6735ee8 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 2ac48588..587c0f95 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 <codeinjectionsemantics>` 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 00000000..63177569 --- /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 <codeinjectionsemantics>` 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 + + <modify-function signature="overloadedMethod(int, char**)"> + <modify-argument index="1"> + <replace-type modified-type="PySequence" /> + </modify-argument> + <modify-argument index="2"> + <remove-argument /> + </modify-argument> + <inject-code class="target" position="beginning"> + 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; + </inject-code> + </modify-function> + |