[gobject-introspection/ebassi/property-annotation: 7/17] Add introspection data for property accessors

[Emmanuele Bassi <ebassi src gnome org>]

commit 9973bcbc2815e23d6b3e9f88ed61ba214e3ac993
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Jun 17 13:07:35 2021 +0100

    Add introspection data for property accessors
    
    A GObject property can be accessed generically through the GObject API,
    e.g. g_object_set_property() and g_object_get_property(). Properties
    typically also have public accessor functions, which are (according to
    our own best practices) called through the generic API.
    
    The introspection data is currently missing the relation between a
    property and its public accessor functions. With this information, a
    language binding could, for instance, avoid exposing the C API entirely,
    thus minimizing the chances of collisions between property names and
    accessor functions; alternatively, a binding could call the C API
    directly instead of going through the generic GObject API, thus avoiding
    the boxing and unboxing from a native type to a GIArgument and finally
    into a GValue, and vice versa.
    
    In the GIR, we add two new attributes to the `property` element:
    
      - setter="SYMBOL"
      - getter="SYMBOL"
    
    where "symbol" is the C function identifier of the setter and getter
    functions, respectively. The `setter` attribute is only applied to
    writable, non-construct-only properties; the `getter` attribute is only
    applied to readable properties.
    
    We maintain the ABI compatibility of the typelib data by using 20 bits
    of the 25 reserved bits inside the PropertyBlob structure. The data is
    exposed through two new GIPropertyInfo methods:
    
      - g_property_info_get_setter()
      - g_property_info_get_getter()
    
    which return the GIFunctionInfo for the setter and getter functions,
    respectively.

 docs/reference/gi-sections.txt    |  2 +
 girepository/gipropertyinfo.c     | 79 +++++++++++++++++++++++++++++++++++++++
 girepository/gipropertyinfo.h     |  6 +++
 girepository/girnode.c            | 32 ++++++++++++++++
 girepository/girnode.h            |  3 ++
 girepository/girparser.c          |  7 ++++
 girepository/girwriter.c          | 22 +++++++++++
 girepository/gitypelib-internal.h |  8 +++-
 8 files changed, 158 insertions(+), 1 deletion(-)
---
diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt
index 0ba40c8e..77e1e163 100644
--- a/docs/reference/gi-sections.txt
+++ b/docs/reference/gi-sections.txt
@@ -300,6 +300,8 @@ GIPropertyInfo
 g_property_info_get_flags
 g_property_info_get_ownership_transfer
 g_property_info_get_type
+g_property_info_get_getter
+g_property_info_get_setter
 </SECTION>
 
 <SECTION>
diff --git a/girepository/gipropertyinfo.c b/girepository/gipropertyinfo.c
index e58d4600..9b854b90 100644
--- a/girepository/gipropertyinfo.c
+++ b/girepository/gipropertyinfo.c
@@ -132,3 +132,82 @@ g_property_info_get_ownership_transfer (GIPropertyInfo *info)
   else
     return GI_TRANSFER_NOTHING;
 }
