
/*
 * Copyright © 2002 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * California 95054, U.S.A. All rights reserved.  Sun Microsystems, Inc. has
 * intellectual property rights relating to technology embodied in the product
 * that is described in this document. In particular, and without limitation,
 * these intellectual property rights may include one or more of the U.S.
 * patents listed at http://www.sun.com/patents and one or more additional
 * patents or pending patent applications in the U.S. and in other countries.
 * U.S. Government Rights - Commercial software. Government users are subject
 * to the Sun Microsystems, Inc. standard license agreement and applicable
 * provisions of the FAR and its supplements.  Use is subject to license terms.
 * Sun,  Sun Microsystems,  the Sun logo and  Java are trademarks or registered
 * trademarks of Sun Microsystems, Inc. in the U.S. and other countries.  This
 * product is covered and controlled by U.S. Export Control laws and may be
 * subject to the export or import laws in other countries.  Nuclear, missile,
 * chemical biological weapons or nuclear maritime end uses or end users,
 * whether direct or indirect, are strictly prohibited.  Export or reexport
 * to countries subject to U.S. embargo or to entities identified on U.S.
 * export exclusion lists, including, but not limited to, the denied persons
 * and specially designated nationals lists is strictly prohibited.
 */

This directory contains an example of using the Visitor design pattern
with JJTree.  Like the Transformer example, it shows how a Java
program can be processed into a slightly different form.

In this case the input code is transformed so that each class has a
jjtAccept() method inserted.  This might be useful for updating node
files created with an earlier version of JJTree so that they can be
used with the Visitor support.

Here is an overview of the source files:

Java1.1.jjt

  This JJTree source file has been slightly modified from the Java 1.1
  grammar distributed in the JavaGrammars examples directory.  Here
  are the main differences:

  1) Removed the main method from the parser class;

  2) Added a couple of JJTree options;

  3) Made the CompilationUnit production return a root AST node;

  4) Made white space SPECIAL_TOKENs rather than SKIPs;

  These changes illustrate how a JavaCC grammar can be used with
  JJTree with very little modification.  In particular, there are no
  node annotations -- instead each production in the grammar is
  represented as a node.

Main.java

  Simply calls the parser to create the AST, creates a Visitor, and
  then asks the root node to accept the visitor.

SimpleNode.java

  This is modified from the automatically generated file.  SimpleNodes
  now maintain their first and last tokens so that the input can be
  reconstituted.  The jjtOpen() and jjtClose() methods are used as
  hooks to collect and store these tokens.  The NODE_USES_PARSER
  option is specified so that the parser object is available to these
  methods.

UnparseVisitor.java

  This is a generally useful Visitor that simply unparses the nodes
  that it visits.  It is intended to be a superclass for
  transformation-specific Visitors such as AddAcceptVisitor.

AddAcceptVisitor.java

  This is a Visitor for a particular transformation.  It extends
  UnparseVisitor and overrides methods for those nodes that require
  special treatment.  In this case, only the visit method for
  ClassBodyDeclaration nodes needs to be overridden.

  The visitor determines whether the node currently being visited is
  the first child of its parent, and if so it inserts the new text.
  It makes an attempt to indent the new text at the same level as the
  current node.


Here's how to build the transformer:

1) Run the JJTree on the grammar.  It will generate many node files
because the MULTI option is set.

trane% jjtree Java1.1.jjt 
Java Compiler Compiler Version 2.0 (Tree Builder)
Copyright (c) 1996-1999 Sun Microsystems, Inc.
Copyright (c) 1997-1999 Metamata, Inc.
(type "jjtree" with no arguments for help)
Reading from file Java1.1.jjt . . .
File "Node.java" does not exist.  Will create one.
File "ASTCompilationUnit.java" does not exist.  Will create one.
File "ASTPackageDeclaration.java" does not exist.  Will create one.
  ... lots more nodes generated here
File "ASTSynchronizedStatement.java" does not exist.  Will create one.
File "ASTTryStatement.java" does not exist.  Will create one.
Annotated grammar generated successfully in Java1.1.jj
trane% 

2) Run JavaCC on the generated grammar.

trane% javacc Java1.1.jj
Java Compiler Compiler Version 2.0 (Parser Generator)
Copyright (c) 1996-1999 Sun Microsystems, Inc.
Copyright (c) 1997-1999 Metamata, Inc.
(type "javacc" with no arguments for help)
Reading from file Java1.1.jj . . .
File "TokenMgrError.java" does not exist.  Will create one.
File "ParseException.java" does not exist.  Will create one.
File "Token.java" does not exist.  Will create one.
File "ASCII_UCodeESC_CharStream.java" does not exist.  Will create one.
Parser generated successfully.
trane% 

3) Ensure that your class path is set up correctly.  The examples
directory (above VTransformer) should be in your class path.

4) Compile the Java files

trane% javac Main.java

5) And finally run it.  It works as a filter now, but it would be
straightforward to make it take file names as arguments.  The
example below shows how to apply the filter on Main.java itself.

trane% java VTransformer.Main < Main.java > Main.new
Reading from standard input...
Thank you.
trane%
