errgonomic 0.7.0 → 0.8.0

data/lib/errgonomic/optional_hash.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'option'
+require_relative 'optional_dig'
+
+module Errgonomic
+  # A companion to Hash whose lookups return Options, composed around a plain
+  # Hash rather than subclassing it. Subclassing cannot keep Option semantics:
+  # since Ruby 3, most Hash methods return plain Hash instances, so wrapped
+  # behavior silently drops off in pipelines. Composition with a small, closed
+  # API keeps the semantics honest; reach the plain Hash back with to_h.
+  #
+  # Lookups follow key presence, not value truthiness, so a key holding nil is
+  # Some(nil). This matches Option presence semantics: the discriminant tells
+  # you whether the key was there, and the inner value is yours to judge.
+  class OptionalHash
+    include OptionalDig
+
+    def initialize(hash = {})
+      unless hash.is_a?(::Hash)
+        raise Errgonomic::TypeMismatchError,
+              "OptionalHash wraps a Hash, got #{hash.class}"
+      end
+
+      @hash = hash
+    end
+
+    # Retrieve the value for a key, wrapped in an Option. A present key with
+    # a nil value is Some(nil); only a missing key is None.
+    #
+    # @example
+    #   h = { color: :blue, shade: nil }.into_optional
+    #   h[:color] # => Some(:blue)
+    #   h[:shade] # => Some(nil)
+    #   h[:smell] # => None()
+    def [](key)
+      return None() unless @hash.key?(key)
+
+      Some(@hash[key])
+    end
+
+    # Write through to the underlying hash.
+    #
+    # @example
+    #   h = {}.into_optional
+    #   h[:color] = :blue
+    #   h[:color] # => Some(:blue)
+    def []=(key, value)
+      @hash[key] = value
+    end
+
+    # Like Hash#dig, but every step checks presence, so the result
+    # distinguishes an absent path (None) from a present nil (Some(nil)),
+    # which Hash#dig conflates. Walks nested Hashes, Arrays, and
+    # OptionalHashes; digging into anything else raises, pedantically, where
+    # Hash#dig would raise TypeError.
+    #
+    # @example
+    #   h = { person: { name: 'Ada', middle_name: nil } }.into_optional
+    #   h.dig(:person, :name) # => Some("Ada")
+    #   h.dig(:person, :middle_name) # => Some(nil)
+    #   h.dig(:person, :nickname) # => None()
+    #   h.dig(:company, :name) # => None()
+    #
+    # @example arrays participate, with bounds checked
+    #   h = { people: [{ name: 'Ada' }] }.into_optional
+    #   h.dig(:people, 0, :name) # => Some("Ada")
+    #   h.dig(:people, 1, :name) # => None()
+    #
+    # @example a nested wrapper walks the rest of the path itself
+    #   h = { person: { name: 'Ada' }.into_optional }.into_optional
+    #   h.dig(:person, :name) # => Some("Ada")
+    #   h.dig(:person, :nickname) # => None()
+    #
+    # @example digging into a non-collection is an error, not a None
+    #   h = { name: 'Ada' }.into_optional
+    #   h.dig(:name, :length) # => raise Errgonomic::TypeMismatchError, "cannot dig into String"
+    def dig(key, *rest)
+      optional_dig(@hash, [key, *rest])
+    end
+
+    # @example
+    #   h = { shade: nil }.into_optional
+    #   h.key?(:shade) # => true
+    #   h.key?(:color) # => false
+    def key?(key)
+      @hash.key?(key)
+    end
+
+    # @example
+    #   {}.into_optional.empty? # => true
+    #   { a: 1 }.into_optional.empty? # => false
+    def empty?
+      @hash.empty?
+    end
+
+    # @example
+    #   { a: 1 }.into_optional.size # => 1
+    def size
+      @hash.size
+    end
+
+    # The escape hatch back to a plain Hash: a shallow copy, so hash-shaped
+    # code cannot mutate the wrapped state behind the Option semantics.
+    #
+    # @example
+    #   { a: 1 }.into_optional.to_h # => { a: 1 }
+    def to_h
+      @hash.dup
+    end
+
+    # Equal to another OptionalHash wrapping an equal hash; never equal to a
+    # plain Hash, mirroring how Some(x) is never equal to x.
+    #
+    # @example
+    #   { a: 1 }.into_optional == { a: 1 }.into_optional # => true
+    #   { a: 1 }.into_optional == { a: 2 }.into_optional # => false
+    #   { a: 1 }.into_optional == { a: 1 } # => false
+    def ==(other)
+      other.is_a?(OptionalHash) && inner == other.inner
+    end
+
+    # @example
+    #   { a: 1 }.into_optional.eql?({ a: 1 }.into_optional) # => true
+    #   h = { a: 1 }.into_optional
+    #   { h => :hit }[{ a: 1 }.into_optional] # => :hit
+    def eql?(other)
+      other.is_a?(OptionalHash) && inner.eql?(other.inner)
+    end
+
+    def hash
+      [self.class, inner].hash
+    end
+
+    # @example
+    #   {}.into_optional.inspect # => "OptionalHash({})"
+    def inspect
+      "OptionalHash(#{@hash.inspect})"
+    end
+
+    protected
+
+    def inner
+      @hash
+    end
+  end
+end

