Module lace.error
Error routines for Lace ruleset compilers and runtime engines.
Errors are a critical part of anything user-facing. Lace works very hard to ensure that it can report errors effectively so that the author of the ruleset (the user of the application which is using Lace) can work out what went wrong and how to fix it.
Functions
| error (str, words, rnil) | Report an error. |
| offset (err, offs) | Offset an error's recorded wordset. |
| augment (err, source, number) | Augment an error with source information
In order for errors to be useful they need to be augmented with the source document in which they occurred and the line number on which they occurred. |
| render (err) | Render an error down to a string. |
Functions
- error (str, words, rnil)
-
Report an error.
Report an error, including indicating which words caused the problem. The words are 1-indexed from the start of whatever routine is trying to consume words.
Parameters:
- str string The error message.
- words {number,...} or nil A list of the words causing this error.
- rnil boolean Whether to return nil (indicating a programming error).
Returns:
-
boolean or nil,table
The compilation result (false or nil) and a
compilation error table
- offset (err, offs)
-
Offset an error's recorded wordset.
Since errors carry word indices, if the layers of the compiler or runtime alter the offsets, this routine can be used to offset the word indices in an error message.
Parameters:
- err table The error table
- offs number The offset by which to adjust the error words.
Returns:
-
table
The error table (mutated by the offset).
- augment (err, source, number)
-
Augment an error with source information
In order for errors to be useful they need to be augmented with the source document in which they occurred and the line number on which they occurred. This function allows the compiler (or runtime) to do just that.
Parameters:
- err table The error table to augment
- source table The lexically analysed source document.
- number linenr The line number on which the error occurred.
Returns:
-
table
The error table (mutated with the source information).
- render (err)
-
Render an error down to a string.
Error tables carry a message, an optional set of words which caused the error (if known) and a lexically analysed source and line number.
This function renders that information down to a multiline string which can usefully be presented to the user of an application using Lace for access control.
Parameters:
- err table The error table.
Returns:
-
string
A multiline string rendering of the error.