plurimath-parslet 3.0.0

data/lib/parslet/atoms/visitor.rb

@@ -0,0 +1,89 @@
+# Augments all parslet atoms with an accept method that will call back 
+# to the visitor given.
+
+# 
+module Parslet::Atoms
+  class Base
+    def accept(visitor)
+      raise NotImplementedError, "No #accept method on #{self.class.name}."
+    end
+  end
+  
+  class Str
+    # Call back visitors #visit_str method. See parslet/export for an example.
+    #
+    def accept(visitor)
+      visitor.visit_str(str)
+    end
+  end
+  
+  class Entity
+    # Call back visitors #visit_entity method. See parslet/export for an
+    # example. 
+    #
+    def accept(visitor)
+      visitor.visit_entity(name, block)
+    end
+  end
+  
+  class Named
+    # Call back visitors #visit_named method. See parslet/export for an
+    # example. 
+    #
+    def accept(visitor)
+      visitor.visit_named(name, parslet)
+    end
+  end
+  
+  class Sequence
+    # Call back visitors #visit_sequence method. See parslet/export for an
+    # example. 
+    #
+    def accept(visitor)
+      visitor.visit_sequence(parslets)
+    end
+  end
+  
+  class Repetition
+    # Call back visitors #visit_repetition method. See parslet/export for an
+    # example. 
+    #
+    def accept(visitor)
+      visitor.visit_repetition(@tag, min, max, parslet)
+    end
+  end
+  
+  class Alternative
+    # Call back visitors #visit_alternative method. See parslet/export for an
+    # example. 
+    #
+    def accept(visitor)
+      visitor.visit_alternative(alternatives)
+    end
+  end
+  
+  class Lookahead
+    # Call back visitors #visit_lookahead method. See parslet/export for an
+    # example. 
+    #
+    def accept(visitor)
+      visitor.visit_lookahead(positive, bound_parslet)
+    end
+  end
+  
+  class Re
+    # Call back visitors #visit_re method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.visit_re(match)
+    end
+  end
+end
+
+class Parslet::Parser
+  # Call back visitors #visit_parser method. 
+  #
+  def accept(visitor)
+    visitor.visit_parser(root)
+  end
+end

data/lib/parslet/atoms.rb

@@ -0,0 +1,34 @@
+
+# This is where parslets name comes from: Small parser atoms.
+#
+module Parslet::Atoms
+  # The precedence module controls parenthesis during the #inspect printing
+  # of parslets. It is not relevant to other aspects of the parsing.
+  #
+  module Precedence
+    BASE       = 1    # everything else
+    LOOKAHEAD  = 2    # &SOMETHING
+    REPETITION = 3    # 'a'+, 'a'?
+    SEQUENCE   = 4    # 'a' 'b'
+    ALTERNATE  = 5    # 'a' | 'b'
+    OUTER      = 6    # printing is done here.
+  end
+
+  require 'parslet/atoms/can_flatten'
+  require 'parslet/atoms/context'
+  require 'parslet/atoms/dsl'
+  require 'parslet/atoms/base'
+  require 'parslet/atoms/ignored'
+  require 'parslet/atoms/named'
+  require 'parslet/atoms/lookahead'
+  require 'parslet/atoms/alternative'
+  require 'parslet/atoms/sequence'
+  require 'parslet/atoms/repetition'
+  require 'parslet/atoms/re'
+  require 'parslet/atoms/str'
+  require 'parslet/atoms/entity'
+  require 'parslet/atoms/capture'
+  require 'parslet/atoms/dynamic'
+  require 'parslet/atoms/scope'
+  require 'parslet/atoms/infix'
+end

data/lib/parslet/cause.rb

