Errors
Author: Daniel Diaz
Keywords: GNU Prolog, manual, Prolog, compiler, constraints, finite domains

### 6.3 Errors

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

#### 6.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 7.2.4) and to raise an error using throw/1 (section 7.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 8.22.3) and current_bip_name/2 (section 8.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).

#### 6.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 6.3.1).

#### 6.3.3 Uninstantiation error

An uninstantiation Error when an argument or one of its components is not a variable, and a variable or a component as variable is required. ErrorTerm has the following form: uninstantiation_error(Culprit) where Culprit is the argument or one of its components which caused the error.

The system predicate ’$pl_err_uninstantiation’(Culprit) raises this error in the current error context (section 6.3.1).

#### 6.3.4 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
- pair
- predicate_indicator

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

#### 6.3.5 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
- order
- 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 6.3.1).

#### 6.3.6 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 6.3.1).

#### 6.3.7 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 6.3.1).

#### 6.3.8 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
- integer_32bits
- 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 6.3.1).

#### 6.3.9 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 6.3.1).

#### 6.3.10 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

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

#### 6.3.11 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 6.3.1).

#### 6.3.12 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 6.3.1).

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