facets 2.8.4 → 2.9.0.pre.1

data/lib/core/facets/comparable/cmp.rb

@@ -14,6 +14,7 @@ module Comparable
   def cmp(o)
     self<=>o
   end
+
 end
 
 class String
@@ -27,6 +28,8 @@ class String
   #   "xyz".cmp("abc")   #=>  1
   #
   # CREDIT: Peter Vanbroekhoven
+  #
+  # TODO: Move String#cmp to string/ directory.
 
   def cmp(other)
     return -1 if length < other.length

data/lib/core/facets/comparable/op_get.rb

@@ -0,0 +1,45 @@
+module Comparable
+
+  # Automatically generate comparitive definitions based on
+  # attribute fields.
+  #
+  #   include Comparable[:a, :b]
+  #
+  # is equivalent to including a module containing:
+  #
+  #   def <=>(other)
+  #     cmp = self.a <=> other.a; return cmp unless cmp == 0
+  #     cmp = self.b <=> other.b; return cmp unless cmp == 0
+  #     0
+  #   end
+  #
+  def self.[](*accessors)
+    Module.new do
+      include Comparable
+      define_method(:comparability){ accessors }
+      define_method(:<=>) do |other|
+        comparability.each do |a|
+          cmp = (send(a) <=> other.send(a))
+          break cmp unless cmp == 0
+        end
+      end
+    end
+  end
+
+end
+
+# Would it be nice if we could define comparability for all objects?
+# Then Comparable[] method would not be needed. Just:
+#
+#   module Comparable
+#
+#    def <=>(other)
+#      comparability.each do |field|
+#        cmp = send(field) <=> other.send(field); return cmp unless cmp == 0
+#      end
+#    end
+#
+#  end
+#
+# But I fear it might break other code.
+

data/lib/core/facets/dir/ascend.rb

@@ -4,15 +4,13 @@ class Dir
 
   # Ascend a directory path.
   #
+  #   a = []
+  #
   #   Dir.ascend("/var/log") do |path|
-  #     p path
+  #     a << path
   #   end
   #
-  # _produces_
-  #
-  #   /var/log
-  #   /var
-  #   /
+  #   a  #=> ['/var/log', '/var', '/']
   #
   # CREDIT: Daniel Berger, Jeffrey Schwab
   #
@@ -35,15 +33,13 @@ class Dir
 
   # Descend a directory path.
   #
+  #   d = []
+  #
   #   Dir.descend("/var/log") do |path|
-  #     p path
+  #     d << path
   #   end
   #
-  # _produces_
-  #
-  #   /
-  #   /var
-  #   /var/log
+  #   d  #=> ['/', '/var', '/var/log']
   #
   # CREDIT: Daniel Berger, Jeffrey Schwab
 

data/lib/core/facets/dir/each_child.rb

@@ -0,0 +1,16 @@
+class Dir
+
+  # Like #each, except the "." and ".." special files are ignored.
+  # You can use +ignore+ to override '.' and '..' and ignore 
+  # other entries via a exact match or regular expression.
+  #
+  # CREDIT: Tyler Rick
+  def each_child(*ignore)
+    ignore = ['.', '..'] if ignore.empty?
+    each do |file|
+      yield file unless ignore.any?{ |i| i === file }
+    end
+  end
+
+end
+

data/lib/core/facets/dir/multiglob.rb

@@ -2,10 +2,10 @@ class Dir
 
   # Like +glob+ but can take multiple patterns.
   #
-  #   Dir.multiglob( '*.rb', '*.py' )
+  #   Dir.multiglob('tmp/*.rb', 'tmp/*.py')
   #
   # Rather then constants for options multiglob accepts a trailing options
-  # hash of symbol keys.
+  # hash of symbol keys...
   #
   #   :noescape    File::FNM_NOESCAPE
   #   :casefold    File::FNM_CASEFOLD
@@ -13,35 +13,23 @@ class Dir
   #   :dotmatch    File::FNM_DOTMATCH
   #   :strict      File::FNM_PATHNAME && File::FNM_DOTMATCH
   #
-  # It also has an option for recurse.
+  # It also has an option for recurse...
   #
   #   :recurse     Recurively include contents of directories.
   #
   # For example
   #
-  #   Dir.multiglob( '*', :recurse => true )
+  #   Dir.multiglob('tmp/*', :recurse => true)
   #
   # would have the same result as
   #
-  #   Dir.multiglob('**/*')
+  #   Dir.multiglob('tmp/**/*')
   #
-  #--
-  # DEPRECATED
-  #
-  # Multiglob also accepts '+' and '-' prefixes. Any entry that begins with a '-'
-  # is treated as an exclusion glob and will be removed from the final result.
-  # For example, to collect all files in the current directory, less ruby scripts:
-  #
-  #   Dir.multiglob( '*', '-*.rb' )
-  #
-  # This is very useful in collecting files as specificed by a configuration
-  # parameter.
-  #++
   def self.multiglob(*patterns)
     options  = (Hash === patterns.last ? patterns.pop : {})
 
     if options.delete(:recurse)
