parsanol 3.0.0

data/example/json/zero_copy.rb

@@ -0,0 +1,316 @@
+# JSON Parser Example - ZeroCopy: Mirrored Objects (Direct FFI)
+#
+# This example demonstrates ZeroCopy for parsing JSON:
+# 1. Rust parser (parsanol-rs) does the parsing
+# 2. Rust constructs typed JSON value objects
+# 3. Direct Ruby object construction via FFI (no serialization!)
+# 4. Maximum performance with zero-copy
+#
+# This option provides the best performance for JSON parsing.
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol'
+
+# NOTE: This example requires:
+# 1. ZeroCopy extension support for parse_to_objects
+# 2. #[derive(RubyObject)] proc macro in Rust
+# 3. Matching Ruby class definitions
+#
+# This serves as an API preview.
+
+# Step 1: Define Ruby classes that mirror Rust struct definitions
+module Json
+  class Value
+    def to_ruby
+      raise NotImplementedError
+    end
+  end
+
+  class Null < Value
+    def to_ruby = nil
+    def to_s = "null"
+  end
+
+  class Bool < Value
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_ruby = @value
+    def to_s = @value ? "true" : "false"
+  end
+
+  class Number < Value
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_ruby = @value
+    def to_s = @value.to_s
+  end
+
+  class String < Value
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def to_ruby = @value
+    def to_s = "\"#{@value}\""
+  end
+
+  class Array < Value
+    attr_reader :elements
+
+    def initialize(elements)
+      @elements = elements
+    end
+
+    def to_ruby = @elements.map(&:to_ruby)
+    def to_s = "[#{@elements.map(&:to_s).join(', ')}]"
+  end
+
+  class Object < Value
+    attr_reader :members
+
+    def initialize(members)
+      @members = members
+    end
+
+    def to_ruby = @members.transform_values(&:to_ruby)
+
+    def to_s
+      pairs = @members.map { |k, v| "\"#{k}\": #{v}" }
+      "{#{pairs.join(', ')}}"
+    end
+
+    def [](key)
+      @members[key]
+    end
+
+    def keys
+      @members.keys
+    end
+  end
+end
+
+# Step 2: Define the parser with output type mapping
+class JsonParser < Parsanol::Parser
+  # Include ZeroCopy module (planned)
+  # include Parsanol::ZeroCopy
+
+  root :json
+
+  rule(:json) { space? >> value >> space? }
+
+  rule(:value) {
+    object |
+    array |
+    string |
+    number |
+    true_value |
+    false_value |
+    null_value
+  }
+
+  rule(:object) {
+    str('{') >> space? >>
+    (entry >> (comma >> entry).repeat).maybe.as(:object) >>
+    space? >> str('}')
+  }
+
+  rule(:entry) {
+    (string.as(:key) >> space? >> colon >> space? >> value.as(:val)).as(:entry)
+  }
+
+  rule(:array) {
+    str('[') >> space? >>
+    (value >> (comma >> value).repeat).maybe.as(:array) >>
+    space? >> str(']')
+  }
+
+  rule(:string) {
+    str('"') >> (
+      str('\\') >> any | str('"').absent? >> any
+    ).repeat.as(:string) >> str('"')
+  }
+
+  rule(:number) {
+    (
+      str('-').maybe >>
+      (str('0') | (match('[1-9]') >> digit.repeat)) >>
+      (str('.') >> digit.repeat(1)).maybe >>
+      (match('[eE]') >> (str('+') | str('-')).maybe >> digit.repeat(1)).maybe
+    ).as(:number)
+  }
+
+  rule(:true_value) { str('true').as(:true) }
+  rule(:false_value) { str('false').as(:false) }
+  rule(:null_value) { str('null').as(:null) }
+
+  rule(:digit) { match('[0-9]') }
+  rule(:space) { match('\s').repeat(1) }
+  rule(:space?) { space.maybe }
+  rule(:comma) { space? >> str(',') >> space? }
+  rule(:colon) { str(':') }
+
+  # Output type mapping (planned feature)
+  # output_types(
+  #   null: Json::Null,
+  #   bool: Json::Bool,
+  #   number: Json::Number,
+  #   string: Json::String,
+  #   array: Json::Array,
+  #   object: Json::Object
+  # )
+end
+
+# Step 3: Parse with direct object construction
+def parse_json(input)
+  parser = JsonParser.new
+
+  # ZeroCopy: Parse and get direct Ruby objects
+  # NOTE: This requires native extension support
+  # value = parser.parse(input)
+  # # value is already a Json::String, Json::Number, etc.!
+  # # No transform needed, no JSON serialization!
+
+  # For demonstration, simulate what ZeroCopy would return
+  value = simulate_parse(input)
+  puts "Parsed: #{value.class}"
+  puts "Value: #{value.to_s}"
+
+  result = value.to_ruby
+  puts "Ruby: #{result.inspect[0..100]}..."
+
+  result
+end
+
+# Simulated parsing for demonstration
+def simulate_parse(input)
+  input = input.strip
+
+  case input
+  when 'null'
+    Json::Null.new
+  when 'true'
+    Json::Bool.new(true)
+  when 'false'
+    Json::Bool.new(false)
+  when /^"(.*)"$/
+    Json::String.new($1)
+  when /^-?\d+$/
+    Json::Number.new(input.to_i)
+  when /^-?\d+\.\d+$/
+    Json::Number.new(input.to_f)
+  when /^\[(.*)\]$/
+    inner = $1.strip
+    return Json::Array.new([]) if inner.empty?
+
+    # Simple split for demonstration
+    elements = inner.split(',').map { |e| simulate_parse(e.strip) }
+    Json::Array.new(elements)
+  when /^\{(.*)\}$/
+    inner = $1.strip
+    return Json::Object.new({}) if inner.empty?
+
+    # Simple parse for demonstration
+    members = {}
+    inner.scan(/"([^"]+)":\s*([^,}]+)/) do |key, val|
+      members[key] = simulate_parse(val.strip)
+    end
+    Json::Object.new(members)
+  else
+    raise "Cannot parse: #{input}"
+  end
+end
+
+# Example usage
+if __FILE__ == $0
+  puts "=" * 60
+  puts "JSON Parser Example - ZeroCopy: Mirrored Objects"
+  puts "=" * 60
+  puts
+  puts "NOTE: This example shows the planned API for ZeroCopy."
+  puts "The native extension support for parse_to_objects is coming soon."
+  puts
+
+  test_cases = [
+    ['"hello"', "hello"],
+    ['42', 42],
+    ['true', true],
+    ['null', nil],
+    ['[1, 2, 3]', [1, 2, 3]],
+    ['{"a": 1}', { "a" => 1 }],
+  ]
+
+  test_cases.each do |input, expected|
+    puts
+    puts "-" * 40
+    puts "Input: #{input}"
+    begin
+      result = parse_json(input)
+      status = result == expected ? "✓ PASS" : "✗ FAIL"
+      puts "Expected: #{expected.inspect}, Got: #{result.inspect} - #{status}"
+    rescue => e
+      puts "Error: #{e.message}"
+      puts "✗ FAIL"
+    end
+  end
+
+  # Show type safety benefit
+  puts
+  puts "-" * 40
+  puts "Type Safety Example:"
+  json_obj = simulate_parse('{"name": "Alice", "age": 30}')
+  puts "Parsed object type: #{json_obj.class}"
+  puts "Name field type: #{json_obj['name'].class}"
+  puts "Age field type: #{json_obj['age'].class}"
+
+  puts
+  puts "=" * 60
+  puts "ZeroCopy Benefits for JSON:"
+  puts "- FASTEST: No serialization overhead"
+  puts "- Type-safe: Each JSON value type is a different class"
+  puts "- Methods: Can add custom methods to Json::Object, etc."
+  puts "- Zero-copy: Direct construction from Rust"
+  puts
+  puts "When to use ZeroCopy for JSON:"
+  puts "- High-throughput JSON parsing"
+  puts "- When you need typed access to values"
+  puts "- When you want custom methods on JSON objects"
+  puts "=" * 60
+end
+
+# Rust code that would be needed (for reference):
+#
+# // In parsanol-rs
+# use parsanol_ruby_derive::RubyObject;
+#
+# #[derive(Debug, Clone, RubyObject)]
+# #[ruby_class("Json::Value")]
+# pub enum JsonValue {
+#     #[ruby_variant("null")]
+#     Null,
+#
+#     #[ruby_variant("bool")]
+#     Bool(bool),
+#
+#     #[ruby_variant("number")]
+#     Number(f64),
+#
+#     #[ruby_variant("string")]
+#     String(String),
+#
+#     #[ruby_variant("array")]
+#     Array(Vec<JsonValue>),
+#
+#     #[ruby_variant("object")]
+#     Object(HashMap<String, JsonValue>),
+# }

