shiboken6: Add element <declare-function>

Make it possible to simply declare functions that the code
parser cannot see.

Task-number: PYSIDE-904
Task-number: PYSIDE-1339
Change-Id: If50bc0f1fc77a63e753b6fa440e6f08dd312ce4c
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

7 files changed, 62 insertions, 11 deletions

diff --git a/sources/shiboken6/ApiExtractor/abstractmetalang.cpp b/sources/shiboken6/ApiExtractor/abstractmetalang.cpp
index d88775356..30f879c5e 100644
--- a/sources/shiboken6/ApiExtractor/abstractmetalang.cpp
+++ b/sources/shiboken6/ApiExtractor/abstractmetalang.cpp
@@ -353,6 +353,11 @@ QString AbstractMetaFunction::signature() const
     return m_cachedSignature;
 }
 
+bool AbstractMetaFunction::isUserAdded() const
+{
+    return !m_addedFunction.isNull() && !m_addedFunction->isDeclaration();
+}
+
 int AbstractMetaFunction::actualMinimumArgumentCount() const
 {
     AbstractMetaArgumentList arguments = this->arguments();
diff --git a/sources/shiboken6/ApiExtractor/abstractmetalang.h b/sources/shiboken6/ApiExtractor/abstractmetalang.h
index 9c52182ef..1fd2eb3ff 100644
--- a/sources/shiboken6/ApiExtractor/abstractmetalang.h
+++ b/sources/shiboken6/ApiExtractor/abstractmetalang.h
@@ -599,7 +599,7 @@ public:
     }
 
     /// Returns true if the AbstractMetaFunction was added by the user via the type system description.
-    bool isUserAdded() const { return !m_addedFunction.isNull(); }
+    bool isUserAdded() const;
 
     QString toString() const
     {
diff --git a/sources/shiboken6/ApiExtractor/typesystem.cpp b/sources/shiboken6/ApiExtractor/typesystem.cpp
index 0c84cc980..92f2b38ae 100644
--- a/sources/shiboken6/ApiExtractor/typesystem.cpp
+++ b/sources/shiboken6/ApiExtractor/typesystem.cpp
@@ -632,6 +632,8 @@ QDebug operator<<(QDebug d, const AddedFunction &af)
     d << af.returnType() << ' ' << af.name() << '(' << af.arguments() << ')';
     if (af.isConstant())
         d << " const";
+    if (af.isDeclaration())
+        d << " [declaration]";
     return d;
 }
 #endif // !QT_NO_DEBUG_STREAM
diff --git a/sources/shiboken6/ApiExtractor/typesystem.h b/sources/shiboken6/ApiExtractor/typesystem.h
index 2bbaabc91..4f9da99ef 100644
--- a/sources/shiboken6/ApiExtractor/typesystem.h
+++ b/sources/shiboken6/ApiExtractor/typesystem.h
@@ -491,6 +491,9 @@ struct AddedFunction
         return m_isStatic;
     }
 
+    bool isDeclaration() const { return m_isDeclaration; } // <declare-function>
+    void setDeclaration(bool value) { m_isDeclaration = value; }
+
     FunctionModificationList modifications;
 
 private:
@@ -500,6 +503,7 @@ private:
     Access m_access = Protected;
     bool m_isConst = false;
     bool m_isStatic = false;
+    bool m_isDeclaration = false;
 };
 
 #ifndef QT_NO_DEBUG_STREAM
