parsanol 1.3.13-arm-linux

data/lib/parsanol/string_view.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Zero-copy string view that references original input.
+  #
+  # StringView avoids string copies by maintaining a reference to the
+  # original string with offset and length. Strings are only materialized
+  # when explicitly requested via #to_s.
+  #
+  # == Usage
+  #
+  #   view = StringView.new(input_string, offset: 10, length: 5)
+  #   view.to_s  # Materializes string only when needed
+  #   view[0]    # Direct character access without copying
+  #
+  # == Performance
+  #
+  # - No string allocation until to_s called
+  # - Direct character access without copying
+  # - Reduced GC pressure from intermediate strings
+  # - Caches materialized strings for reuse
+  #
+  # == Design Principles
+  #
+  # 1. Zero-Copy: Reference original string, don't copy
+  # 2. Lazy Materialization: Create strings only when to_s called
+  # 3. Caching: Cache materialized strings for reuse
+  # 4. Compatibility: Acts like String where needed
+  # 5. Extensibility: Foundation for Rope (Phase 3.2)
+  #
+  class StringView
+    include Resettable
+
+    # @return [String] Original input string
+    attr_reader :string
+
+    # @return [Integer] Byte offset into string
+    attr_reader :offset
+
+    # @return [Integer] Length in bytes
+    attr_reader :length
+
+    # Initialize a new StringView.
+    #
+    # @param string [String] Original input string
+    # @param offset [Integer] Byte offset (default: 0)
+    # @param length [Integer] Length in bytes (default: string.bytesize)
+    #
+    def initialize(string, offset: 0, length: nil)
+      @string = string
+      @offset = offset
+      @length = length || (string.bytesize - offset)
+      @materialized = nil
+    end
+
+    # Materialize to string (with caching).
+    #
+    # First call creates string slice, subsequent calls return cached.
+    # This implements lazy evaluation - strings are only created when
+    # explicitly needed, not during parsing.
+    #
+    # @return [String] Materialized string
+    #
+    def to_s
+      @materialized ||= @string.byteslice(@offset, @length)
+    end
+
+    # Get character at index (zero-copy).
+    #
+    # Direct access to character in original string without creating
+    # intermediate string objects.
+    #
+    # @param index [Integer] Zero-based index
+    # @return [String, nil] Character at index or nil
+    #
+    def [](index)
+      return nil if index.negative? || index >= @length
+
+      @string.byteslice(@offset + index, 1)
+    end
+
+    # Get byte size.
+    #
+    # @return [Integer] Length in bytes
+    #
+    def bytesize
+      @length
+    end
+
+    alias size bytesize
+    alias length bytesize
+
+    # Check if empty.
+    #
+    # @return [Boolean] true if length is 0
+    #
+    def empty?
+      @length.zero?
+    end
+
+    # Compare with another object.
+    #
+    # StringViews are only equal if they reference the exact same string object
+    # (by object_id) and have the same offset/length. This is consistent with
+    # the view pattern - they're views of a specific string instance.
+    #
+    # When comparing with a String, content is compared.
+    #
+    # @param other [Object] Object to compare with
+    # @return [Boolean] true if equal
+    #
+    def ==(other)
+      case other
+      when String
+        to_s == other
+      when StringView
+        # Only equal if viewing the exact same string object with same range
+        @string.equal?(other.string) &&
+          @offset == other.offset &&
+          @length == other.length
+      else
+        super
+      end
+    end
+
+    alias eql? ==
+
+    # Hash code for hashing.
+    #
+    # Uses object_id of string to avoid materializing the view.
+    #
+    # @return [Integer] Hash code
+    #
+    def hash
+      [@string.object_id, @offset, @length].hash
+    end
+
+    # Create substring view (zero-copy).
+    #
+    # Returns a new StringView referencing a substring of this view.
+    # No string allocation occurs - just a new view with adjusted offset.
+    #
+    # @param start [Integer] Start offset (relative to view)
+    # @param len [Integer] Length
+    # @return [StringView] New view of substring
+    #
+    def slice(start, len)
+      # Handle edge cases
+      if len <= 0 || start >= @length
+        return self.class.new(@string, offset: @offset,
+                                       length: 0)
+      end
+
+      # Clamp start to valid range [0, @length)
+      clamped_start = [[start, 0].max, @length].min
+
+      # Calculate actual offset in original string
+      actual_offset = @offset + clamped_start
+
+      # Calculate actual length (min of requested and available)
+      available = @length - clamped_start
+      actual_length = [len, available].min
+
+      self.class.new(@string, offset: actual_offset, length: actual_length)
+    end
+
+    # Inspect for debugging.
+    #
+    # Shows whether string has been materialized.
+    #
+    # @return [String] Inspection string
+    #
+    def inspect
+      if @materialized
+        "#<StringView:#{object_id} @offset=#{@offset} @length=#{@length} cached=#{@materialized.inspect}>"
+      else
+        "#<StringView:#{object_id} @offset=#{@offset} @length=#{@length}>"
+      end
+    end
+
+    # Reset for pooling (if needed in future phases).
+    #
+    # Allows StringView objects to be reused from a pool.
+    #
+    # @param string [String] New string
+    # @param offset [Integer] New offset
+    # @param length [Integer] New length
+    # @return [self]
+    #
+    def reset!(string, offset, length)
+      @string = string
+      @offset = offset
+      @length = length
+      @materialized = nil
+      self
+    end
+  end
+end

