use_case 0.7.0 → 0.8.0

data/Gemfile.lock

@@ -12,7 +12,7 @@ GIT
 PATH
   remote: .
   specs:
-    use_case (0.6.0)
+    use_case (0.8.0)
 
 GEM
   remote: http://rubygems.org/

data/Readme.md

@@ -46,10 +46,12 @@ class RepositoryController < ApplicationController
   def create
     outcome = CreateRepository.new(self, current_user).execute(params)
 
-    outcome.pre_condition_failed do |condition|
-      redirect_to(login_path) and return if condition.is_a?(UserLoggedInPrecondition)
-      flash[:error] = "You're not allowed to do that"
-      redirect_to project_path
+    outcome.pre_condition_failed do |f|
+      f.when(:user_required) { redirect_to(login_path) }
+      f.otherwise do
+        flash[:error] = "You're not allowed to do that"
+        redirect_to project_path
+      end
     end
 
     outcome.failure do |model|
@@ -109,7 +111,7 @@ end
 # This is often implemented as a controller filter in many Rails apps.
 # Unfortunately that means we have to duplicate the check when exposing the use
 # case in other contexts (e.g. a stand-alone API app, console API etc).
-class UserLoggedInPrecondition
+class UserRequired
   # The constructor is only used by us and can look and do whever we want
   def initialize(user)
     @user = user
@@ -205,12 +207,79 @@ solution for input sanitation and some level of type-safety. If you provide a
 
 ## Pre-conditions
 
-A pre-condition is any object that responds to `satisfied?(params)` where
-params will either be a `Hash` or an instance of whatever you passed to
-`input_class`. The method should return `true/false`. If it raises, the outcome
-of the use case will call the `pre_condition_failed` block with the raised
-error. If it fails, the `pre_condition_failed` block will be called with the
-pre-condition instance that failed.
+A pre-condition is any object that responds to `satisfied?(params)` where params
+will either be a `Hash` or an instance of whatever you passed to `input_class`.
+The method should return `true/false`. If it raises, the outcome of the use case
+will call the `pre_condition_failed` block with the raised error. If it fails,
+the `pre_condition_failed` block will be called with a failure object wrapping
+the pre-condition instance that failed.
+
+The wrapper failure object provides three methods of interest:
+
+### `when`
+
+The when method allows you to associate a block of code with a specific
+pre-condition. The block is called with the pre-condition instance if that
+pre-condition fails. Because the pre-condition class may not be explicitly
+available in contexts where you want to use `when`, a symbolic representation is
+used.
+
+If you have the following two pre-conditions:
+
+* `UserRequired`
+* `ProjectAdminRequired`
+
+Then you can use `when(:user_required) { |condition ... }` and
+`when(:project_admin_required) { |condition ... }`. If you want control over how
+a class name is symbolized, make the class implement `symbol`, i.e.:
+
+```js
+class UserRequired
+  def self.symbol; :user_plz; end
+  def initialize(user); @user = user; end
+  def satisfied?(params); !@user.nil?; end
+end
+
+# Then:
+
+outcome = use_case.execute(params)
+
+outcome.pre_condition_failed do |f|
+  f.when(:user_plz) { |c| puts "Needs moar user" }
+  # ...
+end
+```
+
+### `otherwise`
+
+`otherwise` is a catch-all that is called if no calls to `when` mention the
+offending pre-condition:
+
+
+```js
+class CreateProject
+  include UseCase
+
+  def initialize(user)
+    add_pre_condition(UserRequired.new(user))
+    add_pre_condition(AdminRequired.new(user))
+    step(CreateProjectCommand.new(user))
+  end
+end
+
+# Then:
+
+outcome = CreateProject.new(current_user).execute(params)
+
+outcome.pre_condition_failed do |f|
+  f.when(:user_required) { |c| puts "Needs moar user" }
+  f.otherwise { |c| puts "#{c.name} pre-condition failed" }
+end
+```
+### `pre_condition`
+
+If you want to roll your own flow control, simply get the offending
+pre-condition from this method.
 
 ## Validations
 

data/lib/use_case/outcome.rb

@@ -63,12 +63,13 @@ module UseCase
     def initialize(use_case = nil, pre_condition = nil)
       super(use_case)
       @pre_condition = pre_condition
+      @failure = PreConditionFailure.new(@pre_condition)
     end
 
     def pre_condition_failed?; true; end
 
     def pre_condition_failed
-      yield @pre_condition if block_given?
+      yield @failure if block_given?
       @pre_condition
     end
 
@@ -77,6 +78,31 @@ module UseCase
     end
   end
 
