REBOL 3 Concepts: Errors: Generating Errors

Pending Revision

This document was written for R2 and has yet to be revised for R3.

User errors can be generated. The simplest way to generate an error is make it. Here is an example:

make error! "this is an error"
** User Error: this is an error.
** Where: make error! "this is an error"

Any of the existing errors can be generated by making the error with a block argument. This block contains the error category name and the error message id name. If the error requires arguments, the arguments follow the message id name. The arguments are what define the arg1, arg2 and arg3 values in the error object. Here is an example:

make error! [script expect-set series! number!]
** Script Error: Expected one of: series! - not: number!.
** Where: make error! [script expect-set series! number!]

Custom errors can be entered into the system/error object's user category. This is done by making a new user category with new entries. These entries are used when generating errors. For instance, the following example enters an error into the user category:

system/error/user: make system/error/user [
    my-error: "a simple error"
]

Now an error can be generated using the my-error message id:

if error? err: try [
    make error! [user my-error]
] [probe disarm err]
make object! [
    code: 803
    type: 'user
    id: 'my-error
    arg1: none
    arg2: none
    arg3: none
    near: [make error! [user my-error]]
    where: none
]

To create more informative errors, define an error that uses data available when it is generated. This data is included in the disarmed error object and printed as part of the error message. For instance, to use all three argument spaces in an error object:

system/error/user: make system/error/user [
    my-error: [:arg1 "doesn't go into" :arg2 "using" :arg3]
]

if error? err: try [
    make error! [user my-error [this] "that" my-function]
] [probe disarm err]
make object! [
    code: 803
    type: 'user
    id: 'my-error
    arg1: [this]
    arg2: "that"
    arg3: 'my-function
    near: [make error! [user my-error [this] "that" my-function]]
    where: none
]

The error message generated for my-error can be printed without stopping the script:

disarmed: disarm err
print bind (get disarmed/id) (in disarmed 'id)
this doesn't go into that using my-function

A new library category may be created if there is a need to group a series of errors together by making a new category in system/error:

system/error: make system/error [
    my-errors: make object! [
        code: 1000
        type: "My Error Category"
        error1: "a simple error"
        error2: [:arg1 "doesn't go into" :arg2 "using" :arg3]
    ]
]

The type defined in the error object will be the error type printed when the error is generated. The following example illustrates generating an error from both error1 and error2 in the my-error category.

Generating an error from error1. This error requires no arguments:

disarmed: disarm try [make error! [my-errors error1]]
print get disarmed/id
a simple error

Generating an error from error2 requires three arguments:

disarmed: disarm try [
make error! [my-errors error2 [this] "that" my-function]]
print bind (get disarmed/id) (in disarmed 'id)
this doesn't go into that using my-function

Finally, the description that returns the errors defined in my-errors may be obtained with:

probe get in get disarmed/type 'type
My Error Category