diff options
Diffstat (limited to 'sources/shiboken6/doc/typesystem_specifying_types.rst')
| -rw-r--r-- | sources/shiboken6/doc/typesystem_specifying_types.rst | 509 |
1 files changed, 509 insertions, 0 deletions
diff --git a/sources/shiboken6/doc/typesystem_specifying_types.rst b/sources/shiboken6/doc/typesystem_specifying_types.rst new file mode 100644 index 000000000..405469ea2 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_specifying_types.rst @@ -0,0 +1,509 @@ +Specifying Types +---------------- + +.. _typesystem: + +Including Snippets +^^^^^^^^^^^^^^^^^^ + +There might be repetitive XML code, for example function modifications that +need to be done on classes that are not related by type inheritance. +It is possible to split out such snippets and include them via an entity reference. + +.. code-block:: xml + + <typesystem> + <object-type name="A"> + &common_function_modifications; + </object-type> + <object-type name="B"> + &common_function_modifications; + </object-type> + </typesystem> + +The entity name is interpreted as file name (with suffix **xml**) appended and resolved +in the type system paths passed as command line argument. + +Note that this is not a standard externally parsed entity due to the limitations +of the underlying parser. + +typesystem +^^^^^^^^^^ + + This is the root node containing all the type system information. It can + have a number of attributes, described below. + + .. code-block:: xml + + <typesystem package="..." default-superclass="..." allow-thread="..." exception-handling="..."> + </typesystem> + + The **package** attribute is a string describing the package to be used, + e.g. "QtCore". + The *optional* **default-superclass** attribute is the canonical C++ base class + name of all objects, e.g., "object". + + The *optional* attributes **allow-thread** and **exception-handling** + specify the default handling for the corresponding function modification + (see :ref:`modify-function`). + +load-typesystem +^^^^^^^^^^^^^^^ + + The load-typesystem node specifies which type systems to load when mapping + multiple libraries to another language or basing one library on another, and + it is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <load-typesystem name="..." generate="yes | no" /> + </typesystem> + + The **name** attribute is the filename of the typesystem to load, the + **generate** attribute specifies whether code should be generated or not. The + later must be specified when basing one library on another, making the generator + able to understand inheritance hierarchies, primitive mapping, parameter types + in functions, etc. + + Most libraries will be based on both the QtCore and QtGui modules, in which + case code generation for these libraries will be disabled. + + +rejection +^^^^^^^^^ + + The rejection node rejects the given class, or the specified function or + field, and it is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <rejection class="..." + function-name="..." + field-name="..." /> + </typesystem> + + The **class** attribute is the C++ class name of the class to reject. Use the + *optional* **function-name** or **field-name** attributes to reject a particular + function or field. Note that the **field-name** and **function-name** cannot + be specified at the same time. To remove all occurrences of a given field or + function, set the class attribute to \*. + +.. _primitive-type: + +primitive-type +^^^^^^^^^^^^^^ + + The primitive-type node describes how a primitive type is mapped from C++ to + the target language, and is a child of the typesystem node. Note that most + primitives are already specified in the QtCore typesystem. + + .. code-block:: xml + + <typesystem> + <primitive-type name="..." + since="..." + until="..." + target-name="..." + default-constructor="..." + preferred-conversion="yes | no" /> + view-on="..." + </typesystem> + + The **name** attribute is the name of the primitive in C++, the optional, + **target-name** attribute is the name of the primitive type in the target + language. If the later two attributes are not specified their default value + will be the same as the **name** attribute. + + The *optional* **since** value is used to specify the API version in which + the type was introduced. + + Similarly, the *optional* **until** value can be used to specify the API + version in which the type will be obsoleted. + + If the *optional* **preferred-conversion** attribute is set to *no*, it + indicates that this version of the primitive type is not the preferred C++ + equivalent of the target language type. For example, in Python both "qint64" + and "long long" become "long" but we should prefer the "qint64" version. For + this reason we mark "long long" with preferred-conversion="no". + + The *optional* **default-constructor** specifies the minimal constructor + call to build one value of the primitive-type. This is not needed when the + primitive-type may be built with a default constructor (the one without + arguments). + + The *optional* **preferred-conversion** attribute tells how to build a default + instance of the primitive type. It should be a constructor call capable of + creating a instance of the primitive type. Example: a class "Foo" could have + a **preferred-conversion** value set to "Foo()". Usually this attribute is + used only for classes declared as primitive types and not for primitive C++ + types, but that depends on the application using *ApiExtractor*. + + The *optional* **view-on** attribute specifies that the type is a view + class like std::string_view or QStringView which has a constructor + accepting another type like std::string or QString. Since typically + no values can be assigned to view classes, no target-to-native conversion + can be generated for them. Instead, an instance of the viewed class should + be instantiated and passed to functions using the view class + for argument types. + +.. _namespace: + +namespace-type +^^^^^^^^^^^^^^ + + The namespace-type node maps the given C++ namespace to the target language, + and it is a child of the typesystem node. Note that within namespaces, the + generator only supports enums (i.e., no functions or classes). + + .. code-block:: xml + + <typesystem> + <namespace-type name="..." + visible="true | auto | false" + generate="yes | no" + generate-using="yes | no" + package="..." + since="..." + revision="..." /> + </typesystem> + + The **name** attribute is the name of the namespace, e.g., "Qt". + + The *optional* **visible** attribute is used specify whether the + namespace is visible in the target language name. Its default value is + **auto**. It means that normal namespaces are visible, but inline namespaces + (as introduced in C++ 11) will not be visible. + + The detection of inline namespaces requires shiboken to be built + using LLVM 9.0. + + The *optional* **generate** is a legacy attribute. Specifying + **no** is equivalent to **visible="false"**. + + The *optional* **generate-using** attribute specifies whether + ``using namespace`` is generated into the wrapper code for classes within + the namespace (default: **yes**). This ensures for example that not fully + qualified enumeration values of default argument values compile. + However, in rare cases, it might cause ambiguities and can then be turned + off. + + The **package** attribute can be used to override the package of the type system. + + The *optional* **since** value is used to specify the API version of this type. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + +enum-type +^^^^^^^^^ + + The enum-type node maps the given enum from C++ to the target language, + and it is a child of the typesystem node. Use the reject-enum-value to + reject values. + + .. code-block:: xml + + <typesystem> + <enum-type name="..." + identified-by-value="..." + class="yes | no" + since="..." + flags="yes | no" + flags-revision="..." + lower-bound="..." + upper-bound="..." + force-integer="yes | no" + extensible="yes | no" + revision="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ name of the enum + (e.g.,"Qt::FillRule"). If the *optional* **flags** attribute is set to *yes* + (the default is *no*), the generator will expect an existing QFlags<T> for the + given enum type. The **lower-bound** and **upper-bound** attributes are used + to specify runtime bounds checking for the enum value. The value must be a + compilable target language statement, such as "QGradient.Spread.PadSpread" + (taking again Python as an example). If the **force-integer** attribute is + set to *yes* (the default is *no*), the generated target language code will + use the target language integers instead of enums. And finally, the + **extensible** attribute specifies whether the given enum can be extended + with user values (the default is *no*). + + The *optional* **since** value is used to specify the API version of this type. + + The attribute **identified-by-value** helps to specify anonymous enums using the + name of one of their values, which is unique for the anonymous enum scope. + Notice that the **enum-type** tag can either have **name** or **identified-by-value** + but not both. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The **flags-revision** attribute has the same purposes of **revision** attribute but + is used for the QFlag related to this enum. + + +reject-enum-value +^^^^^^^^^^^^^^^^^ + + The reject-enum-value node rejects the enum value specified by the **name** + attribute, and it is a child of the enum-type node. + + .. code-block:: xml + + <enum-type> + <reject-enum-value name="..."/> + </enum-type> + + This node is used when a C++ enum implementation has several identical numeric + values, some of which are typically obsolete. + +.. _value-type: + +value-type +^^^^^^^^^^ + + The value-type node indicates that the given C++ type is mapped onto the target + language as a value type. This means that it is an object passed by value on C++, + i.e. it is stored in the function call stack. It is a child of the :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <value-type name="..." since="..." + copyable="yes | no" + allow-thread="..." + disable-wrapper="yes | no" + exception-handling="..." + hash-function="..." + stream="yes | no" + default-constructor="..." + revision="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name, such as + "QMatrix" or "QPainterPath::Element". The **copyable** attribute is used to + force or not specify if this type is copyable. The *optional* **hash-function** + attribute informs the function name of a hash function for the type. + + The *optional* attribute **stream** specifies whether this type will be able to + use externally defined operators, like QDataStream << and >>. If equals to **yes**, + these operators will be called as normal methods within the current class. + + The *optional* **since** value is used to specify the API version of this type. + + The *optional* **default-constructor** specifies the minimal constructor + call to build one instance of the value-type. This is not needed when the + value-type may be built with a default constructor (the one without arguments). + Usually a code generator may guess a minimal constructor for a value-type based + on its constructor signatures, thus **default-constructor** is used only in + very odd cases. + + For the *optional* **disable-wrapper** attribute, see :ref:`object-type`. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The *optional* attributes **allow-thread** and **exception-handling** + specify the default handling for the corresponding function modification + (see :ref:`modify-function`). + +.. _object-type: + +object-type +^^^^^^^^^^^ + + The object-type node indicates that the given C++ type is mapped onto the target + language as an object type. This means that it is an object passed by pointer on + C++ and it is stored on the heap. It is a child of the :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <object-type name="..." + since="..." + copyable="yes | no" + allow-thread="..." + disable-wrapper="yes | no" + exception-handling="..." + hash-function="..." + stream="yes | no" + revision="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. If there is no + C++ base class, the default-superclass attribute can be used to specify a + superclass for the given type, in the generated target language API. The + **copyable** and **hash-function** attributes are the same as described for + :ref:`value-type`. + + The *optional* **disable-wrapper** attribute disables the generation of a + **C++ Wrapper** (see :ref:`codegenerationterminology`). This will + effectively disable overriding virtuals methods in Python for the class. + It can be used when the class cannot be instantiated from Python and + its virtual methods pose some problem for the code generator (by returning + references, or using a default value that cannot be generated for a + parameter, or similar). + + The *optional* attribute **stream** specifies whether this type will be able to + use externally defined operators, like QDataStream << and >>. If equals to **yes**, + these operators will be called as normal methods within the current class. + + The *optional* **since** value is used to specify the API version of this type. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The *optional* attributes **allow-thread** and **exception-handling** + specify the default handling for the corresponding function modification + (see :ref:`modify-function`). + +interface-type +^^^^^^^^^^^^^^ + + This type is deprecated and no longer has any effect. Use object-type instead. + +.. _container-type: + +container-type +^^^^^^^^^^^^^^ + + The container-type node indicates that the given class is a container and + must be handled using one of the conversion helpers provided by attribute **type**. + + .. code-block:: xml + + <typesystem> + <container-type name="..." + since="..." + type ="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. The **type** + attribute is used to indicate what conversion rule will be applied to the + container. It can be: *list*, *string-list*, *linked-list*, *vector*, *stack*, + *queue*, *set*, *map*, *multi-map*, *hash*, *multi-hash* or *pair*. + + The *optional* **since** value is used to specify the API version of this container. + +typedef-type +^^^^^^^^^^^^ + + The typedef-type allows for specifying typedefs in the typesystem. They + are mostly equivalent to spelling out the typedef in the included header, which + is often complicated when trying to wrap libraries whose source code cannot be + easily extended. + + .. code-block:: xml + + <typesystem> + <typedef-type name="..." + source="..." + since="..." /> + </typesystem> + + The **source** attribute is the source. Example: + + .. code-block:: xml + + <namespace-type name='std'> + <value-type name='optional' generate='no'/>\n" + </namespace-type> + <typedef-type name="IntOptional" source="std::optional<int>"/> + + is equivalent to + + .. code-block:: c++ + + typedef std::optional<int> IntOptional; + + The *optional* **since** value is used to specify the API version of this type. + +.. _custom-type: + +custom-type +^^^^^^^^^^^ + + The custom-type node simply makes the parser aware of the existence of a target + language type, thus avoiding errors when trying to find a type used in function + signatures and other places. The proper handling of the custom type is meant to + be done by a generator using the APIExractor. + + .. code-block:: xml + + <typesystem> + <custom-type name="..." /> + </typesystem> + + The **name** attribute is the name of the custom type, e.g., "PyObject". + +.. _smart-pointer-type: + +smart-pointer-type +^^^^^^^^^^^^^^^^^^ + + The smart pointer type node indicates that the given class is a smart pointer + and requires inserting calls to **getter** to access the pointeee. + Currently, only the **type** *shared* is supported and the usage is limited + to function return values. + **ref-count-method** specifies the name of the method used to do reference counting. + + The *optional* attribute **instantiations** specifies for which instantiations + of the smart pointer wrappers will be generated (comma-separated list). + By default, this will happen for all instantiations found by code parsing. + This might be a problem when linking different modules, since wrappers for the + same instantiation might be generated into different modules, which then clash. + Providing an instantiations list makes it possible to specify which wrappers + will be generated into specific modules. + + .. code-block:: xml + + <typesystem> + <smart-pointer-type name="..." + since="..." + type="..." + getter="..." + ref-count-method="..." + instantiations="..."/> + </typesystem> + +.. _function: + +function +^^^^^^^^ + + The function node indicates that the given C++ global function is mapped onto + the target language. + + .. code-block:: xml + + <typesystem> + <function signature="..." rename="..." since="..."/> + </typesystem> + + This tag has some limitations, it doesn't support function modifications, besides you + can't add a function overload using :ref:`add-function` tag to an existent function. + These limitation will be addressed in future versions of ApiExtractor. + + The function tag has two *optional* attributes: **since**, whose value is used to specify + the API version of this function, and **rename**, to modify the function name. + +.. _system_include: + +system-include +^^^^^^^^^^^^^^ + + The optional **system-include** specifies the name of a system include + file or a system include path (indicated by a trailing slash) to be + parsed. Normally, include files considered to be system include + files are skipped by the C++ code parser. Its primary use case + is exposing classes from the STL library. + + .. code-block:: xml + + <typesystem> + <system-include file-name="memory"/> + <system-include file-name="/usr/include/Qt/"/> + </typesystem> |