deferred_enum 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in deferred_enum.gemspec
+gemspec
+
+group :development do
+  gem 'rspec'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Alexey Mikhaylov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,34 @@
+== Synopsys
+Ruby Enumerable extension. Main idea is lazy computations within enumerators.
+
+== Usage
+Install as a gem:
+  sudo gem install deferred_enum
+
+This gem introduces DeferredEnumerator class:
+  ary = [1, 2, 3, 4]
+  deferred = ary.defer                 # #<DeferredEnumerator: [1, 2, 3, 4]:each>
+
+DeferredEnumerator brings some optimizations to all?, any? and none? predicates
+  deferred.all?(&:even?)               # Will stop iteration after first false-result = 1 iteration
+  deferred.none?(&:even?)              # 2 iterations
+  deferred.any?(&:even?)               # 2 iterations
+
+It also introduces lazy versions of Enumerable's #select, #map and #reject methods
+  deferred.map { |i| i + 1 }           # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+  deferred.select { |i| i.even? }      # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+  deferred.reject { |i| i.odd? }       # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+
+So you can safely chain your filters, they won't be treated as arrays:
+  deferred.map(&:succ).select(&:even?) # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+
+You can build chains of Enumerables:
+  deferred.concat([2]).to_a            # [1, 2, 3, 4, 2]
+
+Or append elements to the end of enumerator:
+  deferred << 2
+
+You can even remove duplicates from enumerator, though this operation can be tough:
+  deferred.uniq                        # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+
+There are many other methods in DeferredEnumerator, please refer to documentation.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/deferred_enum.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "deferred_enum/version"
+
+Gem::Specification.new do |s|
+  s.name        = "deferred_enum"
+  s.version     = DeferredEnum::VERSION
+  s.authors     = ["Alexey Mikhaylov"]
+  s.email       = ["amikhailov83@gmail.com"]
+  s.homepage    = "https://github.com/take-five/deferred_enum"
+  s.summary     = %q{Introduces lazy computations to Enumerable}
+  s.description = File.read(File.expand_path('../README.rdoc', __FILE__))
+  s.date        = Time.now.strftime('%Y-%m-%d')
+
+  s.rubyforge_project = "deferred_enum"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+end

data/lib/deferred_enum.rb

@@ -0,0 +1 @@
+require "deferred_enumerable"

data/lib/deferred_enum/enumerable.rb

@@ -0,0 +1,5 @@
+module Enumerable
+  def defer(method_id = :each)
+    DeferredEnumerator.new(self, method_id)
+  end
+end

data/lib/deferred_enum/version.rb

@@ -0,0 +1,3 @@
+module DeferredEnum
+  VERSION = "0.0.1"
+end

data/lib/deferred_enumerable.rb

