parsanol 1.0.1-aarch64-linux

data/lib/parsanol/atoms.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Parser atoms - the building blocks for grammars.
+# Each atom type handles a specific parsing primitive or combinator.
+module Parsanol
+  module Atoms
+    # Precedence levels for pretty-printing.
+    # Higher values bind more loosely.
+    module Precedence
+      ATOM       = 1  # literals, entities
+      LOOKAHEAD  = 2  # &expr, !expr
+      REPETITION = 3  # expr*, expr+, expr?
+      SEQUENCE   = 4  # expr expr
+      CHOICE     = 5  # expr | expr
+      TOP        = 6  # outer level
+
+      # Backward-compatible aliases
+      BASE      = ATOM
+      ALTERNATE = CHOICE
+      OUTER     = TOP
+    end
+
+    # Load atom implementations
+    require 'parsanol/atoms/can_flatten'
+    require 'parsanol/atoms/context'
+    require 'parsanol/atoms/dsl'
+    require 'parsanol/atoms/base'
+    require 'parsanol/atoms/custom'
+    require 'parsanol/atoms/ignored'
+    require 'parsanol/atoms/named'
+    require 'parsanol/atoms/lookahead'
+    require 'parsanol/atoms/cut'
+    require 'parsanol/atoms/alternative'
+    require 'parsanol/atoms/sequence'
+    require 'parsanol/atoms/repetition'
+    require 'parsanol/atoms/re'
+    require 'parsanol/atoms/str'
+    require 'parsanol/atoms/entity'
+    require 'parsanol/atoms/capture'
+    require 'parsanol/atoms/dynamic'
+    require 'parsanol/atoms/scope'
+    require 'parsanol/atoms/infix'
+    # Load visitor pattern (must be after all atom classes)
+    require 'parsanol/atoms/visitor'
+  end
+end

data/lib/parsanol/buffer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # A fixed-size buffer for efficient array operations.
+  #
+  # Buffer wraps an array with a logical size separate from capacity.
+  # This allows reusing buffers without reallocating arrays, reducing GC pressure.
+  #
+  # == Usage
+  #
+  #   buffer = Buffer.new(capacity: 10)
+  #   buffer.push("a")
+  #   buffer.push("b")
+  #   buffer.size  # => 2
+  #   buffer.to_a  # => ["a", "b"]
+  #   buffer.clear!
+  #   buffer.size  # => 0 (but capacity still 10)
+  #
+  # == Size vs Capacity
+  #
+  # - Size: Number of elements logically in the buffer
+  # - Capacity: Maximum elements before reallocation
+  #
+  # Reusing buffers maintains capacity while resetting size.
+  #
+  class Buffer
+    include Resettable
+
+    # @return [Integer] Logical size (number of elements)
+    attr_reader :size
+
+    # @return [Integer] Maximum capacity before growth
+    attr_reader :capacity
+
+    # @return [Array] Underlying array storage
+    attr_reader :storage
+
+    # Initialize a new buffer with specified capacity.
+    #
+    # @param capacity [Integer] Initial capacity (default: 10)
+    #
+    def initialize(capacity: 10)
+      @capacity = capacity
+      @storage = Array.new(capacity)
+      @size = 0
+    end
+
+    # Add an element to the buffer.
+    #
+    # Grows buffer if needed, but this should be rare with proper size classes.
+    #
+    # @param element [Object] Element to add
+    # @return [self] For method chaining
+    #
+    def push(element)
+      grow! if @size >= @capacity
+      @storage[@size] = element
+      @size += 1
+      self
+    end
+
+    alias << push
+
+    # Get element at index.
+    #
+    # @param index [Integer] Zero-based index
+    # @return [Object] Element at index, or nil if out of bounds
+    #
+    def [](index)
+      return nil if index >= @size
+
+      @storage[index]
+    end
+
+    # Set element at index.
+    #
+    # @param index [Integer] Zero-based index
+    # @param value [Object] Value to set
+    #
+    def []=(index, value)
+      @storage[index] = value if index < @size
+    end
+
+    # Convert buffer to array (creates new array slice of logical size).
+    #
+    # @return [Array] Array containing elements [0...size]
+    #
+    def to_a
+      @storage[0...@size]
+    end
+
+    # Clear the buffer (reset logical size, keep capacity).
+    #
+    # @return [self] For method chaining
+    #
+    def clear!
+      # Clear references for GC (keep capacity)
+      @size.upto(@capacity - 1) { |i| @storage[i] = nil }
+      @size = 0
+      self
+    end
+
+    # Check if buffer is empty.
+    #
+    # @return [Boolean] true if size is zero
+    #
+    def empty?
+      @size.zero?
+    end
+
+    # Reset protocol for ObjectPool compatibility.
+    # Delegates to clear! for buffer cleanup.
+    #
+    # @return [self] For method chaining
+    #
+    def reset!
+      clear!
+    end
+
+    private
+
+    # Grow buffer capacity (double it).
+    # Should be rare with proper size class selection.
+    #
+    def grow!
+      new_capacity = @capacity * 2
+      new_storage = Array.new(new_capacity)
+      @storage.each_with_index { |elem, i| new_storage[i] = elem }
+      @storage = new_storage
+      @capacity = new_capacity
+    end
+  end
+end

