Package: org.codehaus.groovy.macro.matcher

## [Groovy] Class ASTMatcher

- org.codehaus.groovy.macro.matcher.ASTMatcher

-     @AutoFinal
      @CompileStatic
      class ASTMatcher
      extends ContextualClassCodeVisitor

  Matches AST nodes against pattern ASTs.

  Since:
    2.5.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static String` | `WILDCARD` | Wildcard marker used in matcher patterns.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `static List<TreeContext>` | `find(ASTNode node, ASTNode pattern)` Locates all nodes in the given AST which match the pattern AST.
    `` | `protected SourceUnit` | `getSourceUnit()` Returns no source unit because AST matching is source-independent.
    `<T>` | `T` | `ifConstraint(T defaultValue, Closure<T> code)` Executes the supplied closure with the current matching constraints as delegate.
    `` | `static boolean` | `matches(ASTNode node, ASTNode pattern)` Matches an AST with another AST (pattern).
    `` | `static Predicate<ASTNode>` | `matching(ASTNode pattern)` Returns a Predicate that tests whether a node matches the supplied pattern AST.
    `` | `void` | `visitAnnotations(AnnotatedNode node)` Matches annotations on the current annotated node.
    `` | `void` | `visitArrayExpression(ArrayExpression expression)` Matches an array expression against the current candidate.
    `` | `void` | `visitAttributeExpression(AttributeExpression expression)` Matches an attribute expression against the current candidate.
    `` | `void` | `visitBinaryExpression(BinaryExpression expression)` Matches a binary expression against the current candidate.
    `` | `void` | `visitBitwiseNegationExpression(BitwiseNegationExpression expression)` Matches a bitwise-negation expression against the current candidate.
    `` | `void` | `visitBlockStatement(BlockStatement block)` Matches a block statement against the current candidate.
    `` | `void` | `visitBooleanExpression(BooleanExpression expression)` Matches a boolean expression against the current candidate.
    `` | `void` | `visitCastExpression(CastExpression expression)` Matches a cast expression against the current candidate.
    `` | `void` | `visitClass(ClassNode node)` Matches a class node against the current candidate.
    `` | `protected void` | `visitClassCodeContainer(Statement code)` Matches a class code container against the current candidate.
    `` | `void` | `visitClassExpression(ClassExpression expression)` Matches a class expression against the current candidate.
    `` | `void` | `visitClosureExpression(ClosureExpression expression)` Matches a closure expression against the current candidate.
    `` | `void` | `visitClosureListExpression(ClosureListExpression cle)` Matches a closure-list expression against the current candidate.
    `` | `void` | `visitConstantExpression(ConstantExpression expression)` Matches a constant expression against the current candidate.
    `` | `void` | `visitConstructorCallExpression(ConstructorCallExpression call)` Matches a constructor call expression against the current candidate.
    `` | `protected void` | `visitConstructorOrMethod(MethodNode node, boolean isConstructor)` Matches a constructor or method node against the current candidate.
    `` | `void` | `visitDeclarationExpression(DeclarationExpression expression)` Matches a declaration expression against the current candidate.
    `` | `void` | `visitExpressionStatement(ExpressionStatement statement)` Matches an expression statement against the current candidate.
    `` | `void` | `visitField(FieldNode node)` Matches a field node against the current candidate.
    `` | `void` | `visitForLoop(ForStatement forLoop)` Matches a for loop against the current candidate.
    `` | `void` | `visitGStringExpression(GStringExpression expression)` Matches a GString expression against the current candidate.
    `` | `void` | `visitIfElse(IfStatement ifElse)` Matches an if/else statement against the current candidate.
    `` | `void` | `visitImports(ModuleNode node)` Matches module imports against the current candidate.
    `` | `void` | `visitListExpression(ListExpression expression)` Matches a list expression against the current candidate.
    `` | `void` | `visitListOfExpressions(List<? extends Expression> list)` Matches a list of expressions against the current candidate list.
    `` | `void` | `visitMapEntryExpression(MapEntryExpression expression)` Matches a map-entry expression against the current candidate.
    `` | `void` | `visitMapExpression(MapExpression expression)` Matches a map expression against the current candidate.
    `` | `void` | `visitMethodCallExpression(MethodCallExpression call)` Matches a method call expression against the current candidate.
    `` | `void` | `visitMethodPointerExpression(MethodPointerExpression expression)` Matches a method-pointer expression against the current candidate.
    `` | `void` | `visitNotExpression(NotExpression expression)` Matches a not expression against the current candidate.
    `` | `protected void` | `visitObjectInitializerStatements(ClassNode node)` Matches object initializer statements for the current class candidate.
    `` | `void` | `visitPackage(PackageNode node)` Matches a package node against the current candidate.
    `` | `void` | `visitPostfixExpression(PostfixExpression expression)` Matches a postfix expression against the current candidate.
    `` | `void` | `visitPrefixExpression(PrefixExpression expression)` Matches a prefix expression against the current candidate.
    `` | `void` | `visitProperty(PropertyNode node)` Matches a property node against the current candidate.
    `` | `void` | `visitPropertyExpression(PropertyExpression expression)` Matches a property expression against the current candidate.
    `` | `void` | `visitRangeExpression(RangeExpression expression)` Matches a range expression against the current candidate.
    `` | `void` | `visitSpreadExpression(SpreadExpression expression)` Matches a spread expression against the current candidate.
    `` | `void` | `visitTernaryExpression(TernaryExpression expression)` Matches a ternary expression against the current candidate.
    `` | `void` | `visitTupleExpression(TupleExpression expression)` Matches a tuple expression against the current candidate.
    `` | `void` | `visitUnaryMinusExpression(UnaryMinusExpression expression)` Matches a unary-minus expression against the current candidate.
    `` | `void` | `visitUnaryPlusExpression(UnaryPlusExpression expression)` Matches a unary-plus expression against the current candidate.
    `` | `void` | `visitVariableExpression(VariableExpression expression)` Matches a variable expression against the current candidate.
    `` | `void` | `visitWhileLoop(WhileStatement loop)` Matches a while loop against the current candidate.
    `` | `static ASTNode` | `withConstraints(ASTNode pattern, Closure constraintsSpec)` Annotates an AST node with matching constraints.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class ContextualClassCodeVisitor` | `getLastContext, getTreeContext, getTreePath, matchByClass, pathMatches, pathUpTo, pathUpTo, pathUpTo, popContext, pushContext, pushContext, visitArrayExpression, visitAssertStatement, visitAttributeExpression, visitBinaryExpression, visitBitwiseNegationExpression, visitBlockStatement, visitBooleanExpression, visitBreakStatement, visitBytecodeExpression, visitCaseStatement, visitCastExpression, visitCatchStatement, visitClass, visitClassExpression, visitClosureExpression, visitClosureListExpression, visitConstantExpression, visitConstructorCallExpression, visitConstructorOrMethod, visitContinueStatement, visitDoWhileLoop, visitEmptyStatement, visitExpressionStatement, visitField, visitFieldExpression, visitForLoop, visitGStringExpression, visitIfElse, visitImports, visitListExpression, visitMapEntryExpression, visitMapExpression, visitMethodCallExpression, visitMethodPointerExpression, visitNotExpression, visitPackage, visitPostfixExpression, visitPrefixExpression, visitProperty, visitPropertyExpression, visitRangeExpression, visitReturnStatement, visitShortTernaryExpression, visitSpreadExpression, visitSpreadMapExpression, visitStaticMethodCallExpression, visitSwitch, visitSwitchExpression, visitSynchronizedStatement, visitTernaryExpression, visitThrowStatement, visitTryCatchFinally, visitTupleExpression, visitUnaryMinusExpression, visitUnaryPlusExpression, visitVariableExpression, visitWhileLoop, visitYieldStatement`
    `class ClassCodeVisitorSupport` | `addError, getSourceUnit, visitAnnotation, visitAnnotations, visitAnnotations, visitAssertStatement, visitBlockStatement, visitBreakStatement, visitCaseStatement, visitCatchStatement, visitClass, visitClassCodeContainer, visitClosureExpression, visitConstructor, visitConstructorOrMethod, visitContinueStatement, visitDeclarationExpression, visitDoWhileLoop, visitExpressionStatement, visitField, visitForLoop, visitIfElse, visitImports, visitMethod, visitObjectInitializerStatements, visitPackage, visitProperty, visitReturnStatement, visitStatement, visitStatementAnnotations, visitSwitch, visitSynchronizedStatement, visitThrowStatement, visitTryCatchFinally, visitWhileLoop, visitYieldStatement`
    `class CodeVisitorSupport` | `afterSwitchCaseStatementsVisited, afterSwitchCaseStatementsVisited, afterSwitchConditionExpressionVisited, afterSwitchConditionExpressionVisited, visitArgumentlistExpression, visitArrayExpression, visitAssertStatement, visitAttributeExpression, visitBinaryExpression, visitBitwiseNegationExpression, visitBlockStatement, visitBooleanExpression, visitBreakStatement, visitBytecodeExpression, visitCaseStatement, visitCastExpression, visitCatchStatement, visitClassExpression, visitClosureExpression, visitClosureListExpression, visitConstantExpression, visitConstructorCallExpression, visitContinueStatement, visitDeclarationExpression, visitDoWhileLoop, visitEmptyStatement, visitExpressionStatement, visitFieldExpression, visitForLoop, visitGStringExpression, visitIfElse, visitLambdaExpression, visitListExpression, visitMapEntryExpression, visitMapExpression, visitMethodCallExpression, visitMethodPointerExpression, visitMethodReferenceExpression, visitNotExpression, visitPostfixExpression, visitPrefixExpression, visitPropertyExpression, visitRangeExpression, visitReturnStatement, visitShortTernaryExpression, visitSpreadExpression, visitSpreadMapExpression, visitStaticMethodCallExpression, visitSwitch, visitSwitchExpression, visitSynchronizedStatement, visitTernaryExpression, visitThrowStatement, visitTryCatchFinally, visitTupleExpression, visitUnaryMinusExpression, visitUnaryPlusExpression, visitVariableExpression, visitWhileLoop, visitYieldStatement`

