monad-oxide 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0be7d626dfbb5f8398d3b3ac58c4228bc28323fc0d64d74c4cd6d7e4f5966698
-  data.tar.gz: fed978afd4d3ea108a8ab1fece39379573ade7bab1ae167c92ea9a6ca8bb3836
+  metadata.gz: f39d28705c0ba38e6cdaff1b0dfbd12468f7f8529d16d51b89b9583d5ddc484d
+  data.tar.gz: 245f18cb7377cfe3ff4ecee26d553d1bd695daa01ba0919a73218520ce23e980
 SHA512:
-  metadata.gz: 90a2f66f1e4bcd4f08a39c96aa7c9b2d65dd7cdc5c92a9e7f3cb7660f00d64bae5645250fcb25fc9b4688b8d7bece8e4ceaa470de634ac868db03b4a025f1871
-  data.tar.gz: 9b64b9ad89870629f44a593429e1f43b70ee04124e139ce334db65acf805ccb436c88992846eee80d09baf1c97a6f60bdf660382aa318b1042b05c742a3757c3
+  metadata.gz: a0c170fddf3095ffa876701fdaa799b5385055098e583ad1e82400c183204a9b5801558ead2dd265c8f9fe5eaca42c0e100ee15f9f76adab8e2e7f309fea5aa9
+  data.tar.gz: 4c82cfb3ae795077dfb14b62e3e9c663edd44cca6fd0b35b24e23d84f4b3fef53f02a0439e668eb0856c2956608e5fe150fe2ab562178e97b843f8aa1139763a

data/lib/either.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+################################################################################
+# Provide an Either type (either one thing or another thing).  Either represents
+# this with a Left or a Right.  The notable difference is Either doesn't assume
+# one of the branches must be some kind of error - in fact no branch of Either
+# has any preference to Left or Right.
+#
+# This is not part of Rust's standard library but it fits well with the monadic
+# operations that Rust has with Result and Option.  This particular
+# implementation is a port from the Either library for Rust
+# (https://docs.rs/either/latest/either/enum.Either.html).
+#
+# Be mindful that an Either can raise exceptions if errors are present in its
+# calls.  Since Either is not strictly compatible with Result, we cannot safely
+# convert some operation to a Result implicitly.
+################################################################################
+
+require_relative './error'
+
+module MonadOxide
+
+  ##
+  # Thie Exception signals an area under construction, or somehow the consumer
+  # wound up with a `Result' and not one of its subclasses (@see Ok and @see
+  # Err). Implementors of new methods on `Ok' and `Err' should create methods on
+  # `Result' as well which immediately raise this `Exception'.
+  class EitherMethodNotImplementedError < MonadOxideError; end
+
+  ##
+  # This `Exception' is produced when a method that expects the function or
+  # block to provide a `Result' but was given something else. Generally this
+  # Exception is not raised, but instead converts the Result into a an Err.
+  # Example methods with this behavior are Result#and_then and Result#or_else.
+  class EitherReturnExpectedError < MonadOxideError
+    ##
+    # The transformation expected a `Result' but got something else.
+    # @param data [Object] Whatever we got that wasn't a `Result'.
+    def initialize(data)
+      super("An Either was expected but got #{data.inspect()}.")
+      data = @data
+    end
+    attr_reader(:data)
+  end
+
+  class Either
+
+    def initialize(_data)
+      raise NoMethodError.new('Do not use Either directly. See Left and Right.')
+    end
+
+    ##
+    # Use pattern matching to work with both Left and Right 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 Either classes themselves as the keys.
+    #
+    # Tests for this are found in the tests of the Left and Right classes.
+    #
+    # @param matcher [Hash<Class, Proc<T | E, R>] matcher The matcher to match
+    # upon.
+    # @option matcher [Proc] MonadOxide::Left The branch to execute for Left.
+    # @option matcher [Proc] MonadOxide::Right The branch to execute for Right.
+    # @return [R] The return value of the executed Proc.
+    def match(matcher)
+      matcher[self.class()].call(@data)
+    end
+
+  end
+
+end

data/lib/error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+################################################################################
+# Houses generic exception types.
+#
+# Not to be mistaken with err.rb for MonadOxide::Err.
+################################################################################
+module MonadOxide
+
+  ##
+  # All errors in monad-oxide should inherit from this error. This makes it easy
+  # to handle library-wide errors on the consumer side.
+  class MonadOxideError < StandardError; end
+
+  ##
+  # This `Exception' is raised when the consumer makes a dangerous wager
+  # about which state the `Result' is in, and lost. More specifically: An `Ok'
+  # cannot unwrap an Exception, and an `Err' cannot unwrap the `Ok' data.
+  class UnwrapError < MonadOxideError; end
+
+end

