summaryrefslogtreecommitdiffstats
path: root/doc/typesystemvariables.rst
diff options
context:
space:
mode:
authorMarcelo Lira <marcelo.lira@openbossa.org>2009-11-16 17:12:45 -0300
committerMarcelo Lira <marcelo.lira@openbossa.org>2009-11-16 18:52:13 -0300
commit8297598336b3248fd1d8be778f62b641121b98a0 (patch)
tree39c48caea60cb2381b231f242babb1a7f4ce161e /doc/typesystemvariables.rst
parent127367b3ede6e3a59604cc93a3f2133d35b958ef (diff)
downloadshiboken-8297598336b3248fd1d8be778f62b641121b98a0.tar.gz
shiboken-8297598336b3248fd1d8be778f62b641121b98a0.tar.xz
shiboken-8297598336b3248fd1d8be778f62b641121b98a0.zip
Shiboken documentation updated with type system variables information
Reviewed by Hugo Lima <hugo.lima@openbossa.org>
Diffstat (limited to 'doc/typesystemvariables.rst')
-rw-r--r--doc/typesystemvariables.rst105
1 files changed, 105 insertions, 0 deletions
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, &amp;argc, &amp;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 &lt; argc; ++i)
+ delete[] argv[i];
+ delete[] argv;
+ </inject-code>
+ </modify-function>
+