Merge issue-1699-union-grouping: combine "&" and "[A | B]" into one PR

Combines intersection type support ("A & B", from lsegal#1700) with grouped-
union support ("[A | B]", from lsegal#1702) into a single PR, per review
feedback, and fixes an integration bug the merge surfaced: the
grouping syntax's "|" handler pushed its type directly instead of
routing through finish_intersection, which would have silently
dropped any pending "&" conjuncts when a group boundary was hit (e.g.
in "[Foo & Bar | Baz]").

Also fixes a real English-rendering ambiguity in the combined output:
GroupType wraps its whole member list in one pair of parens, but
IntersectionType (and a multi-method DuckType, "#foo & #bar") render
as a bare "X and Y" with no punctuation of their own. Sitting next to
a sibling in the group's "or"-joined list, that read ambiguously
("a Foo and a Bar or a Baz" doesn't show which operator binds
tighter) even though the parse itself was correct. GroupType now adds
defensive parens around exactly those two cases.

Documents operator precedence explicitly: "&" always binds tighter
than whichever separator surrounds it ("," at the top level, "|"
inside "[...]"); "|" is only valid inside "[...]"; "," is never valid
inside "[...]". Adds end-to-end specs combining both operators,
including the precedence and disambiguation cases above.

Author: apiology

CHANGELOG.md

@@ -1,6 +1,8 @@
 # main
 
-- Add support for intersection types (`Foo & Bar`) in tag type lists (closes #1644)
+- Add support for intersection (`Foo & Bar`) and grouped-union
+  (`[Foo | Bar]`) syntax in tag type lists (closes #1644, #1699); document
+  the existing anonymous `<A>`, `(A)`, and `{A=>B}` shorthand forms
 - Fix duplicate "View source" links after client-side navigation in default HTML template
 
 # [0.9.45] - July 14th, 2026

docs/Tags.md

@@ -182,6 +182,9 @@ a list of parametrized types can occur in any order inside of a type. An array
 specified as `Array<String, Fixnum>` can contain any amount of Strings or Fixnums,
 in any order. When the order matters, use "order-dependent lists", described below.
 
+The type name before `<...>` can be omitted, in which case it defaults to
+`Array`: `<String, Fixnum>` means the same thing as `Array<String, Fixnum>`.
+
 #### Duck-Types
 
 Duck-types are allowed in type specifier lists, and are identified by method
@@ -238,13 +241,55 @@ Keys in the hash-specific syntax are commonly [literal values](#Literals) such
 as symbols (`:key`) or strings (`'key'`, `"key"`), but any type listed in the
 [type conventions](#Type_List_Conventions) is allowed.
 
+The type name before `{...}` can be omitted, in which case it defaults to
+`Hash`: `{K=>V}` means the same thing as `Hash{K=>V}`.
+
 #### Order-Dependent Lists
 
 An order dependent list is a set of types surrounded by "()" and separated by
 commas. This list must contain exactly those types in exactly the order specified.
 For instance, an Array containing a String, Fixnum and Hash in that order (and
 having exactly those 3 elements) would be listed as: `Array(String, Fixnum, Hash)`.
 
+The type name before `(...)` can be omitted, in which case it defaults to
+`Array`: `(String, Fixnum, Hash)` means the same thing as
+`Array(String, Fixnum, Hash)`.
+
+#### Grouped Unions
+
+A comma inside an order-dependent list already means "next slot," so there's no
+way to write "a slot that can be either of two types" using a comma there - and
+the same problem applies to any other position where `,` already has a
+different meaning. Wrapping a `|`-separated list in square brackets (`[...]`)
+groups it into a single union type that can be used anywhere a type is
+expected, including as one slot of an order-dependent list:
+`Array([Integer | String], Symbol)` describes a 2-element Array whose first
+element is an `Integer` or a `String`, followed by a `Symbol`.
+
+`[...]` is dedicated entirely to this grouping; unlike `<...>`, `(...)`, and
+`{...}`, it never takes a preceding type name and is never itself a
+collection - `[Integer | String]` alone just means "an Integer or a String",
+identical in meaning to the plain top-level list `Integer, String`, just
+usable in more places. `|` is only meaningful inside `[...]`, and a plain `,`
+is not allowed inside `[...]` - a top-level type list already uses `,` for
+the same "either of these" meaning, so there is no need for two spellings of
+it in the same position.
+
+#### Operator Precedence
+
+`&`, `,`, and `|` can all appear in the same type, and each means something
+different depending on where it's used, so here's how they combine:
+
+* `&` always binds tighter than whichever separator surrounds it - `,` at
+  the top level, or `|` inside `[...]`. `Foo & Bar, Baz` means
+  `(Foo & Bar), Baz`, and `[Foo & Bar | Baz]` means `[(Foo & Bar) | Baz]`,
+  not `Foo & (Bar, Baz)` or `Foo & [Bar | Baz]`.
+* `|` only has meaning inside `[...]` - anywhere else, it's not valid syntax.
+* `,` is not valid inside `[...]` - use `|` there instead.
+* `[...]` can nest inside itself (`[[Foo | Bar] | Baz]`), and can be used
+  as one conjunct of an intersection in either order
+  (`[Foo | Bar] & Baz`, `Baz & [Foo | Bar]`).
+
 #### Literals
 
 Some literals are accepted by virtue of being Ruby literals, but also by YARD

lib/yard/tags/types_explainer.rb

@@ -82,6 +82,37 @@ def to_s(singular = true)
         end
       end
 
+      # @private
+      class GroupType < Type
+        attr_accessor :types
+
+        def initialize(types)
+          @types = types
+        end
+
+        def to_s(singular = true)
+          "(" + list_join(types.map {|t| disambiguate(t, singular) }) + ")"
+        end
+
+        private
+
+        # {IntersectionType} and a multi-method {DuckType} (`#foo & #bar`)
+        # both render as a bare "X and Y", with no punctuation of their own
+        # to mark where they end. Sitting next to a sibling in this group's
+        # own "or"-joined list, that reads ambiguously (e.g. "a Foo and a
+        # Bar or a Baz" doesn't show whether the "and" or the "or" binds
+        # tighter) even though the parse itself is unambiguous. Wrap those
+        # two cases in their own parens so the group's members are visually
+        # self-delimiting; every other {Type} already is (a bare name, or
+        # something with its own bracketing like {GroupType} itself).
+        def disambiguate(type, singular)
+          rendered = type.to_s(singular)
+          needs_parens = type.is_a?(IntersectionType) ||
+                         (type.is_a?(DuckType) && type.name.include?('&'))
+          needs_parens ? "(#{rendered})" : rendered
+        end
+      end
+
       # @private
       class CollectionType < Type
         attr_accessor :types
@@ -167,10 +198,13 @@ class Parser
           :collection_end => />/,
           :fixed_collection_start => /\(/,
           :fixed_collection_end => /\)/,
+          :group_start => /\[/,
+          :group_end => /\]/,
           :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|#{LITERALMATCH}|\w+/,
           :symbol => /:#{METHODNAMEMATCH}/,
           :type_next => /[,]/,
           :intersect => /&/,
+          :union_sep => /\|/,
           :whitespace => /\s+/,
           :hash_collection_start => /\{/,
           :hash_collection_value => /=>/,
@@ -195,7 +229,26 @@ def parse(until_tokens: [:parse_end])
 
         private
 
-        def parse_until(until_tokens)
+        # @param allow_pipe [Boolean] whether a bare `|` is a legal separator
+        #   in this scope. Only true directly inside `[...]`, YARD's grouping
+        #   syntax: it lets a union be nested as a single type wherever a
+        #   type is expected, including inside constructs where `,` already
+        #   has a different meaning (an order-dependent list's positional
+        #   slots). `,` is not allowed inside `[...]` (and `|` is not allowed
+        #   anywhere else) - the two are never legal in the same scope, so
+        #   there is nothing to disambiguate between them.
+        # @param allow_comma [Boolean] whether a bare `,` is a legal separator
+        #   in this scope. False only directly inside `[...]`.
+        #
+        # `&` (intersection) is handled orthogonally to both of the above via
+        # `intersection_conjuncts`/{#finish_intersection} - it is legal
+        # anywhere a type is expected (top-level, inside `<...>`/`(...)`,
+        # and inside `[...]` alongside `|`), and always binds tighter than
+        # whichever separator (`,` or `|`) is active in the current scope:
+        # `A & B, C` is `(A & B), C`, and `[A & B | C]` is `[(A & B) | C]`.
+        # @return [Array(Array<Type>, Symbol)] the parsed types and the
+        #   token that ended the list
+        def parse_until(until_tokens, allow_pipe: false, allow_comma: true)
           current_parsed_types = []
           type = nil
           name = nil
@@ -221,17 +274,31 @@ def parse_until(until_tokens)
               name = nil
               type = nil
             when :type_next
+              raise SyntaxError, "',' is not allowed inside '[...]' groups" unless allow_comma
               raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
               type = create_type(name) unless type
               current_parsed_types << finish_intersection(intersection_conjuncts, type)
               intersection_conjuncts = []
               name = nil
               type = nil
+            when :union_sep
+              raise SyntaxError, "'|' is only allowed inside '[...]' groups" unless allow_pipe
+              raise SyntaxError, "expecting name, got '|' at #{@scanner.pos}" if name.nil?
+              type = create_type(name) unless type
+              current_parsed_types << finish_intersection(intersection_conjuncts, type)
+              intersection_conjuncts = []
+              name = nil
+              type = nil
             when :fixed_collection_start, :collection_start
               name ||= "Array"
               klass = token_type == :collection_start ? CollectionType : FixedCollectionType
               nested_types, = parse_until([:fixed_collection_end, :collection_end, :parse_end])
               type = klass.new(name, nested_types)
+            when :group_start
+              raise SyntaxError, "'[' cannot follow a type name" if name
+              nested_types, = parse_until([:group_end, :parse_end], allow_pipe: true, allow_comma: false)
+              type = GroupType.new(nested_types)
+              name = "Group"
             when :hash_collection_start
               name ||= "Hash"
               type = parse_hash_collection(name)

spec/tags/types_explainer_spec.rb

@@ -85,6 +85,37 @@ def type(name)
     end
   end
 
+  describe YARD::Tags::TypesExplainer::GroupType, '#to_s' do
+    it "works for two types" do
+      group = described_class.new([type("Foo"), type("Bar")])
+      expect(group.to_s).to eq "(a Foo or a Bar)"
+      expect(group.to_s(false)).to eq "(Foos or Bars)"
+    end
+
+    it "works for more than two types" do
+      group = described_class.new([type("Foo"), type("Bar"), type("Baz")])
+      expect(group.to_s).to eq "(a Foo, a Bar or a Baz)"
+    end
+
+    it "adds defensive parens around an IntersectionType member" do
+      intersection = YARD::Tags::TypesExplainer::IntersectionType.new([type("Foo"), type("Bar")])
+      group = described_class.new([intersection, type("Baz")])
+      expect(group.to_s).to eq "((a Foo and a Bar) or a Baz)"
+    end
+
+    it "adds defensive parens around a multi-method DuckType member" do
+      duck = YARD::Tags::TypesExplainer::DuckType.new("#foo & #bar")
+      group = described_class.new([duck, type("Baz")])
+      expect(group.to_s).to eq "((an object that responds to #foo and #bar) or a Baz)"
+    end
+
+    it "does not add extra parens around a single-method DuckType member" do
+      duck = YARD::Tags::TypesExplainer::DuckType.new("#foo")
+      group = described_class.new([duck, type("Baz")])
+      expect(group.to_s).to eq "(an object that responds to #foo or a Baz)"
+    end
+  end
+
   describe YARD::Tags::TypesExplainer::LiteralType, '#to_s' do
     it "works for literal values" do
       [':symbol', "'5'"].each do |name|
@@ -216,6 +247,36 @@ def parse_fail(types)
       expect(type.first.name).to eq "Array"
     end
 
+    it "parses a grouped union inside square brackets as a GroupType" do
+      type = parse("[String | Symbol]")
+      expect(type.first).to be_a(YARD::Tags::TypesExplainer::GroupType)
+      expect(type.first.types.map(&:name)).to eq ["String", "Symbol"]
+    end
+
+    it "allows a grouped union as a fixed-tuple slot" do
+      type = parse("Array([String | Symbol], Integer)")
+      expect(type.first).to be_a(YARD::Tags::TypesExplainer::FixedCollectionType)
+      expect(type.first.types.first).to be_a(YARD::Tags::TypesExplainer::GroupType)
+      expect(type.first.types.first.types.map(&:name)).to eq ["String", "Symbol"]
+      expect(type.first.types.last.name).to eq "Integer"
+    end
+
+    it "does not allow '|' outside of square brackets" do
+      parse_fail "String | Symbol"
+    end
+
+    it "does not allow '|' inside a collection type" do
+      parse_fail "Array<String | Symbol>"
+    end
+
+    it "does not allow ',' inside square brackets" do
+      parse_fail "[String, Symbol]"
+    end
+
+    it "does not allow '[' to follow a type name" do
+      parse_fail "Foo[String]"
+    end
+
     it "allows a hash collection type without a name" do
       type = parse("{K=>V}")
       expect(type.first.name).to eq "Hash"
@@ -306,5 +367,65 @@ def parse_fail(types)
         expect(explain).to eq expected.delete("\n").squeeze(' ')
       end
     end
+
+    it "parses grouped unions (`[A | B]`)" do
+      expect = {
+        # standalone, redundant with a plain top-level union, but legal
+        "[Integer | String]" => "(an Integer or a String)",
+        # the motivating case: a union in a fixed-tuple slot, which `,`
+        # can't express there since it already means "next slot"
+        "Array([Integer | String], Symbol)" =>
+          "an Array containing ((an Integer or a String) followed by a Symbol)",
+        "Hash{String => [Integer | Symbol]}" =>
+          "a Hash with keys made of (Strings) and values of ((Integers or Symbols))"
+      }
+      expect.each do |input, expected|
+        explain = YARD::Tags::TypesExplainer.explain(input)
+        expect(explain).to eq expected.delete("\n").squeeze(' ')
+      end
+    end
+
+    it "composes `&` and `[A | B]` together, with `&` binding tighter than `|`" do
+      expect = {
+        # a group used as one conjunct of an intersection
+        "[Integer | String] & Comparable" => "(an Integer or a String) and a Comparable",
+        "Comparable & [Integer | String]" => "a Comparable and (an Integer or a String)",
+        # `&` binds tighter than `|` *inside* a group too, matching how it
+        # already binds tighter than `,` everywhere else: `A & B | C` inside
+        # `[...]` groups parses as `(A & B) | C`, not `A & (B | C)`. The
+        # `&`-joined conjunct has no punctuation of its own to mark where it
+        # ends, so the group adds defensive parens around it (only) to keep
+        # the English rendering unambiguous, matching the real parse tree.
+        "[Foo & Bar | Baz]" => "((a Foo and a Bar) or a Baz)",
+        "[Foo | Bar & Baz]" => "(a Foo or (a Bar and a Baz))",
+        # duck-types inside a group are NOT collapsed the way `&`-joined ones
+        # are - grouping is a real alternative ("either responds to #foo, or
+        # responds to #bar"), not the same method-list convention. But a
+        # multi-method duck-type (already `&`-collapsed before the `|` is
+        # seen) gets the same defensive-parens treatment as `&` above.
+        "[#foo | #bar]" => "(an object that responds to #foo or an object that responds to #bar)",
+        "[#foo & #bar | #baz]" =>
+          "((an object that responds to #foo and #bar) or an object that responds to #baz)",
+        # a group nested inside another group's slot - GroupType always
+        # parenthesizes itself, so no extra disambiguation is needed here
+        "Array([[Integer | String] | Symbol], Number)" =>
+          "an Array containing (((an Integer or a String) or a Symbol) followed by a Number)"
+      }
+      expect.each do |input, expected|
+        explain = YARD::Tags::TypesExplainer.explain(input)
+        expect(explain).to eq expected.delete("\n").squeeze(' ')
+      end
+    end
+
+    it "does not allow ',' or bare '|' to leak across the '&'/'[...]' boundary" do
+      # '&' never needs '[...]' - it's legal (and binds tightest) everywhere
+      expect(YARD::Tags::TypesExplainer.explain("Array<Foo & Bar, Baz>")).to eq(
+        "an Array of (Foos and Bars or Bazs)"
+      )
+      # but a bare '|' still requires '[...]' even next to a valid '&' usage
+      expect(YARD::Tags::TypesExplainer.explain("Foo & Bar | Baz")).to be_nil
+      # and ',' still can't cross into a '[...]' group just because '&' is nearby
+      expect(YARD::Tags::TypesExplainer.explain("[Foo & Bar, Baz]")).to be_nil
+    end
   end
 end