data/lib/left.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+################################################################################
+#
+################################################################################
+
+require_relative './error'
+
+module MonadOxide
+
+  ##
+  # `Left' represents an arbitrary branch of Either.  Since Either is supposed
+  # to be unbiased, you can assign any bias you like to Left, though in some
+  # ecosystems (such as Haskell, where this Either is ultimately inspired from),
+  # the Left side is the less common/favorable one, but this is only out of
+  # convention.
+  class Left < Either
+
+    ##
+    # Constructs a `Left' with the data provided.
+    # @param data [Object] The inner data this Either encapsulates.
+    def initialize(data)
+      @data = data
+    end
+
+    ##
+    # Applies `f` or the block over the data and returns the same `Left`.  No
+    # changes are applied.  This is ideal for logging.  @see Either#inspect_left
+    # for a higher level understanding how this works with Eithers in general.
+    # @param f [Proc<A, _>] 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 [Either<A, B>] returns self.
+    def inspect_left(f=nil, &block)
+      (f || block).call(@data)
+      self
+    end
+
+    ##
+    # Falls through. @see Either#inspect_right for how this is handled in the
+    # Either case, and @see Right#inspect_right for how this is handled in the
+    # Right case.
+    # @param f [Proc] Optional Proc - ignored.
+    # @yield An ignored block.
+    # @return [Either] This Either.
+    def inspect_right(f=nil, &block)
+      self
+    end
+
+    ##
+    # Identifies that this is a `Left`.
+    # For counterparts:
+    # @see MonadOxide::Left#right?
+    # @see MonadOxide::Right#left?
+    # @see MonadOxide::Right#right?
+    # @return [Boolean] `true` because this is a `Left`.
+    def left?()
+      true
+    end
+
+    ##
+    # Invokes `f' or the block with the data and returns the Either returned
+    # from that.  The return type is enforced.
+    # @param f [Proc<A, Result<C>>] The function to call. Could be a block
+    #          instead. Takes an [A=Object] and must return a [Either<C, B>].
+    # @yield Will yield a block that takes an A and returns a Either<C>. Same as
+    #        `f' parameter.
+    # @return [Left<C> | Right<C>] A new Result from `f' or the
+    #         block.  If the return value is a non-Either, this this will raise
+    #         `EitherReturnExpectedError'.
+    def left_and_then(f=nil, &block)
+      either = (f || block).call(@data)
+      if either.is_a?(Either)
+        either
+      else
+        raise EitherReturnExpectedError.new(either)
+      end
+    end
+
+
+    ##
+    # Applies `f' or the block over the data and returns a new `Left' with the
+    # returned value.
+    # @param f [Proc<A, C>] The function to call. Could be a block
+    #          instead. Takes an [A=Object] and returns a C.
+    # @yield Will yield a block that takes an A and returns a C. Same as
+    #        `f' parameter.
+    # @return [Either<C, B>] A new `Left<C>' whose `C' is the return of `f' or
+    #         the block.
+    def map_left(f=nil, &block)
+      Left.new((f || block).call(@data))
+    end
+
+    ##
+    # This is a no-op for Left. @see Right#map_right.
+    # @param f [Proc<A, C>] A dummy function. Not used.
+    # @yield A dummy block. Not used.
+    # @return [Either<A, B>] This `Left'.
+    def map_right(f=nil, &block)
+      self
+    end
+
+    ##
+    # Identifies that this is not a `Right`.
+    # For counterparts:
+    # @see MonadOxide::Left#left?
+    # @see MonadOxide::Right#left?
+    # @see MonadOxide::Right#right?
+    # @return [Boolean] `false` because this is not a `Right`.
+    def right?()
+      false
+    end
+
+    ##
+    # The Left equivalent to Right#left_and_then.  This is a no-op for Left.
+    # @see Right#right_and_then.
+    # @param f [Proc<A, B>] A dummy function. Not used.
+    # @yield A dummy block. Not used.
+    # @return [Either<A, B>] This `Either'.
+    def right_and_then(f=nil, &block)
+      self
+    end
+
+    ##
+    # Dangerously access the `Left' data.  If this is a `Right', an
+    # `UnwrapError` will be raised.  It is recommended to use this for tests
+    # only.
+    # @return [A] The inner data of this `Left'.
+    def unwrap_left()
+      @data
+    end
+
+    ##
+    # Dangerously access the `Right' data.  Since this is a `Left', it will
+    # always raise an error.  @see Either#unwrap_right.  It is recommended to
+    # use this for tests only.
+    # @return [E] The data of this `Right'.
+    def unwrap_right()
+      raise UnwrapError.new(
+        <<~EOE
+          #{self.class()} with #{@data.inspect()} could not be unwrapped as a
+          Right.
+        EOE
+      )
+    end
+
+  end
+
+end

