errgonomic 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b6ae05f6601a1d5470b1cb9cd9266e3937b91fd2ea2bab8eeac469959b24e90
-  data.tar.gz: 5b3095f01409a6275b500df7d08e0c8b23b50062924d61ada8a4a6c98e0b69fe
+  metadata.gz: d39f466feedb411b53780fa853b509dc6a40db2f12aef63235a6817881ce2d95
+  data.tar.gz: bc81bba0f57ddaac60178b0319533feeb054be296614332b8a9744d72b0ae9d1
 SHA512:
-  metadata.gz: a74d4cdf58805801e853a59329b076ca43c553da3a670fc56762fea5d755da898c6a6951e2c697fcb91b28930382d2f0ff6e3e2a85038ad33a5a3a0d4567c6c3
-  data.tar.gz: d636451a6addbfc3e2af62974e659fe7de490dd7b4176f3cf2f53c6f93dd6d620244f14e99a684817a160a4715c02ed4b5d0b003bded913f5962e64987d674cc
+  metadata.gz: 26b24e1089898ad573927824616829559a6c9fa5c169abf71addcad1284a345597ae12928f4a22153ce1d06f64db3572e7e4d0d6c596df2dffef4a1eb260e72e
+  data.tar.gz: 5f20b741f3feb1c4f5b84daee2f3934edc09f89f962a459c485dfed8356d63e84297f778b3b74f761ada2c1be2ea5c371c73b318a2ef5aa54c8ba635612ba450

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-10
+
+This release gives `deconstruct` the Rust shape and names the four variants at top level, so a pattern reads as `in Some(v)`.
+
+### Upgrading from 0.9.3
+
+`deconstruct` answers `[value]` for a `Some`, an `Ok` and an `Err` and `[]` for a `None`, so a pattern written against 0.9.x's `[self, value]` has to change shape: `in Errgonomic::Option::Some, v` becomes `in Some(v)`, `in Errgonomic::Result::Err, String => msg` becomes `in Err(String => msg)`, and `in Errgonomic::Option::None` stays as it is or becomes `in None`. `Some`, `None`, `Ok` and `Err` are now top-level names for the four variants, for patterns, as well as constructors. An application that defines its own constant under one of those names has to rename it: errgonomic refuses to load over one with a `NameError`, and a `class` or `module` of that name written after it loads raises `TypeError`.
+
+### Changes
+
+- [Behavior change] `deconstruct` answers `[value]` for a `Some`, an `Ok` and an `Err` and `[]` for a `None`, the one-payload shape `Data.define(:value)` and Rust's tuple variants share, where 0.9.x answered `[self, value]` and `[None]`. `in Some(v)` binds the value, `in Ok(Some(v))` nests, a two-branch `case/in` with no `else` is exhaustive, and a wrong type reaches `NoMatchingPatternError`. There is no `deconstruct_keys`: a one-payload sum type has no named field, and a `Some` around a Hash nests as `in Some({ id: })` through the Hash's own protocol
+- A value-less `Err()` deconstructs to `[]`, so `in Err` and `in Err()` match it and `in Err(e)` matches only an `Err` that carries a value. The sentinel `Err()` holds in place of a value is internal, and a pattern variable must never bind it
+- `Some`, `None`, `Ok` and `Err` are defined at top level beside the constructors of the same name, so a pattern reads as it does in Rust. Each is an `Errgonomic::VariantName` rather than the class it names: it matches as that class in a pattern and a `case/when`, and a bare one, written as Rust writes `return None`, refuses to stand in for a value. `to_s`, `to_json`, `as_json` and every ActiveRecord boundary that unwraps an Option raise `Errgonomic::SerializeError` on it, where the class would write `Errgonomic::Option::None` into a string, a column or a query, and a boolean column would store `true`. A constant of the same name that the application already defines stops the gem's load with a `NameError`, and a `class None` written after the gem loads raises `TypeError`, rather than one replacing or reopening the other. Rails defines none of the four
+
+## [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.

data/README.md

@@ -111,17 +111,21 @@ Some(1).each.to_a                # => [1]
 
 `map` wraps whatever the block returns, as Rust's does, so a block that itself returns an Option gives `Some(Some(x))`. `and_then` is the spelling for that block.
 
-Options support pattern matching:
+Options pattern match in the Rust shape. `Some`, `None`, `Ok` and `Err` name the variants in a pattern as well as building them, so a pattern reads as it does in Rust:
 
 ```ruby
 case measurement
-in Errgonomic::Option::Some, value
+in Some(value)
   "Measurement is #{value}"
-in Errgonomic::Option::None
+in None
   "Measurement is not available"
 end
 ```
 
