Updated with Tizen:Base source codes

1 files changed, 351 insertions, 0 deletions

diff --git a/codegen/README.defs b/codegen/README.defs
new file mode 100644
index 0000000..5f7957e
--- /dev/null
+++ b/codegen/README.defs
@@ -0,0 +1,351 @@
+   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))
+