jinx 2.1.1

data/lib/jinx/helpers/array.rb

@@ -0,0 +1,108 @@
+require 'jinx/helpers/class'
+
+class Array
+  # The EMPTY_ARRAY constant is an immutable empty array, used primarily as a default argument.
+  class << EMPTY_ARRAY ||= Array.new
+    def <<(value)
+      Jinx.fail(NotImplementedError, "Modification of the constant empty array is not supported")
+    end
+  end
+
+  # Relaxes the Ruby Array methods which take an Array argument to allow collection Enumerable arguments.
+  [:|, :+, :-, :&].each do |meth|
+    redefine_method(meth) do |old_meth|
+      lambda { |other| send(old_meth, other.collection? ? other.to_a : other) }
+    end
+  end
+
+  redefine_method(:flatten) do |old_meth|
+    # if an item is a non-Array collection, then convert it into an array before recursively flattening the list
+    lambda { map { |item| item.collection? ? item.to_a : item }.send(old_meth) }
+  end
+
+  # Returns an array containing all but the first item in this Array. This method is syntactic sugar for
+  # +self[1..-1]+ or +last(length-1)+.
+  #
+  # @return [Array] an array the tail of this array
+  def rest
+    self[1..-1]
+  end
+
+  alias :tail :rest
+
+  # Deletes items from this array which do not satisfy the given block.
+  #
+  # @yield [item] the retention test
+  # @yieldparam item an item in this array
+  # @return [Array] this array
+  def keep_if
+    delete_if { |item| not yield(item) }
+  end
+
+  # Prints the content of this array as a series, e.g.:
+  #   [1, 2, 3].to_series #=> "1, 2 and 3"
+  #   [1, 2, 3].to_series('or') #=> "1, 2 or 3"
+  #
+  # If a block is given to this method, then the block is applied before the series is formed, e.g.:
+  #   [1, 2, 3].to_series { |n| n + 1 } #=> "2, 3 and 4"
+  def to_series(conjunction=nil)
+    conjunction ||= 'and'
+    return map { |item| yield item }.to_series(conjunction) if block_given?
+    padded_conjunction = " #{conjunction} "
+    # join all but the last item as a comma-separated list and append the conjunction and last item
+    length < 2 ? to_s : self[0...-1].join(', ') + padded_conjunction + last.to_s
+  end
+
+  # Returns a new Hash generated from this array of arrays by associating the first element of each
+  # member to the remaining elements. If there are only two elements in the member, then the first
+  # element is associated with the second element. If there is less than two elements in the member,
+  # the first element is associated with nil. An empty array is ignored.
+  #
+  # @example
+  #   [[:a, 1], [:b, 2, 3], [:c], []].to_assoc_hash #=> { :a => 1, :b => [2,3], :c => nil }
+  # @return [Hash] the first => rest hash
+  def to_assoc_hash
+    hash = {}
+    each do |item|
+      Jinx.fail(ArgumentError, "Array member must be an array: #{item.pp_s(:single_line)}") unless Array === item
+      key = item.first
+      if item.size < 2 then
+        value = nil
+      elsif item.size == 2 then
+        value = item[1]
+      else
+        value = item[1..-1]
+      end
+      hash[key] = value unless key.nil?
+    end
+    hash
+  end
+
+  alias :base__flatten :flatten
+  private :base__flatten
+  # Recursively flattens this array, including any collection item that implements the +to_a+ method.
+  def flatten
+    # if any item is a Set or Java Collection, then convert those into arrays before recursively flattening the list
+    if any? { |item| Set === item or Java::JavaUtil::Collection === item } then
+      return map { |item| (Set === item or Java::JavaUtil::Collection === item) ? item.to_a : item }.flatten
+    end
+    base__flatten
+  end
+
+  # Concatenates the other Enumerable to this array.
+  #
+  # @param [#to_a] other the other Enumerable
+  # @raise [ArgumentError] if other does not respond to the +to_a+ method
+  def add_all(other)
+    return concat(other) if Array === other
+    begin
+      add_all(other.to_a)
+    rescue NoMethodError
+      raise e
+    rescue
+      Jinx.fail(ArgumentError, "Can't convert #{other.class.name} to array")
+    end
+  end
+
+  alias :merge! :add_all
+end

