errgonomic 0.9.1 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e5dd5bf1efa4f12df029b4084a03a8a16eacac628f9481c35cbac8d03164b0c
-  data.tar.gz: c61b4e0944afd847636e0e7a1beb44a60793b2124fb9b390cdc408cb3899fb6c
+  metadata.gz: 58963c6e1c1cfcf52d8fe4b065dd986acda616f4e55001d7d2bc13cbeab1eb28
+  data.tar.gz: 9d6f93fdd27c94525f2f2a2dc53010eb4f99760dae7514eaf4f035f5c9947869
 SHA512:
-  metadata.gz: bafdcc2538e9603d54fc0452912fddf9f86f912074f9a94dd0af3de3783df26917263cca09d0a5ea9440844016fb3da7190127327602a18506c62723ee81c4d8
-  data.tar.gz: 43a642d0ebfc22610b0f0ad0fe14f954d23c9b6909cc72e1a4ed56543e7e7d3e3c6e6173ce5443a12f33504045aacc734a5ea922d9a7998d4bd5a03f80a889c7
+  metadata.gz: 2adf6eadd64c94629ba265ea9747d943314616f8c26943ad075ea5399bc86c4747e433946273989640b668e0841c337cdc6f3ecc873fed9006aa82eb439510d9
+  data.tar.gz: 475c6a42553b89700d4de4d0d7257bcbb71388c61d8b12da69a51ce4aa30a75f7074757a498bb20d5074539748b8e799bf8c78303ef3dc8ac33a74306d615aad

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## [Unreleased]
 
+## [0.9.3] - 2026-09-10
+
+This release removes the public `value` slot from `Some`, `Ok` and `Err`, and freezes every instance as it is constructed, so an Option or a Result is the value the README already said it was.
+
+### Upgrading from 0.9.2
+
+`value` and `value=` are gone from `Some`, `Ok` and `Err`, and every instance is frozen as it is constructed. A read of `.value` becomes `unwrap_or(fallback)`, `expect!(message)`, `map`, `and_then` or a pattern, each of which names the other branch; a write of `.value=` becomes a new `Some(v)` assigned where the old one lived. A call to either now raises `Errgonomic::UnwrappedAccessError`, which is a `NoMethodError`, naming the combinators.
+
+### Changes
+
+- [Behavior change] `Some`, `Ok` and `Err` no longer expose `value` or `value=`, and every Option and Result is frozen as it is constructed, whether by `Some`, `None`, `Ok`, `Err`, `new` or a combinator; `clone` keeps it frozen. A copy that skips construction, from `dup`, `Marshal.load`, a YAML load or ActiveSupport's `deep_dup`, is not frozen; with no writer, it changes only through `instance_variable_set`. The reader reached the inner value with no `None` branch, the writer mutated a wrapper through an alias and moved a Hash key out from under its own bucket, and the README already said an Option is a value rather than a slot. The reader is protected, for the sibling reads equality, ordering and `zip` need; a call from outside gets the combinator teaching `Errgonomic::UnwrappedAccessError` gives any other miss
+
+## [0.9.2] - 2026-09-10
+
+This release makes `Option#and`, `#xor`, `#zip` and `#zip_with` check their operand the way `or` already did.
+
+### Upgrading from 0.9.1
+
+`Option#and`, `#xor`, `#zip` and `#zip_with` raise `Errgonomic::ArgumentError` on a bare operand, on a `None` receiver as well as a `Some`. Code that passed a bare value to `and` and read it back has to wrap it.
+
+### Changes
+
+- [Behavior change] `Option#and`, `#xor`, `#zip` and `#zip_with` check their operand the way `or` already did, raising `Errgonomic::ArgumentError` (`other must be an Option, was Integer`) before the receiver's variant is consulted. 0.9.x let `Some(2).and(3)` hand back the bare `3`, let `None().and(3)` and `None().zip(2)` accept the operand silently, and let `Some(1).zip(2)` and `Some(:l).xor(:r)` fall into a bare `NoMethodError` on `some?` or `none?`
+
 ## [0.9.1] - 2026-09-10
 
 This release reverts the 0.9.0 change that made `to_s` render an Option or a Result. The raise is back, with a message that says what to call instead.

data/README.md

@@ -144,7 +144,7 @@ Writers unwrap under that integration, which changes what a truthiness slip cost
 
 The remaining present-side helpers are soft-deprecated on Options in favor of the combinators. They unwrap, where on any other object they return the receiver: `Some(v).present_or_raise!(msg)`, `present_or(default)` and `present_or_else { }` all yield `v`, and `None` raises, substitutes, or computes. Each prints a one-line stderr nudge naming the combinator to use instead (`expect!`, `unwrap_or`, `unwrap_or_else`), once per process per method rather than once per call, so a hot path does not flood the log. The blank side (`blank_or*`) raises `UnwrappedAccessError` outright: an Option's blankness is its discriminant, so test it with `none?`.
 
