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.
Error objects can be created with Error() and retrieved with Catch.
"ErrorObj" is used below as a placeholder for any Error object, as "Error" is the class itself.
In addition to the methods and properties inherited from Object, Error objects have the following predefined methods and properties.
Creates an Error object.
ErrorObj := Error(Message , What, Extra) ErrorObj := Error.Call(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 the Message, What, and Extra properties, 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:
NewError.What contains the name of the function.NewError.Line and NewError.File indicate the line which called the function.NewError.Stack contains a partial stack trace, with the indicated stack frame at the top.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)
}
Shows a standard script error dialog.
ErrorObj.Show(Mode)
Type: String
If omitted, it defaults to Return. Otherwise, specify one of the following words:
Return: Shows the leading text "Error:" and the Continue and Abort buttons.
Exit: Shows the leading text "Error:" and the Abort button.
ExitApp: Shows the leading text "Critical Error:" and the Abort button. The script exits when the dialog is closed.
Warn: Shows the leading text "Warning:" and the Continue button.
Type: Integer
If the Return mode is used, the return value is -1 if the dialog was closed by the Continue button. Otherwise, the return value is 1.
If present, the Message, Extra, File, Line, Hint and Stack properties are used to determine the content of the dialog. If blank, the corresponding element of the dialog is omitted. In particular, File can be removed to hide the "vicinity lines" normally shown in the dialog. If File does not correspond to the main script or an #include file, only the file name and line number are shown.
Message can contain multiple lines of text, in which case the first line is rendered with the title font and subsequent lines are rendered with the default font.
The Mode parameter and return value are compatible with OnError callbacks. For example:
#Requires AutoHotkey v2.1-alpha.10
; This is an anonymous function definition being passed to the OnError function.
; This syntax requires v2.1-alpha.3+, but Show requires v2.1-alpha.10+.
OnError (err, mode) {
err.File := unset
err.Line := unset
return err.Show(mode)
}
throw ValueError("This value is not 42", -1, 41)
Gets or sets a string relating to the error.
CurrentExtra := ErrorObj.Extra
ErrorObj.Extra := NewExtra
The standard error dialog displays a line with "Specifically:" followed by this string.
Gets or sets the full path of the script file containing the line at which the error occurred, or at which the Error object was constructed.
CurrentFile := ErrorObj.File
ErrorObj.File := NewFile
Gets or sets a string of text displayed near the bottom of the standard error dialog, above the stack trace link (if present).
CurrentHint := ErrorObj.Hint
ErrorObj.Hint := NewHint
This property is not defined by default in the standard Error classes. If left undefined, a default hint is used, usually indicating that the thread will exit. An empty string can be used to suppress the default hint.
Gets or sets the line number at which the error occurred, or at which the Error object was constructed.
CurrentLine := ErrorObj.Line
ErrorObj.Line := NewLine
Gets or sets the error message.
CurrentMessage := ErrorObj.Message
ErrorObj.Message := NewMessage
Returns a readable description of the error.
Text := ErrorObj.ToString()
The result is a multi-line report with one labelled line per property, in this order: the error's class name, Message, What, Extra, File, Line, then Stack on the lines that follow. Every line is present even when the property is empty. This is the format the error dialog displays, and it is what an Error yields where a string is expected.
Exception: ValueError Message: Invalid capability name: fly. What: RequestCapabilities Extra/Code: File: C:\Scripts\demo.ks Line: 12 Stack: ...
Gets or sets a string representing the call stack at the time the Error object was constructed.
CurrentStack := ErrorObj.Stack
ErrorObj.Stack := NewStack
Each line may be formatted as follows:
File (Line) : [What] SourceCode`r`n> What`r`n... N moreStack property cannot exceed 2047 characters.Gets or sets the source that threw the exception.
CurrentWhat := ErrorObj.What
ErrorObj.What := NewWhat
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).
The following subclasses of Error are predefined:
Note: Calling OSError(Code) is intended to initialize Number and Message from the supplied numeric code, but Code is currently ignored. On Windows, Number and Message are initialized from the last P/Invoke error. On Linux and macOS, Number is initialized from A_LastError and no operating-system message is generated.
Errors are also thrown using the base Error class.
The standard error dialog requires the Message, Extra, File, Line and Hint properties to be own value properties.
An error's stack trace begins at the point where the error is thrown, rather than the point where its Error object was constructed. Constructing an Error and throwing it later therefore reports the later throw site.