errgonomic 0.7.0 → 0.8.1

data/lib/errgonomic/core_ext/bool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../option'
+require_relative '../result'
+
+# Lift booleans into Option and Result, following Rust's bool: then_some,
+# and ok_or/ok_or_else from nightly. Rust splits the lazy form into `then`,
+# but that name is core Ruby (Kernel#then), so then_some takes either a
+# value or a block. Rust's ok_or returns Result<(), E>; Ruby has no unit
+# type, so Ok carries true.
+class TrueClass
+  # @example
+  #   true.then_some(:hello) # => Some(:hello)
+  #   true.then_some { :hello } # => Some(:hello)
+  #   true.then_some(nil) # => Some(nil)
+  #   true.then_some # => raise Errgonomic::ArgumentError, "then_some takes either a value or a block"
+  def then_some(*args, &block)
+    if args.length == 1 && !block
+      Some(args[0])
+    elsif args.empty? && block
+      Some(block.call)
+    else
+      raise Errgonomic::ArgumentError, 'then_some takes either a value or a block'
+    end
+  end
+
+  # @example
+  #   true.ok_or(:ohno) # => Ok(true)
+  def ok_or(_err)
+    Ok(true)
+  end
+
+  # @example
+  #   true.ok_or_else { :ohno } # => Ok(true)
+  def ok_or_else
+    Ok(true)
+  end
+end
+
+# The false halves of the conversions above.
+class FalseClass
+  # The block is never called; arguments are validated all the same, so a
+  # misuse fails regardless of which way the flag happens to point.
+  #
+  # @example
+  #   false.then_some(:hello) # => None()
+  #   false.then_some { :hello } # => None()
+  #   false.then_some # => raise Errgonomic::ArgumentError, "then_some takes either a value or a block"
+  def then_some(*args, &block)
+    unless (args.length == 1 && !block) || (args.empty? && block)
+      raise Errgonomic::ArgumentError, 'then_some takes either a value or a block'
+    end
+
+    None()
+  end
+
+  # @example
+  #   false.ok_or(:ohno) # => Err(:ohno)
+  def ok_or(err)
+    Err(err)
+  end
+
+  # @example
+  #   false.ok_or_else { :ohno } # => Err(:ohno)
+  def ok_or_else(&block)
+    Err(block.call)
+  end
+end

data/lib/errgonomic/core_ext/hash.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative '../option'
+require_relative '../optional_hash'
+
+# Two additive lookups; no existing Hash behavior changes. This is as deep as
+# the gem reaches into Hash: the wider Ruby ecosystem leans on Hash semantics
+# too heavily to patch them, so richer behavior lives in
+# Errgonomic::OptionalHash instead.
+class Hash
+  # Retrieve the value for a key, wrapped in an Option, following key
+  # presence as Rust's HashMap#get does: a present key with a nil value is
+  # Some(nil); only a missing key is None.
+  #
+  # @example
+  #   h = { color: :blue, shade: nil }
+  #   h.fetch_option(:color) # => Some(:blue)
+  #   h.fetch_option(:shade) # => Some(nil)
+  #   h.fetch_option(:smell) # => None()
+  def fetch_option(key)
+    return None() unless key?(key)
+
+    Some(self[key])
+  end
+
+  # Wrap this hash in an Errgonomic::OptionalHash view. The wrapper reads and
+  # writes this same hash; use its to_h for a detached copy.
+  #
+  # @example
+  #   h = { color: :blue }.into_optional
+  #   h[:color] # => Some(:blue)
+  #   h[:smell] # => None()
+  def into_optional
+    Errgonomic::OptionalHash.new(self)
+  end
+end

data/lib/errgonomic/option.rb

@@ -5,20 +5,65 @@ module Errgonomic
     # The base class for all options. Some and None are subclasses.
     #
     class Any
-      # def method_missing(_name, *_args)
-      #   raise 'do it right noob'
-      # end
-
-      # An option of the same type with an equal inner value is equal.
-      #
-      # Because we're going to monkey patch this into other libraries Rails, we
-      # allow some "pass through" functionality into the inner value of a Some,
-      # such as comparability here.
+      include Comparable
+
+      # Rust spellings we accept but do not advertise: they delegate to the
+      # Ruby-idiomatic predicate and nudge the caller there via stderr.
+      RUST_SPELLINGS = {
+        is_some: :some?,
+        is_none: :none?,
+        is_some_and: :some_and?,
+        is_none_or: :none_or?
+      }.freeze
+
+      # An Option deliberately forwards nothing to its inner value, so a miss
+      # here is almost always someone treating the container as its contents.
+      # Teach the route out instead of leaving a bare NoMethodError. Rust
+      # spellings of the predicates delegate, with a nudge on stderr.
       #
