verbalize 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 61174d8fa1734e70a63a74b34060d056515098ca
-  data.tar.gz: b3fc22d20687f9eba615606cdbc10865e56ea02f
+  metadata.gz: 2d3d8f53fd6b37b6d5729c0c73d9fabb5cfe3c0b
+  data.tar.gz: 22afc7cd81eb619e8dd393f4b606824e479b2780
 SHA512:
-  metadata.gz: f3aeff77f6ce6012c78c597cfaadd60f19450e0cdfbd2c08e9f785b2a32b60d55685cc5571c97f0278a8c35795548811ade2e1dcc20209fe8bf7f9a600c5fbd5
-  data.tar.gz: f5c66899c7b5bcf67b088b92cbdeb1e81191d6479cea19204b9d8541cd144eec97a7f3b33e35a83ff67762429d703f05d896c8b3428e5ef679620de530eb69ab
+  metadata.gz: 771d473b91c42ff8f3c58a12c847eff35969b25aae89141e2dbb9dab4f063112a3552b991ac3174e913c2aab2b4362c8b3db4c95962c666cf446390339c2cc63
+  data.tar.gz: 01b65780f3f72a326d8c9b185dfba2ef257ec50bbe29abb16778cd9b9fde468fdd5cb67cd708d86a43618bf3982fdb7b5a8d5b81187905156e317018411b65f1

data/README.md

@@ -6,7 +6,7 @@
 
 ```ruby
 class Add
-  include Verbalize
+  include Verbalize::Action
 
   input :a, :b
 
@@ -30,7 +30,7 @@ value # => 42
 
 ```ruby
 class Add
-  include Verbalize
+  include Verbalize::Action
 
   input optional: [:a, :b]
 
@@ -55,7 +55,7 @@ Add.call(a: 660, b: 6) # => [:ok, 666]
 
 ```ruby
 class Divide
-  include Verbalize
+  include Verbalize::Action
 
   input :a, :b
 
@@ -96,7 +96,7 @@ class RubyAdd
 end
 
 class VerbalizeAdd
-  include Verbalize
+  include Verbalize::Action
 
   input :a, :b
 
@@ -150,6 +150,149 @@ Comparison:
 
 ```
 
