parsanol 1.0.1-aarch64-linux

data/lib/parsanol/wasm_parser.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # WASM-based parser for Opal environments
+  #
+  # This class provides a bridge between Opal (Ruby compiled to JavaScript)
+  # and the WASM parser. It uses the Parslet WASM module.
+  #
+  # @example In Opal environment
+  #   # First, ensure WASM is loaded (in your HTML/JS)
+  #   # <script src="parslet_wasm.js"></script>
+  #   # <script>
+  #   #   ParsletWasm.init().then(() => console.log('ready'));
+  #   # </script>
+  #
+  #   # Then in Ruby/Opal:
+  #   grammar_json = parser.to_json
+  #   wasm_parser = Parsanol::WasmParser.new(grammar_json)
+  #   result = wasm_parser.parse(input)
+  #
+  class WasmParser
+    # Tags for flat array format
+    TAG_NIL         = 0x00
+    TAG_BOOL        = 0x01
+    TAG_INT         = 0x02
+    TAG_FLOAT       = 0x03
+    TAG_STRING      = 0x04
+    TAG_ARRAY_START = 0x05
+    TAG_ARRAY_END   = 0x06
+    TAG_HASH_START  = 0x07
+    TAG_HASH_END    = 0x08
+    TAG_HASH_KEY    = 0x09
+
+    # @return [String] The grammar JSON
+    attr_reader :grammar_json
+
+    # Create a new WASM parser
+    #
+    # @param grammar_json [String, Hash] Grammar JSON string or hash
+    # @raise [RuntimeError] If WASM is not initialized
+    #
+    def initialize(grammar_json)
+      @grammar_json = grammar_json.is_a?(Hash) ? grammar_json.to_json : grammar_json
+      @parser = nil
+    end
+
+    # Parse input string and return AST
+    #
+    # @param input [String] Input string to parse
+    # @return [Hash, Array, String, nil] Parsed AST
+    # @raise [RuntimeError] If parsing fails
+    #
+    def parse(input)
+      ensure_initialized
+      result = `#{@parser}.parse(#{input})`
+      convert_js_to_ruby(result)
+    end
+
+    # Parse input and return flat array (more efficient for large results)
+    #
+    # @param input [String] Input string to parse
+    # @return [Array] Flat array with tagged values
+    # @raise [RuntimeError] If parsing fails
+    #
+    def parse_flat(input)
+      ensure_initialized
+      flat = `#{@parser}.parseFlat(#{input})`
+      decode_flat(flat, input)
+    end
+
+    # Parse input and return JSON string
+    #
+    # @param input [String] Input string to parse
+    # @return [String] JSON string of parsed AST
+    # @raise [RuntimeError] If parsing fails
+    #
+    def parse_json(input)
+      ensure_initialized
+      `#{@parser}.parseJson(#{input})`
+    end
+
+    # Check if WASM is available and initialized
+    #
+    # @return [Boolean]
+    #
+    def self.available?
+      `
+        if (typeof ParsletWasm === 'undefined') {
+          return false;
+        }
+        return ParsletWasm.isInitialized ? ParsletWasm.isInitialized() : false;
+      `
+    end
+
+    # Initialize WASM module (async)
+    #
+    # @return [Promise] Promise that resolves when WASM is ready
+    #
+    def self.init
+      `
+        if (typeof ParsletWasm !== 'undefined' && ParsletWasm.initParslet) {
+          return ParsletWasm.initParslet();
+        }
+        return Promise.reject(new Error('ParsletWasm not loaded'));
+      `
+    end
+
+    private
+
+    def ensure_initialized
+      return if @parser
+
+      `
+        if (typeof ParsletWasm === 'undefined') {
+          throw new Error('ParsletWasm not loaded. Include parslet.js and parsanol_native_bg.wasm');
+        }
+        if (!ParsletWasm.isInitialized || !ParsletWasm.isInitialized()) {
+          throw new Error('WASM not initialized. Call Parsanol::WasmParser.init first');
+        }
+        #{@parser} = new ParsletWasm.ParsletParser(#{@grammar_json});
+      `
+    end
+
+    # Convert JavaScript result to Ruby
+    def convert_js_to_ruby(_js_obj)
+      %x{
+        if (js_obj === null || js_obj === undefined) {
+          return nil;
+        }
+        if (typeof js_obj === 'boolean') {
+          return js_obj;
+        }
+        if (typeof js_obj === 'number') {
+          return js_obj;
+        }
+        if (typeof js_obj === 'string') {
+          return js_obj;
+        }
+        if (Array.isArray(js_obj)) {
+          return js_obj.map(function(item) {
+            return #{convert_js_to_ruby(`item`)};
+          });
+        }
+        if (typeof js_obj === 'object') {
+          var hash = {};
+          Object.keys(js_obj).forEach(function(key) {
+            hash[key] = #{convert_js_to_ruby(`js_obj[key]`)};
+          });
+          return hash;
+        }
+        return nil;
+      }
+    end
+
+    # Decode flat array format to Ruby objects
+    def decode_flat(flat, input)
+      stack = []
+      i = 0
+      length = `#{flat}.length`
+
+      while i < length
+        tag = `#{flat}[#{i}]`
+
+        case tag
+        when TAG_NIL
+          stack << nil
+          i += 1
+        when TAG_BOOL
+          stack << (`#{flat}[#{i + 1}]` != 0)
+          i += 2
+        when TAG_INT
+          stack << `#{flat}[#{i + 1}]`
+          i += 2
+        when TAG_FLOAT
+          bits = `#{flat}[#{i + 1}]`
+          float = `new Float64Array(new BigUint64Array([#{bits}]).buffer)[0]`
+          stack << float
+          i += 2
+        when TAG_STRING
+          offset = `#{flat}[#{i + 1}]`
+          len = `#{flat}[#{i + 2}]`
+          stack << input.byteslice(offset, len)
+          i += 3
+        when TAG_ARRAY_START
+          stack << :array_marker
+          i += 1
+        when TAG_ARRAY_END
+          items = []
+          items.unshift(stack.pop) while stack.last != :array_marker
+          stack.pop # Remove marker
+          stack << items
+          i += 1
+        when TAG_HASH_START
+          stack << :hash_marker
+          i += 1
+        when TAG_HASH_END
+          pairs = []
+          while stack.last != :hash_marker
+            value = stack.pop
+            key = stack.pop
+            pairs.unshift([key, value])
+          end
+          stack.pop # Remove marker
+          stack << pairs.to_h
+          i += 1
+        when TAG_HASH_KEY
+          len = `#{flat}[#{i + 1}]`
+          i += 3 # Skip tag, len, and placeholder
+          # Read key bytes
+          key_bytes = []
+          chunks = (len + 7) / 8
+          chunks.times do |j|
+            chunk = `#{flat}[#{i + j}]`
+            8.times do |k|
+              break if key_bytes.length >= len
+
+              key_bytes << ((chunk >> (k * 8)) & 0xff)
+            end
+          end
+          i += chunks
+          key = key_bytes.pack('C*').force_encoding('UTF-8')
+          stack << key
+        else
+          raise "Unknown tag: #{tag} at index #{i}"
+        end
+      end
+
+      stack.first
+    end
+  end
+
+  # Factory method to create appropriate parser
+  #
+  # @param grammar_json [String, Hash] Grammar JSON
+  # @return [WasmParser, Object] Appropriate parser for current environment
+  #
+  def self.create_wasm_parser(grammar_json)
+    WasmParser.new(grammar_json)
+  end
+end