@@ -0,0 +1,101 @@
+module Parslet
+  # Represents a cause why a parse did fail. A lot of these objects are
+  # constructed - not all of the causes turn out to be failures for the whole
+  # parse. 
+  #
+  class Cause
+    def initialize(message, source, pos, children)
+      @message, @source, @pos, @children, @context =
+        message, source, pos, children, nil
+    end
+    
+    # @return [String, Array] A string or an array of message pieces that 
+    #   provide failure information. Use #to_s to get a formatted string.
+    attr_reader :message
+    
+    # @return [Parslet::Source] Source that was parsed when this error 
+    #   happend. Mainly used for line number information.
+    attr_reader :source
+    
+    # Location of the error. 
+    #
+    # @return [Fixnum] Position where the error happened. (character offset)
+    attr_reader :pos 
+    
+    # When this cause is part of a tree of error causes: child nodes for this
+    # node. Very often carries the reasons for this cause. 
+    #
+    # @return [Array<Parslet::Cause>] A list of reasons for this cause. 
+    def children
+      @children ||= []
+    end
+    
+    # Appends 'at line LINE char CHAR' to the string given. Use +pos+ to
+    # override the position of the +source+. This method returns an object
+    # that can be turned into a string using #to_s.
+    #
+    # @param source [Parslet::Source] source that was parsed when this error
+    #   happened 
+    # @param pos [Fixnum] position of error
+    # @param str [String, Array<String>] message parts
+    # @param children [Array<Parslet::Cause>] child nodes for this error tree
+    # @return [Parslet::Cause] a new instance of {Parslet::Cause}
+    #
+    def self.format(source, pos, str, children=[])
+      self.new(str, source, pos, children)
+    end
+
+    # Update error message to include context provided by label
+    # Update all child causes too (the same context applies to all causes)
+    def set_label(l)
+      @context = " when parsing #{l}"
+      children.each { |c| c.set_label(l) }
+    end
+
+    def to_s
+      line, column = source.line_and_column(pos)
+      # Allow message to be a list of objects. Join them here, since we now
+      # really need it.
+      Array(message).map { |o|
+        o.respond_to?(:to_slice) ?
+          o.str.inspect :
+          o.to_s }.join + " at line #{line} char #{column}#{@context}."
+    end
+    
+    # Signals to the outside that the parse has failed. Use this in
+    # conjunction with .format for nice error messages. 
+    #
+    def raise(exception_klass=Parslet::ParseFailed)
+      exception = exception_klass.new(self.to_s, self)
+      Kernel.raise exception
+    end
+
+    # Returns an ascii tree representation of the causes of this node and its
+    # children. 
+    #
+    def ascii_tree
+      StringIO.new.tap { |io| 
+        recursive_ascii_tree(self, io, [true]) }.
+        string
+    end
+
+  private
+    def recursive_ascii_tree(node, stream, curved)
+      append_prefix(stream, curved)
+      stream.puts node.to_s
+
+      node.children.each do |child|
+        last_child = (node.children.last == child)
+
+        recursive_ascii_tree(child, stream, curved + [last_child])
+      end
+    end
+    def append_prefix(stream, curved)
+      return if curved.size < 2
+      curved[1..-2].each do |c|
+        stream.print c ? "   " : "|  "
+      end
+      stream.print curved.last ? "`- " : "|- "
+    end
+  end
+end

data/lib/parslet/context.rb

@@ -0,0 +1,21 @@
+# Provides a context for tree transformations to run in. The context allows
+# accessing each of the bindings in the bindings hash as local method.
+#
+# Example: 
+#
+#   ctx = Context.new(:a => :b)
+#   ctx.instance_eval do 
+#     a # => :b
+#   end
+#
+# @api private
+class Parslet::Context
+  include Parslet
+
+  def initialize(bindings)
+    bindings.each do |key, value|
+      singleton_class.send(:define_method, key) { value }
+      instance_variable_set("@#{key}", value)
+    end
+  end
+end

data/lib/parslet/convenience.rb

@@ -0,0 +1,33 @@
+class Parslet::Atoms::Base
+  
+  # Packages the common idiom
+  #    
+  #    begin
+  #      tree = parser.parse('something')
+  #    rescue Parslet::ParseFailed => error
+  #      puts parser.parse_failure_cause.ascii_tree
+  #    end
+  #
+  # into a convenient method.
+  #
+  # Usage:
+  #   
+  #   require 'parslet'
+  #   require 'parslet/convenience'
+  #   
+  #   class FooParser < Parslet::Parser
+  #     rule(:foo) { str('foo') }
+  #     root(:foo)
+  #   end
+  #   
+  #   FooParser.new.parse_with_debug('bar')
+  #
+  # @see Parslet::Atoms::Base#parse
+  #
+  def parse_with_debug str, opts={}
+    parse str, opts
+  rescue Parslet::ParseFailed => error
+    puts error.parse_failure_cause.ascii_tree
+  end
+
+end

data/lib/parslet/error_reporter/contextual.rb

