<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>API Extractor — 3.4. Modifying Arguments</title>
<link rel="stylesheet" href="_static/pysidedocs.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '0.10.0',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<!--[if lt IE 7]>
<style media="screen" type="text/css">
#container {
height:100%;
}
</style>
<![endif]-->
<link rel="top" title="API Extractor v0.10.0 documentation" href="index.html" />
<link rel="up" title="3. The API Extractor Type System" href="typesystem.html" />
<link rel="next" title="3.5. Solving compilation problems" href="typesystem_solving_compilation.html" />
<link rel="prev" title="3.3. Modifying Functions" href="typesystem_modify_function.html" />
</head>
<body id="typesystem_arguments">
<div id="container">
<div id="header">
<div id="header_container">
<div id="logo"><a href="http://www.pyside.org"><img alt="PySide" src="_static/pysidelogo.png" width="199" height="102" /></a></div>
<ul id="relbar">
<li class="right">
<a href="typesystem_solving_compilation.html" title="3.5. Solving compilation problems"
accesskey="N">next</a></li>
<li class="right">
<a href="typesystem_modify_function.html" title="3.3. Modifying Functions"
accesskey="P">previous</a> |</li>
<li><a href="contents.html">API Extractor v0.10.0 documentation</a> »</li>
<li><a href="typesystem.html" accesskey="U">3. The API Extractor Type System</a> »</li>
</ul>
</div>
</div>
<div id="body" >
<div id="sidebar">
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">3.4. Modifying Arguments</a><ul>
<li><a class="reference internal" href="#conversion-rule">3.4.1. conversion-rule</a></li>
<li><a class="reference internal" href="#remove-argument">3.4.2. remove-argument</a></li>
<li><a class="reference internal" href="#rename-to">3.4.3. rename to</a></li>
<li><a class="reference internal" href="#remove-default-expression">3.4.4. remove-default-expression</a></li>
<li><a class="reference internal" href="#replace-default-expression">3.4.5. replace-default-expression</a></li>
<li><a class="reference internal" href="#replace-type">3.4.6. replace-type</a></li>
<li><a class="reference internal" href="#define-ownership">3.4.7. define-ownership</a></li>
<li><a class="reference internal" href="#reference-count">3.4.8. reference-count</a></li>
<li><a class="reference internal" href="#replace-value">3.4.9. replace-value</a></li>
<li><a class="reference internal" href="#parent">3.4.10. parent</a></li>
</ul>
</li>
</ul>
<h3>Previous topic</h3>
<p class="topless"><a href="typesystem_modify_function.html"
title="previous chapter">3.3. Modifying Functions</a></p>
<h3>Next topic</h3>
<p class="topless"><a href="typesystem_solving_compilation.html"
title="next chapter">3.5. Solving compilation problems</a></p>
<div id="search_box">
<h3>Quick search</h3>
<form action="search.html" method="get">
<input type="text" name="q" id="q" />
<input type="submit" value="Go" id="search_button" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="section" id="modifying-arguments">
<span id="id1"></span><h1>3.4. Modifying Arguments</h1>
<div class="section" id="conversion-rule">
<span id="id2"></span><h2>3.4.1. conversion-rule</h2>
<blockquote>
<div><p>The conversion-rule node allows you to write customized code to convert
the given argument between the target language and C++, and it is a child of the modify-argument node.</p>
<div class="highlight-xml"><pre><modify-argument ...>
<conversion-rule class="target | native">
// the code
</conversion-rule>
</modify-argument></pre>
</div>
<p>This node is typically used in combination with the replace-type and
remove-argument nodes. The given code is used instead of the generator’s
conversion code.</p>
<p>Writing %N in the code (where N is a number), will insert the name of the
nth argument. Alternatively, %in and %out which will be replaced with the
name of the conversion’s input and output variable, respectively. Note the
output variable must be declared explicitly, for example:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><conversion-rule</span> <span class="na">class=</span><span class="s">"native"</span><span class="nt">></span>
bool %out = (bool) %in;
<span class="nt"></conversion-rule></span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can also use the conversion-rule node to specify <a class="reference internal" href="typesystem_manipulating_objects.html#conversion-rule-on-types"><em>a conversion code which will be used instead of the generator’s conversion code everywhere for a given type</em></a>.</p>
</div>
</div></blockquote>
</div>
<div class="section" id="remove-argument">
<h2>3.4.2. remove-argument</h2>
<blockquote>
<div><p>The remove-argument node removes the given argument from the function’s
signature, and it is a child of the modify-argument node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument></span>
<span class="nt"><remove-argument</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="rename-to">
<h2>3.4.3. rename to</h2>
<blockquote>
<div><p>The ‘rename to’ node is used to rename a argument and use this new name in the generated code.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument></span>
<span class="nt"><rename</span> <span class="na">to=</span><span class="s">'...'</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="remove-default-expression">
<h2>3.4.4. remove-default-expression</h2>
<blockquote>
<div><p>The remove-default-expression node disables the use of the default expression
for the given argument, and it is a child of the modify-argument node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument...></span>
<span class="nt"><remove-default-expression</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="replace-default-expression">
<h2>3.4.5. replace-default-expression</h2>
<blockquote>
<div><p>The replace-default-expression node replaces the specified argument with the
expression specified by the <tt class="docutils literal"><span class="pre">with</span></tt> attribute, and it is a child of the
modify-argument node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument></span>
<span class="nt"><replace-default-expression</span> <span class="na">with=</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="replace-type">
<h2>3.4.6. replace-type</h2>
<blockquote>
<div><p>The replace-type node replaces the type of the given argument to the one
specified by the <tt class="docutils literal"><span class="pre">modified-type</span></tt> attribute, and it is a child of the
modify-argument node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument></span>
<span class="nt"><replace-type</span> <span class="na">modified-type=</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
<p>If the new type is a class, the <tt class="docutils literal"><span class="pre">modified-type</span></tt> attribute must be set to
the fully qualified name (including name of the package as well as the class
name).</p>
</div></blockquote>
</div>
<div class="section" id="define-ownership">
<h2>3.4.7. define-ownership</h2>
<blockquote>
<div><p>The define-ownership tag indicates that the function changes the ownership
rules of the argument object. The <tt class="docutils literal"><span class="pre">class</span></tt> attribute specifies the class of
function where to inject the ownership altering code. The <tt class="docutils literal"><span class="pre">owner</span></tt> attribute
specifies the new ownership of the object. It accepts the following values:</p>
<blockquote>
<div><ul>
<li><dl class="first docutils">
<dt>target: the target language will assume full ownership of the object.</dt>
<dd><p class="first last">The native resources will be deleted when the target language
object is finalized.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>c++: The native code assumes full ownership of the object. The target</dt>
<dd><p class="first last">language object will not be garbage collected.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>default: The object will get default ownership, depending on how it</dt>
<dd><p class="first last">was created.</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument></span>
<span class="nt"><define-ownership</span> <span class="na">class=</span><span class="s">"target | native"</span>
<span class="na">owner=</span><span class="s">"target | c++ | default"</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="reference-count">
<h2>3.4.8. reference-count</h2>
<blockquote>
<div><p>The reference-count tag dictates how an argument should be handled by the
target language reference counting system (if there is any), it also indicates
the kind of relationship the class owning the function being modified has with
the argument. For instance, in a model/view relation a view receiving a model
as argument for a <strong>setModel</strong> method should increment the model’s reference
counting, since the model should be kept alive as much as the view lives.
Remember that out hypothetical view could not become parent of the model,
since the said model could be used by other views as well.
The <tt class="docutils literal"><span class="pre">action</span></tt> attribute specifies what should be done to the argument
reference counting when the modified method is called. It accepts the
following values:</p>
<blockquote>
<div><ul>
<li><p class="first">add: increments the argument reference counter.</p>
</li>
<li><p class="first">add-all: increments the reference counter for each item in a collection.</p>
</li>
<li><p class="first">remove: decrements the argument reference counter.</p>
</li>
<li><p class="first">set: will assign the argument to the variable containing the reference.</p>
</li>
<li><dl class="first docutils">
<dt>ignore: does nothing with the argument reference counter</dt>
<dd><dl class="first last docutils">
<dt>(sounds worthless, but could be used in situations</dt>
<dd><p class="first last">where the reference counter increase is mandatory
by default).</p>
</dd>
</dl>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument></span>
<span class="nt"><reference-count</span> <span class="na">action=</span><span class="s">"add|add-all|remove|set|ignore"</span> <span class="na">variable-name=</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
<p>The variable-name attribute specifies the name used for the variable that
holds the reference(s).</p>
</div></blockquote>
</div>
<div class="section" id="replace-value">
<h2>3.4.9. replace-value</h2>
<blockquote>
<div><p>The <tt class="docutils literal"><span class="pre">replace-value</span></tt> attribute lets you replace the return statement of a
function with a fixed string. This attribute can only be used for the
argument at <tt class="docutils literal"><span class="pre">index</span></tt> 0, which is always the function’s return value.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument</span> <span class="na">index=</span><span class="s">"0"</span> <span class="na">replace-value=</span><span class="s">"this"</span><span class="nt">/></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="parent">
<h2>3.4.10. parent</h2>
<blockquote>
<div><p>The parent node lets you define the argument parent which will
take ownership of argument and will destroy the C++ child object when the
parent is destroyed.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument</span> <span class="na">index=</span><span class="s">"1"</span><span class="nt">></span>
<span class="nt"><parent</span> <span class="na">index=</span><span class="s">"this"</span> <span class="na">action=</span><span class="s">"add | remove"</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
<p>In the <tt class="docutils literal"><span class="pre">index</span></tt> argument you must specify the parent argument. The action
<em>add</em> creates a parent link between objects, while <em>remove</em> will undo the
parentage relationship.</p>
</div></blockquote>
</div>
</div>
</div> <!-- container -->
<div id="footer">
<a href="http://www.indt.org.br"><img src="_static/logo_indt.jpg" alt="Indt" border="0" /></a>
<a href="http://www.openbossa.org"><img src="_static/logo_openbossa.png" alt="Openbossa" border="0" /></a>
<a href="http://qt.nokia.com/"><img src="_static/logo_qt.png" alt="Qt" border="0" /></a>
<a href="http://www.python.org"><img src="_static/logo_python.jpg" alt="Python" border="0" /></a>
</div>
</div>
</body>
</html>
