\newpage
\section{Prolog built-in predicates}
%HEVEA\cutdef[1]{subsection}
\subsection{Type testing}

\subsubsection{\texttt{var/1},
\texttt{nonvar/1},
\texttt{atom/1},
\texttt{integer/1},
\texttt{float/1},
\texttt{number/1},
\texttt{atomic/1}, \\
\texttt{compound/1},
\texttt{callable/1},
\texttt{list/1},
\texttt{partial\_list/1},
\texttt{list\_or\_partial\_list/1}}
\label{var/1}

\begin{TemplatesTwoCols}
var(?term)\\
nonvar(?term)\\
atom(?term)\\
integer(?term)\\
float(?term)\\
number(?term)\\
atomic(?term)\\               
compound(?term)\\              
callable(?term)\\            
list(?term)\\                 
partial\_list(?term)\\      
list\_or\_partial\_list(?term)

\end{TemplatesTwoCols}

\Description

\IdxPBD[var/1]{var(Term)} succeeds if \texttt{Term} is currently
uninstantiated (which therefore has not been bound to anything, except
possibly another uninstantiated variable).

\IdxPBD[nonvar/1]{nonvar(Term)} succeeds if \texttt{Term} is currently instantiated
(opposite of \texttt{var/1}).

\IdxPBD[atom/1]{atom(Term)} succeeds if \texttt{Term} is currently instantiated
to an atom.

\IdxPBD[integer/1]{integer(Term)} succeeds if \texttt{Term} is currently
instantiated to an integer.

\IdxPBD[float/1]{float(Term)} succeeds if \texttt{Term} is currently instantiated
to a floating point number.

\IdxPBD[number/1]{number(Term)} succeeds if \texttt{Term} is currently instantiated
to an integer or a floating point number.

\IdxPBD[atomic/1]{atomic(Term)} succeeds if \texttt{Term} is currently instantiated
to an atom, an integer or a floating point number.

\IdxPBD[compound/1]{compound(Term)} succeeds if \texttt{Term} is currently
instantiated to a compound term, i.e. a term of arity $>$ 0 (a list or a
structure).

\IdxPBD[callable/1]{callable(Term)} succeeds if \texttt{Term} is currently
instantiated to a callable term, i.e. an atom or a compound term.

\IdxPBD[list/1]{list(Term)} succeeds if \texttt{Term} is currently instantiated
to a list, i.e. the atom \texttt{[]} (empty list) or a term with principal
functor \texttt{'.'/2} and with second argument (the tail) a list.

\IdxPBD[partial\_list/1]{partial\_list(Term)} succeeds if \texttt{Term} is currently
instantiated to a partial list, i.e. a variable or a term whose the main
functor is \texttt{'.'/2} and the second argument (the tail) is a partial
list.

\IdxPBD[list\_or\_partial\_list/1]{list\_or\_partial\_list(Term)} succeeds if \texttt{Term} is
currently instantiated to a list or a partial list.

\PlErrorsNone

\Portability

\texttt{var/1}, \texttt{nonvar/1}, \texttt{atom/1}, \texttt{integer/1},
\texttt{float/1}, \texttt{number/1}, \texttt{atomic/1}, \texttt{compound/1}
and \texttt{callable/1} are ISO predicates.

\texttt{list/1}, \texttt{partial\_list/1} and
\texttt{list\_or\_partial\_list/1} are GNU Prolog predicates.

\subsection{Term unification}

\subsubsection{\texttt{(=)/2} - Prolog unification}

\begin{TemplatesOneCol}
=(?term, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[(=)/2]{Term1 = Term2} unifies \texttt{Term1} and \texttt{Term2}. No occurs
check is done, i.e. this predicate does not check if a variable is unified
with a compound term containing this variable (this can lead to an infinite
loop).

\texttt{=} is a predefined infix operator \RefSP{op/3:(Term-input/output)}.

\PlErrorsNone

\Portability

ISO predicate.

\subsubsection{\texttt{unify\_with\_occurs\_check/2}}

\begin{TemplatesOneCol}
unify\_with\_occurs\_check(?term, ?term)
\end{TemplatesOneCol}

\Description

\IdxPBD[unify\_with\_occurs\_check/2]{unify\_with\_occurs\_check(Term1, Term2)} unifies \texttt{Term1} and
\texttt{Term2}. The occurs check test is done (i.e. the unification fails if
a variable is unified with a compound term containing this variable).

\PlErrorsNone

\Portability

ISO predicate.

\subsubsection{\texttt{({\bs}=)/2} - not Prolog unifiable}

\begin{TemplatesOneCol}
{\bs}=(?term, ?term)
\end{TemplatesOneCol}

\Description

\IdxPBD[({\bs}=)/2]{Term1 {\bs}= Term2} succeeds if \texttt{Term1} and \texttt{Term2}
are not unifiable (no occurs check is done). 

\texttt{{\bs}=} is a predefined infix operator \RefSP{op/3:(Term-input/output)}.

\PlErrorsNone

\Portability

ISO predicate.

\subsection{Term comparison}

\subsubsection{Standard total ordering of terms}
\label{Standard-total-ordering-of-terms}
The built-in predicates described in this section allows the user to compare
Prolog terms. Prolog terms are totally ordered according to the standard
total ordering of terms which is as follows (from the smallest term to the
greatest):

\begin{itemize}

\item variables, oldest first.

\item finite domain variables \RefSP{Finite-Domain-variables}, oldest
first.

\item floating point numbers, in numeric order. 

\item integers, in numeric order. 

\item atoms, in alphabetical (i.e. character code) order. 

\item compound terms, ordered first by arity, then by the name of the
principal functor and by the arguments in left-to-right order.

\end{itemize}

A list is treated as a compound term (whose principal functor is
\texttt{'.'/2}).

The portability of the order of variables is not guaranteed (in the ISO
reference the oder of variables is system dependent).

\subsubsection{\texttt{(==)/2} - term identical,
\texttt{({\bs}==)/2} - term not identical, \\
\texttt{(@{\lt})/2} - term less than,
\texttt{(@={\lt})/2} - term less than or equal to, \\
\texttt{(@{\gt})/2} - term greater than,
\texttt{(@{\gt}=)/2} - term greater than or equal to}
\label{(==)/2} 

\begin{TemplatesTwoCols}
==(?term, ?term)\\
{\bs}==(?term, ?term) \\
@{\lt}(?term, ?term) \\
@={\lt}(?term, ?term)\\
@{\gt}(?term, ?term)\\
@{\gt}=(?term, ?term)

\end{TemplatesTwoCols}

\Description

These predicates compare two terms according to the standard total ordering
of terms \RefSP{Standard-total-ordering-of-terms}.

\IdxPBD[(==)/2]{Term1 == Term2} succeeds if \texttt{Term1} and \texttt{Term2} are
equal. 

\IdxPBD[({\bs}==)/2]{Term1 {\bs}== Term2} succeeds if \texttt{Term1} and
\texttt{Term2} are different.

\IdxPBD[("@{\lt})/2]{Term1 @{\lt} Term2} succeeds if \texttt{Term1} is less than
\texttt{Term2}.

\IdxPBD[("@={\lt})/2]{Term1 @={\lt} Term2} succeeds if \texttt{Term1} is less than or
equal to \texttt{Term2}.

\IdxPBD[("@{\gt})/2]{Term1 @{\gt} Term2} succeeds if \texttt{Term1} is greater than
\texttt{Term2}.

\IdxPBD[("@{\gt}=)/2]{Term1 @{\gt}= Term2} succeeds if \texttt{Term1} is greater than
or equal to \texttt{Term2}.

\texttt{==}, \texttt{{\bs}==}, \texttt{@{\lt}}, \texttt{@={\lt}},
\texttt{@{\gt}} and \texttt{@{\gt}=} are predefined infix operators \RefSP{op/3:(Term-input/output)}.

\PlErrorsNone

\Portability

ISO predicates.

\subsubsection{\texttt{compare/3}}

\begin{TemplatesOneCol}
compare(?atom, +term, +term)

\end{TemplatesOneCol}

\Description

\IdxPBD[compare/3]{compare(Result, Term1, Term2)} compares \texttt{Term1} and
\texttt{Term2} according to the standard \RefSP{Standard-total-ordering-of-terms} and unifies \texttt{Result} with:

\begin{itemize}

\item the atom \texttt{{\lt}} if \texttt{Term1} is less than \texttt{Term2}.

\item the atom \texttt{=} if \texttt{Term1} and \texttt{Term2} are equal.

\item the atom \texttt{{\gt}} if \texttt{Term1} is greater than
\texttt{Term2}.

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Result} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Result)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Term processing}

\subsubsection{\texttt{functor/3}}

\begin{TemplatesOneCol}
functor(+nonvar, ?atomic, ?integer)\\
functor(-nonvar, +atomic, +integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[functor/3]{functor(Term, Name, Arity)} succeeds if the principal functor of
\texttt{Term} is \texttt{Name} and its arity is \texttt{Arity}. This
predicate can be used in two ways:

\begin{itemize}

\item \texttt{Term} is not a variable: extract the name (an atom or a number
if \texttt{Term} is a number) and the arity of \texttt{Term} (if
\texttt{Term} is atomic \texttt{Arity} = 0).

\item \texttt{Term} is a variable: unify \texttt{Term} with a general term
whose principal functor is given by \texttt{Name} and arity is given by
\texttt{Arity}.

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Term} and \texttt{Name} are both variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Term} and \texttt{Arity} are both variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Term} is a variable and \texttt{Name} is neither a variable
nor an atomic term}
\ErrTerm{type\_error(atomic, Name)}

\ErrCond{\texttt{Term} is a variable and \texttt{Arity} is neither a
variable nor an integer}
\ErrTerm{type\_error(integer, Arity)}

\ErrCond{\texttt{Term} is a variable, \texttt{Name} is a constant but not an
atom and \texttt{Arity} is an integer $>$ 0}
\ErrTerm{type\_error(atom, Name)}

\ErrCond{\texttt{Term} is a variable and \texttt{Arity} is an integer $>$
\texttt{max\_arity} flag \RefSP{set-prolog-flag/2}}
\ErrTerm{representation\_error(max\_arity)}

\ErrCond{\texttt{Term} is a variable and \texttt{Arity} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Arity)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{arg/3}}

\begin{TemplatesOneCol}
arg(+integer, +compound\_term, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[arg/3]{arg(N, Term, Arg)} succeeds if the \texttt{N}\emph{th} argument of
\texttt{Term} is \texttt{Arg}.

\begin{PlErrors}

\ErrCond{\texttt{N} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Term} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{N} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, N)}

\ErrCond{\texttt{Term} is neither a variable nor a compound term}
\ErrTerm{type\_error(compound, Term)}

\ErrCond{\texttt{N} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, N)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{(=..)/2} - univ}

\begin{TemplatesOneCol}
=..(+nonvar, ?list)\\
=..(-nonvar, +list)

\end{TemplatesOneCol}

\Description

\IdxPBD[(=..)/2]{Term =.. List} succeeds if \texttt{List} is a list whose head is the
atom corresponding to the principal functor of \texttt{Term} and whose tail
is a list of the arguments of \texttt{Term}.

\texttt{=..} is a predefined infix operator \RefSP{op/3:(Term-input/output)}.

\begin{PlErrors}

\ErrCond{\texttt{Term} is a variable and \texttt{List} is a partial list}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{List} is neither a partial list nor a list}
\ErrTerm{type\_error(list, List)}

\ErrCond{\texttt{Term} is a variable and \texttt{List} is a list whose head
is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{List} is a list whose head \texttt{H} is neither an atom
nor a variable and whose tail is not the empty list}
\ErrTerm{type\_error(atom, H)}

\ErrCond{\texttt{List} is a list whose head \texttt{H} is a compound term
and whose tail is the empty list}
\ErrTerm{type\_error(atomic, H)}

\ErrCond{\texttt{Term} is a variable and \texttt{List} is the empty list}
\ErrTerm{domain\_error(non\_empty\_list, [])}

\ErrCond{\texttt{Term} is a variable and the tail of \texttt{List} has a
length $>$ \texttt{max\_arity} flag \RefSP{set-prolog-flag/2}}
\ErrTerm{representation\_error(max\_arity)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{copy\_term/2}}

\begin{TemplatesOneCol}
copy\_term(?term, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[copy\_term/2]{copy\_term(Term1, Term2)} succeeds if \texttt{Term2} unifies with a
term \texttt{T} which is a renamed copy of \texttt{Term1}.

\PlErrorsNone

\Portability

ISO predicate.

\subsubsection{\texttt{setarg/4},
\texttt{setarg/3}}

\begin{TemplatesOneCol}
setarg(+integer, +compound\_term, +term, +boolean)\\
setarg(+integer, +compound\_term, +term)

\end{TemplatesOneCol}

\Description

\IdxPBD[setarg/4]{setarg(N, Term, NewValue, Undo)} replaces destructively the
\texttt{N}\emph{th} argument of \texttt{Term} with \texttt{NewValue}. This
assignment is undone on backtracking if \texttt{Undo} = \texttt{true}. This
should only used if there is no further use of the old value of the replaced
argument. If \texttt{Undo} = \texttt{false} then \texttt{NewValue} must be
either an atom or an integer.

\IdxPBD[setarg/3]{setarg(N, Term, NewValue)} is equivalent to \texttt{setarg(N, Term,
NewValue, true)}.

\begin{PlErrors}

\ErrCond{\texttt{N} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{N} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, N)}

\ErrCond{\texttt{N} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, N)}

\ErrCond{\texttt{Term} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Term} is neither a variable nor a compound term}
\ErrTerm{type\_error(compound, Term)}

\ErrCond{\texttt{NewValue} is neither an atom nor an integer and
\texttt{Undo} = \texttt{false}}
\ErrTerm{type\_error(atomic, NewValue)}

\ErrCond{\texttt{Undo} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Undo} is neither a variable nor a boolean}
\ErrTerm{type\_error(boolean, Undo)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Variable naming/numbering}
\label{Variable-naming/numbering}

\subsubsection{\texttt{name\_singleton\_vars/1}}
\label{name-singleton-vars/1}

\begin{TemplatesOneCol}
name\_singleton\_vars(?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[name\_singleton\_vars/1]{name\_singleton\_vars(Term)} binds each singleton variable appearing
in \texttt{Term} with a term of the form \texttt{'\$VARNAME'('\_')}. Such a
term can be output by \texttt{write\_term/3} as a variable name
\RefSP{write-term/3}.

\PlErrorsNone

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{name\_query\_vars/2}}
\label{name-query-vars/2}

\begin{TemplatesOneCol}
name\_query\_vars(+list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[name\_query\_vars/2]{name\_query\_vars(List, Rest)} for each element of \texttt{List} of
the form \texttt{Name = Var} where \texttt{Name} is an atom and \texttt{Var}
a variable, binds \texttt{Var} with the term \texttt{'\$VARNAME'(Name)}.
Such a term can be output by \texttt{write\_term/3} as a variable name
\RefSP{write-term/3}. \texttt{Rest} is unified with the list of elements of
\texttt{List} that have not given rise to a binding. This predicate is
provided as a way to name the variable lists obtained returned by
\texttt{read\_term/3} with \IdxPO[variable\_names]{variable\_names(List)} or
\IdxPO[singletons]{singletons(List)} options \RefSP{read-term/3}.

\begin{PlErrors}

\ErrCond{\texttt{List} is a partial list}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{List} is neither a partial list nor a list}
\ErrTerm{type\_error(list, List)}

\ErrCond{\texttt{Rest} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Rest)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{bind\_variables/2},
\texttt{numbervars/3},
\texttt{numbervars/1}}
\label{bind-variables/2}

\begin{TemplatesOneCol}
bind\_variables(?term, +var\_binding\_option\_list)\\
numbervars(?term, +integer, ?integer)\\
numbervars(?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[bind\_variables/2]{bind\_variables(Term, Options)} binds each variable appearing in
\texttt{Term} according to the options given by \texttt{Options}. 

\SPart{Variable binding options}: \texttt{Options} is a list of variable
binding options. If this list contains contradictory options, the rightmost
option is the one which applies. Possible options are:

\begin{itemize}

\item \IdxPOD{numbervars}: specifies that each variable appearing in
\texttt{Term} should be bound to a term of the form \texttt{'\$VAR'(N)}
where \texttt{N} is an integer. Such a term can be output by
\texttt{write\_term/3} as a variable name \RefSP{write-term/3}. This is
the default.

\item \IdxPOD{namevars}: specifies that each variables appearing in
\texttt{Term} shall be bound to a term of the form
\texttt{'\$VARNAME'(Name)} where \texttt{Name} is the atom that would be
output by \texttt{write\_term/3} seeing a term of the \texttt{'\$VAR'(N)}
where \texttt{N} is an integer. Such a term can be output by
\texttt{write\_term/3} as a variable name \RefSP{write-term/3}. This is
the alternative to \texttt{numbervars}.

\item \IdxPOD[from]{from(From)}: the first integer \texttt{N} to use for
number/name variables of \texttt{Term} is \texttt{From}. The default value
is \texttt{0}.

\item \IdxPOD[next]{next(Next)}: when \texttt{bind\_variables/2} succeeds,
\texttt{Next} is unified with the (last integer \texttt{N})+1 used
to bind the variables of \texttt{Term}. 

\item \IdxPOD[exclude]{exclude(List)}: collects all variable names appearing
in \texttt{List} to avoid a clash when binding a variable of \texttt{Term}.
Precisely a number \texttt{N} $\geq$ \texttt{From} will not be used to bind a
variable of \texttt{Term} if:

\begin{itemize}

\item there is a sub-term of \texttt{List} of the form \texttt{'\$VAR'(N)}
or \texttt{'\$VARNAME'(Name)} where \texttt{Name} is the constant that would
be output by \texttt{write\_term/3} seeing a term of the
\texttt{'\$VAR'(N)}.

\item an element of \texttt{List} is of the form \texttt{Name = Var} where
\texttt{Name} is an atom that would be output by \texttt{write\_term/3} on
seeing a term of the from \texttt{'\$VAR'(N)}. This case allows for lists
returned by \texttt{read\_term/3}
(with \IdxPO[variable\_names]{variable\_names(List)} or
\IdxPO[singletons]{singletons(List)} options) \RefSP{read-term/3} and by
\texttt{name\_query\_vars/2} \RefSP{name-query-vars/2}.

\end{itemize}

\end{itemize}

\IdxPBD[numbervars/3]{numbervars(Term, From, Next)} is equivalent to
\texttt{bind\_variables(Term, [from(From), next(Next)]}, i.e. each variable
of \texttt{Term} is bound to \texttt{'\$VAR'(N)} where \texttt{From $\leq$}
\texttt{N} $<$ \texttt{Next}.


\IdxPBD[numbervars/1]{numbervars(Term)} is equivalent to \texttt{numbervars(Term, 0, \_)}.

\begin{PlErrors}

\ErrCond{\texttt{Options} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Options)}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is neither a
variable nor a variable binding option} 
\ErrTerm{domain\_error(var\_binding\_option, E)}

\ErrCond{\texttt{From} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{From} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, From)}

\ErrCond{\texttt{Next} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Next)}

\ErrCond{\texttt{List} is a partial list}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{List} is neither a partial list nor a list}
\ErrTerm{type\_error(list, List)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{term\_ref/2}}

\begin{TemplatesOneCol}
term\_ref(+term, ?integer)\\
term\_ref(?term, +integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[term\_ref/2]{term\_ref(Term, Ref}) succeeds if the internal reference of
\texttt{Term} is \texttt{Ref}. This predicate can be used either to obtain
the internal reference of a term or to obtain the term associated to a given
reference. Note that two identical terms can have different internal
references. A good way to use this predicate is to first record the internal
reference of a given term and to later re-obtain the term via this
reference.

\begin{PlErrors}

\ErrCond{\texttt{Term} and \texttt{Ref} are both variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Ref} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Ref)}

\ErrCond{\texttt{Ref} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Ref)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Arithmetic}

\subsubsection{Evaluation of an arithmetic expression}
\label{Evaluation-of-an-arithmetic-expression}
An arithmetic expression is a Prolog term built from numbers,
variables, and functors (or operators) that represent arithmetic functions.
When an expression is evaluated each variable must be bound to a
non-variable expression. An expression evaluates to a number, which may be
an integer or a floating point number. The following table details the
components of an arithmetic expression, how they are evaluated, the types
expected/returned and if they are ISO or an extension:

\begin{tabular}{|l|L{7.4cm}|c|c|}
\hline

Expression & Result = \textit{eval}(Expression) & Signature & ISO \\

\hline\hline

Variable & must be bound to a non-variable expression \texttt{E}. 
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

           The result is \textit{eval}(\texttt{E})
         & IF $\rightarrow$ IF & Y \\
         

\hline

integer number & this number & I $\rightarrow$ I & Y \\

\hline

floating point number & this number & F $\rightarrow$ F & Y \\

\hline

\texttt{+ E} & \textit{eval}(\texttt{E}) & IF $\rightarrow$ IF & N \\

\hline

\texttt{- E} & - \textit{eval}(\texttt{E}) & IF $\rightarrow$ IF & Y \\

\hline

\texttt{inc(E)} & \textit{eval}(\texttt{E}) + 1 & IF $\rightarrow$ IF & N \\

\hline

\texttt{dec(E)} & \textit{eval}(\texttt{E}) - 1 & IF $\rightarrow$ IF & N \\

\hline

\texttt{E1 + E2} & \textit{eval}(\texttt{E1}) + \textit{eval}(\texttt{E2}) &
IF, IF $\rightarrow$ IF & Y \\

\hline

\texttt{E1 - E2} & \textit{eval}(\texttt{E1}) - \textit{eval}(\texttt{E2}) &
IF, IF $\rightarrow$ IF & Y \\

\hline

\texttt{E1 * E2} & \textit{eval}(\texttt{E1}) * \textit{eval}(\texttt{E2}) &
IF, IF $\rightarrow$ IF & Y \\

\hline

\texttt{E1 / E2} & \textit{eval}(\texttt{E1}) / \textit{eval}(\texttt{E2}) &
IF, IF $\rightarrow$ F & Y \\

\hline

\texttt{E1 // E2} & \textit{rnd}(\textit{eval}(\texttt{E1}) /
\textit{eval}(\texttt{E2})) & I, I $\rightarrow$ I & Y \\

\hline

\texttt{E1 rem E2} & \textit{eval}(\texttt{E1}) -
(\textit{rnd}(\textit{eval}(\texttt{E1}) /
\textit{eval}(\texttt{E2}))*\textit{eval}(\texttt{E2})) & I, I $\rightarrow$
I & Y \\

\hline

\texttt{E1 mod E2} & \textit{eval}(\texttt{E1}) - (
$\lfloor$\textit{eval}(\texttt{E1}) / \textit{eval}(\texttt{E2})$\rfloor$
*\textit{eval}(\texttt{E2})) & I, I $\rightarrow$ I & Y \\

\hline

\texttt{E1 /{\bs} E2} & \textit{eval}(\texttt{E1}) bitwise\_and
\textit{eval}(\texttt{E2}) & I, I $\rightarrow$ I & Y \\

\hline

\texttt{E1 {\bs}/ E2} & \textit{eval}(\texttt{E1}) bitwise\_or
\textit{eval}(\texttt{E2}) & I, I $\rightarrow$ I & Y \\

\hline

\texttt{E1 \^{} E2} & \textit{eval}(\texttt{E1}) bitwise\_xor
\textit{eval}(\texttt{E2}) & I, I $\rightarrow$ I & N \\

\hline

\texttt{{\bs} E} & bitwise\_not \textit{eval}(\texttt{E}) & I $\rightarrow$
I & Y \\

\hline

\texttt{E1 {\lt}{\lt} E2} & \textit{eval}(\texttt{E1}) integer\_shift\_left
\textit{eval}(\texttt{E2}) & I, I $\rightarrow$ I & Y \\

\hline

\texttt{E1 {\gt}{\gt} E2} & \textit{eval}(\texttt{E1}) integer\_shift\_right
\textit{eval}(\texttt{E2}) & I, I $\rightarrow$ I & Y \\

\hline

\texttt{abs(E)} & absolute value of \textit{eval}(\texttt{E}) & IF
$\rightarrow$ IF & Y \\

\hline

\texttt{sign(E)} & sign of \textit{eval}(\texttt{E}) (-1 if $<$ 0, 0 if = 0,
+1 if $>$ 0) & IF $\rightarrow$ IF & Y \\

\hline

\texttt{E1 ** E2} & \textit{eval}(\texttt{E1}) raised to the power of
\textit{eval}(\texttt{E2}) & IF, IF $\rightarrow$ F & Y \\

\hline

\texttt{sqrt(E)} & square root of \textit{eval}(\texttt{E}) & IF
$\rightarrow$ F & Y \\

\hline

\texttt{atan(E)} & arc tangent of \textit{eval}(\texttt{E}) & IF
$\rightarrow$ F & Y \\

\hline

\texttt{cos(E)} & cosine of \textit{eval}(\texttt{E}) & IF $\rightarrow$ F &
Y \\

\hline

\texttt{sin(E)} & sine of \textit{eval}(\texttt{E}) & IF $\rightarrow$ F & Y
\\

\hline

\texttt{exp(E)} & $e$ raised to the power of \textit{eval}(\texttt{E}) &
IF $\rightarrow$ F & Y \\

\hline

\texttt{log(E)} & natural logarithms of \textit{eval}(\texttt{E}) & IF
$\rightarrow$ F & Y \\

\hline

\texttt{float(E)} & the floating point number equal to
\textit{eval}(\texttt{E}) & IF $\rightarrow$ F & Y \\

\hline

\texttt{ceiling(E)} & rounds \textit{eval}(\texttt{E}) upward to the
nearest integer & F $\rightarrow$ I & Y \\

\hline

\texttt{floor(E)} & rounds \textit{eval}(\texttt{E}) downward to the
nearest integer & F $\rightarrow$ I & Y \\

\hline

\texttt{round(E)} & rounds \textit{eval}(\texttt{E}) to the nearest integer
& F $\rightarrow$ I & Y \\

\hline

\texttt{truncate(E)} & the integer value of \textit{eval}(\texttt{E}) & F
$\rightarrow$ I & Y \\

\hline

\texttt{float\_fractional\_part(E)} & the float equal to the fractional part
of \textit{eval}(\texttt{E}) & F $\rightarrow$ F & Y \\

\hline

\texttt{float\_integer\_part(E)} & the float equal to the integer part of
\textit{eval}(\texttt{E}) & F $\rightarrow$ F & Y \\

\hline
\end{tabular}

The meaning of the signature field is as follows:

\begin{itemize}

\item I $\rightarrow$ I: unary function, the operand must be an integer and
the result is an integer.

\item F $\rightarrow$ F: unary function, the operand must be a floating
point number and the result is a floating point number.

\item F $\rightarrow$ I: unary function, the operand must be a floating
point number and the result is an integer.

\item IF $\rightarrow$ F: unary function, the operand can be an integer or a
floating point number and the result is a floating point number.

\item IF $\rightarrow$ IF: unary function, the operand can be an integer or
a floating point number and the result has the same type as the operand.

\item I, I $\rightarrow$ I: binary function: each operand must be an integer
and the result is an integer.

\item IF, IF $\rightarrow$ IF: binary function: each operand can be an
integer or a floating point number and the result is a floating point number
if at least one operand is a floating point number, an integer otherwise.

\end{itemize}

