[ ECLiPSe Event built-in.|Group Index| Full Index]

error(+Number, ?Culprit, +Module)

An error Number is raised with Culprit (in module Module) the culprit, and the corresponding error handler is executed.

+Number
Integer or structure with functor default/1.
?Culprit
Prolog term.
+Module
Atom.

Description

The error with number Number and Culprit as its culprit is issued. Module is the module from where the goal Culprit was called. The appropriate error handler (belonging to the error with number Number) is invoked. This simulates an occurence of the error Number inside a call to Culprit. The valid error numbers are those returned by current_error/1.

If Number is not an integer but a structure with functor default/1, the structure argument is taken as the error number and the default handler is executed, even if the error handler has been redefined using set_error_handler/2. This is useful for writing user error handlers.

If the error handler fails or calls exit_block/1, the execution continues in the appropriate way. If the error handler succeeds, possibly binding some variables, error/3 succeeds.

Not that when the error handler ignores the module (ie. has arity less than three), then calls to error/2 and error/3 are equal.

Fail Conditions

Fails if the handler fails.

Resatisfiable

No.

Exceptions

(4) Instantiation fault
Number is not instantiated.
(5) Type error
Number is not an error specification.
(6) Range error
Number is not a valid error number.

Examples


Success:

    [eclipse]: error(68, length(X, Y), somewhere).
    calling an undefined procedure length(_g56, _g58)
                                      in module somewhere

   % writing an alternative error handler for undefined predicates:
    [eclipse]: arg(1,2).           % we want to change this
    calling an undefined procedure arg(1, 2) in module eclipse

    [eclipse]: [user].             % compile the new handler
     :- import current_predicate_body/2 from sepia_kernel.
     :- import current_built_in_body/2 from sepia_kernel.

     undef_handler(_, Goal, Module) :-
            functor(Goal, Name, BadArity),
            (
                current_predicate_body(Name/Arity, Module)
            ;
                current_built_in_body(Name/Arity, Module)
            ),
            !,
            printf("%w does not exist, but there is %w\n",
                               [Name/BadArity, Name/Arity]),
            fail.
     undef_handler(Err, Goal, Module) :-
            error(default(Err), Goal, Module).
     user compiled 764 bytes in 0.02 seconds

    yes.
    [eclipse]: set_error_handler(68, undef_handler/3).

    yes.
    [eclipse]: arg(1,2).            % check if it works
    arg / 2 does not exist, but there is arg / 3

    no.

Error:
      error(N,dummy(1),eclipse).    (Error 4).
      error(5.0,dummy(1),eclipse).  (Error 5).
      error(-2,dummy(1),eclipse).   (Error 6).
      error(95,dummy(1),eclipse).   (Error 6).


See Also

error / 2, current_error / 1, define_error / 2, error_id / 2, get_error_handler / 3, reset_error_handler / 1, reset_error_handlers / 0, set_error_handler / 2