monad-oxide 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f39d28705c0ba38e6cdaff1b0dfbd12468f7f8529d16d51b89b9583d5ddc484d
-  data.tar.gz: 245f18cb7377cfe3ff4ecee26d553d1bd695daa01ba0919a73218520ce23e980
+  metadata.gz: 5ef9afae9321a36b11f966859ba1e031288d0c532f758e4f9b7063234ab8fe2a
+  data.tar.gz: 9c1e4528650956209644f9095db174b510a4277e79c96d11f137ef1bb1ed708c
 SHA512:
-  metadata.gz: a0c170fddf3095ffa876701fdaa799b5385055098e583ad1e82400c183204a9b5801558ead2dd265c8f9fe5eaca42c0e100ee15f9f76adab8e2e7f309fea5aa9
-  data.tar.gz: 4c82cfb3ae795077dfb14b62e3e9c663edd44cca6fd0b35b24e23d84f4b3fef53f02a0439e668eb0856c2956608e5fe150fe2ab562178e97b843f8aa1139763a
+  metadata.gz: 5270dd501e132f3396184508e05a1dc41e8ff119689a5a44a4b6c27bfcc4b23d5db18d53f8b5cdd68dc1915debe134ac27c8516fe143d165ba023414dbbc3d6f
+  data.tar.gz: 7badd118397b1bddc5a5c65b2e23f2c87e57d3c1ac10f774ee6863f3116aed9923f21d43693dbb1e4402128cd5c32e1640a7a8071c2083d29cfcdf977116ac9f

data/lib/monad-oxide.rb

@@ -4,6 +4,9 @@ require_relative './ok'
 require_relative './either'
 require_relative './left'
 require_relative './right'
+require_relative './option'
+require_relative './some'
+require_relative './none'
 require_relative './array'
 require_relative './version'
 
@@ -11,6 +14,7 @@ require_relative './version'
 # The top level module for the monad-oxide library. Of interest, @see `Result',
 # @see `Err', and @see `Ok'.
 module MonadOxide
+
   module_function
 
   ##
@@ -25,6 +29,10 @@ module MonadOxide
     MonadOxide::Left.new(data)
   end
 
+  def none()
+    MonadOxide::None.new()
+  end
+
   ##
   # Create an `Ok' as a conveniece method.
   # @param data [Object] The inner data for this `Ok'.
@@ -33,8 +41,16 @@ module MonadOxide
     MonadOxide::Ok.new(data)
   end
 
+  def option(data)
+    data.nil?() ? none() : some(data)
+  end
+
   def right(data)
     MonadOxide::Right.new(data)
   end
 
+  def some(data)
+    MonadOxide::Some.new(data)
+  end
+
 end

