lib/parslet/cause.rb in parslet-1.3.0 vs lib/parslet/cause.rb in parslet-1.4.0

@@ -1,16 +1,50 @@
 module Parslet
-  # An internal class that allows delaying the construction of error messages
-  # (as strings) until we really need to print them. 
+  # 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 < Struct.new(:message, :source, :pos) # :nodoc: 
-    # Appends 'at line ... char ...' to the string given. Use +pos+ to
+  class Cause
+    def initialize(message, source, pos, children)
+      @message, @source, @pos, @children = 
+        message, source, pos, children
+    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.
     #
-    def self.format(source, pos, str)
-      self.new(str, source, pos)
+    # @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
     
     def to_s
       line, column = source.line_and_column(pos)
       # Allow message to be a list of objects. Join them here, since we now
@@ -35,26 +69,24 @@
     def ascii_tree
       StringIO.new.tap { |io| 
         recursive_ascii_tree(self, io, [true]) }.
         string
     end
-    
-    def children
-      @children ||= Array.new
-    end
+
   private
-    def recursive_ascii_tree(node, stream, curved) # :nodoc:
+    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) # :nodoc:
-      curved[0..-2].each do |c|
+    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
\ No newline at end of file