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.
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
> What`r`n
... N more
Stack
property cannot exceed 2047 characters.Note: The standard error dialog requires Message, Extra, File and Line to be own value properties.
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:
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) }
The following subclasses of Error are predefined:
OSError(Code)
where Code is numeric sets Number and Message based on the given OS-defined error code. If Code is omitted, it defaults to A_LastError. For example, OSError(5).Message
returns "(5) Access is denied."Errors are also thrown using the base Error class.