+## Testing
+
+### Happy Path
+
+When testing positive cases of a `Verbalize::Action`, it is recommended to test using the `call!` class method and
+assert on the result.  This implicitly ensures a successful result, and your tests will fail with a bang! if 
+something goes wrong:
+
+```ruby
+class MyAction
+  include Verbalize::Action
+  
+  input :a
+  
+  def call
+    fail!('#{a} is greater than than 100!') if a >= 100
+    a + 1
+  end
+end
+
+it 'returns the expected result' do
+  result = MyAction.call!(a: 50)
+  expect(result).to eq 51
+end
+```
+
+### Sad Path
+
+When testing negative cases of a `Verbalize::Action`, it is recommended to test using the `call` non-bang 
+class method.  Use of `call!` here is not advised as it will result in an exception being thrown. Set assertions 
+on both the outcome and error value of the result:
+
+```ruby
+class MyAction
+  include Verbalize::Action
+  
+  input :a
+  
+  def call
+    fail!('#{a} is greater than 100!') if a >= 100
+    a + 1
+  end
+end
+  
+# rspec:
+it 'fails when the input is out of bounds' do
+  result = MyAction.call(a: 1000)
+  
+  expect(result).to be_failed
+  expect(result.value).to eq '1000 is greater than 100!'
+end
+```
+
+### Stubbing Responses
+
+When unit testing, it may be necessary to stub responses of Actions. The approach required depends 
+on how the nested actions are called by the object under test.
+ 
+#### Stubbing `call`
+
+When an object calls a `Verbalize::Action` via `call`, you can stub the response with a `Verbalize::Success` or
+`Verbalize::Failure` instance.
+
+Example:
+
+```ruby
+class Foo
+  def do_something
+    result = MyAction.call(a: 1)
+    raise 'I couldn\'t do the thing!' if result.failure?
+    
+    'baz'
+  end
+end
+
+# rspec:
+describe Foo do
+  describe '#something' do
+    subject { described_class.new(foo: 'bar') }
+    
+    it 'does the thing when my action succeeds' do
+      successful_result = Verbalize::Success.new(123)
+      allow(MyAction).to receive(:call)
+                               .with(a: 1)
+                               .and_return(successful_result)
+      
+      result = described_class.do_something
+      
+      expect(result).to eq 'baz'
+    end
+    
+    it 'raises an error when MyAction fails' do
+      failed_result = Verbalize::Failure.new('Y U NO!')
+      allow(MyAction).to receive(:call)
+                               .with(a: 3)
+                               .and_return(failed_result)
+      
+      expect {
+        described_class.do_something
+      }.to raise_error(StandardError, 'I couldnt do the thing!')
+    end
+  end
+end
+```
+
+#### Stubbing `call!`
+
+When an object calls a `Verbalize::Action` via `call!`, you can stub the response for the positive case with the value
+you expect to be returned.  When stubbing the negative case, you should instead throw `Verbalize::THROWN_SYMBOL`
+(and the error message, if desired):
+
+Example:
+
+```ruby
+# rspec:
+describe Foo do
+  describe '#something' do
+    subject { described_class.new(foo: 'bar') }
+    
+    it 'does the thing' do
+      allow(MyAction).to receive(:call!)
+                               .with(a: 1)
+                               .and_return(123)
+      
+      result = described_class.something
+      
+      expect(result).to eq 'baz'
+    end
+    
+    it 'returns an error when MyAction fails' do
+      failed_result = Verbalize::Failure.new('Y U NO!')
+      allow(MyAction).to receive(:call)
+                               .with(a: 3)
+                               .and_throw(::Verbalize::THROWN_SYMBOL, 'the failure message, if any')
+      
+      expect {
+        described_class.something
+      }.to raise_error UncaughtThrowError
+    end
+  end
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/verbalize.rb

@@ -1,94 +1,13 @@
 require 'verbalize/version'
-require 'verbalize/build_initialize_method'
-require 'verbalize/build_safe_action_method'
-require 'verbalize/build_dangerous_action_method'
-require 'verbalize/build_attribute_readers'
-require 'verbalize/result'
+require 'verbalize/action'
 
 module Verbalize
-  THROWN_SYMBOL = :verbalize_error
-  VerbalizeError = Class.new(StandardError)
-
-  def fail!(failure_value = nil)
-    throw(THROWN_SYMBOL, failure_value)
-  end
+  # Remove this in a later version of Verbalize if desired.  Aliased here for backwards compatibility.
+  THROWN_SYMBOL = Action::THROWN_SYMBOL
 
   def self.included(target)
-    target.extend ClassMethods
-  end
-
-  module ClassMethods
-    def verbalize(*arguments, **keyword_arguments)
-      method_name, *arguments = arguments
-      input(*arguments, method_name: method_name, **keyword_arguments)
-    end
-
-    def input( # rubocop:disable Metrics/MethodLength
-      *required_keywords,
-      optional:    [],
-      method_name: :call,
-      **other_keyword_arguments
-    )
-
-      unless other_keyword_arguments.empty?
-        raise(
-          ArgumentError,
-          "Unsupported keyword arguments received: #{other_keyword_arguments.inspect}"
-        )
-      end
-
-      optional_keywords = Array(optional)
-
-      class_eval BuildSafeActionMethod.call(
-        required_keywords: required_keywords,
-        optional_keywords: optional_keywords,
-        method_name:       method_name
-      )
-
-      class_eval BuildDangerousActionMethod.call(
-        required_keywords: required_keywords,
-        optional_keywords: optional_keywords,
-        method_name:       method_name
-      )
-
-      class_eval BuildInitializeMethod.call(
-        required_keywords: required_keywords,
-        optional_keywords: optional_keywords
-      )
-
-      class_eval BuildAttributeReaders.call(
-        attributes: required_keywords + optional_keywords
-      )
-    end
-
-    def call
-      __verbalized_send(:call)
-    end
-
-    def call!
-      __verbalized_send!(:call)
-    end
-
-    private
-
-    def __verbalized_send(method_name, *args)
-      outcome = :error
-      value = catch(:verbalize_error) do
-        value = new(*args).send(method_name)
-        # The outcome is :ok if the call didn't throw.
-        outcome = :ok
-        value
-      end
-      Result.new(outcome: outcome, value: value)
-    end
-
-    def __verbalized_send!(method_name, *args)
-      new(*args).send(method_name)
-    rescue UncaughtThrowError => uncaught_throw_error
-      fail_value = uncaught_throw_error.value
-      error = VerbalizeError.new("Unhandled fail! called with: #{fail_value.inspect}.")
-      error.set_backtrace(uncaught_throw_error.backtrace[2..-1])
-      raise error
-    end
+    warn Kernel.caller.first + ': `include Verbalize` is deprecated and will be removed in Verbalize v3.0; ' \
+                                          'include `Verbalize::Action` instead'
+    target.include Verbalize::Action
   end
 end

data/lib/verbalize/action.rb

@@ -0,0 +1,103 @@
+require_relative 'error'
+require_relative 'build_initialize_method'
+require_relative 'build_safe_action_method'
+require_relative 'build_dangerous_action_method'
+require_relative 'build_attribute_readers'
+require_relative 'success'
+require_relative 'failure'
+
+module Verbalize
+  module Action
+    THROWN_SYMBOL = :verbalize_error
+
+    def fail!(failure_value = nil)
+      throw(THROWN_SYMBOL, failure_value)
+    end
+
+    def self.included(target)
+      target.extend ClassMethods
+    end
+
+    module ClassMethods
+      def verbalize(*arguments, **keyword_arguments)
+        method_name, *arguments = arguments
+        input(*arguments, method_name: method_name, **keyword_arguments)
+      end
+
+      def input( # rubocop:disable Metrics/MethodLength
+        *required_keywords,
+        optional:    [],
+        method_name: :call,
+        **other_keyword_arguments
+      )
+
+        deprecate_custom_methods(method_name)
+
+        unless other_keyword_arguments.empty?
+          raise(
+            ArgumentError,
+            "Unsupported keyword arguments received: #{other_keyword_arguments.inspect}"
+          )
+        end
+
+        optional_keywords = Array(optional)
+
+        class_eval BuildSafeActionMethod.call(
+          required_keywords: required_keywords,
+          optional_keywords: optional_keywords,
+          method_name:       method_name
+        )
+
+        class_eval BuildDangerousActionMethod.call(
+          required_keywords: required_keywords,
+          optional_keywords: optional_keywords,
+          method_name:       method_name
+        )
+
+        class_eval BuildInitializeMethod.call(
+          required_keywords: required_keywords,
+          optional_keywords: optional_keywords
+        )
+
+        class_eval BuildAttributeReaders.call(
+          attributes: required_keywords + optional_keywords
+        )
+      end
+
+      def call
+        __verbalized_send(:call)
+      end
+
+      def call!
+        __verbalized_send!(:call)
+      end
+
+      private
+
+      def deprecate_custom_methods(method_name)
+        return if method_name == :call
+        warn Kernel.caller[2] + ': use of custom method names for Actions is deprecated and support ' \
+          'for it will be dropped in Verbalize v2.0.  The `verbalize` method will also be removed.' \
+          'Use `input` and define `#call` on your Action class instead.'
+      end
+
+      def __verbalized_send(method_name, *args)
+        error = catch(:verbalize_error) do
+          value = new(*args).send(method_name)
+          return Success.new(value)
+        end
+
+        Failure.new(error)
+      end
+
+      def __verbalized_send!(method_name, *args)
+        new(*args).send(method_name)
+      rescue UncaughtThrowError => uncaught_throw_error
+        fail_value = uncaught_throw_error.value
+        error = VerbalizeError.new("Unhandled fail! called with: #{fail_value.inspect}.")
+        error.set_backtrace(uncaught_throw_error.backtrace[2..-1])
+        raise error
+      end
+    end
+  end
+end

