libis-workflow-mongoid 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0a259d21bb114e3b4397ecb6c1152769d9960965
-  data.tar.gz: c75a90afe74196dd1ab779cd37fc7012f2b04c0b
+  metadata.gz: ae15d66c11b105c5d81e707bad684d3b7f9805ec
+  data.tar.gz: 1116380cbcc99ae1bf7ba0aac642f12c633feac9
 SHA512:
-  metadata.gz: c3318624c4f63e725150382369c9bc29fedb501996cb37113cb7d57729090d024f81bf54bf5cdcd086b47e43d0c42e350b6d66342148024b77eeaca298debdae
-  data.tar.gz: 8f2b4c72528be421539f498166943cdcd5f228d7f6799b8889f4bbd9e58265bfe591c8f5ed16f68f55d98b19671ebabdac72f9e62646a6dc2b0a4bd0f9732d4d
+  metadata.gz: 082fee48cc81d1a54b0e451b93ab4704aa86aaaf8d479946bfbeeff886eabee7628b43730266c027f08b61fcfaf6eb7ec11c2bf27c60f5dfffc33f0fb79f50da
+  data.tar.gz: 4563f3ec708ecc6e72d05e1b7485422dae39b06080a7afa5ddba4be5df6481ea9aeac5387dc4e234ca54549fab37da23e71709008534244f4c7ae0096848abfe

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec name: 'libis-workflow-mongoid', development_group: :test
-

data/lib/libis/workflow/mongoid/base.rb

@@ -3,6 +3,7 @@ require 'mongoid'
 require 'mongoid/document'
 require 'yaml'
 require 'libis/tools/extend/hash'
+require 'map_with_indifferent_access'
 
 # require 'mongoid_indifferent_access'
 require_relative 'sequence'
@@ -15,6 +16,7 @@ module Libis
       module Base
 
         def self.included(klass)
+          klass.extend(ClassMethods)
           klass.class_eval do
             include ::Mongoid::Document
             include ::Mongoid::Timestamps::Created::Short
@@ -26,14 +28,50 @@ module Libis
           end
         end
 
+        module ClassMethods
+          def from_hash(hash)
+            self.create_from_hash(hash.cleanup, [:name])
+          end
+
+          def create_from_hash(hash, id_tags, &block)
+            hash = hash.key_strings_to_symbols
+            id_tags = id_tags.map(&:to_sym)
+            return nil unless id_tags.empty? || id_tags.any? { |k| hash.include?(k) }
+            tags = id_tags.inject({}) do |h, k|
+              v = hash.delete(k)
+              h[k] = v if v
+              h
+            end
+            item = tags.empty? ? self.new : self.find_or_initialize_by(tags)
+            block.call(item, hash) if block unless hash.empty?
+            item.assign_attributes(hash)
+            unless self.embedded?
+              item.save!
+            end
+            item
+          end
+
+          def indifferent_hash(field_name, method_name)
+            define_method method_name do
+              MapWithIndifferentAccess::Map.new(self.read_attribute(field_name))
+            end
+
+            define_method "#{method_name}=" do |value|
+              self.write_attribute(field_name, value)
+              self.send(method_name)
+            end
+          end
+
+        end
+
         def dup
           new_obj = self.class.new
           new_obj.copy_attributes(self)
         end
 
-        def info
-          result = self.attributes.reject { |k,v| v.blank? || volatile_attributes.include?(k) }
-          result = result.to_yaml.gsub(/!ruby\/hash:BSON::Document/,'')
+        def to_hash
+          result = self.attributes.reject { |k, v| v.blank? || volatile_attributes.include?(k) }
+          result = result.to_yaml.gsub(/!ruby\/hash:BSON::Document/, '')
           # noinspection RubyResolve
           result = YAML.load(result)
           result.key_strings_to_symbols!(recursive: true)
@@ -48,6 +86,7 @@ module Libis
         def volatile_attributes
           %w'_id c_at'
         end
+
         private
 
         def copy_attributes(other)

data/lib/libis/workflow/mongoid/job.rb

@@ -1,5 +1,4 @@
-# encoding: utf-8
-
+require 'map_with_indifferent_access'
 require 'libis/workflow/base/job'
 require 'libis/workflow/mongoid/base'
 
@@ -16,7 +15,7 @@ module Libis
 
         field :name, type: String
         field :description, type: String
-        field :input, type: Hash, default: -> { Hash.new }
+        field :_input, type: Hash, default: -> { Hash.new }
         field :run_object, type: String
         field :log_to_file, type: Boolean, default: false
         field :log_each_run, type: Boolean, default: false
@@ -30,6 +29,29 @@ module Libis
 
         belongs_to :workflow, polymorphic: true
 
