Use soft keyword throws instead of canThrow

Author: odersky

compiler/src/dotty/tools/dotc/ast/Desugar.scala

@@ -1261,6 +1261,14 @@ object desugar {
       makeOp(left, right, Span(left.span.start, op.span.end, op.span.start))
   }
 
+  /** Translate throws type `A throws E1 | ... | En`
+   */
+  def throws(tpt: Tree, op: Ident, excepts: Tree)(using Context): AppliedTypeTree = excepts match
+    case InfixOp(l, bar @ Ident(tpnme.raw.BAR), r) =>
+      throws(throws(tpt, op, l), bar, r)
+    case e =>
+      AppliedTypeTree(cpy.Ident(op)(tpnme.THROWS), tpt :: excepts :: Nil)
+
   /** Translate tuple expressions of arity <= 22
    *
    *     ()             ==>   ()

compiler/src/dotty/tools/dotc/core/StdNames.scala

@@ -305,6 +305,7 @@ object StdNames {
     val SPECIALIZED_INSTANCE: N     = "specInstance$"
     val THIS: N                     = "_$this"
     val TRAIT_CONSTRUCTOR: N        = "$init$"
+    val THROWS: N                   = "$throws"
     val U2EVT: N                    = "u2evt$"
     val ALLARGS: N                  = "$allArgs"
 
@@ -600,6 +601,7 @@ object StdNames {
     val this_ : N               = "this"
     val thisPrefix : N          = "thisPrefix"
     val throw_ : N              = "throw"
+    val throws: N               = "throws"
     val toArray: N              = "toArray"
     val toList: N               = "toList"
     val toObjectArray : N       = "toObjectArray"

compiler/src/dotty/tools/dotc/typer/Typer.scala

@@ -2600,7 +2600,10 @@ class Typer extends Namer
     val untpd.InfixOp(l, op, r) = tree
     val result =
       if (ctx.mode.is(Mode.Type))
-        typedAppliedTypeTree(cpy.AppliedTypeTree(tree)(op, l :: r :: Nil))
+        typedAppliedTypeTree(
+          if op.name == tpnme.throws && Feature.enabled(Feature.saferExceptions)
+          then desugar.throws(l, op, r)
+          else cpy.AppliedTypeTree(tree)(op, l :: r :: Nil))
       else if (ctx.mode.is(Mode.Pattern))
         typedUnApply(cpy.Apply(tree)(op, l :: r :: Nil), pt)
       else {

docs/docs/reference/experimental/canthrow.md

@@ -47,9 +47,9 @@ However, a programming language is not a framework; it has to cater also for tho
 Why does `map` work so poorly with Java's checked exception model? It's because
 `map`'s signature limits function arguments to not throw checked exceptions. We could try to come up with a more polymorphic formulation of `map`. For instance, it could look like this:
 ```scala
-  def map[B, E](f: A => B canThrow E): List[B] canThrow E
+  def map[B, E](f: A => B throws E): List[B] throws E
 ```
-This assumes a type `A canThrow E` to indicate computations of type `A` that can throw an exception of type `E`. But in practice the overhead of the additional type parameters makes this approach unappealing as well. Note in particular that we'd have to parameterize _every method_ that takes a function argument that way, so the added overhead of declaring all these exception types looks just like a sort of ceremony we would like to avoid.
+This assumes a type `A throws E` to indicate computations of type `A` that can throw an exception of type `E`. But in practice the overhead of the additional type parameters makes this approach unappealing as well. Note in particular that we'd have to parameterize _every method_ that takes a function argument that way, so the added overhead of declaring all these exception types looks just like a sort of ceremony we would like to avoid.
 
 But there is a way to avoid the ceremony. Instead of concentrating on possible _effects_ such as "this code might throw an exception", concentrate on _capabilities_ such as "this code needs the capability to throw an exception". From a standpoint of expressiveness this is quite similar. But capabilities can be expressed as parameters whereas traditionally effects are expressed as some addition to result values. It turns out that this can make a big difference!
 
@@ -71,19 +71,32 @@ How can the ability be produced? There are several possibilities:
 Most often, the ability is produced by having a using clause `(using CanThrow[Exc])` in some enclosing scope. This roughly corresponds to a `throws` clause
 in Java. The analogy is even stronger since alongside `CanThrow` there is also the following type alias defined in the `scala` package:
 ```scala
-infix type canThrow[R, +E <: Exception] = CanThrow[E] ?=> R
+infix type $throws[R, +E <: Exception] = CanThrow[E] ?=> R
 ```
-That is, `R canThrow E` is a context function type that takes an implicit `CanThrow[E]` parameter and that returns a value of type `R`. Therefore, a method written like this:
+That is, `R $throws E` is a context function type that takes an implicit `CanThrow[E]` parameter and that returns a value of type `R`. What's more, the compiler
+will translate an infix types with `throws` as the operator to `$throws` applications
+according to the rules
+```
+                A throws E  -->  A $throws E
+    A throws E₁ | ... | Eᵢ  -->  A $throws E₁ ... $throws Eᵢ
+```
+Therefore, a method written like this:
 ```scala
 def m(x: T)(using CanThrow[E]): U
 ```
 can alternatively be expressed like this:
 ```scala
-def m(x: T): U canThrow E
+def m(x: T): U throws E
 ```
-_Aside_: If we rename `canThrow` to `throws` we would have a perfect analogy with Java but unfortunately `throws` is already taken in Scala 2.13.
-
-The `CanThrow`/`canThrow` combo essentially propagates the `CanThrow` requirement outwards. But where are these abilities created in the first place? That's in the `try` expression. Given a `try` like this:
+Multiple `CanThrow` capabilities can be combined in a single throws clause. For instance, the method
+```scala
+def m2(x: T)(using CanThrow[E1], CanThrow[E2]): U
+```
+can alternatively be expressed like this:
+```scala
+def m(x: T): U throws E1 | E2
+```
+The `CanThrow`/`throws` combo essentially propagates the `CanThrow` requirement outwards. But where are these abilities created in the first place? That's in the `try` expression. Given a `try` like this:
 
 ```scala
 try
@@ -126,16 +139,16 @@ You'll get this error message:
   |The ability to throw exception LimitExceeded is missing.
   |The ability can be provided by one of the following:
   | - A using clause `(using CanThrow[LimitExceeded])`
-  | - A `canThrow` clause in a result type such as `X canThrow LimitExceeded`
+  | - A `throws` clause in a result type such as `X throws LimitExceeded`
   | - an enclosing `try` that catches LimitExceeded
   |
   |The following import might fix the problem:
   |
   |  import unsafeExceptions.canThrowAny
 ```
-As the error message implies, you have to declare that `f` needs the ability to throw a `LimitExceeded` exception. The most concise way to do so is to add a `canThrow` clause:
+As the error message implies, you have to declare that `f` needs the ability to throw a `LimitExceeded` exception. The most concise way to do so is to add a `throws` clause:
 ```scala
-def f(x: Double): Double canThrow LimitExceeded =
+def f(x: Double): Double throws LimitExceeded =
   if x < limit then x * x else throw LimitExceeded()
 ```
 Now put a call to `f` in a `try` that catches `LimitExceeded`:
@@ -169,12 +182,12 @@ So the takeaway is that the effects as abilities model naturally provides for ef
 
 ## Gradual Typing Via Imports
 
-Another advantage is that the model allows a gradual migration from current unchecked exceptions to safer exceptions. Imagine for a moment that `experimental.saferExceptions` is turned on everywhere. There would be lots of code that breaks since functions have not yet been properly annotated with `canThrow`. But it's easy to create an escape hatch that lets us ignore the breakages for a while: simply add the import
+Another advantage is that the model allows a gradual migration from current unchecked exceptions to safer exceptions. Imagine for a moment that `experimental.saferExceptions` is turned on everywhere. There would be lots of code that breaks since functions have not yet been properly annotated with `throws`. But it's easy to create an escape hatch that lets us ignore the breakages for a while: simply add the import
 ```scala
 import scala.unsafeExceptions.canThrowAny
 ```
 This will provide the `CanThrow` ability for any exception, and thereby allow
-all throws and all other calls, no matter what the current state of `canThrow` declarations is. Here's the
+all throws and all other calls, no matter what the current state of `throws` declarations is. Here's the
 definition of `canThrowAny`:
 ```scala
 package scala
@@ -188,7 +201,8 @@ enable more fluid explorations of code without regard for complete exception saf
 
 To summarize, the extension for safer exception checking consists of the following elements:
 
- - It adds to the standard library the class `scala.CanThrow`, the type `scala.canThrow`, and the `scala.unsafeExceptions` object, as they were described above.
+ - It adds to the standard library the class `scala.CanThrow`, the type `scala.$throws`, and the `scala.unsafeExceptions` object, as they were described above.
+ - It adds some desugaring rules ro rewrite `throws` types to cascaded `$throws` types.
  - It augments the type checking of `throw` by _demanding_ a `CanThrow` ability or the thrown exception.
  - It augments the type checking of `try` by _providing_ `CanThrow` abilities for every caught exception.
 

docs/docs/reference/soft-modifier.md

@@ -5,7 +5,7 @@ title: Soft Keywords
 
 A soft modifier is one of the identifiers `opaque`, `inline`, `open`, `transparent`, and `infix`.
 
-A soft keyword is a soft modifier, or one of `derives`, `end`, `extension`, `using`, `|`, `+`, `-`, `*`
+A soft keyword is a soft modifier, or one of `derives`, `end`, `extension`, `throws`, `using`, `|`, `+`, `-`, `*`
 
 A soft modifier is treated as potential modifier of a definition if it is followed by a hard modifier or a keyword combination starting a definition (`def`, `val`, `var`, `type`, `given`, `class`, `trait`, `object`, `enum`, `case class`, `case object`). Between the two words there may be a sequence of newline tokens and soft modifiers.
 

library/src-bootstrapped/scala/CanThrow.scala

@@ -7,15 +7,17 @@ import annotation.{implicitNotFound, experimental}
  *  a given of class `CanThrow[Ex]` to be available.
  */
 @experimental