-      #patterns += patterns.collect{ |f| File.join(f, '**', '**') }
+      ##patterns += patterns.collect{ |f| File.join(f, '**', '**') }
       multiglob_r(*patterns)
     end
 
@@ -65,26 +53,26 @@ class Dir
 
   # The same as +multiglob+, but recusively includes directories.
   #
-  #   Dir.multiglob_r( 'folder' )
+  #   Dir.multiglob_r('tmp')
   #
   # is equivalent to
   #
-  #   Dir.multiglob( 'folder', :recurse=>true )
+  #   Dir.multiglob('tmp', :recurse=>true)
   #
   # The effect of which is
   #
-  #   Dir.multiglob( 'folder', 'folder/**/**' )
+  #   Dir.multiglob('tmp', 'tmp/**/**')
   #
   def self.multiglob_r(*patterns)
-    options = (Hash === patterns.last ? patterns.pop : {})
+    options = Hash === patterns.last ? patterns.pop : {}
     matches = multiglob(*patterns)
     directories = matches.select{ |m| File.directory?(m) }
-    matches += directories.collect{ |d| multiglob_r(File.join(d, '**'), options) }.flatten
+    matches += directories.map{ |d| multiglob_r(File.join(d, '**'), options) }.flatten
     matches.uniq
-    #options = (Hash === patterns.last ? patterns.pop : {})
-    #options[:recurse] = true
-    #patterns << options
-    #multiglob(*patterns)
+    ##options = (Hash === patterns.last ? patterns.pop : {})
+    ##options[:recurse] = true
+    ##patterns << options
+    ##multiglob(*patterns)
   end
 
 end

data/lib/core/facets/dir/parent.rb

@@ -2,11 +2,14 @@ class Dir
 
   # Is a path parental to another?
   #
+  #   Dir.parent?('parent', 'parent/child')  #=> true
+  #
   # TODO: Needs improvement.
+  #
   # TODO: Instance version?
 
   def self.parent?(parent_path, child_path)
-    %r|^#{Regexp.escape(parent_path)}| =~ child_path
+    %r|^#{Regexp.escape(parent_path)}| =~ child_path ? true : false
   end
 
 end

data/lib/core/facets/dir/recurse.rb

@@ -1,7 +1,10 @@
 class Dir
 
-  # Recursively scan a directory and pass each file
-  # to the given block.
+  # Recursively scan a directory and pass each file to the given block.
+  #
+  #   Dir.recurse('tmp') do |path|
+  #     # ...
+  #   end
   #
   # CREDIT: George Moschovitis
   #
@@ -17,7 +20,7 @@ class Dir
       list << filename
       block.call(filename) if block
       if FileTest.directory?(filename) and not FileTest.symlink?(filename)
-        list.concat( Dir.recurse(filename, &block) )
+        list.concat(Dir.recurse(filename, &block))
       end
     end
     list

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

@@ -2,20 +2,58 @@ require 'facets/functor'
 
 module Enumerable
 
-  # Accumulate a set of a set.
+  # Accumulate a set of a set. For example, in an ORM design
+  # where `Group has_many User` we might have something
+  # equivalent to the following.
   #
-  # For example, in an ORM design if Group
-  # has_many User then
+  #   Group = Struct.new(:users)
+  #   User  = Struct.new(:name, :friends)
   #
-  #   groups.accumulate.users
+  #   user1 = User.new('John', [])
+  #   user2 = User.new('Jane', ['Jill'])
+  #   user3 = User.new('Joe' , ['Jack', 'Jim'])
   #
-  # will return a list of users from all groups.
+  #   group1 = Group.new([user1, user2])
+  #   group2 = Group.new([user2, user3])
   #
-  # CREDIT: George Moshchovitis
+  #   groups = [group1, group2]
+  #
+  # Now we can *accumulate* the users of all groups.
+  #
+  #   groups.accumulate.users  #=> [user1, user2, user3]
+  #
+  # You may pass an argument to perform chains, e.g. the following
+  # returns the names of users from all groups.
+  #
+  #   groups.accumulate(2).users.name  #=> ['John','Jane','Joe']
+  #
+  # Or we can gather all the friends of all users in groups.
+  #
+  #   groups.accumulate(2).users.friends  #=> ['Jill','Jack','Jim']
+  # 
+  # This is more convenient then the equivalent.
+  #
+  #   groups.accumulate.users.accumulate.friends  #=> ['Jill','Jack','Jim']
+  #
+  # CREDIT: George Moshchovitis, Daniel Emirikol
+
+  def accumulate(iterations=1)
+    return self if iterations == 0
+    Functor.new do |op, *args|
+      result = inject([]) { |a, x| a << x.send(op, *args) }.flatten.uniq
+      result.accumulate(iterations - 1)
+    end
+  end
 
