double calculateArea(Shape shape) {
  if (shape is Square) {
    return shape.length + shape.length;
  } else if (shape is Circle) {
    return math.pi * shape.radius * shape.radius;
  } else {
    throw ArgumentError("Unexpected shape.");
  }
}

Patterns

The core of this proposal is a new category of language construct called a
pattern. “Expression” and “statement” are both syntactic categories in the
grammar. Patterns form a third category. Like expressions and statements,
patterns are often composed of other subpatterns.

The basic idea with a pattern is that it:

• Can be tested against some value to determine if the pattern matches. If
  not, the pattern refutes the value. Some kinds of patterns, called
  “irrefutable patterns” always match.

• If (and only if) a pattern does match, the pattern may bind new variables in
  some scope.

Patterns appear inside a number of other constructs in the language. This
proposal extends Dart to allow patterns in:

• Top-level and local variable declarations.
• Static and instance field declarations.
• For loop variable declarations.
• Switch statement cases.
• A new switch expression form’s cases.

Binding and matching patterns

Languages with patterns have to deal with a tricky ambiguity. What does a bare
identifier inside a pattern mean? In some cases, you would like it declare a
variable with that name:

Here, a and b declare new variables. In other cases, you would like
identifiers to be references to constants so that you can refer to a constant
value in the pattern:

const a = 1;
const b = 2;

switch ([1, 2]) {
  case [a, b]: print("Got 1 and 2");
}

Here, a and b are references to constants and the pattern checks to see if
the value being switched on is equivalent to a list containing those two
elements.

This proposal follows Swift and addresses the ambiguity by
dividing patterns into two general categories binding patterns or binders
and matching patterns or matchers. (Binding patterns don’t always
necessarily bind a variable, but “binder” is easier to say than “irrefutable
pattern”.) Binders appear in irrefutable contexts like variable declarations
where the intent is to destructure and bind variables. Matchers appear in
contexts like switch cases where the intent is first to see if the value matches
the pattern or not and where control flow can occur when the pattern doesn’t
match.

Grammar summary

Before walking through them in detail, here is a short summary of the kinds of
patterns and where they can appear. There are three basic entrypoints into the
pattern grammar:

• matcher is the refutable patterns.

• binder is the irrefutable patterns.

• declarationBinder is a subset of the irrefutable
  patterns that make sense as the outermost pattern in a variable declaration.
  Subsetting allows reasonable code like:

  var [a, b] = [1, 2]; // List.
  var (a, b) = (1, 2); // Record.
  var {1: a} = {1: 2}; // Map.

  While avoiding strange uses like:

  var String str = 'redundant'; // Variable.
  var str as String = 'weird';  // Cast.
  var definitely! = maybe;      // Null-assert.

These entrypoints are wired into the rest of the language like so:

• A pattern variable declaration contains a
  declarationBinder.

• A switch case contains a matcher.

• A declarationMatcher pattern embeds a
  declarationBinder inside a refutable pattern. This is
  a convenience to let you avoid repeating var or final several times
  inside a matching pattern, as in:

  // List matcher containing three variable matchers:
  case [var a, var b, var c]:
  // Declaration matcher containing list binder
  // containing three variable binders:
  case var [a, b, c]:

  These two cases both do the same thing.

Many kinds of patterns have both matcher (refutable) and binder (irrefutable)
forms. The table below shows examples of every specific pattern type and which
categories it appears in:

Syntax

This proposal introduces a number different pattern forms and several places in
the language where they can be used.

Going top-down through the grammar, we start with the constructs where patterns
are allowed and then get to the patterns themselves.

Pattern variable declaration

Most places in the language where a variable can be declared are extended to
allow a pattern, like:

var (a, [b, c]) = ("str", [1, 2]);

Dart’s existing C-style variable declaration syntax makes it harder to
incorporate patterns. Variables can be declared just by writing their type, and
a single declaration might declare multiple variables. Fully incorporating
patterns into that could lead to confusing syntax like:

(int, String) (n, s) = (1, "str");
final (a, b) = (1, 2), c = 3, (d, e);

To avoid this weirdness, patterns only occur in variable declarations that begin
with a var or final keyword. Also, a variable declaration using a pattern
can only have a single declaration “section”. No comma-separated multiple
declarations like:

Also, declarations with patterns must have an initializer. This is not a
limitation since the point of using a pattern in a variable declaration is to
immediately destructure the initialized value.

Add these new rules:

patternDeclaration ::=
  | patternDeclarator declarationBinder '=' expression

patternDeclarator ::= 'late'? ( 'final' | 'var' )

TODO: Should we support destructuring in const declarations?

And incorporate the new rules into these existing rules:

topLevelDeclaration ::=
  | // Existing productions...
  | patternDeclaration ';' // New.

localVariableDeclaration ::=
  | initializedVariableDeclaration ';' // Existing.
  | patternDeclaration ';' // New.

forLoopParts ::=
  | // Existing productions...
  | ( 'final' | 'var' ) declarationBinder 'in' expression // New.

// Static and instance fields:
declaration ::=
  | // Existing productions...
  | 'static' patternDeclaration // New.
  | 'covariant'? patternDeclaration // New.

Switch statement

We extend switch statements to allow patterns in cases:

switchStatement ::= 'switch' '(' expression ')' '{' switchCase* defaultCase? '}'
switchCase      ::= label* caseHead ':' statements
caseHead        ::= 'case' matcher caseGuard?
caseGuard       ::= 'if' '(' expression ')'

Allowing patterns in cases significantly increases the expressiveness of what
properties a case can verify, including executing arbitrary user-defined code.
This implies that the order that cases are checked is now potentially
user-visible and an implementation must execute the first case that matches.

Guard clauses

