deferrable_gratification 0.2.0 → 0.3.0

data/lib/deferrable_gratification.rb

@@ -19,6 +19,19 @@ module DeferrableGratification
   # Allow DG.const, DG.failure etc
   extend Primitives
 
+  # Exception passed to errbacks by {Combinators#guard} if the arguments to
+  # +Deferrable#succeed+ fail the supplied predicate.
+  class GuardFailed < RuntimeError
+    attr_reader :reason
+    attr_reader :args
+
+    def initialize(reason, args)
+      @reason = reason || 'guard failed'
+      @args = args
+      super("#{@args.inspect}: #{@reason}")
+    end
+  end
+
   # Bestow DG goodness upon an existing module or class.
   #
   # N.B. calling this on a module won't enhance any classes that have already

data/lib/deferrable_gratification/combinators.rb

@@ -165,6 +165,58 @@ module DeferrableGratification
     end
 
 
+    # If this Deferrable succeeds, ensure that the arguments passed to
+    # +Deferrable#succeed+ meet certain criteria (specified by passing a
+    # predicate as a block).  If they do, subsequently defined callbacks will
+    # fire as normal, receiving the same arguments; if they do not, this
+    # Deferrable will fail instead, calling its errbacks with a {GuardFailed}
+    # exception.
+    #
+    # This follows the usual Deferrable semantics of calling +Deferrable#fail+
+    # inside a callback: any callbacks defined *before* the call to {#guard}
+    # will still execute as normal, but those defined *after* the call to
+    # {#guard} will only execute if the predicate returns truthy.
+    #
+    # Multiple successive calls to {#guard} will work as expected: the
+    # predicates will be evaluated in order, stopping as soon as any of them
+    # returns falsy, and subsequent callbacks will fire only if all the
+    # predicates pass.
+    #
+    # If instead of returning a boolean, the predicate raises an exception,
+    # the Deferrable will fail, but errbacks will receive the exception raised
+    # instead of {GuardFailed}.  You could use this to indicate the reason for
+    # failure in a complex guard expression; however the same intent might be
+    # more clearly expressed by multiple guard expressions with appropriate
+    # reason messages.
+    #
+    # @param [String] reason optional description of the reason for the guard:
+    #                        specifying this will both serve as code
+    #                        documentation, and be included in the
+    #                        {GuardFailed} exception for error handling
+    #                        purposes.
+    #
+    # @yieldparam *args the arguments passed to callbacks if this Deferrable
+    #                   succeeds.
+    # @yieldreturn [Boolean] +true+ if subsequent callbacks should fire (with
+    #                        the same arguments); +false+ if instead errbacks
+    #                        should fire.
+    #
+    # @raise [ArgumentError] if called without a predicate
+    def guard(reason = nil, &block)
+      raise ArgumentError, 'must be called with a block' unless block_given?
+      callback do |*callback_args|
+        begin
+          unless block.call(*callback_args)
+            raise ::DeferrableGratification::GuardFailed.new(reason, callback_args)
+          end
+        rescue => exception
+          fail(exception)
+        end
+      end
+      self
+    end
+
+
     # Boilerplate hook to extend {ClassMethods}.
     def self.included(base)
       base.send :extend, ClassMethods

data/lib/deferrable_gratification/fluent.rb

@@ -30,5 +30,16 @@ module DeferrableGratification
       super(&block)
       self
     end
+
+    # Ensure that if this Deferrable doesn't either succeed or fail within the
+    # timeout, it will call its errback with no parameters.
+    #
+    # @return [Deferrable, Fluent] +self+
+    #
+    # @see EventMachine::Deferrable#timeout
+    def timeout(seconds)
+      super(seconds)
+      self
+    end
   end
 end

data/lib/deferrable_gratification/primitives.rb

@@ -12,20 +12,39 @@ module DeferrableGratification
   # {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.
+    # Return a Deferrable which immediately succeeds, passing 0 or more values
+    # to callbacks.
+    def success(*values)
+      blank.tap {|d| d.succeed(*values) }
+    end
+
+    # Return a Deferrable which immediately succeeds, passing a constant value
+    # to callbacks.
     def const(value)
-      blank.tap {|d| d.succeed(value) }
+      success(value)
     end
 
     # Return a Deferrable which immediately fails with an exception.
-    def failure(class_or_message, message_or_nil = nil)
+    #
+    # @overload failure(message)
+    #   Passes +RuntimeError.new(message)+ to errbacks.
+    # @overload failure(exception_class)
+    #   Passes +exception_class.new+ to errbacks.
+    # @overload failure(exception_class, message)
+    #   Passes +exception_class.new(message)+ to errbacks.
+    # @overload failure(exception)
+    #   Passes +exception+ to errbacks.
+    def failure(exception_class_or_message, message_or_nil = nil)
       blank.tap do |d|
         d.fail(
-          case class_or_message
+          case exception_class_or_message
+          when Exception
+            raise ArgumentError, "can't specify both exception and message" if message_or_nil
+            exception_class_or_message
           when Class
-            class_or_message.new(message_or_nil)
+            exception_class_or_message.new(message_or_nil)
           else
-            RuntimeError.new(class_or_message.to_s)
+            RuntimeError.new(exception_class_or_message.to_s)
           end)
       end
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: deferrable_gratification
 version: !ruby/object:Gem::Version 
-  hash: 23
-  prerelease: false
+  hash: 19
+  prerelease: 
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Sam Stokes
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-21 00:00:00 -08:00
+date: 2011-03-25 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -152,7 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.4.2
 signing_key: 
 specification_version: 3
 summary: Makes evented programming easier with composition and abstraction.