linked 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f849d6e81849d33fc12f3d7d6812b9e73a59ad7
-  data.tar.gz: c236972593f1ab6e4e677fd554cf1bb50fbddddc
+  metadata.gz: 05e94a861ba2e494ea20dc84572c5dac578421eb
+  data.tar.gz: 849a8b134e95bcd6d444782c167f83ff6f982be4
 SHA512:
-  metadata.gz: f035c1eefc48f188b208632a6bbc80135be6b7b7110b3cb8faa02a26b417a096754fcd1f7593991ba7265026f0485fa0b3e49022fdc40fa7276e5499ebee3e4a
-  data.tar.gz: 31b1561e5d7c6dab409533cb1b263bec7a6db13c4a889acb99605997702cd52b577828673617f23bb27b26d84966c41a20181225f10d150a25ba52defc10d591
+  metadata.gz: 255a18d48ba2d395e12394aa8a6a72880100a1c2677ad3f5e3005c7412ea74011c4b902947b390b85077675c6a0447c112b6bed36ba4da8bf03dcd5769bf7f73
+  data.tar.gz: e2e9b8f9a72c06074c1aa3af9cbecff9c3fbb8adc2bc6674f50f86d3a089abec934ca5ee91815e9156f4647c374ec3bea87fec583e80236a5b010c9939c0cbf8

data/README.md

