GOB \- The GTK+ Object Builder
.SH SYNOPSIS
.PP
-.B gob
+.B gob [-?] [-h] [-w] [--exit-on-warn] [--no-exit-on-warn] [--for-cpp]
+[--no-touch-headers] file
.SH DESCRIPTION
.PP
GTK+ Object Builder is a simple preprocessor for easily creating
GTK+ objects. It does not parse any C code and ignores any C errors. It
is in spirit similar to things like lex or yacc.
+.SH OPTIONS
+.PP
+.TP
+.B -?
+.TP
+.B -h
+Display a simple help screen.
+.TP
+.B -w
+.TP
+.B --exit-on-warn
+Exit with an errorcode even when you encounter a warning.
+.TP
+.B --no-exit-on-warn
+Exit with an error only on errors, not on warnings, this is the default.
+.TP
+.B --for-cpp
+Generate C++ code.
+.TP
+.B --no-touch-headers
+Don't touch the generated header file unless it really changed, this avoids
+spurious rebuilds, but can confuse some make systems (automake in particular),
+so it is not enabled by default.
+
+
.SH TYPENAMES
.PP
-Because we need to parse out different parts of the typename,
-sometimes you need to specify the typename with some special syntax.
-Types are specified in capitalized form and words are separated by ':'.
-The first word of the type (which can be empty) is the "namespace". This
-fact is for example used for the type checking macro. For "Gtk:New:Button",
-the macro will be GTK_IS_NEW_BUTTON. This format of typenames is used in
-the class declaration header and for method argument types.
+Because we need to parse out different parts of the typename, sometimes you
+need to specify the typename with some special syntax. Types are specified in
+capitalized form and words are separated by ':'. The first word of the type
+(which can be empty) is the "namespace". This fact is for example used for the
+type checking macro and the type macro. For "Gtk:New:Button", the macros will
+be GTK_IS_NEW_BUTTON and GTK_TYPE_NEW_BUTTON. This colon separated format of
+typenames is used in the class declaration header and for method argument
+types.
-.SH OUTPUT FILE NAMES
+.SH OUTPUT FILES
.PP
The filenames are created from the typename. The words are
separated by '-' and all in lower case. For example for an object named
"Gtk:New:Button", the files are gtk-new-button.c and gtk-new-button.h.
+The header file is created to be human readable and to be used as a
+reference to the object. The .c source file is not created as a human
+readable source and is littered with #line statements, which make the
+compiler attempt to point you to the right line in your .gob file in
+case of parsing errors. The output should not be editted by hand, and
+you should only edit the .gob file.
.SH INCLUDING NORMAL C CODE IN THE OUTPUT FILES
.PP
-To include some code directly in the output C file begin with
-'%{' on an empty line and end the code with a '%{' on an empty line. To
+To include some code directly in the output C file begin with '%{'
+on an empty line and end the code with a '%}' on an empty line. To
put the code in the output header file, start the code with a '%h{'.
For example:
.nf
%h{
+ /* will be included in the header */
void somefunc(int i);
%}
+
%{
+ /* will be included in the C file */
void somefunc(int i)
{
- /* some code */
+ /* some code */
}
%}
typename of the class you are overriding a method from. Other then that
it is the same as for other methods. The "self" pointer in this case
should be the type of the method you are overriding so that you don't
-get warnings during compilation. Example:
+get warnings during compilation. Also to call the method of the parent
+class, you can use the PARENT_HANDLER macro with your arguments. Example:
.nf
override (Gtk:Container) void
add (Gtk:Container *self (check null type), Gtk:Widget *wid (check null type))
{
- ...
+ /* some code here */
+ PARENT_HANDLER(self, wid);
}
.fi
.PP
Calling methods:
.PP
-Inside the code, defines are set for the methods, so that you don't
-have to type the class name before each call. Example:
+Inside the code, pointers are set for the methods, so that you don't
+have to type the class name before each call, just the name of the method.
+Example:
.nf
private int
.fi
+.SH C++ MODE
+.PP
+There is a C++ mode so that gob creates C++ compiler friendly files. You need
+to use the --for-cpp argument to gob. This will make the generated file have
+a .cc instead of a .c extention, and several things will be adjusted to
+make it all work for a C++ compiler. One thing that will be missing is an
+alias to the new method, as that clashes with C++, so instead you'll have to
+use the full name of the method inside your code. Also note that gob does
+not use any C++ features, this option will just make the generated code
+compile with a C++ compiler.
+
.SH BUGS
.PP
The generated header file is included as the first file in the .c file, no
completely. If you find any, send me the source that makes it go gaga and I'll
try to make the lexer try to handle it properly, but no promises.
.PP
-Gob uses a lot of #define's so sometimes it can confuse your code. One way
-to make sure you don't get confused is not to use method names for absolutely
-anything else since gob will use defines of the type:
+Another thing is that gob ignores preprocessor macros. Since gob counts
+braces, the following code won't work:
+.nf
+
+ #ifdef SOME_DEFINE
+ if(foo) {
+ #else
+ if(bar) {
+ #endif
+ blah();
+ }
+
+.fi
+To make this work, you'd have to do this:
.nf
- #define method_name class_name_method_name
+ #ifdef SOME_DEFINE
+ if(foo)
+ #else
+ if(bar)
+ #endif
+ {
+ blah();
+ }
.fi
-For your class code.
+There is no real good way we can handle this without parsing C code, so we
+probably never will. In the future, I might add #if 0 as a comment but
+that's about as far as I can really take it and even that is problematic.
+Basically, if you use gob, just don't use the C preprocessor too extensively.
.SH AUTHOR
.PP
projects / gob-dx.git / blobdiff