-  def accumulate
-    @_accumulate ||= Functor.new do |op, *args|
-      inject([]) { |a, x| a << x.send(op, *args) }.flatten
+  # Same as #accumulate, but does not apply #uniq to final result.
+  #
+  #   groups.accumulate_all(2).users.friends  #=> ['Jill', 'Jill','Jack','Jim']
+  #
+  def accumulate_all(iterations=1)
+    return self if iterations == 0
+    Functor.new do |op, *args|
+      result = inject([]) { |a, x| a << x.send(op, *args) }.flatten
+      result.accumulate_all(iterations - 1)
     end
   end
 

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

@@ -6,10 +6,7 @@ module Enumerable
   # Returned elements are sorted by block.
   #
   #    %w{this is a test}.cluster_by {|x| x[0]}
-  #
-  # _produces_
-  #
-  #    [ ['a'], ['is'], ['this', 'test'] ]
+  #    #=> [ ['a'], ['is'], ['this', 'test'] ]
   #
   # CREDIT: Erik Veenstra
 

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

@@ -3,13 +3,11 @@ module Enumerable
   # A more versitle #compact method. It can be used to
   # collect and filter items out in one single step.
   #
-  #   [1,2,3].compact_map do |n|
-  #     n < 1 ? nil : n
+  #   c = [1,2,3].compact_map do |n|
+  #     n < 2 ? nil : n
   #   end
   #
-  # _produces_
-  #
-  #   [2,3]
+  #   c  #=> [2,3]
   #
   # CREDIT: Trans
   #

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

@@ -2,40 +2,52 @@ require 'facets/hash/count'
 
 module Enumerable
 
-  unless method_defined?(:count)
+  # Count the number of items in an enumerable equal (==)
+  # to the given object(s).
+  #
+  #   e = [ 'a', 1, 'a' ]
+  #
+  #   e.count(1)       #=> 1
+  #   e.count('a')     #=> 2
+  #
+  # The method can count more than one item by supplying additional
+  # arguments.
+  #
+  #   e.count('a', 1)  #=> 3
+  #
+  # A block may also be used to select countable entries.
+  #
+  #   e.count{ |x| String === x }  #=> 2
+  #
+  # Note that Hash#count only considers values.
+  #
+  #   e = { 'a' => 2, 'x' => 2, 'b' => 1 }
+  #
+  #   e.count(1)  #=> 1
+  #   e.count(2)  #=> 2
+  #
+  # NOTE: This is one of the few method overrides in Facets.
+  #
+  # CREDIT: Trans
 
-    # Count the number of items in an enumerable
-    # equal (==) to the given object(s).
-    #
-    #   e = [ 'a', '1', 'a' ]
-    #   e.count('1')     #=> 1
-    #   e.count('a')     #=> 2
-    #   e.count('a', 1)  #=> 3
-    #
-    # Note that Hash#count only considers values.
-    #
-    #   e = { 'a' => 2, 'x' => 2, 'b' => 1 }
-    #   e.count(1) #=> 1
-    #   e.count(2) #=> 2
-    #
-    # CREDIT: Trans
-
-    def count(*items, &block)
-      if block || !items.empty?
-        r = self
-        r = r.select(&block) if block
-        r = r.select{ |x| items.any?{ |i| i == x } } if !items.empty?
-        r.size
-      else
-        begin
-          size
-        rescue
-          i=0; each{ |e| i+=1 }; i
-        end
+  def count(*items, &block)
+    if block || !items.empty?
+      r = self
+      r = r.select(&block) if block
+      r = r.select{ |x| items.any?{ |i| i == x } } if !items.empty?
+      r.size
+    else
+      begin
+        size
+      rescue
+        i=0; each{ |e| i+=1 }; i
       end
     end
-
   end
 
 end
 
+class Array
+  remove_method(:count) rescue nil
+end
+

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

@@ -20,8 +20,7 @@ module Enumerable
   #   (1..1_000_000_000).
   #     defer { |out,i| out << i if i % 2 == 0 }.  # like select
   #     defer { |out,i| out << i + 100 }.          # like map
-  #     take(10).
-  #     each { |i| puts i }
+  #     take(10).to_a
   #
   # Use a method like to_a or to_h at the end of the chain when you want an
   # Array or Hash built with the results, or each{...} if you just want

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

@@ -8,13 +8,13 @@ module Enumerable
     # Say we want to count characters in a string. Using
     # the #each_with_object method we have:
     #
-    #    string.each_with_object(Hash.new(0)) do |c, h|
+    #    "string".each_with_object(Hash.new(0)) do |c, h|
     #      h[c] += 1
     #    end
     #
     # versus using #inject which would be:
     #
-    #    string.inject(Hash.new(0)) do |h, c|
+    #    "string".inject(Hash.new(0)) do |h, c|
     #      h[c] +=1
     #      h
     #    end