001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2025 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.api; 021 022import javax.annotation.Nullable; 023 024/** 025 * An interface of Checkstyle's AST nodes for traversing trees generated from the 026 * Java code. The main purpose of this interface is to abstract away ANTLR 027 * specific classes from API package so other libraries won't require it. 028 * 029 * @see <a href="https://www.antlr.org/">ANTLR Website</a> 030 */ 031public interface DetailAST { 032 033 /** 034 * Returns the number of child nodes one level below this node. That is, 035 * does not recurse down the tree. 036 * 037 * @return the number of child nodes 038 */ 039 int getChildCount(); 040 041 /** 042 * Returns the number of direct child tokens that have the specified type. 043 * 044 * @param type the token type to match 045 * @return the number of matching token 046 */ 047 int getChildCount(int type); 048 049 /** 050 * Returns the parent token. 051 * 052 * @return the parent token 053 */ 054 DetailAST getParent(); 055 056 /** 057 * Gets the text of this AST. 058 * 059 * @return the text. 060 */ 061 String getText(); 062 063 /** 064 * Gets the type of this AST. 065 * 066 * @return the type. 067 */ 068 int getType(); 069 070 /** 071 * Gets line number. 072 * 073 * @return the line number 074 */ 075 int getLineNo(); 076 077 /** 078 * Gets column number. 079 * 080 * @return the column number 081 */ 082 int getColumnNo(); 083 084 /** 085 * Gets the last child node. 086 * 087 * @return the last child node 088 */ 089 DetailAST getLastChild(); 090 091 /** 092 * Checks if this branch of the parse tree contains a token 093 * of the provided type. 094 * 095 * @param type a TokenType 096 * @return true if and only if this branch (including this node) 097 * contains a token of type {@code type}. 098 * @deprecated 099 * Usage of this method is no longer accepted. We encourage 100 * traversal of subtrees to be written per the needs of each check 101 * to avoid unintended side effects. 102 * @noinspection DeprecatedIsStillUsed, RedundantSuppression 103 * @noinspectionreason DeprecatedIsStillUsed - Method used in unit testing 104 * @noinspectionreason RedundantSuppression - Inspections shows false positive for 105 * redundant suppression, see 106 * <a href="https://github.com/checkstyle/checkstyle/issues/12359">here</a> 107 * for more details. 108 */ 109 @Deprecated(since = "8.43") 110 boolean branchContains(int type); 111 112 /** 113 * Returns the previous sibling or null if no such sibling exists. 114 * 115 * @return the previous sibling or null if no such sibling exists. 116 */ 117 DetailAST getPreviousSibling(); 118 119 /** 120 * Returns the first child token that makes a specified type. 121 * 122 * @param type the token type to match 123 * @return the matching token, or null if no match 124 */ 125 @Nullable 126 DetailAST findFirstToken(int type); 127 128 /** 129 * Get the next sibling in line after this one. 130 * 131 * @return the next sibling or null if none. 132 */ 133 DetailAST getNextSibling(); 134 135 /** 136 * Get the first child of this AST. 137 * 138 * @return the first child or null if none. 139 */ 140 DetailAST getFirstChild(); 141 142 /** 143 * Get number of children of this AST. 144 * 145 * @return the number of children. 146 * @deprecated This method will be removed in a future release. 147 * Use {@link #getChildCount()} instead. 148 */ 149 @Deprecated(since = "8.30") 150 int getNumberOfChildren(); 151 152 /** 153 * Returns whether this AST has any children. 154 * 155 * @return {@code true} if this AST has any children. 156 */ 157 boolean hasChildren(); 158}