monad-oxide 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f4a3e02d264fe9a27b7e48c58865eacf77db7a083d75d4c6383aa76243d65a9
-  data.tar.gz: f422c2b96a295fa4bcfee050d494c43f8ee721dac43d8e609321cfecf2f0020c
+  metadata.gz: 527a364e877c458b44d2f94cc3d59adace690bbee75e6da602daef77319369e2
+  data.tar.gz: dc568c5996d9dc36ae83cebf34cec5289fe6ea8e319c4ad1dde0aae1231e1e58
 SHA512:
-  metadata.gz: 0c146c13f5d0a6867ec4cd0426c2a765c611c6c71b83bb12a5872ef2adc0fea4fb9845b46c9925d0a731722420d1c603afbbb0e72c3890405790c66c9474e249
-  data.tar.gz: 0732a70394523cfde5269d72ec6581ff7695bce800aea1cdd86e1c78574b81d419aaa8a38fb2dfde7b5e988673493f03261294b48e18ca37e6c1f22bdbd1c67a
+  metadata.gz: 8bc31b055fcff603efff03d5057836be330c031210f77397c169a220777f3acb4ac583aab47b09d320c5bf52b209dac44b16c626d3f66d334a5c24f8e9dc2fa8
+  data.tar.gz: 6d1c32430d663eb3471ff25f0eb42c79249599e131ce866d422bad051c6bb4e6d74221ef59a55714a90216ed640c7d259e649635a22cda4ebf5e7513c89404fe

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,220 @@
+# 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
+
+    ##
+    # Use pattern matching to work with both Some and None 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-Option type.
+    #
+    # Ruby has no built-in pattern matching, but the next best thing is a
+    # Hash using the Option classes themselves as the keys.
+    #
+    # Tests for this are found in Some and None's tests.
+    #
+    # @param matcher [Hash<Class, Proc<T, R>] matcher The matcher to match
+    # upon.
+    # @option matcher [Proc] MonadOxide::Some The branch to execute for Some.
+    # @option matcher [Proc] MonadOxide::None The branch to execute for None.
+    # @return [R] The return value of the executed Proc.
+    def match(matcher)
+      if self.kind_of?(None)
+        matcher[self.class].call()
+      else
+        matcher[self.class].call(@data)
+      end
+    end
+
+  end
+
+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.14.0'
+  VERSION='0.16.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monad-oxide
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Logan Barnett
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-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: