parsanol 3.0.0

data/example/calculator/pattern.rb

@@ -0,0 +1,153 @@
+# A simple integer calculator to answer the question about how to do 
+# left and right associativity in parslet (PEG) once and for all. 
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'rspec'
+require 'parsanol/parslet'
+require 'parsanol/rig/rspec'
+
+# This is the parsing stage. It expresses left associativity by compiling
+# list of things that have the same associativity. 
+class CalcParser < Parsanol::Parser
+  root :addition
+  
+  rule(:addition) {
+    multiplication.as(:l) >> (add_op >> multiplication.as(:r)).repeat(1) |
+    multiplication
+  }
+  
+  rule(:multiplication) { 
+    integer.as(:l) >> (mult_op >> integer.as(:r)).repeat(1) |
+    integer }
+  
+  rule(:integer) { digit.repeat(1).as(:i) >> space? }
+
+  rule(:mult_op) { match['*/'].as(:o) >> space? }
+  rule(:add_op) { match['+-'].as(:o) >> space? }
+
+  rule(:digit) { match['0-9'] }
+  rule(:space?) { match['\s'].repeat }
+end
+
+# Classes for the abstract syntax tree.
+Int    = Struct.new(:int) {
+  def eval; self end
+  def op(operation, other)
+    left = int
+    right = other.int 
+
+    Int.new(
+      case operation
+        when '+'
+          left + right
+        when '-'
+          left - right
+        when '*'
+          left * right
+        when '/'
+          left / right
+      end)
+  end
+  def to_i
+    int
+  end
+}
+Seq    = Struct.new(:sequence) {
+  def eval
+    sequence.reduce { |accum, operation| 
+      operation.call(accum) }
+  end
+}
+LeftOp = Struct.new(:operation, :right) {
+  def call(left)
+    left = left.eval
+    right = self.right.eval
+
+    left.op(operation, right)
+  end
+}
+
+# Transforming intermediary syntax tree into a real AST.
+class CalcTransform < Parsanol::Transform
+  rule(i: simple(:i)) { Int.new(Integer(i)) }
+  rule(o: simple(:o), r: simple(:i)) { LeftOp.new(o, i) }
+  rule(l: simple(:i)) { i }
+  rule(sequence(:seq)) { Seq.new(seq) }
+end
+
+# And this calls everything in the right order.
+def calculate(str)
+  intermediary_tree = CalcParser.new.parse(str)
+  abstract_tree = CalcTransform.new.apply(intermediary_tree)
+  result = abstract_tree.eval
+  
+  result.to_i
+end
+
+# A test suite for the above parser
+describe CalcParser do
+  let(:p) { described_class.new }
+  describe '#integer' do
+    let(:i) { p.integer }
+    it "parses integers" do
+      i.should parse('1')
+      i.should parse('123')
+    end 
+    it "consumes trailing white space" do
+      i.should parse('123   ')
+    end 
+    it "doesn't parse floats" do
+      i.should_not parse('1.3')
+    end 
+  end
+  describe '#multiplication' do
+    let(:m) { p.multiplication }
+    it "parses simple multiplication" do
+      m.should parse('1*2')
+    end
+    it "parses division" do
+      m.should parse('1/2')
+    end 
+  end
+  describe '#addition' do
+    let(:a) { p.addition }
+    
+    it "parses simple addition" do
+      a.should parse('1+2')
+      a.should parse('1+2+3-4')
+    end 
+  end
+end
+describe CalcTransform do
+  def t(obj)
+    described_class.new.apply(obj)
+  end
+  
+  it "transforms integers" do
+    t(i: '1').should == Int.new(1)
+  end 
+  it "unwraps left operand" do
+    t(l: :obj).should == :obj
+  end 
+end
+describe 'whole computation specs' do
+  def self.result_of(str, int)
+    it(str) { calculate(str).should == int } 
+  end
+
+  result_of '1+1', 2
+  result_of '1-1-1', -1
+  result_of '1+1+3*5/2', 9
+  result_of '123*2', 246
+end
+
+
+# Enable these if you want to change the code.
+# RSpec::Core::Runner.run([], $stderr, $stdout)
+
+str = ARGV.join
+str = '123*2' if str.match(/^\s*$/)
+
+print "#{str} (command line): -> "
+puts calculate(str)

data/example/calculator/ruby_transform.rb