data/lib/jinx/helpers/boolean.rb

@@ -0,0 +1,42 @@
+module Jinx
+  # Boolean marks the +true+ and +false+ primitive objects.
+  module Boolean
+    # The match for a +true+ String.
+    TRUE_REGEXP = /^(t(rue)?|y(es)?|1)$/i
+  
+    # The match for a +false+ String.
+    FALSE_REGEXP = /^(f(alse)?||no?|0)$/i
+  
+    # Converts the given object to a Boolean as follows:
+    # * If the object is nil or Boolean, then the unconverted value
+    # * 1 -> true
+    # * 0 -> false
+    # * A {TRUE_REGEXP} match -> true
+    # * A {FALSE_REGEXP} match -> false
+    #
+    # @param for the object to convert
+    # @return [Boolean, nil] the corresponding Boolean
+    # @raise [ArgumentError] if the value cannot be converted
+    def self.for(obj)
+      case obj
+      when nil then nil
+      when true then true
+      when false then false
+      when 1 then true
+      when 0 then false
+      when TRUE_REGEXP then true
+      when FALSE_REGEXP then false
+      else
+        raise ArgumentError.new("Value cannot be converted to boolean: '#{obj}'")
+      end
+    end
+  end
+end
+
+class TrueClass
+  include Jinx::Boolean
+end
+
+class FalseClass
+  include Jinx::Boolean
+end

data/lib/jinx/helpers/case_insensitive_hash.rb

@@ -0,0 +1,39 @@
+module Jinx
+  # CaseInsensitiveHash accesses entries in a case-insensitive String comparison. The accessor method
+  # key argument is converted to a String before look-up.
+  #
+  # @example
+  #   hash = CaseInsensitiveHash.new
+  #   hash[:UP] = "down"
+  #   hash['up'] #=> "down"
+  class CaseInsensitiveHash < Hash
+    def initialize
+      super
+    end
+
+    def [](key)
+      # if there is lower-case key association, then convert to lower-case and return.
+      # otherwise, delegate to super with the call argument unchanged. this ensures
+      # that a default block passed to the constructor will be called with the correct
+      # key argument.
+      has_key?(key) ? super(key.to_s.downcase) : super(key)
+    end
+
+    def []=(key, value)
+      super(key.to_s.downcase, value)
+    end
+
+    def has_key?(key)
+      super(key.to_s.downcase)
+    end
+
+    def delete(key)
+      super(key.to_s.downcase)
+    end
+
+    alias :store :[]=
+    alias :include? :has_key?
+    alias :key? :has_key?
+    alias :member? :has_key?
+  end
+end

data/lib/jinx/helpers/class.rb