@@ -0,0 +1,120 @@
+module Parslet
+  module ErrorReporter
+
+    # A reporter that tries to improve on the deepest error reporter by
+    # using heuristics to find the most relevant error and provide more
+    # context.
+    # The heuristic chooses the deepest error when parsing a sequence for which
+    # no alternative parsed successfully.
+    #
+    # Given the following parser:
+    #
+    # root(:call)
+    #
+    # rule(:call, label: 'call') {
+    #   identifier >> str('.') >> method
+    # }
+    #
+    # rule(:method, label: 'method call') {
+    #   identifier >> str('(') >> arguments.maybe >> str(')')
+    # }
+    #
+    # rule(:identifier, label: 'identifier') {
+    #   match['[:alnum:]'].repeat(1)
+    # }
+    #
+    # rule(:arguments, label: 'method call arguments') {
+    #   argument >> str(',') >> arguments | argument
+    # }
+    #
+    # rule(:argument) {
+    #    call | identifier
+    # }
+    #
+    # and the following source:
+    #
+    #   foo.bar(a,goo.baz(),c,)
+    #
+    # The contextual reporter returns the following causes:
+    #
+    # 0: Failed to match sequence (identifier '.' method call) at line 1 char 5
+    #    when parsing method call arguments.
+    # 1: Failed to match sequence (identifier '(' method call arguments? ')') at
+    #    line 1 char 22 when parsing method call arguments.
+    # 2: Failed to match [[:alnum:]] at line 1 char 23 when parsing method call
+    #    arguments.
+    #
+    # (where 2 is a child cause of 1 and 1 a child cause of 0)
+    #
+    # The last piece used by the reporter is the (newly introduced) ability
+    # to attach a label to rules that describe a sequence in the grammar. The
+    # labels are used in two places:
+    #   - In the "to_s" of Atom::Base so that any error message uses labels to
+    #     refer to atoms
+    #   - In the cause error messages to give information about which expression
+    #     failed to parse
+    #
+    class Contextual < Deepest
+
+      def initialize
+        @last_reset_pos = 0
+        reset
+      end
+
+      # A sequence expression successfully parsed, reset all errors reported
+      # for previous expressions in the sequence (an alternative matched)
+      # Only reset errors if the position of the source that matched is higher
+      # than the position of the source that was last successful (so we keep
+      # errors that are the "deepest" but for which no alternative succeeded)
+      #
+      def succ(source)
+        source_pos = source.pos.bytepos
+        return if source_pos < @last_reset_pos
+        @last_reset_pos = source_pos
+        reset
+      end
+
+      # Reset deepest error and its position and sequence index
+      #
+      def reset
+        @deepest_cause = nil
+        @label_pos = -1
+      end
+
+      # Produces an error cause that combines the message at the current level
+      # with the errors that happened at a level below (children).
+      # Compute and set label used by Cause to produce error message.
+      #
+      # @param atom [Parslet::Atoms::Base] parslet that failed
+      # @param source [Source] Source that we're using for this parse. (line
+      #   number information...)
+      # @param message [String, Array] Error message at this level.
+      # @param children [Array] A list of errors from a deeper level (or nil).
+      # @return [Cause] An error tree combining children with message.
+      #
+      def err(atom, source, message, children=nil)
+        cause = super(atom, source, message, children)
+        if (label = atom.respond_to?(:label) && atom.label)
+          update_label(label, source.pos.bytepos)
+          cause.set_label(@label)
+        end
+        cause
+      end
+
+      # Update error message label if given label is more relevant.
+      # A label is more relevant if the position of the matched source is
+      # bigger.
+      #
+      # @param label [String] label to apply if more relevant
+      # @param bytepos [Integer] position in source code of matched source
+      #
+      def update_label(label, bytepos)
+        if bytepos >= @label_pos
+          @label_pos = bytepos
+          @label = label
+        end
+      end
+
+    end
+  end
+end

data/lib/parslet/error_reporter/deepest.rb

