Crossreference, code documentation
- To: mathgroup at christensen.cybernetics.net
- Subject: [mg1609] Crossreference, code documentation
- From: <larso171 at maroon.tc.umn.edu>
- Date: Tue, 4 Jul 1995 03:08:36 -0400
- Organization: University of Minnesota, Twin Cities
Hi,
I'm wondering if there is a tool that will take an MMA .m source code file
and do somethings to it, particularly create a crossreference table.
The first thing I did, thinking it would be a hour job at the most, was to
strip comments out of the file. But with nested comments, it turned
out to be a 10 hour job, also to get rid of excessive blank lines that were
left behind when the comments were removed. I thought it would be a simple
Lisp-like exercise on recursion, but ended up with a procedural mess.
Anyway it works.
If anyone is curious, it seems so simple, once I tokenized the file into 3
types of strings:
"(*"
"*)"
"everything else not containing any (* or *) tokens"
For notational simplicity in the below, I'll let L (for left separator)
represent "(*" , R (for right separator) represent "*)", and S represent
"everything else". Just for the sake of illustration in the below, I'm
also omitting the commas, a la Lisp. So a program looks like the list below
(the "+-----+" 's above the list indicates comments, and the " ^ " 's below
the list indicate which strings are non-comments):
+--------------------+
+------+ +------+ +------+
program = { S1 L S2 L S3 R S4 R S5 L S6 R S7 L S8 R S9 }
^ ^ ^ ^
stripComments[program_ListOfStrings] := ( horrible long procedural program )
outputProgramWithoutComments = stripComments[program] ;
outputProgramWithoutComments ==> { S1 S5 S7 S9 }
(since S2, S3, S4, S6, and S8 are enclosed between (* and *), and
therefore are comments. S3 is a nested comment).
Given that this simple exercise took me so much time, it seems wise to ask
around if there is a tool that does an even more complex job --
providing a crossreference table of functions and the variables they use,
particularly global variables.
This problem arose because I'm designing a very large complicated genetic
algorithm (multiple populations, all kinds of statistics, multiple
restarts, which genetic operators are selected and the size of their
paramters adjusted by the various statistics such as generation counter,
and bias, on and on).
It became too much of a hassle to keep worrying about what were local and
what were global, continuously changing the function paramater list and the
calls to these functions, etc. Despite a lot of "up front" design time, I
eventually reached the point where it was easiest to write code, and to
allow any variable that was needed by several other functions to be global.
(I did give all my global variables a "G" suffix though). Basically, I
didn't know what statistics were needed by what functions when, when a
particular statistic would be generated and by who, etc.
Besides, I'm not really just after a program with few global variables,
what I'm really after is a highly encapsulated object - oriented kind of
thing. So a lot of effort worrying about what was global and what was
local to a function would be wasted, because the whole thing is to be
completely redesigned into nearly independent packages.
To help this redesign effort, it would be great to have a crossreference
listing of each function, and what globals they used and what globals they
modify. And their local variables while I'm at it.
(The ultimate goal would be to produce a list by variable of which
functions use it and which functions modify it -- that would help me decide
on which additional variables could be easily made local, and help me
organize the whole thing into packages -- e.g. randomPermutationList is
used only by 5 "selection wheel" functions, that could fit together well in
a "selectionWheel.m" package).
As an intermediate goal, if I just could generate a listing like the below,
I could probably easily rearrange it into whatever "view" I liked with
Excel's pivot tables:
function variable global global
name name local? used? modified?
========= ======== ====== ======= ==========
func1 xabcF1 Y N N
func1 xdefF1G N Y N
func1 xghiF1G N Y Y
func2 x123F2 Y N N
func2 x456F2G N Y N
func2 x789F2G N Y Y
func2 xjklF2 Y N N
...
(Yes, I do use more descriptive function names and variable names in real
code. Also, unlike the above, the variable names do not include a function
identifier (would be meaningless with globals anyway), and not all global
variables have a G suffix -- part of the reason for the program is to help
me find variables that I'm not aware of being global that are global.)
I'm aware of the Names["Global*`"] command, which will give me a list of
all globals. But I can't think of a simple way to find out which functions
use them or modify them.
Anyway, does anyone know of such a crossreference / documentation tool?
Thanks
Jim Larson