-Four of Rust's methods are deliberately absent: `take`, `replace`, `insert` and `get_or_insert`. Every one of them writes through an `&mut Option`, and an Option here is a value rather than a slot: `Some(1)` is something you pass around and compare, not a cell whose contents you swap out from under another reference. Build the Option you want and assign it where the old one lived.
+Four of Rust's methods are deliberately absent: `take`, `replace`, `insert` and `get_or_insert`. Every one of them writes through an `&mut Option`, and an Option here is a value rather than a slot: `Some(1)` is something you pass around and compare, not a cell whose contents you swap out from under another reference. Build the Option you want and assign it where the old one lived. The same rule is why a `Some`, an `Ok` and an `Err` have no `value` reader or writer, and why every instance is frozen as it is constructed. A copy that skips construction, from `dup`, `Marshal.load`, a YAML load or ActiveSupport's `deep_dup`, is not frozen; with no writer, it changes only through `instance_variable_set`. A reader would reach the inner value with no `None` branch, and a writer would move a Hash key out from under its own bucket. Reach in with `unwrap_or`, `expect!`, `map`, `and_then` or a pattern, each of which names what happens on the other branch.
 
 Equality is between Options only: `Some(5) == Some(5)`, but `Some(5) == 5` and `None() == nil` are `false`. That is quiet, never an error, matching how every Ruby object compares across types. Rust rejects `Some(5) == 5` at compile time; Ruby cannot, so guard the idiom in review and tests: compare against a wrapped value (`opt == Some(5)`) or test the inner value (`opt.some_and? { |v| v == 5 }`). `Errgonomic.strict_equality = true` turns that guard into an error, which is what a test suite wants; see [Pedantic runtime checks](#pedantic-runtime-checks).
 

data/lib/errgonomic/core_ext/enumerable.rb

@@ -46,7 +46,7 @@ module Enumerable
       end
       return None() if member.none?
 
-      values << member.value
+      member.tap_some { |value| values << value }
     end
     Some(values)
   end
@@ -87,7 +87,7 @@ module Enumerable
       end
       return member if member.err?
 
-      values << member.value
+      member.tap_ok { |value| values << value }
     end
     Ok(values)
   end

data/lib/errgonomic/option.rb

@@ -178,7 +178,7 @@ module Errgonomic
       #   measurement = Errgonomic::Option::Some.new(1)
       #   case measurement
       #   in Errgonomic::Option::Some, value
-      #     "Measurement is #{measurement.value}"
+      #     "Measurement is #{value}"
       #   in Errgonomic::Option::None
       #     "Measurement is not available"
       #   else
@@ -594,10 +594,10 @@ module Errgonomic
       # @example
       #   None().or(Some(1)) # => Some(1)
       #   Some(2).or(Some(3)) # => Some(2)
-      #   None().or(2) # => raise Errgonomic::ArgumentError.new, "other must be an Option, was Integer"
+      #   None().or(2) # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
+      #   Some(1).or(2) # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
       def or(other)
-        raise ArgumentError, "other must be an Option, was #{other.class.name}" unless other.is_a?(Any)
-
+        option_operand!(other)
         return self if some?
 
         other
@@ -620,12 +620,17 @@ module Errgonomic
         val
       end
 
-      # If self is Some, return the provided other Option.
+      # If self is Some, return the provided other Option. The operand is
+      # checked on both variants, so a None-heavy path still learns that it
+      # was handed a bare value.
       #
       # @example
       #   None().and(Some(1)) # => None()
       #   Some(2).and(Some(3)) # => Some(3)
+      #   Some(2).and(3) # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
+      #   None().and(3) # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
       def and(other)
+        option_operand!(other)
         return self if none?
 
         other
@@ -657,7 +662,10 @@ module Errgonomic
       #   None().zip(Some(1)) # => None()
       #   Some(1).zip(None()) # => None()
       #   Some(2).zip(Some(3)) # => Some([2, 3])
+      #   Some(1).zip(2) # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
+      #   None().zip(2) # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
       def zip(other)
+        option_operand!(other)
         return None() unless some? && other.some?
 
         Some([value, other.value])
@@ -671,7 +679,10 @@ module Errgonomic
       #   None().zip_with(Some(1)) { |a, b| a + b } # => None()
       #   Some(1).zip_with(None()) { |a, b| a + b } # => None()
       #   Some(2).zip_with(Some(3)) { |a, b| a + b } # => Some(5)
+      #   Some(1).zip_with(2) { |a, b| a + b } # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
+      #   None().zip_with(2) { |a, b| a + b } # => raise Errgonomic::ArgumentError, "other must be an Option, was Integer"
       def zip_with(other, &block)
+        option_operand!(other)
         return None() unless some? && other.some?
 
         other = block.call(value, other.value)
@@ -767,8 +778,10 @@ module Errgonomic
       #   Some(:left).xor(Some(:right)) # => None()
       #   Some(:left).xor(None()) #=> Some(:left)
       #   None().xor(Some(:right)) #=> Some(:right)
-      #
+      #   Some(:left).xor(:right) # => raise Errgonomic::ArgumentError, "other must be an Option, was Symbol"
+      #   None().xor(:right) # => raise Errgonomic::ArgumentError, "other must be an Option, was Symbol"
       def xor(other)
+        option_operand!(other)
         return self if some? && other.none?
         return other if other.some? && none?
 
@@ -777,6 +790,14 @@ module Errgonomic
 
       private
 
+      # Checked before the discriminant is consulted, so a None-heavy path
+      # learns about a bare operand as soon as a Some-heavy one would.
+      def option_operand!(other)
+        return if other.is_a?(Errgonomic::Option::Any)
+
+        raise Errgonomic::ArgumentError, "other must be an Option, was #{other.class.name}"
+      end
+
       def to_s_refusal
         "#{bounded_inspect} refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value"
       end
@@ -830,11 +851,47 @@ module Errgonomic
 
     # Represent a value
     class Some < Any
-      attr_accessor :value
-
+      # A Some is a value, not a slot: nothing outside reads the inner value
+      # without handling the None branch, and nothing swaps it out from under
+      # another reference or a Hash key.
+      #
+      # @example the inner value is reached through a combinator, never a reader
+      #   begin
+      #     Some(1).value
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   Some(1).respond_to?(:value) # => false
+      #
+      # @example a Some cannot be mutated through an alias
+      #   a = Some(1)
+      #   b = a
+      #   begin
+      #     b.value = 99
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   a # => Some(1)
+      #   Some(1).frozen? # => true
+      #   begin
+      #     Some(1).instance_variable_set(:@value, 2)
+      #   rescue FrozenError => e
+      #     e.class
+      #   end # => FrozenError
+      #
+      # @example a Some keeps its place as a Hash key
+      #   k = Some(1)
+      #   h = { k => :v }
+      #   begin
+      #     k.value = 2
+      #   rescue NoMethodError
+      #     nil
+      #   end
+      #   h[k] # => :v
       def initialize(value)
         super()
         @value = value
+        freeze
       end
 
       def some?
@@ -856,10 +913,28 @@ module Errgonomic
       def inspect
         "Some(#{value.inspect})"
       end
+
+      protected
+
+      # Sibling instances read each other's value for equality, ordering and
+      # zip; nothing else does.
+      attr_reader :value
     end
 
     # Represent the absence of a value.
     class None < Any
+      # @example a None has no value to read, and says so the same way a Some does
+      #   begin
+      #     None().value
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   None().frozen? # => true
+      def initialize
+        super
+        freeze
+      end
+
       def some?
         false
       end

data/lib/errgonomic/result.rb

@@ -8,10 +8,27 @@ module Errgonomic
     class Any
       include Comparable
 
-      attr_reader :value
-
+      # A Result is a value, not a slot: the inner value is reached through a
+      # combinator that handles the other variant, and nothing swaps it out
+      # from under another reference.
+      #
+      # @example
+      #   begin
+      #     Ok(1).value
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   begin
+      #     Err(:x).value = :y
+      #   rescue NoMethodError => e
+      #     e.class
+      #   end # => Errgonomic::UnwrappedAccessError
+      #   Ok(1).respond_to?(:value) # => false
+      #   Ok(1).frozen? # => true
+      #   Err().frozen? # => true
       def initialize(value)
         @value = value
+        freeze
       end
 
       # Results order like Rust's: Ok sorts before any Err, and same variants
@@ -477,6 +494,12 @@ module Errgonomic
         [self, value]
       end
 
+      protected
+
+      # Sibling instances read each other's value for equality and ordering;
+      # nothing else does.
+      attr_reader :value
+
       private
 
       def to_s_refusal
@@ -512,8 +535,6 @@ module Errgonomic
 
     # The Ok variant.
     class Ok < Any
-      attr_accessor :value
-
       # Ok is always ok
       #
       # @example
@@ -544,13 +565,11 @@ module Errgonomic
     class Err < Any
       class Arbitrary; end
 
-      attr_accessor :value
-
       # Err may be constructed without a value, if you want.
       #
       # @example
-      #   Err(:y).value # => :y
-      #   Err().value # => Arbitrary
+      #   Err(:y).unwrap_err! # => :y
+      #   Err().unwrap_err! # => Arbitrary
       def initialize(value = Arbitrary)
         super(value)
       end

data/lib/errgonomic/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.9.3
 platform: ruby
 authors:
 - Nick Zadrozny