+        def self.from_hash(hash)
+          self.create_from_hash(hash, [:name]) do |item, cfg|
+            item.workflow = Libis::Workflow::Mongoid.from_hash(name: cfg.delete(:workflow))
+          end
+        end
+
+        # def input
+        #   MapWithIndifferentAccess::Map.new(self.read_attribute(:_input))
+        # end
+        #
+        # def input=(hash)
+        #   self.write_attribute(:_input, hash)
+        #   self.input
+        # end
+
+        indifferent_hash :_input, :input
+
+        def to_hash
+          result = super
+          result[:input] = result.delete(:_input)
+          result
+        end
+
         def logger
           return ::Libis::Workflow::Mongoid::Config.logger unless self.log_to_file
           logger = ::Logging::Repository[self.name]

data/lib/libis/workflow/mongoid/run.rb

@@ -19,10 +19,14 @@ module Libis
         field :start_date, type: Time, default: -> { Time.now }
         field :log_to_file, type: Boolean, default: false
         field :log_level, type: String, default: 'DEBUG'
+        field :log_filename, type: String
 
         set_callback(:destroy, :before) do |document|
           wd = document.work_dir
           FileUtils.rmtree wd if wd && !wd.blank? && Dir.exist?(wd)
+          # noinspection RubyResolve
+          log_file = document.log_filename
+          FileUtils.rm(log_file) if log_file && !log_file.blank? && File.exist?(log_file)
         end
 
         index start_date: 1
@@ -30,23 +34,24 @@ module Libis
         belongs_to :job, polymorphic: true
         embeds_one :log_config, as: :log_configurator
 
-        def run
+        def run(action = :run)
           self.tasks = []
           self.items = []
           # noinspection RubySuperCallWithoutSuperclassInspection
-          super
+          super action
         end
 
         def logger
           unless self.log_to_file
             return self.job.logger
           end
-          logger = ::Logging::Repository[self.name]
+          logger = ::Logging::Repository.instance[self.name]
           return logger if logger
           unless ::Logging::Appenders[self.name]
+            self.log_filename ||= File.join(::Libis::Workflow::Mongoid::Config[:log_dir], "#{self.name}.log")
             ::Logging::Appenders::File.new(
                 self.name,
-                filename: File.join(::Libis::Workflow::Mongoid::Config[:log_dir], "#{self.name}.log"),
+                filename: self.log_filename,
                 layout: ::Libis::Workflow::Mongoid::Config.get_log_formatter,
                 level: self.log_level
             )

data/lib/libis/workflow/mongoid/version.rb

@@ -3,7 +3,7 @@
 module Libis
   module Workflow
     module Mongoid
-      VERSION = '2.0.2' unless const_defined? :VERSION # the guard is against a redefinition warning that happens on Travis
+      VERSION = '2.0.3' unless const_defined? :VERSION # the guard is against a redefinition warning that happens on Travis
     end
   end
 end

data/lib/libis/workflow/mongoid/work_item_base.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+require 'map_with_indifferent_access'
 require 'libis-workflow'
 
 module Libis
@@ -14,9 +14,9 @@ module Libis
 
             store_in collection: 'workflow_items'
 
-            field :options, type: Hash, default: -> { Hash.new }
-            field :properties, type: Hash, default: -> { Hash.new }
-            field :summary, type: Hash, default: -> { Hash.new }
+            field :_options, type: Hash, default: -> { Hash.new }
+            field :_properties, type: Hash, default: -> { Hash.new }
+            field :_summary, type: Hash, default: -> { Hash.new }
 
             has_many :logs, as: :logger, class_name: Libis::Workflow::Mongoid::LogEntry.to_s,
                      dependent: :destroy, autosave: true, order: :_id.asc do
@@ -39,9 +39,21 @@ module Libis
               document.logs.each { |log| log.destroy! }
             end
 
+            indifferent_hash :_options, :options
+            indifferent_hash :_properties, :properties
+            indifferent_hash :_summary, :summary
+
           end
         end
 
+        def to_hash
+          result = super
+          result[:options] = result.delete(:_options)
+          result[:properties] = result.delete(:_properties)
+          result[:summary] = result.delete(:_summary)
+          result
+        end
+
         def log_history
           # noinspection RubyResolve
           self.logs.log_history.all || []

data/lib/libis/workflow/mongoid/workflow.rb

@@ -1,5 +1,4 @@
-# encoding: utf-8
-
+require 'map_with_indifferent_access'
 require 'libis/workflow/base/workflow'
 require 'libis/workflow/mongoid/base'
 require 'libis/tools/config_file'
