plurimath-parslet 3.0.0

data/lib/parslet/atoms/dsl.rb

@@ -0,0 +1,112 @@
+
+# A mixin module that defines operations that can be called on any subclass
+# of Parslet::Atoms::Base. These operations make parslets atoms chainable and 
+# allow combination of parslet atoms to form bigger parsers.
+#
+# Example: 
+#
+#   str('foo') >> str('bar')
+#   str('f').repeat
+#   any.absent?               # also called The Epsilon
+#
+module Parslet::Atoms::DSL
+  # Construct a new atom that repeats the current atom min times at least and
+  # at most max times. max can be nil to indicate that no maximum is present. 
+  #
+  # Example: 
+  #   # match any number of 'a's
+  #   str('a').repeat     
+  #
+  #   # match between 1 and 3 'a's
+  #   str('a').repeat(1,3)
+  #
+  def repeat(min=0, max=nil)
+    Parslet::Atoms::Repetition.new(self, min, max)
+  end
+  
+  # Returns a new parslet atom that is only maybe present in the input. This
+  # is synonymous to calling #repeat(0,1). Generated tree value will be 
+  # either nil (if atom is not present in the input) or the matched subtree. 
+  #
+  # Example: 
+  #   str('foo').maybe
+  #
+  def maybe
+    Parslet::Atoms::Repetition.new(self, 0, 1, :maybe)
+  end
+
+  # Returns a new parslet atom that will not show up in the output. This
+  # is synonymous to calling #repeat(0,1). Generated tree value will always be 
+  # nil.
+  #
+  # Example: 
+  #   str('foo').ignore
+  #
+  def ignore
+    Parslet::Atoms::Ignored.new(self)
+  end
+
+  # Chains two parslet atoms together as a sequence. 
+  #
+  # Example: 
+  #   str('a') >> str('b')
+  #
+  def >>(parslet)
+    Parslet::Atoms::Sequence.new(self, parslet)
+  end
+
+  # Chains two parslet atoms together to express alternation. A match will
+  # always be attempted with the parslet on the left side first. If it doesn't
+  # match, the right side will be tried. 
+  #
+  # Example:
+  #   # matches either 'a' OR 'b'
+  #   str('a') | str('b')
+  #
+  def |(parslet)
+    Parslet::Atoms::Alternative.new(self, parslet)
+  end
+  
+  # Tests for absence of a parslet atom in the input stream without consuming
+  # it. 
+  # 
+  # Example: 
+  #   # Only proceed the parse if 'a' is absent.
+  #   str('a').absent?
+  #
+  def absent?
+    Parslet::Atoms::Lookahead.new(self, false)
+  end
+
+  # Tests for presence of a parslet atom in the input stream without consuming
+  # it. 
+  # 
+  # Example: 
+  #   # Only proceed the parse if 'a' is present.
+  #   str('a').present?
+  #
+  def present?
+    Parslet::Atoms::Lookahead.new(self, true)
+  end
+  
+  # Marks a parslet atom as important for the tree output. This must be used 
+  # to achieve meaningful output from the #parse method. 
+  #
+  # Example:
+  #   str('a').as(:b) # will produce {:b => 'a'}
+  #
+  def as(name)
+    Parslet::Atoms::Named.new(self, name)
+  end
+
+  # Captures a part of the input and stores it under the name given. This 
+  # is very useful to create self-referential parses. A capture stores
+  # the result of its parse (may be complex) on a successful parse action.
+  # 
+  # Example: 
+  #   str('a').capture(:b)  # will store captures[:b] == 'a'
+  # 
+  def capture(name)
+    Parslet::Atoms::Capture.new(self, name)
+  end
+end

data/lib/parslet/atoms/dynamic.rb

