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.

A record with no components is matched by empty parentheses:

Empty parentheses form a pattern only after a capitalised type name, optionally qualified (case Opt.None() ->), so case foo() remains a call.

Two narrow carve-outs result. 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. Likewise case Foo() ->, where Foo names a zero-argument method, called Foo() before and is now a zero-component record pattern. The lower-case spellings case foo(_) -> and case foo() -> are unaffected and still call foo. To keep a call to a capitalised method, quote its name or give it a receiver: case 'Foo'() -> or case this.Foo() ->. A GString name, as in case "$name"() ->, is always a call.

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.

Any of the following satisfies it:

A pattern counts toward coverage only when it provably matches every value of its type:

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.

The MatchException choice is made from the target bytecode, not from the JDK running the compiler or the program. The exception is referenced by name in the generated code, so a class compiled for 21 throws it on every JDK it can load on, and a class compiled for 17 never does. This needs no change to Groovy’s minimum JDK. Neither exception is meant to be caught; a default arm that throws gives a defined exception on every target.

A null subject is not an error, as set out under Features: it is matched only by an explicit case null label, and otherwise in statement position it falls through and in expression position it raises IllegalStateException, on every target. 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 [:]:, and case Foo():, which is still a call in a switch statement or a switch expression.

No realistic program relies on the first two legacy meanings; they are itemised for completeness. The third is the one with real exposure, which is why it is a compile-time error rather than a silent change.

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 reference implementation reports a non-exhaustive pattern switch statement as an error, following JEP 441. The alternatives are a warning, or no check at all, so that an unmatched value falls through silently as in every other Groovy statement. Erroring costs no compatibility, since pattern syntax is new, and matches Java. Whichever is chosen applies only to type-checked code: dynamic Groovy has no exhaustiveness analysis, so a non-exhaustive pattern statement falls through there either way.

This is the one place where the coverage analysis still rejects a switch Java accepts. With sealed interface S permits P and record P(Object o), the single arm case P(Object o) -> covers S in Java, because there a nested type pattern that is total for the component type also matches null. Under this proposal a typed element does not match a null component (see Features), so the pattern can fail and a default is required. Adopting Java’s rule would mean a typed element matches null exactly when its type is total for the component, which is a decision about null semantics inside patterns rather than about exhaustiveness.

A pattern dominated by an earlier label is a warning here and an error in Java. GROOVY-12447 already makes an exact duplicate type label an error, so case Circle after case Circle is an error while case Circle c after case Shape s is a warning. The two should probably agree.

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.