use_case 0.1.0 → 0.2.0

data/Readme.md

@@ -11,65 +11,84 @@ Compose non-trivial business logic into use cases, that combine:
   different contexts etc.
 * Commands: Avoid defensive coding by performing the core actions in commands
   that receive type-converted input, and are only executed when pre-conditions
-  are met and input validated.
+  are met and input is validated.
 
 ## Example
 
-At its very simplest, a use case wraps a command. A command is any Ruby object
-with an `execute` method that receives one argument (input parameters). Because
-UseCase is intended as a mechanism for implementing non-trivial use cases, the
-following contrived example will seem particularly useless.
+`UseCase` is designed to break up and keep non-trivial workflows understandable
+and decoupled. As such, a trivial example would not illustrate what is good
+about it. The following example is simplified, yet still has enough aspects to
+show how `UseCase` helps you break things up.
+
+Pre-conditions are conditions not directly related to input parameters alone,
+and whose failure signifies other forms of errors than simple validation errors.
+If you have a Rails application that uses controller filters, then those are
+very likely good candidates for pre-conditions.
+
+The following example is a simplified use case from
+[Gitorious](http://gitorious.org) where we want to create a new repository. To
+do this, we need a user that can admin the project under which we want the new
+repository to live.
+
+This example illustrates how to solve common design challenges in Rails
+applications; that does not mean that `UseCase` is only useful to Rails
+applications.
+
+First, let's look at what your Rails controller will look like using a
+`UseCase`:
 
 ```rb
-require "use_case"
+class RepositoryController < ApplicationController
+  include Gitorious::Authorization # Adds stuff like can_admin?(actor, thing)
 
-class HelloWorldCommand
-  def execute(params)
-    puts "Hello, #{params[:place]}!"
-  end
-end
+  # ...
 
-class PrintHelloWorld
-  include UseCase
+  def create
+    outcome = CreateRepository.new(self, current_user).execute(params)
 
-  def initialize
-    command(HelloWorldCommand.new)
+    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
+    end
+
+    outcome.failure do |model|
+      # Render form with validation errors
+      render :new, :locals => { :repository => model }
+    end
+
+    outcome.success do |repository|
+      redirect_to(repository_path(repository))
+    end
   end
 end
-
-# Usage
-PrintHelloWorld.new.execute(:place => "World")
 ```
 
-Not that you are free to design your constructors any way you want.
+Executing the use case in an `irb` session could look like this:
 
-## Useful example
-
-A more useful example will use every aspect of a `UseCase`. Pre-conditions are
-conditions not directly related to input parameters, and whose failure signifies
-other forms of errors than simple validation errors. If you have a Rails
-application that uses controller filters, then those are very likely good
-candidates for pre-conditions.
-
-The following example is a simplified use case from
-[Gitorious](http://gitorious.org) where we want to create a new repository. To
-do this, we need a user that can admin the project under which we want the new
-repository to live.
+```rb
+include Gitorious::Authorization
+user = User.find_by_login("christian")
+project = Project.find_by_name("gitorious")
+outcome = CreateRepository.new(self, user).execute(:project => project,
+                                                   :name => "use_case")
+outcome.success? #=> true
+outcome.result.name #=> "use_case"
+```
 
-This example illustrates how to solve common design challenges in Rails
-applications, but that does not mean that `UseCase` is only useful to Rails
-applications.
+The code behind this use case follows:
 
 ```rb
 require "use_case"
 require "virtus"
 
-# Input parameters can be sanitized and pre-processed anyway you like. One nice
+# Input parameters can be sanitized and pre-processed any way you like. One nice
 # way to go about it is to use Datamapper 2's Virtus gem to define a parameter
 # set.
 #
 # This class uses Project.find to look up a project by id if project_id is
-# provided and project is not. This is the only class that has
+# provided and project is not. This is the only class that directly touches
+# classes from the Rails application.
 class NewRepositoryInput
   include Virtus
   attribute :name, String
@@ -143,32 +162,6 @@ class CreateRepository
     command(CreateRepositoryCommand.new(user))
   end
 end
-
-# Finally, the actual usage. This example is a Rails controller
-class RepositoryController < ApplicationController
-  include Gitorious::Authorization # Adds stuff like can_admin?(actor, thing)
-
-  # ...
-
-  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
-    end
-
-    outcome.failure do |model|
-      # Render form with validation errors
-      render :new, :locals => { :repository => model }
-    end
-
-    outcome.success do |repository|
-      redirect_to(repository_path(repository))
-    end
-  end
-end
 ```
 
 ## Input sanitation
@@ -269,6 +262,27 @@ work by the "data in, data out" principle, meaning you can easily test them with
 any kind of object (which spares you of loading heavy ActiveRecord-bound models,
 running opaque controller tets etc).
 
+## Installation
+
+    $ gem install use_case
+
+## Developing
+
+    $ bundle install
+    $ rake
+
+## Contributing
+
+* Clone repo
+* Make changes
+* Add test(s)
+* Run tests
+* If adding new abilities, add docs in Readme, or commit a working example
+* Send patch, [pull request](http://github.com/cjohansen/use_case) or [merge request](http://gitorious.org/gitorious/use_case)
+
+If you intend to add entirely new features, you might want to open an issue to
+discuss it with me first.
+
 ## License
 
 UseCase is free software licensed under the MIT license.

data/lib/use_case/outcome.rb

@@ -34,6 +34,7 @@ module UseCase
     def pre_condition_failed?; false; end
     def success?; false; end
     def success; end
+    def result; end
     def pre_condition_failed; end
     def failure; end
   end
@@ -51,6 +52,8 @@ module UseCase
       @result
     end
 
+    def result; @result; end
+
     def to_s
       "#<UseCase::SuccessfulOutcome: #{@result}>"
     end

data/lib/use_case/validator.rb

@@ -45,7 +45,7 @@ module UseCase
         end
       end
 
-      klass.instance_eval(&block)
+      klass.class_eval(&block)
       klass
     end
   end

data/lib/use_case/version.rb

@@ -24,5 +24,5 @@
 #++
 
 module UseCase
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/test/use_case/validator_test.rb

@@ -29,6 +29,14 @@ NewPersonValidator = UseCase::Validator.define do
   validates_presence_of :name
 end
 
+CustomValidator = UseCase::Validator.define do
+  validate :validate_custom
+
+  def validate_custom
+    errors.add(:name, "is not Dude") if name != "Dude"
+  end
+end
+
 class Person
   attr_accessor :name
 end
@@ -48,4 +56,19 @@ describe UseCase::Validator do
     refute result.valid?
     assert_equal 1, result.errors.count
   end
+
+  it "supports custom validators" do
+    result = CustomValidator.call(Person.new)
+
+    refute result.valid?
+    assert_equal 1, result.errors.count
+  end
+
+  it "passes custom validator" do
+    person = Person.new
+    person.name = "Dude"
+    result = CustomValidator.call(person)
+
+    assert result.valid?
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: use_case
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-26 00:00:00.000000000 Z
+date: 2013-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest