linked 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 05e94a861ba2e494ea20dc84572c5dac578421eb
-  data.tar.gz: 849a8b134e95bcd6d444782c167f83ff6f982be4
+SHA256:
+  metadata.gz: 44eaaab09ac6111dd607d3cd52e35d2d072315bbc4614b7805254c8a7bab311a
+  data.tar.gz: 4672f6d56f0dde64a6fe12ecaefdf82d39795a957d97ccb55eb0558ffe23285d
 SHA512:
-  metadata.gz: 255a18d48ba2d395e12394aa8a6a72880100a1c2677ad3f5e3005c7412ea74011c4b902947b390b85077675c6a0447c112b6bed36ba4da8bf03dcd5769bf7f73
-  data.tar.gz: e2e9b8f9a72c06074c1aa3af9cbecff9c3fbb8adc2bc6674f50f86d3a089abec934ca5ee91815e9156f4647c374ec3bea87fec583e80236a5b010c9939c0cbf8
+  metadata.gz: c94e42bee0a6717053ff3c33de9f36c03ab4ba24d35ddb3b387ed78a3e4a54898269eb62237117a05db4cf4c96b5555c376cc507cb2d8cc02aed1a80059f69a3
+  data.tar.gz: 479b9a24c6dc2a785993072e620695bebe35e9599cfb9f8842fd1a767d6783c5b0838f6ccd0abce247a155e416930fa76cc6c164cb6ae85e2e9aac23c7948c9f

data/.rubocop.yml

@@ -0,0 +1,71 @@
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+  TargetRubyVersion: 2.3
+
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+Layout/ClassStructure:
+  Enabled: true
+  Categories:
+    module_inclusion:
+      - include
+      - prepend
+      - extend
+  ExpectedOrder:
+      - module_inclusion
+      - constants
+      - public_class_methods
+      - initializer
+      - instance_methods
+      - protected_methods
+      - private_methods
+
+Layout/IndentHeredoc:
+  EnforcedStyle: squiggly
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - 'test/**/*.rb'
+
+Lint/InterpolationCheck:
+  Exclude:
+    - 'test/**/*.rb'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'Rakefile'
+    - '**/*.rake'
+    - 'test/**/*.rb'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'test/**/*.rb'
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Naming/UncommunicativeMethodParamName:
+  AllowedNames:
+    - "_"
+    - x
+    - y
+    - i
+    - p
+    - n
+    - t
+    - r
+    - g
+    - b
+    - to
+    
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+    
+Style/FormatStringToken:
+  Enabled: false
+  
+Style/MultipleComparison:
+  Enabled: false

data/.travis.yml

@@ -3,3 +3,4 @@ language: ruby
 rvm:
   - 2.3.0
 before_install: gem install bundler -v 1.12.5
+script: bundle exec rake test

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in linked.gemspec

data/Rakefile

@@ -1,10 +1,23 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'yard'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+RuboCop::RakeTask.new(:rubocop)
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.stats_options = %w[--list-undoc]
+end
+
+desc 'Generate Ruby documentation'
+task doc: %w[yard]
+
+task default: %w[test rubocop:auto_correct]

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "linked"
+require 'bundler/setup'
+require 'linked'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "linked"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start

data/lib/linked.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require 'linked/version'
+require 'linked/util'
 require 'linked/listable'
 require 'linked/item'
-require 'linked/list/eol'
+require 'linked/list_enumerable'
 require 'linked/list'
 
+# Linked List implementation.
 module Linked
-
+  private_constant :Util, :ListEnumerable
 end

data/lib/linked/item.rb

@@ -1,37 +1,32 @@
 # frozen_string_literal: true
 
 module Linked
-  # Item
+  # This is the default implementation of a listable object
   #
   # This class implements a listable value object that wraps an arbitrary value
-  # an can be stored in a list.
-
+  # an can be with other listable items.
   class Item
     include Listable
 
     # The Item can hold an arbitrary object as its value and it will stay with
     # the item.
-
+    # @return [Object] any object that is stored in the item.
     attr_accessor :value
 
     # 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.
     #
-    # value - an arbitrary object to store with the item.
-    # list - an object responding to #head and #tail.
-    #
-    # Returns a new Item.
-
+    # @param  value [Object] an arbitrary object to store with the item.
     def initialize(value = nil)
       @value = value
       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.
+    # original item chain. The value will also be copied.
     #
