Optionally report unused lexer/parser rules

[SimonSntPeter]

Sam Harwell points out this is dubious given that all parse rules can be considered roots from which a caller can start parsing from, and some rules deliberately left unused (his example https://github.com/tunnelvisionlabs/antlr4-grammar-postgresql/blob/master/src/com/tunnelvisionlabs/postgresql/PostgreSqlLexer.g4#L609-L636).
However it may be helpful to allow them to be reported. Definition of unused rule is any parse/lex rule unreferenced by any other. Put this onto stdout and let the user decide what to do with it.

[KvanTTT]

Yes, it is especially usefull in grammar developing stage. Moreover, parsing from custom rule is rarely used feature.

Maybe additional attribute should be added to parser rule? Something like root. If rule will have not this attribute and will have not any references, the warning will be generated.

[KvanTTT]

What about such syntax for root rules?

parserRule1 options { root=true; }
    : parserRule2
    | TOKEN
    ...
    ;

If at least one rule this "root" option is enabled, warnings will be generated for unreachable parser rules like this:

parserRule1 options { root=true; }    // No warning, root.
    : parserRule2
    : parserRule3
    ;

parserRule2          // Warning: this rule doesn't have "root" option and references.
    : TOKEN1
    ;

parserRule3          // No warning because it has reference from parserRule1.
    : parserRule4
    | TOKEN2
    ;

parserRule5 options { root=true; }    // No warning here because it's root.
    : TOKEN3
    ;

But if grammar has no root nodes, warnings will not be generated (for back-compatibility issues with old format). In most cases only one root rule required in grammar development. But the root node brings logical clarity.

[KvanTTT]

UPDATE: this option is not actual now since we have options { } for lexer and parser rules.

Another idea: put "root" modifier before rule declaration (similary to token "fragment" modifier):

root parserRule1
    : parserRule2
    | TOKEN
    ...
    ;

Moreover it can be extended to "caseSensitive" or "caseInsensitive" modifier in mode (implemented in this PR):

caseInsensitive mode PHP;
Abstract: 'abstract';
Array: 'array';
As: 'as';

[KvanTTT]

If roots exist, they will be available in Parser class:

public override List<ParseRuleContext> Roots { get; }

Similarly to Vocabulary.

If no root option is detected, Roots will contain the first rule from the parser or nothing. I haven't decided what's more preferable.

[parrt]

I think this is a matter for dev tools, like the intellij plugin, not antlr itself so i'm closing.

[KvanTTT]

I think this is a matter for dev tools, like the intellij plugin, not antlr itself so i'm closing.

But dev tools don't have info about root rules, they highlight everything unused. It's untidy.