plurimath-parslet 3.0.0

data/README.adoc

@@ -0,0 +1,454 @@
+= Plurimath Parslet
+
+This is a fork of the original Parslet gem, which is a parser library for Ruby.
+
+This differs from the original Parslet gem, such that it is Opal (JS based Ruby)
+compatible.
+
+== Introduction
+
+Parslet makes developing complex parsers easy. It does so by:
+
+* providing the best error reporting possible
+* not generating reams of code for you to debug
+
+Parslet takes the long way around to make your job easier. It allows for
+incremental language construction. Often, you start out small, implementing
+the atoms of your language first; _parslet_ takes pride in making this
+possible.
+
+Eager to try this out? Please see the associated web site:
+https://kschiess.github.io/parslet/
+
+== Synopsis
+
+[source,ruby]
+----
+require 'parslet'
+include Parslet
+
+# parslet parses strings
+str('foo').
+  parse('foo') # => "foo"@0
+
+# it matches character sets
+match['abc'].parse('a') # => "a"@0
+match['abc'].parse('b') # => "b"@0
+match['abc'].parse('c') # => "c"@0
+
+# and it annotates its output
+str('foo').as(:important_bit).
+  parse('foo') # => {:important_bit=>"foo"@0}
+
+# you can construct parsers with just a few lines
+quote = str('"')
+simple_string = quote >> (quote.absent? >> any).repeat >> quote
+
+simple_string.
+  parse('"Simple Simple Simple"') # => "\"Simple Simple Simple\""@0
+
+# or by making a fuss about it
+class Smalltalk < Parslet::Parser
+  root :smalltalk
+
+  rule(:smalltalk) { statements }
+  rule(:statements) {
+    # insert smalltalk parser here (outside of the scope of this readme)
+  }
+end
+
+# and then
+Smalltalk.new.parse('smalltalk')
+----
+
+== Features
+
+* Tools for every part of the parser chain
+* Transformers generate Abstract Syntax Trees
+* Accelerators transform parsers, making them quite a bit faster
+* Pluggable error reporters
+* Graphviz export for your parser
+* Rspec testing support rig
+* Simply Ruby, composable and hackable
+
+== Compatibility
+
+This library is intended to work with Ruby variants >= 2.7. It has been tested on:
+
+* MRI Ruby 2.7+
+* JRuby
+* Opal (works as Ruby 3.2, with the limitation of `StringScanner#charpos` not being
+  available, which is used in some examples)
+
+Please report as a bug if you encounter issues.
+
+== Status
+
+Production worthy.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'plurimath-parslet'
+----
+
+And then execute:
+
+[source,bash]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source,bash]
+----
+$ gem install plurimath-parslet
+----
+
+== Usage
+
+[source,ruby]
+----
+require 'parslet'
+----
+
+The gem maintains the original `parslet` namespace for compatibility.
+
+== Examples
+
+The `examples/` directory contains 25 interactive examples that demonstrate various parsing scenarios and techniques. These examples are designed to help you learn parslet by showing real-world parsing problems and their solutions.
+
+=== How to run examples
+
+Each example can be run directly from the command line:
+
+[source,bash]
+----
+$ ruby examples/run_boolean_algebra.rb
+$ ruby examples/run_json.rb
+$ ruby examples/run_calc.rb
+----
+
+=== Available examples
+
+[cols="1,3,2", options="header"]
+|===
+| Example | Description | Key Features
+
+| `run_boolean_algebra.rb`
+| Boolean expression parser with operator precedence
+| AND/OR operators, parentheses, DNF transformation
+
+| `run_calc.rb`
+| Basic calculator with arithmetic operations
+| Operator precedence, expression evaluation
+
+| `run_capture.rb`
+| Named capture groups and result extraction
+| Capture syntax, result processing
+
+| `run_comments.rb`
+| Comment parsing (single-line and multi-line)
+| Comment syntax, nested structures
+
+| `run_deepest_errors.rb`
+| Advanced error reporting and debugging
+| Error handling, parse failure analysis
+
+| `run_documentation.rb`
+| Markdown-style documentation parser
+| Headers, lists, formatting, code blocks
+
+| `run_email_parser.rb`
+| Email address validation and parsing
+| Email format validation, domain parsing
+
+| `run_empty.rb`
+| Empty rule behavior and edge cases
+| Empty matches, optional content
+
+| `run_erb.rb`
+| ERB template parsing
+| Template syntax, embedded Ruby code
+
+| `run_ip_address.rb`
+| IPv4 address parsing and validation
+| IP format validation, octet parsing
+
+| `run_json.rb`
+| Complete JSON parser with all data types
+| Objects, arrays, strings, numbers, booleans, null
+
+| `run_local.rb`
+| Local variable scoping demonstration
+| Variable declarations, scope management
+
+| `run_mathn.rb`
+| Mathematical expression parsing
+| Math operations, Ruby mathn compatibility
+
+| `run_minilisp.rb`
+| Minimal Lisp interpreter
+| S-expressions, nested structures, symbols
+
+| `run_modularity.rb`
+| Modular parser design patterns
+| Parser composition, reusable components
+
+| `run_nested_errors.rb`
+| Nested error handling strategies
+| Error propagation, context preservation
+
+| `run_optimized_erb.rb`
+| Performance-optimized ERB parsing
+| Greedy parsing, performance comparison
+
+| `run_parens.rb`
+| Parentheses matching and balancing
+| Balanced expressions, nesting validation
+
+| `run_prec_calc.rb`
+| Calculator with full operator precedence
+| Complex precedence rules, associativity
+
+| `run_readme.rb`
+| README-style documentation parsing
+| Document structure, sections, formatting
+
+| `run_scopes.rb`
+| Variable scope handling in parsers
+| Block scoping, variable shadowing
+
+| `run_seasons.rb`
+| Transform chains and data processing
+| Multi-stage transformations, data flow
+
+| `run_sentence.rb`
+| Natural language sentence parsing
+| Grammar rules, sentence structure
+
+| `run_simple_xml.rb`
+| Basic XML parsing
+| Tags, attributes, nested elements
+
+| `run_string_parser.rb`
+| String literal parsing with escaping
+| Quote handling, escape sequences
+|===
+
+=== Example structure
+
+Each example follows a consistent structure:
+
+* Educational comments explaining the parsing problem
+* Sample input data demonstrating various test cases
+* Parser demonstration showing both successful parsing and error handling
+* Output explanation describing what the parser supports and how it works
+
+=== Learning path
+
+For beginners, we recommend starting with these examples in order:
+
+. `run_simple_xml.rb` - Basic parsing concepts
+. `run_calc.rb` - Operator precedence and evaluation
+. `run_json.rb` - Complex data structures
+. `run_boolean_algebra.rb` - Transformations and logic
+. `run_minilisp.rb` - Advanced parsing techniques
+
+== Development
+
+After checking out the repo, run:
+
+[source,bash]
+----
+$ bundle install
+----
+
+=== Available rake tasks
+
+==== Testing
+
+* `rake spec` - Run all tests (438 examples covering all functionality)
+* `rake spec:unit` - Run unit tests only
+* `rake spec:opal` - Run Opal (JavaScript) tests (437 examples)
+
+===== Running Opal tests
+
+The Opal test suite runs the same specs as the Ruby test suite but in a
+JavaScript environment via Node.js. This ensures parslet works correctly when
+compiled to JavaScript with Opal.
+
+To run all Opal tests:
+
+[source,bash]
+----
+$ bundle exec rake spec:opal
+----
+
+The Opal specs are located in the `spec-opal/` directory and mirror the
+structure of the main `spec/` directory.
+
+NOTE: Some Opal tests may fail due to environment differences between Ruby and
+JavaScript execution, but the core parsing functionality is fully supported.
+
+==== Benchmarking
+
+* `rake benchmark` - Run quick benchmarks (alias for benchmark:quick)
+* `rake benchmark:quick` - Run example-focused benchmarks only
+* `rake benchmark:examples` - Run example-focused benchmarks
+* `rake benchmark:all` - Run comprehensive benchmark suite (all categories)
+* `rake benchmark:export` - Run benchmarks and export results to JSON/YAML files
+
+===== What gets benchmarked
+
+The benchmark suite measures parsing performance across different scenarios:
+
+**Basic Parsing Operations**
+
+* `str('hello')` - Simple string matching performance
+* `match('[a-z]').repeat(1)` - Character class matching with repetition
+* Email-like pattern matching - Complex regex-style parsing (`user@example.com`)
+
+**Calculator Parser** (from `example/calc.rb`)
+
+* Simple expressions: `1+2`
+* Medium complexity: `1+2*3-4/2`
+* Complex expressions: `123*456+789-321/3*2+1`
+* Full pipeline (parse + transform + evaluate)
+
+**JSON Parser** (from `example/json.rb`)
+
+* Simple objects: `{"key": "value"}`
+* Arrays: `[1, 2, 3, 4, 5]`
+* Complex nested structures with multiple data types
+* Parse vs. transform performance comparison
+
+**String Parsing**
+
+* Simple quoted strings: `"hello world"`
+* Long strings (1000+ characters)
+* Escaped strings with backslash sequences: `"hello \"world\" with escapes"`
+
+**Repetition Patterns**
+
+* `repeat(1)` with varying input lengths (short/medium/long)
+* Bounded repetition `repeat(3,6)`
+* Optional repetition `repeat` (zero or more)
+* Performance scaling with input size
+
+**Transform Operations**
+
+* Simple AST transformations (number/string conversion)
+* Medium complexity (multiple rules, arrays)
+* Complex nested transformations with multiple rule types
+
+===== Sample benchmark output
+
+[example]
+====
+[source]
+----
+Plurimath Parslet Performance Benchmarks
+==================================================
+
+Basic Parsing Operations
+------------------------------
+ruby 3.3.2 (2024-05-30 revision e5a195edf6) [arm64-darwin23]
+Warming up --------------------------------------
+        str('hello')    17.235k i/100ms
+match('[a-z]').repeat(1)
+                         3.502k i/100ms
+  email-like pattern     2.780k i/100ms
+Calculating -------------------------------------
+        str('hello')    174.636k (± 2.1%) i/s    (5.73 μs/i)
+match('[a-z]').repeat(1)
+                         35.182k (± 2.6%) i/s   (28.42 μs/i)
+  email-like pattern     27.874k (± 8.5%) i/s   (35.88 μs/i)
+
+Comparison:
+        str('hello'):   174636.1 i/s
+match('[a-z]').repeat(1):    35182.1 i/s - 4.96x  slower
+  email-like pattern:    27873.8 i/s - 6.27x  slower
+
+Calculator Parser Benchmarks
+------------------------------
+ parse simple: '1+2'     18.791k (± 3.2%) i/s   (53.22 μs/i)
+parse medium: '1+2*3-4/2'
+                          8.871k (± 6.4%) i/s  (112.73 μs/i)
+parse complex: '123*456+789-321/3*2+1'
+                          5.872k (± 4.3%) i/s  (170.30 μs/i)
+    full calc simple      7.516k (± 8.5%) i/s  (133.06 μs/i)
+   full calc complex      3.018k (± 1.9%) i/s  (331.34 μs/i)
+----
+====
+
+===== Benchmark results export
+
+Results are exported to multiple formats for analysis:
+
+* `benchmark/results.json` - Detailed benchmark data with iterations/second, standard deviation, and microseconds per iteration
+* `benchmark/results.yaml` - YAML format results for easy reading
+* `benchmark/summary.json` - Performance summary with fastest/slowest operations and insights
+* `benchmark/summary.yaml` - YAML format summary
+
+The exported data includes:
+
+* Ruby version and platform information
+* Parslet version and benchmark tool versions
+* Detailed performance metrics for each test case
+* Statistical analysis (standard deviation, error percentages)
+* Performance comparisons and insights
+* Identification of performance bottlenecks and optimization opportunities
+
+==== Building and distribution
+
+* `rake build` - Build plurimath-parslet-3.0.0.gem into the pkg directory
+* `rake build:checksum` - Generate SHA512 checksum of the gem
+* `rake install` - Build and install gem into system gems
+* `rake install:local` - Build and install gem without network access
+* `rake release[remote]` - Create tag and push gem to rubygems.org
+
+==== Documentation
+
+* `rake rdoc` - Build RDoc HTML files
+* `rake rdoc:coverage` - Print RDoc coverage report
+* `rake rerdoc` - Rebuild RDoc HTML files
+
+==== Maintenance
+
+* `rake clean` - Remove temporary products
+* `rake clobber` - Remove generated files
+* `rake clobber_rdoc` - Remove RDoc HTML files
+* `rake stat` - Print lines of code statistics
+
+=== Example coverage
+
+All 25 examples in the `examples/` directory are covered by specs and tested automatically:
+
+* boolean_algebra.rb, calc.rb, capture.rb, comments.rb, deepest_errors.rb
+* documentation.rb, email_parser.rb, empty.rb, erb.rb, ip_address.rb
+* json.rb, local.rb, mathn.rb, minilisp.rb, modularity.rb
+* nested_errors.rb, optimized_erb.rb, parens.rb, prec_calc.rb, readme.rb
+* scopes.rb, seasons.rb, sentence.rb, simple_xml.rb, string_parser.rb
+
+== Contributing
+
+. Fork it
+. Create your feature branch (`git checkout -b my-new-feature`)
+. Commit your changes (`git commit -am 'Add some feature'`)
+. Push to the branch (`git push origin my-new-feature`)
+. Create a new Pull Request
+
+== License
+
+The gem is available as open source under the terms of the MIT License.
+
+== Copyright
+
+(c) 2010-2018 Kaspar Schiess.
+
+2025 Augmented by Ribose Inc.