data/lib/parsanol/builder_callbacks.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Module for streaming builder callbacks.
+  # Include this module in your builder class to receive callbacks
+  # during single-pass parsing with the streaming builder API.
+  #
+  # The streaming builder API allows maximum performance by eliminating
+  # intermediate AST construction. Instead, callbacks are invoked as
+  # parsing progresses, allowing you to construct custom output directly.
+  #
+  # @example Basic string collector
+  #   class StringCollector
+  #     include Parsanol::BuilderCallbacks
+  #
+  #     def initialize
+  #       @strings = []
+  #     end
+  #
+  #     def on_string(value, offset, length)
+  #       @strings << value
+  #     end
+  #
+  #     def finish
+  #       @strings
+  #     end
+  #   end
+  #
+  #   grammar = Parsanol::Native.serialize_grammar(parser.root)
+  #   builder = StringCollector.new
+  #   result = Parsanol::Native.parse_with_builder(grammar, input, builder)
+  #   # result: ["hello", "world"]
+  #
+  # @example Building a typed AST
+  #   class AstBuilder
+  #     include Parsanol::BuilderCallbacks
+  #
+  #     def initialize
+  #       @stack = []
+  #       @current_hash = nil
+  #       @current_key = nil
+  #     end
+  #
+  #     def on_hash_start(size = nil)
+  #       @stack.push(@current_hash) if @current_hash
+  #       @current_hash = {}
+  #     end
+  #
+  #     def on_hash_end(size)
+  #       finished = @current_hash
+  #       @current_hash = @stack.pop
+  #       if @current_hash && @current_key
+  #         @current_hash[@current_key] = finished
+  #         @current_key = nil
+  #       end
+  #       finished
+  #     end
+  #
+  #     def on_hash_key(key)
+  #       @current_key = key
+  #     end
+  #
+  #     def on_string(value, offset, length)
+  #       if @current_hash && @current_key
+  #         @current_hash[@current_key] = value
+  #         @current_key = nil
+  #       end
+  #     end
+  #
+  #     def finish
+  #       @current_hash
+  #     end
+  #   end
+  #
+  module BuilderCallbacks
+    # Called when parsing starts.
+    #
+    # @param input [String] The input being parsed
+    # @return [void]
+    def on_start(input); end
+
+    # Called when parsing succeeds.
+    #
+    # @return [void]
+    def on_success; end
+
+    # Called when parsing fails.
+    #
+    # @param message [String] The error message
+    # @return [void]
+    def on_error(message); end
+
+    # Called when a string value is matched.
+    #
+    # @param value [String] The matched string value
+    # @param offset [Integer] Byte offset in the original input
+    # @param length [Integer] Length of the matched string in bytes
+    # @return [void]
+    def on_string(value, offset, length); end
+
+    # Called when an integer value is matched.
+    #
+    # @param value [Integer] The matched integer value
+    # @return [void]
+    def on_int(value); end
+
+    # Called when a float value is matched.
+    #
+    # @param value [Float] The matched float value
+    # @return [void]
+    def on_float(value); end
+
+    # Called when a boolean value is matched.
+    #
+    # @param value [Boolean] The matched boolean value
+    # @return [void]
+    def on_bool(value); end
+
+    # Called when a nil/null value is matched.
+    #
+    # @return [void]
+    def on_nil; end
+
+    # Called when starting to parse a hash/object.
+    # Use this to initialize state for collecting key-value pairs.
+    #
+    # @param size [Integer, nil] Expected number of entries (may be nil)
+    # @return [void]
+    def on_hash_start(size = nil); end
+
+    # Called when finishing parsing a hash/object.
+    #
+    # @param size [Integer] Actual number of entries
+    # @return [void]
+    def on_hash_end(size); end
+
+    # Called when a hash key is encountered.
+    # The next value callback(s) will provide the value for this key.
+    #
+    # @param key [String] The hash key name
+    # @return [void]
+    def on_hash_key(key); end
+
+    # Called when a hash value is about to be parsed.
+    # Called after on_hash_key for the corresponding value.
+    #
+    # @param key [String] The hash key name
+    # @return [void]
+    def on_hash_value(key); end
+
+    # Called when starting to parse an array.
+    # Use this to initialize state for collecting array elements.
+    #
+    # @param size [Integer, nil] Expected number of elements (may be nil)
+    # @return [void]
+    def on_array_start(size = nil); end
+
+    # Called when an array element is about to be parsed.
+    #
+    # @param index [Integer] The index of the element
+    # @return [void]
+    def on_array_element(index); end
+
+    # Called when finishing parsing an array.
+    #
+    # @param size [Integer] Actual number of elements
+    # @return [void]
+    def on_array_end(size); end
+
+    # Called when starting to parse a named rule.
+    #
+    # @param name [String] The rule name
+    # @return [void]
+    def on_named_start(name); end
+
+    # Called when finishing parsing a named rule.
+    #
+    # @param name [String] The rule name
+    # @return [void]
+    def on_named_end(name); end
+
+    # Called when parsing is complete.
+    # Override this method to return your final constructed result.
+    #
+    # @return [Object] The final result of the builder
+    def finish; end
+  end
+
+  # Built-in builders for common use cases
+  module Builders
+    # Debug builder that collects all events as strings.
+    # Useful for understanding the parsing flow.
+    class DebugBuilder
+      include BuilderCallbacks
+
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def on_start(input)
+        @events << "start: #{input.inspect}"
+      end
+
+      def on_success
+        @events << 'success'
+      end
+
+      def on_error(message)
+        @events << "error: #{message}"
+      end
+
+      def on_string(value, offset, length)
+        @events << "string: #{value.inspect} @ #{offset}(#{length})"
+      end
+
+      def on_int(value)
+        @events << "int: #{value}"
+      end
+
+      def on_float(value)
+        @events << "float: #{value}"
+      end
+
+      def on_bool(value)
+        @events << "bool: #{value}"
+      end
+
+      def on_nil
+        @events << 'nil'
+      end
+
+      def on_hash_start(size = nil)
+        @events << "hash_start(#{size.inspect})"
+      end
+
+      def on_hash_end(size)
+        @events << "hash_end(#{size})"
+      end
+
+      def on_hash_key(key)
+        @events << "hash_key: #{key.inspect}"
+      end
+
+      def on_hash_value(key)
+        @events << "hash_value: #{key.inspect}"
+      end
+
+      def on_array_start(size = nil)
+        @events << "array_start(#{size.inspect})"
+      end
+
+      def on_array_element(index)
+        @events << "array_element[#{index}]"
+      end
+
+      def on_array_end(size)
+        @events << "array_end(#{size})"
+      end
+
+      def on_named_start(name)
+        @events << "named_start: #{name}"
+      end
+
+      def on_named_end(name)
+        @events << "named_end: #{name}"
+      end
+
+      def finish
+        @events.join("\n")
+      end
+    end
+
+    # Builder that collects all string values.
+    class StringCollector
+      include BuilderCallbacks
+
+      attr_reader :strings
+
+      def initialize
+        @strings = []
+      end
+
+      def on_start(input); end
+
+      def on_success; end
+
+      def on_error(message); end
+
+      def on_string(value, _offset, _length)
+        @strings << value
+      end
+
+      def finish
+        @strings
+      end
+    end
+
+    # Builder that counts nodes by type.
+    class NodeCounter
+      include BuilderCallbacks
+
+      attr_reader :counts
+
+      def initialize
+        @counts = Hash.new(0)
+      end
+
+      def on_start(input); end
+
+      def on_success; end
+
+      def on_error(message); end
+
+      def on_string(_value, _offset, _length)
+        @counts[:string] += 1
+      end
+
+      def on_int(_value)
+        @counts[:int] += 1
+      end
+
+      def on_float(_value)
+        @counts[:float] += 1
+      end
+
+      def on_bool(_value)
+        @counts[:bool] += 1
+      end
+
+      def on_nil
+        @counts[:nil] += 1
+      end
+
+      def on_hash_start(_size = nil)
+        @counts[:hash] += 1
+      end
+
+      def on_array_start(_size = nil)
+        @counts[:array] += 1
+      end
+
+      def on_named_start(_name)
+        @counts[:named] += 1
+      end
+
+      def finish
+        @counts
+      end
+    end
+  end
+end

