Class: Rigor::Type::Union

Inherits:
Object
  • Object
show all
Includes:
AcceptanceRouter, ValueSemantics
Defined in:
lib/rigor/type/union.rb

Overview

A normalized non-empty union of two or more distinct types. Unions are constructed exclusively through Rigor::Type::Combinator.union, which flattens nested unions, deduplicates structurally-equal members, and collapses single-member or empty results to the appropriate scalar type. Direct calls to .new are an internal contract: callers MUST pass an already-normalized members array.

See docs/type-specification/normalization.md.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ValueSemantics

included

Methods included from AcceptanceRouter

#accepts

Constructor Details

#initialize(members) ⇒ Union

Returns a new instance of Union.



20
21
22
23
24
25
26
27
 
# File 'lib/rigor/type/union.rb', line 20

def initialize(members)
  unless members.is_a?(Array) && members.size >= 2
    raise ArgumentError, "Union requires at least two members; use Combinator.union for normalization"
  end

  @members = members.freeze
  freeze
end

Instance Attribute Details

#members ⇒ Object (readonly)

Returns the value of attribute members.



18
19
20
 
# File 'lib/rigor/type/union.rb', line 18

def members
  @members
end

Instance Method Details

#bot ⇒ Object 



83
84
85
 
# File 'lib/rigor/type/union.rb', line 83

def bot
  Trinary.no
end

#describe(verbosity = :short) ⇒ Object

Display-only adoption of two concise RBS spellings for the union (see docs/type-specification/normalization.md § “Interaction with display” and rbs-compatible-types.md § “Optionals”). Both are purely cosmetic: ‘@members` keeps every carrier verbatim, so the underlying type identity, RBS erasure, and round-trip are unchanged — only the human-facing rendering reads like the RBS the user wrote.

* `true | false`           → `bool`   (the RBS boolean alias). The
  `bool` token leads the rendering, so `false | Foo | true` reads
  as `bool | Foo` rather than burying the pair mid-list.
* `T | nil`                → `T?`     (the RBS optional sugar). Only
  applied when exactly one *logical* member remains beside `nil`,
  matching the rbs gem's own `to_s`: a multi-member union such as
  `Integer | String | nil` stays explicit rather than gaining a
  parenthesised `(Integer | String)?`. The two collapses compose,
  so `false | true | nil` reads as `bool?`.



45
46
47
48
49
50
51
52
53
54
 
# File 'lib/rigor/type/union.rb', line 45

def describe(verbosity = :short)
  return "#{optional_inner(verbosity)}?" if optional?

  if boolean_pair?
    rest = members.reject { |m| boolean_literal?(m) }
    ["bool", *rest.map { |m| m.describe(verbosity) }].join(" | ")
  else
    members.map { |m| m.describe(verbosity) }.join(" | ")
  end
end

#dynamic ⇒ Object 



87
88
89
 
# File 'lib/rigor/type/union.rb', line 87

def dynamic
  members.any? { |m| m.respond_to?(:dynamic) && m.dynamic.yes? } ? Trinary.maybe : Trinary.no
end

#erase_to_rbs ⇒ Object

ADR-1 § “RBS round-trip is lossless” + the value-lattice rule ‘untyped | T = untyped` (every `T` is gradually consistent with `untyped`). When any union member erases to `“untyped”`, the whole union erases to `“untyped”` —the RBS surface has no carrier for “Dynamic-origin alongside a static facet”, and the gradual-consistency contract guarantees the substitution is sound at every call site.

Post-erasure dedupe removes ‘String | String` artefacts that arise when two structurally-distinct `Constant` carriers (e.g. `Constant<“Alice”>` / `Constant<“Bob”>`) share an RBS-erased envelope. The members themselves are already structurally deduped at construction by `Type::Combinator.union`, but the post-erase strings can collide.



72
73
74
75
76
77
 
# File 'lib/rigor/type/union.rb', line 72

def erase_to_rbs
  erased = members.map(&:erase_to_rbs)
  return "untyped" if erased.include?("untyped")

  erased.uniq.join(" | ")
end

#inspect ⇒ Object 



97
98
99
 
# File 'lib/rigor/type/union.rb', line 97

def inspect
  "#<Rigor::Type::Union #{describe(:short)}>"
end

#top ⇒ Object 



79
80
81
 
# File 'lib/rigor/type/union.rb', line 79

def top
  Trinary.no
end