cursor 0.5

data/cursor.rb

@@ -0,0 +1,1138 @@
+#!/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
+
+

metadata

@@ -0,0 +1,37 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: cursor
+version: !ruby/object:Gem::Version 
+  version: "0.5"
+date: 2005-05-19
+summary: external iterator API
+require_paths: 
+  - "."
+email: 
+homepage: 
+rubyforge_project: cursor
+description: 
+autorequire: cursor
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+authors: 
+  - Eric Mahurin
+files: 
+  - cursor.rb
+test_files: []
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: []