\texttt{is}, \texttt{+}, \texttt{-}, \texttt{*}, \texttt{//}, \texttt{/},
\texttt{rem}, and \texttt{mod} are predefined infix operators. \texttt{+}
and \texttt{-} are predefined prefix operators \RefSP{op/3:(Term-input/output)}.

\SPart{Integer division rounding function}: the integer division rounding
function \texttt{\textit{rnd}(X)} rounds the floating point number
\texttt{X} to an integer. There are two possible definitions (depending on
the target machine) for this function which differ on negative numbers:

\begin{itemize}

\item \texttt{\textit{rnd}(X)} = integer part of \texttt{X}, e.g.
\texttt{\textit{rnd}(-1.5)} = \texttt{-1} (round toward 0)

\item \texttt{\textit{rnd}(X)} = $\lfloor$\texttt{X}$\rfloor$, e.g.
\texttt{\textit{rnd}(-1.5)} = \texttt{-2} (round toward $-\infty$)

\end{itemize}

The definition of this function determines the precise definition of the
integer division \texttt{(//)/2} and of the integer remainder
\texttt{(rem)/2}. Rounding toward zero is the most common case. In any case
it is possible to test the value (\texttt{toward\_zero} or \texttt{down}) of
the \IdxPF{integer\_rounding\_function} \Idx{Prolog flag} to determine which
function being used \RefSP{set-prolog-flag/2}.

\SPart{Fast mathematical mode}: in order to speed-up integer computations,
the GNU Prolog compiler can generate faster code when invoked with the
\IdxK{--fast-math} option \RefSP{Using-the-compiler}. In this mode only
integer operations are allowed and a variable in an expression must be bound
at evaluation time to an integer. No type checking is done. 

\begin{PlErrors}

\ErrCond{a sub-expression \texttt{E} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{a sub-expression \texttt{E} is neither a number nor an evaluable
functor}
\ErrTerm{type\_error(evaluable, E)}

\ErrCond{a sub-expression \texttt{E} is a floating point number while an
integer is expected}
\ErrTerm{type\_error(integer, E)}

\ErrCond{a sub-expression \texttt{E} is an integer while a floating point
number is expected}
\ErrTerm{type\_error(float, E)}

\ErrCond{a division by zero occurs}
\ErrTerm{evaluation\_error(zero\_divisor)}

\end{PlErrors}

\Portability

Refer to the above table to determine which evaluable functors are ISO
and which are GNU Prolog extensions. For efficiency reasons, GNU
Prolog does not detect the following ISO arithmetic errors:
\texttt{float\_overflow},
\texttt{int\_overflow, int\_underflow}, and \texttt{undefined}.

\subsubsection{\texttt{(is)/2} - evaluate expression}

\begin{TemplatesOneCol}
is(?nonvar, +evaluable)

\end{TemplatesOneCol}

\Description

\IdxPBD[(is)/2]{Result is Expression} succeeds if \texttt{Result} can be
unified with \textit{eval}(\texttt{Expression}). Refer to the
evaluation of an arithmetic expression for the definition of the
\textit{eval} function
\RefSP{Evaluation-of-an-arithmetic-expression}.

\texttt{is} is a predefined infix operator \RefSP{op/3:(Term-input/output)}.

\Errors

Refer to the evaluation of an arithmetic expression for possible errors
\RefSP{Evaluation-of-an-arithmetic-expression}.

\Portability

ISO predicate.

\subsubsection{\texttt{(=:=)/2} - arithmetic equal,
\texttt{(={\bs}=)/2} - arithmetic not equal, \\
\texttt{({\lt})/2} - arithmetic less than,
\texttt{(={\lt})/2} - arithmetic less than or equal to, \\
\texttt{({\gt})/2} - arithmetic greater than,
\texttt{({\gt}=)/2} - arithmetic greater than or equal to}
\label{(=:=)/2} 

\begin{TemplatesTwoCols}
=:=(+evaluable, +evaluable)\\
={\bs}=(+evaluable, +evaluable)\\
{\lt}(+evaluable, +evaluable)\\
={\lt}(+evaluable, +evaluable)\\
{\gt}(+evaluable, +evaluable)\\
{\gt}=(+evaluable, +evaluable)

\end{TemplatesTwoCols}

\Description

\IdxPBD[(=:=)/2]{Expr1 =:= Expr2} succeeds if \textit{eval}(\texttt{Expr1}) =
\textit{eval}(\texttt{Expr2}).

\IdxPBD[(={\bs}=)/2]{Expr1 ={\bs}= Expr2} succeeds if \textit{eval}(\texttt{Expr1})
$\neq$ \textit{eval}(\texttt{Expr2}).

\IdxPBD[({\lt})/2]{Expr1 {\lt} Expr2} succeeds if \textit{eval}(\texttt{Expr1}) $<$
\textit{eval}(\texttt{Expr2}).

\IdxPBD[(={\lt})/2]{Expr1 ={\lt} Expr2} succeeds if \textit{eval}(\texttt{Expr1})
$\leq$ \textit{eval}(\texttt{Expr2}).

\IdxPBD[({\gt})/2]{Expr1 {\gt} Expr2} succeeds if \textit{eval}(\texttt{Expr1}) $>$
\textit{eval}(\texttt{Expr2}).

\IdxPBD[({\gt}=)/2]{Expr1 {\gt}= Expr2} succeeds if \textit{eval}(\texttt{Expr1})
$\geq$ \textit{eval}(\texttt{Expr2}).

Refer to the evaluation of an arithmetic expression for the definition of
the \textit{eval} function \RefSP{Evaluation-of-an-arithmetic-expression}.

\texttt{=:=}, \texttt{={\bs}=}, \texttt{{\lt}}, \texttt{={\lt}},
\texttt{{\gt}} and \texttt{{\gt}=} are predefined infix operators
\RefSP{op/3:(Term-input/output)}.

\Errors

Refer to the evaluation of an arithmetic expression for possible errors
\RefSP{Evaluation-of-an-arithmetic-expression}.

\Portability

ISO predicates.

\subsection{Dynamic clause management}

\subsubsection{Introduction}
\label{Introduction:(Dynamic-clause-management)}
\SPart{Static and dynamic procedures}: a procedure is either dynamic or
static. All built-in predicates are static. A user-defined procedure is
static by default unless a \IdxDi{dynamic/1} directive precedes its
definition \RefSP{dynamic/1}. Adding a clause to a non-existent procedure
creates a dynamic procedure. The clauses of a dynamic procedure can be
altered (e.g. using \texttt{asserta/1}), the clauses of a static procedure
cannot be altered. 

\SPart{Private and public procedures}: each procedure is either public or
private. A dynamic procedure is always public. Each built-in predicate is
private, and a static user-defined procedure is private by default unless a
\IdxDi{public/1} directive precedes its definition \RefSP{public/1}. If a
dynamic declaration exists it is unnecessary to add a public declaration
since a dynamic procedure is also public. A clause of a public procedure can
be inspected (e.g. using \texttt{clause/2}), a clause of a private procedure
cannot be inspected.

\SPart{A logical database update view}: any change in the database that
occurs as the result of executing a goal (e.g. when a sub-goal is a call of
\texttt{assertz/1} or \texttt{retract/1}) only affects subsequent
activations. The change does not affect any activation that is currently
being executed. Thus the database is frozen during the execution of a goal,
and the list of clauses defining a predication is fixed at the moment of its
execution.

\subsubsection{\texttt{asserta/1},
\texttt{assertz/1}}

\begin{TemplatesOneCol}
asserta(+clause)\\
assertz(+clause)

\end{TemplatesOneCol}

\Description

\IdxPBD[asserta/1]{asserta(Clause)} first converts the term \texttt{Clause} to a clause
and then adds it to the current internal database. The predicate concerned
must be dynamic \RefSP{Introduction:(Dynamic-clause-management)} or
undefined and the clause is inserted before the first clause of the
predicate. If the predicated is undefined it is created as a dynamic
procedure.

\IdxPBD[assertz/1]{assertz(Clause)} acts like \texttt{asserta/1} except that the clause
is added at the end of all existing clauses of the concerned predicate.

\SPart{Converting a term \texttt{Clause} to a clause \texttt{Clause1}:} 

\begin{itemize}

\item extract the head and the body of \texttt{Clause}: either
\texttt{Clause} = \texttt{(Head :- Body)} or \texttt{Clause} = \texttt{Head}
and \texttt{Body} = \texttt{true}.

\item \texttt{Head} must be a callable term (or else the conversion fails).

\item convert \texttt{Body} to a body clause (i.e. a goal) \texttt{Body1}.

\item the converted clause \texttt{Clause1} = \texttt{(Head :- Body1)}.

\end{itemize}

\SPart{Converting a term \texttt{T} to a goal:}

\begin{itemize}

\item if \texttt{T} is a variable it is replaced by the term
\texttt{call(T)}.

\item if \texttt{T} is a control construct \texttt{(',')/2}, \texttt{(;)/2}
or \texttt{(-{\gt})/2} each argument of the control construct is recursively
converted to a goal.

\item if \texttt{T} is a callable term it remains unchanged.

\item otherwise the conversion fails (\texttt{T} is neither a variable nor a
callable term).

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Head} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Head} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Head)}

\ErrCond{\texttt{Body} cannot be converted to a goal}
\ErrTerm{type\_error(callable, Body)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Head} is that of a
static procedure}
\ErrTerm{permission\_error(modify, static\_procedure, Pred)}

\end{PlErrors}

\Portability

ISO predicates.

\subsubsection{\texttt{retract/1}}

\begin{TemplatesOneCol}
retract(+clause)

\end{TemplatesOneCol}

\Description

\IdxPBD[retract/1]{retract(Clause)} erases the first clause of the database
that unifies with \texttt{Clause}. The concerned predicate must be a
dynamic procedure
\RefSP{Introduction:(Dynamic-clause-management)}. Removing all clauses
of a procedure does not erase the procedure definition. To achieve
this use \texttt{abolish/1} \RefSP{abolish/1}. \texttt{retract/1} is
re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Head} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Head} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Head)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Head} is that of a
static procedure}
\ErrTerm{permission\_error(modify, static\_procedure, Pred)}

\end{PlErrors}

\Portability

ISO predicate. In the ISO reference, the operation associated to the
\texttt{permission\_error} is \texttt{access} while it is \texttt{modify} in
GNU Prolog. This seems to be an error of the ISO reference since for
\texttt{asserta/1} (which is similar in spirit to \texttt{retract/1}) the
operation is also \texttt{modify}.

\subsubsection{\texttt{retractall/1}}

\begin{TemplatesOneCol}
retractall(+head)

\end{TemplatesOneCol}

\Description

\IdxPBD[retractall/1]{retractall(Head)} erases all clauses whose head unifies with
\texttt{Head}. The concerned predicate must be a dynamic procedure
\RefSP{Introduction:(Dynamic-clause-management)}. The procedure definition
is not removed so that it is found by \IdxPB{current\_predicate/1}
\RefSP{current-predicate/1}. \texttt{abolish/1} should be used to remove the
procedure \RefSP{abolish/1}.

\begin{PlErrors}

\ErrCond{\texttt{Head} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Head} is not a callable term}
\ErrTerm{type\_error(callable, Head)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Head} is that of a
static procedure}
\ErrTerm{permission\_error(modify, static\_procedure, Pred)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{clause/2}}

\begin{TemplatesOneCol}
clause(+head, ?callable\_term)

\end{TemplatesOneCol}

\Description

\IdxPBD[clause/2]{clause(Head, Body)} succeeds if there exists a clause in the
database that unifies with \texttt{Head :- Body}. The predicate in question
must be a public procedure \RefSP{Introduction:(Dynamic-clause-management)}. Clauses are delivered from the first to the last. This
predicate is re-executable on backtracking. 

\begin{PlErrors}

\ErrCond{\texttt{Head} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Head} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Head)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Head} is that of a
private procedure}
\ErrTerm{permission\_error(access, private\_procedure, Pred)}

\ErrCond{\texttt{Body} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Body)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{abolish/1}}
\label{abolish/1}

\begin{TemplatesOneCol}
abolish(+predicate\_indicator)

\end{TemplatesOneCol}

\Description

\IdxPBD[abolish/1]{abolish(Pred)} removes from the database the procedure whose
predicate indicator is \texttt{Pred}. The concerned predicate must be a
dynamic procedure \RefSP{Introduction:(Dynamic-clause-management)}.

\begin{PlErrors}

\ErrCond{\texttt{Pred} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and either
\texttt{Name} or \texttt{Arity} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Pred} is neither a variable nor a predicate indicator}
\ErrTerm{type\_error(predicate\_indicator, Pred)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
neither a variable nor an integer}
\ErrTerm{type\_error(integer, Arity)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Name} is
neither a variable nor an atom}
\ErrTerm{type\_error(atom, Name)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Arity)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
an integer $>$ \texttt{max\_arity} flag \RefSP{set-prolog-flag/2}}
\ErrTerm{representation\_error(max\_arity)}

\ErrCond{The predicate indicator \texttt{Pred} is that of a static
procedure}
\ErrTerm{permission\_error(modify, static\_procedure, Pred)}

\end{PlErrors}

\Portability

ISO predicate.

\subsection{Predicate information}

\subsubsection{\texttt{current\_predicate/1}}
\label{current-predicate/1}

\begin{TemplatesOneCol}
current\_predicate(?predicate\_indicator)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_predicate/1]{current\_predicate(Pred)} succeeds if there
exists a predicate indicator of a defined procedure that unifies with
\texttt{Pred}. All user defined procedures are found, whether static or
dynamic. Internal system procedures whose name begins
with \texttt{'\$'} are not found. A user-defined procedure is found
even when it has no clauses. A user-defined procedure is not found if
it has been abolished. To conform to the ISO reference, built-in predicates
are not found except if the \IdxPF{strict\_iso} \Idx{Prolog flag} is switched off \RefSP{set-prolog-flag/2}. This predicate is re-executable on
backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Pred} is neither a variable nor a predicate indicator}
\ErrTerm{type\_error(predicate\_indicator, Pred)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
neither a variable nor an integer}
\ErrTerm{type\_error(integer, Arity)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Name} is
neither a variable nor an atom}
\ErrTerm{type\_error(atom, Name)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Arity)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
an integer $>$ \texttt{max\_arity} flag \RefSP{set-prolog-flag/2}}
\ErrTerm{representation\_error(max\_arity)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{predicate\_property/2}}
\label{predicate-property/2}

\begin{TemplatesOneCol}
predicate\_property(?predicate\_indicator, ?predicate\_property)

\end{TemplatesOneCol}

\Description

\IdxPBD[predicate\_property/2]{predicate\_property(Pred, Property)} succeeds if
\texttt{current\_predicate(Pred)} succeeds \RefSP{current-predicate/1} and
if \texttt{Property} unifies with one of the properties of the procedure.
This predicate is re-executable on backtracking.

\SPart{Predicate properties}:

\begin{itemize}

\item \IdxPPD{static}: if the procedure is static.

\item \IdxPPD{dynamic}: if the procedure is dynamic.

\item \IdxPPD{private}: if the procedure is private.

\item \IdxPPD{public}: if the procedure is public.

\item \IdxPPD{user}: if the procedure is a user-defined procedure.

\item \IdxPPD{built\_in}: if the procedure is a Prolog built-in predicate.

\item \IdxPPD{built\_in\_fd}: if the procedure is an FD built-in predicate.

\item \IdxPPD{native\_code}: if the procedure is compiled in native code.

\item \IdxPPD[prolog\_file]{prolog\_file(File)}: source file from which the
predicate has been read.

\item \IdxPPD[prolog\_line]{prolog\_line(Line)}: line number of the source
file.

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Pred} is neither a variable nor a predicate indicator}
\ErrTerm{type\_error(predicate\_indicator, Pred)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
neither a variable nor an integer}
\ErrTerm{type\_error(integer, Arity)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Name} is
neither a variable nor an atom}
\ErrTerm{type\_error(atom, Name)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Arity)}

\ErrCond{\texttt{Pred} is a term \texttt{Name/Arity} and \texttt{Arity} is
an integer $>$ \texttt{max\_arity} flag \RefSP{set-prolog-flag/2}}
\ErrTerm{representation\_error(max\_arity)}

\ErrCond{\texttt{Property} is neither a variable nor a predicate property
term}
\ErrTerm{domain\_error(predicate\_property, Property)}

\ErrCond{\texttt{Property} = \texttt{prolog\_file(File)} and \texttt{File}
is neither a variable nor an atom}
\ErrTerm{type\_error(atom, File)}

\ErrCond{\texttt{Property} = \texttt{prolog\_line(Line)} and \texttt{Line}
is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Line)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{All solutions}

\subsubsection{Introduction}
\label{Introduction:(All-solutions)}
It is sometimes useful to collect all solutions for a goal. This can be done
by repeatedly backtracking and gradually building the list of solutions. The
following built-in predicates are provided to automate this process. 

The built-in predicates described in this section invoke \texttt{call/1}
\RefSP{call/1} on the argument \texttt{Goal}. When efficiency is crucial
and \texttt{Goal} is complex it is better to define an auxiliary predicate
which can then be compiled, and have \texttt{Goal} call this predicate.

\subsubsection{\texttt{findall/3}}

\begin{TemplatesOneCol}
findall(?term, +callable\_term, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[findall/3]{findall(Template, Goal, Instances)} succeeds if \texttt{Instances}
unifies with the list of values to which a variable \texttt{X} not occurring
in \texttt{Template} or \texttt{Goal} would be instantiated by successive
re-executions of \texttt{call(Goal), X = Template} after systematic
replacement of all variables in \texttt{X} by new variables. Thus, the order
of the list \texttt{Instances} corresponds to the order in which the proofs
are found.

\begin{PlErrors}

\ErrCond{\texttt{Goal} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Goal} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Goal)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Goal} does not
correspond to an existing procedure and the value of the \texttt{unknown}
Prolog flag is \texttt{error} \RefSP{set-prolog-flag/2}}
\ErrTerm{existence\_error(procedure, Pred)}

\ErrCond{\texttt{Instances} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Instances)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{bagof/3},
\texttt{setof/3}}

\begin{TemplatesOneCol}
bagof(?term, +callable\_term, ?list)\\
setof(?term, +callable\_term, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[bagof/3]{bagof(Template, Goal, Instances)} assembles as a list the
set of solutions of \texttt{Goal} for each different instantiation of the
free variables in \texttt{Goal}. The elements of each list are in order of
solution, but the order in which each list is found is undefined.
This predicate is re-executable on backtracking.

\SPart{Free variable set}: \texttt{bagof/3} groups the solutions of
\texttt{Goal} according to the free variables in \texttt{Goal}. This set
corresponds to all variables occurring in \texttt{Goal} but not in
\texttt{Template}. It is sometimes useful to exclude some additional
variables of \texttt{Goal}. For that, \texttt{bagof/3} recognizes a goal of
the form \texttt{T\^{}Goal} and exclude all variables occuring in \texttt{T}
from the free variable set. \texttt{(\^{})/2} can be viewed as an
\emph{existential quantifier} (the logical reading of \texttt{X\^{}Goal}
being ``there exists an \texttt{X} such that \texttt{Goal} is true''). The
use of this existential qualifier is superfluous outside \texttt{bagof/3}
(and \texttt{setof/3}) and then is not recognized.

\texttt{(\^{})/2} is a predefined infix operator \RefSP{op/3:(Term-input/output)}.

\IdxPBD[setof/3]{setof(Template, Goal, Instances)} is equivalent to
\texttt{bagof(Template,Goal,I), sort(I,Instances)}. Each list is then a
sorted list (duplicate elements are removed).

From the implementation point of view \texttt{setof/3} is as fast as
\texttt{bagof/3}. Both predicates use an in-place (i.e. destructive) sort
\RefSP{sort/2} and require the same amount of memory.

\begin{PlErrors}

\ErrCond{\texttt{Goal} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Goal} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Goal)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Goal} does not
correspond to an existing procedure and the value of the \texttt{unknown}
Prolog flag is \texttt{error} \RefSP{set-prolog-flag/2}}
\ErrTerm{existence\_error(procedure, Pred)}

\ErrCond{\texttt{Instances} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Instances)}

\end{PlErrors}

\Portability

ISO predicates.

\subsection{Streams}
\label{Streams}

\subsubsection{Introduction}
\label{Introduction:(Streams)}
A stream provides a logical view of a source/sink.

\SPart{Sources and sinks}: a program can output results to a sink or input
data from a source. A source/sink may be a file (regular file, terminal,
device,\ldots), a constant term, a pipe, a socket,\ldots 

\SPart{Associating a stream to a source/sink}: to manipulate a source/sink
it must be associated to a stream. This provides a logical and uniform view
of the source/sink whatever its type. Once this association has been
established, i.e. a stream has been created, all subsequent references to
the source/sink are made by referring the stream. A stream is
unidirectional: it is either an input stream or an output stream. For a
classical file, the association is done by opening the file (whose name is
specified as an atom) with the \IdxPB{open/4} \RefSP{open/4}. GNU Prolog
makes it possible to treat a Prolog constant term as a source/sink and
provides built-in predicates to associate a stream to such a term
\RefSP{Constant-term-streams}. GNU Prolog provides operating system interface
predicates defining pipes between GNU Prolog and child processes with streams
associated to these pipes, e.g. \IdxPB{popen/3} \RefSP{popen/3}.
Similarly, socket interface predicates associate streams to a socket to
allow the communication, e.g. \IdxPB{socket\_connect/4}
\RefSP{socket-connect/4}.

\SPart{Stream-term}: a stream-term identifies a stream during a call of an
input/output built-in predicate. It is created as a result of associating a
stream to a source/sink (section above). A stream-term is a compound term of
the form \texttt{'\$stream'(I)} where \texttt{I} is an integer.

\SPart{Stream aliases}: any stream may be associated with a stream alias
which is an atom which may be used to refer to that stream. The association
automatically ends when the stream is closed. A particular alias only refers
to at most one stream at any one time. However, more than one alias can be
associated to a stream. All built-in predicates which have a stream-term as
an input argument also accept a stream alias as that argument. However,
built-in predicates which return a stream-term do not accept a stream alias.

\SPart{Standard streams}: two streams are predefined and open during the
execution of every goal: the standard input stream which has the alias
\IdxPKD{user\_input} and the standard output stream which has the alias
\IdxPKD{user\_output}. A goal which attempts to close either standard stream
succeeds, but does not close the stream.

\SPart{Current streams}: during execution there is a current input stream
and a current output stream. By default, the current input and output
streams are the standard input and output streams, but the built-in
predicates \IdxPB{set\_input/1} \RefSP{set-input/1} and
\IdxPB{set\_output/1} \RefSP{set-output/1} can be used to change them.
When the current input stream is closed, the standard input stream becomes
the current input stream. When the current output stream is closed, the
standard output stream becomes the current output stream. 

\SPart{Text streams and binary streams}: a text stream is a sequence of
characters. A text stream is also regarded as a sequence of lines where each
line is a possibly empty sequence of characters followed by a new line
character. GNU Prolog may add or remove space characters at the ends of lines
in order to conform to the conventions for representing text streams in the
operating system. A binary stream is a sequence of bytes. Only a few
built-in predicates can deal with binary streams, e.g.
\IdxPB{get\_byte/2} \RefSP{Byte-input/output}.

\SPart{Stream positions}: the stream position of a stream identifies an
absolute position of the source/sink to which the stream is connected and
defines where in the source/sink the next input or output will take place. A
stream position is a ground term of the form
\texttt{'\$stream\_position'(I1, I2, I3, I4)} where \texttt{I1},
\texttt{I2}, \texttt{I3} and \texttt{I4} are integers. Stream positions are
use to reposition a stream (when possible) using for instance
\IdxPB{set\_stream\_position/2} \RefSP{set-stream-position/2}.

\SPart{The position end of stream}: when all data of a stream
\Param{S} has been input \Param{S} has a stream position
end-of-stream. At this stream position a goal to input more data will return
a specific value to indicate that end of stream has been reached (e.g.
\texttt{-1} for \texttt{get\_code/2} or \texttt{end\_of\_file} for
\texttt{get\_char/2},\ldots). When this terminating value has been input, the
stream has a stream position past-end-of-stream.

\SPart{Buffering mode}: input/output on a stream can be buffered
(line-buffered or block-buffered) or not buffered at all. The buffering mode
can be specified at open time or using \IdxPB{set\_stream\_buffering/2}
\RefSP{set-stream-buffering/2}. Line buffering is used on output streams,
output data are only written to the sink when a new-line character is output
(or at the close time). Block buffering is used on input or output. On input
streams, when an input is requested on the source, if the buffer is empty,
all available characters are read (within the limits of the size of the
buffer), subsequent reads will first use the characters in the buffer. On
output streams, output data are stored in the buffer and only when the
buffer is full is it physically written on the sink. Thus, an output to a
buffered stream may not be sent immediately to the sink connected to that
stream. When it is necessary to be certain that output has been delivered,
the built-in predicate \IdxPB{flush\_output/1} \RefSP{flush-output/1}
should be used. Finally, it is also possible to use non-buffered streams, in
that case input/output are directly done on the connected source/sink. This
can be useful for communication purposes (e.g. sockets) or when a precise
control is needed, e.g. \IdxPB{select/5} \RefSP{wait/2}.

\subsubsection{\texttt{current\_input/1}}

\begin{TemplatesOneCol}
current\_input(?stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_input/1]{current\_input(Stream)} unifies \texttt{Stream} with the stream-term
identifying the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is neither a variable nor a stream}
\ErrTerm{domain\_error(stream, Stream)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{current\_output/1}}

\begin{TemplatesOneCol}
current\_output(?stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_output/1]{current\_output(Stream)} unifies \texttt{Stream} with the
stream-term identifying the current output stream.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is neither a variable nor a stream}
\ErrTerm{domain\_error(stream, Stream)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{set\_input/1}}
\label{set-input/1}

\begin{TemplatesOneCol}
set\_input(+stream\_or\_alias)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_input/1]{set\_input(SorA)} sets the current input stream to be the stream
associated with the stream-term or alias \texttt{SorA}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{set\_output/1}}
\label{set-output/1}

\begin{TemplatesOneCol}
set\_output(+stream\_or\_alias)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_output/1]{set\_output(SorA)} sets the current output stream to be the stream
associated with the stream-term or alias \texttt{SorA}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{open/4},
\texttt{open/3}}
\label{open/4}

\begin{TemplatesOneCol}
open(+source\_sink, +io\_mode, -stream, +stream\_option\_list)\\
open(+source\_sink, +io\_mode, -stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[open/4]{open(SourceSink, Mode, Stream, Options)} opens the source/sink
\texttt{SourceSink} for input or output as indicated by \texttt{Mode} and
the list of stream-options \texttt{Options} and unifies \texttt{Stream} with
the stream-term which is associated to this stream. See
\IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{SourceSink} \RefSP{absolute-file-name/2}.

\SPart{Input/output modes}: \texttt{Mode} is an atom which defines the
input/output operations that may be performed the stream. Possible modes
are:

\begin{itemize}

\item \IdxPMD{read}: the source/sink is a source and must already exist.
Input starts at the beginning of the source. 

\item \IdxPMD{write}: the source/sink is a sink. If the sink already exists
then it is emptied else an empty sink is created. Output starts at the
beginning of that sink.

\item \IdxPMD{append}: the source/sink is a sink. If the sink does not exist
it is created. Output starts at the end of that sink.

\end{itemize}

\SPart{Stream options}: \texttt{Options} is a list of stream options. If
this list contains contradictory options, the rightmost option is the one
which applies. Possible options are:

\begin{itemize}

\item \IdxPOD[type]{type(text}/\texttt{binary)}: specifies whether the
stream is a text stream or a binary stream. The default value is
\texttt{text}.

\item \IdxPOD[reposition]{reposition(true}/\texttt{false)}: specifies
whether it is possible to reposition the stream. The default value is
\texttt{true} except if the stream cannot be repositioned (e.g. a terminal).

\item \IdxPOD[eof\_action]
{eof\_action(error}/\texttt{eof\_code}/\texttt{reset)}:
specifies the effect of attempting to input from a stream whose stream
position is past-end-of-stream:

\begin{itemize}

\item \IdxPOD{error}: a \texttt{permission\_error} is raised signifying that
no more input exists in this stream.

\item \IdxPOD{eof\_code}: the result of input is as if the stream position
is end-of-stream.

\item \IdxPOD{reset}: the stream position is reset so that it is not
past-end-of-stream, and another attempt is made to input from it (this is
useful when inputting from a terminal).

\end{itemize}

The default value is \texttt{eof\_code}.

\item \IdxPOD[alias]{alias(Alias)}: specifies that the atom \texttt{Alias}
is to be an alias for the stream. By default no alias is attached to the
stream.

\item \IdxPOD[buffering]{buffering(none}/\texttt{line}/\texttt{block)}:
specifies which type of buffering is used by input/output operations on
this stream:

\begin{itemize}

\item \IdxPOD{none}: no buffering.

\item \IdxPOD{line}: output operations buffer data emitted until a new-line
occurs

\item \IdxPOD{block}: input/output operations buffer data until a given
number (implementation dependant) of characters/bytes have been treated.

\end{itemize}

The default value is \texttt{line} for a terminal (TTY), \texttt{block}
otherwise.

\end{itemize}

\IdxPBD[open/3]{open(SourceSink, Mode, Stream, Options)} is equivalent to
\texttt{open(SourceSink, Mode, Stream, [])}.

\begin{PlErrors}

\ErrCond{\texttt{SourceSink} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Mode} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Mode} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Mode)}

\ErrCond{\texttt{Options} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Options)}

\ErrCond{\texttt{Stream} is not a variable}
\ErrTerm{type\_error(variable, Stream)}

\ErrCond{\texttt{SourceSink} is neither a variable nor a source/sink}
\ErrTerm{domain\_error(source\_sink, SourceSink)}

\ErrCond{\texttt{Mode} is an atom but not an input/output mode}
\ErrTerm{domain\_error(io\_mode, Mode)}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is neither a
variable nor a stream-option}
\ErrTerm{domain\_error(stream\_option, E)}

\ErrCond{the source/sink specified by \texttt{SourceSink} does not exist}
\ErrTerm{existence\_error(source\_sink, SourceSink)}

\ErrCond{the source/sink specified by \texttt{SourceSink} cannot be opened}
\ErrTerm{permission\_error(open, source\_sink, SourceSink)}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is
\texttt{alias(A)} and \texttt{A} is already associated with an open stream} 
\ErrTerm{permission\_error(open, source\_sink, alias(A))}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is
\texttt{reposition(true}) and it is not possible to reposition this stream} 
\ErrTerm{permission\_error(open, source\_sink, reposition(true))}

\end{PlErrors}

\Portability

ISO predicates. The \texttt{buffering/1} stream option is a GNU Prolog
extension.

\subsubsection{\texttt{close/2},
\texttt{close/1}}
\label{close/2}

\begin{TemplatesOneCol}
close(+stream\_or\_alias, +close\_option\_list)\\
close(+stream\_or\_alias)

\end{TemplatesOneCol}

\Description

\IdxPBD[close/2]{close(SorA, Options)} closes the stream associated with the stream-term
or alias \texttt{SorA}. If \texttt{SorA} is the standard input stream or the
standard output stream \texttt{close/2} simply succeeds else the associated
source/sink is physically closed. If \texttt{SorA} is the current input
stream the current input stream becomes the standard input stream
\IdxPK{user\_input}. If \texttt{SorA} is the current output stream the
current output stream becomes the standard output stream
\IdxPK{user\_output}.

\SPart{Close options}: \texttt{Options} is a list of close options. For the
moment only one option is available:

\begin{itemize}

