1 Code generation

Code generation is the final step in the processing path of a macrocoding program. Code generation consists in reading the CORE objects and writing on one or more files the source code in the language we need. The Macrocoder program will open the files and write in them the generated source code in Java, C, .NET, JavaScript, PHP or whatever other language. Note that code generation is not limited to computer languages: Macrocoder can as well generate documents (HTML, RTF, etc.), configurations files (for example in XML), or whatever other standard or custom format.

At first, writing a program that writes a program is a bit odd and requires some acquainting.

1.1 Preparation of sample code

Before writing the code that writes the code (sorry for the pun!), we must have an exact idea of what the final code must be. Probably the best approach is to manually write and test a sample source file that will serve as a template for writing the code generator.

In this chapter we shall work on code generation for the Genealogy project from the previous book. For that project, we decided that the Macrocoder output must be a single static HTML page containing the names of all the listed people, with an hyperlink to their parents if specified. Although this project is generates HTML, the same principles are valid for any other output language like C, C++, Java, PHP, SQL and so on.

This is our manually written page that will serve as a template:

Figure 1.1.1 - Example of code generated by the Genealogy project.

In order to have a sample of all the cases, in the example we included two people: one without a specified father (Mike, lines 11 and 12) and another with a specified father (Luke, lines 14 and 15).

Once loaded in a web browser, the HTML above produces a very basic static page where every person is listed with his or her name. Under the person name, the web page reports Father unknown if no father has been declared, or Father: name with an hyperlink to his father if known:

Generated code shown on a web browser — Figure 1.1.2 - Web browser showing the static page at figure 1.1.1.

1.2 Code generation blocks

Before addressing the code generator we must have analyzed and understood the logic blocks that compose the files that have to be generated. This analysis should not be functional, but it must be focused on the needs of code generation.

In our sample HTML page we immediately recognize that we have a fixed header (lines 1-10) a fixed footer (lines 17-18), evidenced in the figure below:

Figure 1.2.1 - Example of code generated by the Genealogy project with fixed header and footers evidenced.

The fixed header and footer evidenced above must be written as they are, one at the beginning of the file and the other at the end. Instead, the central area, covered by lines 11-16, is made of a sequence of n blocks where n is the number of people defined in the Macrocoder target source file. Let's analyze in detail a single block:

Figure 1.2.2 - Example of code generated by the Genealogy project - detail of one repeated block

The block above is formed by fixed and variable parts, which have been evidenced. Line 2 can be replaced by a simple "Father unknown" if no father information is available.

After this analysis, we determined that our code generator will have to be composed by the following elements:

a fixed header, to be printed once at the beginning of the output file;
a series of intermediate blocks, one per defined person, containing their details;
a fixed footer, to be printed once at the end of the output file;

1.3 Writing the code generator

The code generation is done in a phase executed when all the semantic analysis has been completed and all the required data is available, verified, validated and ready to be used. If anything fails before due to inconsistent information given by the target programmer (for example, a person linked to an unexisting father), the execution will not reach the code generation phase. Therefore, during this phase we are sure that all the data is valid and consistent, saving us the effort of writing checking code.

The next step is to create a new rules source file core_generate.fcl and add it to the rules project with the following contents:

At a glance we immediately note that this code has some parts evidenced in yellow. Those parts are freetext, a special Macrocoder editor mode. If you are not confident with Macrocoder freetext mode, please first read the freetext howto before continuing. We also note at line 26 and 31 that guillemets are used (for example «name»): they are also explained in the freetext howto.

We can now proceed with lines analysis:

line 3: we defined a generate phase with a value (20) high enough so it will be the last executed phase;
line 5: by applying the in phase declaration at the root level we are extending the lifeset class; in this way the phase code will be executed once on the lifeset singleton;
line 6: we declare a variable var FileOutStream htmlFile which is initialized with "index.html": this will create a file named index.html in the directory where the target project is; errors in creating the files will automatically reported;
lines 9-19: we write on the html file the fixed header that we copied from the sample file and pasted as freetext in the Macrocoder editor;
line 23: we start looping on the knownPeople lookup table; we defined this lookup in a previous step and served to verify duplications and to check the existence of parents; now we use it for the third time as a simple list of references to Person instances sorted by name;
lines 24-25: the knownPeople lookup table is accessed and the information about the i-th person are extracted in two local variables name and father: this step is not strictly required, but it enhances readability since from now on, we can refer to that data by using the variables names;
line 26: we write on the generated file the first line of the two lines required for each person block;
line 27: the if statement decides whether this person has a father defined or not; the father is defined if its stored name is not empty;
lines 28 and 31: these two lines produces the two versions of block's line #2, the one without a father and the one listing the known father;
lines 36-39: at the end of the operations, the fixed footer block is written and the output HTML file is complete.

The complete rules and target projects for at this stage can be downloaded at this link: Genealogy5.zip.

2 Summary

In this book we have covered the following concepts about Macrocoder programming:

code generation is the final action of a Macrocoder process;
the manual develpment and testing of one or more examples of generated code is highly recommended, since they give hints on the required code generation and serve as templates to be copied in the code generator code;
the sample sources must be examined to identify which parts are fixed, which variable and how they are to be nested together;
the code generator can then be developed within its own phase.

« Go to book 3 Go to book 4 »