cursor 0.5 → 0.6

data/cursor.rb

@@ -1,1138 +1,1257 @@
-#!/bin/env ruby
-# cursor.rb
-
-# An object in this Cursor class can be best thought of as a cursor in a text
-# editor.  Many of the same operations apply - insert, delete, replace, copy,
-# paste, move, goto begin/end, mark position, goto mark, etc.  Unlike a
-# text editor, this class can operate on variety of data, not just characters
-# and strings.  It is up to the derived classes to deal with what type of data
-# is stored (i.e. characters, arbitrary array objects) and how it is stored (in
-# an Array, String, IO, mapping to another Cursor, etc).
-class Cursor
-
-    include Comparable
-    include Enumerable
-
-    # Operate on data before the cursor rather than after
-    Reverse = 1
-    # Hold position - do the operation and come back
-    Hold = 2
-    # Just count the elements from get/delete instead of returning their value
-    Ignore = 4
-    # Read the data being replaced using put and return it (instead of the count)
-    Read = 4
-    # Delete instead of retrieve elements (used with get)
-    Delete = 8
-    # Insert instead of replace elements (used with put)
-    Insert = 8
-    # Put a single element instead of a sequence (needed when it looks like a sequence)
-    Single = 16
-    # Operate on what follows the cursor and then move foward
-    Next = 0
-    # Operate on what precedes the cursor and then move backward
-    Prev = Reverse
-    # Operate on what follows the cursor and hold position
-    After = Hold
-    # Operate on what precedes the cursor and hold position
-    Before = Reverse|Hold
-    
-    protected
-
-    # Delete one element at the cursor and return it.  The observed bits in +flags+
-    # are +Reverse+ (delete before the cursor instead of after) and +Ignore+
-    # (return true instead of the deleted element).  When the cursor is at the end (or beginning),
-    # either nil or the code block result is returned (see #get).  
-    # <b>This method must be overriden
-    # in a derived class</b>.
-    def _delete1(flags,&more) # :yield: len=1
-        raise(NotImplementedError)
-    end
-    # Insert one element at the cursor.  Only the +Reverse+ bit
-    # is observed in +flags+.  nil should be returned.  <b>This method must be overriden
-    # in a derived class</b>.
-    def _insert1(value,flags)
-        raise(NotImplementedError)
-    end
-    # Get an element at the cursor.  The observed bits in +flags+ are +Reverse+
-    # (read before instead of after the cursor), +Hold+ (don't move the
-    # cursor), and +Ignore+ (just return +true+ instead of the value).  When the
-    # cursor is at the end (or beginning), either nil or the code block result
-    # is returned (see #get).
-    def _get1(flags,&more) # :yield: len=1
-        value = _delete1(flags&~Ignore) { |len| more&&more[len] || return }
-        if flags&Hold != 0
-            flags ^= Hold
-            flags ^= Reverse
-        end
-        _insert1(value,flags)
-        (flags&Ignore != 0) ? true : value
-    end
-    # Put an element at the cursor.  The observed bits in +flags+ are +Reverse+
-    # (put before instead of after the cursor), +Hold+ (don't move the
-    # cursor), and +Read+ (read and return what is being replaced instead of
-    # just returning +true+).  When the cursor is at the end (or beginning),
-    # either nil or the code block result is returned (see #get).
-    # The value is inserted at that point when that happens.
-    def _put1(value,flags,&more) # :yield: len=1
-        value0 = _delete1(flags^Read,&more)
-        if flags&Hold != 0
-            flags ^= Hold
-            flags ^= Reverse
-        end
-        _insert1(value,flags)
-        value0
-    end
-
-    public
-
-    # Create a cursor.
-    def initialize
-        @positions = []
-    end
-    # Return the class used for passing/returning a sequence of elements.  This
-    # class must behave as a String or an Array ([], []=, slice, slice!, length).
-    # The default in the base class is Array.
-    def data_class
-        Array
-    end
-    # Get a single element or a sequence of them.
-    #
-    # +len+ can be +nil+ (get one element), a positive number (get a
-    # sequence of that many elements), 0 (get all remaining),
-    # a negative number (get all but that many), or what +data_class+ says
-    # (get a sequence up until it finds a match to +len+).
-    #
-    # The observed bits in +flags+ are +Reverse+
-    # (read before instead of after the cursor), +Hold+ (don't move the
-    # cursor), +Ignore+ (just return +true+ or a count instead of the value),
-    # and +Delete+ (delete the element or sequence while retrieving it).
-    #
-    # If there is left, either nil (no code block) or the result from code block is
-    # returned.  This code block could set some variable(s) to say signify it
-    # is done or return data from some other source to make it look as though
-    # it is not done.  When returning more data, it should return it in a
-    # String or Array of up to +len+ elements.
-    def get(len=nil,flags=Next,&more) # :yield: len
-        g = (flags&Delete != 0) ? :_delete1 : :_get1
-        return(__send__(g,flags,&more)) if not len
-        if flags&Hold != 0 && flags&Delete == 0
-            flags ^= Hold
-            position { get(len,flags,&more) }
-        elsif len.class==data_class
-            if flags&Ignore != 0
-                value = get(len,flags^Ignore,&more)
-                return(value&&value.size)
-            end
-            value = data_class.new
-            if flags&Reverse != 0
-                i = len.size-1
-                step = -1
-                finish = -1
-            else
-                i = 0
-                step = +1
-                finish = len.size
-            end
-            loop do
-                v = __send__(g,flags) { |len|
-                    more&&more[len] || begin
-                        value = value.reverse if flags&Reverse != 0
-                        value = nil if value.size==0
-                        return
-                    end
-                }
-                value << v
-                if v==len[i]
-                    i += step
-                    if i==finish
-                        value = value.reverse if flags&Reverse != 0
-                        return(value)
-                    end
-                else
-                    i = 0
-                end
-            end
-        else
-            if flags&Ignore != 0
-                len1 = 0
-                if len<=0
-                    if len<0 and flags&Delete != 0
-                        value = get(len,flags^Ignore,&more)
-                        return(value&&value.size)
-                    end
-                    continue = true
-                    loop do
-                        __send__(g,flags) { |len| continue = more&&more[len] }
-                        break unless continue
-                        len1 += 1
-                    end
-                    (len..-1).each do
-                        _get1(flags^Reverse) { |len|
-                            more&&more[len] || (return(len1))
-                        }
-                        len1 -= 1
-                    end
-                else
-                    len -= 1
-                    while len1<=len
-                        __send__(g,flags) { |len|
-                            more&&more[len] ||
-                            (return(len1==0 ? nil : len1))
-                        }
-                        len1 += 1
-                    end
-                end
-                len1
-            else
-                value = data_class.new
-                if len<=0
-                    continue = true
-                    loop do
-                        v = __send__(g,flags) { |len| continue = more&&more[len] }
-                        break unless continue
-                        value << v
-                    end
-                    (len..-1).each do
-                        return(nil) if value.size==0
-                        v = value.slice!(-1)
-                        if flags&Delete != 0
-                            _insert1(v,flags&~Read^Reverse)
-                        else
-                            _get1(flags^Reverse|Ignore) { raise(IndexError,"couldn't get back to where we were") }
-                        end
-                    end
-                else
-                    len -= 1
-                    while value.size<=len
-                        v = __send__(g,flags&~Ignore) { |len|
-                            more&&more[len] || begin
-                                if value.size==0
-                                    value = nil
-                                elsif flags&Reverse != 0
-                                    value = value.reverse
-                                end
-                                return(value)
-                            end
-                        }
-                        value << v
-                    end
-                end
-                flags&Reverse != 0 ? value.reverse : value
-            end
-        end
-    end
-    # Put a single element or a sequence of them at the cursor.
-    #
-    # The observed bits in +flags+ are +Reverse+
-    # (read before instead of after the cursor), +Hold+ (don't move the
-    # cursor), +Read+ (return the what is overwritten instead of +true+ or a count),
-    # +Insert+ (insert rather than replace +value+), and +Single+ (force +value+
-    # to be treated as a single element rather than a sequence).
-    #
-    # When the cursor is at the end (or beginning),
-    # either nil or the code block result is returned (see #get).
-    # The value is inserted at that point when that happens.
-    def put(value,flags=Next,&more) # :yield: len
-        if flags&Single != 0 or value.class!=data_class
-            if flags&Insert != 0
-                if flags&Hold != 0
-                    flags ^= Hold
-                    flags ^= Reverse
-                end
-                return(_insert1(value,flags,&more))
-            else
-                return(_put1(value,flags,&more))
-            end
-        end
-        if flags&Insert != 0
-            flags |= Single
-            if flags&Hold != 0
-                flags ^= Hold
-                flags ^= Reverse
-            end
-            if flags&Reverse != 0
-                start = value.size-1
-                finish = 0
-                step = -1
-            else
-                start = 0
-                finish = value.size-1
-                step = +1
-            end
-            start.step(finish,step) do |i|
-                _insert1(value[i],flags)
-            end
-            nil
-        elsif flags&Hold != 0
-            flags ^= Hold
-            position { put(value,flags,&more) }
-        else
-            flags |= Single
-            if flags&Reverse != 0
-                start = value.size-1
-                finish = 0
-                step = -1
-            else
-                start = 0
-                finish = value.size-1
-                step = +1
-            end
-            if flags&Read != 0
-                value0 = data_class.new
-                replacing = true
-                start.step(finish,step) do |i|
-                    v = _put1(value[i],flags) { |len|
-                        replacing = more&&more[len]
-                    }
-                    value0 << v if replacing
-                end
-                if value0.size==0
-                    nil
-                elsif step<0
-                    value0.reverse
-                else
-                    value0
-                end
-            else
-                len0 = 0
-                replacing = true
-                start.step(finish,step) do |i|
-                    _put1(value[i],flags) { |len|
-                        replacing = more&&more[len]
-                    }
-                    len0 += 1 if replacing
-                end
-                if len0==0
-                    nil
-                else
-                    len0
-                end
-            end
-        end
-    end
-    # With no +p+ or code block, this will return an numeric position.  This
-    # base class uses 0 to mean the beginning and the total number of elements to
-    # represent the end.  Derived classes can shift these relative positions
-    # if desired (i.e. Cursor::Reversed uses negative numbers).
-    #
-    # With a +p+ or code block specified, optionally set #pos= +p+,
-    # execute the code block or find the #pos (without a block), and finally return to where it
-    # started (using #pos/#pos=).  The return value will be the
-    # result of code block or the inner #pos.
-    def pos(p=nil,&code) # :yield:
-        if code or p
-            start = pos
-            self.pos = p if p
-            ret = code ? code[] : pos
-            self.pos = start
-            ret
-        else
-            p = get(0,Prev|Ignore)
-            return(0) if not p or p==0
-            get(p,Next|Ignore)==p or raise(IndexError,"couldn't get back to where we were: #{p}")
-            p
-        end
-    end
-    # Returns the #pos
-    def to_i
-        pos
-    end
-    # Returns the string "pos=#{#pos}".  Derived classes may override this
-    # to provide more information (i.e. line and column).
-    def to_s
-        "pos=#{pos}"
-    end
-    # Set #pos to be +p+.  This base class also allows +p+ to be negative
-    # values measured from the end just like the indices for String/Array.
-    def pos=(p)
-        if p<0
-            get(0,Next|Ignore)
-            return(-0.1) if p>-1
-            p = -(get(-p,Prev|Ignore)||0.1)
-        else
-            get(0,Prev|Ignore)
-            return(0) if p<1
-            get(p,Next|Ignore)||0
-        end
-    end
-    def _finalizer(id) # :nodoc:
-        i = @positions.index(id)
-        @positions.slice!(i) if i
-    end
-    protected :_finalizer
-    # Similar to #pos except Cursor::Position objects (which are Cursors) are
-    # used to save and retrieve the position.
-    def position(p=nil,&code) # :yield:
-        if code or p
-            start = position
-            self.position = p if p
-            ret = code ? code[] : position
-            self.position = start
-            start.close
-            ret
-        else
-            p = Position.new(self,pos)
-            @positions << (p.object_id >> 1)
-            ObjectSpace.define_finalizer(p,method(:_finalizer))
-            p
-        end
-    end
-    # Set the position to +p+.  +p+ can be numeric (from #pos) or from #position.
-    def position=(p)
-        if p.respond_to?(:pos)
-            position?(p) or raise(TypeError,"invalid position #{p}")
-            self.pos = p.pos
-        else
-            self.pos = p                                               
-        end
-    end
-    # Without a code block, this queries whether a particular #position +p+ is
-    # valid (is a child) or determines if there is any outstanding #position
-    # (when +p+=+nil+).
-    #
-    # With a code block, it sets optionally sets the #position= +p+ and
-    # and executes the code.  If the result of the code is false/nil, it will
-    # return to the original #position (intially saved).  Otherwise it will stay where the code
-    # left it.  The result of the code block is returned.  This is useful when
-    # you want the cursor to stay for a pass/match, and return to try something
-    # else for a fail/mismatch.
-    def position?(p=nil,&code) # :yield:
-        if code
-            start = position
-            self.position = p if p
-            ret = code[]
-            self.position = start if not ret
-            start.close
-            ret
-        elsif p
-            i = @positions.rindex(p.object_id >> 1)
-            if not i
-                return(true) if p.object_id==self.object_id
-                return(nil)
-            end
-            if p.closed?
-                @positions.slice!(i)
-                nil
-            else
-                true
-            end
-        else
-            while @positions.size>0
-                return(true) if not ObjectSpace._id2ref(@positions[0] << 1).closed?
-                @positions.shift
-            end
-        end
-    end
-    # Either discard/close the given #position +p+ or discard/close every child #position (+p+=+nil+).
-    def position!(p=nil)
-        if p
-            p.close
-            position?(p) && raise(RuntimeError,"#{p} didn't seem to close")
-        else
-            @positions.each { |p| ObjectSpace._id2ref(p << 1).close }
-            @positions = []
-        end
-        self
-    end
-    # Close the cursor.  This will also close every child #position.
-    def close
-        position!
-        # this should make just about any operation fail
-        instance_variables.each { |v| remove_instance_variable(v) }
-        nil
-    end
-    # Is the cursor closed?
-    def closed?
-        instance_variables.size==0
-    end
-    # Are we at the end?  Or beginning if +reverse+.
-    def eof?(reverse=false)
-        flags = After|Ignore
-        flags |= Reverse if reverse
-        not get(nil,flags)
-    end
-    alias_method :eof, :eof?
-    # Is +other+ (either #pos or #position) at the same location as the cursor?
-    def ==(other)
-        if other.respond_to?:pos
-            position?(other) or return(false)
-            other = other.pos
-        else
-            other = pos(other)
-        end
-        pos==other
-    end
-    alias_method :===, :==
-    # Compare +other+ (from #pos or #position) to the current position.  +1
-    # for the self is after, -1 for self being before, and 0 for it being at
-    # same location.
-    def <=>(other)
-        if other.respond_to?:pos
-            position?(other) or raise(TypeError,"invalid position #{p}")
-            other = other.pos
-        else
-            other = pos(other)
-        end
-        pos<=>other
-
-    end
-    # If +other+ is from #position, this will return the distance (number
-    # or elements) from +other+ to +self+.  This can be +, -, or 0.
-    # If +other+ is numeric, this returns a new position that is decreased by
-    # this amount (positive: before, negative: after).  Otherwise, it is taken to
-    # be a +len+ for #get (going backward).
-    def -(other)
-        if other.respond_to?:pos
-            position?(other) or raise(TypeError,"invalid position #{p}")
-            pos.to_i-other.pos.to_i
-        elsif other.kind_of?Numeric
-            if other>0
-                position { get(other,Prev|Ignore);position }
-            elsif other<0
-                position { get(other,Next|Ignore);position }
-            else
-                position
-            end
-        else
-            position { get(other,Prev|Ignore);position }
-        end
-    end
-    # If +other+ is numeric, this returns a new position that is increased by
-    # this amount (positive: before, negative: after).  Otherwise, it is taken to
-    # be a +len+ for #get (going forward).
-    def +(other)
-        if other.kind_of?Numeric
-            if other>0
-                position { get(other,Next|Ignore);position }
-            elsif other<0
-                position { get(other,Prev|Ignore);position }
-            else
-                position
-            end
-        else
-            position { get(other,Next|Ignore);position }
-        end
-    end
-    # Returns a Reversed cursor.
-    def -@
-        Cursor::Reversed.new(self)
-    end
-    # Increments the cursor by +len+ (same +len+ of #get - defaults to one element)
-    # Returns +nil+ at the end and self otherwise.
-    def succ!(len=nil); get(len,Next|Ignore) && self; end
-    # Decrements the cursor by +len+ (same +len+ of #get - defaults to one element)
-    # Returns +nil+ at the beginning and self otherwise.
-    def pred!(len=nil); get(len,Prev|Ignore) && self; end
-    # Similar to #succ! except a new #position is returned instead of
-    # modifying the current.
-    def succ(len=nil); position { get(len,Next|Ignore) && position }; end
-    # Similar to #pred! except a new #position is returned instead of
-    # modifying the current.
-    def pred(len=nil); position { get(len,Prev|Ignore) && position }; end
-    # Go to the beginning
-    def first!; get(0,Prev|Ignore); self; end
-    # Go to the end
-    def last!; get(0,Next|Ignore); self; end
-    # Similar to #first! except a new #position is returned instead of
-    # modifying the current.
-    def first; position { get(0,Prev|Ignore);position }; end
-    # Similar to #last! except a new #position is returned instead of
-    # modifying the current.
-    def last; position { get(0,Next|Ignore);position }; end
-    alias_method :begin, :first
-    alias_method :begin!, :first!
-    alias_method :end, :last
-    alias_method :end!, :last!
-    # Returns the number of elements.
-    def size
-        l1 = position { get(0,Next|Ignore) } || 0
-        l0 = position { get(0,Prev|Ignore) } || 0
-        l0+l1
-    end
-    alias_method :length, :size
-    # Determines whether there is anything before or after the cursor.
-    def empty?
-        get(nil,After |Ignore)&&(return(false)) ||
-        get(nil,Before|Ignore)&&(return(false)) ||
-        true
-    end
-    # Removes all elements and returns the number removed
-    def clear
-        (get(0,Next|Delete|Ignore)||0)+(get(0,Prev|Delete|Ignore)||0)
-    end
-    # Appends a single element at the end
-    def << (value)
-        get(0,Next|Ignore)
-        put(value,Next|Single)
-    end
-    # Prepends a single element at the beginning
-    def >> (value)
-        get(0,Prev|Ignore)
-        put(value,Prev|Single)
-    end
-    protected
-    def _index(index,len,flags) # :nodoc:
-        if index.respond_to?:exclude_end?
-            len = (index.last-index.first).to_i
-            if index.exclude_end?
-                len = len.ceil
-            else
-                len = len.to_i+1
-            end
-            index = index.first
-            index += len if flags&Reverse != 0
-            len = 0 if len<0
-        elsif len.kind_of?Numeric
-            if len<0
-                flags ^= Reverse
-                len = -len
-            end
-            len = len.to_i
-        end
-        self.position = index if index
-        [len,flags]
-    end
-    public
-    # Provides random access for the cursor like what is in Array/String.
-    # +index+ can be +nil+ (start at the current location), a numeric (possibly range)
-    # (just like Array/String), and even a range from start to end cursors.
-    # +len+ can be positive/0 (just like in Array/String), negative (goes
-    # in reverse), or even a +data_class+ (passed to #get).
-    # +flags+ can take on the same things they can in get.  A code block can
-    # be given just like in #get.
-    def [](index=nil,len=nil,flags=After,&more) # :yield: len
-        len,flags = _index(index,len,flags)
-        return(data_class.new) if len==0
-        get(len,flags,&more)
-    end
-    # Random access store like in Array/String.  Accepts the same enhancements
-    # for index, len, and flags as #[] does.
-    def []=(*args) # :args: (index=nil,len=nil,flags=After,value)
-        value = args.slice!(-1)
-        index,len,flags = *args
-        flags ||= After
-        len,flags = _index(index,len,flags)
-        if not len
-            ret = put(value,flags|Single)
-        else
-            flags &= ~Single
-            if len==0
-                flags &= ~Read
-                ret = put(value,flags|Insert)
-            elsif value.size==len
-                ret = put(value,flags&~Insert)
-            else
-                ret = get(len,flags^Ignore|Delete)
-                put(value,flags|Insert)
-            end
-        end
-        if flags&Read != 0
-            ret
-        else
-            value
-        end
-    end
-    alias_method :slice, :[]
-    # Random access slice! like in Array/String.  Accepts the same enhancements
-    # for index, len, flags, and code block as #[] does (same except +Delete+
-    # bit is set).
-    def slice!(index=nil,len=nil,flags=After,&more) # :yield: len
-        len,flags = _index(index,len,flags)
-        return(data_class.new) if len==0
-        get(len,flags|Delete,&more)
-    end
-    # Performs each just to make this class Enumerable.  Accepts the same enhancements
-    # for index, len, and flags as #[] does.  +index+ defaults to nil which
-    # starts where the cursor (like IO) as opposed to the beginning (like Array).
-    # The cursor will be left at the end (or beginning if the +Reverse+ flags bit is use).
-    # nil is returned (or the break value if the code does a break).
-    def each(index=nil,len=nil,flags=Next,&code) # :yield: value
-        len,flags = _index(index,len,flags)
-        raise if len==0 or flags&Hold != 0
-        continue = true
-        loop do
-            value = get(len,flags) { continue = nil }
-            if not continue
-                code[value] if len and value
-                break
-            end
-            code[value]
-        end
-    end
-    # copies data from +index+ to the current location.  Uses #[] and #[]=
-    # to accomplish the copy so that all of those options are available.
-    # +pflags are used for the put and +gflags+ for the get.
-    def copy_from(index,len=nil,pflags=After,gflags=After)
-        gflags &= ~Ignore
-        if len
-            pflags |= Single
-        else
-            pflags &= ~Single
-        end
-        self[nil,nil,pflags] = self[index,len,gflags]
-    end
-    # copies data from the current location to +index+.  Uses #[] and #[]=
-    # to accomplish the copy so that all of those options are available.
-    # +pflags are used for the put and +gflags+ for the get.
-    def copy_to(index,len=nil,pflags=After,gflags=After)
-        gflags &= ~Ignore
-        if len
-            pflags |= Single
-        else
-            pflags &= ~Single
-        end
-        self[index,nil,pflags] = self[nil,len,gflags]
-    end
-
-    # Objects in this class are mainly used to simply mark/remember the location
-    # of a parent cursor.  But, this class also has the fully functionality of the
-    # parent.  When this child want to do an operation, it uses the parent to
-    # do it and returns the parent to where it was.  Derived classes where the
-    # underlying data is random access may be able to implement this class to
-    # directly access the data rather than go through the parent.
-    class Position < Cursor
-        def initialize(parent,p)
-            @parent = parent
-            @pos = p
-        end
-        def data_class
-            @parent.data_class
-        end
-        def get(*args,&more) # :args: (len=nil, flags=Next) { |len| ... }
-            @parent.pos(@pos) {
-                ret = @parent.get(*args,&more)
-                @pos = @parent.pos
-                ret
-            }
-        end
-        def put(*args,&more) # :args: (value, flags=Next) { |len| ... }
-            @parent.pos(@pos) { 
-                ret = @parent.put(*args,&more)
-                @pos = @parent.pos
-                ret
-            }
-        end
-        def position(p=nil,&code) # :yield:
-            if p or code
-                super(p,&code)
-            else
-                @parent.pos(@pos) { @parent.position }
-            end
-        end
-        def position?(p=nil,&code) # :yield:
-            if code
-                super(p,&code)
-            else
-                @parent.position?(p)
-            end
-        end
-        def position!(p=nil)
-            if p
-                @parent.position!(p)
-            else
-                nil
-            end
-        end
-        def close
-            parent = @parent
-            super
-            parent.position?(self)
-        end
-    end
-
-    # This class can be used to reverse the direction of operations on a given
-    # cursor.  It operates on the given cursor directly moving it around.
-    class Reversed < Cursor
-        def initialize(cursor)
-            super()
-            @cursor = cursor
-        end
-        def data_class
-            @cursor.data_class
-        end
-        def get(len=nil,flags=Next,&more) # :yield: len
-            @cursor.get(len,flags^Reverse)
-        end
-        def put(value,flags=Next,&more) # :yield: len
-            @cursor.put(value,flags^Reverse,&more)
-        end
-        # Every +pos+ returned here is negative (-0.1: end, -N: beginning)
-        # unlike the base class.
-        def pos(p=nil,&code) # :yield:
-            if p or code
-                super(*args,&code)
-            else
-                p = @cursor.pos
-                p = -p
-                p = -0.1 if p==0
-                p
-            end
-        end
-        def pos=(p)
-            p = -p
-            p = -0.1 if p==0
-            p = (@cursor.pos = p)
-            p = -p
-            p = -0.1 if p==0
-            p
-        end
-    end
-
-    # This class is used to test the base class by overriding as few methods
-    # as possible.
-    class Test < Cursor
-        def initialize(data=[],index=0)
-            super()
-            @data = data
-            @pos = index
-            @data_class = (@data.respond_to?:data_class) ?
-                @data.data_class : @data.class
-        end
-        def data_class
-            @data_class
-        end
-        def _delete1(flags,&more) # :yield: len=1
-            if flags&Reverse != 0
-                @pos>0 && (@pos -= 1)
-            else
-                @pos<@data.size
-            end or return(
-                if ret = more&&more[1]
-                    if flags&Ignore != 0
-                        ret = true
-                    else
-                        ret,=ret
-                        ret
-                    end
-                end
-            )
-            if flags&Ignore != 0
-                @data[@pos,1] = @data_class.new
-                1
-            else
-                @data.slice!(@pos)
-            end
-        end
-        def _insert1(value,flags)
-            @data[@pos,0] = (@data_class.new << value)
-            @pos += 1 if flags&Reverse == 0
-        end
-    end
-
-    # This class puts a cursor on an Array or String.
-    class Indexed < Cursor
-        def initialize(data=[],index=0)
-            super()
-            @data = data
-            @pos = index
-            @data_class = (@data.respond_to?:data_class) ?
-                @data.data_class : @data.class
-        end
-        def data_class
-            @data_class
-        end
-        def _delete1(flags,&more) # :yield: len=1
-            if flags&Reverse != 0
-                @pos>0 && @pos -= 1
-            else
-                @pos<@data.size
-            end or return(
-                if ret = more&&more[1]
-                    if flags&Ignore != 0
-                        ret = true
-                    else
-                        ret,=ret
-                        ret
-                    end
-                end
-            )
-            if flags&Ignore != 0
-                @data[@pos,1] = @data_class.new
-                true
-            else
-                @data.slice!(@pos)
-            end
-        end
-        def _insert1(value,flags)
-            @data[@pos,0] = (@data_class.new << value)
-            @pos += 1 if flags&Reverse == 0
-        end
-    end
-
-    # This class treats an IO (or StringIO) as a Cursor.  An IO is already
-    # like a Cursor, but doesn't have as robust an interface.  Deleting and
-    # inserting is a slow/painful process.
-    class IO < Cursor
-        def initialize(io=StringIO.new)
-            super()
-            @io = io
-        end
-        def data_class
-            String
-        end
-        def _delete1(flags,&more) # :yield: len=1
-            if flags&Reverse != 0
-                begin
-                    @io.seek(-1,::IO::SEEK_CUR)
-                    ret = @io.getc
-                rescue
-                    ret = nil
-                end
-            else
-                ret = @io.getc
-            end or return(
-                if ret = more&&more[1]
-                    if flags&Ignore != 0
-                        ret = true
-                    else
-                        ret,=ret
-                        ret
-                    end
-                end
-            )
-            ret = true if flags&Ignore != 0
-            after = 0
-            while c = @io.getc
-                after += 1
-                @io.seek(-2,::IO::SEEK_CUR)
-                @io.putc(c)
-                @io.seek(+1,::IO::SEEK_CUR)
-            end
-            @io.seek(-1,::IO::SEEK_CUR)
-            @io.truncate(@io.pos)
-            @io.seek(-after,::IO::SEEK_CUR) if after>0
-            ret
-        end
-        def _insert1(value,flags)
-            after = 0
-            while c = @io.getc
-                after += 1
-                @io.seek(-1,::IO::SEEK_CUR)
-                @io.putc(value)
-                value = c
-            end
-            @io.putc(value)
-            after += 1 if flags&Reverse != 0
-            @io.seek(-after,::IO::SEEK_CUR) if after>0
-            nil
-        end
-        def _get1(flags,&more) # :yield: len=1
-            if flags&Reverse != 0
-                begin
-                    @io.seek(-1,::IO::SEEK_CUR)
-                rescue
-                    if ret = more&&more[1]
-                        ret,=ret
-                        if flags&Hold != 0
-                            flags ^= Hold
-                            flags ^= Reverse
-                        end
-                        _insert(flags,ret)
-                        ret = true if flags&Ignore != 0
-                    end
-                    return(ret)
-                end
-                if flags&Ignore != 0
-                    @io.seek(+1,::IO::SEEK_CUR) if flags&Hold != 0
-                    ret = true
-                else
-                    ret = @io.getc
-                    @io.seek(-1,::IO::SEEK_CUR) if flags&Hold == 0
-                end
-            else
-                if not ret = @io.getc
-                    if ret = more&&more[1]
-                        ret,=ret
-                        @io.putc(ret)
-                        @io.seek(-1,::IO::SEEK_CUR) if flags&Hold != 0
-                        ret = true if flags&Ignore != 0
-                    end
-                    return(ret)
-                end
-                @io.ungetc(ret) if flags&Hold != 0
-                ret = true if flags&Ignore != 0
-            end
-            ret
-        end
-        def _put1(value,flags,&more) # :yield: len=1
-            if flags&Reverse != 0
-                begin
-                    @io.seek(-1,::IO::SEEK_CUR)
-                rescue
-                    if ret = more&&more[1]
-                        if flags&Read == 0
-                            ret = true
-                        else
-                            ret,=ret
-                        end
-                    end
-                    if flags&Hold != 0
-                        flags ^= Hold
-                        flags ^= Reverse
-                    end
-                    _insert1(value,flags)
-                    return(ret)
-                end
-                if flags&Read != 0
-                    ret = @io.getc
-                    @io.ungetc(ret)
-                else
-                    ret = true
-                end
-                @io.putc(value)
-                if flags&Hold == 0
-                    @io.seek(-1,::IO::SEEK_CUR)
-                end
-            else
-                if flags&Read != 0
-                    if not ret = @io.getc
-                        if ret = more&&more[1]
-                            ret, = ret
-                        end
-                    else
-                        @io.ungetc(ret)
-                    end
-                elsif @io.eof?
-                    ret = more&&more[1]&&true
-                else
-                    ret = true
-                end
-                @io.putc(value)
-                @io.seek(-1,::IO::SEEK_CUR) if flags&Hold != 0
-            end
-            ret
-        end
-        def close
-            @io.close
-            super                
-        end
-    end
-
-    # This Cursor class uses an Array/String for data before the cursor
-    # and another one for data after the cursor.  The result of this is that
-    # data is only deleted/inserted at the end of these 2.  Because of that
-    # most operations have similar expense and are linear with respect to the
-    # number of elements being moved, inserted, deleted, replaced, etc.
-    class Buffer < Cursor
-        def initialize(before=[],after=before.class.new)
-            super()
-            @before = before
-            @after = after
-            @data_class = (@before.respond_to?:data_class) ?
-                @before.data_class : @before.class
-        end
-        def data_class
-            @data_class
-        end
-        def _delete1(flags,&more) # :yield: len=1
-            data = (flags&Reverse != 0) ? @before : @after
-            data.size>0 or return(
-                if ret = more&&more[1]
-                    if flags&Ignore != 0
-                        ret = true
-                    else
-                        ret,=ret
-                        ret
-                    end
-                end
-            )
-            if flags&Ignore != 0
-                data[-1,1] = @data_class.new
-                true
-            else
-                data.slice!(-1)
-            end
-        end
-        def _insert1(value,flags)
-            data = (flags&Reverse != 0) ? @after : @before
-            data << value
-        end
-    end
-
-    # This class gives unidirectional cursors (i.e. IO pipes) some
-    # bidirectional capabilities.  An input cursor and/or an output cursor
-    # can be specified.  The #position, #position?, and #position! methods are
-    # used to control buffering.  Full cursor capability (limited by the buffer
-    # cursor) is accessible starting from the first #position.  When the end of
-    # the buffer is reached more data is read from the input cursor (if not nil) using #get .  When no
-    # #position is outstanding, everything before the buffer cursor is written
-    # to the output cursor (if not nil) using #put.  If the cursor is attempted
-    # to be moved before the buffer, the output cursor is read in reverse.
-    class Buffered < Cursor
-        def initialize(input,output=nil,buffer=Buffer.new((input||output).data_class.new))
-            @input = input
-            @output = output
-            @buffer = buffer
-            @offset = 0
-            super()
-        end
-        def data_class
-            @buffer.data_class
-        end
-        def get(len=nil,flags=Next,&more) # :yield: len
-            value = @buffer.get(len,flags) { |len|
-                if flags&Reverse != 0
-                    if @offset==0
-                        more&&more[len]
-                    else
-                        v = @output.get(len,Prev,&more)
-                        @offset -= v.size if v
-                        v
-                    end
-                elsif @input
-                    @input.get(len,Next,&more)
-                else
-                    more&&more[len]
-                end
-            }
-            if not position?
-                if output_value = @buffer.get(0,Prev|Delete)
-                    @offset += output_value.size
-                    @output.put(output_value,Next) if @output
-                end
-            end
-            value
-        end
-        def put(value,flags=Next,&more) # :yield: len
-            value0 = @buffer.put(value,flags) { |len|
-                if flags&Reverse != 0
-                    if @offset==0
-                        more&&more[len]
-                    else
-                        v = @output.get(len,Prev,&more)
-                        @offset -= v.size if v
-                        v
-                    end
-                elsif @input
-                    @input.get(len,Next,&more)
-                else
-                    more&&more[len]
-                end
-            }
-            if not position?
-                if output_value = @buffer.get(0,Prev|Delete)
-                    @offset += output_value.size
-                    @output.put(output_value,Next) if @output
-                end
-            end
-            value0
-        end
-        def pos(p=nil,&code) # :yield:
-            if p or code
-                super(*args,&code)
-            else
-                @buffer.pos+@offset
-            end
-        end
-        def pos=(p)
-            if p<0
-                @buffer.pos = p
-            else
-                @buffer.pos = p-@offset
-            end
-        end
-    end
-
-end
-
-
+#!/bin/env ruby
+# = cursor.rb - external iterators with capabilities like a text editor cursor
+# $Id: cursor.rb,v 1.8 2005/05/25 16:12:22 eric_mahurin Exp $
+# Author::  Eric Mahurin (Eric under Mahurin at yahoo dot com)
+# License:: Ruby license
+# Home::    http://rubyforge.org/projects/cursor
+
+# An object in this Cursor class can be best thought of as a cursor in a text
+# editor.  Many of the same operations apply - insert, delete, replace, copy,
+# paste, move, goto begin/end, mark position, goto mark, etc.  Unlike a
+# text editor, this class can operate on variety of data, not just characters
+# and strings.  It is up to the derived classes to deal with what type of data
+# is stored (i.e. characters, arbitrary array objects) and how it is stored (in
+# an Array, String, IO, mapping to another Cursor, etc).
+class Cursor
+
+    include Comparable
+    include Enumerable
+
+    # Operate on data before the cursor rather than after
+    Reverse = 1
+    # Hold position - do the operation and come back
+    Hold = 2
+    # Just count the elements from get/delete instead of returning their value
+    Ignore = 4
+    # Read the data being replaced using put and return it (instead of the count)
+    Read = 4
+    # Delete instead of retrieve elements (used with get)
+    Delete = 8
+    # Insert instead of replace elements (used with put)
+    Insert = 8
+    # Put a single element instead of a sequence (needed when it looks like a sequence)
+    Single = 16
+    # Operate on what follows the cursor and then move foward
+    Next = 0
+    # Operate on what precedes the cursor and then move backward
+    Prev = Reverse
+    # Operate on what follows the cursor and hold position
+    After = Hold
+    # Operate on what precedes the cursor and hold position
+    Before = Reverse|Hold
+    # #pos for the beginning (positive zero)
+    Begin = +0
+    # #pos for the end (negative zero)
+    End = -0.1
+    # #get +len+ for getting the rest of the elements
+    Rest = +1.0/0
+
+    protected
+    # Delete one element at the cursor and return it.  The observed bits in +flags+
+    # are +Reverse+ (delete before the cursor instead of after) and +Ignore+
+    # (return true instead of the deleted element).  When the cursor is at the end (or beginning),
+    # either nil or the code block result is returned (see #get).  
+    # <b>This method must be overriden
+    # in a derived class</b>.
+    def _delete1(flags,&more) # :yield: l=1
+        raise(NotImplementedError)
+    end
+    # Insert one element at the cursor.  Only the +Reverse+ bit
+    # is observed in +flags+.  nil should be returned.  <b>This method must be overriden
+    # in a derived class</b>.
+    def _insert1(value,flags)
+        raise(NotImplementedError)
+    end
+    # Get an element at the cursor.  The observed bits in +flags+ are +Reverse+
+    # (read before instead of after the cursor), +Hold+ (don't move the
+    # cursor), and +Ignore+ (just return +true+ instead of the value).  When the
+    # cursor is at the end (or beginning), either nil or the code block result
+    # is returned (see #get).
+    def _get1(flags,&more) # :yield: l=1
+        value = _delete1(flags&~Ignore) { |l| more&&more[l] || return }
+        if (flags&Hold).nonzero?
+            flags ^= Hold
+            flags ^= Reverse
+        end
+        _insert1(value,flags)
+        (flags&Ignore).nonzero? ? true : value
+    end
+    # Put an element at the cursor.  The observed bits in +flags+ are +Reverse+
+    # (put before instead of after the cursor), +Hold+ (don't move the
+    # cursor), and +Read+ (read and return what is being replaced instead of
+    # just returning +true+).  When the cursor is at the end (or beginning),
+    # either nil or the code block result is returned (see #get).
+    # The value is inserted at that point when that happens.
+    def _put1(value,flags,&more) # :yield: l=1
+        value0 = _delete1(flags^Read,&more)
+        if (flags&Hold).nonzero?
+            flags ^= Hold
+            flags ^= Reverse
+        end
+        _insert1(value,flags)
+        value0
+    end
+
+    public
+    # Create a cursor.
+    def initialize
+        @positions = []
+    end
+    # Return the class used for passing/returning a sequence of elements.  This
+    # class must behave as a String or an Array ([], []=, slice, slice!, length).
+    # The default in the base class is Array.
+    def data_class
+        Array
+    end
+    # Get a single element or a sequence of them.
+    #
+    # +len+ can be +nil+ (get one element - like IO#getc), a non-negative number (get a
+    # sequence of that many elements - like IO#read), a negative number (get that many in reverse), 
+    # or a termination sequence (get a sequence up until it finds a match to +len+ - like IO#gets).
+    #
+    # The observed bits in +flags+ are +Reverse+
+    # (read before instead of after the cursor), +Hold+ (don't move the
+    # cursor), +Ignore+ (just return +true+ or a count instead of the value),
+    # and +Delete+ (delete the element or sequence while retrieving it).
+    #
+    # If there is anything left, either nil (no code block) or the result from code block is
+    # returned.  This code block could set some variable(s) to signify it
+    # is done or return data from some other source to make it look as though
+    # it is not done.  When returning more data, it should return it in a
+    # String or Array of up to +l+ elements.
+    def get(len=nil,flags=Next,&more) # :yield: l
+        g = (flags&Delete).nonzero? ? :_delete1 : :_get1
+        return(__send__(g,flags,&more)) if not len
+        if (flags&Hold).nonzero? and (flags&Delete).zero?
+            flags ^= Hold
+            position { get(len,flags,&more) }
+        elsif len.respond_to?:zero?
+            if len<0
+                flags ^= Reverse
+                len = -len
+            end
+            len -= 1
+            if (flags&Ignore).nonzero?
+                len1 = 0
+                while len>=len1
+                    __send__(g,flags) { |l|
+                        more&&more[l] ||
+                        (return(len1.zero? ? nil : len1))
+                    }
+                    len1 += 1
+                end
+                len1
+            else
+                value = data_class.new
+                while len>=value.size
+                    v = __send__(g,flags&~Ignore) { |l|
+                        more&&more[l] || (return(
+                            value.size.zero? ? nil :
+                            (flags&Reverse).nonzero? ? value.reverse : value
+                        ))
+                    }
+                    value << v
+                end
+                (flags&Reverse).nonzero? ? value.reverse : value
+            end
+        else
+            if (flags&Ignore).nonzero?
+                value = get(len,flags^Ignore,&more)
+                return(value&&value.size)
+            end
+            value = data_class.new
+            if (flags&Reverse).nonzero?
+                step = -1
+                start = len.size-1
+                finish = -1
+            else
+                step = +1
+                start = 0
+                finish = len.size
+            end
+            i = start
+            loop do
+                v = __send__(g,flags) { |l|
+                    more&&more[l] || begin
+                        value = value.reverse if (flags&Reverse).nonzero?
+                        value = nil if value.size.zero?
+                        return
+                    end
+                }
+                value << v
+                if v==len[i]
+                    i += step
+                    if i==finish
+                        value = value.reverse if (flags&Reverse).nonzero?
+                        return(value)
+                    end
+                else
+                    i = start
+                end
+            end
+        end
+    end
+    # Put a single element or a sequence of them at the cursor.
+    #
+    # The observed bits in +flags+ are +Reverse+
+    # (read before instead of after the cursor), +Hold+ (don't move the
+    # cursor), +Read+ (return the what is overwritten instead of +true+ or a count),
+    # +Insert+ (insert rather than replace +value+), and +Single+ (force +value+
+    # to be treated as a single element rather than a sequence).
+    #
+    # When the cursor is at the end (or beginning),
+    # either nil or the code block result is returned (see #get).
+    # The value is inserted at that point when that happens.
+    def put(value,flags=Next,&more) # :yield: l
+        if (flags&Single).nonzero? or not data_class>=value.class
+            if (flags&Insert).nonzero?
+                if (flags&Hold).nonzero?
+                    flags ^= Hold
+                    flags ^= Reverse
+                end
+                return(_insert1(value,flags,&more))
+            else
+                return(_put1(value,flags,&more))
+            end
+        end
+        if (flags&Insert).nonzero?
+            flags |= Single
+            if (flags&Hold).nonzero?
+                flags ^= Hold
+                flags ^= Reverse
+            end
+            if (flags&Reverse).nonzero?
+                start = value.size-1
+                finish = 0
+                step = -1
+            else
+                start = 0
+                finish = value.size-1
+                step = +1
+            end
+            start.step(finish,step) do |i|
+                _insert1(value[i],flags)
+            end
+            nil
+        elsif (flags&Hold).nonzero?
+            flags ^= Hold
+            position { put(value,flags,&more) }
+        else
+            flags |= Single
+            if (flags&Reverse).nonzero?
+                start = value.size-1
+                finish = 0
+                step = -1
+            else
+                start = 0
+                finish = value.size-1
+                step = +1
+            end
+            if (flags&Read).nonzero?
+                value0 = data_class.new
+                replacing = true
+                start.step(finish,step) do |i|
+                    v = _put1(value[i],flags) { |l|
+                        replacing = more&&more[l]
+                    }
+                    value0 << v if replacing
+                end
+                if value0.size.zero?
+                    nil
+                elsif step<0
+                    value0.reverse
+                else
+                    value0
+                end
+            else
+                len0 = 0
+                replacing = true
+                start.step(finish,step) do |i|
+                    _put1(value[i],flags) { |l|
+                        replacing = more&&more[l]
+                    }
+                    len0 += 1 if replacing
+                end
+                if len0.zero?
+                    nil
+                else
+                    len0
+                end
+            end
+        end
+    end                                                                                      
+    # This will return a numeric position.  When not +reverse+,
+    # this numeric position is the number of elements from the beginning (0 is at the beginning).  With
+    # +reverse+ it is negative and the number of elements from the end (-0.1 is at the end).
+    def pos(reverse=false,&code) # :yield:
+        flags = (reverse ? Prev : Next)|Ignore
+        ref = reverse ? End : Begin
+        p = get(Rest,flags^Reverse) or return(ref)
+        get(p,flags)==p or raise(IndexError,"couldn't get back to where we were: #{p}")
+        p = reverse ? -p : p
+        p+ref.to_i
+    end
+    # Returns #pos.to_i
+    def to_i
+        pos.to_i
+    end
+    # Returns "pos=#pos.to_s" followed by what's in prop in a reasonable format.
+    def to_s
+        s = "pos=#{pos.to_s}"
+        p = prop
+        if not p
+        elsif p.respond_to?:members
+            p.members.each { |m| s += " #{m}=#{p[m]}" }
+        elsif p.respond_to?:keys
+            p.keys.each { |k| s += " #{k}=#{p[k]}" }
+        elsif p.respond_to?:to_a
+            s += p.to_a.join(" ")
+        else
+            s += p.to_s
+        end
+        s
+    end
+    # Set #pos to be +p+.  When +p+ is negative, it is set from the end.  
+    def pos=(p)
+        reverse = p<Begin
+        flags = (reverse ? Prev : Next)|Ignore
+        ref = reverse ? End : Begin
+        p = (p-ref).round
+        p = reverse ? -p : p
+        get(Rest,flags^Reverse)
+        p.nonzero? or return(ref)
+        p = get(p,flags) or return(ref)
+        p = reverse ? -p : p
+        p+ref.to_i
+    end
+    # Get back what was stored by #prop=.
+    def prop
+        @prop
+    end
+    # Arbitrary data may be placed in here.  It will be saved and restored by
+    # #position and friends.
+    def prop=(p)
+        @prop = p.clone if p
+    end
+    def _finalizer(id) # :nodoc:
+        i = @positions.index(id >> 1)
+        @positions.slice!(i) if i
+    end
+    protected :_finalizer
+    # These position* methods use a Cursor object (from Cursor::Position) to
+    # hold the #position rather than simply a numeric position that #pos and
+    # #pos= use.  These Cursor::Position objects hold a #pos and whatever is
+    # in #prop.  For now, the #pos in these objects do not adjust based on
+    # insertions and deletions, but that may change.  So don't count 
+    # Without +p+ or a code block, #position returns one of these objects to
+    # represent the current location of the cursor.  With +p+ or a code block,
+    # the current #position is saved, the #position is set to +p+ using
+    # #position= (if +p+), the code block is executed (or the current #position
+    # is found with no code block), and the #position is returned to where it
+    # was saved (using #position=).  The return value is the result of the code
+    # block or the #position if that was executed instead.
+    def position(p=nil,&code) # :yield:
+        if code or p
+            start = position
+            self.position = p if p
+            ret = code ? code[] : position
+            self.position = start
+            start.close
+            ret
+        else
+            p = Position.new(self,pos,prop)
+            @positions << (p.object_id >> 1)
+            ObjectSpace.define_finalizer(p,method(:_finalizer))
+            p
+        end
+    end
+    # Set the position to +p+.  +p+ can be numeric (from #pos) or from #position.
+    def position=(p)
+        if p.respond_to?(:pos)
+            position?(p) or raise(TypeError,"invalid position #{p}")
+            self.pos = p.pos
+            self.prop = p.prop
+        else
+            self.pos = p                                               
+        end
+    end
+    # Without a code block, this queries whether a particular #position +p+ is
+    # valid (is a child) or determines if there is any outstanding #position
+    # (when +p+=+nil+).
+    #
+    # With a code block, it sets optionally sets the #position= +p+ and
+    # and executes the code.  If the result of the code is false/nil, it will
+    # return to the original #position (intially saved).  Otherwise it will stay where the code
+    # left it.  The result of the code block is returned.  This is useful when
+    # you want the cursor to stay for a pass/match, and return to try something
+    # else for a fail/mismatch.
+    def position?(p=nil,&code) # :yield:
+        if code
+            start = position
+            self.position = p if p
+            ret = code[]
+            self.position = start if not ret
+            start.close
+            ret
+        elsif p
+            i = @positions.rindex(p.object_id >> 1)
+            if not i
+                return(true) if p.object_id==self.object_id
+                return(nil)
+            end
+            if p.closed?
+                @positions.slice!(i)
+                nil
+            else
+                true
+            end
+        else
+            while @positions.size>0
+                return(true) if not ObjectSpace._id2ref(@positions[0] << 1).closed?
+                @positions.shift
+            end
+        end
+    end
+    # Either discard/close the given #position +p+ or discard/close every child #position (+p+=+nil+).
+    def position!(p=nil)
+        if p
+            p.close
+        else
+            @positions.clone.each { |p| ObjectSpace._id2ref(p << 1).close }
+        end
+        self
+    end
+    # Close the cursor.  This will also close every child #position.
+    def close
+        position!
+        # this should make just about any operation fail
+        instance_variables.each { |v| remove_instance_variable(v) }
+        nil
+    end
+    # Is the cursor closed?
+    def closed?
+        instance_variables.size.zero?
+    end
+    # Are we at the end?  Or beginning if +reverse+.
+    def eof?(reverse=false)
+        not get(nil,(reverse ? Before : After)|Ignore)
+    end
+    alias eof eof?
+    # Compare +other+ (from #pos or #position) to the current position.  +1
+    # for the self is after, -1 for self being before, and 0 for it being at
+    # same location.
+    def <=>(other)
+        if other.respond_to?:pos
+            position?(other) or return(nil)
+            other = other.pos
+        end
+        other.respond_to?:zero? or return(nil)
+        pos(other<0).to_i<=>other.to_i
+    end
+    alias === ==
+    # If +other+ is from #position, this will return the distance (number
+    # or elements) from +other+ to +self+.  This can be +, -, or 0.
+    # Otherwise, a new #position is returned that is decreased by this amount
+    # (using #get).
+    def -(other)
+        if other.respond_to?:pos
+            position?(other) or return(nil)
+            other = other.pos
+            pos(other<0).to_i-other.to_i
+        elsif other.respond_to?:zero?
+            position { get(other,Prev|Ignore);position }
+        end
+    end
+    # Returns a new #position increased by +other+ (using #get).
+    def +(other)
+        position { get(other,Next|Ignore);position }
+    end
+    # Returns a Reversed cursor.
+    def reverse
+        Reversed.new(self)
+    end
+    alias -@ reverse
+    # Increments the cursor by +len+ (same +len+ of #get)
+    # Returns +nil+ at the end and self otherwise.
+    def succ!(len=nil); get(len,Next|Ignore) && self; end
+    # Decrements the cursor by +len+ (same +len+ of #get)
+    # Returns +nil+ at the beginning and self otherwise.
+    def pred!(len=nil); get(len,Prev|Ignore) && self; end
+    # Similar to #succ! except a new #position is returned instead of
+    # modifying the current.
+    def succ(len=nil); position { get(len,Next|Ignore) && position }; end
+    # Similar to #pred! except a new #position is returned instead of
+    # modifying the current.
+    def pred(len=nil); position { get(len,Prev|Ignore) && position }; end
+    # Go to the beginning
+    def begin!; get(Rest,Prev|Ignore); self; end
+    # Go to the end
+    def end!; get(Rest,Next|Ignore); self; end
+    # Similar to #first! except a new #position is returned instead of
+    # modifying the current.
+    def begin; position { get(Rest,Prev|Ignore);position }; end
+    # Similar to #last! except a new #position is returned instead of
+    # modifying the current.
+    def end; position { get(Rest,Next|Ignore);position }; end
+    # Returns the number of elements.
+    def size
+        l1 = position { get(Rest,Next|Ignore) } || 0
+        l0 = position { get(Rest,Prev|Ignore) } || 0
+        l0+l1
+    end
+    alias length size
+    # Determines whether there is anything before or after the cursor.
+    def empty?
+        get(nil,After |Ignore) and return(false)
+        get(nil,Before|Ignore) and return(false)
+        true
+    end
+    # Removes all elements and returns the number removed
+    def clear
+        (get(Rest,Next|Delete|Ignore)||0)+(get(Rest,Prev|Delete|Ignore)||0)
+    end
+    # If +obj+ is the #data_class, replace the all of the data with it.  Otherwise
+    # use #position= +obj+.  self is returned.
+    def replace(obj)
+        if data_class>=obj.class
+            clear
+            put(obj)
+        else
+            self.position = obj
+        end
+        self
+    end
+    # Get all of the data (beginning to the end)
+    def data
+        get(Rest,Prev|Ignore)
+        get(Rest,Next)
+    end
+    # Appends a single element at the end and returns self
+    def << (value)
+        get(Rest,Next|Ignore)
+        put(value,Next|Single)
+        self
+    end
+    # Prepends a single element at the beginning and returns self
+    def >> (value)
+        get(Rest,Prev|Ignore)
+        put(value,Prev|Single)
+        self
+    end
+    # like Array#first, except it takes a +len+
+    def first(len=nil)
+        get(Rest,Prev|Ignore)
+        get(len,Next)
+    end
+    # like Array#last, except it takes a +len+
+    def last(len=nil)
+        get(Rest,Next|Ignore)
+        get(len,Prev)
+    end
+    protected
+    def _index(index,len,flags) # :nodoc:
+        if index.respond_to?:exclude_end?
+            if index.first.respond_to?:zero? and (index.first<0)!=(index.last<0)
+                len = (size-index.last)-abs(index.first)
+            else
+                len = index.last-index.first
+            end
+            if index.exclude_end?
+                len = (len<0) ? len.floor : len.ceil
+            else
+                len = (len<0) ? len.to_i-1 : len.to_i+1
+            end
+            index = index.first
+            index += len if (flags&Reverse).nonzero?
+        end
+        self.position = index if index
+        [len,flags]
+    end
+    public
+    # Provides random access for the cursor like what is in Array/String.
+    # +index+ can be +nil+ (start at the current location), a numeric (possibly range)
+    # (just like Array/String), and even a range from start to end cursors.
+    # +len+ can be positive/0 (just like in Array/String), negative (goes
+    # in reverse), or even a matching sequence (passed to #get).
+    # +flags+ can take on the same things they can in get.
+    def slice(index=nil,len=nil,flags=After)
+        len,flags = _index(index,len,flags)
+        get(len,flags)
+    end
+    alias [] slice
+    alias at slice
+    # Random access slice! like in Array/String.  Accepts the same enhancements
+    # for index, len, flags, and code block as #slice does (same except +Delete+
+    # bit is set).
+    def slice!(index=nil,len=nil,flags=After)
+        len,flags = _index(index,len,flags)
+        get(len,flags|Delete)
+    end
+    # Random access store like in Array/String.  Accepts the same enhancements
+    # for index, len, and flags as #slice does.
+    def []=(*args) # :args: (index=nil,len=nil,flags=After,value)
+        value = args.slice!(-1)
+        index,len,flags = *args
+        flags ||= After
+        len,flags = _index(index,len,flags)
+        if not len
+            ret = put(value,flags|Single)
+        else
+            flags &= ~Single
+            ret = get(len,flags^Ignore|Delete)
+            put(value,flags|Insert)
+        end
+        if (flags&Read).nonzero?
+            ret
+        else
+            value
+        end
+    end
+    # copies data from one place to another.  The default from and to indices are
+    # nil which is the current cursor location.  All of the options of #slice
+    # are available for the indices, +len+, and flags.
+    def copy(from_index=nil,to_index=nil,len=nil,from_flags=After,to_flags=After)
+        if not to_index
+            value = position { self[from_index,len,from_flags] }
+            self[to_index,len,to_flags] = value
+        elsif not from_index
+            value = self[from_index,len,from_flags]
+            position { self[to_index,len,to_flags] = value }
+        else
+            self[to_index,len,to_flags] = self[from_index,len,from_flags]
+        end
+    end
+    # Performs each just to make this class Enumerable.  Accepts the same enhancements
+    # for index, len, and flags as #slice does.
+    # The cursor will be left at the end (or beginning if the +Reverse+ flags bit is use).
+    # nil is returned (or the break value if the code does a break).
+    def each(index=Begin,len=nil,flags=Next,&code) # :yield: value
+        len,flags = _index(index,len,flags)
+        continue = true
+        loop do
+            value = get(len,flags) { continue = nil }
+            if not continue
+                code[value] if len and value
+                break
+            end
+            code[value]
+        end
+    end
+    # Same as #each except go in Reverse.
+    def reverse_each(index=End,len=nil,flags=Prev,&code) # :yield: value
+        each(index,len,flags,&code)
+    end
+    # Performs an in-place collect! (like Array#collect!).  Accepts the same enhancements
+    # for index, len, and flags as #slice does.
+    # The cursor will be left at the end (or beginning if the +Reverse+ flags bit is use).
+    # nil is returned (or the break value if the code does a break).
+    def collect!(index=Begin,len=nil,flags=Next,&code) # :yield: value
+        len,flags = _index(index,len,flags)
+        continue = true
+        loop do
+            value = get(len,flags|Delete) { continue = nil }
+            if not continue
+                if len and value
+                    value = code[value]
+                    put(value,flags|Insert) if value
+                end
+                break
+            end
+            value = code[value]
+            put(value,flags|Insert|(len ? 0 : Single)) if value || !len
+        end
+    end
+    alias map! collect!
+    # Performs an in-place reject! (like Array#reject!).  Accepts the same enhancements
+    # for index, len, and flags as #slice does.
+    # The cursor will be left at the end (or beginning if the +Reverse+ flags bit is use).
+    # nil is returned (or the break value if the code does a break).
+    def reject!(index=Begin,len=nil,flags=Next,&code) # :yield: value
+        len,flags = _index(index,len,flags)
+        continue = true
+        ret = nil
+        loop do
+            value = get(len,flags) { continue = nil }
+            if not continue
+                if len and value
+                    if code[value]
+                        get(len,flags^Reverse|Delete|Ignore)
+                        ret = self
+                    end
+                end
+                break
+            end
+            if code[value]
+                get(len,flags^Reverse|Delete|Ignore)
+                ret = self
+            end
+        end
+        ret
+    end
+    
+    
+    # Objects in this class are mainly used to simply mark/remember the location
+    # of a parent cursor.  But, this class also has the fully functionality of the
+    # parent.  When this child want to do an operation, it uses the parent to
+    # do it and returns the parent to where it was.  Derived classes where the
+    # underlying data is random access may be able to implement this class to
+    # directly access the data rather than go through the parent.
+    class Position < Cursor
+        def initialize(parent,pos,prop)
+            @parent = parent
+            @pos,self.prop = pos,prop
+        end
+        def data_class
+            @parent.data_class
+        end
+        protected
+        def _pos(&code) # :nodoc:
+            start = @parent.pos,@parent.prop
+            @parent.pos,@parent.prop = @pos,self.prop
+            ret = code[]
+            @pos,self.prop = @parent.pos,@parent.prop
+            @parent.pos,@parent.prop = start
+            ret
+        end
+        public
+        def get(len=nil,flags=Next,&more) # :yield: l
+            _pos { @parent.get(len,flags,&more) }
+        end
+        def put(value,flags=Next,&more) # :yield: l
+            _pos { @parent.put(value,flags,&more) }
+        end
+        def pos(reverse=false)
+            if reverse
+                super(reverse)
+            else
+                @pos
+            end
+        end
+        def position(p=nil,&code) # :yield:
+            if p or code
+                super(p,&code)
+            else
+                _pos { @parent.position }
+            end
+        end
+        def position?(p=nil,&code) # :yield:
+            if code
+                super(p,&code)
+            else
+                @parent.position?(p)
+            end
+        end
+        def position!(p=nil)
+            if p
+                @parent.position!(p)
+            else
+                nil
+            end
+        end
+        def close
+            parent = @parent
+            super()
+            parent.position?(self)
+        end
+    end
+
+    # This class can be used to reverse the direction of operations on a given
+    # cursor.  It operates on the given cursor directly moving it around.
+    class Reversed < Cursor
+        def initialize(cursor)
+            super()
+            @cursor = cursor
+        end
+        def data_class
+            @cursor.data_class
+        end
+        def get(len=nil,flags=Next,&more) # :yield: l
+            @cursor.get(len,flags^Reverse)
+        end
+        def put(value,flags=Next,&more) # :yield: l
+            @cursor.put(value,flags^Reverse,&more)
+        end
+        def pos(reverse=false,&code) # :yield:
+            if code
+                super(!reverse)
+            else
+                p = @cursor.pos(!reverse)
+                p = -p+Begin+End
+            end
+        end
+        def pos=(p)
+            reverse = p<Begin
+            p = -p+Begin+End
+            p = (@cursor.pos = p)
+            p = -p+Begin+End
+        end
+    end
+
+    # This class is used to test the base class by overriding as few methods
+    # as possible.
+    class Test < Cursor
+        def initialize(data=[],index=0)
+            super()
+            @data = data
+            @pos = index
+            @data_class = (@data.respond_to?:data_class) ?
+                @data.data_class : @data.class
+        end
+        def data_class
+            @data_class
+        end
+        def _delete1(flags,&more) # :yield: l=1
+            if (flags&Reverse).nonzero?
+                @pos>0 && (@pos -= 1)
+            else
+                @pos<@data.size
+            end or return(
+                if ret = more&&more[1]
+                    (flags&Ignore).nonzero? ? true : ret[0]
+                end
+            )
+            if (flags&Ignore).nonzero?
+                @data[@pos,1] = @data_class.new
+                1
+            else
+                @data.slice!(@pos)
+            end
+        end
+        def _insert1(value,flags)
+            @data[@pos,0] = (@data_class.new << value)
+            @pos += 1 if (flags&Reverse).zero?
+        end
+    end
+
+    # This class puts a cursor on an Array or String.
+    class Indexed < Cursor
+        def initialize(data=[],index=0)
+            super()
+            @data = data
+            @pos = index
+            @data_class = (@data.respond_to?:data_class) ?
+                @data.data_class : @data.class
+        end
+        def data_class
+            @data_class
+        end
+        def _delete1(flags,&more) # :yield: l=1
+            if (flags&Reverse).nonzero?
+                @pos>0 && @pos -= 1
+            else
+                @pos<@data.size
+            end or return(
+                if ret = more&&more[1]
+                    (flags&Ignore).nonzero? ? true : ret[0]
+                end
+            )
+            if (flags&Ignore).nonzero?
+                @data[@pos,1] = @data_class.new
+                true
+            else
+                @data.slice!(@pos)
+            end
+        end
+        def _insert1(value,flags)
+            @data[@pos,0] = (@data_class.new << value)
+            @pos += 1 if (flags&Reverse).zero?
+        end
+    end
+
+    # This class treats an IO (or StringIO) as a Cursor.  An IO is already
+    # like a Cursor, but doesn't have as robust an interface.  Deleting and
+    # inserting is a slow/painful process.
+    class IO < Cursor
+        def initialize(io=StringIO.new)
+            super()
+            @io = io
+        end
+        def data_class
+            String
+        end
+        def _delete1(flags,&more) # :yield: l=1
+            if (flags&Reverse).nonzero?
+                begin
+                    @io.seek(-1,::IO::SEEK_CUR)
+                    ret = @io.getc
+                rescue
+                    ret = nil
+                end
+            else
+                ret = @io.getc
+            end or return(
+                if ret = more&&more[1]
+                    (flags&Ignore).nonzero? ? true : ret[0]
+                end
+            )
+            ret = true if (flags&Ignore).nonzero?
+            after = 0
+            while c = @io.getc
+                after += 1
+                @io.seek(-2,::IO::SEEK_CUR)
+                @io.putc(c)
+                @io.seek(+1,::IO::SEEK_CUR)
+            end
+            @io.seek(-1,::IO::SEEK_CUR)
+            @io.truncate(@io.pos)
+            @io.seek(-after,::IO::SEEK_CUR) if after>0
+            ret
+        end
+        def _insert1(value,flags)
+            after = 0
+            while c = @io.getc
+                after += 1
+                @io.seek(-1,::IO::SEEK_CUR)
+                @io.putc(value)
+                value = c
+            end
+            @io.putc(value)
+            after += 1 if (flags&Reverse).nonzero?
+            @io.seek(-after,::IO::SEEK_CUR) if after>0
+            nil
+        end
+        def _get1(flags,&more) # :yield: l=1
+            if (flags&Reverse).nonzero?
+                begin
+                    @io.seek(-1,::IO::SEEK_CUR)
+                rescue
+                    return(
+                        if ret = more&&more[1]
+                            if (flags&Hold).nonzero?
+                                flags ^= Hold
+                                flags ^= Reverse
+                            end
+                            _insert(flags,ret=ret[0])
+                            (flags&Ignore).nonzero? ? true : ret
+                        end
+                    )
+                end
+                if (flags&Ignore).nonzero?
+                    @io.seek(+1,::IO::SEEK_CUR) if (flags&Hold).nonzero?
+                    ret = true
+                else
+                    ret = @io.getc
+                    @io.seek(-1,::IO::SEEK_CUR) if (flags&Hold).zero?
+                end
+            else
+                if not ret = @io.getc
+                    return(
+                        if ret = more&&more[1]
+                            @io.putc(ret=ret[0])
+                            @io.seek(-1,::IO::SEEK_CUR) if (flags&Hold).nonzero?
+                            (flags&Ignore).nonzero? ? true : ret
+                        end
+                    )
+                end
+                @io.ungetc(ret) if (flags&Hold).nonzero?
+                ret = true if (flags&Ignore).nonzero?
+            end
+            ret
+        end
+        def _put1(value,flags,&more) # :yield: l=1
+            if (flags&Reverse).nonzero?
+                begin
+                    @io.seek(-1,::IO::SEEK_CUR)
+                rescue
+                    if ret = more&&more[1]
+                        ret = (flags&Read).zero? ? true : ret[0]
+                    end
+                    if (flags&Hold).nonzero?
+                        flags ^= Hold
+                        flags ^= Reverse
+                    end
+                    _insert1(value,flags)
+                    return(ret)
+                end                                                                                               
+                if (flags&Read).nonzero?
+                    ret = @io.getc
+                    @io.ungetc(ret)
+                else
+                    ret = true
+                end
+                @io.putc(value)
+                if (flags&Hold).zero?
+                    @io.seek(-1,::IO::SEEK_CUR)
+                end
+            else
+                if (flags&Read).nonzero?
+                    if not ret = @io.getc
+                        if ret = more&&more[1]
+                            ret = ret[0]
+                        end
+                    else
+                        @io.ungetc(ret)
+                    end
+                elsif @io.eof?
+                    ret = more&&more[1]&&true
+                else
+                    ret = true
+                end
+                @io.putc(value)
+                @io.seek(-1,::IO::SEEK_CUR) if (flags&Hold).nonzero?
+            end
+            ret
+        end
+        def close
+            @io.close
+            super()                
+        end
+    end
+
+    # This Cursor class uses an Array/String for data before the cursor
+    # and another one for data after the cursor.  The result of this is that
+    # data is only deleted/inserted at the end of these 2.  Because of that
+    # most operations have similar expense and are linear with respect to the
+    # number of elements being moved, inserted, deleted, replaced, etc.
+    class Buffer < Cursor
+        def initialize(before=[],after=before.class.new)
+            super()
+            @before = before
+            @after = after
+            @data_class = (@before.respond_to?:data_class) ?
+                @before.data_class : @before.class
+        end
+        def data_class
+            @data_class
+        end
+        def _delete1(flags,&more) # :yield: l=1
+            data = (flags&Reverse).nonzero? ? @before : @after
+            data.size>0 or return(
+                if ret = more&&more[1]
+                    (flags&Ignore).nonzero? ? true : ret[0]
+                end
+            )
+            if (flags&Ignore).nonzero?
+                data[-1,1] = @data_class.new
+                true
+            else
+                data.slice!(-1)
+            end
+        end
+        def _insert1(value,flags)
+            data = (flags&Reverse).nonzero? ? @after : @before
+            data << value
+        end
+    end
+
+    # This Cursor class implements a circular buffer (not very efficient now).  The beginning and end
+    # are treated to be the current position.  #pos/#position and friends really
+    # don't make sense here (at least right now).
+    class Circular < Cursor
+        def initialize(data=[])
+            super()
+            @data = data
+            @data_class = (@data.respond_to?:data_class) ?
+                @data.data_class : @data.class
+        end
+        def data_class
+            @data_class
+        end
+        def _delete1(flags,&more) # :yield: l=1
+            @data.size>0 or return(
+                if ret = more&&more[1]
+                    (flags&Ignore).nonzero? ? true : ret[0]
+                end
+            )
+            index = (flags&Reverse).nonzero? ? -1 : 0
+            if (flags&Ignore).nonzero?
+                @data[index,1] = @data_class.new
+                true
+            else
+                @data.slice!(index)
+            end
+        end
+        def _insert1(value,flags)
+            if (flags&Reverse).nonzero?
+                @data[0,0] = (@data_class.new << value)
+            else
+                @data << value
+            end
+        end
+        def get(len=nil,flags=Next,&more) # :yield: l
+            if len==Rest
+                nil
+            else
+                super(len,flags,&more)
+            end
+        end
+        def size
+            @data.size
+        end
+        alias length size
+        def clear
+            @data.replace(@data_class.new)
+        end
+        def data
+            @data.clone()
+        end
+        def replace(obj)
+            if @data_class>=obj.class
+                @data.replace(obj)
+            else
+                super(obj)
+            end
+            self
+        end
+        
+    end
+
+    # This class gives unidirectional cursors (i.e. IO pipes) some
+    # bidirectional capabilities.  An input cursor and/or an output cursor
+    # can be specified.  The #position, #position?, and #position! methods are
+    # used to control buffering.  Full cursor capability (limited by the buffer
+    # cursor) is accessible starting from the first #position.  When the end of
+    # the buffer is reached more data is read from the input cursor (if not nil) using #get .  When no
+    # #position is outstanding, everything before the buffer cursor is written
+    # to the output cursor (if not nil) using #put.  If the cursor is attempted
+    # to be moved before the buffer, the output cursor is read in reverse (which
+    # the output cursor may not like).
+    class Buffered < Cursor
+        def initialize(input,output=nil,buffer=Buffer.new((input||output).data_class.new))
+            @input = input
+            @output = output
+            @buffer = buffer
+            @offset = 0
+            super()
+        end
+        def data_class
+            @buffer.data_class
+        end
+        def get(len=nil,flags=Next,&more) # :yield: l
+            value = @buffer.get(len,flags) { |l|
+                if (flags&Reverse).nonzero?
+                    if @offset.zero?
+                        more&&more[l]
+                    else
+                        v = @output.get(l,Prev,&more)
+                        @offset -= v.size if v
+                        v
+                    end
+                elsif @input
+                    @input.get(l,Next,&more)
+                else
+                    more&&more[l]
+                end
+            }
+            if not position?
+                @offset = @buffer.pos+@offset
+                if output_value = @buffer.get(Rest,Prev|Delete)
+                    @output.put(output_value,Next) if @output
+                end
+            end
+            value
+        end
+        def put(value,flags=Next,&more) # :yield: l
+            value0 = @buffer.put(value,flags) { |l|
+                if (flags&Reverse).nonzero?
+                    if @offset.zero?
+                        more&&more[l]
+                    else
+                        v = @output.get(l,Prev,&more)
+                        @offset -= v.size if v
+                        v
+                    end
+                elsif @input
+                    @input.get(l,Next,&more)
+                else
+                    more&&more[l]
+                end
+            }
+            if not position?
+                @offset = @buffer.pos+@offset
+                if output_value = @buffer.get(Rest,Prev|Delete)
+                    @output.put(output_value,Next) if @output
+                end
+            end
+            value0
+        end
+        def pos(reverse=false,&code) # :yield:
+            if code or reverse
+                super(reverse,&code)
+            else
+                @buffer.pos+@offset
+            end
+        end
+        def pos=(p)
+            if p<Begin
+                super(p)
+            else
+                p = p-@offset
+                if p<Begin
+                    @buffer.pos = Begin
+                    get(-p,Prev|Ignore)
+                    @offset
+                else
+                    (@buffer.pos = p)+@offset
+                end
+            end
+        end
+        def close
+            value = @buffer.get(Rest,Prev|Delete) and @output and
+                @output.put(value,Next)
+            value = @buffer.get(Rest,Next|Delete) and @output and
+                @output.put(value,Next)
+            super()
+        end
+    end
+
+    # This class tracks the current line and column.  Both line and column
+    # start at 0.  When a newline is found, the line is incremented and the
+    # column is reset.  With other characters, the column is incremented.
+    # The line and column numbers are only tracked when reading forward, but
+    # using #position (and friends) will hold the line and column.
+    class LineColumnNumbered < Cursor
+        # Structure stored in the #prop attribute.  line and column numbers
+        # are accessed through #prop.line and #prop.column.
+        LineColumn = Struct.new("LineColumn",:line,:column)
+        # Create a new Cursor from another that tracks line and column.
+        # +newline+ can be any valid argument for String#index (or the
+        # index method for whatever the underlying #data_class is).  For example,
+        # +newline+=+/\n|\r(?!\n)/+ could be used for unix, mac, dos/cpm style
+        # newlines.
+        def initialize(cursor,newline="\n"[0])
+            @cursor = cursor
+            @newline = newline
+            self.prop = LineColumn.new(0,0)
+            super()
+        end
+        def get(len=nil,flags=Next,&more) # :yield: l
+            ret = @cursor.get(len,flags,&more)
+            if (flags&Ignore).zero? and (flags&Reverse).zero? and ret
+                if not len
+                    if ret==@newline
+                        prop.line += 1
+                        prop.column = 0
+                    else
+                        prop.column += 1
+                    end
+                else
+                    i0 = 0
+                    begin
+                        while i = index(@newline,i0)
+                            prop.line += 1
+                            prop.column = 0
+                            i0 = i+1
+                        end
+                    rescue
+                        #index with 2 args not supported
+                        i = i0
+                        while i<ret.size
+                            if @newline==ret[i]
+                                prop.line += 1
+                                prop.column = 0
+                                i0 = i+1
+                            end
+                            i += 1
+                        end
+                    end
+                    prop.column += ret.size-i0
+                end
+            end
+            ret
+        end
+    end
+    
+end
+
+