\item \IdxPOD[force]{force(true}/\texttt{false)}: with \texttt{false}, if
an error occurs when trying to close the source/sink, the stream is not
closed and an error (\texttt{system\_error} or \texttt{resource\_error}) is
raised (but \texttt{close/2} succeeds). With \texttt{true}, if an error
occurs it is ignored and the stream is closed. The purpose of
\texttt{force/1} option is to allow an error handling routine to do its best
to reclaim resources. The default value is \texttt{false}.

\end{itemize}

\IdxPBD[close/1]{close(SorA)} is equivalent to \texttt{close(SorA, [])}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Options)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is neither a
variable nor a close-option} 
\ErrTerm{domain\_error(close\_option, E)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} needs a special close \RefSP{Constant-term-streams}}
\ErrTerm{system\_error(needs\_special\_close)}

\end{PlErrors}

\Portability

ISO predicates. The \texttt{system\_error(needs\_special\_close)} is a
GNU Prolog extension.

\subsubsection{\texttt{flush\_output/1},
\texttt{flush\_output/0}}
\label{flush-output/1}

\begin{TemplatesOneCol}
flush\_output(+stream\_or\_alias)\\
flush\_output

\end{TemplatesOneCol}

\Description

\IdxPBD[flush\_output/1]{flush\_output(SorA)} sends any buffered output characters/bytes to
the stream.

\IdxPBD[flush\_output/0]{flush\_output/0} applies to the current output stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\end{PlErrors}

\Portability

ISO predicates.

\subsubsection{\texttt{current\_stream/1}}
\label{current-stream/1}

\begin{TemplatesOneCol}
current\_stream(?stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_stream/1]{current\_stream(Stream)} succeeds if there exists
a stream-term that unifies with \texttt{Stream}. This predicate is
re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is neither a variable nor a stream-term}
\ErrTerm{domain\_error(stream, Stream)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{stream\_property/2}}
\label{stream-property/2}


\begin{TemplatesOneCol}
stream\_property(?stream, ?stream\_property)

\end{TemplatesOneCol}

\Description

\IdxPBD[stream\_property/2]{stream\_property(Stream, Property)} succeeds if
\texttt{current\_stream(Stream)} succeeds \RefSP{current-stream/1} and if
\texttt{Property} unifies with one of the properties of the stream. This
predicate is re-executable on backtracking.

\SPart{Stream properties}:

\begin{itemize}

\item \IdxPPD[file\_name]{file\_name(F)}: the name of the connected 
source/sink.

\item \IdxPPD[mode]{mode(M)}: \texttt{M} is the open mode (\texttt{read},
\texttt{write}, \texttt{append}).

\item \IdxPPD{input}: if it is an input stream.

\item \IdxPPD{output}: if it is an output stream.

\item \IdxPPD[alias]{alias(A)}: \texttt{A} is an alias of the stream.

\item \IdxPPD[type]{type(T)}: \texttt{T} is the type of the stream
(\texttt{text}, \texttt{binary}).

\item \IdxPPD[reposition]{reposition(R)}: \texttt{R} is the reposition
boolean (\texttt{true}, \texttt{false}).

\item \IdxPPD[eof\_action]{eof\_action(A)}: \texttt{A} is the end-of-file
action (\texttt{error}, \texttt{eof\_code}, \texttt{reset}).

\item \IdxPPD[buffering]{buffering(B)}: \texttt{B} is the buffering mode
(\texttt{none}, \texttt{line}, \texttt{block}).

\item \IdxPPD[end\_of\_stream]{end\_of\_stream(E)}: \texttt{E} is the
current end-of-stream status (\texttt{not}, \texttt{at}, \texttt{past}). If
the stream position is end-of-stream then \texttt{E} is unified with
\texttt{at} else if the stream position is past-end-of-stream then \texttt{E}
is unified with \texttt{past} else \texttt{E} is unified with \texttt{not}.

\item \IdxPPD[position]{position(P)}: \texttt{P} is the stream-position
term associated to the current position.

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Stream} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Stream} is neither a variable nor a stream-term}
\ErrTerm{domain\_error(stream, Stream)}

\ErrCond{\texttt{Property} is neither a variable nor a stream property}
\ErrTerm{domain\_error(stream\_property, Property)}

\ErrCond{\texttt{Property} = \texttt{file\_name(E)},\texttt{ mode(E)},
\texttt{alias(E)}, \texttt{end\_of\_stream(E)}, \texttt{eof\_action(E)},
\texttt{reposition(E)}, \texttt{type(E)} or \texttt{buffering(E)} and
\texttt{E} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\end{PlErrors}

\Portability

ISO predicate. The \texttt{buffering/1} property is a GNU Prolog extension.

\subsubsection{\texttt{at\_end\_of\_stream/1},
\texttt{at\_end\_of\_stream/0}}


\begin{TemplatesOneCol}
at\_end\_of\_stream(+stream\_or\_alias)\\
at\_end\_of\_stream

\end{TemplatesOneCol}

\Description

\IdxPBD[at\_end\_of\_stream/1]{at\_end\_of\_stream(SorA)} succeeds if the stream associated with
stream-term or alias \texttt{SorA} has a stream position end-of-stream or
past-end-of-stream. This predicate can be defined using
\IdxPB{stream\_property/2} \RefSP{stream-property/2}.

\IdxPBD[at\_end\_of\_stream/0]{at\_end\_of\_stream/0} applies to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\end{PlErrors}

\Portability

ISO predicates. The \texttt{permission\_error(input, stream, SorA)} is a
GNU Prolog extension.

\subsubsection{\texttt{stream\_position/2}}
\label{stream-position/2}

\begin{TemplatesOneCol}
stream\_position(+stream\_or\_alias, ?stream\_position)

\end{TemplatesOneCol}

\Description

\IdxPBD[stream\_position/2]{stream\_position(SorA, Position)} succeeds unifying
\texttt{Position} with the stream-position term associated to the current
position of the stream-term or alias \texttt{SorA}. This predicate can be
defined using \IdxPB{stream\_property/2} \RefSP{stream-property/2}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{Position} is neither a variable nor a stream-position term}
\ErrTerm{domain\_error(stream\_position, Position)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{set\_stream\_position/2}}
\label{set-stream-position/2}

\begin{TemplatesOneCol}
set\_stream\_position(+stream\_or\_alias, +stream\_position)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_stream\_position/2]{set\_stream\_position(SorA, Position)} sets the position of
the stream associated with the stream-term or alias \texttt{SorA} to
\texttt{Position}. \texttt{Position} should have previously been returned by
\IdxPB{stream\_property/2} \RefSP{stream-property/2} or by
\IdxPB{stream\_position/2} \RefSP{stream-position/2}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Position} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{Position} is neither a variable nor a stream-position term}
\ErrTerm{domain\_error(stream\_position, Position)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} has stream property \texttt{reposition(false)}}
\ErrTerm{permission\_error(reposition, stream, SorA)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{seek/4}}

\begin{TemplatesOneCol}
seek(+stream\_or\_alias, +stream\_seek\_method, +integer, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[seek/4]{seek(SorA, Whence, Offset, NewOffset)} sets the position of
the stream associated with the stream-term or alias \texttt{SorA} to
\texttt{Offset} according to \texttt{Whence} and unifies \texttt{NewOffset}
with the new offset from the beginning of the file. \texttt{seek/4} can only
be used on binary streams. \texttt{Whence} is an atom from:

\begin{itemize}

\item \IdxPWD{bof}: the position is set relatively to the begin of the file
(\texttt{Offset} should be $\geq$ 0).

\item \IdxPWD{current}: the position is set relatively to the current
position (\texttt{Offset} can be $\geq$ 0 or $\leq$ 0).

\item \IdxPWD{eof}: the position is set relatively to the end of the file
(\texttt{Offset} should be $\leq$ 0).

\end{itemize}

This predicate is an interface to the C Unix function \texttt{lseek(2)}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Whence} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Offset} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{Whence} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Whence)}

\ErrCond{\texttt{Whence} is an atom but not a valid stream seek method}
\ErrTerm{domain\_error(stream\_seek\_method, Whence)}

\ErrCond{\texttt{Offset} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Offset)}

\ErrCond{\texttt{NewOffset} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, NewOffset)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} has stream property \texttt{reposition(false)}}
\ErrTerm{permission\_error(reposition, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a text stream}
\ErrTerm{permission\_error(reposition, text\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{character\_count/2}}

\begin{TemplatesOneCol}
character\_count(+stream\_or\_alias, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[character\_count/2]{character\_count(SorA, Count)} unifies \texttt{Count} with the
number of characters/bytes read/written on the stream associated with
stream-term or alias \texttt{SorA}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Count} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Count)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{line\_count/2}}
\label{line-count/2}

\begin{TemplatesOneCol}
line\_count(+stream\_or\_alias, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[line\_count/2]{line\_count(SorA, Count)} unifies \texttt{Count} with the number of
lines read/written on the stream associated with the stream-term or alias
\texttt{SorA}. This predicate can only be used on text streams.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Count} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Count)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(access, binary\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{line\_position/2}}
\label{line-position/2}

\begin{TemplatesOneCol}
line\_position(+stream\_or\_alias, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[line\_position/2]{line\_position(SorA, Count)} unifies
\texttt{Count} with the number of characters read/written on the current
line of the stream associated with the stream-term or alias
\texttt{SorA}. This predicate can only be used on text streams.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Count} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Count)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(access, binary\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{stream\_line\_column/3}}

\begin{TemplatesOneCol}
stream\_line\_column(+stream\_or\_alias, ?integer, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[stream\_line\_column/3]{stream\_line\_column(SorA, Line, Column)} unifies \texttt{Line}
(resp. \texttt{Column}) with the current line number (resp. column number)
of the stream associated with the stream-term or alias \texttt{SorA}. This
predicate can only be used on text streams. Note that \texttt{Line}
corresponds to the value returned by \IdxPB{line\_count/2} + 1
\RefSP{line-count/2} and \texttt{Column} to the value returned
by \texttt{line\_position/2} + 1 \RefSP{line-position/2}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Line} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Line)}

\ErrCond{\texttt{Column} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Column)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(access, binary\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{set\_stream\_line\_column/3}}

\begin{TemplatesOneCol}
set\_stream\_line\_column(+stream\_or\_alias, +integer, +integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_stream\_line\_column/3]{set\_stream\_line\_column(SorA, Line, Column)} sets the stream
position of the stream associated with the stream-term or alias \texttt{SorA}
according to the line number \texttt{Line} and the column number
\texttt{Column}. This predicate can only be used on text streams. It first
repositions the stream to the beginning of the file and then reads character
by character until the required position is reached.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Line} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Column} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Line} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Line)}

\ErrCond{\texttt{Column} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Column)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(reposition, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream property \texttt{reposition(false)}}
\ErrTerm{permission\_error(reposition, stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{add\_stream\_alias/2}}

\begin{TemplatesOneCol}
add\_stream\_alias(+stream\_or\_alias, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[add\_stream\_alias/2]{add\_stream\_alias(SorA, Alias)} adds \texttt{Alias} as a new alias
to the stream associated with the stream-term or alias \texttt{SorA}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Alias} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Alias} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Alias)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{Alias} is already associated with an open stream} 
\ErrTerm{permission\_error(add\_alias, source\_sink, alias(Alias))}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{current\_alias/2}}

\begin{TemplatesOneCol}
current\_alias(?stream, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_alias/2]{current\_alias(Stream, Alias)} succeeds if
\texttt{current\_stream(Stream)} succeeds \RefSP{current-stream/1} and if
\texttt{Alias} unifies with one of the aliases of the stream. It can be
defined using \IdxPB{stream\_property/2} \RefSP{stream-property/2}. This
predicate is re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is neither a variable nor a stream-term}
\ErrTerm{domain\_error(stream, Stream)}

\ErrCond{\texttt{Alias} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Alias)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{set\_stream\_type/2}}
\label{set-stream-type/2}

\begin{TemplatesOneCol}
set\_stream\_type(+stream\_or\_alias, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_stream\_type/2]{set\_stream\_type(SorA, Type)} updates the type associated with
stream-term or alias \texttt{SorA}. The value of \texttt{Type} is an atom in
\IdxPO{text} or \IdxPO{binary} as for \IdxPB{open/4} \RefSP{open/4}.
The type of a stream can only be changed before any input/output operation
is executed.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Type} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Type} is neither a variable nor a valid type}
\ErrTerm{domain\_error(stream\_type, Type)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{An I/O operation has already been executed on \texttt{SorA}}
\ErrTerm{permission\_error(modify, stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{set\_stream\_eof\_action/2}}

\begin{TemplatesOneCol}
set\_stream\_eof\_action(+stream\_or\_alias, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_stream\_eof\_action/2]{set\_stream\_eof\_action(SorA, Action)}
updates the \texttt{eof\_action} option associated with the stream-term or
alias \texttt{SorA}. The value of \texttt{Action} is one of the atoms
\IdxPO{error}, \IdxPO{eof\_code}, \IdxPO{reset} as for \IdxPB{open/4} \RefSP{open/4}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Action} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Action} is neither a variable nor a valid eof action}
\ErrTerm{domain\_error(eof\_action, Action)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(modify, stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{set\_stream\_buffering/2}}
\label{set-stream-buffering/2}

\begin{TemplatesOneCol}
set\_stream\_buffering(+stream\_or\_alias, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_stream\_buffering/2]{set\_stream\_buffering(SorA, Buffering)}
updates the buffering mode associated with the stream-term or alias
\texttt{SorA}. The value of \texttt{Buffering} is one of the atoms
\IdxPO{none}, \IdxPO{line} or \IdxPO{block} as for \IdxPB{open/4}
\RefSP{open/4}.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Buffering} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Buffering} is neither a variable nor a valid buffering
mode}
\ErrTerm{domain\_error(buffering\_mode, Buffering)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Constant term streams}
\label{Constant-term-streams}

\subsubsection{Introduction}
\label{Introduction:(Constant-term-streams)}
Constant term streams allow the user to consider a constant term (atom,
character list or character code list) as a source/sink by associating to
them a stream. Reading from a constant term stream will deliver the
characters of the constant term as if they had been read from a standard
file. Characters written on a constant term stream are stored to form the
final constant term when the stream is closed. The built-in predicates
described in this section allow the user to open and close a constant term
stream for input or output. However, very often, a constant term stream is
created to be only read or written once and then closed. To avoid the
creation and the destruction of such a stream, GNU Prolog offers several
built-in predicates to perform single input/output from/to constant terms
\RefSP{Input/output-from/to-constant-terms}.

\subsubsection{\texttt{open\_input\_atom\_stream/2},
\texttt{open\_input\_chars\_stream/2}, \\
\texttt{open\_input\_codes\_stream/2}}

\begin{TemplatesOneCol}
open\_input\_atom\_stream(+atom, -stream)\\
open\_input\_chars\_stream(+character\_list, -stream)\\
open\_input\_codes\_stream(+character\_code\_list, -stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[open\_input\_atom\_stream/2]{open\_input\_atom\_stream(Atom, Stream)} unifies \texttt{Stream}
with the stream-term which is associated to a new input text-stream whose
data are the characters of \texttt{Atom}.

\IdxPBD[open\_input\_chars\_stream/2]{open\_input\_chars\_stream(Chars, Stream)} is similar to
\texttt{open\_input\_atom\_stream/2} except that data are the content of the
character list \texttt{Chars}.

\IdxPBD[open\_input\_codes\_stream/2]{open\_input\_codes\_stream(Codes, Stream)} is similar to
\texttt{open\_input\_atom\_stream/2} except that data are the content of the
character code list \texttt{Codes}.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is not a variable}
\ErrTerm{type\_error(variable, Stream)}

\ErrCond{\texttt{Atom} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Chars} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Codes} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor a an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Chars} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Chars)}

\ErrCond{\texttt{Codes} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{an element \texttt{E} of the \texttt{Chars} list is neither a
variable nor a character}
\ErrTerm{type\_error(character, E)}

\ErrCond{an element \texttt{E} of the \texttt{Codes} list is neither a
variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{an element \texttt{E} of the \texttt{Codes} list is an integer but
not a character code}
\ErrTerm{representation\_error(character\_code)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{close\_input\_atom\_stream/1},
\texttt{close\_input\_chars\_stream/1}, \\ 
\texttt{close\_input\_codes\_stream/1}}

\begin{TemplatesOneCol}
close\_input\_atom\_stream(+stream\_or\_alias)\\
close\_input\_chars\_stream(+stream\_or\_alias)\\
close\_input\_codes\_stream(+stream\_or\_alias)

\end{TemplatesOneCol}

\Description

\IdxPBD[close\_input\_atom\_stream/1]{close\_input\_atom\_stream(SorA)} closes the constant term stream
associated with the stream-term or alias \texttt{SorA}. \texttt{SorA} must a
stream open with \texttt{open\_input\_atom\_stream/2}
\RefSP{Introduction:(Constant-term-streams)}.

\IdxPBD[close\_input\_chars\_stream/1]{close\_input\_chars\_stream(SorA)} acts similarly for a character
list stream.

\IdxPBD[close\_input\_codes\_stream/1]{close\_input\_codes\_stream(SorA)} acts similarly for a character
code list stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(close, stream, SorA)}

\ErrCond{\texttt{SorA} is a stream-term or alias but does not refer to a
constant term stream.}
\ErrTerm{domain\_error(term\_stream\_or\_alias, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{open\_output\_atom\_stream/1}, 
\texttt{open\_output\_chars\_stream/1}, \\ 
\texttt{open\_output\_codes\_stream/1}}
\label{open-output-atom-stream/1}

\begin{TemplatesOneCol}
open\_output\_atom\_stream(-stream)\\
open\_output\_chars\_stream(-stream)\\
open\_output\_codes\_stream(-stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[open\_output\_atom\_stream/1]{open\_output\_atom\_stream(Stream)} unifies \texttt{Stream} with the
stream-term which is associated to a new output text-stream. All characters
written to this stream are collected and will be returned as an atom when
the stream is closed by \texttt{close\_ouput\_atom\_stream/2}
\RefSP{close-output-atom-stream/2}.

\IdxPBD[open\_output\_chars\_stream/1]{open\_output\_chars\_stream(Stream)} is similar to
\texttt{open\_output\_atom\_stream/1} except that the result will be a
character list.

\IdxPBD[open\_output\_codes\_stream/1]{open\_output\_codes\_stream(Stream)} is similar to
\texttt{open\_output\_atom\_stream/1} except that the result will be a
character code list.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is not a variable}
\ErrTerm{type\_error(variable, Stream)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{close\_output\_atom\_stream/2},
\texttt{close\_output\_chars\_stream/2}, \\
\texttt{close\_output\_codes\_stream/2}}
\label{close-output-atom-stream/2}

\begin{TemplatesOneCol}
close\_output\_atom\_stream(+stream\_or\_alias, ?atom)\\
close\_output\_chars\_stream(+stream\_or\_alias, ?character\_list)\\
close\_output\_codes\_stream(+stream\_or\_alias, ?character\_code\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[close\_output\_atom\_stream/2]{close\_output\_atom\_stream(SorA, Atom)} closes the constant term
stream associated with the stream-term or alias \texttt{SorA}. \texttt{SorA} must
be associated to a stream open with \texttt{open\_output\_atom\_stream/1}
\RefSP{open-output-atom-stream/1}.  \texttt{Atom} is unified with an atom
formed with all characters written on the stream.

\IdxPBD[close\_output\_chars\_stream/2]{close\_output\_chars\_stream(SorA, Chars)} acts similarly for a
character list stream.

\IdxPBD[close\_output\_codes\_stream/2]{close\_output\_codes\_stream(SorA, Codes)} acts similarly for a
character code list stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Chars} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Chars)}

\ErrCond{\texttt{Codes} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(close, stream, SorA)}

\ErrCond{\texttt{SorA} is a stream-term or alias but does not refer to a
constant term stream}
\ErrTerm{domain\_error(term\_stream\_or\_alias, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsection{Character input/output}
These built-in predicates enable a single character or character code to be
input from and output to a text stream. The atom \texttt{end\_of\_file} is
returned as character to indicate the end-of-file. \texttt{-1} is returned
as character code to indicate the end-of-file.

\subsubsection{\texttt{get\_char/2},
\texttt{get\_char/1}, 
\texttt{get\_code/1},
\texttt{get\_code/2}}
\label{get-char/2}

\begin{TemplatesOneCol}
get\_char(+stream\_or\_alias, ?in\_character)\\
get\_char(?in\_character)\\
get\_code(+stream\_or\_alias, ?in\_character\_code)\\
get\_code(?in\_character\_code)

\end{TemplatesOneCol}

\Description

\IdxPBD[get\_char/2]{get\_char(SorA, Char)} succeeds if \texttt{Char} unifies with the
next character read from the stream associated with the stream-term or alias
\texttt{SorA}.

\IdxPBD{get\_code/2} is similar to \texttt{get\_char/2} but deals with
character codes.

\IdxPBD{get\_char/1} and \IdxPBD{get\_code/1} apply to the current input
stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is neither a variable nor an in-character}
\ErrTerm{type\_error(in\_character, Char)}

\ErrCond{\texttt{Code} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Code)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\ErrCond{The entity input from the stream is not a character}
\ErrTerm{representation\_error(character)}

\ErrCond{\texttt{Code} is an integer but not an in-character code}
\ErrTerm{representation\_error(in\_character\_code)}

\end{PlErrors}

\Portability

ISO predicates.

\subsubsection{\texttt{get\_code\_no\_echo/2},
\texttt{get\_code\_no\_echo/1}}

\begin{TemplatesOneCol}
get\_code\_no\_echo(+stream\_or\_alias, ?integer)\\
get\_code\_no\_echo(?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[get\_code\_no\_echo/2]{get\_code\_no\_echo/2} is similar to \IdxPB{get\_code/2}
\RefSP{get-char/2} except that if the associated source is a terminal the
input is not echoed. This is possible only if the \IdxK{linedit} facility
has been installed \RefSP{The-line-editor} otherwise
\IdxPBD[get\_code\_no\_echo/1]{get\_code\_no\_echo/2} is similar to
\texttt{get\_code/2}. Any integer can be returned (not only an in-character
code) to allow for function key reading.

\texttt{get\_code\_no\_echo/1} applies to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Code} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Code)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{peek\_char/2},
\texttt{peek\_char/1},
\texttt{peek\_code/1},
\texttt{peek\_code/2}}

\begin{TemplatesOneCol}
peek\_char(+stream\_or\_alias, ?in\_character)\\
peek\_char(?in\_character)\\
peek\_code(+stream\_or\_alias, ?in\_character\_code)\\
peek\_code(?in\_character\_code)

\end{TemplatesOneCol}

\Description

\IdxPBD[peek\_char/2]{peek\_char(SorA, Char)} succeeds if \texttt{Char} unifies with the
next character that will be read from the stream associated with the stream-term
or alias \texttt{SorA}. The character is not read.

\IdxPBD{peek\_code/2} is similar to \texttt{peek\_char/2} but deals with
character codes.

\IdxPBD{peek\_char/1} and \IdxPBD{peek\_code/1} apply to the current input
stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is neither a variable nor an in-character}
\ErrTerm{type\_error(in\_character, Char)}

\ErrCond{\texttt{Code} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Code)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\ErrCond{The entity input from the stream is not a character}
\ErrTerm{representation\_error(character)}

\ErrCond{\texttt{Code} is an integer but not an in-character code}
\ErrTerm{representation\_error(in\_character\_code)}

\end{PlErrors}

\Portability

ISO predicates.

\subsubsection{\texttt{unget\_char/2},
\texttt{unget\_char/1},
\texttt{unget\_code/2},
\texttt{unget\_code/1}}

\begin{TemplatesOneCol}
unget\_char(+stream\_or\_alias, +character)\\
unget\_char(+character)\\
unget\_code(+stream\_or\_alias, +character\_code)\\
unget\_code(+character\_code)

\end{TemplatesOneCol}

\Description

\IdxPBD[unget\_char/2]{unget\_char(SorA, Char)} pushes back \texttt{Char}
onto the stream associated with the stream-term or alias \texttt{SorA}.
\texttt{Char} will be the next character read by \texttt{get\_char/2}. The
maximum number of characters that can be cumulatively pushed back is given by
the \IdxPF{max\_unget} \Idx{Prolog flag} \RefSP{set-prolog-flag/2}.

\IdxPBD{unget\_code/2} is similar to \texttt{unget\_char/2} but deals with
character codes.

\IdxPBD{unget\_char/1} and \IdxPBD{unget\_code/1} apply to the current input
stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Code} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is neither a variable nor a character}
\ErrTerm{type\_error(character, Char)}

\ErrCond{\texttt{Code} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Code)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{Code} is an integer but not a character code}
\ErrTerm{representation\_error(character\_code)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{put\_char/2},
\texttt{put\_char/1},
\texttt{put\_code/1},
\texttt{put\_code/2},
\texttt{nl/1},
\texttt{nl/0}}
\label{put-char/2}

\begin{TemplatesOneCol}
put\_char(+stream\_or\_alias, +character)\\
put\_char(+character)\\
put\_code(+stream\_or\_alias, +character\_code)\\
put\_code(+character\_code)\\
nl(+stream\_or\_alias)\\
nl

\end{TemplatesOneCol}

\Description

\IdxPBD[put\_char/2]{put\_char(SorA, Char)} writes \texttt{Char} onto the
stream associated with the stream-term or alias \texttt{SorA}.

\IdxPBD{put\_code/2} is similar to \texttt{put\_char/2} but deals with
character codes.

\IdxPBD[nl/1]{nl(SorA)} writes a new-line character onto the stream
associated with the stream-term or alias \texttt{SorA}. This is equivalent to
\texttt{put\_char(SorA, '{\bs}n')}.

\IdxPBD{put\_char/1}, \IdxPBD{put\_code/1} and \IdxPBD{nl/0} apply to the
current output stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Code} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is neither a variable nor a character}
\ErrTerm{type\_error(character, Char)}

\ErrCond{\texttt{Code} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Code)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(output, binary\_stream, SorA)}

\ErrCond{\texttt{Code} is an integer but not a character code}
\ErrTerm{representation\_error(character\_code)}

\end{PlErrors}

\Portability

ISO predicates.

\subsection{Byte input/output}
\label{Byte-input/output}

These built-in predicates enable a single byte to be input from and output
to a binary stream. \texttt{-1} is returned to indicate the end-of-file.

\subsubsection{\texttt{get\_byte/2},
\texttt{get\_byte/1}}

\begin{TemplatesOneCol}
get\_byte(+stream\_or\_alias, ?in\_byte)\\
get\_byte(?in\_byte)

\end{TemplatesOneCol}

\Description

\IdxPBD[get\_byte/2]{get\_byte(SorA, Byte)} succeeds if \texttt{Byte} unifies with the
next byte read from the stream associated with the stream-term or alias
\texttt{SorA}.

