1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
.. _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
<value-type>
<conversion-rule>
<native-to-target>
// Code to convert a native value to a target language object.
</native-to-target>
<target-to-native>
<add-conversion type='TARGETTYPEA' check='TARGETTYPEA_CHECK(%in)'>
// Code to convert target language type object of type TARGETTYPEA
// to the C++ native type represented by the value/primitive/container-type.
</add-conversion>
<add-conversion type='TARGETTYPEB' check='TARGETTYPEB_CHECK(%in)'>
// Code to convert target language type object of type TARGETTYPEB
// to the C++ native type represented by the value/primitive/container-type.
</add-conversion>
</target-to-native>
</conversion-rule>
</value-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
<conversion-rule>
<native-to-target>
// Code to convert a native value to a target language object.
</native-to-target>
</conversion-rule>
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<int>"**) 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<int>"**).
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
<conversion-rule>
<target-to-native replace='yes|no'>
// List of target to native conversions meant to replace or expand
// the already existing implicit conversions.
</target-to-native>
</conversion-rule>
.. _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
<target-to-native>
<add-conversion type='TARGETTYPE' check='TARGETTYPECHECK(%in)'>
// Code to convert target language type object of type TARGETTYPE_A
// to the C++ native type represented by the value/primitive/container-type.
</add-conversion>
<target-to-native>
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).
|