data/example/json/zero_copy.rb.md

@@ -0,0 +1,36 @@
+# JSON (Zero-Copy - Option C)
+
+## Purpose
+
+This implementation demonstrates direct FFI object construction for JSON
+parsing without serialization overhead.
+
+## When to Use
+
+- Maximum performance required
+- Production systems
+- When zero-copy is critical
+
+## Key Concepts
+
+1. **Direct FFI**: No serialization overhead
+2. **Ruby Object Construction**: Direct via rb_funcall
+3. **Type Safety**: Mirrored types on both sides
+
+## Running
+
+```bash
+ruby example/json/zero_copy.rb
+```
+
+## Output
+
+```
+Input: {"key": "value"}
+Result: Hash
+Value: {"key" => "value"}
+```
+
+## Note
+
+This is the fastest option but requires more complex FFI setup.

data/example/local/basic.rb

@@ -0,0 +1,34 @@
+
+# An exploration of two ideas: 
+#   a) Constructing a whole parser inline, without the artificial class around
+#      it. 
+# and:
+#   b) Constructing non-greedy or non-blind parsers by transforming the 
+#      grammar.
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parsanol/parslet'
+include Parsanol::Parslet
+
+a =  str('a').repeat >> str('aa')
+
+# E1% E2
+# 
+# S = E2 | E1 S 
+
+def this(name, &block); return Parsanol::Atoms::Entity.new(name, &block) end
+def epsilon; any.absent? end 
+
+# Traditional repetition will try as long as the pattern can be matched and 
+# then give up. This is greedy and blind. 
+a = str('a').as(:e) >> this('a') { a }.as(:rec) | epsilon
+
+# Here's a pattern match that is greedy and non-blind. The first pattern
+# 'a'* will be tried as many times as possible, while still matching the 
+# end pattern 'aa'.
+b = str('aa').as(:e2) >> epsilon | str('a').as(:e1) >> this('b') { b }.as(:rec)
+
+p a.parse('aaaa')
+p b
+p b.parse('aaaa')

