coroutines 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d94b2f0be52e246350f8eff0bbdef56df5bfd9ed
-  data.tar.gz: d71f2c7e340d258ac7588d5e315ee1d8fecb3efa
+  metadata.gz: 6075ff02c811ae434bd45a95c49d4e55dbef28a7
+  data.tar.gz: 6533a5e7ab42de553f513c93fee0622fb081f755
 SHA512:
-  metadata.gz: 4b073d2df415afdc01b406a71fce37a04a94218a5a2db425ac4bc20f5fa68dc06e121e6983020ebe6163f409af87dcc66fd2397971375f239985a7de3429b52d
-  data.tar.gz: ded24fe0ab150e7989b55c1413093262abe211bea74d5a593eb9c10abd6a2dfa12c1b205a7cf03bc028162a3d13820e3bb98965036b95b93a257b89884e0cd27
+  metadata.gz: ff68457b130b88bebee3f5df84e3f6cd97b6e7fbef3b9fff7c0b58acf353052abcb4e0a2e976ab02613e7e14f1471ea01f6ab3f7f2a90550a08d62569c520981
+  data.tar.gz: 30b78a1aa708333c17b6d366255d286cdc65252f96deb1debb6748ce09345ed8d144fe9adf8d10f031897b0b4681f345f2f76b586d7f4901259942e7fc65a1e5

data/README.rdoc

@@ -4,13 +4,23 @@ Producers are already provided by Ruby's built-in Enumerator class; this
 library provides Transformer and Consumer classes that work analogously. In
 particular, they are also based on Fiber and not on threads (as in some other
 producer/consumer libraries). Also provides a module Sink, which is analogous
-to Enumerable, and Enumerable/Transformer/Sink composition using overloaded
-<= and >= operators.
+to Enumerable, and Enumerable/Transformer/Sink composition.
 
 == Installing
    gem install coroutines
 
 == Using
+---
+<b>Major change in version 0.2.0:</b> The preferred way of connecting enumerables,
+transformers and sinks is now to use Enumerable#out_connect, Sink#in_connect,
+Transformer#out_connect, Transformer#in_connect. I currently tend to the
+conclusion that descriptive names are more idiomatic Ruby (while the operator
+notation is rather a bit Haskellish). The <= and >= operators are still
+provided by default for backwards-compatibility, and for comparing the relative
+benefits of both notations. However, please consider their usage without
+explicitly requiring 'coroutines/operators' as deprecated. Feedback welcome.
+---
+
 A simple consumer:
 
    require 'coroutines'
@@ -44,11 +54,11 @@ A simple transformer:
    end  
    
    tr = trans_for :running_sum, 3  # => #<Transformer: main:running_sum>
-   sums = (1..10) >= tr  # => #<Enumerator: #<Transformer: main:running_sum> <= 1..10>
+   sums = tr.in_connect(1..10)  # => #<Enumerator::Lazy: #<Transformer: main:running_sum> <= 1..10>
    sums.to_a  # => [4, 6, 9, 13, 18, 24, 31, 39, 48, 58]
 
    tr = trans_for :running_sum, 0  # => #<Transformer: main:running_sum>
-   collect_sums = tr >= []
+   collect_sums = tr.out_connect([])  # => #<Consumer: #<Transformer: main:running_sum> >= []>
    collect_sums << 1 << 1 << 2 << 3 << 5
    collect_sums.close  # => [1, 2, 4, 7, 12]
 
@@ -66,60 +76,99 @@ _accept_ sequences of values:
    [] << "a" << "b" << "c"  # => ["a", "b", "c"]
    "" << "a" << "b" << "c"  # => "abc"
 
