\chapter{Introduction}			\label{sec:intro}

\section{SWI-Prolog}			\label{sec:swiprolog}

SWI-Prolog started back in 1986 with the requirement for a Prolog that
could handle recursive interaction with the C-language: Prolog calling C
and C calling Prolog recursively. Those days Prolog systems were very
aware of its environment and we needed such a system to support
interactive applications. Since then, SWI-Prolog's development has been
guided by requests from the user community, especially focussing on
(in arbitrary order) interaction with the environment, scalability,
(I/O) performance, standard compliance, teaching and the program
development environment.

SWI-Prolog is based on a very simple Prolog virtual machine called ZIP
\cite{Bowen:83,Neumerkel:93} which defines only 7 instructions. Prolog can easily be
compiled into this language and the abstract machine code is easily
decompiled back into Prolog. As it is also possible to wire a standard
4-port debugger in the virtual machine there is no need for a
distinction between compiled and interpreted code. Besides simplifying
the design of the Prolog system itself this approach has advantages for
program development: the compiler is simple and fast, the user does not
have to decide in advance whether debugging is required and the system
only runs slightly slower when in debug mode. The price we have to pay
is some performance degradation (taking out the debugger from the VM
interpreter improves performance by about 20\%) and somewhat additional
memory usage to help the decompiler and debugger.

SWI-Prolog extends the minimal set of instructions described in
\cite{Bowen:83} to improve performance. While extending this set care
has been taken to maintain the advantages of decompilation and tracing
of compiled code. The extensions include specialised instructions for
unification, predicate invocation, some frequently used built-in
predicates, arithmetic, and control (\predref{;}{2}, \predref{|}{2}),
if-then (\predref{->}{2}) and negation-by-failure (\predref{\+}{1}).

\subsection{Books about Prolog}		\label{sec:books}

This manual does not describe the full syntax and semantics of Prolog,
nor how one should write a program in Prolog. These subjects have been
described extensively in the literature. See \cite{Bratko:86},
\cite{Sterling:86}, and \cite{Clocksin:87}. For more advanced Prolog
material see \cite{Keefe:90}. Syntax and standard operator declarations
conform to the `Edinburgh standard'. Most built-in predicates are
compatible with those described in \cite{Clocksin:87}. SWI-Prolog also
offers a number of primitive predicates compatible with Quintus Prolog%
    \footnote{Quintus is a trademark of Quintus Computer Systems Inc., USA}
\cite{QUINTUS:manual} and BIM_Prolog%
    \footnote{BIM is a trademark of BIM sa/nv., Belgium}
\cite{BIMPROLOG:manual}.

ISO compliant predicates are based on ``Prolog: The Standard'',
\cite{Deransart:96}, validated using \cite{stdprolog:98}.

\section{Status}			\label{sec:status}

This manual describes version \versionshort{} of SWI-Prolog. SWI-Prolog
has been used now for many years. The application range includes Prolog
course material, meta-interpreters, simulation of parallel Prolog,
learning systems, natural language processing, complex interactive
systems, web-server and web-server components. Although in our
experience rather obvious and critical bugs can remain unnoticed for a
remarkable long period, we assume the basic Prolog system is fairly
stable. Bugs can be expected in infrequently used built-in predicates.

Some bugs are known to the author. They are described as footnotes in
this manual.


\section{Compliance to the ISO standard}		\label{sec:iso}

SWI-Prolog 3.3.0 implements all predicates described in ``Prolog: The
Standard'' \cite{Deransart:96}.

Exceptions and warning are still weak. Some SWI-Prolog predicates
silently fail on conditions where the ISO specification requires an
exception (functor/3 for example). Some predicates print warnings
rather than raising an exception.  All predicates where exceptions
may be caused due to a correct program operating in an imperfect
world (I/O, arithmetic, resource overflows) should behave according
to the ISO standard. In other words: SWI-Prolog should be able to
execute any program conforming to \cite{Deransart:96} that does not rely
on exceptions generated by errors in the program.


\section{Should you be using SWI-Prolog?}	\label{sec:swiorother}

There are a number of reasons why you better choose a commercial Prolog
system, or another academic product:

\begin{itemlist}
    \item [SWI-Prolog is not supported]
Although I usually fix bugs shortly after a bug report arrives, I cannot
promise anything.  Now that the sources are provided, you can always
dig into them yourself.
    \item [Memory requirements and performance are your first concerns]
A number of commercial compilers are more keen on memory and performance
than SWI-Prolog.  I do not wish to sacrifice some of the nice features of
the system, nor its portability to compete on raw performance.
    \item [You need features not offered by SWI-Prolog]
In this case you may wish to give me suggestions for extensions. If
you have great plans, please contact me (you might have to implement
them yourself however).
\end{itemlist}

On the other hand, SWI-Prolog offers some nice facilities:

\begin{itemlist}
    \item [Nice environment]
This includes `Do What I Mean', automatic completion of atom names,
history mechanism and a tracer that operates on single key-strokes.
Interfaces to some standard editors are provided (and can be extended),
as well as a facility to maintain programs (see make/0).
    \item [Very fast compiler]
