TextBuffer.insertWithTagsByName method is missing

[dejlek]

Looks like gidgen did not generate this method. I did check the GIR files and not GTK3 and GTK4 GIR files have it.

GTK3: https://docs.gtk.org/gtk3/method.TextBuffer.insert_with_tags_by_name.html
GTK4: https://docs.gtk.org/gtk4/method.TextBuffer.insert_with_tags_by_name.html

GTK3 Gir:

      <method name="insert_with_tags_by_name"
              c:identifier="gtk_text_buffer_insert_with_tags_by_name"
              introspectable="0">
        <doc xml:space="preserve"
             filename="gtk/gtktextbuffer.c"
             line="1550">Same as gtk_text_buffer_insert_with_tags(), but allows you
to pass in tag names instead of tag objects.</doc>
        <source-position filename="gtk/gtktextbuffer.h" line="232"/>
        <return-value transfer-ownership="none">
          <type name="none" c:type="void"/>
        </return-value>
        <parameters>
          <instance-parameter name="buffer" transfer-ownership="none">
            <doc xml:space="preserve"
                 filename="gtk/gtktextbuffer.c"
                 line="1552">a #GtkTextBuffer</doc>
            <type name="TextBuffer" c:type="GtkTextBuffer*"/>
          </instance-parameter>
          <parameter name="iter" transfer-ownership="none">
            <doc xml:space="preserve"
                 filename="gtk/gtktextbuffer.c"
                 line="1553">position in @buffer</doc>
            <type name="TextIter" c:type="GtkTextIter*"/>
          </parameter>
          <parameter name="text" transfer-ownership="none">
            <doc xml:space="preserve"
                 filename="gtk/gtktextbuffer.c"
                 line="1554">UTF-8 text</doc>
            <type name="utf8" c:type="const gchar*"/>
          </parameter>
          <parameter name="len" transfer-ownership="none">
            <doc xml:space="preserve"
                 filename="gtk/gtktextbuffer.c"
                 line="1555">length of @text, or -1</doc>
            <type name="gint" c:type="gint"/>
          </parameter>
          <parameter name="first_tag_name" transfer-ownership="none">
            <doc xml:space="preserve"
                 filename="gtk/gtktextbuffer.c"
                 line="1556">name of a tag to apply to @text</doc>
            <type name="utf8" c:type="const gchar*"/>
          </parameter>
          <parameter name="..." transfer-ownership="none">
            <doc xml:space="preserve"
                 filename="gtk/gtktextbuffer.c"
                 line="1557">more tag names</doc>
            <varargs/>
          </parameter>
        </parameters>
      </method>

I am porting by DIDE application to gid:gtk3 and that is where I found out that this method is missing...

[elementgreen]

Yes, this is also handled manually in GtkD. Another non-introspectable varargs method.

[dejlek]

I did not know much about GIR when I wrote this ticket. Now I do know a little. Most importantly, I now know what introspectable="0" means. :) Gidgen did what was expected from it.

As I am writing down notes what was needed to convert GtkD application into a gid:gtk3 (will do the same later for gid:gtk4) I will most likely modify def files at some point to add these much needed methods/functions. I am going to keep this ticket as a reminder so I do not forget to do it. :)

[elementgreen]

I have been doing some more research on varargs GIR functions and why they are not introspectable. At first I thought I could come up with a solution in gidgen to provide vararg functionality using D vararg functions or templates. However, after further analysis, I was reminded that you cannot forward variable arguments to a C varargs ellipses function. If a "v" variation, like vprintf for the printf function for example, is provided, then you can pass them as a va_list. However, most (if not all) of the varargs methods in GIR files do not have a va_list version. So that means you are limited to a static list of arguments to any C ellipses varargs function. The vargs methods are purely convenience functions for C and the functionality they provide can almost always be performed with other API functions.

So in summary: I don't see a very convenient way for gidgen to provide the ability to automatically bind varargs callables. So that means manually creating them, as you are doing. Its worthy to note though, they are for convenience, and there should usually be a way to accomplish all the functionality with other APIs. I did not see any functionality with the Dialog methods for example, that couldn't be done with the other available methods. I'd certainly like to know if you have any specific examples of functionality that is missing by not having a binding for a varargs callable.

[elementgreen]

Oh. Hmm, it seems like Grok lied to me. I was actually able to create a D template which passes its arguments to a C varargs function (printf in this case). So it might still be possible for gidgen to generate templates which can be used to call varargs C functions. Going to play with this..

[elementgreen]

Here is a template I wrote as an exercise, with some help from Paul Backus on the D Language Code Club on Discord who provided the mapArgs() template. I can see potentially doing this in an automated way:

import gtk.c.functions;
import gtk.c.types;
import std.string;
import std.algorithm;
import std.meta;
import std.traits;

void insertWithTagsByName(Args...)(Args args)
  if(args.length >= 4
    && is(Args[0] : gtk.text_buffer.TextBuffer)
    && is(Args[1] : gtk.text_iter.TextIter)
    && allSatisfy!(isSomeString, Args[2 .. $]))
{
    auto _tags = args[3 .. $].mapArgs!toStringz;
    gtk_text_buffer_insert_with_tags_by_name(cast(GtkTextBuffer*)args[0].cPtr, cast(GtkTextIter*)args[1].cPtr,
        args[2].toStringz, cast(int)args[2].length, _tags[], null);
}

/// map over a variadic argument list
template mapArgs(alias fun)
{
    auto mapArgs(Args...)(auto ref Args args)
    {
        import std.typecons: tuple;
        import core.lifetime: forward;
        import std.meta: Map = staticMap;

        auto ref mapArg(alias arg)()
        {
            return fun(forward!arg);
        }

        return tuple(Map!(mapArg, args));
    }
}

[elementgreen]

Some ideas of how to handle this in a semi-automated way, would be to add some gid extensions to GIR. What would be needed is a way to describe the types of the varargs arguments. I could see adding some attributes, which could be patched in definition files, such as:

1. gid:varargs-types = <typename>, <typename>, ...
2. gid:varargs-skip-first = 0 | 1
3. gid:varargs-term-value = <termination_value>
4. gid:varargs-printf-param = <format_param_index>

#1 could be used if all of the varargs are of a single type, such as in this case. It would be gid:varargs-type="const(char)*". Or could also be used for varargs methods that take a sequence of types, by separating the types with commas. For example, the gtk.dialog.Dialog.newWithButtons method could have gid:varargs-types="const(char)*, int" for the button label string and response ID value.

#2 would be used for sequence types which skip the first item in the sequence and have it as the argument before the varargs. Such as with the newWithButtons example.

#3 would provide a way to specify that the varargs are terminated with the given value (0 could be used for null or a zero valued integer field). This would correspond with the first item in a sequence if there are multiple types. An arbitrary D value could potentially be specified here, such as an enum value, which could be used verbatim in the generated code.

#4 Indicates that the varargs are parameters to a printf style format string, with the parameter at the given index (could use -1 to mean the argument just before the varargs).

This is likely to be rather complicated to implement, but seems kind of cool. I don't think I'm going to prioritize it at the moment though. Might be worth implementing it before the next release, but I think improved array handling would be more valuable. There are currently a number of API functions which cannot be bound, because they use arrays whose size cannot be described by GIR as it is.

[dejlek]

This is just too clever for me to comprehend. :) What I did in my code migrated from GtkD to giddy is was to do it in few manual steps instead of calling insertWithTagsByName...

[elementgreen]

Indeed, I think all of the vararg methods are just for convenience.

[dejlek]

Yes, they all are. :)