@@ -0,0 +1,149 @@
+require 'enumerator'
+
+class Class
+  # Returns an Enumerable on this class and its ancestors.
+  def class_hierarchy
+    @class__hierarchy ||= Enumerable::Enumerator.new(self, :each_class_in_hierarchy)
+  end
+
+  # Returns this class's superclass, thereby enabling class ranges, e.g.
+  #   class A; end
+  #   class B < A; end
+  #   (B..Object).to_a #=> [B, A, Object]
+  alias :succ :superclass
+
+  private
+  
+  # Creates an alias for each accessor method of the given attribute.
+  #
+  # @example
+  #   class Person
+  #    attr_reader :social_security_number
+  #    attr_accessor :postal_code
+  #    alias_attribute(:ssn, :social_security_number)
+  #    alias_attribute(:zip_code, :postal_code)
+  #   end
+  #   Person.method_defined?(:ssn) #=> true
+  #   Person.method_defined?(:ssn=) #=> false
+  #   Person.method_defined?(:zip_code) #=> true
+  #   Person.method_defined?(:zip_code=) #=> true
+  def alias_attribute(aliaz, attribute)
+    alias_method(aliaz, attribute) if method_defined?(attribute)
+    writer = "#{attribute}=".to_sym
+    alias_method("#{aliaz}=".to_sym, writer) if method_defined?(writer)
+  end
+
+  # Creates new accessor methods for each _method_ => _original_ hash entry.
+  # The new _method_ offsets the existing Number _original_ attribute value by the given
+  # offset (default -1).
+  #
+  # @example
+  #   class OneBased
+  #     attr_accessor :index
+  #     offset_attr_accessor :zero_based_index => :index
+  #   end
+  #@param [{Symbol => Symbol}] hash the offset => original method hash
+  #@param [Integer, nil] offset the offset amount (default is -1) 
+  def offset_attr_accessor(hash, offset=nil)
+    offset ||= -1
+    hash.each do |method, original|
+      define_method(method) { value = send(original); value + offset if value } if method_defined?(original)
+      original_writer = "#{original}=".to_sym
+      if method_defined?(original_writer) then
+        define_method("#{method}=".to_sym) do |value|
+          adjusted = value - offset if value
+          send(original_writer, adjusted)
+        end
+      end
+    end
+  end
+
+  # Defines an instance variable accessor attribute whose reader calls the block given
+  # to this method to create a new instance variable on demand, if necessary.
+  #
+  # For example, the declaration
+  #   class AlertHandler
+  #     attr_create_on_demand_accessor(:pings) { Array.new }
+  #   end
+  # is equivalent to:
+  #   class AlertHandler
+  #     attr_writer :pings
+  #     def pings
+  #       instance_variable_defined?(@pings) ? @pings : Array.new
+  #     end
+  #   end
+  #
+  # This method is useful either as a short-hand for the create-on-demand idiom
+  # as shown in the example above, or when it is desirable to dynamically add a
+  # mix-in attribute to a class at runtime whose name is not known when the class
+  # is defined.
+  #
+  # @example
+  #   class AlertHandler
+  #     def self.handle(alert)
+  #       attr_create_on_demand_accessor(alert) { AlertQueue.new }
+  #     end
+  #   end
+  #   ...
+  #   AlertHandler.handle(:pings)
+  #   AlertHandler.new.pings #=> empty AlertQueue
+  #
+  # @param [Symbol] symbol the attribute to define
+  # @yield [obj] factory to create the new attribute value for the given instance
+  # @yieldparam obj the class instance for which the attribute will be set
+  def attr_create_on_demand_accessor(symbol)
+    attr_writer(symbol)
+    wtr = "#{symbol}=".to_sym
+    iv = "@#{symbol}".to_sym
+    # the attribute reader creates a new proxy on demand
+    define_method(symbol) do
+      instance_variable_defined?(iv) ? instance_variable_get(iv) : send(wtr, yield(self))
+    end
+  end
+
+  # Enumerates each class in the hierarchy.
+  #
+  # @yield [klass] the enumeration block
+  # @yieldparam [Class] klass the class in the hierarchy
+  def each_class_in_hierarchy
+    current = self
+    until current.nil?
+      yield current
+      current = current.superclass
+    end
+  end
+
+  # Redefines method using the given block. The block argument is a new alias for the old method.
+  # The block creates a proc which implements the new method body.
+  #
+  # @example
+  #   redefine_method(:ssn) { |omth| lambda { send(omth).delete('-').to_i } }
+  # @param [Symbol] method the method to redefine
+  # @yield [old_method] the redefinition Proc
+  # @yieldparam old_method [Symbol] the method being redefined
+  # @return [Symbol] an alias to the old method implementation
+  def redefine_method(method)
+    # make a new alias id method__base for the existing method.
+    # disambiguate with a counter suffix if necessary.
+    counter = 2
+    # make a valid alias base
+    old, eq = /^([^=]*)(=)?$/.match(method.to_s).captures
+    old.tr!('|', 'or')
+    old.tr!('&', 'and')
+    old.tr!('+', 'plus')
+    old.tr!('*', 'mult')
+    old.tr!('/', 'div')
+    old.gsub!(/[^\w]/, 'op')
+    base = "redefined__#{old}"
+    old_id = "#{base}#{eq}".to_sym
+    while method_defined?(old_id)
+      base = "#{base}#{counter}"
+      old_id = "#{base}#{eq}".to_sym
+      counter = counter + 1
+    end
+    alias_method(old_id, method)
+    body = yield old_id
+    define_method(method, body)
+    old_id
+  end
+end

data/lib/jinx/helpers/collection.rb

