.. _conversion-rule-tag:
Conversion Rule Tag
-------------------
.. _conversion-rule:
conversion-rule
^^^^^^^^^^^^^^^
The **conversion-rule** tag specifies how a **primitive-type**, a **container-type**,
or a **value-type** may be converted to and from the native C++ language types to the
target language types (see also :ref:`user-defined-type-conversion`).
It is a child of the :ref:`container-type`, :ref:`primitive-type` or
:ref:`value-type` and may contain :ref:`native-to-target` or
:ref:`native-to-target` child nodes.
.. code-block:: xml
// Code to convert a native value to a target language object.
// Code to convert target language type object of type TARGETTYPEA
// to the C++ native type represented by the value/primitive/container-type.
// Code to convert target language type object of type TARGETTYPEB
// to the C++ native type represented by the value/primitive/container-type.
The code can be inserted directly, via :ref:`add-conversion` (providing snippet
functionality) or via :ref:`insert-template` (XML template,
see :ref:`using-code-templates`).
The example above show the structure of a complete conversion rule. Each of the
child tags comprising the conversion rule are described in their own sections
below.
.. note::
You can also use the ``conversion-rule`` node to specify customized code
to convert a function argument between the target language and C++
(see :ref:`conversionrule-on-arguments`).
.. _native-to-target:
native-to-target
^^^^^^^^^^^^^^^^
The **native-to-target** tag tells how to convert a native C++ value to its
target language equivalent. It is a child of the :ref:`conversion-rule` node.
The text inside the tag is a C++ code the takes
an input value an does what's needed to convert it to the output value.
:ref:`insert-template` tags may be used to insert commonly repeating code.
.. code-block:: xml
// Code to convert a native value to a target language object.
Use the replace node to modify the template code.
Notice that the generator must provide type system variables for the input
and output values and types, namely **%in**, **%out**, **%INTYPE** and
**%OUTTYPE**. In the case of container types, **%INTYPE** refers to the
full container type (e.g. **"list"**) and **%INTYPE_0**, **%INTYPE_1**,
**%INTYPE_#**, should be replaced by the types used in the container template
(e.g. **%INTYPE_0** correspondes to **"int"** for **"list"**).
The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes).
.. _target-to-native:
target-to-native
^^^^^^^^^^^^^^^^
The **target-to-native** tag encloses at least one, but usually many, conversions
from target language values to C++ native values. It is a child of the
:ref:`conversion-rule` node and may have one or several :ref:`add-conversion`
child nodes. The *optional* attribute ``replace`` tells if the target
language to C++ conversions will be added to, or if they will replace the
implicit conversions collected by *ApiExtractor*. The default
value for it is *yes*.
.. code-block:: xml
// List of target to native conversions meant to replace or expand
// the already existing implicit conversions.
.. _add-conversion:
add-conversion
^^^^^^^^^^^^^^
Each **add-conversion** tag adds a rule for conversion of a target language type,
indicated by the ``type`` attribute, to the C++ native type represented by the
**primitive-type**, a **container-type**, or **value-type**, to which the parent
**conversion-rule** belongs.
It is a child of the :ref:`target-to-native` node.
.. code-block:: xml
// Code to convert target language type object of type TARGETTYPE_A
// to the C++ native type represented by the value/primitive/container-type.
The ``check`` attribute tells how a target value should be checked to see if it belongs to
the type expected. This attribute is *optional*, for it can be derived from the ``type``
attribute, but it isn't unusual that some special check is needed. The variables
**%in**, **%out**, **%INTYPE**, **%INTYPE_#**, and **%OUTTYPE**, must be provided by
the generator as in the ``native-to-target`` tag.
The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes).