Skip to content

Start rule in ParseCST is grammar.Rules[0] implicitly — document or make explicit #4

@fredxfred

Description

@fredxfred

Summary

metaparser.ParseCST picks the start rule from the textual order of
rules in the grammar:

// v2/metaparser/cst.go
startRule := gd.GetRules()[0].GetName()

This is load-bearing but not documented in the CstRequest proto or
the ParseCST godoc. A user who reorders their .ebnf file (for
example, alphabetising rules or promoting a helper rule to the top)
silently changes the entry point, and the error message ("production
"foo" did not match at offset 0") doesn't hint at the cause.

Proposal

Pick one of:

  1. Add a start_rule field to CstRequest. If unset, fall back
    to Rules[0] to preserve current behaviour.
  2. Add a start annotation on RuleDescriptor (similar to ANTLR's
    grammar / options preamble). The EBNF parser sets it on the
    first rule; callers can override via a grammar-level edit.
  3. Document the current behaviour prominently in the ParseCST
    godoc and the CstRequest proto comment, and consider an error
    hint when parsing fails at offset 0 on the first rule:
    "did not match at offset 0 (start rule %q — first in grammar)".

Option 3 is the minimum. Option 1 is the cleanest API change. Option
2 requires an EBNF syntax extension and feels heavier than warranted.

Context

Encountered while wiring gluon v2 up against a DOCX grammar in
accretional/proto-docx.
The document rule is deliberately first; alphabetising the file
(e.g. moving attrs to the top) would silently break the parser.
Flagged rather than worked around.

Full write-up: #2

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions