parsanol 1.0.1-aarch64-linux

data/lib/parsanol/rope.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Rope data structure for efficient string accumulation.
+  #
+  # Uses deferred concatenation to avoid O(n²) repeated string building.
+  # Segments are accumulated in O(1) time and joined once in O(n) time when
+  # converted to a final string.
+  #
+  # @example Basic usage
+  #   rope = Rope.new
+  #   rope.append('hello')
+  #   rope.append(' ')
+  #   rope.append('world')
+  #   rope.to_s  # => "hello world"
+  #
+  # @example With Slices
+  #   rope = Rope.new
+  #   rope.append(Slice.new(0, 'hello'))
+  #   rope.append(Slice.new(5, ' world'))
+  #   rope.to_s  # => "hello world"
+  #
+  class Rope
+    # Creates a new empty Rope.
+    def initialize
+      @segments = []
+      @frozen = false
+    end
+
+    # Appends a string or Slice to the rope.
+    #
+    # This is an O(1) operation. The segment is stored as-is and will be
+    # joined later when {#to_s} is called.
+    #
+    # @param segment [String, Slice] The segment to append
+    # @return [Rope] self for method chaining
+    # @raise [FrozenError] if rope has been frozen by calling {#to_s}
+    def append(segment)
+      raise FrozenError, "can't modify frozen Rope" if @frozen
+
+      @segments << segment
+      self
+    end
+
+    # Converts the rope to a final string.
+    #
+    # This is an O(n) operation performed once. After calling this method,
+    # the rope is frozen and cannot be modified further.
+    #
+    # @return [String] The concatenated result of all segments
+    def to_s
+      @frozen = true
+      @segments.join
+    end
+
+    # Checks if the rope is empty (contains no segments).
+    #
+    # @return [Boolean] true if no segments have been appended
+    def empty?
+      @segments.empty?
+    end
+
+    # Estimates the total size of all segments.
+    #
+    # This is an estimate because segments may be Slice objects or other
+    # types that respond to #size or #to_s.
+    #
+    # @return [Integer] The sum of all segment sizes
+    def size
+      @segments.sum { |s| s.respond_to?(:size) ? s.size : s.to_s.size }
+    end
+
+    # Creates a rope from an existing string.
+    #
+    # @param str [String] The string to initialize the rope with
+    # @return [Rope] A new rope containing the string
+    def self.from_string(str)
+      new.tap { |r| r.append(str) unless str.empty? }
+    end
+  end
+end

data/lib/parsanol/scope.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Scoped variable bindings for parser context management. Provides a
+# stack-like interface for creating nested scopes that inherit from
+# parent scopes.
+#
+# @example Basic usage
+#   scope = Parsanol::Scope.new
+#   scope[:x] = 1
+#   scope.push      # Create nested scope
+#   scope[:x]       # => 1 (inherited from parent)
+#   scope[:y] = 2
+#   scope.pop       # Return to parent scope
+#   scope[:y]       # raises NotFound
+#
+# Inspired by lexical scoping patterns in programming languages.
+#
+module Parsanol
+  class Scope
+    # Error raised when attempting to access an undefined binding.
+    class UndefinedVariable < StandardError
+    end
+    # Legacy alias for backward compatibility
+    NotFound = UndefinedVariable
+
+    # Internal class representing a single scope level. Each frame can
+    # look up values in its parent frame if not found locally.
+    class Frame
+      # @return [Frame, nil] parent frame in the scope chain
+      attr_reader :parent_frame
+
+      # Creates a new frame optionally linked to a parent.
+      #
+      # @param parent [Frame, nil] the parent frame to inherit from
+      def initialize(parent = nil)
+        @parent_frame = parent
+        @bindings = {}
+      end
+
+      # Retrieves a value by key, searching parent frames if necessary.
+      #
+      # @param key [Symbol] the variable name to look up
+      # @return [Object] the bound value
+      # @raise [UndefinedVariable] if key not found in any frame
+      def fetch(key)
+        if @bindings.key?(key)
+          @bindings[key]
+        elsif @parent_frame
+          @parent_frame.fetch(key)
+        else
+          raise UndefinedVariable, "No binding for #{key.inspect}"
+        end
+      end
+
+      # Stores a value in the current frame.
+      #
+      # @param key [Symbol] the variable name
+      # @param value [Object] the value to bind
+      # @return [Object] the stored value
+      def store(key, value)
+        @bindings[key] = value
+      end
+
+      alias [] fetch
+      alias []= store
+    end
+
+    # Creates a new scope with an empty root frame.
+    def initialize
+      @active_frame = Frame.new
+    end
+
+    # Retrieves a value from the current scope chain.
+    #
+    # @param key [Symbol] the variable name
+    # @return [Object] the bound value
+    # @raise [UndefinedVariable] if not found
+    def [](key)
+      @active_frame.fetch(key)
+    end
+
+    # Stores a value in the current frame.
+    #
+    # @param key [Symbol] the variable name
+    # @param value [Object] the value to bind
+    def []=(key, value)
+      @active_frame.store(key, value)
+    end
+
+    # Creates a new nested scope frame. Call #pop to restore.
+    #
+    # @return [void]
+    def push
+      @active_frame = Frame.new(@active_frame)
+    end
+
+    # Returns to the parent scope frame.
+    #
+    # @return [void]
+    def pop
+      @active_frame = @active_frame.parent_frame
+    end
+  end
+end