-      # TODO: does None == null?
+      # @example
+      #   begin
+      #     Some(5) + 1
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   Some(5).respond_to?(:+) # => false
+      #   Some(1).is_some_and { |x| x > 0 } # => true
+      #   None().is_none # => true
+      #   Some(5).respond_to?(:is_some) # => true
+      def method_missing(name, *args, &block)
+        if (canonical = RUST_SPELLINGS[name])
+          warn "Errgonomic: `#{name}` is the Rust spelling; prefer `#{canonical}`. Delegating."
+          return public_send(canonical, *args, &block)
+        end
+
+        raise Errgonomic::UnwrappedAccessError.new(<<~MSG, name)
+          undefined method `#{name}' for #{inspect}, an Option, which does not forward methods to its inner value.
+          Reach for a combinator instead:
+            map, and_then, filter: transform the value if present
+            unwrap_or, unwrap_or_else: supply a fallback
+            ok_or, ok_or_else: convert to a Result
+            some_and?, none_or?: test a predicate against the inner value
+          unwrap! and expect! also exist, but are intended for tests rather than application code.
+        MSG
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        RUST_SPELLINGS.key?(name) || super
+      end
+
+      # An Option equals another Option of the same class with an equal inner
+      # value. Anything else, including nil and the raw inner value, is not
+      # equal: quietly false, never an error. Rust rejects Some(5) == 5 at
+      # compile time; Ruby cannot, and raising here would break the many
+      # places Ruby compares heterogeneous operands (Array#include?,
+      # assertion diffs, dirty tracking). Compare Options (opt == Some(5)) or
+      # test the inner value (opt.some_and? { |v| v == 5 }) instead.
       #
-      # strict:
-      #   Some(1) == 1 # => raise Errgonomic::NotComparableError, "Cannot compare Errgonomic::Option::Some with Integer"
+      # None() == nil is likewise false: None is a value that represents
+      # absence, not an absence Ruby can see. (The Rails integration
+      # separately makes None#nil? answer true, as an ActiveRecord
+      # compromise; equality does not follow it.)
       #
       # @example
       #   Some(1) == Some(1) # => true
@@ -34,6 +79,34 @@ module Errgonomic
         value == other.value
       end
 
+      # Hash-based collections (Hash keys, Set, uniq, group_by) use eql? and
+      # hash, not ==. Follow the inner value's own eql? semantics, so Options
+      # behave as keys exactly like their inner values: Some(1) and Some(1.0)
+      # are distinct keys, just as 1 and 1.0 are.
+      #
+      # @example
+      #   Some(5).eql?(Some(5)) # => true
+      #   Some(1).eql?(Some(1.0)) # => false
+      #   None().eql?(None()) # => true
+      #   { Some(5) => 1 }[Some(5)] # => 1
+      #   [Some(1), Some(1), None(), None()].uniq # => [Some(1), None()]
+      def eql?(other)
+        return false if self.class != other.class
+        return true if none?
+
+        value.eql?(other.value)
+      end
+
+      # @example
+      #   Some(5).hash == Some(5).hash # => true
+      #   None().hash == None().hash # => true
+      #   Some(5).hash == None().hash # => false
+      def hash
+        return self.class.hash if none?
+
+        [self.class, value].hash
+      end
+
       # @example
       #   measurement = Errgonomic::Option::Some.new(1)
       #   case measurement
@@ -50,6 +123,28 @@ module Errgonomic
         [Errgonomic::Option::None]
       end
 
+      # Options order like Rust's: None sorts before any Some, and Somes
+      # order by their inner values. Follows Ruby's <=> convention of
+      # returning nil for incomparable operands, whether the other object is
+      # not an Option or the inner values do not themselves compare.
+      #
+      # @example
+      #   (Some(5) <=> Some(6)) # => -1
+      #   (None() <=> Some(5)) # => -1
+      #   (Some(5) <=> None()) # => 1
+      #   (None() <=> None()) # => 0
+      #   (Some(1) <=> Some("x")) # => nil
+      #   (Some(1) <=> 1) # => nil
+      #   [Some(2), None(), Some(1)].sort # => [None(), Some(1), Some(2)]
+      #   [Some(2), Some(1)].min # => Some(1)
+      def <=>(other)
+        return nil unless other.is_a?(Errgonomic::Option::Any)
+        return none? ? 0 : 1 if other.none?
+        return -1 if none?
+
+        value <=> other.value
+      end
+
       # return true if the contained value is Some and the block returns truthy
       #
       # @example
@@ -78,6 +173,135 @@ module Errgonomic
 
       alias none_or? none_or
 
+      # Presence follows the discriminant, not the inner value: Some is
+      # present, None is blank. So Some(false) and Some(nil) are present,
+      # unlike their unwrapped values.
+      #
+      # @example
+      #   Some(1).present? # => true
+      #   Some(false).present? # => true
+      #   Some("").present? # => true
+      #   None().present? # => false
+      def present?
+        some?
+      end
+
+      # @example
+      #   None().blank? # => true
+      #   Some(1).blank? # => false
+      #   Some(nil).blank? # => false
+      def blank?
+        none?
+      end
+
+      # The presence helpers on Object keep their receiver; on an Option that
+      # would hand back the wrapper where the caller asked for a value. Here
+      # the present side unwraps instead, so a name that reads like an
+      # accessor behaves like one. The whole family is soft-deprecated on
+      # Options in favor of the combinators, so each call nudges via stderr,
+      # and the blank side, which has no working call sites to preserve,
+      # teaches rather than guesses at semantics.
+
+      # Returns the inner value of a Some, and raises on a None. Presence
+      # follows the discriminant, so Some(nil) yields nil.
+      #
+      # @param message [String] The error message to raise on a None.
+      # @return [Object] The inner value of a Some.
+      #
+      # @example
+      #   Some("secret").present_or_raise!("no secret") # => "secret"
+      #   Some(nil).present_or_raise!("no secret") # => nil
+      #   None().present_or_raise!("no secret") # => raise Errgonomic::NotPresentError, "no secret"
+      def present_or_raise!(message)
+        presence_nudge('present_or_raise', 'expect!')
+        raise Errgonomic::NotPresentError, message if none?
+
+        value
+      end
+
+      alias present_or_raise present_or_raise!
+
+      # Returns the inner value of a Some, and the given default on a None.
+      # No pedantic type check on the default: this family is deprecated on
+      # Options, and unwrap_or, which the nudge points to, has none either.
+      #
+      # @param default [Object] The value to return on a None.
+      # @return [Object] The inner value of a Some, otherwise the default.
+      #
+      # @example
+      #   Some("secret").present_or("fallback") # => "secret"
+      #   None().present_or("fallback") # => "fallback"
+      def present_or(default)
+        presence_nudge('present_or', 'unwrap_or')
+        return default if none?
+
+        value
+      end
+
+      # Returns the inner value of a Some, and the result of the block on a
+      # None.
+      #
+      # @param block [Proc] The block to call on a None.
+      # @return [Object] The inner value of a Some, otherwise the block's value.
+      #
+      # @example
+      #   Some("secret").present_or_else { "fallback" } # => "secret"
+      #   None().present_or_else { "fallback" } # => "fallback"
+      def present_or_else(&block)
+        presence_nudge('present_or_else', 'unwrap_or_else')
+        return block.call if none?
+
+        value
+      end
+
+      # Returns the inner value of a Some, and nil on a None, so the Rails
+      # +presence || default+ idiom reaches the value rather than the wrapper.
+      #
+      # @return [Object, nil] The inner value of a Some, otherwise nil.
+      #
+      # @example
+      #   Some("secret").presence # => "secret"
+      #   None().presence # => nil
+      #   None().presence || "fallback" # => "fallback"
+      def presence
+        presence_nudge('presence', 'unwrap_or(nil)')
+        return nil if none?
+
+        value
+      end
+
+      # @example the blank side of the presence family teaches the combinators
+      #   begin
+      #     None().blank_or("x")
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      def blank_or(_default)
+        raise_blank_side_teaching(:blank_or)
+      end
+
+      # @example
+      #   begin
+      #     Some(1).blank_or_else { :x }
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      def blank_or_else(&_block)
+        raise_blank_side_teaching(:blank_or_else)
+      end
+
+      # @example
+      #   begin
+      #     None().blank_or_raise!("msg")
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      def blank_or_raise!(_message)
+        raise_blank_side_teaching(:blank_or_raise!)
+      end
+
+      alias blank_or_raise blank_or_raise!
+
       # return an Array with the contained value, if any
       # @example
       #   Some(1).to_a # => [1]
@@ -119,16 +343,6 @@ module Errgonomic
         value
       end
 
-      # # returns the inner value if present, else returns the default value
-      # # @example
-      # #   Some(1).unwrap_or(2) # => 1
-      # #   None().unwrap_or(2) # => 2
-      # def unwrap_or_default
-      #   self.class.respond_to?(:default) or raise
-      #   return self.class.default if none?
-      #   value
-      # end
-
       # returns the inner value if present, else returns the result of the
       # provided block
       # @example
@@ -342,14 +556,77 @@ module Errgonomic
         raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Option'
       end
 
-      # filter
-      # xor
-      # insert
-      # get_or_insert
-      # get_or_insert_with
-      # take
-      # take_if
-      # replace
+      # pp uses its own object dump unless told otherwise; keep it consistent
+      # with inspect.
+      def pretty_print(pp)
+        pp.text(inspect)
+      end
+
+      # Return self if the predicate is truthy for the inner value, else None.
+      # None passes through.
+      #
+      # @example
+      #   Some(1).filter(&:odd?) # => Some(1)
+      #   Some(2).filter(&:odd?) # => None()
+      #   None().filter(&:odd?) # => None()
+      def filter(&block)
+        return self if none?
+
+        block.call(value) ? self : None()
+      end
+
+      # Remove one level of Option nesting. Pedantically raises when the inner
+      # value is not itself an Option, which in Rust would not have compiled.
+      #
+      # @example
+      #   Some(Some(1)).flatten # => Some(1)
+      #   Some(None()).flatten # => None()
+      #   None().flatten # => None()
+      #   Some(Some(Some(1))).flatten # => Some(Some(1))
+      #   Some(1).flatten # => raise Errgonomic::TypeMismatchError, "cannot flatten Integer; it is not an Option"
+      def flatten
+        return self if none?
+
+        unless value.is_a?(Errgonomic::Option::Any)
+          raise Errgonomic::TypeMismatchError,
+                "cannot flatten #{value.class}; it is not an Option"
+        end
+
+        value
+      end
+
+      # Return Some when either self or other are Some, otherwise return None
+      # when both are None or both are Some.
+      #
+      # @example
+      #   Some(:left).xor(Some(:right)) # => None()
+      #   Some(:left).xor(None()) #=> Some(:left)
+      #   None().xor(Some(:right)) #=> Some(:right)
+      #
+      def xor(other)
+        return self if some? && other.none?
+        return other if other.some? && none?
+
+        None()
+      end
+
+      private
+
+      def presence_nudge(from, to)
+        warn "Errgonomic: `#{from}` on an Option is soft-deprecated; prefer `#{to}`."
+      end
+
+      def raise_blank_side_teaching(name)
+        raise Errgonomic::UnwrappedAccessError.new(<<~MSG, name)
+          `#{name}` is not supported on an Option, whose blankness is its discriminant.
+          Test it with none?, or supply a fallback with unwrap_or / unwrap_or_else.
+        MSG
+      end
+
+      public
+
+      # Rust's mutating combinators (insert, get_or_insert, take, replace)
+      # are deliberately omitted: an Option here is a value, not a slot.
     end
 
     # Represent a value
