/******************************************************************************* * Copyright (c) 2000, 2006 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package net.sourceforge.phpdt.core.dom; import net.sourceforge.phpdt.core.compiler.InvalidInputException; import net.sourceforge.phpdt.internal.compiler.parser.Scanner; import net.sourceforge.phpdt.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. * For JLS2: *
* Statement: * Block * IfStatement * ForStatement * WhileStatement * DoStatement * TryStatement * SwitchStatement * SynchronizedStatement * ReturnStatement * ThrowStatement * BreakStatement * ContinueStatement * EmptyStatement * ExpressionStatement * LabeledStatement * AssertStatement * VariableDeclarationStatement * TypeDeclarationStatement * ConstructorInvocation * SuperConstructorInvocation ** For JLS3, an enhanced for node type was added: *
* Statement: * Block * IfStatement * ForStatement * EnhancedForStatement * WhileStatement * DoStatement * TryStatement * SwitchStatement * SynchronizedStatement * ReturnStatement * ThrowStatement * BreakStatement * ContinueStatement * EmptyStatement * ExpressionStatement * LabeledStatement * AssertStatement * VariableDeclarationStatement * TypeDeclarationStatement * ConstructorInvocation * SuperConstructorInvocation ** * * @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.
*/
private String optionalLeadingComment = null;
/**
* Creates a new AST node for a statement owned by the given AST.
* * N.B. This constructor is package-private. *
* * @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. *
* * @return the comment string, ornull
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 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
*
*
null
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();
}
}
// 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.
*
* @param source the statement that supplies the leading comment
* @since 2.1
*/
void copyLeadingComment(Statement source) {
setLeadingComment(source.getLeadingComment());
}
/* (omit javadoc for this method)
* Method declared on ASTNode.
*/
int memSize() {
int size = BASE_NODE_SIZE + 1 * 4 + stringSize(getLeadingComment());
return size;
}
}