data/example/local/basic.rb.md

@@ -0,0 +1,91 @@
+# Non-Greedy Parsing Patterns - Ruby Implementation
+
+## How to Run
+
+```bash
+cd parsanol-ruby/example/local
+ruby basic.rb
+```
+
+## Code Walkthrough
+
+### The Problem with Greedy Parsing
+
+Traditional repetition is greedy and blind:
+
+```ruby
+a = str('a').repeat >> str('aa')
+# Input: 'aaaa'
+# Fails! repeat consumes all 'a's, leaving nothing for 'aa'
+```
+
+Greedy repetition takes as much as possible without considering what follows.
+
+### Non-Blind Pattern
+
+Transform the grammar to look ahead:
+
+```ruby
+# E1% E2 transformation:
+# S = E2 | E1 S
+
+def this(name, &block)
+  Parsanol::Atoms::Entity.new(name, &block)
+end
+def epsilon
+  any.absent?
+end
+
+a = str('a').as(:e) >> this('a') { a }.as(:rec) | epsilon
+```
+
+This recursively matches while checking alternatives.
+
+### Greedy Non-Blind Alternative
+
+Put the terminal first:
+
+```ruby
+b = str('aa').as(:e2) >> epsilon |
+    str('a').as(:e1) >> this('b') { b }.as(:rec)
+```
+
+Try to match the end (`aa`) first, then recurse if that fails.
+
+### Entity for Recursion
+
+The `this()` helper enables recursive rule definition:
+
+```ruby
+def this(name, &block)
+  Parsanol::Atoms::Entity.new(name, &block)
+end
+```
+
+Entity delays evaluation until parse time, allowing forward references.
+
+## Output Types
+
+```ruby
+# Greedy blind (fails):
+a.parse('aaaa')  # => ParseFailed
+
+# Greedy non-blind (succeeds):
+b.parse('aaaa')
+# => {:e2=>"aa"@0}
+#    or with proper structure showing the match
+```
+
+## Design Decisions
+
+### Why Transform Instead of Modify Parser?
+
+Grammar transformation is more flexible than modifying the parser engine. Different transformations achieve different behaviors.
+
+### Why Entity for Recursion?
+
+Ruby blocks capture variables at definition time. Entity provides a way to reference rules that aren't defined yet.
+
+### Ruby-Only Feature
+
+These advanced PEG patterns use Parslet's Ruby-specific constructs. They demonstrate theoretical parsing concepts more than practical usage.

data/example/local/example.json

@@ -0,0 +1,38 @@
+{
+  "id": "local",
+  "title": "Local Variable Parsing",
+  "description": "Demonstrate non-greedy parsing patterns using local variable bindings.",
+  "category": "conceptual",
+  "tags": ["local", "non-greedy", "parslet", "context"],
+  "difficulty": "intermediate",
+  "concepts": ["local binding", "non-greedy matching", "context", "delimiters"],
+
+  "motivation": {
+    "why": "Local provides non-greedy parsing within a specific context. This enables matching up to delimiters without consuming them.",
+    "useCases": [
+      "Matching up to delimiters",
+      "Context-sensitive parsing",
+      "Non-greedy content extraction"
+    ]
+  },
+
+  "inputFormat": {
+    "description": "Content with delimiters to parse non-greedily.",
+    "examples": [
+      { "input": "content", "description": "Content to parse", "valid": true }
+    ]
+  },
+
+  "outputFormat": {
+    "description": "Non-greedily matched content.",
+    "structure": {
+      "content": { "description": "The locally matched content" }
+    }
+  },
+
+  "rubyOnly": true,
+  "parsletCompatible": true,
+  "implementations": {
+    "ruby": { "basic": "basic.rb" }
+  }
+}