lazily 0.0.1 → 0.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTE1ODg4ZDgzNDFjMTc0YzlhMWE0ODU5MWRmNjcyYzQyMTNkMGNmYw==
+    OTA2Zjk3MzAxNDg4N2JhMGFhZDAyNTJjZmQ3YzExYzFkNDA4NmZlMw==
   data.tar.gz: !binary |-
-    MDlhZjZhMWI5ZDNiMDdmMzk3OWU4NGM4MGVmYzhlODUyMzEyYzg3Ng==
+    YmY5MzM3N2ZiYTZkZWVjNzMzNTE2NjhjMmQ1NDZhN2UyYjgxODcxOQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NWNkYWNkOTViODA2OWM0ZWM1NWJkNTlhY2Y2NWUwNmQ0NGQ1MjZiZjFkODgz
-    MGFiYjRlYmZjYTQzZDkyYjMyMzFhYjU1ZTE3Y2JmMTMwZWEwMzBhYWFhZDIw
-    Nzg3Y2I0MjUyYzQzOTJkOTg2MmI4NjdlZmQ0MTkwZTkzMzA2YTY=
+    OThlZDA3NGU5ZTAzMmUxZjY0ZmJkMGU3OGE0MDZhZGE0ZTE5NDI5ZDBlZmVi
+    ODFmYjEyYmVmNGUwYmMwMzllYjU0NGUwMTgwN2I5NTc5NjExM2U1MTI0MmY3
+    ZjYyOTJiZTMwN2I1ZGMwNmUzYWM5ZWZkMmZjZjJhYTkxOWRlYzI=
   data.tar.gz: !binary |-
-    OGQ5ZTBhZTgyNTUwOTc3NTEwOGE3MTgwMmM0OWFiZjBiZDY1ZGJjYWRlMDJl
-    YTM2NmY5ZmYzMGRhNDI3Yjk4NTgwYTU5MTdmYjllM2U4Y2M0ZDVlODM1ZTI1
-    MThmOTkyZDNhZDNjNDVkYWVkZjBmMDJmMGEwMGZjMGRiZTAxYzI=
+    NDA3OTM0ZWMzOGNkMDY3M2JjNmYwYzg2Zjk4NmY0MjNlZDY2ZWZkY2I0NzMx
+    Y2E5MzJmODU5MTgyYTk4MjUxZWIxYWQwNzM5NjExNWRhNDFhYTgzYjM3NGE3
+    Yzk5NjVmMjBjMjBkMDcyZmM2YTAwNzI1YzcwZTA1NTBiZmIyZDM=

data/.gitignore

@@ -1,4 +1,6 @@
 *.gem
 .bundle
+.yardoc
 Gemfile.lock
