MathGroup Archive 1995

[Date Index] [Thread Index] [Author Index]

Search the Archive

Crossreference, code documentation

  • To: mathgroup at
  • Subject: [mg1609] Crossreference, code documentation
  • From: <larso171 at>
  • Date: Tue, 4 Jul 1995 03:08:36 -0400
  • Organization: University of Minnesota, Twin Cities


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?


Jim Larson

  • Prev by Date: Re: rhs of SetDelayed
  • Next by Date: Text in Mathematica Graphics
  • Previous by thread: Re: Crossreference, code documentation
  • Next by thread: Re: Crossreference, code documentation