\IdxPBD[get\_byte/1]{get\_byte/1} applies to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Byte} is neither a variable nor an in-byte}
\ErrTerm{type\_error(in\_byte, Byte)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a text stream}
\ErrTerm{permission\_error(input, text\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\end{PlErrors}

\Portability

ISO predicates.

\subsubsection{\texttt{peek\_byte/2},
\texttt{peek\_byte/1}}

\begin{TemplatesOneCol}
peek\_byte(+stream\_or\_alias, ?in\_byte)\\
peek\_byte(?in\_byte)

\end{TemplatesOneCol}

\Description

\IdxPBD[peek\_byte/2]{peek\_byte(SorA, Byte)} succeeds if \texttt{Byte} unifies with the
next byte that will be read from the stream associated with the stream-term or
alias \texttt{SorA}. The byte is not read.

\IdxPBD[peek\_byte/1]{peek\_byte/1} applies to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Byte} is neither a variable nor an in-byte}
\ErrTerm{type\_error(in\_byte, Byte)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a text stream}
\ErrTerm{permission\_error(input, text\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\end{PlErrors}

\Portability

ISO predicates.

\subsubsection{\texttt{unget\_byte/2},
\texttt{unget\_byte/1}}

\begin{TemplatesOneCol}
unget\_byte(+stream\_or\_alias, +byte)\\
unget\_byte(+byte)

\end{TemplatesOneCol}

\Description

\IdxPBD[unget\_byte/2]{unget\_byte(SorA, Byte)} pushes back \texttt{Byte} onto the stream
associated with the stream-term or alias \texttt{SorA}. \texttt{Byte} will be
the next byte read by \texttt{get\_byte/2}. The maximum number of bytes that
can be successively pushed back is given by the \IdxPF{max\_unget}
\Idx{Prolog flag} \RefSP{set-prolog-flag/2}.

\IdxPBD[unget\_byte/1]{unget\_byte/1} applies to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Byte} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Byte} is neither a variable nor a byte}
\ErrTerm{type\_error(byte, Byte)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a text stream}
\ErrTerm{permission\_error(input, text\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{put\_byte/2},
\texttt{put\_byte/1}}

\begin{TemplatesOneCol}
put\_byte(+stream\_or\_alias, +byte)\\
put\_byte(+byte)

\end{TemplatesOneCol}

\Description

\IdxPBD[put\_byte/2]{put\_byte(SorA, Byte)} writes \texttt{Byte} onto the stream
associated with the stream-term or alias \texttt{SorA}. 

\IdxPBD[put\_byte/1]{put\_byte/1} applies to the current output stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Byte} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Byte} is neither a variable nor a byte}
\ErrTerm{type\_error(byte, Byte)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a text stream}
\ErrTerm{permission\_error(output, text\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsection{Term input/output}
\label{Term-input/output}
These built-in predicates enable a Prolog term to be input from or output to
a text stream. The atom \texttt{end\_of\_file} is returned as term to
indicate the end-of-file. The syntax of such terms can also be altered by
changing the operators \RefSP{op/3:(Term-input/output)}, and making some
characters equivalent to others \RefSP{char-conversion/2} if the
\IdxPF{char\_conversion} \Idx{Prolog flag} is \texttt{on}
\RefSP{set-prolog-flag/2}. Double quoted tokens will be returned as an atom
or a character list or a character code list depending on the value of the
\IdxPF{double\_quotes} Prolog flag \RefSP{set-prolog-flag/2}.

\subsubsection{\texttt{read\_term/3},
\texttt{read\_term/2},
\texttt{read/2},
\texttt{read/1}}
\label{read-term/3}

\begin{TemplatesOneCol}
read\_term(+stream\_or\_alias, ?term, +read\_option\_list)\\
read\_term(?term, +read\_option\_list)\\
read(+stream\_or\_alias, ?term)\\
read(?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[read\_term/3]{read\_term(SorA, Term, Options)} is true if
\texttt{Term} unifies with the next term read from the stream associated
with the stream-term or alias \texttt{SorA} according to the options given by
\texttt{Options}.

\SPart{Read options}: \texttt{Options} is a list of read options. If this
list contains contradictory options, the rightmost option is the one which
applies. Possible options are:

\begin{itemize}

\item \IdxPOD[variables]{variables(VL)}: \texttt{VL} is unified with the
list of all variables of the input term, in left-to-right traversal
order. Anonymous variables are included in the list \texttt{VL}.

\item \IdxPOD[variable\_names]{variable\_names(VNL)}: \texttt{VNL} is
unified with the list of pairs \texttt{Name = Var} where \texttt{Var} is a
named variable of the term and \texttt{Name} is the atom associated to the
name of \texttt{Var}.  Anonymous variables are not included in the list
\texttt{VNL}.

\item \IdxPOD[singletons]{singletons(SL)}: \texttt{SL} is unified with the
list of pairs \texttt{Name = Var} where \texttt{Var} is a named variable
which occurs only once in the term and \texttt{Name} is the atom associated
to the name of \texttt{Var}. Anonymous variables are not included in the list
\texttt{SL}.

\item \IdxPOD[syntax\_error]
{syntax\_error(error}/\texttt{warning}/\texttt{fail)}: specifies the effect
of a syntax error:

\begin{itemize}

\item \IdxPOD{error}: a \texttt{syntax\_error} is raised.

\item \IdxPOD{warning}: a warning message is displayed and the predicate
fails.

\item \IdxPOD{fail}: the predicate quietly fails.

\end{itemize}

The default value is the value of the \IdxPF{syntax\_error}
\Idx{Prolog flag} \RefSP{set-prolog-flag/2}.

\item \IdxPOD[end\_of\_term]{end\_of\_term(dot}/\texttt{eof)}: specifies the
end-of-term delimiter: \texttt{dot} is the classical full-stop delimiter (a
dot followed with a layout character), \texttt{eof} is the end-of-file
delimiter. This option is useful for predicates like
\IdxPB{read\_from\_atom/2} \RefSP{read-term-from-atom/3} to avoid to add a
terminal dot at the end of the atom. The default value is \texttt{dot}.

\end{itemize}

\IdxPBD[read/2]{read(SorA, Term)} is equivalent to
\texttt{read\_term(SorA, Term, [])}.

\IdxPBD{read\_term/2} and \IdxPBD{read/1} apply to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{Options} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Options)}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is neither a
variable nor a valid read option}
\ErrTerm{domain\_error(read\_option, E)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\ErrCond{a syntax error occurs and the value of the \texttt{syntax\_error}
Prolog flag is \texttt{error} \RefSP{set-prolog-flag/2}}
\ErrTerm{syntax\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

ISO predicates. The ISO reference raises a
\texttt{representation\_error(Flag)} where \texttt{Flag} is
\texttt{max\_arity},\texttt{ max\_integer}, or\texttt{ min\_integer} when
the read term breaches an implementation defined limit specified by
\texttt{Flag}. GNU Prolog detects neither \texttt{min\_integer} nor
\texttt{max\_integer} violation and treats a \texttt{max\_arity} violation
as a syntax error. The read options \texttt{syntax\_error/1} and
\texttt{end\_of\_term/1} are GNU Prolog extensions.

\subsubsection{\texttt{read\_atom/2},
\texttt{read\_atom/1}, 
\texttt{read\_integer/2},
\texttt{read\_integer/1}, \\ 
\texttt{read\_number/2},
\texttt{read\_number/1}}
\label{read-atom/2}

\begin{TemplatesOneCol}
read\_atom(+stream\_or\_alias, ?atom)\\
read\_atom(?atom)\\
read\_integer(+stream\_or\_alias, ?integer)\\
read\_integer(?integer)\\
read\_number(+stream\_or\_alias, ?number)\\
read\_number(?number)

\end{TemplatesOneCol}

\Description

\IdxPBD[read\_atom/2]{read\_atom(SorA, Atom)} succeeds if \texttt{Atom}
unifies with the next atom read from the stream associated with the
stream-term or alias \texttt{SorA}.

\IdxPBD[read\_integer/2]{read\_integer(SorA, Integer)} succeeds if
\texttt{Integer} unifies with the next integer read from the stream
associated with the stream-term or alias \texttt{SorA}.

\IdxPBD[read\_number/2]{read\_number(SorA, Number)} succeeds if
\texttt{Number} unifies with the next number (integer or floating point
number) read from the stream associated with the stream-term or alias
\texttt{SorA}.

\IdxPBD{read\_atom/1}, \IdxPBD{read\_integer/1} and \IdxPBD{read\_number/1}
apply to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Integer} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Integer)}

\ErrCond{\texttt{Number} is neither a variable nor a number}
\ErrTerm{type\_error(number, Number)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\ErrCond{a syntax error occurs and the value of the \texttt{syntax\_error}
Prolog flag is \texttt{error} \RefSP{set-prolog-flag/2}}
\ErrTerm{syntax\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{read\_token/2},
\texttt{read\_token/1}}
\label{read-token/2}

\begin{TemplatesOneCol}
read\_token(+stream\_or\_alias, ?nonvar)\\
read\_token(?nonvar)

\end{TemplatesOneCol}

\Description

\IdxPBD[read\_token/2]{read\_token(SorA, Token)} succeeds if \texttt{Token} unifies with
the encoding of the next Prolog token read from the stream associated with
stream-term or alias \texttt{SorA}.

\SPart{Token encoding}:

\begin{itemize}

\item \IdxPTD[var]{var(A)}: a variable is read whose name is the atom
\texttt{A}.

\item an atom \texttt{A}: an atom \texttt{A} is read.

\item integer \texttt{N}: an integer \texttt{N} is read.

\item floating point number \texttt{N}: a floating point number \texttt{N}
is read.

\item \IdxPTD[string]{string(A)}: a string (double quoted item) is read whose
characters forms the atom \texttt{A}. 

\item \IdxPTD[punct]{punct(P)}: a punctuation character \texttt{P} is read
(\texttt{P} is a one-character atom in \texttt{()[]{\lb}|{\rb}}, the atom
\texttt{full\_stop} or the atom \texttt{end\_of\_file}).

\item \IdxPTD[back\_quotes]{back\_quotes(A)}: a back quoted item is read
whose characters forms the atom \texttt{A}.

\item \IdxPTD[extended]{extended(A)}: an extended character \texttt{A} (an
atom) is read.

\end{itemize}

As for \texttt{read\_term/3}, the behavior of \texttt{read\_token/2} can be
affected by some \Idx[Prolog flag]{Prolog flags} \RefSP{Term-input/output}.

\IdxPBD[read\_token/1]{read\_token/1} applies to the current input stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an output stream}
\ErrTerm{permission\_error(input, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(input, binary\_stream, SorA)}

\ErrCond{\texttt{SorA} has stream properties \texttt{end\_of\_stream(past)}
and \texttt{eof\_action(error)}}
\ErrTerm{permission\_error(input, past\_end\_of\_stream, SorA)}

\ErrCond{a syntax error occurs and the value of the \texttt{syntax\_error}
Prolog flag is \texttt{error} \RefSP{set-prolog-flag/2}}
\ErrTerm{syntax\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{syntax\_error\_info/4}}
\label{syntax-error-info/4}

\begin{TemplatesOneCol}
syntax\_error\_info(?atom, ?integer, ?integer, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[syntax\_error\_info/4]{syntax\_error\_info(FileName, Line, Column, Error)} returns the
information associated to the last syntax error. \texttt{Line} is the line
number of the error, \texttt{Column} is the column number of the error and
\texttt{Error} is an atom explaining the error.

\begin{PlErrors}

\ErrCond{\texttt{FileName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, FileName)}

\ErrCond{\texttt{Line} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Line)}

\ErrCond{\texttt{Column} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Column)}

\ErrCond{\texttt{Error} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Error)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{last\_read\_start\_line\_column/2}}

\begin{TemplatesOneCol}
last\_read\_start\_line\_column(?integer, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[last\_read\_start\_line\_column/2]{last\_read\_start\_line\_column(Line, Column)} unifies \texttt{Line}
and \texttt{Column} with the line number and the column number associated to
the start of the last read predicate. This predicate can be used after
calling one of the following predicates: \IdxPB{read\_term/3},
\IdxPB{read\_term/2}, \IdxPB{read/2}, \IdxPB{read/1}
\RefSP{read-term/3}, \IdxPB{read\_atom/2}, \IdxPB{read\_atom/1},
\IdxPB{read\_integer/2}, \IdxPB{read\_integer/1}, \IdxPB{read\_number/2},
\IdxPB{read\_number/1} \RefSP{read-atom/2} or \IdxPB{read\_token/2},
\IdxPB{read\_token/1} \RefSP{read-token/2}.

\begin{PlErrors}

\ErrCond{\texttt{Line} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Line)}

\ErrCond{\texttt{Column} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Column)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{write\_term/3},
\texttt{write\_term/2},
\texttt{write/2},
\texttt{write/1},
\texttt{writeq/2},
\texttt{writeq/1}, \\
\texttt{write\_canonical/2},
\texttt{write\_canonical/1},
\texttt{display/2},
\texttt{display/1},
\texttt{print/2}, \\
\texttt{print/1}}
\label{write-term/3}

\begin{TemplatesOneCol}
write\_term(+stream\_or\_alias, ?term, +write\_option\_list)\\
write\_term(?term, +write\_option\_list)\\
write(+stream\_or\_alias, ?term)\\
write(?term)\\
writeq(+stream\_or\_alias, ?term)\\
writeq(?term)\\
write\_canonical(+stream\_or\_alias, ?term)\\
write\_canonical(?term)\\
display(+stream\_or\_alias, ?term)\\
display(?term)\\
print(+stream\_or\_alias, ?term)\\
print(?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[write\_term/3]{write\_term(SorA, Term, Options)} writes
\texttt{Term} to the stream associated with the stream-term or alias
\texttt{SorA} according to the options given by \texttt{Options}.

\SPart{Write options}: \texttt{Options} is a list of write options. If this
list contains contradictory options, the rightmost option is the one which
applies. Possible options are:

\begin{itemize}

\item \IdxPOD[quoted]{quoted(true}/\texttt{false)}: if \texttt{true} each
atom and functor is quoted if this would be necessary for the term to be
input by \texttt{read\_term/3}. If \texttt{false} no extra quotes are
written. The default value is \texttt{false}.

\item \IdxPOD[ignore\_ops]{ignore\_ops(true}/\texttt{false}): if
\texttt{true} each compound term is output in functional notation (neither
operator notation nor list notation is used). If \texttt{false} operator and
list notations are used. The default value is \texttt{false}.

\item \IdxPOD[numbervars]{numbervars(true}/\texttt{false}): if
\texttt{true} a term of the form \texttt{'\$VAR'(N)}, where \texttt{N} is an
integer, is output as a variable name (see below). If \texttt{false}
such a term is output normally (according to the other options). The
default value is
\texttt{true}.

\item \IdxPOD[namevars]{namevars(true}/\texttt{false}): if \texttt{true} a
term of the form \texttt{'\$VARNAME'(Name)}, where \texttt{Name} is an atom,
is output as a variable name (see below). If \texttt{false} such a term is
output normally (according to the other options). The default value is
\texttt{true}.

\item \IdxPOD[space\_args]{space\_args(true}/\texttt{false}): if
\texttt{true} an extra space character is emitted after each comma
separating the arguments of a compound term in functional notation or of a
list. If \texttt{false} no extra space is emitted. The default value is
\texttt{false}.

\item \IdxPOD[portrayed]{portrayed(true}/\texttt{false}): if \texttt{true}
and if there exists a predicate \texttt{portray/1}, \texttt{write\_term/3}
acts as follows: if \texttt{Term} is a variable it is simply written. If
\texttt{Term} is non-variable then it is passed to \IdxPBD{portray/1}. If
this succeeds then it is assumed that \texttt{Term} has been output.
Otherwise \texttt{write\_term/3} outputs the principal functor of
\texttt{Term} (\texttt{Term} itself if it is atomic) according to other
options and recursively calls \texttt{portray/1} on the components of
\texttt{Term} (if it is a compound term). With \texttt{ignore\_ops(false)} a
list is first passed to \texttt{portray/1} and only if this call fails each
element of the list is passed to \texttt{portray/1} (thus every sub-list is
not passed). The default value is \texttt{false}.

\item \IdxPOD[max\_depth]{max\_depth(N}): controls the depth of output for
compound terms. \texttt{N} is an integer specifying the depth. The output of
a term whose depth is greater then \texttt{N} gives rise to the output of
\texttt{...} (3 dots). By default there is no depth limit.

\end{itemize}

\SPart{Variable numbering}: when the \texttt{numbervars(true)} option is
passed to \texttt{write\_term/3} any term of the form \texttt{'\$VAR'(N)}
where \texttt{N} is an integer is output as a variable name consisting of a
capital letter possibly followed by an integer. The capital letter is the
\texttt{(I+1)}\emph{th} letter of the alphabet and the integer is
\texttt{J}, where \texttt{I = N mod 26} and \texttt{J = N // 26}. The
integer \texttt{J} is omitted if it is zero. For example: 

\begin{CodeTwoCols}[2cm]
\Two{'\$VAR'(0)}{is written as \texttt{A}}
\Two{'\$VAR'(1)}{is written as \texttt{B}}
\One{...}
\Two{'\$VAR'(25)}{is written as \texttt{Z}}
\Two{'\$VAR'(26)}{is written as \texttt{A1}}
\Two{'\$VAR'(27)}{is written as \texttt{B1}}
\end{CodeTwoCols}

\SPart{Variable naming}: when the \texttt{namevars(true)} option is passed
to \texttt{write\_term/3} any term of the form \texttt{'\$VARNAME'(Name)}
where \texttt{Name} is an atom is output as a variable name consisting of
the characters \texttt{Name}. For example: \texttt{'\$VARNAME'('A')} is
written as \texttt{A} (even in the presence of the \texttt{quoted(true)}
option).

\IdxPBD[write/2]{write(SorA, Term)} is equivalent to
\texttt{write\_term(SorA, Term, [])}.

\IdxPBD[writeq/2]{writeq(SorA, Term)} is equivalent to
\texttt{write\_term(SorA, Term, [quoted(true)])}.

\IdxPBD[write\_canonical/2]{write\_canonical(SorA, Term)} is equivalent to
\IdxPBD[write\_term/2]{write\_term(SorA, Term, [quoted(true), \\
ignore\_ops(true), numbervars(false)])}.

\IdxPBD[display/2]{display(SorA, Term)} is equivalent to
\texttt{write\_term(SorA, Term, [ignore\_ops(true), \\
numbervars(false)])}.

\IdxPBD[print/2]{print(SorA, Term)} is equivalent to
\texttt{write\_term(SorA, Term, [numbervars(false), \\
portrayed(true)])}.

\IdxPBD{write\_term/2}, \IdxPBD{write/1}, \IdxPBD{writeq/1},
\IdxPBD{write\_canonical/1}, \IdxPBD{display/1} and \IdxPBD{print/1} apply
to the current output stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Options} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Options)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{an element \texttt{E} of the \texttt{Options} list is neither a
variable nor a valid write-option}
\ErrTerm{domain\_error(write\_option, E)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(output, binary\_stream, SorA)}

\end{PlErrors}

\Portability

ISO predicates except \texttt{display/1-2} and \texttt{print/1-2} that
are GNU Prolog predicates. \texttt{namevars/1}, \texttt{space\_args/1},
\texttt{portrayed/1} and \texttt{max\_depth/1} options are GNU Prolog
extensions.

\subsubsection{\texttt{format/3},
\texttt{format/2}}
\label{format/3}

\begin{TemplatesOneCol}
format(+stream\_or\_alias, +character\_code\_list\_or\_atom,
+list)\\
format(+character\_code\_list\_or\_atom, +list)

\end{TemplatesOneCol}

\Description

\IdxPBD[format/3]{format(SorA, Format, Arguments)} writes the \texttt{Format} string
replacing each format control sequence \texttt{F} by the corresponding
element of \texttt{Arguments} (formatted according to \texttt{F}) to the
stream associated with the stream-term or alias \texttt{SorA}.

\SPart{Format control sequences}: the general format of a control sequence
is \texttt{'\~{}NC'}. The character \texttt{C} determines the type of
the control sequence. \texttt{N} is an optional numeric argument. An
alternative form of \texttt{N} is \texttt{'*'}. \texttt{'*'} implies
that the next argument \texttt{Arg} in \texttt{Arguments} should be
used as a numeric argument in the control sequence. The use of C
\texttt{printf()} formatting sequence (beginning by the character
\texttt{\%}) is also allowed. The following control sequences are
available:

\begin{tabular}{|C{1.4cm}|C{2.8cm}|p{10.45cm}|}
\hline

Format sequence  & type of the argument & Description \\

\hline\hline

\texttt{\~{}a} & atom & print the atom without quoting \\

\hline

\texttt{\~{}Nc} & character code & print the character associated to the
code. \texttt{N} is the number of times to print the character (default: 1)\\

\hline

\texttt{ \~{}Nf}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

\texttt{\~{}Ne \~{}NE \~{}Ng \~{}NG}
               &  float expression & pass the argument \texttt{Arg} and 
                                     \texttt{N} to the C \texttt{printf()}
                                     function as: 
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

                               if \texttt{N} is not specified 
                               \texttt{printf("\%f",Arg)} else
                               \texttt{printf("\%.Nf",Arg)}.
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

Similarly for \texttt{\~{}Ne}, \texttt{\~{}NE}, \texttt{\~{}Ng} and \texttt{\~{}NG} \\ 

\hline

\texttt{\~{}Nd} & integer expression & print the argument. \texttt{N} is the
number of digits after the decimal point. If \texttt{N} is 0 no
decimal point is printed (default: 0)\\

\hline

\texttt{\~{}ND} & integer expression & identical to \texttt{\~{}Nd} except
that \texttt{','} separates groups of three digits to the left of the
decimal point \\

\hline

\texttt{\~{}Nr} & integer expression & print the argument according to the
radix \texttt{N}. 2 $\leq$ \texttt{N} $\leq$ 36 (default: 8). The letters
\texttt{a-z} denote digits $>$ 9 \\ 

\hline

\texttt{\~{}NR} & integer expression & identical to \texttt{\~{}Nr} except
that the letters \texttt{A-Z} denote digits $>$ 9 \\

\hline

\texttt{\~{}Ns} & character code list & print exactly \texttt{N} characters 
(default: the length of the list) \\

\hline

\texttt{\~{}NS} & character list & print exactly \texttt{N} characters
(default: the length of the list) \\

\hline

\texttt{\~{}i} & term & ignore the current argument \\

\hline

\texttt{\~{}k} & term & pass the argument to
\IdxPB{write\_canonical/1} \RefSP{write-term/3} \\

\hline

\texttt{\~{}p} & term & pass the argument to \IdxPB{print/1}
\RefSP{write-term/3} \\

\hline

\texttt{\~{}q} & term & pass the argument to \IdxPB{writeq/1}
\RefSP{write-term/3} \\

\hline

\texttt{\~{}w} & term & pass the argument to \IdxPB{write/1}
\RefSP{write-term/3} \\

\hline

\texttt{\~{}\~{}} & none & print the character \texttt{'\~{}'} \\

\hline

\texttt{\~{}Nn} & none & print \texttt{N} new-line characters (default: 1) \\

\hline

\texttt{\~{}N} & none & print a new-line character if not at the beginning
of a line \\

\hline

\texttt{\~{}?} & atom & use the argument as a nested format string \\

\hline

\texttt{\%F} & atom, integer or float expression & interface to the C
function \texttt{printf(3)} for outputting atoms (C string), integers and
floating point numbers. \texttt{*} are also allowed. \\

\hline
\end{tabular}

\IdxPBD[format/2]{format/2} applies to the current output stream.

\begin{PlErrors}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Format} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Arguments} is a partial list}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Format} is neither a partial list nor a list or an atom}
\ErrTerm{type\_error(list, Format)}

\ErrCond{\texttt{Arguments} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Arguments)}

\ErrCond{an element \texttt{E} of the \texttt{Format} list is neither a
variable nor a character code}
\ErrTerm{representation\_error(character\_code, E)}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{an element \texttt{E} of Format is not a valid format control
sequence}
\ErrTerm{domain\_error(format\_control\_sequence, E)}

\ErrCond{the \texttt{Arguments} list does not contain sufficient elements}
\ErrTerm{domain\_error(non\_empty\_list, [])}

\ErrCond{an element \texttt{E} of the \texttt{Arguments} list is a variable
while a non-variable term was expected}
\ErrTerm{instantiation\_error}

\ErrCond{an element \texttt{E} of the \texttt{Arguments} list is neither
variable nor an atom while an atom was expected}
\ErrTerm{type\_error(atom, E)}

\ErrCond{an element \texttt{E} of the \texttt{Arguments} cannot be evaluated
as an arithmetic expression while an integer or a floating point number was
expected}
\ErrTermRm{an arithmetic error \RefSP{Evaluation-of-an-arithmetic-expression}}

\ErrCond{an element \texttt{E} of the \texttt{Arguments} list is neither
variable nor character code while a character code was expected}
\ErrTerm{representation\_error(character\_code, E)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(output, binary\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates. 

\subsubsection{\texttt{portray\_clause/2},
\texttt{portray\_clause/1}}
\label{portray-clause/2}

\begin{TemplatesOneCol}
portray\_clause(+stream\_or\_alias, +clause)\\
portray\_clause(+clause)

\end{TemplatesOneCol}

\Description

\IdxPBD[portray\_clause/2]{portray\_clause(SorA, Clause)} pretty prints
\texttt{Clause} to the stream associated with the stream-term or alias
\texttt{SorA}.
\texttt{portray\_clause/2} uses the variable binding predicates
\IdxPB{name\_singleton\_vars/1} \RefSP{name-singleton-vars/1} and
\IdxPB{numbervars/1} \RefSP{bind-variables/2}. This predicate is
used by \IdxPB{listing/1} \RefSP{listing/1}.

\IdxPBD[portray\_clause/1]{portray\_clause/1} applies to the current output stream.

\begin{PlErrors}

\ErrCond{\texttt{Clause} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Clause} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Clause)}

\ErrCond{\texttt{SorA} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{SorA} is neither a variable nor a stream-term or alias}
\ErrTerm{domain\_error(stream\_or\_alias, SorA)}

\ErrCond{\texttt{SorA} is not associated with an open stream}
\ErrTerm{existence\_error(stream, SorA)}

\ErrCond{\texttt{SorA} is an input stream}
\ErrTerm{permission\_error(output, stream, SorA)}

\ErrCond{\texttt{SorA} is associated with a binary stream}
\ErrTerm{permission\_error(output, binary\_stream, SorA)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{get\_print\_stream/1}}

