Re: Fourth draft of defs file format

[Miroslav Silovic <silovic zesoi fer hr>]

Okay, I got a bit late into the discussion. Wheeww. :)

First, I since I called for unified defsfile earlier, I got a few
comments on gnome list and on guile-gtk lists. Two are worth
forwarding for review:

] From James Henstridge:
] 
] If you are going to make a new binding description format (which I think
] is a good idea -- C header files do not convey as much information as is
] needed for some bindings), one target should be C headers and skeleton
] code.  This way, people who are not even interested in making bindings for
] their widget libraries would have a reason to write an description file.

Note that this would be a significant change to the current gtk
codebase (as all the headers would be replaced by autogenerated
stuff), and if you like this idea, it would certainly have to go in
before the code freeze. I like this, BTW - it would also force people
to review their APIs and remove much of the problems (both known
problems and the ones we have yet to encounter).

] From Alex Stark:
] 
] My 2c worth is that provision for very short documentation strings (ie
] fewer than 60 chars) could be very useful.

This would be great for interactive languages like Guile where you can
request short help for all defined symbols.

Now comments on the current draft:

> Some definitions can have a c-declaration field that gives the C code 
> we parsed to arrive at the definition. The c-declaration is a quoted 
> string because it can contain parentheses and such. 

Note that if the .defs aren't autogenerated but used to create
headers, this would go "Some definitions can have a c-declaration
field that gives the C code to be put into the header file."

Also, C headers obscure more semantic issues than obvious (see below,
on parametric types), so .defs autogeneration may not be the option in
many cases (modulo magic comments).

> (type 
>  (alias some-unique-identifier) 
>  (in-module module-name) ;; optional, gchar* is not in a module 
>  (gtk-type-id gtk-type-system-id) ;; optional, absent if this is not 
> 				    ;; in the type system 
>  (in-c-name name-of-symbol-in-C) 
>  (out-c-name name-of-symbol-in-C) 
>  (inout-c-name name-of-symbol-in-C)) 
> 
> Ex: (type 
>      (alias string) 
>      (gtk-type-id GTK_TYPE_STRING) 
>      (in-c-name "const gchar*") 
>      (out-c-name "gchar**") ;; actually I'm not sure how strings work out/inout 
>      (inout-c-name "gchar*")) 
> 
>  ;; This one would be implied by the (object) def for GtkWidget I 
>  ;; think - (type) is only required for types that are not implied 
>  ;; by other definitions, such as int/boolean/etc. 
>   
>     (type 
>      (alias GtkWidget) 
>      (in-module (Gtk)) 
>      (gtk-type-id GTK_TYPE_WIDGET) 
>      (in-c-name "GtkWidget*") 
>      (inout-c-name "GtkWidget*") 
>      (out-c-name "GtkWidget**")) 

gnome-guile also uses parametric types. For example, if a function
returns a linked list (in glib sense) of GdkPoints (boxed type), you
can use (list point) as a parameter. Now these get passed as simple C
types (but in more than one argument, sometimes) - therefore, the
definition above is more or less sufficient, with wrapper-dependant
extensions (defined in a separate file). However, wrapper creation
would be simpler with some additions:

(type
  (doc "Linked list of elements") ; illustrate docstrings
  (alias list)
  (allow-parameters) ; specify that this is a compound type
  (in-c-name "GList*")
  (out-c-name "GList**")
  (inout-c-name "Glist**"))

Then allow use of (list GtkWidget) instead of just list. Wrapper would 
have to take care of the proper handling of list.

> For arrays that specify a size ditto, you would handle them by
> adding an (array-size) attribute or something or using the "native"
> keyword and skipping the (type) stuff.

guile-gtk currently uses the equivalent of (array-size) attribute. The
other case of paired function arguments are in callbacks (function
pointer + data) - perhaps one or more callback types would be in
order.

> (boxed boxed-name 
>   (in-module modname) 
>   (c-name c-name) 
>   (ref-func func-to-increase-refcount) 
>   (copy-func func-to-copy) 
>   (release-func func-to-destroy-or-decrement-refcount) 
>   (field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule))) 
> 
> It is never OK to use memcpy() to copy a boxed type, or use 
> malloc()/free() to alloc/free one. 

The one case in gnome-libs that doesn't work well as boxed is
GnomeHelpMenuEntry, as it seems to be designed for being embedded in C
static structures. It lacked constructors/destructors/copiers.

-- 
How to eff the ineffable?