data/lib/parsanol/transform.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "parsanol/pattern"
+
+# Tree transformation engine for converting parse trees into abstract syntax trees.
+#
+# Transforms expression trees through depth-first post-order traversal.
+# When a rule pattern matches a node, that node is replaced by the result
+# of the rule's transformation block. Unmatched nodes pass through unchanged.
+#
+# @example Basic transformation class
+#   class NumberTransform < Parsanol::Transform
+#     rule(int: simple(:value)) { Integer(value) }
+#     rule(float: simple(:value)) { Float(value) }
+#   end
+#
+#   transform = NumberTransform.new
+#   transform.apply({ int: '42' })  # => 42
+#
+# @example Inline transformation definition
+#   transform = Parsanol::Transform.new do
+#     rule(a: simple(:x)) { x.upcase }
+#   end
+#   transform.apply({ a: 'hello' })  # => 'HELLO'
+#
+# @example Using context for external dependencies
+#   builder = AstBuilder.new
+#   transform = Parsanol::Transform.new do
+#     rule(expr: simple(:e)) { builder.build_node(e) }
+#     rule(expr: simple(:e)) { |ctx| ctx[:builder].build_node(e) }
+#   end
+#   transform.apply(tree, builder: builder)
+#
+# Rule blocks can have two forms:
+# - Zero-arity: executed in a context where pattern bindings are local variables
+# - Arity-1: receives a hash of bindings as the argument
+#
+# Inspired by tree transformation patterns in parser combinators.
+#
+module Parsanol
+  class Transform
+    include Parsanol
+
+    # Class-level rule definition for subclass inheritance.
+    class << self
+      include Parsanol
+
+      # Defines a transformation rule at the class level.
+      # Rules are inherited by subclasses and evaluated in reverse order
+      # (most recently defined rules have highest precedence).
+      #
+      # @param expression [Object] pattern to match against tree nodes
+      # @yield block to execute when pattern matches, receives bindings
+      # @return [Array] the updated rules list
+      #
+      def rule(expression, &transformer)
+        class_rules.unshift([Parsanol::Pattern.new(expression), transformer])
+      end
+
+      # Returns all class-level rules defined for this transform.
+      #
+      # @return [Array<Array>] array of [pattern, block] pairs
+      #
+      def class_rules
+        @class_rules ||= []
+      end
+
+      # Ensures subclasses inherit parent rules.
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@class_rules, class_rules.dup)
+      end
+    end
+
+    # Creates a new transform instance.
+    #
+    # @param strict [Boolean] if true, raises on unmatched hash nodes
+    # @yield optional block for inline rule definition
+    #
+    def initialize(strict = false, &definition)
+      @strict_mode = strict
+      @instance_rules = []
+
+      instance_eval(&definition) if definition
+    end
+
+    # Defines an instance-level transformation rule.
+    # Instance rules are checked before class rules.
+    #
+    # @param expression [Object] pattern to match
+    # @yield transformation block
+    #
+    def rule(expression, &transformer)
+      @instance_rules.unshift([Parsanol::Pattern.new(expression), transformer])
+    end
+
+    # Applies transformation to a parse tree.
+    #
+    # Performs depth-first post-order traversal, transforming nodes
+    # from leaves to root. Context values are available in rule blocks.
+    #
+    # @param tree [Object] parse tree to transform
+    # @param context [Hash, nil] optional context bindings
+    # @return [Object] transformed tree
+    #
+    def apply(tree, context = nil)
+      # First, recursively transform children (depth-first)
+      transformed = transform_children(tree, context)
+
+      # Then, try to match and transform this node
+      attempt_transformation(transformed, context)
+    end
+
+    # Returns combined class and instance rules.
+    # Instance rules take precedence over class rules.
+    #
+    # @return [Array<Array>] all applicable rules
+    #
+    def all_rules
+      @instance_rules + self.class.class_rules
+    end
+
+    # Executes a transformation block with the given bindings.
+    # Public API for testing and advanced usage.
+    #
+    # @param bindings [Hash] pattern bindings
+    # @param block [Proc] transformation block
+    # @return [Object] block result
+    #
+    def call_on_match(bindings, block)
+      return nil unless block
+
+      if block.arity == 1
+        block.call(bindings)
+      else
+        Context.new(bindings).instance_eval(&block)
+      end
+    end
+
+    private
+
+    # Recursively transforms child nodes based on tree type.
+    #
+    # @param node [Object] current tree node
+    # @param ctx [Hash, nil] context bindings
+    # @return [Object] node with transformed children
+    #
+    def transform_children(node, ctx)
+      case node
+      when Hash
+        transform_hash_children(node, ctx)
+      when Array
+        transform_array_children(node, ctx)
+      else
+        node
+      end
+    end
+
+    # Transforms all values in a hash.
+    #
+    def transform_hash_children(hash, ctx)
+      result = {}
+      hash.each { |key, val| result[key] = apply(val, ctx) }
+      result
+    end
+
+    # Transforms all elements in an array.
+    #
+    def transform_array_children(array, ctx)
+      array.map { |element| apply(element, ctx) }
+    end
+
+    # Attempts to match a node against all rules and transform if matched.
+    #
+    # @param node [Object] node to potentially transform
+    # @param ctx [Hash, nil] context bindings
+    # @return [Object] transformed node or original if no match
+    #
+    def attempt_transformation(node, ctx)
+      all_rules.each do |pattern, block|
+        bindings = pattern.match(node, ctx)
+        next unless bindings
+
+        return execute_block(block, bindings)
+      end
+
+      # No rule matched
+      handle_unmatched(node)
+    end
+
+    # Executes a transformation block with proper binding context.
+    #
+    # @param block [Proc] transformation block
+    # @param bindings [Hash] matched pattern bindings
+    # @return [Object] block result
+    #
+    def execute_block(block, bindings)
+      return nil unless block
+
+      if block.arity == 1
+        # Block expects bindings as argument
+        block.call(bindings)
+      else
+        # Block executes in context with bindings as local variables
+        Context.new(bindings).instance_eval(&block)
+      end
+    end
+
+    # Handles nodes that didn't match any rule.
+    #
+    # @param node [Object] unmatched node
+    # @return [Object] the node (or raises in strict mode)
+    # @raise [NotImplementedError] if strict mode and node is a Hash
+    #
+    def handle_unmatched(node)
+      return node unless @strict_mode
+      return node unless node.is_a?(Hash)
+
+      # In strict mode, provide helpful error about what wasn't matched
+      signature = node.transform_values(&:class)
+      raise NotImplementedError, "Failed to match #{signature.inspect}"
+    end
+  end
+end
+
+require "parsanol/context"

