parsanol 3.0.0

data/example/error-reporting/basic.rb

@@ -0,0 +1,132 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol/parslet'
+require 'parsanol/convenience'
+
+# This example demonstrates tree error reporting in a real life example.
+# Originally contributed to Parslet, ported to Parsanol as an example.
+
+def prettify(str)
+  puts " "*3 + " "*4 + "." + " "*4 + "10" + " "*3 + "." + " "*4 + "20"
+  str.lines.each_with_index do |line, index|
+    printf "%02d %s\n", 
+      index+1, 
+      line.chomp
+  end
+end
+
+class Parser < Parsanol::Parser
+
+  # commons
+
+  rule(:space) { match('[ \t]').repeat(1) }
+  rule(:space?) { space.maybe }
+
+  rule(:newline) { match('[\r\n]') }
+
+  rule(:comment) { str('#') >> match('[^\r\n]').repeat }
+
+  rule(:line_separator) {
+    (space? >> ((comment.maybe >> newline) | str(';')) >> space?).repeat(1)
+  }
+
+  rule(:blank) { line_separator | space }
+  rule(:blank?) { blank.maybe }
+
+  rule(:identifier) { match('[a-zA-Z0-9_]').repeat(1) }
+
+  # res_statement
+
+  rule(:reference) {
+    (str('@').repeat(1,2) >> identifier).as(:reference)
+  }
+
+  rule(:res_action_or_link) {
+    str('.').as(:dot) >> (identifier >> str('?').maybe ).as(:name) >> str('()')
+  }
+
+  rule(:res_actions) {
+    (
+      reference
+    ).as(:resources) >>
+    (
+      res_action_or_link.as(:res_action)
+    ).repeat(0).as(:res_actions)
+  }
+
+  rule(:res_statement) {
+    res_actions >>
+    (str(':') >> identifier.as(:name)).maybe.as(:res_field)
+  }
+
+  # expression
+
+  rule(:expression) {
+    res_statement
+  }
+
+  # body
+
+  rule(:body) {
+    (line_separator >> (block | expression)).repeat(1).as(:body) >>
+    line_separator
+  }
+
+  # blocks
+
+  rule(:begin_block) {
+    (str('concurrent').as(:type) >> space).maybe.as(:pre) >>
+    str('begin').as(:begin) >>
+    body >>
+    str('end')
+  }
+
+  rule(:define_block) {
+    str('define').as(:define) >> space >>
+    identifier.as(:name) >> str('()') >>
+    body >>
+    str('end')
+  }
+
+  rule(:block) {
+    define_block | begin_block
+  }
+
+  # root
+
+  rule(:radix) {
+    line_separator.maybe >> block >> line_separator.maybe
+  }
+
+  root(:radix)
+end
+
+
+ds = [
+  %{
+    define f()
+      @res.name
+    end
+  },
+  %{
+    define f()
+      begin
+        @res.name
+      end
+    end
+  }
+]
+
+ds.each do |d|
+
+  puts '-' * 80
+  prettify(d)
+
+  parser = Parser.new
+
+  begin
+    parser.parse_with_debug(d)
+  end
+end
+
+puts '-' * 80

data/example/error-reporting/basic.rb.md

@@ -0,0 +1,122 @@
+# Error Reporting - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/error-reporting
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### Common Rules
+
+Whitespace and comments are handled uniformly:
+
+```ruby
+rule(:space) { match('[ \t]').repeat(1) }
+rule(:space?) { space.maybe }
+rule(:newline) { match('[\r\n]') }
+rule(:comment) { str('#') >> match('[^\r\n]').repeat }
+```
+
+Separating common rules improves readability.
+
+### Line Separator Rule
+
+Complex line ending handles comments:
+
+```ruby
+rule(:line_separator) {
+  (space? >> ((comment.maybe >> newline) | str(';')) >> space?).repeat(1)
+}
+```
+
+Lines can end with newline, semicolon, or comment followed by newline.
+
+### Block Structure
+
+Define and begin blocks share body structure:
+
+```ruby
+rule(:begin_block) {
+  (str('concurrent').as(:type) >> space).maybe.as(:pre) >>
+  str('begin').as(:begin) >>
+  body >>
+  str('end')
+}
+
+rule(:define_block) {
+  str('define').as(:define) >> space >>
+  identifier.as(:name) >> str('()') >>
+  body >>
+  str('end')
+}
+```
+
+Both have opening keyword, content, and closing `end`.
+
+### Body Rule
+
+Bodies contain expressions or nested blocks:
+
+```ruby
+rule(:body) {
+  (line_separator >> (block | expression)).repeat(1).as(:body) >>
+  line_separator
+}
+```
+
+Recursive structure allows arbitrary nesting.
+
+### parse_with_debug
+
+The example uses debug parsing:
+
+```ruby
+parser.parse_with_debug(d)
+```
+
+This method prints detailed error information when parsing fails.
+
+### Prettify Helper
+
+Error context is displayed with line numbers:
+
+```ruby
+def prettify(str)
+  puts " "*3 + " "*4 + "." + " "*4 + "10" + " "*3 + "." + " "*4 + "20"
+  str.lines.each_with_index do |line, index|
+    printf "%02d %s\n", index+1, line.chomp
+  end
+end
+```
+
+Column markers help identify error positions.
+
+## Output Types
+
+```ruby
+# Successful parse:
+{:define=>"define", :name=>"f", :body=>[...]}
+
+# Parse failure with debug:
+# Displays:
+# - Expected token at position
+# - Line and column information
+# - What was found vs. expected
+```
+
+## Design Decisions
+
+### Why Separate Line Separator?
+
+Line endings in this language can include comments. A dedicated rule handles the complexity.
+
+### Why parse_with_debug?
+
+`parse_with_debug` provides developer-friendly error output, essential for language tooling.
+
+### Why Multiple Test Cases?
+
+The example tests both simple and nested structures to demonstrate error reporting at different nesting levels.