Even very large applications can be loaded in seconds on most machines.
If this is not enough, there is a Quick Load Format that is slightly
more compact and loading is almost always I/O bound.
    \item [Transparent compiled code]
SWI-Prolog compiled code can be treated just as interpreted code: you
can list it, trace it, etc. This implies you do not have to decide
beforehand whether a module should be loaded for debugging or not. Also,
performance is much better than the performance of most interpreters.
    \item [Profiling]
SWI-Prolog offers tools for performance analysis, which can be very
useful to optimise programs. Unless you are very familiar with Prolog
and Prolog performance considerations this might be more helpful than a
better compiler without these facilities.
    \item [Flexibility]
SWI-Prolog can easily be integrated with C, supporting non-determinism
in Prolog calling C as well as C calling Prolog (see \secref{foreign}).
It can also be \jargon{embedded} embedded in external programs (see
\secref{plld}). System predicates can be redefined locally to provide
compatibility with other Prolog systems.
    \item [Integration with XPCE]
\index{Unix}\index{X-Windows}\index{Windows}\index{MacOS X}%
SWI-Prolog offers a tight integration to the Object Oriented Package
for User Interface Development, called XPCE \cite{P1098:C1.6}.
XPCE allows you to implement graphical user interfaces that are
source-code compatible over Unix/X11, Win32 (Windows 95/98/ME and
NT/2000/XP) and MacOS X (darwin).
\end{itemlist}


\input{xpce}

\section{Release Notes}			\label{sec:relnotes}

Collected release-notes. This section only contains some highlights.
Smaller changes to especially older releases have been removed. For
a complete log, see the file \file{ChangeLog} from the distribution.


\subsection*{Version 1.8 Release Notes}	\label{sec:rel-1.8}

Version 1.8 offers a stack-shifter to provide dynamically expanding
stacks on machines that do not offer operating-system support for
implementing dynamic stacks.


\subsection*{Version 1.9 Release Notes}	\label{sec:rel-1.9}

Version 1.9 offers better portability including an MS-Windows 3.1
version.  Changes to the Prolog system include:

\begin{itemlist}
    \item [Redefinition of system predicates]