+doc
 pkg/*

data/CHANGES.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1 (2013-04-19)
+
+* Initial version, ported from "enumerating".

data/Gemfile

@@ -4,3 +4,4 @@ gemspec
 
 gem "rake", "~> 10.0.0"
 gem "rspec", "~> 2.13.0"
+gem "yard"

data/README.md

@@ -0,0 +1,147 @@
+Lazily [![Build Status](https://secure.travis-ci.org/mdub/lazily.png?branch=master)](http://travis-ci.org/mdub/lazily)
+===========
+
+Lazily provides various "lazy" Enumerable operations, similar to:
+
+* Clojure's sequences
+* Haskell's lists
+* Scala's "views"
+* Ruby 2.0's Enumerator::Lazy
+
+Lazy filtering and transforming
+-------------------------------
+
+Lazy evaluation is triggered using `Enumerable#lazily`:
+
+    [1,2,3].lazily              #=> #<Lazily::Proxy: [1, 2, 3]>
+
+The resulting object implements lazy versions of various Enumerable methods.  Rather than returning Arrays, the lazy forms return new Enumerable objects, which generate results incrementally, on demand.
+
+Consider the following code, which squares a bunch of numbers, then takes the first 4 results.
+
+    >> (1..10).collect { |x| p x; x*x }.take(4)
+    1
+    2
+    3
+    4
+    5
+    6
+    7
+    8
+    9
+    10
+    => [1, 4, 9, 16]
+
+See how it printed all the numbers from 1 to 10, indicating that the block given to `collect` was run ten times. We can do the same thing lazily, like this:
+
+    >> (1..10).lazily.collect { |x| p x; x*x }.take(4).to_a
+    1
+    2
+    3
+    4
+    => [1, 4, 9, 16]
+
+Same result, but notice how the block was only evaluated four times. 
+
+Lazy pipelines
+--------------
+
+By combining two or more lazy operations, you can create an efficient "pipeline", e.g.
+
+    User.to_enum(:find_each).lazily.select do |u| 
+      u.first_name[0] == u.last_name[0]
+    end.collect(&:company).uniq.to_a
+
+In case you missed it:
+
+    # enumerate all users
+    users = User.to_enum(:find_each)
+
+    # lazily select those matching "X... X..." (e.g. "Mickey Mouse")
+    users = users.lazily.select { |u| u.first_name[0] == u.last_name[0] }
+
+    # grab their company (weeding out duplicates)
+    companies = users.collect(&:company).uniq
+
+    # force resolution
+    companies.to_a              #=> ["Disney"]
+
+Because the steps in the pipeline operate in parallel, without creation of intermediate collections (Arrays), you can efficiently operate on large (or even infinite) Enumerable collections.
+
+This is analogous to a Unix shell pipeline, though of course here we're talking about streams of objects, rather than streams of text.
+
+Lazy multi-threaded processing
+------------------------------
+
+The `#in_threads` method is a multi-threaded version of `#collect`, allowing multiple elements of a collection to be processed in parallel.  It requires a numeric argument specifying the maximum number of Threads to use. 
+
+    Benchmark.realtime do
+      [1,2,3,4].lazily.in_threads(10) do |x|
+        sleep 1
+        x * 2
+      end.to_a                  #=> [2,4,6,8]
+    end.to_i                    #=> 1
+
+Outputs will be yielded in the expected order, making it a drop-in replacement for `#collect`. 
+
+Unlike some other "parallel map" implementations, the output of `#in_threads` is lazy (though it does need to pre-fetch elements from the source collection as required to start Threads).
+
+Lazy combination of Enumerables
+-------------------------------
+
+Lazily also provides some interesting ways to combine several Enumerable collections to create a new collection.
+
+`Lazily.zip` pulls elements from a number of collections in parallel, yielding each group.
+
+    array1 = [1,3,6]
+    array2 = [2,4,7]
+    Lazily.zip(array1, array2)          #=> [1,2], [3,4], [6,7]
+
+`Lazily.concat` concatenates collections.
+
+    array1 = [1,3,6]
+    array2 = [2,4,7]
+    Lazily.concat(array1, array2)       #=> [1,3,6,2,4,7]
+
+`Lazily.merge` merges multiple collections, preserving sort-order.  The inputs are assumed to be sorted already.
+
+    array1 = [1,4,5]
+    array2 = [2,3,6]
+    Lazily.merge(array1, array2)        #=> [1,2,3,4,5,6]
+
+A block can be provided to determine the sort-order.
+
+    array1 = %w(a dd cccc)
+    array2 = %w(eee bbbbb)
+    Lazily.merge(array1, array2) { |x| x.length }
+                                        #=> %w(a dd eee cccc bbbbb)
+
+Same but different
+------------------
+
+There are numerous similar implementations of lazy operations on Enumerables.  
+
+### Lazily vs. Enumerating
+
+Lazily supercedes "[Enumerating](http://github.com/mdub/enumerating)".  Whereas Enumerating mixed lazy operations directly onto `Enumerable`, Lazily does not.  Instead, it implements an API modelled on Ruby 2.0's `Enumerable#lazy`.
+
+### Lazily vs. Ruby 2.0
+
+Q: Why use Lazily, when Ruby 2.x has built-in lazy enumerations?
+
+- Compatibility: Perhaps you haven't managed to migrate to Ruby 2.0 yet.  Lazily provides the same benefits, but works in older versions of Ruby (most features work even in Ruby-1.8.7).
+- Consistency: Being pure-Ruby, you can use the same implementation of lazy enumeration across Ruby versions and interpreters.
+- Features: Lazily provides some extra features not present in Ruby 2.0, such as multi-threaded lazy enumeration.
+- Speed: Despite being implemented in pure Ruby, `Enumerable#lazily` actually performs a little better than `Enumerable#lazy`.
+
+Q: When would you use built-in Ruby lazy enumerations, rather than Lazily?
+
+- I wouldn't.
+
+### Others
+
+See also:
+
+* Greg Spurrier's gem "`lazing`"
+* `Enumerable#defer` from the Ruby Facets library
+* The "`backports`" gem, which implements `Enumerable#lazy` for Ruby pre-2.0.

data/Rakefile

@@ -10,3 +10,9 @@ RSpec::Core::RakeTask.new do |t|
 end
 
 task "default" => "spec"
+
+desc "Generate documentation"
+task(:doc) { sh "yard" }
+
+desc "Generate documentation incrementally"
+task(:redoc) { sh "yard -c" }

data/benchmarks/pipeline_bench.rb

@@ -0,0 +1,97 @@
+require 'benchmark'
+
+$: << File.expand_path("../../lib", __FILE__)
+
+array = (1..100000).to_a
+
+# Test scenario:
+#  - filter out even numbers
+#  - square them
+#  - grab the first thousand
+
+printf "%-30s", "IMPLEMENTATION"
+printf "%12s", "take(10)"
+printf "%12s", "take(100)"
+printf "%12s", "take(1000)"
+printf "%12s", "to_a"
+puts ""
+
+def measure(&block)
+  printf "%12.5f", Benchmark.realtime(&block)
+end
+
+def benchmark(description, control_result = nil)
+  result = nil
+  printf "%-30s", description
+  measure { yield.take(10).to_a }
+  measure { yield.take(100).to_a }
+  measure { result = yield.take(1000).to_a }
+  measure { yield.to_a }
+  puts ""
+  unless control_result.nil? || result == control_result
+    raise "unexpected result from '#{description}': #{result.inspect}"
+  end
+  result
+end
+
+@control = benchmark "eager" do
+  array.select { |x| x.even? }.collect { |x| x*x }
+end
+
+def can_require?(library)
+  require(library)
+  true
+rescue LoadError
+  false
+end
+
+if array.respond_to?(:lazy)
+
+  benchmark "ruby2", @control do
+    array.lazy.select { |x| x.even? }.collect { |x| x*x }
+  end
+
+elsif can_require?("backports/2.0.0")
+
+  benchmark "backports", @control do
+    array.lazy.select { |x| x.even? }.collect { |x| x*x }
+  end
+
+end
+
+if can_require? "facets"
+
+  benchmark "facets", @control do
+    array.defer.select { |x| x.even? }.collect { |x| x*x }
+  end
+
+end
+
+if defined?(Fiber) && can_require?("lazing")
+
+  module Enumerable
+    alias :lazing_select :selecting
+    alias :lazing_collect :collecting
+  end
+
+  benchmark "lazing", @control do
+    array.lazing_select { |x| x.even? }.lazing_collect { |x| x*x }
+  end
+
+end
+
+if can_require?("enumerating")
+
+  benchmark "enumerating", @control do
+    array.selecting { |x| x.even? }.collecting { |x| x*x }
+  end
+
+end
+
+if can_require?("lazily")
+
+  benchmark "lazily", @control do
+    array.lazily.select { |x| x.even? }.collect { |x| x*x }
+  end
+
+end

data/lib/lazily/concatenating.rb

@@ -4,6 +4,11 @@ module Lazily
 
   class << self
 
+    # Concatenates two or more Enumerables.
+    #
+    # @param enumerables [Array<Enumerable>]
+    # @return [Enumerable] elements of all the enumerables
+    #
     def concat(*enumerables)
       Concatenator.new(enumerables)
     end
@@ -12,6 +17,13 @@ module Lazily
 
   module Enumerable
 
+    # Concatenates this and other Enumerables.
+    #
+    # @param others [Array<Enumerable>]
+    # @return [Enumerable] elements of this and other Enumerables
+    #
+    # @see Array#concat
+    #
     def concat(*others)
       Lazily.concat(self, *others)
     end

data/lib/lazily/enumerable.rb

@@ -8,6 +8,10 @@ module Lazily
       true
     end
 
+    def lazily
+      self
+    end
+
   end
 
 end

data/lib/lazily/filtering.rb

@@ -4,8 +4,13 @@ module Lazily
 
   module Enumerable
 
-    def collect
-      Filter.new do |output|
+    # Transform elements using the block provided.
+    # @return [Enumerable] the transformed elements
+    #
+    # @see ::Enumerable#collect
+    #
+    def collect(&transformation)
+      filter("collect") do |output|
         each do |element|
           output.call yield(element)
         end
@@ -14,8 +19,14 @@ module Lazily
 
     alias map collect
 
-    def select
-      Filter.new do |output|
+    # Select elements using a predicate block.
+    #
+    # @return [Enumerable] the elements that pass the predicate
+    #
+    # @see ::Enumerable#select
+    #
+    def select(&predicate)
+      filter("select") do |output|
         each do |element|
           output.call(element) if yield(element)
         end
@@ -24,54 +35,87 @@ module Lazily
 
     alias find_all select
 
+    # Select elements that fail a test.
+    #
+    # @yield [element] each element
+    # @yieldreturn [Boolean] truthy if the element passed the test
+    # @return [Enumerable] the elements which failed the test
+    #
+    # @see ::Enumerable#reject
+    #
     def reject
-      Filter.new do |output|
+      filter("reject") do |output|
         each do |element|
           output.call(element) unless yield(element)
         end
       end
     end
 
+    # Remove duplicate values.
+    #
+    # @return [Enumerable] elements which have not been previously encountered
+    # @overload uniq
+    #
+    # @overload uniq(&block)
+    #
+    # @see ::Enumerable#uniq
+    #
     def uniq
-      Filter.new do |output|
+      filter("uniq") do |output|
         seen = Set.new
         each do |element|
-          output.call(element) if seen.add?(element)
-        end
-      end
-    end
-
-    def uniq_by
-      Filter.new do |output|
-        seen = Set.new
-        each do |element|
-          output.call(element) if seen.add?(yield element)
+          key = if block_given?
+            yield element
+          else
+            element
+          end
+          output.call(element) if seen.add?(key)
         end
       end
     end
 
+    # Select the first n elements.
+    #
+    # @param n [Integer] the number of elements to take
+    # @return [Enumerable] the first N elements
+    #
+    # @see ::Enumerable#take
+    #
     def take(n)
-      Filter.new do |output|
+      filter("take") do |output|
         if n > 0
           each_with_index do |element, index|
             output.call(element)
-            throw Lazily::Filter::DONE if index + 1 == n
+            throw Filter::DONE if index + 1 == n
           end
         end
       end
     end
 
-    def take_while
-      Filter.new do |output|
+    # Select elements while a predicate returns true.
+    #
+    # @return [Enumerable] all elements before the first that fails the predicate
+    #
+    # @see ::Enumerable#take_while
+    #
+    def take_while(&predicate)
+      filter("take_while") do |output|
         each do |element|
-          throw Lazily::Filter::DONE unless yield(element)
+          throw Filter::DONE unless yield(element)
           output.call(element)
         end
       end
     end
 
+    # Ignore the first n elements.
+    #
+    # @param n [Integer] the number of elements to drop
+    # @return [Enumerable] elements after the first N
+    #
+    # @see ::Enumerable#drop
+    #
     def drop(n)
-      Filter.new do |output|
+      filter("drop") do |output|
         each_with_index do |element, index|
           next if index < n
           output.call(element)
@@ -79,8 +123,14 @@ module Lazily
       end
     end
 
-    def drop_while
-      Filter.new do |output|
+    # Reject elements while a predicate returns true.
+    #
+    # @return [Enumerable] all elements including and after the first that fails the predicate
+    #
+    # @see ::Enumerable#drop_while
+    #
+    def drop_while(&predicate)
+      filter("drop_while") do |output|
         take = false
         each do |element|
           take ||= !yield(element)
@@ -89,17 +139,102 @@ module Lazily
       end
     end
 
+    # Select elements matching a pattern.
+    #
+    # @return [Enumerable] elements for which the pattern matches
+    #
+    # @see ::Enumerable#grep
+    #
+    def grep(pattern)
+      filter("grep") do |output|
+        each do |element|
+          if pattern === element
+            result = if block_given?
+              yield element
+            else
+              element
+            end
+            output.call(result)
+          end
+        end
+      end
+    end
+
+    # Flatten the collection, such that Enumerable elements are included inline.
+    #
+    # @return [Enumerable] elements of elements of the collection
+    #
+    # @see ::Array#flatten
+    #
+    def flatten(level = 1)
+      filter("flatten") do |output|
+        each do |element|
+          if level > 0 && element.respond_to?(:each)
+            element.flatten(level - 1).each(&output)
+          else
+            output.call(element)
+          end
+        end
+      end
+    end
+
+    def flat_map(&block)
+      map(&block).flatten
+    end
+
+    alias collect_concat flat_map
+
+    # Ignore nil values.
+    #
+    # @return [Enumerable] the elements that are not nil
+    #
+    # @see ::Array#compact
+    #
+    def compact
+      filter("compact") do |output|
+        each do |element|
+          output.call(element) unless element.nil?
+        end
+      end
+    end
+
+    if ::Enumerable.method_defined?(:slice_before)
+
+      def slice_before(*args, &block)
+        super.lazily
+      end
+
+    end
+
+    if ::Enumerable.method_defined?(:chunk)
+
+      def chunk(*args, &block)
+        super.lazily
+      end
+
+    end
+
+    # @return the nth element
+    #
     def [](n)
       drop(n).first
     end
 
+    private
+
+    def filter(method, &block)
+      Filter.new(self, method, &block)
+    end
+
   end
 
   class Filter
 
     include Lazily::Enumerable
 
-    def initialize(&generator)
+    def initialize(source, method, &generator)
+      @source = source
+      @method = method
       @generator = generator
     end
 
@@ -113,6 +248,10 @@ module Lazily
       end
     end
 
+    def inspect
+      "#<#{self.class}: #{@method} #{@source.inspect}>"
+    end
+
   end
 
 end

data/lib/lazily/merging.rb

@@ -4,11 +4,7 @@ module Lazily
 
   class << self
 
-    def merge(*enumerables)
-      Merger.new(enumerables)
-    end
-
-    def merge_by(*enumerables, &block)
+    def merge(*enumerables, &block)
       Merger.new(enumerables, &block)
     end
 

data/lib/lazily/proxy.rb

@@ -27,6 +27,10 @@ module Lazily
       @source.each(&block)
     end
 
+    def inspect
+      "#<#{self.class}: #{@source.inspect}>"
+    end
+
   end
 
 end

data/lib/lazily/threading.rb

@@ -8,7 +8,7 @@ module Lazily
       collect do |item|
         Thread.new { block.call(item) }
       end.prefetch(max_threads - 1).collect do |thread|
-        thread.join; thread.value
+        thread.join.value
       end
     end
   end

data/lib/lazily/version.rb

@@ -1,3 +1,3 @@
 module Lazily
-  VERSION = "0.0.1".freeze
+  VERSION = "0.1.0".freeze
 end

data/spec/lazily/concatenating_spec.rb

@@ -2,36 +2,32 @@ require "spec_helper"
 
 describe Lazily, "concatenating" do
 
-  describe ".concat" do
+  let(:array1) { [1,5,3] }
+  let(:array2) { [2,9,4] }
 
-    let(:array1) { [1,5,3] }
-    let(:array2) { [2,9,4] }
+  describe ".concat" do
 
     it "concatenates multiple Enumerables" do
-      result = Lazily.concat([1,5,3], [2,9,4])
-      result.to_a.should == [1,5,3,2,9,4]
+      result = Lazily.concat(array1, array2)
+      result.to_a.should == array1 + array2
     end
 
     it "is lazy" do
-      result = Lazily.concat([3,4], [1,2].with_time_bomb)
-      result.take(3).to_a.should == [3,4,1]
+      Lazily.concat(array1, array2.ecetera).should be_lazy
     end
 
   end
 
   describe "#concat" do
 
-    let(:array1) { [1,5,3] }
-    let(:array2) { [2,9,4] }
-
     it "concatenates multiple Enumerables" do
-      result = [1,5,3].lazily.concat([2,9,4])
-      result.to_a.should == [1,5,3,2,9,4]
+      result = array1.lazily.concat(array2)
+      result.to_a.should == array1 + array2
     end
 
     it "is lazy" do
-      result = [3,4].lazily.concat([1,2].with_time_bomb)
-      result.take(3).to_a.should == [3,4,1]
+      result = array1.lazily.concat(array2.ecetera)
+      result.take(3).to_a.should == (array1 + array2).take(3)
     end
 
   end

data/spec/lazily/filtering_spec.rb

@@ -9,7 +9,7 @@ describe Lazily, "filter" do
     end
 
     it "is lazy" do
-      [1,2,3].with_time_bomb.lazily.collect { |x| x * 2 }.first.should == 2
+      [1,2,3].ecetera.lazily.collect { |x| x * 2 }.should be_lazy
     end
 
   end
@@ -21,7 +21,7 @@ describe Lazily, "filter" do
     end
 
     it "is lazy" do
-      (1..6).with_time_bomb.lazily.select { |x| x%2 == 0 }.first == 2
+      (1..6).ecetera.lazily.select { |x| x%2 == 0 }.should be_lazy
     end
 
   end
@@ -33,7 +33,7 @@ describe Lazily, "filter" do
     end
 
     it "is lazy" do
-      (1..6).with_time_bomb.lazily.reject { |x| x%2 == 0 }.first == 1
+      (1..6).ecetera.lazily.reject { |x| x%2 == 0 }.should be_lazy
     end
 
   end
@@ -45,16 +45,16 @@ describe Lazily, "filter" do
     end
 
     it "is lazy" do
-      [1,2,3].with_time_bomb.lazily.uniq.first.should == 1
+      [1,2,3].ecetera.lazily.uniq.should be_lazy
     end
 
-  end
+    context "with a block" do
 
-  describe "#uniq_by" do
+      it "uses the block to derive identity" do
+        array = %w(A1 A2 B1 A3 C1 B2 C2)
+        array.lazily.uniq { |s| s[0,1] }.to_a.should == %w(A1 B1 C1)
+      end
 
-    it "uses the block to derive identity" do
-      @array = %w(A1 A2 B1 A3 C1 B2 C2)
-      @array.lazily.uniq_by { |s| s[0,1] }.to_a.should == %w(A1 B1 C1)
     end
 
   end
@@ -62,16 +62,16 @@ describe Lazily, "filter" do
   describe "#take" do
 
     it "includes the specified number" do
-      @array = [1,2,3,4]
-      @array.lazily.take(3).to_a.should == [1,2,3]
+      array = [1,2,3,4]
+      array.lazily.take(3).to_a.should == [1,2,3]
     end
 
     it "is lazy" do
-      [1,2].with_time_bomb.lazily.take(2).to_a.should == [1,2]
+      [1,2].ecetera.lazily.take(2).should be_lazy
     end
 
     it "copes with 0" do
-      [].with_time_bomb.lazily.take(0).to_a.should == []
+      [].ecetera.lazily.take(0).to_a.should == []
     end
 
   end
@@ -79,12 +79,12 @@ describe Lazily, "filter" do
   describe "#take_while" do
 
     it "takees elements as long as the predicate is true" do
-      @array = [2,4,6,3]
-      @array.lazily.take_while(&:even?).to_a.should == [2,4,6]
+      array = [2,4,6,3]
+      array.lazily.take_while(&:even?).to_a.should == [2,4,6]
     end
 
     it "is lazy" do
-      [2,3].with_time_bomb.lazily.take_while(&:even?).to_a.should == [2]
+      [2,3].ecetera.lazily.take_while(&:even?).should be_lazy
     end
 
   end
@@ -92,12 +92,12 @@ describe Lazily, "filter" do
   describe "#drop" do
 
     it "excludes the specified number" do
-      @array = [1,2,3,4]
-      @array.lazily.drop(2).to_a.should == [3,4]
+      array = [1,2,3,4]
+      array.lazily.drop(2).to_a.should == [3,4]
     end
 
     it "is lazy" do
-      [1,2,3,4].with_time_bomb.lazily.drop(2).lazily.take(1).to_a.should == [3]
+      [1,2,3,4].ecetera.lazily.drop(2).lazily.take(1).to_a.should == [3]
     end
 
   end
@@ -105,28 +105,158 @@ describe Lazily, "filter" do
   describe "#drop_while" do
 
     it "drops elements as long as the predicate is true" do
-      @array = [2,4,6,3,4]
-      @array.lazily.drop_while(&:even?).to_a.should == [3,4]
+      array = [2,4,6,3,4]
+      array.lazily.drop_while(&:even?).to_a.should == [3,4]
+    end
+
+    it "is lazy" do
+      [2,3].ecetera.lazily.drop_while(&:even?).lazily.should be_lazy
+    end
+
+  end
+
+  describe "#grep" do
+
+    let(:fruits) { %w(apple banana pear orange) }
+
+    it "returns elements matching a pattern" do
+      fruits.lazily.grep(/e$/).to_a.should == %w(apple orange)
+    end
+
+    it "applies the associated block" do
+      fruits.lazily.grep(/e$/, &:capitalize).to_a.should == %w(Apple Orange)
+    end
+
+    it "is lazy" do
+      fruits.ecetera.lazily.grep(/p/).should be_lazy
+    end
+
+  end
+
+  describe "#flatten" do
+
+    let(:array1) { [1,2,3] }
+    let(:array2) { [4,5,6] }
+
+    it "flattens" do
+      [[1,2], [3,4]].lazily.flatten.to_a.should == [1,2,3,4]
+    end
+
+    it "handles non-Enumerable elements" do
+      [1,2].lazily.flatten.to_a.should == [1,2]
+    end
+
+    it "goes one level deep (by default)" do
+      [[1,2], [[3]]].lazily.flatten.to_a.should == [1,2,[3]]
+    end
+
+    it "allows the depth to be specified" do
+      [[1], [[2]], [[[3]]]].lazily.flatten(2).to_a.should == [1, 2, [3]]
+    end
+
+    it "is lazy" do
+      [array1.ecetera, array2].lazily.flatten.should be_lazy
+    end
+
+  end
+
+  describe "#flat_map" do
+
+    let(:array) { [1,2,3] }
+
+    it "flattens resulting Enumerables" do
+      array.lazily.flat_map { |n| [n] * n }.to_a.should == [1,2,2,3,3,3]
+    end
+
+    it "handles blocks that don't return Enumerables" do
+      array.lazily.flat_map { |n| n * n }.to_a.should == [1,4,9]
+    end
+
+    it "handles nils " do
+      array.lazily.flat_map { nil }.to_a.should == [nil, nil, nil]
+    end
+
+    it "is lazy" do
+      array.ecetera.lazily.flat_map { |n| [n] * n }.should be_lazy
+    end
+
+  end
+
+  if ::Enumerable.method_defined?(:slice_before)
+
+    describe "#slice_before" do
+
+      let(:words) do
+        %w(One two three Two two three)
+      end
+
+      it "can slice with a pattern" do
+        words.lazily.slice_before(/^[A-Z]/).to_a.should == [
+          %w(One two three),
+          %w(Two two three)
+        ]
+      end
+
+      it "can slice with a block" do
+        words.lazily.slice_before { |w| w =~ /^[A-Z]/ }.to_a.should == [
+          %w(One two three),
+          %w(Two two three)
+        ]
+      end
+
+      it "is lazy" do
+        words.ecetera.lazily.slice_before(/^[A-Z]/).should be_lazy
+      end
+
+    end
+
+  end
+
+  if ::Enumerable.method_defined?(:chunk)
+
+    describe "#chunk" do
+
+      it "groups elements by the result of a block" do
+        [3,1,4,1,5,9,2,6].lazily.chunk(&:even?).to_a.should == [
+          [false, [3, 1]],
+          [true, [4]],
+          [false, [1, 5, 9]],
+          [true, [2, 6]],
+        ]
+      end
+
+      it "is lazy" do
+        [3,1,4,1,5,9,2,6].ecetera.lazily.chunk(&:even?).should be_lazy
+      end
+
+    end
+
+  end
+
+  describe "#compact" do
+
+    it "omits nils" do
+      [1, "too", nil, true, nil, false].lazily.compact.to_a.should == [1, "too", true, false]
     end
 
     it "is lazy" do
-      [2,3].with_time_bomb.lazily.drop_while(&:even?).lazily.take(1).to_a.should == [3]
+      [nil].ecetera.lazily.compact.should be_lazy
     end
 
   end
 
   describe "#[]" do
 
-    before do
-      @evens = [1,2,3,4,5].lazily.collect { |x| x * 2 }
+    let(:evens) do
+      (1..999).lazily.collect { |x| x * 2 }
     end
 
     it "finds the specified element" do
-      @evens.lazily[2].should == 6
+      evens.lazily[2].should == 6
     end
 
     it "is lazy" do
-      @evens.with_time_bomb.lazily[3].should == 8
+      evens.ecetera.lazily[3].should == 8
     end
 
   end

data/spec/lazily/merging_spec.rb

@@ -5,29 +5,29 @@ describe Lazily, :needs_enumerators => true do
   describe ".merge" do
 
     it "merges multiple Enumerators" do
-      @array1 = [1,3,6]
-      @array2 = [2,4,7]
-      @array3 = [5,8]
-      @merge = Lazily.merge(@array1, @array2, @array3)
-      @merge.to_a.should == [1,2,3,4,5,6,7,8]
+      array1 = [1,3,6]
+      array2 = [2,4,7]
+      array3 = [5,8]
+      merged = Lazily.merge(array1, array2, array3)
+      merged.to_a.should == [1,2,3,4,5,6,7,8]
     end
 
     it "is lazy" do
-      @enum1 = [1,3,6]
-      @enum2 = [2,4,7].with_time_bomb
-      @merge = Lazily.merge(@enum1, @enum2)
-      @merge.take(4).to_a.should == [1,2,3,4]
+      enum1 = [1,3,6]
+      enum2 = [2,4,7].ecetera
+      merged = Lazily.merge(enum1, enum2)
+      merged.should be_lazy
     end
 
-  end
+    context "with a block" do
 
-  describe ".merge_by" do
+      it "uses the block to determine order" do
+        array1 = %w(cccc dd a)
+        array2 = %w(eeeee bbb)
+        merged = Lazily.merge(array1, array2) { |s| -s.length }
+        merged.to_a.should == %w(eeeee cccc bbb dd a)
+      end
 
-    it "uses the block to determine order" do
-      @array1 = %w(cccc dd a)
-      @array2 = %w(eeeee bbb)
-      @merge = Lazily.merge_by(@array1, @array2) { |s| -s.length }
-      @merge.to_a.should == %w(eeeee cccc bbb dd a)
     end
 
   end

data/spec/lazily/prefetching_spec.rb

@@ -37,7 +37,7 @@ describe Lazily do
     end
 
     it "is lazy" do
-      source.with_time_bomb.lazily.prefetch(2).first.should eq(source.first)
+      source.ecetera.lazily.prefetch(2).should be_lazy
     end
 
     it "pre-computes the specified number of elements" do

data/spec/lazily/threading_spec.rb

@@ -13,7 +13,7 @@ describe Lazily, "threading" do
     end
 
     it "is lazy" do
-      [1,2,3].with_time_bomb.lazily.in_threads(2) { |x| x * 2 }.first.should == 2
+      [1,2,3].ecetera.lazily.in_threads(2) { |x| x * 2 }.should be_lazy
     end
 
     def round(n, accuracy = 0.02)

data/spec/lazily/zipping_spec.rb

@@ -10,12 +10,11 @@ describe Lazily, "zipping", :needs_enumerators => true do
 
     it "zips together multiple Enumerables" do
       zip = Lazily.zip(array1, array2, array3)
-      zip.to_a.should == [[1,2,5], [3,4,8], [6,7,nil]]
+      zip.to_a.should == array1.zip(array2, array3)
     end
 
     it "is lazy" do
-      zip = Lazily.zip(%w(a b c), [1,2].with_time_bomb)
-      zip.take(2).to_a.should == [["a", 1], ["b", 2]]
+      Lazily.zip(array1, array2.ecetera).should be_lazy
     end
 
   end
@@ -24,12 +23,11 @@ describe Lazily, "zipping", :needs_enumerators => true do
 
     it "zips an Enumerable with multiple others" do
       zip = array1.lazily.zip(array2, array3)
-      zip.to_a.should == [[1,2,5], [3,4,8], [6,7,nil]]
+      zip.to_a.should == array1.zip(array2, array3)
     end
 
     it "is lazy" do
-      zip = %w(a b c).lazily.zip([1,2].with_time_bomb)
-      zip.take(2).to_a.should == [["a", 1], ["b", 2]]
+      array1.lazily.zip(array2.ecetera).should be_lazy
     end
 
   end

data/spec/spec_helper.rb

@@ -2,7 +2,7 @@ require "lazily"
 
 class NotLazyEnough < StandardError; end
 
-class WithTimeBomb
+class Ecetera
 
   include Enumerable
 
@@ -20,8 +20,8 @@ end
 module Enumerable
 
   # extend an Enumerable to throw an exception after last element
-  def with_time_bomb
-    WithTimeBomb.new(self)
+  def ecetera
+    Ecetera.new(self)
   end
 
   unless method_defined?(:first)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lazily
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-19 00:00:00.000000000 Z
+date: 2013-05-13 00:00:00.000000000 Z
 dependencies: []
 description: ! "    Lazily implements \"lazy\" versions of many Enumerable methods,\n
   \   allowing streamed processing of large (or even infinite) collections.\n\n    It's
@@ -22,8 +22,11 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- CHANGES.md
 - Gemfile
+- README.md
 - Rakefile
+- benchmarks/pipeline_bench.rb
 - lazily.gemspec
 - lib/lazily.rb
 - lib/lazily/combining.rb
@@ -76,3 +79,4 @@ test_files:
 - spec/lazily/zipping_spec.rb
 - spec/lazily_spec.rb
 - spec/spec_helper.rb
+has_rdoc: