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

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

SWI-Prolog has been designed and implemented to get a Prolog
implementation which can be used for experiments with logic programming
and the relation to other programming paradigms. The intention was to
build a Prolog environment which offers enough power and flexibility to
write substantial applications, but is straightforward enough to be
modified for experiments with debugging, optimisation or the
introduction of non-standard data types. Performance optimisation is
limited due to the main objectives:  portability (SWI-Prolog is
entirely written in C and Prolog) and modifiability.

SWI-Prolog is based on a very restricted form of the WAM (Warren
Abstract Machine) described in \cite{Bowen:83} 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 WAM
interpreter 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 WAM
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{Other 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
confirm 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 and two large workbenches
for knowledge engineering. Although we experienced 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). Many 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]
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 and Win32 (Windows 95 and NT).
\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.
    \item [`Answer' reuse]
The toplevel maintains a table of bindings returned by toplevel 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 to 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
\funcref{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 descriped 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 souce-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 [feature/2, 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 feature/2 and set_feature/2, so no source {\bf has} to 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 explicitely 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 forntend.
    \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}


\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 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!