data/lib/errgonomic/presence.rb

@@ -5,6 +5,8 @@
 # gem a dependency.
 require_relative './core_ext/blank' unless Object.methods.include?(:blank?)
 
+# Presence-based fallbacks for every object: keep the receiver when it is
+# present, otherwise substitute, compute, or raise.
 class Object
   # Returns the receiver if it is present, otherwise raises a NotPresentError.
   # This method is useful to enforce strong expectations, where it is preferable
@@ -18,7 +20,7 @@ class Object
     self
   end
 
-  alias_method :present_or_raise, :present_or_raise!
+  alias present_or_raise present_or_raise!
 
   # Returns the receiver if it is present, otherwise returns the given value. If
   # constructing the default value is expensive, consider using
@@ -61,7 +63,7 @@ class Object
     self
   end
 
-  alias_method :blank_or_raise, :blank_or_raise!
+  alias blank_or_raise blank_or_raise!
 
   # Returns the receiver if it is blank, otherwise returns the given value.
   #

data/lib/errgonomic/rails/active_record_delegate_optional.rb

@@ -1,5 +1,10 @@
+# frozen_string_literal: true
+
 module Errgonomic
   module Rails
+    # Adds a `delegate_optional` class method in the spirit of Rails'
+    # `delegate`, returning an Option instead of nil or NoMethodError when
+    # the delegation target is absent.
     module ActiveRecordDelegateOptional
       extend ActiveSupport::Concern
 
@@ -14,6 +19,7 @@ module Errgonomic
                 #{to}.map { |obj| obj.send(:#{method_name}) }
               end
             RUBY
+            send(:private, prefixed_method_name) if private
           end
         end
       end

data/lib/errgonomic/rails/active_record_optional.rb

@@ -4,6 +4,21 @@ module Errgonomic
   module Rails
     # Concern to make ActiveRecord optional attributes and associations return an Option.
     #
+    # Four pragmatic compromises below satisfy ActiveRecord's assumptions
+    # about how accessors behave. They are deliberate exceptions to "Option
+    # behaves like Rust's Option", and the set is closed: a fifth would be a
+    # signal that ActiveRecord is pushing back somewhere unmapped, deserving
+    # a design discussion rather than a quiet patch.
+    #
+    # 1. None#nil? answers true, so AR internals and ordinary nil checks
+    #    treat an absent value as absent. Equality does not follow suit:
+    #    None() == nil stays false.
+    # 2. Some delegates persisted?, marked_for_destruction?, and touch_later
+    #    to its record, so a Some can stand in for it during persistence.
+    # 3. Two quoting prepends unwrap Options at the SQL boundary, so an
+    #    Option can be passed to where/quote.
+    # 4. SomeValidator provides a presence-style validation for Option
+    #    attributes.
     module ActiveRecordOptional
       extend ActiveSupport::Concern
 
@@ -18,8 +33,19 @@ module Errgonomic
         @errgonomic_optionals.each do |name|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{name}
-              raise "stack too deep" if caller.length > 1024
-              val = super
+              reads = Thread.current[:errgonomic_optional_reads] ||= {}
+              key = [object_id, :#{name}]
+              if reads[key]
+                raise Errgonomic::RecursiveOptionalReadError,
+                      "\#{self.class}##{name} re-entered itself; something beneath this reader reads it again"
+              end
+
+              reads[key] = true
+              begin
+                val = super
+              ensure
+                reads.delete(key)
+              end
               val.nil? ? Errgonomic::Option::None.new : Errgonomic::Option::Some.new(val)
             end
           RUBY
@@ -35,7 +61,8 @@ module Errgonomic
   end
 end
 
-# do we need this since we alias present below?
+# Validates that an Option attribute is Some, analogous to a presence
+# validation on a plain attribute.
 class SomeValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
     record.errors.add(attribute, 'is invalid') unless value.some?
@@ -44,17 +71,16 @@ end
 
 module Errgonomic
   module Option
-    class Any
-      alias some? present?
-      alias none? blank?
-    end
-
+    # Delegate ActiveRecord lifecycle checks to the wrapped record, so a Some
+    # can stand in for its record during persistence.
     class Some
       delegate :marked_for_destruction?, to: :value
       delegate :persisted?, to: :value
       delegate :touch_later, to: :value
     end
 
+    # A None answers nil? like nil itself, so ActiveRecord internals that
+    # check for nil treat an absent value as absent.
     class None
       def nil?
         true
@@ -63,6 +89,8 @@ module Errgonomic
   end
 end
 
+# Teach ActiveRecord type casting to unwrap Options: a Some casts as its
+# inner value, a None casts as nil.
 module ActiveRecordOptionShim
   def type_cast(value)
     case value
@@ -78,12 +106,14 @@ end
 
 ActiveRecord::ConnectionAdapters::Quoting.prepend(ActiveRecordOptionShim)
 
+# Lift nil into None.
 class NilClass
   def to_option
     None()
   end
 end
 
+# Lift any other value into Some.
 class Object
   def to_option
     Some(self)
@@ -92,6 +122,8 @@ end
 
 module Errgonomic
   module Rails
+    # Teach ActiveRecord SQL quoting to unwrap Options, quoting a None as
+    # SQL NULL.
     module ActiveRecordQuoting
       def quote(value)
         return super(value) unless value.is_a?(Errgonomic::Option::Any)

data/lib/errgonomic/rails.rb

@@ -1,4 +1,6 @@
-require_relative 'option'
+# frozen_string_literal: true
+
+require_relative '../errgonomic'
 require_relative 'rails/active_record_optional'
 require_relative 'rails/active_record_delegate_optional'
 

data/lib/errgonomic/result.rb

@@ -6,12 +6,77 @@ module Errgonomic
     # much logic as possible here, and let Ok and Err handle their
     # initialization and self identification.
     class Any
+      include Comparable
+
       attr_reader :value
 
       def initialize(value)
         @value = value
       end
 
+      # Results order like Rust's: Ok sorts before any Err, and same variants
+      # order by their inner values. Follows Ruby's <=> convention of
+      # returning nil for incomparable operands, whether the other object is
+      # not a Result or the inner values do not themselves compare.
+      #
+      # @example
+      #   (Ok(1) <=> Ok(2)) # => -1
+      #   (Ok(1) <=> Err(:a)) # => -1
+      #   (Err(:a) <=> Ok(1)) # => 1
+      #   (Err(:a) <=> Err(:b)) # => -1
+      #   (Ok(1) <=> 1) # => nil
+      #   [Err(:a), Ok(2), Ok(1)].sort # => [Ok(1), Ok(2), Err(:a)]
+      def <=>(other)
+        return nil unless other.is_a?(Errgonomic::Result::Any)
+        return ok? ? -1 : 1 if self.class != other.class
+
+        value <=> other.value
+      end
+
+      # 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_ok: :ok?,
+        is_err: :err?,
+        is_ok_and: :ok_and?,
+        is_err_and: :err_and?
+      }.freeze
+
+      # A Result 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.
+      #
+      # @example
+      #   begin
+      #     Ok(5) + 1
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   Ok(5).respond_to?(:+) # => false
+      #   Ok(1).is_ok_and(&:odd?) # => true
+      #   Err(:a).is_err # => true
+      #   Ok(1).respond_to?(:is_ok) # => 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}, a Result, which does not forward methods to its inner value.
+          Reach for a combinator instead:
+            map, map_err, and_then, or_else: transform the value or the error
+            unwrap_or, unwrap_or_else: supply a fallback
+            ok_and?, err_and?: test a predicate against the inner value
+          unwrap!, unwrap_err!, 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
+
       # Equality comparison for Result objects is based on value not reference.
       #
       # @param other [Object]
@@ -28,6 +93,27 @@ 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 Results
+      # behave as keys exactly like their inner values.
+      #
+      # @example
+      #   Ok(5).eql?(Ok(5)) # => true
+      #   Ok(1).eql?(Ok(1.0)) # => false
+      #   Ok(1).eql?(Err(1)) # => false
+      #   { Ok(5) => 1 }[Ok(5)] # => 1
+      #   [Err(:a), Err(:a)].uniq # => [Err(:a)]
+      def eql?(other)
+        self.class == other.class && value.eql?(other.value)
+      end
+
+      # @example
+      #   Ok(5).hash == Ok(5).hash # => true
+      #   Ok(5).hash == Err(5).hash # => false
+      def hash
+        [self.class, value].hash
+      end
+
       # Indicate that this is some kind of result object. Contrast to
       # Object#result? which is false for all other types.
       #
@@ -283,6 +369,12 @@ module Errgonomic
         raise Errgonomic::SerializeError, 'cannot serialize an unwrapped Result'
       end
 
