stepladder 0.0.2 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cd6ff328453446dc663837b4e70fd2df7d82de39429409418445e597b393d86
+  data.tar.gz: 9907fe3ed9411bcb7dc50ad62a08cd50faaecfd5bed31d172948e5997c3c87dc
+SHA512:
+  metadata.gz: 6ad4c68022bf02a60ad99c60fd7ed77b5d67f20e88e1adf344b1957807249065329279cc70afcf6759886f4fdfb0e49152bf406533215693a57e261df66142d1
+  data.tar.gz: 262b43d27e1d36b5da47a648611d75b912545a6487ec1acf493b08c91ce39c3b10ca3e355de5b969e27558aeaaaee0519ba8fd3c5ccc186ce23b8a8155be7cec

data/.gitignore

@@ -1,4 +1,6 @@
 ./spikes/*
 .rvmrc
+.ruby-version
+.ruby-gemset
 Gemfile.lock
 pkg

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - 2.5.0
+  - jruby-19mode

data/Gemfile

@@ -1,5 +1,8 @@
 source 'http://rubygems.org'
 
-gem 'cucumber'
-gem 'aruba'
-gem 'rspec'
+gem 'rake',        '10.3.2'
+gem 'rspec',       '3.1.0'
+gem 'rspec-core',  '3.1.2'
+gem 'rspec-its',   '1.0.1'
+gem 'rspec-given', '3.8.0'
+gem 'pry'

data/README.md

@@ -1,112 +1,255 @@
+[![Build Status](https://travis-ci.org/joelhelbling/stepladder.png)](https://travis-ci.org/joelhelbling/stepladder)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/joelhelbling/stepladder)
+
 # The Stepladder Framework
 
 _"How many Ruby fibers does it take to screw in a lightbulb?"_
 
 ## Quick Start
 
-### Workers have tasks...
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stepladder'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself:
 
-Initialize with a block of code:
+    $ gem install steplader
+
+And then use it:
 
 ```ruby
-source_worker = Stepladder::Worker.new { "hulk" }
+require 'stepladder'
+```
+
+## New!  Stepladders now has a DSL!
+
+As of version ?? there is now a DSL which provides convenient shorthand
+for several common types of workers.  Let's look at them.
 
-source_worker.product #=> "hulk"
+But first, be sure to include the DSL mixin:
+
+```ruby
+include Stepladder::Dsl
 ```
-If you supply a worker with another worker as its supplier, then you
-can give it a task which accepts a value:
+
+### Source Worker
+
+At the headwater of every Stepladder pipeline, there is a source worker
+which is able to generate its own work items.
+
+Here is possibly the simplest of source workers, which provides the same
+string each time it is invoked:
 
 ```ruby
-relay_worker = Stepladder::Worker.new { |name| name.upcase }
-relay_worker.supplier = source_worker
+worker = source_worker { "Number 9" }
 
-relay_worker.product #=> "HULK"
+worker.product #=> "Number 9"
+worker.product #=> "Number 9"
+worker.product #=> "Number 9"
+# ...ad nauseum...
 ```
 
-You can also initialize a worker by passing in a callable object
-as its task:
+Sometimes you want a worker which generates until it doesn't:
 
 ```ruby
-capitalizer = Proc.new { |name| name.capitalize }
-relay_worker = Stepladder::Worker.new(task: capitalizer, supplier: source_worker)
+counter = 0
+worker = source_worker do
+  if counter < 3
+    counter += 1
+    counter + 1000
+  end
+end
 
-relay_worker.product #=> 'Hulk'
+worker.product #=> 1001
+worker.product #=> 1002
+worker.product #=> 1003
+worker.product #=> nil
+worker.product #=> nil (and will be nil henceforth)
 ```
 
-A worker also has an accessor for its @task:
+If all you want is a source worker which generates a series of numbers
+the DSL provides an easier way to do it:
 
 ```ruby
-doofusizer = Proc.new { |name| name.gsub(/u/, 'oo') }
-relay_worker.task = doofusizer
+w1 = source_worker [0,1,2]
+w2 = source_worker (0..2)
 
-relay_worker.product #=> 'hoolk'
+w1.product == w2.product #=> 0
+w1.product == w2.product #=> 1
+w1.product == w2.product #=> 2
+w1.product == w2.product #=> nil (and henceforth, etc.)
 ```
 
-And finally, you can provide a task by directly overriding the
-worker's #task instance method:
+### Relay Worker
+
+This is perhaps the most "normal" kind of worker in Stepladder.  It
+accepts a value and returns some transformation of that value:
 
 ```ruby
-def relay_worker.task(name)
-  name.to_sym
+squarer = relay_worker do |number|
+  number ** 2
 end
+```
+
+Of course a relay worker needs a source from which to get values upon
+which to operate:
 
-relay_worker.product #=> :hulk
+```ruby
+source = source_worker (0..3)
+
+squarer.supplier = source
 ```
 
-Even workers without a task have a task; all workers actually come
-with a default task which simply passes on the received value unchanged:
+Or, if you prefer, the DSL provides a vertical pipe for linking the
+workers together into a pipeline:
 
 ```ruby
-useless_worker = Stepladder::Worker.new(supplier: source_worker)
+pipeline = source | squarer
 
-useless_worker.product #=> 'hulk'
+pipeline.product #=> 0
+pipeline.product #=> 1
+pipeline.product #=> 4
+pipeline.product #=> 9
+pipeline.product #=> nil
 ```
 
-This turns out to be helpful in implementing filter workers, which are up next.
+### Side Worker
 
-### Workers can have filters...
+As we travel down the pipeline, from time to time, we will want to
+stop and smell the roses, or write to a log file, or drop a beat, or
+create some other kind of side-effect.  That's the purpose of the
+`side_worker`.  A side worker will pass through the same value that
+it received, but as it does so, it can perform some kind side-effect
+work.
 
-Given a source worker which provides integers 1-3:
+```
+source = source_worker (0..3)
 
-```ruby
-source = Stepladder::Worker.new do
-  (1..3).each { |number| handoff number }
+evens = []
+even_stasher = side_effect do |value|
+  if value % 2 == 0
+    evens << value
+  end
 end
+
+# re-using "squarer" from above example...
+pipeline = source | even_stasher | squarer
+
+pipeline.product #=> 0
+pipeline.product #=> 1
+pipeline.product #=> 4
+pipeline.product #=> 9
+pipeline.product #=> nil
+
+evens #=> [0, 2]
 ```
 
-...we can define a subscribing worker with a filter:
+Notice that the output is the same as the previous example, even though
+we put this `even_stasher` `side_worker` in the middle of the pipeline.
+
+However, we can also see that the `evens` array now contains the even numbers from `source` (the side effect).
+
+_But wait,_ you want to say, _can't we still create side effects with
+regular ole relay workers?_  Why, yes.  Yes you can.  Ruby being what
+it is, there really isn't a way to prevent the implementation of any
+worker from creating side effects.
+
+_And still wait,_ you'll also be wanting to say, _isn't it possible
+that a side worker could mutate the value as it's passed through?_  And
+again, yes.  It would be very difficult\* in the Ruby language (where
+so many things are passed by reference) to perfectly prevent a side
+worker from mutating the value.  But please don't.
+
+The side effect worker's purpose is to provide _intentionality_ and
+clarity.  When you're creating a side effect, let it be very clear.
+And don't do regular, pure functional style work in the same worker.
+
+This will make side effects easier to troubleshoot; if you pull them
+out of the pipeline, the pipeline's output shouldn't change.  By the
+same token, if there is a problem with a side effect, troubleshooting
+it will be much simpler if the side effects are already isolated and
+named.
+
+\* _Under consideration: a variant of the side-effect which attempts
+to prevent side-effects by doing a `Marshal.dump/load`.  But the
+potential overhead in all that marshalling makes me hesitant to make
+this the default behavior.  Making it available as an option, however,
+opens the possibility to troubleshoot side effects: if the marshalling
+eliminates an unwanted mutation, then chances are that you have a
+side effect that is doing mutation._
+
+### Filter Worker
+
+The filter worker simply passes through the values which are given
+to it, but _only_ those values which result in truthiness when your
+provided callable is run against it.  Values which result in
+falsiness are simply discarded.
 
 ```ruby
-odd_number_filter = Proc.new { |number| number % 2 > 0 }
-filter_worker = Stepladder::Worker.new filter: odd_number_filter
+source = source_worker (0..5)
+
+filter = filter_worker do |value|
+  value % 2 == 0
+end
 
-filter_worker.product #=> 1
-filter_worker.product #=> 3
-filter_worker.product #=> nil
+pipeline = source | filter
+
+pipeline.product #=> 0
+pipeline.product #=> 2
+pipeline.product #=> 4
+pipeline.product #=> nil
 ```
 
-### The pipeline DSL
+### Batch Worker
 
-You can stitch your workers together using the vertical pipe ("|") like so:
+The batch worker gathers outputs into batches and the returns each
+batch as its output.
 
 ```ruby
-pipeline = source_worker | filter_worker | relay_worker | another worker
+source = source_worker (0..7)
+
+batch = batch_worker gathering: 3
+
+pipeline = source | batch
+
+pipeline.product #=> [0, 1, 2]
+pipeline.product #=> [3, 4, 5]
+pipeline.product #=> [6, 7]
+pipeline.product #=> nil
 ```
 
-...and then just call on that pipeline (it's actually the last worker in the
-chain):
+Notice how the final batch doesn't have full compliment of three.
+
+Fixed-numbered batch workers are useful for things like pagination,
+perhaps, but sometimes we don't want a batch to include a specific
+number of items, but to batch together all items until a certain
+condition is met.  So batch worker can also accept a callable:
 
 ```ruby
-while next_value = pipeline.product do
-  do_something_with next_value
-  # etc.
+source = source_worker [
+  "some", "rain", "must\n", "fall", "but", "ok" ]
+
+line_reader = batch_worker do |value|
+  value.end_with? "\n"
 end
+
+pipeline = source | line_reader
+
+pipeline.product #=> ["some", "rain", "must\n"]
+pipeline.product #=> ["fall", "but", "ok"]
+pipeline.product #=> nil
 ```
 
 ## Origins of Stepladder
 
 Stepladder grew out of experimentation with Ruby fibers, after readings
-[Dave Thomas' demo of Ruby fibers](http://pragdave.blogs.pragprog.com/pragdave/2007/12/pipelines-using.html), wherein he created a
+[Dave Thomas' demo of Ruby fibers](http://pragdave.me/blog/2007/12/30/pipelines-using-fibers-in-ruby-19/), wherein he created a
 pipeline of fiber processes, emulating the style and syntax of the
 \*nix command line.  I noticed that, courtesy of fibers' extremely
 low surface area, fiber-to-fiber collaborators could operate with
@@ -176,50 +319,59 @@ just _common objects_ coupling-- this little remaining coupling is
 mitigated by the possibility of having coupled code _live together_.
 I call this feature the _folded collaborators_ effect.
 
-Consider the following -code- vaporware:
+Consider the following ~~code~~ vaporware:
 
 ```ruby
-ME = "joelhelbling"
+SUBJECT = 'kitteh'
 
-module Stepladder
-  tweet_getter = Worker.new do
-    twitter_api.fetch_my_tweets
-  end
+include Stepladder::Dsl
 
-  about_me_filter      = Proc.new { |tweet| tweet.referenced.include? ME }
-  just_about_me_getter = Worker.new filter: about_me_filter
+tweet_getter = source_worker do
+  twitter_api.fetch_my_tweets
+end
 
-  tweet_formatter = Worker.new do |tweet|
-    apply_format_to tweet
-  end
+about_me = filter_worker do |tweet|
+  tweet.referenced.include? SUBJECT
+end
+
+tweet_formatter = relay_worker do |tweet|
+  apply_format_to tweet
+end
+
+kitteh_tweets = tweet_getter | about_me | tweet_formatter
 
-  formatted_tweets = tweet_getter | just_about_me_getter | tweet_formatter
+while tweet = kitteh_tweets.product
+  display(tweet)
 end
 ```
 
 None of these tasks have hard coupling with each other.  If we were to
-insert another worker between the filter and the formatter, neither of those
-workers would need changes in their code, assuming the inserted worker plays
-nicely with the objects they're all passing along.
+insert another worker between the filter and the formatter, neither of
+those workers would need changes in their code, assuming the inserted
+worker plays nicely with the objects they're all passing along.
 
 Which brings me to the point: these workers to have a dependency upon the
 objects they're handing off and receiving.  But we have the capability to
 coordinate those workers in a centralized location (such as in this code
 example).
 
-## Ok, but why is it called "Stepladder"?
-
-This framework's name was inspired by a conversation with Tim Wingfield
-in which we joked about the profusion of new frameworks in the Ruby
-community.  We quickly began riffing on a fictional framework called
-"Stepladder" which all the cool kids, we asserted, were (or would soon
-be) using.
+## Stepladder::Worker
 
-I have waited a long time to make that farce a reality, but hey, I take
-joke frameworks very seriously. ;)
-([Really?](http://github.com/joelhelbling/really))
+The Stepladder::Worker documentation has been moved
+[here](docs/stepladder/worker.md).
 
 ## Roadmap
 
-- add a nicer top-layer to the DSL --no reason we should have to do
-  all that `Worker.new` stuff
+- `splitter_worker` -- would accept a value and return an array.  The
+  elements of that returned array would then be output as separate values
+  to the next worker in the pipeline.
+- `batch_worker trailing: n` -- accepts a value, and returns the last n
+  values.  This would mean that no values would be returned until n
+  values had been accumulated.  This could be useful for things like
+  rolling averages.
+- `side_worker(:hardened) { |v| do_stuff_with(v) }` -- the `:hardened`
+  flag would attempt to ensure no side effects may occur by using
+  `Marshal` to dump/load the value before handing it to the workers
+  callable.  Also might make a runtime-wide toggle which hardens all
+  side_workers, which could be useful in flushing out side workers
+  which are doing inadvertent mutation.

data/Rakefile

@@ -1,3 +1,11 @@
-require 'bundler'
+require 'rspec/core/rake_task'
 
 Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = false
+  t.pattern = 'spec/lib/**/*_spec.rb'
+  t.rspec_opts = " --format doc"
+end
+
+task default: :spec