data/Rakefile

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rdoc/task'
+
+begin
+  require 'opal/rspec/rake_task'
+rescue LoadError, NoMethodError
+  # Opal not available or incompatible with current Ruby version
+end
+
+desc 'Run all tests'
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :spec do
+  desc 'Run unit tests only'
+  RSpec::Core::RakeTask.new(:unit) do |task|
+    task.pattern = 'spec/parslet/**/*_spec.rb'
+  end
+
+  if defined?(Opal::RSpec::RakeTask)
+    desc 'Run Opal (JavaScript) tests'
+    Opal::RSpec::RakeTask.new(:opal) do |task|
+      task.append_path 'lib'
+    end
+  end
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'Plurimath Parslet'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.adoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc 'Print LOC statistics'
+task :stat do
+  %w[lib spec example].each do |dir|
+    next unless Dir.exist?(dir)
+
+    loc = `find #{dir} -name "*.rb" | xargs wc -l | grep 'total'`.split.first.to_i
+    printf("%20s %d\n", dir, loc)
+  end
+end
+
+namespace :benchmark do
+  desc 'Run comprehensive benchmark suite'
+  task :all do
+    ruby 'benchmark/benchmark_suite.rb'
+  end
+
+  desc 'Run example-focused benchmarks'
+  task :examples do
+    ruby 'benchmark/example_benchmarks.rb'
+  end
+
+  desc 'Run benchmarks and export results to JSON/YAML'
+  task :export do
+    ruby 'benchmark/benchmark_runner.rb'
+  end
+
+  desc 'Run quick benchmark (examples only)'
+  task quick: :examples
+end
+
+desc 'Run quick benchmarks'
+task benchmark: 'benchmark:quick'
+
+task default: :spec

