facets 2.8.2 → 2.8.3

data/AUTHORS

@@ -9,17 +9,19 @@
 The following developers have recently contributed to the development of Facets.
 They are held in the highest regard for their efforts.
 
-* Roger Pack          Added generational depth to Class#descendants.
-* Marco Otte-Witte    Fixed return value of Kernel#extend.
-* Mauro Tortonesi     Fixed issues with duration.rb and date.rb.
-* Sandor Szücs        Fixes for String#align_right and #align_left.
-* Tyler Rick          Fixed bug in Time#hence and #ago.
-* Brian Candler       Provided Enumerator::Filter.
-* Jeena Paradies      Provided INI implementation.
-* Robert Klemme       Fix for Enumerable#mode.
-* Daniel Schierbeck   Speed imporvements to odd? and even?
-* Ken Bloom           For DictionaryMatcher class (class might be renamed in future).
-* Matthew Harris      Incorporated very useful Duration class.
+* Lavir the Whiolet    Improved Range#at_rand and added File#ext.
+* Jean-Denis Vauguet   Added Pathname#visit.
+* Roger Pack           Added generational depth to Class#descendants.
+* Marco Otte-Witte     Fixed return value of Kernel#extend.
+* Mauro Tortonesi      Fixed issues with duration.rb and date.rb.
+* Sandor Szücs         Fixes for String#align_right and #align_left.
+* Tyler Rick           Fixed bug in Time#hence and #ago.
+* Brian Candler        Provided Enumerator::Filter.
+* Jeena Paradies       Provided INI implementation.
+* Robert Klemme        Fix for Enumerable#mode.
+* Daniel Schierbeck    Speed imporvements to odd? and even?
+* Ken Bloom            For DictionaryMatcher class (class might be renamed in future).
+* Matthew Harris       Incorporated very useful Duration class.
 
 == Recent Bug Reports
 

data/HISTORY.rdoc

@@ -1,5 +1,63 @@
 = Facets Release History
 
+== 2.8.3 / 2009-04-10
+
+New release which makes a few adjustments in Kernel core extensions,
+adds a few new extensions and additions, plus other small improvements.
+The biggest change is the addition of Recusor, which is created via
+Enumerable#recursive. This class is somewhat like Enumerator and
+provides a number of recursive methods.
+
+Changes:
+
+* 9 New Core Extensions
+
+  * Enumerable#recursive provides a number of other recursive methods.
+  * Enumerable#visit can be used to recursively iterate any Enumerable.
+  * Module#set has been added (from Sinatra).
+  * Symbol#/ is added to be like String#/.
+  * Struct#to_h is added and will ultimately replace Struct#attributes.
+  * ObjectSpace#reflect routes method calls to Kernel context.
+  * Hash#to_module converts a hash to mixin module (Jay Fields).
+  * Kernel#dup! is same as #try_dup from extlib.
+  * Add File#ext which is a useful variation of #extname (Lavir the Whiolet).
+
+* 3 Core Extensions Renamed
+
+  * renamed #set_from to #assign_from (alias remains until Kernel#set is considerd).
+  * rename #populate to #assign and improve.
+  * Kernel#instance_vars is now Kernel#instance and also more useful.
+
+* 1 Core Deprecation
+
+  * Removed #instance_eval hack.
+
+* 2 Core Bug Fixes
+
+  * #map_with_index now uses #each_with_index.
+  * #to_proc_with_response spelling correction.
+
+* 1 Core Adjustment
+
+  * Aliased #metadef to #meta_def.
+
+* 3 New More Libraries
+
+  * casting_hash.rb provides CastingHash class, a hash with flexible keys and values.
+  * prepend.rb allows for AOP-like inclusion of modules.
+  * roman.rb provides simple roman numeral extensions to String and Integer.
+
+* 5 More Improvements
+
+  * Pathname#visit for iterating all entries beneath a path (chikamichi).
+  * Pathname#to_str, b/c Pathname is basically a type of String (from extlib).
+  * Range#at_rand in random.rb handles Float ranges (Lavir the Whiolet).
+  * FileUtils#cp_rx provides controlled copies.
+  * Stash class in stash.rb is improved and is now available as a stand-alone library.
+  * ioredirect.rb has been removed as IORedirect no longer worked.
+  * plugin_manager.rb has been removed. Use 'plugin' gem instead.
+
+
 == 2.8.2 / 2009-02-22
 
 This release fixes a bug by removing Numeric#size. Turns out that was a

data/lib/core/facets/array/recursive.rb

