Summary

The current examples and SyntaxErrorCounter helper show attaching error listeners to either the lexer or parser separately, but not both together. When parsing full Apex files, users should attach the error listener to both the lexer and parser to capture all errors.

Problem

Lexer errors (like invalid escape sequences in string literals or SOSL queries) are only reported if an error listener is attached to the lexer. If users only attach to the parser (as the createParser() helper does), these errors are silently lost.

Examples of lexer-only errors:

Invalid escape sequence in string literal:

String s = '\q';  // \q is not a valid escape

Invalid escape in SOSL query:

List<List<SObject>> results = [FIND 'test\q' IN ALL FIELDS RETURNING Account];

These produce lexer errors like token recognition error at: ''\q' which won't be captured if only listening to the parser.

Suggested improvement

1. Update the README to show best practice of attaching an error listener to both lexer and parser
2. Consider adding a combined helper method like createLexerAndParser() that returns both with a shared error listener attached to each

Example pattern:

ApexLexer lexer = ApexParserFactory.createLexer(input);
lexer.removeErrorListeners();
lexer.addErrorListener(errorListener);

CommonTokenStream tokens = new CommonTokenStream(lexer);
ApexParser parser = new ApexParser(tokens);
parser.removeErrorListeners();
parser.addErrorListener(errorListener);

Related

This was discovered while fixing apex-dev-tools/apex-ls#420 where lexer errors for invalid escape sequences were not being reported.