1GOB2(1)                     General Commands Manual                    GOB2(1)
2
3
4

NAME

6       GOB2 - The GObject Builder
7

SYNOPSIS

9       gob2 [ option ] ...  file
10
11

DESCRIPTION

13       GObject  Builder  is  a simple preprocessor for easily creating GObject
14       objects.  It does not parse any C code and ignores any C errors.  It is
15       in  spirit  similar  to  things like lex or yacc.  In some ways it also
16       resembles java.  But it is really just a simple preprocessor for creat‐
17       ing GObjects for use in C or C++ and it is not a programming language.
18
19

OPTIONS

21       -? -h --help
22              Display a simple help screen.
23
24       --version
25              Display version information
26
27       -w --exit-on-warn
28              Exit with an error code even when you encounter a warning.
29
30       --no-exit-on-warn
31              Exit  with an error only on errors, not on warnings, this is the
32              default.
33
34       --for-cpp
35              Generate C++ code.
36
37       --no-extern-c
38              Never add the extern "C" to the header.
39
40       --no-gnu
41              Never generate any code with GNU C extensions.  However all  the
42              GNU  C extensions are always wrapped in #ifdef __GNUC__, so code
43              using them compiles correctly even on non-GNU  compilers.   This
44              option is for purists only.  (using GNU extensions some warnings
45              are eliminated, some ugly hacks and  there  is  better  argument
46              type safety, so it´s good to use them)
47
48       --no-touch
49              Don´t  touch  output  files  unless they really changed (implies
50              --no-touch-headers).  Be careful with automake, see section PRE‐
51              VENTING SPURIOUS BUILDS.
52
53       --no-touch-headers
54              Don´t  touch the generated header file unless it really changed,
55              this avoids spurious rebuilds, but can confuse some make systems
56              (automake in particular), so it is not enabled by default.  Pri‐
57              vate header is still touched even if unchanged however.
58
59       --always-private-header
60              Always create a <basename>-private.h file, even if it  would  be
61              empty.
62
63       --ondemand-private-header
64              Create the private header only if it would have something in it,
65              that is, if there are some private  data  members  or  protected
66              methods.  This is the default.
67
68       --no-private-header
69              Never  create a private header file.  If we use any private data
70              members, define the private data structure at the point  in  the
71              .c source where the class definition begins.
72
73       --m4   Preprocess source with m4. Following args will be passed to m4.
74
75       --m4-dir
76              Print directory that will be searched for m4 files.
77
78       -n --no-write
79              Do  not  write  any output files, just check syntax of the input
80              file.
81
82       --no-lines
83              Do not print out the ´#line´ statements into the output.  Useful
84              for debugging the auto-generated generated code.
85
86       --no-self-alias
87              Do  not create the Self and SelfClass type aliases and the SELF,
88              IS_SELF and SELF_CLASS macros.
89
90       --no-kill-underscores
91              Do not remove the initial underscore from method names.
92
93       --always-private-struct
94              Always include the private pointer in the  public  header  file.
95              This  is  useful  for  files which are part of a library and you
96              want to reserve the right to add some private data members with‐
97              out breaking binary compatibility.
98
99       -o --output-dir
100              The directory into which output should be placed.
101
102       --file-sep[=c]
103              Replace  default `-´ file name separator.  If no separator char‐
104              acter is given then none is used.  Only  one  character  can  be
105              used.
106
107

TYPENAMES

109       Because we need to parse out different parts of the typename, sometimes
110       you need to specify the typename with some special syntax.   Types  are
111       specified  in  capitalized  form  and  words are separated by `:´.  The
112       first word of the type (which can be empty) is the  "namespace".   This
113       fact  is  for  example  used  for  the type checking macro and the type
114       macro.  For "Gtk:New:Button", the macros will be GTK_IS_NEW_BUTTON  and
115       GTK_TYPE_NEW_BUTTON.   This colon separated format of typenames is used
116       in the class declaration header and for method argument types.
117
118

OUTPUT FILES