+      # pp uses its own object dump unless told otherwise; keep it consistent
+      # with inspect.
+      def pretty_print(pp)
+        pp.text(inspect)
+      end
+
       # @example simple pattern match with variable capture of the value
       #   result = Errgonomic::Result::Ok.new(1)
       #   case result
@@ -305,7 +397,6 @@ module Errgonomic
       def deconstruct
         [self, value]
       end
-
     end
 
     # The Ok variant.
@@ -327,8 +418,18 @@ module Errgonomic
       def err?
         false
       end
+
+      # Render like Rust's Debug, delegating to the inner value's inspect.
+      #
+      # @example
+      #   Ok(1).inspect # => "Ok(1)"
+      #   Ok("x").inspect # => "Ok(\"x\")"
+      def inspect
+        "Ok(#{value.inspect})"
+      end
     end
 
+    # The Err variant.
     class Err < Any
       class Arbitrary; end
 
@@ -358,15 +459,25 @@ module Errgonomic
       def ok?
         false
       end
+
+      # Render like Rust's Debug; a value-less Err renders bare.
+      #
+      # @example
+      #   Err(:nope).inspect # => "Err(:nope)"
+      #   Err().inspect # => "Err()"
+      def inspect
+        return 'Err()' if value == Arbitrary
+
+        "Err(#{value.inspect})"
+      end
     end
   end
 end
 
-# Introduce certain helper methods into the Object class.
-#
-# @example
-#   "foo".result? # => false
-#   "foo".assert_result! # => raise Errgonomic::ResultRequiredError
+# Introduce result-ness helpers into the Object class. No doctests here:
+# several files reopen Object, and YARD keeps only one docstring for it, so
+# examples on the class itself can be silently dropped. Each method carries
+# its own examples instead.
 class Object
   # Convenience method to indicate whether we are working with a result.
   # TBD whether we implement some stubs for the rest of the Result API; I want

data/lib/errgonomic/type.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Runtime type assertions for every object: keep the receiver when it matches
+# the expected type, otherwise substitute, compute, or raise.
 class Object
   # Returns the receiver if it matches the expected type, otherwise raises a TypeMismatchError.
   # This is useful for enforcing type expectations in method arguments.

data/lib/errgonomic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Errgonomic
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

data/lib/errgonomic.rb

@@ -12,6 +12,13 @@ require_relative 'errgonomic/type'
 require_relative 'errgonomic/option'
 require_relative 'errgonomic/result'
 
+# Option-returning lookups for the collections.
+require_relative 'errgonomic/core_ext/hash'
+require_relative 'errgonomic/core_ext/array'
+
+# Lift booleans into Option and Result.
+require_relative 'errgonomic/core_ext/bool'
+
 # Rails fu
 require_relative 'errgonomic/rails' if defined?(Rails::Railtie)
 
@@ -29,6 +36,8 @@ module Errgonomic
 
   class TypeMismatchError < Error; end
 
+  # Raised when unwrap! is called on a None or an Err. Carries the Err's
+  # inner value so diagnostics can show what actually went wrong.
   class UnwrapError < Error
     attr_reader :value
 
@@ -44,8 +53,18 @@ module Errgonomic
 
   class ResultRequiredError < Error; end
 
+  # Raised when a wrapped ActiveRecord attribute reader re-enters itself on
+  # the same record, catching runaway recursion at the first repeated frame
+  # instead of a SystemStackError thousands of frames later.
+  class RecursiveOptionalReadError < Error; end
+
   class NotComparableError < StandardError; end
 
+  # Raised when a method missing from Option or Result is called, with a
+  # message that teaches the combinators. Subclasses NoMethodError so every
+  # rescue path and Ruby-internal probe that expects one keeps working.
+  class UnwrappedAccessError < ::NoMethodError; end
+
   class SerializeError < TypeError; end
 
   # A little bit of control over how pedantic we are in our runtime type checks.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Nick Zadrozny
@@ -66,16 +66,23 @@ files:
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - doctest_helper.rb
 - flake.lock
 - flake.nix
-- gemset.nix
+- gem-groups.json
 - lib/errgonomic.rb
+- lib/errgonomic/core_ext/array.rb
 - lib/errgonomic/core_ext/blank.rb
+- lib/errgonomic/core_ext/bool.rb
+- lib/errgonomic/core_ext/hash.rb
 - lib/errgonomic/option.rb
+- lib/errgonomic/optional_array.rb
+- lib/errgonomic/optional_dig.rb
+- lib/errgonomic/optional_hash.rb
 - lib/errgonomic/presence.rb
 - lib/errgonomic/rails.rb
 - lib/errgonomic/rails/active_record_delegate_optional.rb
@@ -104,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Opinionated, ergonomic error handling for Ruby, inspired by Rails and Rust.
 test_files: []