data/docs/stepladder/worker.md

@@ -0,0 +1,103 @@
+# Stepladder::Worker
+
+_The workhorse of the Stepladder framework._
+
+## Workers have tasks...
+
+Initialize with a block of code:
+
+```ruby
+source_worker = Stepladder::Worker.new { "hulk" }
+
+source_worker.product #=> "hulk"
+```
+If you supply a worker with another worker as its supplier, then you
+can give it a task which accepts a value:
+
+```ruby
+relay_worker = Stepladder::Worker.new { |name| name.upcase }
+relay_worker.supplier = source_worker
+
+relay_worker.product #=> "HULK"
+```
+
+You can also initialize a worker by passing in a callable object
+as its task:
+
+```ruby
+capitalizer = Proc.new { |name| name.capitalize }
+relay_worker = Stepladder::Worker.new(task: capitalizer, supplier: source_worker)
+
+relay_worker.product #=> 'Hulk'
+```
+
+A worker also has an accessor for its @task:
+
+```ruby
+doofusizer = Proc.new { |name| name.gsub(/u/, 'oo') }
+relay_worker.task = doofusizer
+
+relay_worker.product #=> 'hoolk'
+```
+
+And finally, you can provide a task by directly overriding the
+worker's #task instance method:
+
+```ruby
+def relay_worker.task(name)
+  name.to_sym
+end
+
+relay_worker.product #=> :hulk
+```
+
+Even workers without a task have a task; all workers actually come
+with a default task which simply passes on the received value unchanged:
+
+```ruby
+useless_worker = Stepladder::Worker.new(supplier: source_worker)
+
+useless_worker.product #=> 'hulk'
+```
+
+This turns out to be helpful in implementing filter workers, which are up next.
+
+## Workers can have filters...
+
+Given a source worker which provides integers 1-3:
+
+```ruby
+source = Stepladder::Worker.new do
+  (1..3).each { |number| handoff number }
+end
+```
+
+...we can define a subscribing worker with a filter:
+
+```ruby
+odd_number_filter = Proc.new { |number| number % 2 > 0 }
+filter_worker = Stepladder::Worker.new filter: odd_number_filter
+
+filter_worker.product #=> 1
+filter_worker.product #=> 3
+filter_worker.product #=> nil
+```
+
+## The pipeline DSL
+
+You can stitch your workers together using the vertical pipe ("|") like so:
+
+```ruby
+pipeline = source_worker | filter_worker | relay_worker | another worker
+```
+
+...and then just call on that pipeline (it's actually the last worker in the
+chain):
+
+```ruby
+while next_value = pipeline.product do
+  do_something_with next_value
+  # etc.
+end
+```
+