@@ -0,0 +1,267 @@
+module DeferredEnumerable
+  include Enumerable
+
+  # Passes each element of the collection to the given block.
+  # The method returns true if the block never returns false or nil.
+  def all?(&blk) # :yields: obj
+    blk ||= proc { |e| e }
+    each { |entry| return false unless blk.call(entry) }
+    true
+  end
+
+  # Passes each element of the collection to the given block.
+  # The method returns true if the block ever returns a value other than false or nil.
+  def any?(&blk) # :yields: obj
+    blk ||= proc { |e| e }
+    each { |entry| return true if blk.call(entry) }
+    false
+  end
+
+  # Passes each element of the collection to the given block.
+  # The method returns true if the block never returns true for all elements.
+  # If the block is not given, none? will return true only if none of the collection members is true.
+  def none?(&blk)
+    blk ||= proc { |e| e }
+    each { |entry| return false if blk.call(entry) }
+    true
+  end
+
+  # Returns a new enumerator with the results of running block once for every element in enum.
+  def collect # :yields: obj
+    return self unless block_given?
+
+    DeferredEnumerator.new do |yielder|
+      each { |entry| yielder << yield(entry) }
+    end
+  end
+  alias map collect
+
+  # Returns a enumerator containing all elements of enum for which block is not false
+  def select # :yields: obj
+    return self unless block_given?
+
+    DeferredEnumerator.new do |yielder|
+      each { |entry| yielder << entry if yield(entry) }
+    end
+  end
+  alias find_all select
+
+  # Returns a enumerator containing all elements of enum for which block is false
+  def reject # :yields: obj
+    return self unless block_given?
+
+    DeferredEnumerator.new do |yielder|
+      each { |entry| yielder << entry unless yield(entry) }
+    end
+  end
+
+  # Returns a new enumerator that is a one-dimensional flattening of this enumerator (recursively).
+  # That is, for every element that is an Enumerable, extract its elements into the new enumerator.
+  # If the optional level argument determines the level of recursion to flatten.
+  def flatten(level = nil)
+    do_recursion, next_level = if level.is_a?(Fixnum)
+      [level > 0, level - 1]
+    else
+      [true, nil]
+    end
+
+    DeferredEnumerator.new do |yielder|
+      each do |entry|
+        if entry.is_a?(Enumerable) && do_recursion
+          entry.defer.flatten(next_level).each { |nested| yielder << nested }
+        else
+          yielder << entry
+        end
+      end
+    end # Enumerator.new
+  end # def flatten
+
+  # Returns a new enumerator with the concatenated results of running block once for every element in enum.
+  def flat_map(&blk) # :yields: obj
+    return flatten unless block_given?
+
+    flatten.collect(&blk)
+  end
+  alias collect_concat flat_map
+
+  # Calls block for each element of enum repeatedly n times or forever if none or nil is given.
+  # If a non-positive number is given or the collection is empty, does nothing.
+  # Returns nil if the loop has finished without getting interrupted.
+  #
+  # Unlike <tt>Enumerable#cycle</tt> <tt>DeferredEnumerable#cycle</tt> DOES NOT save elements in an internal array.
+  #
+  # If no block is given, an enumerator is returned instead.
+  def cycle(n = nil) # :yields: obj
+    cycles_num = n.is_a?(Fixnum) ? n : nil
+
+    enum = DeferredEnumerator.new do |yielder|
+      while cycles_num.nil? || cycles_num > 0
+        each { |entry| yielder << entry }
+
+        cycles_num -= 1 if cycles_num
+      end
+    end
+
+    unless block_given?
+      enum
+    else
+      enum.each { |e| yield(e) }
+
+      nil
+    end
+  end
+
+  # Drops first n elements from enum, and returns rest elements in an enumerator.
+  def drop(n)
+    raise TypeError, 'Integer (> 0) expected' unless n.is_a?(Fixnum) && n > 0
+
+    DeferredEnumerator.new do |yielder|
+      each { |entry| yielder << entry if (n -= 1) < 0}
+    end
+  end
+
+  # Returns first n elements from enum.
+  def take(n)
+    raise TypeError, 'Integer (> 0) expected' unless n.is_a?(Fixnum) && n > 0
+
+    DeferredEnumerator.new do |yielder|
+      each { |entry| yielder << entry if (n -= 1) >= 0}
+    end
+  end
+
+  # Drops elements up to, but not including, the first element for which the block returns nil
+  # or false and returns an enumerator containing the remaining elements.
+  def drop_while # :yields: obj
+    return self unless block_given?
+
+    DeferredEnumerator.new do |yielder|
+      keep = false
+      each do |entry|
+        keep ||= !yield(entry)
+
+        yielder << entry if keep
+      end
+    end
+  end
+
+  # Passes elements to the block until the block returns <code>nil</code> or <code>false</code>,
+  # then stops iterating and returns an enumerator of all prior elements.
+  def take_while # :yields: obj
+    return self unless block_given?
+
+    DeferredEnumerator.new do |yielder|
+      each do |entry|
+        break unless yield(entry)
+
+        yielder << entry
+      end
+    end
+  end
+
+  # Returns an array of every element in enum for which <code>Pattern === element</code>.
+  # If the optional <code>block</code> is supplied, each matching element is passed to it,
+  # and the block's result is stored in the output array.
+  def grep(pattern, &blk) # :yields: obj
+    filtered = select { |obj| pattern === obj }
+
+    block_given? ?
+        filtered.collect(&blk) :
+        filtered
+  end
+
+  # Returns <code>true</code> if any member of <code>enum</code> equals <code>obj</code>.
+  # Equality is tested using <code>==</code>.
+  def include?(obj) # :yields: obj
+    any? { |e| obj == e }
+  end
+  alias member? include?
+
+  # Returns two enums, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
+  def partition # :yields: obj
+    super.map(&:defer)
+  end
+
+  # Returns an enumerator containing the items in enum sorted,
+  # either according to their own <=> method,
+  # or by using the results of the supplied block.
+  def sort
+    super.defer
+  end
+
+  # Sorts enum using a set of keys generated by mapping the values in enum through the given block.
+  def sort_by
+    super.defer
+  end
+
+  # Takes one element from <i>enum</i> and merges corresponding
+  # elements from each <i>enumerables</i>. This generates a sequence of
+  # <em>n</em>-element arrays, where <em>n</em> is one more than the
+  # count of arguments.  The length of the resulting sequence will be
+  # <code>enum#size</code>. If the size of any argument is less than
+  # <code>enum#size</code>, <code>nil</code> values are supplied. If
+  # a block is given, it is invoked for each output array, otherwise
+  # an enumerator of arrays is returned.
+  def zip(*enumerables)
+    return super if block_given?
+
+    raise TypeError, 'Zip accepts only enumerables' unless enumerables.all? { |e| e.is_a?(Enumerable) }
+
+    deferred = enumerables.map(&:defer)
+
+    DeferredEnumerator.new do |yielder|
+      each do |entry|
+        ary = [entry]
+
+        deferred.each do |enum|
+          ary << begin
+            enum.next
+          rescue StopIteration
+            nil
+          end
+        end
+
+        yielder << ary
+      end
+    end
+  end
+
+  # Returns a enumerator with all nil elements removed.
+  def compact
+    reject(&:nil?)
+  end
+
+  # Appends the <code>enumerables</code> to self.
+  def concat(*enumerables)
+    raise TypeError, 'DeferredEnumerabler#concat accepts only enumerables' unless enumerables.all? { |e| e.is_a?(Enumerable) }
+
+    DeferredEnumerator.new do |yielder|
+      [self, *enumerables].each do |enum|
+        enum.each { |entry| yielder << entry }
+      end
+    end
+  end
+  alias chain concat
+  alias + concat
+
+  # Appends the <code>element</code> to end of enumerator
+  def push(element)
+    concat([element])
+  end
+  alias << push
+
+  # Returns a new enumerator by removing duplicate values in self.
+  def uniq
+    values = {}
+
+    select { |entry|
+      value = block_given? ? yield(entry) : entry
+
+      unless values.has_key?(value)
+        values.store(value, true)
+      end
+    }
+  end
+end
+
+require "deferred_enumerator"
+require "deferred_enum/enumerable"

