Third draft (was Re: defs files)

[Havoc Pennington <hp redhat com>]

ChangeLog for this draft:
 - caller-owns-return attribute on functions/methods
 - include gtk-type-id in the type alias system
 - c-name for types converted to in-c-name out-c-name inout-c-name
 - merge unref-func and destroy-func for boxed types into release-func
 - split structs out of boxed types
 - c-declaration field
 - special "native" type alias; bail and use C declaration when necessary
 - defined objects and boxeds automatically create a module
 - make constructors functions and not methods, in appropriate
   object/boxed module

Draft =========================

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:

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

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

===

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

"Type" bindings are automatically assumed for objects, boxed types,
etc. as defined below.

The alias field is used to refer to the type later on.

If the C type has spaces they are converted to hyphens after
compressing all syntactically significant whitespace to a single
space:
 (type
    (alias const-gchar*
     (c-name const-gchar*)))

So hyphens have to go back to spaces for binding generators that
output C code.

Whenever a type alias can be used, it is also possible to use the
keyword "native", which implies that the type in question is too
C-specific to represent. Then a c-declaration will typically be
available for use.

C types containing [] or () are function pointers or arrays. For
arrays that don't specify a size, we just treat them as pointers. For
function pointers, we need special (type) syntax/attributes of some
kind, but since there basically aren't any of these right now in the
libs we care about we can just ignore them. 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.

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

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

An "object" declaration automatically implies the type definition:

(type
  (alias concat-module-elements-and-object-name)
  (in-c-name pointer-to-c-name)
  (out-c-name pointer-to-pointer-to-c-name)
  (inout-c-name pointer-to-c-name))

Ex: 
 (type (alias GtkWidget) 
       (in-c-name GtkWidget*) 
       (out-c-name GtkWidget**) 
       (inout-c-name GtkWidget*))

It also implies a module that is the name broken into parts:
 (module CTree
   (submodule-of Gtk))

===

(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
  (parameter in-or-out-or-inout 
      (type-and-name parameter-type-alias parameter-name)
      (c-declaration "c-type-and-name")) ;; c-declaration only required
                                         ;; if the type alias is "native"
  (varargs #t) ;; has varargs at the end
)

Ex:
  (function init
    (in-module (Gdk Rgb)
    (c-name gdk_rgb_init)))

Ex: 
  (function new
    (in-module (Gdk Rgb Cmap))
    (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
    (parameter in (type-and-name array-of-guint32 colors))
    (parameter in (type-and-name gint n_colors)))

Ex:
  (function config_set_set_handler
   (in-module (Gnome))
   (c-name gnome_config_set_set_handler)
   (parameter in (type-and-name native func)
                 (c-declaration "void (*func)(void*)"))
   (parameter in (type-and-name gpointer data)))  

===
(method method-name
  (of-object object-name module-name)
  ;; retval/arg attributes as for (function), but with first parameter
  ;; omitted for non-constructors
   )
 
Ex:
  (method set_text
     (of-object Label (Gtk))
     (parameter (type-and-name const-gchar* str)))

===
(object-argument arg-name
   (of-object object-we-are-an-argument-of optional-objects-module)
   (type argument-type)       ;; not sure what to put for type
   ;; flags all default to #f
   (readable bool-value)
   (writeable bool-value)
   (run-action bool-value)         
   (construct-only bool-value))

Ex:
  (object-argument label
     (of-object Label (Gtk))
     (type gchar*) ;; ????
     (readable #t)
     (writeable #t))

=== 
(signal signal-name
  (of-object object-we-are-a-signal-of optional-objects-module)
  ;; return value and parameters as for a function, omitting the object
  ;; and user data parameters

  ;; what other properties matter for a signal?
)

Ex:
  (signal select_row
     (of-object CList (Gtk))
     ;; 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 (name value-name-noprefixes-hyphen-lowercase) (c-name value-c-name)))

Ex:

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

  (enum Pos
    (in-module (Gtk CTree))
    (c-name GtkCTreePos)
    (value (name before) (c-name GTK_CTREE_POS_BEFORE))
    (value (name as-child) (c-name GTK_CTREE_POS_AS_CHILD))
    (value (name after) (c-name GTK_CTREE_POS_AFTER)))

===
(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)
   (unref-func pixmap_unref))

An "object" declaration automatically implies the type definition:

(type
  (alias concat-module-elements-and-boxed-name)
  (in-c-name pointer-to-c-name)
  (out-c-name pointer-to-pointer-to-c-name)
  (inout-c-name pointer-to-c-name))

Ex: 
 (type (alias GdkPixmap) 
       (in-c-name GdkPixmap*) 
       (out-c-name GdkPixmap**) 
       (inout-c-name GdkPixmap*))


===

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

Ex:
 (struct Rectangle
   (in-module (Gdk))
   (c-name GdkRectangle)
   (field (type-and-name gint16 x) (access readwrite))
   (field (type-and-name gint16 y) (access readwrite))
   (field (type-and-name guint16 width) (access readwrite))
   (field (type-and-name guint16 height) (access readwrite)))

Implies GdkRectangle type alias:

 (type (alias GdkRectangle) 
       (in-c-name GdkRectangle*) 
       (out-c-name GdkRectangle*)    ;; note - not the same as boxed types 
       (inout-c-name GdkRectangle*))

===

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

Ex:

 (user-function PrintFunc
    (in-module (Gtk))
    (parameter in (type-and-name gpointer func_data))
    (parameter in (type-and-name gchar* str)))

===

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