data/lib/monad-oxide.rb

@@ -1,6 +1,9 @@
 require_relative './result'
 require_relative './err'
 require_relative './ok'
+require_relative './either'
+require_relative './left'
+require_relative './right'
 require_relative './array'
 require_relative './version'
 
@@ -18,6 +21,10 @@ module MonadOxide
     MonadOxide::Err.new(data)
   end
 
+  def left(data)
+    MonadOxide::Left.new(data)
+  end
+
   ##
   # Create an `Ok' as a conveniece method.
   # @param data [Object] The inner data for this `Ok'.
@@ -25,4 +32,9 @@ module MonadOxide
   def ok(data)
     MonadOxide::Ok.new(data)
   end
+
+  def right(data)
+    MonadOxide::Right.new(data)
+  end
+
 end

data/lib/ok.rb

@@ -1,4 +1,5 @@
 require_relative './result'
+require_relative './error'
 
 module MonadOxide
   ##
@@ -53,7 +54,7 @@ module MonadOxide
 
     ##
     # Falls through. @see Result#inspect_err for how this is handled in either
-    # Result case, and @see Err.inspect_err for how this is handled in the Err
+    # Result case, and @see Err#inspect_err for how this is handled in the Err
     # case.
     # @param f [Proc] Optional Proc - ignored.
     # @yield An ignored block.
@@ -81,7 +82,7 @@ module MonadOxide
     end
 
     ##
-    # Applies `f' or the block over the data and returns a new new `Ok' with the
+    # Applies `f' or the block over the data and returns a new `Ok' with the
     # returned value.
     # @param f [Proc<A, B>] The function to call. Could be a block
     #          instead. Takes an [A=Object] and returns a B.

data/lib/result.rb

@@ -1,8 +1,20 @@
+# frozen_string_literal: true
+################################################################################
+# A monadic way of handling error based flow.
+# A Result is a semi-abstract class, whose implementors are Ok or Err.  Ok
+# carries some data and represents a success case.  Err carries an error and
+# represents a failure case.
+
+# Most methods on Result will follow a success or error "track".  This means an
+# Ok will execute all of the success methods, such as inspect_ok, map, and
+# and_then.  Err will execute error methods, such as inspect_err, map_err, and
+# or_else.  In cases where the method doesn't match the state of the Result
+# (Ok/Err), they return self, which also means they just fall through.
+################################################################################
+
+require_relative './error'
+
 module MonadOxide
-  ##
-  # All errors in monad-oxide should inherit from this error. This makes it easy
-  # to handle library-wide errors on the consumer side.
-  class MonadOxideError < StandardError; end
 
   ##
   # Thie Exception signals an area under construction, or somehow the consumer
@@ -27,12 +39,6 @@ module MonadOxide
     attr_reader(:data)
   end
 
-  ##
-  # This `Exception' is raised when the consumer makes a dangerous wager
-  # about which state the `Result' is in, and lost. More specifically: An `Ok'
-  # cannot unwrap an Exception, and an `Err' cannot unwrap the `Ok' data.
-  class UnwrapError < MonadOxideError; end
-
   ##
   # A Result is a chainable series of sequential transformations. The Result
   # structure contains an `Ok<A> | Err<Exception>`. This is the central location

