parslet 1.3.0 → 1.4.0

data/lib/parslet/convenience.rb

@@ -5,8 +5,7 @@ class Parslet::Atoms::Base
   #    begin
   #      tree = parser.parse('something')
   #    rescue Parslet::ParseFailed => error
-  #      puts error
-  #      puts parser.error_tree
+  #      puts parser.cause.ascii_tree
   #    end
   #
   # into a convenient method.
@@ -23,13 +22,14 @@ class Parslet::Atoms::Base
   #   
   #   FooParser.new.parse_with_debug('bar')
   #
-  def parse_with_debug str
-    parse str
+  # @see Parslet::Atoms::Base#parse
+  #
+  def parse_with_debug str, opts={}
+    parse str, opts
   rescue Parslet::UnconsumedInput => error
     puts error
   rescue Parslet::ParseFailed => error
-    puts error
-    puts error_tree
+    puts error.cause.ascii_tree
   end
 
 end

data/lib/parslet/error_reporter.rb

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

data/lib/parslet/error_reporter/deepest.rb

@@ -0,0 +1,95 @@
+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. 
+      #
+      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)
+        rank, 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,57 @@
+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
+    end
+  end
+end

data/lib/parslet/export.rb

@@ -68,7 +68,7 @@ class Parslet::Parser
 
   # A helper class that formats Citrus and Treetop grammars as a string. 
   #
-  class PrettyPrinter # :nodoc:
+  class PrettyPrinter
     attr_reader :visitor
     def initialize(visitor_klass)
       @visitor = visitor_klass.new(self)
@@ -78,7 +78,7 @@ class Parslet::Parser
     # configured in initialize. Returns the string representation of the
     # Citrus or Treetop grammar.
     #
-    def pretty_print(name, parslet) # :nodoc:
+    def pretty_print(name, parslet)
       output = "grammar #{name}\n"
       
       output << rule('root', parslet)
@@ -111,7 +111,7 @@ class Parslet::Parser
     # Whenever the visitor encounters an rule in a parslet, it defers the
     # pretty printing of the rule by calling this method. 
     #
-    def deferred(name, content) # :nodoc:
+    def deferred(name, content)
       @todo ||= []
       @todo << [name, content]
     end
@@ -120,7 +120,7 @@ class Parslet::Parser
     # transforms some of the things that Ruby allows into other patterns. If
     # there is collision, we will not detect it for now. 
     #
-    def mangle_name(str) # :nodoc:
+    def mangle_name(str)
       str.to_s.sub(/\?$/, '_p')
     end
   end

data/lib/parslet/expression.rb

@@ -6,8 +6,6 @@
 # This can be viewed as an extension to parslet and might even be hosted in
 # its own gem one fine day. 
 # 
-# NOT FINISHED & EXPERIMENTAL
-#
 class Parslet::Expression
   include Parslet
   

data/lib/parslet/expression/treetop.rb

@@ -1,5 +1,5 @@
 class Parslet::Expression::Treetop
-  class Parser < Parslet::Parser # :nodoc:
+  class Parser < Parslet::Parser
     root(:expression)
     
     rule(:expression) { alternatives }
@@ -69,7 +69,7 @@ class Parslet::Expression::Treetop
     end
   end
   
