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="..." snake-case="yes | no | both" >
        </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`).

    The *optional* **snake-case** attribute specifies whether function
    and field names will be automatically changed to the snake case
    style that is common in Python (for example,  ``snakeCase`` will be
    changed to ``snake_case``).

    The value ``both`` means that the function or field will be exposed
    under both its original name and the snake case version. There are
    limitations to this though:

    - When overriding a virtual function of a C++ class in Python,
      the snake case name must be used.

    - When static and non-static overloads of a class member function
      exist (as is the case for example for ``QFileInfo::exists()``),
      the snake case name must be used.

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="..."
             snake-case="yes | no | both" />
        </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`).

    The *optional* **snake-case** attribute allows for overriding the value
    specified on the **typesystem** element.

.. _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="..."
             force-abstract="yes | no"
             hash-function="..."
             stream="yes | no"
             revision="..."
             snake-case="yes | no | both" />
        </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* **force-abstract** attribute forces the class to be
    abstract, disabling its instantiation. The generator will normally detect
    this automatically unless the class inherits from an abstract base class
    that is not in the type system.

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

    The *optional* **snake-case** attribute allows for overriding the value
    specified on the **typesystem** element.

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&lt;int&gt;"/>

    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="..." snake-case="yes | no | both" />
        </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.

    The *optional* **snake-case** attribute allows for overriding the value
    specified on the **typesystem** element.

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