data/lib/parsanol/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Parsanol
+  VERSION = "1.3.13"
+end

data/lib/parsanol/wasm/README.md

@@ -0,0 +1,80 @@
+# @parsanol/wasm
+
+High-performance PEG parser using WebAssembly. Designed for use with Opal (Ruby in JavaScript) and general JavaScript applications.
+
+## Features
+
+- **18-44x faster** than pure Ruby parser
+- **99.5% fewer allocations**
+- Works in browsers and Node.js
+- Full TypeScript support
+- Compatible with Opal
+
+## Installation
+
+```bash
+npm install @parsanol/wasm
+```
+
+## Usage
+
+### Browser/ESM
+
+```html
+<script type="module">
+  import { initParsanol, ParsanolParser } from '@parsanol/wasm';
+
+  // Initialize WASM (call once)
+  await initParsanol();
+
+  // Create parser from grammar JSON
+  const grammar = {
+    atoms: [
+      { Str: { pattern: "hello" } }
+    ],
+    root: 0
+  };
+
+  const parser = new ParsanolParser(grammar);
+
+  // Parse input
+  const result = parser.parse('hello');
+  console.log(result); // "hello"
+</script>
+```
+
+### Node.js
+
+```javascript
+const { initParsanol, ParsanolParser } = require('@parsanol/wasm');
+
+async function main() {
+  await initParsanol();
+
+  const parser = new ParsanolParser(grammarJson);
+  const result = parser.parse('input text');
+  console.log(result);
+}
+
+main();
+```
+
+### Opal (Ruby in Browser)
+
+```ruby
+# First initialize WASM in JavaScript:
+# Parsanol::WasmParser.init.then { puts "ready" }
+
+require 'parsanol/wasm_parser'
+
+grammar_json = {
+  atoms: [
+    { Str: { pattern: "hello" } }
+  ],
+  root: 0
+}.to_json
+
+parser = Parsanol::WasmParser.new(grammar_json)
+result = parser.parse('hello')
+puts result  # => "hello"
+```

