What is the intended behavior of the lexer?



The relevant part to notice is that the Lexer is independent from the Parser.  That is, it doesn't know what the parser expects and does not take any parser rules into account.  Therefore, you have to make sure the tokens the parser expects are actually generated by the Lexer.  This implies that a rule that matches almost anything will probably not be what you want, since it will always match anything, regardless of whether some other rule might match; see detailed rules below.  If you are getting a MismatchedTokenException or UnwantedTokenException telling you that 0!=0, this might well be the case.

The input stream is analyzed to identify the next token.
It does this by evaluating rules.
The winning rule injects a token (usually composed of an extract from the input stream) into the token stream.
A rule wins by passing a set of gates in order.
A conceptual description of these gates follows.
The implementation details of these gates is omitted here.
A bug is when the gate does not behave as described.
An surprise is when you don't agree with the gate structure or behavior.

Which rules match?

All lexer rules that emit tokens are created equal, some are just more equal than others.
All rules work on an input stream.
The rules either match the input stream or they don't.
For those rules that don't match, then they don't and that's it for those rules.
If only one rule matches then it is the winner.

Which rules are the longest?

The number of characters (or is it bytes?) matched by a rule are counted.
The rule having the greatest count is the winner.

Which rule has precedence?

The rule defined first is the winner.