data/lib/stepladder/dsl.rb

@@ -0,0 +1,137 @@
+module Stepladder
+  class WorkerInitializationError < StandardError; end
+
+  module Dsl
+    def source_worker(argument=nil, &block)
+      ensure_correct_arity_for!(argument, block)
+
+      series = series_from(argument)
+      callable = setup_callable_for(block, series)
+
+      return Worker.new(&callable) if series.nil?
+
+      Worker.new do
+        series.each(&callable)
+
+        while true do
+          handoff nil
+        end
+      end
+
+    end
+
+    def relay_worker(&block)
+      ensure_regular_arity(block)
+
+      Worker.new do |value|
+        value && block.call(value)
+      end
+    end
+
+    def side_worker(&block)
+      ensure_regular_arity(block)
+
+      Worker.new do |value|
+        value.tap do |v|
+          v && block.call(v)
+        end
+      end
+    end
+
+    def filter_worker(argument=nil, &block)
+      if (block && argument.respond_to?(:call))
+        throw_with 'You cannot supply two callables'
+      end
+      callable = argument.respond_to?(:call) ? argument : block
+
+      ensure_callable(callable)
+      Worker.new filter: block
+    end
+
+    def batch_worker(options = {gathering: 1}, &block)
+      ensure_regular_arity(block) if block
+
+      Worker.new.tap do |worker|
+        worker.instance_variable_set(:@batch_size, options[:gathering])
+        worker.instance_variable_set(:@batch_complete_block, block)
+
+        def worker.task(value)
+          if value
+            @collection = [value]
+            until batch_complete?(@collection.last)
+              @collection << supplier.product
+            end
+            @collection.compact
+          end
+        end
+
+        def worker.batch_complete?(value)
+          return true if value.nil?
+          if @batch_complete_block
+            !! @batch_complete_block.call(value)
+          else
+            @collection.size >= @batch_size
+          end
+        end
+      end
+    end
+
+    def handoff(something)
+      Fiber.yield something
+    end
+
+    private
+
+    def throw_with(*msg)
+      raise WorkerInitializationError.new([msg].flatten.join(' '))
+    end
+
+    def ensure_callable(callable)
+      unless callable && callable.respond_to?(:call)
+        throw_with 'You must supply a callable'
+      end
+    end
+
+    def ensure_regular_arity(block)
+      if block.arity != 1
+        throw_with \
+          "Worker must accept exactly one argument (arity == 1)"
+      end
+    end
+
+    # only valid for #source_worker
+    def ensure_correct_arity_for!(argument, block)
+      return unless block
+      if argument
+        ensure_regular_arity(block)
+      else
+        if block.arity > 0
+          throw_with \
+            'Source worker cannot accept any arguments (arity == 0)'
+        end
+      end
+    end
+
+    def series_from(series)
+      return if series.nil?
+      case
+      when series.respond_to?(:to_a)
+        series.to_a
+      when series.respond_to?(:scan)
+        series.scan(/./)
+      else
+        [series]
+      end
+    end
+
+    def setup_callable_for(block, series)
+      return block unless series
+      if block
+        return Proc.new { |value| handoff block.call(value) }
+      else
+        return Proc.new { |value| handoff value }
+      end
+    end
+
+  end
+end

