[gnome-bindings] Redefining the defs format =)

[Ariel Rios <ariel linuxppc org>]

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.


Ah! My comments to the doc start with 4 semicolons =)

ariel  

 
*Marius could you please forward to guile-gtk list? sourceware.cygnus is
bouncing all of my emails*

The overall syntax is:

     (type-of-thing-being-defined  name-used-to-refer-to-this-thing
       (attribute-name  attribute-value-depending-on-the-attribute)
       (attribute-name  attribute-value-depending-on-the-attribute)
       (attribute-name  attribute-value-depending-on-the-attribute))

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.

Defined types and their attributes:

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

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

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.

===

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


===
(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")

===

(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?

;;;;Ok the examples are wrong
;;;; c-name should be quoted


===
(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
 
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)))

;;;;Also. I think we should not use const-gchar*
;;;; it is better to have gchar * as string
;;;; and const gchar * as cstring

===
(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?

=== 
(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")

Ex:
  (signal select_row
     (of-object CList (Gtk))
     (run-first #t)
     ;; return type defaults to void
     (parameter in (type-and-name gint row))
     (parameter in (type-and-name gint column))
     (parameter in (type-and-name GdkEvent* event)))

=== 
(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)

So the following example should be:

  (enum DirectionType
    (in-module Gtk)
    (c-name GtkDirectionType)
    (value (nick tab-forward) (c-name GTK_DIR_TAB_FORWARD))
;;;;(value tab-forward GTK_DIR_TAB_FORWARD)
    (value (nick tab-backward) (c-name GTK_DIR_TAB_BACKWARD))
;;;;(value tab-backward GTK_DIR_TAB_BACKWARD)
    (value (nick up) (c-name GTK_DIR_UP))
;;;; and so on 
    (value (nick down) (c-name GTK_DIR_DOWN))
    (value (nick left) (c-name GTK_DIR_LEFT))
    (value (nick right) (c-name GTK_DIR_RIGHT)))


===
(flags) is just like enum, but some bindings may wrap enums and flags differently.
    
===

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

Ex:

 (boxed Pixmap
   (in-module (Gdk))
   (c-name GdkPixmap)
   (ref-func pixmap_ref)
   (release-func pixmap_unref))

;;;; Looks good for me

===

(struct struct-name
  (in-module modname)
  (c-name c-name)
  (field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))

Unlike a boxed type, a struct type can be copied with memcpy() and
allocated on the stack or with g_malloc().

;;;; Ditto
 

===

(user-function name
  (in-module module)
  (c-name c-typedef-name)
  ;; return-type and parameters as for (function)
)

;;;; What does this is for?

===

(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