Throw [v1.1.04+]

Signals the occurrence of an error. This signal can be caught by a try-catch statement.

Throw , Expression

Parameters

Expression

A value to store in catch's OutputVar.

Since this parameter is an expression, all of the following are valid examples:

throw 3
throw "literal string"
throw MyVar
throw i + 1
throw { what: "Custom error", file: A_LineFile, line: A_LineNumber } ; Throws an object

This parameter is always an expression, so variable references should not be enclosed in percent signs except to perform a double-deref.

[v1.1.05+]: If omitted, an exception object is thrown with a default message.

Exception()

Creates an object with properties, also common to exceptions created by runtime errors.

Exception(Message , What, Extra)

This object contains the following properties:

• Message: An error message or ErrorLevel value.
• What: The name of the command, function or label which was executing or about to execute when the error occurred.
• Extra: Additional information about the error, if available.
• File: Set automatically to the full path of the script file which contains the line at which the error occurred.
• Line: Set automatically to the line number at which the error occurred.

If What is omitted, it defaults to the name of the current function or subroutine. Otherwise it can be a string or a negative offset from the top of the call stack. For example, a value of -1 sets Exception.What to the current function or subroutine, and Exception.Line and Exception.File to the line and file which called it. However, if the script is compiled or the offset is invalid, What is simply converted to a string.

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

try
    SomeFunction()
catch e
    MsgBox % "Error in " e.What ", which was called at line " e.Line 

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

Related

Try, Catch, Finally, OnError()

Examples

See Try.