@@ -18,12 +17,23 @@ module Libis
 
         field :name, type: String
         field :description, type: String
-        field :config, type: Hash, default: -> { Hash.new }
+        field :_config, type: Hash, default: -> { Hash.new }
 
         index({name: 1}, {unique: 1})
 
         has_many :jobs, as: :workflow, dependent: :destroy, autosave: true, order: :c_at.asc
 
+        def self.from_hash(hash)
+          self.create_from_hash(hash, [:name]) do |item, cfg|
+            if (value = item.read_attribute(:config))
+              item.write_attribute(:_config, value)
+              item.remove_attribute(:config)
+            end
+            item.configure(cfg.key_strings_to_symbols(recursive: true).merge(name: item.name))
+            cfg.clear
+          end
+        end
+
         def self.load(file_or_hash)
           config = Libis::Tools::ConfigFile.new
           config << file_or_hash
@@ -33,6 +43,18 @@ module Libis
           workflow
         end
 
+        indifferent_hash :_config, :config
+
+        def to_hash
+          result = super
+          result[:config] = result.delete(:_config)
+          result
+        end
+
+        def input
+          Libis::Tools::DeepStruct.new(super)
+        end
+
       end
     end
   end

data/lib/map_with_indifferent_access.rb

@@ -0,0 +1,20 @@
+require "map_with_indifferent_access/version"
+require "map_with_indifferent_access/wraps_collection"
+require "map_with_indifferent_access/map"
+require "map_with_indifferent_access/list"
+require "map_with_indifferent_access/values"
+require "map_with_indifferent_access/normalization"
+require 'forwardable'
+
+module MapWithIndifferentAccess
+  class << self
+    extend Forwardable
+
+    # @!method new
+    #   Creates and returns a new instance of {Map}.
+    #
+    #   @return [Map]
+    #   @see Map#initialize
+    def_delegator Map, :new
+  end
+end

data/lib/map_with_indifferent_access/list.rb