+Leave the `else` off: the two branches cover an Option, and a value that is not one raises `NoMatchingPatternError` where an `else` would take it quietly. When that value is a Result, the error's message refuses to print; see the `case/in` note below. `deconstruct` answers `[value]` for a `Some` and `[]` for a `None`, the one-payload shape `Data.define(:value)` and Rust's tuple variants share, and there is no `deconstruct_keys`, because a one-payload sum type has no named field. Patterns nest through the inner value's own protocol instead: `in Ok(Some(value))` reaches through a Result, and `in Some({ id: })` reaches into a Hash a `Some` wraps.
+
+A bare `Some`, `None`, `Ok` or `Err`, without parentheses, is that name and not a value, where Rust's `return None` is one. It matches as the class it names in a pattern or a `case/when`, and refuses to stand in for a value: interpolation, `to_s`, `join`, `to_json` and `as_json` raise `Errgonomic::SerializeError` (`bare None names a variant for a pattern, not a value; build one with parentheses`), and so does handing one to an ActiveRecord attribute, a bulk write or a `where`. It is not a class, so `is_a?`, `kind_of?` and `instance_of?` raise `TypeError` when given the bare name (`class or module required`), `Some.new`, `Some <= Errgonomic::Option::Any` and `Some.name` raise `NoMethodError`, and Minitest's `assert_kind_of Some, x` raises the same `TypeError` before it can assert anything. Each has a working spelling: check the variant with `x.some?`, `x.none?`, `x.ok?` or `x.err?`, or give the fully qualified class anywhere a class or module is required, as in `x.is_a?(Errgonomic::Option::Some)`, `assert_kind_of Errgonomic::Option::Some, x`, `Errgonomic::Option::Some.new(1)`, `Errgonomic::Option::Some <= Errgonomic::Option::Any` or `Errgonomic::Option::Some.name`. Build with the constructor, `Some(1)`, rather than `.new`. An application constant of the same name collides loudly: defined before errgonomic loads, it stops the load with a `NameError`, and a `class None` or `module Ok` written after raises `TypeError` where it is written. Two forms get past that. `None = …` assigned after the load replaces the name with only Ruby's `already initialized constant` warning, and in a Rails application Zeitwerk skips an autoloaded `app/models/ok.rb` because `Ok` is already defined, so the first call on `Ok` raises `NoMethodError`.
+
 An unhandled Option refuses to leak into your output: `to_s`, `to_json` and `as_json` raise `Errgonomic::SerializeError`, so you handle the inner value deliberately rather than shipping `Some("...")` to a user. The refusal names what it was carrying (`cannot serialize an unwrapped Some("cell-a1b2")`), so a payload built out of many values says which one went unhandled; the value's `inspect` is bounded to 60 characters, with an ellipsis past that. The refusal covers `as_json` because Hash and Array serialization recurses through that method, and an Option nested in a payload would otherwise serialize as `{"value": ...}`. A converted ActiveRecord model is the one exception, at the model boundary: it unwraps each attribute as it serializes, so a record's own `as_json` says what an unconverted record's says. See [Rails integration](#rails-integration).
 
 The `to_s` refusal is the loudest guard of the three, because a string is where a wrapper turns into data: string interpolation, `Array#join`, `format`, `String()`, a bare ERB `<%= %>` and the key of a Hash on its way to JSON all reach the value through `to_s`, and every one of them raises rather than writing `Some("...")` into a hostname, a column or a page. Rust gives `Option` a `Debug` and no `Display`, and `inspect` is the `Debug` here: it renders `Some(1)`, and it is what a log line or a `rescue` should call (`"got #{opt.inspect}"`). The refusal says so: `Some(1) refuses to_s; use inspect for a log line, or unwrap_or / expect! for the value`.
@@ -144,7 +148,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).
 
@@ -172,11 +176,11 @@ Results also pattern match, including against the kind of inner value:
 
 ```ruby
 case result
-in Errgonomic::Result::Ok, value
+in Ok(value)
   "Measurement is #{value}"
-in Errgonomic::Result::Err, String => msg
+in Err(String => msg)
   "Measurement failed with a message: #{msg}"
-in Errgonomic::Result::Err, Exception => e
+in Err(Exception => e)
   "Measurement produced an exception -- #{e.class}: #{e}"
 end
 ```

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

