bcdd-result 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a41105b84f902004736a171bd42c943923ee188d14fe6630bf379fb3e3ef158
-  data.tar.gz: 7b879ee4c04c2b60e95d1c2af18e28c8e7f1edb475c0cdb8274c56f6a577198a
+  metadata.gz: 96c58d6a9132fbf42fc8f3c1d9ba683f0b6297e23b1f0536fc4bcb7efb5084df
+  data.tar.gz: fcef45f3c5ddacc20ff5e9533012c7fbe5817878cef1ff528dabd8920e1cbccd
 SHA512:
-  metadata.gz: 48e9dd67d1f69a4b9aae0bbf1166aab532ca2f8cdc8883bf303b5a41f702a77c8531c4ae2baa96bf256a828e9db0624d631c1259e0870c9ee22ecd65b4ed2ce9
-  data.tar.gz: cb2a0e618b21a4bf98c61b0a4dabfac322efe4293eab18c84cf729df920c49bf47557dcf20ceb01c42ac7c4673fa6fb55c235a2e93f2555a2021cbbfb3f37b36
+  metadata.gz: d4cf048907571205c6cd0b90ca4b95c2480c34de79d082132e4f1cab1e809f4c6eec538d9d38b036ad313d9653420625b68a502272e73371b99b157f43315123
+  data.tar.gz: 4662aaeb33a7eb770ab51529cc1f2c4e9d86844dec70dfcdc4f37674aab33d010d6cbe7932fc635f09979d47b4b631748a3d4791021e99108a011a93469a2d73

data/.rubocop_todo.yml

@@ -1,12 +1,12 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2023-09-25 17:14:03 UTC using RuboCop version 1.56.3.
+# on 2023-09-27 00:47:03 UTC using RuboCop version 1.56.3.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 9
+# Offense count: 13
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
@@ -15,5 +15,7 @@ Style/Documentation:
     - 'lib/bcdd/result.rb'
     - 'lib/bcdd/result/error.rb'
     - 'lib/bcdd/result/failure.rb'
+    - 'lib/bcdd/result/handler.rb'
     - 'lib/bcdd/result/success.rb'
+    - 'lib/bcdd/result/type.rb'
     - 'lib/bcdd/resultable.rb'

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.3.0] - 2023-09-26
+
+### Added
+
+- Add `BCDD::Result#handle`. This method allows defining blocks for each hook (type, failure, success), but instead of returning the result itself, it will return the output of the first match/block execution.
+
 ## [0.2.0] - 2023-09-26
 
 ### Added

data/README.md

@@ -14,6 +14,7 @@ Furthermore, this abstraction exposes several features that will be useful to ma
 
 Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofit.com/rop/) pattern (superpower) in your code.
 
