bcdd-result 0.10.0 → 0.12.0

data/lib/bcdd/result/callable_and_then/caller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class CallableAndThen::Caller
+    def self.call(source, value:, injected_value:, method_name:)
+      method = callable_method(source, method_name)
+
+      Transitions.tracking.record_and_then(method, injected_value, source) do
+        result =
+          if source.is_a?(::Proc)
+            call_proc!(source, value, injected_value)
+          else
+            call_method!(source, method, value, injected_value)
+          end
+
+        ensure_result_object(source, value, result)
+      end
+    end
+
+    def self.call_proc!(source, value, injected_value)
+      case source.arity
+      when 1 then source.call(value)
+      when 2 then source.call(value, injected_value)
+      else raise CallableAndThen::Error::InvalidArity.build(source: source, method: :call, arity: '1..2')
+      end
+    end
+
+    def self.call_method!(source, method, value, injected_value)
+      case method.arity
+      when 1 then source.send(method.name, value)
+      when 2 then source.send(method.name, value, injected_value)
+      else raise CallableAndThen::Error::InvalidArity.build(source: source, method: method.name, arity: '1..2')
+      end
+    end
+
+    def self.callable_method(source, method_name)
+      source.method(method_name || Config.instance.and_then!.default_method_name_to_call)
+    end
+
+    def self.ensure_result_object(source, _value, result)
+      return result if result.is_a?(::BCDD::Result)
+
+      raise Error::UnexpectedOutcome.build(outcome: result, origin: source)
+    end
+
+    private_class_method :new, :allocate
+    private_class_method :call_proc!, :call_method!, :callable_method, :ensure_result_object
+  end
+end

data/lib/bcdd/result/callable_and_then/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class CallableAndThen::Config
+    attr_accessor :default_method_name_to_call
+
+    def initialize
+      self.default_method_name_to_call = :call
+    end
+
+    def options
+      { default_method_name_to_call: default_method_name_to_call }
+    end
+  end
+end

data/lib/bcdd/result/callable_and_then/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class CallableAndThen::Error < Error
+    class InvalidArity < self
+      def self.build(source:, method:, arity:)
+        new("Invalid arity for #{source.class}##{method} method. Expected arity: #{arity}")
+      end
+    end
+  end
+end

data/lib/bcdd/result/callable_and_then.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module CallableAndThen
+    require_relative 'callable_and_then/error'
+    require_relative 'callable_and_then/config'
+    require_relative 'callable_and_then/caller'
+  end
+end

data/lib/bcdd/result/config/switchers/addons.rb

@@ -3,11 +3,16 @@
 class BCDD::Result
   class Config
     module Addons
+      AFFECTS = %w[
+        BCDD::Result.mixin
+        BCDD::Result::Context.mixin
+        BCDD::Result::Expectations.mixin
+        BCDD::Result::Context::Expectations.mixin
+      ].freeze
+
       OPTIONS = {
-        continue: {
-          default: false,
-          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-        }
+        continue: { default: false, affects: AFFECTS },
+        given: { default: true, affects: AFFECTS }
       }.transform_values!(&:freeze).freeze
 
       def self.switcher

data/lib/bcdd/result/config/switchers/features.rb

@@ -10,7 +10,11 @@ class BCDD::Result
         },
         transitions: {
           default: true,
-          affects: %w[BCDD::Result BCDD::Result::Context]
+          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        },
+        and_then!: {
+          default: false,
+          affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
         }
       }.transform_values!(&:freeze).freeze
 

data/lib/bcdd/result/config.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'singleton'
-
 require_relative 'config/options'
 require_relative 'config/switcher'
 require_relative 'config/switchers/addons'
@@ -20,6 +18,11 @@ class BCDD::Result
       @feature = Features.switcher
       @constant_alias = ConstantAliases.switcher
       @pattern_matching = PatternMatching.switcher
+      @and_then_ = CallableAndThen::Config.new
+    end
+
+    def and_then!
+      @and_then_
     end
 
     def freeze
@@ -27,6 +30,7 @@ class BCDD::Result
       feature.freeze
       constant_alias.freeze
       pattern_matching.freeze
