4.3 | Errors

4.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 5.2.4) and to raise an error using `throw/1` (section 5.2.4).
To illustrate how to write a 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 6.22.3) and `current_bip_name/2` (section 6.22.4) are provided to set and recover the name and the arity associated to 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).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.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 4.3.1).

4.3.11 | System error

A system error can occur at any stage. A system error is generally associated to 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 4.3.1).

Copyright (C) 1999,2000 Daniel Diaz
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
More about the copyright