data/lib/parsanol/wasm/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@parsanol/wasm",
+  "version": "0.1.0",
+  "description": "High-performance PEG parser using WebAssembly for Opal and JavaScript",
+  "main": "parsanol.js",
+  "module": "parsanol.js",
+  "types": "parsanol.d.ts",
+  "browser": "parsanol.js",
+  "files": [
+    "parsanol.js",
+    "parsanol.d.ts",
+    "parsanol_native.js",
+    "parsanol_native_bg.js",
+    "parsanol_native_bg.wasm",
+    "parsanol_native.d.ts"
+  ],
+  "scripts": {
+    "build": "cd ../../ext/parsanol_native && wasm-pack build --features wasm --target web --out-dir ../../lib/parsanol/wasm",
+    "build:node": "cd ../../ext/parsanol_native && wasm-pack build --features wasm --target nodejs --out-dir ../../lib/parsanol/wasm-node",
+    "test": "node test/parsanol.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "parser",
+    "peg",
+    "parsing-expression-grammar",
+    "wasm",
+    "webassembly",
+    "opal",
+    "ruby",
+    "performance"
+  ],
+  "author": "Ribose Inc. <open.source@ribose.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parsanol/parsanol-rs.git",
+    "directory": "lib/parsanol/wasm"
+  },
+  "bugs": {
+    "url": "https://github.com/parsanol/parsanol-ruby/issues"
+  },
+  "homepage": "https://github.com/parsanol/parsanol-ruby#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "sideEffects": [
+    "parsanol_native.js",
+    "parsanol_native_bg.js"
+  ]
+}