parsanol 3.0.0

data/example/output/scopes.out

@@ -0,0 +1 @@
+parses 'aba'

data/example/output/seasons.out

@@ -0,0 +1,28 @@
+"And when Spring comes"
+{:bud=>{:stem=>[{:branch=>:leaf}]}}
+
+"And when Summer comes"
+{:bud=>{:stem=>[{:branch=>[:leaf, :flower]}]}}
+
+"And when Fall comes"
+Fruit!
+Falling Leaves!
+{:bud=>{:stem=>[{:branch=>[]}]}}
+
+"And when Winter comes"
+{:bud=>{:stem=>[]}}
+
+"And when Spring comes"
+{:bud=>{:stem=>[{:branch=>:leaf}]}}
+
+"And when Summer comes"
+{:bud=>{:stem=>[{:branch=>[:leaf, :flower]}]}}
+
+"And when Fall comes"
+Fruit!
+Falling Leaves!
+{:bud=>{:stem=>[{:branch=>[]}]}}
+
+"And when Winter comes"
+{:bud=>{:stem=>[]}}
+

data/example/output/sentence.out

@@ -0,0 +1 @@
+["RubyKaigi2009のテーマは、「変わる／変える」です。", " 前回のRubyKaigi2008のテーマであった「多様性」の言葉の通り、 2008年はRubyそのものに関しても、またRubyの活躍する舞台に関しても、 ますます多様化が進みつつあります。", "RubyKaigi2008は、そのような Rubyの生態系をあらためて認識する場となりました。", " しかし、こうした多様化が進む中、異なる者同士が単純に距離を 置いたままでは、その違いを認識したところであまり意味がありません。", " 異なる実装、異なる思想、異なる背景といった、様々な多様性を理解しつつ、 すり合わせるべきものをすり合わせ、変えていくべきところを 変えていくことが、豊かな未来へとつながる道に違いありません。"]

data/example/output/simple_xml.out

@@ -0,0 +1,2 @@
+"verified"
+{:o=>{:name=>"b"@1}, :i=>"verified", :c=>{:name=>"a"@33}}

data/example/output/string_parser.out

