Intuitive DSL Grammar Reference: Overview

Written by dbalabs | Mar 10, 2026 7:02:12 PM

This reference defines the portable grammar contract used by Intuitive DSL. It explains how command grammars are written, how user input is tokenized and parsed, and how successful matches become structured captures for binding and execution.

The goal of this hub is language-agnostic clarity. The grammar rules described here are not tied to one implementation language, even though the current product is available as Intuitive DSL for Java and documented separately in the Java product documentation.

Key idea: the grammar is authored once, compiled into an immutable tree, and then reused to parse runtime input deterministically.

Grammar definition
      ↓
Grammar compiler
      ↓
Immutable AST
      ↓
User input
      ↓
Lexer
      ↓
Tokens + AST
      ↓
Parser
      ↓
Parse result
      ↓
Binder / execution layer

Intuitive DSL separates authoring-time grammar compilation from runtime parsing and binding.

What this reference covers

Grammar constructs such as keywords, parameters, groups, alternatives, delimiters, macros, and repetition.
Runtime rules for tokenization, matching, backtracking, and full-input validation.
Binding semantics based on exact keyword phrases and ordered parameter captures.
Validation rules for rejecting invalid definitions early and surfacing precise runtime diagnostics.

Normative principles

... is the only repetition operator.
. remains a literal delimiter when it appears as a standalone character.
Macro names are case-sensitive between the grammar and the macro registry.
A quoted value binds its normalized semantic value, not the raw quoted source text.
Exact keyword phrases matter for clause presence and context-sensitive binding.
A command only succeeds when the full input is matched.

How the model works

A command grammar is not interpreted directly at runtime. It is first compiled into an immutable abstract syntax tree that represents sequences, groups, alternatives, parameters, delimiters, macros, and repeatable elements.

At runtime, user input is tokenized into word-like tokens, string tokens, delimiters, and an end-of-input marker. The parser navigates the compiled tree against that token stream, records captures, and returns structured data to the binding layer.

Who should read which page

Core grammar concepts for the basic notation and mental model.
Repetition and delimiters for the most error-prone part of the syntax.
Macros for dynamic runtime choices.
Binding semantics for exact capture and clause rules.
Quoted values and tokenization for lexical behavior.
Validation and error handling for invalid definitions and diagnostics.
Complex examples for complete end-to-end patterns.
Reference / cheat sheet for a compact reminder.

Scope boundaries

This hub is about the grammar contract and its observable semantics. It does not try to explain every product integration concern, host-language reflection model, or deployment detail.

Where the current Java implementation exposes API names such as annotations or diagnostic methods, this hub documents them as the current Java mapping, while keeping the core grammar rules portable across future language variants.