+  class PreConditionFailure
+    attr_reader :pre_condition
+    def initialize(pre_condition); @pre_condition = pre_condition; end
+
+    def when(symbol, &block)
+      raise Exception.new("Cannot call when after otherwise") if @otherwise
+      if symbol == class_symbol
+        @called = true
+        yield(@pre_condition)
+      end
+    end
+
+    def otherwise(&block)
+      @otherwise = true
+      yield(@pre_condition) if !@called
+    end
+
+    private
+    def class_symbol
+      klass = @pre_condition.class
+      return klass.symbol if klass.respond_to?(:symbol)
+      klass.name.gsub(/([^A-Z])([A-Z])/, '\1_\2').gsub(/[:_]+/, "_").downcase.to_sym
+    end
+  end
+
   class FailedOutcome < Outcome
     def initialize(use_case = nil, errors = nil)
       super(use_case)

data/lib/use_case/version.rb

@@ -24,5 +24,5 @@
 #++
 
 module UseCase
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/test/use_case/outcome_test.rb

@@ -25,6 +25,10 @@
 require "test_helper"
 require "use_case/outcome"
 
+class MyPreCondition
+  def self.symbol; :something; end
+end
+
 describe UseCase::Outcome do
   it "exposes use case" do
     use_case = 42
@@ -93,19 +97,75 @@ describe UseCase::Outcome do
       refute outcome.success?
     end
 
-    it "yields and returns failed pre-condition" do
+    it "returns failed pre-condition" do
       pre_condition = 42
-      yielded_pc = nil
       outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
-      returned_pc = outcome.pre_condition_failed { |pc| yielded_pc = pc }
+      returned_pc = outcome.pre_condition_failed
 
-      assert_equal pre_condition, yielded_pc
       assert_equal pre_condition, returned_pc
     end
 
-    it "gets pre_condition without block" do
-      outcome = UseCase::PreConditionFailed.new(nil, 42)
-      assert_equal 42, outcome.pre_condition_failed
+    describe "yielded wrapper" do
+      it "has flow control API" do
+        yielded = false
+        pre_condition = Array.new
+        outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
+
+        returned_pc = outcome.pre_condition_failed do |f|
+          f.when(:array) { |pc| yielded = pc }
+        end
+
+        assert_equal yielded, pre_condition
+      end
+
+      it "does not call non-matching block" do
+        yielded = nil
+        pre_condition = Array.new
+        outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
+
+        returned_pc = outcome.pre_condition_failed do |f|
+          f.when(:something) { |pc| yielded = pc }
+        end
+
+        assert_nil yielded
+      end
+
+      it "matches by class symbol" do
+        yielded = false
+        pre_condition = MyPreCondition.new
+        outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
+
+        returned_pc = outcome.pre_condition_failed do |f|
+          f.when(:something) { |pc| yielded = pc }
+        end
+
+        assert_equal yielded, pre_condition
+      end
+
+      it "yields to otherwise if no match" do
+        yielded = false
+        pre_condition = MyPreCondition.new
+        outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
+
+        returned_pc = outcome.pre_condition_failed do |f|
+          f.when(:nothing) { |pc| yielded = 42 }
+          f.otherwise { |pc| yielded = pc }
+        end
+
+        assert_equal yielded, pre_condition
+      end
+
+      it "raises if calling when after otherwise" do
+        pre_condition = MyPreCondition.new
+        outcome = UseCase::PreConditionFailed.new(nil, pre_condition)
+
+        assert_raises(Exception) do
+          returned_pc = outcome.pre_condition_failed do |f|
+            f.otherwise { |pc| yielded = pc }
+            f.when(:nothing) { |pc| yielded = 42 }
+          end
+        end
+      end
     end
   end
 

data/test/use_case_test.rb

@@ -35,8 +35,8 @@ describe UseCase do
   it "fails first pre-condition; no user logged in" do
     outcome = CreateRepository.new(nil).execute({})
 
-    outcome.pre_condition_failed do |pc|
-      assert_equal UserLoggedInPrecondition, pc.class
+    outcome.pre_condition_failed do |f|
+      assert_equal UserLoggedInPrecondition, f.pre_condition.class
     end
   end
 
@@ -44,8 +44,8 @@ describe UseCase do
     @logged_in_user.can_admin = false
     outcome = CreateRepository.new(@logged_in_user).execute({})
 
-    outcome.pre_condition_failed do |pc|
-      assert_equal ProjectAdminPrecondition, pc.class
+    outcome.pre_condition_failed do |f|
+      assert_equal ProjectAdminPrecondition, f.pre_condition.class
     end
   end
 
@@ -53,8 +53,8 @@ describe UseCase do
     def @logged_in_user.id; raise "Oops!"; end
     outcome = CreateRepository.new(@logged_in_user).execute({})
 
-    outcome.pre_condition_failed do |pc|
-      assert_equal RuntimeError, pc.class
+    outcome.pre_condition_failed do |f|
+      assert_equal RuntimeError, f.pre_condition.class
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: use_case
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-05 00:00:00.000000000 Z
+date: 2013-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest