Error Object

class Error extends Object

Error objects are thrown by built-in code when a runtime error occurs, and may also be thrown explicitly by the script.

Table of Contents

Standard Properties

Message: An error message.

What: What threw the exception. This is usually the name of a function, but is blank for exceptions thrown due to an error in an expression (such as using a math operator on a non-numeric value).

Extra: A string value relating to the error, if available. If this value can be converted to a non-empty string, the standard error dialog displays a line with "Specifically:" followed by this string.

File: The full path of the script file which contains the line at which the error occurred, or at which the Error object was constructed.

Line: The line number at which the error occurred, or at which the Error object was constructed.

Stack: A string representing the call stack at the time the Error object was constructed. Each line may be formatted as follows:

File (Line) : [What] SourceCode`r`n
Represents a call to the function What. File and Line indicate the current script line at this stack depth. SourceCode is an approximation of the source code at that line, as it would be shown in ListLines.
> What`r`n
Represents the launching of a thread, typically the direct cause of the function call above it.
... N more
Indicates that the stack trace was truncated, and there are N more stack entries not shown. Currently the Stack property cannot exceed 2047 characters.

Note: The standard error dialog requires Message, Extra, File and Line to be own value properties.

Error()

Creates an Error object.

NewError := Error(Message , What, Extra)

Error may be replaced with one of the subclasses listed under Error Types, although some subclasses may take different parameters.

The parameters directly correspond to properties described above, but may differ for Error subclasses which override the __New method.

Message and Extra are converted to strings. These are displayed by an error dialog if the exception is thrown and not caught.

What indicates the source of the error. It can be an arbitrary string, but should be a negative integer or the name of a running function. Specifying -1 indicates the current function, -2 indicates the function which called it, and so on. If the script is compiled or the value does not identify a valid stack frame, the value is merely converted to a string and assigned to NewError.What. Otherwise, the identified stack frame is used as follows to determine the other properties:

Use of the What parameter can allow a complex function to use helper functions to perform its work or parameter validation, while omitting those internal details from any reported error information. For example:

MyFunction(a, b) {
    CheckArg "a", a
    CheckArg "b", b
    ;...
    CheckArg(name, value) {
        if value < 0
            throw ValueError(name " is negative", "myfunction", value)
    }
}

try
    MyFunction(1, -1)  ; err.Line indicates this line.
catch ValueError as err
    MsgBox Format("{1}: {2}.`n`nFile:`t{3}`nLine:`t{4}`nWhat:`t{5}`nStack:`n{6}"
        , type(err), err.Message, err.File, err.Line, err.What, err.Stack)
try
    SomeFunction()
catch as e
    MsgBox(type(e) " in " e.What ", which was called at line " e.Line)

SomeFunction() {
    throw Error("Fail", -1)
}

Error Types

The following subclasses of Error are predefined:

Errors are also thrown using the base Error class.

Throw, Try, Catch, Finally, OnError