data/lib/parslet/accelerator/application.rb

@@ -0,0 +1,62 @@
+
+# @api private
+module Parslet::Accelerator
+  class Application
+    def initialize atom, rules
+      @atom = atom
+      @rules = rules
+    end
+
+    def call
+      @atom.accept(self)
+    end
+
+    def visit_parser(root)
+      transform root.accept(self)
+    end
+    def visit_entity(name, block)
+      transform Parslet::Atoms::Entity.new(name) { block.call.accept(self) }
+    end
+    def visit_named(name, atom)
+      transform Parslet::Atoms::Named.new(atom.accept(self), name)
+    end
+    def visit_repetition(tag, min, max, atom)
+      transform Parslet::Atoms::Repetition.new(atom.accept(self), min, max, tag)
+    end
+    def visit_alternative(alternatives)
+      transform Parslet::Atoms::Alternative.new(
+        *alternatives.map { |atom| atom.accept(self) })
+    end
+    def visit_sequence(sequence)
+      transform Parslet::Atoms::Sequence.new(
+        *sequence.map { |atom| atom.accept(self) })
+    end
+    def visit_lookahead(positive, atom)
+      transform Parslet::Atoms::Lookahead.new(atom, positive)
+    end
+    def visit_re(regexp)
+      transform Parslet::Atoms::Re.new(regexp)
+    end
+    def visit_str(str)
+      transform Parslet::Atoms::Str.new(str)
+    end
+
+    def transform atom
+      @rules.each do |expr, action|
+        # Try and match each rule in turn
+        binding = Parslet::Accelerator.match(atom, expr)
+        if binding
+          # On a successful match, allow the rule action to transform the
+          # parslet into something new. 
+          ctx = Parslet::Context.new(binding)
+          return ctx.instance_eval(&action)
+        end
+      end # rules.each 
+
+      # If no rule matches, this is the fallback - a clean new parslet atom.
+      return atom
+    end
+  end
+end
+
+require 'parslet/context'