data/lib/parsanol.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require 'set'
+
+# Parsanol - A high-performance PEG parser construction library for Ruby.
+#
+# Typical usage:
+#
+#   require 'parsanol'
+#
+#   class MyParser < Parsanol::Parser
+#     rule(:a) { str('a').repeat }
+#     root(:a)
+#   end
+#
+#   result = MyParser.new.parse('aaaa')   # => 'aaaa'@0
+#
+# Parsanol provides a declarative DSL for constructing parsers using PEG
+# (Parsing Expression Grammar) semantics. The library is designed as a
+# high-performance, feature-rich alternative to Parslet.
+#
+# == Two-Stage Parsing
+#
+# Parsing is typically done in two stages:
+#
+# 1. Parse the input string to produce an intermediate tree
+# 2. Transform the tree into an application-specific AST
+#
+# This separation allows grammar changes without affecting downstream code.
+#
+# == Error Handling
+#
+# Failed parses raise {Parsanol::ParseFailed} with detailed error information:
+#
+#   begin
+#     parser.parse(invalid_input)
+#   rescue Parsanol::ParseFailed => e
+#     puts e.parse_failure_cause.ascii_tree
+#   end
+#
+# Inspired by Parslet (MIT License).
+
+module Parsanol
+  # Hook to extend including classes with ClassMethods.
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # Exception raised when parsing fails. Contains detailed error information
+  # in the #parse_failure_cause attribute.
+  class ParseFailed < StandardError
+    def initialize(message, cause = nil)
+      super(message)
+      @parse_failure_cause = cause
+    end
+
+    # Detailed cause of the parse failure.
+    # @return [Parsanol::Cause]
+    attr_reader :parse_failure_cause
+  end
+
+  # Class methods added to classes that include Parsanol.
+  module ClassMethods
+    # Enable automatic rule optimization for all rules in this parser.
+    # Optimizations include quantifier simplification, sequence flattening,
+    # choice reordering, and lookahead simplification.
+    #
+    # NOTE: Optimizations are DISABLED BY DEFAULT as of v3.1.0.
+    # Use this method to opt-in for complex grammars.
+    def optimize_rules!(enable = true)
+      @optimize_rules = enable
+    end
+
+    # Disable automatic rule optimization.
+    def disable_optimization!
+      @optimize_rules = false
+    end
+
+    # Check if rule optimization is enabled.
+    # @return [Boolean]
+    def optimize_rules?
+      @optimize_rules = false if @optimize_rules.nil?
+      @optimize_rules
+    end
+
+    # Define a named grammar rule. Creates a method that returns an Entity atom.
+    # Rules are memoized for efficiency.
+    #
+    # @param name [Symbol] the rule name
+    # @param opts [Hash] options (:label for custom labeling)
+    # @yield block that returns the rule's parser atom
+    def rule(name, opts = {}, &definition)
+      undef_method name if method_defined? name
+      define_method(name) do
+        @rule_cache ||= {}
+        return @rule_cache[name] if @rule_cache.key?(name)
+
+        wrapper = proc {
+          atom = instance_eval(&definition)
+
+          if self.class.optimize_rules?
+            atom = Parsanol::Optimizer.simplify_quantifiers(atom)
+            atom = Parsanol::Optimizer.simplify_sequences(atom)
+            atom = Parsanol::Optimizer.simplify_choices(atom)
+            atom = Parsanol::Optimizer.simplify_lookaheads(atom)
+          end
+
+          atom
+        }
+
+        @rule_cache[name] = Atoms::Entity.new(name, opts[:label], &wrapper)
+      end
+    end
+  end
+
+  # Helper class for bracket notation character class matching.
+  # @api private
+  class CharacterClassBuilder
+    def [](chars)
+      Atoms::Re.new("[#{chars}]")
+    end
+  end
+
+  # Creates a character class matcher. Supports both method and bracket forms.
+  #
+  # @overload match(pattern)
+  #   @param pattern [String] regex character class
+  # @overload match[]
+  #   @return [CharacterClassBuilder] builder for bracket notation
+  # @return [Parsanol::Atoms::Re] regex atom
+  def match(pattern = nil)
+    return CharacterClassBuilder.new unless pattern
+
+    Atoms::Re.new(pattern)
+  end
+  module_function :match
+
+  # Creates a literal string matcher.
+  #
+  # @param literal [String] the string to match
+  # @return [Parsanol::Atoms::Str] string atom
+  def str(literal)
+    Atoms::Str.new(literal)
+  end
+  module_function :str
+
+  # Creates a matcher for any single character.
+  #
+  # @return [Parsanol::Atoms::Re] regex atom matching '.'
+  def any
+    Atoms::Re.new('.')
+  end
+  module_function :any
+
+  # Creates a new variable scope for captures. Inner captures shadow outer
+  # ones with the same name during the block's execution.
+  #
+  # @yield block containing scoped parsing
+  # @return [Parsanol::Atoms::Scope] scope atom
+  def scope(&block)
+    Atoms::Scope.new(block)
+  end
+  module_function :scope
+
+  # Creates a dynamic parser that is evaluated at parse time.
+  # Useful for context-dependent parsing. Use sparingly due to performance.
+  #
+  # @yield block returning a parser atom or parse result
+  # @return [Parsanol::Atoms::Dynamic] dynamic atom
+  def dynamic(&block)
+    Atoms::Dynamic.new(block)
+  end
+  module_function :dynamic
+
+  # Creates an infix expression parser with operator precedence.
+  # Operators are specified as [atom, precedence, associativity] tuples.
+  #
+  # @param operand [Parsanol::Atoms::Base] parser for operands
+  # @param operators [Array<Array>] operator definitions
+  # @yield optional block to customize result tree structure
+  # @return [Parsanol::Atoms::Infix] infix parser
+  def infix_expression(operand, *operators, &combiner)
+    Atoms::Infix.new(operand, operators, &combiner)
+  end
+  module_function :infix_expression
+
+  # Creates a pattern binding for sequence matching in transforms.
+  # Only matches array values, not single elements.
+  #
+  # @param name [Symbol] binding variable name
+  # @return [Parsanol::Pattern::SequenceBind] sequence pattern
+  def sequence(name)
+    Pattern::SequenceBind.new(name)
+  end
+  module_function :sequence
+
+  # Creates a pattern binding for simple (leaf) value matching.
+  # Matches anything that is not a Hash or Array.
+  #
+  # @param name [Symbol] binding variable name
+  # @return [Parsanol::Pattern::SimpleBind] simple pattern
+  def simple(name)
+    Pattern::SimpleBind.new(name)
+  end
+  module_function :simple
+
+  # Creates a pattern binding that matches any subtree.
+  # This is the most permissive pattern type.
+  #
+  # @param name [Symbol] binding variable name
+  # @return [Parsanol::Pattern::SubtreeBind] subtree pattern
+  def subtree(name)
+    Pattern::SubtreeBind.new(name)
+  end
+  module_function :subtree
+
+  # Parses a treetop-style expression string and returns the corresponding atom.
+  #
+  # This is a convenience method for defining parsers using treetop syntax.
+  # The expression parser is pure Ruby (not Rust-accelerated) since it runs only
+  # at grammar definition time. The resulting atoms can be used with native parsing.
+  #
+  # @note Whitespace is required before operators: 'a' ? not 'a'?
+  #
+  # @example Basic usage
+  #   exp("'a' 'b' ?")  # => str('a') >> str('b').maybe
+  #
+  # @example With Rust-accelerated parsing
+  #   atom = exp("'a' +")
+  #   Native.parse_with_grammar(atom, 'aaa')  # Uses Rust extension
+  #
+  # @param str [String] a treetop expression string
+  # @return [Parsanol::Atoms::Base] the corresponding parser atom
+  # @see Parsanol::Expression for full syntax documentation
+  def exp(str)
+    Expression.new(str).to_parslet
+  end
+  module_function :exp
+
+  autoload :Expression, 'parsanol/expression'
+end
+
+require 'parsanol/version'
+require 'parsanol/resettable'
+require 'parsanol/result'
+require 'parsanol/slice'
+require 'parsanol/string_view'
+require 'parsanol/rope'
+require 'parsanol/pool'
+require 'parsanol/pools/slice_pool'
+require 'parsanol/pools/array_pool'
+require 'parsanol/pools/position_pool'
+require 'parsanol/buffer'
+require 'parsanol/pools/buffer_pool'
+require 'parsanol/lazy_result'
+require 'parsanol/result_builder'
+require 'parsanol/first_set'
+require 'parsanol/cause'
+require 'parsanol/source'
+require 'parsanol/atoms'
+require 'parsanol/pattern'
+require 'parsanol/pattern/binding'
+require 'parsanol/transform'
+require 'parsanol/parser'
+require 'parsanol/error_reporter'
+require 'parsanol/scope'
+require 'parsanol/optimizer'
+require 'parsanol/options'
+require 'parsanol/native'
+
+# New features (require native extension for full functionality)
+require 'parsanol/source_location'
+require 'parsanol/grammar_builder'
+require 'parsanol/streaming_parser'
+require 'parsanol/incremental_parser'
+require 'parsanol/builder_callbacks'
+require 'parsanol/parallel'
+
+# Add GrammarBuilder DSL to Parsanol module
+Parsanol.extend(Parsanol::GrammarBuilderDSL)