data/lib/stepladder/version.rb

@@ -1,3 +1,3 @@
 module Stepladder
-  VERSION = "0.0.2"
+  VERSION = "0.2.0"
 end

data/lib/stepladder/worker.rb

@@ -6,20 +6,20 @@ module Stepladder
       @supplier = p[:supplier]
       @filter   = p[:filter] || default_filter
       @task     = block || p[:task]
+      # don't define default task here
+      # because we want to allow for
+      # an initialized worker to have
+      # a task injected, including
+      # method-based tasks.
     end
 
     def product
-      if ready_to_work?
-        work.resume
-      end
+      ensure_ready_to_work!
+      workflow.resume
     end
 
     def ready_to_work?
-      @task ||= default_task
-      if (task_accepts_a_value? && supplier.nil?)
-        raise "This worker's task expects to receive a value from a supplier, but has no supplier."
-      end
-      true
+      @task && (supplier || !task_accepts_a_value?)
     end
 
     def |(subscribing_worker)
@@ -29,12 +29,23 @@ module Stepladder
 
     private
 
-    def work
+    def ensure_ready_to_work!
+      @task ||= default_task
+      # at this point we will ensure a task exists
+      # because we know that the worker is being
+      # asked for product
+
+      unless ready_to_work?
+        raise "This worker's task expects to receive a value from a supplier, but has no supplier."
+      end
+    end
+
+    def workflow
       @my_little_machine ||= Fiber.new do
         loop do
           value = supplier && supplier.product
           if value.nil? || passes_filter?(value)