+
+/**
+ * g_property_info_get_setter:
+ * @info: a #GIPropertyInfo
+ *
+ * Obtains the setter function associated with this #GIPropertyInfo.
+ *
+ * The setter is only available for %G_PARAM_WRITABLE properties that
+ * are also not %G_PARAM_CONSTRUCT_ONLY.
+ *
+ * Returns: (transfer full): the function info or %NULL if not set.
+ *   Free it with g_base_info_unref() when done.
+ */
+GIFunctionInfo *
+g_property_info_get_setter (GIPropertyInfo *info)
+{
+  GIRealInfo *rinfo = (GIRealInfo *)info;
+  PropertyBlob *blob;
+  GIBaseInfo *container;
+  GIInfoType parent_type;
+
+  g_return_val_if_fail (info != NULL, NULL);
+  g_return_val_if_fail (GI_IS_PROPERTY_INFO (info), NULL);
+
+  blob = (PropertyBlob *)&rinfo->typelib->data[rinfo->offset];
+  if (!blob->writable || blob->construct_only)
+    return NULL;
+
+  if (blob->setter == 0x3ff)
+    return NULL;
+
+  container = rinfo->container;
+  parent_type = g_base_info_get_type (container);
+  if (parent_type == GI_INFO_TYPE_OBJECT)
+    return g_object_info_get_method ((GIObjectInfo *) container, blob->setter);
+  else if (parent_type == GI_INFO_TYPE_INTERFACE)
+    return g_interface_info_get_method ((GIInterfaceInfo *) container, blob->setter);
+  else
+    return NULL;
+}
+
+/**
+ * g_property_info_get_getter:
+ * @info: a #GIPropertyInfo
+ *
+ * Obtains the getter function associated with this #GIPropertyInfo.
+ *
+ * The setter is only available for %G_PARAM_READABLE properties.
+ *
+ * Returns: (transfer full): the function info or %NULL if not set.
+ *   Free it with g_base_info_unref() when done.
+ */
+GIFunctionInfo *
+g_property_info_get_getter (GIPropertyInfo *info)
+{
+  GIRealInfo *rinfo = (GIRealInfo *)info;
+  PropertyBlob *blob;
+  GIBaseInfo *container;
+  GIInfoType parent_type;
+
+  g_return_val_if_fail (info != NULL, NULL);
+  g_return_val_if_fail (GI_IS_PROPERTY_INFO (info), NULL);
+
+  blob = (PropertyBlob *)&rinfo->typelib->data[rinfo->offset];
+  if (!blob->readable)
+    return NULL;
+
+  if (blob->getter == 0x3ff)
+    return NULL;
+
+  container = rinfo->container;
+  parent_type = g_base_info_get_type (container);
+  if (parent_type == GI_INFO_TYPE_OBJECT)
+    return g_object_info_get_method ((GIObjectInfo *) container, blob->getter);
+  else if (parent_type == GI_INFO_TYPE_INTERFACE)
+    return g_interface_info_get_method ((GIInterfaceInfo *) container, blob->getter);
+  else
+    return NULL;
+}
diff --git a/girepository/gipropertyinfo.h b/girepository/gipropertyinfo.h
index 7f9c89a0..4889f42e 100644
--- a/girepository/gipropertyinfo.h
+++ b/girepository/gipropertyinfo.h
@@ -50,6 +50,12 @@ GITypeInfo * g_property_info_get_type  (GIPropertyInfo *info);
 GI_AVAILABLE_IN_ALL
 GITransfer   g_property_info_get_ownership_transfer (GIPropertyInfo *info);
 
+GI_AVAILABLE_IN_1_70
+GIFunctionInfo *g_property_info_get_setter (GIPropertyInfo *info);
+
+GI_AVAILABLE_IN_1_70
+GIFunctionInfo *g_property_info_get_getter (GIPropertyInfo *info);
+
 G_END_DECLS
 
 #endif  /* __GIPROPERTYINFO_H__ */
diff --git a/girepository/girnode.c b/girepository/girnode.c
index 07e0d056..8e00447c 100644
--- a/girepository/girnode.c
+++ b/girepository/girnode.c
@@ -254,6 +254,8 @@ _g_ir_node_free (GIrNode *node)
        GIrNodeProperty *property = (GIrNodeProperty *)node;
 
        g_free (node->name);
+        g_free (property->setter);
+        g_free (property->getter);
        _g_ir_node_free ((GIrNode *)property->type);
       }
       break;
@@ -1627,6 +1629,36 @@ _g_ir_node_build_typelib (GIrNode         *node,
        blob->transfer_container_ownership = prop->shallow_transfer;
        blob->reserved = 0;
 
+        if (prop->setter != NULL)
+          {
+            int index = get_index_of_member_type ((GIrNodeInterface*)parent,
+                                                  G_IR_NODE_FUNCTION,
+                                                  prop->setter);
+            if (index == -1)
+              {
+                g_error ("Unknown setter %s for property %s", prop->setter, node->name);
+              }
+
+            blob->setter = (guint) index;
+          }
+        else
+          blob->setter = 0x3ff; /* max of 10 bits */
+
+        if (prop->getter != NULL)
+          {
+            int index = get_index_of_member_type ((GIrNodeInterface*)parent,
+                                                  G_IR_NODE_FUNCTION,
+                                                  prop->getter);
+            if (index == -1)
+              {
+                g_error ("Unknown getter %s for property %s", prop->getter, node->name);
+              }
+
+            blob->getter = (guint) index;
+          }
+        else
+          blob->getter = 0x3ff;
+
         _g_ir_node_build_typelib ((GIrNode *)prop->type,
                                 node, build, offset, offset2, NULL);
       }
