### LazyEnumerable
### Written By Blaine Buxton Copyright 2006
###
### It takes a functional approach to the common Enumerable protocol of select, collect, and reject. 
### By functional, I mean the collection is not changed nor is a new modified one created. 
### The blocks are kept around until they are absolutely needed. 
### I have been wanting this functionality for some time because it's nice for large collections. 
### If you have a collection in which you are calling a lot selects, rejects, or collects on, 
### then this will not create the intermediate collections. 
### It will wait until you ask something of the collection where it can not delay the answer. 
### This should make these chained operations must faster on large collections. 
###
### This was a lot of fun to program and it's not that big. Take whatever you want from it!
###
### Read the tests at the bottom to see how it works!
### People have told them this hurts their brain. If you learn anything from this
### please feel to send me an email!
###
### There's example of Lisp-like macros (not quite, but bear with me), meta-programming,
### and lots of closures of course.

class LazyEnumerable
  ##
  ## Remove any unnecessary methods so that method_missing is invoked
  ##
  def self.wack_all_my_methods
    to_wack=instance_methods.reject do |each|
      ['===','method_missing'].include?(each) || each =~ /^__/
    end
    to_wack.each do |each|
      alias_method(("_" << each), each)
      undef_method(each)
    end
  end
  
  ##
  ## Wack all of my methods, then apply Enumerable and define my constants
  ## and class variable for cached method calls
  ##
  wack_all_my_methods
  include Enumerable
  PLACEBO=lambda {|each| each}
  @@cached={}
  
  ##
  ## Meta-programming to provide a shorthand for extensions to let themselves
  ## known so that they can be found on the method_missing.
  ##
  def self.define_for(method_name)
    undef_method(method_name)
    @@cached[method_name]=self
  end
  
  ##
  ## Lookup a subclass for the particular method. Basically, this is so that each
  ## template will provide its own functionality for each
  ##
  def self.class_for(method_name)
    @@cached[method_name]
  end
  
  def self.iterator_creator(*method_names)
  	method_names.each {|each| iterator_creator_for(each)}
  end
  
  ###
  ### This code creates methods for an iterator method (:collect, :select, etc)
  ### if invoked with no arguments (no blocks either). It returns a LazyIterator
  ### on no block because it them assumes you are creating higher order methods.
  ### This allows you to do things like big_collection.reject.nil? instead of
  ### big_collection.reject {|each| each.nil?}. I hate the use of eval here even though
  ### it is Lisp-ish (macros). I think I should have been able to do with define_method
  ### but you can not use the same semantics passing blocks as arguments to blocks as
  ### you do in methods. Variable arguments failed as well. But, eval keeps the same job
  ### done even if in an inelegant way. Also, it's uglier than hell with the <<METHOD
  ### crap.
  ###
  def self.iterator_creator_for(method_name)
    private_name = "_#{method_name}"
    alias_method private_name, method_name
    
    method= 