-The +coroutines+ library provides the mixin Sink for such classes. Among
-other methods, this provides an operator <= for "connecting" sources (i.e.
-enumerables) to sinks.
+The +coroutines+ library provides the mixin Sink for such classes. Among other
+methods, this provides Sink#in_connect, which "connects" an enumerable (as a
+"source" of values) to a sink's "input". Upon connecting, the enumerable is
+iterated and each value is appended to the sink; then the sink is closed (by
+calling its #close method). Sink#in_connect returns whatever #close returns,
+which defaults to simply returning the sink itself (see Sink#close).
 
-   open("test.txt", "w") <= ["a", "b", "c"]  # write "abc" to test.txt
-   ["a", "b", "c"] <= ("d".."f")  # => ["a", "b", "c", "d", "e", "f"]
-   "abc" <= ("d".."f")  # => "abcdef"
+   open("test.txt", "w").in_connect(["a", "b", "c"])  # write "abc" to test.txt
+   ["a", "b", "c"].in_connect("d".."f")  # => ["a", "b", "c", "d", "e", "f"]
+   "abc".in_connect("d".."f")  # => "abcdef"
 
-Note that <= closes the sink after having exhausted the enumerable,
-returning whatever #close returns. close defaults to simply returning the
-sink itself, as in the Array and String examples above. For IO, which has
-its own close implementation, this implies that the file descriptor will be
-closed after the <= operation finishes. If this is not what you want, use
-dup:
+Note that for IO/File objects, this implies that the file descriptor will be
+closed after in_connect finishes. If this is not what you want, use dup:
 
-   $stdout.dup <= ["a", "b", "c"]  # print "abc"
+   $stdout.dup.in_connect(["a", "b", "c"])  # print "abc"
 
-For symmetry, the coroutines library augments Enumerable with an operator
->= that mirrors <=:
+For symmetry, the coroutines library also implements Enumerable#out_connect, which
+mirrors Sink#in_connect:
 
-   ("d".."f") >= "abc"  # => "abcdef"
+   ("d".."f").out_connect("abc")  # => "abcdef"
 
 == Pipelines involving transformers
-Re-using the running_sum example from above:
+We'll be re-using the running_sum example from above.
 
-   (1..10) >= trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" } >= $stdout.dup
+   (1..10).
+     out_connect(trans_for :running_sum, 0).
+     lazy.map{|x| x.to_s + "\n"}.
+     out_connect($stdout.dup)
 
-What does this do? Well, it takes the sequences of integers from 1 to 10, then
-computes the running sum, then convers each partial sum to a string, and
+What does this do? It takes the sequences of integers from 1 to 10, then
+computes the running sum, then converts each partial sum to a string, and
 finally prints out each string to $stdout. Except that the "thens" in the
 previous sentence are not entirely correct, since the processing stages run  in
-parallel (using coroutines, so blocking IO in one stage will block all other
-stages). Instead of (1..10), we could have a File and iterate over GBs of data,
-and at no point would we need to have the entire sequence in memory.
+parallel (using coroutines where required, so blocking IO in one stage will
+block all other stages). Instead of (1..10), we could have a File and iterate
+over GBs of data, and at no point would we need to have the entire sequence in
+memory.
+
+In the above example, the "lazyness" of the pipeline - that is, the fact that
+we don't have to keep the complete sequence of values in memory at any stage -
+requires Enumerable#lazy. If we replace the lazy.map with a simple map, the
+complete sequence of strings will be stored in an intermediate Array.
+
+[ In order to avoid confusing readers it should be noted that lazy enumerators
+were added in Ruby 2.0; the coroutines gem therefore depends on Charles Oliver
+Nutter's lazy_enumerator gem, which contains a backport of the feature to
+Ruby 1.8/1.9 ]
 
 Any part of a pipeline can be passed around and stored as an individual object:
 
-  enum = (1..10) >= trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" }  # => an Enumerator
-  cons = trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" } >= $stdout.dup  # => a Consumer
-  trans = trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" }  # => a Transformer
+   (1..10).
+     out_connect(trans_for :running_sum, 0).
+     lazy.map{|x| x.to_s + "\n"}
+   # => an Enumerator
 
-== map/filter equivalent pipelines
-As shown above, a Proc object can be used in place of a Transformer. Connecting
-transformer procs to enums, sinks or other procs is special-cased to minimize
-overhead, so that something like
+   trans_for(:running_sum, 0).
+     lazy.map{|x| x.to_s + "\n"}.
+     out_connect($stdout.dup)
+   # => a Consumer
 
-   (1..9) >= proc{|x| x.to_s if x.even? } >= ""
+   trans_for(:running_sum, 0).
+     lazy.map{|x| x.to_s + "\n"}
+   # => a Transformer
+
+Note however that, while the last example works for map and some other common
+Enumerable methods, not all of the Enumerable API is implemented yet.
 
-is just syntactic sugar for
+== Connect operators
+As explained above, the overloaded <= and >= operators are currently provided
+by default; but using them without explicitly requiring 'coroutines/operators'
+is deprecated.
 
-   (1..9).lazy.select{|x| x.even? }.map{|x| x.to_s }.inject(""){|memo, x| memo << x }
+'coroutines/operators' provides a short-hand notation for in_connect,
+out_connect and Enumerable#filter_map by overloading >= and <=:
 
-(And yes, the latter could also be written more succinctly if Enumerator::Lazy
-would provide operations like filter_map and join.)
+   open("test.txt", "w") <= ["a", "b", "c"]  # write "abc" to test.txt
+   ["a", "b", "c"] <= ("d".."f")  # => ["a", "b", "c", "d", "e", "f"]
+   "abc" <= ("d".."f")  # => "abcdef"
+   enum = (1..10) >= trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" }  # => an Enumerator
+   cons = trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" } >= $stdout.dup  # => a Consumer
+   trans = trans_for(:running_sum, 0) >= proc{|x| x.to_s + "\n" }  # => a Transformer
+
+where a Proc object in a pipeline is interpreted as if it were an argument to Enumerable#filter_map; i.e. the following to are equivalent:
+
+   (1..9) >= proc{|x| x.to_s if x.even? } >= ""
+   (1..9).lazy.filter_map{|x| x.to_s if x.even? }.out_connect("")
+
+Apart from saving a few keystrokes (d'oh...), this has a the advantage that all
+elements of a pipeline are lazy _by default_. When using map, filter and
+friends, forgetting to drop a "lazy" in the right place causes this part of the
+pipeline to become strict (but of course it may still produce the intended
+results!). This type of bug can be hard to catch - unless you're always
+testing with production-sized data sets.
 
 == Links and Acknowledgements
 Inspired by {David M. Beazley's Generator Tricks}[http://www.dabeaz.com/generators] (Python)
@@ -139,7 +188,9 @@ Consumer and Transformer manually in order to use them; and you'll have to be
 more explicit when constructing certain pipelines.
 
 Patched core modules and classes are:
-Enumerable::        add Enumerable#>= operator
+Enumerable::        add Enumerable#filter_map, Enumerable#out_connect and
+                    Enumerable#>= operator
+Enumerator::Lazy::  add Enumerator::Lazy#filter_map
 IO, Array, String:: include Sink mixin
 Hash::              define Hash#<< operator and include Sink mixin
 Method::            define Method#<< operator, define Method#close as an alias
@@ -148,3 +199,10 @@ Object::            define Object#await, Object#consum_for and Object#trans_for
 Proc::              define Proc#to_trans, Proc#<= and Proc#>=
 Symbol::            define Symbol#to_trans, Symbol#<= and Symbol#>=
 
+== Contributing
+1. Fork it {on Github}[https://github.com/nome/coroutines]
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/lib/coroutines/base.rb

@@ -1,5 +1,6 @@
 require 'fiber'
 require 'coroutines/sink'
+require 'lazy_enumerator' unless defined? Enumerator::Lazy
 
 # A class implementing consumer coroutines
 #
@@ -7,7 +8,7 @@ require 'coroutines/sink'
 # * Object#consum_for
 # * Object#consumer
 # * Consumer.new
-# * Transformer#>=
+# * Transformer#out_connect
 #
 # See Object#consum_for for an explanation of the basic concepts.
 class Consumer
@@ -111,13 +112,13 @@ end
 # Transformers are pieces of code that accept input values and produce output
 # values (without returning from their execution context like in a regular
 # method call). They are used by connecting either their input to an enumerable
-# or their output to a sink (or both, using Sink#<= or Enumerable#>=). An
-# enumerable is any object implementing an iterator method each; a sink is
-# any object implementing the << operator (which is assumed to store or
-# output the supplied values in some form).
+# or their output to a sink (or both, using Sink#in_connect or
+# Enumerable#out_connect). An enumerable is any object implementing an iterator
+# method each; a sink is any object implementing the << operator (which is
+# assumed to store or output the supplied values in some form).
 #
 # The input of a transformer is connected to an enumerable +enum+ using
-# trans <= enum, the result of which is a new Enumerator instance. The
+# trans.in_connect(enum), the result of which is a new Enumerator instance. The
 # transformer is started upon iterating over this Enumerator. Whenever the
 # transformer requests a new input value (see Object#trans_for and
 # Transformer#new for how to do this), iteration over +enum+ is resumed. The
@@ -128,19 +129,20 @@ end
 # terminate without requesting any more values (though it may execute e.g. some
 # cleanup actions).
 #
-# The output of a transformer is connected to a sink using trans >= sink, the
-# result of which is a new Consumer instance. The transformer starts
-# executing right away; when it requests its first input value, the >=
-# operation returns. Input values supplied using << to the enclosing
-# Consumer are forwarded to the transformer by resuming execution at the
-# point where it last requested an input value. Output values produced by the
+# The output of a transformer is connected to a sink using
+# trans.out_connect(sink), the result of which is a new Consumer instance. The
+# transformer starts executing right away; when it requests its first input
+# value, out_connect returns. Input values supplied using << to the enclosing
+# Consumer are forwarded to the transformer by resuming execution at the point
+# where it last requested an input value. Output values produced by the
 # transformer are fed to sink#<<. After terminating, the result of the new
 # Consumer is the value returned by sink.close (see Consumer#result and
 # Consumer#close).
 #
 # Transformers can also be chained together by connecting the output of one the
-# input the next using trans >= other_trans or trans <= other_trans. See
-# Transformer#>= and Transformer#<= for details.
+# input the next using trans.out_connect(other_trans) or
+# trans.in_connect(other_trans). See Transformer#out_connect and
+# Transformer#in_connect for details.
 #
 class Transformer
 	# :call-seq:
@@ -158,7 +160,7 @@ class Transformer
 	#     loop { result += y.await; y.yield result }
 	#   end
 	# 
-	#   (1..3) >= running_sum >= []  # => [1, 3, 6]
+	#   (1..3).out_connect(running_sum).out_connect([])  # => [1, 3, 6]
 	#
 	def initialize(&block)
 		@self = block
@@ -177,15 +179,15 @@ class Transformer
 	end
 
 	# :call-seq:
-	#   trans <= other_trans  -> new_trans
-	#   trans <= enum         -> new_enum
+	#   trans.in_connect(other_trans)  -> new_trans
+	#   trans.in_connect(enum)         -> lazy_enumerator
 	#
 	# In the first form, creates a new Transformer that has the input of
 	# +trans+ connected to the output of +other_trans+.
 	#
-	# In the second form, creates a new Enumerator by connecting +enum+ to
-	# the input of +trans+. See Transformer for details.
-	def <=(source)
+	# In the second form, creates a new lazy Enumerator by connecting the
+	# output of +enum+ to the input of +trans+. See Transformer for details.
+	def in_connect(source)
 		if not source.respond_to? :each
 			return source.to_trans.transformer_chain self
 		end
@@ -196,9 +198,9 @@ class Transformer
 				source_enum.next
 			end
 			@self.call(y)
-		end
+		end.lazy
 
-		description = "#<Enumerator: #{inspect} <= #{source.inspect}>"
+		description = "#<Enumerator::Lazy: #{inspect} <= #{source.inspect}>"
 		enum.define_singleton_method :inspect do
 			description
 		end
@@ -207,15 +209,15 @@ class Transformer
 	end
 
 	# :call-seq:
-	#   trans >= other_trans  -> new_trans
-	#   trans >= sink         -> consum
+	#   trans.out_connect(other_trans)  -> new_trans
+	#   trans.out_connect(sink)         -> consum
 	#
 	# In the first form, creates a new Transformer that has the output of
 	# +trans+ connected to the input of +other_trans+.
 	#
 	# In the second form, creates a new Consumer by connecting the output of
-	# +trans+ to +sink+. See Transformer for details.
-	def >=(sink)
+	# +trans+ to the input of +sink+. See Transformer for details.
+	def out_connect(sink)
 		if not sink.respond_to? :<<
 			return transformer_chain sink.to_trans
 		end
@@ -223,6 +225,7 @@ class Transformer
 		consum = Consumer.new do |y|
 			y.define_singleton_method :yield do |args|
 				sink << args
+				y
 			end
 			y.singleton_class.instance_eval { alias_method :<<, :yield }
 			begin
@@ -240,6 +243,299 @@ class Transformer
 		consum
 	end
 
+	class Lazy
+		def initialize(trans)
+			@trans = trans.instance_variable_get :@self
+		end
+
+		def lazy
+			self
+		end
+
+		class Yielder
+			def initialize(wrapped)
+				@wrapped = wrapped
+			end
+			def await
+				@wrapped.await
+			end
+
+			def define_yield(&block)
+				singleton_class.instance_eval do
+					define_method(:yield, &block)
+					alias_method :<<, :yield
+				end
+			end
+		end
+
+		def count
+			Consumer.new do |y|
+				yy = Yielder.new y
+				n = 0
+				yy.define_yield do |*values|
+					n += 1
+					yy
+				end
+				@trans.call yy
+				n
+			end
+		end
+
+		def drop(n)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				to_drop = n
+				yy.define_yield do |*values|
+					if to_drop > 0
+						to_drop -= 1
+					else
+						y.yield(*values)
+					end
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def drop_while(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				dropping = true
+				yy.define_yield do |*values|
+					if dropping
+						if not block.call(*values)
+							dropping = false
+							y.yield(*values)
+						end
+					else
+						y.yield(*values)
+					end
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def each(&block)
+			Consumer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					block.call(*values)
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def filter_map(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					x = block.call(*values)
+					y.yield(x) unless x.nil?
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def flat_map(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					x = block.call(*values)
+					if x.respond_to? :to_ary
+						x.to_ary.each{|xx| y.yield xx }
+					else
+						y.yield x
+					end
+					yy
+				end
+				@trans.call yy
+			end
+		end
+		alias_method :collect_concat, :flat_map
+
+		def map(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					y.yield(block.call(*values))
+					yy
+				end
+				@trans.call yy
+			end
+		end
+		alias_method :collect, :map
+
+		def out_connect(other)
+			Transformer.new(&@trans).out_connect(other)
+		end
+
+		def reduce(*args)
+			if not block_given?
+				if args.size == 1
+					return reduce(&args[0].to_proc)
+				elsif args.size == 2
+					return reduce(args[0], &args[1].to_proc)
+				else
+					raise ArgumentError, "wrong number of arguments"
+				end
+			end
+			raise ArgumentError, "wrong number of arguments" if args.size > 1
+			block = proc
+
+			memo = if args.empty? then nil else args[0] end
+			Consumer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |value|
+					if memo.nil?
+						memo = value
+					else
+						memo = block.call memo, value
+					end
+					yy
+				end
+				@trans.call yy
+				memo
+			end
+		end
+		alias_method :inject, :reduce
+
+		def reject(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					y.yield(*values) unless block.call(*values)
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def select(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					y.yield(*values) if block.call(*values)
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def take(n)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				to_take = n
+				yy.define_yield do |*values|
+					if to_take > 0
+						y.yield(*values)
+						to_take -= 1
+					else
+						raise StopIteration
+					end
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def take_while(&block)
+			Transformer.new do |y|
+				yy = Yielder.new y
+				yy.define_yield do |*values|
+					if block.call(*values)
+						y.yield(*values)
+					else
+						raise StopIteration
+					end
+					yy
+				end
+				@trans.call yy
+			end
+		end
+
+		def sort
+			Consumer.new do |y|
+				yy = Yielder.new y
+				result = []
+				yy.define_yield do |value|
+					result << value
+					yy
+				end
+				@trans.call yy
+				result.sort
+			end
+		end
+
+		def sort_by(&block)
+			Consumer.new do |y|
+				yy = Yielder.new y
+				result = []
+				yy.define_yield do |value|
+					result << value
+					yy
+				end
+				@trans.call yy
+				result.sort_by(&block)
+			end
+		end
+
+		def to_a
+			Consumer.new do |y|
+				yy = Yielder.new y
+				result = []
+				yy.define_yield do |value|
+					result << value
+					yy
+				end
+				@trans.call yy
+				result
+			end
+		end
+
+		def to_h
+			Consumer.new do |y|
+				yy = Yielder.new y
+				result = {}
+				yy.define_yield do |value|
+					result[value[0]] = value[1]
+					yy
+				end
+				@trans.call yy
+				result
+			end
+		end
+	end
+
+	# :call-seq:
+	#    trans.lazy -> lazy_trans
+	#
+	# Returns a "lazy enumeration like" transformer. More precisely, the object
+	# returned can in many situations be used as if it were an Enumerator
+	# returned by trans.in_connect, since it implements work-alikes of many
+	# Enumerable methods. Note however that the return types of those methods
+	# differ: where an Enumerator method would return a new Enumerator, the
+	# corresponding lazy transformer returns a new Transformer; where an
+	# Enumerator would return a single value, the lazy transformer returns a
+	# Consumer.
+	#
+	# Example:
+	#
+	#   running_sum = Transformer.new do |y|
+	#     result = 0
+	#     loop { result += y.await; y.yield result }
+	#   end
+	#
+	#   sum_str = running_sum.lazy.map{|x| x.to_s}
+	#   # => a Transformer
+	#   (1..10).out_connect(sum_str).to_a
+	#   # => ["1", "3", "6", "10", "15", "21", "28", "36", "45", "55"]
+	def lazy
+		Lazy.new self
+	end
+
 	protected
 
 	class FirstYielder < Consumer::Yielder
@@ -249,6 +545,7 @@ class Transformer
 			end
 			def yield(*args)
 				Fiber.yield(:yield, *args)
+				self
 			end
 			alias_method :<<, :yield
 		else
@@ -260,6 +557,7 @@ class Transformer
 			def yield(*args)
 				item = Fiber.yield(:yield, *args)
 				raise(*item.args) if item.instance_of? @@exception_wrapper
+				self
 			end
 			alias_method :<<, :yield
 		end
@@ -305,6 +603,7 @@ class Transformer
 
 		def yield(*args)
 			@y.yield(*args)
+			self
 		end
 		alias_method :<<, :yield
 	end

data/lib/coroutines/operators.rb

@@ -0,0 +1,180 @@
+require 'coroutines/base'
+
+module Enumerable
+	# :call-seq:
+	#   enum >= sink  -> obj
+	#   enum >= trans -> new_enum
+	#
+	# In the first form, iterate over +enum+ and write each result to +sink+
+	# using <<; then return the result of sink.close.
+	#
+	# In the second form, create a new Enumerator by connecting the output of
+	# +enum+ to the input of +trans+ (which must be convertible to a
+	# Transformer using the to_trans method).
+	def >=(other)
+		if other.respond_to? :<<
+			begin
+				each { |x| other << x }
+			rescue StopIteration
+			end
+			other.close
+		elsif other.respond_to? :to_trans
+			other <= self
+		end
+	end
+end
+
+module Sink
+	# :call-seq:
+	#   sink <= enum  -> obj
+	#   sink <= trans -> new_consum
+	#
+	# In the first form, iterate over +enum+ and write each result to +sink+
+	# using <<; then return the result of sink.close.
+	#
+	# In the second form, create a new Consumer by connecting the output of
+	# +trans+ (which must be convertible to a Transformer using the
+	# to_trans method) to the input of +sink+.
+	def <=(other)
+		if other.respond_to? :each
+			begin
+				other.each { |x| self << x }
+			rescue StopIteration
+			end
+			close
+		elsif other.respond_to? :to_trans
+			other >= self
+		end
+	end
+end
+
+class Transformer
+	alias_method :<=, :in_connect
+	alias_method :>=, :out_connect
+end
+
+class Symbol
+	# :call-seq:
+	#   sym.to_trans -> transformer
+	#
+	# Allows implicit conversion of Symbol to Transformer. The transformer
+	# accepts any objects as input, calls the method given by +sym+ on each and
+	# outputs all non-nil results of the method. See Proc#to_trans for details.
+	#
+	# example:
+	#
+	#   collector = [] <= :to_s
+	#   collector << 1 << 4 << 9
+	#   collector.close # => ["1", "4", "9"]
+	#
+	def to_trans
+		Transformer.new do |y|
+			loop do
+				value = y.await.send self
+				y.yield value unless value.nil?
+			end
+		end
+	end
+
+	# :call-seq:
+	#   sym <= trans  -> new_trans
+	#   sym <= enum   -> new_enum
+	#
+	# Equivalent to sym.to_trans <= trans/enum, except that it uses a more
+	# efficient implementation.
+	def <=(source)
+		to_proc <= source
+	end
+
+	# :call-seq:
+	#   sym >= trans  -> new_trans
+	#   sym >= sink   -> new_consumer
+	#
+	# Equivalent to sym.to_trans >= trans/sink, except that it uses a more
+	# efficient implementation.
+	def >=(sink)
+		to_proc >= sink
+	end
+end
+
+class Proc
+	# :call-seq:
+	#   proc.to_trans -> transformer
+	#
+	# Allows implicit conversion of Proc to Transformer. The transformer is a
+	# combination of map and filter over its input values: For each input
+	# value, +proc+ is called with the input value as parameter. Every non-nil
+	# value returned by +proc+ is yielded as an output value.
+	#
+	# This is similar to Enumerable#map followed by Array#compact, but without
+	# constructing the intermediate Array (so it's even more similar to
+	# something like enum.lazy.map(&proc).reject(&:nil?), using the lazy
+	# enumerator introduced in Ruby 2.0).
+	#
+	# Example:
+	#
+	#   (1..10) >= proc{|x| x.to_s + ", " if x.even? } >= ""
+	#   # => "2, 4, 6, 8, 10, "
+	#
+	def to_trans
+		Transformer.new do |y|
+			loop do
+				value = self.call(y.await)
+				y.yield value unless value.nil?
+			end
+		end
+	end
+
+	# :call-seq:
+	#   proc <= trans  -> new_trans
+	#   proc <= enum   -> new_enum
+	#
+	# Equivalent to proc.to_trans <= trans/enum, except that it uses a more
+	# efficient implementation.
+	def <=(source)
+		if source.respond_to? :each
+			Enumerator.new do |y|
+				source.each do |obj|
+					value = call obj
+					y << value unless value.nil?
+				end
+			end.lazy
+		elsif source.respond_to? :to_proc
+			sp = source.to_proc
+			proc do |*args|
+				value = sp.call(*args)
+				if value.nil? then nil else self.call value end
+			end
+		elsif source.respond_to? :to_trans
+			# FIXME: this could be implemented more efficiently; proc doesn't
+			#        need to run in a separate Fiber
+			self.to_trans <= source.to_trans
+		else
+			raise ArgumentError, "#{source.inspect} is neither an enumerable nor a transformer"
+		end
+	end
+
+	# :call-seq:
+	#   proc >= trans  -> new_trans
+	#   proc >= sink   -> new_consumer
+	#
+	# Equivalent to proc.to_trans >= trans/sink, except that it uses a more
+	# efficient implementation.
+	def >=(sink)
+		if sink.respond_to? :input_map
+			sink.input_reject(&:nil?).input_map(&self)
+		elsif sink.respond_to? :to_proc
+			sp = sink.to_proc
+			proc do |*args|
+				value = self.call(*args)
+				if value.nil? then nil else sp.call value end
+			end
+		elsif sink.respond_to? :to_trans
+			# FIXME: this could be implemented more efficiently; proc doesn't
+			#        need to run in a separate Fiber
+			self.to_trans >= sink.to_trans
+		else
+			raise ArgumentError, "#{sink.inspect} is neither a sink nor a transformer"
+		end
+	end
+end

data/lib/coroutines/sink.rb

@@ -11,8 +11,8 @@ module Sink
 	end
 
 	# :call-seq:
-	#   sink <= enum  -> obj
-	#   sink <= trans -> new_consum
+	#   sink.in_connect(enum)  -> obj
+	#   sink.in_connect(trans) -> new_consum
 	#
 	# In the first form, iterate over +enum+ and write each result to +sink+
 	# using <<; then return the result of sink.close.
@@ -20,7 +20,7 @@ module Sink
 	# In the second form, create a new Consumer by connecting the output of
 	# +trans+ (which must be convertible to a Transformer using the
 	# to_trans method) to +sink+.
-	def <=(other)
+	def in_connect(other)
 		if other.respond_to? :each
 			begin
 				other.each { |x| self << x }
@@ -28,7 +28,7 @@ module Sink
 			end
 			close
 		elsif other.respond_to? :to_trans
-			other >= self
+			other.to_trans.out_connect(self)
 		end
 	end
 

data/lib/coroutines.rb

@@ -1,21 +1,22 @@
 require 'coroutines/base'
+require 'coroutines/operators' # deprecated
 
 #--
-# Most of the Sink methods mirror Enumerable, except for <=
-# for symmetry, also add a >= method to Enumerable
+# Most of the Sink methods mirror Enumerable, except for #in_connect
+# for symmetry, also add an #out_connect method to Enumerable
 #++
 module Enumerable
 	# :call-seq:
-	#   enum >= sink  -> obj
-	#   enum >= trans -> new_enum
+	#   enum.out_connect(sink)  -> obj
+	#   enum.out_connect(trans) -> new_enum
 	#
 	# In the first form, iterate over +enum+ and write each result to +sink+
 	# using <<; then return the result of sink.close.
 	#
-	# In the second form, create a new Enumerator by connecting +enum+ to the
-	# input of +trans+ (which must be convertible to a Transformer using the
-	# to_trans method).
-	def >=(other)
+	# In the second form, create a new Enumerator by connecting the output of
+	# +enum+ to the input of +trans+ (which must be convertible to a
+	# Transformer using the to_trans method).
+	def out_connect(other)
 		if other.respond_to? :<<
 			begin
 				each { |x| other << x }
@@ -23,7 +24,34 @@ module Enumerable
 			end
 			other.close
 		elsif other.respond_to? :to_trans
-			other <= self
+			other.to_trans.in_connect(self)
+		end
+	end
+
+	# :call-seq:
+	#   enum.filter_map {|obj| block }  -> array
+	#
+	# For each +obj+ in in +enum+, calls +block+, and collects its non-nil
+	# return values into a new +array+.
+	#--
+	# taken from the API doc of Enumerator::Lazy.new
+	def filter_map(&block)
+		map(&block).compact
+	end
+end
+
+class Enumerator::Lazy
+	# :call-seq:
+	#   enum.filter_map {|obj| block }  -> an_enumerator
+	#
+	# Returns a new lazy Enumerator which iterates over all non-nil values
+	# returned by +block+ while +obj+ iterates over +enum+.
+	#--
+	# taken from the API doc of Enumerator::Lazy.new
+	def filter_map
+		Lazy.new(self) do |yielder, *values|
+			result = yield *values
+			yielder << result if result
 		end
 	end
 end
@@ -145,10 +173,10 @@ class Object
 	# analogous to using Kernel#enum_for to create an Enumerator instance, or
 	# using Object#consum_for to create a Consumer instance. The method is not
 	# executed immediately. The resulting Transformer can be connected to an
-	# enumerable (using transformer <= enum) or to a sink (using
-	# transformer >= sink). The point at which the transformer method gets
-	# started depends on how it is connected; in any case however, the method
-	# will be called with the +args+ given to trans_for. See Transformer
+	# enumerable (using transformer.in_connect(enum)) or to a sink (using
+	# transformer.out_connect(sink)). The point at which the transformer method
+	# gets started depends on how it is connected; in any case however, the
+	# method will be called with the +args+ given to trans_for. See Transformer
 	# for details.
 	#
 	# Within the transformer method, #await can be used to read the next
@@ -164,7 +192,7 @@ class Object
 	#   end
 	#
 	#   tr = trans_for :running_sum, 3  #=> #<Transformer: main:running_sum>
-	#   sums = (1..10) >= tr  #=> #<Enumerator: #<Transformer: main:running_sum> <= 1..10>
+	#   sums = (1..10).out_connect(tr)  #=> #<Enumerator: #<Transformer: main:running_sum> <= 1..10>
 	#   sums.to_a  #=> [4, 6, 9, 13, 18, 24, 31, 39, 48, 58]
 	#
 	def trans_for(meth, *args)
@@ -180,155 +208,3 @@ class Object
 	end
 end
 
-class Symbol
-	# :call-seq:
-	#   sym.to_trans -> transformer
-	#
-	# Allows implicit conversion of Symbol to Transformer. The transformer
-	# accepts any objects as input, calls the method given by +sym+ on each and
-	# outputs all non-nil results of the method. See Proc#to_trans for details.
-	#
-	# example:
-	#
-	#   collector = [] <= :to_s
-	#   collector << 1 << 4 << 9
-	#   collector.close # => ["1", "4", "9"]
-	#
-	def to_trans
-		Transformer.new do |y|
-			loop do
-				value = y.await.send self
-				y.yield value unless value.nil?
-			end
-		end
-	end
-
-	# :call-seq:
-	#   sym <= trans  -> new_trans
-	#   sym <= enum   -> new_enum
-	#
-	# Equivalent to sym.to_trans <= trans/enum, except that it uses a more
-	# efficient implementation.
-	def <=(source)
-		to_proc <= source
-	end
-
-	# :call-seq:
-	#   sym >= trans  -> new_trans
-	#   sym >= sink   -> new_consumer
-	#
-	# Equivalent to sym.to_trans >= trans/sink, except that it uses a more
-	# efficient implementation.
-	def >=(sink)
-		to_proc >= sink
-	end
-end
-
-# Define a poor man's Enumerator::Lazy for Ruby < 2.0
-if defined? Enumerator::Lazy
-	LazyEnumerator = Enumerator::Lazy
-else
-	class LazyEnumerator
-		def initialize(obj, &block)
-			@obj = obj; @block = block
-		end
-
-		class Yielder
-			def initialize(iter_block)
-				@iter_block = iter_block
-			end
-			def yield(*values)
-				@iter_block.call(*values)
-			end
-			alias_method :<<, :yield
-		end
-
-		def each(&iter_block)
-			yielder = Yielder.new(iter_block)
-			@obj.each do |*args|
-				@block.call(yielder, *args)
-			end
-		end
-		include Enumerable
-	end
-end
-
-class Proc
-	# :call-seq:
-	#   proc.to_trans -> transformer
-	#
-	# Allows implicit conversion of Proc to Transformer. The transformer is a
-	# combination of map and filter over its input values: For each input
-	# value, +proc+ is called with the input value as parameter. Every non-nil
-	# value returned by +proc+ is yielded as an output value.
-	#
-	# This is similar to Enumerable#map followed by Array#compact, but without
-	# constructing the intermediate Array (so it's even more similar to
-	# something like enum.lazy.map(&proc).reject(&:nil?), using the lazy
-	# enumerator introduced in Ruby 2.0).
-	#
-	# Example:
-	#
-	#   (1..10) >= proc{|x| x.to_s + ", " if x.even? } >= ""
-	#   # => "2, 4, 6, 8, 10, "
-	#
-	def to_trans
-		Transformer.new do |y|
-			loop do
-				value = self.call(y.await)
-				y.yield value unless value.nil?
-			end
-		end
-	end
-
-	# :call-seq:
-	#   proc <= trans  -> new_trans
-	#   proc <= enum   -> new_enum
-	#
-	# Equivalent to proc.to_trans <= trans/enum, except that it uses a more
-	# efficient implementation.
-	def <=(source)
-		if source.respond_to? :each
-			LazyEnumerator.new(source) do |y, *args|
-				value = call(*args)
-				y << value unless value.nil?
-			end
-		elsif source.respond_to? :to_proc
-			sp = source.to_proc
-			proc do |*args|
-				value = sp.call(*args)
-				if value.nil? then nil else self.call value end
-			end
-		elsif source.respond_to? :to_trans
-			# FIXME: this could be implemented more efficiently; proc doesn't
-			#        need to run in a separate Fiber
-			self.to_trans <= source.to_trans
-		else
-			raise ArgumentError, "#{source.inspect} is neither an enumerable nor a transformer"
-		end
-	end
-
-	# :call-seq:
-	#   proc >= trans  -> new_trans
-	#   proc >= sink   -> new_consumer
-	#
-	# Equivalent to proc.to_trans >= trans/sink, except that it uses a more
-	# efficient implementation.
-	def >=(sink)
-		if sink.respond_to? :input_map
-			sink.input_reject(&:nil?).input_map(&self)
-		elsif sink.respond_to? :to_proc
-			sp = sink.to_proc
-			proc do |*args|
-				value = self.call(*args)
-				if value.nil? then nil else sp.call value end
-			end
-		elsif sink.respond_to? :to_trans
-			# FIXME: this could be implemented more efficiently; proc doesn't
-			#        need to run in a separate Fiber
-			self.to_trans >= sink.to_trans
-		else
-			raise ArgumentError, "#{sink.inspect} is neither a sink nor a transformer"
-		end
-	end
-end

data/tests/suite.rb

@@ -0,0 +1,4 @@
+require 'test_sink'
+require 'test_enumerable'
+require 'test_coroutines'
+require 'test_operators'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coroutines
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Knut Franke
@@ -9,15 +9,28 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2014-10-12 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lazy_enumerator
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   A library for creating and composing producer/transformer/consumer coroutines.
   Producers are already provided by Ruby's built-in Enumerator class; this
   library provides Transformer and Consumer classes that work analogously. In
   particular, they are also based on Fiber and not on threads (as in some other
   producer/consumer libraries). Also provides a module Sink, which is analogous
-  to Enumerable, and Enumerable/Transformer/Sink composition using overloaded
-  <= and >= operators.
+  to Enumerable, and Enumerable/Transformer/Sink composition.
 email: knut.franke@gmx.de
 executables: []
 extensions: []
@@ -27,8 +40,9 @@ files:
 - README.rdoc
 - lib/coroutines.rb
 - lib/coroutines/base.rb
+- lib/coroutines/operators.rb
 - lib/coroutines/sink.rb
-- tests/test_coroutines.rb
+- tests/suite.rb
 homepage: https://github.com/nome/coroutines
 licenses:
 - Ruby
@@ -55,5 +69,5 @@ signing_key:
 specification_version: 4
 summary: Library for producer/transformer/consumer coroutines
 test_files:
-- tests/test_coroutines.rb
-has_rdoc: false
+- tests/suite.rb
+has_rdoc: true

data/tests/test_coroutines.rb

@@ -1,154 +0,0 @@
-require 'coroutines'
-require 'test/unit'
-
-class TestCoroutines < Test::Unit::TestCase
-	def test_sink
-		assert_equal("abcdef", "abc" <= ("d".."f"))
-		assert_equal([1,2,3,4], [1] <= [2,3,4])
-	end
-
-	def test_source
-		assert_equal("abcdef", ("d".."f") >= "abc")
-		assert_equal([1,2,3,4], [2,3,4] >= [1])
-	end
-
-	def test_consumer
-		c = Consumer.new { |y| [ y.await, y.await ] }
-		c << :first << :second
-		assert_equal([:first, :second], c.close)
-	end
-
-	def counter(start)
-		result = start
-		loop { result += await }
-		"Final value: #{result}"
-	end
-	def test_consumer_method
-		c = consum_for :counter, 10
-		c << 10 << 1000 << 10000
-		assert_equal("Final value: 11020", c.close)
-	end
-
-	def test_transformer
-		rs = Transformer.new do |y|
-			result = 0
-			loop { result += y.await; y.yield result }
-		end
-		assert_equal([1, 3, 6], (1..3) >= rs >= [])
-
-		rs = Transformer.new do |y|
-			result = 0
-			loop { result += y.await; y.yield result }
-		end
-		assert_equal([1, 3, 6], [] <= rs <= (1..3))
-	end
-
-	def test_transformer_chaining
-		t1 = Transformer.new{|y| y.yield (y.await + "a")}
-		t2 = Transformer.new{|y| y.yield (y.await + "b")}
-		t = t1 >= t2
-		result = %w{x y z} >= t >= []
-		assert_equal(["xab"], result)
-	end
-
-	def test_associativity
-		s = (1..3)
-		def t1
-			Transformer.new{|y| loop { y.yield y.await.to_s } }
-		end
-		def t2
-			Transformer.new{|y| loop { y.yield (y.await + ",") } }
-		end
-
-		assert_equal("1,2,3,", s >= t1 >= t2 >= "")
-		assert_equal("1,2,3,", s >= t1 >= (t2 >= ""))
-		assert_equal("1,2,3,", s >= (t1 >= t2 >= ""))
-		assert_equal("1,2,3,", s >= (t1 >= t2) >= "")
-		assert_equal("1,2,3,", s >= ((t1 >= t2) >= ""))
-
-		assert_equal("1,2,3,", "" <= t2 <= t1 <= s)
-		assert_equal("1,2,3,", "" <= t2 <= (t1 <= s))
-		assert_equal("1,2,3,", "" <= (t2 <= t1 <= s))
-		assert_equal("1,2,3,", "" <= (t2 <= t1) <= s)
-		assert_equal("1,2,3,", "" <= ((t2 <= t1) <= s))
-	end
-
-	def running_sum(start)
-		result = start
-		loop { result += await; yield result }
-	end
-	def test_transformer_method
-		assert_equal([4, 6, 9], (1..3) >= trans_for(:running_sum, 3) >= [])
-		assert_equal([4, 6, 9], (1..3) >= (trans_for(:running_sum, 3) >= []))
-	end
-
-	def test_stop_iteration
-		consume_three = Consumer.new do |y|
-			[y.await, y.await, y.await]
-		end
-		assert_equal([1,2,3], (1..Float::INFINITY) >= consume_three)
-
-		limit_three = Transformer.new do |y|
-			3.times { y.yield y.await }
-		end
-		assert_equal([1,2,3], (1..Float::INFINITY) >= limit_three >= [])
-	end
-
-	def test_transformer_procs
-		s = (1..3)
-		t1_proc = proc{|x| x.to_s }
-		t2_proc = proc{|x| x + "," }
-		def t1
-			Transformer.new{|y| loop { y.yield y.await.to_s } }
-		end
-		def t2
-			Transformer.new{|y| loop { y.yield (y.await + ",") } }
-		end
-
-		assert_equal("1,2,3,", s >= t1_proc >= t2_proc >= "")
-		assert_equal("1,2,3,", s >= t1_proc >= (t2_proc >= ""))
-		assert_equal("1,2,3,", s >= (t1_proc >= t2_proc >= ""))
-		assert_equal("1,2,3,", s >= (t1_proc >= t2_proc) >= "")
-		assert_equal("1,2,3,", s >= ((t1_proc >= t2_proc) >= ""))
-
-		assert_equal("1,2,3,", "" <= t2_proc <= t1_proc <= s)
-		assert_equal("1,2,3,", "" <= t2_proc <= (t1_proc <= s))
-		assert_equal("1,2,3,", "" <= (t2_proc <= t1_proc <= s))
-		assert_equal("1,2,3,", "" <= (t2_proc <= t1_proc) <= s)
-		assert_equal("1,2,3,", "" <= ((t2_proc <= t1_proc) <= s))
-
-		assert_equal("1,2,3,", s >= t1_proc >= t2 >= "")
-		assert_equal("1,2,3,", s >= t1_proc >= (t2 >= ""))
-		assert_equal("1,2,3,", s >= (t1_proc >= t2 >= ""))
-		assert_equal("1,2,3,", s >= (t1_proc >= t2) >= "")
-		assert_equal("1,2,3,", s >= ((t1_proc >= t2) >= ""))
-
-		assert_equal("1,2,3,", "" <= t2 <= t1_proc <= s)
-		assert_equal("1,2,3,", "" <= t2 <= (t1_proc <= s))
-		assert_equal("1,2,3,", "" <= (t2 <= t1_proc <= s))
-		assert_equal("1,2,3,", "" <= (t2 <= t1_proc) <= s)
-		assert_equal("1,2,3,", "" <= ((t2 <= t1_proc) <= s))
-
-		assert_equal("1,2,3,", s >= t1 >= t2_proc >= "")
-		assert_equal("1,2,3,", s >= t1 >= (t2_proc >= ""))
-		assert_equal("1,2,3,", s >= (t1 >= t2_proc >= ""))
-		assert_equal("1,2,3,", s >= (t1 >= t2_proc) >= "")
-		assert_equal("1,2,3,", s >= ((t1 >= t2_proc) >= ""))
-
-		assert_equal("1,2,3,", "" <= t2_proc <= t1 <= s)
-		assert_equal("1,2,3,", "" <= t2_proc <= (t1 <= s))
-		assert_equal("1,2,3,", "" <= (t2_proc <= t1 <= s))
-		assert_equal("1,2,3,", "" <= (t2_proc <= t1) <= s)
-		assert_equal("1,2,3,", "" <= ((t2_proc <= t1) <= s))
-	end
-
-	def test_transformer_proc_filter
-		assert_equal("2468", (1..9) >= proc{|x| x.to_s if x.even? } >= "")
-		assert_equal("2468", (1..9) >= proc{|x| x if x.even? } >= proc{|x| x.to_s} >= "")
-		assert_equal("56789", (5..15) >= proc{|x| x.to_s } >= proc{|s| s if s.length == 1 } >= "")
-	end
-
-	def test_multiple_args
-		assert_equal([[1,2],[3,4]], [[1,2],[3,4]] >= proc{|a,b| [a,b]} >= [])
-	end
-end