\newpage
\section{Format of definitions}
%HEVEA\cutdef[1]{subsection}
\subsection{General format}
The definition of control constructs, directives and built-in predicates is
presented as follows:

\Templates

Specifies the types of the arguments and which of them shall be instantiated
(mode). Types and modes are described later \RefSP{Types-and-modes}.

\Description

Describes the behavior (in the absence of any error conditions). It is
explicitly mentioned when a built-in predicate is re-executable on
backtracking. Predefined operators involved in the definition are also
mentioned.

\Errors

Details the error conditions. Possible errors are detailed later
\RefSP{Errors}.  For directives, this part is omitted.

\Portability

Specifies whether the definition conforms to the ISO standard or is a GNU Prolog
extension.

\subsection{Types and modes}
\label{Types-and-modes}
The templates part defines, for each argument of the concerned built-in
predicate, its mode and type. The mode specifies whether or not the argument
must be instantiated when the built-in predicate is called. The mode is
encoded with a symbol just before the type. Possible modes are:

\begin{itemize}

\item \texttt{+}: the argument must be instantiated.

\item \texttt{-}: the argument must be a variable (will be instantiated if
the built-in predicate succeeds).

\item \texttt{?}: the argument can be instantiated or a variable.

\end{itemize}

The type of an argument is defined by the following table:

\begin{tabular}{|l|p{11.5cm}|}
\hline

Type & Description \\

\hline\hline

\texttt{\Param{TYPE}\_list} & a list whose the type of each element is
\Param{TYPE} \\

\hline

\texttt{\Param{TYPE1}\_or\_\Param{TYPE2}} & a term whose type is either
\Param{TYPE1} or \Param{TYPE2} \\

\hline

\texttt{atom} & an atom \\

\hline

\texttt{atom\_property} & an atom property \RefSP{atom-property/2} \\

\hline

\texttt{boolean} & the atom \texttt{true} or \texttt{false} \\

\hline

\texttt{byte} & an integer $\geq$ 0 and $\leq$ 255 \\

\hline

\texttt{callable\_term} & an atom or a compound term \\

\hline

\texttt{character} & a single character atom \\

\hline

\texttt{character\_code} & an integer $\geq$ 1 and $\leq$ 255 \\

\hline

\texttt{clause} & a clause (fact or rule) \\

\hline

\texttt{close\_option} & a close option \RefSP{close/2} \\

\hline

\texttt{compound\_term} & a compound term \\

\hline

\texttt{evaluable} & an arithmetic expression \RefSP{Evaluation-of-an-arithmetic-expression} \\

\hline

\texttt{fd\_bool\_evaluable} & a boolean FD expression \RefSP{Boolean-FD-expressions} \\

\hline

\texttt{fd\_labeling\_option} & an FD labeling option \RefSP{fd-labeling/2}
\\

\hline

\texttt{fd\_evaluable} & an arithmetic FD expression \RefSP{FD-arithmetic-expressions} \\

\hline

\texttt{fd\_variable} & an FD variable \\

\hline

\texttt{flag} & a \Idx{Prolog flag} \RefSP{set-prolog-flag/2} \\

\hline

\texttt{float} & a floating point number \\

\hline

\texttt{head} & a head of a clause (atom or compound term) \\

\hline

\texttt{integer} & an integer \\

\hline

\texttt{in\_byte} & an integer $\geq$ 0 and $\leq$ 255 or \texttt{-1} (for
the end-of-file) \\

\hline

\texttt{in\_character} & a single character atom or the atom
\texttt{end\_of\_file} (for the end-of-file) \\

\hline

\texttt{in\_character\_code} & an integer $\geq$ 1 and $\leq$ 255 or
\texttt{-1} (for the end-of-file) \\

\hline

\texttt{io\_mode} & an atom in: \texttt{read}, \texttt{write} or
\texttt{append} \\

\hline

\texttt{list} & the empty list \texttt{[]} or a non-empty list
\texttt{[\_|\_]} \\

\hline

\texttt{nonvar} & any term that is not a variable \\

\hline

\texttt{number} & an integer or a floating point number \\

\hline

\texttt{operator\_specifier} & an operator specifier \RefSP{op/3:(Term-input/output)} \\