data/example/expression-evaluator/basic.rb

@@ -0,0 +1,284 @@
+# Expression Evaluator - Ruby Implementation
+#
+# A complete expression parser with operator precedence, variables,
+# and function calls. Demonstrates building a practical calculator.
+#
+# Run with: ruby example/expression-evaluator/basic.rb
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol/parslet'
+
+# Expression parser with full operator precedence
+class ExpressionParser < Parsanol::Parser
+  root :expression
+
+  # Comparison (lowest precedence)
+  rule(:expression) { comparison }
+
+  rule(:comparison) {
+    addition.as(:left) >>
+    ((match('==|!=|<=|>=|<>').as(:op) | str('<') | str('>')).as(:op) >>
+     addition.as(:right)).repeat(1) |
+    addition
+  }
+
+  # Addition/subtraction
+  rule(:addition) {
+    multiplication.as(:left) >>
+    (match('[+-]').as(:op) >> multiplication.as(:right)).repeat(1) |
+    multiplication
+  }
+
+  # Multiplication/division/modulo
+  rule(:multiplication) {
+    power.as(:left) >>
+    (match('[*/%]').as(:op) >> power.as(:right)).repeat(1) |
+    power
+  }
+
+  # Exponentiation (right associative)
+  rule(:power) {
+    unary.as(:left) >>
+    (str('^').as(:op) >> power.as(:right)).maybe |
+    unary
+  }
+
+  # Unary operators
+  rule(:unary) {
+    (str('-').as(:op) >> unary.as(:operand)).as(:unary) |
+    (str('!').as(:op) >> unary.as(:operand)).as(:unary) |
+    primary
+  }
+
+  # Primary: number, function call, variable, or parenthesized expression
+  rule(:primary) {
+    funcall |
+    number |
+    variable |
+    lparen >> expression >> rparen
+  }
+
+  rule(:number) {
+    (match('[0-9]').repeat(1) >> str('.') >> match('[0-9]').repeat(1) |
+     match('[0-9]').repeat(1)).as(:number) >> space?
+  }
+
+  rule(:variable) {
+    (match('[a-zA-Z_]') >> match('[a-zA-Z0-9_]').repeat).as(:variable) >> space?
+  }
+
+  rule(:funcall) {
+    (match('[a-zA-Z_]') >> match('[a-zA-Z0-9_]').repeat).as(:name) >>
+    lparen >>
+    arglist.as(:args) >>
+    rparen
+  }
+
+  rule(:arglist) {
+    (expression >> (comma >> expression).repeat).maybe
+  }
+
+  rule(:lparen) { str('(') >> space? }
+  rule(:rparen) { str(')') >> space? }
+  rule(:comma) { str(',') >> space? }
+  rule(:space?) { match('\s').repeat }
+end
+
+# AST node classes
+Number = Struct.new(:value) do
+  def eval(_ctx)
+    value
+  end
+end
+
+Variable = Struct.new(:name) do
+  def eval(ctx)
+    ctx.variables.fetch(name) { raise "Unknown variable: #{name}" }
+  end
+end
+
+BinaryOp = Struct.new(:left, :op, :right) do
+  def eval(ctx)
+    l = left.eval(ctx)
+    r = right.eval(ctx)
+
+    case op
+    when '+' then l + r
+    when '-' then l - r
+    when '*' then l * r
+    when '/' then l / r
+    when '%' then l % r
+    when '^' then l ** r
+    when '==' then l == r ? 1.0 : 0.0
+    when '!=' then l != r ? 1.0 : 0.0
+    when '<' then l < r ? 1.0 : 0.0
+    when '>' then l > r ? 1.0 : 0.0
+    when '<=' then l <= r ? 1.0 : 0.0
+    when '>=' then l >= r ? 1.0 : 0.0
+    else raise "Unknown operator: #{op}"
+    end
+  end
+end
+
+UnaryOp = Struct.new(:op, :operand) do
+  def eval(ctx)
+    v = operand.eval(ctx)
+    case op
+    when '-' then -v
+    when '!' then v == 0 ? 1.0 : 0.0
+    else raise "Unknown unary operator: #{op}"
+    end
+  end
+end
+
+FunctionCall = Struct.new(:name, :args) do
+  def eval(ctx)
+    arg_values = args.map { |a| a.eval(ctx) }
+
+    if ctx.functions.key?(name)
+      ctx.functions[name].call(arg_values)
+    else
+      raise "Unknown function: #{name}"
+    end
+  end
+end
+
+# Transform parse tree to AST
+class ExpressionTransform < Parsanol::Transform
+  rule(number: simple(:n)) { Number.new(n.to_s.to_f) }
+  rule(variable: simple(:v)) { Variable.new(v.to_s) }
+
+  rule(name: simple(:n), args: simple(:a)) {
+    FunctionCall.new(n.to_s, a.is_a?(Array) ? a : [a])
+  }
+  rule(name: simple(:n), args: sequence(:a)) {
+    FunctionCall.new(n.to_s, a)
+  }
+
+  rule(left: simple(:l)) { l }
+
+  rule(left: simple(:l), op: simple(:o), right: simple(:r)) {
+    BinaryOp.new(l, o.to_s, r)
+  }
+
+  rule(unary: { op: simple(:o), operand: simple(:e) }) {
+    UnaryOp.new(o.to_s, e)
+  }
+end
+
+# Evaluation context with variables and functions
+class EvalContext
+  attr_accessor :variables, :functions
+
+  def initialize
+    @variables = {
+      'PI' => Math::PI,
+      'E' => Math::E
+    }
+
+    @functions = {
+      'sin' => ->(args) { Math.sin(args[0] || 0) },
+      'cos' => ->(args) { Math.cos(args[0] || 0) },
+      'tan' => ->(args) { Math.tan(args[0] || 0) },
+      'sqrt' => ->(args) { Math.sqrt(args[0] || 0) },
+      'abs' => ->(args) { (args[0] || 0).abs },
+      'floor' => ->(args) { (args[0] || 0).floor },
+      'ceil' => ->(args) { (args[0] || 0).ceil },
+      'round' => ->(args) { (args[0] || 0).round },
+      'min' => ->(args) { [args[0] || 0, args[1] || 0].min },
+      'max' => ->(args) { [args[0] || 0, args[1] || 0].max },
+      'log' => ->(args) { Math.log(args[0] || 1) },
+      'exp' => ->(args) { Math.exp(args[0] || 0) }
+    }
+  end
+
+  def set(name, value)
+    @variables[name] = value
+  end
+end
+
+# Evaluate an expression string
+def evaluate(str, ctx = EvalContext.new)
+  parser = ExpressionParser.new
+  transform = ExpressionTransform.new
+
+  tree = parser.parse(str)
+  ast = transform.apply(tree)
+
+  # Handle BinaryOp chains with multiple ops
+  if ast.is_a?(Array) && ast.length == 1
+    ast = ast.first
+  end
+
+  # Reduce left-associative chains
+  while ast.is_a?(Hash) && ast.key?(:left)
+    left = ast[:left]
+    if left.is_a?(Hash) && left.key?(:left)
+      # Nested chain - flatten
+      inner = evaluate_helper(left, ctx)
+      ast = BinaryOp.new(inner, ast[:op], ast[:right])
+    else
+      ast = BinaryOp.new(left, ast[:op], ast[:right])
+    end
+  end
+
+  ast.eval(ctx)
+rescue => e
+  "Error: #{e.message}"
+end
+
+def evaluate_helper(node, ctx)
+  return node unless node.is_a?(Hash)
+
+  if node.key?(:left)
+    left = evaluate_helper(node[:left], ctx)
+    right = evaluate_helper(node[:right], ctx)
+    BinaryOp.new(left, node[:op], right)
+  else
+    node
+  end
+end
+
+# Main demo
+if __FILE__ == $0
+  ctx = EvalContext.new
+  ctx.set('x', 10.0)
+  ctx.set('y', 5.0)
+
+  puts "Expression Evaluator Example"
+  puts "=" * 40
+  puts
+  puts "Variables: x = #{ctx.variables['x']}, y = #{ctx.variables['y']}"
+  puts "Constants: PI = #{ctx.variables['PI']}, E = #{ctx.variables['E']}"
+  puts
+
+  expressions = [
+    "1 + 2 * 3",
+    "(1 + 2) * 3",
+    "2 ^ 3 ^ 2",
+    "x + y",
+    "x * y - 5",
+    "sin(PI / 2)",
+    "sqrt(16)",
+    "max(x, y)",
+    "x > y",
+    "min(sin(0), cos(0))"
+  ]
+
+  printf "%-25s | %s\n", "Expression", "Result"
+  puts "-" * 40
+
+  expressions.each do |expr|
+    result = evaluate(expr, ctx)
+    printf "%-25s | %s\n", expr, result
+  end
+
+  # Command line argument
+  if ARGV.length > 0
+    expr = ARGV.join(' ')
+    puts
+    puts "Evaluating: #{expr}"
+    puts "Result: #{evaluate(expr, ctx)}"
+  end
+end