@@ -0,0 +1,867 @@
+module MapWithIndifferentAccess
+
+  class List
+    extend Forwardable
+    include MapWithIndifferentAccess::WrapsCollection
+
+    def first
+      self.at(0)
+    end
+
+    def last
+      self.at(-1)
+    end
+
+    # Try to convert `from_obj` into a {List}.
+    #
+    # @return [List]
+    #   converted object if `from_obj` is convertible.
+    #
+    # @return [nil]
+    #   if `from_obj` cannot be converted for any reason.
+    def self.try_convert(from_obj)
+      if self === from_obj
+        from_obj
+      else
+        array = ::Array.try_convert( from_obj )
+        new( array ) if array
+      end
+    end
+
+    # Try to convert `obj`, which might be a {List} into an
+    # `Array`.
+    #
+    # @return [Array]
+    #   converted object if `obj` is convertible.
+    #
+    # @return [nil]
+    #   if `obj` cannot be converted for any reason.
+    def self.try_deconstruct(obj)
+      if self === obj
+        obj.inner_array
+      elsif obj.respond_to?(:to_ary )
+        a = obj.to_ary
+        ::Array === a ? a : nil
+      else
+        nil
+      end
+    end
+
+    # @!attribute inner_array
+    #   @return [Array]
+    #
+    #   Alias for {#inner_collection}.  The encapsulated `Array`
+    #   instance.
+    alias inner_array inner_collection
+
+    # @!method to_a
+    #
+    #   Alias for {#inner_collection}.  Returns the
+    #   encapsulated `Array` instance.
+
+    # Use class_eval to hide the aliasing from Yard doc.
+    class_eval 'alias to_a inner_collection', __FILE__, __LINE__
+
+    # Initializes a new instance of {List} that encapsulates a
+    # new empty `Array` or the `Array` coerced from the given
+    # `basis`.
+    #
+    # When a {List} is given as a `basis`, this results on the
+    # given and new instances sharing the same {#inner_array}.
+    # There is no obvious reason to do that on purpose, but there
+    # is also no particular harm in allowing it to happen.
+    #
+    # @param [Array, List, Object] basis
+    #   An `Array` or an object that can be implicitly coerced to
+    #   an `Array`
+    def initialize(basis = [])
+      use_basis = basis
+      use_basis = basis.inner_array if self.class === basis
+      use_basis = ::Array.try_convert( use_basis )
+      raise ArgumentError, "Could not convert #{basis.inspect} into an ::Array" unless use_basis
+      @inner_collection = use_basis
+    end
+
+    # Element Assignment — Sets the element at index, or replaces
+    # a subarray from the start index for length elements, or
+    # replaces a subarray specified by the range of indices.
+    #
+    # The given object or array is internalized befor being
+    # ussed for assignment into the {#inner_array}.
+    #
+    # @return the given value or array.
+    #
+    # @see Values.internalize
+    # @see #push
+    # @see #unshift
+    #
+    # @overload []=(index, value)
+    #   @param index [Fixnum]
+    #   @param value [Object]
+    #
+    # @overload []=(start, length, array_or_value)
+    #   @param start [Fixnum]
+    #   @param length [Fixnum]
+    #   @param array_or_value [Array, List Object, nil]
+    #
+    # @overload []=(range, array_or_value)
+    #   @param range [Ramge]
+    #   @param array_or_value [Array, List, Object, nil]
+    def []=(index, length_or_value, *maybe_value)
+      arg_count = 2 + maybe_value.length
+      unless (2..3) === arg_count
+        raise ArgumentError, "wrong number of arguments (#{arg_count} for 2..3)"
+      end
+
+      if maybe_value.empty?
+        maybe_length = []
+        value_or_values = length_or_value
+      else
+        maybe_length = [length_or_value]
+        value_or_values = maybe_value.first
+      end
+
+      if (
+        ( !maybe_length.empty? || Range === index ) &&
+        ( value_array = List.try_deconstruct( value_or_values ) )
+      )
+        value_array = value_array.map{ |v| Values << v }
+        inner_array[ index, *maybe_length ] = value_array
+      else
+        value = Values << value_or_values
+        inner_array[ index, *maybe_length ] = value
+      end
+    end
+
+    # @!method []
+    #   Returns the element at index, or returns a subarray
+    #   starting at the start index and continuing for length
+    #   elements, or returns a subarray specified by range of
+    #   indices.
+    #
+    #   Externalizes the result before returning it.
+    #
+    #   @see Values.externalize
+    #
+    #   @overload [](index)
+    #     @param index [Fixnum]
+    #     @return [Object]
+    #
+    #   @overload [](start, length)
+    #     @param start [Fixnum]
+    #     @param length [Fixnum]
+    #     @return [List]
+    #
+    #   @overload [](range)
+    #     @param range [Range]
+    #     @return [List]
+    #
+    #   @overload slice(index)
+    #     @param index [Fixnum]
+    #     @return [Object]
+    #
+    #   @overload slice(start, length)
+    #     @param start [Fixnum]
+    #     @param length [Fixnum]
+    #     @return [List]
+    #
+    #   @overload slice(range)
+    #     @param range [Range]
+    #     @return [List]
+
+    ['[]', 'slice'].each do |method_name|
+      class_eval <<-EOS, __FILE__, __LINE__ + 1
+
+        def #{method_name}(index, *maybe_length)
+          arg_count = 1 + maybe_length.length
+          unless (1..2) === arg_count
+            raise ArgumentError, "wrong number of arguments (\#{arg_count} for 1..2)"
+          end
+
+          if !maybe_length.empty? || Range === index
+            value_array = inner_array.#{method_name}( index, *maybe_length )
+            value_array.map!{ |v| Values >> v }
+            List.new( value_array )
+          else
+            value = inner_array.#{method_name}( index )
+            Values >> value
+          end
+        end
+
+      EOS
+    end
+
+    # Returns the externalization of the element at `index`. A
+    # negative index counts from the end of the list. Returns
+    # `nil` if the index is out of range.
+    #
+    # @see #[]
+    def at(index)
+      item = inner_array.at( index )
+      Values >> item
+    end
+
+    # Append. Pushes the given object on to the end of the list.
+    # Returns the array itself, so several appends may be chained
+    # together.
+    #
+    # Internalizes the given onject before appending it to the
+    # target's {#inner_array}.
+    #
+    # @return [List]
+    # @see #push
+    def <<(value)
+      value = Values << value
+      inner_array << value
+      self
+    end
+
+    # Append. Pushes the given object(s) on to the end of the
+    # list. Returns the array itself, so several appends may be
+    # chained together.
+    #
+    # Internalizes each given object before appending it to the
+    # target's {#inner_array}.
+    #
+    # @return [List]
+    # @see #<<
+    # @see #pop
+    # @see Values.internalize
+    def push(*values)
+      values.map!{ |v| Values << v }
+      inner_array.push *values
+      self
+    end
+
+    # Prepends objects to the front of the list, moving other
+    # elements upwards.
+    #
+    # Internalizes each value before prepending it to the
+    # target's {#inner_array}.
+    #
+    # See also {#shift} for the opposite effect.
+    #
+    # @return [List]
+    # @see #shift
+    # @see Values.internalize
+    def unshift(*values)
+      values.map!{ |v| Values << v }
+      inner_array.unshift *values
+      self
+    end
+
+    # Inserts the given values before the element with the given
+    # index.
+    #
+    # Internalizes the values before inserting them into the
+    # target's {#inner_array}.
+    #
+    # Negative indices count backwards from the end of the array,
+    # where -1 is the last element. If a negative index is used,
+    # the given values will be inserted after that element, so
+    # using an index of -1 will insert the values at the end of
+    # the list.
+    #
+    # @return [List]
+    # @see Values.internalize
+    def insert(index, *values)
+      values.map!{ |v| Values << v }
+      inner_array.insert(index, *values)
+      self
+    end
+
+    # Appends elements of `other` (a `List` or other
+    # `Array`-like object) to the target `List`.
+    #
+    # @param other [List, Array, Object]
+    # @return [List] The target list.
+    #
+    # @see #+
+    def concat(other)
+      other = self.class.try_deconstruct(other) || other
+      inner_array.concat other
+      self
+    end
+
+    # Returns a {List} containing the elements in self
+    # corresponding to the given selector(s).
+    #
+    # The selectors may be either `Integer` indices or
+    # `Range`s.
+    #
+    # @return List
+    def values_at(*indexes)
+      inner_result = inner_array.values_at( *indexes )
+      Values >> inner_result
+    end
+
+    # Tries to retrieve the element at position `index`, but
+    # raises an `IndexError` exception or uses a default value
+    # when an invalid index is referenced.
+    #
+    # Returns the externalization of the retrieved value.
+    #
+    # @see MapWithIndifferentAccess::Values.externalize
+    #
+    # @overload fetch(index)
+    #   Tries to retrieve the element at position `index`, but
+    #   raises an `IndexError` exception if the referenced index
+    #   lies outside of the array bounds.
+    #
+    #   @raise [IndexError]
+    #
+    # @overload fetch(index, default)
+    #   Tries to retrieve the element at position `index`, but
+    #   uses the given default if the referenced index lies
+    #   outside of the array bounds.
+    #
+    # @overload fetch(index)
+    #   @yieldparam index
+    #   Tries to retrieve the element at position `index`, but if
+    #   the referenced index lies outside of the array bounds,
+    #   calls the given block, and uses the block call result.
+    def fetch(index, *args)
+      item =
+        if block_given?
+          inner_array.fetch( index, *args ){ |idx| yield idx }
+        else
+          inner_array.fetch( index, *args )
+        end
+      Values >> item
+    end
+
+    # @!method shift(*maybe_n)
+    #   Removes and returns the first element or first `n`
+    #   elements of the array, shifting all of the other elements
+    #   downward.
+    #
+    #   Returns the externalization of the removed element or
+    #   array of elements
+    #
+    #   See {#unshift} for the opposite effect.
+    #
+    #   @see #unshift
+    #   @see #pop
+    #
+    #   @overload shift()
+    #     Removes the first element and returns it, shifting all
+    #     other elements down by one. Returns nil if the array is
+    #     empty.
+    #
+    #     @return [Object, nil]
+    #
+    #   @overload shift(n)
+    #     Returns a {List} of the first `n` elements (or less) just
+    #     like `array.slice!(0, n)` does, but also removing those
+    #     elements from the target.
+    #
+    #     @return [List]
+
+    # @!method pop(*maybe_n)
+    # Removes and returns the last element or last `n` elements
+    # of the array.
+    #
+    # Returns the externalization of the removed element or array
+    # of elements
+    #
+    # See {#push} for the opposite effect.
+    #
+    # @see #push
+    # @see #shift
+    #
+    # @overload pop()
+    #   Removes the last element and returns it. Returns nil if
+    #   the array is empty.
+    #
+    #   @return [Object, nil]
+    #
+    # @overload pop(n)
+    #   Returns a {MapWithIndifferentAccess::List} of the last
+    #   `n` elements (or less) just like `array.slice!(-n, n)`
+    #   does, but also removing those elements from the target.
+    #
+    #   @param n [Fixnum]
+    #   @return [MapWithIndifferentAccess::List]
+    #
+
+    %w(shift pop).each do |method_name|
+      class_eval <<-EOS, __FILE__, __LINE__ + 1
+
+        def #{method_name}(*maybe_n)
+          arg_count = maybe_n.length
+          unless (0..1) === arg_count
+            raise ArgumentError, "wrong number of arguments (\#{arg_count} for 0..1)"
+          end
+          if maybe_n.empty?
+            Values >> inner_array.#{method_name}
+          else
+            inner_result = inner_array.#{method_name}( *maybe_n )
+            List.new( inner_result )
+          end
+        end
+
+      EOS
+    end
+
+    # Deletes the element at the specified `index`, returning the
+    # externalization of that element, or `nil` if the index is
+    # out of range.
+    #
+    # @param index [Fixnum]
+    # @return [Object, nil]
+    #
+    # @see #slice
+    # @see Values.externalize
+    def delete_at(index)
+      inner_result = inner_array.delete_at( index )
+      Values >> inner_result
+    end
+
+    # @!method &(other)
+    #   @param other [List, Array, Object]
+    #   @return [List]
+    #
+    #   Set Intersection.  Returns a new {List} containing
+    #   elements common to the target {List} and `other` (a
+    #   `List` or other `Array`-like object), excluding any
+    #   duplicate items.  The order is preserved from the
+    #   original list.
+    #
+    #   It compares elements using their `#hash` and `#eql?`
+    #   methods for efficiency.
+    #
+    #   Note that this does not recongnize items of `Map` type as
+    #   equal just because they are equal by `#==`, which can be
+    #   the case when they have equivalent keys that differ by
+    #   `String`/`Symbol` type. You might therefore wish to call
+    #   {#&} for lists that have first had their keys
+    #   deeply-stringified or deeply-symbolized.
+
+    # @!method |(other)
+    #   @param other [List, Array, Object]
+    #   @return [List]
+    #
+    #   Set Union.  Returns a new {List} by joining the target
+    #   `List` with `other` (a `List` or other `Array`-like
+    #   object), excluding any duplicates and preserving the
+    #   order from the original `List`.
+    #
+    #   It compares elements using their `#hash` and `#eql?`
+    #   methods for efficiency.
+    #
+    #   Note that this does not recongnize items of `Map` type as
+    #   equal just because they are equal by `#==`, which can be
+    #   the case when they have equivalent keys that differ by
+    #   `String`/`Symbol` type. You might therefore wish to call
+    #   {#|} for lists that have first had their keys
+    #   deeply-stringified or deeply-symbolized.
+
+    # @!method +(other)
+    #   @param other [List, Array, Object]
+    #   @return [List]
+    #
+    #   Concatenation.  Returns a new {List} built by
+    #   concatenating `other` (a `List` or other `Array`-like
+    #   object) to the target `List`.
+    #
+    #   @see #concat
+
+    # @!method -(other)
+    #   @param other [List, Array, Object]
+    #   @return [List]
+    #
+    #   Difference.  Returns a new {List} that is a copy of the
+    #   original, removing any items that also appear in
+    #   `other` (a `List` or other `Array`-like object).  The
+    #   order is preserved from the original `List`.
+    #
+    #   It compares elements using their `#hash` and `#eql?`
+    #   methods for efficiency.
+    #
+    #   Note that this does not recongnize items of `Map` type as
+    #   equal just because they are equal by `#==`, which can be
+    #   the case when they have equivalent keys that differ by
+    #   `String`/`Symbol` type. You might therefore wish to call
+    #   {#-} for lists that have first had their keys
+    #   deeply-stringified or deeply-symbolized.
+
+    %w( & | + - ).each do |method_name|
+      class_eval <<-EOS, __FILE__, __LINE__ + 1
+
+        def #{method_name}(other)
+          other = self.class.try_deconstruct( other ) || other
+          inner_result = inner_array.#{method_name}(other)
+          List.new( inner_result )
+        end
+
+      EOS
+    end
+
+    # @!method join(separator=$,)
+    #   @param separator [String]
+    #   @return [String]
+    #
+    #   Returns a string consisting of `String`-converted item
+    #   values from the target `List` separated by the
+    #   `separator` string.  If no `separator` or `nil` is given,
+    #   uses the value of `$,` as the separator.  Treats a `nil`
+    #   `$,` value as a blank string.
+    #
+    #   The items are not externalized before being converted to
+    #   `String`s, so `my_map.join` is exactly equivalent to
+    #   `my_map.inner_array.join`.
+    #
+    #   @see Array#join
+    def_delegator :inner_array, :join
+
+    # Repetition.
+    #
+    # @overload *(n_copies)
+    #   @return [Map]
+    #
+    #   Returns a new `List` built by concatenating `n_copies`
+    #   copies of itself together.
+    #
+    # @overload *(separator)
+    #   @return [String]
+    #
+    #   Equivalent to `target_list.join(separator)`.
+    def *(n_copies_or_separator)
+      result = inner_array * n_copies_or_separator
+      result = List.new( result ) if Array === result
+      result
+    end
+
+    # Deletes all items from self, the externalizations of which
+    # are equal to the externalization of `obj`.
+    #
+    # Returns the externalization of the last deleted item if
+    # applicable.
+    #
+    # @see Values.externalize
+    #
+    # @overload delete(obj)
+    #   Returns `nil` if no matching items are found.
+    #
+    # @overload delete(obj)
+    #   @yield
+    #   Returns the externalization of the block result is no
+    #   matching items are found.
+    def delete(obj)
+      obj = Values >> obj
+      removed_items = false
+      result = nil
+      inner_array.delete_if{ |v|
+        v = Values >> v
+        if v == obj
+          result = v
+          removed_items = true
+          true
+        end
+      }
+      if !removed_items && block_given?
+        result = Values >> yield( obj )
+      end
+      result
+    end
+
+    # Returns a new instance with duplicate items omitted.
+    # Items are considered equal if their `#hash` values are
+    # equal and comparison using `#eql?` returns `true`.
+    #
+    # If a block is given, then externalized items are passed to
+    # the block, and the return values from the block will be
+    # used for dupliacte-check comparison.
+    #
+    # Note that items externally represented as `Map`s that are
+    # equal according to {Map#==} will not necessarily be
+    # identified as duplicates since they can still differ
+    # according to {Map#eql} if their encapsulated `Hash`
+    # objects are unequal due to key `String`/`Symbol` type
+    # differences.  You might therefore want to ensure that the
+    # target `List` has been deeply stringified or symbolized
+    # before calling {#uniq!} on it.
+    #
+    # @return [List]
+    #
+    # @see #uniq!
+    def uniq
+      result = dup
+      if block_given?
+        result.uniq!{ |item| yield( item ) }
+      else
+        result.uniq!
+      end
+      result
+    end
+
+    # Deletes duplicate items from the target's {#inner_array},
+    # leaving only unique items remaining. Items are considered
+    # equal if their `#hash` values are equal and comparison
+    # using `#eql?` returns `true`.
+    #
+    # Returns the target `List` if any duplicates were found and
+    # removed.  Otherwise, returns `nil`.
+    #
+    # If a block is given, then externalized items are passed to
+    # the block, and the return values from the block will be
+    # used for dupliacte-check comparison.
+    #
+    # Note that items externally represented as `Map`s that are
+    # equal according to {Map#==} will not necessarily be
+    # identified as duplicates since they can still differ
+    # according to {Map#eql} if their encapsulated `Hash`
+    # objects are unequal due to key `String`/`Symbol` type
+    # differences.  You might therefore want to ensure that the
+    # target `List` has been deeply stringified or symbolized
+    # before calling {#uniq} on it.
+    #
+    # @return [List, nil]
+    #
+    # @see #uniq
+    def uniq!
+      inner_result = 
+        if block_given?
+          inner_array.uniq!{ |item|
+            yield( Values >> item )
+          }
+        else
+          inner_array.uniq!
+        end
+
+      inner_result && self
+    end
+
+    # Equality. The target is equal to the given `Array`-like
+    # object if both contain the same number of elements, and
+    # externalizations of corresponding items in itself and the
+    # given object are equal according to `#==`.
+    #
+    # @return [Boolean]
+    #
+    # @see Values.externalize
+    def ==(other)
+      same_class = self.class === other
+
+      return false unless same_class || other.respond_to?(:to_ary )
+
+      # Optimizations
+      return true if equal?( other )
+      return true if same_class && inner_array == other.inner_array
+
+      return false unless length == other.length
+      zip( other ).all? { |(v,other_v)| v == Values >> other_v }
+    end
+
+    # @param [List, Array, Object]
+    # @return [1, 0, -1, nil]
+    #
+    # Comparison.  Returns an integer (-1, 0, or +1) if this
+    # `List` is less than, equal to, or greater than `other`, and
+    # `other` is a `List` or other `Array`-like object that can
+    # be coerced to a `List`.
+    #
+    # Each externaized item in the target `List` is compared to
+    # the corresponding externalized item in `other` (using the
+    # `<=>` operator).  As soon as a comparison is non zero (i.e.
+    # the two corresponding elements are not equal), that result
+    # is returned for the whole array comparison.
+    #
+    # If all the elements are equal, then the result is based on
+    # a comparison of the list lengths.  Thus, two `List`s are
+    # "equal" according to {#<=>} if, and only if, they have the
+    # same length and the value of each element is equal to the
+    # value of the corresponding element in the other list.
+    #
+    # `nil` is returned if `other` is not a `List` or `Array`like
+    # object or if the comparison of two elements returns `nil`.
+    #
+    # @see Array#<=>
+    def <=>(other)
+      return nil unless \
+        List === other || (
+          other.respond_to?(:to_ary ) && other.respond_to?(:length )
+        )
+      other = Values >> other
+      rel_order( other )
+    end
+
+    # Calls the given block once for each item in the target's
+    # {#inner_array}, passing the externalization of the item to
+    # the block.
+    #
+    # @see MapWithIndifferentAccess::Values.externalize
+    #
+    # @overload each
+    #   @yieldparam item
+    #   @return [List]
+    #
+    # @overload each
+    #   @return [Enumerator]
+    def each
+      inner_array.each do |item|
+        item = Values >> item
+        yield item
+      end
+    end
+
+    # @!method assoc(value)
+    #   Searches through elements of the target `List` that are
+    #   also externally represented as `List`s, comparing the
+    #   first item in each of those with `value` using {#==}.
+    #
+    #   Returns the first item from the target that matches (is
+    #   the first associated `List`) or nil of no match is found.
+    #
+    #   @return [List, nil]
+    #
+    #   @see Array#assoc
+    #   @see #rassoc
+
+    # @!method rassoc(value)
+    #   Searches through elements of the target `List` that are
+    #   also externally represented as `List`s, comparing the
+    #   second item in each of those with `value` using {#==}.
+    #
+    #   Returns the first item from the target that matches (is
+    #   the first associated `List`) or nil of no match is found.
+    #
+    #   @return [List, nil]
+    #
+    #   @see Array#rassoc
+    #   @see #assoc
+
+    [ ['assoc', 0 ], ['rassoc', 1 ] ].each do |(method_name,search_col)|
+      class_eval <<-EOS, __FILE__, __LINE__
+
+        def #{method_name}(value)
+          result = nil
+          each do |item|
+            next unless List === item && item.length > #{search_col}
+            result = item if item[#{search_col}] == value
+          end
+          result
+        end
+
+      EOS
+    end
+
+    # Works identically to `Array#bsearch` except that
+    # externalized values are passed to the block, and the
+    # externalized result is returned.
+    #
+    # @overload bsearch
+    #   @yieldparam x
+    #   @return [Object, nil]
+    #
+    # @overload bsearch
+    #   @return [Enumerator]
+    def bsearch
+      return to_enum(:bsearch) unless block_given?
+      inner_result = inner_array.bsearch{ |x| yield Values >> x }
+      Values >> inner_result
+    end
+
+    # @!method collect!
+    #   Invokes the given block once for each externalized item
+    #   from the target `List`, replacing the element with the
+    #   internalization of the value returned by the block.
+    #
+    #   If no block is given, returns an `Enumerator` instead.
+    #
+    #   @yieldparam extern_item
+    #   @return [List, Enumerable]
+    #
+    #   @see Enumerable#collect
+    #
+    #   @overload collect!
+    #   @overload map!
+
+    %w(collect! map!).each do |method_name|
+      class_eval <<-EOS, __FILE__, __LINE__ + 1
+
+        def #{method_name}
+          return to_enum( :#{method_name} ) unless block_given?
+
+          inner_array.#{method_name}{ |item|
+            item = Values >> item
+            mapped_outer = yield( item )
+            Values << mapped_outer
+          }
+          self
+        end
+
+      EOS
+    end
+
+    # Yields every combination of length n of elements from the
+    # target `List` in the form of a `List` and then returns the
+    # target `List` itself.
+    #
+    # Makes no guarantees about the order in which the
+    # combinations are yielded.
+    #
+    # If no block is given, an `Enumerator` is returned instead.
+    #
+    # @overload combination(n)
+    #   @param n [Fixnum]
+    #   @yieldparam combination [List]
+    #   @return [List]
+    #
+    # @overload combination(n)
+    #   @param n [Fixnum]
+    #   @return [Enumerator]
+    def combination(n)
+      return to_enum( :combination, n ) unless block_given?
+
+      inner_array.combination n do |inner_combos|
+        yield List.new( inner_combos )
+      end
+      self
+    end
+
+    # Removes `nil` elements from the target `List`.
+    #
+    # Returns `nil` if no changes were made.  Otherwise returns
+    # the `List`.
+    #
+    # @return [List, nil]
+    #
+    # @see #compact
+    def compact!
+      inner_array.compact! && self
+    end
+
+    # Returns a copy of the target `List` with all `nil` items
+    # removed.
+    #
+    # @return [List]
+    #
+    # @see #compact!
+    def compact
+      result = dup
+      result.compact!
+      result
+    end
+
+    protected
+
+    def rel_order(other_list)
+      length_rel = length <=> other_list.length
+      return other_list.reverse_rel_order(self) if length_rel == 1
+
+      rel = 0
+      zip other_list do |a,b|
+        rel = a <=> b
+        break unless rel == 0
+      end
+      rel == 0 ? length_rel : rel
+    end
+
+    def reverse_rel_order(other_list)
+      rel = rel_order(other_list)
+      rel.nil? ? nil : -rel
+    end
+  end
+
+end