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 compoint 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.
- 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.
boolean one of
char Atom of length 1 code Representation Unicode code point chars Proper list of 1-character atoms codes Proper list of Unicode character codes text One of
Number [FloatL..FloatU] nonneg Integer >= 0 positive_integer Integer > 0 negative_integer Integer < 0
Ground term that is member of L encoding Valid name for a character encoding cyclic Cyclic term (rational tree) acyclic Acyclic term (tree)
Proper list with elements of Type list_or_partial_list A list or an open list (ending in a variable
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_not(+Type, @Term)[private]
- Throws appropriate error. It is known that Term is not of type Type.
- 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_encoding(?Name) is nondet[private]
- True if Name is the name of a supported encoding. See encoding option of e.g., open/4.
- 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.