/*****************************************************************************
 *                                                                           *
 *   Tool:    CGraphPP                                                       *
 *   Author:  Andreas Saebjoernsen                                           *
 *   Version: 0.2 beta                                                       *
 *                                                                           *
 *****************************************************************************/


Introduction
------------

CGraphPP is a tool which utilise the ROSE project to traverse code and 
graph it dynamically and statically. The goal is to create a tool which
is capable of graphing any C and C++ code.

Thanks to: Dan Quinlan, Nils Thuerey and Markus Schordan for support and
help in the process of creating this tool.

Design 
------

To graph a variable in a function you have to insert a comment or pragma.
        int variableName = 20;
        //pragma GenPRintCode_variableName = graph-it
You may use a pragma instead:
        int variableName = 20;
         #pragma GenPrintCode_variableName = graph-it
The type of the variable may be *any* type. 

In the pre-processing of a C/C++ code a class-like structure of type
Class may be a Class, Struct or Union. 

Class

All the variables in the scope of the Class will be graphed. A member
function:

void ScopeN:ScopeN-1:: .. :: Scope2 :: ClassScope :: save(
   GenRepresentation* generateRepresentation, string className,
   GenRepresentation::TypeOfPrint printType = 
   GenRepresentation::Container);

is generated. Why a member function and not a global function? That is 
because the class may have private variables. ScopeN to Scope2 is the 
scopes the Class Declaration was declared in, and ClassScope is the scope 
of the Class which is to be graphed. GenRepresentation is the object which 
generate dot-code which can be displayed. the 'string className' is the 
name of the class. It is possible to use this method to graph a poiner 
GenRepresentation::Container (default value) or a reference 
GenRepresentation::Contained.

Struct

The struct is similar to the Class, but the generated code is not a 
member function. This is because the most common use of a struct is in C with
no private variables. Therefore the advantage of not modifying the code is
bigger than the limitation of not graphing private variables in the few
cases where that has been done.

void
save_11treeElement12__T140705452 (GenRepresentation * generateRepresentation,
                                  string className,
                                  treeElement::__T140705452 * classReference,
                                  GenRepresentation::TypeOfPrint printType =
                                  GenRepresentation::Container)


Union

An union is treated like a variable in the scope of a Class or Struct. The 
consequences for this is that a control variable has to be defined in the 
parent scope of the union in order for it to be graphed dynamically. To 
specify this the user has to specify a pragma statement or a comment which 
tells CGraphPP what the variable name is and what the condition is:
   #pragma GenUnionControl_variableName =  (controlVariable==Condition1)&(controlvariable2!=Condition2)....|(controlVariableN==ConditionN)
Instead of #pragma you may use a comment :
   //pragma GenUnionControl_variableName = ....
It is important that it spans only a line. As you see it is allowed to have
many controlvariables. Allowed logic:
   (.. != ..)
   (.. == ..)
   .. (something)|(something-else)..
   .. (something)&(something-else)..
Eample of logic currently *not* allowed:
   .. ( (..)&(..) )|( (..)|(..) ) ..



Usage
-----

To graph the code write:
   cgraphpp filename.C
If you want to generate a graph for the global scope write:
   cgraphpp --gall filename.C
            or
   cgraphpp --graph-all filename.C

Static Graphing 

The file generated from this is:
   Static_filename.C.dot
Which is the static graphing of the code. The code you can see graphed
statically is the same components that its possible to graph at runtime.

Dynamic Graphing

The code generated to dynamically graph the code is in the file:
   CodeGenerated_filename.C
This code has to be included in filename.C in an appropriate way so that the 
methods generated is where intended. For Class-like structures a 
member function is generated and that requires a change in the code in
filename.C. For structs that is not the case. 
  In the 'main' function several statements has been included as comment.
Uncomment those, and also uncomment the inclusion of 'GenRepresentation.h' in
the top of scope. 
  When you run the code the file generated is:
    Dynamic_filename.C.dot
Which is the dynamic graphing of the code. 

Garbage Collection

There is a limitation that the handling of pointers must be clean. That means
that if a pointer P and another pointer P' points to the same object and
the pointer P is freed, then P' *must* be equal to NULL. Garbage collection
may remedy for this by replacing this with another test:
   #ifdef CGRAPHPP_USE_GC
     if ( GC_base(classReference->variablePtr) != NULL)
   #endif
This uses the GC Garbage collector by Hans Boehm to test if the variable is 
pointing to a valid object in the heap of GC. The user has to do the
appropriate steps to use the debug allocator of GC in the code himself and
compile to code with the option
   -DCGRAPHPP_USE_GC


Current Limitations
-------------------

-Due to inherent limitations C++ codes which utilise STL or templates 
cannot be graphed. In the future that will be worked on.
-The code inserted by the preprocessor into the user filename.C must
be comments due to the above limitation.
-There is a limitation that the handling of pointers must be clean. That means
that if a pointer P and another pointer P' points to the same object and
the pointer P is freed, then P' *must* be equal to NULL. 