data/example/expression-evaluator/basic.rb.md

@@ -0,0 +1,138 @@
+# Expression Evaluator - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/expression-evaluator
+ruby basic.rb "1+2*3"
+```
+
+## Code Walkthrough
+
+### Operator Precedence Hierarchy
+
+The parser uses layered rules for precedence:
+
+```ruby
+rule(:expression) { comparison }
+rule(:comparison) { addition >> (op >> addition).repeat | addition }
+rule(:addition) { multiplication >> (op >> multiplication).repeat | multiplication }
+rule(:multiplication) { power >> (op >> power).repeat | power }
+rule(:power) { unary >> (str('^') >> power).maybe | unary }
+```
+
+Lower precedence operators are higher in the rule hierarchy. Comparison is tried first, falling through to addition, then multiplication, then power.
+
+### Right Associativity for Exponentiation
+
+Power uses `.maybe` for right associativity:
+
+```ruby
+rule(:power) {
+  unary.as(:left) >>
+  (str('^').as(:op) >> power.as(:right)).maybe |
+  unary
+}
+```
+
+Recursive reference to `power` on the right creates `2^(3^2)` instead of `(2^3)^2`.
+
+### Unary Operators
+
+Unary minus and logical not prefix expressions:
+
+```ruby
+rule(:unary) {
+  (str('-').as(:op) >> unary.as(:operand)).as(:unary) |
+  (str('!').as(:op) >> unary.as(:operand)).as(:unary) |
+  primary
+}
+```
+
+Recursive definition allows `--5` (double negation).
+
+### Function Calls
+
+Functions have name followed by parenthesized arguments:
+
+```ruby
+rule(:funcall) {
+  (match('[a-zA-Z_]') >> match('[a-zA-Z0-9_]').repeat).as(:name) >>
+  lparen >>
+  arglist.as(:args) >>
+  rparen
+}
+
+rule(:arglist) {
+  (expression >> (comma >> expression).repeat).maybe
+}
+```
+
+Arguments are comma-separated expressions; empty arglists are valid.
+
+### AST Node Classes
+
+Ruby structs represent AST nodes with evaluation logic:
+
+```ruby
+BinaryOp = Struct.new(:left, :op, :right) do
+  def eval(ctx)
+    l = left.eval(ctx)
+    r = right.eval(ctx)
+    case op
+    when '+' then l + r
+    when '-' then l - r
+    # ...
+    end
+  end
+end
+```
+
+Each node type implements `eval(context)` for recursive evaluation.
+
+### Evaluation Context
+
+Context holds variables and functions:
+
+```ruby
+class EvalContext
+  attr_accessor :variables, :functions
+
+  def initialize
+    @variables = { 'PI' => Math::PI, 'E' => Math::E }
+    @functions = {
+      'sin' => ->(args) { Math.sin(args[0] || 0) },
+      'cos' => ->(args) { Math.cos(args[0] || 0) },
+      # ...
+    }
+  end
+end
+```
+
+Functions are Ruby lambdas that receive argument arrays.
+
+## Output Types
+
+```ruby
+Number.new(42.0)                      # Numeric literal
+Variable.new("x")                     # Variable reference
+BinaryOp.new(Number.new(1), "+", Number.new(2))  # Binary operation
+UnaryOp.new("-", Number.new(5))       # Unary negation
+FunctionCall.new("sin", [Variable.new("x")])  # Function call
+```
+
+After `eval`: returns Float result.
+
+## Design Decisions
+
+### Why Layered Rules for Precedence?
+
+Layered rules naturally express precedence in PEG parsers. Each layer only "sees" operators at its level, preventing incorrect bindings.
+
+### Why Structs with eval Methods?
+
+Structs are lightweight and can define instance methods. Embedding `eval` in each node enables clean recursive evaluation without visitor patterns.
+
+### Why Lambda for Functions?
+
+Ruby lambdas are first-class and can be stored in a hash. This allows easy extension of the function library without modifying the evaluator.