data/lib/deferred_enumerator.rb

@@ -0,0 +1,6 @@
+require "deferred_enumerable"
+require "deferred_enum/enumerable"
+
+class DeferredEnumerator < Enumerator
+  include ::DeferredEnumerable
+end

data/spec/defer_spec.rb

@@ -0,0 +1,12 @@
+require File.expand_path('../test_helper', __FILE__)
+
+describe Enumerable do
+  it "should have defer method" do
+    ary = []
+    ary.should respond_to(:defer)
+  end
+
+  it "should return DeferredEnumerable" do
+    [].defer.should be_a(DeferredEnumerable)
+  end
+end

data/spec/drop_take_spec.rb

@@ -0,0 +1,15 @@
+require File.expand_path('../test_helper', __FILE__)
+
+describe DeferredEnumerator do
+  it "should drop elements from collections" do
+    [1, 2, 3, 4, 3].defer.drop(3).to_a.should == [4, 3]
+
+    [1, 2, 3, 4, 3].defer.drop_while {|n| n <= 3 }.to_a.should == [4, 3]
+  end
+
+  it "should take first elements from collections" do
+    [4, 3, 2, 1, 4].defer.take(3).to_a.should == [4, 3, 2]
+
+    [4, 3, 2, 1, 4].defer.take_while { |n| n > 1 }.to_a.should == [4, 3, 2]
+  end
+end

data/spec/map_select_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path('../test_helper', __FILE__)
+
+describe DeferredEnumerator do
+  it "should map collections" do
+    [1, 2, 3].defer.map { |i| i + 1 }.to_a.should == [2, 3, 4]
+  end
+
+  it "should filter collections" do
+    [1, 2, 3].defer.select { |i| i.odd? }.to_a.should == [1, 3]
+  end
+
+  it "should reject elements from collections" do
+    [1, 2, 3].defer.reject { |i| i.odd? }.to_a.should == [2]
+  end
+
+  it "should flatten collections" do
+    [[1, 2], 3, [4]].defer.flatten.to_a.should == [1, 2, 3, 4]
+
+    [[1, [2]], 3].defer.flatten(1).to_a.should == [1, [2], 3]
+  end
+
+  it "should flat and map collections" do
+    [[1, 2], 3, [4]].defer.flat_map { |i| i + 1 }.to_a.should == [2, 3, 4, 5]
+  end
+
+  it "should cycle collections" do
+    [1].defer.cycle(2).to_a.should == [1, 1]
+
+    counts = 0
+    [1].defer.cycle { counts += 1; break if counts == 10 }
+    counts.should == 10
+  end
+
+  it "should grep collections" do
+    ['abc', 'def', 'ghi'].defer.grep(/abc/).to_a.should == ['abc']
+  end
+
+  it "should compact collections" do
+    [1, 2, nil].defer.compact.to_a.should == [1, 2]
+  end
+
+  it "should chain collections" do
+    [1, 2].defer.chain([3], [], [4]).to_a.should == [1, 2, 3, 4]
+  end
+
+  it "should remove duplicates from collections" do
+    [1, 2, 3, 4, 3, 4].defer.uniq.to_a.should == [1, 2, 3, 4]
+
+    [1, 2, 3, 4].defer.uniq { |n| n.even? }.to_a.should == [1, 2]
+  end
+end

