ROSE INTERNAL DOCUMENTATION (README FILE)


1) Some old source from ROSE I is mixed with the current ROSE II
code. The old source is in statement.C, expression.C and
array_class_interface.C. The source is for the most part not used and
will be removed at some point soon. array_class_interface.C is being
modified (some of the functions to reflect the requirements of ROSE
II's design, this source will be retained and the unused functions in
array_class_interface.C will be removed.  Much of what was in
statement.C and expression.C represents the old design of ROSE I
(which was not desinged to have multiple passes) and so it is replaced
in part by code from file representing each independent
transformation.

2) Code general enough to be a part of all the transformations is
located in the src directory with subdirectories for different passes
separating the implementations of those specific transformations.

3) The code specific to individual transformations (organized as
separate passes) is placed into the ROSE_Transform_# directories
(where # is a number code for the transformation, since we have so few
right now (1) numbers work well to distinguish the different
transformations).

4) Each transformation sees the whole program tree

5) Each transformation is organized as follows: 
*NOTE: The word
"template" is used to refer to a stencil or cookie cutter approach to
defining source code and certainly does not refer to the C++ use of
the word (niehter does the use of the word stencil in this
explaination of this have anything to do with numerical
finite-difference stencils).

      a) A template (the target template) is used to define what we
are looking for in the applications source when we perform
transformations. A validating function is paired with the template
code.  The function may or may not reference the program tree
generated by the template code. The purpose of the validating function
is to determine when, within a users application, the transformation
can be preformed.

      b) A template (the transformation template) is used to define
the target transformation, the program tree for the transformation
template is represented within the class representing a specific
transformation.  This program tree is represented by numerious pieces
(subtransformations) which are edited and assembled into the final
transformation within the users application code.  A transformation
function ("transform()") is paired with the transformation template
and performs the transformation (copies, edits and assembles the
program tree).  The transformation template may or may not be
referenced by the transformation function, "transform()", the
transformation may alternatively be built from scratch instead of
using program tree representing the transformation template.  This
allows for maximal flexibility in the development of transformations
(a mixed approach is also possible, building parts of the
transformation from scratch and taking parts of the program tree and
editing them then assembling them together).

      c) Logical functions about the array class (names of classes and
member functions, for example) are abstracted away from most of the
ROSE implementation and buried into the array_class_interface.C file
(and the array_class_interface object provided).  Thus other array
class libraries may be readily used alternatively to A++/P++.  This
sort of thing has not been tried yet (it is treated as a design goal).


6) Transform_1 directory is not used (it will be removed) it contains
the pattern-mathing approach used previous to the development of grammars.

7) Within the Transform_2 and Transform_3 directories the implementations of
the grammars (classes representing terminals and non-terminals of the grammar)
are automatically generated.  The process uses a perl script and represents
the best method currently "in use" within ROSE.  A better methods (which requires
far less input) is to generate the grammar from the BNF notation plus 
suplimentary code.  This later method is implemented in the ROSE/grammar 
directory, and can be used to generate compilable versions of the array class
grammar (but other grammars have not be 'fully' generated).

8) The generation of the Sage grammar is a current test project and is incomplete
(only the header files were generated, not the source code) using the grammar generation
technique.  This method requires more work.