Re: [gnome-bindings] Redefining the defs format =)

[Ariel Rios <ariel linuxppc org>]

El 15 Apr 2001 19:03:00 +0800, James Henstridge escribió:

> # ;;;; 1) type-of-thing-being-defined should be define-type-of thing 
> # ;;;; i.e. define-module, define-type, define-type, define-func, etc
> # ;;;; Purpose:
> # ;;;; More clarity
> # ;;;; Avoid problems in languages that might use defs files 
> # ;;;; as macros (i.e. lisp languagues) 

As far as I remember php bindings use the new format.
rep uses the old format, and guile-gtk old format. 
 
> I don't know if anyone else is actually using the new defs format yet.
> It would be very quick to fix my code generator after a change like
> this.  If it makes it easier for guile/lisp, then we may as well make
> this change.  Does anyone else have an opinion?

There are two approaches two using defs files:
1)Parse the file and generate what is needed (python does this)
2)Interpret the defs as language functions (what I want to do w/guile)
This option obviously might only work with lisp's macro systems
(scheme, repl, common lisp)
We can simply use defs files as a program rather than a simple file.
That's why using names like define-type and so avoids
problems with lisp primitives and is a very small almost cosmetic change


> Again, this is going to cause problems.  GtkCList is a subclass
> GtkContainer.  It is a member of the Gtk module/package.  Does guile
> give some other meaning to modules that makes it a bad choice?

Moidules in guile are a collection of programs
HOwever, for example I only have a module for gtk, one for gdk,
one for gnome, etc
so when I require to use a module I do:
(use-modules (gtk gtk) (gtk gdk))

Doing 
(use-modules (gtk gtk editable text))
is a no no.
Yes I can ommit that but still the name can confuse people
Maybe we can call them gmodules  


> # 
> # ===
> # 
> # (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
> #  (is-parametric boolean)          ;; optional default to #f
> #  (in-c-name name-of-symbol-in-C)
> #  (out-c-name name-of-symbol-in-C)
> #  (inout-c-name name-of-symbol-in-C))
> # 
> # ;;;; I really do not understand what does in-c-name, 
> # ;;;; out-c-name inout-c-name stand for
> # ;;;; I can't really comment on this... 

> My code generator doesn't handle this at all at the moment -- I
> override the results of the code generator for functions that have out
> arguments, so don't really care what happens to this part of the spec.

I do not like the way it is. I would prefer:

(define-type new-type
 (gmodule-name gmodule)
 (c-name name) 
 (gtk-type-id gtk-type-system-id))


> 
> # 
> # 

> # ;;;; (parent Object (Gtk) "GtkObject")
This is perfect and lovely =)

 
> # 
> # ===
> # 
> # (function function-name
> #   (in-module module-name-list) ;; "static methods" go in their
> #                                ;;  object's module
> #   (is-constructor-of object-type-alias) ;; optional, marks a constructor
> #   (c-name function-name)
> #   (return-type return-value-type) ;; defaults to void
> #   (caller-owns-return boolean-value) ;; defaults to #f
> #   (can-return-null boolean-value) ;; defaults to #t
> #   (parameter in-or-out-or-inout 
> #       (type-and-name parameter-type-alias parameter-name)
> #       (type-parameter name-of-contained-type) ;; optional, requires parametric type
> #       (c-declaration "c-type-and-name")) ;; c-declaration only required
> #                                          ;; if the type alias is "native"
> #   (varargs #t) ;; has varargs at the end
> # )
> # ;;;; James can you explain me what are caller-owns-return, can-return-null 
> # ;;;; stand for? And why do we have different kind of paramenters
> # ;;;; in, out?
> 
> caller-owns-return is to specify whether you have to free the
> return/have been given a reference to the return value.  I don't use
> this in my code generator, as GTK+ is fairly consistent in this
> respect:
>   constructors give reference/ownership to caller
>   strings with type (gchar *) must be freed by caller
>   strings with type (const gchar *) must not be freed
>   a few others here ...

I see. It seems to me that this info is not required by guile.
Everything should be handle by the GC. 

> as for can-return-null, that says whether the function can ever return
> a NULL rather than a valid pointer/object reference.  My code
> generator always checks the return value for safety, so doesn't use
> this either.
I don't see the use of this... 
> I also don't support out or inout params in the code generator, as
> they don't really fit properly in python (again, I use override
> code).  It is the equivalent of the CORBA meanings of these keywords.
Ditto.
> # 
> # ;;;;Ok the examples are wrong
> # ;;;; c-name should be quoted
> 
> I am sure that a guile programmer knows best here :)
> 
> # 
> # 
> # ===
> # (method method-name
> #   (of-object object-name module-name)
> #   ;; retval/arg attributes as for (function), but with first parameter
> #   ;; omitted for non-constructors
> #    )
> # ;;;; This is broken
> # ;;;; we need to have a cname field
> 
> I think the comment here is a little misleading.  (method) can contain
> all attributes of (function).  It doesn't give the implied self/this
> argument.  For procedural style bindings, you can easily work out the
> type for this from the (of-object ...) bit.  Again, it may be better
> to use the C style name in of-object here.
agreed
> #  
> # Ex:
> #   (method set_text
> #      (of-object Label (Gtk))
> #      (parameter (type-and-name const-gchar* str)))
> # ;;;; should be
> # ;;;;(metod set_text
> # ;;;;  (of-object Label (Gtk))
> # ;;;;  (c-name "gtk_label_set_text")
> # ;;;;  (parameter (type-and-name const-gchar* str)))
> 
> That is almost exactly what I have :).  Just with (return-type none) added.
Obviosuly this should also need to change (of-object "GtkLabel") 
> # 
> # ;;;;Also. I think we should not use const-gchar*
> # ;;;; it is better to have gchar * as string
> # ;;;; and const gchar * as cstring
> 
> What is the rationale for this?  They both C string types, so it seems
> a little confusing.  In my h2def.py script, it keeps quite close to
> the C names in most places.
gchar * makes little sense in scheme whilst string is an easier translation.

> # 
> # ===
> # (object-argument arg-name
> #    (of-object object-we-are-an-argument-of optional-objects-module)
> #    (type-id argument-type)       ;; GTK_TYPE_OBJECT etc.
> #    ;; flags all default to #f
> #    (readable bool-value)
> #    (writeable bool-value)
> #    (construct-only bool-value))
> # 
> # ;;;; What are this for?
> 
> Probably GtkArg stuff.  Should probably be renamed to
> object-property.  This isn't used at all in the python bindings, as we
> get that information from introspection.
I do not seed the need for this. 
> # 
> # === 
> # (signal signal-name
> #   (run-action bool-value)
> #   (run-first bool-value)
> #   (run-last bool-value)
> #   (of-object object-we-are-a-signal-of optional-objects-module)
> #  )
> # 
> # ;;;; Same comments as in object apply, i.e.
> # ;;;;  (parent Object (Gtk) "GtkObject")
> 
> Again, I use introspection for this.  Which languages need
> signal/property definitions in the defs files?  The authors of those
> bindings are most qualified to judge what is needed here.

Guile does not.

> # 
> # === 
> # (enum enum-name
> #   (in-module modname)
> #   (c-name name-in-c)
> #   (value (nick value-name-noprefixes-hyphen-lowercase) (c-name value-c-name)))
> # 
> # ;;;; I think the value field should be simply used as:
> # ;;;; (value  value-name-noprefixes-hyphen-lowercase  value-c-name)
> 
> /me has no opinion here.
This is basically a cosmetic change. we really do not need to have nick and c-name
separated. In the old def ormat we had:
(define-enum MY-ENUM
 (none MY_ENUM_NONE)
 (other MY_ENUM_other))

I think that adding the nick and c-name expressions is not needed 

> # Ex:
> # 
> #  (boxed Pixmap
> #    (in-module (Gdk))
> #    (c-name GdkPixmap)
> #    (ref-func pixmap_ref)
> #    (release-func pixmap_unref))
> # 
> # ;;;; Looks good for me
> 
> yep, but the specification should probably use an actual boxed type as
> an example, since GdkPixmap is now a GObject.
Oh well yes.

  
> I guess for function prototype typedefs such as GtkCallback, etc.  Not
> really used in my code generator, as I usually need to special case
> these sort of things.
Not used here. 
 
> Same here.  These look like they would be covered by object/boxed
> definitions.
=)

ariel