120       The filenames are created from the typename.  The words  are  separated
121       by  `-´  (this  can be changed with --file-sep option) and all in lower
122       case.  For example for an object named "Gtk:New:Button", the files  are
123       gtk-new-button.c  and gtk-new-button.h.  If you are using C++ mode, the
124       output .c file will in fact be a .cc file.  If  you  have  any  private
125       data members, a private header file will also be created, called <base‐
126       name>-private.h (for the example above it would be  gtk-new-button-pri‐
127       vate.h).  The public header file is created to be human readable and to
128       be used as a reference to the object.  The .c source file is  not  cre‐
129       ated  as a human readable source and is littered with #line statements,
130       which make the compiler attempt to point you to the right line in  your
131       .gob  file  in case of parsing errors.  The output should not be edited
132       by hand, and you should only edit the .gob file.
133
134

INCLUDING NORMAL C CODE IN THE OUTPUT FILES

136       To include some code directly in the output C file begin with  ´%{´  on
137       an  empty  line  and  end the code with a ´%}´ on an empty line.  These
138       sections will appear in the output files in the order they  are  given.
139       There  are  several  other sections to which you can put code.  You can
140       put it in the ´header´ section (which can be abbreviated  ´h´)  and  it
141       will  go into the public header file.  You can also put it in the ´pri‐
142       vateheader´ section (abbreviated ´ph´) which will make the code go into
143       the private header file.  Sometimes you want some code (other includes)
144       to appear before the extern "C" and the protecting define.  To do  this
145       you  can put them into the ´headertop´ (or ´ht´) section.  You may wish
146       to include code or comments in all the  files,  which  you  can  do  by
147       putting them into the ´all´ (or ´a´) section.  Similarly, code you wish
148       to appear at the top of all files go in the ´alltop´ (or ´at´) section.
149       Finally,  ´afterdecls´  includes  code between the declarations and the
150       method implementations, but note  that  ´afterdecls´  requires  version
151       2.0.16.  For example:
152
153         %alltop{
154               /* this will be on top of all output files */
155         %}
156
157         %headertop{
158               /* this will be on top of the public header */
159         %}
160
161         %privateheader{
162               /* this will go into the private header file */
163         %}
164
165         %h{
166               /* will be included in the header */
167               void somefunc(int i);
168         %}
169
170         %a{
171               /* will be included in all files */
172         %}
173
174         %afterdecls{
175               /* between the declarations and the method implementations */
176               /* Requires gob version 2.0.16 */
177         %}
178
179         %{
180               /* will be included in the C file */
181               void somefunc(int i)
182               {
183                     /* some code */
184               }
185         %}
186
187
188

INCLUDE FILES

190       Gob  will automatically include the class header file at the top of the
191       .c source file.  If you wish to include  it  somewhere  else,  put  the
192       include  into  some  %{  %} section above the class definition, and gob
193       will not include it automatically.  This way  you  can  avoid  circular
194       includes  and  control  where  in  the  file do you want to include the
195       header.
196
197       If you made any data members private, gob will  also  create  a  source
198       file  that  will  be  called  <basename>-private.h.  Same rule as above
199       applies for this just as it does for the regular header file.   If  you
200       do  explicitly  include  the  regular  header  file,  you should always
201       include this private header file below it.  That is,  if  you  use  any
202       private  data members.  If you don´t, the private header file automati‐
203       cally includes the public header file, and thus the public header  file
204       will be indirectly included at the very top of the file.
205
206

THE CLASS HEADER

208       There  can  be only one class per input file.  Defining a class is sort
209       of like in Java, you define the class and write  inline  code  directly
210       into  the  class definition.  To define a class you need to specify the
211       new object name and the name of the object from  which  it  is  derived
212       from,  such as this "class <new type> from <parent type> { <class code>
213       }".  For example:
214
215         class Gtk:New:Button from Gtk:Button {
216              <class code>
217         }
218
219
220       To  make  an  abstract  class  (to   pass   G_TYPE_FLAG_ABSTRACT)   add
221       ´(abstract)´  before  the curly braces above.  This works since version
222       2.0.13.
223
224

DATA MEMBERS

226       There are five types of data members.  Three of them  are  normal  data
227       members,  one is class wide (global) in scope and one is a virtual one,
228       usually linked to a normal data member or a  class  wide  data  member.
229       The  three normal data members are public, protected and private.  Pub‐
230       lic and protected are basically just entries in the  object  structure,
231       while  private  has  it´s  own dynamically allocated private structure.
232       Protected members are always put after the public one in the  structure
233       and are marked protected in the header file.  There is only one identi‐
234       fier allowed per typename unlike in normal C.  Example:
235
236         public int i;
237         private GtkWidget *h;
238         protected long k;
239
240
241       Public and protected data members are accessed normally as  members  of
242       the object struct.  Example where ´i´ is as above a public data member:
243
244         object->i = 1;
245
246
247       The  private  data  members  are  defined  in a structure which is only
248       available inside the .c file, or by including a  private  header  file.
249       You  must  access them using the structure _priv.  Example where ´h´ is
250       the private data member (as in the above example):
251
252         object->_priv->h = NULL;
253
254       The _priv structure is defined in the <basename>-private.h.  This  file
255       is automatically included if you don´t include it yourself.  You should
256       always explicitly include it in your .gob file if you  explicitly  also
257       include  the main header file.  The reason it is a separate header file
258       is that you can also include it in other places  that  need  to  access
259       this  objects  private  data, such as if you have the majority of func‐
260       tionality of an object in a separate .c file.  Or if a  derived  object
261       needs to access the protected methods.
262
263       In  case you use the --no-private-header option, no private header file
264       is created and you can only access the _priv pointer  below  the  class
265       definition in the .gob file.
266
267       Also note that this structure is dynamically allocated, and is freed in
268       the finalize handler.  If you override the finalized handler, your code
269       will be run first and only then will the _priv structure be freed.
270
271       Classwide data members:
272
273       Sometimes  you want a datamember to be shared by all objects.  You then
274       need the "classwide" scope keyword.  So for example the following  adds
275       a global member foo:
276
277         classwide int foo;
278
279       To  access  the  member  you  can  use  the  SELF_GET_CLASS  macro  (or
280       YOUR_OBJECT_NAME_GET_CLASS) to get at the class.   Thus  the  following
281       would work:
282
283         SELF_GET_CLASS(object)->foo = 20;
284
285
286       Automatic Initialization:
287
288       You  can automatically initialize the public private and protected data
289       members without having to add an init method.  The  advantage  here  is
290       that  initialization is kept close to the definition of the data member
291       and thus it´s easier to check.  To do this, just add a ´=´ followed  by
292       a  number  or a token.  It is also possible to include arbitrary C code
293       for more elaborate initializations by putting it all in  curly  braces.
294       Note  that  the  curly  braces will not be printed into the output, but
295       since gob does not C parsing it needs them to figure out  where  the  C
296       code  ends.   The code will be inserted into the init method, above the
297       user defined body.  So for example the  following  will  initialize  an
298       integer to -1 and a string with a newly allocated string of "hello".
299
300         public int foo = -1;
301         private char *bar = {g_strdup("hello")};
302
303
304       Automatic Destruction:
305
306       Most  data  stored as pointers needs to have a function called when the
307       object is finalized to either free the data.  Gob will let you define a
308       function  to  be  called  on the data the object is finalized.  This is
309       achieved by putting ´destroywith´ followed by a function name after the
310       variable definition.  It is only called if the data you defined this on
311       is not NULL, so you cans specify functions which do  not  handle  NULL.
312       It  is very much like the GDestroyNotify function used in GTK+ and glib
313       in many places.  Unlike many other places, gob  will  not  enforce  any
314       kind of type safety here so be a little bit more careful.  Any function
315       you give it will be called as a "void function(void *)".   It  will  in
316       fact be cast into such a form before called.  This is to avoid spurious
317       warnings for gtk calls to subclass methods.  The function needs not  be
318       of  that  form  exactly,  it just has to take one argument which is the
319       pointer to the data.  You should also  not  define  this  on  any  non-
320       pointer data as the results may be undefined.  Example:
321
322         public char *foo = {g_strdup("bar")}
323                 destroywith g_free;
324
325       Note  that  the  function name you give must be a real function and not
326       macro.  Also note that this is always called in the  "finalize"  method
327       of  GObject.   It  is  always called after any user defined body of the
328       finalize handler.
329
330       Sometimes you may want to run arbitrary  code  on  destruction.   While
331       this  can be perfectly well done in the finalize handler.  Depending on
332       the style you may want to include all  destruction/initialization  code
333       together  with the definition of the data member.  Thus you may want to
334       put arbitrary code which will then  be  inserted  into  the  "finalize"
335       method  of  GObject.   This can be done with the "destroy" keyword fol‐
336       lowed by arbitrary code in curly braces.   Inside  this  code  a  macro
337       called  VAR will be define which refers to your variable.  So for exam‐
338       ple destroying a GString can be either done with a  helper  routine  or
339       the following code:
340
341         public GString *string = {g_string_new(NULL)}
342                 destroy {
343                      if(VAR) g_string_free(VAR, TRUE);
344              };
345
346       The thing to remember with these is that there are many ways to do this
347       and you´d better be consistent in your code in how you  use  the  above
348       things.   Also  defining  a helper routine that will do the destruction
349       will be a nicer thing to do if that´s  a  possibility.   The  "destroy"
350       keyword with code does take up more space in the file and it may become
351       more cluttered.
352
353       The data is zeroed out after being destroyed.  This is to  make  debug‐
354       ging  easier in case your code might try to access an already finalized
355       object.  In case you have overridden the  finalize  method,  your  code
356       will  be  run  first and only then will the destructors be called.  You
357       should not however make any assumptions about the order  at  which  the
358       destructors are called.  If you have interdependencies between destruc‐
359       tors for different data members, you will have to do this in  your  own
360       finalize override function.
361
362       Automatic Unreffing:
363
364       This is very much like the automatic destruction, but is instead run in
365       the dispose method (it is among other places called from the  "destroy"
366       method  of  GtkObject).   All  data  and other objects that you need to
367       unref should be done here, and not at finalize time.  The semantics are
368       otherwise  the  same  as  for the "destroywith" and "destroy" keywords,
369       except that you use "unrefwith" and "unref".
370
371         public G:Object *foo = NULL
372                 unrefwith g_object_unref;
373         public G:Object *bar = NULL
374                 unref {
375                 g_object_unref (VAR);
376              };
377
378
379

GOBJECT PROPERTIES

381       The fourth type of a data member a property type.  It is a  named  data
382       member  which  is  one  of the features of the GObject system.  It just
383       defines a way to get and set some data, but you have to  take  care  of
384       storing  that  data  somewhere.   So it is normal to also have a normal
385       private (or public) data member where you store  the  real  data.   You
386       normally need to define a get and a set handler.  They are fragments of
387       C code that will be used to get the value or set the value of the argu‐
388       ment.   Inside  them you can use the define VAL to which you assign the
389       data or get the data.  You should treat this  VAL  as  a  GValue  which
390       stores  the  data of the correct type.  You can also use the identifier
391       "self" as pointer to the object instance.  The type is defined  as  one
392       of  the  GObject type enums, but without the G_TYPE_ prefix.  There are
393       also some attributes of a property which you can set.  For example  the
394       following is a definition of an integer property ´height´ which will be
395       synchronized with a private  integer  data  member  also  of  the  name
396       ´height´.
397
398         private int height;
399         property INT height
400                (nick = _("Short nickname"),
401                 blurb = _("Long description"),
402                 minimum = 10,
403                 maximum = 200,
404                 default_value = 100)
405               set { self->_priv->height = g_value_get_int (VAL); }
406               get { g_value_set_int (VAL, self->_priv->height); };
407
408
409       The  attributes are really optional though you should at least set some
410       of them.  All property types have a ´nick´ and a ´blurb´ attribute  and
411       you  should set those accordingly.  This will make runtime querying the
412       object nicer as things such as gui editors and class  browsers  can  be
413       more  verbose  about  the  class itself.  You can use the ´_("string")´
414       notation instead of just "string", and that will mark  the  string  for
415       translation.
416
417       Almost  all  types also have a ´default_value´ attribute which sets the
418       initial value of this property (on object initialization, the set  han‐
419       dler  will  be  run automatically with this value).  This value will be
420       overriden if the user sets a value of this  property  on  the  call  to
421       g_object_new.
422
423       All  the  numeric  types  (including CHAR) have ´minimum´ and ´maximum´
424       attributes which can restrict the range.  If you do not  specify  these
425       the range will be the full range that the data type can handle.
426
427       Types  such  as  UNICHAR  and BOOLEAN only have the ´nick´, ´blurb´ and
428       ´default_value´ attributes.
429
430       The ENUM type has an ´enum_type´ attribute which is the exact  type  of
431       the  enum.  This is so that the property knows which exact type you can
432       set, rather then just knowing it is an enum.  You should always  create
433       an  enum  type  specific  for  the enum itself (see section on the enum
434       types)
435
436       Similarly FLAGS type has a ´flags_type´ which again you should  set  to
437       the specific type of this flags data member.
438
439       There  is  a  STRING  type  which  has  only  the extra ´default_value´
440       attribute.
441
442       The OBJECT type is one of the types that doesn´t have a ´default_value´
443       and  it  only  has  an ´object_type´ attribute (in addition to nick and
444       blurb of course) that is the  exact  object  type  that  this  property
445       accepts.   The  object_type  should  be  as a type, that is for example
446       ´Gtk:Button´.
447
448       There is a BOXED type which is a pointer which has a boxed type defined
449       (such  that  GObject knows how to copy and destroy this pointer).  Here
450       you will need to specify the ´boxed_type´ attribute with  the  specific
451       type of the boxed pointer.
452
453       There  is  also  a  POINTER type, which has only the ´nick´ and ´blurb´
454       attributes.  This is for storing arbitrary  pointers.   You  should  be
455       careful  with  this one, as GObject knows nothing about the data stored
456       at this pointer.  It is somewhat like a ´void *´ type.
457
458       There is also the PARAM type for storing parameters with a ´param_type´
459       attribute.
460
461       You  should  notice  that  this  list  is  pretty much like the list of
462       g_param_spec_* functions from gobject/gparamspecs.h, and the attributes
463       are  like  the  arguments  of those functions.  Note however that value
464       array is NOT supported yet.
465
466       You can also specify extra flags, such as CONSTRUCT  or  CONSTRUCT_ONLY
467       using  the  ´flags´ attribute.  You can specify multiple flags by oring
468       them together with ´|´.  These flags correspond to the GParamFlags enu‐
469       meration  except do not include the G_PARAM_ prefix.  So for example to
470       define an enumeration property, which is a CONSTRUCT_ONLY property,  we
471       could do the following:
472
473         private SomeEnumerationType foo;
474         property ENUM foo
475                (nick = _("Short nickname"),
476                 blurb = _("Long description"),
477                 enum_type = Some:Enumeration:Type
478                 default_value = SOME_ENUMERATION_VALUE,
479                 flags = CONSTRUCT_ONLY,
480                 link);
481
482
483       The above example also gives an example of automatic linking to a stan‐
484       dard data memember.  By including the attribute ´link´ a  get  and  set
485       handlers  will  be  automatically  added without having to type them by
486       hand.  This is useful for a vast majority  data  types  that  are  just
487       linked  to  some  standard  data  member and do not need to do anything
488       extra on get or set.
489
490       Another extra feature of properties is the possibility of automatically
491       exporing  methods  to get and set the property.  That is without having
492       to use g_object_set and g_object_get.  This is achieved  by  adding  an
493       ´export´ attribute to the list of property attributes.
494
495       If  you do not define a set or get handler, the property will automati‐
496       cally be only readable or writable as appropriate.
497
498       Gob2 also creates macros which can be used  for  type  safe  access  to
499       properties  through  g_object_set  and  g_object_get.   The  macros are
500       called  <type>_PROP_<argument  name>(x)  and  <type>_GET_PROP_<argument
501       name>(x).   They define both the string and the value part of the argu‐
502       ment.  So for setting an argument of height, one would use (for  object
503       type My:Object):
504
505         g_object_set (G_OBJECT (object),
506                 MY_OBJECT_PROP_HEIGHT (7),
507                 NULL);
508
509       And for getting, you would use:
510
511         int height;
512         g_object_get (G_OBJECT (object),
513                 MY_OBJECT_GET_PROP_HEIGHT (&height),
514                 NULL);
515
516       Note  however  that the type safety only works completely on GNU C com‐
517       pilers.  The code will compile on other compilers but with minimal type
518       safety.  For complete type safety it is useful to use the get/set meth‐
519       ods that are defined by using the ´export´ attribute.
520
521       To get bettery type safety on some of the property types, you can spec‐
522       ify the ´type´ attribute which will add casts where appropriate in code
523       dealing with this property.  This is especially useful for POINTER  and
524       OBJECT types.  But even for others.
525
526       You  can also override properties from parent objects (that is override
527       their implementation, not their attributes).  Do  this  by  adding  the
528       special  ´override´  attribute.  For example if the parent object had a
529       ´height´ property then you could override it by
530
531         private int height;
532         property INT height
533                (override)
534               set { self->_priv->height = g_value_get_int (VAL); }
535               get { g_value_set_int (VAL, self->_priv->height); };
536
537       Overriding is supported since gob 2.0.10.
538
539

METHODS

541       There is a whole array of possible methods.  The three normal,  "famil‐
542       iar"  method  types  are  private,  protected  and  public.  Public are
543       defined as normal functions with a prototype in the header file.   Pro‐
544       tected  methods  are defined as normal methods (which you can call from
545       other files), but their prototype is placed in the private header file.
546       Private  methods are defined as static functions with prototypes at the
547       top of the .c file.  Then there are signal, virtual and override  meth‐
548       ods.   More  on  those  later.  You can also define init and class_init
549       methods with a special definition if you want to add code to  the  con‐
550       structors  or  you  can just leave them out.  You can also not define a
551       body for a method, by just using ´;´ instead  of  a  body.   This  will
552       define  an empty function.  You can´t do this for non-void regular pub‐
553       lic, private or protected methods, however it is  acceptable  for  non-
554       void virtual, signal and override methods.
555
556       Function argument lists:
557
558       For all but the init and class_init methods, you use the following syn‐
559       tax for arguments.  The first argument can be just  "self",  which  gob
560       will  translate into a pointer to the object instance.  The rest of the
561       arguments are very similar to normal C arguments.  If the  typename  is
562       an  object  pointer  you  should  use the syntax defined above with the
563       words separated by ´:´
564       <type> <argument id>
565       or
566       <type> <argument id> (check <list of checks>)
567
568       The checks are glib type  preconditions,  and  can  be  the  following:
569       "null",  which  tests pointers for being NULL, "type" which checks GTK+
570       object pointers for being the right type, "<test> <number>" which tests
571       numeric  arguments  for  being  a  certain  value.   The  test can be a
572       <,>,<=,>= != or ==.  Example:
573
574         public int
575         foo (self,
576              int h (check > 0 < 11),
577              Gtk:Widget *w (check null type))
578
579
580       This will be the prototype of a function which has a  self  pointer  as
581       the  first  argument, an integer argument which will be checked and has
582       to be more then 0 and less then 11, and a pointer to a GtkWidget object
583       instance  and  it  is  checked for being null and the type will also be
584       checked.
585
586       Function attributes:
587
588       For method that aren't virtual, signal or override methods, and  aren't
589       init  or  class_init,  GLib  function  attribute  macros G_GNUC_PRINTF,
590       G_GNUC_SCANF, and G_GNUC_FORMAT can optionally be  included  after  the
591       argument  list.   Simply  include  an  ´attr´ keyword and the C code to
592       include in the file.  You have to include braces  and  anything  inside
593       the braces will be printed into the header file after the function dec‐
594       laration and before the trailing semicolon.  The braces themselves  are
595       not printed.  For example:
596
597         public void
598         print (self, const char *format (check null), ...)
599           attr {G_GNUC_PRINTF(2, 3)}
600
601
602       This  will produce a prototype which will generate a warning at compile
603       time if the contents of the format argument (argument number 2)  aren't
604       consistent  with  the types and number of the subsequent variadic argu‐
605       ments (the first of which is argument number 3).  Only one ´attr´  key‐
606       word  per  method  is  allowed.  If you have more than one attribute to
607       include, you should put them all within the braces.  Note that function
608       attributes were aded in version 2.0.16.
609
610       Error return:
611
612       Methods  which  have  a  return  value,  there also has to be something
613       returned if there is an error, such as if a precondition  is  not  met.
614       The  default  is  0,  casted to the type of the method.  If you need to
615       return something else then you can specify an ´onerror´  keyword  after
616       the  prototype  and  any  optional function attribute macros, and after
617       that a number, a token (an identifier) or a bit of C code  enclosed  in
618       braces  {}.   The braces will not be printed into the output, they just
619       delimit the string.  For example:
620
621         public void * get_something (self, int i (check >= 0)) onerror NULL {
622              ...
623         }
624
625       The onerror value is also used in overrides that have a  return  value,
626       in  case  there  isn´t  a parent method, PARENT_HANDLER will return it.
627       More about this later.
628
629       Default return:
630
631       Some signal and virtual methods have a return type.  But  what  happens
632       if  there  is no default handler and no one connects to a signal.  GOB2
633       will normally have  the  wrappers  return  whatever  you  specify  with
634       onerror or ´0´ if you haven´t specified anything.  You can also specify
635       a default return value with the keyword ´defreturn´.  It´s use is iden‐
636       tical  to  the use of onerror, and you can in fact use both at the same
637       time.  Example
638
639         virtual int get_some_int (self) onerror -1 defreturn 10 ;
640
641       That is an empty virtual method (in C++ terms a pure virtual).  If  you
642       never  specify  any handler for it in the derived children it will just
643       return 10.
644
645       Constructor methods:
646
647       There are two methods that handle the construction of an  object,  init
648       and  class_init.   You define them by just using the init or class_init
649       keyword with an untyped argument in the argument  list.   The  argument
650       will  be  usable  in your function as a pointer to your object or class
651       depending if it´s init or class_init.  For example:
652
653         init (self) {
654                 /* initialize the object here */
655                 self->a = 9;
656                 self->b = 9;
657         }
658
659         class_init (class) {
660                 /* initialize the class, this is rarely needed */
661                 class->blah = NULL;
662         }
663
664       The class_init function is very rarely needed  as  all  standard  class
665       initialization  is taken care of for you by gob itself.  The init func‐
666       tion should on the other hand be used whenever you need to construct or
667       initialize anything in the object to put it into a sane state.
668
669       Constructor, dispose, finalize methods:
670
671       Since 2.0.16, you can also easily add code to the object's constructor,
672       dispose, and finalize methods.  See GObject documentation on how  these
673       are run.  The code you add will be run before calling the parents func‐
674       tion for dispose and finalize, and after the parent function  for  con‐
675       structor.  The syntax is just like init and class_init.  For example:
676
677         constructor (self) {
678            /* constructor method */
679         }
680
681         dispose (self) {
682            /* dispose method */
683         }
684
685         finalize (self) {
686            /* finalize method */
687         }
688
689       You  can  also  just  override those methods as usual, but the above is
690       much easier and nearly as flexible.
691
692       Virtual methods:
693
694       Virtual methods are basically pointers in the class structure, so  that
695       one  can  override the method in derived methods.  That is to implement
696       the method in a derived class, you must then  use  an  override  method
697       (more  on  those  later).  They can be empty (if you put ´;´ instead of
698       the C code).  A wrapper will also be defined which  makes  calling  the
699       methods  he same as public methods.  This type of method is just a lit‐
700       tle bit "slower" then normal functions, but not  as  slow  as  signals.
701       You  define  them  by using "virtual" keyword before the prototype.  If
702       you put the keyword "private" right after the  "virtual"  keyword,  the
703       wrapper will not be a public method, but a private one.  You can do the
704       same with "protected" to make a protected wrapper.
705
706       Signals:
707
708       Signals are methods to which the user can bind other handlers and over‐
709       ride  the default handler.  The default handler is basically the method
710       body.  This is the most versatile and flexible type  of  a  method  and
711       also the slowest.  You need to specify a whole bunch of things when you
712       define a signal.  One thing is when the default handler  will  be  run,
713       first  or  last.  You specify that by "first" or "last" right after the
714       "signal" keyword.  Then you need  to  define  the  GObject  enum  types
715       (again  without  the  G_TYPE_  prefix).  For that you define the return
716       types and the types of arguments after the "self" pointer (not  includ‐
717       ing  the  "self" pointer).  You put it in the following syntax "<return
718       type> (<list of arguments>)".  If the return type  is  void,  the  type
719       should  be  "NONE", the same should be for the argument list.  The rest
720       of the prototype is the same as for other method types.  The  body  can
721       also  be empty, and also there is a public method wrapper which you can
722       use for calling the signal just like a public method.  Example:
723
724         signal first INT (POINTER, INT)
725         int do_something (self, Gtk:Widget *w (check null type), int length)
726         {
727              ...
728         }
729
730       or
731
732         signal last NONE (NONE) void foo (self);
733
734
735       If you don´t want the wrapper that emits the signal to be  public,  you
736       can  include  the  keyword  "private" after the "signal" keyword.  This
737       will make the wrapper a normal private method.  You  can  also  make  a
738       protected wrapper by using "protected" instead of "private".
739
740       If you don´t define a "first" or a "last", the default will be taken as
741       "last".
742
743       You can also add additional flags.  You do  this  just  like  with  the
744       argument  flags,  although  this  is probably very rare.  These are the
745       G_SIGNAL_* flags, and you can add them  without  the  G_SIGNAL_  prefix
746       into  a  parenthesis,  just after the "signal" keyword.  By default all
747       public signals are G_SIGNAL_ACTION.
748
749       Also gob2 creates a wrapper  macros  for  typesafe  signal  connection.
750       That  is you will be warned by the compiler if you pass a callback that
751       is not the correct prototype.  This will again only warn  you  on  gcc,
752       but  it  will  compile without warning on another compiler.  So as with
753       all the typesafety hacks in gob, it is  better  to  test  your  objects
754       under  gcc  to  get any warnings even if you are using a different com‐
755       piler in the end.
756
757       The methods that are created for you are:
758
759         <class_name>_connect__<signal_name> (<object>, <callback>, <data>)
760         <class_name>_connect_after__<signal_name> (<object>, <callback>, <data>)
761         <class_name>_connect_data__<signal_name> (<object>, <callback>, <data>,
762                                                   <destroy_notify>, <flags>)
763
764
765       These three functions correspond to the g_signal_connect, g_signal_con‐
766       nect_after  and g_signal_connect_data functions that you would normally
767       use, except they are for a specific  signal.   Also  do  note  the  two
768       underscores  between  the method name and the signal name.  For example
769       to connect the signal "foo" on the object "Test:Object" you would do:
770
771         test_object_connect__foo (object, callback, data);
772
773
774       To use BOXED in the signal arguments you need to tell gob which type of
775       boxed   argument   you  want  to  use.   For  this  you  can  just  add
776       BOXED_GTK_TYPE_STRING    instead     of     BOXED.      For     example
777       BOXED_GTK_TYPE_TREE_ITER  for  GtkTreeIter.   This  works since version
778       2.0.13.
779
780       Override methods:
781
782       If you need to override some method (a signal or a  virtual  method  of
783       some  class  in  the parent tree of the new object), you can define and
784       override method.  After the "override"  keyword,  you  should  put  the
785       typename  of  the  class  you are overriding a method from.  Other then
786       that it is the same as for other methods.  The "self" pointer  in  this
787       case  should  be  the type of the method you are overriding so that you
788       don´t get warnings during compilation.  Also to call the method of  the
789       parent class, you can use the PARENT_HANDLER macro with your arguments.
790       Example:
791
792         override (Gtk:Container) void
793         add (Gtk:Container *self (check null type), Gtk:Widget *wid (check null type))
794         {
795                 /* some code here */
796                 PARENT_HANDLER(self, wid);
797         }
798
799       If the function has a return value, then PARENT_HANDLER is  an  expres‐
800       sion  that  you  can  use.   It will return whatever the parent handler
801       returned, or the "onerror" expression if there was no parent handler.
802
803       Method names:
804
805       Inside the code, aliases are set for the methods,  so  that  you  don´t
806       have  to  type the class name before each call, just type self_ instead
807       of the name of the class.  So to call a method called blah,  you  would
808       use the name self_blah.  Example:
809
810         private int
811         foo (self)
812         {
813              return self->len;
814         }
815
816         private int
817         bar (self, int i)
818         {
819              return self_foo (self) + i;
820         }
821
822
823

MAKING NEW OBJECTS

825       You  should define a new method which should be a normal public method.
826       Inside this method, you can use the GET_NEW macro that is  defined  for
827       you  and  that will fetch a new object, so a fairly standard new method
828       would look like:
829
830         public GObject *
831         new (void) {
832              GObject *ret = GET_NEW;
833              return G_OBJECT (ret);
834         }
835
836
837       You should not a subtle peculiarity of the  GObject  system  here.   If
838       there  is any code inside the G_OBJECT macro argument, it will get exe‐
839       cuted multiple times.  This means that things such as G_OBJECT(GET_NEW)
840       would  actually  create  4 objects, leaking 3 of them.  A good rule (as
841       with anywhere in C) is to be careful with all macros.
842
843

SELF REFERENCES

845       Self alias casts:
846
847       There are some standard casts defined for you.  Instead  of  using  the
848       full  macros  inside  the  .c  file,  you  can  use  SELF,  IS_SELF and
849       SELF_CLASS.  Using these makes it easier to for  example  change  class
850       names around.
851
852       Self alias types:
853
854       There are also the Self and SelfClass types inside your .c file.  These
855       serve the same function as the above, they make it easier to  type  and
856       easier to change typenames around which can help a lot during prototyp‐
857       ing stage.  However you should note that the Self type  should  not  be
858       used  in  function  prototypes  as  one of the arguments or as a return
859       value type.  This is because this is a simple C typedef which  is  only
860       available  inside  your  .c  file and not in the header files.  You can
861       disable both the self casting macros and the self type aliases by pass‐
862       ing --no-self-alias to gob.
863
864

DEALING WITH DIFFERENT GOB VERSIONS

866       Defines:
867
868       In  your  generated  C  file, you can use the defines GOB_VERSION_MAJOR
869       GOB_VERSION_MINOR and GOB_VERSION_PATCHLEVEL if you wish to for example
870       use  a  feature that is only available in some newer gob version.  Note
871       however that you can only use these defines in the C code  portions  of
872       your .gob file, and #ifdef´s cannot span multiple functions.  Check the
873       BUGS section for more on using the C preprocessor and gob.
874
875       Minimum version requires:
876
877       You can also make your .gob file require at least  certain  version  of
878       gob.   You do this by putting ´requires x.y.z´ (where x.y.z is the ver‐
879       sion number) outside of any C block,  comment  or  class,  usually  you
880       should  make  this  the first line in the file or close to the top.  If
881       gob finds this and the version of gob used to compile the code is lower
882       then  that  listed in the require, gob will generate an error and exit.
883       For example to require that gob2 version 2.0.0 or  higher  be  used  to
884       compile a file, put this at the top of that file:
885
886         requires 2.0.0
887
888
889

CREATING NEW ENUM, FLAGS and ERROR TYPES

891       You can create new GObject ENUM, FLAGS and GError types for use in your
892       classes easily.  Glib includes some utilities for handling these,  how‐
893       ever  it may be cleaner to use the below specified way in your classes.
894       It also then doesn´t require any Makefile setup.   Make  sure  this  is
895       defined  in  the  same  section as the class, that is not in any of the
896       ´%?{´ ´%}´ sections.
897
898       You use the keywords ´enum´ ´flags´ and ´error´ as you  would  use  the
899       ´class´ keyword.  Then you give a prefix for the values in the enumera‐
900       tion.  Then you define a list of values just like  in  C.   For  ´enum´
901       types  you  can  also specify the values assigned to each string.  Then
902       you specify the type in the standard gob  style  of  specifying  types.
903       Here are a few examples of all of these:
904
905         enum LAME_CLIENT {
906               IS_CONNECTED,
907               NONE = 9,
908               LAST
909         } Test:Enum;
910
911         flags BUGA_BUGA {
912               ONE,
913               TWO,
914               MANY,
915         } Some:Flags;
916
917         error TEST_OBJECT_ERROR {
918               BAD_THIS,
919               BAD_THAT
920         } Test:Object:Error;
921
922
923       This  will for example define an enum that is equivalent to the follow‐
924       ing C code:
925
926         typedef enum {
927               LAME_CLIENT_IS_CONNECTED,
928               LAME_CLIENT_NONE = 9,
929               LAME_CLIENT_LAST
930         } TestEnum;
931
932
933

C++ MODE

935       There is a C++ mode so that gob creates C++  compiler  friendly  files.
936       You need to use the --for-cpp argument to gob.  This will make the gen‐
937       erated file have a .cc instead of a .c extension,  and  several  things
938       will  be  adjusted  to  make it all work for a C++ compiler.  One thing
939       that will be missing is an alias to the new  method,  as  that  clashes
940       with  C++,  so  instead  you´ll have to use the full name of the method
941       inside your code.  Also note that gob does not use  any  C++  features,
942       this  option  will just make the generated code compile with a C++ com‐
943       piler.
944
945

OVERRIDING THE GET_TYPE METHOD

947       The get_type is not really a method, but a function  which  initializes
948       your  object.   Recently  objects  appeared which require you to make a
949       custom get_type function.  So it is possible to override this function.
950       To  do  so,  just  define  a new public method called get_type, with no
951       arguments.  Example:
952
953         public GType
954         get_type (void)
955         {
956            /* code goes here */
957            return some_type;
958         }
959
960
961

INTERFACES

963       Currently gob will only allow you to  implement  interfaces  (that  is,
964       define  new  classes which implement an interface) and doesn´t yet have
965       support for making new interfaces, but this  will  be  coming  at  some
966       point in the future.
967
968       To define a class that implements an interface add a class flag ´inter‐
969       face´ with the type name of the interface  as  an  argument.   Then  to
970       implement  a  specific  method  of  the  interface, just add ´interface
971       <typename>´ before the method definition.  The method can, and probably
972       should be, private.
973
974       The  following  example  implements  a  new object, that implements the
975       Gtk:Tree:Model interface and implements the get_flags  method  of  that
976       interface.   Do  note that except for standard (GTK+ and glib) specific
977       interfaces which seem to have a non-standard  name  for  the  interface
978       structure,  the  structure should end with and Iface, if you are imple‐
979       menting an interface.  That is for example for the Gtk:Tree:Model,  the
980       structure  containing  the table of methods should be named GtkTreeMod‐
981       elIface.
982         class Some:Object from G:Object
983                 (interface Gtk:Tree:Model)
984         {
985                 /* function implemented for the Gtk:Tree:Model interface */
986                 interface Gtk:Tree:Model
987                 private GtkTreeModelFlags
988                 get_flags (Gtk:Tree:Model *self (check null type))
989                 {
990                      /* Here would be the implementation */
991                      return (GtkTreeModelFlags)0;
992                 }
993         }
994
995
996       If you want to implement multiple interfaces just list more class  flag
997       lines as follows:
998
999         class Some:Object from G:Object
1000                 (interface Gtk:Tree:Model)
1001                 (interface Gtk:Editable)
1002         {
1003                 /* ... */
1004         }
1005
1006
1007

DIRECT BonoboObject SUPPORT

1009       If  you  want to build a BonoboObject class gob2 has direct support for
1010       these.  Just create a new object that derives from Bonobo:Object.  Then
1011       use a "BonoboObject" class flag with the interface name as an argument.
1012       The interface name should be as you would type it in C,  that  is  with
1013       underscores  as  namespace separators.  Then you add the methods (using
1014       exact same names as in the idl file) and prepend those methods  with  a
1015       BonoboObject  keyword.   For  example  imagine  you  have  an interface
1016       GNOME/Foo/SomeInterface, with a  method  fooBar  that  takes  a  single
1017       string:
1018
1019         class Foo:Some:Interface from Bonobo:Object
1020           (BonoboObject GNOME_Foo_SomeInterface) {
1021
1022                 BonoboObject
1023                 private void
1024                 fooBar (PortableServer_Servant servant,
1025                         const CORBA_char *string,
1026                         CORBA_Environment *ev)
1027                 {
1028                         Self *self = SELF (bonobo_object_from_servant (servant));
1029
1030                         /* your code here */
1031                 }
1032
1033                 /* rest of class */
1034         }
1035
1036       Note  that  the  implementation  method  can be private, in fact that´s
1037       probably a good idea to do.  It won´t work to make this  a  signal,  it
1038       can  however  be  a virtual.  Note that the method prototype must match
1039       the one from the interface header file, or you will get a  bad  assign‐
1040       ment  warning.  You should check the header file generated by orbit-idl
1041       and see the epv structure for the correct prototypes if you can´t  fig‐
1042       ure them out from the idl itself.  Also note that the first argument is
1043       not "self", but the servant and you must use bonobo_object_from_servant
1044       function to get the actual object pointer.
1045
1046

DIRECT LIBGLADE SUPPORT

1048       Gob  can  simplify  writing a libglade class.  Just create a new object
1049       that derives from a GtkContainer widget.  Then use a  "GladeXML"  class
1050       flag  with  the  glade  file  name, root widget and optional domain  as
1051       arguments between double quotes.  For example:
1052
1053       class My:Glade from Gtk:Window (GladeXML "gob-libglade.glade" "root")
1054       {
1055         ....
1056       }
1057
1058       Note however that then "gob-libglade.glade" would have  to  be  in  the
1059       current directory.  You could specify a path, but that may not work for
1060       all installations.  You can replace the glade filename with a token  to
1061       be used in the generated .c file and you can then have a macro with the
1062       filename, as follows:
1063
1064       class My:Glade from Gtk:Window (GladeXML GLADE_FILE "root")
1065       {
1066         ....
1067       }
1068
1069       And somewhere in your header files you would have
1070
1071       #define GLADE_FILE "/path/to/file.glade"
1072
1073
1074       You can declare widgets as data members by adding a 'GladeXML'  to  the
1075       definition.
1076
1077       private Gtk:Button * button1 GladeXML;
1078
1079       This will automatically set the "button1" from the GladeXML file.
1080
1081       All  signals  created  with  glade  are  automatically connected if you
1082       defined those class methods in your  class.   For  example  suppose  in
1083       glade  that  we  set  the  "connect" signal on button1 to go to on_but‐
1084       ton1_clicked, then in our gob file we can just write:
1085
1086       public void
1087       on_button1_clicked(self, GtkButton * button)
1088       {
1089       }
1090
1091
1092       See the examples directory for a full example.  Note that this  feature
1093       requires version at least 2.0.12.
1094
1095
1096

IDENTIFIER CONFLICTS

1098       Gob  will need to define some local variables and functions in the gen‐
1099       erated files, so you need to take some precaution not to conflict  with
1100       these.  The general rule of thumb is that all of these start with three
1101       underscores.  There is one, "parent_class" which doesn´t  because  it´s
1102       intended for use in your code.  For virtuals or signals, you cannot use
1103       the identifier __parent__ which is used for the parent of  the  object.
1104       You should actually never access __parent__ either as it not guaranteed
1105       that it will stay named this way.  Data members cannot be named  __par‐
1106       ent__ nor _priv.  For methods, you cannot use the identifiers "init" or
1107       "class_init" unless you mean the constructor  methods.   You  shouldn´t
1108       generally  use 3 underscores even in override method argument lists and
1109       virtual and signal method names as it might confuse the  PARENT_HANDLER
1110       macro.   In  fact avoiding all names with three underscores is the best
1111       policy when working with gob.
1112
1113       There are a couple of defines which you shouldn´t be redefining in  the
1114       code or other headers.  These are SELF, IS_SELF, SELF_CLASS, SELF_TYPE,
1115       ARG, VAR, PARENT_HANDLER, GET_NEW, GOB_VERSION_MAJOR, GOB_VERSION_MINOR
1116       and GOB_VERSION_PATCHLEVEL.
1117
1118       As for types, there are Self and SelfClass types which are only defined
1119       in your source files.  Their generation (just like  the  generation  of
1120       the SELF macros) can be turned off, see command line options.
1121
1122

USING GTK-DOC STYLE INLINE DOCUMENTATION

1124       If you want to use gtk-doc style inline documentation for your objects,
1125       you can do one of two things.  First, you could include the inline doc‐
1126       umentation comments in your %{ %} section which will then be put verba‐
1127       tim into the output source file.  This is the way you  should  use  for
1128       functions you define outside of the class.
1129
1130       For  class methods, you should use a gtk+ style comment, however it can
1131       be indented any number of tabs or spaces and  you  can  use  the  short
1132       method  name  without  the  type prefix.  Gob will automatically try to
1133       extract these and translate to full names and put them  in  the  output
1134       source file.  An example would be:
1135
1136         class Gtk:Button:Example from Gtk:Button {
1137                 /**
1138                  * new:
1139                  *
1140                  * Makes a new #GtkButtonExample widget
1141                  *
1142                  * Returns: a new widget
1143                  **/
1144                 public
1145                 GtkWidget *
1146                 new(void)
1147                 {
1148                         return (GtkWidget *)GET_NEW;
1149                 }
1150         }
1151
1152       If  the  function  you are documenting is a signal or a virtual then it
1153       will be documenting the wrapper that starts that  virtual  function  or
1154       emits that signal.
1155
1156

DEALING WITH CIRCULAR HEADERS

1158       Sometimes  you may need to use an object of type MyObjectA in the MyOb‐
1159       jectB class and vice versa.  Obviously you can´t  include  headers  for
1160       both.   So  you need to just declare the typedef in the header of A for
1161       B, and the other way around as well.  The headers generated  include  a
1162       protecting  define  before it declares the typedef.  This define is the
1163       __TYPEDEF_<upper case object name>__.  So  inside  my-object-a.h  there
1164       will be this:
1165
1166         #ifndef __TYPEDEF_MY_OBJECT_A__
1167         #define __TYPEDEF_MY_OBJECT_A__
1168         typedef struct _MyObjectA MyObjectA;
1169         #endif
1170
1171       Now  instead  of  including  my-object-a.h in the header section of my-
1172       object-b.gob, just copy the above code there and you´re set  for  using
1173       MyObjectA as a type in the method parameters and public types.
1174
1175       Another  way  to  get out of this problem is if you can use those types
1176       only in the private members, in which case they won´t be in the  gener‐
1177       ated public header.
1178
1179

BUILDING WITH MAKE

1181       If  you  are  using  normal  makefiles, what you need to do is to add a
1182       generic rule for .gob files.  So you would include the following in the
1183       Makefile  and then just use the .c and .h files as usual (make sure the
1184       space before the ´gob2´ is a tab, not spaces):
1185
1186         %.c %.h %-private.h: %.gob
1187                 gob2 $<
1188
1189
1190

BUILDING WITH AUTOCONF and AUTOMAKE

1192       This is a little bit more involved.  Basically the first thing to do is
1193       to  check for GOB2 in your configure.in file.  You can use the supplied
1194       m4 macro which will also check  the  version  of  gob.   Basically  you
1195       include this:
1196
1197         GOB2_CHECK([2.0.0])
1198
1199       This  will replace @GOB2@ in your makefiles with the full path of gob2.
1200       Thus when adding the generic rule to your Makefile.am file,  it  should
1201       look like:
1202
1203         %.c %.h %-private.h: %.gob
1204                 @GOB2@ $<
1205
1206
1207       For  Makefile.am  you  have  to set up a couple more things.  First you
1208       have to include the generated .c and .h files into BUILT_SOURCES  vari‐
1209       able.  You have to include both the .gob and the .c and .h files in the
1210       SOURCES for your program.
1211
1212

PREVENTING SPURIOUS BUILDS

1214       When nothing has changed you might not really want  to  rebuild  every‐
1215       thing  and  gob  provides  options  --no-touch (since 2.0.13) and --no-
1216       touch-headers to avoid this.  When working with build systems  such  as
1217       automake  you  have  to be more careful as just using those options can
1218       cause automake to get confused and you will need to use something  like
1219       the following:
1220
1221         foo_SOURCES = foo.gob foo.gob.stamp foo.c foo.h foo-private.h
1222         BUILT_SOURCES = foo.gob.stamp
1223         MAINTAINERCLEANFILES = foo.gob.stamp
1224
1225         %.gob.stamp: %.gob
1226                 @GOB2@ --no-touch $<
1227                 @touch $@
1228
1229
1230

DEBUGGING

1232       GOB  does  several  things to make debugging the code easier.  First it
1233       adds preprocessor commands into the output c file  that  point  to  the
1234       correct  places in your .gob input file.  However sometimes there might
1235       be some bigger confusion and this is just not helpful.   In  this  case
1236       you  will probably want to have gcc point you directly at the generated
1237       files.  For this use the --no-lines command line  option.   You  should
1238       also  note  that these commands are not generated for the public header
1239       file at all.  If there is an error  which  points  you  to  the  public
1240       header  file,  make sure you fix this error in the .gob file, otherwise
1241       your changes will not have any effect after gob recompiles the  sources
1242       again.
1243
1244       Sometimes  you  might  want  to  know  which method you are in for some
1245       debugging output.  GOB will define  __GOB_FUNCTION__  macro,  which  is
1246       just a string constant with a pretty name of the method.
1247
1248

M4 SUPPORT

1250       It is possible to have your .gob file also preprocessed by m4.  This is
1251       useful if you have a lot of files and you´d  like  to  have  some  pre‐
1252       processor  put in some common features.  All you have to do is add --m4
1253       to the command line of gob2 and gob2 will first run your  file  through
1254       m4.   You can print the directory that is searched for m4 files by run‐
1255       ning "gob2 --m4-dir"
1256
1257       All the arguments after --m4 will be passed to m4 itself, so it has  to
1258       be  the last gob2 argument on the command line.  This way you can spec‐
1259       ify arbitrary options to pass to m4.
1260
1261

BUGS

1263       The lexer does not actually parse the C code, so  I´m  sure  that  some
1264       corner  cases  or maybe even some not so corner cases of C syntax might
1265       confuse gob completely.  If you find any, send me the source that makes
1266       it  go  gaga  and I´ll try to make the lexer try to handle it properly,
1267       but no promises.
1268
1269       Another thing is that  gob  ignores  preprocessor  macros.   Since  gob
1270       counts braces, the following code won´t work:
1271
1272         #ifdef SOME_DEFINE
1273         if(foo) {
1274         #else
1275         if(bar) {
1276         #endif
1277                 blah();
1278         }
1279
1280       To make this work, you´d have to do this:
1281
1282         #ifdef SOME_DEFINE
1283         if(foo)
1284         #else
1285         if(bar)
1286         #endif
1287         {
1288                 blah();
1289         }
1290
1291       There is no real good way we can handle this without parsing C code, so
1292       we probably never will.  In the future, I might add #if 0 as a  comment
1293       but  that´s about as far as I can really take it and even that is prob‐
1294       lematic.  Basically, if you use gob, just don´t use the C  preprocessor
1295       too extensively.  And if you use it make sure that you do not cross the
1296       boundaries of the C code segments.
1297
1298       Comments will not get through to the generated files  unless  inside  C
1299       code.   This  is not the case for gtk-doc style comments which are sup‐
1300       ported.
1301
1302       The short name aliases are actually implemented as  pointers  to  func‐
1303       tions.   Thus  if  you  want to get the pointer of a function using the
1304       short name alias you can´t use the ´&´.  Thus:
1305
1306         void (*foo)(Self *);
1307
1308         /* this will NOT work */
1309         foo = &self_short_name;
1310
1311         /* this will work */
1312         foo = self_short_name;
1313
1314         /* Both of these will work */
1315         foo = &my_class_long_name;
1316         foo = my_class_long_name;
1317
1318
1319

AUTHOR

1321       George Lebl <jirka@5z.com>
1322
1323       GOB2 Homepage: http://www.jirka.org/gob.html
1324
1325
1326
1327                                  GOB2 2.0.16                          GOB2(1)
Impressum