net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/Statement.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2006 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11
  12 package net.sourceforge.phpdt.core.dom;
  13
  14 import net.sourceforge.phpdt.core.compiler.InvalidInputException;
  15 import net.sourceforge.phpdt.internal.compiler.parser.Scanner;
  16 import net.sourceforge.phpdt.internal.compiler.parser.TerminalTokens;
  17
  18 /**
  19  * Abstract base class of AST nodes that represent statements.
  20  * There are many kinds of statements.
  21  * <p>
  22  * The grammar combines both Statement and BlockStatement.
  23  * For JLS2:
  24  * <pre>
  25  * Statement:
  26  *    Block
  27  *    IfStatement
  28  *    ForStatement
  29  *    WhileStatement
  30  *    DoStatement
  31  *    TryStatement
  32  *    SwitchStatement
  33  *    SynchronizedStatement
  34  *    ReturnStatement
  35  *    ThrowStatement
  36  *    BreakStatement
  37  *    ContinueStatement
  38  *    EmptyStatement
  39  *    ExpressionStatement
  40  *    LabeledStatement
  41  *    AssertStatement
  42  *    VariableDeclarationStatement
  43  *    TypeDeclarationStatement
  44  *    ConstructorInvocation
  45  *    SuperConstructorInvocation
  46  * </pre>
  47  * For JLS3, an enhanced for node type was added:
  48  * <pre>
  49  * Statement:
  50  *    Block
  51  *    IfStatement
  52  *    ForStatement
  53  *    EnhancedForStatement
  54  *    WhileStatement
  55  *    DoStatement
  56  *    TryStatement
  57  *    SwitchStatement
  58  *    SynchronizedStatement
  59  *    ReturnStatement
  60  *    ThrowStatement
  61  *    BreakStatement
  62  *    ContinueStatement
  63  *    EmptyStatement
  64  *    ExpressionStatement
  65  *    LabeledStatement
  66  *    AssertStatement
  67  *    VariableDeclarationStatement
  68  *    TypeDeclarationStatement
  69  *    ConstructorInvocation
  70  *    SuperConstructorInvocation
  71  * </pre>
  72  * </p>
  73  *
  74  * @since 2.0
  75  */
  76 public abstract class Statement extends ASTNode {
  77
  78         /**
  79          * The leading comment, or <code>null</code> if none.
  80          * Defaults to none.
  81          *
  82          * @deprecated The leading comment feature was removed in 2.1.
  83          */
  84         private String optionalLeadingComment = null;
  85
  86         /**
  87          * Creates a new AST node for a statement owned by the given AST.
  88          * <p>
  89          * N.B. This constructor is package-private.
  90          * </p>
  91          *
  92          * @param ast the AST that is to own this node
  93          */
  94         Statement(AST ast) {
  95                 super(ast);
  96         }
  97
  98         /**
  99          * Returns the leading comment string, including the starting
 100          * and ending comment delimiters, and any embedded line breaks.
 101          * <p>
 102          * A leading comment is a comment that appears before the statement.
 103          * It may be either a traditional comment or an end-of-line comment.
 104          * Traditional comments must begin with "/&#42;, may contain line breaks,
 105          * and must end with "&#42;/. End-of-line comments must begin with "//",
 106          * must end with a line delimiter (as per JLS 3.7), and must not contain
 107          * line breaks.
 108          * </p>
 109          *
 110          * @return the comment string, or <code>null</code> if none
 111          * @deprecated This feature was removed in the 2.1 release because it was
 112          * only a partial, and inadequate, solution to the issue of associating
 113          * comments with statements. Furthermore, AST.parseCompilationUnit did not
 114          * associate leading comments, making this moot. Clients that need to access
 115          * comments preceding a statement should either consult the compilation
 116          * unit's {@linkplain CompilationUnit#getCommentList() comment table}
 117          * or use a scanner to reanalyze the source text immediately preceding
 118          * the statement's source range.
 119          */
 120         public String getLeadingComment() {
 121                 return optionalLeadingComment;
 122         }
 123
 124         /**
 125          * Sets or clears the leading comment string. The comment
 126          * string must include the starting and ending comment delimiters,
 127          * and any embedded linebreaks.
 128          * <p>
 129          * A leading comment is a comment that appears before the statement.
 130          * It may be either a traditional comment or an end-of-line comment.
 131          * Traditional comments must begin with "/&#42;, may contain line breaks,
 132          * and must end with "&#42;/. End-of-line comments must begin with "//"
 133          * (as per JLS 3.7), and must not contain line breaks.
 134          * </p>
 135          * <p>
 136          * Examples:
 137          * <code>
 138          * <pre>
 139          * setLeadingComment("/&#42; traditional comment &#42;/");  // correct
 140          * setLeadingComment("missing comment delimiters");  // wrong
 141          * setLeadingComment("/&#42; unterminated traditional comment ");  // wrong
 142          * setLeadingComment("/&#42; broken\n traditional comment &#42;/");  // correct
 143          * setLeadingComment("// end-of-line comment\n");  // correct
 144          * setLeadingComment("// end-of-line comment without line terminator");  // correct
 145          * setLeadingComment("// broken\n end-of-line comment\n");  // wrong
 146          * </pre>
 147          * </code>
 148          * </p>
 149          *
 150          * @param comment the comment string, or <code>null</code> if none
 151          * @exception IllegalArgumentException if the comment string is invalid
 152          * @deprecated This feature was removed in the 2.1 release because it was
 153          * only a partial, and inadequate, solution to the issue of associating
 154          * comments with statements.
 155          */
 156         public void setLeadingComment(String comment) {
 157                 if (comment != null) {
 158                         char[] source = comment.toCharArray();
 159                         Scanner scanner = this.ast.scanner;
 160                         scanner.resetTo(0, source.length);
 161                         scanner.setSource(source);
 162                         try {
 163                                 int token;
 164                                 boolean onlyOneComment = false;
 165                                 while ((token = scanner.getNextToken()) != TerminalTokens.TokenNameEOF) {
 166                                         switch(token) {
 167                                                 case TerminalTokens.TokenNameCOMMENT_BLOCK :
 168                                                 case TerminalTokens.TokenNameCOMMENT_JAVADOC :
 169                                                 case TerminalTokens.TokenNameCOMMENT_LINE :
 170                                                         if (onlyOneComment) {
 171                                                                 throw new IllegalArgumentException();
 172                                                         }
 173                                                         onlyOneComment = true;
 174                                                         break;
 175                                                 default:
 176                                                         onlyOneComment = false;
 177                                         }
 178                                 }
 179                                 if (!onlyOneComment) {
 180                                         throw new IllegalArgumentException();
 181                                 }
 182                         } catch (InvalidInputException e) {
 183                                 throw new IllegalArgumentException();
 184                         }
 185                 }
 186                 // we do not consider the obsolete comment as a structureal property
 187                 // but we protect them nevertheless
 188                 checkModifiable();
 189                 this.optionalLeadingComment = comment;
 190         }
 191
 192         /**
 193          * Copies the leading comment from the given statement.
 194          *
 195          * @param source the statement that supplies the leading comment
 196          * @since 2.1
 197          */
 198         void copyLeadingComment(Statement source) {
 199                 setLeadingComment(source.getLeadingComment());
 200         }
 201
 202         /* (omit javadoc for this method)
 203          * Method declared on ASTNode.
 204          */
 205         int memSize() {
 206                 int size = BASE_NODE_SIZE + 1 * 4 + stringSize(getLeadingComment());
 207                 return size;
 208         }
 209 }
 210