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 * <li>
46 * Each line of text in the text block must be indented at
47 * least as much as the opening and closing quotes.
48 * </li>
49 * </ol>
50 * Note: Closing quotes can be followed by additional code on the same line.
51 *
52 * @since 12.3.0
53 */
54 @StatelessCheck
55 public class TextBlockGoogleStyleFormattingCheck extends AbstractCheck {
56
57 /**
58 * A key is pointing to the warning message text in "messages.properties" file.
59 */
60 public static final String MSG_OPEN_QUOTES_ERROR = "textblock.format.open";
61
62 /**
63 * A key is pointing to the warning message text in "messages.properties" file.
64 */
65 public static final String MSG_CLOSE_QUOTES_ERROR = "textblock.format.close";
66
67 /**
68 * A key is pointing to the warning message text in "messages.properties" file.
69 */
70 public static final String MSG_VERTICALLY_UNALIGNED = "textblock.vertically.unaligned";
71
72 /**
73 * A key is pointing to the warning message text in "messages.properties" file.
74 */
75 public static final String MSG_TEXT_BLOCK_CONTENT = "textblock.indentation";
76
77 /**
78 * Creates a new {@code TextBlockGoogleStyleFormattingCheck} instance.
79 */
80 public TextBlockGoogleStyleFormattingCheck() {
81 // no code by default
82 }
83
84 @Override
85 public int[] getDefaultTokens() {
86 return getRequiredTokens();
87 }
88
89 @Override
90 public int[] getAcceptableTokens() {
91 return getRequiredTokens();
92 }
93
94 @Override
95 public int[] getRequiredTokens() {
96 return new int[] {
97 TokenTypes.TEXT_BLOCK_LITERAL_BEGIN,
98 };
99 }
100
101 @Override
102 public void visitToken(DetailAST ast) {
103 if (!openingQuotesAreAloneOnTheLine(ast)) {
104 log(ast, MSG_OPEN_QUOTES_ERROR);
105 }
106
107 final DetailAST closingQuotes = getClosingQuotes(ast);
108 if (!closingQuotesAreAloneOnTheLine(closingQuotes)) {
109 log(closingQuotes, MSG_CLOSE_QUOTES_ERROR);
110 }
111
112 if (!quotesAreVerticallyAligned(ast, closingQuotes)) {
113 log(closingQuotes, MSG_VERTICALLY_UNALIGNED);
114 }
115
116 if (!isContentIndentedProperly(ast)) {
117 log(ast.getFirstChild(), MSG_TEXT_BLOCK_CONTENT);
118 }
119
120 }
121
122 /**
123 * Checks if opening and closing quotes are vertically aligned.
124 *
125 * @param openQuotes the ast to check.
126 * @param closeQuotes the ast to check.
127 * @return true if both quotes have same indentation else false.
128 */
129 private static boolean quotesAreVerticallyAligned(DetailAST openQuotes, DetailAST closeQuotes) {
130 return openQuotes.getColumnNo() == closeQuotes.getColumnNo();
131 }
132
133 /**
134 * Gets the {@code TEXT_BLOCK_LITERAL_END} of a {@code TEXT_BLOCK_LITERAL_BEGIN}.
135 *
136 * @param ast the ast to check
137 * @return DetailAST {@code TEXT_BLOCK_LITERAL_END}
138 */
139 private static DetailAST getClosingQuotes(DetailAST ast) {
140 return ast.getFirstChild().getNextSibling();
141 }
142
143 /**
144 * Determines if the Opening quotes of text block are not preceded by any code.
145 *
146 * @param openingQuotes opening quotes
147 * @return true if the opening quotes are on the new line.
148 */
149 private static boolean openingQuotesAreAloneOnTheLine(DetailAST openingQuotes) {
150 final DetailAST previousSibling = openingQuotes.getPreviousSibling();
151 boolean quotesAreNotPreceded = previousSibling == null
152 || !TokenUtil.areOnSameLine(openingQuotes, previousSibling);
153 for (DetailAST parent = openingQuotes.getParent(); parent != null;
154 parent = parent.getParent()) {
155 if (!quotesAreNotPreceded || parent.getType() == TokenTypes.ELIST
156 || parent.getType() == TokenTypes.EXPR) {
157 continue;
158 }
159 if (parent.getType() == TokenTypes.METHOD_DEF) {
160 quotesAreNotPreceded = !quotesArePrecededWithComma(openingQuotes);
161 }
162 else {
163 quotesAreNotPreceded = !TokenUtil.areOnSameLine(openingQuotes, parent);
164 }
165 }
166 return quotesAreNotPreceded;
167 }
168
169 /**
170 * Determines if opening quotes are preceded by {@code ,}.
171 *
172 * @param openingQuotes the quotes
173 * @return true if {@code ,} is present before opening quotes.
174 */
175 private static boolean quotesArePrecededWithComma(DetailAST openingQuotes) {
176 final DetailAST expression = openingQuotes.getParent();
177 return expression.getPreviousSibling() != null
178 && TokenUtil.areOnSameLine(openingQuotes, expression.getPreviousSibling());
179 }
180
181 /**
182 * Determines if the Closing quotes of text block are not preceded by any code.
183 *
184 * @param closingQuotes closing quotes
185 * @return true if the closing quotes are on the new line.
186 */
187 private static boolean closingQuotesAreAloneOnTheLine(DetailAST closingQuotes) {
188 final DetailAST content = closingQuotes.getPreviousSibling();
189 final String text = content.getText();
190 int index = text.length() - 1;
191 while (text.charAt(index) == ' ') {
192 index--;
193 }
194 return Character.isWhitespace(text.charAt(index));
195 }
196
197 /**
198 * Determine if the Text Block content indentation is equal or less than
199 * opening quotes indentation.
200 *
201 * @param openingQuotes openingQuotes
202 * @return true if text-block content is properly indented.
203 */
204 private static boolean isContentIndentedProperly(DetailAST openingQuotes) {
205 final int quoteIndent = openingQuotes.getColumnNo();
206 final DetailAST textAst = openingQuotes.getFirstChild();
207 boolean result = true;
208
209 final String[] lines = textAst.getText().split("\n", -1);
210
211 for (String line : lines) {
212
213 int indentation = 0;
214 while (indentation < line.length()
215 && Character.isWhitespace(line.charAt(indentation))) {
216 indentation++;
217 }
218
219 if (indentation < quoteIndent && indentation < line.length()) {
220 result = false;
221 }
222 }
223
224 return result;
225 }
226
227 }