-  class Transform < Parslet::Transform # :nodoc:
+  class Transform < Parslet::Transform
     
     rule(:repetition => simple(:rep), :sign => simple(:sign)) { 
       min = sign=='+' ? 1 : 0

data/lib/parslet/parser.rb

@@ -57,15 +57,11 @@ class Parslet::Parser < Parslet::Atoms::Base
     end
   end
   
-  def try(source, context) # :nodoc:
+  def try(source, context)
     root.try(source, context)
   end
   
-  def error_tree # :nodoc:
-    root.error_tree
-  end
-  
-  def to_s_inner(prec) # :nodoc:
+  def to_s_inner(prec)
     root.to_s(prec)
   end
 end

data/lib/parslet/pattern.rb

@@ -28,10 +28,13 @@ class Parslet::Pattern
   # bindings to be a hash, the mappings in it will be treated like bindings
   # made during an attempted match. 
   #
-  # Example: 
-  #
   #   Pattern.new('a').match('a', :foo => 'bar') # => { :foo => 'bar' }
   #
+  # @param subtree [String, Hash, Array] poro subtree returned by a parse
+  # @param bindings [Hash] variable bindings to be verified
+  # @return [Hash, nil] On success: variable bindings that allow a match. On 
+  #   failure: nil
+  #
   def match(subtree, bindings=nil)
     bindings = bindings && bindings.dup || Hash.new
     return bindings if element_match(subtree, @pattern, bindings)
@@ -41,6 +44,8 @@ class Parslet::Pattern
   # given by +exp+. This match must respect bindings already made in
   # +bindings+. Note that bindings is carried along and modified. 
   #
+  # @api private
+  #
   def element_match(tree, exp, bindings) 
     # p [:elm, tree, exp]
     case [tree, exp].map { |e| e.class }
@@ -63,7 +68,9 @@ class Parslet::Pattern
     end
   end
   
-  def element_match_binding(tree, exp, bindings) # :nodoc:
+  # @api private
+  #
+  def element_match_binding(tree, exp, bindings)
     var_name = exp.variable_name
 
     # TODO test for the hidden :_ feature.
@@ -77,13 +84,17 @@ class Parslet::Pattern
     return true
   end
   
-  def element_match_ary_single(sequence, exp, bindings) # :nodoc:
+  # @api private
+  #
+  def element_match_ary_single(sequence, exp, bindings)
     return false if sequence.size != exp.size
     
     return sequence.zip(exp).all? { |elt, subexp|
       element_match(elt, subexp, bindings) }
   end
   
+  # @api private
+  #
   def element_match_hash(tree, exp, bindings)
     # Early failure when one hash is bigger than the other
     return false unless exp.size == tree.size

data/lib/parslet/pattern/binding.rb

@@ -5,7 +5,7 @@
 # It defines the most permissive kind of bind, the one that matches any subtree
 # whatever it looks like. 
 #
-class Parslet::Pattern::SubtreeBind < Struct.new(:symbol) # :nodoc:
+class Parslet::Pattern::SubtreeBind < Struct.new(:symbol)
   def variable_name
     symbol
   end
@@ -33,7 +33,7 @@ end
 # Binds a symbol to a simple subtree, one that is not either a sequence of
 # elements or a collection of attributes. 
 #
-class Parslet::Pattern::SimpleBind < Parslet::Pattern::SubtreeBind # :nodoc:
+class Parslet::Pattern::SimpleBind < Parslet::Pattern::SubtreeBind
   def can_bind?(subtree)
     not [Hash, Array].include?(subtree.class)
   end
@@ -41,7 +41,7 @@ end
 
 # Binds a symbol to a sequence of simple leafs ([element1, element2, ...])
 #
-class Parslet::Pattern::SequenceBind < Parslet::Pattern::SubtreeBind # :nodoc:
+class Parslet::Pattern::SequenceBind < Parslet::Pattern::SubtreeBind
   def can_bind?(subtree)
     subtree.kind_of?(Array) &&
       (not subtree.any? { |el| [Hash, Array].include?(el.class) })

data/lib/parslet/rig/rspec.rb

@@ -7,8 +7,8 @@ RSpec::Matchers.define(:parse) do |input, opts|
       block ? 
         block.call(result) : 
         (as == result || as.nil?)
-    rescue Parslet::ParseFailed
-      trace = parser.error_tree.ascii_tree if opts && opts[:trace]
+    rescue Parslet::ParseFailed => ex
+      trace = ex.cause.ascii_tree if opts && opts[:trace]
       false
     end
   end

data/lib/parslet/slice.rb

@@ -98,10 +98,4 @@ class Parslet::Slice
   def inspect
     str.inspect << "@#{offset}"
   end
-end
-
-# Raised when trying to do an operation on slices that cannot succeed, like
-# adding non-adjacent slices. See Parslet::Slice.
-#
-class Parslet::InvalidSliceOperation < StandardError
 end

data/lib/parslet/source.rb

@@ -4,82 +4,63 @@ require 'stringio'
 require 'parslet/source/line_cache'
 
 module Parslet
-  # Wraps the input IO to parslet. The interface defined by this class is 
-  # smaller than what IO offers, but enhances it with a #column and #line 
-  # method for the current position. 
+  # Wraps the input string for parslet. 
   #
   class Source
-    def initialize(io)
-      if io.respond_to? :to_str
-        io = StringIO.new(io)
-      end
+    def initialize(str)
+      raise ArgumentError unless str.respond_to?(:to_str)
     
-      @io = io
+      @pos = 0
+      @str = str
+      
       @line_cache = LineCache.new
+      @line_cache.scan_for_line_endings(0, @str)
     end
   
-    # Reads n bytes from the input and returns a Range instance. If the n 
-    # bytes end in the middle of a multibyte representation of a char, that 
-    # char is returned fully. 
+    # Checks if the given pattern matches at the current input position. 
     #
-    # Example: 
-    #   source.read(1)  # always returns at least one valid char
-    #   source.read(7)  # reads 7 bytes, then to the next char boundary.
+    # @param pattern [Regexp, String] pattern to check for
+    # @return [Boolean] true if the pattern matches at #pos
     #
-    def read(n)
-      raise ArgumentError, "Cannot read < 1 characters at a time." if n < 1
-      read_slice(n)
-    end
-  
-    def eof?
-      @io.eof?
-    end
-    def pos
-      @io.pos
-    end
-    def pos=(new_pos)
-      @io.pos = new_pos
+    def matches?(pattern)
+      @str.index(pattern, @pos) == @pos
     end
-
-    # Returns a <line, column> tuple for the given position. If no position is
-    # given, line/column information is returned for the current position given
-    # by #pos. 
+    alias match matches?
+    
+    # Consumes n characters from the input, returning them as a slice of the
+    # input. 
     #
-    def line_and_column(position=nil)
-      @line_cache.line_and_column(position || self.pos)
+    def consume(n)
+      slice_str = @str.slice(@pos, n)
+      slice = Parslet::Slice.new(
+        slice_str, 
+        pos,
+        @line_cache)
+      
+      @pos += slice_str.size
+      return slice
     end
-  
-    # Formats an error cause at the current position or at the position given 
-    # by pos. If pos is nil, the current source position will be the error 
-    # position.
+    
+    # Returns how many chars remain in the input. 
     #
-    def error(message, error_pos=nil)
-      real_pos = (error_pos||self.pos)      
-      
-      Cause.format(self, real_pos, message)
+    def chars_left
+      @str.size - @pos
     end
-  
-  private
-    def read_slice(needed)
-      start = @io.pos
-      buf = @io.gets(nil, needed)
-
-      # cache line ends
-      @line_cache.scan_for_line_endings(start, buf)
     
-      Parslet::Slice.new(buf || '', start, @line_cache)
+    def eof?
+      @pos >= @str.size
     end
-  
-    if RUBY_VERSION !~ /^1.9/
-      def read_slice(needed)
-        start = @io.pos
-        buf = @io.read(needed)
 
-        # cache line ends
-        @line_cache.scan_for_line_endings(start, buf)
+    # Position of the parse as a character offset into the original string. 
+    # @note: Encodings...
+    attr_accessor :pos
 
-        Parslet::Slice.new(buf || '', start, @line_cache)
-      end
+    # Returns a <line, column> tuple for the given position. If no position is
+    # given, line/column information is returned for the current position
+    # given by #pos. 
+    #
+    def line_and_column(position=nil)
+      @line_cache.line_and_column(position || self.pos)
     end
   end
 end