Copyright (c) 2000, 2019 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
IBM Corporation - initial API and implementation
/*******************************************************************************
* Copyright (c) 2000, 2019 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdt.core.dom;
import org.eclipse.jdt.core.compiler.InvalidInputException;
import org.eclipse.jdt.internal.compiler.parser.Scanner;
import org.eclipse.jdt.internal.compiler.parser.TerminalTokens;
Abstract base class of AST nodes that represent statements.
There are many kinds of statements.
The grammar combines both Statement and BlockStatement.
Statement: AssertStatement, Block, BreakStatement, ConstructorInvocation, ContinueStatement, DoStatement, EmptyStatement, EnhancedForStatement ExpressionStatement, ForStatement, IfStatement, LabeledStatement, ReturnStatement, SuperConstructorInvocation, SwitchCase, SwitchStatement, SynchronizedStatement, ThrowStatement, TryStatement, TypeDeclarationStatement, VariableDeclarationStatement, WhileStatement
Since: 2.0
/**
* Abstract base class of AST nodes that represent statements.
* There are many kinds of statements.
* <p>
* The grammar combines both Statement and BlockStatement.</p>
* <pre>
* Statement:
* {@link AssertStatement},
* {@link Block},
* {@link BreakStatement},
* {@link ConstructorInvocation},
* {@link ContinueStatement},
* {@link DoStatement},
* {@link EmptyStatement},
* {@link EnhancedForStatement}
* {@link ExpressionStatement},
* {@link ForStatement},
* {@link IfStatement},
* {@link LabeledStatement},
* {@link ReturnStatement},
* {@link SuperConstructorInvocation},
* {@link SwitchCase},
* {@link SwitchStatement},
* {@link SynchronizedStatement},
* {@link ThrowStatement},
* {@link TryStatement},
* {@link TypeDeclarationStatement},
* {@link VariableDeclarationStatement},
* {@link WhileStatement}
* </pre>
*
* @since 2.0
*/
public abstract class Statement extends ASTNode {
The leading comment, or null if none.
Defaults to none.
Deprecated: The leading comment feature was removed in 2.1.
/**
* The leading comment, or <code>null</code> if none.
* Defaults to none.
*
* @deprecated The leading comment feature was removed in 2.1.
*/
private String optionalLeadingComment = null;
Creates a new AST node for a statement owned by the given AST.
N.B. This constructor is package-private.
Params: - ast – the AST that is to own this node
/**
* Creates a new AST node for a statement owned by the given AST.
* <p>
* N.B. This constructor is package-private.
* </p>
*
* @param ast the AST that is to own this node
*/
Statement(AST ast) {
super(ast);
}
Returns the leading comment string, including the starting
and ending comment delimiters, and any embedded line breaks.
A leading comment is a comment that appears before the statement.
It may be either a traditional comment or an end-of-line comment.
Traditional comments must begin with "/*, may contain line breaks,
and must end with "*/. End-of-line comments must begin with "//",
must end with a line delimiter (as per JLS 3.7), and must not contain
line breaks.
Returns: the comment string, or null if none Deprecated: This feature was removed in the 2.1 release because it was only a partial, and inadequate, solution to the issue of associating comments with statements. Furthermore, AST.parseCompilationUnit did not associate leading comments, making this moot. Clients that need to access comments preceding a statement should either consult the compilation unit's comment table or use a scanner to reanalyze the source text immediately preceding the statement's source range.
/**
* Returns the leading comment string, including the starting
* and ending comment delimiters, and any embedded line breaks.
* <p>
* A leading comment is a comment that appears before the statement.
* It may be either a traditional comment or an end-of-line comment.
* Traditional comments must begin with "/*, may contain line breaks,
* and must end with "*/. End-of-line comments must begin with "//",
* must end with a line delimiter (as per JLS 3.7), and must not contain
* line breaks.
* </p>
*
* @return the comment string, or <code>null</code> if none
* @deprecated This feature was removed in the 2.1 release because it was
* only a partial, and inadequate, solution to the issue of associating
* comments with statements. Furthermore, AST.parseCompilationUnit did not
* associate leading comments, making this moot. Clients that need to access
* comments preceding a statement should either consult the compilation
* unit's {@linkplain CompilationUnit#getCommentList() comment table}
* or use a scanner to reanalyze the source text immediately preceding
* the statement's source range.
*/
public String getLeadingComment() {
return this.optionalLeadingComment;
}
Sets or clears the leading comment string. The comment
string must include the starting and ending comment delimiters,
and any embedded linebreaks.
A leading comment is a comment that appears before the statement.
It may be either a traditional comment or an end-of-line comment.
Traditional comments must begin with "/*, may contain line breaks,
and must end with "*/. End-of-line comments must begin with "//"
(as per JLS 3.7), and must not contain line breaks.
Examples:
setLeadingComment("/* traditional comment */"); // correct
setLeadingComment("missing comment delimiters"); // wrong
setLeadingComment("/* unterminated traditional comment "); // wrong
setLeadingComment("/* broken\n traditional comment */"); // correct
setLeadingComment("// end-of-line comment\n"); // correct
setLeadingComment("// end-of-line comment without line terminator"); // correct
setLeadingComment("// broken\n end-of-line comment\n"); // wrong
Params: - comment – the comment string, or
null if none
Throws: - IllegalArgumentException – if the comment string is invalid
Deprecated: This feature was removed in the 2.1 release because it was
only a partial, and inadequate, solution to the issue of associating
comments with statements.
/**
* Sets or clears the leading comment string. The comment
* string must include the starting and ending comment delimiters,
* and any embedded linebreaks.
* <p>
* A leading comment is a comment that appears before the statement.
* It may be either a traditional comment or an end-of-line comment.
* Traditional comments must begin with "/*, may contain line breaks,
* and must end with "*/. End-of-line comments must begin with "//"
* (as per JLS 3.7), and must not contain line breaks.
* </p>
* <p>
* Examples:
* <pre>
* <code>
* setLeadingComment("/* traditional comment */"); // correct
* setLeadingComment("missing comment delimiters"); // wrong
* setLeadingComment("/* unterminated traditional comment "); // wrong
* setLeadingComment("/* broken\n traditional comment */"); // correct
* setLeadingComment("// end-of-line comment\n"); // correct
* setLeadingComment("// end-of-line comment without line terminator"); // correct
* setLeadingComment("// broken\n end-of-line comment\n"); // wrong
* </code>
* </pre>
*
* @param comment the comment string, or <code>null</code> if none
* @exception IllegalArgumentException if the comment string is invalid
* @deprecated This feature was removed in the 2.1 release because it was
* only a partial, and inadequate, solution to the issue of associating
* comments with statements.
*/
public void setLeadingComment(String comment) {
if (comment != null) {
char[] source = comment.toCharArray();
Scanner scanner = this.ast.scanner;
scanner.resetTo(0, source.length);
scanner.setSource(source);
try {
int token;
boolean onlyOneComment = false;
while ((token = scanner.getNextToken()) != TerminalTokens.TokenNameEOF) {
switch(token) {
case TerminalTokens.TokenNameCOMMENT_BLOCK :
case TerminalTokens.TokenNameCOMMENT_JAVADOC :
case TerminalTokens.TokenNameCOMMENT_LINE :
if (onlyOneComment) {
throw new IllegalArgumentException();
}
onlyOneComment = true;
break;
default:
onlyOneComment = false;
}
}
if (!onlyOneComment) {
throw new IllegalArgumentException();
}
} catch (InvalidInputException e) {
throw new IllegalArgumentException(e);
}
}
// we do not consider the obsolete comment as a structureal property
// but we protect them nevertheless
checkModifiable();
this.optionalLeadingComment = comment;
}
Copies the leading comment from the given statement.
Params: - source – the statement that supplies the leading comment
Since: 2.1
/**
* Copies the leading comment from the given statement.
*
* @param source the statement that supplies the leading comment
* @since 2.1
*/
void copyLeadingComment(Statement source) {
setLeadingComment(source.getLeadingComment());
}
@Override
int memSize() {
int size = BASE_NODE_SIZE + 1 * 4 + stringSize(getLeadingComment());
return size;
}
}