data/lib/right.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+################################################################################
+#
+################################################################################
+
+require_relative './error'
+
+module MonadOxide
+
+  ##
+  # `Right' represents an arbitrary branch of Either.  Since Either is supposed
+  # to be unbiased, you can assign any bias you like to Right, though in some
+  # ecosystems (such as Haskell, where this Either is ultimately inspired from),
+  # the Right side is the more common/favorable one, but this is only out of
+  # convention.
+  class Right < Either
+
+    def initialize(data)
+      @data = data
+    end
+
+    ##
+    # Falls through. @see Either#inspect_left for how this is handled in the
+    # Either case, and @see Left#inspect_left for how this is handled in the
+    # Left case.
+    # @param f [Proc] Optional Proc - ignored.
+    # @yield An ignored block.
+    # @return [Either] This Either.
+    def inspect_left(f=nil, &block)
+      self
+    end
+
+    ##
+    # Applies `f` or the block over the data and returns the same `Right`.  No
+    # changes are applied.  This is ideal for logging.  @see
+    # Either#inspect_right for a higher level understanding how this works with
+    # Eithers in general.
+    # @param f [Proc<A, _>] 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 [Either<A, B>] returns self.
+    def inspect_right(f=nil, &block)
+      (f || block).call(@data)
+      self
+    end
+
+    ##
+    # Identifies that this is not a `Left`.
+    # For counterparts:
+    # @see MonadOxide::Left#left?
+    # @see MonadOxide::Left#right??
+    # @see MonadOxide::Right#right?
+    # @return [Boolean] `false` because this is not a `Left`.
+    def left?()
+      false
+    end
+
+    ##
+    # The Right equivalent to Left#right_and_then.  This is a no-op for Right.
+    # @see Lefft#right_and_then.
+    # @param f [Proc<A, B>] A dummy function. Not used.
+    # @yield A dummy block. Not used.
+    # @return [Either<A, B>] This `Either'.
+    def left_and_then(f=nil, &block)
+      self
+    end
+
+    ##
+    # This is a no-op for Right. @see Left#map_left.
+    # @param f [Proc<A, C>] A dummy function. Not used.
+    # @yield A dummy block. Not used.
+    # @return [Either<A, B>] This `Left'.
+    def map_left(f=nil, &block)
+      self
+    end
+
+    ##
+    # Applies `f' or the block over the data and returns a new `Right' with the
+    # returned value.
+    # @param f [Proc<A, C>] The function to call. Could be a block
+    #          instead. Takes an [A=Object] and returns a C.
+    # @yield Will yield a block that takes an A and returns a C. Same as
+    #        `f' parameter.
+    # @return [Either<A, C>] A new `Right<C>' whose `C' is the return of `f' or
+    #         the block.
+    def map_right(f=nil, &block)
+      Right.new((f || block).call(@data))
+    end
+
+    ##
+    # Identifies that this is a `Right`.
+    # For counterparts:
+    # @see MonadOxide::Left#left?
+    # @see MonadOxide::Left#right?
+    # @see MonadOxide::Right#left?
+    # @return [Boolean] `true` because this is a `Right`.
+    def right?()
+      true
+    end
+
+    ##
+    # Invokes `f' or the block with the data and returns the Either returned
+    # from that.  The return type is enforced.
+    # @param f [Proc<A, Result<C>>] The function to call. Could be a block
+    #          instead. Takes an [A=Object] and must return a [Either<C, B>].
+    # @yield Will yield a block that takes an A and returns a Either<C>. Same as
+    #        `f' parameter.
+    # @return [Left<C> | Right<C>] A new Result from `f' or the
+    #         block.  If the return value is a non-Either, this this will raise
+    #         `EitherReturnExpectedError'.
+    def right_and_then(f=nil, &block)
+      either = (f || block).call(@data)
+      if either.is_a?(Either)
+        either
+      else
+        raise EitherReturnExpectedError.new(either)
+      end
+    end
+
+    ##
+    # Dangerously access the `Left' data.  Since this is a `Right', it will
+    # always raise an error.  @see Either#unwrap_left.  It is recommended to use
+    # this for tests only.
+    # @return [A] The inner data of this `Right'.
+    def unwrap_left()
+      raise UnwrapError.new(
+        <<~EOE
+        #{self.class()} with #{@data.inspect()} could not be unwrapped as a
+        Left.
+        EOE
+      )
+    end
+
+    ##
+    # Dangerously access the `Right' data.  If this is a `Left', an
+    # `UnwrapError` will be raised.  It is recommended to use this for tests
+    # only.
+    # @return [A] The inner data of this `Right'.
+    def unwrap_right()
+      @data
+    end
+
+  end
+
+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.12.0'
+  VERSION='0.13.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monad-oxide
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Logan Barnett
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-27 00:00:00.000000000 Z
+date: 2025-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: org-ruby
@@ -70,23 +70,27 @@ description: |
   Monad-Oxide is a port of Rust's built-in monads from std, such as Result and
   Option. This enables better reasoning about error handling and possibly missing
   data.
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/array.rb
+- lib/either.rb
 - lib/err.rb
+- lib/error.rb
+- lib/left.rb
 - lib/monad-oxide.rb
 - lib/ok.rb
 - lib/result.rb
+- lib/right.rb
 - lib/version.rb
-homepage: 
+homepage:
 licenses:
 - Apache-2.0
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -102,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.26
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Ruby port of Rust's Result and Option.
 test_files: []