| // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file |
| // for details. All rights reserved. Use of this source code is governed by a |
| // BSD-style license that can be found in the LICENSE file. |
| |
| package com.google.dart.compiler.parser; |
| |
| import com.google.dart.compiler.DartCompilationError; |
| import com.google.dart.compiler.DartSource; |
| import com.google.dart.compiler.Source; |
| import com.google.dart.compiler.parser.DartScanner.Location; |
| |
| /** |
| * Abstracts parser and permits marking lexical ranges via event driven methods. Certain IDEs need |
| * more location information than just the source line/column/position of an AST node, such as the |
| * complete set of lexemes that encompass a given node, e.g. function foo() {}} => |
| * [FUNCTION, SPACE, IDENTIFIER, LPAREN, RPAREN, SPACE, LBRACE, RBRACE].This interface allows a |
| * parser to mark the begin and end of each non-terminal AST node in a lexical stream. |
| */ |
| public interface ParserContext { |
| |
| /** |
| * Consume the current token, and advance to the next one, skipping whitespace and comment |
| * tokens. |
| */ |
| void advance(); |
| |
| /** |
| * Called at the beginning of a non-terminal rule. The purpose for this method |
| * is to record any information that might be needed at the end of the rule |
| * (such as the current source position) as well as any state necessary to be |
| * able to roll back to the state just prior to the invocation of this method. |
| * |
| * @see #done(T) |
| * @see #doneWithoutConsuming(T) |
| * @see #rollback() |
| */ |
| void begin(); |
| |
| /** |
| * Called at the end of a non-terminal rule to mark the end of the non-terminal |
| * node. This method consumes any information saved by the {@link #begin()} |
| * method, updating the node with any saved information (such as its position |
| * in the source) as appropriate. |
| * |
| * @param result the non-terminal node being ended |
| * |
| * @return the non-terminal node that should be included in the AST structure, |
| * which is typically the same as the argument |
| * |
| * @see #begin() |
| * @see #doneWithoutConsuming(T) |
| * @see #rollback() |
| */ |
| <T> T done(T result); |
| |
| /** |
| * Called at the end of a non-terminal rule to mark the end of the non-terminal |
| * node. Unlike {@link #done()}, this method does not consume any information |
| * saved by the {@link #begin()} method, but does update the node with any |
| * saved information (such as its position in the source) as appropriate. |
| * |
| * @param result the non-terminal node being ended |
| * |
| * @return the non-terminal node that should be included in the AST structure, |
| * which is typically the same as the argument |
| * |
| * @see #begin() |
| * @see #doneWithoutConsuming(T) |
| * @see #rollback() |
| */ |
| <T> T doneWithoutConsuming(T result); |
| |
| /** |
| * Log a parse error for the current lexical range. |
| * @param dartError helpful error messaging describing what the expected tokens were |
| */ |
| void error(DartCompilationError dartError); |
| |
| /** |
| * Called by the {@link DartParser} before parsing given {@link DartSource}. |
| */ |
| void unitAboutToCompile(DartSource source, boolean diet); |
| |
| /** |
| * Return the current token. |
| */ |
| Token getCurrentToken(); |
| |
| /** |
| * Return Source if present. |
| */ |
| Source getSource(); |
| |
| /** |
| * Return location information for the current token. |
| */ |
| DartScanner.Location getTokenLocation(); |
| |
| /** |
| * Return the string value, if any, of the current token (e.g. IDENTIFIER) |
| */ |
| String getTokenString(); |
| |
| /** |
| * Peek ahead without advancing the lexer. |
| */ |
| Token peek(int steps); |
| |
| /** |
| * Return location information for the token that is 'n' tokens ahead of the current token. |
| */ |
| Location peekTokenLocation(int n); |
| |
| /** |
| * Set the next token to be returned. |
| */ |
| void replaceNextToken(Token token); |
| |
| /** |
| * Rolls back the current token to the position when {@link begin()} was |
| * called. |
| * |
| * @see #begin() |
| * @see #done(T) |
| * @see #doneWithoutConsuming(T) |
| */ |
| void rollback(); |
| |
| /** |
| * Peek ahead, for the value, without advancing the lexer. |
| */ |
| String peekTokenString(int steps); |
| |
| } |