data/lib/none.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative './option'
+
+module MonadOxide
+
+  ##
+  # `None' represents the absence of a value in an `Option'.
+  #
+  # Any methods in Option that would process a present value (Some) will fall
+  # through with None instances.
+  class None < Option
+
+    ##
+    # Create a None.
+    def initialize()
+    end
+
+    ##
+    # Falls through. @see Option#and_then for how this is handled in either
+    # Option case, and @see Some#and_then for how this is handled in the Some
+    # case.
+    # @param f [Proc] Optional Proc - ignored.
+    # @yield An ignored block.
+    # @return [None] This None.
+    def and_then(f=nil, &block)
+      self
+    end
+
+    ##
+    # Falls through. @see Option#inspect_some for how this is handled in
+    # either Option case, and @see Some#inspect_some for how this is handled
+    # in the Some case.
+    # @param f [Proc] Optional Proc - ignored.
+    # @yield An ignored block.
+    # @return [None] This None.
+    def inspect_some(f=nil, &block)
+      self
+    end
+
+    ##
+    # Applies `f' or the block and returns the same `None'. No changes are
+    # applied. This is ideal for logging.
+    # @param f [Proc<B>] The function to call. Could be a block instead. Takes
+    #          nothing, the return is ignored.
+    # @yield Will yield a block that takes nothing, the return is ignored.
+    #        Same as `f' parameter.
+    # @return [Option] returns self.
+    def inspect_none(f=nil, &block)
+      (f || block).call()
+      self
+    end
+
+    ##
+    # Falls through. @see Option#map for how this is handled in either
+    # Option case, and @see Some#map for how this is handled in the Some
+    # case.
+    # @param f [Proc] Optional Proc - ignored.
+    # @yield An ignored block.
+    # @return [None] This None.
+    def map(f=nil, &block)
+      self
+    end
+
+    ##
+    # Applies `f' or the block and returns a new `Option' with the returned
+    # value.
+    # @param f [Proc<B>] The function to call. Could be a block instead. Takes
+    #          nothing and returns a B.
+    # @yield Will yield a block that takes nothing and returns a B. Same as
+    #        `f' parameter.
+    # @return [Option<B>] A new `Option<B>' whose `B' is the return of `f' or
+    #         the block.
+    def map_none(f=nil, &block)
+      Some.new((f || block).call())
+    end
+
+    ##
+    # Identifies that this is a `None'.
+    # For counterparts:
+    # @see MonadOxide::Some#some?
+    # @see MonadOxide::Some#none?
+    # @see MonadOxide::None#some?
+    # @return [Boolean] `true` because this is a `None'.
+    def none?()
+      true
+    end
+
+    ##
+    # Invokes `f' or the block and returns the Option returned from that. The
+    # return type is enforced.
+    # @param f [Proc<Option<B>>] The function to call. Could be a block
+    #          instead. Takes nothing and must return a [Option<B>].
+    # @yield Will yield a block that takes nothing and returns a Option<B>.
+    #        Same as `f' parameter.
+    # @return [Some<B> | None] A new Option from `f' or the block. If `f'
+    #         returns a non-Option, this will raise
+    #         `OptionReturnExpectedError'.
+    def or_else(f=nil, &block)
+      option = (f || block).call()
+      if !option.kind_of?(Option)
+        raise OptionReturnExpectedError.new(option)
+      else
+        option
+      end
+    end
+
+    ##
+    # Identifies that this is not a `Some'.
+    # For counterparts:
+    # @see MonadOxide::Some#some?
+    # @see MonadOxide::Some#none?
+    # @see MonadOxide::None#none?
+    # @return [Boolean] `false` because this is not a `Some'.
+    def some?()
+      false
+    end
+
+    ##
+    # Dangerously try to access the `Option' data. If this is a `None', an
+    # exception will be raised. It is recommended to use this for tests only.
+    # @return [A] The inner data of this `Option'.
+    def unwrap()
+      raise UnwrapError.new(
+        "#{self.class} could not be unwrapped as a Some.",
+      )
+    end
+
+    ##
+    # Dangerously access the `None' data. If this is a `Some', an exception
+    # will be raised. It is recommended to use this for tests only.
+    # @return [nil] Returns nil for `None'.
+    def unwrap_none()
+      nil
+    end
+
+  end
+
+end

