monad-oxide 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9e34a9c5d348e0d022e91919a9d4f8c3c3337cc4040e3c6003a21395db4a553
-  data.tar.gz: 589f27d397f02deddc8e4372fc1ddbf553803e301ed5cff6df176d7e0d740c79
+  metadata.gz: eb1f3b4527006d3ab2dac1f0bd4f4a34ba51b5322be9f399b8aac2c329a0522f
+  data.tar.gz: cea1e0e146c40f451d1cfacf37b8c00b588bbd54b45426a1ba2d6b66e7a51017
 SHA512:
-  metadata.gz: 30d113b3edff4cc76192203e038606d62cdb306fc4baf386b40ef60b6bef1eb6638d5b26c2a2f0496ca990c96a12ae902b8d92c55babcff74de385c24bf99c39
-  data.tar.gz: 58f34dc9b1d67dceb2c229f8f53fce8cf6f309a8625bbe267166840482f77001c511306cada76212b5f7022d6ed1fcffbf05d2d675ae51be186ff26bed16bce9
+  metadata.gz: d6e010dd7e59da9bc9041079e58e75b4c6de45dfb4628489023720d637c963d773a1e98890e5ed83c133ae38608cd3f2454cb64f44551a93e93a4ed91a031215
+  data.tar.gz: 7f51e98348f6f5588b2d57bbf6ad998c63d84a36aab3b9fd4de953766c70b968c779aa7ceeb5d3f338cab7c30924a20f39f861810756ad58d3a18f51b2e7b767

data/lib/array.rb

@@ -0,0 +1,28 @@
+# Reopen Array to add some handy capabilities idoimatic to Ruby.
+class Array
+
+  ##
+  # Take an Array of Results and convert them to a single Result whose value is
+  # an Array of Ok or Err values. Ok Results will have only Ok values, and Err
+  # Results will have only Err values. A single Err in the input Array will
+  # convert the entire Result into an Err.
+  #
+  # @return [MonadOxide::Result<Array<V>, Array<E>>] A Result whose value is an
+  # array of all of the Oks or Errs in the Array.
+  def into_result()
+    tracker = {
+      oks: [],
+      errs: [],
+    }
+    self.each do |result|
+      result.match({
+        MonadOxide::Ok => ->(x) { tracker[:oks].push(x) },
+        MonadOxide::Err => ->(e) { tracker[:errs].push(e) },
+      })
+    end
+    tracker[:errs].empty?() ?
+      MonadOxide.ok(tracker[:oks]) :
+      MonadOxide.err(tracker[:errs])
+  end
+
+end

data/lib/err.rb

@@ -6,6 +6,33 @@ module MonadOxide
   # Any methods in Result that would process a successful Result (Ok) will fall
   # through with Err instances.
   class Err < Result
+
+    ##
+    # Add a backtrace to an Exception, or just pass long whatever was given.
+    # The Exception is mutated in the process.
+    #
+    # Ruby Exceptions do not come with a backtrace. During the act of raising
+    # an Exception, that Exception is granted a backtrace. So any kind of
+    # `Exception.new()' invocations will have a `nil' value for `backtrace()'.
+    # To get around this, we can simply raise the Exception here, and then we
+    # get the backtrace we want.
+    #
+    # On a cursory search, this is not documented behavior.
+    #
+    # @param x [Exception|T] The potential Exception to add a backtrace to, if
+    #                        it is missing a backtrace.
+    # @returns [Exception|T] The passed value, with a backtrace added if it is
+    #                        an Exception.
+    def self.backtrace_fix(x)
+      if x.kind_of?(Exception) && x.backtrace.nil?
+        raise x
+      else
+        x
+      end
+    rescue => e
+      e
+    end
+
     ##
     # Create an Err.
     #
@@ -15,29 +42,16 @@ module MonadOxide
     # causes the backtrace to be populated and will be availabl to any cosumers
     # automatically.
     #
-    # @param data [Exception] This must be an Exception it will result in a
-    #                         TypeError.
-    # @raise [TypeError] Is raised if the input is not an Exception.
+    # @param data [T|Array<T>] The data for this Err.  If it is an Exception or
+    #                          an Array of Exceptions, this will add a backtrace
+    #                          if it the Exceptions do not have backtraces
+    #                          already.  Exception it will result in a
+    #                          TypeError.
     def initialize(data)
-      if !data.kind_of?(Exception)
-        raise TypeError.new("#{data.inspect} is not an Exception.")
+      if data.kind_of?(Array)
+        @data = data.map(&self.class.method(:backtrace_fix))
       else
-        begin
-          # Ruby Exceptions do not come with a backtrace. During the act of
-          # raising an Exception, that Exception is granted a backtrace. So any
-          # kind of `Exception.new()' invocations will have a `nil' value for
-          # `backtrace()'. To get around this, we can simply raise the Exception
-          # here, and then we get the backtrace we want.
-          #
-          # On a cursory search, this is not documented behavior.
-          if data.backtrace.nil?
-            raise data
-          else
-            @data = data
-          end
-        rescue => e
-          @data = e
-        end
+        @data = self.class.backtrace_fix(data)
       end
     end
 
