GEP-19

A type pattern matches if the switch value is an instance of the named type, binding a new local variable in the case body:

The bound name is narrowed to the declared type within the case body and any when guard. @CompileStatic and @TypeChecked see the narrowed type within the binding’s scope.

Record patterns deconstruct record-typed values positionally. Component positions accept nested patterns, including the unnamed pattern _:

Bare _ is permitted inside Type(…​) because record-pattern component grammar is not expression grammar. A call-shaped label is read as a record pattern only when its arguments are pattern-shaped, so case foo(), case foo(bar) and case lower('ABC') keep their legacy isCase semantics.

One narrow carve-out results. Argument forms such as var x do not parse today, so claiming them breaks nothing; bare does, because it is an ordinary identifier. A label spelled case Foo() ->, where the name is capitalised and is in scope as a variable, therefore changes meaning: it called Foo() before and is now read as a record pattern on the type Foo. The lower-case spelling case foo(_) -> is unaffected and still calls foo.

A value deconstructs positionally if it is a record — native or emulated, Groovy or Java — or if it provides a toList() method, which is the current spelling of the Deconstructable strategy (see Compilation).

List patterns destructure List, array, and Iterable values structurally. Element positions accept literals, type patterns, var/def bindings, nested patterns, and a single rest binding:

var and def are interchangeable in any binding position. The shortcut …​ is accepted for var…​ (and …​ ident for var…​ ident); see _Rest bindings below.

Element count rules:

Matching rules:

Type rules:

Map patterns destructure Map values by key. Keys are compile-time constants — identifier keys, string or number literals; a computed key (a parenthesised expression or GString) is a compile-time error in a map pattern, though it remains valid in a legacy map label. Values are arbitrary patterns; literal values (e.g. 'circle' below) match by Groovy equality (==):

Map pattern semantics are open: a pattern matches if all named keys are present and their value patterns match. Extra keys in the map are ignored unless captured by a rest binding. Closed semantics — "exactly these keys" — is expressed via a guard:

The rest binding var…​ rest in a map pattern binds a new Map of the entries not matched by named keys (the matched map is never aliased). A named key whose value pattern is a wildcard still requires the key to be present: [name: var _] matches a map with a name key whatever its value (even null), but not a map lacking one.

The empty list literal [] and empty map literal [:] in case-label position are always treated as patterns matching empty collections of the appropriate kind:

The legacy isCase semantics for these — never matching anything, because [].contains(x) and [:].get(x) are always false / null — have no practical use, so claiming the pattern interpretation removes no functionality. Because patterns require the arrow form, the reinterpretation applies to case [] -> and case [:] -> only; the colon-form spellings case []: and case [:]: keep their legacy never-matching meaning, so nothing that compiles today stops compiling.

The unnamed pattern matches any value without binding it. The form depends on context:

Rest bindings collect remaining elements into a single binding. The canonical form is var…​ ident (or def…​ ident / Type…​ ident), reusing Groovy’s existing varargs token sequence — the same shape as int…​ args in method parameter lists:

The var…​ t spelling reuses an existing Groovy token sequence (varargs in method declarations) and matches the shape Java is most likely to adopt for variadic deconstructor components — keeping the case List.of(var h, var…​ t) surface form (when Java specifies it) consistent with the list-literal form.

when guards apply to patterns:

Guards may reference any binding from the same pattern. Guards are evaluated once after pattern matching succeeds; arms with failing guards fall through to the next arm.

when guards apply to pattern labels only. A guard on a legacy-shaped label (e.g. case [1, 2, 3] when g ->, where the literal has no binding form) is a compile-time error rather than silently choosing between containment and equality semantics; adding a binding form makes the label a pattern.

Type patterns and record patterns extend to instanceof, mirroring Java:

List and map patterns are not valid in instanceof because they have no type at the head. To test "is this value shaped like …​", use a single-arm switch expression returning a boolean.

One divergence from Java in instanceof position: a primitive-typed record component (e.g. x in instanceof Point(int x, _)) binds its wrapper type (Integer), because the instanceof lowering lives in expression context where the primitive re-declaration used by the switch lowering is unavailable. In switch case labels the declared primitive type is bound, matching Java (JEP 440). The difference is only visible to the static type checker (e.g. overload selection); values are identical.

A […​] or [k: v, …​] case label is parsed as a structural pattern if and only if at least one of the following holds:

Otherwise, the label retains its legacy isCase semantics — exactly today’s behaviour.

The rule is parser-local and does not depend on surrounding scope. Every binding form listed above currently fails to parse as a Groovy expression in list-literal or map-literal value position, so claiming them as pattern grammar does not change the meaning of any program valid in Groovy 6.