+      and_then!.freeze
 
       super
     end
@@ -45,7 +49,9 @@ class BCDD::Result
     end
 
     def inspect
-      "#<#{self.class.name} options=#{options.keys.sort.inspect}>"
+      "#<#{self.class.name} " \
+        "options=#{options.keys.sort.inspect} " \
+        "and_then!=#{and_then!.options.inspect}>"
     end
   end
 end

data/lib/bcdd/result/context/callable_and_then.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Context::CallableAndThen
+    class Caller < CallableAndThen::Caller
+      module KeyArgs
+        def self.parameters?(source)
+          parameters = source.parameters.map(&:first)
+
+          !parameters.empty? && parameters.all?(/\Akey/)
+        end
+
+        def self.invalid_arity(source, method)
+          CallableAndThen::Error::InvalidArity.build(source: source, method: method, arity: 'only keyword args')
+        end
+      end
+
+      def self.call_proc!(source, value, _injected_value)
+        return source.call(**value) if KeyArgs.parameters?(source)
+
+        raise KeyArgs.invalid_arity(source, :call)
+      end
+
+      def self.call_method!(source, method, value, _injected_value)
+        return source.send(method.name, **value) if KeyArgs.parameters?(method)
+
+        raise KeyArgs.invalid_arity(source, method.name)
+      end
+
+      def self.ensure_result_object(source, value, result)
+        return result.tap { result.send(:acc).then { _1.merge!(value.merge(_1)) } } if result.is_a?(Context)
+
+        raise Error::UnexpectedOutcome.build(outcome: result, origin: source, expected: Context::EXPECTED_OUTCOME)
+      end
+
+      private_class_method :call_proc!, :call_method!
+    end
+  end
+end

data/lib/bcdd/result/context/expectations/mixin.rb

@@ -7,13 +7,21 @@ class BCDD::Result::Context
     Methods = BCDD::Result::Expectations::Mixin::Methods
 
     module Addons
-      module Continuable
+      module Continue
         private def Continue(**value)
-          Success.new(type: :continued, value: value, subject: self)
+          Success.new(type: :continued, value: value, source: self)
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          Success.new(type: :given, value: value, source: self)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/context/mixin.rb

@@ -13,15 +13,15 @@ class BCDD::Result::Context
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, source: self, terminal: terminal)
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         def Success(type, **value)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(**value)
@@ -29,7 +29,15 @@ class BCDD::Result::Context
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          _ResultAs(Success, :given, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/context/success.rb

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
 
-class BCDD::Result::Context::Success < BCDD::Result::Context
-  include ::BCDD::Result::Success::Methods
+class BCDD::Result
+  class Context::Success < Context
+    include ::BCDD::Result::Success::Methods
 
-  def and_expose(type, keys, halted: true)
-    unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
-      raise ::ArgumentError, 'keys must be an Array of Symbols'
-    end
+    def and_expose(type, keys, terminal: true)
+      unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
+        raise ::ArgumentError, 'keys must be an Array of Symbols'
+      end
+
+      Transitions.tracking.reset_and_then!
 
-    exposed_value = acc.merge(value).slice(*keys)
+      exposed_value = acc.merge(value).slice(*keys)
 
-    self.class.new(type: type, value: exposed_value, subject: subject, halted: halted)
+      self.class.new(type: type, value: exposed_value, source: source, terminal: terminal)
+    end
   end
 end

data/lib/bcdd/result/context.rb

@@ -6,6 +6,9 @@ class BCDD::Result
     require_relative 'context/success'
     require_relative 'context/mixin'
     require_relative 'context/expectations'
+    require_relative 'context/callable_and_then'
+
+    EXPECTED_OUTCOME = 'BCDD::Result::Context::Success or BCDD::Result::Context::Failure'
 
     def self.Success(type, **value)
       Success.new(type: type, value: value)
@@ -15,7 +18,7 @@ class BCDD::Result
       Failure.new(type: type, value: value)
     end
 
-    def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
+    def initialize(type:, value:, source: nil, expectations: nil, terminal: nil)
       value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
 
       @acc = {}
@@ -23,8 +26,16 @@ class BCDD::Result
       super
     end
 
-    def and_then(method_name = nil, **context_data, &block)
-      super(method_name, context_data, &block)
+    def and_then(method_name = nil, **injected_value, &block)
+      super(method_name, injected_value, &block)
+    end
+
+    def and_then!(source, **injected_value)
+      _call = injected_value.delete(:_call)
+
+      acc.merge!(injected_value)
+
+      super(source, injected_value, _call: _call)
     end
 
     protected
@@ -33,20 +44,23 @@ class BCDD::Result
 
     private
 
-    SubjectMethodArity = ->(method) do
+    SourceMethodArity = ->(method) do
       return 0 if method.arity.zero?
-      return 1 if method.parameters.map(&:first).all?(/\Akey/)
+
+      parameters = method.parameters.map(&:first)
+
+      return 1 if !parameters.empty? && parameters.all?(/\Akey/)
 
       -1
     end
 
-    def call_and_then_subject_method!(method, context_data)
-      acc.merge!(value.merge(context_data))
+    def call_and_then_source_method!(method, injected_value)
+      acc.merge!(value.merge(injected_value))
 
-      case SubjectMethodArity[method]
-      when 0 then subject.send(method.name)
-      when 1 then subject.send(method.name, **acc)
-      else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 1)
+      case SourceMethodArity[method]
+      when 0 then source.send(method.name)
+      when 1 then source.send(method.name, **acc)
+      else raise Error::InvalidSourceMethodArity.build(source: source, method: method, max_arity: 1)
       end
     end
 
