1/*
2 [The "BSD license"]
3 Copyright (c) 2005-2009 Terence Parr
4 All rights reserved.
5
6 Redistribution and use in source and binary forms, with or without
7 modification, are permitted provided that the following conditions
8 are met:
9 1. Redistributions of source code must retain the above copyright
10     notice, this list of conditions and the following disclaimer.
11 2. Redistributions in binary form must reproduce the above copyright
12     notice, this list of conditions and the following disclaimer in the
13     documentation and/or other materials provided with the distribution.
14 3. The name of the author may not be used to endorse or promote products
15     derived from this software without specific prior written permission.
16
17 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28package org.antlr.runtime.tree;
29
30import org.antlr.runtime.RecognizerSharedState;
31import org.antlr.runtime.RecognitionException;
32import org.antlr.runtime.TokenStream;
33
34/**
35 Cut-n-paste from material I'm not using in the book anymore (edit later
36 to make sense):
37
38 Now, how are we going to test these tree patterns against every
39subtree in our original tree?  In what order should we visit nodes?
40For this application, it turns out we need a simple ``apply once''
41rule application strategy and a ``down then up'' tree traversal
42strategy.  Let's look at rule application first.
43
44As we visit each node, we need to see if any of our patterns match. If
45a pattern matches, we execute the associated tree rewrite and move on
46to the next node. In other words, we only look for a single rule
47application opportunity (we'll see below that we sometimes need to
48repeatedly apply rules). The following method applies a rule in a @cl
49TreeParser (derived from a tree grammar) to a tree:
50
51here is where weReferenced code/walking/patterns/TreePatternMatcher.java
52
53It uses reflection to lookup the appropriate rule within the generated
54tree parser class (@cl Simplify in this case). Most of the time, the
55rule will not match the tree.  To avoid issuing syntax errors and
56attempting error recovery, it bumps up the backtracking level.  Upon
57failure, the invoked rule immediately returns. If you don't plan on
58using this technique in your own ANTLR-based application, don't sweat
59the details. This method boils down to ``call a rule to match a tree,
60executing any embedded actions and rewrite rules.''
61
62At this point, we know how to define tree grammar rules and how to
63apply them to a particular subtree. The final piece of the tree
64pattern matcher is the actual tree traversal. We have to get the
65correct node visitation order.  In particular, we need to perform the
66scalar-vector multiply transformation on the way down (preorder) and
67we need to reduce multiply-by-zero subtrees on the way up (postorder).
68
69To implement a top-down visitor, we do a depth first walk of the tree,
70executing an action in the preorder position. To get a bottom-up
71visitor, we execute an action in the postorder position.  ANTLR
72provides a standard @cl TreeVisitor class with a depth first search @v
73visit method. That method executes either a @m pre or @m post method
74or both. In our case, we need to call @m applyOnce in both. On the way
75down, we'll look for @r vmult patterns. On the way up,
76we'll look for @r mult0 patterns.
77 */
78public class TreeFilter extends TreeParser {
79    public interface fptr {
80        public void rule() throws RecognitionException;
81    }
82
83    protected TokenStream originalTokenStream;
84    protected TreeAdaptor originalAdaptor;
85
86    public TreeFilter(TreeNodeStream input) {
87        this(input, new RecognizerSharedState());
88    }
89    public TreeFilter(TreeNodeStream input, RecognizerSharedState state) {
90        super(input, state);
91        originalAdaptor = input.getTreeAdaptor();
92        originalTokenStream = input.getTokenStream();
93    }
94
95    public void applyOnce(Object t, fptr whichRule) {
96        if ( t==null ) return;
97        try {
98            // share TreeParser object but not parsing-related state
99            state = new RecognizerSharedState();
100            input = new CommonTreeNodeStream(originalAdaptor, t);
101            ((CommonTreeNodeStream)input).setTokenStream(originalTokenStream);
102            setBacktrackingLevel(1);
103            whichRule.rule();
104            setBacktrackingLevel(0);
105        }
106        catch (RecognitionException e) { ; }
107    }
108
109    public void downup(Object t) {
110        TreeVisitor v = new TreeVisitor(new CommonTreeAdaptor());
111        TreeVisitorAction actions = new TreeVisitorAction() {
112            public Object pre(Object t)  { applyOnce(t, topdown_fptr); return t; }
113            public Object post(Object t) { applyOnce(t, bottomup_fptr); return t; }
114        };
115        v.visit(t, actions);
116    }
117
118    fptr topdown_fptr = new fptr() {
119        public void rule() throws RecognitionException {
120            topdown();
121        }
122    };
123
124    fptr bottomup_fptr = new fptr() {
125        public void rule() throws RecognitionException {
126            bottomup();
127        }
128    };
129
130    // methods the downup strategy uses to do the up and down rules.
131    // to override, just define tree grammar rule topdown and turn on
132    // filter=true.
133    public void topdown() throws RecognitionException {;}
134    public void bottomup() throws RecognitionException {;}
135}
136