\hline

\texttt{os\_file\_property} & an operating system file property \RefSP{file-property/2}
\\

\hline

\texttt{predicate\_indicator} & a term \texttt{Name/Arity} where
\texttt{Name} is an atom and \texttt{Arity} an integer $\geq$ 0. A callable
term can be given if the \IdxPF{strict\_iso} \Idx{Prolog flag} is switched
off \RefSP{set-prolog-flag/2} \\
\hline

\texttt{predicate\_property} & a predicate property
\RefSP{predicate-property/2} \\

\hline

\texttt{read\_option} & a read option \RefSP{read-term/3} \\

\hline

\texttt{socket\_address} & a term of the form \texttt{'AF\_UNIX'(A)} or
\texttt{'AF\_INET'(A,N)} where \texttt{A} is an atom and \texttt{N} an
integer \\

\hline

\texttt{socket\_domain} & an atom in: \texttt{'AF\_UNIX'} or
\texttt{'AF\_INET'} \\

\hline

\texttt{source\_sink} & an atom identifying a source or a sink \\

\hline

\texttt{stream} & a stream-term: a term of the form \texttt{'\$stream'(N)}
where \texttt{N} is an integer $\geq$ 0 \\

\hline

\texttt{stream\_option} & a stream option \RefSP{open/4} \\

\hline

\texttt{stream\_or\_alias} & a stream-term or an alias (atom) \\

\hline

\texttt{stream\_position} & a stream position: a term
\texttt{'\$stream\_position'(I1, I2, I3, I4)} where
\texttt{I1}, \texttt{I2}, \texttt{I3} and \texttt{I4} are integers \\

\hline

\texttt{stream\_property} & a stream property \RefSP{stream-property/2} \\

\hline

\texttt{stream\_seek\_method} & an atom in: \texttt{bof}, \texttt{current}
or \texttt{eof} \\

\hline

\texttt{term} & any term \\

\hline

\texttt{var\_binding\_option} & a variable binding option
\RefSP{bind-variables/2} \\

\hline

\texttt{write\_option} & a write option \RefSP{write-term/3} \\

\hline
\end{tabular}

\subsection{Errors}
\label{Errors}

\subsubsection{General format and error context}
\label{General-format-and-error-context}
When an error occurs an exception of the form:
\texttt{error(\Param{ErrorTerm}, \Param{Caller})} is raised.
\Param{ErrorTerm} is a term specifying the error (detailed in next
sections) and \Param{Caller} is a term specifying the context of
the error. The context is either the predicate indicator of the last invoked
built-in predicate or an atom giving general context information.

Using exceptions allows the user both to recover an error using
\IdxPB{catch/3} \RefSP{catch/3} and to raise an error using
\IdxPB{throw/1} \RefSP{catch/3}. 

To illustrate how to write a error cases, let us write a predicate
\texttt{my\_pred(X)} where \texttt{X} must be an integer:

\begin{Indentation}
\begin{verbatim}
my_pred(X) :-
        (   nonvar(X) ->
            true
        ;   throw(error(instantiation_error), my_pred/1)),
        ),
        (   integer(X) ->
            true
        ;   throw(error(type_error(integer, X), my_pred/1))
        ),
        ...
\end{verbatim}
\end{Indentation}

To help the user to write these error cases, a set of system predicates is
provided to raise errors. These predicates are of the form
\texttt{'\$pl\_err\_...'} and they all refer to the implicit error context.
The predicates \IdxPB{set\_bip\_name/2} \RefSP{set-bip-name/2} and
\IdxPB{current\_bip\_name/2} \RefSP{current-bip-name/2} are provided to
set and recover the name and the arity associated to this context (an arity
$<$ 0 means that only the atom corresponding to the functor is significant).
Using these system predicates the user could define the above predicate as
follow:

\begin{Indentation}
\begin{verbatim}
my_pred(X) :-
        set_bip_name(my_pred,1),
        (   nonvar(X) ->
            true
        ;   '$pl_err_instantiation'
        ),
        (   integer(X) ->
            true
        ;   '$pl_err_type'(integer, X)
        ),
        ...
\end{verbatim}
\end{Indentation}

The following sections detail each kind of errors (and associated system
predicates).

