Debian Codegraph @

examples/VTransformer/README

raw
1 /* Copyright (c) 2006, Sun Microsystems, Inc.
2 * All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 *
7 * * Redistributions of source code must retain the above copyright notice,
8 * this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of the Sun Microsystems, Inc. nor the names of its
13 * contributors may be used to endorse or promote products derived from
14 * this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
26 * THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 This directory contains an example of using the Visitor design pattern
30 with JJTree. Like the Transformer example, it shows how a Java
31 program can be processed into a slightly different form.
32
33 In this case the input code is transformed so that each class has a
34 jjtAccept() method inserted. This might be useful for updating node
35 files created with an earlier version of JJTree so that they can be
36 used with the Visitor support.
37
38 Here is an overview of the source files:
39
40 Java1.1.jjt
41
42 This JJTree source file has been slightly modified from the Java 1.1
43 grammar distributed in the JavaGrammars examples directory. Here
44 are the main differences:
45
46 1) Removed the main method from the parser class;
47
48 2) Added a couple of JJTree options;
49
50 3) Made the CompilationUnit production return a root AST node;
51
52 4) Made white space SPECIAL_TOKENs rather than SKIPs;
53
54 These changes illustrate how a JavaCC grammar can be used with
55 JJTree with very little modification. In particular, there are no
56 node annotations -- instead each production in the grammar is
57 represented as a node.
58
59 Main.java
60
61 Simply calls the parser to create the AST, creates a Visitor, and
62 then asks the root node to accept the visitor.
63
64 SimpleNode.java
65
66 This is modified from the automatically generated file. SimpleNodes
67 now maintain their first and last tokens so that the input can be
68 reconstituted. The jjtOpen() and jjtClose() methods are used as
69 hooks to collect and store these tokens. The NODE_USES_PARSER
70 option is specified so that the parser object is available to these
71 methods.
72
73 UnparseVisitor.java
74
75 This is a generally useful Visitor that simply unparses the nodes
76 that it visits. It is intended to be a superclass for
77 transformation-specific Visitors such as AddAcceptVisitor.
78
79 AddAcceptVisitor.java
80
81 This is a Visitor for a particular transformation. It extends
82 UnparseVisitor and overrides methods for those nodes that require
83 special treatment. In this case, only the visit method for
84 ClassBodyDeclaration nodes needs to be overridden.
85
86 The visitor determines whether the node currently being visited is
87 the first child of its parent, and if so it inserts the new text.
88 It makes an attempt to indent the new text at the same level as the
89 current node.
90
91
92 Here's how to build the transformer:
93
94 1) Run the JJTree on the grammar. It will generate many node files
95 because the MULTI option is set.
96
97 trane% jjtree Java1.1.jjt
98 Java Compiler Compiler Version 2.0 (Tree Builder)
99 Copyright (c) 1996-1999 Sun Microsystems, Inc.
100 Copyright (c) 1997-1999 Metamata, Inc.
101 (type "jjtree" with no arguments for help)
102 Reading from file Java1.1.jjt . . .
103 File "Node.java" does not exist. Will create one.
104 File "ASTCompilationUnit.java" does not exist. Will create one.
105 File "ASTPackageDeclaration.java" does not exist. Will create one.
106 ... lots more nodes generated here
107 File "ASTSynchronizedStatement.java" does not exist. Will create one.
108 File "ASTTryStatement.java" does not exist. Will create one.
109 Annotated grammar generated successfully in Java1.1.jj
110 trane%
111
112 2) Run JavaCC on the generated grammar.
113
114 trane% javacc Java1.1.jj
115 Java Compiler Compiler Version 2.0 (Parser Generator)
116 Copyright (c) 1996-1999 Sun Microsystems, Inc.
117 Copyright (c) 1997-1999 Metamata, Inc.
118 (type "javacc" with no arguments for help)
119 Reading from file Java1.1.jj . . .
120 File "TokenMgrError.java" does not exist. Will create one.
121 File "ParseException.java" does not exist. Will create one.
122 File "Token.java" does not exist. Will create one.
123 File "ASCII_UCodeESC_CharStream.java" does not exist. Will create one.
124 Parser generated successfully.
125 trane%
126
127 3) Ensure that your class path is set up correctly. The examples
128 directory (above VTransformer) should be in your class path.
129
130 4) Compile the Java files
131
132 trane% javac Main.java
133
134 5) And finally run it. It works as a filter now, but it would be
135 straightforward to make it take file names as arguments. The
136 example below shows how to apply the filter on Main.java itself.
137
138 trane% java Main < Main.java > Main.new
139 Reading from standard input...
140 Thank you.
141 trane%