Introduction to Intuitive BNF (iBNF)

Intuitive BNF (iBNF) is the core of the Intuitive DSL Engine. It is a human-readable grammar definition language designed to be written effortlessly by developers and parsed instantly by the engine.

Unlike traditional parser generators (such as ANTLR or JavaCC) that require complex external .g4 files and generate thousands of lines of boilerplate code, iBNF is defined as a simple inline string directly inside your Java @DslCommand annotation.

At application startup, the engine compiles this string into an immutable, in-memory Abstract Syntax Tree (AST), guaranteeing zero-overhead, reflection-free execution at runtime.

1. The Foundations: Keywords vs. Parameters

The iBNF grammar compiler uses strict case sensitivity to differentiate the structural path of your command from the data you want to extract.

  • Keywords: Must be written in UPPERCASE. These define the static structure of your command. While the definition must be uppercase, the runtime lexer processes user input case-insensitively.
    Example: SHOW, CREATE USER, FROM.
  • Parameters: Must be written in lowercase (or snake_case). These represent dynamic variables captured from the user input. Their names map directly to the value attribute of your @Bind annotations.
    Example: username, target_directory, amount.
// The command starts with a static keyword and captures a dynamic parameter
syntax = "PROVISION USER username ;"

2. Flow Control: Groups & Alternatives

To build powerful DSLs, iBNF offers logical branching operators inspired by POSIX syntax, strictly typed and validated by the engine.

Required Groups: { }

Curly braces define a mandatory block. When combined with the alternative operator |, it forces the user to make an exclusive choice.

syntax = "CHANGE STATUS { TO ACTIVE | TO SUSPENDED } ;"

Optional Groups: [ ]

Square brackets define a block that the user can entirely bypass. If they choose to provide it, the internal syntax of the block is strictly enforced.

syntax = "CREATE USER username [ WITH PASSWORD password ] ;"

Complex Combinations

Our LL(k) recursive descent parser handles deep nesting effortlessly, utilizing full backtracking to resolve ambiguities without throwing false-positive errors.

syntax = "COPY { FILE file_path | DIRECTORY dir_path [ RECURSIVE ] } TO target ;"

3. Advanced Modifiers

Repetitions: ...

The ellipsis operator (...) indicates that the preceding node (whether it is a parameter, a keyword, or an entire group) can be repeated multiple times. The engine incorporates built-in Infinite Loop Protection to prevent malicious or malformed repeated optional groups.

// The user can specify multiple IPs in a row
syntax = "BLOCK TRAFFIC FROM IP ip_address ... ;"

// Repeating an entire optional group
syntax = "GENERATE REPORT [ WITH metric_name ] ... ;"

Dynamic Macros: ${...}

This is the killer feature of the Intuitive DSL Engine. A macro delegates the validation of a syntax node to a late-binding business logic supplier rather than a static definition.

syntax = "ASSIGN ROLE ${db_roles} TO username ;"

Note: Check the "Dynamic Macros & Context" reference page to see how to bind this node to a live database query.

4. Strings & Delimiters

iBNF safely handles string literals and common punctuation.

  • String Literals: Users can wrap inputs containing spaces in single quotes (e.g., 'my text with spaces'). The lexer automatically handles quote escaping and strips the quotes before Java injection.
  • Delimiters: Characters like ;, ,, ., or / are natively recognized by the lexer as DelimiterNodes and do not require declaration as keywords. We highly recommend terminating all your commands with a ; for visual clarity.

Next Step

Discover how to bind this syntax to your Java classes with absolutely zero boilerplate in the "Core Concepts: Zero Boilerplate & Binding" guide.