\chapter{Built-in Predicates}			\label{sec:builtin}

\section{Notation of Predicate Descriptions}	\label{sec:preddesc}

We have tried to keep the predicate descriptions clear and concise.
First, the predicate name is printed in bold face, followed by the
arguments in italics.  Arguments are preceded by a mode indicator.
There is no complete agreement on mode indicators in the Prolog
community.  We use the following definitions:%
	\footnote{These definitions are taken from PlDoc.  The current
		  manual has only one mode declaration per predicate and
		  therefore predicates with mode (+,-) and (-,+) are
		  described as (?,?).  The \chr{@}-mode is often replaced
		  by \chr{\Splus}.}

\begin{center}
\begin{tabular}{lp{0.7\linewidth}}
\hline
++&	Argument must be ground, i.e., the argument may not contain a
	variable anywhere. \\
+ &	Argument must be fully instantiated to a term that satisfies the
	type.  This is not necessarily \jargon{ground}, e.g., the term
	\exam{[_]} is a \jargon{list}, although its only member is
	unbound. \\
- &	Argument is an \emph{output} argument.  Unless specified
	otherwise, output arguments need not to be unbound. For
	example, the goal \exam{findall(X, Goal, [T])} is good style and
	equivalent to \exam{findall(X, Goal, Xs), Xs = [T]}\footnote{The
	ISO standard dictates that \exam{findall(X, Goal, 1)} raises a
	\const{type_error} exception, breaking this semantic relation.
	SWI-Prolog does not follow the standard here.}  Note that the
	\jargon{determinism} specification, e.g., ``det'' only applies
	if this argument is unbound. \\
--&	Argument must be unbound.  Typically used by predicates that
	create `something' and return a handle to the created object,
	such as \index{open/3}\predref{open}{3} which creates a \jargon{stream}. \\
? &	Argument must be bound to a \emph{partial term} of the indicated
	type.  Note that a variable is a partial term for any type.
	Think of the argument as either \jargon{input} or \jargon{output} or
	\emph{both} input and output.  For example, in
	\exam{stream_property(S, reposition(Bool))}, the \const{reposition}
	part of the term is input and the uninstantiated \arg{Bool} is output. \\
: &	Argument is a meta-argument.  Implies \chr{\Splus}. See \chapref{modules}
	for more information on module handling. \\
@ &	Argument is not further instantiated. Typically used for type tests.\\
! &	Argument contains a mutable structure that may be modified using
	\index{setarg/3}\predref{setarg}{3} or \index{nb_setarg/3}\predref{nb_setarg}{3}. \\
\hline
\end{tabular}
\end{center}

\index{predicate indicator}%
Referring to a predicate in running text is done using a
\jargon{predicate indicator}. The canonical and most generic form of a
predicate indicator is a term \bnfmeta{module}:\bnfmeta{name}/\bnfmeta{arity}. If the module is
irrelevant (built-in predicate) or can be inferred from the context it
is often omitted. Compliant to the ISO standard draft on DCG (see
\secref{DCG}), SWI-Prolog also allows for [\bnfmeta{module}]:\bnfmeta{name}//\bnfmeta{arity} to
refer to a grammar rule. For all non-negative arity, \bnfmeta{name}//\bnfmeta{arity} is
the same as \bnfmeta{name}/\bnfmeta{arity}+2, regardless of whether or not the
referenced predicate is defined or can be used as a grammar rule.
The //-notation can be used in all places that traditionally allow
for a predicate indicator, e.g., the module declaration, \index{spy/1}\predref{spy}{1},
and \index{dynamic/1}\predref{dynamic}{1}.


\section{Character representation}		\label{sec:chars}

In traditional (Edinburgh) Prolog, characters are represented using
\jargon{character codes}. Character codes are integer indices into
a specific character set.  Traditionally the character set was 7-bit
US-ASCII. 8-bit character sets have been allowed for a long time, providing
support for national character sets, of which iso-latin-1 (ISO 8859-1)
is applicable to many Western languages.

ISO Prolog introduces three types, two of which are used for characters
and one for accessing binary streams (see \index{open/4}\predref{open}{4}).  These types are:

\begin{itemlist}
    \item [code]
A \jargon{character code} is an integer representing a single character.
As files may use multi-byte encoding for supporting different character
sets (\idx{utf-8} encoding for example), reading a code from a text file
is in general not the same as reading a byte.
    \item [char]
Alternatively, characters may be represented as
\jargon{one-character atoms}.  This is a natural representation,
hiding encoding problems from the programmer as well as providing much
easier debugging.
    \item [byte]
Bytes are used for accessing binary streams.
\end{itemlist}

In SWI-Prolog, character codes are \emph{always} the Unicode equivalent
of the encoding. That is, if \index{get_code/1}\predref{get_code}{1} reads from a stream encoded as
\const{KOI8-R} (used for the Cyrillic alphabet), it returns the
corresponding Unicode code points. Similarly, assembling or disassembling
atoms using \index{atom_codes/2}\predref{atom_codes}{2} interprets the codes as Unicode points.  See
\secref{encoding} for details.

To ease the pain of the two character representations (code and char),
SWI-Prolog's built-in predicates dealing with character data work as
flexible as possible: they accept data in any of these formats as long
as the interpretation is unambiguous. In addition, for output arguments
that are instantiated, the character is extracted before unification.
This implies that the following two calls are identical, both testing
whether the next input character is an \const{a}.

\begin{code}
peek_code(Stream, a).
peek_code(Stream, 97).
\end{code}

\noindent
The two character representations are handled by a large number of
built-in predicates, all of which are ISO-compatible. For converting
between code and character there is \index{char_code/2}\predref{char_code}{2}. For breaking atoms and
numbers into characters there are \index{atom_chars/2}\predref{atom_chars}{2}, \index{atom_codes/2}\predref{atom_codes}{2},
\index{number_chars/2}\predref{number_chars}{2} and \index{number_codes/2}\predref{number_codes}{2}. For character I/O on streams there are
\index{get_char/[1,2]}\predref{get_char}{[1,2]}, \index{get_code/[1,2]}\predref{get_code}{[1,2]}, \index{get_byte/[1,2]}\predref{get_byte}{[1,2]}, \index{peek_char/[1,2]}\predref{peek_char}{[1,2]},
\index{peek_code/[1,2]}\predref{peek_code}{[1,2]}, \index{peek_byte/[1,2]}\predref{peek_byte}{[1,2]}, \index{put_code/[1,2]}\predref{put_code}{[1,2]}, \index{put_char/[1,2]}\predref{put_char}{[1,2]} and
\index{put_byte/[1,2]}\predref{put_byte}{[1,2]}. The Prolog flag \prologflag{double_quotes} controls how
text between double quotes is interpreted.


\section{Loading Prolog source files}	\label{sec:consulting}

This section deals with loading Prolog source files. A Prolog source
file is a plain text file containing a Prolog program or part thereof.
Prolog source files come in three flavours:

\begin{description}
    \item [ A traditional ] Prolog source file contains Prolog
clauses and directives, but no \jargon{module declaration} (see
\index{module/1}\predref{module}{1}). They are normally loaded using \index{consult/1}\predref{consult}{1} or \index{ensure_loaded/1}\predref{ensure_loaded}{1}.
Currently, a non-module file can only be loaded into a single
module.\footnote{This limitation may be lifted in the future. Existing
limitations in SWI-Prolog's source code administration make this
non-trivial.}

    \item [ A module ] Prolog source file starts with a module
declaration.  The subsequent Prolog code is loaded into the
specified module, and only the \jargon{exported} predicates are
made available to the context loading the module.  Module files
are normally loaded with \index{use_module/[1,2]}\predref{use_module}{[1,2]}.  See \chapref{modules}
for details.

    \item [ An include ] Prolog source file is loaded using
the \index{include/1}\predref{include}{1} directive, textually including Prolog text into
another Prolog source.  A file may be included into multiple
source files and is typically used to share \jargon{declarations}
such as multifile or dynamic between source files.
\end{description}

Prolog source files are located using \index{absolute_file_name/3}\predref{absolute_file_name}{3} with
the following options:

\begin{code}
locate_prolog_file(Spec, Path) :-
        absolute_file_name(Spec,
                           [ file_type(prolog),
                             access(read)
                           ],
                           Path).
\end{code}

\noindent
The \term{file_type}{prolog} option is used to determine the extension
of the file using \index{prolog_file_type/2}\predref{prolog_file_type}{2}. The default extension is
\fileext{pl}.  \arg{Spec} allows for the \jargon{path alias} construct
defined by \index{absolute_file_name/3}\predref{absolute_file_name}{3}.  The most commonly used path alias
is \term{library}{LibraryFile}.  The example below loads the library
file \file{ordsets.pl} (containing predicates for manipulating ordered
sets).

\begin{code}
:- use_module(library(ordsets)).
\end{code}

\noindent
SWI-Prolog recognises grammar rules (\idx{DCG}) as defined in
\cite{Clocksin:87}. The user may define additional compilation of the
source file by defining the dynamic multifile predicates
\index{term_expansion/2}\predref{term_expansion}{2}, \index{term_expansion/4}\predref{term_expansion}{4}, \index{goal_expansion/2}\predref{goal_expansion}{2} and
\index{goal_expansion/4}\predref{goal_expansion}{4}. It is not allowed to use \index{assert/1}\predref{assert}{1}, \index{retract/1}\predref{retract}{1} or any
other database predicate in \index{term_expansion/2}\predref{term_expansion}{2} other than for local
computational purposes.\footnote{It does work for normal loading, but
not for \index{qcompile/1}\predref{qcompile}{1}.} Code that needs to create additional clauses must
use \index{compile_aux_clauses/1}\predref{compile_aux_clauses}{1}. See \pllib{library(apply_macros)} for an
example.

A \jargon{directive} is an instruction to the compiler. Directives are
used to set (predicate) properties (see \secref{declare}), set flags
(see \index{set_prolog_flag/2}\predref{set_prolog_flag}{2}) and load files (this section).  Directives are
terms of the form \mbox{\texttt{\Sneck} \bnfmeta{term}.}.  Here are some examples:

\begin{code}
:- use_module(library(lists)).
:- dynamic
        store/2.                % Name, Value
\end{code}

\noindent
The directive \index{initialization/1}\predref{initialization}{1} can be used to run arbitrary Prolog
goals.  The specified goal is started \emph{after} loading the file
in which it appears has completed.

SWI-Prolog compiles code as it is read from the file, and directives are
executed as \jargon{goals}. This implies that directives may call any
predicate that has been defined before the point where the directive
appears. It also accepts \mbox{\texttt{\Sdirective} \bnfmeta{term}.} as a synonym.

\index{reconsult}%
SWI-Prolog does not have a separate \nopredref{reconsult}{1} predicate.
Reconsulting is implied automatically by the fact that a file is
consulted which is already loaded.

Advanced topics are handled in subsequent sections: mutually dependent
files (\secref{depload}), multithreaded loading (\secref{mtload}) and
reloading running code (\secref{loadrunningcode}).

The core of the family of loading predicates is \index{load_files/2}\predref{load_files}{2}.  The predicates
\index{consult/1}\predref{consult}{1}, \index{ensure_loaded/1}\predref{ensure_loaded}{1}, \index{use_module/1}\predref{use_module}{1}, \index{use_module/2}\predref{use_module}{2} and \index{reexport/1}\predref{reexport}{1} pass the
file argument directly to \index{load_files/2}\predref{load_files}{2} and pass additional options as expressed
in the \tabref{loadpreds}:

\begin{table}
\begin{center}
\begin{tabular}{lccc}
\hline
\bf Predicate	& \bf if	     & \bf must_be_module & \bf import \\
\hline
\index{consult/1}\predref{consult}{1}	& \const{true}	     & \const{false} & all \\
\index{ensure_loaded/1}\predref{ensure_loaded}{1}	& \const{not_loaded} & \const{false} & all \\
\index{use_module/1}\predref{use_module}{1}	& \const{not_loaded} & \const{true}  & all\\
\index{use_module/2}\predref{use_module}{2}	& \const{not_loaded} & \const{true}  & specified \\
\index{reexport/1}\predref{reexport}{1}	& \const{not_loaded} & \const{true}  & all \\
\index{reexport/2}\predref{reexport}{2}	& \const{not_loaded} & \const{true}  & specified \\
\hline
\end{tabular}
\end{center}
    \caption{Properties of the file-loading predicates. The \textit{import}
	     column specifies what is imported if the loaded file is a module
	     file.}
    \label{tab:loadpreds}
\end{table}

\begin{description}
    \predicate{load_files}{1}{:Files}
Equivalent to \term{load_files}{Files, []}.  Same as \index{consult/1}\predref{consult}{1},
See \index{load_files/2}\predref{load_files}{2} for supported options.
    \predicate{load_files}{2}{:Files, +Options}
The predicate \index{load_files/2}\predref{load_files}{2} is the parent of all the other loading
predicates except for \index{include/1}\predref{include}{1}. It currently supports a subset
of the options of Quintus \index{load_files/2}\predref{load_files}{2}. \arg{Files} is either
a single source file or a list of source files. The specification for a
source file is handed to \index{absolute_file_name/2}\predref{absolute_file_name}{2}. See this predicate for
the supported expansions. \arg{Options} is a list of options using the
format \arg{OptionName}(\arg{OptionValue}).

The following options are currently supported:

\begin{description}
    \termitem{autoload}{Bool}
If \const{true} (default \const{false}), indicate that this load is a
\jargon{demand} load. This implies that, depending on the setting of the
Prolog flag \prologflag{verbose_autoload}, the load action is printed at
level \const{informational} or \const{silent}.  See also \index{print_message/2}\predref{print_message}{2}
and \index{current_prolog_flag/2}\predref{current_prolog_flag}{2}.

    \termitem{check_script}{Bool}
If \const{false} (default \const{true}), do not check the first
character to be \chr{\Shash} and skip the first line when found.

    \termitem{derived_from}{File}
Indicate that the loaded file is derived from \arg{File}.  Used by
\index{make/0}\predref{make}{0} to time-check and load the original file rather than the derived
file.

    \termitem{dialect}{+Dialect}
Load \arg{Files} with enhanced compatibility with the target Prolog
system identified by \arg{Dialect}.  See \index{expects_dialect/1}\predref{expects_dialect}{1} and
\secref{dialect} for details.

    \termitem{encoding}{Encoding}
Specify the way characters are encoded in the file.  Default is taken
from the Prolog flag \prologflag{encoding}.  See \secref{encoding} for
details.

    \termitem{expand}{Bool}
If \const{true}, run the filenames through \index{expand_file_name/2}\predref{expand_file_name}{2} and load
the returned files.  Default is \const{false}, except for \index{consult/1}\predref{consult}{1}
which is intended for interactive use.  Flexible location of files
is defined by \index{file_search_path/2}\predref{file_search_path}{2}.

    \termitem{format}{+Format}
Used to specify the file format if data is loaded from a stream using
the \term{stream}{Stream} option. Default is \const{source}, loading
Prolog source text.  If \const{qlf}, load QLF data (see \index{qcompile/1}\predref{qcompile}{1}).

    \termitem{if}{Condition}
Load the file only if the specified condition is satisfied. The value
\const{true} loads the file unconditionally, \const{changed} loads the
file if it was not loaded before or has been modified since it was
loaded the last time, and \const{not_loaded} loads the file if it was not
loaded before.

    \termitem{imports}{Import}
Specify what to import from the loaded module. The default for
\index{use_module/1}\predref{use_module}{1} is \const{all}. \arg{Import} is passed from the second
argument of \index{use_module/2}\predref{use_module}{2}. Traditionally it is a list of predicate
indicators to import. As part of the SWI-Prolog/YAP integration, we also
support \arg{Pred} as \arg{Name} to import a predicate under another
name. Finally, \arg{Import} can be the term \term{except}{Exceptions},
where \arg{Exceptions} is a list of predicate indicators that specify
predicates that are \emph{not} imported or \arg{Pred} as \arg{Name}
terms to denote renamed predicates. See also \index{reexport/2}\predref{reexport}{2} and
\index{use_module/2}\predref{use_module}{2}.%
	\bug{\arg{Name}/\arg{Arity} as \arg{NewName} is currently
	     implemented using a \jargon{link clause}.  This harms
	     efficiency and does not allow for querying the relation
	     through \index{predicate_property/2}\predref{predicate_property}{2}.}

If \arg{Import} equals \const{all}, all operators are imported as well.
Otherwise, operators are \emph{not} imported. Operators can be imported
selectively by adding terms \term{op}{Pri,Assoc,Name} to the
\arg{Import} list. If such a term is encountered, all exported
operators that unify with this term are imported. Typically, this
construct will be used with all arguments unbound to import all
operators or with only \arg{Name} bound to import a particular operator.

    \termitem{modified}{TimeStamp}
Claim that the source was loaded at \arg{TimeStamp} without
checking the source.  This option is intended to be used together with
the \term{stream}{Input} option, for example after extracting the time
from an HTTP server or database.

    \termitem{module}{+Module}
Load the indicated file into the given module, overruling the module
name specified in the \exam{:- module(Name, ...)} directive. This
currently serves two purposes: (1) allow loading two module files that
specify the same module	into the same process and force and (2): force
loading source code in a specific module, even if the code provides its
own module name.  Experimental.

    \termitem{must_be_module}{Bool}
If \const{true}, raise an error if the file is not a module file.  Used by
\index{use_module/[1,2]}\predref{use_module}{[1,2]}.

    \termitem{qcompile}{Atom}
How to deal with quick-load-file compilation by \index{qcompile/1}\predref{qcompile}{1}.  Values are:

    \begin{description}
	\termitem{never}{}
Default.  Do not use qcompile unless called explicitly.
	\termitem{auto}{}
Use qcompile for all writeable files.  See comment below.
	\termitem{large}{}
Use qcompile if the file is `large'. Currently, files larger than
100~Kbytes are considered large.
        \termitem{part}{}
If \index{load_files/2}\predref{load_files}{2} appears in a directive of a file that is compiled
into Quick Load Format using \index{qcompile/1}\predref{qcompile}{1}, the contents of the argument
files are included in the \fileext{qlf} file instead of the loading
directive.
    \end{description}

If this option is not present, it uses the value of the Prolog
flag \prologflag{qcompile} as default.

    \termitem{optimise}{+Boolean}
Explicitly set the optimization for compiling this module.  See
\prologflag{optimise}.

    \termitem{redefine_module}{+Action}
Defines what to do if a file is loaded that provides a module that is
already loaded from another file. \arg{Action} is one of \const{false}
(default), which prints an error and refuses to load the file, or
\const{true}, which uses \index{unload_file/1}\predref{unload_file}{1} on the old file and then proceeds
loading the new file. Finally, there is \const{ask}, which starts
interaction with the user. \const{ask} is only provided if the
stream \const{user_input} is associated with a terminal.

    \termitem{reexport}{Bool}
If \const{true} re-export the imported predicate.  Used by \index{reexport/1}\predref{reexport}{1}
and \index{reexport/2}\predref{reexport}{2}.

    \termitem{register}{Bool}
If \const{false}, do not register the load location and options.  This
option is used by \index{make/0}\predref{make}{0} and \libpredref{load_hotfixes}{1} to avoid
polluting the load-context database. See \index{source_file_property/2}\predref{source_file_property}{2}.

    \termitem{sandboxed}{Bool}
Load the file in \jargon{sandboxed} mode.  This option controls the
flag \prologflag{sandboxed_load}. The only meaningful value for
\arg{Bool} is \const{true}.  Using \const{false} while the Prolog
flag is set to \const{true} raises a permission error.

    \termitem{scope_settings}{Bool}
Scope \index{style_check/1}\predref{style_check}{1} and \index{expects_dialect/1}\predref{expects_dialect}{1} to the file and files loaded
from the file after the directive.  Default is \const{true}.  The system
and user initialization files (see \cmdlineoption{-f} and
\cmdlineoption{-F}) are loading with \term{scope_settings}{false}.

    \termitem{silent}{Bool}
If \const{true}, load the file without printing a message. The
specified value is the default for all files loaded as a result of
loading the specified files. This option writes the Prolog flag
\prologflag{verbose_load} with the negation of \arg{Bool}.

    \termitem{stream}{Input}
This SWI-Prolog extension compiles the data from the stream
\arg{Input}.  If this option is used, \arg{Files} must be a single atom
which is used to identify the source location of the loaded clauses as
well as to remove all clauses if the data is reconsulted.

This option is added to allow compiling from non-file locations such as
databases, the web, the \jargon{user} (see \index{consult/1}\predref{consult}{1}) or other servers.
It can be combined with \term{format}{qlf} to load QLF data from a
stream.
\end{description}

The \index{load_files/2}\predref{load_files}{2} predicate can be hooked to load other data or data from
objects other than files.  See \index{prolog_load_file/2}\predref{prolog_load_file}{2} for a description and
\pllib{http/http_load} for an example. All hooks for \index{load_files/2}\predref{load_files}{2} are
documented in \secref{loadfilehook}.

    \predicate{consult}{1}{:File}
Read \arg{File} as a Prolog source file. Calls to \index{consult/1}\predref{consult}{1} may be
abbreviated by just typing a number of filenames in a list. Examples:

\begin{center}\begin{tabular}{ll}
\exam{?- consult(load).}     & \% consult \file{load} or \file{load.pl} \\
\exam{?- [library(lists)].}  & \% load library lists \\
\exam{?- [user].}	     & \% Type program on the terminal \\
\end{tabular}\end{center}

The predicate \index{consult/1}\predref{consult}{1} is equivalent to \verb$load_files(File, [])$,
except for handling the special file \const{user}, which reads clauses
from the terminal. See also the \term{stream}{Input} option of
\index{load_files/2}\predref{load_files}{2}. Abbreviation using \verb$?- [file1,file2].$ does
\emph{not} work for the empty list (\verb$[]$). This facility is
implemented by defining the list as a predicate. Applications may
only rely on using the list abbreviation at the Prolog toplevel and
in directives.

    \predicate{ensure_loaded}{1}{:File}
If the file is not already loaded, this is equivalent to \index{consult/1}\predref{consult}{1}.
Otherwise, if the file defines a module, import all public predicates.
Finally, if the file is already loaded, is not a module file, and the
context module is not the global user module, \index{ensure_loaded/1}\predref{ensure_loaded}{1} will
call \index{consult/1}\predref{consult}{1}.

With this semantics, we hope to get as close as possible to the clear
semantics without the presence of a module system.  Applications using
modules should consider using \index{use_module/[1,2]}\predref{use_module}{[1,2]}.

Equivalent to \verb$load_files(Files, [if(not_loaded)]).$%
	\footnote{On older versions the condition used to be
		  \exam{if(changed)}. Poor time management on some
		  machines or copying often caused problems. The \index{make/0}\predref{make}{0}
		  predicate deals with updating the running system after
		  changing the source code.}

    \predicate[ISO]{include}{1}{+File}
Textually include the content of \arg{File} at the position where the
\jargon{directive} \exam{:- include(File).} appears. The include
construct is only honoured if it appears as a directive in a
source file. \jargon{Textual} include (similar to C/C++ \#include) is
obviously useful for sharing declarations such as \index{dynamic/1}\predref{dynamic}{1} or
\index{multifile/1}\predref{multifile}{1} by including a file with directives from multiple files that
use these predicates.

Textually including files that contain \emph{clauses} is less obvious.
Normally, in SWI-Prolog, clauses are \emph{owned} by the file in which
they are defined. This information is used to \emph{replace} the old
definition after the file has been modified and is reloaded by, e.g.,
\index{make/0}\predref{make}{0}. As we understand it, \index{include/1}\predref{include}{1} is intended to include the same
file multiple times. Including a file holding clauses multiple times
into the same module is rather meaningless as it just duplicates the
same clauses. Including a file holding clauses in multiple modules
does not suffer from this problem, but leads to multiple equivalent
\emph{copies} of predicates. Using \index{use_module/1}\predref{use_module}{1} can achieve the same
result while \emph{sharing} the predicates.

If \index{include/1}\predref{include}{1} is used to load files holding clauses, and if these files
are loaded only once, then these \index{include/1}\predref{include}{1} directives can be replaced by
other predicates (such as \index{consult/1}\predref{consult}{1}). However, there are several cases
where either \index{include/1}\predref{include}{1} has no alternative, or using any alternative also
requires other changes. An example of the former is using \index{include/1}\predref{include}{1} to
share directives. An example of the latter are cases where clauses of
different predicates are distributed over multiple files: If these files
are loaded with \index{include/1}\predref{include}{1}, the directive \index{discontiguous/1}\predref{discontiguous}{1} is appropriate,
whereas if they are consulted, one must use the directive \index{multifile/1}\predref{multifile}{1}.

To accommodate included files holding clauses, SWI-Prolog distinguishes
between the source location of a clause (in this case the included
file) and the \jargon{owner} of a clause (the file that includes the
file holding the clause).  The source location is used by, e.g., \index{edit/1}\predref{edit}{1},
the graphical tracer, etc., while the owner is used to determine which
clauses are removed if the file is modified.  Relevant information is
found with the following predicates:

    \begin{itemize}

    \item \index{source_file/2}\predref{source_file}{2} describes the owner relation.
    \item \index{predicate_property/2}\predref{predicate_property}{2} describes the source location (of the
          first clause).
    \item \index{clause_property/2}\predref{clause_property}{2} provides access to both source and ownership.
    \item \index{source_file_property/2}\predref{source_file_property}{2} can be used to query include relationships
          between files.
    \end{itemize}

    \predicate{require}{1}{+ListOfNameAndArity}
Declare that this file/module requires the specified predicates to be
defined ``with their commonly accepted definition''.  This predicate
originates from the Prolog portability layer for XPCE.  It is intended
to provide a portable mechanism for specifying that this module requires
the specified predicates.

The implementation normally first verifies whether the predicate is
already defined.  If not, it will search the libraries and load the
required library.

SWI-Prolog, having autoloading, does {\bf not} load the library. Instead
it creates a procedure header for the predicate if it does not exist.
This will flag the predicate as `undefined'.  See also \index{check/0}\predref{check}{0} and
\index{autoload/0}\predref{autoload}{0}.

    \predicate{encoding}{1}{+Encoding}
This directive can appear anywhere in a source file to define how
characters are encoded in the remainder of the file.  It can be
used in files that are encoded with a superset of US-ASCII,
currently UTF-8 and ISO Latin-1.  See also \secref{encoding}.

    \predicate{make}{0}{}
Consult all source files that have been changed since they were
consulted.  It checks \arg{all} loaded source files: files loaded into a
compiled state using \exam{pl -c \ldots} and files loaded using \index{consult/1}\predref{consult}{1}
or one of its derivatives. The predicate \index{make/0}\predref{make}{0} is called after
\index{edit/1}\predref{edit}{1}, automatically reloading all modified files.  If the user uses
an external editor (in a separate window), \index{make/0}\predref{make}{0} is normally used to
update the program after editing.  In addition, \index{make/0}\predref{make}{0} updates the
autoload indices (see \secref{autoload}) and runs \index{list_undefined/0}\predref{list_undefined}{0}
from the \pllib{check} library to report on undefined predicates.

    \predicate{library_directory}{1}{?Atom}
Dynamic predicate used to specify library directories. Default
\file{./lib}, \file{~/lib/prolog} and the system's library (in this
order) are defined. The user may add library directories using
\index{assertz/1}\predref{assertz}{1}, \index{asserta/1}\predref{asserta}{1} or remove system defaults using \index{retract/1}\predref{retract}{1}.
Deprecated. New code should use \index{file_search_path/2}\predref{file_search_path}{2}.

    \predicate{file_search_path}{2}{+Alias, -Path}
Dynamic multifile hook predicate used to specify `path aliases'. This
hook is called by \index{absolute_file_name/3}\predref{absolute_file_name}{3} to search files specified as
\term{Alias}{Name}, e.g., \term{library}{lists}. This feature is best
described using an example. Given the definition:

\begin{code}
file_search_path(demo, '/usr/lib/prolog/demo').
\end{code}

\noindent
the file specification \file{demo(myfile)} will be expanded to
\file{/usr/lib/prolog/demo/myfile}. The second argument of
\index{file_search_path/2}\predref{file_search_path}{2} may be another alias.

Below is the initial definition of the file search path.  This path
implies \metafile{swi(\bnfmeta{Path})} and refers to a file in the SWI-Prolog home
directory.  The alias \metafile{foreign(\bnfmeta{Path})} is intended for storing
shared libraries (\fileext{so} or \fileext{DLL} files).  See also
\index{use_foreign_library/1}\predref{use_foreign_library}{1}.

\begin{code}
user:file_search_path(library, X) :-
        library_directory(X).
user:file_search_path(swi, Home) :-
        current_prolog_flag(home, Home).
user:file_search_path(foreign, swi(ArchLib)) :-
        current_prolog_flag(arch, Arch),
        atom_concat('lib/', Arch, ArchLib).
user:file_search_path(foreign, swi(lib)).
user:file_search_path(path, Dir) :-
        getenv('PATH', Path),
        (   current_prolog_flag(windows, true)
        ->  atomic_list_concat(Dirs, (;), Path)
        ;   atomic_list_concat(Dirs, :, Path)
        ),
        member(Dir, Dirs).
\end{code}

\noindent
The \index{file_search_path/2}\predref{file_search_path}{2} expansion is used by all loading predicates as
well as by \index{absolute_file_name/[2,3]}\predref{absolute_file_name}{[2,3]}.

The Prolog flag \prologflag{verbose_file_search} can be set to \const{true}
to help debugging Prolog's search for files.

    \predicate[nondet]{expand_file_search_path}{2}{+Spec, -Path}
Unifies \arg{Path} with all possible expansions of the filename
specification \arg{Spec}.  See also \index{absolute_file_name/3}\predref{absolute_file_name}{3}.

    \predicate{prolog_file_type}{2}{?Extension, ?Type}
This dynamic multifile predicate defined in module \module{user}
determines the extensions considered by \index{file_search_path/2}\predref{file_search_path}{2}.
\arg{Extension} is the filename extension without the leading dot, and
\arg{Type} denotes the type as used by the \term{file_type}{Type}
option of \index{file_search_path/2}\predref{file_search_path}{2}.  Here is the initial definition of
\index{prolog_file_type/2}\predref{prolog_file_type}{2}:

\begin{code}
user:prolog_file_type(pl,       prolog).
user:prolog_file_type(Ext,      prolog) :-
        current_prolog_flag(associate, Ext),
        Ext \== pl.
user:prolog_file_type(qlf,      qlf).
user:prolog_file_type(Ext,      executable) :-
        current_prolog_flag(shared_object_extension, Ext).
\end{code}

\noindent
Users can add extensions for Prolog source files to avoid conflicts
(for example with \program{perl}) as well as to be compatible with
another Prolog implementation. We suggest using \fileext{pro} for
avoiding conflicts with \program{perl}. Overriding the system
definitions can stop the system from finding libraries.

    \predicate{source_file}{1}{?File}
True if \arg{File} is a loaded Prolog source file.  \arg{File} is
the absolute and canonical path to the source file.

    \predicate{source_file}{2}{:Pred, ?File}
True if the predicate specified by \arg{Pred} is owned by file
\arg{File}, where \arg{File} is an absolute path name (see
\index{absolute_file_name/2}\predref{absolute_file_name}{2}). Can be used with any instantiation pattern, but
the database only maintains the source file for each predicate. If
\arg{Pred} is a \jargon{multifile} predicate this predicate succeeds for
all files that contribute clauses to \arg{Pred}.\footnote{The current
implementation performs a linear scan through all clauses to establish
this set of files.} See also \index{clause_property/2}\predref{clause_property}{2}. Note that the relation
between files and predicates is more complicated if \index{include/1}\predref{include}{1} is used.
The predicate describes the \jargon{owner} of the predicate. See
\index{include/1}\predref{include}{1} for details.

    \predicate{source_file_property}{2}{?File, ?Property}
True when \arg{Property} is a property of the loaded file \arg{File}.
If \arg{File} is non-var, it can be a file specification that is valid
for \index{load_files/2}\predref{load_files}{2}.  Defined properties are:

    \begin{description}
	\termitem{derived_from}{Original, OriginalModified}
\arg{File} was generated from the file \arg{Original}, which was
last modified at time \arg{OriginalModified} at the time it was loaded.
This property is available if \arg{File} was loaded using the
\term{derived_from}{Original} option to \index{load_files/2}\predref{load_files}{2}.

	\termitem{includes}{IncludedFile, IncludedFileModified}
\arg{File} used \index{include/1}\predref{include}{1} to include \arg{IncludedFile}. The
last modified time of \arg{IncludedFile} was \arg{IncludedFileModified}
at the time it was included.

	\termitem{included_in}{MasterFile, Line}
\arg{File} was included into \arg{MasterFile} from line \arg{Line}. This
is the inverse of the \const{includes} property.

	\termitem{load_context}{Module, Location, Options}
\arg{Module} is the module into which the file was loaded. If \arg{File}
is a module, this is the module into which the exports are imported.
Otherwise it is the module into which the clauses of the non-module
file are loaded.  \arg{Location} describes the file location from which
the file was loaded.  It is either a term \bnfmeta{file}:\bnfmeta{line} or the atom
\const{user} if the file was loaded from the terminal or another unknown
source. \arg{Options} are the options passed to \index{load_files/2}\predref{load_files}{2}. Note that
all predicates to load files are mapped to \index{load_files/2}\predref{load_files}{2}, using the
option argument to specify the exact behaviour.

	\termitem{load_count}{-Count}
\arg{Count} is the number of times the file have been loaded, i.e.,
1 (one) if the file has been loaded once.

	\termitem{modified}{Stamp}
File modification time when \arg{File} was loaded.  This is used by
\index{make/0}\predref{make}{0} to find files whose modification time is different from when
it was loaded.

	\termitem{source}{Source}
One of \const{file} if the source was loaded from a file,
\const{resource} if the source was loaded from a resource or
\const{state} if the file was included in the saved state.

	\termitem{module}{Module}
\arg{File} is a module file that declares the module \arg{Module}.

	\termitem{number_of_clauses}{Count}
\arg{Count} is the number of clauses associated with \arg{File}.
Note that clauses loaded from included files are counted as part
of the main file.

	\termitem{reloading}{}
Present if the file is currently being \textbf{re}loaded.
    \end{description}

    \predicate{unload_file}{1}{+File}
Remove all clauses loaded from \arg{File}.  If \arg{File} loaded a
module, clear the module's export list and disassociate it from the
file.  \arg{File} is a canonical filename or a file indicator that is
valid for \index{load_files/2}\predref{load_files}{2}.

This predicate should be used with care. The multithreaded nature of
SWI-Prolog makes removing static code unsafe. Attempts to do this should
be reserved for development or situations where the application can
guarantee that none of the clauses associated to \arg{File} are active.

    \predicate{prolog_load_context}{2}{?Key, ?Value}
Obtain context information during compilation.  This predicate can be
used from directives appearing in a source file to get information about
the file being loaded as well as by the \index{term_expansion/2}\predref{term_expansion}{2} and
\index{goal_expansion/2}\predref{goal_expansion}{2} hooks. See also \index{source_location/2}\predref{source_location}{2} and \index{if/1}\predref{if}{1}. The
following keys are defined:

\begin{center}
\begin{tabular}{|l|p{\linewidth-35mm}|}
\hline
\bf Key               & \bf Description \\
\hline
\const{directory}     & Directory in which \const{source} lives \\
\const{dialect}	      & Compatibility mode.  See \index{expects_dialect/1}\predref{expects_dialect}{1}. \\
\const{file}          & Similar to \const{source}, but returns the file
			being included when called while an include file
			is being processed \\
\const{module}        & Module into which file is loaded \\
\const{reload}	      & \const{true} if the file is being
			\textbf{re}loaded.  Not present on first load \\
\const{script}	      & Boolean that indicates whether the file is
			loaded as a script file (see
			\cmdlineoption{-s}) \\
\const{source}        & File being loaded.  If the system is processing an
			included file, the value is the \emph{main} file.
			Returns the original Prolog file when loading a
			\fileext{qlf} file. \\
\const{stream}        & Stream identifier (see \index{current_input/1}\predref{current_input}{1}) \\
\const{term_position} & Start position of last term read.  See also
			\index{stream_property/2}\predref{stream_property}{2} (\const{position} property and
			\index{stream_position_data/3}\predref{stream_position_data}{3}.\footnote{Up to version
			7.1.22, the position term carried fake data
			except for the \const{line_count} and had
			\textbf{five} arguments, where the position
			property of a stream only has \textbf{four}.} \\
\const{term}	      & Term being expanded by \index{expand_term/2}\predref{expand_term}{2}. \\
\const{variable_names}& A list of `\arg{Name} = \arg{Var}' of the last
			term read.  See \index{read_term/2}\predref{read_term}{2} for details. \\
\hline
\end{tabular}
\end{center}

The \const{directory} is commonly used to add rules to \index{file_search_path/2}\predref{file_search_path}{2},
setting up a search path for finding files with \index{absolute_file_name/3}\predref{absolute_file_name}{3}.
For example:

\begin{code}
:- dynamic user:file_search_path/2.
:- multifile user:file_search_path/2.

:- prolog_load_context(directory, Dir),
   asserta(user:file_search_path(my_program_home, Dir)).

    ...
    absolute_file_name(my_program_home('README.TXT'), ReadMe,
                       [ access(read) ]),
    ...
\end{code}

\noindent
    \predicate{source_location}{2}{-File, -Line}
If the last term has been read from a physical file (i.e., not from the
file \const{user} or a string), unify \arg{File} with an absolute path to
the file and \arg{Line} with the line number in the file. New code
should use \index{prolog_load_context/2}\predref{prolog_load_context}{2}.

    \predicate{at_halt}{1}{:Goal}
Register \arg{Goal} to be run from \cfuncref{PL_cleanup}{}, which is called when
the system halts. The hooks are run in the reverse order they were
registered (FIFO). Success or failure executing a hook is ignored. If
the hook raises an exception this is printed using \index{print_message/2}\predref{print_message}{2}. An
attempt to call \index{halt/[0,1]}\predref{halt}{[0,1]} from a hook is ignored. Hooks may call
\index{cancel_halt/1}\predref{cancel_halt}{1}, causing \index{halt/0}\predref{halt}{0} and \cfuncref{PL_halt}{0} to print a message
indicating that halting the system has been cancelled.

    \predicate{cancel_halt}{1}{+Reason}
If this predicate is called from a hook registered with \index{at_halt/1}\predref{at_halt}{1},
halting Prolog is cancelled and an informational message is printed
that includes \arg{Reason}.  This is used by the development tools
to cancel halting the system if the editor has unsafed data and the
user decides to cancel.

    \directive[ISO]{initialization}{1}{:Goal}
Call \arg{Goal} \emph{after} loading the source file in which this
directive appears has been completed. In addition, \arg{Goal} is
executed if a saved state created using \index{qsave_program/1}\predref{qsave_program}{1} is restored.

The ISO standard only allows for using \exam{:- Term} if \arg{Term} is a
\emph{directive}. This means that arbitrary goals can only be called
from a directive by means of the \index{initialization/1}\predref{initialization}{1} directive. SWI-Prolog
does not enforce this rule.

The \index{initialization/1}\predref{initialization}{1} directive must be used to do program initialization
in saved states (see \index{qsave_program/1}\predref{qsave_program}{1}). A saved state contains the
predicates, Prolog flags and operators present at the moment the state
was created.  Other resources (records, foreign resources, etc.) must
be recreated using \index{initialization/1}\predref{initialization}{1} directives or from the entry goal
of the saved state.

Up to SWI-Prolog 5.7.11, \arg{Goal} was executed immediately rather than
after loading the program text in which the directive appears as
dictated by the ISO standard. In many cases the exact moment of
execution is irrelevant, but there are exceptions. For example,
\index{load_foreign_library/1}\predref{load_foreign_library}{1} must be executed immediately to make the loaded
foreign predicates available for exporting. SWI-Prolog now provides the
directive \index{use_foreign_library/1}\predref{use_foreign_library}{1} to ensure immediate loading as well as
loading after restoring a saved state. If the system encounters a
directive \exam{:- initialization(load_foreign_library(...))}, it will
load the foreign library immediately and issue a warning to update your
code. This behaviour can be extended by providing clauses for the
multifile hook predicate \term{prolog:initialize_now}{Term, Advice},
where \arg{Advice} is an atom that gives advice on how to resolve the
compatibility issue.

    \predicate{initialization}{2}{:Goal, +When}
Similar to \index{initialization/1}\predref{initialization}{1}, but allows for specifying when \arg{Goal}
is executed while loading the program text:

\begin{description}
    \termitem{now}{} Execute \arg{Goal} immediately.

    \termitem{after_load}{} Execute \arg{Goal} after loading the
program text in which the directive appears. This is the same as
\index{initialization/1}\predref{initialization}{1}.

    \termitem{prepare_state}{}
Execute \arg{Goal} as part of \index{qsave_program/2}\predref{qsave_program}{2}.  This hook can be
used for example to eagerly execute initialization that is normally
done lazily on first usage.

    \termitem{restore_state}{}
Do not execute \arg{Goal} while loading the program, but \emph{only}
when restoring a saved state.\footnote{Used to be called
\const{restore}. \const{restore} is still accepted for backward
compatibility.}

    \termitem{program}{}
Execute \arg{Goal} once after executing the \cmdlineoption{-g} goals
at program startup. Registered goals are executed in the order
encountered and a failure or exception causes the Prolog to exit with
non-zero exit status.  These goals are \emph{not} executed if the
\cmdlineoption{-l} is given to merely \emph{load} files.  In that case
they may be executed explicitly using \index{initialize/0}\predref{initialize}{0}. See also
\secref{plscript}.

    \termitem{main}{}
When Prolog starts, the last goal registered using
\term{initialization}{Goal, main} is executed as main goal. If
\arg{Goal} fails or raises an exception, the process terminates with
non-zero exit code. If not explicitly specified using the
\cmdlineoption{-t} the \jargon{toplevel goal} is set to \index{halt/0}\predref{halt}{0}, causing
the process to exit with status 0. An explicitly specified toplevel is
executed normally. This implies that \exam{-t prolog} causes the
application to start the normal interactive toplevel after completing
\arg{Goal}.  See also the Prolog flag \prologflag{toplevel_goal} and
\secref{plscript}.
\end{description}

    \predicate[det]{initialize}{0}{}
Run all initialization goals registered using
\term{initialization}{Goal, program}. Raises an error
\term{initialization_error}{Reason, Goal, File:Line} if \arg{Goal}
fails or raises an exception.  \arg{Reason} is \const{failed} or
the exception raised.

    \predicate{compiling}{0}{}
True if the system is compiling source files with the \cmdlineoption{-c}
option or \index{qcompile/1}\predref{qcompile}{1} into an intermediate code file. Can be used to
perform conditional code optimisations in \index{term_expansion/2}\predref{term_expansion}{2} (see also the
\cmdlineoption{-O} option) or to omit execution of directives during
compilation.
\end{description}


\subsection{Conditional compilation and program transformation}
\label{sec:progtransform}

\index{transformation,of program}%
ISO Prolog defines no way for program transformations such as macro
expansion or conditional compilation. Expansion through \index{term_expansion/2}\predref{term_expansion}{2}
and \index{expand_term/2}\predref{expand_term}{2} can be seen as part of the de-facto standard.  This
mechanism can do arbitrary translation between valid Prolog terms read
from the source file to Prolog terms handed to the compiler.  As
\index{term_expansion/2}\predref{term_expansion}{2} can return a list, the transformation does not need
to be term-to-term.

Various Prolog dialects provide the analogous \index{goal_expansion/2}\predref{goal_expansion}{2} and
\index{expand_goal/2}\predref{expand_goal}{2} that allow for translation of individual body terms,
freeing the user of the task to disassemble each clause.

\begin{description}
    \predicate{term_expansion}{2}{+Term1, -Term2}
Dynamic and multifile predicate, normally not defined. When defined by
the user all terms read during consulting are given to this
predicate. If the predicate succeeds Prolog will assert \arg{Term2} in
the database rather than the read term (\arg{Term1}). \arg{Term2} may be
a term of the form \exam{?- Goal.} or \exam{:- Goal}. \arg{Goal} is
then treated as a directive. If \arg{Term2} is a list, all terms of the
list are stored in the database or called (for directives). If
\arg{Term2} is of the form below, the system will assert \arg{Clause}
and record the indicated source location with it:

\begin{quote}
\mbox{\tt '\$source_location'(\bnfmeta{File}, \bnfmeta{Line}):\bnfmeta{Clause}}
\end{quote}

When compiling a module (see \chapref{modules} and the directive \index{module/2}\predref{module}{2}),
\index{expand_term/2}\predref{expand_term}{2} will first try \index{term_expansion/2}\predref{term_expansion}{2} in the module being
compiled to allow for term expansion rules that are local to a module.
If there is no local definition, or the local definition fails to
translate the term, \index{expand_term/2}\predref{expand_term}{2} will try \index{term_expansion/2}\predref{term_expansion}{2} in module
\module{user}. For compatibility with SICStus and Quintus Prolog, this
feature should not be used. See also \index{expand_term/2}\predref{expand_term}{2}, \index{goal_expansion/2}\predref{goal_expansion}{2} and
\index{expand_goal/2}\predref{expand_goal}{2}.

    \predicate{expand_term}{2}{+Term1, -Term2}
This predicate is normally called by the compiler on terms read from the
input to perform preprocessing.  It consists of four steps, where each
step processes the output of the previous step.

    \begin{enumerate}
        \item Test conditional compilation directives and translate
	all input to \verb$[]$ if we are in a `false branch' of the
	conditional compilation.  See \secref{conditionalcompilation}.

	\item Call \index{term_expansion/2}\predref{term_expansion}{2}.  This predicate is first tried in
	the module that is being compiled and then in modules from which
	this module inherits according to \index{default_module/2}\predref{default_module}{2}.  The output
	of the expansion in a module is used as input for the next
	module.  Using the default setup and when compiling a normal
	application module \arg{M}, this implies expansion is executed
	in \arg{M}, \const{user} and finally in \const{system}.  Library
	modules inherit directly from \const{system} and can thus not be
	re-interpreted by term expansion rules in \const{user}.

	\item Call DCG expansion (\index{dcg_translate_rule/2}\predref{dcg_translate_rule}{2}).

	\item Call \index{expand_goal/2}\predref{expand_goal}{2} on each body term that appears in
	the output of the previous steps.
    \end{enumerate}

    \predicate{goal_expansion}{2}{+Goal1, -Goal2}
Like \index{term_expansion/2}\predref{term_expansion}{2}, \index{goal_expansion/2}\predref{goal_expansion}{2} provides for macro expansion
of Prolog source code. Between \index{expand_term/2}\predref{expand_term}{2} and the actual compilation,
the body of clauses analysed and the goals are handed to \index{expand_goal/2}\predref{expand_goal}{2},
which uses the \index{goal_expansion/2}\predref{goal_expansion}{2} hook to do user-defined expansion.

The predicate \index{goal_expansion/2}\predref{goal_expansion}{2} is first called in the module that is
being compiled, and then follows the module inheritance path as defined
by \index{default_module/2}\predref{default_module}{2}, i.e., by default \const{user} and \const{system}.
If \arg{Goal} is of the form \arg{Module}:\arg{Goal} where \arg{Module}
is instantiated, \index{goal_expansion/2}\predref{goal_expansion}{2} is called on \arg{Goal} using rules
from module \arg{Module} followed by default modules for \arg{Module}.

Only goals appearing in the body of clauses when reading a source file
are expanded using this mechanism, and only if they appear literally in
the clause, or as an argument to a defined meta-predicate that is
annotated using `0' (see \index{meta_predicate/1}\predref{meta_predicate}{1}). Other cases need a real
predicate definition.

The expansion hook can use \index{prolog_load_context/2}\predref{prolog_load_context}{2} to obtain information
about the context in which the goal is exanded such as the module,
variable names or the encapsulating term.

    \predicate{expand_goal}{2}{+Goal1, -Goal2}
This predicate is normally called by the compiler to perform
preprocessing using \index{goal_expansion/2}\predref{goal_expansion}{2}.  The predicate computes a
fixed-point by applying transformations until there are no more
changes.  If optimisation is enabled (see \cmdlineoption{-O} and
\prologflag{optimise}), \index{expand_goal/2}\predref{expand_goal}{2} simplifies the result by
removing unneeded calls to \index{true/0}\predref{true}{0} and \index{fail/0}\predref{fail}{0} as well as unreachable
branches.

    \predicate{compile_aux_clauses}{1}{+Clauses}
Compile clauses on behalf of \index{goal_expansion/2}\predref{goal_expansion}{2}.  This predicate compiles
the argument clauses into static predicates, associating the predicates
with the current file but avoids changing the notion of current predicate
and therefore discontiguous warnings.

Note that in some cases multiple expansions of similar goals can share
the same compiled auxiliary predicate. In such cases, the implementation
of \index{goal_expansion/2}\predref{goal_expansion}{2} can use \index{predicate_property/2}\predref{predicate_property}{2} using the property
\const{defined} to test whether the predicate is already defined in the
current context.

    \predicate{dcg_translate_rule}{2}{+In, -Out}
This predicate performs the translation of a term \exam{Head-->Body}
into a normal Prolog clause.  Normally this functionality should be
accessed using \index{expand_term/2}\predref{expand_term}{2}.

    \predicate{var_property}{2}{+Var, ?Property}
True when \arg{Property} is a property of \arg{Var}. These properties
are available during goal- and term-expansion. Defined properties are
below. Future versions are likely to provide more properties, such as
whether the variable is a singleton or whether the variable is
referenced in the remainder of the term.  See also \index{goal_expansion/2}\predref{goal_expansion}{2}.

    \begin{description}
    \termitem{fresh}{Bool}
Bool has the value \arg{true} if the variable is guaranteed to be
unbound at entry of the goal, otherwise its value is \arg{false}.
This implies that the variable first appears in this goal or a
previous appearance was in a negation (\predref{\Snot}{1}) or a
different branch of a disjunction.

    \termitem{name}{Name}
True when variable appears with the given name in the source.
    \end{description}
\end{description}


\subsubsection{Program transformation with source layout info}
\label{sec:progtransform-layout}

This sections documents extended versions of the program transformation
predicates that also transform the source layout information.  Extended
layout information is currently processed, but unused.  Future versions
will use for the following enhancements:

\begin{itemize}
    \item More precise locations of warnings and errors
    \item More reliable setting of breakpoints
    \item More reliable source layout information in the graphical
          debugger.
\end{itemize}

\begin{description}
    \predicate{expand_goal}{4}{+Goal1, ?Layout1, -Goal2, -Layout2}
    \nodescription
    \predicate{goal_expansion}{4}{+Goal1, ?Layout1, -Goal2, -Layout2}
    \nodescription
    \predicate{expand_term}{4}{+Term1, ?Layout1, -Term2, -Layout2}
    \nodescription
    \predicate{term_expansion}{4}{+Term1, ?Layout1, -Term2, -Layout2}
    \predicate{dcg_translate_rule}{4}{+In, ?LayoutIn, -Out, -LayoutOut}
These versions are called \emph{before} their 2-argument counterparts.
The input layout term is either a variable (if no layout information is
available) or a term carrying detailed layout information as returned by
the \const{subterm_positions} of \index{read_term/2}\predref{read_term}{2}.
\end{description}


\subsubsection{Conditional compilation}
\label{sec:conditionalcompilation}

\index{if, directive}%
Conditional compilation builds on the same principle as
\index{term_expansion/2}\predref{term_expansion}{2}, \index{goal_expansion/2}\predref{goal_expansion}{2} and the expansion of grammar rules to
compile sections of the source code conditionally. One of the reasons
for introducing conditional compilation is to simplify writing portable
code. See \secref{dialect} for more information. Here is a simple
example:

\begin{code}
:- if(\+source_exports(library(lists), suffix/2)).

suffix(Suffix, List) :-
        append(_, Suffix, List).

:- endif.
\end{code}

\noindent
Note that these directives can only appear as separate terms in the
input.  Typical usage scenarios include:

\begin{shortlist}
    \item Load different libraries on different dialects.
    \item Define a predicate if it is missing as a system predicate.
    \item Realise totally different implementations for a particular
    part of the code due to different capabilities.
    \item Realise different configuration options for your software.
\end{shortlist}


\begin{description}
    \directive{if}{1}{:Goal}
Compile subsequent code only if \arg{Goal} succeeds.  For enhanced
portability, \arg{Goal} is processed by \index{expand_goal/2}\predref{expand_goal}{2} before execution.
If an error occurs, the error is printed and processing proceeds as if
\arg{Goal} has failed.

    \directive{elif}{1}{:Goal}
Equivalent to \exam{:- else. :-if(Goal).} ... \exam{:- endif.}  In a sequence as below,
the section below the first matching \const{elif} is processed. If no test
succeeds, the else branch is processed.

\begin{code}
:- if(test1).
section_1.
:- elif(test2).
section_2.
:- elif(test3).
section_3.
:- else.
section_else.
:- endif.
\end{code}

\noindent
    \directive{else}{0}{}
Start `else' branch.

    \directive{endif}{0}{}
End of conditional compilation.
\end{description}


\subsection{Reloading files, active code and threads}
\label{sec:loadrunningcode}

Traditionally, Prolog environments allow for reloading files holding
currently active code.  In particular, the following sequence is a valid
use of the development environment:

\begin{shortlist}
    \item Trace a goal
    \item Find unexpected behaviour of a predicate
    \item Enter a \jargon{break} using the \textbf{b} command
    \item Fix the sources and reload them using \index{make/0}\predref{make}{0}
    \item Exit the break, \jargon{retry} executing the now
	  fixed predicate using the \textbf{r} command
\end{shortlist}

\jargon{Reloading} a previously loaded file is safe, both in the debug
scenario above and when the code is being executed by another
\jargon{thread}. Executing threads switch atomically to the new
definition of modified predicates, while clauses that belong to the old
definition are (eventually) reclaimed by
\index{garbage_collect_clauses/0}\predref{garbage_collect_clauses}{0}.\footnote{As of version 7.3.12. Older versions
wipe all clauses originating from the file before loading the new
clauses. This causes threads that executes the code to (typically) die
with an \jargon{undefined predicate} exception.}  Below we describe the
steps taken for \emph{reloading} a file to help understanding the
limitations of the process.

\begin{enumerate}
    \item If a file is being reloaded, a \jargon{reload context} is
    associated to the file administration.  This context includes a
    table keeping track of predicates and a table keeping track of
    the module(s) associated with this source.
    \item If a new predicate is found, an entry is added to the
    context predicate table.  Three options are considered:
    \begin{enumerate}
        \item The predicate is new.  It is handled the same as
	if the file was loaded for the first time.
	\item The predicate is foreign or thread local.  These
	too are treated as if the file was loaded for the first
	time.
	\item Normal predicates.  Here we initialise a pointer
	to the \emph{current clause}.
    \end{enumerate}
    \item New clauses for `normal predicates' are considered as
    follows:
    \begin{enumerate}
        \item If the clause's byte-code is the same as the predicates
	current clause, discard the clause and advance the current
	clause pointer.
	\item If the clause's byte-code is the same as some clause
	further into the clause list of the predicate, discard the
	new clause, mark all intermediate clauses for future deletion,
	and advance the current clause pointer to the first clause
	after the matched one.
	\item If the clause's byte-code matches no clause, insert it
	for \emph{future activation} before the current clause and
	keep the current clause.
    \end{enumerate}
    \item \jargon{Properties} such as \const{dynamic} or \const{meta_predicate}
    are in part applied immediately and in part during the fixup process
    after the file completes loading.  Currently, \const{dynamic} and
    \const{thread_local} are applied immediately.
    \item New modules are recorded in the reload context.  Export declarations
    (the module's public list and \index{export/1}\predref{export}{1} calls) are both applied and
    recorded.
    \item When the end-of-file is reached, the following fixup steps are taken
    \begin{enumerate}
        \item For each predicate
	\begin{enumerate}
	    \item The current clause and subsequent clauses are marked for
	    future deletion.
	    \item All clauses marked for future deletion or creation are
	    (in)activated by changing their `erased' or `created'
	    \jargon{generation}.  Erased clauses are (eventually)
	    reclaimed by the \jargon{clause garbage collector}, see
	    \index{garbage_collect_clauses/0}\predref{garbage_collect_clauses}{0}.
	    \item Pending predicate property changes are applied.
	\end{enumerate}
	\item For each module
	\begin{enumerate}
	    \item Exported predicates that are not encountered in the
	    reload context are removed from the export list.
	\end{enumerate}
    \end{enumerate}
\end{enumerate}

The above generally ensures that changes to the \emph{content} of source
files can typically be activated safely using \index{make/0}\predref{make}{0}. Global changes
such as operator changes, changes of module names, changes to multi-file
predicates, etc.\ sometimes require a restart. In almost all cases, the
need for restart is indicated by permission or syntax errors during the
reload or existence errors while running the program.

In some cases the content of a source file refers `to itself'. This is
notably the case if local rules for \index{goal_expansion/2}\predref{goal_expansion}{2} or \index{term_expansion/2}\predref{term_expansion}{2}
are defined or goals are executed using
\jargon{directives}.\footnote{Note that \index{initialization/1}\predref{initialization}{1} directives are
executed \emph{after} loading the file. SWI-Prolog allows for directives
that are executed \emph{while} loading the file using \exam{:- Goal.} or
\index{initialization/2}\predref{initialization}{2}}. Up to version 7.5.12 it was typically needed to
reload the file \emph{twice}, once for updating the code that was used
for compiling the remainder of the file and once to effectuate this. As
of version 7.5.13, conventional \jargon{transaction semantics} apply.
This implies that for the thread performing the reload the file's
content is first wiped and gradually rebuilt, while other threads see
an \jargon{atomic} update from the old file content to the
new.\footnote{This feature was implemented by Keri Harris.}

\subsubsection{Compilation of mutually dependent code} \label{sec:depload}

Large programs are generally split into multiple files. If file $A$
accesses predicates from file $B$ which accesses predicates from file
$A$, we consider this a mutual or circular dependency. If traditional
load predicates (e.g., \index{consult/1}\predref{consult}{1}) are used to include file $B$ from $A$
and $A$ from $B$, loading either file results in a loop. This is because
\index{consult/1}\predref{consult}{1} is mapped to \index{load_files/2}\predref{load_files}{2} using the option \term{if(true)}.
Such programs are typically loaded using a \jargon{load file} that
consults all required (non-module) files. If modules are used, the
dependencies are made explicit using \index{use_module/1}\predref{use_module}{1} statements. The
\index{use_module/1}\predref{use_module}{1} predicate, however, maps to \index{load_files/2}\predref{load_files}{2} with the option
\term{if(not_loaded)}. A \index{use_module/1}\predref{use_module}{1} on an already loaded file merely
makes the public predicates of the used module available.

Summarizing, mutual dependency of source files is fully supported with
no precautions when using modules. Modules can use each other in an
arbitrary dependency graph. When using \index{consult/1}\predref{consult}{1}, predicate dependencies
between loaded files can still be arbitrary, but the consult relations
between files must be a proper tree.


\subsubsection{Compilation with multiple threads} \label{sec:mtload}

This section discusses compiling files for the first time. For
reloading, see \secref{loadrunningcode}.

In older versions, compilation was thread-safe due to a global
\jargon{lock} in \index{load_files/2}\predref{load_files}{2} and the code dealing with
\jargon{autoloading} (see \secref{autoload}). Besides unnecessary
stalling when multiple threads trap unrelated undefined predicates,
this easily leads to deadlocks, notably if threads are started from an
\index{initialization/1}\predref{initialization}{1} directive.\footnote{Although such goals are started
after loading the file in which they appear, the calling thread is still
likely to hold the `load' lock because it is compiling the file from
which the file holding the directive is loaded.}

Starting with version 5.11.27, the autoloader is no longer locked and
multiple threads can compile files concurrently. This requires special
precautions only if multiple threads wish to load the same file at the
same time. Therefore, \index{load_files/2}\predref{load_files}{2} checks automatically whether some other
thread is already loading the file. If not, it starts loading the file.
If another thread is already loading the file, the thread blocks until
the other thread finishes loading the file. After waiting, and if the
file is a module file, it will make the public predicates available.

Note that this schema does not prevent deadlocks under all situations.
Consider two mutually dependent (see \secref{depload}) module files $A$
and $B$, where thread~1 starts loading $A$ and thread~2 starts loading
$B$ at the same time. Both threads will deadlock when trying to load the
used module.

The current implementation does not detect such cases and the involved
threads will freeze. This problem can be avoided if a mutually dependent
collection of files is always loaded from the same start file.


\subsection{Quick load files}		\label{sec:qlf}

SWI-Prolog supports compilation of individual or multiple Prolog
source files into `Quick Load Files'. A `Quick Load File' (\fileext{qlf}
file) stores the contents of the file in a precompiled format.

These files load considerably faster than source files and are normally
more compact.  They are machine-independent and may thus be loaded
on any implementation of SWI-Prolog.  Note, however, that clauses are
stored as virtual machine instructions.  Changes to the compiler will
generally make old compiled files unusable.

Quick Load Files are created using \index{qcompile/1}\predref{qcompile}{1}. They are loaded using
\index{consult/1}\predref{consult}{1} or one of the other file-loading predicates described in
\secref{consulting}. If \index{consult/1}\predref{consult}{1} is given an explicit \fileext{pl} file,
it will load the Prolog source. When given a \fileext{qlf} file, it
will load the file. When no extension is specified, it will load the
\fileext{qlf} file when present and the \fileext{pl} file otherwise.

\begin{description}
    \predicate{qcompile}{1}{:File}
Takes a file specification as \index{consult/1}\predref{consult}{1}, etc., and, in addition to the
normal compilation, creates a \emph{Quick Load File} from \arg{File}.
The file extension of this file is \fileext{qlf}. The basename of the
Quick Load File is the same as the input file.

If the file contains `\exam{:- consult(\arg{+File})}', `\exam{:-
[\arg{+File}]}' or `\exam{:- load_files(\arg{+File}, [qcompile(part),
...])}' statements, the referred files are compiled into the
same \fileext{qlf} file. Other directives will be stored in the
\fileext{qlf} file and executed in the same fashion as when loading the
\fileext{pl} file.

For \index{term_expansion/2}\predref{term_expansion}{2}, the same rules as described in
\secref{compilation} apply.

Conditional execution or optimisation may test the predicate
\index{compiling/0}\predref{compiling}{0}.

Source references (\index{source_file/2}\predref{source_file}{2}) in the Quick Load File refer to
the Prolog source file from which the compiled code originates.

    \predicate{qcompile}{2}{:File, +Options}
As \index{qcompile/1}\predref{qcompile}{1}, but processes additional options as defined by
\index{load_files/2}\predref{load_files}{2}.\bug{Option processing is currently incomplete.}
\end{description}


\section{Editor Interface}	\label{sec:edit}

SWI-Prolog offers an extensible interface which allows the user to
edit objects of the program: predicates, modules, files, etc.  The
editor interface is implemented by \index{edit/1}\predref{edit}{1} and consists of three parts:
{\em locating}, {\em selecting} and {\em starting} the editor.
Any of these parts may be customized.  See \secref{customedit}.

The built-in edit specifications for \index{edit/1}\predref{edit}{1} (see \index{prolog_edit:locate/3}\qpredref{prolog_edit}{locate}{3})
are described in the table below:

\begin{center}
\begin{tabular}{|l|p{3.5in}|}
\hline
\multicolumn{2}{|c|}{\bf Fully specified objects} \\
\hline
\bnfmeta{Module}:\bnfmeta{Name}/\bnfmeta{Arity}	& Refers to a predicate \\
module(\bnfmeta{Module})	& Refers to a module \\
file(\bnfmeta{Path})		& Refers to a file \\
source_file(\bnfmeta{Path})	& Refers to a loaded source file \\
\hline
\multicolumn{2}{|c|}{\bf Ambiguous specifications} \\
\hline
\bnfmeta{Name}/\bnfmeta{Arity}		& Refers to this predicate in any module \\
\bnfmeta{Name}			& Refers to (1) the named predicate in any
		          module with any arity, (2) a (source) file, or
			  (3) a module. \\
\hline
\end{tabular}
\end{center}


\begin{description}
    \predicate{edit}{1}{+Specification}
First, exploit \qpredref{prolog_edit}{locate}{3} to translate
\arg{Specification} into a list of \jargon{Locations}. If there is more
than one `hit', the user is asked to select from the locations found.
Finally, \qpredref{prolog_edit}{edit_source}{1} is used to invoke
the user's preferred editor. Typically, \index{edit/1}\predref{edit}{1} can be handed the name of
a predicate, module, basename of a file, XPCE class, XPCE method, etc.

    \predicate{edit}{0}{}
Edit the `default' file using \index{edit/1}\predref{edit}{1}.  The default file is the file
loaded with the command line option \cmdlineoption{-s} or, in Windows,
the file loaded by double-clicking from the Windows shell.
\end{description}

\subsection{Customizing the editor interface}
\label{sec:customedit}

The predicates described in this section are \jargon{hooks} that can be
defined to disambiguate specifications given to \index{edit/1}\predref{edit}{1}, find the related
source, and open an editor at the given source location.

\begin{description}
    \predicate{prolog_edit:locate}{3}{+Spec, -FullSpec, -Location}
Where \arg{Spec} is the specification provided through \index{edit/1}\predref{edit}{1}.  This
multifile predicate is used to enumerate locations where an object
satisfying the given \arg{Spec} can be found.  \arg{FullSpec} is unified
with the complete specification for the object.  This distinction is used
to allow for ambiguous specifications.  For example, if \arg{Spec} is
an atom, which appears as the basename of a loaded file and as the
name of a predicate, \arg{FullSpec} will be bound to \term{file}{Path}
or \arg{Name}/\arg{Arity}.

\arg{Location} is a list of attributes of the location.  Normally, this
list will contain the term \term{file}{File} and, if available, the
term \term{line}{Line}.

    \predicate{prolog_edit:locate}{2}{+Spec, -Location}
Same as \index{prolog_edit:locate/3}\qpredref{prolog_edit}{locate}{3}, but only deals with fully specified
objects.

    \predicate{prolog_edit:edit_source}{1}{+Location}
Start editor on \arg{Location}. See \index{prolog_edit:locate/3}\qpredref{prolog_edit}{locate}{3} for the format
of a location term. This multifile predicate is normally not defined.
If it succeeds, \index{edit/1}\predref{edit}{1} assumes the editor is started.

If it fails, \index{edit/1}\predref{edit}{1} uses its internal defaults, which are defined by
the Prolog flag \prologflag{editor} and/or the environment variable
\env{EDITOR}.  The following rules apply.  If the Prolog flag \prologflag{editor}
is of the format \verb|$|\bnfmeta{name}, the editor is determined by the environment
variable \bnfmeta{name}.  Else, if this flag is \const{pce_emacs} or \const{built_in}
\emph{and} XPCE is loaded or can be loaded, the built-in Emacs clone is used.
Else, if the environment \env{EDITOR} is set, this editor is used.  Finally,
\program{vi} is used as default on Unix systems and \program{notepad} on
Windows.

See the default user preferences file \file{dotfiles/dotswiplrc} for
examples.

    \predicate{prolog_edit:edit_command}{2}{+Editor, -Command}
Determines how \arg{Editor} is to be invoked using \index{shell/1}\predref{shell}{1}. \arg{Editor}
is the determined editor (see \qpredref{prolog_edit}{edit_source}{1}),
without the full path specification, and without a possible
(\fileext{exe}) extension. \arg{Command} is an atom describing the
command. The following \%-sequences are replaced in \arg{Command} before
the result is handed to \index{shell/1}\predref{shell}{1}:

\begin{center}
\begin{tabular}{|l|p{3.5in}|}
\hline
\%e	& Replaced by the (OS) command name of the editor \\
\%f	& Replaced by the (OS) full path name of the file \\
\%d	& Replaced by the line number \\
\hline
\end{tabular}
\end{center}

If the editor can deal with starting at a specified line, two clauses
should be provided. The first pattern invokes the editor with a
line number, while the second is used if the line number is unknown.

The default contains definitions for \program{vi}, \program{emacs},
\program{emacsclient}, \program{vim}, \program{notepad}$^*$ and
\program{wordpad}$^*$.  Starred editors do not provide starting
at a given line number.

Please contribute your specifications to \email{bugs@swi-prolog.org}.

    \predicate{prolog_edit:load}{0}{}
Normally an undefined multifile predicate.  This predicate may be defined
to provide loading hooks for user extensions to the edit module.  For
example, XPCE provides the code below to load \pllib{swi_edit}, containing
definitions to locate classes and methods as well as to bind this package
to the PceEmacs built-in editor.

\begin{code}
:- multifile prolog_edit:load/0.

prolog_edit:load :-
        ensure_loaded(library(swi_edit)).
\end{code}

\noindent
\end{description}

\section{List the program, predicates or clauses}	\label{sec:listing}

\begin{description}
    \predicate{listing}{1}{:Pred}
List predicates specified by \arg{Pred}.  \arg{Pred} may be a predicate
name (atom), which lists all predicates with this name, regardless of
their arity.  It can also be a predicate indicator (\bnfmeta{name}/\bnfmeta{arity} or
\bnfmeta{name}//\bnfmeta{arity}), possibly qualified with a module.  For example:
\exam{?- listing(\index{lists:member/2}\qpredref{lists}{member}{2}).}.

A listing is produced by enumerating the clauses of the predicate using
\index{clause/2}\predref{clause}{2} and printing each clause using \index{portray_clause/1}\predref{portray_clause}{1}.  This implies
that the variable names are generated (\arg{A}, \arg{B}, \ldots) and
the layout is defined by rules in \index{portray_clause/1}\predref{portray_clause}{1}.

    \predicate{listing}{0}{}
List all predicates from the calling module using \index{listing/1}\predref{listing}{1}.  For example,
\exam{?- listing.} lists clauses in the default \const{user} module
and \exam{?- lists:listing.} lists the clauses in the module
\const{lists}.

    \predicate{portray_clause}{1}{+Clause}
Pretty print a clause. A clause should be specified as a term
`\exam{\bnfmeta{Head} :- \bnfmeta{Body}}'. Facts are represented as `\exam{\bnfmeta{Head} :-
true}' or simply \exam{\bnfmeta{Head}}.  Variables in the clause are written
as $A$, $B$, \ldots.  Singleton variables are written as \verb$_$.
See also \index{portray_clause/2}\predref{portray_clause}{2}.

    \predicate{portray_clause}{2}{+Stream, +Clause}
Pretty print a clause to \arg{Stream}. See \index{portray_clause/1}\predref{portray_clause}{1} for details.
\end{description}


\section{Verify Type of a Term}			\label{sec:typetest}

Type tests are semi-deterministic predicates that succeed if the
argument satisfies the requested type. Type-test predicates have no
error condition and do not instantiate their argument. See also library
\pllib{error}.

\begin{description}
    \predicate[ISO]{var}{1}{@Term}
True if \arg{Term} currently is a free variable.
    \predicate[ISO]{nonvar}{1}{@Term}
True if \arg{Term} currently is not a free variable.
    \predicate[ISO]{integer}{1}{@Term}
True if \arg{Term} is bound to an integer.
    \predicate[ISO]{float}{1}{@Term}
True if \arg{Term} is bound to a floating point number.
    \predicate{rational}{1}{@Term}
True if \arg{Term} is bound to a rational number.  Rational numbers
include integers.
    \predicate{rational}{3}{@Term, -Numerator, -Denominator}
True if \arg{Term} is a rational number with given \arg{Numerator} and
\arg{Denominator}.  The \arg{Numerator} and \arg{Denominator} are in
canonical form, which means \arg{Denominator} is a positive integer and
there are no common divisors between \arg{Numerator} and \arg{Denominator}.
    \predicate[ISO]{number}{1}{@Term}
True if \arg{Term} is bound to an integer or floating point number.%
	\footnote{As rational numbers are not atomic in the current
		  implementation and we do not want to break the rule
		  that \index{number/1}\predref{number}{1} implies \index{atomic/1}\predref{atomic}{1}, \index{number/1}\predref{number}{1} fails on
		  rational numbers. This will change if rational numbers
		  become atomic.}

    \predicate[ISO]{atom}{1}{@Term}
True if \arg{Term} is bound to an atom.

    \predicate{blob}{2}{@Term, ?Type}
True if \arg{Term} is a \jargon{blob} of type \arg{Type}. See
\secref{blob}.

    \predicate{string}{1}{@Term}
True if \arg{Term} is bound to a string. Note that string here refers to
the built-in atomic type string as described in \secref{strings}.
Starting with version~7, the syntax for a string object is text between
double quotes, such as \verb|"hello"|.\footnote{In traditional Prolog
systems, double quoted text is often mapped to a list of
\jargon{character codes}.} See also the Prolog flag
\prologflag{double_quotes}.

    \predicate[ISO]{atomic}{1}{@Term}
True if \arg{Term} is bound (i.e., not a variable) and is not
compound.  Thus, atomic acts as if defined by:

\begin{code}
atomic(Term) :-
        nonvar(Term),
        \+ compound(Term).
\end{code}

\noindent
SWI-Prolog defines the following atomic datatypes: atom (\index{atom/1}\predref{atom}{1}),
string (\index{string/1}\predref{string}{1}), integer (\index{integer/1}\predref{integer}{1}), floating point number
(\index{float/1}\predref{float}{1}) and blob (\index{blob/2}\predref{blob}{2}).  In addition, the symbol \verb$[]$
(empty list) is atomic, but not an atom.  See \secref{ext-lists}.

    \predicate[ISO]{compound}{1}{@Term}
True if \arg{Term} is bound to a compound term.  See also \index{functor/3}\predref{functor}{3}
=../2, \index{compound_name_arity/3}\predref{compound_name_arity}{3} and \index{compound_name_arguments/3}\predref{compound_name_arguments}{3}.

    \predicate[ISO]{callable}{1}{@Term}
True if \arg{Term} is bound to an atom or a compound term. This was
intended as a type-test for arguments to \index{call/1}\predref{call}{1} and \index{call/2}\predref{call}{2}.. Note that
callable only tests the \jargon{surface term}. Terms such as (22,true)
are considered callable, but cause \index{call/1}\predref{call}{1} to raise a type error.
Module-qualification of meta-argument (see \index{meta_predicate/1}\predref{meta_predicate}{1}) using
\functor{\Smodule}{2} causes callable to succeed on any
meta-argument.\footnote{We think that \index{callable/1}\predref{callable}{1} should be deprecated
and there should be two new predicates, one performing a test for
callable that is minimally module aware and possibly consistent with
type-checking in \index{call/1}\predref{call}{1} and a second predicate that tests for atom or
compound.} Consider the program and query below:

\begin{code}
:- meta_predicate p(0).

p(G) :- callable(G), call(G).

?- p(22).
ERROR: Type error: `callable' expected, found `22'
ERROR: In:
ERROR:    [6] p(user:22)
\end{code}

\noindent
    \predicate[ISO]{ground}{1}{@Term}
True if \arg{Term} holds no free variables. See also \index{nonground/2}\predref{nonground}{2}
and \index{term_variables/2}\predref{term_variables}{2}.

    \predicate{cyclic_term}{1}{@Term}
True if \arg{Term} contains cycles, i.e.\ is an infinite term.
See also \index{acyclic_term/1}\predref{acyclic_term}{1} and \secref{cyclic}.%
	\footnote{The predicates \index{cyclic_term/1}\predref{cyclic_term}{1} and \index{acyclic_term/1}\predref{acyclic_term}{1} are
		  compatible with SICStus Prolog.  Some Prolog systems
		  supporting cyclic terms use \nopredref{is_cyclic}{1}.}

    \predicate[ISO]{acyclic_term}{1}{@Term}
True if \arg{Term} does not contain cycles,  i.e.\ can be processed
recursively in finite time.  See also \index{cyclic_term/1}\predref{cyclic_term}{1} and \secref{cyclic}.
\end{description}

\section{Comparison and Unification of Terms}	\label{sec:compare}

Although unification is mostly done implicitly while matching the
head of a predicate, it is also provided by the predicate =/2.

\begin{description}
    \infixop[ISO]{\Seq}{?Term1}{?Term2}
Unify \arg{Term1} with \arg{Term2}. True if the unification succeeds.
For behaviour on cyclic terms see the Prolog flag
\prologflag{occurs_check}. It acts as if defined by the following fact:

\begin{code}
=(Term, Term).
\end{code}

\noindent
    \infixop[ISO]{\Sne}{@Term1}{@Term2}
Equivalent to \exam{\Snot Term1 = Term2}.

This predicate is logically sound if its arguments are sufficiently
instantiated. In other cases, such as \exam{?- X \Sne\ Y.},
the predicate fails although there are solutions. This is due to the
incomplete nature of~\predref{\Snot}{1}.

To make your programs work correctly also in situations where the
arguments are not yet sufficiently instantiated, use \index{dif/2}\predref{dif}{2} instead.
\end{description}


\subsection{Standard Order of Terms}		\label{sec:standardorder}

Comparison and unification of arbitrary terms. Terms are ordered in the
so-called ``standard order''. This order is defined as follows:

\begin{enumerate}
    \item $\arg{Variables} < \arg{Numbers} < \arg{Strings} < \arg{Atoms}
          < \arg{Compound Terms}$
    \item Variables are sorted by address.
    \item \arg{Numbers} are compared by value.  Mixed integer/float are compared
	  as floats. If the comparison is equal, the float is considered
	  the smaller value. If the Prolog flag \prologflag{iso} is defined,
	  all floating point numbers precede all integers.
    \item \arg{Strings} are compared alphabetically.
    \item \arg{Atoms} are compared alphabetically.
    \item \arg{Compound} terms are first checked on their arity, then
          on their functor name (alphabetically) and finally recursively
	  on their arguments, leftmost argument first.
\end{enumerate}

Although variables are ordered, there are some unexpected properties one
should keep in mind when relying on variable ordering. This applies to
the predicates below as to predicate such as \index{sort/2}\predref{sort}{2} as well as libraries
that reply on ordering such as library \pllib{assoc} and library
\pllib{ordsets}. Obviously, an established relation \mbox{\arg{A}
\const{\Stlt} \arg{B}} no longer holds if \arg{A} is unified with e.g., a
number. Also unifying \arg{A} with \arg{B} invalidates the relation
because they become equivalent (==/2) after unification.

As stated above, variables are sorted by address, which implies that
they are sorted by `age', where `older' variables are ordered before
`newer' variables. If two variables are unified their `shared' age is
the age of oldest variable. This implies we can examine a list of sorted
variables with `newer' (fresh) variables without invalidating the order.
Attaching an \jargon{attribute}, see \secref{attvar}, turns an `old'
variable into a `new' one as illustrated below. Note that the first
always succeeds as the first argument of a term is always the oldest.
This only applies for the \emph{first} attribute, i.e., further
manipulation of the attribute list does \emph{not} change the `age'.

\begin{code}
?- T = f(A,B), A @< B.
T = f(A, B).

?- T = f(A,B), put_attr(A, name, value), A @< B.
false.
\end{code}

\noindent
The above implies you \emph{can} use e.g., an assoc (from library
\pllib{assoc}, implemented as an AVL tree) to maintain information about
a set of variables. You must be careful about what you do with the
attributes though. In many cases it is more robust to use attributes to
register information about variables.

\begin{description}
    \infixop[ISO]{\Sequal}{@Term1}{@Term2}
True if \arg{Term1} is equivalent to \arg{Term2}. A variable is only
identical to a sharing variable.

    \infixop[ISO]{\Snequal}{@Term1}{@Term2}
Equivalent to \exam{\Snot Term1 == Term2}.

    \infixop[ISO]{\Stlt}{@Term1}{@Term2}
True if \arg{Term1} is before \arg{Term2} in the standard order of terms.

    \infixop[ISO]{\Stle}{@Term1}{@Term2}
True if both terms are equal (\predref{\Sequal}{2}) or \arg{Term1} is
before \arg{Term2} in the standard order of terms.

    \infixop[ISO]{\Stgt}{@Term1}{@Term2}
True if \arg{Term1} is after \arg{Term2} in the standard order of terms.

    \infixop[ISO]{\Stge}{@Term1}{@Term2}
True if both terms are equal (\predref{\Sequal}{2}) or \arg{Term1} is
after \arg{Term2} in the standard order of terms.

    \predicate[ISO]{compare}{3}{?Order, @Term1, @Term2}
Determine or test the \arg{Order} between two terms in the standard
order of terms. \arg{Order} is one of \const{\Slt}, \const{\Sgt} or \const{\Seq},
with the obvious meaning.
\end{description}


\subsection{Special unification and comparison predicates}
\label{sec:unifyspecial}

This section describes special purpose variations on Prolog unification.
The predicate \index{unify_with_occurs_check/2}\predref{unify_with_occurs_check}{2} provides sound unification and
is part of the ISO standard. The predicate \index{subsumes_term/2}\predref{subsumes_term}{2} defines
`one-sided unification' and is part of the ISO proposal established in
Edinburgh (2010). Finally, \index{unifiable/3}\predref{unifiable}{3} is a `what-if' version of
unification that is often used as a building block in constraint
reasoners.


\begin{description}
    \predicate[ISO]{unify_with_occurs_check}{2}{+Term1, +Term2}
As \predref{\Seq}{2}, but using \jargon{sound unification}. That is, a
variable only unifies to a term if this term does not contain the
variable itself.  To illustrate this, consider the two queries below.

\begin{code}
1 ?- A = f(A).
A = f(A).
2 ?- unify_with_occurs_check(A, f(A)).
false.
\end{code}

\noindent
\index{occurs_check}%
The first statement creates a \jargon{cyclic term}, also called a
\jargon{rational tree}. The second executes logically sound unification
and thus fails. Note that the behaviour of unification through
\predref{\Seq}{2} as well as implicit unification in the head can be
changed using the Prolog flag \prologflag{occurs_check}.

The SWI-Prolog implementation of \index{unify_with_occurs_check/2}\predref{unify_with_occurs_check}{2} is cycle-safe
and only guards against \emph{creating} cycles, not against cycles that
may already be present in one of the arguments.  This is illustrated in
the following two queries:

\begin{code}
?- X = f(X), Y = X, unify_with_occurs_check(X, Y).
X = Y, Y = f(Y).
?- X = f(X), Y = f(Y), unify_with_occurs_check(X, Y).
X = Y, Y = f(Y).
\end{code}

\noindent
Some other Prolog systems interpret \index{unify_with_occurs_check/2}\predref{unify_with_occurs_check}{2} as if
defined by the clause below, causing failure on the above two queries.
Direct use of \index{acyclic_term/1}\predref{acyclic_term}{1} is portable and more appropriate for such
applications.

\begin{code}
unify_with_occurs_check(X,X) :- acyclic_term(X).
\end{code}

\noindent
    \infixop{\Sstructeq}{+Term1}{+Term2}
\index{variant}%
True if \arg{Term1} is a \jargon{variant} of (or \jargon{structurally
equivalent} to) \arg{Term2}. Testing for a variant is weaker than
equivalence (\predref{\Sequal}{2}), but stronger than unification
(\predref{\Seq}{2}). Two terms $A$ and $B$ are variants iff there exists a
renaming of the variables in $A$ that makes $A$ equivalent (==) to $B$
and vice versa.\footnote{Row~7 and 8 of this table may come as a
surprise, but row~8 is satisfied by (left-to-right) $A\rightarrow C$,
$B\rightarrow A$ and (right-to-left) $C\rightarrow A$, $A\rightarrow B$.
If the same variable appears in different locations in the left and
right term, the variant relation can be broken by consistent binding of
both terms. E.g., after binding the first argument in row~8 to a value,
both terms are no longer variant.} Examples:

\begin{quote}
\begin{tabular}{rcc}
1 & \tt	    a  =@= A       & false \\
2 & \tt     A  =@= B       & true \\
3 & \tt x(A,A) =@= x(B,C)  & false \\
4 & \tt x(A,A) =@= x(B,B)  & true \\
5 & \tt x(A,A) =@= x(A,B)  & false \\
6 & \tt x(A,B) =@= x(C,D)  & true \\
7 & \tt x(A,B) =@= x(B,A)  & true \\
8 & \tt x(A,B) =@= x(C,A)  & true \\
\end{tabular}
\end{quote}

A term is always a variant of a copy of itself. Term copying takes place
in, e.g., \index{copy_term/2}\predref{copy_term}{2}, \index{findall/3}\predref{findall}{3} or proving a clause added with
\index{asserta/1}\predref{asserta}{1}. In the pure Prolog world (i.e., without attributed
variables), \predref{\Sstructeq}{2} behaves as if defined below. With
attributed variables, variant of the attributes is tested rather than
trying to satisfy the constraints.

\begin{code}
A =@= B :-
        copy_term(A, Ac),
        copy_term(B, Bc),
        numbervars(Ac, 0, N),
        numbervars(Bc, 0, N),
        Ac == Bc.
\end{code}

\noindent
The SWI-Prolog implementation is cycle-safe and can deal with variables
that are shared between the left and right argument. Its performance is
comparable to \predref{\Sequal}{2}, both on success and (early) failure.
\footnote{The current implementation is contributed by Kuniaki Mukai.}

This predicate is known by the name \predref{variant}{2} in some other
Prolog systems. Be aware of possible differences in semantics if the
arguments contain attributed variables or share variables.\footnote{In
many systems variant is implemented using two calls to \index{subsumes_term/2}\predref{subsumes_term}{2}.}

    \infixop{\Sstructneq}{+Term1}{+Term2}
Equivalent to \exam{`\Snot Term1 =@= Term2'}.  See \predref{\Sstructeq}{2} for
details.

    \predicate[ISO]{subsumes_term}{2}{{@}Generic, {@}Specific}
True if \arg{Generic} can be made equivalent to \arg{Specific} by only
binding variables in \arg{Generic}.  The current implementation performs
the unification and ensures that the variable set of \arg{Specific} is
not changed by the unification. On success, the bindings are
undone.\footnote{This predicate is often named \index{subsumes_chk/2}\predref{subsumes_chk}{2} in older
Prolog dialects. The current name was established in the ISO WG17
meeting in Edinburgh (2010). The \texttt{chk} postfix was
considered to refer to determinism as in e.g., \index{memberchk/2}\predref{memberchk}{2}.}
This predicate respects constraints.

    \predicate{term_subsumer}{3}{+Special1, +Special2, -General}
\arg{General} is the most specific term that is a generalisation of
\arg{Special1} and \arg{Special2}. The implementation can handle cyclic
terms.

    \predicate{unifiable}{3}{{@}X, {@}Y, -Unifier}
If \arg{X} and \arg{Y} can unify, unify \arg{Unifier} with a list of
\mbox{\arg{Var} = \arg{Value}}, representing the bindings required to
make \arg{X} and \arg{Y} equivalent.%
	\footnote{This predicate was introduced for the implementation
		  of \index{dif/2}\predref{dif}{2} and \index{when/2}\predref{when}{2} after discussion with Tom
		  Schrijvers and Bart Demoen.  None of us is really
		  happy with the name and therefore suggestions for
		  a new name are welcome.}
This predicate can handle cyclic terms.  Attributed variables are
handled as normal variables.  Associated hooks are \emph{not}
executed.

    \predicate{?=}{2}{{@}Term1, {@}Term2}
Succeeds if the syntactic equality of \arg{Term1} and \arg{Term2}
can be decided safely, i.e.\ if the result of \exam{Term1 == Term2}
will not change due to further instantiation of either term.  It
behaves as if defined by \verb$?=(X,Y) :- \+ unifiable(X,Y,[_|_]).$
\end{description}

\section{Control Predicates}		\label{sec:control}

The predicates of this section implement control structures. Normally
the constructs in this section, except for \index{repeat/0}\predref{repeat}{0}, are translated by
the compiler. Please note that complex goals passed as arguments to
meta-predicates such as \index{findall/3}\predref{findall}{3} below cause the goal to be compiled to
a temporary location before execution. It is faster to define a
sub-predicate (i.e.\ \nopredref{one_character_atoms}{1} in the example
below) and make a call to this simple predicate.

\begin{code}
one_character_atoms(As) :-
        findall(A, (current_atom(A), atom_length(A, 1)), As).
\end{code}

\noindent
\begin{description}
    \predicate[ISO]{fail}{0}{}
Always fail.  The predicate \index{fail/0}\predref{fail}{0} is translated into a single virtual
machine instruction.
    \predicate[ISO]{false}{0}{}
Same as fail, but the name has a more declarative connotation.
    \predicate[ISO]{true}{0}{}
Always succeed. The predicate \index{true/0}\predref{true}{0} is translated into a single virtual
machine instruction.
    \predicate[ISO]{repeat}{0}{}
Always succeed, provide an infinite number of choice points.

    \predicate[ISO]{\Scut}{0}{}
Cut. Discard all choice points created since entering the predicate in
which the cut appears. In other words, \jargon{commit} to the clause in
which the cut appears \emph{and} discard choice points that have been
created by goals to the left of the cut in the current clause. Meta
calling is opaque to the cut. This implies that cuts that appear in a
term that is subject to meta-calling (\index{call/1}\predref{call}{1}) only affect choice points
created by the meta-called term. The following control structures are
transparent to the cut: \predref{\Ssemicolon}{2}, \predref{\Sifthen}{2} and
\predref{\Ssoftcut}{2}. Cuts appearing in the {\em condition} part of
\predref{\Sifthen}{2} and \predref{\Ssoftcut}{2} are opaque to the cut. The
table below explains the scope of the cut with examples. \textit{Prunes}
here means ``prunes $X$ choice point created by $X$''.

\begin{center}\begin{tabular}{ll}
\exam{t0 :- (a, !, b).}                 & \% prunes {a}/0 and {t0}/0 \\
\exam{t1 :- (a, !, fail ; b).}          & \% prunes {a}/0 and {t1}/0 \\
\exam{t2 :- (a -> b, ! ; c).}           & \% prunes {b}/0 and {t2}/0 \\
\exam{t3 :- call((a, !, fail ; b)).}    & \% prunes {a}/0 \\
\exam{t4 :- \Snot (a, !, fail).}        & \% prunes {a}/0 \\
\end{tabular}\end{center}

\infixop[ISO]{\Scomma}{:Goal1}{:Goal2}
Conjunction.  True if both `Goal1' and `Goal2' can be proved.  It is
defined as follows (this definition does not lead to a loop as the second comma
is handled by the compiler):
\begin{code}
Goal1, Goal2 :- Goal1, Goal2.
\end{code}

\noindent
\infixop[ISO]{\Ssemicolon}{:Goal1}{:Goal2}
The `or' predicate is defined as:
\begin{code}
Goal1 ; _Goal2 :- Goal1.
_Goal1 ; Goal2 :- Goal2.
\end{code}

\noindent
\infixop{\Sbar}{:Goal1}{:Goal2}
Equivalent to \predref{\Ssemicolon}{2}.  Retained for compatibility only.  New code
should use \predref{\Ssemicolon}{2}.

\infixop[ISO]{\Sifthen}{:Condition}{:Action}
If-then and If-Then-Else. The \predref{\Sifthen}{2} construct commits to
the choices made at its left-hand side, destroying choice points created
inside the clause (by \predref{\Ssemicolon}{2}), or by goals called by
this clause. Unlike \predref{\Scut}{0}, the choice point of the predicate as
a whole (due to multiple clauses) is \strong{not} destroyed. The
combination \predref{\Ssemicolon}{2} and \predref{\Sifthen}{2} acts as if
defined as:

\begin{code}
If -> Then; _Else :- If, !, Then.
If -> _Then; Else :- !, Else.
If -> Then :- If, !, Then.
\end{code}

\noindent
Please note that (If \verb$->$ Then) acts as (If \verb$->$ Then ;
\textbf{fail}), making the construct \emph{fail} if the condition fails.
This unusual semantics is part of the ISO and all de-facto Prolog
standards.

Please note that \mbox{(if{\Sifthen}then;else)} is read as
\mbox{((if{\Sifthen}then);else)} and that the \emph{combined} semantics of
this syntactic construct as defined above is \emph{different} from the
simple nesting of the two individual constructs, i.e., the semantics of
\predref{\Sifthen}{2} \emph{changes} when embedded in \predref{\Ssemicolon}{2}. See also
\index{once/1}\predref{once}{1}.

\infixop{\Ssoftcut}{:Condition}{:Action ; :Else}
This construct implements the so-called `soft-cut'. The control is
defined as follows: If \arg{Condition} succeeds at least once, the
semantics is the same as (\term{call}{Condition},
\arg{Action}).\footnote{Note that the \arg{Condition} is wrapped in
\index{call/1}\predref{call}{1}, limiting the scope of the cut (\predref{\Scut}{0}} If
\arg{Condition} does not succeed, the semantics is that of (\verb$\+$
\arg{Condition}, \arg{Else}). In other words, if \arg{Condition}
succeeds at least once, simply behave as the conjunction of
\term{call}{Condition} and \arg{Action}, otherwise execute \arg{Else}.
The construct is known under the name \nopredref{if}{3} in some other
Prolog implementations.

The construct \arg{A} \verb$*->$ \arg{B}, i.e., without an \arg{Else}
branch, the semantics is the same as (\term{call}{A}, \arg{B}).

This construct is rarely used. An example use case is the implementation
of \textsc{optional} in \textsc{sparql}.  The optional construct should
preserve all solutions if the argument succeeds as least once but still
succeed otherwise.  This is implemented as below.

\begin{code}
optional(Goal) :-
    (   Goal
    *-> true
    ;   true
    ).
\end{code}

\noindent
Now calling e.g., \verb$optional(member(X, [a,b]))$ has the solutions
$X=a$ and $X=b$, while \verb$optional(member(X,[]))$ succeeds without
binding $X$.

\prefixop[ISO]{\Snot}{:Goal}
True if `Goal' cannot be proven (mnemonic: \chr{\Splus} refers to {\em
provable} and the backslash (\chr{\Sneg}) is normally used to
indicate negation in Prolog).
\end{description}

\section{Meta-Call Predicates}		\label{sec:metacall}

Meta-call predicates are used to call terms constructed at run time.
The basic meta-call mechanism offered by SWI-Prolog is to use
variables as a subclause (which should of course be bound to a valid
goal at runtime).  A meta-call is slower than a normal call as it
involves actually searching the database at runtime for the predicate,
while for normal calls this search is done at compile time.

\begin{description}
    \predicate[ISO]{call}{1}{:Goal}
Invoke \arg{Goal} as a goal. Note that clauses may have variables as
subclauses, which is identical to \index{call/1}\predref{call}{1}.

    \predicate[ISO]{call}{2}{:Goal, +ExtraArg1, \ldots}		% 2..
Append \arg{ExtraArg1, ExtraArg2, \ldots} to the argument list of
\arg{Goal} and call the result. For example, \exam{call(plus(1), 2, X)}
will call \exam{plus(1, 2, X)}, binding \arg{X} to 3.

The call/[2..] construct is handled by the compiler. The predicates
call/[2-8] are defined as real (meta-)predicates and are available to
inspection through \index{current_predicate/1}\predref{current_predicate}{1}, \index{predicate_property/2}\predref{predicate_property}{2},
etc.\footnote{Arities 2..8 are demanded by ISO/IEC
13211-1:1995/Cor.2:2012.} Higher arities are handled by the compiler and
runtime system, but the predicates are not accessible for
inspection.\footnote{Future versions of the reflective predicate may
fake the presence of \nopredref{call}{9..}. Full logical behaviour,
generating all these pseudo predicates, is probably undesirable and will
become impossible if \jargon{max_arity} is removed.}

    \predicate{apply}{2}{:Goal, +List}
Append the members of \arg{List} to the arguments of \arg{Goal} and call
the resulting term. For example: \exam{apply(plus(1), [2, X])} calls
\exam{plus(1, 2, X)}. New code should use call/[2..] if the length of
\arg{List} is fixed.

    \predicate{not}{1}{:Goal}
True if \arg{Goal} cannot be proven.  Retained for compatibility
only. New code should use \predref{\Snot}{1}.

    \predicate[ISO]{once}{1}{:Goal}
Make a possibly \jargon{nondet} goal \jargon{semidet}, i.e., succeed at
most once.  Defined as:

\begin{code}
once(Goal) :-
    call(Goal), !.
\end{code}

\noindent
\index{once/1}\predref{once}{1} can in many cases be replaced with \predref{\Sifthen}{2}. The only
difference is how the cut behaves (see !/0). The following two clauses
below are identical. Be careful about the interaction with
\predref{\Ssemicolon}{2}. The \pllib{apply_macros} library defines an inline
expansion of \index{once/1}\predref{once}{1}, mapping it to \verb$(Goal->true;fail)$. Using the
full if-then-else constructs prevents its semantics from being changed
when embedded in a \predref{\Ssemicolon}{2} disjunction.

\begin{code}
1) a :- once((b, c)), d.
2) a :- b, c -> d.
\end{code}

\noindent
    \predicate{ignore}{1}{:Goal}
Calls \arg{Goal} as \index{once/1}\predref{once}{1}, but succeeds, regardless of whether
\arg{Goal} succeeded or not. Defined as:

\begin{code}
ignore(Goal) :-
        Goal, !.
ignore(_).
\end{code}

\noindent
    \predicate{call_with_depth_limit}{3}{:Goal, +Limit, -Result}
If \arg{Goal} can be proven without recursion deeper than \arg{Limit}
levels, \index{call_with_depth_limit/3}\predref{call_with_depth_limit}{3} succeeds, binding \arg{Result} to the
deepest recursion level used during the proof.  Otherwise, \arg{Result}
is unified with \const{depth_limit_exceeded} if the limit was exceeded
during the proof, or the entire predicate fails if \arg{Goal} fails
without exceeding \arg{Limit}.

The depth limit is guarded by the internal machinery. This may differ
from the depth computed based on a theoretical model. For example,
\index{true/0}\predref{true}{0} is translated into an inline virtual machine instruction. Also,
\index{repeat/0}\predref{repeat}{0} is not implemented as below, but as a non-deterministic foreign
predicate.

\begin{code}
repeat.
repeat :-
        repeat.
\end{code}

\noindent
As a result, \index{call_with_depth_limit/3}\predref{call_with_depth_limit}{3} may still loop infinitely on programs
that should theoretically finish in finite time. This problem can be
cured by using Prolog equivalents to such built-in predicates.

This predicate may be used for theorem provers to realise techniques
like \jargon{iterative deepening}. See also \index{call_with_inference_limit/3}\predref{call_with_inference_limit}{3}.
It was implemented after discussion with Steve Moyle
\email{smoyle@ermine.ox.ac.uk}.

    \predicate{call_with_inference_limit}{3}{:Goal, +Limit, -Result}
Equivalent to \term{call}{Goal}, but limits the number of inferences
\emph{for each solution of \arg{Goal}}.\footnote{This predicate was
realised after discussion with Ulrich Neumerkel and Markus Triska.}.
Execution may terminate as follows:

    \begin{itemize}
	\item If \arg{Goal} does \emph{not} terminate before the
	      inference limit is exceeded, \arg{Goal} is aborted by
	      injecting the exception \const{inference_limit_exceeded}
	      into its execution.  After termination of \arg{Goal},
	      \arg{Result} is unified with the atom
	      \const{inference_limit_exceeded}.
	      \textit{Otherwise},
	\item If \arg{Goal} fails, \index{call_with_inference_limit/3}\predref{call_with_inference_limit}{3} fails.
	\item If \arg{Goal} succeeds \emph{without a choice point},
	       \arg{Result} is unified with \const{\Scut}.
	\item If \arg{Goal} succeeds \emph{with a choice point},
	       \arg{Result} is unified with \const{true}.
        \item If \arg{Goal} throws an exception, \index{call_with_inference_limit/3}\predref{call_with_inference_limit}{3}
	      re-throws the exception.
    \end{itemize}

An inference is defined as a call or redo on a predicate. Please note
that some primitive built-in predicates are compiled to virtual machine
instructions for which inferences are not counted. The execution of
predicates defined in other languages (e.g., C, C++) count as a single
inference. This includes potentially expensive built-in predicates such
as \index{sort/2}\predref{sort}{2}.

Calls to this predicate may be nested. An inner call that sets the limit
below the current is honoured. An inner call that would terminate after
the current limit does not change the effective limit. See also
\index{call_with_depth_limit/3}\predref{call_with_depth_limit}{3} and \index{call_with_time_limit/2}\predref{call_with_time_limit}{2}.

    \predicate{setup_call_cleanup}{3}{:Setup, :Goal, :Cleanup}
Calls \exam{(once(Setup), Goal)}. If \arg{Setup} succeeds, \arg{Cleanup}
will be called exactly once after \arg{Goal} is finished: either on
failure, deterministic success, commit, or an exception. The execution
of \arg{Setup} is protected from asynchronous interrupts like
\index{call_with_time_limit/2}\predref{call_with_time_limit}{2} (package clib) or \index{thread_signal/2}\predref{thread_signal}{2}. In most uses,
\arg{Setup} will perform temporary side-effects required by \arg{Goal}
that are finally undone by \arg{Cleanup}.

Success or failure of \arg{Cleanup} is ignored, and choice points it
created are destroyed (as \index{once/1}\predref{once}{1}). If \arg{Cleanup} throws an exception,
this is executed as normal while it was not triggered as the result of
an exception the exception is propagated as normal. If \arg{Cleanup} was
triggered by an exception the rules are described in
\secref{urgentexceptions}

Typically, this predicate is used to cleanup permanent data storage
required to execute \arg{Goal}, close file descriptors, etc. The example
below provides a non-deterministic search for a term in a file, closing
the stream as needed.

\begin{code}
term_in_file(Term, File) :-
        setup_call_cleanup(open(File, read, In),
                           term_in_stream(Term, In),
                           close(In) ).

term_in_stream(Term, In) :-
        repeat,
        read(In, T),
        (   T == end_of_file
        ->  !, fail
        ;   T = Term
        ).
\end{code}

\noindent
Note that it is impossible to implement this predicate in Prolog.  The
closest approximation would be to read all terms into a list, close
the file and call \index{member/2}\predref{member}{2}.  Without \index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} there is no
way to gain control if the choice point left by \index{repeat/0}\predref{repeat}{0} is removed by a
cut or an exception.

\index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} can also be used to test determinism of a goal,
providing a portable alternative to \index{deterministic/1}\predref{deterministic}{1}:

\begin{code}
?- setup_call_cleanup(true,(X=1;X=2), Det=yes).

X = 1 ;

X = 2,
Det = yes ;
\end{code}

\noindent
This predicate is under consideration for inclusion into the ISO standard.
For compatibility with other Prolog implementations see \index{call_cleanup/2}\predref{call_cleanup}{2}.

    \predicate{setup_call_catcher_cleanup}{4}{:Setup, :Goal, +Catcher, :Cleanup}
Similar to \term{setup_call_cleanup}{Setup, Goal, Cleanup} with
additional information on the reason for calling \arg{Cleanup}.  Prior
to calling \arg{Cleanup}, \arg{Catcher} unifies with the termination
code (see below).  If this unification fails, \arg{Cleanup} is
\emph{not} called.

\begin{description}
    \termitem{exit}{}
\arg{Goal} succeeded without leaving any choice points.

    \termitem{fail}{}
\arg{Goal} failed.

    \termitem{\Scut}{}
\arg{Goal} succeeded with choice points and these are now discarded
by the execution of a cut (or other pruning of the search tree such as
if-then-else).

    \termitem{exception}{Exception}
\arg{Goal} raised the given \arg{Exception}.

    \termitem{external_exception}{Exception}
\arg{Goal} succeeded with choice points and these are now discarded
due to an exception.  For example:

\begin{code}
?- setup_call_catcher_cleanup(true, (X=1;X=2),
                              Catcher, writeln(Catcher)),
   throw(ball).
external_exception(ball)
ERROR: Unhandled exception: Unknown message: ball
\end{code}

\noindent
\end{description}

    \predicate{call_cleanup}{2}{:Goal, :Cleanup}
Same as \term{setup_call_cleanup}{true, Goal, Cleanup}.
This is provided
for compatibility with a number of other Prolog implementations only.  Do
not use \index{call_cleanup/2}\predref{call_cleanup}{2} if you perform side-effects prior to calling
that will be undone by \arg{Cleanup}.  Instead, use
\index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} with an appropriate first argument to perform those
side-effects.

    \predicate{call_cleanup}{3}{:Goal, +Catcher, :Cleanup}
Same as \term{setup_call_catcher_cleanup}{true, Goal, Catcher, Cleanup}.
The same warning as for \index{call_cleanup/2}\predref{call_cleanup}{2} applies.
\end{description}


\section{Delimited continuations}	     \label{sec:delcont}

The predicates \index{reset/3}\predref{reset}{3} and \index{shift/1}\predref{shift}{1} implement \jargon{delimited
continuations} for Prolog. Delimited continuation for Prolog is
described in \cite{DBLP:journals/tplp/SchrijversDDW13}. The mechanism
allows for proper \jargon{coroutines}, two or more routines whose
execution is interleaved, while they exchange data. Note that coroutines
in this sense differ from coroutines realised using attributed variables
as described in~\chapref{clp}.

The suspension mechanism provided by delimited continuations is suitable
for the implementation of \jargon{tabling}
\cite{DBLP:journals/tplp/DesouterDS15}, see library \pllib{tabling}.

\begin{description}
    \predicate{reset}{3}{:Goal, ?Ball, -Continuation}
Call \arg{Goal}. If \arg{Goal} calls \index{shift/1}\predref{shift}{1} and the argument of \index{shift/1}\predref{shift}{1}
can be unified with \arg{Ball},\footnote{The argument order described in
\cite{DBLP:journals/tplp/SchrijversDDW13} is
\term{reset}{Goal,Continuation,Ball}. We swapped the argument order for
compatibility with \index{catch/3}\predref{catch}{3}} \index{shift/1}\predref{shift}{1} causes \index{reset/3}\predref{reset}{3} to return, unifying
\arg{Continuation} with a goal that represents the \jargon{continuation}
after \index{shift/1}\predref{shift}{1}. In other words, meta-calling \arg{Continuation} completes
the execution where shift left it. If \arg{Goal} does not call \index{shift/1}\predref{shift}{1},
\arg{Continuation} are unified with the integer \const{0}
(zero).\footnote{Note that older versions also unify \arg{Ball} with
\const{0}.  Testing whether or not shift happened on \arg{Ball} however
is \emph{always} ambiguous.}

    \predicate{shift}{1}{+Ball}
Abandon the execution of the current goal, returning control to just
\emph{after} the matching \index{reset/3}\predref{reset}{3} call.  This is similar to \index{throw/1}\predref{throw}{1}
except that (1) nothing is `undone' and (2) the 3th argument of
\index{reset/3}\predref{reset}{3} is unified with the \jargon{continuation}, which allows the
code calling \index{reset/3}\predref{reset}{3} to \jargon{resume} the current goal.
\end{description}


\section{Exception handling}
\label{sec:exception}

The predicates \index{catch/3}\predref{catch}{3} and \index{throw/1}\predref{throw}{1} provide ISO compliant raising and
catching of exceptions.

\begin{description}
    \predicate[ISO]{catch}{3}{:Goal, +Catcher, :Recover}
Behaves as \index{call/1}\predref{call}{1} if no exception is raised when executing \arg{Goal}.
If an exception is raised using \index{throw/1}\predref{throw}{1} while \arg{Goal} executes, and
the \arg{Goal} is the innermost goal for which \arg{Catcher} unifies
with the argument of \index{throw/1}\predref{throw}{1}, all choice points generated by \arg{Goal}
are cut, the system backtracks to the start of \index{catch/3}\predref{catch}{3} while preserving
the thrown exception term, and \arg{Recover} is called as in \index{call/1}\predref{call}{1}.

The overhead of calling a goal through \index{catch/3}\predref{catch}{3} is comparable to
\index{call/1}\predref{call}{1}.  Recovery from an exception is much slower, especially if the
exception term is large due to the copying thereof or is decorated with
a stack trace using, e.g., the library \pllib{prolog_stack} based on the
\index{prolog_exception_hook/4}\predref{prolog_exception_hook}{4} hook predicate to rewrite exceptions.

    \predicate[ISO]{throw}{1}{+Exception}
Raise an exception. The system looks for the innermost \index{catch/3}\predref{catch}{3}
ancestor for which \arg{Exception} unifies with the \arg{Catcher}
argument of the \index{catch/3}\predref{catch}{3} call.  See \index{catch/3}\predref{catch}{3} for details.

ISO demands that \index{throw/1}\predref{throw}{1} make a copy of \arg{Exception}, walk up the
stack to a \index{catch/3}\predref{catch}{3} call, backtrack and try to unify the copy of
\arg{Exception} with \arg{Catcher}. SWI-Prolog delays backtracking until
it actually finds a matching \index{catch/3}\predref{catch}{3} goal. The advantage is that we can
start the debugger at the first possible location while preserving the
entire exception context if there is no matching \index{catch/3}\predref{catch}{3} goal. This
approach can lead to different behaviour if \arg{Goal} and \arg{Catcher}
of \index{catch/3}\predref{catch}{3} call shared variables. We assume this to be highly unlikely
and could not think of a scenario where this is useful.%
	\footnote{I'd like to acknowledge Bart Demoen for his
	          clarifications on these matters.}

In addition to explicit calls to \index{throw/1}\predref{throw}{1}, many built-in predicates throw
exceptions directly from C. If the \arg{Exception} term cannot be copied
due to lack of stack space, the following actions are tried in order:

\begin{enumerate}
    \item If the exception is of the form \term{error}{Formal, ImplementationDefined},
try to raise the exception without the \arg{ImplementationDefined} part.
    \item Try to raise \term{error}{\term{resource_error}{stack}, global}.
    \item Abort (see \index{abort/0}\predref{abort}{0}).
\end{enumerate}

If an exception is raised in a call-back from C (see \chapref{foreign})
and not caught in the same call-back, \cfuncref{PL_next_solution}{} fails and
the exception context can be retrieved using \cfuncref{PL_exception}{}.

    \predicate{catch_with_backtrace}{3}{:Goal, +Catcher, :Recover}
As \index{catch/3}\predref{catch}{3}, but if library \pllib{prolog_stack} is loaded and an
exception of the shape \term{error}{Format, Context} is raised
\arg{Context} is extended with a backtrace.  To catch an error
and print its message including a backtrace, use the following
template:

\begin{code}
:- use_module(library(prolog_stack)).

    ...,
    catch_with_backtrace(Goal, Error,
                         print_message(error, Error)),
    ...,
\end{code}

\noindent
This is good practice for a \jargon{catch-all} wrapper around an
application.  See also \index{main/0}\predref{main}{0} from library \pllib{main}.
\end{description}


\subsection{Urgency of exceptions}
\label{sec:urgentexceptions}

Under some conditions an exception may be raised as a result of handling
another exception.  Below are some of the scenarios:

\begin{itemize}
    \item
The predicate \index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} calls the cleanup handler as a result
of an exception and the cleanup handler raises an exception itself. In
this case the most \jargon{urgent} exception is propagated into the
environment.
    \item
Raising an exception fails due to lack of resources, e.g., lack of
stack space to store the exception. In this case a resource exception is
raised. If that too fails the system tries to raise a resource exception
without (stack) context. If that fails it will raise the exception
\verb='$aborted'=, also raised by \index{abort/0}\predref{abort}{0}. As no stack space is
required for processing this atomic exception, this should always
succeed.
    \item
Certain \jargon{callback} operations raise an exception while processing
another exception or a previous callback already raised an exception
before there was an opportunity to process the exception. The most
notable \jargon{callback} subject to this issue are \index{prolog_event_hook/1}\predref{prolog_event_hook}{1}
(supporting e.g., the graphical debugger), \index{prolog_exception_hook/4}\predref{prolog_exception_hook}{4}
(rewriting exceptions, e.g., by adding context) and \index{print_message/2}\predref{print_message}{2} when
called from the core facilities such as the internal debugger. As with
\index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3}, the most \jargon{urgent} exception is preserved.
\end{itemize}

If the most urgent exceptions needs to be preserved, the following
exception ordering is respected, preserving the topmost matching error.

\begin{enumerate}
    \item \verb='$aborted'= (\index{abort/0}\predref{abort}{0})
    \item \verb$time_limit_exceeded$ (\index{call_with_time_limit/2}\predref{call_with_time_limit}{2})
    \item \term{error}{\term{resource_error}{Resource}, Context}
    \item \term{error}{Formal, Context}
    \item All other exceptions
\end{enumerate}

\paragraph{Note} The above resolution is not described in the ISO
standard. This is not needed either because ISO does not specify
\index{setup_call_cleanup/3}\predref{setup_call_cleanup}{3} and does not deal with environment management
issues such as (debugger) callbacks. Neither does it define \index{abort/0}\predref{abort}{0} or
timeout handling. Notably \index{abort/0}\predref{abort}{0} and timeout are non-logical control
structures. They are implemented on top of exceptions as they need to
unwind the stack, destroy choice points and call cleanup handlers in
the same way.  However, the pending exception should not be replaced
by another one before the intended handler is reached.  The abort
exception cannot be caught, something which is achieved by wrapping
the \jargon{cleanup handler} of \index{catch/3}\predref{catch}{3} into
\term{call_cleanup}{Handler, abort}.


\subsection{Debugging and exceptions}
\label{sec:debugexceptions}

\index{exceptions,debugging}%
\index{debugging,exceptions}%
Before the introduction of exceptions in SWI-Prolog a runtime error was
handled by printing an error message, after which the predicate failed.
If the Prolog flag \prologflag{debug_on_error} was in effect (default),
the tracer was switched on. The combination of the error message and
trace information is generally sufficient to locate the error.

With exception handling, things are different. A programmer may wish to
trap an exception using \index{catch/3}\predref{catch}{3} to avoid it reaching the user. If the
exception is not handled by user code, the interactive top level will
trap it to prevent termination.

If we do not take special precautions, the context information
associated with an unexpected exception (i.e., a programming error) is
lost. Therefore, if an exception is raised which is not caught using
\index{catch/3}\predref{catch}{3} and the top level is running, the error will be printed, and the
system will enter trace mode.

If the system is in a non-interactive call-back from foreign code and
there is no \index{catch/3}\predref{catch}{3} active in the current context, it cannot determine
whether or not the exception will be caught by the external routine
calling Prolog.  It will then base its behaviour on the Prolog flag
\prologflag{debug_on_error}:

\begin{itemlist}
    \item [current_prolog_flag(debug_on_error, false)]
The exception does not trap the debugger and is returned to the foreign
routine calling Prolog, where it can be accessed using \cfuncref{PL_exception}{}.
This is the default.
    \item [current_prolog_flag(debug_on_error, true)]
If the exception is not caught by Prolog in the current context, it will
trap the tracer to help analyse the context of the error.
\end{itemlist}

While looking for the context in which an exception takes place, it is
advised to switch on debug mode using the predicate \index{debug/0}\predref{debug}{0}. The hook
\index{prolog_exception_hook/4}\predref{prolog_exception_hook}{4} can be used to add more debugging facilities to
exceptions. An example is the library \pllib{http/http_error},
generating a full stack trace on errors in the HTTP server library.


\subsection{The exception term}		\label{sec:exceptterm}

Built-in predicates generate exceptions using a term
\term{error}{Formal, Context}.  The first argument is the `formal'
description of the error, specifying the class and generic defined
context information.  When applicable, the ISO error term definition
is used.  The second part describes some additional context to help
the programmer while debugging.  In its most generic form this is
a term of the form \term{context}{Name/Arity, Message}, where
\arg{Name}/\arg{Arity} describes the built-in predicate that raised
the error, and \arg{Message} provides an additional description of
the error.  Any part of this structure may be a variable if no
information was present.


\subsection{Printing messages}			\label{sec:printmsg}

The predicate \index{print_message/2}\predref{print_message}{2} is used to print a message term in a
human-readable format. The other predicates from this section allow the user
to refine and extend the message system. A common usage of
\index{print_message/2}\predref{print_message}{2} is to print error messages from exceptions. The code
below prints errors encountered during the execution of \arg{Goal},
without further propagating the exception and without starting the
debugger.

\begin{code}
        ...,
        catch(Goal, E,
              ( print_message(error, E),
                fail
              )),
        ...
\end{code}

\noindent
Another common use is to define \index{message_hook/3}\predref{message_hook}{3} for printing messages
that are normally \jargon{silent}, suppressing messages, redirecting
messages or make something happen in addition to printing the message.

\begin{description}
    \predicate{print_message}{2}{+Kind, +Term}
The predicate \index{print_message/2}\predref{print_message}{2} is used by the system and libraries to
print messages. \arg{Kind} describes the nature of the message, while
\arg{Term} is a Prolog term that describes the content. Printing
messages through this indirection instead of using \index{format/3}\predref{format}{3} to the
stream \const{user_error} allows displaying the message appropriate
to the application (terminal, logfile, graphics), acting on messages
based on their content instead of a string (see \index{message_hook/3}\predref{message_hook}{3}) and
creating language specific versions of the messages.  See also
\secref{libprintmsg}.  The following message kinds are known:

\begin{description}
    \termitem{banner}{}
The system banner message. Banner messages can be suppressed by setting
the Prolog flag \prologflag{verbose} to \const{silent}.

    \termitem{debug}{Topic}
Message from library(debug).  See \index{debug/3}\predref{debug}{3}.

    \termitem{error}{}
The message indicates an erroneous situation.  This kind is used to
print uncaught exceptions of type \term{error}{Formal, Context}. See
section introduction (\secref{printmsg}).

    \termitem{help}{}
User requested help message, for example after entering `h' or `?' to
a prompt.

    \termitem{information}{}
Information that is requested by the user.  An example is \index{statistics/0}\predref{statistics}{0}.

    \termitem{informational}{}
Typically messages of events are progres that are considered useful
to a developer.  Such messages can be suppressed by setting the
Prolog flag \prologflag{verbose} to \const{silent}.

    \termitem{silent}{}
Message that is normally not printed. Applications may define
\index{message_hook/3}\predref{message_hook}{3} to act upon such messages.

    \termitem{trace}{}
Messages from the (command line) tracer.

    \termitem{warning}{}
The message indicates something dubious that is not considered fatal.
For example, discontiguous predicates (see \index{discontiguous/1}\predref{discontiguous}{1}).
\end{description}

The predicate \index{print_message/2}\predref{print_message}{2} first translates the \arg{Term} into a
list of `message lines' (see \index{print_message_lines/3}\predref{print_message_lines}{3} for details). Next,
it calls the hook \index{message_hook/3}\predref{message_hook}{3} to allow the user to intercept the
message. If \index{message_hook/3}\predref{message_hook}{3} fails it prints the message unless \arg{Kind}
is silent.

The \index{print_message/2}\predref{print_message}{2} predicate and its rules are in the file
\metafile{\bnfmeta{plhome}/boot/messages.pl}, which may be inspected for more
information on the error messages and related error terms. If you need
to write messages from your own predicates, it is recommended to reuse
the existing message terms if applicable. If no existing message term is
applicable, invent a fairly unique term that represents the event and
define a rule for the multifile predicate prolog:message//1. See
\secref{libprintmsg} for a deeper discussion and examples.

See also \index{message_to_string/2}\predref{message_to_string}{2}.

    \predicate{print_message_lines}{3}{+Stream, +Prefix, +Lines}
Print a message (see \index{print_message/2}\predref{print_message}{2}) that has been translated to
a list of message elements.  The elements of this list are:

\begin{description}
    \termitem{\bnfmeta{Format}-\bnfmeta{Args}}{}
        Where \arg{Format} is an atom and \arg{Args} is a list
	of format arguments.  Handed to \index{format/3}\predref{format}{3}.
    \termitem{flush}{}
	If this appears as the last element, \arg{Stream} is flushed
	(see \index{flush_output/1}\predref{flush_output}{1}) and no final newline is generated.  This
	is combined with a subsequent message that starts with
	\const{at_same_line} to complete the line.
    \termitem{at_same_line}{}
        If this appears as first element, no prefix is printed for
	the first line and the line position is not forced to 0
	(see \index{format/1}\predref{format}{1}, \verb$~N$).
    \termitem{ansi}{+Attributes, +Format, +Args}
	This message may be intercepted by means of the hook
	\index{prolog:message_line_element/2}\qpredref{prolog}{message_line_element}{2}.  The library \pllib{ansi_term}
	implements this hook to achieve coloured output. If it is not
	intercepted it invokes \term{format}{Stream, Format, Args}.
    \termitem{nl}{}
        A new line is started.  If the message is not complete,
	\arg{Prefix} is printed before the remainder of the message.
    \termitem{begin}{Kind, Var}
    \nodescription
    \termitem{end}{Var}
	The entire message is headed by \term{begin}{Kind, Var} and
	ended by \term{end}{Var}.  This feature is used by, e.g.,
	library \pllib{ansi_term} to colour entire messages.
    \termitem{\bnfmeta{Format}}{}
        Handed to \index{format/3}\predref{format}{3} as \term{format}{Stream, Format, []}.
	Deprecated because it is ambiguous if \arg{Format} collides
	with one of the atomic commands.
\end{description}

See also \index{print_message/2}\predref{print_message}{2} and \index{message_hook/3}\predref{message_hook}{3}.

    \predicate{message_hook}{3}{+Term, +Kind, +Lines}
Hook predicate that may be defined in the module \const{user} to
intercept messages from \index{print_message/2}\predref{print_message}{2}. \arg{Term} and \arg{Kind} are
the same as passed to \index{print_message/2}\predref{print_message}{2}. \arg{Lines} is a list of format
statements as described with \index{print_message_lines/3}\predref{print_message_lines}{3}.  See also
\index{message_to_string/2}\predref{message_to_string}{2}.

This predicate must be defined dynamic and multifile to allow other
modules defining clauses for it too.

    \predicate{thread_message_hook}{3}{+Term, +Kind, +Lines}
As \index{message_hook/3}\predref{message_hook}{3}, but this predicate is local to the calling thread
(see \index{thread_local/1}\predref{thread_local}{1}).  This hook is called \emph{before} \index{message_hook/3}\predref{message_hook}{3}.
The `pre-hook' is indented to catch messages they may be produced by
calling some goal without affecting other threads.

    \predicate{message_property}{2}{+Kind, ?Property}
This hook can be used to define additional message kinds and the way
they are displayed.  The following properties are defined:

    \begin{description}
	\termitem{color}{-Attributes}
Print message using ANSI terminal attributes.  See \index{ansi_format/3}\predref{ansi_format}{3}
for details.  Here is an example, printing help messages in blue:

\begin{code}
:- multifile user:message_property/2.

user:message_property(help, color([fg(blue)])).
\end{code}

\noindent
	\termitem{prefix}{-Prefix}
Prefix printed before each line.  This argument is handed to \index{format/3}\predref{format}{3}.
The default is \verb$'~N'$. For example, messages of kind
\const{warning} use \verb$'~NWarning: '$.

	\termitem{location_prefix}{+Location, -FirstPrefix, -ContinuePrefix}
Used for printing messages that are related to a source location.
Currently, \arg{Location} is a term \mbox{\arg{File}:\arg{Line}}.
\arg{FirstPrefix} is the prefix for the first line and
\arg{-ContinuePrefix} is the prefix for continuation lines.  For
example, the default for errors is

\begin{code}
location_prefix(File:Line,
                '~NERROR: ~w:~d:'-[File,Line], '~N\t')).
\end{code}

\noindent
	\termitem{stream}{-Stream}
Stream to which to print the message. Default is \const{user_error}.

	\termitem{wait}{-Seconds}
Amount of time to wait after printing the message. Default is not to
wait.
    \end{description}

    \predicate{prolog:message_line_element}{2}{+Stream, +Term}
This hook is called to print the individual elements of a message from
\index{print_message_lines/3}\predref{print_message_lines}{3}. This hook is used by e.g., library
\pllib{ansi_term} to colour messages on ANSI-capable terminals.

    \predicate{prolog:message_prefix_hook}{2}{+ContextTerm, -Prefix}
This hook is called to add context to the message prefix.
\arg{ContextTerm} is a member of the list provided by the
\prologflag{message_context}. \arg{Prefix} must be unified with an
atomic value that is added to the message prefix.

    \predicate{message_to_string}{2}{+Term, -String}
Translates a message term into a string object (see \secref{strings}).

    \predicate{version}{0}{}
Write the SWI-Prolog banner message as well as additional messages
registered using \index{version/1}\predref{version}{1}. This is the default \jargon{initialization
goal} which can be modified using \cmdlineoption{-g}.

    \predicate{version}{1}{+Message}
Register additional messages to be printed by \index{version/0}\predref{version}{0}. Each registered
message is handed to the message translation DCG and can thus be defined
using the hook prolog:message//1.  If not defined, it is simply printed.
\end{description}


\subsubsection{Printing from libraries}		\label{sec:libprintmsg}

Libraries should \emph{not} use \index{format/3}\predref{format}{3} or other output predicates
directly. Libraries that print informational output directly to the
console are hard to use from code that depend on your textual output,
such as a CGI script. The predicates in \secref{printmsg} define the API
for dealing with messages. The idea behind this is that a library that
wants to provide information about its status, progress, events or
problems calls \index{print_message/2}\predref{print_message}{2}. The first argument is the
\jargon{level}. The supported levels are described with \index{print_message/2}\predref{print_message}{2}.
Libraries typically use \const{informational} and \const{warning}, while
libraries should use exceptions for errors (see \index{throw/1}\predref{throw}{1}, \index{type_error/2}\predref{type_error}{2},
etc.).

The second argument is an arbitrary Prolog term that carries the
information of the message, but \emph{not} the precise text. The text is
defined by the grammar rule prolog:message//1. This distinction is made
to allow for translations and to allow hooks processing the information
in a different way (e.g., to translate progress messages into a
progress bar).

For example, suppose we have a library that must download data from the
Internet (e.g., based on \index{http_open/3}\predref{http_open}{3}). The library wants to print the
progress after each downloaded file.  The code below is a good skeleton:

\begin{code}
download_urls(List) :-
        length(List, Total),
        forall(nth1(I, List, URL),
               (   download_url(URL),
                   print_message(informational,
                                 download_url(URL, I, Total)))).
\end{code}

\noindent
The programmer can now specify the default textual output using the rule
below. Note that this rule may be in the same file or anywhere else.
Notably, the application may come with several rule sets for different
languages. This, and the user-hook example below are the reason to
represent the message as a compound term rather than a string. This is
similar to using message numbers in non-symbolic languages. The
documentation of \index{print_message_lines/3}\predref{print_message_lines}{3} describes the elements that may
appear in the output list.

\begin{code}
:- multifile
        prolog:message//1.

prolog:message(download_url(URL, I, Total)) -->
        { Perc is round(I*100/Total) },
        [ 'Downloaded ~w; ~D from ~D (~d%)'-[URL, I, Total, Perc] ].
\end{code}

\noindent
A \emph{user} of the library may define rules for \index{message_hook/3}\predref{message_hook}{3}.   The
rule below acts on the message content.  Other applications can act on
the message level and, for example, popup a message box for warnings and
errors.

\begin{code}
:- multifile user:message_hook/3.

message_hook(download_url(URL, I, Total), _Kind, _Lines) :-
        <send this information to a GUI component>
\end{code}

\noindent
In addition, using the command line option \cmdlineoption{-q}, the user
can disable all \jargon{informational} messages.


\section{Handling signals}			\label{sec:signal}

As of version 3.1.0, SWI-Prolog is able to handle software interrupts
(signals) in Prolog as well as in foreign (C) code (see \secref{csignal}).

Signals are used to handle internal errors (execution of a non-existing
CPU instruction, arithmetic domain errors, illegal memory access,
resource overflow, etc.), as well as for dealing with asynchronous
interprocess communication.

Signals are defined by the POSIX standard and part of all Unix machines.
The MS-Windows Win32 provides a subset of the signal handling routines,
lacking the vital functionality to raise a signal in another thread for
achieving asynchronous interprocess (or interthread) communication
(Unix kill() function).

\begin{description}
    \predicate{on_signal}{3}{+Signal, -Old, :New}
Determines the reaction on \arg{Signal}.  \arg{Old} is unified with
the old behaviour, while the behaviour is switched to \arg{New}.  As
with similar environment control predicates, the current value is
retrieved using \exam{on_signal(Signal, Current, Current)}.

The action description is an atom denoting the name of the predicate
that will be called if \arg{Signal} arrives. \index{on_signal/3}\predref{on_signal}{3} is a
meta-predicate, which implies that \bnfmeta{Module}:\bnfmeta{Name} refers to \bnfmeta{Name}/1
in module \bnfmeta{Module}. The handler is called with a single argument:
the name of the signal as an atom. The Prolog names for signals are
explained below.

Two predicate names have special meaning.  \const{throw} implies Prolog
will map the signal onto a Prolog exception as described in
\secref{exception}.  \const{default} resets the handler to the settings
active before SWI-Prolog manipulated the handler.

Signals bound to a foreign function through \cfuncref{PL_signal}{} are reported
using the term \term{\$foreign_function}{Address}.

After receiving a signal mapped to \const{throw}, the exception raised
has the following structure:

\begin{quote}\tt
error(signal(\bnfmeta{SigName}, \bnfmeta{SigNum}), \bnfmeta{Context})
\end{quote}

The signal names are defined by the POSIX standard as symbols of the
form {\tt SIG}\bnfmeta{SIGNAME}. The Prolog name for a signal is the lowercase
version of \bnfmeta{SIGNAME}. The predicate \index{current_signal/3}\predref{current_signal}{3} may be used to map
between names and signals.

Initially, some signals are mapped to \const{throw}, while all other
signals are \const{default}. The following signals throw an exception:
\const{fpe}, \const{alrm}, \const{xcpu}, \const{xfsz} and \const{vtalrm}.

    \predicate{current_signal}{3}{?Name, ?Id, ?Handler}
Enumerate the currently defined signal handling.  \arg{Name} is the
signal name, \arg{Id} is the numerical identifier and \arg{Handler}
is the currently defined handler (see \index{on_signal/3}\predref{on_signal}{3}).

    \predicate{prolog_alert_signal}{2}{?Old, +New}
Query or set the signal used to unblock blocking system calls on Unix
systems and process pending Prolog signals. The default is
\const{SIGUSR2}. See also \cmdlineoption{--sigalert}.
\end{description}


\subsection{Notes on signal handling}
\label{sec:signalhandling}

Before deciding to deal with signals in your application, please
consider the following:

\begin{itemlist}
    \item[Portability]
On MS-Windows, the signal interface is severely limited. Different Unix
brands support different sets of signals, and the relation between
signal name and number may vary. Currently, the system only supports
signals numbered 1 to 32\footnote{TBD: the system should support the
Unix realtime signals}. Installing a signal outside the limited set of
supported signals in MS-Windows crashes the application.

    \item[Safety]
Immediately delivered signals (see below) are unsafe. This implies that
foreign functions called from a handler cannot safely use the SWI-Prolog
API and	cannot use C longjmp().  Handlers defined as \const{throw} are
unsafe.  Handlers defined to call a predicate are safe.  Note that the
predicate can call \index{throw/1}\predref{throw}{1}, but the delivery is delayed until Prolog
is in a safe state.

The C-interface described in \secref{csignal} provides the option
\const{PL_SIGSYNC} to select either safe synchronous or unsafe
asynchronous delivery.

    \item[Time of delivery]
Using \const{throw} or a foreign handler, signals are delivered
immediately (as defined by the OS). When using a Prolog predicate,
delivery is delayed to a safe moment.  Blocking system calls or
foreign loops may cause long delays.  Foreign code can improve
on that by calling \cfuncref{PL_handle_signals}{}.

Signals are blocked when the garbage collector is active.
\end{itemlist}


\section{DCG Grammar rules}			\label{sec:DCG}

\index{DCG}\index{serialize}\index{deserialize}%
Grammar rules form a comfortable interface to \jargon{difference lists}.
They are designed both to support writing parsers that build a parse
tree from a list of characters or tokens and for generating a flat list
from a term.

Grammar rules look like ordinary clauses using \functor{\Sdcg}{2} for
separating the head and body rather than \functor{\Sneck}{2}. Expanding
grammar rules is done by \index{expand_term/2}\predref{expand_term}{2}, which adds two additional
arguments to each term for representing the difference list.

The body of a grammar rule can contain three types of terms. A callable
term is interpreted as a reference to a grammar rule. Code between
\verb${$\ldots\verb$}$ is interpreted as plain Prolog code, and finally,
a list is interpreted as a sequence of \jargon{literals}. The Prolog
control-constructs (\functor{\Snot}{1}, \functor{\Sifthen}{2}, \functor{\Ssemicolon}/2,
\functor{\Scomma}{2} and \functor{\Scut}{0}) can be used in grammar rules.

We illustrate the behaviour by defining a rule set for parsing an
integer.

\begin{code}
integer(I) -->
        digit(D0),
        digits(D),
        { number_codes(I, [D0|D])
        }.

digits([D|T]) -->
        digit(D), !,
        digits(T).
digits([]) -->
        [].

digit(D) -->
        [D],
        { code_type(D, digit)
        }.
\end{code}

\noindent
Grammar rule sets are called using the built-in predicates \index{phrase/2}\predref{phrase}{2}
and \index{phrase/3}\predref{phrase}{3}:

\begin{description}
    \predicate{phrase}{2}{:DCGBody, ?List}
Equivalent to \exam{phrase(\arg{DCGBody}, \arg{InputList}, [])}.
    \predicate{phrase}{3}{:DCGBody, ?List, ?Rest}
True when \arg{DCGBody} applies to the difference
\arg{List}/\arg{Rest}. Although \arg{DCGBody} is typically a
\jargon{callable} term that denotes a grammar rule, it can be any
term that is valid as the body of a DCG rule.

The example below calls the rule set integer//1 defined in \secref{DCG}
and available from \pllib{library(dcg/basics)}, binding \arg{Rest} to
the remainder of the input after matching the integer.

\begin{code}
?- [library(dcg/basics)].
?- atom_codes('42 times', Codes),
   phrase(integer(X), Codes, Rest).
X = 42
Rest = [32, 116, 105, 109, 101, 115]
\end{code}

\noindent
The next example exploits a complete body. Given the following
definition of \nodcgref{digit_weight}{1}, we can pose the query
below.

\begin{code}
digit_weight(W) -->
        [D],
        { code_type(D, digit(W)) }.
\end{code}

\noindent
\begin{code}
?- atom_codes('Version 3.4', Codes),
   phrase(("Version ",
           digit_weight(Major),".",digit_weight(Minor)),
          Codes).
Major = 3,
Minor = 4.
\end{code}

\noindent
The SWI-Prolog implementation of \index{phrase/3}\predref{phrase}{3} verifies that the \arg{List}
and \arg{Rest} arguments are unbound, bound to the empty list or a list
\jargon{cons cell}. Other values raise a type error.\footnote{The ISO
standard allows for both raising a type error and accepting any term
as input and output. Note the tail of the list is not checked for
performance reasons.}  The predicate \index{call_dcg/3}\predref{call_dcg}{3} is provided to use
grammar rules with terms that are not lists.

Note that the syntax for lists of codes changed in SWI-Prolog version~7
(see \secref{strings}). If a DCG body is translated, both \verb$"text"$
and \verb$`text`$ is a valid code-list literal in version~7. A version~7
string (\verb$"text"$) is \textbf{not} acceptable for the second and
third arguments of \index{phrase/3}\predref{phrase}{3}. This is typically not a problem for
applications as the input of a DCG rarely appears in the source code.
For testing in the toplevel, one must use double quoted text in versions
prior to~7 and back quoted text in version~7 or later.

See also \index{portray_text/1}\predref{portray_text}{1}, which can be used to print lists of character
codes as a string to the top level and debugger to facilitate debugging
DCGs that process character codes. The library \pllib{apply_macros}
compiles \index{phrase/3}\predref{phrase}{3} if the argument is sufficiently instantiated,
eliminating the runtime overhead of translating \arg{DCGBody} and
meta-calling.

    \predicate{call_dcg}{3}{:DCGBody, ?State0, ?State}
As \index{phrase/3}\predref{phrase}{3}, but without type checking \arg{State0} and \arg{State}.
This allows for using DCG rules for threading an arbitrary state
variable. This predicate was introduced after type checking was added to
\index{phrase/3}\predref{phrase}{3}.\footnote{After discussion with Samer Abdallah.}

A portable solution for threading state through a DCG can be implemented
by wrapping the state in a list and use the DCG semicontext facility.
Subsequently, the following predicates may be used to access and modify
the state:\footnote{This solution was proposed by Markus Triska.}

\begin{code}
state(S), [S] --> [S].
state(S0, S), [S] --> [S0].
\end{code}

\noindent
\end{description}

As stated above, grammar rules are a general interface to difference
lists. To illustrate, we show a DCG-based implementation of
\index{reverse/2}\predref{reverse}{2}:

\begin{code}
reverse(List, Reversed) :-
        phrase(reverse(List), Reversed).

reverse([])    --> [].
reverse([H|T]) --> reverse(T), [H].
\end{code}

\noindent
\section{Database}			\label{sec:db}

SWI-Prolog offers several ways to store data in globally accessible
memory, i.e., outside the Prolog \jargon{stacks}. Data stored this way
notably does not change on \jargon{backtracking}. Typically it is a bad
idea to use any of the predicates in this section for realising global
variables that can be assigned to. Typically, first consider
representing data processed by your program as terms passed around as
predicate arguments. If you need to reason over multiple solutions to a
goal, consider \index{findall/3}\predref{findall}{3}, \index{aggregate/3}\predref{aggregate}{3} and related predicates.

Nevertheless, there are scenarios where storing data outside the Prolog
stacks is a good option. Below are the main options for storing data:

\begin{description}
    \item[Using dynamic predicates]
Dynamic predicates are predicates for which the list of clauses is
modified at runtime using \index{asserta/1}\predref{asserta}{1}, \index{assertz/1}\predref{assertz}{1}, \index{retract/1}\predref{retract}{1} or
\index{retractall/1}\predref{retractall}{1}. Following the ISO standard, predicates that are modified
this way need to be declared using the \index{dynamic/1}\predref{dynamic}{1} \jargon{directive}.
These facilities are defined by the ISO standard and widely supported.
The mechanism is often considered slow in the literature. Performance
depends on the Prolog implementation. In SWI-Prolog, querying dynamic
predicates has the same performance as static ones. The manipulation
predicates are fast. Using \index{retract/1}\predref{retract}{1} or \index{retractall/1}\predref{retractall}{1} on a predicate
registers the predicate as `dirty'. Dirty predicates are cleaned by
\index{garbage_collect_clauses/0}\predref{garbage_collect_clauses}{0}, which is normally automatically invoked. Some
workloads may result in significant performance reduction due to
skipping retracted clauses and/or clause garbage collection.

Dynamic predicates can be wrapped using library \pllib{persistency} to
maintain a backup of the data on disk. Dynamic predicates come in two
flavours, \jargon{shared} between threads and \jargon{local} to each
thread. The latter version is created using the directive
\index{thread_local/1}\predref{thread_local}{1}.

    \item[The recorded database]
The `recorded database' registers a list of terms with a \jargon{key},
an atom or compound term. The list is managed using \index{recorda/3}\predref{recorda}{3}, \index{recordz/3}\predref{recordz}{3}
and \index{erase/1}\predref{erase}{1}. It is queried using \index{recorded/3}\predref{recorded}{3}. The recorded database is
not part of the ISO standard but fairly widely supported, notably in
implementations building on the `Edinburgh tradition'.  There are few
reasons to use this database in SWI-Prolog due to the good performance
of dynamic predicates.  Advantages are (1) the handle provides a direct
reference to a term, (2) cyclic terms can be stored and (3) attributes
(\secref{attvar}) are preserved.  Disadvantages are (1) the terms in
a list associated with a key are not indexed, (2) the poorly specified
\jargon{immediate update semantics} (see \secref{update} applies to the
recorded database and (3) reduced portability.

    \item[The \index{flag/3}\predref{flag}{3} predicate]
The predicate \index{flag/3}\predref{flag}{3} associates one simple value (number or atom) with
a key (atom, integer or compound).  It is an old SWI-Prolog specific
predicate that should be considered deprecated, although there is no
plan to remove it.

    \item[Using global variables]
The predicates \index{b_setval/2}\predref{b_setval}{2} and \index{nb_setval/2}\predref{nb_setval}{2} associate a term living on the
Prolog stack with a name, either backtrackable or non-backtrackable.
Backtrackable and non-backtrackable assignment without using a global
name can be realised with \index{setarg/3}\predref{setarg}{3} and \index{nb_setarg/3}\predref{nb_setarg}{3}.  Notably the latter
are used to realise aggregation as e.g., \index{aggregate_all/3}\predref{aggregate_all}{3} performs.

    \item[Tries]
As of version 7.3.21, SWI-Prolog provides \jargon{tries} (prefix trees)
to associate a term \jargon{variant} with a value. Tries have been
introduced to support \arg{tabling} and are described in \secref{trie}.
\end{description}

\subsection{Managing (dynamic) predicates}
\label{sec:dynpreds}

\begin{description}
    \predicate[ISO]{abolish}{1}{:PredicateIndicator}
Removes all clauses of a predicate with functor \arg{Functor} and arity
\arg{Arity} from the database. All predicate attributes (dynamic,
multifile, index, etc.) are reset to their defaults. Abolishing an
imported predicate only removes the import link; the predicate will keep
its old definition in its definition module.

According to the ISO standard, \index{abolish/1}\predref{abolish}{1} can only be applied to dynamic
procedures.  This is odd, as for dealing with dynamic procedures there
is already \index{retract/1}\predref{retract}{1} and \index{retractall/1}\predref{retractall}{1}.  The \index{abolish/1}\predref{abolish}{1} predicate was
introduced in DEC-10 Prolog precisely for dealing with static procedures.
In SWI-Prolog, \index{abolish/1}\predref{abolish}{1} works on static procedures, unless the Prolog
flag \prologflag{iso} is set to \const{true}.

It is advised to use \index{retractall/1}\predref{retractall}{1} for erasing all clauses of a dynamic
predicate.

    \predicate{abolish}{2}{+Name, +Arity}
Same as \term{abolish}{Name/Arity}. The predicate \index{abolish/2}\predref{abolish}{2} conforms
to the Edinburgh standard, while \index{abolish/1}\predref{abolish}{1} is ISO compliant.

    \predicate{copy_predicate_clauses}{2}{:From, :To}
Copy all clauses of predicate \arg{From} to \arg{To}. The predicate
\arg{To} must be dynamic or undefined. If \arg{To} is undefined, it is
created as a dynamic predicate holding a copy of the clauses of
\arg{From}. If \arg{To} is a dynamic predicate, the clauses of
\arg{From} are added (as in \index{assertz/1}\predref{assertz}{1}) to the clauses of \arg{To}.
\arg{To} and \arg{From} must have the same arity. Acts as if defined by
the program below, but at a much better performance by avoiding
decompilation and compilation.

\begin{code}
copy_predicate_clauses(From, To) :-
        head(From, MF:FromHead),
        head(To, MT:ToHead),
        FromHead =.. [_|Args],
        ToHead =.. [_|Args],
        forall(clause(MF:FromHead, Body),
               assertz(MT:ToHead, Body)).

head(From, M:Head) :-
        strip_module(From, M, Name/Arity),
        functor(Head, Name, Arity).
\end{code}

\noindent
    \predicate{redefine_system_predicate}{1}{+Head}
This directive may be used both in module \const{user} and in normal
modules to redefine any system predicate.  If the system definition is
redefined in module \const{user}, the new definition is the default
definition for all sub-modules.  Otherwise the redefinition is local
to the module.  The system definition remains in the module \const{system}.

Redefining system predicate facilitates the definition of compatibility
packages.  Use in other contexts is discouraged.

    \predicate[ISO,nondet]{retract}{1}{+Term}
When \arg{Term} is an atom or a term it is unified with the first
unifying fact or clause in the database. The fact or clause is removed
from the database. The \index{retract/1}\predref{retract}{1} predicate respects the \jargon{logical
update view}. This implies that \index{retract/1}\predref{retract}{1} succeeds for all clauses that
match \arg{Term} when the predicate was \emph{called}. The example below
illustrates that the first call to \index{retract/1}\predref{retract}{1} succeeds on \const{bee} on
backtracking despite the fact that \const{bee} is already
retracted.\footnote{Example by Jan Burse}.

\begin{code}
:- dynamic insect/1.
insect(ant).
insect(bee).

?- (   retract(insect(I)),
       writeln(I),
       retract(insect(bee)),
       fail
   ;   true
   ).
ant ;
bee.
\end{code}

\noindent
If multiple threads start a retract on the same predicate at the same
time their notion of the \jargon{entry generation} is adjusted such that
they do not retract the same first clause. This implies that, if
multiple threads use \verb$once(retract(Term))$, no two threads will
retract the same clause. Note that on backtracking over \index{retract/1}\predref{retract}{1},
multiple threads may retract the same clause as both threads respect the
logical update view.

    \predicate[ISO,det]{retractall}{1}{+Head}
All facts or clauses in the database for which the \arg{head}
unifies with \arg{Head} are removed. If \arg{Head} refers to a predicate
that is not defined, it is implicitly created as a dynamic predicate.
See also \index{dynamic/1}\predref{dynamic}{1}.\footnote{The ISO standard only allows using
\index{dynamic/1}\predref{dynamic}{1} as a \jargon{directive}.}

    \predicate[ISO]{asserta}{1}{+Term}
\nodescription
    \predicate[ISO]{assertz}{1}{+Term}
\nodescription
    \predicate[deprecated]{assert}{1}{+Term}
Assert a clause (fact or rule) into the database. The predicate
\index{asserta/1}\predref{asserta}{1} asserts the clause as first clause of the predicate while
\index{assertz/1}\predref{assertz}{1} assert the clause as last clause. The deprecated \index{assert/1}\predref{assert}{1} is
equivalent to \index{assertz/1}\predref{assertz}{1}. If the program space for the target module is
limited (see \index{set_module/1}\predref{set_module}{1}), \index{asserta/1}\predref{asserta}{1} can raise a
\term{resource_error}{program_space} exception.  The example below
adds two facts and a rule.  Note the double parentheses around the
rule.

\begin{code}
?- assertz(parent('Bob', 'Jane')).
?- assertz(female('Jane')).
?- assertz((mother(Child, Mother) :-
                parent(Child, Mother),
                female(Mother))).
\end{code}

\noindent
    \predicate{asserta}{2}{+Term, -Reference}
\nodescription
    \predicate{assertz}{2}{+Term, -Reference}
\nodescription
    \predicate[deprecated]{assert}{2}{+Term, -Reference}
Equivalent to \index{asserta/1}\predref{asserta}{1}, \index{assertz/1}\predref{assertz}{1}, \index{assert/1}\predref{assert}{1}, but in addition unifies
\arg{Reference} with a handle to the asserted clauses. The handle can be
used to access this clause with \index{clause/3}\predref{clause}{3} and \index{erase/1}\predref{erase}{1}.
\end{description}

\subsection{The recorded database}
\label{sec:recdb}

\begin{description}
    \predicate{recorda}{3}{+Key, +Term, -Reference}
Assert \arg{Term} in the recorded database under key \arg{Key}.
\arg{Key} is a small integer (range \prologflag{min_tagged_integer}
\ldots \prologflag{max_tagged_integer}, atom or compound term. If the
key is a compound term, only the name and arity define the key.
\arg{Reference} is unified with an opaque handle to the record (see
\index{erase/1}\predref{erase}{1}).

    \predicate{recorda}{2}{+Key, +Term}
Equivalent to \exam{recorda(\arg{Key}, \arg{Term}, _)}.

    \predicate{recordz}{3}{+Key, +Term, -Reference}
Equivalent to \index{recorda/3}\predref{recorda}{3}, but puts the \arg{Term} at the tail of the terms
recorded under \arg{Key}.

    \predicate{recordz}{2}{+Key, +Term}
Equivalent to \exam{recordz(\arg{Key}, \arg{Term}, _)}.

    \predicate{recorded}{3}{?Key, ?Value, ?Reference}
True if \arg{Value} is recorded under \arg{Key} and has the given
database \arg{Reference}. If \arg{Reference} is given, this predicate is
semi-deterministic. Otherwise, it must be considered non-deterministic.
If neither \arg{Reference} nor \arg{Key} is given, the triples are
generated as in the code snippet below.\footnote{Note that, without a
given \arg{Key}, some implementations return triples in the order
defined by \index{recorda/2}\predref{recorda}{2} and \index{recordz/2}\predref{recordz}{2}.}  See also \index{current_key/1}\predref{current_key}{1}.

\begin{code}
        current_key(Key),
        recorded(Key, Value, Reference)
\end{code}

\noindent
    \predicate{recorded}{2}{+Key, -Value}
Equivalent to \exam{recorded(\arg{Key}, \arg{Value}, _)}.

    \predicate{erase}{1}{+Reference}
Erase a record or clause from the database.  \arg{Reference} is a
db-reference returned by \index{recorda/3}\predref{recorda}{3}, \index{recordz/3}\predref{recordz}{3} or \index{recorded/3}\predref{recorded}{3}, \index{clause/3}\predref{clause}{3},
\index{assert/2}\predref{assert}{2}, \index{asserta/2}\predref{asserta}{2} or \index{assertz/2}\predref{assertz}{2}. Fail silently if the referenced object
no longer exists. Notably, if multiple threads attempt to erase the same
clause one will succeed and the others will fail.

    \predicate{instance}{2}{+Reference, -Term}
Unify \arg{Term} with the referenced clause or database record.  Unit
clauses are represented as \arg{Head} :- \const{true}.
\end{description}


\subsection{Flags}				\label{sec:flag}

The predicate \index{flag/3}\predref{flag}{3} is the oldest way to store global non-backtrackable
data in SWI-Prolog. Flags are global and shared by all threads. Their
value is limited to atoms, small (64-bit) integers and floating point
numbers.  Flags are thread-safe.  The flags described in this section
must not be confused with \jargon{Prolog flags} described in
\secref{flags}.

\begin{description}
    \predicate{get_flag}{2}{+Key, -Value}
True when \arg{Value} is the value currently associated with \arg{Key}.
If \arg{Key} does not exist, a new flag with value `0' (zero) is
created.
    \predicate{set_flag}{2}{+Key, Value}
Set flag \arg{Key} to \arg{Value}. Value must be an atom, small (64-bit)
integer or float.
    \predicate{flag}{3}{+Key, -Old, +New}
True when \arg{Old} is the current value of the flag \arg{Key} and the
flag has been set to \arg{New}. \arg{New} can be an arithmetic
expression. The update is \jargon{atomic}. This predicate can be used to
create a \emph{shared} global counter as illustrated in the example
below.

\begin{code}
next_id(Id) :-
    flag(my_id, Id, Id+1).
\end{code}

\noindent
\end{description}

\subsection{Tries}
\label{sec:trie}

Tries (also called \jargon{digital tree}, \jargon{radix tree} or
\jargon{prefix tree} maintain a mapping between a variant of a term (see
\predref{\Sstructeq}{2}) and a value. They have been introduced in SWI-Prolog
7.3.21 as part of the implementation of \jargon{tabling}. The current
implementation is rather immature.   In particular, the following
limitations currently apply:

\begin{shortlist}
    \item Tries are not thread-safe.
    \item Tries should not be modified while non-deterministic
          predicates such as \index{trie_gen/3}\predref{trie_gen}{3} are running on the trie.
    \item Terms cannot have \jargon{attributed variables}.
    \item Terms cannot be \jargon{cyclic}.  Possibly this will
	  not change because cyclic terms can only be supported
          after creating a canonical form of the term.
\end{shortlist}

\textbf{We give the definition of these predicates for reference and
debugging tabled predicates.  Future versions are likely to get a more
stable and safer implementation. The API to tries should not be
considered stable.}


\begin{description}
    \predicate{trie_new}{1}{-Trie}
Create a new trie and unify \arg{Trie} with a handle to the trie.  The
trie handle is a \jargon{blob}. Tries are subject to atom garbage
collection.

    \predicate{trie_destroy}{1}{+Trie}
Destroy \arg{Trie}. This removes all nodes from the trie and causes
further access to \arg{Trie} to raise an existence_error exception. The
handle itself is reclaimed by atom garbage collection.

    \predicate[semidet]{is_trie}{1}{@Trie}
True when \arg{Trie} is a trie object.  See also \index{current_trie/1}\predref{current_trie}{1}.

    \predicate[nondet]{current_trie}{1}{-Trie}
True if \arg{Trie} is a currently existing trie.  As this enumerates and
then filters all known atoms this predicate is slow and should only be
used for debugging purposes.  See also \index{is_trie/1}\predref{is_trie}{1}.

    \predicate{trie_insert}{3}{+Trie, +Key, +Value}
Insert the term \arg{Key} into \arg{Trie} and associate it with
\arg{Value}. \arg{Value} can be any term.  If \arg{Key}-\arg{Value}
is already part of \arg{Trie}, the predicates \emph{fails} silently.
If \arg{Key} is in \arg{Trie} associated with a different value, a
\const{permission_error} is raised.

    \predicate{trie_update}{3}{+Trie, +Key, +Value}
As \index{trie_insert/3}\predref{trie_insert}{3}, but if \arg{Key} is in \arg{Trie}, its associated
value is \emph{updated}.

    \predicate{trie_insert}{4}{+Trie, +Term, +Value, -Handle}
As \index{trie_insert/3}\predref{trie_insert}{3}, returning a handle to the trie node. This predicate is
currently unsafe as \arg{Handle} is an integer used to encode a pointer.
It was used to implement a pure Prolog version of the \pllib{tabling}
library.

    \predicate{trie_delete}{3}{+Trie, +Key, ?Value}
Delete \arg{Key} from \arg{Trie} if the value associated with \arg{Key}
unifies with \arg{Value}.

    \predicate{trie_lookup}{3}{+Trie, +Key, -Value}
True if the term \arg{Key} is in \arg{Trie} and associated with
\arg{Value}.

    \predicate{trie_term}{2}{+Handle, -Term}
True when \arg{Term} is a copy of the term associated with \arg{Handle}.
The result is undefined (including crashes) if \arg{Handle} is not a
handle returned by \index{trie_insert_new/3}\predref{trie_insert_new}{3} or the node has been removed
afterwards.

    \predicate[nondet]{trie_gen}{3}{+Trie, ?Key, -Value}
True when \arg{Key} is associated with \arg{Value} in \arg{Trie}.
Backtracking retrieves all pairs. Currently scans the entire
trie, even if \arg{Key} is partly known.  Currently unsafe if \arg{Trie}
is modified while the values are being enumerated.

    \predicate[nondet]{trie_property}{2}{?Trie, ?Property}
True if \arg{Trie} exists with \arg{Property}.	 Intended for
debugging and statistical purposes.  Retrieving some of these
properties visit all nodes of the trie. Defined properties are
    \begin{description}
	\termitem{value_count}{-Count}
    Number of key-value pairs in the trie.
	\termitem{node_count}{-Count}
    Number of nodes in the trie.
	\termitem{size}{-Bytes}
    Required storage space of the trie.
	\termitem{hashed}{-Count}
    Number of nodes that use a hashed index to its children.
    \end{description}
\end{description}


\subsection{Update view}			\label{sec:update}

\index{logical,update view}%
\index{immediate, update view}%
\index{update view}%
Traditionally, Prolog systems used the \jargon{immediate update view}:
new clauses became visible to predicates backtracking over dynamic
predicates immediately, and retracted clauses became invisible
immediately.

Starting with SWI-Prolog 3.3.0 we adhere to the \jargon{logical update
view}, where backtrackable predicates that enter the definition of a
predicate will not see any changes (either caused by \index{assert/1}\predref{assert}{1} or
\index{retract/1}\predref{retract}{1}) to the predicate.  This view is the ISO standard, the
most commonly used and the most `safe'.%
    \footnote{For example, using the immediate update view, no call to a
	      dynamic predicate is deterministic.}
Logical updates are realised by keeping reference counts on predicates
and \jargon{generation} information on clauses.  Each change to the
database causes an increment of the generation of the database.  Each
goal is tagged with the generation in which it was started.  Each clause
is flagged with the generation it was created in as well as the generation
it was erased from.  Only clauses with a `created' \ldots `erased' interval
that encloses the generation of the current goal are considered visible.


\subsection{Indexing databases}			\label{sec:hashterm}

\index{indexing,term-hashes}%

The indexing capabilities of SWI-Prolog are described in
\secref{jitindex}. Summarizing, SWI-Prolog creates indexes for any
applicable argument, pairs of arguments and indexes on the arguments of
compound terms when applicable. Extended JIT indexing is not widely
supported amoung Prolog implementations. Programs that aim at
portability should consider using \index{term_hash/2}\predref{term_hash}{2} and \index{term_hash/4}\predref{term_hash}{4} to design
their database such that indexing on constant or functor (name/arity
reference) on the first argument is sufficient. In some cases, using the
predicates below to add one or more additional columns (arguments) to a
database predicate may improve performance. The overall design of code
using these predicates is given below. Note that as \index{term_hash/2}\predref{term_hash}{2} leaves
the hash unbound if \arg{Term} is not ground. This causes the lookup to
be fast if \arg{Term} is ground and correct (but slow) otherwise.

\begin{code}
:- dynamic
    x/2.

assert_x(Term) :-
    term_hash(Term, Hash),
    assertz(x(Hash, Term)).

x(Term) :-
    term_hash(Term, Hash),
    x(Hash, Term).
\end{code}

\noindent
\begin{description}
    \predicate[det]{term_hash}{2}{+Term, -HashKey}
If \arg{Term} is a ground term (see \index{ground/1}\predref{ground}{1}), \arg{HashKey} is unified
with a positive integer value that may be used as a hash key to the
value. If \arg{Term} is not ground, the predicate leaves \arg{HashKey}
an unbound variable.  Hash keys are in the range $0 \ldots 16,777,215$,
the maximal integer that can be stored efficiently on both 32 and 64
bit platforms.

This predicate may be used to build hash tables as well as to exploit
argument indexing to find complex terms more quickly.

The hash key does not rely on temporary information like addresses of
atoms and may be assumed constant over different invocations and
versions of SWI-Prolog.\footnote{Last change: version 5.10.4} Hashes
differ between big and little endian machines. The \index{term_hash/2}\predref{term_hash}{2} predicate
is cycle-safe.\bug{All arguments that (indirectly) lead to a cycle
have the same hash key.}

    \predicate[det]{term_hash}{4}{+Term, +Depth, +Range, -HashKey}
As \index{term_hash/2}\predref{term_hash}{2}, but only considers \arg{Term} to the specified
\arg{Depth}.   The top-level term has depth 1, its arguments have
depth 2, etc.  That is, $\arg{Depth} = 0$ hashes nothing; $\arg{Depth} = 1$
hashes atomic values or the functor and arity of a compound term,
not its arguments; $\arg{Depth} = 2$ also indexes the immediate
arguments, etc.

\arg{HashKey} is in the range $[0 \ldots \arg{Range}-1]$.  \arg{Range}
must be in the range $[1 \ldots 2147483647]$

    \predicate[det]{variant_sha1}{2}{+Term, -SHA1}
Compute a SHA1-hash from \arg{Term}. The hash is represented as a
40-byte hexadecimal atom. Unlike \index{term_hash/2}\predref{term_hash}{2} and friends, this predicate
produces a hash key for non-ground terms. The hash is invariant over
variable-renaming (see \predref{\Sstructeq}{2}) and constants over different
invocations of Prolog.\bug{The hash depends on word order
(big/little-endian) and the wordsize (32/64 bits).}

This predicate raises an exception when trying to compute the hash on
a cyclic term or attributed term.  Attributed terms are not handled
because \index{subsumes_chk/2}\predref{subsumes_chk}{2} is not considered well defined for attributed
terms.  Cyclic terms are not supported because this would require
establishing a canonical cycle.  That is, given A=[a|A] and B=[a,a|B],
\arg{A} and \arg{B} should produce the same hash.  This is not
(yet) implemented.

This hash was developed for lookup of solutions to a goal stored in a
table.  By using a cryptographic hash, heuristic algorithms can often
ignore the possibility of hash collisions and thus avoid storing the
goal term itself as well as testing using \predref{\Sstructeq}{2}.

    \predicate[det]{variant_hash}{2}{+Term, -HashKey}
Similar to \index{variant_sha1/2}\predref{variant_sha1}{2}, but using a non-cryptographic hash and
produces an integer result like \index{term_hash/2}\predref{term_hash}{2}. This version does deal with
attributed variables, processing them as normal variables.  This hash is
primarily intended to speedup finding variant terms in a set of terms.
\bug{As \index{variant_sha1/2}\predref{variant_sha1}{2}, cyclic terms result in an exception.}
\end{description}


\section{Declaring predicate properties}	\label{ch:dynamic}
\label{sec:declare}

This section describes directives which manipulate attributes of
predicate definitions. The functors \index{dynamic/1}\predref{dynamic}{1}, \index{multifile/1}\predref{multifile}{1},
\index{discontiguous/1}\predref{discontiguous}{1} and \index{public/1}\predref{public}{1} are operators of priority 1150 (see \index{op/3}\predref{op}{3}),
which implies that the list of predicates they involve can just be a
comma-separated list:

\begin{code}
:- dynamic
        foo/0,
        baz/2.
\end{code}

\noindent
In SWI-Prolog all these directives are just predicates. This implies
they can also be called by a program.  Do not rely on this feature if
you want to maintain portability to other Prolog implementations.

\begin{description}
    \prefixop[ISO]{dynamic}{:PredicateIndicator, \ldots}
Informs the interpreter that the definition of the predicate(s) may change
during execution (using \index{assert/1}\predref{assert}{1} and/or \index{retract/1}\predref{retract}{1}). In the
multithreaded version, the clauses of dynamic predicates are shared
between the threads. The directive \index{thread_local/1}\predref{thread_local}{1} provides an
alternative where each thread has its own clause list for the
predicate.  Dynamic predicates can be turned into static ones using
\index{compile_predicates/1}\predref{compile_predicates}{1}.

    \predicate{compile_predicates}{1}{:ListOfPredicateIndicators}
Compile a list of specified dynamic predicates (see \index{dynamic/1}\predref{dynamic}{1} and
\index{assert/1}\predref{assert}{1}) into normal static predicates.  This call tells the Prolog
environment the definition will not change anymore and further calls
to \index{assert/1}\predref{assert}{1} or \index{retract/1}\predref{retract}{1} on the named predicates raise a permission
error.  This predicate is designed to deal with parts of the program
that are generated at runtime but do not change during the remainder
of the program execution.%
	\footnote{The specification of this predicate is from
		  Richard O'Keefe.  The implementation is allowed to
		  optimise the predicate.  This is not yet implemented.
		  In multithreaded Prolog, however, static code runs
		  faster as it does not require synchronisation.  This
		  is particularly true on SMP hardware.}

    \prefixop[ISO]{multifile}{:PredicateIndicator, \ldots}
Informs the system that the specified predicate(s) may be defined over
more than one file. This stops \index{consult/1}\predref{consult}{1} from redefining a predicate
when a new definition is found.

    \prefixop[ISO]{discontiguous}{:PredicateIndicator, \ldots}
Informs the system that the clauses of the specified predicate(s) might
not be together in the source file.  See also \index{style_check/1}\predref{style_check}{1}.

    \prefixop{public}{:PredicateIndicator, \ldots}
Instructs the cross-referencer that the predicate can be called. It has
no semantics.\footnote{This declaration is compatible with SICStus. In
YAP, \index{public/1}\predref{public}{1} instructs the compiler to keep the source. As the source
is always available in SWI-Prolog, our current interpretation also
enhances the compatibility with YAP.} The public declaration can be
queried using \index{predicate_property/2}\predref{predicate_property}{2}. The \index{public/1}\predref{public}{1} directive does
\emph{not} export the predicate (see \index{module/1}\predref{module}{1} and \index{export/1}\predref{export}{1}). The public
directive is used for (1) direct calls into the module from, e.g.,
foreign code, (2) direct calls into the module from other modules, or (3)
flag a predicate as being called if the call is generated by meta-calling constructs that are not analysed by the cross-referencer.

    \prefixop{non_terminal}{:PredicateIndicator, \ldots}
Sets the \const{non_terminal} attribute on the predicate. This indicates
that the predicate implements a \jargon{grammar rule}. Currently,
predicates that are exported using \arg{Name//Arity} syntax are flagged
as non-terminals. Ideally we should add this flag to any predicate
created from the expansion of a \const{\Sdcg} rule, but that is difficult
without breaking compatibility for programs that reason about
\index{expand_term/2}\predref{expand_term}{2},4.
\end{description}

\section{Examining the program}		\label{sec:examineprog}

\begin{description}
    \predicate{current_atom}{1}{-Atom}
Successively unifies \arg{Atom} with all atoms known to the system.
Note that \index{current_atom/1}\predref{current_atom}{1} always succeeds if \arg{Atom} is instantiated to
an atom.

    \predicate{current_blob}{2}{?Blob, ?Type}
Examine the type or enumerate blobs of the given \arg{Type}.  Typed
blobs are supported through the foreign language interface for
storing arbitrary BLOBs (Binary Large Object) or handles to external
entities. See \secref{blob} for details.

    \predicate{current_functor}{2}{?Name, ?Arity}
True when \arg{Name}/\arg{Arity} is a known functor. This means that at
some point in time a term with name \arg{Name} and \arg{Arity} arguments
was created. Functor objects are currently not subject to garbage
collection. Due to timing, \nopredref{t}{2} below with instantiated
\arg{Name} and \arg{Arity} can theoretically fail, i.e., a functor may
be visible in instantiated mode while it is not yet visible in unbound
mode.  Considering that the only practical value of \index{current_functor/2}\predref{current_functor}{2}
we are aware of is to analyse resource usage we accept this impure
behaviour.

\begin{code}
t(Name, Arity) :-
    (   current_functor(Name, Arity)
    ->  current_functor(N, A), N == Name, A == Arity
    ;   true
    ).
\end{code}

\noindent
    \predicate{current_flag}{1}{-FlagKey}
Successively unifies \arg{FlagKey} with all keys used for flags (see
\index{flag/3}\predref{flag}{3}).

    \predicate{current_key}{1}{-Key}
Successively unifies \arg{Key} with all keys used for records (see
\index{recorda/3}\predref{recorda}{3}, etc.).

    \predicate[ISO]{current_predicate}{1}{:PredicateIndicator}
True if \arg{PredicateIndicator} is a currently defined predicate. A
predicate is considered defined if it exists in the specified module, is
imported into the module or is defined in one of the modules from which
the predicate will be imported if it is called (see
\secref{importmodule}). Note that \index{current_predicate/1}\predref{current_predicate}{1} does \emph{not}
succeed for predicates that can be \jargon{autoloaded}.  See also
\index{current_predicate/2}\predref{current_predicate}{2} and \index{predicate_property/2}\predref{predicate_property}{2}.

If \arg{PredicateIndicator} is not fully specified, the predicate only
generates values that are defined in or already imported into the target
module. Generating all callable predicates therefore requires
enumerating modules using \index{current_module/1}\predref{current_module}{1}. Generating predicates
callable in a given module requires enumerating the import modules
using \index{import_module/2}\predref{import_module}{2} and the autoloadable predicates using the
\index{predicate_property/2}\predref{predicate_property}{2} \const{autoload}.

    \predicate{current_predicate}{2}{?Name, :Head}
Classical pre-ISO implementation of \index{current_predicate/1}\predref{current_predicate}{1}, where the
predicate is represented by the head term.  The advantage is that
this can be used for checking the existence of a predicate before calling
it without the need for \index{functor/3}\predref{functor}{3}:

\begin{code}
call_if_exists(G) :-
        current_predicate(_, G),
        call(G).
\end{code}

\noindent
Because of this intended usage, \index{current_predicate/2}\predref{current_predicate}{2} also succeeds if the
predicate can be autoloaded.  Unfortunately, checking the autoloader
makes this predicate relatively slow, in particular because a failed
lookup of the autoloader will cause the autoloader to verify that its
index is up-to-date.

    \predicate{predicate_property}{2}{:Head, ?Property}
True when \arg{Head} refers to a predicate that has property
\arg{Property}. With sufficiently instantiated \arg{Head},
\index{predicate_property/2}\predref{predicate_property}{2} tries to resolve the predicate the same way as
calling it would do: if the predicate is not defined it scans the
default modules (see \index{default_module/2}\predref{default_module}{2}) and finally tries the autoloader.
Unlike calling, failure to find the target predicate causes
\index{predicate_property/2}\predref{predicate_property}{2} to fail silently. If \arg{Head} is not sufficiently
bound, only currently locally defined and already imported predicates
are enumerated. See \index{current_predicate/1}\predref{current_predicate}{1} for enumerating all predicates.
A common issue concerns \emph{generating} all built-in predicates. This
can be achieved using the code below:

\begin{code}
generate_built_in(Name/Arity) :-
    predicate_property(system:Head, built_in),
    functor(Head, Name, Arity),
    \+ sub_atom(Name, 0, _, _, $).   % discard reserved names
\end{code}

\noindent
\arg{Property} is one of:

\begin{description}
    \termitem{autoload}{File}
True if the predicate can be autoloaded from the file \arg{File}.
Like \const{undefined}, this property is \emph{not} generated.

    \termitem{built_in}{}
True if the predicate is locked as a built-in predicate. This
implies it cannot be redefined in its definition module and it can
normally not be seen in the tracer.

    \termitem{defined}{}
True if the predicate is defined.  This property is aware of sources
being \emph{reloaded}, in which case it claims the predicate defined
only if it is defined in another source or it has seen a definition
in the current source.  See \index{compile_aux_clauses/1}\predref{compile_aux_clauses}{1}.

    \termitem{dynamic}{}
True if \index{assert/1}\predref{assert}{1} and \index{retract/1}\predref{retract}{1} may be used to modify the predicate.
This property is set using \index{dynamic/1}\predref{dynamic}{1}.

    \termitem{exported}{}
True if the predicate is in the public list of the context module.

    \termitem{imported_from}{Module}
Is true if the predicate is imported into the context module from
module \arg{Module}.

    \termitem{file}{FileName}
Unify \arg{FileName} with the name of the source file in which the
predicate is defined.  See also \index{source_file/2}\predref{source_file}{2} and the property
\const{line_count}.  Note that this reports the file of the
first clause of a predicate.  A more robust interface can be
achieved using \index{nth_clause/3}\predref{nth_clause}{3} and \index{clause_property/2}\predref{clause_property}{2}.

    \termitem{foreign}{}
True if the predicate is defined in the C language.

    \termitem{implementation_module}{-Module}
True when \arg{Module} is the module in which \arg{Head} is or will be
defined. Resolving this property goes through the same search mechanism
as when the an undefined predicate is encountered, but does not perform
any loading.  It searches (1) the module inheritence hierarchy (see
\index{default_module/2}\predref{default_module}{2}) and (2) the autoload index if the \prologflag{unknown}
flag is not set to \const{fail} in the target module.

    \termitem{indexed}{Indexes}
\arg{Indexes}\footnote{This predicate property should be used for
analysis and statistics only. The exact representation of \arg{Indexes}
may change between versions.} is a list of additional (hash) indexes on
the predicate. Each element of the list is a term
\arg{ArgSpec}-\arg{Index}. \arg{ArgSpec} denotes the indexed argument(s)
and is one of

\begin{description}
    \termitem{single}{Argument}
Hash on a single argument.  \arg{Argument} is the 1-based argument
number.
    \termitem{multi}{ArgumentList}
Hash on a combination of arguments.
    \termitem{deep}{Position}
Index on a sub-argument.  Position is a list holding first the
argument of the predicate then the argument into the compound
and recursively into deeper compound terms.
\end{description}

\arg{Index} is a term \term{hash}{Buckets, Speedup, Size, IsList}. Here
\arg{Buckets} is the number of buckets in the hash and \arg{Speedup} is
the expected speedup relative to trying all clauses linearly, \arg{Size}
is the size of the index in memory in bytes and finally, \arg{IsList}
indicates that a list is created for all clauses with the same key. This
is used to create \jargon{deep indexes} for the arguments of compound
terms.

    \termitem{interpreted}{}
True if the predicate is defined in Prolog. We return true on this
because, although the code is actually compiled, it is completely
transparent, just like interpreted code.

    \termitem{iso}{}
True if the predicate is covered by the ISO standard (ISO/IEC
13211-1).

    \termitem{line_count}{LineNumber}
Unify \arg{LineNumber} with the line number of the first clause of the
predicate.  Fails if the predicate is not associated with a file.  See
also \index{source_file/2}\predref{source_file}{2}.  See also the \const{file} property above, notably
the reference to \index{clause_property/2}\predref{clause_property}{2}.

    \termitem{multifile}{}
True if there may be multiple (or no) files providing clauses for the
predicate.  This property is set using \index{multifile/1}\predref{multifile}{1}.

    \termitem{meta_predicate}{Head}
If the predicate is declared as a meta-predicate using \index{meta_predicate/1}\predref{meta_predicate}{1},
unify \arg{Head} with the head-pattern.  The head-pattern is a
compound term with the same name and arity as the predicate where each
argument of the term is a meta-predicate specifier.  See \index{meta_predicate/1}\predref{meta_predicate}{1}
for details.

    \termitem{nodebug}{}
Details of the predicate are not shown by the debugger. This is the
default for built-in predicates.  User predicates can be compiled this
way using the Prolog flag \prologflag{generate_debug_info}.

    \termitem{non_terminal}
True if the predicate implements a \jargon{grammar rule}.  See
\index{non_terminal/1}\predref{non_terminal}{1}.

    \termitem{notrace}{}
Do not show ports of this predicate in the debugger.

    \termitem{number_of_clauses}{ClauseCount}
Unify \arg{ClauseCount} to the number of clauses associated with the
predicate.  Fails for foreign predicates.

    \termitem{number_of_rules}{RuleCount}
Unify \arg{RuleCount} to the number of clauses associated with the
predicate. A \jargon{rule} is defined as a clauses that has a body that
is not just \const{true} (i.e., a \jargon{fact}). Fails for foreign
predicates. This property is used to avoid analysing predicates with
only facts in \pllib{prolog_codewalk}.

    \termitem{last_modified_generation}{Generation}
Database generation at which the predicate was modified for the last
time.  Intended to quickly assesses the validity of caches.

    \termitem{public}{}
Predicate is declared public using \index{public/1}\predref{public}{1}.  Note that without further
definition, public predicates are considered undefined and this property
is \emph{not} reported.

    \termitem{quasi_quotation_syntax}{}
The predicate (with arity~4) is declared to provide quasi quotation
syntax with \index{quasi_quotation_syntax/1}\predref{quasi_quotation_syntax}{1}.

    \termitem{static}{}
The definition can \emph{not} be modified using \index{assertz/1}\predref{assertz}{1} and friends.
This property is the opposite from \const{dynamic}, i.e., for each
defined predicate, either \const{static} or \const{dynamic} is true but
never both.

    \termitem{thread_local}{}
If true (only possible on the multithreaded version) each thread has
its own clauses for the predicate. This property is set using
\index{thread_local/1}\predref{thread_local}{1}.

    \termitem{transparent}{}
True if the predicate is declared transparent using the
\index{module_transparent/1}\predref{module_transparent}{1} or \index{meta_predicate/1}\predref{meta_predicate}{1} declaration.  In the
latter case the property \term{meta_predicate}{Head} is also provided.
See \chapref{modules} for details.

    \termitem{undefined}{}
True if a procedure definition block for the predicate exists, but there
are no clauses for it and it is not declared dynamic or multifile. This
is true if the predicate occurs in the body of a loaded predicate, an
attempt to call it has been made via one of the meta-call predicates,
the predicate has been declared as e.g., a meta-predicate or the
predicate had a definition in the past. Originally used to find missing
predicate definitions. The current implementation of \index{list_undefined/0}\predref{list_undefined}{0}
used cross-referencing. Deprecated.

    \termitem{visible}{}
True when predicate can be called without raising a predicate existence
error. This means that the predicate is (1) defined, (2) can be
inherited from one of the default modules (see \index{default_module/2}\predref{default_module}{2}) or (3)
can be autoloaded. The behaviour is logically consistent iff the property
\const{visible} is provided explicitly. If the property is left unbound,
only defined predicates are enumerated.

    \termitem{volatile}{}
If true, the clauses are not saved into a saved state
by \index{qsave_program/[1,2]}\predref{qsave_program}{[1,2]}.  This property is set using \index{volatile/1}\predref{volatile}{1}.
\end{description}

    \predicate{dwim_predicate}{2}{+Term, -Dwim}
`Do What I Mean' (`dwim') support predicate. \arg{Term} is a term, whose
name and arity are used as a predicate specification. \arg{Dwim} is
instantiated with the most general term built from \arg{Name} and the
arity of a defined predicate that matches the predicate specified by
\arg{Term} in the `Do What I Mean' sense. See \index{dwim_match/2}\predref{dwim_match}{2} for `Do What
I Mean' string matching. Internal system predicates are not generated,
unless the access level is \const{system} (see
\prologflag{access_level}). Backtracking provides all alternative
matches.

    \predicate[ISO]{clause}{2}{:Head, ?Body}
True if \arg{Head} can be unified with a clause head and \arg{Body} with
the corresponding clause body. Gives alternative clauses on
backtracking. For facts, \arg{Body} is unified with the atom \arg{true}.

    \predicate{clause}{3}{:Head, ?Body, ?Reference}
Equivalent to \index{clause/2}\predref{clause}{2}, but unifies \arg{Reference} with a unique
reference to the clause (see also \index{assert/2}\predref{assert}{2}, \index{erase/1}\predref{erase}{1}). If \arg{Reference}
is instantiated to a reference the clause's head and body will be
unified with \arg{Head} and \arg{Body}.

    \predicate{nth_clause}{3}{?Pred, ?Index, ?Reference}
Provides access to the clauses of a predicate using their index number.
Counting starts at 1.  If \arg{Reference} is specified it unifies \arg{Pred}
with the most general term with the same name/arity as the predicate and
\arg{Index} with the index number of the clause.  Otherwise the name and
arity of \arg{Pred} are used to determine the predicate.  If \arg{Index}
is provided, \arg{Reference} will be unified with the clause reference.
If \arg{Index} is unbound, backtracking will yield both the indexes and
the references of all clauses of the predicate.  The following example
finds the 2nd clause of \index{append/3}\predref{append}{3}:

\begin{code}
?- use_module(library(lists)).
...
?- nth_clause(append(_,_,_), 2, Ref), clause(Head, Body, Ref).
Ref = <clause>(0x994290),
Head = lists:append([_G23|_G24], _G21, [_G23|_G27]),
Body = append(_G24, _G21, _G27).
\end{code}

\noindent
    \predicate{clause_property}{2}{+ClauseRef, -Property}
Queries properties of a clause. \arg{ClauseRef} is a reference to a
clause as produced by \index{clause/3}\predref{clause}{3}, \index{nth_clause/3}\predref{nth_clause}{3} or
\index{prolog_frame_attribute/3}\predref{prolog_frame_attribute}{3}. Unlike most other predicates that access
clause references, \index{clause_property/2}\predref{clause_property}{2} may be used to get information
about erased clauses that have not yet been reclaimed. \arg{Property} is
one of the following:

\begin{description}
    \termitem{file}{FileName}
Unify \arg{FileName} with the name of the file from which the clause
is loaded.  Fails if the clause was not created by loading a file
(e.g., clauses added using \index{assertz/1}\predref{assertz}{1}).  See also \const{source}.
    \termitem{line_count}{LineNumber}
Unify \arg{LineNumber} with the line number of the clause.  Fails if
the clause is not associated to a file.
    \termitem{size}{SizeInBytes}
True when \arg{SizeInBytes} is the size that the clause uses in memory
in bytes.  The size required by a predicate also includes the predicate
data record, a linked list of clauses, clause selection instructions and
optionally one or more clause indexes.
    \termitem{source}{FileName}
Unify \arg{FileName} with the name of the source file that created
the clause.  This is the same as the \const{file} property, unless the
file is loaded from a file that is textually included into source using
\index{include/1}\predref{include}{1}.  In this scenario, \const{file} is the included file, while
the \const{source} property refers to the \jargon{main} file.
    \termitem{fact}{}
True if the clause has no body.
    \termitem{erased}{}
True if the clause has been erased, but not yet reclaimed because
it is referenced.
    \termitem{predicate}{PredicateIndicator}
\arg{PredicateIndicator} denotes the predicate to which this clause
belongs. This is needed to obtain information on erased clauses because
the usual way to obtain this information using \index{clause/3}\predref{clause}{3} fails for erased
clauses.
    \termitem{module}{Module}
\arg{Module} is the context module used to execute the body of the
clause.  For normal clauses, this is the same as the module in which
the predicate is defined.  However, if a clause is compiled with a
module qualified \jargon{head}, the clause belongs to the predicate
with the qualified head, while the body is executed in the context
of the module in which the clause was defined.
\end{description}
\end{description}

\section{Input and output}		\label{sec:IO}

SWI-Prolog provides two different packages for input and output.  The
native I/O system is based on the ISO standard predicates \index{open/3}\predref{open}{3},
\index{close/1}\predref{close}{1} and friends.%
	\footnote{Actually based on Quintus Prolog, providing this interface
		  before the ISO standard existed.}
Being more widely portable and equipped with a clearer and more robust
specification, new code is encouraged to use these predicates for
manipulation of I/O streams.

\Secref{edinburghIO} describes \index{tell/1}\predref{tell}{1}, \index{see/1}\predref{see}{1} and friends, providing I/O
in the spirit of the traditional Edinburgh standard. These predicates
are layered on top of the ISO predicates. Both packages are fully
integrated; the user may switch freely between them.

\subsection{Predefined stream aliases}			\label{sec:streamalias}

Each thread has five stream aliases: \const{user_input},
\const{user_output}, \const{user_error}, \const{current_input}, and
\const{current_output}. Newly created threads inherit these stream
aliases from their parent. The \const{user_input}, \const{user_output}
and \const{user_error} aliases of the \const{main} thread are initially
bound to the standard operating system I/O streams (\jargon{stdin},
\jargon{stdout} and \jargon{stderr}, normally bound to the POSIX file
handles 0,~1 and~2). These aliases may be re-bound, for example if
standard I/O refers to a window such as in the \program{swipl-win.exe}
GUI executable for Windows. They can be re-bound by the user using
\index{set_prolog_IO/3}\predref{set_prolog_IO}{3} and \index{set_stream/2}\predref{set_stream}{2} by setting the alias of a stream (e.g,
\exam{set_stream(S, alias(user_output))}). An example of rebinding can
be found in library \pllib{prolog_server}, providing a \program{telnet}
service. The aliases \const{current_input} and \const{current_output}
define the source and destination for predicates that do not take a
stream argument (e.g., \index{read/1}\predref{read}{1}, \index{write/1}\predref{write}{1}, \index{get_code/1}\predref{get_code}{1}, \ldots). Initially,
these are bound to the same stream as \const{user_input} and
\const{user_error}. They are re-bound by \index{see/1}\predref{see}{1}, \index{tell/1}\predref{tell}{1}, \index{set_input/1}\predref{set_input}{1} and
\index{set_output/1}\predref{set_output}{1}. The \const{current_output} stream is also temporary
re-bound by \index{with_output_to/2}\predref{with_output_to}{2} or \index{format/3}\predref{format}{3} using e.g.,
\exam{format(atom(A), ...}. Note that code which explicitly writes to
the streams \const{user_output} and \const{user_error} will not be
redirected by \index{with_output_to/2}\predref{with_output_to}{2}.

\paragraph{Compatibility}

Note that the ISO standard only defines the \const{user_*} streams. The
`current' streams can be accessed using \index{current_input/1}\predref{current_input}{1} and
\index{current_output/1}\predref{current_output}{1}.  For example, an ISO compatible implementation of
\index{write/1}\predref{write}{1} is

\begin{code}
write(Term) :- current_output(Out), write_term(Out, Term).
\end{code}

\noindent
while SWI-Prolog additionally allows for

\begin{code}
write(Term) :- write(current_output, Term).
\end{code}

\noindent
\subsection{ISO Input and Output Streams}		\label{sec:isoIO}

The predicates described in this section provide ISO compliant I/O,
where streams are explicitly created using the predicate \index{open/3}\predref{open}{3}. The
resulting stream identifier is then passed as a parameter to the reading
and writing predicates to specify the source or destination of the data.

This schema is not vulnerable to filename and stream ambiguities as
well as changes to the working directory.  On the other hand, using
the notion of current-I/O simplifies reusability of code without the
need to pass arguments around.  E.g., see \index{with_output_to/2}\predref{with_output_to}{2}.

SWI-Prolog streams are, compatible with the ISO standard, either input
or output streams.  To accommodate portability to other systems, a
pair of streams can be packed into a \jargon{stream-pair}.  See
\index{stream_pair/3}\predref{stream_pair}{3} for details.

SWI-Prolog stream handles are unique symbols that have no syntactical
representation. They are written as \verb$<stream>(hex-number)$, which
is not valid input for \index{read/1}\predref{read}{1}.  They are realised using a \jargon{blob}
of type \const{stream} (see \index{blob/2}\predref{blob}{2} and \secref{blob}).


\begin{description}
    \predicate[ISO]{open}{4}{+SrcDest, +Mode, --Stream, +Options}
True when \arg{SrcDest} can be opened in \arg{Mode} and \arg{Stream} is
an I/O stream to/from the object. \arg{SrcDest} is normally the name of
a file, represented as an atom or string. \arg{Mode} is one of
\const{read}, \const{write}, \const{append} or \const{update}. Mode
\const{append} opens the file for writing, positioning the file pointer
at the end. Mode \const{update} opens the file for writing, positioning
the file pointer at the beginning of the file without truncating the
file. \arg{Stream} is either a variable, in which case it is bound to an
integer identifying the stream, or an atom, in which case this atom will
be the stream identifier.%
    \footnote{New code should use the \term{alias}{Alias}
	      option for compatibility with the ISO standard.}

SWI-Prolog also allows \arg{SrcDest} to be a term \term{pipe}{Command}.
In this form, \arg{Command} is started as a child process and if
\arg{Mode} is \const{write}, output written to \arg{Stream} is sent to
the standard input of \arg{Command}. Viso versa, if \arg{Mode} is
\const{read}, data written by \arg{Command} to the standard output may
be read from \arg{Stream}. On Unix systems, \arg{Command} is handed to
popen() which hands it to the Unix shell. On Windows, \arg{Command} is
executed directly. See also \index{process_create/3}\predref{process_create}{3} from \pllib{process}.

If \arg{SrcDest} is an \jargon{IRI}, i.e., starts with
\bnfmeta{scheme}\verb$://$, where \bnfmeta{scheme} is a non-empty sequence of lowercase
ASCII letters \index{open/3}\predref{open}{3},4 calls hooks registered by \index{register_iri_scheme/3}\predref{register_iri_scheme}{3}.
Currently the only predefined IRI scheme is \const{res}, providing
access to the \jargon{resource database}. See
\secref{program-resources}.

The following \arg{Options} are recognised by \index{open/4}\predref{open}{4}:

\begin{description}
    \termitem{alias}{Atom}
Gives the stream a name.   Below is an example.   Be careful with this
option as stream names are global.  See also \index{set_stream/2}\predref{set_stream}{2}.

\begin{code}
?- open(data, read, Fd, [alias(input)]).

        ...,
        read(input, Term),
        ...
\end{code}

\noindent
    \termitem{bom}{Bool}
Check for a BOM (\jargon{Byte Order Marker}) or write
one.  If omitted, the default is \const{true} for mode \const{read} and
\const{false} for mode \const{write}.  See also \index{stream_property/2}\predref{stream_property}{2} and
especially \secref{bom} for a discussion of this feature.

    \termitem{buffer}{Buffering}
Defines output buffering. The atom \const{full} (default) defines full
buffering, \const{line} buffering by line, and \const{false} implies the
stream is fully unbuffered.  Smaller buffering is useful if another
process or the user is waiting for the output as it is being produced.
See also \index{flush_output/[0,1]}\predref{flush_output}{[0,1]}. This option is not an ISO option.

    \termitem{close_on_abort}{Bool}
If \const{true} (default), the stream is closed on an abort (see
\index{abort/0}\predref{abort}{0}). If \const{false}, the stream is not closed. If it is an output
stream, however, it will be flushed.  Useful for logfiles and if the
stream is associated to a process (using the \functor{pipe}{1}
construct).

    \termitem{create}{+List}
Specifies how a new file is created when opening in \const{write},
\const{append} or \const{update} mode. Currently, \arg{List} is a list
of atoms that describe the permissions of the created
file.\footnote{Added after feedback from Joachim Shimpf and Per
Mildner.} Defined values are below. Not recognised values are silently
ignored, allowing for adding platform specific extensions to this set.

    \begin{description}
	\termitem{read}{}
    Allow read access to the file.
	\termitem{write}{}
    Allow write access to the file.
	\termitem{execute}{}
    Allow execution access to the file.
	\termitem{default}{}
    Allow read and write access to the file.
	\termitem{all}{}
    Allow any access provided by the OS.
    \end{description}

Note that if \arg{List} is empty, the created file has no associated
access permissions. The create options map to the POSIX \arg{mode}
option of open(), where \const{read} map to 0444, \const{write} to 0222
and \const{execute} to 0111. On POSIX systems, the final permission is
defined as (mode \& \chr{\Stilde}umask).

    \termitem{encoding}{Encoding}
Define the encoding used for reading and writing text to this stream.
The default encoding for type \const{text} is derived from the Prolog
flag \prologflag{encoding}. For \const{binary} streams the default encoding
is \const{octet}. For details on encoding issues, see \secref{encoding}.

    \termitem{eof_action}{Action}
Defines what happens if the end of the input stream is reached. The
default value for Action is \const{eof_code}, which makes \index{get0/1}\predref{get0}{1} and
friends return -1, and \index{read/1}\predref{read}{1} and friends return the atom
\const{end_of_file}.  Repetitive reading keeps yielding the same
result.  Action \const{error} is like \const{eof_code}, but repetitive
reading will raise an error.  With action \const{reset}, Prolog will
examine the file again and return more data if the file has grown.

    \termitem{locale}{+Locale}
Set the locale that is used by notably \index{format/2}\predref{format}{2} for output on this
stream.  See \secref{locale}.

    \termitem{lock}{LockingMode}
Try to obtain a lock on the open file.  Default is \const{none}, which
does not lock the file.  The value \const{read} or \const{shared} means
other processes may read the file, but not write it.  The value
\const{write} or \const{exclusive} means no other process may read
or write the file.

Locks are acquired through the POSIX function fcntl() using the command
\const{F_SETLKW}, which makes a blocked call wait for the lock to be
released. Please note that fcntl() locks are {\em advisory} and
therefore only other applications using the same advisory locks
honour your lock. As there are many issues around locking in Unix,
especially related to NFS (network file system), please study the
fcntl() manual page before trusting your locks!

The \const{lock} option is a SWI-Prolog extension.

    \termitem{type}{Type}
Using type \const{text} (default), Prolog will write a text file in
an operating system compatible way. Using type \const{binary} the
bytes will be read or written without any translation.  See also
the option \const{encoding}.

    \termitem{wait}{Bool}
This option can be combined with the \const{lock} option. If
\const{false} (default \const{true}), the open call returns immediately
with an exception if the file is locked.  The exception has the format
\term{permission_error}{lock, source_sink, SrcDest}.
\end{description}

The option \const{reposition} is not supported in SWI-Prolog.  All streams
connected to a file may be repositioned.

    \predicate[ISO]{open}{3}{+SrcDest, +Mode, --Stream}
Equivalent to \index{open/4}\predref{open}{4} with an empty option list.

    \predicate{open_null_stream}{1}{--Stream}
Open an output stream that produces no output. All counting functions
are enabled on such a stream. It can be used to discard output (like
Unix \file{/dev/null}) or exploit the counting properties. The initial
encoding of \arg{Stream} is \const{utf8}, enabling arbitrary Unicode
output. The encoding can be changed to determine byte counts of the
output in a particular encoding or validate if output is possible in a
particular encoding. For example, the code below determines the number
of characters emitted when writing \arg{Term}.

\begin{code}
write_length(Term, Len) :-
        open_null_stream(Out),
        write(Out, Term),
        character_count(Out, Len0),
        close(Out),
        Len = Len0.
\end{code}

\noindent
    \predicate[ISO]{close}{1}{+Stream}
Close the specified stream. If \arg{Stream} is not open, an existence
error is raised.  See \index{stream_pair/3}\predref{stream_pair}{3} for the implications of closing a
\jargon{stream pair}.

If the closed stream is the current input, output or error stream, the
stream alias is bound to the initial standard I/O streams of the
process. Calling \index{close/1}\predref{close}{1} on the initial standard I/O streams of the
process is a no-op for an input stream and flushes an output stream
without closing it.\footnote{This behaviour was defined with purely
interactive usage of Prolog in mind. Applications should not count on
this behaviour. Future versions may allow for closing the initial
standard I/O streams.}

    \predicate[ISO]{close}{2}{+Stream, +Options}
Provides \term{close}{Stream, [force(true)]} as the only option.  Called
this way, any resource errors (such as write errors while flushing the
output buffer) are ignored.

    \predicate[ISO]{stream_property}{2}{?Stream, ?StreamProperty}
True when \arg{StreamProperty} is a property of \arg{Stream}. If
enumeration of streams or properties is demanded because either
\arg{Stream} or \arg{StreamProperty} are unbound, the implementation
enumerates all candidate streams and properties while locking the stream
database.  Properties are fetched without locking the stream and may
be outdated before this predicate returns due to asynchronous activity.

\begin{description}
    \termitem{alias}{Atom}
If \arg{Atom} is bound, test if the stream has the specified alias.
Otherwise unify \arg{Atom} with the first alias of the stream.%
	\bug{Backtracking does not give other aliases.}

    \termitem{buffer}{Buffering}
SWI-Prolog extension to query the buffering mode of this stream.
\arg{Buffering} is one of \const{full}, \const{line} or \const{false}.
See also \index{open/4}\predref{open}{4}.

    \termitem{buffer_size}{Integer}
SWI-Prolog extension to query the size of the I/O buffer associated
to a stream in bytes.  Fails if the stream is not buffered.

    \termitem{bom}{Bool}
If present and \const{true}, a BOM (\jargon{Byte Order Mark}) was
detected while opening the file for reading, or a BOM was written while
opening the stream. See \secref{bom} for details.

    \termitem{close_on_abort}{Bool}
Determine whether or not \index{abort/0}\predref{abort}{0} closes the stream.  By default
streams are closed.

    \termitem{close_on_exec}{Bool}
Determine whether or not the stream is closed when executing a new
process (exec() in Unix, CreateProcess() in Windows). Default is to
close streams. This maps to fcntl() \const{F_SETFD} using the flag
\const{FD_CLOEXEC} on Unix and (negated) \const{HANDLE_FLAG_INHERIT} on
Windows.

    \termitem{encoding}{Encoding}
Query the encoding used for text.  See \secref{encoding} for an
overview of wide character and encoding issues in SWI-Prolog.

    \termitem{end_of_stream}{E}
If \arg{Stream} is an input stream, unify \arg{E} with one of the
atoms \const{not}, \const{at} or \const{past}. See also
\index{at_end_of_stream/[0,1]}\predref{at_end_of_stream}{[0,1]}.

    \termitem{eof_action}{A}
Unify \arg{A} with one of \const{eof_code}, \const{reset} or
\const{error}.  See \index{open/4}\predref{open}{4} for details.

    \termitem{file_name}{Atom}
If \arg{Stream} is associated to a file, unify \arg{Atom} to the
name of this file.

    \termitem{file_no}{Integer}
If the stream is associated with a POSIX file descriptor, unify
\arg{Integer} with the descriptor number.  SWI-Prolog extension used
primarily for integration with foreign code.  See also Sfileno() from
\file{SWI-Stream.h}.

    \termitem{input}{}
True if \arg{Stream} has mode \const{read}.

    \termitem{locale}{Locale}
True when \arg{Locale} is the current locale associated with the
stream. See \secref{locale}.

    \termitem{mode}{IOMode}
Unify \arg{IOMode} to the mode given to \index{open/4}\predref{open}{4} for opening the stream.
Values are: \const{read}, \const{write}, \const{append} and the
SWI-Prolog extension \const{update}.

    \termitem{newline}{NewlineMode}
One of \const{posix} or \const{dos}.  If \const{dos}, text streams
will emit \verb$\r\n$ for \verb$\n$ and discard \verb$\r$ from input
streams.  Default depends on the operating system.

    \termitem{nlink}{-Count}
Number of hard links to the file.  This expresses the number of `names'
the file has. Not supported on all operating systems and the value might
be bogus.  See the documentation of fstat() for your OS and the value
\texttt{st_nlink}.

    \termitem{output}{}
True if \arg{Stream} has mode \const{write}, \const{append} or
\const{update}.

    \termitem{position}{Pos}
Unify \arg{Pos} with the current stream position. A stream position is
an opaque term whose fields can be extracted using
\index{stream_position_data/3}\predref{stream_position_data}{3}. See also \index{set_stream_position/2}\predref{set_stream_position}{2}.

    \termitem{reposition}{Bool}
Unify \arg{Bool} with \arg{true} if the position of the stream can
be set (see \index{seek/4}\predref{seek}{4}).  It is assumed the position can be set if the
stream has a \jargon{seek-function} and is not based on a POSIX
file descriptor that is not associated to a regular file.

    \termitem{representation_errors}{Mode}
Determines behaviour of character output if the stream cannot represent
a character. For example, an ISO Latin-1 stream cannot represent
Cyrillic characters.  The behaviour is one of \const{error} (throw
an I/O error exception), \const{prolog} (write \verb$\...\$ escape
code) or \const{xml} (write \verb$&#...;$ XML character entity).
The initial mode is \const{prolog} for the user streams and
\const{error} for all other streams. See also \secref{encoding}
and \index{set_stream/2}\predref{set_stream}{2}.

    \termitem{timeout}{-Time}
\arg{Time} is the timeout currently associated with the stream.  See
\index{set_stream/2}\predref{set_stream}{2} with the same option. If no timeout is specified,
\arg{Time} is unified to the atom \const{infinite}.

    \termitem{type}{Type}
Unify \arg{Type} with \const{text} or \const{binary}.

    \termitem{tty}{Bool}
This property is reported with \arg{Bool} equal to \const{true} if
the stream is associated with a terminal.  See also \index{set_stream/2}\predref{set_stream}{2}.

    \termitem{write_errors}{Atom}
\arg{Atom} is one of \const{error} (default) or \const{ignore}. The
latter is intended to deal with service processes for which the standard
output handles are not connected to valid streams. In these cases write
errors may be ignored on \const{user_error}.
\end{description}

    \predicate{current_stream}{3}{?Object, ?Mode, ?Stream}
The predicate \index{current_stream/3}\predref{current_stream}{3} is used to access the status of a
stream as well as to generate all open streams.  \arg{Object} is the
name of the file opened if the stream refers to an open file, an
integer file descriptor if the stream encapsulates an operating system
stream, or the atom \const{\Snil} if the stream refers to some other object.
\arg{Mode} is one of \const{read} or \const{write}.

    \predicate{is_stream}{1}{+Term}
True if \arg{Term} is a stream name or valid stream handle.  This
predicate realises a safe test for the existence of a stream alias
or handle.

    \predicate{stream_pair}{3}{?StreamPair, ?Read, ?Write}
This predicate can be used in mode (-,+,+) to create a
\jargon{stream-pair} from an input stream and an output stream. Mode
(+,-,-) can be used to get access to the underlying streams. If a stream
has already been closed, the corresponding argument is left unbound. If
mode (+,-,-) is used on a single stream, either \arg{Read} or
\arg{Write} is unified with the stream while the other argument is left
unbound. This behaviour simplifies writing code that must operate both
on streams and stream pairs.

Stream-pairs can be used by all I/O operations on streams, where the
operation selects the appropriate member of the pair. The predicate
\index{close/1}\predref{close}{1} closes the still open streams of the pair.\footnote{As of
version 7.1.19, it is allowed to close one of the members of the
stream directly and close the pair later.} The output stream is
closed before the input stream. If closing the output stream results in
an error, the input stream is still closed. Success is only returned if
both streams were closed successfully.

    \predicate[ISO]{set_stream_position}{2}{+Stream, +Pos}
Set the current position of \arg{Stream} to \arg{Pos}.  \arg{Pos} is
a term as returned by \index{stream_property/2}\predref{stream_property}{2} using the \term{position}{Pos}
property.  See also \index{seek/4}\predref{seek}{4}.

    \predicate{stream_position_data}{3}{?Field, +Pos, -Data}
Extracts information from the opaque stream position term as returned
by \index{stream_property/2}\predref{stream_property}{2} requesting the \term{position}{Pos} property.
\arg{Field} is one of \const{line_count}, \const{line_position},
\const{char_count} or \const{byte_count}.  See also \index{line_count/2}\predref{line_count}{2},
\index{line_position/2}\predref{line_position}{2}, \index{character_count/2}\predref{character_count}{2} and \index{byte_count/2}\predref{byte_count}{2}.%
	\footnote{Introduced in version 5.6.4 after extending the
		  position term with a byte count.  Compatible with
		  SICStus Prolog.}

    \predicate{seek}{4}{+Stream, +Offset, +Method, -NewLocation}
Reposition the current point of the given \arg{Stream}.  \arg{Method}
is one of \const{bof}, \const{current} or \const{eof}, indicating
positioning relative to the start, current point or end of the
underlying object.  \arg{NewLocation} is unified with the new offset,
relative to the start of the stream.

Positions are counted in `units'. A unit is 1 byte, except for
text files using 2-byte Unicode encoding (2 bytes) or \emph{wchar}
encoding (sizeof(wchar_t)). The latter guarantees comfortable
interaction with wide-character text objects. Otherwise, the use of
\index{seek/4}\predref{seek}{4} on non-binary files (see \index{open/4}\predref{open}{4}) is of limited use, especially
when using multi-byte text encodings (e.g.\ UTF-8) or multi-byte newline
files (e.g.\ DOS/Windows). On text files, SWI-Prolog offers reliable
backup to an old position using \index{stream_property/2}\predref{stream_property}{2} and
\index{set_stream_position/2}\predref{set_stream_position}{2}. Skipping $N$ character codes is achieved calling
\index{get_code/2}\predref{get_code}{2} $N$ times or using \index{copy_stream_data/3}\predref{copy_stream_data}{3}, directing the output
to a null stream (see \index{open_null_stream/1}\predref{open_null_stream}{1}). If the seek modifies the
current location, the line number and character position in the line are
set to 0.

If the stream cannot be repositioned, a \const{permission_error} is
raised. If applying the offset would result in a file position less than
zero, a \const{domain_error} is raised. Behaviour when seeking to
positions beyond the size of the underlying object depend on the object
and possibly the operating system. The predicate \index{seek/4}\predref{seek}{4} is compatible with
Quintus Prolog, though the error conditions and signalling is ISO
compliant. See also \index{stream_property/2}\predref{stream_property}{2} and \index{set_stream_position/2}\predref{set_stream_position}{2}.

    \predicate{set_stream}{2}{+Stream, +Attribute}
Modify an attribute of an existing stream. \arg{Attribute} specifies the
stream property to set. If stream is a \emph{pair} (see \index{stream_pair/3}\predref{stream_pair}{3})
both streams are modified, unless the property is only meaningful on
one of the streams or setting both is not meaningful.  In particular,
\const{eof_action} only applies to the \emph{read} stream,
\const{representation_errors} only applies to the \emph{write} stream
and trying to set \const{alias} or \const{line_position} on a pair
results in a \const{permission_error} exception. See also
\index{stream_property/2}\predref{stream_property}{2} and \index{open/4}\predref{open}{4}.

\begin{description}
    \termitem{alias}{AliasName}
Set the alias of an already created stream. If \arg{AliasName} is the
name of one of the standard streams, this stream is rebound.
Thus, \exam{set_stream(S, current_input)} is the same as \index{set_input/1}\predref{set_input}{1}, and
by setting the alias of a stream to \const{user_input}, etc., all user
terminal input is read from this stream. See also \index{interactor/0}\predref{interactor}{0}.

    \termitem{buffer}{Buffering}
Set the buffering mode of an already created stream.  Buffering is one
of \const{full}, \const{line} or \const{false}.

    \termitem{buffer_size}{+Size}
Set the size of the I/O buffer of the underlying stream to \arg{Size}
bytes.

    \termitem{close_on_abort}{Bool}
Determine whether or not the stream is closed by \index{abort/0}\predref{abort}{0}.  By default,
streams are closed.

    \termitem{close_on_exec}{Bool}
Set the \const{close_on_exec} property.  See \index{stream_property/2}\predref{stream_property}{2}.

    \termitem{encoding}{Atom}
Defines the mapping between bytes and character codes used for the
stream.  See \secref{encoding} for supported encodings.  The value
\const{bom} causes the stream to check whether the current character
is a Unicode BOM marker.  If a BOM marker is found, the encoding is
set accordingly and the call succeeds.  Otherwise the call fails.

    \termitem{eof_action}{Action}
Set end-of-file handling to one of \const{eof_code}, \const{reset} or
\const{error}.

    \termitem{file_name}{FileName}
Set the filename associated to this stream.  This call can be used
to set the file for error locations if \arg{Stream} corresponds to
\arg{FileName} and is not obtained by opening the file directly but,
for example, through a network service.

    \termitem{line_position}{LinePos}
Set the line position attribute of the stream.  This feature is
intended to correct position management of the stream after sending
a terminal escape sequence (e.g., setting ANSI character attributes).
Setting this attribute raises a permission error if the stream does
not record positions. See \index{line_position/2}\predref{line_position}{2} and \index{stream_property/2}\predref{stream_property}{2}
(property \const{position}).

    \termitem{locale}{+Locale}
Change the locale of the stream.  See \secref{locale}.

    \termitem{newline}{NewlineMode}
Set input or output translation for newlines. See corresponding
\index{stream_property/2}\predref{stream_property}{2} for details.  In addition to the detected modes,
an input stream can be set in mode \const{detect}.  It will be set
to \const{dos} if a \verb$\r$ character was removed.

    \termitem{timeout}{Seconds}
This option can be used to make streams generate an exception if it
takes longer than \arg{Seconds} before any new data arrives at the
stream.  The value \arg{infinite} (default) makes the stream block
indefinitely.  Like \index{wait_for_input/3}\predref{wait_for_input}{3}, this call only applies to
streams that support the select() system call. For further information
about timeout handling, see \index{wait_for_input/3}\predref{wait_for_input}{3}. The exception is of the
form

\begin{quote}
    \term{error}{\term{timeout_error}{read, Stream}, _}
\end{quote}

    \termitem{type}{Type}
Set the type of the stream to one of \const{text} or \const{binary}.
See also \index{open/4}\predref{open}{4} and the \const{encoding} property of streams. Switching
to \const{binary} sets the encoding to \const{octet}.  Switching to
\const{text} sets the encoding to the default text encoding.

    \termitem{record_position}{Bool}
Do/do not record the line count and line position (see \index{line_count/2}\predref{line_count}{2}
and \index{line_position/2}\predref{line_position}{2}). Calling \exam{set_stream(S,
record_position(true))} resets the position the start of line~1.

    \termitem{representation_errors}{Mode}
Change the behaviour when writing characters to the stream that cannot
be represented by the encoding.  See also \index{stream_property/2}\predref{stream_property}{2} and
\secref{encoding}.

    \termitem{tty}{Bool}
Modify whether Prolog thinks there is a terminal (i.e.\ human
interaction) connected to this stream.  On Unix systems the initial
value comes from isatty().  On Windows, the initial user streams are
supposed to be associated to a terminal.  See also \index{stream_property/2}\predref{stream_property}{2}.
\end{description}

    \predicate{set_prolog_IO}{3}{+In, +Out, +Error}
Prepare the given streams for interactive behaviour normally associated
to the terminal. \arg{In} becomes the \const{user_input} and
\const{current_input} of the calling thread. \arg{Out} becomes
\const{user_output} and \const{current_output}. If \arg{Error} equals
\arg{Out} an unbuffered stream is associated to the same destination and
linked to \const{user_error}. Otherwise \arg{Error} is used for
\const{user_error}. Output buffering for \arg{Out} is set to
\const{line} and buffering on \arg{Error} is disabled.
See also \index{prolog/0}\predref{prolog}{0} and \index{set_stream/2}\predref{set_stream}{2}.  The \emph{clib} package
provides the library \pllib{prolog_server}, creating a TCP/IP
server for creating an interactive session to Prolog.
\end{description}

\subsection{Edinburgh-style I/O}	\label{sec:edinburghIO}

The package for implicit input and output destinations is (almost)
compatible with Edinburgh DEC-10 and C-Prolog. The reading and writing
predicates refer to, resp., the \emph{current} input and output streams.
Initially these streams are connected to the terminal. The current
output stream is changed using \index{tell/1}\predref{tell}{1} or \index{append/1}\predref{append}{1}. The current input
stream is changed using \index{see/1}\predref{see}{1}. The stream's current value can be obtained
using \index{telling/1}\predref{telling}{1} for output and \index{seeing/1}\predref{seeing}{1} for input.

Source and destination are either a file, \const{user}, or a term
`pipe(\arg{Command})'. The reserved stream name \const{user} refers
to the terminal.%
	\footnote{The ISO I/O layer uses \const{user_input},
		  \const{user_output} and \const{user_error}.}
In the predicate descriptions below we will call the source/destination
argument `\arg{SrcDest}'. Below are some examples of source/destination
specifications.

\begin{center}\begin{tabular}{ll}
\exam{?- see(data).}        & \% Start reading from file `data'. \\
\exam{?- tell(user).}       & \% Start writing to the terminal. \\
\exam{?- tell(pipe(lpr)).}  & \% Start writing to the printer.
\end{tabular}\end{center}

Another example of using the \functor{pipe}{1} construct is shown
below.%
	\footnote{As of version 5.3.15, the pipe construct is supported
		  in the MS-Windows version, both for
		  \program{swipl.exe} and \program{swipl-win.exe}. The
		  implementation uses code from the LUA programming
		  language (\url{http://www.lua.org}).}
Note that the \functor{pipe}{1} construct is not part of
Prolog's standard I/O repertoire.

\begin{code}
getwd(Wd) :-
        seeing(Old), see(pipe(pwd)),
        collect_wd(String),
        seen, see(Old),
        atom_codes(Wd, String).

collect_wd([C|R]) :-
        get0(C), C \== -1, !,
        collect_wd(R).
collect_wd([]).
\end{code}

\noindent
The effect of \index{tell/1}\predref{tell}{1} is not undone on backtracking, and since the
stream handle is not specified explicitly in further I/O operations
when using Edinburgh-style I/O, you may write to unintended streams
more easily than when using ISO compliant I/O. For example, the
following query writes both "a" and "b" into the file `out' :

\begin{code}
?- (tell(out), write(a), false ; write(b)), told.
\end{code}

\noindent
\subsubsection*{Compatibility notes}

Unlike Edinburgh Prolog systems, \index{telling/1}\predref{telling}{1} and \index{seeing/1}\predref{seeing}{1} do not return
the filename of the current input/output but rather the stream identifier, to
ensure the design pattern below	works under all circumstances:%
	\footnote{Filenames can be ambiguous and SWI-Prolog streams can
		  refer to much more than just files.}

\begin{code}
        ...,
        telling(Old), tell(x),
        ...,
        told, tell(Old),
        ...,
\end{code}

\noindent
The predicates \index{tell/1}\predref{tell}{1} and \index{see/1}\predref{see}{1} first check for \const{user}, the
\term{pipe}{command} and a stream handle.  Otherwise, if the argument
is an atom it is first compared to open streams associated to a file
with \emph{exactly} the same name.  If such a stream exists, created using
\index{tell/1}\predref{tell}{1} or \index{see/1}\predref{see}{1}, output (input) is switched to the open stream.
Otherwise a file with the specified name is opened.

The behaviour is compatible with Edinburgh Prolog.  This is not without
problems. Changing directory, non-file streams, and multiple names referring
to the same file easily lead to unexpected behaviour. New code,
especially when managing multiple I/O channels, should consider using
the ISO I/O predicates defined in \secref{isoIO}.

\begin{description}
    \predicate{see}{1}{+SrcDest}
Open \arg{SrcDest} for reading and make it the current input (see
\index{set_input/1}\predref{set_input}{1}). If \arg{SrcDest} is a stream handle, just make this
stream the current input. See the introduction of \secref{edinburghIO}
for details.

    \predicate{tell}{1}{+SrcDest}
Open \arg{SrcDest} for writing and make it the current output (see
\index{set_output/1}\predref{set_output}{1}).  If \arg{SrcDest} is a stream handle, just make this
stream the current output. See the introduction of \secref{edinburghIO}
for details.

    \predicate{append}{1}{+File}
Similar to \index{tell/1}\predref{tell}{1}, but positions the file pointer at the end of \arg{File}
rather than truncating an existing file. The pipe construct is not
accepted by this predicate.

    \predicate{seeing}{1}{?SrcDest}
Same as \index{current_input/1}\predref{current_input}{1}, except that \const{user} is returned if the
current input is the stream \const{user_input} to improve compatibility
with traditional Edinburgh I/O. See the introduction of
\secref{edinburghIO} for details.

    \predicate{telling}{1}{?SrcDest}
Same as \index{current_output/1}\predref{current_output}{1}, except that \const{user} is returned if the
current output is the stream \const{user_output} to improve compatibility
with traditional Edinburgh I/O. See the introduction of
\secref{edinburghIO} for details.

    \predicate{seen}{0}{}
Close the current input stream. The new input stream becomes
\const{user_input}.

    \predicate{told}{0}{}
Close the current output stream. The new output stream becomes
\const{user_output}.
\end{description}


\subsection{Switching between Edinburgh and ISO I/O}
\label{sec:edinburgh-iso-io}

The predicates below can be used for switching between the implicit
and the explicit stream-based I/O predicates.

\begin{description}
    \predicate[ISO]{set_input}{1}{+Stream}
Set the current input stream to become \arg{Stream}.  Thus, \exam{open(file,
read, Stream), set_input(Stream)} is equivalent to \exam{see(file)}.
    \predicate[ISO]{set_output}{1}{+Stream}
Set the current output stream to become \arg{Stream}.  See also
\index{with_output_to/2}\predref{with_output_to}{2}.
    \predicate[ISO]{current_input}{1}{-Stream}
Get the current input stream.  Useful for getting access to the status
predicates associated with streams.
    \predicate[ISO]{current_output}{1}{-Stream}
Get the current output stream.
\end{description}

\subsection{Adding IRI schemas}
\label{sec:iri-schema}

The file handling predicates may be \jargon{hooked} to deal with
\jargon{IRIs}. An IRI starts with \bnfmeta{scheme}\verb$://$, where \bnfmeta{scheme} is
a non-empty sequence of lowercase ASCII letters. After detecting the
scheme the file manipulation predicates call a hook that is registered
using \index{register_iri_scheme/3}\predref{register_iri_scheme}{3}.

Hooking the file operations using extensible IRI schemas allows us to
place any resource that is accessed through Prolog I/O predicates on
arbitrary devices such as web servers or the ZIP archive used to store
program resources (see \secref{saved-states}). This is typically
combined with \index{file_search_path/2}\predref{file_search_path}{2} declarations to switch between
accessing a set of resources from local files, from the program
resource database, from a web-server, etc.


\begin{description}
    \predicate{register_iri_scheme}{3}{+Scheme, :Hook, +Options}
Register \arg{Hook} to be called by all file handling predicates
if a name that starts with \arg{Scheme}:// is encountered.  The
\arg{Hook} is called by \index{call/4}\predref{call}{4} using the \jargon{operation}, the
\arg{IRI} and a term that receives the \textit{result} of the
operation.  The following operations are defined:

\begin{description}
    \termitem{open}{Mode,Options}
Called by \index{open/3}\predref{open}{3},4.  The result argument must be unified with
a stream.

    \termitem{access}{Mode}
Called by \index{access_file/2}\predref{access_file}{2}, \index{exists_file/1}\predref{exists_file}{1} (\arg{Mode} is \const{file}) and
\index{exists_directory/1}\predref{exists_directory}{1} (\arg{Mode} is \const{directory}). The result
argument must be unified with a boolean.

    \termitem{time}{}
Called by \index{time_file/2}\predref{time_file}{2}.  The result must be unified with a time stamp.

    \termitem{size}{}
Called by \index{size_file/2}\predref{size_file}{2}.  The result must be unified with an integer
representing the size in bytes.
\end{description}
\end{description}


\subsection{Write onto atoms, code-lists, etc.}
\label{sec:write-on-atom}

\begin{description}
    \predicate{with_output_to}{2}{+Output, :Goal}
Run \arg{Goal} as \index{once/1}\predref{once}{1}, while characters written to the current output
are sent to \arg{Output}. The predicate is SWI-Prolog-specific, inspired
by various posts to the mailinglist. It provides a flexible replacement
for predicates such as \nopredref{sformat}{3}, \index{swritef/3}\predref{swritef}{3},
\index{term_to_atom/2}\predref{term_to_atom}{2}, \index{atom_number/2}\predref{atom_number}{2} converting numbers to atoms, etc. The
predicate \index{format/3}\predref{format}{3} accepts the same terms as output argument.

Applications should generally avoid creating atoms by breaking and
concatenating other atoms, as the creation of large numbers of
intermediate atoms generally leads to poor performance, even more so in
multithreaded applications.  This predicate supports creating
difference lists from character data efficiently.  The example below
defines the DCG rule term//1 to insert a term in the output:

\begin{code}
term(Term, In, Tail) :-
        with_output_to(codes(In, Tail), write(Term)).

?- phrase(term(hello), X).

X = [104, 101, 108, 108, 111]
\end{code}

\noindent
\begin{description}
    \definition{A Stream handle or alias}
Temporarily switch current output to the given stream.  Redirection using
\index{with_output_to/2}\predref{with_output_to}{2} guarantees the original output is restored, also if
\arg{Goal} fails or raises an exception.  See also \index{call_cleanup/2}\predref{call_cleanup}{2}.

    \termitem{atom}{-Atom}
Create an atom from the emitted characters. Please note the remark
above.

    \termitem{string}{-String}
Create a string object as defined in \secref{strings}.

    \termitem{codes}{-Codes}
Create a list of character codes from the emitted characters, similar to
\index{atom_codes/2}\predref{atom_codes}{2}.

    \termitem{codes}{-Codes, -Tail}
Create a list of character codes as a difference list.

    \termitem{chars}{-Chars}
Create a list of one-character atoms from the emitted characters,
similar to \index{atom_chars/2}\predref{atom_chars}{2}.

    \termitem{chars}{-Chars, -Tail}
Create a list of one-character atoms as a difference list.
\end{description}
\end{description}


\subsection{Fast binary term I/O}
\label{sec:fast-term-io}

The predicates in this section provide fast binary I/O of arbitrary
Prolog terms, including cyclic terms and terms holding attributed
variables. Library \pllib{fastrw} is a SICSTus/Ciao compatible library
that extends the core primitives described below.

The binary representation the same as used by \cfuncref{PL_record_external}{}. The
use of these primitives instead of using \index{write_canonical/2}\predref{write_canonical}{2} has
advantages and disadvantages. Below are the main considerations:

\begin{itemize}
    \item Using \index{write_canonical/2}\predref{write_canonical}{2} allows or exchange of terms with
    other Prolog systems.  The format is stable and, as it is text
    based, it can be inspected and corrected.
    \item Using the binary format improves the performance roughly
    3 times.
    \item The size of both representations is comparable.
    \item The binary format can deal with cycles, sharing and
    attributes.  Special precautions are needed to transfer
    such terms using \index{write_canonical/2}\predref{write_canonical}{2}.  See \index{term_factorized/3}\predref{term_factorized}{3}
    and \index{copy_term/3}\predref{copy_term}{3}.
    \item In the current version, reading the binary format has
    only incomplete consistency checks.  This implies a user must
    be able to \textbf{trust the source} as crafted messages may
    compromise the reading Prolog system.
\end{itemize}

\begin{description}
    \predicate{fast_term_serialized}{2}{?Term, ?String}
(De-)serialize \arg{Term} to/from \arg{String}.

    \predicate{fast_write}{2}{+Output, +Term}
Write \arg{Term} using the fast serialization format to the
\arg{Output} stream.  \arg{Output} \emph{must} be a binary
stream.

    \predicate{fast_read}{2}{+Input, -Term}
Read \arg{Term} using the fast serialization format from the
\arg{Input} stream.  \arg{Input} \emph{must} be a binary
stream.\bug{The predicate \index{fast_read/2}\predref{fast_read}{2} may crash on arbitrary
input.}
\end{description}


\section{Status of streams}		\label{sec:streamstat}

\begin{description}
    \predicate[det]{wait_for_input}{3}{+ListOfStreams, -ReadyList, +TimeOut}
Wait for input on one of the streams in \arg{ListOfStreams} and return a
list of streams on which input is available in \arg{ReadyList}. Each
element of \arg{ListOfStreams} is either a stream or an integer.
Integers are consider waitable OS handles. This can be used to wait
(also) wait for handles that are not associated with Prolog streams such
as UDP sockets. See \index{tcp_sockopt/2}\predref{tcp_sockopt}{2}.

This predicate waits for at most \arg{TimeOut} seconds. \arg{TimeOut}
may be specified as a floating point number to specify fractions of a
second. If \arg{TimeOut} equals \const{infinite}, \index{wait_for_input/3}\predref{wait_for_input}{3} waits
indefinitely. If \arg{Timeout} is 0 or 0.0 this predicate returns
without waiting.\footnote{Prior to 7.3.23, the integer value `0' was the
same as \const{infinite}.}

This predicate can be used to implement timeout while reading and to
handle input from multiple sources and is typically used to wait for
multiple (network) sockets. On Unix systems it may be used on any stream
that is associated with a system file descriptor. On Windows it can only
be used on sockets. If \arg{ListOfStreams} contains a stream that is not
associated with a supported device, a \term{domain_error}{waitable_stream,
Stream} is raised.

The example below waits for input from the user and an explicitly opened
secondary terminal stream. On return, \arg{Inputs} may hold
\const{user_input} or \arg{P4} or both.

\begin{code}
?- open('/dev/ttyp4', read, P4),
   wait_for_input([user_input, P4], Inputs, 0).
\end{code}

\noindent
\index{select()}\index{poll()}%
When available, the implementation is based on the poll() system call.
The poll() puts no additional restriction on the number of open files
the process may have. It does limit the time to $2^{31}-1$ milliseconds
(a bit less than 25 days). Specifying a too large timeout raises a
\term{representation_error}{timeout} exception. If poll() is not
supported by the OS, select() is used. The select() call can only handle
file descriptors up to \const{FD_SETSIZE}. If the set contains a
descriptor that exceeds this limit a
\term{representation_error}{'FD_SETSIZE'} is raised.

Note that \index{wait_for_input/3}\predref{wait_for_input}{3} returns streams that have data waiting. This
does not mean you can, for example, call \index{read/2}\predref{read}{2} on the stream without
blocking as the stream might hold an incomplete term. The predicate
\index{set_stream/2}\predref{set_stream}{2} using the option \term{timeout}{Seconds} can be used to
make the stream generate an exception if no new data arrives within
the timeout period.  Suppose two processes communicate by exchanging Prolog
terms.  The following code makes the server immune for clients that
write an incomplete term:

\begin{code}
    ...,
    tcp_accept(Server, Socket, _Peer),
    tcp_open(Socket, In, Out),
    set_stream(In, timeout(10)),
    catch(read(In, Term), _, (close(Out), close(In), fail)),
    ...,
\end{code}

\noindent
    \predicate{byte_count}{2}{+Stream, -Count}
Byte position in \arg{Stream}.  For binary streams this is the same
as \index{character_count/2}\predref{character_count}{2}.  For text files the number may be different due
to multi-byte encodings or additional record separators (such as
Control-M in Windows).

    \predicate{character_count}{2}{+Stream, -Count}
Unify \arg{Count} with the current character index.  For input streams
this is the number of characters read since the open; for output
streams this is the number of characters written. Counting starts at 0.

    \predicate{line_count}{2}{+Stream, -Count}
Unify \arg{Count} with the number of lines read or written.  Counting
starts at 1.

    \predicate{line_position}{2}{+Stream, -Count}
Unify \arg{Count} with the position on the current line. Note that this
assumes the position is 0 after the open.  Tabs are assumed to be
defined on each 8-th character, and backspaces are assumed to reduce the
count by one, provided it is positive.
\end{description}


\section{Primitive character I/O}		\label{sec:chario}

See \secref{chars} for an overview of supported character
representations.

\begin{description}
    \predicate[ISO]{nl}{0}{}
Write a newline character to the current output stream.  On Unix systems
\index{nl/0}\predref{nl}{0} is equivalent to \exam{put(10)}.

    \predicate[ISO]{nl}{1}{+Stream}
Write a newline to \arg{Stream}.

    \predicate{put}{1}{+Char}
Write \arg{Char} to the current output stream. \arg{Char} is either an
integer expression evaluating to a character code or an atom of one
character.  Deprecated.  New code should use \index{put_char/1}\predref{put_char}{1} or \index{put_code/1}\predref{put_code}{1}.

    \predicate{put}{2}{+Stream, +Char}
Write \arg{Char} to \arg{Stream}.  See \index{put/1}\predref{put}{1} for details.

    \predicate[ISO]{put_byte}{1}{+Byte}
Write a single byte to the output.  \arg{Byte} must be an integer
between 0 and 255.

    \predicate[ISO]{put_byte}{2}{+Stream, +Byte}
Write a single byte to \arg{Stream}. \arg{Byte} must be an integer
between 0 and 255.

    \predicate[ISO]{put_char}{1}{+Char}
Write a character to the current output, obeying the encoding defined
for the current output stream. Note that this may raise an exception if
the encoding of the output stream cannot represent \arg{Char}.

    \predicate[ISO]{put_char}{2}{+Stream, +Char}
Write a character to \arg{Stream}, obeying the encoding defined for
\arg{Stream}. Note that this may raise an exception if the
encoding of \arg{Stream} cannot represent \arg{Char}.

    \predicate[ISO]{put_code}{1}{+Code}
Similar to \index{put_char/1}\predref{put_char}{1}, but using a \jargon{character code}.  \arg{Code}
is a non-negative integer.  Note that this may raise an exception if the
encoding of the output stream cannot represent \arg{Code}.

    \predicate[ISO]{put_code}{2}{+Stream, +Code}
Same as \index{put_code/1}\predref{put_code}{1} but directing \arg{Code} to \arg{Stream}.

    \predicate{tab}{1}{+Amount}
Write \arg{Amount} spaces on the current output stream.  \arg{Amount}
should be an expression that evaluates to a positive integer (see
\secref{arith}).

    \predicate{tab}{2}{+Stream, +Amount}
Write \arg{Amount} spaces to \arg{Stream}.

    \predicate[ISO]{flush_output}{0}{}
Flush pending output on current output stream. \index{flush_output/0}\predref{flush_output}{0} is
automatically generated by \index{read/1}\predref{read}{1} and derivatives if the current input
stream is \const{user} and the cursor is not at the left margin.

    \predicate[ISO]{flush_output}{1}{+Stream}
Flush output on the specified stream.  The stream must be open for
writing.

    \predicate{ttyflush}{0}{}
Flush pending output on stream \const{user}. See also \index{flush_output/[0,1]}\predref{flush_output}{[0,1]}.
    \predicate[ISO]{get_byte}{1}{-Byte}
Read the current input stream and unify the next byte with \arg{Byte}
(an integer between 0 and 255). \arg{Byte} is unified with -1 on end of
file.

    \predicate[ISO]{get_byte}{2}{+Stream, -Byte}
Read the next byte from \arg{Stream} and unify \arg{Byte} with an integer between
0 and 255.

    \predicate[ISO]{get_code}{1}{-Code}
Read the current input stream and unify \arg{Code} with the character
code of the next character. \arg{Code} is unified with -1 on end of
file.  See also \index{get_char/1}\predref{get_char}{1}.

    \predicate[ISO]{get_code}{2}{+Stream, -Code}
Read the next character code from \arg{Stream}.

    \predicate[ISO]{get_char}{1}{-Char}
Read the current input stream and unify \arg{Char} with the next
character as a one-character atom.  See also \index{atom_chars/2}\predref{atom_chars}{2}.
On end-of-file, \arg{Char} is unified to the atom \const{end_of_file}.

    \predicate[ISO]{get_char}{2}{+Stream, -Char}
Unify \arg{Char} with the next character from \arg{Stream} as a
one-character atom.  See also \index{get_char/2}\predref{get_char}{2}, \index{get_byte/2}\predref{get_byte}{2} and \index{get_code/2}\predref{get_code}{2}.

    \predicate[deprecated]{get0}{1}{-Char}
Edinburgh version of the ISO \index{get_code/1}\predref{get_code}{1} predicate. Note that Edinburgh
Prolog didn't support wide characters and therefore technically speaking
\index{get0/1}\predref{get0}{1} should have been mapped to \index{get_byte/1}\predref{get_byte}{1}.  The intention of \index{get0/1}\predref{get0}{1},
however, is to read character codes.

    \predicate[deprecated]{get0}{2}{+Stream, -Char}
Edinburgh version of the ISO \index{get_code/2}\predref{get_code}{2} predicate.  See also \index{get0/1}\predref{get0}{1}.

    \predicate[deprecated]{get}{1}{-Char}
Read the current input stream and unify the next non-blank character
with \arg{Char}. \arg{Char} is unified with -1 on end of file.  The
predicate \index{get/1}\predref{get}{1} operates on character \emph{codes}.  See also \index{get0/1}\predref{get0}{1}.

    \predicate[deprecated]{get}{2}{+Stream, -Char}
Read the next non-blank character from \arg{Stream}.  See also
\index{get/1}\predref{get}{1}, \index{get0/1}\predref{get0}{1} and \index{get0/2}\predref{get0}{2}.

    \predicate[ISO]{peek_byte}{1}{-Byte}
    \nodescription
    \predicate[ISO]{peek_byte}{2}{+Stream, -Byte}
    \nodescription
    \predicate[ISO]{peek_code}{1}{-Code}
    \nodescription
    \predicate[ISO]{peek_code}{2}{+Stream, -Code}
    \nodescription
    \predicate[ISO]{peek_char}{1}{-Char}
    \nodescription
    \predicate[ISO]{peek_char}{2}{+Stream, -Char}
Read the next byte/code/char from the input without removing it.
These predicates do not modify the stream's position or end-of-file
status. These predicates require a buffered stream (see \index{set_stream/2}\predref{set_stream}{2})
and raise a permission error if the stream is unbuffered or the buffer
is too small to hold the longest multi-byte sequence that might need to
be buffered.

    \predicate{peek_string}{3}{+Stream, +Len, -String}
Read the next \arg{Len} characters (if the stream is a text stream) or
bytes (if the stream is binary) from Stream without removing the data.
If \arg{Len} is larger that the stream buffer size, the buffer size is
increased to \arg{Len}.  \arg{String} can be shorter than \arg{Len} if
the stream contains less data. This predicate is intended to guess the
content type of data read from non-repositionable streams.

    \predicate{skip}{1}{+Code}
Read the input until \arg{Code} or the end of the file is encountered.
A subsequent call to \index{get_code/1}\predref{get_code}{1} will read the first character after
\arg{Code}.

    \predicate{skip}{2}{+Stream, +Code}
Skip input (as \index{skip/1}\predref{skip}{1}) on \arg{Stream}.

    \predicate{get_single_char}{1}{-Code}
Get a single character from input stream `user' (regardless of the
current input stream). Unlike \index{get_code/1}\predref{get_code}{1}, this predicate does not
wait for a return. The character is not echoed to the user's terminal.
This predicate is meant for keyboard menu selection, etc. If SWI-Prolog
was started with the \cmdlineoption{--no-tty} option this predicate
reads an entire line of input and returns the first non-blank character
on this line, or the character code of the newline (10) if the entire
line consisted of blank characters.

    \predicate[ISO]{at_end_of_stream}{0}{}
Succeeds after the last character of the current input stream has
been read.  Also succeeds if there is no valid current input stream.

    \predicate[ISO]{at_end_of_stream}{1}{+Stream}
Succeeds after the last character of the named stream is read, or
\arg{Stream} is not a valid input stream.  The end-of-stream test
is only available on buffered input streams (unbuffered input streams
are rarely used; see \index{open/4}\predref{open}{4}).

    \predicate{set_end_of_stream}{1}{+Stream}
Set the size of the file opened as \arg{Stream} to the current
file position.  This is typically used in combination with the
open-mode \const{update}.

    \predicate{copy_stream_data}{3}{+StreamIn, +StreamOut, +Len}
Copy \arg{Len} codes from \arg{StreamIn} to \arg{StreamOut}.
Note that the copy is done using the semantics of \index{get_code/2}\predref{get_code}{2} and
\index{put_code/2}\predref{put_code}{2}, taking care of possibly recoding that needs to take place
between two text files.  See \secref{encoding}.

    \predicate{copy_stream_data}{2}{+StreamIn, +StreamOut}
Copy all (remaining) data from \arg{StreamIn} to
\arg{StreamOut}.

    \predicate[det]{fill_buffer}{1}{+Stream}
Fill the \arg{Stream}'s input buffer. Subsequent calls try to read more
input until the buffer is completely filled. This predicate is used
together with \index{read_pending_codes/3}\predref{read_pending_codes}{3} to process input with minimal
buffering.

    \predicate{read_pending_codes}{3}{+StreamIn, -Codes, ?Tail}
Read input pending in the input buffer of \arg{StreamIn} and return
it in the difference list \arg{Codes}-\arg{Tail}. That is, the
available characters codes are used to create the list \arg{Codes}
ending in the tail \arg{Tail}. On encountering end-of-file, both
\arg{Codes} and \arg{Tail} are unified with the empty list ({\Snil}).

This predicate is intended for efficient unbuffered copying and
filtering of input coming from network connections or devices. It also
enables the library \pllib{pure_input}, which processes input from files
and streams using a DCG.

The following code fragment realises efficient non-blocking copying of data
from an input to an output stream. The \index{at_end_of_stream/1}\predref{at_end_of_stream}{1} call checks
for end-of-stream and fills the input buffer.  Note that the use of
a \index{get_code/2}\predref{get_code}{2} and \index{put_code/2}\predref{put_code}{2} based loop requires a \index{flush_output/1}\predref{flush_output}{1} call
after \emph{each} \index{put_code/2}\predref{put_code}{2}.  The \index{copy_stream_data/2}\predref{copy_stream_data}{2} does not allow
for inspection of the copied data and suffers from the same buffering
issues.

\begin{code}
copy(In, Out) :-
        repeat,
            fill_buffer(In),
            read_pending_codes(In, Chars, Tail),
            \+ \+ ( Tail = [],
                    format(Out, '~s', [Chars]),
                    flush_output(Out)
                  ),
            (   Tail == []
            ->  !
            ;   fail
            ).
\end{code}

\noindent
    \predicate{read_pending_chars}{3}{+StreamIn, -Chars, ?Tail}
As \index{read_pending_codes/3}\predref{read_pending_codes}{3}, but returns a difference list of one-character
atoms.
\end{description}

\section{Term reading and writing}		\label{sec:termrw}

This section describes the basic term reading and writing predicates.
The predicates \index{format/[1,2]}\predref{format}{[1,2]} and \index{writef/2}\predref{writef}{2} provide formatted output.
Writing to Prolog data structures such as atoms or code-lists is
supported by \index{with_output_to/2}\predref{with_output_to}{2} and \index{format/3}\predref{format}{3}.

Reading is sensitive to the Prolog flag \prologflag{character_escapes},
which controls the interpretation of the \chr{\Sneg} character in quoted
atoms and strings.

\begin{description}
    \predicate[ISO]{write_term}{2}{+Term, +Options}
The predicate \index{write_term/2}\predref{write_term}{2} is the generic form of all Prolog term-write
predicates.  Valid options are:

\begin{description}
    \termitem{attributes}{Atom}
Define how attributed variables (see \secref{attvar}) are written. The
default is determined by the Prolog flag \prologflag{write_attributes}.
Defined values are \const{ignore} (ignore the attribute), \const{dots}
(write the attributes as \verb${...}$), \const{write} (simply hand
the attributes recursively to \index{write_term/2}\predref{write_term}{2}) and \const{portray}
(hand the attributes to \index{attr_portray_hook/2}\predref{attr_portray_hook}{2}).

    \termitem{back_quotes}{Atom}
Fulfills the same role as the \prologflag{back_quotes} prolog flag.
Notably, the value \const{string} causes string objects to be printed
between back quotes and \const{symbol_char} causes the backquote to
be printed unquoted.  In all other cases the backquote is printed as
a quoted atom.

    \termitem{brace_terms}{Bool}
If \const{true} (default), write \verb${}(X)$ as \verb${X}$.  See also
\const{dotlists} and \const{ignore_ops}.

    \termitem{blobs}{Atom}
Define how non-text blobs are handled.  By default, this is left to
the write handler specified with the blob type.  Using \const{portray},
\index{portray/1}\predref{portray}{1} is called for each blob encountered.  See \secref{blob}.

    \termitem{character_escapes}{Bool}
If \const{true} and \term{quoted}{true} is active, special characters
in quoted atoms and strings are emitted as ISO escape sequences.
Default is taken from the reference module (see below).

    \termitem{cycles}{Bool}
If \const{true} (default), cyclic terms are written as
\term{@}{Template, Substitutions}, where \arg{Substitutions} is a list
\mbox{\arg{Var} = \arg{Value}}. If \const{cycles} is \const{false},
\const{max_depth} is not given, and \arg{Term} is cyclic, \index{write_term/2}\predref{write_term}{2}
raises a \const{domain_error}.\footnote{The cycles option and the cyclic
term representation using the @-term are copied from SICStus Prolog.
However, the default in SICStus is set to \const{false} and SICStus
writes an infinite term if not protected by, e.g., the
\const{depth_limit} option.} See also the \const{cycles} option in
\index{read_term/2}\predref{read_term}{2}.

    \termitem{dotlists}{Bool}
If \const{true} (default \const{false}), write lists using the
dotted term notation rather than the list notation.\footnote{Copied from
ECLiPSe.} Note that as of version~7, the list constructor is
\verb$'[|]'$. Using \term{dotlists}{true}, \index{write_term/2}\predref{write_term}{2} writes a list
using `.' as constructor. This is intended for communication with
programs such as other Prolog systems, that rely on this notation.

    \termitem{fullstop}{Bool}
If \const{true} (default \const{false}), add a fullstop token to the
output.  The dot is preceeded by a space if needed and followed by
a space (default) or newline if the \term{nl}{true} option is also
given.\footnote{Compatible with
\href{http://eclipseclp.org/doc/bips/kernel/ioterm/write_term-3.html}{ECLiPSe}}

    \termitem{ignore_ops}{Bool}
If \const{true}, the generic term representation (\bnfmeta{functor}(\bnfmeta{args}
\ldots)) will be used for all terms.  Otherwise (default), operators
will be used where appropriate.\footnote{In traditional systems this
flag also stops the syntactic sugar notation for lists and brace terms.
In SWI-Prolog, these are controlled by the separate options
\const{dotlists} and \const{brace_terms}}.

    \termitem{max_depth}{Integer}
If the term is nested deeper than \arg{Integer}, print the remainder
as ellipses (\ldots).  A 0 (zero) value (default) imposes no depth limit.
This option also delimits the number of printed items in a list.  Example:

\begin{code}
?- write_term(a(s(s(s(s(0)))), [a,b,c,d,e,f]),
              [max_depth(3)]).
a(s(s(...)), [a, b|...])
true.
\end{code}

\noindent
Used by the top level and debugger to limit screen output.  See also
the Prolog flags \prologflag{answer_write_options} and
\prologflag{debugger_write_options}.

    \termitem{module}{Module}
Define the reference module (default \const{user}).  This defines
the default value for the \prologflag{character_escapes} option as well
as the operator definitions to use.  See also \index{op/3}\predref{op}{3}.

    \termitem{nl}{Bool}
Add a newline to the output.  See also the \const{fullstop} option.

    \termitem{numbervars}{Bool}
If \const{true}, terms of the format \verb|$VAR(N)|, where \arg{N} is a
non-negative integer, will be written as a variable name. If \arg{N} is
an atom it is written without quotes. This extension allows for writing
variables with user-provided names. The default is \const{false}. See
also \index{numbervars/3}\predref{numbervars}{3} and the option \const{variable_names}.

    \termitem{partial}{Bool}
If \const{true} (default \const{false}), do not reset the logic that
inserts extra spaces that separate tokens where needed. This is intended
to solve the problems with the code below.  Calling \term{write_value}{\Sdot}
writes \verb$..$, which cannot be read.  By adding \term{partial}{true}
to the option list, it correctly emits \verb$. .$.  Similar problems appear
when emitting operators using multiple calls to \index{write_term/3}\predref{write_term}{3}.

\begin{code}
write_value(Value) :-
        write_term(Value, [partial(true)]),
        write('.'), nl.
\end{code}

\noindent
    \termitem{portray}{Bool}
Same as \term{portrayed}{Bool}.  Deprecated.

    \termitem{portray_goal}{:Goal}
Implies \term{portray}{true}, but calls \arg{Goal} rather than the
predefined hook \index{portray/1}\predref{portray}{1}.  \arg{Goal} is called through \index{call/3}\predref{call}{3}, where
the first argument is \arg{Goal}, the second is the term to be
printed and the 3rd argument is the current write option list.  The
write option list is copied from the write_term call, but the list
is guaranteed to hold an option \const{priority} that reflects the
current priority.

    \termitem{portrayed}{Bool}
If \const{true}, the hook \index{portray/1}\predref{portray}{1} is called before printing a term
that is not a variable.  If \index{portray/1}\predref{portray}{1} succeeds, the term is considered
printed.  See also \index{print/1}\predref{print}{1}.  The default is \const{false}.  This option
is an extension to the ISO write_term options.

    \termitem{priority}{Integer}
An integer between 0 and 1200 representing the `context priority'.
Default is 1200.  Can be used to write partial terms appearing as
the argument to an operator.  For example:

\begin{code}
        format('~w = ', [VarName]),
        write_term(Value, [quoted(true), priority(699)])
\end{code}

\noindent
    \termitem{quoted}{Bool}
If \const{true}, atoms and functors that need quotes will be quoted.
The default is \const{false}.

    \termitem{spacing}{+Spacing}
Determines whether and where extra white space is added to enhance
readability. The default is \const{standard}, adding only space where
needed for proper tokenization by \index{read_term/3}\predref{read_term}{3}.  Currently, the only
other value is \const{next_argument}, adding a space after a comma
used to separate arguments in a term or list.

    \termitem{variable_names}{+List}
Assign names to variables in \arg{Term}. \arg{List} is a list of terms
\mbox{\arg{Name} = \arg{Var}}, where \arg{Name} is an atom that
represents a valid Prolog variable name. Terms where \arg{Var} is bound
or is a variable that does not appear in \arg{Term} are ignored. Raises
an error if \arg{List} is not a list, one of the members is not a term
\mbox{\arg{Name} = \arg{Var}}, \arg{Name} is not an atom or
\arg{Name} does not represent a valid Prolog variable name.

The implementation binds the variables from \arg{List} to a term
\verb"'$VAR'"(\arg{Name}).  Like \index{write_canonical/1}\predref{write_canonical}{1}, terms that
where already bound to \verb"'$VAR'"(\arg{X}) before \index{write_term/2}\predref{write_term}{2}
are printed normally, unless the option \term{numbervars}{true} is
also provided.  If the option \term{numbervars}{true} is used, the
user is responsible for avoiding collisions between assigned names
and numbered names. See also the \const{variable_names} option of
\index{read_term/2}\predref{read_term}{2}.

Possible variable attributes (see \secref{attvar}) are ignored.  In
most cases one should use \index{copy_term/3}\predref{copy_term}{3} to obtain a copy that is free
of attributed variables and handle the associated constraints as
appropriate for the use-case.
\end{description}

    \predicate[ISO]{write_term}{3}{+Stream, +Term, +Options}
As \index{write_term/2}\predref{write_term}{2}, but output is sent to \arg{Stream} rather than the
current output.

    \predicate[semidet]{write_length}{3}{+Term, -Length, +Options}
True when \arg{Length} is the number of characters emitted for
\arg{write_term}{Term, Options}.  In addition to valid options for
\index{write_term/2}\predref{write_term}{2}, it processes the option:

    \begin{description}
	\termitem{max_length}{+MaxLength}
If provided, fail if \arg{Length} would be larger than \arg{MaxLength}.
The implementation ensures that the runtime is limited when computing
the length of a huge term with a bounded maximum.
    \end{description}

    \predicate[ISO]{write_canonical}{1}{+Term}
Write \arg{Term} on the current output stream using standard
parenthesised prefix notation (i.e., ignoring operator declarations).
Atoms that need quotes are quoted.  Terms written with this predicate
can always be read back, regardless of current operator declarations.
Equivalent to \index{write_term/2}\predref{write_term}{2} using the options \const{ignore_ops},
\const{quoted} and \const{numbervars} after \index{numbervars/4}\predref{numbervars}{4} using the
\const{singletons} option.

Note that due to the use of \index{numbervars/4}\predref{numbervars}{4}, non-ground terms must be
written using a \emph{single} \index{write_canonical/1}\predref{write_canonical}{1} call.  This used to
be the case anyhow, as garbage collection between multiple calls
to one of the write predicates can change the \verb|_G|\bnfmeta{NNN} identity
of the variables.

    \predicate[ISO]{write_canonical}{2}{+Stream, +Term}
Write \arg{Term} in canonical form on \arg{Stream}.

    \predicate[ISO]{write}{1}{+Term}
Write \arg{Term} to the current output, using brackets and operators
where appropriate.

    \predicate[ISO]{write}{2}{+Stream, +Term}
Write \arg{Term} to \arg{Stream}.

    \predicate[ISO]{writeq}{1}{+Term}
Write \arg{Term} to the current output, using brackets and operators where
appropriate. Atoms that need quotes are quoted. Terms written with this
predicate can be read back with \index{read/1}\predref{read}{1} provided the currently active
operator declarations are identical.

    \predicate[ISO]{writeq}{2}{+Stream, +Term}
Write \arg{Term} to \arg{Stream}, inserting quotes.

    \predicate{writeln}{1}{+Term}
Equivalent to \exam{write(Term), nl.}. The output stream is locked,
which implies no output from other threads can appear between the term
and newline.

    \predicate{writeln}{2}{+Stream, +Term}
Equivalent to \exam{write(Stream, Term), nl(Stream).}. The output stream
is locked, which implies no output from other threads can appear between
the term and newline.

    \predicate{print}{1}{+Term}
Print a term for debugging purposes.  The predicate \index{print/1}\predref{print}{1} acts as
if defined as below.

\begin{code}
print(Term) :-
    current_prolog_flag(print_write_options, Options), !,
    write_term(Term, Options).
print(Term) :-
    write_term(Term, [ portray(true),
                       numbervars(true),
                       quoted(true)
                     ]).
\end{code}

\noindent
The \index{print/1}\predref{print}{1} predicate is used primarily through the \verb$~p$ escape
sequence of \index{format/2}\predref{format}{2}, which is commonly used in the recipies used by
\index{print_message/2}\predref{print_message}{2} to emit messages.

The classical definition of this predicate is equivalent to the ISO
predicate \index{write_term/2}\predref{write_term}{2} using the options \term{portray}{true} and
\term{numbervars}{true}. The \term{portray}{true} option allows the
user to implement application-specific printing of terms printed during
debugging to facilitate easy understanding of the output. See also
\index{portray/1}\predref{portray}{1} and \pllib{portray_text}. SWI-Prolog adds \term{quoted}{true}
to (1) facilitate the copying/pasting of terms that are not affected by
\index{portray/1}\predref{portray}{1} and to (2) allow numbers, atoms and strings to be more easily
distinguished, e.g., \verb$42$, \verb$'42'$ and \verb$"42"$.

    \predicate{print}{2}{+Stream, +Term}
Print \arg{Term} to \arg{Stream}.

    \predicate{portray}{1}{+Term}
A dynamic predicate, which can be defined by the user to change the
behaviour of \index{print/1}\predref{print}{1} on (sub)terms.  For each subterm encountered that
is not a variable \index{print/1}\predref{print}{1} first calls \index{portray/1}\predref{portray}{1} using the term as
argument.  For lists, only the list as a whole is given to \index{portray/1}\predref{portray}{1}.  If
\index{portray/1}\predref{portray}{1} succeeds \index{print/1}\predref{print}{1} assumes the term has been written.

    \predicate[ISO]{read}{1}{-Term}
Read the next Prolog term from the current input stream and unify it
with \arg{Term}.  On a syntax error \index{read/1}\predref{read}{1} displays an error message,
attempts to skip the erroneous term and fails.  On reaching end-of-file
\arg{Term} is unified with the atom \const{end_of_file}.

    \predicate[ISO]{read}{2}{+Stream, -Term}
Read \arg{Term} from \arg{Stream}.

    \predicate{read_clause}{3}{+Stream, -Term, +Options}
Equivalent to \index{read_term/3}\predref{read_term}{3}, but sets options according to the current
compilation context and optionally processes comments.  Defined
options:

    \begin{description}
        \termitem{syntax_errors}{+Atom}
	See \index{read_term/3}\predref{read_term}{3}, but the default is \const{dec10} (report
	and restart).

	\termitem{term_position}{-TermPos}
	Same as for \index{read_term/3}\predref{read_term}{3}.

	\termitem{subterm_positions}{-TermPos}
	Same as for \index{read_term/3}\predref{read_term}{3}.

	\termitem{variable_names}{-Bindings}
	Same as for \index{read_term/3}\predref{read_term}{3}.

	\termitem{process_comment}{+Boolean}
	If \const{true} (default), call
	\term{prolog:comment_hook}{Comments, TermPos, Term} if this
	multifile hook is defined (see \index{prolog:comment_hook/3}\qpredref{prolog}{comment_hook}{3}).  This
	is used to drive PlDoc.

	\termitem{comments}{-Comments}
	If provided, unify \arg{Comments} with the comments encountered
	while reading \arg{Term}. This option implies
	\term{process_comment}{false}.
    \end{description}

The \const{singletons} option of \index{read_term/3}\predref{read_term}{3} is initialised from the
active style-checking mode.  The \const{module} option is initialised
to the current compilation module (see \index{prolog_load_context/2}\predref{prolog_load_context}{2}).

    \predicate[ISO]{read_term}{2}{-Term, +Options}
Read a term from the current input stream and unify the term with
\arg{Term}. The reading is controlled by options from the list of
\arg{Options}. If this list is empty, the behaviour is the same as for
\index{read/1}\predref{read}{1}. The options are upward compatible with Quintus Prolog. The
argument order is according to the ISO standard.  Syntax errors are
always reported using exception-handling (see \index{catch/3}\predref{catch}{3}). Options:

\begin{description}
    \termitem{backquoted_string}{Bool}
If \const{true}, read \verb$`$\ldots\verb$`$ to a string object (see
\secref{strings}).  The default depends on the Prolog flag
\prologflag{back_quotes}.

    \termitem{character_escapes}{Bool}
Defines how to read \verb$\$ escape sequences in quoted atoms.
See the Prolog flag \prologflag{character_escapes} in \index{current_prolog_flag/2}\predref{current_prolog_flag}{2}.
(SWI-Prolog).

    \termitem{comments}{-Comments}
Unify \arg{Comments} with a list of \arg{Position}-\arg{Comment}, where
\arg{Position} is a stream position object (see \index{stream_position_data/3}\predref{stream_position_data}{3})
indicating the start of a comment and \arg{Comment} is a string object
containing the text including delimiters of a comment.  It returns all
comments from where the \index{read_term/2}\predref{read_term}{2} call started up to the end of the
term read.

    \termitem{cycles}{Bool}
If \const{true} (default \const{false}), re-instantiate templates as
produced by the corresponding \index{write_term/2}\predref{write_term}{2} option. Note that the default
is \const{false} to avoid misinterpretation of \term{@}{Template,
Substutions}, while the default of \index{write_term/2}\predref{write_term}{2} is \const{true} because
emitting cyclic terms without using the template construct produces an
infinitely large term (read: it will generate an error after producing
a huge amount of output).

    \termitem{dotlists}{Bool}
If \const{true} (default \const{false}), read \verb$.(a,[])$ as a list,
even if lists are internally nor constructed using the dot as functor.
This is primarily intended to read the output from \index{write_canonical/1}\predref{write_canonical}{1}
from other Prolog systems.  See \secref{ext-lists}.

    \termitem{double_quotes}{Atom}
Defines how to read "\ldots" strings. See the Prolog flag
\prologflag{double_quotes}.  (SWI-Prolog).

    \termitem{module}{Module}
Specify \arg{Module} for operators, \prologflag{character_escapes} flag
and \prologflag{double_quotes} flag. The value of the latter two is overruled
if the corresponding \index{read_term/3}\predref{read_term}{3} option is provided.  If no module is
specified, the current `source module' is used.  (SWI-Prolog).

    \termitem{quasi_quotations}{-List}
If present, unify \arg{List} with the quasi quotations (see
\secref{quasiquotations}) instead of evaluating quasi quotations.
Each quasi quotation is a term \term{quasi_quotation}{+Syntax,
+Quotation, +VarDict, -Result}, where \arg{Syntax} is the term in
\verb${|Syntax||..|}$, \arg{Quotation} is a list of character codes that
represent the quotation, \arg{VarDict} is a list of
\arg{Name}=\arg{Variable} and \arg{Result} is a variable that shares
with the place where the quotation must be inserted.  This option is
intended to support tools that manipulate Prolog source text.

    \termitem{singletons}{Vars}
As \const{variable_names}, but only reports the variables occurring only
once in the \arg{Term} read (ISO). If \arg{Vars} is the constant
\const{warning}, singleton variables are reported using \index{print_message/2}\predref{print_message}{2}.
The variables appear in the order they have been read. The latter option
provides backward compatibility and is used to read terms from source
files. Not all singleton variables are reported as a warning.  See
\secref{singleton} for the rules that apply for warning about a
singleton variable.\footnote{As of version 7.7.17, \emph{all} variables
starting with an underscore except for the the truely anonymous variable
are returned in \arg{Vars}. Older versions only reported those that
would have been reported if \const{warning} is used.}

    \termitem{syntax_errors}{Atom}
If \const{error} (default), throw an exception on a syntax error. Other
values are \const{fail}, which causes a message to be printed using
\index{print_message/2}\predref{print_message}{2}, after which the predicate fails, \const{quiet} which
causes the predicate to fail silently, and \const{dec10} which causes
syntax errors to be printed, after which \index{read_term/[2,3]}\predref{read_term}{[2,3]} continues
reading the next term. Using \const{dec10}, \index{read_term/[2,3]}\predref{read_term}{[2,3]} never fails.
(Quintus, SICStus).

    \termitem{subterm_positions}{TermPos}
Describes the detailed layout of the term. The formats for the various
types of terms are given below. All positions are character positions. If
the input is related to a normal stream, these positions are relative to
the start of the input; when reading from the terminal, they are
relative to the start of the term.
    \begin{description}
        \definition{\arg{From}-\arg{To}}
    Used for primitive types (atoms, numbers, variables).

        \termitem{string_position}{\arg{From}, \arg{To}}
    Used to indicate the position of a string enclosed in double
    quotes (\chr{"}).

        \termitem{brace_term_position}{\arg{From}, \arg{To}, \arg{Arg}}
    Term of the form \exam{\{\ldots \}}, as used in DCG rules.  \arg{Arg}
    describes the argument.

        \termitem{list_position}{\arg{From}, \arg{To},
				  \arg{Elms}, \arg{Tail}}
A list. \arg{Elms} describes the positions of the elements. If the list
specifies the tail as \mbox{\chr{\Sbar}\bnfmeta{TailTerm}}, \arg{Tail} is unified
with the term position of the tail, otherwise with the atom \const{none}.

        \termitem{term_position}{\arg{From}, \arg{To},
				 \arg{FFrom}, \arg{FTo}, \arg{SubPos}}
    Used for a compound term not matching one of the above.  \arg{FFrom}
    and \arg{FTo} describe the position of the functor.  \arg{SubPos}
    is a list, each element of which describes the term position of the
    corresponding subterm.

	\termitem{dict_position}{\arg{From}, \arg{To},
				 \arg{TagFrom}, \arg{TagTo},
				 \arg{KeyValuePosList}}
    Used for a dict (see \secref{bidicts}). The position of the
    key-value pairs is described by \arg{KeyValuePosList}, which is a
    list of \functor{key_value_position}{7} terms. The
    \functor{key_value_position}{7} terms appear in the order of the
    input. Because maps to not preserve ordering, the key is provided in
    the position description.

	\termitem{key_value_position}{\arg{From}, \arg{To},
				      \arg{SepFrom}, \arg{SepTo},
				      \arg{Key},
				      \arg{KeyPos}, \arg{ValuePos}}
    Used for key-value pairs in a map (see \secref{bidicts}). It is
    similar to the \functor{term_position}{5} that would be created,
    except that the key and value positions do not need an intermediate
    list and the key is provided in \arg{Key} to enable synchronisation
    of the file position data with the data structure.

	\termitem{parentheses_term_position}{\arg{From}, \arg{To},
					     \arg{ContentPos}}
    Used for terms between parentheses. This is an extension compared to
    the original Quintus specification that was considered necessary for
    secure refactoring of terms.

	\termitem{quasi_quotation_position}{\arg{From}, \arg{To},
					    \arg{SyntaxFrom}, \arg{SyntaxTo},
					    \arg{ContentPos}}
    Used for quasi quotations.
    \end{description}

    \termitem{term_position}{Pos}
Unifies \arg{Pos} with the starting position of the term read.  \arg{Pos}
is of the same format as used by \index{stream_property/2}\predref{stream_property}{2}.

    \termitem{var_prefix}{Bool}
If \const{true}, demand variables to start with an underscore.  See
\secref{varprefix}.

    \termitem{variables}{Vars}
Unify \arg{Vars} with a list of variables in the term. The variables
appear in the order they have been read. See also \index{term_variables/2}\predref{term_variables}{2}.
(ISO).

    \termitem{variable_names}{Vars}
Unify \arg{Vars} with a list of `\arg{Name} = \arg{Var}', where
\arg{Name} is an atom describing the variable name and \arg{Var} is a
variable that shares with the corresponding variable in \arg{Term}.
(ISO). The variables appear in the order they have been read.
\end{description}

    \predicate[ISO]{read_term}{3}{+Stream, -Term, +Options}
Read term with options from \arg{Stream}.  See \index{read_term/2}\predref{read_term}{2}.

    \predicate{read_term_from_atom}{3}{+Atom, -Term, +Options}
Use \index{read_term/3}\predref{read_term}{3} to read the next term from \arg{Atom}.  \arg{Atom} is
either an atom or a string object (see \secref{strings}).  It is not
required for \arg{Atom} to end with a full-stop.  This predicate
supersedes \index{atom_to_term/3}\predref{atom_to_term}{3}.

    \predicate{read_history}{6}{+Show, +Help, +Special, +Prompt, -Term, -Bindings}
Similar to \index{read_term/2}\predref{read_term}{2} using the option \const{variable_names}, but
allows for history substitutions. \index{read_history/6}\predref{read_history}{6} is used by the top level
to read the user's actions. \arg{Show} is the command the user
should type to show the saved events. \arg{Help} is the command to get
an overview of the capabilities. \arg{Special} is a list of commands
that are not saved in the history. \arg{Prompt} is the first prompt
given. Continuation prompts for more lines are determined by \index{prompt/2}\predref{prompt}{2}. A
\const{\%w} in the prompt is substituted by the event number. See
\secref{history} for available substitutions.

SWI-Prolog calls \index{read_history/6}\predref{read_history}{6} as follows:

\begin{code}
read_history(h, '!h', [trace], '%w ?- ', Goal, Bindings)
\end{code}

\noindent
    \predicate{prompt}{2}{-Old, +New}
Set prompt associated with \index{read/1}\predref{read}{1} and its derivatives.  \arg{Old}
is first unified with the current prompt.  On success the prompt will be
set to \arg{New} if this is an atom.  Otherwise an error message is
displayed.  A prompt is printed if one of the read predicates is
called and the cursor is at the left margin.  It is also printed
whenever a newline is given and the term has not been terminated.
Prompts are only printed when the current input stream is \arg{user}.

    \predicate{prompt1}{1}{+Prompt}
Sets the prompt for the next line to be read.  Continuation lines will
be read using the prompt defined by \index{prompt/2}\predref{prompt}{2}.
\end{description}

\section{Analysing and Constructing Terms}	\label{sec:manipterm}

\begin{description}
    \predicate[ISO]{functor}{3}{?Term, ?Name, ?Arity}
True when \arg{Term} is a term with functor \arg{Name}/\arg{Arity}. If
\arg{Term} is a variable it is unified with a new term whose arguments are all
different variables (such a term is called a skeleton). If \arg{Term} is
atomic, \arg{Arity} will be unified with the integer 0, and \arg{Name} will be
unified with \arg{Term}.  Raises \errorterm{instantiation_error}{} if \arg{Term}
is unbound and \arg{Name}/\arg{Arity} is insufficiently instantiated.

SWI-Prolog also supports terms with arity 0, as in \exam{a()} (see
\secref{extensions}. Such terms must be processed using
\index{compound_name_arity/3}\predref{compound_name_arity}{3}. The predicate \index{functor/3}\predref{functor}{3} and \predref{\Suniv}{2}
raise a \const{domain_error} when faced with these terms. Without this
precaution, the inconsistency demonstrated below could happen
silently.\footnote{Raising a domain error was suggested by Jeff
Schultz.}

\begin{code}
?- functor(a(), N, A).
N = a, A = 0.
?- functor(T, a, 0).
T = a.
\end{code}

\noindent
    \predicate[ISO]{arg}{3}{?Arg, +Term, ?Value}
\arg{Term} should be instantiated to a term, \arg{Arg} to an integer
between 1 and the arity of \arg{Term}. \arg{Value} is unified with the
\arg{Arg}-th argument of \arg{Term}.  \arg{Arg} may also be unbound.
In this case \arg{Value} will be unified with the successive arguments
of the term. On successful unification, \arg{Arg} is unified with the
argument number. Backtracking yields alternative solutions.%
    \footnote{The instantiation pattern (-, +, ?) is an extension to
              `standard' Prolog. Some systems provide
	      \nopredref{genarg}{3} that covers this pattern.}
The predicate \index{arg/3}\predref{arg}{3} fails silently if $\arg{Arg} = 0$ or
$\arg{Arg} > \mbox{\em arity}$ and raises the exception
\errorterm{domain_error}{not_less_than_zero, \arg{Arg}} if $\arg{Arg} <
0$.

    \infixop[ISO]{\Suniv}{?Term}{?List}
\arg{List} is a list whose head is the functor of \arg{Term} and the
remaining arguments are the arguments of the term. Either side of the
predicate may be a variable, but not both.  This predicate is called
`Univ'.

\begin{code}
?- foo(hello, X) =.. List.
List = [foo, hello, X]

?- Term =.. [baz, foo(1)].
Term = baz(foo(1))
\end{code}

\noindent
SWI-Prolog also supports terms with arity 0, as in \exam{a()} (see
\secref{extensions}. Such terms must be processed using
\index{compound_name_arguments/3}\predref{compound_name_arguments}{3}. This predicate raises a domain error as shown
below. See also \index{functor/3}\predref{functor}{3}.

\begin{code}
?- a() =.. L.
ERROR: Domain error: `compound_non_zero_arity' expected, found `a()'
\end{code}

\noindent
    \predicate{compound_name_arity}{3}{?Compound, ?Name, ?Arity}
Rationalized version of \index{functor/3}\predref{functor}{3} that only works for compound terms
and can examine and create compound terms with zero arguments (e.g,
\exam{name()}.  See also \index{compound_name_arguments/3}\predref{compound_name_arguments}{3}.

    \predicate{compound_name_arguments}{3}{?Compound, ?Name, ?Arguments}
Rationalized version of \predref{\Suniv}{2} that can compose and decompose
compound terms with zero arguments. See also \index{compound_name_arity/3}\predref{compound_name_arity}{3}.

    \predicate{numbervars}{3}{+Term, +Start, -End}
Unify the free variables in \arg{Term} with a term \term{\$VAR}{N},
where \arg{N} is the number of the variable. Counting starts at
\arg{Start}. \arg{End} is unified with the number that should be given
to the next variable.\bug{Only \jargon{tagged integers} are supported
(see the Prolog flag \prologflag{max_tagged_integer}). This suffices to
count all variables that can appear in the largest term that can be
represented, but does not support arbitrary large integer values for
\arg{Start}. On overflow, a \term{representation_error}{tagged_integer}
exception is raised.} The example below illustrates this. Note that the
toplevel prints \verb!'$VAR'(0)! as \arg{A} due to the
\term{numbervars}{true} option used to print answers.

\begin{code}
?- Term = f(X,Y,X),
   numbervars(Term, 0, End),
   write_canonical(Term), nl.
f('$VAR'(0),'$VAR'(1),'$VAR'(0))
Term = f(A, B, A),
X = A,
Y = B,
End = 2.
\end{code}

\noindent
See also the \const{numbervars} option to \index{write_term/3}\predref{write_term}{3} and \index{numbervars/4}\predref{numbervars}{4}.

    \predicate{numbervars}{4}{+Term, +Start, -End, +Options}
As \index{numbervars/3}\predref{numbervars}{3}, providing the following options:

    \begin{description}
        \termitem{functor_name}{+Atom}
Name of the functor to use instead of \verb|$VAR|.

	\termitem{attvar}{+Action}
What to do if an attributed variable is encountered.  Options are
\const{skip}, which causes \index{numbervars/3}\predref{numbervars}{3} to ignore the attributed
variable, \const{bind} which causes it to treat it as a normal
variable and assign the next \verb|'$VAR'|(N) term to it, or (default)
\const{error} which raises a \const{type_error} exception.%
	\footnote{This behaviour was decided after a long discussion
		  between David Reitter, Richard O'Keefe, Bart Demoen
		  and Tom Schrijvers.}

	\termitem{singletons}{+Bool}
If \const{true} (default \const{false}), \index{numbervars/4}\predref{numbervars}{4} does singleton
detection.  Singleton variables are unified with \verb|'$VAR'('_')|,
causing them to be printed as \verb|_| by \index{write_term/2}\predref{write_term}{2} using the
numbervars option.  This option is exploited by \index{portray_clause/2}\predref{portray_clause}{2}
and \index{write_canonical/2}\predref{write_canonical}{2}.%
	\bug{Currently this option is ignored for cyclic terms.}
    \end{description}

    \predicate{var_number}{2}{@Term, -VarNumber}
True if \arg{Term} is numbered by \index{numbervars/3}\predref{numbervars}{3} and \arg{VarNumber} is
the number given to this variable.  This predicate avoids the need for
unification with \verb!'$VAR'(X)! and opens the path for replacing this
valid Prolog term by an internal representation that has no textual
equivalent.

    \predicate[ISO]{term_variables}{2}{+Term, -List}
Unify \arg{List} with a list of variables, each sharing with a unique variable
of \arg{Term}.%
	\footnote{This predicate used to be called
	\nopredref{free_variables}{2}. The name \index{term_variables/2}\predref{term_variables}{2} is more
	widely used. The old predicate is still available from the
	library \pllib{backcomp}.}
The variables in \arg{List} are ordered in order of appearance
traversing \arg{Term} depth-first and left-to-right. See also
\index{term_variables/3}\predref{term_variables}{3} and \index{nonground/2}\predref{nonground}{2}. For example:

\begin{code}
?- term_variables(a(X, b(Y, X), Z), L).
L = [X, Y, Z].
\end{code}

\noindent
    \predicate[semidet]{nonground}{2}{+Term, -Var}
True when \arg{Var} is a variable in \arg{Term}.  Fails if \arg{Term}
is \jargon{ground} (see \index{ground/1}\predref{ground}{1}).  This predicate is intended for
coroutining to trigger a wakeup if \arg{Term} becomes ground, e.g.,
using \index{when/2}\predref{when}{2}.  The current implemention always returns the first
variable in depth-first left-right search.  Ideally it should return
a random member of the set of variables (see \index{term_variables/2}\predref{term_variables}{2}) to
realise logarithmetic complexity for the ground trigger.  Compatible
with ECLiPSe and hProlog.

    \predicate{term_variables}{3}{+Term, -List, ?Tail}
Difference list version of \index{term_variables/2}\predref{term_variables}{2}.  That is, \arg{Tail} is the
tail of the variable list \arg{List}.

    \predicate{term_singletons}{2}{+Term, -List}
Unify \arg{List} with a list of variables, each sharing with a variable
that appears only once in \arg{Term}.\bug{In the current implementation
\arg{Term} must be acyclic.  If not, a \const{representation_error} is
raised.}  Note that, if a variable appears
in a shared subterm, it is \emph{not} considered singleton. Thus,
\arg{A} is \emph{not} a singleton in the example below.  See also
the \const{singleton} option of \index{numbervars/4}\predref{numbervars}{4}.

\begin{code}

?- S = a(A), term_singletons(t(S,S), L).
L = [].
\end{code}

\noindent
    \predicate[ISO]{copy_term}{2}{+In, -Out}
Create a version of \arg{In} with renamed (fresh) variables and unify it
to \arg{Out}.  Attributed variables (see \secref{attvar}) have their
attributes copied.  The implementation of \index{copy_term/2}\predref{copy_term}{2} can deal with
infinite trees (cyclic terms). As pure Prolog cannot distinguish a
ground term from another ground term with exactly the same structure,
ground sub-terms are \emph{shared} between \arg{In} and \arg{Out}.
Sharing ground terms does affect \index{setarg/3}\predref{setarg}{3}.  SWI-Prolog provides
\index{duplicate_term/2}\predref{duplicate_term}{2} to create a true copy of a term.
\end{description}


\subsection{Non-logical operations on terms}	\label{sec:setarg}

Prolog is not able to \emph{modify} instantiated parts of a term.
Lacking that capability makes the language much safer, but
unfortunately there are problems that suffer severely in terms of
time and/or memory usage.  Always try hard to avoid the use of
these primitives, but they can be a good alternative to using
dynamic predicates.  See also \secref{gvar}, discussing the use
of global variables.

\begin{description}
    \predicate{setarg}{3}{+Arg, +Term, +Value}
Extra-logical predicate.  Assigns the \arg{Arg}-th argument of the
compound term \arg{Term} with the given \arg{Value}.  The assignment
is undone if backtracking brings the state back into a position before
the \index{setarg/3}\predref{setarg}{3} call.  See also \index{nb_setarg/3}\predref{nb_setarg}{3}.

This predicate may be used for destructive assignment to terms, using
them as an extra-logical storage bin. Always try hard to avoid the use
of \index{setarg/3}\predref{setarg}{3} as it is not supported by many Prolog systems and one has to
be very careful about unexpected copying as well as unexpected
noncopying of terms. A good practice to improve somewhat on this situation
is to make sure that terms whose arguments are subject to \index{setarg/3}\predref{setarg}{3} have
one unused and unshared variable in addition to the used arguments. This
variable avoids unwanted sharing in, e.g., \index{copy_term/2}\predref{copy_term}{2}, and causes the
term to be considered as non-ground. An alternative is to use \index{put_attr/3}\predref{put_attr}{3}
to attach information to attributed variables (see~\secref{attvar}).

    \predicate{nb_setarg}{3}{+Arg, +Term, +Value}
Assigns the \arg{Arg}-th argument of the compound term \arg{Term} with
the given \arg{Value} as \index{setarg/3}\predref{setarg}{3}, but on backtracking the assignment
is \emph{not} reversed.  If \arg{Value} is not atomic, it is duplicated
using \index{duplicate_term/2}\predref{duplicate_term}{2}. This predicate uses the same technique as
\index{nb_setval/2}\predref{nb_setval}{2}.  We therefore refer to the description of \index{nb_setval/2}\predref{nb_setval}{2}
for details on non-backtrackable assignment of terms.  This predicate
is compatible with GNU-Prolog \term{setarg}{A,T,V,false}, removing the
type restriction on \arg{Value}.  See also \index{nb_linkarg/3}\predref{nb_linkarg}{3}.  Below
is an example for counting the number of solutions of a goal.  Note
that this implementation is thread-safe, reentrant and capable of
handling exceptions.  Realising these features with a traditional
implementation based on assert/retract or \index{flag/3}\predref{flag}{3} is much more
complicated.

\begin{code}
:- meta_predicate
        succeeds_n_times(0, -).

succeeds_n_times(Goal, Times) :-
        Counter = counter(0),
        (   Goal,
            arg(1, Counter, N0),
            N is N0 + 1,
            nb_setarg(1, Counter, N),
            fail
        ;   arg(1, Counter, Times)
        ).
\end{code}

\noindent
    \predicate{nb_linkarg}{3}{+Arg, +Term, +Value}
As \index{nb_setarg/3}\predref{nb_setarg}{3}, but like \index{nb_linkval/2}\predref{nb_linkval}{2} it does \emph{not} duplicate
\arg{Value}.  Use with extreme care and consult the documentation
of \index{nb_linkval/2}\predref{nb_linkval}{2} before use.

    \predicate{duplicate_term}{2}{+In, -Out}
Version of \index{copy_term/2}\predref{copy_term}{2} that also copies ground terms and therefore
ensures that destructive modification using \index{setarg/3}\predref{setarg}{3} does not affect the
copy.  See also \index{nb_setval/2}\predref{nb_setval}{2}, \index{nb_linkval/2}\predref{nb_linkval}{2}, \index{nb_setarg/3}\predref{nb_setarg}{3} and \index{nb_linkarg/3}\predref{nb_linkarg}{3}.

    \predicate[semidet]{same_term}{2}{@T1, @T2}
True if \arg{T1} and \arg{T2} are equivalent and will remain
equivalent, even if \index{setarg/3}\predref{setarg}{3} is used on either of them.   This means
\arg{T1} and \arg{T2} are the same variable, equivalent atomic data
or a compound term allocated at the same address.
\end{description}


\section{Analysing and Constructing Atoms}	\label{sec:manipatom}

These predicates convert between Prolog constants and lists of character
codes. The predicates \index{atom_codes/2}\predref{atom_codes}{2}, \index{number_codes/2}\predref{number_codes}{2} and \index{name/2}\predref{name}{2} behave
the same when converting from a constant to a list of character codes.
When converting the other way around, \index{atom_codes/2}\predref{atom_codes}{2} will generate an
atom, \index{number_codes/2}\predref{number_codes}{2} will generate a number or exception and \index{name/2}\predref{name}{2} will
return a number if possible and an atom otherwise.

The ISO standard defines \index{atom_chars/2}\predref{atom_chars}{2} to describe the `broken-up'
atom as a list of one-character atoms instead of a list of codes.  Up to
version 3.2.x, SWI-Prolog's \index{atom_chars/2}\predref{atom_chars}{2} behaved like atom_codes, compatible with
Quintus and SICStus Prolog. As of 3.3.x, SWI-Prolog
\index{atom_codes/2}\predref{atom_codes}{2} and \index{atom_chars/2}\predref{atom_chars}{2} are compliant to the ISO standard.

To ease the pain of all variations in the Prolog community, all
SWI-Prolog predicates behave as flexible as possible.  This implies
the `list-side' accepts either a code-list or a char-list and the
`atom-side' accepts all atomic types (atom, number and string).

\begin{description}
    \predicate[ISO]{atom_codes}{2}{?Atom, ?String}
Convert between an atom and a list of character codes. If
\arg{Atom} is instantiated, it will be translated into a list of character
codes and the result is unified with \arg{String}. If \arg{Atom}
is unbound and \arg{String} is a list of character codes,
\arg{Atom} will be unified with an atom constructed from this list.


    \predicate[ISO]{atom_chars}{2}{?Atom, ?CharList}
As \index{atom_codes/2}\predref{atom_codes}{2}, but \arg{CharList} is a list of one-character atoms
rather than a list of character codes.%
	\footnote{Up to version 3.2.x, \index{atom_chars/2}\predref{atom_chars}{2} behaved as the
		  current \index{atom_codes/2}\predref{atom_codes}{2}.  The current definition is
		  compliant with the ISO standard.}
\begin{code}
?- atom_chars(hello, X).

X = [h, e, l, l, o]
\end{code}

\noindent
    \predicate[ISO]{char_code}{2}{?Atom, ?Code}
Convert between character and character code for a single
character.%
	\footnote{This is also called \nopredref{atom_char}{2} in older
	versions of SWI-Prolog as well as some other Prolog
	implementations. The \nopredref{atom_char}{2} predicate is
	available from the library \file{backcomp.pl}}

    \predicate[ISO]{number_chars}{2}{?Number, ?CharList}
Similar to \index{atom_chars/2}\predref{atom_chars}{2}, but converts between a number and its
representation as a list of one-character atoms. If \arg{CharList} is a
\jargon{proper list}, i.e., not unbound or a \jargon{partial list},
\arg{CharList} is parsed according to the Prolog syntax for numbers and
the resulting number is unified with \arg{Number}. Otherwise, if
\arg{Number} is a number, \arg{Number} is serialized and the result is
unified with \arg{CharList}.

If \arg{CharList} is parsed, it is parsed using the Prolog syntax for
numbers. Following the ISO standard, it allows for \emph{leading} white
space (including newlines) and does not allow for \emph{trailing} white
space.\footnote{ISO also allows for Prolog comments in leading white
space. We--and most other implementations--believe this is incorrect. We
also beleive it would have been better not to allow for white space, or
to allow for both leading and trailing white space. Prolog syntax-based
conversion can also be achieved using \index{format/3}\predref{format}{3} and \index{read_from_chars/2}\predref{read_from_chars}{2}.}
A \except{syntax_error} exception is raised if \arg{CharList} does not
represent a valid Prolog number.

    \predicate[ISO]{number_codes}{2}{?Number, ?CodeList}
As \index{number_chars/2}\predref{number_chars}{2}, but converts to a list of character codes rather
than one-character atoms.  In the mode (-,+), both predicates
behave identically to improve handling of non-ISO source.

    \predicate{atom_number}{2}{?Atom, ?Number}
Realises the popular combination of \index{atom_codes/2}\predref{atom_codes}{2} and \index{number_codes/2}\predref{number_codes}{2} to
convert between atom and number (integer or float) in one predicate,
avoiding the intermediate list. Unlike the ISO \index{number_codes/2}\predref{number_codes}{2}
predicates, \index{atom_number/2}\predref{atom_number}{2} fails silently in mode (+,-) if \arg{Atom}
does not represent a number.\footnote{Versions prior to 6.1.7 raised a
syntax error, compliant to \index{number_codes/2}\predref{number_codes}{2}} See also \index{atomic_list_concat/2}\predref{atomic_list_concat}{2}
for assembling an atom from atoms and numbers.

    \predicate{name}{2}{?Atomic, ?CodeList}
\arg{CodeList} is a list of character codes representing the same text
as \arg{Atomic}. Each of the arguments may be a variable, but not both.
When \arg{CodeList} describes an integer or floating point number and
\arg{Atomic} is a variable, \arg{Atomic} will be unified with the numeric
value described by \arg{CodeList} (e.g., \exam{name(N, "300"), 400 is N +
100} succeeds). If \arg{CodeList} is not a representation of a number,
\arg{Atomic} will be unified with the atom with the name given by the
character code list. If \arg{Atomic} is an atom or number, the
unquoted print representation of it as a character code list is
unified with \arg{CodeList}.

This predicate is part of the Edinburgh tradition. It should be
considered \jargon{deprecated} although, given its long tradition, it is
unlikely to be removed from the system. It still has some value for
converting input to, depending on the syntax, a number or atom. New code
should consider the ISO predicates \index{atom_codes/2}\predref{atom_codes}{2}, \index{number_codes/2}\predref{number_codes}{2} or the
SWI-Prolog predicate \index{atom_number/2}\predref{atom_number}{2}.

    \predicate{term_to_atom}{2}{?Term, ?Atom}
True if \arg{Atom} describes a term that unifies with \arg{Term}. When
\arg{Atom} is instantiated, \arg{Atom} is parsed and the result unified
with \arg{Term}. If \arg{Atom} has no valid syntax, a
\except{syntax_error} exception is raised. Otherwise \arg{Term} is
``written'' on \arg{Atom} using \index{write_term/2}\predref{write_term}{2} with the option
\term{quoted}{true}. See also \index{format/3}\predref{format}{3}, \index{with_output_to/2}\predref{with_output_to}{2} and
\index{term_string/2}\predref{term_string}{2}.

    \predicate[deprecated]{atom_to_term}{3}{+Atom, -Term, -Bindings}
Use \arg{Atom} as input to \index{read_term/2}\predref{read_term}{2} using the option
\const{variable_names} and return the read term in \arg{Term} and the
variable bindings in \arg{Bindings}. \arg{Bindings} is a list of
$\arg{Name} = \arg{Var}$ couples, thus providing access to the actual
variable names. See also \index{read_term/2}\predref{read_term}{2}. If \arg{Atom} has no valid syntax,
a \except{syntax_error} exception is raised.  New code should use
\index{read_term_from_atom/3}\predref{read_term_from_atom}{3}.

    \predicate[ISO]{atom_concat}{3}{?Atom1, ?Atom2, ?Atom3}
\arg{Atom3} forms the concatenation of \arg{Atom1} and \arg{Atom2}. At
least two of the arguments must be instantiated to atoms. This predicate
also allows for the mode (-,-,+), non-deterministically splitting the
3rd argument into two parts (as \index{append/3}\predref{append}{3} does for lists).  SWI-Prolog
allows for atomic arguments.  Portable code must use \index{atomic_concat/3}\predref{atomic_concat}{3}
if non-atom arguments are involved.

    \predicate{atomic_concat}{3}{+Atomic1, +Atomic2, -Atom}
\arg{Atom} represents the text after converting \arg{Atomic1} and
\arg{Atomic2} to text and concatenating the result:

\begin{code}
?- atomic_concat(name, 42, X).
X = name42.
\end{code}

\noindent
    \predicate[commons]{atomic_list_concat}{2}{+List, -Atom}
\arg{List} is a list of strings, atoms, integers or floating point
numbers. Succeeds if \arg{Atom} can be unified with the concatenated
elements of \arg{List}. Equivalent to \term{atomic_list_concat}{List,
'', Atom}.

    \predicate[commons]{atomic_list_concat}{3}{+List, +Separator, -Atom}
Creates an atom just like \index{atomic_list_concat/2}\predref{atomic_list_concat}{2}, but inserts \arg{Separator}
between each pair of inputs.  For example:
\begin{code}
?- atomic_list_concat([gnu, gnat], ', ', A).

A = 'gnu, gnat'
\end{code}

\noindent
The SWI-Prolog version of this predicate can also be used to split atoms
by instantiating \arg{Separator} and \arg{Atom} as shown below.  We kept
this functionality to simplify porting old SWI-Prolog code where this
predicate was called \index{concat_atom/3}\predref{concat_atom}{3}.  When used in mode (-,+,+),
\arg{Separator} must be a non-empty atom.  See also \index{split_string/4}\predref{split_string}{4}.

\begin{code}
?- atomic_list_concat(L, -, 'gnu-gnat').

L = [gnu, gnat]
\end{code}

\noindent
    \predicate[ISO]{atom_length}{2}{+Atom, -Length}
True if \arg{Atom} is an atom of \arg{Length} characters. The
SWI-Prolog version accepts all atomic types, as well as code-lists and
character-lists. New code should avoid this feature and use
\index{write_length/3}\predref{write_length}{3} to get the number of characters that would be written if
the argument was handed to \index{write_term/3}\predref{write_term}{3}.

    \predicate[deprecated]{atom_prefix}{2}{+Atom, +Prefix}
True if \arg{Atom} starts with the characters from \arg{Prefix}.
Its behaviour is equivalent to
\exam{?- sub_atom(\arg{Atom}, 0, _, _, \arg{Prefix})}.  Deprecated.

    \predicate[ISO]{sub_atom}{5}{+Atom, ?Before, ?Len, ?After, ?Sub}
ISO predicate for breaking atoms.  It maintains the following relation:
\arg{Sub} is a sub-atom of \arg{Atom} that starts at \arg{Before}, has
\arg{Len} characters, and \arg{Atom} contains \arg{After} characters
after the match.

\begin{code}
?- sub_atom(abc, 1, 1, A, S).

A = 1, S = b
\end{code}

\noindent
The implementation minimises non-determinism and creation of atoms.
This is a flexible predicate that can do search, prefix- and
suffix-matching, etc.

    \predicate[semidet]{sub_atom_icasechk}{3}{+Haystack, ?Start, +Needle}
True when \arg{Needle} is a sub atom of \arg{Haystack} starting at
\arg{Start}. The match is `half case insensitive', i.e., uppercase
letters in \arg{Needle} only match themselves, while lowercase letters
in \arg{Needle} match case insensitively.  \arg{Start} is the first
0-based offset inside \arg{Haystack} where \arg{Needle}
matches.\footnote{This predicate replaces \$\index{apropos_match/2}\predref{apropos_match}{2}, used by the
help system, while extending it with locating the (first) match and
performing case insensitive prefix matching. We are still not happy
with the name and interface.}
\end{description}


\section{Localization (locale) support}		\label{sec:locale}

SWI-Prolog provides (currently limited) support for localized
applications.

\begin{itemize}
    \item
The predicates \index{char_type/2}\predref{char_type}{2} and \index{code_type/2}\predref{code_type}{2} query character classes
depending on the locale.
    \item
The predicates \index{collation_key/2}\predref{collation_key}{2} and \index{locale_sort/2}\predref{locale_sort}{2} can be used for
locale dependent sorting of atoms.
    \item
The predicate \index{format_time/3}\predref{format_time}{3} can be used to format time and date
representations, where some of the specifiers are locale dependent.
    \item
The predicate \index{format/2}\predref{format}{2} provides locale-specific formating of numbers.
This functionality is based on a more fine-grained localization model
that is the subject of this section.
\end{itemize}

A locale is a (optionally named) read-only object that provides
information to locale specific functions.\footnote{The locale interface
described in this section and its effect on \index{format/2}\predref{format}{2} and reading
integers from digit groups was discussed on the SWI-Prolog mailinglist.
Most input in this discussion is from Ulrich Neumerkel and Richard
O'Keefe. The predicates in this section were designed by Jan
Wielemaker.} The system creates a default locale object named
\const{default} from the system locale. This locale is used as the
initial locale for the three standard streams as well as the
\const{main} thread. Locale sensitive output predicates such as \index{format/3}\predref{format}{3}
get their locale from the stream to which they deliver their output. New
streams get their locale from the thread that created the stream.
Threads get their locale from the thread that created them.

\begin{description}
    \predicate{locale_create}{3}{-Locale, +Default, +Options}
Create a new locale object.  \arg{Default} is either an existing
locale or a string that denotes the name of a locale provided by
the system, such as \verb$"en_EN.UTF-8"$.  The values read from
the default locale can be modified using \arg{Options}.  \arg{Options}
provided are:

    \begin{description}
	\termitem{alias}{+Atom}
    Give the locale a name.
	\termitem{decimal_point}{+Atom}
    Specify the decimal point to use.
	\termitem{thousands_sep}{+Atom}
    Specify the string that delimits digit groups.  Only
    effective is \const{grouping} is also specified.
	\termitem{grouping}{+List}
    Specify the grouping of digits.  Groups are created from
    the right (least significant) digits, left of the decimal
    point.  \arg{List} is a list of integers, specifying the
    number of digits in each group, counting from the right.
    If the last element is \term{repeat}{Count}, the remaining
    digits are grouped in groups of size \arg{Count}.  If the
    last element is a normal integer, digits further to the left
    are not grouped.
    \end{description}

For example, the English locale uses
\begin{code}
[ decimal_point('.'), thousands_sep(','), grouping([repeat(3)]) ]
\end{code}

\noindent
Named locales exists until they are destroyed using \index{locale_destroy/1}\predref{locale_destroy}{1}
and they are no longer referenced.  Unnamed locales are subject to
(atom) garbage collection.

    \predicate{locale_destroy}{1}{+Locale}
Destroy a locale.  If the locale is named, this removes the name
association from the locale, after which the locale is left to be
reclaimed by garbage collection.

    \predicate{locale_property}{2}{?Locale, ?Property}
True when \arg{Locale} has \arg{Property}.  Properties are the same
as the \arg{Options} described with \index{locale_create/3}\predref{locale_create}{3}.

    \predicate{set_locale}{1}{+Locale}
Set the default locale for the current thread, as well as the locale
for the standard streams (\const{user_input}, \const{user_output},
\const{user_error}, \const{current_output} and \const{current_input}.
This locale is used for new streams, unless overruled using the
\term{locale}{Locale} option of \index{open/4}\predref{open}{4} or \index{set_stream/2}\predref{set_stream}{2}.

    \predicate{current_locale}{1}{-Locale}
True when \arg{Locale} is the locale of the calling thread.
\end{description}


\section{Character properties}		\label{sec:chartype}

SWI-Prolog offers two comprehensive predicates for classifying
characters and character codes. These predicates are defined as built-in
predicates to exploit the C-character classification's handling of
\jargon{locale} (handling of local character sets). These predicates are
fast, logical and deterministic if applicable.

In addition, there is the library \pllib{ctypes} providing compatibility
with some other Prolog systems. The predicates of this library are defined
in terms of \index{code_type/2}\predref{code_type}{2}.

\begin{description}
    \predicate{char_type}{2}{?Char, ?Type}
Tests or generates alternative \arg{Type}s or \arg{Char}s. The
character types are inspired by the standard C \file{<ctype.h>}
primitives.  Note that the mode (-,+) is only efficient if the
\arg{Type} has a parameter, e.g., \term{char_type}{C, digit(8)}.
With an atomic \arg{Type} the whole unicode range (0..0x1ffff)
is generated and tested against the C character classification
function.

\begin{description}
    \termitem{alnum}{}
\arg{Char} is a letter (upper- or lowercase) or digit.
    \termitem{alpha}{}
\arg{Char} is a letter (upper- or lowercase).
    \termitem{csym}{}
\arg{Char} is a letter (upper- or lowercase), digit or the underscore
(\verb$_$).  These are valid C and Prolog symbol characters.
    \termitem{csymf}{}
\arg{Char} is a letter (upper- or lowercase) or the underscore
(\verb$_$). These are valid first characters for C and Prolog symbols.
    \termitem{ascii}{}
\arg{Char} is a 7-bit ASCII character (0..127).
    \termitem{white}{}
\arg{Char} is a space or tab, i.e.\ white space inside a line.
    \termitem{cntrl}{}
\arg{Char} is an ASCII control character (0..31), ASCII DEL character
(127), or non-ASCII character in the range 128..159 or 8232..8233.
    \termitem{digit}{}
\arg{Char} is a digit.
    \termitem{digit}{Weight}
\arg{Char} is a digit with value \arg{Weight}. I.e.\ \exam{char_type(X,
digit(6))} yields \arg{X} = \exam{'6'}.  Useful for parsing numbers.
    \termitem{xdigit}{Weight}
\arg{Char} is a hexadecimal digit with value \arg{Weight}. I.e.\
\exam{char_type(a, xdigit(X))} yields \arg{X} = \exam{'10'}. Useful for
parsing numbers.
    \termitem{graph}{}
\arg{Char} produces a visible mark on a page when printed. Note that
the space is not included!
    \termitem{lower}{}
\arg{Char} is a lowercase letter.
    \termitem{lower}{Upper}
\arg{Char} is a lowercase version of \arg{Upper}. Only true if
\arg{Char} is lowercase and \arg{Upper} uppercase.
    \termitem{to_lower}{Upper}
\arg{Char} is a lowercase version of \arg{Upper}. For non-letters,
or letter without case, \arg{Char} and \arg{Lower} are the same.
See also \index{upcase_atom/2}\predref{upcase_atom}{2} and \index{downcase_atom/2}\predref{downcase_atom}{2}.
    \termitem{upper}{}
\arg{Char} is an uppercase letter.
    \termitem{upper}{Lower}
\arg{Char} is an uppercase version of \arg{Lower}. Only true if
\arg{Char} is uppercase and \arg{Lower} lowercase.
    \termitem{to_upper}{Lower}
\arg{Char} is an uppercase version of \arg{Lower}.  For non-letters,
or letter without case, \arg{Char} and \arg{Lower} are the same.
See also \index{upcase_atom/2}\predref{upcase_atom}{2} and \index{downcase_atom/2}\predref{downcase_atom}{2}.
    \termitem{punct}{}
\arg{Char} is a punctuation character. This is a \const{graph} character
that is not a letter or digit.
    \termitem{space}{}
\arg{Char} is some form of layout character (tab, vertical tab, newline,
etc.).
    \termitem{end_of_file}{}
\arg{Char} is -1.
    \termitem{end_of_line}{}
\arg{Char} ends a line (ASCII: 10..13).
    \termitem{newline}{}
\arg{Char} is a newline character (10).
    \termitem{period}{}
\arg{Char} counts as the end of a sentence (.,!,?).
    \termitem{quote}{}
\arg{Char} is a quote character (\verb$"$, \verb$'$, \verb$`$).
    \termitem{paren}{Close}
\arg{Char} is an open parenthesis and \arg{Close} is the corresponding
close parenthesis.
    \termitem{prolog_var_start}{}
\arg{Char} can start a Prolog variable name.
    \termitem{prolog_atom_start}{}
\arg{Char} can start a unquoted Prolog atom that is not a symbol.
    \termitem{prolog_identifier_continue}{}
\arg{Char} can continue a Prolog variable name or atom.
    \termitem{prolog_symbol}{}
\arg{Char} is a Prolog symbol character.  Sequences of Prolog
symbol characters glue together to form an unquoted atom.  Examples
are \const{\Suniv}, \const{\Sne}, etc.
\end{description}

    \predicate{code_type}{2}{?Code, ?Type}
As \index{char_type/2}\predref{char_type}{2}, but uses character codes rather than one-character
atoms.  Please note that both predicates are as flexible as possible.
They handle either representation if the argument is instantiated
and will instantiate only with an integer code or a one-character atom,
depending of the version used. See also the Prolog flag
\prologflag{double_quotes}, \index{atom_chars/2}\predref{atom_chars}{2} and \index{atom_codes/2}\predref{atom_codes}{2}.
\end{description}


\subsection{Case conversion}
\label{sec:case}

There is nothing in the Prolog standard for converting case in textual
data.  The SWI-Prolog predicates \index{code_type/2}\predref{code_type}{2} and \index{char_type/2}\predref{char_type}{2} can be used
to test and convert individual characters. We have started some
additional support:

\begin{description}
    \predicate{downcase_atom}{2}{+AnyCase, -LowerCase}
Converts the characters of \arg{AnyCase} into lowercase as \index{char_type/2}\predref{char_type}{2}
does (i.e.\ based on the defined \jargon{locale} if Prolog provides
locale support on the hosting platform) and unifies the lowercase atom
with \arg{LowerCase}.

    \predicate{upcase_atom}{2}{+AnyCase, -UpperCase}
Converts, similar to \index{downcase_atom/2}\predref{downcase_atom}{2}, an atom to uppercase.
\end{description}


\subsection{White space normalization}
\label{sec:whitespace}

\begin{description}
    \predicate{normalize_space}{2}{-Out, +In}
Normalize white space in \arg{In}. All leading and trailing white space
is removed. All non-empty sequences for Unicode white space characters
are replaced by a single space (\verb$\u0020$) character.  \arg{Out}
uses the same conventions as \index{with_output_to/2}\predref{with_output_to}{2} and \index{format/3}\predref{format}{3}.
\end{description}


\subsection{Language-specific comparison}
\label{sec:collate}

\index{locale}\index{collate}\index{compare,language-specific}%
This section deals with predicates for language-specific string
comparison operations.

\begin{description}
    \predicate{collation_key}{2}{+Atom, -Key}
Create a \arg{Key} from \arg{Atom} for locale-specific comparison.
The key is defined such that if the key of atom $A$ precedes the key
of atom $B$ in the standard order of terms, $A$ is alphabetically
smaller than $B$ using the sort order of the current locale.

The predicate \index{collation_key/2}\predref{collation_key}{2} is used by \index{locale_sort/2}\predref{locale_sort}{2} from
library(sort).  Please examine the implementation of \index{locale_sort/2}\predref{locale_sort}{2}
as an example of using this call.

The \arg{Key} is an implementation-defined and generally unreadable
string.  On systems that do not support locale handling, \arg{Key}
is simply unified with \arg{Atom}.

    \predicate{locale_sort}{2}{+List, -Sorted}
Sort a list of atoms using the current locale.  \arg{List} is a list
of atoms or string objects (see \secref{strings}).  \arg{Sorted} is
unified with a list containing all atoms of \arg{List}, sorted to
the rules of the current locale.  See also \index{collation_key/2}\predref{collation_key}{2} and
\index{setlocale/3}\predref{setlocale}{3}.
\end{description}


\section{Operators}			\label{sec:operators}

Operators are defined to improve the readability of source code.
For example, without operators, to write \exam{2*3+4*5} one would have
to write \exam{+(*(2,3),*(4,5))}.  In Prolog, a number of operators have
been predefined. All operators, except for the comma (,) can be
redefined by the user.

\index{operator,and modules}%
Some care has to be taken before defining new operators. Defining too
many operators might make your source `natural' looking, but at the same
time using many operators can make it hard to understand the limits of
your syntax.

In SWI-Prolog, operators are local to the module in which they are
defined. Operators can be exported from modules using a term
\term{op}{Precedence, Type, Name} in the export list as specified by
\index{module/2}\predref{module}{2}. Many modern Prolog systems have module specific operators.
Unfortunately, there is no established interface for exporting and
importing operators. SWI-Prolog's convention has been addopted by YAP.

The module table of the module \const{user} acts as default table for
all modules and can be modified explicitly from inside a module to
achieve compatibility with other Prolog that do not have module-local
operators:

\begin{code}
:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).
\end{code}

\noindent
Although operators are module-specific and the predicates that define
them (\index{op/3}\predref{op}{3}) or rely on them such as \index{current_op/3}\predref{current_op}{3}, \index{read/1}\predref{read}{1} and \index{write/1}\predref{write}{1} are
module sensitive, they are not proper meta-predicates. If they were
proper meta predicates \index{read/1}\predref{read}{1} and \index{write/1}\predref{write}{1} would use the module from
which they are called, breaking compatibility with other Prolog systems.
The following rules apply:

\begin{enumerate}
    \item If the module is explicitly specified by qualifying the
          third argument (\index{op/3}\predref{op}{3}, \index{current_op/3}\predref{current_op}{3}) or specifying a
	  \term{module}{Module} option (\index{read_term/3}\predref{read_term}{3}, \index{write_term/3}\predref{write_term}{3}),
	  this module is used.
    \item While compiling, the module into which the compiled code
          is loaded applies.
    \item Otherwise, the \jargon{typein module} applies.  This is
          normally \const{user} and may be changed using \index{module/1}\predref{module}{1}.
\end{enumerate}

In SWI-Prolog, a \emph{quoted atom} never acts as an operator.  Note
that the portable way to stop an atom acting as an operator is to
enclose it in parentheses like this: (myop). See also
\secref{ext-syntax-op}.

\begin{description}
    \predicate[ISO]{op}{3}{+Precedence, +Type, :Name}
Declare \arg{Name} to be an operator of type \arg{Type} with precedence
\arg{Precedence}. \arg{Name} can also be a list of names, in which case
all elements of the list are declared to be identical operators.
\arg{Precedence} is an integer between 0 and 1200. Precedence 0 removes
the declaration. \arg{Type} is one of: \const{xf}, \const{yf},
\const{xfx}, \const{xfy}, \const{yfx}, \const{fy} or
\const{fx}. The `\chr{f}' indicates the position of the functor, while
\chr{x} and \chr{y} indicate the position of the arguments. `\chr{y}'
should be interpreted as ``on this position a term with precedence lower
or equal to the precedence of the functor should occur''. For `\chr{x}'
the precedence of the argument must be strictly lower. The precedence of
a term is 0, unless its principal functor is an operator, in which case
the precedence is the precedence of this operator. A term enclosed in
parentheses \exam{(\ldots)} has precedence 0.

The predefined operators are shown in \tabref{operators}. Operators can
be redefined, unless prohibited by one of the limitations below.
Applications must be careful with (re-)defining operators because
changing operators may cause (other) files to be interpreted
\textbf{differently}. Often this will lead to a syntax error. In other
cases, text is read silently into a different term which may lead to
subtle and difficult to track errors.

\begin{itemize}
    \item It is not allowed to redefine the comma (\verb$','$).
    \item The bar (\verb$|$) can only be (re-)defined as infix
          operator with priority not less than 1001.
    \item It is not allowed to define the empty list (\verb$[]$) or the
	  curly-bracket pair (\verb${}$) as operators.
\end{itemize}

In SWI-Prolog, operators are \emph{local} to a module (see also
\secref{moduleop}). Keeping operators in modules and using controlled
import/export of operators as described with the \index{module/2}\predref{module}{2} directive keep
the issues manageable. The module \const{system} provides the operators
from \tabref{operators} and these operators cannot be modified. Files
that are loaded from the SWI-Prolog directories resolve operators and
predicates from this \const{system} module rather than \const{user},
which makes the semantics of the library and development system modules
independent of operator changes to the \const{user} module.
See \secref{operators} for details about the relation between operators
and modules.

\begin{table}
\begin{center}
\begin{tabular}{|r|D{f}{f}{-1}|p{4in}|}
\hline
1200 & xfx & \op{\Sdcg}, \op{\Sneck} \\
1200 & fx & \op{\Sneck}, \op{\Sdirective} \\
1150 & fx & \op{dynamic}, \op{discontiguous}, \op{initialization},
	    \op{meta_predicate},
	    \op{module_transparent}, \op{multifile}, \op{public},
	    \op{thread_local}, \op{thread_initialization}, \op{volatile} \\
1100 & xfy & \op{\Ssemicolon}, \op{\Sbar} \\
1050 & xfy & \op{\Sifthen}, \op{\Ssoftcut} \\
1000 & xfy & \op{\Scomma} \\
990 & xfx & \op{:=} \\
900 & fy & \op{\Snot} \\
700 & xfx & \op{\Slt}, \op{\Seq}, \op{\Suniv}, \op{\Sstructeq}, \op{\Sstructneq},
	    \op{\Saeq}, \op{\Sle}, \op{\Sequal},
            \op{\Sane}, \op{\Sgt}, \op{\Sge}, \op{\Stlt}, \op{\Stle}, \op{\Stgt},
            \op{\Stge}, \op{\Sne}, \op{\Snequal}, \op{as}, \op{is},
	    \op{\Smappunify}, \op{\Smapselect}
	    \\
600 & xfy & \op{\Smodule} \\
500 & yfx & \op{\Splus}, \op{\Sminus}, \op{\Sand}, \op{\Sor}, \op{xor} \\
500 & fx & \op{\Squest} \\
400 & yfx & \op{\Stimes}, \op{\Sdiv}, \op{\Sidiv}, \op{div}, \op{rdiv},
            \op{\Slshift}, \op{\Srshift}, \op{mod}, \op{rem} \\
200 & xfx & \op{\Spow} \\
200 & xfy & \op{\Shat} \\
200 & fy  & \op{\Splus}, \op{\Sminus}, \op{\Sneg} \\
100 & yfx & \op{\Sdot} \\
1   & fx  & \op{\Sdollar} \\
\hline
\end{tabular}
\end{center}
    \caption{System operators}
    \label{tab:operators}
\end{table}

    \predicate[ISO]{current_op}{3}{?Precedence, ?Type, ?:Name}
True if \arg{Name} is currently defined as an operator of type \arg{Type}
with precedence \arg{Precedence}. See also \index{op/3}\predref{op}{3}.  Note that an
\jargon{unqualified} \arg{Name} does \textbf{not} resolve to the
calling context but, when compiling, to the compiler's target
module and otherwise to the \jargon{typein module}. See
\secref{operators} for details.
\end{description}


\section{Character Conversion}		\label{sec:charconv}

Although I wouldn't really know why you would like to use these
features, they are provided for ISO compliance.

\begin{description}
    \predicate[ISO]{char_conversion}{2}{+CharIn, +CharOut}
Define that term input (see \index{read_term/3}\predref{read_term}{3}) maps each character read as
\arg{CharIn} to the character \arg{CharOut}. Character conversion is
only executed if the Prolog flag \prologflag{char_conversion} is set to
\const{true} and not inside quoted atoms or strings. The initial table
maps each character onto itself. See also \index{current_char_conversion/2}\predref{current_char_conversion}{2}.
    \predicate[ISO]{current_char_conversion}{2}{?CharIn, ?CharOut}
Queries the current character conversion table.  See \index{char_conversion/2}\predref{char_conversion}{2}
for details.
\end{description}


\section{Arithmetic}				\label{sec:arith}

Arithmetic can be divided into some special purpose integer predicates
and a series of general predicates for integer, floating point and
rational arithmetic as appropriate. The general arithmetic predicates
all handle \arg{expressions}. An expression is either a simple number or
a \arg{function}. The arguments of a function are expressions. The
functions are described in \secref{functions}.


\subsection{Special purpose integer arithmetic}
\label{sec:logic-int-arith}

The predicates in this section provide more logical operations between
integers. They are not covered by the ISO standard, although they are
`part of the community' and found as either library or built-in in many
other Prolog systems.

\begin{description}
    \predicate{between}{3}{+Low, +High, ?Value}
\arg{Low} and \arg{High} are integers, $\arg{High} \geq \arg{Low}$. If
\arg{Value} is an integer, $\arg{Low} \leq \arg{Value} \leq \arg{High}$.
When \arg{Value} is a variable it is successively bound to all integers
between \arg{Low} and \arg{High}.  If \arg{High} is \const{inf} or
\const{infinite}%
	\footnote{We prefer \const{infinite}, but some other Prolog
		  systems already use \const{inf} for infinity; we
		  accept both for the time being.}
\index{between/3}\predref{between}{3} is true iff $\arg{Value} \geq \arg{Low}$, a feature that
is particularly interesting for generating integers from a certain
value.

    \predicate{succ}{2}{?Int1, ?Int2}
True if $\arg{Int2} = \arg{Int1} + 1$ and $\arg{Int1} \geq 0$.
At least one of the arguments must be instantiated to a natural number.
This predicate raises the domain error \const{not_less_than_zero} if
called with a negative integer.  E.g.\ \term{succ}{X, 0} fails silently
and \term{succ}{X, -1} raises a domain error.%
	\footnote{The behaviour to deal with natural numbers only was
		  defined by Richard O'Keefe to support
		  the common count-down-to-zero in a natural way.  Up to
		  5.1.8, \index{succ/2}\predref{succ}{2} also accepted negative integers.}

    \predicate{plus}{3}{?Int1, ?Int2, ?Int3}
True if $\arg{Int3} = \arg{Int1} + \arg{Int2}$. At least two of the
three arguments must be instantiated to integers.

    \predicate{divmod}{4}{+Dividend, +Divisor, -Quotient, -Remainder}
This predicate is a shorthand for computing both the \arg{Quotient} and
\arg{Remainder} of two integers in a single operation. This allows for
exploiting the fact that the low level implementation for computing the
quotient also produces the remainder. Timing confirms that this
predicate is almost twice as fast as performing the steps independently.
Semantically, \index{divmod/4}\predref{divmod}{4} is defined as below.

\begin{code}
divmod(Dividend, Divisor, Quotient, Remainder) :-
        Quotient  is Dividend div Divisor,
        Remainder is Dividend mod Divisor.
\end{code}

\noindent
Note that this predicate is only available if SWI-Prolog is compiled
with unbounded integer support.  This is the case for all packaged
versions.

    \predicate{nth_integer_root_and_remainder}{4}{+N, +I, -Root, -Remainder}
True when $\pow{Root}{N} + Remainder = I$. \arg{N} and \arg{I} must be
integers.\footnote{This predicate was suggested by Markus Triska.  The
final name and argument order is by Richard O'Keefe.  The decision to
include the remainder is by Jan Wielemaker.  Including the remainder
makes this predicate about twice as slow if \arg{Root} is not exact.}
\arg{N} must be one or more. If \arg{I} is negative and
\arg{N} is \jargon{odd}, \arg{Root} and \arg{Remainder} are negative,
i.e., the following holds for $\arg{I} < 0$:

\begin{code}
%   I < 0,
%   N mod 2 =\= 0,
    nth_integer_root_and_remainder(
        N, I, Root, Remainder),
    IPos is -I,
    nth_integer_root_and_remainder(
        N, IPos, RootPos, RemainderPos),
    Root =:= -RootPos,
    Remainder =:= -RemainderPos.
\end{code}

\noindent
\end{description}


\subsection{General purpose arithmetic}		\label{sec:arithpreds}

The general arithmetic predicates are optionally compiled (see
\index{set_prolog_flag/2}\predref{set_prolog_flag}{2} and the \cmdlineoption{-O} command line option).
Compiled arithmetic reduces global stack requirements and improves
performance. Unfortunately compiled arithmetic cannot be traced, which
is why it is optional.

\begin{description}
    \infixop[ISO]{\Sgt}{+Expr1}{+Expr2}
True if expression \arg{Expr1} evaluates to a larger number than \arg{Expr2}.

\infixop[ISO]{\Slt}{+Expr1}{+Expr2}
True if expression \arg{Expr1} evaluates to a smaller number than \arg{Expr2}.

\infixop[ISO]{\Sle}{+Expr1}{+Expr2}
True if expression \arg{Expr1} evaluates to a smaller or equal number
to \arg{Expr2}.

\infixop[ISO]{\Sge}{+Expr1}{+Expr2}
True if expression \arg{Expr1} evaluates to a larger or equal number
to \arg{Expr2}.

\infixop[ISO]{\Sane}{+Expr1}{+Expr2}
True if expression \arg{Expr1} evaluates to a number non-equal to
\arg{Expr2}.

\infixop[ISO]{\Saeq}{+Expr1}{+Expr2}
True if expression \arg{Expr1} evaluates to a number equal to \arg{
Expr2}.

\infixop[ISO]{is}{-Number}{+Expr}
True when \arg{Number} is the value to which \arg{Expr} evaluates.
Typically, \index{is/2}\predref{is}{2} should be used with unbound left operand. If equality is
to be tested, \predref{\Saeq}{2} should be used. For example:

\begin{center}\begin{tabular}{lp{2.5in}}
\exam{?- 1 is sin({pi}/2).}        & Fails!  sin({pi}/2) evaluates to the
				     float 1.0, which does not unify with
				     the integer 1. \\
\exam{?- 1 =:= sin({pi}/2).}       & Succeeds as expected.
\end{tabular}\end{center}
\end{description}


\subsubsection{Arithmetic types}	\label{sec:artypes}

\index{integer,unbounded}\index{rational,number}\index{number,rational}%
SWI-Prolog defines the following numeric types:

\begin{itemlist}
    \item [integer]
If SWI-Prolog is built using the \emph{GNU multiple precision arithmetic
library} \index{GMP}(GMP), integer arithmetic is \emph{unbounded}, which
means that the size of integers is limited by available memory only.
Without GMP, SWI-Prolog integers are 64-bits, regardless of the native
integer size of the platform. The type of integer support can be
detected using the Prolog flags \prologflag{bounded}, \prologflag{min_integer} and
\prologflag{max_integer}. As the use of GMP is default, most of the following
descriptions assume unbounded integer arithmetic.

Internally, SWI-Prolog has three integer representations. Small integers
(defined by the Prolog flag \prologflag{max_tagged_integer}) are encoded
directly. Larger integers are represented as 64-bit values on the
global stack. Integers that do not fit in 64 bits are represented as
serialised GNU MPZ structures on the global stack.

    \item [rational number]
Rational numbers ($Q$) are quotients of two integers. Rational
arithmetic is only provided if GMP is used (see above). Rational numbers
are currently not supported by a Prolog type. They are represented by
the compound term \term{rdiv}{N,M}. Rational numbers that are returned
from \index{is/2}\predref{is}{2} are \emph{canonical}, which means $M$ is positive and $N$ and
$M$ have no common divisors. Rational numbers are introduced in the
computation using the \funcref{rational}{1}, \funcref{rationalize}{1} or
the \funcref{rdiv}{2} (rational division) function. Using the same
functor for rational division and for representing rational numbers allows
for passing rational numbers between computations as well as for using \index{format/3}\predref{format}{3}
for printing.

In the long term, it is likely that rational numbers will become
\emph{atomic} as well as a subtype of \emph{number}.  User code that
creates or inspects the \term{rdiv}{M,N} terms will not be portable
to future versions.  Rationals are created using one of the functions
mentioned above and inspected using \index{rational/3}\predref{rational}{3}.

    \item [float]
Floating point numbers are represented using the C type \const{double}.
On most of today's platforms these are 64-bit IEEE floating point numbers.
\end{itemlist}

Arithmetic functions that require integer arguments accept, in addition
to integers, rational numbers with (canonical) denominator `1'. If the
required argument is a float the argument is converted to float. Note
that conversion of integers to floating point numbers may raise an
overflow exception. In all other cases, arguments are converted to the
same type using the order below.

\begin{quote}
integer $\rightarrow$ rational number $\rightarrow$ floating point number
\end{quote}


\subsubsection{Rational number examples}	\label{sec:rational}

The use of rational numbers with unbounded integers allows for exact
integer or \jargon{fixed point} arithmetic under addition,
subtraction, multiplication and division.  To exploit rational
arithmetic \funcref{rdiv}{2} should be used instead of `/' and floating
point numbers must be converted to rational using \funcref{rational}{1}.
Omitting the \funcref{rational}{1} on floats will convert a rational
operand to float and continue the arithmetic using floating point
numbers. Here are some examples.

\begin{center}
\begin{tabular}{ll}
A is 2 rdiv 6			& A = 1 rdiv 3 \\
A is 4 rdiv 3 + 1		& A = 7 rdiv 3 \\
A is 4 rdiv 3 + 1.5		& A = 2.83333 \\
A is 4 rdiv 3 + rational(1.5)	& A = 17 rdiv 6 \\
\end{tabular}
\end{center}

Note that floats cannot represent all decimal numbers exactly.  The
function \funcref{rational}{1} creates an \emph{exact} equivalent of the
float, while \funcref{rationalize}{1} creates a rational number that is
within the float rounding error from the original float. Please check
the documentation of these functions for details and examples.

Rational numbers can be printed as decimal numbers with arbitrary
precision using the \index{format/3}\predref{format}{3} floating point conversion:

\begin{code}
?- A is 4 rdiv 3 + rational(1.5),
   format('~50f~n', [A]).
2.83333333333333333333333333333333333333333333333333

A = 17 rdiv 6
\end{code}

\noindent
\subsubsection{Arithmetic Functions}	\label{sec:functions}

Arithmetic functions are terms which are evaluated by the arithmetic
predicates described in \secref{arithpreds}. There are four types of
arguments to functions:

\begin{center}\begin{tabular}{lp{4in}}
\arg{Expr}	& Arbitrary expression, returning either a floating
		  point value or an integer. \\
\arg{IntExpr}   & Arbitrary expression that must evaluate to
                  an integer. \\
\arg{RatExpr}   & Arbitrary expression that must evaluate to
                  a rational number. \\
\arg{FloatExpr} & Arbitrary expression that must evaluate to
                  a floating point.
\end{tabular}\end{center}

For systems using bounded integer arithmetic (default is unbounded,
see \secref{artypes} for details), integer operations that would cause
overflow automatically convert to floating point arithmetic.

SWI-Prolog provides many extensions to the set of floating point
functions defined by the ISO standard. The current policy is to provide
such functions on `as-needed' basis if the function is widely supported
elsewhere and notably if it is part of the
\href{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf}{C99}
mathematical library.  In addition, we try to maintain compatibility
with \href{http://www.dcc.fc.up.pt/~vsc/Yap/}{YAP}.

\begin{description}
    \prefixfunction[ISO]{\Sminus}{+Expr}
$\arg{Result} = -\arg{Expr}$

    \prefixfunction[ISO]{\Splus}{+Expr}
$\arg{Result} = \arg{Expr}$.  Note that if \chr{\Splus} is followed by a number,
the parser discards the \chr{\Splus}.  I.e.\ \verb$?- integer(+1)$ succeeds.

    \infixfunction[ISO]{\Splus}{+Expr1}{+Expr2}
$\arg{Result} = \arg{Expr1} + \arg{Expr2}$

    \infixfunction[ISO]{\Sminus}{+Expr1}{+Expr2}
$\arg{Result} = \arg{Expr1} - \arg{Expr2}$

    \infixfunction[ISO]{\Stimes}{+Expr1}{+Expr2}
$\arg{Result} = \arg{Expr1} \times \arg{Expr2}$

    \infixfunction[ISO]{\Sdiv}{+Expr1}{+Expr2}
$\arg{Result} = \frac{\arg{Expr1}}{\arg{Expr2}}$.
If the flag \prologflag{iso} is \const{true}, both arguments are converted
to float and the return value is a float. Otherwise (default), if both
arguments are integers the operation returns an integer if the division
is exact. If at least one of the arguments is rational and the other
argument is integer, the operation returns a rational number. In all
other cases the return value is a float.  See also \funcref{\Sidiv}{2}
and \funcref{rdiv}{2}.

    \infixfunction[ISO]{mod}{+IntExpr1}{+IntExpr2}
Modulo, defined as \mbox{\arg{Result} = \arg{IntExpr1} - (\arg{IntExpr1}
div \arg{IntExpr2}) $\times$ \arg{IntExpr2}}, where \const{div} is
\jargon{floored} division.

    \infixfunction[ISO]{rem}{+IntExpr1}{+IntExpr2}
Remainder of integer division.  Behaves as if defined by
\mbox{\arg{Result} is \arg{IntExpr1} -
(\arg{IntExpr1} // \arg{IntExpr2}) $\times$ \arg{IntExpr2}}

    \infixfunction[ISO]{\Sidiv}{+IntExpr1}{+IntExpr2}
Integer division, defined as \mbox{\arg{Result} is
$rnd_I$(\arg{Expr1}/\arg{Expr2})}. The function $rnd_I$ is the default
rounding used by the C compiler and available through the Prolog flag
\prologflag{integer_rounding_function}. In the C99 standard, C-rounding
is defined as \const{towards_zero}.\footnote{Future versions might
guarantee rounding towards zero.}

    \function[ISO]{div}{2}{+IntExpr1, +IntExpr2}
Integer division, defined as \mbox{\arg{Result} is
(\arg{IntExpr1} - \arg{IntExpr1} $mod$ \arg{IntExpr2}) // \arg{IntExpr2}}.
In other words, this is integer division that rounds towards -infinity.
This function guarantees behaviour that is consistent with
\funcref{mod}{2}, i.e., the following holds for every pair of integers
$X,Y$ where \verb$Y =\= 0$.

\begin{code}
        Q is div(X, Y),
        M is mod(X, Y),
        X =:= Y*Q+M.
\end{code}

\noindent
    \infixfunction{rdiv}{+RatExpr}{+RatExpr}
Rational number division. This function is only available if
SWI-Prolog has been compiled with rational number support. See
\secref{rational} for details.

    \infixfunction{gcd}{+IntExpr1}{+IntExpr2}
Result is the greatest common divisor of \arg{IntExpr1}, \arg{IntExpr2}.

    \function[ISO]{abs}{1}{+Expr}
Evaluate \arg{Expr} and return the absolute value of it.

    \function[ISO]{sign}{1}{+Expr}
Evaluate to -1 if $\arg{Expr} < 0$, 1 if $\arg{Expr} > 0$ and 0 if
$\arg{Expr} = 0$.  If \arg{Expr} evaluates to a float, the return value
is a float (e.g., -1.0, 0.0 or 1.0). In particular, note that sign(-0.0)
evaluates to 0.0.  See also \funcref{copysign}{2}

    \function[ISO]{copysign}{2}{+Expr1, +Expr2}
Evaluate to \arg{X}, where the absolute value of \arg{X} equals the
absolute value of \arg{Expr1} and the sign of \arg{X} matches the sign
of \arg{Expr2}. This function is based on copysign() from C99, which
works on double precision floats and deals with handling the sign of
special floating point values such as -0.0. Our implementation follows
C99 if both arguments are floats.  Otherwise, \funcref{copysign}{2}
evaluates to \arg{Expr1} if the sign of both expressions matches or
-\arg{Expr1} if the signs do not match.  Here, we use the extended
notion of signs for floating point numbers, where the sign of -0.0
and other special floats is negative.

    \function[ISO]{max}{2}{+Expr1, +Expr2}
Evaluate to the larger of \arg{Expr1} and \arg{Expr2}.  Both
arguments are compared after converting to the same type, but the
return value is in the original type.  For example, max(2.5, 3) compares
the two values after converting to float, but returns the integer 3.

    \function[ISO]{min}{2}{+Expr1, +Expr2}
Evaluate to the smaller of \arg{Expr1} and \arg{Expr2}. See
\funcref{max}{2} for a description of type handling.

    \function{\Sdot}{2}{+Int, []}
A list of one element evaluates to the element. This implies \exam{"a"}
evaluates to the character code of the letter `a' (97) using the
traditional mapping of double quoted string to a list of character
codes. Arithmetic evaluation also translates a string object (see
\secref{strings}) of one character length into the character code for
that character. This implies that expression \exam{"a"} also works of
the Prolog flag \prologflag{double_quotes} is set to \const{string}. The
recommended way to specify the character code of the letter `a' is
\exam{0'a}.

    \function{random}{1}{+IntExpr}
Evaluate to a random integer \arg{i} for which $0 \leq i <
\arg{IntExpr}$. The system has two implementations. If it is compiled
with support for unbounded arithmetic (default) it uses the GMP library
random functions. In this case, each thread keeps its own random state.
The default algorithm is the \jargon{Mersenne Twister} algorithm. The
seed is set when the first random number in a thread is generated. If
available, it is set from \file{/dev/random}.\footnote{On Windows the
state is initialised from CryptGenRandom().} Otherwise it is set from
the system clock. If unbounded arithmetic is not supported, random
numbers are shared between threads and the seed is initialised from the
clock when SWI-Prolog was started. The predicate \index{set_random/1}\predref{set_random}{1} can be
used to control the random number generator.

\textbf{Warning!} Although properly seeded (if supported on the OS), the
Mersenne Twister algorithm does \emph{not} produce cryptographically
secure random numbers. To generate cryptographically secure random
numbers, use \index{crypto_n_random_bytes/2}\predref{crypto_n_random_bytes}{2} from library \pllib{crypto}
provided by the \const{ssl} package.

    \function{random_float}{0}{}
Evaluate to a random float $I$ for which $0.0 < i < 1.0$. This function
shares the random state with \funcref{random}{1}. All remarks with the
function \funcref{random}{1} also apply for \funcref{random_float}{0}.
Note that both sides of the domain are \jargon{open}. This avoids
evaluation errors on, e.g., \funcref{log}{1} or \funcref{\Sdiv}{2} while no
practical application can expect 0.0.\footnote{Richard O'Keefe said:
``If you \emph{are} generating IEEE doubles with the claimed
uniformity, then 0 has a 1 in $2^{53} = 1 in 9,007,199,254,740,992$
chance of turning up. No program that expects [0.0,1.0) is going to be
surprised when 0.0 fails to turn up in a few millions of millions of
trials, now is it? But a program that expects (0.0,1.0) could be
devastated if 0.0 did turn up.''}

    \function[ISO]{round}{1}{+Expr}
Evaluate \arg{Expr} and round the result to the nearest integer.
According to ISO, \funcref{round}{1} is defined as
\term{floor}{Expr+1/2}, i.e., rounding \emph{down}.  This is an
unconventional choice under which the relation
\verb$round(Expr) == -round(-Expr)$ does not hold.  SWI-Prolog
rounds \emph{outward}, e.g., \exam{round(1.5) =:= 2} and
\exam{round(-1.5) =:= -2}.

    \function{integer}{1}{+Expr}
Same as \funcref{round}{1} (backward compatibility).

    \function[ISO]{float}{1}{+Expr}
Translate the result to a floating point number.  Normally, Prolog will
use integers whenever possible.  When used around the 2nd argument of
\index{is/2}\predref{is}{2}, the result will be returned as a floating point number.  In other
contexts, the operation has no effect.

    \function{rational}{1}{+Expr}
Convert the \arg{Expr} to a rational number or integer.  The function
returns the input on integers and rational numbers.  For floating point
numbers, the returned rational number \emph{exactly} represents the
float.  As floats cannot exactly represent all decimal numbers the
results may be surprising.  In the examples below, doubles can
represent 0.25 and the result is as expected, in contrast to the
result of \term{rational}{0.1}. The function \funcref{rationalize}{1}
remedies this. See \secref{rational} for more information on rational
number support.

\begin{code}
?- A is rational(0.25).

A is 1 rdiv 4
?- A is rational(0.1).
A = 3602879701896397 rdiv 36028797018963968
\end{code}

\noindent
    \function{rationalize}{1}{+Expr}
Convert the \arg{Expr} to a rational number or integer.  The function
is similar to \funcref{rational}{1}, but the result is only accurate
within the rounding error of floating point numbers, generally producing
a much smaller denominator.%
	\footnote{The names \funcref{rational}{1} and
	\funcref{rationalize}{1} as well as their semantics are inspired
	by Common Lisp.}

\begin{code}
?- A is rationalize(0.25).

A = 1 rdiv 4
?- A is rationalize(0.1).

A = 1 rdiv 10
\end{code}

\noindent
    \function[ISO]{float_fractional_part}{1}{+Expr}
Fractional part of a floating point number.  Negative if \arg{Expr} is
negative, rational if \arg{Expr} is rational and 0 if \arg{Expr} is
integer.  The following relation is always true:
$X is float_fractional_part(X) + float_integer_part(X)$.

    \function[ISO]{float_integer_part}{1}{+Expr}
Integer part of floating point number. Negative if \arg{Expr} is
negative, \arg{Expr} if \arg{Expr} is integer.

    \function[ISO]{truncate}{1}{+Expr}
Truncate \arg{Expr} to an integer.  If $\arg{Expr} \geq 0$ this is the
same as \term{floor}{Expr}.  For $\arg{Expr} < 0$ this is the same as
\term{ceil}{Expr}.  That is, \index{truncate/1}\predref{truncate}{1} rounds towards zero.

    \function[ISO]{floor}{1}{+Expr}
Evaluate \arg{Expr} and return the largest integer smaller or equal
to the result of the evaluation.

    \function[ISO]{ceiling}{1}{+Expr}
Evaluate \arg{Expr} and return the smallest integer larger or equal
to the result of the evaluation.

    \function{ceil}{1}{+Expr}
Same as \funcref{ceiling}{1} (backward compatibility).

    \infixfunction[ISO]{\Srshift}{+IntExpr1}{+IntExpr2}
Bitwise shift \arg{IntExpr1} by \arg{IntExpr2} bits to the right.  The
operation performs \jargon{arithmetic shift}, which implies that the
inserted most significant bits are copies of the original most
significant bits.

    \infixfunction[ISO]{\Slshift}{+IntExpr1}{+IntExpr2}
Bitwise shift \arg{IntExpr1} by \arg{IntExpr2} bits to the left.

    \infixfunction[ISO]{\Sor}{+IntExpr1}{+IntExpr2}
Bitwise `or' \arg{IntExpr1} and \arg{IntExpr2}.

    \infixfunction[ISO]{\Sand}{+IntExpr1}{+IntExpr2}
Bitwise `and' \arg{IntExpr1} and \arg{IntExpr2}.

    \infixfunction[ISO]{xor}{+IntExpr1}{+IntExpr2}
Bitwise `exclusive or' \arg{IntExpr1} and \arg{IntExpr2}.

    \prefixfunction[ISO]{\Sneg}{+IntExpr}
Bitwise negation.  The returned value is the one's complement of
\arg{IntExpr}.

    \function[ISO]{sqrt}{1}{+Expr}
$\arg{Result} = \sqrt{\arg{Expr}}$
    \function[ISO]{sin}{1}{+Expr}
$\arg{Result} = \sin{\arg{Expr}}$. \arg{Expr} is the angle in radians.
    \function[ISO]{cos}{1}{+Expr}
$\arg{Result} = \cos{\arg{Expr}}$. \arg{Expr} is the angle in radians.
    \function[ISO]{tan}{1}{+Expr}
$\arg{Result} = \tan{\arg{Expr}}$. \arg{Expr} is the angle in radians.
    \function[ISO]{asin}{1}{+Expr}
$\arg{Result} = \arcsin{\arg{Expr}}$. \arg{Result} is the angle in radians.
    \function[ISO]{acos}{1}{+Expr}
$\arg{Result} = \arccos{\arg{Expr}}$. \arg{Result} is the angle in radians.
    \function[ISO]{atan}{1}{+Expr}
$\arg{Result} = \arctan{\arg{Expr}}$. \arg{Result} is the angle in radians.
    \function[ISO]{atan2}{2}{+YExpr, +XExpr}
$\arg{Result} = \arctan{\frac{\arg{YExpr}}{\arg{XExpr}}}$. \arg{Result} is the
angle in radians.  The return value is in the range $[-\pi\ldots\pi]$.
Used to convert between rectangular and polar coordinate system.

Note that the ISO Prolog standard demands \term{atan2}{0.0,0.0} to raise
an evaluation error, whereas the C99 and POSIX standards demand this to
evaluate to 0.0.  SWI-Prolog follows C99 and POSIX.
    \function{atan}{2}{+YExpr, +XExpr}
Same as \funcref{atan2}{2} (backward compatibility).

    \function{sinh}{1}{+Expr}
$\arg{Result} = \sinh{\arg{Expr}}$. The hyperbolic sine of $X$ is
defined as $\frac{\pow{e}{X} - \pow{e}{-X}}{2}$.
    \function{cosh}{1}{+Expr}
$\arg{Result} = \cosh{\arg{Expr}}$. The hyperbolic cosine of $X$ is
defined as $\frac{\pow{e}{X} + \pow{e}{-X}}{2}$.
    \function{tanh}{1}{+Expr}
$\arg{Result} = \tanh{\arg{Expr}}$. The hyperbolic tangent of $X$ is
defined as $\frac{\sinh{X}}{\cosh{X}}$.

    \function{asinh}{1}{+Expr}
$\arg{Result} = arcsinh(\arg{Expr})$ (inverse hyperbolic sine).
    \function{acosh}{1}{+Expr}
$\arg{Result} = arccosh(\arg{Expr})$ (inverse hyperbolic cosine).
    \function{atanh}{1}{+Expr}
$\arg{Result} = arctanh(\arg{Expr})$. (inverse hyperbolic tangent).

    \function[ISO]{log}{1}{+Expr}
Natural logarithm.  $\arg{Result} = \ln{\arg{Expr}}$
    \function{log10}{1}{+Expr}
Base-10 logarithm.  $\arg{Result} = \lg{\arg{Expr}}$
    \function[ISO]{exp}{1}{+Expr}
$\arg{Result} = \pow{e}{\arg{Expr}}$

    \infixfunction[ISO]{\Spow}{+Expr1}{+Expr2}
$\arg{Result} = \pow{\arg{Expr1}}{\arg{Expr2}}$. The result is a float,
unless SWI-Prolog is compiled with unbounded integer support and the
inputs are integers and produce an integer result. The integer
expressions $\pow{0}{I}$, $\pow{1}{I}$ and $\pow{-1}{I}$ are guaranteed
to work for any integer $I$. Other integer base values generate a
\const{resource} error if the result does not fit in memory.

The ISO standard demands a float result for all inputs and introduces
\funcref{\Shat}{2} for integer exponentiation. The function
\funcref{float}{1} can be used on one or both arguments to force a
floating point result. Note that casting the \emph{input} result in a
floating point computation, while casting the \emph{output} performs
integer exponentiation followed by a conversion to float.

    \infixfunction[ISO]{\Shat}{+Expr1}{+Expr2}
In SWI-Prolog, \funcref{\Shat}{2} is equivalent to \funcref{\Spow}{2}. The ISO
version	is similar, except that it produces a evaluation error if both
\arg{Expr1} and \arg{Expr2} are integers and the result is not an
integer.  The table below illustrates the behaviour of the exponentiation
functions in ISO and SWI.

\begin{center}
\begin{tabular}{|ll|l|l|l|}
\hline
\arg{Expr1}   & \arg{Expr2}  & Function &  SWI          & ISO \\
\hline
Int	      & Int	     & \funcref{\Spow}{2} &  Int or Float & Float \\
Int	      & Float	     & \funcref{\Spow}{2} &  Float        & Float \\
Rational      & Int	     & \funcref{\Spow}{2} &  Rational     & - \\
Float	      & Int	     & \funcref{\Spow}{2} &  Float        & Float \\
Float         & Float        & \funcref{\Spow}{2} &  Float        & Float \\
\hline
Int	      & Int	     & \funcref{\Shat}{2}  &  Int or Float & Int or error \\
Int	      & Float	     & \funcref{\Shat}{2}  &  Float        & Float \\
Rational      & Int          & \funcref{\Shat}{2}  &  Rational     & - \\
Float	      & Int	     & \funcref{\Shat}{2}  &  Float        & Float \\
Float         & Float        & \funcref{\Shat}{2}  &  Float        & Float \\
\hline
\end{tabular}
\end{center}

    \function{powm}{3}{+IntExprBase, +IntExprExp, +IntExprMod}
$\arg{Result} = (\pow{\arg{IntExprBase}}{\arg{IntExprExp}})
 \mbox{ modulo } \arg{IntExprMod}$.
Only available when compiled with unbounded integer support. This
formula is required for Diffie-Hellman key-exchange, a technique where
two parties can establish a secret key over a public network.
\arg{IntExprBase} and \arg{IntExprExp} must be non-negative ($>=0$),
\arg{IntExprMod} must be positive ($>0$).\footnote{The underlying GMP
mpz_powm() function allows negative values under some conditions.  As
the conditions are expensive to pre-compute, error handling from GMP is
non-trivial and negative values are not needed for Diffie-Hellman
key-exchange we do not support these.}

    \function{lgamma}{1}{+Expr}
Return the natural logarithm of the absolute value of the Gamma
function.\footnote{Some interfaces also provide the sign of the Gamma
function. We canot do that in an arithmetic function. Future versions
may provide a \emph{predicate} \nopredref{lgamma}{3} that returns both
the value and the sign.}

    \function{erf}{1}{+Expr}
\href{https://en.wikipedia.org/wiki/Error_function}{Wikipedia}: ``In
mathematics, the error function (also called the Gauss error function)
is a special function (non-elementary) of sigmoid shape which occurs in
probability, statistics and partial differential equations.''

    \function{erfc}{1}{+Expr}
\href{https://en.wikipedia.org/wiki/Error_function}{Wikipedia}: ``The
complementary error function.''

    \function[ISO]{pi}{0}{}
Evaluate to the mathematical constant $\pi$ (3.14159\ldots).
    \function{e}{0}{}
Evaluate to the mathematical constant $e$ (2.71828\ldots).
    \function{epsilon}{0}{}
Evaluate to the difference between the float 1.0 and
the first larger floating point number.
    \function{inf}{0}{}
Evaluate to positive infinity.  See \secref{floatsyntax}.  This value
can be negated using \funcref{\Sminus}{1}.
    \function{nan}{0}{}
Evaluate to \emph{Not a Number}.  See \secref{floatsyntax}.
    \function{cputime}{0}{}
Evaluate to a floating point number expressing the {\sc cpu} time (in seconds)
used by Prolog up till now. See also \index{statistics/2}\predref{statistics}{2} and \index{time/1}\predref{time}{1}.

    \function{eval}{1}{+Expr}
Evaluate \arg{Expr}. Although ISO standard dictates that `$A$=1+2, $B$ is
$A$' works and unifies $B$ to 3, it is widely felt that source level
variables in arithmetic expressions should have been limited to numbers.
In this view the eval function can be used to evaluate arbitrary
expressions.\footnote{The \funcref{eval}{1} function was first
introduced by ECLiPSe and is under consideration for YAP.}
\end{description}


\paragraph{Bitvector functions}

The functions below are not covered by the standard. The
\funcref{msb}{1} function also appears in hProlog and SICStus Prolog.
The \funcref{getbit}{2} function also appears in ECLiPSe, which also
provides \term{setbit}{Vector,Index} and \term{clrbit}{Vector,Index}.
The others are SWI-Prolog extensions that improve handling of
---unbounded--- integers as bit-vectors.

\begin{description}
    \function{msb}{1}{+IntExpr}
Return the largest integer $N$ such that \verb$(IntExpr >> N) /\ 1 =:= 1$.
This is the (zero-origin) index of the most significant 1 bit in the
value of \arg{IntExpr}, which must evaluate to a positive integer.
Errors for 0, negative integers, and non-integers.

    \function{lsb}{1}{+IntExpr}
Return the smallest integer $N$ such that \verb$(IntExpr >> N) /\ 1 =:= 1$.
This is the (zero-origin) index of the least significant 1 bit in the
value of \arg{IntExpr}, which must evaluate to a positive integer. Errors for
0, negative integers, and non-integers.

    \function{popcount}{1}{+IntExpr}
Return the number of 1s in the binary representation of the
non-negative integer \arg{IntExpr}.

    \function{getbit}{2}{+IntExprV, +IntExprI}
Evaluates to the bit value (0 or 1) of the \arg{IntExprI}-th bit of
\arg{IntExprV}. Both arguments must evaluate to non-negative integers.
The result is equivalent to \verb$(IntExprV >> IntExprI)/\1$, but more
efficient because materialization of the shifted value is avoided.
Future versions will optimise \verb$(IntExprV >> IntExprI)/\1$ to a call
to \funcref{getbit}{2}, providing both portability and
performance.\footnote{This issue was fiercely debated at the ISO
standard mailinglist. The name \textit{getbit} was selected for
compatibility with ECLiPSe, the only system providing this support.
Richard O'Keefe disliked the name and argued that efficient handling of
the above implementation is the best choice for this functionality.}
\end{description}


\section{Misc arithmetic support predicates}   \label{sec:miscarith}

\begin{description}
    \predicate{set_random}{1}{+Option}
Controls the random number generator accessible through the
\emph{functions} \funcref{random}{1} and \funcref{random_float}{0}. Note
that the library \pllib{random} provides an alternative API to the same
random primitives.

    \begin{description}
	\termitem{seed}{+Seed}
Set the seed of the random generator for this thread.  \arg{Seed} is
an integer or the atom \const{random}.  If \const{random}, repeat the
initialization procedure described with the function
\funcref{random}{1}. Here is an example:

\begin{code}
?- set_random(seed(111)), A is random(6).
A = 5.
?- set_random(seed(111)), A is random(6).
A = 5.
\end{code}

\noindent
	\termitem{state}{+State}
Set the generator to a state fetched using the state
property of \index{random_property/1}\predref{random_property}{1}.  Using other values may lead to undefined
behaviour.\footnote{The limitations of the underlying (GMP) library are
unknown, which makes it impossible to validate the \arg{State}.}
    \end{description}

    \predicate{random_property}{1}{?Option}
True when \arg{Option} is a current property of the random generator.
Currently, this predicate provides access to the state.  This predicate
is not present on systems where the state is inaccessible.

    \begin{description}
	\termitem{state}{-State}
Describes the current state of the random generator. State is a normal
Prolog term that can be asserted or written to a file. Applications
should make no other assumptions about its representation. The only
meaningful operation is to use as argument to \index{set_random/1}\predref{set_random}{1} using the
\term{state}{State} option.\bug{GMP provides no portable mechanism to
fetch and restore the state.  The current implementation works, but the
state depends on the platform.  I.e., it is generally not possible to
reuse the state with another version of GMP or on a CPU with different
datasizes or endian-ness.}
    \end{description}

    \predicate{current_arithmetic_function}{1}{?Head}
True when \arg{Head} is an evaluable function.  For example:

\begin{code}
?- current_arithmetic_function(sin(_)).
true.
\end{code}

\noindent
\end{description}


\section{Built-in list operations}		\label{sec:builtinlist}

Most list operations are defined in the library \pllib{lists} described
in \secref{lists}. Some that are implemented with more low-level
primitives are built-in and described here.


\begin{description}
    \predicate{is_list}{1}{+Term}
True if \arg{Term} is bound to the empty list (\exam{\Snil}) or a term with
functor `\const{'[|]'}'\footnote{The traditional list functor is the dot
(\const{'.'}). This is still the case of the command line option
\cmdlineoption{--traditional} is given. See also \secref{ext-lists}.}
and arity~2 and the second argument is a list.%
	\footnote{In versions before 5.0.1, \index{is_list/1}\predref{is_list}{1} just checked for
		  \const{\Snil} or \exam{[_|_]} and
		  \nopredref{proper_list}{1} had the role of the current
		  \index{is_list/1}\predref{is_list}{1}. The current definition conforms to the
		  de facto standard. Assuming proper coding standards,
		  there should only be very few cases where a
		  quick-and-dirty \index{is_list/1}\predref{is_list}{1} is a good choice. Richard
		  O'Keefe pointed at this issue.}
This predicate acts as if defined by the definition below on
\jargon{acyclic} terms. The implementation \emph{fails} safely if
\arg{Term} represents a cyclic list.

\begin{code}
is_list(X) :-
        var(X), !,
        fail.
is_list([]).
is_list([_|T]) :-
        is_list(T).
\end{code}

\noindent
    \predicate[semidet]{memberchk}{2}{?Elem, +List}
True when \arg{Elem} is an element of \arg{List}. This `chk' variant of
\index{member/2}\predref{member}{2} is semi deterministic and typically used to test membership of
a list. Raises a \const{type} error if scanning \arg{List} encounters a
non-list. Note that \index{memberchk/2}\predref{memberchk}{2} does \emph{not} perform a full list
typecheck. For example, \exam{memberchk(a, [a|b])} succeeds without
error. If \arg{List} is cyclic and \arg{Elem} is not a member of
\arg{List}, \index{memberchk/2}\predref{memberchk}{2} eventually raises a \const{type}
error.\footnote{\textit{Eventually} here means it will scan as many
elements as the longest list that may exist given the current stack
usage before raising the exception.}

    \predicate[ISO]{length}{2}{?List, ?Int}
True if \arg{Int} represents the number of elements in \arg{List}.
This predicate is a true relation and can be used to find the length of
a list or produce a list (holding variables) of length \arg{Int}.  The
predicate is non-deterministic, producing lists of increasing length if
\arg{List} is a \jargon{partial list} and \arg{Int} is unbound. It
raises errors if

    \begin{itemize}
    \item \arg{Int} is bound to a non-integer.
    \item \arg{Int} is a negative integer.
    \item \arg{List} is neither a list nor a partial list.  This
	  error condition includes cyclic lists.\footnote{ISO
	  demands failure here. We think an error is more appropriate.}
    \end{itemize}

This predicate fails if the tail of \arg{List} is equivalent to
\arg{Int} (e.g., \exam{length(L,L)}).\footnote{This is logically
correct. An exception would be more appropriate, but to our best
knowledge, current practice in Prolog does not describe a suitable
candidate exception term.}

    \predicate[ISO]{sort}{2}{+List, -Sorted}
True if \arg{Sorted} can be unified with a list holding the
elements of \arg{List}, sorted to the standard order of terms (see
\secref{compare}).  Duplicates are removed.  The implementation is
in C, using \jargon{natural merge sort}.%
	\footnote{Contributed by Richard O'Keefe.}
The \index{sort/2}\predref{sort}{2} predicate can sort a cyclic list, returning a non-cyclic
version with the same elements.

Note that \arg{List} may contain non-ground terms. If \arg{Sorted} is
unbound at call-time, for each consequtive pair of elements in
\arg{Sorted}, the relation \verb$E1 @< E2$ will hold. However, unifying
a variable in \arg{Sorted} may cause this relation to become invalid,
\emph{even} unifying a variable in \arg{Sorted} with another (older)
variable.  See also \secref{standardorder}.

    \predicate{sort}{4}{+Key, +Order, +List, -Sorted}
True when \arg{Sorted} can be unified with a list holding the element of
\arg{List}. \arg{Key} determines which part of each element in
\arg{List} is used for comparing two term and \arg{Order} describes the
relation between each set of consecutive elements in
\arg{Sorted}.\footnote{The definition of this predicate was established
after discussion with Joachim Schimpf from the ECLiPSe team. ECLiPSe
currently only accepts \const{\Slt}, \const{\Sle}, \const{\Sgt} and \const{\Sge}
for the \arg{Order} argument but this is likely to change. SWI-Prolog
extends this predicate to deal with dicts.}

If \arg{Key} is the integer zero (0), the entire term is used to compare
two elements. Using \arg{Key}=0 can be used to sort arbitrary Prolog
terms. Other values for \arg{Key} can only be used with compound terms
or dicts (see \secref{bidicts}). An integer key extracts the
\arg{Key}-th argument from a compound term. An integer or atom key
extracts the value from a dict that is associated with the given key. A
type_error is raised if the list element is of the wrong type and an
existence_error is raised if the compound has not enough argument or the
dict does not contain the requested key.

Deeper nested elements of structures can be selected by using a list
of keys for the \arg{Key} argument.

The \arg{Order} argument is described in the table below\footnote{For
compatibility with ECLiPSe, the values \const{\Slt}, \const{\Sle}, \const{\Sgt}
and \const{\Sge} are allowed as synonyms.}

\begin{center}
\begin{tabular}{lll}
Order & Ordering & Duplicate handling \\
\hline
\const{\Stlt}  & ascending  & remove \\
\const{\Stle} & ascending  & keep \\
\const{\Stgt}  & descending & remove \\
\const{\Stge} & descending & keep \\
\end{tabular}
\end{center}

The sort is \jargon{stable}, which implies that, if duplicates are kept,
the order of duplicates is not changed. If duplicates are removed, only
the first element of a sequence of duplicates appears in \arg{Sorted}.

This predicate supersedes most of the other sorting primitives, for
example:

\begin{code}
sort(List, Sorted)     :- sort(0,  @<, List,  Sorted).
msort(List, Sorted)    :- sort(0, @=<, List,  Sorted).
keysort(Pairs, Sorted) :- sort(1, @=<, Pairs, Sorted).
\end{code}

\noindent
The following example sorts a list of rows, for example resulting from
\index{csv_read_file/2}\predref{csv_read_file}{2}) ascending on the 3th column and descending on the 4th
column:

\begin{code}
    sort(4, @>=, Rows0, Rows1),
    sort(3, @=<, Rows1, Sorted).
\end{code}

\noindent
See also \index{sort/2}\predref{sort}{2} (ISO), \index{msort/2}\predref{msort}{2}, \index{keysort/2}\predref{keysort}{2}, \index{predsort/3}\predref{predsort}{3} and \index{order_by/2}\predref{order_by}{2}.

    \predicate{msort}{2}{+List, -Sorted}
Equivalent to \index{sort/2}\predref{sort}{2}, but does not remove duplicates. Raises a
\except{type_error} if \arg{List} is a cyclic list or not a list.

    \predicate[ISO]{keysort}{2}{+List, -Sorted}
Sort a list of \jargon{pairs}. \arg{List} must be a list of
\exam{\arg{Key}-\arg{Value}} pairs, terms whose principal functor is
(-)/2. \arg{List} is sorted on \arg{Key} according to the standard order
of terms (see \secref{standardorder}). Duplicates are \emph{not}
removed. Sorting is \jargon{stable} with regard to the order of the
\arg{Values}, i.e., the order of multiple elements that have the same
\arg{Key} is not changed.

The \index{keysort/2}\predref{keysort}{2} predicate is often used together with library
\pllib{pairs}. It can be used to sort lists on different or multiple
criteria. For example, the following predicates sorts a list of atoms
according to their length, maintaining the initial order for atoms that
have the same length.

\begin{code}
:- use_module(library(pairs)).

sort_atoms_by_length(Atoms, ByLength) :-
        map_list_to_pairs(atom_length, Atoms, Pairs),
        keysort(Pairs, Sorted),
        pairs_values(Sorted, ByLength).
\end{code}

\noindent
    \predicate{predsort}{3}{+Pred, +List, -Sorted}
Sorts similar to \index{sort/2}\predref{sort}{2}, but determines the order of two terms by
calling \mbox{\arg{Pred}(-\arg{Delta}, +\arg{E1}, +\arg{E2})}.  This
call must unify \arg{Delta} with one of \const{\Slt}, \const{\Sgt} or
\const{\Seq}.  If the built-in predicate \index{compare/3}\predref{compare}{3} is used, the result is
the same as \index{sort/2}\predref{sort}{2}.  See also \index{keysort/2}\predref{keysort}{2}.
\end{description}


\section{Finding all Solutions to a Goal}	\label{sec:allsolutions}

\begin{description}
    \predicate[ISO]{findall}{3}{+Template, :Goal, -Bag}
Create a list of the instantiations \arg{Template} gets successively on
backtracking over \arg{Goal} and unify the result with \arg{Bag}.
Succeeds with an empty list if \arg{Goal} has no solutions. \index{findall/3}\predref{findall}{3} is
equivalent to \index{bagof/3}\predref{bagof}{3} with all free variables bound with the existential
operator (\op{\Shat}), except that \index{bagof/3}\predref{bagof}{3} fails when \arg{Goal} has no
solutions.

    \predicate{findall}{4}{+Template, :Goal, -Bag, +Tail}
As \index{findall/3}\predref{findall}{3}, but returns the result as the difference list
\arg{Bag}-\arg{Tail}.   The 3-argument version is defined as

\begin{code}
findall(Templ, Goal, Bag) :-
        findall(Templ, Goal, Bag, [])
\end{code}

\noindent
    \predicate[nondet]{findnsols}{4}{+N, @Template, :Goal, -List}
    \nodescription
    \predicate[nondet]{findnsols}{5}{+N, @Template, :Goal, -List, ?Tail}
As \index{findall/3}\predref{findall}{3} and \index{findall/4}\predref{findall}{4}, but generates at most \arg{N} solutions. If
\arg{N} solutions are returned, this predicate succeeds with a choice
point if \arg{Goal} has a choice point. Backtracking returns the next
chunk of (at most) \arg{N} solutions. In addition to passing a plain
integer for \arg{N}, a term of the form \term{count}{N} is accepted.
Using \term{count}{N}, the size of the next chunk can be controlled
using \index{nb_setarg/3}\predref{nb_setarg}{3}. The non-deterministic behaviour used to implement the
\jargon{chunk} option in \pllib{pengines}. Based on Ciao, but the Ciao
version is deterministic. Portability can be achieved by wrapping the
goal in \index{once/1}\predref{once}{1}. Below are three examples. The first illustrates standard
chunking of answers.  The second illustrates that the chunk size can be
adjusted dynamically and the last illustrates that no choice point is
left if \arg{Goal} leaves no choice-point after the last solution.

\begin{code}
?- findnsols(5, I, between(1, 12, I), L).
L = [1, 2, 3, 4, 5] ;
L = [6, 7, 8, 9, 10] ;
L = [11, 12].

?- State = count(2),
   findnsols(State, I, between(1, 12, I), L),
   nb_setarg(1, State, 5).
State = count(5), L = [1, 2] ;
State = count(5), L = [3, 4, 5, 6, 7] ;
State = count(5), L = [8, 9, 10, 11, 12].

?- findnsols(4, I, between(1, 4, I), L).
L = [1, 2, 3, 4].
\end{code}

\noindent
    \predicate[ISO]{bagof}{3}{+Template, :Goal, -Bag}
Unify \arg{Bag} with the alternatives of \arg{Template}. If \arg{Goal}
has free variables besides the one sharing with \arg{Template}, \index{bagof/3}\predref{bagof}{3}
will backtrack over the alternatives of these free variables, unifying
\arg{Bag} with the corresponding alternatives of \arg{Template}. The
construct \exam{+\arg{Var}{\Shat}\arg{Goal}} tells \index{bagof/3}\predref{bagof}{3} not to bind
\arg{Var} in \arg{Goal}. \index{bagof/3}\predref{bagof}{3} fails if \arg{Goal} has no solutions.

The example below illustrates \index{bagof/3}\predref{bagof}{3} and the \op{\Shat} operator. The
variable bindings are printed together on one line to save paper.
\begin{code}
2 ?- listing(foo).
foo(a, b, c).
foo(a, b, d).
foo(b, c, e).
foo(b, c, f).
foo(c, c, g).
true.

3 ?- bagof(C, foo(A, B, C), Cs).
A = a, B = b, C = G308, Cs = [c, d] ;
A = b, B = c, C = G308, Cs = [e, f] ;
A = c, B = c, C = G308, Cs = [g].

4 ?- bagof(C, A^foo(A, B, C), Cs).
A = G324, B = b, C = G326, Cs = [c, d] ;
A = G324, B = c, C = G326, Cs = [e, f, g].

5 ?-
\end{code}

\noindent
    \predicate[ISO]{setof}{3}{+Template, +Goal, -Set}
Equivalent to \index{bagof/3}\predref{bagof}{3}, but sorts the result using \index{sort/2}\predref{sort}{2} to get a sorted
list of alternatives without duplicates.
\end{description}

\section{Forall}			\label{sec:forall2}

\begin{description}
    \predicate[semidet]{forall}{2}{:Cond, :Action}
For all alternative bindings of \arg{Cond}, \arg{Action} can be proven.
The example verifies that all arithmetic statements in the given list
are correct. It does not say which is wrong if one proves wrong.

\begin{code}
?- forall(member(Result = Formula, [2 = 1 + 1, 4 = 2 * 2]),
                 Result =:= Formula).
\end{code}

\noindent
The predicate \index{forall/2}\predref{forall}{2} is implemented as \verb$\+ ( Cond, \+ Action)$,
i.e., \textit{There is no instantiation of \arg{Cond} for which
\arg{Action} is false.}. The use of double negation implies that
\index{forall/2}\predref{forall}{2} \emph{does not change any variable bindings}. It proves a
relation. The \index{forall/2}\predref{forall}{2} control structure can be used for its
side-effects. E.g., the following asserts relations in a list into the
dynamic database:

\begin{code}
?- forall(member(Child-Parent, ChildPairs),
          assertz(child_of(Child, Parent))).
\end{code}

\noindent
Using \index{forall/2}\predref{forall}{2} as \term{forall}{Generator, SideEffect} is preferred over
the classical \jargon{failure driven loop} as shown below because it
makes it explicit which part of the construct is the generator and which
part creates the side effects. Also, unexpected failure of the side
effect causes the construct to fail. Failure makes it evident that there
is an issue with the code, while a failure driven loop would succeed
with an erroneous result.

\begin{code}
        ...,
        (   Generator,
            SideEffect,
            fail
        ;   true
        )
\end{code}

\noindent
If your intent is to create variable bindings, the \index{forall/2}\predref{forall}{2} control
structure is inadequate.  Possibly you are looking for \index{maplist/2}\predref{maplist}{2},
\index{findall/3}\predref{findall}{3} or \index{foreach/2}\predref{foreach}{2}.
\end{description}


\section{Formatted Write}		\label{sec:format}

The current version of SWI-Prolog provides two formatted write
predicates. The `writef' family (\index{writef/1}\predref{writef}{1}, \index{writef/2}\predref{writef}{2}, \index{swritef/3}\predref{swritef}{3}), is
compatible with Edinburgh C-Prolog and should be considered
\emph{deprecated}. The `format' family (\index{format/1}\predref{format}{1}, \index{format/2}\predref{format}{2}, \index{format/3}\predref{format}{3}),
was defined by Quintus Prolog and currently available in many Prolog
systems, although the details vary.

\subsection{Writef}
\label{sec:writef}

\begin{description}
    \predicate[deprecated]{writef}{1}{+Atom}
Equivalent to \exam{writef(Atom, []).}  See \index{writef/2}\predref{writef}{2} for details.
    \predicate[deprecated]{writef}{2}{+Format, +Arguments}
Formatted write.  \arg{Format} is an atom whose characters will be printed.
\arg{Format} may contain certain special character sequences which specify
certain formatting and substitution actions.  \arg{Arguments} provides
all the terms required to be output.

Escape sequences to generate a single special character:

\begin{center}
\begin{tabular}{|l|p{3.5in}|}
\hline
\fmtseq{\n}   &  Output a newline character (see also \index{nl/[0,1]}\predref{nl}{[0,1]}) \\
\fmtseq{\l}   &  Output a line separator (same as \fmtseq{\n}) \\
\fmtseq{\r}   &  Output a carriage return character (ASCII 13) \\
\fmtseq{\t}   &  Output the ASCII character TAB (9) \\
\fmtseq{\\}   &  The character \chr{\Sneg} is output \\
\fmtseq{\%}   &  The character \chr{\Spercent} is output \\
\fmtseq{\nnn} &  where \bnfmeta{nnn} is an integer (1-3 digits); the
		 character with code \bnfmeta{nnn} is output
		 (NB : \bnfmeta{nnn} is read as \strong{decimal}) \\
\hline
\end{tabular}
\end{center}

Note that \fmtseq{\l}, \fmtseq{\nnn} and \fmtseq{\\}
are interpreted differently when character escapes are in effect. See
\secref{charescapes}.

Escape sequences to include arguments from \arg{Arguments}. Each time a
\% escape sequence is found in \arg{Format} the next argument from \arg{Arguments} is formatted according to the specification.

\begin{center}
\begin{tabular}{|l|p{3.5in}|}
\hline
\fmtseq{%t}  &  \index{print/1}\predref{print}{1} the next item (mnemonic: term) \\
\fmtseq{%w}  &  \index{write/1}\predref{write}{1} the next item \\
\fmtseq{%q}  &  \index{writeq/1}\predref{writeq}{1} the next item \\
\fmtseq{%d}  &  Write the term, ignoring operators.  See also
		\index{write_term/2}\predref{write_term}{2}.  Mnemonic: old Edinburgh \index{display/1}\predref{display}{1} \\
\fmtseq{%p}  &  \index{print/1}\predref{print}{1} the next item (identical to \fmtseq{%t}) \\
\fmtseq{%n}  &  Put the next item as a character (i.e., it is
                a character code) \\
\fmtseq{%r}  &  Write the next item N times where N is the
                second item (an integer) \\
\fmtseq{%s}  &  Write the next item as a String (so it must
                be a list of characters) \\
\fmtseq{%f}  &  Perform a \index{ttyflush/0}\predref{ttyflush}{0} (no items used) \\
\fmtseq{%Nc} &  Write the next item Centered in $N$ columns \\
\fmtseq{%Nl} &  Write the next item Left justified in $N$ columns \\
\fmtseq{%Nr} &  Write the next item Right justified in $N$ columns.
                $N$ is a decimal number with at least one digit.
                The item must be an atom, integer, float or string. \\
\hline
\end{tabular}
\end{center}
    \predicate[deprecated]{swritef}{3}{-String, +Format, +Arguments}
Equivalent to \index{writef/2}\predref{writef}{2}, but ``writes'' the result on \arg{String} instead
of the current output stream. Example:
\begin{code}
?- swritef(S, '%15L%w', ['Hello', 'World']).

S = "Hello          World"
\end{code}

\noindent
    \predicate[deprecated]{swritef}{2}{-String, +Format}
Equivalent to \exam{swritef(String, Format, []).}
\end{description}

\subsection{Format}
\label{sec:format-predicates}

The format family of predicates is the most versatile and
portable\footnote{Unfortunately not covered by any standard.} way to
produce textual output.

\begin{description}
    \predicate{format}{1}{+Format}
Defined as `\exam{format(Format) :- format(Format, []).}'.  See
\index{format/2}\predref{format}{2} for details.

    \predicate{format}{2}{+Format, :Arguments}
\arg{Format} is an atom, list of character codes, or a Prolog string.
\arg{Arguments} provides the arguments required by the format
specification. If only one argument is required and this single argument
is not a list, the argument need not be put in a list. Otherwise the
arguments are put in a list.

Special sequences start with the tilde (\chr{\Stilde}), followed by an
optional numeric argument, optionally followed by a colon modifier (:),
\footnote{The colon modifiers is a SWI-Prolog extension, proposed by
Richard O'Keefe.} followed by a character describing the action to be
undertaken. A numeric argument is either a sequence of digits,
representing a positive decimal number, a sequence \exam{`\bnfmeta{character}},
representing the character code value of the character (only useful for
\fmtseq{~t}) or a asterisk (\chr{\Stimes}), in which case the numeric argument
is taken from the next argument of the argument list, which should be a
positive integer. E.g., the following three examples all pass 46
(\chr{\Sdot}) to \verb$~t$:

\begin{code}
?- format('~w ~46t ~w~72|~n', ['Title', 'Page']).
?- format('~w ~`.t ~w~72|~n', ['Title', 'Page']).
?- format('~w ~*t ~w~72|~n', ['Title', 46, 'Page']).
\end{code}

\noindent
Numeric conversion (\chr{d}, \chr{D}, \chr{e}, \chr{E}, \chr{f}, \chr{g}
and \chr{G}) accept an arithmetic expression as argument. This is
introduced to handle rational numbers transparently (see
\secref{rational}).  The floating point conversions allow for unlimited
precision for printing rational numbers in decimal form.  E.g., the
following will write as many 3's as you want by changing the `50'.

\begin{code}
?- format('~50f', [10 rdiv 3]).
3.33333333333333333333333333333333333333333333333333
\end{code}

\noindent
\begin{itemize}
    \fmtchar{\Stilde}
Output the tilde itself.

    \fmtchar{a}
Output the next argument, which must be an atom. This option is
equivalent to {\bf w}, except that it requires the argument to be an
atom.

    \fmtchar{c}
Interpret the next argument as a character code and add it to the
output. This argument must be a valid Unicode character code. Note that
the actually emitted bytes are defined by the character encoding of the
output stream and an exception may be raised if the output stream is not
capable of representing the requested Unicode character. See
\secref{encoding} for details.

    \fmtchar{d}
Output next argument as a decimal number.  It should be an integer.  If
a numeric argument is specified, a dot is inserted \arg{argument}
positions from the right (useful for doing fixed point arithmetic with
integers, such as handling amounts of money).

The colon modifier (e.g., \verb$~:d$) causes the number to be printed
according to the locale of the output stream.  See \secref{locale}.

    \fmtchar{D}
Same as {\bf d}, but makes large values easier to read by inserting a
comma every three digits left or right of the dot.  This is the same
as \verb$~:d$, but using the fixed English locale.

    \fmtchar{e}
Output next argument as a floating point number in exponential
notation.  The numeric argument specifies the precision.  Default is 6
digits.  Exact representation depends on the C library function
printf(). This function is invoked with the format
\mbox{\tt\%.\bnfmeta{precision}e}.

    \fmtchar{E}
Equivalent to {\bf e}, but outputs a capital E to indicate the exponent.

    \fmtchar{f}
Floating point in non-exponential notation. The numeric argument defines
the number of digits right of the decimal point.  If the colon modifier
(:) is used, the float is formatted using conventions from the current
locale, which may define the decimal point as well as grouping of digits
left of the decimal point.

    \fmtchar{g}
Floating point in {\bf e} or {\bf f} notation, whichever is shorter.

    \fmtchar{G}
Floating point in {\bf E} or {\bf f} notation, whichever is shorter.

    \fmtchar{i}
Ignore next argument of the argument list. Produces no output.

    \fmtchar{I}
Emit a decimal number using Prolog digit grouping (the underscore,
\verb$_$).  The argument describes the size of each digit group.
The default is 3.  See also \secref{digitgroupsyntax}.  For example:

\begin{code}
?- A is 1<<100, format('~10I', [A]).
1_2676506002_2822940149_6703205376
\end{code}

\noindent
    \fmtchar{k}
Give the next argument to \index{write_canonical/1}\predref{write_canonical}{1}.
    \fmtchar{n}
Output a newline character.
    \fmtchar{N}
Only output a newline if the last character output on this stream was
not a newline. Not properly implemented yet.
    \fmtchar{p}
Give the next argument to \index{print/1}\predref{print}{1}.
    \fmtchar{q}
Give the next argument to \index{writeq/1}\predref{writeq}{1}.

    \fmtchar{r}
Print integer in radix numeric argument notation. Thus
\fmtseq{~16r} prints its argument hexadecimal. The argument should
be in the range $[2, \ldots, 36]$. Lowercase letters are used for
digits above 9.  The colon modifier may be used to form locale-specific
digit groups.

    \fmtchar{R}
Same as {\bf r}, but uses uppercase letters for digits above 9.
    \fmtchar{s}
Output text from a list of character codes or a string (see \index{string/1}\predref{string}{1} and
\secref{strings}) from the next argument.\footnote{The \textbf{s}
modifier also accepts an atom for compatibility.  This is deprecated
due to the ambiguity of \texttt{\Snil}.}
    \fmtchar{@}
Interpret the next argument as a goal and execute it.  Output written
to the \const{current_output} stream is inserted at this place.  Goal
is called in the module calling \index{format/3}\predref{format}{3}.  This option is not present
in the original definition by Quintus, but supported by some other
Prolog systems.
    \fmtchar{t}
All remaining space between 2 tab stops is distributed equally over
\fmtseq{~t} statements between the tab stops. This space is padded
with spaces by default. If an argument is supplied, it is taken to be
the character code of the character used for padding. This can be
used to do left or right alignment, centering, distributing, etc. See
also \fmtseq{~|} and \fmtseq{~+} to set tab stops. A tab stop is
assumed at the start of each line.
    \fmtchar{\Sbar}
Set a tab stop on the current position. If an argument is supplied set
a tab stop on the position of that argument. This will cause all
\fmtseq{~t}'s to be distributed between the previous and this tab stop.

    \fmtchar{\Splus}
Set a tab stop (as \fmtseq{~|}) relative to the last tab stop or the
beginning of the line if no tab stops are set before the \fmtseq{~+}.
This constructs can be used to fill fields. The partial format sequence
below prints an integer right-aligned and padded with zeros in 6
columns.  The \ldots{} sequences in the example illustrate that the
integer is aligned in 6 columns regardless of the remainder of the
format specification.

\begin{code}
        format('...~|~`0t~d~6+...', [..., Integer, ...])
\end{code}

\noindent
    \fmtchar{w}
Give the next argument to \index{write/1}\predref{write}{1}.
    \fmtchar{W}
Give the next two arguments to \index{write_term/2}\predref{write_term}{2}.  For example,
\verb$format('~W', [Term, [numbervars(true)]])$.
This option is SWI-Prolog specific.
\end{itemize}

Example:

\begin{code}
simple_statistics :-
    <obtain statistics>         % left to the user
    format('~tStatistics~t~72|~n~n'),
    format('Runtime: ~`.t ~2f~34|  Inferences: ~`.t ~D~72|~n',
                                            [RunT, Inf]),
    ....
\end{code}

\noindent
will output

\begin{code}
                             Statistics

Runtime: .................. 3.45  Inferences: .......... 60,345
\end{code}

\noindent
    \predicate{format}{3}{+Output, +Format, :Arguments}
As \index{format/2}\predref{format}{2}, but write the output on the given \arg{Output}. The
de-facto standard only allows \arg{Output} to be a stream. The
SWI-Prolog implementation allows all valid arguments for
\index{with_output_to/2}\predref{with_output_to}{2}.%
	\footnote{Earlier versions defined \nopredref{sformat}{3}.
	These predicates have been moved to the library
	\pllib{backcomp}.}
For example:

\begin{code}
?- format(atom(A), '~D', [1000000]).
A = '1,000,000'
\end{code}

\noindent
\end{description}


\subsection{Programming Format}
\label{sec:format-hook}

\begin{description}
    \predicate{format_predicate}{2}{+Char, +Head}
If a sequence \fmtseq{~c} (tilde, followed by some character) is
found, the \index{format/3}\predref{format}{3} and friends first check whether the user has
defined a predicate to handle the format. If not, the built-in
formatting rules described above are used. \arg{Char} is either a
character code or a one-character atom, specifying the letter to
be (re)defined. \arg{Head} is a term, whose name and arity are used to
determine the predicate to call for the redefined formatting character.
The first argument to the predicate is the numeric argument of the
format command, or the atom \const{default} if no argument is specified.
The remaining arguments are filled from the argument list. The example
below defines \fmtseq{~T} to print a timestamp in ISO8601 format (see
\index{format_time/3}\predref{format_time}{3}).  The subsequent block illustrates a possible call.

\begin{code}
:- format_predicate('T', format_time(_Arg,_Time)).

format_time(_Arg, Stamp) :-
        must_be(number, Stamp),
        format_time(current_output, '%FT%T%z', Stamp).
\end{code}

\noindent
\begin{code}
?- get_time(Now),
   format('Now, it is ~T~n', [Now]).
Now, it is 2012-06-04T19:02:01+0200
Now = 1338829321.6620328.
\end{code}

\noindent
    \predicate{current_format_predicate}{2}{?Code, ?:Head}
True when \chr{\Stilde}\arg{Code} is handled by the user-defined predicate
specified by \arg{Head}.
\end{description}

\section{Global variables}			\label{sec:gvar}

Global variables are associations between names (atoms) and terms.
They differ in various ways from storing information using \index{assert/1}\predref{assert}{1}
or \index{recorda/3}\predref{recorda}{3}.

\begin{itemize}
    \item The value lives on the Prolog (global) stack.  This implies
          that lookup time is independent of the size of the term.
	  This is particularly interesting for large data structures
	  such as parsed XML documents or the CHR global constraint
	  store.

    \item They support both global assignment using \index{nb_setval/2}\predref{nb_setval}{2} and
          backtrackable assignment using \index{b_setval/2}\predref{b_setval}{2}.

    \item Only one value (which can be an arbitrary complex Prolog
	  term) can be associated to a variable at a time.

    \item Their value cannot be shared among threads.  Each thread
          has its own namespace and values for global variables.

    \item Currently global variables are scoped globally.  We may
          consider module scoping in future versions.
\end{itemize}

Both \index{b_setval/2}\predref{b_setval}{2} and \index{nb_setval/2}\predref{nb_setval}{2} implicitly create a variable if the
referenced name does not already refer to a variable.

Global variables may be initialised from directives to make them
available during the program lifetime, but some considerations are
necessary for saved states and threads. Saved states do not store global
variables, which implies they have to be declared with \index{initialization/1}\predref{initialization}{1}
to recreate them after loading the saved state.  Each thread has
its own set of global variables, starting with an empty set.  Using
\index{thread_initialization/1}\predref{thread_initialization}{1} to define a global variable it will be
defined, restored after reloading a saved state and created in all
threads that are created \emph{after} the registration.  Finally,
global variables can be initialised using the exception hook
\index{exception/3}\predref{exception}{3}.  The latter technique is used by CHR (see \chapref{chr}).


\begin{description}
    \predicate{b_setval}{2}{+Name, +Value}
Associate the term \arg{Value} with the atom \arg{Name} or replace
the currently associated value with \arg{Value}.  If \arg{Name} does
not refer to an existing global variable, a variable with initial value
\const{\Snil} is created (the empty list).  On backtracking the
assignment is reversed.

    \predicate{b_getval}{2}{+Name, -Value}
Get the value associated with the global variable \arg{Name} and unify
it with \arg{Value}. Note that this unification may further instantiate
the value of the global variable. If this is undesirable the normal
precautions (double negation or \index{copy_term/2}\predref{copy_term}{2}) must be taken. The
\index{b_getval/2}\predref{b_getval}{2} predicate generates errors if \arg{Name} is not an atom or
the requested variable does not exist.
\end{description}

\begin{description}
    \predicate{nb_setval}{2}{+Name, +Value}
Associates a copy of \arg{Value} created with \index{duplicate_term/2}\predref{duplicate_term}{2}
with the atom \arg{Name}.  Note that this can be used to set an
initial value other than \const{\Snil} prior to backtrackable assignment.

    \predicate{nb_getval}{2}{+Name, -Value}
The \index{nb_getval/2}\predref{nb_getval}{2} predicate is a synonym for \index{b_getval/2}\predref{b_getval}{2}, introduced for
compatibility and symmetry.  As most scenarios will use a particular
global variable using either non-backtrackable or backtrackable
assignment, using \index{nb_getval/2}\predref{nb_getval}{2} can be used to document that the
variable is non-backtrackable. Raises \term{existence_error}{variable,
Name} if the variable does not exist.  Alternatively, \index{nb_current/2}\predref{nb_current}{2} can
used to query a global variable.  This version \emph{fails} if the
variable does not exist rather than raising an exception.

    \predicate{nb_linkval}{2}{+Name, +Value}
Associates the term \arg{Value} with the atom \arg{Name} without copying
it. This is a fast special-purpose variation of \index{nb_setval/2}\predref{nb_setval}{2} intended for
expert users only because the semantics on backtracking to a point
before creating the link are poorly defined for compound terms. The
principal term is always left untouched, but backtracking behaviour on
arguments is undone if the original assignment was \jargon{trailed} and
left alone otherwise, which implies that the history that created the
term affects the behaviour on backtracking. Consider the
following example:

\begin{code}
demo_nb_linkval :-
        T = nice(N),
        (   N = world,
            nb_linkval(myvar, T),
            fail
        ;   nb_getval(myvar, V),
            writeln(V)
        ).
\end{code}

\noindent
    \predicate{nb_current}{2}{?Name, ?Value}
Enumerate all defined variables with their value. The order of
enumeration is undefined. Note that \index{nb_current/2}\predref{nb_current}{2} can be used as an
alternative for \index{nb_getval/2}\predref{nb_getval}{2} to request the value of a variable and fail
silently if the variable does not exists.

    \predicate{nb_delete}{1}{+Name}
Delete the named global variable.  Succeeds also if the named variable
does not exist.
\end{description}


\subsection{Compatibility of SWI-Prolog Global Variables}
\label{sec:gvars-compat}

Global variables have been introduced by various Prolog implementations
recently.  The implementation of them in SWI-Prolog is based on hProlog
by Bart Demoen. In discussion with Bart it was decided that the
semantics of hProlog \index{nb_setval/2}\predref{nb_setval}{2}, which is equivalent to \index{nb_linkval/2}\predref{nb_linkval}{2},
is not acceptable for normal Prolog users as the behaviour is influenced
by how built-in predicates that construct terms (\index{read/1}\predref{read}{1}, =../2, etc.) are
implemented.

GNU-Prolog provides a rich set of global variables, including arrays.
Arrays can be implemented easily in SWI-Prolog using \index{functor/3}\predref{functor}{3} and
\index{setarg/3}\predref{setarg}{3} due to the unrestricted arity of compound terms.

\section{Terminal Control}		\label{sec:tty}

The following predicates form a simple access mechanism to the Unix termcap
library to provide terminal-independent I/O for screen terminals. These
predicates are only available on Unix machines.  The SWI-Prolog Windows
console accepts the ANSI escape sequences.

\begin{description}
    \predicate{tty_get_capability}{3}{+Name, +Type, -Result}
Get the capability named \arg{Name} from the termcap library.  See
termcap(5) for the capability names. \arg{Type} specifies the type of
the expected result, and is one of \const{string}, \const{number} or
\const{bool}.  String results are returned as an atom, number results as
an integer, and bool results as the atom \const{on} or \const{off}.  If
an option cannot be found, this predicate fails silently.  The
results are only computed once. Successive queries on the same
capability are fast.
    \predicate{tty_goto}{2}{+X, +Y}
Goto position \mbox{(\arg{X}, \arg{Y})} on the screen.  Note that the predicates
\index{line_count/2}\predref{line_count}{2} and \index{line_position/2}\predref{line_position}{2} will not have a well-defined
behaviour while using this predicate.
    \predicate{tty_put}{2}{+Atom, +Lines}
Put an atom via the termcap library function tputs().  This function
decodes padding information in the strings returned by \index{tty_get_capability/3}\predref{tty_get_capability}{3}
and should be used to output these strings. \arg{Lines} is the
number of lines affected by the operation, or 1 if not applicable (as
in almost all cases).
    \predicate{tty_size}{2}{-Rows, -Columns}
Determine the size of the terminal.  Platforms:

\begin{description}
    \item[Unix]
If the system provides \jargon{ioctl} calls for this, these are
used and \index{tty_size/2}\predref{tty_size}{2} properly reflects the actual size after a user
resize of the window.   The \jargon{ioctl} is issued on teh file
descriptor associated with the \const{user_input} stream. As a fallback,
the system uses \index{tty_get_capability/3}\predref{tty_get_capability}{3} using \const{li} and \const{co}
capabilities. In this case the reported size reflects the size at the
first call and is not updated after a user-initiated resize of the
terminal.

    \item[Windows]
Getting the size of the terminal is provided for \program{swipl-win.exe}.
The requested value reflects the current size. For the
multithreaded version the console that is associated with the
\const{user_input} stream is used.
\end{description}
\end{description}

\section{Operating System Interaction}	\label{sec:system}

The predicates in this section provide basic access to the operating
system that has been part of the Prolog legacy tradition. Note that more
advanced access to low-level OS features is provided by several libaries
from the \const{clib} package, notably library \pllib{process},
\pllib{socket}, \pllib{unix} and \pllib{filesex}.


\begin{description}
    \predicate{shell}{1}{+Command}
Equivalent to `\exam{shell(Command, 0)}'.  See \index{shell/2}\predref{shell}{2} for details.

    \predicate{shell}{2}{+Command, -Status}
Execute \arg{Command} on the operating system. \arg{Command} is given to the
Bourne shell (/bin/sh). \arg{Status} is unified with the exit status of
the command.

On Windows, \index{shell/[1,2]}\predref{shell}{[1,2]} executes the command using the CreateProcess()
API and waits for the command to terminate. If the command ends with a
\chr{\&} sign, the command is handed to the WinExec() API, which does
not wait for the new task to terminate. See also \index{win_exec/2}\predref{win_exec}{2} and
\index{win_shell/2}\predref{win_shell}{2}. Please note that the CreateProcess() API does {\bf not}
imply the Windows command interpreter (\program{cmd.exe} and therefore
commands that are built in the command interpreter can only be activated
using the command interpreter. For example, a file can be compied using
the command below.

\begin{code}
?- shell('cmd.exe /C copy file1.txt file2.txt').
\end{code}

\noindent
Note that many of the operations that can be achieved using the shell
built-in commands can easily be achieved using Prolog primitives. See
\index{make_directory/1}\predref{make_directory}{1}, \index{delete_file/1}\predref{delete_file}{1}, \index{rename_file/2}\predref{rename_file}{2}, etc. The clib package
provides \pllib{filesex}, implementing various high level file
operations such as \index{copy_file/2}\predref{copy_file}{2}.  Using Prolog primitives instead of
shell commands improves the portability of your program.

The library \pllib{process} provides \index{process_create/3}\predref{process_create}{3} and several
related primitives that support more fine-grained interaction with
processes, including I/O redirection and management of asynchronous
processes.

    \predicate{getenv}{2}{+Name, -Value}
Get environment variable. Fails silently if the variable does not exist.
Please note that environment variable names are case-sensitive on Unix
systems and case-insensitive on Windows.

    \predicate{setenv}{2}{+Name, +Value}
Set an environment variable.  \arg{Name} and \arg{Value} must be
instantiated to atoms or integers.  The environment variable will be
passed to shell/[0-2] and can be requested using \index{getenv/2}\predref{getenv}{2}.  They also
influence \index{expand_file_name/2}\predref{expand_file_name}{2}.  Environment variables are shared between
threads.  Depending on the underlying C library, \index{setenv/2}\predref{setenv}{2} and \index{unsetenv/1}\predref{unsetenv}{1}
may not be thread-safe and may cause memory leaks.  Only changing the
environment once and before starting threads is safe in all versions
of SWI-Prolog.

    \predicate{unsetenv}{1}{+Name}
Remove an environment variable from the environment. Some systems lack
the underlying unsetenv() library function. On these systems \index{unsetenv/1}\predref{unsetenv}{1}
sets the variable to the empty string.

    \predicate{setlocale}{3}{+Category, -Old, +New}
Set/Query the \jargon{locale} setting which tells the C library how to
interpret text files, write numbers, dates, etc. Category is one of
\const{all}, \const{collate}, \const{ctype}, \const{messages},
\const{monetary}, \const{numeric} or \const{time}. For details, please
consult the C library locale documentation. See also \secref{encoding}.
Please note that the locale is shared between all threads and
thread-safe usage of \index{setlocale/3}\predref{setlocale}{3} is in general not possible. Do locale
operations before starting threads or thoroughly study threading aspects
of locale support in your environment before using in multithreaded
environments. Locale settings are used by \index{format_time/3}\predref{format_time}{3}, \index{collation_key/2}\predref{collation_key}{2}
and \index{locale_sort/2}\predref{locale_sort}{2}.

    \predicate{unix}{1}{+Command}
This predicate comes from the Quintus compatibility library and provides
a partial implementation thereof.  It provides access to some operating
system features and unlike the name suggests, is not operating system
specific.  Defined \arg{Command}'s are below.

\begin{description}
    \termitem{system}{+Command}
Equivalent to calling \index{shell/1}\predref{shell}{1}.  Use for compatibility only.

    \termitem{shell}{+Command}
Equivalent to calling \index{shell/1}\predref{shell}{1}.  Use for compatibility only.

    \termitem{shell}{}
Equivalent to calling \index{shell/0}\predref{shell}{0}.  Use for compatibility only.

    \termitem{cd}{}
Equivalent to calling \index{working_directory/2}\predref{working_directory}{2} to the expansion (see
\index{expand_file_name/2}\predref{expand_file_name}{2}) of \chr{\Stilde}.  For compatibility only.

    \termitem{cd}{+Directory}
Equivalent to calling \index{working_directory/2}\predref{working_directory}{2}. Use for compatibility
only.

    \termitem{argv}{-Argv}
Unify \arg{Argv} with the list of command line arguments provided to
this Prolog run. Please note that Prolog system arguments and
application arguments are separated by \const{--}.  Integer arguments
are passed as Prolog integers, float arguments and Prolog floating
point numbers and all other arguments as Prolog atoms.  New applications
should use the Prolog flag \prologflag{argv}.  See also the Prolog flag
\prologflag{argv}.
\end{description}
\end{description}

\subsection{Windows-specific Operating System Interaction}
\label{sec:winsystem}

The predicates in this section are only available on the Windows version
of SWI-Prolog. Their use is discouraged if there are portably
alternatives. For example, \index{win_exec/2}\predref{win_exec}{2} and \index{win_shell/2}\predref{win_shell}{2} can often be
replaced by the more portable \index{shell/2}\predref{shell}{2} or the more powerful
\index{process_create/3}\predref{process_create}{3}.

\begin{description}
    \predicate{win_exec}{2}{+Command, +Show}
Windows only. Spawns a Windows task without waiting for its
completion.  \arg{Show} is one of the Win32 \const{SW_*} constants
written in lowercase without the \const{SW_*}:
\const{hide}
\const{maximize}
\const{minimize}
\const{restore}
\const{show}
\const{showdefault}
\const{showmaximized}
\const{showminimized}
\const{showminnoactive}
\const{showna}
\const{shownoactive}
\const{shownormal}.
In addition, \const{iconic} is a synonym for \const{minimize} and
\const{normal} for \const{shownormal}.

    \predicate{win_shell}{3}{+Operation, +File, +Show}
Windows only. Opens the document \arg{File} using the Windows shell
rules for doing so. \arg{Operation} is one of \const{open},
\const{print} or \const{explore} or another operation registered with
the shell for the given document type. On modern systems it is also
possible to pass a \index{URL}URL as \arg{File}, opening the URL in
Windows default browser. This call interfaces to the Win32 API
ShellExecute(). The \arg{Show} argument determines the initial state of
the opened window (if any). See \index{win_exec/2}\predref{win_exec}{2} for defined values.

    \predicate{win_shell}{2}{+Operation, +File}
Same as \term{win_shell}{Operation, File, normal}

    \predicate{win_registry_get_value}{3}{+Key, +Name, -Value}
Windows only. Fetches the value of a Windows registry key. \arg{Key} is
an atom formed as a path name describing the desired registry key.
\arg{Name} is the desired attribute name of the key. \arg{Value} is
unified with the value. If the value is of type \type{DWORD}, the value
is returned as an integer. If the value is a string, it is returned as a
Prolog atom. Other types are currently not supported. The default `root'
is \const{HKEY_CURRENT_USER}. Other roots can be specified explicitly as
\const{HKEY_CLASSES_ROOT}, \const{HKEY_CURRENT_USER},
\const{HKEY_LOCAL_MACHINE} or \const{HKEY_USERS}. The example below
fetches the extension to use for Prolog files (see \file{README.TXT} on
the Windows version):

\begin{code}
?- win_registry_get_value(
       'HKEY_LOCAL_MACHINE/Software/SWI/Prolog',
       fileExtension,
       Ext).

Ext = pl
\end{code}

\noindent
    \predicate{win_folder}{2}{?Name, -Directory}
True if \arg{Name} is the Windows `CSIDL' of \arg{Directory}.  If
\arg{Name} is unbound, all known Windows special paths are generated.
\arg{Name} is the CSIDL after deleting the leading \const{CSIDL_} and
mapping the constant to lowercase.  Check the Windows documentation
for the function SHGetSpecialFolderPath() for a description of the
defined constants.  This example extracts the `My Documents' folder:

\begin{code}
?- win_folder(personal, MyDocuments).

MyDocuments = 'C:/Documents and Settings/jan/My Documents'
\end{code}

\noindent
    \predicate{win_add_dll_directory}{1}{+AbsDir}
This predicate adds a directory to the search path for dependent DLL
files.  If possible, this is achieved with \index{win_add_dll_directory/2}\predref{win_add_dll_directory}{2}.
Otherwise, \const{\%PATH\%} is extended with the provided directory.
\arg{AbsDir} may be specified in the Prolog canonical syntax.  See
\index{prolog_to_os_filename/2}\predref{prolog_to_os_filename}{2}.  Note that \index{use_foreign_library/1}\predref{use_foreign_library}{1} passes an
absolute path to the DLL if the destination DLL can be located from
the specification using \index{absolute_file_name/3}\predref{absolute_file_name}{3}.

    \predicate{win_add_dll_directory}{2}{+AbsDir, -Cookie}
This predicate adds a directory to the search path for dependent DLL
files. If the call is successful it unifies \arg{Cookie} with a handle
that must be passed to \index{win_remove_dll_directory/1}\predref{win_remove_dll_directory}{1} to remove the
directory from the search path. Error conditions:

    \begin{itemize}
    \item This predicate is available in the Windows port of SWI-Prolog
	  starting from 6.3.8/6.2.6.
    \item This predicate \emph{fails} if Windows does not yet support the
          underlying primitives.  These are available in recently
	  patched Windows~7 systems and later.
    \item This predicate throws an acception if the provided path is
          invalid or the underlying Windows API returns an error.
    \end{itemize}

If \index{open_shared_object/2}\predref{open_shared_object}{2} is passed an \emph{absolute} path to a DLL on a
Windows installation that supports AddDllDirectory() and
friends,\footnote{Windows~7 with up-to-date patches or Windows~8.}
SWI-Prolog uses LoadLibraryEx() with the flags
\const{LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR} and
\const{LOAD_LIBRARY_SEARCH_DEFAULT_DIRS}. In this scenario, directories
from \const{\%PATH\%} and \emph{not} searched. Additional directories
can be added using \index{win_add_dll_directory/2}\predref{win_add_dll_directory}{2}.

    \predicate{win_remove_dll_directory}{1}{-Cookie}
Remove a DLL search directory installed using \index{win_add_dll_directory/2}\predref{win_add_dll_directory}{2}.
\end{description}


\subsection{Dealing with time and date}		\label{sec:timedate}

Representing time in a computer system is surprisingly complicated.
There are a large number of time representations in use, and the correct
choice depends on factors such as compactness, resolution and desired
operations. Humans tend to think about time in hours, days, months,
years or centuries. Physicists think about time in seconds. But, a month
does not have a defined number of seconds. Even a day does not have a
defined number of seconds as sometimes a leap-second is introduced to
synchronise properly with our earth's rotation. At the same time,
resolution demands a range from better than pico-seconds to millions of
years. Finally, civilizations have a wide range of calendars. Although
there exist libraries dealing with most if this complexity, our desire
to keep Prolog clean and lean stops us from fully supporting these.

For human-oriented tasks, time can be broken into years, months, days,
hours, minutes, seconds and a timezone. Physicists prefer to have time
in an arithmetic type representing seconds or fraction thereof, so basic
arithmetic deals with comparison and durations. An additional advantage
of the physicist's approach is that it requires much less space. For
these reasons, SWI-Prolog uses an arithmetic type as its prime time
representation.

Many C libraries deal with time using fixed-point arithmetic, dealing
with a large but finite time interval at constant resolution. In our
opinion, using a floating point number is a more natural choice as we can
use a natural unit and the interface does not need to be changed if
a higher resolution is required in the future. Our unit of choice is the
second as it is the scientific unit.%
	\footnote{Using Julian days is a choice made by the Eclipse
		  team.  As conversion to dates is needed for a human
		  readable notation of time and Julian days cannot deal
		  naturally with leap seconds, we decided for the second as
		  our unit.}
We have placed our origin at 1970-1-1T0:0:0Z for compatibility with the
POSIX notion of time as well as with older time support provided by
SWI-Prolog.

Where older versions of SWI-Prolog relied on the POSIX conversion
functions, the current implementation uses
\href{http://cr.yp.to/libtai.html}{libtai} to realise conversion between
time-stamps and calendar dates for a period of 10 million years.

\subsubsection{Time and date data structures}
\label{sec:dattimedata}

We use the following time representations

\begin{description}
    \definition{TimeStamp}
A TimeStamp is a floating point number expressing the time in seconds
since the Epoch at 1970-1-1.

    \termitem{date}{Y,M,D,H,Mn,S,Off,TZ,DST}
We call this term a \emph{date-time} structure. The first 5 fields are
integers expressing the year, month (1..12), day (1..31), hour (0..23)
and minute (0..59). The \arg{S} field holds the seconds as a floating point
number between 0.0 and 60.0. \arg{Off} is an integer representing the
offset relative to UTC in seconds, where positive values are west of
Greenwich.  If converted from local time (see \index{stamp_date_time/3}\predref{stamp_date_time}{3}),
\arg{TZ} holds the name of the local timezone.  If the timezone is
not known, \arg{TZ} is the atom \const{\Sminus}.  \arg{DST} is \const{true}
if daylight saving time applies to the current time, \const{false}
if daylight saving time is relevant but not effective, and \const{\Sminus}
if unknown or the timezone has no daylight saving time.

    \termitem{date}{Y,M,D}
Date using the same values as described above.  Extracted using
\index{date_time_value/3}\predref{date_time_value}{3}.

    \termitem{time}{H,Mn,S}
Time using the same values as described above.  Extracted using
\index{date_time_value/3}\predref{date_time_value}{3}.
\end{description}

\subsubsection{Time and date predicates}
\label{sec:datimepreds}


\begin{description}
    \predicate{get_time}{1}{-TimeStamp}
Return the current time as a \arg{TimeStamp}.  The granularity is system-dependent.  See \secref{dattimedata}.

    \predicate{stamp_date_time}{3}{+TimeStamp, -DateTime, +TimeZone}
Convert a \arg{TimeStamp} to a \arg{DateTime} in the given timezone.
See \secref{dattimedata} for details on the data types.  \arg{TimeZone}
describes the timezone for the conversion.  It is one of \const{local}
to extract the local time, \const{'UTC'} to extract a UTC time or an
integer describing the seconds west of Greenwich.

    \predicate{date_time_stamp}{2}{+DateTime, -TimeStamp}
Compute the timestamp from a {date}/9 term.  Values for month, day,
hour, minute or second need not be normalized.  This flexibility
allows for easy computation of the time at any given number of
these units from a given timestamp.  Normalization can be achieved
following this call with \index{stamp_date_time/3}\predref{stamp_date_time}{3}.  This example computes
the date 200 days after 2006-7-14:

\begin{code}
?- date_time_stamp(date(2006,7,214,0,0,0,0,-,-), Stamp),
   stamp_date_time(Stamp, D, 0),
   date_time_value(date, D, Date).
Date = date(2007, 1, 30)
\end{code}

\noindent
When computing a time stamp from a local time specification, the UTC
offset (arg~7), TZ (arg~8) and DST (arg~9) argument may be left unbound
and are unified with the proper information. The example below, executed
in Amsterdam, illustrates this behaviour. On the 25th of March at 01:00,
DST does not apply. At 02.00, the clock is advanced by one hour and thus
both 02:00 and 03:00 represent the same time stamp.

\begin{code}
1 ?- date_time_stamp(date(2012,3,25,1,0,0,UTCOff,TZ,DST),
                     Stamp).
UTCOff = -3600,
TZ = 'CET',
DST = false,
Stamp = 1332633600.0.

2 ?- date_time_stamp(date(2012,3,25,2,0,0,UTCOff,TZ,DST),
                     Stamp).
UTCOff = -7200,
TZ = 'CEST',
DST = true,
Stamp = 1332637200.0.

3 ?- date_time_stamp(date(2012,3,25,3,0,0,UTCOff,TZ,DST),
                     Stamp).
UTCOff = -7200,
TZ = 'CEST',
DST = true,
Stamp = 1332637200.0.
\end{code}

\noindent
Note that DST and offset calculation are based on the POSIX function
mktime().  If mktime() returns an error, a representation_error
\const{dst} is generated.

    \predicate{date_time_value}{3}{?Key, +DateTime, ?Value}
Extract values from a {date}/9 term.  Provided keys are:

\begin{center}
\begin{tabular}{ll}
\hline
\bf key & \bf value \\
\hline
\const{year}	&  Calendar year as an integer \\
\const{month}	&  Calendar month as an integer 1..12 \\
\const{day}	&  Calendar day as an integer 1..31 \\
\const{hour}	&  Clock hour as an integer 0..23 \\
\const{minute}	&  Clock minute as an integer 0..59 \\
\const{second}	&  Clock second as a float 0.0..60.0 \\
\const{utc_offset}	&  Offset to UTC in seconds (positive is west) \\
\const{time_zone}	&  Name of timezone; fails if unknown \\
\const{daylight_saving}	&  Bool \const(true) if dst is in effect \\
\const{date}	&  Term \term{date}{Y,M,D} \\
\const{time}	&  Term \term{time}{H,M,S} \\
\hline
\end{tabular}
\end{center}

    \predicate{format_time}{3}{+Out, +Format, +StampOrDateTime}
Modelled after POSIX strftime(), using GNU extensions.  \arg{Out}
is a destination as specified with \index{with_output_to/2}\predref{with_output_to}{2}.  \arg{Format}
is an atom or string with the following conversions.  Conversions
start with a percent (\%) character.%
	\footnote{Descriptions taken from Linux Programmer's Manual}
\arg{StampOrDateTime} is either a numeric time-stamp, a term
\term{date}{Y,M,D,H,M,S,O,TZ,DST} or a term \term{date}{Y,M,D}.

\begin{itemize}
    \fmtchar{a}
The abbreviated weekday name according to the current locale.  Use
\index{format_time/4}\predref{format_time}{4} for POSIX locale.
    \fmtchar{A}
The full weekday name according to the current locale.   Use
\index{format_time/4}\predref{format_time}{4} for POSIX locale.
    \fmtchar{b}
The abbreviated month name according to the current locale.  Use
\index{format_time/4}\predref{format_time}{4} for POSIX locale.
    \fmtchar{B}
The full month name according to the current locale.  Use
\index{format_time/4}\predref{format_time}{4} for POSIX locale.
    \fmtchar{c}
The  preferred  date  and  time  representation  for the current
locale.
    \fmtchar{C}
The century number ({year}/100) as a 2-digit integer.
    \fmtchar{d}
The day of the month as a decimal number (range 01 to 31).
    \fmtchar{D}
Equivalent to \%m/\%d/\%y. (For Americans only. Americans should
note that in other countries \%d/\%m/\%y is rather common. This means
that in an international context this format is ambiguous and should not
be used.)
    \fmtchar{e}
Like \%d, the day of the month as a decimal number, but a leading
zero is replaced by a space.
    \fmtchar{E}
Modifier.  Not implemented.
    \fmtchar{f}
Number of microseconds.  The \const{f} can be prefixed by an integer
to print the desired number of digits.  E.g., \const{\%3f} prints
milliseconds.  This format is not covered by any standard, but
available with different format specifiers in various incarnations
of the strftime() function.
    \fmtchar{F}
Equivalent to \%Y-\%m-\%d (the ISO 8601 date format).
    \fmtchar{g}
Like \%G, but without century, i.e., with a 2-digit year (00-99).
    \fmtchar{G}
The ISO 8601 year with century as a decimal number. The 4-digit year
corresponding to the ISO week number (see \%V). This has the same format
and value as \%y, except that if the ISO week number belongs to the
previous or next year, that year is used instead.
    \fmtchar{V}
The ISO 8601:1988 week number of the current year as a decimal number,
range 01 to 53, where week 1 is the first week that has at least 4 days
in the current year, and with Monday as the first day of the week. See
also \%U and \%W.
    \fmtchar{h}
Equivalent to \%b.
    \fmtchar{H}
The  hour as a decimal number using a 24-hour clock (range 00 to 23).
    \fmtchar{I}
The hour as a decimal number using a 12-hour clock (range 01  to 12).
    \fmtchar{j}
The day of the year as a decimal number (range 001 to 366).
    \fmtchar{k}
The hour (24-hour clock) as a decimal number (range 0 to 23); single
digits are preceded by a blank. (See also \%H.)
    \fmtchar{l}
The hour (12-hour clock) as a decimal number (range  1  to  12);
single digits are preceded by a blank. (See also \%I.)
    \fmtchar{m}
The month as a decimal number (range 01 to 12).
    \fmtchar{M}
The minute as a decimal number (range 00 to 59).
    \fmtchar{n}
A newline character.
    \fmtchar{O}
Modifier to select locale-specific output.  Not implemented.
    \fmtchar{p}
Either `AM' or `PM' according to the given time value, or the
corresponding strings for the current locale. Noon is treated as `pm'
and midnight as `am'.\footnote{Despite the above clain, some locales
yield \const{am} or \const{pm} in lower case.}
    \fmtchar{P}
Like \%p but in lowercase: `am' or `pm' or a corresponding string
for the current locale.
    \fmtchar{r}
The time in a.m.\ or p.m.\ notation. In the POSIX locale this is
equivalent to `\%I:\%M:\%S \%p'.
    \fmtchar{R}
The time in 24-hour notation (\%H:\%M).  For a version including the
seconds, see \%T below.
    \fmtchar{s}
The number of seconds since the Epoch,  i.e.,  since  1970-01-01
00:00:00 UTC.
    \fmtchar{S}
The  second as a decimal number (range 00 to 60).  (The range is
up to 60 to allow for occasional leap seconds.)
    \fmtchar{t}
A tab character.
    \fmtchar{T}
The time in 24-hour notation (\%H:\%M:\%S).
    \fmtchar{u}
The day of the week as a decimal, range 1 to 7, Monday being  1.
See also \%w.
    \fmtchar{U}
The week number of the current year as a decimal number, range 00 to 53,
starting with the first Sunday as the first day of week 01. See also \%V
and \%W.
    \fmtchar{w}
The day of the week as a decimal, range 0 to 6, Sunday being  0.
See also \%u.
    \fmtchar{W}
The week number of the current year as a decimal number, range 00 to 53,
starting with the first Monday as the first day of week 01.
    \fmtchar{x}
The preferred date representation for the current locale without
the time.
    \fmtchar{X}
The preferred time representation for the current locale without
the date.
    \fmtchar{y}
The year as a decimal number without a century (range 00 to 99).
    \fmtchar{Y}
The year as a decimal number including the century.
    \fmtchar{z}
The timezone as hour offset from GMT using the format HHmm. Required to
emit RFC822-conforming dates (using
\texttt{'\%a,~\%d~\%b~\%Y~\%T~\%z'}). Our implementation supports
\texttt{\%:z}, which modifies the output to HH:mm as required by
XML-Schema. Note that both notations are valid in ISO 8601. The
sequence \texttt{\%:z} is compatible to the GNU	date(1) command.
    \fmtchar{Z}
The timezone or name or abbreviation.
    \fmtchar{\Splus}
The date and time in date(1) format.
    \fmtchar{\%}
A literal `\%' character.
\end{itemize}

The table below gives some format strings for popular time
representations.  RFC1123 is used by HTTP.  The full implementation of
\index{http_timestamp/2}\predref{http_timestamp}{2} as available from \pllib{http/http_header} is here.

\begin{code}
http_timestamp(Time, Atom) :-
        stamp_date_time(Time, Date, 'UTC'),
        format_time(atom(Atom),
                    '%a, %d %b %Y %T GMT',
                    Date, posix).
\end{code}

\noindent
\begin{center}
\begin{tabular}{ll}
\hline
\textbf{Standard} & \textbf{Format string} \\
\hline
\textbf{xsd} & \texttt{'\%FT\%T\%:z'} \\
\textbf{ISO8601} & \texttt{'\%FT\%T\%z'} \\
\textbf{RFC822} & \texttt{'\%a, \%d \%b \%Y \%T \%z'} \\
\textbf{RFC1123} & \texttt{'\%a, \%d \%b \%Y \%T GMT'} \\
\hline
\end{tabular}
\end{center}


    \predicate{format_time}{4}{+Out, +Format, +StampOrDateTime, +Locale}
Format time given a specified \arg{Locale}. This predicate is a
work-around for lacking proper portable and thread-safe time and locale
handling in current C libraries.  In its current implementation the only
value allowed for \arg{Locale} is \const{posix}, which currently only
modifies the behaviour of the \chr{a}, \chr{A}, \chr{b} and \chr{B}
format specifiers.  The predicate is used to be able to emit POSIX
locale week and month names for emitting standardised time-stamps
such as RFC1123.

    \predicate{parse_time}{2}{+Text, -Stamp}
Same as \term{parse_time}{Text, _Format, Stamp}.  See \index{parse_time/3}\predref{parse_time}{3}.

    \predicate{parse_time}{3}{+Text, ?Format, -Stamp}
Parse a textual time representation, producing a time-stamp.  Supported
formats for \arg{Text} are in the table below.  If the format is known,
it may be given to reduce parse time and avoid ambiguities.  Otherwise,
\arg{Format} is unified with the format encountered.

\begin{center}
\begin{tabular}{|l|l|}
\hline
\bf Name & \bf Example \\
\hline
rfc_1123 & \tt Fri, 08 Dec 2006 15:29:44 GMT \\
         & \tt Fri, 08 Dec 2006 15:29:44 +0000 \\
\hline
iso_8601 & \tt 2006-12-08T17:29:44+02:00 \\
         & \tt 20061208T172944+0200 \\
         & \tt 2006-12-08T15:29Z \\
         & \tt 2006-12-08 \\
         & \tt 20061208 \\
         & \tt 2006-12 \\
         & \tt 2006-W49-5 \\
         & \tt 2006-342 \\
\hline
\end{tabular}
\end{center}

    \predicate{day_of_the_week}{2}{+Date,-DayOfTheWeek}
Computes the day of the week for a given date.
\exam{\arg{Date} = date(\arg{Year},\arg{Month},\arg{Day})}.
Days of the week are numbered from one to seven: Monday = 1, Tuesday =
2, \ldots, Sunday = 7.
\end{description}

\subsection{Controlling the \program{swipl-win.exe} console window}
\label{sec:plwin}

The Windows executable \program{swipl-win.exe} console has a number of
predicates to control the appearance of the console. Being totally
non-portable, we do not advise using it for your own application, but
use XPCE or another portable GUI platform instead. We give the
predicates for reference here.

\begin{description}
    \predicate{window_title}{2}{-Old, +New}
Unify \arg{Old} with the title displayed in the console and change the
title to \arg{New}.%
	\bug{This predicate should have been called
	\const{win_window_title} for consistent naming.}

    \predicate{win_window_pos}{1}{+ListOfOptions}
Interface to the MS-Windows SetWindowPos() function, controlling
size, position and stacking order of the window.  \arg{ListOfOptions}
is a list that may hold any number of the terms below:

\begin{description}
    \termitem{size}{W, H}
Change the size of the window.  \arg{W} and \arg{H} are expressed
in character units.
    \termitem{position}{X, Y}
Change the top-left corner of the window.  The values are expressed
in pixel units.
    \termitem{zorder}{ZOrder}
Change the location in the window stacking order.  Values are
\const{bottom}, \const{top}, \const{topmost} and \const{notopmost}.
\emph{Topmost} windows are displayed above all other windows.
    \termitem{show}{Bool}
If \const{true}, show the window, if \const{false} hide the window.
    \termitem{activate}{}
If present, activate the window.
\end{description}

    \predicate{win_has_menu}{0}{}
True if \index{win_insert_menu/2}\predref{win_insert_menu}{2} and \index{win_insert_menu_item/4}\predref{win_insert_menu_item}{4} are present.

    \predicate{win_insert_menu}{2}{+Label, +Before}
Insert a new entry (pulldown) in the menu.  If the menu already contains
this entry, nothing is done.  The \arg{Label} is the label and, using the
Windows convention, a letter prefixed with \const{\&} is underlined and
defines the associated accelerator key. \arg{Before} is the label before
which this one must be inserted. Using \chr{\Sminus} adds the new entry at the
end (right).  For example, the call below adds an {\sf Application}
entry just before the {\sf Help} menu.

\begin{code}
win_insert_menu('&Application', '&Help')
\end{code}

\noindent
    \predicate{win_insert_menu_item}{4}{+Pulldown, +Label, +Before, :Goal}
Add an item to the named \arg{Pulldown} menu. \arg{Label} and
\arg{Before} are handled as in \index{win_insert_menu/2}\predref{win_insert_menu}{2}, but the label \chr{\Sminus}
inserts a \jargon{separator}.  \arg{Goal} is called if the user selects
the item.
\end{description}


\section{File System Interaction}	\label{sec:files}

\begin{description}
    \predicate{access_file}{2}{+File, +Mode}
True if \arg{File} exists and can be accessed by this Prolog
process under mode \arg{Mode}.  \arg{Mode} is one of the atoms
\const{read}, \const{write}, \const{append}, \const{exist}, \const{none} or
\const{execute}. \arg{File} may also be the name of a directory. Fails
silently otherwise.  \exam{access_file(File, none)} simply succeeds
without testing anything.

If \arg{Mode} is \const{write} or \const{append}, this predicate also succeeds
if the file does not exist and the user has write access to the
directory of the specified location.

The bahaviour is backed up by the POSIX access() API. The Windows
replacement (_waccess()) returns incorrect results because it does not
consider ACLs (Access Control Lists). The Prolog flag
\prologflag{win_file_access_check} may be used to control the level of
checking performed by Prolog. Please note that checking access never
provides a guarantee that a subsequent open succeeds without errors due
to inherent concurrency in file operations. It is generally more robust
to try and open the file and handle possible exceptions. See \index{open/4}\predref{open}{4} and
\index{catch/3}\predref{catch}{3}.

    \predicate{exists_file}{1}{+File}
True if \arg{File} exists and is a \jargon{regular} file. This does not
imply the user has read or write access to the file. See also
\index{exists_directory/1}\predref{exists_directory}{1} and \index{access_file/2}\predref{access_file}{2}.

    \predicate{file_directory_name}{2}{+File, -Directory}
Extracts the directory part of \arg{File}. This predicate removes the
longest match for the regular expression \verb|/*[^/]*/*$|. If the
result is empty it binds \arg{Directory} to \const{\Sdiv} if the first
character of \arg{File} is \const{\Sdiv} and \const{\Sdot} otherwise. The
behaviour is consistent with the POSIX \program{dirname}
program.\footnote{Before SWI-Prolog 7.7.13 trailing \const{\Sdiv} where
\emph{not} removed, translation \exam{/a/b/} into \exam{/a/b}. Volker
Wysk pointed at this incorrect behaviour.}

See also \index{directory_file_path/3}\predref{directory_file_path}{3} from \pllib{filesex}. The system ensures
that for every valid \arg{Path} using the Prolog (POSIX) directory
separators, following is true on systems with a sound implementation of
\index{same_file/2}\predref{same_file}{2}.\footnote{On some systems, \arg{Path} and \arg{Path2} refer
to the same entry in the file system, but \index{same_file/2}\predref{same_file}{2} may fail.} See
also \index{prolog_to_os_filename/2}\predref{prolog_to_os_filename}{2}.

\begin{code}
        ...,
        file_directory_name(Path, Dir),
        file_base_name(Path, File),
        directory_file_path(Dir, File, Path2),
        same_file(Path, Path2).
\end{code}

\noindent
    \predicate{file_base_name}{2}{+Path, -File}
Extracts the file name part from a path. Similar to
\index{file_directory_name/2}\predref{file_directory_name}{2} the extraction is based on the regex
\verb|/*([^/]*)/*$|, now capturing the non-\const{\Sdiv} segment. If the
segment is empty it unifies \arg{File} with \const{\Sdiv} if \arg{Path}
starts with \const{\Sdiv} and the empty atom (\verb$''$) otherwise. The
behaviour is consistent with the POSIX \program{basename}
program.\footnote{Before SWI-Prolog 7.7.13, if arg{Path} ended with
a \const{\Sdiv} \arg{File} was unified with the empty atom.}

    \predicate{same_file}{2}{+File1, +File2}
True if both filenames refer to the same physical file. That is, if
\arg{File1} and \arg{File2} are the same string or both names exist and
point to the same file (due to hard or symbolic links and/or relative
vs.\ absolute paths). On systems that provide stat() with meaningful
values for \const{st_dev} and \const{st_inode}, \index{same_file/2}\predref{same_file}{2} is
implemented by comparing the device and inode identifiers. On Windows,
\index{same_file/2}\predref{same_file}{2} compares the strings returned by the GetFullPathName()
system call.

    \predicate{exists_directory}{1}{+Directory}
True if \arg{Directory} exists and is a directory. This does not
imply the user has read, search or write permission for the
directory.

    \predicate{delete_file}{1}{+File}
Remove \arg{File} from the file system.

    \predicate{rename_file}{2}{+File1, +File2}
Rename \arg{File1} as \arg{File2}. The semantics is compatible to the
POSIX semantics of the rename() system call as far as the operating
system allows. Notably, if \arg{File2} exists, the operation succeeds
(except for possible permission errors) and is \jargon{atomic} (meaning
there is no window where \arg{File2} does not exist).

    \predicate{size_file}{2}{+File, -Size}
Unify \arg{Size} with the size of \arg{File} in bytes.

    \predicate{time_file}{2}{+File, -Time}
Unify the last modification time of \arg{File} with \arg{Time}.
\arg{Time} is a floating point number expressing the seconds elapsed
since Jan~1, 1970. See also \index{convert_time/[2,8]}\predref{convert_time}{[2,8]} and \index{get_time/1}\predref{get_time}{1}.

    \predicate{absolute_file_name}{2}{+File, -Absolute}
Expand a local filename into an absolute path. The absolute path is
canonicalised: references to \file{.} and \file{..} are deleted. This
predicate ensures that expanding a filename returns the same
absolute path regardless of how the file is addressed. SWI-Prolog uses
absolute filenames to register source files independent of the current
working directory. See also \index{absolute_file_name/3}\predref{absolute_file_name}{3} and \index{expand_file_name/2}\predref{expand_file_name}{2}.

    \predicate{absolute_file_name}{3}{+Spec, -Absolute, +Options}
Convert the given file specification into an absolute path. \arg{Spec}
is a term Alias(Relative) (e.g., \verb$(library(lists)$), a relative
filename or an absolute filename. The primary intention of this
predicate is to resolve files specified as Alias(Relative).
\arg{Option} is a list of options to guide the conversion:

\begin{description}
    \termitem{extensions}{ListOfExtensions}
List of file extensions to try.  Default is \const{''}.  For each
extension, \index{absolute_file_name/3}\predref{absolute_file_name}{3} will first add the extension and then
verify the conditions imposed by the other options.  If the condition
fails, the next extension on the list is tried.  Extensions may be
specified both as \fileext{ext} or plain \const{ext}.

    \termitem{relative_to}{+FileOrDir}
Resolve the path relative to the given directory or the directory
holding the given file.  Without this option, paths are resolved
relative to the working directory (see \index{working_directory/2}\predref{working_directory}{2}) or,
if \arg{Spec} is atomic and \index{absolute_file_name/[2,3]}\predref{absolute_file_name}{[2,3]} is executed
in a directive, it uses the current source file as reference.

    \termitem{access}{Mode}
Imposes the condition access_file(\arg{File}, \arg{Mode}).  \arg{Mode}
is one of \const{read}, \const{write}, \const{append},
\const{execute}, \const{exist} or \const{none}. See also \index{access_file/2}\predref{access_file}{2}.

    \termitem{file_type}{Type}
Defines extensions. Current mapping: \const{txt} implies \const{['']},
\const{prolog} implies \const{['.pl', '']}, \const{executable} implies
\const{['.so', '']}, \const{qlf} implies \const{['.qlf', '']} and
\const{directory} implies \const{['']}. The file type \const{source} is
an alias for \const{prolog} for compatibility with SICStus Prolog. See
also \index{prolog_file_type/2}\predref{prolog_file_type}{2}. This predicate only returns non-directories,
unless the option \term{file_type}{directory} is specified.

    \termitem{file_errors}{fail/error}
If \const{error} (default), throw an \const{existence_error} exception
if the file cannot be found.  If \const{fail}, stay silent.%
	\footnote{Silent operation was the default up to version 3.2.6.}

    \termitem{solutions}{first/all}
If \const{first} (default), the predicate leaves no choice point.
Otherwise a choice point will be left and backtracking may yield
more solutions.

    \termitem{expand}{Boolean}
If \const{true} (default is \const{false}) and \arg{Spec} is atomic,
call \index{expand_file_name/2}\predref{expand_file_name}{2} followed by \index{member/2}\predref{member}{2} on \arg{Spec} before
proceeding.  This is a SWI-Prolog extension intended to minimise
porting effort after SWI-Prolog stopped expanding environment
variables and the \chr{\Stilde} by default.  This option should be
considered deprecated.  In particular the use of \jargon{wildchart}
patterns such as \exam{\Stimes} should be avoided.
\end{description}

The Prolog flag \prologflag{verbose_file_search} can be set to \const{true}
to help debugging Prolog's search for files.

This predicate is derived from Quintus Prolog. In Quintus Prolog, the
argument order was \term{absolute_file_name}{+Spec, +Options, -Path}.
The argument order has been changed for compatibility with ISO and
SICStus.  The Quintus argument order is still accepted.

    \predicate{is_absolute_file_name}{1}{+File}
True if \arg{File} specifies an absolute path name.  On Unix systems,
this implies the path starts with a `/'.  For Microsoft-based systems
this implies the path starts with \metafile{\bnfmeta{letter}:}. This predicate is
intended to provide platform-independent checking for absolute paths.
See also \index{absolute_file_name/2}\predref{absolute_file_name}{2} and \index{prolog_to_os_filename/2}\predref{prolog_to_os_filename}{2}.

    \predicate{file_name_extension}{3}{?Base, ?Extension, ?Name}
This predicate is used to add, remove or test filename extensions. The
main reason for its introduction is to deal with different filename
properties in a portable manner.  If the file system is case-insensitive,
testing for an extension will also be done case-insensitive. \arg{Extension} may be specified with or without a leading dot (\chr{\Sdot}).
If an \arg{Extension} is generated, it will not have a leading dot.

    \predicate{directory_files}{2}{+Directory, -Entries}
Unify \arg{Entries} with a list of entries in \arg{Directory}.
Each member of \arg{Entries} is an atom denoting an entry relative
to \arg{Directory}. \arg{Entries} contains all entries, including hidden
files and, if supplied by the OS, the special entries \const{\Sdot} and
\const{..}.  See also \index{expand_file_name/2}\predref{expand_file_name}{2}.\footnote{This predicate should
be considered a misnomer because it returns entries rather than files.
We stick to this name for compatibility with, e.g., SICStus, Ciao and
YAP.}

    \predicate{expand_file_name}{2}{+WildCard, -List}
Unify \arg{List} with a sorted list of files or directories matching
\arg{WildCard}. The normal Unix wildcard constructs `\const{\Squest}',
`\const{\Stimes}', `\const{[\ldots]}' and `\const{\{\ldots\}}' are recognised.
The interpretation of `\const{\{\ldots\}}' is slightly
different from the C shell (csh(1)). The comma-separated argument can be
arbitrary patterns, including `\const{\{\ldots\}}' patterns. The empty
pattern is legal as well: `\file{\{.pl,\}}' matches either `\file{.pl}'
or the empty string.

If the pattern contains wildcard characters, only existing files and
directories are returned. Expanding a `pattern' without wildcard
characters returns the argument, regardless of whether or not it exists.

Before expanding wildcards, the construct \file{\$\arg{var}} is expanded
to the value of the environment variable \var{var}, and a possible
leading \verb$~$ character is expanded to the user's home directory.%
    \footnote{On Windows, the home directory is determined as follows:
	      if the environment variable \env{HOME} exists, this is
	      used.  If the variables \env{HOMEDRIVE} and \env{HOMEPATH}
	      exist (Windows-NT), these are used.  At initialisation,
	      the system will set the environment variable \env{HOME}
	      to point to the SWI-Prolog home directory if neither
	      \env{HOME} nor \env{HOMEPATH} and \env{HOMEDRIVE} are
	      defined.}

    \predicate{prolog_to_os_filename}{2}{?PrologPath, ?OsPath}
Convert between the internal Prolog path name conventions and the
operating system path name conventions. The internal conventions follow
the POSIX standard, which implies that this predicate is equivalent
to =/2 (unify) on POSIX (e.g., Unix) systems. On Windows systems it
changes the directory separator from \chr{\Sneg} into \chr{\Sdiv}.

    \predicate{read_link}{3}{+File, -Link, -Target}
If \arg{File} points to a symbolic link, unify \arg{Link} with the
value of the link and \arg{Target} to the file the link is pointing to.
\arg{Target} points to a file, directory or non-existing entry in the
file system, but never to a link.  Fails if \arg{File} is not a link.
Fails always on systems that do not support symbolic links.

    \predicate[deprecated]{tmp_file}{2}{+Base, -TmpName}
Create a name for a temporary file. \arg{Base} is an identifier for the
category of file. The \arg{TmpName} is guaranteed to be unique. If the
system halts, it will automatically remove all created temporary files.
\arg{Base} is used as part of the final filename.  Portable applications
should limit themselves to alphanumeric characters.

Because it is possible to guess the generated filename, attackers may
create the filesystem entry as a link and possibly create a security
issue.  New code should use \index{tmp_file_stream/3}\predref{tmp_file_stream}{3}.

    \predicate{tmp_file_stream}{3}{+Encoding, -FileName, -Stream}
\nodescription
    \predicate{tmp_file_stream}{3}{-FileName, -Stream, +Options}
Create a temporary filename \arg{FileName}, open it for writing and
unify \arg{Stream} with the output stream. If the OS supports it, the
created file is only accessible to the current user and the file is
created using the open()-flag \const{O_EXCL}, which guarantees that the
file did not exist before this call. The following options are
processed:

\begin{description}
    \termitem{encoding}{+Encoding}
Encoding of \arg{Stream}.  Default is the value of the Prolog flag
\prologflag{encoding}.  The value \const{binary} opens the file in
binary mode.
    \termitem{extension}{+Ext}
Ensure the created file has the given extension.  Default is no
extension.  Using an extension may be necessary to run external
programs on the file.
\end{description}

This predicate is a safe replacement of \index{tmp_file/2}\predref{tmp_file}{2}. Note that in those
cases where the temporary file is needed to store output from an
external command, the file must be closed first. E.g., the following
downloads a file from a URL to a temporary file and opens the file for
reading (on Unix systems you can delete the file for cleanup after
opening it for reading):

\begin{code}
open_url(URL, In) :-
        tmp_file_stream(text, File, Stream),
        close(Stream),
        process_create(curl, ['-o', File, URL], []),
        open(File, read, In),
        delete_file(File).              % Unix-only
\end{code}

\noindent
Temporary files created using this call are removed if the Prolog
process terminates \emph{gracefully}. Calling \index{delete_file/1}\predref{delete_file}{1} using
\arg{FileName} removes the file and removes the entry from the
administration of files-to-be-deleted.

    \predicate{make_directory}{1}{+Directory}
Create a new directory (folder) on the filesystem.  Raises an exception
on failure.  On Unix systems, the directory is created with default
permissions (defined by the process \jargon{umask} setting).

    \predicate{delete_directory}{1}{+Directory}
Delete directory (folder) from the filesystem.  Raises an exception on
failure.  Please note that in general it will not be possible to delete
a non-empty directory.

    \predicate{working_directory}{2}{-Old, +New}
Unify \arg{Old} with an absolute path to the current working directory
and change working directory to \arg{New}.  Use the pattern
\term{working_directory}{CWD, CWD} to get the current directory.  See
also \index{absolute_file_name/2}\predref{absolute_file_name}{2} and \index{chdir/1}\predref{chdir}{1}.%
	\bug{Some of the file I/O predicates use local filenames.
	     Changing directory while file-bound streams are open causes
	     wrong results on \index{telling/1}\predref{telling}{1}, \index{seeing/1}\predref{seeing}{1} and \index{current_stream/3}\predref{current_stream}{3}.}
Note that the working directory is shared between all threads.

    \predicate{chdir}{1}{+Path}
Compatibility predicate.  New code should use \index{working_directory/2}\predref{working_directory}{2}.
\end{description}

\section{User Top-level Manipulation}	\label{sec:toplevel}

\begin{description}
    \predicate{break}{0}{}
Recursively start a new Prolog top level. This Prolog top level shares
everything from the environment it was started in. Debugging is switched
off on entering a break and restored on leaving one. The break
environment is terminated by typing the system's \mbox{end-of-file}
character (control-D). If that is somehow not functional, the term
\exam{end_of_file.} can be entered to return from the break environment.
If the \argoption{-t}{toplevel} command line option is given, this goal
is started instead of entering the default interactive top level
(\index{prolog/0}\predref{prolog}{0}).

Notably the gui based versions (\program{swipl-win} on Windows and
MacOS) provide the menu \textsf{Run/New thread} that opens a new
toplevel that runs concurrently with the initial toplevel. The
concurrent toplevel can be used to examine the program, in particular
global dynamic predicates. It can not access \jargon{global variables}
or thread-local dynamic predicates (see \index{thread_local/1}\predref{thread_local}{1}) of the main
thread.

    \predicate{abort}{0}{}
Abort the Prolog execution and restart the top level. If the
\argoption{-t}{toplevel} command line option is given, this goal is
restarted instead of entering the default interactive top level.

Aborting is implemented by throwing the reserved exception
\verb='$aborted'=. This exception can be caught using \index{catch/3}\predref{catch}{3}, but the
recovery goal is wrapped with a predicate that prunes the choice points
of the recovery goal (i.e., as \index{once/1}\predref{once}{1}) and re-throws the exception.
This is illustrated in the example below, where we press control-C
and `a'.  See also \secref{urgentexceptions}.

\begin{code}
?- catch((repeat,fail), E, true).
^CAction (h for help) ? abort
% Execution Aborted
\end{code}

\noindent
    \predicate[ISO]{halt}{0}{}
Terminate Prolog execution.  This is the same as \term{halt}{0}. See
\index{halt/1}\predref{halt}{1} for details.

    \predicate[ISO]{halt}{1}{+Status}
Terminate Prolog execution with \arg{Status}. This predicate calls
\cfuncref{PL_halt}{} which preforms the following steps:

    \begin{enumerate}
    \item Set the Prolog flag \prologflag{exit_status} to \arg{Status}.

    \item Call all hooks registered using \index{at_halt/1}\predref{at_halt}{1}.  If \arg{Status}
    equals 0 (zero), any of these hooks calls \index{cancel_halt/1}\predref{cancel_halt}{1},
    termination is cancelled.

    \item Call all hooks registered using \cfuncref{PL_at_halt}{}.  In the future,
    if any of these hooks returns non-zero, termination will be
    cancelled.  Currently, this only prints a warning.

    \item Perform the following system cleanup actions:

    \begin{itemize}
    \item Cancel all threads, calling \index{thread_at_exit/1}\predref{thread_at_exit}{1} registered
          termination hooks.  Threads not responding within 1 second
	  are cancelled forcefully.
    \item Flush I/O and close all streams except for standard I/O.
    \item Reset the terminal if its properties were changed.
    \item Remove temporary files and incomplete compilation output.
    \item Reclaim memory.
    \end{itemize}

    \item Call exit(Status) to terminate the process
    \end{enumerate}

    \predicate{prolog}{0}{}
This goal starts the default interactive top level. Queries are read
from the stream \const{user_input}. See also the Prolog flag
\prologflag{history}. The \index{prolog/0}\predref{prolog}{0} predicate is terminated (succeeds) by
typing the end-of-file character (typically control-D).
\end{description}

The following two hooks allow for expanding queries and handling the
result of a query.  These hooks are used by the top level variable
expansion mechanism described in \secref{topvars}.

\begin{description}
    \predicate{expand_query}{4}{+Query, -Expanded, +Bindings, -ExpandedBindings}
Hook in module \const{user}, normally not defined.  \arg{Query} and
\arg{Bindings} represents the query read from the user and the names
of the free variables as obtained using \index{read_term/3}\predref{read_term}{3}.  If this predicate
succeeds, it should bind \arg{Expanded} and \arg{ExpandedBindings} to
the query and bindings to be executed by the top level.  This predicate
is used by the top level (\index{prolog/0}\predref{prolog}{0}).  See also \index{expand_answer/2}\predref{expand_answer}{2} and
\index{term_expansion/2}\predref{term_expansion}{2}.

    \predicate{expand_answer}{2}{+Bindings, -ExpandedBindings}
Hook in
module \const{user}, normally not defined. Expand the result of a
successfully executed top-level query. \arg{Bindings} is the query
$\bnfmeta{Name}=\bnfmeta{Value}$ binding list from the query. \arg{ExpandedBindings}
must be unified with the bindings the top level should print.
\end{description}

\section{Creating a Protocol of the User Interaction}	\label{sec:protocol}

SWI-Prolog offers the possibility to log the interaction with the user
on a file.%
    \footnote{A similar facility was added to Edinburgh C-Prolog by
              Wouter Jansweijer.}
All Prolog interaction, including warnings and tracer output, are written
to the protocol file.

\begin{description}
    \predicate{protocol}{1}{+File}
Start protocolling on file \arg{File}. If there is already a protocol
file open, then close it first. If \arg{File} exists it is truncated.
    \predicate{protocola}{1}{+File}
Equivalent to \index{protocol/1}\predref{protocol}{1}, but does not truncate the \arg{File} if it
exists.
    \predicate{noprotocol}{0}{}
Stop making a protocol of the user interaction.  Pending output is
flushed on the file.
    \predicate{protocolling}{1}{-File}
True if a protocol was started with \index{protocol/1}\predref{protocol}{1} or \index{protocola/1}\predref{protocola}{1} and
unifies \arg{File} with the current protocol output file.
\end{description}

\section{Debugging and Tracing Programs}	\label{sec:debugger}

This section is a reference to the debugger interaction predicates. A
more use-oriented overview of the debugger is in \secref{debugoverview}.

If you have installed XPCE, you can use the graphical front-end of the
tracer.  This front-end is installed using the predicate \index{guitracer/0}\predref{guitracer}{0}.

\begin{description}
    \predicate{trace}{0}{}
Start the tracer. \index{trace/0}\predref{trace}{0} itself cannot be seen in the tracer.  Note that
the Prolog top level treats \index{trace/0}\predref{trace}{0} special; it means `trace the next goal'.
    \predicate{tracing}{0}{}
True if the tracer is currently switched on.  \index{tracing/0}\predref{tracing}{0} itself cannot
be seen in the tracer.
    \predicate{notrace}{0}{}
Stop the tracer. \index{notrace/0}\predref{notrace}{0} itself cannot be seen in the tracer.
    \predicate{guitracer}{0}{}
Installs hooks (see \index{prolog_trace_interception/4}\predref{prolog_trace_interception}{4}) into the system that
redirect tracing information to a GUI front-end providing structured
access to variable bindings, graphical overview of the stack and
highlighting of relevant source code.
    \predicate{noguitracer}{0}{}
Revert back to the textual tracer.
    \predicate{trace}{1}{+Pred}
Equivalent to \exam{trace(\arg{Pred}, +all)}.
    \predicate{trace}{2}{+Pred, +Ports}
Put a trace point on all predicates satisfying the predicate specification
\arg{Pred}. \arg{Ports} is a list of port names (\const{call},
\const{redo}, \const{exit}, \const{fail}). The atom \const{all} refers
to all ports. If the port is preceded by a \const{\Sminus} sign, the
trace point is cleared for the port. If it is preceded by a \const{\Splus},
the trace point is set.

The predicate \index{trace/2}\predref{trace}{2} activates debug mode (see \index{debug/0}\predref{debug}{0}).  Each time
a port (of the 4-port model) is passed that has a trace point set, the
goal is printed as with \index{trace/0}\predref{trace}{0}.  Unlike \index{trace/0}\predref{trace}{0}, however, the execution
is continued without asking for further information.  Examples:

\begin{center}
\begin{tabular}{lp{3in}}
\exam{?- trace(hello).}          & Trace all ports of hello with any arity
                                   in any module. \\
\exam{?- trace({foo}/2, +fail).} & Trace failures of {foo}/2 in any module. \\
\exam{?- trace({bar}/1, -all).}  & Stop tracing {bar}/1.
\end{tabular}
\end{center}

The predicate \index{debugging/0}\predref{debugging}{0} shows all currently defined trace points.

    \predicate{notrace}{1}{:Goal}
Call \arg{Goal}, but suspend the debugger while \arg{Goal} is executing.
The current implementation cuts the choice points of \arg{Goal} after
successful completion. See \index{once/1}\predref{once}{1}.  Later implementations may have the
same semantics as \index{call/1}\predref{call}{1}.

    \predicate{debug}{0}{}
Start debugger. In debug mode, Prolog stops at spy and trace points,
disables last-call optimisation and aggressive destruction of
choice points to make debugging information accessible.  Implemented
by the Prolog flag \prologflag{debug}.

Note that the \const{min_free} parameter of all stacks is enlarged to
8~K cells if debugging is switched off in order to avoid excessive GC. GC
complicates tracing because it renames the \textit{_G\bnfmeta{NNN}} variables
and replaces unreachable variables with the atom
\verb$<garbage_collected>$. Calling \index{nodebug/0}\predref{nodebug}{0} does \emph{not} reset the
initial free-margin because several parts of the top level and debugger
disable debugging of system code regions.  See also \index{set_prolog_stack/2}\predref{set_prolog_stack}{2}.

    \predicate{nodebug}{0}{}
Stop debugger.  Implemented by the Prolog flag \prologflag{debug}.  See
also \index{debug/0}\predref{debug}{0}.

    \predicate{debugging}{0}{}
Print debug status and spy points on current output stream.  See also
the Prolog flag \prologflag{debug}.
    \predicate{spy}{1}{+Pred}
Put a spy point on all predicates meeting the predicate specification
\arg{Pred}. See \secref{listing}.
    \predicate{nospy}{1}{+Pred}
Remove spy point from all predicates meeting the predicate specification
\arg{Pred}.
    \predicate{nospyall}{0}{}
Remove all spy points from the entire program.
    \predicate{leash}{1}{?Ports}
Set/query leashing (ports which allow for user interaction). \arg{Ports} is
one of \arg{+Name}, \arg{-Name}, \arg{?Name} or a list of these.
\arg{+Name} enables leashing on that port, \arg{-Name} disables it and
\arg{?Name} succeeds or fails according to the current setting.
Recognised ports are \const{call}, \const{redo}, \const{exit}, \const{fail} and
\const{unify}. The special shorthand \const{all} refers to all ports,
\const{full} refers to all ports except for the unify port (default).
\const{half} refers to the \const{call}, \const{redo} and \const{fail}
port.

    \predicate{visible}{1}{+Ports}
Set the ports shown by the debugger. See \index{leash/1}\predref{leash}{1} for a description of
the \arg{Ports} specification. Default is \const{full}.

    \predicate{unknown}{2}{-Old, +New}
Edinburgh-Prolog compatibility predicate, interfacing to the ISO Prolog
flag \prologflag{unknown}. Values are \const{trace} (meaning \const{error})
and \const{fail}. If the \prologflag{unknown} flag is set to
\const{warning}, \index{unknown/2}\predref{unknown}{2} reports the value as \const{trace}.

    \predicate{style_check}{1}{+Spec}
Modify/query style checking options. \arg{Spec} is one of the terms
below or a list of these.

\begin{itemize}
    \item +\arg{Style} enables a style check
    \item -\arg{Style} disables a style check
    \item ?(\arg{Style}) queries a style check (note the brackets).
	  If \arg{Style} is unbound, all active style check options
	  are returned on backtracking.
\end{itemize}

Loading a file using \index{load_files/2}\predref{load_files}{2} or one of its derived predicates reset
the style checking options to their value before loading the file,
scoping the option to the remainder of the file and all files loaded
\emph{after} changing the style checking.

\begin{description}
    \termitem{singleton}{true}
The predicate \index{read_clause/3}\predref{read_clause}{3} (used by the compiler to read source code)
warns on variables appearing only once in a term (clause) which have a
name not starting with an underscore. See \secref{singleton} for details
on variable handling and warnings.

    \termitem{no_effect}{true}
This warning is generated by the compiler for BIPs (built-in predicates)
that are inlined by the compiler and for which the compiler can prove
that they are meaningless.  An example is using \predref{\Sequal}{2} against
a not-yet-initialised variable as illustrated in the example below. This
comparison is always \const{false}.

\begin{code}
always_false(X) :-
        X == Y,
        write(Y).
\end{code}

\noindent
    \termitem{var_branches}{false}
Verifies that if a variable is introduced in a branch and used
\emph{after} the branch, it is introduced in all branches. This code
aims at bugs following the skeleton below, where \term{p}{Next} may be
called with \arg{Next} unbound.

\begin{code}
p(Arg) :-
        (  Cond
        -> Next = value1
        ;  true
        ),
        p(Next).
\end{code}

\noindent
If a variable \arg{V} is intended to be left unbound, one can use
\exam{V=_}. This construct is removed by the compiler and thus has no
implications for the performance of your program.

This check was suggested together with \jargon{semantic} singleton
checking. The SWI-Prolog libraries contain about a hundred clauses that
are triggered by this style check. Unlike semantic singleton analysis,
only a tiny fraction of these clauses proofed faulty. In most cases, the
branches failing to bind the variable fail or raise an exception or the
caller handles the case where the variable is unbound.  The status of
this style check is unclear. It might be removed in the future or it
might be enhanced with a deeper analysis to be more precise.

    \termitem{discontiguous}{true}
Warn if the clauses for a predicate are not together in the same source file.
It is advised to disable the warning for discontiguous predicates using
the \index{discontiguous/1}\predref{discontiguous}{1} directive.

    \termitem{charset}{false}
Warn on atoms and variable names holding non-ASCII characters that are
not quoted. See also \secref{processorcharset}.
\end{description}
\end{description}

\section{Obtaining Runtime Statistics}	\label{sec:statistics}

\begin{description}
    \predicate{statistics}{2}{+Key, -Value}
Unify system statistics determined by \arg{Key} with \arg{Value}. The
possible keys are given in the \tabref{statistics}.  This predicate
supports additional keys for compatibility reasons.  These keys are
described in \tabref{qpstatistics}.

\begin{table}
\begin{center}
\begin{tabular}{|l|p{\linewidth-35mm}|}
\hline
\multicolumn{2}{|c|}{Native keys (times as float in seconds)} \\
\hline
agc		& Number of atom garbage collections performed \\
agc_gained	& Number of atoms removed \\
agc_time	& Time spent in atom garbage collections \\
atoms           & Total number of defined atoms \\
c_stack		& System (C-) stack limit.  0 if not known. \\
cgc		& Number of clause garbage collections performed \\
cgc_gained	& Number of clauses reclaimed \\
cgc_time	& Time spent in clause garbage collections \\
clauses         & Total number of clauses in the program \\
codes           & Total size of (virtual) executable code in words \\
cputime         & (User) {\sc cpu} time since thread was started in seconds \\
epoch		& Time stamp when thread was started \\
functors        & Total number of defined name/arity pairs \\
global          & Allocated size of the global stack in bytes \\
globalused      & Number of bytes in use on the global stack \\
globallimit     & Size to which the global stack is allowed to grow \\
global_shifts	& Number of global stack expansions \\
heapused        & Bytes of heap in use by Prolog (0 if not maintained) \\
inferences      & Total number of passes via the call and redo ports
                  since Prolog was started \\
modules         & Total number of defined modules \\
local           & Allocated size of the local stack in bytes \\
local_shifts	& Number of local stack expansions \\
locallimit      & Size to which the local stack is allowed to grow \\
localused       & Number of bytes in use on the local stack \\
table_space_used& Amount of bytes in use by the thread's answer tables \\
trail           & Allocated size of the trail stack in bytes \\
trail_shifts	& Number of trail stack expansions \\
traillimit      & Size to which the trail stack is allowed to grow \\
trailused       & Number of bytes in use on the trail stack \\
shift_time	& Time spent in stack-shifts \\
stack		& Total memory in use for stacks in all threads \\
predicates	& Total number of predicates.  This includes predicates
		  that are undefined or not yet resolved. \\
indexes_created & Number of clause index tables creates. \\
indexes_destroyed & Number of clause index tables destroyed. \\
process_epoch	& Time stamp when Prolog was started \\
process_cputime & (User) {\sc cpu} time since Prolog was started in seconds \\
thread_cputime  & MT-version: Seconds CPU time used by finished threads.
		  Basically non-portable. Works on Linux, MacOSX, Windows and
		  probably some more. \\
threads		& MT-version: number of active threads \\
threads_created & MT-version: number of created threads \\
engines		& MT-version: number of existing engines \\
engines_created & MT-version: number of created engines \\
\hline
\end{tabular}
\end{center}
    \caption{Keys for \index{statistics/2}\predref{statistics}{2}. Space is expressed in bytes.
	     Time is expressed in seconds, represented as a
	     floating point number.}
    \label{tab:statistics}
\end{table}


\begin{table}
\begin{center}
\begin{tabular}{|l|p{\linewidth-35mm}|}
\hline
\multicolumn{2}{|c|}{Compatibility keys (times in milliseconds)} \\
\hline
runtime		& [ CPU time, CPU time since last ]
		  (milliseconds, excluding time spent in
		   garbage collection) \\
system_time	& [ System CPU time, System CPU time since last ]
		  (milliseconds)\\
real_time	& [ Wall time, Wall time since last ]
		  (integer seconds. See \index{get_time/1}\predref{get_time}{1}) \\
walltime	& [ Wall time since start, Wall time since last]
		  (milliseconds, SICStus compatibility) \\
memory		& [ Total unshared data, free memory ]
		  (Used is based on \const{ru_idrss} from getrusage().
		   Free is based on \const{RLIMIT_DATA} from
		   getrlimit(). Both are reported as zero if the OS
		   lacks support.) \\
stacks		& [ global use, local use ] \\
program		& [ heap, 0 ] \\
global_stack	& [ global use, global free ] \\
local_stack	& [ local use, local free ] \\
trail		& [ trail use, trail free ] \\
garbage_collection & [ number of GC, bytes gained, time spent, bytes left ]
		  The last column is a SWI-Prolog extension.  It contains the
		  sum of the memory left after each collection, which can be
		  divided by the count to find the average working set size
		  after GC.  Use \exam{[Count, Gained, Time|_]} for compatiblity. \\
stack_shifts    & [ global shifts, local shifts, time spent ] \\
atoms		& [ number, memory use, 0 ] \\
atom_garbage_collection &
		  [ number of AGC, bytes gained, time spent ] \\
clause_garbage_collection &
		  [ number of CGC, clauses gained, time spent ] \\
core		& Same as memory \\
\hline
\end{tabular}
\end{center}
    \caption{Compatibility keys for \index{statistics/2}\predref{statistics}{2}. Time is expressed in
	     milliseconds.}
    \label{tab:qpstatistics}
\end{table}

    \predicate{statistics}{0}{}
Display a table of system statistics on the stream \const{user_error}.

    \predicate{time}{1}{:Goal}
Execute \arg{Goal} just like \index{call/1}\predref{call}{1} and print time used, number of
logical inferences and the average number of \arg{lips} (logical
inferences per second). Note that SWI-Prolog counts the actual executed
number of inferences rather than the number of passes through the call
and redo ports of the theoretical 4-port model. If \arg{Goal} is
non-deterministic, print statistics for each solution, where the
reported values are relative to the previous answer.
\end{description}

		 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
		 %	      PROFILER		%
		 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\input{profile.tex}


		 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
		 %	GARBAGE COLLECTION	%
		 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Memory Management}		\label{sec:memory}

\begin{description}
    \predicate{garbage_collect}{0}{}
Invoke the global and trail stack garbage collector.  Normally the
garbage collector is invoked automatically if necessary.  Explicit
invocation might be useful to reduce the need for garbage collections in
time-critical segments of the code.  After the garbage collection
\index{trim_stacks/0}\predref{trim_stacks}{0} is invoked to release the collected memory resources.

    \predicate{garbage_collect_atoms}{0}{}
Reclaim unused atoms. Normally invoked after \prologflag{agc_margin} (a
Prolog flag) atoms have been created. On multithreaded versions the
actual collection is delayed until there are no threads performing
normal garbage collection. In this case \index{garbage_collect_atoms/0}\predref{garbage_collect_atoms}{0} returns
immediately. Note that there is no guarantee it will \emph{ever}
happen, as there may always be threads performing garbage collection.

    \predicate{garbage_collect_clauses}{0}{}
Reclaim retracted clauses. During normal operation, retracting a clause
implies setting the \jargon{erased generation} to the current
\jargon{generation} of the database and increment the generation.
Keeping the clause around is both needed to realise the \jargon{logical
update view} and deal with the fact that other threads may be executing
the clause. Both static and dynamic code is processed this
way.\footnote{Up to version 7.3.11, dynamic code was handled using
\jargon{reference counts}.}.

The clause garbage collector (CGC) scans the environment stacks of all
threads for referenced dirty predicates and at which generation this
reference accesses the predicate. It then removes the references for
clauses that have been retracted before the oldest access generation
from the clause list as well as the secondary clauses indexes of the
predicate. If the clause list is not being scanned, the clause
references and ultimately the clause itself is reclaimed.

The clause garbage collector is called under three conditions, (1) after
\jargon{reloading} a source file, (2) if the memory occupied by
retracted but not yet reclaimed clauses exceeds 12.5\% of the program
store, or (3) if skipping dead clauses in the clause lists becomes too
costly. The cost of clause garbage collection is proportional with the
total size of the local stack of all threads (the scanning phase) and
the number of clauses in all `dirty' predicates (the reclaiming phase).

    \predicate{set_prolog_gc_thread}{1}{+Status}
Control whether or not atom and clause garbage collection are executed
in a dedicated thread. The default is \const{true}. Values for
\arg{Status} are \const{true}, \const{false} and \const{stop}. The
latter stops the \const{gc} thread but allows is to be recreated lazily.
This is use by e.g., \index{fork/1}\predref{fork}{1} to avoid forking a multi-threaded
application.  See also \prologflag{gc_thread}.

    \predicate{trim_stacks}{0}{}
Release stack memory resources that are not in use at this moment,
returning them to the operating system. It can be used to release memory
resources in a backtracking loop, where the iterations require typically
seconds of execution time and very different, potentially large, amounts
of stack space. Such a loop can be written as follows:

\begin{code}
loop :-
        generator,
            trim_stacks,
            potentially_expensive_operation,
        stop_condition, !.
\end{code}

\noindent
The Prolog top-level loop is written this way, reclaiming memory
resources after every user query.

    \predicate{set_prolog_stack}{2}{+Stack, +KeyValue}
Set a parameter for one of the Prolog runtime stacks. \arg{Stack} is one
of \const{local}, \const{global} or \const{trail}. The table below
describes the \arg{Key}(\arg{Value}) pairs.

Current settings can be retrieved with \index{prolog_stack_property/2}\predref{prolog_stack_property}{2}.

\begin{description}
    \termitem{min_free}{+Cells}
Minimum amount of free space after trimming or shifting the stack.
Setting this value higher can reduce the number of garbage collections
and stack-shifts at the cost of higher memory usage. The
amount is reported and specified in \jargon{cells}. A cell is 4 bytes
in the 32-bit version and 8 bytes on the 64-bit version. See
\prologflag{address_bits}. See also \index{trim_stacks/0}\predref{trim_stacks}{0} and \index{debug/0}\predref{debug}{0}.

    \termitem{low}{+Cells}
\nodescription
    \termitem{factor}{+Number}
These two figures determine whether, if the stacks are low, a stack
\jargon{shift} (expansion) or garbage collection is performed. This
depends on these two parameters, the current stack usage and the amount
of stack used after the last garbage collection.  A garbage collection
is started if $used > factor \times lastused + low$.

    \termitem{spare}{+Cells}
All stacks trigger overflow before actually reaching the limit, so the
resulting error can be handled gracefully. The spare stack is used for
\index{print_message/2}\predref{print_message}{2} from the garbage collector and for handling exceptions.
The default suffices, unless the user redefines related hooks. Do
\textbf{not} specify large values for this because it reduces the amount
of memory available for your real task.

Related hooks are \index{message_hook/3}\predref{message_hook}{3} (redefining GC messages),
\index{prolog_trace_interception/4}\predref{prolog_trace_interception}{4} and \index{prolog_exception_hook/4}\predref{prolog_exception_hook}{4}.
\end{description}

    \predicate{prolog_stack_property}{2}{?Stack, ?KeyValue}
True if \arg{KeyValue} is a current property of \arg{Stack}.  See
\index{set_prolog_stack/2}\predref{set_prolog_stack}{2} for defined properties.
\end{description}

The total space limit for all stacks is controlled using the prolog
flag \prologflag{stack_limit}.


\section{Windows DDE interface}          \label{sec:DDE}

The predicates in this section deal with MS-Windows `Dynamic Data
Exchange' or DDE protocol.%
        \footnote{This interface is contributed by Don Dwiggins.}
A Windows DDE conversation is a form of interprocess communication
based on sending reserved window events between the communicating
processes.

Failing DDE operations raise an error of the structure below, where
\arg{Operation} is the name of the (partial) operation that failed and
\arg{Message} is a translation of the operator error code. For some
errors, \arg{Context} provides additional comments.

\begin{code}
        error(dde_error(Operation, Message), Context)
\end{code}

\noindent
\subsection{DDE client interface}
\label{sec:dde-client}

The DDE client interface allows Prolog to talk to DDE server programs.
We will demonstrate the use of the DDE interface using the Windows
PROGMAN (Program Manager) application:

\begin{code}
1 ?- open_dde_conversation(progman, progman, C).

C = 0
2 ?- dde_request(0, groups, X)

--> Unifies X with description of groups

3 ?- dde_execute(0, '[CreateGroup("DDE Demo")]').
true.

4 ?- close_dde_conversation(0).
true.
\end{code}

\noindent
For details on interacting with \program{progman}, use the SDK online
manual section on the Shell DDE interface. See also the Prolog
\file{library(progman)}, which may be used to write simple Windows setup
scripts in Prolog.


\begin{description}
    \predicate{open_dde_conversation}{3}{+Service, +Topic, -Handle}
Open a conversation with a server supporting the given service name and
topic (atoms).  If successful, \arg{Handle} may be used to send
transactions to the server.  If no willing server is found this
predicate fails silently.

    \predicate{close_dde_conversation}{1}{+Handle}
Close the conversation associated with \arg{Handle}.  All opened
conversations should be closed when they're no longer needed, although
the system will close any that remain open on process termination.

    \predicate{dde_request}{3}{+Handle, +Item, -Value}
Request a value from the server.  \arg{Item} is an atom that identifies
the requested data, and \arg{Value} will be a string (\const{CF_TEXT} data
in DDE parlance) representing that data, if the request is successful.

    \predicate{dde_execute}{2}{+Handle, +Command}
Request the DDE server to execute the given command string.  Succeeds
if the command could be executed and fails with an error message otherwise.

    \predicate{dde_poke}{4}{+Handle, +Item, +Command}
Issue a \const{POKE} command to the server on the specified \arg{Item}.
\arg{command} is passed as data of type \const{CF_TEXT}.
\end{description}


\subsection{DDE server mode}
\label{sec:dde-server}

The \file{library(dde)} defines primitives to realise simple
DDE server applications in SWI-Prolog.  These features are provided as
of version 2.0.6 and should be regarded as prototypes.  The C part of
the DDE server can handle some more primitives, so if you need features
not provided by this interface, please study \file{library(dde)}.


\begin{description}
    \predicate{dde_register_service}{2}{+Template, +Goal}
Register a server to handle DDE request or DDE \const{execute} requests from
other applications. To register a service for a DDE request, \arg{Template} is of the form:
\begin{quote}
+Service(+Topic, +Item, +Value)
\end{quote}
\arg{Service} is the name of the DDE service provided (like
\program{progman} in the client example above). \arg{Topic} is either an
atom, indicating \arg{Goal} only handles requests on this topic, or a
variable that also appears in \arg{Goal}. \arg{Item} and \arg{Value} are
variables that also appear in \arg{Goal}. \arg{Item} represents the
request data as a Prolog atom.%
    \footnote{Up to version 3.4.5 this was a list of character codes.
	      As recent versions have atom garbage collection there is
	      no need for this anymore.}

The example below registers the Prolog \index{current_prolog_flag/2}\predref{current_prolog_flag}{2} predicate
to be accessible from other applications. The request may be given from
the same Prolog as well as from another application.

\begin{code}
?- dde_register_service(prolog(current_prolog_flag, F, V),
                        current_prolog_flag(F, V)).

?- open_dde_conversation(prolog, current_prolog_flag, Handle),
   dde_request(Handle, home, Home),
   close_dde_conversation(Handle).

Home = '/usr/local/lib/pl-2.0.6/'
\end{code}

\noindent
Handling DDE \const{execute} requests is very similar.  In this case the
template is of the form:

\begin{quote}
+Service(+Topic, +Item)
\end{quote}

Passing a \arg{Value} argument is not needed as \const{execute} requests either
succeed or fail.  If \arg{Goal} fails, a `not processed' is passed back
to the caller of the DDE request.
    \predicate{dde_unregister_service}{1}{+Service}
Stop responding to \arg{Service}. If Prolog is halted, it will
automatically call this on all open services.
    \predicate{dde_current_service}{2}{-Service, -Topic}
Find currently registered services and the topics served on them.
    \predicate{dde_current_connection}{2}{-Service, -Topic}
Find currently open conversations.
\end{description}


\section{Miscellaneous}			\label{sec:miscpreds}

\begin{description}
    \predicate{dwim_match}{2}{+Atom1, +Atom2}
True if \arg{Atom1} matches \arg{Atom2} in the `Do What I Mean' sense.
Both \arg{Atom1} and \arg{Atom2} may also be integers or floats.
The two atoms match if:
\begin{shortlist}
    \item They are identical
    \item They differ by one character (spy $\equiv$ spu)
    \item One character is inserted/deleted (debug $\equiv$ deug)
    \item Two characters are transposed (trace $\equiv$ tarce)
    \item `Sub-words' are glued differently (existsfile $\equiv$ existsFile $\equiv$ exists_file)
    \item Two adjacent sub-words are transposed (existsFile $\equiv$ fileExists)
\end{shortlist}
    \predicate{dwim_match}{3}{+Atom1, +Atom2, -Difference}
Equivalent to \index{dwim_match/2}\predref{dwim_match}{2}, but unifies \arg{Difference} with an atom
identifying the difference between \arg{Atom1} and \arg{Atom2}.  The
return values are (in the same order as above): \const{equal},
\const{mismatched_char}, \const{inserted_char}, \const{transposed_char},
\const{separated} and \const{transposed_word}.
    \predicate{wildcard_match}{2}{+Pattern, +String}
True if \arg{String} matches the wildcard pattern \arg{Pattern}.
\arg{Pattern} is very similar to the Unix \const{csh} pattern matcher. The
patterns are given below:

\begin{center}\begin{tabular}{ll}
\const{\Squest}          & Matches one arbitrary character. \\
\const{\Stimes}          & Matches any number of arbitrary characters. \\
\const{[\ldots]}   & Matches one of the characters specified between the
		     brackets. \\
		   & \mbox{\tt \bnfmeta{char1}-\bnfmeta{char2}} indicates a range. \\
\const{\{\ldots\}} & Matches any of the patterns of the comma-separated
list between the braces.
\end{tabular}\end{center}

Example:

\begin{code}
?- wildcard_match('[a-z]*.{pro,pl}[%~]', 'a_hello.pl%').
true.
\end{code}

\noindent
    \predicate{sleep}{1}{+Time}
Suspend execution \arg{Time} seconds. \arg{Time} is either a floating
point number or an integer. Granularity is dependent on the system's
timer granularity.  A negative time causes the timer to return
immediately. On most non-realtime operating systems we can only ensure
execution is suspended for {\bf at least} \arg{Time} seconds.

On Unix systems the \index{sleep/1}\predref{sleep}{1} predicate is realised ---in order of
preference--- by nanosleep(), usleep(), select() if the time is below 1
minute, or sleep().  On Windows systems Sleep() is used.
\end{description}
