This module provides predicates to simplify error generation and checking. It's implementation is based on a discussion on the SWI-Prolog mailinglist on best practices in error handling. The utility predicate must_be/2 provides simple run-time type validation. The *_error predicates are simple wrappers around throw/1 to simplify throwing the most common ISO error terms.
- type_error(+Type, +Term)
- Tell the user that Term is not of the expected Type. This error
is closely related to domain_error/2 because the notion of types
is not really set in stone in Prolog. We introduce the
difference using a simple example.
Suppose an argument must be a non-negative integer. If the actual argument is not an integer, this is a type_error. If it is a negative integer, it is a domain_error.
Typical borderline cases are predicates accepting a compound term, e.g.,
point(X,Y). One could argue that the basic type is a compound-term and any other compound term is a domain error. Most Prolog programmers consider each compound as a type and would consider a compound that is not
- domain_error(+Type, +Term)
- The argument is of the proper type, but has a value that is outside the supported values. See type_error/2 for a more elaborate discussion of the distinction between type- and domain-errors.
- existence_error(+Type, +Term)
- Term is of the correct type and correct domain, but there is no existing (external) resource that is represented by it.
- existence_error(+Type, +Term, +Set)
- Term is of the correct type and correct domain, but there is no existing (external) resource that is represented by it in the provided set.
- permission_error(+Action, +Type, +Term)
- It is not allowed to perform Action on the object Term that is of the given Type.
- An argument is under-instantiated. I.e. it is not acceptable as it is, but if some variables are bound to appropriate values it would be acceptable.
- An argument is over-instantiated. This error is used for output
arguments whose value cannot be known upfront. For example, the
open(File, read, input)cannot succeed because the system will allocate a new unique stream handle that will never unify with
- A representation error indicates a limitation of the implementation. SWI-Prolog has no such limits that are not covered by other errors, but an example of a representation error in another Prolog implementation could be an attempt to create a term with an arity higher than supported by the system.
- A text has invalid syntax. The error is described by Culprit.
- A goal cannot be completed due to lack of resources.
- must_be(+Type, @Term) is det
- True if Term satisfies the type constraints for Type. Defined
Most of these types are defined by an arity-1 built-in predicate of the same name. Below is a brief definition of the other types.
acyclic Acyclic term (tree); see acyclic_term/1 any any term
Integer [IntL..IntU] boolean One of
char Atom of length 1 chars Proper list of 1-character atoms code Representation Unicode code point codes Proper list of Unicode character codes constant Same as
cyclic Cyclic term (rational tree); see cyclic_term/1 dict A dictionary term; see is_dict/1 encoding Valid name for a character encoding; see current_encoding/1 list A (non-open) list; see is_list/1 negative_integer Integer < 0 nonneg Integer >= 0
Ground term that is member of L positive_integer Integer > 0 proper_list Same as list
Proper list with elements of Type list_or_partial_list A list or an open list (ending in a variable); see is_list_or_partial_list/1 stream A stream name or valid stream handle; see is_stream/1 symbol Same as
text One of
type Term is a valid type specification
Note: The Windows version can only represent Unicode code points up to 2^16-1. Higher values cause a representation error on most text handling predicates.
- is_of_type(+Type, @Term) is semidet
- True if Term satisfies Type.
- has_type(+Type, @Term) is semidet[multifile]
- True if Term satisfies Type.
- current_type(?Type, @Var, -Body) is nondet
- True when Type is a currently defined type and Var satisfies Type of the body term Body succeeds.