-            handoff @task.call(value)
+            Fiber.yield @task.call(value)
           end
         end
       end
@@ -76,7 +87,3 @@ module Stepladder
 
   end
 end
-
-def handoff(product)
-  Fiber.yield product
-end

data/lib/stepladder.rb

@@ -0,0 +1,3 @@
+require_relative 'stepladder/version'
+require_relative 'stepladder/worker'
+require_relative 'stepladder/dsl'

data/spec/lib/stepladder/dsl_spec.rb

@@ -0,0 +1,256 @@
+require 'spec_helper'
+
+module Stepladder
+  describe Dsl do
+    include Stepladder::Dsl
+
+    describe '#source_worker' do
+      context 'normal usage' do
+        context 'with an array' do
+          Given(:worker) { source_worker [:fee, :fi] }
+
+          Then { worker.product == :fee }
+          And  { worker.product == :fi }
+          And  { worker.product.nil? }
+        end
+
+        context 'with a range' do
+          Given(:worker) { source_worker (0..2) }
+
+          Then { worker.product == 0 }
+          And  { worker.product == 1 }
+          And  { worker.product == 2 }
+          And  { worker.product.nil? }
+        end
+
+        context 'with a string' do
+          Given(:worker) { source_worker 'abc' }
+
+          Then { worker.product == 'a' }
+          And  { worker.product == 'b' }
+          And  { worker.product == 'c' }
+          And  { worker.product.nil? }
+        end
+
+        context 'with a hash' do
+          Given(:worker) { source_worker({foo: 2, bar: 'yarr'}) }
+
+          Then { worker.product == [:foo, 2] }
+          And  { worker.product == [:bar, 'yarr'] }
+          And  { worker.product.nil? }
+        end
+
+        context 'with a anything else' do
+          Given(:worker) { source_worker :foo }
+
+          Then { worker.product == :foo }
+          And  { worker.product.nil? }
+        end
+
+        context 'with a callable' do
+          Given(:worker) do
+            notes = %i[doh ray me fa so la ti]
+            source_worker do
+              notes.shift if notes.size > 4
+            end
+          end
+
+          Then { worker.product == :doh }
+          And  { worker.product == :ray }
+          And  { worker.product == :me }
+          And  { worker.product.nil? }
+        end
+
+        context 'with a callable and an argument' do
+          Given(:notes) { %i[so la ti] }
+          Given(:worker) do
+            source_worker notes do |note|
+              note.to_s.upcase
+            end
+          end
+
+          Then { worker.product == 'SO' }
+          And  { worker.product == 'LA' }
+          And  { worker.product == 'TI' }
+          And  { worker.product.nil? }
+        end
+      end
+
+      context 'illegal usage' do
+        context 'with no argument and arity > 0' do
+          Given(:invocation) do
+            -> { source_worker { |v| v * 2 } }
+          end
+          Then { expect(invocation).to raise_error(/arity == 0/) }
+        end
+      end
+
+      context 'with argument' do
+        context 'and arity == 0' do
+          Given(:invocation) do
+            -> { source_worker([]) { :boo } }
+          end
+          Then { expect(invocation).to raise_error(/arity == 1/) }
+        end
+        context 'and arity > 1' do
+          Given(:invocation) do
+            -> { source_worker([]) { |p, q| :boo } }
+          end
+          Then { expect(invocation).to raise_error(/arity == 1/) }
+        end
+      end
+    end
+
+    describe '#relay_worker' do
+      context 'normal usage' do
+        Given(:source) { source_worker %w[better stronger faster] }
+        Given(:relay) do
+          relay_worker { |v| v.gsub(/t/, '+') }
+        end
+
+        When { source | relay }
+
+        Then { relay.product == 'be++er' }
+        And  { relay.product == 's+ronger' }
+        And  { relay.product == 'fas+er' }
+        And  { relay.product.nil? }
+      end
+
+      context 'illegal usage' do
+        context 'arity == 0' do
+          Given(:invocation) do
+            -> { relay_worker() { :foo } }
+          end
+
+          Then { expect(invocation).to raise_error(/arity == 1/) }
+        end
+      end
+    end
+
+    describe '#side_worker' do
+      context 'normal usage' do
+        Given(:source) { source_worker (0..2) }
+        Given(:side_effect) { [] }
+        Given(:worker) do
+          side_effect
+          side_worker { |v| side_effect << v * 2 }
+        end
+
+        When { source | worker }
+
+        Then { worker.product == 0 }
+        And  { worker.product == 1 }
+        And  { worker.product == 2 }
+        And  { worker.product.nil? }
+        And  { side_effect == [0, 2, 4] }
+      end
+
+      context 'illegal usage' do
+        context 'arity == 0' do
+          Given(:invocation) do
+            -> { side_worker() { :foo } }
+          end
+
+          Then { expect(invocation).to raise_error(/arity == 1/) }
+        end
+      end
+    end
+
+    describe '#filter_worker' do
+      context 'normal usage' do
+        Given(:source) { source_worker (1..3) }
+
+        When { source | filter }
+
+        Given(:filter) do
+           filter_worker { |v| v % 2 == 0 }
+        end
+
+        Then { filter.product == 2 }
+        And { expect(filter.product).to be_nil }
+      end
+
+      context 'illegal usage' do
+        context 'requires a callable' do
+          context 'with no arguments or block' do
+            Given(:invocation) { -> { filter_worker } }
+            Then { expect(invocation).to raise_error(/supply a callable/) }
+          end
+
+          context 'with no callable' do
+            Given(:invocation) { -> { filter_worker :foo } }
+            Then { expect(invocation).to raise_error(/supply a callable/) }
+          end
+
+          context 'with callable arg' do
+            Given(:arg) { Proc.new { true } }
+            Given(:invocation) { -> { filter_worker arg } }
+            Then { expect(invocation).to_not raise_error }
+          end
+
+          context 'with both callable arg and block' do
+            Given(:arg) { Proc.new { true } }
+            Given(:invocation) { -> { filter_worker(arg) do false; end } }
+            Then { expect(invocation).to raise_error(/two callables/) }
+          end
+        end
+      end
+    end
+
+    describe '#batch_worker' do
+      Given(:source) { source_worker (0..7) }
+
+      context 'normal usage' do
+        When { source | worker }
+
+        context 'with specified "gathering" batch size' do
+          Given(:worker) do
+            batch_worker gathering: 3
+          end
+
+          Then { worker.product == [ 0, 1, 2 ] }
+          And  { worker.product == [ 3, 4, 5 ] }
+          And  { worker.product == [ 6, 7 ] }
+          And  { worker.product.nil? }
+        end
+
+        context 'defaults to batch size of 1' do
+          Given(:source) { source_worker [8,9] }
+          Given(:worker) { batch_worker }
+
+          Then { worker.product == [ 8 ] }
+          And  { worker.product == [ 9 ] }
+          And  { worker.product.nil? }
+        end
+
+        context 'collects until condition' do
+          Given(:source) { source_worker (1..5) }
+          Given(:worker) do
+            batch_worker { |n| n % 2 == 0 }
+          end
+
+          Then { worker.product == [ 1, 2 ] }
+          And  { worker.product == [ 3, 4 ] }
+          And  { worker.product == [ 5 ] }
+          And  { worker.product.nil? }
+        end
+      end
+
+      context 'illegal usage' do
+        context 'requires a callable' do
+          context 'with arity == 0' do
+            Given(:invocation) { -> { batch_worker() { :foo } } }
+            Then { expect(invocation).to raise_error(/arity == 1/) }
+          end
+
+          context 'with arity > 1' do
+            Given(:invocation) { -> { batch_worker() { |a,b| :foo } } }
+            Then { expect(invocation).to raise_error(/arity == 1/) }
+          end
+
+        end
+      end
+    end
+
+  end
+end

data/spec/lib/stepladder/worker_spec.rb

@@ -1,9 +1,49 @@
 require 'spec_helper'
-require 'stepladder/worker'
 
 module Stepladder
   describe Worker do
-    it { should respond_to(:product, :supplier, :supplier=) }
+    it { should respond_to(:product, :supplier, :supplier=, :"|") }
+
+    describe "readiness" do
+      context "with no supplier" do
+        context "with no task" do
+          it { should_not be_ready_to_work }
+        end
+        context "with a task which accepts a value" do
+          subject do
+            Worker.new { |value| value.to_s }
+          end
+          it { should_not be_ready_to_work }
+        end
+        context "with a task which doesn't accept a value" do
+          subject do
+            Worker.new { "foo" }
+          end
+          it { should be_ready_to_work }
+        end
+      end
+
+      context "with a supplier" do
+        before do
+          subject.supplier = Worker.new { "foofoo" }
+        end
+        context "with no task" do
+          it { should_not be_ready_to_work }
+        end
+        context "with a task which accepts a value" do
+          subject do
+            Worker.new { |value| value.upcase }
+          end
+          it { should be_ready_to_work }
+        end
+        context "with a task which doesn't accept a value" do
+          subject do
+            Worker.new { "bar" }
+          end
+          it { should be_ready_to_work }
+        end
+      end
+    end
 
     describe "can accept a task" do
       let(:result) { double }