-    # Returns a new Item.
-
+    # @param  source [Item] the item to copy.
+    # @return [item] a new Item.
     def initialize_dup(source)
       @value = begin
                  source.value.dup
@@ -45,10 +40,9 @@ module Linked
     # responds to #value, and its value is equal (#==) to this value, the
     # objects are considered equal.
     #
-    # other - any object.
-    #
-    # Returns true if the objects are considered equal.
-
+    # @param  other [#value, Object] any object.
+    # @return [true, false] true if the value of the given object is equal to
+    #   the item value.
     def ==(other)
       return false unless other.respond_to? :value
       value == other.value
@@ -58,28 +52,27 @@ module Linked
 
     # Uses the hash value of the item value.
     #
-    # Returns a fixnum that can be used by Hash to identify the item.
-
+    # @return [Integer] a fixnum that can be used by Hash to identify the item.
     def hash
       value.hash
     end
 
-    # Freezes the value, as well as making the list item itself immutable.
-
+    # Freezes the value, as well as making the item itself immutable.
+    #
+    # @return [self]
     def freeze
       value.freeze
       super
     end
 
     # The default #inspect method becomes very cluttered the moment you start
-    # liking objects together. This implementation fixes that and only shows the
-    # class name, object id and value (if set).
-
+    # linking objects together. This implementation fixes that and only shows
+    # the class name, object id and value (if set).
+    #
+    # @return [String] a string representation of the list item.
     def inspect
-      return yield self if block_given?
-
-      output = format '%s:0x%0x', self.class.name, object_id
-      value ? output + " value=#{value.inspect}" : output
+      return yield(self).to_s if block_given?
+      value ? object_identifier + " value=#{value.inspect}" : object_identifier
     end
   end
 end

data/lib/linked/list.rb

@@ -1,70 +1,52 @@
 # frozen_string_literal: true
 
 module Linked
-  # List
+  # This class provides a way extend the regular chain of listable items with
+  # the concept of an empty chain.
   #
-  # 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.
-
+  # Lists are ment to behave more like arrays, and respond to many of the same
+  # methods.
   class List
-    include Enumerable
-
-    # 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.
+    include ListEnumerable
+    include Util
 
+    # Initializes the list.
     def initialize
-      @_eol = EOL.new self
-      @_item_count = 0
-
+      reset_list
       super
     end
 
     # When copying a list its entire item chain needs to be copied as well.
     # Therefore #dup will be called on each of the original lists items, making
     # this operation quite expensive.
-
+    #
+    # @param source [List] the list to copy.
     def initialize_dup(source)
-      @_eol = EOL.new self
-      @_item_count = 0
-
-      source.each_item { |item| push item.dup  }
+      reset_list
+      source.each_item { |item| push item.dup }
 
       super
     end
 
-    # Identity method that simply return the list. This method mirrors Item#list
-    # and allows other methods that work on List objects to easily and
-    # interchangebly accept both lists and items as arguments.
-    #
-    # Returns the list itself.
-
-    def list
-      self
-    end
-
     # Access the first item in the list. If the list is empty a NoMethodError
     # will be raised. This mirrors the behaviour of Item#item and allows other
     # methods that work on List objects to easily and interchangeably accept
     # both lists and items as arguments.
     #
-    # Returns the first item in the list.
-
+    # @return [Listable] the first item in the list.
     def item
       raise NoMethodError if empty?
-      head.next
+      @_chain
     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.
-
+    # @param  other [Object] the object to compare with.
+    # @return [true] if the given object is a list and the items are equal.
+    # @return [false] otherwise.
     def ==(other)
       return false unless other.is_a? self.class
-      return false unless other.count == @_item_count
+      return false unless other.count == count
 
       other_items = other.each_item
       each_item.all? { |item| item == other_items.next }
@@ -72,86 +54,10 @@ module Linked
 
     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