@@ -0,0 +1,156 @@
+# Calculator Example - Ruby Transform: Ruby Transform (Parslet-Compatible)
+#
+# This example demonstrates Ruby Transform where:
+# 1. Rust parser (parsanol-rs) does the fast parsing
+# 2. Returns a generic tree (hash/array/string structure)
+# 3. Ruby transform converts tree to Ruby objects
+#
+# This is the most flexible option and is 100% Parslet API compatible.
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol'
+
+# Step 1: Define the parser grammar
+class CalculatorParser < Parsanol::Parser
+  root :expression
+
+  rule(:expression) {
+    (term.as(:left) >> add_op.as(:op) >> expression.as(:right)).as(:binop) |
+    term
+  }
+
+  rule(:term) {
+    (factor.as(:left) >> mult_op.as(:op) >> term.as(:right)).as(:binop) |
+    factor
+  }
+
+  rule(:factor) {
+    lparen >> expression >> rparen |
+    number
+  }
+
+  rule(:number) {
+    (match('[0-9]').repeat(1)).as(:int) >> space?
+  }
+
+  rule(:add_op) { match('[+-]').as(:op) >> space? }
+  rule(:mult_op) { match('[*/]').as(:op) >> space? }
+
+  rule(:lparen) { str('(') >> space? }
+  rule(:rparen) { str(')') >> space? }
+  rule(:space?) { match('\s').repeat }
+end
+
+# Step 2: Define the AST classes
+class IntExpr
+  attr_reader :value
+
+  def initialize(value)
+    @value = value
+  end
+
+  def eval = @value
+
+  def to_s = @value.to_s
+
+  def ==(other)
+    other.is_a?(IntExpr) && @value == other.value
+  end
+end
+
+class BinOpExpr
+  attr_reader :left, :op, :right
+
+  def initialize(left, op, right)
+    @left = left
+    @op = op
+    @right = right
+  end
+
+  def eval
+    left_val = @left.eval
+    right_val = @right.eval
+
+    case @op
+    when '+' then left_val + right_val
+    when '-' then left_val - right_val
+    when '*' then left_val * right_val
+    when '/' then left_val / right_val
+    end
+  end
+
+  def to_s
+    "(#{@left} #{@op} #{@right})"
+  end
+end
+
+# Step 3: Define the transform (Parslet-style)
+class CalculatorTransform < Parsanol::Transform
+  # Transform integer captures
+  rule(int: simple(:n)) { IntExpr.new(Integer(n)) }
+
+  # Transform binary operations
+  # NOTE: The grammar wraps op with as(:op), so we get { op: { op: "+" } }
+  # The outer :op is from add_op.as(:op), inner :op is from match('[+-]').as(:op)
+  rule(left: simple(:l), op: { op: simple(:o) }, right: simple(:r)) {
+    BinOpExpr.new(l, o, r)
+  }
+
+  # Handle binop wrapper
+  rule(binop: simple(:b)) { b }
+end
+
+# Step 4: Parse and transform
+def calculate(input)
+  parser = CalculatorParser.new
+  transform = CalculatorTransform.new
+
+  # Ruby Transform: Parse in Rust, transform in Ruby
+  tree = parser.parse(input)
+  puts "Parse tree: #{tree.inspect}"
+
+  ast = transform.apply(tree)
+  puts "AST: #{ast.to_s}"
+
+  result = ast.eval
+  puts "Result: #{result}"
+
+  result
+end
+
+# Example usage
+if __FILE__ == $0
+  test_cases = [
+    ["42", 42],
+    ["1 + 2", 3],
+    ["3 * 4", 12],
+    ["2 + 3 * 4", 14],
+    ["(2 + 3) * 4", 20],
+    ["10 - 3 - 2", 5],  # Left associative: (10 - 3) - 2
+    ["100 / 5 / 2", 10], # Left associative: (100 / 5) / 2
+  ]
+
+  puts "=" * 60
+  puts "Calculator Example - Ruby Transform: Ruby Transform"
+  puts "=" * 60
+
+  test_cases.each do |input, expected|
+    puts
+    puts "-" * 40
+    puts "Input: #{input}"
+    begin
+      result = calculate(input)
+      status = result == expected ? "✓ PASS" : "✗ FAIL"
+      puts "Expected: #{expected}, Got: #{result} - #{status}"
+    rescue => e
+      puts "Error: #{e.message}"
+      puts "✗ FAIL"
+    end
+  end
+end
+
+# Performance comparison note:
+# - Ruby Transform is slower than Options B and C+ because transform happens in Ruby
+# - But it's still faster than pure Ruby Parslet because parsing is in Rust
+# - Use Ruby Transform for maximum flexibility and debugging

data/example/calculator/ruby_transform.rb.md

