diff options
author | Marcelo Lira <marcelo.lira@openbossa.org> | 2011-07-25 22:44:53 -0300 |
---|---|---|
committer | Hugo Parente Lima <hugo.pl@gmail.com> | 2012-03-09 19:10:19 -0300 |
commit | 35ab8b8e722b73a3a3ed9312379f6ab849252e19 (patch) | |
tree | 1411f293a32e125874b4b092bb96788b8f583d85 /doc | |
parent | e7fdca6465740132bd881ffd9d20e61be47472d0 (diff) |
Added improved functionality for the 'conversion-rule' tag.
It works for primitive, container and value types. Object types doesn't
have conversion rules because they can not have implicit conversions,
and the regular conversion is always the same (get C++ object held on
Python wrapper, and finding/creating a Python wrapper to a C++ pointer).
Unit tests were added.
Documentation was updated.
Reviewed by Luciano Wolf <luciano.wolf@openbossa.org>
Reviewed by Renato Araújo <renato.filho@openbossa.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/typesystem.rst | 1 | ||||
-rw-r--r-- | doc/typesystem_conversionrule.rst | 113 |
2 files changed, 114 insertions, 0 deletions
diff --git a/doc/typesystem.rst b/doc/typesystem.rst index 098a9d983..69dda43a0 100644 --- a/doc/typesystem.rst +++ b/doc/typesystem.rst @@ -23,6 +23,7 @@ can be found in the PySide/<QT_MODULE_NAME> directory of the PySide package. typesystem_arguments typesystem_solving_compilation typesystem_templates + typesystem_conversionrule typesystem_documentation diff --git a/doc/typesystem_conversionrule.rst b/doc/typesystem_conversionrule.rst new file mode 100644 index 000000000..c62d5bbf6 --- /dev/null +++ b/doc/typesystem_conversionrule.rst @@ -0,0 +1,113 @@ +.. _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>"**). + + +.. _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. + |