- - ### Field Detail

    - #### public static final String WILDCARD

      Wildcard marker used in matcher patterns.

  - ### Method Detail

    - #### static List<TreeContext> find(ASTNode node, ASTNode pattern)

      Locates all nodes in the given AST which match the pattern AST. This operation can cost a lot, because it tries to match a sub-tree to every node of the AST.

      Parameters:
        `node` - an AST Node
        `pattern` - a pattern to be found somewhere in the AST
      Returns:
        a list of TreeContext, always not null.

    - #### @Override
      protected SourceUnit getSourceUnit()

      Returns no source unit because AST matching is source-independent.

    - #### <T> T ifConstraint(T defaultValue, @DelegatesTo(value=MatchingConstraints, strategy=Closure.DELEGATE_FIRST)
      Closure<T> code)

      Executes the supplied closure with the current matching constraints as delegate.

      Parameters:
        `defaultValue` - the value to return when no constraints are available
        `code` - the code to execute with the current constraints
      Returns:
        the closure result, or `defaultValue` when no constraints are present

    - #### static boolean matches(ASTNode node, ASTNode pattern)

      Matches an AST with another AST (pattern). It will return true if the AST matches all the nodes from the pattern AST.

      Parameters:
        `node` - the AST we want to match with
        `pattern` - the pattern AST we want to match to
      Returns:
        true if this AST matches the pattern

    - #### static Predicate<ASTNode> matching(ASTNode pattern)

      Returns a Predicate that tests whether a node matches the supplied pattern AST. This is the bridge between exemplar pattern matching and the fluent AstQuery API, letting a pattern be used as a filter:

           import static org.codehaus.groovy.macro.matcher.ASTMatcher.matching
           AstQuery.from(node).descendants(MethodCallExpression).where(matching(macro { _.foo() })).list()

      The predicate reports only whether the shape matches (honouring `_` wildcards); use find(ASTNode, ASTNode) when placeholder bindings need to be extracted.
      Parameters:
        `pattern` - the pattern AST to match candidate nodes against
      Returns:
        a predicate that returns `true` when a node matches the pattern
      Since:
        6.0.0

    - #### @Override
      void visitAnnotations(AnnotatedNode node)

      Matches annotations on the current annotated node.

    - #### @Override
      void visitArrayExpression(ArrayExpression expression)

      Matches an array expression against the current candidate.

    - #### @Override
      void visitAttributeExpression(AttributeExpression expression)

      Matches an attribute expression against the current candidate.

    - #### @Override
      void visitBinaryExpression(BinaryExpression expression)

      Matches a binary expression against the current candidate.

    - #### @Override
      void visitBitwiseNegationExpression(BitwiseNegationExpression expression)

      Matches a bitwise-negation expression against the current candidate.

    - #### @Override
      void visitBlockStatement(BlockStatement block)

      Matches a block statement against the current candidate.

    - #### @Override
      void visitBooleanExpression(BooleanExpression expression)

      Matches a boolean expression against the current candidate.

    - #### @Override
      void visitCastExpression(CastExpression expression)

      Matches a cast expression against the current candidate.

    - #### @Override
      void visitClass(ClassNode node)

      Matches a class node against the current candidate.

    - #### @Override
      protected void visitClassCodeContainer(Statement code)

      Matches a class code container against the current candidate.

    - #### @Override
      @CompileDynamic
      void visitClassExpression(ClassExpression expression)

      Matches a class expression against the current candidate.

    - #### @Override
      void visitClosureExpression(ClosureExpression expression)

      Matches a closure expression against the current candidate.

    - #### @Override
      void visitClosureListExpression(ClosureListExpression cle)

      Matches a closure-list expression against the current candidate.

    - #### @Override
      @CompileDynamic
      void visitConstantExpression(ConstantExpression expression)

      Matches a constant expression against the current candidate.

    - #### @Override
      void visitConstructorCallExpression(ConstructorCallExpression call)

      Matches a constructor call expression against the current candidate.

    - #### @Override
      protected void visitConstructorOrMethod(MethodNode node, boolean isConstructor)

      Matches a constructor or method node against the current candidate.

    - #### @Override
      @CompileDynamic
      void visitDeclarationExpression(DeclarationExpression expression)

      Matches a declaration expression against the current candidate.

    - #### @Override
      void visitExpressionStatement(ExpressionStatement statement)

      Matches an expression statement against the current candidate.

    - #### @Override
      void visitField(FieldNode node)

      Matches a field node against the current candidate.

    - #### @Override
      void visitForLoop(ForStatement forLoop)

      Matches a for loop against the current candidate.

    - #### @Override
      void visitGStringExpression(GStringExpression expression)

      Matches a GString expression against the current candidate.

    - #### @Override
      void visitIfElse(IfStatement ifElse)

      Matches an if/else statement against the current candidate.

    - #### @Override
      void visitImports(ModuleNode node)

      Matches module imports against the current candidate.

    - #### @Override
      void visitListExpression(ListExpression expression)

      Matches a list expression against the current candidate.

    - #### @Override
      void visitListOfExpressions(List<? extends Expression> list)

      Matches a list of expressions against the current candidate list.

    - #### @Override
      void visitMapEntryExpression(MapEntryExpression expression)

      Matches a map-entry expression against the current candidate.

    - #### @Override
      void visitMapExpression(MapExpression expression)

      Matches a map expression against the current candidate.

    - #### @Override
      void visitMethodCallExpression(MethodCallExpression call)

      Matches a method call expression against the current candidate.

    - #### @Override
      void visitMethodPointerExpression(MethodPointerExpression expression)

      Matches a method-pointer expression against the current candidate.

    - #### @Override
      void visitNotExpression(NotExpression expression)

      Matches a not expression against the current candidate.

    - #### @Override
      protected void visitObjectInitializerStatements(ClassNode node)

      Matches object initializer statements for the current class candidate.

    - #### @Override
      void visitPackage(PackageNode node)

      Matches a package node against the current candidate.

    - #### @Override
      void visitPostfixExpression(PostfixExpression expression)

      Matches a postfix expression against the current candidate.

    - #### @Override
      void visitPrefixExpression(PrefixExpression expression)

      Matches a prefix expression against the current candidate.

    - #### @Override
      void visitProperty(PropertyNode node)

      Matches a property node against the current candidate.

    - #### @Override
      void visitPropertyExpression(PropertyExpression expression)

      Matches a property expression against the current candidate.

    - #### @Override
      void visitRangeExpression(RangeExpression expression)

      Matches a range expression against the current candidate.

    - #### @Override
      void visitSpreadExpression(SpreadExpression expression)

      Matches a spread expression against the current candidate.

    - #### @Override
      void visitTernaryExpression(TernaryExpression expression)

      Matches a ternary expression against the current candidate.

    - #### @Override
      void visitTupleExpression(TupleExpression expression)

      Matches a tuple expression against the current candidate.

    - #### @Override
      void visitUnaryMinusExpression(UnaryMinusExpression expression)

      Matches a unary-minus expression against the current candidate.

    - #### @Override
      void visitUnaryPlusExpression(UnaryPlusExpression expression)

      Matches a unary-plus expression against the current candidate.

    - #### @Override
      void visitVariableExpression(VariableExpression expression)

      Matches a variable expression against the current candidate.

    - #### @Override
      void visitWhileLoop(WhileStatement loop)

      Matches a while loop against the current candidate.

    - #### static ASTNode withConstraints(ASTNode pattern, @DelegatesTo(value=MatchingConstraintsBuilder, strategy=Closure.DELEGATE_ONLY)
      Closure constraintsSpec)

      Annotates an AST node with matching constraints. Call this on an AST intended to be used as a pattern only; it attaches node metadata that customises behaviour during pattern matching.

      Parameters:
        `pattern` - a pattern AST
        `constraintsSpec` - a closure specification of matching constraints
      Returns:
        the same pattern, annotated with constraints
      Since:
        2.5.0