From 4c7165be86e32cce4ca7eca59bd0ec2130bbb360 Mon Sep 17 00:00:00 2001
From: Qyriad <qyriad@qyriad.me>
Date: Mon, 24 Jun 2024 17:26:21 -0600
Subject: distinguish between throws & errors during throw
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Turns errors like this:

let
  throwMsg = a: throw (a + " invalid bar");
in throwMsg "bullshit"

error:
       … from call site
         at «string»:3:4:
            2|   throwMsg = a: throw (a + " invalid bar");
            3| in throwMsg "bullshit"
             |    ^

       … while calling 'throwMsg'
         at «string»:2:14:
            1| let
            2|   throwMsg = a: throw (a + " invalid bar");
             |              ^
            3| in throwMsg "bullshit"

       … while calling the 'throw' builtin
         at «string»:2:17:
            1| let
            2|   throwMsg = a: throw (a + " invalid bar");
             |                 ^
            3| in throwMsg "bullshit"

       error: bullshit invalid bar

into errors like this:

let
  throwMsg = a: throw (a + " invalid bar");
in throwMsg "bullshit"

error:
       … from call site
         at «string»:3:4:
            2|   throwMsg = a: throw (a + " invalid bar");
            3| in throwMsg "bullshit"
             |    ^

       … while calling 'throwMsg'
         at «string»:2:14:
            1| let
            2|   throwMsg = a: throw (a + " invalid bar");
             |              ^
            3| in throwMsg "bullshit"

       … caused by explicit throw
         at «string»:2:17:
            1| let
            2|   throwMsg = a: throw (a + " invalid bar");
             |                 ^
            3| in throwMsg "bullshit"

       error: bullshit invalid bar

Change-Id: I593688928ece20f97999d1bf03b2b46d9ac338cb
---
 doc/manual/rl-next/distinguish-throw-errors.md | 70 ++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 doc/manual/rl-next/distinguish-throw-errors.md

(limited to 'doc/manual/rl-next')

diff --git a/doc/manual/rl-next/distinguish-throw-errors.md b/doc/manual/rl-next/distinguish-throw-errors.md
new file mode 100644
index 000000000..243e33d61
--- /dev/null
+++ b/doc/manual/rl-next/distinguish-throw-errors.md
@@ -0,0 +1,70 @@
+---
+synopsis: "Distinguish between explicit throws and errors that happened while evaluating a throw"
+cls: 1511
+credits: Qyriad
+category: Improvements
+---
+
+Previously, errors caused by an expression like `throw "invalid argument"` were treated like an error that happened simply while some builtin function was being called:
+
+```
+let
+  throwMsg = p: throw "${p} isn't the right package";
+in throwMsg "linuz"
+
+error:
+       … while calling the 'throw' builtin
+         at «string»:2:17:
+            1| let
+            2|   throwMsg = p: throw "${p} isn't the right package";
+             |                 ^
+            3| in throwMsg "linuz"
+
+       error: linuz isn't the right package
+```
+
+But the error didn't just happen "while" calling the `throw` builtin — it's a throw error!
+Now it looks like this:
+
+```
+let
+  throwMsg = p: throw "${p} isn't the right package";
+in throwMsg "linuz"
+
+error:
+       … caused by explicit throw
+         at «string»:2:17:
+            1| let
+            2|   throwMsg = p: throw "${p} isn't the right package";
+             |                 ^
+            3| in throwMsg "linuz"
+
+       error: linuz isn't the right package
+```
+
+This also means that incorrect usage of `throw` or errors evaluating its arguments are easily distinguishable from explicit throws:
+
+```
+let
+  throwMsg = p: throw "${p} isn't the right package";
+in throwMsg { attrs = "error when coerced in string interpolation"; }
+
+error:
+       … while calling the 'throw' builtin
+         at «string»:2:17:
+            1| let
+            2|   throwMsg = p: throw "${p} isn't the right package";
+             |                 ^
+            3| in throwMsg { attrs = "error when coerced in string interpolation"; }
+
+       … while evaluating a path segment
+         at «string»:2:24:
+            1| let
+            2|   throwMsg = p: throw "${p} isn't the right package";
+             |                        ^
+            3| in throwMsg { attrs = "error when coerced in string interpolation"; }
+
+       error: cannot coerce a set to a string: { attrs = "error when coerced in string interpolation"; }
+```
+
+Here, instead of an actual thrown error, a type error happens first (trying to coerce an attribute set to a string), but that type error happened *while* calling `throw`.
-- 
cgit v1.2.3