Errors

5.3 Errors

5.3.1 General format and error context

When an error occurs an exception of the form: error(ErrorTerm, Caller) is raised. ErrorTerm is a term specifying the error (detailed in next sections) and Caller is a term specifying the context of the error. The context is either the predicate indicator of the last invoked built-in predicate or an atom giving general context information.

Using exceptions allows the user both to recover an error using catch/3 (section 6.2.4) and to raise an error using throw/1 (section 6.2.4).

To illustrate how to write error cases, let us write a predicate my_pred(X) where X must be an integer:

my_pred(X) :-
        (   nonvar(X) ->
            true
        ;   throw(error(instantiation_error), my_pred/1)),
        ),
        (   integer(X) ->
            true
        ;   throw(error(type_error(integer, X), my_pred/1))
        ),
        ...

To help the user to write these error cases, a set of system predicates is provided to raise errors. These predicates are of the form '$pl_err_...' and they all refer to the implicit error context. The predicates set_bip_name/2 (section 7.22.3) and current_bip_name/2 (section 7.22.4) are provided to set and recover the name and the arity associated with this context (an arity < 0 means that only the atom corresponding to the functor is significant). Using these system predicates the user could define the above predicate as follow:

my_pred(X) :-
        set_bip_name(my_pred,1),
        (   nonvar(X) ->
            true
        ;   '$pl_err_instantiation'
        ),
        (   integer(X) ->
            true
        ;   '$pl_err_type'(integer, X)
        ),
        ...

The following sections detail each kind of errors (and associated system predicates).

5.3.2 Instantiation error

An instantiation error occurs when an argument or one of its components is variable while an instantiated argument was expected. ErrorTerm has the following form: instantiation_error.

The system predicate '$pl_err_instantiation' raises this error in the current error context (section 5.3.1).

5.3.3 Type error

A type error occurs when the type of an argument or one of its components is not the expected type (but not a variable). ErrorTerm has the following form: type_error(Type, Culprit) where Type is the expected type and Culprit the argument which caused the error. Type is one of:

atom
atomic
boolean
byte
callable
character
compound
evaluable
fd_bool_evaluable
fd_evaluable
fd_variable
float
in_byte
in_character
integer
list
number
predicate_indicator
variable

The system predicate '$pl_err_type'(Type, Culprit) raises this error in the current error context (section 5.3.1).

5.3.4 Domain error

A domain error occurs when the type of an argument is correct but its value is outside the expected domain. ErrorTerm has the following form: domain_error(Domain, Culprit) where Domain is the expected domain and Culprit the argument which caused the error. Domain is one of:

atom_property
buffering_mode
character_code_list
close_option
date_time
eof_action
fd_labeling_option
flag_value
format_control_sequence
g_array_index
io_mode
non_empty_list
not_less_than_zero
operator_priority
operator_specifier
os_file_permission
os_file_property
os_path
predicate_property
prolog_flag
read_option
selectable_item
socket_address
socket_domain
source_sink
statistics_key
statistics_value
stream
stream_option
stream_or_alias
stream_position
stream_property
stream_seek_method
stream_type
term_stream_or_alias
var_binding_option
write_option

The system predicate '$pl_err_domain'(Domain, Culprit) raises this error in the current error context (section 5.3.1).

5.3.5 Existence error

an existence error occurs when an object on which an operation is to be performed does not exist. ErrorTerm has the following form: existence_error(Object, Culprit) where Object is the type of the object and Culprit the argument which caused the error. Object is one of:

procedure
source_sink
stream

The system predicate '$pl_err_existence'(Object, Culprit) raises this error in the current error context (section 5.3.1).

5.3.6 Permission error

A permission error occurs when an attempt to perform a prohibited operation is made. ErrorTerm has the following form: permission_error(Operation, Permission, Culprit) where Operation is the operation which caused the error, Permission the type of the tried permission and Culprit the argument which caused the error. Operation is one of:

access
add_alias
close
create
input
modify
open
output
reposition

and Permission is one of:

binary_stream
flag
operator
past_end_of_stream
private_procedure
source_sink
static_procedure
stream
text_stream

The system predicate '$pl_err_permission'(Operation, Permission, Culprit) raises this error in the current error context (section 5.3.1).

5.3.7 Representation error

A representation error occurs when an implementation limit has been breached. ErrorTerm has the following form: representation_error(Limit) where Limit is the name of the reached limit. Limit is one of:

character
character_code
in_character_code
max_arity
max_integer
min_integer
too_many_variables

The errors max_integer and min_integer are not currently implemented.

The system predicate '$pl_err_representation'(Limit) raises this error in the current error context (section 5.3.1).

5.3.8 Evaluation error

An evaluation error occurs when an arithmetic expression gives rise to an exceptional value. ErrorTerm has the following form: evaluation_error(Error) where Error is the name of the error. Error is one of:

float_overflow
int_overflow
undefined
underflow
zero_divisor

The errors float_overflow, int_overflow, undefined and underflow are not currently implemented.

The system predicate '$pl_err_evaluation'(Error) raises this error in the current error context (section 5.3.1).

5.3.9 Resource error

A resource error occurs when GNU Prolog does not have enough resources. ErrorTerm has the following form: resource_error(Resource) where Resource is the name of the resource. Resource is one of:

print_object_not_linked
too_big_fd_constraint
too_many_open_streams

The system predicate '$pl_err_resource'(Resource) raises this error in the current error context (section 5.3.1).

5.3.10 Syntax error

A syntax error occurs when a sequence of character does not conform to the syntax of terms. ErrorTerm has the following form: syntax_error(Error) where Error is an atom explaining the error.

The system predicate '$pl_err_syntax'(Error) raises this error in the current error context (section 5.3.1).

5.3.11 System error

A system error can occur at any stage. A system error is generally associated with an external component (e.g. operating system). ErrorTerm has the following form: system_error(Error) where Error is an atom explaining the error. This is an extension to ISO which only defines system_error without arguments.

The system predicate '$pl_err_system'(Error) raises this error in the current error context (section 5.3.1).

Copyright (C) 1999-2007 Daniel Diaz

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

More about the copyright