data/lib/parsanol/slice.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Source position tracker for parsed content.
+# Preserves both the string value and its byte offset in the original input,
+# enabling precise error reporting and source mapping.
+#
+# Inspired by string slicing concepts in text editors and IDEs.
+module Parsanol
+  class Slice
+    include Parsanol::Resettable
+
+    attr_reader :content, :position_cache
+
+    # Creates a slice with position tracking.
+    #
+    # @param byte_offset [Integer] position in original input
+    # @param string_content [String] the slice content
+    # @param cache [Object] optional cache for line/column lookup
+    def initialize(byte_offset = 0, string_content = '', cache = nil)
+      @byte_position = byte_offset
+      @content = string_content
+      @position_cache = cache
+    end
+
+    # Resets slice state for object pool reuse.
+    #
+    # @param new_offset [Integer] new byte position
+    # @param new_content [String] new content
+    # @param new_cache [Object] new line cache
+    # @return [self] for method chaining
+    def reset!(new_offset = 0, new_content = '', new_cache = nil)
+      @byte_position = new_offset
+      @content = new_content
+      @position_cache = new_cache
+      self
+    end
+
+    # Creates a Slice from a Rope concatenation.
+    #
+    # @param rope [Parsanol::Rope] rope to convert
+    # @param offset [Integer] byte position
+    # @param cache [Object] optional cache
+    # @return [Parsanol::Slice] new slice
+    def self.from_rope(rope, offset, cache = nil)
+      new(offset, rope.to_s, cache)
+    end
+
+    # @return [Integer] byte offset in original input
+    def offset
+      @byte_position
+    end
+
+    alias bytepos offset
+    alias charpos offset
+    alias str content # backward compatibility
+    alias line_cache position_cache # backward compatibility
+
+    # Compares slices or strings for equality.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if equal
+    def ==(other)
+      return content == other if other.is_a?(String)
+      return content == other.content if other.is_a?(Parsanol::Slice)
+
+      content == other
+    end
+
+    # Type-strict equality check.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if same type and content
+    def eql?(other)
+      other.is_a?(Parsanol::Slice) && content.eql?(other.content)
+    end
+
+    # Hash for use as hash keys.
+    #
+    # @return [Integer] hash combining content and position
+    def hash
+      [content, offset].hash
+    end
+
+    # Matches regular expression against content.
+    #
+    # @param pattern [Regexp] pattern to match
+    # @return [MatchData, nil] match result
+    def match(pattern)
+      content.match(pattern)
+    end
+
+    # @return [Integer] length of slice content
+    def size
+      content.size
+    end
+
+    alias length size
+
+    # Concatenates slices assuming second continues from first's end.
+    #
+    # @param other [Slice, String] slice to append
+    # @return [Parsanol::Slice] combined slice
+    def +(other)
+      self.class.new(@byte_position, content + other.to_s, position_cache)
+    end
+
+    # Returns [line, column] tuple for this position.
+    #
+    # @return [Array<Integer, Integer>] line and column (1-indexed)
+    # @raise [ArgumentError] if no line cache available
+    def line_and_column
+      raise ArgumentError, 'Line/column info requires a line cache. Pass one during parsing.' unless position_cache
+
+      position_cache.line_and_column(@byte_position)
+    end
+
+    # String conversions ---------------------------------------------------------
+
+    def to_str
+      content.is_a?(String) ? content : content.to_s
+    end
+    alias to_s to_str
+
+    def to_slice
+      self
+    end
+
+    def to_sym
+      content.to_sym
+    end
+
+    def to_i
+      content.to_i
+    end
+
+    def to_f
+      content.to_f
+    end
+
+    # Inspection ---------------------------------------------------------
+
+    def inspect
+      "#{content.inspect}@#{offset}"
+    end
+  end
+end