@@ -0,0 +1,91 @@
+require 'facets/enumerable/recursive'
+
+class Array
+
+  # Apply a block to array, and recursively apply that block
+  # to each subarray.
+  #
+  #   arr = ["a", ["b", "c", nil], nil]
+  #   arr.recursively{|a| a.compact! }
+  #   => ["a", ["b", "c"]]
+  #
+  def recursive(opts={}, &block)
+    if block
+      a = inject([]) do |array, value|
+        if value.is_a?(Array)
+          array << value.recursive(&block)
+        else
+          array << value
+        end
+        array
+      end
+      yield a
+    else
+      Recursor.new(self, opts)
+    end
+  end
+
+  # In place form of #recursive.
+
+  def recursive!(&block)
+    r = recursive(&block)
+    raise TypeError unless Array === r
+    replace(r)
+  end
+
+ 
+  #
+  class Recursor < ::Enumerable::Recursor
+
+    # Recursively iterate over the Array's elements.
+    # If an element is an Array or responds to #to_ary
+    # then it will be itereated over as well.
+    #
+    def each(&block)
+      if block_given?
+        @enum.each do |e|
+          if Array === e || e.respond_to?(:to_ary)
+            e.to_ary.recursive.each(&block)
+          else
+            block.call(e)
+          end
+        end
+      else
+        to_enum(:each)
+      end
+    end
+
+    # Returns a new array created by traversing the array and its
+    # sub-arrays, executing the given block on the elements.
+    #
+    #   h = ["A", "B", ["X", "Y"]]
+    #
+    #   g = h.recursive.map{ |e| e.downcase }
+    #
+    #   g = ["a", "b", ["x", "y"]]
+    #
+    # CREDIT: Trans
+
+    def map(&block)
+      if block_given?
+        @enum.map do |e|
+          if Array === e || e.respond_to?(:to_ary)
+            e.to_ary.recursive.map(&block)
+          else
+            block.call(e)
+          end
+        end
+      else
+        to_enum(:map)
+      end
+    end
+
+    # Like #map, but will change the array in place.
+
+    def map!(&block)
+      replace(map(&block))
+    end
+
+  end
+
+end

data/lib/core/facets/array/recursively.rb

@@ -7,9 +7,8 @@ class Array
   #   arr.recursively{|a| a.compact! }
   #   => ["a", ["b", "c"]]
   #
-  # TODO: Can this be generalized in Enumerbale?
-
   def recursively(&block)
+    warn "Use #recusive instead of #recursively for future versions"
     a = inject([]) do |array, value|
       if value.is_a?(Array)
         array << value.recursively(&block)
@@ -28,3 +27,4 @@ class Array
   end
 
 end
+

data/lib/core/facets/array/traverse.rb

@@ -1,18 +1,35 @@
 class Array
 
+  # Returns a new array created by traversing the array and its
+  # sub-arrays, executing the given block on the elements.
   #
+  #   h = ["A", "B", ["X", "Y"]]
+  #
+  #   g = h.traverse{ |e| e.downcase }
+  #
+  #   g = ["a", "b", ["x", "y"]]
+  #
+  # This is the same as <code>recursive.map</code> and will
+  # likely be deprecated in the future because of it.
+  #
+  # CREDIT: Trans
 
   def traverse(&block)
-    map do |item|
-      if item.is_a?(self.class)
-        item.traverse(&block)
-      else
-        yield item
+    if block_given?
+      map do |e|
+        if e.respond_to?(:to_ary)
+          e.to_ary.traverse(&block)
+        else
+          block.call(e)
+        end
       end
+    else
+      to_enum(:traverse)
     end
   end
 
-  #
+  # Like #recursive_map, but will change the
+  # array in place.
 
   def traverse!(&block)
     replace(traverse(&block))

data/lib/core/facets/enumerable/collisions.rb

@@ -0,0 +1 @@
+require 'facets/enumerable/commonality'

data/lib/core/facets/enumerable/commonality.rb

@@ -4,7 +4,7 @@ module Enumerable
   # If no block is given objects are considered to be equal if they
   # return the same value for Object#hash and if obj1 == obj2.
   #
-  #   [1, 2, 2, 3, 4, 4].commonality # => { 2 => [2], 4 => [4] }
+  #   [1, 2, 2, 3, 4, 4].commonality # => { 2 => [2, 2], 4 => [4, 4] }
   #
   #   ["foo", "bar", "a"].commonality { |str| str.length }
   #   # => { 3 => ["foo, "bar"] }
@@ -14,7 +14,7 @@ module Enumerable
   #
   # CREDIT: Florian Gross
 
-  def commonality( &block )
+  def commonality(&block)
     had_no_block = !block
     block ||= lambda { |item| item }
     result = Hash.new { |hash, key| hash[key] = Array.new }
@@ -29,5 +29,7 @@ module Enumerable
     return result
   end
 
+  alias_method :collisions, :commonality
+
 end
 

data/lib/core/facets/enumerable/graph.rb

