10.1 Errors
function | ||||||||||||
|
If who is not #false, it is added to the beginning of the message, and a : separator is added in between.
The msg part of the error message is meant to fit on a single line. If details is non-empty, then ; is added to the end of msg, and each element of details is written on its own line with a 1-space prefix.
The clauses are added to the end of the error message. Construct a clause with functions like error.val, error.vals, error.annot, or error.text. Each clause will start on its own line with a 2-space prefix.
When exn is called by error, the first argument is a string message, and the second argument is Continuation.Marks.current(). If exn accepts at least three arguments, then PairList[srcloc] is provided as the third argument if srcloc is a Srcloc or PairList[] otherwise. If exn accepts four arguments, then the list of clauses is provided as the fourth argument.
Conventions for using error:
Start msg in lowercase, and keep it short. Use details to elaborate on the initial message, but report any values or other specifics in clauses. When details has multiple sentences, separate then with ; and stay in lowercase mode.
Normally, Exn.Fail.Annot should be used for exn (in place of Exn.Fail) if the exception represents an error that could have been prevented (without a race condition) by a preceding check.
To throw an error that complains about a single argument–annotation mismatch (in the same way as ::), use ~exn: Exn.Fail.Annot, use error.annot_msg to construct message, and use error.annot to and error.val to constructs clauses. Provide the same label string to error.annot_msg and error.val if it is useful to be more specific than "value".
> error("oops")
oops
me: oops
"oops",
~details: ["something has gone wrong;",
"see the manual for more information"])
me: oops;
something has gone wrong;
see the manual for more information
~exn: Exn.Fail.Annot,
error.annot_msg("fruit"),
error.annot("Tropical"),
me: fruit does not satisfy annotation
annotation: Tropical
fruit: #’Apple
"mismatch between fruit and vegetable",
me: mismatch between fruit and vegetable
fruit: [#’Apple, 0]
vegetable: [#’Lettuce, -1]
function | ||||||||
|
> error.message(~who: #'me, "oops")
"me: oops"
annotation | |
class | |||
| |||
function | |||
| |||
| |||
function | |||
| |||
function | |||
| |||
| |||
function | |||
|
The error.val and error.vals function convert each v to a string using repr.
Use error.annot to report an annotation in an error message, where Syntax.to_source_string may be useful (especially in in a macro’s implementation) to construct a suitable string form of an annotation.
The msg field of a error.Clause omits a 2-space prefix that will be added to the clause by error or error.message, but if it spans multiple lines, then msg will include a 3-space prefix on each line after the first one.
> error.text(~label: "name", "Alice")
Clause("name: Alice")
> error.val([1, 2, 3])
Clause("value: [1, 2, 3]")
> error.val(~label: "list", [1, 2, 3])
Clause("list: [1, 2, 3]")
> error.vals(1, 2, 3)
Clause("values:\n 1\n 2\n 3")
> error.annot("List.of(Int)")
Clause("annotation: List.of(Int)")
function | |
|
function | ||||||||
The label argument is used only to determine the default value of max_len.