Module Kernel.SpecSource

Specification interface

This module exports the data structures that represent the user's error specification after parsing and resolution.

Type definitions:

• ('g, 'r) clause: A group of patterns sharing the same action (one clause in the grammar)
• ('g, 'r) branch: A single pattern within a clause

• clause_def: Additional metadata about a clause, mainly for handling %shortest groups:
• shortest: Is the clause in a %shortest group
• new_group: Is the clause the first of the group? If true, it starts a new priority group.

• ('g, 'r) clauses: All clauses in a rule:
• definitions: The clause definition for each clause
• captures: The captured variables for each clause

• ('g, 'r) branches: All branches across all clauses:
• clause, pattern, expr: Branch properties. Pattern is the abstract syntax of the pattern being recognized, while expr is a lower-level representation of the pattern as a regular expression.
• of_clause: Mapping from clauses to their branches
• lookaheads: Optional lookahead constraints per branch
• br_captures: Captured variables per branch
• is_total, is_partial: Whether branches are total/partial
• priority: Priorities determine which branch should match when multiple branches succeed. Text order is used most of the time (first branch matches first), except for a %shortest group, in which case the branch that matches the first has the priority.

• 'g _rule: A rule with all its clauses and branches

Main functions:

• branch_count: Return the number of branches
• import_rule: Compile a Syntax.rule into the internal specification

Implementation details:

• The priority system allows specification of multiple clauses with different precedence. Later clauses have lower priority.

• The is_total / is_partial distinction matters for coverage analysis: partial clauses only accept specific lookaheads, total clauses accept any lookahead.

• The import_rule function handles various clause types:
• Normal clauses (total)
• Partial clauses with specific lookahead constraints
• %shortest groups where all clauses share priority

TODO: "Unreachable" clauses are not implemented at the moment.