pyfcstm.dsl.error

ANTLR Parsing Error Collection and Reporting Utilities.

This module defines a set of exceptions and a custom ANTLR error listener for collecting and reporting parsing errors. Instead of halting on the first error, the listener aggregates errors and raises a single GrammarParseError when parsing is complete, enabling comprehensive diagnostics.

The module contains the following main components:

GrammarItemError - Base class for grammar-related exceptions
SyntaxFailError - Syntax error details for invalid input
AmbiguityError - Error for ambiguous grammar interpretation
FullContextAttemptError - Error for full-context parsing attempts
ContextSensitivityError - Error for context sensitivity warnings
UnfinishedParsingError - Error for unconsumed input after parsing
GrammarParseError - Aggregated exception for multiple errors
CollectingErrorListener - Error listener that aggregates errors

Example:

>>> from antlr4 import CommonTokenStream
>>> from pyfcstm.dsl.error import CollectingErrorListener
>>> listener = CollectingErrorListener()
>>> # ... attach listener to a parser and parse input ...
>>> # After parsing:
>>> listener.check_unfinished_parsing_error(token_stream)
>>> listener.check_errors()

Note

The listener stores errors in memory until CollectingErrorListener.check_errors() is called. For large inputs, ensure that error accumulation is acceptable for your memory constraints.

GrammarItemError

class pyfcstm.dsl.error.GrammarItemError[source]

Base class for all grammar-related errors.

This class serves as the parent class for specific grammar error types, providing a common interface for error handling in the grammar parsing system.

SyntaxFailError

class pyfcstm.dsl.error.SyntaxFailError(line: int, column: int, offending_symbol_text: str | None, msg: str)[source]

Error raised when a syntax error is encountered during parsing.

Parameters:

line (int) – The line number where the error occurred.
column (int) – The column number where the error occurred.
offending_symbol_text (str or None) – The text of the problematic symbol, if any.
msg (str) – The error message.

__init__(line: int, column: int, offending_symbol_text: str | None, msg: str) → None[source]

AmbiguityError

class pyfcstm.dsl.error.AmbiguityError(input_range: str, start_index: int, stop_index: int)[source]

Error raised when grammar ambiguity is detected.

This error indicates that the parser found multiple valid ways to interpret the input, which may suggest a grammar design issue or ambiguous syntax.

Parameters:

input_range (str) – The range of input text where ambiguity was detected.
start_index (int) – The starting index of the ambiguous section.
stop_index (int) – The ending index of the ambiguous section.

__init__(input_range: str, start_index: int, stop_index: int) → None[source]

FullContextAttemptError

class pyfcstm.dsl.error.FullContextAttemptError(input_range: str, start_index: int, stop_index: int)[source]

Error raised when the parser attempts full context interpretation.

This error indicates that the parser needed to use a more expensive parsing strategy to resolve ambiguity. While not necessarily an error in user code, it may suggest complex or ambiguous syntax that could be simplified.

Parameters:

input_range (str) – The range of input text where full context attempt occurred.
start_index (int) – The starting index of the affected section.
stop_index (int) – The ending index of the affected section.

__init__(input_range: str, start_index: int, stop_index: int) → None[source]

ContextSensitivityError

class pyfcstm.dsl.error.ContextSensitivityError(input_range: str, start_index: int, stop_index: int)[source]

Error raised when context sensitivity is detected.

This error indicates that the parser’s decision depends on the surrounding context in a way that may make the grammar harder to understand or maintain. While not necessarily an error, it suggests the syntax could be clearer.

Parameters:

input_range (str) – The range of input text where context sensitivity was detected.
start_index (int) – The starting index of the sensitive section.
stop_index (int) – The ending index of the sensitive section.

__init__(input_range: str, start_index: int, stop_index: int) → None[source]

UnfinishedParsingError

class pyfcstm.dsl.error.UnfinishedParsingError(lineno: int)[source]

Error raised when the input was not completely consumed by the parser.

Parameters:: lineno (int) – The line number where unparsed content begins.

__init__(lineno: int) → None[source]

GrammarParseError

class pyfcstm.dsl.error.GrammarParseError(errors: List[GrammarItemError])[source]

Exception raised when one or more grammar parsing errors are encountered.

Parameters:: errors (list[GrammarItemError]) – List of grammar-related errors that occurred during parsing.
Variables:: errors (list[GrammarItemError]) – Collected grammar-related errors.

__init__(errors: List[GrammarItemError]) → None[source]

CollectingErrorListener

class pyfcstm.dsl.error.CollectingErrorListener[source]

A custom ANTLR error listener that collects errors during parsing.

This class extends ANTLR’s antlr4.error.ErrorListener.ErrorListener to provide comprehensive error collection and reporting functionality. Instead of immediately throwing exceptions, it accumulates errors and can report them collectively via check_errors().

Variables:: errors (list[GrammarItemError]) – List storing all encountered error messages.

__init__() → None[source]: Initialize the error listener with an empty error collection.

check_errors() → None[source]

Check for collected errors and raise an exception if any exist.

This method should be called after parsing is complete to verify if any errors were encountered during the process. It filters out cascading errors to provide clearer diagnostics.

Raises:: GrammarParseError – If any errors were collected during parsing, with detailed error messages.

check_unfinished_parsing_error(stream: CommonTokenStream) → None[source]

Append an UnfinishedParsingError if the token stream is not consumed.

This method checks whether the token stream has reached the end-of-file token. If not, it records an unfinished parsing error using the line number of the current token.

Parameters:: stream (CommonTokenStream) – The token stream to inspect.

reportAmbiguity(recognizer: Any, dfa: Any, startIndex: int, stopIndex: int, exact: bool, ambigAlts: Any, configs: Any) → None[source]

Handle and collect grammar ambiguity issues.

Parameters:

recognizer (Any) – The parser that encountered the ambiguity.
dfa (Any) – The DFA being processed.
startIndex (int) – Starting index of the ambiguous input.
stopIndex (int) – Ending index of the ambiguous input.
exact (bool) – Whether the ambiguity is exact.
ambigAlts (Any) – The ambiguous alternatives.
configs (Any) – The ATN configurations.

reportAttemptingFullContext(recognizer: Any, dfa: Any, startIndex: int, stopIndex: int, conflictingAlts: Any, configs: Any) → None[source]

Handle and collect full context parsing attempts.

Parameters:

recognizer (Any) – The parser attempting full context.
dfa (Any) – The DFA being processed.
startIndex (int) – Starting index of the affected input.
stopIndex (int) – Ending index of the affected input.
conflictingAlts (Any) – The conflicting alternatives.
configs (Any) – The ATN configurations.

reportContextSensitivity(recognizer: Any, dfa: Any, startIndex: int, stopIndex: int, prediction: Any, configs: Any) → None[source]

Handle and collect context sensitivity issues.

Parameters:

recognizer (Any) – The parser that encountered the sensitivity.
dfa (Any) – The DFA being processed.
startIndex (int) – Starting index of the sensitive input.
stopIndex (int) – Ending index of the sensitive input.
prediction (Any) – The predicted alternative.
configs (Any) – The ATN configurations.

syntaxError(recognizer: Any, offendingSymbol: Any | None, line: int, column: int, msg: str, e: Exception | None) → None[source]

Handle and collect syntax errors encountered during parsing.

Parameters:

recognizer (Any) – The parser that encountered the error.
offendingSymbol (Any or None) – The problematic input symbol.
line (int) – Line number where the error occurred.
column (int) – Column number where the error occurred.
msg (str) – The error message.
e (Exception or None) – The exception that was raised, if any.