pay_dirt 1.0.7 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 80daedc2e23621dd1692c5092c9cce375baf07a3
-  data.tar.gz: 6db425bb6a5785adb71396cfa42ef26fdc29ecf0
+  metadata.gz: deb62d56966b35151bb79ca90be9ef8782668bb7
+  data.tar.gz: daec7ce9dc30b8c260de4e0eabac949c92e24401
 SHA512:
-  metadata.gz: 6d5956acf790c96f0086e66b0312cbfe4037e421ff3f902a23386f937fe265f458738c299c8d0fd183efd942e860a2cc305cbf25bbf0f8d749806f95c05b6277
-  data.tar.gz: 6cb08a75659b00259a7b273d6c0107c9f30a669817710fb97c2814984788cacb9065e4c4b000fa70622039eea600d7d6aaf20334197254123b687d7e8bda1183
+  metadata.gz: 55677cf4e2a832677f672c8b9e332a2f40ca3df46c1c517bbc0cef4365f5c90b4726da53b4cd4f48a556f3e83596860d98c08f9db4ca377ffbef765c8292f43a
+  data.tar.gz: b422b2fbf53018bd23d471cfebb351645d845459fe1298d225ea4ee643ed6f184c1c7e71dfbfbc92b5e1cd4dae57bc8bf058a3ab0cf90c7400e80e848147803c

data/.travis.yml

@@ -8,8 +8,7 @@ rvm:
   - 2.0.0
   - 1.9.3
   - 1.9.2
-  - jruby-19mode
+  - jruby
   - ruby-head
-  - jruby-head
 
 script: bundle exec rake test

data/README.md

@@ -1,9 +1,33 @@
 ## pay_dirt [![Gem Version](https://badge.fury.io/rb/pay_dirt.png)](http://badge.fury.io/rb/pay_dirt) [![Build Status](https://travis-ci.org/rthbound/pay_dirt.png?branch=master)](https://travis-ci.org/rthbound/pay_dirt) [![Coverage Status](https://coveralls.io/repos/rthbound/pay_dirt/badge.png?branch=master)](https://coveralls.io/r/rthbound/pay_dirt?branch=master) [![Code Climate](https://codeclimate.com/github/rthbound/pay_dirt.png)](https://codeclimate.com/github/rthbound/pay_dirt)
 
-#### A Ruby gem based on the "use case" pattern set forth in [opencurriculum-flashcards](https://github.com/isotope11/opencurriculum-flashcards)
-
 Provides the basic building blocks of a pattern capable of reducing a towering codebase to modular rubble (or more Ruby gems)
 
