. documentation

lib/parslet/cause.rb

@@ -1,14 +1,46 @@
 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, :children) # :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. 
+    attr_reader :children
+
+    # 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, children=nil)
-      self.new(str, source, pos, children || [])
+    # @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