diff options
Diffstat (limited to 'sources/shiboken6/doc/typesystem_conversionrule.rst')
| -rw-r--r-- | sources/shiboken6/doc/typesystem_conversionrule.rst | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/sources/shiboken6/doc/typesystem_conversionrule.rst b/sources/shiboken6/doc/typesystem_conversionrule.rst new file mode 100644 index 000000000..9a8f51c18 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_conversionrule.rst @@ -0,0 +1,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). + |