data/parsanol-ruby.gemspec

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'lib/parsanol/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'parsanol'
+  spec.version = Parsanol::VERSION
+  spec.platform = Gem::Platform::RUBY
+
+  spec.authors = ['Ribose Inc.']
+  spec.email = ['open.source@ribose.com']
+
+  spec.summary = 'Parser construction library with great error reporting in Ruby.'
+  spec.description = 'A small Ruby library for constructing parsers in the PEG (Parsing Expression Grammar) fashion. ' \
+                     'Parsanol provides Parslet-compatible API with additional features including ' \
+                     'static frozen parsers and dynamic parsers, with optional Rust native extension for improved performance.'
+  spec.homepage = 'https://github.com/parsanol/parsanol-ruby'
+  spec.license = 'MIT'
+
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/parsanol/parsanol-ruby/issues',
+    'changelog_uri' => 'https://github.com/parsanol/parsanol-ruby/blob/main/HISTORY.txt',
+    'documentation_uri' => 'https://parsanol.github.io/parsanol-ruby/',
+    'homepage_uri' => 'https://github.com/parsanol/parsanol-ruby',
+    'source_code_uri' => 'https://github.com/parsanol/parsanol-ruby',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  # Rust extension
+  spec.extensions = ['ext/parsanol_native/extconf.rb']
+
+  spec.files = Dir.glob('{lib,ext}/**/*') + %w[
+    HISTORY.txt
+    LICENSE
+    Rakefile
+    README.adoc
+    parsanol-ruby.gemspec
+    Cargo.toml
+    Cargo.lock
+  ]
+  spec.files.reject! { |f| File.directory?(f) }
+  spec.files.reject! { |f| f =~ /\.(dll|so|dylib|lib|bundle)\Z/ }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.2.0'
+
+  # Required for Rust extension
+  spec.add_dependency 'rb_sys', '~> 0.9.39'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rake-compiler', '~> 1.2.0'
+  spec.add_development_dependency 'rdoc', '~> 6.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+
+  # For code style checking
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+
+  # For Parslet compatibility verification
+  spec.add_development_dependency 'parslet', '~> 2.0.0'
+
+  # For benchmarking
+  spec.add_development_dependency 'benchmark-ips', '~> 2.0'
+
+  # For type checking
+  spec.add_development_dependency 'rbs', '~> 3.0'
+  spec.add_development_dependency 'steep', '~> 1.0'
+end