Binding Semantics

Parsing does not directly execute a command. It first produces a structured parse result. Binding is the stage that maps that structured result into a concrete command instance or equivalent runtime object.

Binding is phrase-based and ordered. The engine does not guess context. It uses exact parameter names, exact keyword phrases, and the order of captures produced by the parser.

The parse result model

A successful parse yields ordered parameter captures and ordered traversed keyword phrases. Conceptually, each parameter capture has three semantic parts:

  • name
  • context
  • value

The context is the exact keyword phrase that structurally precedes the capture in the grammar when such context is relevant.

User input
      ↓
Successful parse
      ↓
Captures:
(name, context, value)
      ↓
Binding rules
      ↓
Fields / methods / clause flags
Binding consumes semantic captures, not raw tokens.

Exact phrase semantics

Adjacent uppercase keywords form exact phrases. This is not cosmetic. It directly affects both clause presence and context-sensitive binding.

WITH AGE user_age
AS ACTIVE
DRY RUN

If the grammar contains WITH AGE user_age, then the exact phrase is WITH AGE. A context filter targeting AGE alone is not equivalent.

Current Java mapping

The current Java implementation exposes binding semantics through annotations. These names are useful if you are integrating with the Java product, but the underlying semantics are portable.

  • @Bind("name") binds captures by parameter name.
  • @Bind(after = "WITH AGE") binds captures only when the exact context phrase matches.
  • @OnClause("AS ACTIVE") activates a boolean-like flag or no-argument callback when that exact clause phrase was traversed.

Field binding and method binding

Repeated captures are preserved in encounter order. The final observable effect depends on the binding target type.

  • For a field target, the last assignment wins.
  • For a method target, the method is invoked once per matching capture, in encounter order.

Use method binding when you need to accumulate all occurrences of a repeated element. Use field binding when only the final value is meaningful.

Clause activation

Clause bindings are independent from parameter bindings. A clause is present when its exact keyword phrase was traversed during parsing.

  • A clause field becomes true when the clause is present.
  • A clause field remains false when the clause is absent.
  • A clause method is invoked exactly once when the clause is present.

Registration-time validation

Binding metadata is validated against the compiled grammar during registration. A compliant engine should reject:

  • a bound parameter name that does not exist in the grammar,
  • an after phrase that does not exactly exist in the grammar,
  • a clause phrase that is not an exact keyword phrase in the compiled tree.

Current Java example

@DslCommand(syntax = "PROVISION USER username [ WITH AGE user_age ] { AS ACTIVE | AS SUSPENDED } [ FORCE ] ;")
public final class ProvisionUserCommand {

    @Bind("username")
    private String username;

    @Bind(after = "WITH AGE")
    private Integer age;

    @OnClause("AS ACTIVE")
    private boolean active;

    @OnClause("FORCE")
    private boolean force;
}

Practical guidance

  • Prefer explicit multi-word keyword phrases that express real clause boundaries.
  • Use context-sensitive binding when the same parameter name appears in multiple places.
  • Prefer method binding for repeated structures when every occurrence matters.
  • Do not rely on substring matching for clauses or contexts. Matching is exact.

See also