+- [Ruby Version](#ruby-version)
 - [Installation](#installation)
 - [Usage](#usage)
 - [Reference](#reference)
@@ -24,6 +25,7 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
     - [`result.on_type`](#resulton_type)
     - [`result.on_success`](#resulton_success)
     - [`result.on_failure`](#resulton_failure)
+    - [`result.handle`](#resulthandle)
   - [Result Value](#result-value)
     - [`result.value_or`](#resultvalue_or)
     - [`result.data_or`](#resultdata_or)
@@ -39,18 +41,26 @@ Use it to enable the [Railway Oriented Programming](https://fsharpforfunandprofi
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
 
+## Ruby Version
+
+`>= 2.7.0`
+
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add this line to your application's Gemfile:
 
-    $ bundle add bcdd-result
+```ruby
+gem 'bcdd-result', require: 'bcdd/result'
+```
+
+And then execute:
+
+    $ bundle install
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
     $ gem install bcdd-result
 
-> **NOTE:** This gem is compatible with Ruby >= 2.7.0
-
 <p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
 ## Usage
@@ -263,6 +273,52 @@ divide(4, 0).on_failure(:invalid_arg) { |error| puts error }
 
 <p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
 
+#### `result.handle`
+
+This method will allow you to define blocks for each hook (type, failure, success), but instead of returning itself, it will return the output of the first match/block execution.
+
+```ruby
+divide(4, 2).handle do |result|
+  result.success { |number| number }
+  result.failure(:invalid_arg) { |err| puts err }
+  result.type(:division_by_zero) { raise ZeroDivisionError }
+end
+
+#or
+
+divide(4, 2).handle do |on|
+  on.success { |number| number }
+  on.failure { |err| puts err }
+end
+
+#or
+
+divide(4, 2).handle do |on|
+  on.type(:invalid_arg) { |err| puts err }
+  on.type(:division_by_zero) { raise ZeroDivisionError }
+  on.type(:division_completed) { |number| number }
+end
+
+# or
+
+divide(4, 2).handle do |on|
+  on[:invalid_arg] { |err| puts err }
+  on[:division_by_zero] { raise ZeroDivisionError }
+  on[:division_completed] { |number| number }
+end
+
+# The [] syntax 👆 is an alias of #type.
+```
+
+**Notes:**
+* You can define multiple types to be handled by the same hook/block
+* If the type is missing, it will perform the block for any success or failure handler.
+* The `#type` and `#[]` handlers will require at least one type/argument.
+
+*PS: The `divide()` implementation is [here](#result-hooks).*
+
+<p align="right">(<a href="#-bcddresult">⬆️ &nbsp;back to top</a>)</p>
+
 ### Result Value
 
 The most simple way to get the result value is by calling `BCDD::Result#value` or `BCDD::Result#data`.

data/lib/bcdd/result/handler.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Handler
+    UNDEFINED = ::Object.new
+
+    def initialize(result)
+      @outcome = UNDEFINED
+
+      @_type = result._type
+      @result = result
+    end
+
+    def [](*types, &block)
+      raise Error::MissingTypeArgument if types.empty?
+
+      self.outcome = block if _type.in?(types, allow_empty: false)
+    end
+
+    def failure(*types, &block)
+      self.outcome = block if result.failure? && _type.in?(types, allow_empty: true)
+    end
+
+    def success(*types, &block)
+      self.outcome = block if result.success? && _type.in?(types, allow_empty: true)
+    end
+
+    alias type []
+
+    private
+
+    attr_reader :_type, :result
+
+    def outcome?
+      @outcome != UNDEFINED
+    end
+
+    def outcome
+      @outcome if outcome?
+    end
+
+    def outcome=(block)
+      @outcome = block.call(result.value, result.type) unless outcome?
+    end
+  end
+
+  private_constant :Handler
+end

data/lib/bcdd/result/type.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Type
+    attr_reader :to_sym
+
+    def initialize(type)
+      @to_sym = type.to_sym
+    end
+
+    def in?(types, allow_empty: false)
+      (allow_empty && types.empty?) || types.any?(to_sym)
+    end
+  end
+
+  private_constant :Type
+end

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/bcdd/result.rb

@@ -2,22 +2,28 @@
 
 require_relative 'result/version'
 require_relative 'result/error'
+require_relative 'result/type'
+require_relative 'result/handler'
 require_relative 'result/failure'
 require_relative 'result/success'
 
 require_relative 'resultable'
 
 class BCDD::Result
-  attr_reader :type, :value, :subject
+  attr_reader :_type, :value, :subject
 
   protected :subject
 
   def initialize(type:, value:, subject: nil)
-    @type = type.to_sym
+    @_type = Type.new(type)
     @value = value
     @subject = subject
   end
 
+  def type
+    _type.to_sym
+  end
+
   def success?(_type = nil)
     raise Error::NotImplemented
   end
@@ -46,15 +52,15 @@ class BCDD::Result
   def on(*types)
     raise Error::MissingTypeArgument if types.empty?
 
-    tap { yield(value, type) if expected_type?(types) }
+    tap { yield(value, type) if _type.in?(types, allow_empty: false) }
   end
 
   def on_success(*types)
-    tap { yield(value, type) if success? && allowed_to_handle?(types) }
+    tap { yield(value, type) if success? && _type.in?(types, allow_empty: true) }
   end
 
   def on_failure(*types)
-    tap { yield(value, type) if failure? && allowed_to_handle?(types) }
+    tap { yield(value, type) if failure? && _type.in?(types, allow_empty: true) }
   end
 
   def and_then(method_name = nil)
@@ -67,20 +73,20 @@ class BCDD::Result
     ensure_result_object(result, origin: :block)
   end
 
+  def handle
+    handler = Handler.new(self)
+
+    yield handler
+
+    handler.send(:outcome)
+  end
+
   alias data value
   alias data_or value_or
   alias on_type on
 
   private
 
-  def expected_type?(types)
-    types.any?(type)
-  end
-
-  def allowed_to_handle?(types)
-    types.empty? || expected_type?(types)
-  end
-
   def call_subject_method(method_name)
     method = subject.method(method_name)
 

data/sig/bcdd/result.rbs

@@ -5,12 +5,14 @@ module BCDD
 end
 
 class BCDD::Result
-  attr_reader type: Symbol
+  attr_reader _type: BCDD::Result::Type
   attr_reader value: untyped
   attr_reader subject: untyped
 
   def initialize: (type: Symbol, value: untyped, ?subject: untyped) -> void
 
+  def type: -> Symbol
+
   def success?: (?Symbol type) -> bool
   def failure?: (?Symbol type) -> bool
 
@@ -29,14 +31,14 @@ class BCDD::Result
 
   def and_then: (?Symbol method_name) { (untyped) -> untyped } -> BCDD::Result
 
+  def handle: { (BCDD::Result::Handler) -> void } -> untyped
+
   alias data value
   alias data_or value_or
   alias on_type on
 
   private
 
-  def expected_type?: (Array[Symbol]) -> bool
-  def allowed_to_handle?: (Array[Symbol]) -> bool
   def call_subject_method: (Symbol) -> BCDD::Result
   def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result
 end
@@ -55,6 +57,31 @@ class BCDD::Result
   def self.Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
 end
 
+class BCDD::Result
+  class Handler
+    UNDEFINED: Object
+
+    def initialize: (BCDD::Result) -> void
+
+    def []: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def failure: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def success: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+
+    alias type []
+
+    private
+
+    attr_reader _type: BCDD::Result::Type
+    attr_reader result: BCDD::Result
+
+    def outcome?: -> bool
+
+    def outcome: -> untyped
+
+    def outcome=: (Proc) -> void
+  end
+end
+
 module BCDD
   module Resultable
     def Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
@@ -63,6 +90,16 @@ module BCDD
   end
 end
 
+class BCDD::Result
+  class Type
+    attr_reader to_sym: Symbol
+
+    def initialize: (Symbol) -> void
+
+    def in?: (Array[Symbol], allow_empty: bool) -> bool
+  end
+end
+
 class BCDD::Result
   class Error < ::StandardError
     def self.build: (**untyped) -> BCDD::Result::Error

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bcdd-result
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-26 00:00:00.000000000 Z
+date: 2023-09-27 00:00:00.000000000 Z
 dependencies: []
 description: A general-purpose result monad that allows you to create objects that
   represent a success (BCDD::Result::Success) or failure (BCDD::Result::Failure).
@@ -29,7 +29,9 @@ files:
 - lib/bcdd/result.rb
 - lib/bcdd/result/error.rb
 - lib/bcdd/result/failure.rb
+- lib/bcdd/result/handler.rb
 - lib/bcdd/result/success.rb
+- lib/bcdd/result/type.rb
 - lib/bcdd/result/version.rb
 - lib/bcdd/resultable.rb
 - sig/bcdd/result.rbs