cxx_parsing_ambiguity.md

C++ Declaration Ambiguity ("The Most Vexing Parse")

C++ is famous for its grammatical ambiguities. The most well-known of these is often called "the most vexing parse," where a statement can grammatically be interpreted as either an expression or a declaration.

For example:

T x(A());

Is this:

1. A declaration of a variable x of type T, initialized with an instance of A?
2. A declaration of a function x returning T, taking a single parameter (a function returning A and taking no arguments)?

The aburi Resolution Policy

According to the C++ Standard (stmt.ambig / dcl.ambig.res), the rule is: If it can be parsed as a declaration, it is a declaration.

Aburiscript strictly adheres to this policy. In C++ mode, when the parser encounters an ambiguous statement context (such as inside a block or a for loop initializer), it relies on its tentative parsing engine.

How it works internally:

1. Detection: The parser uses isTokenDeclarationSpec to see if the current token could start a declaration.
2. Tentative Probes: It delegates to classify_cxx_stmt_disambiguation, which begins a full speculative semantic parse (collect_begin_speculative_parse).
3. Execution: It tries to parse the statement as a simple declaration.
   • If that succeeds without semantic errors, it commits to the declaration path.
   • If the declaration parse fails (syntactically or semantically), it rolls back the speculative semantic state (collect_rollback_speculative_parse) and parses it as an expression statement.

This guarantees that we resolve ambiguities correctly without polluting the terminal with duplicate or conflicting diagnostic errors from the failed tentative path.