5 Nana Shortform Generator.

The Eiffel language provides a shortform of a class which consists of the exported methods and their pre and post conditions. The private part of the class such as the code is hidden in this form leaving only:

1. Arguments and return values for methods.
2. ‘REQUIRE’ and ‘ENSURE’ calls which specify the precondition and postconditions of each method.

This is useful to provide a summary of what the code does and how to use it rather than how it works.

Nana provides a similar service which can be used to generated a HTML version of the short form of your program automatically. The code for this is kept in ‘shortform’. Do a ‘make example’ to build an example document.¹

Consider the following program:

     /* smallex.c - a small example */
     
     #include <stdio.h>
     #include <math.h>
     #include <eiffel.h>
     
     void sort(int *v, int n) {
       int i;
       REQUIRE(v != NULL &&
         0 <= n);
     
       for(i = 0; < n; i++) { /* at last, an O(n) sort! */
         v[i] = i;
       }
       /* And no, this isn't what most people think of as sorting */
     
       ENSURE(A(int i = 0, i < n - 1, i++,
           v[i] <= v[i+1]));
     }

Its short form can be generated by using the ‘nana-sfg’² program which generates:

     % nana-sfg smallex.c
     ...
     #include <stdio.h>
     #include <math.h>
     #include <eiffel.h>
     ...
     void sort(int *v, int n) {
       ...
       REQUIRE(v != NULL &&
         n >= 0);
       ...
       ENSURE(A(int i = 0, i < n, i++,
           v[i] <= v[i+1]));
     }
     %

The ‘nana-sfg’ program is a small AWK program which processes its arguments into shortform and always writes to the standard output. If it is passed no arguments it works as a normal UNIX filter reading from the standard input.

It is suggested that a copy of ‘nana-sfg’ be kept in each projects ‘bin’ directory so that it can be modified for local taste. The user will probably wish to modify the rules for short form generation. For example you might add rules such as:

     /^\/\//           { emit(); } # print out C++ comments in column 1
     /^\/\*\+/,/\*\//  { emit(); } # print out multi-line /*+ ... */ comments

Of course for a real project you need to run ‘nana-sfg’ over the entire source tree. To do this you can use the ‘nana-sfdir’ program.

     % nana-sfdir

This command simply creates a copy of the source tree in the current directory under ‘NANASF’ using the ‘nana-sfg’ program. You can then run a source code to HTML translator over the ‘NANASF’ directory. Currently we are using the GLOBAL package which was written by Shigio Yamaguchi which available from:

• ‘http://wafu.netgate.net/tama/unix/global.html’ – the GLOBAL homepage.
• ‘ftp://ftp.cs.ntu.edu/pub/nana/global-2.24.tar.gz’ – a local (well for Darwin at least) copy of the GLOBAL package.

The alert reader will perhaps be asking themselves why we did not simply modify GLOBAL. Well that was the original idea, however after a bit of thinking it seemed better to separate the generation of the short form of the code from the generation of the HTML. This gives us the ability to use other translators and other tools. It also simplifies the interaction between nana and GLOBAL. For information on other translators see:

• ‘http://www.zib.de/Visual/software/doc++/index.html’ – DOC++ homepage.
• ‘http://www.webnz.com/webnz/robert/cpp_site.html#Documentation’ – an index of other translation tools (e.g. to LaTeX).