defsformat.txt 9.42 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338

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

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

 (type
     (alias list)
     (gtk-type-id GTK_TYPE_POINTER)
     (is-parametric #t)
     (in-c-name "GList*")
     (out-c-name "GList**")
     (inout-c-name "GList**"))


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

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

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-id argument-type)       ;; GTK_TYPE_OBJECT etc.
   ;; flags all default to #f
   (readable bool-value)
   (writeable bool-value)
   (construct-only bool-value))

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

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

Ex:

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

  (enum Pos
    (in-module (Gtk CTree))
    (c-name GtkCTreePos)
    (value (nick before) (c-name GTK_CTREE_POS_BEFORE))
    (value (nick as-child) (c-name GTK_CTREE_POS_AS_CHILD))
    (value (nick 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)
   (release-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)))

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

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