data/lib/option.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+################################################################################
+# An Option represents a value that may or may not be present.  Some languages
+# also calls this a Maybe.  This is represented by two subclasses: Some and
+# None.  Some represents a present value, and None means no value is present.
+# It is advantageous to use this over `nil` because, unlike `nil`, you can
+# compose over `Option`.
+################################################################################
+
+module MonadOxide
+
+  ##
+  # Thie Exception signals an area under construction, or somehow the consumer
+  # wound up with a base class instance and not one of its
+  # subclasses. Implementors of new methods on subclasses should
+  # create methods on the base class as well which immediately raise this
+  # `Exception'.
+  class OptionMethodNotImplementedError < 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 OptionReturnExpectedError < 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("A Result was expected but got #{data.inspect}.")
+      data = @data
+    end
+    attr_reader(:data)
+  end
+
+  ##
+  # An Option is a chainable series of sequential transformations. The Option
+  # structure contains a `Some<A> | None`. This is the central location
+  # for documentation between both `Some' and `None'. It is best to think of
+  # any given `Some' or `None' as an `Option' instead. All methods on `Some'
+  # are present on `None' and vice versa. This way we can interchange one for
+  # the other during virtually any call.
+  #
+  # This is a base-class only, and you should never see instances of these in
+  # the wild.
+  class Option
+
+    def initialize(data)
+      raise NoMethodError.new('Do not use Option directly. See Some and None.')
+    end
+
+    ##
+    # Determine if this is a MonadOxide::Some.
+    # @return [Boolean] `true` if this is a MonadOxide::Some, `false`
+    # otherwise.
+    def some?()
+      false
+    end
+
+    ##
+    # Determine if this is a MonadOxide::None.
+    # @return [Boolean] `true` if this is a MonadOxide::None, `false`
+    # otherwise.
+    def none?()
+      false
+    end
+
+    ##
+    # In the case of `Some', applies `f' or the block over the data and
+    # returns a new `Some' with the returned value. For `None', this method
+    # falls through.
+    # @param f [Proc<A, B>] The function to call. Could be a block instead.
+    #          Takes an [A=Object] and returns a B.
+    # @yield Will yield a block that takes an A and returns a B. Same as `f'
+    #        parameter.
+    # @return [Option<B>] A new `Option<B>' whose `B' is the return of `f' or
+    #         the block for `Some'. For `None', returns self.
+    def map(f=nil, &block)
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # In the case of `None', applies `f' or the block and returns a new
+    # `Option' with the returned value. For `Some', this method falls through.
+    # @param f [Proc<B>] The function to call. Could be a block instead. Takes
+    #          nothing and returns a B.
+    # @yield Will yield a block that takes nothing and returns a B. Same as
+    #        `f' parameter.
+    # @return [Option<B>] A new `Option<B>' whose `B' is the return of `f' or
+    #         the block for `None'. For `Some', returns self.
+    def map_none(f=nil, &block)
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # In the case of `Some', applies `f' or the block over the data and
+    # returns the same `Some'. No changes are applied. This is ideal for
+    # logging. For `None', this method falls through.
+    # @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 [Option<A>] returns self.
+    def inspect_some(f=nil, &block)
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # In the case of `None', applies `f' or the block and returns the same
+    # `None'. No changes are applied. This is ideal for logging. For `Some',
+    # this method falls through.
+    # @param f [Proc<B>] The function to call. Could be a block instead. Takes
+    #          nothing, the return is ignored.
+    # @yield Will yield a block that takes nothing, the return is ignored.
+    #        Same as `f' parameter.
+    # @return [Option] returns self.
+    def inspect_none(f=nil, &block)
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # For `Some', invokes `f' or the block with the data and returns the
+    # Option returned from that.
+    #
+    # For `None', returns itself and the function/block are ignored.
+    #
+    # This method is used for control flow based on `Option' values.
+    #
+    # `and_then' is desirable for chaining together other Option based
+    # operations, or doing transformations where flipping from a `Some' to a
+    # `None' is desired. In cases where there is little/no risk of a `None'
+    # state, @see Option#map.
+    #
+    # The `None' equivalent operation is @see Option#or_else.
+    #
+    # The return type is enforced.
+    #
+    # @param f [Proc<A, Option<B>>] The function to call. Could be a block
+    #          instead. Takes an [A=Object] and must return a [Option<B>].
+    # @yield Will yield a block that takes an A and returns a Option<B>. Same
+    #        as `f' parameter.
+    # @return [Some<B> | None] A new Option from `f' or the block. If `f'
+    #         returns a non-Option, this will raise
+    #         `OptionReturnExpectedError'.
+    def and_then(f=nil, &block)
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # For `None', invokes `f' or the block and returns the Option returned
+    # from that.
+    #
+    # For `Some', returns itself and the function/block are ignored.
+    #
+    # This method is used for control flow based on `Option' values.
+    #
+    # `or_else' is desirable for chaining together other Option based
+    # operations, or doing transformations where flipping from a `None' to a
+    # `Some' is desired.
+    #
+    # The `Some' equivalent operation is @see Option#and_then.
+    #
+    # The return type is enforced.
+    #
+    # @param f [Proc<Option<B>>] The function to call. Could be a block
+    #          instead. Takes nothing and must return a [Option<B>].
+    # @yield Will yield a block that takes nothing and returns a Option<B>.
+    #        Same as `f' parameter.
+    # @return [Some<B> | None] A new Option from `f' or the block. If `f'
+    #         returns a non-Option, this will raise
+    #         `OptionReturnExpectedError'.
+    def or_else(f=nil, &block)
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # Dangerously access the `Option' data. If this is a `None', an exception
+    # will be raised. It is recommended to use this for tests only.
+    # @raise [UnwrapError] if called on a `None'.
+    # @return [A] - The inner data of this `Some'.
+    def unwrap()
+      raise OptionMethodNotImplementedError.new()
+    end
+
+    ##
+    # Dangerously access the `Option' data. If this is a `Some', an exception
+    # will be raised. It is recommended to use this for tests only.
+    # @raise [UnwrapError] if called on a `Some'.
+    # @return [nil] - Returns nil for `None'.
+    def unwrap_none()
+      raise OptionMethodNotImplementedError.new()
+    end
+
+  end
+
+end

data/lib/result.rb

@@ -58,6 +58,28 @@ module MonadOxide
     #   protected :new
     # end
 
+    class << self
+
+      ##
+      # Convenience for executing arbitrary code and coercing it to a Result.
+      # Any exceptions raised coerce it into an Err, and the return value is the
+      # value for the Ok.
+      # @param f [Proc<Result<A>>] The function to call. Could be a block
+      #          instead. Takes no arguments and could return any [Object].
+      # @yield Will yield a block that takes no arguments A and returns a
+      #        [Object]. Same as `f' parameter.
+      # @return [MonadOxide::Result<A, E>] An Ok if there are no exceptions
+      # raised, and an Err with the exception if any exception is raised.
+      def try(f=nil, &block)
+        begin
+          MonadOxide.ok((f || block).call())
+        rescue => e
+          MonadOxide.err(e)
+        end
+      end
+
+    end
+
     def initialize(data)
       raise NoMethodError.new('Do not use Result directly. See Ok and Err.')
     end

