Errors

Throwing custom errors in BoxLang is a powerful feature that allows developers to handle exceptional situations in their code. By creating and throwing custom errors, developers can provide more specific and meaningful error information, which can be crucial for debugging and maintaining the application.

In BoxLang, you can throw a custom error using the bx:throw component or the throw function. Both allow you to specify the type of the error, a message describing the error, and additional custom information.

Here's an example of throwing a custom error with the bx:throw component:

<bx:throw type="MyCustomError" message="Something went wrong" detail="More details about the error">

And here's how you can do it with the throw function:

throw(type="MyCustomError", message="Something went wrong", detail="More details about the error");

The type attribute is used to categorize the error. This can be any string, but it's common to use a descriptive name that indicates the nature of the error. The message attribute is a brief description of the error, and the detail attribute can be used to provide more detailed information.

When you throw a custom error, it can be caught and handled using the bx:catch component or the catch block in a try/catch statement. The caught error object will contain the type, message, and detail that you specified when throwing the error, along with other information about the error.

Here's an example of catching a custom error with the bx:catch component:

<bx:try>
    <!--- Some code that might throw an error --->
    <bx:throw type="MyCustomError" message="Something went wrong" detail="More details about the error">
    <bx:output>
        <bx:catch type="MyCustomError">
            <!--- Handle the error --->
            Error: #bxCatch.message# (#bxCatch.detail#)</bx:output>
        </bx:catch>
    </bx:output>
</bx:try>

Note: Notice that the component <bx:try> uses the built in scope bxCatch whereas the script syntax below uses an argument name like other functions.

And here's how you can use this in script/classes with a try/catch statement:

try {
    // Some code that might throw an error
    throw(type="MyCustomError", message="Something went wrong", detail="More details about the error");
} catch (any e) {
    if (e.type == "MyCustomError") {
        // Handle the error
        writeOutput("Error: " & e.message & " (" & e.detail & ")");
    }
}

Throwing custom errors is particularly useful when you're writing a function or a component that can be used by other parts of your application or by other developers. By throwing a custom error when something goes wrong, you can communicate exactly what the problem is, making it easier for the calling code to handle the error appropriately.

In conclusion, throwing custom errors in BoxLang is a powerful technique for handling exceptional situations in your code. It allows you to provide specific, meaningful error information, which can be crucial for debugging and maintaining your application. Whether you're a beginner or an experienced BoxLang developer, understanding how to throw and catch custom errors is an important skill.