Add spec section for given patterns reflecting existing semantics

[yilinwei]

This needs #19718 to test locally from a fresh docker build.

[yilinwei]

I have not put a link here, because the implicit section has not been updated to reflect given/using yet and I do not know whether I should link to https://docs.scala-lang.org/scala3/reference/contextual/relationship-implicits.html.

[sjrd]

The parser considers that this a case of SimplePattern:
https://github.com/lampepfl/dotty/blob/7f410aa1b5cbb38dc4c51da0b5772c7babfaabf0/compiler/src/dotty/tools/dotc/parsing/Parsers.scala#L3026

Also, we should update docs/_docs/internals/syntax.md at the same time, to keep them in sync.

[sjrd]

I don't understand what the last part of the sentence means, starting from "to the scope". It does not appear to be grammatically correct, or it's grammatically ambiguous at best. Rephrase?

[sjrd]

What if the corresponding scrutinee is not statically known to have the type TypePat? Is that a compile error or a no-match at run-time?

[yilinwei]

@sjrd I was trying to refer to the scope of the case clause - is the term local scope fine?

I think that in the case that the scrutinee is known statically or not statically should be the same as for a TypePat without a given modifier.

Currently,

val x = 1
val y = x match {
  case y: String => ???
}

gives a compile error and

val x = "asd"

def foo[A](a: A): Unit = {
  a match {
    case s: Int=> 1
  }
}

foo(x)

Is a runtime error.

[sjrd]

Link?

[yilinwei]

Currently, it does not exist in the spec; can I link to the reference in the spec or not?

[sjrd]

This example does not illustrate that we statically receive an Int. Include a val x: Int = summon[List[Int]].head?

[yilinwei]

Sure, the return type is Int of the function, but I can introduce a val if it would make it clearer.

[som-snytt]

scala 2

scala> List(42) match { case xs @ (_: List[_]) => xs }
val res1: List[Any] = List(42)

scala 3

scala> List(42) match { case xs @ (_: List[_]) => xs }
val res0: List[Int] = List(42)

I'm not sure if scala 2 is plain wrong here. So any clarification would be helpful.
Oh nm it's REPL output bc:

scala> val ys: List[Int] = List(42) match { case xs @ (_: List[_]) => xs }
val ys: List[Int] = List(42)

but that goes to my point that a) a semi-casual reader might not have a preconceived notion and b) if I try it in the REPL, REPL may let me down, so I rely on your examples before giving up.

[sjrd]

Sure, the return type is Int of the function, but I can introduce a val if it would make it clearer.

The reader of the spec does know that, and does not have an IDE or REPL to prove it. So yes, a val with an expected type would make it a lot clearer.