-@implicitNotFound("The ability to throw exception ${E} is missing.\nThe ability can be provided by one of the following:\n - A using clause `(using CanThrow[${E}])`\n - A `canThrow` clause in a result type such as `X canThrow ${E}`\n - an enclosing `try` that catches ${E}")
+@implicitNotFound("The ability to throw exception ${E} is missing.\nThe ability can be provided by one of the following:\n - A using clause `(using CanThrow[${E}])`\n - A `throws` clause in a result type such as `X throws ${E}`\n - an enclosing `try` that catches ${E}")
 erased class CanThrow[-E <: Exception]
 
 /** A helper type to allow syntax like
  *
- *    def f(): T canThrow Ex
+ *    def f(): T throws Ex1 | Ex2
+ *
+ *  Used in desugar.throws.
  */
 @experimental
-infix type canThrow[R, +E <: Exception] = CanThrow[E] ?=> R
+infix type $throws[R, +E <: Exception] = CanThrow[E] ?=> R
 
 @experimental
 object unsafeExceptions:

project/MiMaFilters.scala

@@ -8,10 +8,10 @@ object MiMaFilters {
     exclude[MissingClassProblem]("scala.annotation.internal.ProvisionalSuperClass"),
 
     // New APIs marked @experimental in 3.0.2
-    exclude[MissingClassProblem]("scala.Selectable$WithoutPreciseParameterTypes")
+    exclude[MissingClassProblem]("scala.Selectable$WithoutPreciseParameterTypes"),
 
     // Experimental API for saferExceptions
-    exclude[MissingClassProblem]("scala.CanThrow")
+    exclude[MissingClassProblem]("scala.CanThrow"),
     exclude[MissingClassProblem]("scala.CanThrow$package"),
     exclude[MissingClassProblem]("scala.CanThrow$package$"),
     exclude[MissingClassProblem]("scala.unsafeExceptions"),

tests/neg/safeThrowsStrawman.check

@@ -4,13 +4,13 @@
    |                                The capability to throw exception scalax.Fail is missing.
    |                                The capability can be provided by one of the following:
    |                                 - A using clause `(using CanThrow[scalax.Fail])`
-   |                                 - A throws clause in a result type such as `X throws scalax.Fail`
+   |                                 - A raises clause in a result type such as `X raises scalax.Fail`
    |                                 - an enclosing `try` that catches scalax.Fail
 -- Error: tests/neg/safeThrowsStrawman.scala:27:15 ---------------------------------------------------------------------
 27 |    println(bar)        // error
    |               ^
    |               The capability to throw exception Exception is missing.
    |               The capability can be provided by one of the following:
    |                - A using clause `(using CanThrow[Exception])`
-   |                - A throws clause in a result type such as `X throws Exception`
+   |                - A raises clause in a result type such as `X raises Exception`
    |                - an enclosing `try` that catches Exception

tests/neg/safeThrowsStrawman.scala

@@ -2,21 +2,21 @@ import language.experimental.erasedDefinitions
 import annotation.implicitNotFound
 
 object scalax:
-  @implicitNotFound("The capability to throw exception ${E} is missing.\nThe capability can be provided by one of the following:\n - A using clause `(using CanThrow[${E}])`\n - A throws clause in a result type such as `X throws ${E}`\n - an enclosing `try` that catches ${E}")
+  @implicitNotFound("The capability to throw exception ${E} is missing.\nThe capability can be provided by one of the following:\n - A using clause `(using CanThrow[${E}])`\n - A raises clause in a result type such as `X raises ${E}`\n - an enclosing `try` that catches ${E}")
   erased class CanThrow[-E <: Exception]
 
-  infix type throws[R, +E <: Exception] = CanThrow[E] ?=> R
+  infix type raises[R, +E <: Exception] = CanThrow[E] ?=> R
 
   class Fail extends Exception
 
-  def raise[E <: Exception](e: E): Nothing throws E = throw e
+  def raise[E <: Exception](e: E): Nothing raises E = throw e
 
 import scalax._
 
 def foo(x: Boolean): Int =
   if x then 1 else raise(Fail())  // error
 
-def bar: Int throws Exception =
+def bar: Int raises Exception =
   raise(Fail())
 
 @main def Test =

tests/neg/safeThrowsStrawman2.scala

@@ -4,15 +4,15 @@ object scalax:
   erased class CanThrow[E <: Exception]
   type CTF = CanThrow[Fail]
 
-  infix type throws[R, E <: Exception] = CanThrow[E] ?=> R
+  infix type raises[R, E <: Exception] = CanThrow[E] ?=> R
 
   class Fail extends Exception
 
-  def raise[E <: Exception](e: E): Nothing throws E = throw e
+  def raise[E <: Exception](e: E): Nothing raises E = throw e
 
 import scalax._
 
-def foo(x: Boolean, y: CanThrow[Fail]): Int throws Fail =
+def foo(x: Boolean, y: CanThrow[Fail]): Int raises Fail =
   if x then 1 else raise(Fail())
 
 def bar(x: Boolean)(using CanThrow[Fail]): Int =

tests/neg/saferExceptions.check

@@ -1,26 +1,26 @@
--- Error: tests/neg/saferExceptions.scala:14:16 ------------------------------------------------------------------------
-14 |      case 4 => throw Exception()             // error
+-- Error: tests/neg/saferExceptions.scala:12:16 ------------------------------------------------------------------------
+12 |      case 4 => throw Exception()             // error
    |                ^^^^^^^^^^^^^^^^^
    |                The ability to throw exception Exception is missing.
    |                The ability can be provided by one of the following:
    |                 - A using clause `(using CanThrow[Exception])`
-   |                 - A `canThrow` clause in a result type such as `X canThrow Exception`
+   |                 - A `throws` clause in a result type such as `X throws Exception`
    |                 - an enclosing `try` that catches Exception
    |
    |                The following import might fix the problem:
    |
    |                  import unsafeExceptions.canThrowAny
    |
--- Error: tests/neg/saferExceptions.scala:19:48 ------------------------------------------------------------------------
-19 |  def baz(x: Int): Int canThrow Failure = bar(x)  // error
-   |                                                ^
-   |                                The ability to throw exception java.io.IOException is missing.
-   |                                The ability can be provided by one of the following:
-   |                                 - A using clause `(using CanThrow[java.io.IOException])`
-   |                                 - A `canThrow` clause in a result type such as `X canThrow java.io.IOException`
-   |                                 - an enclosing `try` that catches java.io.IOException
+-- Error: tests/neg/saferExceptions.scala:17:46 ------------------------------------------------------------------------
+17 |  def baz(x: Int): Int throws Failure = bar(x)  // error
+   |                                              ^
+   |                                    The ability to throw exception java.io.IOException is missing.
+   |                                    The ability can be provided by one of the following:
+   |                                     - A using clause `(using CanThrow[java.io.IOException])`
+   |                                     - A `throws` clause in a result type such as `X throws java.io.IOException`
+   |                                     - an enclosing `try` that catches java.io.IOException
    |
-   |                                The following import might fix the problem:
+   |                                    The following import might fix the problem:
    |
-   |                                  import unsafeExceptions.canThrowAny
+   |                                      import unsafeExceptions.canThrowAny
    |

tests/neg/saferExceptions.scala

@@ -4,9 +4,7 @@ object test:
 
   class Failure extends Exception
 
-  def bar(x: Int): Int
-      `canThrow` Failure
-      `canThrow` IOException =
+  def bar(x: Int): Int throws Failure | IOException =
     x match
       case 1 => throw AssertionError()
       case 2 => throw Failure()               // ok
@@ -15,5 +13,5 @@ object test:
       case 5 => throw Throwable()             // ok: Throwable is treated as unchecked
       case _ => 0
 
-  def foo(x: Int): Int canThrow Exception = bar(x)
-  def baz(x: Int): Int canThrow Failure = bar(x)  // error
+  def foo(x: Int): Int throws Exception = bar(x)
+  def baz(x: Int): Int throws Failure = bar(x)  // error

tests/pos/reference/saferExceptions.scala

@@ -5,7 +5,7 @@ class LimitExceeded extends Exception
 
 val limit = 10e9
 
-def f(x: Double): Double canThrow LimitExceeded =
+def f(x: Double): Double throws LimitExceeded =
   if x < limit then x * x else throw LimitExceeded()
 
 @main def test(xs: Double*) =

tests/run/safeThrowsStrawman.scala

@@ -3,19 +3,19 @@ import language.experimental.erasedDefinitions
 object scalax:
   erased class CanThrow[-E <: Exception]
 
-  infix type throws[R, +E <: Exception] = CanThrow[E] ?=> R
+  infix type raises[R, +E <: Exception] = CanThrow[E] ?=> R
 
   class Fail extends Exception
 
-  def raise[E <: Exception](e: E): Nothing throws E = throw e
+  def raise[E <: Exception](e: E): Nothing raises E = throw e
 
 import scalax._
 
-def foo(x: Boolean): Int throws Fail =
+def foo(x: Boolean): Int raises Fail =
   if x then 1 else raise(Fail())
 
 def bar(x: Boolean)(using CanThrow[Fail]): Int = foo(x)
-def baz: Int throws Exception = foo(false)
+def baz: Int raises Exception = foo(false)
 
 @main def Test =
   try

tests/run/safeThrowsStrawman2.scala

@@ -3,19 +3,19 @@ import language.experimental.erasedDefinitions
 object scalax:
   erased class CanThrow[-E <: Exception]
 
-  infix type throws[R, +E <: Exception] = CanThrow[E] ?=> R
+  infix type raises[R, +E <: Exception] = CanThrow[E] ?=> R
 
   class Fail extends Exception
 
-  def raise[E <: Exception](e: E): Nothing throws E = throw e
+  def raise[E <: Exception](e: E): Nothing raises E = throw e
 
   private class Result[T]:
     var value: T = scala.compiletime.uninitialized
 
-  def try1[R, E <: Exception](body: => R throws E)(c: E => Unit): R =
+  def try1[R, E <: Exception](body: => R raises E)(c: E => Unit): R =
     try2(body)(c) {}
 
-  def try2[R, E <: Exception](body: => R throws E)(c: E => Unit)(f: => Unit): R =
+  def try2[R, E <: Exception](body: => R raises E)(c: E => Unit)(f: => Unit): R =
     val res = new Result[R]
     try
       given CanThrow[E] = ???
@@ -30,11 +30,11 @@ object scalax:
 
 import scalax._
 
-def foo(x: Boolean): Int throws Fail =
+def foo(x: Boolean): Int raises Fail =
   if x then 1 else raise(Fail())
 
 def bar(x: Boolean)(using CanThrow[Fail]): Int = foo(x)
-def baz: Int throws Exception = foo(false)
+def baz: Int raises Exception = foo(false)
 
 @main def Test =
   try1 {