1 /*
   2  * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.nashorn.api.tree;
  27 
  28 /**
  29  * A visitor of trees, in the style of the visitor design pattern.
  30  * Classes implementing this interface are used to operate
  31  * on a tree when the kind of tree is unknown at compile time.
  32  * When a visitor is passed to an tree's {@link Tree#accept
  33  * accept} method, the <tt>visit<i>XYZ</i></tt> method most applicable
  34  * to that tree is invoked.
  35  *
  36  * <p> Classes implementing this interface may or may not throw a
  37  * {@code NullPointerException} if the additional parameter {@code p}
  38  * is {@code null}; see documentation of the implementing class for
  39  * details.
  40  *
  41  * <p> <b>WARNING:</b> It is possible that methods will be added to
  42  this interface to accommodate new, currently unknown, language
  43  structures added to future versions of the ECMAScript programming
  44  language. When new visit methods are added for new Tree subtypes,
  45  default method bodies will be introduced which will call visitUnknown
  46  method as a fallback.
  47  *
  48  * @param <R> the return type of this visitor's methods.  Use {@link
  49  *            Void} for visitors that do not need to return results.
  50  * @param <P> the type of the additional parameter to this visitor's
  51  *            methods.  Use {@code Void} for visitors that do not need an
  52  *            additional parameter.
  53  *
  54  * @since 1.9
  55  */
  56 @jdk.Exported
  57 public interface TreeVisitor<R,P> {
  58     /**
  59      * Visit assignment tree.
  60      *
  61      * @param node node being visited
  62      * @param p extra parameter passed to the visitor
  63      * @return value from the visitor
  64      */
  65     R visitAssignment(AssignmentTree node, P p);
  66 
  67     /**
  68      * Visit compound assignment tree.
  69      *
  70      * @param node node being visited
  71      * @param p extra parameter passed to the visitor
  72      * @return value from the visitor
  73      */
  74     R visitCompoundAssignment(CompoundAssignmentTree node, P p);
  75 
  76     /**
  77      * Visit binary expression tree.
  78      *
  79      * @param node node being visited
  80      * @param p extra parameter passed to the visitor
  81      * @return value from the visitor
  82      */
  83     R visitBinary(BinaryTree node, P p);
  84 
  85     /**
  86      * Visit block statement tree.
  87      *
  88      * @param node node being visited
  89      * @param p extra parameter passed to the visitor
  90      * @return value from the visitor
  91      */
  92     R visitBlock(BlockTree node, P p);
  93 
  94     /**
  95      * Visit break statement tree.
  96      *
  97      * @param node node being visited
  98      * @param p extra parameter passed to the visitor
  99      * @return value from the visitor
 100      */
 101     R visitBreak(BreakTree node, P p);
 102 
 103     /**
 104      * Visit case statement tree.
 105      *
 106      * @param node node being visited
 107      * @param p extra parameter passed to the visitor
 108      * @return value from the visitor
 109      */
 110     R visitCase(CaseTree node, P p);
 111 
 112     /**
 113      * Visit catch block statement tree.
 114      *
 115      * @param node node being visited
 116      * @param p extra parameter passed to the visitor
 117      * @return value from the visitor
 118      */
 119     R visitCatch(CatchTree node, P p);
 120 
 121     /**
 122      * Visit conditional expression tree.
 123      *
 124      * @param node node being visited
 125      * @param p extra parameter passed to the visitor
 126      * @return value from the visitor
 127      */
 128     R visitConditionalExpression(ConditionalExpressionTree node, P p);
 129 
 130     /**
 131      * Visit continue statement tree.
 132      *
 133      * @param node node being visited
 134      * @param p extra parameter passed to the visitor
 135      * @return value from the visitor
 136      */
 137     R visitContinue(ContinueTree node, P p);
 138 
 139     /**
 140      * Visit debugger statement tree.
 141      *
 142      * @param node node being visited
 143      * @param p extra parameter passed to the visitor
 144      * @return value from the visitor
 145      */
 146     R visitDebugger(DebuggerTree node, P p);
 147 
 148     /**
 149      * Visit do-while statement tree.
 150      *
 151      * @param node node being visited
 152      * @param p extra parameter passed to the visitor
 153      * @return value from the visitor
 154      */
 155     R visitDoWhileLoop(DoWhileLoopTree node, P p);
 156 
 157     /**
 158      * Visit error expression tree.
 159      *
 160      * @param node node being visited
 161      * @param p extra parameter passed to the visitor
 162      * @return value from the visitor
 163      */
 164     R visitErroneous(ErroneousTree node, P p);
 165 
 166     /**
 167      * Visit expression statement tree.
 168      *
 169      * @param node node being visited
 170      * @param p extra parameter passed to the visitor
 171      * @return value from the visitor
 172      */
 173     R visitExpressionStatement(ExpressionStatementTree node, P p);
 174 
 175     /**
 176      * Visit 'for' statement tree.
 177      *
 178      * @param node node being visited
 179      * @param p extra parameter passed to the visitor
 180      * @return value from the visitor
 181      */
 182     R visitForLoop(ForLoopTree node, P p);
 183 
 184     /**
 185      * Visit for..in statement tree.
 186      *
 187      * @param node node being visited
 188      * @param p extra parameter passed to the visitor
 189      * @return value from the visitor
 190      */
 191     R visitForInLoop(ForInLoopTree node, P p);
 192 
 193     /**
 194      * Visit function call expression tree.
 195      *
 196      * @param node node being visited
 197      * @param p extra parameter passed to the visitor
 198      * @return value from the visitor
 199      */
 200     R visitFunctionCall(FunctionCallTree node, P p);
 201 
 202     /**
 203      * Visit function declaration tree.
 204      *
 205      * @param node node being visited
 206      * @param p extra parameter passed to the visitor
 207      * @return value from the visitor
 208      */
 209     R visitFunctionDeclaration(FunctionDeclarationTree node, P p);
 210 
 211     /**
 212      * Visit function expression tree.
 213      *
 214      * @param node node being visited
 215      * @param p extra parameter passed to the visitor
 216      * @return value from the visitor
 217      */
 218     R visitFunctionExpression(FunctionExpressionTree node, P p);
 219 
 220         /**
 221      * Visit identifier tree.
 222      *
 223      * @param node node being visited
 224      * @param p extra parameter passed to the visitor
 225      * @return value from the visitor
 226      */
 227     R visitIdentifier(IdentifierTree node, P p);
 228 
 229     /**
 230      * Visit 'if' statement tree.
 231      *
 232      * @param node node being visited
 233      * @param p extra parameter passed to the visitor
 234      * @return value from the visitor
 235      */
 236     R visitIf(IfTree node, P p);
 237 
 238     /**
 239      * Visit array access expression tree.
 240      *
 241      * @param node node being visited
 242      * @param p extra parameter passed to the visitor
 243      * @return value from the visitor
 244      */
 245     R visitArrayAccess(ArrayAccessTree node, P p);
 246 
 247     /**
 248      * Visit array literal expression tree.
 249      *
 250      * @param node node being visited
 251      * @param p extra parameter passed to the visitor
 252      * @return value from the visitor
 253      */
 254     R visitArrayLiteral(ArrayLiteralTree node, P p);
 255 
 256     /**
 257      * Visit labeled statement tree.
 258      *
 259      * @param node node being visited
 260      * @param p extra parameter passed to the visitor
 261      * @return value from the visitor
 262      */
 263     R visitLabeledStatement(LabeledStatementTree node, P p);
 264 
 265     /**
 266      * Visit literal expression tree.
 267      *
 268      * @param node node being visited
 269      * @param p extra parameter passed to the visitor
 270      * @return value from the visitor
 271      */
 272     R visitLiteral(LiteralTree node, P p);
 273 
 274     /**
 275      * Visit parenthesized expression tree.
 276      *
 277      * @param node node being visited
 278      * @param p extra parameter passed to the visitor
 279      * @return value from the visitor
 280      */
 281     R visitParenthesized(ParenthesizedTree node, P p);
 282 
 283     /**
 284      * Visit return statement tree.
 285      *
 286      * @param node node being visited
 287      * @param p extra parameter passed to the visitor
 288      * @return value from the visitor
 289      */
 290     R visitReturn(ReturnTree node, P p);
 291 
 292     /**
 293      * Visit member select expression tree.
 294      *
 295      * @param node node being visited
 296      * @param p extra parameter passed to the visitor
 297      * @return value from the visitor
 298      */
 299     R visitMemberSelect(MemberSelectTree node, P p);
 300 
 301     /**
 302      * Visit 'new' expression tree.
 303      *
 304      * @param node node being visited
 305      * @param p extra parameter passed to the visitor
 306      * @return value from the visitor
 307      */
 308     R visitNew(NewTree node, P p);
 309 
 310     /**
 311      * Visit object literal tree.
 312      *
 313      * @param node node being visited
 314      * @param p extra parameter passed to the visitor
 315      * @return value from the visitor
 316      */
 317     R visitObjectLiteral(ObjectLiteralTree node, P p);
 318 
 319     /**
 320      * Visit a property of an object literal expression tree.
 321      *
 322      * @param node node being visited
 323      * @param p extra parameter passed to the visitor
 324      * @return value from the visitor
 325      */
 326     R visitProperty(PropertyTree node, P p);
 327 
 328     /**
 329      * Visit regular expression literal tree.
 330      *
 331      * @param node node being visited
 332      * @param p extra parameter passed to the visitor
 333      * @return value from the visitor
 334      */
 335     R visitRegExpLiteral(RegExpLiteralTree node, P p);
 336 
 337     /**
 338      * Visit an empty statement tree.
 339      *
 340      * @param node node being visited
 341      * @param p extra parameter passed to the visitor
 342      * @return value from the visitor
 343      */
 344     R visitEmptyStatement(EmptyStatementTree node, P p);
 345 
 346     /**
 347      * Visit 'switch' statement tree.
 348      *
 349      * @param node node being visited
 350      * @param p extra parameter passed to the visitor
 351      * @return value from the visitor
 352      */
 353     R visitSwitch(SwitchTree node, P p);
 354 
 355     /**
 356      * Visit 'throw' expression tree.
 357      *
 358      * @param node node being visited
 359      * @param p extra parameter passed to the visitor
 360      * @return value from the visitor
 361      */
 362     R visitThrow(ThrowTree node, P p);
 363 
 364     /**
 365      * Visit compilation unit tree.
 366      *
 367      * @param node node being visited
 368      * @param p extra parameter passed to the visitor
 369      * @return value from the visitor
 370      */
 371     R visitCompilationUnit(CompilationUnitTree node, P p);
 372 
 373     /**
 374      * Visit 'try' statement tree.
 375      *
 376      * @param node node being visited
 377      * @param p extra parameter passed to the visitor
 378      * @return value from the visitor
 379      */
 380     R visitTry(TryTree node, P p);
 381 
 382     /**
 383      * Visit 'instanceof' expression tree.
 384      *
 385      * @param node node being visited
 386      * @param p extra parameter passed to the visitor
 387      * @return value from the visitor
 388      */
 389     R visitInstanceOf(InstanceOfTree node, P p);
 390 
 391     /**
 392      * Visit unary expression tree.
 393      *
 394      * @param node node being visited
 395      * @param p extra parameter passed to the visitor
 396      * @return value from the visitor
 397      */
 398     R visitUnary(UnaryTree node, P p);
 399 
 400     /**
 401      * Visit variable declaration tree.
 402      *
 403      * @param node node being visited
 404      * @param p extra parameter passed to the visitor
 405      * @return value from the visitor
 406      */
 407     R visitVariable(VariableTree node, P p);
 408 
 409     /**
 410      * Visit 'while' statement tree.
 411      *
 412      * @param node node being visited
 413      * @param p extra parameter passed to the visitor
 414      * @return value from the visitor
 415      */
 416     R visitWhileLoop(WhileLoopTree node, P p);
 417 
 418     /**
 419      * Visit 'with' statement tree.
 420      *
 421      * @param node node being visited
 422      * @param p extra parameter passed to the visitor
 423      * @return value from the visitor
 424      */
 425     R visitWith(WithTree node, P p);
 426 
 427     /**
 428      * Visit unknown expression/statement tree. This fallback will be
 429      * called if new Tree subtypes are introduced in future. A specific
 430      * implementation may throw {{@linkplain UnknownTreeException unknown tree exception}
 431      * if the visitor implementation was for an older language version.
 432      *
 433      * @param node node being visited
 434      * @param p extra parameter passed to the visitor
 435      * @return value from the visitor
 436      */
 437     R visitUnknown(Tree node, P p);
 438 }