data/lib/some.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative './option'
+require_relative './error'
+
+module MonadOxide
+
+  ##
+  # `Some' represents a present value in an `Option'. For most operations,
+  # `Some' will perform some operation.
+  class Some < Option
+
+    ##
+    # Constructs a `Some' with the data provided.
+    # @param data [Object] The inner data this Option encapsulates.
+    def initialize(data)
+      @data = data
+    end
+
+    ##
+    # Invokes `f' or the block with the data and returns the Option returned
+    # from that. The return type is enforced.
+    # @param f [Proc<A, Option<B>>] The function to call. Could be a block
+    #          instead. Takes an [A=Object] and must return a [Option<B>].
+    # @yield Will yield a block that takes an A and returns a Option<B>. Same
+    #        as `f' parameter.
+    # @return [Some<B> | None] A new Option from `f' or the block. If `f'
+    #         returns a non-Option, this will raise
+    #         `OptionReturnExpectedError'.
+    def and_then(f=nil, &block)
+      option = (f || block).call(@data)
+      if !option.kind_of?(Option)
+        raise OptionReturnExpectedError.new(option)
+      else
+        option
+      end
+    end
+
+    ##
+    # Applies `f' or the block over the data and returns the same `Some'. No
+    # changes are applied. This is ideal for logging.
+    # @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 [Option<A>] returns self.
+    def inspect_some(f=nil, &block)
+      (f || block).call(@data)
+      self
+    end
+
+    ##
+    # Falls through. @see Option#inspect_none for how this is handled in
+    # either Option case, and @see None#inspect_none for how this is handled
+    # in the None case.
+    # @param f [Proc] Optional Proc - ignored.
+    # @yield An ignored block.
+    # @return [Some] This Some.
+    def inspect_none(f=nil, &block)
+      self
+    end
+
+    ##
+    # Applies `f' or the block over the data and returns a new `Some' 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.
+    # @yield Will yield a block that takes an A and returns a B. Same as `f'
+    #        parameter.
+    # @return [Option<B>] A new `Some<B>' whose `B' is the return of `f' or
+    #         the block.
+    def map(f=nil, &block)
+      self.class.new((f || block).call(@data))
+    end
+
+    ##
+    # This is a no-op for Some. @see None#map_none.
+    # @param f [Proc<A, B>] A dummy function. Not used.
+    # @yield A dummy block. Not used.
+    # @return [Option<A>] This `Some'.
+    def map_none(f=nil, &block)
+      self
+    end
+
+    ##
+    # Identifies that this is not a `None'.
+    # For counterparts:
+    # @see MonadOxide::Some#some?
+    # @see MonadOxide::None#some?
+    # @see MonadOxide::None#none?
+    # @return [Boolean] `false` because this is not a `None'.
+    def none?()
+      false
+    end
+
+    ##
+    # The None equivalent to Some#and_then. This is a no-op for Some. @see
+    # None#or_else.
+    # @param f [Proc<A, B>] A dummy function. Not used.
+    # @yield A dummy block. Not used.
+    # @return [Option<A>] This `Some'.
+    def or_else(f=nil, &block)
+      self
+    end
+
+    ##
+    # Identifies that this is a `Some'.
+    # For counterparts:
+    # @see MonadOxide::Some#none?
+    # @see MonadOxide::None#some?
+    # @see MonadOxide::None#none?
+    # @return [Boolean] `true` because this is a `Some'.
+    def some?()
+      true
+    end
+
+    ##
+    # Dangerously access the `Some' data. If this is a `None', an exception
+    # will be raised. It is recommended to use this for tests only.
+    # @return [A] The inner data of this `Some'.
+    def unwrap()
+      @data
+    end
+
+    ##
+    # Dangerously access the `None' data. If this is a `Some', an exception
+    # will be raised. It is recommended to use this for tests only.
+    # @return [nil] Returns nil for `None'.
+    def unwrap_none()
+      raise UnwrapError.new(
+        <<~EOE
+          #{self.class} with #{@data.inspect()} could not be unwrapped as a
+          None.
+        EOE
+      )
+    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.13.0'
+  VERSION='0.15.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monad-oxide
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Logan Barnett
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-06 00:00:00.000000000 Z
+date: 2025-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: org-ruby
@@ -81,9 +81,12 @@ files:
 - lib/error.rb
 - lib/left.rb
 - lib/monad-oxide.rb
+- lib/none.rb
 - lib/ok.rb
+- lib/option.rb
 - lib/result.rb
 - lib/right.rb
+- lib/some.rb
 - lib/version.rb
 homepage:
 licenses: