deferrable_gratification 0.1.0

data/LICENSE.MIT

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

data/README.markdown

@@ -0,0 +1,64 @@
+# Deferrable Gratification #
+
+## Purpose ##
+
+Deferrable Gratification (DG) makes evented code less error-prone and easier to
+compose, and thus easier to create higher-level abstractions around.  It also
+enhances the API offered by Ruby Deferrables to make them more pleasant to work
+with.
+
+## Documentation ##
+
+* [API](http://samstokes.github.com/deferrable_gratification/doc/frames.html)
+* [Behaviour specs](http://samstokes.github.com/deferrable_gratification/doc/spec/index.html)
+  (generated from RSpec code examples)
+
+## Components ##
+
+It currently consists of the following components:
+
+ * [`DG::Fluent`](#fluent): fluent (aka chainable) syntax for registering
+   multiple callbacks and errbacks to the same Deferrable.
+
+ * [`DG::Bothback`](#bothback): a `#bothback` method for registering code to
+   run on either success or failure.
+
+ * [`DG::Combinators`](#combinators): a combinator library for building up
+   complex asynchronous operations out of simpler ones.
+
+
+<h3 id="fluent"><tt>DG::Fluent</tt></h3>
+
+Use JQuery-style fluent syntax for registering several callbacks and
+errbacks on the same Deferrable.  e.g.
+
+     DeferrableMonkeyShaver.new(monkey).
+       callback { puts "Monkey is shaved" }.
+       callback { monkey.entertain! }.
+       errback {|e| puts "Unable to shave monkey! #{e}" }.
+       errback {|_| monkey.terminate! }.
+       shave
+
+<h3 id="bothback"><tt>DG::Bothback</tt></h3>
+
+Register code to run on either success or failure: shorthand for calling both
+`#callback` and `#errback` with the same code block.
+
+<h3 id="combinators"><tt>DG::Combinators</tt></h3>
+
+Allows building up higher-level asynchronous abstractions by composing simpler
+asynchronous operations, without having to manually wire callbacks together
+and remember to propagate errors correctly.
+
+Motivating example: assume we have an asynchronous database API `DB.query`
+which returns a Deferrable to communicate when the query finishes.  (See
+the [API docs for `DG::Combinators`](DeferrableGratification/Combinators.html)
+for more detail.)
+
+    def product_names_for_username(username)
+      DB.query('SELECT id FROM users WHERE username = ?', username).bind! do |user_id|
+        DB.query('SELECT name FROM products WHERE user_id = ?', user_id)
+      end.map do |product_names|
+        product_names.join(', ')
+      end
+    end

data/lib/deferrable_gratification.rb

@@ -0,0 +1,59 @@
+require File.join(File.dirname(__FILE__), *%w[deferrable_gratification bothback])
+require File.join(File.dirname(__FILE__), *%w[deferrable_gratification combinators])
+require File.join(File.dirname(__FILE__), *%w[deferrable_gratification default_deferrable])
+require File.join(File.dirname(__FILE__), *%w[deferrable_gratification fluent])
+require File.join(File.dirname(__FILE__), *%w[deferrable_gratification primitives])
+
+# Deferrable Gratification ({DG}) makes evented code less error-prone and
+# easier to compose, and thus easier to create higher-level abstractions
+# around.  It also enhances the API offered by Ruby Deferrables to make them
+# more pleasant to work with.
+#
+# @see Fluent
+# @see Bothback
+# @see Combinators
+module DeferrableGratification
+  # Allow DG.lift, DG.chain etc
+  extend Combinators::ClassMethods
+
+  # Allow DG.const, DG.failure etc
+  extend Primitives
+
+  # Bestow DG goodness upon an existing module or class.
+  #
+  # N.B. calling this on a module won't enhance any classes that have already
+  # included that module.
+  def self.enhance!(module_or_class)
+    module_or_class.send :include, Combinators
+    module_or_class.send :include, Fluent
+    module_or_class.send :include, Bothback
+  end
+
+  # Enhance EventMachine::Deferrable itself so that any class including it
+  # gets DG goodness.  This should mean that all Deferrables in the current
+  # process will get enhanced.
+  #
+  # N.B. this will not enhance any classes that have *already* included
+  # Deferrable before this method was called, so you should call this before
+  # loading any other Deferrable libraries, and before defining any of your
+  # own Deferrable classes.  (If that isn't possible, you can always call
+  # {enhance!} on them after definition.)
+  def self.enhance_all_deferrables!
+    require 'eventmachine'
+    require 'em/deferrable'
+
+    enhance! EventMachine::Deferrable
+
+    # Also have to do that to EM::DefaultDeferrable because it included
+    # Deferrable before we enhanced it.
+    enhance! EventMachine::DefaultDeferrable
+  end
+
+  # Make sure the combinator implementations themselves are enhanced.  Have to
+  # do this here, rather than just including the modules in DefaultDeferrable,
+  # to avoid a nasty circular dependencies with default_deferrable.rb.
+  enhance! DefaultDeferrable
+end
+
+# Shorthand
+DG = DeferrableGratification

data/lib/deferrable_gratification/bothback.rb

@@ -0,0 +1,18 @@
+module DeferrableGratification
+  # Allows registering a 'bothback' that will be fired on either success or
+  # failure, analogous to the +ensure+ clause of a +begin+/+rescue+ block.
+  #
+  # Include this into a class that has already included +Deferrable+.
+  module Bothback
+    # Register +block+ to be called on either success or failure.
+    # This is just a shorthand for registering the same +block+ as both a
+    # callback and an errback.
+    #
+    # @return [Deferrable, Bothback] +self+
+    def bothback(&block)
+      callback(&block)
+      errback(&block)
+      self
+    end
+  end
+end

data/lib/deferrable_gratification/combinators.rb

@@ -0,0 +1,172 @@
+Dir.glob(File.join(File.dirname(__FILE__), *%w[combinators *.rb])) do |file|
+  require file.sub(/\.rb$/, '')
+end
+
+module DeferrableGratification
+  # Combinators for building up higher-level asynchronous abstractions by
+  # composing simpler asynchronous operations, without having to manually wire
+  # callbacks together and remember to propagate errors correctly.
+  #
+  # @example Perform a sequence of database queries and transform the result.
+  #   # With DG::Combinators:
+  #   def product_names_for_username(username)
+  #     DB.query('SELECT id FROM users WHERE username = ?', username).bind! do |user_id|
+  #       DB.query('SELECT name FROM products WHERE user_id = ?', user_id)
+  #     end.map do |product_names|
+  #       product_names.join(', ')
+  #     end
+  #   end
+  #
+  #   status = product_names_for_username('bob')
+  #
+  #   status.callback {|product_names| ... }
+  #   # If both queries complete successfully, the callback receives the string
+  #   # "Car, Spoon, Coffee".  The caller doesn't have to know that two separate
+  #   # queries were made, or that the query result needed transforming into the
+  #   # desired format: he just gets the event he cares about.
+  #
+  #   status.errback {|error| puts "Oh no!  #{error}" }
+  #   # If either query went wrong, the errback receives the error that occurred.
+  #
+  #
+  #   # Without DG::Combinators:
+  #   def product_names_for_username(username)
+  #     product_names_status = EM::DefaultDeferrable.new
+  #     query1_status = DB.query('SELECT id FROM users WHERE username = ?', username)
+  #     query1_status.callback do |user_id|
+  #       query2_status = DB.query('SELECT name FROM products WHERE user_id = ?', user_id)
+  #       query2_status.callback do |product_names|
+  #         product_names = product_names.join(', ')
+  #         # N.B. don't forget to report success to the caller!
+  #         product_names_status.succeed(product_names)
+  #       end
+  #       query2_status.errback do |error|
+  #         # N.B. don't forget to tell the caller we failed!
+  #         product_names_status.fail(error)
+  #       end
+  #     end
+  #     query1_status.errback do |error|
+  #       # N.B. don't forget to tell the caller we failed!
+  #       product_names_status.fail(error)
+  #     end
+  #     # oh yes, and don't forget to return this!
+  #     product_names_status
+  #   end
+
+  module Combinators
+    # Alias for {#bind!}.
+    #
+    # Note that this takes a +Proc+ (e.g. a lambda) while {#bind!} takes a
+    # block.
+    #
+    # @param [Proc] prok proc to call with the successful result of +self+.
+    #   Assumed to return a Deferrable representing the status of its own
+    #   operation.
+    #
+    # @return [Deferrable] status of the compound operation of passing the
+    #     result of +self+ into the proc.
+    #
+    # @example Perform a database query that depends on the result of a previous query.
+    #   DB.query('first query') >> lambda {|result| DB.query("query with #{result}") }
+    def >>(prok)
+      Bind.setup!(self, &prok)
+    end
+
+    # Register callbacks so that when this Deferrable succeeds, its result
+    # will be passed to the block, which is assumed to return another
+    # Deferrable representing the status of a second operation.
+    #
+    # If this operation fails, the block will not be run.  If either operation
+    # fails, the compound Deferrable returned will fire its errbacks, meaning
+    # callers don't have to know about the inner operations and can just
+    # subscribe to the result of {#bind!}.
+    #
+    #
+    # If you find yourself writing lots of nested {#bind!} calls, you can
+    # equivalently rewrite them as a chain and remove the nesting: e.g.
+    #
+    #     a.bind! do |x|
+    #       b(x).bind! do |y|
+    #         c(y).bind! do |z|
+    #           d(z)
+    #         end
+    #       end
+    #     end
+    #
+    # has the same behaviour as
+    #
+    #     a.bind! do |x|
+    #       b(x)
+    #     end.bind! do |y|
+    #       c(y)
+    #     end.bind! do |z|
+    #       d(y)
+    #     end
+    #
+    # As well as being more readable due to avoiding left margin inflation,
+    # this prevents introducing bugs due to inadvertent local variable capture
+    # by the nested blocks.
+    #
+    #
+    # @see #>>
+    #
+    # @param &block block to call with the successful result of +self+.
+    #   Assumed to return a Deferrable representing the status of its own
+    #   operation.
+    #
+    # @return [Deferrable] status of the compound operation of passing the
+    #     result of +self+ into the block.
+    #
+    # @example Perform a web request based on the result of a database query.
+    #   DB.query('url').bind! {|url| HTTP.get(url) }.
+    #     callback {|response| puts "Got response!" }
+    def bind!(&block)
+      Bind.setup!(self, &block)
+    end
+
+    # Transform the result of this Deferrable by invoking +block+, returning
+    # a Deferrable which succeeds with the transformed result.
+    #
+    # If this operation fails, the operation will not be run, and the returned
+    # Deferrable will also fail.
+    #
+    # @param &block block that transforms the expected result of this
+    # operation in some way.
+    #
+    # @return [Deferrable] Deferrable that will succeed if this operation did,
+    #   after transforming its result.
+    #
+    # @example Retrieve a web page and call back with its title.
+    #   HTTP.request(url).map {|page| Hpricot(page).at(:title).inner_html }
+    def map(&block)
+      bind!(&block)
+    end
+
+
+    # Boilerplate hook to extend {ClassMethods}.
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+    # Combinators which don't make sense as methods on +Deferrable+.
+    #
+    # {DeferrableGratification} extends this module, and thus the methods
+    # here are accessible via the {DG} alias.
+    module ClassMethods
+      # Execute a sequence of asynchronous operations that may each depend on
+      # the result of the previous operation.
+      #
+      # @see #bind! more detail on the semantics.
+      #
+      # @param [*Proc] *actions procs that will perform an operation and
+      #   return a Deferrable.
+      #
+      # @return [Deferrable] Deferrable that will succeed if all of the
+      #   chained operations succeeded, and callback with the result of the
+      #   last operation.
+      def chain(*actions)
+        actions.inject(DG.const(nil), &:>>)
+      end
+    end
+  end
+end

data/lib/deferrable_gratification/combinators/bind.rb

@@ -0,0 +1,94 @@
+require File.join(File.dirname(__FILE__), *%w[.. default_deferrable])
+
+module DeferrableGratification
+  module Combinators
+    # Combinator that passes the result of one deferred operation to a block
+    # that uses that result to begin another deferred operation.  The compound
+    # operation itself succeeds if the second operation does.
+    #
+    # You probably want to call {#bind!} rather than using this class directly.
+    #
+    # If we define +Deferrable err (IO a)+ to be the type of a Deferrable that
+    # may perform a side effect and then either succeed with a value of type a
+    # or fail with an error of type err, then we expect the block to have type
+    #
+    #     a -> Deferrable err (IO b)
+    #
+    # and if so this combinator (actually {Bind.setup!}) is a specialisation
+    # of the monadic bind operator +>>=+:
+    #
+    #     # example: database query that depends on the result of another
+    #     Bind.setup!(DB.query('select foo from bar')) do |result|
+    #       DB.query("select baz from quuz where name = '#{result}'")
+    #     end
+    #
+    #     # type signatures, in pseudo-Haskell
+    #     (>>=) :: Deferrable err a ->
+    #                  (a -> Deferrable err b) -> Deferrable err b
+    #     Bind :: Deferrable err a ->
+    #                  (a -> Deferrable err (IO b)) -> Deferrable err (IO b)
+    #
+    # However, because Ruby doesn't actually type-check blocks, we can't
+    # enforce that the block really does return a second Deferrable.  This
+    # therefore also supports (reasonably) arbitrary blocks.  However, it's
+    # probably clearer (though equivalent) to use {#map} for this case.
+    class Bind < DefaultDeferrable
+      # Prepare to bind +block+ to +first+, and create the Deferrable that
+      # will represent the bind.
+      #
+      # Does not actually set up any callbacks or errbacks: call {#setup!} for
+      # that.
+      #
+      # @param [Deferrable] first  operation to bind to.
+      # @param &block  block to run on success; should return a Deferrable.
+      #
+      # @raise [ArgumentError] if called without a block.
+      def initialize(first, &block)
+        @first = first
+
+        raise ArgumentError, 'must pass a block' unless block
+        @proc = block
+      end
+
+      # Register a callback on the first Deferrable to run the bound block on
+      # success, and an errback to fail this {Bind} on failure.
+      def setup!
+        @first.callback {|*args| run_bound_proc(*args) }
+        @first.errback {|*args| self.fail(*args) }
+      end
+
+      # Create a {Bind} and register the callbacks.
+      #
+      # @param (see #initialize)
+      #
+      # @return [Bind] Deferrable representing the compound operation.
+      #
+      # @raise (see #initialize)
+      def self.setup!(first, &block)
+        new(first, &block).tap(&:setup!)
+      end
+
+      private
+      def run_bound_proc(*args)
+        begin
+          second = @proc.call(*args)
+        rescue => error
+          self.fail(error)
+        else
+          # We expect the block to return a Deferrable, on which we can set
+          # callbacks.  However, as referred to in the class comment above, we
+          # can't assume that it will, and need to behave sensibly if it
+          # doesn't.
+          if second.respond_to?(:callback) && second.respond_to?(:errback)
+            second.callback {|*args2| self.succeed(*args2) }
+            second.errback {|*error| self.fail(*error) }
+          else
+            # Not a Deferrable, so we need to "behave sensibly" as alluded to
+            # above.  Just behaving like #map is sensible enough.
+            self.succeed(second)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/deferrable_gratification/default_deferrable.rb

@@ -0,0 +1,17 @@
+require 'eventmachine'
+require 'em/deferrable'
+
+module DeferrableGratification
+  # Barebones Deferrable that includes the {DeferrableGratification}
+  # extensions:
+  #
+  # @see Fluent
+  # @see Bothback
+  # @see Combinators
+  class DefaultDeferrable
+    include EventMachine::Deferrable
+
+    # want to include Combinators here, but that would introduce a circular
+    # dependency, so have to do that in the top-level .rb file.
+  end
+end

data/lib/deferrable_gratification/fluent.rb

@@ -0,0 +1,34 @@
+module DeferrableGratification
+  # Allows JQuery-style fluent syntax for registering several callbacks and
+  # errbacks on the same Deferrable.  e.g.
+  #
+  #     DeferrableMonkeyShaver.new(monkey).
+  #       callback { puts "Monkey is shaved" }.
+  #       callback { monkey.entertain! }.
+  #       errback {|e| puts "Unable to shave monkey! #{e}" }.
+  #       errback {|_| monkey.terminate! }.
+  #       shave
+  #
+  # Include this into a class that has already included +Deferrable+.
+  module Fluent
+    # Register +block+ to be called on success.
+    #
+    # @return [Deferrable, Fluent] +self+
+    #
+    # @see EventMachine::Deferrable#callback
+    def callback(&block)
+      super(&block)
+      self
+    end
+
+    # Register +block+ to be called on failure.
+    #
+    # @return [Deferrable, Fluent] +self+
+    #
+    # @see EventMachine::Deferrable#errback
+    def errback(&block)
+      super(&block)
+      self
+    end
+  end
+end

data/lib/deferrable_gratification/primitives.rb

@@ -0,0 +1,38 @@
+Dir.glob(File.join(File.dirname(__FILE__), *%w[primitives *.rb])) do |file|
+  require file.sub(/\.rb$/, '')
+end
+
+module DeferrableGratification
+  # Trivial operations which return Deferrables.
+  #
+  # Used internally by the library, and may be useful in cases where you need
+  # to return a Deferrable to keep API compatibility but the result is already
+  # available.
+  #
+  # {DeferrableGratification} extends this module, and thus the methods here
+  # are accessible via the {DG} alias.
+  module Primitives
+    # Return a Deferrable which immediately succeeds with a constant value.
+    def const(value)
+      blank.tap {|d| d.succeed(value) }
+    end
+
+    # Return a Deferrable which immediately fails with an exception.
+    def failure(class_or_message, message_or_nil = nil)
+      blank.tap do |d|
+        d.fail(
+          case class_or_message
+          when Class
+            class_or_message.new(message_or_nil)
+          else
+            RuntimeError.new(class_or_message.to_s)
+          end)
+      end
+    end
+
+    # Return a completely uninteresting Deferrable.
+    def blank
+      DeferrableGratification::DefaultDeferrable.new
+    end
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification 
+name: deferrable_gratification
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Sam Stokes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-15 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 3
+        - 0
+        version: 2.3.0
+  type: :development
+  version_requirements: *id005
+description: |
+  Deferrable Gratification (DG) makes evented code less error-prone and easier to compose, and thus easier to create higher-level abstractions around.  It also enhances the API offered by Ruby Deferrables to make them more pleasant to work with.
+  
+  Currently consists of the following components:
+  
+   * fluent (aka chainable) syntax for registering multiple callbacks and errbacks to the same Deferrable.
+  
+   * a #bothback method for registering code to run on either success or failure.
+   
+   * a combinator library for building up complex asynchronous operations out of simpler ones.
+
+email: 
+- sam@rapportive.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/deferrable_gratification.rb
+- lib/deferrable_gratification/default_deferrable.rb
+- lib/deferrable_gratification/combinators/bind.rb
+- lib/deferrable_gratification/combinators.rb
+- lib/deferrable_gratification/bothback.rb
+- lib/deferrable_gratification/fluent.rb
+- lib/deferrable_gratification/primitives.rb
+- LICENSE.MIT
+- README.markdown
+has_rdoc: true
+homepage: http://github.com/samstokes/deferrable_gratification
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Makes evented programming easier with composition and abstraction.
+test_files: []
+