This manual is for GNU Gengen (version 1.4.2, 31 August 2010). GNU Gengen (GENerator GENerator), a tool to generate a C++ class (or C functions) for generating text, based on a template file with parameters, after substituting some parameters. This can be used in code generators.
Copyright © 2002–2007 Lorenzo Bettini.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”
GNU Gengen (GENerator GENerator) is a tool that, starting from a parameterized text, called template, generates a text generator that can substitute parameters with values.
This manual is written for C++ and C programmers, specifically the
lazy ones ;-). If you've written any non-trivial code generator,
you probably had to write many cout << or printf lines of
code, mixing fixed text to be generated and parts based on the value of
some variables. If the text to be generated is full of parts that have
to be substituted at run-time, your code will end up containing many
instructions that print constant strings and variables; this will tend
to make the text to be generated unclear and thus also more difficult to
maintain. Gengen can save you from this work, leaving you free to
focus on the text that has to be generated.
Indeed the code to be generated will be written in a separated file (that we call template file) that can contain variable parts (that we call parameters or variables); Gengen will generate the generator for you and this generator will also accept the values that will be substituted in the output.
I started to develop Gengen while maintaining GNU Gengetopt1, since I had to generate a big amount of code and I found it quite hard to write code to generate it, since the program ended up being full of many printf! That code was unclear and quite hard to maintain.
At the moment Gengen generates C++ or C code; however other target languages are under development (e.g., Java).
NOTICE: Gengen uses code generated by Gengen itself :-)
GNU Gengen is free software; you are free to use, share and modify it under the terms of the GNU General Public License that accompanies this manual.
The code that Gengen generates is also free software; however it is licensed with a simple all-permissive license instead of the GPL or LGPL. You are free to do anything you like with the generated code, including incorporating it into or linking it with proprietary software.
See the file INSTALL for detailed building and installation instructions; anyway if you're used to compiling Linux software that comes with sources you may simply follow the usual procedure, i.e. untar the file you downloaded in a directory and then:
cd <source code main directory>
./configure
make
make install
Note: unless you specify a different install directory by
--prefix option of
configure (e.g. ./configure --prefix=<your home>),
you must be root to run make install.
Files will be installed in the following directories:
executables/prefix/bin
docs/prefix/share/doc/gengen
examples/prefix/share/doc/gengen/examples
additional files/prefix/share/gengen
Default value for prefix is /usr/local
but you may change it with --prefix
option to configure.
You can download it from GNU's ftp site: ftp://ftp.gnu.org/gnu/gengen or from one of its mirrors (see http://www.gnu.org/prep/ftp.html).
I do not distribute Windows binaries anymore; since, they can be easily built by using Cygnus C/C++ compiler, available at http://www.cygwin.com. However, if you don't feel like downloading such compiler, you can request such binaries directly to me, by e-mail (find my e-mail at my home page) and I can send them to you.
Archives are digitally signed by me (Lorenzo Bettini) with GNU gpg (http://www.gnupg.org). My GPG public key can be found at my home page (http://www.lorenzobettini.it).
You can also get the patches, if they are available for a particular release (see below for patching from a previous version).
This project's git repository can be checked out through the following clone instruction2:
git clone git://git.savannah.gnu.org/gengen.git
Further instructions can be found at the address:
http://savannah.gnu.org/projects/gengen.
And the git repository can also browsed on-line at
http://git.savannah.gnu.org/cgit/gengen.git.
Please note that this way you will get the latest development sources of Gengen, which may also be unstable. This solution is the best if you intend to correct/extend this program: you should send me patches against the latest git repository sources.
If, on the contrary, you want to get the sources of a given release,
through git, say, e.g., version X.Y.Z, you must specify the tag
rel_X_Y_Z.
When you compile the sources that you get from the git repository,
before running the configure and make commands, for the
first time, you must run the command:
sh autogen.sh
This will run the autotools commands in the correct order, and also copy
possibly missing files. You should have installed recent versions of
automake and autoconf in order for this to
succeed.
Instead of running autogen.sh another option is to run
autoreconf -i
Gengen has been developed under GNU/Linux, using gcc (C++), and bison (yacc) and flex (lex), and ported under Win32 with Cygnus C/C++compiler, available at http://www.cygwin.com. I used the excellent GNU Autoconf and GNU Automake. I also used Autotools (ftp://ftp.ugcs.caltech.edu/pub/elef/autotools) which creates a starting source tree (according to GNU standards) with autoconf, automake starting files.
Finally I used GNU gengetopt (http://www.gnu.org/software/gengetopt), for command line parsing.
Actually, you don't need all these tools above to build gengen because I provide generated sources, unless you want to develop gengen.
If you downloaded a patch, say gengen-1.3-1.3.1-patch.gz (i.e., the patch to go from version 1.3 to version 1.3.1), cd to the directory with sources from the previous version (gengen-1.3) and type:
gunzip -cd ../gengen-1.3-1.3.1.patch.gz | patch -p1
and restart the compilation process (if you had already run configure a simple make should do).
Say you are writing a C/C++ program and at some point your program has to generate the following code:
if (i < 10)
printf("the value of i is %d", i);
It is not so difficult to write this piece of C++ code:
cout << "if (i < 10)" << endl;
cout << " printf(\"the value of i is %d\", i);" << endl;
or the C code:
printf("if (i < 10)\n");
printf(" printf(\"the value of i is %%d\", i);\n");
provided that you remember to escape the " (and in the
C code, also the %).
Suppose now that the previous piece of code has to be generated many
times by your program, and every time instead of i another
symbol has to be generated (decided at run time). In this case,
supposing that this value is contained in a variable symb,
the code for generating this code would be a little bit more
complex:
cout << "if (" << symb << "< 10)" << endl;
cout << " printf(\"the value of " << symb << " is %d\", "
<< symb << ");" << endl;
And the C version would be even more obfuscated.
Probably you didn't even realize that you forgot to leave
a space before the < 10; basically this is due to the fact
that this piece of code mixes the code that has to be generated
with the code that generates it, and this tends to make this part
of program less easy to maintain. Especially if some day you
have to change the code that has to be generated, you'll have
to act on this part of the program, and probably you'll have to
execute some tests in order to be sure that you did it right.
If the code that you have to generate is a slightly more complex, the task may easily become a pain in the neck!
Wouldn't it be nice if you could write the code to be generated in a separate file, let's call it template, say test1.cc_skel this way
if (@i@ < 10)
printf("the value of @i@ is %d", @i@);
and have a tool that generates a generator, that you
can instantiate at run-time with the value that has to be substituted to
the parameter i? If such a tool existed, and it generated
a file test1_c.h with a C struct test1_gen_struct, then
you could write simply this code, in another file, say
test1_gen_c.c:
#include <stdio.h>
#include "test1_c.h"
int
main()
{
struct test1_gen_struct gen_struct;
gen_struct.i = "foo";
generate_test1(stdout, &gen_struct, 0);
printf("\n");
gen_struct.i = "bar";
generate_test1(stdout, &gen_struct, 0);
printf("\n");
return 0;
}
Alternatively, if it generated a file test1.h with a C++ class
test1_gen_class, then you could write simply this code, in
another file, say test1_gen.cc:
#include <iostream>
using std::cout;
using std::endl;
#include "test1.h"
int
main()
{
test1_gen_class gen_class;
gen_class.set_i("foo");
gen_class.generate_test1(cout);
cout << endl;
gen_class.set_i("bar");
gen_class.generate_test1(cout);
cout << endl;
return 0;
}
and when you run it you would obtain the expected output:
if (foo < 10)
printf("the value of foo is %d", foo);
if (bar < 10)
printf("the value of bar is %d", bar);
Well, Gengen does right this! Now the code that has to
be generated and the code that generates it are separated and they can
be maintained more easily: if you want to change the code that has to be
generated you act on the file test1.cc_skel; alternatively, say
you need to change the value that will be substituted for i, you
just change the file test1_gen.cc or test1_gen_c.c.
Notice that the method generate_test1 accepts an output stream
(indeed in this example the standard output stream cout is used),
thus the stream abstraction facilities can be exploited. Similarly, the
C function generate_test1 accepts a FILE*, so you can use
the C file abstraction.
Indeed in order to generate the C++ file test1.h with the class
test1_gen_class, I simply had to run the following command:
gengen -i test1.cc_skel --file-name test1.h --gen-name test1
and in order to generate the C file test1_c.h with the structure
test1_gen_struct, I simply had to run the following command:
gengen -i test1.cc_skel --file-name test1_c.h --gen-name test1 \
--output-format=c
If I caught your attention and you would like to know more about these options and more advanced features of Gengen, I hope you read on :-)
We've run Gengen, and used it to produce a really spiffy, if rather pointless, program. Now we'll go back and look at things in more detail.
The input file for Gengen is basically any text file, where some parts
are interpreted differently, namely symbols enclosed in @. We
call this input file a template and the symbols enclosed in
@ parameters (or variables):
This is @name@ generated by the program @progname@.
The code of @progname@ that generated this text was
generated by @generator@ version @version@, made by
Lorenzo Bettini <foobar@@foo.org>.
First all notice that, since @ is a special
character, if you really want it to appear in the generated text you
have to repeated, as in the e-mail address foobar@@foo.org.
If this text is stored in the file example_text.text_skel and I process it with the following command:
gengen -i example_text.text_skel
--file-name example_text_c.h --gen-name example_text
--output_format=c
the struct example_text_gen_struct (option
--gen-name example_text) will be generated in the file
example_text_c.h (option --file-name example_text_c.h).
This struct will have a field for each single parameter, with the same
name of the parameter and type const char *. For in instance in
this example it will contain the fields name, progname,
generator and version. These can be used to set the
string that will be substituted at run-time for the corresponding name
in the input file (Notice that otherwise the empty string is assumed).
Notice that the fields of the structure are not initialized (i.e., they contain random values) thus we suggest to always initialize the structure with the following generated function:
void
init_example_text_gen_struct(struct example_text_gen_struct *record);
Once these values are set, the function
void generate_example_text(FILE *stream,
example_text_gen_struct *record, unsigned int indent)
can be called in order to generate the text with
substitutions (using the values of the passed struct) into the stream
stream. The parameter indent is useful to specify an
indentation in the generated text.
Alternatively, one can use the following function (even with a non
initiliazed struct) specifying the values for each field (notice the
p after generate):
void
generatep_example_text(FILE *stream, unsigned int indent,
const char *generator, const char *name, const char *progname,
const char *version);
The following example uses the generated struct in order to
generate the text twice; the second time, the name of the
parameter name is changed, and the indentation is set to
23:
#include <stdio.h>
#include "example_text_c.h"
int
main()
{
struct example_text_gen_struct gen_struct;
init_example_text_gen_struct(&gen_struct);
gen_struct.name = "an example";
gen_struct.progname = "example_text_gen";
gen_struct.generator = "Gengen";
gen_struct.version = "1.0";
generate_example_text(stdout, &gen_struct, 0);
printf("\n");
printf("\n");
gen_struct.name = "another example";
printf(" ");
generate_example_text(stdout, &gen_struct, 2);
printf("\n");
return 0;
}
The output of this program will be as expected:
This is an example generated by the program example_text_gen.
The code of example_text_gen that generated this text was
generated by Gengen version 1.0, made by
Lorenzo Bettini <[email protected]>.
This is another example generated by the program example_text_gen.
The code of example_text_gen that generated this text was
generated by Gengen version 1.0, made by
Lorenzo Bettini <[email protected]>.
Now, since C lacks the (wonderful :-) stream abstraction that permits
creating a stream that writes into a string (such as the
ostringstream), two additional functions are provided in the
generated file, that return a (malloced) string instead of
generating the output to a file (they correspond to the two generate
functions seen above):
char *
genstring_example_text(struct example_text_gen_struct *record,
unsigned int indent);
char *
genstringp_example_text(unsigned int indent,
const char *generator, const char *name, const char *progname,
const char *version);
Remember: it is up to you to free these strings when
you don't need them anymore.
If you prefer to program in C++ you process the file example_text.text_skel with the following command4:
gengen -i example_text.text_skel
--file-name example_text.h --gen-name example_text
the class example_text_gen_class (option
--gen-name example_text) will be generated in the file
example_text.h (option --file-name example_text.h). This
class will have a member for each single parameter, with the same name
of the parameter and type string. This class will also contain
a method set_<xxx> for each distinct @xxx@ present in
the input file; for in instance in this example it will contain the
methods set_name, set_progname, set_generator and
set_version. These methods get a const string & as
parameter. These can be used to set the string that will be
substituted at run-time for the corresponding name in the input file
(otherwise the empty string is assumed).
Notice that in C++ there's no need to call any initialization function,
since the fields in the class are automatically initialized (as empty
strings) by the constructor. Morever, there is no version that
generates a string, as in C, since you can use the class
ostringstream.
Once these values are set, the method
void generate_example_text(ostream &stream, unsigned int indent = 0)
can be called in order to generate the text with
substitutions into the stream stream. The parameter
indent (default = 0) is useful to specify an indentation
in the generated text.
The following example uses the generated class in order to
generate the text twice; the second time, the name of the
parameter name is changed, and the indentation is set to
25:
#include <iostream>
#include "example_text.h"
using std::cout;
using std::endl;
int
main()
{
example_text_gen_class gen_class;
gen_class.set_name("an example");
gen_class.set_progname("example_text_gen");
gen_class.set_generator("Gengen");
gen_class.set_version("1.0");
gen_class.generate_example_text(cout);
cout << endl;
cout << endl;
gen_class.set_name("another example");
cout << " ";
gen_class.generate_example_text(cout, 2);
cout << endl;
return 0;
}
The output of this program will be as before.
This is already a useful feature of Gengen (at least that's what I think ;-). However if the text to be generated requires some more preprocessing, substituting only strings may not be enough. Instead you may want the generator to invoke a call back method when it comes to generate a specific symbol. This will be explained in the following section.
You may want the generator to invoke a call back method when it comes to
generate a specific symbol, instead of relying only on strings. This
can be achieved by specifying the type method for a
parameter. Let me clarify this with an example.
Say that your program has to generate some functions, and you, obviously, want all these functions to have the same definition style; then you can create a template file example_fundef.cc_skel:
@rettype@
@funname@(@paramtype@ @param@)
{
@funbody:method@
}
and once again process it with the command
gengen -i example_fundef.cc_skel --file-name example_fundef.h
--gen-name example_fundef
Then the generated class example_fundef_gen_class
will contain the set-methods set_rettype, set_funname,
set_paramtype and set_param, and a method
set_funbody, but it will also declare the following abstract
method:
virtual void
generate_funbody(ostream &stream, unsigned int indent) = 0;
Thus, this class cannot be directly instantiated; instead you can derive
from this class and provide the implementation of such method, knowing
that this method will be called right when it comes to generate that
part of code, in case the variable funbody has not already been
set via the method set_funbody (indeed the virtual method is
called if funbody is an empty string). Here's an example that
extends this class and uses the previous class test1_gen_class to
generate the function body (file example_fundef_gen.cc):
#include <iostream>
#include "test1.h"
#include "example_fundef.h"
using std::cout;
using std::endl;
class my_fundef_gen : public example_fundef_gen_class
{
public:
virtual void generate_funbody(ostream &stream, unsigned int indent) {
test1_gen_class body_gen;
body_gen.set_i (param);
body_gen.generate_test1 (stream, indent);
}
};
int
main()
{
my_fundef_gen fun_gen;
fun_gen.set_rettype ("void");
fun_gen.set_funname ("foo_fun");
fun_gen.set_paramtype ("unsigned int");
fun_gen.set_param ("bar");
fun_gen.generate_example_fundef (std::cout);
cout << endl;
return (0);
}
Notice that the parameter i of test1_gen_class
is set to the same name of the inherited field param: this will
guarantee consistency in the generated code (the code will be
compilable) and the generated function body will use the parameter of
the function definition. Moreover when the method generate_test1
is invoked, both the stream and indent parameters are
passed over, so that they will be used also by the other generator.
The generated code is once again as expected:
void
foo_fun(unsigned int bar)
{
if (bar < 10)
printf("the value of bar is %d", bar);
}
Notice how the indentation is handled automatically! Indeed the code generated by Gengen is able to keep track of the indentation level according to the leading spaces in a line.
This scenario can take place in a code generator where you want to have all the generated functions with the same style. When you decide you want to change the style you'll only have to change the file example_fundef.cc_skel, while the other parts of the programs remain unchanged.
When a generated class contains at least an abstract method, a virtual destructor is also generated (that basically performs no action) that is useful if you have to destroy something allocated in the derived class.
The type method has also an option; an option is basically
a statement of the shape <name>=<value> and has to be specified
between brackets {}. The option is iteration. If one
specified @funbody:method{iteration=true}@ then no space
would have been generated before invoking the call back method, and no
newline would have been generated after. This could be useful when the
result of the call back method is either the empty string or a sequence
of similar items; this way if these are handled from within a loop (the
name “iteration” comes from this) they can be handled more easily and
uniformly (otherwise you would have to treat the first element and the
last one differently).
If you want to generate C code, you can process it with the command
gengen -i example_fundef.c_skel --file-name example_fundef.h
--gen-name example_fundef --output-format c
This will generate the file example_fundef.h containing the following struct declaration:
struct example_fundef_gen_struct
{
const char *funbody;
const char *funname;
const char *param;
const char *paramtype;
const char *rettype;
};
and some functions
void generate_example_fundef(FILE *stream, struct
example_fundef_gen_struct *record, unsigned int indent);
that, given an initialized struct, generates the output to
the file stream, and
void
generatep_example_fundef(FILE *stream, unsigned int indent,
const char *funbody, const char *funname,
const char *param, const char *paramtype,
const char *rettype);
that does not require a struct, since it requires a value for each parameter in the template file.
We suggest to use the following function in order to be sure that each
string in the struct is correctly initialized to NULL:
void
init_example_fundef_gen_struct(struct example_fundef_gen_struct *r);
and two additional functions are provided in the
generated file, that return a (malloced) string instead of
generating the output to a file (they correspond to the two generate
functions seen above):
char *
genstring_example_fundef(struct example_fundef_gen_struct *record,
unsigned int indent);
char *
genstringp_example_fundef(unsigned int indent,
const char *funbody, const char *funname,
const char *param, const char *paramtype,
const char *rettype);
Remember: it is up to you to free these strings when
you don't need them anymore.
As for the type method, instead of creating a pure virtual
method as in C++, an extern function declaration is generated:
extern
void generate_funbody(FILE *stream,
struct example_fundef_gen_struct *record,
unsigned int indent);
but no code is generated for this function, so that
the programmer is required to provide a definition for this function
somewhere else in the program. This (extern) function will be called
right when it comes to generate that part of code, in case the argument
funbody or the field funbody in the passed struct is
NULL.
When you use @if@ conditionals (or bool parameters, see
Types), the generated record fields are of type short, and
when you use int parameters the fields are of type int.
So far, we dealt only with parameters of type method or string
parameters. Actually, unless explicitly stated, the type of parameter
is implicitly considered as string (and for conditional
expressions as bool, see Conditionals). However, the type
of a parameter can be made explicit, just like we did with method
type. In particular, currently, the following basic types are
available: string, int and bool6.
Since gengen does not provide variable declarations (to keep things
simple :-) you must always specify the type each time (just like for
method parameters), unless the type is not the default one. Of
course, gengen will check that you use parameter types consistently,
i.e., always with the same type.
For instance, the following code is correct, since by default the type
of a parameter is of type string, thus the parameter mypar is
used consistently:
This is the value of the parameter @mypar@.
And I repeat it here @mypar:string@.
While this example will generate an error, since the first time
mypar is (implicitly) of type string, while the second
time is of type int:
This is the value of the parameter @mypar@.
And I repeat it here @mypar:int@.
For instance, if this file is called foo.skel, gengen will issue the following error:
foo.skel:2: variable "mypar" of type "int"
foo.skel:2: already used with another type
foo.skel:1: previous usage was here with type "string"
Gengen will use the specified type to generate fields and methods of the
generated class accordintly, e.g., if a parameter is declared of type
int the generated set method will get an integer parameter.
When generating a parameter of type int the string representation
of the actual integer value will be output; while for bool
parameters the literal true or false will be output.
It is often useful to generate some parts only if specific conditions are met, and other in the opposite case. Inside the template file you can also use the following syntax:
@if@ condvar1 @then@
text1
@elseif@ condvar2 @then@
text2
@elseif@ ... other alternatives...
@else@
text_else
@endif@
that has the same semantics of if in programming languages you're used to,
and of course all the else parts are optional. For every
condvar a boolean instance variable is added to the generated
class, and of course a corresponding set method receiving a boolean
argument.
It is important to notice a possible new line characters and spaces
after a @then@, @else@ and @endif@, and
possible spaces before @if@, @elseif@ and
@else@ are NOT discarded during the generation of code. Thus,
the following this code
@if@ c @then@ foo
@else@ bar@endif@
will generate the following C++ code7
if (c)
{
stream << " foo";
stream << "\n";
stream << indent_str;
}
else
{
stream << " bar";
}
Notice that there are spaces before the generated strings, as there were in the template file.
And the following code
@if@ c @then@
foo
@else@
bar
@endif@
will generate the following C++ code
stream << " ";
if (c)
{
stream << "\n";
stream << indent_str;
stream << "foo";
stream << "\n";
stream << indent_str;
indent = 2;
stream << " ";
}
else
{
stream << "\n";
stream << indent_str;
stream << "bar";
stream << "\n";
stream << indent_str;
}
Notice the two characters inserted before the
if test (that are generated independently from the evaluation of
c) and the new line before the then and else bodies.
If you're not confortable with this treatment of spaces and new lines in
conjunction with if statements, you can use the uppercase version of
these keywords, i.e., IF, THEN, etc. When you use these
keywords, spaces and newlines are skipped. For instance, the previous
example can be rewritten as follows:
@IF@ c @THEN@ foo
@ELSE@ bar@ENDIF@
and the generated code will not contain the extra spaces:
if (c)
{
stream << "foo";
stream << "\n";
stream << indent_str;
}
else
{
stream << "bar";
}
Notice that the space “eating” stops at the first newline, thus, the following code:
@IF@ c @THEN@
foo
@ELSE@
bar
@ENDIF@
will correctly consider the indentation in the then and else bodies:
if (c)
{
stream << " foo";
stream << "\n";
stream << indent_str;
}
else
{
stream << " bar";
stream << "\n";
stream << indent_str;
}
Finally, you can mix uppercase and lowercase keywords in the same if statement as you see fit.
Of course, you can nest if inside then branches, else branches, and so on, just like you do in your programming language:
@if@ c1 @then@
@if@ c2 @then@ foo2
@elseif@ c3 @then@ foo3
@endif@
@else@ bar
@if@ c4 @then@ foo4
@endif@
@endif@
Unfortunately, you cannot indent nested ifs. Or better, you can actually, but the indentation characters will be generated in the code. If you want to indent the nested ifs you have to use the uppercase version.
While there is not the concept of “variable declaration” in the
template file, Gengen will check that you do use variables in a
consistent way (see Types); thus you're not allowed to the same
name for a string variable and for the boolean expression of an if
statement (which is implicitly considered of type bool). For
instance, the following code:
@foo@
@if@ foo @then@ @else@ bar @endif@
will generate the following error:
test.h_skel:3: variable "foo" of type "bool"
test.h_skel:3: already used with another type
test.h_skel:1: previous usage was here with type "string"
On the contrary, this version will work fine, since foo is used
consistently:
@foo:bool@
@if@ foo @then@ @else@ bar @endif@
Since version 1.0, it is possible to specify complex conditional
expressions. You then can use comparison operators <, >,
<=, >=, =8 and !=, and boolean operators
and, or and not.
The precendence of these operators is the standard one, and, of course, you're allowed to override the precedence by using parenthesis.
Gengen will perform type checking on the expressions (see Types),
thus it will check that and, or and not are used
only on boolean expressions, and that when using the other operators,
the operands are of the same type. Moreover, <, >,
<=, >= cannot be used on boolean expressions. While they
can be used on string expressions, and in that case the standard
lexicographical order will be used for the comparison.
In expressions you can use constants of the basic types, and in this case you must not specify the type: it will be automatically inferred.
Any numerical literal will be considered an integer constant; the
literals true and false will be considered boolean
constants; finally, string constants must be enclosed in ".
For instance, the following is a valid expression (notice that, since we
are in the context of an if expression, parameters are automatically
considered of type bool, thus string parameters must be
explicitly specified with type string):
@if@ (not foo) and (mystring:string < "foo" or i:int > j:int) @then@
...
Instead, the following one
@if@ (not foo) and (mystring < "foo") @then@
...
will produce the following error:
test.h_skel:1: mystring and "foo" must have the same type
test.h_skel:1: mystring has type bool, "foo" has type string
These are the options that can be passed to GNU Gengen:
-h, --help Print help and exit
-V, --version Print version and exit
-i, --input=file input file (default std input)
-F, --file-name=name name used for generating file (default stdout)
-f, --gen-name=STRING prefix for generated code (default=`gengen')
--output-format=lang target language (cpp, c) (default=`cpp')
--output-dir=STRING output directory (default current dir)
--separate-files output to separate files (header, source). require
--file-name
--expand-tabs strings containing newlines are indented according
to the current indentation level
--no-gen-version do not put gengen version in the generated file
--test-mode even with errors exit with 0 (this is only for
testing purposes)
--force force regeneration of output code
Let us examine the ones not yet explained.
--separate-files that makes Gengen generate the header with
class definition and a .cc file with the same name specified with
--file-name, which contains the implementation of the generate
methods.
--expand-tabs is pretty useful: all the variables specified in
the template files, when generated, will be correctly indented according
to the current indentation level (i.e., the indentation level at the
point where they are in the template file). Thus, consider a slight
variation of the example seen before:
@rettype@
@funname@(@paramtype@ @param@)
{
@funbody@
}
where funbody is not of type method.
Then, if you do not use the --expand-tabs and you set the string
if (bar < 10)\n return;, then the resulting generated code
will look the following one (the other variables are set to values as
seen before):
void
foo_fun(unsigned int bar)
{
if (bar < 10)
return;
}
While, if you use --expand-tabs, the string
containing newlines will be correctly formatted:
void
foo_fun(unsigned int bar)
{
if (bar < 10)
return;
}
Gengen, in order to make separate compilation easier and minimize
recompilations of many files, before actually generating the output
file, checks whether a previous generated file exists and, if so,
whether there are any changes since the last generation. If no
modification is needed, the previous generated file is not overwritten.
This saves compilations, for instance, when you use
--separate-files and you only change something in the template
file that affects only the code that has to be generated (i.e., the
generate method itself), but not the class interface. However,
if you want to force the generation of the output file, you can do so
with the option --force.
The --output-format permits generating code different from C++
(in the current version the other available target language is C).
The remaining options should be self-explanatory :-)
No program is perfect, and GNU Gengen is certainly no exception. A partial list of problems with Gengen 1.4.2 can be found in the TODO.txt.
Should you discover a bug, propose an extension/feature, or just fell
like telling me what you think of this program, please send an e-mail at
the address bug-gengen at gnu dot org.
The following mailing lists are available:
help-gengen at gnu dot org
for generic discussions about the program and for asking for help about it (open mailing list), http://mail.gnu.org/mailman/listinfo/help-gengen
info-gengen at gnu dot org
for receiving information about new releases and features (read-only mailing list), http://mail.gnu.org/mailman/listinfo/info-gengen.
If you want to subscribe to a mailing list just go to the URL and follow the instructions, or send me an e-mail and I'll subscribe you.
[1] http://www.gnu.org/software/gengetopt
[2] Since version 1.4.2 of Gengen the CVS repository was dismissed in favor of Git (http://git-scm.com/).
[3] Notice that the first indentation has to be performed manually; this behavior is useful in conjunction with a more involved feature that will be explained later.
[4] Notice
that, by default gengen produces C++ code, so you don't need to specify
the --output-format option.
[5] Notice that the first indentation has to be performed manually; this behavior is useful in conjunction with a more involved feature that will be explained later.
[6] This holds since version 1.0.
[7] In this section will use generated C++ code as an example, but of course, the same features hold for generated C code as well.
[8] This is the equality operator, not the assignment operator.