data/lib/parsanol/source/line_cache.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Line position caching for efficient line/column lookups.
+# Stores line ending positions to enable O(log n) line number queries.
+#
+# Inspired by Parslet (MIT License).
+
+module Parsanol
+  class Source
+    # Caches line ending positions for quick line/column resolution.
+    # Uses binary search for efficient position lookup.
+    class LineCache
+      def initialize
+        # Array of byte offsets where each line ends
+        @breaks = []
+        @breaks.extend(IntervalLookup)
+        @max_scanned = nil
+      end
+
+      # Converts a byte offset to [line_number, column_number].
+      # Line and column numbers are 1-indexed.
+      #
+      # @param position [Integer, #bytepos] the byte offset to convert
+      # @return [Array<Integer, Integer>] [line, column] tuple
+      def line_and_column(position)
+        position = position.bytepos if position.respond_to?(:bytepos)
+
+        line_idx = @breaks.lower_bound_index(position)
+
+        if line_idx
+          # Found a line ending after this position
+          line_start = line_idx.positive? ? @breaks[line_idx - 1] : 0
+          [line_idx + 1, position - line_start + 1]
+        else
+          # Position is beyond all known line endings
+          line_start = @breaks.last || 0
+          [@breaks.size + 1, position - line_start + 1]
+        end
+      end
+
+      # Scans a string buffer for line endings and caches their positions.
+      # Avoids re-scanning already processed regions.
+      #
+      # @param start_offset [Integer] the byte offset where buffer starts
+      # @param buffer [String] the string content to scan
+      def scan_for_line_endings(start_offset, buffer)
+        return unless buffer
+
+        scanner = StringScanner.new(buffer)
+        return unless scanner.exist?(/\n/)
+
+        # Skip already-scanned content
+        scanner.pos = @max_scanned - start_offset if @max_scanned && start_offset < @max_scanned
+
+        # Record all newline positions
+        while scanner.skip_until(/\n/)
+          @max_scanned = start_offset + scanner.pos
+          @breaks << @max_scanned
+        end
+      end
+    end
+
+    # Mixin providing binary search for interval containment queries.
+    # Treats array values as interval endpoints where each interval [n-1, n]
+    # is represented by value at index n.
+    #
+    # @example
+    #   [10, 20, 30] represents intervals [0,10], (10,20], (20,30]
+    module IntervalLookup
+      # Calculates midpoint index for binary search.
+      # Uses floor to ensure integer result.
+      def midpoint_index(lo, hi)
+        lo + ((hi - lo) / 2).floor
+      end
+
+      # Finds the index of the first value greater than the bound.
+      # Returns nil if no such value exists.
+      #
+      # @param bound [Numeric] the value to search against
+      # @return [Integer, nil] index of first value > bound, or nil
+      def lower_bound_index(bound)
+        return nil if empty?
+        return nil unless last > bound
+
+        lo = 0
+        hi = size - 1
+
+        loop do
+          mid = midpoint_index(lo, hi)
+
+          if self[mid] > bound
+            hi = mid
+          else
+            lo = mid + 1
+          end
+
+          return hi if hi <= lo
+        end
+      end
+
+      # Legacy method name for backward compatibility
+      alias find_mid midpoint_index
+      alias lbound lower_bound_index
+    end
+
+    # Legacy constant name for backward compatibility
+    RangeSearch = IntervalLookup
+  end
+end

