path: root/codegen/README.defs

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