@@ -56,20 +70,24 @@ class BCDD::Result
       block.call(acc)
     end
 
+    def call_and_then_callable!(source, value:, injected_value:, method_name:)
+      acc.merge!(value.merge(injected_value))
+
+      CallableAndThen::Caller.call(source, value: acc, injected_value: injected_value, method_name: method_name)
+    end
+
     def ensure_result_object(result, origin:)
       raise_unexpected_outcome_error(result, origin) unless result.is_a?(Context)
 
-      return result.tap { _1.acc.merge!(acc) } if result.subject.equal?(subject)
+      return result.tap { _1.acc.merge!(acc) } if result.source.equal?(source)
 
-      raise Error::InvalidResultSubject.build(given_result: result, expected_subject: subject)
+      raise Error::InvalidResultSource.build(given_result: result, expected_source: source)
     end
 
-    EXPECTED_OUTCOME = 'BCDD::Result::Context::Success or BCDD::Result::Context::Failure'
-
     def raise_unexpected_outcome_error(result, origin)
       raise Error::UnexpectedOutcome.build(outcome: result, origin: origin, expected: EXPECTED_OUTCOME)
     end
 
-    private_constant :SubjectMethodArity, :EXPECTED_OUTCOME
+    private_constant :SourceMethodArity
   end
 end

data/lib/bcdd/result/error.rb

@@ -9,7 +9,7 @@ class BCDD::Result::Error < StandardError
   end
 
   class MissingTypeArgument < self
-    def initialize(_arg = nil)
+    def initialize(_message = nil)
       super('A type (argument) is required to invoke the #on/#on_type method')
     end
   end
@@ -22,29 +22,38 @@ class BCDD::Result::Error < StandardError
     end
   end
 
-  class InvalidResultSubject < self
-    def self.build(given_result:, expected_subject:)
+  class InvalidResultSource < self
+    def self.build(given_result:, expected_source:)
       message =
-        "You cannot call #and_then and return a result that does not belong to the subject!\n" \
-        "Expected subject: #{expected_subject.inspect}\n" \
-        "Given subject: #{given_result.send(:subject).inspect}\n" \
+        "You cannot call #and_then and return a result that does not belong to the same source!\n" \
+        "Expected source: #{expected_source.inspect}\n" \
+        "Given source: #{given_result.send(:source).inspect}\n" \
         "Given result: #{given_result.inspect}"
 
       new(message)
     end
   end
 