+### What is PayDirt
+
+PayDirt gets its name from an 18th century gold mining idiom. One was said to have "struck pay dirt" when his pick axe revealed a vein of ore.
+I hit pay dirt when I discovered this pattern. It provides me the freedom to build quickly with the confidence of knowing that testing will be a breeze.
+
+### What is the use case?
+
+Its use case is gem making. It's for getting rid of callbacks and for shipping business logic off to the more suitable (and more portable) location.
+It's for packaging use cases up in a modular fashion, where each unit expects to be provided certain dependencies and can be called to provide an expected result.
+It makes sure you're using dependency injection so you can painlessly mock all your dependencies.
+
+The basic idea:
+
+1. Initialize an object by supplying ALL dependencies as a single options hash.
+2. The object should have ONE public method, `#call`, which will return an expected result object.
+
+What pay_dirt does to help:
+
+1. It will set instance variables from the hash of dependencies, using top level key-value pairs.
+2. It will not initialize (it WILL error) without all required dependencies.
+3. It allows you to set default values for any dependencies (just merge the `options` argument into your defaults hash before calling `#load_options`)
+
+PayDirt also provides a `PayDirt::Result` object for your service objects to return (it will respond to `#successful?` and `#data`, see some examples). This is entirely optional, as this object can return whatever you like.
+
+### Getting on to it
+
 There are two ways to employ the pattern:
 
 1. use a class that inherits from [PayDirt::Base](https://github.com/rthbound/pay_dirt/blob/master/test/unit/pay_dirt/base_test.rb#L6-L24)
@@ -44,16 +68,18 @@ create a service object
 example
 -------
 ```
-$ thor pay_dirt:service_object:new digit_check -d fingers toes -D fingers:10 toes:10
-  create  lib/service_objects/digit_check.rb
+$ thor pay_dirt:service_object:new quick/digit_check -d fingers toes nose -D fingers:10 toes:10
+      create  lib/quick/digit_check.rb
+      create  test/unit/quick/digit_check_test.rb
+      append  test/minitest_helper.rb
 ```
 
-Running the above generator will create the following file
+Running the above generator will create the following object
 
 ```ruby
 require 'pay_dirt'
 
-module ServiceObjects
+module Quick
   class DigitCheck < PayDirt::Base
     def initialize(options = {})
       options = {
@@ -61,23 +87,58 @@ module ServiceObjects
         toes: 10,
       }.merge(options)
 
-      load_options(:fingers, :toes, options)
+      load_options(:fingers, :toes, :nose, options)
     end
 
-    def execute!
-      result(true)
+    def call
+      return result(true)
+    end
+  end
+end
+```
+
+and the following unit test
+```ruby
+require 'minitest_helper'
+
+describe Quick::DigitCheck do
+  before do
+    @subject = Quick::DigitCheck
+    @params = {
+      fingers: MiniTest::Mock.new,
+      toes: MiniTest::Mock.new,
+      nose: MiniTest::Mock.new,
+    }
+  end
+
+  describe "as a class" do
+    it "initializes properly" do
+      @subject.new(@params).must_respond_to :call
+    end
+
+    it "errors when initialized without required dependencies" do
+      -> { @subject.new(@params.reject { |k| k.to_s == 'nose' }) }.must_raise RuntimeError
+    end
+  end
+
+  describe "as an instance" do
+    it "executes successfully" do
+      result = @subject.new(@params).call
+      result.successful?.must_equal true
+      result.must_be_kind_of PayDirt::Result
     end
   end
 end
 ```
 
 ### Usage:
+The class generated can be used in the following manner:
 ```ruby
-require "service_objects/digit_check"  #=> true
-ServiceObjects::DigitCheck.new.execute!
+require "quick/digit_check"  #=> true
+Quick::DigitCheck.new(nose: true).call
  #=> #<PayDirt::Result:0xa0be85c @data=nil, @success=true>
 ```
-As you can see, we can now call `ServiceObjects::DigitCheck.new(fingers: 10, toes: 10).execute!`
+As you can see, we can now call `Quick::DigitCheck.new(nose: true).call`
 and expect a successful return object. Where you take it from there is up to you.
 
 more examples
@@ -86,3 +147,8 @@ more examples
 2. [protected_record](https://github.com/rthbound/protected_record)
 3. [konamio](https://github.com/rthbound/konamio)
 4. [eenie_meenie](https://github.com/rthbound/eenie_meenie)
+5. [foaas](https://github.com/rthbound/foaas)
+6. [konami-fo](https://github.com/rthbound/konami-fo)
+7. [rungs](https://github.com/rthbound/rungs)
+
+#### PayDirt is a Ruby gem based on the "use case" pattern set forth in [opencurriculum-flashcards](https://github.com/isotope11/opencurriculum-flashcards)

data/lib/pay_dirt/version.rb

@@ -1,3 +1,3 @@
 module PayDirt
-  VERSION = "1.0.7"
+  VERSION = "1.0.8"
 end

data/pay_dirt.thor

@@ -2,11 +2,14 @@ module PayDirt
   class ServiceObject < Thor
     include Thor::Actions
 
-    desc "new FILE", "create a service object"
+    desc "new FILE", "create a fully tested object (optionally, requires dependencies)"
     method_option :dependencies,
       type: :array,
       aliases: "-d",
-      desc: "specify required dependencies"
+      desc:    "specify required dependencies"
+    method_option :test_framework,
+      type: :string,
+      desc:    "choose a testing framework"
     method_option :defaults,
       type: :hash,
       aliases: "-D",
@@ -26,73 +29,180 @@ module PayDirt
       class_names = file.split("/").map { |str| str.split("_").map{ |s| (s[0].upcase + s[1..-1]) }.join("") }
       @dependencies = options[:dependencies] || []
 
-      # Favor 2 spaces
-      @append = Proc.new { |depth, string| (@rets ||= "") << ("  " * depth) + string }
-
-      create_file "lib/service_objects/#{file}.rb" do
-        open_class(class_names)
-        write_initialize_method
-        write_execute_method
-
-        close_class(class_names)
-
-        @rets
-      end
+      create_object(file, class_names)
+      create_tests(file, class_names)
     end
 
     private
-    desc "close_class CLASS_NAMES", "hide", hide: true
     def close_class(class_names)
-      @append.call(@class_depth, "end\n") # Closes innermost class definition
+      append(@class_depth, "end\n") # Closes innermost class definition
 
-      class_names[0..-1].each_with_index { |m,i| @append.call(@class_depth - (i + 1), "end\n") }
+      @class_depth.times { |i| append(@class_depth - (i + 1), "end\n") }
     end
 
-    desc "open_class CLASS_NAMES", "hide", hide: true
     def open_class(class_names)
       @class_name  = class_names.last
-      @class_depth = class_names.length
-      @inner_depth = class_names.length + 1
+      @class_depth = class_names.length - 1
+      @inner_depth = class_names.length
 
-      @append.call(0, "require 'pay_dirt'\n\nmodule ServiceObjects\n")
-      class_names[0..-2].each_with_index { |mod,i| @append.call(i.next, "module #{mod}\n") }
+      append(0, "require 'pay_dirt'\n\n")
+      class_names[0..-2].each_with_index { |mod,i| append(i, "module #{mod}\n") }
 
       if options[:include]
-        @append.call(@class_depth, "class #{@class_name}\n")
-        @append.call(@class_depth.next, "include PayDirt::UseCase\n")
+        append(@class_depth, "class #{@class_name}\n")
+        append(@inner_depth, "include PayDirt::UseCase\n")
       elsif options[:inherit]
-        @append.call(@class_depth, "class #{@class_name} < PayDirt::Base\n")
+        append(@class_depth, "class #{@class_name} < PayDirt::Base\n")
       end
     end
 
     def write_execute_method
-      # The execute! method
-      @append.call(@inner_depth, "def execute!\n")
-      @append.call(@inner_depth.next, "return result(true)\n")
-      @append.call(@inner_depth, "end\n")
+      # The call method
+      append(@inner_depth, "def call\n")
+      append(@inner_depth.next, "return result(true)\n")
+      append(@inner_depth, "end\n")
     end
 
     def write_initialize_method
-      @append.call(@inner_depth, "def initialize(options = {})\n")
+      append(@inner_depth, "def initialize(options = {})\n")
 
       set_defaults if options[:defaults]
       call_load_options
 
-      @append.call(@inner_depth, "end\n\n")
+      append(@inner_depth, "end\n\n")
     end
 
     def call_load_options
-      @append.call(@inner_depth.next, "load_options(")
-      @dependencies.each { |dep| @append.call(0, ":#{dep}, ") }
-      @append.call(0, "options)\n")
+      append(@inner_depth.next, "# sets instance variables from key value pairs,\n")
+      append(@inner_depth.next, "# will fail if any keys given before options aren't in options\n")
+      append(@inner_depth.next, "load_options(")
+      @dependencies.each { |dep| append(0, ":#{dep}, ") }
+      append(0, "options)\n")
     end
 
     def set_defaults
-      @append.call(@inner_depth.next, "options = {\n")
+      append(@inner_depth.next, "options = {\n")
+
+      options[:defaults].each { |k,v| append(@inner_depth + 2, "#{k}: #{v}" + ",\n") }
+
+      append(@inner_depth.next, "}.merge(options)\n\n")
+    end
+
+    # TESTS!
+    def open_test_class(class_names, file)
+      case options[:test_framework]
+      when "minitest", "mini_test"
+        append(0, "require 'minitest_helper'\n\n")
+        append_to_file "test/minitest_helper.rb" do
+          "require \"#{file}\"\n"
+        end
+      else
+        append(0, "require 'test_helper'\n\n")
+        append_to_file "test/test_helper.rb" do
+          "require \"#{file}\"\n"
+        end
+      end
+      append(0, "describe #{ class_string(class_names) } do\n")
+    end
+
+    def mock_test_dependencies
+      append(2, "@params = {\n")
+
+      @dependencies.each do |dep|
+        append(3, "#{dep}: MiniTest::Mock.new,\n")
+      end
+
+      append(2, "}\n")
+    end
+
+    def add_before_hook(class_names)
+      append(1, "before do\n")
+      append(2, "@subject = #{ class_string(class_names) }\n")
+      mock_test_dependencies
+      append(1, "end\n")
+    end
+
+    def assert_this(assertion, asserts)
+      append(2, "it \"#{assertion}\" do\n")
+
+      asserts.each do |s|
+        append(3, "#{s}\n")
+      end
+
+      append(2, "end\n")
+    end
 
-      options[:defaults].each { |k,v| @append.call(@inner_depth + 2, "#{k}: #{v}" + ",\n") }
+    def assert_error_without_dependencies
+      assert_this("errors when initialized without required dependencies", @dependencies.reject { |d|
+        options[:defaults] && options[:defaults].keys.include?(d)
+      }.map { |required_dep|
+        "-> { @subject.new(@params.reject { |k| k.to_s == '#{ required_dep }' }) }.must_raise RuntimeError"
+      })
+    end
+
+    def assert_wont_error_with_all_dependencies
+      assert_this("initializes properly", ["@subject.new(@params).must_respond_to :call"])
+    end
+
+    def assert_returns_a_successful_result
+      assert_this("executes successfully", [
+        "result = @subject.new(@params).call",
+        "result.successful?.must_equal true",
+        "result.must_be_kind_of PayDirt::Result"
+      ])
+    end
+
+    def context_class
+      append(1, "describe \"as a class\" do\n")
+      assert_wont_error_with_all_dependencies
+      append(0, "\n")
+      assert_error_without_dependencies
+      append(1, "end\n")
+    end
+
+    def context_instance
+      append(1, "describe \"as an instance\" do\n")
+      assert_returns_a_successful_result
+      append(1, "end\n")
+    end
+
+    def close_test_class
+      append(0, "end")
+    end
+
+    def create_object(file, class_names)
+      @rets = nil
+      create_file "lib/#{file}.rb" do
+        open_class(class_names)
+        write_initialize_method
+        write_execute_method
+
+        close_class(class_names)
+
+        @rets
+      end
+    end
+
+    def create_tests(file, class_names)
+      @rets = nil
+      create_file "test/unit/#{file}_test.rb" do
+        open_test_class(class_names, file)
+        add_before_hook(class_names)
+        append(0, "\n")
+        context_class
+        append(0, "\n")
+        context_instance
+        close_test_class
+        @rets
+      end
+    end
+
+    def append(depth, string)
+      (@rets ||= "") << ("  " * depth) + string
+    end
 
-      @append.call(@inner_depth.next, "}.merge(options)\n\n")
+    def class_string(names)
+      names.map(&:to_s).join("::")
     end
   end
 end

data/test/unit/pay_dirt/base_test.rb

@@ -13,7 +13,7 @@ describe PayDirt::Base do
           load_options(:the_question, :the_secret, options)
         end
 
-        def execute!
+        def call
           @the_secret == 42 and return result(true, @the_secret )
           return result(false)
         end
@@ -33,26 +33,26 @@ describe PayDirt::Base do
   end
 
   it "won't error if defaults were supplied for an omitted option" do
-    @use_case.new(the_secret: :not_telling).must_respond_to :execute!
+    @use_case.new(the_secret: :not_telling).must_respond_to :call
   end
 
-  it "can execute successfully" do
+  it "can be called successfully" do
     dependencies = {
       the_secret: 42
     }
 
-    result = @use_case.new(dependencies).execute!
+    result = @use_case.new(dependencies).call
 
     result.successful?.must_equal true
     result.must_be_kind_of PayDirt::Result
   end
 
-  it "can execute unsuccessfully" do
+  it "can be called unsuccessfully" do
     dependencies = {
       the_secret: :i_dunno
     }
 
-    result = @use_case.new(dependencies).execute!
+    result = @use_case.new(dependencies).call
 
     result.successful?.must_equal false
   end

data/test/unit/pay_dirt/result_test.rb

@@ -19,7 +19,7 @@ describe PayDirt::Result do
           load_options(:success, :data, options)
         end
 
-        def execute!
+        def call
           result(@success, @data)
         end
       end
@@ -28,15 +28,15 @@ describe PayDirt::Result do
     end
 
     it "can succeed" do
-      @pay_dirt.new(success: true, data: "yum").execute!.successful?.must_equal true
+      @pay_dirt.new(success: true, data: "yum").call.successful?.must_equal true
     end
 
     it "can be unsuccessful" do
-      @pay_dirt.new(success: false, data: "gross").execute!.successful?.must_equal false
+      @pay_dirt.new(success: false, data: "gross").call.successful?.must_equal false
     end
 
     it "provides access to data" do
-      @pay_dirt.new(success: true, data: "yum").execute!.data.must_equal "yum"
+      @pay_dirt.new(success: true, data: "yum").call.data.must_equal "yum"
     end
   end
 end

data/test/unit/pay_dirt/use_case_test.rb

@@ -16,7 +16,7 @@ describe PayDirt::UseCase do
           load_options(:the_secret_to_life_the_universe_and_everything, options)
         end
 
-        def execute!
+        def call
           if @the_secret_to_life_the_universe_and_everything == 42
             return PayDirt::Result.new(data: return_value, success: true)
           else
@@ -46,30 +46,30 @@ describe PayDirt::UseCase do
   end
 
   it "must not error when options with defaults are omitted" do
-    @use_case.new({}).must_respond_to :execute!
+    @use_case.new({}).must_respond_to :call
   end
 
   it "loads options that are not required" do
-    result = @use_case.new({ some_random_option: true }).execute!
+    result = @use_case.new({ some_random_option: true }).call
     assert result.data[:some_random_option]
   end
 
-  it "can execute successfully" do
+  it "can be called successfully" do
     dependencies = {
     }
 
-    result = @use_case.new(dependencies).execute!
+    result = @use_case.new(dependencies).call
 
     result.successful?.must_equal true
     result.must_be_kind_of PayDirt::Result
   end
 
-  it "can execute unsuccessfully" do
+  it "can be called unsuccessfully" do
     dependencies = {
       the_secret_to_life_the_universe_and_everything: :i_dunno
     }
 
-    result = @use_case.new(dependencies).execute!
+    result = @use_case.new(dependencies).call
 
     result.successful?.must_equal false
   end
@@ -86,7 +86,7 @@ describe PayDirt::UseCase do
         load_options(:required_option_with_default_value, :required_option, options)
       end
 
-      def execute!
+      def call
         if !@required_option_with_default_value
           return PayDirt::Result.new(data: return_value, success: true)
         else
@@ -105,15 +105,15 @@ describe PayDirt::UseCase do
     end
 
     # Cheating by not injecting all dependencies
-    result = SomeThing.new(required_option: true).execute! # Returns a PayDirt::Result
+    result = SomeThing.new(required_option: true).call # Returns a PayDirt::Result
     assert !result.successful?                             #=> false
     result.data[:optional_option].must_be_nil              #=> nil
     # Playing nice and injecting all required dependencies
-    result = SomeThing.new(required_option: true, required_option_with_default_value: false).execute!
+    result = SomeThing.new(required_option: true, required_option_with_default_value: false).call
     assert result.successful?                              #=> true
     result.data[:optional_option].must_be_nil              #=> nil
     # Making use of an optional option
-    result = SomeThing.new(required_option: true, optional_option: true).execute!
+    result = SomeThing.new(required_option: true, optional_option: true).call
     assert !result.successful?                             #=> false
     assert result.data[:optional_option]                   #=> true
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pay_dirt
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.0.8
 platform: ruby
 authors:
 - Tad Hosford
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-30 00:00:00.000000000 Z
+date: 2013-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest