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

[James Henstridge <james daa com au>]

On 14 Apr 2001, Ariel Rios wrote:

> Ok guys.
> We need to get a final version of the defs file format
> that satisfy most of the language binders.
> I will restart the discussion by sending some comments
> of the current version. This do not means that all
> of my ideas are there... But I want to start discussion
> Hopefully if we all agree we can have the gtk-defs and gnome-defs
> modules.
> 
> Remember that the current version of the document is on gtk+ HEAD
> on the docs dir.

The exact filename is gtk+/docs/defsformat.txt (HEAD branch of gtk+).
This is available on the web at:
  http://cvs.gnome.org/bonsai/cvsblame.cgi?file=gtk%2b/docs/defsformat.txt&root=/cvs/gnome

The final revised spec we use would be a good thing to put on
bindings.gnome.org when we set it up :)

Attached are my comments interspersed with Ariel's.  If anyone else has an
opinion, please send it to the list.

James.

-- 
Email: james daa com au
WWW:   http://www.daa.com.au/~james/

# ;;;; 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) 

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?

# 
# ===
# (module module-name
#   (submodule-of module-name)) ;; submodule is optional
# 
# Ex: (module Gtk)
# Ex: (module Rgb
#       (submodule-of Gdk))
# 
# modules are later referred to with a list of module names, like 
# (Gdk Rgb) or (Gtk)
# 
# ;; I really do not like the name module
# ;; It might lead to confusion compared to guile modules.
# ;; Specially since it might imply that we need a guile module
# ;; per defs module
# ;; I encourage the use of a different name 
# ;; maybe 'class' is a good one

class sounds like a really bad choice.  GObject derivatives are
classes in most of the bindings.  In the python world, you might use
the terms module or package for this.

# 
# Object and boxed type definitions automatically create a submodule.
# For example, GtkCList creates the module (module CList (submodule-of
# (Gtk))) which is referred to as module (Gtk CList).
# 
# ;; so CList should be called a subclass of Gtk
# ;; which I think it is better.

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?

# 
# ===
# 
# (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... 

I don't use this at all in my code generator at the moment.I think the
idea is that you might define a type (such as string).  in-c-name
would be the type of the variable when passing it as an `in' argument
(ie. gchar *), and out-c-name would be for an `out' argument
(ie. gchar **).

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.

# 
# 
# ===
# (object object-name
#    (in-module module-name-list)
#    (parent object-name optional-module-name-if-different)
#    (abstract boolean-is-abstract-class) ;; omit for default of #f
#    (c-name name-of-the-object-in-C)
#    (field (type-and-name type-alias-of-struct-field name-of-struct-field)
#           (access read-or-write-or-readwrite)))
# 
# ;;; Much of this info is overhead for guile
# ;;; I really do not need much besides c-name, parent
# ;;; and fields. I assume that OO guys can make good use of it.
# ;;; I will suggest a change in (parent)
# ;;; 
# 
# Ex: (object Widget
#       (in-module (Gtk))
#       (parent Object)      ;; could say (parent Object (Gtk))
#       (abstract #t)
#       (c-name GtkWidget)
#       (field (type-and-name GdkWindow* window) (access read)))
# 
# ;;;; I prefer this to be (parent object optional c-name)
# ;;;; (parent Object (Gtk) "GtkObject")

or just (parent "GtkWidget").  You can find its name/module from the
(object ...) def for the parent.  Anyone else have an opinion?

# 
# ===
# 
# (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 ...

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 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.

# 
# ;;;;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.

#  
# 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.

# 
# ;;;;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.

# 
# ===
# (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.

# 
# === 
# (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.

# 
# === 
# (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.

# 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.

# ===
# 
# (user-function name
#   (in-module module)
#   (c-name c-typedef-name)
#   ;; return-type and parameters as for (function)
# )
# 
# ;;;; What does this is for?

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.

# 
# ===
# 
# (typedef new-name
#   (in-module module)
#   (c-name c-full-name)
#   (orig-type alias-of-orig-type))
# 
# Ex:
# 
#  (typedef Type
#    (in-module (Gtk))
#    (c-name GtkType)
#    (orig-type guint))
# 
# 
# ;;;; Do not see the need of this.
# ;;;; I suppose define-type, define-object, etc

Same here.  These look like they would be covered by object/boxed
definitions.