.. _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.
.. 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 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.
.. _native-to-target:
native-to-target
^^^^^^^^^^^^^^^^
The **native-to-target** tag tells how to convert a native C++ value to its
target language equivalent. 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.
``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. 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.
.. 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).