Skip to content

Commit

Permalink
Merge pull request #1976 from hanjoes/doc
Browse files Browse the repository at this point in the history 
Swift Documentations
  • Loading branch information
@parrt
parrt authored Jul 30, 2017
2 parents 0ff5ad6 + 22caddc commit 752d4d5
Show file tree
Hide file tree
Showing 152 changed files with 5,991 additions and 4,971 deletions.
124 changes: 67 additions & 57 deletions runtime/Swift/Sources/Antlr4/ANTLRErrorListener.swift
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,31 @@
///
/// Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
/// Use of this file is governed by the BSD 3-clause license that
/// can be found in the LICENSE.txt file in the project root.
/// How to emit recognition errors.
///

public protocol ANTLRErrorListener: class {
///
/// Upon syntax error, notify any interested parties. This is not how to
/// recover from errors or compute error messages. {@link org.antlr.v4.runtime.ANTLRErrorStrategy}
/// recover from errors or compute error messages. _org.antlr.v4.runtime.ANTLRErrorStrategy_
/// specifies how to recover from syntax errors and how to compute error
/// messages. This listener's job is simply to emit a computed message,
/// though it has enough information to create its own message in many cases.
///
/// <p>The {@link org.antlr.v4.runtime.RecognitionException} is non-null for all syntax errors except
///
/// The _RecognitionException_ is non-null for all syntax errors except
/// when we discover mismatched token errors that we can recover from
/// in-line, without returning from the surrounding rule (via the single
/// token insertion and deletion mechanism).</p>
///
/// token insertion and deletion mechanism).
///
/// - parameter recognizer:
/// What parser got the error. From this
/// object, you can access the context as well
/// as the input stream.
/// - parameter offendingSymbol:
/// The offending token in the input token
/// stream, unless recognizer is a lexer (then it's null). If
/// no viable alternative error, {@code e} has token at which we
/// no viable alternative error, `e` has token at which we
/// started production for the decision.
/// - parameter line:
/// The line number in the input where the error occurred.
Expand All @@ -35,52 +38,55 @@ public protocol ANTLRErrorListener: class {
/// the reporting of an error. It is null in the case where
/// the parser was able to recover in line without exiting the
/// surrounding rule.
///
func syntaxError<T:ATNSimulator>(_ recognizer: Recognizer<T>,
_ offendingSymbol: AnyObject?,
_ line: Int,
_ charPositionInLine: Int,
_ msg: String,
_ e: AnyObject?// RecognitionException?
_ e: AnyObject?
)

///
/// This method is called by the parser when a full-context prediction
/// results in an ambiguity.
///
/// <p>Each full-context prediction which does not result in a syntax error
/// will call either {@link #reportContextSensitivity} or
/// {@link #reportAmbiguity}.</p>
///
/// <p>When {@code ambigAlts} is not null, it contains the set of potentially
///
/// Each full-context prediction which does not result in a syntax error
/// will call either _#reportContextSensitivity_ or
/// _#reportAmbiguity_.
///
/// When `ambigAlts` is not null, it contains the set of potentially
/// viable alternatives identified by the prediction algorithm. When
/// {@code ambigAlts} is null, use {@link org.antlr.v4.runtime.atn.ATNConfigSet#getAlts} to obtain the
/// represented alternatives from the {@code configs} argument.</p>
///
/// <p>When {@code exact} is {@code true}, <em>all</em> of the potentially
/// `ambigAlts` is null, use _org.antlr.v4.runtime.atn.ATNConfigSet#getAlts_ to obtain the
/// represented alternatives from the `configs` argument.
///
/// When `exact` is `true`, __all__ of the potentially
/// viable alternatives are truly viable, i.e. this is reporting an exact
/// ambiguity. When {@code exact} is {@code false}, <em>at least two</em> of
/// ambiguity. When `exact` is `false`, __at least two__ of
/// the potentially viable alternatives are viable for the current input, but
/// the prediction algorithm terminated as soon as it determined that at
/// least the <em>minimum</em> potentially viable alternative is truly
/// viable.</p>
///
/// <p>When the {@link org.antlr.v4.runtime.atn.PredictionMode#LL_EXACT_AMBIG_DETECTION} prediction
/// least the __minimum__ potentially viable alternative is truly
/// viable.
///
/// When the _org.antlr.v4.runtime.atn.PredictionMode#LL_EXACT_AMBIG_DETECTION_ prediction
/// mode is used, the parser is required to identify exact ambiguities so
/// {@code exact} will always be {@code true}.</p>
///
/// <p>This method is not used by lexers.</p>
///
/// `exact` will always be `true`.
///
/// This method is not used by lexers.
///
/// - parameter recognizer: the parser instance
/// - parameter dfa: the DFA for the current decision
/// - parameter startIndex: the input index where the decision started
/// - parameter stopIndex: the input input where the ambiguity was identified
/// - parameter exact: {@code true} if the ambiguity is exactly known, otherwise
/// {@code false}. This is always {@code true} when
/// {@link org.antlr.v4.runtime.atn.PredictionMode#LL_EXACT_AMBIG_DETECTION} is used.
/// - parameter ambigAlts: the potentially ambiguous alternatives, or {@code null}
/// - parameter exact: `true` if the ambiguity is exactly known, otherwise
/// `false`. This is always `true` when
/// _org.antlr.v4.runtime.atn.PredictionMode#LL_EXACT_AMBIG_DETECTION_ is used.
/// - parameter ambigAlts: the potentially ambiguous alternatives, or `null`
/// to indicate that the potentially ambiguous alternatives are the complete
/// set of represented alternatives in {@code configs}
/// set of represented alternatives in `configs`
/// - parameter configs: the ATN configuration set where the ambiguity was
/// identified
///
func reportAmbiguity(_ recognizer: Parser,
_ dfa: DFA,
_ startIndex: Int,
Expand All @@ -89,62 +95,65 @@ public protocol ANTLRErrorListener: class {
_ ambigAlts: BitSet,
_ configs: ATNConfigSet) throws

///
/// This method is called when an SLL conflict occurs and the parser is about
/// to use the full context information to make an LL decision.
///
/// <p>If one or more configurations in {@code configs} contains a semantic
///
/// If one or more configurations in `configs` contains a semantic
/// predicate, the predicates are evaluated before this method is called. The
/// subset of alternatives which are still viable after predicates are
/// evaluated is reported in {@code conflictingAlts}.</p>
///
/// <p>This method is not used by lexers.</p>
///
/// evaluated is reported in `conflictingAlts`.
///
/// This method is not used by lexers.
///
/// - parameter recognizer: the parser instance
/// - parameter dfa: the DFA for the current decision
/// - parameter startIndex: the input index where the decision started
/// - parameter stopIndex: the input index where the SLL conflict occurred
/// - parameter conflictingAlts: The specific conflicting alternatives. If this is
/// {@code null}, the conflicting alternatives are all alternatives
/// represented in {@code configs}. At the moment, conflictingAlts is non-null
/// `null`, the conflicting alternatives are all alternatives
/// represented in `configs`. At the moment, conflictingAlts is non-null
/// (for the reference implementation, but Sam's optimized version can see this
/// as null).
/// - parameter configs: the ATN configuration set where the SLL conflict was
/// detected
///
func reportAttemptingFullContext(_ recognizer: Parser,
_ dfa: DFA,
_ startIndex: Int,
_ stopIndex: Int,
_ conflictingAlts: BitSet?,
_ configs: ATNConfigSet) throws

///
/// This method is called by the parser when a full-context prediction has a
/// unique result.
///
/// <p>Each full-context prediction which does not result in a syntax error
/// will call either {@link #reportContextSensitivity} or
/// {@link #reportAmbiguity}.</p>
///
/// <p>For prediction implementations that only evaluate full-context
///
/// Each full-context prediction which does not result in a syntax error
/// will call either _#reportContextSensitivity_ or
/// _#reportAmbiguity_.
///
/// For prediction implementations that only evaluate full-context
/// predictions when an SLL conflict is found (including the default
/// {@link org.antlr.v4.runtime.atn.ParserATNSimulator} implementation), this method reports cases
/// _org.antlr.v4.runtime.atn.ParserATNSimulator_ implementation), this method reports cases
/// where SLL conflicts were resolved to unique full-context predictions,
/// i.e. the decision was context-sensitive. This report does not necessarily
/// indicate a problem, and it may appear even in completely unambiguous
/// grammars.</p>
///
/// <p>{@code configs} may have more than one represented alternative if the
/// grammars.
///
/// `configs` may have more than one represented alternative if the
/// full-context prediction algorithm does not evaluate predicates before
/// beginning the full-context prediction. In all cases, the final prediction
/// is passed as the {@code prediction} argument.</p>
///
/// <p>Note that the definition of "context sensitivity" in this method
/// differs from the concept in {@link org.antlr.v4.runtime.atn.DecisionInfo#contextSensitivities}.
/// is passed as the `prediction` argument.
///
/// Note that the definition of "context sensitivity" in this method
/// differs from the concept in _org.antlr.v4.runtime.atn.DecisionInfo#contextSensitivities_.
/// This method reports all instances where an SLL conflict occurred but LL
/// parsing produced a unique result, whether or not that unique result
/// matches the minimum alternative in the SLL conflicting set.</p>
///
/// <p>This method is not used by lexers.</p>
///
/// matches the minimum alternative in the SLL conflicting set.
///
/// This method is not used by lexers.
///
/// - parameter recognizer: the parser instance
/// - parameter dfa: the DFA for the current decision
/// - parameter startIndex: the input index where the decision started
Expand All @@ -153,6 +162,7 @@ public protocol ANTLRErrorListener: class {
/// - parameter prediction: the unambiguous result of the full-context prediction
/// - parameter configs: the ATN configuration set where the unambiguous prediction
/// was determined
///
func reportContextSensitivity(_ recognizer: Parser,
_ dfa: DFA,
_ startIndex: Int,
Expand Down
128 changes: 74 additions & 54 deletions runtime/Swift/Sources/Antlr4/ANTLRErrorStrategy.swift
View file
Original file line number Diff line number Diff line change
@@ -1,99 +1,119 @@
///
///
/// Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
/// Use of this file is governed by the BSD 3-clause license that
/// can be found in the LICENSE.txt file in the project root.
/// The interface for defining strategies to deal with syntax errors encountered
/// during a parse by ANTLR-generated parsers. We distinguish between three
///
///


///
///
/// The interface for defining strategies to deal with syntax errors
/// encountered during a parse by ANTLR-generated parsers. We distinguish between three
/// different kinds of errors:
///
/// <ul>
/// <li>The parser could not figure out which path to take in the ATN (none of
/// the available alternatives could possibly match)</li>
/// <li>The current input does not match what we were looking for</li>
/// <li>A predicate evaluated to false</li>
/// </ul>
///
///
/// * The parser could not figure out which path to take in the ATN (none of
/// the available alternatives could possibly match)
/// * The current input does not match what we were looking for
/// * A predicate evaluated to false
///
/// Implementations of this interface report syntax errors by calling
/// {@link org.antlr.v4.runtime.Parser#notifyErrorListeners}.
///
/// <p>TODO: what to do about lexers</p>

/// _org.antlr.v4.runtime.Parser#notifyErrorListeners_.
///
/// TODO: what to do about lexers
///
public protocol ANTLRErrorStrategy {
/// Reset the error handler state for the specified {@code recognizer}.
///
/// Reset the error handler state for the specified `recognizer`.
/// - parameter recognizer: the parser instance
///
func reset(_ recognizer: Parser)

///
/// This method is called when an unexpected symbol is encountered during an
/// inline match operation, such as {@link org.antlr.v4.runtime.Parser#match}. If the error
/// inline match operation, such as _org.antlr.v4.runtime.Parser#match_. If the error
/// strategy successfully recovers from the match failure, this method
/// returns the {@link org.antlr.v4.runtime.Token} instance which should be treated as the
/// returns the _org.antlr.v4.runtime.Token_ instance which should be treated as the
/// successful result of the match.
///
/// <p>This method handles the consumption of any tokens - the caller should
/// <b>not</b> call {@link org.antlr.v4.runtime.Parser#consume} after a successful recovery.</p>
///
/// <p>Note that the calling code will not report an error if this method
///
/// This method handles the consumption of any tokens - the caller should
/// __not__ call _org.antlr.v4.runtime.Parser#consume_ after a successful recovery.
///
/// Note that the calling code will not report an error if this method
/// returns successfully. The error strategy implementation is responsible
/// for calling {@link org.antlr.v4.runtime.Parser#notifyErrorListeners} as appropriate.</p>
///
/// for calling _org.antlr.v4.runtime.Parser#notifyErrorListeners_ as appropriate.
///
/// - parameter recognizer: the parser instance
/// - org.antlr.v4.runtime.RecognitionException if the error strategy was not able to
/// - throws: _RecognitionException_ if the error strategy was not able to
/// recover from the unexpected input symbol
///
@discardableResult
func recoverInline(_ recognizer: Parser) throws -> Token // RecognitionException;
func recoverInline(_ recognizer: Parser) throws -> Token

/// This method is called to recover from exception {@code e}. This method is
/// called after {@link #reportError} by the default exception handler
///
/// This method is called to recover from exception `e`. This method is
/// called after _#reportError_ by the default exception handler
/// generated for a rule method.
///
///
/// - seealso: #reportError
///
///
/// - parameter recognizer: the parser instance
/// - parameter e: the recognition exception to recover from
/// - org.antlr.v4.runtime.RecognitionException if the error strategy could not recover from
/// - throws: _RecognitionException_ if the error strategy could not recover from
/// the recognition exception
func recover(_ recognizer: Parser, _ e: AnyObject) throws // RecognitionException;
///
func recover(_ recognizer: Parser, _ e: AnyObject) throws

///
/// This method provides the error handler with an opportunity to handle
/// syntactic or semantic errors in the input stream before they result in a
/// {@link org.antlr.v4.runtime.RecognitionException}.
///
/// <p>The generated code currently contains calls to {@link #sync} after
/// entering the decision state of a closure block ({@code (...)*} or
/// {@code (...)+}).</p>
///
/// <p>For an implementation based on Jim Idle's "magic sync" mechanism, see
/// {@link org.antlr.v4.runtime.DefaultErrorStrategy#sync}.</p>
///
/// _org.antlr.v4.runtime.RecognitionException_.
///
/// The generated code currently contains calls to _#sync_ after
/// entering the decision state of a closure block (`(...)*` or
/// `(...)+`).
///
/// For an implementation based on Jim Idle's "magic sync" mechanism, see
/// _org.antlr.v4.runtime.DefaultErrorStrategy#sync_.
///
/// - seealso: org.antlr.v4.runtime.DefaultErrorStrategy#sync
///
///
/// - parameter recognizer: the parser instance
/// - org.antlr.v4.runtime.RecognitionException if an error is detected by the error
/// - throws: _RecognitionException_ if an error is detected by the error
/// strategy but cannot be automatically recovered at the current state in
/// the parsing process
func sync(_ recognizer: Parser) throws // RecognitionException;
///
func sync(_ recognizer: Parser) throws

///
/// Tests whether or not recognizer} is in the process of recovering
/// from an error. In error recovery mode, {@link org.antlr.v4.runtime.Parser#consume} adds
/// from an error. In error recovery mode, _org.antlr.v4.runtime.Parser#consume_ adds
/// symbols to the parse tree by calling
/// {@link Parser#createErrorNode(ParserRuleContext, Token)} then
/// {@link ParserRuleContext#addErrorNode(ErrorNode)} instead of
/// {@link Parser#createTerminalNode(ParserRuleContext, Token)}.
///
/// _Parser#createErrorNode(ParserRuleContext, Token)_ then
/// _ParserRuleContext#addErrorNode(ErrorNode)_ instead of
/// _Parser#createTerminalNode(ParserRuleContext, Token)_.
///
/// - parameter recognizer: the parser instance
/// - returns: {@code true} if the parser is currently recovering from a parse
/// error, otherwise {@code false}
/// - returns: `true` if the parser is currently recovering from a parse
/// error, otherwise `false`
///
func inErrorRecoveryMode(_ recognizer: Parser) -> Bool

///
/// This method is called by when the parser successfully matches an input
/// symbol.
///
///
/// - parameter recognizer: the parser instance
///
func reportMatch(_ recognizer: Parser)

/// Report any kind of {@link org.antlr.v4.runtime.RecognitionException}. This method is called by
///
/// Report any kind of _org.antlr.v4.runtime.RecognitionException_. This method is called by
/// the default exception handler generated for a rule method.
///
///
/// - parameter recognizer: the parser instance
/// - parameter e: the recognition exception to report
///
func reportError(_ recognizer: Parser, _ e: AnyObject)
}
Loading

0 comments on commit 752d4d5

Please sign in to comment.