% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(error): Error generating support}

\label{sec:error}

\begin{tags}
\mtag{author}- Jan Wielemaker \\- Richard O'Keefe \\- Ulrich Neumerkel\mtag{See also}- \verb$library(debug)$ and \verb$library(prolog_stack)$. \\- \predref{print_message}{2} is used to print (uncaught) error terms.
\end{tags}

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
\predref{must_be}{2} provides simple run-time type validation. The *_error
predicates are simple wrappers around \predref{throw}{1} to simplify throwing the
most common ISO error terms.\vspace{0.7cm}

\begin{description}
    \predicate{type_error}{2}{+Type, +Term}
Tell the user that \arg{Term} is not of the expected \arg{Type}. This error
is closely related to \predref{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 \textit{type_error}. If it
is a negative integer, it is a \textit{domain_error}.

Typical borderline cases are predicates accepting a compound
term, e.g., \verb$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 \verb$point(_,_)$ a \textit{type_error}.

    \predicate{domain_error}{2}{+Type, +Term}
The argument is of the proper type, but has a value that is
outside the supported values. See \predref{type_error}{2} for a more
elaborate discussion of the distinction between type- and
domain-errors.

    \predicate{existence_error}{2}{+Type, +Term}
\arg{Term} is of the correct type and correct domain, but there is no
existing (external) resource that is represented by it.

    \predicate{existence_error}{3}{+Type, +Term, +Set}
\arg{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.

\begin{tags}
    \tag{Compatibility}
This error is not in ISO.
\end{tags}

    \predicate{permission_error}{3}{+Action, +Type, +Term}
It is not allowed to perform \arg{Action} on the object \arg{Term} that is
of the given \arg{Type}.

    \predicate{instantiation_error}{1}{+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.

\begin{arguments}
\arg{Term} & is the term that needs (further) instantiation.
Unfortunately, the ISO error does not allow for passing
this term along with the error, but we pass it to this
predicate for documentation purposes and to allow for
future enhancement. \\
\end{arguments}

    \predicate{uninstantiation_error}{1}{+Term}
An argument is over-instantiated. This error is used for output
arguments whose value cannot be known upfront. For example, the
goal \verb$open(File, read, input)$ cannot succeed because the system
will allocate a new unique stream handle that will never unify
with \const{input}.

    \predicate{representation_error}{1}{+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.

    \predicate{syntax_error}{1}{+Culprit}
A text has invalid syntax. The error is described by \arg{Culprit}.

\begin{tags}
    \tag{To be done}
Deal with proper description of the location of the
error. For short texts, we allow for Type(Text), meaning
Text is not a valid Type. E.g. \verb$syntax_error(number('1a'))$
means that \verb$1a$ is not a valid number.
\end{tags}

    \predicate{resource_error}{1}{+Culprit}
A goal cannot be completed due to lack of resources.

    \predicate[det]{must_be}{2}{+Type, @Term}
True if \arg{Term} satisfies the type constraints for \arg{Type}. Defined
types are \const{atom}, \const{atomic}, \const{between}, \const{boolean}, \const{callable},
\const{chars}, \const{codes}, \const{text}, \const{compound}, \const{constant}, \const{float},
\const{integer}, \const{nonneg}, \verb$positive_integer$, \verb$negative_integer$,
\const{nonvar}, \const{number}, \const{oneof}, \const{list}, \verb$list_or_partial_list$,
\const{symbol}, \const{var}, \const{rational}, \const{encoding}, \const{dict} and \const{string}.

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.

\begin{quote}
\begin{tabular}{|l|l|}
\hline
acyclic & Acyclic term (tree); see \predref{acyclic_term}{1} \\
any &  \\
\verb$between(FloatL,FloatU)$ & Number [FloatL..FloatU] \\
\verb$between(IntL,IntU)$ & Integer [IntL..IntU] \\
boolean & One of \const{true} or \const{false} \\
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 \const{atomic} \\
cyclic & Cyclic term (rational tree); see \predref{cyclic_term}{1} \\
dict & A dictionary term; see \predref{is_dict}{1} \\
encoding & Valid name for a character encoding; see \predref{current_encoding}{1} \\
list & A (non-open) list; see \predref{is_list}{1} \\
negative_integer & Integer $<$ 0 \\
nonneg & Integer \Sge{} 0 \\
\verb$oneof(L)$ & Ground term that is member of L \\
positive_integer & Integer $>$ 0 \\
proper_list & Same as list \\
\verb$list(Type)$ & Proper list with elements of \arg{Type} \\
list_or_partial_list & A list or an open list (ending in a variable); see \predref{is_list_or_partial_list}{1} \\
stream & A stream name or valid stream handle; see \predref{is_stream}{1} \\
symbol & Same as \const{atom} \\
text & One of \const{atom}, \const{string}, \const{chars} or \const{codes} \\
type & \arg{Term} is a valid type specification \\
\hline
\end{tabular}
\end{quote}

Note: The Windows version can only represent Unicode code points
up to 2\Shat{}16-1. Higher values cause a representation error on most
text handling predicates.

\begin{tags}
    \tag{throws}
instantiation_error if \arg{Term} is insufficiently
instantiated and \verb$type_error(Type, Term)$ if \arg{Term} is not of \arg{Type}.
\end{tags}

    \predicate[semidet]{is_of_type}{2}{+Type, @Term}
True if \arg{Term} satisfies \arg{Type}.

    \predicate[semidet,multifile]{has_type}{2}{+Type, @Term}
True if \arg{Term} satisfies \arg{Type}.

    \predicate[nondet]{current_type}{3}{?Type, @Var, -Body}
True when \arg{Type} is a currently defined type and \arg{Var} satisfies \arg{Type} of
the body term \arg{Body} succeeds.
\end{description}