data/lib/parsanol/cause.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Represents a cause why a parse did fail. Stores information about
+# parse failure including:
+# - message: Human-readable error description
+# - source: The source object being parsed
+# - position: Byte position where error occurred
+# - children: Nested causes (for deeper context)
+#
+# @example
+#   cause = Parsanol::Cause.new(
+#     "Expected at least one",
+#     source,
+#     5
+#   )
+#   cause.children  # => []
+#   cause.to_s  # => "Expected at least one"
+#
+module Parsanol
+  class Cause
+    # @return [Array<String>] Error message parts
+    attr_reader :message
+
+    # @return [Parsanol::Source] Source being parsed
+    attr_reader :source
+
+    # @return [Integer] Byte position where error occurred
+    attr_reader :position
+
+    # Alias for position (API compatibility)
+    alias pos position
+
+    # @return [Array<Cause>] Child causes
+    attr_reader :children
+
+    # Creates a new cause for parse failure
+    #
+    # @param message [String, Array<String>] Error description
+    # @param source [Parsanol::Source] Source being parsed
+    # @param position [Integer] Byte position where error occurred
+    # @param children [Array<Cause>] Nested causes (optional)
+    def initialize(message, source, position, children = [])
+      @message = Array(message)
+      @source = source
+      @position = position
+      @children = children.nil? ? [] : children
+      @parsing_label = nil
+    end
+
+    # Factory method for creating a cause
+    #
+    # @param source [Parsanol::Source] source being parsed
+    # @param position [Integer] Byte position where error occurred
+    # @param message [String, Array<String>] Error description
+    # @param children [Array<Cause>] Nested causes
+    # @return [Cause] New cause instance
+    def self.format(source, position, message, children = [])
+      new(message, source, position, children)
+    end
+
+    # Associates a label with this cause for parsing context
+    #
+    # @param label [String] Description of what was being parsed
+    # @return [void]
+    def set_label(label)
+      @parsing_label = " while parsing #{label}"
+      @children.each { |c| c.set_label(label) }
+    end
+
+    # Formats this cause as a human-readable string
+    #
+    # @return [String] Formatted error message
+    def to_s
+      line_num, col_num = @source.line_and_column(@position)
+
+      formatted_msg = @message.map do |msg|
+        msg.respond_to?(:to_slice) ? msg.content.inspect : msg.to_s
+      end.join
+
+      "#{formatted_msg} at line #{line_num} char #{col_num}#{@parsing_label}."
+    end
+
+    # Generates a tree-style visualization of error causes
+    #
+    # @return [String] ASCII tree representation
+    def ascii_tree
+      output = StringIO.new
+      build_tree_recursive(self, output, [true])
+      output.string
+    end
+
+    # Raises a ParseFailed exception with this cause's information
+    #
+    # @raise [Parsanol::ParseFailed] Always
+    def raise
+      exc = Parsanol::ParseFailed.new(to_s, self)
+      Kernel.raise exc
+    end
+
+    private
+
+    def build_tree_recursive(node, stream, prefix_flags)
+      render_prefix(stream, prefix_flags)
+      stream.puts node.to_s
+
+      node.children.each do |child|
+        is_last_child = (node.children.last == child)
+        build_tree_recursive(child, stream, prefix_flags + [is_last_child])
+      end
+    end
+
+    def render_prefix(stream, prefix_flags)
+      return if prefix_flags.size < 2
+
+      prefix_flags[1..-2].each do |is_last|
+        stream.print is_last ? '   ' : '|  '
+      end
+
+      stream.print prefix_flags.last ? '`- ' : '|- '
+    end
+  end
+end

data/lib/parsanol/context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Execution context for tree transformation rules.
+# Provides a clean interface for accessing bound variables within transformation blocks.
+#
+# @example
+#   ctx = Parsanol::Context.new(name: 'Alice', value: 42)
+#   ctx.instance_eval { name }  # => 'Alice'
+#   ctx.instance_eval { @value }  # => 42
+#
+# Inspired by Parslet (MIT License).
+module Parsanol
+  class Context
+    include Parsanol
+
+    # Creates a new context with the given bindings.
+    # Each binding becomes accessible as both a method and an instance variable.
+    #
+    # @param bindings [Hash] variable name => value pairs
+    def initialize(bindings)
+      bindings.each_pair do |key, val|
+        # Define accessor method on singleton class
+        define_singleton_method(key) { val }
+        # Also set as instance variable for @-style access
+        instance_variable_set("@#{key}", val)
+      end
+    end
+
+    private
+
+    # Defines a method on the object's singleton class.
+    #
+    # @param name [Symbol, String] method name
+    # @yield block to execute when method is called
+    def define_singleton_method(name, &body)
+      singleton_class.define_method(name, &body)
+    end
+  end
+end