Demeter/C++ to Demeter/Java transition document
===============================================

A significant amount of documentation about
Demeter/C++ has been written: 

In the book "Adaptive Object-Oriented Software", the Demeter/C++ syntax
is used in the examples which explain the concepts.

The following documents are all on-line:

User's Guide
Laboratory Guide
FAQ
man pages

It will take time to update those documents. In the mean-time, we
provide this document which explains the differences between the
two systems.

CONCEPTUAL DIFFERENCES

Demeter/Java uses context objects described at URL
http://www.ccs.neu.edu/research/demeter/biblio/context.html
instead of propagation patterns with wrappers and transportation patterns.
A propagation pattern is now expressed by a method attached
to some class. The class defines a traversal function f and
the method instantiates
one or more context objects c1, c2, ... and invokes
the traversal function with a call someObject.f(c1,c2, ...).
While the traversal function f executes, the context objects
execute the "wrappers" which are expressed in the context class
definitions.

Traversal functions are attached to a class in Demeter/Java.
This makes the "from" part of a directive superfluous
since the traversal starts from the class to which
the traversal function is attached. The "from" part
is therefore optional.


NAME CHANGES

The terminal classes have been renamed as follows:

C++			Java
---                     ----
DemNumber		Integer
DemString		String
DemIdent		Ident
DemText			?
DemReal			?

Integer and String are defined in Java.

SYNTACTIC DIFFERENCES

Demeter/C++ puts all keywords between *. Demeter/Java uses
reserved words instead. They are:

after
before
to
traversal

Current deficiency:

Doug
We need syntax to specify directives independently of a traversal
function. The same directive can be reused for many different
purposes: building block of other directives, traversals with different
visitors, subtraversals.

Proposed syntax (approximate):

directives {
  D1 = from A to B;
  D2 = from B to D;
  D3 = D1 join D3;
  D4 = from A bypassing {X,Y} to B; 	// bypass classes X and Y
  D5 = from A bypassing {-> F,g,G} to B; 	// bypass edges (all)
  D6 = from A through {Y,Z} to B; 		// through classes Y or Z
  D7 = from A through {-> F,g,G} to B; 	// through edges (at least one)
}

Wild card symbols should be allowed.




SYSTEM USE DIFFERENCES

The scanner currently is very simple. Use only tokens consisting
of all letters or of one non-letter.

imake is not used in Demeter/Java. Therefore, gen-imake
is not available. To generate the default Makefile, use

j-gen-make

(When Demeter/Java needs a command which is also in Demeter/C++,
it is prefixed by j-.)

In Demeter/Java you need to edit currently the default Makefile
to replace "program" by the file name you have chosen, say x.
Demeter/Java currently expects only two files per directory:
x.cd (class dictionary) and x.beh (adaptive program). 

The class dictionary must contain a class Main = .

The parser currently allows only one input file: x.input

In future versions, the Makefile will be generated from a
configuration file so that it no longer needs to be edited.
Several *.beh files will be allowed and input can come from
any file.


TRANSLATION EXAMPLES

propagation pattern:

*operation* int countB() *init* (@ 0 @)
  *traverse* *from* A *to* B
  *wrapper* B 
    *prefix* (@ return_val++; @)

Equivalent Demeter/Java:

// define a traversal with one visitor
A {
  traversal allB(CountingVisitor c){
    to B; // "from A" not needed
  }
}
// CountingVisitor is defined in the class dictionary by
// CountingVisitor is a context class which modifies behavior
// CountingVisitor = <total> Integer.

CountingVisitor {
  // behavior modification
  before B (@ new Integer(total.getValue()+1); @)
}

A {
  (@
  int countB() {
    // initalization of counter is done when context object is created
    CountingVisitor c = new CountingVisitor(new Integer(0));
    // traverse with counting visitor
    this.allB(c);
    // return result in context object
    return c.get_total.getValue();
  }
  @)
}

More examples of Demeter/Java programs are at
http://www.ccs.neu.edu/research/demeter/sources/DemeterJava/examples