\subsubsection{Instantiation error}
\label{Instantiation-error}
An instantiation error occurs when an argument or one of its components is
variable while an instantiated argument was expected.
\Param{ErrorTerm} has the following form:
\texttt{instantiation\_error}.

The system predicate \texttt{'\$pl\_err\_instantiation'} raises this
error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Type error}
\label{Type-error}
A type error occurs when the type of an argument or one of its components is
not the expected type (but not a variable). \Param{ErrorTerm} has
the following form: \texttt{type\_error(\Param{Type}, Culprit)} where
\Param{Type} is the expected type and \Param{Culprit}
the argument which caused the error. \Param{Type} is one of:

\begin{ItemizeThreeCols}

\item \texttt{atom}

\item \texttt{atomic}

\item \texttt{boolean}

\item \texttt{byte}

\item \texttt{callable}

\item \texttt{character}

\item \texttt{compound}

\item \texttt{evaluable}

\item \texttt{fd\_bool\_evaluable}

\item \texttt{fd\_evaluable}

\item \texttt{fd\_variable}

\item \texttt{float}

\item \texttt{in\_byte}

\item \texttt{in\_character}

\item \texttt{integer}

\item \texttt{list}

\item \texttt{number}

\item \texttt{predicate\_indicator}

\item \texttt{variable}

\end{ItemizeThreeCols}

The system predicate \texttt{'\$pl\_err\_type'(Type, Culprit)} raises this
error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Domain error}
\label{Domain-error}
A domain error occurs when the type of an argument is correct but its value
is outside the expected domain. \Param{ErrorTerm} has the
following form: \texttt{domain\_error(\Param{Domain}, \Param{Culprit})}
where \Param{Domain} is the expected domain and
\Param{Culprit} the argument which caused the error.
\Param{Domain} is one of:

\begin{ItemizeThreeCols}

\item \texttt{atom\_property}

\item \texttt{buffering\_mode}

\item \texttt{character\_code\_list}

\item \texttt{close\_option}

\item \texttt{date\_time}

\item \texttt{eof\_action}

\item \texttt{fd\_labeling\_option}

\item \texttt{flag\_value}

\item \texttt{format\_control\_sequence}

\item \texttt{g\_array\_index}

\item \texttt{io\_mode}

\item \texttt{non\_empty\_list}

\item \texttt{not\_less\_than\_zero}

\item \texttt{operator\_priority}

\item \texttt{operator\_specifier}

\item \texttt{os\_file\_permission}

\item \texttt{os\_file\_property}

\item \texttt{os\_path}

\item \texttt{predicate\_property}

\item \texttt{prolog\_flag}

\item \texttt{read\_option}

\item \texttt{selectable\_item}

\item \texttt{socket\_address}

\item \texttt{socket\_domain}

\item \texttt{source\_sink}

\item \texttt{statistics\_key}

\item \texttt{statistics\_value}

\item \texttt{stream}

\item \texttt{stream\_option}

\item \texttt{stream\_or\_alias}

\item \texttt{stream\_position}

\item \texttt{stream\_property}

\item \texttt{stream\_seek\_method}

\item \texttt{stream\_type}

\item \texttt{term\_stream\_or\_alias}

\item \texttt{var\_binding\_option}

\item \texttt{write\_option}

\end{ItemizeThreeCols}

The system predicate \texttt{'\$pl\_err\_domain'(Domain, Culprit)} raises
this error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Existence error}
\label{Existence-error}
an existence error occurs when an object on which an operation is to be
performed does not exist. \Param{ErrorTerm} has the following
form: \texttt{existence\_error(\Param{Object}, \Param{Culprit})} where
\Param{Object} is the type of the object and
\Param{Culprit} the argument which caused the error.
\Param{Object} is one of:

\begin{ItemizeThreeCols}

\item \texttt{procedure}

\item \texttt{source\_sink}

\item \texttt{stream}

\end{ItemizeThreeCols}

