summaryrefslogtreecommitdiffstats
path: root/doc
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
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')
-rw-r--r--doc/_templates/index.html6
-rw-r--r--doc/contents.rst1
-rw-r--r--doc/sequenceprotocol.rst3
-rw-r--r--doc/typesystemvariables.rst105
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, &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>
+