The bare identifier _ continues to parse as an identifier in expression position — case [_] -> therefore retains its legacy meaning. Users wanting a single-element wildcard pattern write case [var _] ->.

A nested […​] element inside a pattern follows the same rule: a pattern-shaped nested literal is a nested pattern, while a plain nested literal (e.g. the inner [1, 2] in [[1, 2], var x]) is a literal element matched by equality.

In Groovy 7.0, def […​] = expr would accept the same pattern grammar as switch case labels. This is the bridge between switch and assignment destructuring:

The bracket form supports the full switch pattern grammar — nested patterns, type bindings with narrowing, wildcard _ (via var _ or def _), typed rest, and record patterns. A binding marker (var, def, a type, or …​ for rest) is required inside […​] for the same disambiguation reason it is in case labels: without one, the literal would parse as today’s legacy list literal.

The parens form (def (…​) = …​) is a separate, simpler grammar covered by GEP-20 and shipped in Groovy 6.x. It remains canonical for everyday destructuring (positional bindings, simple rest, map-style keys) and does not require var markers because the surrounding def already declares the names. The two forms coexist:

Two distinctions are worth keeping apart. What triggers the requirement is a pattern label and nothing else; what satisfies it is any coverage the compiler can prove, so a class-literal label can help satisfy a check that a pattern has triggered without being able to trigger one itself.

Whether case null should also trigger the requirement, as it does in Java, is left open. Java has that rule because case null is itself new in Java 21; in Groovy it is long-standing and matches today, so adopting the trigger would reject working code. See Remaining work.

A null subject is not an error, as set out under Features: it matches no constant or type label, so in statement position it falls through and in expression position it raises IllegalStateException, while a legacy case null label still matches it. Java instead throws NullPointerException unless a case null label is present. Groovy’s labels match through isCase, for which null is an ordinary value that simply matches nothing, so the Java behaviour is not adopted.

Every program valid in Groovy 6 compiles with identical semantics in Groovy 7, with the narrow carve-outs itemised below. The disambiguation rule is purely parser-local and is triggered only by syntactic forms that currently fail to parse:

Two […​] forms have legacy semantics that never usefully match — case [] → and case [:] → — and are reinterpreted as empty-list and empty-map patterns respectively. No existing program depends on these never-matching legacy forms.

Beyond the empty literals, the full list of carve-outs — forms that parse today and change meaning — is:

That is the complete list. Colon-form labels are deliberately not on it: a pattern requires the arrow form, so a colon-form label is never read as a pattern and keeps whatever it means today, including the never-matching case []: and case [:]:.

No realistic program relies on either legacy meaning; they are itemised for completeness.

Wildcard _ semantics introduced in this proposal apply inside […​] list and map patterns, and inside Type(…​) record patterns. The parens-form assignment def (…​) = expr (covered by GEP-20) continues to treat _ as a regular identifier indefinitely, matching GEP-20’s explicit non-deprecation. Existing idioms such as def (_, y, m) = Calendar.instance keep compiling unchanged with no warning in Groovy 7.

This scoping means GEP-19 introduces no behavioural break for any existing program: the wildcard semantics live in grammar ([…​] patterns, Type(…​) patterns) that does not parse today.

The coverage analysis is deliberately conservative in one place: record, list and map patterns never contribute to it, because a deconstruction can fail on arity or on a component even when its head type matches. The consequence is that a switch Java accepts as exhaustive can be rejected here. For example, with sealed interface S permits P and record P(Object o), the single arm case P(Object o) -> covers S in Java but not in the current analysis.

That argues against a single severity for every case:

Implementing recursive component coverage — a record pattern is unconditional for its type when all of its component patterns are — would let the third row move up to error.

Discussed in position and exhaustiveness. Adopting Java’s rule would reject working Groovy code; not adopting it leaves a visible difference from Java. Either way it should be a decision rather than an omission.

Groovy rejects all three inside a statement-position arrow arm, and has since the 4.0 parser; Java allows them. For constant labels the colon form is a workaround, but pattern labels require the arrow form, so under this proposal there is no way to return out of a matching arm. This is not caused by pattern matching, but pattern matching is what makes it hard to live with, so it should be fixed alongside.

Two items depend on it and neither is available below Java 21:

The reference implementation now checks exhaustiveness of a pattern switch statement, which was previously happening only by accident: before position became decisive, every arrow switch was an expression and so was checked on that path. The trigger deliberately keys on pattern labels alone, since reusing the expression check would demand a default from every switch statement in existence.