@@ -2,6 +2,7 @@
 
 require 'set'
 require 'stringio'
+require_relative 'variant_name'
 
 module Errgonomic
   module Option
@@ -174,20 +175,65 @@ module Errgonomic
         [self.class, value].hash
       end
 
+      # The Rust shape: a Some deconstructs to its one payload and a None to
+      # nothing, so `in Some(v)` binds the value and `in None` matches. There
+      # is no deconstruct_keys, because a one-payload sum type has no named
+      # field; a Some wrapping a Hash nests as `in Some({id:})` through the
+      # Hash's own protocol.
+      #
       # @example
-      #   measurement = Errgonomic::Option::Some.new(1)
+      #   Some(1).deconstruct # => [1]
+      #   None().deconstruct # => []
+      #   Some(1).respond_to?(:deconstruct_keys) # => false
+      #
+      # @example a two-branch case/in with no else is exhaustive
+      #   measurement = Some(1)
       #   case measurement
-      #   in Errgonomic::Option::Some, value
-      #     "Measurement is #{measurement.value}"
-      #   in Errgonomic::Option::None
+      #   in Some(value)
+      #     "Measurement is #{value}"
+      #   in None
       #     "Measurement is not available"
-      #   else
-      #     "not matched"
       #   end # => "Measurement is 1"
+      #   case None()
+      #   in Some(value)
+      #     "Measurement is #{value}"
+      #   in None
+      #     "Measurement is not available"
+      #   end # => "Measurement is not available"
+      #
+      # @example the wrong type falls through to Ruby's own exhaustiveness check
+      #   begin
+      #     case 1
+      #     in Some(value) then value
+      #     in None then nil
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, e.message]
+      #   end # => [NoMatchingPatternError, "1"]
+      #
+      # @example a Result that falls through carries a message that refuses to print
+      #   begin
+      #     case Ok(1)
+      #     in Some(value) then value
+      #     in None then nil
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, (e.message rescue $!.class)]
+      #   end # => [NoMatchingPatternError, Errgonomic::SerializeError]
+      #
+      # @example patterns nest through the inner value's own protocol
+      #   case Ok(Some(1))
+      #   in Ok(Some(value)) then value
+      #   end # => 1
+      #   case Some({ id: 7, name: 'x' })
+      #   in Some({ id: }) then id
+      #   end # => 7
+      #   case Some(1)
+      #   in Errgonomic::Option::Some(value) then "bound #{value}"
+      #   else "not matched"
+      #   end # => "bound 1"
       def deconstruct
-        return [self, value] if some?
-
-        [Errgonomic::Option::None]
+        to_a
       end
 
       # Options order like Rust's: None sorts before any Some, and Somes
@@ -851,11 +897,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?
@@ -877,10 +959,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
@@ -907,3 +1007,8 @@ end
 def None
   Errgonomic::Option::None.new
 end
+
+# The variants under their short names, so a pattern reads as it does in
+# Rust: `in Some(v)`, `in None`.
+Errgonomic::VariantName.define(:Some, Errgonomic::Option::Some)
+Errgonomic::VariantName.define(:None, Errgonomic::Option::None)

data/lib/errgonomic/rails/active_record_optional.rb

@@ -516,10 +516,10 @@ module Errgonomic
     #   Errgonomic::Rails.unwrap_options(1) # => 1
     def self.unwrap_options(value)
       case value
-      when Errgonomic::Option::Any
-        value.unwrap_or(nil)
+      when Errgonomic::Option::Any, Errgonomic::VariantName
+        unwrap_option(value)
       when Array
-        value.any? { |v| v.is_a?(Errgonomic::Option::Any) } ? value.map { |v| unwrap_options(v) } : value
+        value.any? { |v| unwrapped_at_boundary?(v) } ? value.map { |v| unwrap_options(v) } : value
       else
         value
       end
@@ -527,13 +527,16 @@ module Errgonomic
 
     # Take the value inside an Option, and a None as nil, where the boundary
     # takes one value: an attribute is a single typed field, so a collection
-    # that happens to hold an Option is that collection.
+    # that happens to hold an Option is that collection. A bare variant name
+    # is refused here, since a boolean column would cast it to true.
     #
     # @example
     #   Errgonomic::Rails.unwrap_option(Some(1)) # => 1
     #   Errgonomic::Rails.unwrap_option(None()) # => nil
     #   Errgonomic::Rails.unwrap_option([Some(1)]) # => [Some(1)]