data/spec/predicates_spec.rb

@@ -0,0 +1,24 @@
+require File.expand_path('../test_helper', __FILE__)
+
+describe DeferredEnumerator do
+  it "should lazily execute all? method" do
+    counts = 0
+
+    [2, 3, 4].all? { |e| counts += 1; e.even? }.should == false
+    counts.should == 2
+  end
+
+  it "should lazily execute any? method" do
+    counts = 0
+
+    [2, 3, 4].any? { |e| counts += 1; e.odd? }.should == true
+    counts.should == 2
+  end
+
+  it "should lazily execute none? method" do
+    counts = 0
+
+    [2, 3, 4].none? { |e| counts += 1; e.odd? }.should == false
+    counts.should == 2
+  end
+end

data/spec/test_helper.rb

@@ -0,0 +1,5 @@
+require "rubygems"
+require "bundler"
+Bundler.setup
+
+require "deferred_enum"

data/spec/zip_spec.rb

@@ -0,0 +1,10 @@
+require File.expand_path('../test_helper', __FILE__)
+
+describe DeferredEnumerator do
+  it "should zip collections" do
+    seq1 = [2, 3, 4]
+    seq2 = [3, 4]
+
+    [1, 2, 3].defer.zip(seq1, seq2).to_a.should == [[1, 2, 3], [2, 3, 4], [3, 4, nil]]
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification 
+name: deferred_enum
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Alexey Mikhaylov
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-11 00:00:00 +06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: |-
+  == Synopsys
+  Ruby Enumerable extension. Main idea is lazy computations within enumerators.
+  
+  == Usage
+  Install as a gem:
+    sudo gem install deferred_enum
+  
+  This gem introduces DeferredEnumerator class:
+    ary = [1, 2, 3, 4]
+    deferred = ary.defer                 # #<DeferredEnumerator: [1, 2, 3, 4]:each>
+  
+  DeferredEnumerator brings some optimizations to all?, any? and none? predicates
+    deferred.all?(&:even?)               # Will stop iteration after first false-result = 1 iteration
+    deferred.none?(&:even?)              # 2 iterations
+    deferred.any?(&:even?)               # 2 iterations
+  
+  It also introduces lazy versions of Enumerable's #select, #map and #reject methods
+    deferred.map { |i| i + 1 }           # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+    deferred.select { |i| i.even? }      # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+    deferred.reject { |i| i.odd? }       # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+  
+  So you can safely chain your filters, they won't be treated as arrays:
+    deferred.map(&:succ).select(&:even?) # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+  
+  You can build chains of Enumerables:
+    deferred.concat([2]).to_a            # [1, 2, 3, 4, 2]
+  
+  Or append elements to the end of enumerator:
+    deferred << 2
+  
+  You can even remove duplicates from enumerator, though this operation can be tough:
+    deferred.uniq                        # #<DeferredEnumerator: #<Enumerator::Generator>:each>
+  
+  There are many other methods in DeferredEnumerator, please refer to documentation.
+email: 
+- amikhailov83@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- deferred_enum.gemspec
+- lib/deferred_enum.rb
+- lib/deferred_enum/enumerable.rb
+- lib/deferred_enum/version.rb
+- lib/deferred_enumerable.rb
+- lib/deferred_enumerator.rb
+- spec/defer_spec.rb
+- spec/drop_take_spec.rb
+- spec/map_select_spec.rb
+- spec/predicates_spec.rb
+- spec/test_helper.rb
+- spec/zip_spec.rb
+has_rdoc: true
+homepage: https://github.com/take-five/deferred_enum
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: deferred_enum
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Introduces lazy computations to Enumerable
+test_files: []
+