@@ -0,0 +1,32 @@
+# Evaluates a block at parse time. The result from the block must be a parser
+# (something which implements #apply). In the first case, the parser will then
+# be applied to the input, creating the result. 
+#
+# Dynamic parses are never cached. 
+#
+# Example: 
+#   dynamic { rand < 0.5 ? str('a') : str('b') }
+#
+class Parslet::Atoms::Dynamic < Parslet::Atoms::Base
+  attr_reader :block
+  
+  def initialize(block)
+    @block = block
+  end
+  
+  def cached?
+    false
+  end
+  
+  def try(source, context, consume_all)
+    result = block.call(source, context)
+    
+    # Result is a parslet atom.
+    return result.apply(source, context, consume_all)
+  end
+  
+  def to_s_inner(prec)
+    "dynamic { ... }"
+  end
+end
+

data/lib/parslet/atoms/entity.rb

@@ -0,0 +1,45 @@
+# This wraps pieces of parslet definition and gives them a name. The wrapped
+# piece is lazily evaluated and cached. This has two purposes: 
+#     
+# * Avoid infinite recursion during evaluation of the definition
+# * Be able to print things by their name, not by their sometimes
+#   complicated content.
+#
+# You don't normally use this directly, instead you should generate it by
+# using the structuring method Parslet.rule.
+#
+class Parslet::Atoms::Entity < Parslet::Atoms::Base
+  attr_reader :name, :block
+  def initialize(name, label=nil, &block)
+    super()
+    
+    @name = name
+    @label = label
+    @block = block
+    @parslet = nil
+  end
+
+  def try(source, context, consume_all)
+    parslet.apply(source, context, consume_all)
+  end
+  
+  def parslet
+    return @parslet unless @parslet.nil?
+    @parslet = @block.call
+    raise_not_implemented if @parslet.nil?
+    @parslet.label = @label
+    @parslet
+  end
+
+  def to_s_inner(prec)
+    name.to_s.upcase
+  end  
+private 
+  def raise_not_implemented
+    trace = caller.reject {|l| l =~ %r{#{Regexp.escape(__FILE__)}}} # blatantly stolen from dependencies.rb in activesupport
+    exception = NotImplementedError.new("rule(#{name.inspect}) { ... }  returns nil. Still not implemented, but already used?")
+    exception.set_backtrace(trace)
+    
+    raise exception
+  end
+end

data/lib/parslet/atoms/ignored.rb

@@ -0,0 +1,26 @@
+# Ignores the result of a match.
+#
+# Example:
+#
+#   str('foo')            # will return 'foo',
+#   str('foo').ignore     # will return nil
+#
+class Parslet::Atoms::Ignored < Parslet::Atoms::Base
+  attr_reader :parslet
+  def initialize(parslet)
+    super()
+
+    @parslet = parslet
+  end
+
+  def apply(source, context, consume_all)
+    success, _ = result = parslet.apply(source, context, consume_all)
+
+    return result unless success
+    succ(nil)
+  end
+  
+  def to_s_inner(prec)
+    "ignored(#{parslet.to_s(prec)})"
+  end
+end

data/lib/parslet/atoms/infix.rb

@@ -0,0 +1,115 @@
+class Parslet::Atoms::Infix < Parslet::Atoms::Base
+  attr_reader :element, :operations, :reducer
+
+  def initialize(element, operations, &reducer)
+    super()
+
+    @element = element
+    @operations = operations
+    @reducer = reducer || lambda { |left, op, right| {l: left, o: op, r: right} }
+  end
+  
+  def try(source, context, consume_all)
+    return catch(:error) {
+      return succ(
+        produce_tree(
+          precedence_climb(source, context, consume_all)))
+    }
+  end
+
+  # Turns an array of the form ['1', '+', ['2', '*', '3']] into a hash that
+  # reflects the same structure.
+  #
+  def produce_tree(ary)
+    return ary unless ary.kind_of? Array
+
+    left = ary.shift
+
+    until ary.empty?
+      op, right = ary.shift(2)
+
+      # p [left, op, right]
+
+      if right.kind_of? Array
+        # Subexpression -> Subhash
+        left = reducer.call(left, op, produce_tree(right))
+      else
+        left = reducer.call(left, op, right)
+      end
+    end
+
+    left
+  end
+
+  # A precedence climbing algorithm married to parslet, as described here
+  #   http://eli.thegreenplace.net/2012/08/02/parsing-expressions-by-precedence-climbing/
+  # 
+  # @note Error handling in this routine is done by throwing :error and 
+  #       as a value the error to return to parslet. This avoids cluttering
+  #       the recursion logic here with parslet error handling. 
+  #
+  def precedence_climb(source, context, consume_all, current_prec=1, needs_element=false)
+    result = []
+
+    # To even begin parsing an arithmetic expression, there needs to be 
+    # at least one @element. 
+    success, value = @element.apply(source, context, false)
+    
+    unless success
+      throw :error, context.err(self, source, "#{@element.inspect} was expected", [value])
+    end
+
+    result << flatten(value, true)
+
+    # Loop until we fail on operator matching or until input runs out.
+    loop do
+      op_pos = source.bytepos
+      op_match, prec, assoc = match_operation(source, context, false)
+
+      # If no operator could be matched here, one of several cases 
+      # applies: 
+      #
+      # - end of file
+      # - end of expression
+      # - syntax error
+      # 
+      # We abort matching the expression here. 
+      break unless op_match
+
+      if prec >= current_prec
+        next_prec = (assoc == :left) ? prec+1 : prec
+
+        result << op_match
+        result << precedence_climb(
+          source, context, consume_all, next_prec, true)
+      else
+        source.bytepos = op_pos
+        return unwrap(result)
+      end
+    end
+
+    return unwrap(result)
+  end
+
+  def unwrap expr
+    expr.size == 1 ? expr.first : expr
+  end
+
+  def match_operation(source, context, consume_all)
+    errors = []
+    @operations.each do |op_atom, prec, assoc|
+      success, value = op_atom.apply(source, context, consume_all)
+      return flatten(value, true), prec, assoc if success
+
+      # assert: this was in fact an error, accumulate
+      errors << value
+    end
+
+    return nil
+  end
+
+  def to_s_inner(prec)
+    ops = @operations.map { |o, _, _| o.inspect }.join(', ')
+    "infix_expression(#{@element.inspect}, [#{ops}])"
+  end
+end

data/lib/parslet/atoms/lookahead.rb

@@ -0,0 +1,52 @@
+# Either positive or negative lookahead, doesn't consume its input. 
+#
+# Example: 
+#
+#   str('foo').present? # matches when the input contains 'foo', but leaves it
+#
+class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
+  attr_reader :positive
+  attr_reader :bound_parslet
+  
+  def initialize(bound_parslet, positive=true)
+    super()
+    
+    # Model positive and negative lookahead by testing this flag.
+    @positive = positive
+    @bound_parslet = bound_parslet
+  end
+
+  def error_msgs
+    @error_msgs ||= {
+      :positive => ["Input should start with ", bound_parslet],
+      :negative => ["Input should not start with ", bound_parslet]
+    }
+  end
+  
+  def try(source, context, consume_all)
+    rewind_pos  = source.bytepos
+    error_pos   = source.pos
+
+    success, _ = bound_parslet.apply(source, context, consume_all)
+    
+    if positive
+      return succ(nil) if success
+      return context.err_at(self, source, error_msgs[:positive], error_pos)
+    else
+      return succ(nil) unless success
+      return context.err_at(self, source, error_msgs[:negative], error_pos)
+    end
+    
+  # This is probably the only parslet that rewinds its input in #try.
+  # Lookaheads NEVER consume their input, even on success, that's why. 
+  ensure 
+    source.bytepos = rewind_pos
+  end
+  
+  precedence LOOKAHEAD
+  def to_s_inner(prec)
+    @char = positive ? '&' : '!'
+
+    "#{@char}#{bound_parslet.to_s(prec)}"
+  end
+end

data/lib/parslet/atoms/named.rb

@@ -0,0 +1,32 @@
+# Names a match to influence tree construction. 
+#
+# Example: 
+#
+#   str('foo')            # will return 'foo', 
+#   str('foo').as(:foo)   # will return :foo => 'foo'
+#
+class Parslet::Atoms::Named < Parslet::Atoms::Base
+  attr_reader :parslet, :name
+  def initialize(parslet, name)
+    super()
+
+    @parslet, @name = parslet, name
+  end
+  
+  def apply(source, context, consume_all)
+    success, value = result = parslet.apply(source, context, consume_all)
+
+    return result unless success
+    succ(
+      produce_return_value(
+        value))
+  end
+  
+  def to_s_inner(prec)
+    "#{name}:#{parslet.to_s(prec)}"
+  end
+private
+  def produce_return_value(val)
+    { name => flatten(val, true) }
+  end
+end

data/lib/parslet/atoms/re.rb

@@ -0,0 +1,41 @@
+# Matches a special kind of regular expression that only ever matches one
+# character at a time. Useful members of this family are: <code>character
+# ranges, \\w, \\d, \\r, \\n, ...</code>
+#
+# Example: 
+#
+#   match('[a-z]')  # matches a-z
+#   match('\s')     # like regexps: matches space characters
+#
+class Parslet::Atoms::Re < Parslet::Atoms::Base
+  attr_reader :match, :re
+  def initialize(match)
+    super()
+
+    @match = match.to_s
+    @re    = Regexp.new(self.match, Regexp::MULTILINE)
+  end
+
+  def error_msgs
+    @error_msgs ||= {
+      premature: 'Premature end of input',
+      failed: "Failed to match #{match.inspect[1..-2]}"
+    }
+  end
+
+  def try(source, context, consume_all)
+    return succ(source.consume(1)) if source.matches?(@re)
+    
+    # No string could be read
+    return context.err(self, source, error_msgs[:premature]) \
+      if source.chars_left < 1
+        
+    # No match
+    return context.err(self, source, error_msgs[:failed])
+  end
+
+  def to_s_inner(prec)
+    match.inspect[1..-2]
+  end
+end
+

data/lib/parslet/atoms/repetition.rb

@@ -0,0 +1,87 @@
+
+# Matches a parslet repeatedly. 
+#
+# Example: 
+#
+#   str('a').repeat(1,3)  # matches 'a' at least once, but at most three times
+#   str('a').maybe        # matches 'a' if it is present in the input (repeat(0,1))
+#
+class Parslet::Atoms::Repetition < Parslet::Atoms::Base  
+  attr_reader :min, :max, :parslet
+  def initialize(parslet, min, max, tag=:repetition)
+    super()
+
+    raise ArgumentError, 
+      "Asking for zero repetitions of a parslet. (#{parslet.inspect} repeating #{min},#{max})" \
+      if max == 0
+
+
+    @parslet = parslet
+    @min = min
+    @max = max
+    @tag = tag
+  end
+
+  def error_msgs
+    @error_msgs ||= {
+      minrep: "Expected at least #{min} of #{parslet.inspect}",
+      unconsumed: 'Extra input after last repetition'
+    }
+  end
+  
+  def try(source, context, consume_all)
+    occ = 0
+    accum = [@tag]   # initialize the result array with the tag (for flattening)
+    start_pos = source.pos
+    
+    break_on = nil
+    loop do
+      success, value = parslet.apply(source, context, false)
+
+      break_on = value
+      break unless success
+
+      occ += 1
+      accum << value
+      
+      # If we're not greedy (max is defined), check if that has been reached. 
+      return succ(accum) if max && occ>=max
+    end
+    
+    # Last attempt to match parslet was a failure, failure reason in break_on.
+    
+    # Greedy matcher has produced a failure. Check if occ (which will
+    # contain the number of successes) is >= min.
+    return context.err_at(
+      self, 
+      source, 
+      error_msgs[:minrep],
+      start_pos, 
+      [break_on]) if occ < min
+      
+    # consume_all is true, that means that we're inside the part of the parser
+    # that should consume the input completely. Repetition failing here means
+    # probably that we didn't. 
+    #
+    # We have a special clause to create an error here because otherwise
+    # break_on would get thrown away. It turns out, that contains very
+    # interesting information in a lot of cases. 
+    #
+    return context.err(
+      self, 
+      source, 
+      error_msgs[:unconsumed], 
+      [break_on]) if consume_all && source.chars_left>0
+      
+    return succ(accum)
+  end
+  
+  precedence REPETITION
+  def to_s_inner(prec)
+    minmax = "{#{min}, #{max}}"
+    minmax = '?' if min == 0 && max == 1
+
+    parslet.to_s(prec) + minmax
+  end
+end
+

data/lib/parslet/atoms/scope.rb

@@ -0,0 +1,26 @@
+# Starts a new scope in the parsing process. Please also see the #captures
+# method. 
+#
+class Parslet::Atoms::Scope < Parslet::Atoms::Base
+  attr_reader :block
+  def initialize(block)
+    super()
+
+    @block = block
+  end
+  
+  def cached?
+    false
+  end
+  
+  def apply(source, context, consume_all)
+    context.scope do
+      parslet = block.call
+      return parslet.apply(source, context, consume_all)
+    end
+  end
+  
+  def to_s_inner(prec)
+    "scope { #{block.call.to_s(prec)} }"
+  end
+end

data/lib/parslet/atoms/sequence.rb

@@ -0,0 +1,48 @@
+# A sequence of parslets, matched from left to right. Denoted by '>>'
+#
+# Example: 
+#
+#   str('a') >> str('b')  # matches 'a', then 'b'
+#
+class Parslet::Atoms::Sequence < Parslet::Atoms::Base
+  attr_reader :parslets
+  def initialize(*parslets)
+    super()
+
+    @parslets = parslets
+  end
+
+  def error_msgs
+    @error_msgs ||= {
+      failed: "Failed to match sequence (#{inspect})"
+    }
+  end
+  
+  def >>(parslet)
+    self.class.new(* @parslets+[parslet])
+  end
+  
+  def try(source, context, consume_all)
+    # Presize an array
+    result = Array.new(parslets.size + 1)
+    result[0] = :sequence
+    
+    parslets.each_with_index do |p, idx|
+      child_consume_all = consume_all && (idx == parslets.size-1)
+      success, value = p.apply(source, context, child_consume_all) 
+
+      unless success
+        return context.err(self, source, error_msgs[:failed], [value])
+      end
+
+      result[idx+1] = value
+    end
+    
+    return succ(result)
+  end
+      
+  precedence SEQUENCE
+  def to_s_inner(prec)
+    parslets.map { |p| p.to_s(prec) }.join(' ')
+  end
+end

data/lib/parslet/atoms/str.rb

@@ -0,0 +1,42 @@
+# Matches a string of characters. 
+#
+# Example: 
+# 
+#   str('foo') # matches 'foo'
+#
+class Parslet::Atoms::Str < Parslet::Atoms::Base
+  attr_reader :str
+  def initialize(str)
+    super()
+
+    @str = str.to_s
+    @pat = Regexp.new(Regexp.escape(str))
+    @len = str.size
+  end
+
+  def error_msgs
+    @error_msgs ||= {
+      premature: 'Premature end of input',
+      failed: "Expected #{str.inspect}, but got "
+    }
+  end
+  
+  def try(source, context, consume_all)
+    return succ(source.consume(@len)) if source.matches?(@pat)
+    
+    # Input ending early:
+    return context.err(self, source, error_msgs[:premature]) \
+      if source.chars_left<@len
+    
+    # Expected something, but got something else instead:  
+    error_pos = source.pos  
+    return context.err_at(
+      self, source, 
+      [error_msgs[:failed], source.consume(@len)], error_pos) 
+  end
+  
+  def to_s_inner(prec)
+    "'#{str}'"
+  end
+end
+