The system predicate \texttt{'\$pl\_err\_existence'(Object, Culprit)} raises
this error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Permission error}
\label{Permission-error}
A permission error occurs when an attempt to perform a prohibited operation
is made. \Param{ErrorTerm} has the following form:
\texttt{permission\_error(\Param{Operation}, \Param{Permission},
\Param{Culprit})} where \Param{Operation} is the operation which
caused the error, \Param{Permission} the type of the tried
permission and \Param{Culprit} the argument which caused the
error. \Param{Operation} is one of:

\begin{ItemizeThreeCols}

\item \texttt{access}

\item \texttt{add\_alias}

\item \texttt{close}

\item \texttt{create}

\item \texttt{input}

\item \texttt{modify}

\item \texttt{open}

\item \texttt{output}

\item \texttt{reposition}

\end{ItemizeThreeCols}

and \Param{Permission} is one of:

\begin{ItemizeThreeCols}

\item \texttt{binary\_stream}

\item \texttt{flag}

\item \texttt{operator}

\item \texttt{past\_end\_of\_stream}

\item \texttt{private\_procedure}

\item \texttt{source\_sink}

\item \texttt{static\_procedure}

\item \texttt{stream}

\item \texttt{text\_stream}

\end{ItemizeThreeCols}

The system predicate \texttt{'\$pl\_err\_permission'(Operation, Permission,
Culprit)} raises this error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Representation error}
\label{Representation-error}
A representation error occurs when an implementation limit has been
breached. \Param{ErrorTerm} has the following form:
\texttt{representation\_error(\Param{Limit})} where \Param{Limit}
is the name of the reached limit. \Param{Limit} is one of:

\begin{ItemizeThreeCols}

\item \texttt{character}

\item \texttt{character\_code}

\item \texttt{in\_character\_code}

\item \texttt{max\_arity}

\item \texttt{max\_integer}

\item \texttt{min\_integer}

\item \texttt{too\_many\_variables}

\end{ItemizeThreeCols}

The errors \texttt{max\_integer} and \texttt{min\_integer} are not currently
implemented.

The system predicate \texttt{'\$pl\_err\_representation'(Limit)} raises this 
error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Evaluation error}
\label{Evaluation-error}
An evaluation error occurs when an arithmetic expression gives rise to
an exceptional value. \Param{ErrorTerm} has the following form:
\texttt{evaluation\_error(\Param{Error})} where \Param{Error} is
the name of the error. \Param{Error} is one of:

\begin{ItemizeThreeCols}

\item \texttt{float\_overflow}

\item \texttt{int\_overflow}

\item \texttt{undefined}

\item \texttt{underflow}

\item \texttt{zero\_divisor}

\end{ItemizeThreeCols}

The errors \texttt{float\_overflow}, \texttt{int\_overflow},
\texttt{undefined} and \texttt{underflow} are not currently
implemented.

The system predicate \texttt{'\$pl\_err\_evaluation'(Error)} raises this
error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Resource error}
\label{Resource-error}
A resource error occurs when GNU Prolog does not have enough resources.
\Param{ErrorTerm} has the following form:
\texttt{resource\_error(\Param{Resource})} where \Param{Resource} is the
name of the resource. \Param{Resource} is one of:

\begin{ItemizeThreeCols}

\item \texttt{print\_object\_not\_linked}

\item \texttt{too\_big\_fd\_constraint}

\item \texttt{too\_many\_open\_streams}

\end{ItemizeThreeCols}

The system predicate \texttt{'\$pl\_err\_resource'(Resource)} raises this
error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{Syntax error}
\label{Syntax-error}
A syntax error occurs when a sequence of character does not conform to the
syntax of terms. \Param{ErrorTerm} has the following form:
\texttt{syntax\_error(\Param{Error})} where \Param{Error} is an
atom explaining the error.

The system predicate \texttt{'\$pl\_err\_syntax'(Error)} raises this
error in the current error context \RefSP{General-format-and-error-context}.

\subsubsection{System error}
A system error can occur at any stage. A system error is generally
associated to an external component (e.g. operating system).
\Param{ErrorTerm} has the following form:
\texttt{system\_error(\Param{Error})} where \Param{Error} is an
atom explaining the error. This is an extension to ISO which only defines
\texttt{system\_error} without arguments.

The system predicate \texttt{'\$pl\_err\_system'(Error)} raises this
error in the current error context \RefSP{General-format-and-error-context}.

%HEVEA\cutend