-    # will be returned.
-    #
-    # n - the number of items to return.
-    #
-    # Returns, for different values of n:
-    # n == 0) nil
-    # n == 1) an item if the list contains one, or nil
-    #  n > 1) an array of between 0 and n items, depending on how many are in
-    #         the list
-
-    def first(n = 1)
-      raise ArgumentError, 'n cannot be negative' if n < 0
-
-      return first_item_after head, n, count unless block_given?
-
-      item = head
-      items_left = count
-
-      items_left.times do
-        break if yield next_item = item.next
-        item = next_item
-        items_left -= 1
-      end
-
-      first_item_after item, n, items_left
-    end
-
-    # Access the last n item(s) in the list. The items will retain thier order.
-    # If a block is given each item, starting with the last in the list, will be
-    # yielded to it. The first item for which the block returns true and the
-    # n - 1 items directly preceding it will be returned.
-    #
-    # n - the number of items to return.
-    #
-    # Returns, for different values of n:
-    # n == 0) nil
-    # n == 1) an item if the list contains one, or nil
-    #  n > 1) an array of between 0 and n items, depending on how many are in
-    #         the list
-
-    def last(n = 1)
-      raise ArgumentError, 'n cannot be negative' if n < 0
-
-      return last_item_before tail, n, count unless block_given?
-
-      item = tail
-      items_left = count
-
-      items_left.times do
-        break if yield prev_item = item.prev
-        item = prev_item
-        items_left -= 1
-      end
-
-      last_item_before item, n, items_left
-    end
-
-    # Overrides the Enumerable#count method when given no argument to provide a
-    # fast item count. Instead of iterating over each item, the internal item
-    # count is returned.
-    #
-    # args - see Enumerable#count
-    #
-    # Returns the number of items counted.
-
-    def count(*args)
-      if args.empty? && !block_given?
-        @_item_count
-      else
-        super
-      end
-    end
-
-    # Returns true if the list does not contain any items.
-
+    # @return [true] if the list does not contain any items.
+    # @return [false] otherwise.
     def empty?
-      @_item_count == 0
+      nil.eql? @_chain
     end
 
     # Insert an item at the end of the list. If the given object is not an
@@ -160,12 +66,17 @@ module Linked
     #
     # See Item#append for more details.
     #
-    # object - the item to insert, or an arbitrary object.
-    #
-    # Returns self.
-
+    # @param object [#item, Object] the item to insert, or an arbitrary object.
+    # @return [self]
     def push(object)
-      tail.append object
+      item = coerce_item object
+
+      if empty?
+        @_chain = item
+      else
+        list_tail.append item
+      end
+
       self
     end
 
@@ -173,11 +84,18 @@ module Linked
 
     # Pop the last item off the list.
     #
-    # Returns the last item in the list, or nil if the list is empty.
-
+    # @return [Listable, nil] the last item in the list, or nil if the list is
+    #   empty.
     def pop
       return nil if empty?
-      last.delete
+
+      if list_tail.first?
+        item = last
+        @_chain = nil
+        item
+      else
+        list_tail.delete
+      end
     end
 
     # Insert an item at the beginning of the list. If the given object is not an
@@ -186,67 +104,49 @@ module Linked
     #
     # See Item#prepend for more details.
     #
-    # object - the item to insert, or an arbitrary object.
-    #
-    # Returns self.
-
+    # @param object [#item, Object] the item to insert, or an arbitrary object.
+    # @return [self]
     def unshift(object)
-      head.prepend object
+      item = coerce_item object
+      @_chain = empty? ? item.chain : @_chain.prepend(item)
+
       self
     end
 
     # Shift the first item off the list.
     #
-    # Returns the first item in the list, or nil if the list is empty.
-
+    # @return [Listable, nil] the first item in the list, or nil if the list is
+    #   empty.
     def shift
       return nil if empty?
-      first.delete
+
+      if list_head.last?
+        item = @_chain
+        @_chain = nil
+        item
+      else
+        old_head = list_head
+        @_chain = list_head.next
+        old_head.delete
+      end
     end
 
     # Check if an item is in the list.
     #
-    # item - Item, or any object that may be in the list.
-    #
-    # Returns true if the given item is in the list, otherwise false.
-
+    # @param  item [Object] any object that may be in the list.
+    # @return [true] if the given item is in the list.
+    # @return [false] otherwise.
     def include?(item)
-      item.in? self
-    rescue NoMethodError
-      false
-    end
-
-    # Iterates over each item in the list If a block is not given an enumerator
-    # is returned.
-
-    def each_item
-      return to_enum(__method__) { count } unless block_given?
-      return if empty?
-
-      item = head
-      loop { yield item = item.next }
-    end
-
-    alias each each_item
-
-    # Iterates over each item in the list in reverse order. If a block is not
-    # given an enumerator is returned.
-
-    def reverse_each_item
-      return to_enum(__method__) { count } unless block_given?
-      return if empty?
-
-      item = tail
-      loop { yield item = item.prev }
+      return false if empty?
+      # TODO: This works fine, but looks wrong.
+      @_chain.in_chain? item
     end
 