@@ -0,0 +1,33 @@
+class Object
+  # Returns whether this object is a collection capable of holding heterogenous items.
+  # An Object is a not a collection by default. Subclasses can override this method.
+  def collection?
+    false
+  end
+end
+
+module Enumerable
+  # Overrides {Object#collection?} to returns +true+, since an Enumerable is capable of
+  # holding heterogenous items by default. Subclasses can override this method.
+  def collection?
+    true
+  end
+end
+
+class String
+  # Overrides {Enumerable#collection?} to returns +false+, since a String is constrained
+  # to hold characters.
+  def collection?
+    false
+  end
+end
+
+module Jinx
+  module Collection
+    include Enumerable
+  end
+end
+
+module Java::JavaUtil::Collection
+  include Jinx::Collection
+end

data/lib/jinx/helpers/collections.rb

@@ -0,0 +1,11 @@
+# This file loads the definitions of useful collection mix-ins and utility classes.
+
+require 'jinx/helpers/collection'
+require 'jinx/helpers/array'
+require 'jinx/helpers/hashable'
+require 'jinx/helpers/hash'
+require 'jinx/helpers/set'
+require 'jinx/helpers/enumerable'
+require 'jinx/helpers/enumerate'
+require 'jinx/helpers/filter'
+require 'jinx/helpers/flattener'

data/lib/jinx/helpers/collector.rb

@@ -0,0 +1,20 @@
+module Jinx
+  # The Collector utility implements the {on} method to apply a block to a collection
+  # transitive closure.
+  module Collector
+    # Collects the result of applying the given block to the given obj.
+    # If obj is a collection, then collects the result of recursively calling this
+    # Collector on the enumerated members.
+    # If obj is nil, then returns nil.
+    # Otherwise, calls block on obj and returns the result.
+    #
+    # @example
+    #  Collector.on([1, 2, [3, 4]]) { |n| n * 2 } #=> [2, 4, [6, 8]]]
+    #  Collector.on(nil) { |n| n * 2 } #=> nil
+    #  Collector.on(1) { |n| n * 2 } #=> 2
+    # @param obj the collection or item to enumerate
+    def self.on(obj, &block)
+      obj.collection? ? obj.map { |item| on(item, &block) } : yield(obj) unless obj.nil?
+    end
+  end
+end

data/lib/jinx/helpers/conditional_enumerator.rb

@@ -0,0 +1,21 @@
+module Jinx
+  # ConditionalEnumerator applies a filter to another Enumerable.
+  #
+  # @example
+  #   ConditionalEnumerator.new([1, 2, 3]) { |i| i < 3 }.to_a #=> [1, 2]
+  class ConditionalEnumerator
+    include Collection
+
+    # Creates a ConditionalEnumerator which wraps the base Enumerator with a conditional filter.
+    def initialize(base, &filter)
+      @base = base
+      @filter = filter
+    end
+
+    # Applies the iterator block to each of this ConditionalEnumerator's base Enumerable items
+    # for which this ConditionalEnumerator's filter returns true.
+    def each
+      @base.each { |item| (yield item) if @filter.call(item) }
+    end
+  end
+end

data/lib/jinx/helpers/enumerable.rb

