plurimath-parslet 3.0.0

data/lib/parslet.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+# A simple parser generator library. Typical usage would look like this:
+#
+#   require 'parslet'
+#
+#   class MyParser < Parslet::Parser
+#     rule(:a) { str('a').repeat }
+#     root(:a)
+#   end
+#
+#   pp MyParser.new.parse('aaaa')   # => 'aaaa'@0
+#   pp MyParser.new.parse('bbbb')   # => Parslet::Atoms::ParseFailed:
+#                                   #    Don't know what to do with bbbb at line 1 char 1.
+#
+# The simple DSL allows you to define grammars in PEG-style. This kind of
+# grammar construction does away with the ambiguities that usually comes with
+# parsers; instead, it allows you to construct grammars that are easier to
+# debug, since less magic is involved.
+#
+# Parslet is typically used in stages:
+#
+#
+# * Parsing the input string; this yields an intermediary tree, see
+#   Parslet.any, Parslet.match, Parslet.str, Parslet::ClassMethods#rule and
+#   Parslet::ClassMethods#root.
+# * Transformation of the tree into something useful to you, see
+#   Parslet::Transform, Parslet.simple, Parslet.sequence and Parslet.subtree.
+#
+# The first stage is traditionally intermingled with the second stage; output
+# from the second stage is usually called the 'Abstract Syntax Tree' or AST.
+#
+# The stages are completely decoupled; You can change your grammar around and
+# use the second stage to isolate the rest of your code from the changes
+# you've effected.
+#
+# == Further reading
+#
+# All parslet atoms are subclasses of {Parslet::Atoms::Base}. You might want to
+# look at all of those: {Parslet::Atoms::Re}, {Parslet::Atoms::Str},
+# {Parslet::Atoms::Repetition}, {Parslet::Atoms::Sequence},
+# {Parslet::Atoms::Alternative}.
+#
+# == When things go wrong
+#
+# A parse that fails will raise {Parslet::ParseFailed}. This exception contains
+# all the details of what went wrong, including a detailed error trace that
+# can be printed out as an ascii tree. ({Parslet::Cause})
+#
+module Parslet
+  # Extends classes that include Parslet with the module
+  # {Parslet::ClassMethods}.
+  #
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # Raised when the parse failed to match. It contains the message that should
+  # be presented to the user. More details can be extracted from the
+  # exceptions #parse_failure_cause member: It contains an instance of {Parslet::Cause} that
+  # stores all the details of your failed parse in a tree structure.
+  #
+  #   begin
+  #     parslet.parse(str)
+  #   rescue Parslet::ParseFailed => failure
+  #     puts failure.parse_failure_cause.ascii_tree
+  #   end
+  #
+  # Alternatively, you can just require 'parslet/convenience' and call the
+  # method #parse_with_debug instead of #parse. This method will never raise
+  # and print error trees to stdout.
+  #
+  #   require 'parslet/convenience'
+  #   parslet.parse_with_debug(str)
+  #
+  class ParseFailed < StandardError
+    def initialize(message, parse_failure_cause=nil)
+      super(message)
+      @parse_failure_cause = parse_failure_cause
+    end
+
+    # Why the parse failed.
+    #
+    # @return [Parslet::Cause]
+    attr_reader :parse_failure_cause
+  end
+
+  module ClassMethods
+    # Define an entity for the parser. This generates a method of the same
+    # name that can be used as part of other patterns. Those methods can be
+    # freely mixed in your parser class with real ruby methods.
+    #
+    #   class MyParser
+    #     include Parslet
+    #
+    #     rule(:bar) { str('bar') }
+    #     rule(:twobar) do
+    #       bar >> bar
+    #     end
+    #
+    #     root :twobar
+    #   end
+    #
+    def rule(name, opts={}, &definition)
+      undef_method name if method_defined? name
+      define_method(name) do
+        @rules ||= {}     # <name, rule> memoization
+        return @rules[name] if @rules.has_key?(name)
+
+        # Capture the self of the parser class along with the definition.
+        definition_closure = proc {
+          self.instance_eval(&definition)
+        }
+
+        @rules[name] = Atoms::Entity.new(name, opts[:label], &definition_closure)
+      end
+    end
+  end
+
+  # Allows for delayed construction of #match. See also Parslet.match.
+  #
+  # @api private
+  class DelayedMatchConstructor
+    def [](str)
+      Atoms::Re.new("[" + str + "]")
+    end
+  end
+
+  # Returns an atom matching a character class. All regular expressions can be
+  # used, as long as they match only a single character at a time.
+  #
+  #   match('[ab]')     # will match either 'a' or 'b'
+  #   match('[\n\s]')   # will match newlines and spaces
+  #
+  # There is also another (convenience) form of this method:
+  #
+  #   match['a-z']      # synonymous to match('[a-z]')
+  #   match['\n']       # synonymous to match('[\n]')
+  #
+  # @overload match(str)
+  #   @param str [String] character class to match (regexp syntax)
+  #   @return [Parslet::Atoms::Re] a parslet atom
+  #
+  def match(str=nil)
+    return DelayedMatchConstructor.new unless str
+
+    return Atoms::Re.new(str)
+  end
+  module_function :match
+
+  # Returns an atom matching the +str+ given:
+  #
+  #   str('class')      # will match 'class'
+  #
+  # @param str [String] string to match verbatim
+  # @return [Parslet::Atoms::Str] a parslet atom
+  #
+  def str(str)
+    Atoms::Str.new(str)
+  end
+  module_function :str
+
+  # Returns an atom matching any character. It acts like the '.' (dot)
+  # character in regular expressions.
+  #
+  #   any.parse('a')    # => 'a'
+  #
+  # @return [Parslet::Atoms::Re] a parslet atom
+  #
+  def any
+    Atoms::Re.new('.')
+  end
+  module_function :any
+
+  # Introduces a new capture scope. This means that all old captures stay
+  # accessible, but new values stored will only be available during the block
+  # given and the old values will be restored after the block.
+  #
+  # Example:
+  #   # :a will be available until the end of the block. Afterwards,
+  #   # :a from the outer scope will be available again, if such a thing
+  #   # exists.
+  #   scope { str('a').capture(:a) }
+  #
+  def scope(&block)
+    Parslet::Atoms::Scope.new(block)
+  end
+  module_function :scope
+
+  # Designates a piece of the parser as being dynamic. Dynamic parsers can
+  # either return a parser at runtime, which will be applied on the input, or
+  # return a result from a parse.
+  #
+  # Dynamic parse pieces are never cached and can introduce performance
+  # abnormalitites - use sparingly where other constructs fail.
+  #
+  # Example:
+  #   # Parses either 'a' or 'b', depending on the weather
+  #   dynamic { rand() < 0.5 ? str('a') : str('b') }
+  #
+  def dynamic(&block)
+    Parslet::Atoms::Dynamic.new(block)
+  end
+  module_function :dynamic
+
+  # Returns a parslet atom that parses infix expressions. Operations are
+  # specified as a list of <atom, precedence, associativity> tuples, where
+  # atom is simply the parslet atom that matches an operator, precedence is
+  # a number and associativity is either :left or :right.
+  #
+  # Higher precedence indicates that the operation should bind tighter than
+  # other operations with lower precedence. In common algebra, '+' has
+  # lower precedence than '*'. So you would have a precedence of 1 for '+' and
+  # a precedence of 2 for '*'. Only the order relation between these two
+  # counts, so any number would work.
+  #
+  # Associativity is what decides what interpretation to take for strings that
+  # are ambiguous like '1 + 2 + 3'. If '+' is specified as left associative,
+  # the expression would be interpreted as '(1 + 2) + 3'. If right
+  # associativity is chosen, it would be interpreted as '1 + (2 + 3)'. Note
+  # that the hash trees output reflect that choice as well.
+  #
+  # An optional block can be provided in order to manipulate the generated tree.
+  # The block will be called on each operator and passed 3 arguments: the left
+  # operand, the operator, and the right operand.
+  #
+  # Examples:
+  #   infix_expression(integer, [add_op, 1, :left])
+  #   # would parse things like '1 + 2'
+  #
+  #   infix_expression(integer, [add_op, 1, :left]) { |l,o,r| { :plus => [l, r] } }
+  #   # would parse '1 + 2 + 3' as:
+  #   # { :plus => [1, { :plus => [2, 3] }] }
+  #
+  # @param element [Parslet::Atoms::Base] elements that take the NUMBER position
+  #    in the expression
+  # @param operations [Array<(Parslet::Atoms::Base, Integer, {:left, :right})>]
+  #
+  # @see Parslet::Atoms::Infix
+  #
+  def infix_expression(element, *operations, &reducer)
+    Parslet::Atoms::Infix.new(element, operations, &reducer)
+  end
+  module_function :infix_expression
+
+  # A special kind of atom that allows embedding whole treetop expressions
+  # into parslet construction.
+  #
+  #   # the same as str('a') >> str('b').maybe
+  #   exp(%Q("a" "b"?))
+  #
+  # @param str [String] a treetop expression
+  # @return [Parslet::Atoms::Base] the corresponding parslet parser
+  #
+  def exp(str)
+    Parslet::Expression.new(str).to_parslet
+  end
+  module_function :exp
+
+  # Returns a placeholder for a tree transformation that will only match a
+  # sequence of elements. The +symbol+ you specify will be the key for the
+  # matched sequence in the returned dictionary.
+  #
+  #   # This would match a body element that contains several declarations.
+  #   { :body => sequence(:declarations) }
+  #
+  # The above example would match <code>:body => ['a', 'b']</code>, but not
+  # <code>:body => 'a'</code>.
+  #
+  # see {Parslet::Transform}
+  #
+  def sequence(symbol)
+    Pattern::SequenceBind.new(symbol)
+  end
+  module_function :sequence
+
+  # Returns a placeholder for a tree transformation that will only match
+  # simple elements. This matches everything that <code>#sequence</code>
+  # doesn't match.
+  #
+  #   # Matches a single header.
+  #   { :header => simple(:header) }
+  #
+  # see {Parslet::Transform}
+  #
+  def simple(symbol)
+    Pattern::SimpleBind.new(symbol)
+  end
+  module_function :simple
+
+  # Returns a placeholder for tree transformation patterns that will match
+  # any kind of subtree.
+  #
+  #   { :expression => subtree(:exp) }
+  #
+  def subtree(symbol)
+    Pattern::SubtreeBind.new(symbol)
+  end
+  module_function :subtree
+
+  autoload :Expression, 'parslet/expression'
+end
+
+require 'parslet/version'
+require 'parslet/slice'
+require 'parslet/cause'
+require 'parslet/source'
+require 'parslet/atoms'
+require 'parslet/pattern'
+require 'parslet/pattern/binding'
+require 'parslet/transform'
+require 'parslet/parser'
+require 'parslet/error_reporter'
+require 'parslet/scope'