@@ -1 +1,37 @@
-require 'facets/enumerable/mash'
+module Enumerable
+
+  # Like <tt>#map</tt>/<tt>#collect</tt>, but generates a Hash. The block
+  # is expected to return two values: the key and the value for the new hash.
+  #
+  #   numbers  = (1..3)
+  #   squares  = numbers.graph{ |n| [n, n*n] }   # { 1=>1, 2=>4, 3=>9 }
+  #   sq_roots = numbers.graph{ |n| [n*n, n] }   # { 1=>1, 4=>2, 9=>3 }
+  #
+  # CREDIT: Andrew Dudzik (adudzik), Trans
+
+  def graph(&yld)
+    if yld
+      h = {}
+      each do |*kv|
+        r = yld[*kv]
+        case r
+        when Hash
+          nk, nv = *r.to_a[0]
+        when Range
+          nk, nv = r.first, r.last
+        else
+          nk, nv = *r
+        end
+        h[nk] = nv
+      end
+      h
+    else
+      Enumerator.new(self,:graph)
+    end
+  end
+
+  # Alias for #graph, which stands for "map hash".
+  alias_method :mash, :graph
+
+end
+

data/lib/core/facets/enumerable/mash.rb

@@ -1,39 +1 @@
-module Enumerable
-
-  # Like <tt>#map</tt>/<tt>#collect</tt>, but generates a Hash. The block
-  # is expected to return two values: the key and the value for the new hash.
-  #
-  #   numbers  = (1..3)
-  #   squares  = numbers.mash { |n| [n, n*n] }   # { 1=>1, 2=>4, 3=>9 }
-  #   sq_roots = numbers.mash { |n| [n*n, n] }   # { 1=>1, 4=>2, 9=>3 }
-  #
-  # The name "mash" stands for "map hash".
-  #
-  # CREDIT: Andrew Dudzik (adudzik), Trans
-
-  def mash(&yld)
-    if yld
-      h = {}
-      each do |*kv|
-        r = yld[*kv]
-        case r
-        when Hash
-          nk, nv = *r.to_a[0]
-        when Range
-          nk, nv = r.first, r.last
-        else
-          nk, nv = *r
-        end
-        h[nk] = nv
-      end
-      h
-    else
-      Enumerator.new(self,:mash)
-    end
-  end
-
-  # Alias for #mash. This is the original name of this method.
-  alias_method :graph, :mash
-
-end
-
+require 'facets/enumerable/graph'

data/lib/core/facets/enumerable/recursive.rb

@@ -0,0 +1,75 @@
+module Enumerable
+
+  def recursive(opts={})
+    Recursor.new(self, opts)
+  end
+
+  # Recursor "functor".
+  #
+  # NOTE: THIS IS A WORK IN PROGRESS!
+  #
+  class Recursor
+
+    def initialize(enum, opts)
+      @enum = enum
+      @opts = opts
+    end
+
+    # Recursive iteration over enumerables.
+    #
+    #   [1, 2, [3, 4]].recursive.each{ |e| p e }
+    #
+    # produces
+    #
+    #   1
+    #   2
+    #   3
+    #   4
+    #
+    # NOTE: Technically this should check for the proper conversion
+    # method if applicable, eg. #to_ary for Array, rather than
+    # just checking the class type. In the future this may be 
+    # generally supported if Facets ever adds a "class know-thy-self"
+    # library. In the meantime override in classes are required to
+    # incorporate this.
+
+    def each(&b)
+      @enum.each{ |*v| process(:each, *v, &b) }
+    end
+
+    # Recursive map.
+    #
+    #   [1, 2, ['a', 'b']].recursive.map{ |e| e.succ }
+    #   #=> [1, 2, ['b', 'c']]
+    #
+    def map(&b)
+      @enum.map{ |*v| process(:map, *v, &b) }
+    end
+
+    #
+    #def graph(&b)
+    #  @enum.graph{ |*v| process(:graph, *v, &b) }
+    #end
+
+    private
+
+    #
+    def process(op, v, &b)
+      case v
+      when String # b/c of 1.8
+        b.call(v)
+      when @enum.class
+        v.recursive(@opts).send(op,&b)
+      else
+        #if @opts[:skip] && Enumerable === v
+        #  v
+        #else
+          b.call(v)
+        #end
+      end
+    end
+
+  end
+
+end
+

data/lib/core/facets/enumerable/visit.rb

@@ -0,0 +1,30 @@
+module Enumerable
+
+  # Recursively iterate over all Enumerable elements, or
+  # subset given <code>:type=>[type1, type2, ...]</code>.
+  #
+  #   [1, 2, 8..9].visit{ |x| x.succ }
+  #   # => [2, 3, [9, 10]]
+  #
+  def visit(opts={}, &block)
+    type = opts[:type] ? [opts[:type]].flatten : [Enumerable]
+    skip = opts[:skip]
+
+    map do |v|
+      case v
+      when String # b/c of 1.8
+        b.call(v)
+      when *type
+        v.recursive(opts).send(op,&b)
+      else
+        if skip && Enumerable === v
+          v
+        else
+          b.call(v)
+        end
+      end
+    end
+  end
+
+end
+