Errors

5.3 | Errors

- General format and error context
- Instantiation error
- Type error
- Domain error
- Existence error
- Permission error
- Representation error
- Evaluation error
- Resource error
- Syntax error
- System error

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

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 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 5.3.1).

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