@@ -36,13 +36,8 @@ A basic use case is show below. For more details, for now, see the docs.
 ```ruby
 require 'linked'
 
-# Include the List module in a class
-class ListLike
-  include Linked::List    
-end
-
 # Create a list
-list = ListLike.new
+list = Linked::List.new
 
 # Append values
 list << :value

data/lib/linked/item.rb

@@ -1,58 +1,19 @@
 # frozen_string_literal: true
 
-# TODO: Think about moving some of basic functionallity of Item into Item::Base.
-
 module Linked
   # Item
   #
-  # This class implements doubly linked list items, designed to work both on
-  # their own and as children of list.
-  #
-  #             +- - - +    +------+------+            +- - - +
-  #             | Head | <--| prev | next |--> ... --> | Tail |
-  #             + - - -+    +------+------+            + - - -+
-  #            (optional)     First Item     N Items  (optional)
-  #
-  # An object is considered a list if it responds to #head, #tail, #grow and
-  # #shrink. The latter facilitate counting of the items and will be called
-  # everytime an item is appended, prepended or deleted. #head and #tail are
-  # expected to return two objects that, respectivly
-  # a) responds to #next= and #append, or #prev= and #prepend and
-  # b) returns true for #nil?.
-  #
-  # Notation
-  # --------
-  #
-  # Some methods operate on chains of items, and to describe the effects of an
-  # operation the following syntax is used.
-  #
-  #                    A   ( A <> B )   [ A <> B ]
-  #                   (i)     (ii)        (iii)
-  #
-  # Single items are denoted with capital letters (i), while chains are written
-  # as multiple connected items (ii). The parenthesis are optional. To show that
-  # one or more nodes are wraped in a list, angle brackets are used (iii).
+  # This class implements a listable value object that wraps an arbitrary value
+  # an can be stored in a list.
 
   class Item
-    # Access the list (if any) that the item belongs to. Writing to this
-    # attribute is protected and should be avoided.
-    #
-    # Returns the item's list, or nil
-
-    attr_writer :list
-    protected :list=
+    include Listable
 
     # The Item can hold an arbitrary object as its value and it will stay with
     # the item.
 
     attr_accessor :value
 
-    # Calling either #prev= or #next= directly is not recommended, since can
-    # corrupt the chain.
-
-    attr_writer :prev, :next
-    protected :prev=, :next=
-
     # Creates a new item. If a list is given the item will be considered a part
     # of that list and appended to the end of it.
     #
@@ -61,15 +22,9 @@ module Linked
     #
     # Returns a new Item.
 
-    def initialize(value = nil, list: nil)
+    def initialize(value = nil)
       @value = value
-      @list = list
-      if list
-        list.tail.append self
-      else
-        @next = nil
-        @prev = nil
-      end
+      super()
     end
 
     # Calling #dup on an item returns a copy that is no longer connected to the
@@ -78,7 +33,6 @@ module Linked
     # Returns a new Item.
 
     def initialize_dup(source)
-      @next = @prev = @list = nil
       @value = begin
                  source.value.dup
                rescue TypeError
@@ -87,272 +41,27 @@ module Linked
       super
     end
 
-    # Identity method that simply return the item. This method mirrors List#item
-    # and allows other methods that work on Item objects to easily and
-    # interchangebly accept both lists and items as arguments.
-    #
-    # Returns the item itself.
-
-    def item
-      self
-    end
-
-    # Access the list that the item is part of. If the item is not in a list a
-    # NoMethodError will be raised. This mirrors the behaviour of List#list and
-    # allows other methods that work on List objects to easily and
-    # interchangeably accept both lists and items as arguments.
-    #
-    # Returns the list that the item is part of.
-
-    def list
-      raise NoMethodError unless @list
-      @list
-    end
-
-    # Check it the item is part of a list.
-    #
-    # Returns true if the item is in a list.
-
-    def in_list?
-      @list ? true : false
-    end
-
-    # Check if this is the first item in the list. It is crucial that tail#nil?
-    # returns true for the first item to be identified correctly.
-    #
-    # Returns true if no item come before this one.
-
-    def first?
-      @prev.nil?
-    end
-
-    # Check if this is the last item in the list. It is crucial that head#nil?
-    # returns true for the last item to be identified correctly.
-    #
-    # Returns true if no item come after this one.
-
-    def last?
-      @next.nil?
-    end
-
-    # Check if the item is in the given list.
-    #
-    # list - any object.
-    #
-    # Returns true if the item is part of the given list.
-
-    def in?(list)
-      @list.equal? list
-    end
-
-    # Access the next item in the list. If this is the last one a StopIteration
-    # will be raised, so that items may be iterated over safely in a loop.
-    #
-    # Example
-    #   loop do
-    #     item = item.next
-    #   end
-    #
-    # Returns the item that come after this.
-
-    def next
-      raise StopIteration if last?
-      @next
-    end
-
-    # Unsafe accessor of the next item in the list. It is preferable to use
-    # #next.
-    #
-    # Returns the item that come after this, or nil if this is the last one.
-
-    def next!
-      @next
-    end
-
-    # Access the previous item in the list. If this is the first one a
-    # StopIteration will be raised, so that items may be iterated over safely in
-    # a loop.
-    #
-    # Example
-    #   loop do
-    #     item = item.prev
-    #   end
-    #
-    # Returns the item that come before this.
-
-    def prev
-      raise StopIteration if first?
-      @prev
-    end
-
-    alias previous prev
-
-    # Unsafe accessor of the previous item in the list. It is preferable to use
-    # #prev.
-    #
-    # Returns the item that come before this, or nil if this is the first one.
-
-    def prev!
-      @prev
-    end
-
-    alias previous! prev!
-
-    # Inserts the given item between this one and the one after it (if any). If
-    # the given item is part of a chain, all items following it will be moved to
-    # this one, and added to the list if one is set.
-    #
-    # Example for the chain (A <> C)
-    #
-    #   A.append B # => (A <> B <> C)
-    #
-    # Alternativly the argument can be an arbitrary object, in which case a new
-    # item will be created around it.
-    #
-    # If this item is part of a list #grow will be called on it with the
-    # number of added items as an argument. Should it also be the last item
-    # #prev= will be called on the list tail.
-    #
-    # object - the item to append, or an arbitrary object to be wraped in a new
-    #          item. If in a list it will be asked to create the new item via
-    #          List#create_item.
-    #
-    # Returns the last item that was appended.
-
-    def append(object)
-      if object.respond_to? :item
-        first_item = object.item
-        last_item = first_item.send :extract_beginning_with, @list
-      else
-        if @list
-          first_item = last_item = @list.send :create_item, object
-          first_item.list = @list
-          @list.send :grow
-        else
-          first_item = last_item = self.class.new object
-        end
-      end
-
-      first_item.prev = self
-      @next.prev = last_item if @next
-      @next, last_item.next = first_item, @next
-
-      last_item
-    end
-
-    # Inserts the given item between this one and the one before it (if any). If
-    # the given item is part of a chain, all items preceeding it will be moved
-    # to this one, and added to the list if one is set.
-    #
-    # Example for the chain (A <> C)
-    #
-    #   C.prepend B # => (A <> B <> C)
+    # Item equality is solely determined by tha value. If the other object
+    # responds to #value, and its value is equal (#==) to this value, the
+    # objects are considered equal.
     #
-    # Alternativly the argument can be an arbitrary object, in which case a new
-    # item will be created around it.
+    # other - any object.
     #
-    # If this item is part of a list #grow will be called on it with the
-    # number of added items as an argument. Should it also be the first item
-    # #next= will be called on the list head.
-    #
-    # object - the item to prepend. or an arbitrary object to be wraped in a
-    #          new item. If in a list it will be asked to create the new item
-    #          via List#create_item.
-    #
-    # Returns the last item that was prepended.
-
-    def prepend(object)
-      if object.respond_to? :item
-        last_item = object.item
-        first_item = last_item.send :extract_ending_with, @list
-      else
-        if @list
-          first_item = last_item = @list.send :create_item, object
-          first_item.list = @list
-          @list.send :grow
-        else
-          first_item = last_item = self.class.new object
-        end
-      end
+    # Returns true if the objects are considered equal.
 
-      last_item.next = self
-      @prev.next = first_item if @prev
-      @prev, first_item.prev = last_item, @prev
-
-      first_item
-    end
-
-    # Remove an item from the chain. If this item is part of a list and is
-    # either first, last or both in that list, #next= and #prev= will be called
-    # on the list head and tail respectivly.
-    #
-    # If this item is part of a list #shrink will be called on it.
-    #
-    # Returns self.
-
-    def delete
-      @next.prev = @prev if @next
-      @prev.next = @next if @prev
-      @list.send :shrink if @list
-
-      @next = @prev = @list = nil
-      self
+    def ==(other)
+      return false unless other.respond_to? :value
+      value == other.value
     end
 
-    # Remove all items before this one in the chain. If the items are part of a
-    # list they will be removed from it.
-    #
-    # Returns the last item in the chain that was just deleted, or nil if this
-    # is the first item.
-
-    def delete_before
-      @prev.send :extract_ending_with unless first?
-    end
+    alias eql? ==
 
-    # Remove all items after this one in the chain. If the items are part of a
-    # list they will be removed from it.
+    # Uses the hash value of the item value.
     #
-    # Returns the last item in the chain that was just deleted, or nil if this
-    # is the first item.
+    # Returns a fixnum that can be used by Hash to identify the item.
 
-    def delete_after
-      @next.send :extract_beginning_with unless last?
-    end
-
-    # Iterates over each item before this, in reverse order. If a block is not
-    # given an enumerator is returned.
-    #
-    # Note that raising a StopIteraion inside the block will cause the loop to
-    # silently stop the iteration early.
-
-    def before
-      return to_enum(__callee__) unless block_given?
-      return if first?
-
-      item = self.prev
-
-      loop do
-        yield item
-        item = item.prev
-      end
-    end
-
-    # Iterates over each item after this. If a block is not given an enumerator
-    # is returned.
-    #
-    # Note that raising a StopIteraion inside the block will cause the loop to
-    # silently stop the iteration early.
-
-    def after
-      return to_enum(__callee__) unless block_given?
-      return if last?
-
-      item = self.next
-
-      loop do
-        yield item
-        item = item.next
-      end
+    def hash
+      value.hash
     end
 
     # Freezes the value, as well as making the list item itself immutable.
@@ -372,100 +81,5 @@ module Linked
       output = format '%s:0x%0x', self.class.name, object_id
       value ? output + " value=#{value.inspect}" : output
     end
-
-    # PRIVATE DANGEROUS METHOD. This method should never be called directly
-    # since it may leave the extracted item chain in an invalid state.
-    #
-    # This method extracts the item, together with the chain following it, from
-    # the list they are in (if any) and optionally facilitates moving them to a
-    # new list.
-    #
-    # Given the two lists
-    #                         [ A <> B <> C ]   [ D ]
-    #                               (I)          (II)
-    #
-    # calling B.extract_beginning_with(II) will result in (B <> C) being removed
-    # from (I), and (II) to be grown by two. (B <> C) will now reference (II)
-    # but they will not yet be linked to any of the items in it. It is therefore
-    # necessary to insert them directly after calling this method, or (II) will
-    # be left in an invalid state.
-    #
-    # Returns the last item of the chain.
-
-    private def extract_beginning_with(new_list = nil)
-      old_list = @list
-      # Count items and move them to the new list
-      last_item = self
-      count = 1 + loop.count do
-        last_item.list = new_list
-        last_item = last_item.next
-      end
-
-      # Make sure the old list is in a valid state
-      if old_list
-        if first?
-          old_list.send :clear
-        else
-          old_list.send :shrink, count
-          # Fix the links within in the list
-          @prev.next = last_item.next!
-          last_item.next!.prev = @prev
-        end
-      else
-        # Disconnect the item directly after the chain
-        @prev.next = nil unless first?
-      end
-
-      # Disconnect the chain from the list
-      @prev = last_item.next = nil
-
-      # Preemptivly tell the new list to grow
-      new_list.send :grow, count if new_list
-
-      last_item
-    end
-
-    # PRIVATE DANGEROUS METHOD. This method should never be called directly
-    # since it may leave the extracted item chain in an invalid state.
-    #
-    # This method extracts the item, together with the chain preceding it, from
-    # the list they are in (if any) and optionally facilitates moving them to a
-    # new list. See #extract_beginning_with for a description of the side
-    # effects from calling this method.
-    #
-    # Returns the first item in the chain.
-
-    private def extract_ending_with(new_list = nil)
-      old_list = @list
-      # Count items and move them to the new list
-      first_item = self
-      count = 1 + loop.count do
-        first_item.list = new_list
-        first_item = first_item.prev
-      end
-
-      # Make sure the old list is in a valid state
-      if old_list
-        if last?
-          old_list.send :clear
-        else
-          old_list.send :shrink, count
-          # Fix the links within in the list
-          @next.prev = first_item.prev!
-          first_item.prev!.next = @next
-        end
-      else
-        # Disconnect the item directly after the chain
-        @next.prev = nil unless last?
-      end
-
-      # Disconnect the chain from the list
-      first_item.prev = @next = nil
-
-      # Preemptivly tell the new list to grow
-      new_list.send :grow, count if new_list
-
-      first_item
-    end
   end
 end

data/lib/linked/list/eol.rb

@@ -1,13 +1,13 @@
 module Linked
-  module List
+  class List
     # End Of List
     #
     # This class implements a special list item that is placed at both the end
-    # and the beginning of a chain of regular items to form a list. The naming
+    # and the beginning of a chain of listable items to form a list. The naming
     # (end of list) comes from the fact that this object, by returning true for
     # calls to #nil?, signifies the end of a list of Items. In both directions
     # as a matter of fact, which is why the head and tail objects defined by
-    # Item is combined into one.
+    # Item are combined into one.
     #
     # In a nutshell, the structure looks something like this:
     #
@@ -18,13 +18,23 @@ module Linked
     #     +-| prev | next |<- ... ->| prev | next |-+
     #       +------+------+         +------+------+
 
-    class EOL < Item
-      private :value, :value=, :delete, :first?, :last?
+    class EOL
+      include Listable
 
-      def initialize(list:)
+      # Calling #delete on the EOL is not supported and would break the
+      # connection between the list and its items.
+
+      undef delete
+
+      # Creates a new enf-of-list, as part of a list, with no items yet added to
+      # it.
+      #
+      # list - a List object.
+
+      def initialize(list)
         super()
-        @list = list
-        @prev = @next = self
+        self.list = list
+        reset
       end
 
       # EOL objects will return true when asked if they are nil. This is
@@ -43,7 +53,7 @@ module Linked
       # See Item#append for more details.
 
       def append(object)
-        empty? ? super : @prev.append(object)
+        empty? ? super : prev!.append(object)
       end
 
       # Inserts one or more items at the beginning of the list.
@@ -51,7 +61,15 @@ module Linked
       # See Item#append for more details.
 
       def prepend(object)
-        empty? ? super : @next.prepend(object)
+        empty? ? super : next!.prepend(object)
+      end
+
+      # Private helper to reset the EOL to its initial state. This method should
+      # never be called directly as it leaves the both the list and the items in
+      # an inconsistant state.
+
+      private def reset
+        self.prev = self.next = self
       end
 
       # Private helper to check if the item chain is empty.
@@ -59,7 +77,7 @@ module Linked
       # Return true if the chain is empty, otherwise nil.
 
       private def empty?
-        @prev == self
+        prev!.equal? self
       end
     end
   end

data/lib/linked/list.rb

@@ -3,49 +3,20 @@
 module Linked
   # List
   #
-  # This module can be included in any class to give it list like behaviour.
-  # Most importantly, the methods #head, #tail, #grow and #shrink are
-  # implemented to comply with the requirements defined by Item.
-  #
-  # Example
-  #
-  #   class ListLike
-  #     include Linked::List
-  #
-  #     def initialize
-  #       super
-  #       ...
-  #
-  # A key implementation detail is the End-Of-List, or EOL object that sits
-  # between the list and the actual list items. It provides separation between
-  # the list and the actual list items.
+  # This class implements a linked list. Most importantly, the methods #head,
+  # #tail, #grow, #shrink and #create_item are implemented to comply with the
+  # requirements defined by Listable.
 
-  module List
+  class List
     include Enumerable
 
-    # Private accessor method for the End-Of-List object.
-    #
-    # Returns a List::EOL object.
-
-    attr_reader :eol
-    private :eol
-
-    # Returns an object that responds to #next= and #prepend.
-
-    alias head eol
-
-    # Returns an object that responds to #prev= and #append.
-
-    alias tail eol
+    # Initializes the list. It is important that this method be called during
+    # the initialization of the including class, and that the instance variables
+    # @_item_count and @_eol never be accessed directly.
 
-    # Initializes the list by setting the two instance variable @item_count and
-    # @eol. It is important that this method be called during the initialization
-    # of the including class, and that the instance variables never be accessed
-    # directly.
-
-    def initialize(*)
-      @eol = EOL.new list: self
-      @item_count = 0
+    def initialize
+      @_eol = EOL.new self
+      @_item_count = 0
 
       super
     end
@@ -55,8 +26,8 @@ module Linked
     # this operation quite expensive.
 
     def initialize_dup(source)
-      @eol = EOL.new list: self
-      @item_count = 0
+      @_eol = EOL.new self
+      @_item_count = 0
 
       source.each_item { |item| push item.dup  }
 
@@ -82,9 +53,25 @@ module Linked
 
     def item
       raise NoMethodError if empty?
-      eol.next
+      head.next
     end
 
+    # Two lists are considered equal if the n:th item from each list are equal.
+    #
+    # other - any object.
+    #
+    # Returns true if the given object is a list and the items are equal.
+
+    def ==(other)
+      return false unless other.is_a? self.class
+      return false unless other.count == @_item_count
+
+      other_items = other.each_item
+      each_item.all? { |item| item == other_items.next }
+    end
+
+    alias eql? ==
+
     # Access the first n item(s) in the list. If a block is given each item will
     # be yielded to it. The first item, starting from the first in the list, for
     # which the block returns true and the n - 1 items directly following it
@@ -101,9 +88,9 @@ module Linked
     def first(n = 1)
       raise ArgumentError, 'n cannot be negative' if n < 0
 
-      return first_item_after eol, n, count unless block_given?
+      return first_item_after head, n, count unless block_given?
 
-      item = eol
+      item = head
       items_left = count
 
       items_left.times do
@@ -131,9 +118,9 @@ module Linked
     def last(n = 1)
       raise ArgumentError, 'n cannot be negative' if n < 0
 
-      return last_item_before eol, n, count unless block_given?
+      return last_item_before tail, n, count unless block_given?
 
-      item = eol
+      item = tail
       items_left = count
 
       items_left.times do
@@ -155,7 +142,7 @@ module Linked
 
     def count(*args)
       if args.empty? && !block_given?
-        @item_count
+        @_item_count
       else
         super
       end
@@ -164,7 +151,7 @@ module Linked
     # Returns true if the list does not contain any items.
 
     def empty?
-      @item_count == 0
+      @_item_count == 0
     end
 
     # Insert an item at the end of the list. If the given object is not an
@@ -178,7 +165,7 @@ module Linked
     # Returns self.
 
     def push(object)
-      eol.append object
+      tail.append object
       self
     end
 
@@ -204,7 +191,7 @@ module Linked
     # Returns self.
 
     def unshift(object)
-      eol.prepend object
+      head.prepend object
       self
     end
 
@@ -236,7 +223,7 @@ module Linked
       return to_enum(__method__) { count } unless block_given?
       return if empty?
 
-      item = eol
+      item = head
       loop { yield item = item.next }
     end
 
@@ -249,7 +236,7 @@ module Linked
       return to_enum(__method__) { count } unless block_given?
       return if empty?
 
-      item = eol
+      item = tail
       loop { yield item = item.prev }
     end
 
@@ -259,7 +246,7 @@ module Linked
     # (eol).
 
     def freeze
-      eol.freeze
+      @_eol.freeze
       each_item(&:freeze)
       super
     end
@@ -289,7 +276,7 @@ module Linked
     # method is called whenever an arbitrary object is pushed or unshifted onto
     # the list and need to be wraped inside an Item.
     #
-    # This method can be overridden to suport different Item types.
+    # This method can be overridden to support different Item types.
     #
     # args - any arguments will be passed on to Item.new.
     #
@@ -299,6 +286,16 @@ module Linked
       Item.new(*args)
     end
 
+    # Returns an object that responds to #next= and #prepend.
+
+    protected def head
+      @_eol
+    end
+
+    # Returns an object that responds to #prev= and #append.
+
+    alias tail head
+
     # Internal method to grow the list with n elements. Never call this method
     # without also inserting the n elements.
     #
@@ -307,7 +304,7 @@ module Linked
     # Returns updated the item count.
 
     private def grow(n = 1)
-      @item_count += n
+      @_item_count += n
     end
 
     # Internal method to shrink the list with n elements. Never call this method
@@ -318,7 +315,7 @@ module Linked
     # Returns updated the item count.
 
     private def shrink(n = 1)
-      @item_count -= n
+      @_item_count -= n
     end
 
     # Private method to clear the list. Never call this method without also
@@ -328,13 +325,11 @@ module Linked
     # b) clear the `next` pointer of the last item.
 
     private def clear
-      head.send :next=, tail
-      tail.send :prev=, head
-
-      @item_count = 0
+      @_eol.send :reset
+      @_item_count = 0
     end
 
-    # Protected helper method that returns the first n items, starting just
+    # Private helper method that returns the first n items, starting just
     # after item, given that there are items_left items left. Knowing the exact
     # number of items left is not cruicial but does impact speed. The number
     # should not be lower than the actual ammount. The following must
@@ -351,10 +346,10 @@ module Linked
     # n == 1) an item if items_left > 0 or nil
     #  n > 1) an array of items if items_left > 0 or an empty array
 
-    protected def first_item_after(item, n, items_left = @item_count)
+    private def first_item_after(item, n, items_left = @_item_count)
       # Optimize for these cases
       return nil if n == 0
-      return n > 1 ? [] : nil if item.next!.nil?
+      return n > 1 ? [] : nil if item.last?
       return item.next if n == 1
 
       n = items_left if n > items_left
@@ -366,7 +361,7 @@ module Linked
       arr.compact! || arr
     end
 
-    # Protected helper method that returns the last n items, ending just before
+    # Private helper method that returns the last n items, ending just before
     # item,  given that there are items_left items left. Knowing the exact
     # number of items left is not cruicial but does impact speed. The number
     # should not be lower than the actual ammount. The following must hold for
@@ -383,10 +378,10 @@ module Linked
     # n == 1) an item if items_left > 0 or nil
     #  n > 1) an array of items if items_left > 0 or an empty array
 
-    protected def last_item_before(item, n, items_left = @item_count)
+    private def last_item_before(item, n, items_left = @_item_count)
       # Optimize for these cases
       return nil if n == 0
-      return n > 1 ? [] : nil if item.prev!.nil?
+      return n > 1 ? [] : nil if item.first?
       return item.prev if n == 1
 
       n = items_left if n > items_left
@@ -397,13 +392,5 @@ module Linked
     rescue StopIteration
       arr.compact! || arr
     end
-
-    # This method is called whenever the module is included somewhere. In the
-    # special case when List is included in an Item the #item method must be
-    # changed to return self.
-
-    def self.included(klass)
-      klass.send(:define_method, :item) { self } if klass < Item
-    end
   end
 end

data/lib/linked/listable.rb

@@ -0,0 +1,441 @@
+module Linked
+  # Listable
+  #                               List (optional)
+  #                           +----^-----+
+  #                   prev <- | Listable | -> next
+  #                           +----------+
+  #
+  # This module implements doubly linked list items, designed to work both on
+  # their own in a chain, and as children of list.
+  #
+  # An object is considered a list if it responds to #grow, #shrink and
+  # #create_item. The former two facilitate counting of the items and will be
+  # called everytime an item is appended, prepended or deleted. #create_item is
+  # expected to return a new object that is compatible with the list.
+  #
+  # Notation
+  # --------
+  #
+  # Some methods operate on chains of items, and to describe the effects of an
+  # operation the following syntax is used.
+  #
+  #                    A   ( A <> B )   [ A <> B ]
+  #                   (i)     (ii)        (iii)
+  #
+  # Single items are denoted with capital letters (i), while chains are written
+  # as multiple connected items (ii). The parenthesis are optional. To show that
+  # one or more nodes are wraped in a list, angle brackets are used (iii).
+
+  module Listable
+    # Creates a new item. Always make a call to super whenever implementing this
+    # method in a subclass.
+
+    def initialize(*)
+      @_next = @_prev = @_list = nil
+      super
+    end
+
+    # Calling #dup on an item returns a copy that is no longer connected to the
+    # original item chain, or the list. The value will also be copied.
+    #
+    # Returns a new Item.
+
+    def initialize_copy(*)
+      @_next = @_prev = @_list = nil
+      super
+    end
+
+    # Identity method that simply return the item. This method mirrors List#item
+    # and allows other methods that work on Item objects to easily and
+    # interchangebly accept both lists and items as arguments.
+    #
+    # Returns the item itself.
+
+    def item
+      self
+    end
+
+    # Access the list that the item is part of. If the item is not in a list a
+    # NoMethodError will be raised. This mirrors the behaviour of List#list and
+    # allows other methods that work on List objects to easily and
+    # interchangeably accept both lists and items as arguments.
+    #
+    # Returns the list that the item is part of.
+
+    def list
+      raise NoMethodError unless @_list
+      @_list
+    end
+
+    # Check it the item is part of a list.
+    #
+    # Returns true if the item is in a list.
+
+    def in_list?
+      @_list ? true : false
+    end
+
+    # Check if this is the first item in the list. It is crucial that tail#nil?
+    # returns true for the first item to be identified correctly.
+    #
+    # Returns true if no item come before this one.
+
+    def first?
+      @_prev.nil?
+    end
+
+    # Check if this is the last item in the list. It is crucial that head#nil?
+    # returns true for the last item to be identified correctly.
+    #
+    # Returns true if no item come after this one.
+
+    def last?
+      @_next.nil?
+    end
+
+    # Check if the item is in the given list.
+    #
+    # list - any object.
+    #
+    # Returns true if the item is part of the given list.
+
+    def in?(list)
+      @_list.equal? list
+    end
+
+    # Access the next item in the list. If this is the last one a StopIteration
+    # will be raised, so that items may be iterated over safely in a loop.
+    #
+    # Example
+    #   loop do
+    #     item = item.next
+    #   end
+    #
+    # Returns the item that come after this.
+
+    def next
+      raise StopIteration if last?
+      @_next
+    end
+
+    # Access the previous item in the list. If this is the first one a
+    # StopIteration will be raised, so that items may be iterated over safely in
+    # a loop.
+    #
+    # Example
+    #   loop do
+    #     item = item.prev
+    #   end
+    #
+    # Returns the item that come before this.
+
+    def prev
+      raise StopIteration if first?
+      @_prev
+    end
+
+    alias previous prev
+
+    # Inserts the given item between this one and the one after it (if any). If
+    # the given item is part of a chain, all items following it will be moved to
+    # this one, and added to the list if one is set.
+    #
+    # Example for the chain (A <> C)
+    #
+    #   A.append B # => (A <> B <> C)
+    #
+    # Alternativly the argument can be an arbitrary object, in which case a new
+    # item will be created around it.
+    #
+    # If this item is part of a list #grow will be called on it with the
+    # number of added items as an argument. Should it also be the last item
+    # #prev= will be called on the list tail.
+    #
+    # object - the item to append, or an arbitrary object to be wraped in a new
+    #          item. If in a list it will be asked to create the new item via
+    #          List#create_item.
+    #
+    # Returns the last item that was appended.
+
+    def append(object)
+      if object.respond_to? :item
+        first_item = object.item
+        last_item = first_item.send :extract_beginning_with, @_list
+      else
+        if @_list
+          first_item = last_item = @_list.send :create_item, object
+          first_item.list = @_list
+          @_list.send :grow
+        else
+          first_item = last_item = create_item object
+        end
+      end
+
+      first_item.prev = self
+      @_next.prev = last_item if @_next
+      @_next, last_item.next = first_item, @_next
+
+      last_item
+    end
+
+    # Inserts the given item between this one and the one before it (if any). If
+    # the given item is part of a chain, all items preceeding it will be moved
+    # to this one, and added to the list if one is set.
+    #
+    # Example for the chain (A <> C)
+    #
+    #   C.prepend B # => (A <> B <> C)
+    #
+    # Alternativly the argument can be an arbitrary object, in which case a new
+    # item will be created around it.
+    #
+    # If this item is part of a list #grow will be called on it with the
+    # number of added items as an argument. Should it also be the first item
+    # #next= will be called on the list head.
+    #
+    # object - the item to prepend. or an arbitrary object to be wraped in a
+    #          new item. If in a list it will be asked to create the new item
+    #          via List#create_item.
+    #
+    # Returns the last item that was prepended.
+
+    def prepend(object)
+      if object.respond_to? :item
+        last_item = object.item
+        first_item = last_item.send :extract_ending_with, @_list
+      else
+        if @_list
+          first_item = last_item = @_list.send :create_item, object
+          first_item.list = @_list
+          @_list.send :grow
+        else
+          first_item = last_item = create_item object
+        end
+      end
+
+      last_item.next = self
+      @_prev.next = first_item if @_prev
+      @_prev, first_item.prev = last_item, @_prev
+
+      first_item
+    end
+
+    # Remove an item from the chain. If this item is part of a list and is
+    # either first, last or both in that list, #next= and #prev= will be called
+    # on the list head and tail respectivly.
+    #
+    # If this item is part of a list #shrink will be called on it.
+    #
+    # Returns self.
+
+    def delete
+      @_next.prev = @_prev if @_next
+      @_prev.next = @_next if @_prev
+      @_list.send :shrink if @_list
+
+      @_next = @_prev = @_list = nil
+      self
+    end
+
+    # Remove all items before this one in the chain. If the items are part of a
+    # list they will be removed from it.
+    #
+    # Returns the last item in the chain that was just deleted, or nil if this
+    # is the first item.
+
+    def delete_before
+      @_prev.send :extract_ending_with unless first?
+    end
+
+    # Remove all items after this one in the chain. If the items are part of a
+    # list they will be removed from it.
+    #
+    # Returns the last item in the chain that was just deleted, or nil if this
+    # is the first item.
+
+    def delete_after
+      @_next.send :extract_beginning_with unless last?
+    end
+
+    # Iterates over each item before this, in reverse order. If a block is not
+    # given an enumerator is returned.
+    #
+    # Note that raising a StopIteraion inside the block will cause the loop to
+    # silently stop the iteration early.
+
+    def before
+      return to_enum(__callee__) unless block_given?
+      return if first?
+
+      item = self.prev
+
+      loop do
+        yield item
+        item = item.prev
+      end
+    end
+
+    # Iterates over each item after this. If a block is not given an enumerator
+    # is returned.
+    #
+    # Note that raising a StopIteraion inside the block will cause the loop to
+    # silently stop the iteration early.
+
+    def after
+      return to_enum(__callee__) unless block_given?
+      return if last?
+
+      item = self.next
+
+      loop do
+        yield item
+        item = item.next
+      end
+    end
+
+    # Protected factory method for creating items compatible with this listable
+    # item. This method is called whenever an arbitrary object is appended or
+    # prepended onto this item and need to be wraped/converted.
+    #
+    # This method can be overridden to support different behaviours.
+    #
+    # args - any arguments will be passed on to .new.
+    #
+    # Returns a new Listable object.
+
+    protected def create_item(*args)
+      self.class.new(*args)
+    end
+
+    # Protected unsafe accessor of the next item in the list. It is preferable
+    # to use #next, possibly in conjunction with #last?.
+    #
+    # Returns the item that come after this, or nil if this is the last one.
+
+    protected def next!
+      @_next
+    end
+
+    # Calling #next= directly is not recommended since it may corrupt the chain.
+
+    protected def next=(other)
+      @_next = other
+    end
+
+    # Protected, unsafe accessor of the previous item in the list. It is
+    # preferable to use #prev, possibly in conjunction with #first?.
+    #
+    # Returns the item that come before this, or nil if this is the first one.
+
+    protected def prev!
+      @_prev
+    end
+
+    # Calling #prev= directly is not recommended since it may corrupt the chain.
+
+    protected def prev=(other)
+      @_prev = other
+    end
+
+    # Calling #list= directly is not recommended since it may corrupt the list.
+
+    protected def list=(list)
+      @_list = list
+    end
+
+    # PRIVATE DANGEROUS METHOD. This method should never be called directly
+    # since it may leave the extracted item chain in an invalid state.
+    #
+    # This method extracts the item, together with the chain following it, from
+    # the list they are in (if any) and optionally facilitates moving them to a
+    # new list.
+    #
+    # Given the two lists
+    #                         [ A <> B <> C ]   [ D ]
+    #                               (I)          (II)
+    #
+    # calling B.extract_beginning_with(II) will result in (B <> C) being removed
+    # from (I), and (II) to be grown by two. (B <> C) will now reference (II)
+    # but they will not yet be linked to any of the items in it. It is therefore
+    # necessary to insert them directly after calling this method, or (II) will
+    # be left in an invalid state.
+    #
+    # Returns the last item of the chain.
+
+    private def extract_beginning_with(new_list = nil)
+      old_list = @_list
+      # Count items and move them to the new list
+      last_item = self
+      count = 1 + loop.count do
+        last_item.list = new_list
+        last_item = last_item.next
+      end
+
+      # Make sure the old list is in a valid state
+      if old_list
+        if first?
+          old_list.send :clear
+        else
+          old_list.send :shrink, count
+          # Fix the links within in the list
+          @_prev.next = last_item.next!
+          last_item.next!.prev = @_prev
+        end
+      else
+        # Disconnect the item directly after the chain
+        @_prev.next = nil unless first?
+      end
+
+      # Disconnect the chain from the list
+      @_prev = last_item.next = nil
+
+      # Preemptivly tell the new list to grow
+      new_list.send :grow, count if new_list
+
+      last_item
+    end
+
+    # PRIVATE DANGEROUS METHOD. This method should never be called directly
+    # since it may leave the extracted item chain in an invalid state.
+    #
+    # This method extracts the item, together with the chain preceding it, from
+    # the list they are in (if any) and optionally facilitates moving them to a
+    # new list. See #extract_beginning_with for a description of the side
+    # effects from calling this method.
+    #
+    # Returns the first item in the chain.
+
+    private def extract_ending_with(new_list = nil)
+      old_list = @_list
+      # Count items and move them to the new list
+      first_item = self
+      count = 1 + loop.count do
+        first_item.list = new_list
+        first_item = first_item.prev
+      end
+
+      # Make sure the old list is in a valid state
+      if old_list
+        if last?
+          old_list.send :clear
+        else
+          old_list.send :shrink, count
+          # Fix the links within in the list
+          @_next.prev = first_item.prev!
+          first_item.prev!.next = @_next
+        end
+      else
+        # Disconnect the item directly after the chain
+        @_next.prev = nil unless last?
+      end
+
+      # Disconnect the chain from the list
+      first_item.prev = @_next = nil
+
+      # Preemptivly tell the new list to grow
+      new_list.send :grow, count if new_list
+
+      first_item
+    end
+  end
+end

data/lib/linked/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Linked
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

data/lib/linked.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'linked/version'
+require 'linked/listable'
 require 'linked/item'
 require 'linked/list/eol'
 require 'linked/list'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: linked
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Sebastian Lindberg
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-10 00:00:00.000000000 Z
+date: 2016-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -87,6 +87,7 @@ files:
 - lib/linked/item.rb
 - lib/linked/list.rb
 - lib/linked/list/eol.rb
+- lib/linked/listable.rb
 - lib/linked/version.rb
 - linked.gemspec
 homepage: https://github.com/seblindberg/ruby-linked