\begin{TemplatesOneCol}
get\_print\_stream(-stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[get\_print\_stream/1]{get\_print\_stream(Stream)} unifies \texttt{Stream} with the
stream-term associated to the output stream used by \IdxPB{print/2}
\RefSP{write-term/3}. The purpose of this predicate is to allow a
user-defined \IdxPB{portray/1} predicate to identify the output stream in
use.

\begin{PlErrors}

\ErrCond{\texttt{Stream} is not a variable}
\ErrTerm{type\_error(variable, Stream)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{op/3}}
\label{op/3:(Term-input/output)}

\begin{TemplatesOneCol}
op(+integer, +operator\_specifier, +atom\_or\_atom\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[op/3]{op(Priority, OpSpecifier, Operator)} alters the operator table.
\texttt{Operator} is declared as an operator with properties defined by
specifier \texttt{OpSpecifier} and \texttt{Priority}. \texttt{Priority} must
be an integer $\geq$ 0 and $\leq$ 1200. If \texttt{Priority} is 0 then the
operator properties of \texttt{Operator} (if any) are canceled.
\texttt{Operator} may also be a list of atoms in which case all of them are
declared to be operators. In general, operators can be removed from
the operator table and their priority or specifier can be changed. However,
it is an error to attempt to change the \texttt{','} operator from its
initial status. An atom can have multiple operator definitions (e.g.
prefix and infix like \texttt{+}) however an atom cannot have both an
infix and a postfix operator definitions.

\SPart{Operator specifiers}: the following specifiers are available:

\begin{tabular}{|c|c|c|}
\hline

Specifier & Type & Associativity \\

\hline\hline

\texttt{fx} & prefix & no \\

\hline

\texttt{fy} & prefix & yes \\

\hline

\texttt{xf} & postfix & no \\

\hline

\texttt{yf} & postfix & yes \\

\hline

\texttt{xfx} & infix & no \\

\hline

\texttt{yfx} & infix & left \\

\hline

\texttt{xfy} & infix & right \\

\hline
\end{tabular}

\SPart{Prolog predefined operators}:

\begin{tabular}{|r|c|L{11cm}|}
\hline

Priority & Specifier & Operators \\

\hline\hline

\texttt{1200} & \texttt{xfx} & \texttt{:- ~--{\gt}} \\

\hline

\texttt{1200} & \texttt{fx} & \texttt{:-} \\

\hline

\texttt{1100} & \texttt{xfy} & \texttt{;} \\

\hline

\texttt{1050} & \texttt{xfy} & \texttt{-{\gt}} \\

\hline

\texttt{1000} & \texttt{xfy} & \texttt{,} \\

\hline

\texttt{900} & \texttt{fy} & \texttt{{\bs}+} \\

\hline

\texttt{700} & \texttt{xfx} & \texttt{= ~{\bs}= ~=.. ~== ~{\bs}== ~@{\lt}
~@={\lt} ~@{\gt} ~@{\gt}= ~is ~=:= ~={\bs}= ~{\lt} ~={\lt} ~{\gt} ~{\gt}=}
\\

\hline

\texttt{500} & \texttt{yfx} & \texttt{+ ~- ~/{\bs} ~{\bs}/} \\

\hline

\texttt{400} & \texttt{yfx} & \texttt{* ~/ ~// ~rem ~mod ~{\lt}{\lt}
~{\gt}{\gt}} \\

\hline

\texttt{200} & \texttt{xfy} & \texttt{** ~\^{}} \\

\hline

\texttt{200} & \texttt{fy} & \texttt{+ ~- ~{\bs}} \\

\hline
\end{tabular}

\SPart{FD predefined operators}:

\begin{tabular}{|r|c|L{11cm}|}
\hline

Priority & Specifier & Operators \\

\hline\hline

\texttt{750} & \texttt{xfy} & \texttt{\#{\lt}={\gt} ~\#{\bs}{\lt}={\gt}} \\

\hline

\texttt{740} & \texttt{xfy} & \texttt{\#=={\gt} ~\#{\bs}=={\gt}} \\

\hline

\texttt{730} & \texttt{xfy} & \texttt{\#\# ~\#{\bs}/ ~\#{\bs}{\bs}/} \\

\hline

\texttt{720} & \texttt{yfx} & \texttt{\#/{\bs} ~\#{\bs}/{\bs}} \\

\hline

\texttt{710} & \texttt{fy} & \texttt{\#{\bs}} \\

\hline

\texttt{700} & \texttt{xfx} & \texttt{\#= ~\#{\bs}= ~\#{\lt} ~\#={\lt}
~\#{\gt} ~\#{\gt}= ~\#=\# ~\#{\bs}=\# ~\#{\lt}\# ~\#={\lt}\# ~\#{\gt}\#
~\#{\gt}=\#} \\

\hline

\texttt{500} & \texttt{yfx} & \texttt{+ ~-} \\

\hline

\texttt{400} & \texttt{yfx} & \texttt{* ~/ ~// ~rem} \\

\hline

\texttt{200} & \texttt{xfy} & \texttt{**} \\

\hline

\texttt{200} & \texttt{fy} & \texttt{+ ~-} \\

\hline
\end{tabular}

\begin{PlErrors}

\ErrCond{\texttt{Priority} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{OpSpecifier} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Operator} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Priority} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Priority)}

\ErrCond{\texttt{OpSpecifier} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, OpSpecifier)}

\ErrCond{\texttt{Operator} is neither a partial list nor a list nor an atom}
\ErrTerm{type\_error(list, Operator)}

\ErrCond{an element \texttt{E} of the \texttt{Operator} list is neither a
variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{\texttt{Priority} is an integer not $\geq$ 0 and $\leq$ 1200}
\ErrTerm{domain\_error(operator\_priority, Priority)}

\ErrCond{\texttt{OpSpecifier} is not a valid operator specifier}
\ErrTerm{domain\_error(operator\_specifier, OpSpecifier)}

\ErrCond{\texttt{Operator} is \texttt{','} or an element of the
\texttt{Operator} list is \texttt{','}}
\ErrTerm{permission\_error(modify, operator, ',')}

\ErrCond{\texttt{OpSpecifier} is a specifier such that \texttt{Operator}
would have a postfix and an infix definition.}
\ErrTerm{permission\_error(create, operator, Operator)}

\end{PlErrors}

\Portability

ISO predicate. 

The ISO reference implies that if a program calls \texttt{current\_op/3},
then modifies an operator definition by calling \texttt{op/3} and backtracks
into the call to \texttt{current\_op/3}, then the changes are guaranteed not
to affect that \texttt{current\_op/3} goal.  This is not guaranteed by
GNU Prolog.

\subsubsection{\texttt{current\_op/3}}

\begin{TemplatesOneCol}
current\_op(?integer, ?operator\_specifier, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_op/3]{current\_op(Priority, OpSpecifier, Operator)} succeeds if
\texttt{Operator} is an operator with properties defined by specifier
\texttt{OpSpecifier} and \texttt{Priority}. This predicate is re-executable
on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Priority} is neither a variable nor an operator priority} 
\ErrTerm{domain\_error(operator\_priority, Priority)}

\ErrCond{\texttt{OpSpecifier} is neither a variable nor an operator
specifier}
\ErrTerm{domain\_error(operator\_specifier, OpSpecifier)}

\ErrCond{\texttt{Operator} is neither a variable nor an atom} 
\ErrTerm{type\_error(atom, Operator)}

\end{PlErrors}

\Portability

ISO predicate. 

\subsubsection{\texttt{char\_conversion/2}}
\label{char-conversion/2}

\begin{TemplatesOneCol}
char\_conversion(+character, +character)

\end{TemplatesOneCol}

\Description

\IdxPBD[char\_conversion/2]{char\_conversion(InChar, OutChar)} alters the character-conversion
mapping. This mapping is used by the following read predicates:
\IdxPB{read\_term/3} \RefSP{read-term/3}, \IdxPB{read\_atom/2},
\IdxPB{read\_integer/2}, \IdxPB{read\_number/2} \RefSP{read-atom/2} and
\IdxPB{read\_token/2} \RefSP{read-token/2} to replace any occurrence of a
character \texttt{InChar} by \texttt{OutChar}. However the conversion
mechanism should have been previously activated by switching on the
\IdxPF{char\_conversion} \Idx{Prolog flag} \RefSP{set-prolog-flag/2}. When
\texttt{InChar} and \texttt{OutChar} are the same, the effect is to remove
any conversion of a character \texttt{InChar}.

Note that the single character read predicates (e.g. \texttt{get\_char/2})
never do character conversion. If such behavior is required, it must be
explicitly done using \texttt{current\_char\_conversion/2}
\RefSP{current-char-conversion/2}.

\begin{PlErrors}

\ErrCond{\texttt{InChar} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{OutChar} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{InChar} is neither a variable nor a character}
\ErrTerm{type\_error(character, InChar)}

\ErrCond{\texttt{OutChar} is neither a variable nor a character}
\ErrTerm{type\_error(character, OutChar)}

\end{PlErrors}

\Portability

ISO predicate. The \texttt{type\_error(character,\ldots)} is a GNU Prolog
behavior, the ISO reference instead defines a
\texttt{representation\_error(character)} in this case. This seems to be an
error of the ISO reference since, for many other built-in predicates
accepting a character (e.g. \texttt{char\_code/2}, \texttt{put\_char/2}), a
\texttt{type\_error} is raised. 

The ISO reference implies that if a program calls
\texttt{current\_char\_conversion/2}, then modifies the character mapping by
calling \texttt{char\_conversion/2}, and backtracks into the call to
\texttt{current\_char\_conversion/2} then the changes are guaranteed not to
affect that \texttt{current\_char\_conversion/2} goal. This is not guaranteed
by GNU Prolog.

\subsubsection{\texttt{current\_char\_conversion/2}}
\label{current-char-conversion/2}

\begin{TemplatesOneCol}
current\_char\_conversion(?character, ?character)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_char\_conversion/2]{current\_char\_conversion(InChar, OutChar)} succeeds if the
conversion of \texttt{InChar} is \texttt{OutChar} according to the
character-conversion mapping. In that case, \texttt{InChar} and
\texttt{OutChar} are different. This predicate is re-executable on
backtracking.

\begin{PlErrors}

\ErrCond{\texttt{InChar} is neither a variable nor a character}
\ErrTerm{type\_error(character, InChar)}

\ErrCond{\texttt{OutChar} is neither a variable nor a character}
\ErrTerm{type\_error(character, OutChar)}

\end{PlErrors}

\Portability

ISO predicate. Same remark as for char\_conversion/2
\RefSP{char-conversion/2}.

\subsection{Input/output from/to constant terms}
\label{Input/output-from/to-constant-terms}
These built-in predicates enable a Prolog term to be input from or output to
a Prolog constant term (atom, character list or character code list). All
these predicates can be defined using constant term streams
\RefSP{Constant-term-streams}. They are however simpler to use.

\subsubsection{\texttt{read\_term\_from\_atom/3},
\texttt{read\_from\_atom/2},
\texttt{read\_token\_from\_atom/2}}
\label{read-term-from-atom/3}

\begin{TemplatesOneCol}
read\_term\_from\_atom(+atom ?term, +read\_option\_list)\\
read\_from\_atom(+atom, ?term)\\
read\_token\_from\_atom(+atom, ?nonvar)

\end{TemplatesOneCol}

\Description

\IdxPBD[read\_term\_from\_atom/3]{}%
\IdxPBD[read\_from\_atom/2]{}%
\IdxPBD[read\_token\_from\_atom/2]{}%
Like \IdxPB{read\_term/3}, \IdxPB{read/2} \RefSP{read-term/3} and
\IdxPB{read\_token/2} \RefSP{read-token/2} except that characters are not
read from a text-stream but from \texttt{Atom}; the atom given as first
argument.

\begin{PlErrors}

\ErrCond{\texttt{Atom} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{see associated predicate errors}
\ErrTermRm{\RefSP{read-term/3} and \RefSP{read-token/2}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{read\_term\_from\_chars/3},
\texttt{read\_from\_chars/2},
\texttt{read\_token\_from\_chars/2}}

\begin{TemplatesOneCol}
read\_term\_from\_chars(+character\_list ?term,
+read\_option\_list)\\
read\_from\_chars(+character\_list, ?term)\\
read\_token\_from\_chars(+character\_list, ?nonvar)

\end{TemplatesOneCol}

\Description

\IdxPBD[read\_term\_from\_chars/3]{}%
\IdxPBD[read\_from\_chars/2]{}%
\IdxPBD[read\_token\_from\_chars/2]{}%
Like \IdxPB{read\_term/3}, \IdxPB{read/2} \RefSP{read-term/3} and
\IdxPB{read\_token/2} \RefSP{read-token/2} except that characters are not
read from a text-stream but from \texttt{Chars}; the character list given as
first argument.

\begin{PlErrors}

\ErrCond{\texttt{Chars} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Chars} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Chars)}

\ErrCond{an element \texttt{E} of the \texttt{Chars} list is neither a
variable nor a character}
\ErrTerm{type\_error(character, E)}

\ErrCond{see associated predicate errors}
\ErrTermRm{\RefSP{read-term/3} and \RefSP{read-token/2}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{read\_term\_from\_codes/3},
\texttt{read\_from\_codes/2},
\texttt{read\_token\_from\_codes/2}}

\begin{TemplatesOneCol}
read\_term\_from\_codes(+character\_code\_list ?term,
+read\_option\_list)\\
read\_from\_codes(+character\_code\_list, ?term)\\
read\_token\_from\_codes(+character\_code\_list, ?nonvar)

\end{TemplatesOneCol}

\Description

\IdxPBD[read\_term\_from\_codes/3]{}%
\IdxPBD[read\_from\_codes/2]{}%
\IdxPBD[read\_token\_from\_codes/2]{}%
Like \IdxPB{read\_term/3}, \IdxPB{read/2} \RefSP{read-term/3} and
\IdxPB{read\_token/2} \RefSP{read-token/2} except that characters are not
read from a text-stream but from \texttt{Codes}; the character code list
given as first argument.

\begin{PlErrors}

\ErrCond{\texttt{Codes} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Codes} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{an element \texttt{E} of the \texttt{Codes} list is neither a
variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{an element \texttt{E} of the \texttt{Codes} list is an integer but
not a character code}
\ErrTerm{representation\_error(character\_code, E)}

\ErrCond{see associated predicate errors}
\ErrTermRm{\RefSP{read-term/3} and \RefSP{read-token/2}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{write\_term\_to\_atom/3},
\texttt{write\_to\_atom/2},
\texttt{writeq\_to\_atom/2}, \\
\texttt{write\_canonical\_to\_atom/2},
\texttt{display\_to\_atom/2}, 
\texttt{print\_to\_atom/2}, \\
\texttt{format\_to\_atom/3}} 

\begin{TemplatesOneCol}
write\_term\_to\_atom(?atom, ?term, +write\_option\_list)\\
write\_to\_atom(?atom, ?term)\\
writeq\_to\_atom(?atom, ?term)\\
write\_canonical\_to\_atom(?atom, ?term)\\
display\_to\_atom(?atom, ?term)\\
print\_to\_atom(?atom, ?term)\\
format\_to\_atom(?atom, +character\_code\_list\_or\_atom, +list)

\end{TemplatesOneCol}

\Description

\IdxPBD[write\_term\_to\_atom/3]{}%
\IdxPBD[write\_to\_atom/2]{}%
\IdxPBD[writeq\_to\_atom/2]{}%
\IdxPBD[write\_canonical\_to\_atom/2]{}%
\IdxPBD[display\_to\_atom/2]{}%
\IdxPBD[print\_to\_atom/2]{}%
\IdxPBD[format\_to\_atom/3]{}%
Similar to \IdxPB{write\_term/3}, \IdxPB{write/2}, \IdxPB{writeq/2},
\IdxPB{write\_canonical/2}, \IdxPB{display/2}, \IdxPB{print/2}
\RefSP{write-term/3} and \IdxPB{format/3} \RefSP{format/3} except that
characters are not written onto a text-stream but are collected as an atom
which is then unified with the first argument \texttt{Atom}.

\begin{PlErrors}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{see associated predicate errors}
\ErrTermRm{\RefSP{write-term/3} and \RefSP{format/3}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{write\_term\_to\_chars/3},
\texttt{write\_to\_chars/2},
\texttt{writeq\_to\_chars/2}, \\
\texttt{write\_canonical\_to\_chars/2}, 
\texttt{display\_to\_chars/2},
\texttt{print\_to\_chars/2}, \\
\texttt{format\_to\_chars/3}} 

\begin{TemplatesOneCol}
write\_term\_to\_chars(?character\_list, ?term, +write\_option\_list)\\
write\_to\_chars(?character\_list, ?term)\\
writeq\_to\_chars(?character\_list, ?term)\\
write\_canonical\_to\_chars(?character\_list, ?term)\\
display\_to\_chars(?character\_list, ?term)\\
print\_to\_chars(?character\_list, ?term)\\
format\_to\_chars(?character\_list, +character\_code\_list\_or\_atom, +list)

\end{TemplatesOneCol}

\Description

\IdxPBD[write\_term\_to\_chars/3]{}%
\IdxPBD[write\_to\_chars/2]{}%
\IdxPBD[writeq\_to\_chars/2]{}%
\IdxPBD[write\_canonical\_to\_chars/2]{}%
\IdxPBD[display\_to\_chars/2]{}%
\IdxPBD[print\_to\_chars/2]{}%
\IdxPBD[format\_to\_chars/3]{}%
Similar to \IdxPB{write\_term/3}, \IdxPB{write/2}, \IdxPB{writeq/2},
\IdxPB{write\_canonical/2}, \IdxPB{display/2}, \IdxPB{print/2}
\RefSP{write-term/3} and \IdxPB{format/3} \RefSP{format/3} except that
characters are not written onto a text-stream but are collected as a
character list which is then unified with the first argument \texttt{Chars}.

\begin{PlErrors}

\ErrCond{\texttt{Chars} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Chars)}

\ErrCond{see associated predicate errors}
\ErrTermRm{\RefSP{write-term/3} and \RefSP{format/3}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{write\_term\_to\_codes/3},
\texttt{write\_to\_codes/2},
\texttt{writeq\_to\_codes/2}, \\
\texttt{write\_canonical\_to\_codes/2},
\texttt{display\_to\_codes/2},
\texttt{print\_to\_codes/2}, \\
\texttt{format\_to\_codes/3}}

\begin{TemplatesOneCol}
write\_term\_to\_codes(?character\_code\_list, ?term, +write\_option\_list)\\
write\_to\_codes(?character\_code\_list, ?term)\\
writeq\_to\_codes(?character\_code\_list, ?term)\\
write\_canonical\_to\_codes(?character\_code\_list, ?term)\\
display\_to\_codes(?character\_code\_list, ?term)\\
print\_to\_codes(?character\_code\_list, ?term)\\
format\_to\_codes(?character\_code\_list, +character\_code\_list\_or\_atom,
+list)

\end{TemplatesOneCol}

\Description

\IdxPBD[write\_term\_to\_codes/3]{}%
\IdxPBD[write\_to\_codes/2]{}%
\IdxPBD[writeq\_to\_codes/2]{}%
\IdxPBD[write\_canonical\_to\_codes/2]{}%
\IdxPBD[display\_to\_codes/2]{}%
\IdxPBD[print\_to\_codes/2]{}%
\IdxPBD[format\_to\_codes/3]{}%
Similar to \IdxPB{write\_term/3}, \IdxPB{write/2}, \IdxPB{writeq/2},
\IdxPB{write\_canonical/2}, \IdxPB{display/2}, \IdxPB{print/2}
\RefSP{write-term/3} and \IdxPB{format/3} \RefSP{format/3} except that
characters are not written onto a text-stream but are collected as a
character code list which is then unified with the first argument
\texttt{Codes}.

\begin{PlErrors}

\ErrCond{\texttt{Codes} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{see associated predicate errors}
\ErrTermRm{\RefSP{write-term/3} and \RefSP{format/3}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsection{DEC-10 compatibility input/output}

\subsubsection{Introduction}
The DEC-10 Prolog I/O predicates manipulate streams implicitly since they
only refer to current input/output streams \RefSP{Introduction:(Streams)}.
The current input and output streams are initially set to
\IdxPK{user\_input} and \IdxPK{user\_output} respectively. The predicate
\texttt{see/1}
(resp. \texttt{tell/1}, \texttt{append/1}) can be used for setting the
current input (resp. output) stream to newly opened streams for
particular files. The predicate \texttt{seen/0}
(resp. \texttt{told/0}) close the current input (resp. output) stream,
and resets it to the standard input (resp. output). The predicate
\texttt{seeing/1} (resp. \texttt{telling/1}) is used for retrieving
the file name associated with the current input (resp. output)
stream. The file name \IdxPKD{user} stands for the standard input or
output, depending on context (\IdxPK{user\_input} and
\IdxPK{user\_output} can also be used). The DEC-10 Prolog I/O predicates
are only provided for compatibility, they are now obsolete and
their use is discouraged. The predicates for explicit stream manipulation
should be used instead \RefSP{Streams}.

\subsubsection{\texttt{see/1},
\texttt{tell/1},
\texttt{append/1}}

\begin{TemplatesOneCol}
see(+source\_sink)\\
see(+stream)\\
tell(+source\_sink)\\
tell(+stream)\\
append(+source\_sink)\\
append(+stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[see/1]{see(FileName)} sets the current input stream to \texttt{FileName}.
If there is a stream opened by \texttt{see/1} associated with the same
\texttt{FileName} already, then it becomes the current input stream.
Otherwise, \texttt{FileName} is opened for reading and becomes the current
input stream.

\IdxPBD[tell/1]{tell(FileName)} sets the current output stream to \texttt{FileName}.
If there is a stream opened by \texttt{tell/1} associated with the same
\texttt{FileName} already, then it becomes the current output stream.
Otherwise, \texttt{FileName} is opened for writing and becomes the current
output stream.

\IdxPBD[append/1]{append(FileName)} like \texttt{tell/1} but
\texttt{FileName} is opened for writing + append.

A stream-term (obtained with any other built-in predicate) can also be
provided as \texttt{FileName} to these predicates.

\Errors

See errors associated to \texttt{open/4} \RefSP{open/4}.

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{seeing/1},
\texttt{telling/1}}

\begin{TemplatesOneCol}
seeing(?source\_sink)\\
telling(?source\_sink)

\end{TemplatesOneCol}

\Description

\IdxPBD[seeing/1]{seeing(FileName)} succeeds if \texttt{FileName} unifies
with the name of the current input file, if it was opened by
\texttt{see/1}; else with the current input stream-term, if this is not
\IdxPK{user\_input}, otherwise with
\IdxPK{user}. 

\IdxPBD[telling/1]{telling(FileName)} succeeds if \texttt{FileName} unifies with the
name of the current output file, if it was opened by \texttt{tell/1} or
\texttt{append/1}; else with the current output stream-term, if this is not
\IdxPK{user\_output}, otherwise with \IdxPK{user}. 

\PlErrorsNone

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{seen/0},
\texttt{told/0}}

\begin{TemplatesOneCol}
seen\\
told

\end{TemplatesOneCol}

\Description

\IdxPBD[seen/0]{seen} closes the current input, and resets it to
\IdxPK{user\_input}.

\IdxPBD[told/0]{told} closes the current output, and resets it to
\IdxPK{user\_output}.

\PlErrorsNone

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{get0/1},
\texttt{get/1},
\texttt{skip/1}}

\begin{TemplatesOneCol}
get0(?in\_character\_code)\\
get(?in\_character\_code)\\
skip(+character\_code)

\end{TemplatesOneCol}

\Description

\IdxPBD[get0/1]{get0(Code)} succeeds if \texttt{Code} unifies with the next
character code read from the current input stream. Thus it is equivalent to
\IdxPBD[get/1]{get\_code(Code)} \RefSP{get-char/2}.

\texttt{get(Code)} succeeds if \texttt{Code} unifies with the next character
code read from the current input stream that is not a layout character.

\IdxPBD[skip/1]{skip(Code)} skips just past the next character code \texttt{Code}
from the current input stream.

\Errors

See errors for \texttt{get\_code/2} \RefSP{get-char/2}.

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{put/1},
\texttt{tab/1}}

\begin{TemplatesOneCol}
put(+character\_code)\\
tab(+evaluable)

\end{TemplatesOneCol}

\Description

\IdxPBD[put/1]{put(Code)} writes the character whose code is \texttt{Code} onto the
current output stream. It is equivalent to \texttt{put\_code(Code)}
\RefSP{put-char/2}.

\IdxPBD[tab/1]{tab(N)} writes \texttt{N} spaces onto the current output
stream. \texttt{N} may be an arithmetic expression.

\Errors

See errors for \texttt{put\_code/2} \RefSP{put-char/2} and for arithmetic
expressions \RefSP{Evaluation-of-an-arithmetic-expression}.

\Portability

GNU Prolog predicates.

\subsection{Term expansion}
\label{Term-expansion}

\subsubsection{Definite clause grammars}
\label{DCG}
\index{Definite clause grammars|see {DCG}}

Definite clause grammars are a useful notation to express grammar rules.
However the ISO reference does not include them, so they should be considered
as a system dependent feature. Definite clause grammars are an extension of
context-free grammars. A grammar rule is of the form:

\OneLine{\textrm{head} \IdxPKD[(--{\gt})/2]{--{\gt}} \textrm{body}.}

\texttt{--{\gt}} is a predefined infix operator \RefSP{op/3:(Term-input/output)}.

Here are some features of definite clause grammars:

\begin{itemize}

\item a non-terminal symbol may be any callable term.

\item a terminal symbol may be any Prolog term and is written as a list. The
  empty list represents an empty sequence of terminals.

\item a sequence is expressed using the Prolog conjunction operator
  \texttt((',')/2).

\item the head of a grammar rule consists of a non-terminal optionally
  followed by a sequence of terminals (i.e. a Prolog list).

\item the body of a grammar rule consists of a sequence of non-terminals,
  terminals, predicate call, disjunction (using \texttt{;/2}), if-then (using
  \texttt{(-{\gt})/2}) or cut (using \texttt{!}).

\item a predicate call must be enclosed in curly brackets (using
  \texttt{{\lb}{\rb}/1}). This makes it possible to express an extra
  condition.

\end{itemize}

A grammar rule is nothing but a ``syntactic sugar'' for a Prolog clause. Each
grammar rule accepts as input a list of terminals (tokens), parses a prefix
of this list and gives as output the rest of this list (possibly enlarged).
This rest is generally parsed later. So, each a grammar rule is translated
into a Prolog clause that explicitly the manages the list. Two arguments
are then added: the input list (\texttt{Start}) and the output list
(\texttt{Stop}). For instance:

\OneLine{p --{\gt} q.}

is translated into:

\OneLine{p(Start, End) :- q(Start, End).}

Extra arguments can be provided and the body of the rule can contain several
non-terminals. Example:

\begin{Indentation}
\begin{verbatim}
p(X, Y) -->
        q(X),
        r(X, Y),
        s(Y).
\end{verbatim}
\end{Indentation}

is translated into:

\begin{Indentation}
\begin{verbatim}
p(X, Y, Start, End) :-
        q(X, Start, A),
        r(X, Y, A, B),
        s(Y, B, End).
\end{verbatim}
\end{Indentation}

Terminals are translated using unification:

\OneLine{assign(X,Y) --{\gt} left(X), [:=], right(Y), [;].}

is translated into:

\begin{Indentation}
\begin{verbatim}
assign(X,Y,Start,End) :-
        left(X, Start, A),
        A=[:=|B],
        right(Y, B, C),
        C=[;|End].
\end{verbatim}
\end{Indentation}

Terminals appearing on the left-hand side of a rule are connected to the
output argument of the head.

It is possible to include a call to a prolog predicate enclosing it in curly
brackets (to distinguish them from non-terminals):

\OneLine{assign(X,Y) --{\gt} left(X), [:=], right(Y0), {\lb}Y is Y0 {\rb},
[;].}

is translated into:

\begin{Indentation}
\begin{verbatim}
assign(X,Y,Start,End) :-
        left(X, Start, A),
        A=[:=|B],
        right(Y0, B, C),
        Y is Y0,
        C=[;|End].
\end{verbatim}
\end{Indentation}

Cut, disjunction and if-then(-else) are translated literally (and do not need
to be enclosed in curly brackets).

\subsubsection{\texttt{expand\_term/2},
\texttt{term\_expansion/2}}

\begin{TemplatesOneCol}
expand\_term(?term, ?term)\\
term\_expansion(?term, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[expand\_term/2]{expand\_term(Term1, Term2)} succeeds if
\texttt{Term2} is a transformation of \texttt{Term1}. The transformation
steps are as follows:

\begin{itemize}

\item if \texttt{Term1} is a variable, it is unified with \texttt{Term2}

\item if \texttt{term\_expansion(Term1, Term2)} succeeds \texttt{Term2} is
  assumed to be the transformation of \texttt{Term1}.

\item if \texttt{Term1} is a DCG then \texttt{Term2} is its translation
  \RefSP{DCG}.

\item otherwise \texttt{Term2} is unified with \texttt{Term1}.

\end{itemize}

\texttt{term\_expansion(Term1, Term2)} is a hook predicate allowing the user
to define a specific transformation. 

The GNU Prolog compiler \RefSP{The-GNU-Prolog-compiler} automatically calls
\texttt{expand\_term/2} on each \texttt{Term1} read in. However, in the
current release, only DCG transformation are done by the compiler (i.e.
\texttt{term\_expansion/2} cannot be used). To use
\texttt{term\_expansion/2}, it is necessary to call \texttt{expand\_term/2}
explicitly.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{phrase/3},
\texttt{phrase/2}}

\begin{TemplatesOneCol}
phrase(?term, ?list, ?list)\\
phrase(?term, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[phrase/3]{phrase(Phrase, List, Remainder)} succeeds if the list
\texttt{List} is in the language defined by the grammar rule body
\texttt{Phrase}. \texttt{Remainder} is what remains of the list after a
phrase has been found. 

\IdxPBD[phrase/2]{phrase(Phrase, List)} is equivalent to
\texttt{phrase(Phrase, List, [])}.

\begin{PlErrors}

\ErrCond{\texttt{List} is neither a list nor a partial list}
\ErrTerm{type\_error(list, List)}

\ErrCond{\texttt{Remainder} is neither a list nor a partial list}
\ErrTerm{type\_error(list, Remainder)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsection{Logic, control and exceptions}

\subsubsection{\texttt{abort/0},
\texttt{stop/0},
\texttt{top\_level/0},
\texttt{break/0},
\texttt{halt/1},
\texttt{halt/0}}
\label{abort/0}

\begin{TemplatesOneCol}
abort\\
stop\\
top\_level\\
break\\
halt(+integer)\\
halt

\end{TemplatesOneCol}

\Description

\IdxPBD[abort/0]{abort} aborts the current execution. If this execution was initiated
under a \Idx{top-level} the control is given back to the top-level and the
message \texttt{{\lb}execution aborted{\rb}} is displayed. Otherwise,
e.g. execution started by a \texttt{initialization/1} directive
\RefSP{initialization/1}, \texttt{abort/0} is equivalent to
\texttt{halt(1)} (see below).

\IdxPBD[stop/0]{stop} stops the current execution. If this execution was initiated
under a \Idx{top-level} the control is given back to the
top-level. Otherwise, \texttt{stop/0} is equivalent to \texttt{halt(0)}
(see below).

\IdxPBD[top\_level/0]{top\_level} starts a new recursive \Idx{top-level} (including the
banner display). To end this new \Idx{top-level} simply type the end-of-file
key sequence (\texttt{Ctl-D}) or its term representation:
\texttt{end\_of\_file.}

\IdxPBD[break/0]{break} invokes a recursive top-level (no banner is displayed). To
end this new level simply type the end-of-file key sequence (\texttt{Ctl-D})
or its term representation: \texttt{end\_of\_file.}

\IdxPBD[halt/1]{halt(Status)} causes the GNU Prolog process to immediately exit back to
the shell with the return code \texttt{Status}.

\IdxPBD[halt/0]{halt} is equivalent to \texttt{halt(0)}.

\begin{PlErrors}

\ErrCond{\texttt{Status} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Status} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Status)}

\end{PlErrors}

\Portability

\texttt{halt/1} and \texttt{halt/0} are ISO predicates. \texttt{abort/0},
\texttt{stop/0}, \texttt{top\_level/0} and \texttt{break/0} are GNU Prolog
predicates.

\subsubsection{\texttt{once/1}, \texttt{({\bs}+)/1} - not provable,
\texttt{call\_with\_args/1-11}, \texttt{call/2}}

\begin{TemplatesOneCol}
once(+callable\_term)\\
{\bs}+(+callable\_term) \\
call\_with\_args(+atom, +term,\ldots, +term)\\
call(+callable\_term, ?boolean)

\end{TemplatesOneCol}

\Description

\IdxPBD[once/1]{once(Goal)} succeeds if \texttt{call(Goal)} succeeds. However
\texttt{once/1} is not re-executable on backtracking since all alternatives
of \texttt{Goal} are cut. \texttt{once(Goal)} is equivalent to
\texttt{call(Goal), !}.

\IdxPBD[({\bs}+)/1]{{\bs}+ Goal} succeeds if \texttt{call(Goal)} fails and fails
otherwise. This built-in predicate gives negation by failure.

\IdxPBD[call\_with\_args/1-11]{call\_with\_args(Functor, Arg1,\ldots, ArgN)} calls the goal whose functor is \texttt{Functor} and whose arguments are \texttt{Arg1},\ldots, \texttt{ArgN} ($0 \leq \texttt{N} \leq 10$).

\IdxPBD[call/2]{call(Goal, Deterministic)} succeeds if \texttt{call(Goal)}
succeeds and unifies \texttt{Deterministic} with \texttt{true} if
\texttt{Goal} has not created any choice-points, with \texttt{false}
otherwise.

\texttt{{\bs}+} is a predefined prefix operator \RefSP{op/3:(Term-input/output)}.

\begin{PlErrors}

\ErrCond{\texttt{Goal} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Goal} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, Goal)}

\ErrCond{The predicate indicator \texttt{Pred} of \texttt{Goal} does not
correspond to an existing procedure and the value of the \texttt{unknown}
Prolog flag is \texttt{error} \RefSP{set-prolog-flag/2}}
\ErrTerm{existence\_error(procedure, Pred)}

\ErrCond{\texttt{Functor} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Functor} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Functor)}

\ErrCond{\texttt{Deterministic} is neither a variable nor a boolean}
\ErrTerm{type\_error(boolean, Deterministic)}

\end{PlErrors}

\Portability

\texttt{once/1} and \texttt{({\bs}+)/1} are ISO predicates, \texttt{call\_with\_args/1-11} and \texttt{call/2} are GNU Prolog predicates.

\subsubsection{\texttt{repeat/0}}

\begin{TemplatesOneCol}
repeat

\end{TemplatesOneCol}

\Description

\IdxPBD[repeat/0]{repeat} generates an infinite sequence of backtracking choices. The
purpose is to repeatedly perform some action on elements which are somehow
generated, e.g. by reading them from a stream, until some test becomes true.
Repeat loops cannot contribute to the logic of the program. They are only
meaningful if the action involves side-effects. The only reason for using
repeat loops instead of a more natural tail-recursive formulation is
efficiency: when the test fails back, the Prolog engine immediately reclaims
any working storage consumed since the call to \texttt{repeat/0}.

\PlErrorsNone

\Portability

ISO predicate. 