+    #   Errgonomic::Rails.unwrap_option(None) # => raise Errgonomic::SerializeError, "bare None names a variant for a pattern, not a value; build one with parentheses"
     def self.unwrap_option(value)
+      value.refuse! if value.is_a?(Errgonomic::VariantName)
       value.is_a?(Errgonomic::Option::Any) ? value.unwrap_or(nil) : value
     end
 
@@ -548,7 +551,7 @@ module Errgonomic
     #   plain = { title: 'x' }
     #   Errgonomic::Rails.unwrap_option_values(plain).equal?(plain) # => true
     def self.unwrap_option_values(hash)
-      return hash unless hash.each_value.any?(Errgonomic::Option::Any)
+      return hash unless hash.each_value.any? { |value| unwrapped_at_boundary?(value) }
 
       hash.transform_values { |value| unwrap_option(value) }
     end
@@ -561,11 +564,17 @@ module Errgonomic
     #   plain = [{ title: 'x' }]
     #   Errgonomic::Rails.unwrap_option_rows(plain).equal?(plain) # => true
     def self.unwrap_option_rows(rows)
-      return rows unless rows.any? { |row| row.is_a?(Hash) && row.each_value.any?(Errgonomic::Option::Any) }
+      return rows unless rows.any? { |row| row.is_a?(Hash) && row.each_value.any? { |v| unwrapped_at_boundary?(v) } }
 
       rows.map { |row| row.is_a?(Hash) ? unwrap_option_values(row) : row }
     end
 
+    # An Option, or a bare variant name, which a boundary refuses rather than
+    # let a column type cast it.
+    def self.unwrapped_at_boundary?(value)
+      value.is_a?(Errgonomic::Option::Any) || value.is_a?(Errgonomic::VariantName)
+    end
+
     # A declared default that is a Proc is not a value yet: ActiveModel calls
     # it with no arguments each time a record is built. Wrap it rather than
     # unwrap it, so what it returns meets the type where a literal default

data/lib/errgonomic/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'variant_name'
+
 module Errgonomic
   module Result
     # The base class for Result's Ok and Err class variants. We implement as
@@ -8,10 +10,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
@@ -454,29 +473,87 @@ module Errgonomic
         pp.text(inspect)
       end
 
-      # @example simple pattern match with variable capture of the value
-      #   result = Errgonomic::Result::Ok.new(1)
-      #   case result
-      #   in Errgonomic::Result::Ok, value
+      # The Rust shape: each variant deconstructs to its one payload, so
+      # `in Ok(v)` binds the value and `in Err(e)` binds the error. A
+      # value-less Err deconstructs to nothing: the sentinel behind it is
+      # internal and must never bind to a pattern variable.
+      #
+      # @example
+      #   Ok(1).deconstruct # => [1]
+      #   Err(:e).deconstruct # => [:e]
+      #   Err().deconstruct # => []
+      #   Ok(1).respond_to?(:deconstruct_keys) # => false
+      #
+      # @example a value-less Err matches `in Err` and `in Err()`, never `in Err(e)`
+      #   case Err()
+      #   in Err(e) then e
+      #   in Err then :no_value
+      #   end # => :no_value
+      #   case Err()
+      #   in Err() then :no_value
+      #   end # => :no_value
+      #   case Err(:x)
+      #   in Err(e) then e
+      #   in Err then :no_value
+      #   end # => :x
+      #   begin
+      #     case Err()
+      #     in Err(e) then e
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     e.class
+      #   end # => NoMatchingPatternError
+      #
+      # @example a two-branch case/in with no else is exhaustive
+      #   case Ok(1)
+      #   in Ok(value)
       #     "Measurement is #{value}"
-      #   in Errgonomic::Result::Err, err
+      #   in Err(err)
       #     "Measurement is not available"
       #   end # => "Measurement is 1"
       #
-      # @example more advanced pattern match against the kind of value
-      #   result = Errgonomic::Result::Err.new(StandardError.new("nope"))
+      # @example the wrong type falls through to Ruby's own exhaustiveness check
+      #   begin
+      #     case :done
+      #     in Ok(value) then value
+      #     in Err(err) then err
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, e.message]
+      #   end # => [NoMatchingPatternError, "done"]
+      #
+      # @example an Option that falls through carries a message that refuses to print
+      #   begin
+      #     case Some(1)
+      #     in Ok(value) then value
+      #     in Err(err) then err
+      #     end
+      #   rescue NoMatchingPatternError => e
+      #     [e.class, (e.message rescue $!.class)]
+      #   end # => [NoMatchingPatternError, Errgonomic::SerializeError]
+      #
+      # @example a pattern reaches the kind of value inside the variant
+      #   result = Err(StandardError.new("nope"))
       #   case result