diff --git a/sources/shiboken6/ApiExtractor/typesystemparser.cpp b/sources/shiboken6/ApiExtractor/typesystemparser.cpp
index 7b018cd4e..c52a2e843 100644
--- a/sources/shiboken6/ApiExtractor/typesystemparser.cpp
+++ b/sources/shiboken6/ApiExtractor/typesystemparser.cpp
@@ -348,6 +348,7 @@ ENUM_LOOKUP_BEGIN(StackElement::ElementType, Qt::CaseInsensitive,
         {u"custom-constructor", StackElement::CustomMetaConstructor},
         {u"custom-destructor", StackElement::CustomMetaDestructor},
         {u"custom-type", StackElement::CustomTypeEntry},
+        {u"declare-function", StackElement::DeclareFunction},
         {u"define-ownership", StackElement::DefineOwnership},
         {u"enum-type", StackElement::EnumTypeEntry},
         {u"extra-includes", StackElement::ExtraIncludes},
@@ -2219,11 +2220,12 @@ static bool parseOverloadNumber(const QXmlStreamAttribute &attribute, int *overl
 }
 
 bool TypeSystemParser::parseAddFunction(const QXmlStreamReader &,
-                               const StackElement &topElement,
-                               QXmlStreamAttributes *attributes)
+                                        const StackElement &topElement,
+                                        StackElement::ElementType t,
+                                        QXmlStreamAttributes *attributes)
 {
     if (!(topElement.type & (StackElement::ComplexTypeEntryMask | StackElement::Root))) {
-        m_error = QString::fromLatin1("Add function requires a complex type or a root tag as parent"
+        m_error = QString::fromLatin1("Add/Declare function requires a complex/container type or a root tag as parent"
                                       ", was=%1").arg(topElement.type, 0, 16);
         return false;
     }
@@ -2275,6 +2277,7 @@ bool TypeSystemParser::parseAddFunction(const QXmlStreamReader &,
         }
         func->setAccess(a);
     }
+    func->setDeclaration(t == StackElement::DeclareFunction);
 
     m_contextStack.top()->addedFunctions << func;
     m_contextStack.top()->addedFunctionModificationIndex =
@@ -3087,8 +3090,9 @@ bool TypeSystemParser::startElement(const QXmlStreamReader &reader)
             if (!parseModifyField(reader, &attributes))
                 return false;
             break;
+        case StackElement::DeclareFunction:
         case StackElement::AddFunction:
-            if (!parseAddFunction(reader, topElement, &attributes))
+            if (!parseAddFunction(reader, topElement, element->type, &attributes))
                 return false;
             break;
         case StackElement::Property:
diff --git a/sources/shiboken6/ApiExtractor/typesystemparser.h b/sources/shiboken6/ApiExtractor/typesystemparser.h
index 130d8d3d2..681ed7ae6 100644
--- a/sources/shiboken6/ApiExtractor/typesystemparser.h
+++ b/sources/shiboken6/ApiExtractor/typesystemparser.h
@@ -84,11 +84,12 @@ class StackElement
             TemplateInstanceEnum        = 0x0e00,
             Replace                     = 0x0f00,
             AddFunction                 = 0x1000,
-            NativeToTarget              = 0x1100,
-            TargetToNative              = 0x1200,
-            AddConversion               = 0x1300,
-            SystemInclude               = 0x1400,
-            Property                    = 0x1500,
+            DeclareFunction             = 0x1100,
+            NativeToTarget              = 0x1200,
+            TargetToNative              = 0x1300,
+            AddConversion               = 0x1400,
+            SystemInclude               = 0x1500,
+            Property                    = 0x1600,
             SimpleMask                  = 0x3f00,
 
             // Code snip tags (0x1000, 0x2000, ... , 0xf000)
@@ -232,7 +233,7 @@ private:
                      const StackElement &topElement, QXmlStreamAttributes *);
     bool parseModifyField(const QXmlStreamReader &, QXmlStreamAttributes *);
     bool parseAddFunction(const QXmlStreamReader &, const StackElement &topElement,
-                          QXmlStreamAttributes *);
+                          StackElement::ElementType t, QXmlStreamAttributes *);
     bool parseProperty(const QXmlStreamReader &, const StackElement &topElement,
                        QXmlStreamAttributes *);
     bool parseModifyFunction(const QXmlStreamReader &, const StackElement &topElement,
diff --git a/sources/shiboken6/doc/typesystem_manipulating_objects.rst b/sources/shiboken6/doc/typesystem_manipulating_objects.rst
index d87b816a3..9f9bc2b33 100644
--- a/sources/shiboken6/doc/typesystem_manipulating_objects.rst
+++ b/sources/shiboken6/doc/typesystem_manipulating_objects.rst
@@ -210,6 +210,41 @@ add-function
 
         void foo(int @parameter1@,float)
 
+.. _declare-function:
+
+declare-function
+^^^^^^^^^^^^^^^^
+
+    The declare-function node allows you to declare a function present in the
+    type.
+
+    .. code-block:: xml
+
+         <container-type>
+             <declare-function signature="..." return-type="..." since="..."/>
+         </container-type>
+
+    The ``return-type`` attribute defaults to *void*.
+
+    The ``since`` attribute specifies the API version when this function was
+    added.
+
+    This is useful to make functions known to shiboken which its code parser
+    does not detect. For example, in Qt 6, the ``append()`` function of the
+    ``QList<T>`` container takes an argument of ``parameter_type`` which is
+    specialized to ``T`` for simple types and ``const T &`` for complex types
+    by some template expression which the code parser cannot resolve.
+    In that case, the function can be declared with a simple signature:
+
+    .. code-block:: xml
+
+         <container-type name="QList">
+             <declare-function signature="append(T)"/>
+         </container-type>
+
+    This tells shiboken a public function of that signature exists and
+    bindings will be created in specializations of ``QList``.
+
 .. _conversion-rule-on-types:
 
 conversion-rule