verbalize 1.4.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d3d8f53fd6b37b6d5729c0c73d9fabb5cfe3c0b
-  data.tar.gz: 22afc7cd81eb619e8dd393f4b606824e479b2780
+  metadata.gz: ca403601a9b7decbc85e77a20103926c8d92765a
+  data.tar.gz: ad015b2d9a8bfa2afa3e9524be0bc8dcfe4260d8
 SHA512:
-  metadata.gz: 771d473b91c42ff8f3c58a12c847eff35969b25aae89141e2dbb9dab4f063112a3552b991ac3174e913c2aab2b4362c8b3db4c95962c666cf446390339c2cc63
-  data.tar.gz: 01b65780f3f72a326d8c9b185dfba2ef257ec50bbe29abb16778cd9b9fde468fdd5cb67cd708d86a43618bf3982fdb7b5a8d5b81187905156e317018411b65f1
+  metadata.gz: 10d7fcf1fda2c00aa8b12d571858595222bc329d8714234ffc4d52a247e31c66fa183e5c0da9d52475a88ca76de7c407a9d6ced73c30aa9dbe2ba88b8a103d38
+  data.tar.gz: c0699fbe4b2c5da4e8f40f143058c552e90c2ffb421ebbc42946d138269c6b7f16d5167cb783885239e76d8ac4e2ba86fa22a2cad2ff01657690b9c4afb06ac2

data/README.md

@@ -179,8 +179,10 @@ 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:
+class method which will return a `Verbalize::Failure` on failure.
+
+Use of `call!` here is not advised as it will result in an exception being thrown. Set assertions on both 
+the failure outcome and value:
 
 ```ruby
 class MyAction
@@ -199,95 +201,75 @@ 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!'
+  expect(result.failure).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.
+When unit testing, it may be necessary to stub the responses of Verbalize actions.  To correctly stub responses,
+you should __always__ stub the `MyAction.perform` class method on the action class being stubbed per the 
+instructions below.  __Never__ stub the `call` or `call!` methods directly.
+
+Stubbing `.perform` will enable `Verbalize` to wrap results correctly for references to either `call` or `call!`.
  
-#### Stubbing `call`
+#### Stubbing Successful Responses
 
-When an object calls a `Verbalize::Action` via `call`, you can stub the response with a `Verbalize::Success` or
-`Verbalize::Failure` instance.
+To simulate a successful response of the `Verbalize::Action` being stubbed, you should stub the `MyAction.perform`
+class method to return the __value__ you expect the `MyAction#call` instance method to return.
 
-Example:
+For example, if you expect the action to return the value `123` on success:
 
 ```ruby
 class Foo
-  def do_something
+  def self.multiply_by(multiple)
     result = MyAction.call(a: 1)
-    raise 'I couldn\'t do the thing!' if result.failure?
+    raise "I couldn't do the thing!" if result.failure?
     
-    'baz'
+    result.value * multiple
   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
+    it 'does the thing when MyAction succeeds' do
+      # Simulate the successful result
+      allow(MyAction).to receive(:perform)
+        .with(a: 1)
+        .and_return(123)
       
-      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)
+      result = described_class.multiply_by(100)
       
-      expect {
-        described_class.do_something
-      }.to raise_error(StandardError, 'I couldnt do the thing!')
+      expect(result).to eq 12300
     end
   end
 end
 ```
 
-#### Stubbing `call!`
+#### Stubbing Failure Responses
 
-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):
+To simulate a __failure__ response of the `Verbalize::Action` being stubbed, you should stub the `MyAction.perform`
+class method to __throw__ `::Verbalize::THROWN_SYMBOL` with the __message__ you expect `MyAction#call` to throw
+when the simulated failure occurs.
 