\subsubsection{\texttt{for/3}}

\begin{TemplatesOneCol}
for(?integer, +integer, +integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[for/3]{for(Counter, Lower, Upper)} generates an sequence of backtracking
choices instantiating \texttt{Counter} to the values \texttt{Lower},
\texttt{Lower+1},\ldots, \texttt{Upper}. 

\begin{PlErrors}

\ErrCond{\texttt{Counter} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Counter)}

\ErrCond{\texttt{Lower} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Lower} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Lower)}

\ErrCond{\texttt{Upper} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Upper} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Upper)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Atomic term processing}
These built-in predicates enable atomic terms to be processed as a sequence
of characters and character codes. Facilities exist to split and join atoms,
to convert a single character to and from the corresponding character code,
and to convert a number to and from a list of characters and character
codes.

\subsubsection{\texttt{atom\_length/2}}

\begin{TemplatesOneCol}
atom\_length(+atom, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[atom\_length/2]{atom\_length(Atom, Length)} succeeds if \texttt{Length} unifies with
the number of characters of the name of \texttt{Atom}.

\begin{PlErrors}

\ErrCond{\texttt{Atom} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Length} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Length)}

\ErrCond{\texttt{Length} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Length)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{atom\_concat/3}}

\begin{TemplatesOneCol}
atom\_concat(+atom, +atom, ?atom)\\
atom\_concat(?atom, ?atom, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[atom\_concat/3]{atom\_concat(Atom1, Atom2, Atom12)} succeeds if the name of
\texttt{Atom12} is the concatenation of the name of \texttt{Atom1} with the
name of \texttt{Atom1}. This predicate is re-executable on backtracking
(e.g. if \texttt{Atom12} is instantiated and both \texttt{Atom1} and
\texttt{Atom2} are variables).

\begin{PlErrors}

\ErrCond{\texttt{Atom1} and \texttt{Atom12} are variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom2} and \texttt{Atom12} are variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom1} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom1)}

\ErrCond{\texttt{Atom2} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom2)}

\ErrCond{\texttt{Atom12} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom12)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{sub\_atom/5}}

\begin{TemplatesOneCol}
sub\_atom(+atom, ?integer, ?integer, ?integer, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[sub\_atom/5]{sub\_atom(Atom, Before, Length, After, SubAtom)} succeeds if atom
\texttt{Atom} can be split into three atoms, \texttt{AtomL},
\texttt{SubAtom} and \texttt{AtomR} such that \texttt{Before} is the number
of characters of the name of \texttt{AtomL}, \texttt{Length} is the number
of characters of the name of \texttt{SubAtom} and \texttt{After} is the
number of characters of the name of \texttt{AtomR}. This predicate is
re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Atom} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{SubAtom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, SubAtom)}

\ErrCond{\texttt{Before} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Before)}

\ErrCond{\texttt{Length} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Length)}

\ErrCond{\texttt{After} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, After)}

\ErrCond{\texttt{Before} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Before)}

\ErrCond{\texttt{Length} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Length)}

\ErrCond{\texttt{After} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, After)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{char\_code/2}}
\label{char-code/2}

\begin{TemplatesOneCol}
char\_code(+character, ?character\_code)\\
char\_code(-character, +character\_code)

\end{TemplatesOneCol}

\Description

\IdxPBD[char\_code/2]{char\_code(Char, Code)} succeeds if the character code for the
one-char atom \texttt{Char} is \texttt{Code}.

\begin{PlErrors}

\ErrCond{\texttt{Char} and \texttt{Code} are variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char} is neither a variable nor a one-char atom}
\ErrTerm{type\_error(character, Char)}

\ErrCond{\texttt{Code} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Code)}

\ErrCond{\texttt{Code} is an integer but not a character code}
\ErrTerm{representation\_error(character\_code)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{lower\_upper/2}}

\begin{TemplatesOneCol}
lower\_upper(+character, ?character)\\
lower\_upper(-character, +character)

\end{TemplatesOneCol}

\Description

\IdxPBD[lower\_upper/2]{lower\_upper(Char1, Char2)} succeeds if \texttt{Char1} and
\texttt{Char2} are one-char atoms and if \texttt{Char2} is the upper
conversion of \texttt{Char1}. If \texttt{Char1} (resp. \texttt{Char2}) is a
character that is not a lower (resp. upper) letter then \texttt{Char2} is
equal to \texttt{Char1}.

\begin{PlErrors}

\ErrCond{\texttt{Char1} and \texttt{Char2} are variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Char1} is neither a variable nor a one-char atom}
\ErrTerm{type\_error(character, Char1)}

\ErrCond{\texttt{Char2} is neither a variable nor a one-char atom}
\ErrTerm{type\_error(character, Char2)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{atom\_chars/2},
\texttt{atom\_codes/2}}
\label{atom-chars/2}

\begin{TemplatesOneCol}
atom\_chars(+atom, ?character\_list)\\
atom\_chars(-atom, +character\_list)\\
atom\_codes(+atom, ?character\_code\_list)\\
atom\_codes(-atom, +character\_code\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[atom\_chars/2]{atom\_chars(Atom, Chars)} succeeds if \texttt{Chars}
is the list of one-char atoms whose names are the successive characters of
the name of \texttt{Atom}.

\IdxPBD[atom\_codes/2]{atom\_codes(Atom, Codes)} is similar to
\texttt{atom\_chars/2} but deals with a list of character codes.

\begin{PlErrors}

\ErrCond{\texttt{Atom} is a variable and \texttt{Chars} (or \texttt{Codes})
is a partial list or a list with an element which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Chars} is neither a list nor a partial list}
\ErrTerm{type\_error(list, Chars)}

\ErrCond{\texttt{Codes} is neither a list nor a partial list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{\texttt{Atom} is a variable and an element \texttt{E} of the list
\texttt{Chars} is neither a variable nor a one-char atom}
\ErrTerm{type\_error(character, E)}

\ErrCond{\texttt{Atom} is a variable and an element \texttt{E} of the list
\texttt{Codes} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{\texttt{Atom} is a variable and an element \texttt{E} of the list
\texttt{Codes} is an integer but not a character code}
\ErrTerm{representation\_error(character\_code)}

\end{PlErrors}

\Portability

ISO predicates. The ISO reference only causes a \texttt{type\_error(list,
Chars)} if \texttt{Atom} is a variable and \texttt{Chars} is neither a list
nor a partial list. GNU Prolog always checks if \texttt{Chars} is a list.
Similarly for \texttt{Codes}. The \texttt{type\_error(integer, E)} when an
element \texttt{E} of the \texttt{Codes} is not an integer is a GNU Prolog
extension. This seems to be an omission in the ISO reference since this
error is detected for many other built-in predicates accepting a character
code (e.g. \texttt{char\_code/2}, \texttt{put\_code/2}).

\subsubsection{\texttt{number\_atom/2},
\texttt{number\_chars/2},
\texttt{number\_codes/2}}
\label{number-atom/2}

\begin{TemplatesOneCol}
number\_atom(+number, ?atom)\\
number\_atom(-number, +atom)\\
number\_chars(+number, ?character\_list)\\
number\_chars(-number, +character\_list)\\
number\_codes(+number, ?character\_code\_list)\\
number\_codes(-number, +character\_code\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[number\_atom/2]{number\_atom(Number, Atom)} succeeds if
\texttt{Atom} is an atom whose name corresponds to the characters of
\texttt{Number}.

\IdxPBD[number\_chars/2]{number\_chars(Number, Chars)} is similar to
\texttt{number\_atom/2} but deals with a list of character codes.

\IdxPBD[number\_codes/2]{number\_codes(Number, Codes)} is similar to
\texttt{number\_atom/2} but deals with a list of characters.

\begin{PlErrors}

\ErrCond{\texttt{Number} and \texttt{Atom} are variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Number} is a variable and \texttt{Chars} (or
\texttt{Codes}) is a partial list or a list with an element which is a
variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Number} is neither a variable nor an number}
\ErrTerm{type\_error(number, Number)}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Number} is a variable and \texttt{Chars} is neither a list
nor a partial list}
\ErrTerm{type\_error(list, Chars)}

\ErrCond{\texttt{Number} is a variable and \texttt{Codes} is neither a list
nor a partial list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{\texttt{Number} is a variable and an element \texttt{E} of the list
\texttt{Chars} is neither a variable nor a one-char atom}
\ErrTerm{type\_error(character, E)}

\ErrCond{\texttt{Number} is a variable and an element \texttt{E} of the list
\texttt{Codes} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{\texttt{Number} is a variable and an element \texttt{E} of the list
\texttt{Codes} is an integer but not a character code}
\ErrTerm{representation\_error(character\_code)}

\ErrCond{\texttt{Number} is a variable, \texttt{Atom} (or \texttt{Chars} or
\texttt{Codes}) cannot be parsed as a number and the value of the
\texttt{syntax\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{syntax\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

\texttt{number\_atom/2} is a GNU Prolog predicate. \texttt{number\_chars/2}
and \texttt{number\_codes/2} are ISO predicates.

GNU Prolog only raises an error about an element \texttt{E} of the
\texttt{Chars} (or \texttt{Codes}) list when \texttt{Number} is a variable
while the ISO reference always check this. This seems an error since
the list itself is only checked if \texttt{Number} is a variable.

The \texttt{type\_error(integer, E)} when an element \texttt{E} of the
\texttt{Codes} is not an integer is a GNU Prolog extension. This seems to be
an omission in the ISO reference since this error is detected for many other
built-in predicates accepting a character code (e.g. \texttt{char\_code/2},
\texttt{put\_code/2}).

\subsubsection{\texttt{name/2}}

\begin{TemplatesOneCol}
name(+atomic, ?character\_code\_list)\\
name(-atomic, +character\_code\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[name/2]{name(Constant, Codes)} succeeds if \texttt{Codes} is a list whose
elements are the character codes corresponding to the successive characters
of \texttt{Constant} (a number or an atom). However, there atoms are for
which \texttt{name(Constant, Codes)} is true, but which will not be
constructed if \texttt{name/2} is called with \texttt{Constant}
uninstantiated, e.g. the atom \texttt{'1024'}. For this reason the use of
\texttt{name/2} is discouraged and should be limited to compatibility
purposes. It is preferable to use atom\_codes/2 \RefSP{atom-chars/2}
or number\_chars/2 \RefSP{number-atom/2}.

\begin{PlErrors}

\ErrCond{\texttt{Constant} is a variable and \texttt{Codes} is a partial
list or a list with an element which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Constant} is neither a variable nor an atomic term}
\ErrTerm{type\_error(atomic, Constant)}

\ErrCond{\texttt{Constant} is a variable and \texttt{Codes} is neither a list
nor a partial list}
\ErrTerm{type\_error(list, Codes)}

\ErrCond{\texttt{Constant} is a variable and an element \texttt{E} of the
list \texttt{Codes} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{\texttt{Constant} is a variable and an element \texttt{E} of the
list \texttt{Codes} is an integer but not a character code}
\ErrTerm{representation\_error(character\_code)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{atom\_hash/2}}
\label{atom-hash/2}

\begin{TemplatesOneCol}
atom\_hash(+atom, ?integer)\\
atom\_hash(?atom, +integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[atom\_hash/2]{atom\_hash(Atom, Hash)} succeeds if \texttt{Hash} is the internal
key associated to \texttt{Atom} (an existing atom). The internal key of an
atom is a unique integer $\geq$ 0 and $<$ to the \IdxPF{max\_atom}
\Idx{Prolog flag} \RefSP{set-prolog-flag/2}.

\begin{PlErrors}

\ErrCond{\texttt{Atom} and \texttt{Hash} are both variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Hash} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Hash)}

\ErrCond{\texttt{Hash} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Hash)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{new\_atom/3},
\texttt{new\_atom/2},
\texttt{new\_atom/1}}

\begin{TemplatesOneCol}
new\_atom(+atom, +integer, -atom)\\
new\_atom(+atom, -atom)\\
new\_atom(-atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[new\_atom/3]{new\_atom(Prefix, Hash, Atom)} unifies \texttt{Atom} with a new atom
whose name begins with the characters of the name of \texttt{Prefix} and
whose internal key is \texttt{Hash} \RefSP{atom-hash/2}. This predicate is
then a symbol generator. It is guaranteed that \texttt{Atom} does not exist
before the invocation of \texttt{new\_atom/3}. The characters appended to
\texttt{Prefix} to form \texttt{Atom} are in: \texttt{A}-\texttt{Z} (capital
letter), \texttt{a}-\texttt{z} (small letter), \texttt{0}-\texttt{9}
(digit), \texttt{\#}, \texttt{\$}, \texttt{\&}, \texttt{\_}, \texttt{@}.

\IdxPBD[new\_atom/2]{new\_atom/2} is similar to \texttt{new\_atom/3}, but the atom
generated can have any (free) internal key.

\IdxPBD[new\_atom/1]{new\_atom/1} is similar to \texttt{new\_atom(atom\_, Atom)}, i.e.
the generated atom begins with \texttt{atom\_}.

\begin{PlErrors}

\ErrCond{\texttt{Prefix} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Hash} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Prefix} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Prefix)}

\ErrCond{\texttt{Hash} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Hash)}

\ErrCond{\texttt{Hash} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Hash)}

\ErrCond{\texttt{Atom} is not a variable}
\ErrTerm{type\_error(variable, Atom)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{current\_atom/1}}
\label{current-atom/2}

\begin{TemplatesOneCol}
current\_atom(?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_atom/1]{current\_atom(Atom)} succeeds if there exists an atom that unifies
with \texttt{Atom}. All atoms are found except those beginning with a
\texttt{'\$'} (system atoms). This predicate is re-executable on
backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{atom\_property/2}}
\label{atom-property/2}

\begin{TemplatesOneCol}
atom\_property(?atom, ?atom\_property)

\end{TemplatesOneCol}

\Description

\IdxPBD[atom\_property/2]{atom\_property(Atom, Property)} succeeds if
\texttt{current\_atom(Atom)} succeeds \RefSP{current-atom/2} and if
\texttt{Property} unifies with one of the properties of the atom. This
predicate is re-executable on backtracking.

\SPart{Atom properties}:

\begin{itemize}

\item \IdxPPD[length]{length(Length)}: \texttt{Length} is the length of the
name of the atom.

\item \IdxPPD[hash]{hash(Hash)}: \texttt{Hash} is the internal key of the
atom \RefSP{atom-hash/2}.

\item \IdxPPD{prefix\_op}: if there is a prefix operator currently defined
with this name.

\item \IdxPPD{infix\_op}: if there is an infix operator currently defined
with this name.

\item \IdxPPD{postfix\_op}: if there is a postfix operator currently defined
with this name.

\item \IdxPPD{needs\_quotes}: if the atom must be quoted to be read later.

\item \IdxPPD{needs\_scan}: if the atom must be scanned when output to be
read later (e.g. contains special characters that must be output with a
\texttt{{\bs}} escape sequence).

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Atom} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Atom)}

\ErrCond{\texttt{Property} is neither a variable nor a n atom property term}
\ErrTerm{domain\_error(atom\_property, Property)}

\ErrCond{\texttt{Property} = \texttt{length(E)} or \texttt{hash(E)} and
\texttt{E} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{List processing}

These predicates manipulate lists. They are bootstrapped predicates (i.e.
written in Prolog) and no error cases are tested (for the moment). However,
since they are written in Prolog using other built-in predicates, some
errors can occur due to those built-in predicates.

\subsubsection{\texttt{append/3}}

\begin{TemplatesOneCol}
append(?list, ?list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[append/3]{append(List1, List2, List12)} succeeds if the concatenation of the
list \texttt{List1} and the list \texttt{List2} is the list \texttt{List12}.
This predicate is re-executable on backtracking (e.g. if \texttt{List12} is
instantiated and both \texttt{List1} and \texttt{List2} are variable).

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{member/2},
\texttt{memberchk/2}}

\begin{TemplatesOneCol}
member(?term, ?list)\\
memberchk(?term, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[member/2]{member(Element, List)} succeeds if \texttt{Element} belongs to the
\texttt{List}. This predicate is re-executable on backtracking and can be
thus used to enumerate the elements of \texttt{List}.

\IdxPBD[memberchk/2]{memberchk/2} is similar to \texttt{member/2} but only succeeds once.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{reverse/2}}

\begin{TemplatesOneCol}
reverse(?list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[reverse/2]{reverse(List1, List2)} succeeds if \texttt{List2} unifies with the
list \texttt{List1} in reverse order.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{delete/3},
\texttt{select/3}}

\begin{TemplatesOneCol}
delete(?list, ?term, ?list)\\
select(?term, ?list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[delete/3]{delete(List1, Element, List2)} removes all occurrences of
\texttt{Element} in \texttt{List1} to provide \texttt{List2}. A strict term
equality is required, cf. \IdxPB{(==)/2} \RefSP{(==)/2}.

\IdxPBD[select/3]{select(Element, List1, List2)} removes one occurrence of
\texttt{Element} in \texttt{List1} to provide \texttt{List2}. This predicate
is re-executable on backtracking.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{permutation/2}}

\begin{TemplatesOneCol}
permutation(?list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[permutation/2]{permutation(List1, List2)} succeeds if \texttt{List2}
is a permutation of the elements of \texttt{List1}. This predicate is
re-executable on backtracking.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{prefix/2},
\texttt{suffix/2}}

\begin{TemplatesOneCol}
prefix(?list, ?list)\\
suffix(?list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[prefix/2]{prefix(Prefix, List)} succeeds if \texttt{Prefix} is a prefix of
\texttt{List}. This predicate is re-executable on backtracking.

\IdxPBD[suffix/2]{suffix(Suffix, List)} succeeds if \texttt{Suffix} is a suffix of
\texttt{List}. This predicate is re-executable on backtracking.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{sublist/2}}

\begin{TemplatesOneCol}
sublist(?list, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[sublist/2]{sublist(List1, List2)} succeeds if \texttt{List2} is a sub-list of
\texttt{List1}. This predicate is re-executable on backtracking.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{last/2}}

\begin{TemplatesOneCol}
last(?list, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[last/2]{last(List, Element)} succeeds if \texttt{Element} is the last element
of \texttt{List}.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{length/2}}

\begin{TemplatesOneCol}
length(?list, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[length/2]{length(List, Length)} succeeds if \texttt{Length} is the length of
\texttt{List}.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{nth/3}}

\begin{TemplatesOneCol}
nth(+integer, ?list, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[nth/3]{nth(N, List, Element)} succeeds if the \texttt{N}\emph{th}
argument of \texttt{List} is \texttt{Element}.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{max\_list/2},
\texttt{min\_list/2},
\texttt{sum\_list/2}}

\begin{TemplatesOneCol}
min\_list(+list, ?number)\\
max\_list(+list, ?number)\\
sum\_list(+list, ?number)

\end{TemplatesOneCol}

\Description

\IdxPBD[min\_list/2]{min\_list(List, Min)} succeeds if \texttt{Min} is the
smallest number in \texttt{List}.

\IdxPBD[max\_list/2]{max\_list(List, Max)} succeeds if \texttt{Max} is the
largest number in \texttt{List}.

\IdxPBD[sum\_list/2]{sum\_list(List, Sum)} succeeds if \texttt{Sum} is the
sum of all the elements in \texttt{List}.

\texttt{List} must be a list of arithmetic evaluable terms
\RefSP{Evaluation-of-an-arithmetic-expression}.

\PlErrorsNone

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{sort/2},
\texttt{sort0/2},
\texttt{keysort/2}
\texttt{sort/1},
\texttt{sort0/1},
\texttt{keysort/1}}
\label{sort/2}

\begin{TemplatesOneCol}
sort(+list, ?list)\\
sort0(+list, ?list)\\
keysort(+list, ?list)\\
sort(+list)\\
sort0(+list)\\
keysort(+list)

\end{TemplatesOneCol}

\Description

\IdxPBD[sort/2]{sort(List1, List2)} succeeds if \texttt{List2} is the
sorted list corresponding to \texttt{List1} where duplicate elements are
merged.

\IdxPBD{sort0/2} is similar to \texttt{sort/2} except that duplicate elements
are not merged.

\IdxPBD[keysort/2]{keysort(List1, List2)} succeeds if \texttt{List2} is the
sorted list of \texttt{List1} according to the keys. The list \texttt{List1}
consists of items of the form \texttt{Key-Value}. These items are sorted
according to the value of \texttt{Key} yielding the \texttt{List2}. Duplicate
keys are not merged. This predicate is stable, i.e. if \texttt{K-A} occurs
before \texttt{K-B} in the input, then \texttt{K-A} will occur before
\texttt{K-B} in the output.

\IdxPBD{sort/1}, \IdxPBD{sort0/1} and \IdxPBD{keysort/1} are similar to
\texttt{sort/2}, \texttt{sort0/2} and \texttt{keysort/2} but achieve a sort
in-place destructing the original \texttt{List1} (this in-place assignment is
not undone at backtracking). The sorted list occupies the same memory space
as the original list (saving thus memory consumption).

The time complexity of these sorts is $O(N~log~N)$, $N$ being the length of
the list to sort.

These predicates refer to the standard ordering of terms
\RefSP{Standard-total-ordering-of-terms}. 

\begin{PlErrors}

\ErrCond{\texttt{List1} is a partial list}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{List1} is neither a partial list nor a list}
\ErrTerm{type\_error(list, List1)}