data/lib/parslet/accelerator/engine.rb

@@ -0,0 +1,112 @@
+
+require 'parslet/atoms/visitor'
+
+module Parslet::Accelerator
+  # @api private
+  class Apply
+    def initialize(engine, expr)
+      @engine = engine
+      @expr = expr
+    end
+
+    def visit_parser(root)
+      false
+    end
+    def visit_entity(name, block)
+      false
+    end
+    def visit_named(name, atom)
+      match(:as) do |key|
+        @engine.try_bind(key, name)
+      end
+    end
+    def visit_repetition(tag, min, max, atom)
+      match(:rep) do |e_min, e_max, expr|
+        e_min == min && e_max == max && @engine.match(atom, expr)
+      end
+    end
+    def visit_alternative(alternatives)
+      match(:alt) do |*expressions|
+        return false if alternatives.size != expressions.size
+
+        alternatives.zip(expressions).all? do |atom, expr|
+          @engine.match(atom, expr)
+        end
+      end
+    end
+    def visit_sequence(sequence)
+      match(:seq) do |*expressions|
+        return false if sequence.size != expressions.size
+
+        sequence.zip(expressions).all? do |atom, expr|
+          @engine.match(atom, expr)
+        end
+      end
+    end
+    def visit_lookahead(positive, atom)
+      match(:absent) do |expr|
+        return positive == false && @engine.match(atom, expr)
+      end
+      match(:present) do |expr|
+        return positive == true && @engine.match(atom, expr)
+      end
+    end
+    def visit_re(regexp)
+      match(:re) do |*bind_conditions|
+        bind_conditions.all? { |bind_cond| 
+          @engine.try_bind(bind_cond, regexp) }
+      end
+    end
+    def visit_str(str)
+      match(:str) do |*bind_conditions|
+        bind_conditions.all? { |bind_cond| 
+          @engine.try_bind(bind_cond, str) }
+      end
+    end
+
+    def match(type_tag)
+      expr_tag = @expr.type
+      if expr_tag == type_tag
+        yield *@expr.args
+      end
+    end
+  end
+
+  # @api private
+  class Engine
+    attr_reader :bindings
+
+    def initialize 
+      @bindings = {}
+    end
+
+    def match(atom, expr)
+      atom.accept(
+        Apply.new(self, expr))
+    end
+
+    def try_bind(variable, value)
+      if bound? variable
+        return value == lookup(variable)
+      else
+        case variable
+          when Symbol
+            bind(variable, value)
+        else
+          # This does not look like a variable - let's try matching it against
+          # the value: 
+          variable === value
+        end    
+      end
+    end
+    def bound? var
+      @bindings.has_key? var
+    end
+    def lookup var
+      @bindings[var]
+    end
+    def bind var, val
+      @bindings[var] = val
+    end
+  end
+end