data/lib/verbalize/error.rb

@@ -0,0 +1,3 @@
+module Verbalize
+  VerbalizeError = Class.new(StandardError)
+end

data/lib/verbalize/failure.rb

@@ -0,0 +1,22 @@
+require_relative 'result'
+
+module Verbalize
+  class Failure < Result
+    extend Gem::Deprecate
+
+    def initialize(failure)
+      super(outcome: :error, value: failure)
+    end
+
+    def failure
+      @value
+    end
+
+    def value
+      warn Kernel.caller.first + ': `Verbalize::Failure#value` is deprecated; use `Verbalize::Failure#failure` '\
+        'instead when explicitly handling failures. `Verbalize::Failure#value` will raise an exception in Verbalize '\
+        '2.0 to prevent accidental use of `#value` on failure results without explicit error handling. '
+      @value
+    end
+  end
+end

data/lib/verbalize/result.rb

@@ -5,7 +5,7 @@ module Verbalize
       @value   = value
     end
 
-    attr_reader :outcome, :value
+    attr_reader :outcome
 
     def succeeded?
       !failed?
@@ -18,7 +18,13 @@ module Verbalize
     alias_method :failure?, :failed?
 
     def to_ary
-      [outcome, value]
+      [outcome, @value]
+    end
+
+    def value
+      warn Kernel.caller.first + ': `Verbalize::Result#value` is deprecated and will be removed in Verbalize 2.0. '\
+        'Use `Verbalize::Failure#error` or `Verbalize::Success#value` instead.'
+      @value
     end
   end
 end

data/lib/verbalize/success.rb

@@ -0,0 +1,11 @@
+require_relative 'result'
+
+module Verbalize
+  class Success < Result
+    def initialize(value)
+      super(outcome: :ok, value: value)
+    end
+
+    attr_reader :value
+  end
+end

data/lib/verbalize/version.rb

@@ -1,3 +1,3 @@
 module Verbalize
-  VERSION = '1.3.0'.freeze
+  VERSION = '1.4.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verbalize
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Zach Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-09 00:00:00.000000000 Z
+date: 2016-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -113,12 +113,16 @@ files:
 - bin/setup
 - circle.yml
 - lib/verbalize.rb
+- lib/verbalize/action.rb
 - lib/verbalize/build_attribute_readers.rb
 - lib/verbalize/build_dangerous_action_method.rb
 - lib/verbalize/build_initialize_method.rb
 - lib/verbalize/build_method_base.rb
 - lib/verbalize/build_safe_action_method.rb
+- lib/verbalize/error.rb
+- lib/verbalize/failure.rb
 - lib/verbalize/result.rb
+- lib/verbalize/success.rb
 - lib/verbalize/version.rb
 - verbalize.gemspec
 homepage: https://github.com/taylorzr/verbalize