<<METHOD 
      def #{method_name}(&block)
        return #{private_name}(&block) unless (block.nil?)
        LazyIterator.new(_method(:#{private_name}))
      end
METHOD
    eval(method, binding)
  end
  
  def initialize(original, block=PLACEBO)
    @original=original
    @block=block
    _freeze
  end
  
  ##
  ## This is basically the default implementation and should be overriden in
  ## subclasses. It's because we can create a basic LazyEnumerable (on call to_lazy)
  ## that simply is a placebo implementation to keep things simple
  ##
  
  def each(&block)
  	@original.each(&block)
  end
  
  ##
  ## Look up the implementation of the iterator method (for example, :select, :collect:, etc)
  ## I do define the missing method on this call. The reason is for ease of debugging and
  ## speed. We don't need to go through this logic. It's on the fly code generation without
  ## eval
  ##
  def method_missing(method_name, *arguments)
    my_class=self._class.class_for(method_name)
    if (my_class.nil?)
      super.method_missing(method_name, *arguments)
    end
    
    proc = lambda {|*args| my_class.new(self, *args)}
    self._class.send(:define_method, method_name, &proc)
    proc.call(*arguments)
  end
  
  ##
  ## Give me the size. This can be dangerous if you ever wrap an infinite enumerable
  ##
  def size
    inject(0) {|sum,each| sum + 1 }
  end
  
  def to_lazy
    self
  end

  def to_real
    _collect(PLACEBO)
  end
  
  ##
  ## Create the lazy iterators when no block is passed in the methods
  ## below
  ##
  iterator_creator :select, :collect, :reject, :detect, :each
  
end

class LazySelectEnumerable < LazyEnumerable
  define_for(:select)
  
  def each(&each_block)
    @original.each do |every|
      each_block.call(every) if @block.call(every)
    end
  end
end

class LazyRejectEnumerable < LazyEnumerable
  define_for(:reject)
  
  def each(&each_block)
    @original.each do |every|
      each_block.call(every) unless @block.call(every)
    end
  end
end

class LazyCollectEnumerable < LazyEnumerable
  define_for(:collect)

  def each(&each_block)
    @original.each do |every|
      each_block.call(@block.call(every))
    end
  end
end

###
### LazyEnumerable makes the implementtion of higher order methods easier. LazyIterator
### is a simple implemetation of that. It basically works by "stacking" up the method
### calls until the collection needs to be calculated (realized). It then calls the
### "stacked up" methods.
###
### LazyEnumerable is immutable and I would like LazyIterator to be as well. But,
### every attempt has made the code ugly and inelegant. I'm still looking for a good
### solution. Immuntability gives the ability to calculate on different levels.
###
class LazyIterator < LazyEnumerable
  
  def initialize(proc)
    @internal=proc
    @sends=[]
  end
  
  ##
  ## Simply make a closure around the method and capturing it's arguments as well
  ## This is so it can be replayed. Notice again, I cache the method with a define_method
  ##
  def method_missing(method_name, *arguments)
    proc=lambda do |*args|
      send=lambda {|each| each.send(method_name, *args)}
      @sends << send
      self
    end
    self._class.send(:define_method, method_name, &proc)
    proc.call(*arguments)
  end
  
  ##
  ## Do a placebo collect to get it to create an array with the elements
  ##
  def to_real
    collect { |each| each }
  end
  
  ##
  ## Call each member in the original collection and call each "captured" method
  ## in succession. Notice the use of inject to make this really elegant and succint.
  ## I do cheat a little and realize the collection and then call each. I want
  ## to change this in the future.
  ##
  def each(&block)
    method_missing(:each, &block) if (block.nil?)
    answer=@internal.call do |each|
      result=@sends.inject(each) do |result, each_send |
        each_send.call(result)
      end
    end
    answer.each(&block)
  end
end

###
### Hack to get the current method off the stack. I hate this.
### Why can't I reflect on the stack and get the real method 
### invocation? Grrr...
###
module Kernel
  private
  def current_method
    (caller[0] =~ /`([^']*)'/ and $1).to_sym
  end
end

###
### Conversion methods
###
module Enumerable
  def to_lazy
    LazyEnumerable.new(self)
  end
  
  def to_real
    self
  end
  
end

###
### TESTS
###

if ($0 == __FILE__)
  require 'test/unit'
  class LazyEnumerableTest < Test::Unit::TestCase
    def test_lazy
      original=(1..100)
      modified=original.to_lazy.select {|each| each % 2 == 0}
      modified_even=modified
      modified=modified.reject {|each| (each % 4).zero?}
      modified=modified.collect {|each| each.to_s}
      modified=modified.select {|each| each.size == 1}
      #force, the collection to be realized
      realized_collection=modified.to_real
      assert_equal(['2', '6'], realized_collection)
      assert_equal(50,modified_even.size)
      assert(modified_even.to_real.class != LazyEnumerable)
    end
    def test_iterator
      original=(1..100)
      modified=original.to_lazy.select.even
      modified_even=modified
      modified=(modified.reject % 4).zero?
      modified=modified.collect.to_s
      modified=modified.select {|each| each.size == 1}
      #force, the collection to be realized
      realized_collection=modified.to_real
      assert_equal(['2', '6'], realized_collection)
      assert_equal(50,modified_even.size)
      assert(modified_even.to_real.class != LazyEnumerable)
    end
  end
  class Numeric
    def even
      self % 2 == 0
    end
  end
end