release 0.2.6: lambda actions via RuleId

[siy]

Summary

Programmatic action attachment via type-safe RuleId. Callers attach action lambdas to grammar rules without modifying the grammar file.

var actions = Actions.empty()
    .with(RuleId.Number.class, sv -> sv.toInt())
    .with(RuleId.Sum.class, sv -> (Integer) sv.get(0) + (Integer) sv.get(1));

PegParser.fromGrammar(grammarText, config, actions).unwrap().parse(input);

Inline grammar actions ({ return ...; } blocks) remain fully supported. Lambda wins when both attached to the same rule.

Forward compatibility

RuleId shape is designed for parseRuleAt(Class<? extends RuleId>, String input, int offset) which will be added in 0.3.0 alongside the multi-module reshape.

Tests

618 → 635 passing, 1 skipped (RoundTripTest). +17 new tests: RuleIdEmissionTest, LambdaActionTest, LambdaVsInlineActionTest, ActionsImmutabilityTest.

Test plan

• mvn test — 635/635 + 1 skipped
• All corpus parity suites 22/22
• GeneratorFlagInertnessTest 3/3

Summary by CodeRabbit

• New Features

  • Added programmatic lambda-based action attachment for grammar rules using a type-safe API
  • Lambda actions override inline grammar actions when both exist for the same rule
  • New composable builder for managing multiple rule actions

• Documentation

  • Updated version to 0.2.6 with new section on lambda action attachment and precedence behavior

• Tests

  • Added test suites covering action immutability, lambda override precedence, and generated parser rule identifiers

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Introduced a programmatic action attachment mechanism enabling type-safe lambda binding to grammar rules via sealed RuleId interfaces and an immutable composable Actions builder. Updated parser construction APIs to accept Actions parameters. ParserGenerator now emits concrete sealed RuleId types in generated parsers with one parameter-less marker record per rule. Lambda actions override inline grammar actions when both exist.

Changes

Cohort / File(s)	Summary
Documentation and Version Updates pom.xml, README.md, docs/GRAMMAR-DSL.md	Version bump to 0.2.6 and documentation of new programmatic action attachment feature, including precedence rules (lambda overrides inline actions), usage patterns, and SemanticValues nested record.
Core Action Framework src/main/java/org/pragmatica/peg/action/Actions.java, src/main/java/org/pragmatica/peg/action/RuleId.java	New immutable builder Actions with empty(), with(...), and lookup methods; new sealed marker interface RuleId with default name() method for deriving rule identifiers from class names.
Parser Entry Points src/main/java/org/pragmatica/peg/PegParser.java	Three new fromGrammar(...) overloads accepting Actions parameter; delegate to grammar-based overload which invokes PegEngine.create(grammar, config, actions).
Engine and Code Generation src/main/java/org/pragmatica/peg/parser/PegEngine.java, src/main/java/org/pragmatica/peg/generator/ParserGenerator.java	PegEngine adds factory accepting Actions and merges lambda actions into inline action dispatch table (lambda wins per rule); ParserGenerator now emits generated parsers with sealed RuleId interface extending library base, one marker record per rule, nested SemanticValues class, and withAction(...) chaining method for lambda override registration; rule dispatch checks lambda map first and applies transformation before inline action path.
Action Mechanism Tests src/test/java/org/pragmatica/peg/action/ActionsImmutabilityTest.java, src/test/java/org/pragmatica/peg/action/LambdaActionTest.java, src/test/java/org/pragmatica/peg/action/LambdaVsInlineActionTest.java, src/test/java/org/pragmatica/peg/action/RuleIdEmissionTest.java	New test suites validating: Actions immutability and composability (chaining with(...) produces fresh instances), interpreter-based lambda action attachment for number/arithmetic parsing with token transformation, lambda override precedence over inline actions, generated parser RuleId emission and correct sealed interface hierarchy, parameter-less marker records per rule, in-memory compilation and runtime lambda dispatch verification.

Sequence Diagram

sequenceDiagram
    participant User as User Code
    participant PP as PegParser
    participant PE as PegEngine
    participant Gen as ParserGenerator
    participant Interp as Generated<br/>Parser

    User->>PP: fromGrammar(grammarText,<br/>config, actions)
    PP->>PP: parse(grammarText)<br/>→ Grammar
    PP->>PE: create(grammar,<br/>config, actions)
    PE->>PE: compile inline<br/>actions
    PE->>PE: mergeActions(inline,<br/>lambda actions)
    PE-->>PP: return PegEngine
    PP-->>User: return Parser
    
    User->>Interp: parse(input)
    loop For each matched rule
        Interp->>Interp: compute<br/>ruleClassName
        alt Lambda action exists
            Interp->>Interp: create SemanticValues<br/>(matched text, values)
            Interp->>Interp: invoke lambda<br/>→ result
        else No lambda
            Interp->>Interp: apply inline<br/>action / default
        end
    end
    Interp-->>User: return Result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• PR #7: Modifies ParserGenerator, PegEngine, and action/SemanticValues handling—directly overlaps with this PR's action dispatch and semantic value infrastructure.
• PR #10: Changes core action/engine generation surfaces (PegEngine, ParserGenerator, SemanticValues)—shares the action and code-generation transformation layer.
• PR #13: Modifies ParserGenerator code-generation output—both PRs alter generated parser emission and rule handling logic.

Poem

🐰 A parser with actions in hand,
Lambda-sealed, immutable, grand,
Rules now wear badges so bright,
Override semantics, get precedence right!
No mutation, just functional delight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and concisely summarizes the main change: introducing lambda actions via RuleId as part of the 0.2.6 release.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release-0.2.6

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}