-    alias reverse_each reverse_each_item
-
     # Calls #freeze on all items in the list, as well as the head and the tail
     # (eol).
-
+    #
+    # @return [self]
     def freeze
-      @_eol.freeze
       each_item(&:freeze)
       super
     end
@@ -257,14 +157,13 @@ module Linked
     # Importantly this implementation supports nested lists and will return a
     # tree like structure.
 
-    def inspect(&block)
-      # Get the parents inspect output
-      res = [super]
+    def inspect_list(&block)
+      res = [block_given? ? yield(self) : object_identifier]
 
       each_item do |item|
         lines = item.inspect(&block).split "\n"
 
-        res.push (item.last? ? '└─╴' : '├─╴') + lines.shift
+        res.push((item.last? ? '└─╴' : '├─╴') + lines.shift)
         padding = item.last? ? '   ' : '│  '
         lines.each { |line| res.push padding + line }
       end
@@ -272,125 +171,49 @@ module Linked
       res.join("\n")
     end
 
+    alias inspect inspect_list
+
     # Protected factory method for creating items compatible with the list. This
     # 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 support different Item types.
     #
-    # args - any arguments will be passed on to Item.new.
-    #
-    # Returns a new Item.
-
+    # @param  args [Array<Object>] the arguments that are to be passed on to
+    #   `Item.new`.
+    # @return [Item] a new `Listable` item.
     protected def create_item(*args)
       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.
+    # Takes an arbitrary object and coerces it into an item compliant with the
+    # list. If the object is already an item it will be used as is. Otherwise
+    # #create_item will be called with the object as an argument.
     #
-    # n - the number of items that has been/will be added to the list.
-    #
-    # Returns updated the item count.
-
-    private def grow(n = 1)
-      @_item_count += n
-    end
-
-    # Internal method to shrink the list with n elements. Never call this method
-    # without also deleting the n elements.
-    #
-    # n - the number of items that has been/will be removed from the list.
-    #
-    # Returns updated the item count.
-
-    private def shrink(n = 1)
-      @_item_count -= n
+    # @param  [#item, Object] the object to coerce.
+    # @return [Listable] see `#create_item`.
+    private def coerce_item(object)
+      if object.respond_to? :item
+        object.item
+      else
+        create_item object
+      end
     end
 
-    # Private method to clear the list. Never call this method without also
-    # modifying the items in the list, as this operation leavs them in an
-    # inconsistant state. If the list items are kept, make sure to
-    # a) clear the `prev` pointer of the first item and
-    # b) clear the `next` pointer of the last item.
-
-    private def clear
-      @_eol.send :reset
-      @_item_count = 0
+    # Private method for clearing the list and bringing it to a pristine
+    # state.
+    private def reset_list
+      @_chain = nil
     end
 
-    # 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
-    # hold for the output to be valid:
-    # a) n > 0
-    # b) there are at least items_left items left
-    #
-    # item - the Item just before the item to start from.
-    # n - the number of items to return.
-    # items_left - the number of items left.
-    #
-    # Returns, for different values of n:
-    # n == 0) nil
-    # n == 1) an item if items_left > 0 or nil
-    #  n > 1) an array of items if items_left > 0 or an empty array
-
-    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.last?
-      return item.next if n == 1
-
-      n = items_left if n > items_left
-
-      arr = Array.new n
-      n.times { |i| arr[i] = item = item.next }
-      arr
-    rescue StopIteration
-      arr.compact! || arr
+    # Returns the first item item in the list, or nil if empty.
+    private def list_head
+      @_chain
     end
 
-    # 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
-    # the output to be valid:
-    # a) n > 0
-    # b) there are at least items_left items left
-    #
-    # item - the Item just after the item to start from.
-    # n - the number of items to return.
-    # items_left - the number of items left.
-    #
-    # Returns, for different values of n:
-    # n == 0) nil
-    # n == 1) an item if items_left > 0 or nil
-    #  n > 1) an array of items if items_left > 0 or an empty array
-
-    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.first?
-      return item.prev if n == 1
-
-      n = items_left if n > items_left
-
-      arr = Array.new n
-      (n - 1).downto(0) { |i| arr[i] = item = item.prev }
-      arr
-    rescue StopIteration
-      arr.compact! || arr
+    # Returns an the last item in the list, or nil if empty.
+    private def list_tail
+      @_chain.last_in_chain
     end
   end
 end