
error.pl -- Error generating support
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 notpoint(_,_)
a type_error. 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.
instantiation_error(+Term)
- 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.
uninstantiation_error(+Term)
- An argument is over-instantiated. This error is used for output
arguments whose value cannot be known upfront. For example, the
goal
open(File, read, input)
cannot succeed because the system will allocate a new unique stream handle that will never unify withinput
. representation_error(+Reason)
- 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.
syntax_error(+Culprit)
- A text has invalid syntax. The error is described by Culprit.
resource_error(+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
types are
atom
,atomic
,between
,boolean
,callable
,chars
,codes
,text
,compound
,constant
,float
,integer
,nonneg
,positive_integer
,negative_integer
,nonvar
,number
,oneof
,list
,list_or_partial_list
,symbol
,var
,rational
,encoding
,dict
andstring
.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 between(FloatL,FloatU)
Number [FloatL..FloatU] between(IntL,IntU)
Integer [IntL..IntU] boolean One of true
orfalse
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 atomic
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 oneof(L)
Ground term that is member of L positive_integer Integer > 0 proper_list Same as list list(Type)
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 atom
text One of atom
,string
,chars
orcodes
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.