facets 2.4.5 → 2.5.0

data/lib/more/facets/filter.rb

@@ -0,0 +1,121 @@
+require 'facets/enumerable/take'
+require 'facets/enumerator'
+
+module Enumerable
+
+  # Without a block: wrap the Enumerable object in such a way that map,
+  # select and similar operations are performed "horizontally" across a
+  # series of blocks, instead of building an array of results at each step.
+  # This reduces memory usage, allows partial results to be provided
+  # early, and permits working with infinite series.
+  #
+  #   (1..1_000_000_000).filter.select{ |i| i % 2 == 0 }.
+  #                             map{ |i| i + 100 }.
+  #                             take(10).to_a
+  #
+  # With a block: the block acts as an arbitrary filter on the data. Unlike
+  # map, it can choose to drop elements from the result, and/or add
+  # additional ones. The first object passed to the block is the receiver
+  # of the output.
+  #
+  #   (1..1_000_000_000).
+  #     filter { |out,i| out << i if i % 2 == 0 }.  # like select
+  #     filter { |out,i| out << i + 100 }.          # like map
+  #     take(10).each { |i| puts i }
+  #
+  # Use a method like to_a or to_h at the end of the chain if you want an
+  # Array or Hash built with the results, or each { ... } if you just want
+  # to output each result and discard it.
+  #
+  def filter(&blk)
+    if block_given?
+      Enumerator::Filter.new do |output|
+        each do |*input|
+          yield output, *input
+        end
+      end
+    else
+      Enumerator::Filter.new do |output|
+        each do |*input|
+          output.yield *input
+        end
+      end
+    end
+  end
+
+  # = Filterable
+  #
+  # Classes which include Enumerable::Filterable will get versions
+  # of map, select etc. which return a Filter, so that they work
+  # horizontally without creating intermediate arrays.
+  #
+  module Filterable
+    def map
+      Enumerator::Filter.new do |output|
+        each do |*input|
+          output.yield yield(*input)
+        end
+      end
+    end
+    alias :collect :map
+
+    def select
+      Enumerator::Filter.new do |output|
+        each do |*input|
+          output.yield(*input) if yield(*input)
+        end
+      end
+    end
+    alias :find_all :select
+
+    def reject
+      Enumerator::Filter.new do |output|
+        each do |*input|
+          output.yield(*input) unless yield(*input)
+        end
+      end
+    end
+
+    # Limit to the first n items in the list
+
+    def take(n)
+      Enumerator::Filter.new do |output|
+        count = 0
+        each do |*input|
+          break if count >= n
+          output.yield(*input)
+          count += 1
+        end
+      end
+    end
+
+    # Skip the first n items in the list
+
+    def skip(n)
+      Enumerator::Filter.new do |output|
+        count = 0
+        each do |*input|
+          output.yield(*input) if count >= n
+          count += 1
+        end
+      end
+    end
+
+    # TODO: add more methods, e.g. grep, take_while etc.
+  end
+
+end # module Enumerable
+
+
+class Enumerator
+
+  # = Enumerator::Filter
+  #
+  # A class like Enumerator, but which has 'lazy' versions of map, select etc.
+  #
+  class Filter < Enumerator
+    include Enumerable::Filterable
+  end
+
+end
+

data/lib/more/facets/inheritor.rb

@@ -1,30 +1,7 @@
 # = Inheritor
 #
-# Inheritor providse a means to store and inherit data via
-# the class heirarchy. An inheritor creates two methods
-# one named after the key that provides a reader. And one
-# named after key! which provides the writer. (Because of
-# the unique nature of inheritor the reader and writer
-# can't be the same method.)
-#
-#   class X
-#     inheritor :foo, [], :+
-#   end
-#
-#   class Y < X
-#   end
-#
-#   X.x! << :a
-#   X.x => [:a]
-#   Y.x => [:a]
-#
-#   Y.x! << :b
-#   X.x => [:a]
-#   Y.x => [:a, :b]
-#
-# It is interesting to note that the only reason inheritor is needed at all
-# is becuase Ruby does not allow modules to be inherited at the class-level, or
-# conversely that the "class-levels" of classes are not modules instead.
+#  Inheritor providse a means to store and inherit data via
+#  the class heirarchy.
 #
 # == Authors
 #
@@ -43,44 +20,45 @@
 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 # FOR A PARTICULAR PURPOSE.
 
-#require 'facets/module/class_extension'
 require 'facets/class_extension'
 
