The predicate throw/1
takes a single argument, the exception term, and the ISO
standard stipulates that the exception term be of the form
the‘formal' description of the error, as listed in chapter 7.12.2 pp. 62-63 ("Error classification") of the ISO standard. It indicates the error class and possibly relevant error context information. It may be a compound term of arity 1,2 or 3 - or simply an atom if there is no relevant error context information.
additional context information beyond the one in Formal. If may be unset, i.e. a fresh variable, or set to something that hopefully will help the programmer in debugging. The structure of Context is left unspecified by the ISO Standard, so SWI-Prolog creates it own convention (see below).
Thus, constructing an error term and throwing it might take this form (although you would not use the illustrative explicit naming given here; instead composing the exception term directly in a one-liner):
Exception = error(Formal, Context), Context = ... some local convention ..., Formal = type_error(ValidType, Culprit), % for "type error" for example ValidType = integer, % valid atoms are listed in the ISO standard Culprit = ... some value ..., throw(Exception)
Note that the ISO standard formal term expresses what should be the case or what is the expected correct state, and not what is the problem. For example:
- If a variable is found to be uninstantiated but should be
instantiated, the error term is
instantiation_error: The problem is not that there is an unwanted instantiation, but that the correct state is the one with an instantiated variable.
- In case a variable is found to be instantiated but should be
uninstantiated (because it will be used for output), the error term is
uninstantiation_error(Culprit): The problem is not that there is lack of instantiation, but that the correct state is the one which Culprit (or one of its subterms) is more uninstantiated than is the case.
- If you try to disassemble an empty list with compound_name_arguments/3,
the error term is
type_error(compound,). The problem is not that
is (erroneously) a compound term, but that a compound term is expected and
does not belong to that class.
User predicates are free to choose the structure of their exception terms (i.e., they can define their own conventions) but should adhere to the ISO standard if possible, in particular for libraries.
Notably, exceptions of the shape
are recognised by the development tools and therefore expressing
unexpected situations using these exceptions improves the debugging
In SWI-Prolog, the second argument of the exception term, i.e., the
Context argument, is generally of the form
context(Location, Message), where:
describes the execution context in which the exception occurred. While the Location argument may be specified as a predicate indicator (Name/Arity), it is typically filled by the
library(prolog_stack)library. This library recognises uncaught errors or errors caught by catch_with_backtrace/3 and fills the Location argument with a backtrace.
provides an additional description of the error or can be left as a fresh variable if there is nothing appropriate to fill in.
ISO standard exceptions can be thrown via the predicates exported
library(error). Termwise, these predicates look
exactly like the
Formal of the ISO standard error term they throw:
- instantiation_error/1 (the argument is not used: ISO specifies no argument)
- existence_error/3 (a SWI-Prolog extension that is not ISO)