@@ -0,0 +1,32 @@
+# Calculator (Ruby Transform - Option A)
+
+## Purpose
+
+This implementation demonstrates Parslet-compatible parsing: Rust parses the
+input, Ruby transforms the result into domain objects.
+
+## When to Use
+
+- Migrating from Parslet
+- Maximum flexibility in transformation
+- When domain logic should stay in Ruby
+
+## Key Concepts
+
+1. **Rust Parsing**: Fast native parsing engine
+2. **Ruby Transform**: Familiar Parslet::Transform API
+3. **Flexible Output**: Any Ruby object structure
+
+## Running
+
+```bash
+ruby example/calculator/ruby_transform.rb
+```
+
+## Output
+
+```
+Input: 42+8
+Parse tree: {int: "42", op: "+", rhs: {int: "8"}}
+Result: 50
+```

data/example/calculator/serialized.rb

@@ -0,0 +1,257 @@
+# Calculator Example - Serialized: JSON Serialization
+#
+# This example demonstrates Serialized where:
+# 1. Rust parser (parsanol-rs) does the parsing
+# 2. Result is serialized to JSON
+# 3. Ruby deserializes JSON to Ruby objects
+#
+# This option provides cross-language compatibility and structured output.
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol'
+require 'json'
+
+# Check native extension availability
+unless Parsanol::Native.available?
+  puts "=" * 60
+  puts "Calculator Example - Serialized: JSON Serialization"
+  puts "=" * 60
+  puts
+  puts "ERROR: Native extension not available!"
+  puts "Please run: rake compile"
+  puts "=" * 60
+  exit 1
+end
+
+puts "=" * 60
+puts "Calculator Example - Serialized: JSON Serialization"
+puts "=" * 60
+puts
+puts "✓ Native extension loaded successfully!"
+puts
+
+# Step 1: Define the parser grammar (same as RubyTransform)
+class CalculatorParser < Parsanol::Parser
+  root :expression
+
+  rule(:expression) {
+    (term.as(:left) >> add_op.as(:op) >> expression.as(:right)).as(:binop) |
+    term
+  }
+
+  rule(:term) {
+    (factor.as(:left) >> mult_op.as(:op) >> term.as(:right)).as(:binop) |
+    factor
+  }
+
+  rule(:factor) {
+    lparen >> expression >> rparen |
+    number
+  }
+
+  rule(:number) {
+    (match('[0-9]').repeat(1)).as(:int) >> space?
+  }
+
+  rule(:add_op) { match('[+-]').as(:op) >> space? }
+  rule(:mult_op) { match('[*/]').as(:op) >> space? }
+
+  rule(:lparen) { str('(') >> space? }
+  rule(:rparen) { str(')') >> space? }
+  rule(:space?) { match('\s').repeat }
+end
+
+# Step 2: Define AST classes
+class Expr
+  def eval
+    raise NotImplementedError
+  end
+end
+
+class NumberExpr < Expr
+  attr_reader :value
+
+  def initialize(value)
+    @value = value
+  end
+
+  def eval = @value
+  def to_s = @value.to_s
+end
+
+class BinOpExpr < Expr
+  attr_reader :left, :op, :right
+
+  def initialize(left, op, right)
+    @left = left
+    @op = op
+    @right = right
+  end
+
+  def eval
+    left_val = @left.eval
+    right_val = @right.eval
+
+    case @op
+    when '+' then left_val + right_val
+    when '-' then left_val - right_val
+    when '*' then left_val * right_val
+    when '/' then left_val / right_val
+    end
+  end
+
+  def to_s
+    "(#{@left} #{@op} #{@right})"
+  end
+end
+
+# Step 3: Native JSON parser
+def parse_json_to_expr(data)
+  case data
+  when Hash
+    if data.key?('int')
+      int_val = data['int']
+      int_val = int_val.first if int_val.is_a?(Array)
+      NumberExpr.new(Integer(int_val))
+    elsif data.key?('binop')
+      binop = data['binop']
+
+      # Handle both array and hash formats
+      if binop.is_a?(Array)
+        # Array format: [{"left": ...}, {"op": ...}, {"right": ...}]
+        left_data = binop.find { |e| e.is_a?(Hash) && e.key?('left') }&.dig('left')
+        op_data = binop.find { |e| e.is_a?(Hash) && e.key?('op') }&.dig('op')
+        right_data = binop.find { |e| e.is_a?(Hash) && e.key?('right') }&.dig('right')
+      else
+        # Hash format
+        left_data = binop['left']
+        op_data = binop['op']
+        right_data = binop['right']
+      end
+
+      op = extract_op(op_data)
+      left = parse_json_to_expr(left_data)
+      right = parse_json_to_expr(right_data)
+      BinOpExpr.new(left, op, right)
+    else
+      # Try to find the first value that's parseable
+      data.each_value do |v|
+        result = parse_json_to_expr(v)
+        return result if result
+      end
+      nil
+    end
+  when Array
+    # Arrays often contain [value, whitespace] - extract the value
+    # Or they could be [elem1, elem2, elem3] format
+    result = nil
+    data.each do |elem|
+      parsed = parse_json_to_expr(elem)
+      result = parsed if parsed
+    end
+    result
+  when String
+    # Could be a number string
+    Integer(data) rescue nil
+  else
+    nil
+  end
+end
+
+def extract_op(data)
+  case data
+  when Hash
+    if data.key?('op')
+      extract_op(data['op'])
+    else
+      extract_op(data.values.first)
+    end
+  when Array
+    # Find the op value in the array
+    data.each do |elem|
+      result = extract_op(elem)
+      return result if result.is_a?(String) && result.match?(/^[+\-*\/]$/)
+    end
+    nil
+  when String
+    data
+  else
+    data.to_s
+  end
+end
+
+# Step 4: Parse using native extension
+def calculate(input)
+  parser = CalculatorParser.new
+
+  # Serialized: Parse using native extension and get JSON
+  grammar_json = Parsanol::Native.serialize_grammar(parser.root)
+  json_string = Parsanol::Native.parse_to_json(grammar_json, input)
+
+  puts "Native JSON: #{json_string}"
+
+  # Deserialize to Ruby objects
+  data = JSON.parse(json_string)
+  expr = parse_json_to_expr(data)
+
+  if expr
+    puts "AST: #{expr.to_s}"
+    result = expr.eval
+    puts "Result: #{result}"
+    result
+  else
+    # Fall back to pure Ruby parsing
+    tree = parser.parse(input)
+    transform = CalculatorTransform.new
+    ast = transform.apply(tree)
+    puts "AST (fallback): #{ast.to_s}"
+    result = ast.eval
+    puts "Result: #{result}"
+    result
+  end
+end
+
+# Transform class for fallback
+class CalculatorTransform < Parsanol::Transform
+  rule(int: simple(:n)) { NumberExpr.new(Integer(n)) }
+  rule(left: simple(:l), op: { op: simple(:o) }, right: simple(:r)) {
+    BinOpExpr.new(l, o, r)
+  }
+  rule(binop: simple(:b)) { b }
+end
+
+# Example usage
+if __FILE__ == $0
+  test_cases = [
+    ["42", 42],
+    ["1 + 2", 3],
+    ["3 * 4", 12],
+    ["2 + 3 * 4", 14],
+    ["(2 + 3) * 4", 20],
+  ]
+
+  test_cases.each do |input, expected|
+    puts
+    puts "-" * 40
+    puts "Input: #{input}"
+    begin
+      result = calculate(input)
+      status = result == expected ? "✓ PASS" : "✗ FAIL"
+      puts "Expected: #{expected}, Got: #{result} - #{status}"
+    rescue => e
+      puts "Error: #{e.message}"
+      puts e.backtrace.first(3).join("\n")
+      puts "✗ FAIL"
+    end
+  end
+
+  puts
+  puts "=" * 60
+  puts "Serialized Benefits:"
+  puts "- Cross-language: Same JSON works for Python, JavaScript, etc."
+  puts "- Native performance: All parsing done in Rust"
+  puts "- Structured output with type information"
+  puts "- Easy to cache/store results"
+  puts "=" * 60
+end

data/example/calculator/serialized.rb.md

@@ -0,0 +1,32 @@
+# Calculator (Serialized - Option B)
+
+## Purpose
+
+This implementation demonstrates full Rust processing with JSON output:
+Rust parses AND transforms, returning serialized JSON.
+
+## When to Use
+
+- Cross-language compatibility
+- Structured output required
+- Performance-critical applications
+
+## Key Concepts
+
+1. **Rust Parsing + Transform**: All processing in Rust
+2. **JSON Serialization**: Language-agnostic output
+3. **Type Safety**: Schema-driven structure
+
+## Running
+
+```bash
+ruby example/calculator/serialized.rb
+```
+
+## Output
+
+```
+Input: 42+8
+JSON: {"type":"AddExpr","left":{"type":"Number","value":42},"op":"+","right":{"type":"Number","value":8}}
+Result: 50
+```