@@ -151,5 +165,6 @@ module MonadOxide
     def unwrap_err()
       @data
     end
+
   end
 end

data/lib/monad-oxide.rb

@@ -1,6 +1,7 @@
 require_relative './result'
 require_relative './err'
 require_relative './ok'
+require_relative './array'
 require_relative './version'
 
 ##

data/lib/result.rb

@@ -99,6 +99,34 @@ module MonadOxide
       Err.new(ResultMethodNotImplementedError.new())
     end
 
+    ##
+    # In the case of `Err', applies `f' or the block over the `Exception' and
+    # returns the same `Err'. No changes are applied. This is ideal for logging.
+    # For `Ok', this method falls through. Exceptions raised during these
+    # transformations will return an `Err' with the Exception.
+    # @param f [Proc<A, B>] The function to call. Could be a block instead.
+    #          Takes an [A=Exception] the return is ignored.
+    # @yield Will yield a block that takes an A the return is ignored. Same as
+    #        `f' parameter.
+    # @return [Result<A>] returns self.
+    def inspect_err(f=nil, &block)
+      Err.new(ResultMethodNotImplementedError.new())
+    end
+
+    ##
+    # In the case of `Ok', applies `f' or the block over the data and returns
+    # the same `Ok'. No changes are applied. This is ideal for logging.  For
+    # `Err', this method falls through. Exceptions raised during these
+    # transformations will return an `Err' with the Exception.
+    # @param f [Proc<A, B>] The function to call. Could be a block instead.
+    #          Takes an [A] the return is ignored.
+    # @yield Will yield a block that takes an A the return is ignored. Same as
+    #        `f' parameter.
+    # @return [Result<A>] returns self.
+    def inspect_ok(f=nil, &block)
+      Err.new(ResultMethodNotImplementedError.new())
+    end
+
     ##
     # In the case of `Ok', applies `f' or the block over the data and returns a
     # new new `Ok' with the returned value. For `Err', this method falls
@@ -132,31 +160,23 @@ module MonadOxide
     end
 
     ##
-    # In the case of `Err', applies `f' or the block over the `Exception' and
-    # returns the same `Err'. No changes are applied. This is ideal for logging.
-    # For `Ok', this method falls through. Exceptions raised during these
-    # transformations will return an `Err' with the Exception.
-    # @param f [Proc<A, B>] The function to call. Could be a block instead.
-    #          Takes an [A=Exception] the return is ignored.
-    # @yield Will yield a block that takes an A the return is ignored. Same as
-    #        `f' parameter.
-    # @return [Result<A>] returns self.
-    def inspect_err(f=nil, &block)
-      Err.new(ResultMethodNotImplementedError.new())
-    end
-
-    ##
-    # In the case of `Ok', applies `f' or the block over the data and returns
-    # the same `Ok'. No changes are applied. This is ideal for logging.  For
-    # `Err', this method falls through. Exceptions raised during these
-    # transformations will return an `Err' with the Exception.
-    # @param f [Proc<A, B>] The function to call. Could be a block instead.
-    #          Takes an [A] the return is ignored.
-    # @yield Will yield a block that takes an A the return is ignored. Same as
-    #        `f' parameter.
-    # @return [Result<A>] returns self.
-    def inspect_ok(f=nil, &block)
-      Err.new(ResultMethodNotImplementedError.new())
+    # Use pattern matching to work with both Ok and Err variants. This is useful
+    # when it is desirable to have both variants handled in the same location.
+    # It can also be useful when either variant can coerced into a non-Result
+    # type.
+    #
+    # Ruby has no built-in pattern matching, but the next best thing is a Hash
+    # using the Result classes themselves as the keys.
+    #
+    # Tests for this are found in Ok and Err's tests.
+    #
+    # @param matcher [Hash<Class, Proc<T | E, R>] matcher The matcher to match
+    # upon.
+    # @option matcher [Proc] MonadOxide::Ok The branch to execute for Ok.
+    # @option matcher [Proc] MonadOxide::Err The branch to execute for Err.
+    # @return [R] The return value of the executed Proc.
+    def match(matcher)
+      matcher[self.class].call(@data)
     end
 
     ##

data/lib/version.rb

@@ -3,5 +3,5 @@ module MonadOxide
   # This version is locked to 0.x.0 because semver is a lie and this project
   # uses CICD to push new versions. Any commits that appear on main will result
   # in a new version of the gem created and published.
-  VERSION='0.3.0'
+  VERSION='0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monad-oxide
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Logan Barnett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-25 00:00:00.000000000 Z
+date: 2023-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: org-ruby
@@ -75,6 +75,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/array.rb
 - lib/err.rb
 - lib/monad-oxide.rb
 - lib/ok.rb
@@ -100,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.26
 signing_key: 
 specification_version: 4
 summary: Ruby port of Rust's Result and Option.