nandi.uk
Fork of daniellemaywood.uk/gleam — Wasm codegen work
1<!--
2 SPDX-License-Identifier: Apache-2.0
3 SPDX-FileCopyrightText: 2024 The Gleam contributors
4-->
5
6# Runtime errors
7
8There are several runtime errors that Gleam code can throw. This documentation
9lists them and their runtime properties.
10
11On Erlang runtime errors are Erlang maps thrown with `erlang:error/1`, having at
12least these properties:
13
14| Key | Type | Value |
15| --- | ---- | ----- |
16| gleam_error | Atom | See individual errors |
17| message | String | See individual errors |
18| file | String | A path to the original source file location |
19| module | String | The module the error occurred in |
20| function | String | The function the error occurred in |
21| line | Int | The line number the error occurred on |
22
23On JavaScript runtime errors are instances of the JavaScript `Error` class,
24having at least these properties added to them:
25
26| Key | Type | Value |
27| --- | ---- | ----- |
28| gleam_error | String | See individual errors |
29| message | String | See individual errors |
30| module | String | The module the error occurred in |
31| function | String | The function the error occurred in |
32| line | Number | The line number the error occurred on |
33
34## Todo
35
36A panic that indicates that the code has not yet been completed, intended for
37use in development.
38
39```gleam
40todo
41todo as "some message"
42```
43| Key | Erlang Value | JavaScript Value |
44| --- | ------------ | ---------------- |
45| gleam_error | `todo` | `"todo"` |
46| message | The given message | The given message |
47
48## Panic
49
50An explicit panic to unconditionally error.
51
52```gleam
53panic
54panic as "some message"
55```
56| Key | Erlang Value | JavaScript Value |
57| --- | ------------ | ---------------- |
58| gleam_error | `panic` | `"panic"` |
59| message | The given message | The given message |
60
61## Let assert
62
63An inexhaustive pattern match, erroring if the pattern does not match.
64
65```gleam
66let assert Ok(x) = something()
67let assert Error(e) = something() as "This should fail"
68```
69| Key | Erlang Value | JavaScript Value |
70| --- | ------------ | ---------------- |
71| gleam_error | `let_assert` | `"let_assert"` |
72| message | The given message | The given message |
73| value | The unmatched value | The unmatched value |
74| start | The byte-index of the start of the `let assert` statement | The byte-index of the start of the `let assert` statement |
75| end | The byte-index of the end of the `let assert` statement | The byte-index of the end of the `let assert` statement |
76| pattern_start | The byte-index of the start of the asserted pattern | The byte-index of the start of the asserted pattern |
77| pattern_end | The byte-index of the end of the asserted pattern | The byte-index of the end of the asserted pattern |
78
79## Assert
80
81An assertion of a boolean value.
82
83The error format of `assert` differs based on the expression that is asserted.
84It always has these fields:
85
86| Key | Erlang Value | JavaScript Value |
87| --- | ------------ | ---------------- |
88| gleam_error | `assert` | `"assert"` |
89| message | The given message | The given message |
90| kind | The kind of asserted expression | The kind of asserted expression |
91| start | The byte-index of the start of the `assert` statement | The byte-index of the start of the `assert` statement |
92| end | The byte-index of the end of the `assert` expression | The byte-index of the end of the `assert` expression |
93| expression_start | The byte-index of the start of the asserted expression | The byte-index of the start of the asserted expression |
94
95But, depending on the expression that was asserted, it contains additional
96information which can be used to diagnose the error.
97
98### Binary operators
99
100```gleam
101assert level >= 30
102```
103
104| Key | Erlang Type | JavaScript Type | Value |
105| --- | ----------- | --------------- | ----- |
106| kind | Atom | String | `binary_operator` |
107| operator | Atom | String | The binary operator that was used |
108| left | Map | Object | The left hand side of the operator |
109| right | Map | Object | The left hand side of the operator |
110
111### Function calls
112
113```gleam
114assert check_some_property(a, b, c)
115```
116
117| Key | Erlang Type | JavaScript Type | Value |
118| --- | ----------- | --------------- | ----- |
119| kind | Atom | String | `function_call` |
120| arguments | List of map | Array of objects | The arguments of the asserted function |
121
122### Other expressions
123
124```gleam
125assert other_expression
126```
127
128| Key | Erlang Type | JavaScript Type | Value |
129| --- | ----------- | --------------- | ----- |
130| kind | Atom | String | `expression` |
131| expression | Map | Object | The value of the asserted expression |
132
133The expression maps have this structure:
134
135| Key | Erlang Type | JavaScript Type | Value |
136| --- | ----------- | --------------- | ----- |
137| value | any | any | the value the expression evaluated to at runtime |
138| kind | Atom | String | `literal` or `expression` or `unevaluated` |
139| start | Int | Number | The byte-index of the start of this expression in the source code |
140| end | Int | Number | The byte-index of the end of this expression in the source code |
141
142If the expression is a literal, such as `True` or `15`, it will have the `literal`
143kind. This signals that its value is not runtime dependent, and may not need to
144be printed.
145
146If the expression is on the right hand side of a short-circuiting operator, like
147`||` or `&&`, it might not be evaluated. If the operator short-circuits, the right
148hand side expression will have kind `unevaluated`.