@@ -357,6 +634,7 @@ module Errgonomic
       attr_accessor :value
 
       def initialize(value)
+        super()
         @value = value
       end
 
@@ -367,8 +645,21 @@ module Errgonomic
       def none?
         false
       end
+
+      # Render like Rust's Debug, delegating to the inner value's inspect so
+      # nesting stays unambiguous.
+      #
+      # @example
+      #   Some(5).inspect # => "Some(5)"
+      #   Some("x").inspect # => "Some(\"x\")"
+      #   Some(nil).inspect # => "Some(nil)"
+      #   Some(Some(1)).inspect # => "Some(Some(1))"
+      def inspect
+        "Some(#{value.inspect})"
+      end
     end
 
+    # Represent the absence of a value.
     class None < Any
       def some?
         false
@@ -377,6 +668,12 @@ module Errgonomic
       def none?
         true
       end
+
+      # @example
+      #   None().inspect # => "None"
+      def inspect
+        'None'
+      end
     end
   end
 end

data/lib/errgonomic/optional_array.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'option'
+require_relative 'optional_dig'
+
+module Errgonomic
+  # A companion to Array whose lookups return Options, composed around a
+  # plain Array for the same reasons OptionalHash composes around a Hash.
+  # Lookups follow element presence: an element holding nil is Some(nil),
+  # and only an out-of-bounds index is None, as with Rust's slice get.
+  class OptionalArray
+    include OptionalDig
+
+    def initialize(array = [])
+      unless array.is_a?(::Array)
+        raise Errgonomic::TypeMismatchError,
+              "OptionalArray wraps an Array, got #{array.class}"
+      end
+
+      @array = array
+    end
+
+    # Retrieve the element at an integer index, wrapped in an Option.
+    # Negative indexes count from the end, as usual. A non-integer index
+    # raises, pedantically: the silent nil of Array#[] with a bad argument is
+    # the ambiguity this class exists to remove.
+    #
+    # @example
+    #   a = [:a, nil].into_optional
+    #   a[0] # => Some(:a)
+    #   a[1] # => Some(nil)
+    #   a[2] # => None()
+    #   a[-1] # => Some(nil)
+    #   a[:nope] # => raise Errgonomic::TypeMismatchError, "index must be an Integer, got Symbol"
+    def [](index)
+      unless index.is_a?(::Integer)
+        raise Errgonomic::TypeMismatchError,
+              "index must be an Integer, got #{index.class}"
+      end
+      return None() unless (-@array.length...@array.length).cover?(index)
+
+      Some(@array[index])
+    end
+
+    # Write through to the underlying array.
+    #
+    # @example
+    #   a = [].into_optional
+    #   a[0] = :a
+    #   a[0] # => Some(:a)
+    def []=(index, value)
+      @array[index] = value
+    end
+
+    # Like Array#dig, but every step checks presence, so an absent path
+    # (None) stays distinct from a present nil (Some(nil)).
+    #
+    # @example
+    #   a = [{ name: 'Ada' }].into_optional
+    #   a.dig(0, :name) # => Some("Ada")
+    #   a.dig(0, :nickname) # => None()
+    #   a.dig(1, :name) # => None()
+    def dig(index, *rest)
+      optional_dig(@array, [index, *rest])
+    end
+
+    # The first element as an Option, as with Rust's slice first.
+    #
+    # @example
+    #   [1, 2].into_optional.first # => Some(1)
+    #   [nil].into_optional.first # => Some(nil)
+    #   [].into_optional.first # => None()
+    def first
+      return None() if @array.empty?
+
+      Some(@array.first)
+    end
+
+    # The last element as an Option, as with Rust's slice last.
+    #
+    # @example
+    #   [1, 2].into_optional.last # => Some(2)
+    #   [].into_optional.last # => None()
+    def last
+      return None() if @array.empty?
+
+      Some(@array.last)
+    end
+
+    # @example
+    #   [].into_optional.empty? # => true
+    #   [1].into_optional.empty? # => false
+    def empty?
+      @array.empty?
+    end
+
+    # @example
+    #   [1, 2].into_optional.size # => 2
+    def size
+      @array.size
+    end
+
+    # The escape hatch back to a plain Array: a shallow copy, so array-shaped
+    # code cannot mutate the wrapped state behind the Option semantics.
+    #
+    # @example
+    #   [1].into_optional.to_a # => [1]
+    def to_a
+      @array.dup
+    end
+
+    # Equal to another OptionalArray wrapping an equal array; never equal to
+    # a plain Array, mirroring how Some(x) is never equal to x.
+    #
+    # @example
+    #   [1].into_optional == [1].into_optional # => true
+    #   [1].into_optional == [2].into_optional # => false
+    #   [1].into_optional == [1] # => false
+    def ==(other)
+      other.is_a?(OptionalArray) && inner == other.inner
+    end
+
+    # @example
+    #   [1].into_optional.eql?([1].into_optional) # => true
+    #   { [1].into_optional => :hit }[[1].into_optional] # => :hit
+    def eql?(other)
+      other.is_a?(OptionalArray) && inner.eql?(other.inner)
+    end
+
+    def hash
+      [self.class, inner].hash
+    end
+
+    # @example
+    #   [1].into_optional.inspect # => "OptionalArray([1])"
+    def inspect
+      "OptionalArray(#{@array.inspect})"
+    end
+
+    protected
+
+    def inner
+      @array
+    end
+  end
+end

data/lib/errgonomic/optional_dig.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'option'
+
+module Errgonomic
+  # The presence-checking walk behind OptionalHash#dig and OptionalArray#dig:
+  # every step checks key or bounds presence, so an absent path (None) stays
+  # distinct from a present nil (Some(nil)), which the core dig methods
+  # conflate. A nested wrapper handles the rest of the walk itself, by
+  # recursion. Digging into a non-collection raises, pedantically, where
+  # core dig would raise TypeError.
+  module OptionalDig
+    private
+
+    def optional_dig(start, keys)
+      current = start
+      keys.each_with_index do |key, idx|
+        case current
+        when OptionalHash, OptionalArray
+          return current.dig(key, *keys[(idx + 1)..])
+        when ::Hash
+          return None() unless current.key?(key)
+        when ::Array
+          return None() unless key.is_a?(Integer) && (-current.length...current.length).cover?(key)
+        else
+          raise Errgonomic::TypeMismatchError, "cannot dig into #{current.class}"
+        end
+        current = current[key]
+      end
+      Some(current)
+    end
+  end
+end