parsanol 3.0.0

data/example/boolean-algebra/basic.rb.md

@@ -0,0 +1,108 @@
+# Boolean Algebra - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/boolean-algebra
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Variable Rule
+
+Variables are `var` followed by digits:
+
+```ruby
+rule(:var) { str("var") >> match["0-9"].repeat(1).as(:var) >> space? }
+```
+
+The `.as(:var)` captures the numeric suffix for later use.
+
+### Operator Precedence
+
+AND binds tighter than OR through rule ordering:
+
+```ruby
+rule(:and_operation) {
+  (primary.as(:left) >> and_operator >> and_operation.as(:right)).as(:and) |
+  primary
+}
+
+rule(:or_operation) {
+  (and_operation.as(:left) >> or_operator >> or_operation.as(:right)).as(:or) |
+  and_operation
+}
+```
+
+OR calls AND first, giving AND higher precedence.
+
+### Parentheses Handling
+
+Primary handles grouping:
+
+```ruby
+rule(:primary) { lparen >> or_operation >> rparen | var }
+```
+
+Parenthesized expressions recurse back to the top-level OR rule.
+
+### DNF Transform
+
+The transform converts to Disjunctive Normal Form:
+
+```ruby
+class Transformer < Parsanol::Transform
+  rule(:var => simple(:var)) { [[String(var)]] }
+
+  rule(:or => { :left => subtree(:left), :right => subtree(:right) }) do
+    (left + right)
+  end
+
+  rule(:and => { :left => subtree(:left), :right => subtree(:right) }) do
+    res = []
+    left.each do |l|
+      right.each do |r|
+        res << (l + r)
+      end
+    end
+    res
+  end
+end
+```
+
+OR concatenates alternatives; AND creates all combinations.
+
+### DNF Output Structure
+
+Arrays of arrays represent the formula:
+
+```ruby
+# var1 and (var2 or var3)
+# => [["1", "2"], ["1", "3"]]
+# Means: (var1 AND var2) OR (var1 AND var3)
+```
+
+## Output Types
+
+```ruby
+# Parse tree for "var1 and (var2 or var3)":
+{:and=>{:left=>{:var=>"1"}, :right=>{:or=>{:left=>{:var=>"2"}, :right=>{:var=>"3"}}}}}
+
+# After transform (DNF):
+[["1", "2"], ["1", "3"]]
+```
+
+## Design Decisions
+
+### Why Right Recursion?
+
+Right recursion naturally handles left-to-right parsing while building the correct tree structure.
+
+### Why DNF Output?
+
+DNF is useful for query optimization and database searches. Each inner array is a conjunction that must all be true.
+
+### Why subtree Instead of simple?
+
+`subtree(:x)` matches any tree structure, allowing recursive matching of nested AND/OR operations.

data/example/boolean-algebra/ruby_transform.rb