@@ -0,0 +1,3 @@
+[#<struct IntLit text="123"@0>,
+ #<struct IntLit text="12345"@4>,
+ #<struct StringLit text=" Some String with \\\"escapes\\\""@11>]

data/example/prec-calc/basic.rb

@@ -0,0 +1,71 @@
+
+# A demonstration of the new precedence climbing infix expression parser. 
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'pp'
+require 'rspec'
+require 'parsanol/parslet'
+require 'parsanol/rig/rspec'
+require 'parsanol/convenience'
+
+class InfixExpressionParser < Parsanol::Parser
+  root :variable_assignment_list
+
+  rule(:space) { match[' '] }
+
+  def cts atom
+    atom >> space.repeat
+  end
+  def infix *args
+    Infix.new(*args)
+  end
+
+  # This is the heart of the infix expression parser: real simple definitions
+  # for all the pieces we need. 
+  rule(:mul_op) { cts match['*/'] }
+  rule(:add_op) { cts match['+-'] }
+  rule(:digit) { match['0-9'] }
+  rule(:integer) { cts digit.repeat(1).as(:int) }
+
+  rule(:expression) { infix_expression(integer, 
+    [mul_op, 2, :left], 
+    [add_op, 1, :right]) }
+
+  # And now adding variable assignments to that, just to a) demonstrate this
+  # embedded in a bigger parser, and b) make the example interesting. 
+  rule(:variable_assignment_list) { 
+    variable_assignment.repeat(1) }
+  rule(:variable_assignment) {
+    identifier.as(:ident) >> equal_sign >> expression.as(:exp) >> eol }
+  rule(:identifier) {
+    cts (match['a-z'] >> match['a-zA-Z0-9'].repeat) }
+  rule(:equal_sign) {
+    cts str('=') }
+  rule(:eol) {
+    cts(str("\n")) | any.absent? }
+end
+
+class InfixInterpreter < Parsanol::Transform
+  rule(int: simple(:int)) { Integer(int) }
+  rule(ident: simple(:ident), exp: simple(:result)) { |d| 
+    d[:doc][d[:ident].to_s.strip.to_sym] = d[:result] }
+
+  rule(l: simple(:l), o: /^\*/, r: simple(:r)) { l * r }
+  rule(l: simple(:l), o: /^\+/, r: simple(:r)) { l + r }
+end
+
+input = <<ASSIGNMENTS
+a = 1
+b = 2
+c = 3 * 25
+d = 100 + 3*4
+ASSIGNMENTS
+
+puts input
+
+int_tree = InfixExpressionParser.new.parse_with_debug(input)
+bindings = {}
+result   = InfixInterpreter.new.apply(int_tree, doc: bindings)
+
+pp bindings

data/example/prec-calc/basic.rb.md

@@ -0,0 +1,114 @@
+# Precedence Calculator - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/prec-calc
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Infix Expression Parser
+
+Parslet's Infix helper simplifies precedence handling:
+
+```ruby
+rule(:expression) { infix_expression(integer,
+  [mul_op, 2, :left],
+  [add_op, 1, :right]) }
+```
+
+Each operator tuple specifies: operator rule, precedence level, and associativity.
+
+### Operator Definitions
+
+Operators are simple character matches:
+
+```ruby
+rule(:mul_op) { cts match['*/'] }
+rule(:add_op) { cts match['+-'] }
+```
+
+`cts` (consume trailing space) is a helper that strips whitespace after atoms.
+
+### Helper Methods
+
+The `cts` and `infix` methods reduce repetition:
+
+```ruby
+def cts atom
+  atom >> space.repeat
+end
+def infix *args
+  Infix.new(*args)
+end
+```
+
+These keep the grammar DRY and readable.
+
+### Variable Assignment Rule
+
+Assignments combine identifier with expression:
+
+```ruby
+rule(:variable_assignment) {
+  identifier.as(:ident) >> equal_sign >> expression.as(:exp) >> eol
+}
+```
+
+Labels (`:ident`, `:exp`) mark captures for transformation.
+
+### Transform Rules
+
+The interpreter transforms parse tree to values:
+
+```ruby
+rule(int: simple(:int)) { Integer(int) }
+rule(l: simple(:l), o: /^\*/, r: simple(:r)) { l * r }
+rule(l: simple(:l), o: /^\+/, r: simple(:r)) { l + r }
+```
+
+Regex patterns on `:o` distinguish operators in transform rules.
+
+### Binding Context
+
+Transform receives context for variable storage:
+
+```ruby
+rule(ident: simple(:ident), exp: simple(:result)) { |d|
+  d[:doc][d[:ident].to_s.strip.to_sym] = d[:result]
+}
+```
+
+The `doc:` parameter passes a hash for accumulating bindings.
+
+## Output Types
+
+```ruby
+# Parse tree
+[{:ident=>"a"@0, :exp=>{:int=>"1"@4}},
+ {:ident=>"b"@8, :exp=>{:int=>"2"@12}},
+ {:ident=>"c"@16, :exp=>{:l=>{:int=>"3"@20}, :o=>"*"@22, :r=>{:int=>"25"@24}}}]
+
+# After transform (bindings)
+{:a=>1, :b=>2, :c=>75}
+```
+
+## Design Decisions
+
+### Why Infix Helper?
+
+The `Infix` class encapsulates precedence climbing logic. Without it, you'd need multiple recursive rules with careful ordering.
+
+### Why Regex in Transform?
+
+Parslet's transform doesn't support operator-specific rules directly. Regex matching on the operator string provides clean separation.
+
+### Why Pass Context to Transform?
+
+Variable bindings need accumulation across statements. Passing a context hash enables this without global state.
+
+### Why Right Associativity for Addition?
+
+This example demonstrates both associativities. In practice, addition is typically left-associative; the right associativity here is for demonstration.

data/example/readme/basic.rb

@@ -0,0 +1,30 @@
+# The example from the readme. With this, I am making sure that the readme 
+# 'works'. Is this too messy?
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+# cut here -------------------------------------------------------------------
+require 'parsanol/parslet'
+include Parsanol::Parslet
+
+# Constructs a parser using a Parser Expression Grammar like DSL: 
+parser =  str('"') >> 
+          (
+            str('\\') >> any |
+            str('"').absent? >> any
+          ).repeat.as(:string) >> 
+          str('"')
+  
+# Parse the string and capture parts of the interpretation (:string above)        
+tree = parser.parse('"This is a \\"String\\" in which you can escape stuff"')
+
+tree # => {:string=>"This is a \\\"String\\\" in which you can escape stuff"}
+
+# Here's how you can grab results from that tree:
+
+transform = Parsanol::Transform.new do
+  rule(:string => simple(:x)) { 
+    puts "String contents: #{x}" }
+end
+transform.apply(tree)
+

data/example/readme/basic.rb.md

@@ -0,0 +1,80 @@
+# Error Demo - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/readme
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Simple Parser Definition
+
+A minimal parser that matches repeated 'a' characters:
+
+```ruby
+class MyParser < Parsanol::Parser
+  rule(:a) { str('a').repeat }
+
+  def parse(str)
+    a.parse(str)
+  end
+end
+```
+
+The parser only accepts strings of 'a's.
+
+### Successful Parse
+
+When input matches the grammar:
+
+```ruby
+MyParser.new.parse('aaaa')
+# => "aaaa"
+```
+
+Returns the matched string.
+
+### Failed Parse
+
+When input doesn't match:
+
+```ruby
+MyParser.new.parse('bbbb')
+# => Parsanol::ParseFailed: Expected "a" at line 1, column 1
+```
+
+Raises an exception with error details.
+
+### Error Reporting
+
+Parslet provides rich error messages:
+
+- What was expected
+- Where the error occurred (line, column)
+- What was found instead
+
+## Output Types
+
+```ruby
+# Success:
+"aaaa"
+
+# Failure (raises exception):
+# Parsanol::ParseFailed: Expected "a" at line 1, column 1
+```
+
+## Design Decisions
+
+### Why This Example?
+
+Demonstrates basic error handling behavior. Understanding errors is crucial for debugging parsers.
+
+### Why Repeat?
+
+`.repeat` allows zero or more matches. Empty string would also parse successfully.
+
+### Ruby-Only Feature
+
+This is a simple demonstration of Parslet-compatible error handling.

data/example/scopes/basic.rb

@@ -0,0 +1,15 @@
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+require 'parsanol/parslet'
+
+include Parsanol::Parslet
+
+parser = str('a').capture(:a) >> scope { str('b').capture(:a) } >> 
+  dynamic { |s,c| str(c.captures[:a]) }
+  
+begin
+  parser.parse('aba')
+  puts "parses 'aba'"
+rescue
+  puts "exception!"
+end

data/example/scopes/basic.rb.md

@@ -0,0 +1,73 @@
+# Scope Handling - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/scopes
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Scope Blocks
+
+Scopes isolate captures:
+
+```ruby
+parser = str('a').capture(:a) >>
+         scope { str('b').capture(:a) } >>
+         dynamic { |s,c| str(c.captures[:a]) }
+```
+
+The outer capture of 'a' is shadowed by the inner scope's capture of 'b'.
+
+### Shadowing Behavior
+
+Inner scopes can shadow outer captures:
+
+```ruby
+# Outer scope captures :a => 'a'
+str('a').capture(:a) >>
+# Inner scope captures :a => 'b' (shadows outer)
+scope { str('b').capture(:a) } >>
+# After scope, :a still refers to inner capture
+dynamic { |s,c| str(c.captures[:a]) }  # matches 'b'
+```
+
+### Isolation Benefits
+
+Scopes prevent capture pollution:
+
+- Nested constructs don't interfere with outer captures
+- Each level has its own namespace
+- Cleanup is automatic when scope exits
+
+## Output Types
+
+```ruby
+# Input: 'aba'
+# Parses successfully because:
+# - 'a' captured as :a in outer
+# - 'b' captured as :a in inner scope (shadows)
+# - dynamic matches 'b' (inner capture)
+
+# Input: 'aaa'
+# Would FAIL because:
+# - 'a' captured as :a
+# - scope captures 'a' as :a
+# - dynamic matches 'a' (not 'b')
+```
+
+## Design Decisions
+
+### Why Lexical Scoping?
+
+Lexical scoping matches how variables work in most programming languages. Users can reason about capture visibility.
+
+### Why Shadow Instead of Merge?
+
+Shadowing prevents accidental capture conflicts. Explicit naming would be needed for merging.
+
+### Ruby-Only Feature
+
+Scope blocks are a Parslet-specific feature for managing capture context. The Rust implementation uses different patterns for similar functionality.

data/example/scopes/example.json

@@ -0,0 +1,38 @@
+{
+  "id": "scopes",
+  "title": "Scope DSL",
+  "description": "Demonstrate Parslet's scope DSL for managing variable bindings across grammar rules.",
+  "category": "conceptual",
+  "tags": ["scope", "binding", "parslet", "context"],
+  "difficulty": "intermediate",
+  "concepts": ["scope", "variable binding", "context", "nested rules"],
+
+  "motivation": {
+    "why": "Scopes provide isolated variable binding contexts within grammar rules. This enables nested language constructs and parameterized rules.",
+    "useCases": [
+      "Nested language constructs",
+      "Parameterized rules",
+      "Context-sensitive parsing"
+    ]
+  },
+
+  "inputFormat": {
+    "description": "Expressions with scoped variable bindings.",
+    "examples": [
+      { "input": "let x = 1", "description": "Variable declaration in scope", "valid": true }
+    ]
+  },
+
+  "outputFormat": {
+    "description": "Scoped variable bindings.",
+    "structure": {
+      "scope": { "description": "The scope context with bound variables" }
+    }
+  },
+
+  "rubyOnly": true,
+  "parsletCompatible": true,
+  "implementations": {
+    "ruby": { "basic": "basic.rb" }
+  }
+}

data/example/seasons/basic.rb

@@ -0,0 +1,46 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol/parslet'
+require 'pp'
+
+tree = {:bud => {:stem => []}}
+
+class Spring < Parsanol::Transform
+  rule(:stem => sequence(:branches)) {
+    {:stem => (branches + [{:branch => :leaf}])}
+  }
+end
+class Summer < Parsanol::Transform
+  rule(:stem => subtree(:branches)) {
+    new_branches = branches.map { |b| {:branch => [:leaf, :flower]} }
+    {:stem => new_branches}
+  }
+end
+class Fall < Parsanol::Transform
+  rule(:branch => sequence(:x)) {
+    x.each { |e| puts "Fruit!" if e==:flower }
+    x.each { |e| puts "Falling Leaves!" if e==:leaf }
+    {:branch => []}
+  }
+end
+class Winter < Parsanol::Transform
+  rule(:stem => subtree(:x)) {
+    {:stem => []}
+  }
+end
+
+def do_seasons(tree)
+  [Spring, Summer, Fall, Winter].each do |season|
+    p "And when #{season} comes"
+    tree = season.new.apply(tree)
+    pp tree
+    puts
+  end
+  tree
+end
+
+# What marvel of life!
+tree = do_seasons(tree)
+tree = do_seasons(tree)
+
+

data/example/seasons/basic.rb.md

@@ -0,0 +1,117 @@
+# Transform Patterns - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/seasons
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Transform Class Structure
+
+Each season is a separate transform class:
+
+```ruby
+class Spring < Parsanol::Transform
+  rule(:stem => sequence(:branches)) {
+    {:stem => (branches + [{:branch => :leaf}])}
+  }
+end
+```
+
+Different classes encapsulate different transformation behaviors.
+
+### Sequence Pattern
+
+`sequence(:x)` matches arrays of simple values:
+
+```ruby
+rule(:stem => sequence(:branches)) {
+  {:stem => (branches + [{:branch => :leaf}])}
+}
+```
+
+`branches` is bound to the array content.
+
+### Subtree Pattern
+
+`subtree(:x)` matches any nested structure:
+
+```ruby
+rule(:stem => subtree(:branches)) {
+  new_branches = branches.map { |b| {:branch => [:leaf, :flower]} }
+  {:stem => new_branches}
+}
+```
+
+Recursively applies to children.
+
+### Branch Pattern
+
+Match and transform nested arrays:
+
+```ruby
+class Fall < Parsanol::Transform
+  rule(:branch => sequence(:x)) {
+    x.each { |e| puts "Fruit!" if e == :flower }
+    x.each { |e| puts "Falling Leaves!" if e == :leaf }
+    {:branch => []}
+  }
+end
+```
+
+Iterate over array contents while transforming.
+
+### Composition
+
+Multiple transforms are applied in sequence:
+
+```ruby
+def do_seasons(tree)
+  [Spring, Summer, Fall, Winter].each do |season|
+    tree = season.new.apply(tree)
+  end
+  tree
+end
+```
+
+Each transform passes its output to the next.
+
+## Output Types
+
+```ruby
+# Initial tree:
+{:bud => {:stem => []}}
+
+# After Spring:
+{:bud => {:stem => [{:branch => :leaf}]}}
+
+# After Summer:
+{:bud => {:stem => [{:branch => [:leaf, :flower]}]}}
+
+# After Fall:
+{:bud => {:stem => [{:branch => []}]}}
+
+# After Winter:
+{:bud => {:stem => []}}
+```
+
+## Design Decisions
+
+### Why Separate Transform Classes?
+
+Each transform has a single responsibility. Separation makes transformations testable and reusable.
+
+### Why sequence vs subtree?
+
+`sequence` is for homogeneous arrays; `subtree` handles arbitrary nesting. Different patterns for different structures.
+
+### Why Apply in Sequence?
+
+Pipelining transforms creates complex behavior from simple pieces. Each step is easy to understand and debug.
+
+### Ruby-Only Feature
+
+Transform patterns are Parslet's Ruby DSL for AST manipulation. Rust uses pattern matching and visitor patterns instead.

data/example/seasons/example.json

@@ -0,0 +1,40 @@
+{
+  "id": "seasons",
+  "title": "Transform Patterns",
+  "description": "Demonstrate Parslet transform DSL patterns through seasonal tree transformations.",
+  "category": "conceptual",
+  "tags": ["transform", "pattern-matching", "parslet", "ast"],
+  "difficulty": "intermediate",
+  "concepts": ["transform", "pattern matching", "sequence", "subtree", "AST transformation"],
+
+  "motivation": {
+    "why": "Transforms convert parse trees to domain objects using pattern matching. This example shows how multiple transforms can be composed to create complex behavior from simple pieces.",
+    "useCases": [
+      "AST transformation",
+      "Code generation",
+      "Data normalization",
+      "Multi-stage processing"
+    ]
+  },
+
+  "inputFormat": {
+    "description": "Tree structure representing a plant through seasons.",
+    "examples": [
+      { "input": "{bud: {stem: []}}", "description": "Initial tree state", "valid": true }
+    ]
+  },
+
+  "outputFormat": {
+    "description": "Transformed tree after seasonal transformations.",
+    "structure": {
+      "season": { "description": "The season transform being applied" },
+      "tree": { "description": "The resulting tree structure" }
+    }
+  },
+
+  "rubyOnly": true,
+  "parsletCompatible": true,
+  "implementations": {
+    "ruby": { "basic": "basic.rb" }
+  }
+}