@@ -47,7 +87,7 @@ module Stepladder
             supplier.stub(:product).and_return(result)
             subject.supplier = supplier
             def subject.task(value)
-              handoff value
+              Fiber.yield value
             end
           end
           its(:product) { should be_copasetic }
@@ -74,13 +114,13 @@ module Stepladder
 
     end
 
-    describe "= WORKER TYPES =" do
+    describe "= EXAMPLE WORKER TYPES =" do
 
       let(:source_worker) do
         Worker.new do
           numbers = (1..3).to_a
-          until numbers.empty?
-            handoff numbers.shift
+          while value = numbers.shift
+            Fiber.yield value
           end
         end
       end
@@ -166,31 +206,29 @@ module Stepladder
         end
       end
 
-      describe "Also, there's a pipeline dsl:" do
-        let(:subscribing_worker) { relay_worker }
-        let(:pipeline) { source_worker | subscribing_worker }
+    end
 
-        subject { pipeline }
+    describe "#|" do
+      Given(:source_worker) { Worker.new { :foo } }
+      Given(:subscribing_worker) { Worker.new { |v| "#{v}_bar".to_sym } }
 
-        it "lets you daisy-chain workers using \"|\"" do
-          subject.inspect
-          subscribing_worker.supplier.should == source_worker
-        end
-      end
+      When(:pipeline) { source_worker | subscribing_worker }
 
