Permalink
Browse files

. slice documentation

  • Loading branch information...
1 parent 3ba78cd commit d97b3262ffc61dab8614e71ebab02f9fe1243922 @kschiess committed Mar 2, 2011
Showing with 50 additions and 9 deletions.
  1. +50 −9 lib/parslet/slice.rb
View
@@ -1,17 +1,50 @@
# A slice is a small part from the parse input. A slice mainly behaves like
-# any other string, except that it remembers where it came from (offset in
+# any other string, except that it remembers where it came from (offset in
# original input).
#
-# Some slices also know what parent slice they are a small part of. This
-# allows the slice to be concatenated to other slices from the same buffer
-# by reslicing it against that original buffer.
+# Some slices also know what parent slice they are a small part of. This
+# allows the slice to be concatenated to other slices from the same buffer by
+# reslicing it against that original buffer.
#
# Why the complexity? Slices allow retaining offset information. This will
-# allow to assign line and column to each small bit of output from the
-# parslet parser. Also, while we keep that information, we might as well
-# try to do something useful with it. Reslicing the same buffers should
-# in theory keep buffer copies and allocations down.
+# allow to assign line and column to each small bit of output from the parslet
+# parser. Also, while we keep that information, we might as well try to do
+# something useful with it. Reslicing the same buffers should in theory keep
+# buffer copies and allocations down.
+#
+# == Extracting line and column
+#
+# Using the #line_and_column method, you can extract the line and column in
+# the original input where this slice starts.
+#
+# Example:
+# slice.line_and_column # => [1, 13]
+# slice.offset # => 12
+#
+# == Likeness to strings
+#
+# Parslet::Slice behaves in many ways like a Ruby String. This likeness
+# however is not complete - many of the myriad of operations String supports
+# are not yet in Slice. You can always extract the internal string instance by
+# calling #to_s.
+#
+# These omissions are somewhat intentional. Rather than maintaining a full
+# delegation, we opt for a partial emulation that gets the job done.
+#
+# Note also that there are some things that work with strings that will never
+# work when using slices. For instance, you cannot concatenate slices that
+# aren't from the same source or that don't join up:
+#
+# Example:
+# big_slice = 'abcdef'
+# a = big_slice.slice(0, 2) # => "ab"@0
+# b = big_slice.slice(4, 2) # => "ef"@4
+#
+# a + b # raises Parslet::InvalidSliceOperation
+#
+# This avoids creating slices with impossible offsets or that are
+# discontinous.
#
class Parslet::Slice
attr_reader :str, :offset
@@ -36,7 +69,9 @@ def match(regexp)
str.match(regexp)
end
- # Reslicing
+ # Returns a slice that starts at offset start and that has length characters.
+ # Whenever possible, return parts of the parent buffer that this slice was
+ # cut out of.
#
def slice(start, length)
# NOTE: At a later stage, we might not want to create huge trees of slices.
@@ -49,6 +84,10 @@ def slice(start, length)
self.class.new(str.slice(start, length), offset+start, source, self)
end
end
+
+ # Returns a slice that starts at file offset start and that has length
+ # characters in it.
+ #
def abs_slice(start, length)
slice(start-offset, length)
end
@@ -119,6 +158,8 @@ def to_f
end
# Inspection & Debugging ---------------------------------------------------
+
+ # Prints the slice as <code>"string"@offset</code>.
def inspect
str.inspect << "@#{offset}"
end

0 comments on commit d97b326

Please sign in to comment.