@@ -0,0 +1,100 @@
+module Parslet
+  module ErrorReporter
+    # Instead of reporting the latest error that happens like {Tree} does,
+    # this class reports the deepest error. Depth is defined here as how
+    # advanced into the input an error happens. The errors close to the
+    # greatest depth tend to be more relevant to the end user, since they
+    # specify what could be done to make them go away. 
+    #
+    # More specifically, errors produced by this reporter won't be related to
+    # the structure of the grammar at all. The positions of the errors will 
+    # be advanced and convey at every grammar level what the deepest rule
+    # was to fail. 
+    #
+    class Deepest
+      def initialize
+        @deepest_cause = nil
+      end
+      
+      # Produces an error cause that combines the message at the current level
+      # with the errors that happened at a level below (children).
+      #
+      # @param atom [Parslet::Atoms::Base] parslet that failed
+      # @param source [Source] Source that we're using for this parse. (line 
+      #   number information...)
+      # @param message [String, Array] Error message at this level.
+      # @param children [Array] A list of errors from a deeper level (or nil).
+      # @return [Cause] An error tree combining children with message.
+      #
+      def err(atom, source, message, children=nil)
+        position = source.pos
+        cause = Cause.format(source, position, message, children)
+        return deepest(cause)
+      end
+
+      # Produces an error cause that combines the message at the current level
+      # with the errors that happened at a level below (children).
+      #
+      # @param atom [Parslet::Atoms::Base] parslet that failed
+      # @param source [Source] Source that we're using for this parse. (line 
+      #   number information...)
+      # @param message [String, Array] Error message at this level.
+      # @param pos [Fixnum] The real position of the error.
+      # @param children [Array] A list of errors from a deeper level (or nil).
+      # @return [Cause] An error tree combining children with message.
+      #
+      def err_at(atom, source, message, pos, children=nil)
+        position = pos
+        cause = Cause.format(source, position, message, children)
+        return deepest(cause)
+      end
+      
+      # Returns the cause that is currently deepest. Mainly for specs. 
+
+      # Notification that an expression successfully parsed
+      # not used, see ErrorReporter::Contextual
+      def succ(source)
+      end
+      #
+      attr_reader :deepest_cause
+      
+      # Checks to see if the lineage of the cause given includes a cause with
+      # an error position deeper than the current deepest cause stored. If
+      # yes, it passes the cause through to the caller. If no, it returns the
+      # current deepest error that was saved as a reference.
+      #
+      def deepest(cause)
+        _, leaf = deepest_child(cause)
+        
+        if !deepest_cause || leaf.pos >= deepest_cause.pos
+          # This error reaches deeper into the input, save it as reference.
+          @deepest_cause = leaf
+          return cause
+        end
+        
+        return deepest_cause
+      end
+      
+    private
+      # Returns the leaf from a given error tree with the biggest rank. 
+      #
+      def deepest_child(cause, rank=0)
+        max_child = cause
+        max_rank  = rank
+        
+        if cause.children && !cause.children.empty?
+          cause.children.each do |child|
+            c_rank, c_cause = deepest_child(child, rank+1)
+            
+            if c_rank > max_rank
+              max_rank = c_rank
+              max_child = c_cause
+            end
+          end
+        end
+        
+        return max_rank, max_child
+      end
+    end
+  end
+end

data/lib/parslet/error_reporter/tree.rb

@@ -0,0 +1,63 @@
+module Parslet
+  module ErrorReporter
+    # An error reporter has two central methods, one for reporting errors at
+    # the current parse position (#err) and one for reporting errors at a
+    # given parse position (#err_at). The reporter can return an object (a
+    # 'cause') that will be returned to the caller along with the information
+    # that the parse failed. 
+    # 
+    # When reporting errors on the outer levels of your parser, these methods
+    # get passed a list of error objects ('causes') from the inner levels. In
+    # this default implementation, the inner levels are considered error
+    # subtrees and are appended to the generated tree node at each level,
+    # thereby constructing an error tree. 
+    #
+    # This error tree will report in parallel with the grammar structure that
+    # failed. A one-to-one correspondence exists between each error in the 
+    # tree and the parslet atom that produced that error. 
+    #
+    # The implementor is really free to use these return values as he sees
+    # fit. One example would be to return an error state object from these
+    # methods that is then updated as errors cascade up the parse derivation
+    # tree. 
+    #
+    class Tree
+      # Produces an error cause that combines the message at the current level
+      # with the errors that happened at a level below (children).
+      #
+      # @param atom [Parslet::Atoms::Base] parslet that failed
+      # @param source [Source] Source that we're using for this parse. (line 
+      #   number information...)
+      # @param message [String, Array] Error message at this level.
+      # @param children [Array] A list of errors from a deeper level (or nil).
+      # @return [Cause] An error tree combining children with message.
+      #
+      def err(atom, source, message, children=nil)
+        position = source.pos
+        Cause.format(source, position, message, children)
+      end
+
+      # Produces an error cause that combines the message at the current level
+      # with the errors that happened at a level below (children).
+      #
+      # @param atom [Parslet::Atoms::Base] parslet that failed
+      # @param source [Source] Source that we're using for this parse. (line 
+      #   number information...)
+      # @param message [String, Array] Error message at this level.
+      # @param pos [Fixnum] The real position of the error.
+      # @param children [Array] A list of errors from a deeper level (or nil).
+      # @return [Cause] An error tree combining children with message.
+      #
+      def err_at(atom, source, message, pos, children=nil)
+        position = pos
+        Cause.format(source, position, message, children)
+      end
+
+      # Notification that an expression successfully parsed
+      # not used, see ErrorReporter::Contextual
+      def succ(source)
+      end
+
+    end
+  end
+end

data/lib/parslet/error_reporter.rb

@@ -0,0 +1,8 @@
+# A namespace for all error reporters.
+#
+module Parslet::ErrorReporter
+end
+
+require 'parslet/error_reporter/tree'
+require 'parslet/error_reporter/deepest'
+require 'parslet/error_reporter/contextual'