pestle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06fb88b355cc01ed9c3b17aa398c2b5c61246a875082246dd3f509406979e62c
+  data.tar.gz: 55e5b166a282d8d3aba0c8b6af8751d1f1b6098482a986079a21da1f5480d6e8
+SHA512:
+  metadata.gz: b2ded82209106e7e7355ddb2605069e4f9c008ad35bfb51247cf94e48dff7e812ca15508a4a6bb83cc5f6c7704b137da5fb300dd705f8ca7a60f2b605c9ec8d4
+  data.tar.gz: 0d9228e4e56327ace972b15e707c85ff3f3d2f20680e8998436e9895924dcf5083e0f1b0259d58ac11f74d63f8bbb4376ee74970569dfda49bbfced147912676

data/.rubocop.yml

@@ -0,0 +1,59 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 100
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 100
+
+Metrics/CyclomaticComplexity:
+  Max: 50
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/MethodParameterName:
+  AllowedNames: [op, re]
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Minitest/AssertPredicate:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 26-02-21
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 James Prior
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/LICENSE_PEST.txt

@@ -0,0 +1,23 @@
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+# Ruby Pestle
+
+Pestle is a Ruby port of the [Rust pest](https://pest.rs/) parsing library - a PEG (Parsing Expression Grammar) parser generator.
+
+We use the same grammar syntax as Pest v2. See the [Pest Book](https://pest.rs/book/).
+
+Language grammars are parsed to an internal representation from which input text can be parsed into token pairs. Currently there is no code gen phase.
+
+As of version 0.1.0, grammar optimization is unimplemented. Even with some optimization passes, Pest implemented in pure Ruby is never going to be as fast as a hand-crafted parser. It might still be useful for prototyping and/or testing during language design.
+
+## Links
+
+- Change log: https://github.com/jg-rp/ruby-pestle/blob/main/CHANGELOG.md
+- RubyGems: https://rubygems.org/gems/pestle
+- Source code: https://github.com/jg-rp/ruby-pestle
+- Issue tracker: https://github.com/jg-rp/ruby-pestle/issues
+
+## Usage
+
+Please see [examples](https://github.com/jg-rp/ruby-pestle/tree/main/examples) and refer to [pair.rb](https://github.com/jg-rp/ruby-pestle/blob/main/lib/pestle/pair.rb) for the token API.
+
+### Debugging
+
+Given this example grammar for a calculator with grammar-encoded operator precedence.
+
+```ruby
+GRAMMAR = <<~GRAMMAR
+  program     =  { SOI ~ expr ~ EOI }
+  expr        =  { add_sub }   // top-level expression
+
+  add_sub     =  { mul_div ~ (add_op ~ mul_div)* }
+  add_op      = _{ add | sub }
+    add       =  { "+" }
+    sub       =  { "-" }
+
+  mul_div     =  { pow_expr ~ (mul_op ~ pow_expr)* }
+  mul_op      = _{ mul | div }
+    mul       =  { "*" }
+    div       =  { "/" }
+
+  pow_expr    =  { prefix ~ (pow_op ~ pow_expr)? } // right-associative
+  pow_op      = _{ pow }
+    pow       =  { "^" }
+
+  prefix      =  { (neg)* ~ postfix }
+    neg       =  { "-" }
+
+  postfix     =  { primary ~ (fac)* }
+    fac       =  { "!" }
+
+  primary     = { int | ident | "(" ~ expr ~ ")" }
+    int       = @{ (ASCII_NONZERO_DIGIT ~ ASCII_DIGIT* | "0") }
+    ident     = @{ ASCII_ALPHA+ }
+
+  WHITESPACE  = _{ " " | "\t" | NEWLINE }
+GRAMMAR
+
+START_RULE = :program
+
+parser = Pestle::Parser.from_grammar(GRAMMAR)
+```
+
+We can dump a tree view of the grammar.
+
+```ruby
+puts parser.tree_view
+```
+
+**Output** (we're just showing the first three rules here)
+
+```
+Pestle::Grammar::Rule                      program = { SOI ~ expr ~ EOI }
+    └── Pestle::Grammar::Sequence          SOI ~ expr ~ EOI
+        ├── Pestle::Grammar::Identifier    SOI
+        ├── Pestle::Grammar::Identifier    expr
+        └── Pestle::Grammar::Identifier    EOI
+
+Pestle::Grammar::Rule                  expr = { add_sub }
+    └── Pestle::Grammar::Identifier    add_sub
+
+Pestle::Grammar::Rule                                  add_sub = { mul_div ~ (add_op ~ mul_div)* }
+    └── Pestle::Grammar::Sequence                      mul_div ~ (add_op ~ mul_div)*
+        ├── Pestle::Grammar::Identifier                mul_div
+        └── Pestle::Grammar::Repeat                    (add_op ~ mul_div)*
+            └── Pestle::Grammar::Group                 (add_op ~ mul_div)
+                └── Pestle::Grammar::Sequence          add_op ~ mul_div
+                    ├── Pestle::Grammar::Identifier    add_op
+                    └── Pestle::Grammar::Identifier    mul_div
+```
+
+We can also dump arbitrary token pairs for inspection.
+
+```ruby
+pairs = parser.parse(START_RULE, "1 + 2 * 3!")
+puts pairs.dumps
+```
+
+**Output**
+
+```
+- program
+  - expr > add_sub
+    - mul_div > pow_expr > prefix > postfix > primary > int: "1"
+    - add: "+"
+    - mul_div
+      - pow_expr > prefix > postfix > primary > int: "2"
+      - mul: "*"
+      - pow_expr > prefix > postfix
+        - primary > int: "3"
+        - fac: "!"
+  - EOI: ""
+```
+
+There's also `Pair#dump` and `Pairs#dump`, which return a more verbose, JSON-like representation of the generated token pairs.
+
+```ruby
+puts JSON.pretty_generate(pairs.dump)
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Ruby Pestle is a port of [Rust pest](https://pest.rs/). See `LICENSE_PEST.txt`.

data/Rakefile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new do |task|
+  task.plugins << "rubocop-minitest"
+  task.plugins << "rubocop-rake"
+  task.plugins << "rubocop-performance"
+end
+
+require "steep/rake_task"
+
+Steep::RakeTask.new do |t|
+  t.check.severity_level = :error
+  t.watch.verbose
+end
+
+task default: %i[test rubocop steep]

data/Steepfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+  check "lib"
+
+  library "json"
+  library "strscan"
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end

data/benchmarks/jsonpath_ips.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "json"
+require_relative "../examples/jsonpath/lib/jsonpath"
+
+CTS = JSON.parse(File.read("test/jsonpath-compliance-test-suite/cts.json"))
+VALID_QUERIES = CTS["tests"].filter { |t| !t.key?("invalid_selector") }
+COMPILED_QUERIES = VALID_QUERIES.map { |t| [JSONPathPest.compile(t["selector"]), t["document"]] }
+
+puts "#{VALID_QUERIES.length} queries per iteration"
+
+Benchmark.ips do |x|
+  # Configure the number of seconds used during
+  # the warmup phase (default 2) and calculation phase (default 5)
+  x.config(warmup: 2, time: 5)
+
+  x.report("compile and find:") do
+    VALID_QUERIES.map { |t| JSONPathPest.find(t["selector"], t["document"]) }
+  end
+
+  x.report("just compile:") do
+    VALID_QUERIES.map { |t| JSONPathPest.compile(t["selector"]) }
+  end
+
+  x.report("just find:") do
+    COMPILED_QUERIES.map { |p, d| p.find(d) }
+  end
+
+  x.report("just pest parse:") do
+    VALID_QUERIES.map { |t| JSONPathPest.pest_parse(t["selector"]) }
+  end
+end

data/examples/calculator_pratt.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# Based on the calculator example found in the pest book, with
+# the addition of the `ident` rule.
+# https://pest.rs/book/precedence.html.
+
+# https://github.com/pest-parser/book/blob/master/LICENSE-MIT
+#
+# Permission is hereby granted, free of charge, to any
+# person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the
+# Software without restriction, including without
+# limitation the rights to use, copy, modify, merge,
+# publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software
+# is furnished to do so, subject to the following
+# conditions:
+#
+# The above copyright notice and this permission notice
+# shall be included in all copies or substantial portions
+# of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+# ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+# TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+# IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+require_relative "../lib/pestle"
+
+module PrattExample
+  GRAMMAR = <<~'GRAMMAR'
+    WHITESPACE   =  _{ " " | "\t" | NEWLINE }
+
+    program      =   { SOI ~ expr ~ EOI }
+      expr       =   { prefix* ~ primary ~ postfix* ~ (infix ~ prefix* ~ primary ~ postfix* )* }
+        infix    =  _{ add | sub | mul | div | pow }
+          add    =   { "+" } // Addition
+          sub    =   { "-" } // Subtraction
+          mul    =   { "*" } // Multiplication
+          div    =   { "/" } // Division
+          pow    =   { "^" } // Exponentiation
+        prefix   =  _{ neg }
+          neg    =   { "-" } // Negation
+        postfix  =  _{ fac }
+          fac    =   { "!" } // Factorial
+        primary  =  _{ int | "(" ~ expr ~ ")" | ident }
+          int    =  @{ (ASCII_NONZERO_DIGIT ~ ASCII_DIGIT+ | ASCII_DIGIT) }
+          ident  =  @{ ASCII_ALPHA+ }
+  GRAMMAR
+
+  PARSER = Pestle::Parser.from_grammar(GRAMMAR)
+
+  START_RULE = :program
+
+  # Very basic abstract syntax tree (AST) nodes.
+
+  VarExpr = Struct.new(:value) do
+    def evaluate(vars) = vars[value]
+  end
+
+  IntExpr = Struct.new(:value) do
+    def evaluate(vars) = value # rubocop: disable Lint/UnusedMethodArgument
+  end
+
+  PrefixExpr = Struct.new(:op, :expr) do
+    def evaluate(vars) = expr.evaluate(vars).send(op)
+  end
+
+  InfixExpr = Struct.new(:left, :op, :right) do
+    def evaluate(vars) = left.evaluate(vars).send(op, right.evaluate(vars))
+  end
+
+  PostfixExpr = Struct.new(:expr, :op) do
+    def evaluate(vars) = expr.evaluate(vars).send(op)
+  end
+
+  # Monkey patch Integer with a factorial method.
+  class ::Integer
+    remove_method(:fact) if method_defined?(:fact)
+    def fact
+      (1..self).reduce(1, :*)
+    end
+  end
+
+  # Example Pratt parser for a calculator grammar.
+  class CalculatorParser < Pestle::PrattParser
+    PREFIX_OPS = { neg: 6 }.freeze
+
+    INFIX_OPS = {
+      add: [3, LEFT_ASSOC],
+      sub: [3, LEFT_ASSOC],
+      mul: [4, LEFT_ASSOC],
+      div: [4, LEFT_ASSOC],
+      pow: [5, RIGHT_ASSOC]
+    }.freeze
+
+    POSTFIX_OPS = { fac: 7 }.freeze
+
+    def parse(program)
+      pairs = PARSER.parse(START_RULE, program)
+      parse_expr(pairs.first.inner.first.stream)
+    end
+
+    def parse_primary(pair)
+      case pair
+      in :int, _
+        IntExpr.new(pair.text.to_i)
+      in :ident, _
+        VarExpr.new(pair.text)
+      in :expr, _
+        parse_expr(pair.stream)
+      else
+        raise "unexpected #{pair.text.inspect}"
+      end
+    end
+
+    def parse_prefix(op, rhs)
+      raise "unknown prefix operator #{op.text.inspect}" unless op.rule == :neg
+
+      PrefixExpr.new(:-@, rhs)
+    end
+
+    def parse_postfix(lhs, op)
+      raise "unknown postfix operator #{op.text.inspect}" unless op.rule == :fac
+
+      PostfixExpr.new(lhs, :fact)
+    end
+
+    def parse_infix(lhs, op, rhs)
+      case op
+      in :add, _
+        InfixExpr.new(lhs, :+, rhs)
+      in :sub, _
+        InfixExpr.new(lhs, :-, rhs)
+      in :mul, _
+        InfixExpr.new(lhs, :*, rhs)
+      in :div, _
+        InfixExpr.new(lhs, :/, rhs)
+      in :pow, _
+        InfixExpr.new(lhs, :**, rhs)
+      else
+        raise "unknown infix operator #{op.text.inspect}"
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  parser = PrattExample::CalculatorParser.new
+  prog = parser.parse("1 + 2 + x")
+  puts prog.evaluate({ "x" => 39 })
+end