-      #   in Errgonomic::Result::Ok, value
+      #   in Ok(value)
       #     "Measurement is #{value}"
-      #   in Errgonomic::Result::Err, String => msg
+      #   in Err(String => msg)
       #     "Measurement failed with a message: #{msg}"
-      #   in Errgonomic::Result::Err, Exception => e
+      #   in Err(Exception => e)
       #     "Measurement produced an exception -- #{e.class}: #{e}"
       #   end # => "Measurement produced an exception -- StandardError: nope"
       def deconstruct
-        [self, value]
+        return [] if value.equal?(Err::Arbitrary)
+
+        [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 +589,6 @@ module Errgonomic
 
     # The Ok variant.
     class Ok < Any
-      attr_accessor :value
-
       # Ok is always ok
       #
       # @example
@@ -544,13 +619,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
@@ -624,3 +697,8 @@ end
 def Err(value = Errgonomic::Result::Err::Arbitrary)
   Errgonomic::Result::Err.new(value)
 end
+
+# The variants under their short names, so a pattern reads as it does in
+# Rust: `in Ok(v)`, `in Err(e)`.
+Errgonomic::VariantName.define(:Ok, Errgonomic::Result::Ok)
+Errgonomic::VariantName.define(:Err, Errgonomic::Result::Err)

data/lib/errgonomic/variant_name.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Errgonomic
+  # What a bare `Some`, `None`, `Ok` or `Err` evaluates to. Rust writes a
+  # value as `return None`, where here the value is `None()`; the bare name
+  # is for patterns. It matches as the class it names, and refuses to become
+  # a string, so a missing pair of parentheses raises rather than writing a
+  # class name into a column. It is not a class, so an application's own
+  # `class None` fails where it is written instead of reopening the gem's.
+  #
+  # @example
+  #   case Some(1)
+  #   in Some(value) then value
+  #   end # => 1
+  #   None === None() # => true
+  #   None === Some(1) # => false
+  #   None.inspect # => "Errgonomic::Option::None"
+  #   "tier-#{None}" # => raise Errgonomic::SerializeError, "bare None names a variant for a pattern, not a value; build one with parentheses"
+  #   [Ok].join # => raise Errgonomic::SerializeError, "bare Ok names a variant for a pattern, not a value; build one with parentheses"
+  #   Some(1).is_a?(Some) # => raise TypeError, "class or module required"
+  #   Some(1).is_a?(Errgonomic::Option::Some) # => true
+  class VariantName
+    # Name a variant at top level, refusing a constant the application
+    # already holds there rather than replacing it.
+    def self.define(name, variant)
+      if Object.const_defined?(name, false)
+        existing = Object.const_get(name)
+        return if existing.is_a?(VariantName) && existing.names?(variant)
+
+        raise NameError.new("#{name} is already defined as #{existing.inspect}; errgonomic defines #{name} " \
+                            "at top level to name #{variant} in patterns, so rename the application's constant", name)
+      end
+      Object.const_set(name, new(name, variant))
+    end
+
+    def initialize(name, variant)
+      @name = name
+      @variant = variant
+      freeze
+    end
+
+    def names?(variant)
+      @variant.equal?(variant)
+    end
+
+    def ===(other)
+      @variant === other # rubocop:disable Style/CaseEquality
+    end
+
+    def inspect
+      @variant.inspect
+    end
+
+    # Refuse to stand in for a value.
+    def refuse!(*_args)
+      raise Errgonomic::SerializeError,
+            "bare #{@name} names a variant for a pattern, not a value; build one with parentheses"
+    end
+    alias to_s refuse!
+    alias to_json refuse!
+    alias as_json refuse!
+  end
+end

data/lib/errgonomic/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: errgonomic
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Nick Zadrozny
@@ -90,6 +90,7 @@ files:
 - lib/errgonomic/rails/active_record_optional.rb
 - lib/errgonomic/result.rb
 - lib/errgonomic/type.rb
+- lib/errgonomic/variant_name.rb
 - lib/errgonomic/version.rb
 - sig/errgonomic.rbs
 homepage: https://omc.io/