-  class InvalidSubjectMethodArity < self
-    def self.build(subject:, method:, max_arity:)
-      new("#{subject.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0..#{max_arity}")
+  class InvalidSourceMethodArity < self
+    def self.build(source:, method:, max_arity:)
+      new("#{source.class}##{method.name} has unsupported arity (#{method.arity}). Expected 0..#{max_arity}")
     end
   end
 
   class UnhandledTypes < self
     def self.build(types:)
-      subject = types.size == 1 ? 'This was' : 'These were'
+      source = types.size == 1 ? 'This was' : 'These were'
 
-      new("You must handle all cases. #{subject} not handled: #{types.map(&:inspect).join(', ')}")
+      new("You must handle all cases. #{source} not handled: #{types.map(&:inspect).join(', ')}")
+    end
+  end
+
+  class CallableAndThenDisabled < self
+    def initialize(_message = nil)
+      super(
+        'You cannot use #and_then! as the feature is disabled. ' \
+        'Please use BCDD::Result.config.feature.enable!(:and_then!) to enable it.'
+      )
     end
   end
 end

data/lib/bcdd/result/expectations/mixin.rb

@@ -24,25 +24,31 @@ class BCDD::Result
 
       FACTORY = <<~RUBY
         private def _Result
-          @_Result ||= Result.with(subject: self, halted: %<halted>s)
+          @_Result ||= Result.with(source: self, terminal: %<terminal>s)
         end
       RUBY
 
       def self.to_eval(addons)
-        halted = addons.key?(:continue) ? 'true' : 'nil'
+        terminal = addons.key?(:continue) ? 'true' : 'nil'
 
-        "#{BASE}\n#{format(FACTORY, halted: halted)}"
+        "#{BASE}\n#{format(FACTORY, terminal: terminal)}"
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         private def Continue(value)
-          Success.new(type: :continued, value: value, subject: self)
+          Success.new(type: :continued, value: value, source: self)
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(value)
+          Success.new(type: :given, value: value, source: self)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/expectations.rb

@@ -38,10 +38,10 @@ class BCDD::Result
 
     private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
 
-    def initialize(subject: nil, contract: nil, halted: nil, **options)
-      @halted = halted
+    def initialize(source: nil, contract: nil, terminal: nil, **options)
+      @terminal = terminal
 
-      @subject = subject
+      @source = source
 
       @contract = contract if contract.is_a?(Contract::Evaluator)
 
@@ -60,16 +60,16 @@ class BCDD::Result
       _ResultAs(Failure, type, value)
     end
 
-    def with(subject:, halted: nil)
-      self.class.new(subject: subject, halted: halted, contract: contract)
+    def with(source:, terminal: nil)
+      self.class.new(source: source, terminal: terminal, contract: contract)
     end
 
     private
 
     def _ResultAs(kind_class, type, value)
-      kind_class.new(type: type, value: value, subject: subject, expectations: contract, halted: halted)
+      kind_class.new(type: type, value: value, source: source, expectations: contract, terminal: terminal)
     end
 
-    attr_reader :subject, :halted, :contract
+    attr_reader :source, :terminal, :contract
   end
 end

data/lib/bcdd/result/mixin.rb

@@ -20,15 +20,15 @@ class BCDD::Result
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, source: self, terminal: terminal)
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         def Success(type, value = nil)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(value)
@@ -36,7 +36,13 @@ class BCDD::Result
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(value)
+          _ResultAs(Success, :given, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/transitions/tracking/disabled.rb

@@ -2,16 +2,26 @@
 
 module BCDD::Result::Transitions
   module Tracking::Disabled
-    def self.start(name:, desc:); end
-
-    def self.finish(result:); end
+    def self.exec(_name, _desc)
+      EnsureResult[yield]
+    end
 
     def self.reset!; end
 
     def self.record(result); end
 
-    def self.record_and_then(_type, _data, _subject)
+    def self.record_and_then(_type, _data, _source)
       yield
     end
+
+    def self.reset_and_then!; end
+
+    class << self
+      private
+
+      def start(name, desc); end
+
+      def finish(result); end
+    end
   end
 end