data/lib/parsanol/source.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'strscan'
+
+require 'parsanol/position'
+require 'parsanol/source/line_cache'
+require 'parsanol/pools/slice_pool'
+require 'parsanol/pools/position_pool'
+
+module Parsanol
+  # Encapsulates input source for parsing operations. Provides position tracking,
+  # character consumption, line/column calculation, and object pooling for
+  # memory efficiency.
+  #
+  # @example Creating a source
+  #   src = Parsanol::Source.new("input string")
+  #   src.matches?(/a/)  # => true if 'a' is at current position
+  #   src.consume(1)     # => Slice containing one character
+  #
+  # Inspired by source/position tracking patterns in parser implementations.
+  #
+  class Source
+    # @return [Parsanol::Pools::SlicePool] pool for Slice objects
+    attr_reader :slice_pool
+
+    # @return [Parsanol::Pools::PositionPool] pool for Position objects
+    attr_reader :position_pool
+
+    # Creates a new source wrapper around a string.
+    #
+    # @param input [#to_str] string-like object to parse
+    # @raise [ArgumentError] if input doesn't respond to to_str
+    #
+    def initialize(input)
+      raise ArgumentError, 'Source requires a string-like object (responds to to_str)' unless input.respond_to?(:to_str)
+
+      # Core scanner for input traversal
+      @scanner = StringScanner.new(input)
+      @raw_string = input.to_str
+
+      # Regex cache: maps count n to /(.|$){n}/m pattern
+      @regex_cache = Hash.new { |h, count| h[count] = Regexp.new("(.|$){#{count}}", Regexp::MULTILINE) }
+
+      # Line ending cache for position-to-line/column mapping
+      @line_data = LineCache.new
+      @line_data.scan_for_line_endings(0, input)
+
+      # Object pools for memory efficiency
+      # SlicePool: reduces Slice allocations during matching
+      @slice_pool = Parsanol::Pools::SlicePool.new(size: 5000)
+
+      # PositionPool: reduces Position allocations for error reporting
+      @position_pool = Parsanol::Pools::PositionPool.new(size: 1000)
+    end
+
+    # Checks if a pattern matches at the current input position without consuming.
+    #
+    # @param pattern [Regexp] pattern to test
+    # @return [Boolean] true if pattern matches at current position
+    #
+    def matches?(pattern)
+      @scanner.match?(pattern)
+    end
+    alias match matches?
+
+    # Consumes n characters from input and returns them as a pooled Slice.
+    #
+    # @param count [Integer] number of characters to consume
+    # @return [Parsanol::Slice] slice containing consumed characters
+    #
+    def consume(count)
+      current_pos = @scanner.pos
+      content = @scanner.scan(@regex_cache[count])
+      @slice_pool.acquire_with(current_pos, content, @line_data)
+    end
+
+    # Creates a pooled slice at a specific position.
+    # Preferred method for atoms to construct slices.
+    #
+    # @param offset [Integer] byte position in source
+    # @param content [String] slice content
+    # @return [Parsanol::Slice] pooled slice instance
+    #
+    def slice(offset, content)
+      @slice_pool.acquire_with(offset, content, @line_data)
+    end
+
+    # Returns a slice to the pool for reuse.
+    #
+    # @param sl [Parsanol::Slice] slice to release
+    #
+    def release_slice(sl)
+      @slice_pool.release(sl)
+    end
+
+    # Returns count of remaining characters in input.
+    #
+    # @return [Integer] characters left to consume
+    #
+    def chars_left
+      @scanner.rest_size
+    end
+
+    # Counts characters from current position until a target string.
+    # Returns chars_left if target is not found.
+    #
+    # @param target [String] string to search for
+    # @return [Integer] count of chars until target or remaining chars
+    #
+    def chars_until(target)
+      found = @scanner.check_until(Regexp.new(Regexp.escape(target)))
+      return chars_left unless found
+
+      found.size - target.size
+    end
+
+    # Finds the byte position of the next occurrence of a character.
+    # Does not move the scanner position.
+    #
+    # @param ch [String] character to search for
+    # @return [Integer, nil] byte position or nil if not found
+    #
+    def index_of_char(ch)
+      rel_idx = @scanner.rest.index(ch)
+      return nil unless rel_idx
+
+      @scanner.pos + rel_idx
+    end
+
+    # Returns current byte position in input.
+    #
+    # @return [Integer] current byte offset
+    # @note Encoding-aware: position is in bytes, not characters
+    #
+    def pos
+      @scanner.pos
+    end
+    alias bytepos pos
+
+    # Sets the current byte position.
+    #
+    # @param new_pos [Integer] target byte position
+    #
+    def bytepos=(new_pos)
+      @scanner.pos = new_pos
+    rescue RangeError
+      # Silently ignore out-of-range positions
+    end
+
+    # Converts a byte position to line and column numbers.
+    #
+    # @param offset [Integer, nil] byte position (defaults to current)
+    # @return [Array<Integer, Integer>] [line, column] tuple (1-indexed)
+    #
+    def line_and_column(offset = nil)
+      effective = offset || @scanner.pos
+      @line_data.line_and_column(effective)
+    end
+
+    # Creates a pooled Position object for error reporting.
+    #
+    # @param offset [Integer, nil] byte position (defaults to current)
+    # @return [Parsanol::Position] pooled position instance
+    #
+    def position(offset = nil)
+      effective = offset || @scanner.pos
+      line_and_column(effective)
+
+      # Character position approximation
+      char_pos = @raw_string.byteslice(0, effective).size
+
+      @position_pool.acquire_with(
+        string: @raw_string,
+        bytepos: effective,
+        charpos: char_pos
+      )
+    end
+  end
+end