We also allow an optional guard clause to appear after a case. This enables
a switch case to evaluate a secondary arbitrary predicate:

This is useful because if the guard evaluates to false then execution proceeds
to the next case, instead of exiting the entire switch like it would if you
had nested an if statement inside the switch case.

Implicit break

A long-running annoyance with switch statements is the mandatory break
statements at the end of each case body. Dart does not allow fallthrough, so
these break statements have no real effect. They exist so that Dart code does
not appear to be doing fallthrough to users coming from languages like C that
do allow it. That is a high syntactic tax for limited benefit.

I inspected the 25,014 switch cases in the most recent 1,000 packages on pub
(10,599,303 LOC). 26.40% of the statements in them are break. 28.960% of the
cases contain only a single statement followed by a break. This means
break is a fairly large fraction of the statements in all switches for
marginal benefit.

Therefore, this proposal removes the requirement that each non-empty case body
definitely exit. Instead, a non-empty case body implicitly jumps to the end of
the switch after completion. From the spec, remove:

If s is a non-empty block statement, let s instead be the last statement
of the block statement. It is a compile-time error if s is not a break,
continue, rethrow or return statement or an expression statement where the
expression is a throw expression.

This is now valid code that prints “one”:

switch (1) {
  case 1:
    print("one");
  case 2:
    print("two");
}

Empty cases continue to fallthrough to the next case as before:

This prints “one or two”:

switch (1) {
  case 1:
  case 2:
    print("one or two");
}

Switch expression

When you want an if statement in an expression context, you can use a
conditional expression (?:). There is no expression form for multi-way
branching, so we define a new switch expression. It takes code like this:

Color shiftHue(Color color) {
  switch (color) {
    case Color.red:
      return Color.orange;
    case Color.orange:
      return Color.yellow;
    case Color.yellow:
      return Color.green;
    case Color.green:
      return Color.blue;
    case Color.blue:
      return Color.purple;
    case Color.purple:
      return Color.red;
  }
}

And turns it into:

switch (json) {
  case [int x, int y]:
    return Point(x, y);
}

if (case [int x, int y] = json) return Point(x, y);

if (case [int x, int y] = json) {
  print('Was coordinate array $x,$y');
} else {
  throw FormatException('Invalid JSON.');
}

ifCaseStatement ::= 'if' '(' 'case' matcher '=' expression ')'
                         statement ('else' statement)?

declarationBinder ::=
| listBinder
| mapBinder
| recordBinder

binder
| declarationBinder
| wildcardBinder
| variableBinder
| castBinder
| nullAssertBinder

binders ::= binder ( ',' binder )* ','?

recordBinder        ::= '(' recordFieldBinders ')'

recordFieldBinders  ::= recordFieldBinder ( ',' recordFieldBinder )* ','?
recordFieldBinder   ::= ( identifier ':' )? binder
                      | identifier ':'

var (first: first, second: second) = (first: 1, second: 2);
var (first:, second:) = (first: 1, second: 2);

var list = [1, 2, 3];
var [_, two, _] = list;

variableBinder ::= typeWithBinder? identifier

castBinder ::= identifier "as" type

num n = 1;
var i as int = n; // Instead of this...
var i = n as int; // ...do this.

(num, Object) record = (1, "s");
var (i as int, s as String) = record;

nullAssertBinder ::= binder '!'

matcher ::=
  | literalMatcher
  | constantMatcher
  | wildcardMatcher
  | listMatcher
  | mapMatcher
  | recordMatcher
  | variableMatcher
  | declarationMatcher
  | extractMatcher
  | nullCheckMatcher

literalMatcher ::=
  | booleanLiteral
  | nullLiteral
  | numericLiteral
  | stringLiteral

const a = 1;
const b = 2;
var obj = [1, 2]; // Not const.

switch (obj) {
  case [a, b]: print("match"); break;
  default: print("no match");
}

constantMatcher ::= qualified ( "." identifier )?

mapMatcher ::= mapTypeArguments? '{' mapMatcherEntries '}'

mapMatcherEntries ::= mapMatcherEntry ( ',' mapMatcherEntry )* ','?
mapMatcherEntry ::= expression ':' matcher

recordMatcher ::= '(' recordFieldMatchers ')'

recordFieldMatchers ::= recordFieldMatcher ( ',' recordFieldMatcher )* ','?
recordFieldMatcher  ::= ( identifier ':' )? matcher
                      | identifier ':'

switch (obj) {
  case (first: final first, second: final second): ...
  case (first:, second:): ...
}

variableMatcher ::= ( 'final' | 'var' | 'final'? typeWithBinder ) identifier

declarationMatcher ::= ( "var" | "final" ) declarationBinder

switch (obj) {
  // Instead of:
  case [var a, var b, var c]: ...

  // Can use:
  case var [a, b, c]: ...
}

class Rect {
  final double width, height;
  Rect(this.width, this.height);
}

display(Object obj) {
  switch (obj) {
    case Rect(var width, var height):
      print('Rect $width x $height');
    case _:
      print(obj);
  }
}

enum Severity  {
  error(1, "Error"),
  warning(2, "Warning");

  Severity(this.level, this.prefix);

  final int level;
  final String prefix;
}

log(Severity severity, String message) {
  switch (severity) {
    case Severity.error(_, prefix):
      print('!! $prefix !! $message'.toUppercase());
    case Severity.warning(_, prefix):
      print('$prefix: $message');
  }
}

extractMatcher ::= extractName typeArgumentsOrBinders? "(" recordFieldMatchers ")"
extractName    ::= typeIdentifier | qualifiedName

nullCheckMatcher ::= matcher '?'

String? maybeString = ...
if (case var s? = maybeString) {
  // s has type String here.
}

var (a, int b) = ... // Schema is `(?, int)`.