1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2026 the original author or authors.
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 ///////////////////////////////////////////////////////////////////////////////////////////////
19
20 package com.puppycrawl.tools.checkstyle.checks.coding;
21
22 import com.puppycrawl.tools.checkstyle.StatelessCheck;
23 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
24 import com.puppycrawl.tools.checkstyle.api.DetailAST;
25 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
26 import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
27
28 /**
29 * <div>
30 * Checks correct format of
31 * <a href="https://docs.oracle.com/en/java/javase/17/text-blocks/index.html">Java Text Blocks</a>
32 * as specified in
33 * <a href="https://google.github.io/styleguide/javaguide.html#s4.8.9-text-blocks">
34 * Google Java Style Guide</a>.
35 * </div>
36 * This Check performs two validations:
37 * <ol>
38 * <li>
39 * It ensures that the opening and closing text-block quotes ({@code """}) each appear on their
40 * own line, with no other item preceding them.
41 * </li>
42 * <li>
43 * Opening and closing quotes are vertically aligned.
44 * </li>
45 * </ol>
46 * Note: Closing quotes can be followed by additional code on the same line.
47 *
48 * @since 12.3.0
49 */
50 @StatelessCheck
51 public class TextBlockGoogleStyleFormattingCheck extends AbstractCheck {
52
53 /**
54 * A key is pointing to the warning message text in "messages.properties" file.
55 */
56 public static final String MSG_OPEN_QUOTES_ERROR = "textblock.format.open";
57
58 /**
59 * A key is pointing to the warning message text in "messages.properties" file.
60 */
61 public static final String MSG_CLOSE_QUOTES_ERROR = "textblock.format.close";
62
63 /**
64 * A key is pointing to the warning message text in "messages.properties" file.
65 */
66 public static final String MSG_VERTICALLY_UNALIGNED = "textblock.vertically.unaligned";
67
68 @Override
69 public int[] getDefaultTokens() {
70 return getRequiredTokens();
71 }
72
73 @Override
74 public int[] getAcceptableTokens() {
75 return getRequiredTokens();
76 }
77
78 @Override
79 public int[] getRequiredTokens() {
80 return new int[] {
81 TokenTypes.TEXT_BLOCK_LITERAL_BEGIN,
82 };
83 }
84
85 @Override
86 public void visitToken(DetailAST ast) {
87 if (!openingQuotesAreAloneOnTheLine(ast)) {
88 log(ast, MSG_OPEN_QUOTES_ERROR);
89 }
90
91 final DetailAST closingQuotes = getClosingQuotes(ast);
92 if (!closingQuotesAreAloneOnTheLine(closingQuotes)) {
93 log(closingQuotes, MSG_CLOSE_QUOTES_ERROR);
94 }
95
96 if (!quotesAreVerticallyAligned(ast, closingQuotes)) {
97 log(closingQuotes, MSG_VERTICALLY_UNALIGNED);
98 }
99 }
100
101 /**
102 * Checks if opening and closing quotes are vertically aligned.
103 *
104 * @param openQuotes the ast to check.
105 * @param closeQuotes the ast to check.
106 * @return true if both quotes have same indentation else false.
107 */
108 private static boolean quotesAreVerticallyAligned(DetailAST openQuotes, DetailAST closeQuotes) {
109 return openQuotes.getColumnNo() == closeQuotes.getColumnNo();
110 }
111
112 /**
113 * Gets the {@code TEXT_BLOCK_LITERAL_END} of a {@code TEXT_BLOCK_LITERAL_BEGIN}.
114 *
115 * @param ast the ast to check
116 * @return DetailAST {@code TEXT_BLOCK_LITERAL_END}
117 */
118 private static DetailAST getClosingQuotes(DetailAST ast) {
119 return ast.getFirstChild().getNextSibling();
120 }
121
122 /**
123 * Determines if the Opening quotes of text block are not preceded by any code.
124 *
125 * @param openingQuotes opening quotes
126 * @return true if the opening quotes are on the new line.
127 */
128 private static boolean openingQuotesAreAloneOnTheLine(DetailAST openingQuotes) {
129 DetailAST parent = openingQuotes;
130 boolean quotesAreNotPreceded = true;
131 while (quotesAreNotPreceded || parent.getType() == TokenTypes.ELIST
132 || parent.getType() == TokenTypes.EXPR) {
133
134 parent = parent.getParent();
135
136 if (parent.getType() == TokenTypes.METHOD_DEF) {
137 quotesAreNotPreceded = !quotesArePrecededWithComma(openingQuotes);
138 }
139 else if (parent.getType() == TokenTypes.QUESTION
140 && openingQuotes.getPreviousSibling() != null) {
141 quotesAreNotPreceded = !TokenUtil.areOnSameLine(openingQuotes,
142 openingQuotes.getPreviousSibling());
143 }
144 else {
145 quotesAreNotPreceded = !TokenUtil.areOnSameLine(openingQuotes, parent);
146 }
147
148 if (TokenUtil.isOfType(parent.getType(),
149 TokenTypes.LITERAL_RETURN,
150 TokenTypes.VARIABLE_DEF,
151 TokenTypes.METHOD_DEF,
152 TokenTypes.CTOR_DEF,
153 TokenTypes.ENUM_DEF,
154 TokenTypes.CLASS_DEF)) {
155 break;
156 }
157 }
158 return quotesAreNotPreceded;
159 }
160
161 /**
162 * Determines if opening quotes are preceded by {@code ,}.
163 *
164 * @param openingQuotes the quotes
165 * @return true if {@code ,} is present before opening quotes.
166 */
167 private static boolean quotesArePrecededWithComma(DetailAST openingQuotes) {
168 final DetailAST expression = openingQuotes.getParent();
169 return expression.getPreviousSibling() != null
170 && TokenUtil.areOnSameLine(openingQuotes, expression.getPreviousSibling());
171 }
172
173 /**
174 * Determines if the Closing quotes of text block are not preceded by any code.
175 *
176 * @param closingQuotes closing quotes
177 * @return true if the closing quotes are on the new line.
178 */
179 private static boolean closingQuotesAreAloneOnTheLine(DetailAST closingQuotes) {
180 final DetailAST content = closingQuotes.getPreviousSibling();
181 final String text = content.getText();
182 int index = text.length() - 1;
183 while (text.charAt(index) == ' ') {
184 index--;
185 }
186 return Character.isWhitespace(text.charAt(index));
187 }
188 }