Redefinition of system predicates was allowed silently in older versions.
Version 1.9 only allows it if the new definition is headed by a
:- redefine_system_predicate/1 directive.top-level
    \item [`Answer' reuse]
The top-level maintains a table of bindings returned by top-level goals and
allows for reuse of these bindings by prefixing the variables with the \$
sign.  See \secref{topvars}.
    \item [Better source code administration]
Allows for proper updating of multifile predicates and finding the
sources of individual clauses.
\end{itemlist}


\subsection*{Version 2.0 Release Notes}	\label{sec:rel-2.0}

New features offered:

\begin{itemlist}
    \item [32-bit Virtual Machine]
Removes various limits and improves performance.
    \item [Inline foreign functions]
`Simple' foreign predicates no longer build a Prolog stack-frame, but
are directly called from the VM.  Notably provides a speedup for the
test predicates such as var/1, etc.
    \item [Various compatibility improvements]
    \item [Stream based I/O library]
All SWI-Prolog's I/O is now handled by the stream-package defined in
the foreign include file \file{SWI-Stream.h}. Physical I/O of
Prolog streams may be redefined through the foreign language interface,
facilitating much simpler integration in window environments.
\end{itemlist}


\subsection*{Version 2.5 Release Notes}	\label{sec:rel-2.5}

Version 2.5 is an intermediate release on the path from 2.1 to 3.0. All
changes are to the foreign-language interface, both to user- and
system-predicates implemented in the C-language. The aim is twofold.
First of all to make garbage-collection and stack-expansion
(stack-shifts) possible while foreign code is active without the
C-programmer having to worry about locking and unlocking C-variables
pointing to Prolog terms. The new approach is closely compatible with the
Quintus and SICStus Prolog foreign interface using the \const{+term}
argument specification (see their respective manuals). This allows for
writing foreign interfaces that are easily portable over these three
Prolog platforms.

Apart from various bug fixes listed in the ChangeLog file, these
are the main changes since 2.1.0:

\begin{itemlist}
    \item [ISO compatibility]
Many ISO compatibility features have been added: open/4, arithmetic
functions, syntax, etc.
    \item [Win32]
Many fixes for the Win32 (NT, '95 and win32s) platforms.  Notably
many problems related to pathnames and a problem in the garbage
collector.
    \item [Performance]
Many changes to the clause indexing system: added hash-tables,
lazy computation of the index information, etc.
    \item [Portable saved-states]
The predicate qsave_program/[1,2] allows for the creating of machine
independent saved-states that load very quickly.
\end{itemlist}

\subsection*{Version 2.6 Release Notes}	\label{sec:rel-2.6}

Version 2.6 provides a stable implementation of the features added in
the 2.5.x releases, but at the same time implements a number of new
features that may have impact on the system stability.

\begin{itemlist}
    \item [32-bit integer and double float arithmetic]
The biggest change is the support for full 32-bit signed integers and
raw machine-format double precision floats. The internal data
representation as well as the arithmetic instruction set and interface
to the arithmetic functions has been changed for this.
    \item [Embedding for Win32 applications]
The Win32 version has been reorganised.  The Prolog kernel is now
implemented as Win32 DLL that may be embedded in C-applications.
Two front ends are provided, one for window-based operation and
one to run as a Win32 console application.
    \item [Creating stand-alone executables]
Version 2.6.0 can create stand-alone executables by attaching the
saved-state to the emulator.  See qsave_program/2.
\end{itemlist}

\subsection*{Version 2.7 Release Notes}	\label{sec:rel-2.7}

Version 2.7 reorganises the entire data-representation of the Prolog data
itself.  The aim is to remove most of the assumption on the machine's
memory layout to improve portability in general and enable embedding on
systems where the memory layout may depend on invocation or on how the
executable is linked.  The latter is notably a problem on the Win32
platforms.  Porting to 64-bit architectures is feasible now.

Furthermore, 2.7 lifts the limits on arity of predicates and number of
variables in a clause considerably and allow for further expansion at
minimal cost.


\subsection*{Version 2.8 Release Notes}	\label{sec:rel-2.8}

\index{Alpha, DEC}\index{DEC, Alpha}%
With version 2.8, we declare the data-representation changes of 2.7.x
stable. Version 2.8 exploits the changes of 2.7 to support 64-bit
processors like the DEC Alpha. As of version 2.8.5, the representation
of recorded terms has changed, and terms on the heap are now
represented in a compiled format. SWI-Prolog no longer limits the use of
malloc() or uses assumptions on the addresses returned by this
function.

\subsection*{Version 2.9 Release Notes}	\label{sec:rel-2.9}

Version 2.9 is the next step towards version 3.0, improving ISO
compliance and introducing ISO compliant exception handling. New are
catch/3, throw/1, abolish/1, write_term/[2,3], write_canonical/[1,2] and
the C-functions PL_exception() and PL_throw(). The predicates
display/[1,2] and displayq/[1,2] have been moved to \pllib{backcomp}, so
old code referring to them will autoload them.

The interface to PL_open_query() has changed.  The \arg{debug} argument
is replaced by a bitwise or'ed \arg{flags} argument.  The values
\const{FALSE} and \const{TRUE} have their familiar meaning, making old
code using these constants compatible. Non-zero values other than
\const{TRUE} (1) will be interpreted different.


\subsection*{Version 3.0 Release Notes}	\label{sec:rel-3.0}

Complete redesign of the saved-state mechanism, providing the
possibility of `program resources'. See resource/3, open_resource/3, and
qsave_program/[1,2].


\subsection*{Version 3.1 Release Notes}	\label{sec:rel-3.1}

Improvements on exception-handling. Allows relating software interrupts
(signals) to exceptions, handling signals in Prolog and C (see
on_signal/3 and PL_signal()).  Prolog stack overflows now raise
the \const{resource_error} exception and thus can be handled in
Prolog using catch/3.


\subsection*{Version 3.3 Release Notes}	\label{sec:rel-3.3}

Version 3.3 is a major release, changing many things internally and
externally.  The highlights are a complete redesign of the high-level
I/O system, which is now based on explicit streams rather then current
input/output.  The old Edinburgh predicates (see/1, tell/1, etc.) are
now defined on top of this layer instead of the other way around.  This
fixes various internal problems and removes Prolog limits on the number
of streams.

Much progress has been made to improve ISO compliance: handling strings
as lists of one-character atoms is now supported (next to character
codes as integers). Many more exceptions have been added and printing of
exceptions and messages is rationalised using Quintus and SICStus Prolog
compatible print_message/2, message_hook/3 and print_message_lines/3.
All predicates described in \cite{Deransart:96} are now implemented.

As of version 3.3, SWI-Prolog adheres the ISO \jargon{logical update view}
for dynamic predicates.  See \secref{update} for details.

SWI-Prolog 3.3 includes garbage collection on atoms, removing the last
serious memory leak especially in text-manipulation applications. See
\secref{atomgc}. In addition, both the user-level and foreign interface
supports atoms holding \jargon{0-bytes}.

Finally, an alpha version of a multi-threaded SWI-Prolog for Linux is
added. This version is still much slower than the single-threaded
version due to frequent access to `thread-local-data' as well as some
too detailed mutex locks. The basic thread API is ready for serious
use and testing however.  See \secref{threads}.


\subsubsection*{Incompatible changes}

A number of incompatible changes result from this upgrade.  They
are all easily fixed however.

\begin{itemlist}
    \item [\predref{!}{0}, call/1]
The cut now behaves according to the ISO standard. This implies it works
in compound goals passed to call/1 and is local to the {\em condition}
part of if-then-else as well as the argument of \predref{\+}{1}.
    \item [atom_chars/2]
This predicate is now ISO compliant and thus generates a list of
one-character atoms.  The behaviour of the old predicate is available
in the ---also ISO compliant--- atom_codes/2 predicate.  Safest repair
is a replacement of all \const{atom_chars} into \const{atom_codes}.  If
you do not want to change any source-code, you might want to use

\begin{code}
user:goal_expansion(atom_chars(A,B), atom_codes(A,B)).
\end{code}
    \item [number_chars/2]
Same applies for number_chars/2 and number_codes/2.
    \item [\nopredref{feature}{2}, \nopredref{set_feature}{2}]
These are replaced by the ISO compliant current_prolog_flag/2 and
set_prolog_flag/2.  The library \pllib{backcomp} provides definitions
for these predicates, so no source {\bf must} be updated.
    \item [Accessing command-line arguments]
This used to be provided by the undocumented '\$argv'/1 and Quintus
compatible library unix/1.  Now there is also documented
\term{current_prolog_flag}{argv, Argv}.
    \item [dup_stream/2]
Has been deleted.  New stream-aliases can deal with most of the problems
for which dup_stream/2 was designed and dup/2 from the \jargon{clib}
package can with most others.
    \item [op/3]
Operators are now {\bf local to modules}.  This implies any modification
of the operator-table does not influence other modules. This is
consistent with the proposed ISO behaviour and a necessity to have
any usable handling of operators in a multi-threaded environment.
    \item [set_prolog_flag(character_escapes, Bool)]
This Prolog flag is now an interface to changing attributes on the
current source-module, effectively making this flag module-local as
well.  This is required for consistent handling of sources written
with ISO (obligatory) character-escape sequences together with old
Edinburgh code.
    \item [current_stream/3 and stream_position]
These predicates have been moved to \pllib{quintus}.
\end{itemlist}


\subsection*{Version 3.4 Release Notes}	\label{sec:rel-3.4}

The 3.4 release is a consolidation release. It consolidates the
improvements and standard conformance of the 3.3 releases.  This
version is closely compatible with the 3.3 version except for one
important change:

\begin{itemlist}
    \item [Argument order in select/3]
The list-processing predicate select/3 somehow got into a very early
version of SWI-Prolog with the wrong argument order.  This has been
fixed in 3.4.0.  The correct order is select(?Elem, ?List, ?Rest).

As select/3 has no error conditions, runtime checking cannot be done.
To simplify debugging, the library module \pllib{checkselect} will
print references to select/3 in your source code and install a version
of select that enters the debugger if select is called and the second
argument is not a list.

This library can be loaded explicitly or by calling check_old_select/0.
\end{itemlist}


\subsection*{Version 4.0 Release Notes}	\label{sec:rel-4.0}

As of version 4.0 the standard distribution of SWI-Prolog is bundled
with a number of its popular extension packages, among which the now
open source XPCE GUI toolkit (see \secref{xpce}). No significant changes
have been made to the basic SWI-Prolog engine.

Some useful tricks in the integrated environment:

\begin{itemlist}
    \item [Register the GUI tracer]
Using a call to guitracer/0, hooks are installed that replace the normal
command-line driven tracer with a graphical front-end.

    \item [Register PceEmacs for editing files]
From your initialisation file. you can load \pllib{emacs/swi_prolog} that
cause edit/1 to use the built-in PceEmacs editor.
\end{itemlist}


\subsection*{Version 5.0 Release Notes} \label{sec:rel-5.0}

Version 5.0 marks a breakpoint in the philosophy, where SWI-Prolog
moves from a dual GPL/proprietary to a uniform LGPL (Lesser GNU Public
Licence) schema, providing a widely usable Free Source Prolog
implementation.

On the technical site the development environment, consisting of
source-level debugger, integrated editor and various analysis and
navigation tools progress steadily towards a mature set of tools.

Many portability issues have been improved, including a port to
MacOS X (Darwin).

For details, please visit the new website at
\url{http://www.swi-prolog.org}


\subsection*{Version 5.1 Release Notes} \label{sec:rel-5.1}

Version 5.1 is a beta-serie introducing portable multi-threading. See
\chapref{threads}.  In addition it introduces many new facilities to
support server applications, such as the new \pllib{rlimit} library
to limit system resources and the possibility to set timeouts on
input streams.


\subsection*{Version 5.2 Release Notes} \label{sec:rel-5.2}

Version 5.2 consolidates the 5.1.x beta series that introduced threading
and many related modifications to the kernel.


\subsection*{Version 5.3 Release Notes} \label{sec:rel-5.3}

Version 5.3.x is a development series for adding coroutining,
constraints, global variables, cyclic terms (infinite trees) and other
goodies to the kernel.  The package JPL, providing a bidirectional
Java/Prolog interface is added to the common source-tree and common
binary packages.


\subsection*{Version 5.4 Release Notes} \label{sec:rel-5.4}

Version 5.4 consolidates the 5.3.x beta series.


\subsection*{Version 5.5 Release Notes} \label{sec:rel-5.5}

Version 5.5.x provides support for \jargon{wide characters} with UTF-8
and UNICODE I/O (\secref{encoding}). On both 32 and 64-bit hardware
Prolog integers are now at minimum 64-bit integers. If available,
SWI-Prolog arithmetic uses the GNU GMP library to provided
\jargon{unbounded} integer arithmetic as well as rational arithmetic.
Adding GMP support is sponsored by Scientific Software and Systems
Limited, \url{www.sss.co.nz}. This version also incorporates clp(r) by
Christian Holzbaur, brought to SWI-Prolog by Tom Schrijvers and Leslie
De Koninck (\secref{lib:clpqr}).

\subsection*{Version 5.6 Release Notes} \label{sec:rel-5.6}

Version 5.6 consolidates the 5.5.x beta series.

\subsection*{Version 5.7 Release Notes} \label{sec:rel-5.7}

The aim of the 5.7 series is to cleanup much of the system. Notably, the
virtual machine has a much simpler setup that makes it much easier to
add new instructions. This facility has been exploited to enhance
performance and provide proper support for the meta_predicate/1
directive for enhanced portability.

\subsection*{Version 5.10 Release Notes} \label{sec:rel-5.10}

The 5.9 series has enhanced SWI-Prolog in terms of memory management,
scalability and robustness.  Notable, threads are much cheaper and now
limited in count only by the OS.  Database and stream-handles have
becomes safe.  Compatibility to YAP and SISCtus has been improved.


\section{Donate to the SWI-Prolog project}	\label{sec:sponsor}

If you are happy with SWI-Prolog, you care it to be around for much
longer while it becomes faster, more stable and with more features
you should consider to donate to the SWI-Prolog foundation.  Please
visit the page below.

\begin{quote}
\url{http://www.swi-prolog.org/donate.html}
\end{quote}


\section{Acknowledgements}	\label{sec:acknowledge}

Some small parts of the Prolog code of SWI-Prolog are modified
versions of the corresponding Edinburgh C-Prolog code: grammar rule
compilation and writef/2.  Also some of the C-code originates from
C-Prolog: finding the path of the currently running executable and
some of the code underlying absolute_file_name/2. Ideas on programming
style and techniques originate from C-Prolog and Richard O'Keefe's {\em
thief} editor. An important source of inspiration are the programming
techniques introduced by Anjo Anjewierden in PCE version~1 and~2.

I also would like to thank those who had the fade of using the early
versions of this system, suggested extensions or reported bugs.  Among
them are Anjo Anjewierden, Huub Knops, Bob Wielinga, Wouter Jansweijer,
Luc Peerdeman, Eric Nombden, Frank van Harmelen, Bert Rengel.

Martin Jansche (\email{jansche@novell1.gs.uni-heidelberg.de}) has been
so kind to reorganise the sources for version 2.1.3 of this manual.

Horst von Brand has been so kind to fix many typos in the 2.7.14 manual.
Thanks!

Bart Demoen and Tom Schrijvers have helped me adding coroutining,
constraints, global variables and support for cyclic terms to the
kernel.  Tom has provided the integer interval constraint solver,
the CHR compiler and some of the coroutining predicates.

Paul Singleton has integrated Fred Dushin's Java-calls-Prolog side
with his Prolog-calls-Java side into the current bidirectional JPL
interface package.

Richard O'Keefe is gratefully acknowledged for his efforts to educate
beginners as well as valuable comments on proposed new developments.

Scientific Software and Systems Limited, \url{www.sss.co.nz} has
sponsored the development if the SSL library as well as unbounded
integer and rational number arithmetic.

Leslie de Koninck has made clp(QR) available to SWI-Prolog.

Markus Triska has contributed to various libraries.

Paulo Moura's great experience in maintaining Logtalk for many Prolog
systems including SWI-Prolog has helped in many places fixing
compatibility issues.  He also worked on the MacOS port and fixed many
typos in the 5.6.9 release of the documentation.