Defs file format Revision 3

[Ariel Rios <ariel linuxppc org>]

Ok guys,
I have done some cleaning in the defs file
according to the proposals done in the list.
So I put into your consideration the new revision
which can be found at
http://linux.cem.itesm.mx/~ariel/defsformat.txt

or at this mail.

Still it have some comments inside /* */
whenever I don't know if we do need this or that.


ariel

Authors:
Havoc, James, Ariel

Revision 3.0

The overall syntax is:

     (define-type-of-thing  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:

===
GModules

(gmodule module-name) 

Ex: (gmodule "Gtk")
Ex: (gmodule "GdkRgb")


===
TYPES

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

(define-type string
  (c-name "gchar *")
  (g-type-id "GTK_TYPE_STRING"))

==========
Interfaces
   
(define-interface Editable
  (in-module module-name)
  (c-name name-of-the-c-interface))
    
Eg.
(define-interface Editable
 (in-module "Gtk")
 (c-name "GtkEditable"))

====
Objects

(define-object object-name
   (in-module module-name)
   (parent object-name)
   (c-name name-of-the-object-in-C)
   (abstract boolean) ;;defaults to #f
   (implements name-of-interface) ;;defaults to #f
   (fields (alias-of-struct-field name-of-struct-field access)*))
   
Eg: (define-object Widget
      (in-module "Gtk")
      (parent "GtkObject")     
      (c-name GtkWidget)	       
      (abstract #t)   
      (fields 
         ("GdkWindow *" "window" "read"))))

Eg:

(define-object Entry
  (in-module "Gtk")
  (parent "GtkWidget")
  (c-name "GtkEntry")
  (implements "GtkEditable"))


=========
Functions

(define-function function-name
  (in-module module-name-list) ;; "static methods" go in their objects's module
  (is-constructor-of object-type-alias) ;; bool, marks a constructor defaults to #f
  (c-name function-name)
  (return-type return-value-type) 
  (caller-owns-return boolean-value) ;; defaults to #f
  (can-return-null boolean-value) ;; defaults to #t
  (parameters 
      (in-or-out parameter-type-alias parameter-name . c-name)*)
  (varargs #t) ;; has varargs at the end
)

Ex:
  (define-function init
    (in-module "GdkRgb")
    (c-name "gdk_rgb_init")
    (parameteres ()))

Ex: 
  (define-function new
    (in-module "GdkRgbCmap")
    (is-constructor-of "GdkRgbCmap")
    (c-name "gdk_rgb_cmap_new")
    (return-type "GdkRgbCmap")
    (caller-owns-return #t)   ;; perhaps this could be implied by is-constructor-of
    (parameters 
        (in "array-of-guint32" "colors")
        (in "gint" "n_colors")))

/*
	Do we need this native stuff?
	Why do we need to pass such a pointer as an argument
*/

Ex:
  (define-function config_set_set_handler
   (in-module "Gnome")
   (c-name "gnome_config_set_set_handler")
   (parameters 
       (in "native" "func" "void (*func)(void*)")
       (in "gpointer" "data")))

===
METHODS

/*
	Cant' we just handle methods with define-func
        and just add a field called,
        (is-method bool) ???
*/

     
(define-method method-name
  (c-name c-name)
  (of-object object-name)
  ;; retval/arg attributes as for (function), but with first parameter
  ;; omitted for non-constructors
   )
 
Ex:
  (define-method set_text
     (c-name "gtk_label_set_text")
     (of-object "Label")
     (parameters 
         ("const-gchar*" "str")))
     
===
OBJECT ARGUMENTS

/*
  What are these for?
*/

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

Ex:
  (define-object-argument label
     (of-object Label "Gtk")
     (type "GTK_TYPE_STRING")
     (readable #t)
     (writeable #t))

=== 
SIGNALS

(definal-signal signal-name
  (of-object object-we-are-a-signal-of)
  (run-action bool-value)
  (run-first bool-value)
  (run-last bool-value)
  (parameters 
      (in-or-out parameter-type-alias parameter-name . c-name)*))

Ex:
  (define-signal select_row
     (of-object "CList")
     (run-first #t)
     ;; return type defaults to void
     (parameters 
         (in "gint" "row")
         (in "gint" "column")
         (in "GdkEvent *" "event")))

=== 
ENUMS

(define-enum enum-name
  (in-module modname)
  (c-name name-in-c)
  (values* 
     (nick value-c-name numval)*)

Ex:

  (define-enum DirectionType
    (in-module "Gtk")
    (c-name "GtkDirectionType")
    (values 
       ("tab-forward" "GTK_DIR_TAB_FORWARD" 0)
       ("tab-backward" "GTK_DIR_TAB_BACKWARD" 1)
       ("up" "GTK_DIR_UP" 2)
       ("down" "GTK_DIR_DOWN" 3)
       ("left" "GTK_DIR_LEFT" 4)
       ("right" "GTK_DIR_RIGHT" 5)))

  (define-enum Pos
    (in-module "GtkCTree")
    (c-name "GtkCTreePos")
    (values 
       ("before" "GTK_CTREE_POS_BEFORE")
       ("as-child" "GTK_CTREE_POS_AS_CHILD")
       ("after" "GTK_CTREE_POS_AFTER")))

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

(define-boxed boxed-name
  (in-module modname)
  (boxed-c-name c-name)
  (ref-func func-to-increase-refcount c-name)
  (copy-func func-to-copy c-name)
  (release-func func-to-destroy-or-decrement-refcount c-name)
  (fields 
     (type-alias-of-struct-field name-of-struct-field access-rule)*))


Ex:

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




===
STRUCTS

(define-struct struct-name
  (in-module modname)
  (c-name c-name)
   (fields 
     (type-alias-of-struct-field name-of-struct-field access-rule)*))

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

Ex:
 (define-struct Rectangle
   (in-module "Gdk")
   (c-name "GdkRectangle")
   (fields 
      ("gint16" "x" "readwrite")
      ("gint16" "y" "readwrite")
      ("guint16" "width" "readwrite")
      ("guint16" "height" "readwrite")))



===
USER-FUNCTIONS

/*
  What are these intended for?
*/

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

Ex:

 (define-user-function PrintFunc
    (in-module "Gtk")
    (parameters 
        (in "gpointer" "func_data")
        (in "gchar *" "str")))

===
TYPEDEF

/*
  And this?
  Do anyone needs this?
*/
(define-typedef new-name
  (in-module module)
  (c-name c-full-name)
  (orig-type alias-of-orig-type))

Ex:

 (define-typedef Type
   (in-module (Gtk))
   (c-name GtkType)
   (orig-type guint))