diff --git a/girepository/girnode.h b/girepository/girnode.h
index 2cb5a960..c5630b11 100644
--- a/girepository/girnode.h
+++ b/girepository/girnode.h
@@ -174,6 +174,9 @@ struct _GIrNodeProperty
   gboolean transfer;
   gboolean shallow_transfer;
 
+  char *setter;
+  char *getter;
+
   GIrNodeType *type;
 };
 
diff --git a/girepository/girparser.c b/girepository/girparser.c
index 99ec91a9..ae3f3ce2 100644
--- a/girepository/girparser.c
+++ b/girepository/girparser.c
@@ -1526,6 +1526,8 @@ start_property (GMarkupParseContext *context,
   const gchar *construct;
   const gchar *construct_only;
   const gchar *transfer;
+  const gchar *setter;
+  const gchar *getter;
   GIrNodeProperty *property;
   GIrNodeInterface *iface;
 
@@ -1551,6 +1553,8 @@ start_property (GMarkupParseContext *context,
   construct = find_attribute ("construct", attribute_names, attribute_values);
   construct_only = find_attribute ("construct-only", attribute_names, attribute_values);
   transfer = find_attribute ("transfer-ownership", attribute_names, attribute_values);
+  setter = find_attribute ("setter", attribute_names, attribute_values);
+  getter = find_attribute ("getter", attribute_names, attribute_values);
 
   if (name == NULL)
     {
@@ -1582,6 +1586,9 @@ start_property (GMarkupParseContext *context,
   else
     property->construct_only = FALSE;
 
+  property->setter = g_strdup (setter);
+  property->getter = g_strdup (getter);
+
   parse_property_transfer (property, transfer, ctx);
 
   iface = (GIrNodeInterface *)CURRENT_NODE (ctx);
diff --git a/girepository/girwriter.c b/girepository/girwriter.c
index b913da00..caf3f039 100644
--- a/girepository/girwriter.c
+++ b/girepository/girwriter.c
@@ -977,6 +977,28 @@ write_property_info (const gchar    *namespace,
   if (flags & G_PARAM_CONSTRUCT_ONLY)
     xml_printf (file, " construct-only=\"1\"");
 
+  if (flags & G_PARAM_READABLE)
+    {
+      GIFunctionInfo *getter = g_property_info_get_getter (info);
+
+      if (getter != NULL)
+        {
+          xml_printf (file, " getter=\"%s\"", g_base_info_get_name ((GIBaseInfo *) getter));
+          g_base_info_unref ((GIBaseInfo *) getter);
+        }
+    }
+
+  if (flags & G_PARAM_WRITABLE)
+    {
+      GIFunctionInfo *setter = g_property_info_get_setter (info);
+
+      if (setter != NULL)
+        {
+          xml_printf (file, " setter=\"%s\"", g_base_info_get_name ((GIBaseInfo *) setter));
+          g_base_info_unref ((GIBaseInfo *) setter);
+        }
+    }
+
   write_ownership_transfer (g_property_info_get_ownership_transfer (info), file);
 
   write_attributes (file, (GIBaseInfo*) info);
diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h
index 28b177d6..0f044902 100644
--- a/girepository/gitypelib-internal.h
+++ b/girepository/gitypelib-internal.h
@@ -918,6 +918,10 @@ typedef struct {
  *   ownership of the container, but not of its contents, is transferred.
  *   This is typically the case when reading lists of statically allocated
  *   things.
+ * @setter: the index of the setter function for this property, if @writable
+ *   is set; if the method is not known, the value will be set to 0x3ff
+ * @getter: ths index of the getter function for this property, if @readable
+ *   is set; if the method is not known, the value will be set to 0x3ff
  * @reserved: Reserved for future use.
  * @reserved2: Reserved for future use.
  * @type: Describes the type of the property.
@@ -934,7 +938,9 @@ typedef struct {
   guint32        construct_only               : 1;
   guint32        transfer_ownership           : 1;
   guint32        transfer_container_ownership : 1;
-  guint32        reserved                     :25;
+  guint32        setter                       :10;
+  guint32        getter                       :10;
+  guint32        reserved                     : 5;
 
   guint32        reserved2;