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
|
.. _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
<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 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
<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. 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.
.. 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).
|
