Validation and Error Handling

Intuitive DSL is designed to reject invalid definitions early and to report runtime syntax failures precisely. This split is deliberate: structural mistakes belong to registration time, while invalid user input belongs to execution time.

Validate grammar authoring upfront. Diagnose runtime input with the furthest, richest failure you can explain.

Invalid definitions

A compliant engine should reject structurally invalid grammars during registration or compilation, before any command is executed.

Empty syntax definitions.
Empty optional groups such as [].
Empty required groups such as {}.
Empty alternatives such as { | A }, { A || B }, or { A | }.
Empty macro names such as ${} or <>.
Unclosed macros such as ${task.
Unmatched brackets or braces.
A repetition operator with no preceding node.

Invalid binding metadata

Definition validation also includes binding metadata. The engine should reject a command definition when a parameter name, a context phrase, or a clause phrase does not exist exactly in the compiled grammar.

Runtime syntax errors

When no registered command can fully match the user input, execution fails with a syntax error. A useful diagnostic should explain:

where parsing failed,
what token was unexpected,
what would have been valid there.

Furthest failure and expected possibilities

If several parsing paths fail, the engine keeps the failure that occurred furthest into the token stream. If several failures happen at the same furthest position, their expected possibilities should be merged deterministically.

This rule is what makes diagnostics informative instead of noisy.

Short diagnostics and rich diagnostics

Most implementations expose both a short message and a richer diagnostic payload. In the current Java implementation, the rich detail is exposed through methods such as getExpectedPossibilities() and getRichMessage().

Tests should assert against the structured or rich diagnostic whenever precision matters.

Common runtime cases

An unclosed quoted string should report an expected closing quote.
An incomplete command at end of input should report what token or phrase was still expected.
A wrong literal delimiter should report the expected delimiter.
An unknown macro choice should fail like a normal parse mismatch at that position.

Examples of rejected grammar definitions

[]
{}
{ | A }
{ A || B }
${}
${task
... USER name ;
DO { A [ B | C } ;

Examples of runtime diagnostic situations

Input: SET TITLE 'unterminated
Expected detail: closing quote (')

Input: PROCESS FILE ;
Expected detail: a value for file_path

Input: SET DATE 07 03 2026 ;
Expected detail: '.' between date components

Practical guidance

Write negative tests for every business-critical grammar.
Test empty branches, wrong clause order, unknown macro values, and unclosed strings.
Prefer exact diagnostics in documentation so users know what the parser is actually expecting.