-Example:
+For example, when you expect the outer class to raise an exception when MyAction fails:
 
 ```ruby
+# See also: Foo class definition in Stubbing Successful Responses above
+
 # 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')
+  describe '#multiply_by' do
+    it 'raises an error when MyAction fails' do
+      # Simulate the failure
+      allow(MyAction).to receive(:perform)
+        .with(a: 1)
+        .and_throw(::Verbalize::THROWN_SYMBOL, 'Y U NO!')
       
       expect {
-        described_class.something
-      }.to raise_error UncaughtThrowError
+        described_class.multiply_by(100)
+      }.to raise_error "I couldn't do the thing!"
     end
   end
 end

data/lib/verbalize/action.rb

@@ -19,20 +19,11 @@ module Verbalize
     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,
+        optional: [],
         **other_keyword_arguments
       )
-
-        deprecate_custom_methods(method_name)
-
         unless other_keyword_arguments.empty?
           raise(
             ArgumentError,
@@ -44,14 +35,12 @@ module Verbalize
 
         class_eval BuildSafeActionMethod.call(
           required_keywords: required_keywords,
-          optional_keywords: optional_keywords,
-          method_name:       method_name
+          optional_keywords: optional_keywords
         )
 
         class_eval BuildDangerousActionMethod.call(
           required_keywords: required_keywords,
-          optional_keywords: optional_keywords,
-          method_name:       method_name
+          optional_keywords: optional_keywords
         )
 
         class_eval BuildInitializeMethod.call(
@@ -65,36 +54,33 @@ module Verbalize
       end
 
       def call
-        __verbalized_send(:call)
+        __verbalized_send
       end
 
       def call!
-        __verbalized_send!(:call)
+        __verbalized_send!
       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.'
+      def perform(*args)
+        new(*args).send(:call)
       end
 
-      def __verbalized_send(method_name, *args)
+      def __verbalized_send(*args)
         error = catch(:verbalize_error) do
-          value = new(*args).send(method_name)
+          value = perform(*args)
           return Success.new(value)
         end
 
         Failure.new(error)
       end
 
-      def __verbalized_send!(method_name, *args)
-        new(*args).send(method_name)
+      def __verbalized_send!(*args)
+        perform(*args)
       rescue UncaughtThrowError => uncaught_throw_error
         fail_value = uncaught_throw_error.value
-        error = VerbalizeError.new("Unhandled fail! called with: #{fail_value.inspect}.")
+        error = Verbalize::Error.new("Unhandled fail! called with: #{fail_value.inspect}.")
         error.set_backtrace(uncaught_throw_error.backtrace[2..-1])
         raise error
       end

data/lib/verbalize/build_dangerous_action_method.rb

@@ -5,15 +5,11 @@ module Verbalize
     private
 
     def declaration
-      "def self.#{method_name}!(#{declaration_keyword_arguments})"
+      declare('self.call!')
     end
 
     def body
-      if all_keywords.empty?
-        "  __verbalized_send!(:#{method_name})"
-      else
-        "  __verbalized_send!(:#{method_name}, #{initialize_keywords_and_values})"
-      end
+      verbalized_send_string(bang: true)
     end
   end
 end

data/lib/verbalize/build_initialize_method.rb

@@ -5,7 +5,7 @@ module Verbalize
     private
 
     def declaration
-      "def initialize(#{declaration_keyword_arguments})"
+      declare('initialize')
     end
 
     def body

data/lib/verbalize/build_method_base.rb

@@ -1,56 +1,68 @@
-class BuildMethodBase
-  def self.call(required_keywords: [], optional_keywords: [], method_name: :call)
-    new(
-      required_keywords: required_keywords,
-      optional_keywords: optional_keywords,
-      method_name:       method_name
-    ).call
-  end
+module Verbalize
+  class BuildMethodBase
+    def self.call(required_keywords: [], optional_keywords: [])
+      new(
+        required_keywords: required_keywords,
+        optional_keywords: optional_keywords
+      ).call
+    end
 
-  def initialize(required_keywords: [], optional_keywords: [], method_name: :call)
-    @required_keywords = required_keywords
-    @optional_keywords = optional_keywords
-    @method_name       = method_name
-  end
+    def initialize(required_keywords: [], optional_keywords: [])
+      @required_keywords = required_keywords
+      @optional_keywords = optional_keywords
+    end
 
-  def call
-    parts.compact.join "\n"
-  end
+    def call
+      parts.compact.join "\n"
+    end
 
-  private
+    private
 
-  attr_reader :required_keywords, :optional_keywords, :method_name
+    attr_reader :required_keywords, :optional_keywords
 
-  def parts
-    [declaration, body, "end\n"]
-  end
+    def parts
+      [declaration, body, "end\n"]
+    end
 
-  def declaration
-    raise NotImplementedError
-  end
+    def declaration
+      raise NotImplementedError
+    end
 
-  def body
-    raise NotImplementedError
-  end
+    def body
+      raise NotImplementedError
+    end
 
-  def all_keywords
-    required_keywords + optional_keywords
-  end
+    def declare(method_name)
+      "def #{method_name}(#{declaration_keyword_arguments})"
+    end
 
-  def required_keyword_segments
-    required_keywords.map { |keyword| "#{keyword}:" }
-  end
+    def all_keywords
+      required_keywords + optional_keywords
+    end
 
-  def optional_keyword_segments
-    optional_keywords.map { |keyword| "#{keyword}: nil" }
-  end
+    def required_keyword_segments
+      required_keywords.map { |keyword| "#{keyword}:" }
+    end
 
-  def declaration_keyword_arguments
-    return if all_keywords.empty?
-    (required_keyword_segments + optional_keyword_segments).join(', ')
-  end
+    def optional_keyword_segments
+      optional_keywords.map { |keyword| "#{keyword}: nil" }
+    end
+
+    def declaration_keyword_arguments
+      return if all_keywords.empty?
+      (required_keyword_segments + optional_keyword_segments).join(', ')
+    end
+
+    def initialize_keywords_and_values
+      all_keywords.map { |variable| "#{variable}: #{variable}" }.join(', ')
+    end
+
+    def verbalized_send_string(bang: false)
+      send_string = '  __verbalized_send'
+      send_string += '!' if bang
 
-  def initialize_keywords_and_values
-    all_keywords.map { |variable| "#{variable}: #{variable}" }.join(', ')
+      return send_string if all_keywords.empty?
+      send_string + "(#{initialize_keywords_and_values})"
+    end
   end
 end

data/lib/verbalize/build_safe_action_method.rb

@@ -5,15 +5,11 @@ module Verbalize
     private
 
     def declaration
-      "def self.#{method_name}(#{declaration_keyword_arguments})"
+      declare('self.call')
     end
 
     def body
-      if all_keywords.empty?
-        "  __verbalized_send(:#{method_name})"
-      else
-        "  __verbalized_send(:#{method_name}, #{initialize_keywords_and_values})"
-      end
+      verbalized_send_string(bang: false)
     end
   end
 end

data/lib/verbalize/error.rb

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

data/lib/verbalize/failure.rb

@@ -1,4 +1,5 @@
 require_relative 'result'
+require_relative 'error'
 
 module Verbalize
   class Failure < Result
@@ -13,10 +14,9 @@ module Verbalize
     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
+      raise Verbalize::Error, 'You called #value on a Failure result.  You should never use `Verbalize::Action#call` ' \
+        'without also explicitly handling potential errors.  Please use `Verbalize::Action#call!` to return a value ' \
+        'directly on successful execution of an action, or handle the error case explicitly if using `#call`.'
     end
   end
 end

data/lib/verbalize/result.rb

@@ -22,9 +22,7 @@ module Verbalize
     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
+      raise NotImplementedError, 'Subclasses must override Verbalize::Result#value'
     end
   end
 end

data/lib/verbalize/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verbalize
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Zach Taylor