\ErrCond{\texttt{List2} is neither a partial list nor a list}
\ErrTerm{type\_error(list, List2)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsection{Global variables}
\label{Global-variables}

GNU Prolog provides a simple and powerful way to assign and read global
variables. There are 3 kinds of objects which can be associated to a global
variable:

\begin{itemize}

\item a copy of a term (the assignment can be made backtrackable or not).

\item a link to a term.

\item an array of objects.

\end{itemize}

The initial value of a global variable is the integer 0. A global variable
is referenced by a name (i.e. name = an atom) possibly indexed if it is an
array (i.e. name = a compound term). In the following, \Param{GVarName}
represents such a reference to a global variable and its syntax is as
follows:

\begin{Indentation}
\begin{tabular}{@{}lll}
\Param{GVarName} & ::= & \Param{atom} \\
                 &     & \Param{atom}\texttt{(}\Param{Index}\texttt{,}\ldots\texttt{,}\Param{Index}\texttt{)} \\
\Param{Index}    & ::= & \Param{integer} \\
                 &     & \Param{GVarName}
\end{tabular}
\end{Indentation}

When a \Param{GVarName} is used as an index, the value of this variable
must be an integer. Indexes range from 0 to \Param{Size}-1 if the array has
\Param{Size} elements. The space necessary for copies and arrays are
dynamically allocated and recovered as soon as possible. For instance, when
an atom is associated to a global variable whose current value is an array,
the space for this array is recovered (unless the assignment is to be undone
when backtracking occurs).

\SPart{Arrays}: the predicates \texttt{g\_assign/2}, \texttt{g\_assignb/2}
and \texttt{g\_link/2} \RefSP{g-assign/2} define an array when the
assigned value is a compound term with principal functor \IdxPGD{g\_array}.
Then an array is assigned to \Param{GVarName}. There are 3 forms for the
term \texttt{g\_array}:

\begin{itemize}

\item \texttt{g\_array(Size)}: if \texttt{Size} is an integer 
$>$ 0 then defines an array of \texttt{Size} elements which are all
initialized with the integer \texttt{0}.

\item \texttt{g\_array(Size, Initial)}: as above but the elements are
initialized with the term \texttt{Initial} instead of 0. \texttt{Initial}
can contain other array definitions allowing thus for multi-dimensional
arrays. Some examples are presented later \RefSP{Examples}. 

\item \texttt{g\_array(List)}: as above if \texttt{List} is a list of length
\texttt{Size} except that the elements of the array are initialized
according to the elements of \texttt{List} (which can contain other array
definitions). 

\end{itemize}

The compound term with principal functor \IdxPGD{g\_array\_extend} can be
used instead of \texttt{g\_array} to modify the structure of a (possibly)
existing array. In that case, the existing elements of the array are not
initialized.

When an array is read, a term of the form \texttt{g\_array([Elem0,...,
ElemSize-1])} is returned.

\subsubsection{\texttt{g\_assign/2},
\texttt{g\_assignb/2},
\texttt{g\_link/2}}
\label{g-assign/2}

\begin{TemplatesOneCol}
g\_assign(+callable\_term, ?term)\\
g\_assignb(+callable\_term, ?term)\\
g\_link(+callable\_term, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[g\_assign/2]{g\_assign(GVarName, Value)} assigns a copy of the term
\texttt{Value} to \texttt{GVarName}. This assignment is not undone when
backtracking occurs.

\IdxPBD[g\_assignb/2]{g\_assignb/2} is similar to \texttt{g\_assign/2} but the assignment
is undone at backtracking.

\IdxPBD[g\_link/2]{g\_link(GVarName, Value)} makes a link between \texttt{GVarName} to
the term \texttt{Value}. This allows the user to give a name to any Prolog
term (in particular non-ground terms). Such an assignment is always undone
when backtracking occurs (since the term may no longer exist). If
\texttt{Value} is an atom or an integer, \texttt{g\_link/2} and
\texttt{g\_assignb/2} have the same behavior. Since \texttt{g\_link/2} only
handles links to existing terms it does not require extra memory space and
is not expensive in terms of execution time.

\begin{PlErrors}

\ErrCond{\texttt{GVarName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{GVarName} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, GVarName)}

\ErrCond{\texttt{GVarName} is a compound term and a sub-argument \texttt{E}
is not a valid index \RefSP{Global-variables}}
\ErrTerm{domain\_error(g\_array\_index, E)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{g\_read/2}}

\begin{TemplatesOneCol}
g\_read(+callable\_term, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[g\_read/2]{g\_read(GVarName, Value)} unifies \texttt{Value} with the term
assigned to \texttt{GVarName}.

\begin{PlErrors}

\ErrCond{\texttt{GVarName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{GVarName} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, GVarName)}

\ErrCond{\texttt{GVarName} is a compound term and a sub-argument \texttt{E}
is not a valid index \RefSP{Global-variables}}
\ErrTerm{domain\_error(g\_array\_index, E)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{g\_array\_size/2}}

\begin{TemplatesOneCol}
g\_array\_size(+callable\_term, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[g\_array\_size/2]{g\_array\_size(GVarName, Value)} unifies \texttt{Size} with the
dimension (an integer $>$ 0) of the array assigned to \texttt{GVarName}.
Fails if \texttt{GVarName} is not an array.

\begin{PlErrors}

\ErrCond{\texttt{GVarName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{GVarName} is neither a variable nor a callable term}
\ErrTerm{type\_error(callable, GVarName)}

\ErrCond{\texttt{GVarName} is a compound term and a sub-argument \texttt{E}
is not a valid index \RefSP{Global-variables}}
\ErrTerm{domain\_error(g\_array\_index, E)}

\ErrCond{\texttt{Size} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Size)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{Examples}
\label{Examples}

\SPart{A simple counter}: the following predicate defines a counter using a
global variable:

\begin{Indentation}
\begin{verbatim}
inc(Var, Value) :-
        g_read(Var, Value),
        X is Value+1,
        g_assign(Var, X).
\end{verbatim}
\end{Indentation}

The query: \texttt{inc(c, X)} will succeed unifying \texttt{X} with
\texttt{0}, another call to \texttt{inc(a, Y)} will then unify \texttt{Y}
with \texttt{1}, and so on.

\SPart{Difference between \texttt{g\_assign/2} and \texttt{g\_assignb/2}}:
\texttt{g\_assign/2} does not undo its assignment when backtracking occurs
whereas \texttt{g\_assignb/2} undoes it.

\begin{Code}
\begin{tabular}{@{}p{6cm}@{\quad}l@{}}
test(Old) :-                 & testb(Old) :- \\                  
~~~~~~~~g\_assign(x,1),      & ~~~~~~~~g\_assign(x,1), \\        
~~~~~~~~(~~~g\_read(x, Old), & ~~~~~~~~(~~~g\_read(x, Old), \\   
~~~~~~~~~~~~\textit{g\_assign}(x, 2)  & ~~~~~~~~~~~~\textit{g\_assignb}(x, 2) \\
~~~~~~~~;~~~g\_read(x,~Old), & ~~~~~~~~;~~~g\_read(x, Old), \\   
~~~~~~~~~~~~g\_assign(x, 3)  & ~~~~~~~~~~~~g\_assign(x, 3) \\    
~~~~~~~~).                   & ~~~~~~~~).                  \\
\end{tabular}
\end{Code}

The query \texttt{test(Old)} will succeed unifying \texttt{Old} with
\texttt{1} and on backtracking with \texttt{2} (i.e. the assignment of the
value \texttt{2} has not been undone). The query \texttt{testb(Old)} will
succeed unifying \texttt{Old} with \texttt{1} and on backtracking with
\texttt{1} (i.e. the assignment of the value \texttt{2} has been undone). 

\SPart{Difference between \texttt{g\_assign/2} and \texttt{g\_link/2}}:
\texttt{g\_assign/2} (and \texttt{g\_assignb/2}) creates a copy of the term
whereas \texttt{g\_link/2} does not. \texttt{g\_link/2} can be used to avoid
passing big data structures (e.g. dictionaries,\ldots) as arguments to
predicates.

\begin{Code}
\begin{tabular}{@{}p{6cm}@{\quad}l@{}}
test(B) :-                  & test(B) :-                \\
~~~~~~~~\textit{g\_assign}(b, f(X)), & ~~~~~~~~\textit{g\_link}(b, f(X)), \\ 
~~~~~~~~X=12,               & ~~~~~~~~X=12,             \\
~~~~~~~~g\_read(b, B).      & ~~~~~~~~g\_read(b, B).    \\
\end{tabular}
\end{Code}

The query \texttt{test(B)} will succeed unifying \texttt{B} with
\texttt{f(\_)} (\texttt{g\_assign/2} assigns a copy of the value). The query
\texttt{testl(B)} will succeed unifying \texttt{B} with \texttt{f(12)}
(\texttt{g\_link/2} assigns a pointer to the term). 

\SPart{Simple array definition}: here are some queries to show how arrays
can be handled:

\begin{Indentation}
\begin{verbatim}
| ?- g_assign(w, g_array(3)), g_read(w, X).

X = g_array([0,0,0])

| ?- g_assign(w(0), 16), g_assign(w(1), 32), g_assign(w(2), 64), g_read(w, X).

X = g_array([16,32,64])
\end{verbatim}
\end{Indentation}

this is equivalent to:

\begin{Indentation}
\begin{verbatim}
| ?- g_assign(k, g_array([16,32,64])), g_read(k, X).

X = g_array([16,32,64])

| ?- g_assign(k, g_array(3,null)), g_read(k, X), g_array_size(k, S).

S = 3
X = g_array([null,null,null])
\end{verbatim}
\end{Indentation}

\SPart{2-D array definition}:

\begin{Indentation}
\begin{verbatim}
| ?- g_assign(w, g_array(2, g_array(3))), g_read(w, X).

X = g_array([g_array([0,0,0]),g_array([0,0,0])])

| ?- (   for(I,0,1), for(J,0,2), K is I*3+J, g_assign(w(I,J), K),
         fail
     ;   g_read(w, X)
     ).

X = g_array([g_array([0,1,2]),g_array([3,4,5])])

| ?- g_read(w(1),X).

X = g_array([3,4,5])
\end{verbatim}
\end{Indentation}

\SPart{Hybrid array}:

\begin{Indentation}
\begin{verbatim}
| ?- g_assign(w,g_array([1,2,g_array([a,b,c]), g_array(2,z),5])), g_read(w, X).

X = g_array([1,2,g_array([a,b,c]), g_array([z,z]),5])

| ?- g_read(w(1), X), g_read(w(2,1), Y), g_read(w(3,1), Z).

X = 2
Y = b
Z = z

| ?- g_read(w(1,2),X).

{exception: error(domain_error(g_array_index,w(1,2)),g_read/2)}
\end{verbatim}
\end{Indentation}

\SPart{Array extension}:

\begin{Indentation}
\begin{verbatim}
| ?- g_assign(a, g_array([10,20,30])), g_read(a, X).

X = g_array([10,20,30])

| ?- g_assign(a, g_array_extend(5,null)), g_read(a, X).

X = g_array([10,20,30,null,null])

| ?- g_assign(a, g_array([10,20,30])), g_read(a, X).

X = g_array([10,20,30])

| ?- g_assign(a, g_array_extend([1,2,3,4,5,6])), g_read(a, X).

X = g_array([10,20,30,4,5,6])
\end{verbatim}
\end{Indentation}

\subsection{Prolog state} 

\subsubsection{\texttt{set\_prolog\_flag/2}}
\label{set-prolog-flag/2}

\begin{TemplatesOneCol}
set\_prolog\_flag(+flag, +term)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_prolog\_flag/2]{set\_prolog\_flag(Flag, Value)} sets the value
of the \IdxD{Prolog flag} \texttt{Flag} to \texttt{Value}.

\index{flag|see {Prolog flag}}
\SPart{Prolog flags}: a Prolog flag is an atom
which is associated with a value that is either implementation defined
or defined by the user. Each flag has a permitted range of values; any
other value is a \texttt{domain\_error}. The following two tables
present available flags, the possible values, a description and if
they are ISO or an extension. The first table presents unchangeable
flags while the second one the changeable flags. For flags whose
default values is machine independent, this value is
\underline{underlined}.

\SPart{Unchangeable flags}:

\begin{tabular}{|L{4.5cm}|C{2.2cm}|L{6.5cm}|C{0,6cm}|}
\hline

Flag & Values & Description & ISO \\

\hline\hline

\IdxPFD{bounded} & \texttt{\underline{true}} / \texttt{false} & are integers
bounded ? & Y \\

\hline

\IdxPFD{max\_integer} & an integer & greatest integer & Y \\

\hline

\IdxPFD{min\_integer} & an integer & smallest integer & Y \\

\hline

\IdxPFD{integer\_rounding\_function} & \texttt{toward\_zero}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

\texttt{down} & 
\texttt{\textit{rnd}(X)} = integer part of \texttt{X}

%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%
\texttt{\textit{rnd}(X)} = $\lfloor$\texttt{X$\rfloor$}
\RefSP{Evaluation-of-an-arithmetic-expression} & Y \\

\hline

\IdxPFD{max\_arity} & an integer & maximum arity for compound terms (255) &
Y \\

\hline

\IdxPFD{max\_atom} & an integer & maximum number of atoms & N \\

\hline

\IdxPFD{max\_stream} & an integer & maximum number of streams & N \\

\hline

\IdxPFD{max\_unget} & an integer & maximum number of successive ungets & N
\\

\hline

\IdxPFD{prolog\_name} & an atom &  name of the Prolog system & N \\

\hline

\IdxPFD{prolog\_version} & an atom & version number of the Prolog system & N
\\

\hline

\IdxPFD{prolog\_date} & an atom & date of the Prolog system & N \\

\hline

\IdxPFD{prolog\_copyright} & an atom &  copyright message of the Prolog
system & N \\ 

\hline
\end{tabular}

\SPart{Changeable flags}:

\begin{tabular}{|L{4.5cm}|C{2.2cm}|L{6.5cm}|C{0,6cm}|}
\hline

Flag & Values & Description & ISO \\

\hline\hline

\IdxPFD{char\_conversion} & \texttt{on} / \texttt{\underline{off}} & is
character conversion activated ? & Y \\

\hline

\IdxPFD{debug} & \texttt{on} / \texttt{\underline{off}} & is the debugger
activated ? & Y \\

\hline

\IdxPFD{singleton\_warning} & \texttt{\underline{on}} / \texttt{off} & warn
about named singleton variables ? & N \\ 

\hline

\IdxPFD{strict\_iso} & \texttt{\underline{on}} / \texttt{off} & strict ISO
behavior ? & N \\

\hline

~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

\IdxPFD{double\_quotes} &
  ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{atom}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{chars}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{\underline{codes}} &
    a double quoted constant is returned as:
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    an atom
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a list of characters
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a list of character codes &
      ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

      Y \\

\hline

~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

\IdxPFD{unknown} &
  ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{\underline{error}}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{warning}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{fail} &
    a predicate calls an unknown procedure:
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    an \texttt{existence\_error} is raised
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a message is displayed then fails
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    quietly fails &
      ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

      Y \\

\hline

~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

\IdxPFD{syntax\_error} &
  ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{\underline{error}}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{warning}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{fail} &
    a predicate causes a syntax error:
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a \texttt{syntax\_error} is raised
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a message is displayed then fails
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    quietly fails &
      ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

      N \\

\hline

~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

\IdxPFD{os\_error} &
  ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{\underline{error}}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{warning}
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

  \texttt{fail} &
    a predicate causes an O.S. error:
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a \texttt{system\_error} is raised
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    a message is displayed then fails
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

    quietly fails &
      ~
%%%%%%%% line break: a blank line works for both HEVEA and LaTeX %%%%%%%

      N \\

\hline
\end{tabular}

The \texttt{strict\_iso} flag is introduced to allow a compatibility with
other Prolog systems. When turned off the following relaxations apply:

\begin{itemize}

\item a callable term can be given as a predicate indicator.

\item built-in predicates are found by \texttt{current\_predicate/1}
\RefSP{current-predicate/1}.

\end{itemize}

\begin{PlErrors}

\ErrCond{\texttt{Flag} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Value} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Flag} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Flag)}

\ErrCond{\texttt{Flag} is an atom but not a valid flag}
\ErrTerm{domain\_error(prolog\_flag, Flag)}

\ErrCond{\texttt{Value} is inappropriate for Flag}
\ErrTerm{domain\_error(flag\_value, Flag+Value)}

\ErrCond{\texttt{Value} is appropriate for \texttt{Flag} but flag
\texttt{Flag} is not modifiable}
\ErrTerm{permission\_error(modify, flag, Flag)}

\end{PlErrors}

\Portability

ISO predicate. All ISO flags are implemented.

\subsubsection{\texttt{current\_prolog\_flag/2}}

\begin{TemplatesOneCol}
current\_prolog\_flag(?flag, ?term)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_prolog\_flag/2]{current\_prolog\_flag(Flag, Value)}
succeeds if there exists a \Idx{Prolog flag} that unifies with
\texttt{Flag} and whose value unifies with \texttt{Value}. This predicate
is re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Flag} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Flag)}

\ErrCond{\texttt{Flag} is an atom but not a valid flag}
\ErrTerm{domain\_error(prolog\_flag, Flag)}

\end{PlErrors}

\Portability

ISO predicate.

\subsubsection{\texttt{set\_bip\_name/2}}
\label{set-bip-name/2}

\begin{TemplatesOneCol}
set\_bip\_name(+atom, +arity)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_bip\_name/2]{set\_bip\_name(Functor, Arity)} initializes the context of the error
\RefSP{General-format-and-error-context} with \texttt{Functor} and
\texttt{Arity} (if \texttt{Arity} $<$ 0 only \texttt{Functor} is
significant).

\begin{PlErrors}

\ErrCond{\texttt{Functor} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Arity} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Functor} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Functor)}

\ErrCond{\texttt{Arity} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Arity)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{current\_bip\_name/2}}
\label{current-bip-name/2}

\begin{TemplatesOneCol}
current\_bip\_name(?atom, ?arity)

\end{TemplatesOneCol}

\Description

\IdxPBD[current\_bip\_name/2]{current\_bip\_name(Functor, Arity)} succeeds if \texttt{Functor} and
\texttt{Arity} correspond to the context of the error \RefSP{General-format-and-error-context} (if \texttt{Arity} $<$ 0 only \texttt{Functor} is
significant).

\begin{PlErrors}

\ErrCond{\texttt{Functor} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Functor)}

\ErrCond{\texttt{Arity} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Arity)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{write\_pl\_state\_file/1},
\texttt{read\_pl\_state\_file/1}}
\label{write-pl-state-file/1}

\begin{TemplatesOneCol}
write\_pl\_state\_file(+source\_sink)\\
read\_pl\_state\_file(+source\_sink)

\end{TemplatesOneCol}

\Description

\IdxPBD[write\_pl\_state\_file/1]{write\_pl\_state\_file(FileName)} writes onto \texttt{FileName} all
information that influences the parsing of a term \RefSP{Term-input/output}. This allows a sub-process written in Prolog to read this
file and then process any Prolog term as done by the parent process. This
file can also be passed as argument of the \IdxK{--pl-state} option when
invoking \IdxK{gplc} \RefSP{Using-the-compiler}. More precisely the
following elements are saved:

\begin{itemize}

\item all operator definitions \RefSP{op/3:(Term-input/output)}.

\item the character conversion table \RefSP{char-conversion/2}.

\item the value of \IdxPF{char\_conversion}, \IdxPF{double\_quotes} and
\IdxPF{singleton\_warning} \Idx[Prolog flag]{Prolog flags}
\RefSP{set-prolog-flag/2}.

\end{itemize}

\IdxPBD[read\_pl\_state\_file/1]{read\_pl\_state\_file(FileName)} reads (restores) from
\texttt{FileName} all information previously saved by
\texttt{write\_pl\_state\_file/1.}

\begin{PlErrors}

\ErrCond{\texttt{FileName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{FileName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, FileName)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Program state}

\subsubsection{\texttt{consult/1},
\texttt{'.'/2} - program consult}
\label{consult/1}

\begin{TemplatesOneCol}
consult(+atom\_or\_atom\_list)\\
'.'(+atom, +atom\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[consult/1]{consult(Files)} compiles and loads into memory each file
of the list \texttt{Files}. Each file is compiled for byte-code using the
GNU Prolog compiler \RefSP{The-GNU-Prolog-compiler} then loaded using
\texttt{load/1} \RefSP{load/1}. It is possible to specify \IdxPK{user} as a
file name to directly enter the program from the terminal. \texttt{Files} can
be also a single file name (i.e. an atom). Refer to the section concerning
the consult of a Prolog program for more information
\RefSP{Consulting-a-Prolog-program}.

The final file name of a file is computed using the predicates
\IdxPB{prolog\_file\_name/2} \RefSP{prolog-file-name/2} and
\IdxPB{absolute\_file\_name/2} \RefSP{absolute-file-name/2}.

\texttt{[ File | Files ]}, i.e. \IdxPBD['.'/2]{'.'(File, Files)} is
equivalent to \texttt{consult([ File | Files ])}.

\begin{PlErrors}

\ErrCond{\texttt{Files} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Files} is neither a partial list nor a list nor an atom}
\ErrTerm{type\_error(list, Files)}

\ErrCond{an element \texttt{E} of the \texttt{Files} list is neither a
variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{an element \texttt{E} of the \texttt{Files} list is an atom but not
a valid pathname}
\ErrTerm{domain\_error(os\_path, E)}

\ErrCond{an element \texttt{E} of the \texttt{Files} list is a valid
pathname but does not correspond to an existing source}
\ErrTerm{existence\_error(source\_sink, E)}

\ErrCond{an error occurs executing a directive}
\ErrTermRm{see \texttt{call/1} errors \RefSP{call/1}}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{load/1}}
\label{load/1}

\begin{TemplatesOneCol}
load(+atom\_or\_atom\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[load/1]{load(Files)} loads into memory each file of the list
\texttt{Files}. Each file must have been previously compiled for byte-code
using the GNU Prolog compiler \RefSP{The-GNU-Prolog-compiler}.
\texttt{Files} can be also a single file name (i.e. an atom).

The final file name of a file is computed using the predicates
\IdxPB{absolute\_file\_name/2} \RefSP{absolute-file-name/2}. If no
suffix is given \texttt{'.wbc'} is appended to the file name.

\begin{PlErrors}

\ErrCond{\texttt{Files} is a partial list or a list with an element
\texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Files} is neither a partial list nor a list nor an atom}
\ErrTerm{type\_error(list, Files)}

\ErrCond{an element \texttt{E} of the \texttt{Files} list is neither a
variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{an element \texttt{E} of the \texttt{Files} list is an atom but not
a valid pathname}
\ErrTerm{domain\_error(os\_path, E)}

\ErrCond{an element \texttt{E} of the \texttt{Files} list is a valid
pathname but does not correspond to an existing source}
\ErrTerm{existence\_error(source\_sink, E)}

\ErrCond{an error occurs executing a directive}
\ErrTermRm{see \texttt{call/1} errors \RefSP{call/1}}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{listing/1},
\texttt{listing/0}}
\label{listing/1}

\begin{TemplatesOneCol}
listing(+predicate\_indicator)\\
listing(+atom)\\
listing

\end{TemplatesOneCol}

\Description

\IdxPBD[listing/1]{listing(Pred)} lists the clauses of the consulted predicate whose
predicate indicator is \texttt{Pred}. \texttt{Pred} can also be a single
atom in which case all predicates whose name is \texttt{Pred} are listed (of
any arity). This predicate uses \IdxPB{portray\_clause/2}
\RefSP{portray-clause/2} to output the clauses. 

\IdxPBD[listing/0]{listing} lists all clauses of all consulted predicates.

\begin{PlErrors}

\ErrCond{\texttt{Pred} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Pred} is neither a variable nor predicate indicator or an
atom}
\ErrTerm{type\_error(predicate\_indicator, Pred)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{System statistics}

\subsubsection{\texttt{statistics/0},
\texttt{statistics/2}}

\begin{TemplatesOneCol}
statistics\\
statistics(?atom, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[statistics/0]{statistics} displays statistics about memory usage and run times.

\IdxPBD[statistics/2]{statistics(Key, Value)} unifies \texttt{Value} with the current
value of the statistics key \texttt{Key}. \texttt{Value} a list of two
elements. Times are in milliseconds, sizes of areas in bytes.

\begin{tabular}{|l|l|l|}
\hline

Key & Description & Value \\

\hline\hline

\texttt{user\_time} & user CPU time & \texttt{[SinceStart, SinceLast]} \\

\hline

\texttt{system\_time} & system CPU time & \texttt{[SinceStart, SinceLast]}
\\

\hline

\texttt{cpu\_time} & total CPU time (user + system) & \texttt{[SinceStart,
SinceLast]} \\

\hline

\texttt{real\_time} & absolute time & \texttt{[SinceStart, SinceLast]} \\

\hline

\texttt{local\_stack} & local stack sizes (control, environments, choices) & \texttt{[UsedSize, FreeSize]} \\

\hline

\texttt{global\_stack} & global stack sizes (compound terms) &
\texttt{[UsedSize, FreeSize]} \\

\hline

\texttt{trail\_stack} & trail stack sizes (variable bindings to undo) &
\texttt{[UsedSize, FreeSize]} \\

\hline

\texttt{cstr\_stack} & constraint trail sizes (finite domain constraints) &
\texttt{[UsedSize, FreeSize]} \\

\hline
\end{tabular}

Note that the key \texttt{runtime} is recognized as \texttt{user\_time} for
compatibility purpose.


\begin{PlErrors}

\ErrCond{\texttt{Key} is neither a variable nor a valid key}
\ErrTerm{domain\_error(statistics\_key, Key)}

\ErrCond{\texttt{Value} is neither a variable nor a list of two elements}
\ErrTerm{domain\_error(statistics\_value, Value)}

\ErrCond{\texttt{Value} is a list of two elements and an element \texttt{E}
is neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{user\_time/1},
\texttt{system\_time/1},
\texttt{cpu\_time/1},
\texttt{real\_time/1}}
\label{user-time/1}

\begin{TemplatesOneCol}
user\_time(?integer)\\
system\_time(?integer)\\
cpu\_time(?integer)\\
real\_time(?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[user\_time/1]{user\_time(Time)} unifies \texttt{Time} with the user
CPU time elapsed since the start of Prolog.

\IdxPBD[system\_time/1]{system\_time(Time)} unifies \texttt{Time} with the
system CPU time elapsed since the start of Prolog.

\IdxPBD[cpu\_time/1]{cpu\_time(Time)} unifies \texttt{Time} with the CPU
time (user + system) elapsed since the start of Prolog.

\IdxPBD[real\_time/1]{real\_time(Time)} unifies \texttt{Time} with the
absolute time elapsed since the start of Prolog.

\begin{PlErrors}

\ErrCond{\texttt{Time} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Time)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsection{Random number generator}

\subsubsection{\texttt{set\_seed/1},
\texttt{randomize/0}}

\begin{TemplatesOneCol}
set\_seed(+integer)\\
randomize

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_seed/1]{set\_seed(Seed)} reinitializes the random number generator seed with
\texttt{Seed}.

\IdxPBD[randomize/0]{randomize} reinitializes the random number generator. This
predicates calls \texttt{set\_seed/1} with a random value depending on the
absolute time.

\begin{PlErrors}

\ErrCond{\texttt{Seed} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Seed} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Seed)}

\ErrCond{\texttt{Seed} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Seed)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{get\_seed/1}}

\begin{TemplatesOneCol}
get\_seed(?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[get\_seed/1]{get\_seed(Seed)} unifies \texttt{Seed} with the current random
number generator seed.

\begin{PlErrors}

\ErrCond{\texttt{Seed} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Seed)}

\ErrCond{\texttt{Seed} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Seed)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{random/1}}

\begin{TemplatesOneCol}
random(-float)

\end{TemplatesOneCol}

\Description

\IdxPBD[random/1]{random(Number)} unifies \texttt{Number} with a random floating point
number such that 0.0 $\leq$ \texttt{Number} $<$ 1.0.

\begin{PlErrors}

\ErrCond{\texttt{Number} is not a variable}
\ErrTerm{type\_error(variable, Number)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{random/3}}

\begin{TemplatesOneCol}
random(+number, +number, -number)

\end{TemplatesOneCol}

\Description

\IdxPBD[random/3]{random(Base, Max, Number)} unifies \texttt{Number} with a random
number such that \texttt{Base} $\leq$ \texttt{Number} $<$ \texttt{Max}. If
both \texttt{Base} and \texttt{Max} are integers \texttt{Number} will be an
integer, otherwise \texttt{Number} will be a floating point number.

\begin{PlErrors}

\ErrCond{\texttt{Base} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Base} is neither a variable nor a number}
\ErrTerm{type\_error(number, Base)}

\ErrCond{\texttt{Max} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Max} is neither a variable nor a number}
\ErrTerm{type\_error(number, Max)}

\ErrCond{\texttt{Number} is not a variable}
\ErrTerm{type\_error(variable, Number)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{File name processing}

\subsubsection{\texttt{absolute\_file\_name/2}}
\label{absolute-file-name/2}

\begin{TemplatesOneCol}
absolute\_file\_name(+atom, atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[absolute\_file\_name/2]{absolute\_file\_name(File1, File2)} succeeds if \texttt{File2} is
the absolute pathname associated to the relative file name \texttt{File1}.
\texttt{File1} can contain \texttt{\$\Param{VAR\_NAME}} sub-strings. When
such a sub-string is encountered, it is expanded with the value of the
environment variable whose name is \Param{VAR\_NAME} if exists
(otherwise no expansion is done). \texttt{File1} can also begin with a
sub-string \texttt{\~{}\Param{USER\_NAME}/}, this is expanded as the home
directory of the user \Param{USER\_NAME}. If
\Param{USER\_NAME} does not exist \texttt{File1} is an invalid
pathname. If no \Param{USER\_NAME} is given (i.e. \texttt{File1}
begins with \texttt{\~{}/}) the \texttt{\~{}} character is expanded as the
value of the environment variable \texttt{HOME}. If the \texttt{HOME}
variable is not defined \texttt{File1} is an invalid pathname. Relative
references to the current directory (\texttt{/./} sub-string) and to the
parent directory (\texttt{/../} sub-strings) are removed and no longer
appear in \texttt{File2}. \texttt{File1} is also invalid if it contains too
many \texttt{/../} consecutive sub-strings (i.e. parent directory relative
references). Finally if \texttt{File1} is \IdxPK{user} then \texttt{File2}
is also unified with \texttt{user} to allow this predicate to be called on
Prolog file names (since \texttt{user} in DEC-10 input/output predicates
denotes the current input/output stream). 

Most predicates using a file name implicitly call this predicate to obtain
the desired file, e.g. \texttt{open/4}. 

\begin{PlErrors}

\ErrCond{\texttt{File1} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{File1} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, File1)}

\ErrCond{\texttt{File2} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, File2)}

\ErrCond{\texttt{File1} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, File1)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{decompose\_file\_name/4}}

\begin{TemplatesOneCol}
decompose\_file\_name(+atom, ?atom, ?atom, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[decompose\_file\_name/4]{decompose\_file\_name(File, Directory, Prefix, Suffix)} decomposes
the pathname \texttt{File} and extracts the \texttt{Directory} part
(characters before the last \texttt{/}), the \texttt{Prefix} part
(characters after the last \texttt{/} and before the last \texttt{.} or
until the end if there is no suffix) and the \texttt{Suffix} part
(characters from the last \texttt{.} to the end of the string). 

\begin{PlErrors}

\ErrCond{\texttt{File} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{File} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, File)}

\ErrCond{\texttt{Directory} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Directory)}

\ErrCond{\texttt{Prefix} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Prefix)}

\ErrCond{\texttt{Suffix} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Suffix)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{prolog\_file\_name/2}}
\label{prolog-file-name/2}

\begin{TemplatesOneCol}
prolog\_file\_name(+atom, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[prolog\_file\_name/2]{prolog\_file\_name(File1, File2)} unifies \texttt{File2} with the
Prolog file name associated to \texttt{File1}. More precisely \texttt{File2}
is computed as follows:

\begin{itemize}

\item if \texttt{File1} has a suffix or if it is \IdxPK{user} then
\texttt{File2} is unified with \texttt{File1}.

\item else if the file whose name is \texttt{File1} + \texttt{'.pl'} exists
then \texttt{File2} is unified with this name.

\item else if the file whose name is \texttt{File1} + \texttt{'.pro'} exists
then \texttt{File2} is unified with this name.

\item else \texttt{File2} is unified with the name \texttt{File1} +
\texttt{'.pl'}.

\end{itemize}

This predicate uses \IdxPB{absolute\_file\_name/2} to check the existence
of a file \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{File1} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{File1} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, File1)}

\ErrCond{\texttt{File2} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, File2)}

\ErrCond{\texttt{File1} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, File1)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Operating system interface}

\subsubsection{\texttt{argument\_counter/1}}
\label{argument-counter/1}

\begin{TemplatesOneCol}
argument\_counter(?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[argument\_counter/1]{argument\_counter(Counter)} succeeds if \texttt{Counter} is the
number of arguments of the command-line. Since the first argument is always
the name of the running program, \texttt{Counter} is always $\geq$ 1.

\begin{PlErrors}

\ErrCond{\texttt{Counter} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Counter)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{argument\_value/2}}
\label{argument-value/2}

\begin{TemplatesOneCol}
argument\_value(+integer, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[argument\_value/2]{argument\_value(N, Arg)} succeeds if the \texttt{N}\emph{th}
argument on the command-line unifies with \texttt{Arg}. The first argument
is always the name of the running program and its number is 0. The number of
arguments on the command-line can be obtained using
\texttt{argument\_counter/1} \RefSP{argument-counter/1}.

\begin{PlErrors}

\ErrCond{\texttt{N} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{N} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, N)}

\ErrCond{\texttt{N} is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, N)}

\ErrCond{\texttt{Arg} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Arg)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{argument\_list/1}}
\label{argument-list/1}

\begin{TemplatesOneCol}
argument\_list(?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[argument\_list/1]{argument\_list(Args)} succeeds if \texttt{Args} unifies with the
list of atoms associated to each argument on the command-line other than the
first argument (the name of the running program).

\begin{PlErrors}

\ErrCond{\texttt{Args} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Args)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{environ/2}}

\begin{TemplatesOneCol}
environ(?atom, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[environ/2]{environ(Name, Value)} succeeds if \texttt{Name} is the name of an
environment variable whose value is \texttt{Value}. This predicate is
re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Name} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Name)}

\ErrCond{\texttt{Value} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Value)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{make\_directory/1},
\texttt{delete\_directory/1},
\texttt{change\_directory/1}}

\begin{TemplatesOneCol}
make\_directory(+atom)\\
delete\_directory(+atom)\\
change\_directory(+atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[make\_directory/1]{make\_directory(PathName)} creates the directory whose pathname is
\texttt{PathName}. 

\IdxPBD[delete\_directory/1]{delete\_directory(PathName)} removes the directory whose pathname is
\texttt{PathName}.

\IdxPBD[change\_directory/1]{change\_directory(PathName)} sets the current directory to the
directory whose pathname is \texttt{PathName}.

See \IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{PathName} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{PathName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{\texttt{PathName} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{working\_directory/1}}

\begin{TemplatesOneCol}
working\_directory(?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[working\_directory/1]{working\_directory(PathName)} succeeds if \texttt{PathName} is the
pathname of the current directory. 

\begin{PlErrors}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{directory\_files/2}}

\begin{TemplatesOneCol}
directory\_files(+atom, ?list)

\end{TemplatesOneCol}

\Description

\IdxPBD[directory\_files/2]{directory\_files(PathName, Files)} succeeds if \texttt{Files} is the
list of all entries (files, sub-directories,\ldots) in the directory whose
pathname is \texttt{PathName}. See \IdxPB{absolute\_file\_name/2} for
information about the syntax of \texttt{PathName}
\RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{PathName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{\texttt{PathName} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName)}

\ErrCond{\texttt{Files} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Files)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{rename\_file/2}}

\begin{TemplatesOneCol}
rename\_file(+atom, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[rename\_file/2]{rename\_file(PathName1, PathName2)} renames the file or directory
whose pathname is \texttt{PathName1} to \texttt{PathName2}. See
\IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{PathName1} and \texttt{PathName2} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{PathName1} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName1} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName1)}

\ErrCond{\texttt{PathName1} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName1)}

\ErrCond{\texttt{PathName2} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName2} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName2)}

\ErrCond{\texttt{PathName2} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName2)}

\ErrCond{an operating system error occurs and value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{delete\_file/1},
\texttt{unlink/1}}

\begin{TemplatesOneCol}
delete\_file(PathName)\\
unlink(PathName)

\end{TemplatesOneCol}

\Description

\IdxPBD[delete\_file/1]{delete\_file(PathName)} removes the existing file whose pathname is
\texttt{PathName}.

\IdxPBD[unlink/1]{unlink/1} is similar to \texttt{delete\_file/1} except that it never
causes a \texttt{system\_error} (e.g. if \texttt{PathName} does not refer to
an existing file).

See \IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{PathName} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{PathName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{\texttt{PathName} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{file\_permission/2},
\texttt{file\_exists/1}}
\label{file-permission/2}

\begin{TemplatesOneCol}
file\_permission(+atom, +atom)\\
file\_permission(+atom, +atom\_list)\\
file\_exists(+atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[file\_permission/2]{file\_permission(PathName, Permission)} succeeds if
\texttt{PathName} is the pathname of an existing file (or directory) whose
permissions include \texttt{Permission}.

\SPart{File permissions}: \texttt{Permission} can be a single permission or
a list of permissions. A permission is an atom among: 

\begin{itemize}

\item \IdxPXD{read}: the file or directory can be read.

\item \IdxPXD{write}: the file or directory can be written.

\item \IdxPXD{execute}: the file can be executed.

\item \IdxPXD{search}: the directory can be searched.

\end{itemize}

If \texttt{PathName} does not exists or if it its permissions do not include
\texttt{Permission} this predicate fails.

\IdxPBD[file\_exists/1]{file\_exists(PathName)} is equivalent to
\texttt{file\_permission(PathName, [])}, i.e. it succeeds if
\texttt{PathName} is the pathname of an existing file (or directory).

See \IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{PathName} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{PathName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{\texttt{PathName} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName)}

\ErrCond{\texttt{Permission} is a partial list or a list with an element
which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Permission} is neither an atom nor partial list or a list}
\ErrTerm{type\_error(list, Permission)}

\ErrCond{an element \texttt{E} of the \texttt{Permission} list is neither a
variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{an element \texttt{E} of the \texttt{Permission} is an atom but not
a valid permission}
\ErrTerm{domain\_error(os\_file\_permission, Permission)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{file\_property/2}}
\label{file-property/2}

\begin{TemplatesOneCol}
file\_property(+atom, ?os\_file\_property)

\end{TemplatesOneCol}

\Description

\IdxPBD[file\_property/2]{file\_property(PathName, Property)} succeeds if \texttt{PathName} is
the pathname of an existing file (or directory) and if \texttt{Property}
unifies with one of the properties of the file. This predicate is
re-executable on backtracking.

\SPart{File properties}:

\begin{itemize}

\item \IdxPPD[absolute\_file\_name]{absolute\_file\_name(File)}:
\texttt{File} is the absolute file name of \texttt{PathName}
\RefSP{absolute-file-name/2}.

\item \IdxPPD[real\_file\_name]{real\_file\_name(File)}: \texttt{File} is
the real file name of \texttt{PathName} (follows symbolic links).

\item \IdxPPD[type]{type(Type)}: \texttt{Type} is the type of
  \texttt{PathName}. Possible values are: \IdxPXD{regular},
  \IdxPXD{directory}, \IdxPXD{fifo}, \IdxPXD{socket}, 
\IdxPXD{character\_device}, \IdxPXD{block\_device} or \IdxPXD{unknown}.

\item \IdxPPD[size]{size(Size)}: \texttt{Size} is the size (in bytes) of
\texttt{PathName}.

\item \IdxPPD[permission]{permission(Permission)}: \texttt{Permission} is a
permission of \texttt{PathName} \RefSP{file-permission/2}.

\item \IdxPPD[last\_modification]{last\_modification(DT)}: \texttt{DT} is
the last modification date and time \RefSP{date-time/1}.

\end{itemize}

See \IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{PathName} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{PathName} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{\texttt{PathName} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, PathName)}

\ErrCond{\texttt{Property} is neither a variable nor a file property term}
\ErrTerm{domain\_error(os\_file\_property, Property)}

\ErrCond{\texttt{Property} = \texttt{absolute\_file\_name(E)},
\texttt{real\_file\_name(E)}, \texttt{type(E)} or \texttt{permission(E)} and
\texttt{E} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{\texttt{Property} = \texttt{last\_modification(DateTime)} and
\texttt{DateTime} is neither a variable nor a compound term}
\ErrTerm{type\_error(compound, DateTime)}

\ErrCond{\texttt{Property} = \texttt{last\_modification(DateTime)} and
\texttt{DateTime} is a compound term but not a structure \texttt{dt/6}}
\ErrTerm{domain\_error(date\_time, DateTime)}

\ErrCond{\texttt{Property} = \texttt{size(E)} or
\texttt{last\_modification(DateTime)} and \texttt{DateTime} is a structure
\texttt{dt/6} but an element \texttt{E} is neither a variable nor an
integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{temporary\_name/2}}

\begin{TemplatesOneCol}
temporary\_name(+atom, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[temporary\_name/2]{temporary\_name(Template, PathName)} creates a unique file name
\texttt{PathName} whose pathname begins by \texttt{Template}.
\texttt{Template} should contain a pathname with six trailing
\texttt{X}\emph{s}. \texttt{PathName} is \texttt{Template} with the six
\texttt{X}\emph{s} replaced with a letter and the process identifier. This
predicate is an interface to the C Unix function \texttt{mktemp(3)}.

See \IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{Template} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{Template} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Template} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Template)}

\ErrCond{\texttt{Template} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, Template)}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{temporary\_file/3}}

\begin{TemplatesOneCol}
temporary\_file(+atom, +atom, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[temporary\_file/3]{temporary\_file(Directory, Prefix, PathName)} creates a unique file
name \texttt{PathName} whose pathname begins by \texttt{Directory/Prefix}.
If \texttt{Directory} is the empty atom \texttt{''} a standard temporary
directory will be used (e.g. \texttt{/tmp}). \texttt{Prefix} can be the
empty atom \texttt{''}. This predicate is an interface to the C Unix
function \texttt{tempnam(3)}.

See \IdxPB{absolute\_file\_name/2} for information about the syntax of
\texttt{Directory} \RefSP{absolute-file-name/2}.

\begin{PlErrors}

\ErrCond{\texttt{Directory} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Directory} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Directory)}

\ErrCond{\texttt{Directory} is an atom but not a valid pathname}
\ErrTerm{domain\_error(os\_path, Directory)}

\ErrCond{\texttt{Prefix} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Prefix} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Prefix)}

\ErrCond{\texttt{PathName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, PathName)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{date\_time/1}}
\label{date-time/1}

\begin{TemplatesOneCol}
date\_time(?compound)

\end{TemplatesOneCol}

\Description

\IdxPBD[date\_time/1]{date\_time(DateTime)} unifies \texttt{DateTime} with a compound term
containing the current date and time. \texttt{DateTime} is a structure
\texttt{dt(Year, Month, Day, Hour, Minute, Second)}. Each sub-argument of
the term \texttt{dt/6} is an integer.

\begin{PlErrors}

\ErrCond{\texttt{DateTime} is neither a variable nor a compound term}
\ErrTerm{type\_error(compound, DateTime)}

\ErrCond{\texttt{DateTime} is a compound term but not a structure
\texttt{dt/6}}
\ErrTerm{domain\_error(date\_time, DateTime)}

\ErrCond{\texttt{DateTime} is a structure \texttt{dt/6} and an element
\texttt{E} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{host\_name/1}}

\begin{TemplatesOneCol}
host\_name(?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[host\_name/1]{host\_name(HostName)} unifies \texttt{HostName} with the name of the
host machine executing the current GNU Prolog process. If the sockets are
available \RefSP{Introduction:(Sockets-input/output)}, the name returned
will be fully qualified. In that case, \texttt{host\_name/1} will also
succeed if \texttt{HostName} is instantiated to the unqualified name (or an
alias) of the machine.

\begin{PlErrors}

\ErrCond{\texttt{Hostname} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, HostName)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{os\_version/1}}

\begin{TemplatesOneCol}
os\_version(?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[os\_version/1]{os\_version(OSVersion)} unifies \texttt{OSVersion} with the
operating system version of the machine executing the current GNU Prolog
process.

\begin{PlErrors}

\ErrCond{\texttt{OSVersion} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, OSVersion)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{architecture/1}}

\begin{TemplatesOneCol}
architecture(?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[architecture/1]{architecture(Architecture)} unifies \texttt{Architecture} with the
name of the machine executing the current GNU Prolog process.

\begin{PlErrors}

\ErrCond{\texttt{Architecture} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Architecture)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{shell/2},
\texttt{shell/1},
\texttt{shell/0}}

\begin{TemplatesOneCol}
shell(+atom, ?integer)\\
shell(+atom)\\
shell

\end{TemplatesOneCol}

\Description

\IdxPBD[shell/2]{shell(Command, Status)} invokes a new shell (named by the
\texttt{SHELL} environment variable) passing \texttt{Command} for execution
and unifies \texttt{Status} with the result of the execution. If
\texttt{Command} is the empty atom \texttt{''} a new interactive shell is
executed. The control is returned to Prolog upon termination of the called
process.

\IdxPBD[shell/1]{shell(Command)} is equivalent to \texttt{shell(Command, 0)}.

\IdxPBD[shell/0]{shell} is equivalent to \texttt{shell('', 0)}.

\begin{PlErrors}

\ErrCond{\texttt{Command} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Command} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Command)}

\ErrCond{\texttt{Status} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Status)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{system/2},
\texttt{system/1}}

\begin{TemplatesOneCol}
system(+atom, ?integer)\\
system(+atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[system/2]{system(Command, Status)} invokes a new default shell passing
\texttt{Command} for execution and unifies \texttt{Status} with the result
of the execution. The control is returned to Prolog upon termination of the
shell process. This predicate is an interface to the C Unix function
\IdxPBD[system/1]{system(3)}.

\texttt{system(Command)} is equivalent to \texttt{system(Command, 0)}.

\begin{PlErrors}

\ErrCond{\texttt{Command} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Command} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Command)}

\ErrCond{\texttt{Status} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Status)}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{spawn/3},
\texttt{spawn/2}}

\begin{TemplatesOneCol}
spawn(+atom, +atom\_list, ?integer)\\
spawn(+atom, +atom\_list)

\end{TemplatesOneCol}

\Description

\IdxPBD[spawn/3]{spawn(Command, Arguments, Status)} executes \texttt{Command} passing
as arguments of the command-line each element of the list \texttt{Arguments}
and unifies \texttt{Status} with the result of the execution. The control is
returned to Prolog upon termination of the command.

\IdxPBD[spawn/2]{spawn(Command, Arguments)} is equivalent to \texttt{spawn(Command,
Arguments, 0)}.

\begin{PlErrors}

\ErrCond{\texttt{Command} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Command} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Command)}

\ErrCond{\texttt{Arguments} is a partial list or a list with an element
which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Arguments} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Arguments)}

\ErrCond{an element \texttt{E} of the \texttt{Arguments} list is neither a
variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{\texttt{Status} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Status)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{popen/3}}
\label{popen/3}

\begin{TemplatesOneCol}
popen(+atom, +io\_mode, -stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[popen/3]{popen(Command, Mode, Stream)} invokes a new default shell (by
creating a pipe) passing \texttt{Command} for execution and associates a
stream either to the standard input or the standard output of the created
process. if \texttt{Mode} is \texttt{read} (resp. \texttt{write}) an input
(resp. output) stream is created and \texttt{Stream} is unified with the
stream-term associated. Writing to the stream writes to the standard input
of the command while reading from the stream reads the command's standard
output. The stream must be closed using \IdxPB{close/2} \RefSP{close/2}.
This predicate is an interface to the C Unix function \texttt{popen(3)}.

\begin{PlErrors}

\ErrCond{\texttt{Command} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Command} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Command)}

\ErrCond{\texttt{Mode} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Mode} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Mode)}

\ErrCond{\texttt{Mode} is an atom but neither \texttt{read} nor
\texttt{write}.}
\ErrTerm{domain\_error(io\_mode, Mode)}

\ErrCond{\texttt{Stream} is not a variable}
\ErrTerm{type\_error(variable, Stream)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{exec/5},
\texttt{exec/4}}

\begin{TemplatesOneCol}
exec(+atom, -stream, -stream, -stream, -integer)\\
exec(+atom, -stream, -stream, -stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[exec/5]{exec(Command, StreamIn, StreamOut, StreamErr, Pid)} invokes a new
default shell passing \texttt{Command} for execution and associates streams
to standard streams of the created process. \texttt{StreamIn} is unified
with the stream-term associated to the standard input stream of
\texttt{Command} (it is an output stream). \texttt{StreamOut} is unified
with the stream-term associated to the standard output stream of
\texttt{Command} (it is an input stream). \texttt{StreamErr} is unified with
the stream-term associated to the standard error stream of \texttt{Command}
(it is an input stream). \texttt{Pid} is unified with the process identifier
of the new process. This information is only useful if it is necessary to
obtain the status of the execution using \texttt{wait/2} \RefSP{wait/2}.
Until a call to \texttt{wait/2} is done the process remains in the system
processes table (as a zombie process if terminated). For this reason, if the
status is not needed it is preferable to use \texttt{exec/4}.

\IdxPBD[exec/4]{exec/4} is similar to \texttt{exec/5} but the process is removed
from system processes as soon as it is terminated.

\begin{PlErrors}

\ErrCond{\texttt{Command} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Command} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Command)}

\ErrCond{\texttt{StreamIn} is not a variable}
\ErrTerm{type\_error(variable, StreamIn)}

\ErrCond{\texttt{StreamOut} is not a variable}
\ErrTerm{type\_error(variable, StreamOut)}

\ErrCond{\texttt{StreamErr} is not a variable}
\ErrTerm{type\_error(variable, StreamErr)}

\ErrCond{\texttt{Pid} is not a variable}
\ErrTerm{type\_error(variable, Pid)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{wait/2}}
\label{wait/2}

\begin{TemplatesOneCol}
wait(+integer, ?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[wait/2]{wait(Pid, Status)} waits for the child process whose identifier is
\texttt{Pid} to terminate. \texttt{Status} is then unified with the exit
status. This predicate is an interface to the C Unix function
\texttt{waitpid(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Pid} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Pid} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Pid)}

\ErrCond{\texttt{Status} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Status)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{prolog\_pid/1}}

\begin{TemplatesOneCol}
prolog\_pid(?integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[prolog\_pid/1]{prolog\_pid(Pid)} unifies \texttt{Pid} with the process identifier
of the current GNU Prolog process.

\begin{PlErrors}

\ErrCond{\texttt{Pid} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Pid)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{send\_signal/2}}

\begin{TemplatesOneCol}
send\_signal(+integer, +integer)\\
send\_signal(+integer, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[send\_signal/2]{send\_signal(Pid, Signal)} sends \texttt{Signal} to the process whose
identifier is \texttt{Pid.} \texttt{Signal} can be specified directly as an
integer or symbolically as an atom. Allowed atoms depend on the machine (e.g.
\texttt{'SIGINT'}, \texttt{'SIGQUIT'}, \texttt{'SIGKILL'},
\texttt{'SIGUSR1'}, \texttt{'SIGUSR2'}, \texttt{'SIGALRM'},\ldots). This
predicate is an interface to the C Unix function \texttt{kill(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Pid} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Pid} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Pid)}

\ErrCond{\texttt{Signal} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Signal} is neither a variable nor an integer or an atom}
\ErrTerm{type\_error(integer, Signal)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{sleep/1}}

\begin{TemplatesOneCol}
sleep(+number)

\end{TemplatesOneCol}

\Description

\IdxPBD[sleep/1]{sleep(Seconds)} puts the GNU Prolog process to sleep for
\texttt{Second}s seconds. \texttt{Seconds} can be an integer or a floating
point number (in which case it can be $<$ 1). This predicate is an interface
to the C Unix function \texttt{usleep(3)}.

\begin{PlErrors}

\ErrCond{\texttt{Seconds} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Seconds} is neither a variable nor a number}
\ErrTerm{type\_error(number, Seconds)}

\ErrCond{\texttt{Seconds} is a number $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, Seconds)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{select/5}}
\label{select/5}

\begin{TemplatesOneCol}
select(+list, ?list, +list, ?list, +number)

\end{TemplatesOneCol}

\Description

\IdxPBD[select/5]{select(Reads, ReadyReads, Writes, ReadyWrites, TimeOut)} waits for a
number of streams (or file descriptors) to change status.
\texttt{ReadyReads} is unified with the list of elements listed in
\texttt{Reads} that have characters available for reading. Similarly
\texttt{ReadyWrites} is unified with the list of elements of \texttt{Writes}
that are ok for immediate writing. The elements of \texttt{Reads} and
\texttt{Writes} are either stream-terms or aliases or integers considered as
file descriptors, e.g. for sockets \RefSP{Sockets-input/output}. Streams
that must be tested with \texttt{select/5} should not be buffered. This can
be done at the opening using \IdxPB{open/4} \RefSP{open/4} or later using
\IdxPB{set\_stream\_buffering/2} \RefSP{set-stream-buffering/2}.
\texttt{TimeOut} is an upper bound on the amount of time (in milliseconds)
elapsed before \texttt{select/5} returns. If \texttt{TimeOut} $\leq$ 0 (no
timeout) \texttt{select/5} waits until something is available (either or
reading or for writing) and thus can block indefinitely. This predicate is
an interface to the C Unix function \texttt{select(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Reads} (or \texttt{Writes}) is a partial list or a list
with an element \texttt{E} which is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Reads} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Reads)}

\ErrCond{\texttt{Writes} is neither a partial list nor a list}
\ErrTerm{type\_error(list, Writes)}

\ErrCond{\texttt{ReadyReads} is neither a partial list nor a list}
\ErrTerm{type\_error(list, ReadyReads)}

\ErrCond{\texttt{ReadyWrites} is neither a partial list nor a list}
\ErrTerm{type\_error(list, ReadyWrites)}

\ErrCond{an element \texttt{E} of the \texttt{Reads} (or \texttt{Writes})
list is neither a stream-term or alias nor an integer}
\ErrTerm{domain\_error(stream\_or\_alias, E)}

\ErrCond{an element \texttt{E} of the \texttt{Reads} (or \texttt{Writes})
list is not a selectable item}
\ErrTerm{domain\_error(selectable\_item, E)}

\ErrCond{an element \texttt{E} of the \texttt{Reads} (or \texttt{Writes})
list is an integer $<$ 0}
\ErrTerm{domain\_error(not\_less\_than\_zero, E)}

\ErrCond{an element \texttt{E} of the \texttt{Reads} (or \texttt{Writes})
list is a stream-tern or alias not associated with an open stream}
\ErrTerm{existence\_error(stream, E)}

\ErrCond{an element \texttt{E} of the \texttt{Reads} list is associated to
an output stream}
\ErrTerm{permission\_error(input, stream, E)}

\ErrCond{an element \texttt{E} of the \texttt{Writes} list is associated to
an input stream}
\ErrTerm{permission\_error(output, stream, E)}

\ErrCond{\texttt{TimeOut} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{TimeOut} is neither a variable nor a number}
\ErrTerm{type\_error(number, TimeOut)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Sockets input/output}
\label{Sockets-input/output}

\subsubsection{Introduction}
\label{Introduction:(Sockets-input/output)}
This set of predicates provides a way to manipulate sockets. The predicates
are straightforward interfaces to the corresponding BSD-type socket
functions. This facility is available if the sockets part of GNU Prolog has
been installed. A reader familiar with BSD sockets will understand them
immediately otherwise a study of sockets is needed. 

The domain is either the atom \texttt{'AF\_INET'} or \texttt{'AF\_UNIX'}
corresponding to the same domains in BSD-type sockets.

An address is either of the form \texttt{'AF\_INET'(HostName, Port)} or
\texttt{'AF\_UNIX'(SocketName)}. \texttt{HostName} is an atom denoting a
machine name, \texttt{Port} is a port number and \texttt{SocketName} is an
atom denoting a socket. 

By default, streams associated to sockets are \texttt{block} buffered. The
predicate \IdxPB{set\_stream\_buffering/2} \RefSP{set-stream-buffering/2}
can be used to change this mode. They are also text streams by default. Use
\IdxPB{set\_stream\_type/2} \RefSP{set-stream-type/2} to change the type
if binary streams are needed.

\subsubsection{\texttt{socket/2}}

\begin{TemplatesOneCol}
socket(+socket\_domain, -integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[socket/2]{socket(Domain, Socket)} creates a socket whose domain is
\texttt{Domain} \RefSP{Sockets-input/output} and unifies \texttt{Socket}
with the descriptor identifying the socket. This predicate is an interface
to the C Unix function \texttt{socket(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Domain} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Domain} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Domain)}

\ErrCond{\texttt{Domain} is an atom but not a valid socket domain}
\ErrTerm{domain\_error(socket\_domain, Domain)}

\ErrCond{\texttt{Socket} is not a variable}
\ErrTerm{type\_error(variable, Socket)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{socket\_close/1}}

\begin{TemplatesOneCol}
socket\_close(+integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[socket\_close/1]{socket\_close(Socket)} closes the socket whose descriptor is
\texttt{Socket}. This predicate should not be used if \texttt{Socket} has
given rise to a stream, e.g. by \IdxPB{socket\_connect/2}
\RefSP{socket-connect/4}.  In that case simply use \IdxPB{close/2}
\RefSP{close/2} on the associated stream.

\begin{PlErrors}

\ErrCond{\texttt{Socket} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Socket} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Socket)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{socket\_bind/2}}

\begin{TemplatesOneCol}
socket\_bind(+integer, +socket\_address)

\end{TemplatesOneCol}

\Description

\IdxPBD[socket\_bind/2]{socket\_bind(Socket, Address)} binds the socket whose descriptor is
\texttt{Socket} to the address specified by \texttt{Address}
\RefSP{Sockets-input/output}. If \texttt{Address} if of the form
\texttt{'AF\_INET'(HostName, Port)} and if \texttt{HostName} is
uninstantiated then it is unified with the current machine name. If
\texttt{Port} is uninstantiated, it is unified to a port number picked by
the operating system. This predicate is an interface to the C Unix function
\texttt{bind(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Socket} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Socket} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Socket)}

\ErrCond{\texttt{Address} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Address} is neither a variable nor a valid address}
\ErrTerm{domain\_error(socket\_address, Address)}

\ErrCond{\texttt{Address} = \texttt{'AF\_UNIX'(E)} and \texttt{E} is a
variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Address} = \texttt{'AF\_UNIX'(E)} or \texttt{'AF\_INET'(E,
\_)} and \texttt{E} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{\texttt{Address} = \texttt{'AF\_UNIX'(E)} and \texttt{E} is an atom
but not a valid pathname}
\ErrTerm{domain\_error(os\_path, E)}

\ErrCond{\texttt{Address} = \texttt{'AF\_INET'(\_, E)} and \texttt{E} is
neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{socket\_connect/4}}
\label{socket-connect/4}

\begin{TemplatesOneCol}
socket\_connect(+integer, +socket\_address, -stream, -stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[socket\_connect/4]{socket\_connect(Socket, Address, StreamIn, StreamOut)} connects the
socket whose descriptor is \texttt{Socket} to the address specified by
\texttt{Address} \RefSP{Sockets-input/output}. \texttt{StreamIn} is
unified with a stream-term associated to the input of the connection (it is
an input stream). Reading from this stream gets data from the socket.
\texttt{StreamOut} is unified with a stream-term associated to the output of
the connection (it is an output stream). Writing to this stream sends data
to the socket. The use of \IdxPB{select/5} can be useful
\RefSP{select/5}. This predicate is an interface to the C Unix function
\texttt{connect(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Socket} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Socket} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Socket)}

\ErrCond{\texttt{Address} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Address} is neither a variable nor a valid address}
\ErrTerm{domain\_error(socket\_address, Address)}

\ErrCond{\texttt{Address} = \texttt{'AF\_UNIX'(E)} or \texttt{'AF\_INET'(E,
\_)} or \texttt{Address} = \texttt{'AF\_INET'(\_, E)} and \texttt{E} is a
variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Address} = \texttt{'AF\_UNIX'(E)} or \texttt{'AF\_INET'(E,
\_)} and \texttt{E} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, E)}

\ErrCond{\texttt{Address} = \texttt{'AF\_UNIX'(E)} and \texttt{E} is an atom
but not a valid pathname}
\ErrTerm{domain\_error(os\_path, E)}

\ErrCond{\texttt{Address} = \texttt{'AF\_INET'(\_, E)} and \texttt{E} is
neither a variable nor an integer}
\ErrTerm{type\_error(integer, E)}

\ErrCond{\texttt{StreamIn} is not a variable}
\ErrTerm{type\_error(variable, StreamIn)}

\ErrCond{\texttt{StreamOut} is not a variable}
\ErrTerm{type\_error(variable, StreamOut)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{socket\_listen/2}}

\begin{TemplatesOneCol}
socket\_listen(+integer, +integer)

\end{TemplatesOneCol}

\Description

\IdxPBD[socket\_listen/2]{socket\_listen(Socket, Length)} defines the socket whose descriptor
is \texttt{Socket} to have a maximum backlog queue of \texttt{Length}
pending connections. This predicate is an interface to the C Unix function
\texttt{listen(2)}.

\begin{PlErrors}

\ErrCond{\texttt{Socket} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Socket} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Socket)}

\ErrCond{\texttt{Length} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Length} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Length)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{socket\_accept/4},
\texttt{socket\_accept/3}}

\begin{TemplatesOneCol}
socket\_accept(+integer, -atom, -stream, -stream)\\
socket\_accept(+integer, -stream, -stream)

\end{TemplatesOneCol}

\Description

\IdxPBD[socket\_accept/4]{socket\_accept(Socket, Client, StreamIn, StreamOut)} extracts the
first connection to the socket whose descriptor is \texttt{Socket}. If the
domain is \texttt{'AF\_INET'}, \texttt{Client} is unified with an atom whose
name is the Internet host address in numbers-and-dots notation of the
connecting machine. \texttt{StreamIn} is unified with a stream-term
associated to the input of the connection (it is an input stream). Reading
from this stream gets data from the socket. \texttt{StreamOut} is unified
with a stream-term associated to the output of the connection (it is an
output stream). Writing to this stream sends data to the socket. The use of
\IdxPB{select/5} can be useful \RefSP{select/5}. This predicate is an
interface to the C Unix function \texttt{accept(2)}.

\IdxPBD[socket\_accept/3]{socket\_accept(Socket, StreamIn, StreamOut)} is equivalent to
\texttt{socket\_accept(Socket, \_,\\
 StreamIn, StreamOut)}.

\begin{PlErrors}

\ErrCond{\texttt{Socket} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Socket} is neither a variable nor an integer}
\ErrTerm{type\_error(integer, Socket)}

\ErrCond{\texttt{Client} is not a variable}
\ErrTerm{type\_error(variable, Client)}

\ErrCond{\texttt{StreamIn} is not a variable}
\ErrTerm{type\_error(variable, StreamIn)}

\ErrCond{\texttt{StreamOut} is not a variable}
\ErrTerm{type\_error(variable, StreamOut)}

\ErrCond{an operating system error occurs and the value of the
\texttt{os\_error} Prolog flag is \texttt{error}
\RefSP{set-prolog-flag/2}}
\ErrTerm{system\_error(\textit{atom explaining the error})}

\end{PlErrors}

\Portability

GNU Prolog predicates.

\subsubsection{\texttt{hostname\_address/2}}

\begin{TemplatesOneCol}
hostname\_address(+atom, ?atom)\\
hostname\_address(?atom, +atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[hostname\_address/2]{hostname\_address(HostName, HostAddress)} succeeds if the Internet
host address in numbers-and-dots notation of \texttt{HostName} is
\texttt{HostAddress}. \texttt{Hostname} can be given as a fully qualified
name, or an unqualified name or an alias of the machine. The predicate will
fail if the machine name or address cannot be resolved.

\begin{PlErrors}

\ErrCond{\texttt{HostName} and \texttt{HostAddress} are variables}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{HostName} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, HostName)}

\ErrCond{\texttt{HostAddress} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, HostAddress)}

\ErrCond{\texttt{Address} is neither a variable nor a valid address}
\ErrTerm{domain\_error(socket\_address, Address)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsection{Linedit management}
The following predicates are only available if the \IdxK{linedit} part of
GNU Prolog has been installed.

\subsubsection{\texttt{get\_linedit\_prompt/1}}

\begin{TemplatesOneCol}
get\_linedit\_prompt(?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[get\_linedit\_prompt/1]{get\_linedit\_prompt(Prompt)} succeeds if \texttt{Prompt} is the
current \IdxK{linedit} prompt, e.g. the \Idx{top-level} prompt is
\texttt{'| ?-'}. By default all other reads have an empty prompt.

\begin{PlErrors}

\ErrCond{\texttt{Prompt} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Pred)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{set\_linedit\_prompt/1}}

\begin{TemplatesOneCol}
set\_linedit\_prompt(+atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[set\_linedit\_prompt/1]{set\_linedit\_prompt(Prompt)} sets the current \IdxK{linedit}
prompt to \texttt{Prompt}. This prompt will be displayed for reads from a
terminal (except for \Idx{top-level} reads).

\begin{PlErrors}

\ErrCond{\texttt{Prompt} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Prompt} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Pred)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{add\_linedit\_completion/1}}

\begin{TemplatesOneCol}
add\_linedit\_completion(+atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[add\_linedit\_completion/1]{add\_linedit\_completion(Word)} adds \texttt{Word} in the list of
\Idx{completion} words maintained by \IdxK{linedit}
\RefSP{The-line-editor}. Only words containing letters, digits and
the underscore character are added (if \texttt{Word} does not respect
this restriction the predicate fails).

\begin{PlErrors}

\ErrCond{\texttt{Word} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Word} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Word)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

\subsubsection{\texttt{find\_linedit\_completion/2}}

\begin{TemplatesOneCol}
find\_linedit\_completion(+atom, ?atom)

\end{TemplatesOneCol}

\Description

\IdxPBD[find\_linedit\_completion/2]{find\_linedit\_completion(Prefix, Word)} succeeds if \texttt{Word}
is a word beginning by \texttt{Prefix} and belongs to the list of
\Idx{completion} words maintained by \IdxK{linedit}
\RefSP{The-line-editor}. This predicate is re-executable on backtracking.

\begin{PlErrors}

\ErrCond{\texttt{Prefix} is a variable}
\ErrTerm{instantiation\_error}

\ErrCond{\texttt{Prefix} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Prefix)}

\ErrCond{\texttt{Word} is neither a variable nor an atom}
\ErrTerm{type\_error(atom, Word)}

\end{PlErrors}

\Portability

GNU Prolog predicate.

%HEVEA\cutend