@@ -0,0 +1,263 @@
+# Boolean Algebra Parser Example - RubyTransform: Ruby Transform
+#
+# This example demonstrates parsing boolean expressions with AND/OR operators.
+# Shows operator precedence, parentheses handling, and evaluation.
+#
+# Run with: ruby -Ilib example/boolean_algebra_ruby_transform.rb
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol'
+
+# Step 1: Define the parser grammar
+class BooleanAlgebraParser < Parsanol::Parser
+  root :expression
+
+  rule(:expression) { or_expr }
+
+  # OR expression (lowest precedence)
+  rule(:or_expr) {
+    (and_expr.as(:left) >> or_op >> or_expr.as(:right)).as(:or) |
+    and_expr
+  }
+
+  # AND expression (higher precedence)
+  rule(:and_expr) {
+    (primary.as(:left) >> and_op >> and_expr.as(:right)).as(:and) |
+    primary
+  }
+
+  # Primary: variable or parenthesized expression
+  rule(:primary) {
+    lparen >> expression >> rparen |
+    variable
+  }
+
+  rule(:variable) { match['a-z'].repeat(1).as(:var) >> digit.repeat(1).as(:num) }
+  rule(:digit) { match('[0-9]') }
+
+  rule(:or_op) { spaces >> str('or') >> spaces }
+  rule(:and_op) { spaces >> str('and') >> spaces }
+
+  rule(:lparen) { str('(') >> spaces? }
+  rule(:rparen) { spaces? >> str(')') }
+  rule(:spaces) { match('\s').repeat(1) }
+  rule(:spaces?) { match('\s').repeat }
+end
+
+# Step 2: Define AST classes
+class BoolExpr
+  def eval(bindings)
+    raise NotImplementedError
+  end
+end
+
+class VarExpr < BoolExpr
+  attr_reader :name
+
+  def initialize(name)
+    @name = name
+  end
+
+  def eval(bindings)
+    bindings[@name] || raise("Unknown variable: #{@name}")
+  end
+
+  def to_s = @name
+end
+
+class AndExpr < BoolExpr
+  attr_reader :left, :right
+
+  def initialize(left, right)
+    @left = left
+    @right = right
+  end
+
+  def eval(bindings)
+    @left.eval(bindings) && @right.eval(bindings)
+  end
+
+  def to_s = "(#{@left} AND #{@right})"
+end
+
+class OrExpr < BoolExpr
+  attr_reader :left, :right
+
+  def initialize(left, right)
+    @left = left
+    @right = right
+  end
+
+  def eval(bindings)
+    @left.eval(bindings) || @right.eval(bindings)
+  end
+
+  def to_s = "(#{@left} OR #{@right})"
+end
+
+# Step 3: Define transform
+class BooleanTransform < Parsanol::Transform
+  rule(var: simple(:v), num: simple(:n)) { VarExpr.new("#{v}#{n}") }
+  rule(and: simple(:a)) { a }
+  rule(or: simple(:o)) { o }
+  rule(left: simple(:l), right: simple(:r)) {
+    # This handles the case where there's no explicit operator
+    l  # Just return the left side for non-binary expressions
+  }
+end
+
+# Transform that handles binary expressions properly
+class BooleanTransformFull < Parsanol::Transform
+  rule(var: simple(:v), num: simple(:n)) { VarExpr.new("#{v}#{n}") }
+
+  rule(left: simple(:l), right: simple(:r)) {
+    # This catches expressions without explicit and/or tags
+    # Return just the first one (this is a simplified handling)
+    l
+  }
+
+  # These would need the actual tree structure to work correctly
+  rule(and: subtree(:a)) {
+    if a.is_a?(Hash) && a[:left] && a[:right]
+      AndExpr.new(transform(a[:left]), transform(a[:right]))
+    else
+      a
+    end
+  }
+
+  rule(or: subtree(:o)) {
+    if o.is_a?(Hash) && o[:left] && o[:right]
+      OrExpr.new(transform(o[:left]), transform(o[:right]))
+    else
+      o
+    end
+  }
+end
+
+# Manual AST builder for demonstration
+def build_ast(tree)
+  case tree
+  when Hash
+    if tree[:var] && tree[:num]
+      VarExpr.new("#{tree[:var]}#{tree[:num]}")
+    elsif tree[:and]
+      build_and_expr(tree[:and])
+    elsif tree[:or]
+      build_or_expr(tree[:or])
+    else
+      # Try to extract from nested structure
+      tree.each_value do |v|
+        result = build_ast(v)
+        return result if result.is_a?(BoolExpr)
+      end
+      nil
+    end
+  when Array
+    build_ast(tree.first)
+  when Parsanol::Slice
+    nil
+  else
+    nil
+  end
+end
+
+def build_and_expr(data)
+  case data
+  when Hash
+    left = build_ast(data[:left])
+    right = build_ast(data[:right])
+    if left && right
+      AndExpr.new(left, right)
+    else
+      build_ast(data)
+    end
+  else
+    build_ast(data)
+  end
+end
+
+def build_or_expr(data)
+  case data
+  when Hash
+    left = build_ast(data[:left])
+    right = build_ast(data[:right])
+    if left && right
+      OrExpr.new(left, right)
+    else
+      build_ast(data)
+    end
+  else
+    build_ast(data)
+  end
+end
+
+# Step 4: Parse and transform
+def parse_boolean(input)
+  parser = BooleanAlgebraParser.new
+
+  # RubyTransform: Parse and get tree
+  tree = parser.parse(input)
+  puts "Parse tree: #{tree.inspect}"
+
+  # Build AST
+  ast = build_ast(tree)
+  puts "AST: #{ast.to_s}"
+
+  ast
+end
+
+# Example usage
+if __FILE__ == $0
+  puts "=" * 60
+  puts "Boolean Algebra Parser - RubyTransform"
+  puts "=" * 60
+  puts
+
+  expressions = [
+    "var1",
+    "var1 and var2",
+    "var1 or var2",
+    "var1 and var2 or var3",
+    "var1 or var2 and var3",
+    "(var1 or var2) and var3",
+  ]
+
+  expressions.each do |expr_str|
+    puts "-" * 40
+    puts "Input: #{expr_str}"
+    begin
+      ast = parse_boolean(expr_str)
+    rescue => e
+      puts "Error: #{e.message}"
+    end
+    puts
+  end
+
+  # Demonstrate evaluation
+  puts "=" * 60
+  puts "Evaluation Example"
+  puts "=" * 60
+
+  bindings = { "var1" => true, "var2" => false, "var3" => true }
+  puts "Bindings: var1=true, var2=false, var3=true"
+  puts
+
+  eval_exprs = [
+    "var1 and var2",
+    "var1 or var2",
+    "var1 and var3",
+    "(var1 or var2) and var3",
+  ]
+
+  eval_exprs.each do |expr_str|
+    begin
+      ast = parse_boolean(expr_str)
+      result = ast.eval(bindings)
+      puts "  #{expr_str} = #{result}"
+    rescue => e
+      puts "  #{expr_str} = ERROR: #{e.message}"
+    end
+    puts
+  end
+end

data/example/calculator/basic.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/basic.rb.md

@@ -0,0 +1,120 @@
+# Calculator - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/calculator
+ruby basic.rb "1+2*3"
+```
+
+## Code Walkthrough
+
+### Left Associativity via Repetition
+
+Addition uses repetition for left associativity:
+
+```ruby
+rule(:addition) {
+  multiplication.as(:l) >> (add_op >> multiplication.as(:r)).repeat(1) |
+  multiplication
+}
+```
+
+The pattern `l >> (op >> r).repeat` creates left-associative chains like `((1+2)+3)`.
+
+### Multiplication Rule
+
+Multiplication has higher precedence:
+
+```ruby
+rule(:multiplication) {
+  integer.as(:l) >> (mult_op >> integer.as(:r)).repeat(1) |
+  integer
+}
+```
+
+Multiplication is tried first in the addition rule, giving it higher precedence.
+
+### Operator Rules
+
+Operators capture their symbol:
+
+```ruby
+rule(:mult_op) { match['*/'].as(:o) >> space? }
+rule(:add_op) { match['+-'].as(:o) >> space? }
+```
+
+The `:o` label marks the operator for transform matching.
+
+### AST Node Classes
+
+Ruby structs represent AST nodes:
+
+```ruby
+Int = Struct.new(:int) {
+  def eval; self end
+  def op(operation, other)
+    left = int
+    right = other.int
+    Int.new(
+      case operation
+        when '+' then left + right
+        when '-' then left - right
+        when '*' then left * right
+        when '/' then left / right
+      end)
+  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
+}
+```
+
+`Int` represents values; `Seq` represents expression chains; `LeftOp` represents binary operations.
+
+### Transform Rules
+
+Transform builds the AST:
+
+```ruby
+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
+```
+
+Pattern matching extracts components and constructs typed objects.
+
+## Output Types
+
+```ruby
+Int.new(42)              # Integer value
+LeftOp.new('+', Int.new(2))  # Binary operation
+Seq.new([Int.new(1), LeftOp.new('+', Int.new(2))])  # Expression chain
+```
+
+After `eval`: returns `Int` with result value.
+
+## Design Decisions
+
+### Why Struct for AST Nodes?
+
+Structs are lightweight, immutable, and can define methods. They're ideal for simple AST representation.
+
+### Why `repeat(1)` for Operators?
+
+`repeat(1)` requires at least one operator, distinguishing `1+2` from bare `1`. The alternative handles the base case.