@@ -0,0 +1,242 @@
+require 'jinx/helpers/transformer'
+require 'jinx/helpers/multi_enumerator'
+
+module Enumerable
+  # Returns a new Hash generated from this Enumerable and an optional value generator block.
+  # This Enumerable contains the Hash keys. If the value generator block is given to this
+  # method then the block is called with each enumerated element as an argument to
+  # generate the associated hash value. If no block is given, then the values are nil.
+  #
+  # @example
+  #   [1, 2, 3].hashify { |item| item.modulo(2) } #=> { 1 => 1, 2 => 0, 3 => 1 }
+  #   [:a].hashify #=> { :a => nil }
+  # @return [Hash]
+  def hashify
+    hash = {}
+    each { |item| hash[item] = yield item if block_given? }
+    hash
+  end
+  
+  # Returns a new Hash generated from this Enumerable and a required value generator block.
+  # This Enumerable contains the Hash keys. The block is called with each enumerated
+  # element as an argument to generate the associated hash value.
+  # Only non-nil, non-empty values are included in the hash.
+  #
+  # @example
+  #   [1, 2, 3].to_compact_hash { |item| item.modulo(2) } #=> { 1 => 1, 2 => 0, 3 => 1 }
+  #   [1, 2, 3].to_compact_hash { |n| n.modulo(2) unless item > 2 } #=> {1 => 1, 2 => 0}
+  #   [1, 2, 3].to_compact_hash { |n| n > 2 } #=> {1 => false, 2 => false, 3 => true}
+  #   [1, 2, 3].to_compact_hash { |n| Array.new(n - 1, n) } #=> {2 => [2], 3 => [2, 3]}
+  # @return [Hash]
+  # @raise [ArgumentError] if the generator block is not given
+  # @see #hashify
+  def to_compact_hash
+    Jinx.fail(ArgumentError, "Compact hash builder is missing the value generator block") unless block_given?
+    to_compact_hash_with_index { |item, index| yield item }
+  end
+
+  # Returns a new Hash generated from this Enumerable with a block whose arguments include the enumerated item
+  # and its index. Every value which is nil or empty is excluded.
+  #
+  # @example
+  #   [1, 2, 3].to_compact_hash_with_index { |item, index| item + index } #=> { 1 => 1, 2 => 3, 3 => 5 }
+  # @yield [item, index] the hash value
+  # @yieldparam item the enumerated value
+  # @yieldparam index the enumeration index
+  # @return [Hash] this {Enumerable} converted to a hash by the given block
+  def to_compact_hash_with_index
+    hash = {}
+    self.each_with_index do |item, index|
+      next if item.nil?
+      value = yield(item, index)
+      next if value.nil_or_empty?
+      hash[item] = value
+    end
+    hash
+  end
+
+  # This method is functionally equivalent to +to_a.empty+ but is more concise and efficient.
+  #
+  # @return [Boolean] whether this Enumerable iterates over at least one item
+  def empty?
+    not any? { true }
+  end
+
+  # This method is functionally equivalent to +to_a.first+ but is more concise and efficient.
+  #
+  # @return the first enumerated item in this Enumerable, or nil if this Enumerable is empty
+  def first
+    detect { true }
+  end
+
+  # This method is functionally equivalent to +to_a.last+ but is more concise and efficient.
+  #
+  # @return the last enumerated item in this Enumerable, or nil if this Enumerable is empty
+  def last
+    detect { true }
+  end
+
+  # This method is functionally equivalent to +to_a.size+ but is more concise and efficient
+  # for an Enumerable which does not implement the {#size} method.
+  #
+  # @return [Integer] the count of items enumerated in this Enumerable
+  def size
+    inject(0) { |size, item| size + 1 }
+  end
+
+  alias :length :size
+
+  # @return [String] the content of this Enumerable as a series using {Array#to_series}
+  def to_series(conjunction=nil)
+    to_a.to_series
+  end
+
+  # Returns the first non-nil, non-false enumerated value resulting from a call to the block given to this method,
+  # or nil if no value detected.
+  #
+  # @example
+  #   [1, 2].detect_value { |item| item / 2 if item % 2 == 0 } #=> 1
+  # @return [Object] the detected block result
+  # @see #detect_with_value
+  def detect_value
+    each do |*item|
+      value = yield(*item)
+      return value if value
+    end
+    nil
+  end
+
+  # Returns the first item and value for which an enumeration on the block given to this method returns
+  # a non-nil, non-false value.
+  #
+  # @example
+  #   [1, 2].detect_with_value { |item| item / 2 if item % 2 == 0 } #=> [2, 1]
+  # @return [(Object, Object)] the detected [item, value] pair
+  # @see #detect_value
+  def detect_with_value
+    value = nil
+    match = detect do |*item|
+      value = yield(*item)
+    end
+    [match, value]
+  end
+
+  # Returns a new Enumerable that iterates over the base Enumerable items for which filter evaluates to a non-nil,
+  #  non-false value, e.g.:
+  #   [1, 2, 3].filter { |n| n != 2 }.to_a #=> [1, 3]
+  #
+  # Unlike select, filter reflects changes to the base Enumerable, e.g.:
+  #   a = [1, 2, 3]
+  #   filter = a.filter { |n| n != 2 }
+  #   a << 4
+  #   filter.to_a #=> [1, 3, 4]
+  #
+  # In addition, filter has a small, fixed storage requirement, making it preferable to select for large collections.
+  # Note, however, that unlike select, filter does not return an Array.
+  # The default filter block returns the passed item.
+  #
+  # @example
+  #   [1, nil, 3].filter.to_a #=> [1, 3]
+  # @yield [item] filter the selection filter
+  # @yieldparam item the collection member to filter
+  # @return [Enumerable] the filtered result
+  def filter(&filter)
+    Jinx::Filter.new(self, &filter)
+  end
+
+  # @return [Enumerable] an iterator over the non-nil items in this Enumerable
+  def compact
+    filter { |item| not item.nil? }
+  end
+
+  # @example
+  #   {:a => {:b => :c}, :d => [:e]}.enum_values.flatten.to_a #=> [:b, :c, :e]
+  # @return [Enumerable] the flattened result
+  def flatten
+    Jinx::Flattener.new(self).to_a
+  end
+
+  # Returns an Enumerable which iterates over items in this Enumerable and the other Enumerable in sequence.
+  # Unlike the Array plus (+) operator, {#union} reflects changes to the underlying enumerators.
+  #
+  # @example
+  #   a = [1, 2]
+  #   b = [4, 5]
+  #   ab = a.union(b)
+  #   ab #=> [1, 2, 4, 5]
+  #   a << 3
+  #   a + b #=> [1, 2, 4, 5]
+  #   ab #=> [1, 2, 3, 4, 5]
+  # @param [Enumerable] other the Enumerable to compose with this Enumerable
+  # @return [Enumerable] an enumerator over self followed by other
+  def union(other)
+    Jinx::MultiEnumerator.new(self, other)
+  end
+
+  alias :+ :union
+
+  # @return an Enumerable which iterates over items in this Enumerable but not the other Enumerable
+  def difference(other)
+    filter { |item| not other.include?(item) }
+  end
+
+  alias :- :difference
+
+  # @return an Enumerable which iterates over items in this Enumerable which are also in the other Enumerable
+  def intersect(other)
+    filter { |item| other.include?(item) }
+  end
+
+  alias :& :intersect
+
+  # Returns a new Enumerable that iterates over the base Enumerable applying the transformer block to each item, e.g.:
+  #   [1, 2, 3].transform_value { |n| n * 2 }.to_a #=> [2, 4, 6]
+  #
+  # Unlike Array.map, {#wrap} reflects changes to the base Enumerable, e.g.:
+  #   a = [2, 4, 6]
+``#   transformed = a.wrap { |n| n * 2 }
+  #   a << 4
+  #   transformed.to_a #=> [2, 4, 6, 8]
+  #
+  # In addition, transform has a small, fixed storage requirement, making it preferable to select for large collections.
+  # Note, however, that unlike map, transform does not return an Array.
+  #
+  # @yield [item] the transformer on the enumerated items
+  # @yieldparam item an enumerated item
+  # @return [Enumerable] an enumeration on the transformed values
+  def transform(&mapper)
+    Jinx::Transformer.new(self, &mapper)
+  end
+  
+  alias :wrap :transform
+  
+  def join(sep = $,)
+    to_a.join(sep)
+  end
+  
+  # Sorts this collection's members with a partial sort operator, i.e. the comparison returns -1, 0, 1 or nil.
+  # The resulting sorted order places each non-nil comparable items in the sort order. The order of nil
+  # comparison items is indeterminate.
+  #
+  # @example
+  #    [Array, Numeric, Enumerable, Set].partial_sort #=> [Array, Numeric, Set, Enumerable]
+  # @return [Enumerable] the items in this collection in partial sort order
+  def partial_sort
+    unless block_given? then return partial_sort { |item1, item2| item1 <=> item2 } end
+    sort { |item1, item2| yield(item1, item2) or 1 }
+  end
+  
+  # Sorts this collection's members with a partial sort operator on the results of applying the block.
+  #
+  # @return [Enumerable] the items in this collection in partial sort order
+  def partial_sort_by
+    partial_sort { |item1, item2| yield(item1) <=> yield(item2) }
+  end
+  
+  # @yield [item] the transformer on the enumerated items
+  # @yieldparam item an enumerated item
+  # @return [Enumerable] the mapped values excluding null values
+  def compact_map(&mapper)
+    wrap(&mapper).compact
+  end
+end