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