diff options
Diffstat (limited to 'doc/typesystem.rst')
| -rw-r--r-- | doc/typesystem.rst | 810 |
1 files changed, 810 insertions, 0 deletions
diff --git a/doc/typesystem.rst b/doc/typesystem.rst new file mode 100644 index 000000000..19c46aeb1 --- /dev/null +++ b/doc/typesystem.rst @@ -0,0 +1,810 @@ +The API Extractor Type System +***************************** + +The typesystem is used by a binding generator to map a C++ library API onto +a higher level language. + +The typesystem specification is a handwritten XML document listing the types +that will be available in the generated target language API; types that are not +declared in the specification will be ignored along with everything depending on +them. In addition, it is possible to manipulate and modify types and functions. +It is even possible to use the typesystem specification to inject arbitrary +code into the source files, such as an extra member function. + +The typesystem specification is passed as an argument to the generator. + +Below there is a complete reference guide to the various nodes of the typesystem. +For usage examples, take a look at the typesystem files used to generate the Qt +Python bindings. These files can be found in the data directory of the PySide +package. + +.. _specifying-types: + +Specifying Types +---------------- + +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="..."> + </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". + +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 \*. You can use an empty class field + to denote a global function. + + +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="..." + target-name="..." + preferred-conversion="yes | no" /> + </typesystem> + + The **name** attribute is the name of the primitive in C++, the optimal + **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. + + 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". + +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="..." + package="..." /> + </typesystem> + + The **name** attribute is the name of the namespace, e.g., "Qt". The **package** + attribute can be used to override the package of the type system. + +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="..." + flags="yes | no" + lower-bound="..." + upper-bound="..." + force-integer="yes | no" + extensible="yes | no" /> + </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*). + + +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 typesystem node. + + .. code-block:: xml + + <typesystem> + <value-type name="..." + copyable="yes | no" + hash-function="..." /> + </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. + + +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 typesystem node. + + .. code-block:: xml + + <typesystem> + <object-type name="..." + copyable="yes | no" + hash-function="..." /> + </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`. + + +interface-type +^^^^^^^^^^^^^^ + + The interface-type node indicates that the given class is replaced by an + interface pattern when mapping from C++ to the target language. Using the + interface-type node implicitly makes the given type an object type. + + .. code-block:: xml + + <typesystem> + <interface-type name="..." + package ="..." + default-superclass ="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. The *optional* + **package** attribute can be used to override the package of the type system. + If there is no C++ base class, the *optional* **default-superclass** attribute + can be used to specify a superclass in the generated target language API, for + the given class. + +suppress-warning +^^^^^^^^^^^^^^^^ + + The generator will generate several warnings which may be irrelevant to the + user. The suppress-warning node suppresses the specified warning, and it is + a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <suppress-warning text="..." /> + </typesystem> + + The **text* attribute is the warning text to suppress, and may contain the * + wildcard (use "" to escape regular expression matching if the warning contain + a regular "*"). + + +template +^^^^^^^^ + + The template node registers a template that can be used to avoid duplicate + code when extending the generated code, and it is a child of the typesystem + node. + + .. code-block:: xml + + <typesystem> + <template name="my_template"> + // the code + </template> + </typesystem> + + Use the insert-template node to insert the template code (identified by the + template's **name** attribute) into the generated code base. + + + +.. _value-type-requirements: + +Value Type Requirements +------------------------ + +custom-constructor +^^^^^^^^^^^^^^^^^^ + + In some target languages, such as Python, value types are required to have a + copy constructor. If a C++ class without a copy constructor is mapped onto + the target language as a value type, it is possible to provide a custom + constructor using the custom-constructor node which is a child of the + value-type node. + + .. code-block:: xml + + <value-type> + <custom-constructor + name="..." + param-name="..."> + // code for custom constructor + </custom-constructor> + </value-type> + + The custom constructor's signature becomes: + + T \*name(T \*param-name); + + If not specified the **name** of the constructor becomes + <lowercase type name>_create() and the **param-name** becomes copy. + + **name** and **param-name** attributes are *optional*. + +custom-destructor +^^^^^^^^^^^^^^^^^ + + When a custom constructor is provided using the custom-constructor node, it is + most likely required to clean up the allocated memory. For that reason, it is + also possible to provide a custom destructor using the custom-destructor node + which is a child of the value-type node. + + .. code-block:: xml + + <value-type> + <custom-destructor + name="..." + param-name="..."> + // code for custom destructor + </custom-destructor> + </value-type> + + The custom destructor must have the following signature: + + T \*name(T \*param-name); + + If not specified the **name** of the destructor becomes + <lowercase type name>_delete() and the **param-name** becomes copy. + + **name** and **param-name** attributes are *optional*. + +insert-template +^^^^^^^^^^^^^^^ + + Documented in the :ref:`using-code-templates` + + + +.. _manipulating-object-and-value-types: + +Manipulating Object and Value Types +----------------------------------- + +inject-code +^^^^^^^^^^^ + The inject-code node inserts the given code into the generated code for the + given type or function, and it is a child of the object-type, value-type and + modify-function nodes. + + .. code-block:: xml + + <value-type> + <inject-code class="native | target | target-declaration" + position="beginning | end"> + // the code + </inject-code> + </value-type> + + The **class** attribute specifies which module of the generated code that + will be affected by the code injection. The **class** attribute accepts the + following values: + + * native: The c++ code + * target: The binding code + * target-declaration: The code will be injected into the generated header + file containing the c++ wrapper class definition. + + If the **position** attribute is set to *beginning* (the default), the code + is inserted at the beginning of the function. If it is set to *end*, the code + is inserted at the end of the function. + +modify-field +^^^^^^^^^^^^ + + The modify-field node allows you to alter the access privileges for a given + C++ field when mapping it onto the target language, and it is a child of an + object-type or a value-type node. + + .. code-block:: xml + + <object-type> + <modify-field name="..." + write="true | false" + read="true | false" /> + </object-type> + + The **name** attribute is the name of the field, the *optional* **write** + and **read** attributes specify the field's access privileges in the target + language API (both are set to true by default). + +modify-function +^^^^^^^^^^^^^^^ + + The modify-function node allows you to modify a given C++ function when mapping + it onto the target language, and it is a child of an object-type or a value-type + node. Use the modify-argument node to specify which argument the modification + affects. + + .. code-block:: xml + + <object-type> + <modify-function signature="..." + remove="all | c++" + access="public | private | protected" + rename="..." > + </object-type> + + The **signature** attribute is a normalized C++ signature, excluding return + values but including potential const declarations. + + The **remove**, **access** and **rename** attributes are *optional* attributes + for added convenience; they serve the same purpose as the tags remove, access + and rename. + + +include +^^^^^^^ + + Documented in the :ref:`manipulating-namespace-and-interface-types` + + +extra-includes +^^^^^^^^^^^^^^ + + Documented in the :ref:`manipulating-namespace-and-interface-types` + + +insert-template +^^^^^^^^^^^^^^^ + + Documented in the :ref:`using-code-templates` + + +.. _manipulating-namespace-and-interface-types: + +Manipulating Namespace and Interface Types +------------------------------------------ + +extra-includes +^^^^^^^^^^^^^^ + + The extra-includes node contains declarations of additional include files, + and it can be a child of the interface-type, namespace-type, value-type and + object-type nodes. + + The generator automatically tries to read the global header for each type but + sometimes it is required to include extra files in the generated C++ code to + make sure that the code compiles. These files must be listed using include + nodes witin the extra-include node: + + .. code-block:: xml + + <value-type> + <extra-includes> + <include file-name="..." location="global | local"/> + </extra-includes> + </value-type> + + The **file-name** attribute is the file to include, such as "QStringList". + The **location** attribute is where the file is located: *global* means that + the file is located in $INCLUDEPATH and will be included using #include <...>, + *local* means that the file is in a local directory and will be included + using #include "...". + + +include +^^^^^^^ + + The include node specifies the name and location of a file that must be + included, and it is a child of the interface-type, namespace-type, value-type, + object-type or extra-includes nodes + + The generator automatically tries to read the global header for each type. Use + the include node to override this behavior, providing an alternative file. The + include node can also be used to specify extra include files. + + .. code-block:: xml + + <value-type> + <include file-name="..." + location="global | local"/> + </value-type> + The **file-name** attribute is the file to include, such as "QStringList". + The **location** attribute is where the file is located: *global* means that + the file is located in $INCLUDEPATH and will be included using #include <...>, + *local* means that the file is in a local directory and will be included + using #include "...". + + +.. _manipulating-enum-types: + +Manipulating Enum Types +----------------------- + +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. + + **WARNING:** If the enum has some duplicated value don't forget to remove one + of them. + + +.. _modifying-functions: + +Modifying Functions +------------------- + +modify-argument +^^^^^^^^^^^^^^^ + + The modify-argument node specifies which of the given function's arguments the + modification affects, and is a child of the modify-function node. Use the + remove-argument, replace-default-expression, remove-default-expression, + replace-type, reference-count and define-ownership nodes to specify the details + of the modification. + + .. code-block:: xml + + <modify-function> + <modify-argument index="return | this | 1 ..." > + // modifications + </modify-argument> + </modify-function> + + Set the **index** attribute to "1" for the first argument, "2" for the second + one and so on. Alternatively, set it to "return" or "this" if you want to + modify the function's return value or the object the function is called upon, + respectively. + + +remove +^^^^^^ + + The remove node removes the given method from the generated target language + API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <remove class="all" /> + </modify-function> + + +access +^^^^^^ + + The access node changes the access privileges of the given function in the + generated target language API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <access modifier="public | protected | private"/> + </modify-function> + + +rename +^^^^^^ + + The rename node changes the name of the given function in the generated target + language API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <rename to="..." /> + </modify-function> + + The **to** attribute is the new name of the function. + + +inject-code +^^^^^^^^^^^ + + Documented in the :ref:`manipulating-object-and-value-types` + + +argument-map +^^^^^^^^^^^^ + + The argument-map node maps a C++ argument name to the argument name used in + the generated target language API, and is a child of the inject-code node + when the later is a child of a modify-function node. + + .. code-block:: xml + + <modify-function> + <inject-code> + <argument-map index="numeric value" + meta-name="string value"> + </inject-code> + </modify-function> + + The **index** attribute is an index, starting at 1, indicating the argument + position to which this argument mapping applies. The **meta-name** attribute + is the name used within the code injection to adress the argument at the + given position. + + +.. _modifying-arguments: + +Modifying Arguments +------------------- + +remove-argument +^^^^^^^^^^^^^^^ + + The remove-argument node removes the given argument from the function's + signature, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument> + <remove-argument /> + </modify-argument> + + Typically, when removing an argument, some conversion rules must be specified, + e.g., when converting from the target language to C++. This can be done using + the :ref:`conversion-rule` node. + + +remove-default-expression +^^^^^^^^^^^^^^^^^^^^^^^^^ + + The remove-default-expression node disables the use of the default expression + for the given argument, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument...> + <remove-default-expression /> + </modify-argument> + +replace-default-expression +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The replace-default-expression node replaces the specified argument with the + expression specified by the **with** attribute, and it is a child of the + modify-argument node. + + .. code-block:: xml + + <modify-argument> + <replace-default-expression with="..." /> + </modify-argument> + + +replace-type +^^^^^^^^^^^^ + + The replace-type node replaces the type of the given argument to the one + specified by the **modified-type** attribute, and it is a child of the + modify-argument node. + + .. code-block:: xml + + <modify-argument> + <replace-type modified-type="..." /> + </modify-argument> + + If the new type is a class, the **modified-type** attribute must be set to + the fully qualified name (including name of the package as well as the class + name). + + Typically when changing the type of an argument some conversion rules must be + specified. This can be done using the :ref:`conversion-rule` node. + + +define-ownership +^^^^^^^^^^^^^^^^ + + The define-ownership tag indicates that the function changes the ownership + rules of the argument object. The **class** attribute specifies the class of + function where to inject the ownership altering code. The **owner** attribute + specifies the new ownership of the object. It accepts the following values: + + * target: the target language will assume full ownership of the object. + The native resources will be deleted when the target language + object is finalized. + * c++: The native code assumes full ownership of the object. The target + language object will not be garbage collected. + * default: The object will get default ownership, depending on how it + was created. + + .. code-block:: xml + + <modify-argument> + <define-ownership class="target | shell" + owner="target | c++ | default" /> + </modify-argument> + + +insert-template +^^^^^^^^^^^^^^^ + + Documented in the :ref:`using-code-templates` + + +replace-value +^^^^^^^^^^^^^ + + The **replace-value** attribute lets you replace the return statement of a + function with a fixed string. This attribute can only be used for the + argument at **index** 0, which is always the function's return value. + + .. code-block:: xml + + <modify-argument index="0" replace-value="this"/> + + +parent +^^^^^^ + + The **parent** attribute lets you define argument parent which will + take ownership of argument and will destroy the C++ child object when the + parent is destroyed. + + .. code-block:: xml + + <modify-argument> + <parent index="this" action="add | remove" /> + </modify-argument> + + In the **index** argument you must specify the parent argument. The action + *add* creates a parent link between objects, while *remove* will undo the + parentage relationship. + + +.. _using-code-templates: + +Using Code Templates +-------------------- + +insert-template +^^^^^^^^^^^^^^^ + + The insert-template node includes the code template identified by the name + attribute, and it can be a child of the inject-code, conversion-rule, template, + custom-constructor and custom-destructor nodes. + + .. code-block:: xml + + <inject-code class="target" position="beginning"> + <insert-template name="my_template" /> + </inject-code> + + Use the replace node to modify the template code. + + +replace +^^^^^^^ + + The replace node allows you to modify template code before inserting it into + the generated code, and it can be a child of the insert-template node. + + .. code-block:: xml + + <insert-template name="my_template"> + <replace from="..." to="..." /> + </insert-template> + + This node will replace the attribute **from** with the value pointed by + **to**. + + +Manipulating Documentation +-------------------------- + +inject-documentation +^^^^^^^^^^^^^^^^^^^^ + + The inject-documentation node inserts the documentation into the generated + documentation. This node is a child of the object-type, value-type and + modify-function nodes. + + .. code-block:: xml + + <value-type> + <inject-documentation mode="append | prepend | replace" format="native | target" > + // the documentation + </inject-code> + </value-type> + + The **mode** attribute default value is *replace*. + + The **format** attribute specifies when the documentation injection will + occur and it accepts the following values: + + * native: Before XML<->Backend transformation occur, so the injected code *must* be a valid XML. + * target: Before XML<->Backend transformation occur, so the injected code *must* be a valid backend format. + + At the moment the only supported backend is Sphinx. + +modify-documentation +^^^^^^^^^^^^^^^^^^^^ + + The modify-documentation node allows you to change the auto-generated + documentation. API Extractor transforms XML's from qdoc3 (the Qt documentation + tool) into .rst files to be processed later using Sphinx. So you can modify + the XML before the transformation occur. + + .. code-block:: xml + + <modify-documentation xpath="..."> + <!-- new documentation --> + </modify-documentation> + + The **xpath** attribute is the XPath to the node that you want to modify. |