-# = Inheritor
-#
-# Inheritor providse a means to store and inherit data via
-# the class heirarchy. An inheritor creates two methods
-# one named after the key that provides a reader. And one
-# named after key! which provides the writer. (Because of
-# the unique nature of inheritor the reader and writer
-# can't be the same method.)
-#
-#   class X
-#     inheritor :foo, [], :+
-#   end
-#
-#   class Y < X
-#   end
-#
-#   X.x! << :a
-#   X.x => [:a]
-#   Y.x => [:a]
-#
-#   Y.x! << :b
-#   X.x => [:a]
-#   Y.x => [:a, :b]
-#
-# It is interesting to note that the only reason inheritor is needed at all
-# is becuase Ruby does not allow modules to be inherited at the class-level, or
-# conversely that the "class-levels" of classes are not modules instead.
-
 class Object
 
+  # = Inheritor
+  #
   # Create an inheritor "class attribute".
-  def inheritor( key, obj, op=nil )
+  #
+  # Inheritor providse a means to store and inherit data via
+  # the class heirarchy. An inheritor creates two methods
+  # one named after the key that provides a reader. And one
+  # named after key! which provides the writer. (Because of
+  # the unique nature of inheritor the reader and writer
+  # can't be the same method.)
+  #
+  #   class X
+  #     inheritor :foo, [], :+
+  #   end
+  #
+  #   class Y < X
+  #   end
+  #
+  #   X.x! << :a
+  #   X.x => [:a]
+  #   Y.x => [:a]
+  #
+  #   Y.x! << :b
+  #   X.x => [:a]
+  #   Y.x => [:a, :b]
+  #
+  # It is interesting to note that the only reason inheritor is needed at all
+  # is becuase Ruby does not allow modules to be "inherited" at the class-level,
+  # or conversely that the class-level is not a module instead.
+  # Otherwise using #super at the class-level would suffice.
+  #
+  def inheritor(key, obj, op=nil)
 
     # inhertiance operator
-    op = op ? op.to_sym : :add
+    op = op ? op.to_sym : :add  #NOTE: why #add ?
 
     # inheritor store a this level
     instance_variable_set("@#{key}", obj)
@@ -98,6 +76,7 @@ class Object
         else
           inheritor(key, obj.class.new, op)
         end
+        # -- old version --
         #if instance_variables.include?("@#{key}")
         #  instance_variable_get("@#{key}")
         #else
@@ -108,8 +87,8 @@ class Object
       end
     end
 
-    # TODO This is an issue if you try to include a module
-    # into Module or Class itself. How to fix?
+    # TODO: This is an issue if you try to include a module
+    #       into Module or Class itself. How to fix?
 
     # if the object is a module (not a class or other object)
     if self == Class or self == Module

data/lib/more/facets/iteration.rb

@@ -48,7 +48,7 @@ class Array
   #   []         [1]        [1,2]
   #   [2,3]      [3]        []
   #
-  #  CREDIT: Trans
+  # CREDIT: Trans
 
   def each_iteration
     if block_given?

data/lib/more/facets/kernel/meta.rb

@@ -20,7 +20,7 @@ module Kernel
   # TODO: Don't see any reason this can't go into core, but there is
   # a conflict with URI prior to 1.8.6, so it will have to wait.
   #
-  #  CREDIT: Trans
+  # CREDIT: Trans
 
   def meta
     @_meta_functor ||= Functor.new do |op,*args|

data/lib/more/facets/{dictionarymatcher.rb → matcher.rb}

@@ -1,4 +1,8 @@
-class DictionaryMatcher
+#= Matcher
+#
+# Matcher derives from Ruby Quiz #103, the DictionaryMatcher quiz.
+#
+class Matcher
   attr_reader :word_count
 
   #Contains the index matched, and the word matched
@@ -36,7 +40,7 @@ class DictionaryMatcher
 
     container[0] = true # Mark end of word
     container[:depth]=i
-     
+
     ff=compute_failure_function word
     ff.zip(containers).each do |pointto,container|
       container[:failure]=containers[pointto] if pointto
@@ -61,7 +65,7 @@ class DictionaryMatcher
   end
   private :compute_failure_function
 
-   #Determine whether +string+ was previously <tt>add</tt>ed to the 
+   #Determine whether +string+ was previously <tt>add</tt>ed to the
    #Trie.
   def include?(word)
     container = @trie
@@ -72,18 +76,18 @@ class DictionaryMatcher
     container[0]
   end
 
-   #Determines whether one of the words in the DictionaryMatcher is a 
+   #Determines whether one of the words in the DictionaryMatcher is a
    #substring of
-   #+string+. Returns the index of the match if found, +nil+ if not 
+   #+string+. Returns the index of the match if found, +nil+ if not
    #found.
   def =~ text
     internal_match(text){|md| return md.index}
     nil
   end
 
-   #Determine whether one of the words in the DictionaryMatcher is a 
+   #Determine whether one of the words in the DictionaryMatcher is a
    #substring of
-   #+string+. Returns a DictionaryMatcher::MatchData object if found, 
+   #+string+. Returns a DictionaryMatcher::MatchData object if found,
    #+nil+ if not #found.
   def match text
     internal_match(text){|md| return md}
@@ -101,7 +105,7 @@ class DictionaryMatcher
 	       if node[:failure]
 		  node=node[:failure]
 	       else
-		  advance=true 
+		  advance=true
 	       end
 	    elsif nextnode[0]
 	       yield MatchData.new(pos, string[pos+1-nextnode[:depth],nextnode[:depth]])
@@ -117,11 +121,11 @@ class DictionaryMatcher
   end
   private :internal_match
 
-   #Scans +string+ for all occurrances of strings in the 
+   #Scans +string+ for all occurrances of strings in the
    #DictionaryMatcher.
-   #Overlapping matches are skipped (only the first one is yielded), and 
+   #Overlapping matches are skipped (only the first one is yielded), and
    #when some strings in the
-   #DictionaryMatcher are substrings of others, only the shortest match 
+   #DictionaryMatcher are substrings of others, only the shortest match
    #at a given position is found.
   def scan(text, &block)
     matches=[]

data/lib/more/facets/memoize.rb

@@ -16,12 +16,13 @@
 #     memoize :a
 #   end
 #
-#   t = T.new
+#   t = T.new(1)
 #   t.a.__id__ == t.a.__id__  #=> true
 #
 # == Authors
 #
-# * Trans
+# * trans
+# * rtb
 #
 # == Copying
 #
@@ -36,6 +37,8 @@
 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 # FOR A PARTICULAR PURPOSE.
 
+#require 'facets/memoizer'
+
 #
 class Module
 
@@ -59,11 +62,10 @@ class Module
   #   t.a.__id__ == t.a.__id__  #=> true
   #
   def memoize(*meths)
-    @_MEMOIZE_CACHE ||= Hash.new
     meths.each do |meth|
-      mc = @_MEMOIZE_CACHE[meth] = Hash.new
       old = instance_method(meth)
       new = proc do |*args|
+        mc = ((@_MEMOIZE_CACHE ||= {})[meth] ||= {})
         if mc.has_key? args
           mc[args]
         else
@@ -77,23 +79,18 @@ class Module
 end
 
 # This allows memoize to work in main and instance scope too.
-#--
-# Would this be good to have? Will need to modify for instance level, if so.
-#++
-
 def memoize(*args)
   Object.memoize(*args)
 end
 
-#
-module Kernel
+module Kernel #:nodoc:
 
   # Object#cache is essentially like Module#memoize except
   # it can also be used on singleton/eigen methods.
   # OTOH, memoize's implementation is arguably better for it's
   # use of #bind instead of #alias. Eventually the two implmenations
-  # will be reconciled with a single implmentation.
-
+  # should be reconciled with a single implementation.
+  #
   def cache m = nil
     if m
       (Module === self ? self : (class << self; self; end)).module_eval <<-code

data/lib/more/facets/memoizer.rb

@@ -0,0 +1,74 @@
+# = Memoizer
+#
+# == Synopsis
+#
+# Memoizer wraps objects to provide cached method calls.
+#
+#   class X
+#     def initialize ; @tick = 0 ; end
+#     def tick; @tick + 1; end
+#     def memo; @memo ||= Memoizer.new(self) ; end
+#   end
+#
+#   x = X.new
+#   x.tick       #=> 1
+#   x.memo.tick  #=> 2
+#   x.tick       #=> 3
+#   x.memo.tick  #=> 2
+#   x.tick       #=> 4
+#   x.memo.tick  #=> 2
+#
+# You can also use to cache a collections of objects to gain code
+# speed ups.
+#
+#   points = points.collect{|point| Memoizer.cache(point)}
+#
+# After our algorithm has finished using points, we want to get rid of
+# these Memoizer objects. That's easy:
+#
+#    points = points.collect{|point| point.self }
+#
+# Or if you prefer (it is ever so slightly safer):
+#
+#    points = points.collect{|point| Memoizer.uncache(point)}
+#
+# == References
+#
+# See http://javathink.blogspot.com/2008/09/what-is-memoizer-and-why-should-you.html
+#
+# == Authors
+#
+# * Erik Veenstra
+# * Thomas Sawyer
+#
+# == Copying
+#
+# Copyright (c) 2006 Erik Veenstra
+
+class Memoizer
+
+  #private :class, :clone, :display, :type, :method, :to_a, :to_s
+  private *instance_methods(true).select{ |m| m.to_s !~ /^__/ }
+
+  def initialize(object)
+    @self  = object
+    @cache = {}
+  end
+
+  def method_missing(method_name, *args, &block)
+    # Not thread-safe! Speed is important in caches... ;]
+    @cache[[method_name, args, block]] ||= @self.__send__(method_name, *args, &block)
+  end
+
+  def self; @self; end
+
+  def self.cache(object)
+    new(object)
+  end
+
+  def self.uncache(cached_object)
+    cached_object.self
+  end
+
+end
+