data/plurimath-parslet.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/parslet/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'plurimath-parslet'
+  spec.version = Parslet::VERSION
+  spec.platform = Gem::Platform::RUBY
+
+  spec.authors = ['Kaspar Schiess', '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. ' \
+                     'This is a fork of the original parslet gem with Opal (JavaScript-based Ruby) compatibility.'
+  spec.homepage = 'https://github.com/plurimath/plurimath-parslet'
+  spec.license = 'MIT'
+
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/plurimath/plurimath-parslet/issues',
+    'changelog_uri' => 'https://github.com/plurimath/plurimath-parslet/blob/main/HISTORY.txt',
+    'documentation_uri' => 'https://kschiess.github.io/parslet/',
+    'homepage_uri' => 'https://github.com/plurimath/plurimath-parslet',
+    'source_code_uri' => 'https://github.com/plurimath/plurimath-parslet',
+    'rubygems_mfa_required' => 'true',
+  }
+
+  spec.files = Dir.glob('{lib,spec,example}/**/*') + %w[
+    HISTORY.txt
+    LICENSE
+    Rakefile
+    README.adoc
+    plurimath-parslet.gemspec
+  ]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rdoc', '~> 6.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

data/spec/acceptance/infix_parser_spec.rb

@@ -0,0 +1,145 @@
+require 'spec_helper'
+
+describe 'Infix expression parsing' do
+  class InfixExpressionParser < Parslet::Parser
+    rule(:space) { Parslet.match['\s'] }
+
+    def cts(atom)
+      atom >> space.repeat
+    end
+
+    def infix(*args)
+      Infix.new(*args)
+    end
+
+    rule(:mul_op) { Parslet.match['*/'] >> str(' ').maybe }
+    rule(:add_op) { Parslet.match['+-'] >> str(' ').maybe }
+    rule(:digit) { Parslet.match['0-9'] }
+    rule(:integer) { cts digit.repeat(1).as(:int) }
+
+    rule(:expression) do
+      infix_expression(integer,
+                       [mul_op, 2, :left],
+                       [add_op, 1, :right])
+    end
+  end
+
+  let(:p) { InfixExpressionParser.new }
+
+  describe '#integer' do
+    let(:i) { p.integer }
+
+    it 'parses integers' do
+      i.should parse('1')
+      i.should parse('123')
+    end
+
+    it 'consumes trailing white space' do
+      i.should parse('1   ')
+      i.should parse('134   ')
+    end
+
+    it "doesn't parse floats" do
+      i.should_not parse('1.3')
+    end
+  end
+
+  describe '#multiplication' do
+    let(:m) { p.expression }
+
+    it 'parses simple multiplication' do
+      m.should parse('1*2').as(l: {int: '1'}, o: '*', r: {int: '2'})
+    end
+
+    it 'parses simple multiplication with spaces' do
+      m.should parse('1 * 2').as(l: {int: '1'}, o: '* ', r: {int: '2'})
+    end
+
+    it 'parses division' do
+      m.should parse('1/2')
+    end
+  end
+
+  describe '#addition' do
+    let(:a) { p.expression }
+
+    it 'parses simple addition' do
+      a.should parse('1+2')
+    end
+
+    it 'parses complex addition' do
+      a.should parse('1+2+3-4')
+    end
+
+    it 'parses a single element' do
+      a.should parse('1')
+    end
+  end
+
+  describe 'mixed operations' do
+    let(:mo) { p.expression }
+
+    describe 'inspection' do
+      it 'produces useful expressions' do
+        p.expression.parslet.inspect.should ==
+          'infix_expression(INTEGER, [MUL_OP, ADD_OP])'
+      end
+    end
+
+    describe 'right associativity' do
+      it 'produces trees that lean right' do
+        mo.should parse('1+2+3').as(
+          l: {int: '1'}, o: '+', r: { l: {int: '2'}, o: '+', r: {int: '3'} },
+        )
+      end
+    end
+
+    describe 'left associativity' do
+      it 'produces trees that lean left' do
+        mo.should parse('1*2*3').as(
+          l: { l: {int: '1'}, o: '*', r: {int: '2'} }, o: '*', r: {int: '3'},
+        )
+      end
+    end
+
+    describe 'error handling' do
+      describe 'incomplete expression' do
+        it 'produces the right error' do
+          cause = catch_failed_parse do
+            mo.parse('1+')
+          end
+
+          cause.ascii_tree.to_s.should == <<~ERROR
+            INTEGER was expected at line 1 char 3.
+            `- Failed to match sequence (int:(DIGIT{1, }) SPACE{0, }) at line 1 char 3.
+               `- Expected at least 1 of DIGIT at line 1 char 3.
+                  `- Premature end of input at line 1 char 3.
+          ERROR
+        end
+      end
+
+      describe 'invalid operator' do
+        it 'produces the right error' do
+          cause = catch_failed_parse do
+            mo.parse('1%')
+          end
+
+          cause.ascii_tree.to_s.should == <<~ERROR
+            Don't know what to do with "%" at line 1 char 2.
+          ERROR
+        end
+      end
+    end
+  end
+
+  describe 'providing a reducer block' do
+    class InfixExpressionReducerParser < Parslet::Parser
+      rule(:top) { infix_expression(str('a'), [str('-'), 1, :right]) { |l, _o, r| { and: [l, r] } } }
+    end
+
+    it 'applies the reducer' do
+      result = InfixExpressionReducerParser.new.top.parse('a-a-a')
+      strip_positions(result).should == { and: ['a', { and: %w[a a] }] }
+    end
+  end
+end

data/spec/acceptance/mixing_parsers_spec.rb

@@ -0,0 +1,74 @@
+require 'spec_helper'
+
+require 'parslet'
+
+describe 'Mixing parsers using alternate' do
+  class MixedParsersParser
+    include Parslet
+
+    rule(:parser1) do
+      str('a') >> match('\d').repeat(1).as(:number) >> (str(':') >> match('\d').repeat(4, 4).as(:year)).maybe
+    end
+
+    rule(:parser2) do
+      str('a') >> match('\d').repeat(1).as(:number) >> str(' Edition').as(:edition).maybe
+    end
+
+    rule(:failing_rule_example) do
+      str('(') >> ((parser1 | parser2) >> str(', ').maybe).repeat(1) >> str(')')
+    end
+
+    rule(:mixed_parsers) do
+      parser1 | parser2
+    end
+
+    rule(:identifiers) do
+      str('(') >> (match('[^),]').repeat(1).as(:identifier) >> str(', ').maybe).repeat(1) >> str(')')
+    end
+
+    def two_pass_parsing(code)
+      TransformIdentifiers.new.apply(MixedParsersParser.new.identifiers.parse(code))
+    end
+  end
+
+  class TransformIdentifiers < Parslet::Transform
+    rule(identifier: simple(:identifier)) do |x|
+      { identifier: MixedParsersParser.new.mixed_parsers.parse(x[:identifier].to_s) }
+    end
+  end
+
+  describe MixedParsersParser do
+    subject { MixedParsersParser.new }
+
+    let(:should_match_parser1) { 'a12345:1234' }
+    let(:should_match_parser2) { 'a12345 Edition' }
+    let(:should_match_any_parser) { 'a12345' }
+    let(:should_match_both_parsers) { "(#{should_match_parser1}, #{should_match_parser2})" }
+
+    let(:parser1_result) { subject.parser1.parse(should_match_parser1) }
+    let(:parser2_result) { subject.parser2.parse(should_match_parser2) }
+
+    it 'fails with alternating parsers' do
+      expect(subject.failing_rule_example).to parse("(#{should_match_any_parser})")
+      expect(subject.failing_rule_example).to parse("(#{should_match_parser1})")
+      expect(subject.failing_rule_example).not_to parse("(#{should_match_parser2})", trace: true)
+      expect(subject.failing_rule_example).not_to parse(should_match_both_parsers, trace: true)
+    end
+
+    it 'parses identifier' do
+      result = subject.identifiers.parse("(#{should_match_parser1})")
+      expect(strip_positions(result)).to eq([{ identifier: should_match_parser1 }])
+    end
+
+    it 'parses several identifiers' do
+      result = subject.identifiers.parse(should_match_both_parsers)
+      expect(strip_positions(result)).to eq([{ identifier: should_match_parser1 },
+                                             { identifier: should_match_parser2 }])
+    end
+
+    it 'parses using 2-level parsing' do
+      expect(subject.two_pass_parsing(should_match_both_parsers))
+        .to eq([{ identifier: parser1_result }, { identifier: parser2_result }])
+    end
+  end
+end