+      Then { subscribing_worker.supplier == source_worker }
+      Then { pipeline.product == :foo_bar }
+      Then { pipeline == subscribing_worker }
     end
 
     describe "#product" do
-      before do
-        supplier.stub(:product).and_return(result)
-        subject.supplier = supplier
-      end
-      let(:result)   { :foo }
-      let(:supplier) { double }
+      Given(:work_product) { :whatever }
+      Given { supplier.stub(:product).and_return(work_product) }
+      Given { subject.supplier = supplier }
+      Given(:supplier) { double }
+
+      context "resumes a fiber" do
+        Given { Fiber.any_instance.should_receive(:resume).and_return(work_product) }
 
-      it "resumes a fiber" do
-        Fiber.any_instance.should_receive(:resume).and_return(result)
-        subject.product.should == result
+        Then { subject.product }
       end
     end
 

data/spec/spec_helper.rb

@@ -1 +1,16 @@
+require 'rspec/its'
+require 'rspec/given'
+require 'pry'
+
 $LOAD_PATH.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+
+require 'stepladder'
+
+RSpec.configure do |cfg|
+  cfg.expect_with :rspec do |c|
+    c.syntax = [:should, :expect]
+  end
+  cfg.mock_with :rspec do |c|
+    c.syntax = [:should, :expect]
+  end
+end

data/stepladder.gemspec

@@ -17,9 +17,9 @@ Gem::Specification.new do |s|
   s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency 'cucumber'
-  s.add_development_dependency 'rake'
-  s.add_development_dependency 'rspec'
-  s.add_development_dependency 'rspec-core'
-  s.add_development_dependency 'aruba'
+  s.add_development_dependency 'rspec',      '3.1.0'
+  s.add_development_dependency 'rspec-core', '3.1.2'
+  s.add_development_dependency 'rspec-its',  '1.0.1'
+  s.add_development_dependency 'rspec-given', '3.8.0'
+  s.add_development_dependency 'pry'
 end

metadata

@@ -1,141 +1,132 @@
 --- !ruby/object:Gem::Specification
 name: stepladder
 version: !ruby/object:Gem::Version
-  version: 0.0.2
-  prerelease: 
+  version: 0.2.0
 platform: ruby
 authors:
 - Joel Helbling
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-15 00:00:00.000000000 Z
+date: 2018-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: cucumber
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec-core
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.2
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rspec-its
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.1
 - !ruby/object:Gem::Dependency
-  name: rspec-core
+  name: rspec-given
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.8.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.8.0
 - !ruby/object:Gem::Dependency
-  name: aruba
+  name: pry
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: ! ' Stepladder grew out of experimentation with Ruby fibers, after readings
-  Dave Thomas'' demo of Ruby fibers, wherein he created a pipeline of fiber processes,
+description: " Stepladder grew out of experimentation with Ruby fibers, after readings
+  Dave Thomas' demo of Ruby fibers, wherein he created a pipeline of fiber processes,
   emulating the style and syntax of the *nix command line. I noticed that, courtesy
-  of fibers'' extremely low surface area, fiber-to-fiber collaborators could operate
-  with extremely low coupling. That was the original motivation for creating the framework. '
+  of fibers' extremely low surface area, fiber-to-fiber collaborators could operate
+  with extremely low coupling. That was the original motivation for creating the framework. "
 email:
 - joel@joelhelbling.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
+- ".travis.yml"
 - Gemfile
 - README.md
 - Rakefile
+- docs/stepladder/worker.md
+- lib/stepladder.rb
+- lib/stepladder/dsl.rb
 - lib/stepladder/version.rb
 - lib/stepladder/worker.rb
 - pkg/.gitkeep
+- spec/lib/stepladder/dsl_spec.rb
 - spec/lib/stepladder/worker_spec.rb
 - spec/spec_helper.rb
 - stepladder.gemspec
 homepage: http://github.com/joelhelbling/stepladder
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: stepladder
-rubygems_version: 1.8.24
+rubygems_version: 2.7.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A ruby-fibers-based framework aimed at extremely low coupling.
-test_files:
-- spec/lib/stepladder/worker_spec.rb
-- spec/spec_helper.rb
+test_files: []