swi-prolog-nox 7.6.4+dfsg-1build1 / usr / lib / swi-prolog / library / MANUAL

 VU University Amsterdam                          University of Amsterdam

~  De1Boelelaan01081a,81 HV  Amsterdam              KruislaanV419,A1098Amsterdam
     The Netherlands                                  The Netherlands

                             SWI-Prolog 7.6
                            Reference Manual
                _U_p_d_a_t_e_d _f_o_r _v_e_r_s_i_o_n _7_._6_-_4_, _J_a_n_u_a_r_y _2_0_1_8

                             _J_a_n _W_i_e_l_e_m_a_k_e_r
                           J.Wielemaker@vu.nl
                       http://www.swi-prolog.org

    SWI-Prolog  is a  comprehensive and portable  implementation of
    the  Prolog  programming language.    SWI-Prolog  aims to  be a
    robust  and scalable implementation supporting  a wide range of
    applications.   In  particular, it  ships with a  wide range of
    interface  libraries, providing interfaces  to other languages,
    databases,  graphics  and networking.    It  provides extensive
    support  for  managing HTML/SGML/XML  and RDF  documents.   The
    system  is particularly suited  for server  applications due to
    robust support for multithreading and HTTP server libraries.

    SWI-Prolog  is  designed  in the  `Edinburgh  tradition'.    In
    addition  to the ISO  Prolog standard it  is largely compatible
    to  Quintus, SICStus  and YAP  Prolog.   SWI-Prolog  provides a
    compatibility  framework developed in cooperation  with YAP and
    instantiated for YAP, SICStus and IF/Prolog.

    SWI-Prolog  aims at  providing a good  development environment,
    including  extensive  editor  support,  graphical  source-level
    debugger,   autoloading  and `make'  facility  and  much  more.
    SWI-Prolog  editor  and  the  PDT  plugin  for Eclipse  provide
    alternative environments.

    This  document gives an overview of the features, system limits
    and built-in predicates.


~

    This  work is licensed under  the Creative Commons Attribution-
    ShareAlike  3.0  Unported License.    To  view a  copy  of this
    license,  visit  http://creativecommons.org/licenses/by-sa/3.0/
    or  send a letter to Creative Commons, 444 Castro Street, Suite
    900, Mountain View, California, 94041, USA.


CChhaapptteerr 11..  IINNTTRROODDUUCCTTIIOONN

This document is a  _r_e_f_e_r_e_n_c_e _m_a_n_u_a_l.  That means that it  documents the
system, but it  does not explain the  basics of the Prolog language  and
it leaves many details of the syntax, semantics  and built-in primitives
undefined  where SWI-Prolog  follows  the standards.    This  manual  is
intended  for people  that are  familiar with  Prolog.    For those  not
familiar with Prolog, we recommend to start with  a Prolog textbook such
as [??], [??] or [??].  For more advanced Prolog usage we recommend [??].


11..11 PPoossiittiioonniinngg SSWWII--PPrroolloogg

Most implementations  of the  Prolog language  are designed  to serve  a
limited set  of use cases.    SWI-Prolog is no  exception to this  rule.
SWI-Prolog  positions  itself  primarily as  a  Prolog  environment  for
`programming in the large'  and use cases where it plays a  central role
in an  application, i.e.,  where it acts  as `glue' between  components.
At  the same  time,  SWI-Prolog aims  at  providing a  productive  rapid
prototyping environment.    Its orientation towards  programming in  the
large is backed  up by scalability, compiler speed,  program structuring
(modules), support  for multithreading  to accommodate servers,  Unicode
and interfaces  to a  large number  of document  formats, protocols  and
programming languages.   Prototyping is facilitated by good  development
tools,  both  for  command  line  usage  as  for  usage  with  graphical
development tools.   Demand loading of  predicates from the library  and
a  `make' facility  avoids the  _r_e_q_u_i_r_e_m_e_n_t for  using declarations  and
reduces typing.

SWI-Prolog is traditionally  strong in education because it is  free and
portable, but also  because of its compatibility with textbooks  and its
easy-to-use environment.

Note that these  positions do not imply  that the system cannot be  used
with other scenarios.  SWI-Prolog is used as  an embedded language where
it serves as a small rule subsystem in a large application.   It is also
used as a  deductive database.  In  some cases this is the right  choice
because SWI-Prolog  has features that are  required in the  application,
such as threading or  Unicode support.  In general though,  for example,
GNU-Prolog is  more suited  for embedding  because it is  small and  can
compile to  native code, XSB is  better for deductive databases  because
it provides  advanced resolution  techniques (tabling),  and ECLiPSe  is
better at constraint handling.

The  syntax  and  set  of  built-in  predicates  is  based  on  the  ISO
standard [??].   Most extensions follow the `Edinburgh  tradition' (DEC10
Prolog  and  C-Prolog) and  Quintus  Prolog  [??].    The  infrastructure
for constraint  programming is  based on  hProlog [??].   Some  libraries
are  copied from  the YAP  system.   Together  with YAP  we developed  a
portability framework (see section ????).  This framework  has been filled
for  SICStus Prolog,  YAP, IF/Prolog  and Ciao.    SWI-Prolog version  7
introduces various extensions  to the Prolog language (see section  ????).
The _s_t_r_i_n_g data  type and its supporting  set of built-in predicates  is
compatibility with ECLiPSe.


11..22 SSttaattuuss aanndd rreelleeaasseess

This manual describes version  7.6 of SWI-Prolog.  SWI-Prolog  is widely
considered to  be a  robust and  scalable implementation  of the  Prolog
language.   It is widely used in  education and research.  In  addition,
it  is in  use for  247* mission  critical commercial  server processes.
The site http://www.swi-prolog.org  is hosted using the SWI-Prolog  HTTP
server  infrastructure.    It receives  approximately 2.3  million  hits
and serves  approximately 300 Gbytes on  manual data and downloads  each
month.    SWI-Prolog  applications  range from  student  assignments  to
commercial  applications that  count  more  than one  million  lines  of
Prolog code.

SWI-Prolog has  two development tracks.   _S_t_a_b_l_e  releases have an  even
_m_i_n_o_r version  number (e.g., 6.2.1)  and are released  as a branch  from
the  development version  when  the  development version  is  considered
stable and  there is sufficient  new functionality  to justify a  stable
release.   Stable releases often  get a few  patch updates to deal  with
installation  issues or  major flaws.    A  new _D_e_v_e_l_o_p_m_e_n_t  version  is
typically released  every couple of  weeks as a  snapshot of the  public
git  repository.    `Extra  editions'  of the  development  version  may
be released  after problems  that severely  hindered the  user in  their
progress have been fixed.

Known  bugs that  are  not likely  to be  fixed  soon are  described  as
footnotes in this manual.


11..33 SShhoouulldd II bbee uussiinngg SSWWII--PPrroolloogg??

There  are a  number of  reasons  why it  might be  better  to choose  a
commercial, or another free, Prolog system:

  o _S_W_I_-_P_r_o_l_o_g _c_o_m_e_s _w_i_t_h _n_o _w_a_r_r_a_n_t_i_e_s
    Although   the  developers   or  the  community   often  provide   a
    work-around or a fix for  a bug, there is no place you can go to for
    guaranteed  support.  However, the full source archive  is available
    and can be used  to compile and debug SWI-Prolog using free tools on
    all  major platforms.   Users requiring  more support should  ensure
    access to knowledgeable developers.

  o _P_e_r_f_o_r_m_a_n_c_e _i_s _y_o_u_r _f_i_r_s_t _c_o_n_c_e_r_n
    Various  free and commercial systems have better performance.   But,
    `standard'  Prolog benchmarks disregard many factors that  are often
    critical  to the performance of  large applications.  SWI-Prolog  is
    not  good  at fast  calling of  simple  predicates and  if-then-else
    selection  based  on simple  built-in tests,  but  it is  fast  with
    dynamic  code,   meta-calling  and  predicates  that  contain  large
    numbers  of clauses.   Many of SWI-Prolog's built-in predicates  are
    written in C and have excellent performance.

  o _Y_o_u _n_e_e_d _f_e_a_t_u_r_e_s _n_o_t _o_f_f_e_r_e_d _b_y _S_W_I_-_P_r_o_l_o_g
    Although SWI-Prolog has  many features, it also lacks some important
    features.   The  most well known  is probably _t_a_b_l_i_n_g [??].   If  you
    require additional features  and you have resources, be it financial
    or expertise, please contact the developers.

On the  other hand,  SWI-Prolog offers some  facilities that are  widely
appreciated by users:

  o _N_i_c_e _e_n_v_i_r_o_n_m_e_n_t
    SWI-Prolog  provides a good command line environment,  including `Do
    What I Mean',  autocompletion, history and a tracer that operates on
    single  key strokes.   The system automatically recompiles  modified
    parts  of the source code using the make/0 command.  The  system can
    be  instructed to  open an arbitrary  editor on  the right file  and
    line based on its  source database.  It ships with various graphical
    tools  and can be combined with the SWI-Prolog editor,  PDT (Eclipse
    plugin for Prolog) or GNU-Emacs.

  o _F_a_s_t _c_o_m_p_i_l_e_r
    Even  very  large applications  can  be loaded  in seconds  on  most
    machines.   If this is not  enough, there is the Quick  Load Format.
    See qcompile/1 and qsave_program/2.

  o _T_r_a_n_s_p_a_r_e_n_t _c_o_m_p_i_l_e_d _c_o_d_e
    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, and the  performance of debugged code  is close to that  of
    normal operation.

  o _S_o_u_r_c_e _l_e_v_e_l _d_e_b_u_g_g_e_r
    The  source  level   debugger  provides  a  good  overview  of  your
    current  location  in  the  search  tree,  variable  bindings,  your
    source  code  and  open choice  points.    Choice  point  inspection
    provides  meaningful insight to both novices and  experienced users.
    Avoiding unintended choice  points often provides a huge increase in
    performance and a huge saving in memory usage.

  o _P_r_o_f_i_l_i_n_g
    SWI-Prolog  offers an execution profiler with either  textual output
    or  graphical output.   Finding and  improving hotspots in a  Prolog
    program may result in huge speedups.

  o _F_l_e_x_i_b_i_l_i_t_y
    SWI-Prolog  can  easily   be  integrated  with  C,  supporting  non-
    determinism  in Prolog calling  C as well  as C calling Prolog  (see
    section  ????).   It can  also be _e_m_b_e_d_d_e_d  in external programs  (see
    section ????).   System predicates can be redefined locally to provide
    compatibility with other Prolog systems.

  o _T_h_r_e_a_d_s
    Robust  support for multiple threads may improve performance  and is
    a key enabling factor for deploying Prolog in server applications.

  o _I_n_t_e_r_f_a_c_e_s
    SWI-Prolog   ships  with  many   extension  packages  that   provide
    robust  interfaces  to processes,  encryption,  TCP/IP, TIPC,  ODBC,
    SGML/XML/HTML, RDF, HTTP, graphics and much more.


11..44 SSuuppppoorrtt tthhee SSWWII--PPrroolloogg pprroojjeecctt

You  can support  the SWI-Prolog  project in  several ways.    Academics
are  invited to  cite one  of the  publications on  SWI-Prolog.    Users
can  help  by  identifying and/or  fixing  problems  with  the  code  or
its  documentation..    Users  can  contribute  new  features  or,  more
lightweight,   contribute  packs.      Commercial  users  may   consider
contacting the  developers to  sponsor the development  of new  features
or seek  for opportunities  to cooperate  with the  developers or  other
commercial users.


11..55 IImmpplleemmeennttaattiioonn hhiissttoorryy

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.  In those days Prolog  systems were
not very  aware of  their 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 simple  Prolog  virtual machine  called  ZIP
[??,  ??] 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  in debug  mode compared  to
normal  execution.    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
[??]  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  (;/2,  |/2), if-then  (->/2)  and
negation-by-failure (\+/1).


11..66 AAcckknnoowwlleeddggeemmeennttss

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 _t_h_i_e_f  editor.
An  important  source  of inspiration  are  the  programming  techniques
introduced by Anjo Anjewierden in PCE version 1 and 2.

Our special  thanks go  to those  who had the  fate 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  (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!
Randy Sharp fixed many issues in the 6.0.x version of the manual.

Bart  Demoen and  Tom  Schrijvers  have helped  me  adding  coroutining,
constraints,  global  variables and  support  for  cyclic terms  to  the
kernel.  Tom Schrijvers has provided a first  clp(fd) constraint solver,
the CHR compiler and some of the coroutining predicates.   Markus Triska
contributed the  current clp(fd)  implementation as well  as the  clp(b)
implementation.

Tom  Schrijvers  and   Bart  Demoen  initiated  the  implementation   of
_d_e_l_i_m_i_t_e_d _c_o_n_t_i_n_u_a_t_i_o_n_s (section ????), which was used  by Benoit Desouter
and  Tom Schrijvers  to implement  _t_a_b_l_i_n_g (section  ????)  as a  library.
Fabrizio Riguzzi added a first implementation for  _m_o_d_e _d_i_r_e_c_t_e_d _t_a_b_l_i_n_g
(section ????).

The  SWI-Prolog 7  extensions (section  ????)  are the  result of  a  long
heated discussion on  the mailinglist.   Nicos Angelopoulos' wish for  a
smooth integration with  the R language triggered the overall  intend of
these extensions to  enable a smoother integration of Prolog  with other
languages.    Michael Hendrix  suggested and  helped shaping  SWI-Prolog
_q_u_a_s_i _q_u_o_t_a_t_i_o_n_s.

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,  www.sss.co.nz has  sponsored
the  development of  the SSL  library,  unbounded integer  and  rational
number arithmetic and many enhancements to the memory  management of the
system.

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

Jeff  Rosenwald contributed  the TIPC  networking  library and  Google's
protocol buffer handling.

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.

Kyndi  (https://kyndi.com/) sponsored  the  development of  the  _e_n_g_i_n_e_s
interface (chapter ????).  The final API was  established after discussion
with the founding father of engines, Paul Tarau and Paulo  Moura.  Kyndi
also sponsored JIT indexing on multiple arguments.


CChhaapptteerr 22..  OOVVEERRVVIIEEWW


22..11 GGeettttiinngg ssttaarrtteedd qquuiicckkllyy


22..11..11 SSttaarrttiinngg SSWWII--PPrroolloogg


22..11..11..11 SSttaarrttiinngg SSWWII--PPrroolloogg oonn UUnniixx

By  default, SWI-Prolog  is  installed as  `swipl'.   The  command  line
arguments of SWI-Prolog  itself and its utility programs are  documented
using standard Unix  man pages.   SWI-Prolog is normally operated as  an
interactive application simply by starting the program:

________________________________________________________________________|                                                                        |
|$ swipl                                                                 |

|Welcome to SWI-Prolog ...                                               |
|...                                                                     |
|                                                                        |
|1|?-___________________________________________________________________ | |

After  starting   Prolog,  one   normally  loads   a  program  into   it
using   consult/1,   which   may   be   abbreviated   by   putting   the
name   of   the  program   file   between   square  brackets.        The
following  goal loads  the  file  https://raw.githubusercontent.com/SWI-
Prolog/swipl-devel/master/demo/likes.pllikes.pl  containing clauses  for
the predicates likes/2:

________________________________________________________________________|                                                                        |
|?- [likes].                                                             |
|true.                                                                   |

|                                                                        |
|?-|____________________________________________________________________ |  |

Alternatively, the source file may be given as command line arguments:

________________________________________________________________________|                                                                        |
|$ swipl likes.pl                                                        |
|Welcome to SWI-Prolog ...                                               |
|...                                                                     |
|                                                                        |

|1|?-___________________________________________________________________ | |

After this  point, Unix  and Windows users  unite, so  if you are  using
Unix please continue at section ????.


22..11..11..22 SSttaarrttiinngg SSWWII--PPrroolloogg oonn WWiinnddoowwss

After SWI-Prolog has been  installed on a Windows system,  the following
important new things are available to the user:

  o A  folder  (called  _d_i_r_e_c_t_o_r_y in  the  remainder of  this  document)
    called  swipl containing  the executables, libraries,  etc., of  the
    system.  No files are installed outside this directory.

  o A  program swipl-win.exe,  providing a  window for interaction  with
    Prolog.  The  program swipl.exe is a version of SWI-Prolog that runs
    in a console window.

  o The  file  extension  .pl  is associated  with  the  program  swipl-
    win.exe.    Opening a .pl  file will  cause swipl-win.exe to  start,
    change  directory  to  the  directory  in which  the  file  to  open
    resides, and load this file.

The normal way to start the likes.pl file mentioned in  section ???? is by
simply double-clicking this file in the Windows explorer.


22..11..22 AAddddiinngg rruulleess ffrroomm tthhee ccoonnssoollee

Although we strongly  advice to put your  program in a file,  optionally
edit it and use make/0 to reload it (see section ????),  it is possible to
manage facts and  rules from the terminal.   The most conveniant way  to
add a few clauses is  by consulting the pseudo file user.  The  input is
ended using the system end-of-file character.

________________________________________________________________________|                                                                        |
|?- [user].                                                              |

||: hello :- format('Hello world~n').                                    |
||: ^D                                                                   |
|true.                                                                   |
|                                                                        |
|?- hello.                                                               |
|Hello world                                                             |
|true.|_________________________________________________________________ |     |

The  predicates assertz/1  and  retract/1 are  alternatives to  add  and
remove rules and facts.


22..11..33 EExxeeccuuttiinngg aa qquueerryy

After loading a program,  one can ask Prolog queries about  the program.
The query below asks Prolog what food `sam' likes.   The system responds
with X = <_v_a_l_u_e> if it can prove the goal for a certain _X. The  user can
type the  semi-colon (;)  or spacebar if  (s)he wants another  solution.
Use the return key if  you do not want to see the more answers.   Prolog
completes the output with a  full stop (.)  if the user uses  the return
key or Prolog  _k_n_o_w_s there are no more  answers.  If Prolog cannot  find
(more) answers,  it  writes ffaallssee..    Finally, Prolog  answers using  an
error message to indicate the query or program contains an error.

________________________________________________________________________|                                                                        |
|?- likes(sam, X).                                                       |

|X = dahl ;                                                              |
|X = tandoori ;                                                          |
|...                                                                     |
|X = chips.                                                              |
|                                                                        |
|?-|____________________________________________________________________ |  |

Note  that the  answer  written by  Prolog  is  a valid  Prolog  program
that, when  executed, produces the same  set of answers as the  original
program.


22..11..44 EExxaammiinniinngg aanndd mmooddiiffyyiinngg yyoouurr pprrooggrraamm

If  properly configured,  the predicate  edit/1 starts  the built-in  or
user configured editor  on the argument.   The argument can be  anything
that can be linked to  a location:  a file name, predicate  name, module
name, etc.  If the argument resolves to only one  location the editor is
started on this location, otherwise the user is presented a choice.

If a graphical user interface is available, the  editor normally creates
a new  window and the  system prompts for  the next command.   The  user
may edit the source file, save it and run make/0  to update any modified
source file.   If the editor  cannot be opened in  a window it the  same
console and leaving  the editor runs make/0  to reload any source  files
that have been modified.

________________________________________________________________________|                                                                        |
|?- edit(likes).                                                         |
|                                                                        |
|true.                                                                   |

|?- make.                                                                |
|% /home/jan/src/pl-devel/linux/likes compiled 0.00 sec, 0 clauses       |
|                                                                        |
|?- likes(sam, X).                                                       |
|...|___________________________________________________________________ |   |

The  program can  also be  _d_e_c_o_m_p_i_l_e_d using  listing/1 as  below.    The
argument is  listing/1 is just a  predicate name, a predicate  _i_n_d_i_c_a_t_o_r
of  the form  _N_a_m_e_/_A_r_i_t_y, e.g.,  ?- listing(mild/1).  or a  _h_e_a_d,  e.g.,
?- listing(likes(sam, _)., listing all _m_a_t_c_h_i_n_g clauses.   The predicate
listing/0, i.e., without arguments lists the entire program.

________________________________________________________________________|                                                                        |
|?- listing(mild).                                                       |

|mild(dahl).                                                             |
|mild(tandoori).                                                         |
|mild(kurma).                                                            |
|                                                                        |
|true.|_________________________________________________________________ |     |


22..11..55 SSttooppppiinngg PPrroolloogg

The interactive toplevel can  be stopped in two ways:  enter  the system
end-of-file character (typically  _C_o_n_t_r_o_l_-_D) or by executing the  halt/0
predicate:

________________________________________________________________________|                                                                        |
|?- halt.                                                                |

|$|_____________________________________________________________________ | |


22..22 TThhee uusseerr''ss iinniittiiaalliissaattiioonn ffiillee

After the  system initialisation,  the system  consults (see  consult/1)
the user's startup file.  The basename of  this file follows conventions
of  the operating  system.   On  MS-Windows,  it is  the file  swipl.ini
and  on  Unix  systems  .swiplrc.    The  file  is  searched  using  the
file_search_path/2 clauses for user_profile.  The table below  shows the
default value for this search  path.  The phrase <_a_p_p_d_a_t_a> refers to the
Windows CSIDL  name for  the folder.   The  actual name  depends on  the
Windows language.  English versions typically use ApplicationData.   See
also win_folder/2

                   __________________________________
                   |____________|UUnniixx__||WWiinnddoowwss__________________________ ||
                   ||_hhoommee_||~___|<_a_p_p_d_a_t_a>/SWI-Prolog_|

After the  first startup  file is found  it is  loaded and Prolog  stops
looking for further startup files.  The name of the  startup file can be
changed with the  `-f file' option.   If _F_i_l_e denotes an absolute  path,
this file is loaded,  otherwise the file is searched for using  the same
conventions as for the default startup file.  Finally,  if _f_i_l_e is none,
no file is loaded.

The installation provides  a file customize/dotswiplrc with  (commented)
commands that are often used to customize the behaviour  of Prolog, such
as interfacing  to the  editor, color selection  or history  parameters.
Many  of the  development tools  provide menu  entries  for editing  the
startup  file  and  starting  a  fresh  startup  file  from  the  system
skeleton.

See  also  the  -s  (script)  and  -F  (system-wide  initialisation)  in
section ???? and section ????.


22..33 IInniittiiaalliissaattiioonn ffiilleess aanndd ggooaallss

Using  command  line arguments  (see  section  ????),  SWI-Prolog  can  be
forced to load files and execute queries for  initialisation purposes or
non-interactive operation.   The most commonly used options  are -f file
or -s file to make Prolog load a file,  -g goal to define initialisation
goals and  -t goal to define  the _t_o_p_-_l_e_v_e_l  _g_o_a_l.   The following is  a
typical example  for starting an application  directly from the  command
line.

________________________________________________________________________|                                                                        |
|machine%|swipl_-s_load.pl_-g_go_-t_halt________________________________ |        |

It  tells  SWI-Prolog to  load  load.pl,  start  the  application  using
the _e_n_t_r_y  _p_o_i_n_t go/0  and ---instead  of entering  the interactive  top
level--- exit after completing go/0.

The command line may  have multiple -g goal occurrences.  The  goals are
executed  in order.    Possible choice  points of  individual goals  are
pruned.  If a _g_o_a_l fails execution stops with exit status 1.   If a _g_o_a_l
raises an  exception, the  exception is  printed and  the process  stops
with exit code 2.

The -q  may be used  to suppress all informational  messages as well  as
the error  message that is  normally printed  if an initialisation  goal
_f_a_i_l_s.

In  MS-Windows,  the  same  can  be  achieved  using  a  short-cut  with
appropriately  defined  command  line  arguments.     A  typically  seen
alternative  is to  write  a file  run.pl  with content  as  illustrated
below.  Double-clicking run.pl will start the application.

________________________________________________________________________|                                                                        |

|:- [load].                      % load program                          |
|:- go.                          % run it                                |
|:-|halt.________________________%_and_exit_____________________________ |  |

Section  ????  discusses   further  scripting  options,  and   chapter  ????
discusses the  generation of runtime executables.   Runtime  executables
are  a means  to deliver  executables  that do  not require  the  Prolog
system.


22..44 CCoommmmaanndd lliinnee ooppttiioonnss

SWI-Prolog can be executed in one of the following modes:

swipl --help
swipl --version
swipl --arch
swipl --dump-runtime-variables
    These  options must appear  as only  option.   They cause Prolog  to
    print an informational message and exit.  See section ????.

swipl [[_o_p_t_i_o_n ......]]  _s_c_r_i_p_t_-_f_i_l_e [[_a_r_g ......]]
    These arguments are  passed on Unix systems if file that starts with
    #!/path/to/executable [_o_p_t_i_o_n ...]  is  executed.   Arguments  after
    the script file are made available in the Prolog flag argv.

swipl [[_o_p_t_i_o_n ......]]  _p_r_o_l_o_g_-_f_i_l_e ......  [[[[--]] _a_r_g ......]]
    This  is the normal way to start Prolog.  The options  are described
    in  section ????, section  ???? and section  ????.   The Prolog flag  argv
    provides  access  to  _a_r_g  ...    If  the _o_p_t_i_o_n_s  are  followed  by
    one  or more  Prolog file  names  (i.e., names  with extension  .pl,
    .prolog  or (on  Windows)  the user  preferred extension  registered
    during  installation),  these files  are  loaded.   The  first  file
    is  registered in  the Prolog  flag associated_file.   In  addition,
    pl-win[.exe] switches to  the directory in which this primary source
    file is located using working_directory/2.

swipl --oo _o_u_t_p_u_t --cc _p_r_o_l_o_g_-_f_i_l_e ......
    The  -c option  is used to  compile a  set of Prolog  files into  an
    executable.  See section ????.

swipl --oo _o_u_t_p_u_t --bb _b_o_o_t_f_i_l_e _p_r_o_l_o_g_-_f_i_l_e ......
    Bootstrap compilation.  See section ????.


22..44..11 IInnffoorrmmaattiioonnaall ccoommmmaanndd lliinnee ooppttiioonnss

--arch
    When   given  as  the  only  option,  it  prints   the  architecture
    identifier   (see  Prolog  flag   arch)  and  exits.      See   also
    -dump-runtime-variables.  Also available as -arch.

--dump-runtime-variables _[_=_f_o_r_m_a_t_]
    When  given as  the only option,  it prints  a sequence of  variable
    settings   that  can  be  used   in  shell  scripts  to  deal   with
    Prolog  parameters.   This  feature is  also used  by swipl-ld  (see
    section ????).  Below is a typical example of using this feature.

    ____________________________________________________________________|                                                                    |
    | eval `swipl --dump-runtime-variables`                              |

    ||cc_-I$PLBASE/include_-L$PLBASE/lib/$PLARCH_...____________________ ||

    The  option can be  followed by  =sh to dump  in POSIX shell  format
    (default) or =cmd to dump in MS-Windows cmd.exe compatible format.

--help
    When  given as  the only  option, it summarises  the most  important
    options.  Also available as -h and -help.

--version
    When  given as the  only option, it  summarises the version and  the
    architecture identifier.  Also available as -v.


22..44..22 CCoommmmaanndd lliinnee ooppttiioonnss ffoorr rruunnnniinngg PPrroolloogg

--home=DIR
    Use DIR as home directory.  See section ???? for details.

--quiet
    Set  the Prolog  flag verbose to  silent, suppressing  informational
    and banner messages.  Also available as -q.

--nodebug
    Disable   debugging.        See   the   current_prolog_flag/2   flag
    generate_debug_info for details.

--nosignals
    Inhibit any signal  handling by Prolog, a property that is sometimes
    desirable  for embedded  applications.   This option  sets the  flag
    signals  to false.    See section  ???? for details.    Note that  the
    handler  to unblock system  calls is still installed.   This can  be
    prevented using --sigalert=0 additionally.  See --sigalert.

--pldoc _[_=_p_o_r_t_]
    Start  the PlDoc  documentation system  on a free  network port  and
    launch  the user's  browser on  http://localhost:_p_o_r_t.   If _p_o_r_t  is
    specified,  the server is started at the given port and  the browser
    is _n_o_t launched.

--sigalert=NUM
    Use  signal _N_U_M  (1...31) for  alerting a thread.    This is  needed
    to  make  thread_signal/2,  and derived  Prolog  signal handling  act
    immediately  when the target thread  is blocked on an  interruptable
    system  call  (e.g., sleep/1,  read/write  to most  devices).    The
    default is to use SIGUSR2.   If _N_U_M is 0 (zero), this handler is not
    installed.   See prolog_alert_signal/2to query or  modify this value
    at runtime.

-tty
    Unix  only.      Switches  controlling  the  terminal  for  allowing
    single-character  commands to the tracer and  get_single_char/1.   By
    default,  manipulating  the terminal  is enabled  unless the  system
    detects  it is not  connected to a  terminal or it  is running as  a
    GNU-Emacs inferior process.  See also tty_control.

--win_app
    This  option  is   available  only  in  swipl-win.exe  and  is  used
    for  the  start-menu  item.     If causes  plwin  to  start  in  the
    folder  ...\My Documents\Prolog  or  local equivalent  thereof  (see
    win_folder/2).   The Prolog subdirectory  is created if it does  not
    exist.

-O
    Optimised  compilation.  See current_prolog_flag/2flag  optimise for
    details.

-l _f_i_l_e
    Load  _f_i_l_e.    This  flag  provides  compatibility with  some  other
    Prolog  systems.    It is  used in  SWI-Prolog to  skip the  program
    initialization  specified using  initialization/2 directives.    See
    also section ????, and initialize/0.

-s _f_i_l_e
    Use  _f_i_l_e as a  script file.   The script file  is loaded after  the
    initialisation  file  specified with  the -f file  option.    Unlike
    -f file,  using -s does  not stop Prolog  from loading the  personal
    initialisation file.

-f _f_i_l_e
    Use  _f_i_l_e as  initialisation file  instead of  the default  .swiplrc
    (Unix)  or swipl.ini  (Windows).   `-f none'  stops SWI-Prolog  from
    searching  for  a startup  file.   This  option can  be  used as  an
    alternative  to -s file that stops Prolog from loading  the personal
    initialisation file.  See also section ????.

-F _s_c_r_i_p_t
    Select  a startup script  from the SWI-Prolog  home directory.   The
    script  file  is named  <_s_c_r_i_p_t>.rc.    The  default _s_c_r_i_p_t  name  is
    deduced  from  the  executable,  taking the  leading  alphanumerical
    characters  (letters, digits and underscore) from the  program name.
    -F none stops looking  for a script.  Intended for simple management
    of  slightly different  versions.   One  could,  for example,  write
    a  script  iso.rc  and  then select  ISO  compatibility  mode  using
    pl -F iso or make a link from iso-pl to pl.

-x _b_o_o_t_f_i_l_e
    Boot  from _b_o_o_t_f_i_l_e instead  of the system's default  boot file.   A
    boot  file is a file resulting  from a Prolog compilation using  the
    -b or -c option or a program saved using qsave_program/[1,2].

-p _a_l_i_a_s_=_p_a_t_h_1_[_:_p_a_t_h_2 _._._._]
    Define  a  path  alias  for file_search_path.    _a_l_i_a_s  is  the  name
    of  the  alias, and  argpath1 ...    is  a list  of  values for  the
    alias.    On Windows  the list  separator is ;.    On other  systems
    it  is :.   A  value is either  a term of  the form alias(value)  or
    pathname.    The  computed aliases  are added  to file_search_path/2
    using  asserta/1, so they precede  predefined values for the  alias.
    See  file_search_path/2 for  details  on  using this  file  location
    mechanism.

--traditional
    This  flag  disables the  most  important extensions  of  SWI-Prolog
    version  7 (see  section ????) that  introduce incompatibilities  with
    earlier  versions.   In  particular,  lists are  represented in  the
    traditional  way,  double  quoted  text  is represented  by  a  list
    of  character codes  and  the functional  notation on  dicts is  not
    supported.   Dicts  as a syntactic entity,  and the predicates  that
    act on them, are still supported if this flag is present.

--
    Stops  scanning for more  arguments, so you  can pass arguments  for
    your  application after this  one.   See current_prolog_flag/2 using
    the flag argv for obtaining the command line arguments.


22..44..33 CCoonnttrroolllliinngg tthhee ssttaacckk ssiizzeess

The default limit for the  Prolog stacks is 128 MB on 32-bit and  256 MB
on 64-bit hardware.   The 128 MB limit on 32-bit systems is  the highest
possible value  and the command  line options can thus  only be used  to
lower the  limit.   On  64-bit systems,  the limit can  both be  reduced
and enlarged.    See section  ????.   Below  are two  examples, the  first
reducing the local stack limit to catch unbounded  recursion quickly and
the second using a  big (32 GB) global limit, which is only  possible on
64-bit hardware.   Note  that setting the limit  using the command  line
only sets a _s_o_f_t  limit.  Stack parameters can be changed  (both reduced
and enlarged) at any time using the predicate set_prolog_stack/2.

________________________________________________________________________|                                                                        |
|$ swipl -L8m                                                            |

|$|swipl_-G32g__________________________________________________________ | |

-G_s_i_z_e_[_k_m_g_]
    Limit  for the  global stack  (sometimes also called  _t_e_r_m _s_t_a_c_k  or
    _h_e_a_p).  This is where compound terms and large numbers live.

-L_s_i_z_e_[_k_m_g_]
    Limit  for  the  local  stack  (sometimes  also  called  _e_n_v_i_r_o_n_m_e_n_t
    _s_t_a_c_k).  This is where environments and choice points live.

-T_s_i_z_e_[_k_m_g_]
    Limit  for  the  trail stack.    This  is  where  we keep  track  of
    assignments, so we can rollback on backtracking or exceptions.

-M_s_i_z_e_[_k_m_g_]
    Limit  for the _t_a_b_l_e  _s_p_a_c_e.  This  is where tries holding  memoized
    answers  for _t_a_b_l_i_n_g  are  stored.   The  default is  1Gb on  64-bit
    machines  and  512Mb  on 32-bit  machines.    See  the  Prolog  flag
    table_space


22..44..44 RRuunnnniinngg ggooaallss ffrroomm tthhee ccoommmmaanndd lliinnee

-g _g_o_a_l
    _G_o_a_l  is executed just before entering  the top level.  This  option
    may  appear multiple  times.   See section ????  for details.   If  no
    initialization  goal is present the system calls version/0  to print
    the  welcome message.   The welcome  message can be suppressed  with
    --quiet,  but also with -g true.   _g_o_a_l can be  a complex term.   In
    this  case  quotes are  normally  needed to  protect it  from  being
    expanded  by the shell.  A safe way to run a  goal non-interactively
    is below.   If go/0/succeeds -g halt causes the process to stop with
    exit  code 0.  If it fails,  the exit code is 1 and it it  raises an
    exception the exit code is 2.

    ____________________________________________________________________|                                                                    |
    ||%_swipl_<options>_-g_go_-g_halt___________________________________ ||

-t _g_o_a_l
    Use  _g_o_a_l  as interactive  top  level instead  of the  default  goal
    prolog/0.   The _g_o_a_l can be a  complex term.  If the  top-level goal
    succeeds  SWI-Prolog exits  with status  0.   If it  fails the  exit
    status is 1.   If the top level raises an exception, this is printed
    as  an uncaught error  and the top  level is _r_e_s_t_a_r_t_e_d.   This  flag
    also  determines the goal  started by break/0 and  abort/0.  If  you
    want  to prevent the user from entering interactive mode,  start the
    application with `-g goal -t halt'.


22..44..55 CCoommppiillaattiioonn ooppttiioonnss

-c _f_i_l_e _._._.
    Compile files into an `intermediate code file'.  See section ????.

-o _o_u_t_p_u_t
    Used  in combination  with -c  or -b  to determine  output file  for
    compilation.


22..44..66 MMaaiinntteennaannccee ooppttiioonnss

The following options  are for system maintenance.   They are given  for
reference only.

-b _i_n_i_t_f_i_l_e _._._.-c _f_i_l_e _._._.
    Boot  compilation.   _i_n_i_t_f_i_l_e  _._._.   are compiled  by the  C-written
    bootstrap  compiler,  _f_i_l_e  _._._.    by  the normal  Prolog  compiler.
    System maintenance only.

-d _t_o_k_e_n_1_,_t_o_k_e_n_2_,_._._.
    Print  debug messages for  DEBUG statements tagged  with one of  the
    indicated  tokens.  Only has  effect if the system is compiled  with
    the -DO_DEBUG flag.  System maintenance only.


22..55 GGNNUU EEmmaaccss IInntteerrffaaccee

Unfortunately the  default Prolog mode  of GNU Emacs  is not very  good.
There are several alternatives though:

  o https://bruda.ca/emacs/prolog_mode_for_emacs
    Prolog mode for Emacs and XEmacs maintained by Stefan Bruda.

  o https://www.metalevel.at/pceprolog/
    Recommended  configuration  options  for editing  Prolog  code  with
    Emacs.

  o https://www.metalevel.at/ediprolog/
    Interact with SWI-Prolog directly in Emacs buffers.

  o https://www.metalevel.at/etrace/
    Trace Prolog code with Emacs.


22..66 OOnnlliinnee HHeellpp

SWI-Prolog  provides an  online  help system  that covers  this  manual.
If  the  XPCE  graphics  system  is  available,   online  help  opens  a
graphical  window.     Otherwise  the  documentation  is  shown  in  the
Prolog  console.    The help  system  is  controlled by  the  predicates
below.   Note  that this  help system  only covers  the core  SWI-Prolog
manual.  The website provides an integrated manual  that covers the core
system as  well as  all standard  extension packages.    It is  possible
to  install  the  SWI-Prolog website  locally  by  cloning  the  website
repository git://www.swi-prolog.org/home/pl/git/plweb.git and  following
the instructions in the README file.


hheellpp
    Equivalent to help(help/1).


hheellpp((_+_W_h_a_t))
    Show specified part of the manual.  _W_h_a_t is one of:

          <_N_a_m_e>/<_A_r_i_t_y> Give help on specified predicate
          <_N_a_m_e>         Give  help on  named  predicate with  any
                         arity or  C interface function  with that
                         name
          <_S_e_c_t_i_o_n>      Display  specified  section.      Section
                         numbers are dash-separated  numbers:  2-3
                         refers  to  section 2.3  of  the  manual.

                         Section   numbers  are   obtained   using
                         apropos/1.

    Examples:

       ?- help(assert).     Give help on predicate assert
       ?- help(3-4).        Display section 3.4 of the manual
       ?- help('PL_retry'). Give    help   on    interface   function
                            PL_retry()

    See   also  apropos/1  and  the   SWI-Prolog  home  page  at   http:
    //www.swi-prolog.org,  which  provides a  FAQ,  an HTML  version  of
    the  manual  for online  browsing,  and HTML  and PDF  versions  for
    downloading.


aapprrooppooss((_+_P_a_t_t_e_r_n))
    Display all predicates,  functions and sections that have _P_a_t_t_e_r_n in
    their  name or summary  description.   Lowercase letters in  _P_a_t_t_e_r_n
    also match a corresponding uppercase letter.  Example:

            ?- apropos(file).  Display   predicates,   functions
                               and  sections  that  have  `file'
                               (or  `File',  etc.)     in  their
                               summary description.


eexxppllaaiinn((_+_T_o_E_x_p_l_a_i_n))
    Give an explanation on  the given `object'.  The argument may be any
    Prolog  data object.   If  the argument is  an atom,  a term of  the
    form  _N_a_m_e_/_A_r_i_t_y or a term of the form  _M_o_d_u_l_e_:_N_a_m_e_/_A_r_i_t_y, explain/1
    describes  the predicate as well as possible references to it.   See
    also gxref/0.


eexxppllaaiinn((_+_T_o_E_x_p_l_a_i_n_, _-_E_x_p_l_a_n_a_t_i_o_n))
    Unify  _E_x_p_l_a_n_a_t_i_o_n with an explanation for _T_o_E_x_p_l_a_i_n.   Backtracking
    yields further explanations.


22..77 CCoommmmaanndd lliinnee hhiissttoorryy

SWI-Prolog  offers a  query substitution  mechanism similar  to what  is
seen in Unix shells.  The availability of this  feature is controlled by
set_prolog_flag/2,  using the history Prolog  flag.  By default,  history
is available  if no interactive  command line editor is  available.   To
enable history,  remembering  the last  50 commands,  put the  following
into your startup file (see section ????):

________________________________________________________________________|                                                                        |
|:-|set_prolog_flag(history,_50)._______________________________________ |  |

The history  system allows the  user to compose  new queries from  those
typed  before and  remembered by  the  system.   The  available  history
commands are shown in table ????.  History expansion is  not done if these
sequences appear in quoted atoms or strings.
             ______________________________________________
             | !!.   |Repeat last query                     |
             | !nr.  |Repeat query numbered <_n_r>            |

             | !str. |Repeat last query starting with <_s_t_r> |
             | h.    |Show history of commands              |
             |_!h.___|Show_this_list_______________________ |

                      Table 2.1:  History commands


22..88 RReeuussee ooff ttoopp--lleevveell bbiinnddiinnggss

Bindings resulting  from the  successful execution of  a top-level  goal
are asserted in a database _i_f _t_h_e_y _a_r_e _n_o_t _t_o_o _l_a_r_g_e.   These values may
be reused in  further top-level queries as $Var.   If the same  variable
name is used  in a subsequent query  the system associates the  variable
with the latest binding.  Example:
________________________________________________________________________|                                                                        |
|1 ?- maplist(plus(1), "hello", X).                                      |
|X = [105,102,109,109,112].                                              |
|                                                                        |

|2 ?- format('~s~n', [$X]).                                              |
|ifmmp                                                                   |
|true.                                                                   |
|                                                                        |
|3|?-___________________________________________________________________ | |

                Figure 2.1:  Reusing top-level bindings

Note that variables may be set by executing =/2:

________________________________________________________________________|                                                                        |
|6 ?- X = statistics.                                                    |

|X = statistics.                                                         |
|                                                                        |
|7 ?- $X.                                                                |
|28.00 seconds cpu time for 183,128 inferences                           |
|4,016 atoms, 1,904 functors, 2,042 predicates, 52 modules               |
|55,915 byte codes; 11,239 external references                           |
|                                                                        |
|                      Limit    Allocated       In use                   |

|Heap         :                                624,820 Bytes             |
|Local  stack :    2,048,000        8,192          404 Bytes             |
|Global stack :    4,096,000       16,384          968 Bytes             |
|Trail  stack :    4,096,000        8,192          432 Bytes             |
|true.|_________________________________________________________________ |     |


22..99 OOvveerrvviieeww ooff tthhee DDeebbuuggggeerr

SWI-Prolog has  a 6-port  tracer, extending the  standard 4-port  tracer
[??,  ??] with  two additional  ports.   The  optional  _u_n_i_f_y port  allows
the user  to inspect  the result  after unification of  the head.    The
_e_x_c_e_p_t_i_o_n  port  shows  exceptions raised  by  throw/1  or  one  of  the
built-in predicates.  See section ????.

The standard  ports are called call,  exit, redo, fail  and unify.   The
tracer is started  by the trace/0 command,  when a spy point is  reached
and the system is in debugging mode (see spy/1 and  debug/0), or when an
exception is raised that is not caught.

The interactive top-level  goal trace/0 means ``trace the next  query''.
The tracer shows the  port, displaying the port name, the  current depth
of the  recursion and the goal.   The goal  is printed using the  Prolog
predicate  write_term/2.     The style  is  defined  by the  Prolog  flag
debugger_write_options and can be modified using this flag or  using the
w, p and d commands of the tracer.
________________________________________________________________________|                                                                        |
|min_numlist([H|T], Min) :-                                              |
|        min_numlist(T, H, Min).                                         |
|                                                                        |

|min_numlist([], Min, Min).                                              |
|min_numlist([H|T], Min0, Min) :-                                        |
|        Min1 is min(H, Min0),                                           |
||_______min_numlist(T,_Min1,_Min)._____________________________________ ||

________________________________________________________________________|                                                                        |

|1 ?- visible(+all), leash(-exit).                                       |
|true.                                                                   |
|                                                                        |
|2 ?- trace, min_numlist([3, 2], X).                                     |
|   Call: (7) min_numlist([3, 2], _G0) ? creep                           |

|   Unify: (7) min_numlist([3, 2], _G0)                                  |
|   Call: (8) min_numlist([2], 3, _G0) ? creep                           |
|   Unify: (8) min_numlist([2], 3, _G0)                                  |
|^  Call: (9) _G54 is min(2, 3) ? creep                                  |
|^  Exit: (9) 2 is min(2, 3)                                             |
|   Call: (9) min_numlist([], 2, _G0) ? creep                            |
|   Unify: (9) min_numlist([], 2, 2)                                     |
|   Exit: (9) min_numlist([], 2, 2)                                      |

|   Exit: (8) min_numlist([2], 3, 2)                                     |
|   Exit: (7) min_numlist([3, 2], 2)                                     |
|X|=_2._________________________________________________________________ | |

Figure  2.2:   Example trace  of the  program above  showing all  ports.
The  lines marked  ^ indicate  calls  to _t_r_a_n_s_p_a_r_e_n_t  predicates.    See
section ????.

On _l_e_a_s_h_e_d  _p_o_r_t_s (set  with the  predicate leash/1,  default are  call,
exit, redo and  fail) the user is prompted  for an action.  All  actions
are single-character commands  which are executed wwiitthhoouutt waiting for  a
return, unless the command line option -tty is active.  Tracer options:

+ ((SSppyy))
    Set a spy point (see spy/1) on the current predicate.

- ((NNoo ssppyy))
    Remove the spy point (see nospy/1) from the current predicate.

/ ((FFiinndd))
    Search  for a port.   After the  `/', the user  can enter a line  to
    specify  the port to  search for.   This line consists  of a set  of
    letters  indicating the  port type,  followed by  an optional  term,
    that  should unify with  the goal run by  the port.   If no term  is
    specified  it is taken as a variable, searching for any port  of the
    specified  type.  If an atom is given, any goal whose  functor has a
    name equal to that atom matches.  Examples:

            /f               Search for any fail port

            /fe solve        Search for a  fail or exit  port of
                             any goal with name solve
            /c solve(a, _)   Search for a call to  solve/2 whose
                             first argument is a variable or the
                             atom a
            /a member(_, _)  Search for  any  port on  member/2.
                             This is equivalent to setting a spy

                             point on member/2.

. ((RReeppeeaatt ffiinndd))
    Repeat the last find command (see `/').

A ((AAlltteerrnnaattiivveess))
    Show all goals that have alternatives.

C ((CCoonntteexxtt))
    Toggle  `Show Context'.   If on, the context  module of the goal  is
    displayed  between square  brackets (see  section ????).   Default  is
    off.

L ((LLiissttiinngg))
    List the current predicate with listing/1.

a ((AAbboorrtt))
    Abort Prolog execution (see abort/0).

b ((BBrreeaakk))
    Enter a Prolog break environment (see break/0).

c ((CCrreeeepp))
    Continue execution, stop at next port.  (Also return, space).

d ((DDiissppllaayy))
    Set  the max_depth(_D_e_p_t_h) option of debugger_write_options,  limiting
    the  depth  to which  terms are  printed.    See also  the  w and  p
    options.

e ((EExxiitt))
    Terminate Prolog (see halt/0).

f ((FFaaiill))
    Force failure of the current goal.

g ((GGooaallss))
    Show the list of  parent goals (the execution stack).  Note that due
    to  tail recursion optimization a  number of parent goals might  not
    exist any more.

h ((HHeellpp))
    Show available options (also `?').

i ((IIggnnoorree))
    Ignore the current goal, pretending it succeeded.

l ((LLeeaapp))
    Continue execution, stop at next spy point.

n ((NNoo ddeebbuugg))
    Continue execution in `no debug' mode.

p ((PPrriinntt))
    Set  the Prolog  flag debugger_write_options to  [quoted(true), por-
    tray(true), max_depth(10), priority(699)].  This is the default.

r ((RReettrryy))
    Undo  all actions (except for database and I/O actions) back  to the
    call  port of  the current  goal and  resume execution  at the  call
    port.

s ((SSkkiipp))
    Continue  execution,  stop  at the  next  port  of tthhiiss  goal  (thus
    skipping all calls to children of this goal).

u ((UUpp))
    Continue  execution, stop at the next port of tthhee ppaarreenntt  goal (thus
    skipping  this goal and all calls to  children of this goal).   This
    option is useful to stop tracing a failure driven loop.

w ((WWrriittee))
    Set  the  Prolog flag  debugger_write_options to  [quoted(true), at-
    tributes(write), priority(699)], bypassing portray/1, etc.

The ideal  4-port model  [??] as described  in many  Prolog books [??]  is
not visible  in many  Prolog implementations  because code  optimisation
removes  part  of  the  choice  and  exit  points.     Backtrack  points
are not  shown if  either the  goal succeeded  deterministically or  its
alternatives were  removed using the  cut.  When  running in debug  mode
(debug/0) choice points are only destroyed when removed by the  cut.  In
debug mode, last call optimisation is switched off.

Reference information to  all predicates available for manipulating  the
debugger is in section ????.


22..1100 CCoommppiillaattiioonn


22..1100..11 DDuurriinngg pprrooggrraamm ddeevveellooppmmeenntt

During  program development,  programs  are  normally loaded  using  the
list abbreviation  (?- [load].).   It is common  practice to organise  a
project as a collection  of source files and a _l_o_a_d _f_i_l_e, a  Prolog file
containing only use_module/[1,2] or ensure_loaded/1 directives, possibly
with a definition of the _e_n_t_r_y _p_o_i_n_t of the  program, the predicate that
is  normally used  to start  the program.    This file  is often  called
load.pl.  If the entry point is called _g_o, a typical session starts as:

________________________________________________________________________|                                                                        |
|% swipl                                                                 |

|<banner>                                                                |
|                                                                        |
|1 ?- [load].                                                            |
|<compilation messages>                                                  |
|true.                                                                   |
|                                                                        |
|2 ?- go.                                                                |
|<program|interaction>__________________________________________________ |        |

When  using  Windows,  the  user  may  open  load.pl  from  the  Windows
explorer, which will cause swipl-win.exe to be started  in the directory
holding load.pl.   Prolog loads load.pl  before entering the top  level.
If Prolog is started from an interactive shell, one  may choose the type
swipl -s load.pl.


22..1100..22 FFoorr rruunnnniinngg tthhee rreessuulltt

There are  various options if  you want to make  your program ready  for
real usage.   The best  choice depends on whether  the program is to  be
used only  on machines  holding the SWI-Prolog  development system,  the
size of the program, and the operating system (Unix vs. Windows).


22..1100..22..11 UUssiinngg PPrroollooggSSccrriipptt

A Prolog source  file can be used directly  as a Unix program using  the
Unix #! magic start.  The Unix #! magic is  allowed because if the first
letter of a  Prolog file is #, the  first line is treated as a  comment.
To create  a Prolog  script, use one  of the  two alternatives below  as
first line.    The first  can be  used to bind  a script  to a  specific
Prolog installation, while the latter uses the  default prolog installed
in $PATH.

________________________________________________________________________|                                                                        |
|#!/path/to/swipl                                                        |
|#!/usr/bin/env|swipl___________________________________________________ |              |

The interpretation of  arguments to the executable in the  _H_a_s_h_B_a_n_g line
differs between  Unix-derived systems.    For portability,  the #!  must
be followed  immediately with  an absolute  path to  the executable  and
should have none or one argument.  Neither the  executable path, nor the
argument shall use quotes or spaces.  When started  this way, the Prolog
flag argv  contains the command  line arguments  that follow the  script
invocation.

Starting with version  7.5.8, initialization/2 support the _W_h_e_n  options
program and  main, allowing  for the  following definition  of a  Prolog
script  that evaluates  an arithmetic  expression on  the command  line.
Note that main/0 is defined lib the library main.   It calls main/1 with
the command line arguments after disabling signal handling.

________________________________________________________________________|                                                                        |

|#!/usr/bin/env swipl                                                    |
|                                                                        |
|:- initialization(main, main).                                          |
|                                                                        |
|main(Argv) :-                                                           |
|        concat_atom(Argv, ' ', SingleArg),                              |

|        term_to_atom(Term, SingleArg),                                  |
|        Val is Term,                                                    |
||_______format('~w~n',_[Val])._________________________________________ ||

And here are two example runs:

________________________________________________________________________|                                                                        |
|% ./eval 1+2                                                            |
|3                                                                       |
|% ./eval foo                                                            |

|ERROR:|is/2:_Arithmetic:_`foo/0'_is_not_a_function_____________________ |      |

Prolog script may be lauched for debugging or  inspection purposes using
the -l or  -t.  For example,  -l merely loads the script, ignoring  main
and program initialization.

________________________________________________________________________|                                                                        |
|swipl -l eval 1+1                                                       |
|<banner>                                                                |
|                                                                        |
|?- main.                                                                |

|2                                                                       |
|true.                                                                   |
|                                                                        |
|?-|____________________________________________________________________ |  |

We can also  force the program to  enter the interactive toplevel  after
the application is completed using -t prolog:

________________________________________________________________________|                                                                        |
|swipl -t prolog eval 1+1                                                |
|2                                                                       |

|?-|____________________________________________________________________ |  |

The Windows version simply ignores the #! line.


22..1100..22..22 CCrreeaattiinngg aa sshheellll ssccrriipptt

With  the introduction  of _P_r_o_l_o_g_S_c_r_i_p_t  (see section  ????), using  shell
scripts  as explained  in this  section has  become  redundant for  most
applications.

Especially on  Unix systems  and not-too-large  applications, writing  a
shell script  that simply  loads your  application and  calls the  entry
point is  often a  good choice.    A skeleton  for the  script is  given
below, followed by the Prolog code to obtain the program arguments.

________________________________________________________________________|                                                                        |
|#!/bin/sh                                                               |

|                                                                        |
|base=<absolute-path-to-source>                                          |
|PL=swipl                                                                |
|                                                                        |
|exec|$PL_-q_-f_"$base/load"_--_________________________________________ |    |

________________________________________________________________________|                                                                        |
|:- initialization go.                                                   |
|                                                                        |
|go :-                                                                   |
|        current_prolog_flag(argv, Arguments),                           |
|        go(Arguments).                                                  |

|                                                                        |
|go(Args) :-                                                             |
||_______...____________________________________________________________ ||

On Windows  systems, similar  behaviour can  be achieved  by creating  a
shortcut to Prolog, passing the proper options or writing a .bat file.


22..1100..22..33 CCrreeaattiinngg aa ssaavveedd ssttaattee

For  larger programs,  as  well as  for programs  that are  required  to
run  on systems  that  do not  have  the SWI-Prolog  development  system
installed,  creating a  saved  state is  the  best solution.    A  saved
state  is  created using  qsave_program/[1,2]  or the  -c  command  line
option.     A saved  state  is  a  file  containing  machine-independent
intermediate code in a  format dedicated for fast loading.   Optionally,
the emulator  may be integrated  in the saved  state, creating a  single
file, but machine-dependent,  executable.  This process is  described in
chapter ????.


22..1100..22..44 CCoommppiillaattiioonn uussiinngg tthhee --cc ccoommmmaanndd lliinnee ooppttiioonn

This mechanism loads a series of Prolog source files  and then creates a
saved state as qsave_program/2 does.  The command syntax is:

________________________________________________________________________|                                                                        |
|%|swipl_[option_...]_[-o_output]_-c_file.pl_...________________________ | |

The  _o_p_t_i_o_n_s argument  are  options to  qsave_program/2 written  in  the
format below.    The option names  and their  values are described  with
qsave_program/2.

    --_o_p_t_i_o_n_-_n_a_m_e=_o_p_t_i_o_n_-_v_a_l_u_e

For  example,  to  create  a  stand-alone   executable  that  starts  by
executing main/0  and for which  the source  is loaded through  load.pl,
use the command

________________________________________________________________________|                                                                        |
|%|swipl_--goal=main_--stand_alone=true_-o_myprog_-c_load.pl____________ | |

This performs exactly the same as executing

________________________________________________________________________|                                                                        |
|% swipl                                                                 |

|<banner>                                                                |
|                                                                        |
|?- [load].                                                              |
|?- qsave_program(myprog,                                                |
|                 [ goal(main),                                          |
|                   stand_alone(true)                                    |
|                 ]).                                                    |
|?-|halt._______________________________________________________________ |  |


22..1111 EEnnvviirroonnmmeenntt CCoonnttrrooll ((PPrroolloogg ffllaaggss))

The  predicates  current_prolog_flag/2 and  set_prolog_flag/2 allow  the
user  to examine  and modify  the execution  environment.   It  provides
access  to whether  optional  features are  available on  this  version,
operating  system, foreign  code  environment, command  line  arguments,
version,  as well  as runtime  flags to  control  the runtime  behaviour
of  certain  predicates  to  achieve  compatibility  with  other  Prolog
environments.


ccuurrrreenntt__pprroolloogg__ffllaagg((_?_K_e_y_, _-_V_a_l_u_e))                                  _[_I_S_O_]
    The  predicate current_prolog_flag/2defines an interface  to instal-
    lation  features:  options  compiled in, version,  home, etc.   With
    both  arguments unbound, it will generate all defined  Prolog flags.
    With  _K_e_y  instantiated, it  unifies  _V_a_l_u_e with  the value  of  the
    Prolog flag or fails if the _K_e_y is not a Prolog flag.

    Flags   marked   rrww    can   be   modified   by   the   user   using
    set_prolog_flag/2.     Flag   values  are  typed.      Flags  marked
    as  bool  can  have  the  values  true or  false.     The  predicate
    create_prolog_flag/3 may be  used to create  flags that describe  or
    control  behaviour  of  libraries and  applications.    The  library
    settings  provides  an alternative  interface for  managing  notably
    application parameters.

    Some  Prolog  flags  are  not defined  in  all  versions,  which  is
    normally  indicated in the documentation  below as _`_`_i_f _p_r_e_s_e_n_t  _a_n_d
    _t_r_u_e_'_'.    A boolean  Prolog flag  is true  iff the  Prolog flag  is
    present  aanndd the  _V_a_l_u_e is  the atom  true.   Tests  for such  flags
    should be written as below:

    ____________________________________________________________________|                                                                    |
    |         (   current_prolog_flag(windows, true)                     |
    |         ->  <Do MS-Windows things>                                 |
    |         ;   <Do normal things>                                     |

    ||________)_________________________________________________________ ||

    Some  Prolog  flags are  scoped to  a  source file.    This  implies
    that  if they  are set  using a directive  inside a  file, the  flag
    value encountered when  loading of the file started is restored when
    loading  of the file is completed.   Currently, the following  flags
    are scoped to the source file:  generate_debug_info and optimise.

    A new thread (see  section ????) _c_o_p_i_e_s all flags from the thread that
    created the new thread  (its _p_a_r_e_n_t).  As a consequence, modifying a
    flag inside a thread does not affect other threads.

    aacccceessss__lleevveell _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This flag  defines  a normal  `user'  view (user,  default)  or
         a `system'  view.   In  system view  all system  code is  fully
         accessible as  if  it was  normal user  code.    In user  view,
         certain operations are not permitted and some  details are kept
         invisible.   We  leave the exact  consequences undefined,  but,
         for example, system code can be traced using  system access and
         system predicates can be redefined.

    aaddddrreessss__bbiittss _(_i_n_t_e_g_e_r_)
         Address size  of the  hosting  machine.   Typically  32 or  64.
         Except for the maximum  stack limit, this has few  implications
         to the user.  See also the Prolog flag arch.

    aaggcc__mmaarrggiinn _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         If this amount  of atoms possible  garbage atoms exist  perform
         atom garbage  collection at  the  first opportunity.    Initial
         value is  10,000.    May  be changed.    A  value of  0  (zero)
         disables atom garbage collection.  See also PL_register_atom().

    aappppllee _(_b_o_o_l_)
         If present and  true, the operating  system is MacOSX.  Defined
         if the C  compiler used to  compile this version of  SWI-Prolog
         defines __APPLE__.    Note that the  unix is  also defined  for
         MacOSX.

    aallllooww__ddoott__iinn__aattoomm _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true (default  false),  dots  may be  embedded  into  atoms
         that are  not quoted and  start with  a letter.   The  embedded
         dot _m_u_s_t  be followed by  an identifier continuation  character
         (i.e.,  letter, digit  or  underscore).    The dot  is  allowed
         in  identifiers  in many  languages,  which  can  make  this  a
         useful flag for defining  DSLs.  Note that this  conflicts with
         cascading functional notation.   For example,  Post.meta.author
         is read as .(Post, 'meta.author' if this flag is set to true.

    aallllooww__vvaarriiaabbllee__nnaammee__aass__ffuunnccttoorr _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default  is false),  Functor(arg) is  read  as if  it
         were written 'Functor'(arg).  Some applications  use the Prolog
         read/1  predicate for  reading  an  application-defined  script
         language.   In these  cases, it is  often difficult to  explain
         to  non-Prolog users  of  the  application that  constants  and
         functions can only  start with a  lowercase letter.   Variables
         can be  turned into atoms  starting with  an uppercase atom  by
         calling read_term/2 using the option variable_names and binding
         the variables to their name.   Using this feature, F(x)  can be
         turned into valid syntax for such script languages.   Suggested
         by Robert van Engelen.  SWI-Prolog specific.

    aarrggvv _(_l_i_s_t_, _c_h_a_n_g_e_a_b_l_e_)
         List is a  list of atoms  representing the application  command
         line  arguments.     Application  command  line  arguments  are
         those  that  have _n_o_t  been  processed  by  Prolog  during  its
         initialization.   Note that Prolog's argument processing  stops
         at -- or the first non-option argument.  See also os_argv.

    aarrcchh _(_a_t_o_m_)
         Identifier for  the  hardware and  operating system  SWI-Prolog
         is running  on.   Used to  select foreign files  for the  right
         architecture.  See also section ???? and file_search_path/2.

    aassssoocciiaatteedd__ffiillee _(_a_t_o_m_)
         Set if  Prolog  was started  with a  prolog  file as  argument.
         Used by e.g., edit/0 to edit the initial file.

    aauuttoollooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default) autoloading of library functions is enabled.

    bbaacckk__qquuootteess _(_c_o_d_e_s_,_c_h_a_r_s_,_s_t_r_i_n_g_,_s_y_m_b_o_l___c_h_a_r_, _c_h_a_n_g_e_a_b_l_e_)
         Defines the term-representation for back-quoted material.   The
         default is  codes.    If --traditional  is given,  the  default
         is symbol_char, which allows  using ` in operators composed  of
         symbols..  See also section ????.

    bbaacckkttrraaccee _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default), print a backtrace on an uncaught exception.

    bbaacckkttrraaccee__ddeepptthh _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         If backtraces  on errors  are enabled,  this  flag defines  the
         maximum number of frames that is printed (default 20).

    bbaacckkttrraaccee__ggooaall__ddeepptthh _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         The frame  of a  backtrace is  printed after  making a  shallow
         copy of the goal.  This flag determines the depth  to which the
         goal term is copied.  Default is `3'.

    bbaacckkttrraaccee__sshhooww__lliinneess _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default), try to reconstruct the line  number at which
         the exception happened.

    bboouunnddeedd _(_b_o_o_l_)
         ISO Prolog  flag.   If  true, integer  representation is  bound
         by  min_integer and max_integer.    If  false integers  can  be
         arbitrarily large and  the min_integer and max_integer are  not
         present.  See section ????.

    bbrreeaakk__lleevveell _(_i_n_t_e_g_e_r_)
         Current break-level.   The initial top level (started  with -t)
         has value 0.   See break/0.   This flag is absent from  threads
         that are not running a top-level loop.

    cc__cccc _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Name of the  C compiler used to  compile SWI-Prolog.   Normally
         either gcc or cc.  See section ????.

    cc__ccffllaaggss _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         CFLAGS used to compile SWI-Prolog.  See section ????.

    cc__llddffllaaggss _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         LDFLAGS used to link SWI-Prolog.  See section ????.

    cc__lliibbss _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Libraries needed  to  link executables  that embed  SWI-Prolog.
         Typically -lswipl if the  SWI-Prolog kernel is a shared  (DLL).
         If the  SWI-Prolog kernel  is in  a static  library, this  flag
         also contains the dependencies.

    cc__lliibbppllssoo _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Libraries needed  to link  extensions (shared  object, DLL)  to
         SWI-Prolog.   Typically  empty on  ELF systems  and -lswipl  on
         COFF-based systems.  See section ????.

    cchhaarr__ccoonnvveerrssiioonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines  whether  character  conversion  takes  place  while
         reading terms.  See also char_conversion/2.

    cchhaarraacctteerr__eessccaappeess _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default),  read/1 interprets  \  escape sequences  in
         quoted atoms and strings.  May be changed.   This flag is local
         to the module in which it is changed.  See section ????.

    ccoolloonn__sseettss__ccaalllliinngg__ccoonntteexxtt _(_b_o_o_l_)
         Using the construct <_m_o_d_u_l_e>:<_g_o_a_l> sets the _c_a_l_l_i_n_g _c_o_n_t_e_x_t for
         executing <_g_o_a_l>.    This  flag is  defined by  ISO/IEC 13211-2
         (Prolog modules standard).  See section ????.

    ccoolloorr__tteerrmm _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         This flag is managed  by library ansi_term, which is loaded  at
         startup if the two conditions  below are both true.   Note that
         this implies that  setting this flag  to false from the  system
         or  personal  initialization  file  (see  section  ????  disables
         colored output.   The predicate message_property/2 can be  used
         to control  the actual  color scheme depending  in the  message
         type passed to print_message/2.

           o stream_property(current_output, tty(true))

           o \+ current_prolog_flag(color_term, false)

    ccoommppiillee__mmeettaa__aarrgguummeennttss _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Experimental  flag  that  controls  compilation   of  arguments
         passed to meta-calls marked `0'  or `^' (see meta_predicate/1).
         Supported values are:

         ffaallssee
             (default).  Meta-arguments are passed verbatim.

         ccoonnttrrooll
             Compile  meta-arguments  that  contain  control  structures
             ((A,B),  (A;B),  (A->B;C),  etc.).    If  not  compiled  at
             compile  time, such arguments  are compiled to a  temporary
             clause  before  execution.    Using  this  option  enhances
             performance  of  processing  complex  meta-goals  that  are
             known at compile time.

         ttrruuee
             Also  compile references to normal  user predicates.   This
             harms  performance (a  little), but enhances  the power  of
             poor-mens consistency check used  by make/0 and implemented
             by list_undefined/0.

         aallwwaayyss
             Always  create  an  intermediate clause,  even  for  system
             predicates.     This  prepares  for  replacing  the  normal
             head  of the generated predicate  with a special  reference
             (similar   to  database  references  as   used  by,   e.g.,
             assert/2)  that provides  direct access  to the  executable
             code,  thus  avoiding  runtime  lookup  of  predicates  for
             meta-calling.

    ccoommppiilleedd__aatt _(_a_t_o_m_)
         Describes when the  system has been  compiled.  Only  available
         if  the C  compiler used  to  compile SWI-Prolog  provides  the
         __DATE__and __TIME__macros.

    ccoonnssoollee__mmeennuu _(_b_o_o_l_)
         Set  to true  in swipl-win.exe  to  indicate that  the  console
         supports menus.  See also section ????.

    ccppuu__ccoouunntt _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         Number of physical  CPUs or cores in the  system.  The flag  is
         marked read-write both to allow pretending the  system has more
         or less processors.   See also thread_setconcurrency/2 and  the
         library thread.   This flag is  not available on systems  where
         we do not  know how to get  the number of CPUs.   This flag  is
         not included in a saved state (see qsave_program/1).

    ddddee _(_b_o_o_l_)
         Set  to  true  if this  instance  of  Prolog  supports  DDE  as
         described in section ????.

    ddeebbuugg _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Switch debugging  mode  on/off.   If  debug  mode is  activated
         the system traps encountered  spy points (see spy/1) and  trace
         points (see  trace/1).    In addition,  last-call  optimisation
         is disabled and the  system is more conservative in  destroying
         choice points to simplify debugging.

         Disabling these optimisations can  cause the system to run  out
         of memory on  programs that behave  correctly if debug mode  is
         off.

    ddeebbuugg__oonn__eerrrroorr _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true,  start  the  tracer  after   an  error  is  detected.
         Otherwise  just continue  execution.    The  goal  that  raised
         the  error will  normally  fail.    See  also the  Prolog  flag
         report_error.  Default is true.

    ddeebbuuggggeerr__wwrriittee__ooppttiioonnss _(_t_e_r_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  argument is  given  as  option-list to  write_term/2  for
         printing goals by the debugger.   Modified by the `w',  `p' and
         `<N> d' commands  of the debugger.   Default is  [quoted(true),
         portray(true), max_depth(10), attributes(portray)].

    ddeebbuuggggeerr__sshhooww__ccoonntteexxtt _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, show  the context module while printing a  stack-frame
         in the  tracer.   Normally controlled using  the `C' option  of
         the tracer.

    ddiiaalleecctt _(_a_t_o_m_)
         Fixed to swi.   The code below  is a reliable and portable  way
         to detect SWI-Prolog.

         _______________________________________________________________|                                                               |
         |is_dialect(swi) :-                                             |
         ||_______catch(current_prolog_flag(dialect,_swi),__,_fail).____ ||

    ddoouubbllee__qquuootteess _(_c_o_d_e_s_,_c_h_a_r_s_,_a_t_o_m_,_s_t_r_i_n_g_, _c_h_a_n_g_e_a_b_l_e_)
         This flag  determines how  double  quoted strings  are read  by
         Prolog  and  is  ---like character_escapes  and  back_quotes---
         maintained  for  each   module.      The  default  is   string,
         which  produces a  string  as described  in  section  ????.    If
         --traditional is  given, the default  is codes, which  produces
         a list of  character codes, integers  that represent a  Unicode
         code-point.  The  value chars produces a list  of one-character
         atoms  and the  value  atom makes  double  quotes the  same  as
         single quotes, creating a atom.  See also section ????.

    eeddiittoorr _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Determines the  editor used  by  edit/1.   See  section ????  for
         details on selecting the editor used.

    eemmaaccss__iinnffeerriioorr__pprroocceessss _(_b_o_o_l_)
         If  true,  SWI-Prolog is  running  as an  _i_n_f_e_r_i_o_r  _p_r_o_c_e_s_s  of
         (GNU/X-)Emacs.   SWI-Prolog  assumes this  is the  case if  the
         environment variable EMACS is t and INFERIOR is yes.

    eennccooddiinngg _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Default encoding  used for  opening files in  text mode.    The
         initial value is deduced from the environment.   See section ????
         for details.

    eexxeeccuuttaabbllee _(_a_t_o_m_)
         Pathname of the running executable.  Used by qsave_program/2 as
         default emulator.

    eexxiitt__ssttaattuuss _(_i_n_t_e_g_e_r_)
         Set  by  halt/1  to  its  argument,   making  the  exit  status
         available to hooks registered with at_halt/1.

    ffiillee__nnaammee__ccaassee__hhaannddlliinngg _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This flag defines  how Prolog handles  the case of file  names.
         The  flag is  used  for  case normalization  and  to  determine
         whether two names refer  to the same file.   It has one of  the
         following values:

         ccaassee__sseennssiittiivvee
             The  filesystem  is fully  case  sensitive.    Prolog  does
             not  perform  any  case modification  or  case  insensitive
             matching.  This is the default on Unix systems.

         ccaassee__pprreesseerrvviinngg
             The  filesystem is case insensitive,  but it preserves  the
             case with  which the user jas created a file.  This  is the
             default on Windows systems.

         ccaassee__iinnsseennssiittiivvee
             The  filesystem  doesn't store  or match  case.    In  this
             scenario Prolog maps all file names to lower case.

    ffiillee__nnaammee__vvaarriiaabblleess _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true  (default  false),  expand  $_v_a_r_n_a_m_e   and  ~  in  ar-
         guments  of  built-in  predicates  that  accept  a   file  name
         (open/3, exists_file/1,  access_file/2,  etc.).   The  predicate
         expand_file_name/2 can be used to expand environment  variables
         and  wildcard patterns.    This  Prolog  flag is  intended  for
         backward compatibility with older versions of SWI-Prolog.

    ffiillee__sseeaarrcchh__ccaacchhee__ttiimmee _(_n_u_m_b_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         Time   in    seconds    for   which    search   results    from
         absolute_file_name/3  are   cached.        Within   this   time
         limit, the system will  first check that the old  search result
         satisfies  the  conditions.    Default  is  10  seconds,  which
         typically avoids most  repetitive searches for (library)  files
         during compilation.   Setting this  value to 0 (zero)  disables
         the cache.

    ggcc _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default), the garbage collector is active.   If false,
         neither garbage collection,  nor stack shifts will take  place,
         even not on explicit request.  May be changed.

    ggcc__tthhrreeaadd _(_b_o_o_l_)
         If true  (default if  threading is  enabled),  atom and  clause
         garbage  collection are  executed  in  a seperate  thread  with
         the _a_l_i_a_s  gc.    Otherwise the  thread  the detect  sufficient
         garbage  executes the  garbage collector.    As  running  these
         global collectors may  take relatively using a seperate  thread
         improves real time behaviour.  The gc thread  can be controlled
         using set_prolog_gc_thread/1.

    ggeenneerraattee__ddeebbuugg__iinnffoo _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default) generate  code  that can  be debugged  using
         trace/0, spy/1, etc.   Can be set to false using  the -nodebug.
         This  flag is  scoped  within  a source  file.    Many  of  the
         libraries  have  :- set_prolog_flag(generate_debug_info, false)
         to hide their details from a normal trace.

    ggmmpp__vveerrssiioonn _(_i_n_t_e_g_e_r_)
         If  Prolog is  linked  with  GMP,  this flag  gives  the  major
         version of the GMP library used.  See also section ????.

    gguuii _(_b_o_o_l_)
         Set to true if XPCE is around and can be used for graphics.

    hhiissttoorryy _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         If _i_n_t_e_g_e_r >0,  support Unix csh(1)-like  history as described
         in  section ????.     Otherwise, only  support  reusing  commands
         through the command  line editor.   The default is to set  this
         Prolog flag  to 0  if a command  line editor  is provided  (see
         Prolog flag readline) and 15 otherwise.

    hhoommee _(_a_t_o_m_)
         SWI-Prolog's  notion  of  the  home  directory.      SWI-Prolog
         uses  its  home   directory  to  find   its  startup  file   as
         <_h_o_m_e>/boot32.prc(32-bit machines) or <_h_o_m_e>/boot64.prc (64-bit
         machines) and to find its library as <_h_o_m_e>/library.

    hhwwnndd _(_i_n_t_e_g_e_r_)
         In swipl-win.exe, this  refers to the MS-Windows window  handle
         of the console window.

    iinntteeggeerr__rroouunnddiinngg__ffuunnccttiioonn _(_d_o_w_n_,_t_o_w_a_r_d___z_e_r_o_)
         ISO Prolog flag  describing rounding by  // and rem  arithmetic
         functions.  Value depends on the C compiler used.

    iissoo _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Include some weird ISO compatibility that is  incompatible with
         normal SWI-Prolog behaviour.   Currently  it has the  following
         effect:

           o The  //2 (float division) _a_l_w_a_y_s  returns a float, even  if
             applied to integers that can be divided.

           o In  the  standard order  of  terms (see  section  ????),  all
             floats are before all integers.

           o atom_length/2 yields a type error if the  first argument is
             a number.

           o clause/[2,3]  raises  a  permission  error  when  accessing
             static predicates.

           o abolish/[1,2]  raises  a permission  error  when  accessing
             static predicates.

           o Syntax is closer to the ISO standard:

               {{  Unquoted commas and  bars appearing  as atoms are  not
                  allowed.    Instead  of  f(,,a)  now  write  f(',',a).
                  Unquoted  commas   can  only  be   used  to   separate
                  arguments in  functional notation  and list  notation,
                  and  as  a  conjunction  operator.      Unquoted  bars
                  can only  appear  within lists  to separate  head  and
                  tail,  like [Head|Tail],  and  as infix  operator  for
                  alternation in grammar rules, like a --> b | c.

               {{  Within functional  notation  and list  notation  terms
                  must  have priority  below  1000.    That  means  that
                  rules and  control constructs  appearing as  arguments
                  need  bracketing.    A  term  like  [a :- b, c].  must
                  now  be  disambiguated   to  mean  [(a :- b), c].   or
                  [(a :- b, c)].

               {{  Operators appearing  as  operands must  be  bracketed.
                  Instead   of   X == -, true.   write   X == (-), true.
                  Currently, this is not entirely enforced.

               {{  Backslash-escaped newlines  are interpreted  according
                  to the ISO standard.  See section ????.

    llaarrggee__ffiilleess _(_b_o_o_l_)
         If present and  true, SWI-Prolog has  been compiled with  _l_a_r_g_e
         _f_i_l_e _s_u_p_p_o_r_t  (LFS) and  is capable of  accessing files  larger
         than 2GB on 32-bit hardware.  Large file support  is default on
         installations built using configure that support it  and may be
         switched off using the configure option --disable-largefile.

    llaasstt__ccaallll__ooppttiimmiissaattiioonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines whether  or not last-call  optimisation is  enabled.
         Normally  the  value  of this  flag  is  the  negation  of  the
         debug flag.   As  programs may  run out of  stack if  last-call
         optimisation is  omitted, it is  sometimes necessary to  enable
         it during debugging.

    mmaaxx__aarriittyy _(_u_n_b_o_u_n_d_e_d_)
         ISO  Prolog  flag describing  there  is  no  maximum  arity  to
         compound terms.

    mmaaxx__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Maximum integer value  if integers are _b_o_u_n_d_e_d.   See also  the
         flag bounded and section ????.

    mmaaxx__ttaaggggeedd__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Maximum integer value represented as a `tagged' value.   Tagged
         integers  require  one word  storage.     Larger  integers  are
         represented as `indirect  data' and require significantly  more
         space.

    mmiinn__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Minimum integer value  if integers are _b_o_u_n_d_e_d.   See also  the
         flag bounded and section ????.

    mmiinn__ttaaggggeedd__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Start of the tagged-integer value range.

    ooccccuurrss__cchheecckk _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  flag  controls  unification  that  creates   an  infinite
         tree  (also called  _c_y_c_l_i_c _t_e_r_m)  and  can have  three  values.
         Using  false  (default),  unification  succeeds,   creating  an
         infinite  tree.       Using   true,   unification  behaves   as
         unify_with_occurs_check/2, failing  silently.   Using error,  an
         attempt to  create  a cyclic  term results  in an  occurs_check
         exception.  The latter is intended  for debugging unintentional
         creations of  cyclic terms.   Note that this  flag is a  global
         flag modifying fundamental behaviour  of Prolog.  Changing  the
         flag from its default  may cause libraries to stop  functioning
         properly.

    ooppeenn__sshhaarreedd__oobbjjeecctt _(_b_o_o_l_)
         If  true,  open_shared_object/2 and  friends  are  implemented,
         providing access  to shared  libraries (.so  files) or  dynamic
         link libraries (.DLL files).

    ooppttiimmiissee _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, compile in optimised mode.  The initial  value is true
         if Prolog  was started with the  -O command line  option.   The
         optimise flag is scoped to a source file.

         Currently   optimised  compilation   implies   compilation   of
         arithmetic, and  deletion of redundant  true/0 that may  result
         from expand_goal/2.

         Later versions might imply various other optimisations  such as
         integrating small  predicates into  their callers,  eliminating
         constant expressions and other predictable constructs.   Source
         code  optimisation is  never  applied  to predicates  that  are
         declared dynamic (see dynamic/1).

    ooss__aarrggvv _(_l_i_s_t_, _c_h_a_n_g_e_a_b_l_e_)
         List  is  a  list  of  atoms  representing   the  command  line
         arguments used  to invoke  SWI-Prolog.   Please  note that  aallll
         arguments are included in the  list returned.  See argv  to get
         the application options.

    ppiidd _(_i_n_t_)
         Process identifier of  the running Prolog  process.   Existence
         of this flag is implementation-defined.

    ppiippee _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true,  open(pipe(command), mode, Stream),   etc.  are  sup-
         ported.    Can  be  changed to  disable  the use  of  pipes  in
         applications testing this feature.  Not recommended.

    pprriinntt__wwrriittee__ooppttiioonnss _(_t_e_r_m_, _c_h_a_n_g_e_a_b_l_e_)
         Specifies  the options  for write_term/2  used by  print/1  and
         print/2.

    pprroommpptt__aalltteerrnnaattiivveess__oonn _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Determines prompting for alternatives in the Prolog  top level.
         Default  is  determinism,  which  implies  the  system  prompts
         for alternatives  if the  goal succeeded  while leaving  choice
         points.   Many classical Prolog  systems behave as  groundness:
         they prompt for alternatives if and only if  the query contains
         variables.

    pprrootteecctt__ssttaattiicc__ccooddee _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default  false), clause/2 does  not operate on  static
         code, providing  some basic protection  from hackers that  wish
         to list the static code of your Prolog program.   Once the flag
         is true,  it cannot be  changed back to false.   Protection  is
         default in  ISO mode (see  Prolog flag  iso).   Note that  many
         parts of the  development environment require clause/2 to  work
         on static  code, and  enabling this  flag should  thus only  be
         used for production code.

    qqccoommppiillee _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  option  provides  the  default  for  the  qcompile(_+_A_t_o_m)
         option of load_files/2.

    rreeaaddlliinnee _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Specifies  which form  of  command  line editing  is  provided.
         Possible values  are  below.   The  flag may  be  set from  the
         user's init file (see section ????) to one of  false, readline or
         editline.  This causes the toplevel not to load  a command line
         editor (false)  or load the  specified one.   If loading  fails
         the flag is set to false.

         ffaallssee
             No command line editing is available.

         rreeaaddlliinnee
             The  library  readline is  loaded, providing  line  editing
             based on the GNU readline library.

         eeddiittlliinnee
             The  library  editline is  loaded, providing  line  editing
             based on the BSD libedit.   This is the default if editline
             is available and can be loaded.

         sswwiippll__wwiinn
             SWI-Prolog uses its own  console (swipl-win.exe on Windows,
             the  Qt  based  swipl-win on  MacOS)  which  provides  line
             editing.

    rreessoouurrccee__ddaattaabbaassee _(_a_t_o_m_)
         Set to the absolute filename of the attached state.   Typically
         this is the file boot32.prc, the file specified with  -x or the
         running executable.  See also resource/3.

    rreeppoorrtt__eerrrroorr _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, print  error messages; otherwise  suppress them.   May
         be changed.  See also  the debug_on_errorProlog flag.   Default
         is true, except for the runtime version.

    rruunnttiimmee _(_b_o_o_l_)
         If present and  true, SWI-Prolog is  compiled with -DO_RUNTIME,
         disabling various  useful development  features (currently  the
         tracer and profiler).

    ssaannddbbooxxeedd__llooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default  false), load_files/2  calls hooks  to  allow
         library(sandbox) to verify the safety of directives.

    ssaavveedd__pprrooggrraamm _(_b_o_o_l_)
         If present  and  true, Prolog  has been  started  from a  state
         saved with qsave_program/[1,2].

    sshhaarreedd__oobbjjeecctt__eexxtteennssiioonn _(_a_t_o_m_)
         Extension used  by  the operating  system for  shared  objects.
         .so for  most Unix  systems and  .dll for  Windows.   Used  for
         locating  files using  the  file_type  executable.    See  also
         absolute_file_name/3.

    sshhaarreedd__oobbjjeecctt__sseeaarrcchh__ppaatthh _(_a_t_o_m_)
         Name of the environment  variable used by the system  to search
         for shared objects.

    ssiiggnnaallss _(_b_o_o_l_)
         Determine  whether Prolog  is  handling signals  (software  in-
         terrupts).   This  flag is  false if  the hosting  OS does  not
         support signal handling  or the command line option  -nosignals
         is active.  See section ???? for details.

    ssttrreeaamm__ttyyppee__cchheecckk _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Defines whether  and  how strictly  the system  validates  that
         byte I/O  should not be  applied to text  streams and text  I/O
         should not be applied to binary streams.  Values  are false (no
         checking),  true (full  checking) and  loose.   Using  checking
         mode loose  (default), the  system accepts byte  I/O from  text
         stream that use ISO  Latin-1 encoding and accepts writing  text
         to binary streams.

    ssyysstteemm__tthhrreeaadd__iidd _(_i_n_t_)
         Available  in  multithreaded version  (see  section  ????)  where
         the  operating  system  provides  system-wide   integer  thread
         identifiers.    The  integer  is  the  thread  identifier  used
         by the  operating system  for  the calling  thread.   See  also
         thread_self/1.

    ttaabbllee__ssppaaccee _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         Space reserved for storing answer tables for  _t_a_b_l_e_d _p_r_e_d_i_c_a_t_e_s
         (see  table/1).    When exceeded  a  resource_error(_t_a_b_l_e___s_p_a_c_e)
         exception is raised.

    ttiimmeezzoonnee _(_i_n_t_e_g_e_r_)
         Offset in seconds  west of GMT of the  current time zone.   Set
         at initialization  time from the  timezone variable  associated
         with the POSIX tzset() function.  See also format_time/3.

    ttoopplleevveell__ggooaall _(_t_e_r_m_, _c_h_a_n_g_e_a_b_l_e_)
         Defines  the goal  that  is  executed after  running  the  ini-
         tialization goals  and entry  point (see  -g,  initialization/2
         and section  ????.   The  initial value  is  default, starting  a
         normal interactive session.   This  value may be changed  using
         the command  line option  -t.    The explicit  value prolog  is
         equavalent to  default.   If initialization(_G_o_a_l_,_m_a_i_n) is  used
         and the toplevel is  default, the toplevel is set to  halt (see
         halt/0).

    ttoopplleevveell__mmooddee _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         If  backtracking  (default),  the   toplevel  backtracks  after
         completing a query.  If recursive, the  toplevel is implemented
         as a recursive  loop.  This  implies that global variables  set
         using b_setval/2 are maintained between queries.   In _r_e_c_u_r_s_i_v_e
         mode, answers to  toplevel variables (see section ????) are  kept
         in backtrackable  global variables  and thus  nnoott ccooppiieedd.    In
         _b_a_c_k_t_r_a_c_k_i_n_g mode  answers to  toplevel variables  are kept  in
         the recorded database (see section ????).

         The recursive mode has been added for interactive  usage of CHR
         (see section ????),  which maintains the global constraint  store
         in backtrackable global variables.

    ttoopplleevveell__pprriinntt__aannoonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true,  top-level variables starting  with an  underscore (_)
         are printed normally.   If false they are hidden.  This  may be
         used to hide bindings in complex queries from the top level.

    ttoopplleevveell__pprriinntt__ffaaccttoorriizzeedd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default false)  show the internal sharing of  subterms
         in  the  answer  substitution.     The  example  below  reveals
         internal  sharing   of  leaf  nodes   in  _r_e_d_-_b_l_a_c_k  _t_r_e_e_s   as
         implemented by the rbtrees predicate rb_new/1:

         _______________________________________________________________|                                                               |

         |?- set_prolog_flag(toplevel_print_factorized, true).           |
         |?- rb_new(X).                                                  |
         |X = t(_S1, _S1), % where                                       |
         ||____S1_=_black('',__G387,__G388,_'').________________________ ||

         If this flag  is false, the % where  notation is still used  to
         indicate cycles as illustrated below.  This  example also shows
         that the implementation reveals the internal cycle  length, and
         _n_o_t the minimal cycle  length.  Cycles of different  length are
         indistinguishable in Prolog (as illustrated by S == R).

         _______________________________________________________________|                                                               |
         |?- S = s(S), R = s(s(R)), S == R.                              |

         |S = s(S),                                                      |
         |R|=_s(s(R)).__________________________________________________ | |

    aannsswweerr__wwrriittee__ooppttiioonnss _(_t_e_r_m_, _c_h_a_n_g_e_a_b_l_e_)
         This  argument is  given  as  option-list to  write_term/2  for
         printing  results  of  queries.     Default  is  [quoted(true),
         portray(true), max_depth(10), attributes(portray)].

    ttoopplleevveell__pprroommpptt _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Define the prompt  that is used  by the interactive top  level.
         The following ~ (tilde) sequences are replaced:

         _____________________________________________________________________~m_T_y_p_e _i_n module if not user (see module/1)

          ~l  _B_r_e_a_k _l_e_v_e_l if not 0 (see break/0)
          ~d  _D_e_b_u_g_g_i_n_g _s_t_a_t_e if not normal execution (see debug/0, trace/0)
         _~!___H_i_s_t_o_r_y__e_v_e_n_t_if_history_is_enabled_(see_flag_history)__________

    ttoopplleevveell__vvaarr__ssiizzee _(_i_n_t_, _c_h_a_n_g_e_a_b_l_e_)
         Maximum  size counted  in  literals of  a  term returned  as  a
         binding for a variable  in a top-level query that is  saved for
         re-use using the $ variable reference.  See section ????.

    ttrraaccee__ggcc _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default  false), garbage collections and  stack-shifts
         will be reported on the terminal.  May be changed.   Values are
         reported in bytes  as G+T, where G  is the global stack  value
         and T  the trail stack  value.   `Gained' describes the  number
         of bytes reclaimed.   `used' the  number of bytes on the  stack
         after GC and `free'  the number of bytes allocated, but  not in
         use.  Below is an example output.

         _______________________________________________________________|                                                               |
         |% GC: gained 236,416+163,424 in 0.00 sec;                      |
         ||_____used_13,448+5,808;_free_72,568+47,440___________________ ||

    ttrraaddiittiioonnaall _(_b_o_o_l_)
         Available in  SWI-Prolog version  7.    If true,  `traditional'
         mode has been selected  using --traditional.  Notice  that some
         SWI7 features,  like the functional notation  on dicts, do  not
         work in this mode.  See also section ????.

    ttttyy__ccoonnttrrooll _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines whether  the terminal  is switched to  raw mode  for
         get_single_char/1,  which also  reads the user  actions for  the
         trace.  May be set.  If this flag is  false at startup, command
         line editing  is disabled.   See also  the +/-tty command  line
         option.

    uunniixx _(_b_o_o_l_)
         If present  and  true,  the operating  system is  some  version
         of Unix.    Defined  if the  C compiler  used  to compile  this
         version of  SWI-Prolog either  defines __unix__  or unix.    On
         other systems this flag is  not available.  See also  apple and
         windows.

    uunnkknnoowwnn _(_f_a_i_l_,_w_a_r_n_i_n_g_,_e_r_r_o_r_, _c_h_a_n_g_e_a_b_l_e_)
         Determines  the behaviour  if  an  undefined procedure  is  en-
         countered.    If  fail,  the  predicate  fails silently.     If
         warn,  a warning  is printed,  and  execution continues  as  if
         the predicate  was  not defined,  and  if error  (default),  an
         existence_error exception is  raised.   This flag  is local  to
         each  module and  inherited  from the  module's  _i_m_p_o_r_t_-_m_o_d_u_l_e.
         Using default setup,  this implies that normal modules  inherit
         the flag  from  user, which  in turn  inherit  the value  error
         from system.   The  user may  change the flag  for module  user
         to  change the  default  for  all application  modules  or  for
         a  specific module.     It  is strongly  advised  to  keep  the
         error default and  use dynamic/1 and/or multifile/1 to  specify
         possible non-existence of a predicate.

    uunnllooaadd__ffoorreeiiggnn__lliibbrraarriieess _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default  false), unload all loaded foreign  libraries.
         Default is  false  because modern  OSes reclaim  the  resources
         anyway and  unloading  the foreign  code may  cause  registered
         hooks to point to no longer existing data or code.

    uusseerr__ffllaaggss _(_A_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Define  the  behaviour  of  set_prolog_flag/2 if  the  flag  is
         not  known.    Values are  silent,  warning  and  error.    The
         first two  create  the flag  on-the-fly,  where warning  prints
         a  message.    The  value  error is  consistent  with  ISO:  it
         raises an existence  error and does not  create the flag.   See
         also create_prolog_flag/3.  The  default is silent, but  future
         versions may  change that.   Developers  are encouraged to  use
         another value and ensure  proper use of create_prolog_flag/3 to
         create flags for their library.

    vvaarr__pprreeffiixx _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default  false), variables must  start with an  under-
         score (_).  May be changed.   This flag is local to  the module
         in which it is changed.  See section ????.

    vveerrbboossee _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This flag is used by print_message/2.  If its  value is silent,
         messages of type informational and banner are suppressed.   The
         -q switches the value from the initial normal to silent.

    vveerrbboossee__aauuttoollooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true the  normal  consult  message  will be  printed  if  a
         library is autoloaded.  By default this  message is suppressed.
         Intended to be used for debugging purposes.

    vveerrbboossee__llooaadd _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Determines  messages printed  for  loading  (compiling)  Prolog
         files.    Current  values are  full  (print  a message  at  the
         start and  end of each  file loaded),  normal (print a  message
         at the  end of  each file loaded),  brief (print  a message  at
         end of  loading the  toplevel file),  and  silent (no  messages
         are printed,  default).   The  value of this  flag is  normally
         controlled by the option silent(_B_o_o_l) provided by load_files/2.

    vveerrbboossee__ffiillee__sseeaarrcchh _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true  (default   false),  print  messages  indicating   the
         progress   of  absolute_file_name/[2,3]  in   locating   files.
         Intended for  debugging  complicated file-search  paths.    See
         also file_search_path/2.

    vveerrssiioonn _(_i_n_t_e_g_e_r_)
         The version identifier is an integer with value:

                          10000_*Major+ 100_*Minor+_P_a_t_c_h

    vveerrssiioonn__ddaattaa _(_s_w_i_(_M_a_j_o_r_, _M_i_n_o_r_, _P_a_t_c_h_, _E_x_t_r_a_)_)
         Part of the  dialect compatibility layer;  see also the  Prolog
         flag dialect and section ????.   _E_x_t_r_a provides platform-specific
         version information  as  a list.    _E_x_t_r_a  is used  for  _t_a_g_g_e_d
         _v_e_r_s_i_o_n_s such as ``7.4.0-rc1'', in which case  _E_x_t_r_a contains a
         term tag(_r_c_1).

    vveerrssiioonn__ggiitt _(_a_t_o_m_)
         Available if created from  a git repository.   See git-describe
         for details.

    wwaarrnn__oovveerrrriiddee__iimmpplliicciitt__iimmppoorrtt _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true (default),  a  warning  is printed  if  an  implicitly
         imported predicate  is clobbered by  a local  definition.   See
         use_module/1 for details.

    wwiinn__ffiillee__aacccceessss__cchheecckk _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Controls the behaviour  or access_file/2 under Windows.   There
         is no  reliable way to  check access  to files and  directories
         on Windows.    This  flag allows  for  switching between  three
         alternative approximations.

         aacccceessss
             Use Windows _waccess() function.  This ignores ACLs (Access
             Control List) and thus may  indicate that access is allowed
             while it is not.

         ffiilleesseeccuurriittyy
             Use the Windows GetFileSecurity() function.   This does not
             work on  all file systems, but is probably the  best choice
             on  file systems  that do  support it,  notably local  NTFS
             volumes.

         ooppeenncclloossee
             Try  to open the file  and close it.   This works  reliable
             for files, but not for  directories.  Currently directories
             are checked using _waccess().  This is the default.

    wwiinnddoowwss _(_b_o_o_l_)
         If present and true, the operating system  is an implementation
         of  Microsoft  Windows.     This  flag  is  only  available  on
         MS-Windows based versions.  See also unix.

    wwrriittee__aattttrriibbuutteess _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Defines how  write/1  and friends  write attributed  variables.
         The option values are  described with the attributes option  of
         write_term/3.  Default is ignore.

    wwrriittee__hheellpp__wwiitthh__oovveerrssttrriikkee _(_b_o_o_l_)
         Internal flag used  by help/1 when writing  to a terminal.   If
         present  and true  it prints  bold  and underlined  text  using
         _o_v_e_r_s_t_r_i_k_e.

    xxppccee _(_b_o_o_l_)
         Available  and set  to  true if  the  XPCE graphics  system  is
         loaded.

    xxppccee__vveerrssiioonn _(_a_t_o_m_)
         Available and set to the version of the loaded XPCE system.

    xxrreeff _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true, source code  is being read for _a_n_a_l_y_s_i_s  purposes such
         as cross-referencing.    Otherwise (default) it  is being  read
         to  be compiled.    This  flag is  used  at several  places  by
         term_expansion/2 and goal_expansion/2 hooks,  notably if  these
         hooks use side effects.   See also  the libraries prolog_source
         and prolog_xref.


sseett__pprroolloogg__ffllaagg((_:_K_e_y_, _+_V_a_l_u_e))                                      _[_I_S_O_]
    Define  a new  Prolog flag or  change its value.    _K_e_y is an  atom.
    If  the flag is a system-defined flag that is not  marked _c_h_a_n_g_e_a_b_l_e
    above,  an  attempt to  modify the flag  yields a  permission_error.
    If  the  provided _V_a_l_u_e  does not  match  the type  of the  flag,  a
    type_error is raised.

    Some  flags (e.g.,  unknown) are maintained  on a per-module  basis.
    The addressed module is determined by the _K_e_y argument.

    In  addition  to  ISO,  SWI-Prolog allows  for  user-defined  Prolog
    flags.   The type of the  flag is determined from the  initial value
    and  cannot be changed  afterwards.   Defined types are boolean  (if
    the  initial value is one  of false, true, on  or off), atom if  the
    initial value is any  other atom, integer if the value is an integer
    that  can be expressed as a 64-bit signed value.  Any  other initial
    value  results  in an  untyped  flag that  can represent  any  valid
    Prolog term.

    The  behaviour when _K_e_y  denotes a non-existent  key depends on  the
    Prolog  flag user_flags.   The default is  to define them  silently.
    New code is encouraged to use create_prolog_flag/3 for portability.


ccrreeaattee__pprroolloogg__ffllaagg((_+_K_e_y_, _+_V_a_l_u_e_, _+_O_p_t_i_o_n_s))                         _[_Y_A_P_]
    Create  a  new Prolog  flag.    The ISO  standard does  not  foresee
    creation  of  new flags,  but many  libraries  introduce new  flags.
    _O_p_t_i_o_n_s is a list of the options below.  See also user_flags.

    aacccceessss((_+_A_c_c_e_s_s))
         Define access rights for  the flag.  Values  are read_write  and
         read_only.  The default is read_write.

    ttyyppee((_+_A_t_o_m))
         Define a type restriction.  Possible values  are boolean, atom,
         integer,  float and  term.    The  default is  determined  from
         the initial  value.  Note  that term restricts  the term to  be
         ground.

    kkeeeepp((_+_B_o_o_l_e_a_n))
         If true, do not modify  the flag if it already exists.   Other-
         wise (default), this predicate  behaves as set_prolog_flag/2 if
         the flag already exists.


22..1122 AAnn oovveerrvviieeww ooff hhooookk pprreeddiiccaatteess

SWI-Prolog provides a large number of hooks, mainly  to control handling
messages, debugging,  startup, shut-down, macro-expansion,  etc.   Below
is  a  summary  of  all  defined  hooks  with  an  indication  of  their
portability.

  o _p_o_r_t_r_a_y_/_1
    Hook into write_term/3 to alter the way terms are printed (ISO).

  o _m_e_s_s_a_g_e___h_o_o_k_/_3
    Hook  into  print_message/2 to  alter the  way system  messages  are
    printed (Quintus/SICStus).

  o _m_e_s_s_a_g_e___p_r_o_p_e_r_t_y_/_2
    Hook  into  print_message/2  that  defines  prefix,  output  stream,
    color, etc.

  o _l_i_b_r_a_r_y___d_i_r_e_c_t_o_r_y_/_1
    Hook  into  absolute_file_name/3 to define  new library  directories
    (most Prolog systems).

  o _f_i_l_e___s_e_a_r_c_h___p_a_t_h_/_2
    Hook   into   absolute_file_name/3  to  define   new  search   paths
    (Quintus/SICStus).

  o _t_e_r_m___e_x_p_a_n_s_i_o_n_/_2
    Hook  into  load_files/2  to  modify  read  terms  before  they  are
    compiled (macro-processing) (most Prolog systems).

  o _g_o_a_l___e_x_p_a_n_s_i_o_n_/_2
    Same as term_expansion/2 for individual goals (SICStus).

  o _p_r_o_l_o_g___l_o_a_d___f_i_l_e_/_2
    Hook  into  load_files/2  to  load other  data  formats  for  Prolog
    sources  from `non-file' resources.   The load_files/2 predicate  is
    the ancestor of consult/1, use_module/1, etc.

  o _q_p_r_e_d_r_e_f_p_r_o_l_o_g___e_d_i_t_l_o_c_a_t_e_3
    Hook into edit/1 to locate objects (SWI).

  o _q_p_r_e_d_r_e_f_p_r_o_l_o_g___e_d_i_t_e_d_i_t___s_o_u_r_c_e_1
    Hook into edit/1 to call an internal editor (SWI).

  o _p_r_o_l_o_g___e_d_i_t_:_e_d_i_t___c_o_m_m_a_n_d_/_2
    Hook into edit/1 to define the external editor to use (SWI).

  o _p_r_o_l_o_g___l_i_s_t___g_o_a_l_/_1
    Hook  into the tracer  to list the  code associated to a  particular
    goal (SWI).

  o _p_r_o_l_o_g___t_r_a_c_e___i_n_t_e_r_c_e_p_t_i_o_n_/_4
    Hook into the tracer to handle trace events (SWI).

  o _q_p_r_e_d_r_e_f_p_r_o_l_o_g_d_e_b_u_g___c_o_n_t_r_o_l___h_o_o_k_1
    Hook  in spy/1, nospy/1, nospyall/0 and debugging/0 to  extend these
    control predicates to higher-level libraries.

  o _q_p_r_e_d_r_e_f_p_r_o_l_o_g_h_e_l_p___h_o_o_k_1
    Hook in help/0, help/1 and apropos/1 to extend the help system.

  o _r_e_s_o_u_r_c_e_/_3
    Define a new resource (not really a hook, but similar) (SWI).

  o _e_x_c_e_p_t_i_o_n_/_3
    Old  attempt  to  a  generic  hook mechanism.     Handles  undefined
    predicates (SWI).

  o _a_t_t_r___u_n_i_f_y___h_o_o_k_/_2
    Unification  hook for attributed variables.   Can be defined in  any
    module.  See section ???? for details.


22..1133 AAuuttoommaattiicc llooaaddiinngg ooff lliibbrraarriieess

If ---at runtime--- an  undefined predicate is trapped, the  system will
first try to import the predicate from the module's  default module (see
section ????.    If this fails  the _a_u_t_o _l_o_a_d_e_r  is activated.   On  first
activation an  index to  all library  files in  all library  directories
is  loaded  in  core  (see library_directory/1,  file_search_path/2  and
reload_library_index/0).   If the  undefined predicate can be located  in
one of the libraries, that library file is  automatically loaded and the
call to the (previously  undefined) predicate is restarted.   By default
this mechanism loads  the file silently.   The current_prolog_flag/2 key
verbose_autoload is provided  to get verbose loading.   The Prolog  flag
autoload can be used to enable/disable the autoload system.

Autoloading  only handles  (library) source  files that  use the  module
mechanism  described  in  chapter  ????.     The  files  are  loaded  with
use_module/2 and only the  trapped undefined predicate is imported  into
the  module where  the undefined  predicate was  called.   Each  library
directory  must hold  a file  INDEX.pl  that contains  an index  to  all
library files  in the directory.    This file consists  of lines of  the
following format:

________________________________________________________________________|                                                                        |
|index(Name,|Arity,_Module,_File).______________________________________ |           |

The  predicate make/0  updates the  autoload  index.   It  searches  for
all library directories (see library_directory/1 and file_search_path/2)
holding the file MKINDEX.pl or INDEX.pl.  If the  current user can write
or create the file INDEX.pl  and it does not exist or is older  than the
directory or one of its files, the index for  this directory is updated.
If the  file MKINDEX.pl  exists, updating  is achieved  by loading  this
file,  normally  containing  a  directive calling  make_library_index/2.
Otherwise make_library_index/1is  called, creating an index for all *.pl
files containing a module.

Below is an example creating an indexed library directory.

________________________________________________________________________|                                                                        |

|% mkdir ~/lib/prolog                                                    |
|% cd ~/lib/prolog                                                       |
|%|swipl_-g_true_-t_'make_library_index(.)'_____________________________ | |

If  there  is  more  than  one  library  file   containing  the  desired
predicate, the following search schema is followed:

 1. If  there is a  library file  that defines the  module in which  the
    undefined predicate is trapped, this file is used.

 2. Otherwise  library files  are considered  in the  order they  appear
    in  the  library_directory/1  predicate  and  within  the  directory
    alphabetically.


aauuttoollooaadd__ppaatthh((_+_D_i_r_A_l_i_a_s))
    Add  _D_i_r_A_l_i_a_s to  the  libraries that  are used  by the  autoloader.
    This  extends  the  search path  autoload  and reloads  the  library
    index.  For example:

    ____________________________________________________________________|                                                                    |
    ||:-_autoload_path(library(http)).__________________________________ ||

    If   this  call  appears  as   a  directive,  it  is   term-expanded
    into  a clause  for user:file_search_path/2 and  a directive  calling
    reload_library_index/0.   This keeps  source information and  allows
    for removing this directive.


mmaakkee__lliibbrraarryy__iinnddeexx((_+_D_i_r_e_c_t_o_r_y))
    Create  an index for this  directory.  The  index is written to  the
    file  'INDEX.pl' in the specified directory.   Fails with a  warning
    if the directory does not exist or is write protected.


mmaakkee__lliibbrraarryy__iinnddeexx((_+_D_i_r_e_c_t_o_r_y_, _+_L_i_s_t_O_f_P_a_t_t_e_r_n_s))
    Normally  used in  MKINDEX.pl, this  predicate creates INDEX.pl  for
    _D_i_r_e_c_t_o_r_y,  indexing all files that  match one of the file  patterns
    in _L_i_s_t_O_f_P_a_t_t_e_r_n_s.

    Sometimes  library packages consist  of one public  load file and  a
    number  of files used by  this load file, exporting predicates  that
    should not be used  directly by the end user.  Such a library can be
    placed  in a sub-directory of  the library and the files  containing
    public  functionality can  be  added to  the index  of the  library.
    As  an  example we  give the  XPCE library's  MKINDEX.pl,  including
    the  public  functionality of  trace/browse.pl to  the  autoloadable
    predicates for the XPCE package.

    ____________________________________________________________________|                                                                    |
    | :- make_library_index('.',                                         |

    |                       [ '*.pl',                                    |
    |                         'trace/browse.pl'                          |
    ||______________________])._________________________________________ ||


rreellooaadd__lliibbrraarryy__iinnddeexx
    Force  reloading  the  index  after modifying  the  set  of  library
    directories   by   changing  the   rules  for   library_directory/1,
    file_search_path/2,  adding  or  deleting  INDEX.pl  files.     This
    predicate   does   _n_o_t   update  the   INDEX.pl   files.       Check
    make_library_index/[1,2] and make/0 for updating the index files.

    Normally, the index  is reloaded automatically if a predicate cannot
    be  found  in the  index  and the  set  of library  directories  has
    changed.   Using reload_library_index/0 is necessary if  directories
    are removed or the order of the library directories is changed.

When  creating an  executable  using either  qsave_program/2 or  the  -c
command  line options,  it is  necessarry to  load  all predicates  that
would  normally  be  autoloaded  explicitly.     This  is  discussed  in
section ????.  See autoload/0.


22..1144 PPaacckkss::  ccoommmmuunniittyy aadddd--oonnss

SWI-Prolog  has  a   mechanism  for  easy  incorporation  of   community
extensions.    See the  http://www.swi-prolog.org/pack/listpack  landing
page  for  details  and  available  packs.      This  section  documents
the  built-in predicates  to attach  packs.    Predicates for  creating,
registering  and   installing  packs   are  provided   by  the   library
prolog_pack.


aattttaacchh__ppaacckkss
    Attaches  all  packs  in  subdirectories  of  directories  that  are
    accessible  through the _f_i_l_e _s_e_a_r_c_h  _p_a_t_h (see absolute_file_name/3)
    pack.  The default for this search path is:

    ____________________________________________________________________|                                                                    |
    | user:file_search_path(pack, app_data(pack)).                       |

    ||user:file_search_path(pack,_swi(pack)).___________________________ ||

    The predicate attach_packs/0 is called on startup of SWI-Prolog.


aattttaacchh__ppaacckkss((_+_D_i_r_e_c_t_o_r_y))
    Attach  all  packs   in  subdirectories  of  _D_i_r_e_c_t_o_r_y.     Same  as
    attach_packs(_D_i_r_e_c_t_o_r_y_, _[_]).


aattttaacchh__ppaacckkss((_+_D_i_r_e_c_t_o_r_y_, _+_O_p_t_i_o_n_s))
    Attach  all packs in  subdirectories of _D_i_r_e_c_t_o_r_y.   Options is  one
    of:

    sseeaarrcchh((_+_W_h_e_r_e))
         Determines the  order  in which  pack library  directories  are
         searched.   Default is to add  new packages at the end  (last).
         Using first, new packages are added at the start.

    dduupplliiccaattee((_+_A_c_t_i_o_n))
         Determines  what happens  if  a  pack  with the  same  name  is
         already attached.   Default is warning, which prints  a warning
         and ignores the  new pack.   Other options  are keep, which  is
         like warning but operates silently and replace,  which detaches
         the old pack and attaches the new.

    The  predicate attach_packs/2 can  be used  to attach packages  that
    are bundled with an application.


22..1155 GGaarrbbaaggee CCoolllleeccttiioonn

SWI-Prolog provides garbage collection, last-call optimization  and atom
garbage collection.   These features  are controlled using Prolog  flags
(see current_prolog_flag/2).


22..1166 TThhee SSWWII--PPrroolloogg ssyynnttaaxx

SWI-Prolog  syntax  is  close  to  ISO-Prolog  standard  syntax,   which
is  based  on  the  Edinburgh Prolog  syntax.     A  formal  description
can  be  found  in  the  ISO  standard  document.      For  an  informal
introduction  we  refer  to Prolog  text  books  (see  section  ????)  and
http://www.swi-prolog.org/Links.htmlonline tutorials.    In addition  to
the  differences  from the  ISO  standard  documented  here,  SWI-Prolog
offers several extensions,  some of which also  extend the syntax.   See
section ???? for more information.


22..1166..11 IISSOO SSyynnttaaxx SSuuppppoorrtt

This section lists various extensions w.r.t. the ISO Prolog syntax.


22..1166..11..11 PPrroocceessssoorr CChhaarraacctteerr SSeett

The processor character  set specifies the class of each  character used
for parsing Prolog  source text.   Character classification is fixed  to
http://www.unicode.org/Unicode.  See also section ????.


22..1166..11..22 NNeesstteedd ccoommmmeennttss

SWI-Prolog  allows  for  nesting /* ...*/  comments.     Where  the  ISO
standard accepts  /* .../* ...*/ as  a comment,  SWI-Prolog will  search
for  a terminating  */.    This is  useful if  some  code with  /* ...*/
comment statements  in it should  be commented out.   This  modification
also  avoids unintended  commenting  in  the example  below,  where  the
closing */ of the first comment has been forgotten.

________________________________________________________________________|                                                                        |
|/* comment                                                              |

|                                                                        |
|code                                                                    |
|                                                                        |
|/* second comment */                                                    |
|                                                                        |
|code                                                                    |
||______________________________________________________________________ ||


22..1166..11..33 CChhaarraacctteerr EEssccaappee SSyynnttaaxx

Within quoted atoms (using single quotes:   '<atom>') special characters
are  represented using  escape sequences.    An escape  sequence is  led
in  by the  backslash  (\) character.    The  list of  escape  sequences
is compatible  with the ISO standard  but contains some extensions,  and
the interpretation of numerically specified characters  is slightly more
flexible to improve compatibility.  Undefined escape  characters raise a
syntax_error exception.

\a
    Alert character.  Normally the ASCII character 7 (beep).

\b
    Backspace character.

\c
    No  output.    All input  characters  up to  but not  including  the
    first  non-layout  character  are skipped.     This allows  for  the
    specification  of pretty-looking long lines.  Not supported  by ISO.
    Example:

    ____________________________________________________________________|                                                                    |
    | format('This is a long line that looks better if it was \c         |

    ||_______split_across_multiple_physical_lines_in_the_input')________ ||

\<NEWLINE>
    When  in  ISO  mode  (see  the Prolog  flag  iso),  only  skip  this
    sequence.    In native mode,  white space  that follows the  newline
    is  skipped as well and a  warning is printed, indicating that  this
    construct  is deprecated and  advising to use \c.   We advise  using
    \c  or putting  the layout  _b_e_f_o_r_e the  \, as  shown below.    Using
    \c  is supported  by various other  Prolog implementations and  will
    remain  supported by SWI-Prolog.  The style shown below is  the most
    compatible solution.

    ____________________________________________________________________|                                                                    |

    | format('This is a long line that looks better if it was \          |
    ||split_across_multiple_physical_lines_in_the_input')_______________ ||

    instead of

    ____________________________________________________________________|                                                                    |
    | format('This is a long line that looks better if it was\           |
    ||_split_across_multiple_physical_lines_in_the_input')______________ ||

    Note  that SWI-Prolog  also allows unescaped  newlines to appear  in
    quoted material.   This is not allowed be the ISO standard, but used
    to be common practice before.

\e
    Escape character (ASCII 27).  Not ISO, but widely supported.

\f
    Form-feed character.

\n
    Next-line character.

\r
    Carriage-return only (i.e., go back to the start of the line).

\s
    Space  character.    Intended  to  allow  writing 0'\s  to  get  the
    character code of the space character.  Not ISO.

\t
    Horizontal tab character.

\v
    Vertical tab character (ASCII 11).

\xXX..\
    Hexadecimal  specification  of  a  character.    The  closing  \  is
    obligatory   according  to  the  ISO   standard,  but  optional   in
    SWI-Prolog  to   enhance  compatibility  with  the  older  Edinburgh
    standard.   The code \xa\3 emits the character 10  (hexadecimal `a')
    followed  by `3'.  Characters specified this way are  interpreted as
    Unicode characters.  See also \u.

\uXXXX
    Unicode  character specification  where the  character is  specified
    using  _e_x_a_c_t_l_y 4 hexadecimal  digits.  This  is an extension to  the
    ISO  standard,  fixing two  problems.   First,  where  \x defines  a
    numeric  character code,  it doesn't  specify the  character set  in
    which  the  character should  be interpreted.    Second,  it is  not
    needed to use the idiosyncratic closing \ ISO Prolog syntax.

\UXXXXXXXX
    Same as \uXXXX, but using 8 digits to cover the whole Unicode set.

\40
    Octal   character  specification.     The  rules  and   remarks  for
    hexadecimal specifications apply to octal specifications as well.

\\
    Escapes  the backslash itself.  Thus, '\\' is an atom  consisting of
    a single \.

\'
    Single  quote.  Note that '\'' and '''' both describe the  atom with
    a single ', i.e., '\'' == '''' is true.

\"
    Double quote.

\`
    Back quote.

Character        escaping       is        only       available        if
current_prolog_flag(character_escapes, true) is active (default).    See
current_prolog_flag/2.    Character  escapes  conflict with  writef/2  in
two  ways:   \40  is  interpreted as  decimal  40 by  writef/2,  but  as
octal  40 (decimal  32) by  read.   Also,  the writef/2  sequence \l  is
illegal.   It is advised to  use the more widely supported  format/[2,3]
predicate instead.   If  you insist upon  using writef/2, either  switch
character_escapes to false, or use double \\, as in writef('\\l').


22..1166..11..44 SSyynnttaaxx ffoorr nnoonn--ddeecciimmaall nnuummbbeerrss

SWI-Prolog  implements  both  Edinburgh  and  ISO   representations  for
non-decimal numbers.   According to  Edinburgh syntax, such numbers  are
written as <_r_a_d_i_x>'<number>, where <_r_a_d_i_x> is a number between 2 and 36.
ISO defines binary,  octal and hexadecimal numbers using 0[bxo]<_n_u_m_b_e_r>.
For example:  A is 0b100 \/ 0xf00  is a valid expression.   Such numbers
are always unsigned.


22..1166..11..55 UUssiinngg ddiiggiitt ggrroouuppss iinn llaarrggee iinntteeggeerrss

SWI-Prolog  supports   splitting  long   integers  into  _d_i_g_i_t   _g_r_o_u_p_s.
Digit  groups   can  be   separated  with  the   sequence  <_u_n_d_e_r_s_c_o_r_e>,
<_o_p_t_i_o_n_a_l _w_h_i_t_e _s_p_a_c_e>.   If the  <_r_a_d_i_x> is 10  or lower, they  may also
be separated  with exactly  one space.   The  following all express  the
integer 1 million:

________________________________________________________________________|                                                                        |
|1_000_000                                                               |

|1 000 000                                                               |
|1_000_/*more*/000|_____________________________________________________ |                 |

Integers can be printed using this notation with format/2,  using the ~I
format specifier.  For example:

________________________________________________________________________|                                                                        |
|?- format('~I', [1000000]).                                             |
|1_000_000|_____________________________________________________________ |         |

The  current  syntax  has been  proposed  by  Ulrich  Neumerkel  on  the
SWI-Prolog mailinglist.


22..1166..11..66 NNaaNN aanndd IInnffiinniittyy ffllooaattss aanndd tthheeiirr ssyynnttaaxx

SWI-Prolog supports reading an printing `special'  floating point values
according  to  http://eclipseclp.org/Specs/core_update_float.htmlProposal
for  Prolog  Standard  core update  wrt  floating  point  arithmetic  by
Joachim Schimpf and available in ECLiPSe Prolog.  In particular,

  o Infinity  is printed as  1.0Inf or -1.0Inf.   Any sequence  matching
    the  regular expression  [+-]?\sd+[.]\sd+Inf  is mapped  to plus  or
    minus infinity.

  o NaN  (Not  a Number)  is printed  as 1.xxxNaN,  where  _1_._x_x_x is  the
    float  after replacing the exponent by `1'.  Such numbers  are read,
    resulting  in the same  NaN. The NaN  constant can also be  produced
    using the function nan/0, e.g.,

    ____________________________________________________________________|                                                                    |

    | ?- A is nan.                                                       |
    ||A_=_1.5NaN._______________________________________________________ ||

Note that, compliant  with the ISO standard, SWI-Prolog  arithmetic (see
section ????) never returns one of the above values  but instead raises an
_e_x_c_e_p_t_i_o_n, e.g.,

________________________________________________________________________|                                                                        |
|?- A is 1/0.                                                            |

|ERROR:|//2:_Arithmetic:_evaluation_error:_`zero_divisor'_______________ |      |

There is one  exception to this rule.   For compatibility the  functions
inf/0 and nan/0  return 1.0Inf and the  default system NaN. The  ability
to create, read and write such values is  primarily provided to exchange
data with languages that can represent the full range of IEEE doubles.


22..1166..11..77 FFoorrccee oonnllyy uunnddeerrssccoorree ttoo iinnttrroodduuccee aa vvaarriiaabbllee

According to the ISO standard and most Prolog  systems, identifiers that
start with  an uppercase  letter or  an underscore  are variables.    In
the  past, _P_r_o_l_o_g  _b_y _B_I_M  provided an  alternative syntax,  where  only
the  underscore (_) introduces  a variable.    As  of SWI-Prolog  7.3.27
SWI-Prolog supports  this alternative syntax,  controlled by the  Prolog
flag var_prefix.  As the character_escapes flag, this flag is maintained
per module, where the default is false, supporting standard syntax.

Having only the  underscore introduce a variable is particularly  useful
if  code contains  identifiers for  case  sensitive external  languages.
Examples are  the RDF library where  code frequently specifies  property
and  class  names  and the  R  interface  for  specifying  functions  or
variables that  start with an  uppercase character.   Lexical  databases
were  part of  the  terms start  with  an  uppercase letter  is  another
category were the readability of the code improves using this option.


22..1166..11..88 UUnniiccooddee PPrroolloogg ssoouurrccee

The ISO standard  specifies the Prolog syntax  in ASCII characters.   As
SWI-Prolog supports Unicode  in source files we must extend  the syntax.
This  section describes  the implication  for  the source  files,  while
writing international source files is described in section ????.

The  SWI-Prolog Unicode  character classification  is  based on  version
6.0.0  of the  Unicode  standard.    Please  note  that char_type/2  and
friends, intended  to be used with all  text except Prolog source  code,
is based on the C library locale-based classification routines.

  o _Q_u_o_t_e_d _a_t_o_m_s _a_n_d _s_t_r_i_n_g_s
    Any  character  of  any script  can  be  used in  quoted  atoms  and
    strings.      The  escape  sequences  \uXXXX  and   \UXXXXXXXX  (see
    section ????) were  introduced to specify Unicode code points in ASCII
    files.

  o _A_t_o_m_s _a_n_d _V_a_r_i_a_b_l_e_s
    We  handle  them in  one item  as they  are closely  related.    The
    Unicode  standard  defines  a  syntax for  identifiers  in  computer
    languages.   In this syntax identifiers start with ID_Start followed
    by  a sequence of ID_Continue codes.  Such sequences are  handled as
    a  single token  in SWI-Prolog.    The token  is a  _v_a_r_i_a_b_l_e iff  it
    starts with  an uppercase character or an underscore (_).  Otherwise
    it  is an atom.   Note  that many languages do  not have the  notion
    of  character case.  In such languages variables _m_u_s_t be  written as
    _name.

  o _W_h_i_t_e _s_p_a_c_e
    All  characters marked as separators (Z*) in the Unicode  tables are
    handled as layout characters.

  o _C_o_n_t_r_o_l _a_n_d _u_n_a_s_s_i_g_n_e_d _c_h_a_r_a_c_t_e_r_s
    Control  and unassigned  (C*) characters produce  a syntax error  if
    encountered outside quoted atoms/strings and outside comments.

  o _O_t_h_e_r _c_h_a_r_a_c_t_e_r_s
    The  first 128 characters follow the  ISO Prolog standard.   Unicode
    symbol  and punctuation characters (general category S* and  P*) act
    as  glueing symbol  characters (i.e.,  just  like ==:   an  unquoted
    sequence of symbol characters are combined into an atom).

    Other  characters (this is mainly No:  _a _n_u_m_e_r_i_c _c_h_a_r_a_c_t_e_r  _o_f _o_t_h_e_r
    _t_y_p_e) are currently handled as `solo'.


22..1166..11..99 SSiinngglleettoonn vvaarriiaabbllee cchheecckkiinngg

A _s_i_n_g_l_e_t_o_n  _v_a_r_i_a_b_l_e is  a variable  that appears  only one  time in  a
clause.   It can always be  replaced by _, the  _a_n_o_n_y_m_o_u_s variable.   In
some cases,  however, people  prefer to give  the variable a  name.   As
mistyping a variable is a common mistake, Prolog  systems generally give
a  warning (controlled  by style_check/1)  if a  variable is  used  only
once.   The system can  be informed that a  variable is meant to  appear
once by _s_t_a_r_t_i_n_g it with  an underscore, e.g., _Name.  Please  note that
any variable,  except plain _, shares  with variables of the same  name.
The term  t(_X, _X) is equivalent  to t(X, X),  which is _d_i_f_f_e_r_e_n_t  from
t(_, _).

As  Unicode requires  variables  to start  with  an underscore  in  many
languages, this schema  needs to be extended.   First we define the  two
classes of named variables.

  o _N_a_m_e_d _s_i_n_g_l_e_t_o_n _v_a_r_i_a_b_l_e_s
    Named  singletons start with  a double underscore  (__) or a  single
    underscore followed by an uppercase letter, e.g., __var or _Var.

  o _N_o_r_m_a_l _v_a_r_i_a_b_l_e_s
    All other variables are  `normal' variables.  Note this makes _var a
    normal variable.

Any normal variable appearing  exactly once in the clause _a_n_d  any named
singleton variables appearing  more than once are  reported.  Below  are
some examples  with warnings in  the right column.   Singleton  messages
can be suppressed using the style_check/1 directive.

___________________________________________________________________________
| test(_).      |                                                         |

| test(_a).     |Singleton variables:  [_a]                                 |
| test(_12).    |Singleton variables:  [_12]                                |
| test(A).     |Singleton variables:  [A]                                 |
| test(_A).     |                                                         |
| test(__a).    |                                                         |
| test(_, _).   |                                                         |
| test(_a, _a). |                                                         |

| test(__a, __a).S|ingleton-marked variables appearing more than once:  [__a] |
| test(_A, _A). |Singleton-marked variables appearing more than once:  [_A] |
|_test(A,_A).__|__________________________________________________________|_

SSeemmaannttiicc ssiinngglleettoonnss

Starting with  version 6.5.1,  SWI-Prolog has  _s_y_n_t_a_c_t_i_c _s_i_n_g_l_e_t_o_n_s  and
_s_e_m_a_n_t_i_c  _s_i_n_g_l_e_t_o_n_s.    The first  are  checked  by read_clause/3  (and
read_term/3 using  the  option singletons(_w_a_r_n_i_n_g)).    The  latter  are
generated by the compiler  for variables that appear alone in  a _b_r_a_n_c_h.
For  example, in  the  code below  the  variable _X  is not  a  _s_y_n_t_a_c_t_i_c
singleton,  but the variable  _X does  not communicate  any bindings  and
replacing _X with _does not change the semantics.

________________________________________________________________________|                                                                        |

|test :-                                                                 |
|        (   test_1(X)                                                   |
|        ;   test_2(X)                                                   |
||_______)._____________________________________________________________ ||


22..1177 RRaattiioonnaall ttrreeeess ((ccyycclliicc tteerrmmss))

SWI-Prolog  supports  rational  trees,  also   known  as  cyclic  terms.
`Supports'  is  so  defined  that  most   relevant  built-in  predicates
terminate  when faced  with rational  trees.    Almost all  SWI-Prolog's
built-in term  manipulation predicates process terms  in a time that  is
linear to the amount of memory used to represent the  term on the stack.
The following set  of predicates safely handles rational trees:   =../2,
==/2,  =@=/2,  =/2, @</2 , @=</2,  @>=/2,  @>/2,  \==/2,  \=@=/2,  \=/2,
acyclic_term/1, bagof/3,  compare/3, copy_term/2, cyclic_term/1,  dif/2,
duplicate_term/2,   findall/3,  ground/1,   term_hash/2,   numbervars/3,
numbervars/4,    recorda/3,   recordz/3,    setof/3,    subsumes_term/2,
term_variables/2,   throw/1,   unify_with_occurs_check/2,    unifiable/3,
when/2, write/1 (and related predicates) .

In  addition,  some built-ins  recognise  rational  trees and  raise  an
appropriate exception.    Arithmetic evaluation belongs  to this  group.
The  compiler (asserta/1,  etc.)   also  raises  an exception.    Future
versions may  support rational  trees.   Predicates  that could  provide
meaningful processing  of rational  trees raise  a representation_error.
Predicates for  which rational trees  have no meaningful  interpretation
raise a type_error.  For example:

________________________________________________________________________|                                                                        |
|1 ?- A = f(A), asserta(a(A)).                                           |

|ERROR: asserta/1: Cannot represent due to `cyclic_term'                 |
|2 ?- A = 1+A, B is A.                                                   |
|ERROR: is/2: Type error: `expression' expected, found                   |
||____________`@(S_1,[S_1=1+S_1])'_(cyclic_term)________________________ ||


22..1188 JJuusstt--iinn--ttiimmee ccllaauussee iinnddeexxiinngg

SWI-Prolog  provides `just-in-time'  indexing over  multiple  arguments.
`Just-in-time' means that  clause indexes are not built by  the compiler
(or asserta/1  for dynamic predicates),  but on the  first call to  such
a predicate  where an  index might  help (i.e.,  a call  where at  least
one argument is  instantiated).  This  section describes the rules  used
by the  indexing logic.   Note that  this logic is  not `set in  stone'.
The indexing  capabilities of  the system  will change.   Although  this
inevitably leads  to some regressing  on some  particular use cases,  we
strive to avoid significant slowdowns.

The  list below  describes  the  clause selection  process  for  various
predicates and  calls.   The  alternatives are considered  in the  order
they are presented.

  o _S_p_e_c_i_a_l _p_u_r_p_o_s_e _c_o_d_e
    Currently two special  cases are recognised by the compiler:  static
    code  with exactly one clause and static code with two  clauses, one
    where  the first argument is the  empty list ([]) and one where  the
    first argument is a non-empty list ([_|_]).

  o _L_i_n_e_a_r _s_c_a_n _o_n _f_i_r_s_t _a_r_g_u_m_e_n_t
    The  principal clause list maintains  a _k_e_y for the first  argument.
    An  indexing  key is  either  a constant  or a  functor  (name/arity
    reference).    Calls with  an instantiated first  argument and  less
    than  10  clauses perform  a  linear scan  for a  possible  matching
    clause using this index key.

  o _H_a_s_h _l_o_o_k_u_p
    If  none of the  above applies, the  system considers the  available
    hash  tables for which  the corresponding argument is  instantiated.
    If  a table is  found with acceptable  characteristics, it is  used.
    Otherwise  it assesses  the clauses for  all instantiated  arguments
    and  selects  the best  candidate  for creating  a new  hash  table.
    If  there is  no single  argument that provides  an acceptable  hash
    quality it will search for a combination of arguments.

    Clauses  that have  a variable  at an  otherwise indexable  argument
    must  be linked into all hash  buckets.  Currently, predicates  that
    have  more than  10% such clauses  for a  specific argument are  not
    considered for indexing on that argument.

    Disregarding  variables, the suitability of an argument  for hashing
    is  expressed as the  number of unique  indexable values divided  by
    the  standard deviation of the  number of duplicate values for  each
    value plus one.

    The  indexes of  dynamic  predicates are  deleted if  the number  of
    clauses  is doubled since its creation or reduced below 1/4th.   The
    JIT  approach  will recreate  a  suitable index  on the  next  call.
    Indexes  of running predicates  cannot be deleted.   They are  added
    to  a `removed index  list' associated to  the predicate.   Outdated
    indexes  of predicates  are reclaimed  by garbage_collect_clauses/0.
    The  clause garbage collector  is scheduled automatically, based  on
    time  and space based heuristics.  See garbage_collect_clauses/0 for
    details.

The library prolog_jiti provides jiti_list/0,1 to list  the characteris-
tics of all or some of the created hash tables.


22..1188..11 FFuuttuurree ddiirreeccttiioonnss

  o The  current  indexing  system  is largely  prepared  for  secondary
    indexes.   This  implies that if there  are many clauses that  match
    a  given  key, the  system  could (JIT)  create a  secondary  index.
    This  secondary index could exploit another argument or, if  the key
    denotes a functor, an argument inside the compound term.

  o The  `special cases' can  be extended.   This is notably  attractive
    for  static predicates  with a  relatively small  number of  clauses
    where a hash lookup is too costly.


22..1188..22 IInnddeexxiinngg aanndd ppoorrttaabbiilliittyy

The base-line functionality of Prolog implementations  provides indexing
on constants and functor (name/arity) on the first argument.   This must
be your  assumption if wide  portability of  your program is  important.
This can typically be  achieved by exploiting term_hash/2 or term_hash/4
and/or  maintaining  multiple  copies  of  a  predicate  with  reordered
arguments and wrappers that update all  implementations (assert/retract)
and selects the appropriate implementation (query).

YAP  provides  full  JIT  indexing,   including  indexing  arguments  of
compound terms.   YAP's indexing has been the inspiration  for enhancing
SWI-Prolog's indexing capabilities.


22..1199 WWiiddee cchhaarraacctteerr ssuuppppoorrtt

SWI-Prolog  supports _w_i_d_e  _c_h_a_r_a_c_t_e_r_s, characters  with character  codes
above  255 that  cannot be  represented in  a single  _b_y_t_e.    _U_n_i_v_e_r_s_a_l
_C_h_a_r_a_c_t_e_r  _S_e_t (UCS)  is the  ISO/IEC 10646  standard  that specifies  a
unique 31-bit unsigned  integer for any character  in any language.   It
is  a superset  of  16-bit  Unicode, which  in  turn  is a  superset  of
ISO  8859-1 (ISO  Latin-1),  a  superset  of US-ASCII.  UCS  can  handle
strings  holding  characters  from  multiple  languages,  and  character
classification (uppercase, lowercase, digit, etc.)   and operations such
as case conversion are unambiguously defined.

For this reason SWI-Prolog has two representations for  atoms and string
objects (see  section ????).    If the  text fits  in ISO  Latin-1, it  is
represented as  an array  of 8-bit characters.    Otherwise the text  is
represented as an array of 32-bit numbers.   This representational issue
is completely  transparent to  the Prolog user.    Users of the  foreign
language  interface as  described in  chapter ????  sometimes  need to  be
aware of these issues though.

Character coding comes into  view when characters of strings need  to be
read from  or written to file  or when they  have to be communicated  to
other software  components using  the foreign  language interface.    In
this section we only deal with I/O through streams,  which includes file
I/O as well as I/O through network sockets.


22..1199..11 WWiiddee cchhaarraacctteerr eennccooddiinnggss oonn ssttrreeaammss

Although  characters   are  uniquely  coded   using  the  UCS   standard
internally, streams  and files are byte  (8-bit) oriented and there  are
a variety of  ways to represent the larger  UCS codes in an 8-bit  octet
stream.   The most popular  one, especially in  the context of the  web,
is UTF-8.   Bytes 0 ... 127 represent simply the  corresponding US-ASCII
character, while bytes 128  ... 255 are used for multi-byte  encoding of
characters placed  higher in the  UCS space.   Especially on  MS-Windows
the 16-bit  Unicode standard,  represented by  pairs of  bytes, is  also
popular.

Prolog I/O streams  have a property called _e_n_c_o_d_i_n_g which  specifies the
used encoding that  influences get_code/2 and put_code/2 as well as  all
the other text I/O predicates.

The  default  encoding  for  files  is  derived  from  the  Prolog  flag
encoding,  which   is  initialised  from  the  environment.      If  the
environment variable  LANG ends  in "UTF-8", this  encoding is  assumed.
Otherwise  the  default   is  text  and  the  translation  is   left  to
the  wide-character functions  of  the C  library.    The  encoding  can
be  specified  explicitly  in load_files/2  for  loading  Prolog  source
with  an  alternative encoding,   open/4 when  opening  files  or  using
set_stream/2  on  any  open  stream.     For  Prolog   source  files  we
also  provide  the encoding/1  directive  that  can be  used  to  switch
between encodings that are compatible with US-ASCII (ascii, iso_latin_1,
utf8  and many  locales).    See  also  section  ???? for  writing  Prolog
files with  non-US-ASCII characters  and section ????  for syntax  issues.
For  additional   information  and  Unicode   resources,  please   visit
http://www.unicode.org/.

SWI-Prolog currently defines and supports the following encodings:

oocctteett
    Default  encoding for binary streams.  This causes the stream  to be
    read and written fully untranslated.

aasscciiii
    7-bit  encoding  in 8-bit  bytes.   Equivalent  to  iso_latin_1,  but
    generates errors and warnings on encountering values above 127.

iissoo__llaattiinn__11
    8-bit  encoding supporting many Western languages.  This  causes the
    stream to be read and written fully untranslated.

tteexxtt
    C  library default locale encoding for  text files.  Files are  read
    and  written using the C library functions mbrtowc()  and wcrtomb().
    This may be the  same as one of the other locales, notably it may be
    the  same as iso_latin_1 for Western languages  and utf8 in a  UTF-8
    context.

uuttff88
    Multi-byte encoding of full UCS, compatible with ascii.  See above.

uunniiccooddee__bbee
    Unicode  _B_i_g  _E_n_d_i_a_n.     Reads  input  in  pairs  of  bytes,   most
    significant byte first.  Can only represent 16-bit characters.

uunniiccooddee__llee
    Unicode  _L_i_t_t_l_e  _E_n_d_i_a_n.    Reads input  in  pairs of  bytes,  least
    significant byte first.  Can only represent 16-bit characters.

Note that not all encodings can represent all characters.   This implies
that  writing text  to a  stream  may cause  errors because  the  stream
cannot represent these characters.   The behaviour of a stream  on these
errors can  be controlled  using set_stream/2.   Initially the  terminal
stream writes the  characters using Prolog escape sequences while  other
streams generate an I/O exception.


22..1199..11..11 BBOOMM:: BByyttee OOrrddeerr MMaarrkk

From  section ????,  you  may  have got  the  impression that  text  files
are  complicated.   This  section  deals with  a related  topic,  making
life  often easier  for the  user, but  providing another  worry to  the
programmer.   BBOOMM or  _B_y_t_e _O_r_d_e_r _M_a_r_k_e_r is  a technique for  identifying
Unicode text files as well  as the encoding they use.  Such  files start
with  the Unicode  character 0xFEFF,  a non-breaking,  zero-width  space
character.   This is a pretty unique  sequence that is not likely to  be
the start of  a non-Unicode file and uniquely distinguishes  the various
Unicode file  formats.   As it is  a zero-width  blank, it even  doesn't
produce any output.  This solves all problems, or ...

Some formats start  off as US-ASCII and  may contain some encoding  mark
to  switch to  UTF-8, such  as the  encoding="UTF-8" in  an XML  header.
Such formats often  explicitly forbid the use  of a UTF-8 BOM. In  other
cases there  is additional  information revealing  the encoding,  making
the use of a BOM redundant or even illegal.

The BOM  is handled by  SWI-Prolog open/4 predicate.   By default,  text
files are  probed for  the BOM when  opened for reading.    If a BOM  is
found, the  encoding is  set accordingly and  the property bom(_t_r_u_e)  is
available through stream_property/2.   When opening a file for  writing,
writing a BOM can be requested using the option bom(_t_r_u_e) with open/4.


22..2200 SSyysstteemm lliimmiittss


22..2200..11 LLiimmiittss oonn mmeemmoorryy aarreeaass

SWI-Prolog has  a number of  memory areas which are  only enlarged to  a
certain  limit.   The  internal data  representation  limits the  local,
global  and  trail  stack to  128  MB  on  32-bit  processors,  or  more
generally  to 2 to the power bits-per-pointer - 5  bytes.    Considering
that almost  all modern  hardware can  deal with this  amount of  memory
with  ease,  the default  limits  are set  to  their maximum  on  32-bit
hardware.   The representation limits can easily exceed  physical memory
on 64-bit hardware.   The default  limits on 64-bit hardware are  double
that of  32-bit hardware, which  allows for storing  the same amount  of
(Prolog) data.

The limits can  be changed from the command  line as well as at  runtime
using set_prolog_stack/2.   The table below shows these areas.  The first
column gives  the option  name to  modify the  size of  the area.    The
option character is  immediately followed by a number and  optionally by
a  k or  m.   With  k or  no unit  indicator, the  value is  interpreted
in Kbytes  (1024 bytes);  with  m, the  value is  interpreted in  Mbytes
(10241* 024 bytes).

The PrologScript facility  described in section ???? provides a  mechanism
for  specifying  options   with  the  load  file.      On  Windows   the
default stack  sizes are controlled  using the  Windows registry on  the
key  HKEY_CURRENT_USER\Software\SWI\Prolog using  the  names  localSize,
globalSize and trailSize.   The value is a DWORD expressing  the default
stack size  in Kbytes.   A  GUI for modifying  these values is  provided
using the XPCE package.  To use this, start the  XPCE manual tools using
manpce/0, after which you find _P_r_e_f_e_r_e_n_c_e_s in the _F_i_l_e menu.

Considering portability,  applications that need  to modify the  default
limits are advised to do so using set_prolog_stack/2.
        _________________________________________________________
        |_Option_|Default_|Area_name____|Description____________|_||-L||128Mlloocc||aallTssttaacckkhe||||local|stack|is used

        |        |                      to  store   the  execu- |              |           ||
        |        |                      tion  environments   of |              |           ||
        |        |                      procedure  invocations. |              |           ||
        |        |                      The  space for  an  en- |              |           ||
        |        |                      vironment is  reclaimed |              |           ||
        |        |                      when  it  fails,  exits |              |           ||
        |        |                      without leaving  choice |              |           ||
        |        |                      points,   the  alterna- |              |           ||
        |        |                      tives are cut  off with |              |           ||
        |        |                                              |              |           ||

        |        |                      the  !/0  predicate  or |              |           ||
        |        |                      no  choice points  have |              |           ||
        |        |                      been created  since the |              |           ||
        |        |                      invocation and the last |              |           ||
        |        |                      subclause  is   started |              |           ||
        |        |                      (last  call   optimisa- |              |           ||
        ||       ||      |             ||tion).                  ||             |           ||

        |   -G   |128M   |gglloobbaall ssttaacckk ||Theusglobaled stacktois store| terms
        |        |       |             ||created during Prolog's |
        |        |       |             ||execution.    Terms  on |
        |        |       |             ||                        |
        |        |       |             ||this stack will  be re- |
        |        |       |             ||claimed by backtracking |
        |        |       |             ||to a  point before  the |
        |        |       |             ||term  was   created  or |
        |        |       |             ||by  garbage  collection |

        |        |       |             ||(provided  the term  is |
        ||       ||      ||            ||no||longer referenced).  ||
        |   -T   |128M   |ttrraaiill ssttaacckk  ||Theusetraild stackto isstore|  as-
        |        |       |             ||signments during execu- |
        |        |       |             ||                        |
        |        |       |             ||tion.   Entries on this |
        |        |       |             ||stack remain  alive un- |

        |        |       |             ||til backtracking before |
        |        |       |             ||the  point of  creation |
        |        |       |             ||or the  garbage collec- |
        |        |       |             ||tor determines they are |
        |________|_______|_____________||no_longer_needed._______|_

                        Table 2.2:  Memory areas


22..2200..11..11 TThhee hheeaapp

With  the heap,  we  refer  to the  memory  area  used by  malloc()  and
friends.  SWI-Prolog uses the area to store  atoms, functors, predicates
and  their clauses,  records and  other dynamic  data.    No limits  are
imposed on the addresses returned by malloc() and friends.


22..2200..22 OOtthheerr LLiimmiittss

CCllaauusseess  The only  limit  on  clauses  is their  arity  (the  number  of
    arguments  to the head),  which is  limited to 1024.   Raising  this
    limit is easy and relatively cheap; removing it is harder.

AAttoommss aanndd SSttrriinnggss  SWI-Prolog has no limits  on the length of atoms  and
    strings.    The  number of  atoms is  limited to  16777216 (16M)  on
    32-bit  machines.  On  64-bit machines this is virtually  unlimited.
    See also section ????.

MMeemmoorryy aarreeaass  On 32-bit hardware, SWI-Prolog data is packed in  a 32-bit
    word,  which contains  both type and  value information.   The  size
    of  the various memory areas  is limited to 128  MB for each of  the
    areas,  except  for the  program heap,  which is  not limited.    On
    64-bit hardware there are no meaningful limits.

NNeessttiinngg ooff tteerrmmss  Most built-in  predicates  that process  Prolog  terms
    create  an explicitly  managed  stack and  perform optimization  for
    processing  the last  argument of  a term.   This  implies they  can
    process  deeply nested  terms at  constant and  low usage  of the  C
    stack,  and the  system raises  a resource  error if  no more  stack
    can  be  allocated.   Currently  only read/1  and  write/1 (and  all
    variations  thereof) still use the C stack and may cause  the system
    to  crash  in an  uncontrolled way  (i.e., not  mapped  to a  Prolog
    exception that can be caught).

IInntteeggeerrss  On  most systems  SWI-Prolog  is  compiled  with  support  for
    unbounded  integers by means  of the GNU GMP  library.  In  practice
    this  means that integers are bound by  the global stack size.   Too
    large  integers cause a resource_error.   On systems that lack  GMP,
    integers are 64-bit on 32- as well as 64-bit machines.

    Integers  up to the value of  the max_tagged_integerProlog  flag are
    represented  more  efficiently on  the  stack.   For  integers  that
    appear  in clauses, the value (below  max_tagged_integeror not)  has
    little impact on the size of the clause.

FFllooaattiinngg ppooiinntt nnuummbbeerrss  Floating  point  numbers   are  represented   as
    C-native double precision floats, 64-bit IEEE on most machines.


22..2200..33 RReesseerrvveedd NNaammeess

The boot compiler  (see -b option) does  not support the module  system.
As large parts of  the system are written in Prolog itself we  need some
way to  avoid name clashes  with the  user's predicates, database  keys,
etc.  Like  Edinburgh C-Prolog [??] all predicates, database  keys, etc.,
that should be hidden from the user start with a dollar ($) sign.


22..2211 SSWWII--PPrroolloogg aanndd 6644--bbiitt mmaacchhiinneess

Most of  today's 64-bit  platforms are  capable of  running both  32-bit
and  64-bit applications.    This asks  for some  clarifications on  the
advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.


22..2211..11 SSuuppppoorrtteedd ppllaattffoorrmmss

SWI-Prolog can  be compiled  for a 32-  or 64-bit  address space on  any
system with a suitable  C compiler.  Pointer arithmetic is based  on the
type (u)intptr_t from stdint.h, with suitable emulation on MS-Windows.


22..2211..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

Most of Prolog's memory usage consists of pointers.   This indicates the
primary drawback:   Prolog memory  usage almost  doubles when using  the
64-bit addressing  model.   Using  more memory means  copying more  data
between CPU and main memory, slowing down the system.

What then  are the advantages?   First  of all, SWI-Prolog's  addressing
of the  Prolog stacks  does not  cover the  whole address  space due  to
the  use of  _t_y_p_e _t_a_g  _b_i_t_s and  _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n  _f_l_a_g_s.   On  32-bit
hardware the stacks  are limited to 128 MB each.   This tends to  be too
low for demanding applications  on modern hardware.  On  64-bit hardware
the limit is 232 times higher, exceeding the  addressing capabilities of
today's CPUs and operating systems.  This implies  Prolog can be started
with stack sizes that use the full capabilities of your hardware.

Multi-threaded applications  profit much more  because every thread  has
its  own  set of  stacks.     The  Prolog stacks  start  small  and  are
dynamically expanded (see section ????).  The C  stack is also dynamically
expanded, but  the maximum size  is _r_e_s_e_r_v_e_d when  a thread is  started.
Using 100 threads  at the maximum default  C stack of 8Mb (Linux)  costs
800Mb virtual memory!

The  implications  of  theoretical performance  loss  due  to  increased
memory  bandwidth implied  by exchanging  wider pointers  depend on  the
design of  the hardware.   We only  have data for  the popular IA32  vs.
AMD64 architectures.  Here, it appears that the  loss is compensated for
by an  instruction set that has  been optimized for modern  programming.
In particular, the AMD64 has more registers and  the relative addressing
capabilities  have been  improved.    Where  we  see a  10%  performance
degradation when placing the SWI-Prolog kernel in a  Unix shared object,
we cannot find a measurable difference on AMD64.


22..2211..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiitt PPrroolloogg

For those  cases where  we can  choose between  32 and  64 bits,  either
because the hardware and OS support both or because  we can still choose
the hardware and OS, we give guidelines for this decision.

First of  all, if SWI-Prolog  needs to be linked  against 32- or  64-bit
native libraries,  there  is no choice  as it  is not  possible to  link
32- and  64-bit code into  a single  executable.   Only if all  required
libraries are available  in both sizes and  there is no clear reason  to
use either do the different characteristics of Prolog become important.

Prolog  applications that  require  more than  the  128 MB  stack  limit
provided in 32-bit  addressing mode must use  the 64-bit edition.   Note
however that the limits  must be doubled to accommodate the  same Prolog
application.

If the system is  tight on physical memory, 32-bit Prolog has  the clear
advantage of using only slightly more than half of  the memory of 64-bit
Prolog.   This argument applies as long  as the application fits in  the
_v_i_r_t_u_a_l _a_d_d_r_e_s_s  _s_p_a_c_e of  the machine.   The  virtual address space  of
32-bit hardware is 4GB, but in many cases the  operating system provides
less to user applications.

The  only  standard  SWI-Prolog library  adding  significantly  to  this
calculation is  the RDF  database provided by  the _s_e_m_w_e_b  package.   It
uses approximately 80 bytes per triple on 32-bit hardware  and 150 bytes
on 64-bit hardware.  Details depend on how  many different resources and
literals appear  in the dataset  as well  as desired additional  literal
indexes.

Summarizing,  if applications  are small  enough to  fit comfortably  in
virtual  and physical  memory, simply  take the  model used  by most  of
the applications  on the OS.  If applications require  more than 128  MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory, fit  in the  128 MB  stack limit  and fit  in
virtual memory, the 32-bit version has clear advantages.   For demanding
applications  on 64-bit  hardware  with  more than  about  6GB  physical
memory the 64-bit model is the model of choice.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

Prolog text-books  give you  an overview of  the Prolog  language.   The
manual tells  you what predicates  are provided in  the system and  what
they do.   This  chapter explains how  to run  a project.   There is  no
ultimate `right'  way to  do this.   Over  the years  we developed  some
practice in  this area and  SWI-Prolog's commands  are there to  support
this practice.   This chapter  describes the conventions and  supporting
commands.

The first two  sections (section ???? and  section ????) only require  plain
Prolog.    The remainder  discusses the  use of  the built-in  graphical
tools that require the XPCE graphical library installed on your system.


33..11 TThhee pprroojjeecctt ssoouurrccee ffiilleess

Organisation  of  source files  depends  largely  on the  size  of  your
project.    If  you  are doing  exercises  for  a Prolog  course  you'll
normally use one  file for each exercise.   If you have a small  project
you'll work with one directory holding a couple of  files and some files
to link  it all together.    Even bigger projects  will be organised  in
sub-projects, each using its own directory.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

The  first  consideration  is what  extension  to  use  for  the  source
files.   Tradition  calls for  .pl, but  conflicts with  Perl force  the
use  of  another  extension on  systems  where  extensions  have  global
meaning,  such as  MS-Windows.    On  such systems  .pro is  the  common
alternative.    On  MS-Windows,  the  alternative  extension  is  stored
in the  registry key HKEY_CURRENT_USER/Software/SWI/Prolog/fileExtension
or HKEY_LOCAL_MACHINE/Software/SWI/Prolog/fileExtension.   All  versions
of  SWI-Prolog  load files  with  the  extension  .pl as  well  as  with
the  registered  alternative  extension  without  explicitly  specifying
the  extension.    For  portability  reasons we  propose  the  following
convention:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  choose .pro and  use this extension  for the files  you
    want  to load  through your file  manager.   Use .pl  for all  other
    files for maximal portability.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

Large projects  are generally composed of  sub-projects, each using  its
own directory or  directory structure.   If nobody else will ever  touch
your files  and you  use only  one computer,  there is  little to  worry
about, but this is rarely the case with a large project.

To   improve   portability,   SWI-Prolog   uses   the   POSIX   notation
for  filenames,   which  uses   the  forward   slash  (/)  to   separate
directories.   Just  before reaching  the file  system, SWI-Prolog  uses
prolog_to_os_filename/2to  convert the filename to the conventions  used
by  the hosting  operating system.    It is  _s_t_r_o_n_g_l_y  advised to  write
paths using the  /, especially on systems  using the \ for this  purpose
(MS-Windows).  Using  \ violates the portability rules and  requires you
to _d_o_u_b_l_e the \ due to the Prolog quoted-atom escape rules.

Portable  code should  use  prolog_to_os_filename/2to  convert  computed
paths  into system  paths  when constructing  commands for  shell/1  and
friends.


33..11..11..33 SSuubb--pprroojjeeccttss uussiinngg sseeaarrcchh ppaatthhss

Thanks to Quintus, Prolog adapted an extensible  mechanism for searching
files using file_search_path/2.   This mechanism allows for  comfortable
and readable specifications.

Suppose  you  have  extensive  library  packages  on  graph  algorithms,
set  operations and  GUI  primitives.    These sub-projects  are  likely
candidates for re-use in future projects.  A good choice  is to create a
directory with sub-directories for each of these sub-projects.

Next,  there are  three options.    One is  to add  the sub-projects  to
the directory  hierarchy of the current  project.   Another is to use  a
completely dislocated  directory.  Third,  the sub-project can be  added
to  the SWI-Prolog  hierarchy.    Using  local installation,  a  typical
file_search_path/2is:

________________________________________________________________________|                                                                        |
|:- prolog_load_context(directory, Dir),                                 |

|   asserta(user:file_search_path(myapp, Dir)).                          |
|                                                                        |
|user:file_search_path(graph, myapp(graph)).                             |
|user:file_search_path(ui,|___myapp(ui))._______________________________ |                         |

When  using sub-projects  in the  SWI-Prolog hierarchy,  one should  use
the path  alias swi as basis.   For  a system-wide installation, use  an
absolute path.

Extensive sub-projects  with a  small well-defined API  should define  a
load  file with  calls to  use_module/1 to  import the  various  library
components and export the API.


33..11..22 PPrroojjeecctt SSppeecciiaall FFiilleess

There are  a number of  tasks you typically carry  out on your  project,
such as  loading it, creating a  saved state, debugging  it, etc.   Good
practice  on large  projects is  to  define small  files that  hold  the
commands to execute such a task, name this file after  the task and give
it a  file extension that  makes starting  easy (see section  ????).   The
task _l_o_a_d  is generally central  to these  tasks.   Here is a  tentative
list:

  o load.pl
    Use  this file  to set  up the  environment (Prolog  flags and  file
    search  paths) and load the sources.  Quite commonly this  file also
    provides  convenient predicates  to parse command  line options  and
    start the application.

  o run.pl
    Use  this file to start the application.  Normally it  loads load.pl
    in  silent-mode,  and  calls one  of  the starting  predicates  from
    load.pl.

  o save.pl
    Use this file to  create a saved state of the application by loading
    load.pl  and calling qsave_program/2 to generate a saved  state with
    the proper options.

  o debug.pl
    Loads  the program for  debugging.   In addition to loading  load.pl
    this  file defines rules for portray/1 to modify printing  rules for
    complex  terms and customisation rules for the debugger  and editing
    environment.  It may start some of these tools.


33..11..33 IInntteerrnnaattiioonnaall ssoouurrccee ffiilleess

As discussed in section ????, SWI-Prolog  supports international character
handling.    Its  internal  encoding  is UNICODE.  I/O  streams  convert
to/from this internal  format.  This  section discusses the options  for
source files not in US-ASCII.

SWI-Prolog  can  read  files  in  any  of  the  encodings  described  in
section  ????.   Two  encodings  are of  particular interest.    The  text
encoding  deals with  the  current  _l_o_c_a_l_e,  the default  used  by  this
computer for  representing text files.   The encodings  utf8, unicode_le
and unicode_be are _U_N_I_C_O_D_E encodings:  they can represent---in  the same
file---characters of  virtually any known language.   In addition,  they
do so unambiguously.

If one wants to represent non US-ASCII text as Prolog  terms in a source
file, there are several options:

  o _U_s_e _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s
    This approach describes  NON-ASCII as sequences of the form \_o_c_t_a_l\.
    The  numerical argument is interpreted as a UNICODE character.   The
    resulting  Prolog file is  strict 7-bit US-ASCII,  but if there  are
    many NON-ASCII characters it becomes very unreadable.

  o _U_s_e _l_o_c_a_l _c_o_n_v_e_n_t_i_o_n_s
    Alternatively  the file  may be specified  using local  conventions,
    such  as the EUC  encoding for Japanese text.   The disadvantage  is
    portability.  If  the file is moved to another machine, this machine
    must  use the same _l_o_c_a_l_e  or the file is  unreadable.  There is  no
    elegant  way if files  from multiple locales  must be united in  one
    application  using this technique.   In other words, it is  fine for
    local projects in countries with uniform locale conventions.

  o _U_s_i_n_g _U_T_F_-_8 _f_i_l_e_s
    The best way  to specify source files with many NON-ASCII characters
    is  definitely the use  of UTF-8 encoding.   Prolog can be  notified
    of  this encoding in two  ways, using a  UTF-8 _B_O_M (see section  ????)
    or  using  the directive  :- encoding(utf8).  Many of  today's  text
    editors,  including PceEmacs,  are capable  of editing UTF-8  files.
    Projects  that were started using local conventions can  be re-coded
    using  the Unix iconv  tool or often  using commands offered by  the
    editor.


33..22 UUssiinngg mmoodduulleess

Modules have  been debated fiercely  in the Prolog world.   Despite  all
counter-arguments we feel they are extremely useful because:

  o _T_h_e_y _h_i_d_e _l_o_c_a_l _p_r_e_d_i_c_a_t_e_s
    This  is the reason they were invented  in the first place.   Hiding
    provides  two  features.    They  allow  for short  predicate  names
    without  worrying  about  conflicts.    Given  the  flat  name-space
    introduced  by modules, they  still require meaningful module  names
    as well as meaningful names for exported predicates.

  o _T_h_e_y _d_o_c_u_m_e_n_t _t_h_e _i_n_t_e_r_f_a_c_e
    Possibly  more important than avoiding name conflicts is  their role
    in  documenting  which part  of the  file is  for  public usage  and
    which  is  private.    When  editing a  module  you may  assume  you
    can  reorganise anything except  the name and  the semantics of  the
    exported predicates without worrying.

  o _T_h_e_y _h_e_l_p _t_h_e _e_d_i_t_o_r
    The  PceEmacs built-in editor  does on-the-fly cross-referencing  of
    the  current module, colouring predicates based on their  origin and
    usage.    Using modules,  the editor  can quickly find  out what  is
    provided  by the imported  modules by reading  just the first  term.
    This  allows it to  indicate in real-time  which predicates are  not
    used or not defined.

Using modules  is generally  easy.   Only if  you write  meta-predicates
(predicates reasoning about  other predicates) that are exported from  a
module is a  good understanding required of  the resolution of terms  to
predicates inside a module.  Here is a typical example from readutil.

________________________________________________________________________|                                                                        |

|:- module(read_util,                                                    |
|          [ read_line_to_codes/2,       % +Fd, -Codes                   |
|            read_line_to_codes/3,       % +Fd, -Codes, ?Tail            |
|            read_stream_to_codes/2,     % +Fd, -Codes                   |
|            read_stream_to_codes/3,     % +Fd, -Codes, ?Tail            |

|            read_file_to_codes/3,       % +File, -Codes, +Options       |
|            read_file_to_terms/3        % +File, -Terms, +Options       |
||_________]).__________________________________________________________ ||


33..33 TThhee tteesstt--eeddiitt--rreellooaadd ccyyccllee

SWI-Prolog  does  not  enforce  the  use  of  a  particular  editor  for
writing  Prolog source  code.   Editors  are  complicated programs  that
must  be  mastered in  detail  for  real  productive programming.     If
you  are familiar  with  a specific  editor  you  should not  be  forced
to change.    You may  specify your  favourite editor  using the  Prolog
flag editor,  the environment variable EDITOR  or by defining rules  for
prolog_edit:edit_source/1.

The use of  a built-in editor, which  is selected by setting the  Prolog
flag  editor to  pce_emacs,  has  advantages.   The  XPCE _e_d_i_t_o_r  object,
around which the built-in  PceEmacs is built, can be opened as  a Prolog
stream allowing analysis of your source by the real Prolog system.


33..33..11 LLooccaattiinngg tthhiinnggss ttoo eeddiitt

The central  predicate for  editing something is  edit/1, an  extensible
front-end  that searches  for objects  (files, predicates,  modules,  as
well as XPCE classes  and methods) in the Prolog database.   If multiple
matches are  found it  provides a choice.    Together with the  built-in
completion on atoms  bound to the TAB key  this provides a quick way  to
edit objects:

________________________________________________________________________|                                                                        |
|?- edit(country).                                                       |

|Please select item to edit:                                             |
|                                                                        |
|  1 chat:country/10      '/staff/jan/lib/prolog/chat/countr.pl':16      |
|  2 chat:country/1       '/staff/jan/lib/prolog/chat/world0.pl':72      |
|                                                                        |
|Your|choice?___________________________________________________________ |    |


33..33..22 EEddiittiinngg aanndd iinnccrreemmeennttaall ccoommppiillaattiioonn

One of  the nice features  of Prolog  is that the  code can be  modified
while  the program  is running.    Using  pure Prolog  you  can trace  a
program,  find it  is misbehaving,  enter  a _b_r_e_a_k  _e_n_v_i_r_o_n_m_e_n_t,  modify
the  source code,  reload it  and finally  do _r_e_t_r_y  on the  misbehaving
predicate  and  try  again.      This  sequence  is  not   uncommon  for
long-running programs.    For faster  programs one  will normally  abort
after understanding  the misbehaviour,  edit the source,  reload it  and
try again.

One of the nice features of SWI-Prolog is the  availability of make/0, a
simple predicate that checks  all loaded source files to see  which ones
you have modified.  It then reloads these  files, considering the module
from which  the file  was loaded  originally.   This greatly  simplifies
the trace-edit-verify development cycle.  For example,  after the tracer
reveals there is something wrong with prove/3, you do:

________________________________________________________________________|                                                                        |
|?-|edit(prove).________________________________________________________ |  |

Now  edit the  source,  possibly switching  to  other files  and  making
multiple changes.   After finishing,  invoke make/0, either through  the
editor UI (Compile/Make (Control-C Control-M)) or on the  top level, and
watch the files being reloaded.

________________________________________________________________________|                                                                        |

|?- make.                                                                |
|%|show_compiled_into_photo_gallery_0.03_sec,_3,360_bytes_______________ | |


33..44 UUssiinngg tthhee PPcceeEEmmaaccss bbuuiilltt--iinn eeddiittoorr


33..44..11 AAccttiivvaattiinngg PPcceeEEmmaaccss

Initially edit/1  uses the  editor specified in  the EDITOR  environment
variable.   There are two ways to  force it to use the built-in  editor.
One is to  set the Prolog flag editor  to pce_emacs and the other is  by
starting the editor explicitly using the emacs/[0,1] predicates.


33..44..22 BBlluuffffiinngg tthhrroouugghh PPcceeEEmmaaccss

PceEmacs closely  mimics Richard Stallman's  GNU-Emacs commands,  adding
features from  modern window-based  editors to make  it more  acceptable
for beginners.

At the  basis, PceEmacs  maps keyboard sequences  to methods defined  on
the extended  _e_d_i_t_o_r object.   Some frequently  used commands are,  with
their key-binding, presented  in the menu bar above each  editor window.
A complete  overview of the  bindings for the  current _m_o_d_e is  provided
through Help/Show key bindings (Control-h Control-b).


33..44..22..11 EEddiitt mmooddeess

Modes  are the  heart of  (Pce)Emacs.   Modes  define dedicated  editing
support for  a particular kind  of (source)  text.   For our purpose  we
want _P_r_o_l_o_g _m_o_d_e.   There are various  ways to make PceEmacs use  Prolog
mode for a file.

  o _U_s_i_n_g _t_h_e _p_r_o_p_e_r _e_x_t_e_n_s_i_o_n
    If  the file  ends in .pl  or the  selected alternative (e.g.  .pro)
    extension, Prolog mode is selected.

  o _U_s_i_n_g #!/path/to/.../swipl
    If  the  file  is a  _P_r_o_l_o_g  _S_c_r_i_p_t  file, starting  with  the  line
    #!/path/to/swipl _o_p_t_i_o_n_s, Prolog  mode is selected regardless of the
    extension.

  o _U_s_i_n_g -*- Prolog -*-
    If the above sequence  appears in the first line of the file (inside
    a Prolog comment) Prolog mode is selected.

  o _E_x_p_l_i_c_i_t _s_e_l_e_c_t_i_o_n
    Finally,  using  File/Mode/Prolog  you  can switch  to  Prolog  mode
    explicitly.


33..44..22..22 FFrreeqquueennttllyy uusseedd eeddiittoorr ccoommmmaannddss

Below we list a few important commands and how to activate them.

  o _C_u_t_/_C_o_p_y_/_P_a_s_t_e
    These  commands  follow Unix/X11  traditions.    You're best  suited
    with  a three-button mouse.   After  selecting using the  left-mouse
    (double-click  uses word-mode  and triple  line-mode), the  selected
    text   is  _a_u_t_o_m_a_t_i_c_a_l_l_y  copied  to  the  clipboard   (X11  primary
    selection  on  Unix).   _C_u_t  is achieved  using the  DEL  key or  by
    typing something else at  the location.  _P_a_s_t_e is achieved using the
    middle-mouse  (or wheel) button.   If you don't have a  middle-mouse
    button,  pressing the  left- and  right-button at the  same time  is
    interpreted  as a middle-button click.   If nothing helps, there  is
    the Edit/Paste menu entry.  Text is pasted at the caret location.

  o _U_n_d_o
    Undo  is bound to the GNU-Emacs Control-_ as well as  the MS-Windows
    Control-Z sequence.

  o _A_b_o_r_t
    Multi-key sequences can be aborted at any stage using Control-G.

  o _F_i_n_d
    Find  (Search) is  started  using Control-S  (forward) or  Control-R
    (backward).    PceEmacs  implements  _i_n_c_r_e_m_e_n_t_a_l _s_e_a_r_c_h.    This  is
    difficult  to use for  novices, but very  powerful once you get  the
    clue.    After one  of the above  start keys,  the system  indicates
    search  mode in  the status  line.   As  you are  typing the  search
    string, the system  searches for it, extending the search with every
    character you type.   It illustrates the current match using a green
    background.

    If  the target  cannot be found,  PceEmacs warns  you and no  longer
    extends  the search  string.   During search,  some characters  have
    special  meaning.  Typing anything but these characters  commits the
    search, re-starting normal edit mode.  Special commands are:

    Control-S
         Search forwards for next.

    Control-R
         Search backwards for next.

    Control-W
         Extend search to next word boundary.

    Control-G
         Cancel search, go back to where it started.

    ESC
         Commit search, leaving caret at found location.

    Backspace
         Remove a character from the search string.

  o _D_y_n_a_m_i_c _A_b_b_r_e_v_i_a_t_i_o_n
    Also  called _d_a_b_b_r_e_v, dynamic  abbreviation is an important  feature
    of Emacs clones to  support programming.  After typing the first few
    letters  of an identifier, you may press Alt-/, causing  PceEmacs to
    search  backwards for  identifiers that  start the same  and use  it
    to  complete the text  you typed.   A second Alt-/ searches  further
    backwards.    If  there are  no  hits before  the caret,  it  starts
    searching  forwards.   With  some practice, this  system allows  for
    entering  code  very fast  with nice  and  readable identifiers  (or
    other difficult long words).

  o _O_p_e_n _(_a _f_i_l_e_)
    Is  called File/Find  file (Control-x Control-f).    By default  the
    file  is loaded into the current window.   If you want to  keep this
    window,  press Alt-s or click the little icon at the bottom  left to
    make the window _s_t_i_c_k_y.

  o _S_p_l_i_t _v_i_e_w
    Sometimes  you want to look at two places  in the same file.   To do
    this,  use Control-x 2 to create  a new window pointing to  the same
    file.   Do not worry, you  can edit as well as move around  in both.
    Control-x 1 kills all other windows running on the same file.

These are  the most commonly used  commands.   In section ???? we  discuss
specific support for dealing with Prolog source code.


33..44..33 PPrroolloogg MMooddee

In  the  previous  section (section  ????)  we  explained  the  basics  of
PceEmacs.     Here  we  continue   with  Prolog-specific  functionality.
Possibly  the most  interesting is  _S_y_n_t_a_x _h_i_g_h_l_i_g_h_t_i_n_g.    Unlike  most
editors  where  this  is  based  on  simple  patterns,  PceEmacs  syntax
highlighting  is  achieved   by  Prolog  itself  actually  reading   and
interpreting the  source as you  type it.   There  are three moments  at
which PceEmacs checks (part of) the syntax.

  o _A_f_t_e_r _t_y_p_i_n_g _a .
    After  typing a . that  is not preceded  by a _s_y_m_b_o_l character,  the
    system  assumes you completed a clause,  tries to find the start  of
    this  clause and verifies the syntax.   If this process succeeds  it
    colours  the elements  of the  clause according to  the rules  given
    below.    Colouring is  done using  information from  the last  full
    check  on this file.  If it fails, the syntax error  is displayed in
    the status line and the clause is not coloured.

  o _A_f_t_e_r _t_h_e _c_o_m_m_a_n_d Control-c Control-s
    Acronym  for CCheck SSyntax, it performs the same checks as  above for
    the  clause surrounding the caret.  On a syntax error,  however, the
    caret is moved to the expected location of the error.

  o _A_f_t_e_r _p_a_u_s_i_n_g _f_o_r _t_w_o _s_e_c_o_n_d_s
    After  a short  pause (2  seconds), PceEmacs opens  the edit  buffer
    and  reads it  as a  whole, creating  an index  of defined,  called,
    dynamic,  imported and exported predicates.  After  completing this,
    it  re-reads the file and colours  all clauses and calls with  valid
    syntax.

  o _A_f_t_e_r _t_y_p_i_n_g Control-l Control-l
    The  Control-l command re-centers the window (scrolls the  window to
    make  the caret  the center  of the window).    Typing this  command
    twice starts the same process as above.

TThhee ccoolloouurr sscchheemmaa

itself  is  defined  in  emacs/prolog_colour.     The  colouring  can  be
extended and  modified using multifile  predicates.   Please check  this
source file for  details.  In  general, underlined objects have a  popup
(right-mouse button)  associated with  common commands  such as  viewing
the  documentation or  source.    BBoolldd  text  is  used to  indicate  the
definition of  objects (typically predicates  when using plain  Prolog).
Other colours follow intuitive conventions.  See table ????.
          _____________________________________________________
          |______________________Clauses_______________________|
          | Blue bold  |Head of an exported predicate          |
          | Red bold   |Head of a predicate that is not called |

          |_Black_bold_|Head_of_remaining_predicates___________|
          |______________Calls_in_the_clause_body______________|
          | Blue       |Call to built-in or imported predicate |
          | Red        |Call to undefined predicate            |
          |_Purple_____|Call_to_dynamic_predicate______________|
          |___________________Other_entities___________________|

          | Dark green |Comment                                |
          | Dark blue  |Quoted atom or string                  |
          |_Brown______|Variable_______________________________|

                     Table 3.1:  Colour conventions

LLaayyoouutt ssuuppppoorrtt Layout  is not `just nice',  it is _e_s_s_e_n_t_i_a_l for  writing
readable code.   There is  much debate on  the proper layout of  Prolog.
PceEmacs, being  a rather  small project,  supports only one  particular
style for layout.  Below are examples of typical constructs.

________________________________________________________________________|                                                                        |
|head(arg1, arg2).                                                       |

|                                                                        |
|head(arg1, arg2) :- !.                                                  |
|                                                                        |
|head(Arg1, arg2) :- !,                                                  |
|        call1(Arg1).                                                    |
|                                                                        |
|head(Arg1, arg2) :-                                                     |

|        (   if(Arg1)                                                    |
|        ->  then                                                        |
|        ;   else                                                        |
|        ).                                                              |
|                                                                        |
|head(Arg1) :-                                                           |
|        (   a                                                           |
|        ;   b                                                           |

|        ).                                                              |
|                                                                        |
|head :-                                                                 |
|        a(many,                                                         |
|          long,                                                         |
|          arguments(with,                                               |
|                    many,                                               |

|                    more),                                              |
|          and([ a,                                                      |
|                long,                                                   |
|                list,                                                   |
|                with,                                                   |
|                a,                                                      |
|              | tail                                                    |
||_____________]))._____________________________________________________ ||

PceEmacs uses the  same conventions as GNU-Emacs.   The TAB key  indents
the current  line according  to the  syntax rules.    Alt-q indents  all
lines  of the  current clause.    It provides  support for  head,  calls
(indented 1  tab), if-then-else, disjunction  and argument lists  broken
across multiple lines as illustrated above.


33..44..33..11 FFiinnddiinngg yyoouurr wwaayy aarroouunndd

The command Alt-.   extracts name and arity from the caret  location and
jumps (after conformation  or edit) to the definition of  the predicate.
It does  so based on the  source-location database of loaded  predicates
also used  by edit/1.   This makes locating  predicates reliable if  all
sources are loaded and up-to-date (see make/0).

In addition,  references to files  in use_module/[1,2], consult/1,  etc.
are red if the file cannot be found and underlined blue  if the file can
be loaded.  A popup allows for opening the referenced file.


33..55 TThhee GGrraapphhiiccaall DDeebbuuggggeerr

SWI-Prolog  offers  two  debuggers.     One  is   the  traditional  text
console-based  4-port Prolog  tracer  and the  other is  a  window-based
source  level  debugger.     The  window-based  debugger  requires  XPCE
installed.   It operates  based on  the prolog_trace_interception/4 hook
and other low-level functionality described in chapter ????.

Window-based tracing provides a much better overview due  to the eminent
relation to your source code, a clear list of  named variables and their
bindings as well  as a graphical overview  of the call and choice  point
stack.  There are  some drawbacks though.  Using a textual trace  on the
console, one can scroll  back and examine the past, while  the graphical
debugger just presents a (much better) overview of the current state.


33..55..11 IInnvvookkiinngg tthhee wwiinnddooww--bbaasseedd ddeebbuuggggeerr

Whether the  text-based or window-based debugger  is used is  controlled
using  the predicates  guitracer/0 and  noguitracer/0.   Entering  debug
mode  is controlled  using  the normal  predicates  for this:    trace/0
and  spy/1.   In  addition, PceEmacs  prolog mode  provides the  command
Prolog/Break  at (Control-c b)  to insert  a break-point  at a  specific
location in the source code.

The graphical tracer is  particulary useful for debugging threads.   The
tracer must be loaded from the main thread before it can  be used from a
background thread.


gguuiittrraacceerr
    This  predicate  installs the  above-mentioned hooks  that  redirect
    tracing  to  the  window-based  environment.    No  window  appears.
    The  debugger window  appears as actual  tracing is started  through
    trace/0,  by hitting a spy point  defined by spy/1 or a  break point
    defined using the PceEmacs command Prolog/Break at (Control-c b).


nnoogguuiittrraacceerr
    Disable  the hooks  installed by  guitracer/0,  reverting to  normal
    text console-based tracing.


ggttrraaccee
    Utility defined as guitracer,trace.


ggddeebbuugg
    Utility defined as guitracer,debug.


ggssppyy((_+_P_r_e_d_i_c_a_t_e))
    Utility defined as guitracer,spy(Predicate).


33..66 TThhee PPrroolloogg NNaavviiggaattoorr

Another  tool is  the  _P_r_o_l_o_g  _N_a_v_i_g_a_t_o_r.    This  tool can  be  started
from  PceEmacs  using the  command  Browse/Prolog  navigator,  from  the
GUI  debugger or  using  the  programmatic IDE  interface  described  in
section ????.


33..77 CCrroossss--rreeffeerreenncceerr

A cross-referencer  is a tool that  examines the caller-callee  relation
between predicates, and, using this information  to explicate dependency
relations between source  files, finds calls to non-existing  predicates
and predicates  for which no  callers can be  found.   Cross-referencing
is useful during program development, reorganisation,  clean-up, porting
and  other program  maintenance tasks.    The dynamic  nature of  Prolog
makes the  task non-trivial.    Goals can be  created dynamically  using
call/1  after construction  of a  goal term.    Abstract  interpretation
can find  some of  these calls,  but they  can also  come from  external
communication,  making  it  impossible  to  predict  the  callee.     In
other  words, the  cross-referencer has  only  partial understanding  of
the program,  and its  results are  necessarily incomplete.   Still,  it
provides valuable information to the developer.

SWI-Prolog's cross-referencer  is split into  two parts.   The  standard
Prolog  library prolog_xref  is an  extensible library  for  information
gathering  described  in  section ????,   and the  XPCE  library  pce_xref
provides a graphical front-end for the  cross-referencer described here.
We  demonstrate the  tool on  CHAT80, a  natural  language question  and
answer system by Fernando C.N. Pereira and David H.D. Warren.


ggxxrreeff
    Run  cross-referencer on  all currently loaded  files and present  a
    graphical  overview of  the result.   As  the predicate operates  on
    the  currently loaded application it  must be run after loading  the
    application.

The lleefftt wwiinnddooww (see  figure ????) provides browsers for loaded  files and
predicates.   To  avoid long file  paths, the  file hierarchy has  three
main branches.  The first is the current  directory holding the sources.
The  second is  marked  alias, and  below  it are  the  file-search-path
aliases  (see file_search_path/2 and  absolute_file_name/3).    Here  you
find files  loaded from  the system as  well as  modules of the  program
loaded from  other locations  using the file  search path.   All  loaded
files  that fall  outside these  categories are  below  the last  branch
called /.    Files where  the system found  suspicious dependencies  are
marked  with an  exclamation mark.    This  also holds  for  directories
holding such files.  Clicking on a file opens a  _F_i_l_e _i_n_f_o window in the
right pane.

The FFiillee iinnffoo  window shows a file,  its main properties, its  undefined
and not-called predicates  and its import and export relations  to other
files  in the  project.   Both  predicates and  files can  be opened  by
clicking  on them.    The number  of callers  in a  file  for a  certain
predicate is  indicated with  a blue  underlined number.   A  left-click
will open a list and allow editing the calling predicate.

The DDeeppeennddeenncciieess  (see figure ????) window  displays a graphical  overview
of dependencies  between files.   Using the  background menu a  complete
graph of the project can be created.  It is  also possible to drag files
onto the  graph window and  use the menu on  the nodes to  incrementally
expand the  graph.   The underlined  blue text  indicates the number  of
predicates used in the destination file.  Left-clicking  opens a menu to
open the definition or select one of the callers.

MMoodduullee  aanndd nnoonn--mmoodduullee  ffiilleess The  cross-referencer threads  module  and
non-module  project files  differently.    Module  files  have  explicit
import  and  export   relations  and  the  tool  shows  the   usage  and
consistency of the relations.   Using the Header menu command,  the tool
creates a  consistent import list  for the module  that can be  included
in the  file.   The tool computes the  dependency relations between  the
non-module files.   If  the user  wishes to convert  the project into  a
module-based one,  the Header  command generates  an appropriate  module
header and import list.  Note that the  cross-referencer may have missed
dependencies  and does  not  deal with  meta-predicates defined  in  one
module and called in another.  Such problems must be resolved manually.

SSeettttiinnggss The  following settings  can be  controlled  from the  settings
menu:

WWaarrnn aauuttoollooaadd
    By  default disabled.   If enabled, modules that require  predicates
    to  be  autoloaded are  flagged with  a warning  and  the file  info
    window of a module shows the required autoload predicates.

WWaarrnn nnoott ccaalllleedd
    If  enabled (default),  the file  overview shows an  alert icon  for
    files that have predicates that are not called.


33..88 AAcccceessssiinngg tthhee IIDDEE ffrroomm yyoouurr pprrooggrraamm

Over the years a collection of IDE components have  been developed, each
with its own interface.   In addition, some of these  components require
each  other, and  loading  IDE components  must be  on demand  to  avoid
the IDE  being part of  a saved state (see  qsave_program/2).   For  this
reason, access to the  IDE is concentrated on a single  interface called
prolog_ide/1:


pprroolloogg__iiddee((_+_A_c_t_i_o_n))
    This  predicate ensures the  IDE-enabling XPCE component is  loaded,
    creates  the XPCE class _p_r_o_l_o_g___i_d_e and sends  _A_c_t_i_o_n to its one  and
    only instance @prolog_ide.  _A_c_t_i_o_n is one of the following:

    ooppeenn__nnaavviiggaattoorr((_+_D_i_r_e_c_t_o_r_y))
         Open  the  Prolog Navigator  (see  section  ????)  in  the  given
         _D_i_r_e_c_t_o_r_y.

    ooppeenn__ddeebbuugg__ssttaattuuss
         Open a window to edit spy and trace points.

    ooppeenn__qquueerryy__wwiinnddooww
         Open  a  little  window  to  run  Prolog  queries  from  a  GUI
         component.

    tthhrreeaadd__mmoonniittoorr
         Open a graphical  window indicating existing threads and  their
         status.

    ddeebbuugg__mmoonniittoorr
         Open a graphical front-end for the debug  library that provides
         an overview of the topics and catches messages.

    xxrreeff
         Open  a  graphical  front-end  for  the  cross-referencer  that
         provides an overview of predicates and their callers.


33..99 SSuummmmaarryy ooff tthhee IIDDEE

The  SWI-Prolog  development   environment  consists  of  a  number   of
interrelated but  not (yet) integrated  tools.   Here is  a list of  the
most important features and tips.

  o _A_t_o_m _c_o_m_p_l_e_t_i_o_n
    The  console  completes a  partial atom  on the  TAB  key and  shows
    alternatives on the command Alt-?.

  o _U_s_e edit/1 _f_o_r _f_i_n_d_i_n_g _l_o_c_a_t_i_o_n_s
    The  command edit/1 takes the name  of a file, module, predicate  or
    other  entity registered  through extensions and  starts the  user's
    preferred editor at the right location.

  o _S_e_l_e_c_t _e_d_i_t_o_r
    External   editors  are  selected   using  the  EDITOR   environment
    variable,  by setting  the Prolog  flag editor, or  by defining  the
    hook qpredrefprolog_editedit_source1.

  o _U_p_d_a_t_e _P_r_o_l_o_g _a_f_t_e_r _e_d_i_t_i_n_g
    Using make/0, all files you have edited are re-loaded.

  o _P_c_e_E_m_a_c_s
    Offers  syntax highlighting and checking based on  real-time parsing
    of the editor's buffer, layout support and navigation support.

  o _U_s_i_n_g _t_h_e _g_r_a_p_h_i_c_a_l _d_e_b_u_g_g_e_r
    The   predicates  guitracer/0   and  noguitracer/0  switch   between
    traditional  text-based and window-based debugging.   The tracer  is
    activated  using the trace/0, spy/1  or menu items from PceEmacs  or
    the Prolog Navigator.

  o _T_h_e _P_r_o_l_o_g _N_a_v_i_g_a_t_o_r
    Shows  the file structure and structure inside the file.   It allows
    for loading files, editing, setting spy points, etc.


CChhaapptteerr 44..  BBUUIILLTT--IINN PPRREEDDIICCAATTEESS


44..11 NNoottaattiioonn ooff PPrreeddiiccaattee DDeessccrriippttiioonnss

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:

        _________________________________________________________++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
             _g_r_o_u_n_d, e.g., the term [_] is a _l_i_s_t, although its

             only member is unbound.
         -   Argument  is   an   _o_u_t_p_u_t  argument.       Unless
             specified  otherwise,  output arguments  need  not
             to  be   unbound.       For  example,   the   goal
             findall(X, Goal, [T]) is good style and equivalent
             to  findall(X, Goal, Xs), Xs = [T] Note  that  the
             _d_e_t_e_r_m_i_n_i_s_m  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 open/3 which
             creates a _s_t_r_e_a_m.
         ?   Argument  must   be  bound   to  a  _p_a_r_t_i_a_l   _t_e_r_m
             of   the   indicated  type.        Note   that   a
             variable  is   a  partial   term  for  any   type.

             Think  of   the  argument   as  either  _i_n_p_u_t   or
             _o_u_t_p_u_t  or   _b_o_t_h   input  and   output.       For
             example,  in stream_property(S, reposition(Bool)),
             the reposition part of  the term is input  and the
             uninstantiated _B_o_o_l is output.
         :   Argument  is   a  meta-argument.      Implies   +.
             See chapter  ????  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_setarg/3_or_nb_setarg/3._____________

Referring  to a  predicate in  running text  is done  using a  _p_r_e_d_i_c_a_t_e
_i_n_d_i_c_a_t_o_r.     The  canonical and  most  generic  form  of  a  predicate
indicator is a term <_m_o_d_u_l_e>:<_n_a_m_e>/<_a_r_i_t_y>.  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  section ????),
SWI-Prolog  also  allows for  [<_m_o_d_u_l_e>]:<_n_a_m_e>//<_a_r_i_t_y>  to  refer  to  a
grammar  rule.    For  all  non-negative arity,  <_n_a_m_e>//<_a_r_i_t_y>  is  the
same as  <_n_a_m_e>/<_a_r_i_t_y>+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, spy/1, and dynamic/1.


44..22 CChhaarraacctteerr rreepprreesseennttaattiioonn

In  traditional (Edinburgh)  Prolog,  characters are  represented  using
_c_h_a_r_a_c_t_e_r _c_o_d_e_s.   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 open/4).  These types are:

  o _c_o_d_e
    A  _c_h_a_r_a_c_t_e_r _c_o_d_e  is an  integer representing  a single  character.
    As  files  may  use  multi-byte encoding  for  supporting  different
    character  sets (utf-8 encoding for example), reading a code  from a
    text file is in general not the same as reading a byte.

  o _c_h_a_r
    Alternatively,   characters  may  be  represented  as  _o_n_e_-_c_h_a_r_a_c_t_e_r
    _a_t_o_m_s.   This is a natural representation, hiding  encoding problems
    from the programmer as well as providing much easier debugging.

  o _b_y_t_e
    Bytes are used for accessing binary streams.

In SWI-Prolog, character codes are _a_l_w_a_y_s the Unicode  equivalent of the
encoding.  That is, if get_code/1 reads from a stream  encoded as KOI8-R
(used for the  Cyrillic alphabet), it returns the  corresponding Unicode
code  points.    Similarly,  assembling  or  disassembling  atoms  using
atom_codes/2 interprets the  codes as  Unicode points.   See section  ????
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 a.

________________________________________________________________________|                                                                        |

|peek_code(Stream, a).                                                   |
|peek_code(Stream,|97)._________________________________________________ |                 |

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  char_code/2.     For  breaking
atoms and numbers into  characters there are atom_chars/2, atom_codes/2,
number_chars/2 and number_codes/2.   For character I/O on streams  there
are  get_char/[1,2],  get_code/[1,2],  get_byte/[1,2],  peek_char/[1,2],
peek_code/[1,2],  peek_byte/[1,2],  put_code/[1,2],  put_char/[1,2]  and
put_byte/[1,2].  The Prolog flag double_quotes controls how text between
double quotes is interpreted.


44..33 LLooaaddiinngg PPrroolloogg ssoouurrccee ffiilleess

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:

 AA ttrraaddiittiioonnaall   Prolog  source   file  contains   Prolog  clauses   and
    directives,  but no  _m_o_d_u_l_e _d_e_c_l_a_r_a_t_i_o_n  (see module/1).   They  are
    normally  loaded using consult/1  or ensure_loaded/1.  Currently,  a
    non-module file can only be loaded into a single module.

 AA mmoodduullee   Prolog source file  starts with a module  declaration.   The
    subsequent  Prolog code  is loaded  into the  specified module,  and
    only  the  _e_x_p_o_r_t_e_d predicates  are made  available  to the  context
    loading  the  module.     Module  files  are  normally  loaded  with
    use_module/[1,2].  See chapter ???? for details.

 AAnn iinncclluuddee   Prolog  source  file   is  loaded   using  the   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 _d_e_c_l_a_r_a_t_i_o_n_s  such as multifile or  dynamic
    between source files.

Prolog  source files  are  located using  absolute_file_name/3 with  the
following options:

________________________________________________________________________|                                                                        |

|locate_prolog_file(Spec, Path) :-                                       |
|        absolute_file_name(Spec,                                        |
|                           [ file_type(prolog),                         |
|                             access(read)                               |
|                           ],                                           |

||__________________________Path).______________________________________ ||

The file_type(_p_r_o_l_o_g) option is  used to determine the extension of  the
file using  prolog_file_type/2.    The default extension  is .pl.    _S_p_e_c
allows  for the  _p_a_t_h _a_l_i_a_s  construct defined  by absolute_file_name/3.
The most commonly used path alias is library(_L_i_b_r_a_r_y_F_i_l_e).   The example
below  loads the  library  file  ordsets.pl (containing  predicates  for
manipulating ordered sets).

________________________________________________________________________|                                                                        |
|:-|use_module(library(ordsets))._______________________________________ |  |

SWI-Prolog  recognises grammar  rules (DCG)  as  defined in  [??].    The
user may  define additional compilation of  the source file by  defining
the  dynamic  multifile predicates  term_expansion/2,  term_expansion/4,
goal_expansion/2  and goal_expansion/4.     It is  not  allowed  to  use
assert/1, retract/1 or any other  database predicate in term_expansion/2
other  than  for  local  computational  purposes.      Code  that  needs
to  create  additional clauses  must  use  compile_aux_clauses/1.     See
library(apply_macros) for an example.

A  _d_i_r_e_c_t_i_v_e  is  an  instruction to  the  compiler.     Directives  are
used to  set (predicate)  properties (see  section ????),  set flags  (see
set_prolog_flag/2)  and load files (this section).  Directives  are terms
of the form :- <_t_e_r_m>..  Here are some examples:

________________________________________________________________________|                                                                        |
|:- use_module(library(lists)).                                          |
|:- dynamic                                                              |

||_______store/2.________________%_Name,_Value__________________________ ||

The  directive initialization/1  can  be used  to run  arbitrary  Prolog
goals.   The specified goal is started  _a_f_t_e_r 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  _g_o_a_l_s.   This  implies that  directives  may call  any
predicate that  has been defined  before the  point where the  directive
appears.  It also accepts ?- <_t_e_r_m>.as a synonym.

SWI-Prolog   does   not   have   a   separate   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 (section  ????), multithreaded  loading (section  ????) and  reloading
running code (section ????).

The core  of the  family of  loading predicates  is load_files/2.    The
predicates  consult/1, ensure_loaded/1,  use_module/1, use_module/2  and
reexport/1  pass the  file argument  directly to  load_files/2 and  pass
additional options as expressed in the table ????:
         _______________________________________________________PPrreeddiiccaatteeiiffmmuusstt__bbee__mmoodduulleeiimmppoorrtt

         ______________________________________________________________________________________________________________consult/1truefalseall
          ensure_loaded/1 not_loaded      false         all

          use_module/1    not_loaded       true         all
          use_module/2    not_loaded       true      specified
          reexport/1      not_loaded       true         all
         _reexport/2______not_loaded_______true______specified__

Table  4.1:   Properties of  the file-loading  predicates.   The  _i_m_p_o_r_t
column specifies what is imported if the loaded file is a module file.


llooaadd__ffiilleess((_:_F_i_l_e_s))
    Equivalent  to  load_files(_F_i_l_e_s_,  _[_]).    Same  as  consult/1,  See
    load_files/2 for supported options.


llooaadd__ffiilleess((_:_F_i_l_e_s_, _+_O_p_t_i_o_n_s))
    The  predicate load_files/2 is the parent  of all the other  loading
    predicates  except for include/1.   It  currently supports a  subset
    of  the options of Quintus load_files/2.   _F_i_l_e_s is either a  single
    source  file or a  list of source  files.   The specification for  a
    source  file is handed to absolute_file_name/2.  See  this predicate
    for  the supported expansions.   _O_p_t_i_o_n_s is a list of options  using
    the format _O_p_t_i_o_n_N_a_m_e(_O_p_t_i_o_n_V_a_l_u_e).

    The following options are currently supported:

    aauuttoollooaadd((_B_o_o_l))
         If true (default  false), indicate that  this load is a  _d_e_m_a_n_d
         load.   This  implies that,  depending  on the  setting of  the
         Prolog flag  verbose_autoload, the  load action  is printed  at
         level informational  or silent.   See also  print_message/2 and
         current_prolog_flag/2.

    cchheecckk__ssccrriipptt((_B_o_o_l))
         If false (default  true), do not  check the first character  to
         be # and skip the first line when found.

    ddeerriivveedd__ffrroomm((_F_i_l_e))
         Indicate that the  loaded file is derived  from _F_i_l_e.  Used  by
         make/0 to  time-check and  load the original  file rather  than
         the derived file.

    ddiiaalleecctt((_+_D_i_a_l_e_c_t))
         Load _F_i_l_e_s with  enhanced compatibility with the target  Prolog
         system  identified  by  _D_i_a_l_e_c_t.    See  expects_dialect/1  and
         section ???? for details.

    eennccooddiinngg((_E_n_c_o_d_i_n_g))
         Specify the way  characters are encoded in  the file.   Default
         is taken  from the Prolog flag  encoding.   See section ????  for
         details.

    eexxppaanndd((_B_o_o_l))
         If true, run the  filenames through expand_file_name/2 and load
         the returned  files.   Default is false,  except for  consult/1
         which is intended  for interactive use.   Flexible location  of
         files is defined by file_search_path/2.

    ffoorrmmaatt((_+_F_o_r_m_a_t))
         Used to  specify  the file  format  if data  is loaded  from  a
         stream using  the stream(_S_t_r_e_a_m)  option.   Default is  source,
         loading  Prolog source  text.    If  qlf,  load QLF  data  (see
         qcompile/1).

    iiff((_C_o_n_d_i_t_i_o_n))
         Load the  file only  if the specified  condition is  satisfied.
         The value  true loads the  file unconditionally, changed  loads
         the file  if it  was  not loaded  before or  has been  modified
         since it  was loaded the  last time,  and not_loaded loads  the
         file if it was not loaded before.

    iimmppoorrttss((_I_m_p_o_r_t))
         Specify what  to import from  the loaded module.   The  default
         for use_module/1  is all.   _I_m_p_o_r_t  is passed  from the  second
         argument  of use_module/2.    Traditionally  it  is a  list  of
         predicate indicators to import.  As part  of the SWI-Prolog/YAP
         integration,  we  also  support  _P_r_e_d  as   _N_a_m_e  to  import  a
         predicate under another name.  Finally, _I_m_p_o_r_t can  be the term
         except(_E_x_c_e_p_t_i_o_n_s),  where _E_x_c_e_p_t_i_o_n_s  is a  list of  predicate
         indicators that  specify predicates  that are  _n_o_t imported  or
         _P_r_e_d as  _N_a_m_e terms  to denote renamed  predicates.   See  also
         reexport/2 and use_module/2.

         If _I_m_p_o_r_t  equals  all,  all operators  are imported  as  well.
         Otherwise,  operators  are _n_o_t  imported.    Operators  can  be
         imported selectively by adding terms op(_P_r_i_,_A_s_s_o_c_,_N_a_m_e)  to the
         _I_m_p_o_r_t 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  _N_a_m_e  bound to  import  a
         particular operator.

    mmooddiiffiieedd((_T_i_m_e_S_t_a_m_p))
         Claim that the source was loaded at  _T_i_m_e_S_t_a_m_p without checking
         the source.  This  option is intended to be used  together with
         the  stream(_I_n_p_u_t) option,  for  example after  extracting  the
         time from an HTTP server or database.

    mmoodduullee((_+_M_o_d_u_l_e))
         Load the indicated file  into the given module, overruling  the
         module name  specified in  the :- 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.

    mmuusstt__bbee__mmoodduullee((_B_o_o_l))
         If true,  raise an  error if  the file  is not  a module  file.
         Used by use_module/[1,2].

    qqccoommppiillee((_A_t_o_m))
         How to  deal  with quick-load-file  compilation by  qcompile/1.
         Values are:

         nneevveerr
             Default.  Do not use qcompile unless called explicitly.

         aauuttoo
             Use qcompile for all writeable files.  See comment below.

         llaarrggee
             Use  qcompile if  the file is  `large'.   Currently,  files
             larger than 100 Kbytes are considered large.

         ppaarrtt
             If  load_files/2 appears  in  a directive  of a  file  that
             is  compiled into Quick Load  Format using qcompile/1,  the
             contents  of the argument  files are  included in the  .qlf
             file instead of the loading directive.

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

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

    rreeeexxppoorrtt((_B_o_o_l))
         If true re-export the  imported predicate.  Used  by reexport/1
         and reexport/2.

    rreeggiisstteerr((_B_o_o_l))
         If false, do not register the load location and options.   This
         option is used by make/0 and load_hotfixes/1 to avoid polluting
         the load-context database.  See source_file_property/2.

    ssaannddbbooxxeedd((_B_o_o_l))
         Load the  file in  _s_a_n_d_b_o_x_e_d mode.   This  option controls  the
         flag sandboxed_load.   The  only meaningful value  for _B_o_o_l  is
         true.  Using false while the Prolog flag is set  to true raises
         a permission error.

    ssccooppee__sseettttiinnggss((_B_o_o_l))
         Scope style_check/1 and expects_dialect/1to  the file and files
         loaded from  the file after  the directive.   Default is  true.
         The system and  user initialization files  (see -f and -F)  are
         loading with scope_settings(_f_a_l_s_e).

    ssiilleenntt((_B_o_o_l))
         If  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 verbose_load with the negation of _B_o_o_l.

    ssttrreeaamm((_I_n_p_u_t))
         This SWI-Prolog  extension compiles  the data  from the  stream
         _I_n_p_u_t.   If this option  is used, _F_i_l_e_s  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  _u_s_e_r (see consult/1)
         or other servers.  It can be combined with  format(_q_l_f) to load
         QLF data from a stream.

    The  load_files/2 predicate  can be  hooked to  load  other data  or
    data  from objects  other than  files.   See  prolog_load_file/2 for
    a  description and  http/http_load  for an  example.   All hooks  for
    load_files/2 are documented in section ????.


ccoonnssuulltt((_:_F_i_l_e))
    Read  _F_i_l_e  as  a  Prolog source  file.    Calls  to  consult/1  may
    be  abbreviated by  just typing  a number  of filenames  in a  list.
    Examples:

            ?- consult(load).     % consult load or load.pl
            ?- [library(lists)].  % load library lists
            ?- [user].            % Type program on the terminal

    The  predicate  consult/1  is  equivalent  to  load_files(File, []),
    except for handling  the special file user, which reads clauses from
    the  terminal.  See  also the stream(_I_n_p_u_t) option  of load_files/2.
    Abbreviation  using ?- [file1,file2].  does _n_o_t work  for the  empty
    list  ([]).    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.


eennssuurree__llooaaddeedd((_:_F_i_l_e))
    If the file  is not already loaded, this is equivalent to 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,
    ensure_loaded/1 will call 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 use_module/[1,2].

    Equivalent to load_files(Files, [if(not_loaded)]).


iinncclluuddee((_+_F_i_l_e))                                                    _[_I_S_O_]
    Textually  include the  content of  _F_i_l_e at the  position where  the
    _d_i_r_e_c_t_i_v_e :- include(File). appears.   The include construct is only
    honoured  if it appears as  a directive in a  source file.   _T_e_x_t_u_a_l
    include (similar to  C/C++ #include) is obviously useful for sharing
    declarations  such as dynamic/1 or  multifile/1 by including a  file
    with directives from multiple files that use these predicates.

    Textually  including files  that  contain _c_l_a_u_s_e_s  is less  obvious.
    Normally,  in SWI-Prolog,  clauses are  _o_w_n_e_d by the  file in  which
    they  are defined.    This information is  used to  _r_e_p_l_a_c_e the  old
    definition  after the  file has  been modified and  is reloaded  by,
    e.g.,  make/0.    As  we understand  it,  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  _c_o_p_i_e_s of  predicates.
    Using  use_module/1 can achieve  the same  result while _s_h_a_r_i_n_g  the
    predicates.

    If  include/1 is used  to load files holding  clauses, and if  these
    files  are loaded only once, then these include/1 directives  can be
    replaced  by other predicates (such  as consult/1).  However,  there
    are  several cases  where either  include/1 has  no alternative,  or
    using  any alternative also requires other  changes.  An example  of
    the  former is  using 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
    include/1, the  directive discontiguous/1 is appropriate, whereas if
    they are consulted, one must use the directive 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 _o_w_n_e_r of  a clause (the file  that
    includes  the file  holding the  clause).   The  source location  is
    used  by,  e.g.,  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:

      o  source_file/2 describes the owner relation.

      o  predicate_property/2 describes  the  source  location  (of  the
         first clause).

      o  clause_property/2 provides access to both source and ownership.

      o  source_file_property/2 can be used  to query include  relation-
         ships between files.


rreeqquuiirree((_+_L_i_s_t_O_f_N_a_m_e_A_n_d_A_r_i_t_y))
    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 nnoott 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
    check/0 and autoload/0.


eennccooddiinngg((_+_E_n_c_o_d_i_n_g))
    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 section ????.


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

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

ffiillee__sseeaarrcchh__ppaatthh((_+_A_l_i_a_s_, _-_P_a_t_h))
    Dynamic  multifile hook  predicate used to  specify `path  aliases'.
    This   hook  is  called  by  absolute_file_name/3 to   search  files
    specified  as Alias(_N_a_m_e),  e.g., library(_l_i_s_t_s).   This feature  is
    best described using an example.  Given the definition:

    ____________________________________________________________________|                                                                    |
    ||file_search_path(demo,_'/usr/lib/prolog/demo').___________________ ||

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

    Below  is the  initial definition  of the file  search path.    This
    path  implies swi(<_P_a_t_h>) and  refers to  a file  in the  SWI-Prolog
    home   directory.     The  alias  foreign(<_P_a_t_h>) is   intended  for
    storing   shared  libraries  (.so  or   .DLL  files).     See   also
    use_foreign_library/1.

    ____________________________________________________________________|                                                                    |

    | 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).________________________________________ ||

    The  file_search_path/2expansion  is used by all loading  predicates
    as well as by absolute_file_name/[2,3].

    The  Prolog  flag verbose_file_search can  be set  to  true to  help
    debugging Prolog's search for files.


eexxppaanndd__ffiillee__sseeaarrcchh__ppaatthh((_+_S_p_e_c_, _-_P_a_t_h))                            _[_n_o_n_d_e_t_]
    Unifies  _P_a_t_h with all possible expansions of the  filename specifi-
    cation _S_p_e_c.  See also absolute_file_name/3.


pprroolloogg__ffiillee__ttyyppee((_?_E_x_t_e_n_s_i_o_n_, _?_T_y_p_e))
    This  dynamic multifile predicate defined in module  user determines
    the  extensions considered by file_search_path/2.  _E_x_t_e_n_s_i_o_n is  the
    filename  extension without the  leading dot,  and _T_y_p_e denotes  the
    type  as used  by the file_type(_T_y_p_e) option  of file_search_path/2.
    Here is the initial definition of prolog_file_type/2:

    ____________________________________________________________________|                                                                    |
    | 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).________ ||

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

ssoouurrccee__ffiillee((_?_F_i_l_e))
    True  if _F_i_l_e is a loaded Prolog source file.  _F_i_l_e  is the absolute
    and canonical path to the source file.


ssoouurrccee__ffiillee((_:_P_r_e_d_, _?_F_i_l_e))
    True  if the  predicate specified  by _P_r_e_d  is owned  by file  _F_i_l_e,
    where  _F_i_l_e  is an  absolute path  name  (see absolute_file_name/2).
    Can  be used with any  instantiation pattern, but the database  only
    maintains  the  source file  for  each  predicate.    If _P_r_e_d  is  a
    _m_u_l_t_i_f_i_l_e  predicate  this predicate  succeeds  for all  files  that
    contribute  clauses to  _P_r_e_d.   See  also clause_property/2.    Note
    that  the relation between files and predicates is  more complicated
    if  include/1 is used.    The predicate describes  the _o_w_n_e_r of  the
    predicate.  See include/1 for details.


ssoouurrccee__ffiillee__pprrooppeerrttyy((_?_F_i_l_e_, _?_P_r_o_p_e_r_t_y))
    True  when _P_r_o_p_e_r_t_y  is a  property of  the loaded  file _F_i_l_e.    If
    _F_i_l_e  is non-var, it can be  a file specification that is  valid for
    load_files/2.  Defined properties are:

    ddeerriivveedd__ffrroomm((_O_r_i_g_i_n_a_l_, _O_r_i_g_i_n_a_l_M_o_d_i_f_i_e_d))
         _F_i_l_e was  generated  from the  file  _O_r_i_g_i_n_a_l, which  was  last
         modified at time  _O_r_i_g_i_n_a_l_M_o_d_i_f_i_e_d at the  time it was  loaded.
         This  property  is available  if  _F_i_l_e  was  loaded  using  the
         derived_from(_O_r_i_g_i_n_a_l) option to load_files/2.

    iinncclluuddeess((_I_n_c_l_u_d_e_d_F_i_l_e_, _I_n_c_l_u_d_e_d_F_i_l_e_M_o_d_i_f_i_e_d))
         _F_i_l_e  used  include/1  to  include  _I_n_c_l_u_d_e_d_F_i_l_e.     The  last
         modified time of  _I_n_c_l_u_d_e_d_F_i_l_e was _I_n_c_l_u_d_e_d_F_i_l_e_M_o_d_i_f_i_e_d at  the
         time it was included.

    iinncclluuddeedd__iinn((_M_a_s_t_e_r_F_i_l_e_, _L_i_n_e))
         _F_i_l_e was included into _M_a_s_t_e_r_F_i_l_e from line _L_i_n_e.   This is the
         inverse of the includes property.

    llooaadd__ccoonntteexxtt((_M_o_d_u_l_e_, _L_o_c_a_t_i_o_n_, _O_p_t_i_o_n_s))
         _M_o_d_u_l_e is the module into  which the file was loaded.   If _F_i_l_e
         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.    _L_o_c_a_t_i_o_n describes  the
         file location  from which the file  was loaded.   It is  either
         a term  <_f_i_l_e>:<_l_i_n_e> or the  atom user if  the file  was loaded
         from the terminal or  another unknown source.  _O_p_t_i_o_n_s  are the
         options  passed to  load_files/2.    Note that  all  predicates
         to load  files  are mapped  to load_files/2,  using the  option
         argument to specify the exact behaviour.

    llooaadd__ccoouunntt((_-_C_o_u_n_t))
         _C_o_u_n_t is the number  of times the file have been loaded,  i.e.,
         1 (one) if the file has been loaded once.

    mmooddiiffiieedd((_S_t_a_m_p))
         File modification time when _F_i_l_e  was loaded.  This is  used by
         make/0 to find files whose modification time  is different from
         when it was loaded.

    mmoodduullee((_M_o_d_u_l_e))
         _F_i_l_e is a module file that declares the module _M_o_d_u_l_e.

    nnuummbbeerr__ooff__ccllaauusseess((_C_o_u_n_t))
         _C_o_u_n_t is  the number  of clauses associated  with _F_i_l_e.    Note
         that clauses loaded from included files are counted  as part of
         the main file.

    rreellooaaddiinngg
         Present if the file is currently being rreeloaded.


uunnllooaadd__ffiillee((_+_F_i_l_e))
    Remove  all clauses  loaded from  _F_i_l_e.   If _F_i_l_e  loaded a  module,
    clear  the module's export list  and disassociate it from the  file.
    _F_i_l_e  is a canonical filename or a file indicator that is  valid for
    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
    _F_i_l_e are active.


pprroolloogg__llooaadd__ccoonntteexxtt((_?_K_e_y_, _?_V_a_l_u_e))
    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   term_expansion/2  and  goal_expansion/2  hooks.     See   also
    source_location/2 and if/1.  The following keys are defined:

    ______________________________________________________________________
    |__KKeeyy________________________||DDeessccrriippttiioonn________________________________________________________________________________||__
    || directory      |Directory in which source lives                    |
    | dialect        |Compatibility mode.  See expects_dialect/1.        |
    | file           |Similar  to  source,  but  returns  the  file being|

    |                |included when called while an include file is being|
    |                |processed                                          |
    | module         |Module into which file is loaded                   |
    | reload         |true if the file is being rreeloaded.  Not present on|
    |                |first load                                         |
    | script         |Boolean  that indicates whether the  file is loaded|
    |                |as a script file (see -s)                          |

    | source         |File being  loaded.  If the system is processing an|
    |                |included file, the value is the _m_a_i_n file.  Returns|
    |                |the original Prolog file when loading a .qlf file. |
    | stream         |Stream identifier (see current_input/1)            |
    | term_position  |Start   position   of  last   term  read.       See|
    |                |also   stream_property/2  (position   property  and|
    |                |stream_position_data/3.                            |
    | term           |Term being expanded by expand_term/2.              |

    | variable_names |A list of  `_N_a_m_e = _V_a_r' of the last term read.  See|
    |________________|read_term/2for_details.____________________________|_

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

    ____________________________________________________________________|                                                                    |

    | :- 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) ]),                          |
    ||____...___________________________________________________________ ||


ssoouurrccee__llooccaattiioonn((_-_F_i_l_e_, _-_L_i_n_e))
    If the last term  has been read from a physical file (i.e., not from
    the file user or  a string), unify _F_i_l_e with an absolute path to the
    file  and _L_i_n_e with the  line number in the  file.  New code  should
    use prolog_load_context/2.


aatt__hhaalltt((_:_G_o_a_l))
    Register  _G_o_a_l to  be run  from 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  print_message/2.   An attempt  to call halt/[0,1] from a  hook
    is  ignored.    Hooks  may call  cancel_halt/1, causing  halt/0  and
    PL_halt(_0)  to print a  message indicating  that halting the  system
    has been cancelled.


ccaanncceell__hhaalltt((_+_R_e_a_s_o_n))
    If  this predicate is called from a  hook registered with at_halt/1,
    halting Prolog is  cancelled and an informational message is printed
    that  includes _R_e_a_s_o_n.   This  is used by  the development tools  to
    cancel  halting the system  if the editor  has unsafed data and  the
    user decides to cancel.


::-- iinniittiiaalliizzaattiioonn((_:_G_o_a_l))                                          _[_I_S_O_]
    Call  _G_o_a_l _a_f_t_e_r  loading the  source file in  which this  directive
    appears  has been completed.    In addition, _G_o_a_l  is executed if  a
    saved state created using qsave_program/1 is restored.

    The  ISO  standard  only allows  for  using  :- Term if  _T_e_r_m  is  a
    _d_i_r_e_c_t_i_v_e.  This  means that arbitrary goals can only be called from
    a directive by  means of the initialization/1 directive.  SWI-Prolog
    does not enforce this rule.

    The   initialization/1  directive  must   be  used  to  do   program
    initialization  in  saved states  (see  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 initialization/1
    directives or from the entry goal of the saved state.

    Up  to SWI-Prolog 5.7.11, _G_o_a_l 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,  load_foreign_library/1 must be  executed  immediately
    to  make  the loaded  foreign  predicates available  for  exporting.
    SWI-Prolog  now  provides  the  directive  use_foreign_library/1  to
    ensure  immediate  loading   as  well  as  loading  after  restoring
    a   saved  state.       If   the  system   encounters  a   directive
    :- 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 prolog:initialize_now(_T_e_r_m_,  _A_d_v_i_c_e),
    where  _A_d_v_i_c_e is an  atom that  gives advice on  how to resolve  the
    compatibility issue.


iinniittiiaalliizzaattiioonn((_:_G_o_a_l_, _+_W_h_e_n))
    Similar to initialization/1,  but allows for specifying when _G_o_a_l is
    executed while loading the program text:

    nnooww
         Execute _G_o_a_l immediately.

    aafftteerr__llooaadd
         Execute  _G_o_a_l after  loading  the  program text  in  which  the
         directive appears.  This is the same as initialization/1.

    rreessttoorree
         Do not execute  _G_o_a_l while loading  the program, but _o_n_l_y  when
         restoring a saved state.

    pprrooggrraamm
         Execute  _G_o_a_l once  after executing  the  -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  _n_o_t executed
         if the -l  is given to  merely _l_o_a_d files.   In that case  they
         may  be executed  explicitly  using  initialize/0.    See  also
         section ????.

    mmaaiinn
         When Prolog starts, the last goal registered  using initializa-
         tion(_G_o_a_l_, _m_a_i_n) is  executed as main goal.   If _G_o_a_l fails  or
         raises an exception, the process terminates with  non-zero exit
         code.   If not explicitly specified  using the -t the  _t_o_p_l_e_v_e_l
         _g_o_a_l is set to halt/0, causing the process to  exit with status
         0.   An  explicitly  specified toplevel  is executed  normally.
         This implies  that -t prolog  causes the  application to  start
         the normal  interactive toplevel  after completing _G_o_a_l.    See
         also the Prolog flag toplevel_goal and section ????.


iinniittiiaalliizzaattiioonn                                                    _[_d_e_t_]
    Run  all initialization goals registered using  initialization(_G_o_a_l_,
    _p_r_o_g_r_a_m).     Raises  an  error  initialization_error(_R_e_a_s_o_n_,  _G_o_a_l_,
    _F_i_l_e_:_L_i_n_e)  if _G_o_a_l fails or raises an exception.  _R_e_a_s_o_n  is failed
    or the exception raised.


ccoommppiilliinngg
    True  if the system is compiling source files with the -c  option or
    qcompile/1  into an intermediate code file.  Can be used  to perform
    conditional code  optimisations in term_expansion/2(see  also the -O
    option) or to omit execution of directives during compilation.


44..33..11 CCoonnddiittiioonnaall ccoommppiillaattiioonn aanndd pprrooggrraamm ttrraannssffoorrmmaattiioonn

ISO  Prolog  defines   no  way  for  program  transformations  such   as
macro  expansion  or   conditional  compilation.     Expansion   through
term_expansion/2 and 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  term_expansion/2 can return a  list, the  transformation
does not need to be term-to-term.

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

tteerrmm__eexxppaannssiioonn((_+_T_e_r_m_1_, _-_T_e_r_m_2))
    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 _T_e_r_m_2
    in  the database rather than the read term (_T_e_r_m_1).  _T_e_r_m_2  may be a
    term  of the form ?- Goal.  or :- Goal.   _G_o_a_l is then treated as  a
    directive.   If _T_e_r_m_2  is a list, all  terms of the list are  stored
    in  the database or  called (for directives).   If  _T_e_r_m_2 is of  the
    form  below, the system will assert _C_l_a_u_s_e and record  the indicated
    source location with it:

         '$source_location'(<_F_i_l_e>, <_L_i_n_e>):<_C_l_a_u_s_e>

    When   compiling  a  module  (see  chapter  ????  and   the  directive
    module/2),  expand_term/2  will first  try  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,  expand_term/2 will  try
    term_expansion/2  in module user.    For compatibility with  SICStus
    and  Quintus Prolog,  this feature  should not  be used.   See  also
    expand_term/2, goal_expansion/2 and expand_goal/2.


eexxppaanndd__tteerrmm((_+_T_e_r_m_1_, _-_T_e_r_m_2))
    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.

     1.  Test  conditional  compilation  directives  and  translate  all
         input to []  if we are in  a `false branch' of the  conditional
         compilation.  See section ????.

     2.  Call term_expansion/2.   This predicate is  first tried in  the
         module that is being compiled and then in the module user.

     3.  Call DCG expansion (dcg_translate_rule/2).

     4.  Call expand_goal/2 on each body term that appears in the output
         of the previous steps.


ggooaall__eexxppaannssiioonn((_+_G_o_a_l_1_, _-_G_o_a_l_2))
    Like  term_expansion/2,  goal_expansion/2  provides  for  macro  ex-
    pansion  of  Prolog source  code.    Between  expand_term/2 and  the
    actual  compilation, the body of clauses analysed and the  goals are
    handed  to expand_goal/2, which  uses the goal_expansion/2 hook to do
    user-defined expansion.

    The  predicate goal_expansion/2 is first  called in the module  that
    is  being compiled,  and then  follows the  module inheritance  path
    as  defined by default_module/2, i.e.,  by default user and  system.
    If  _G_o_a_l is of  the form _M_o_d_u_l_e:_G_o_a_l  where _M_o_d_u_l_e is  instantiated,
    goal_expansion/2 is  called on _G_o_a_l  using rules from module  _M_o_d_u_l_e
    followed by default modules for _M_o_d_u_l_e.

    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 meta_predicate/1).
    Other cases need a real predicate definition.

    The   expansion  hook   can  use  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.


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

ccoommppiillee__aauuxx__ccllaauusseess((_+_C_l_a_u_s_e_s))
    Compile  clauses  on behalf  of  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 goal_expansion/2 can use predicate_property/2
    using the property  defined to test whether the predicate is already
    defined in the current context.


ddccgg__ttrraannssllaattee__rruullee((_+_I_n_, _-_O_u_t))
    This  predicate performs the translation of a term  Head-->Body into
    a  normal Prolog  clause.    Normally this  functionality should  be
    accessed using expand_term/2.


vvaarr__pprrooppeerrttyy((_+_V_a_r_, _?_P_r_o_p_e_r_t_y))
    True  when _P_r_o_p_e_r_t_y  is a  property of _V_a_r.    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
    goal_expansion/2.

    ffrreesshh((_B_o_o_l))
         Bool has  the value _t_r_u_e  if the variable  is guaranteed to  be
         unbound at  entry of the  goal, otherwise  its value is  _f_a_l_s_e.
         This implies that  the variable first  appears in this goal  or
         a previous appearance was  in a negation (\+/1) or  a different
         branch of a disjunction.

    nnaammee((_N_a_m_e))
         True when variable appears with the given name in the source.


44..33..11..11 PPrrooggrraamm ttrraannssffoorrmmaattiioonn wwiitthh ssoouurrccee llaayyoouutt iinnffoo

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:

  o More precise locations of warnings and errors

  o More reliable setting of breakpoints

  o More reliable source layout information in the graphical debugger.


eexxppaanndd__ggooaall((_+_G_o_a_l_1_, _?_L_a_y_o_u_t_1_, _-_G_o_a_l_2_, _-_L_a_y_o_u_t_2))


ggooaall__eexxppaannssiioonn((_+_G_o_a_l_1_, _?_L_a_y_o_u_t_1_, _-_G_o_a_l_2_, _-_L_a_y_o_u_t_2))


eexxppaanndd__tteerrmm((_+_T_e_r_m_1_, _?_L_a_y_o_u_t_1_, _-_T_e_r_m_2_, _-_L_a_y_o_u_t_2))


tteerrmm__eexxppaannssiioonn((_+_T_e_r_m_1_, _?_L_a_y_o_u_t_1_, _-_T_e_r_m_2_, _-_L_a_y_o_u_t_2))


ddccgg__ttrraannssllaattee__rruullee((_+_I_n_, _?_L_a_y_o_u_t_I_n_, _-_O_u_t_, _-_L_a_y_o_u_t_O_u_t))
    These  versions  are called  _b_e_f_o_r_e 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 subterm_positions of read_term/2.


44..33..11..22 CCoonnddiittiioonnaall ccoommppiillaattiioonn

Conditional   compilation    builds   on    the   same   principle    as
term_expansion/2,   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  section ???? for more information.  Here is  a simple
example:

________________________________________________________________________|                                                                        |
|:- if(\+source_exports(library(lists), suffix/2)).                      |

|                                                                        |
|suffix(Suffix, List) :-                                                 |
|        append(_, Suffix, List).                                        |
|                                                                        |
|:-|endif.______________________________________________________________ |  |

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

  o Load different libraries on different dialects.

  o Define a predicate if it is missing as a system predicate.

  o Realise  totally different implementations for a particular  part of
    the code due to different capabilities.

  o Realise different configuration options for your software.


::-- iiff((_:_G_o_a_l))
    Compile  subsequent  code  only if  _G_o_a_l  succeeds.    For  enhanced
    portability,  _G_o_a_l is  processed by expand_goal/2 before  execution.
    If an error  occurs, the error is printed and processing proceeds as
    if _G_o_a_l has failed.


::-- eelliiff((_:_G_o_a_l))
    Equivalent to :- else.  :-if(Goal).  ...  :- endif. In a sequence as
    below,  the section below the first matching elif is processed.   If
    no test succeeds, the else branch is processed.

    ____________________________________________________________________|                                                                    |
    | :- if(test1).                                                      |

    | section_1.                                                         |
    | :- elif(test2).                                                    |
    | section_2.                                                         |
    | :- elif(test3).                                                    |
    | section_3.                                                         |
    | :- else.                                                           |
    | section_else.                                                      |
    ||:-_endif._________________________________________________________ ||


::-- eellssee
    Start `else' branch.


::-- eennddiiff
    End of conditional compilation.


44..33..22 RReellooaaddiinngg ffiilleess,, aaccttiivvee ccooddee aanndd tthhrreeaaddss

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

  o Trace a goal

  o Find unexpected behaviour of a predicate

  o Enter a _b_r_e_a_k using the bb command

  o Fix the sources and reload them using make/0

  o Exit the break,  _r_e_t_r_y executing the now fixed predicate using the rr
    command

_R_e_l_o_a_d_i_n_g a previously loaded  file is safe, both in the  debug scenario
above and when the code is being executed by another  _t_h_r_e_a_d.  Executing
threads switch atomically to the new definition  of modified predicates,
while  clauses  that  belong to  the  old  definition  are  (eventually)
reclaimed by  garbage_collect_clauses/0.    Below we  describe the  steps
taken for _r_e_l_o_a_d_i_n_g a file to help understanding the  limitations of the
process.

 1. If  a file is being reloaded, a _r_e_l_o_a_d _c_o_n_t_e_x_t 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.

 2. If  a new  predicate is  found,  an entry  is added  to the  context
    predicate table.  Three options are considered:

    (a)  The predicate is new.   It is handled  the same as if the  file
         was loaded for the first time.

    (b)  The predicate  is  foreign or  thread  local.   These  too  are
         treated as if the file was loaded for the first time.

    (c)  Normal  predicates.    Here  we  initialise a  pointer  to  the
         _c_u_r_r_e_n_t _c_l_a_u_s_e.

 3. New clauses for `normal predicates' are considered as follows:

    (a)  If  the  clause's byte-code  is  the  same  as  the  predicates
         current clause,  discard  the clause  and  advance the  current
         clause pointer.

    (b)  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.

    (c)  If the  clause's byte-code  matches no  clause,  insert it  for
         _f_u_t_u_r_e  _a_c_t_i_v_a_t_i_o_n  before the  current  clause  and  keep  the
         current clause.

 4. _P_r_o_p_e_r_t_i_e_s  such as  dynamic or meta_predicate  are in part  applied
    immediately  and in  part during  the fixup process  after the  file
    completes loading.   Currently, dynamic and thread_local are applied
    immediately.

 5. New   modules  are  recorded  in   the  reload  context.      Export
    declarations (the module's  public list and export/1 calls) are both
    applied and recorded.

 6. When  the  end-of-file is  reached, the  following  fixup steps  are
    taken

    (a)  For each predicate

          i. The  current clause and subsequent  clauses are marked  for
             future deletion.

         ii. All  clauses   marked  for  future  deletion  or   creation
             are   (in)activated   by   changing   their   `erased'   or
             `created'  _g_e_n_e_r_a_t_i_o_n.    Erased clauses  are  (eventually)
             reclaimed   by   the   _c_l_a_u_s_e   _g_a_r_b_a_g_e   _c_o_l_l_e_c_t_o_r,    see
             garbage_collect_clauses/0.

        iii. Pending predicate property changes are applied.

    (b)  For each module

          i. Exported predicates that are not  encountered in the reload
             context are removed from the export list.

The above generally ensures that changes to the _c_o_n_t_e_n_t  of source files
can typically  be activated safely  using 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 goal_expansion/2 or term_expansion/2
are defined  or goals  are executed using  _d_i_r_e_c_t_i_v_e_s..   Up to  version
7.5.12  it was  typically needed  to  reload the  file _t_w_i_c_e,  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
_t_r_a_n_s_a_c_t_i_o_n  _s_e_m_a_n_t_i_c_s  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  _a_t_o_m_i_c update from  the old  file
content to the new.


44..33..22..11 CCoommppiillaattiioonn ooff mmuuttuuaallllyy ddeeppeennddeenntt ccooddee

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., consult/1) are used to  include file
B  from A  and  A  from B,  loading  either file  results  in  a loop.
This is  because consult/1  is mapped to  load_files/2 using the  option
if(true)(_.)    Such programs  are  typically loaded  using a  _l_o_a_d  _f_i_l_e
that consults  all required (non-module)  files.   If modules are  used,
the dependencies are  made explicit using use_module/1 statements.   The
use_module/1 predicate,  however, maps to  load_files/2 with the  option
if(not_loaded)(_.)  A 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  consult/1,  predicate
dependencies  between loaded  files  can  still be  arbitrary,  but  the
consult relations between files must be a proper tree.


44..33..22..22 CCoommppiillaattiioonn wwiitthh mmuullttiippllee tthhrreeaaddss

This  section  discusses compiling  files  for  the  first time.     For
reloading, see section ????.

In older versions, compilation  was thread-safe due to a global  _l_o_c_k in
load_files/2 and  the code dealing  with _a_u_t_o_l_o_a_d_i_n_g  (see section  ????).
Besides  unnecessary  stalling  when  multiple  threads  trap  unrelated
undefined  predicates,  this  easily  leads  to  deadlocks,  notably  if
threads are started from an initialization/1 directive.

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,  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 section  ????) 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.


44..33..33 QQuuiicckk llooaadd ffiilleess

SWI-Prolog supports compilation of individual or  multiple Prolog source
files into `Quick Load  Files'.  A `Quick Load File' (.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 qcompile/1.   They are loaded  using
consult/1  or one  of  the other  file-loading predicates  described  in
section ????.   If consult/1 is given  an explicit .pl file, it will  load
the Prolog  source.   When given  a .qlf  file, it will  load the  file.
When no extension is specified, it will load the  .qlf file when present
and the .pl file otherwise.


qqccoommppiillee((_:_F_i_l_e))
    Takes  a file specification as consult/1, etc., and, in  addition to
    the  normal compilation, creates a _Q_u_i_c_k  _L_o_a_d _F_i_l_e from _F_i_l_e.   The
    file  extension of this  file is .qlf.   The  basename of the  Quick
    Load File is the same as the input file.

    If   the   file  contains   `:- consult(_+_F_i_l_e)',   `:- [_+_F_i_l_e]'   or
    `:- load_files(_+_F_i_l_e, [qcompile(part), ...])'  statements,  the  re-
    ferred  files  are  compiled  into  the  same  .qlf  file.     Other
    directives will be stored  in the .qlf file and executed in the same
    fashion as when loading the .pl file.

    For  term_expansion/2, the  same rules  as described  in section  ????
    apply.

    Conditional  execution   or  optimisation  may  test  the  predicate
    compiling/0.

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

qqccoommppiillee((_:_F_i_l_e_, _+_O_p_t_i_o_n_s))
    As  qcompile/1,  but  processes  additional options  as  defined  by
    load_files/2.


44..44 EEddiittoorr IInntteerrffaaccee

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 edit/1 and consists of  three parts:
_l_o_c_a_t_i_n_g, _s_e_l_e_c_t_i_n_g and _s_t_a_r_t_i_n_g the editor.  Any of  these parts may be
customized.  See section ????.

The built-in  edit specifications for  edit/1 (see prolog_edit:locate/3)
are described in the table below:

   ___________________________________________________________________
   |__________________________________________FFuullllyy__ssppeecciiffiieedd__oobbjjeeccttss____________________________________________||
   || <_M_o_d_u_l_e>:<_N_a_m_e>/<_A_r_i_t_y>R|efers to a predicate                   |
   | module(<_M_o_d_u_l_e>)      |Refers to a module                       |
   | file(<_P_a_t_h>)          |Refers to a file                         |

   |_source_file(<_P_a_t_h>)___R|efers_to_a_loaded_source_file___________|_
   |__________________________________________AAmmbbiigguuoouuss__ssppeecciiffiiccaattiioonnss__________________________________________||
   || <_N_a_m_e>/<_A_r_i_t_y>        R|efers to this predicate in any module   |
   | <_N_a_m_e>                |Refers to (1) the  named predicate in any|
   |                       |module  with any  arity,  (2) a  (source)|
   |_______________________|file,_or_(3)_a_module.___________________|_


eeddiitt((_+_S_p_e_c_i_f_i_c_a_t_i_o_n))
    First,  exploit prolog_edit:locate/3to  translate _S_p_e_c_i_f_i_c_a_t_i_o_n into
    a  list  of  _L_o_c_a_t_i_o_n_s.    If there  is  more than  one  `hit',  the
    user  is  asked  to select  from  the  locations found.     Finally,
    prolog_edit:edit_source/1 is  used  to invoke  the user's  preferred
    editor.   Typically, edit/1 can  be handed the name of  a predicate,
    module, basename of a file, XPCE class, XPCE method, etc.


eeddiitt
    Edit the `default' file  using edit/1.  The default file is the file
    loaded  with the  command line option  -s or, in  Windows, the  file
    loaded by double-clicking from the Windows shell.


44..44..11 CCuussttoommiizziinngg tthhee eeddiittoorr iinntteerrffaaccee

The predicates described in  this section are _h_o_o_k_s that can  be defined
to  disambiguate  specifications  given  to  edit/1,  find  the  related
source, and open an editor at the given source location.


pprroolloogg__eeddiitt::llooccaattee((_+_S_p_e_c_, _-_F_u_l_l_S_p_e_c_, _-_L_o_c_a_t_i_o_n))
    Where  _S_p_e_c is  the  specification provided  through edit/1.    This
    multifile  predicate is used to enumerate locations where  an object
    satisfying  the given _S_p_e_c can be  found.  _F_u_l_l_S_p_e_c is unified  with
    the  complete specification  for the  object.   This distinction  is
    used  to allow for ambiguous specifications.   For example, if  _S_p_e_c
    is  an atom, which appears as the  basename of a loaded file  and as
    the  name of a  predicate, _F_u_l_l_S_p_e_c will  be bound to file(_P_a_t_h)  or
    _N_a_m_e/_A_r_i_t_y.

    _L_o_c_a_t_i_o_n  is a list of attributes  of the location.  Normally,  this
    list  will contain the term  file(_F_i_l_e) and, if available, the  term
    line(_L_i_n_e).


pprroolloogg__eeddiitt::llooccaattee((_+_S_p_e_c_, _-_L_o_c_a_t_i_o_n))
    Same  as prolog_edit:locate/3,  but only  deals with fully  specified
    objects.


pprroolloogg__eeddiitt::eeddiitt__ssoouurrccee((_+_L_o_c_a_t_i_o_n))
    Start  editor on _L_o_c_a_t_i_o_n.   See prolog_edit:locate/3 for the  format
    of  a  location term.    This multifile  predicate  is normally  not
    defined.  If it succeeds, edit/1 assumes the editor is started.

    If  it fails, edit/1 uses  its internal defaults, which are  defined
    by  the Prolog flag editor  and/or the environment variable  EDITOR.
    The  following  rules apply.     If the  Prolog  flag editor  is  of
    the  format $<_n_a_m_e>,  the  editor is  determined by  the environment
    variable  <_n_a_m_e>.   Else, if this flag  is pce_emacs or built_in _a_n_d
    XPCE  is  loaded or  can  be loaded,  the  built-in Emacs  clone  is
    used.  Else,  if the environment EDITOR is set, this editor is used.
    Finally,  vi  is used  as default  on Unix  systems  and notepad  on
    Windows.

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

pprroolloogg__eeddiitt::eeddiitt__ccoommmmaanndd((_+_E_d_i_t_o_r_, _-_C_o_m_m_a_n_d))
    Determines  how  _E_d_i_t_o_r is  to be  invoked using  shell/1.    _E_d_i_t_o_r
    is   the  determined  editor  (see  qpredrefprolog_editedit_source1),
    without  the full path specification, and without a  possible (.exe)
    extension.    _C_o_m_m_a_n_d  is  an  atom describing  the  command.    The
    following  %-sequences are replaced in _C_o_m_m_a_n_d before the  result is
    handed to shell/1:

              ________________________________________________
              | %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_______________|

    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  vi, emacs, emacsclient,  vim,
    notepad* and  wordpad*.   Starred editors do not provide  starting at
    a given line number.

    Please contribute your specifications to bugs@swi-prolog.org.


pprroolloogg__eeddiitt::llooaadd
    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
    swi_edit,  containing definitions to locate  classes and methods  as
    well as to bind this package to the PceEmacs built-in editor.

    ____________________________________________________________________|                                                                    |
    | :- multifile prolog_edit:load/0.                                   |

    |                                                                    |
    | prolog_edit:load :-                                                |
    ||________ensure_loaded(library(swi_edit))._________________________ ||


44..55 LLiisstt tthhee pprrooggrraamm,, pprreeddiiccaatteess oorr ccllaauusseess


lliissttiinngg((_:_P_r_e_d))
    List  predicates specified by  _P_r_e_d.  _P_r_e_d  may be a predicate  name
    (atom),  which lists  all predicates with  this name, regardless  of
    their  arity.  It  can also be a predicate  indicator (<_n_a_m_e>/<_a_r_i_t_y>
    or <_n_a_m_e>//<_a_r_i_t_y>),  possibly qualified with a module.  For example:
    ?- listing(lists:member/2)..

    A  listing is produced by  enumerating the clauses of the  predicate
    using  clause/2  and printing  each  clause using  portray_clause/1.
    This implies that the  variable names are generated (_A, _B, ...)  and
    the layout is defined by rules in portray_clause/1.


lliissttiinngg
    List  all predicates from the calling  module using listing/1.   For
    example,  ?- listing. lists clauses in  the default user module  and
    ?- lists:listing. lists the clauses in the module lists.


ppoorrttrraayy__ccllaauussee((_+_C_l_a_u_s_e))
    Pretty  print a  clause.   A clause  should be specified  as a  term
    `<_H_e_a_d> :- <_B_o_d_y>'.    Facts are  represented as  `<_H_e_a_d> :- true'  or
    simply  <_H_e_a_d>.  Variables  in the clause are written as  A, B, ....
    Singleton variables are written as _.  See also portray_clause/2.


ppoorrttrraayy__ccllaauussee((_+_S_t_r_e_a_m_, _+_C_l_a_u_s_e))
    Pretty print a clause to _S_t_r_e_a_m.  See portray_clause/1 for details.


44..66 VVeerriiffyy TTyyppee ooff aa TTeerrmm

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 error.


vvaarr((_@_T_e_r_m))                                                        _[_I_S_O_]
    True if _T_e_r_m currently is a free variable.


nnoonnvvaarr((_@_T_e_r_m))                                                     _[_I_S_O_]
    True if _T_e_r_m currently is not a free variable.


iinntteeggeerr((_@_T_e_r_m))                                                    _[_I_S_O_]
    True if _T_e_r_m is bound to an integer.


ffllooaatt((_@_T_e_r_m))                                                      _[_I_S_O_]
    True if _T_e_r_m is bound to a floating point number.


rraattiioonnaall((_@_T_e_r_m))
    True  if _T_e_r_m  is  bound to  a rational  number.   Rational  numbers
    include integers.


rraattiioonnaall((_@_T_e_r_m_, _-_N_u_m_e_r_a_t_o_r_, _-_D_e_n_o_m_i_n_a_t_o_r))
    True  if  _T_e_r_m  is  a  rational  number  with  given  _N_u_m_e_r_a_t_o_r  and
    _D_e_n_o_m_i_n_a_t_o_r.   The _N_u_m_e_r_a_t_o_r and _D_e_n_o_m_i_n_a_t_o_r are in  canonical form,
    which  means _D_e_n_o_m_i_n_a_t_o_r  is  a positive  integer and  there are  no
    common divisors between _N_u_m_e_r_a_t_o_r and _D_e_n_o_m_i_n_a_t_o_r.


nnuummbbeerr((_@_T_e_r_m))                                                     _[_I_S_O_]
    True if _T_e_r_m is bound to an integer or floating point number.


aattoomm((_@_T_e_r_m))                                                       _[_I_S_O_]
    True if _T_e_r_m is bound to an atom.


bblloobb((_@_T_e_r_m_, _?_T_y_p_e))
    True if _T_e_r_m is a _b_l_o_b of type _T_y_p_e.  See section ????.


ssttrriinngg((_@_T_e_r_m))
    True  if _T_e_r_m is bound  to a string.   Note that string here  refers
    to  the built-in  atomic  type string  as described  in section  ????.
    Starting  with version  7, the syntax  for a  string object is  text
    between  double quotes, such as "hello".   See also the  Prolog flag
    double_quotes.


aattoommiicc((_@_T_e_r_m))                                                     _[_I_S_O_]
    True  if _T_e_r_m is bound (i.e.,  not a variable) and is  not compound.
    Thus, atomic acts as if defined by:

    ____________________________________________________________________|                                                                    |
    | atomic(Term) :-                                                    |

    |         nonvar(Term),                                              |
    ||________\+_compound(Term).________________________________________ ||

    SWI-Prolog  defines the following atomic datatypes:   atom (atom/1),
    string  (string/1),   integer  (integer/1),  floating  point  number
    (float/1)  and blob  (blob/2).   In addition,  the symbol []  (empty
    list) is atomic, but not an atom.  See section ????.


ccoommppoouunndd((_@_T_e_r_m))                                                   _[_I_S_O_]
    True  if _T_e_r_m  is bound  to a  compound term.    See also  functor/3
    =../2, compound_name_arity/3 and compound_name_arguments/3.


ccaallllaabbllee((_@_T_e_r_m))                                                   _[_I_S_O_]
    True  if _T_e_r_m is  bound to  an atom or  a compound term.   This  was
    intended  as a type-test for arguments to call/1 and call/2..   Note
    that callable only tests  the _s_u_r_f_a_c_e _t_e_r_m.  Terms such as (22,true)
    are  considered callable, but  cause call/1 to  raise a type  error.
    Module-qualification  of meta-argument (see  meta_predicate/1)  using
    :/2  causes callable to succeed on any meta-argument.   Consider the
    program and query below:

    ____________________________________________________________________|                                                                    |
    | :- 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)__________________________________________ ||


ggrroouunndd((_@_T_e_r_m))                                                     _[_I_S_O_]
    True  if _T_e_r_m holds  no free  variables.   See also nonground/2  and
    term_variables/2.


ccyycclliicc__tteerrmm((_@_T_e_r_m))
    True  if _T_e_r_m contains cycles, i.e. is  an infinite term.   See also
    acyclic_term/1 and section ????.


aaccyycclliicc__tteerrmm((_@_T_e_r_m))                                                _[_I_S_O_]
    True  if  _T_e_r_m  does  not contain  cycles,  i.e.  can  be  processed
    recursively in finite time.  See also cyclic_term/1 and section ????.


44..77 CCoommppaarriissoonn aanndd UUnniiffiiccaattiioonn ooff TTeerrmmss

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

_?_T_e_r_m_1 = _?_T_e_r_m_2                                                   _[_I_S_O_]
    Unify  _T_e_r_m_1 with _T_e_r_m_2.   True  if the unification  succeeds.   For
    behaviour  on cyclic  terms see the  Prolog flag  occurs_check.    It
    acts as if defined by the following fact:

    ____________________________________________________________________|                                                                    |
    ||=(Term,_Term).____________________________________________________ ||


_@_T_e_r_m_1 \= _@_T_e_r_m_2                                                  _[_I_S_O_]
    Equivalent to \+Term1 = Term2.

    This predicate is  logically sound if its arguments are sufficiently
    instantiated.   In  other cases, such  as ?- X \= Y., the  predicate
    fails  although there are solutions.  This is due to  the incomplete
    nature of \+/1.

    To  make your programs work  correctly also in situations where  the
    arguments are not yet sufficiently instantiated, use dif/2 instead.


44..77..11 SSttaannddaarrdd OOrrddeerr ooff TTeerrmmss

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

 1. _V_a_r_i_a_b_l_e_s <_N_u_m_b_e_r_s <_S_t_r_i_n_g_s <_A_t_o_m_s <_C_o_m_p_o_u_n_d _T_e_r_m_s

 2. Variables are sorted by address.

 3. _N_u_m_b_e_r_s 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 iso  is defined, all  floating
    point numbers precede all integers.

 4. _S_t_r_i_n_g_s are compared alphabetically.

 5. _A_t_o_m_s are compared alphabetically.

 6. _C_o_m_p_o_u_n_d  terms are  first checked  on  their arity,  then on  their
    functor  name  (alphabetically)  and finally  recursively  on  their
    arguments, leftmost argument first.

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 sort/2  as well
as libraries that  reply on ordering such  as library assoc and  library
ordsets.  Obviously,  an established relation _A @< _B no longer  holds if
_A is unified  with e.g., a number.   Also unifying _A with _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  _a_t_t_r_i_b_u_t_e, see  section ????,  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 _f_i_r_s_t  attribute, i.e., further  manipulation
of the attribute list does _n_o_t change the `age'.

________________________________________________________________________|                                                                        |

|?- T = f(A,B), A @< B.                                                  |
|T = f(A, B).                                                            |
|                                                                        |
|?- T = f(A,B), put_attr(A, name, value), A @< B.                        |
|false.|________________________________________________________________ |      |

The  above implies  you _c_a_n  use  e.g., an  assoc (from  library  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.


_@_T_e_r_m_1 == _@_T_e_r_m_2                                                  _[_I_S_O_]
    True if _T_e_r_m_1 is  equivalent to _T_e_r_m_2.  A variable is only identical
    to a sharing variable.


_@_T_e_r_m_1 \== _@_T_e_r_m_2                                                 _[_I_S_O_]
    Equivalent to \+Term1 == Term2.


_@_T_e_r_m_1 @< _@_T_e_r_m_2                                                  _[_I_S_O_]
    True if _T_e_r_m_1 is before _T_e_r_m_2 in the standard order of terms.


_@_T_e_r_m_1 @=< _@_T_e_r_m_2                                                 _[_I_S_O_]
    True if both terms  are equal (==/2) or _T_e_r_m_1 is before _T_e_r_m_2 in the
    standard order of terms.


_@_T_e_r_m_1 @> _@_T_e_r_m_2                                                  _[_I_S_O_]
    True if _T_e_r_m_1 is after _T_e_r_m_2 in the standard order of terms.


_@_T_e_r_m_1 @>= _@_T_e_r_m_2                                                 _[_I_S_O_]
    True  if both terms are equal (==/2) or _T_e_r_m_1 is after _T_e_r_m_2  in the
    standard order of terms.


ccoommppaarree((_?_O_r_d_e_r_, _@_T_e_r_m_1_, _@_T_e_r_m_2))                                   _[_I_S_O_]
    Determine or test  the _O_r_d_e_r between two terms in the standard order
    of terms.  _O_r_d_e_r is one of <, >  or =, with the obvious meaning.


44..77..22 SSppeecciiaall uunniiffiiccaattiioonn aanndd ccoommppaarriissoonn pprreeddiiccaatteess

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

uunniiffyy__wwiitthh__ooccccuurrss__cchheecckk((_+_T_e_r_m_1_, _+_T_e_r_m_2))                             _[_I_S_O_]
    As  =/2, but  using _s_o_u_n_d  _u_n_i_f_i_c_a_t_i_o_n.   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.

    ____________________________________________________________________|                                                                    |
    | 1 ?- A = f(A).                                                     |

    | A = f(A).                                                          |
    | 2 ?- unify_with_occurs_check(A, f(A)).                             |
    ||false.____________________________________________________________ ||

    The  first statement creates a  _c_y_c_l_i_c _t_e_r_m, also called a  _r_a_t_i_o_n_a_l
    _t_r_e_e.    The second  executes logically sound  unification and  thus
    fails.   Note that the behaviour of unification through =/2  as well
    as implicit unification  in the head can be changed using the Prolog
    flag occurs_check.

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

    ____________________________________________________________________|                                                                    |
    | ?- 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).__________________________________________________ ||

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

    ____________________________________________________________________|                                                                    |
    ||unify_with_occurs_check(X,X)_:-_acyclic_term(X).__________________ ||


_+_T_e_r_m_1 =@= _+_T_e_r_m_2
    True  if  _T_e_r_m_1 is  a  _v_a_r_i_a_n_t of  (or _s_t_r_u_c_t_u_r_a_l_l_y  _e_q_u_i_v_a_l_e_n_t  to)
    _T_e_r_m_2.   Testing  for a variant  is weaker than equivalence  (==/2),
    but  stronger  than unification  (=/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.  Examples:

          1       a =@= A       false
          2       A =@= B       true
          3  x(A,A) =@= x(B,C)  false
          4  x(A,A) =@= x(B,B)  true
          5  x(A,A) =@= x(A,B)  false

          6  x(A,B) =@= x(C,D)  true
          7  x(A,B) =@= x(B,A)  true
          8  x(A,B) =@= x(C,A)  true

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

    ____________________________________________________________________|                                                                    |
    | A =@= B :-                                                         |
    |         copy_term(A, Ac),                                          |
    |         copy_term(B, Bc),                                          |
    |         numbervars(Ac, 0, N),                                      |
    |         numbervars(Bc, 0, N),                                      |

    ||________Ac_==_Bc._________________________________________________ ||

    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  ==/2, both  on  success and  (early)
    failure.

    This  predicate is known by the name variant/2 in some  other Prolog
    systems.    Be aware  of possible  differences in  semantics if  the
    arguments contain attributed variables or share variables.


_+_T_e_r_m_1 \=@= _+_T_e_r_m_2
    Equivalent to `\+Term1 =@= Term2'.  See =@=/2 for details.


ssuubbssuummeess__tteerrmm((_@_G_e_n_e_r_i_c_, _@_S_p_e_c_i_f_i_c))                                 _[_I_S_O_]
    True  if _G_e_n_e_r_i_c can be made equivalent to _S_p_e_c_i_f_i_c by  only binding
    variables  in  _G_e_n_e_r_i_c.   The  current  implementation performs  the
    unification  and ensures that  the variable set  of _S_p_e_c_i_f_i_c is  not
    changed  by the unification.   On success, the bindings are  undone.
    This predicate respects constraints.


tteerrmm__ssuubbssuummeerr((_+_S_p_e_c_i_a_l_1_, _+_S_p_e_c_i_a_l_2_, _-_G_e_n_e_r_a_l))
    _G_e_n_e_r_a_l  is  the most  specific  term that  is a  generalisation  of
    _S_p_e_c_i_a_l_1 and _S_p_e_c_i_a_l_2.  The implementation can handle cyclic terms.


uunniiffiiaabbllee((_@_X_, _@_Y_, _-_U_n_i_f_i_e_r))
    If  _X and _Y  can unify,  unify _U_n_i_f_i_e_r with  a list of  _V_a_r = _V_a_l_u_e,
    representing  the  bindings required  to make  _X  and _Y  equivalent.
    This  predicate can handle cyclic  terms.  Attributed variables  are
    handled as normal variables.  Associated hooks are _n_o_t executed.


??==((_@_T_e_r_m_1_, _@_T_e_r_m_2))
    Succeeds  if  the  syntactic equality  of  _T_e_r_m_1  and _T_e_r_m_2  can  be
    decided  safely,  i.e.  if the  result  of Term1 == Term2  will  not
    change  due to further instantiation of either term.  It  behaves as
    if defined by ?=(X,Y) :- \+ unifiable(X,Y,[_|_]).


44..88 CCoonnttrrooll PPrreeddiiccaatteess

The predicates of  this section implement control structures.   Normally
the constructs in this  section, except for repeat/0, are  translated by
the compiler.   Please  note that complex goals  passed as arguments  to
meta-predicates such  as 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. one_character_atoms/1 in the example below) and make
a call to this simple predicate.

________________________________________________________________________|                                                                        |
|one_character_atoms(As) :-                                              |

||_______findall(A,_(current_atom(A),_atom_length(A,_1)),_As).__________ ||


ffaaiill                                                              _[_I_S_O_]
    Always  fail.   The  predicate fail/0  is translated  into a  single
    virtual machine instruction.


ffaallssee                                                             _[_I_S_O_]
    Same as fail, but the name has a more declarative connotation.


ttrruuee                                                              _[_I_S_O_]
    Always  succeed.  The predicate  true/0 is translated into a  single
    virtual machine instruction.


rreeppeeaatt                                                            _[_I_S_O_]
    Always succeed, provide an infinite number of choice points.


!                                                                 _[_I_S_O_]
    Cut.     Discard  all  choice  points  created  since  entering  the
    predicate  in which the cut appears.  In other words, _c_o_m_m_i_t  to the
    clause  in which  the  cut appears  _a_n_d 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 (call/1)
    only  affect choice  points created by  the meta-called  term.   The
    following control structures are transparent to the cut:   ;/2, ->/2
    and *->/2 .  Cuts appearing in the _c_o_n_d_i_t_i_o_n part of ->/2 and  *->/2
    are  opaque to the cut.   The table below explains the scope  of the
    cut  with examples.    _P_r_u_n_e_s  here means  ``prunes X  choice point
    created by X''.

            t0 :- (a, !, b).               % prunes a/0 and t0/0
            t1 :- (a, !, fail ; b).        % prunes a/0 and t1/0
            t2 :- (a -> b, !  ; c).        % prunes b/0 and t2/0
            t3 :- call((a, !, fail ; b)).  % prunes a/0
            t4 :- \+(a, !, fail).          % prunes a/0


_:_G_o_a_l_1 , _:_G_o_a_l_2                                                   _[_I_S_O_]
    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):

    ____________________________________________________________________|                                                                    |
    ||Goal1,_Goal2_:-_Goal1,_Goal2._____________________________________ ||


_:_G_o_a_l_1 ; _:_G_o_a_l_2                                                   _[_I_S_O_]
    The `or' predicate is defined as:

    ____________________________________________________________________|                                                                    |
    | Goal1 ; _Goal2 :- Goal1.                                           |
    ||_Goal1_;_Goal2_:-_Goal2.__________________________________________ ||


_:_G_o_a_l_1 | _:_G_o_a_l_2
    Equivalent  to ;/2.    Retained for compatibility  only.   New  code
    should use ;/2.


_:_C_o_n_d_i_t_i_o_n -> _:_A_c_t_i_o_n                                             _[_I_S_O_]
    If-then  and  If-Then-Else.    The  ->/2  construct commits  to  the
    choices  made  at  its  left-hand  side,  destroying  choice  points
    created  inside the  clause (by  ;/2), or  by goals  called by  this
    clause.   Unlike !/0, the choice  point of the predicate as  a whole
    (due  to multiple clauses)  is nnoott destroyed.   The combination  ;/2
    and ->/2  acts as if defined as:

    ____________________________________________________________________|                                                                    |
    | If -> Then; _Else :- If, !, Then.                                  |
    | If -> _Then; Else :- !, Else.                                      |

    ||If_->_Then_:-_If,_!,_Then.________________________________________ ||

    Please  note that (If -> Then) acts  as (If -> Then ; ffaaiill),  making
    the  construct _f_a_i_l if the condition fails.  This  unusual semantics
    is part of the ISO and all de-facto Prolog standards.

    Please  note that (if->then;else)  is read as ((if->then);else)  and
    that  the _c_o_m_b_i_n_e_d semantics of this syntactic construct  as defined
    above  is _d_i_f_f_e_r_e_n_t from  the simple nesting  of the two  individual
    constructs,  i.e., the  semantics of ->/2  _c_h_a_n_g_e_s when embedded  in
    ;/2.  See also once/1.


_:_C_o_n_d_i_t_i_o_n *-> _:_A_c_t_i_o_n _; _:_E_l_s_e
    This  construct implements  the so-called `soft-cut'.   The  control
    is  defined as follows:   If _C_o_n_d_i_t_i_o_n succeeds  at least once,  the
    semantics  is the same  as (_C_o_n_d_i_t_i_o_n, _A_c_t_i_o_n).   If _C_o_n_d_i_t_i_o_n  does
    not  succeed, the  semantics is that  of (\+ _C_o_n_d_i_t_i_o_n,  _E_l_s_e).   In
    other  words, if _C_o_n_d_i_t_i_o_n succeeds at least once, simply  behave as
    the  conjunction of  _C_o_n_d_i_t_i_o_n and _A_c_t_i_o_n,  otherwise execute  _E_l_s_e.
    The  construct is  known under the  name if/3  in some other  Prolog
    implementations.

    The  construct _A *-> _B, i.e., without an _E_l_s_e branch,  is translated
    as the normal conjunction _A, _B.

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

    ____________________________________________________________________|                                                                    |
    | optional(Goal) :-                                                  |

    |     (   Goal                                                       |
    |     *-> true                                                       |
    |     ;   true                                                       |
    ||____).____________________________________________________________ ||

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

\+ _:_G_o_a_l                                                          _[_I_S_O_]
    True  if `Goal' cannot  be proven (mnemonic:   + refers to  _p_r_o_v_a_b_l_e
    and  the backslash  (\)  is normally  used to  indicate negation  in
    Prolog).


44..99 MMeettaa--CCaallll PPrreeddiiccaatteess

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.


ccaallll((_:_G_o_a_l))                                                       _[_I_S_O_]
    Invoke  _G_o_a_l as a  goal.   Note that clauses  may have variables  as
    subclauses, which is identical to call/1.


ccaallll((_:_G_o_a_l_, _+_E_x_t_r_a_A_r_g_1_, _._._.))                                      _[_I_S_O_]
    Append  _E_x_t_r_a_A_r_g_1_, _E_x_t_r_a_A_r_g_2_,  _._._.   to  the argument  list of  _G_o_a_l
    and  call the result.   For  example, call(plus(1), 2, X) will  call
    plus(1, 2, X), binding _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  current_predicate/1,
    predicate_property/2,  etc.    Higher  arities  are handled  by  the
    compiler  and runtime system, but the predicates are  not accessible
    for inspection.


aappppllyy((_:_G_o_a_l_, _+_L_i_s_t))
    Append  the  members of  _L_i_s_t  to the  arguments  of _G_o_a_l  and  call
    the  resulting term.    For example:   apply(plus(1), [2, X])  calls
    plus(1, 2, X).   New code  should use call/[2..]   if the length  of
    _L_i_s_t is fixed.


nnoott((_:_G_o_a_l))
    True  if _G_o_a_l cannot  be proven.   Retained for compatibility  only.
    New code should use \+/1.


oonnccee((_:_G_o_a_l))                                                       _[_I_S_O_]
    Make  a possibly _n_o_n_d_e_t  goal _s_e_m_i_d_e_t, i.e.,  succeed at most  once.
    Defined as:

    ____________________________________________________________________|                                                                    |
    | once(Goal) :-                                                      |
    ||____call(Goal),_!.________________________________________________ ||

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

    ____________________________________________________________________|                                                                    |

    | 1) a :- once((b, c)), d.                                           |
    ||2)_a_:-_b,_c_->_d.________________________________________________ ||


iiggnnoorree((_:_G_o_a_l))
    Calls  _G_o_a_l  as once/1,  but succeeds,  regardless  of whether  _G_o_a_l
    succeeded or not.  Defined as:

    ____________________________________________________________________|                                                                    |
    | ignore(Goal) :-                                                    |
    |         Goal, !.                                                   |
    ||ignore(_).________________________________________________________ ||


ccaallll__wwiitthh__ddeepptthh__lliimmiitt((_:_G_o_a_l_, _+_L_i_m_i_t_, _-_R_e_s_u_l_t))
    If  _G_o_a_l can be proven  without recursion deeper than _L_i_m_i_t  levels,
    call_with_depth_limit/3 succeeds,  binding  _R_e_s_u_l_t  to  the  deepest
    recursion  level  used  during the  proof.    Otherwise,  _R_e_s_u_l_t  is
    unified  with depth_limit_exceeded  if the limit was exceeded  during
    the  proof,  or the  entire predicate  fails if  _G_o_a_l fails  without
    exceeding _L_i_m_i_t.

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

    ____________________________________________________________________|                                                                    |
    | repeat.                                                            |

    | repeat :-                                                          |
    ||________repeat.___________________________________________________ ||

    As  a result,  call_with_depth_limit/3may  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   re-
    alise   techniques   like   _i_t_e_r_a_t_i_v_e   _d_e_e_p_e_n_i_n_g.        See   also
    call_with_inference_limit/3.   It was  implemented after  discussion
    with Steve Moyle smoyle@ermine.ox.ac.uk.


ccaallll__wwiitthh__iinnffeerreennccee__lliimmiitt((_:_G_o_a_l_, _+_L_i_m_i_t_, _-_R_e_s_u_l_t))
    Equivalent  to call(_G_o_a_l), but limits  the number of inferences  _f_o_r
    _e_a_c_h _s_o_l_u_t_i_o_n _o_f _G_o_a_l..  Execution may terminate as follows:

      o  If  _G_o_a_l does  _n_o_t  terminate  before the  inference  limit  is
         exceeded, _G_o_a_l  is aborted  by injecting  the exception  infer-
         ence_limit_exceeded  into its execution.   After termination  of
         _G_o_a_l, _R_e_s_u_l_t is unified with the atom inference_limit_exceeded.
         _O_t_h_e_r_w_i_s_e,

      o  If _G_o_a_l fails, call_with_inference_limit/3fails.

      o  If _G_o_a_l  succeeds _w_i_t_h_o_u_t  _a _c_h_o_i_c_e  _p_o_i_n_t,  _R_e_s_u_l_t is  unified
         with !.

      o  If _G_o_a_l succeeds  _w_i_t_h _a _c_h_o_i_c_e  _p_o_i_n_t, _R_e_s_u_l_t is unified  with
         true.

      o  If  _G_o_a_l   throws  an   exception,   call_with_inference_limit/3
         re-throws the exception.

    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 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 call_with_depth_limit/3 and call_with_time_limit/2.


sseettuupp__ccaallll__cclleeaannuupp((_:_S_e_t_u_p_, _:_G_o_a_l_, _:_C_l_e_a_n_u_p))
    Calls  (once(Setup), Goal).     If  _S_e_t_u_p  succeeds,   _C_l_e_a_n_u_p  will
    be  called  exactly   once  after  _G_o_a_l  is  finished:    either  on
    failure,  deterministic  success,  commit, or  an  exception.    The
    execution  of _S_e_t_u_p is  protected from asynchronous interrupts  like
    call_with_time_limit/2 (package clib) or  thread_signal/2.   In  most
    uses,  _S_e_t_u_p will  perform temporary  side-effects required by  _G_o_a_l
    that are finally undone by _C_l_e_a_n_u_p.

    Success  or failure  of _C_l_e_a_n_u_p  is  ignored, and  choice points  it
    created are destroyed  (as once/1).  If _C_l_e_a_n_u_p 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 _C_l_e_a_n_u_p
    was triggered by an exception the rules are described in section ????

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

    ____________________________________________________________________|                                                                    |
    | 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                                               |
    ||________).________________________________________________________ ||

    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 member/2.    Without setup_call_cleanup/3
    there  is  no way  to  gain  control if  the  choice point  left  by
    repeat/0 is removed by a cut or an exception.

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

    ____________________________________________________________________|                                                                    |
    | ?- setup_call_cleanup(true,(X=1;X=2), Det=yes).                    |
    |                                                                    |
    | X = 1 ;                                                            |

    |                                                                    |
    | X = 2,                                                             |
    ||Det_=_yes_;_______________________________________________________ ||

    This  predicate is  under consideration for  inclusion into the  ISO
    standard.   For compatibility with other Prolog  implementations see
    call_cleanup/2.


sseettuupp__ccaallll__ccaattcchheerr__cclleeaannuupp((_:_S_e_t_u_p_, _:_G_o_a_l_, _+_C_a_t_c_h_e_r_, _:_C_l_e_a_n_u_p))
    Similar  to setup_call_cleanup(_S_e_t_u_p_, _G_o_a_l_, _C_l_e_a_n_u_p)  with additional
    information  on the reason  for calling _C_l_e_a_n_u_p.   Prior to  calling
    _C_l_e_a_n_u_p, _C_a_t_c_h_e_r unifies  with the termination code (see below).  If
    this unification fails, _C_l_e_a_n_u_p is _n_o_t called.

    eexxiitt
         _G_o_a_l succeeded without leaving any choice points.

    ffaaiill
         _G_o_a_l failed.

    !
         _G_o_a_l 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).

    eexxcceeppttiioonn((_E_x_c_e_p_t_i_o_n))
         _G_o_a_l raised the given _E_x_c_e_p_t_i_o_n.

    eexxtteerrnnaall__eexxcceeppttiioonn((_E_x_c_e_p_t_i_o_n))
         _G_o_a_l succeeded with choice  points and these are now  discarded
         due to an exception.  For example:

         _______________________________________________________________|                                                               |

         |?- setup_call_catcher_cleanup(true, (X=1;X=2),                 |
         |                              Catcher, writeln(Catcher)),      |
         |   throw(ball).                                                |
         |external_exception(ball)                                       |
         |ERROR:|Unhandled_exception:_Unknown_message:_ball_____________ |      |


ccaallll__cclleeaannuupp((_:_G_o_a_l_, _:_C_l_e_a_n_u_p))
    Same  as setup_call_cleanup(_t_r_u_e_, _G_o_a_l_,  _C_l_e_a_n_u_p).  This is  provided
    for  compatibility with  a  number of  other Prolog  implementations
    only.     Do not  use  call_cleanup/2 if  you  perform  side-effects
    prior  to calling  that will  be undone by  _C_l_e_a_n_u_p.   Instead,  use
    setup_call_cleanup/3 with an  appropriate first argument to  perform
    those side-effects.


ccaallll__cclleeaannuupp((_:_G_o_a_l_, _+_C_a_t_c_h_e_r_, _:_C_l_e_a_n_u_p))
    Same  as  setup_call_catcher_cleanup(_t_r_u_e_, _G_o_a_l_,  _C_a_t_c_h_e_r_,  _C_l_e_a_n_u_p).
    The same warning as for call_cleanup/2 applies.


44..1100 DDeelliimmiitteedd ccoonnttiinnuuaattiioonnss

The  predicates reset/3  and shift/1  implement _d_e_l_i_m_i_t_e_d  _c_o_n_t_i_n_u_a_t_i_o_n_s
for Prolog.    Delimited continuation  for Prolog is  described in  [??].
The  mechanism  allows for  proper  _c_o_r_o_u_t_i_n_e_s,  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 chapter ????.

The  suspension  mechanism   provided  by  delimited  continuations   is
suitable for the implementation of _t_a_b_l_i_n_g [??], see library tabling.


rreesseett((_:_G_o_a_l_, _?_B_a_l_l_, _-_C_o_n_t_i_n_u_a_t_i_o_n))
    Call  _G_o_a_l.  If _G_o_a_l calls  shift/1 and the argument of  shift/1 can
    be  unified with _B_a_l_l,  shift/1 causes  reset/3 to return,  unifying
    _C_o_n_t_i_n_u_a_t_i_o_n  with a  goal  that represents  the _c_o_n_t_i_n_u_a_t_i_o_n  after
    shift/1.   In other  words, meta-calling _C_o_n_t_i_n_u_a_t_i_o_n completes  the
    execution  where shift  left it.   If  _G_o_a_l does  not call  shift/1,
    _C_o_n_t_i_n_u_a_t_i_o_n are unified with the integer 0 (zero).


sshhiifftt((_+_B_a_l_l))
    Abandon  the execution  of the  current goal,  returning control  to
    just  _a_f_t_e_r the matching reset/3 call.   This is similar to  throw/1
    except  that (1)  nothing is `undone'  and (2)  the 3th argument  of
    reset/3  is unified  with the  _c_o_n_t_i_n_u_a_t_i_o_n, which  allows the  code
    calling reset/3 to _r_e_s_u_m_e the current goal.


44..1111 EExxcceeppttiioonn hhaannddlliinngg

The predicates  catch/3 and  throw/1 provide ISO  compliant raising  and
catching of exceptions.


ccaattcchh((_:_G_o_a_l_, _+_C_a_t_c_h_e_r_, _:_R_e_c_o_v_e_r))                                  _[_I_S_O_]
    Behaves  as call/1 if  no exception is  raised when executing  _G_o_a_l.
    If  an exception is  raised using throw/1  while _G_o_a_l executes,  and
    the  _G_o_a_l is the innermost goal  for which _C_a_t_c_h_e_r unifies with  the
    argument  of throw/1, all choice  points generated by _G_o_a_l are  cut,
    the  system backtracks to the start of catch/3 while  preserving the
    thrown exception term, and _R_e_c_o_v_e_r is called as in call/1.

    The  overhead of  calling a  goal through catch/3  is comparable  to
    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 prolog_stack
    based  on  the  prolog_exception_hook/4 hook  predicate  to  rewrite
    exceptions.


tthhrrooww((_+_E_x_c_e_p_t_i_o_n))                                                 _[_I_S_O_]
    Raise  an exception.   The  system looks  for the innermost  catch/3
    ancestor  for which _E_x_c_e_p_t_i_o_n unifies  with the _C_a_t_c_h_e_r argument  of
    the catch/3 call.  See catch/3 for details.

    ISO  demands that  throw/1 make  a copy  of _E_x_c_e_p_t_i_o_n,  walk up  the
    stack  to a catch/3  call, backtrack  and try to  unify the copy  of
    _E_x_c_e_p_t_i_o_n  with _C_a_t_c_h_e_r.   SWI-Prolog  delays backtracking until  it
    actually  finds a  matching 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
    catch/3  goal.   This approach  can lead  to different behaviour  if
    _G_o_a_l  and _C_a_t_c_h_e_r of catch/3 call shared variables.  We  assume this
    to  be highly unlikely and could not think of a scenario  where this
    is useful.

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

     1.  If  the  exception  is  of  the  form  error(_F_o_r_m_a_l_,  _I_m_p_l_e_m_e_n_-
         _t_a_t_i_o_n_D_e_f_i_n_e_d),  try   to  raise  the  exception  without   the
         _I_m_p_l_e_m_e_n_t_a_t_i_o_n_D_e_f_i_n_e_d part.

     2.  Try to raise error(resource_error_(_s_t_a_c_k_)_, _g_l_o_b_a_l).

     3.  Abort (see abort/0).

    If  an exception is  raised in a call-back  from C (see chapter  ????)
    and  not caught in the same  call-back, PL_next_solution()fails  and
    the exception context can be retrieved using PL_exception().


44..1111..11 UUrrggeennccyy ooff eexxcceeppttiioonnss

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

  o The  predicate 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 _u_r_g_e_n_t exception is  propagated into
    the environment.

  o 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  '$aborted', also  raised by  abort/0.   As  no
    stack  space is required for processing this atomic  exception, this
    should always succeed.

  o Certain  _c_a_l_l_b_a_c_k  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 _c_a_l_l_b_a_c_k  subject  to  this  issue
    are  prolog_event_hook/1(supporting  e.g., the graphical  debugger),
    prolog_exception_hook/4  (rewriting  exceptions,  e.g.,   by  adding
    context)  and print_message/2 when called  from the core  facilities
    such  as the internal  debugger.  As  with setup_call_cleanup/3,  the
    most _u_r_g_e_n_t exception is preserved.

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

 1. '$aborted' (abort/0)

 2. time_limit_exceeded (call_with_time_limit/2)

 3. error(resource_error_(_R_e_s_o_u_r_c_e_)_, _C_o_n_t_e_x_t)

 4. error(_F_o_r_m_a_l_, _C_o_n_t_e_x_t)

 5. All other exceptions

NNoottee

The above  resolution is not  described in  the ISO standard.   This  is
not needed either because  ISO does not specify setup_call_cleanup/3 and
does  not deal  with environment  management issues  such as  (debugger)
callbacks.     Neither does  it  define  abort/0  or  timeout  handling.
Notably 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 _c_l_e_a_n_u_p  _h_a_n_d_l_e_r of
catch/3 into call_cleanup(_H_a_n_d_l_e_r_, _a_b_o_r_t).


44..1111..22 DDeebbuuggggiinngg aanndd eexxcceeppttiioonnss

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 debug_on_errorwas 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 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
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 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
debug_on_error:

  o _c_u_r_r_e_n_t___p_r_o_l_o_g___f_l_a_g_(_d_e_b_u_g___o_n___e_r_r_o_r_, _f_a_l_s_e_)
    The  exception does  not trap the  debugger and  is returned to  the
    foreign  routine  calling Prolog,  where it  can  be accessed  using
    PL_exception().  This is the default.

  o _c_u_r_r_e_n_t___p_r_o_l_o_g___f_l_a_g_(_d_e_b_u_g___o_n___e_r_r_o_r_, _t_r_u_e_)
    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.

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

44..1111..33 TThhee eexxcceeppttiioonn tteerrmm

Built-in  predicates  generate exceptions  using  a  term  error(_F_o_r_m_a_l_,
_C_o_n_t_e_x_t).    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
context(_N_a_m_e_/_A_r_i_t_y_,  _M_e_s_s_a_g_e), where _N_a_m_e/_A_r_i_t_y  describes the  built-in
predicate  that raised  the error,  and _M_e_s_s_a_g_e  provides an  additional
description of the error.  Any part of this structure  may be a variable
if no information was present.


44..1111..44 PPrriinnttiinngg mmeessssaaggeess

The  predicate 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
print_message/2 is to  print error messages from  exceptions.  The  code
below prints  errors encountered during the  execution of _G_o_a_l,  without
further propagating the exception and without starting the debugger.

________________________________________________________________________|                                                                        |
|        ...,                                                            |

|        catch(Goal, E,                                                  |
|              ( print_message(error, E),                                |
|                fail                                                    |
|              )),                                                       |
||_______...____________________________________________________________ ||

Another common  use is  to define  message_hook/3 for printing  messages
that are normally _s_i_l_e_n_t, suppressing messages,  redirecting messages or
make something happen in addition to printing the message.


pprriinntt__mmeessssaaggee((_+_K_i_n_d_, _+_T_e_r_m))
    The  predicate print_message/2 is used  by the system and  libraries
    to  print  messages.   _K_i_n_d  describes the  nature  of the  message,
    while  _T_e_r_m is a Prolog term  that describes the content.   Printing
    messages  through  this indirection  instead  of using  format/3  to
    the  stream 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 message_hook/3) and
    creating  language specific  versions  of the  messages.   See  also
    section ????.  The following message kinds are known:

    bbaannnneerr
         The system banner message.   Banner messages can  be suppressed
         by setting the Prolog flag verbose to silent.

    ddeebbuugg((_T_o_p_i_c))
         Message from library(debug).  See debug/3.

    eerrrroorr
         The  message indicates  an  erroneous  situation.    This  kind
         is used  to  print uncaught  exceptions of  type  error(_F_o_r_m_a_l_,
         _C_o_n_t_e_x_t).  See section introduction (section ????).

    hheellpp
         User requested help message, for example after  entering `h' or
         `?'  to a prompt.

    iinnffoorrmmaattiioonn
         Information that  is requested  by  the user.    An example  is
         statistics/0.

    iinnffoorrmmaattiioonnaall
         Typically messages  of events are  progres that are  considered
         useful to  a developer.   Such  messages can  be suppressed  by
         setting the Prolog flag verbose to silent.

    ssiilleenntt
         Message that is normally not printed.   Applications may define
         message_hook/3 to act upon such messages.

    ttrraaccee
         Messages from the (command line) tracer.

    wwaarrnniinngg
         The message indicates something dubious that is  not considered
         fatal.       For   example,   discontiguous   predicates   (see
         discontiguous/1).

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

    The  print_message/2  predicate  and  its  rules  are  in  the  file
    <_p_l_h_o_m_e>/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  section ????  for a  deeper discussion  and
    examples.

    See also message_to_string/2.


pprriinntt__mmeessssaaggee__lliinneess((_+_S_t_r_e_a_m_, _+_P_r_e_f_i_x_, _+_L_i_n_e_s))
    Print a  message (see print_message/2) that has  been translated to a
    list of message elements.  The elements of this list are:

    <_F_o_r_m_a_t>--<_A_r_g_s>
         Where  _F_o_r_m_a_t  is  an  atom  and  _A_r_g_s  is  a  list  of  format
         arguments.  Handed to format/3.

    fflluusshh
         If this  appears as the  last element,  _S_t_r_e_a_m is flushed  (see
         flush_output/1) and  no  final  newline  is generated.     This
         is  combined  with  a  subsequent  message  that   starts  with
         at_same_line to complete the line.

    aatt__ssaammee__lliinnee
         If this  appears as  first element,  no prefix  is printed  for
         the first line  and the line position  is not forced to 0  (see
         format/1, ~N).

    aannssii((_+_A_t_t_r_i_b_u_t_e_s_, _+_F_o_r_m_a_t_, _+_A_r_g_s))
         This message  may  be intercepted  by means  of  the hook  pro-
         log:message_line_element/2.   The  library ansi_term  implements
         this  hook  to  achieve  coloured  output.     If   it  is  not
         intercepted it invokes format(_S_t_r_e_a_m_, _F_o_r_m_a_t_, _A_r_g_s).

    nnll
         A new line is started.  If the message is  not complete, _P_r_e_f_i_x
         is printed before the remainder of the message.

    bbeeggiinn((_K_i_n_d_, _V_a_r))
    eenndd((_V_a_r))
         The entire message is  headed by begin(_K_i_n_d_, _V_a_r) and  ended by
         end(_V_a_r).  This feature is used  by, e.g., library ansi_term to
         colour entire messages.

    <_F_o_r_m_a_t>
         Handed to format/3 as  format(_S_t_r_e_a_m_, _F_o_r_m_a_t_, _[_]).   Deprecated
         because it  is ambiguous  if _F_o_r_m_a_t  collides with  one of  the
         atomic commands.

    See also print_message/2 and message_hook/3.


mmeessssaaggee__hhooookk((_+_T_e_r_m_, _+_K_i_n_d_, _+_L_i_n_e_s))
    Hook  predicate that may be defined in the module user  to intercept
    messages  from  print_message/2.    _T_e_r_m  and _K_i_n_d  are the  same  as
    passed to  print_message/2.  _L_i_n_e_s is a  list of format statements as
    described with print_message_lines/3.  See also message_to_string/2.

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

tthhrreeaadd__mmeessssaaggee__hhooookk((_+_T_e_r_m_, _+_K_i_n_d_, _+_L_i_n_e_s))
    As  message_hook/3,  but this  predicate  is  local to  the  calling
    thread   (see  thread_local/1).      This  hook  is  called   _b_e_f_o_r_e
    message_hook/3.    The  `pre-hook'  is  indented to  catch  messages
    they  may be produced by  calling some goal without affecting  other
    threads.


mmeessssaaggee__pprrooppeerrttyy((_+_K_i_n_d_, _?_P_r_o_p_e_r_t_y))
    This  hook can be  used to define  additional message kinds and  the
    way they are displayed.  The following properties are defined:

    ccoolloorr((_-_A_t_t_r_i_b_u_t_e_s))
         Print  message   using   ANSI  terminal   attributes.       See
         ansi_format/3 for details.   Here is an example, printing  help
         messages in blue:

         _______________________________________________________________|                                                               |

         |:- multifile user:message_property/2.                          |
         |                                                               |
         |user:message_property(help,|color([fg(blue)]))._______________ |                           |

    pprreeffiixx((_-_P_r_e_f_i_x))
         Prefix printed before  each line.   This argument is handed  to
         format/3.  The  default is '~N'. For example, messages  of kind
         warning use '~NWarning: '.

    llooccaattiioonn__pprreeffiixx((_+_L_o_c_a_t_i_o_n_, _-_F_i_r_s_t_P_r_e_f_i_x_, _-_C_o_n_t_i_n_u_e_P_r_e_f_i_x))
         Used for printing messages  that are related to a  source loca-
         tion.   Currently, _L_o_c_a_t_i_o_n is a  term _F_i_l_e:_L_i_n_e.   _F_i_r_s_t_P_r_e_f_i_x
         is the  prefix for the  first line  and _-_C_o_n_t_i_n_u_e_P_r_e_f_i_x is  the
         prefix for continuation  lines.   For example, the default  for
         errors is

         _______________________________________________________________|                                                               |
         |location_prefix(File:Line,                                     |
         ||_______________'~NERROR:_~w:~d:'-[File,Line],_'~N\t')).______ ||

    ssttrreeaamm((_-_S_t_r_e_a_m))
         Stream to which to print the message.  Default is user_error.

    wwaaiitt((_-_S_e_c_o_n_d_s))
         Amount of time to wait after printing the message.   Default is
         not to wait.


pprroolloogg::mmeessssaaggee__lliinnee__eelleemmeenntt((_+_S_t_r_e_a_m_, _+_T_e_r_m))
    This  hook is called to print  the individual elements of a  message
    from  print_message_lines/3.    This hook  is used  by e.g.,  library
    ansi_term to colour messages on ANSI-capable terminals.


mmeessssaaggee__ttoo__ssttrriinngg((_+_T_e_r_m_, _-_S_t_r_i_n_g))
    Translates a message term into a string object (see section ????).


vveerrssiioonn
    Write  the SWI-Prolog banner message as well as  additional messages
    registered  using version/1.    This is  the default  _i_n_i_t_i_a_l_i_z_a_t_i_o_n
    _g_o_a_l which can be modified using -g.


vveerrssiioonn((_+_M_e_s_s_a_g_e))
    Register  additional messages  to  be printed  by 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.


44..1111..44..11 PPrriinnttiinngg ffrroomm lliibbrraarriieess

Libraries should _n_o_t  use 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 section ????  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 print_message/2.  The first argument is the _l_e_v_e_l.   The supported
levels  are described  with print_message/2.    Libraries typically  use
informational and  warning, while  libraries should  use exceptions  for
errors (see throw/1, type_error/2, etc.).

The  second  argument is  an  arbitrary  Prolog term  that  carries  the
information  of the  message,  but  _n_o_t 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 http_open/3).  The library wants  to print
the progress  after each  downloaded file.   The  code below  is a  good
skeleton:

________________________________________________________________________|                                                                        |
|download_urls(List) :-                                                  |
|        length(List, Total),                                            |
|        forall(nth1(I, List, URL),                                      |

|               (   download_url(URL),                                   |
|                   print_message(informational,                         |
||________________________________download_url(URL,_I,_Total))))._______ ||

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 print_message_lines/3 describes  the
elements that may appear in the output list.

________________________________________________________________________|                                                                        |
|:- 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]_].___ ||

A _u_s_e_r  of the library  may define rules for  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.

________________________________________________________________________|                                                                        |
|:- multifile user:message_hook/3.                                       |
|                                                                        |
|message_hook(download_url(URL, I, Total), _Kind, _Lines) :-             |
||_______<send_this_information_to_a_GUI_component>_____________________ ||

In addition, using the command line option -q, the  user can disable all
_i_n_f_o_r_m_a_t_i_o_n_a_l messages.


44..1122 HHaannddlliinngg ssiiggnnaallss

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 section ????).

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).


oonn__ssiiggnnaall((_+_S_i_g_n_a_l_, _-_O_l_d_, _:_N_e_w))
    Determines  the reaction on  _S_i_g_n_a_l.   _O_l_d is  unified with the  old
    behaviour, while the behaviour  is switched to _N_e_w.  As with similar
    environment  control  predicates,  the  current value  is  retrieved
    using on_signal(Signal, Current, Current).

    The  action  description  is  an  atom  denoting  the  name  of  the
    predicate  that will be called if _S_i_g_n_a_l arrives.   on_signal/3 is a
    meta-predicate, which implies that <_M_o_d_u_l_e>:<_N_a_m_e>  refers to <_N_a_m_e>/1
    in  module <_M_o_d_u_l_e>.  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.   throw implies  Prolog
    will  map  the  signal  onto  a Prolog  exception  as  described  in
    section  ????.   default  resets the  handler to  the settings  active
    before SWI-Prolog manipulated the handler.

    Signals  bound   to  a  foreign  function  through  PL_signal()  are
    reported using the term $foreign_function(_A_d_d_r_e_s_s).

    After  receiving a signal mapped to throw, the exception  raised has
    the following structure:

         error(signal(<SigName>, <SigNum>), <_C_o_n_t_e_x_t>)

    The  signal  names are  defined  by the  POSIX standard  as  symbols
    of  the form  SIG<SIGNAME>.   The Prolog  name for a  signal is  the
    lowercase version  of <SIGNAME>.  The predicate current_signal/3 may
    be used to map between names and signals.

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

ccuurrrreenntt__ssiiggnnaall((_?_N_a_m_e_, _?_I_d_, _?_H_a_n_d_l_e_r))
    Enumerate  the  currently defined  signal  handling.   _N_a_m_e  is  the
    signal  name,  _I_d is  the numerical  identifier and  _H_a_n_d_l_e_r is  the
    currently defined handler (see on_signal/3).


pprroolloogg__aalleerrtt__ssiiggnnaall((_?_O_l_d_, _+_N_e_w))
    Query  or set the  signal used to  unblock blocking system calls  on
    Unix  systems and process  pending Prolog signals.   The default  is
    SIGUSR2.  See also --sigalert.


44..1122..11 NNootteess oonn ssiiggnnaall hhaannddlliinngg

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

  o _P_o_r_t_a_b_i_l_i_t_y
    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.    Installing  a  signal
    outside  the limited set of supported signals in  MS-Windows crashes
    the application.

  o _S_a_f_e_t_y
    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  throw are  unsafe.   Handlers defined  to call  a predicate  are
    safe.   Note that the  predicate can call throw/1, but  the delivery
    is delayed until Prolog is in a safe state.

    The  C-interface  described   in  section  ????  provides  the  option
    PL_SIGSYNC to select either safe synchronous  or unsafe asynchronous
    delivery.

  o _T_i_m_e _o_f _d_e_l_i_v_e_r_y
    Using 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
    PL_handle_signals().

    Signals are blocked when the garbage collector is active.


44..1133 DDCCGG GGrraammmmaarr rruulleess

Grammar rules form  a comfortable interface to  _d_i_f_f_e_r_e_n_c_e _l_i_s_t_s.   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 -->/2  for  separating
the head  and body rather than  :-/2.   Expanding grammar rules is  done
by 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  {...}  is  interpreted  as  plain  Prolog  code,  and  finally,
a  list  is  interpreted  as  a  sequence  of  _l_i_t_e_r_a_l_s.     The  Prolog
control-constructs  (\+/1, ->/2 , ;//2,  ,/2  and !/0)  can be  used  in
grammar rules.

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

________________________________________________________________________|                                                                        |
|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)                                           |
||_______}._____________________________________________________________ ||

Grammar rule sets are called using the built-in  predicates phrase/2 and
phrase/3:


pphhrraassee((_:_D_C_G_B_o_d_y_, _?_L_i_s_t))
    Equivalent to phrase(_D_C_G_B_o_d_y, _I_n_p_u_t_L_i_s_t, []).


pphhrraassee((_:_D_C_G_B_o_d_y_, _?_L_i_s_t_, _?_R_e_s_t))
    True  when _D_C_G_B_o_d_y applies  to the difference  _L_i_s_t/_R_e_s_t.   Although
    _D_C_G_B_o_d_y  is typically a _c_a_l_l_a_b_l_e  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
    section  ???? and available from library(dcg/basics), binding  _R_e_s_t to
    the remainder of the input after matching the integer.

    ____________________________________________________________________|                                                                    |
    | ?- [library(dcg/basics)].                                          |

    | ?- atom_codes('42 times', Codes),                                  |
    |    phrase(integer(X), Codes, Rest).                                |
    | X = 42                                                             |
    ||Rest_=_[32,_116,_105,_109,_101,_115]______________________________ ||

    The  next example  exploits a complete  body.   Given the  following
    definition of digit_weight//1, we can pose the query below.

    ____________________________________________________________________|                                                                    |
    | digit_weight(W) -->                                                |
    |         [D],                                                       |

    ||________{_code_type(D,_digit(W))_}._______________________________ ||

    ____________________________________________________________________|                                                                    |
    | ?- atom_codes('Version 3.4', Codes),                               |

    |    phrase(("Version ",                                             |
    |            digit_weight(Major),".",digit_weight(Minor)),           |
    |           Codes).                                                  |
    | Major = 3,                                                         |
    ||Minor_=_4.________________________________________________________ ||

    The  SWI-Prolog implementation  of phrase/3 verifies  that the  _L_i_s_t
    and  _R_e_s_t arguments are unbound, bound  to the empty list or  a list
    _c_o_n_s  _c_e_l_l.    Other  values raise  a  type error.    The  predicate
    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  section ????).   If  a DCG body  is translated,  both
    "text"  and `text` is  a valid code-list  literal in version  7.   A
    version  7 string  ("text")  is nnoott  acceptable for  the second  and
    third  arguments of 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  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  apply_macros  compiles phrase/3  if  the  argument  is
    sufficiently  instantiated,  eliminating  the  runtime  overhead  of
    translating _D_C_G_B_o_d_y and meta-calling.


ccaallll__ddccgg((_:_D_C_G_B_o_d_y_, _?_S_t_a_t_e_0_, _?_S_t_a_t_e))
    As  phrase/3, but  without type  checking _S_t_a_t_e_0  and _S_t_a_t_e.    This
    allows  for  using  DCG  rules  for  threading  an  arbitrary  state
    variable.   This  predicate was introduced  after type checking  was
    added to phrase/3.

    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:

    ____________________________________________________________________|                                                                    |
    | state(S), [S] --> [S].                                             |

    ||state(S0,_S),_[S]_-->_[S0]._______________________________________ ||

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

________________________________________________________________________|                                                                        |
|reverse(List, Reversed) :-                                              |
|        phrase(reverse(List), Reversed).                                |
|                                                                        |

|reverse([])    --> [].                                                  |
|reverse([H|T])|-->_reverse(T),_[H].____________________________________ |              |


44..1144 DDaattaabbaassee

SWI-Prolog  offers several  ways to  store data  in globally  accessible
memory, i.e., outside the  Prolog _s_t_a_c_k_s.  Data stored this  way notably
does not  change on _b_a_c_k_t_r_a_c_k_i_n_g.   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 findall/3, 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:

UUssiinngg ddyynnaammiicc pprreeddiiccaatteess  Dynamic predicates  are predicates  for  which
    the  list  of  clauses  is  modified  at  runtime  using  asserta/1,
    assertz/1,  retract/1 or retractall/1.  Following the  ISO standard,
    predicates  that are  modified this  way need to  be declared  using
    the  dynamic/1 _d_i_r_e_c_t_i_v_e.  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 retract/1  or retractall/1 on  a predicate  registers
    the  predicate  as  `dirty'.     Dirty  predicates  are  cleaned  by
    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  persistency  to
    maintain  a backup of the data on disk.  Dynamic predicates  come in
    two flavours, _s_h_a_r_e_d between  threads and _l_o_c_a_l to each thread.  The
    latter version is created using the directive thread_local/1.

TThhee rreeccoorrddeedd ddaattaabbaassee  The `recorded database' registers a list of terms
    with  a  _k_e_y,  an atom  or  compound term.     The list  is  managed
    using  recorda/3,  recordz/3  and erase/1.     It is  queried  using
    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  (section ????) are preserved.   Disadvantages are (1)  the
    terms  in a  list associated  with a key  are not  indexed, (2)  the
    poorly specified _i_m_m_e_d_i_a_t_e  _u_p_d_a_t_e _s_e_m_a_n_t_i_c_s (see section ???? applies
    to the recorded database and (3) reduced portability.

TThhee flag/3 pprreeddiiccaattee  The predicate 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.

UUssiinngg gglloobbaall vvaarriiaabblleess  The   predicates  b_setval/2   and   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 setarg/3  and nb_setarg/3.   Notably  the latter  are
    used to realise aggregation as e.g., aggregate_all/3 performs.

TTrriieess  As of version 7.3.21, SWI-Prolog provides _t_r_i_e_s (prefix trees) to
    associate  a term _v_a_r_i_a_n_t with a value.  Tries have  been introduced
    to support _t_a_b_l_i_n_g and are described in section ????.


44..1144..11 MMaannaaggiinngg ((ddyynnaammiicc)) pprreeddiiccaatteess


aabboolliisshh((_:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r))                                      _[_I_S_O_]
    Removes  all clauses of a  predicate with functor _F_u_n_c_t_o_r and  arity
    _A_r_i_t_y  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,  abolish/1 can only  be applied  to
    dynamic  procedures.    This is  odd, as  for  dealing with  dynamic
    procedures  there  is  already  retract/1 and  retractall/1.     The
    abolish/1  predicate was introduced  in DEC-10 Prolog precisely  for
    dealing  with static procedures.  In SWI-Prolog, abolish/1  works on
    static procedures, unless the Prolog flag iso is set to true.

    It  is advised  to use  retractall/1 for  erasing all  clauses of  a
    dynamic predicate.


aabboolliisshh((_+_N_a_m_e_, _+_A_r_i_t_y))
    Same  as abolish(_N_a_m_e_/_A_r_i_t_y).   The predicate abolish/2 conforms  to
    the Edinburgh standard, while abolish/1 is ISO compliant.


ccooppyy__pprreeddiiccaattee__ccllaauusseess((_:_F_r_o_m_, _:_T_o))
    Copy  all clauses of predicate  _F_r_o_m to _T_o.   The predicate _T_o  must
    be  dynamic or  undefined.   If _T_o  is undefined, it  is created  as
    a  dynamic predicate  holding a copy  of the  clauses of _F_r_o_m.    If
    _T_o  is a dynamic  predicate, the  clauses of _F_r_o_m  are added (as  in
    assertz/1)  to the clauses of  _T_o.  _T_o  and _F_r_o_m must have the  same
    arity.    Acts as if  defined by the  program below,  but at a  much
    better performance by avoiding decompilation and compilation.

    ____________________________________________________________________|                                                                    |
    | 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)._______________________________ ||


rreeddeeffiinnee__ssyysstteemm__pprreeddiiccaattee((_+_H_e_a_d))
    This  directive  may be  used  both in  module  user and  in  normal
    modules to redefine  any system predicate.  If the system definition
    is  redefined in  module 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
    system.

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

rreettrraacctt((_+_T_e_r_m))                                             _[_I_S_O_,_n_o_n_d_e_t_]
    When  _T_e_r_m  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  retract/1 predicate respects  the
    _l_o_g_i_c_a_l  _u_p_d_a_t_e _v_i_e_w.  This implies that retract/1 succeeds  for all
    clauses that match _T_e_r_m  when the predicate was _c_a_l_l_e_d.  The example
    below  illustrates that the first call to retract/1 succeeds  on bee
    on backtracking despite the fact that bee is already retracted..

    ____________________________________________________________________|                                                                    |
    | :- dynamic insect/1.                                               |

    | insect(ant).                                                       |
    | insect(bee).                                                       |
    |                                                                    |
    | ?- (   retract(insect(I)),                                         |
    |        writeln(I),                                                 |
    |        retract(insect(bee)),                                       |
    |        fail                                                        |
    |    ;   true                                                        |

    |    ).                                                              |
    | ant ;                                                              |
    ||bee.______________________________________________________________ ||

    If  multiple threads start  a retract on  the same predicate at  the
    same  time their  notion of  the _e_n_t_r_y _g_e_n_e_r_a_t_i_o_n  is adjusted  such
    that  they do  not  retract the  same first  clause.   This  implies
    that,  if multiple threads  use once(retract(Term)), no two  threads
    will  retract  the same  clause.   Note  that  on backtracking  over
    retract/1,  multiple threads  may retract  the same  clause as  both
    threads respect the logical update view.


rreettrraaccttaallll((_+_H_e_a_d))                                             _[_I_S_O_,_d_e_t_]
    All  facts or  clauses in the  database for  which the _h_e_a_d  unifies
    with  _H_e_a_d are removed.  If  _H_e_a_d refers to a predicate that  is not
    defined, it is implicitly  created as a dynamic predicate.  See also
    dynamic/1.


aasssseerrttaa((_+_T_e_r_m))                                                    _[_I_S_O_]


aasssseerrttzz((_+_T_e_r_m))                                                    _[_I_S_O_]


aasssseerrtt((_+_T_e_r_m))                                              _[_d_e_p_r_e_c_a_t_e_d_]
    Assert  a clause (fact  or rule) into the  database.  The  predicate
    asserta/1  asserts  the  clause as  first  clause of  the  predicate
    while  assertz/1 assert the clause as  last clause.  The  deprecated
    assert/1  is equivalent to assertz/1.  If the program space  for the
    target  module is limited (see set_module/1), asserta/1 can  raise a
    resource_error(_p_r_o_g_r_a_m___s_p_a_c_e) exception.  The example below adds two
    facts and a rule.  Note the double parentheses around the rule.

    ____________________________________________________________________|                                                                    |
    | ?- assertz(parent('Bob', 'Jane')).                                 |

    | ?- assertz(female('Jane')).                                        |
    | ?- assertz((mother(Child, Mother) :-                               |
    |                 parent(Child, Mother),                             |
    ||________________female(Mother)))._________________________________ ||


aasssseerrttaa((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))


aasssseerrttzz((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))


aasssseerrtt((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))                                  _[_d_e_p_r_e_c_a_t_e_d_]
    Equivalent  to  asserta/1,  assertz/1,  assert/1,  but  in  addition
    unifies  _R_e_f_e_r_e_n_c_e  with a  handle to  the asserted  clauses.    The
    handle can be used to access this clause with clause/3 and erase/1.


44..1144..22 TThhee rreeccoorrddeedd ddaattaabbaassee


rreeccoorrddaa((_+_K_e_y_, _+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Assert  _T_e_r_m in  the recorded  database under  key _K_e_y.    _K_e_y is  a
    small  integer (range min_tagged_integer ...max_tagged_integer,  atom
    or compound term.   If the key is a compound term, only the name and
    arity  define the key.   _R_e_f_e_r_e_n_c_e is unified with an opaque  handle
    to the record (see erase/1).


rreeccoorrddaa((_+_K_e_y_, _+_T_e_r_m))
    Equivalent to recorda(_K_e_y, _T_e_r_m,  _).


rreeccoorrddzz((_+_K_e_y_, _+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Equivalent to recorda/3, but  puts the _T_e_r_m at the tail of the terms
    recorded under _K_e_y.


rreeccoorrddzz((_+_K_e_y_, _+_T_e_r_m))
    Equivalent to recordz(_K_e_y, _T_e_r_m,  _).


rreeccoorrddeedd((_?_K_e_y_, _?_V_a_l_u_e_, _?_R_e_f_e_r_e_n_c_e))
    True  if _V_a_l_u_e  is recorded  under _K_e_y  and has  the given  database
    _R_e_f_e_r_e_n_c_e.     If  _R_e_f_e_r_e_n_c_e  is  given,  this  predicate  is  semi-
    deterministic.   Otherwise, it must be considered non-deterministic.
    If neither _R_e_f_e_r_e_n_c_e  nor _K_e_y is given, the triples are generated as
    in the code snippet below.  See also current_key/1.

    ____________________________________________________________________|                                                                    |
    |         current_key(Key),                                          |

    ||________recorded(Key,_Value,_Reference)___________________________ ||


rreeccoorrddeedd((_+_K_e_y_, _-_V_a_l_u_e))
    Equivalent to recorded(_K_e_y, _V_a_l_u_e,  _).


eerraassee((_+_R_e_f_e_r_e_n_c_e))
    Erase  a  record  or  clause  from  the  database.     _R_e_f_e_r_e_n_c_e  is
    a  db-reference  returned  by recorda/3,  recordz/3  or  recorded/3,
    clause/3,  assert/2, asserta/2 or 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.


iinnssttaannccee((_+_R_e_f_e_r_e_n_c_e_, _-_T_e_r_m))
    Unify  _T_e_r_m with  the referenced clause  or database  record.   Unit
    clauses are represented as _H_e_a_d :- true.


44..1144..33 FFllaaggss

The  predicate   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 _P_r_o_l_o_g  _f_l_a_g_s described  in
section ????.


ggeett__ffllaagg((_+_K_e_y_, _-_V_a_l_u_e))
    True when _V_a_l_u_e is  the value currently associated with _K_e_y.  If _K_e_y
    does not exist, a new flag with value `0' (zero) is created.


sseett__ffllaagg((_+_K_e_y_, _V_a_l_u_e))
    Set  flag _K_e_y  to _V_a_l_u_e.    Value must  be an  atom, small  (64-bit)
    integer or float.


ffllaagg((_+_K_e_y_, _-_O_l_d_, _+_N_e_w))
    True when _O_l_d is  the current value of the flag _K_e_y and the flag has
    been  set to _N_e_w.  _N_e_w can be an arithmetic expression.   The update
    is  _a_t_o_m_i_c.  This  predicate can be used  to create a _s_h_a_r_e_d  global
    counter as illustrated in the example below.

    ____________________________________________________________________|                                                                    |
    | next_id(Id) :-                                                     |

    ||____flag(my_id,_Id,_Id+1).________________________________________ ||


44..1144..44 TTrriieess

Tries (also called  _d_i_g_i_t_a_l _t_r_e_e, _r_a_d_i_x _t_r_e_e  or _p_r_e_f_i_x _t_r_e_e maintain  a
mapping between  a variant  of a term  (see =@=/2)  and a value.    They
have been introduced in SWI-Prolog 7.3.21 as part  of the implementation
of  _t_a_b_l_i_n_g.    The  current implementation  is  rather  immature.    In
particular, the following limitations currently apply:

  o Tries are not thread-safe.

  o Tries  should  not be  modified while  non-deterministic  predicates
    such as trie_gen/3 are running on the trie.

  o Terms cannot have _a_t_t_r_i_b_u_t_e_d _v_a_r_i_a_b_l_e_s.

  o Terms  cannot be  _c_y_c_l_i_c.   Possibly  this will  not change  because
    cyclic  terms can only be supported after creating a  canonical form
    of the term.

WWee ggiivvee tthhee  ddeeffiinniittiioonn ooff tthheessee pprreeddiiccaatteess ffoorr rreeffeerreennccee  aanndd ddeebbuuggggiinngg
ttaabblleedd pprreeddiiccaatteess..    FFuuttuurree vveerrssiioonnss aarree  lliikkeellyy ttoo  ggeett aa mmoorree  ssttaabbllee
aanndd ssaaffeerr  iimmpplleemmeennttaattiioonn..   TThhee AAPPII ttoo ttrriieess  sshhoouulldd nnoott bbee  ccoonnssiiddeerreedd
ssttaabbllee..


ttrriiee__nneeww((_-_T_r_i_e))
    Create  a  new trie  and  unify  _T_r_i_e with  a  handle to  the  trie.
    The  trie handle  is a  _b_l_o_b.   Tries  are subject  to atom  garbage
    collection.


ttrriiee__ddeessttrrooyy((_+_T_r_i_e))
    Destroy  _T_r_i_e.   This  removes all nodes  from the  trie and  causes
    further  access to _T_r_i_e to raise an  existence_error exception.   The
    handle itself is reclaimed by atom garbage collection.


iiss__ttrriiee((_@_T_r_i_e))                                                 _[_s_e_m_i_d_e_t_]
    True when _T_r_i_e is a trie object.  See also current_trie/1.


ccuurrrreenntt__ttrriiee((_-_T_r_i_e))                                             _[_n_o_n_d_e_t_]
    True  if _T_r_i_e 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 is_trie/1.


ttrriiee__iinnsseerrtt((_+_T_r_i_e_, _+_K_e_y_, _+_V_a_l_u_e))
    Insert  the term _K_e_y into _T_r_i_e and  associate it with _V_a_l_u_e.   _V_a_l_u_e
    can  be  any term.    If  _K_e_y-_V_a_l_u_e is  already  part of  _T_r_i_e,  the
    predicates  _f_a_i_l_s silently.   If  _K_e_y is in  _T_r_i_e associated with  a
    different value, a permission_error is raised.


ttrriiee__uuppddaattee((_+_T_r_i_e_, _+_K_e_y_, _+_V_a_l_u_e))
    As  trie_insert/3,  but if _K_e_y  is in _T_r_i_e,  its associated value  is
    _u_p_d_a_t_e_d.


ttrriiee__iinnsseerrtt((_+_T_r_i_e_, _+_T_e_r_m_, _+_V_a_l_u_e_, _-_H_a_n_d_l_e))
    As  trie_insert/3,  returning a  handle  to the  trie  node.    This
    predicate  is  currently unsafe  as  _H_a_n_d_l_e is  an integer  used  to
    encode  a pointer.  It was  used to implement a pure  Prolog version
    of the tabling library.


ttrriiee__ddeelleettee((_+_T_r_i_e_, _+_K_e_y_, _?_V_a_l_u_e))
    Delete  _K_e_y from _T_r_i_e if the value associated with _K_e_y  unifies with
    _V_a_l_u_e.


ttrriiee__llooookkuupp((_+_T_r_i_e_, _+_K_e_y_, _-_V_a_l_u_e))
    True if the term _K_e_y is in _T_r_i_e and associated with _V_a_l_u_e.


ttrriiee__tteerrmm((_+_H_a_n_d_l_e_, _-_T_e_r_m))
    True  when  _T_e_r_m is  a  copy of  the  term associated  with  _H_a_n_d_l_e.
    The  result is  undefined  (including crashes)  if _H_a_n_d_l_e  is not  a
    handle  returned by trie_insert_new/3 or the  node has been  removed
    afterwards.


ttrriiee__ggeenn((_+_T_r_i_e_, _?_K_e_y_, _-_V_a_l_u_e))                                   _[_n_o_n_d_e_t_]
    True  when  _K_e_y is  associated with  _V_a_l_u_e in  _T_r_i_e.    Backtracking
    retrieves  all pairs.  Currently scans the entire trie, even  if _K_e_y
    is  partly known.   Currently unsafe if  _T_r_i_e is modified while  the
    values are being enumerated.


ttrriiee__pprrooppeerrttyy((_?_T_r_i_e_, _?_P_r_o_p_e_r_t_y))                                 _[_n_o_n_d_e_t_]
    True  if _T_r_i_e  exists with  _P_r_o_p_e_r_t_y.   Intended  for debugging  and
    statistical  purposes.   Retrieving some  of these properties  visit
    all nodes of the trie.  Defined properties are

    vvaalluuee__ccoouunntt((_-_C_o_u_n_t))
         Number of key-value pairs in the trie.

    nnooddee__ccoouunntt((_-_C_o_u_n_t))
         Number of nodes in the trie.

    ssiizzee((_-_B_y_t_e_s))
         Required storage space of the trie.

    hhaasshheedd((_-_C_o_u_n_t))
         Number of nodes that use a hashed index to its children.


44..1144..55 UUppddaattee vviieeww

Traditionally,  Prolog systems  used  the _i_m_m_e_d_i_a_t_e  _u_p_d_a_t_e _v_i_e_w:    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 _l_o_g_i_c_a_l _u_p_d_a_t_e  _v_i_e_w,
where backtrackable predicates that enter the definition  of a predicate
will not  see any changes  (either caused by  assert/1 or retract/1)  to
the  predicate.    This view  is the  ISO  standard, the  most  commonly
used and  the most  `safe'.   Logical  updates are  realised by  keeping
reference counts  on predicates and  _g_e_n_e_r_a_t_i_o_n 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'  ...`erased' interval  that encloses the  generation of  the
current goal are considered visible.


44..1144..66 IInnddeexxiinngg ddaattaabbaasseess

The indexing  capabilities of  SWI-Prolog are described  in section  ????.
Summarizing,  SWI-Prolog creates  indexes for  any applicable  argument,
but only on  one argument, and does  not index on arguments of  compound
terms.  The  predicates below provide building blocks to  circumvent the
limitations of the current indexing system.

Programs that aim  at portability should consider  using term_hash/2 and
term_hash/4 to design their  database such that indexing on constant  or
functor (name/arity reference) on the first argument is sufficient.


tteerrmm__hhaasshh((_+_T_e_r_m_, _-_H_a_s_h_K_e_y))                                         _[_d_e_t_]
    If  _T_e_r_m is a  ground term (see ground/1),  _H_a_s_h_K_e_y is unified  with
    a  positive integer  value that may  be used  as a hash  key to  the
    value.    If _T_e_r_m  is not ground,  the predicate  leaves _H_a_s_h_K_e_y  an
    unbound  variable.   Hash  keys are  in the  range 0:::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.   Hashes differ between big and  little
    endian machines.  The term_hash/2 predicate is cycle-safe.


tteerrmm__hhaasshh((_+_T_e_r_m_, _+_D_e_p_t_h_, _+_R_a_n_g_e_, _-_H_a_s_h_K_e_y))                         _[_d_e_t_]
    As  term_hash/2, but  only considers  _T_e_r_m to  the specified  _D_e_p_t_h.
    The  top-level term has  depth 1, its arguments  have depth 2,  etc.
    That  is, _D_e_p_t_h =0  hashes nothing;  _D_e_p_t_h= 1 hashes  atomic values
    or  the functor  and arity of  a compound term,  not its  arguments;
    _D_e_p_t_h =2 also indexes the immediate arguments, etc.

    _H_a_s_h_K_e_y  is in the range  [0:::_R_a_n_g_e-1].   _R_a_n_g_e must be  in the range
    [1:::2147483647]


vvaarriiaanntt__sshhaa11((_+_T_e_r_m_, _-_S_H_A_1))                                         _[_d_e_t_]
    Compute  a  SHA1-hash from  _T_e_r_m.    The hash  is represented  as  a
    40-byte  hexadecimal atom.    Unlike term_hash/2  and friends,  this
    predicate  produces a hash  key for non-ground terms.   The hash  is
    invariant  over  variable-renaming (see  =@=/2) and  constants  over
    different invocations of Prolog.

    This  predicate raises an exception when trying to compute  the hash
    on  a cyclic  term or  attributed term.   Attributed  terms are  not
    handled  because 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], _A and _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 =@=/2.


vvaarriiaanntt__hhaasshh((_+_T_e_r_m_, _-_H_a_s_h_K_e_y))                                      _[_d_e_t_]
    Similar  to  variant_sha1/2,  but  using  a  non-cryptographic  hash
    and  produces  an integer  result like  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.


44..1155 DDeeccllaarriinngg pprreeddiiccaattee pprrooppeerrttiieess

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

________________________________________________________________________|                                                                        |
|:- dynamic                                                              |

|        foo/0,                                                          |
||_______baz/2._________________________________________________________ ||

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.


ddyynnaammiicc _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.                                  _[_I_S_O_]
    Informs  the interpreter  that  the definition  of the  predicate(s)
    may  change during execution (using assert/1 and/or retract/1).   In
    the  multithreaded version,  the clauses  of dynamic predicates  are
    shared  between the threads.  The  directive 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
    compile_predicates/1.


ccoommppiillee__pprreeddiiccaatteess((_:_L_i_s_t_O_f_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_s))
    Compile  a list of specified  dynamic predicates (see dynamic/1  and
    assert/1)  into  normal static  predicates.    This call  tells  the
    Prolog  environment  the  definition  will not  change  anymore  and
    further  calls  to assert/1  or 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.


mmuullttiiffiillee _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.                                _[_I_S_O_]
    Informs  the system that the  specified predicate(s) may be  defined
    over  more than one  file.  This  stops consult/1 from redefining  a
    predicate when a new definition is found.


ddiissccoonnttiigguuoouuss _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.                            _[_I_S_O_]
    Informs  the system that the  clauses of the specified  predicate(s)
    might not be together in the source file.  See also style_check/1.


ppuubblliicc _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.
    Instructs  the cross-referencer  that the predicate  can be  called.
    It  has no semantics.   The public declaration can be queried  using
    predicate_property/2.   The public/1  directive does _n_o_t export  the
    predicate  (see module/1  and 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.


44..1166 EExxaammiinniinngg tthhee pprrooggrraamm


ccuurrrreenntt__aattoomm((_-_A_t_o_m))
    Successively unifies _A_t_o_m with  all atoms known to the system.  Note
    that  current_atom/1 always succeeds if  _A_t_o_m is instantiated to  an
    atom.


ccuurrrreenntt__bblloobb((_?_B_l_o_b_, _?_T_y_p_e))
    Examine the type or  enumerate blobs of the given _T_y_p_e.  Typed blobs
    are  supported through  the foreign language  interface for  storing
    arbitrary  BLOBs  (Binary  Large  Object)  or  handles  to  external
    entities.  See section ???? for details.


ccuurrrreenntt__ffuunnccttoorr((_?_N_a_m_e_, _?_A_r_i_t_y))
    True  when  _N_a_m_e/_A_r_i_t_y is  a known  functor.    This means  that  at
    some  point in time  a term with name  _N_a_m_e and _A_r_i_t_y arguments  was
    created.    Functor  objects are  currently not  subject to  garbage
    collection.   Due  to timing, t/2  below with instantiated _N_a_m_e  and
    _A_r_i_t_y  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  current_functor/2 we
    are  aware of  is to analyse  resource usage  we accept this  impure
    behaviour.

    ____________________________________________________________________|                                                                    |
    | t(Name, Arity) :-                                                  |
    |     (   current_functor(Name, Arity)                               |
    |     ->  current_functor(N, A), N == Name, A == Arity               |

    |     ;   true                                                       |
    ||____).____________________________________________________________ ||


ccuurrrreenntt__ffllaagg((_-_F_l_a_g_K_e_y))
    Successively  unifies  _F_l_a_g_K_e_y with  all keys  used  for flags  (see
    flag/3).


ccuurrrreenntt__kkeeyy((_-_K_e_y))
    Successively  unifies  _K_e_y  with  all keys  used  for  records  (see
    recorda/3, etc.).


ccuurrrreenntt__pprreeddiiccaattee((_:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r))                             _[_I_S_O_]
    True  if _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r  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  section  ????).    Note  that  current_predicate/1  does
    _n_o_t  succeed  for predicates  that  can be  _a_u_t_o_l_o_a_d_e_d.    See  also
    current_predicate/2 and predicate_property/2.

    If  _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r 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 current_module/1.    Generating
    predicates   callable  in  a   given  module  requires   enumerating
    the  import  modules  using  import_module/2  and  the  autoloadable
    predicates using the predicate_property/2 autoload.


ccuurrrreenntt__pprreeddiiccaattee((_?_N_a_m_e_, _:_H_e_a_d))
    Classical  pre-ISO implementation of 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 functor/3:

    ____________________________________________________________________|                                                                    |
    | call_if_exists(G) :-                                               |

    |         current_predicate(_, G),                                   |
    ||________call(G).__________________________________________________ ||

    Because  of this intended  usage, 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.


pprreeddiiccaattee__pprrooppeerrttyy((_:_H_e_a_d_, _?_P_r_o_p_e_r_t_y))
    True  when _H_e_a_d refers  to a predicate  that has property  _P_r_o_p_e_r_t_y.
    With  sufficiently  instantiated  _H_e_a_d,  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 default_module/2)  and finally  tries the  autoloader.
    Unlike  calling,   failure  to  find  the  target  predicate  causes
    predicate_property/2 to fail silently.  If  _H_e_a_d is not sufficiently
    bound,   only  currently   locally  defined  and  already   imported
    predicates are  enumerated.  See current_predicate/1 for enumerating
    all  predicates.   A common issue  concerns _g_e_n_e_r_a_t_i_n_g all  built-in
    predicates.  This can be achieved using the code below:

    ____________________________________________________________________|                                                                    |
    | generate_built_in(Name/Arity) :-                                   |

    |     predicate_property(system:Head, built_in),                     |
    |     functor(Head, Name, Arity),                                    |
    ||____\+_sub_atom(Name,_0,__,__,_$).___%_discard_reserved_names_____ ||

    _P_r_o_p_e_r_t_y is one of:

    aauuttoollooaadd((_F_i_l_e))
         True if  the predicate can  be autoloaded  from the file  _F_i_l_e.
         Like undefined, this property is _n_o_t generated.

    bbuuiilltt__iinn
         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.

    ddeeffiinneedd
         True if the  predicate is defined.   This property is aware  of
         sources being _r_e_l_o_a_d_e_d,  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 compile_aux_clauses/1.

    ddyynnaammiicc
         True  if assert/1  and  retract/1 may  be  used to  modify  the
         predicate.  This property is set using dynamic/1.

    eexxppoorrtteedd
         True if  the predicate  is in the  public list  of the  context
         module.

    iimmppoorrtteedd__ffrroomm((_M_o_d_u_l_e))
         Is true if  the predicate is  imported into the context  module
         from module _M_o_d_u_l_e.

    ffiillee((_F_i_l_e_N_a_m_e))
         Unify  _F_i_l_e_N_a_m_e with  the  name of  the  source file  in  which
         the predicate  is  defined.    See also  source_file/2 and  the
         property line_count.   Note that this  reports the file of  the
         first clause of  a predicate.   A more robust interface can  be
         achieved using nth_clause/3 and clause_property/2.

    ffoorreeiiggnn
         True if the predicate is defined in the C language.

    iimmpplleemmeennttaattiioonn__mmoodduullee((_-_M_o_d_u_l_e))
         True when  _M_o_d_u_l_e is the  module in  which _H_e_a_d 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 default_module/2) and (2) the
         autoload index if  the unknown flag is  not set to fail in  the
         target module.

    iinnddeexxeedd((_I_n_d_e_x_e_s))
         _I_n_d_e_x_e_s  is  a  list  of  additional  (hash)   indexes  on  the
         predicate.  Each  element of the list is a  term _A_r_g_S_p_e_c-_I_n_d_e_x.
         Currently _A_r_g_S_p_e_c is an integer denoting the  argument position
         and _I_n_d_e_x  is  a term  hash(_B_u_c_k_e_t_s_, _S_p_e_e_d_u_p_,  _I_s_L_i_s_t).    Here
         _B_u_c_k_e_t_s is  the number of  buckets in the  hash and _S_p_e_e_d_u_p  is
         the expected speedup  relative to trying all clauses  linearly.
         _I_s_L_i_s_t indicates that  a list is  created for all clauses  with
         the same key.  This is currently not used.

    iinntteerrpprreetteedd
         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.

    iissoo
         True if the predicate  is covered by the ISO  standard (ISO/IEC
         13211-1).

    lliinnee__ccoouunntt((_L_i_n_e_N_u_m_b_e_r))
         Unify _L_i_n_e_N_u_m_b_e_r with  the line number  of the first clause  of
         the predicate.   Fails if the predicate is not  associated with
         a file.   See also source_file/2.   See also the file  property
         above, notably the reference to clause_property/2.

    mmuullttiiffiillee
         True if there may  be multiple (or no) files  providing clauses
         for the predicate.  This property is set using multifile/1.

    mmeettaa__pprreeddiiccaattee((_H_e_a_d))
         If  the  predicate  is  declared  as  a   meta-predicate  using
         meta_predicate/1,  unify  _H_e_a_d 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 meta_predicate/1 for details.

    nnooddeebbuugg
         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 generate_debug_info.

    nnoottrraaccee
         Do not show ports of this predicate in the debugger.

    nnuummbbeerr__ooff__ccllaauusseess((_C_l_a_u_s_e_C_o_u_n_t))
         Unify _C_l_a_u_s_e_C_o_u_n_t to the number of clauses  associated with the
         predicate.  Fails for foreign predicates.

    nnuummbbeerr__ooff__rruulleess((_R_u_l_e_C_o_u_n_t))
         Unify  _R_u_l_e_C_o_u_n_t  to the  number  of  clauses  associated  with
         the  predicate.   A  _r_u_l_e  is defined  as  a clauses  that  has
         a body  that  is not  just true  (i.e.,  a _f_a_c_t).    Fails  for
         foreign predicates.   This property is used to  avoid analysing
         predicates with only facts in prolog_codewalk.

    llaasstt__mmooddiiffiieedd__ggeenneerraattiioonn((_G_e_n_e_r_a_t_i_o_n))
         Database generation  at which  the predicate  was modified  for
         the last time.   Intended to  quickly assesses the validity  of
         caches.

    ppuubblliicc
         Predicate  is  declared public  using  public/1.     Note  that
         without further  definition, public  predicates are  considered
         undefined and this property is _n_o_t reported.

    qquuaassii__qquuoottaattiioonn__ssyynnttaaxx
         The  predicate (with  arity 4)  is  declared to  provide  quasi
         quotation syntax with quasi_quotation_syntax/1.

    ssttaattiicc
         The  definition  can  _n_o_t  be  modified  using   assertz/1  and
         friends.   This property  is the opposite  from dynamic,  i.e.,
         for each defined  predicate, either static  or dynamic is  true
         but never both.

    tthhrreeaadd__llooccaall
         If  true (only  possible  on  the multithreaded  version)  each
         thread has its  own clauses for the  predicate.  This  property
         is set using thread_local/1.

    ttrraannssppaarreenntt
         True  if  the  predicate  is  declared  transparent  using  the
         module_transparent/1 or meta_predicate/1 declaration.   In  the
         latter case the property meta_predicate(_H_e_a_d) is also provided.
         See chapter ???? for details.

    uunnddeeffiinneedd
         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
         list_undefined/0 used cross-referencing.  Deprecated.

    vviissiibbllee
         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 default_module/2) or (3) can be autoloaded.  The behaviour
         is logically  consistent iff the  property visible is  provided
         explicitly.   If  the property  is left  unbound, only  defined
         predicates are enumerated.

    vvoollaattiillee
         If true,  the  clauses are  not  saved into  a saved  state  by
         qsave_program/[1,2].  This property is set using volatile/1.


ddwwiimm__pprreeddiiccaattee((_+_T_e_r_m_, _-_D_w_i_m))
    `Do  What I  Mean'  (`dwim') support  predicate.   _T_e_r_m  is a  term,
    whose  name and arity are used  as a predicate specification.   _D_w_i_m
    is  instantiated with the most general term built from _N_a_m_e  and the
    arity  of a defined predicate  that matches the predicate  specified
    by  _T_e_r_m in the `Do  What I Mean' sense.   See dwim_match/2 for  `Do
    What  I Mean' string matching.   Internal system predicates are  not
    generated,  unless the  access level  is system  (see access_level).
    Backtracking provides all alternative matches.


ccllaauussee((_:_H_e_a_d_, _?_B_o_d_y))                                              _[_I_S_O_]
    True  if  _H_e_a_d can  be unified  with  a clause  head and  _B_o_d_y  with
    the  corresponding  clause  body.    Gives  alternative  clauses  on
    backtracking.  For facts, _B_o_d_y is unified with the atom _t_r_u_e.


ccllaauussee((_:_H_e_a_d_, _?_B_o_d_y_, _?_R_e_f_e_r_e_n_c_e))
    Equivalent  to  clause/2,   but  unifies  _R_e_f_e_r_e_n_c_e  with  a  unique
    reference to the  clause (see also assert/2, erase/1).  If _R_e_f_e_r_e_n_c_e
    is  instantiated to a reference the  clause's head and body will  be
    unified with _H_e_a_d and _B_o_d_y.


nntthh__ccllaauussee((_?_P_r_e_d_, _?_I_n_d_e_x_, _?_R_e_f_e_r_e_n_c_e))
    Provides  access to  the clauses  of a predicate  using their  index
    number.    Counting  starts at  1.   If  _R_e_f_e_r_e_n_c_e  is specified  it
    unifies  _P_r_e_d with the  most general term  with the same  name/arity
    as  the predicate  and _I_n_d_e_x with  the index  number of the  clause.
    Otherwise  the name  and arity  of _P_r_e_d  are used  to determine  the
    predicate.   If  _I_n_d_e_x is provided,  _R_e_f_e_r_e_n_c_e will be unified  with
    the  clause  reference.   If  _I_n_d_e_x  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 append/3:

    ____________________________________________________________________|                                                                    |
    | ?- 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).__________________________________ ||


ccllaauussee__pprrooppeerrttyy((_+_C_l_a_u_s_e_R_e_f_, _-_P_r_o_p_e_r_t_y))
    Queries  properties  of   a  clause.     _C_l_a_u_s_e_R_e_f  is  a  reference
    to   a   clause   as   produced   by   clause/3,   nth_clause/3   or
    prolog_frame_attribute/3.  Unlike most other predicates  that access
    clause references,  clause_property/2may be used  to get information
    about erased clauses that  have not yet been reclaimed.  _P_r_o_p_e_r_t_y is
    one of the following:

    ffiillee((_F_i_l_e_N_a_m_e))
         Unify _F_i_l_e_N_a_m_e 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 assertz/1).  See also source.

    lliinnee__ccoouunntt((_L_i_n_e_N_u_m_b_e_r))
         Unify _L_i_n_e_N_u_m_b_e_r with the line number of the clause.   Fails if
         the clause is not associated to a file.

    ssiizzee((_S_i_z_e_I_n_B_y_t_e_s))
         True when  _S_i_z_e_I_n_B_y_t_e_s  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.

    ssoouurrccee((_F_i_l_e_N_a_m_e))
         Unify _F_i_l_e_N_a_m_e with  the name of  the source file that  created
         the clause.   This  is the  same as the  file property,  unless
         the file  is  loaded from  a file  that  is textually  included
         into source  using include/1.   In this  scenario, file is  the
         included file,  while the  source property refers  to the  _m_a_i_n
         file.

    ffaacctt
         True if the clause has no body.

    eerraasseedd
         True if  the  clause has  been erased,  but  not yet  reclaimed
         because it is referenced.

    pprreeddiiccaattee((_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r))
         _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r 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
         clause/3 fails for erased clauses.

    mmoodduullee((_M_o_d_u_l_e))
         _M_o_d_u_l_e 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  _h_e_a_d, 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.


44..1177 IInnppuutt aanndd oouuttppuutt

SWI-Prolog provides two  different packages for input  and output.   The
native  I/O system  is  based on  the  ISO standard  predicates  open/3,
close/1 and  friends.   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.

Section ????  describes tell/1, 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.


44..1177..11 PPrreeddeeffiinneedd ssttrreeaamm aalliiaasseess

Each  thread  has   five  stream  aliases:     user_input,   user_output,
user_error, current_input, and  current_output.   Newly created  threads
inherit  these  stream aliases  from  their  parent.    The  user_input,
user_output and  user_error aliases  of the  main  thread are  initially
bound to  the standard operating system  I/O streams (_s_t_d_i_n, _s_t_d_o_u_t  and
_s_t_d_e_r_r, 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 swipl-win.exe GUI executable for  Windows.  They can  be
re-bound by  the user using set_prolog_IO/3 and set_stream/2 by  setting
the  alias of  a stream  (e.g,  set_stream(S, alias(user_output))).    An
example of  rebinding can be  found in library  prolog_server,  providing
a telnet service.   The aliases  current_input  and current_output  define
the source  and destination  for predicates  that do not  take a  stream
argument (e.g.,  read/1, write/1,  get_code/1, ...).   Initially,  these
are  bound to  the  same stream  as  user_input and  user_error.    They
are  re-bound by  see/1,  tell/1,  set_input/1 and  set_output/1.    The
current_output stream  is  also temporary  re-bound  by with_output_to/2
or  format/3 using  e.g., format(atom(A), ....    Note  that code  which
explicitly writes to the streams  user_output and  user_error will  not be
redirected by with_output_to/2.

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

________________________________________________________________________|                                                                        |
|write(Term)|:-_current_output(Out),_write_term(Out,_Term)._____________ |           |

while SWI-Prolog additionally allows for

________________________________________________________________________|                                                                        |

|write(Term)|:-_write(current_output,_Term).____________________________ |           |


44..1177..22 IISSOO IInnppuutt aanndd OOuuttppuutt SSttrreeaammss

The  predicates described  in this  section provide  ISO compliant  I/O,
where streams are  explicitly created using the  predicate 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 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  _s_t_r_e_a_m_-_p_a_i_r.   See  stream_pair/3 for
details.

SWI-Prolog stream  handles are unique symbols  that have no  syntactical
representation.  They are written as <stream>(hex-number),  which is not
valid input for read/1.   They are realised using a _b_l_o_b of  type stream
(see blob/2 and section ????).


ooppeenn((_+_S_r_c_D_e_s_t_, _+_M_o_d_e_, _-_-_S_t_r_e_a_m_, _+_O_p_t_i_o_n_s))                         _[_I_S_O_]
    True  when  _S_r_c_D_e_s_t can  be opened  in  _M_o_d_e and  _S_t_r_e_a_m is  an  I/O
    stream  to/from the  object.    _S_r_c_D_e_s_t is  normally the  name of  a
    file,  represented as  an atom  or string.    _M_o_d_e is  one of  read,
    write,  append or update.   Mode append opens the file  for writing,
    positioning  the file pointer  at the  end.   Mode update opens  the
    file  for writing, positioning the file pointer at the  beginning of
    the file without truncating  the file.  _S_t_r_e_a_m 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.

    SWI-Prolog  also allows  _S_r_c_D_e_s_t to  be a  term pipe(_C_o_m_m_a_n_d).    In
    this  form, _C_o_m_m_a_n_d  is started as  a child process  and if _M_o_d_e  is
    write,  output written to  _S_t_r_e_a_m is sent  to the standard input  of
    _C_o_m_m_a_n_d.   Viso versa, if _M_o_d_e  is read, data written by  _C_o_m_m_a_n_d to
    the  standard output  may be  read from _S_t_r_e_a_m.    On Unix  systems,
    _C_o_m_m_a_n_d  is handed to popen() which hands it to the Unix shell.   On
    Windows,  _C_o_m_m_a_n_d is executed  directly.  See  also process_create/3
    from process.

    The following _O_p_t_i_o_n_s are recognised by open/4:

    aalliiaass((_A_t_o_m))
         Gives the  stream a name.   Below  is an example.   Be  careful
         with  this option  as  stream  names  are global.     See  also
         set_stream/2.

         _______________________________________________________________|                                                               |
         |?- open(data, read, Fd, [alias(input)]).                       |

         |                                                               |
         |        ...,                                                   |
         |        read(input, Term),                                     |
         ||_______...___________________________________________________ ||

    bboomm((_B_o_o_l))
         Check for a BOM (_B_y_t_e _O_r_d_e_r _M_a_r_k_e_r) or write one.   If omitted,
         the default  is true for  mode read and  false for mode  write.
         See  also stream_property/2 and  especially  section ????  for  a
         discussion of this feature.

    bbuuffffeerr((_B_u_f_f_e_r_i_n_g))
         Defines output  buffering.    The atom  full (default)  defines
         full buffering, line buffering  by line, and 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 flush_output/[0,1].  This option  is
         not an ISO option.

    cclloossee__oonn__aabboorrtt((_B_o_o_l))
         If  true (default),  the  stream is  closed  on an  abort  (see
         abort/0).   If  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 pipe/1 construct).

    ccrreeaattee((_+_L_i_s_t))
         Specifies how  a new  file is  created when  opening in  write,
         append or  update mode.   Currently,  _L_i_s_t is  a list of  atoms
         that describe  the permissions of  the created  file.   Defined
         values are below.  Not recognised values  are silently ignored,
         allowing for adding platform specific extensions to this set.

         rreeaadd
             Allow read access to the file.

         wwrriittee
             Allow write access to the file.

         eexxeeccuuttee
             Allow execution access to the file.

         ddeeffaauulltt
             Allow read and write access to the file.

         aallll
             Allow any access provided by the OS.

         Note that if _L_i_s_t is empty, the created file  has no associated
         access permissions.   The create options map to the  POSIX _m_o_d_e
         option of  open(), where read  map to 0444,  write to 0222  and
         execute to  0111.   On POSIX systems,  the final permission  is
         defined as (mode & ~umask).

    eennccooddiinngg((_E_n_c_o_d_i_n_g))
         Define the encoding used  for reading and writing text  to this
         stream.   The default  encoding for type  text is derived  from
         the Prolog  flag  encoding.   For  binary  streams the  default
         encoding  is octet.     For details  on  encoding  issues,  see
         section ????.

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

    llooccaallee((_+_L_o_c_a_l_e))
         Set the locale that  is used by notably format/2 for  output on
         this stream.  See section ????.

    lloocckk((_L_o_c_k_i_n_g_M_o_d_e))
         Try to obtain a lock on the open file.  Default  is none, which
         does not lock the file.   The value read or shared  means other
         processes may  read the  file, but  not write  it.   The  value
         write or  exclusive means no  other process  may read or  write
         the file.

         Locks are  acquired through  the POSIX  function fcntl()  using
         the command F_SETLKW, which makes  a blocked call wait for  the
         lock to  be  released.    Please note  that fcntl()  locks  are
         _a_d_v_i_s_o_r_y 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 lock option is a SWI-Prolog extension.

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

    wwaaiitt((_B_o_o_l))
         This option  can be combined with  the lock option.   If  false
         (default  true), the  open  call  returns immediately  with  an
         exception if the file is locked.  The exception  has the format
         permission_error(_l_o_c_k_, _s_o_u_r_c_e___s_i_n_k_, _S_r_c_D_e_s_t).

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

ooppeenn((_+_S_r_c_D_e_s_t_, _+_M_o_d_e_, _-_-_S_t_r_e_a_m))                                   _[_I_S_O_]
    Equivalent to open/4 with an empty option list.


ooppeenn__nnuullll__ssttrreeaamm((_-_-_S_t_r_e_a_m))
    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  /dev/null) or exploit  the counting  properties.
    The  initial encoding of _S_t_r_e_a_m is 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 _T_e_r_m.

    ____________________________________________________________________|                                                                    |
    | write_length(Term, Len) :-                                         |

    |         open_null_stream(Out),                                     |
    |         write(Out, Term),                                          |
    |         character_count(Out, Len0),                                |
    |         close(Out),                                                |
    ||________Len_=_Len0._______________________________________________ ||


cclloossee((_+_S_t_r_e_a_m))                                                    _[_I_S_O_]
    Close  the specified stream.   If _S_t_r_e_a_m  is not open, an  existence
    error is  raised.  See stream_pair/3for  the implications of closing
    a _s_t_r_e_a_m _p_a_i_r.

    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 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.


cclloossee((_+_S_t_r_e_a_m_, _+_O_p_t_i_o_n_s))                                          _[_I_S_O_]
    Provides  close(_S_t_r_e_a_m_, _[_f_o_r_c_e_(_t_r_u_e_)_]) as the  only option.   Called
    this  way, any resource errors (such as write errors  while flushing
    the output buffer) are ignored.


ssttrreeaamm__pprrooppeerrttyy((_?_S_t_r_e_a_m_, _?_S_t_r_e_a_m_P_r_o_p_e_r_t_y))                          _[_I_S_O_]
    True  when _S_t_r_e_a_m_P_r_o_p_e_r_t_y is a property  of _S_t_r_e_a_m.  If  enumeration
    of   streams  or  properties  is  demanded  because   either  _S_t_r_e_a_m
    or   _S_t_r_e_a_m_P_r_o_p_e_r_t_y  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.

    aalliiaass((_A_t_o_m))
         If _A_t_o_m is bound,  test if the stream has the  specified alias.
         Otherwise unify _A_t_o_m with the first alias of the stream.

    bbuuffffeerr((_B_u_f_f_e_r_i_n_g))
         SWI-Prolog  extension  to query  the  buffering  mode  of  this
         stream.   _B_u_f_f_e_r_i_n_g is one of  full, line or  false.  See  also
         open/4.

    bbuuffffeerr__ssiizzee((_I_n_t_e_g_e_r))
         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.

    bboomm((_B_o_o_l))
         If present  and  true, a  BOM (_B_y_t_e  _O_r_d_e_r  _M_a_r_k) was  detected
         while opening the file for reading, or a BOM  was written while
         opening the stream.  See section ???? for details.

    cclloossee__oonn__aabboorrtt((_B_o_o_l))
         Determine  whether or  not  abort/0  closes  the stream.     By
         default streams are closed.

    cclloossee__oonn__eexxeecc((_B_o_o_l))
         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()
         F_SETFD  using  the  flag  FD_CLOEXEC   on  Unix  and  (negated)
         HANDLE_FLAG_INHERIT on Windows.

    eennccooddiinngg((_E_n_c_o_d_i_n_g))
         Query the  encoding  used for  text.   See  section  ???? for  an
         overview of wide character and encoding issues in SWI-Prolog.

    eenndd__ooff__ssttrreeaamm((_E))
         If _S_t_r_e_a_m is  an input stream,  unify _E with  one of the  atoms
         not, at or past.  See also at_end_of_stream/[0,1].

    eeooff__aaccttiioonn((_A))
         Unify _A with one of  eof_code,  reset or error.  See  open/4 for
         details.

    ffiillee__nnaammee((_A_t_o_m))
         If _S_t_r_e_a_m is  associated to a file,  unify _A_t_o_m to the name  of
         this file.

    ffiillee__nnoo((_I_n_t_e_g_e_r))
         If  the stream  is associated  with  a POSIX  file  descriptor,
         unify  _I_n_t_e_g_e_r  with   the  descriptor  number.      SWI-Prolog
         extension used  primarily  for integration  with foreign  code.
         See also Sfileno() from SWI-Stream.h.

    iinnppuutt
         True if _S_t_r_e_a_m has mode read.

    llooccaallee((_L_o_c_a_l_e))
         True when  _L_o_c_a_l_e is  the  current locale  associated with  the
         stream.  See section ????.

    mmooddee((_I_O_M_o_d_e))
         Unify  _I_O_M_o_d_e to  the  mode given  to  open/4 for  opening  the
         stream.   Values are:  read,  write, append and the  SWI-Prolog
         extension update.

    nneewwlliinnee((_N_e_w_l_i_n_e_M_o_d_e))
         One of posix or dos.   If dos, text streams will emit  \r\n for
         \n and discard \r from  input streams.  Default depends  on the
         operating system.

    nnlliinnkk((_-_C_o_u_n_t))
         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 st_nlink.

    oouuttppuutt
         True if _S_t_r_e_a_m has mode write, append or update.

    ppoossiittiioonn((_P_o_s))
         Unify  _P_o_s  with  the  current  stream  position.     A  stream
         position is an opaque term whose fields can  be extracted using
         stream_position_data/3.  See also set_stream_position/2.

    rreeppoossiittiioonn((_B_o_o_l))
         Unify _B_o_o_l with _t_r_u_e if  the position of the stream can  be set
         (see seek/4).   It is  assumed the position  can be set if  the
         stream has  a _s_e_e_k_-_f_u_n_c_t_i_o_n and  is not based  on a POSIX  file
         descriptor that is not associated to a regular file.

    rreepprreesseennttaattiioonn__eerrrroorrss((_M_o_d_e))
         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 error (throw  an I/O error  exception), prolog (write  \...\
         escape code) or xml  (write &#...; XML character entity).   The
         initial mode is prolog  for the user streams and error  for all
         other streams.  See also section ???? and set_stream/2.

    ttiimmeeoouutt((_-_T_i_m_e))
         _T_i_m_e is the timeout currently associated with the stream.   See
         set_stream/2 with the same option.  If no timeout is specified,
         _T_i_m_e is unified to the atom infinite.

    ttyyppee((_T_y_p_e))
         Unify _T_y_p_e with text or binary.

    ttttyy((_B_o_o_l))
         This  property is  reported  with _B_o_o_l  equal  to true  if  the
         stream is associated with a terminal.  See also set_stream/2.

    wwrriittee__eerrrroorrss((_A_t_o_m))
         _A_t_o_m is  one  of error  (default) or  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 user_error.


ccuurrrreenntt__ssttrreeaamm((_?_O_b_j_e_c_t_, _?_M_o_d_e_, _?_S_t_r_e_a_m))
    The  predicate current_stream/3 is  used to access  the status of  a
    stream  as well  as to generate  all open  streams.   _O_b_j_e_c_t 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 [] if the  stream refers to some  other
    object.  _M_o_d_e is one of read or write.


iiss__ssttrreeaamm((_+_T_e_r_m))
    True  if  _T_e_r_m is  a  stream name  or  valid stream  handle.    This
    predicate  realises a safe test for the existence of a  stream alias
    or handle.


ssttrreeaamm__ppaaiirr((_?_S_t_r_e_a_m_P_a_i_r_, _?_R_e_a_d_, _?_W_r_i_t_e))
    This  predicate can be used in mode (-,+,+) to create  a _s_t_r_e_a_m_-_p_a_i_r
    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 _R_e_a_d or _W_r_i_t_e 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  close/1 closes the still open  streams of the pair.   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.


sseett__ssttrreeaamm__ppoossiittiioonn((_+_S_t_r_e_a_m_, _+_P_o_s))                                 _[_I_S_O_]
    Set  the current  position  of _S_t_r_e_a_m  to _P_o_s.    _P_o_s is  a term  as
    returned  by  stream_property/2 using  the  position(_P_o_s)  property.
    See also seek/4.


ssttrreeaamm__ppoossiittiioonn__ddaattaa((_?_F_i_e_l_d_, _+_P_o_s_, _-_D_a_t_a))
    Extracts  information from  the opaque stream  position term as  re-
    turned  by stream_property/2 requesting the position(_P_o_s)  property.
    _F_i_e_l_d is  one of line_count, line_position, char_count or byte_count.
    See   also  line_count/2,  line_position/2,   character_count/2  and
    byte_count/2.


sseeeekk((_+_S_t_r_e_a_m_, _+_O_f_f_s_e_t_, _+_M_e_t_h_o_d_, _-_N_e_w_L_o_c_a_t_i_o_n))
    Reposition the current point  of the given _S_t_r_e_a_m.  _M_e_t_h_o_d is one of
    bof,  current or eof, indicating positioning relative to  the start,
    current  point or  end of  the underlying  object.   _N_e_w_L_o_c_a_t_i_o_n  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  _w_c_h_a_r
    encoding  (sizeof(wchar_t)).    The  latter  guarantees  comfortable
    interaction  with  wide-character  text objects.     Otherwise,  the
    use  of  seek/4  on non-binary  files  (see  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  stream_property/2  and set_stream_position/2.    Skipping  N
    character  codes is  achieved calling  get_code/2 N times  or using
    copy_stream_data/3,  directing the  output  to  a null  stream  (see
    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 permission_error is raised.
    If  applying  the  offset  would  result in  a  file  position  less
    than  zero, a  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  seek/4
    is  compatible  with Quintus  Prolog,  though the  error  conditions
    and  signalling is ISO  compliant.   See also  stream_property/2 and
    set_stream_position/2.


sseett__ssttrreeaamm((_+_S_t_r_e_a_m_, _+_A_t_t_r_i_b_u_t_e))
    Modify  an attribute  of an  existing stream.   _A_t_t_r_i_b_u_t_e  specifies
    the   stream  property  to  set.      If  stream  is  a  _p_a_i_r   (see
    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,  eof_action  only applies  to the  _r_e_a_d
    stream,  representation_errors  only  applies to  the  _w_r_i_t_e  stream
    and  trying to  set alias or  line_position  on a  pair results in  a
    permission_error exception.  See also stream_property/2 and open/4.

    aalliiaass((_A_l_i_a_s_N_a_m_e))
         Set the  alias of  an  already created  stream.   If  _A_l_i_a_s_N_a_m_e
         is  the name  of  one  of the  standard  streams,  this  stream
         is rebound.    Thus,  set_stream(S, current_input) is the  same
         as  set_input/1,  and  by  setting  the  alias of  a  stream  to
         user_input, etc.,  all user  terminal input is  read from  this
         stream.  See also interactor/0.

    bbuuffffeerr((_B_u_f_f_e_r_i_n_g))
         Set the buffering mode  of an already created stream.   Buffer-
         ing is one of full, line or false.

    bbuuffffeerr__ssiizzee((_+_S_i_z_e))
         Set the  size of  the I/O buffer  of the  underlying stream  to
         _S_i_z_e bytes.

    cclloossee__oonn__aabboorrtt((_B_o_o_l))
         Determine whether or not the  stream is closed by abort/0.   By
         default, streams are closed.

    cclloossee__oonn__eexxeecc((_B_o_o_l))
         Set the close_on_exec property.  See stream_property/2.

    eennccooddiinngg((_A_t_o_m))
         Defines the mapping between bytes and character  codes used for
         the stream.    See section  ???? for  supported encodings.    The
         value  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.

    eeooff__aaccttiioonn((_A_c_t_i_o_n))
         Set end-of-file handling to one of eof_code, reset or error.

    ffiillee__nnaammee((_F_i_l_e_N_a_m_e))
         Set the filename associated to  this stream.  This call  can be
         used to set the file for error locations  if _S_t_r_e_a_m corresponds
         to _F_i_l_e_N_a_m_e and  is not obtained  by opening the file  directly
         but, for example, through a network service.

    lliinnee__ppoossiittiioonn((_L_i_n_e_P_o_s))
         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
         line_position/2 and stream_property/2(property position).

    llooccaallee((_+_L_o_c_a_l_e))
         Change the locale of the stream.  See section ????.

    nneewwlliinnee((_N_e_w_l_i_n_e_M_o_d_e))
         Set input or output translation for newlines.   See correspond-
         ing stream_property/2 for details.  In addition to the detected
         modes, an input stream can  be set in mode detect.  It  will be
         set to dos if a \r character was removed.

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

             error(timeout_error_(_r_e_a_d_, _S_t_r_e_a_m_)_, __)

    ttyyppee((_T_y_p_e))
         Set the type of the stream to one of text or binary.   See also
         open/4 and  the encoding  property of  streams.   Switching  to
         binary sets the encoding to octet.  Switching to  text sets the
         encoding to the default text encoding.

    rreeccoorrdd__ppoossiittiioonn((_B_o_o_l))
         Do/do   not   record   the   line   count   and    line   posi-
         tion  (see   line_count/2  and   line_position/2).       Calling
         set_stream(S, record_position(true)) resets  the  position  the
         start of line 1.

    rreepprreesseennttaattiioonn__eerrrroorrss((_M_o_d_e))
         Change the  behaviour  when writing  characters to  the  stream
         that  cannot  be  represented  by  the  encoding.     See  also
         stream_property/2 and section ????.

    ttttyy((_B_o_o_l))
         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 stream_property/2.


sseett__pprroolloogg__IIOO((_+_I_n_, _+_O_u_t_, _+_E_r_r_o_r))
    Prepare  the   given  streams  for  interactive  behaviour  normally
    associated  to  the  terminal.     _I_n  becomes  the  user_input  and
    current_input  of  the calling  thread.    _O_u_t  becomes  user_output
    and  current_output.    If _E_r_r_o_r  equals  _O_u_t an  unbuffered  stream
    is  associated to  the same  destination and  linked to  user_error.
    Otherwise  _E_r_r_o_r is used for  user_error.   Output buffering for  _O_u_t
    is  set  to line  and buffering  on _E_r_r_o_r  is disabled.    See  also
    prolog/0  and set_stream/2.  The  _c_l_i_b package provides the  library
    prolog_server, creating a TCP/IP server for  creating an interactive
    session to Prolog.


44..1177..33 EEddiinnbbuurrgghh--ssttyyllee II//OO

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  _c_u_r_r_e_n_t  input and  output  streams.
Initially these  streams are  connected to  the terminal.   The  current
output stream is  changed using tell/1 or  append/1.  The current  input
stream  is changed  using see/1.    The stream's  current  value can  be
obtained using telling/1 for output and seeing/1 for input.

Source  and   destination  are   either  a  file,   user,   or  a   term
`pipe(_C_o_m_m_a_n_d)'.  The reserved stream name user refers  to the terminal.
In the predicate descriptions below we will  call the source/destination
argument  `_S_r_c_D_e_s_t'.    Below are  some examples  of  source/destination
specifications.

         ?- see(data).        % Start reading from file `data'.
         ?- tell(user).       % Start writing to the terminal.
         ?- tell(pipe(lpr)).  % Start writing to the printer.

Another example  of using  the pipe/1 construct  is shown  below.   Note
that  the  pipe/1  construct  is  not  part  of  Prolog's  standard  I/O
repertoire.

________________________________________________________________________|                                                                        |
|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([]).|_______________________________________________________ |               |

The  effect of  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' :

________________________________________________________________________|                                                                        |
|?-|(tell(out),_write(a),_false_;_write(b)),_told.______________________ |  |


CCoommppaattiibbiilliittyy nnootteess

Unlike Edinburgh  Prolog systems, telling/1  and 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:

________________________________________________________________________|                                                                        |
|        ...,                                                            |
|        telling(Old), tell(x),                                          |
|        ...,                                                            |

|        told, tell(Old),                                                |
||_______...,___________________________________________________________ ||

The predicates tell/1 and see/1 first check for  user, the pipe(_c_o_m_m_a_n_d)
and a stream handle.  Otherwise, if the argument is  an atom it is first
compared to  open streams  associated to  a file with  _e_x_a_c_t_l_y the  same
name.   If such a stream exists,  created using tell/1 or 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 section ????.


sseeee((_+_S_r_c_D_e_s_t))
    Open  _S_r_c_D_e_s_t  for  reading  and  make it  the  current  input  (see
    set_input/1).  If _S_r_c_D_e_s_t is a stream  handle, just make this stream
    the current input.  See the introduction of section ???? for details.


tteellll((_+_S_r_c_D_e_s_t))
    Open  _S_r_c_D_e_s_t  for  writing and  make  it  the current  output  (see
    set_output/1).    If _S_r_c_D_e_s_t  is  a stream  handle,  just make  this
    stream  the current output.  See the introduction of section  ???? for
    details.


aappppeenndd((_+_F_i_l_e))
    Similar  to tell/1,  but positions the  file pointer  at the end  of
    _F_i_l_e  rather than truncating an existing  file.  The pipe  construct
    is not accepted by this predicate.


sseeeeiinngg((_?_S_r_c_D_e_s_t))
    Same  as  current_input/1,  except  that user  is  returned  if  the
    current  input  is the  stream user_input  to improve  compatibility
    with  traditional Edinburgh I/O. See the introduction of  section ????
    for details.


tteelllliinngg((_?_S_r_c_D_e_s_t))
    Same  as  current_output/1, except  that  user  is returned  if  the
    current  output is the  stream user_output to improve  compatibility
    with  traditional Edinburgh I/O. See the introduction of  section ????
    for details.


sseeeenn
    Close  the  current input  stream.   The  new  input stream  becomes
    user_input.


ttoolldd
    Close  the current  output stream.   The  new output stream  becomes
    user_output.


44..1177..44 SSwwiittcchhiinngg bbeettwweeeenn EEddiinnbbuurrgghh aanndd IISSOO II//OO

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

sseett__iinnppuutt((_+_S_t_r_e_a_m))                                                 _[_I_S_O_]
    Set   the  current   input  stream   to  become  _S_t_r_e_a_m.       Thus,
    open(file, read, Stream), set_input(Stream)    is   equivalent    to
    see(file).


sseett__oouuttppuutt((_+_S_t_r_e_a_m))                                                _[_I_S_O_]
    Set  the  current  output  stream  to  become  _S_t_r_e_a_m.     See  also
    with_output_to/2.


ccuurrrreenntt__iinnppuutt((_-_S_t_r_e_a_m))                                             _[_I_S_O_]
    Get  the current input  stream.   Useful for  getting access to  the
    status predicates associated with streams.


ccuurrrreenntt__oouuttppuutt((_-_S_t_r_e_a_m))                                            _[_I_S_O_]
    Get the current output stream.


44..1177..55 WWrriittee oonnttoo aattoommss,, ccooddee--lliissttss,, eettcc..


wwiitthh__oouuttppuutt__ttoo((_+_O_u_t_p_u_t_, _:_G_o_a_l))
    Run  _G_o_a_l  as  once/1,  while  characters  written  to  the  current
    output  are sent to _O_u_t_p_u_t.   The predicate is  SWI-Prolog-specific,
    inspired  by  various posts  to  the mailinglist.    It  provides  a
    flexible  replacement for predicates  such as sformat/3,  swritef/3,
    term_to_atom/2, atom_number/2 converting numbers to atoms, etc.  The
    predicate 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:

    ____________________________________________________________________|                                                                    |
    | term(Term, In, Tail) :-                                            |

    |         with_output_to(codes(In, Tail), write(Term)).              |
    |                                                                    |
    | ?- phrase(term(hello), X).                                         |
    |                                                                    |
    ||X_=_[104,_101,_108,_108,_111]_____________________________________ ||

    AA SSttrreeaamm hhaannddllee oorr aalliiaass
         Temporarily switch current output  to the given stream.   Redi-
         rection using  with_output_to/2guarantees  the original  output
         is restored, also  if _G_o_a_l fails or  raises an exception.   See
         also call_cleanup/2.

    aattoomm((_-_A_t_o_m))
         Create an atom  from the emitted characters.   Please note  the
         remark above.

    ssttrriinngg((_-_S_t_r_i_n_g))
         Create a string object as defined in section ????.

    ccooddeess((_-_C_o_d_e_s))
         Create a list of  character codes from the emitted  characters,
         similar to atom_codes/2.

    ccooddeess((_-_C_o_d_e_s_, _-_T_a_i_l))
         Create a list of character codes as a difference list.

    cchhaarrss((_-_C_h_a_r_s))
         Create a list of  one-character atoms from the emitted  charac-
         ters, similar to atom_chars/2.

    cchhaarrss((_-_C_h_a_r_s_, _-_T_a_i_l))
         Create a list of one-character atoms as a difference list.


44..1177..66 FFaasstt bbiinnaarryy tteerrmm II//OO

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

The  binary representation  the  same as  used  by PL_record_external().
The  use of  these  primitives instead  of  using write_canonical/2  has
advantages and disadvantages.  Below are the main considerations:

  o Using  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.

  o Using the binary format improves the performance roughly 3 times.

  o The size of both representations is comparable.

  o The  binary format  can deal  with cycles,  sharing and  attributes.
    Special  precautions  are   needed  to  transfer  such  terms  using
    write_canonical/2.  See term_factorized/3 and copy_term/3.

  o In  the  current  version,   reading  the  binary  format  has  only
    incomplete  consistency checks.   This implies  a user must be  able
    to  ttrruusstt tthhee ssoouurrccee as crafted messages may compromise  the reading
    Prolog system.


ffaasstt__tteerrmm__sseerriiaalliizzeedd((_?_T_e_r_m_, _?_S_t_r_i_n_g))
    (De-)serialize _T_e_r_m to/from _S_t_r_i_n_g.


ffaasstt__wwrriittee((_+_O_u_t_p_u_t_, _+_T_e_r_m))
    Write  _T_e_r_m  using  the  fast serialization  format  to  the  _O_u_t_p_u_t
    stream.  _O_u_t_p_u_t _m_u_s_t be a binary stream.


ffaasstt__rreeaadd((_+_I_n_p_u_t_, _-_T_e_r_m))
    Read  _T_e_r_m  using  the  fast serialization  format  from  the  _I_n_p_u_t
    stream.  _I_n_p_u_t _m_u_s_t be a binary stream.


44..1188 SSttaattuuss ooff ssttrreeaammss


wwaaiitt__ffoorr__iinnppuutt((_+_L_i_s_t_O_f_S_t_r_e_a_m_s_, _-_R_e_a_d_y_L_i_s_t_, _+_T_i_m_e_O_u_t))               _[_d_e_t_]
    Wait  for input on  one of the  streams in _L_i_s_t_O_f_S_t_r_e_a_m_s and  return
    a  list  of  streams  on  which input  is  available  in  _R_e_a_d_y_L_i_s_t.
    wait_for_input/3 waits  for at most  _T_i_m_e_O_u_t seconds.   _T_i_m_e_O_u_t  may
    be  specified as  a floating  point number to  specify fractions  of
    a  second.    If  _T_i_m_e_O_u_t  equals  infinite,  wait_for_input/3 waits
    indefinitely.    If  _T_i_m_e_o_u_t  is 0  or  0.0 this  predicate  returns
    without waiting.

    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  _L_i_s_t_O_f_S_t_r_e_a_m_s
    contains a stream  that is not associated with a supported device, a
    domain_error(_w_a_i_t_a_b_l_e___s_t_r_e_a_m_, _S_t_r_e_a_m) is raised.

    The  example below waits for input  from the user and an  explicitly
    opened  secondary  terminal stream.    On  return, _I_n_p_u_t_s  may  hold
    user_input or _P_4 or both.

    ____________________________________________________________________|                                                                    |
    | ?- open('/dev/ttyp4', read, P4),                                   |

    ||___wait_for_input([user_input,_P4],_Inputs,_0).___________________ ||

    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  231-1  milliseconds (a bit  less than  25 days).   Specifying  a
    too  large timeout raises a representation_error(_t_i_m_e_o_u_t) exception.
    If  poll()  is not  supported by  the OS,  select() is  used.    The
    select()  call can  only handle file  descriptors up  to FD_SETSIZE.
    If  the  set  contains  a  descriptor  that  exceeds  this  limit  a
    representation_error(_'_F_D___S_E_T_S_I_Z_E_') is raised.

    Note  that wait_for_input/3 returns streams that have data  waiting.
    This  does  not  mean you  can,  for  example,  call read/2  on  the
    stream  without  blocking as  the stream  might  hold an  incomplete
    term.   The predicate set_stream/2 using the option timeout(_S_e_c_o_n_d_s)
    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:

    ____________________________________________________________________|                                                                    |
    |     ...,                                                           |
    |     tcp_accept(Server, Socket, _Peer),                             |
    |     tcp_open(Socket, In, Out),                                     |
    |     set_stream(In, timeout(10)),                                   |
    |     catch(read(In, Term), _, (close(Out), close(In), fail)),       |

    ||____...,__________________________________________________________ ||


bbyyttee__ccoouunntt((_+_S_t_r_e_a_m_, _-_C_o_u_n_t))
    Byte  position in _S_t_r_e_a_m.   For binary streams  this is the same  as
    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).


cchhaarraacctteerr__ccoouunntt((_+_S_t_r_e_a_m_, _-_C_o_u_n_t))
    Unify  _C_o_u_n_t 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.


lliinnee__ccoouunntt((_+_S_t_r_e_a_m_, _-_C_o_u_n_t))
    Unify  _C_o_u_n_t with the  number of  lines read or  written.   Counting
    starts at 1.


lliinnee__ppoossiittiioonn((_+_S_t_r_e_a_m_, _-_C_o_u_n_t))
    Unify  _C_o_u_n_t 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.


44..1199 PPrriimmiittiivvee cchhaarraacctteerr II//OO

See section ???? for an overview of supported character representations.


nnll                                                                _[_I_S_O_]
    Write  a newline character  to the current output  stream.  On  Unix
    systems nl/0 is equivalent to put(10).


nnll((_+_S_t_r_e_a_m))                                                       _[_I_S_O_]
    Write a newline to _S_t_r_e_a_m.


ppuutt((_+_C_h_a_r))
    Write  _C_h_a_r  to the  current  output  stream.    _C_h_a_r is  either  an
    integer  expression evaluating  to a  character code or  an atom  of
    one  character.   Deprecated.    New code  should use  put_char/1 or
    put_code/1.


ppuutt((_+_S_t_r_e_a_m_, _+_C_h_a_r))
    Write _C_h_a_r to _S_t_r_e_a_m.  See put/1 for details.


ppuutt__bbyyttee((_+_B_y_t_e))                                                    _[_I_S_O_]
    Write a single byte  to the output.  _B_y_t_e must be an integer between
    0 and 255.


ppuutt__bbyyttee((_+_S_t_r_e_a_m_, _+_B_y_t_e))                                           _[_I_S_O_]
    Write  a single byte to _S_t_r_e_a_m.   _B_y_t_e must be an integer  between 0
    and 255.


ppuutt__cchhaarr((_+_C_h_a_r))                                                    _[_I_S_O_]
    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
    _C_h_a_r.


ppuutt__cchhaarr((_+_S_t_r_e_a_m_, _+_C_h_a_r))                                           _[_I_S_O_]
    Write  a  character to  _S_t_r_e_a_m,  obeying  the encoding  defined  for
    _S_t_r_e_a_m.   Note that this may  raise an exception if the  encoding of
    _S_t_r_e_a_m cannot represent _C_h_a_r.


ppuutt__ccooddee((_+_C_o_d_e))                                                    _[_I_S_O_]
    Similar  to put_char/1,  but using  a _c_h_a_r_a_c_t_e_r  _c_o_d_e.    _C_o_d_e is  a
    non-negative integer.   Note that this may raise an exception if the
    encoding of the output stream cannot represent _C_o_d_e.


ppuutt__ccooddee((_+_S_t_r_e_a_m_, _+_C_o_d_e))                                           _[_I_S_O_]
    Same as put_code/1 but directing _C_o_d_e to _S_t_r_e_a_m.


ttaabb((_+_A_m_o_u_n_t))
    Write  _A_m_o_u_n_t spaces on  the current output  stream.  _A_m_o_u_n_t  should
    be  an  expression   that  evaluates  to  a  positive  integer  (see
    section ????).


ttaabb((_+_S_t_r_e_a_m_, _+_A_m_o_u_n_t))
    Write _A_m_o_u_n_t spaces to _S_t_r_e_a_m.


fflluusshh__oouuttppuutt                                                       _[_I_S_O_]
    Flush  pending output on current  output stream.   flush_output/0 is
    automatically  generated by  read/1 and derivatives  if the  current
    input stream is user and the cursor is not at the left margin.


fflluusshh__oouuttppuutt((_+_S_t_r_e_a_m))                                              _[_I_S_O_]
    Flush  output on the specified stream.  The stream must be  open for
    writing.


ttttyyfflluusshh
    Flush pending output on stream user.  See also flush_output/[0,1].


ggeett__bbyyttee((_-_B_y_t_e))                                                    _[_I_S_O_]
    Read the current input  stream and unify the next byte with _B_y_t_e (an
    integer  between 0  and 255).   _B_y_t_e is  unified with  -1 on end  of
    file.


ggeett__bbyyttee((_+_S_t_r_e_a_m_, _-_B_y_t_e))                                           _[_I_S_O_]
    Read  the  next byte  from _S_t_r_e_a_m  and unify  _B_y_t_e  with an  integer
    between 0 and 255.


ggeett__ccooddee((_-_C_o_d_e))                                                    _[_I_S_O_]
    Read  the current  input stream  and unify _C_o_d_e  with the  character
    code  of the  next character.   _C_o_d_e is  unified with  -1 on end  of
    file.  See also get_char/1.


ggeett__ccooddee((_+_S_t_r_e_a_m_, _-_C_o_d_e))                                           _[_I_S_O_]
    Read the next character code from _S_t_r_e_a_m.


ggeett__cchhaarr((_-_C_h_a_r))                                                    _[_I_S_O_]
    Read  the  current  input  stream  and  unify  _C_h_a_r  with  the  next
    character  as a  one-character atom.    See also  atom_chars/2.    On
    end-of-file, _C_h_a_r is unified to the atom end_of_file.


ggeett__cchhaarr((_+_S_t_r_e_a_m_, _-_C_h_a_r))                                           _[_I_S_O_]
    Unify  _C_h_a_r with the next  character from _S_t_r_e_a_m as a  one-character
    atom.  See also get_char/2, get_byte/2 and get_code/2.


ggeett00((_-_C_h_a_r))                                                _[_d_e_p_r_e_c_a_t_e_d_]
    Edinburgh  version  of the  ISO  get_code/1 predicate.    Note  that
    Edinburgh  Prolog  didn't  support  wide  characters  and  therefore
    technically  speaking get0/1 should have been  mapped to get_byte/1.
    The intention of get0/1, however, is to read character codes.


ggeett00((_+_S_t_r_e_a_m_, _-_C_h_a_r))                                       _[_d_e_p_r_e_c_a_t_e_d_]
    Edinburgh  version  of  the ISO  get_code/2  predicate.    See  also
    get0/1.


ggeett((_-_C_h_a_r))                                                 _[_d_e_p_r_e_c_a_t_e_d_]
    Read  the  current   input  stream  and  unify  the  next  non-blank
    character  with _C_h_a_r.  _C_h_a_r is unified with -1 on end of file.   The
    predicate get/1 operates on character _c_o_d_e_s.  See also get0/1.


ggeett((_+_S_t_r_e_a_m_, _-_C_h_a_r))                                        _[_d_e_p_r_e_c_a_t_e_d_]
    Read  the next  non-blank character from  _S_t_r_e_a_m.   See also  get/1,
    get0/1 and get0/2.


ppeeeekk__bbyyttee((_-_B_y_t_e))                                                   _[_I_S_O_]


ppeeeekk__bbyyttee((_+_S_t_r_e_a_m_, _-_B_y_t_e))                                          _[_I_S_O_]


ppeeeekk__ccooddee((_-_C_o_d_e))                                                   _[_I_S_O_]


ppeeeekk__ccooddee((_+_S_t_r_e_a_m_, _-_C_o_d_e))                                          _[_I_S_O_]


ppeeeekk__cchhaarr((_-_C_h_a_r))                                                   _[_I_S_O_]


ppeeeekk__cchhaarr((_+_S_t_r_e_a_m_, _-_C_h_a_r))                                          _[_I_S_O_]
    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  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.


ppeeeekk__ssttrriinngg((_+_S_t_r_e_a_m_, _+_L_e_n_, _-_S_t_r_i_n_g))
    Read  the next _L_e_n  characters (if the stream  is a text stream)  or
    bytes  (if the stream  is binary) from  Stream without removing  the
    data.   If  _L_e_n is larger  that the stream  buffer size, the  buffer
    size  is increased to _L_e_n.   _S_t_r_i_n_g can  be shorter than _L_e_n if  the
    stream contains less data.   This predicate is intended to guess the
    content type of data read from non-repositionable streams.


sskkiipp((_+_C_o_d_e))
    Read the input until  _C_o_d_e or the end of the file is encountered.  A
    subsequent  call to get_code/1 will  read the first character  after
    _C_o_d_e.


sskkiipp((_+_S_t_r_e_a_m_, _+_C_o_d_e))
    Skip input (as skip/1) on _S_t_r_e_a_m.


ggeett__ssiinnggllee__cchhaarr((_-_C_o_d_e))
    Get  a single character from input stream `user' (regardless  of the
    current  input stream).  Unlike 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 -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.


aatt__eenndd__ooff__ssttrreeaamm                                                    _[_I_S_O_]
    Succeeds  after the last character  of the current input stream  has
    been  read.    Also succeeds  if  there is  no valid  current  input
    stream.


aatt__eenndd__ooff__ssttrreeaamm((_+_S_t_r_e_a_m))                                           _[_I_S_O_]
    Succeeds  after the last character of  the named stream is read,  or
    _S_t_r_e_a_m 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 open/4).


sseett__eenndd__ooff__ssttrreeaamm((_+_S_t_r_e_a_m))
    Set  the size  of  the file  opened as  _S_t_r_e_a_m to  the current  file
    position.   This is typically used in combination with the open-mode
    update.


ccooppyy__ssttrreeaamm__ddaattaa((_+_S_t_r_e_a_m_I_n_, _+_S_t_r_e_a_m_O_u_t_, _+_L_e_n))
    Copy  _L_e_n codes from _S_t_r_e_a_m_I_n to _S_t_r_e_a_m_O_u_t.   Note that the  copy is
    done  using the semantics of get_code/2 and  put_code/2, taking  care
    of  possibly recoding  that  needs to  take place  between two  text
    files.  See section ????.


ccooppyy__ssttrreeaamm__ddaattaa((_+_S_t_r_e_a_m_I_n_, _+_S_t_r_e_a_m_O_u_t))
    Copy all (remaining) data from _S_t_r_e_a_m_I_n to _S_t_r_e_a_m_O_u_t.


ffiillll__bbuuffffeerr((_+_S_t_r_e_a_m))                                               _[_d_e_t_]
    Fill  the  _S_t_r_e_a_m's input  buffer.   Subsequent  calls  try to  read
    more  input until the buffer is  completely filled.  This  predicate
    is  used together  with read_pending_codes/3 to  process input  with
    minimal buffering.


rreeaadd__ppeennddiinngg__ccooddeess((_+_S_t_r_e_a_m_I_n_, _-_C_o_d_e_s_, _?_T_a_i_l))
    Read input pending in  the input buffer of _S_t_r_e_a_m_I_n and return it in
    the  difference list _C_o_d_e_s-_T_a_i_l.  That is, the  available characters
    codes  are used to  create the list _C_o_d_e_s  ending in the tail  _T_a_i_l.
    On  encountering end-of-file, both _C_o_d_e_s  and _T_a_i_l are unified  with
    the empty list ([]).

    This  predicate is  intended  for efficient  unbuffered copying  and
    filtering  of input coming from network connections or devices.   It
    also  enables  the library  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  at_end_of_stream/1
    call  checks for  end-of-stream and fills  the input  buffer.   Note
    that  the use of a  get_code/2 and put_code/2 based loop requires  a
    flush_output/1 call  after _e_a_c_h put_code/2.   The copy_stream_data/2
    does  not allow for inspection of  the copied data and suffers  from
    the same buffering issues.

    ____________________________________________________________________|                                                                    |
    | copy(In, Out) :-                                                   |

    |         repeat,                                                    |
    |             fill_buffer(In),                                       |
    |             read_pending_codes(In, Chars, Tail),                   |
    |             \+ \+ ( Tail = [],                                     |
    |                     format(Out, '~s', [Chars]),                    |
    |                     flush_output(Out)                              |
    |                   ),                                               |
    |             (   Tail == []                                         |

    |             ->  !                                                  |
    |             ;   fail                                               |
    ||____________).____________________________________________________ ||


rreeaadd__ppeennddiinngg__cchhaarrss((_+_S_t_r_e_a_m_I_n_, _-_C_h_a_r_s_, _?_T_a_i_l))
    As  read_pending_codes/3, but  returns  a  difference list  of  one-
    character atoms.


44..2200 TTeerrmm rreeaaddiinngg aanndd wwrriittiinngg

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

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

wwrriittee__tteerrmm((_+_T_e_r_m_, _+_O_p_t_i_o_n_s))                                        _[_I_S_O_]
    The  predicate  write_term/2  is  the generic  form  of  all  Prolog
    term-write predicates.  Valid options are:

    aattttrriibbuutteess((_A_t_o_m))
         Define how attributed  variables (see section ????) are  written.
         The default is determined by  the Prolog flag write_attributes.
         Defined values are  ignore (ignore the attribute), dots  (write
         the attributes  as {...}),  write (simply  hand the  attributes
         recursively to write_term/2) and  portray (hand the  attributes
         to attr_portray_hook/2).

    bbaacckk__qquuootteess((_A_t_o_m))
         Fulfills  the  same  role  as   the  back_quotes  prolog  flag.
         Notably, the value  string causes string objects to be  printed
         between back quotes and symbol_char causes the backquote  to be
         printed unquoted.  In all other cases the  backquote is printed
         as a quoted atom.

    bbrraaccee__tteerrmmss((_B_o_o_l))
         If true (default), write {}(X)  as {X}.  See also  dotlists and
         ignore_ops.

    bblloobbss((_A_t_o_m))
         Define how  non-text blobs are  handled.   By default, this  is
         left to the write handler specified with the blob type.   Using
         portray, portray/1 is  called for each  blob encountered.   See
         section ????.

    cchhaarraacctteerr__eessccaappeess((_B_o_o_l))
         If  true and  quoted(_t_r_u_e)  is active,  special  characters  in
         quoted atoms and strings  are emitted as ISO escape  sequences.
         Default is taken from the reference module (see below).

    ccyycclleess((_B_o_o_l))
         If true  (default),  cyclic terms  are  written as  @(_T_e_m_p_l_a_t_e_,
         _S_u_b_s_t_i_t_u_t_i_o_n_s), where _S_u_b_s_t_i_t_u_t_i_o_n_s is a list _V_a_r = _V_a_l_u_e.   If
         cycles is false,  max_depth is not given,  and _T_e_r_m is  cyclic,
         write_term/2 raises a domain_error.   See also the cycles option
         in read_term/2.

    ddoottlliissttss((_B_o_o_l))
         If true  (default false),  write  lists using  the dotted  term
         notation  rather  than  the  list  notation.     Note  that  as
         of  version  7,   the  list  constructor  is  '[|]'.      Using
         dotlists(_t_r_u_e),  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.

    ffuullllssttoopp((_B_o_o_l))
         If true (default  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  nl(_t_r_u_e) option is  also
         given.

    iiggnnoorree__ooppss((_B_o_o_l))
         If true, the generic term representation (<_f_u_n_c_t_o_r>(<_a_r_g_s> ...))
         will be  used for all  terms.   Otherwise (default),  operators
         will be used where appropriate..

    mmaaxx__ddeepptthh((_I_n_t_e_g_e_r))
         If the term is nested deeper than _I_n_t_e_g_e_r,  print the remainder
         as ellipses  (...).    A 0  (zero) value  (default) imposes  no
         depth limit.   This option also delimits the number  of printed
         items in a list.  Example:

         _______________________________________________________________|                                                               |

         |?- write_term(a(s(s(s(s(0)))), [a,b,c,d,e,f]),                 |
         |              [max_depth(3)]).                                 |
         |a(s(s(...)), [a, b|...])                                       |
         |true.|________________________________________________________ |     |

         Used  by   the  top   level  and  debugger   to  limit   screen
         output.   See  also the  Prolog flags  answer_write_options and
         debugger_write_options.

    mmoodduullee((_M_o_d_u_l_e))
         Define the reference module  (default user).  This  defines the
         default value for  the character_escapes option as well as  the
         operator definitions to use.  See also op/3.

    nnll((_B_o_o_l))
         Add a newline to the output.  See also the fullstop option.

    nnuummbbeerrvvaarrss((_B_o_o_l))
         If  true, terms  of  the  format $VAR(N),  where  _N is  a  non-
         negative integer, will be written as a variable name.   If _N is
         an atom it  is written without quotes.   This extension  allows
         for writing variables  with user-provided names.   The  default
         is false.  See also numbervars/3 and the option variable_names.

    ppaarrttiiaall((_B_o_o_l))
         If true (default  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
         write_value(.) writes  .., which  cannot be  read.   By  adding
         partial(_t_r_u_e)  to the  option  list,  it correctly  emits  . ..
         Similar problems appear when emitting operators  using multiple
         calls to write_term/3.

         _______________________________________________________________|                                                               |
         |write_value(Value) :-                                          |
         |        write_term(Value, [partial(true)]),                    |

         ||_______write('.'),_nl._______________________________________ ||

    ppoorrttrraayy((_B_o_o_l))
         Same as portrayed(_B_o_o_l).  Deprecated.

    ppoorrttrraayy__ggooaall((_:_G_o_a_l))
         Implies portray(_t_r_u_e),  but calls _G_o_a_l  rather than the  prede-
         fined hook  portray/1.   _G_o_a_l is called  through call/3,  where
         the first  argument  is _G_o_a_l,  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 priority  that
         reflects the current priority.

    ppoorrttrraayyeedd((_B_o_o_l))
         If true, the  hook portray/1 is  called before printing a  term
         that is not  a variable.   If portray/1  succeeds, the term  is
         considered printed.  See  also print/1.  The default  is false.
         This option is an extension to the ISO write_term options.

    pprriioorriittyy((_I_n_t_e_g_e_r))
         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:

         _______________________________________________________________|                                                               |
         |        format('~w = ', [VarName]),                            |
         ||_______write_term(Value,_[quoted(true),_priority(699)])______ ||

    qquuootteedd((_B_o_o_l))
         If true, atoms  and functors that  need quotes will be  quoted.
         The default is false.

    ssppaacciinngg((_+_S_p_a_c_i_n_g))
         Determines whether  and where  extra  white space  is added  to
         enhance readability.    The default  is  standard, adding  only
         space  where needed  for  proper  tokenization by  read_term/3.
         Currently,  the only  other value  is  next_argument,  adding  a
         space after  a comma used  to separate arguments  in a term  or
         list.

    vvaarriiaabbllee__nnaammeess((_+_L_i_s_t))
         Assign names to  variables in _T_e_r_m.   _L_i_s_t  is a list of  terms
         _N_a_m_e = _V_a_r,  where _N_a_m_e  is  an atom  that represents  a  valid
         Prolog  variable name.    Terms  where _V_a_r  is  bound or  is  a
         variable that does not appear  in _T_e_r_m are ignored.   Raises an
         error if _L_i_s_t is not  a list, one of the members is not  a term
         _N_a_m_e = _V_a_r, _N_a_m_e is  not an atom or  _N_a_m_e does not represent  a
         valid Prolog variable name.

         The implementation  binds the  variables  from _L_i_s_t  to a  term
         '$VAR'(_N_a_m_e).  Like write_canonical/1, terms that where already
         bound to  '$VAR'(_X) before  write_term/2 are printed  normally,
         unless the option  numbervars(_t_r_u_e) is also  provided.  If  the
         option numbervars(_t_r_u_e)  is used, the  user is responsible  for
         avoiding collisions between assigned names and  numbered names.
         See also the variable_names option of read_term/2.

         Possible variable attributes (see section ????) are ignored.   In
         most cases  one should  use copy_term/3 to obtain  a copy  that
         is  free of  attributed  variables  and handle  the  associated
         constraints as appropriate for the use-case.


wwrriittee__tteerrmm((_+_S_t_r_e_a_m_, _+_T_e_r_m_, _+_O_p_t_i_o_n_s))                               _[_I_S_O_]
    As  write_term/2,  but output  is sent  to  _S_t_r_e_a_m rather  than  the
    current output.


wwrriittee__lleennggtthh((_+_T_e_r_m_, _-_L_e_n_g_t_h_, _+_O_p_t_i_o_n_s))                         _[_s_e_m_i_d_e_t_]
    True   when  _L_e_n_g_t_h  is  the   number  of  characters  emitted   for
    _w_r_i_t_e___t_e_r_mTerm,  Options.     In  addition  to   valid  options  for
    write_term/2, it processes the option:

    mmaaxx__lleennggtthh((_+_M_a_x_L_e_n_g_t_h))
         If provided,  fail if  _L_e_n_g_t_h would be  larger than  _M_a_x_L_e_n_g_t_h.
         The implementation  ensures that  the runtime  is limited  when
         computing the length of a huge term with a bounded maximum.


wwrriittee__ccaannoonniiccaall((_+_T_e_r_m))                                             _[_I_S_O_]
    Write  _T_e_r_m  on  the current  output  stream using  standard  paren-
    thesised  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  write_term/2  using  the  options
    ignore_ops,  quoted  and  numbervars after  numbervars/4  using  the
    singletons option.

    Note  that due to the use of numbervars/4, non-ground terms  must be
    written  using a  _s_i_n_g_l_e 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 _G<NNN> identity  of the
    variables.


wwrriittee__ccaannoonniiccaall((_+_S_t_r_e_a_m_, _+_T_e_r_m))                                    _[_I_S_O_]
    Write _T_e_r_m in canonical form on _S_t_r_e_a_m.


wwrriittee((_+_T_e_r_m))                                                      _[_I_S_O_]
    Write  _T_e_r_m  to the  current output,  using  brackets and  operators
    where appropriate.


wwrriittee((_+_S_t_r_e_a_m_, _+_T_e_r_m))                                             _[_I_S_O_]
    Write _T_e_r_m to _S_t_r_e_a_m.


wwrriitteeqq((_+_T_e_r_m))                                                     _[_I_S_O_]
    Write  _T_e_r_m  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 read/1  provided
    the currently active operator declarations are identical.


wwrriitteeqq((_+_S_t_r_e_a_m_, _+_T_e_r_m))                                            _[_I_S_O_]
    Write _T_e_r_m to _S_t_r_e_a_m, inserting quotes.


wwrriitteellnn((_+_T_e_r_m))
    Equivalent to write(Term), nl..   The output stream is locked, which
    implies  no output from  other threads can  appear between the  term
    and newline.


wwrriitteellnn((_+_S_t_r_e_a_m_, _+_T_e_r_m))
    Equivalent  to write(Stream, Term), nl(Stream)..  The  output stream
    is  locked, which implies  no output from  other threads can  appear
    between the term and newline.


pprriinntt((_+_T_e_r_m))
    Print a term for  debugging purposes.  The predicate print/1 acts as
    if defined as below.

    ____________________________________________________________________|                                                                    |
    | print(Term) :-                                                     |
    |     current_prolog_flag(print_write_options, Options), !,          |
    |     write_term(Term, Options).                                     |

    | print(Term) :-                                                     |
    |     write_term(Term, [ portray(true),                              |
    |                        numbervars(true),                           |
    |                        quoted(true)                                |
    ||_____________________]).__________________________________________ ||

    The  print/1  predicate  is used  primarily  through the  ~p  escape
    sequence  of format/2, which is  commonly used in the recipies  used
    by print_message/2 to emit messages.

    The  classical definition  of this  predicate is  equivalent to  the
    ISO  predicate  write_term/2  using the  options  portray(_t_r_u_e)  and
    numbervars(_t_r_u_e).    The  portray(_t_r_u_e) option  allows  the user  to
    implement  application-specific  printing  of terms  printed  during
    debugging to facilitate  easy understanding of the output.  See also
    portray/1  and portray_text.   SWI-Prolog  adds quoted(_t_r_u_e) to  (1)
    facilitate  the copying/pasting  of terms that  are not affected  by
    portray/1  and to (2)  allow numbers, atoms  and strings to be  more
    easily distinguished, e.g., 42, '42' and "42".


pprriinntt((_+_S_t_r_e_a_m_, _+_T_e_r_m))
    Print _T_e_r_m to _S_t_r_e_a_m.


ppoorrttrraayy((_+_T_e_r_m))
    A dynamic predicate, which  can be defined by the user to change the
    behaviour  of print/1 on (sub)terms.   For each subterm  encountered
    that is not  a variable print/1 first calls portray/1 using the term
    as  argument.   For  lists, only  the list as  a whole  is given  to
    portray/1.   If portray/1 succeeds print/1 assumes the term has been
    written.


rreeaadd((_-_T_e_r_m))                                                       _[_I_S_O_]
    Read  the next Prolog term from  the current input stream and  unify
    it  with _T_e_r_m.  On a syntax error read/1 displays an  error message,
    attempts  to  skip  the erroneous  term  and  fails.    On  reaching
    end-of-file _T_e_r_m is unified with the atom end_of_file.


rreeaadd((_+_S_t_r_e_a_m_, _-_T_e_r_m))                                              _[_I_S_O_]
    Read _T_e_r_m from _S_t_r_e_a_m.


rreeaadd__ccllaauussee((_+_S_t_r_e_a_m_, _-_T_e_r_m_, _+_O_p_t_i_o_n_s))
    Equivalent  to  read_term/3,  but  sets  options  according  to  the
    current  compilation  context  and  optionally  processes  comments.
    Defined options:

    ssyynnttaaxx__eerrrroorrss((_+_A_t_o_m))
         See read_term/3, but the default is dec10 (report and restart).

    tteerrmm__ppoossiittiioonn((_-_T_e_r_m_P_o_s))
         Same as for read_term/3.

    ssuubbtteerrmm__ppoossiittiioonnss((_-_T_e_r_m_P_o_s))
         Same as for read_term/3.

    vvaarriiaabbllee__nnaammeess((_-_B_i_n_d_i_n_g_s))
         Same as for read_term/3.

    pprroocceessss__ccoommmmeenntt((_+_B_o_o_l_e_a_n))
         If true (default),  call prolog:comment_hook(_C_o_m_m_e_n_t_s_,  _T_e_r_m_P_o_s_,
         _T_e_r_m)   if  this   multifile   hook   is  defined   (see   pro-
         log:comment_hook/3).  This is used to drive PlDoc.

    ccoommmmeennttss((_-_C_o_m_m_e_n_t_s))
         If  provided,  unify _C_o_m_m_e_n_t_s  with  the  comments  encountered
         while   reading   _T_e_r_m.         This   option   implies    pro-
         cess_comment(_f_a_l_s_e).

    The singletons  option of read_term/3is  initialised from the active
    style-checking  mode.    The  module option  is initialised  to  the
    current compilation module (see prolog_load_context/2).


rreeaadd__tteerrmm((_-_T_e_r_m_, _+_O_p_t_i_o_n_s))                                         _[_I_S_O_]
    Read  a term from the current  input stream and unify the term  with
    _T_e_r_m.    The  reading is  controlled  by options  from the  list  of
    _O_p_t_i_o_n_s.   If this list is  empty, the behaviour is the same  as for
    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 catch/3).
    Options:

    bbaacckkqquuootteedd__ssttrriinngg((_B_o_o_l))
         If true, read `...` to  a string object (see section ????).   The
         default depends on the Prolog flag back_quotes.

    cchhaarraacctteerr__eessccaappeess((_B_o_o_l))
         Defines how to  read \ escape sequences  in quoted atoms.   See
         the  Prolog  flag  character_escapes in  current_prolog_flag/2.
         (SWI-Prolog).

    ccoommmmeennttss((_-_C_o_m_m_e_n_t_s))
         Unify _C_o_m_m_e_n_t_s with a list of _P_o_s_i_t_i_o_n-_C_o_m_m_e_n_t,  where _P_o_s_i_t_i_o_n
         is  a  stream   position  object  (see  stream_position_data/3)
         indicating the  start  of a  comment and  _C_o_m_m_e_n_t  is a  string
         object containing the  text including delimiters of a  comment.
         It returns all comments from where the read_term/2 call started
         up to the end of the term read.

    ccyycclleess((_B_o_o_l))
         If true (default  false), re-instantiate templates as  produced
         by  the corresponding  write_term/2  option.    Note  that  the
         default  is false  to  avoid misinterpretation  of  @(_T_e_m_p_l_a_t_e_,
         _S_u_b_s_t_u_t_i_o_n_s), while the default of write_term/2 is 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).

    ddoottlliissttss((_B_o_o_l))
         If true (default false), read .(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 write_canonical/1
         from other Prolog systems.  See section ????.

    ddoouubbllee__qquuootteess((_A_t_o_m))
         Defines  how to  read  "..." strings.     See the  Prolog  flag
         double_quotes.  (SWI-Prolog).

    mmoodduullee((_M_o_d_u_l_e))
         Specify  _M_o_d_u_l_e  for  operators,   character_escapes  flag  and
         double_quotes flag.  The  value of the latter two is  overruled
         if the  corresponding read_term/3 option  is provided.   If  no
         module  is specified,  the  current  `source module'  is  used.
         (SWI-Prolog).

    qquuaassii__qquuoottaattiioonnss((_-_L_i_s_t))
         If present,  unify  _L_i_s_t with  the quasi  quotations (see  sec-
         tion ????) instead  of evaluating quasi  quotations.  Each  quasi
         quotation is a term  quasi_quotation(_+_S_y_n_t_a_x_, _+_Q_u_o_t_a_t_i_o_n_,  _+_V_a_r_-
         _D_i_c_t_, _-_R_e_s_u_l_t),  where _S_y_n_t_a_x  is the  term in  {|Syntax||..|},
         _Q_u_o_t_a_t_i_o_n  is a  list of  character  codes that  represent  the
         quotation, _V_a_r_D_i_c_t is a  list of _N_a_m_e=_V_a_r_i_a_b_l_e and _R_e_s_u_l_t  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.

    ssiinngglleettoonnss((_V_a_r_s))
         As variable_names,  but only  reports  the variables  occurring
         only  once in  the  _T_e_r_m read.     Variables starting  with  an
         underscore (`_')  are not included  in this  list.   (ISO).  If
         _V_a_r_s is the constant warning, singleton variables  are reported
         using print_message/2.  The variables appear in the  order they
         have been read.

    ssyynnttaaxx__eerrrroorrss((_A_t_o_m))
         If error  (default),  throw  an exception  on a  syntax  error.
         Other values  are fail, which  causes a  message to be  printed
         using print_message/2, after which  the predicate fails,  quiet
         which causes the  predicate to fail  silently, and dec10  which
         causes syntax errors to be printed, after which read_term/[2,3]
         continues reading the next term.   Using dec10, read_term/[2,3]
         never fails.  (Quintus, SICStus).

    ssuubbtteerrmm__ppoossiittiioonnss((_T_e_r_m_P_o_s))
         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.

         _F_r_o_m--_T_o
             Used for primitive types (atoms, numbers, variables).

         ssttrriinngg__ppoossiittiioonn((_F_r_o_m_, _T_o))
             Used  to indicate  the  position of  a string  enclosed  in
             double quotes (").

         bbrraaccee__tteerrmm__ppoossiittiioonn((_F_r_o_m_, _T_o_, _A_r_g))
             Term  of  the form  {...},  as used  in  DCG  rules.    _A_r_g
             describes the argument.

         lliisstt__ppoossiittiioonn((_F_r_o_m_, _T_o_, _E_l_m_s_, _T_a_i_l))
             A  list.   _E_l_m_s describes  the positions  of the  elements.
             If  the list  specifies the  tail as  |<TailTerm>, _T_a_i_l  is
             unified with the term position  of the tail, otherwise with
             the atom none.

         tteerrmm__ppoossiittiioonn((_F_r_o_m_, _T_o_, _F_F_r_o_m_, _F_T_o_, _S_u_b_P_o_s))
             Used  for a compound  term not matching  one of the  above.
             _F_F_r_o_m  and  _F_T_o  describe  the  position  of  the  functor.
             _S_u_b_P_o_s is a list, each element  of which describes the term
             position of the corresponding subterm.

         ddiicctt__ppoossiittiioonn((_F_r_o_m_, _T_o_, _T_a_g_F_r_o_m_, _T_a_g_T_o_, _K_e_y_V_a_l_u_e_P_o_s_L_i_s_t))
             Used  for  a  dict (see  section  ????).    The  position  of
             the  key-value  pairs  is   described  by  _K_e_y_V_a_l_u_e_P_o_s_L_i_s_t,
             which  is  a  list  of  key_value_position/7 terms.     The
             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.

         kkeeyy__vvaalluuee__ppoossiittiioonn((_F_r_o_m_, _T_o_, _S_e_p_F_r_o_m_, _S_e_p_T_o_, _K_e_y_, _K_e_y_P_o_s_, _V_a_l_u_e_P_o_s))
             Used  for key-value pairs in  a map (see  section ????).   It
             is  similar to the  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 _K_e_y to enable
             synchronisation  of the  file position data  with the  data
             structure.

         ppaarreenntthheesseess__tteerrmm__ppoossiittiioonn((_F_r_o_m_, _T_o_, _C_o_n_t_e_n_t_P_o_s))
             Used for  terms between parentheses.  This is  an extension
             compared  to the  original Quintus  specification that  was
             considered necessary for secure refactoring of terms.

         qquuaassii__qquuoottaattiioonn__ppoossiittiioonn((_F_r_o_m_, _T_o_, _S_y_n_t_a_x_F_r_o_m_, _S_y_n_t_a_x_T_o_, _C_o_n_t_e_n_t_P_o_s))
             Used for quasi quotations.

    tteerrmm__ppoossiittiioonn((_P_o_s))
         Unifies _P_o_s with the starting  position of the term read.   _P_o_s
         is of the same format as used by stream_property/2.

    vvaarr__pprreeffiixx((_B_o_o_l))
         If true,  demand variables to  start with an  underscore.   See
         section ????.

    vvaarriiaabblleess((_V_a_r_s))
         Unify  _V_a_r_s  with a  list  of  variables  in the  term.     The
         variables appear in  the order they have  been read.  See  also
         term_variables/2.  (ISO).

    vvaarriiaabbllee__nnaammeess((_V_a_r_s))
         Unify _V_a_r_s with a list  of `_N_a_m_e = _V_a_r', where _N_a_m_e is  an atom
         describing the variable name and _V_a_r is a  variable that shares
         with the corresponding variable in _T_e_r_m.   (ISO). The variables
         appear in the order they have been read.


rreeaadd__tteerrmm((_+_S_t_r_e_a_m_, _-_T_e_r_m_, _+_O_p_t_i_o_n_s))                                _[_I_S_O_]
    Read term with options from _S_t_r_e_a_m.  See read_term/2.


rreeaadd__tteerrmm__ffrroomm__aattoomm((_+_A_t_o_m_, _-_T_e_r_m_, _+_O_p_t_i_o_n_s))
    Use  read_term/3 to read the  next term from _A_t_o_m.   _A_t_o_m is  either
    an  atom or a string  object (see section ????).   It is not  required
    for  _A_t_o_m  to end  with  a full-stop.    This  predicate  supersedes
    atom_to_term/3.


rreeaadd__hhiissttoorryy((_+_S_h_o_w_, _+_H_e_l_p_, _+_S_p_e_c_i_a_l_, _+_P_r_o_m_p_t_, _-_T_e_r_m_, _-_B_i_n_d_i_n_g_s))
    Similar  to read_term/2 using the option variable_names, but  allows
    for history  substitutions.  read_history/6is used  by the top level
    to  read the user's actions.   _S_h_o_w is  the command the user  should
    type  to show  the saved  events.   _H_e_l_p is  the command  to get  an
    overview  of the capabilities.   _S_p_e_c_i_a_l is a list of commands  that
    are  not saved in the  history.  _P_r_o_m_p_t  is the first prompt  given.
    Continuation  prompts for  more  lines are  determined by  prompt/2.
    A  %w  in the  prompt  is substituted  by  the event  number.    See
    section ???? for available substitutions.

    SWI-Prolog calls read_history/6 as follows:

    ____________________________________________________________________|                                                                    |
    ||read_history(h,_'!h',_[trace],_'%w_?-_',_Goal,_Bindings)__________ ||


pprroommpptt((_-_O_l_d_, _+_N_e_w))
    Set  prompt associated  with read/1  and its  derivatives.   _O_l_d  is
    first  unified with the current prompt.  On success the  prompt will
    be  set to _N_e_w 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 _u_s_e_r.


pprroommpptt11((_+_P_r_o_m_p_t))
    Sets  the prompt for the next line  to be read.   Continuation lines
    will be read using the prompt defined by prompt/2.


44..2211 AAnnaallyyssiinngg aanndd CCoonnssttrruuccttiinngg TTeerrmmss


ffuunnccttoorr((_?_T_e_r_m_, _?_N_a_m_e_, _?_A_r_i_t_y))                                     _[_I_S_O_]
    True  when _T_e_r_m is  a term with  functor _N_a_m_e/_A_r_i_t_y.   If _T_e_r_m is  a
    variable  it is  unified with  a new  term whose  arguments are  all
    different variables (such a  term is called a skeleton).  If _T_e_r_m is
    atomic,  _A_r_i_t_y will be unified with the integer 0, and _N_a_m_e  will be
    unified  with _T_e_r_m.   Raises instantiation_error if _T_e_r_m is  unbound
    and _N_a_m_e/_A_r_i_t_y is insufficiently instantiated.

    SWI-Prolog   also  supports   terms  with   arity  0,   as  in   a()
    (see   section  ????.       Such   terms  must   be  processed   using
    compound_name_arity/3.   The predicate functor/3  and =../2 raise  a
    domain_error when faced with these terms.   Without this precaution,
    the inconsistency demonstrated below could happen silently.

    ____________________________________________________________________|                                                                    |
    | ?- functor(a(), N, A).                                             |

    | N = a, A = 0.                                                      |
    | ?- functor(T, a, 0).                                               |
    ||T_=_a.____________________________________________________________ ||


aarrgg((_?_A_r_g_, _+_T_e_r_m_, _?_V_a_l_u_e))                                          _[_I_S_O_]
    _T_e_r_m  should be instantiated  to a term,  _A_r_g to an integer  between
    1  and  the  arity of  _T_e_r_m.    _V_a_l_u_e  is  unified with  the  _A_r_g-th
    argument  of _T_e_r_m.   _A_r_g may also  be unbound.   In this case  _V_a_l_u_e
    will  be unified  with the  successive arguments of  the term.    On
    successful  unification, _A_r_g  is unified  with the argument  number.
    Backtracking  yields alternative  solutions.    The predicate  arg/3
    fails  silently if  _A_r_g= 0 or _A_r_g > _a_r_i_t_y and raises  the exception
    domain_error(not_less_than_zero, _A_r_g)if _A_r_g <0.


_?_T_e_r_m =.. _?_L_i_s_t                                                   _[_I_S_O_]
    _L_i_s_t  is a list whose head is the functor of _T_e_r_m 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'.

    ____________________________________________________________________|                                                                    |
    | ?- foo(hello, X) =.. List.                                         |
    | List = [foo, hello, X]                                             |
    |                                                                    |

    | ?- Term =.. [baz, foo(1)].                                         |
    ||Term_=_baz(foo(1))________________________________________________ ||

    SWI-Prolog   also  supports   terms  with   arity  0,   as  in   a()
    (see   section  ????.       Such   terms  must   be  processed   using
    compound_name_arguments/3.  This predicate raises a  domain error as
    shown below.  See also functor/3.

    ____________________________________________________________________|                                                                    |
    | ?- a() =.. L.                                                      |
    ||ERROR:_Domain_error:_`compound_non_zero_arity'_expected,_found_`a()'||_


ccoommppoouunndd__nnaammee__aarriittyy((_?_C_o_m_p_o_u_n_d_, _?_N_a_m_e_, _?_A_r_i_t_y))
    Rationalized  version  of functor/3  that  only works  for  compound
    terms and can  examine and create compound terms with zero arguments
    (e.g, name().  See also compound_name_arguments/3.


ccoommppoouunndd__nnaammee__aarrgguummeennttss((_?_C_o_m_p_o_u_n_d_, _?_N_a_m_e_, _?_A_r_g_u_m_e_n_t_s))
    Rationalized  version of =../2 that  can compose and decompose  com-
    pound terms with zero arguments.  See also compound_name_arity/3.


nnuummbbeerrvvaarrss((_+_T_e_r_m_, _+_S_t_a_r_t_, _-_E_n_d))
    Unify  the free variables  in _T_e_r_m with a  term $VAR(_N), where _N  is
    the  number of  the variable.   Counting starts  at _S_t_a_r_t.   _E_n_d  is
    unified  with the number that should be given to the  next variable.
    The  example below illustrates this.  Note that the  toplevel prints
    '$VAR'(0)  as _A  due to  the numbervars(_t_r_u_e) option  used to  print
    answers.

    ____________________________________________________________________|                                                                    |
    | ?- 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.__________________________________________________________ ||

    See also the numbervars option to write_term/3 and numbervars/4.


nnuummbbeerrvvaarrss((_+_T_e_r_m_, _+_S_t_a_r_t_, _-_E_n_d_, _+_O_p_t_i_o_n_s))
    As numbervars/3, providing the following options:

    ffuunnccttoorr__nnaammee((_+_A_t_o_m))
         Name of the functor to use instead of $VAR.

    aattttvvaarr((_+_A_c_t_i_o_n))
         What to do if  an attributed variable is encountered.   Options
         are skip,  which causes numbervars/3  to ignore the  attributed
         variable,  bind  which  causes  it to  treat  it  as  a  normal
         variable  and  assign  the  next  '$VAR'(N)  term  to  it,   or
         (default) error which raises a type_error exception.

    ssiinngglleettoonnss((_+_B_o_o_l))
         If true  (default false),  numbervars/4  does singleton  detec-
         tion.    Singleton  variables  are  unified  with  '$VAR'('_'),
         causing  them  to  be  printed  as   _  by  write_term/2  using
         the  numbervars  option.      This   option  is  exploited   by
         portray_clause/2 and write_canonical/2.


vvaarr__nnuummbbeerr((_@_T_e_r_m_, _-_V_a_r_N_u_m_b_e_r))
    True  if  _T_e_r_m is  numbered  by numbervars/3  and _V_a_r_N_u_m_b_e_r  is  the
    number  given to this variable.  This predicate avoids the  need for
    unification  with '$VAR'(X)  and opens the  path for replacing  this
    valid Prolog term  by an internal representation that has no textual
    equivalent.


tteerrmm__vvaarriiaabblleess((_+_T_e_r_m_, _-_L_i_s_t))                                       _[_I_S_O_]
    Unify  _L_i_s_t with  a list of  variables, each  sharing with a  unique
    variable  of _T_e_r_m.   The variables in _L_i_s_t  are ordered in order  of
    appearance traversing _T_e_r_m  depth-first and left-to-right.  See also
    term_variables/3 and nonground/2.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- term_variables(a(X, b(Y, X), Z), L).                            |

    ||L_=_[X,_Y,_Z].____________________________________________________ ||


nnoonnggrroouunndd((_+_T_e_r_m_, _-_V_a_r))                                        _[_s_e_m_i_d_e_t_]
    True  when _V_a_r is a variable in _T_e_r_m.  Fails if _T_e_r_m  is _g_r_o_u_n_d (see
    ground/1).   This predicate is intended for coroutining to trigger a
    wakeup  if _T_e_r_m  becomes ground, e.g.,  using 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 term_variables/2)  to realise  logarithmetic
    complexity  for the  ground trigger.   Compatible  with ECLiPSe  and
    hProlog.


tteerrmm__vvaarriiaabblleess((_+_T_e_r_m_, _-_L_i_s_t_, _?_T_a_i_l))
    Difference  list version of term_variables/2.  That is, _T_a_i_l  is the
    tail of the variable list _L_i_s_t.


tteerrmm__ssiinngglleettoonnss((_+_T_e_r_m_, _-_L_i_s_t))
    Unify  _L_i_s_t with a list of  variables, each sharing with a  variable
    that  appears only once in _T_e_r_m.   Note that, if a  variable appears
    in  a shared subterm, it  is _n_o_t considered singleton.   Thus, _A  is
    _n_o_t  a singleton  in  the example  below.   See  also the  singleton
    option of numbervars/4.

    ____________________________________________________________________|                                                                    |
    |                                                                    |

    | ?- S = a(A), term_singletons(t(S,S), L).                           |
    ||L_=_[].___________________________________________________________ ||


ccooppyy__tteerrmm((_+_I_n_, _-_O_u_t))                                               _[_I_S_O_]
    Create  a version  of _I_n  with renamed (fresh)  variables and  unify
    it  to  _O_u_t.    Attributed variables  (see  section ????)  have  their
    attributes  copied.    The  implementation of  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  _s_h_a_r_e_d between  _I_n and  _O_u_t.
    Sharing  ground terms  does affect  setarg/3.   SWI-Prolog  provides
    duplicate_term/2 to create a true copy of a term.


44..2211..11 NNoonn--llooggiiccaall ooppeerraattiioonnss oonn tteerrmmss

Prolog is  not able to  _m_o_d_i_f_y 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 section  ????,
discussing the use of global variables.


sseettaarrgg((_+_A_r_g_, _+_T_e_r_m_, _+_V_a_l_u_e))
    Extra-logical  predicate.     Assigns the  _A_r_g-th  argument  of  the
    compound  term _T_e_r_m with the given _V_a_l_u_e.  The assignment  is undone
    if  backtracking brings the  state back into  a position before  the
    setarg/3 call.  See also 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  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  setarg/3 have  one  unused and  unshared
    variable  in addition to the used  arguments.  This variable  avoids
    unwanted  sharing in, e.g., copy_term/2,  and causes the term to  be
    considered  as non-ground.   An alternative is to  use put_attr/3 to
    attach information to attributed variables (see section ????).


nnbb__sseettaarrgg((_+_A_r_g_, _+_T_e_r_m_, _+_V_a_l_u_e))
    Assigns  the _A_r_g-th  argument  of the  compound term  _T_e_r_m with  the
    given  _V_a_l_u_e  as  setarg/3,   but  on  backtracking  the  assignment
    is  _n_o_t  reversed.    If  _V_a_l_u_e  is not  atomic,  it  is  duplicated
    using  duplicate_term/2.   This  predicate uses  the same  technique
    as  nb_setval/2.     We  therefore  refer   to  the  description  of
    nb_setval/2  for details on  non-backtrackable assignment of  terms.
    This  predicate is  compatible with GNU-Prolog  setarg(_A_,_T_,_V_,_f_a_l_s_e),
    removing  the type  restriction on  _V_a_l_u_e.   See  also 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 flag/3  is
    much more complicated.

    ____________________________________________________________________|                                                                    |
    | :- 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)                                 |
    ||________).________________________________________________________ ||


nnbb__lliinnkkaarrgg((_+_A_r_g_, _+_T_e_r_m_, _+_V_a_l_u_e))
    As  nb_setarg/3,  but like nb_linkval/2 it does _n_o_t duplicate  _V_a_l_u_e.
    Use with  extreme care and consult the documentation of nb_linkval/2
    before use.


dduupplliiccaattee__tteerrmm((_+_I_n_, _-_O_u_t))
    Version  of copy_term/2 that also copies ground terms  and therefore
    ensures  that  destructive  modification  using  setarg/3  does  not
    affect  the copy.   See also  nb_setval/2,  nb_linkval/2, nb_setarg/3
    and nb_linkarg/3.


ssaammee__tteerrmm((_@_T_1_, _@_T_2))                                            _[_s_e_m_i_d_e_t_]
    True  if _T_1 and _T_2 are  equivalent and will remain equivalent,  even
    if  setarg/3 is  used  on either  of them.    This means  _T_1 and  _T_2
    are  the same variable,  equivalent atomic data  or a compound  term
    allocated at the same address.


44..2222 AAnnaallyyssiinngg aanndd CCoonnssttrruuccttiinngg AAttoommss

These  predicates  convert   between  Prolog  constants  and  lists   of
character codes.  The predicates atom_codes/2, number_codes/2 and name/2
behave the same when  converting from a constant to a list  of character
codes.     When converting  the  other  way  around,  atom_codes/2  will
generate an  atom, number_codes/2  will generate a  number or  exception
and name/2 will return a number if possible and an atom otherwise.

The ISO standard  defines 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  atom_chars/2 behaved  like atom_codes,
compatible with  Quintus and SICStus  Prolog.   As of 3.3.x,  SWI-Prolog
atom_codes/2 and atom_chars/2are 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).


aattoomm__ccooddeess((_?_A_t_o_m_, _?_S_t_r_i_n_g))                                         _[_I_S_O_]
    Convert  between an atom and a list of character codes.   If _A_t_o_m is
    instantiated,  it will be translated into a list of  character codes
    and  the result  is unified with  _S_t_r_i_n_g.   If _A_t_o_m  is unbound  and
    _S_t_r_i_n_g  is a list of character  codes, _A_t_o_m will be unified  with an
    atom constructed from this list.


aattoomm__cchhaarrss((_?_A_t_o_m_, _?_C_h_a_r_L_i_s_t))                                       _[_I_S_O_]
    As  atom_codes/2, but  _C_h_a_r_L_i_s_t  is a  list of  one-character  atoms
    rather than a list of character codes.

    ____________________________________________________________________|                                                                    |
    | ?- atom_chars(hello, X).                                           |
    |                                                                    |
    ||X_=_[h,_e,_l,_l,_o]_______________________________________________ ||


cchhaarr__ccooddee((_?_A_t_o_m_, _?_C_o_d_e))                                            _[_I_S_O_]
    Convert  between character and character  code for a single  charac-
    ter.


nnuummbbeerr__cchhaarrss((_?_N_u_m_b_e_r_, _?_C_h_a_r_L_i_s_t))                                   _[_I_S_O_]
    Similar  to  atom_chars/2,  but  converts between  a number  and  its
    representation  as a list  of one-character atoms.   If _C_h_a_r_L_i_s_t  is
    a  _p_r_o_p_e_r _l_i_s_t,  i.e., not unbound  or a  _p_a_r_t_i_a_l _l_i_s_t, _C_h_a_r_L_i_s_t  is
    parsed according to  the Prolog syntax for numbers and the resulting
    number  is unified with _N_u_m_b_e_r.   Otherwise, if _N_u_m_b_e_r is  a number,
    _N_u_m_b_e_r is serialized and the result is unified with _C_h_a_r_L_i_s_t.

    If  _C_h_a_r_L_i_s_t is  parsed, it is  parsed using  the Prolog syntax  for
    numbers.   Following the ISO  standard, it allows for _l_e_a_d_i_n_g  white
    space  (including newlines)  and does not  allow for _t_r_a_i_l_i_n_g  white
    space.    A syntax_error exception  is raised if  _C_h_a_r_L_i_s_t does  not
    represent a valid Prolog number.


nnuummbbeerr__ccooddeess((_?_N_u_m_b_e_r_, _?_C_o_d_e_L_i_s_t))                                   _[_I_S_O_]
    As 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.


aattoomm__nnuummbbeerr((_?_A_t_o_m_, _?_N_u_m_b_e_r))
    Realises  the popular combination of atom_codes/2 and number_codes/2
    to   convert  between  atom  and   number  (integer  or  float)   in
    one  predicate,   avoiding  the  intermediate  list.     Unlike  the
    ISO  number_codes/2  predicates,  atom_number/2  fails  silently  in
    mode  (+,-)  if  _A_t_o_m  does  not  represent a  number.     See  also
    atomic_list_concat/2 for assembling an atom from atoms and numbers.


nnaammee((_?_A_t_o_m_i_c_, _?_C_o_d_e_L_i_s_t))
    _C_o_d_e_L_i_s_t  is a list  of character codes  representing the same  text
    as  _A_t_o_m_i_c.    Each of  the arguments  may be  a variable,  but  not
    both.   When _C_o_d_e_L_i_s_t describes an integer or floating  point number
    and  _A_t_o_m_i_c is a variable, _A_t_o_m_i_c  will be unified with the  numeric
    value  described by  _C_o_d_e_L_i_s_t (e.g.,  name(N, "300"), 400 is N + 100
    succeeds).    If  _C_o_d_e_L_i_s_t  is not  a  representation of  a  number,
    _A_t_o_m_i_c  will be unified  with the  atom with the  name given by  the
    character  code list.  If _A_t_o_m_i_c is an atom or number,  the unquoted
    print representation of  it as a character code list is unified with
    _C_o_d_e_L_i_s_t.

    This  predicate  is part  of the  Edinburgh tradition.    It  should
    be  considered _d_e_p_r_e_c_a_t_e_d  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 atom_codes/2,
    number_codes/2 or the SWI-Prolog predicate atom_number/2.


tteerrmm__ttoo__aattoomm((_?_T_e_r_m_, _?_A_t_o_m))
    True  if  _A_t_o_m describes  a  term  that unifies  with  _T_e_r_m.    When
    _A_t_o_m  is instantiated, _A_t_o_m  is parsed and  the result unified  with
    _T_e_r_m.    If _A_t_o_m has  no valid syntax,  a syntax_error exception  is
    raised.   Otherwise _T_e_r_m  is ``written'' on _A_t_o_m  using write_term/2
    with  the option quoted(_t_r_u_e).   See also format/3, with_output_to/2
    and term_string/2.


aattoomm__ttoo__tteerrmm((_+_A_t_o_m_, _-_T_e_r_m_, _-_B_i_n_d_i_n_g_s))                       _[_d_e_p_r_e_c_a_t_e_d_]
    Use  _A_t_o_m as  input to  read_term/2 using the  option variable_names
    and  return  the read  term in  _T_e_r_m and  the  variable bindings  in
    _B_i_n_d_i_n_g_s.   _B_i_n_d_i_n_g_s is a list of _N_a_m_e =_V_a_r couples, thus providing
    access  to the actual  variable names.   See  also read_term/2.   If
    _A_t_o_m  has no valid syntax, a syntax_error exception is raised.   New
    code should use read_term_from_atom/3.


aattoomm__ccoonnccaatt((_?_A_t_o_m_1_, _?_A_t_o_m_2_, _?_A_t_o_m_3))                                _[_I_S_O_]
    _A_t_o_m_3  forms the concatenation  of _A_t_o_m_1  and _A_t_o_m_2.   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  append/3 does  for  lists).
    SWI-Prolog  allows for  atomic arguments.   Portable  code must  use
    atomic_concat/3 if non-atom arguments are involved.


aattoommiicc__ccoonnccaatt((_+_A_t_o_m_i_c_1_, _+_A_t_o_m_i_c_2_, _-_A_t_o_m))
    _A_t_o_m  represents the  text after converting  _A_t_o_m_i_c_1 and _A_t_o_m_i_c_2  to
    text and concatenating the result:

    ____________________________________________________________________|                                                                    |
    | ?- atomic_concat(name, 42, X).                                     |

    ||X_=_name42._______________________________________________________ ||


aattoommiicc__lliisstt__ccoonnccaatt((_+_L_i_s_t_, _-_A_t_o_m))                               _[_c_o_m_m_o_n_s_]
    _L_i_s_t  is  a  list of  strings,  atoms,  integers or  floating  point
    numbers.    Succeeds if _A_t_o_m  can be  unified with the  concatenated
    elements  of  _L_i_s_t.     Equivalent to  atomic_list_concat(_L_i_s_t_,  _'_'_,
    _A_t_o_m).


aattoommiicc__lliisstt__ccoonnccaatt((_+_L_i_s_t_, _+_S_e_p_a_r_a_t_o_r_, _-_A_t_o_m))                   _[_c_o_m_m_o_n_s_]
    Creates  an atom just like atomic_list_concat/2, but  inserts _S_e_p_a_r_a_-
    _t_o_r between each pair of inputs.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- atomic_list_concat([gnu, gnat], ', ', A).                       |
    |                                                                    |
    ||A_=_'gnu,_gnat'___________________________________________________ ||

    The  SWI-Prolog version of this predicate can also be used  to split
    atoms  by  instantiating _S_e_p_a_r_a_t_o_r  and _A_t_o_m  as shown  below.    We
    kept  this functionality  to  simplify porting  old SWI-Prolog  code
    where  this  predicate  was called  concat_atom/3.    When  used  in
    mode  (-,+,+),  _S_e_p_a_r_a_t_o_r  must  be a  non-empty  atom.    See  also
    split_string/4.

    ____________________________________________________________________|                                                                    |

    | ?- atomic_list_concat(L, -, 'gnu-gnat').                           |
    |                                                                    |
    ||L_=_[gnu,_gnat]___________________________________________________ ||


aattoomm__lleennggtthh((_+_A_t_o_m_, _-_L_e_n_g_t_h))                                        _[_I_S_O_]
    True  if _A_t_o_m  is  an atom  of _L_e_n_g_t_h  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
    write_length/3  to  get  the  number of  characters  that  would  be
    written if the argument was handed to write_term/3.


aattoomm__pprreeffiixx((_+_A_t_o_m_, _+_P_r_e_f_i_x))                                 _[_d_e_p_r_e_c_a_t_e_d_]
    True if _A_t_o_m starts  with the characters from _P_r_e_f_i_x.  Its behaviour
    is equivalent to ?- sub_atom(_A_t_o_m, 0, _, _, _P_r_e_f_i_x).  Deprecated.


ssuubb__aattoomm((_+_A_t_o_m_, _?_B_e_f_o_r_e_, _?_L_e_n_, _?_A_f_t_e_r_, _?_S_u_b))                       _[_I_S_O_]
    ISO  predicate  for breaking  atoms.    It maintains  the  following
    relation:  _S_u_b is  a sub-atom of _A_t_o_m that starts at _B_e_f_o_r_e, has _L_e_n
    characters, and _A_t_o_m contains _A_f_t_e_r characters after the match.

    ____________________________________________________________________|                                                                    |
    | ?- sub_atom(abc, 1, 1, A, S).                                      |
    |                                                                    |

    ||A_=_1,_S_=_b______________________________________________________ ||

    The implementation  minimises non-determinism and creation of atoms.
    This  is  a  flexible predicate  that  can do  search,  prefix-  and
    suffix-matching, etc.


ssuubb__aattoomm__iiccaasseecchhkk((_+_H_a_y_s_t_a_c_k_, _?_S_t_a_r_t_, _+_N_e_e_d_l_e))                  _[_s_e_m_i_d_e_t_]
    True  when _N_e_e_d_l_e is a sub atom of _H_a_y_s_t_a_c_k starting at _S_t_a_r_t.   The
    match is `half  case insensitive', i.e., uppercase letters in _N_e_e_d_l_e
    only match themselves,  while lowercase letters in _N_e_e_d_l_e match case
    insensitively.   _S_t_a_r_t is  the first 0-based offset inside  _H_a_y_s_t_a_c_k
    where _N_e_e_d_l_e matches.


44..2233 LLooccaalliizzaattiioonn ((llooccaallee)) ssuuppppoorrtt

SWI-Prolog   provides   (currently  limited)   support   for   localized
applications.

  o The  predicates char_type/2 and code_type/2 query character  classes
    depending on the locale.

  o The  predicates collation_key/2  and locale_sort/2 can  be used  for
    locale dependent sorting of atoms.

  o The  predicate format_time/3  can be used  to format  time and  date
    representations, where some of the specifiers are locale dependent.

  o The   predicate  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.

A  locale  is  a  (optionally  named)  read-only  object  that  provides
information to locale specific functions.  The system  creates a default
locale object  named default  from the system  locale.   This locale  is
used as  the initial locale  for the three standard  streams as well  as
the main thread.   Locale sensitive  output predicates such as  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.


llooccaallee__ccrreeaattee((_-_L_o_c_a_l_e_, _+_D_e_f_a_u_l_t_, _+_O_p_t_i_o_n_s))
    Create  a new locale object.   _D_e_f_a_u_l_t is either an existing  locale
    or  a string  that  denotes the  name of  a locale  provided by  the
    system,  such as "en_EN.UTF-8".   The  values read from the  default
    locale can be modified using _O_p_t_i_o_n_s.  _O_p_t_i_o_n_s provided are:

    aalliiaass((_+_A_t_o_m))
         Give the locale a name.

    ddeecciimmaall__ppooiinntt((_+_A_t_o_m))
         Specify the decimal point to use.

    tthhoouussaannddss__sseepp((_+_A_t_o_m))
         Specify the string that delimits digit groups.   Only effective
         is grouping is also specified.

    ggrroouuppiinngg((_+_L_i_s_t))
         Specify the grouping  of digits.   Groups are created from  the
         right (least  significant) digits, left  of the decimal  point.
         _L_i_s_t is a list of integers, specifying the number  of digits in
         each group, counting  from the right.   If the last element  is
         repeat(_C_o_u_n_t), the  remaining digits are  grouped in groups  of
         size _C_o_u_n_t.   If the last element  is a normal integer,  digits
         further to the left are not grouped.

    For example, the English locale uses

    ____________________________________________________________________|                                                                    |

    ||[_decimal_point('.'),_thousands_sep(','),_grouping([repeat(3)])_]_ ||

    Named    locales   exists   until    they   are   destroyed    using
    locale_destroy/1  and   they  are  no   longer  referenced.      Un-
    named locales are subject to (atom) garbage collection.


llooccaallee__ddeessttrrooyy((_+_L_o_c_a_l_e))
    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.


llooccaallee__pprrooppeerrttyy((_?_L_o_c_a_l_e_, _?_P_r_o_p_e_r_t_y))
    True  when _L_o_c_a_l_e  has _P_r_o_p_e_r_t_y.   Properties  are the  same as  the
    _O_p_t_i_o_n_s described with locale_create/3.


sseett__llooccaallee((_+_L_o_c_a_l_e))
    Set  the  default  locale  for  the  current  thread,   as  well  as
    the  locale  for  the  standard  streams  (user_input,  user_output,
    user_error, current_output and  current_input.   This locale is  used
    for  new streams, unless  overruled using the locale(_L_o_c_a_l_e)  option
    of open/4 or set_stream/2.


ccuurrrreenntt__llooccaallee((_-_L_o_c_a_l_e))
    True when _L_o_c_a_l_e is the locale of the calling thread.


44..2244 CChhaarraacctteerr pprrooppeerrttiieess

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  _l_o_c_a_l_e  (handling  of  local  character  sets).      These
predicates are fast, logical and deterministic if applicable.

In addition,  there is the  library ctypes providing compatibility  with
some other Prolog systems.   The predicates of this library  are defined
in terms of code_type/2.


cchhaarr__ttyyppee((_?_C_h_a_r_, _?_T_y_p_e))
    Tests or generates  alternative _T_y_p_es or _C_h_a_rs.  The character types
    are inspired by the standard C <ctype.h>  primitives.  Note that the
    mode  (-,+) is  only efficient if  the _T_y_p_e has  a parameter,  e.g.,
    char_type(_C_,  _d_i_g_i_t_(_8_)).   With  an atomic  _T_y_p_e  the whole  unicode
    range  (0..0x1ffff) is generated and tested against the  C character
    classification function.

    aallnnuumm
         _C_h_a_r is a letter (upper- or lowercase) or digit.

    aallpphhaa
         _C_h_a_r is a letter (upper- or lowercase).

    ccssyymm
         _C_h_a_r  is a  letter  (upper- or  lowercase),  digit or  the  un-
         derscore  (_).      These  are   valid  C  and  Prolog   symbol
         characters.

    ccssyymmff
         _C_h_a_r is a letter  (upper- or lowercase) or the  underscore (_).
         These are valid first characters for C and Prolog symbols.

    aasscciiii
         _C_h_a_r is a 7-bit ASCII character (0..127).

    wwhhiittee
         _C_h_a_r is a space or tab, i.e. white space inside a line.

    ccnnttrrll
         _C_h_a_r is an ASCII  control character (0..31), ASCII DEL  charac-
         ter (127),  or  non-ASCII character  in the  range 128..159  or
         8232..8233.

    ddiiggiitt
         _C_h_a_r is a digit.

    ddiiggiitt((_W_e_i_g_h_t))
         _C_h_a_r is a digit with value _W_e_i_g_h_t.  I.e. char_type(X, digit(6))
         yields _X = '6'.  Useful for parsing numbers.

    xxddiiggiitt((_W_e_i_g_h_t))
         _C_h_a_r  is  a  hexadecimal  digit  with  value  _W_e_i_g_h_t.      I.e.
         char_type(a, xdigit(X)) yields _X  = '10'.   Useful for  parsing
         numbers.

    ggrraapphh
         _C_h_a_r produces  a visible mark  on a  page when printed.    Note
         that the space is not included!

    lloowweerr
         _C_h_a_r is a lowercase letter.

    lloowweerr((_U_p_p_e_r))
         _C_h_a_r is a  lowercase version of  _U_p_p_e_r.   Only true if _C_h_a_r  is
         lowercase and _U_p_p_e_r uppercase.

    ttoo__lloowweerr((_U_p_p_e_r))
         _C_h_a_r is  a lowercase  version of _U_p_p_e_r.    For non-letters,  or
         letter without case,  _C_h_a_r and  _L_o_w_e_r are the same.   See  also
         upcase_atom/2 and downcase_atom/2.

    uuppppeerr
         _C_h_a_r is an uppercase letter.

    uuppppeerr((_L_o_w_e_r))
         _C_h_a_r is an  uppercase version of _L_o_w_e_r.   Only true if _C_h_a_r  is
         uppercase and _L_o_w_e_r lowercase.

    ttoo__uuppppeerr((_L_o_w_e_r))
         _C_h_a_r is  an uppercase version  of _L_o_w_e_r.   For non-letters,  or
         letter without case,  _C_h_a_r and  _L_o_w_e_r are the same.   See  also
         upcase_atom/2 and downcase_atom/2.

    ppuunncctt
         _C_h_a_r is  a punctuation character.   This  is a graph  character
         that is not a letter or digit.

    ssppaaccee
         _C_h_a_r is  some  form of  layout  character (tab,  vertical  tab,
         newline, etc.).

    eenndd__ooff__ffiillee
         _C_h_a_r is -1.

    eenndd__ooff__lliinnee
         _C_h_a_r ends a line (ASCII: 10..13).

    nneewwlliinnee
         _C_h_a_r is a newline character (10).

    ppeerriioodd
         _C_h_a_r counts as the end of a sentence (.,!,?).

    qquuoottee
         _C_h_a_r is a quote character (", ', `).

    ppaarreenn((_C_l_o_s_e))
         _C_h_a_r is  an open  parenthesis  and _C_l_o_s_e  is the  corresponding
         close parenthesis.

    pprroolloogg__vvaarr__ssttaarrtt
         _C_h_a_r can start a Prolog variable name.

    pprroolloogg__aattoomm__ssttaarrtt
         _C_h_a_r can start a unquoted Prolog atom that is not a symbol.

    pprroolloogg__iiddeennttiiffiieerr__ccoonnttiinnuuee
         _C_h_a_r can continue a Prolog variable name or atom.

    pprroolloogg__ssyymmbbooll
         _C_h_a_r is a Prolog symbol character.  Sequences  of Prolog symbol
         characters glue together  to form an  unquoted atom.   Examples
         are =.., \=, etc.


ccooddee__ttyyppee((_?_C_o_d_e_, _?_T_y_p_e))
    As  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 double_quotes, atom_chars/2 and atom_codes/2.


44..2244..11 CCaassee ccoonnvveerrssiioonn

There is nothing in  the Prolog standard for converting case  in textual
data.    The SWI-Prolog  predicates code_type/2 and  char_type/2 can  be
used to test  and convert individual characters.   We have started  some
additional support:


ddoowwnnccaassee__aattoomm((_+_A_n_y_C_a_s_e_, _-_L_o_w_e_r_C_a_s_e))
    Converts  the characters  of _A_n_y_C_a_s_e  into lowercase  as char_type/2
    does  (i.e. based on  the defined _l_o_c_a_l_e  if Prolog provides  locale
    support  on the  hosting platform)  and unifies  the lowercase  atom
    with _L_o_w_e_r_C_a_s_e.


uuppccaassee__aattoomm((_+_A_n_y_C_a_s_e_, _-_U_p_p_e_r_C_a_s_e))
    Converts, similar to downcase_atom/2, an atom to uppercase.


44..2244..22 WWhhiittee ssppaaccee nnoorrmmaalliizzaattiioonn


nnoorrmmaalliizzee__ssppaaccee((_-_O_u_t_, _+_I_n))
    Normalize  white  space in  _I_n.    All  leading and  trailing  white
    space  is removed.  All non-empty sequences for Unicode  white space
    characters  are replaced by a single space (\u0020) character.   _O_u_t
    uses the same conventions as with_output_to/2 and format/3.


44..2244..33 LLaanngguuaaggee--ssppeecciiffiicc ccoommppaarriissoonn

This  section  deals   with  predicates  for  language-specific   string
comparison operations.


ccoollllaattiioonn__kkeeyy((_+_A_t_o_m_, _-_K_e_y))
    Create  a _K_e_y from _A_t_o_m 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  collation_key/2  is  used  by   locale_sort/2  from
    library(sort).   Please examine the  implementation of locale_sort/2
    as an example of using this call.

    The  _K_e_y  is  an  implementation-defined  and  generally  unreadable
    string.   On  systems that  do not support  locale handling, _K_e_y  is
    simply unified with _A_t_o_m.


llooccaallee__ssoorrtt((_+_L_i_s_t_, _-_S_o_r_t_e_d))
    Sort  a list of atoms using the current  locale.  _L_i_s_t is a  list of
    atoms  or string objects (see section  ????).  _S_o_r_t_e_d is unified  with
    a  list containing all  atoms of  _L_i_s_t, sorted to  the rules of  the
    current locale.  See also collation_key/2 and setlocale/3.


44..2255 OOppeerraattoorrss

Operators  are  defined  to improve  the  readability  of  source  code.
For  example, without  operators, to  write  2*3+4*5 one  would have  to
write +(*(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.

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 make  it hard to  understand the  limits of your  syntax.
To ease  the pain, as  of SWI-Prolog 3.3.0,  operators are local to  the
module  in which  they are  defined.   Operators  can  be exported  from
modules  using a  term op(_P_r_e_c_e_d_e_n_c_e_,  _T_y_p_e_,  _N_a_m_e) in  the export  list
as  specified by  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 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:

________________________________________________________________________|                                                                        |
|:- module(prove,                                                        |

|          [ prove/1                                                     |
|          ]).                                                           |
|                                                                        |
|:-|op(900,_xfx,_user:(=>)).____________________________________________ |  |

In SWI-Prolog, a _q_u_o_t_e_d  _a_t_o_m 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 section ????.


oopp((_+_P_r_e_c_e_d_e_n_c_e_, _+_T_y_p_e_, _:_N_a_m_e))                                     _[_I_S_O_]
    Declare  _N_a_m_e  to  be  an  operator of  type  _T_y_p_e  with  precedence
    _P_r_e_c_e_d_e_n_c_e.    _N_a_m_e  can also  be a  list of  names,  in which  case
    all  elements of the  list are declared  to be identical  operators.
    _P_r_e_c_e_d_e_n_c_e  is an integer between 0 and 1200.  Precedence  0 removes
    the  declaration.  _T_y_p_e  is one of:   xf, yf, xfx,  xfy, yfx, fy  or
    fx.   The `f' indicates the  position of the functor, while x  and y
    indicate  the position of the arguments.  `y' should  be interpreted
    as  ``on this position a term with precedence lower or equal  to the
    precedence  of the functor should occur''.   For `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 (...) has precedence 0.

    The  predefined operators  are shown  in table  ????.   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
    ddiiffffeerreennttllyy.   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.

      o  It is not allowed to redefine the comma (',').

      o  The bar  (|) can only  be (re-)defined  as infix operator  with
         priority not less than 1001.

      o  It  is not  allowed  to  define  the empty  list  ([])  or  the
         curly-bracket pair ({}) as operators.

    In   SWI-Prolog,  operators  are   _l_o_c_a_l  to  a  module  (see   also
    section  ????).   Keeping  operators in modules  and using  controlled
    import/export of operators  as described with the module/2 directive
    keep  the  issues  manageable.    The  module  system  provides  the
    operators  from table  ???? and  these operators  cannot be  modified.
    Files  that  are  loaded  from the  SWI-Prolog  directories  resolve
    operators  and predicates from this system module rather  than user,
    which  makes the  semantics of  the library  and development  system
    modules independent of operator changes to the user module.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |

     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic,    discontiguous,     initialization, |
     |      |     |meta_predicate,  module_transparent, multifile,|
     |      |     |public,  thread_local,   thread_initialization,|
     |      |     |volatile                                       |
     | 1100 |xfy  |;, |                                           |
     | 1050 |xfy  |->, *->                                        |
     | 1000 |xfy  |,                                              |

     |  990 |xfx  |:=                                             |
     |  900 | fy  |\+                                             |
     |  700 |xfx  |<, =, =.., =@=, \=@=, =:=, =<, ==, =\=, >, >=, |
     |      |     |@<, @=<, @>, @>=, \=, \==, as, is, >:<, :<     |
     |  600 |xfy  |:                                              |
     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |?                                              |

     |  400 | yfx |*, /, //, div, rdiv, <<, >>, mod, rem          |
     |  200 |xfx  |**                                             |
     |  200 |xfy  |^                                              |
     |  200 | fy  |+, -, \                                        |
     |  100 | yfx |.                                              |
     |____1_|_fx__|$______________________________________________|_

                      Table 4.2:  System operators


ccuurrrreenntt__oopp((_?_P_r_e_c_e_d_e_n_c_e_, _?_T_y_p_e_, _?_:_N_a_m_e))                             _[_I_S_O_]
    True  if _N_a_m_e is currently defined as an operator of type  _T_y_p_e with
    precedence _P_r_e_c_e_d_e_n_c_e.  See also op/3.


44..2266 CChhaarraacctteerr CCoonnvveerrssiioonn

Although  I  wouldn't really  know  why  you  would like  to  use  these
features, they are provided for ISO compliance.


cchhaarr__ccoonnvveerrssiioonn((_+_C_h_a_r_I_n_, _+_C_h_a_r_O_u_t))                                 _[_I_S_O_]
    Define  that term input  (see read_term/3) maps each character  read
    as  _C_h_a_r_I_n to the character _C_h_a_r_O_u_t.   Character conversion is  only
    executed  if  the Prolog  flag char_conversion is  set  to true  and
    not  inside quoted atoms  or strings.   The initial table maps  each
    character onto itself.  See also current_char_conversion/2.


ccuurrrreenntt__cchhaarr__ccoonnvveerrssiioonn((_?_C_h_a_r_I_n_, _?_C_h_a_r_O_u_t))                         _[_I_S_O_]
    Queries   the   current   character   conversion   table.        See
    char_conversion/2 for details.


44..2277 AArriitthhmmeettiicc

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 _e_x_p_r_e_s_s_i_o_n_s.   An expression is  either a simple number or  a
_f_u_n_c_t_i_o_n.  The  arguments of a function are expressions.   The functions
are described in section ????.


44..2277..11 SSppeecciiaall ppuurrppoossee iinntteeggeerr aarriitthhmmeettiicc

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.


bbeettwweeeenn((_+_L_o_w_, _+_H_i_g_h_, _?_V_a_l_u_e))
    _L_o_w  and _H_i_g_h are  integers, _H_i_g_h >=_L_o_w.   If  _V_a_l_u_e is an  integer,
    _L_o_w=< _V_a_l_u_e=< _H_i_g_h.   When _V_a_l_u_e  is a  variable it is  successively
    bound  to  all integers  between  _L_o_w and  _H_i_g_h.    If _H_i_g_h  is  inf
    or  infinite between/3 is  true iff _V_a_l_u_e>= _L_o_w,  a feature that  is
    particularly  interesting  for generating  integers from  a  certain
    value.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    True  if _I_n_t_2= _I_n_t_1+1  and _I_n_t_1>=0.   At least one of the arguments
    must  be instantiated to  a natural number.   This predicate  raises
    the  domain  error  not_less_than_zero  if  called  with  a  negative
    integer.   E.g. succ(_X_, _0)  fails silently and succ(_X_, _-_1) raises  a
    domain error.


pplluuss((_?_I_n_t_1_, _?_I_n_t_2_, _?_I_n_t_3))
    True  if _I_n_t_3 =_I_n_t_1 +_I_n_t_2.    At least two  of the  three arguments
    must be instantiated to integers.


ddiivvmmoodd((_+_D_i_v_i_d_e_n_d_, _+_D_i_v_i_s_o_r_, _-_Q_u_o_t_i_e_n_t_, _-_R_e_m_a_i_n_d_e_r))
    This  predicate is a shorthand  for computing both the _Q_u_o_t_i_e_n_t  and
    _R_e_m_a_i_n_d_e_r  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, divmod/4 is defined as below.

    ____________________________________________________________________|                                                                    |
    | divmod(Dividend, Divisor, Quotient, Remainder) :-                  |

    |         Quotient  is Dividend div Divisor,                         |
    ||________Remainder_is_Dividend_mod_Divisor.________________________ ||

    Note  that  this  predicate  is  only  available  if  SWI-Prolog  is
    compiled  with unbounded integer support.  This is the case  for all
    packaged versions.


nntthh__iinntteeggeerr__rroooott__aanndd__rreemmaaiinnddeerr((_+_N_, _+_I_, _-_R_o_o_t_, _-_R_e_m_a_i_n_d_e_r))
    True  when  Root to the power N+ Remainder= I.    _N and  _I must  be
    integers.   _N must be one or more.   If _I is negative and _N  is _o_d_d,
    _R_o_o_t  and  _R_e_m_a_i_n_d_e_r are  negative, i.e.,  the  following holds  for
    _I <0:

    ____________________________________________________________________|                                                                    |
    | %   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.__________________________________ ||


44..2277..22 GGeenneerraall ppuurrppoossee aarriitthhmmeettiicc

The  general   arithmetic  predicates   are  optionally  compiled   (see
set_prolog_flag/2  and  the   -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.


_+_E_x_p_r_1 > _+_E_x_p_r_2                                                   _[_I_S_O_]
    True if expression _E_x_p_r_1 evaluates to a larger number than _E_x_p_r_2.


_+_E_x_p_r_1 < _+_E_x_p_r_2                                                   _[_I_S_O_]
    True if expression _E_x_p_r_1 evaluates to a smaller number than _E_x_p_r_2.


_+_E_x_p_r_1 =< _+_E_x_p_r_2                                                  _[_I_S_O_]
    True  if expression _E_x_p_r_1 evaluates to a smaller or equal  number to
    _E_x_p_r_2.


_+_E_x_p_r_1 >= _+_E_x_p_r_2                                                  _[_I_S_O_]
    True  if expression _E_x_p_r_1 evaluates to  a larger or equal number  to
    _E_x_p_r_2.


_+_E_x_p_r_1 =\= _+_E_x_p_r_2                                                 _[_I_S_O_]
    True if expression _E_x_p_r_1 evaluates to a number non-equal to _E_x_p_r_2.


_+_E_x_p_r_1 =:= _+_E_x_p_r_2                                                 _[_I_S_O_]
    True if expression _E_x_p_r_1 evaluates to a number equal to  _E_x_p_r_2.


_-_N_u_m_b_e_r iiss _+_E_x_p_r                                                  _[_I_S_O_]
    True  when _N_u_m_b_e_r is the value to which _E_x_p_r evaluates.   Typically,
    is/2  should be used with unbound left  operand.  If equality  is to
    be tested, =:=/2 should be used.  For example:

             ?- 1 is sin(pi/2).   Fails!    sin(pi/2) evaluates
                                  to the float  1.0, which does
                                  not unify with the integer 1.
             ?- 1 =:= sin(pi/2).  Succeeds as expected.


44..2277..22..11 AArriitthhmmeettiicc ttyyppeess

SWI-Prolog defines the following numeric types:

  o _i_n_t_e_g_e_r
    If  SWI-Prolog is built using the _G_N_U _m_u_l_t_i_p_l_e  _p_r_e_c_i_s_i_o_n _a_r_i_t_h_m_e_t_i_c
    _l_i_b_r_a_r_y  (GMP), integer  arithmetic is _u_n_b_o_u_n_d_e_d,  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  bounded, min_integer  and
    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  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.

  o _r_a_t_i_o_n_a_l _n_u_m_b_e_r
    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 rdiv(_N_,_M). Rational numbers  that
    are  returned from is/2  are _c_a_n_o_n_i_c_a_l, which  means M  is positive
    and  N  and  M have  no  common divisors.    Rational  numbers  are
    introduced  in the computation  using the rational/1,  rationalize/1
    or the 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 format/3 for printing.

    In  the long term,  it is likely  that rational numbers will  become
    _a_t_o_m_i_c  as well  as a subtype  of _n_u_m_b_e_r.   User  code that  creates
    or  inspects the  rdiv(_M_,_N)  terms will  not be  portable to  future
    versions.     Rationals  are  created using  one  of  the  functions
    mentioned above and inspected using rational/3.

  o _f_l_o_a_t
    Floating  point numbers  are represented  using the  C type  double.
    On  most of today's platforms  these are 64-bit IEEE floating  point
    numbers.

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.

    integer ! rational number ! floating point number


44..2277..22..22 RRaattiioonnaall nnuummbbeerr eexxaammpplleess

The  use  of  rational  numbers  with  unbounded   integers  allows  for
exact integer  or _f_i_x_e_d  _p_o_i_n_t arithmetic  under addition,  subtraction,
multiplication  and division.    To exploit  rational arithmetic  rdiv/2
should  be used  instead  of `/'  and  floating  point numbers  must  be
converted to  rational using  rational/1.   Omitting  the rational/1  on
floats  will  convert a  rational  operand  to float  and  continue  the
arithmetic using floating point numbers.  Here are some examples.

              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

Note that  floats cannot  represent all  decimal numbers exactly.    The
function  rational/1 creates  an _e_x_a_c_t  equivalent of  the float,  while
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 format/3 floating point conversion:

________________________________________________________________________|                                                                        |
|?- A is 4 rdiv 3 + rational(1.5),                                       |

|   format('~50f~n', [A]).                                               |
|2.83333333333333333333333333333333333333333333333333                    |
|                                                                        |
|A|=_17_rdiv_6__________________________________________________________ | |


44..2277..22..33 AArriitthhmmeettiicc FFuunnccttiioonnss

Arithmetic functions  are terms  which are evaluated  by the  arithmetic
predicates described in section  ????.  There are four types  of arguments
to functions:

       _E_x_p_r       Arbitrary   expression,   returning  either   a
                  floating point value or an integer.
       _I_n_t_E_x_p_r    Arbitrary expression  that must evaluate to  an
                  integer.
       _R_a_t_E_x_p_r    Arbitrary expression  that must  evaluate to  a
                  rational number.
       _F_l_o_a_t_E_x_p_r  Arbitrary expression  that must  evaluate to  a

                  floating point.

For systems using bounded integer arithmetic (default  is unbounded, see
section ????  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
http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdfC99  mathemati-
cal  library.    In addition,  we  try  to maintain  compatibility  with
http://www.dcc.fc.up.pt/ vsc/Yap/YAP.


- _+_E_x_p_r                                                           _[_I_S_O_]
    _R_e_s_u_l_t =-_E_x_p_r


+ _+_E_x_p_r                                                           _[_I_S_O_]
    _R_e_s_u_l_t =_E_x_p_r.   Note that if + is  followed by a number, the parser
    discards the +.  I.e. ?- integer(+1) succeeds.


_+_E_x_p_r_1 + _+_E_x_p_r_2                                                   _[_I_S_O_]
    _R_e_s_u_l_t =_E_x_p_r_1 +_E_x_p_r_2


_+_E_x_p_r_1 - _+_E_x_p_r_2                                                   _[_I_S_O_]
    _R_e_s_u_l_t =_E_x_p_r_1 -_E_x_p_r_2


_+_E_x_p_r_1 * _+_E_x_p_r_2                                                   _[_I_S_O_]
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2                                                   _[_I_S_O_]
    _R_e_s_u_l_t = _E_x_p_r_1=_E_x_p_r_2.  If the flag  iso is 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 ///2 and rdiv/2.


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2                                           _[_I_S_O_]
    Modulo, defined as _R_e_s_u_l_t = _I_n_t_E_x_p_r_1 - (_I_n_t_E_x_p_r_1 div _I_n_t_E_x_p_r_2)  * _I_n_t_E_x_p_r_2,
    where div is _f_l_o_o_r_e_d division.


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2                                           _[_I_S_O_]
    Remainder   of  integer  division.     Behaves  as  if   defined  by
    _R_e_s_u_l_t is _I_n_t_E_x_p_r_1 - (_I_n_t_E_x_p_r_1 // _I_n_t_E_x_p_r_2)  * _I_n_t_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2                                            _[_I_S_O_]
    Integer  division,  defined  as  _R_e_s_u_l_t is rndI(_E_x_p_r_1/_E_x_p_r_2).     The
    function  rndI is the  default rounding used  by the C  compiler and
    available  through the  Prolog flag  integer_rounding_function.    In
    the C99 standard, C-rounding is defined as towards_zero.


ddiivv((_+_I_n_t_E_x_p_r_1_, _+_I_n_t_E_x_p_r_2))                                         _[_I_S_O_]
    Integer              division,                defined             as
    _R_e_s_u_l_t is (_I_n_t_E_x_p_r_1 - _I_n_t_E_x_p_r_1 mod _I_n_t_E_x_p_r_2) // _I_n_t_E_x_p_r_2 .        In
    other   words,  this  is   integer  division  that  rounds   towards
    -infinity.   This function  guarantees behaviour that is  consistent
    with  mod/2, i.e.,  the following holds for  every pair of  integers
    X; Y where Y =\= 0.

    ____________________________________________________________________|                                                                    |
    |         Q is div(X, Y),                                            |
    |         M is mod(X, Y),                                            |

    ||________X_=:=_Y*Q+M.______________________________________________ ||


_+_R_a_t_E_x_p_r rrddiivv _+_R_a_t_E_x_p_r
    Rational  number  division.    This function  is only  available  if
    SWI-Prolog  has been  compiled with  rational number support.    See
    section ???? for details.


_+_I_n_t_E_x_p_r_1 ggccdd _+_I_n_t_E_x_p_r_2
    Result is the greatest common divisor of _I_n_t_E_x_p_r_1, _I_n_t_E_x_p_r_2.


aabbss((_+_E_x_p_r))                                                        _[_I_S_O_]
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))                                                       _[_I_S_O_]
    Evaluate to -1  if _E_x_p_r< 0, 1 if _E_x_p_r> 0 and 0 if _E_x_p_r= 0.  If _E_x_p_r
    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 copysign/2


ccooppyyssiiggnn((_+_E_x_p_r_1_, _+_E_x_p_r_2))                                          _[_I_S_O_]
    Evaluate  to _X, where  the absolute value  of _X equals the  absolute
    value  of  _E_x_p_r_1 and  the  sign  of _X  matches  the sign  of  _E_x_p_r_2.
    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, copysign/2 evaluates  to
    _E_x_p_r_1  if the  sign of  both expressions  matches or  -_E_x_p_r_1 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.


mmaaxx((_+_E_x_p_r_1_, _+_E_x_p_r_2))                                               _[_I_S_O_]
    Evaluate  to the  larger of  _E_x_p_r_1 and _E_x_p_r_2.    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.


mmiinn((_+_E_x_p_r_1_, _+_E_x_p_r_2))                                               _[_I_S_O_]
    Evaluate  to  the smaller  of _E_x_p_r_1  and _E_x_p_r_2.    See  max/2 for  a
    description of type handling.


.((_+_I_n_t_, _[_]))
    A  list of one element evaluates to  the element.  This  implies "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
    section  ????) of  one character  length into the  character code  for
    that character.   This implies that expression "a" also works of the
    Prolog flag  double_quotesis set to string.   The recommended way to
    specify the character code of the letter `a' is 0'a.


rraannddoomm((_+_I_n_t_E_x_p_r))
    Evaluate  to  a random  integer _i  for which  0=< i< _I_n_t_E_x_p_r.    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 _M_e_r_s_e_n_n_e _T_w_i_s_t_e_r algorithm.   The seed
    is  set when the first random number  in a thread is generated.   If
    available,  it is set  from /dev/random.   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 set_random/1
    can be used to control the random number generator.

    WWaarrnniinngg!!     Although properly  seeded  (if  supported on  the  OS),
    the  Mersenne Twister algorithm  does _n_o_t produce  cryptographically
    secure random numbers.   To generate cryptographically secure random
    numbers, use crypto_n_random_bytes/2 from library crypto provided by
    the ssl package.


rraannddoomm__ffllooaatt
    Evaluate  to a random float I  for which 0:0 <i <1:0.   This function
    shares  the  random state  with  random/1.    All remarks  with  the
    function  random/1 also apply  for random_float/0.   Note that  both
    sides  of the domain  are _o_p_e_n.   This avoids evaluation errors  on,
    e.g., log/1 or //2 while no practical application can expect 0.0.


rroouunndd((_+_E_x_p_r))                                                      _[_I_S_O_]
    Evaluate  _E_x_p_r  and   round  the  result  to  the  nearest  integer.
    According  to  ISO, round/1  is  defined as  floor(_E_x_p_r_+_1_/_2),  i.e.,
    rounding  _d_o_w_n.     This  is  an  unconventional  choice  and  under
    which  the  relation  round(Expr) == -round(-Expr)  does  not  hold.
    SWI-Prolog   rounds  _o_u_t_w_a_r_d,   e.g.,  round(1.5) =:= 2  and   round
    round(-1.5) =:= -2.


iinntteeggeerr((_+_E_x_p_r))
    Same as round/1 (backward compatibility).


ffllooaatt((_+_E_x_p_r))                                                      _[_I_S_O_]
    Translate  the result to a floating point number.   Normally, Prolog
    will  use integers  whenever possible.    When used  around the  2nd
    argument  of is/2, the result will  be returned as a floating  point
    number.  In other contexts, the operation has no effect.


rraattiioonnaall((_+_E_x_p_r))
    Convert  the _E_x_p_r to  a rational  number or integer.   The  function
    returns  the input on integers and  rational numbers.  For  floating
    point  numbers, the returned rational number _e_x_a_c_t_l_y  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 rational(_0_._1).   The function rationalize/1 remedies this.
    See section ???? for more information on rational number support.

    ____________________________________________________________________|                                                                    |
    | ?- A is rational(0.25).                                            |

    |                                                                    |
    | A is 1 rdiv 4                                                      |
    | ?- A is rational(0.1).                                             |
    ||A_=_3602879701896397_rdiv_36028797018963968_______________________ ||


rraattiioonnaalliizzee((_+_E_x_p_r))
    Convert  the _E_x_p_r to  a rational  number or integer.   The  function
    is  similar to rational/1,  but the result  is only accurate  within
    the rounding error  of floating point numbers, generally producing a
    much smaller denominator.

    ____________________________________________________________________|                                                                    |
    | ?- A is rationalize(0.25).                                         |
    |                                                                    |
    | A = 1 rdiv 4                                                       |

    | ?- A is rationalize(0.1).                                          |
    |                                                                    |
    ||A_=_1_rdiv_10_____________________________________________________ ||


ffllooaatt__ffrraaccttiioonnaall__ppaarrtt((_+_E_x_p_r))                                       _[_I_S_O_]
    Fractional   part  of  a  floating  point  number.      Negative  if
    _E_x_p_r   is  negative,  rational   if  _E_x_p_r  is  rational  and  0   if
    _E_x_p_r   is  integer.     The  following  relation  is   always  true:
    Xisfloatfractionalpart(X)+ floatintegerpart(X).


ffllooaatt__iinntteeggeerr__ppaarrtt((_+_E_x_p_r))                                          _[_I_S_O_]
    Integer  part  of  floating point  number.    Negative  if  _E_x_p_r  is
    negative, _E_x_p_r if _E_x_p_r is integer.


ttrruunnccaattee((_+_E_x_p_r))                                                   _[_I_S_O_]
    Truncate  _E_x_p_r to  an integer.    If _E_x_p_r>= 0  this is  the same  as
    floor(_E_x_p_r).  For _E_x_p_r <0 this is the same as ceil(_E_x_p_r).  That is,
    truncate/1 rounds towards zero.


fflloooorr((_+_E_x_p_r))                                                      _[_I_S_O_]
    Evaluate  _E_x_p_r and return  the largest integer  smaller or equal  to
    the result of the evaluation.


cceeiilliinngg((_+_E_x_p_r))                                                    _[_I_S_O_]
    Evaluate  _E_x_p_r and return  the smallest integer  larger or equal  to
    the result of the evaluation.


cceeiill((_+_E_x_p_r))
    Same as ceiling/1 (backward compatibility).


_+_I_n_t_E_x_p_r_1 >> _+_I_n_t_E_x_p_r_2                                            _[_I_S_O_]
    Bitwise  shift  _I_n_t_E_x_p_r_1  by  _I_n_t_E_x_p_r_2  bits to  the  right.     The
    operation   performs  _a_r_i_t_h_m_e_t_i_c  _s_h_i_f_t,  which  implies   that  the
    inserted  most  significant bits  are copies  of  the original  most
    significant bits.


_+_I_n_t_E_x_p_r_1 << _+_I_n_t_E_x_p_r_2                                            _[_I_S_O_]
    Bitwise shift _I_n_t_E_x_p_r_1 by _I_n_t_E_x_p_r_2 bits to the left.


_+_I_n_t_E_x_p_r_1 \/ _+_I_n_t_E_x_p_r_2                                            _[_I_S_O_]
    Bitwise `or' _I_n_t_E_x_p_r_1 and _I_n_t_E_x_p_r_2.


_+_I_n_t_E_x_p_r_1 /\ _+_I_n_t_E_x_p_r_2                                            _[_I_S_O_]
    Bitwise `and' _I_n_t_E_x_p_r_1 and _I_n_t_E_x_p_r_2.


_+_I_n_t_E_x_p_r_1 xxoorr _+_I_n_t_E_x_p_r_2                                           _[_I_S_O_]
    Bitwise `exclusive or' _I_n_t_E_x_p_r_1 and _I_n_t_E_x_p_r_2.


\ _+_I_n_t_E_x_p_r                                                        _[_I_S_O_]
    Bitwise  negation.   The returned value  is the one's complement  of
    _I_n_t_E_x_p_r.


ssqqrrtt((_+_E_x_p_r))                                                       _[_I_S_O_]
    _R_e_s_u_l_t =square root of _E_x_p_r


ssiinn((_+_E_x_p_r))                                                        _[_I_S_O_]
    _R_e_s_u_l_t =sine of _E_x_p_r.  _E_x_p_r is the angle in radians.


ccooss((_+_E_x_p_r))                                                        _[_I_S_O_]
    _R_e_s_u_l_t =cosine of _E_x_p_r.  _E_x_p_r is the angle in radians.


ttaann((_+_E_x_p_r))                                                        _[_I_S_O_]
    _R_e_s_u_l_t =tangus of _E_x_p_r.  _E_x_p_r is the angle in radians.


aassiinn((_+_E_x_p_r))                                                       _[_I_S_O_]
    _R_e_s_u_l_t =inverse sine of _E_x_p_r.  _R_e_s_u_l_t is the angle in radians.


aaccooss((_+_E_x_p_r))                                                       _[_I_S_O_]
    _R_e_s_u_l_t =inverse cosine of _E_x_p_r.  _R_e_s_u_l_t is the angle in radians.


aattaann((_+_E_x_p_r))                                                       _[_I_S_O_]
    _R_e_s_u_l_t =inverse tangus of _E_x_p_r.  _R_e_s_u_l_t is the angle in radians.


aattaann22((_+_Y_E_x_p_r_, _+_X_E_x_p_r))                                             _[_I_S_O_]
    _R_e_s_u_l_t = inverse tangus of _Y_E_x_p_r / _X_E_x_p_r.   _R_e_s_u_l_t is  the angle in
    radians.    The return  value is  in the  range [-pi:::pi].   Used  to
    convert between rectangular and polar coordinate system.

    Note  that the ISO Prolog  standard demands 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.


aattaann((_+_Y_E_x_p_r_, _+_X_E_x_p_r))
    Same as atan2/2 (backward compatibility).


ssiinnhh((_+_E_x_p_r))
    _R_e_s_u_l_t = sinh_E_x_p_r.     The  hyperbolic  sine  of  X  is  defined  as
    e to the power X -e to the power -X=2.


ccoosshh((_+_E_x_p_r))
    _R_e_s_u_l_t = cosh_E_x_p_r.     The hyperbolic  cosine  of  X is  defined  as
    e to the power X +e to the power -X=2.


ttaannhh((_+_E_x_p_r))
    _R_e_s_u_l_t = tanh_E_x_p_r.   The  hyperbolic  tangent of  X  is defined  as
    sinhX=coshX.


aassiinnhh((_+_E_x_p_r))
    _R_e_s_u_l_t =arcsinh(_E_x_p_r) (inverse hyperbolic sine).


aaccoosshh((_+_E_x_p_r))
    _R_e_s_u_l_t =arccosh(_E_x_p_r) (inverse hyperbolic cosine).


aattaannhh((_+_E_x_p_r))
    _R_e_s_u_l_t =arctanh(_E_x_p_r).  (inverse hyperbolic tangent).


lloogg((_+_E_x_p_r))                                                        _[_I_S_O_]
    Natural logarithm.  _R_e_s_u_l_t =natural logarithm of _E_x_p_r


lloogg1100((_+_E_x_p_r))
    Base-10 logarithm.  _R_e_s_u_l_t =10 base logarithm of _E_x_p_r


eexxpp((_+_E_x_p_r))                                                        _[_I_S_O_]
    _R_e_s_u_l_t =e to the power _E_x_p_r


_+_E_x_p_r_1 ** _+_E_x_p_r_2                                                  _[_I_S_O_]
    _R_e_s_u_l_t = _E_x_p_r_1 to the power _E_x_p_r_2.   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 ex-
    pressions  0 to the power I, 1 to the power I and  -1 to the power I
    are  guaranteed to  work  for any  integer I.    Other integer  base
    values  generate a  resource error  if the  result does  not fit  in
    memory.

    The  ISO  standard  demands  a  float  result  for  all  inputs  and
    introduces  ^/2 for  integer exponentiation.   The function  float/1
    can  be used  on one  or both arguments  to force  a floating  point
    result.     Note  that  casting  the  _i_n_p_u_t  result  in  a  floating
    point  computation,   while  casting  the  _o_u_t_p_u_t  performs  integer
    exponentiation followed by a conversion to float.


_+_E_x_p_r_1 ^ _+_E_x_p_r_2                                                   _[_I_S_O_]
    In  SWI-Prolog,  ^/2 is  equivalent to  **/2.   The  ISO version  is
    similar,  except that it produces  a evaluation error if both  _E_x_p_r_1
    and _E_x_p_r_2 are integers  and the result is not an integer.  The table
    below  illustrates the behaviour of the exponentiation  functions in
    ISO and SWI.

          ________________________________________________________
          |__E_x_p_r_1_____E_x_p_r_2__|_Function_|SWI__________|ISO__________|
          | Int      Int   | **/2     |Int or Float |Float        |
          | Int      Float | **/2     |Float        |Float        |
          | Rational Int   | **/2     |Rational     |-            |

          | Float    Int   | **/2     |Float        |Float        |
          |_Float____Float_|_**/2_____|Float________|Float________|
          | Int      Int   | ^/2      |Int or Float |Int or error |
          | Int      Float | ^/2      |Float        |Float        |
          | Rational Int   | ^/2      |Rational     |-            |
          | Float    Int   | ^/2      |Float        |Float        |
          |_Float____Float_|_^/2______|Float________|Float________|


ppoowwmm((_+_I_n_t_E_x_p_r_B_a_s_e_, _+_I_n_t_E_x_p_r_E_x_p_, _+_I_n_t_E_x_p_r_M_o_d))
    _R_e_s_u_l_t   =  (_I_n_t_E_x_p_r_B_a_s_e to the power _I_n_t_E_x_p_r_E_x_p) modulo _I_n_t_E_x_p_r_M_o_d.
    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.
    _I_n_t_E_x_p_r_B_a_s_e  and _I_n_t_E_x_p_r_E_x_p must be non-negative (>= 0), _I_n_t_E_x_p_r_M_o_d
    must be positive (> 0).


llggaammmmaa((_+_E_x_p_r))
    Return  the natural  logarithm of  the absolute value  of the  Gamma
    function.


eerrff((_+_E_x_p_r))
    https://en.wikipedia.org/wiki/Error_functionWikipedia:   ``In  math-
    ematics,   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.''


eerrffcc((_+_E_x_p_r))
    https://en.wikipedia.org/wiki/Error_functionWikipedia:   ``The  com-
    plementary error function.''


ppii                                                                _[_I_S_O_]
    Evaluate to the mathematical constant pi (3.14159...).


ee
    Evaluate to the mathematical constant e (2.71828...).


eeppssiilloonn
    Evaluate  to the  difference  between the  float 1.0  and the  first
    larger floating point number.


iinnff
    Evaluate  to positive infinity.  See section ????.  This  value can be
    negated using -/1 .


nnaann
    Evaluate to _N_o_t _a _N_u_m_b_e_r.  See section ????.


ccppuuttiimmee
    Evaluate  to a  floating point  number expressing the  cpu time  (in
    seconds)  used by Prolog  up till  now.   See also statistics/2  and
    time/1.


eevvaall((_+_E_x_p_r))
    Evaluate  _E_x_p_r.  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.

BBiittvveeccttoorr ffuunnccttiioonnss

The  functions   below  are  not   covered  by  the   standard.      The
msb/1  function  also appears  in  hProlog  and  SICStus Prolog.     The
getbit/2  function  also   appears  in  ECLiPSe,  which   also  provides
setbit(_V_e_c_t_o_r_,_I_n_d_e_x)  and   clrbit(_V_e_c_t_o_r_,_I_n_d_e_x).      The  others   are
SWI-Prolog extensions that improve handling of  ---unbounded--- integers
as bit-vectors.


mmssbb((_+_I_n_t_E_x_p_r))
    Return  the largest integer N  such that (IntExpr >> N) /\ 1 =:= 1.
    This  is the (zero-origin)  index of the  most significant 1 bit  in
    the  value of _I_n_t_E_x_p_r,  which must evaluate  to a positive  integer.
    Errors for 0, negative integers, and non-integers.


llssbb((_+_I_n_t_E_x_p_r))
    Return  the smallest integer N such that (IntExpr >> N) /\ 1 =:= 1.
    This  is the (zero-origin) index of  the least significant 1 bit  in
    the  value of _I_n_t_E_x_p_r,  which must evaluate  to a positive  integer.
    Errors for 0, negative integers, and non-integers.


ppooppccoouunntt((_+_I_n_t_E_x_p_r))
    Return  the  number  of  1s  in the  binary  representation  of  the
    non-negative integer _I_n_t_E_x_p_r.


ggeettbbiitt((_+_I_n_t_E_x_p_r_V_, _+_I_n_t_E_x_p_r_I))
    Evaluates  to the  bit  value (0  or 1)  of the  _I_n_t_E_x_p_r_I-th bit  of
    _I_n_t_E_x_p_r_V.  Both arguments  must evaluate  to non-negative  integers.
    The  result  is equivalent  to (IntExprV >> IntExprI)/\1,  but  more
    efficient  because materialization of the shifted value  is avoided.
    Future  versions will optimise  (IntExprV >> IntExprI)/\1 to a  call
    to getbit/2, providing both portability and performance.


44..2288 MMiisscc aarriitthhmmeettiicc ssuuppppoorrtt pprreeddiiccaatteess


sseett__rraannddoomm((_+_O_p_t_i_o_n))
    Controls   the  random  number  generator  accessible   through  the
    _f_u_n_c_t_i_o_n_s  random/1  and  random_float/0.     Note that  the  library
    random provides an alternative API to the same random primitives.

    sseeeedd((_+_S_e_e_d))
         Set the  seed of the random  generator for this  thread.   _S_e_e_d
         is an  integer  or the  atom random.    If random,  repeat  the
         initialization procedure described with the  function random/1.
         Here is an example:

         _______________________________________________________________|                                                               |

         |?- set_random(seed(111)), A is random(6).                      |
         |A = 5.                                                         |
         |?- set_random(seed(111)), A is random(6).                      |
         |A|=_5.________________________________________________________ | |

    ssttaattee((_+_S_t_a_t_e))
         Set the generator to  a state fetched using the  state property
         of random_property/1.  Using other values may lead to undefined
         behaviour.


rraannddoomm__pprrooppeerrttyy((_?_O_p_t_i_o_n))
    True  when _O_p_t_i_o_n  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.

    ssttaattee((_-_S_t_a_t_e))
         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 set_random/1 using the state(_S_t_a_t_e) option.


ccuurrrreenntt__aarriitthhmmeettiicc__ffuunnccttiioonn((_?_H_e_a_d))
    True when _H_e_a_d is an evaluable function.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- current_arithmetic_function(sin(_)).                            |

    ||true._____________________________________________________________ ||


44..2299 BBuuiilltt--iinn lliisstt ooppeerraattiioonnss

Most  list operations  are defined  in the  library  lists described  in
section ????.   Some that are  implemented with more low-level  primitives
are built-in and described here.


iiss__lliisstt((_+_T_e_r_m))
    True if _T_e_r_m is  bound to the empty list ([]) or a term with functor
    `'[|]''  and  arity 2  and the  second argument  is a  list.    This
    predicate  acts as  if defined  by the definition  below on  _a_c_y_c_l_i_c
    terms.   The implementation _f_a_i_l_s safely if _T_e_r_m represents a cyclic
    list.

    ____________________________________________________________________|                                                                    |
    | is_list(X) :-                                                      |
    |         var(X), !,                                                 |
    |         fail.                                                      |

    | is_list([]).                                                       |
    | is_list([_|T]) :-                                                  |
    ||________is_list(T)._______________________________________________ ||


mmeemmbbeerrcchhkk((_?_E_l_e_m_, _+_L_i_s_t))                                       _[_s_e_m_i_d_e_t_]
    True  when  _E_l_e_m  is  an  element  of _L_i_s_t.     This  `chk'  variant
    of  member/2  is  semi  deterministic and  typically  used  to  test
    membership  of  a list.     Raises a  type  error if  scanning  _L_i_s_t
    encounters  a non-list.   Note that  memberchk/2 does _n_o_t perform  a
    full  list typecheck.    For  example, memberchk(a, [a|b])  succeeds
    without error.   If _L_i_s_t is cyclic and _E_l_e_m is not a member of _L_i_s_t,
    memberchk/2 eventually raises a type error.


lleennggtthh((_?_L_i_s_t_, _?_I_n_t))                                               _[_I_S_O_]
    True  if  _I_n_t represents  the number  of  elements in  _L_i_s_t.    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  _I_n_t.
    The  predicate is non-deterministic,  producing lists of  increasing
    length  if _L_i_s_t is  a _p_a_r_t_i_a_l _l_i_s_t  and _I_n_t is unbound.   It  raises
    errors if

      o  _I_n_t is bound to a non-integer.

      o  _I_n_t is a negative integer.

      o  _L_i_s_t  is neither  a  list  nor a  partial  list.    This  error
         condition includes cyclic lists.

    This  predicate  fails if  the tail  of _L_i_s_t  is  equivalent to  _I_n_t
    (e.g., length(L,L)).


ssoorrtt((_+_L_i_s_t_, _-_S_o_r_t_e_d))                                              _[_I_S_O_]
    True  if _S_o_r_t_e_d  can be  unified with  a list  holding the  elements
    of  _L_i_s_t, sorted to  the standard order  of terms (see section  ????).
    Duplicates  are removed.  The implementation is in C,  using _n_a_t_u_r_a_l
    _m_e_r_g_e _s_o_r_t.   The sort/2 predicate can sort a cyclic list, returning
    a non-cyclic version with the same elements.

    Note  that _L_i_s_t may contain non-ground terms.  If _S_o_r_t_e_d  is unbound
    at  call-time,  for each  consequtive pair  of  elements in  _S_o_r_t_e_d,
    the  relation E1 @< E2 will hold.   However, unifying a variable  in
    _S_o_r_t_e_d  may cause  this relation  to become  invalid, _e_v_e_n  unifying
    a  variable  in _S_o_r_t_e_d  with another  (older) variable.    See  also
    section ????.


ssoorrtt((_+_K_e_y_, _+_O_r_d_e_r_, _+_L_i_s_t_, _-_S_o_r_t_e_d))
    True  when _S_o_r_t_e_d can be unified with a list holding the  element of
    _L_i_s_t.   _K_e_y determines  which part of each  element in _L_i_s_t is  used
    for  comparing two  term and  _O_r_d_e_r describes  the relation  between
    each set of consecutive elements in _S_o_r_t_e_d.

    If  _K_e_y is the integer zero (0), the entire term is used  to compare
    two  elements.   Using _K_e_y=0  can be used  to sort arbitrary  Prolog
    terms.   Other values for _K_e_y  can only be used with  compound terms
    or  dicts (see  section ????).   An  integer key  extracts the  _K_e_y-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 _K_e_y argument.

    The _O_r_d_e_r argument is described in the table below

                   _Order__Ordering____Duplicate_handling__
                    @<     ascending   remove
                    @=<    ascending   keep
                    @>     descending  remove
                    @>=    descending  keep

    The sort is _s_t_a_b_l_e,  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
    _S_o_r_t_e_d.

    This predicate supersedes  most of the other sorting primitives, for
    example:

    ____________________________________________________________________|                                                                    |

    | sort(List, Sorted)     :- sort(0,  @<, List,  Sorted).             |
    | msort(List, Sorted)    :- sort(0, @=<, List,  Sorted).             |
    ||keysort(Pairs,_Sorted)_:-_sort(1,_@=<,_Pairs,_Sorted).____________ ||

    The  following example sorts a  list of rows, for example  resulting
    from  csv_read_file/2) ascending on the 3th column  and descending on
    the 4th column:

    ____________________________________________________________________|                                                                    |
    |     sort(4, @>=, Rows0, Rows1),                                    |
    ||____sort(3,_@=<,_Rows1,_Sorted).__________________________________ ||

    See   also  sort/2   (ISO),  msort/2,   keysort/2,  predsort/3   and
    order_by/2.


mmssoorrtt((_+_L_i_s_t_, _-_S_o_r_t_e_d))
    Equivalent  to sort/2,  but does not  remove duplicates.   Raises  a
    type_error if _L_i_s_t is a cyclic list or not a list.


kkeeyyssoorrtt((_+_L_i_s_t_, _-_S_o_r_t_e_d))                                           _[_I_S_O_]
    Sort  a list  of _p_a_i_r_s.   _L_i_s_t must  be a  list of _K_e_y-_V_a_l_u_e  pairs,
    terms  whose  principal  functor  is  (-)/2.    _L_i_s_t  is  sorted  on
    _K_e_y  according to  the  standard order  of terms  (see section  ????).
    Duplicates  are _n_o_t removed.   Sorting is _s_t_a_b_l_e with regard to  the
    order of the _V_a_l_u_e_s,  i.e., the order of multiple elements that have
    the same _K_e_y is not changed.

    The  keysort/2 predicate is often used together with  library 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.

    ____________________________________________________________________|                                                                    |
    | :- 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).___________________________ ||


pprreeddssoorrtt((_+_P_r_e_d_, _+_L_i_s_t_, _-_S_o_r_t_e_d))
    Sorts  similar to sort/2, but determines  the order of two terms  by
    calling  _P_r_e_d(-_D_e_l_t_a, +_E_1, +_E_2).   This call  must unify _D_e_l_t_a  with
    one of <, >  or =.  If the built-in predicate compare/3 is used, the
    result is the same as sort/2.  See also keysort/2.


44..3300 FFiinnddiinngg aallll SSoolluuttiioonnss ttoo aa GGooaall


ffiinnddaallll((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_B_a_g))                                   _[_I_S_O_]
    Create  a list of the  instantiations _T_e_m_p_l_a_t_e gets successively  on
    backtracking  over _G_o_a_l  and unify the  result with  _B_a_g.   Succeeds
    with  an  empty  list  if _G_o_a_l  has  no  solutions.    findall/3  is
    equivalent  to  bagof/3  with  all free  variables  bound  with  the
    existential  operator (^), except that  bagof/3 fails when _G_o_a_l  has
    no solutions.


ffiinnddaallll((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_B_a_g_, _+_T_a_i_l))
    As  findall/3,  but  returns  the  result  as  the  difference  list
    _B_a_g-_T_a_i_l.  The 3-argument version is defined as

    ____________________________________________________________________|                                                                    |
    | findall(Templ, Goal, Bag) :-                                       |

    ||________findall(Templ,_Goal,_Bag,_[])_____________________________ ||


ffiinnddnnssoollss((_+_N_, _@_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_L_i_s_t))                         _[_n_o_n_d_e_t_]


ffiinnddnnssoollss((_+_N_, _@_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_L_i_s_t_, _?_T_a_i_l))                  _[_n_o_n_d_e_t_]
    As  findall/3 and findall/4, but generates at most _N solutions.   If
    _N  solutions are  returned, this  predicate succeeds  with a  choice
    point  if _G_o_a_l has  a choice point.   Backtracking returns the  next
    chunk  of (at most)  _N solutions.   In addition  to passing a  plain
    integer  for _N,  a term of  the form  count(_N) is accepted.    Using
    count(_N),  the  size  of the  next  chunk  can be  controlled  using
    nb_setarg/3.  The non-deterministic behaviour  used to implement the
    _c_h_u_n_k  option in  pengines.   Based on  Ciao, but  the Ciao  version
    is  deterministic.    Portability can  be achieved  by wrapping  the
    goal  in 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 _G_o_a_l leaves no choice-point  after
    the last solution.

    ____________________________________________________________________|                                                                    |
    | ?- 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]._________________________________________________ ||


bbaaggooff((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_B_a_g))                                     _[_I_S_O_]
    Unify  _B_a_g with  the alternatives  of _T_e_m_p_l_a_t_e.   If  _G_o_a_l has  free
    variables  besides  the  one sharing  with  _T_e_m_p_l_a_t_e,  bagof/3  will
    backtrack  over the alternatives  of these free variables,  unifying
    _B_a_g with the  corresponding alternatives of _T_e_m_p_l_a_t_e.  The construct
    +_V_a_r^_G_o_a_l  tells bagof/3 not to bind _V_a_r in _G_o_a_l.  bagof/3  fails if
    _G_o_a_l has no solutions.

    The  example below  illustrates bagof/3  and the  ^ operator.    The
    variable bindings are printed together on one line to save paper.

    ____________________________________________________________________|                                                                    |
    | 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_?-______________________________________________________________ ||


sseettooff((_+_T_e_m_p_l_a_t_e_, _+_G_o_a_l_, _-_S_e_t))                                     _[_I_S_O_]
    Equivalent  to bagof/3, but sorts the  result using sort/2 to get  a
    sorted list of alternatives without duplicates.


44..3311 FFoorraallll


ffoorraallll((_:_C_o_n_d_, _:_A_c_t_i_o_n))                                        _[_s_e_m_i_d_e_t_]
    For  all alternative bindings of  _C_o_n_d, _A_c_t_i_o_n 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.

    ____________________________________________________________________|                                                                    |
    | ?- forall(member(Result = Formula, [2 = 1 + 1, 4 = 2 * 2]),        |

    ||_________________Result_=:=_Formula)._____________________________ ||

    The  predicate  forall/2  is implemented  as  \+ ( Cond, \+ Action),
    i.e., _T_h_e_r_e _i_s  _n_o _i_n_s_t_a_n_t_i_a_t_i_o_n _o_f _C_o_n_d _f_o_r _w_h_i_c_h _A_c_t_i_o_n _i_s _f_a_l_s_e_..
    The  use of double  negation implies that  forall/2 _d_o_e_s _n_o_t  _c_h_a_n_g_e
    _a_n_y _v_a_r_i_a_b_l_e _b_i_n_d_i_n_g_s.   It proves a relation.  The forall/2 control
    structure  can be used  for its side-effects.   E.g., the  following
    asserts relations in a list into the dynamic database:

    ____________________________________________________________________|                                                                    |
    | ?- forall(member(Child-Parent, ChildPairs),                        |
    ||__________assertz(child_of(Child,_Parent))).______________________ ||

    Using  forall/2 as forall(_G_e_n_e_r_a_t_o_r_,  _S_i_d_e_E_f_f_e_c_t) is preferred  over
    the  classical _f_a_i_l_u_r_e _d_r_i_v_e_n _l_o_o_p  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.

    ____________________________________________________________________|                                                                    |
    |         ...,                                                       |
    |         (   Generator,                                             |
    |             SideEffect,                                            |

    |             fail                                                   |
    |         ;   true                                                   |
    ||________)_________________________________________________________ ||

    If your intent  is to create variable bindings, the forall/2 control
    structure  is inadequate.   Possibly you are looking for  maplist/2,
    findall/3 or foreach/2.


44..3322 FFoorrmmaatttteedd WWrriittee

The  current  version   of  SWI-Prolog  provides  two  formatted   write
predicates.   The  `writef' family (writef/1,  writef/2, swritef/3),  is
compatible with Edinburgh C-Prolog and should  be considered _d_e_p_r_e_c_a_t_e_d.
The  `format' family  (format/1,  format/2,  format/3), was  defined  by
Quintus Prolog and currently available in many  Prolog systems, although
the details vary.


44..3322..11 WWrriitteeff


wwrriitteeff((_+_A_t_o_m))                                              _[_d_e_p_r_e_c_a_t_e_d_]
    Equivalent to writef(Atom, []). See writef/2 for details.


wwrriitteeff((_+_F_o_r_m_a_t_, _+_A_r_g_u_m_e_n_t_s))                                _[_d_e_p_r_e_c_a_t_e_d_]
    Formatted  write.    _F_o_r_m_a_t  is an  atom  whose characters  will  be
    printed.    _F_o_r_m_a_t may contain  certain special character  sequences
    which   specify   certain  formatting   and  substitution   actions.
    _A_r_g_u_m_e_n_t_s provides all the terms required to be output.

    Escape sequences to generate a single special character:

             __________________________________________________
             | \n   |Output  a  newline  character  (see  also |
             |      |nl/[0,1])                                 |
             | \l   |Output a line separator (same as \n)      |

             | \r   |Output  a   carriage   return   character |
             |      |(ASCII 13)                                |
             | \t   |Output the ASCII character TAB (9)        |
             | \\   |The character \ is output                 |
             | \%   |The character % is output                 |
             | \nnn |where <_n_n_n> is  an integer  (1-3 digits); |
             |      |the character with  code <_n_n_n>  is output |

             |______|(NB_:_<_n_n_n>_is_read_as_ddeecciimmaall)___________|

    Note  that  \l,   \nnn  and  \\  are  interpreted  differently  when
    character escapes are in effect.  See section ????.

    Escape  sequences to include  arguments from _A_r_g_u_m_e_n_t_s.   Each  time
    a  %  escape sequence  is found  in _F_o_r_m_a_t  the  next argument  from
    _A_r_g_u_m_e_n_t_s is formatted according to the specification.

              _________________________________________________%t

              | %w  print/1 the next item (mnemonic:  term)   |    |

              | %q  |write/1the next item                     |

              |     |writeq/1the next item                    |
              | %d  |Write the term,  ignoring operators.  See|
              |     |also  write_term/2.      Mnemonic:    old|
              | %p  |Edinburgh display/1                      |

              |     |print/1the next item (identical to %t)   |
              | %n  |Put the  next item as  a character (i.e.,|

              |     |it is a character code)                  |
              | %r  |Write the  next item  N times where  N is|
              |     |the second item (an integer)             |
              | %s  |Write the  next item  as a String  (so it|
              |     |must be a list of characters)            |
              | %f  |Perform a ttyflush/0 (no items used)     |
              | %Nc |Write  the   next  item  Centered  in  N |

              |     |columns                                  |
              | %Nl |Write the next  item Left justified in N |
              |     |columns                                  |
              | %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.__________|_


sswwrriitteeff((_-_S_t_r_i_n_g_, _+_F_o_r_m_a_t_, _+_A_r_g_u_m_e_n_t_s))                      _[_d_e_p_r_e_c_a_t_e_d_]
    Equivalent to writef/2,  but ``writes'' the result on _S_t_r_i_n_g instead
    of the current output stream.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- swritef(S, '%15L%w', ['Hello', 'World']).                       |
    |                                                                    |
    ||S_=_"Hello__________World"________________________________________ ||


sswwrriitteeff((_-_S_t_r_i_n_g_, _+_F_o_r_m_a_t))                                  _[_d_e_p_r_e_c_a_t_e_d_]
    Equivalent to swritef(String, Format, []).


44..3322..22 FFoorrmmaatt

The format family of  predicates is the most versatile and  portable way
to produce textual output.


ffoorrmmaatt((_+_F_o_r_m_a_t))
    Defined  as `format(Format) :- format(Format, []).'.   See  format/2
    for details.


ffoorrmmaatt((_+_F_o_r_m_a_t_, _:_A_r_g_u_m_e_n_t_s))
    _F_o_r_m_a_t  is an  atom, list of  character codes,  or a Prolog  string.
    _A_r_g_u_m_e_n_t_s   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 (~), followed by an optional
    numeric  argument,  optionally  followed by  a colon  modifier  (:),
    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  `<_c_h_a_r_a_c_t_e_r>, representing  the
    character  code value  of the character  (only useful  for ~t) or  a
    asterisk  (*), 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 (.) to ~t:

    ____________________________________________________________________|                                                                    |
    | ?- 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']).______________ ||

    Numeric  conversion (d, D,  e, E, f, g  and G) accept an  arithmetic
    expression  as argument.    This  is introduced  to handle  rational
    numbers  transparently  (see  section  ????).     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'.

    ____________________________________________________________________|                                                                    |
    | ?- format('~50f', [10 rdiv 3]).                                    |
    ||3.33333333333333333333333333333333333333333333333333______________ ||

      ~  Output the tilde itself.

      a  Output the next argument, which  must be an atom.   This option
         is equivalent to ww, except that it requires the  argument to be
         an atom.

      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 section ???? for details.

      d  Output  next argument  as  a decimal  number.    It  should  be
         an integer.    If a  numeric argument  is specified,  a dot  is
         inserted _a_r_g_u_m_e_n_t  positions from the  right (useful for  doing
         fixed point arithmetic with integers, such as  handling amounts
         of money).

         The colon modifier (e.g., ~:d) causes the number  to be printed
         according to the locale of the output stream.  See section ????.

      D  Same as dd, 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 ~:d, but using the fixed English locale.

      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 %.<_p_r_e_c_i_s_i_o_n>e.

      E  Equivalent  to ee,  but  outputs a  capital  E to  indicate  the
         exponent.

      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.

      g  Floating point in ee or ff notation, whichever is shorter.

      G  Floating point in EE or ff notation, whichever is shorter.

      i  Ignore  next argument  of  the  argument  list.    Produces  no
         output.

      I  Emit  a  decimal  number  using  Prolog  digit   grouping  (the
         underscore, _).  The argument describes the size  of each digit
         group.  The default is 3.  See also section ????.  For example:

         _______________________________________________________________|                                                               |

         |?- A is 1<<100, format('~10I', [A]).                           |
         |1_2676506002_2822940149_6703205376|___________________________ |                                  |

      k  Give the next argument to write_canonical/1.

      n  Output a newline character.

      N  Only output  a newline  if the  last character  output on  this
         stream was not a newline.  Not properly implemented yet.

      p  Give the next argument to print/1.

      q  Give the next argument to writeq/1.

      r  Print integer in  radix numeric argument  notation.  Thus  ~16r
         prints its  argument hexadecimal.   The  argument should be  in
         the range [2;:::;36].   Lowercase letters are used for digits above
         9.   The  colon modifier may  be used  to form  locale-specific
         digit groups.

      R  Same as rr, but uses uppercase letters for digits above 9.

      s  Output text  from a list  of character codes  or a string  (see
         string/1 and section ????) from the next argument.

      @  Interpret the next argument as  a goal and execute it.   Output
         written to the current_output stream is inserted at this place.
         Goal is  called in the  module calling format/3.   This  option
         is not  present  in the  original  definition by  Quintus,  but
         supported by some other Prolog systems.

      t  All remaining space between 2 tab stops  is distributed equally
         over ~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  ~| and ~+ to set  tab
         stops.  A tab stop is assumed at the start of each line.

      |  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  ~t's  to  be  distributed  between  the
         previous and this tab stop.

      +  Set  a tab  stop (as  ~|)  relative to  the  last tab  stop  or
         the beginning  of  the line  if  no tab  stops are  set  before
         the ~+.    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 ...   sequences in the
         example illustrate  that the  integer is aligned  in 6  columns
         regardless of the remainder of the format specification.

         _______________________________________________________________|                                                               |
         ||_______format('...~|~`0t~d~6+...',_[...,_Integer,_...])______ ||

      w  Give the next argument to write/1.

      W  Give the  next two  arguments to  write_term/2.   For  example,
         format('~W', [Term, [numbervars(true)]]).     This   option  is
         SWI-Prolog specific.

    Example:

    ____________________________________________________________________|                                                                    |
    | 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]),          |
    ||____....__________________________________________________________ ||

    will output

    ____________________________________________________________________|                                                                    |

    |                              Statistics                            |
    |                                                                    |
    ||Runtime:_.................._3.45__Inferences:_.........._60,345___ ||


ffoorrmmaatt((_+_O_u_t_p_u_t_, _+_F_o_r_m_a_t_, _:_A_r_g_u_m_e_n_t_s))
    As  format/2, but write  the output on  the given _O_u_t_p_u_t.   The  de-
    facto  standard only allows _O_u_t_p_u_t to  be a stream.  The  SWI-Prolog
    implementation  allows  all  valid  arguments for  with_output_to/2.
    For example:

    ____________________________________________________________________|                                                                    |
    | ?- format(atom(A), '~D', [1000000]).                               |

    ||A_=_'1,000,000'___________________________________________________ ||


44..3322..33 PPrrooggrraammmmiinngg FFoorrmmaatt


ffoorrmmaatt__pprreeddiiccaattee((_+_C_h_a_r_, _+_H_e_a_d))
    If  a sequence ~c (tilde, followed by some character) is  found, the
    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.  _C_h_a_r  is either a character  code
    or  a one-character atom, specifying  the letter to be  (re)defined.
    _H_e_a_d  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 default if  no argument is  specified.
    The  remaining arguments  are filled from  the argument  list.   The
    example  below defines  ~T to  print a timestamp  in ISO8601  format
    (see  format_time/3).   The  subsequent block illustrates a  possible
    call.

    ____________________________________________________________________|                                                                    |
    | :- format_predicate('T', format_time(_Arg,_Time)).                 |
    |                                                                    |
    | format_time(_Arg, Stamp) :-                                        |

    |         must_be(number, Stamp),                                    |
    ||________format_time(current_output,_'%FT%T%z',_Stamp).____________ ||

    ____________________________________________________________________|                                                                    |

    | ?- get_time(Now),                                                  |
    |    format('Now, it is ~T~n', [Now]).                               |
    | Now, it is 2012-06-04T19:02:01+0200                                |
    ||Now_=_1338829321.6620328._________________________________________ ||


ccuurrrreenntt__ffoorrmmaatt__pprreeddiiccaattee((_?_C_o_d_e_, _?_:_H_e_a_d))
    True  when ~_C_o_d_e is handled by the user-defined  predicate specified
    by _H_e_a_d.


44..3333 GGlloobbaall vvaarriiaabblleess

Global  variables are  associations  between  names (atoms)  and  terms.
They differ in  various ways from storing information using  assert/1 or
recorda/3.

  o 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.

  o They   support  both   global  assignment   using  nb_setval/2   and
    backtrackable assignment using b_setval/2.

  o Only  one value (which can be an arbitrary complex Prolog  term) can
    be associated to a variable at a time.

  o Their  value cannot be  shared among threads.   Each thread has  its
    own namespace and values for global variables.

  o Currently  global variables are  scoped globally.   We may  consider
    module scoping in future versions.

Both  b_setval/2 and 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
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 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  _a_f_t_e_r the  registration.    Finally,  global
variables can be initialised using the exception hook exception/3.   The
latter technique is used by CHR (see chapter ????).


bb__sseettvvaall((_+_N_a_m_e_, _+_V_a_l_u_e))
    Associate  the  term  _V_a_l_u_e  with  the  atom  _N_a_m_e  or  replace  the
    currently  associated value  with _V_a_l_u_e.    If _N_a_m_e  does not  refer
    to  an existing global  variable, a variable  with initial value  []
    is  created (the  empty list).   On  backtracking the assignment  is
    reversed.


bb__ggeettvvaall((_+_N_a_m_e_, _-_V_a_l_u_e))
    Get the value  associated with the global variable _N_a_m_e and unify it
    with _V_a_l_u_e.   Note that this unification may further instantiate the
    value  of the global  variable.  If  this is undesirable the  normal
    precautions  (double negation or  copy_term/2) must be  taken.   The
    b_getval/2 predicate generates errors if _N_a_m_e is not  an atom or the
    requested variable does not exist.


nnbb__sseettvvaall((_+_N_a_m_e_, _+_V_a_l_u_e))
    Associates  a copy of  _V_a_l_u_e created with duplicate_term/2 with  the
    atom  _N_a_m_e.   Note that  this can be  used to  set an initial  value
    other than [] prior to backtrackable assignment.


nnbb__ggeettvvaall((_+_N_a_m_e_, _-_V_a_l_u_e))
    The  nb_getval/2 predicate is  a synonym for  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  nb_getval/2  can  be   used
    to  document  that  the  variable  is  non-backtrackable.     Raises
    existence_error(_v_a_r_i_a_b_l_e_,  _N_a_m_e)  if the  variable does  not  exist.
    Alternatively,  nb_current/2 can  used to query  a global  variable.
    This  version  _f_a_i_l_s if  the  variable does  not exist  rather  than
    raising an exception.


nnbb__lliinnkkvvaall((_+_N_a_m_e_, _+_V_a_l_u_e))
    Associates  the term _V_a_l_u_e  with the atom  _N_a_m_e without copying  it.
    This  is a  fast special-purpose  variation of  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  _t_r_a_i_l_e_d and  left  alone otherwise,  which  implies
    that  the history  that created  the term affects  the behaviour  on
    backtracking.  Consider the following example:

    ____________________________________________________________________|                                                                    |
    | demo_nb_linkval :-                                                 |

    |         T = nice(N),                                               |
    |         (   N = world,                                             |
    |             nb_linkval(myvar, T),                                  |
    |             fail                                                   |
    |         ;   nb_getval(myvar, V),                                   |
    |             writeln(V)                                             |
    ||________).________________________________________________________ ||


nnbb__ccuurrrreenntt((_?_N_a_m_e_, _?_V_a_l_u_e))
    Enumerate  all defined  variables with their  value.   The order  of
    enumeration is  undefined.  Note that nb_current/2 can be used as an
    alternative  for nb_getval/2 to request the value of a  variable and
    fail silently if the variable does not exists.


nnbb__ddeelleettee((_+_N_a_m_e))
    Delete  the  named global  variable.   Succeeds  also  if the  named
    variable does not exist.


44..3333..11 CCoommppaattiibbiilliittyy ooff SSWWII--PPrroolloogg GGlloobbaall VVaarriiaabblleess

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 nb_setval/2, which is equivalent  to nb_linkval/2,
is  not  acceptable  for  normal  Prolog  users  as   the  behaviour  is
influenced  by how  built-in predicates  that  construct terms  (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  functor/3  and
setarg/3 due to the unrestricted arity of compound terms.


44..3344 TTeerrmmiinnaall CCoonnttrrooll

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.


ttttyy__ggeett__ccaappaabbiilliittyy((_+_N_a_m_e_, _+_T_y_p_e_, _-_R_e_s_u_l_t))
    Get  the  capability named  _N_a_m_e  from the  termcap  library.    See
    termcap(5)  for the capability  names.   _T_y_p_e specifies the type  of
    the  expected result, and is one of string, number or bool.   String
    results  are returned as an atom, number results as an  integer, and
    bool  results as the atom on or 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.


ttttyy__ggoottoo((_+_X_, _+_Y))
    Goto  position  (_X, _Y) on  the screen.    Note  that the  predicates
    line_count/2  and  line_position/2  will  not  have  a  well-defined
    behaviour while using this predicate.


ttttyy__ppuutt((_+_A_t_o_m_, _+_L_i_n_e_s))
    Put  an  atom  via the  termcap  library  function tputs().     This
    function  decodes padding  information  in the  strings returned  by
    tty_get_capability/3 and  should be  used to  output these  strings.
    _L_i_n_e_s is the number  of lines affected by the operation, or 1 if not
    applicable (as in almost all cases).


ttttyy__ssiizzee((_-_R_o_w_s_, _-_C_o_l_u_m_n_s))
    Determine the size of the terminal.  Platforms:

    UUnniixx  If  the  system  provides _i_o_c_t_l  calls  for  this,  these  are
         used and  tty_size/2 properly  reflects the  actual size  after
         a user  resize of  the window.    The  _i_o_c_t_l is  issued on  teh
         file descriptor  associated  with the  user_input  stream.    As
         a fallback,  the system uses tty_get_capability/3 using li  and
         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.

    WWiinnddoowwss  Getting  the   size  of  the   terminal  is  provided   for
         swipl-win.exe.  The requested value reflects  the current size.
         For the  multithreaded version the  console that is  associated
         with the user_input stream is used.


44..3355 OOppeerraattiinngg SSyysstteemm IInntteerraaccttiioonn

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 clib package, notably  library process, socket,  unix
and filesex.


sshheellll((_+_C_o_m_m_a_n_d))
    Equivalent to `shell(Command, 0)'.  See shell/2 for details.


sshheellll((_+_C_o_m_m_a_n_d_, _-_S_t_a_t_u_s))
    Execute  _C_o_m_m_a_n_d on the operating system.   _C_o_m_m_a_n_d is given to  the
    Bourne  shell (/bin/sh).  _S_t_a_t_u_s is unified with the exit  status of
    the command.

    On   Windows,    shell/[1,2]  executes   the   command   using   the
    CreateProcess() API and waits  for the command to terminate.  If the
    command  ends with a & sign, the command is handed to  the WinExec()
    API,  which does not wait for the  new task to terminate.   See also
    win_exec/2 and  win_shell/2.   Please  note that the  CreateProcess()
    API  does nnoott  imply the  Windows command  interpreter (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.

    ____________________________________________________________________|                                                                    |
    ||?-_shell('cmd.exe_/C_copy_file1.txt_file2.txt').__________________ ||

    Note  that  many  of  the  operations that  can  be  achieved  using
    the  shell built-in  commands can  easily be  achieved using  Prolog
    primitives.    See  make_directory/1, delete_file/1,  rename_file/2,
    etc.   The clib package provides filesex, implementing  various high
    level file  operations such as copy_file/2.   Using Prolog primitives
    instead of shell commands improves the portability of your program.

    The  library process  provides process_create/3 and several  related
    primitives   that   support  more   fine-grained  interaction   with
    processes, including  I/O redirection and management of asynchronous
    processes.


ggeetteennvv((_+_N_a_m_e_, _-_V_a_l_u_e))
    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.


sseetteennvv((_+_N_a_m_e_, _+_V_a_l_u_e))
    Set  an environment variable.   _N_a_m_e and _V_a_l_u_e must be  instantiated
    to  atoms or  integers.   The  environment variable  will be  passed
    to  shell/[0-2] and  can be  requested using  getenv/2.   They  also
    influence  expand_file_name/2.    Environment variables  are  shared
    between  threads.  Depending  on the underlying C library,  setenv/2
    and  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.


uunnsseetteennvv((_+_N_a_m_e))
    Remove  an environment variable from the environment.   Some systems
    lack  the underlying unsetenv() library function.  On  these systems
    unsetenv/1 sets the variable to the empty string.


sseettllooccaallee((_+_C_a_t_e_g_o_r_y_, _-_O_l_d_, _+_N_e_w))
    Set/Query  the  _l_o_c_a_l_e setting  which  tells the  C library  how  to
    interpret  text  files, write  numbers,  dates, etc.    Category  is
    one  of all, collate,  ctype, messages,  monetary, numeric or  time.
    For  details,  please consult  the C  library locale  documentation.
    See  also  section ????.     Please note  that  the locale  is  shared
    between  all  threads and  thread-safe usage  of  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 format_time/3,  collation_key/2  and
    locale_sort/2.


uunniixx((_+_C_o_m_m_a_n_d))
    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 _C_o_m_m_a_n_d's are below.

    ssyysstteemm((_+_C_o_m_m_a_n_d))
         Equivalent to calling shell/1.  Use for compatibility only.

    sshheellll((_+_C_o_m_m_a_n_d))
         Equivalent to calling shell/1.  Use for compatibility only.

    sshheellll
         Equivalent to calling shell/0.  Use for compatibility only.

    ccdd
         Equivalent to calling working_directory/2 to the expansion (see
         expand_file_name/2) of ~.  For compatibility only.

    ccdd((_+_D_i_r_e_c_t_o_r_y))
         Equivalent to calling working_directory/2.  Use for compatibil-
         ity only.

    aarrggvv((_-_A_r_g_v))
         Unify _A_r_g_v with the list of command line  arguments provided to
         this Prolog run.  Please note that Prolog  system arguments and
         application arguments are separated  by --.  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 argv.   See
         also the Prolog flag argv.


44..3355..11 WWiinnddoowwss--ssppeecciiffiicc OOppeerraattiinngg SSyysstteemm IInntteerraaccttiioonn

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,  win_exec/2 and win_shell/2  can
often be  replaced by  the more  portable shell/2 or  the more  powerful
process_create/3.


wwiinn__eexxeecc((_+_C_o_m_m_a_n_d_, _+_S_h_o_w))
    Windows  only.    Spawns  a Windows  task  without waiting  for  its
    completion.    _S_h_o_w  is  one  of the  Win32  SW_*  constants  written
    in  lowercase  without the  SW_*:   hide maximize  minimize  restore
    show showdefault  showmaximized showminimized showminnoactive showna
    shownoactive  shownormal.   In  addition,  iconic is  a synonym  for
    minimize and normal for shownormal.


wwiinn__sshheellll((_+_O_p_e_r_a_t_i_o_n_, _+_F_i_l_e_, _+_S_h_o_w))
    Windows  only.   Opens  the document  _F_i_l_e using  the Windows  shell
    rules  for doing so.  _O_p_e_r_a_t_i_o_n is one of open, print  or explore or
    another  operation registered with the shell for the  given document
    type.  On  modern systems it is also possible to pass a URL as _F_i_l_e,
    opening  the URL in Windows default  browser.  This call  interfaces
    to  the Win32 API ShellExecute().  The _S_h_o_w argument  determines the
    initial  state of the  opened window (if any).   See  win_exec/2 for
    defined values.


wwiinn__sshheellll((_+_O_p_e_r_a_t_i_o_n_, _+_F_i_l_e))
    Same as win_shell(_O_p_e_r_a_t_i_o_n_, _F_i_l_e_, _n_o_r_m_a_l)


wwiinn__rreeggiissttrryy__ggeett__vvaalluuee((_+_K_e_y_, _+_N_a_m_e_, _-_V_a_l_u_e))
    Windows  only.  Fetches  the value of a  Windows registry key.   _K_e_y
    is  an atom formed  as a path  name describing the desired  registry
    key.   _N_a_m_e  is the  desired attribute name  of the key.   _V_a_l_u_e  is
    unified  with  the value.    If  the  value is  of 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 HKEY_CURRENT_USER. Other  roots
    can be  specified explicitly as HKEY_CLASSES_ROOT, HKEY_CURRENT_USER,
    HKEY_LOCAL_MACHINE  or HKEY_USERS.  The  example below  fetches  the
    extension  to use for  Prolog files (see  README.TXT on the  Windows
    version):

    ____________________________________________________________________|                                                                    |
    | ?- win_registry_get_value(                                         |
    |        'HKEY_LOCAL_MACHINE/Software/SWI/Prolog',                   |
    |        fileExtension,                                              |

    |        Ext).                                                       |
    |                                                                    |
    ||Ext_=_pl__________________________________________________________ ||


wwiinn__ffoollddeerr((_?_N_a_m_e_, _-_D_i_r_e_c_t_o_r_y))
    True  if _N_a_m_e  is the  Windows `CSIDL'  of _D_i_r_e_c_t_o_r_y.    If _N_a_m_e  is
    unbound,  all  known Windows  special  paths are  generated.    _N_a_m_e
    is  the  CSIDL after  deleting the  leading 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:

    ____________________________________________________________________|                                                                    |
    | ?- win_folder(personal, MyDocuments).                              |

    |                                                                    |
    ||MyDocuments_=_'C:/Documents_and_Settings/jan/My_Documents'________ ||


wwiinn__aadddd__ddllll__ddiirreeccttoorryy((_+_A_b_s_D_i_r))
    This  predicate  adds  a  directory  to  the  search  path  for  de-
    pendent   DLL  files.      If  possible,   this  is  achieved   with
    win_add_dll_directory/2.   Otherwise,  %PATH% is  extended with  the
    provided  directory.     _A_b_s_D_i_r  may  be  specified  in  the  Prolog
    canonical   syntax.     See  prolog_to_os_filename/2.      Note  that
    use_foreign_library/1 passes  an absolute  path  to the  DLL if  the
    destination  DLL  can   be  located  from  the  specification  using
    absolute_file_name/3.


wwiinn__aadddd__ddllll__ddiirreeccttoorryy((_+_A_b_s_D_i_r_, _-_C_o_o_k_i_e))
    This  predicate adds a  directory to the  search path for  dependent
    DLL  files.   If the  call is  successful it unifies  _C_o_o_k_i_e with  a
    handle  that must be passed  to win_remove_dll_directory/1to  remove
    the directory from the search path.  Error conditions:

      o  This predicate is available  in the Windows port of  SWI-Prolog
         starting from 6.3.8/6.2.6.

      o  This  predicate _f_a_i_l_s  if  Windows  does not  yet  support  the
         underlying  primitives.     These  are  available  in  recently
         patched Windows 7 systems and later.

      o  This predicate  throws an  acception  if the  provided path  is
         invalid or the underlying Windows API returns an error.

    If    open_shared_object/2  is   passed   an   _a_b_s_o_l_u_t_e    path   to
    a    DLL   on   a    Windows   installation   that   supports    Ad-
    dDllDirectory()    and    friends,     SWI-Prolog    uses    LoadLi-
    braryEx()   with  the   flags   LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR   and
    LOAD_LIBRARY_SEARCH_DEFAULT_DIRS. In this  scenario, directories from
    %PATH% and _n_o_t  searched.  Additional directories can be added using
    win_add_dll_directory/2.


wwiinn__rreemmoovvee__ddllll__ddiirreeccttoorryy((_-_C_o_o_k_i_e))
    Remove     a     DLL     search    directory     installed     using
    win_add_dll_directory/2.


44..3355..22 DDeeaalliinngg wwiitthh ttiimmee aanndd ddaattee

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.  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
http://cr.yp.to/libtai.htmllibtai  to realise  conversion between  time-
stamps and calendar dates for a period of 10 million years.


44..3355..22..11 TTiimmee aanndd ddaattee ddaattaa ssttrruuccttuurreess

We use the following time representations

TTiimmeeSSttaammpp
    A  TimeStamp  is a  floating  point number  expressing the  time  in
    seconds since the Epoch at 1970-1-1.

ddaattee((_Y_,_M_,_D_,_H_,_M_n_,_S_,_O_f_f_,_T_Z_,_D_S_T))
    We  call this term a  _d_a_t_e_-_t_i_m_e structure.   The first 5 fields  are
    integers  expressing  the year,  month  (1..12), day  (1..31),  hour
    (0..23)  and minute (0..59).   The  _S field holds  the seconds as  a
    floating  point number  between 0.0  and 60.0.   _O_f_f  is an  integer
    representing  the offset relative to UTC in seconds,  where positive
    values  are west of  Greenwich.  If  converted from local time  (see
    stamp_date_time/3), _T_Z  holds the name  of the local  timezone.   If
    the  timezone is  not known,  _T_Z is  the atom  -.   _D_S_T  is true  if
    daylight saving time  applies to the current time, false if daylight
    saving  time is relevant but not effective, and - if unknown  or the
    timezone has no daylight saving time.

ddaattee((_Y_,_M_,_D))
    Date  using the  same values as  described above.   Extracted  using
    date_time_value/3.

ttiimmee((_H_,_M_n_,_S))
    Time  using the  same values as  described above.   Extracted  using
    date_time_value/3.


44..3355..22..22 TTiimmee aanndd ddaattee pprreeddiiccaatteess


ggeett__ttiimmee((_-_T_i_m_e_S_t_a_m_p))
    Return  the  current  time as  a  _T_i_m_e_S_t_a_m_p.    The  granularity  is
    system-dependent.  See section ????.


ssttaammpp__ddaattee__ttiimmee((_+_T_i_m_e_S_t_a_m_p_, _-_D_a_t_e_T_i_m_e_, _+_T_i_m_e_Z_o_n_e))
    Convert  a _T_i_m_e_S_t_a_m_p  to  a _D_a_t_e_T_i_m_e  in the  given timezone.    See
    section  ???? for details on the  data types.  _T_i_m_e_Z_o_n_e describes  the
    timezone  for the conversion.   It  is one of  local to extract  the
    local  time, 'UTC' to  extract a UTC  time or an integer  describing
    the seconds west of Greenwich.


ddaattee__ttiimmee__ssttaammpp((_+_D_a_t_e_T_i_m_e_, _-_T_i_m_e_S_t_a_m_p))
    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 stamp_date_time/3.  This example  computes
    the date 200 days after 2006-7-14:

    ____________________________________________________________________|                                                                    |
    | ?- 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)__________________________________________ ||

    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.

    ____________________________________________________________________|                                                                    |
    | 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._____________________________________________ ||

    Note   that   DST  and   offset  calculation   are   based  on   the
    POSIX  function  mktime().     If  mktime()  returns  an  error,   a
    representation_error dst is generated.


ddaattee__ttiimmee__vvaalluuee((_?_K_e_y_, _+_D_a_t_e_T_i_m_e_, _?_V_a_l_u_e))
    Extract values from a date/9 term.  Provided keys are:

       ______________________________________________________________kkeeyyvvaalluuee
       ____________________________________________________________________________________________________________________________yearCalendar year as an integer

        month            Calendar month as an integer 1..12
        day              Calendar day as an integer 1..31
        hour             Clock hour as an integer 0..23

        minute           Clock minute as an integer 0..59
        second           Clock second as a float 0.0..60.0
        utc_offset       Offset to UTC in seconds (positive is west)
        time_zone        Name of timezone; fails if unknown
        daylight_saving  Bool (true) if dst is in effect
        date             Term date(_Y_,_M_,_D)
       _time_____________Term_time(_H_,_M_,_S)____________________________


ffoorrmmaatt__ttiimmee((_+_O_u_t_, _+_F_o_r_m_a_t_, _+_S_t_a_m_p_O_r_D_a_t_e_T_i_m_e))
    Modelled  after POSIX  strftime(),  using GNU  extensions.   _O_u_t  is
    a  destination  as  specified  with  with_output_to/2.     _F_o_r_m_a_t  is
    an  atom or  string  with the  following conversions.    Conversions
    start  with a percent  (%) character.   _S_t_a_m_p_O_r_D_a_t_e_T_i_m_e is either  a
    numeric  time-stamp,  a term  date(_Y_,_M_,_D_,_H_,_M_,_S_,_O_,_T_Z_,_D_S_T)  or a  term
    date(_Y_,_M_,_D).

      a  The abbreviated weekday  name according to the current  locale.
         Use format_time/4 for POSIX locale.

      A  The full  weekday name according  to the current  locale.   Use
         format_time/4 for POSIX locale.

      b  The abbreviated  month name  according to  the current  locale.
         Use format_time/4 for POSIX locale.

      B  The full  month name  according  to the  current locale.    Use
         format_time/4 for POSIX locale.

      c  The preferred  date  and time  representation for  the  current
         locale.

      C  The century number (year/100) as a 2-digit integer.

      d  The day of the month as a decimal number (range 01 to 31).

      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.)

      e  Like %d,  the  day of  the month  as a  decimal number,  but  a
         leading zero is replaced by a space.

      E  Modifier.  Not implemented.

      f  Number of microseconds.   The f  can be prefixed by an  integer
         to print  the  desired number  of  digits.   E.g.,  %3f  prints
         milliseconds.   This  format is  not covered  by any  standard,
         but  available  with different  format  specifiers  in  various
         incarnations of the strftime() function.

      F  Equivalent to %Y-%m-%d (the ISO 8601 date format).

      g  Like  %G,  but without  century,  i.e.,  with  a  2-digit  year
         (00-99).

      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.

      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.

      h  Equivalent to %b.

      H  The hour as  a decimal number using  a 24-hour clock (range  00
         to 23).

      I  The hour as  a decimal number using  a 12-hour clock (range  01
         to 12).

      j  The day of the year as a decimal number (range 001 to 366).

      k  The hour (24-hour clock)  as a decimal number (range 0  to 23);
         single digits are preceded by a blank.  (See also %H.)

      l  The hour (12-hour clock)  as a decimal number (range 1  to 12);
         single digits are preceded by a blank.  (See also %I.)

      m  The month as a decimal number (range 01 to 12).

      M  The minute as a decimal number (range 00 to 59).

      n  A newline character.

      O  Modifier to select locale-specific output.  Not implemented.

      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'.

      P  Like %p  but in  lowercase:  `am'  or `pm'  or a  corresponding
         string for the current locale.

      r  The time in  a.m. or p.m. notation.   In the POSIX locale  this
         is equivalent to `%I:%M:%S %p'.

      R  The time in 24-hour  notation (%H:%M). For a version  including
         the seconds, see %T below.

      s  The number of seconds  since the Epoch, i.e., since  1970-01-01
         00:00:00 UTC.

      S  The second as  a decimal number (range 00  to 60).  (The  range
         is up to 60 to allow for occasional leap seconds.)

      t  A tab character.

      T  The time in 24-hour notation (%H:%M:%S).

      u  The day of the  week as a decimal,  range 1 to 7, Monday  being
         1.  See also %w.

      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.

      w  The day of the  week as a decimal,  range 0 to 6, Sunday  being
         0.  See also %u.

      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.

      x  The  preferred  date  representation  for  the  current  locale
         without the time.

      X  The  preferred  time  representation  for  the  current  locale
         without the date.

      y  The year  as a decimal  number without a  century (range 00  to
         99).

      Y  The year as a decimal number including the century.

      z  The  timezone  as  hour  offset  from  GMT   using  the  format
         HHmm.     Required  to  emit  RFC822-conforming   dates  (using
         '%a, %d %b %Y %T %z').  Our implementation supports  %:z, which
         modifies the output to  HH:mm as required by XML-Schema.   Note
         that both notations  are valid in ISO  8601.  The sequence  %:z
         is compatible to the GNU date(1) command.

      Z  The timezone or name or abbreviation.

      +  The date and time in date(1) format.

      %  A literal `%' character.

    The  table  below   gives  some  format  strings  for  popular  time
    representations.   RFC1123 is used by HTTP. The  full implementation
    of http_timestamp/2 as available from http/http_header is here.

    ____________________________________________________________________|                                                                    |

    | http_timestamp(Time, Atom) :-                                      |
    |         stamp_date_time(Time, Date, 'UTC'),                        |
    |         format_time(atom(Atom),                                    |
    |                     '%a, %d %b %Y %T GMT',                         |
    ||____________________Date,_posix)._________________________________ ||

                      __________________________________SSttaannddaarrddFFoorrmmaatt ssttrriinngg
                      ____________________________________________________________________xxssdd'%FT%T%:z'

                       IISSOO88660011   '%FT%T%z'
                       RRFFCC882222    '%a, %d %b %Y %T %z'
                      _RRFFCC11112233___'%a,_%d_%b_%Y_%T_GMT'__


ffoorrmmaatt__ttiimmee((_+_O_u_t_, _+_F_o_r_m_a_t_, _+_S_t_a_m_p_O_r_D_a_t_e_T_i_m_e_, _+_L_o_c_a_l_e))
    Format  time  given  a  specified  _L_o_c_a_l_e.    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  _L_o_c_a_l_e is posix,  which
    currently  only modifies the behaviour of  the a, A, b and  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.


ppaarrssee__ttiimmee((_+_T_e_x_t_, _-_S_t_a_m_p))
    Same as parse_time(_T_e_x_t_, ___F_o_r_m_a_t_, _S_t_a_m_p).  See parse_time/3.


ppaarrssee__ttiimmee((_+_T_e_x_t_, _?_F_o_r_m_a_t_, _-_S_t_a_m_p))
    Parse  a  textual  time  representation,   producing  a  time-stamp.
    Supported  formats  for  _T_e_x_t  are in  the  table  below.    If  the
    format  is  known,  it  may  be  given  to  reduce  parse  time  and
    avoid  ambiguities.   Otherwise, _F_o_r_m_a_t is  unified with the  format
    encountered.

                 ___________________________________________
                 |__NNaammee________||EExxaammppllee__________________________________________________||
                 || rfc_1123F|ri, 08 Dec 2006 15:29:44 GMT   |
                 |_________|Fri,_08_Dec_2006_15:29:44_+0000_|
                 | iso_86012|006-12-08T17:29:44+02:00       |

                 |         |20061208T172944+0200            |
                 |         |2006-12-08T15:29Z               |
                 |         |2006-12-08                      |
                 |         |20061208                        |
                 |         |2006-12                         |
                 |         |2006-W49-5                      |
                 |_________|2006-342________________________|


ddaayy__ooff__tthhee__wweeeekk((_+_D_a_t_e_,_-_D_a_y_O_f_T_h_e_W_e_e_k))
    Computes    the   day    of   the   week    for   a   given    date.
    _D_a_t_e = date(_Y_e_a_r,_M_o_n_t_h,_D_a_y).       Days   of  the   week  are   num-
    bered  from one to seven:   Monday = 1, Tuesday  = 2, ..., Sunday  =
    7.


44..3355..33 CCoonnttrroolllliinngg tthhee swipl-win.exe ccoonnssoollee wwiinnddooww

The Windows executable 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.


wwiinnddooww__ttiittllee((_-_O_l_d_, _+_N_e_w))
    Unify  _O_l_d with the  title displayed in  the console and change  the
    title to _N_e_w.


wwiinn__wwiinnddooww__ppooss((_+_L_i_s_t_O_f_O_p_t_i_o_n_s))
    Interface  to the  MS-Windows  SetWindowPos() function,  controlling
    size,  position and stacking order of the window.   _L_i_s_t_O_f_O_p_t_i_o_n_s is
    a list that may hold any number of the terms below:

    ssiizzee((_W_, _H))
         Change the  size of  the window.    _W  and _H  are expressed  in
         character units.

    ppoossiittiioonn((_X_, _Y))
         Change the  top-left corner  of  the window.    The values  are
         expressed in pixel units.

    zzoorrddeerr((_Z_O_r_d_e_r))
         Change the  location  in the  window stacking  order.    Values
         are bottom, top,  topmost and notopmost.   _T_o_p_m_o_s_t windows  are
         displayed above all other windows.

    sshhooww((_B_o_o_l))
         If true, show the window, if false hide the window.

    aaccttiivvaattee
         If present, activate the window.


wwiinn__hhaass__mmeennuu
    True if win_insert_menu/2 and win_insert_menu_item/4are present.


wwiinn__iinnsseerrtt__mmeennuu((_+_L_a_b_e_l_, _+_B_e_f_o_r_e))
    Insert  a new entry  (pulldown) in the  menu.   If the menu  already
    contains  this entry,  nothing  is done.    The _L_a_b_e_l  is the  label
    and,  using  the Windows  convention, a  letter prefixed  with &  is
    underlined  and defines the associated  accelerator key.  _B_e_f_o_r_e  is
    the label before which this one  must be inserted.  Using - adds the
    new  entry at the end (right).  For example, the call  below adds an
    Application entry just before the Help menu.

    ____________________________________________________________________|                                                                    |
    ||win_insert_menu('&Application',_'&Help')__________________________ ||


wwiinn__iinnsseerrtt__mmeennuu__iitteemm((_+_P_u_l_l_d_o_w_n_, _+_L_a_b_e_l_, _+_B_e_f_o_r_e_, _:_G_o_a_l))
    Add  an  item  to  the  named  _P_u_l_l_d_o_w_n menu.     _L_a_b_e_l  and  _B_e_f_o_r_e
    are  handled  as in  win_insert_menu/2,  but the  label -  inserts  a
    _s_e_p_a_r_a_t_o_r.  _G_o_a_l is called if the user selects the item.


44..3366 FFiillee SSyysstteemm IInntteerraaccttiioonn


aacccceessss__ffiillee((_+_F_i_l_e_, _+_M_o_d_e))
    True  if _F_i_l_e  exists and  can be  accessed by  this Prolog  process
    under  mode _M_o_d_e.   _M_o_d_e is  one of the  atoms read, write,  append,
    exist,  none or execute.  _F_i_l_e may also be the name  of a directory.
    Fails  silently otherwise.   access_file(File, none)simply  succeeds
    without testing anything.

    If  _M_o_d_e is  write or 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  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 open/4 and catch/3.


eexxiissttss__ffiillee((_+_F_i_l_e))
    True if _F_i_l_e exists  and is a regular file.  This does not imply the
    user  has read and/or write  permission for the file.   This is  the
    same as access_file(_F_i_l_e_, _e_x_i_s_t).


ffiillee__ddiirreeccttoorryy__nnaammee((_+_F_i_l_e_, _-_D_i_r_e_c_t_o_r_y))
    Extracts  the directory part of _F_i_l_e.   The returned _D_i_r_e_c_t_o_r_y  name
    does  not end in  /.  There  are two special  cases.  The  directory
    name  of / is  / itself, and  the directory name is  . if _F_i_l_e  does
    not  contain any / characters.  If the _F_i_l_e argument ends  with a /,
    e.g.,  '/hello/', it is  not a valid  file name.   In this case  the
    final / is removed from _F_i_l_e, e.g., '/hello'.

    See   also  directory_file_path/3  from   filesex.      The   system
    ensures  that  for   every  valid  _P_a_t_h  using  the  Prolog  (POSIX)
    directory  separators, following  is true  on systems  with a  sound
    implementation of same_file/2.  See also prolog_to_os_filename/2.

    ____________________________________________________________________|                                                                    |
    |         ...,                                                       |

    |         file_directory_name(Path, Dir),                            |
    |         file_base_name(Path, File),                                |
    |         directory_file_path(Dir, File, Path2),                     |
    ||________same_file(Path,_Path2).___________________________________ ||


ffiillee__bbaassee__nnaammee((_+_F_i_l_e_, _-_B_a_s_e_N_a_m_e))
    Extracts the filename part  from a path specification.  If _F_i_l_e does
    not contain any  directory separators, _F_i_l_e is returned in _B_a_s_e_N_a_m_e.
    See  also file_directory_name/2.   If the _F_i_l_e arguments ends  with a
    /, e.g., '/hello/', _B_a_s_e_N_a_m_e is unified with the empty atom ('').


ssaammee__ffiillee((_+_F_i_l_e_1_, _+_F_i_l_e_2))
    True  if both  filenames  refer to  the same  physical file.    That
    is,  if _F_i_l_e_1  and _F_i_l_e_2  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  st_dev  and st_inode, same_file/2
    is  implemented  by  comparing  the device  and  inode  identifiers.
    On  Windows,  same_file/2  compares  the  strings  returned  by  the
    GetFullPathName() system call.


eexxiissttss__ddiirreeccttoorryy((_+_D_i_r_e_c_t_o_r_y))
    True  if _D_i_r_e_c_t_o_r_y exists and is a  directory.  This does  not imply
    the user has read, search or write permission for the directory.


ddeelleettee__ffiillee((_+_F_i_l_e))
    Remove _F_i_l_e from the file system.


rreennaammee__ffiillee((_+_F_i_l_e_1_, _+_F_i_l_e_2))
    Rename  _F_i_l_e_1 as _F_i_l_e_2.   The semantics  is compatible to the  POSIX
    semantics  of  the rename()  system  call as  far as  the  operating
    system  allows.   Notably, if _F_i_l_e_2  exists, the operation  succeeds
    (except  for  possible permission  errors)  and is  _a_t_o_m_i_c  (meaning
    there is no window where _F_i_l_e_2 does not exist).


ssiizzee__ffiillee((_+_F_i_l_e_, _-_S_i_z_e))
    Unify _S_i_z_e with the size of _F_i_l_e in bytes.


ttiimmee__ffiillee((_+_F_i_l_e_, _-_T_i_m_e))
    Unify  the last  modification time of  _F_i_l_e with  _T_i_m_e.   _T_i_m_e is  a
    floating  point number expressing the  seconds elapsed since Jan  1,
    1970.  See also convert_time/[2,8] and get_time/1.


aabbssoolluuttee__ffiillee__nnaammee((_+_F_i_l_e_, _-_A_b_s_o_l_u_t_e))
    Expand  a  local filename  into  an absolute  path.    The  absolute
    path  is  canonicalised:    references  to .  and  ..  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 absolute_file_name/3 and
    expand_file_name/2.


aabbssoolluuttee__ffiillee__nnaammee((_+_S_p_e_c_, _-_A_b_s_o_l_u_t_e_, _+_O_p_t_i_o_n_s))
    Convert  the given file specification into  an absolute path.   _S_p_e_c
    is  a  term  Alias(Relative)  (e.g.,  (library(lists)),  a  relative
    filename  or an absolute  filename.   The primary intention of  this
    predicate is to  resolve files specified as Alias(Relative).  _O_p_t_i_o_n
    is a list of options to guide the conversion:

    eexxtteennssiioonnss((_L_i_s_t_O_f_E_x_t_e_n_s_i_o_n_s))
         List of  file extensions  to try.   Default  is ''.   For  each
         extension,  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 .ext or plain ext.

    rreellaattiivvee__ttoo((_+_F_i_l_e_O_r_D_i_r))
         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   working_directory/2)   or,   if   _S_p_e_c  is   atomic   and
         absolute_file_name/[2,3] is executed  in a  directive, it  uses
         the current source file as reference.

    aacccceessss((_M_o_d_e))
         Imposes the  condition access_file(_F_i_l_e, _M_o_d_e).    _M_o_d_e is  one
         of read,  write,  append, execute,  exist or  none.   See  also
         access_file/2.

    ffiillee__ttyyppee((_T_y_p_e))
         Defines  extensions.    Current  mapping:   txt  implies  [''],
         prolog  implies ['.pl', ''],  executable  implies  ['.so', ''],
         qlf implies  ['.qlf', '']  and  directory implies  [''].    The
         file  type source  is an  alias  for prolog  for  compatibility
         with  SICStus Prolog.     See also  prolog_file_type/2.     This
         predicate  only  returns  non-directories,  unless  the  option
         file_type(_d_i_r_e_c_t_o_r_y) is specified.

    ffiillee__eerrrroorrss((_f_a_i_l_/_e_r_r_o_r))
         If error (default),  throw an existence_error exception if  the
         file cannot be found.  If fail, stay silent.

    ssoolluuttiioonnss((_f_i_r_s_t_/_a_l_l))
         If  first (default),  the  predicate  leaves no  choice  point.
         Otherwise a  choice point  will  be left  and backtracking  may
         yield more solutions.

    eexxppaanndd((_B_o_o_l_e_a_n))
         If  true  (default   is  false)  and   _S_p_e_c  is  atomic,   call
         expand_file_name/2  followed  by   member/2   on  _S_p_e_c   before
         proceeding.    This  is  a  SWI-Prolog  extension  intended  to
         minimise  porting effort  after  SWI-Prolog  stopped  expanding
         environment  variables and  the  ~ by  default.    This  option
         should be  considered deprecated.    In particular  the use  of
         _w_i_l_d_c_h_a_r_t patterns such as * should be avoided.

    The  Prolog  flag verbose_file_search can  be set  to  true to  help
    debugging Prolog's search for files.

    This  predicate is derived from Quintus Prolog.  In  Quintus Prolog,
    the  argument order was  absolute_file_name(_+_S_p_e_c_, _+_O_p_t_i_o_n_s_,  _-_P_a_t_h).
    The  argument order has been changed for compatibility with  ISO and
    SICStus.  The Quintus argument order is still accepted.


iiss__aabbssoolluuttee__ffiillee__nnaammee((_+_F_i_l_e))
    True  if _F_i_l_e specifies  an absolute  path name.   On Unix  systems,
    this  implies the path starts with a `/'.  For  Microsoft-based sys-
    tems  this implies the path  starts with <_l_e_t_t_e_r>:.  This  predicate
    is  intended to provide  platform-independent checking for  absolute
    paths.  See also absolute_file_name/2 and prolog_to_os_filename/2.


ffiillee__nnaammee__eexxtteennssiioonn((_?_B_a_s_e_, _?_E_x_t_e_n_s_i_o_n_, _?_N_a_m_e))
    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.    _E_x_t_e_n_s_i_o_n may  be specified with  or without  a
    leading  dot (.).  If an _E_x_t_e_n_s_i_o_n is generated, it will  not have a
    leading dot.


ddiirreeccttoorryy__ffiilleess((_+_D_i_r_e_c_t_o_r_y_, _-_E_n_t_r_i_e_s))
    Unify  _E_n_t_r_i_e_s with a  list of  entries in _D_i_r_e_c_t_o_r_y.   Each  member
    of  _E_n_t_r_i_e_s is  an  atom denoting  an entry  relative to  _D_i_r_e_c_t_o_r_y.
    _E_n_t_r_i_e_s  contains  all  entries,  including  hidden  files  and,  if
    supplied  by  the OS,  the  special entries  .  and ...    See  also
    expand_file_name/2.


eexxppaanndd__ffiillee__nnaammee((_+_W_i_l_d_C_a_r_d_, _-_L_i_s_t))
    Unify  _L_i_s_t with  a  sorted list  of files  or directories  matching
    _W_i_l_d_C_a_r_d.   The  normal Unix wildcard  constructs `?', `*',  `[...]'
    and  `{...}'  are recognised.    The  interpretation  of `{...}'  is
    slightly  different from the C shell (csh(1)).   The comma-separated
    argument  can  be arbitrary  patterns,  including `{...}'  patterns.
    The  empty pattern  is  legal as  well:   `\{.pl,\}' matches  either
    `.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  $_v_a_r is expanded to  the
    value  of the  environment variable  _v_a_r, and a  possible leading  ~
    character is expanded to the user's home directory.


pprroolloogg__ttoo__ooss__ffiilleennaammee((_?_P_r_o_l_o_g_P_a_t_h_, _?_O_s_P_a_t_h))
    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 \ into /.


rreeaadd__lliinnkk((_+_F_i_l_e_, _-_L_i_n_k_, _-_T_a_r_g_e_t))
    If _F_i_l_e points to  a symbolic link, unify _L_i_n_k with the value of the
    link and _T_a_r_g_e_t to  the file the link is pointing to.  _T_a_r_g_e_t points
    to  a file, directory or non-existing entry in the file  system, but
    never  to a link.   Fails if _F_i_l_e  is not a link.   Fails always  on
    systems that do not support symbolic links.


ttmmpp__ffiillee((_+_B_a_s_e_, _-_T_m_p_N_a_m_e))                                   _[_d_e_p_r_e_c_a_t_e_d_]
    Create  a name for a temporary file.  _B_a_s_e is an  identifier for the
    category  of file.  The _T_m_p_N_a_m_e is guaranteed to be unique.   If the
    system  halts, it  will automatically  remove all created  temporary
    files.    _B_a_s_e 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 tmp_file_stream/3.


ttmmpp__ffiillee__ssttrreeaamm((_+_E_n_c_o_d_i_n_g_, _-_F_i_l_e_N_a_m_e_, _-_S_t_r_e_a_m))
    Create  a  temporary  filename  _F_i_l_e_N_a_m_e and  open  it  for  writing
    in  the  given  _E_n_c_o_d_i_n_g.    _E_n_c_o_d_i_n_g  is a  text-encoding  name  or
    binary.    _S_t_r_e_a_m is  the output  stream.   If the  OS supports  it,
    the  created file is only  accessible to the current  user.  If  the
    OS  supports it, the file  is created using the  open()-flag O_EXCL,
    which  guarantees that  the  file did  not exist  before this  call.
    This  predicate is a safe replacement  of 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):

    ____________________________________________________________________|                                                                    |
    | 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_______________ ||

    Temporary  files  created   using  this  call  are  removed  if  the
    Prolog   process  terminates  _g_r_a_c_e_f_u_l_l_y.     Calling  delete_file/1
    using  _F_i_l_e_N_a_m_e removes  the  file and  removes the  entry from  the
    administration of files-to-be-deleted.


mmaakkee__ddiirreeccttoorryy((_+_D_i_r_e_c_t_o_r_y))
    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 _u_m_a_s_k setting).


ddeelleettee__ddiirreeccttoorryy((_+_D_i_r_e_c_t_o_r_y))
    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.


wwoorrkkiinngg__ddiirreeccttoorryy((_-_O_l_d_, _+_N_e_w))
    Unify  _O_l_d with an  absolute path to  the current working  directory
    and   change  working   directory  to   _N_e_w.      Use  the   pattern
    working_directory(_C_W_D_, _C_W_D) to get the current directory.   See also
    absolute_file_name/2 and chdir/1.   Note that the working  directory
    is shared between all threads.


cchhddiirr((_+_P_a_t_h))
    Compatibility predicate.  New code should use working_directory/2.


44..3377 UUsseerr TToopp--lleevveell MMaanniippuullaattiioonn


bbrreeaakk
    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  end-of-file character (control-D). If that is  somehow not
    functional,  the  term end_of_file. can  be entered  to return  from
    the  break environment.    If  the -t toplevel  command line  option
    is  given,  this goal  is started  instead of  entering the  default
    interactive top level (prolog/0).

    Notably  the gui  based versions  (swipl-win on  Windows and  MacOS)
    provide the menu  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 _g_l_o_b_a_l  _v_a_r_i_a_b_l_e_s or  thread-local
    dynamic predicates (see thread_local/1) of the main thread.


aabboorrtt
    Abort  the Prolog  execution  and restart  the top  level.   If  the
    -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
    '$aborted'.   This  exception can be caught  using catch/3, but  the
    recovery  goal is wrapped  with a predicate  that prunes the  choice
    points  of the  recovery goal  (i.e., as once/1)  and re-throws  the
    exception.    This is  illustrated in  the example  below, where  we
    press control-C and `a'.  See also section ????.

    ____________________________________________________________________|                                                                    |
    | ?- catch((repeat,fail), E, true).                                  |

    | ^CAction (h for help) ? abort                                      |
    ||%_Execution_Aborted_______________________________________________ ||


hhaalltt                                                              _[_I_S_O_]
    Terminate  Prolog execution.   This  is the  same as halt(_0).    See
    halt/1 for details.


hhaalltt((_+_S_t_a_t_u_s))                                                     _[_I_S_O_]
    Terminate  Prolog  execution  with _S_t_a_t_u_s.    This  predicate  calls
    PL_halt() which preforms the following steps:

     1.  Set the Prolog flag exit_status to _S_t_a_t_u_s.

     2.  Call all hooks registered using at_halt/1.  If _S_t_a_t_u_s  equals 0
         (zero), any of these hooks  calls cancel_halt/1,  termination is
         cancelled.

     3.  Call all hooks  registered using PL_at_halt().   In the  future,
         if any  of these  hooks returns non-zero,  termination will  be
         cancelled.  Currently, this only prints a warning.

     4.  Perform the following system cleanup actions:

           o Cancel  all  threads,  calling thread_at_exit/1  registered
             termination hooks.  Threads  not responding within 1 second
             are cancelled forcefully.

           o Flush I/O and close all streams except for standard I/O.

           o Reset the terminal if its properties were changed.

           o Remove temporary files and incomplete compilation output.

           o Reclaim memory.

     5.  Call exit(Status) to terminate the process


pprroolloogg
    This  goal starts the  default interactive top  level.  Queries  are
    read from  the stream user_input.  See  also the Prolog flag history.
    The  prolog/0  predicate  is  terminated (succeeds)  by  typing  the
    end-of-file character (typically control-D).

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 section ????.


eexxppaanndd__qquueerryy((_+_Q_u_e_r_y_, _-_E_x_p_a_n_d_e_d_, _+_B_i_n_d_i_n_g_s_, _-_E_x_p_a_n_d_e_d_B_i_n_d_i_n_g_s))
    Hook  in module  user, normally  not defined.    _Q_u_e_r_y and  _B_i_n_d_i_n_g_s
    represents  the  query read  from  the user  and  the names  of  the
    free  variables as obtained  using read_term/3.   If this  predicate
    succeeds, it should  bind _E_x_p_a_n_d_e_d and _E_x_p_a_n_d_e_d_B_i_n_d_i_n_g_s to the query
    and  bindings to be executed  by the top level.   This predicate  is
    used  by the  top level (prolog/0).    See also  expand_answer/2 and
    term_expansion/2.


eexxppaanndd__aannsswweerr((_+_B_i_n_d_i_n_g_s_, _-_E_x_p_a_n_d_e_d_B_i_n_d_i_n_g_s))
    Hook  in module user,  normally not defined.   Expand the result  of
    a  successfully executed  top-level query.   _B_i_n_d_i_n_g_s  is the  query
    < Name >=<_V_a_l_u_e> binding list  from the query.    _E_x_p_a_n_d_e_d_B_i_n_d_i_n_g_s
    must be unified with the bindings the top level should print.


44..3388 CCrreeaattiinngg aa PPrroottooccooll ooff tthhee UUsseerr IInntteerraaccttiioonn

SWI-Prolog offers the  possibility to log the interaction with  the user
on  a file.    All  Prolog interaction,  including warnings  and  tracer
output, are written to the protocol file.


pprroottooccooll((_+_F_i_l_e))
    Start  protocolling on file  _F_i_l_e.  If  there is already a  protocol
    file open, then close it first.  If _F_i_l_e exists it is truncated.


pprroottooccoollaa((_+_F_i_l_e))
    Equivalent  to protocol/1,  but  does not  truncate the  _F_i_l_e if  it
    exists.


nnoopprroottooccooll
    Stop  making a protocol of the user interaction.  Pending  output is
    flushed on the file.


pprroottooccoolllliinngg((_-_F_i_l_e))
    True  if a protocol was  started with protocol/1 or protocola/1  and
    unifies _F_i_l_e with the current protocol output file.


44..3399 DDeebbuuggggiinngg aanndd TTrraacciinngg PPrrooggrraammss

This section is a  reference to the debugger interaction predicates.   A
more use-oriented overview of the debugger is in section ????.

If you have installed  XPCE, you can use the graphical front-end  of the
tracer.  This front-end is installed using the predicate guitracer/0.


ttrraaccee
    Start  the tracer.   trace/0  itself cannot be  seen in the  tracer.
    Note  that the  Prolog top level  treats trace/0  special; it  means
    `trace the next goal'.


ttrraacciinngg
    True  if the  tracer is  currently switched  on.   tracing/0  itself
    cannot be seen in the tracer.


nnoottrraaccee
    Stop the tracer.  notrace/0 itself cannot be seen in the tracer.


gguuiittrraacceerr
    Installs  hooks  (see 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.


nnoogguuiittrraacceerr
    Revert back to the textual tracer.


ttrraaccee((_+_P_r_e_d))
    Equivalent to trace(_P_r_e_d, +all).


ttrraaccee((_+_P_r_e_d_, _+_P_o_r_t_s))
    Put  a  trace  point  on all  predicates  satisfying  the  predicate
    specification  _P_r_e_d.   _P_o_r_t_s is  a list of  port names (call,  redo,
    exit,  fail).   The atom all refers  to all ports.   If the port  is
    preceded  by a - sign, the trace point is cleared for the port.   If
    it is preceded by a +, the trace point is set.

    The  predicate trace/2  activates debug  mode (see 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 trace/0.  Unlike trace/0, however,
    the  execution is continued without asking for  further information.
    Examples:

        ?- trace(hello).         Trace all  ports of hello  with any
                                 arity in any module.
        ?- trace(foo/2, +fail).  Trace  failures  of  foo/2  in  any
                                 module.
        ?- trace(bar/1, -all).   Stop tracing bar/1.

    The predicate debugging/0 shows all currently defined trace points.


nnoottrraaccee((_:_G_o_a_l))
    Call  _G_o_a_l,  but  suspend  the  debugger while  _G_o_a_l  is  executing.
    The  current implementation  cuts the  choice points  of _G_o_a_l  after
    successful completion.   See once/1.  Later implementations may have
    the same semantics as call/1.


ddeebbuugg
    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 debug.

    Note  that the 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 __G_<_N_N_N_>  variables and
    replaces  unreachable variables  with the atom  <garbage_collected>.
    Calling  nodebug/0 does  _n_o_t reset the  initial free-margin  because
    several  parts of the  top level and  debugger disable debugging  of
    system code regions.  See also set_prolog_stack/2.


nnooddeebbuugg
    Stop  debugger.   Implemented by the  Prolog flag debug.   See  also
    debug/0.


ddeebbuuggggiinngg
    Print  debug status and  spy points on current  output stream.   See
    also the Prolog flag debug.


ssppyy((_+_P_r_e_d))
    Put  a spy point on all predicates meeting the  predicate specifica-
    tion _P_r_e_d.  See section ????.


nnoossppyy((_+_P_r_e_d))
    Remove   spy  point  from  all  predicates  meeting   the  predicate
    specification _P_r_e_d.


nnoossppyyaallll
    Remove all spy points from the entire program.


lleeaasshh((_?_P_o_r_t_s))
    Set/query leashing (ports  which allow for user interaction).  _P_o_r_t_s
    is  one of _+_N_a_m_e, _-_N_a_m_e,  _?_N_a_m_e or a list  of these.  _+_N_a_m_e  enables
    leashing  on that  port,  _-_N_a_m_e disables  it and  _?_N_a_m_e succeeds  or
    fails according to  the current setting.  Recognised ports are call,
    redo,  exit, fail and  unify.  The  special shorthand all refers  to
    all  ports,  full refers  to all  ports except  for  the unify  port
    (default).  half refers to the call, redo and fail port.


vviissiibbllee((_+_P_o_r_t_s))
    Set the ports shown  by the debugger.  See leash/1 for a description
    of the _P_o_r_t_s specification.  Default is full.


uunnkknnoowwnn((_-_O_l_d_, _+_N_e_w))
    Edinburgh-Prolog  compatibility predicate,  interfacing  to the  ISO
    Prolog  flag unknown.   Values are  trace (meaning error) and  fail.
    If  the unknown flag is set to warning, unknown/2 reports  the value
    as trace.


ssttyyllee__cchheecckk((_+_S_p_e_c))
    Modify/query  style checking  options.   _S_p_e_c  is one  of the  terms
    below or a list of these.

      o  +_S_t_y_l_e enables a style check

      o  -_S_t_y_l_e disables a style check

      o  ?(_S_t_y_l_e) queries a style  check (note the brackets).   If _S_t_y_l_e
         is unbound,  all  active style  check options  are returned  on
         backtracking.

    Loading  a file using 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 _a_f_t_e_r changing the style checking.

    ssiinngglleettoonn((_t_r_u_e))
         The  predicate 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 section ???? for details on variable handling and warnings.

    nnoo__eeffffeecctt((_t_r_u_e))
         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 ==/2 against  a not-yet-initialised  variable
         as  illustrated in  the  example below.    This  comparison  is
         always false.

         _______________________________________________________________|                                                               |
         |always_false(X) :-                                             |
         |        X == Y,                                                |
         ||_______write(Y)._____________________________________________ ||

    vvaarr__bbrraanncchheess((_f_a_l_s_e))
         Verifies that if a variable is introduced in a  branch and used
         _a_f_t_e_r the branch, it is introduced in all branches.   This code
         aims at bugs  following the skeleton  below, where p(_N_e_x_t)  may
         be called with _N_e_x_t unbound.

         _______________________________________________________________|                                                               |

         |p(Arg) :-                                                      |
         |        (  Cond                                                |
         |        -> Next = value1                                       |
         |        ;  true                                                |
         |        ),                                                     |
         ||_______p(Next).______________________________________________ ||

         If a variable  _V is intended  to be left  unbound, one can  use
         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  _s_e_m_a_n_t_i_c  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.

    ddiissccoonnttiigguuoouuss((_t_r_u_e))
         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 discontiguous/1 directive.

    cchhaarrsseett((_f_a_l_s_e))
         Warn on atoms  and variable names holding non-ASCII  characters
         that are not quoted.  See also section ????.


44..4400 OObbttaaiinniinngg RRuunnttiimmee SSttaattiissttiiccss


ssttaattiissttiiccss((_+_K_e_y_, _-_V_a_l_u_e))
    Unify system statistics  determined by _K_e_y with _V_a_l_u_e.  The possible
    keys are given in  the table ????.  This predicate supports additional
    keys  for  compatibility  reasons.    These  keys are  described  in
    table ????.
___________________________________________________________________________
|__________________Native_keys_(times_as_float_in_seconds)_________________|
| agc             |Number of atom garbage collections performed           |
| agc_gained      N|umber of atoms removed                                |
| agc_time        T|ime spent in atom garbage collections                 |
| atoms           |Total number of defined atoms                          |
| c_stack         S|ystem (C-) stack limit.  0 if not known.              |

| cgc             |Number of clause garbage collections performed         |
| cgc_gained      N|umber of clauses reclaimed                            |
| cgc_time        T|ime spent in clause garbage collections               |
| clauses         |Total number of clauses in the program                 |
| codes           |Total size of (virtual) executable code in words       |
| cputime         |(User) 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   N|umber 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    N|umber 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_usedA|mount of bytes in use by the thread's answer tables   |
| trail           |Allocated size of the trail stack in bytes             |

| trail_shifts    N|umber 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      T|ime 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.                |
| process_epoch   T|ime stamp when Prolog was started                     |

| process_cputime (|User) cpu time since Prolog was started in seconds    |
| thread_cputime  M|T-version:  Seconds CPU time used by finished threads.|
|                 B|asically  non-portable.     Works  on  Linux,  MacOSX,|
|                 W|indows and probably some more.                        |
| threads         |MT-version:  number of active threads                  |
| threads_created M|T-version:  number of created threads                 |
| engines         |MT-version:  number of existing engines                |

|_engines_created_M|T-version:__number_of_created_engines_________________|_

Table 4.3:  Keys for  statistics/2.  Space is expressed in bytes.   Time

is expressed in seconds, represented as a floating point number.
____________________________________________________________________________________
|_____________________Compatibility_keys_(times_in_milliseconds)____________________|
| 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. |
|                          S|ee get_time/1)                                        |
| walltime                 |[  Wall  time  since  start,   Wall  time  since  last]|
|                          |(milliseconds, SICStus compatibility)                  |
| memory                   |[ Total unshared data,  free memory ] (Uses getrusage()|
|                          |if available, otherwise incomplete own statistics.)    |

| 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 ] |
|                          T|he last column is a SWI-Prolog extension.  It contains|

|                          t|he  sum of  the  memory  left  after  each collection,|
|                          w|hich can be  divided by the count  to find the average|
|                          w|orking set size  after GC. Use  [Count, Gained, Time|_]|
|                          f|or 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_________________________________________|_

Table 4.4:  Compatibility  keys for statistics/2.  Time is  expressed in

milliseconds.


ssttaattiissttiiccss
    Display a table of system statistics on the stream user_error.


ttiimmee((_:_G_o_a_l))
    Execute  _G_o_a_l  just  like call/1  and  print time  used,  number  of
    logical   inferences  and  the  average  number  of   _l_i_p_s  (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  _G_o_a_l is non-deterministic,  print statistics for each  solution,
    where the reported values are relative to the previous answer.


44..4411 EExxeeccuuttiioonn pprrooffiilliinngg

This  section describes  the  hierarchical  execution profiler.     This
profiler is based  on ideas from gprof described  in [??].  The  profiler
consists of two  parts:  the information-gathering component built  into
the  kernel,  and a  presentation  component  which is  defined  in  the
statistics  library.    The  latter can  be  hooked,  which is  used  by
the  XPCE module  swi/pce_profile to  provide an  interactive  graphical
frontend for the results.


44..4411..11 PPrrooffiilliinngg pprreeddiiccaatteess

The following predicates are defined to interact with the profiler.


pprrooffiillee((_:_G_o_a_l))
    Execute _G_o_a_l just  like once/1, collecting profiling statistics, and
    call  show_profile(_[_]).   With XPCE installed this opens  a graphical
    interface to examine the collected profiling data.


pprrooffiillee((_:_G_o_a_l_, _+_O_p_t_i_o_n_s))
    Execute  _G_o_a_l  just  like  once/1.    Collect  profiling  statistics
    according  to _O_p_t_i_o_n_s  and call  show_profile/1 with _O_p_t_i_o_n_s.    The
    default collects CPU  profiling and opens a graphical interface when
    provided,  printing the `plain' time usage of the top  25 predicates
    as a ballback.   Options are described below.  Remaining options are
    passed to show_profile/1.

    ttiimmee((_+_W_h_i_c_h))
         If _W_h_i_c_h is cpu  (default), collect CPU timing statistics.   If
         wall, collect  wall time  statistics based on  a 5  millisecond
         sampling rate.    Wall time statistics  can be  useful if  _G_o_a_l
         calls blocking system calls.


sshhooww__pprrooffiillee((_+_O_p_t_i_o_n_s))
    This  predicate first calls  prolog:show_profile_hook/1.   If XPCE  is
    loaded,  this hook is used to activate a GUI interface  to visualise
    the  profile results.  If not,  a report is printed to  the terminal
    according to _O_p_t_i_o_n_s:

    ttoopp((_+_N))
         Show the only top _N predicates.  Default is 25.

    ccuummuullaattiivvee((_+_B_o_o_l))
         If true (default false), include the time spent  in children in
         the time reported for a predicate.


pprrooffiilleerr((_-_O_l_d_, _+_N_e_w))
    Query or change the status of the profiler.  The status is one of

    ffaallssee
         The profiler is not activated.

    ccppuuttiimmee
         The profiler collects CPU statistics.

    wwaallllttiimmee
         The profiler collects wall time statistics.

    The   value  true  is  accepted   as  a  synonym  for  cputime   for
    compatibility reasons.


rreesseett__pprrooffiilleerr
    Switches the profiler to false and clears all collected statistics.


nnoopprrooffiillee((_+_N_a_m_e_/_+_A_r_i_t_y_, _._._.))
    Declares  the predicate _N_a_m_e/_A_r_i_t_y to be invisible to  the profiler.
    The  time  spent in  the named  predicate is  added  to the  caller,
    and  the  callees are  linked  directly  to the  caller.    This  is
    particularly  useful  for  simple meta-predicates  such  as  call/1,
    ignore/1, catch/3, etc.


44..4411..22 VViissuuaalliizziinngg pprrooffiilliinngg ddaattaa

Browsing  the annotated  call-tree  as described  in section  ????  itself
is  not  very  attractive.      Therefore,  the  results   are  combined
per  predicate,  collecting all  _c_a_l_l_e_r_s  and  _c_a_l_l_e_e_s as  well  as  the
propagation  of time  and activations  in both  directions.   Figure  ????
illustrates  this.     The  central  yellowish  line  is  the  `current'
predicate with  counts for time  spent in  the predicate (`Self'),  time
spent in  its children  (`Siblings'), activations through  the call  and
redo ports.   Above  that are the _c_a_l_l_e_r_s.   Here,  the two time  fields
indicate  how much  time is  spent serving  each of  the callers.    The
columns sum to the time in the yellowish  line.  The caller <_r_e_c_u_r_s_i_v_e>
is the  number of recursive calls.   Below  the yellowish lines are  the
callees,  with the  time  spent in  the callee  itself for  serving  the
current  predicate and  the time  spent  in the  callees of  the  callee
('Siblings'), so  the whole time-block adds  up to the `Siblings'  field
of the current predicate.   The `Access' fields show how many  times the
current predicate accesses each of the callees.

The predicates have a  menu that allows changing the view of  the detail
window to the given  caller or callee, showing the documentation  (if it
is a built-in) and/or jumping to the source.

The  statistics  shown  in  the report  field  of  figure  ????  show  the
following information:

  o _s_a_m_p_l_e_s
    Number  of  times  the call-tree  was  sampled for  collecting  time
    statistics.   On most hardware,  the resolution of SIGPROF is  1/100
    second.    This number must  be sufficiently  large to get  reliable
    timing  figures.   The  Time menu  allows viewing  time as  samples,
    relative time or absolute time.

  o _s_e_c
    Total user CPU time with the profiler active.

  o _p_r_e_d_i_c_a_t_e_s
    Total  count of predicates that have  been called at least one  time
    during the profile.

  o _n_o_d_e_s
    Number of nodes in the call-tree.

  o _d_i_s_t_o_r_t_i_o_n
    How  much  of  the  time  is  spent  building  the  call-tree  as  a
    percentage  of the total execution time.   Timing samples while  the
    profiler is building the call-tree are not added to the call-tree.


44..4411..33 IInnffoorrmmaattiioonn ggaatthheerriinngg

While  the program  executes under  the profiler,  the  system builds  a
_d_y_n_a_m_i_c call-tree.    It does this  using three  hooks from the  kernel:
one  that starts  a  new goal  (_p_r_o_f_C_a_l_l),  one  that tells  the  system
which goal is  resumed after an _e_x_i_t  (_p_r_o_f_E_x_i_t) and one that tells  the
system which  goal is  resumed after a  _f_a_i_l (i.e.,  which goal is  used
to _r_e_t_r_y  (_p_r_o_f_R_e_d_o)).   The  profCall() function finds  or creates  the
subnode for  the argument predicate below  the current node,  increments
the call-count of this  link and returns the sub-node which  is recorded
in the Prolog  stack-frame.  Choice-points  are marked with the  current
profiling  node.   profExit()  and profRedo()  pass  the profiling  node
where execution resumes.

Just using the above  algorithm would create a much too big tree  due to
recursion.  For this reason the system performs  detection of recursion.
In the  simplest case,  recursive procedures  increment the  `recursive'
count on  the current node.   Mutual recursion,  however, is not  easily
detected.   For example,  call/1 can call a  predicate that uses  call/1
itself.   This  can be  viewed as a  recursive invocation,  but this  is
generally not  desirable.   Recursion is currently  assumed if the  same
predicate _w_i_t_h _t_h_e _s_a_m_e _p_a_r_e_n_t appears higher in the  call-graph.  Early
experience with some non-trivial programs are promising.

The  last part  of the  profiler  collects statistics  on the  CPU  time
used in each  node.  On  systems providing setitimer() with SIGPROF,  it
`ticks' the  current node of  the call-tree each  time the timer  fires.
On Windows, a MM-timer in a separate thread checks  100 times per second
how much  time is  spent in  the profiled thread  and adds  this to  the
current node.  See section ???? for details.


44..4411..33..11 PPrrooffiilliinngg iinn tthhee WWiinnddoowwss IImmpplleemmeennttaattiioonn

Profiling  in the  Windows version  is similar,  but as  profiling is  a
statistical process  it is good  to be aware  of the implementation  for
proper interpretation of the results.

Windows does not  provide timers that fire asynchronously,  frequent and
proportional to the CPU time used by the process.   Windows does provide
multi-media  timers that  can  run at  high  frequency.    Such  timers,
however, run  in a separate  thread of execution and  they are fired  on
the wall clock  rather than the amount of  CPU time used.  The  profiler
installs such a timer running, for saving CPU  time, rather inaccurately
at about 100 Hz.   Each time it is fired, it determines the CPU  time in
milliseconds used by Prolog since  the last time it was fired.   If this
value is non-zero, active predicates are incremented with this value.


44..4422 MMeemmoorryy MMaannaaggeemmeenntt


ggaarrbbaaggee__ccoolllleecctt
    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  trim_stacks/0 is  invoked to  release  the
    collected memory resources.


ggaarrbbaaggee__ccoolllleecctt__aattoommss
    Reclaim  unused atoms.  Normally invoked  after 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 garbage_collect_atoms/0
    returns  immediately.    Note that  there is  no  guarantee it  will
    _e_v_e_r  happen,  as there  may always  be  threads performing  garbage
    collection.


ggaarrbbaaggee__ccoolllleecctt__ccllaauusseess
    Reclaim  retracted clauses.    During  normal operation,  retracting
    a  clause  implies  setting the  _e_r_a_s_e_d  _g_e_n_e_r_a_t_i_o_n to  the  current
    _g_e_n_e_r_a_t_i_o_n  of the database and  increment the generation.   Keeping
    the clause around  is both needed to realise the _l_o_g_i_c_a_l _u_p_d_a_t_e _v_i_e_w
    and  deal with  the fact  that other  threads may  be executing  the
    clause.  Both static and dynamic code is processed this way..

    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  _r_e_l_o_a_d_i_n_g 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).


sseett__pprroolloogg__ggcc__tthhrreeaadd((_C))
    ontrol  whether  or  not  atom and  clause  garbage  collection  are
    executed  in a dedicated thread.   The default is true.   Values for
    _S_t_a_t_u_s  are true, false and  stop.  The  latter stops the gc  thread
    but  allows is to be recreated lazily.  This is use by  e.g., fork/1
    to avoid forking a multi-threaded application.  See also gc_thread.


ttrriimm__ssttaacckkss
    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:

    ____________________________________________________________________|                                                                    |
    | loop :-                                                            |
    |         generator,                                                 |
    |             trim_stacks,                                           |

    |             potentially_expensive_operation,                       |
    ||________stop_condition,_!.________________________________________ ||

    The  Prolog top-level loop  is written  this way, reclaiming  memory
    resources after every user query.


sseett__pprroolloogg__ssttaacckk((_+_S_t_a_c_k_, _+_K_e_y_V_a_l_u_e))
    Set a parameter for  one of the Prolog runtime stacks.  _S_t_a_c_k is one
    of local, global,  trail or argument.  The table below describes the
    _K_e_y(_V_a_l_u_e)  pairs.  _V_a_l_u_e  can be an arithmetic integer  expression.
    For  example, to specify a 2 GB limit for the global stack,  one can
    use:

    ____________________________________________________________________|                                                                    |
    ||?-_set_prolog_stack(global,_limit(2*10**9)).______________________ ||

    Current settings can be retrieved with prolog_stack_property/2.

    lliimmiitt((_+_B_y_t_e_s))
         Set the  limit to  which the  stack  is allowed  to grow.    If
         the  specified  value  is  lower  than  the   current  usage  a
         permission_error is  raised.    If  the  limit is  larger  than
         supported, the system  silently reduces the requested limit  to
         the system limit.

    mmiinn__ffrreeee((_+_C_e_l_l_s))
         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  spare  stack  amount  is  reported  and
         specified in `cells'.  A cell is 4 bytes in  the 32-bit version
         and 8 bytes on the 64-bit version.  See address_bits.  See also
         trim_stacks/0 and debug/0.

    llooww((_+_C_e_l_l_s))
    ffaaccttoorr((_+_N_u_m_b_e_r))
         These  two  figures  determine  whether,  if   the  stacks  are
         low,  a  stack  _s_h_i_f_t  (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> factorl* astused+low.

    ssppaarree((_+_C_e_l_l_s))
         All  stacks  trigger  overflow  before  actually  reaching  the
         limit,  so  the  resulting error  can  be  handled  gracefully.
         The spare  stack is used  for print_message/2 from the  garbage
         collector and for handling  exceptions.  The default  suffices,
         unless  the user  redefines  related hooks.    Do  nnoott  specify
         large values for this  because it reduces the amount  of memory
         available for your real task.

         Related  hooks  are message_hook/3  (redefining  GC  messages),
         prolog_trace_interception/4and prolog_exception_hook/4.


pprroolloogg__ssttaacckk__pprrooppeerrttyy((_?_S_t_a_c_k_, _?_K_e_y_V_a_l_u_e))
    True   if  _K_e_y_V_a_l_u_e  is   a  current  property   of  _S_t_a_c_k.      See
    set_prolog_stack/2 for defined properties.


44..4433 WWiinnddoowwss DDDDEE iinntteerrffaaccee

The  predicates in  this  section  deal with  MS-Windows  `Dynamic  Data
Exchange'  or DDE  protocol.    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
_O_p_e_r_a_t_i_o_n  is  the name  of  the  (partial) operation  that  failed  and
_M_e_s_s_a_g_e is a translation  of the operator error code.  For  some errors,
_C_o_n_t_e_x_t provides additional comments.

________________________________________________________________________|                                                                        |
||_______error(dde_error(Operation,_Message),_Context)__________________ ||


44..4433..11 DDDDEE cclliieenntt iinntteerrffaaccee

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:

________________________________________________________________________|                                                                        |
|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.|_________________________________________________________________ |     |

For  details   on  interacting  with   progman,   use  the  SDK   online
manual  section on  the  Shell  DDE interface.     See also  the  Prolog
library(progman),  which  may be  used  to  write simple  Windows  setup
scripts in Prolog.


ooppeenn__ddddee__ccoonnvveerrssaattiioonn((_+_S_e_r_v_i_c_e_, _+_T_o_p_i_c_, _-_H_a_n_d_l_e))
    Open a conversation  with a server supporting the given service name
    and  topic (atoms).    If successful,  _H_a_n_d_l_e  may be  used to  send
    transactions  to the server.    If no willing  server is found  this
    predicate fails silently.


cclloossee__ddddee__ccoonnvveerrssaattiioonn((_+_H_a_n_d_l_e))
    Close  the  conversation   associated  with  _H_a_n_d_l_e.     All  opened
    conversations  should  be  closed  when they're  no  longer  needed,
    although  the system  will  close any  that remain  open on  process
    termination.


ddddee__rreeqquueesstt((_+_H_a_n_d_l_e_, _+_I_t_e_m_, _-_V_a_l_u_e))
    Request  a value from the server.   _I_t_e_m is an atom  that identifies
    the requested  data, and _V_a_l_u_e will be a string (CF_TEXT data in DDE
    parlance) representing that data, if the request is successful.


ddddee__eexxeeccuuttee((_+_H_a_n_d_l_e_, _+_C_o_m_m_a_n_d))
    Request  the  DDE  server  to  execute  the  given  command  string.
    Succeeds  if the command could be  executed and fails with an  error
    message otherwise.


ddddee__ppookkee((_+_H_a_n_d_l_e_, _+_I_t_e_m_, _+_C_o_m_m_a_n_d))
    Issue  a POKE command to the server on the specified _I_t_e_m.   _c_o_m_m_a_n_d
    is passed as data of type CF_TEXT.


44..4433..22 DDDDEE sseerrvveerr mmooddee

The  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 library(dde).


ddddee__rreeggiisstteerr__sseerrvviiccee((_+_T_e_m_p_l_a_t_e_, _+_G_o_a_l))
    Register  a server  to handle  DDE request or  DDE execute  requests
    from  other applications.  To register a service for a  DDE request,
    _T_e_m_p_l_a_t_e is of the form:

         +Service(+Topic, +Item, +Value)

    _S_e_r_v_i_c_e  is the name  of the DDE  service provided (like progman  in
    the  client example  above).   _T_o_p_i_c is either  an atom,  indicating
    _G_o_a_l  only handles requests on this  topic, or a variable that  also
    appears  in _G_o_a_l.  _I_t_e_m and _V_a_l_u_e are variables that also  appear in
    _G_o_a_l.  _I_t_e_m represents the request data as a Prolog atom.

    The   example  below  registers   the  Prolog  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.

    ____________________________________________________________________|                                                                    |
    | ?- 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/'_________________________________ ||

    Handling  DDE execute requests  is very similar.   In this case  the
    template is of the form:

         +Service(+Topic, +Item)

    Passing  a _V_a_l_u_e argument is  not needed as execute requests  either
    succeed  or fail.  If _G_o_a_l  fails, a `not processed' is  passed back
    to the caller of the DDE request.


ddddee__uunnrreeggiisstteerr__sseerrvviiccee((_+_S_e_r_v_i_c_e))
    Stop  responding  to  _S_e_r_v_i_c_e.     If  Prolog  is  halted,  it  will
    automatically call this on all open services.


ddddee__ccuurrrreenntt__sseerrvviiccee((_-_S_e_r_v_i_c_e_, _-_T_o_p_i_c))
    Find currently registered services and the topics served on them.


ddddee__ccuurrrreenntt__ccoonnnneeccttiioonn((_-_S_e_r_v_i_c_e_, _-_T_o_p_i_c))
    Find currently open conversations.


44..4444 MMiisscceellllaanneeoouuss


ddwwiimm__mmaattcchh((_+_A_t_o_m_1_, _+_A_t_o_m_2))
    True  if _A_t_o_m_1 matches _A_t_o_m_2  in the `Do What  I Mean' sense.   Both
    _A_t_o_m_1  and _A_t_o_m_2  may also be  integers or  floats.   The two  atoms
    match if:

      o  They are identical

      o  They differ by one character (spy  spu)

      o  One character is inserted/deleted (debug  deug)

      o  Two characters are transposed (trace  tarce)

      o  `Sub-words' are glued  differently (existsfile   existsFile
         exists_file)

      o  Two   adjacent   sub-words   are  transposed   (existsFile
         fileExists)


ddwwiimm__mmaattcchh((_+_A_t_o_m_1_, _+_A_t_o_m_2_, _-_D_i_f_f_e_r_e_n_c_e))
    Equivalent  to  dwim_match/2,  but unifies  _D_i_f_f_e_r_e_n_c_e  with an  atom
    identifying  the difference  between _A_t_o_m_1  and _A_t_o_m_2.   The  return
    values  are (in the same  order as above):   equal, mismatched_char,
    inserted_char, transposed_char, separated and transposed_word.


wwiillddccaarrdd__mmaattcchh((_+_P_a_t_t_e_r_n_, _+_S_t_r_i_n_g))
    True  if _S_t_r_i_n_g matches  the wildcard pattern  _P_a_t_t_e_r_n.  _P_a_t_t_e_r_n  is
    very  similar to the  Unix csh  pattern matcher.   The patterns  are
    given below:

     ?      Matches one arbitrary character.
     *      Matches any number of arbitrary characters.
     [...]  Matches one of the characters specified between the brackets.
            <_c_h_a_r_1>-<_c_h_a_r_2>indicates a range.
     {...}  Matches any of the patterns of the comma-separated list between the braces.

    Example:

    ____________________________________________________________________|                                                                    |
    | ?- wildcard_match('[a-z]*.{pro,pl}[%~]', 'a_hello.pl%').           |
    ||true._____________________________________________________________ ||


sslleeeepp((_+_T_i_m_e))
    Suspend  execution _T_i_m_e seconds.   _T_i_m_e  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 aatt lleeaasstt _T_i_m_e seconds.

    On  Unix systems the  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.


CChhaapptteerr 55..  SSWWII--PPRROOLLOOGG EEXXTTEENNSSIIOONNSS

This  chapter describes  extensions to  the  Prolog language  introduced
with SWI-Prolog version  7.  The  changes bring more modern  syntactical
conventions to  Prolog such as key-value  maps, called _d_i_c_t_s as  primary
citizens  and a  restricted form  of  _f_u_n_c_t_i_o_n_a_l _n_o_t_a_t_i_o_n.    They  also
extend Prolog basic types with strings, providing a  natural notation to
textual material as opposed to identifiers (atoms) and lists.

These extensions make the  syntax more intuitive to new users,  simplify
the integration  of domain  specific languages (DSLs)  and facilitate  a
more natural Prolog  representation for popular exchange languages  such
as XML and JSON.

While many programs  run unmodified in SWI-Prolog version 7,  especially
those  that  pass   double  quoted  strings  to  general  purpose   list
processing  predicates  require  modifications.     We  provide  a  tool
(list_strings/0) that we used to port a huge code base in half a day.


55..11 LLiissttss aarree ssppeecciiaall

As of version 7, SWI-Prolog lists can be  distinguished unambiguously at
runtime from ./2  terms and the atom '[]'.   The constant [] is  special
constant that is not an atom.  It has the following properties:

________________________________________________________________________|                                                                        |
|?- atom([]).                                                            |

|false.                                                                  |
|?- atomic([]).                                                          |
|true.                                                                   |
|?- [] == '[]'.                                                          |
|false.                                                                  |
|?- [] == [].                                                            |
|true.|_________________________________________________________________ |     |

The `cons' operator for creating list cells has changed  from the pretty
atom  '.' to  the ugly  atom '[|]',  so we  can  use the  '.' for  other
purposes.  See section ????.

This modification has  minimal impact on typical  Prolog code.  It  does
affect  foreign code  (see section  ????) that  uses the  normal atom  and
compound term interface for manipulation lists.  In  most cases this can
be avoided by using the dedicated list functions.   For convenience, the
macros ATOM_nil and ATOM_dot are provided by SWI-Prolog.h.

Another  place  that  is  affected is  write_canonical/1.     Impact  is
minimized  by  using  the  list  syntax  for  lists.     The  predicates
read_term/2 and  write_term/2 support the  option dotlists(_t_r_u_e),  which
causes read_term/2 to read .(a,[]) as [a]  and write_term/2to  write [a]
as .(a,[]).


55..11..11 MMoottiivvaattiinngg ''[|]'' aanndd [] ffoorr lliissttss

Representing lists the conventional way using ./2 as  cons-cell and '[]'
as list  terminator both  (independently) poses  conflicts, while  these
conflicts are easily avoided.

  o Using  ./2 prevents using this  commonly used symbol as an  operator
    because  a.B  cannot   be  distinguished  from  [a|B].  Freeing  ./2
    provides  us  with a  unique term  that we  can  use for  functional
    notation on dicts as described in section ????.

  o Using  '[]' as list terminator prevents dynamic  distinction between
    atoms  and lists.    As a result,  we cannot  use type  polymorphism
    that  involve both  atoms and  lists.   For example,  we cannot  use
    _m_u_l_t_i  _l_i_s_t_s  (arbitrary  deeply nested  lists)  of  atoms.    Multi
    lists  of atoms are  in some situations  a good representation of  a
    flat  list that is assembled from  sub sequences.  The  alternative,
    using  difference lists or DCGs is often less natural  and sometimes
    demands  for `opening' proper  lists (i.e.,  copying the list  while
    replacing  the terminating  empty list  with a  variable) that  have
    to  be  added to  the sequence.    The ambiguity  of  atom and  list
    is  particularly painful when mapping external  data representations
    that do not suffer from this ambiguity.

    At  the same  time, avoiding  '[]' as  a list  terminator makes  the
    various  text representations unambiguous, which allows us  to write
    predicates  that require  a textual argument  to accept both  atoms,
    strings,  and  lists  of  character codes  or  one-character  atoms.
    Traditionally, the empty  list can be interpreted both as the string
    "[]" and "".


55..22 TThhee ssttrriinngg ttyyppee aanndd iittss ddoouubbllee qquuootteedd ssyynnttaaxx

As  of SWI-Prolog  version  7, text  enclosed  in double  quotes  (e.g.,
"Hello world")  is read  as  objects  of the  type  _s_t_r_i_n_g.    A  string
is  a compact  representation  of a  character  sequence that  lives  on
the  global  (term) stack.     Strings represent  sequences  of  Unicode
characters including the  character code 0 (zero).   The length  strings
is  limited by  the available  space  on the  global (term)  stack  (see
set_prolog_stack/2).   Strings  are distinct from  lists, which makes  it
possible  to detect  them at  runtime and  print them  using the  string
syntax, as illustrated below:

________________________________________________________________________|                                                                        |
|?- write("Hello world!").                                               |

|Hello world!                                                            |
|                                                                        |
|?- writeq("Hello world!").                                              |
|"Hello|world!"_________________________________________________________ |      |

_B_a_c_k _q_u_o_t_e_d text (as  in `text`) is mapped to a list of  character codes
in version 7.   The settings for  the flags that control how double  and
back quoted  text is  read is  summarised in table  ????.   Programs  that
aim for compatibility should realise that the ISO  standard defines back
quoted text,  but does not define  the back_quotes Prolog flag and  does
not define the term that is produced by back quoted text.

             _______________________________________________MMooddeedouble_quotesback_quotes
             _______________________________________________Versions7tdefaultringcodes

             _--traditional_________codes_______symbol_char_

  Table 5.1:  Mapping of double and back quoted text in the two modes.

Section  ???? motivates  the introduction  of strings  and mapping  double
quoted text to this type.


55..22..11 PPrreeddiiccaatteess tthhaatt ooppeerraattee oonn ssttrriinnggss

Strings may  be manipulated by  a set of predicates  that is similar  to
the manipulation  of atoms.   In  addition to the  list below,  string/1
performs the type check for this type and is described in section ????.

SWI-Prolog's   string    primitives   are   being   synchronized    with
http://eclipseclp.org/wiki/Prolog/StringsECLiPSe.       We  expect   the
set of  predicates documented  in this  section to  be stable,  although
it  might be  expanded.    In  general, SWI-Prolog's  text  manipulation
predicates accept  any form of  text as input  argument and produce  the
type indicated by the predicate name as output.   This policy simplifies
migration and  writing programs that  can run  unmodified or with  minor
modifications  on systems  that do  not support  strings.   Code  should
avoid relying on  this feature as much  as possible for clarity as  well
as  to facilitate  a more  strict mode  and/or type  checking in  future
releases.


aattoomm__ssttrriinngg((_?_A_t_o_m_, _?_S_t_r_i_n_g))
    Bi-directional  conversion between an atom and  a string.  At  least
    one of the two  arguments must be instantiated.  _A_t_o_m can also be an
    integer or floating point number.


nnuummbbeerr__ssttrriinngg((_?_N_u_m_b_e_r_, _?_S_t_r_i_n_g))
    Bi-directional  conversion between a number and a string.   At least
    one  of the two  arguments must be instantiated.   Besides the  type
    used  to represent the text, this predicate differs in  several ways
    from its ISO cousin:

      o  If _S_t_r_i_n_g  does not  represent a  number,  the predicate  _f_a_i_l_s
         rather than throwing a syntax error exception.

      o  Leading white space and Prolog comments are _n_o_t allowed.

      o  Numbers may start with '+' or '-'.

      o  It is _n_o_t allowed to have white space between a  leading '+' or
         '-' and the number.

      o  Floating point numbers  in exponential notation do not  require
         a dot before exponent, i.e., "1e10" is a valid number.


tteerrmm__ssttrriinngg((_?_T_e_r_m_, _?_S_t_r_i_n_g))
    Bi-directional  conversion between a term and  a string.  If  _S_t_r_i_n_g
    is  instantiated, it is parsed and the result is unified  with _T_e_r_m.
    Otherwise  _T_e_r_m is `written' using  the option quoted(_t_r_u_e) and  the
    result is converted to _S_t_r_i_n_g.


tteerrmm__ssttrriinngg((_?_T_e_r_m_, _?_S_t_r_i_n_g_, _+_O_p_t_i_o_n_s))
    As   term_string/2,  passing   _O_p_t_i_o_n_s  to  either   read_term/2  or
    write_term/2.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- term_string(Term, 'a(A)', [variable_names(VNames)]).            |

    | Term = a(_G1466),                                                  |
    ||VNames_=_['A'=_G1466].____________________________________________ ||


ssttrriinngg__cchhaarrss((_?_S_t_r_i_n_g_, _?_C_h_a_r_s))
    Bi-directional conversion between  a string and a list of characters
    (one-character  atoms).  At least  one of the two arguments must  be
    instantiated.


ssttrriinngg__ccooddeess((_?_S_t_r_i_n_g_, _?_C_o_d_e_s))
    Bi-directional  conversion between a string and a list  of character
    codes.  At least one of the two arguments must be instantiated.


tteexxtt__ttoo__ssttrriinngg((_+_T_e_x_t_, _-_S_t_r_i_n_g))                                     _[_d_e_t_]
    Converts  _T_e_x_t to  a string.   _T_e_x_t is  an atom,  string or list  of
    characters  (codes or chars).   When running in --traditional  mode,
    '[]' is ambiguous and interpreted as an empty string.


ssttrriinngg__lleennggtthh((_+_S_t_r_i_n_g_, _-_L_e_n_g_t_h))
    Unify  _L_e_n_g_t_h  with  the number  of  characters  in _S_t_r_i_n_g.     This
    predicate  is  functionally  equivalent  to atom_length/2  and  also
    accepts atoms, integers and floats as its first argument.


ssttrriinngg__ccooddee((_?_I_n_d_e_x_, _+_S_t_r_i_n_g_, _?_C_o_d_e))
    True  when  _C_o_d_e  represents  the character  at  the  1-based  _I_n_d_e_x
    position in _S_t_r_i_n_g.   If _I_n_d_e_x is unbound the string is scanned from
    index  1.    Raises a  domain error  if _I_n_d_e_x  is negative.    Fails
    silently  if _I_n_d_e_x  is zero or  greater than  the length of  _S_t_r_i_n_g.
    The  mode string_code(_-_,_+_,_+)  is deterministic  if the  searched-for
    _C_o_d_e appears only once in _S_t_r_i_n_g.  See also sub_string/5.


ggeett__ssttrriinngg__ccooddee((_+_I_n_d_e_x_, _+_S_t_r_i_n_g_, _-_C_o_d_e))
    Semi-deterministic  version  of string_code/3.   In  addition,  this
    version  provides strict range checking, throwing a domain  error if
    _I_n_d_e_x is less than  1 or greater than the length of _S_t_r_i_n_g.  ECLiPSe
    provides this to support String[Index] notation.


ssttrriinngg__ccoonnccaatt((_?_S_t_r_i_n_g_1_, _?_S_t_r_i_n_g_2_, _?_S_t_r_i_n_g_3))
    Similar  to atom_concat/3,  but the unbound argument will  be unified
    with  a string object rather  than an atom.   Also, if both  _S_t_r_i_n_g_1
    and  _S_t_r_i_n_g_2 are  unbound and _S_t_r_i_n_g_3  is bound to  text, it  breaks
    _S_t_r_i_n_g_3,  unifying the start with  _S_t_r_i_n_g_1 and the end with  _S_t_r_i_n_g_2
    as  append does  with lists.   Note  that this  is not  particularly
    fast  on long strings,  as for  each redo the  system has to  create
    two  entirely new strings, while the list equivalent only  creates a
    single new list-cell and moves some pointers around.


sspplliitt__ssttrriinngg((_+_S_t_r_i_n_g_, _+_S_e_p_C_h_a_r_s_, _+_P_a_d_C_h_a_r_s_, _-_S_u_b_S_t_r_i_n_g_s))           _[_d_e_t_]
    Break  _S_t_r_i_n_g into _S_u_b_S_t_r_i_n_g_s.   The _S_e_p_C_h_a_r_s argument provides  the
    characters that act  as separators and thus the length of _S_u_b_S_t_r_i_n_g_s
    is  one more  than the number  of separators  found if _S_e_p_C_h_a_r_s  and
    _P_a_d_C_h_a_r_s  do not have common characters.   If _S_e_p_C_h_a_r_s and  _P_a_d_C_h_a_r_s
    are  equal,  sequences  of  adjacent  separators  act  as  a  single
    separator.    Leading  and trailing  characters  for each  substring
    that  appear  in _P_a_d_C_h_a_r_s  are  removed from  the  substring.    The
    input  arguments can be  either atoms,  strings or char/code  lists.
    Compatible with ECLiPSe.  Below are some examples:

    ____________________________________________________________________|                                                                    |
    | % a simple split                                                   |

    | ?- split_string("a.b.c.d", ".", "", L).                            |
    | L = ["a", "b", "c", "d"].                                          |
    | % Consider sequences of separators as a single one                 |
    | ?- split_string("/home//jan///nice/path", "/", "/", L).            |
    | L = ["home", "jan", "nice", "path"].                               |
    | % split and remove white space                                     |
    | ?- split_string("SWI-Prolog, 7.0", ",", " ", L).                   |
    | L = ["SWI-Prolog", "7.0"].                                         |

    | % only remove leading and trailing white space                     |
    | ?- split_string("  SWI-Prolog  ", "", "\s\t\n", L).                |
    ||L_=_["SWI-Prolog"]._______________________________________________ ||

    In the typical  use cases, _S_e_p_C_h_a_r_s either does not overlap _P_a_d_C_h_a_r_s
    or is equivalent  to handle multiple adjacent separators as a single
    (often white space).   The behaviour with partially overlapping sets
    of padding and  separators should be considered undefined.  See also
    read_string/5.


ssuubb__ssttrriinngg((_+_S_t_r_i_n_g_, _?_B_e_f_o_r_e_, _?_L_e_n_g_t_h_, _?_A_f_t_e_r_, _?_S_u_b_S_t_r_i_n_g))
    _S_u_b_S_t_r_i_n_g is a substring  of _S_t_r_i_n_g.  There are _B_e_f_o_r_e characters in
    _S_t_r_i_n_g before _S_u_b_S_t_r_i_n_g,  _S_u_b_S_t_r_i_n_g contains _L_e_n_g_t_h character and is
    followed  by _A_f_t_e_r characters in _S_t_r_i_n_g.  If not  enough information
    is  provided to compute  the start of the  match, _S_t_r_i_n_g is  scanned
    left-to-right.     This  predicate  is  functionally  equivalent  to
    sub_atom/5, but operates  on strings.  The following  example splits
    a string  of the form <_n_a_m_e>=<_v_a_l_u_e> into the name part (an atom) and
    the value (a string).

    ____________________________________________________________________|                                                                    |
    | name_value(String, Name, Value) :-                                 |

    |         sub_string(String, Before, _, After, "="), !,              |
    |         sub_string(String, 0, Before, _, NameString),              |
    |         atom_string(Name, NameString),                             |
    ||________sub_string(String,__,_After,_0,_Value).___________________ ||


aattoommiiccss__ttoo__ssttrriinngg((_+_L_i_s_t_, _-_S_t_r_i_n_g))
    _L_i_s_t  is  a  list of  strings,  atoms,  integers or  floating  point
    numbers.   Succeeds if _S_t_r_i_n_g  can be unified with the  concatenated
    elements  of  _L_i_s_t.     Equivalent  to  atomics_to_string(_L_i_s_t_,  _'_'_,
    _S_t_r_i_n_g).


aattoommiiccss__ttoo__ssttrriinngg((_+_L_i_s_t_, _+_S_e_p_a_r_a_t_o_r_, _-_S_t_r_i_n_g))
    Creates  a string just like atomics_to_string/2, but  inserts _S_e_p_a_r_a_-
    _t_o_r between each pair of inputs.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- atomics_to_string([gnu, "gnat", 1], ', ', A).                   |

    |                                                                    |
    ||A_=_"gnu,_gnat,_1"________________________________________________ ||


ssttrriinngg__uuppppeerr((_+_S_t_r_i_n_g_, _-_U_p_p_e_r_C_a_s_e))
    Convert _S_t_r_i_n_g to upper case and unify the result with _U_p_p_e_r_C_a_s_e.


ssttrriinngg__lloowweerr((_+_S_t_r_i_n_g_, _L_o_w_e_r_C_a_s_e))
    Convert _S_t_r_i_n_g to lower case and unify the result with _L_o_w_e_r_C_a_s_e.


rreeaadd__ssttrriinngg((_+_S_t_r_e_a_m_, _?_L_e_n_g_t_h_, _-_S_t_r_i_n_g))
    Read  at most _L_e_n_g_t_h characters from  _S_t_r_e_a_m and return them in  the
    string _S_t_r_i_n_g.   If _L_e_n_g_t_h is unbound, _S_t_r_e_a_m is read to the end and
    _L_e_n_g_t_h is unified with the number of characters read.


rreeaadd__ssttrriinngg((_+_S_t_r_e_a_m_, _+_S_e_p_C_h_a_r_s_, _+_P_a_d_C_h_a_r_s_, _-_S_e_p_, _-_S_t_r_i_n_g))
    Read  a  string  from _S_t_r_e_a_m,  providing  functionality  similar  to
    split_string/4.  The predicate performs the following steps:

     1.  Skip all characters that match _P_a_d_C_h_a_r_s

     2.  Read up to a character that matches _S_e_p_C_h_a_r_s or end of file

     3.  Discard  trailing  characters  that  match  _P_a_d_C_h_a_r_s  from  the
         collected input

     4.  Unify _S_t_r_i_n_g with a string created from the input  and _S_e_p with
         the separator character read.   If input was terminated  by the
         end of the input, _S_e_p is unified with -1.

    The predicate  read_string/5called repeatedly on  an input until _S_e_p
    is  -1 (end of file) is  equivalent to reading the entire file  into
    a  string  and calling  split_string/4,  provided  that _S_e_p_C_h_a_r_s  and
    _P_a_d_C_h_a_r_s are not _p_a_r_t_i_a_l_l_y _o_v_e_r_l_a_p_p_i_n_g.  Below are some examples:

    ____________________________________________________________________|                                                                    |

    | % Read a line                                                      |
    | read_string(Input, "\n", "\r", End, String)                        |
    | % Read a line, stripping leading and trailing white space          |
    | read_string(Input, "\n", "\r\t ", End, String)                     |
    | % Read upto , or ), unifying End with 0', or 0')                   |

    ||read_string(Input,_",)",_"\t_",_End,_String)______________________ ||


ooppeenn__ssttrriinngg((_+_S_t_r_i_n_g_, _-_S_t_r_e_a_m))
    True  when _S_t_r_e_a_m is  an input stream  that accesses the content  of
    _S_t_r_i_n_g.  _S_t_r_i_n_g  can be any text representation, i.e., string, atom,
    list of codes or list of characters.


55..22..22 RReepprreesseennttiinngg tteexxtt::  ssttrriinnggss,, aattoommss aanndd ccooddee lliissttss

With  the introduction  of strings  as  a Prolog  data type,  there  are
three  main ways  to  represent text:    using strings,  atoms  or  code
lists.   This section explains  what to choose for  what purpose.   Both
strings and  atoms are _a_t_o_m_i_c  objects:  you can  only look inside  them
using  dedicated predicates.    Lists of  character  codes are  compound
datastructures.

LLiissttss ooff cchhaarraacctteerr ccooddeess  is what  you need if  you want  to _p_a_r_s_e  text
    using  Prolog grammar rules (DCGs, see phrase/3).  Most of  the text
    reading  predicates  (e.g., read_line_to_codes/2)  return  a list  of
    character codes because  most applications need to parse these lines
    before the data can be processed.

AAttoommss  are  _i_d_e_n_t_i_f_i_e_r_s.    They  are  typically  used  in  cases  where
    identity  comparison is  the main operation  and that are  typically
    not  composed nor  taken apart.   Examples  are RDF resources  (URIs
    that  identify something), system identifiers (e.g.,  'Boeing 747'),
    but  also individual words in a natural language  processing system.
    They  are  also  used where  other  languages would  use  _e_n_u_m_e_r_a_t_e_d
    _t_y_p_e_s,  such as the names  of days in the  week.  Unlike  enumerated
    types,  Prolog atoms do not form not  a fixed set and the  same atom
    can represent different things in different contexts.

SSttrriinnggss  typically represents text that is  processed as a unit most  of
    the  time, but  which is not  an identifier for  something.   Format
    specifications  for format/3  is a  good example.   Another  example
    is  a  descriptive  text  provided  in  an  application.     Strings
    may  be  composed and  decomposed  using e.g.,  string_concat/3  and
    sub_string/5  or  converted  for  parsing  using  string_codes/2  or
    created  from codes  generated by  a generative  grammar rule,  also
    using string_codes/2.


55..22..33 AAddaappttiinngg ccooddee ffoorr ddoouubbllee qquuootteedd ssttrriinnggss

The predicates  in this section  can help adapting  your program to  the
new convention for  handling double quoted strings.   We have adapted  a
huge code base with which we were not familiar in about half a day.


lliisstt__ssttrriinnggss
    This  predicate  may  be used  to  assess compatibility  issues  due
    to  the  representation of  double quoted  text  as string  objects.
    See  section  ???? and  section ????.    To use  it,  load your  program
    into  Prolog and  run list_strings/0.   The  predicate lists  source
    locations of string  objects encountered in the program that are not
    considered  safe.  Such string  need to be examined manually,  after
    which one of the actions below may be appropriate:

      o  Rewrite the code.  For example, change [X] = "a" into X = 0'a.

      o  If a particular  module relies heavily on representing  strings
         as  lists of  character  code,  consider adding  the  following
         directive to the module.   Note that this flag only  applies to
         the module in which it appears.

         _______________________________________________________________|                                                               |

         ||_________:-_set_prolog_flag(double_quotes,_codes).___________ ||

      o  Use a  back  quoted string  (e.g.,  `text`).   Note  that  this
         will not  make your  code run regardless  of the  --traditional
         command line option  and code exploiting  this mapping is  also
         not portable to ISO compliant systems.

      o  If the strings appear in facts and usage is safe,  add a clause
         to the multifile  predicate check:string_predicate/1 to  silence
         list_strings/0 on all clauses of that predicate.

      o  If the strings  appear as an argument  to a predicate that  can
         handle string objects, add a clause to  the multifile predicate
         check:valid_string_goal/1 to silence list_strings/0.


cchheecckk::ssttrriinngg__pprreeddiiccaattee((_:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r))
    Declare  that _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r has  clauses that contain  strings,
    but  that  this is  safe.   For  example, if  there  is a  predicate
    help_info/2,  where the  second argument  contains  a double  quoted
    string   that  is  handled  properly   by  the  predicates  of   the
    applications'  help system,  add the  following declaration to  stop
    list_strings/0 from complaining:

    ____________________________________________________________________|                                                                    |
    | :- multifile check:string_predicate/1.                             |

    |                                                                    |
    ||check:string_predicate(user:help_info/2)._________________________ ||


cchheecckk::vvaalliidd__ssttrriinngg__ggooaall((_:_G_o_a_l))
    Declare  that calls to _G_o_a_l are  safe.  The module qualification  is
    the  actual module in which  _G_o_a_l is defined.   For example, a  call
    to  format/3 is  resolved  by the  predicate system:format/3.    and
    the  code below specifies that the  second argument may be a  string
    (system predicates that accept strings are defined in the library).

    ____________________________________________________________________|                                                                    |
    | :- multifile check:valid_string_goal/1.                            |

    |                                                                    |
    ||check:valid_string_goal(system:format(_,S,_))_:-_string(S)._______ ||


55..22..44 WWhhyy hhaass tthhee rreepprreesseennttaattiioonn ooff ddoouubbllee qquuootteedd tteexxtt cchhaannggeedd??

Prolog defines two forms  of quoted text.  Traditionally,  single quoted
text is  mapped to atoms while  double quoted text  is mapped to a  list
of _c_h_a_r_a_c_t_e_r _c_o_d_e_s  (integers) or characters represented as  1-character
atoms.   Representing text  using atoms  is often considered  inadequate
for several reasons:

  o It  hides  the   conceptual  difference  between  text  and  program
    symbols.   Where  content of text often  matters because it is  used
    in  I/O, program symbols are merely identifiers that match  with the
    same  symbol elsewhere.   Program symbols can often be  consistently
    replaced, for example to obfuscate or compact a program.

  o Atoms are globally unique  identifiers.  They are stored in a shared
    table.   Volatile strings represented as atoms come at a significant
    price  due to the required cooperation between threads  for creating
    atoms.   Reclaiming temporary atoms using _A_t_o_m _g_a_r_b_a_g_e _c_o_l_l_e_c_t_i_o_n is
    a costly process that requires significant synchronisation.

  o Many Prolog systems  (not SWI-Prolog) put severe restrictions on the
    length of atoms or the maximum number of atoms.

Representing text  as a  list of  character codes  or 1-character  atoms
also comes at a price:

  o It  is not possible to distinguish  (at runtime) a list of  integers
    or  atoms from a string.  Sometimes this information can  be derived
    from  (implicit) typing.  In  other cases the list must be  embedded
    in  a compound  term to  distinguish the two  types.   For  example,
    s("hello world") could be  used to indicate that we are dealing with
    a string.

    Lacking  runtime information,  debuggers and  the toplevel can  only
    use  heuristics to  decide whether to  print a  list of integers  as
    such or as a string (see portray_text/1).

    While  experienced  Prolog programmers  have  learned to  cope  with
    this, we still consider this an unfortunate situation.

  o Lists are expensive  structures, taking 2 cells per character (3 for
    SWI-Prolog  in its current form).  This stresses  memory consumption
    on the stacks while  pushing them on the stack and dealing with them
    during garbage collection is unnecessarilly expensive.

We observe  that in many  programs, most strings are  only handled as  a
single unit during  their lifetime.   Examining real code tells us  that
double quoted strings typically appear in one of the following roles:

 AA DDCCGG lliitteerraall   Although represented as a list of codes is  the correct
    representation  for  handling  in  DCGs,   the  DCG  translator  can
    recognise  the literal and convert it to the  proper representation.
    Such code need not be modified.

 AA ffoorrmmaatt ssttrriinngg   This  is   a  typical   example  of   text  that   is
    conceptually  not a program identifier.  Format is designed  to deal
    with  alternative representations of the  format string.  Such  code
    need not be modified.

 GGeettttiinngg aa cchhaarraacctteerr ccooddee   The construct [X] = "a"  is a commonly  used
    template  for getting the  character code  of the letter  'a'.   ISO
    Prolog  defines the syntax  0'a for this purpose.   Code using  this
    must  be modified.  The modified code will run on any  ISO compliant
    processor.

 AAss aarrgguummeenntt ttoo lliisstt pprreeddiiccaatteess ttoo ooppeerraattee oonn ssttrriinnggss   Here,   we   see
    code  such as append("name:", Rest, Codes).   Such code needs to  be
    modified.    In this  particular example,  the following  is a  good
    portable alternative:  phrase("name:", Codes, Rest)

 CChheecckkss ffoorr aa cchhaarraacctteerr ttoo bbee iinn aa sseett   Such tests are often  performed
    with  code  such  as  this:   memberchk(C, "~!@#$").     This  is  a
    rather  inefficient check in a traditional Prolog system  because it
    pushes  a list of character codes cell-by-cell the Prolog  stack and
    then  traverses this  list cell-by-cell  to see whether  one of  the
    cells  unifies with _C.  If the test is  successful, the string  will
    eventually  be subject  to garbage collection.    The best code  for
    this  is to write a predicate  as below, which pushes noting  on the
    stack  and performs an indexed  lookup to see whether the  character
    code is in `my_class'.

    ____________________________________________________________________|                                                                    |

    | my_class(0'~).                                                     |
    | my_class(0'!).                                                     |
    ||..._______________________________________________________________ ||

    An alternative to reach  the same effect is to use term expansion to
    create the clauses:

    ____________________________________________________________________|                                                                    |
    | term_expansion(my_class(_), Clauses) :-                            |
    |         findall(my_class(C),                                       |
    |                 string_code(_, "~!@#$", C),                        |
    |                 Clauses).                                          |

    |                                                                    |
    ||my_class(_).______________________________________________________ ||

    Finally,  the predicate string_code/3can be  exploited directly as a
    replacement  for the memberchk/2 on a  list of codes.  Although  the
    string  is still pushed onto the stack, it is more compact  and only
    a single entity.

We offer the predicate list_strings/0 to help porting your program.


55..33 SSyynnttaaxx cchhaannggeess


55..33..11 OOppeerraattoorrss aanndd qquuootteedd aattoommss

As of SWI-Prolog version 7, quoted atoms loose  their operator property.
This means  that expressions such as  A = 'dynamic'/1 are valid  syntax,
regardless  of  the  operator  definitions.     From  questions  on  the
mailinglist  this  is what  people  expect.    To  accomodate  for  real
quoted operators, a  quoted atom that _n_e_e_d_s  quotes can still act as  an
operator.  A good use-case for this is a unit  library, which allows for
expressions such as below.

________________________________________________________________________|                                                                        |
|?- Y isu 600kcal - 1h*200'W'.                                           |

|Y|=_1790400.0'J'.______________________________________________________ | |


55..33..22 CCoommppoouunndd tteerrmmss wwiitthh zzeerroo aarrgguummeennttss

As of  SWI-Prolog version  7, the  system supports  compound terms  that
have no  arguments.   This implies  that e.g.,  name() is valid  syntax.
This  extension aims  at functions  on dicts  (see section  ????) as  well
as  the  implementation  of  domain  specific  languages  (DSLs).     To
minimise the  consequences, the classic  predicates functor/3 and  =../2
have  not  been modified.     The  predicates compound_name_arity/3  and
compound_name_arguments/3 have  been added.    These predicates  operate
only on compound  terms and behave consistently for compounds  with zero
arguments.    Code that  _g_e_n_e_r_a_l_i_s_e_s  a term  using the  sequence  below
should generally be changed to use compound_name_arity/3.

________________________________________________________________________|                                                                        |
|    ...,                                                                |

|    functor(Specific, Name, Arity),                                     |
|    functor(General, Name, Arity),                                      |
||___...,_______________________________________________________________ ||

Replacement of =../2 by compound_name_arguments/3 is typically needed to
deal with code that follow the skeleton below.

________________________________________________________________________|                                                                        |
|    ...,                                                                |
|    Term0 =.. [Name|Args0],                                             |
|    maplist(convert, Args0, Args),                                      |
|    Term =.. [Name|Args],                                               |
||___...,_______________________________________________________________ ||

For predicates, goals and arithmetic functions (evaluable terms), <_n_a_m_e>
and <_n_a_m_e>()  are _e_q_u_i_v_a_l_e_n_t.   Below are some  examples that illustrate
this behaviour.

________________________________________________________________________|                                                                        |

|go() :- format('Hello world~n').                                        |
|                                                                        |
|?- go().                                                                |
|Hello world                                                             |
|                                                                        |
|?- go.                                                                  |
|Hello world                                                             |

|                                                                        |
|?- Pi is pi().                                                          |
|Pi = 3.141592653589793.                                                 |
|                                                                        |
|?- Pi is pi.                                                            |
|Pi|=_3.141592653589793.________________________________________________ |  |

Note  that  the   _c_a_n_n_o_n_i_c_a_l  representation  of  predicate  heads   and
functions  without arguments  is  an atom.    Thus,  clause(_g_o_(_)_,  _B_o_d_y)
returns the  clauses for  go/0, but clause(_-_H_e_a_d_,  _-_B_o_d_y_, _+_R_e_f)  unifies
_H_e_a_d with an atom if the clause specified by _R_e_f is  part of a predicate
with zero arguments.


55..33..33 BBlloocckk ooppeerraattoorrss

Introducing curly bracket  and array subscripting.   The symbols []  and
{} may be declared as an operator, which has the following effect:

[[ ]]
    This  operator is  typically declared as  a low-priority yf  postfix
    operator,  which  allows for  array[index] notation.    This  syntax
    produces a term []([index],array).

{ }
    This  operator is  typically declared as  a low-priority xf  postfix
    operator,  which  allows  for  head(arg) { body } notation.     This
    syntax produces a term {}({body},head(arg)).

Below is  an example that  illustrates the  representation of a  typical
`curly bracket language' in Prolog.

________________________________________________________________________|                                                                        |

|?- op(100, xf, {}).                                                     |
|?- op(100, yf, []).                                                     |
|?- op(1100, yf, ;).                                                     |
|                                                                        |
|?- displayq(func(arg)                                                   |

|            { a[10] = 5;                                                |
|              update();                                                 |
|            }).                                                         |
|{}({;(=([]([10],a),5),;(update()))},func(arg))|________________________ |                                              |


55..44 DDiiccttss::  ssttrruuccttuurreess wwiitthh nnaammeedd aarrgguummeennttss

SWI-Prolog  version 7  introduces dicts  as an  abstract  object with  a
concrete modern  syntax and  functional notation  for accessing  members
and as  well as access functions  defined by the user.   The syntax  for
a dict  is illustrated  below.   _T_a_g is  either a variable  or an  atom.
As  with compound  terms, there  is nnoo  space  between the  tag and  the
opening brace.    The keys  are either atoms  or small  integers (up  to
max_tagged_integer).   The  values are arbitrary  Prolog terms which  are
parsed using the same rules as used for arguments in compound terms.

    Tag{Key1:Value1, Key2:Value2, ...}

A  dict can  _n_o_t hold  duplicate keys.    The dict  is transformed  into
an opaque  internal representation that  does _n_o_t  respect the order  in
which the  key-value pairs  appear in  the input  text.   If  a dict  is
written, the keys are  written according to the standard order  of terms
(see section  ????).   Here are  some examples,  where the second  example
illustrates that the  order is not maintained and the  third illustrates
an anonymous dict.

________________________________________________________________________|                                                                        |

|?- A = point{x:1, y:2}.                                                 |
|A = point{x:1, y:2}.                                                    |
|                                                                        |
|?- A = point{y:2, x:1}.                                                 |
|A = point{x:1, y:2}.                                                    |

|                                                                        |
|?- A = _{first_name:"Mel", last_name:"Smith"}.                          |
|A|=__G1476{first_name:"Mel",_last_name:"Smith"}._______________________ | |

Dicts  can   be  unified   following  the   standard  symmetric   Prolog
unification  rules.    As dicts  use  an internal  canonical  form,  the
order in  which the named keys  are represented is  not relevant.   This
behaviour is illustrated by the following example.

________________________________________________________________________|                                                                        |
|?- point{x:1, y:2} = Tag{y:2, x:X}.                                     |
|Tag = point,                                                            |
|X|=_1._________________________________________________________________ | |

NNoottee In the  current implementation, two dicts  unify only if they  have
the same set  of keys and the tags  and values associated with the  keys
unify.   In  future versions,  the notion of  unification between  dicts
could  be modified  such that  two dicts  unify if  their  tags and  the
values associated with _c_o_m_m_o_n keys unify, turning both  dicts into a new
dict that has the union of the keys of the two original dicts.


55..44..11 FFuunnccttiioonnss oonn ddiiccttss

The infix operator dot (op(_1_0_0_,  _y_f_x_, _.)  is used to extract  values and
evaluate functions on  dicts.  Functions  are recognised if they  appear
in the  argument of  a _g_o_a_l  in the source  text, possibly  nested in  a
term.   The keys  act as field  selector, which  is illustrated in  this
example.

________________________________________________________________________|                                                                        |
|?- X = point{x:1,y:2}.x.                                                |

|X = 1.                                                                  |
|                                                                        |
|?- Pt = point{x:1,y:2}, write(Pt.y).                                    |
|2                                                                       |
|Pt = point{x:1,y:2}.                                                    |
|                                                                        |
|?- X = point{x:1,y:2}.C.                                                |
|X = 1,                                                                  |

|C = x ;                                                                 |
|X = 2,                                                                  |
|C|=_y._________________________________________________________________ | |

The compiler translates a goal that contains ./2 terms  in its arguments
into a conjunction of calls to ./3 defined in the system  module.  Terms
functor.2 that  appears in  the head  are replaced with  a variable  and
calls to  ./3 are  inserted at the  start of the  body.   Below are  two
examples, where the first extracts the x key from a  dict and the second
extends  a dict  containing an  address with  the postal  code, given  a
find_postal_code/4predicate.

________________________________________________________________________|                                                                        |
|dict_x(X, X.x).                                                         |
|                                                                        |
|add_postal_code(Dict, Dict.put(postal_code, Code)) :-                   |

|        find_postal_code(Dict.city,                                     |
|                         Dict.street,                                   |
|                         Dict.house_number,                             |
||________________________Code).________________________________________ ||

Note  that expansion  of ./2  terms implies  that such  terms cannot  be
created by  writing them  explicitly in your  source code.   Such  terms
can still  be created  with functor/3, =../2,  compound_name_arity/3 and
compound_name_arguments/3.


.((_+_D_i_c_t_, _+_F_u_n_c_t_i_o_n_, _-_R_e_s_u_l_t))
    This  predicate  is  called  to  evaluate ./2  terms  found  in  the
    arguments of a  goal.  This predicate evaluates the field extraction
    described  above, which is mapped to get_dict_ex/3.  If  _F_u_n_c_t_i_o_n is
    a  compound term, it  checks for the  predefined functions on  dicts
    described  in section  ????  or executes  a user  defined function  as
    described in section ????.


55..44..11..11 UUsseerr ddeeffiinneedd ffuunnccttiioonnss oonn ddiiccttss

The tag of a dict associates the dict to a module.   If the dot notation
uses a compound term, this calls the goal below.

    <_m_o_d_u_l_e>:<_n_a_m_e>(Arg1, ..., +Dict, -Value)

Functions  are  normal  Prolog predicates.     The  dict  infrastructure
provides a  more convenient  syntax for  representing the  head of  such
predicates  without worrying  about  the argument  calling  conventions.
The  code below  defines  a function  multiply(_T_i_m_e_s)  on a  point  that
creates  a new  point  by multiplying  both coordinates.    and  len  to
compute the length  from the origin.  The  .  and := operators  are used
to abstract the location  of the predicate arguments.  It is  allowed to
define multiple a function with multiple clauses,  providing overloading
and non-determinism.

________________________________________________________________________|                                                                        |

|:- module(point, []).                                                   |
|                                                                        |
|M.multiply(F) := point{x:X, y:Y} :-                                     |
|        X is M.x*F,                                                     |
|        Y is M.y*F.                                                     |
|                                                                        |
|M.len() := Len :-                                                       |

||_______Len_is_sqrt(M.x**2_+_M.y**2).__________________________________ ||

After these definitions, we can evaluate the following functions:

________________________________________________________________________|                                                                        |
|?- X = point{x:1, y:2}.multiply(2).                                     |
|X = point{x:2, y:4}.                                                    |
|                                                                        |
|?- X = point{x:1, y:2}.multiply(2).len().                               |

|X|=_4.47213595499958.__________________________________________________ | |


55..44..11..22 PPrreeddeeffiinneedd ffuunnccttiioonnss oonn ddiiccttss

Dicts currently define the following reserved functions:


ggeett((_?_K_e_y))
    Same  as _D_i_c_t._K_e_y, but maps  to get_dict/3 instead of get_dict_ex/3.
    This  implies that  the function  evaluation fails  silently if  _K_e_y
    does  not appear in _D_i_c_t.  See also :</2, which can be  used to test
    for  existence and  unify  multiple key  values from  a dict.    For
    example:

    ____________________________________________________________________|                                                                    |
    | ?- write(t{a:x}.get(a)).                                           |

    | x                                                                  |
    | ?- write(t{a:x}.get(b)).                                           |
    ||false.____________________________________________________________ ||


ppuutt((_+_N_e_w))
    Evaluates  to a  new dict  where the  key-values in  _N_e_w replace  or
    extend the key-values in the original dict.  See put_dict/3.


ppuutt((_+_K_e_y_P_a_t_h_, _+_V_a_l_u_e))
    Evaluates to a  new dict where the _K_e_y_P_a_t_h-_V_a_l_u_e replaces or extends
    the  key-values in  the  original dict.    _K_e_y_P_a_t_h is  either a  key
    or  a  term _K_e_y_P_a_t_h/_K_e_y,  replacing the  value  associated with  _K_e_y
    in  a sub-dict  of the dict  on which  the function operates.    See
    put_dict/4.  Below are some examples:

    ____________________________________________________________________|                                                                    |
    | ?- A = _{}.put(a, 1).                                              |

    | A = _G7359{a:1}.                                                   |
    |                                                                    |
    | ?- A = _{a:1}.put(a, 2).                                           |
    | A = _G7377{a:2}.                                                   |
    |                                                                    |
    | ?- A = _{a:1}.put(b/c, 2).                                         |
    | A = _G1395{a:1, b:_G1584{c:2}}.                                    |
    |                                                                    |

    | ?- A = _{a:_{b:1}}.put(a/b, 2).                                    |
    | A = _G1429{a:_G1425{b:2}}.                                         |
    |                                                                    |
    | ?- A = _{a:1}.put(a/b, 2).                                         |
    ||A_=__G1395{a:_G1578{b:2}}.________________________________________ ||


55..44..22 PPrreeddiiccaatteess ffoorr mmaannaaggiinngg ddiiccttss

This section  documents the predicates  that are defined on  dicts.   We
use the naming and argument conventions of the traditional assoc.


iiss__ddiicctt((_@_T_e_r_m))
    True if _T_e_r_m is a dict.  This is the same as is_dict(Term,_).


iiss__ddiicctt((_@_T_e_r_m_, _-_T_a_g))
    True if _T_e_r_m is a dict of _T_a_g.


ggeett__ddiicctt((_?_K_e_y_, _+_D_i_c_t_, _-_V_a_l_u_e))
    Unify  the value associated  with _K_e_y in  dict with _V_a_l_u_e.   If  _K_e_y
    is  unbound, all associations in _D_i_c_t are returned  on backtracking.
    The  order  in which  the associations  are  returned is  undefined.
    This  predicate is normally  accessed using the functional  notation
    Dict.Key.  See section ????.

    Fails  silently if Key does not appear  in Dict.  This  is different
    from  the behavior of the  functional `.`-notation, which throws  an
    existence error in that case.


ggeett__ddiicctt((_+_K_e_y_, _+_D_i_c_t_, _-_V_a_l_u_e_, _-_N_e_w_D_i_c_t_, _+_N_e_w_V_a_l_u_e))             _[_s_e_m_i_d_e_t_]
    Create a new dict  after updating the value for _K_e_y.  Fails if _V_a_l_u_e
    does not unify with  the current value associated with _K_e_y.  _D_i_c_t is
    either a dict or a list the can be converted into a dict.

    Has the behavior as if defined in the following way:

    ____________________________________________________________________|                                                                    |
    | get_dict(Key, Dict, Value, NewDict, NewValue) :-                   |

    |         get_dict(Key, Dict, Value),                                |
    ||________put_dict(Key,_Dict,_NewValue,_NewDict).___________________ ||


ddiicctt__ccrreeaattee((_-_D_i_c_t_, _+_T_a_g_, _+_D_a_t_a))
    Create  a dict in _T_a_g from _D_a_t_a.  _D_a_t_a is a  list of attribute-value
    pairs   using  the   syntax  Key:Value,   Key=Value,  Key-Value   or
    Key(Value).   An exception is raised  if _D_a_t_a is not a  proper list,
    one  of the elements is not of the shape above, a key  is neither an
    atom nor a small integer or there is a duplicate key.


ddiicctt__ppaaiirrss((_?_D_i_c_t_, _?_T_a_g_, _?_P_a_i_r_s))
    Bi-directional  mapping between a dict and an ordered list  of pairs
    (see section ????).


ppuutt__ddiicctt((_+_N_e_w_, _+_D_i_c_t_I_n_, _-_D_i_c_t_O_u_t))
    _D_i_c_t_O_u_t  is a  new  dict created  by replacing  or adding  key-value
    pairs  from _N_e_w to  _D_i_c_t.   _N_e_w is  either a dict  or a valid  input
    for  dict_create/3.   This predicate  is normally accessed using  the
    functional notation.  Below are some examples:

    ____________________________________________________________________|                                                                    |
    | ?- A = point{x:1, y:2}.put(_{x:3}).                                |

    | A = point{x:3, y:2}.                                               |
    |                                                                    |
    | ?- A = point{x:1, y:2}.put([x=3]).                                 |
    | A = point{x:3, y:2}.                                               |
    |                                                                    |
    | ?- A = point{x:1, y:2}.put([x=3,z=0]).                             |
    ||A_=_point{x:3,_y:2,_z:0}._________________________________________ ||


ppuutt__ddiicctt((_+_K_e_y_, _+_D_i_c_t_I_n_, _+_V_a_l_u_e_, _-_D_i_c_t_O_u_t))
    _D_i_c_t_O_u_t  is a new dict created  by replacing or adding _K_e_y-_V_a_l_u_e  to
    _D_i_c_t_I_n.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- A = point{x:1, y:2}.put(x, 3).                                  |

    ||A_=_point{x:3,_y:2}.______________________________________________ ||

    This  predicate  can  also  be  accessed  by  using  the  functional
    notation,  in which  case Key can  also be a  *path* of  keys.   For
    example:

    ____________________________________________________________________|                                                                    |
    | ?- Dict = _{}.put(a/b, c).                                         |
    ||Dict_=__6096{a:_6200{b:c}}._______________________________________ ||


ddeell__ddiicctt((_+_K_e_y_, _+_D_i_c_t_I_n_, _?_V_a_l_u_e_, _-_D_i_c_t_O_u_t))
    True   when  _K_e_y-_V_a_l_u_e  is  in  _D_i_c_t_I_n  and  _D_i_c_t_O_u_t   contains  all
    associations of _D_i_c_t_I_n except for _K_e_y.


_+_S_e_l_e_c_t :< _+_F_r_o_m                                              _[_s_e_m_i_d_e_t_]
    True  when _S_e_l_e_c_t is  a `sub dict'  of _F_r_o_m:   the tages must  unify
    and  all keys in  _S_e_l_e_c_t must appear  with unifying values in  _F_r_o_m.
    _F_r_o_m  may contain  keys  that are  not in  _S_e_l_e_c_t.   This  operation
    is  frequently used to  _m_a_t_c_h a  dict and at  the same time  extract
    relevant values from it.  For example:

    ____________________________________________________________________|                                                                    |
    | plot(Dict, On) :-                                                  |

    |         _{x:X, y:Y, z:Z} :< Dict, !,                               |
    |         plot_xyz(X, Y, Z, On).                                     |
    | plot(Dict, On) :-                                                  |
    |         _{x:X, y:Y} :< Dict, !,                                    |
    ||________plot_xy(X,_Y,_On).________________________________________ ||

    The  goal Select :< From is equivalent to  select_dict(_S_e_l_e_c_t_,  _F_r_o_m_,
    __).


sseelleecctt__ddiicctt((_+_S_e_l_e_c_t_, _+_F_r_o_m_, _-_R_e_s_t))                             _[_s_e_m_i_d_e_t_]
    True  when the tags of _S_e_l_e_c_t  and _F_r_o_m have been unified,  all keys
    in  _S_e_l_e_c_t appear  in _F_r_o_m  and the corresponding  values have  been
    unified.   The key-value pairs of _F_r_o_m that do not appear  in _S_e_l_e_c_t
    are  used to  form an anonymous  dict, which  us unified with  _R_e_s_t.
    For example:

    ____________________________________________________________________|                                                                    |
    | ?- select_dict(P{x:0, y:Y}, point{x:0, y:1, z:2}, R).              |

    | P = point,                                                         |
    | Y = 1,                                                             |
    ||R_=__G1705{z:2}.__________________________________________________ ||

    See  also select_dict/2 to  ignore _R_e_s_t  and >:</2  for a  symmetric
    partial unification of two dicts.


_+_D_i_c_t_1 >:< _+_D_i_c_t_2
    This  operator specifies  a  _p_a_r_t_i_a_l _u_n_i_f_i_c_a_t_i_o_n  between _D_i_c_t_1  and
    _D_i_c_t_2.  It  is true when the tags and the values associated with all
    _c_o_m_m_o_n  keys have been unified.  The values associated to  keys that
    do  not appear in the other  dict are ignored.  Partial  unification
    is  symmetric.  For example, given a list of dicts, find  dicts that
    represent a point with X equal to zero:

    ____________________________________________________________________|                                                                    |
    |     member(Dict, List),                                            |

    ||____Dict_>:<_point{x:0,_y:Y}._____________________________________ ||

    See also :</2  and select_dict/3.


55..44..22..11 DDeessttrruuccttiivvee aassssiiggnnmmeenntt iinn ddiiccttss

This  section describes  the destructive  update  operations defined  on
dicts.    These actions  can  only _u_p_d_a_t_e  keys and  not  add or  remove
keys.    If  the  requested key  does  not  exist the  predicate  raises
existence_error(_k_e_y_, _K_e_y_, _D_i_c_t).  Note the additional argument.

Destructive assignment  is a  non-logical operation and  should be  used
with care because  the system may copy  or share identical Prolog  terms
at  any time.    Some of  this behaviour  can be  avoided  by adding  an
additional unbound value  to the dict.   This prevents unwanted  sharing
and ensures that copy_term/2 actually copies the dict.   This pitfall is
demonstrated in the example below:

________________________________________________________________________|                                                                        |
|?- A = a{a:1}, copy_term(A,B), b_set_dict(a, A, 2).                     |

|A = B, B = a{a:2}.                                                      |
|                                                                        |
|?- A = a{a:1,dummy:_}, copy_term(A,B), b_set_dict(a, A, 2).             |
|A = a{a:2, dummy:_G3195},                                               |
|B|=_a{a:1,_dummy:_G3391}.______________________________________________ | |


bb__sseett__ddiicctt((_+_K_e_y_, _!_D_i_c_t_, _+_V_a_l_u_e))                                    _[_d_e_t_]
    Destructively  update  the  value associated  with  _K_e_y in  _D_i_c_t  to
    _V_a_l_u_e.   The  update is trailed  and undone on  backtracking.   This
    predicate raises an  existence error if _K_e_y does not appear in _D_i_c_t.
    The update semantics are equivalent to setarg/3 and b_setval/2.


nnbb__sseett__ddiicctt((_+_K_e_y_, _!_D_i_c_t_, _+_V_a_l_u_e))                                   _[_d_e_t_]
    Destructively  update the  value associated  with _K_e_y in  _D_i_c_t to  a
    copy  of _V_a_l_u_e.   The update  is _n_o_t undone on  backtracking.   This
    predicate raises an  existence error if _K_e_y does not appear in _D_i_c_t.
    The update semantics are equivalent to nb_setarg/3 and nb_setval/2.


nnbb__lliinnkk__ddiicctt((_+_K_e_y_, _!_D_i_c_t_, _+_V_a_l_u_e))                                  _[_d_e_t_]
    Destructively  update  the  value associated  with  _K_e_y in  _D_i_c_t  to
    _V_a_l_u_e.   The update is _n_o_t  undone on backtracking.   This predicate
    raises  an existence  error if _K_e_y  does not  appear in _D_i_c_t.    The
    update  semantics are  equivalent to nb_linkarg/3  and nb_linkval/2.
    Use with  extreme care and consult the documentation of nb_linkval/2
    before use.


55..44..33 WWhheenn ttoo uussee ddiiccttss??

Dicts are  a new type in  the Prolog world.   They compete with  several
other types  and libraries.   In the  list below we  have a closer  look
at these  relations.   We will see that  dicts are first  of all a  good
replacement for compound terms  with a high or not clearly  fixed arity,
library record and option processing.

CCoommppoouunndd tteerrmmss  Compound  terms  with  positional  arguments   form  the
    traditional  way to package data in Prolog.  This  representation is
    well  understood, fast  and compound  terms are stored  efficiently.
    Compound  terms are  still the  representation  of choice,  provided
    that  the number  of arguments is  low and  fixed or compactness  or
    performance are of utmost importance.

    A  good example  of a  compound term  is the  representation of  RDF
    triples  using  the  term rdf(_S_u_b_j_e_c_t_,  _P_r_e_d_i_c_a_t_e_,  _O_b_j_e_c_t)  because
    RDF  triples are  defined to  have precisely  these three  arguments
    and  they are  always referred  to in this  order.   An  application
    processing  information  about  persons should  probably  use  dicts
    because  the  information that  is related  to a  person  is not  so
    fixed.    Typically  we see  first and  last name.    But there  may
    also  be  title, middle  name,  gender, date  of birth,  etc.    The
    number of arguments  becomes unmanagable when using a compound term,
    while  adding or removing an argument  leads to many changes in  the
    program.

LLiibbrraarryy record  Using library  record  relieves the  maintenance  issues
    associated  with using  compound terms significantly.   The  library
    generates  access and  modification predicates for  each field in  a
    compound  term  from a  declaration.    The library  provides  sound
    access  to compound terms with many arguments.  One of  its problems
    is  the  verbose syntax  needed  to access  or modify  fields  which
    results  from  long  names  for the  generated  predicates  and  the
    restriction  that each field needs  to be extracted with a  separate
    goal.    Consider the example  below, where  the first uses  library
    record and the second uses dicts.

    ____________________________________________________________________|                                                                    |
    |     ...,                                                           |

    |     person_first_name(P, FirstName),                               |
    |     person_last_name(P, LastName),                                 |
    |     format('Dear ~w ~w,~n~n', [FirstName, LastName]).              |
    |                                                                    |
    |     ...,                                                           |
    ||____format('Dear_~w_~w,~n~n',_[Dict.first_name,_Dict.last_name])._ ||

    Records  have a  fixed number  of arguments  and (non-)existence  of
    an  argument must be represented using  a value that is outside  the
    normal  domain.  This lead to unnatural code.  For  example, suppose
    our person also has a  title.  If we know the first name we use this
    and else we use the title.  The code samples below illustrate this.

    ____________________________________________________________________|                                                                    |

    | salutation(P) :-                                                   |
    |     person_first_name(P, FirstName), nonvar(FirstName), !,         |
    |     person_last_name(P, LastName),                                 |
    |     format('Dear ~w ~w,~n~n', [FirstName, LastName]).              |
    | salutation(P) :-                                                   |
    |     person_title(P, Title), nonvar(Title), !,                      |
    |     person_last_name(P, LastName),                                 |

    |     format('Dear ~w ~w,~n~n', [Title, LastName]).                  |
    |                                                                    |
    | salutation(P) :-                                                   |
    |     _{first_name:FirstName, last_name:LastName} :< P, !,           |
    |     format('Dear ~w ~w,~n~n', [FirstName, LastName]).              |
    | salutation(P) :-                                                   |
    |     _{title:Title, last_name:LastName} :< P, !,                    |
    ||____format('Dear_~w_~w,~n~n',_[Title,_LastName])._________________ ||

LLiibbrraarryy assoc  This library implements  a balanced binary  tree.   Dicts
    can  replace the use  of this library  if the association is  fairly
    static  (i.e.,  there  are  few update  operations),  all  keys  are
    atoms  or (small)  integers and the  code does  not rely on  ordered
    operations.

LLiibbrraarryy option  Option lists are introduced  by ISO Prolog, for  example
    for  read_term/3,  open/4,   etc.     The  option  library  provides
    operations to extract options,  merge options lists, etc.  Dicts are
    well  suited to replace option  lists because they are cheaper,  can
    be processed faster and have a more natural syntax.

LLiibbrraarryy pairs  This library  is  commonly used  to process  large  name-
    value  associations.     In many  cases  this  concerns  short-lived
    datastructures  that result  from findall/3,  maplist/3 and  similar
    list  processing predicates.    Dicts may  play a  role if  frequent
    random  key lookups are  needed on the  resulting association.   For
    example,  the skeleton  `create a pairs  list', `use list_to_assoc/2
    to  create an assoc', followed  by frequent usage of  get_assoc/3 to
    extract  key values can be replaced using  dict_pairs/3and  the dict
    access  functions.  Using dicts  in this scenario is more  efficient
    and provides a more pleasant access syntax.


55..44..44 AA mmoottiivvaattiioonn ffoorr ddiiccttss aass pprriimmaarryy cciittiizzeennss

Dicts, or key-value associations,  are a common data structure.   A good
old example  are _p_r_o_p_e_r_t_y _l_i_s_t_s  as found in Lisp,  while a good  recent
example is formed  by JavaScript _o_b_j_e_c_t_s.   Traditional Prolog does  not
offer native  property lists.    As a result,  people are  using a  wide
range of data structures for key-value associations:

  o Using compound terms and positional arguments, e.g., point(1,2).

  o Using   compound  terms   with  library   record,  which   generates
    access  predicates  for a  term using  positional  arguments from  a
    description.

  o Using   lists  of  terms  Name=Value,   Name-Value,  Name:Value   or
    Name(Value).

  o Using library assoc  which represents the associations as a balanced
    binary tree.

This situation  is unfortunate.    Each of these  have their  advantages
and disadvantages.    E.g.,  compound terms  are compact  and fast,  but
inflexible and using positional arguments quickly breaks down.   Library
record fixes this, but the syntax is considered hard to use.   Lists are
flexible, but  expensive and  the alternative key-value  representations
that  are  used  complicate  the  matter  even  more.     Library  assoc
allows  for efficient  manipulation of  changing associations,  but  the
syntactical  representation of  an assoc  is complex,  which makes  them
unsuitable  for e.g.,  _o_p_t_i_o_n_s  _l_i_s_t_s  as  seen in  predicates  such  as
open/4.


55..44..55 IImmpplleemmeennttaattiioonn nnootteess aabboouutt ddiiccttss

Although  dicts   are  designed  as  an   abstract  data  type  and   we
deliberately reserve  the possibility to  change the representation  and
even use  multiple representations, this  section describes the  current
implementation.

Dicts are  currently represented as  a compound  term using the  functor
`dict`.  The first argument is the tag.   The remaining arguments create
an array of sorted key-value pairs.  This  representation is compact and
guarantees good locality.  Lookup is order log(N),  while adding values,
deleting values  and merging with  other dicts has  order N.   The main
disadvantage is that changing  values in large dicts is costly,  both in
terms of memory and time.

Future versions may share  keys in a separate structure or use  a binary
trees to  allow for  cheaper updates.   One  of the issues  is that  the
representation must  either be  kept cannonical or  unification must  be
extended to compensate for alternate representations.


55..55 IInntteeggrraattiioonn ooff ssttrriinnggss aanndd ddiiccttss iinn tthhee lliibbrraarriieess

While  lacking proper  string  support  and dicts  when  designed,  many
predicates  and libraries  use  interfaces that  must be  classified  as
suboptimal.   Changing  these interfaces  is likely to  break much  more
code  than  the  changes  described in  this  chapter.     This  section
discusses  some  of  these issues.     Roughly,  there  are  two  cases.
There where  key-value associations  or text  is required  as _i_n_p_u_t,  we
can  facilitate the  new  features by  overloading the  accepted  types.
Interfaces that produce  text or key-value associations as their  _o_u_t_p_u_t
however  must make  a choice.    We plan  to resolve  that using  either
options  that specify  the  desired  output or  provide  an  alternative
library.


55..55..11 DDiiccttss aanndd ooppttiioonn pprroocceessssiinngg

System predicates and predicates based on library  options process dicts
as an alternative to traditional option lists.


55..55..22 DDiiccttss iinn ccoorree ddaattaa ssttrruuccttuurreess

Some predicates  now produce  structured data using  compound terms  and
access predicates.   We consider migrating these  to dicts.  Below is  a
tentative list  of candidates.   Portable code  should use the  provided
access predicates and not rely on the term representation.

  o Stream position terms

  o Date and time records


55..55..33 DDiiccttss,, ssttrriinnggss aanndd XXMMLL

The  XML  representation  could  benefit  significantly   from  the  new
features.    In  due time  we  plan to  provide  an set  of  alternative
predicates  and options  to  existing predicates  that  can be  used  to
exploit the  new types.   We propose the  following changes to the  data
representation:

  o The  attribute list of the  element(_N_a_m_e_, _A_t_t_r_i_b_u_t_e_s_, _C_o_n_t_e_n_t)  will
    become a dict.

  o Attribute values will remain atoms

  o CDATA in element content will be represented as strings


55..55..44 DDiiccttss,, ssttrriinnggss aanndd JJSSOONN

The  JSON  representation  could  benefit  significantly  from  the  new
features.    In  due time  we  plan to  provide  an set  of  alternative
predicates  and options  to  existing predicates  that  can be  used  to
exploit the  new types.   We propose the  following changes to the  data
representation:

  o Instead   of  using  json(_K_e_y_V_a_l_u_e_L_i_s_t),  the  new   interface  will
    translate  JSON objects to a  dict.  The  type of this dict will  be
    json.

  o String values in JSON will be mapped to strings.

  o The values true, false and null will be represented as atoms.


55..55..55 DDiiccttss,, ssttrriinnggss aanndd HHTTTTPP

The  HTTP  library  and  related  data  structures   would  profit  from
exploiting dicts.   Below  is a  list of data  structures that might  be
affected by future changes.   Code can be made more robust by  using the
option library functions for extracting values from these structures.

  o The HTTP request structure

  o The HTTP parameter interface

  o URI components

  o Attributes to HTML elements


55..66 RReemmaaiinniinngg iissssuueess

The changes  and extensions  described in  this chapter  resolve a  many
limitations of the  Prolog language we have  encountered.  Still,  there
are remaining issues for which we seek solutions in the future.

TTeexxtt  rreepprreesseennttaattiioonn Although  strings  resolve  this  issue   for  many
applications,  we are still  faced with  the representation  of text  as
lists  of  characters which  we  need  for  parsing using  DCGs.     The
ISO standard  provides two  representations, a list  of _c_h_a_r_a_c_t_e_r  _c_o_d_e_s
(`codes'  for short)  and a  list of  _o_n_e_-_c_h_a_r_a_c_t_e_r  _a_t_o_m_s (`chars'  for
short).     There  are  two  sets of  predicates,  named  *_code(s)  and
*_char(s)  that provide  the same  functionality (e.g.,  atom_codes/2 and
atom_chars/2) using  their  own representation  of  characters.    Codes
can be  used in arithmetic expressions,  while chars are more  readable.
Neither can  unambiguously be interpreted as  a representation for  text
because codes can  be interpreted as a list  of integers and chars as  a
list of atoms.

We have  not found  a convincing  way out.    One of  the options  could
be the  introduction of  a `char' type.    This type can  be allowed  in
arithmetic and with  the 0'<char> syntax we  have a concrete syntax  for
it.

AArrrraayyss Although  lists are  generally  a  much cleaner  alternative  for
Prolog, real  arrays with direct  access to elements  can be useful  for
particular tasks.  The problem of integrating arrays is  twofold.  First
of  all, there  is  no good  one-size-fits-all data  representation  for
arrays.   Many tasks that involve  arrays require _m_u_t_a_b_l_e arrays,  while
Prolog data  is immutable  by design.   Second,  standard Prolog has  no
good  syntax support  for  arrays.    SWI-Prolog  version 7  has  `block
operators'  (see section  ????) which  can resolve  the syntactic  issues.
Block operators have been adopted by YAP.

LLaammbbddaa  eexxpprreessssiioonnss Although many  alternatives have  been proposed,  we
still feel uneasy with them.

LLooooppss Many people have  explored routes to avoid the need  for recursion
in  Prolog for  simple iterations  over  data.   ECLiPSe  have  proposed
_l_o_g_i_c_a_l _l_o_o_p_s [??], while B-Prolog introduced _d_e_c_l_a_r_a_t_i_v_e  _l_o_o_p_s and _l_i_s_t
_c_o_m_p_r_e_h_e_n_s_i_o_n.   The above mentioned  lambda expressions, combined  with
maplist/2 can achieve similar results.


CChhaapptteerr 66..  MMOODDUULLEESS

A Prolog  module is a  collection of predicates  which defines a  public
interface  by means  of  a set  of  provided predicates  and  operators.
Prolog  modules are  defined by  an ISO  standard.   Unfortunately,  the
standard  is considered  a failure  and, as  far as  we are  aware,  not
implemented  by any  concrete  Prolog implementation.    The  SWI-Prolog
module system syntax  is derived from the Quintus Prolog  module system.
The Quintus  module system has  been the starting  point for the  module
systems  of a  number of  mainstream Prolog  systems,  such as  SICStus,
Ciao and YAP. The underlying primitives of the  SWI-Prolog module system
differ from the mentioned systems.  These primitives  allow for multiple
modules in  a file,  hierarchical  modules, emulation  of other  modules
interfaces, etc.

This  chapter motivates  and  describes  the SWI-Prolog  module  system.
Novices  can start  using the  module system  after  reading section  ????
and section ????.   The primitives  defined in these sections suffice  for
basic usage  until one needs  to export predicates  that call or  manage
other predicates dynamically (e.g.,  use call/1, assert/1, etc.).   Such
predicates are called  _m_e_t_a _p_r_e_d_i_c_a_t_e_s and are discussed in  section ????.
Section ???? to section  ???? describe more advanced issues.   Starting with
section ????, we  discuss more low-level aspects of the  SWI-Prolog module
system that are used to implement the visible module  system, and can be
used to build other code reuse mechanisms.


66..11 WWhhyy UUssee MMoodduulleess??

In classic  Prolog systems,  all predicates  are organised  in a  single
namespace  and any  predicate can  call  any predicate.    Because  each
predicate  in  a file  can  be  called  from anywhere  in  the  program,
it  becomes  very  hard  to  find  the  dependencies   and  enhance  the
implementation  of a  predicate  without risking  to break  the  overall
application.  This  is true for any language, but even worse  for Prolog
due to its frequent need for `helper predicates'.

A  Prolog  module  encapsulates a  set  of  predicates  and  defines  an
_i_n_t_e_r_f_a_c_e.     Modules  can  import  other  modules,   which  makes  the
dependencies explicit.   Given explicit dependencies and a  well-defined
interface, it  becomes much easier  to change the internal  organisation
of a module without breaking the overall application.

Explicit dependencies can  also be used by the development  environment.
The SWI-Prolog library  prolog_xref  can be used to analyse  completeness
and  consistency of  modules.   This  library is  used  by the  built-in
editor PceEmacs for syntax highlighting, jump-to-definition, etc.


66..22 DDeeffiinniinngg aa MMoodduullee

Modules are normally  created by loading a _m_o_d_u_l_e  _f_i_l_e.  A module  file
is a file holding a module/2 directive as its first term.   The module/2
directive declares  the name and the  public (i.e., externally  visible)
predicates of  the module.   The  rest of  the file is  loaded into  the
module.   Below is an example of  a module file, defining reverse/2  and
hiding  the helper  predicate rev/3.    A module  can  use all  built-in
predicates and, by default, cannot redefine system predicates.

________________________________________________________________________|                                                                        |
|:- module(reverse, [reverse/2]).                                        |

|                                                                        |
|reverse(List1, List2) :-                                                |
|        rev(List1, [], List2).                                          |
|                                                                        |
|rev([], List, List).                                                    |
|rev([Head|List1], List2, List3) :-                                      |
||_______rev(List1,_[Head|List2],_List3)._______________________________ ||

The  module is  named reverse.    Typically,  the name  of  a module  is
the same  as the name  of the file  by which it  is defined without  the
filename  extension, but  this  naming is  not enforced.    Modules  are
organised in  a single  and flat  namespace and  therefore module  names
must be  chosen with  some care to  avoid conflicts.   As  we will  see,
typical  applications of  the module  system rarely  use the  name of  a
module explicitly in the source text.


::-- mmoodduullee((_+_M_o_d_u_l_e_, _+_P_u_b_l_i_c_L_i_s_t))
    This  directive can  only  be used  as the  first term  of a  source
    file.    It  declares  the file  to be  a  _m_o_d_u_l_e _f_i_l_e,  defining  a
    module  named _M_o_d_u_l_e.   Note  that a module  name is an  atom.   The
    module  exports  the predicates  of  _P_u_b_l_i_c_L_i_s_t.   _P_u_b_l_i_c_L_i_s_t  is  a
    list  of predicate indicators  (name/arity or name//arity pairs)  or
    operator  declarations using the format op(_P_r_e_c_e_d_e_n_c_e_, _T_y_p_e_,  _N_a_m_e).
    Operators  defined  in  the export  list  are available  inside  the
    module  as well  as  to modules  importing this  module.   See  also
    section ????.

    Compatible to Ciao Prolog,  if _M_o_d_u_l_e is unbound, it is unified with
    the basename without extension of the file being loaded.


::-- mmoodduullee((_+_M_o_d_u_l_e_, _+_P_u_b_l_i_c_L_i_s_t_, _+_D_i_a_l_e_c_t))
    Same  as  module/2.     The  additional  _D_i_a_l_e_c_t  argument  provides
    a  list  of  _l_a_n_g_u_a_g_e  _o_p_t_i_o_n_s.    Each  atom in  the  list  _D_i_a_l_e_c_t
    is  mapped  to  a  use_module/1 goal  as  given  below.    See  also
    section ????.   The third argument is supported for compatibility with
    the http://prolog-commons.org/Prolog Commons project.

    ____________________________________________________________________|                                                                    |
    ||:-_use_module(library(dialect/LangOption))._______________________ ||


66..33 IImmppoorrttiinngg PPrreeddiiccaatteess iinnttoo aa MMoodduullee

Predicates  can be  added to  a module  by _i_m_p_o_r_t_i_n_g  them from  another
module.   Importing adds predicates  to the namespace of  a module.   An
imported predicate can be  called exactly the same as a  locally defined
predicate, although  its implementation  remains part of  the module  in
which it has been defined.

Importing  the predicates  from  another module  is achieved  using  the
directives use_module/1 or use_module/2.  Note that both directives take
_f_i_l_e_n_a_m_e_(_s_) as arguments.  That is, modules are  imported based on their
filename rather than their module name.


uussee__mmoodduullee((_+_F_i_l_e_s))
    Load  the file(s)  specified with  _F_i_l_e_s just  like ensure_loaded/1.
    The  files  must all  be  module files.    All  exported  predicates
    from  the  loaded files  are  imported into  the module  from  which
    this  predicate  is  called.     This  predicate  is  equivalent  to
    ensure_loaded/1,  except that it  raises an error  if _F_i_l_e_s are  not
    module files.

    The  imported predicates  act  as _w_e_a_k  _s_y_m_b_o_l_s in  the module  into
    which  they are imported.   This implies that a local definition  of
    a  predicate overrides (clobbers) the  imported definition.  If  the
    flag  warn_override_implicit_importis true  (default), a warning  is
    printed.  Below  is an example of a module that uses library(lists),
    but redefines flatten/2, giving it a totally different meaning:

    ____________________________________________________________________|                                                                    |
    | :- module(shapes, []).                                             |

    | :- use_module(library(lists)).                                     |
    |                                                                    |
    | flatten(cube, square).                                             |
    ||flatten(ball,_circle).____________________________________________ ||

    Loading the above file prints the following message:

    ____________________________________________________________________|                                                                    |
    | Warning: /home/janw/Bugs/Import/t.pl:5:                            |
    |         Local definition of shapes:flatten/2                       |

    ||________overrides_weak_import_from_lists__________________________ ||

    This  warning  can be  avoided  by (1)  using  use_module/2 to  only
    import the predicates  from the lists library that are actually used
    in  the `shapes'  module, (2)  using the except([flatten/2])  option
    of  use_module/2, (3)  use :- abolish(flatten/2).  before the  local
    definition  or (4)  setting warn_override_implicit_import to  false.
    Globally  disabling this warning  is only recommended if  overriding
    imported  predicates is common as a result of design choices  or the
    program  is ported  from a system  that silently overrides  imported
    predicates.

    Note  that  it  is  always  an error  to  import  two  modules  with
    use_module/1 that  export the same predicate.   Such conflicts  must
    be resolved with use_module/2 as described above.


uussee__mmoodduullee((_+_F_i_l_e_, _+_I_m_p_o_r_t_L_i_s_t))
    Load  _F_i_l_e, which must be a  module file, and import the  predicates
    as  specified by  _I_m_p_o_r_t_L_i_s_t.   _I_m_p_o_r_t_L_i_s_t  is a  list of  predicate
    indicators   specifying  the  predicates   that  will  be   imported
    from  the  loaded  module.    _I_m_p_o_r_t_L_i_s_t  also allows  for  renaming
    or  import-everything-except.     See  also  the  import  option  of
    load_files/2.    The first  example below  loads  member/2 from  the
    lists  library and  append/2 under  the name  list_concat, which  is
    how  this predicate is  named in YAP.  The second example loads  all
    exports  from  library  option except  for  meta_options/3.    These
    renaming  facilities are  generally  used to  deal with  portability
    issues  with as few  changes as possible  to the actual  code.   See
    also section ???? and section ????.

    ____________________________________________________________________|                                                                    |
    | :- use_module(library(lists), [ member/2,                          |
    |                                 append/2 as list_concat            |
    |                               ]).                                  |

    ||:-_use_module(library(option),_except([meta_options/3]))._________ ||

In most cases  a module is imported  because some of its predicates  are
being used.  However, sometimes a module is  imported for other reasons,
e.g., for its  declarations.  In such  cases it is best practice to  use
use_module/2 with  empty ImportList.    This  distinguishes an  imported
module that  is used,  although not  for its predicates,  from a  module
that is needlessly imported.

The module/2,  use_module/1 and  use_module/2 directives are  sufficient
to  partition a  simple Prolog  program into  modules.   The  SWI-Prolog
graphical  cross-referencing tool  gxref/0 can  be used  to analyse  the
dependencies between  non-module files  and propose module  declarations
for each file.


66..44 DDeeffiinniinngg aa mmeettaa--pprreeddiiccaattee

A   meta-predicate  is   a  predicate   that   calls  other   predicates
dynamically,  modifies  a  predicate,  or reasons  about  properties  of
a  predicate.     Such predicates  use  either  a  compound  term  or  a
_p_r_e_d_i_c_a_t_e  _i_n_d_i_c_a_t_o_r  to describe  the  predicate  they  address,  e.g.,
assert(name(jan))  or  abolish(name/1).     With  modules,  this  simple
schema  no longer  works as  each module  defines its  own mapping  from
name+arity to  predicate.   This  is resolved by  wrapping the  original
description in a term <_m_o_d_u_l_e>:<_t_e_r_m>,  e.g., assert(person:name(jan)) or
abolish(person:name/1).

Of course,  when calling  assert/1 from  inside a module,  we expect  to
assert to  a predicate  local to this  module.   In other  words, we  do
not wish  to provide  this :/2 wrapper  by hand.    The meta_predicate/1
directive tells the compiler that certain arguments are  terms that will
be used to look  up a predicate and thus need to be  wrapped (qualified)
with <_m_o_d_u_l_e>:<_t_e_r_m>, unless they are already wrapped.

In  the  example  below,  we  use this  to  define  maplist/3  inside  a
module.   The argument `2' in the  meta_predicate declaration means  that
the  argument is  module-sensitive and  refers to  a  predicate with  an
arity that is  two more than the term that  is passed in.   The compiler
only distinguishes the values 0..9 and :,  which denote module-sensitive
arguments,  from +,  -  and ?,  which denote  _m_o_d_e_s.    The values  0..9
are used  by the _c_r_o_s_s_-_r_e_f_e_r_e_n_c_e_r  and syntax highlighting.   Note  that
the  helper predicate  maplist_/3 does  not  need to  be declared  as  a
meta-predicate because the  maplist/3 wrapper already ensures that  _G_o_a_l
is qualified as <_m_o_d_u_l_e>:_G_o_a_l.   See the description of  meta_predicate/1
for details.

________________________________________________________________________|                                                                        |
|:- module(maplist, [maplist/3]).                                        |
|:- meta_predicate maplist(2, ?, ?).                                     |
|                                                                        |

|%%      maplist(:Goal, +List1, ?List2)                                  |
|%                                                                       |
|%       True if Goal can successfully be applied to all                 |
|%       successive pairs of elements from List1 and List2.              |
|                                                                        |
|maplist(Goal, L1, L2) :-                                                |
|        maplist_(L1, L2, Goal).                                         |
|                                                                        |

|maplist_([], [], _).                                                    |
|maplist_([H0|T0], [H|T], Goal) :-                                       |
|        call(Goal, H0, H),                                              |
||_______maplist_(T0,_T,_Goal)._________________________________________ ||


mmeettaa__pprreeddiiccaattee _+_H_e_a_d_, _._._.
    Define  the predicates referenced  by the comma-separated list  _H_e_a_d
    as  _m_e_t_a_-_p_r_e_d_i_c_a_t_e_s.  Each argument of each head is a  _m_e_t_a _a_r_g_u_m_e_n_t
    _s_p_e_c_i_f_i_e_r.  Defined  specifiers are given below.  Only 0..9, : and ^
    are interpreted; the mode declarations +, -  and ? are ignored.

    00....99
         The argument is  a term that is  used to reference a  predicate
         with N  more  arguments than  the given  argument  term.   For
         example:  call(0) or maplist(1, +).

    :
         The argument is  module-sensitive, but does not directly  refer
         to a predicate.  For example:  consult(:).

    -
         The argument is not module-sensitive and unbound on entry.

    ?
         The argument is not  module-sensitive and the mode is  unspeci-
         fied.

    *
         The argument is not  module-sensitive and the mode is  unspeci-
         fied.  The specification * is equivalent to ?.   It is accepted
         for compatibility reasons.   The predicate predicate_property/2
         reports arguments declared using * with ?.

    +
         The argument is  not module-sensitive and bound (i.e.,  nonvar)
         on entry.

    ^
         This extension is used to denote the  possibly ^-annotated goal
         of  setof/3, bagof/3,  aggregate/3  and  aggregate/4.    It  is
         processed similar to `0', but leaving the ^/2 intact.

    //
         The argument is a DCG body.  See phrase/3.

    Each  argument that is module-sensitive (i.e., marked 0..9, :  or ^)
    is  qualified with the  context module  of the caller  if it is  not
    already qualified.   The implementation ensures that the argument is
    passed  as <_m_o_d_u_l_e>:<_t_e_r_m>,  where <_m_o_d_u_l_e>  is an  atom denoting  the
    name  of a  module and  <_t_e_r_m> itself  is not a  :/2 term  where the
    first  argument is an  atom.   Below is a  simple declaration and  a
    number of queries.

    ____________________________________________________________________|                                                                    |

    | :- meta_predicate                                                  |
    |         meta(0, +).                                                |
    |                                                                    |
    | meta(Module:Term, _Arg) :-                                         |
    ||________format('Module=~w,_Term_=_~q~n',_[Module,_Term])._________ ||

    ____________________________________________________________________|                                                                    |
    | ?- meta(test, x).                                                  |
    | Module=user, Term = test                                           |

    | ?- meta(m1:test, x).                                               |
    | Module=m1, Term = test                                             |
    | ?- m2:meta(test, x).                                               |
    | Module=m2, Term = test                                             |
    | ?- m1:meta(m2:test, x).                                            |
    | Module=m2, Term = test                                             |
    | ?- meta(m1:m2:test, x).                                            |

    | Module=m2, Term = test                                             |
    | ?- meta(m1:42:test, x).                                            |
    ||Module=42,_Term_=_test____________________________________________ ||

    The   meta_predicate/1  declaration   is   the  portable   mechanism
    for  defining   meta-predicates  and  replaces  the  old  SWI-Prolog
    specific   mechanism   provided   by   the   deprecated   predicates
    module_transparent/1, context_module/1 and strip_module/3.  See also
    section ????.


66..55 OOvveerrrruulliinngg MMoodduullee BBoouunnddaarriieess

The module system described so far is sufficient  to distribute programs
over multiple  modules.   There are,  however, cases  in which we  would
like to be able to overrule this schema and  explicitly call a predicate
in  some module  or assert  explicitly into  some module.    Calling  in
a  particular  module  is useful  for  debugging  from  the  user's  top
level  or to  access  multiple  implementations of  the  same  interface
that reside  in multiple  modules.   Accessing the  same interface  from
multiple modules cannot be achieved using importing  because importing a
predicate with  the same name  and arity from two  modules results in  a
name conflict.   Asserting in a different  module can be used to  create
models dynamically in a new module.  See section ????.

Direct addressing  of modules is  achieved using a  :/2 explicitly in  a
program and  relies on the module  qualification mechanism described  in
section ????.  Here are a few examples:

________________________________________________________________________|                                                                        |
|?- assert(world:done).   % asserts done/0 into module world             |

|?- world:asserta(done).  % the same                                     |
|?-|world:done.___________%_calls_done/0_in_module_world________________ |  |

Note  that the  second  example  is the  same  due  to the  Prolog  flag
colon_sets_calling_context.   The  system predicate  asserta/1 is  called
in the  module world,  which is possible  because system predicates  are
_v_i_s_i_b_l_e  in all  modules.   At  the same  time, the  _c_a_l_l_i_n_g _c_o_n_t_e_x_t  is
set to  world.   Because meta arguments are  qualified with the  calling
context, the resulting call is the same as the first example.


66..55..11 EExxpplliicciitt mmaanniippuullaattiioonn ooff tthhee ccaalllliinngg ccoonntteexxtt

Quintus'  derived  module   systems  have  no  means  to  separate   the
lookup module  (for finding  predicates) from the  calling context  (for
qualifying meta  arguments).  Some  other Prolog implementations  (e.g.,
ECLiPSe  and IF/Prolog)  distinguish  these operations,  using  @/2  for
setting the calling context of a goal.  This  is provided by SWI-Prolog,
currently mainly to support compatibility layers.


@@((_:_G_o_a_l_, _+_M_o_d_u_l_e))
    Execute  _G_o_a_l,  setting the  calling  context to  _M_o_d_u_l_e.    Setting
    the   calling  context  affects  meta-predicates,  for   which  meta
    arguments  are  qualified  with _M_o_d_u_l_e  and  transparent  predicates
    (see  module_transparent/1).    It  has  no implications  for  other
    predicates.

    For   example,   the  code  asserta(done)@world   is  the  same   as
    asserta(world:done).   Unlike  in world:asserta(done), asserta/1  is
    resolved  in the current module rather than the module world.   This
    makes  no difference for system predicates, but usually does  make a
    difference for user predicates.

    Not that SWI-Prolog does  not define @ as an operator.  Some systems
    define this construct using op(900, xfx, @).


66..66 IInntteerraaccttiinngg wwiitthh mmoodduulleess ffrroomm tthhee ttoopp lleevveell

Debugging  often requires  interaction with  predicates  that reside  in
modules:   running them,  setting spy  points on them,  etc.   This  can
be achieved using  the <_m_o_d_u_l_e>:<_t_e_r_m> construct explicitly  as described
above.     In  SWI-Prolog,  you  may   also  wish  to  omit  the  module
qualification.   Setting a spy point  (spy/1) on a plain predicate  sets
a spy  point on any  predicate with that  name in any  module.   Editing
(edit/1)  or calling  an  unqualified  predicate invokes  the  DWIM  (Do
What I Mean)  mechanism, which generally suggests the  correct qualified
query.

Mainly for compatibility, we provide module/1 to switch  the module with
which the interactive top level interacts:


mmoodduullee((_+_M_o_d_u_l_e))
    The  call module(_M_o_d_u_l_e) may be  used to switch the default  working
    module  for the interactive top level  (see prolog/0).  This may  be
    used  when debugging a module.  The example below lists  the clauses
    of file_of_label/2 in the module tex.

    ____________________________________________________________________|                                                                    |
    | 1 ?- module(tex).                                                  |
    | true.                                                              |
    | tex: 2 ?- listing(file_of_label/2).                                |

    ||..._______________________________________________________________ ||


66..77 CCoommppoossiinngg mmoodduulleess ffrroomm ootthheerr mmoodduulleess

The  predicates in  this  section are  intended  to create  new  modules
from  the content  of other  modules.   Below  is an  example to  define
a  _c_o_m_p_o_s_i_t_e module.    The  example exports  all public  predicates  of
module_1, module_2 and  module_3, pred/1  from module_4, all  predicates
from module_5 except do_not_use/1 and all predicates from module_6 while
renaming pred/1 into mypred/1.

________________________________________________________________________|                                                                        |
|:- module(my_composite, []).                                            |

|:- reexport([ module_1,                                                 |
|              module_2,                                                 |
|              module_3                                                  |
|            ]).                                                         |
|:- reexport(module_4, [ pred/1 ]).                                      |
|:- reexport(module_5, except([do_not_use/1])).                          |
|:-|reexport(module_6,_except([pred/1_as_mypred]))._____________________ |  |


rreeeexxppoorrtt((_+_F_i_l_e_s))
    Load  and  import  predicates  as  use_module/1  and  re-export  all
    imported  predicates.   The reexport  declarations must  immediately
    follow the module declaration.


rreeeexxppoorrtt((_+_F_i_l_e_, _+_I_m_p_o_r_t))
    Import  from   _F_i_l_e  as  use_module/2 and   re-export  the  imported
    predicates.   The reexport declarations must immediately  follow the
    module declaration.


66..88 OOppeerraattoorrss aanndd mmoodduulleess

Operators  (section  ????)  are  local  to  modules,   where  the  initial
table  behaves  as   if  it  is  copied   from  the  module  user   (see
section  ????).   A  specific operator  can be  disabled  inside a  module
using :- op(0, Type, Name).   Inheritance from  the public table can  be
restored using :- op(-1, Type, Name).

In addition to  using the op/3 directive,  operators can be declared  in
the  module/2 directive  as shown  below.    Such operator  declarations
are  visible inside  the  module,  and  importing such  a  module  makes
the operators  visible in  the target  module.   Exporting operators  is
typically used by modules that implement sub-languages such  as chr (see
chapter ????).  The example below is copied from the library clpfd.

________________________________________________________________________|                                                                        |
|:- module(clpfd,                                                        |

|          [ op(760, yfx, #<==>),                                        |
|            op(750, xfy, #==>),                                         |
|            op(750, yfx, #<==),                                         |
|            op(740, yfx, #\/),                                          |
|            ...                                                         |
|            (#<==>)/2,                                                  |
|            (#==>)/2,                                                   |
|            (#<==)/2,                                                   |

|            (#\/)/2,                                                    |
|            ...                                                         |
||_________]).__________________________________________________________ ||


66..99 DDyynnaammiicc iimmppoorrttiinngg uussiinngg iimmppoorrtt mmoodduulleess

Until now  we discussed the  public module interface  that is, at  least
to some  extent, portable between  Prolog implementations with a  module
system that  is derived  from Quintus  Prolog.   The  remainder of  this
chapter describes the underlying mechanisms that can be  used to emulate
other module systems or implement other code-reuse mechanisms.

In  addition to  built-in predicates,  imported  predicates and  locally
defined predicates,  SWI-Prolog modules  can also  call predicates  from
its _i_m_p_o_r_t _m_o_d_u_l_e_s.   Each module has a (possibly empty) list  of import
modules.   In the  default setup,  each new module  has a single  import
module, which  is user for  all normal user modules  and system for  all
system  library modules.    Module user  imports from  system where  all
built-in predicates  reside.   These  special modules  are described  in
more detail in section ????.

The list  of import  modules can  be manipulated and  queried using  the
following predicates, as well as using set_module/1.


iimmppoorrtt__mmoodduullee((_+_M_o_d_u_l_e_, _-_I_m_p_o_r_t))                                 _[_n_o_n_d_e_t_]
    True  if  _M_o_d_u_l_e   inherits  directly  from  _I_m_p_o_r_t.     All  normal
    modules  only import  from user,  which imports  from system.    The
    predicates  add_import_module/3  and delete_import_module/2  can  be
    used to manipulate the import list.  See also default_module/2.


ddeeffaauulltt__mmoodduullee((_+_M_o_d_u_l_e_, _-_D_e_f_a_u_l_t))                                _[_m_u_l_t_i_]
    True  if predicates and operators in _D_e_f_a_u_l_t are visible  in _M_o_d_u_l_e.
    Modules  are returned in the  same search order used for  predicates
    and  operators.   That  is, _D_e_f_a_u_l_t  is first  unified with  _M_o_d_u_l_e,
    followed by the depth-first transitive closure of import_module/2.


aadddd__iimmppoorrtt__mmoodduullee((_+_M_o_d_u_l_e_, _+_I_m_p_o_r_t_, _+_S_t_a_r_t_O_r_E_n_d))
    If  _I_m_p_o_r_t is not  already an  import module for  _M_o_d_u_l_e, add it  to
    this  list at the start  or end depending on  _S_t_a_r_t_O_r_E_n_d.  See  also
    import_module/2 and delete_import_module/2.


ddeelleettee__iimmppoorrtt__mmoodduullee((_+_M_o_d_u_l_e_, _+_I_m_p_o_r_t))
    Delete  _I_m_p_o_r_t from the  list of import modules  for _M_o_d_u_l_e.   Fails
    silently if _I_m_p_o_r_t is not in the list.

One usage  scenario of import modules  is to define  a module that is  a
copy of another,  but where one or  more predicates have an  alternative
definition.


66..1100 RReesseerrvveedd MMoodduulleess aanndd uussiinngg tthhee ``uusseerr'' mmoodduullee

As  mentioned above,  SWI-Prolog  contains two  special  modules.    The
first one  is the  module system.    This module  contains all  built-in
predicates.   Module system has  no import module.   The second  special
module is the module user.  This module forms  the initial working space
of the user.   Initially it is empty.  The import module of  module user
is system, making all built-in predicates available.

All  other modules  import from  the module  user.    This implies  they
can use all  predicates imported into user without explicitly  importing
them.   If an application loads all  modules from the user module  using
use_module/1, one achieves a  scoping system similar to the  C-language,
where  every module  can  access  all exported  predicates  without  any
special precautions.


66..1111 AAnn aalltteerrnnaattiivvee iimmppoorrtt//eexxppoorrtt iinntteerrffaaccee

The use_module/1  predicate from section  ???? defines  import and  export
relations based  on the  filename from  which a module  is loaded.    If
modules are created differently, such as by asserting  predicates into a
new module as  described in section ????,  this interface cannot be  used.
The interface  below provides  for import/export from  modules that  are
not created using a module file.


eexxppoorrtt((_+_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.))
    Add  predicates to  the public  list of the  context module.    This
    implies  the predicate will be imported into another module  if this
    module is  imported with use_module/[1,2].   Note that predicates are
    normally  exported using the directive module/2.  export/1  is meant
    to handle export from dynamically created modules.


iimmppoorrtt((_+_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.))
    Import  predicates   _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r  into  the  current  context
    module.    _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r must specify  the source module  using
    the  <_m_o_d_u_l_e>:<_p_i>construct.    Note  that predicates  are  normally
    imported  using  one  of  the  directives  use_module/[1,2].     The
    import/1 alternative is  meant for handling imports into dynamically
    created modules.  See also export/1 and export_list/2.


66..1122 DDyynnaammiicc MMoodduulleess

So  far, we  discussed modules  that were  created by  loading a  module
file.  These modules have been introduced to  facilitate the development
of large applications.   The modules  are fully defined at load-time  of
the application and normally  will not change during execution.   Having
the  notion  of a  set  of  predicates  as a  self-contained  world  can
be  attractive for  other purposes  as well.    For example,  assume  an
application that  can reason about  multiple worlds.   It is  attractive
to store  the data  of a  particular world in  a module,  so we  extract
information from a world simply by invoking goals in this world.

Dynamic modules  can easily  be created.   Any  built-in predicate  that
tries  to locate  a predicate  in  a specific  module will  create  this
module as a side-effect if it did not yet exist.  For example:

________________________________________________________________________|                                                                        |
|?- assert(world_a:consistent),                                          |

||__set_prolog_flag(world_a:unknown,_fail)._____________________________ ||

These  calls  create  a  module  called  `world_a'  and  make  the  call
`world_a:consistent'  succeed.   Undefined predicates  will not raise  an
exception for this module (see unknown).

Import  and export  from a  dynamically created  world  can be  achieved
using  import/1 and  export/1  or by  specifying  the import  module  as
described in section ????.

________________________________________________________________________|                                                                        |

|?- world_b:export(solve/2).          % exports solve/2 from world_b     |
|?-|world_c:import(world_b:solve/2).__%_and_import_it_to_world_c________ |  |


66..1133 TTrraannssppaarreenntt pprreeddiiccaatteess::  ddeeffiinniittiioonn aanndd ccoonntteexxtt mmoodduullee

_T_h_e  _`_m_o_d_u_l_e_-_t_r_a_n_s_p_a_r_e_n_t_'  _m_e_c_h_a_n_i_s_m  _i_s  _s_t_i_l_l  _u_n_d_e_r_l_y_i_n_g  _t_h_e  _a_c_t_u_a_l
_i_m_p_l_e_m_e_n_t_a_t_i_o_n_.  _D_i_r_e_c_t _u_s_a_g_e _b_y _p_r_o_g_r_a_m_m_e_r_s _i_s _d_e_p_r_e_c_a_t_e_d_.   _P_l_e_a_s_e _u_s_e
meta_predicate/1 _t_o _d_e_a_l _w_i_t_h _m_e_t_a_-_p_r_e_d_i_c_a_t_e_s_.

The qualification of module-sensitive arguments described  in section ????
is  realised  using  _t_r_a_n_s_p_a_r_e_n_t predicates.     It  is  now  deprecated
to  use this  mechanism  directly.    However, studying  the  underlying
mechanism  helps   to  understand  SWI-Prolog's  modules.      In   some
respect, the transparent mechanism is more  powerful than meta-predicate
declarations.

Each  predicate  of  the  program  is  assigned  a  module,  called  its
_d_e_f_i_n_i_t_i_o_n _m_o_d_u_l_e.   The definition module of a predicate is  always the
module in which the predicate was originally defined.   Each active goal
in the Prolog system has a _c_o_n_t_e_x_t _m_o_d_u_l_e assigned to it.

The context  module is used to  find predicates for a  Prolog term.   By
default, the  context module is the  definition module of the  predicate
running the  goal.   For transparent  predicates, however,  this is  the
context module  of the  goal inherited  from the  parent goal.    Below,
we implement  maplist/3 using the  transparent mechanism.   The code  of
maplist/3 and maplist_/3 is the same  as in section ????, but now  we must
declare both the main  predicate and the helper as transparent  to avoid
changing the context module when calling the helper.

________________________________________________________________________|                                                                        |
|:- module(maplist, maplist/3).                                          |

|                                                                        |
|:- module_transparent                                                   |
|        maplist/3,                                                      |
|        maplist_/3.                                                     |
|                                                                        |
|maplist(Goal, L1, L2) :-                                                |
|        maplist_(L1, L2, G).                                            |
|                                                                        |

|maplist_([], [], _).                                                    |
|maplist_([H0|T0], [H|T], Goal) :-                                       |
|        call(Goal, H0, H),                                              |
||_______maplist_(T0,_T,_Goal)._________________________________________ ||

Note  that   _a_n_y  call   that  translates  terms   into  predicates   is
subject  to  the  transparent  mechanism,  not  just  the  terms  passed
to  module-sensitive  arguments.      For  example,  the   module  below
counts  the  number   of  unique  atoms  returned  as  bindings   for  a
variable.     It   works  as  expected.     If  we  use   the  directive
:- module_transparent count_atom_results/3. instead,   atom_result/2  is
called wrongly  in the  module _c_a_l_l_i_n_g  count_atom_results/3.   This  can
be  solved  using  strip_module/3 to  create  a  qualified  goal  and  a
non-transparent helper predicate that is defined in the same module.

________________________________________________________________________|                                                                        |
|:- module(count_atom_results,                                           |
|          [ count_atom_results/3                                        |

|          ]).                                                           |
|:- meta_predicate count_atom_results(-,0,-).                            |
|                                                                        |
|count_atom_results(A, Goal, Count) :-                                   |
|        setof(A, atom_result(A, Goal), As), !,                          |
|        length(As, Count).                                              |
|count_atom_results(_, _, 0).                                            |

|                                                                        |
|atom_result(Var, Goal) :-                                               |
|        call(Goal),                                                     |
||_______atom(Var)._____________________________________________________ ||

The following predicates support the module-transparent interface:


::-- mmoodduullee__ttrraannssppaarreenntt((_+_P_r_e_d_s))
    _P_r_e_d_s   is  a  comma-separated   list  of  name/arity  pairs   (like
    dynamic/1).     Each  goal associated  with  a  transparent-declared
    predicate will inherit the _c_o_n_t_e_x_t _m_o_d_u_l_e from its parent goal.


ccoonntteexxtt__mmoodduullee((_-_M_o_d_u_l_e))
    Unify   _M_o_d_u_l_e  with  the  context  module  of  the   current  goal.
    context_module/1 itself is, of course, transparent.


ssttrriipp__mmoodduullee((_+_T_e_r_m_, _-_M_o_d_u_l_e_, _-_P_l_a_i_n))
    Used in  module-transparent predicates or meta-predicates to extract
    the   referenced  module   and  plain   term.      If   _T_e_r_m  is   a
    module-qualified  term, i.e. of the format _M_o_d_u_l_e:_P_l_a_i_n,  _M_o_d_u_l_e and
    _P_l_a_i_n  are unified to these values.  Otherwise, _P_l_a_i_n is  unified to
    _T_e_r_m and _M_o_d_u_l_e to the context module.


66..1144 MMoodduullee pprrooppeerrttiieess

The following  predicates can  be used  to query the  module system  for
reflexive programming:


ccuurrrreenntt__mmoodduullee((_?_M_o_d_u_l_e))                                         _[_n_o_n_d_e_t_]
    True  if  _M_o_d_u_l_e is  a currently  defined module.    This  predicate
    enumerates  all  modules,  whether loaded  from  a file  or  created
    dynamically.   Note that modules cannot be destroyed in  the current
    version of SWI-Prolog.


mmoodduullee__pprrooppeerrttyy((_?_M_o_d_u_l_e_, _?_P_r_o_p_e_r_t_y))
    True if _P_r_o_p_e_r_t_y is a property of _M_o_d_u_l_e.  Defined properties are:

    ccllaassss((_-_C_l_a_s_s))
         True when _C_l_a_s_s  is the class of  the module.  Defined  classes
         are

         uusseerr
             Default for user-defined modules.

         ssyysstteemm
             Module system and modules from <_h_o_m_e>/boot.

         lliibbrraarryy
             Other modules from the system directories.

         tteemmppoorraarryy
             Module is temporary.

         tteesstt
             Modules that create tests.

         ddeevveellooppmmeenntt
             Modules that only support the development environment.

    ffiillee((_?_F_i_l_e))
         True if _M_o_d_u_l_e was loaded from _F_i_l_e.

    lliinnee__ccoouunntt((_-_L_i_n_e))
         True if _M_o_d_u_l_e was loaded from the N-th line of file.

    eexxppoorrttss((_-_L_i_s_t_O_f_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_s))
         True  if  _M_o_d_u_l_e exports  the  given  predicates.     Predicate
         indicators  are   in  canonical   form  (i.e.,   always   using
         name/arity  and  never the  DCG  form  name//arity).     Future
         versions  may  also  use  the  DCG  form   and  include  public
         operators.  See also predicate_property/2.

    eexxppoorrtteedd__ooppeerraattoorrss((_-_L_i_s_t_O_f_O_p_e_r_a_t_o_r_s))
         True if  _M_o_d_u_l_e exports  the given  operators.   Each  exported
         operator is represented as a term op(_P_r_i_,_A_s_s_o_c_,_N_a_m_e).

    pprrooggrraamm__ssiizzee((_-_B_y_t_e_s))
         Memory  (in bytes)  used for  storing  the predicates  of  this
         module.     This  figure  includes  the  predicate  header  and
         clauses.   Future versions  might give  a more precise  number,
         including e.g., the clause index tables.

    pprrooggrraamm__ssppaaccee((_-_B_y_t_e_s))
         If  present,  this  number   limits  the  program_size.      See
         set_module/1.

    llaasstt__mmooddiiffiieedd__ggeenneerraattiioonn((_-_G_e_n_e_r_a_t_i_o_n))
         Integer expression the last database generation where  a clause
         was added or  removed from a  predicate that is implemented  in
         this module.  See also predicate_property/2.


sseett__mmoodduullee((_:_P_r_o_p_e_r_t_y))
    Modify  properties  of  the  module.     Currently,   the  following
    properties may be modified:

    bbaassee((_+_B_a_s_e))
         Set the default import module of the current  module to _M_o_d_u_l_e.
         Typically, _M_o_d_u_l_e is one of user or system.  See section ????.

    ccllaassss((_+_C_l_a_s_s))
         Set the class of the module.  See module_property/2.

    pprrooggrraamm__ssppaaccee((_+_B_y_t_e_s))
         Maximum amount of memory  used to store the predicates  defined
         inside  the  module.     Raises  a  permission   error  if  the
         current  usage is  above  the requested  limit.    Setting  the
         limit  to  0  (zero)  removes  the  limit.      An  attempt  to
         assert clauses  that causes  the  limit to  be exceeded  causes
         a resource_error(_p_r_o_g_r_a_m___s_p_a_c_e)  exception.   See assertz/1  and
         module_property/2.


66..1155 CCoommppaattiibbiilliittyy ooff tthhee MMoodduullee SSyysstteemm

The  SWI-Prolog  module  system is  largely  derived  from  the  Quintus
Prolog module system,  which is also adopted  by SICStus, Ciao and  YAP.
Originally,  the mechanism  for defining  meta-predicates in  SWI-Prolog
was  based on  the  module_transparent/1 directive  and  strip_module/3.
Since  5.7.4   it  supports   the  de-facto   standard  meta_predicate/1
directive  for  implementing  meta-predicates,   providing  much  better
compatibility.

The   support  for   the   meta_predicate/1  mechanism,    however,   is
considerably  different.       On  most   systems,  the   _c_a_l_l_e_r  of   a
meta-predicate  is   compiled  differently   to  provide  the   required
<_m_o_d_u_l_e>:<_t_e_r_m> qualification.   This  implies that  the meta-declaration
must  be available  to the  compiler when  compiling code  that calls  a
meta-predicate.  In  practice, this implies that other systems  pose the
following restrictions on meta-predicates:

  o Modules  that provide  meta-predicates for a  module to be  compiled
    must be loaded explicitly by that module.

  o The  meta-predicate directives  of exported  predicates must  follow
    the module/2 directive immediately.

  o After  changing  a  meta-declaration,  all  modules  that  _c_a_l_l  the
    modified predicates need to be recompiled.

In  SWI-Prolog,   meta-predicates  are   also  _m_o_d_u_l_e_-_t_r_a_n_s_p_a_r_e_n_t,   and
qualifying  the module-sensitive  arguments  is  done inside  the  meta-
predicate.    As a  result, the  caller need  not  be aware  that it  is
calling a  meta-predicate and none  of the  above restrictions hold  for
SWI-Prolog.  However, code that aims at portability  must obey the above
rules.

Other differences are listed below.

  o If  a module does not define a predicate, it is searched for  in the
    _i_m_p_o_r_t  _m_o_d_u_l_e_s.  By default, the import module of  any user-defined
    module  is the user module.   In turn, the user module  imports from
    the  module  system that  provides  all built-in  predicates.    The
    auto-import  hierarchy can be changed  using add_import_module/3 and
    delete_import_module/2.

    This  mechanism  can be  used to  realise  a simple  object-oriented
    system or a hierarchical module system.

  o Operator  declarations are local  to a module  and may be  exported.
    In  Quintus and  SICStus all  operators are global.    YAP and  Ciao
    also  use  local operators.    SWI-Prolog  provides global  operator
    declarations  from  within a  module  by explicitly  qualifying  the
    operator  name with the user module.  I.e., operators  are inherited
    from the _i_m_p_o_r_t _m_o_d_u_l_e_s (see above).

    ____________________________________________________________________|                                                                    |
    ||:-_op(precedence,_type,_user:(operatorname))._____________________ ||


CChhaapptteerr 77..  CCOONNSSTTRRAAIINNTT LLOOGGIICC PPRROOGGRRAAMMMMIINNGG

This   chapter   describes  the   extensions   primarily   designed   to
support  ccoonnssttrraaiinntt llooggiicc  pprrooggrraammmmiinngg (CLP),  an important  declarative
programming paradigm with countless practical applications.

CLP(X)  stands for  constraint logic  programming  over the  domain X.
Plain  Prolog  can   be  regarded  as  CLP(H),   where  H  stands   for
_H_e_r_b_r_a_n_d _t_e_r_m_s.  Over this domain, =/2 and dif/2  are the most important
constraints  that  express,   respectively,  equality   and  disequality
of terms.  Plain Prolog can thus be regarded as a special case of CLP.

There are dedicated constraint solvers for several important domains:

  o CLP(FD) for iinntteeggeerrss (section ????)

  o CLP(B) for BBoooolleeaann variables (section ????)

  o CLP(Q) for rraattiioonnaall numbers (section ????)

  o CLP(R) for ffllooaattiinngg ppooiinntt numbers (section ????).

In  addition, CHR  (chapter ????)  provides a  general purpose  constraint
handling language to reason over user-defined constraints.

Constraints blend in naturally into Prolog programs,  and behave exactly
like plain Prolog predicates  in those cases that can also  be expressed
without constraints.   However,  there are  two key differences  between
constraints and plain Prolog predicates:

  o Constraints  can  _d_e_l_a_y  checks  until their  truth  can  be  safely
    decided.   This feature can significantly increase the _g_e_n_e_r_a_l_i_t_y of
    your programs, and preserves their relational nature.

  o Constraints  can  take  into  account  everything  you  state  about
    the  entities  you  reason  about,   independent  of  the  order  in
    which  you state  it, both  _b_e_f_o_r_e and  also _d_u_r_i_n_g  any search  for
    concrete  solutions.   Using  available information  to prune  parts
    of  the search  space is  called constraint _p_r_o_p_a_g_a_t_i_o_n,  and it  is
    performed  automatically  by the  available constraint  solvers  for
    their  respective domains.  This feature can  significantly increase
    the _p_e_r_f_o_r_m_a_n_c_e of your programs.

Due to  these two key  advantages over plain Prolog,  CLP has become  an
extremely important declarative programming paradigm in practice.

Among its  most important and typical  instances is CLP(FD),  constraint
logic programming  over _i_n_t_e_g_e_r_s.   For example, using constraints,  you
can  state in  the most  general way  that a  variable _X  is an  integer
greater than  0.   If,  later, _X  is bound  to a  concrete integer,  the
constraint  solver automatically  ensures  this.    If you  in  addition
constrain _X to integers less than 3, the  constraint solver combines the
existing knowledge to  infer that _X is  either 1 or 2  (see below).   To
obtain concrete  values for _X,  you can  ask the solver  to _l_a_b_e_l _X  and
produce 1 and 2 on backtracking.  See section ????.

________________________________________________________________________|                                                                        |
|?- use_module(library(clpfd)).                                          |

|...                                                                     |
|true.                                                                   |
|                                                                        |
|?- X #> 0, X #< 3.                                                      |
|X in 1..2.                                                              |
|                                                                        |
|?- X #> 0, X #< 3, indomain(X).                                         |
|X = 1 ;                                                                 |

|X|=_2._________________________________________________________________ | |

Contrast this with  plain Prolog, which has  no efficient means to  deal
with (integer)  X> 0 and X < 3.   At best it could  translate X >0 to
between(_1_,  _i_n_f_i_n_i_t_e_, _X)  and a similar  primitive for  X <3.    If the
two are  combined it has no  choice but to  generate and test over  this
infinite two-dimensional space.

Using constraints therefore makes your program more  _d_e_c_l_a_r_a_t_i_v_e in that
it frees you from some procedural aspects and limitations of Prolog.

When working with constraints, keep in mind the following:

  o As  with plain Prolog, !/0  also destroys the declarative  semantics
    of  constraints.      A  cut  after  a  goal  that  is  delayed  may
    prematurely  prune the search  space, because  the truth of  delayed
    goals  is not  yet established.   There  are several  ways to  avoid
    cuts  in constraint  logic programs,  retaining both generality  and
    determinism of your programs.  See for example zcompare/3.

  o Term-copying    operations   (assertz/1,    retract/1,    findall/3,
    copy_term/2,  etc.)      generally  also  copy  constraints.     The
    effect  varies from ok, silent  copying of huge constraint  networks
    to  violations of the  internal consistency of constraint  networks.
    As  a  rule  of thumb,  copying  terms  holding attributes  must  be
    deprecated.   If you  need to reason about  a term that is  involved
    in constraints,  use copy_term/3to obtain  the constraints as Prolog
    goals, and use these goals for further processing.

All  of the  mentioned  constraint  solvers are  implemented  using  the
attributed  variables interface  described in  section ????.    These  are
lower-level predicates  that are  mainly intended  for library  authors,
not for typical Prolog programmers.


77..11 AAttttrriibbuutteedd vvaarriiaabblleess

_A_t_t_r_i_b_u_t_e_d  _v_a_r_i_a_b_l_e_s  provide  a technique  for  extending  the  Prolog
unification  algorithm  [??]   by  hooking  the  binding  of   attributed
variables.    There  is no  consensus in  the  Prolog community  on  the
exact definition and interface to attributed variables.   The SWI-Prolog
interface is identical  to the one realised  by Bart Demoen for  hProlog
[??].   This  interface is  simple and  available on  all Prolog  systems
that  can run  the Leuven  CHR system  (see chapter  ????  and the  Leuven
https://dtai.cs.kuleuven.be/CHR/CHR page).

Binding  an attributed  variable  schedules a  goal  to be  executed  at
the  first possible  opportunity.   In  the  current implementation  the
hooks are  executed immediately  after a successful  unification of  the
clause-head or  successful completion of  a foreign language  (built-in)
predicate.   Each  attribute is  associated to  a module,  and the  hook
(attr_unify_hook/2)  is  executed in  this  module.   The  example  below
realises a very simple and incomplete finite domain reasoner:

________________________________________________________________________|                                                                        |
|:- module(domain,                                                       |

|          [ domain/2                    % Var, ?Domain                  |
|          ]).                                                           |
|:- use_module(library(ordsets)).                                        |
|                                                                        |
|domain(X, Dom) :-                                                       |
|        var(Dom), !,                                                    |
|        get_attr(X, domain, Dom).                                       |
|domain(X, List) :-                                                      |

|        list_to_ord_set(List, Domain),                                  |
|        put_attr(Y, domain, Domain),                                    |
|        X = Y.                                                          |
|                                                                        |
|%       An attributed variable with attribute value Domain has been     |
|%       assigned the value Y                                            |
|                                                                        |

|attr_unify_hook(Domain, Y) :-                                           |
|        (   get_attr(Y, domain, Dom2)                                   |
|        ->  ord_intersection(Domain, Dom2, NewDomain),                  |
|            (   NewDomain == []                                         |
|            ->  fail                                                    |
|            ;   NewDomain = [Value]                                     |
|            ->  Y = Value                                               |
|            ;   put_attr(Y, domain, NewDomain)                          |

|            )                                                           |
|        ;   var(Y)                                                      |
|        ->  put_attr( Y, domain, Domain )                               |
|        ;   ord_memberchk(Y, Domain)                                    |
|        ).                                                              |
|                                                                        |
|%       Translate attributes from this module to residual goals         |

|                                                                        |
|attribute_goals(X) -->                                                  |
|        { get_attr(X, domain, List) },                                  |
||_______[domain(X,_List)]._____________________________________________ ||

Before explaining the code we give some example queries:

     ?- domain(X, [a,b]), X = c                fail
     ?- domain(X, [a,b]), domain(X, [a,c]).    X = a
     ?- domain(X, [a,b,c]), domain(X, [a,c]).  domain(X, [a, c])

The  predicate  domain/2  fetches  (first  clause)  or  assigns  (second
clause) the  variable a  _d_o_m_a_i_n, a  set of  values the  variable can  be
unified  with.   In  the second  clause, domain/2  first associates  the
domain with a fresh variable (Y) and then unifies X  to this variable to
deal with the  possibility that X already has  a domain.  The  predicate
attr_unify_hook/2 (see below) is a hook  called after a variable with  a
domain is assigned  a value.  In  the simple case where the variable  is
bound to a concrete value, we simply check whether this  value is in the
domain.   Otherwise we take the  intersection of the domains and  either
fail if the intersection  is empty (first example), assign the  value if
there is only one value in the intersection (second  example), or assign
the intersection  as the  new domain  of the  variable (third  example).
The  nonterminal  attribute_goals//1  is  used  to  translate  remaining
attributes to  user-readable goals  that, when  called, reinstate  these
attributes or attributes that correspond to equivalent constraints.

Implementing constraint  solvers (chapter  ????) is the  most common,  but
not  the only  use case  for  attributed variables:   If  you  implement
algorithms that require efficient destructive modifications,  then using
attributed  variables is  often  a  more convenient  and  somewhat  more
declarative  alternative  for  setarg/3  and  related  predicates  whose
sharing semantics are harder  to understand.  In particular,  attributed
variables  make it  easy to  express graph  networks and  graph-oriented
algorithms, since each variable can store pointers  to further variables
in its  attributes.   In  such cases,  the use  of attributed  variables
should be  confined within a module  that exposes its functionality  via
more declarative interface predicates.


77..11..11 AAttttrriibbuuttee mmaanniippuullaattiioonn pprreeddiiccaatteess


aattttvvaarr((_@_T_e_r_m))
    Succeeds  if _T_e_r_m is an attributed  variable.  Note that var/1  also
    succeeds on attributed  variables.  Attributed variables are created
    with put_attr/3.


ppuutt__aattttrr((_+_V_a_r_, _+_M_o_d_u_l_e_, _+_V_a_l_u_e))
    If  _V_a_r is  a variable  or attributed  variable, set  the value  for
    the  attribute named _M_o_d_u_l_e  to _V_a_l_u_e.   If  an attribute with  this
    name  is already  associated with  _V_a_r, the old  value is  replaced.
    Backtracking  will  restore the  old value  (i.e.,  an attribute  is
    a  mutable  term; see  also setarg/3).    This  predicate raises  an
    uninstantiation error if _V_a_r  is not a variable, and a type error if
    _M_o_d_u_l_e is not an atom.


ggeett__aattttrr((_+_V_a_r_, _+_M_o_d_u_l_e_, _-_V_a_l_u_e))
    Request  the  current _v_a_l_u_e  for the  attribute named  _M_o_d_u_l_e.    If
    _V_a_r  is not  an attributed variable  or the  named attribute is  not
    associated  to _V_a_r this predicate fails silently.  If _M_o_d_u_l_e  is not
    an atom, a type error is raised.


ddeell__aattttrr((_+_V_a_r_, _+_M_o_d_u_l_e))
    Delete  the named attribute.    If _V_a_r loses  its last attribute  it
    is  transformed back into a traditional Prolog variable.   If _M_o_d_u_l_e
    is  not an atom, a  type error is raised.   In all other cases  this
    predicate succeeds regardless  of whether or not the named attribute
    is present.


77..11..22 AAttttrriibbuutteedd vvaarriiaabbllee hhooookkss

Attribute  names  are linked  to  modules.    This  means  that  certain
operations  on attributed  variables cause  _h_o_o_k_s to  be  called in  the
module whose name matches the attribute name.


aattttrr__uunniiffyy__hhooookk((_+_A_t_t_V_a_l_u_e_, _+_V_a_r_V_a_l_u_e))
    A  hook that must  be defined in the  module to which an  attributed
    variable  refers.   It is called  _a_f_t_e_r the attributed variable  has
    been  unified  with  a non-var  term,  possibly  another  attributed
    variable.    _A_t_t_V_a_l_u_e is the  attribute that  was associated to  the
    variable  in  this module  and  _V_a_r_V_a_l_u_e is  the  new value  of  the
    variable.    If this  predicate fails,  the unification fails.    If
    _V_a_r_V_a_l_u_e is another  attributed variable the hook often combines the
    two  attributes and associates the combined attribute  with _V_a_r_V_a_l_u_e
    using put_attr/3.

         TToo bbee ddoonnee The  way  in  which this  hook  currently works
             makes   the   implementation   of  important   classes
             of   constraint   solvers  impossible   or   at  least
             extremely  impractical.     For  increased  generality
             and  convenience,   simultaneous  unifications  as  in
             [X,Y]=[0,1]  should be  processed sequentially  by the
             Prolog   engine,  or   a  more   general  hook  should
             be  provided  in  the  future.     See  [??]  for  more
             information.


aattttrriibbuuttee__ggooaallss((_+_V_a_r)) //
    This  nonterminal  is  the main  mechanism  in which  residual  con-
    straints  are obtained.    It  is called  in every  module where  it
    is  defined,  and  _V_a_r has  an  attribute.    Its argument  is  that
    variable.   In each module, attribute_goals//1 must describe  a list
    of Prolog goals  that are declaratively equivalent to the goals that
    caused  the attributes  of that module  to be  present and in  their
    current  state.    It is  always possible  to do  this (since  these
    attributes  stem from such goals),  and it is the responsibility  of
    constraint library authors  to provide this mapping without exposing
    any  library internals.   Ideally and typically, remaining  relevant
    attributes  are mapped  to  _p_u_r_e and  potentially simplified  Prolog
    goals that satisfy both of the following:

      o  They are declaratively equivalent to the constraints  that were
         originally posted.

      o  They  use only  predicates  that  are themselves  exported  and
         documented in the modules they stem from.

    The  latter property  ensures that users  can reason about  residual
    goals,  and see for themselves whether a constraint  library behaves
    correctly.     It  is  this  property  that  makes  it  possible  to
    thoroughly test  constraint solvers by contrasting obtained residual
    goals with expected answers.

    This  nonterminal is used  by copy_term/3, on  which the Prolog  top
    level relies to  ensure the basic invariant of pure Prolog programs:
    The answer is _d_e_c_l_a_r_a_t_i_v_e_l_y _e_q_u_i_v_a_l_e_n_t to the query.

    Note  that instead  of _d_e_f_a_u_l_t_y  representations, a  Prolog _l_i_s_t  is
    used  to represent residual goals.   This simplifies processing  and
    reasoning  about residual  goals throughout all  programs that  need
    this functionality.


pprroojjeecctt__aattttrriibbuutteess((_+_Q_u_e_r_y_V_a_r_s_, _+_R_e_s_i_d_u_a_l_V_a_r_s))
    A hook that can  be defined in each module to project constraints on
    newly  introduced variables back to the query variables.   _Q_u_e_r_y_V_a_r_s
    is  the list of  variables occurring in  the query and  _R_e_s_i_d_u_a_l_V_a_r_s
    is  a  list of  variables  that have  attributes  attached.    There
    may  be  variables   that  occur  in  both  lists.     If  possible,
    project_attributes/2  should  change  the  attributes  so  that  all
    constraints  are  expressed as  residual goals  that  refer only  to
    _Q_u_e_r_y_V_a_r_s, while other variables are existentially quantified.


aattttrr__ppoorrttrraayy__hhooookk((_+_A_t_t_V_a_l_u_e_, _+_V_a_r))                          _[_d_e_p_r_e_c_a_t_e_d_]
    Called  by  write_term/2  and  friends for  each  attribute  if  the
    option  attributes(_p_o_r_t_r_a_y) is  in  effect.   If  the hook  succeeds
    the  attribute is  considered printed.    Otherwise Module = ...  is
    printed to indicate the  existence of a variable.  This predicate is
    deprecated  because it  cannot work with  pure interface  predicates
    like  copy_term/3.   Use attribute_goals//1instead  to map attributes
    to residual goals.


77..11..33 OOppeerraattiioonnss oonn tteerrmmss wwiitthh aattttrriibbuutteedd vvaarriiaabblleess


ccooppyy__tteerrmm((_+_T_e_r_m_, _-_C_o_p_y_, _-_G_s))
    Create  a  regular  term  _C_o_p_y  as  a  copy  of  _T_e_r_m  (without  any
    attributes), and a  list _G_s of goals that represents the attributes.
    The  goal maplist(call, Gs) recreates the attributes for _C_o_p_y.   The
    nonterminal  attribute_goals//1,  as  defined  in  the  modules  the
    attributes  stem from,  is used  to convert attributes  to lists  of
    goals.

    This  building block  is used  by the  top level  to report  pending
    attributes  in  a   portable  and  understandable  fashion.     This
    predicate  is  the preferred  way to  reason  about and  communicate
    terms with constraints.

    The  form copy_term(Term, Term, Gs)  can be used to reason  about the
    constraints in which Term is involved.


ccooppyy__tteerrmm__nnaatt((_+_T_e_r_m_, _-_C_o_p_y))
    As  copy_term/2.   Attributes, however,  are _n_o_t copied but  replaced
    by fresh variables.


tteerrmm__aattttvvaarrss((_+_T_e_r_m_, _-_A_t_t_V_a_r_s))
    _A_t_t_V_a_r_s  is  a   list  of  all  attributed  variables  in  _T_e_r_m  and
    its   attributes.     That  is,   term_attvars/2  works  recursively
    through  attributes.    This  predicate is  cycle-safe.    The  goal
    term_attvars(_T_e_r_m_,  _[_])  in  an  efficient test  that  _T_e_r_m  has  _n_o
    attributes; scanning the  term is aborted after the first attributed
    variable is found.


77..11..44 SSppeecciiaall ppuurrppoossee pprreeddiiccaatteess ffoorr aattttrriibbuutteess

Normal user code should deal with put_attr/3, get_attr/3 and del_attr/2.
The routines in this  section fetch or set the entire attribute  list of
a variable.  Use of these predicates is anticipated  to be restricted to
printing and other special purpose operations.


ggeett__aattttrrss((_+_V_a_r_, _-_A_t_t_r_i_b_u_t_e_s))
    Get  all  attributes of  _V_a_r.   _A_t_t_r_i_b_u_t_e_s  is a  term  of the  form
    att(_M_o_d_u_l_e_,  _V_a_l_u_e_, _M_o_r_e_A_t_t_r_i_b_u_t_e_s), where _M_o_r_e_A_t_t_r_i_b_u_t_e_s is  [] for
    the last attribute.


ppuutt__aattttrrss((_+_V_a_r_, _-_A_t_t_r_i_b_u_t_e_s))
    Set  all attributes of  _V_a_r.  See  get_attrs/2 for a description  of
    _A_t_t_r_i_b_u_t_e_s.


ddeell__aattttrrss((_+_V_a_r))
    If  _V_a_r is an attributed  variable, delete _a_l_l  its attributes.   In
    all other cases, this predicate succeeds without side-effects.


77..22 CCoorroouuttiinniinngg

Coroutining  allows us  to delay  the execution  of  Prolog goals  until
their truth can be safely decided.

Among  the  most  important  coroutining  predicates  is  dif/2,   which
expresses _d_i_s_e_q_u_a_l_i_t_y  of terms  in a  sound way.   The  actual test  is
delayed  until the  terms are  sufficiently  different, or  have  become
identical.  For example:

________________________________________________________________________|                                                                        |
|?- dif(X, Y), X = a, Y = b.                                             |

|X = a,                                                                  |
|Y = b.                                                                  |
|                                                                        |
|?- dif(X, Y), X = a, Y = a.                                             |
|false.|________________________________________________________________ |      |

There are also  lower-level coroutining predicates that are intended  as
building blocks for higher-level  constraints.  For example, we  can use
freeze/2 to define a variable that can only be assigned an atom:

________________________________________________________________________|                                                                        |
|?- freeze(X, atom(X)), X = a.                                           |

|X|=_a._________________________________________________________________ | |

In this case, calling atom/1 earlier causes the whole query to fail:

________________________________________________________________________|                                                                        |
|?- atom(X), X = a.                                                      |
|false.|________________________________________________________________ |      |

If available, domain-specific constraints should be used  in such cases.
For example,  to state that  a variable can  only assume even  integers,
use the CLP(FD) constraint #=/2:

________________________________________________________________________|                                                                        |
|?- X mod 2 #= 0.                                                        |
|X|mod_2#=0.____________________________________________________________ | |

Importantly, domain-specific constraints can apply  stronger propagation
by  exploiting logical  properties of  their respective  domains.    For
example:

________________________________________________________________________|                                                                        |

|?- X mod 2 #= 0, X in 1..3.                                             |
|X|=_2._________________________________________________________________ | |

Remaining constraints,  such  as X mod 2#=0  in the  example above,  are
called _r_e_s_i_d_u_a_l goals.   They are said to _f_l_o_u_n_d_e_r, because  their truth
is  not yet  decided.   Declaratively,  the query  is only  true if  all
residual goals are satisfiable.   Use call_residue_vars/2to  collect all
variables that are involved in constraints.


ddiiff((_@_A_, _@_B))
    The  dif/2 predicate is  a _c_o_n_s_t_r_a_i_n_t  that is true  if and only  if
    _A  and _B are  different terms.   If _A and _B  can never unify,  dif/2
    succeeds  deterministically.   If _A  and _B are  identical, it  fails
    immediately.  Finally,  if _A and _B can unify, goals are delayed that
    prevent  _A and _B  to become equal.   It is  this last property  that
    makes  dif/2 a  more general  and more  declarative alternative  for
    \=/2 and related predicates.

    This    predicate   behaves   as   if   defined    by   dif(X, Y) :-
    when(?=(X,Y), X \== Y).   See  also  ?=/2.      The   implementation
    can deal with cyclic terms.

    The   dif/2  predicate  is   realised  using  attributed   variables
    associated with the module  dif.  It is an autoloaded predicate that
    is defined in the library dif.


ffrreeeezzee((_+_V_a_r_, _:_G_o_a_l))
    Delay  the execution  of  _G_o_a_l until  _V_a_r is  bound (i.e.  is not  a
    variable  or  attributed  variable).    If  _V_a_r is  bound  on  entry
    freeze/2  is  equivalent  to call/1.     The freeze/2  predicate  is
    realised  using an  attributed variable associated  with the  module
    freeze.   Use frozen(Var, Goal) to find out whether and  which goals
    are delayed on _V_a_r.


ffrroozzeenn((_@_V_a_r_, _-_G_o_a_l))
    Unify  _G_o_a_l with the  goal or conjunction  of goals delayed on  _V_a_r.
    If no goals are frozen on _V_a_r, _G_o_a_l is unified to true.


wwhheenn((_@_C_o_n_d_i_t_i_o_n_, _:_G_o_a_l))
    Execute  _G_o_a_l when  _C_o_n_d_i_t_i_o_n becomes  true.   _C_o_n_d_i_t_i_o_n  is one  of
    ?=(_X_, _Y), nonvar(_X), ground(_X),  ,(_C_o_n_d_1_, _C_o_n_d_2) or ;(_C_o_n_d_1_, _C_o_n_d_2).
    See  also freeze/2  and dif/2.    The implementation  can deal  with
    cyclic terms in _X and _Y.

    The   when/2  predicate  is  realised  using   attributed  variables
    associated  with the module  when.   It is  defined in the  autoload
    library when.


ccaallll__rreessiidduuee__vvaarrss((_:_G_o_a_l_, _-_V_a_r_s))
    Find  residual attributed variables  left by _G_o_a_l.   This  predicate
    is  intended  for   reasoning  about  and  debugging  programs  that
    use  coroutining  or  constraints.     To  see  why  this  predicate
    is   necessary,  consider  a  predicate  that   poses  contradicting
    constraints  on  a  variable,  and  where  that  variable  does  not
    appear  in  any  argument  of  the  predicate  and  hence  does  not
    yield  any residual  goals  on the  toplevel when  the predicate  is
    invoked.   Such programs should fail, but sometimes  succeed because
    the  constraint  solver is  too weak  to  detect the  contradiction.
    Ideally,  delayed  goals and  constraints are  all  executed at  the
    end  of  the computation.    The meta  predicate call_residue_vars/2
    finds  variables that are given  attributes or whose attributes  are
    modified  by _G_o_a_l, regardless of whether or not these  variables are
    reachable from the arguments of _G_o_a_l..


CChhaapptteerr 88..  CCHHRR:: CCOONNSSTTRRAAIINNTT HHAANNDDLLIINNGG RRUULLEESS

This chapter is written by Tom Schrijvers, K.U.  Leuven, and adjustments
by Jan Wielemaker.

The CHR system of SWI-Prolog is the _K_._U_._L_e_u_v_e_n _C_H_R _s_y_s_t_e_m.   The runtime
environment is  written by Christian Holzbaur  and Tom Schrijvers  while
the compiler  is written by  Tom Schrijvers.   Both are integrated  with
SWI-Prolog  and licensed  under  compatible conditions  with  permission
from the authors.

The main reference for the K.U.Leuven CHR system is:

  o T.   Schrijvers,  and   B.  Demoen,   _T_h_e  _K_._U_._L_e_u_v_e_n  _C_H_R   _S_y_s_t_e_m_:
    _I_m_p_l_e_m_e_n_t_a_t_i_o_n   _a_n_d  _A_p_p_l_i_c_a_t_i_o_n,  First  Workshop   on  Constraint
    Handling Rules:   Selected Contributions (Fr"uhwirth, T. and Meister,
    M., eds.), pp.  1--5, 2004.

On the K.U.Leuven CHR website (http://dtai.cs.kuleuven.be/CHR/)  you can
find more related papers, references and example programs.


88..11 IInnttrroodduuccttiioonn

Constraint  Handling  Rules  (CHR)  is  a   committed-choice  rule-based
language embedded  in Prolog.    It is designed  for writing  constraint
solvers and  is particularly  useful for providing  application-specific
constraints.   It  has been  used in  many kinds  of applications,  like
scheduling,  model checking, abduction,  and type  checking, among  many
others.

CHR has  previously been implemented in  other Prolog systems  (SICStus,
Eclipse,  Yap), Haskell  and Java.    This CHR  system is  based on  the
compilation scheme and runtime environment of CHR in SICStus.

In this documentation  we restrict ourselves to giving a  short overview
of  CHR  in general  and  mainly  focus  on elements  specific  to  this
implementation.  For  a more thorough review of CHR we refer  the reader
to [??].  More background on CHR can be found at [??].

In  section ????  we  present the  syntax of  CHR  in Prolog  and  explain
informally  its operational  semantics.   Next,  section  ???? deals  with
practical issues  of writing  and compiling  Prolog programs  containing
CHR.  Section  ????  explains  the  (currently  primitive)  CHR  debugging
facilities.   Section  ???? provides  a few useful  predicates to  inspect
the constraint  store, and section ????  illustrates CHR with two  example
programs.   Section ????  describes some  compatibility issues with  older
versions of this  system and SICStus' CHR  system.  Finally, section  ????
concludes with a few practical guidelines for using CHR.


88..22 SSyynnttaaxx aanndd SSeemmaannttiiccss


88..22..11 SSyynnttaaxx ooff CCHHRR rruulleess

________________________________________________________________________________________________________________________________________________||                                                                        ||
||rules --> rule, rules ; [].                                             |
|                                                                        |
|rule --> name, actual_rule, pragma, [atom('.')].                        |

|                                                                        |
|name --> atom, [atom('@')] ; [].                                        |
|                                                                        |
|actual_rule --> simplification_rule.                                    |
|actual_rule --> propagation_rule.                                       |
|actual_rule --> simpagation_rule.                                       |
|                                                                        |
|simplification_rule --> head, [atom('<=>')], guard, body.               |

|propagation_rule --> head, [atom('==>')], guard, body.                  |
|simpagation_rule --> head, [atom('\')], head, [atom('<=>')],            |
|                     guard, body.                                       |
|                                                                        |
|head --> constraints.                                                   |
|                                                                        |
|constraints --> constraint, constraint_id.                              |

|constraints --> constraint, constraint_id,                              |
|                [atom(',')], constraints.                               |
|                                                                        |
|constraint --> compound_term.                                           |
|                                                                        |
|constraint_id --> [].                                                   |
|constraint_id --> [atom('#')], variable.                                |
|constraint_id --> [atom('#')], [atom('passive')] .                      |

|                                                                        |
|guard --> [] ; goal, [atom('|')].                                       |
|                                                                        |
|body --> goal.                                                          |
|                                                                        |
|pragma --> [].                                                          |
|pragma --> [atom('pragma')], actual_pragmas.                            |

|                                                                        |
|actual_pragmas --> actual_pragma.                                       |
|actual_pragmas --> actual_pragma, [atom(',')], actual_pragmas.          |
|                                                                        |
|actual_pragma|-->_[atom('passive(')],_variable,_[atom(')')].___________ |             |

Note that  the guard of  a rule may  not contain any  goal that binds  a
variable in  the head of  the rule with a  non-variable or with  another
variable in  the head  of the  rule.   It may,  however, bind  variables
that do not appear  in the head of the rule, e.g. an  auxiliary variable
introduced in the guard.


88..22..22 SSeemmaannttiiccss

In  this subsection  the  operational semantics  of  CHR in  Prolog  are
presented informally.   They  do not differ  essentially from other  CHR
systems.

When a constraint is  called, it is considered an active  constraint and
the system  will try  to apply the  rules to it.    Rules are tried  and
executed sequentially in the order they are written.

A rule is conceptually  tried for an active constraint in  the following
way.  The active constraint is matched with a constraint  in the head of
the rule.  If  more constraints appear in the head, they are  looked for
among the  suspended constraints, which  are called passive  constraints
in this context.  If the necessary passive constraints  can be found and
all match with the head of the rule and the guard  of the rule succeeds,
then the rule  is committed and the body of  the rule executed.   If not
all the  necessary passive  constraints can  be found,  or the  matching
or the  guard fails, then the  body is not  executed and the process  of
trying and  executing simply  continues with  the following rules.    If
for  a rule  there are  multiple  constraints in  the head,  the  active
constraint  will try  the rule  sequentially multiple  times, each  time
trying to match with another constraint.

This process ends either when the active constraint  disappears, i.e. it
is removed by some rule, or after the last rule has  been processed.  In
the latter case the active constraint becomes suspended.

A  suspended constraint  is  eligible as  a  passive constraint  for  an
active constraint.   The other way it may interact again with  the rules
is when a variable  appearing in the constraint becomes bound  to either
a non-variable or another variable involved in one  or more constraints.
In that  case the  constraint is triggered,  i.e. it  becomes an  active
constraint and all the rules are tried.

RRuullee  TTyyppeess There are  three different  kinds of  rules,  each with  its
specific semantics:

  o _s_i_m_p_l_i_f_i_c_a_t_i_o_n
    The  simplification rule  removes the  constraints in  its head  and
    calls its body.

  o _p_r_o_p_a_g_a_t_i_o_n
    The   propagation  rule  calls  its   body  exactly  once  for   the
    constraints in its head.

  o _s_i_m_p_a_g_a_t_i_o_n
    The  simpagation rule removes the constraints in its head  after the
    \ and then  calls its body.  It is an optimization of simplification
    rules of the form:

                  constraints1;constraints2<=> constraints1;body

    Namely, in the simpagation form:

                       constraints1\constraints2<=> body
    The constraints1constraints are not called in the body.

RRuullee NNaammeess

Naming  a rule  is  optional and  has  no semantic  meaning.    It  only
functions as documentation for the programmer.

PPrraaggmmaass The semantics of the pragmas are:

ppaassssiivvee((_I_d_e_n_t_i_f_i_e_r))
    The  constraint in the  head of a rule  _I_d_e_n_t_i_f_i_e_r can only match  a
    passive  constraint in that  rule.   There is an abbreviated  syntax
    for this pragma.  Instead of:

    ____________________________________________________________________|                                                                    |

    ||________________...,_c_#_Id,_..._<=>_..._pragma_passive(Id)_______ ||

    you can also write

    ____________________________________________________________________|                                                                    |
    ||________________...,_c_#_passive,_..._<=>_..._____________________ ||

Additional pragmas may be released in the future.


::-- cchhrr__ooppttiioonn((_+_O_p_t_i_o_n_, _+_V_a_l_u_e))
    It  is  possible  to specify  options  that  apply to  all  the  CHR
    rules  in the module.   Options are specified  with the chr_option/2
    declaration:

    ____________________________________________________________________|                                                                    |
    ||:-_chr_option(Option,Value).______________________________________ ||

    and  may appear  in the  file anywhere after  the first  constraints
    declaration.

    Available options are:

    cchheecckk__gguuaarrdd__bbiinnddiinnggss
         This  option controls  whether  guards  should be  checked  for
         (illegal) variable bindings or  not.  Possible values  for this
         option are  on to  enable the checks,  and off  to disable  the
         checks.   If this option is on,  any guard fails when it  binds
         a variable  that appears in  the head of  the rule.   When  the
         option is  off (default),  the behaviour  of a  binding in  the
         guard is undefined.

    ooppttiimmiizzee
         This option  controls the  degree  of optimization.    Possible
         values are  full  to enable  all available  optimizations,  and
         off  (default) to  disable  all  optimizations.    The  default
         is derived  from the  SWI-Prolog flag optimise,  where true  is
         mapped to full.  Therefore the command line  option -O provides
         full CHR optimization.   If optimization is enabled,  debugging
         must be disabled.

    ddeebbuugg
         This option enables  or disables the  possibility to debug  the
         CHR code.    Possible values  are on (default)  and off.    See
         section ????  for more  details  on debugging.    The default  is
         derived  from the  Prolog  flag  generate_debug_info,  which  is
         true by  default.   See  -nodebug.   If  debugging is  enabled,
         optimization must be disabled.


88..33 CCHHRR iinn SSWWII--PPrroolloogg PPrrooggrraammss


88..33..11 EEmmbbeeddddiinngg iinn PPrroolloogg PPrrooggrraammss

The CHR constraints defined in a .pl file are  associated with a module.
The default module is  user.  One should never load different  .pl files
with the same CHR module name.


88..33..22 CCoonnssttrraaiinntt ddeeccllaarraattiioonn


::-- cchhrr__ccoonnssttrraaiinntt((_+_S_p_e_c_i_f_i_e_r))
    Every  constraint  used in  CHR  rules has  to  be declared  with  a
    chr_constraint/1  declaration  by the  _c_o_n_s_t_r_a_i_n_t  _s_p_e_c_i_f_i_e_r.    For
    convenience  multiple constraints may be  declared at once with  the
    same  chr_constraint/1  declaration followed  by  a  comma-separated
    list of constraint specifiers.

    A  constraint specifier is,  in its compact form,  F/A where F  and
    A  are respectively the  functor name and arity  of the constraint,
    e.g.:

    ____________________________________________________________________|                                                                    |
    | :- chr_constraint foo/1.                                           |

    ||:-_chr_constraint_bar/2,_baz/3.___________________________________ ||

    In  its extended form, a constraint specifier is c(A1,...,An) where
    c  is the constraint's functor, n its arity and  the Aiare  argument
    specifiers.   An argument  specifier is a mode, optionally  followed
    by a type.  Example:

    ____________________________________________________________________|                                                                    |
    | :- chr_constraint get_value(+,?).                                  |
    | :- chr_constraint domain(?int, +list(int)),                        |
    ||__________________alldifferent(?list(int))._______________________ ||

MMooddeess

A mode is one of:

-
    The corresponding argument  of every occurrence of the constraint is
    always unbound.

+
    The corresponding argument  of every occurrence of the constraint is
    always ground.

?
    The  corresponding argument  of every occurrence  of the  constraint
    can  have any instantiation,  which may change over  time.  This  is
    the default value.

TTyyppeess

A type can be a user-defined type or one of the built-in  types.  A type
comprises a  (possibly infinite) set  of values.   The type  declaration
for  a  constraint  argument means  that  for  every  instance  of  that
constraint the  corresponding argument is only  ever bound to values  in
that set.   It does  not state that the  argument necessarily has to  be
bound to a value.

The built-in types are:

iinntt
    The corresponding argument  of every occurrence of the constraint is
    an integer number.

ddeennssee__iinntt
    The corresponding argument  of every occurrence of the constraint is
    an  integer that can be used as an  array index.  Note that  if this
    argument takes values in [0; n], the array takes O(n) space.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_T_y_p_e_D_e_c_l_a_r_a_t_i_o_n))
    User-defined  types are algebraic  data types,  similar to those  in
    Haskell  or the discriminated unions in Mercury.  An  algebraic data
    type is defined using chr_type/1:

    ____________________________________________________________________|                                                                    |
    ||:-_chr_type_type_--->_body._______________________________________ ||

    If  the type term is a functor  of arity zero (i.e. one  having zero
    arguments),  it names  a monomorphic type.   Otherwise,  it names  a
    polymorphic  type;  the arguments of  the functor  must be  distinct
    type  variables.     The body  term  is  defined as  a  sequence  of
    constructor definitions separated by semi-colons.

    Each  constructor  definition  must  be a  functor  whose  arguments
    (if  any)  are  types.    Discriminated  union definitions  must  be
    transparent:   all type  variables occurring in  the body must  also
    occur in the type.

    Here are some examples of algebraic data type definitions:

    ____________________________________________________________________|                                                                    |

    | :- chr_type color ---> red ; blue ; yellow ; green.                |
    |                                                                    |
    | :- chr_type tree --->  empty ; leaf(int) ; branch(tree, tree).     |
    |                                                                    |
    | :- chr_type list(T) ---> [] ; [T | list(T)].                       |
    |                                                                    |

    ||:-_chr_type_pair(T1,_T2)_--->_(T1_-_T2).__________________________ ||

    Each  algebraic data  type  definition introduces  a distinct  type.
    Two  algebraic data types that  have the same bodies are  considered
    to be distinct types (name equivalence).

    Constructors may be  overloaded among different types:  there may be
    any  number of constructors with a given name and arity, so  long as
    they all have different types.

    Aliases can be defined  using ==.  For example, if your program uses
    lists of lists of integers, you can define an alias as follows:

    ____________________________________________________________________|                                                                    |
    ||:-_chr_type_lli_==_list(list(int))._______________________________ ||

TTyyppee CChheecckkiinngg

Currently two complementary forms of type checking are performed:

 1. Static  type checking is  always performed by the  compiler.  It  is
    limited to CHR rule heads and CHR constraint calls in rule bodies.

    Two  kinds  of type  error  are detected.    The  first is  where  a
    variable has to belong to two types.  For example, in the program:

    ____________________________________________________________________|                                                                    |
    | :-chr_type foo ---> foo.                                           |
    | :-chr_type bar ---> bar.                                           |

    |                                                                    |
    | :-chr_constraint abc(?foo).                                        |
    | :-chr_constraint def(?bar).                                        |
    |                                                                    |
    ||foobar_@_abc(X)_<=>_def(X)._______________________________________ ||

    the  variable  X has  to be  of both  type foo  and bar.    This  is
    reported as a type clash error:

    ____________________________________________________________________|                                                                    |
    | CHR compiler ERROR:                                                |
    |     `--> Type clash for variable _ in rule foobar:                 |

    |                 expected type foo in body goal def(_, _)           |
    ||________________expected_type_bar_in_head_def(_,__)_______________ ||

    The  second kind of error is where  a functor is used that  does not
    belong to the declared type.  For example in:

    ____________________________________________________________________|                                                                    |
    | :- chr_type foo ---> foo.                                          |
    | :- chr_type bar ---> bar.                                          |
    |                                                                    |
    | :- chr_constraint abc(?foo).                                       |

    |                                                                    |
    ||foo_@_abc(bar)_<=>_true.__________________________________________ ||

    bar  appears in the head of the rule where something of type  foo is
    expected.  This is reported as:

    ____________________________________________________________________|                                                                    |
    | CHR compiler ERROR:                                                |
    |     `--> Invalid functor in head abc(bar) of rule foo:             |
    |                 found `bar',                                       |

    ||________________expected_type_`foo'!______________________________ ||

    No runtime overhead is incurred in static type checking.

 2. Dynamic  type checking checks at runtime, during  program execution,
    whether  the arguments  of  CHR constraints  respect their  declared
    types.   The  when/2 co-routining library  is used to delay  dynamic
    type checks until variables are instantiated.

    The  kind of  error detected  by dynamic  type checking  is where  a
    functor  is used that  does not belong  to the declared  type.   For
    example, for the program:

    ____________________________________________________________________|                                                                    |

    | :-chr_type foo ---> foo.                                           |
    |                                                                    |
    ||:-chr_constraint_abc(?foo)._______________________________________ ||

    we get the following error in an erroneous query:

    ____________________________________________________________________|                                                                    |
    | ?- abc(bar).                                                       |
    | ERROR: Type error: `foo' expected, found `bar'                     |
    ||_______(CHR_Runtime_Type_Error)___________________________________ ||

    Dynamic  type checking is  weaker than static  type checking in  the
    sense  that it only checks the particular program execution  at hand
    rather  than all possible executions.   It is stronger in the  sense
    that it tracks types throughout the whole program.

    Note  that it  is enabled  only in  debug  mode, as  it incurs  some
    (minor) runtime overhead.


88..33..33 CCoommppiillaattiioonn

The  SWI-Prolog   CHR  compiler   exploits  term_expansion/2  rules   to
translate the constraint  handling rules to plain  Prolog.  These  rules
are loaded  from the library chr.   They  are activated if the  compiled
file  has the  .chr extension  or  after finding  a declaration  in  the
following format:

________________________________________________________________________|                                                                        |
|:-|chr_constraint_...__________________________________________________ |  |

It is  advised to define CHR  rules in a  module file, where the  module
declaration  is  immediately  followed  by  including  the  library(chr)
library as exemplified below:

________________________________________________________________________|                                                                        |

|:- module(zebra, [ zebra/0 ]).                                          |
|:- use_module(library(chr)).                                            |
|                                                                        |
|:-|chr_constraint_...__________________________________________________ |  |

Using this style, CHR rules can be defined in  ordinary Prolog .pl files
and the operator  definitions required by CHR  do not leak into  modules
where they might cause conflicts.


88..44 DDeebbuuggggiinngg

The  CHR  debugging facilities  are  currently  rather limited.     Only
tracing is  currently available.   To use  the CHR debugging  facilities
for a  CHR file it  must be  compiled for debugging.   Generating  debug
info is  controlled by the  CHR option debug,  whose default is  derived
from the SWI-Prolog  flag generate_debug_info.   Therefore debug info  is
provided unless the -nodebug is used.


88..44..11 PPoorrttss

For CHR constraints the four standard ports are defined:

ccaallll
    A new constraint is called and becomes active.

eexxiitt
    An  active  constraint  exits:    it has  either  been  inserted  in
    the  store  after trying  all rules  or has  been  removed from  the
    constraint store.

ffaaiill
    An active constraint fails.

rreeddoo
    An active constraint starts looking for an alternative solution.

In addition  to the above  ports, CHR  constraints have five  additional
ports:

wwaakkee
    A suspended constraint is woken and becomes active.

iinnsseerrtt
    An  active constraint has  tried all rules  and is suspended in  the
    constraint store.

rreemmoovvee
    An  active  or passive  constraint is  removed  from the  constraint
    store.

ttrryy
    An  active  constraint  tries  a rule  with  possibly  some  passive
    constraints.  The  try port is entered just before committing to the
    rule.

aappppllyy
    An  active constraint commits to  a rule with possibly some  passive
    constraints.   The  apply port is  entered just after committing  to
    the rule.


88..44..22 TTrraacciinngg

Tracing is enabled with the chr_trace/0 predicate and disabled  with the
chr_notrace/0 predicate.

When enabled  the tracer will  step through the  call, exit, fail,  wake
and apply  ports, accepting  debug commands,  and simply  write out  the
other ports.

The following debug commands are currently supported:

        CHR debug options:

                <cr>    creep           c       creep
                s       skip
                g       ancestors
                n       nodebug
                b       break
                a       abort
                f       fail
                ?       help            h       help

Their meaning is:

ccrreeeepp
    Step to the next port.

sskkiipp
    Skip to exit port of this call or wake port.

aanncceessttoorrss
    Print list of ancestor call and wake ports.

nnooddeebbuugg
    Disable the tracer.

bbrreeaakk
    Enter a recursive Prolog top level.  See break/0.

aabboorrtt
    Exit to the top level.  See abort/0.

ffaaiill
    Insert failure in execution.

hheellpp
    Print the above available debug options.


88..44..33 CCHHRR DDeebbuuggggiinngg PPrreeddiiccaatteess

The chr  module contains  several predicates that  allow inspecting  and
printing the content of the constraint store.


cchhrr__ttrraaccee
    Activate  the CHR tracer.   By default  the CHR tracer is  activated
    and  deactivated automatically by the Prolog predicates  trace/0 and
    notrace/0.


cchhrr__nnoottrraaccee
    Deactivate  the CHR tracer.  By default the CHR tracer  is activated
    and  deactivated automatically by the Prolog predicates  trace/0 and
    notrace/0.


cchhrr__lleeaasshh((_+_S_p_e_c))
    Define  the set of CHR ports on  which the CHR tracer asks  for user
    intervention  (i.e. stops).    _S_p_e_c  is either  a list  of ports  as
    defined  in section  ???? or a  predefined `alias'.   Defined  aliases
    are:   full to  stop at all ports,  none or off  to never stop,  and
    default to stop at  the call, exit, fail, wake and apply ports.  See
    also leash/1.


cchhrr__sshhooww__ssttoorree((_+_M_o_d))
    Prints  all  suspended constraints  of module  _M_o_d  to the  standard
    output.   This predicate  is automatically called by the  SWI-Prolog
    top  level at the end of  each query for every CHR module  currently
    loaded.    The Prolog flag  chr_toplevel_show_store controls  whether
    the  top level shows the constraint stores.  The value  true enables
    it.  Any other value disables it.


ffiinndd__cchhrr__ccoonnssttrraaiinntt((_-_C_o_n_s_t_r_a_i_n_t))
    Returns  a constraint in  the constraint store.   Via  backtracking,
    all constraints in the store can be enumerated.


88..55 EExxaammpplleess

Here are two example constraint solvers written in CHR.

  o The  program below  defines a  solver with  one constraint,  leq/2/,
    which  is a less-than-or-equal constraint,  also known as a  partial
    order constraint.

    ____________________________________________________________________|                                                                    |
    | :- module(leq,[leq/2]).                                            |

    | :- use_module(library(chr)).                                       |
    |                                                                    |
    | :- chr_constraint leq/2.                                           |
    | reflexivity  @ leq(X,X) <=> true.                                  |
    | antisymmetry @ leq(X,Y), leq(Y,X) <=> X = Y.                       |
    | idempotence  @ leq(X,Y) \ leq(X,Y) <=> true.                       |
    ||transitivity_@_leq(X,Y),_leq(Y,Z)_==>_leq(X,Z).___________________ ||

    When the above program  is saved in a file and loaded in SWI-Prolog,
    you can call the leq/2 constraints in a query, e.g.:

    ____________________________________________________________________|                                                                    |

    | ?- leq(X,Y), leq(Y,Z).                                             |
    | leq(_G23837, _G23841)                                              |
    | leq(_G23838, _G23841)                                              |
    | leq(_G23837, _G23838)                                              |
    ||true_.____________________________________________________________ ||

    When  the  query  succeeds,  the  SWI-Prolog top  level  prints  the
    content  of  the  CHR constraint  store  and displays  the  bindings
    generated  during  the query.    Some  of  the query  variables  may
    have  been bound to  attributed variables, as  you see in the  above
    example.

  o The  program  below implements  a  simple finite  domain  constraint
    solver.

    ____________________________________________________________________|                                                                    |
    | :- module(dom,[dom/2]).                                            |

    | :- use_module(library(chr)).                                       |
    |                                                                    |
    | :- chr_constraint dom(?int,+list(int)).                            |
    | :- chr_type list(T) ---> [] ; [T|list(T)].                         |
    |                                                                    |
    | dom(X,[]) <=> fail.                                                |
    | dom(X,[Y]) <=> X = Y.                                              |
    | dom(X,L) <=> nonvar(X) | memberchk(X,L).                           |

    ||dom(X,L1),_dom(X,L2)_<=>_intersection(L1,L2,L3),_dom(X,L3)._______ ||

    When the above program  is saved in a file and loaded in SWI-Prolog,
    you can call the dom/2 constraints in a query, e.g.:

    ____________________________________________________________________|                                                                    |
    | ?- dom(A,[1,2,3]), dom(A,[3,4,5]).                                 |
    ||A_=_3.____________________________________________________________ ||


88..66 BBaacckkwwaarrddss CCoommppaattiibbiilliittyy


88..66..11 TThhee OOlldd SSIICCSSttuuss CCHHRR iimmpplleemmeennaattiioonn

There are  small differences between the  current K.U.Leuven CHR  system
in  SWI-Prolog, older  versions of  the same  system,  and SICStus'  CHR
system.

The  current  system maps  old  syntactic  elements onto  new  ones  and
ignores a number  of no longer required elements.   However, for each  a
_d_e_p_r_e_c_a_t_e_d warning  is issued.   You  are strongly  urged to replace  or
remove deprecated features.

Besides  differences in  available options  and pragmas,  the  following
differences should be noted:

  o _T_h_e constraints/1 _d_e_c_l_a_r_a_t_i_o_n
    This  declaration is  deprecated.   It  has been  replaced with  the
    chr_constraint/1 declaration.

  o _T_h_e option/2 _d_e_c_l_a_r_a_t_i_o_n
    This  declaration is  deprecated.   It  has been  replaced with  the
    chr_option/2 declaration.

  o _T_h_e handler/1 _d_e_c_l_a_r_a_t_i_o_n
    In  SICStus  every  CHR  module  requires  a  handler/1  declaration
    declaring  a unique handler name.  This declaration is  valid syntax
    in  SWI-Prolog, but will have  no effect.   A warning will be  given
    during compilation.

  o _T_h_e rules/1 _d_e_c_l_a_r_a_t_i_o_n
    In  SICStus, for every  CHR module it is  possible to only enable  a
    subset of the  available rules through the rules/1 declaration.  The
    declaration  is valid syntax in  SWI-Prolog, but has  no effect.   A
    warning is given during compilation.

  o _G_u_a_r_d _b_i_n_d_i_n_g_s
    The   check_guard_bindings  option   only  turns  invalid  calls   to
    unification  into failure.   In SICStus this  option does more:   it
    intercepts  instantiation errors from Prolog built-ins such  as is/2
    and turns them into  failure.  In SWI-Prolog, we do not go this far,
    as we like to  separate concerns more.  The CHR compiler is aware of
    the CHR code,  the Prolog system, and the programmer should be aware
    of  the appropriate meaning of the  Prolog goals used in guards  and
    bodies of CHR rules.


88..66..22 TThhee OOlldd EECCLLiiPPSSee CCHHRR iimmpplleemmeennaattiioonn

The old  ECLiPSe CHR  implementation features  a label_with/1  construct
for  labeling variables  in CHR  constraints.    This feature  has  long
since been abandoned.   However, a simple transformation is all  that is
required to port the functionality.

________________________________________________________________________|                                                                        |
|label_with Constraint1 if Condition1.                                   |
|...                                                                     |
|label_with ConstraintN if ConditionN.                                   |

|Constraint1 :- Body1.                                                   |
|...                                                                     |
|ConstraintN|:-_BodyN.__________________________________________________ |           |

is transformed into

________________________________________________________________________|                                                                        |
|:- chr_constraint my_labeling/0.                                        |

|                                                                        |
|my_labeling \ Constraint1 <=> Condition1 | Body1.                       |
|...                                                                     |
|my_labeling \ ConstraintN <=> ConditionN | BodyN.                       |
|my_labeling|<=>_true.__________________________________________________ |           |

Be sure to  put this code after all other  rules in your program!   With
my_labeling/0 (or another predicate name of your choosing)  the labeling
is initiated, rather than ECLiPSe's chr_labeling/0.


88..77 PPrrooggrraammmmiinngg TTiippss aanndd TTrriicckkss

In this section we  cover several guidelines on how to use CHR  to write
constraint solvers and how to do so efficiently.

  o _C_h_e_c_k _g_u_a_r_d _b_i_n_d_i_n_g_s _y_o_u_r_s_e_l_f
    It  is considered bad practice  to write guards that bind  variables
    of  the head and to  rely on the system  to detect this at  runtime.
    It is inefficient and obscures the working of the program.

  o _S_e_t _s_e_m_a_n_t_i_c_s
    The  CHR system allows the  presence of identical constraints,  i.e.
    multiple  constraints with  the same functor,  arity and  arguments.
    For  most constraint  solvers, this  is not desirable:   it  affects
    efficiency and possibly  termination.  Hence appropriate simpagation
    rules should be added of the form:

                         constraint\constraint <=>true

  o _M_u_l_t_i_-_h_e_a_d_e_d _r_u_l_e_s
    Multi-headed   rules  are   executed  more   efficiently  when   the
    constraints share one or more variables.

  o _M_o_d_e _a_n_d _t_y_p_e _d_e_c_l_a_r_a_t_i_o_n_s
    Provide  mode and  type declarations to  get more efficient  program
    execution.     Make sure  to  disable  debug (-nodebug)  and  enable
    optimization (-O).

  o _C_o_m_p_i_l_e _o_n_c_e_, _r_u_n _m_a_n_y _t_i_m_e_s
    Does  consulting your CHR  program take a  long time in  SWI-Prolog?
    Probably  it  takes the  CHR compiler  a long  time  to compile  the
    CHR  rules into  Prolog code.   When  you disable optimizations  the
    CHR  compiler will be a lot  quicker, but you may lose  performance.
    Alternatively, you  can just use SWI-Prolog's qcompile/1 to generate
    a  .qlf  file once  from your  .pl file.    This  .qlf contains  the
    generated  code of  the CHR  compiler (be  it in  a binary  format).
    When you consult the  .qlf file, the CHR compiler is not invoked and
    consultation is much faster.

  o _F_i_n_d_i_n_g _C_o_n_s_t_r_a_i_n_t_s
    The  find_chr_constraint/1 predicate  is fairly  expensive.    Avoid
    it,  if  possible.   If  you must  use it,  try  to use  it with  an
    instantiated top-level constraint symbol.


88..88 CCoommppiilleerr EErrrroorrss aanndd WWaarrnniinnggss

In  this section  we  summarize the  most  important error  and  warning
messages of the CHR compiler.


88..88..11 CCHHRR CCoommppiilleerr EErrrroorrss

TTyyppee ccllaasshh  for variable ...  in rule ...

    This  error indicates  an inconsistency  between declared  types;  a
    variable can not belong to two types.  See static type checking.

IInnvvaalliidd ffuunnccttoorr  in head ...  of rule ...

    This  error indicates an inconsistency  between a declared type  and
    the use of a functor in a rule.  See static type checking.

CCyycclliicc aalliiaass  definition:  ...  == ...

    You  have defined a type alias  in terms of itself, either  directly
    or indirectly.

AAmmbbiigguuoouuss ttyyppee aalliiaasseess  You have defined two overlapping type aliases.

MMuullttiippllee ddeeffiinniittiioonnss  for type

    You have defined the same type multiple times.

NNoonn--ggrroouunndd ttyyppee  in constraint definition:  ...

    You have declared a non-ground type for a constraint argument.

CCoouulldd nnoott ffiinndd ttyyppee ddeeffiinniittiioonn  for ...

    You have used an undefined type in a type declaration.

IIlllleeggaall mmooddee//ttyyppee ddeeccllaarraattiioonn  You  have  used   invalid  syntax  in   a
    constraint declaration.

CCoonnssttrraaiinntt mmuullttiippllyy ddeeffiinneedd  There is more than one declaration  for the
    same constraint.

UUnnddeeccllaarreedd ccoonnssttrraaiinntt  ...  in head of ...

    You have used an  undeclared constraint in the head of a rule.  This
    often  indicates a  misspelled constraint  name or  wrong number  of
    arguments.

IInnvvaalliidd pprraaggmmaa  ...  in ...  Pragma should not be a variable.

    You  have used  a variable  as a  pragma in  a rule.    This is  not
    allowed.

IInnvvaalliidd iiddeennttiiffiieerr  ...  in pragma passive in ...

    You  have  used an  identifier in  a passive  pragma  that does  not
    correspond  to an identifier in  the head of the  rule.  Likely  the
    identifier name is misspelled.

UUnnkknnoowwnn pprraaggmmaa  ...  in ...

    You  have used an unknown  pragma in a rule.   Likely the pragma  is
    misspelled or not supported.

SSoommeetthhiinngg uunneexxppeecctteedd  happened in the CHR compiler

    You have most likely  bumped into a bug in the CHR compiler.  Please
    contact Tom Schrijvers to notify him of this error.


CChhaapptteerr 99..  MMUULLTTIITTHHRREEAADDEEDD AAPPPPLLIICCAATTIIOONNSS

SWI-Prolog multithreading is  based on standard C language  multithread-
ing support.   It is not  like _P_a_r_L_o_g or other parallel  implementations
of the Prolog language.   Prolog threads have their own stacks  and only
share the  Prolog _h_e_a_p:   predicates,  records, flags  and other  global
non-backtrackable data.  SWI-Prolog thread support is  designed with the
following goals in mind.

  o _M_u_l_t_i_t_h_r_e_a_d_e_d _s_e_r_v_e_r _a_p_p_l_i_c_a_t_i_o_n_s
    Today's   computing  services  often  focus  on   (internet)  server
    applications.   Such applications often have need  for communication
    between  services  and/or  fast  non-blocking  service  to  multiple
    concurrent  clients.  The  shared heap provides fast  communication,
    and thread creation is relatively cheap.

  o _I_n_t_e_r_a_c_t_i_v_e _a_p_p_l_i_c_a_t_i_o_n_s
    Interactive   applications   often   need   to   perform   extensive
    computation.   If  such computations are  executed in a new  thread,
    the  main thread  can process events  and allow  the user to  cancel
    the  ongoing computation.    User interfaces can  also use  multiple
    threads,  each thread dealing  with input from  a distinct group  of
    windows.  See also section ????.

  o _N_a_t_u_r_a_l _i_n_t_e_g_r_a_t_i_o_n _w_i_t_h _f_o_r_e_i_g_n _c_o_d_e
    Each Prolog thread  runs in a native thread of the operating system,
    automatically  making them cooperate with _M_T_-_s_a_f_e foreign code.   In
    addition,  any foreign thread can  create its own Prolog engine  for
    dealing with calling Prolog from C code.

SWI-Prolog  multithreading is  based on  the POSIX  thread standard  [??]
used on most popular systems except for MS-Windows.   On Windows it uses
the http://sources.redhat.com/pthreads-win32/pthread-win32 emulation  of
POSIX threads mixed with the Windows native API for  smoother and faster
operation.   The SWI-Prolog thread implementation has been  discussed in
the  ISO WG17  working group  and is  largely addopted  by  YAP and  XSB
Prolog.


99..11 CCrreeaattiinngg aanndd ddeessttrrooyyiinngg PPrroolloogg tthhrreeaaddss


tthhrreeaadd__ccrreeaattee((_:_G_o_a_l_, _-_I_d))
    Shorthand for thread_create(Goal, Id, []).  See thread_create/3.


tthhrreeaadd__ccrreeaattee((_:_G_o_a_l_, _-_I_d_, _+_O_p_t_i_o_n_s))
    Create a new  Prolog thread (and underlying operating system thread)
    and  start  it  by  executing  _G_o_a_l.    If  the  thread  is  created
    successfully,   the thread  identifier  of  the  created  thread  is
    unified to _I_d.

    _I_d is the _a_l_i_a_s  name if the option alias(_n_a_m_e) is given.  Otherwise
    it  is a  _b_l_o_b of  type thread.    The anonymous  blobs are  subject
    to  atom  garbage  collection.    If  a  thread  handle  is  garbage
    collected  and  the thread  is  not _d_e_t_a_c_h_e_d,  it  is _j_o_i_n_e_d  if  it
    has  already terminated  (see thread_join/2) and detached  otherwise
    (see  thread_detach/1).   The  thread identifier  blobs are  printed
    as  <thread>(_I,_P_t_r),  where  _I  is the  internal  thread  identifier
    and  _P_t_r  is  the unique  address  of the  identifier.    The  _I  is
    accepted as input  argument for all thread APIs that accept a thread
    identifier  for convenient interaction from the toplevel.   See also
    thread_property/2.

    _O_p_t_i_o_n_s  is  a list  of  options.    The currently  defined  options
    are  below.   Stack  size options  can also  take the  value inf  or
    infinite,  which is mapped  to the maximum  stack size supported  by
    the platform.

    aalliiaass((_A_l_i_a_s_N_a_m_e))
         Associate an `alias  name' with the thread.   This name may  be
         used to refer to the thread and remains valid  until the thread
         is joined (see  thread_join/2).   If  the OS supports it  (e.g.,
         Linux), the operating system thread is named as well.

    aatt__eexxiitt((_:_A_t_E_x_i_t))
         Register _A_t_E_x_i_t  as using thread_at_exit/1 before entering  the
         thread  goal.    Unlike  calling  thread_at_exit/1 as  part  of
         the normal  _G_o_a_l, this  _e_n_s_u_r_e_s the  _A_t_E_x_i_t is called.    Using
         thread_at_exit/1,  the thread  may be  signalled or  run out  of
         resources before thread_at_exit/1is reached.

    ddeebbuugg((_+_B_o_o_l))
         Enable/disable debugging  the new  thread.   If false  (default
         true),   the  new   thread  is   created   with  the   property
         debug(_f_a_l_s_e) and  debugging is disabled  before the new  thread
         is started.   The  thread debugging  predicates such as  tspy/1
         and tdebug/0 do not signal threads with the  debug property set
         to false.

    ddeettaacchheedd((_B_o_o_l))
         If  false  (default),  the  thread  can  be  waited  for  using
         thread_join/2.   thread_join/2 must  be called  on this  thread
         to  reclaim all  resources  associated with  the  thread.    If
         true,  the   system  will  reclaim  all  associated   resources
         automatically after  the thread  finishes.    Please note  that
         thread identifiers are freed for reuse after  a detached thread
         finishes  or a  normal  thread  has  been joined.     See  also
         thread_join/2 and thread_detach/1.

         If  a  detached  thread  dies  due  to   failure  or  exception
         of  the  initial  goal,  the  thread  prints  a  message  using
         print_message/2.  If such termination is considered normal, the
         code must be  wrapped using ignore/1  and/or catch/3 to  ensure
         successful completion.

    iinnhheerriitt__ffrroomm((_+_T_h_r_e_a_d_I_d))
         Inherit  defaults  from  the  given  _T_h_r_e_a_d_I_d  instead  of  the
         calling thread.    This  option was  added to  ensure that  the
         __thread_pool_manager  (see thread_create_in_pool/4),  which  is
         created  lazily,  has  a predictable  state.     The  following
         properties are inherited:

           o The prompt (see prompt/2)

           o The _t_y_p_e_i_n module (see module/1)

           o The standard streams (user_input, etc.)

           o The default encoding (see encoding)

           o The default locale (see setlocale/1)

           o All prolog flags

           o The limits of Prolog stacks (see set_prolog_stack/2)

    gglloobbaall((_K_-_B_y_t_e_s))
         Set the  limit to  which the global  stack of  this thread  may
         grow.   If omitted,  the limit of the  calling thread is  used.
         See also the -G command line option.

    llooccaall((_K_-_B_y_t_e_s))
         Set the  limit to  which  the local  stack of  this thread  may
         grow.   If omitted,  the limit of the  calling thread is  used.
         See also the -L command line option.

    cc__ssttaacckk((_K_-_B_y_t_e_s))
         Set  the  limit  to which  the  system  stack  of  this  thread
         may  grow.    The  default,  minimum  and  maximum  values  are
         system-dependent.

    ttrraaiill((_K_-_B_y_t_e_s))
         Set the  limit to  which  the trail  stack of  this thread  may
         grow.   If omitted,  the limit of the  calling thread is  used.
         See also the -T command line option.

    The _G_o_a_l argument is  _c_o_p_i_e_d to the new Prolog engine.  This implies
    that  further instantiation of this  term in either thread does  not
    have  consequences for  the  other thread:   Prolog  threads do  not
    share data from their stacks.


tthhrreeaadd__sseellff((_-_I_d))
    Get  the Prolog thread  identifier of  the running thread.   If  the
    thread has an alias, the alias name is returned.


tthhrreeaadd__jjooiinn((_+_I_d))
    Calls  thread_join/2  and  succeeds if  thread  _I_d  terminated  with
    success.   Otherwise the exception error(thread_error_(_S_t_a_t_u_s_)_, __) is
    raised.


tthhrreeaadd__jjooiinn((_+_I_d_, _-_S_t_a_t_u_s))
    Wait  for the termination  of the thread  with the given  _I_d.   Then
    unify  the result  status of  the thread with  _S_t_a_t_u_s.   After  this
    call,  _I_d  becomes invalid  and all  resources  associated with  the
    thread  are  reclaimed.     Note that  threads  with  the  attribute
    detached(_t_r_u_e) cannot be joined.  See also thread_property/2.

    A thread  that has been completed without thread_join/2 being called
    on  it is partly reclaimed:  the Prolog stacks are released  and the
    C  thread is  destroyed.   A small  data structure representing  the
    exit status  of the thread is retained until thread_join/2 is called
    on the thread.  Defined values for _S_t_a_t_u_s are:

    ttrruuee
         The goal has been proven successfully.

    ffaallssee
         The goal has failed.

    eexxcceeppttiioonn((_T_e_r_m))
         The thread is terminated on an  exception.  See print_message/2
         to turn system exceptions into readable messages.

    eexxiitteedd((_T_e_r_m))
         The thread  is terminated on  thread_exit/1 using the  argument
         _T_e_r_m.


tthhrreeaadd__ddeettaacchh((_+_I_d))
    Switch  thread into  detached  state (see  detached(_B_o_o_l) option  at
    thread_create/3) at  runtime.   _I_d is the  identifier of the  thread
    placed in detached state.  This may be the result of thread_self/1.

    One   of  the  possible  applications  is  to   simplify  debugging.
    Threads  that  are  created as  _d_e_t_a_c_h_e_d  leave  no traces  if  they
    crash.   For non-detached threads the status can be  inspected using
    thread_property/2.   Threads  nobody is waiting  for may be  created
    normally  and detach themselves  just before completion.   This  way
    they  leave no  traces  on normal  completion and  their reason  for
    failure can be inspected.


tthhrreeaadd__eexxiitt((_+_T_e_r_m))                                          _[_d_e_p_r_e_c_a_t_e_d_]
    Terminates  the thread immediately,  leaving exited(_T_e_r_m) as  result
    state  for   thread_join/2.     If  the   thread  has  the  attribute
    detached(_t_r_u_e)  it  terminates,   but  its  exit  status  cannot  be
    retrieved using  thread_join/2, making the value  of _T_e_r_m irrelevant.
    The Prolog stacks and C thread are reclaimed.

    The  current  implementation  does not  guarantee  proper  releasing
    of  all  mutexes and  proper cleanup  in  setup_call_cleanup/3,  etc.
    Please  use the  exception  mechanism (throw/1)  to abort  execution
    using non-standard control.


tthhrreeaadd__iinniittiiaalliizzaattiioonn((_:_G_o_a_l))
    Run  _G_o_a_l when  thread is  started.   This predicate  is similar  to
    initialization/1,  but is intended for initialization  operations of
    the  runtime stacks, such as  setting global variables as  described
    in  section ????.   _G_o_a_l  is run on  four occasions:   at the call  to
    this  predicate,  after loading  a saved  state, on  starting a  new
    thread  and on  creating a  Prolog engine through  the C  interface.
    On  loading  a  saved state,  _G_o_a_l  is  executed _a_f_t_e_r  running  the
    initialization/1 hooks.


tthhrreeaadd__aatt__eexxiitt((_:_G_o_a_l))
    Run  _G_o_a_l  just before  releasing the  thread resources.    This  is
    to  be  compared to  at_halt/1, but  only  for the  current  thread.
    These  hooks are run regardless of  why the execution of the  thread
    has  been completed.    When these hooks  are run,  the return  code
    is  already  available through  thread_property/2 using  the  result
    of  thread_self/1  as  thread  identifier.    Note  that  there  are
    two  scenarios  for using  exit hooks.    Using  thread_at_exit/1 is
    typically  used if  the thread  creates a side-effect  that must  be
    reverted if the thread  dies.  Another scenario is where the creator
    of  the thread  wants to be  informed when  the thread ends.    That
    cannot  be  guaranteed by  means of  thread_at_exit/1 because it  is
    possible that the  thread cannot be created or dies almost instantly
    due  to a  signal or resource  error.   The at_exit(_G_o_a_l) option  of
    thread_create/3 is designed to deal with this scenario.


tthhrreeaadd__sseettccoonnccuurrrreennccyy((_-_O_l_d_, _+_N_e_w))
    Determine  the concurrency of the  process, which is defined as  the
    maximum number of  concurrently active threads.  `Active' here means
    they  are using CPU  time.   This option is  provided if the  thread
    implementation  provides  pthread_setconcurrency().    Solaris  is  a
    typical  example of this  family.   On other systems this  predicate
    unifies _O_l_d to 0 (zero) and succeeds silently.


99..22 MMoonniittoorriinngg tthhrreeaaddss

Normal multithreaded  applications should not  need the predicates  from
this section  because almost any  usage of  these predicates is  unsafe.
For example checking the  existence of a thread before signalling  it is
of no use as it  may vanish between the two calls.   Catching exceptions
using  catch/3  is the  only  safe  way to  deal  with  thread-existence
errors.

These predicates are provided  for diagnosis and monitoring tasks.   See
also section ????, describing more high-level primitives.


iiss__tthhrreeaadd((_@_T_e_r_m))
    True if _T_e_r_m is a handle to an existing thread.


tthhrreeaadd__pprrooppeerrttyy((_?_I_d_, _?_P_r_o_p_e_r_t_y))
    True  if thread  _I_d  has _P_r_o_p_e_r_t_y.    Either or  both arguments  may
    be  unbound, enumerating  all relations  on backtracking.    Calling
    thread_property/2  does  not  influence  any  thread.      See  also
    thread_join/2.   For threads that have  an alias name, this name  is
    returned  in _I_d instead  of the opaque  thread identifier.   Defined
    properties are:

    aalliiaass((_A_l_i_a_s))
         _A_l_i_a_s is the alias name of thread _I_d.

    ddeettaacchheedd((_B_o_o_l_e_a_n))
         Current detached status of the thread.

    iidd((_I_n_t_e_g_e_r))
         Integer identifier  for the thread.   Can  be used as  argument
         to the thread predicates,  but applications must be aware  that
         these references are reused.

    ssttaattuuss((_S_t_a_t_u_s))
         Current status of the thread.  _S_t_a_t_u_s is one of:

         rruunnnniinngg
             The  thread is running.   This is  the initial status of  a
             thread.   Please  note that  threads waiting for  something
             are considered running too.

         ssuussppeennddeedd
             Only  if  the  thread  is   an  engine  (see  section  ????).
             Indicates that the engine is  currently not associated with
             an OS thread.

         ffaallssee
             The _G_o_a_l of the thread has been completed and failed.

         ttrruuee
             The _G_o_a_l of the thread has been completed and succeeded.

         eexxiitteedd((_T_e_r_m))
             The   _G_o_a_l  of  the  thread   has  been  terminated   using
             thread_exit/1 with  _T_e_r_m as  argument.   If the  underlying
             native  thread has  exited  (using pthread_exit()) _T_e_r_m  is
             unbound.

         eexxcceeppttiioonn((_T_e_r_m))
             The  _G_o_a_l  of the  thread has  been  terminated due  to  an
             uncaught exception (see throw/1 and catch/3).

    eennggiinnee((_B_o_o_l_e_a_n))
         If the thread is  an engine (see chapter ????), _B_o_o_l_e_a_n  is true.
         Othwerwise the property is not present.

    tthhrreeaadd((_T_h_r_e_a_d_I_d))
         If the  thread is  an engine that  is currently  attached to  a
         thread, _T_h_r_e_a_d_I_d is the thread that executes the engine.

    ssyysstteemm__tthhrreeaadd__iidd((_I_n_t_e_g_e_r))
         Thread identifier used by the operating system  for the calling
         thread.  Not  available on all OSes.   This is the same as  the
         Prolog flag  system_thread_idfor  the calling  thread.   Access
         to the system thread  identifier can, on some systems,  be used
         to gain  additional control  over or  information about  Prolog
         threads.

    See  also thread_statistics/3 to  obtain resource usage  information
    and  message_queue_property/2 to get the  number of queued  messages
    for a thread.


tthhrreeaadd__ssttaattiissttiiccss((_+_I_d_, _+_K_e_y_, _-_V_a_l_u_e))
    Obtains  statistical information on  thread _I_d as statistics/2  does
    in  single-threaded applications.   This call  supports all keys  of
    statistics/2,  although only  stack sizes,  cputime, inferences  and
    epoch yield different values for each thread.


mmuutteexx__ssttaattiissttiiccss
    Print  usage statistics on  internal mutexes and mutexes  associated
    with  dynamic predicates.  For  each mutex two numbers are  printed:
    the  number  of times  the  mutex was  acquired  and the  number  of
    _c_o_l_l_i_s_i_o_n_s:   the  number of times  the calling  thread has to  wait
    for  the mutex.    Generally  collision count  is close  to zero  on
    single-CPU hardware.


99..33 TThhrreeaadd ccoommmmuunniiccaattiioonn


99..33..11 MMeessssaaggee qquueeuueess

Prolog  threads can  exchange data  using dynamic  predicates,  database
records,  and other globally  shared data.   These  provide no  suitable
means to wait for data or a condition as they can  only be checked in an
expensive polling loop.   _M_e_s_s_a_g_e _q_u_e_u_e_s provide a means for  threads to
wait for data or conditions without using the CPU.

Each thread  has a message  queue attached to it  that is identified  by
the thread.  Additional queues are created using message_queue_create/1.
Explicitly  created  queues  come  in two  flavours.     When  given  an
_a_l_i_a_s, they  must be destroyed  by the user.   _A_n_o_n_y_m_o_u_s message  queues
are  identified by  a  _b_l_o_b (see  section  ????)  and subject  to  garbage
collection.


tthhrreeaadd__sseenndd__mmeessssaaggee((_+_Q_u_e_u_e_O_r_T_h_r_e_a_d_I_d_, _+_T_e_r_m))
    Place  _T_e_r_m in  the given queue  or default  queue of the  indicated
    thread  (which  can  even  be  the  message  queue  of  itself,  see
    thread_self/1).   Any  term can be  placed in a  message queue,  but
    note  that the term is copied  to the receiving thread and  variable
    bindings are thus lost.  This call returns immediately.

    If  more than one thread is waiting for messages on the  given queue
    and  at least one of these is waiting with a  partially instantiated
    _T_e_r_m, the waiting  threads are _a_l_l sent a wake-up signal, starting a
    rush  for the available messages in  the queue.  This behaviour  can
    seriously  harm performance  with many threads  waiting on the  same
    queue  as all-but-the-winner  perform a useless  scan of the  queue.
    If  there is  only one waiting  thread or  all waiting threads  wait
    with  an unbound variable, an arbitrary thread is restarted  to scan
    the queue.


tthhrreeaadd__sseenndd__mmeessssaaggee((_+_Q_u_e_u_e_, _+_T_e_r_m_, _+_O_p_t_i_o_n_s))                   _[_s_e_m_i_d_e_t_]
    As  thread_send_message/2, but  providing additional _O_p_t_i_o_n_s.   These
    are  to deal  with  the case  that the  queue has  a finite  maximum
    size  and is full:   whereas thread_send_message/2 will block  until
    the  queue  has  drained  sufficiently  to  accept  a  new  message,
    thread_send_message/3 can accept a time-out or  deadline analogously
    to thread_get_message/3.  The options are:

    ddeeaaddlliinnee((_+_A_b_s_T_i_m_e))
         The call  fails (silently)  if  no space  has become  available
         before  _A_b_s_T_i_m_e.    See get_time/1  for the  representation  of
         absolute time.   If _A_b_s_T_i_m_e is  earlier then the current  time,
         thread_send_message/3 fails immediately.   Both resolution  and
         maximum wait time is platform-dependent.

    ttiimmeeoouutt((_+_T_i_m_e))
         _T_i_m_e is a  float or integer and  specifies the maximum time  to
         wait in  seconds.    This  is a  relative-time version  of  the
         deadline option.   If  both options are  provided, the  earlier
         time is effective.

         If _T_i_m_e is  0 or 0.0, thread_send_message/3 examines the  queue
         and sends  the  message if  space is  availabel,  but does  not
         suspend if no space is available, failing immediately instead.

         If _T_i_m_e  < 0, thread_send_message/3 fails  immediately without
         sending the message.


tthhrreeaadd__ggeett__mmeessssaaggee((_?_T_e_r_m))
    Examines the thread  message queue and if necessary blocks execution
    until  a term that unifies  to _T_e_r_m arrives in  the queue.  After  a
    term  from the queue has been  unified to _T_e_r_m, the term  is deleted
    from the queue.

    Please  note that non-unifying messages remain in the queue.   After
    the  following has been  executed, thread 1  has the term b(_g_n_u)  in
    its queue and continues execution using _A = gnat.

    ____________________________________________________________________|                                                                    |
    |    <thread 1>                                                      |

    |    thread_get_message(a(A)),                                       |
    |                                                                    |
    |    <thread 2>                                                      |
    |    thread_send_message(Thread_1, b(gnu)),                          |
    ||___thread_send_message(Thread_1,_a(gnat)),________________________ ||

    See also thread_peek_message/1.


tthhrreeaadd__ppeeeekk__mmeessssaaggee((_?_T_e_r_m))
    Examines  the thread  message queue  and compares  the queued  terms
    with   _T_e_r_m  until  one  unifies  or  the  end  of  the   queue  has
    been  reached.    In  the first  case  the call  succeeds,  possibly
    instantiating  _T_e_r_m.  If no  term from the queue unifies,  this call
    fails.   I.e., thread_peek_message/1never waits and  does not remove
    any term from the queue.  See also thread_get_message/3.


mmeessssaaggee__qquueeuuee__ccrreeaattee((_?_Q_u_e_u_e))
    Equivalent  to  message_queue_create(Queue,[]).     For  compatibil-
    ity,    calling   message_queue_create(_+_A_t_o_m)   is   equivalent   to
    message_queue_create(_Q_u_e_u_e_,  _[_a_l_i_a_s_(_A_t_o_m_)_]).   New  code should  use
    message_queue_create/2 to create a named queue.


mmeessssaaggee__qquueeuuee__ccrreeaattee((_-_Q_u_e_u_e_, _+_O_p_t_i_o_n_s))
    Create a message queue from _O_p_t_i_o_n_s.  Defined options are:

    aalliiaass((_+_A_l_i_a_s))
         Create  a  message  queue  that  is  identified   by  the  atom
         _A_l_i_a_s.   Message  queues created  this way  must be  explicitly
         destroyed by  the user.   If  the alias option  is omitted,  an
         _A_n_o_n_y_m_o_u_s queue is created  that is indentified by a  _b_l_o_b (see
         section ????) and subject to garbage collection.

    mmaaxx__ssiizzee((_+_S_i_z_e))
         Maximum number  of  terms in  the queue.    If  this number  is
         reached,  thread_send_message/2 will  suspend until  the  queue
         is drained.   The  option can  be used if  the source,  sending
         messages to the queue, is faster than the  drain, consuming the
         messages.


mmeessssaaggee__qquueeuuee__ddeessttrrooyy((_+_Q_u_e_u_e))                                      _[_d_e_t_]
    Destroy  a  message queue  created with  message_queue_create/1.    A
    permission  error is raised  if _Q_u_e_u_e refers  to (the default  queue
    of)  a thread.    Other  threads that  are waiting  for _Q_u_e_u_e  using
    thread_get_message/2 receive an existence error.


tthhrreeaadd__ggeett__mmeessssaaggee((_+_Q_u_e_u_e_, _?_T_e_r_m))                                  _[_d_e_t_]
    As  thread_get_message/1, operating on a given queue.   It is allowed
    (but  not advised) to get messages from the queue of  other threads.
    This predicate raises  an existence error exception if _Q_u_e_u_e doesn't
    exist  or  is  destroyed  using  message_queue_destroy/1 while  this
    predicate is waiting.


tthhrreeaadd__ggeett__mmeessssaaggee((_+_Q_u_e_u_e_, _?_T_e_r_m_, _+_O_p_t_i_o_n_s))                    _[_s_e_m_i_d_e_t_]
    As thread_get_message/2, but providing additional _O_p_t_i_o_n_s:

    ddeeaaddlliinnee((_+_A_b_s_T_i_m_e))
         The call  fails (silently)  if  no message  has arrived  before
         _A_b_s_T_i_m_e.   See  get_time/1 for the  representation of  absolute
         time.     If   _A_b_s_T_i_m_e  is  earlier  then  the   current  time,
         thread_get_message/3 fails immediately.    Both resolution  and
         maximum wait time is platform-dependent.

    ttiimmeeoouutt((_+_T_i_m_e))
         _T_i_m_e is a  float or integer and  specifies the maximum time  to
         wait in  seconds.    This  is a  relative-time version  of  the
         deadline option.   If  both options are  provided, the  earlier
         time is effective.

         If _T_i_m_e  is 0 or  0.0, thread_get_message/3 examines the  queue
         but does not  suspend if no matching  term is available.   Note
         that unlike  thread_peek_message/2, a  matching term is  removed
         from the queue.

         If  _T_i_m_e < 0,  thread_get_message/3 fails  immediately without
         removing any message from the queue.


tthhrreeaadd__ppeeeekk__mmeessssaaggee((_+_Q_u_e_u_e_, _?_T_e_r_m))                             _[_s_e_m_i_d_e_t_]
    As  thread_peek_message/1,  operating on  a  given  queue.    It  is
    allowed  to peek into another  thread's message queue, an  operation
    that  can be used to check whether a thread has swallowed  a message
    sent to it.


mmeessssaaggee__qquueeuuee__pprrooppeerrttyy((_?_Q_u_e_u_e_, _?_P_r_o_p_e_r_t_y))
    True if _P_r_o_p_e_r_t_y is a property of _Q_u_e_u_e.  Defined properties are:

    aalliiaass((_A_l_i_a_s))
         Queue has the given alias name.

    mmaaxx__ssiizzee((_S_i_z_e))
         Maximum  number of  terms  that  can be  in  the queue.     See
         message_queue_create/2.   This property is not present  if there
         is no limit (default).

    ssiizzee((_S_i_z_e))
         Queue  currently  contains  _S_i_z_e terms.     Note  that  due  to
         concurrent access the returned value may be  outdated before it
         is returned.  It can be used for debugging purposes  as well as
         work distribution purposes.

    The  size(_S_i_z_e)  property  is always  present  and  may be  used  to
    enumerate  the created  message queues.   Note  that this  predicate
    does _n_o_t _e_n_u_m_e_r_a_t_e  threads, but can be used to query the properties
    of the default queue of a thread.

Explicit  message queues  are  designed with  the _w_o_r_k_e_r_-_p_o_o_l  model  in
mind,  where  multiple  threads wait  on  a  single queue  and  pick  up
the first  goal to  execute.   Below  is a  simple implementation  where
the workers  execute arbitrary  Prolog goals.   Note  that this  example
provides no means to tell when all work is done.   This must be realised
using additional synchronisation.

________________________________________________________________________|                                                                        |
|%%      create_workers(?Id, +N)                                         |
|%                                                                       |
|%       Create a pool with Id and number of workers.                    |

|%       After the pool is created, post_job/1 can be used to            |
|%       send jobs to the pool.                                          |
|                                                                        |
|create_workers(Id, N) :-                                                |
|        message_queue_create(Id),                                       |
|        forall(between(1, N, _),                                        |
|               thread_create(do_work(Id), _, [])).                      |
|                                                                        |

|do_work(Id) :-                                                          |
|        repeat,                                                         |
|          thread_get_message(Id, Goal),                                 |
|          (   catch(Goal, E, print_message(error, E))                   |
|          ->  true                                                      |
|          ;   print_message(error, goal_failed(Goal, worker(Id)))       |
|          ),                                                            |

|        fail.                                                           |
|                                                                        |
|%%      post_job(+Id, +Goal)                                            |
|%                                                                       |
|%       Post a job to be executed by one of the pool's workers.         |
|                                                                        |
|post_job(Id, Goal) :-                                                   |
||_______thread_send_message(Id,_Goal)._________________________________ ||


99..33..22 SSiiggnnaalllliinngg tthhrreeaaddss

These  predicates provide  a mechanism  to make  another thread  execute
some  goal as  an  _i_n_t_e_r_r_u_p_t.    Signalling  threads  is safe  as  these
interrupts  are only  checked at  safe points  in  the virtual  machine.
Nevertheless,   signalling  in  multithreaded  environments  should   be
handled  with  care as  the  receiving  thread  may hold  a  _m_u_t_e_x  (see
with_mutex/2).  Signalling probably only makes sense to  start debugging
threads and to  cancel no-longer-needed threads with throw/1,  where the
receiving thread  should be designed carefully  to handle exceptions  at
any point.


tthhrreeaadd__ssiiggnnaall((_+_T_h_r_e_a_d_I_d_, _:_G_o_a_l))
    Make thread _T_h_r_e_a_d_I_d execute  _G_o_a_l at the first opportunity.  In the
    current  implementation, this implies at the first pass  through the
    _C_a_l_l  _p_o_r_t.  The  predicate thread_signal/2 itself places _G_o_a_l  into
    the signalled thread's signal queue and returns immediately.

    Signals  (interrupts)  do  not  cooperate well  with  the  world  of
    multithreading,  mainly  because  the status  of mutexes  cannot  be
    guaranteed  easily.   At the call port,  the Prolog virtual  machine
    holds no locks and therefore the asynchronous execution is safe.

    _G_o_a_l  can  be  any valid  Prolog  goal,  including throw/1  to  make
    the  receiving thread generate  an exception,  and trace/0 to  start
    tracing the receiving thread.

    In  the Windows version,  the receiving thread immediately  executes
    the  signal  if  it  reaches  a  Windows  GetMessage()  call,  which
    generally happens if the thread is waiting for (user) input.


99..33..33 TThhrreeaaddss aanndd ddyynnaammiicc pprreeddiiccaatteess

Besides queues  (section ????) threads can  share and exchange data  using
dynamic predicates.   The  multithreaded version  knows about two  types
of  dynamic predicates.     By default,  a  predicate  declared  _d_y_n_a_m_i_c
(see dynamic/1)  is shared  by all  threads.   Each  thread may  assert,
retract and  run the dynamic predicate.   Synchronisation inside  Prolog
guarantees  the consistency  of the  predicate.    Updates are  _l_o_g_i_c_a_l:
visible  clauses  are  not affected  by  assert/retract  after  a  query
started on  the predicate.   In  many cases  primitives from section  ????
should be  used to ensure that  application invariants on the  predicate
are maintained.

Besides shared predicates,  dynamic predicates can be declared  with the
thread_local/1 directive.   Such predicates share their attributes,  but
the clause list is different in each thread.


tthhrreeaadd__llooccaall _+_F_u_n_c_t_o_r_/_+_A_r_i_t_y_, _._._.
    This  directive is  related to the  dynamic/1 directive.   It  tells
    the  system  that  the predicate  may  be modified  using  assert/1,
    retract/1,  etc., during  execution of the program.   Unlike  normal
    shared  dynamic data, however, each  thread has its own clause  list
    for  the predicate.  As a thread starts, this clause list  is empty.
    If  there are still  clauses when the  thread terminates, these  are
    automatically  reclaimed by the system  (see also volatile/1).   The
    thread_local property implies the properties _d_y_n_a_m_i_c and _v_o_l_a_t_i_l_e.

    Thread-local   dynamic  predicates  are  intended  for   maintaining
    thread-specific state or intermediate results of a computation.

    It  is not recommended to  put clauses for a thread-local  predicate
    into  a file, as  in the example below,  because the clause is  only
    visible  from the thread  that loaded  the source file.   All  other
    threads start with an empty clause list.

    ____________________________________________________________________|                                                                    |
    | :- thread_local                                                    |

    |         foo/1.                                                     |
    |                                                                    |
    ||foo(gnat).________________________________________________________ ||

    DDIISSCCLLAAIIMMEERR  Whether or  not this declaration  is appropriate in  the
    sense  of the proper mechanism to  reach the goal is still  debated.
    If you have  strong feelings in favour or against, please share them
    in the SWI-Prolog mailing list.


99..44 TThhrreeaadd ssyynncchhrroonniissaattiioonn

All  internal Prolog  operations are  thread-safe.    This implies  that
two Prolog  threads can operate  on the  same dynamic predicate  without
corrupting the consistency  of the predicate.   This section deals  with
user-level  _m_u_t_e_x_e_s (called  _m_o_n_i_t_o_r_s  in ADA  or _c_r_i_t_i_c_a_l  _s_e_c_t_i_o_n_s  by
Microsoft).   A mutex is a  MMUUTTual EEXXclusive device, which implies  that
at most one thread can _h_o_l_d a mutex.

Mutexes are  used to  realise related  updates to  the Prolog  database.
With `related', we refer to the situation where  a `transaction' implies
two  or more  changes to  the Prolog  database.   For  example, we  have
a  predicate address/2,  representing the  address of  a  person and  we
want  to change  the address  by retracting  the old  and asserting  the
new address.    Between these  two operations the  database is  invalid:
this person  has either no  address or two  addresses, depending on  the
assert/retract order.

The  code   below  provides  a  solution   to  this  problem  based   on
with_mutex/2.    It  also illustrates  the  problem  of mutexes.     The
predicate with_mutex/2  behaves as once/1  with respect  to the  guarded
goal.   This  means that  our predicate address/2  is no  longer a  nice
logical non-deterministic  relation.  This  could be solved by  explicit
locking and  unlocking a  mutex using  setup_call_cleanup/2,  but at  the
risk of  deadlocking the  program if the  choice point  is left open  by
accident.

________________________________________________________________________|                                                                        |
|change_address(Id, Address) :-                                          |
|        with_mutex(addressbook,                                         |
|                   ( retractall(address(Id, _)),                        |

|                     asserta(address_db(Id, Address))                   |
|                   )).                                                  |
|                                                                        |
|address(Id, Address) :-                                                 |
|        with_mutex(addressbook,                                         |
||__________________address_db(Id,_Address)).___________________________ ||

Message queues  (see message_queue_create/3) often  provide simpler  and
more robust ways  for threads to communicate.   Still, mutexes can be  a
sensible solution and are therefore provided.


mmuutteexx__ccrreeaattee((_?_M_u_t_e_x_I_d))
    Create  a mutex.  If _M_u_t_e_x_I_d  is an atom, a _n_a_m_e_d mutex  is created.
    If  it is  a variable,  an  anonymous mutex  reference is  returned.
    Anonymous mutexes are subject to (atom) garbage collection.


mmuutteexx__ccrreeaattee((_-_M_u_t_e_x_I_d_, _+_O_p_t_i_o_n_s))
    Create a mutex using options.  Defined options are:

    aalliiaass((_A_l_i_a_s))
         Set the  alias name.   Using mutex_create(_X_, _[_a_l_i_a_s_(_n_a_m_e_)_])  is
         preferred over the equivalent mutex_create(_n_a_m_e).


mmuutteexx__ddeessttrrooyy((_+_M_u_t_e_x_I_d))
    Destroy  a mutex.  If the  mutex is not locked, it is  destroyed and
    further  access yields an existence_error exception.  As  of version
    7.1.19,  this behaviour is  reliable.  If  the mutex is locked,  the
    mutex  is sheduled for  _d_e_l_a_y_e_d _d_e_s_t_r_u_c_t_i_o_n:   it will be  destroyed
    when it becomes unlocked.


wwiitthh__mmuutteexx((_+_M_u_t_e_x_I_d_, _:_G_o_a_l))
    Execute  _G_o_a_l  while  holding  _M_u_t_e_x_I_d.     If  _G_o_a_l  leaves  choice
    points,   these are  destroyed  (as  in  once/1).     The  mutex  is
    unlocked  regardless of whether  _G_o_a_l succeeds,  fails or raises  an
    exception.    An exception  thrown by  _G_o_a_l is  re-thrown after  the
    mutex  has been successfully unlocked.   See also mutex_create/1 and
    setup_call_cleanup/3.

    Although  described in the  thread section,  this predicate is  also
    available  in the single-threaded  version, where it behaves  simply
    as once/1.


mmuutteexx__lloocckk((_+_M_u_t_e_x_I_d))
    Lock the mutex.   Prolog mutexes are _r_e_c_u_r_s_i_v_e mutexes:  they can be
    locked  multiple times by the same thread.  Only after  unlocking it
    as  many times as it is  locked does the mutex become available  for
    locking  by other threads.   If another thread has locked the  mutex
    the calling thread is suspended until the mutex is unlocked.

    If  _M_u_t_e_x_I_d is  an atom,  and there  is no current  mutex with  that
    name,  the  mutex  is  created automatically  using  mutex_create/1.
    This implies named mutexes need not be declared explicitly.

    Please  note that  locking and  unlocking mutexes  should be  paired
    carefully.     Especially  make  sure  to  unlock  mutexes  even  if
    the  protected  code  fails  or  raises an  exception.     For  most
    common  cases,  use with_mutex/2,  which provides  a  safer way  for
    handling  Prolog-level mutexes.   The predicate setup_call_cleanup/3
    is  another  way  to guarantee  that  the  mutex is  unlocked  while
    retaining non-determinism.


mmuutteexx__ttrryylloocckk((_+_M_u_t_e_x_I_d))
    As  mutex_lock/1,  but if the mutex  is held by another thread,  this
    predicates fails immediately.


mmuutteexx__uunnlloocckk((_+_M_u_t_e_x_I_d))
    Unlock  the mutex.  This can only be called if the mutex  is held by
    the  calling thread.   If this is  not the case,  a permission_error
    exception is raised.


mmuutteexx__uunnlloocckk__aallll                                            _[_d_e_p_r_e_c_a_t_e_d_]
    Unlock  all mutexes  held by  the current  thread.   This  predicate
    should  not  be   needed  if  mutex  unlocking  is  guaranteed  with
    with_mutex/2 or setup_call_cleanup/3.


mmuutteexx__pprrooppeerrttyy((_?_M_u_t_e_x_I_d_, _?_P_r_o_p_e_r_t_y))
    True if _P_r_o_p_e_r_t_y is a property of _M_u_t_e_x_I_d.  Defined properties are:

    aalliiaass((_A_l_i_a_s))
         Mutex has the defined alias name.  See mutex_create/2 using the
         `alias' option.

    ssttaattuuss((_S_t_a_t_u_s))
         Current status  of the mutex.    One of unlocked  if the  mutex
         is currently not  locked, or locked(_O_w_n_e_r_,  _C_o_u_n_t) if mutex  is
         locked _C_o_u_n_t times by thread _O_w_n_e_r.  Note that  unless _O_w_n_e_r is
         the calling thread, the  locked status can change at  any time.
         There is  no useful  application of this  property, except  for
         diagnostic purposes.


99..55 TThhrreeaadd ssuuppppoorrtt lliibbrraarryy((tthhrreeaadduuttiill))

This library  defines a  couple of useful  predicates for  demonstrating
and debugging  multithreaded applications.   This  library is  certainly
not complete.


tthhrreeaaddss
    Lists all current threads and their status.


jjooiinn__tthhrreeaaddss
    Join all terminated  threads.  For normal applications, dealing with
    terminated  threads must be  part of  the application logic,  either
    detaching  the thread before termination  or making sure it will  be
    joined.   The  predicate join_threads/0 is intended for  interactive
    sessions  to reclaim resources  from threads that died  unexpectedly
    during development.


iinntteerraaccttoorr
    Create  a new  console  and run  the Prolog  top level  in this  new
    console.   See also attach_console/0.  In the Windows version  a new
    interactor can also be created from the Run/New thread menu.


99..55..11 DDeebbuuggggiinngg tthhrreeaaddss

Support for debugging  threads is still very  limited.  Debug and  trace
mode are flags  that are local to each  thread.  Individual threads  can
be debugged either using the graphical debugger described  in section ????
(see tspy/1  and friends) or  by attaching a console  to the thread  and
running the  traditional command  line debugger  (see attach_console/0).
When using the graphical debugger, the debugger must  be _l_o_a_d_e_d from the
main thread (for example using guitracer) before gtrace/0  can be called
from a thread.


aattttaacchh__ccoonnssoollee
    If  the  current thread  has no  console  attached yet,  attach  one
    and  redirect the  user streams (input,  output, and  error) to  the
    new  console  window.   On  Unix  systems the  console is  an  xterm
    application.    On  Windows systems  this requires  the GUI  version
    swipl-win.exe rather than the console-based swipl.exe.

    This  predicate has  a couple  of useful applications.    One is  to
    separate (debugging) I/O  of different threads.  Another is to start
    debugging  a thread that  is running in the  background.  If  thread
    10  is running,  the following  sequence starts the  tracer on  this
    thread:

    ____________________________________________________________________|                                                                    |
    ||?-_thread_signal(10,_(attach_console,_trace)).____________________ ||


ttddeebbuugg((_+_T_h_r_e_a_d_I_d))
    Prepare  _T_h_r_e_a_d_I_d for debugging  using the graphical  tracer.   This
    implies installing the  tracer hooks in the thread and switching the
    thread  to debug  mode using  debug/0.   The call  is injected  into
    the  thread using thread_signal/2.   We  refer to the  documentation
    of  this predicate for asynchronous  interaction with threads.   New
    threads  created  inherit  their debug  mode  from the  thread  that
    created them.


ttddeebbuugg
    Call tdebug/1 in all running threads.


ttnnooddeebbuugg((_+_T_h_r_e_a_d_I_d))
    Disable debugging thread _T_h_r_e_a_d_I_d.


ttnnooddeebbuugg
    Disable debugging in all threads.


ttssppyy((_:_S_p_e_c_, _+_T_h_r_e_a_d_I_d))
    Set  a spy point as spy/1 and enable the thread for  debugging using
    tdebug/1.   Note that  a spy point is  a global flag on a  predicate
    that  is visible from all threads.   Spy points are honoured  in all
    threads  that are in debug mode  and ignored in threads that are  in
    nodebug mode.


ttssppyy((_:_S_p_e_c))
    Set  a  spy point  as  spy/1 and  enable  debugging in  all  threads
    using  tdebug/0.   Note that removing spy  points can be done  using
    nospy/1.   Disabling spy points in a specific thread is  achieved by
    tnodebug/1.


99..55..22 PPrrooffiilliinngg tthhrreeaaddss

In the  current implementation, at  most one thread  can be profiled  at
any moment.   Any thread can call profile/1 to profile the  execution of
some part of  its code.   The predicate tprofile/1 allows for  profiling
the execution of another thread until the user  stops collecting profile
data.


ttpprrooffiillee((_+_T_h_r_e_a_d_I_d))
    Start  collecting profile data in _T_h_r_e_a_d_I_d  and ask the user to  hit
    <_r_e_t_u_r_n>  to stop the profiler.   See section ????  for details on the
    execution profiler.


99..66 MMuullttiitthhrreeaaddeedd mmiixxeedd CC aanndd PPrroolloogg aapppplliiccaattiioonnss

All  foreign code  linked to  the multithreading  version of  SWI-Prolog
should  be   thread-safe  (_r_e_e_n_t_r_a_n_t)   or  guarded   in  Prolog   using
with_mutex/2 from  simultaneous  access  from multiple  Prolog  threads.
If  you want  to write  mixed multithreaded  C  and Prolog  applications
you  should  first  familiarise  yourself  with   writing  multithreaded
applications in C (C++).

If you  are using SWI-Prolog  as an embedded  engine in a  multithreaded
application you  can access the Prolog  engine from multiple threads  by
creating an _e_n_g_i_n_e in  each thread from which you call Prolog.   Without
creating an engine, a thread can only use functions that  do _n_o_t use the
term_t type (for example PL_new_atom()).

The  system supports  two models.    Section ????  describes the  original
one-to-one mapping.   In this schema  a native thread attaches a  Prolog
thread if  it needs  to call Prolog  and detaches it  when finished,  as
opposed to the  model from section ????,  where threads temporarily use  a
Prolog engine.


99..66..11 AA PPrroolloogg tthhrreeaadd ffoorr eeaacchh nnaattiivvee tthhrreeaadd ((oonnee--ttoo--oonnee))

In  the  one-to-one  model,   the  thread  that  called  PL_initialise()
has  a  Prolog   engine  attached.      If  another  C  thread  in   the
system  wishes to  call Prolog  it  must first  attach an  engine  using
PL_thread_attach_engine() and call  PL_thread_destroy_engine()after  all
Prolog work is  finished.  This  model is especially suitable with  long
running threads that need  to do Prolog work regularly.  See  section ????
for the alternative many-to-many model.


int PPLL__tthhrreeaadd__sseellff()
    Returns  the  integer  Prolog identifier  of  the  engine or  -1  if
    the  calling thread has  no Prolog  engine.   This function is  also
    provided  in the  single-threaded version  of  SWI-Prolog, where  it
    returns -2.


int PPLL__uunniiffyy__tthhrreeaadd__iidd(_t_e_r_m___t _t_, _i_n_t _i)
    Unify  _t with the  Prolog thread  identifier for thread  _i.   Thread
    identifiers  are normally returned  from PL_thread_self().   Returns
    -1 if the thread does not exist or the unification fails.


int PPLL__tthhrreeaadd__aattttaacchh__eennggiinnee(_c_o_n_s_t _P_L___t_h_r_e_a_d___a_t_t_r___t _*_a_t_t_r)
    Creates  a new Prolog engine in the calling thread.  If  the calling
    thread  already has an engine the  reference count of the engine  is
    incremented.  The  _a_t_t_r argument can be NULL to create a thread with
    default  attributes.  Otherwise it is a pointer to a  structure with
    the  definition below.   For any field  with value `0', the  default
    is  used.    The cancel  field may  be filled  with a  pointer to  a
    function  that is  called when  PL_cleanup() terminates the  running
    Prolog  engines.  If this  function is not present or returns  FALSE
    pthread_cancel() is  used.   The flags  field defines the  following
    flags:

    PPLL__TTHHRREEAADD__NNOO__DDEEBBUUGG
         If this flag is  present, the thread starts in  normal no-debug
         status.   By default,  the debug status  is inherited from  the
         main thread.

    ____________________________________________________________________|                                                                    |
    | typedef struct                                                     |

    | { unsigned long     local_size;    /* Stack sizes (Kbytes) */      |
    |   unsigned long     global_size;                                   |
    |   unsigned long     trail_size;                                    |
    |   unsigned long     argument_size;                                 |
    |   char *            alias;         /* alias name */                |
    |   int              (*cancel)(int thread);                          |
    |   intptr_t          flags;                                         |
    ||}_PL_thread_attr_t;_______________________________________________ ||

    The  structure may be  destroyed after PL_thread_attach_engine() has
    returned.    On success  it returns  the Prolog  identifier for  the
    thread  (as returned by PL_thread_self()).   If an error occurs,  -1
    is returned.   If this Prolog is not compiled for multithreading, -2
    is returned.


int PPLL__tthhrreeaadd__ddeessttrrooyy__eennggiinnee()
    Destroy  the  Prolog engine  in  the calling  thread.    Only  takes
    effect  if  PL_thread_destroy_engine() is called  as many  times  as
    PL_thread_attach_engine() in this thread.   Returns TRUE on  success
    and  FALSE if the calling thread  has no engine or this Prolog  does
    not support threads.

    Please  note  that  construction  and  destruction  of  engines  are
    relatively  expensive  operations.     Only  destroy  an  engine  if
    performance is not critical and memory is a critical resource.


int PPLL__tthhrreeaadd__aatt__eexxiitt(_v_o_i_d _(_*_f_u_n_c_t_i_o_n_)_(_v_o_i_d _*_)_, _v_o_i_d _*_c_l_o_s_u_r_e_, _i_n_t _g_l_o_b_a_l)
    Register  a handle to be called  as the Prolog engine is  destroyed.
    The  handler function  is called  with one  void * argument  holding
    _c_l_o_s_u_r_e.    If  _g_l_o_b_a_l is  TRUE, the  handler is  installed _f_o_r  _a_l_l
    _t_h_r_e_a_d_s.     Globally  installed handlers  are  executed  after  the
    thread-local  handlers.  If the  handler is installed local for  the
    current thread only (_g_l_o_b_a_l  == FALSE) it is stored in the same FIFO
    queue as used by thread_at_exit/1.


99..66..22 PPoooolliinngg PPrroolloogg eennggiinneess ((mmaannyy--ttoo--mmaannyy))

In this model Prolog engines live as entities that  are independent from
threads.  If a  thread needs to call Prolog it takes one of  the engines
from the pool and returns the engine when done.   This model is suitable
in the following identified cases:

  o _C_o_m_p_a_t_i_b_i_l_i_t_y _w_i_t_h _t_h_e _s_i_n_g_l_e_-_t_h_r_e_a_d_e_d _v_e_r_s_i_o_n
    In  the  single-threaded  version,  foreign threads  must  serialise
    access  to the  one and  only thread engine.    Functions from  this
    section allow sharing one engine among multiple threads.

  o _M_a_n_y _n_a_t_i_v_e _t_h_r_e_a_d_s _w_i_t_h _i_n_f_r_e_q_u_e_n_t _P_r_o_l_o_g _w_o_r_k
    Prolog  threads are expensive in terms of memory and time  to create
    and  destroy them.  For systems  that use a large number  of threads
    that only infrequently need  to call Prolog, it is better to take an
    engine from a pool and return it there.

  o _P_r_o_l_o_g _s_t_a_t_u_s _m_u_s_t _b_e _h_a_n_d_e_d _t_o _a_n_o_t_h_e_r _t_h_r_e_a_d
    This  situation  has  been identified  by  Uwe Lesta  when  creating
    a  .NET interface  for SWI-Prolog.    .NET distributes  work for  an
    active  internet connection over  a pool  of threads.   If a  Prolog
    engine  contains the state for a connection, it must be  possible to
    detach  the engine from a thread and re-attach it to  another thread
    handling the same connection.


PL_engine_t PPLL__ccrreeaattee__eennggiinnee(_P_L___t_h_r_e_a_d___a_t_t_r___t _*_a_t_t_r_i_b_u_t_e_s)
    Create  a  new   Prolog  engine.     _a_t_t_r_i_b_u_t_e_s  is  described  with
    PL_thread_attach_engine().   Any  thread can  make  this call  after
    PL_initialise()  returns  success.    The  returned  engine  is  not
    attached  to any thread and lives  until PL_destroy_engine()is  used
    on the returned handle.

    In  the  single-threaded  version  this call  always  returns  NULL,
    indicating failure.


int PPLL__ddeessttrrooyy__eennggiinnee(_P_L___e_n_g_i_n_e___t _e)
    Destroy  the given engine.  Destroying an engine is only  allowed if
    the engine is not  attached to any thread or attached to the calling
    thread.    On success  this function  returns TRUE,  on failure  the
    return value is FALSE.


int PPLL__sseett__eennggiinnee(_P_L___e_n_g_i_n_e___t _e_n_g_i_n_e_, _P_L___e_n_g_i_n_e___t _*_o_l_d)
    Make  the calling thread ready  to use _e_n_g_i_n_e.   If _o_l_d is  non-NULL
    the  current engine  associated with  the calling  thread is  stored
    at  the  given  location.     If  _e_n_g_i_n_e equals  PL_ENGINE_MAIN  the
    initial  engine is attached  to the  calling thread.   If _e_n_g_i_n_e  is
    PL_ENGINE_CURRENT the  engine is  not  changed.   This  can be  used
    to  query the current  engine.   This call  returns PL_ENGINE_SET  if
    the  engine was switched successfully,  PL_ENGINE_INVAL if _e_n_g_i_n_e  is
    not  a  valid engine  handle and  PL_ENGINE_INUSE  if  the engine  is
    currently in use by another thread.

    Engines  can be changed  at any time.   For  example, it is  allowed
    to  select an engine to initiate a  Prolog goal, detach it and  at a
    later  moment execute the goal from another thread.   Note, however,
    that  the term_t, qid_t and fid_t types are interpreted relative  to
    the  engine for which they are created.  Behaviour when  passing one
    of these types from one engine to another is undefined.

    In  the single-threaded  version this call  only succeeds if  _e_n_g_i_n_e
    refers to the main engine.


99..77 MMuullttiitthhrreeaaddiinngg aanndd tthhee XXPPCCEE ggrraapphhiiccss ssyysstteemm

GUI applications  written in  XPCE can  benefit from  Prolog threads  if
they need  to do expensive computations  that would otherwise block  the
UI. The  XPCE message  passing system  is guarded with  a single  _m_u_t_e_x,
which synchronises  both access from Prolog  and activation through  the
GUI. In MS-Windows, GUI events are processed by  the thread that created
the  window in  which  the  event occurred,  whereas  in  Unix/X11  they
are processed  by the  thread that  dispatches messages.   In  practice,
the most  feasible approach  to graphical Prolog  implementations is  to
control XPCE from  a single thread and  deploy other threads for  (long)
computations.

Traditionally,  XPCE runs  in  the foreground  (main) thread.    We  are
working  towards  a  situation where  XPCE  can  run  comfortably  in  a
separate  thread.     A  separate  XPCE  thread  can  be  created  using
pce_dispatch/1.  It is also possible to create this thread  as the (pce)
is loaded by setting the xpce_threaded to true.

Threads other than the  thread in which XPCE runs are provided  with two
predicates to communicate with XPCE.


iinn__ppccee__tthhrreeaadd((_:_G_o_a_l))                                               _[_d_e_t_]
    Assuming  XPCE is running in the foreground thread, this  call gives
    background  threads  the  opportunity  to make  calls  to  the  XPCE
    thread.    A call to  in_pce_thread/1 succeeds immediately,  copying
    _G_o_a_l  to the XPCE  thread.   _G_o_a_l is added to  the XPCE event  queue
    and  executed  synchronous to  normal user  events  like typing  and
    clicking.


iinn__ppccee__tthhrreeaadd__ssyynncc((_:_G_o_a_l))                                       _[_s_e_m_i_d_e_t_]
    Same  as  in_pce_thread/1,  but  wait  for  _G_o_a_l  to  be  completed.
    Success  depends  on  the  success  of executing  _G_o_a_l.     Variable
    bindings  inside  _G_o_a_l are  visible to  the  caller, but  it  should
    be  noted that  the values  are being  _c_o_p_i_e_d.   If  _G_o_a_l throws  an
    exception,  this exception is re-thrown by  in_pce_thread/1.   If the
    calling  thread is the `pce thread', in_pce_thread_sync/1 executes a
    direct meta-call.  See also pce_thread/1.

    Note   that  in_pce_thread_sync/1  is  expensive   because  it   re-
    quires   copying   and  thread   communication.       For   example,
    in_pce_thread_synctrue runs at approximately 50,000 calls per second
    (AMD Phenom 9600B, Ubuntu 11.04).


ppccee__ddiissppaattcchh((_+_O_p_t_i_o_n_s))
    Create  a  Prolog thread  with the  alias name  pce  for XPCE  event
    handling.    In  the X11  version this  call creates  a thread  that
    executes  the X11  event-dispatch loop.   In  MS-Windows it  creates
    a  thread that  executes a windows  event-dispatch loop.   The  XPCE
    event-handling  thread has  the alias  pce.   _O_p_t_i_o_n_s specifies  the
    thread attributes as thread_create/3.


CChhaapptteerr 1100..  CCOORROOUUTTIINNIINNGG UUSSIINNGG PPRROOLLOOGG EENNGGIINNEESS

Where the  term _c_o_r_o_u_t_i_n_e in Prolog  typically refer to hooks  triggered
by  _a_t_t_r_i_b_u_t_e_d _v_a_r_i_a_b_l_e_s  (section ????),  SWI-Prolog  provides two  other
forms of  coroutines.   Delimited continuations  (see section ????)  allow
creating coroutines  that run  in the  same Prolog  engine by  capturing
and restarting the _c_o_n_t_i_n_u_a_t_i_o_n.   This section discusses _e_n_g_i_n_e_s,  also
known as _i_n_t_e_r_a_c_t_o_r_s.   The idea was pinned by Paul Tarau [??].   The API
described in this chapter has been established together  with Paul Tarau
and Paulo Moura.

Engines are  closely related to _t_h_r_e_a_d_s  (section ????).   An engine is  a
Prolog virtual  machine that has  its own  stacks and (virtual)  machine
state.   Unlike normal  Prolog threads though,  they are not  associated
with an operating system thread.  Instead, you _a_s_k an  engine for a next
answer (engine_next/2).  Asking  an engine for the next  answer attaches
the engine to  the calling operating system  thread and cause it to  run
until the engine  calls engine_yield/1 or its associated goal  completes
with an  answer, failure or an  exception.   After the engine yields  or
completes,  it is  detached from  the operating  system  thread and  the
answer term  is made  available to  the calling thread.    Communicating
with an engine is  similar to communicating with a Prolog  system though
the  terminal.    In  this sense  engines  are  related to  _P_e_n_g_i_n_e_s  as
provided  by library  pengines,  but  where  Pengines aim  primarily  at
accessing Prolog  engines through  the network,  engines are  in-process
entities.


1100..11 EExxaammpplleess uussiinngg eennggiinneess

We  introduce engines  by  describing  application areas  and  providing
simple example programs.  The predicates are defined in section  ????.  We
identify the following application areas for engines.

 1. Aggregating solutions from one or more goals.  See section ????.

 2. Access the terms  produced in _f_o_r_w_a_r_d _e_x_e_c_u_t_i_o_n through backtracking
    without  collecting all of them first.  Section ????  illustrates this
    as well.

 3. State accumulation and sharing.  See section ????.

 4. Scalable many-agent applications.  See section ????.


1100..11..11 AAggggrreeggaattiioonn uussiinngg eennggiinneess

Engines  can be  used  to reason  about  solutions  produced by  a  goal
through backtracking.   In  this scenario we create  an engine with  the
goal we wish to  backtrack over and we enumerate all its  solution using
engine_next/1.    This usage  scenario competes  with the  all  solution
predicates (findall/3, bagof/3,  etc.)  and the predicates  from library
aggregate.  Below we implement findall/3 using engines.

________________________________________________________________________|                                                                        |
|findall(Templ, Goal, List) :-                                           |

|        setup_call_cleanup(                                             |
|            engine_create(Templ, Goal, E),                              |
|            get_answers(E, List),                                       |
|            engine_destroy(E)).                                         |
|                                                                        |
|get_answers(E, [H|T]) :-                                                |
|        engine_next(E, H), !,                                           |
|        get_answers(E, T).                                              |

|get_answers(_,|[]).____________________________________________________ |              |

The above is not a particularly attractive alternative  for the built-in
findall/3.    It  is  mostly  slower  due to  time  required  to  create
and  destroy the  engine  as well  as  the (currently)  higher  overhead
of  copying terms  between engines  than the  overhead  required by  the
dedicated representation used by findall/3.

It gets  more interesting if  we wish to  combine answers from  multiple
backtracking  predicates.    Assume  we have  two  predicates  that,  on
backtracking,  return ordered solutions  and we  wish to  merge the  two
answer streams into  a single ordered stream  of answers.  The  solution
in classical  Prolog is  below.   It collects both  answer sets,  merges
them  using ordered  set merging  and extract  the answers.    The  code
is  clean and  short, but  it doesn't  produce any  answers before  both
generaters are fully enumerated and it uses memory  that is proportional
to the combined set of answers.

________________________________________________________________________|                                                                        |

|:- meta_predicate merge(?,0, ?,0, -).                                   |
|                                                                        |
|merge_answers(T1,G1, T2,G2, A) :-                                       |
|        findall(T1, G1, L1),                                            |
|        findall(T2, G2, L2),                                            |
|        ord_union(L1, L2, Ordered),                                     |

||_______member(A,_Ordered).____________________________________________ ||

We  can achieve  the same  using  engines.   We  create  two engines  to
generate the  solutions to both our  generators.   Now, we cas ask  both
for an  answer, put the smallest  in the answer  set and ask the  engine
that created  the smallest for its  next answer, etc.   This way we  can
create an  ordered list of  answers as above,  but now without  creating
intermediate lists.    We can  avoid creating the  intermediate list  by
introducing a third  engine that controls the two generators  and _y_i_e_l_d_s
the answers  rather than  putting them in  a list.   This  is a  general
example  of turning  a  predicate that  builds a  set  of terms  into  a
non-deterministic predicate that  produces the results on  backtracking.
The full  code is below.   Merging the  answers of two generators,  each
generating a set of  10,000 integers is currently about 20%  slower than
the code  above, but  the engine-based solution  runs in constant  space
and generates the  first solution immediately after both our  generators
have produced their first solution.

________________________________________________________________________|                                                                        |
|:- meta_predicate merge(?,0, ?,0, -).                                   |
|                                                                        |
|merge(T1,G1, T2,G2, A) :-                                               |
|        engine_create(A, merge(T1,G1, T2,G2), E),                       |
|        repeat,                                                         |

|            (   engine_next(E, A)                                       |
|            ->  true                                                    |
|            ;   !, fail                                                 |
|            ).                                                          |
|                                                                        |
|merge(T1,G1, T2,G2) :-                                                  |
|        engine_create(T1, G1, E1),                                      |

|        engine_create(T2, G2, E2),                                      |
|        (   engine_next(E1, S1)                                         |
|        ->  (   engine_next(E2, S2)                                     |
|            ->  order_solutions(S1, S2, E1, E2)                         |
|            ;   yield_remaining(S1, E1)                                 |
|            )                                                           |
|        ;   engine_next(E2, S2),                                        |
|            yield_remaining(S2, E2)                                     |

|        ).                                                              |
|                                                                        |
|order_solutions(S1, S2, E1, E2) :- !,                                   |
|        (   S1 @=< S2                                                   |
|        ->  engine_yield(S1),                                           |
|            (   engine_next(E1, S11)                                    |
|            ->  order_solutions(S11, S2, E1, E2)                        |

|            ;   yield_remaining(S2, E2)                                 |
|            )                                                           |
|        ;   engine_yield(S2),                                           |
|            (   engine_next(E2, S21)                                    |
|            ->  order_solutions(S1, S21, E1, E2)                        |
|            ;   yield_remaining(S1, E1)                                 |
|            )                                                           |
|        ).                                                              |

|                                                                        |
|yield_remaining(S, E) :-                                                |
|        engine_yield(S),                                                |
|        engine_next(E, S1),                                             |
||_______yield_remaining(S1,_E).________________________________________ ||


1100..11..22 SSttaattee aaccccuummuullaattiioonn uussiinngg eennggiinneess

Applications that need to manage a state can do so  by passing the state
around in  an additional argument,  storing it in  a global variable  or
update it in the  dynamic database using assertz/1 and retract/1.   Both
using an  additional argument  and a  global variable  (see b_setval/2),
make  the state  subject  to backtracking.    This  may  or may  not  be
desirable.    If  having a  state is  that  subject to  backtracking  is
required, using an additional argument or  backtrackable global variable
is the  right approach.   Otherwise, non-backtrackable global  variables
(nb_setval/2) and dynamic database  come into the picture, where  global
variables are always local  to a thread and the dynamic database  may or
may not be shared between threads (see thread_local/1).

Engines bring  an alternative that  packages a  state inside the  engine
where it is typically represented in a (threaded) Prolog  variable.  The
state may be updated, while controlled backtracking to  a previous state
belongs to the possibilities.  It can be accessed  and updated by anyone
with access to the engines' handle.  Using an  engine to represent state
has the following advantages:

  o The  programming  style  needed  inside  the  engine  is  much  more
    `Prolog  friendly',  using  engine_fetch/1  to read  a  request  and
    engine_yield/1 to reply to it.

  o The state is packaged and subject to (atom) garbage collection.

  o The  state may be  accessed from  multiple threads.   Access to  the
    state is synchronized without the need for explicit locks.

The example  below implements a  shared priority  heap based on  library
heaps.   The predicate update_heap/1 shows  the typical update loop  for
maintaining state inside an engine:  fetch a command,  update the state,
yield with  the reply  and call  the updater  recursively.   The  update
step is  guarded against  failure.   For robustness  one may also  guard
it against  exceptions using catch/3.   Note that heap_get/2 passes  the
_P_r_i_o_r_i_t_y and  _K_e_y it wishes  to delete  from the heap  such that if  the
unification fails, the heap remains unchanged.

The resulting heap is  a global object with either a named  or anonymous
handle that evolves independently from the Prolog  thread(s) that access
it.    If  the  heap is  anonymous,  it  is subject  to  (atom)  garbage
collection.

________________________________________________________________________|                                                                        |

|:- use_module(library(heaps)).                                          |
|                                                                        |
|create_heap(E) :-                                                       |
|        empty_heap(H),                                                  |
|        engine_create(_, update_heap(H), E).                            |
|                                                                        |
|update_heap(H) :-                                                       |

|        engine_fetch(Command),                                          |
|        (   update_heap(Command, Reply, H, H1)                          |
|        ->  true                                                        |
|        ;   H1 = H,                                                     |
|            Reply = false                                               |
|        ),                                                              |
|        engine_yield(Reply),                                            |

|        update_heap(H1).                                                |
|                                                                        |
|update_heap(add(Priority, Key), true, H0, H) :-                         |
|        add_to_heap(H0, Priority, Key, H).                              |
|update_heap(get(Priority, Key), Priority-Key, H0, H) :-                 |
|        get_from_heap(H0, Priority, Key, H).                            |
|                                                                        |
|heap_add(Priority, Key, E) :-                                           |

|        engine_post(E, add(Priority, Key), true).                       |
|                                                                        |
|heap_get(Priority, Key, E) :-                                           |
||_______engine_post(E,_get(Priority,_Key),_Priority-Key).______________ ||


1100..11..33 SSccaallaabbllee mmaannyy--aaggeenntt aapppplliiccaattiioonnss

The final application  area we touch are  agent systems were we wish  to
capture an  agent in a  Prolog goal.   Such  systems can be  implemented
using  threads  (see  section  ????)  that use  thread_send_message/2  and
thread_get_message/1 to communicate.    The  main problem  is that  each
thread is  associated by an  operating system thread.   OS threads  are,
depending on the OS,  relatively expensive.  Scalability of  this design
typically ends,  depending on OS and  hardware, somewhere between  1,000
and 100,000 agents.

Engines provide  an alternative.    A detached  Prolog engine  currently
requires  approximately 20  Kbytes memory  on 64  bit hardware,  growing
with the size of the Prolog stacks.  The Prolog  stacks may be minimised
by calling garbage_collect/0 followed by trim_stacks/0, providing a _d_e_e_p
_s_l_e_e_p mode.   The set  of agents, each represented  by an engine can  be
controlled by  a static  or dynamic  pool of  threads.   Scheduling  the
execution of agents  and their communication is completely open  and can
be optimised to satisfy the requirements of the application.

    This  section needs an example.  Preferably something that fits
    on  one page and would not scale using  threads.  Engines might
    work  nice to implement  _A_n_t_r_a_n_k_:  _A_n _a_n_t  _c_o_l_o_n_y _a_l_g_o_r_i_t_h_m _f_o_r
    _r_a_n_k_i_n_g _w_e_b _p_a_g_e_s.


1100..22 EEnnggiinnee rreessoouurrccee uussaaggee

A  Prolog engine  consists  of a  virtual  machine state  that  includes
the  Prolog  stacks.     An  `empty'  engine  requires  aout  20  KBytes
of  memory.    This grows  when  the  engine requires  additional  stack
space.   Anonymous engines are subject  to atom garbage collection  (see
garbage_collect_atoms/0).    Engines may be  reclaimed immediately  using
engine_destroy/1.  Calling engine_destroy/1 destroys the virtual machine
state,  while the  handle itself  is left  to  atom garbage  collection.
The  virtual machine  is reclaimed  as soon  as an  engine produced  its
last result,  failed or raised an  exception.   This implies that it  is
only advantageous  to call  engine_destroy/1 explicitly if  you are  not
interested in further answers.

Engines that are expected  to be left in inactive state for  a prelonged
time can  be minimized  by calling garbage_collect/0  and trimm_stacks/0
(in that order) before calling engine_yield/1 or succeeding.


1100..33 EEnnggiinnee pprreeddiiccaattee rreeffeerreennccee

This section documents  the built-in predicates that deal with  engines.
In addition to these,  most predicates dealing with threads  and message
queue can be used to access engines.


eennggiinnee__ccrreeaattee((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _?_E_n_g_i_n_e))                           _[_d_e_t_]


eennggiinnee__ccrreeaattee((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_E_n_g_i_n_e_, _+_O_p_t_i_o_n_s))                 _[_d_e_t_]
    Create a new engine  and unify _E_n_g_i_n_e with a handle to it.  _T_e_m_p_l_a_t_e
    and  _G_o_a_l  form a  pair  similar to  findall/3:   the  instantiation
    of  _T_e_m_p_l_a_t_e  becomes  available  though  engine_next/2  after  _G_o_a_l
    succeeds.    _O_p_t_i_o_n_s  is  a list  of  the following  options.    See
    thread_create/3 for details.

    aalliiaass((_+_N_a_m_e))
         Give the engine a name.  _N_a_m_e must be an atom.   If this option
         is provided, _E_n_g_i_n_e is unified  with _N_a_m_e.  The name  space for
         engines is shared with threads and mutexes.

    gglloobbaall((_K_B_y_t_e_s))
         Set the limit for the global stack in KBytes.

    llooccaall((_K_B_y_t_e_s))
         Set the limit for the local stack in KBytes.

    ttrraaiill((_K_B_y_t_e_s))
         Set the limit for the trail stack in KBytes.

    The  _E_n_g_i_n_e argument  of engine_create/3 may  be instantiated to  an
    atom, creating an engine with the given alias.


eennggiinnee__ddeessttrrooyy((_+_E_n_g_i_n_e))                                            _[_d_e_t_]
    Destroy _E_n_g_i_n_e.


eennggiinnee__nneexxtt((_+_E_n_g_i_n_e_, _-_T_e_r_m))                                    _[_s_e_m_i_d_e_t_]
    Ask the engine _E_n_g_i_n_e  to produce a next answer.  On this first call
    on  a specific  engine, the _G_o_a_l  of the engine  is started.   If  a
    previous  call returned  an answer through  completion, this  causes
    the  engine  to backtrack  and finally,  if  the engine  produces  a
    previous  result using engine_yield/1, execution proceeds after  the
    engine_yield/1 call.


eennggiinnee__nneexxtt__rreeiiffiieedd((_+_E_n_g_i_n_e_, _-_T_e_r_m))                                _[_d_e_t_]
    Similar  to  engine_next/2,  but  instead  of  success,  failure  or
    or  raising  an  exception,  _T_e_r_m  is  unified  with  one  of  terms
    below.   This predicate is provided primarily for compatibility with
    Lean Prolog.

    tthhee((_A_n_s_w_e_r))
         Goal succeeded with  _T_e_m_p_l_a_t_e bound to  _A_n_s_w_e_r or Goal  yielded
         with a term _A_n_s_w_e_r.

    nnoo
         Goal failed.

    eexxcceeppttiioonn((_E_x_c_e_p_t_i_o_n))
         Goal raises the error _E_x_c_e_p_t_i_o_n.


eennggiinnee__ppoosstt((_+_E_n_g_i_n_e_, _+_T_e_r_m))                                        _[_d_e_t_]
    Make _T_e_r_m  available to engine_fetch/1inside the _E_n_g_i_n_e.   This call
    must  be followed  by a call  to engine_next/2 and  the engine  must
    call engine_fetch/1.


eennggiinnee__ppoosstt((_+_E_n_g_i_n_e_, _+_T_e_r_m_, _-_R_e_p_l_y))                                _[_d_e_t_]
    Combines engine_post/2 and engine_next/2.


eennggiinnee__yyiieelldd((_+_T_e_r_m))                                                _[_d_e_t_]
    Called  from within the engine, causing engine_next/2 in  the caller
    to  return with  _T_e_r_m.   A subsequent  call to  engine_next/2 causes
    engine_yield/1 to  `return'.  This  predicate can only be called  if
    the  engine is not  involved in  a callback from  C, i.e., when  the
    engine  calls a predicate defined in C that calls back Prolog  it is
    not  possible to use this predicate.   Trying to do so results  in a
    permission_error exception.


eennggiinnee__ffeettcchh((_-_T_e_r_m))                                                _[_d_e_t_]
    Called  from within  the  engine to  fetch the  term made  available
    through  engine_post/2or engine_post/3.  If no term  is available an
    existence_error exception is raised.


eennggiinnee__sseellff((_-_E_n_g_i_n_e))                                               _[_d_e_t_]
    Called  from within the  engine to get access  to the handle to  the
    engine itself.


iiss__eennggiinnee((_@_T_e_r_m))                                               _[_s_e_m_i_d_e_t_]
    True  if _T_e_r_m is  a reference to  or the alias  name of an  existing
    engine.


ccuurrrreenntt__eennggiinnee((_-_E_n_g_i_n_e))                                         _[_n_o_n_d_e_t_]
    True when _E_n_g_i_n_e is an existing engine.


CChhaapptteerr 1111..  FFOORREEIIGGNN LLAANNGGUUAAGGEE IINNTTEERRFFAACCEE

SWI-Prolog  offers a  powerful interface  to C  [??].    The main  design
objectives  of  the  foreign  language  interface  are  flexibility  and
performance.   A foreign  predicate is  a C function  that has the  same
number  of arguments  as the  predicate represented.    C functions  are
provided to analyse the  passed terms, convert them to basic C  types as
well as to  instantiate arguments using unification.   Non-deterministic
foreign predicates are supported, providing the foreign  function with a
handle to control backtracking.

C can call  Prolog predicates, providing both  a query interface and  an
interface to extract multiple solutions from  a non-deterministic Prolog
predicate.    There is  no limit  to the  nesting of  Prolog calling  C,
calling Prolog, etc.   It is also possible to write the `main' in  C and
use Prolog as an embedded logical engine.


1111..11 OOvveerrvviieeww ooff tthhee IInntteerrffaaccee

A special include file called SWI-Prolog.h should be included  with each
C source  file that  is to be  loaded via  the foreign interface.    The
installation process installs this file in the directory  include in the
SWI-Prolog home directory (?- current_prolog_flag(home, Home).).  This C
header file  defines various data types,  macros and functions that  can
be used  to communicate with  SWI-Prolog.  Functions  and macros can  be
divided into the following categories:

  o Analysing Prolog terms

  o Constructing new terms

  o Unifying terms

  o Returning control information to Prolog

  o Registering foreign predicates with Prolog

  o Calling Prolog from C

  o Recorded database interactions

  o Global actions on Prolog (halt, break, abort, etc.)


1111..22 LLiinnkkiinngg FFoorreeiiggnn MMoodduulleess

Foreign modules  may be  linked to  Prolog in two  ways.   Using  _s_t_a_t_i_c
_l_i_n_k_i_n_g, the extensions,  a (short) file defining main()  which attaches
the extension  calls to  Prolog, and the  SWI-Prolog kernel  distributed
as a  C library, are linked  together to form a  new executable.   Using
_d_y_n_a_m_i_c _l_i_n_k_i_n_g,  the extensions  are linked  to a  shared library  (.so
file  on most  Unix  systems) or  dynamic  link  library (.DLL  file  on
Microsoft platforms) and loaded into the running Prolog process.


1111..22..11 WWhhaatt lliinnkkiinngg iiss pprroovviiddeedd??

The _s_t_a_t_i_c  _l_i_n_k_i_n_g schema can  be used on  all versions of  SWI-Prolog.
Whether or  not dynamic  linking is  supported can be  deduced from  the
Prolog  flag open_shared_object (see  current_prolog_flag/2).    If  this
Prolog flag yields true, open_shared_object/2 and related predicates are
defined.   See section ???? for  a suitable high-level interface to  these
predicates.


1111..22..22 WWhhaatt kkiinndd ooff llooaaddiinngg sshhoouulldd II bbee uussiinngg??

All  described  approaches  have  their  advantages  and  disadvantages.
Static linking  is portable and allows  for debugging on all  platforms.
It is relatively  cumbersome and the libraries  you need to pass to  the
linker  may vary  from  system to  system,  though the  utility  program
swipl-ld described  in section ????  often hides  these problems from  the
user.

Loading  shared objects  (DLL  files on  Windows) provides  sharing  and
protection  and is  generally the  best choice.    If a  saved state  is
created using qsave_program/[1,2], an initialization/1 directive  may be
used to load the appropriate library at startup.

Note  that  the  definition of  the  foreign  predicates  is  the  same,
regardless of the linking type used.


1111..22..33 lliibbrraarryy((sshhlliibb))::   UUttiilliittyy  lliibbrraarryy  ffoorr llooaaddiinngg  ffoorreeiiggnn  oobbjjeeccttss
       ((DDLLLLss,, sshhaarreedd oobbjjeeccttss))

This   section   discusses   the   functionality   of   the   (autoload)
library(shlib), providing an  interface to manage shared libraries.   We
describe the procedure for using a foreign resource (DLL  in Windows and
shared object in Unix) called mylib.

First,  one  must  assemble  the resource  and  make  it  compatible  to
SWI-Prolog.    The  details  for  this  vary between  platforms.     The
swipl-ld(1) utility can be used to deal with this  in a portable manner.
The typical commandline is:

________________________________________________________________________|                                                                        |
|swipl-ld|-o_mylib_file.{c,o,cc,C}_...__________________________________ |        |

Make  sure   that  one  of   the  files   provides  a  global   function
install_mylib()   that   initialises   the   module   using   calls   to
PL_register_foreign().   Here  is a  simple example  file mylib.c,  which
creates a Windows MessageBox:

________________________________________________________________________|                                                                        |

|#include <windows.h>                                                    |
|#include <SWI-Prolog.h>                                                 |
|                                                                        |
|static foreign_t                                                        |
|pl_say_hello(term_t to)                                                 |
|{ char *a;                                                              |

|                                                                        |
|  if ( PL_get_atom_chars(to, &a) )                                      |
|  { MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL);                |
|                                                                        |
|    PL_succeed;                                                         |
|  }                                                                     |
|                                                                        |
|  PL_fail;                                                              |

|}                                                                       |
|                                                                        |
|install_t                                                               |
|install_mylib()                                                         |
|{ PL_register_foreign("say_hello", 1, pl_say_hello, 0);                 |
|}|_____________________________________________________________________ | |

Now write a file mylib.pl:

________________________________________________________________________|                                                                        |

|:- module(mylib, [ say_hello/1 ]).                                      |
|:-|use_foreign_library(foreign(mylib)).________________________________ |  |

The file  mylib.pl can be  loaded as a normal  Prolog file and  provides
the predicate defined in C.


llooaadd__ffoorreeiiggnn__lliibbrraarryy((_:_F_i_l_e_S_p_e_c))                                    _[_d_e_t_]


llooaadd__ffoorreeiiggnn__lliibbrraarryy((_:_F_i_l_e_S_p_e_c_, _+_E_n_t_r_y_:_a_t_o_m))                       _[_d_e_t_]
    Load  a  _s_h_a_r_e_d _o_b_j_e_c_t  or  _D_L_L. After  loading the  _E_n_t_r_y  function
    is  called  without  arguments.    The  default  entry  function  is
    composed  from =install_=, followed by  the file  base-name.   E.g.,
    the  load-call below  calls the  function install_mylib().   If  the
    platform  prefixes extern functions  with =_=,  this prefix is  added
    before calling.

    ____________________________________________________________________|                                                                    |
    |       ...                                                          |

    |       load_foreign_library(foreign(mylib)),                        |
    ||______..._________________________________________________________ ||

    ___________________________________________________________Arguments_
     _F_i_l_e_S_p_e_c  is  a  specification  for  absolute_file_name/3.
               If  searching  the file  fails, the  plain  name

               is   passed  to  the  OS  to  try  the   default
               method  of the OS for locating foreign  objects.
               The  default  definition  of  file_search_path/2
               searches  <prolog home>/lib/<arch> on Unix and
               <prolog home>/bin on Windows.

         SSeeee aallssoo use_foreign_library/1,2 are  intended for  use in
             directives.


uussee__ffoorreeiiggnn__lliibbrraarryy((_+_F_i_l_e_S_p_e_c))                                     _[_d_e_t_]


uussee__ffoorreeiiggnn__lliibbrraarryy((_+_F_i_l_e_S_p_e_c_, _+_E_n_t_r_y_:_a_t_o_m))                        _[_d_e_t_]
    Load  and install a foreign  library as load_foreign_library/1,2  and
    register  the installation  using initialization/2  with the  option
    now.  This is similar to using:

    ____________________________________________________________________|                                                                    |
    ||:-_initialization(load_foreign_library(foreign(mylib))).__________ ||

    but  using the  initialization/1 wrapper  causes the  library to  be
    loaded  _a_f_t_e_r loading of the file in which it appears  is completed,
    while  use_foreign_library/1 loads the  library _i_m_m_e_d_i_a_t_e_l_y.    I.e.
    the  difference is only relevant if  the remainder of the file  uses
    functionality of the C-library.


uunnllooaadd__ffoorreeiiggnn__lliibbrraarryy((_+_F_i_l_e_S_p_e_c))                                  _[_d_e_t_]


uunnllooaadd__ffoorreeiiggnn__lliibbrraarryy((_+_F_i_l_e_S_p_e_c_, _+_E_x_i_t_:_a_t_o_m))                      _[_d_e_t_]
    Unload  a _s_h_a_r_e_d  _o_b_j_e_c_t or  _D_L_L. After calling  the _E_x_i_t  function,
    the  shared  object  is removed  from  the  process.    The  default
    exit  function is composed  from =uninstall_=,  followed by the  file
    base-name.


ccuurrrreenntt__ffoorreeiiggnn__lliibbrraarryy((_?_F_i_l_e_, _?_P_u_b_l_i_c))
    Query currently loaded shared libraries.


rreellooaadd__ffoorreeiiggnn__lliibbrraarriieess
    Reload  all  foreign  libraries loaded  (after  restore of  a  state
    created using qsave_program/2.


1111..22..44 LLooww--lleevveell ooppeerraattiioonnss oonn sshhaarreedd lliibbrraarriieess

The interface  defined in this  section allows the  user to load  shared
libraries  (.so files  on most  Unix systems,  .dll  files on  Windows).
This  interface is  portable to  Windows  as well  as to  Unix  machines
providing  dlopen(2)  (Solaris,  Linux,  FreeBSD, Irix  and  many  more)
or  shl_open(2) (HP/UX).  It  is  advised to  use  the  predicates  from
section ???? in your application.


ooppeenn__sshhaarreedd__oobbjjeecctt((_+_F_i_l_e_, _-_H_a_n_d_l_e))
    _F_i_l_e  is  the name  of a  shared object  file  (DLL in  MS-Windows).
    This   file  is  attached  to   the  current  process,  and   _H_a_n_d_l_e
    is   unified  with  a  handle  to  the  library.      Equivalent  to
    open_shared_object(File, Handle, []).  See also open_shared_object/3
    and load_foreign_library/1.

    On  errors, an  exception shared_object(_A_c_t_i_o_n_, _M_e_s_s_a_g_e) is  raised.
    _M_e_s_s_a_g_e is the return value from dlerror().


ooppeenn__sshhaarreedd__oobbjjeecctt((_+_F_i_l_e_, _-_H_a_n_d_l_e_, _+_O_p_t_i_o_n_s))
    As  open_shared_object/2, but  allows  for  additional flags  to  be
    passed.   _O_p_t_i_o_n_s is a list of  atoms.  now implies the  symbols are
    resolved  immediately rather  than lazy (default).   global  implies
    symbols of the  loaded object are visible while loading other shared
    objects (by default they  are local).  Note that these flags may not
    be  supported by your operating system.  Check the  documentation of
    dlopen() or equivalent  on your operating system.  Unsupported flags
    are silently ignored.


cclloossee__sshhaarreedd__oobbjjeecctt((_+_H_a_n_d_l_e))
    Detach the shared object identified by _H_a_n_d_l_e.


ccaallll__sshhaarreedd__oobbjjeecctt__ffuunnccttiioonn((_+_H_a_n_d_l_e_, _+_F_u_n_c_t_i_o_n))
    Call the named function  in the loaded shared library.  The function
    is  called  without  arguments  and the  return  value  is  ignored.
    Normally  this function installs  foreign language predicates  using
    calls to PL_register_foreign().


1111..22..55 SSttaattiicc LLiinnkkiinngg

Below  is an  outline  of the  file  structure required  for  statically
linking SWI-Prolog  with foreign extensions.    .../swipl refers to  the
SWI-Prolog home directory (see the  Prolog flag home).  <_a_r_c_h> refers to
the architecture identifier  that may be obtained using the  Prolog flag
arch.

   .../swipl/runtime/<_a_r_c_h>/libswipl.a SWI-Library
   .../swipl/include/SWI-Prolog.h      Include file
   .../swipl/include/SWI-Stream.h      Stream I/O include file
   .../swipl/include/SWI-Exports       Export declarations (AIX only)
   .../swipl/include/stub.c            Extension stub

The definition  of the  foreign predicates  is the same  as for  dynamic
linking.      Unlike  with  dynamic  linking,   however,  there  is   no
initialisation  function.   Instead,  the file  .../swipl/include/stub.c
may  be copied  to  your project  and  modified  to define  the  foreign
extensions.   Below is  stub.c, modified to  link the lowercase  example
described later in this chapter:

________________________________________________________________________|                                                                        |
|#include <stdio.h>                                                      |
|#include <SWI-Prolog.h>                                                 |

|                                                                        |
|extern foreign_t pl_lowercase(term, term);                              |
|                                                                        |
|PL_extension predicates[] =                                             |
|{                                                                       |
|/*{ "name",      arity,  function,      PL_FA_<flags> },*/              |
|                                                                        |

|  { "lowercase", 2       pl_lowercase,  0 },                            |
|  { NULL,        0,      NULL,          0 } /* terminating line */      |
|};                                                                      |
|                                                                        |
|                                                                        |
|int                                                                     |
|main(int argc, char **argv)                                             |
|{ PL_register_extensions(predicates);                                   |

|                                                                        |
|  if ( !PL_initialise(argc, argv) )                                     |
|    PL_halt(1);                                                         |
|                                                                        |
|  PL_halt(PL_toplevel() ? 0 : 1);                                       |
|}|_____________________________________________________________________ | |

Now,  a  new  executable may  be  created  by compiling  this  file  and
linking  it to  libpl.a from  the runtime  directory  and the  libraries
required  by both  the  extensions and  the  SWI-Prolog  kernel.    This
may be  done by  hand, or  by using  the swipl-ld  utility described  in
section ????.    If the  linking is performed  by hand,  the command  line
option -dump-runtime-variables  (see section ????) can  be used to  obtain
the  required paths,  libraries  and linking  options  to link  the  new
executable.


1111..33 IInntteerrffaaccee DDaattaa TTyyppeess


1111..33..11 TTyyppee term_t::  aa rreeffeerreennccee ttoo aa PPrroolloogg tteerrmm

The principal data  type is term_t.   Type term_t is what Quintus  calls
QP_term_ref.   This name indicates  better what the type represents:   it
is a _h_a_n_d_l_e for a  term rather than the term itself.  Terms can  only be
represented and manipulated  using this type, as  this is the only  safe
way to  ensure the  Prolog kernel is  aware of  all terms referenced  by
foreign code  and thus allows the  kernel to perform garbage  collection
and/or stack-shifts while foreign  code is active, for example  during a
callback from C.

A term  reference is  a C unsigned  long, representing  the offset of  a
variable on the Prolog environment stack.  A  foreign function is passed
term references for the predicate arguments, one for each  argument.  If
references for intermediate  results are needed, such references  may be
created using PL_new_term_ref() or PL_new_term_refs().   These references
normally live till the foreign function returns control  back to Prolog.
Their scope can  be explicitly limited using PL_open_foreign_frame() and
PL_close_foreign_frame()/PL_discard_foreign_frame().

A term_t always refers to a valid Prolog term (variable,  atom, integer,
float  or compound  term).    A  term  lives either  until  backtracking
takes  us back  to a  point before  the term  was created,  the  garbage
collector  has collected  the term,  or  the term  was created  after  a
PL_open_foreign_frame()and PL_discard_foreign_frame()has been called.

The  foreign interface  functions can  either _r_e_a_d,  _u_n_i_f_y  or _w_r_i_t_e  to
term references.   In  this document we use  the following notation  for
arguments of type term_t:

     term_t +t  Accessed in  read-mode.  The  `+' indicates the
                argument is `input'.
     term_t -t  Accessed in write-mode.
     term_t ?t  Accessed in unify-mode.

WWAARRNNIINNGG  Term references  that are  accessed in  `write'  (-) mode  will
refer to an  invalid term if the term  is allocated on the global  stack
and backtracking takes us  back to a point before the term  was written.
Compounds, large integers,  floats and strings are all allocated  on the
global stack.  Below  is a typical scenario where this may happen.   The
first solution writes a term extracted from the solution into  _a.  After
the system backtracks  due to PL_next_solution(), _a becomes a  reference
to a term that no longer exists.

________________________________________________________________________|                                                                        |
|term_t a = PL_new_term_ref();                                           |

|...                                                                     |
|query = PL_open_query(...);                                             |
|while(PL_next_solution(query))                                          |
|{ PL_get_arg(i, ..., a);                                                |
|}                                                                       |
|PL_close_query(query);|________________________________________________ |                      |

There are  two solutions  to this problem.    One is to  scope the  term
reference using  PL_open_foreign_frame()and PL_close_foreign_frame() and
makes  sure it  goes out  of scope  before backtracking  happens.    The
other  is to  clear the  term reference  using  PL_put_variable() before
backtracking.

Term references are obtained in any of the following ways:

  o _P_a_s_s_e_d _a_s _a_r_g_u_m_e_n_t
    The  C functions  implementing foreign predicates  are passed  their
    arguments  as term  references.   These  references may  be read  or
    unified.  Writing to these variables causes undefined behaviour.

  o _C_r_e_a_t_e_d _b_y PL_new_term_ref()
    A  term  created  by  PL_new_term_ref() is normally  used  to  build
    temporary terms or  to be written by one of the interface functions.
    For  example, PL_get_arg() writes a reference  to the term  argument
    in its last argument.

  o _C_r_e_a_t_e_d _b_y PL_new_term_refs(_i_n_t _n)
    This  function  returns  a set  of  term  references with  the  same
    characteristics as PL_new_term_ref().  See PL_open_query().

  o _C_r_e_a_t_e_d _b_y PL_copy_term_ref(_t_e_r_m___t _t)
    Creates a new term  reference to the same term as the argument.  The
    term may be written to.  See figure ????.

Term  references can  safely be  copied  to other  C variables  of  type
term_t, but all copies will always refer to the same term.


term_t PPLL__nneeww__tteerrmm__rreeff()
    Return  a fresh reference  to a  term.   The reference is  allocated
    on  the _l_o_c_a_l  stack.   Allocating a  term reference  may trigger  a
    stack-shift  on machines  that cannot use  sparse memory  management
    for  allocation  of  the Prolog  stacks.    The  returned  reference
    describes a variable.


term_t PPLL__nneeww__tteerrmm__rreeffss(_i_n_t _n)
    Return  _n  new  term  references.    The  first  term  reference  is
    returned.   The others are _t +1, _t +2, etc.   There are two reasons
    for  using this function.   PL_open_query()expects the  arguments as
    a  set of consecutive term  references, and _v_e_r_y time-critical  code
    requiring a number of term references can be written as:

    ____________________________________________________________________|                                                                    |
    | pl_mypredicate(term_t a0, term_t a1)                               |

    | { term_t t0 = PL_new_term_refs(2);                                 |
    |   term_t t1 = t0+1;                                                |
    |                                                                    |
    |   ...                                                              |
    ||}_________________________________________________________________ ||


term_t PPLL__ccooppyy__tteerrmm__rreeff(_t_e_r_m___t _f_r_o_m)
    Create a new term  reference and make it point initially to the same
    term  as _f_r_o_m.  This function  is commonly used to copy  a predicate
    argument to a term reference that may be written.


void PPLL__rreesseett__tteerrmm__rreeffss(_t_e_r_m___t _a_f_t_e_r)
    Destroy  all term  references that  have been  created after  _a_f_t_e_r,
    including  _a_f_t_e_r itself.    Any  reference to  the invalidated  term
    references after this call results in undefined behaviour.

    Note  that  returning  from  the  foreign  context  to  Prolog  will
    reclaim  all references  used in  the foreign  context.   This  call
    is  only necessary  if  references are  created inside  a loop  that
    never  exits  back to  Prolog.    See  also  PL_open_foreign_frame(),
    PL_close_foreign_frame() and PL_discard_foreign_frame().


1111..33..11..11 IInntteerraaccttiioonn wwiitthh tthhee ggaarrbbaaggee ccoolllleeccttoorr aanndd ssttaacckk--sshhiifftteerr

Prolog implements two  mechanisms for avoiding stack overflow:   garbage
collection and stack expansion.   On machines that allow for  it, Prolog
will use virtual  memory management to detect stack overflow  and expand
the  runtime stacks.    On  other machines  Prolog will  reallocate  the
stacks and  update all  pointers to them.    To do so,  Prolog needs  to
know which data  is referenced by C code.   As all Prolog data  known by
C is  referenced through  term references (term_t),  Prolog has all  the
information necessary to  perform its memory management without  special
precautions from the C programmer.


1111..33..22 OOtthheerr ffoorreeiiggnn iinntteerrffaaccee ttyyppeess

aattoomm__tt An atom in Prolog's internal representation.   Atoms are pointers
    to  an  opaque structure.    They are  a  unique representation  for
    represented  text, which  implies that  atom A  represents the same
    text as atom B  if and only if A and B are the same pointer.

    Atoms  are  the  central  representation for  textual  constants  in
    Prolog.    The transformation of  a character  string C  to an atom
    implies  a hash-table lookup.  If the same atom is needed  often, it
    is  advised to  store its reference  in a  global variable to  avoid
    repeated lookup.

ffuunnccttoorr__tt A  functor is  the  internal  representation of  a  name/arity
    pair.   They are used to find the name and arity of  a compound term
    as  well as to construct new compound  terms.  Like atoms  they live
    for the whole Prolog session and are unique.

pprreeddiiccaattee__tt Handle  to a  Prolog  predicate.    Predicate  handles  live
    forever (although they can lose their definition).

qqiidd__tt Query identifier.  Used by  PL_open_query(), PL_next_solution() and
    PL_close_query() to handle backtracking from C.

ffiidd__tt Frame   identifier.       Used   by   PL_open_foreign_frame()  and
    PL_close_foreign_frame().

mmoodduullee__tt A module is  a unique handle to a  Prolog module.  Modules  are
    used only to call predicates in a specific module.

ffoorreeiiggnn__tt Return type for a C function implementing a Prolog predicate.

ccoonnttrrooll__tt Passed  as additional  argument to  non-deterministic  foreign
    functions.  See PL_retry*() and PL_foreign_context*().

iinnssttaallll__tt Type for the install() and uninstall() functions  of shared or
    dynamic link libraries.  See section ????.

iinntt6644__tt Actually  part of  the C99  standard  rather than  Prolog.    As
    of  version  5.5.6,  Prolog integers  are  64-bit on  all  hardware.
    The  C99 type  int64_t is defined  in the  stdint.h standard  header
    and  provides platform-independent 64-bit  integers.  Portable  code
    accessing  Prolog should use this  type to exchange integer  values.
    Please  note that PL_get_long() can return FALSE on Prolog  integers
    that  cannot be represented  as a C  long.   Robust code should  not
    assume  any of the  integer fetching functions  to succeed, _e_v_e_n  if
    the Prolog term is known to be an integer.


1111..33..22..11 PPLL__AARRIITTYY__AASS__SSIIZZEE

As of  SWI-Prolog 7.3.12,  the arity of  terms has  changed from int  to
size_t.   To deal  with this  transition, all  affecting functions  have
two versions, where  the old name exchanges the  arity as int and a  new
function  with name  *_sz() exchanges  the arity  as size_t.    If the  C
macro PL_ARITY_AS_SIZE is defined before loading SWI-Prolog.h,  macros are
put in  place that  map the old  names to  the new functions.    Without
precautions, the  old code is compatible,  but the following warning  is
printed when compiling:

________________________________________________________________________|                                                                        |
|#warning "Term arity has changed from int to size_t."                   |

|#warning|"Please_update_your_code_and_use_#define_PL_ARITY_AS_SIZE_1."_ |        |

To make the code  compile silently again, include SWI-Prolog.h as  below
and change  the types  you use to  represent arity  from int  to size_t.
Please be aware that size_t is _u_n_s_i_g_n_e_d.

________________________________________________________________________|                                                                        |
|#define PL_ARITY_AS_SIZE                                                |
|#include|<SWI-Prolog.h>________________________________________________ |        |


1111..44 TThhee FFoorreeiiggnn IInncclluuddee FFiillee


1111..44..11 AArrgguummeenntt PPaassssiinngg aanndd CCoonnttrrooll

If  Prolog encounters  a foreign  predicate  at run  time it  will  call
a  function  specified  in  the  predicate  definition  of  the  foreign
predicate.   The arguments 1;:::; <_a_r_i_t_y>pass the  Prolog arguments to the
goal as  Prolog terms.   Foreign  functions should  be declared of  type
foreign_t.   Deterministic foreign  functions have  two alternatives  to
return control back to Prolog:


_(_r_e_t_u_r_n_) _f_o_r_e_i_g_n___t PPLL__ssuucccceeeedd(())
    Succeed deterministically.  PL_succeed is defined as return TRUE.


_(_r_e_t_u_r_n_) _f_o_r_e_i_g_n___t PPLL__ffaaiill(())
    Fail  and  start  Prolog  backtracking.     PL_fail  is  defined  as
    return FALSE.


1111..44..11..11 NNoonn--ddeetteerrmmiinniissttiicc FFoorreeiiggnn PPrreeddiiccaatteess

By  default   foreign  predicates   are  deterministic.      Using   the
PL_FA_NONDETERMINISTIC   attribute  (see   PL_register_foreign())  it   is
possible  to register  a  predicate  as a  non-deterministic  predicate.
Writing   non-deterministic   foreign  predicates   is   slightly   more
complicated  as  the  foreign function  needs  context  information  for
generating  the next  solution.   Note  that the  same foreign  function
should  be  prepared  to be  simultaneously  active  in  more  than  one
goal.     Suppose  the  natural_number_below_n/2  is  a  non-deterministic
foreign predicate, backtracking over all natural numbers  lower than the
first argument.  Now consider the following predicate:

________________________________________________________________________|                                                                        |
|quotient_below_n(Q, N) :-                                               |

|        natural_number_below_n(N, N1),                                  |
|        natural_number_below_n(N, N2),                                  |
||_______Q_=:=_N1_/_N2,_!.______________________________________________ ||

In  this predicate  the function  natural_number_below_n/2  simultaneously
generates solutions for both its invocations.

Non-deterministic foreign functions  should be prepared to handle  three
different calls from Prolog:

  o _I_n_i_t_i_a_l _c_a_l_l _(PL_FIRST_CALL_)
    Prolog  has just created a frame  for the foreign function and  asks
    it to produce the first answer.

  o _R_e_d_o _c_a_l_l _(PL_REDO_)
    The previous invocation  of the foreign function associated with the
    current  goal indicated it was possible  to backtrack.  The  foreign
    function should produce the next solution.

  o _T_e_r_m_i_n_a_t_e _c_a_l_l _(PL_PRUNED_)
    The choice point  left by the foreign function has been destroyed by
    a  cut.  The foreign function is given the opportunity to  clean the
    environment.

Both  the  context  information  and  the  type  of   call  is  provided
by  an  argument  of  type  control_t  appended  to  the  argument  list
for  deterministic foreign  functions.   The  macro PL_foreign_control()
extracts  the   type  of  call   from  the  control   argument.      The
foreign  function  can  pass  a context  handle  using  the  PL_retry*()
macros  and  extract  the handle  from  the  extra  argument  using  the
PL_foreign_context*() macro.


_(_r_e_t_u_r_n_) _f_o_r_e_i_g_n___t PPLL__rreettrryy((_i_n_t_p_t_r___t _v_a_l_u_e))
    The  foreign function  succeeds while leaving  a choice  point.   On
    backtracking  over this  goal the  foreign function  will be  called
    again,  but  the  control argument  now  indicates  it is  a  `Redo'
    call  and the macro  PL_foreign_context() returns the handle  passed
    via  PL_retry().   This handle is  a signed  value two bits  smaller
    than  a  pointer,  i.e.,  30  or 62  bits  (two bits  are  used  for
    status  indication).    Defined as  return _PL_retry(_n).    See  also
    PL_succeed().


_(_r_e_t_u_r_n_) _f_o_r_e_i_g_n___t PPLL__rreettrryy__aaddddrreessss((_v_o_i_d _*))
    As  PL_retry(),  but ensures  an address as  returned by malloc()  is
    correctly  recovered  by PL_foreign_context_address().    Defined  as
    return  _PL_retry_address(_n).  See also PL_succeed().


_i_n_t PPLL__ffoorreeiiggnn__ccoonnttrrooll((_c_o_n_t_r_o_l___t))
    Extracts  the type of  call from the control  argument.  The  return
    values  are  described above.    Note that  the  function should  be
    prepared  to handle the PL_PRUNED case and should be aware  that the
    other arguments are not valid in this case.


_i_n_t_p_t_r___t PPLL__ffoorreeiiggnn__ccoonntteexxtt((_c_o_n_t_r_o_l___t))
    Extracts  the context from the context  argument.  If the call  type
    is  PL_FIRST_CALL the context value is 0L. Otherwise it  is the value
    returned  by the last PL_retry() associated with this goal  (both if
    the call type is PL_REDO or PL_PRUNED).


_v_o_i_d _* PPLL__ffoorreeiiggnn__ccoonntteexxtt__aaddddrreessss((_c_o_n_t_r_o_l___t))
    Extracts an address as passed in by PL_retry_address().


_p_r_e_d_i_c_a_t_e___t PPLL__ffoorreeiiggnn__ccoonntteexxtt__pprreeddiiccaattee((_c_o_n_t_r_o_l___t))
    Fetch  the Prolog predicate that is  executing this function.   Note
    that if the  predicate is imported, the returned predicate refers to
    the  final definition rather than the imported predicate,  i.e., the
    module  reported by PL_predicate_info() is the  module in which  the
    predicate  is defined rather  than the module  where it was  called.
    See also PL_predicate_info().

Note:     If  a   non-deterministic  foreign   function  returns   using
PL_succeed() or  PL_fail(),  Prolog  assumes the  foreign  function  has
cleaned its environment.   NNoo call with control  argument PL_PRUNED will
follow.

The code of figure  ???? shows a skeleton for a  non-deterministic foreign
predicate definition.
________________________________________________________________________|                                                                        |
|typedef struct                  /* define a context structure */        |

|{ ...                                                                   |
|} context;                                                              |
|                                                                        |
|foreign_t                                                               |
|my_function(term_t a0, term_t a1, control_t handle)                     |
|{ struct context * ctxt;                                                |
|                                                                        |
|  switch( PL_foreign_control(handle) )                                  |

|  { case PL_FIRST_CALL:                                                 |
|        ctxt = malloc(sizeof(struct context));                          |
|        ...                                                             |
|        PL_retry_address(ctxt);                                         |
|    case PL_REDO:                                                       |
|        ctxt = PL_foreign_context_address(handle);                      |
|        ...                                                             |

|        PL_retry_address(ctxt);                                         |
|    case PL_PRUNED:                                                     |
|        ctxt = PL_foreign_context_address(handle);                      |
|        ...                                                             |
|        free(ctxt);                                                     |
|        PL_succeed;                                                     |
|  }                                                                     |
|}|_____________________________________________________________________ | |

     Figure 11.1:  Skeleton for non-deterministic foreign functions


1111..44..22 AAttoommss aanndd ffuunnccttoorrss

The  following  functions  provide for  communication  using  atoms  and
functors.


atom_t PPLL__nneeww__aattoomm(_c_o_n_s_t _c_h_a_r _*)
    Return an atom handle  for the given C-string.  This function always
    succeeds.    The returned handle  is valid  as long as  the atom  is
    referenced  (see section ????).   The following atoms are provided  as
    macros,  giving access  to the  empty list  symbol and  the name  of
    the  list constructor.   Prior  to version 7,  ATOM_nil is the  same
    as  PL_new_atom(_"_[_]_") and ATOM_dot is the  same as PL_new_atom(_"_._").
    This is no long the case in SWI-Prolog version 7.


_a_t_o_m___t AATTOOMM__nniill((_A))
     tomic  constant  that  represents  the  empty  list.     It  is
     adviced  to  use  PL_get_nil(),  PL_put_nil() or  PL_unify_nil()
     where applicable.


_a_t_o_m___t AATTOOMM__ddoott((_A))
     tomic  constant that  represents  the  name of  the  list  con-
     structor.    The  list  constructor  itself  is  created  using
     PL_new_functor(_A_T_O_M___d_o_t_,_2).  It is adviced to use PL_get_list(),
     PL_put_list()or PL_unify_list() where applicable.


atom_t PPLL__nneeww__aattoomm__mmbbcchhaarrss(_i_n_t _r_e_p_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    This  function  generalizes  PL_new_atom()  and  PL_new_atom_nchars()
    while  allowing for  multiple encodings.   The  _r_e_p argument is  one
    of  REP_ISO_LATIN_1, REP_UTF8 or REP_MB. If _l_e_n is  (size_t)-1,  it is
    computed from _s using strlen().


const char* PPLL__aattoomm__cchhaarrss(_a_t_o_m___t _a_t_o_m)
    Return  a C-string for the text represented by the given atom.   The
    returned  text will not be changed by Prolog.  It is  not allowed to
    modify  the contents, not even `temporary' as the string  may reside
    in  read-only memory.   The returned  string becomes invalid if  the
    atom  is garbage  collected  (see section  ????).   Foreign  functions
    that  require the text from an atom passed in  a term_t  normally use
    PL_get_atom_chars() or PL_get_atom_nchars().


functor_t PPLL__nneeww__ffuunnccttoorr(_a_t_o_m___t _n_a_m_e_, _i_n_t _a_r_i_t_y)
    Returns  a _f_u_n_c_t_o_r  _i_d_e_n_t_i_f_i_e_r, a  handle for  the name/arity  pair.
    The returned handle is valid for the entire Prolog session.


atom_t PPLL__ffuunnccttoorr__nnaammee(_f_u_n_c_t_o_r___t _f)
    Return an atom representing the name of the given functor.


size_t PPLL__ffuunnccttoorr__aarriittyy(_f_u_n_c_t_o_r___t _f)
    Return the arity of the given functor.


1111..44..22..11 AAttoommss aanndd aattoomm ggaarrbbaaggee ccoolllleeccttiioonn

With  the introduction  of  atom garbage  collection in  version  3.3.0,
atoms  no  longer  live  as  long  as  the  process.    Instead,   their
lifetime is  guaranteed only as  long as  they are referenced.   In  the
single-threaded version,  atom garbage collections  are only invoked  at
the _c_a_l_l_-_p_o_r_t.    In the multithreaded  version (see  chapter ????),  they
appear asynchronously, except for the invoking thread.

For dealing with  atom garbage collection, two additional  functions are
provided:


void PPLL__rreeggiisstteerr__aattoomm(_a_t_o_m___t _a_t_o_m)
    Increment  the reference count  of the  atom by one.   PL_new_atom()
    performs  this automatically,  returning  an atom  with a  reference
    count of at least one.


void PPLL__uunnrreeggiisstteerr__aattoomm(_a_t_o_m___t _a_t_o_m)
    Decrement  the reference count of the atom.  If the  reference count
    drops below zero, an assertion error is raised.

Please note that the  following two calls are different with  respect to
atom garbage collection:

________________________________________________________________________|                                                                        |

|PL_unify_atom_chars(t, "text");                                         |
|PL_unify_atom(t,|PL_new_atom("text"));_________________________________ |                |

The  latter increments  the  reference count  of  the atom  text,  which
effectively ensures the atom will never be collected.   It is advised to
use the *_chars() or *_nchars() functions whenever applicable.


1111..44..33 AAnnaallyyssiinngg TTeerrmmss vviiaa tthhee FFoorreeiiggnn IInntteerrffaaccee

Each argument  of a foreign function  (except for the control  argument)
is of type term_t, an opaque  handle to a Prolog term.  Three  groups of
functions are  available for  the analysis  of terms.    The first  just
validates the  type,  like the  Prolog predicates var/1,  atom/1,  etc.,
and are  called PL_is_*().   The second  group attempts to translate  the
argument into a C primitive type.   These predicates take a term_t and a
pointer to the appropriate C type and return TRUE  or FALSE depending on
successful or unsuccessful translation.   If the translation fails,  the
pointed-to data is never modified.


1111..44..33..11 TTeessttiinngg tthhee ttyyppee ooff aa tteerrmm


int PPLL__tteerrmm__ttyyppee(_t_e_r_m___t)
    Obtain  the type  of a  term,  which should  be a  term returned  by
    one  of the  other interface  predicates or passed  as an  argument.
    The  function  returns the  type  of  the Prolog  term.    The  type
    identifiers  are listed below.   Note that the extraction  functions
    PL_get_*() also validate  the type and  thus the two sections  below
    are equivalent.

    ____________________________________________________________________|                                                                    |
    |         if ( PL_is_atom(t) )                                       |

    |         { char *s;                                                 |
    |                                                                    |
    |           PL_get_atom_chars(t, &s);                                |
    |           ...;                                                     |
    |         }                                                          |
    |                                                                    |
    | or                                                                 |
    |                                                                    |

    |         char *s;                                                   |
    |         if ( PL_get_atom_chars(t, &s) )                            |
    |         { ...;                                                     |
    ||________}_________________________________________________________ ||

    VVeerrssiioonn  77  added PL_NIL, PL_BLOB,  PL_LIST_PAIR  and PL_DICT.  Older
    versions  classify  PL_NIL  and PL_BLOB  as PL_ATOM,  PL_LIST_PAIR  as
    PL_TERM and do not have dicts.

    _______________________________________________________________
    | PL_VARIABLE            |A variable or attributed variable    |
    | PL_ATOM                |A Prolog atom                        |
    | PL_NIL                 |The constant []                      |
    | PL_BLOB                |A blob (see section ????)              |
    | PL_STRING              |A string (see section ????)            |
    | PL_INTEGER             |A integer                            |

    | PL_FLOAT               |A floating point number              |
    | PL_TERM                |A compound term                      |
    | PL_LIST_PAIR           |A list cell ([H|T])                  |
    |_PL_DICT________________|A_dict_(see_section_????))_____________|

The functions PL_is_<_t_y_p_e> are an alternative to PL_term_type().  The test
PL_is_variable(_t_e_r_m) is equivalent to  PL_term_type(_t_e_r_m)== PL_VARIABLE,
but  the first  is considerably  faster.   On  the other  hand, using  a
switch over  PL_term_type() is faster  and more readable  then using  an
if-then-else using  the functions  below.   All  these functions  return
either TRUE or FALSE.


int PPLL__iiss__vvaarriiaabbllee(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is a variable.


int PPLL__iiss__ggrroouunndd(_t_e_r_m___t)
    Returns  non-zero if  _t_e_r_m is  a ground term.    See also  ground/1.
    This function is cycle-safe.


int PPLL__iiss__aattoomm(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is an atom.


int PPLL__iiss__ssttrriinngg(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is a string.


int PPLL__iiss__iinntteeggeerr(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is an integer.


int PPLL__iiss__ffllooaatt(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is a float.


int PPLL__iiss__ccaallllaabbllee(_t_e_r_m___t)
    Returns  non-zero if _t_e_r_m  is a callable term.   See callable/1  for
    details.


int PPLL__iiss__ccoommppoouunndd(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is a compound term.


int PPLL__iiss__ffuunnccttoorr(_t_e_r_m___t_, _f_u_n_c_t_o_r___t)
    Returns  non-zero if _t_e_r_m  is compound and  its functor is  _f_u_n_c_t_o_r.
    This  test is  equivalent to  PL_get_functor(),  followed by  testing
    the functor, but easier to write and faster.


int PPLL__iiss__lliisstt(_t_e_r_m___t)
    Returns  non-zero  if  _t_e_r_m  is  a  compound  term  using  the  list
    constructor  or  the list  terminator.    See also  PL_is_pair() and
    PL_skip_list().


int PPLL__iiss__ppaaiirr(_t_e_r_m___t)
    Returns  non-zero  if  _t_e_r_m  is  a  compound  term  using  the  list
    constructor.  See also PL_is_list() and PL_skip_list().


int PPLL__iiss__aattoommiicc(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is atomic (not variable or compound).


int PPLL__iiss__nnuummbbeerr(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is an integer or float.


int PPLL__iiss__aaccyycclliicc(_t_e_r_m___t)
    Returns non-zero if _t_e_r_m is acyclic (i.e. a finite tree).


1111..44..33..22 RReeaaddiinngg ddaattaa ffrroomm aa tteerrmm

The functions PL_get_*() read information from  a Prolog term.  Most  of
them take two arguments.  The first is the input  term and the second is
a pointer to the output value or a term reference.


int PPLL__ggeett__aattoomm(_t_e_r_m___t _+_t_, _a_t_o_m___t _*_a)
    If _t is an atom,  store the unique atom identifier over _a.  See also
    PL_atom_chars() and PL_new_atom().   If there is  no need to  access
    the data (characters)  of an atom, it is advised to manipulate atoms
    using  their handle.  As the  atom is referenced by _t, it  will live
    at  least as long as _t does.   If longer live-time is required,  the
    atom should be locked using PL_register_atom().


int PPLL__ggeett__aattoomm__cchhaarrss(_t_e_r_m___t _+_t_, _c_h_a_r _*_*_s)
    If  _t is an atom, store a  pointer to a 0-terminated C-string  in _s.
    It is explicitly  nnoott allowed to modify the contents of this string.
    Some  built-in  atoms may  have the  string  allocated in  read-only
    memory, so `temporary manipulation' can cause an error.


int PPLL__ggeett__ssttrriinngg__cchhaarrss(_t_e_r_m___t _+_t_, _c_h_a_r _*_*_s_, _s_i_z_e___t _*_l_e_n)
    If  _t  is  a  string  object,  store a  pointer  to  a  0-terminated
    C-string  in _s  and the  length of  the string in  _l_e_n.   Note  that
    this pointer is  invalidated by backtracking, garbage collection and
    stack-shifts,  so generally the only save operations are to  pass it
    immediately to a C function that doesn't involve Prolog.


int PPLL__ggeett__cchhaarrss(_t_e_r_m___t _+_t_, _c_h_a_r _*_*_s_, _u_n_s_i_g_n_e_d _f_l_a_g_s)
    Convert  the argument term _t to  a 0-terminated C-string.  _f_l_a_g_s  is
    a  bitwise disjunction  from two  groups of  constants.   The  first
    specifies  which  term  types should  be  converted and  the  second
    how  the argument  is stored.   Below  is a  specification of  these
    constants.   BUF_RING implies, if the data is  not static (as from an
    atom), that the data  is copied to the next buffer from a ring of 16
    buffers.   This is a convenient way of converting multiple arguments
    passed  to a foreign predicate to C-strings.  If BUF_MALLOC is used,
    the data must be freed using PL_free() when no longer needed.

    With  the introduction of wide characters (see section ????),  not all
    atoms  can be converted into a char*.   This function fails if  _t is
    of the wrong type,  but also if the text cannot be represented.  See
    the REP_* flags below for details.

    CCVVTT__AATTOOMM
         Convert if term is an atom.

    CCVVTT__SSTTRRIINNGG
         Convert if term is a string.

    CCVVTT__LLIISSTT
         Convert if term is a list of of character codes.

    CCVVTT__IINNTTEEGGEERR
         Convert if term is an integer.

    CCVVTT__FFLLOOAATT
         Convert if term  is a float.   The characters returned are  the
         same as write/1 would write for the floating point number.

    CCVVTT__NNUUMMBBEERR
         Convert if term is an integer or float.

    CCVVTT__AATTOOMMIICC
         Convert if term is atomic.

    CCVVTT__VVAARRIIAABBLLEE
         Convert variable to print-name

    CCVVTT__WWRRIITTEE
         Convert any  term that  is not converted  by any  of the  other
         flags using  write/1.   If  no BUF_* is  provided, BUF_RING  is
         implied.

    CCVVTT__WWRRIITTEE__CCAANNOONNIICCAALL
         As CVT_WRITE, but using write_canonical/2.

    CCVVTT__WWRRIITTEEQQ
         As CVT_WRITE, but using writeq/2.

    CCVVTT__AALLLL
         Convert if term  is any of  the above, except  for CVT_VARIABLE
         and CVT_WRITE*.

    CCVVTT__EEXXCCEEPPTTIIOONN
         If conversion fails  due to a type  error, raise a Prolog  type
         error exception in addition to failure

    BBUUFF__DDIISSCCAARRDDAABBLLEE
         Data must copied immediately

    BBUUFF__RRIINNGG
         Data is stored in a ring of buffers

    BBUUFF__MMAALLLLOOCC
         Data is copied to a new buffer  returned by PL_malloc(3).   When
         no longer needed the user must call PL_free() on the data.

    RREEPP__IISSOO__LLAATTIINN__11
         Text is  in ISO  Latin-1 encoding and  the call  fails if  text
         cannot be represented.   This flag has the value 0 and  is thus
         the default.

    RREEPP__UUTTFF88
         Convert the text to a UTF-8 string.  This works for all text.

    RREEPP__MMBB
         Convert  to  default locale-defined  8-bit  string.     Success
         depends on the locale.  Conversion is done  using the wcrtomb()
         C library function.


int PPLL__ggeett__lliisstt__cchhaarrss(_+_t_e_r_m___t _l_, _c_h_a_r _*_*_s_, _u_n_s_i_g_n_e_d _f_l_a_g_s)
    Same  as PL_get_chars(_l_, _s_, _C_V_T___L_I_S_T___f_l_a_g_s), provided _f_l_a_g_s  contains
    none of the CVT_* flags.


int PPLL__ggeett__iinntteeggeerr(_+_t_e_r_m___t _t_, _i_n_t _*_i)
    If  _t is  a Prolog  integer, assign  its value over  _i.   On  32-bit
    machines,  this is the  same as PL_get_long(), but avoids a  warning
    from the compiler.  See also PL_get_long().


int PPLL__ggeett__lloonngg(_t_e_r_m___t _+_t_, _l_o_n_g _*_i)
    If  _t is a Prolog integer that can be represented as a  long, assign
    its value over _i.   If _t is an integer that cannot be represented by
    a  C long,  this function returns  FALSE. If _t  is a floating  point
    number that can  be represented as a long, this function succeeds as
    well.  See also PL_get_int64().


int PPLL__ggeett__iinntt6644(_t_e_r_m___t _+_t_, _i_n_t_6_4___t _*_i)
    If  _t is  a Prolog integer  or float  that can be  represented as  a
    int64_t, assign its value over _i.


int PPLL__ggeett__iinnttppttrr(_t_e_r_m___t _+_t_, _i_n_t_p_t_r___t _*_i)
    Get  an integer that  is at  least as wide  as a pointer.   On  most
    platforms  this is the same as PL_get_long(), but on  Win64 pointers
    are  8 bytes and longs  only 4.  Unlike  PL_get_pointer(), the  value
    is not modified.


int PPLL__ggeett__bbooooll(_t_e_r_m___t _+_t_, _i_n_t _*_v_a_l)
    If _t has the value  true or false, set _v_a_l to the C constant TRUE or
    FALSE and return success, otherwise return failure.


int PPLL__ggeett__ppooiinntteerr(_t_e_r_m___t _+_t_, _v_o_i_d _*_*_p_t_r)
    In the current  system, pointers are represented by Prolog integers,
    but  need some manipulation to make  sure they do not get  truncated
    due  to  the limited  Prolog integer  range.    PL_put_pointer() and
    PL_get_pointer() guarantee  pointers in  the range  of malloc()  are
    handled without truncating.


int PPLL__ggeett__ffllooaatt(_t_e_r_m___t _+_t_, _d_o_u_b_l_e _*_f)
    If _t is a float or integer, its value is assigned over _f.


int PPLL__ggeett__ffuunnccttoorr(_t_e_r_m___t _+_t_, _f_u_n_c_t_o_r___t _*_f)
    If  _t  is  compound  or  an  atom,   the  Prolog  representation  of
    the   name-arity  pair  will  be  assigned   over  _f.     See   also
    PL_get_name_arity() and PL_is_functor().


int PPLL__ggeett__nnaammee__aarriittyy(_t_e_r_m___t _+_t_, _a_t_o_m___t _*_n_a_m_e_, _s_i_z_e___t _*_a_r_i_t_y)
    If  _t is  compound or  an atom,  the functor name  will be  assigned
    over  _n_a_m_e and the arity over _a_r_i_t_y.   See also PL_get_functor() and
    PL_is_functor().  See section ????.


int PPLL__ggeett__ccoommppoouunndd__nnaammee__aarriittyy(_t_e_r_m___t _+_t_, _a_t_o_m___t _*_n_a_m_e_, _s_i_z_e___t _*_a_r_i_t_y)
    If  _t is compound term, the functor name will be assigned  over _n_a_m_e
    and  the arity over _a_r_i_t_y.  This is the same as  PL_get_name_arity(),
    but this function fails if _t is an atom.


int PPLL__ggeett__mmoodduullee(_t_e_r_m___t _+_t_, _m_o_d_u_l_e___t _*_m_o_d_u_l_e)
    If   _t  is  an  atom,  the  system  will  look  up   or  create  the
    corresponding  module  and  assign  an opaque  pointer  to  it  over
    _m_o_d_u_l_e.


int PPLL__ggeett__aarrgg(_s_i_z_e___t _i_n_d_e_x_, _t_e_r_m___t _+_t_, _t_e_r_m___t _-_a)
    If  _t is  compound and  index is  between 1  and arity  (inclusive),
    assign _a with a term reference to the argument.


int _PPLL__ggeett__aarrgg(_s_i_z_e___t _i_n_d_e_x_, _t_e_r_m___t _+_t_, _t_e_r_m___t _-_a)
    Same  as PL_get_arg(), but no checking is performed,  neither whether
    _t is actually a term nor whether _i_n_d_e_x is a valid argument index.


1111..44..33..33 EExxcchhaannggiinngg tteexxtt uussiinngg lleennggtthh aanndd ssttrriinngg

All  internal text  representation in  SWI-Prolog  is represented  using
char * plus length and  allow for _0_-_b_y_t_e_s in them.  The  foreign library
supports this by implementing  a *_nchars() function for  each applicable
*_chars()  function.   Below we briefly present  the signatures of  these
functions.  For full documentation consult the *_chars() function.


int PPLL__ggeett__aattoomm__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _*_l_e_n_, _c_h_a_r _*_*_s)
    See PL_get_atom_chars().


int PPLL__ggeett__lliisstt__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _*_l_e_n_, _c_h_a_r _*_*_s)
    See PL_get_list_chars().


int PPLL__ggeett__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _*_l_e_n_, _c_h_a_r _*_*_s_, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s)
    See PL_get_chars().


int PPLL__ppuutt__aattoomm__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_put_atom_chars().


int PPLL__ppuutt__ssttrriinngg__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_put_string_chars().


int PPLL__ppuutt__lliisstt__nnccooddeess(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_put_list_codes().


int PPLL__ppuutt__lliisstt__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_put_list_chars().


int PPLL__uunniiffyy__aattoomm__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_unify_atom_chars().


int PPLL__uunniiffyy__ssttrriinngg__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_unify_string_chars().


int PPLL__uunniiffyy__lliisstt__nnccooddeess(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_unify_codes().


int PPLL__uunniiffyy__lliisstt__nncchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    See PL_unify_list_chars().

In  addition, the  following functions  are available  for creating  and
inspecting atoms:


atom_t PPLL__nneeww__aattoomm__nncchhaarrss(_s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_s)
    Create  a new atom as PL_new_atom(), but using the given  length and
    characters.    If _l_e_n  is (size_t)-1, it  is computed  from _s  using
    strlen().


const char * PPLL__aattoomm__nncchhaarrss(_a_t_o_m___t _a_, _s_i_z_e___t _*_l_e_n)
    Extract the text and length of an atom.


1111..44..33..44 WWiiddee--cchhaarraacctteerr vveerrssiioonnss

Support  for   exchange  of  wide-character   strings  is  still   under
consideration.    The  functions dealing  with 8-bit  character  strings
return failure when operating on a wide-character atom  or Prolog string
object.  The  functions below can extract and unify both 8-bit  and wide
atoms and  string objects.   Wide character  strings are represented  as
C arrays  of objects of the  type pl_wchar_t,  which is guaranteed to  be
the same as wchar_t on platforms supporting this type.   For example, on
MS-Windows, this represents 16-bit UCS2 characters, while  using the GNU
C library (glibc) this represents 32-bit UCS4 characters.


atom_t PPLL__nneeww__aattoomm__wwcchhaarrss(_s_i_z_e___t _l_e_n_, _c_o_n_s_t _p_l___w_c_h_a_r___t _*_s)
    Create  atom from wide-character string as PL_new_atom_nchars() does
    for ISO-Latin-1 strings.   If _s only contains ISO-Latin-1 characters
    a  normal byte-array atom is created.   If _l_e_n is  (size_t)-1, it  is
    computed from _s using wcslen().


pl_wchar_t* PPLL__aattoomm__wwcchhaarrss(_a_t_o_m___t _a_t_o_m_, _i_n_t _*_l_e_n)
    Extract  characters from  a wide-character  atom.   Succeeds on  any
    atom  marked as `text'.  If the underlying atom is  a wide-character
    atom,  the returned pointer  is a pointer  into the atom  structure.
    If  it is an ISO-Latin-1 character, the returned pointer  comes from
    Prolog's `buffer ring' (see PL_get_chars()).


int PPLL__ggeett__wwcchhaarrss(_t_e_r_m___t _t_, _s_i_z_e___t _*_l_e_n_, _p_l___w_c_h_a_r___t _*_*_s_, _u_n_s_i_g_n_e_d _f_l_a_g_s)
    Wide-character  version of  PL_get_chars().   The  _f_l_a_g_s argument  is
    the same as for PL_get_chars().


int PPLL__uunniiffyy__wwcchhaarrss(_t_e_r_m___t _t_, _i_n_t _t_y_p_e_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _p_l___w_c_h_a_r___t _*_s)
    Unify _t with  a textual representation of the C wide-character array
    _s.   The _t_y_p_e argument defines the Prolog representation and  is one
    of PL_ATOM, PL_STRING, PL_CODE_LIST or PL_CHAR_LIST.


int PPLL__uunniiffyy__wwcchhaarrss__ddiiffff(_t_e_r_m___t _+_t_, _t_e_r_m___t _-_t_a_i_l_, _i_n_t _t_y_p_e_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _p_l___w_c_h_a_r___t _*_s)
    Difference  list version  of PL_unify_wchars(),  only supporting  the
    types  PL_CODE_LIST  and PL_CHAR_LIST. It serves  two purposes.    It
    allows  for returning very long lists  from data read from a  stream
    without  the need  for a  resizing buffer  in  C. Also,  the use  of
    difference  lists  is  often  practical for  further  processing  in
    Prolog.   Examples can be found in packages/clib/readutil.c from the
    source distribution.


1111..44..33..55 RReeaaddiinngg aa lliisstt

The functions from this section are intended to read  a Prolog list from
C. Suppose we expect a list of atoms; the following  code will print the
atoms, each on a line:

________________________________________________________________________|                                                                        |
|foreign_t                                                               |
|pl_write_atoms(term_t l)                                                |

|{ term_t head = PL_new_term_ref();   /* the elements */                 |
|  term_t list = PL_copy_term_ref(l); /* copy (we modify list) */        |
|                                                                        |
|  while( PL_get_list(list, head, list) )                                |
|  { char *s;                                                            |
|                                                                        |
|    if ( PL_get_atom_chars(head, &s) )                                  |
|      Sprintf("%s\n", s);                                               |

|    else                                                                |
|      PL_fail;                                                          |
|  }                                                                     |
|                                                                        |
|  return PL_get_nil(list);            /* test end for [] */             |
|}|_____________________________________________________________________ | |

Note that as  of version 7, lists  have a new representation unless  the
option --traditional is used.  see section ????.


int PPLL__ggeett__lliisstt(_t_e_r_m___t _+_l_, _t_e_r_m___t _-_h_, _t_e_r_m___t _-_t)
    If  _l is a list and not  the empty list, assign a term  reference to
    the head to _h and to the tail to _t.


int PPLL__ggeett__hheeaadd(_t_e_r_m___t _+_l_, _t_e_r_m___t _-_h)
    If  _l is a list and not  the empty list, assign a term  reference to
    the head to _h.


int PPLL__ggeett__ttaaiill(_t_e_r_m___t _+_l_, _t_e_r_m___t _-_t)
    If  _l is a list and not  the empty list, assign a term  reference to
    the tail to _t.


int PPLL__ggeett__nniill(_t_e_r_m___t _+_l)
    Succeeds if _l represents the list termination constant.


int PPLL__sskkiipp__lliisstt(_t_e_r_m___t _+_l_i_s_t_, _t_e_r_m___t _-_t_a_i_l_, _s_i_z_e___t _*_l_e_n)
    This is a multi-purpose  function to deal with lists.  It allows for
    finding the length  of a list, checking whether something is a list,
    etc.   The reference  _t_a_i_l is set to point  to the end of the  list,
    _l_e_n is filled  with the number of list-cells skipped, and the return
    value indicates the status of the list:

    PPLL__LLIISSTT
         The  list is  a `proper'  list:   one  that  ends in  the  list
         terminator constant  and  _t_a_i_l is  filled with  the  terminator
         constant.

    PPLL__PPAARRTTIIAALL__LLIISSTT
         The list is a `partial' list:  one that ends in  a variable and
         _t_a_i_l is a reference to this variable.

    PPLL__CCYYCCLLIICC__TTEERRMM
         The list  is  cyclic (e.g.    X  = [a_X]).  _t_a_i_l points  to  an
         arbitrary cell of the list  and _l_e_n is at most twice  the cycle
         length of the list.

    PPLL__NNOOTT__AA__LLIISSTT
         The  term _l_i_s_t  is  not a  list  at all.     _t_a_i_l is  bound  to
         the non-list term  and _l_e_n is set  to the number of  list-cells
         skipped.

    It is allowed to pass 0 for _t_a_i_l and NULL for _l_e_n.


1111..44..33..66 AAnn eexxaammppllee::  ddeeffiinniinngg write/1 iinn CC

Figure ????  shows a simplified  definition of  write/1 to illustrate  the
described  functions.    This  simplified  version does  not  deal  with
operators.    It is  called  display/1, because  it mimics  closely  the
behaviour of this Edinburgh predicate.
________________________________________________________________________|                                                                        |
|foreign_t                                                               |
|pl_display(term_t t)                                                    |
|{ functor_t functor;                                                    |

|  int arity, len, n;                                                    |
|  char *s;                                                              |
|                                                                        |
|  switch( PL_term_type(t) )                                             |
|  { case PL_VARIABLE:                                                   |
|    case PL_ATOM:                                                       |
|    case PL_INTEGER:                                                    |
|    case PL_FLOAT:                                                      |

|      PL_get_chars(t, &s, CVT_ALL);                                     |
|      Sprintf("%s", s);                                                 |
|      break;                                                            |
|    case PL_STRING:                                                     |
|      PL_get_string_chars(t, &s, &len);                                 |
|      Sprintf("\"%s\"", s);                                             |
|      break;                                                            |

|    case PL_TERM:                                                       |
|    { term_t a = PL_new_term_ref();                                     |
|                                                                        |
|      PL_get_name_arity(t, &name, &arity);                              |
|      Sprintf("%s(", PL_atom_chars(name));                              |
|      for(n=1; n<=arity; n++)                                           |
|      { PL_get_arg(n, t, a);                                            |
|        if ( n > 1 )                                                    |

|          Sprintf(", ");                                                |
|        pl_display(a);                                                  |
|      }                                                                 |
|      Sprintf(")");                                                     |
|      break;                                                            |
|    default:                                                            |
|      PL_fail;                          /* should not happen */         |

|    }                                                                   |
|  }                                                                     |
|                                                                        |
|  PL_succeed;                                                           |
|}|_____________________________________________________________________ | |

            Figure 11.2:  A Foreign definition of display/1


1111..44..44 CCoonnssttrruuccttiinngg TTeerrmmss

Terms  can  be  constructed  using  functions from  the  PL_put_*()  and
PL_cons_*()  families.    This  approach  builds the  term  `inside-out',
starting  at  the  leaves  and  subsequently  creating  compound  terms.
Alternatively,   terms  may  be  created   `top-down',  first   creating
a  compound  holding  only  variables  and   subsequently  unifying  the
arguments.   This section  discusses functions  for the first  approach.
This approach  is generally  used for  creating arguments  for PL_call()
and PL_open_query().


void PPLL__ppuutt__vvaarriiaabbllee(_t_e_r_m___t _-_t)
    Put  a fresh variable in the  term, resetting the term reference  to
    its initial state.


void PPLL__ppuutt__aattoomm(_t_e_r_m___t _-_t_, _a_t_o_m___t _a)
    Put  an  atom  in the  term  reference from  a  handle.    See  also
    PL_new_atom() and PL_atom_chars().


void PPLL__ppuutt__bbooooll(_t_e_r_m___t _-_t_, _i_n_t _v_a_l)
    Put  one of the atoms true or  false in the term reference  See also
    PL_put_atom(), PL_unify_bool()and PL_get_bool().


int PPLL__ppuutt__cchhaarrss(_t_e_r_m___t _-_t_, _i_n_t _f_l_a_g_s_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    New  function  to  deal  with  setting a  term  from  a  char*  with
    various  encodings.  The _f_l_a_g_s  argument is a bitwise _o_r  specifying
    the  Prolog  target type  and  the  encoding of  _c_h_a_r_s.    A  Prolog
    type  is one of  PL_ATOM,  PL_STRING, PL_CODE_LIST  or PL_CHAR_LIST.  A
    representation  is one  of REP_ISO_LATIN_1,  REP_UTF8 or  REP_MB.  See
    PL_get_chars() for  a definition of  the representation  types.   If
    _l_e_n  is -1 _c_h_a_r_s must be zero-terminated and the length  is computed
    from _c_h_a_r_s using strlen().


int PPLL__ppuutt__aattoomm__cchhaarrss(_t_e_r_m___t _-_t_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Put  an  atom  in the  term  reference  constructed from  the  zero-
    terminated  string.  The string  itself will never be referenced  by
    Prolog after this function.


int PPLL__ppuutt__ssttrriinngg__cchhaarrss(_t_e_r_m___t _-_t_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Put  a zero-terminated string in the term reference.  The  data will
    be copied.  See also PL_put_string_nchars().


int PPLL__ppuutt__ssttrriinngg__nncchhaarrss(_t_e_r_m___t _-_t_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Put  a string,  represented by  a length/start pointer  pair in  the
    term  reference.  The data will be copied.  This  interface can deal
    with 0-bytes in the string.  See also section ????.


int PPLL__ppuutt__lliisstt__cchhaarrss(_t_e_r_m___t _-_t_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Put a list of ASCII values in the term reference.


int PPLL__ppuutt__iinntteeggeerr(_t_e_r_m___t _-_t_, _l_o_n_g _i)
    Put a Prolog integer in the term reference.


int PPLL__ppuutt__iinntt6644(_t_e_r_m___t _-_t_, _i_n_t_6_4___t _i)
    Put a Prolog integer in the term reference.


int PPLL__ppuutt__ppooiinntteerr(_t_e_r_m___t _-_t_, _v_o_i_d _*_p_t_r)
    Put a Prolog integer  in the term reference.  Provided _p_t_r is in the
    `malloc()-area', PL_get_pointer() will get the pointer back.


int PPLL__ppuutt__ffllooaatt(_t_e_r_m___t _-_t_, _d_o_u_b_l_e _f)
    Put a floating-point value in the term reference.


int PPLL__ppuutt__ffuunnccttoorr(_t_e_r_m___t _-_t_, _f_u_n_c_t_o_r___t _f_u_n_c_t_o_r)
    Create  a new compound  term from _f_u_n_c_t_o_r and  bind _t to this  term.
    All arguments of the  term will be variables.  To create a term with
    instantiated  arguments, either instantiate the arguments  using the
    PL_unify_*() functions or use PL_cons_functor().


int PPLL__ppuutt__lliisstt(_t_e_r_m___t _-_l)
    As  PL_put_functor(),  using  the list-cell  functor.     Note  that
    on  classical  Prolog  systems or  in  SWI-Prolog using  the  option
    --traditional,  this is ./2, while  on SWI-Prolog version 7 this  is
    [|]/2.


int PPLL__ppuutt__nniill(_t_e_r_m___t _-_l)
    Put  the list terminator constant in  _l.  Always returns TRUE.  Note
    that  in classical Prolog systems or in SWI-Prolog using  the option
    --traditional,  this is  the same  as PL_put_atom_chars(_"_[_]_").    See
    section ????.


void PPLL__ppuutt__tteerrmm(_t_e_r_m___t _-_t_1_, _t_e_r_m___t _+_t_2)
    Make _t_1 point to the same term as _t_2.


int PPLL__ccoonnss__ffuunnccttoorr(_t_e_r_m___t _-_h_, _f_u_n_c_t_o_r___t _f_, _._._.)
    Create  a term whose arguments  are filled from a variable  argument
    list  holding the same number of term_t objects as the arity  of the
    functor.  To create the term animal(gnu, 50), use:

    ____________________________________________________________________|                                                                    |
    | { term_t a1 = PL_new_term_ref();                                   |

    |   term_t a2 = PL_new_term_ref();                                   |
    |   term_t t  = PL_new_term_ref();                                   |
    |   functor_t animal2;                                               |
    |                                                                    |
    |   /* animal2 is a constant that may be bound to a global           |
    |      variable and re-used                                          |
    |   */                                                               |
    |   animal2 = PL_new_functor(PL_new_atom("animal"), 2);              |

    |                                                                    |
    |   PL_put_atom_chars(a1, "gnu");                                    |
    |   PL_put_integer(a2, 50);                                          |
    |   PL_cons_functor(t, animal2, a1, a2);                             |
    ||}_________________________________________________________________ ||

    After  this sequence, the term references _a_1 and _a_2 may be  used for
    other purposes.


int PPLL__ccoonnss__ffuunnccttoorr__vv(_t_e_r_m___t _-_h_, _f_u_n_c_t_o_r___t _f_, _t_e_r_m___t _a_0)
    Create  a compound term  like PL_cons_functor(),  but _a_0 is an  array
    of  term references as  returned by PL_new_term_refs().   The  length
    of  this array should match the number of arguments required  by the
    functor.


int PPLL__ccoonnss__lliisstt(_t_e_r_m___t _-_l_, _t_e_r_m___t _+_h_, _t_e_r_m___t _+_t)
    Create  a list (cons-) cell in  _l from the head _h  and tail _t.   The
    code  below creates a  list of atoms  from a char **.   The list  is
    built  tail-to-head.    The PL_unify_*() functions  can  be used  to
    build a list head-to-tail.

    ____________________________________________________________________|                                                                    |
    | void                                                               |
    | put_list(term_t l, int n, char **words)                            |
    | { term_t a = PL_new_term_ref();                                    |

    |                                                                    |
    |   PL_put_nil(l);                                                   |
    |   while( --n >= 0 )                                                |
    |   { PL_put_atom_chars(a, words[n]);                                |
    |     PL_cons_list(l, a, l);                                         |
    |   }                                                                |
    ||}_________________________________________________________________ ||

    Note  that _l can  be redefined  within a PL_cons_list call as  shown
    here because operationally  its old value is consumed before its new
    value is set.


1111..44..55 UUnniiffyyiinngg ddaattaa

The  functions  of  this  section  _u_n_i_f_y  terms  with   other  terms  or
translated C  data structures.   Except for PL_unify(), these  functions
are specific  to SWI-Prolog.    They have been  introduced because  they
shorten the code for returning data to Prolog and at  the same time make
this more  efficient by  avoiding the  need to  allocate temporary  term
references and reduce  the number of calls  to the Prolog API.  Consider
the case  where we want a  foreign function to  return the host name  of
the machine Prolog  is running on.   Using the PL_get_*() and PL_put_*()
functions, the code becomes:

________________________________________________________________________|                                                                        |
|foreign_t                                                               |
|pl_hostname(term_t name)                                                |

|{ char buf[100];                                                        |
|                                                                        |
|  if ( gethostname(buf, sizeof(buf)) )                                  |
|  { term_t tmp = PL_new_term_ref();                                     |
|                                                                        |
|    PL_put_atom_chars(tmp, buf);                                        |
|    return PL_unify(name, tmp);                                         |
|  }                                                                     |

|                                                                        |
|  PL_fail;                                                              |
|}|_____________________________________________________________________ | |

Using PL_unify_atom_chars(), this becomes:

________________________________________________________________________|                                                                        |
|foreign_t                                                               |
|pl_hostname(term_t name)                                                |

|{ char buf[100];                                                        |
|                                                                        |
|  if ( gethostname(buf, sizeof(buf)) )                                  |
|    return PL_unify_atom_chars(name, buf);                              |
|                                                                        |
|  PL_fail;                                                              |
|}|_____________________________________________________________________ | |

Note  that unification  functions  that  perform multiple  bindings  may
leave part  of the  bindings in  case of  failure.   See  PL_unify() for
details.


int PPLL__uunniiffyy(_t_e_r_m___t _?_t_1_, _t_e_r_m___t _?_t_2)
    Unify two Prolog terms and return TRUE on success.

    Care  is needed if PL_unify() returns FAIL and the  foreign function
    does  not _i_m_m_e_d_i_a_t_e_l_y  return to Prolog  with FAIL. Unification  may
    perform multiple changes to  either _t_1 or _t_2.  A failing unification
    may  have created  bindings  before failure  is detected.    _A_l_r_e_a_d_y
    _c_r_e_a_t_e_d  _b_i_n_d_i_n_g_s _a_r_e _n_o_t _u_n_d_o_n_e.   For example,  calling PL_unify()
    on a(_X_, _a) and  a(_c_,_b) binds _X to c and fails when trying to unify a
    to b.  If  control remains in C or even if we want to return success
    to  Prolog, we  _m_u_s_t undo  such bindings.   This  is achieved  using
    PL_open_foreign_frame() and  PL_rewind_foreign_frame(),  as shown  in
    the snippet below.

    ____________________________________________________________________|                                                                    |
    |     { fid_t fid = PL_open_foreign_frame();                         |

    |                                                                    |
    |       ...                                                          |
    |       if ( !PL_unify(t1, t2) )                                     |
    |         PL_rewind_foreign_frame(fid);                              |
    |       ...                                                          |
    |                                                                    |
    |       PL_close_foreign_frame(fid);                                 |
    ||____}_____________________________________________________________ ||

    In   addition,   PL_unify()  may  have  failed   on  an   eexxcceeppttiioonn,
    typically  a  resource  (stack)  overflow.     This  can  be  tested
    using  PL_exception(),  passing 0 (zero)  for the query-id  argument.
    Foreign  functions that encounter an  exception must return FAIL  to
    Prolog  as  soon as  possible or  call PL_clear_exception() if  they
    wish to ignore the exception.


int PPLL__uunniiffyy__aattoomm(_t_e_r_m___t _?_t_, _a_t_o_m___t _a)
    Unify _t with the atom _a and return non-zero on success.


int PPLL__uunniiffyy__bbooooll(_t_e_r_m___t _?_t_, _i_n_t _a)
    Unify _t with either true or false.


int PPLL__uunniiffyy__cchhaarrss(_t_e_r_m___t _?_t_, _i_n_t _f_l_a_g_s_, _s_i_z_e___t _l_e_n_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    New  function  to  deal  with  unification  of  char*  with  various
    encodings  to a  Prolog representation.    The _f_l_a_g_s  argument is  a
    bitwise  _o_r specifying the  Prolog target type  and the encoding  of
    _c_h_a_r_s.   A Prolog type is one of PL_ATOM, PL_STRING, PL_CODE_LIST or
    PL_CHAR_LIST. A  representation is one  of REP_ISO_LATIN_1,  REP_UTF8
    or REP_MB. See PL_get_chars() for a definition of the representation
    types.   If _l_e_n is -1  _c_h_a_r_s must be zero-terminated and  the length
    is computed from _c_h_a_r_s using strlen().

    If  _f_l_a_g_s includes PL_DIFF_LIST and  type is one  of PL_CODE_LIST  or
    PL_CHAR_LIST, the text is converted to a _d_i_f_f_e_r_e_n_c_e _l_i_s_t.   The tail
    of the difference list is t +1.


int PPLL__uunniiffyy__aattoomm__cchhaarrss(_t_e_r_m___t _?_t_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Unify  _t with  an atom  created from  _c_h_a_r_s and  return non-zero  on
    success.


int PPLL__uunniiffyy__lliisstt__cchhaarrss(_t_e_r_m___t _?_t_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Unify _t with a list of ASCII characters constructed from _c_h_a_r_s.


void PPLL__uunniiffyy__ssttrriinngg__cchhaarrss(_t_e_r_m___t _?_t_, _c_o_n_s_t _c_h_a_r _*_c_h_a_r_s)
    Unify  _t  with  a  Prolog  string  object  created  from  the  zero-
    terminated  string  _c_h_a_r_s.   The  data will  be copied.    See  also
    PL_unify_string_nchars().


int PPLL__uunniiffyy__iinntteeggeerr(_t_e_r_m___t _?_t_, _i_n_t_p_t_r___t _n)
    Unify _t with a Prolog integer from _n.


int PPLL__uunniiffyy__iinntt6644(_t_e_r_m___t _?_t_, _i_n_t_6_4___t _n)
    Unify _t with a Prolog integer from _n.


int PPLL__uunniiffyy__uuiinntt6644(_t_e_r_m___t _?_t_, _u_i_n_t_6_4___t _n)
    Unify  _t with a Prolog integer from _n.  Note that  unbounded integer
    support  is required  if _n does  not fit  in a _s_i_g_n_e_d  int64_t.    If
    unbounded  integers  are  not  supported a  representation_error  is
    raised.


int PPLL__uunniiffyy__ffllooaatt(_t_e_r_m___t _?_t_, _d_o_u_b_l_e _f)
    Unify _t with a Prolog float from _f.


int PPLL__uunniiffyy__ppooiinntteerr(_t_e_r_m___t _?_t_, _v_o_i_d _*_p_t_r)
    Unify  _t with a  Prolog integer  describing the pointer.   See  also
    PL_put_pointer() and PL_get_pointer().


int PPLL__uunniiffyy__ffuunnccttoorr(_t_e_r_m___t _?_t_, _f_u_n_c_t_o_r___t _f)
    If  _t is a compound term with  the given functor, just succeed.   If
    it  is unbound,  create a  term and  bind the  variable, else  fail.
    Note  that this function does not  create a term if the argument  is
    already instantiated.   If _f is a functor with arity 0, _t is unified
    with an atom.  See also PL_unify_compound().


int PPLL__uunniiffyy__ccoommppoouunndd(_t_e_r_m___t _?_t_, _f_u_n_c_t_o_r___t _f)
    If  _t is a compound term with  the given functor, just succeed.   If
    it  is unbound,  create a  term and  bind the  variable, else  fail.
    Note  that this function does not  create a term if the argument  is
    already instantiated.   If _f is a functor with arity 0, _t is unified
    with compound without arguments.  See also PL_unify_functor().


int PPLL__uunniiffyy__lliisstt(_t_e_r_m___t _?_l_, _t_e_r_m___t _-_h_, _t_e_r_m___t _-_t)
    Unify  _l with a list-cell (./2).   If successful, write  a reference
    to  the head of the list into _h  and a reference to the tail  of the
    list  into _t.   This reference may be  used for subsequent calls  to
    this  function.   Suppose we  want to  return a list  of atoms  from
    a  char **.   We could  use the example  described by PL_put_list(),
    followed by  a call to PL_unify(), or we can use  the code below.  If
    the  predicate argument is unbound,  the difference is minimal  (the
    code  based on PL_put_list() is probably slightly  faster).  If  the
    argument  is bound, the code below may fail before reaching  the end
    of  the word list, but even  if the unification succeeds, this  code
    avoids a duplicate (garbage) list and a deep unification.

    ____________________________________________________________________|                                                                    |
    | foreign_t                                                          |

    | pl_get_environ(term_t env)                                         |
    | { term_t l = PL_copy_term_ref(env);                                |
    |   term_t a = PL_new_term_ref();                                    |
    |   extern char **environ;                                           |
    |   char **e;                                                        |
    |                                                                    |
    |   for(e = environ; *e; e++)                                        |
    |   { if ( !PL_unify_list(l, a, l) ||                                |

    |          !PL_unify_atom_chars(a, *e) )                             |
    |       PL_fail;                                                     |
    |   }                                                                |
    |                                                                    |
    |   return PL_unify_nil(l);                                          |
    ||}_________________________________________________________________ ||


int PPLL__uunniiffyy__nniill(_t_e_r_m___t _?_l)
    Unify _l with the atom [].


int PPLL__uunniiffyy__aarrgg(_i_n_t _i_n_d_e_x_, _t_e_r_m___t _?_t_, _t_e_r_m___t _?_a)
    Unifies the _i_n_d_e_x_-_t_h argument (1-based) of _t with _a.


int PPLL__uunniiffyy__tteerrmm(_t_e_r_m___t _?_t_, _._._.)
    Unify  _t with a (normally) compound  term.  The remaining  arguments
    are  a  sequence  of a  type  identifier  followed by  the  required
    arguments.      This  predicate  is  an  extension  to  the  Quintus
    and  SICStus foreign  interface  from which  the SWI-Prolog  foreign
    interface  has been  derived, but has  proved to  be a powerful  and
    comfortable  way to create compound terms from C. Due to  the vararg
    packing/unpacking and  the required type-switching this interface is
    slightly  slower than using the primitives.   Please note that  some
    bad  C compilers have fairly low  limits on the number of  arguments
    that may be passed to a function.

    Special  attention is required when  passing numbers.  C  `promotes'
    any  integral smaller than  int to int.   That  is, the types  char,
    short  and int are all passed as  int.  In addition, on  most 32-bit
    platforms  int and long  are the same.   Up  to version 4.0.5,  only
    PL_INTEGER  could  be specified,  which  was  taken from  the  stack
    as  long.   Such  code fails when  passing small  integral types  on
    machines  where int  is smaller than  long.   It is  advised to  use
    PL_SHORT, PL_INT or PL_LONG as appropriate.  Similarly,  C compilers
    promote  float to  double and  therefore PL_FLOAT and  PL_DOUBLE  are
    synonyms.

    The type identifiers are:

    PL_VARIABLE _n_o_n_e
         No op.  Used in arguments of PL_FUNCTOR.

    PL_BOOL _i_n_t
         Unify the argument with true or false.

    PL_ATOM _a_t_o_m___t
         Unify the argument with an atom, as in PL_unify_atom().

    PL_CHARS _c_o_n_s_t _c_h_a_r _*
         Unify the argument with an atom constructed from  the C char *,
         as in PL_unify_atom_chars().

    PL_NCHARS _s_i_z_e___t_, _c_o_n_s_t _c_h_a_r _*
         Unify the  argument with  an atom constructed  from length  and
         char* as in PL_unify_atom_nchars().

    PL_UTF8_CHARS _c_o_n_s_t _c_h_a_r _*
         Create an atom from a UTF-8 string.

    PL_UTF8_STRING _c_o_n_s_t _c_h_a_r _*
         Create a packed string object from a UTF-8 string.

    PL_MBCHARS _c_o_n_s_t _c_h_a_r _*
         Create an atom from a multi-byte string in the current locale.

    PL_MBCODES _c_o_n_s_t _c_h_a_r _*
         Create a list  of character codes  from a multi-byte string  in
         the current locale.

    PL_MBSTRING _c_o_n_s_t _c_h_a_r _*
         Create a packed string  object from a multi-byte string  in the
         current locale.

    PL_NWCHARS _s_i_z_e___t_, _c_o_n_s_t _w_c_h_a_r___t _*
         Create an atom from a length and a wide character pointer.

    PL_NWCODES _s_i_z_e___t_, _c_o_n_s_t _w_c_h_a_r___t _*
         Create a  list of  character  codes from  a length  and a  wide
         character pointer.

    PL_NWSTRING _s_i_z_e___t_, _c_o_n_s_t _w_c_h_a_r___t _*
         Create  a  packed  string object  from  a  length  and  a  wide
         character pointer.

    PL_SHORT _s_h_o_r_t
         Unify the argument  with an integer,  as in PL_unify_integer().
         As short is promoted to int, PL_SHORT is a synonym for PL_INT.

    PL_INTEGER _l_o_n_g
         Unify the argument with an integer, as in PL_unify_integer().

    PL_INT _i_n_t
         Unify the argument with an integer, as in PL_unify_integer().

    PL_LONG _l_o_n_g
         Unify the argument with an integer, as in PL_unify_integer().

    PL_INT64 _i_n_t_6_4___t
         Unify   the   argument   with   a  64-bit   integer,    as   in
         PL_unify_int64().

    PL_INTPTR _i_n_t_p_t_r___t
         Unify the  argument with an  integer with the  same width as  a
         pointer.  On most machines this is  the same as PL_LONG. but on
         64-bit MS-Windows pointers are 64 bits while longs  are only 32
         bits.

    PL_DOUBLE _d_o_u_b_l_e
         Unify  the  argument  with a  float,  as  in  PL_unify_float().
         Note  that,  as the  argument  is  passed using  the  C  vararg
         conventions, a float must be casted to a double explicitly.

    PL_FLOAT _d_o_u_b_l_e
         Unify the argument with a float, as in PL_unify_float().

    PL_POINTER _v_o_i_d _*
         Unify the argument with a pointer, as in PL_unify_pointer().

    PL_STRING _c_o_n_s_t _c_h_a_r _*
         Unify   the   argument   with   a   string   object,    as   in
         PL_unify_string_chars().

    PL_TERM _t_e_r_m___t
         Unify a  subterm.   Note  this  may be  the return  value of  a
         PL_new_term_ref()call to get access to a variable.

    PL_FUNCTOR _f_u_n_c_t_o_r___t_, _._._.
         Unify the argument  with a compound  term.  This  specification
         should be  followed by  exactly as many  specifications as  the
         number of arguments of the compound term.

    PL_FUNCTOR_CHARS _c_o_n_s_t _c_h_a_r _*_n_a_m_e_, _i_n_t _a_r_i_t_y_, _._._.
         Create a functor from the given name and arity  and then behave
         as PL_FUNCTOR.

    PL_LIST _i_n_t _l_e_n_g_t_h_, _._._.
         Create  a  list  of  the  indicated  length.     The  remaining
         arguments contain the elements of the list.

    For  example, to  unify an argument  with the term  language(dutch),
    the following skeleton may be used:

    ____________________________________________________________________|                                                                    |

    | static functor_t FUNCTOR_language1;                                |
    |                                                                    |
    | static void                                                        |
    | init_constants()                                                   |
    | { FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"),1);   |

    | }                                                                  |
    |                                                                    |
    | foreign_t                                                          |
    | pl_get_lang(term_t r)                                              |
    | { return PL_unify_term(r,                                          |
    |                        PL_FUNCTOR, FUNCTOR_language1,              |
    |                            PL_CHARS, "dutch");                     |
    | }                                                                  |

    |                                                                    |
    | install_t                                                          |
    | install()                                                          |
    | { PL_register_foreign("get_lang", 1, pl_get_lang, 0);              |
    |   init_constants();                                                |
    ||}_________________________________________________________________ ||


int PPLL__cchhaarrss__ttoo__tteerrmm(_c_o_n_s_t _c_h_a_r _*_c_h_a_r_s_, _t_e_r_m___t _-_t)
    Parse  the string _c_h_a_r_s  and put the  resulting Prolog term into  _t.
    _c_h_a_r_s  may or may not  be closed using  a Prolog full-stop (i.e.,  a
    dot  followed by  a blank).   Returns  FALSE if a  syntax error  was
    encountered  and TRUE after successful  completion.  In addition  to
    returning  FALSE, the exception-term  is returned in  _t on a  syntax
    error.  See also term_to_atom/2.

    The  following example builds  a goal term  from a string and  calls
    it.

    ____________________________________________________________________|                                                                    |
    | int                                                                |
    | call_chars(const char *goal)                                       |
    | { fid_t fid = PL_open_foreign_frame();                             |

    |   term_t g = PL_new_term_ref();                                    |
    |   BOOL rval;                                                       |
    |                                                                    |
    |   if ( PL_chars_to_term(goal, g) )                                 |
    |     rval = PL_call(goal, NULL);                                    |
    |   else                                                             |
    |     rval = FALSE;                                                  |
    |                                                                    |

    |   PL_discard_foreign_frame(fid);                                   |
    |   return rval;                                                     |
    | }                                                                  |
    |   ...                                                              |
    |   call_chars("consult(load)");                                     |
    ||__..._____________________________________________________________ ||


int PPLL__wwcchhaarrss__ttoo__tteerrmm(_c_o_n_s_t _p_l___w_c_h_a_r___t _*_c_h_a_r_s_, _t_e_r_m___t _-_t)
    Wide character version of PL_chars_to_term().


char * PPLL__qquuoottee(_i_n_t _c_h_r_, _c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
    Return a quoted version of  _s_t_r_i_n_g.  If _c_h_r is '\'', the result is a
    quoted  atom.  If _c_h_r  is '"', the result is  a string.  The  result
    string  is stored in the same ring of buffers as described  with the
    BUF_RING argument of PL_get_chars();

    In  the current implementation, the string is surrounded by  _c_h_r and
    any occurrence of _c_h_r  is doubled.  In the future the behaviour will
    depend on the character_escapes Prolog flag.


1111..44..66 CCoonnvveenniieenntt ffuunnccttiioonnss ttoo ggeenneerraattee PPrroolloogg eexxcceeppttiioonnss

The  typical  implementation  of a  foreign  predicate  first  uses  the
PL_get_*() functions  to  extract C  data types  from the  Prolog  terms.
Failure of any  of these functions is  normally because the Prolog  term
is of  the wrong  type.   The  *_ex()  family of  functions are  wrappers
around (mostly)  the PL_get_*() functions,  such that  we can write  code
in  the  style  below  and get  proper  exceptions  if  an  argument  is
uninstantiated or of the wrong type.

________________________________________________________________________|                                                                        |
|/** set_size(+Name:atom, +Width:int, +Height:int) is det.               |

|                                                                        |
|static foreign_t                                                        |
|set_size(term_t name, term_t width, term_t height)                      |
|{ char *n;                                                              |
|  int w, h;                                                             |
|                                                                        |
|  if ( !PL_get_chars(name, &n, CVT_ATOM|CVT_EXCEPTION) ||               |
|       !PL_get_integer_ex(with, &w) ||                                  |

|       !PL_get_integer_ex(height, &h) )                                 |
|    return FALSE;                                                       |
|                                                                        |
|  ...                                                                   |
|                                                                        |
|}|_____________________________________________________________________ | |


int PPLL__ggeett__aattoomm__eexx(_t_e_r_m___t _t_, _a_t_o_m___t _*_a)
    As  PL_get_atom(), but raises  a type or instantiation error if  _t is
    not an atom.


int PPLL__ggeett__iinntteeggeerr__eexx(_t_e_r_m___t _t_, _i_n_t _*_i)
    As  PL_get_integer(), but raises  a type or instantiation error  if _t
    is  not an integer, or a representation error if the  Prolog integer
    does not fit in a C int.


int PPLL__ggeett__lloonngg__eexx(_t_e_r_m___t _t_, _l_o_n_g _*_i)
    As  PL_get_long(), but raises  a type or instantiation error if  _t is
    not  an atom, or a representation  error if the Prolog integer  does
    not fit in a C long.


int PPLL__ggeett__iinntt6644__eexx(_t_e_r_m___t _t_, _i_n_t_6_4___t _*_i)
    As  PL_get_int64(), but raises a type or instantiation error  if _t is
    not  an atom, or a representation  error if the Prolog integer  does
    not fit in a C int64_t.


int PPLL__ggeett__iinnttppttrr__eexx(_t_e_r_m___t _t_, _i_n_t_p_t_r___t _*_i)
    As  PL_get_intptr(), but  raises a type  or instantiation error if  _t
    is  not an  atom, or a  representation error  if the Prolog  integer
    does not fit in a C intptr_t.


int PPLL__ggeett__ssiizzee__eexx(_t_e_r_m___t _t_, _s_i_z_e___t _*_i)
    As  PL_get_size(), but raises  a type or instantiation error if  _t is
    not  an atom, or a representation  error if the Prolog integer  does
    not fit in a C size_t.


int PPLL__ggeett__bbooooll__eexx(_t_e_r_m___t _t_, _i_n_t _*_i)
    As  PL_get_bool(), but raises  a type or instantiation error if  _t is
    not an boolean.


int PPLL__ggeett__ffllooaatt__eexx(_t_e_r_m___t _t_, _d_o_u_b_l_e _*_f)
    As  PL_get_float(), but raises a type or instantiation error  if _t is
    not a float.


int PPLL__ggeett__cchhaarr__eexx(_t_e_r_m___t _t_, _i_n_t _*_p_, _i_n_t _e_o_f)
    Get  a character code  from _t, where  _t is either  an integer or  an
    atom with length one.   If _e_o_f is TRUE and _t is -1, _p is filled with
    -1.  Raises an appropriate error if the conversion is not possible.


int PPLL__ggeett__ppooiinntteerr__eexx(_t_e_r_m___t _t_, _v_o_i_d _*_*_a_d_d_r_p)
    As  PL_get_pointer(), but raises  a type or instantiation error  if _t
    is not a pointer.


int PPLL__ggeett__lliisstt__eexx(_t_e_r_m___t _l_, _t_e_r_m___t _h_, _t_e_r_m___t _t)
    As  PL_get_list(), but raises  a type or instantiation error if  _t is
    not a list.


int PPLL__ggeett__nniill__eexx(_t_e_r_m___t _l)
    As  PL_get_nil(), but  raises a type or  instantiation error if _t  is
    not the empty list.


int PPLL__uunniiffyy__lliisstt__eexx(_t_e_r_m___t _l_, _t_e_r_m___t _h_, _t_e_r_m___t _t)
    As PL_unify_list(), but raises a type error if _t is  not a variable,
    list-cell or the empty list.


int PPLL__uunniiffyy__nniill__eexx(_t_e_r_m___t _l)
    As  PL_unify_nil(), but raises  a type error if _t is not  a variable,
    list-cell or the empty list.


int PPLL__uunniiffyy__bbooooll__eexx(_t_e_r_m___t _t_, _i_n_t _v_a_l)
    As  PL_unify_bool(), but raises  a type error if _t is not  a variable
    or a boolean.

The  second  family   of  functions  in  this  section  simplifies   the
generation of  ISO compatible error  terms.   Any foreign function  that
calls  this function  must return  to  Prolog with  the return  code  of
the error  function or  the constant  FALSE. If  available, these  error
functions add the  name of the calling  predicate to the error  context.
See also PL_raise_exception().


int PPLL__iinnssttaannttiiaattiioonn__eerrrroorr(_t_e_r_m___t _c_u_l_p_r_i_t)
    Raise  instantiation_error.    _C_u_l_p_r_i_t  is ignored,  but  should  be
    bound  to  the  term  that  is insufficiently  instantiated.     See
    instantiation_error/1.


int PPLL__uunniinnssttaannttiiaattiioonn__eerrrroorr(_t_e_r_m___t _c_u_l_p_r_i_t)
    Raise  uninstantiation_error(culprit).   This should be called  if an
    argument  that must be unbound at entry  is bound to _c_u_l_p_r_i_t.   This
    error  is typically  raised for a  pure output  arguments such as  a
    newly created stream handle (e.g., the third argument of open/3).


int PPLL__rreepprreesseennttaattiioonn__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_r_e_s_o_u_r_c_e)
    Raise representation_error(resource).  See representation_error/1.


int PPLL__ttyyppee__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_e_x_p_e_c_t_e_d_, _t_e_r_m___t _c_u_l_p_r_i_t)
    Raise type_error(expected, culprit).  See type_error/2.


int PPLL__ddoommaaiinn__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_e_x_p_e_c_t_e_d_, _t_e_r_m___t _c_u_l_p_r_i_t)
    Raise domain_error(expected, culprit).  See domain_error/2.


int PPLL__eexxiisstteennccee__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_t_y_p_e_, _t_e_r_m___t _c_u_l_p_r_i_t)
    Raise existence_error(type, culprit).  See type_error/2.


int PPLL__ppeerrmmiissssiioonn__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_o_p_e_r_a_t_i_o_n_, _c_o_n_s_t _c_h_a_r _*_t_y_p_e_, _t_e_r_m___t _c_u_l_p_r_i_t)
    Raise     permission_error(operation, type, culprit).            See
    permission_error/3.


int PPLL__rreessoouurrccee__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_r_e_s_o_u_r_c_e)
    Raise resource_error(resource).  See resource_error/1.


int PPLL__ssyynnttaaxx__eerrrroorr(_c_o_n_s_t _c_h_a_r _*_m_e_s_s_a_g_e_, _I_O_S_T_R_E_A_M _*_i_n)
    Raise  syntax_error(message).   If _a_r_g  is not NULL, add  information
    about the current position of the input stream.


1111..44..77 BBLLOOBBSS:: UUssiinngg aattoommss ttoo ssttoorree aarrbbiittrraarryy bbiinnaarryy ddaattaa

SWI-Prolog atoms as well as strings can represent  arbitrary binary data
of arbitrary length.   This facility  is attractive for storing  foreign
data such  as images in an  atom.   An atom is  a unique handle to  this
data and the  atom garbage collector is  able to destroy atoms that  are
no longer  referenced by  the Prolog  engine.   This  property of  atoms
makes them  attractive as a  handle to foreign  resources, such as  Java
atoms, Microsoft's  COM objects, etc.,  providing safe combined  garbage
collection.

To  exploit   these  features  safely  and   in  an  organised   manner,
the  SWI-Prolog  foreign  interface allows  for  creating  `atoms'  with
additional type  information.   The type is  represented by a  structure
holding C  function pointers that  tell Prolog  how to handle  releasing
the  atom,  writing it,  sorting  it,  etc.    Two  atoms  created  with
different types  can represent the  same sequence of bytes.   Atoms  are
first ordered on the rank  number of the type and then on the  result of
the compare()  function.   Rank numbers  are assigned  when the type  is
registered.


1111..44..77..11 DDeeffiinniinngg aa BBLLOOBB ttyyppee

The  type PL_blob_t represents  a structure  with  the layout  displayed
below.  The structure contains additional fields at  the ...for internal
bookkeeping as well as future extensions.

________________________________________________________________________|                                                                        |
|typedef struct PL_blob_t                                                |

|{ uintptr_t     magic;          /* PL_BLOB_MAGIC */                     |
|  uintptr_t     flags;          /* Bitwise or of PL_BLOB_* */           |
|  char *        name;           /* name of the type */                  |
|  int           (*release)(atom_t a);                                   |
|  int           (*compare)(atom_t a, atom_t b);                         |
|  int           (*write)(IOSTREAM *s, atom_t a, int flags);             |
|  void          (*acquire)(atom_t a);                                   |
|  ...                                                                   |

|}|PL_blob_t;___________________________________________________________ | |

For each  type, exactly  one such structure  should be  allocated.   Its
first field must be initialised to PL_BLOB_MAGIC. The _f_l_a_g_s is a bitwise
_o_r of the following constants:

PPLL__BBLLOOBB__TTEEXXTT
    If  specified the blob is assumed to contain text and  is considered
    a normal Prolog atom.

PPLL__BBLLOOBB__UUNNIIQQUUEE
    If  specified the system  ensures that the  blob-handle is a  unique
    reference  for a blob with the given  type, length and content.   If
    this flag is not specified, each lookup creates a new blob.

PPLL__BBLLOOBB__NNOOCCOOPPYY
    By  default the  content of the  blob is  copied.   Using this  flag
    the  blob references  the external  data directly.    The user  must
    ensure  the provided  pointer is valid  as long  as the atom  lives.
    If  PL_BLOB_UNIQUE  is also  specified, uniqueness  is determined  by
    comparing the pointer rather than the data pointed at.

The _n_a_m_e  field represents the type  name as available  to Prolog.   See
also current_blob/2.  The  other fields are function pointers  that must
be initialised to proper functions or NULL to get  the default behaviour
of built-in atoms.  Below are the defined member functions:


void aaccqquuiirree(_a_t_o_m___t _a)
    Called  if a new blob of this  type is created through PL_put_blob()
    or  PL_unify_blob().   This  callback may be  used together with  the
    release hook to deal with reference-counted external objects.


int rreelleeaassee(_a_t_o_m___t _a)
    The  blob (atom)  _a is  about to  be released.    This function  can
    retrieve  the data of the blob using PL_blob_data().  If  it returns
    FALSE the atom garbage collector will _n_o_t reclaim the atom.


int ccoommppaarree(_a_t_o_m___t _a_, _a_t_o_m___t _b)
    Compare the blobs _a  and _b, both of which are of the type associated
    to  this blob type.   Return  values are, as  memcmp(), < 0 if _a is
    less than _b, = 0 if both are equal, and >0 otherwise.


int wwrriittee(_I_O_S_T_R_E_A_M _*_s_, _a_t_o_m___t _a_, _i_n_t _f_l_a_g_s)
    Write  the content  of the  blob _a to  the stream  _s respecting  the
    _f_l_a_g_s.   The _f_l_a_g_s are a bitwise _o_r  _o_f _z_e_r_o _o_r _m_o_r_e _o_f _t_h_e PL_WRT_*
    _f_l_a_g_s  _d_e_f_i_n_e_d _i_n SWI-Prolog.h_.  _T_h_i_s _p_r_o_t_o_t_y_p_e _i_s _a_v_a_i_l_a_b_l_e _i_f  _t_h_e
    _u_n_d_o_c_u_m_e_n_t_e_d SWI-Stream.h _i_s _i_n_c_l_u_d_e_d _b_e_f_o_r_e SWI-Prolog.h_.

    _I_f  _t_h_i_s _f_u_n_c_t_i_o_n _i_s _n_o_t _p_r_o_v_i_d_e_d_, write/1 _e_m_i_t_s _t_h_e _c_o_n_t_e_n_t  _o_f _t_h_e
    _b_l_o_b  _f_o_r _b_l_o_b_s _o_f _t_y_p_e PL_BLOB_TEXT _o_r _a _s_t_r_i_n_g _o_f  _t_h_e _f_o_r_m_a_t <#_h_e_x
    _d_a_t_a> _f_o_r _b_i_n_a_r_y _b_l_o_b_s_.

If  a blob  type is  registered from  a loadable  object (shared  object
or DLL)  the blob  type must be  deregistered before  the object may  be
released.


int PPLL__uunnrreeggiisstteerr__bblloobb__ttyyppee(_P_L___b_l_o_b___t _*_t_y_p_e)
    Unlink  the blob  type from  the registered type  and transform  the
    type  of possible  living blobs  to  unregistered, avoiding  further
    reference  to the type structure, functions referred by it,  as well
    as  the data.  This function  returns TRUE if no blobs of  this type
    existed  and FALSE otherwise.  PL_unregister_blob_type() is intended
    for  the  uninstall()  hook of  foreign  modules,  avoiding  further
    references to the module.


1111..44..77..22 AAcccceessssiinngg bblloobbss

The blob access  functions are similar to the atom  accessing functions.
Blobs being atoms, the  atom functions operate on blobs and  vice versa.
For clarity  and possible  future compatibility issues,  however, it  is
not advised to rely on this.


int PPLL__iiss__bblloobb(_t_e_r_m___t _t_, _P_L___b_l_o_b___t _*_*_t_y_p_e)
    Succeeds  if _t refers to a blob,  in which case _t_y_p_e is  filled with
    the type of the blob.


int PPLL__uunniiffyy__bblloobb(_t_e_r_m___t _t_, _v_o_i_d _*_b_l_o_b_, _s_i_z_e___t _l_e_n_, _P_L___b_l_o_b___t _*_t_y_p_e)
    Unify  _t  to  a  new  blob  constructed  from  the  given  data  and
    associated to the given type.  See also PL_unify_atom_nchars().


int PPLL__ppuutt__bblloobb(_t_e_r_m___t _t_, _v_o_i_d _*_b_l_o_b_, _s_i_z_e___t _l_e_n_, _P_L___b_l_o_b___t _*_t_y_p_e)
    Store  the described blob in _t.  The return value  indicates whether
    a  new blob  was allocated  (FALSE) or the  blob is  a reference  to
    an  existing  blob (TRUE).  Reporting new/existing  can  be used  to
    deal  with external objects having their  own reference counts.   If
    the  return is TRUE  this reference count  must be incremented,  and
    it  must be  decremented on  blob destruction  callback.   See  also
    PL_put_atom_nchars().


int PPLL__ggeett__bblloobb(_t_e_r_m___t _t_, _v_o_i_d _*_*_b_l_o_b_, _s_i_z_e___t _*_l_e_n_, _P_L___b_l_o_b___t _*_*_t_y_p_e)
    If  _t holds a blob or atom,  get the data and type and  return TRUE.
    Otherwise  return FALSE. Each result  pointer may be NULL, in  which
    case the requested information is ignored.


void * PPLL__bblloobb__ddaattaa(_a_t_o_m___t _a_, _s_i_z_e___t _*_l_e_n_, _P_L___b_l_o_b___t _*_*_t_y_p_e)
    Get  the data  and type  associated to  a blob.    This function  is
    mainly used from the callback functions described in section ????.


1111..44..88 EExxcchhaannggiinngg GGMMPP nnuummbbeerrss

If  SWI-Prolog is  linked  with the  GNU Multiple  Precision  Arithmetic
Library  (GMP,  used   by  default),  the  foreign   interface  provides
functions  for   exchanging  numeric   values  to   GMP  types.       To
access  these functions  the  header  <gmp.h> must  be  included  _b_e_f_o_r_e
<SWI-Prolog.h>.   Foreign code using GMP  linked to SWI-Prolog asks  for
some considerations.

  o SWI-Prolog  normally   rebinds  the  GMP  allocation  functions  us-
    ing  mp_set_memory_functions().     This  means  SWI-Prolog  must  be
    initialised  before  the  foreign  code touches  any  GMP  function.
    You  can call \cfuncref{PL_action}{PL_GMP_SET_ALLOC_FUNCTIONS, TRUE}
    to   force   Prolog's   GMP   initialization   without   doing   the
    rest    of   the    Prolog   initialization.          If   you    do
    not    want   Prolog    rebinding   the   GMP    allocation,    call
    \cfuncref{PL_action}{PL_GMP_SET_ALLOC_FUNCTIONS, FALSE}  _b_e_f_o_r_e ini-
    tializing Prolog.

  o On  Windows, each DLL  has its own  memory pool.   To make  exchange
    of  GMP numbers between  Prolog and foreign  code possible you  must
    either  let Prolog rebind the allocation functions (default)  or you
    must  recompile  SWI-Prolog to  link to  a DLL  version  of the  GMP
    library.

Here is an example exploiting the function mpz_nextprime():

________________________________________________________________________|                                                                        |

|#include <gmp.h>                                                        |
|#include <SWI-Prolog.h>                                                 |
|                                                                        |
|static foreign_t                                                        |
|next_prime(term_t n, term_t prime)                                      |

|{ mpz_t mpz;                                                            |
|  int rc;                                                               |
|                                                                        |
|  mpz_init(mpz);                                                        |
|  if ( PL_get_mpz(n, mpz) )                                             |
|  { mpz_nextprime(mpz, mpz);                                            |
|                                                                        |
|    rc = PL_unify_mpz(prime, mpz);                                      |

|  } else                                                                |
|    rc = FALSE;                                                         |
|                                                                        |
|  mpz_clear(mpz);                                                       |
|  return rc;                                                            |
|}                                                                       |
|                                                                        |

|install_t                                                               |
|install()                                                               |
|{ PL_register_foreign("next_prime", 2, next_prime, 0);                  |
|}|_____________________________________________________________________ | |


int PPLL__ggeett__mmppzz(_t_e_r_m___t _t_, _m_p_z___t _m_p_z)
    If  _t represents an integer,  _m_p_z is filled  with the value and  the
    function  returns TRUE. Otherwise _m_p_z is untouched and  the function
    returns  FALSE.  Note that  _m_p_z must  have  been initialised  before
    calling  this  function and  must  be cleared  using  mpz_clear()  to
    reclaim any storage associated with it.


int PPLL__ggeett__mmppqq(_t_e_r_m___t _t_, _m_p_q___t _m_p_q)
    If  _t is an integer or rational number (term rdiv/2), _m_p_q  is filled
    with  the _n_o_r_m_a_l_i_s_e_d rational number and the function  returns TRUE.
    Otherwise  _m_p_q is  untouched and  the function  returns FALSE.  Note
    that  _m_p_q must  have been initialised  before calling this  function
    and  must  be  cleared  using  mpq_clear()  to  reclaim  any  storage
    associated with it.


int PPLL__uunniiffyy__mmppzz(_t_e_r_m___t _t_, _m_p_z___t _m_p_z)
    Unify  _t with the integer value  represented by _m_p_z and return  TRUE
    on success.  The _m_p_z argument is not changed.


int PPLL__uunniiffyy__mmppqq(_t_e_r_m___t _t_, _m_p_q___t _m_p_q)
    Unify  _t with a rational number  represented by _m_p_q and return  TRUE
    on  success.    Note  that  _t is  unified  with  an integer  if  the
    denominator is 1.  The _m_p_q argument is not changed.


1111..44..99 CCaalllliinngg PPrroolloogg ffrroomm CC

The  Prolog engine  can  be called  from  C.  There are  two  interfaces
for this.    For the  first, a  term is created  that could  be used  as
an  argument to  call/1,  and then  PL_call() is  used to  call  Prolog.
This  system is  simple, but  does not  allow to  inspect the  different
answers  to a  non-deterministic  goal and  is  relatively slow  as  the
runtime  system needs  to  find the  predicate.    The  other  interface
is  based on  PL_open_query(),  PL_next_solution() and  PL_cut_query() or
PL_close_query().     This mechanism  is  more powerful,  but  also  more
complicated to use.


1111..44..99..11 PPrreeddiiccaattee rreeffeerreenncceess

This  section  discusses   the  functions  used  to  communicate   about
predicates.     Though  a  Prolog  predicate  may  be  defined  or  not,
redefined,  etc.,  a  Prolog predicate  has  a handle  that  is  neither
destroyed nor moved.  This handle is known by the type predicate_t.


predicate_t PPLL__pprreedd(_f_u_n_c_t_o_r___t _f_, _m_o_d_u_l_e___t _m)
    Return  a handle to a predicate for the specified name/arity  in the
    given module.   This function always succeeds, creating a handle for
    an  undefined predicate if no handle  was available.  If the  module
    argument _m is NULL, the current context module is used.


predicate_t PPLL__pprreeddiiccaattee(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_, _i_n_t _a_r_i_t_y_, _c_o_n_s_t _c_h_a_r_* _m_o_d_u_l_e)
    Same  as PL_pred(),  but provides a more convenient interface  to the
    C programmer.


void PPLL__pprreeddiiccaattee__iinnffoo(_p_r_e_d_i_c_a_t_e___t _p_, _a_t_o_m___t _*_n_, _s_i_z_e___t _*_a_, _m_o_d_u_l_e___t _*_m)
    Return  information on the  predicate _p.   The  name is stored  over
    _n,  the  arity  over _a,  while  _m  receives the  definition  module.
    Note  that  the  latter need  not  be  the same  as  specified  with
    PL_predicate().  If the predicate is imported  into the module given
    to  PL_predicate(),  this function will  return the module where  the
    predicate is defined.  Any of the arguments _n, _a and _m can be NULL.


1111..44..99..22 IInniittiiaattiinngg aa qquueerryy ffrroomm CC

This  section discusses  the  functions  for creating  and  manipulating
queries from C. Note that a foreign context can have  at most one active
query.   This implies that it is  allowed to make strictly nested  calls
between C  and Prolog  (Prolog calls C,  calls Prolog,  calls C,  etc.),
but it  is nnoott  allowed to  open multiple queries  and start  generating
solutions for  each of them by  calling PL_next_solution().   Be sure  to
call PL_cut_query() or PL_close_query() on any  query you opened  before
opening the next or returning control back to Prolog.


qid_t PPLL__ooppeenn__qquueerryy(_m_o_d_u_l_e___t _c_t_x_, _i_n_t _f_l_a_g_s_, _p_r_e_d_i_c_a_t_e___t _p_, _t_e_r_m___t _+_t_0)
    Opens  a  query and  returns  an identifier  for  it.   _c_t_x  is  the
    _c_o_n_t_e_x_t  _m_o_d_u_l_e  of  the  goal.    When  NULL,  the  context  module
    of  the  calling context  will  be used,  or  user  if there  is  no
    calling  context  (as  may  happen  in  embedded  systems).     Note
    that  the context  module  only matters  for _m_e_t_a_-_p_r_e_d_i_c_a_t_e_s.    See
    meta_predicate/1, context_module/1 and module_transparent/1.   The _p
    argument  specifies the  predicate, and  should be the  result of  a
    call  to PL_pred() or PL_predicate().   Note that  it is allowed  to
    store  this handle as global data  and reuse it for future  queries.
    The  term reference _t_0 is the  first of a vector of term  references
    as returned by PL_new_term_refs(_n).

    The  _f_l_a_g_s  arguments provides  some additional  options  concerning
    debugging  and  exception handling.    It  is a  bitwise _o_r  of  the
    following values:

    PL_Q_NORMAL
         Normal operation.  The debugger inherits its  settings from the
         environment.   If an  exception occurs that  is not handled  in
         Prolog,  a message  is printed  and the  tracer  is started  to
         debug the error.

    PL_Q_NODEBUG
         Switch off the debugger while executing the goal.   This option
         is used by many  calls to hook-predicates to avoid  tracing the
         hooks.   An example is  print/1 calling portray/1 from  foreign
         code.

    PL_Q_CATCH_EXCEPTION
         If an  exception is  raised while  executing the  goal, do  not
         report it, but make it available for PL_exception().

    PL_Q_PASS_EXCEPTION
         As PL_Q_CATCH_EXCEPTION,  but do  not invalidate the  exception-
         term  while   calling  PL_close_query().      This  option   is
         experimental.

    PL_Q_ALLOW_YIELD
         Support the  I_YIELD  instruction for engine-based  coroutining.
         See $engine_yield/2 in boot/init.pl for details.

    PL_Q_EXT_STATUS
         Make PL_next_solution() return  extended status.    Instead  of
         only  TRUE or  FALSE  extended  status as  illustrated  in  the
         following table:

         __EExxtteennddeedd______________NNoorrmmaall____________________________________________________________________________________________________
          PL_S_EXCEPTION FALSE   Exception available through PL_exception()
          PL_S_FALSE     FALSE   Query failed
          PL_S_TRUE      TRUE    Query succeeded with choicepoint
          PL_S_LAST      TRUE    Query succeeded without choicepoint

    PL_open_query() can return the query identifier `0' if  there is not
    enough  space on  the environment  stack.   This function  succeeds,
    even  if  the  referenced  predicate  is  not  defined.     In  this
    case,  running  the query  using PL_next_solution()  will return  an
    existence_error.  See PL_exception().

    The example below opens  a query to the predicate is_a/2 to find the
    ancestor  of `me'.  The reference to the predicate is valid  for the
    duration of the process and may be cached by the client.

    ____________________________________________________________________|                                                                    |

    | char *                                                             |
    | ancestor(const char *me)                                           |
    | { term_t a0 = PL_new_term_refs(2);                                 |
    |   static predicate_t p;                                            |
    |                                                                    |
    |   if ( !p )                                                        |
    |     p = PL_predicate("is_a", 2, "database");                       |

    |                                                                    |
    |   PL_put_atom_chars(a0, me);                                       |
    |   PL_open_query(NULL, PL_Q_NORMAL, p, a0);                         |
    |   ...                                                              |
    ||}_________________________________________________________________ ||


int PPLL__nneexxtt__ssoolluuttiioonn(_q_i_d___t _q_i_d)
    Generate the first (next)  solution for the given query.  The return
    value  is TRUE if  a solution  was found, or  FALSE to indicate  the
    query  could not be proven.  This function may be  called repeatedly
    until it fails to generate all solutions to the query.


void PPLL__ccuutt__qquueerryy(_q_i_d___t _q_i_d)
    Discards  the query, but does not delete any of the data  created by
    the  query.   It just invalidates  _q_i_d, allowing for  a new call  to
    PL_open_query() in this context.


void PPLL__cclloossee__qquueerryy(_q_i_d___t _q_i_d)
    As  PL_cut_query(), but  all data and  bindings created by the  query
    are destroyed.


qid_t PPLL__ccuurrrreenntt__qquueerryy(_v_o_i_d)
    Returns  the query id of  of the current query  or 0 if the  current
    thread is not executing any queries.


int PPLL__ccaallll__pprreeddiiccaattee(_m_o_d_u_l_e___t _m_, _i_n_t _f_l_a_g_s_, _p_r_e_d_i_c_a_t_e___t _p_r_e_d_, _t_e_r_m___t _+_t_0)
    Shorthand  for  PL_open_query(),  PL_next_solution(),  PL_cut_query(),
    generating  a single solution.   The arguments  are the same as  for
    PL_open_query(), the return value is the same as PL_next_solution().


int PPLL__ccaallll(_t_e_r_m___t _t_, _m_o_d_u_l_e___t _m)
    Call  term _t just like the Prolog predicate once/1.  _t  is called in
    the  module _m, or in the context  module if _m == NULL.  Returns TRUE
    if  the call succeeds, FALSE otherwise.  Figure ???? shows  an example
    to  obtain the number of defined atoms.   All checks are  omitted to
    improve readability.


1111..44..1100 DDiissccaarrddiinngg DDaattaa

The Prolog data  created and term references  needed to set up the  call
and/or analyse  the result can  in most cases  be discarded right  after
the  call.    PL_close_query() allows  for destroying  the  data,  while
leaving the  term references.   The calls below  may be used to  destroy
term references and data.  See figure ???? for an example.


fid_t PPLL__ooppeenn__ffoorreeiiggnn__ffrraammee()
    Create  a  foreign frame,  holding  a mark  that allows  the  system
    to  undo bindings  and destroy  data created  after it,  as well  as
    providing  the  environment  for creating  term  references.    This
    function   is  called  by  the  kernel  before  calling   a  foreign
    predicate.


void PPLL__cclloossee__ffoorreeiiggnn__ffrraammee(_f_i_d___t _i_d)
    Discard  all term  references created  after the  frame was  opened.
    All  other Prolog data is retained.  This function is called  by the
    kernel whenever a foreign function returns control back to Prolog.


void PPLL__ddiissccaarrdd__ffoorreeiiggnn__ffrraammee(_f_i_d___t _i_d)
    Same  as PL_close_foreign_frame(),  but also  undo all bindings  made
    since the open and destroy all Prolog data.


void PPLL__rreewwiinndd__ffoorreeiiggnn__ffrraammee(_f_i_d___t _i_d)
    Undo all bindings  and discard all term references created since the
    frame  was created, but  do not pop  the frame.   That is, the  same
    frame  can be rewound multiple times, and must eventually  be closed
    or discarded.

It is obligatory to call either of the two  closing functions to discard
a foreign frame.  Foreign frames may be nested.
________________________________________________________________________|                                                                        |
|int                                                                     |

|count_atoms()                                                           |
|{ fid_t fid = PL_open_foreign_frame();                                  |
|  term_t goal  = PL_new_term_ref();                                     |
|  term_t a1    = PL_new_term_ref();                                     |
|  term_t a2    = PL_new_term_ref();                                     |
|  functor_t s2 = PL_new_functor(PL_new_atom("statistics"), 2);          |
|  int atoms;                                                            |
|                                                                        |

|  PL_put_atom_chars(a1, "atoms");                                       |
|  PL_cons_functor(goal, s2, a1, a2);                                    |
|  PL_call(goal, NULL);         /* call it in current module */          |
|                                                                        |
|  PL_get_integer(a2, &atoms);                                           |
|  PL_discard_foreign_frame(fid);                                        |
|                                                                        |

|  return atoms;                                                         |
|}|_____________________________________________________________________ | |

                      Figure 11.3:  Calling Prolog


1111..44..1111 FFoorreeiiggnn CCooddee aanndd MMoodduulleess

Modules are  identified via a  unique handle.   The following  functions
are available to query and manipulate modules.


module_t PPLL__ccoonntteexxtt()
    Return the module  identifier of the context module of the currently
    active foreign predicate.


int PPLL__ssttrriipp__mmoodduullee(_t_e_r_m___t _+_r_a_w_, _m_o_d_u_l_e___t _*_m_, _t_e_r_m___t _-_p_l_a_i_n)
    Utility  function.  If  _r_a_w is a  term, possibly holding the  module
    construct <_m_o_d_u_l_e>:<_r_e_s_t>, this function will  make _p_l_a_i_n a reference
    to  <_r_e_s_t>  and fill  _m_o_d_u_l_e _*  with <_m_o_d_u_l_e>.    For further  nested
    module  constructs the  innermost module is  returned via _m_o_d_u_l_e  _*.
    If  _r_a_w is not a module construct, _r_a_w will simply be put  in _p_l_a_i_n.
    The  value  pointed  to by  _m  must  be initialized  before  calling
    PL_strip_module(), either to the  default module or to NULL.  A NULL
    value  is replaced by the current  context module if _r_a_w carries  no
    module.   The following example  shows how to obtain the plain  term
    and module if the default module is the user module:

    ____________________________________________________________________|                                                                    |
    | { module m = PL_new_module(PL_new_atom("user"));                   |
    |   term_t plain = PL_new_term_ref();                                |
    |                                                                    |

    |   PL_strip_module(term, &m, plain);                                |
    |   ...                                                              |
    ||}_________________________________________________________________ ||


atom_t PPLL__mmoodduullee__nnaammee(_m_o_d_u_l_e___t _m_o_d_u_l_e)
    Return the name of _m_o_d_u_l_e as an atom.


module_t PPLL__nneeww__mmoodduullee(_a_t_o_m___t _n_a_m_e)
    Find an existing module or create a new module with the name _n_a_m_e.


1111..44..1122 PPrroolloogg eexxcceeppttiioonnss iinn ffoorreeiiggnn ccooddee

This     section    discusses     PL_exception(),     PL_throw()     and
PL_raise_exception(),  the  interface functions  to  detect and  generate
Prolog exceptions from C code.  PL_throw() and PL_raise_exception() from
the  C interface  raise  an exception  from foreign  code.    PL_throw()
exploits  the  C  function  longjmp()  to  return   immediately  to  the
innermost  PL_next_solution().      PL_raise_exception() registers   the
exception term and returns FALSE. If a foreign  predicate returns FALSE,
while  an exception  term  is registered,  a  Prolog exception  will  be
raised by the virtual machine.

Calling these functions  outside the context of a function  implementing
a foreign predicate results in undefined behaviour.

PL_exception() may  be used  after a  call to  PL_next_solution() fails,
and returns a  term reference to an  exception term if an exception  was
raised, and 0 otherwise.

If  a C  function  implementing a  predicate  calls Prolog  and  detects
an  exception using  PL_exception(), it  can  handle this  exception  or
return  with the  exception.    Some caution  is required  though.    It
is  nnoott allowed  to call  PL_close_query() or  PL_discard_foreign_frame()
afterwards,  as  this  will  invalidate  the  exception  term.     Below
is  the  code  that calls  a  Prolog-defined  arithmetic  function  (see
arithmetic_function/1).

If PL_next_solution() succeeds,  the result  is analysed and  translated
to  a number,  after  which the  query  is closed  and all  Prolog  data
created  after  PL_open_foreign_frame() is  destroyed.    On  the  other
hand,  if  PL_next_solution() fails  and  if an  exception  was  raised,
just  pass it.     Otherwise generate  an  exception  (PL_error() is  an
internal  call  for  building  the  standard  error  terms  and  calling
PL_raise_exception()).    After this,  the Prolog  environment should  be
discarded  using  PL_cut_query() and  PL_close_foreign_frame() to  avoid
invalidating the exception term.

________________________________________________________________________|                                                                        |
|static int                                                              |

|prologFunction(ArithFunction f, term_t av, Number r)                    |
|{ int arity = f->proc->definition->functor->arity;                      |
|  fid_t fid = PL_open_foreign_frame();                                  |
|  qid_t qid;                                                            |
|  int rval;                                                             |
|                                                                        |
|  qid = PL_open_query(NULL, PL_Q_NORMAL, f->proc, av);                  |
|                                                                        |

|  if ( PL_next_solution(qid) )                                          |
|  { rval = valueExpression(av+arity-1, r);                              |
|    PL_close_query(qid);                                                |
|    PL_discard_foreign_frame(fid);                                      |
|  } else                                                                |
|  { term_t except;                                                      |
|                                                                        |

|    if ( (except = PL_exception(qid)) )                                 |
|    { rval = PL_throw(except);          /* pass exception */            |
|    } else                                                              |
|    { char *name = stringAtom(f->proc->definition->functor->name);      |
|                                                                        |
|                                        /* generate exception */        |
|      rval = PL_error(name, arity-1, NULL, ERR_FAILED, f->proc);        |
|    }                                                                   |

|                                                                        |
|    PL_cut_query(qid);                  /* donot destroy data */        |
|    PL_close_foreign_frame(fid);        /* same */                      |
|  }                                                                     |
|                                                                        |
|  return rval;                                                          |
|}|_____________________________________________________________________ | |


int PPLL__rraaiissee__eexxcceeppttiioonn(_t_e_r_m___t _e_x_c_e_p_t_i_o_n)
    Generate  an exception (as  throw/1) and return  FALSE. Below is  an
    example returning an exception from a foreign predicate:

    ____________________________________________________________________|                                                                    |
    | foreign_t                                                          |

    | pl_hello(term_t to)                                                |
    | { char *s;                                                         |
    |                                                                    |
    |   if ( PL_get_atom_chars(to, &s) )                                 |
    |   { Sprintf("Hello \"%s\"\n", s);                                  |
    |                                                                    |
    |     PL_succeed;                                                    |
    |   } else                                                           |

    |   { term_t except = PL_new_term_ref();                             |
    |                                                                    |
    |     PL_unify_term(except,                                          |
    |                   PL_FUNCTOR_CHARS, "type_error", 2,               |
    |                     PL_CHARS, "atom",                              |
    |                     PL_TERM, to);                                  |
    |                                                                    |

    |     return PL_raise_exception(except);                             |
    |   }                                                                |
    ||}_________________________________________________________________ ||


int PPLL__tthhrrooww(_t_e_r_m___t _e_x_c_e_p_t_i_o_n)
    Similar  to PL_raise_exception(),  but returns using the C  longjmp()
    function to the innermost PL_next_solution().


term_t PPLL__eexxcceeppttiioonn(_q_i_d___t _q_i_d)
    If  PL_next_solution() fails,  this  can be  due to  normal  failure
    of  the  Prolog  call, or  because  an  exception was  raised  using
    throw/1.   This function returns  a handle to the exception term  if
    an exception was raised,  or 0 if the Prolog goal simply failed.  If
    there is  an exception, PL_exception()allocates  a term-handle using
    PL_new_term_ref() that is used to return the exception term.

    Additionally,    \cfuncref{PL_exception}{0}  returns   the   pending
    exception  in the  current query or  0 if  no exception is  pending.
    This can be used  to check the error status after a failing call to,
    e.g., one of the unification functions.


void PPLL__cclleeaarr__eexxcceeppttiioonn(_v_o_i_d)
    Tells  Prolog that the encountered exception must be ignored.   This
    function  must be called  if control remains  in C after a  previous
    API call fails with an exception.


1111..44..1133 CCaattcchhiinngg SSiiggnnaallss ((SSooffttwwaarree IInntteerrrruuppttss))

SWI-Prolog offers both  a C and Prolog  interface to deal with  software
interrupts (signals).    The Prolog  mapping is defined  in section  ????.
This subsection deals with handling signals from C.

If a signal is not  used by Prolog and the handler does not  call Prolog
in any way, the native signal interface routines may be used.

Any handler that  wishes to call one  of the Prolog interface  functions
should  call  PL_sigaction()  to  install  the  handler.     PL_signal()
provides a deprecated interface that is notably not  capable of properly
restoring the old signal status if the signal was  previously handled by
Prolog.


int PPLL__ssiiggaaccttiioonn(_i_n_t _s_i_g_, _p_l___s_i_g_a_c_t_i_o_n___t _*_a_c_t_, _p_l___s_i_g_a_c_t_i_o_n___t _*_o_l_d_a_c_t)
    Install  or query  the status  for signal  _s_i_g.   The  signal is  an
    integer  between 1 and 64, where the where the signals up to  32 are
    mapped to OS  signals and signals above that are handled by Prolog's
    synchronous  signal handling.   The pl_sigaction_t is a struct  with
    the following definition:

    ____________________________________________________________________|                                                                    |
    | typedef struct pl_sigaction                                        |

    | { void        (*sa_cfunction)(int);     /* traditional C function */|
    |   predicate_t sa_predicate;             /* call a predicate */     |
    |   int         sa_flags;                 /* additional flags */     |
    ||}_pl_sigaction_t;_________________________________________________ ||

    The  sa_flags  is  a  bitwise  or  of  PLSIG_THROW,  PLSIG_SYNC  and
    PLSIG_NOFRAME.  Signal   handling  is  enabled  if   PLSIG_THROW   is
    provided, sa_cfunction or sa_predicate is provided.  sa_predicate is
    a  predicate handle for a predicate with  arity 1.  If no  action is
    provided  the signal  handling for  this signal is  restored to  the
    default before PL_initialise() was called.

    Finally,  0 (zero) may be passsed for _s_i_g.  In that  case the system
    allocates a free signal  in the _P_r_o_l_o_g _r_a_n_g_e (32...64).  Such signal
    handler are activated using PL_thread_raise().


void (*)() PPLL__ssiiggnnaall(_s_i_g_, _f_u_n_c)
    This  function  is equivalent  to  the BSD-Unix  signal()  function,
    regardless  of the  platform used.   The  signal handler is  blocked
    while  the signal routine  is active, and automatically  reactivated
    after the handler returns.

    After  a  signal handler  is  registered using  this  function,  the
    native  signal interface  redirects the signal  to a generic  signal
    handler  inside  SWI-Prolog.   This  generic  handler validates  the
    environment,   creates  a  suitable  environment  for   calling  the
    interface functions described  in this chapter and finally calls the
    registered user-handler.

    By  default, signals are handled  asynchronously (i.e., at the  time
    they  arrive).   It is inherently  dangerous to call extensive  code
    fragments,  and especially exception related code  from asynchronous
    handlers.     The  interface  allows  for  _s_y_n_c_h_r_o_n_o_u_s  handling  of
    signals.   In  this case  the native OS  handler just schedules  the
    signal  using PL_raise(),  which is checked by PL_handle_signals() at
    the  call- and redo-port.  This behaviour is realised by  _o_r-ing _s_i_g
    with the constant PL_SIGSYNC.

    Signal    handling    routines    may   raise    exceptions    using
    PL_raise_exception().      The  use  of  PL_throw()  is  not   safe.
    If  a  synchronous handler  raises an  exception,  the exception  is
    delayed to the next call to PL_handle_signals();


int PPLL__rraaiissee(_i_n_t _s_i_g)
    Register  _s_i_g  for  _s_y_n_c_h_r_o_n_o_u_s handling  by  Prolog.    Synchronous
    signals  are  handled at  the  call-port or  if foreign  code  calls
    PL_handle_signals().  See also thread_signal/2.


int PPLL__hhaannddllee__ssiiggnnaallss(_v_o_i_d)
    Handle  any signals  pending from  PL_raise().   PL_handle_signals()
    is  called at each  pass through the call-  and redo-port at a  safe
    point.   Exceptions raised by the handler using PL_raise_exception()
    are properly passed to the environment.

    The  user  may   call  this  function  inside  long-running  foreign
    functions to handle  scheduled interrupts.  This routine returns the
    number  of signals handled.   If a handler raises an exception,  the
    return value is  -1 and the calling routine should return with FALSE
    as soon as possible.


int PPLL__ggeett__ssiiggnnuumm__eexx(_t_e_r_m___t _t_, _i_n_t _*_s_i_g)
    Extract  a signal specification from a  Prolog term and store as  an
    integer  signal number in _s_i_g.   The specification is an integer,  a
    lowercase  signal name without SIG or  the full signal name.   These
    refer  to the same:  9, kill and SIGKILL. Leaves a typed,  domain or
    instantiation error if the conversion fails.


1111..44..1144 MMiisscceellllaanneeoouuss


1111..44..1144..11 TTeerrmm CCoommppaarriissoonn


int PPLL__ccoommppaarree(_t_e_r_m___t _t_1_, _t_e_r_m___t _t_2)
    Compares  two terms using  the standard order  of terms and  returns
    -1, 0 or 1.  See also compare/3.


int PPLL__ssaammee__ccoommppoouunndd(_t_e_r_m___t _t_1_, _t_e_r_m___t _t_2)
    Yields TRUE if _t_1  and _t_2 refer to physically the same compound term
    and FALSE otherwise.


1111..44..1144..22 RReeccoorrddeedd ddaattaabbaassee

In some  applications it is  useful to store  and retrieve Prolog  terms
from C code.  For example, the XPCE graphical  environment does this for
storing arbitrary Prolog data as slot-data of XPCE objects.

Please note  that the  returned handles  have no meaning  at the  Prolog
level  and  the recorded  terms  are  not  visible from  Prolog.     The
functions PL_recorded() and PL_erase() are  the only functions that  can
operate on the stored term.

Two groups of functions are provided.   The first group (PL_record() and
friends) store Prolog terms on the Prolog heap for  retrieval during the
same session.   These functions are also used by recorda/3  and friends.
The recorded  database may be used  to communicate Prolog terms  between
threads.


record_t PPLL__rreeccoorrdd(_t_e_r_m___t _+_t)
    Record  the term _t into the Prolog database as recorda/3  and return
    an  opaque handle to  the term.   The returned handle remains  valid
    until  PL_erase() is called on  it.   PL_recorded() is used to  copy
    recorded terms back to the Prolog stack.


record_t PPLL__dduupplliiccaattee__rreeccoorrdd(_r_e_c_o_r_d___t _r_e_c_o_r_d)
    Return  a duplicate  of _r_e_c_o_r_d.   As  records are read-only  objects
    this function merely increments the records reference count.


int PPLL__rreeccoorrddeedd(_r_e_c_o_r_d___t _r_e_c_o_r_d_, _t_e_r_m___t _-_t)
    Copy a recorded term  back to the Prolog stack.  The same record may
    be used to copy  multiple instances at any time to the Prolog stack.
    Returns  TRUE on  success, and FALSE  if there  is not enough  space
    on  the stack  to accommodate the  term.   See also  PL_record() and
    PL_erase().


void PPLL__eerraassee(_r_e_c_o_r_d___t _r_e_c_o_r_d)
    Remove  the recorded term from  the Prolog database, reclaiming  all
    associated memory resources.

The  second group  (headed  by PL_record_external()) provides  the  same
functionality, but the returned data has properties  that enable storing
the  data  on an  external  device.     It has  been  designed  to  make
it  possible to  store Prolog  terms  fast and  compact in  an  external
database.  Here are the main features:

  o _I_n_d_e_p_e_n_d_e_n_t _o_f _s_e_s_s_i_o_n
    Records  can  be communicated  to another  Prolog  session and  made
    visible using PL_recorded_external().

  o _B_i_n_a_r_y
    The representation is  binary for maximum performance.  The returned
    data may contain zero bytes.

  o _B_y_t_e_-_o_r_d_e_r _i_n_d_e_p_e_n_d_e_n_t
    The   representation  can  be  transferred  between   machines  with
    different byte order.

  o _N_o _a_l_i_g_n_m_e_n_t _r_e_s_t_r_i_c_t_i_o_n_s
    There are no  memory alignment restrictions and copies of the record
    can  thus be  moved freely.    For example,  it is  possible to  use
    this  representation to exchange  terms using shared memory  between
    different Prolog processes.

  o _C_o_m_p_a_c_t
    It  is  assumed  that a  smaller  memory footprint  will  eventually
    outperform slightly faster representations.

  o _S_t_a_b_l_e
    The  format is  designed  for future  enhancements without  breaking
    compatibility with older records.


char * PPLL__rreeccoorrdd__eexxtteerrnnaall(_t_e_r_m___t _+_t_, _s_i_z_e___t _*_l_e_n)
    Record  the term _t into the Prolog database as recorda/3  and return
    an  opaque handle to  the term.   The returned handle remains  valid
    until PL_erase_external() is called on it.

    It  is allowed  to copy the  data and use  PL_recorded_external() on
    the  copy.   The user  is responsible for  the memory management  of
    the  copy.    After copying,  the original  may  be discarded  using
    PL_erase_external().

    PL_recorded_external() is used to  copy such recorded terms back  to
    the Prolog stack.


int PPLL__rreeccoorrddeedd__eexxtteerrnnaall(_c_o_n_s_t _c_h_a_r _*_r_e_c_o_r_d_, _t_e_r_m___t _-_t)
    Copy a recorded term  back to the Prolog stack.  The same record may
    be used to copy  multiple instances at any time to the Prolog stack.
    See also PL_record_external() and PL_erase_external().


int PPLL__eerraassee__eexxtteerrnnaall(_c_h_a_r _*_r_e_c_o_r_d)
    Remove  the recorded term from  the Prolog database, reclaiming  all
    associated memory resources.


1111..44..1144..33 GGeettttiinngg ffiillee nnaammeess

The function PL_get_file_name() provides access to Prolog filenames  and
its  file-search mechanism  described  with absolute_file_name/3.    Its
existence is motivated to realise a uniform interface to  deal with file
properties, search, naming conventions, etc., from foreign code.


int PPLL__ggeett__ffiillee__nnaammee(_t_e_r_m___t _s_p_e_c_, _c_h_a_r _*_*_n_a_m_e_, _i_n_t _f_l_a_g_s)
    Translate  a Prolog  term into  a file  name.   The  name is  stored
    in  the static buffer  ring described with  th PL_get_chars() option
    BUF_RING.  Conversion from  the internal  UNICODE  encoding is  done
    using   standard  C  library  functions.     _f_l_a_g_s  is   a  bit-mask
    controlling the conversion process.  Options are:

    PL_FILE_ABSOLUTE
         Return an absolute path to the requested file.

    PL_FILE_OSPATH
         Return  the  name  using  the  hosting  OS  conventions.     On
         MS-Windows, \ is  used to separate directories rather than  the
         canonical /.

    PL_FILE_SEARCH
         Invoke  absolute_file_name/3.      This   implies  rules   from
         file_search_path/2are used.

    PL_FILE_EXIST
         Demand the path to refer to an existing entity.

    PL_FILE_READ
         Demand read-access on the result.

    PL_FILE_WRITE
         Demand write-access on the result.

    PL_FILE_EXECUTE
         Demand execute-access on the result.

    PL_FILE_NOERRORS
         Do not raise any exceptions.


int PPLL__ggeett__ffiillee__nnaammeeWW(_t_e_r_m___t _s_p_e_c_, _w_c_h_a_r___t _*_*_n_a_m_e_, _i_n_t _f_l_a_g_s)
    Same  as  PL_get_file_name(), but  returns the  filename  as a  wide-
    character  string.    This is  intended for  Windows  to access  the
    Unicode  version of the Win32 API. Note that the flag PL_FILE_OSPATH
    must  be provided to  fetch a filename in  OS native (e.g.,  C:\x\y)
    notation.


1111..44..1144..44 DDeeaalliinngg wwiitthh PPrroolloogg ffllaaggss ffrroomm CC

Foreign code can  set or create Prolog flags using  PL_set_prolog_flag().
See set_prolog_flag/2and create_prolog_flag/3.


int PPLL__sseett__pprroolloogg__ffllaagg(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_, _i_n_t _t_y_p_e_, _._._.)
    Set/create  a Prolog flag from C.  _n_a_m_e is the name of the  affected
    flag.    _t_y_p_e  is  one of  the  values below,  which  also  dictates
    the  type of  the  final argument.    The function  returns TRUE  on
    success  and FALSE on failure.   This function can be called  _b_e_f_o_r_e
    PL_initialise(),  making the  flag available to  the Prolog  startup
    code.

    PL_BOOL
         Create a boolean  (true or false) flag.   The argument must  be
         an int.

    PL_ATOM
         Create a flag with an  atom as value.  The argument must  be of
         type const char *.

    PL_INTEGER
         Create a flag with an  integer as value.  The argument  must be
         of type intptr_t *.


1111..44..1155 EErrrroorrss aanndd wwaarrnniinnggss

PL_warning() prints a  standard Prolog warning  message to the  standard
error (user_error) stream.   Please note  that new code should  consider
using  PL_raise_exception() to  raise a  Prolog  exception.    See  also
section ????.


int PPLL__wwaarrnniinngg(_f_o_r_m_a_t_, _a_1_, _._._.)
    Print  an  error message  starting  with `[WARNING: ',  followed  by
    the  output from  _f_o_r_m_a_t, followed  by a `]'  and a newline.    Then
    start  the tracer.   _f_o_r_m_a_t and  the arguments are  the same as  for
    printf(2).  Always returns FALSE.


1111..44..1166 EEnnvviirroonnmmeenntt CCoonnttrrooll ffrroomm FFoorreeiiggnn CCooddee


int PPLL__aaccttiioonn(_i_n_t_, _._._.)
    Perform  some  action on  the  Prolog system.    _i_n_t  describes  the
    action.   Remaining arguments depend  on the requested action.   The
    actions are listed below:

    PPLL__AACCTTIIOONN__TTRRAACCEE
         Start Prolog tracer (trace/0).  Requires no arguments.

    PPLL__AACCTTIIOONN__DDEEBBUUGG
         Switch on Prolog debug mode (debug/0).  Requires no arguments.

    PPLL__AACCTTIIOONN__BBAACCKKTTRRAACCEE
         Print backtrace  on current output  stream.   The argument  (an
         int) is the number of frames printed.

    PPLL__AACCTTIIOONN__HHAALLTT
         Halt Prolog  execution.   This action  should be called  rather
         than Unix exit()  to give Prolog  the opportunity to clean  up.
         This call does not return.   The argument (an int) is  the exit
         code.  See halt/1.

    PPLL__AACCTTIIOONN__AABBOORRTT
         Generate a Prolog abort (abort/0).  This call  does not return.
         Requires no arguments.

    PPLL__AACCTTIIOONN__BBRREEAAKK
         Create a standard Prolog break environment (break/0).   Returns
         after the user  types the end-of-file  character.  Requires  no
         arguments.

    PPLL__AACCTTIIOONN__GGUUIIAAPPPP
         Windows:  Used to  indicate to the kernel that  the application
         is a GUI  application if the argument is  not 0, and a  console
         application if  the argument is 0.   If  a fatal error  occurs,
         the system uses  a windows messagebox to  report this on a  GUI
         application, and otherwise simply prints the error and exits.

    PPLL__AACCTTIIOONN__TTRRAADDIITTIIOONNAALL
         Same effect  as using  --traditional.   Must  be called  _b_e_f_o_r_e
         PL_initialise().

    PPLL__AACCTTIIOONN__WWRRIITTEE
         Write the argument, a char * to the current output stream.

    PPLL__AACCTTIIOONN__FFLLUUSSHH
         Flush the current output stream.  Requires no arguments.

    PPLL__AACCTTIIOONN__AATTTTAACCHH__CCOONNSSOOLLEE
         Attach a  console to a  thread if it  does not have  one.   See
         attach_console/0.

    PPLL__GGMMPP__SSEETT__AALLLLOOCC__FFUUNNCCTTIIOONNSS
         Takes  an integer  argument.    If  TRUE, the  GMP  allocations
         are immediately  bound  to the  Prolog functions.    If  FALSE,
         SWI-Prolog  will never  rebind  the GMP  allocation  functions.
         See mp_set_memory_functions() in  the GMP  documentation.    The
         action returns  FALSE if  there  is no  GMP support  or GMP  is
         already initialised.


1111..44..1177 QQuueerryyiinngg PPrroolloogg


long PPLL__qquueerryy(_i_n_t)
    Obtain  status  information  on  the  Prolog system.     The  actual
    argument  type depends on the  information required.  _i_n_t  describes
    what information is wanted.  The options are given in table ????.
    __________________________________________________________
    | PL_QUERY_ARGC          |Return  an  integer holding  the|
    |                        |number  of  arguments  given  to|
    |                        |Prolog from Unix.               |
    | PL_QUERY_ARGV          |Return  a  char **  holding  the|
    |                        |argument vector  given to Prolog|

    |                        |from Unix.                      |
    | PL_QUERY_SYMBOLFILE    |Return  a   char *  holding  the|
    |                        |current   symbol  file   of  the|
    |                        |running process.                |
    | PL_MAX_INTEGER         |Return a  long, representing the|
    |                        |maximal  integer   value  repre-|
    |                        |sented by a Prolog integer.     |

    | PL_MIN_INTEGER         |Return a  long, representing the|
    |                        |minimal integer value.          |
    | PL_QUERY_VERSION       |Return a  long, representing the|
    |                        |version  as  10;000M* +100m* +p,|
    |                        |where  M is  the  major, m  the |
    |                        |minor version  number and  p the|
    |                        |patch level.  For example, 20717|
    |                        |means 2.7.17.                   |

    | PL_QUERY_ENCODING      |Return the default stream encod-|
    |                        |ing of Prolog (of type IOENC).  |
    | PL_QUERY_USER_CPU      |Get amount  of user CPU  time of|
    |________________________|the_process_in_milliseconds.____|

                    Table 11.1:  PL_query() options


1111..44..1188 RReeggiisstteerriinngg FFoorreeiiggnn PPrreeddiiccaatteess


int PPLL__rreeggiisstteerr__ffoorreeiiggnn__iinn__mmoodduullee(_c_h_a_r _*_m_o_d_, _c_h_a_r _*_n_a_m_e_, _i_n_t _a_r_i_t_y_, _f_o_r_e_i_g_n___t _(_*_f_)_(_)_, _i_n_t _f_l_a_g_s_, _._._.)
    Register  the C function _f to  implement a Prolog predicate.   After
    this  call returns successfully a  predicate with name _n_a_m_e (a  char
    *)  and arity _a_r_i_t_y  (a C  int) is created  in module _m_o_d.   If  _m_o_d
    is  NULL, the  predicate is  created in  the module  of the  calling
    context, or if no context is present in the module user.

    When  called in Prolog,  Prolog will  call _f_u_n_c_t_i_o_n.   _f_l_a_g_s form  a
    bitwise _o_r'ed list of options for the installation.  These are:
    _______________________________________________________________
    | PL_FA_META             |Provide   meta-predicate  info   (see|
    |                        |below)                               |
    | PL_FA_TRANSPARENT      |Predicate   is   module   transparent|
    |                        |(deprecated)                         |

    | PL_FA_NONDETERMINISTIC |Predicate is non-deterministic.   See|
    |                        |also PL_retry().                     |
    | PL_FA_NOTRACE          |Predicate  cannot  be  seen  in   the|
    |                        |tracer                               |
    |_PL_FA_VARARGS__________|Use_alternative_calling_convention.__|

    If  PL_FA_META is provided,  PL_register_foreign_in_module()takes one
    extra  argument.    This argument  is  of type  const char*.    This
    string  must  be exactly  as  long as  the  number of  arguments  of
    the  predicate and  filled with  characters from  the set  0-9:^-+?.
    See  meta_predicate/1 for  details.    PL_FA_TRANSPARENT  is  implied
    if  at  least one  meta-argument is  provided (0-9:^).    Note  that
    meta-arguments  are _n_o_t  _a_l_w_a_y_s passed  as <_m_o_d_u_l_e>:<_t_e_r_m>.    Always
    use  PL_strip_module()to  extract the module  and plain term from  a
    meta-argument.

    Predicates    may   be   registered    either   before   or    after
    PL_initialise().      When  registered  before  initialisation   the
    registration  is recorded and  executed after installing the  system
    predicates and before loading the saved state.

    Default  calling (i.e. without PL_FA_VARARGS) _f_u_n_c_t_i_o_n is  passed the
    same  number of term_t arguments as the arity of the  predicate and,
    if  the predicate is  non-deterministic, an  extra argument of  type
    control_t (see section ????).   If PL_FA_VARARGS is  provided, _f_u_n_c_t_i_o_n
    is  called with  three arguments.   The first  argument is  a term_t
    handle  to the  first argument.   Further  arguments can be  reached
    by  adding the  offset (see  also PL_new_term_refs()).   The  second
    argument  is  the arity,  which  defines the  number of  valid  term
    references  in the argument vector.   The last argument is used  for
    non-deterministic  calls.  It  is currently undocumented and  should
    be defined of type void*.  Here is an example:

    ____________________________________________________________________|                                                                    |

    | static foreign_t                                                   |
    | atom_checksum(term_t a0, int arity, void* context)                 |
    | { char *s;                                                         |
    |                                                                    |
    |   if ( PL_get_atom_chars(a0, &s) )                                 |
    |   { int sum;                                                       |

    |                                                                    |
    |     for(sum=0; *s; s++)                                            |
    |       sum += *s&0xff;                                              |
    |                                                                    |
    |     return PL_unify_integer(a0+1, sum&0xff);                       |
    |   }                                                                |
    |                                                                    |
    |   return FALSE;                                                    |

    | }                                                                  |
    |                                                                    |
    | install_t                                                          |
    | install()                                                          |
    | { PL_register_foreign("atom_checksum", 2,                          |
    |                       atom_checksum, PL_FA_VARARGS);               |
    ||}_________________________________________________________________ ||


int PPLL__rreeggiisstteerr__ffoorreeiiggnn(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_, _i_n_t _a_r_i_t_y_, _f_o_r_e_i_g_n___t _(_*_f_u_n_c_t_i_o_n_)_(_)_, _i_n_t _f_l_a_g_s_, _._._.)
    Same   as  PL_register_foreign_in_module(),  passing  NULL   for  the
    _m_o_d_u_l_e.


void PPLL__rreeggiisstteerr__eexxtteennssiioonnss__iinn__mmoodduullee(_c_o_n_s_t _c_h_a_r _*_m_o_d_u_l_e_, _P_L___e_x_t_e_n_s_i_o_n _*_e)
    Register a series  of predicates from an array of definitions of the
    type  PL_extension in  the given _m_o_d_u_l_e.    If _m_o_d_u_l_e  is NULL,  the
    predicate is created in  the module of the calling context, or if no
    context  is present in  the module user.   The PL_extension type  is
    defined as

    ____________________________________________________________________|                                                                    |
    | typedef struct PL_extension                                        |
    | { char          *predicate_name; /* Name of the predicate */       |
    |   short         arity;           /* Arity of the predicate */      |

    |   pl_function_t function;        /* Implementing functions */      |
    |   short         flags;           /* Or of PL_FA_... */             |
    ||}_PL_extension;___________________________________________________ ||

    For  details,  see  PL_register_foreign_in_module().     Here  is  an
    example of its usage:

    ____________________________________________________________________|                                                                    |
    | static PL_extension predicates[] = {                               |
    | { "foo",        1,      pl_foo, 0 },                               |
    | { "bar",        2,      pl_bar, PL_FA_NONDETERMINISTIC },          |

    | { NULL,         0,      NULL,   0 }                                |
    | };                                                                 |
    |                                                                    |
    | main(int argc, char **argv)                                        |
    | { PL_register_extensions_in_module("user", predicates);            |
    |                                                                    |
    |   if ( !PL_initialise(argc, argv) )                                |

    |     PL_halt(1);                                                    |
    |                                                                    |
    |   ...                                                              |
    ||}_________________________________________________________________ ||


void PPLL__rreeggiisstteerr__eexxtteennssiioonnss( _P_L___e_x_t_e_n_s_i_o_n _*_e)
    Same as  PL_register_extensions_in_module()using  NULL for the _m_o_d_u_l_e
    argument.


1111..44..1199 FFoorreeiiggnn CCooddee HHooookkss

For various specific applications some hooks are provided.


PL_dispatch_hook_t PPLL__ddiissppaattcchh__hhooookk(_P_L___d_i_s_p_a_t_c_h___h_o_o_k___t)
    If this hook is  not NULL, this function is called when reading from
    the  terminal.   It is supposed  to dispatch events when  SWI-Prolog
    is  connected to a  window environment.   It can return two  values:
    PL_DISPATCH_INPUT  indicates  Prolog  input  is  available  on  file
    descriptor  0 or PL_DISPATCH_TIMEOUT to indicate a timeout.   The old
    hook is returned.  The type PL_dispatch_hook_t is defined as:

    ____________________________________________________________________|                                                                    |
    ||typedef_int__(*PL_dispatch_hook_t)(void);_________________________ ||


void PPLL__aabboorrtt__hhooookk(_P_L___a_b_o_r_t___h_o_o_k___t)
    Install  a hook  when abort/0 is  executed.   SWI-Prolog abort/0  is
    implemented  using C  setjmp()/longjmp() construct.   The hooks  are
    executed  in  the  reverse order  of  their registration  after  the
    longjmp()  took place and before the Prolog top level  is reinvoked.
    The type PL_abort_hook_t is defined as:

    ____________________________________________________________________|                                                                    |
    ||typedef_void_(*PL_abort_hook_t)(void);____________________________ ||


int PPLL__aabboorrtt__uunnhhooookk(_P_L___a_b_o_r_t___h_o_o_k___t)
    Remove  a hook installed with PL_abort_hook().  Returns FALSE  if no
    such hook is found, TRUE otherwise.


void PPLL__oonn__hhaalltt(_i_n_t _(_*_f_)_(_i_n_t_, _v_o_i_d _*_)_, _v_o_i_d _*_c_l_o_s_u_r_e)
    Register  the function _f to be called if SWI-Prolog is halted.   The
    function  is  called with  two  arguments:   the  exit code  of  the
    process  (0 if this cannot  be determined) and the _c_l_o_s_u_r_e  argument
    passed  to the PL_on_halt() call.   Handlers _m_u_s_t  return 0.   Other
    return  values are  reserved for future  use.   See  also at_halt/1.
    These  handlers are called _b_e_f_o_r_e  system cleanup and can  therefore
    access all normal Prolog resources.  See also PL_exit_hook().


void PPLL__eexxiitt__hhooookk(_i_n_t _(_*_f_)_(_i_n_t_, _v_o_i_d _*_)_, _v_o_i_d _*_c_l_o_s_u_r_e)
    Similar  to PL_on_halt(), but  the hooks  are executed  by PL_halt()
    instead of PL_cleanup() just before calling exit().


PL_agc_hook_t PPLL__aaggcc__hhooookk(_P_L___a_g_c___h_o_o_k___t _n_e_w)
    Register    a   hook   with   the   atom-garbage    collector   (see
    garbage_collect_atoms/0)  that  is  called  on  any  atom   that  is
    reclaimed.    The old hook  is returned.   If  no hook is  currently
    defined,  NULL is returned.  The argument of the called hook  is the
    atom  that is to be garbage collected.  The return value  is an int.
    If  the return value is zero, the  atom is nnoott reclaimed.   The hook
    may invoke any Prolog predicate.

    The  example  below  defines  a foreign  library  for  printing  the
    garbage collected atoms for debugging purposes.

    ____________________________________________________________________|                                                                    |
    | #include <SWI-Stream.h>                                            |

    | #include <SWI-Prolog.h>                                            |
    |                                                                    |
    | static int                                                         |
    | atom_hook(atom_t a)                                                |
    | { Sdprintf("AGC: deleting %s\n", PL_atom_chars(a));                |
    |                                                                    |
    |   return TRUE;                                                     |
    | }                                                                  |

    |                                                                    |
    | static PL_agc_hook_t old;                                          |
    |                                                                    |
    | install_t                                                          |
    | install()                                                          |
    | { old = PL_agc_hook(atom_hook);                                    |
    | }                                                                  |

    |                                                                    |
    | install_t                                                          |
    | uninstall()                                                        |
    | { PL_agc_hook(old);                                                |
    ||}_________________________________________________________________ ||


1111..44..2200 SSttoorriinngg ffoorreeiiggnn ddaattaa

When combining  foreign code with  Prolog, it can  be necessary to  make
data  represented in  the foreign  language available  to Prolog.    For
example, to  pass it to another  foreign function.   At the end of  this
section, there  is a partial  implementation of using foreign  functions
to manage  bit-vectors.   Another example is  the SGML/XML library  that
manages a `parser' object,  an object that represents the  current state
of  the parser  and that  can be  directed to  perform  actions such  as
parsing a document or make queries about the document content.

This section  provides some hints for  handling foreign data in  Prolog.
There are four options for storing such data:

  o _N_a_t_u_r_a_l _P_r_o_l_o_g _d_a_t_a
    Uses  the representation  one would choose  if no foreign  interface
    was  required.   For  example, a  bitvector representing  a list  of
    small integers can be represented as a Prolog list of integers.

  o _O_p_a_q_u_e _p_a_c_k_e_d _d_a_t_a _o_n _t_h_e _s_t_a_c_k_s
    It  is possible to  represent the raw  binary representation of  the
    foreign object as a  Prolog string (see section ????).  Strings may be
    created from foreign data using PL_put_string_nchars() and retrieved
    using PL_get_string_chars().  It is good practice to wrap the string
    in  a compound term with arity  1, so Prolog can identify  the type.
    The  hook portray/1 rules  may be used  to streamline printing  such
    terms during development.

  o _O_p_a_q_u_e _p_a_c_k_e_d _d_a_t_a _i_n _a _b_l_o_b
    Similar  to  the  above  solution,  binary data  can  be  stored  in
    an  atom.    The  blob interface  (section ????)  provides  additional
    facilities to assign  a type and hook-functions that act on creation
    and destruction of the underlying atom.

  o _N_a_t_u_r_a_l _f_o_r_e_i_g_n _d_a_t_a_, _p_a_s_s_e_d _a_s _a _p_o_i_n_t_e_r
    An  alternative is to pass  a pointer to the  foreign data.   Again,
    the pointer is often wrapped in a compound term.

The choice may be guided using the following distinctions

  o _I_s _t_h_e _d_a_t_a _o_p_a_q_u_e _t_o _P_r_o_l_o_g
    With  `opaque' data, we refer to data handled in  foreign functions,
    passed  around  in  Prolog,  but  where Prolog  never  examines  the
    contents  of the data itself.  If the data is opaque to  Prolog, the
    selection  will be driven solely by simplicity of the  interface and
    performance.

  o _W_h_a_t _i_s _t_h_e _l_i_f_e_t_i_m_e _o_f _t_h_e _d_a_t_a
    With  `lifetime' we refer  to how it is  decided that the object  is
    (or can be) destroyed.  We can distinguish three cases:

     1.  The object must be destroyed on backtracking  and normal Prolog
         garbage collection  (i.e., it  acts as a  normal Prolog  term).
         In  this case,  representing  the  object as  a  Prolog  string
         (second option above) is the only feasible solution.

     2.  The data  must survive Prolog  backtracking.   This leaves  two
         options.   One is to represent  the object using a pointer  and
         use explicit  creation and destruction,  making the  programmer
         responsible.   The  alternative is to  use the  blob-interface,
         leaving destruction to the (atom) garbage collector.

     3.  The  data   lives  as   during  the  lifetime   of  a   foreign
         function that  implements a  predicate.   If  the predicate  is
         deterministic, foreign  automatic variables are  suitable.   If
         the predicate is  non-deterministic, the data may be  allocated
         using malloc() and a pointer may be passed.  See section ????.


1111..44..2200..11 EExxaammpplleess ffoorr ssttoorriinngg ffoorreeiiggnn ddaattaa

In  this section,  we  outline some  examples, covering  typical  cases.
In  the  first  example,  we will  deal  with  extending  Prolog's  data
representation with integer sets, represented as bit-vectors.   Then, we
discuss the outline of the DDE interface.

IInntteeggeerr  sseettss with  not-too-far-apart upper-  and  lower-bounds  can  be
represented using  bit-vectors.  Common  set operations, such as  union,
intersection,  etc.,  are  reduced  to simple  _a_n_d'ing  and  _o_r'ing  the
bit-vectors.  This can be done using Prolog's unbounded integers.

For really demanding  applications, foreign representation will  perform
better,  especially  time-wise.    Bit-vectors are  naturally  expressed
using string  objects.   If the  string is wrapped  in bitvector/1,  the
lower-bound of the  vector is 0 and  the upper-bound is not defined;  an
implementation for  getting and putting  the sets as  well as the  union
predicate for it is below.

________________________________________________________________________|                                                                        |
|#include <SWI-Prolog.h>                                                 |

|                                                                        |
|#define max(a, b) ((a) > (b) ? (a) : (b))                               |
|#define min(a, b) ((a) < (b) ? (a) : (b))                               |
|                                                                        |
|static functor_t FUNCTOR_bitvector1;                                    |
|                                                                        |
|static int                                                              |
|get_bitvector(term_t in, int *len, unsigned char **data)                |

|{ if ( PL_is_functor(in, FUNCTOR_bitvector1) )                          |
|  { term_t a = PL_new_term_ref();                                       |
|                                                                        |
|    PL_get_arg(1, in, a);                                               |
|    return PL_get_string(a, (char **)data, len);                        |
|  }                                                                     |
|                                                                        |

|  PL_fail;                                                              |
|}                                                                       |
|                                                                        |
|static int                                                              |
|unify_bitvector(term_t out, int len, const unsigned char *data)         |
|{ if ( PL_unify_functor(out, FUNCTOR_bitvector1) )                      |
|  { term_t a = PL_new_term_ref();                                       |
|                                                                        |

|    PL_get_arg(1, out, a);                                              |
|                                                                        |
|    return PL_unify_string_nchars(a, len, (const char *)data);          |
|  }                                                                     |
|                                                                        |
|  PL_fail;                                                              |
|}                                                                       |

|                                                                        |
|static foreign_t                                                        |
|pl_bitvector_union(term_t t1, term_t t2, term_t u)                      |
|{ unsigned char *s1, *s2;                                               |
|  int l1, l2;                                                           |
|                                                                        |
|  if ( get_bitvector(t1, &l1, &s1) &&                                   |
|       get_bitvector(t2, &l2, &s2) )                                    |

|  { int l = max(l1, l2);                                                |
|    unsigned char *s3 = alloca(l);                                      |
|                                                                        |
|    if ( s3 )                                                           |
|    { int n;                                                            |
|      int ml = min(l1, l2);                                             |
|                                                                        |

|      for(n=0; n<ml; n++)                                               |
|        s3[n] = s1[n] | s2[n];                                          |
|      for( ; n < l1; n++)                                               |
|        s3[n] = s1[n];                                                  |
|      for( ; n < l2; n++)                                               |
|        s3[n] = s2[n];                                                  |
|                                                                        |
|      return unify_bitvector(u, l, s3);                                 |

|    }                                                                   |
|                                                                        |
|    return PL_warning("Not enough memory");                             |
|  }                                                                     |
|                                                                        |
|  PL_fail;                                                              |
|}                                                                       |

|                                                                        |
|                                                                        |
|install_t                                                               |
|install()                                                               |
|{ PL_register_foreign("bitvector_union", 3, pl_bitvector_union, 0);     |
|                                                                        |
|  FUNCTOR_bitvector1 = PL_new_functor(PL_new_atom("bitvector"), 1);     |
|}|_____________________________________________________________________ | |

TThhee DDDDEE  iinntteerrffaaccee (see section ????) represents  another common usage  of
the foreign interface:  providing communication to  new operating system
features.  The DDE interface requires knowledge about  active DDE server
and  client channels.    These channels  contains  various foreign  data
types.    Such an  interface is  normally achieved  using an  open/close
protocol that creates and destroys a _h_a_n_d_l_e.  The  handle is a reference
to a foreign data structure containing the relevant information.

There are a  couple of possibilities for  representing the handle.   The
choice  depends on  responsibilities  and  debugging facilities.     The
simplest  approach is  to  use PL_unify_pointer()  and PL_get_pointer().
This  approach is  fast and  easy, but  has the  drawbacks of  (untyped)
pointers:   there  is no  reliable way  to detect  the  validity of  the
pointer,  nor to  verify  that it  is  pointing to  a structure  of  the
desired type.   The  pointer may  be wrapped into  a compound term  with
arity  1 (i.e.,  dde_channel(<_P_o_i_n_t_e_r>)),  making the  type-problem  less
serious.

Alternatively  (used in  the  DDE  interface),  the interface  code  can
maintain a  (preferably variable  length) array of  pointers and  return
the index in this  array.  This provides better protection.   Especially
for debugging  purposes, wrapping  the handle  in a compound  is a  good
suggestion.


1111..44..2211 EEmmbbeeddddiinngg SSWWII--PPrroolloogg iinn ootthheerr aapppplliiccaattiioonnss

With embedded Prolog we refer to the situation where  the `main' program
is not the Prolog application.  Prolog is sometimes  embedded in C, C++,
Java or  other languages  to provide  logic based services  in a  larger
application.   Embedding  loads the Prolog  engine as  a library to  the
external language.   Prolog itself only provides for embedding in  the C
language (compatible  with C++).   Embedding in  Java is achieved  using
JPL using a C-glue between the Java and Prolog C interfaces.

The  most   simple  embedded   program  is   below.      The   interface
function  PL_initialise()  mmuusstt  be  called  before  any  of  the  other
SWI-Prolog  foreign  language  functions  described  in   this  chapter,
except  for  PL_initialise_hook(),   PL_new_atom(),  PL_new_functor()  and
PL_register_foreign().   PL_initialise() interprets all the command  line
arguments,  except  for the  -t toplevel  flag  that is  interpreted  by
PL_toplevel().

________________________________________________________________________|                                                                        |
|int                                                                     |

|main(int argc, char **argv)                                             |
|{ if ( !PL_initialise(argc, argv) )                                     |
|    PL_halt(1);                                                         |
|                                                                        |
|  PL_halt(PL_toplevel() ? 0 : 1);                                       |
|}|_____________________________________________________________________ | |


int PPLL__iinniittiiaalliissee(_i_n_t _a_r_g_c_, _c_h_a_r _*_*_a_r_g_v)
    Initialises  the SWI-Prolog  heap and  stacks,  restores the  Prolog
    state, loads the  system and personal initialisation files, runs the
    initialization/1 hooks and finally runs the -g goal hook.

    Special  consideration  is required  for argv[0].    On  UUnniixx,  this
    argument passes the part  of the command line that is used to locate
    the  executable.   Prolog  uses this to  find the  file holding  the
    running executable.   The WWiinnddoowwss version uses this to find a _m_o_d_u_l_e
    of  the  running executable.    If the  specified  module cannot  be
    found, it tries  the module libpl.dll, containing the Prolog runtime
    kernel.   In  all these cases,  the resulting file  is used for  two
    purposes:

      o  See whether a Prolog saved  state is appended to the file.   If
         this is  the case,  this state  will be loaded  instead of  the
         default boot.prc file from the SWI-Prolog home directory.   See
         also qsave_program/[1,2] and section ????.

      o  Find the Prolog home  directory.  This process is  described in
         detail in section ????.

    PL_initialise()  returns 1  if all  initialisation  succeeded and  0
    otherwise.

    In  most cases, _a_r_g_c and _a_r_g_v will be passed from the  main program.
    It  is allowed to create your own argument vector,  provided argv[0]
    is constructed according to the rules above.  For example:

    ____________________________________________________________________|                                                                    |

    | int                                                                |
    | main(int argc, char **argv)                                        |
    | { char *av[10];                                                    |
    |   int ac = 0;                                                      |
    |                                                                    |

    |   av[ac++] = argv[0];                                              |
    |   av[ac++] = "-x";                                                 |
    |   av[ac++] = "mystate";                                            |
    |   av[ac]   = NULL;                                                 |
    |                                                                    |
    |   if ( !PL_initialise(ac, av) )                                    |
    |     PL_halt(1);                                                    |
    |   ...                                                              |

    ||}_________________________________________________________________ ||

    Please  note that the  passed argument vector  may be referred  from
    Prolog  at any time  and should  therefore be valid  as long as  the
    Prolog engine is used.

    A  good setup  in Windows is  to add  SWI-Prolog's bin directory  to
    your  PATH  and either  pass  a module  holding  a saved  state,  or
    "libpl.dll"  as argv[0].  If the  Prolog state is attached to  a DLL
    (see the -dll option of swipl-ld), pass the name of this DLL.


int PPLL__iiss__iinniittiiaalliisseedd(_i_n_t _*_a_r_g_c_, _c_h_a_r _*_*_*_a_r_g_v)
    Test  whether the  Prolog engine  is already initialised.    Returns
    FALSE  if Prolog  is not  initialised and TRUE  otherwise.   If  the
    engine is initialised  and _a_r_g_c is not NULL, the argument count used
    with  PL_initialise() is  stored in  _a_r_g_c.   Same  for the  argument
    vector _a_r_g_v.


int PPLL__sseett__rreessoouurrccee__ddbb__mmeemm(_c_o_n_s_t _u_n_s_i_g_n_e_d _c_h_a_r _*_d_a_t_a_, _s_i_z_e___t _s_i_z_e)
    This  function  must  be called  at  most  once and  _b_e_f_o_r_e  calling
    PL_initialise().   The memory area designated by _d_a_t_a and  _s_i_z_e must
    contain  the  resource data  and be  in the  format  as produced  by
    qsave_program/2.  The memory  area is accessed by PL_initialise() as
    well as calls to open_resource/3.

    For  example, we  can include  the bootstrap data  into an  embedded
    executable  using the steps below.   The advantage of this  approach
    is  that it is  fully supported by  any OS and  you obtain a  single
    file executable.

     1.  Create a saved state using qsave_program/2 or

         _______________________________________________________________|                                                               |
         |%|swipl_-o_state_-c_file.pl_..._______________________________ | |

     2.  Create a  C source  file from the  state using  e.g., the  Unix
         utility xxd(1):

         _______________________________________________________________|                                                               |
         |%|xxd_-i_state_>_state.h______________________________________ | |

     3.  Embed Prolog as in the  example below.  Instead of  calling the
         toplevel you probably want to call your application code.

         _______________________________________________________________|                                                               |
         |#include <SWI-Prolog.h>                                        |
         |#include "state.h"                                             |
         |                                                               |

         |int                                                            |
         |main(int argc, char **argv)                                    |
         |{ if ( !PL_set_resource_db_mem(state, state_len) ||            |
         |       !PL_initialise(argc, argv) )                            |
         |    PL_halt(1);                                                |
         |                                                               |
         |  return PL_toplevel();                                        |
         |}|____________________________________________________________ | |

    Alternative  to xxd, it  is possible to  use inline assembler,  e.g.
    the  gcc incbin instruction.   Code for gcc was provided by  Roberto
    Bagnara  on the SWI-Prolog mailinglist.   Given the state in a  file
    state, create the following assembler program:

    ____________________________________________________________________|                                                                    |

    |         .globl _state                                              |
    |         .globl _state_end                                          |
    | _state:                                                            |
    |         .incbin "state"                                            |
    ||_state_end:_______________________________________________________ ||

    Now include this as follows:

    ____________________________________________________________________|                                                                    |

    | #include <SWI-Prolog.h>                                            |
    |                                                                    |
    | #if __linux                                                        |
    | #define STATE _state                                               |
    | #define STATE_END _state_end                                       |
    | #else                                                              |
    | #define STATE state                                                |

    | #define STATE_END state_end                                        |
    | #endif                                                             |
    |                                                                    |
    | extern unsigned char STATE[];                                      |
    | extern unsigned char STATE_END[];                                  |
    |                                                                    |
    | int                                                                |
    | main(int argc, char **argv)                                        |

    | { if ( !PL_set_resource_db_mem(STATE, STATE_END - STATE) ||        |
    |        !PL_initialise(argc, argv) )                                |
    |     PL_halt(1);                                                    |
    |   return PL_toplevel();                                            |
    ||}_________________________________________________________________ ||

    As   Jose  Morales  pointed  at   https://github.com/graphitemaster/
    incbin,  which  contains a  portability layer  on top  of the  above
    idea.


int PPLL__ttoopplleevveell()
    Runs  the  goal of  the -t toplevel  switch  (default prolog/0)  and
    returns 1 if successful, 0 otherwise.


int PPLL__cclleeaannuupp(_i_n_t _s_t_a_t_u_s)
    This function  performs the reverse of PL_initialise().   It runs the
    PL_on_halt() and at_halt/1 handlers, closes all streams  (except for
    the  `standard I/O'  streams which  are  flushed only),  deallocates
    all  memory if _s_t_a_t_u_s equals  `0' and restores all signal  handlers.
    The  _s_t_a_t_u_s argument is passed to the various termination  hooks and
    indicates the _e_x_i_t_-_s_t_a_t_u_s.

    The  function  returns  TRUE  if  successful  and  FALSE  otherwise.
    Currently,  FALSE  is  returned when  an  attempt  is made  to  call
    PL_cleanup() recursively or if one of the  exit handlers cancels the
    termination  using cancel_halt/1.    Exit handlers  may only  cancel
    termination if _s_t_a_t_u_s is 0.

    In  theory, this function allows deleting and restarting  the Prolog
    system  in the  same process.    In  practice, SWI-Prolog's  cleanup
    process is far  from complete, and trying to revive the system using
    PL_initialise()  will leak memory  in the best  case.   It can  also
    crash the appliction.

    In  this state,  there is  little practical use  for this  function.
    If  you want  to use Prolog  temporarily, consider  running it in  a
    separate  process.   If you want  to be able  to reset Prolog,  your
    options are (again) a separate process, modules or threads.


void PPLL__cclleeaannuupp__ffoorrkk()
    Stop intervaltimer that may  be running on behalf of profile/1.  The
    call is intended to be used in combination with fork():

    ____________________________________________________________________|                                                                    |
    |     if ( (pid=fork()) == 0 )                                       |
    |     { PL_cleanup_fork();                                           |
    |       <some exec variation>                                        |

    ||____}_____________________________________________________________ ||

    The  call behaves the same on  Windows, though there is probably  no
    meaningful application.


int PPLL__hhaalltt(_i_n_t _s_t_a_t_u_s)
    Clean  up the Prolog environment using PL_cleanup() and  if success-
    ful  call exit() with  the status argument.   Returns FALSE if  exit
    was cancelled by PL_cleanup().


1111..44..2211..11 TThhrreeaaddiinngg,, SSiiggnnaallss aanndd eemmbbeeddddeedd PPrroolloogg

This section  applies to  Unix-based environments that  have signals  or
multithreading.   The  Windows version is  compiled for  multithreading,
and Windows lacks proper signals.

We  can distinguish  two classes  of embedded  executables.   There  are
small C/C++  programs that act  as an  interfacing layer around  Prolog.
Most  of  these  programs  can  be  replaced  using  the  normal  Prolog
executable extended with  a dynamically loaded foreign extension and  in
most cases  this is  the preferred  route.   In other  cases, Prolog  is
embedded in a complex application that---like  Prolog---wants to control
the process  environment.   A good  example is Java.   Embedding  Prolog
is generally  the only  way to  get these environments  together in  one
process image.    Java VMs,  however,  are by  nature multithreaded  and
appear to do signal handling (software interrupts).

On  Unix  systems,  SWI-Prolog  installs   handlers  for  the  following
signals:

SSIIGGUUSSRR22  has an empty signal handler.   This signal is sent to  a thread
    after  sending a  thread-signal (see  thread_signal/2).   It  causes
    blocking  system calls to  return with EINTR,  which gives them  the
    opportunity to react to thread-signals.

    In  some  cases the  embedded  system and  SWI-Prolog may  both  use
    SIGUSR2 without conflict.   If the embedded system redefines SIGUSR2
    with  a  handler that  runs  quickly  and no  harm  is done  in  the
    embedded  system due to spurious wakeup when initiated  from Prolog,
    there  is  no problem.    If  SWI-Prolog  is initialised  _a_f_t_e_r  the
    embedded system it  will call the handler set by the embedded system
    and  the same conditions  as above apply.   SWI-Prolog's handler  is
    a  simple function  only chaining a  possibly previously  registered
    handler.  SWI-Prolog can handle spurious SIGUSR2 signals.

SSIIGGIINNTT  is used by the top level to activate the tracer (typically bound
    to control-C). The  first control-C posts a request for starting the
    tracer  in a safe, synchronous fashion.   If control-C is  hit again
    before  the safe route is executed,  it prompts the user whether  or
    not a forced interrupt is desired.

SSIIGGTTEERRMM,, SSIIGGAABBRRTT aanndd SSIIGGQQUUIITT  are caught to  cleanup before killing  the
    process again using the same signal.

SSIIGGSSEEGGVV,, SSIIGGIILLLL,, SSIIGGBBUUSS,, SSIIGGFFPPEE aanndd SSIIGGSSYYSS  are caught  by  to  print  a
    backtrace before killing the process again using the same signal.

SSIIGGHHUUPP  is caught and  causes the process  to exit  with status 2  after
    cleanup.

The --nosignals  option can  be used  to inhibit  all signal  processing
except for SIGUSR2.   The handling of SIGUSR2 is vital for  dealing with
blocking system call in  threads.  The used signal may be  changed using
the --sigalert=NUM option or disabled using --sigalert=0.


1111..55 LLiinnkkiinngg eemmbbeeddddeedd aapppplliiccaattiioonnss uussiinngg sswwiippll--lldd

The  utility program  swipl-ld (Win32:   swipl-ld.exe)  may  be used  to
link  a combination  of C  files  and Prolog  files into  a  stand-alone
executable.    swipl-ld  automates most  of  what  is described  in  the
previous sections.

In  normal usage,  a  copy is  made of  the default  embedding  template
.../swipl/include/stub.c.    The  main()  routine is  modified  to  suit
your  application.   PL_initialise()  mmuusstt be  passed the  program  name
(_a_r_g_v_[_0_])  (Win32:    the  executing  program  can   be  obtained  using
GetModuleFileName()).   The other  elements of the  command line may  be
modified.  Next, swipl-ld is typically invoked as:

________________________________________________________________________|                                                                        |
|swipl-ld|-o_output_stubfile.c_[other-c-or-o-files]_[plfiles]___________ |        |

swipl-ld will first split  the options into various groups for  both the
C compiler and the  Prolog compiler.  Next, it will add  various default
options to the  C compiler and call  it to create an executable  holding
the  user's C  code and  the Prolog  kernel.   Then,  it  will call  the
SWI-Prolog compiler  to create a  saved state  from the provided  Prolog
files  and finally,  it  will attach  this saved  state to  the  created
emulator to create the requested executable.

Below, it  is described how the options  are split and which  additional
options are passed.

-help
    Print brief synopsis.

-pl _p_r_o_l_o_g
    Select  the Prolog to use.   This Prolog  is used for two  purposes:
    get  the home directory as  well as the compiler/linker options  and
    create a saved state of the Prolog code.

-ld _l_i_n_k_e_r
    Linker  used to link the  raw executable.   Default is to use the  C
    compiler (Win32:  link.exe).

-cc _C _c_o_m_p_i_l_e_r
    Compiler  for .c files found  on the command line.   Default is  the
    compiler  used to  build  SWI-Prolog accessible  through the  Prolog
    flag c_cc (Win32:  cl.exe).

-c++ _C_+_+_-_c_o_m_p_i_l_e_r
    Compiler  for C++  source file (extensions  .cpp, .cxx,  .cc or  .C)
    found on the command  line.  Default is c++ or g++ if the C compiler
    is gcc (Win32:  cl.exe).

-nostate
    Just  relink  the  kernel,  do  not  add  any  Prolog  code  to  the
    new  kernel.     This  is  used  to  create  a  new  kernel  holding
    additional  foreign  predicates  on  machines that  do  not  support
    the  shared-library  (DLL)  interface,  or  if  building  the  state
    cannot  be  handled  by  the default  procedure  used  by  swipl-ld.
    In   the  latter   case  the   state  is   created  separately   and
    appended  to  the kernel  using  cat <_k_e_r_n_e_l> <_s_t_a_t_e> > <_o_u_t>(Win32:
    copy /b <_k_e_r_n_e_l>+<_s_t_a_t_e> <_o_u_t>).

-shared
    Link  C, C++ or object files into a shared object (DLL) that  can be
    loaded  by the  load_foreign_library/1predicate.    If used with  -c
    it  sets the proper  options to compile  a C or  C++ file ready  for
    linking into a shared object.

-dll
    _W_i_n_d_o_w_s  _o_n_l_y.     Embed  SWI-Prolog  into  a  DLL  rather  than  an
    executable.

-c
    Compile  C  or C++  source files  into  object files.    This  turns
    swipl-ld into a  replacement for the C or C++ compiler, where proper
    options  such as the  location of the  include directory are  passed
    automatically to the compiler.

-E
    Invoke the C preprocessor.   Used to make swipl-ld a replacement for
    the C or C++ compiler.

-pl-options _,_._._.
    Additional  options passed to Prolog when creating the  saved state.
    The  first character  immediately  following pl-options  is used  as
    separator  and  translated to  spaces when  the  argument is  built.
    Example:  -pl-options,-F,xpce  passes -F xpce as additional flags to
    Prolog.

-ld-options _,_._._.
    Passes options to the linker, similar to -pl-options.

-cc-options _,_._._.
    Passes options to the C/C++ compiler, similar to -pl-options.

-v
    Select  verbose operation,  showing the  various programs and  their
    options.

-o _o_u_t_f_i_l_e
    Reserved to specify the final output file.

-l_l_i_b_r_a_r_y
    Specifies  a  library for  the  C compiler.    By  default,  -lswipl
    (Win32:   libpl.lib) and the  libraries needed by the Prolog  kernel
    are given.

-L_l_i_b_r_a_r_y_-_d_i_r_e_c_t_o_r_y
    Specifies  a  library directory  for the  C compiler.    By  default
    the  directory  containing  the Prolog  C  library for  the  current
    architecture is passed.

-g | -I_i_n_c_l_u_d_e_-_d_i_r_e_c_t_o_r_y | -D_d_e_f_i_n_i_t_i_o_n
    These  options  are passed  to the  C  compiler.   By  default,  the
    include directory containing SWI-Prolog.h  is passed.  swipl-ld adds
    two additional * -Ddef flags:

    -D__SWI_PROLOG__
         Indicates the code is to be connected to SWI-Prolog.

    -D__SWI_EMBEDDED__
         Indicates the creation of an embedded program.

 _*_._o | _*_._c | _*_._C | _*_._c_x_x | _*_._c_p_p
    Passed as input files to the C compiler.

 _*_._p_l |_*_._q_l_f
    Passed  as input files  to the Prolog  compiler to create the  saved
    state.

 *
    All  other options.   These are  passed as linker  options to the  C
    compiler.


1111..55..11 AA ssiimmppllee eexxaammppllee

The  following is  a very  simple example  going through  all the  steps
outlined above.   It  provides an arithmetic expression  evaluator.   We
will call  the application calc  and define it in  the files calc.c  and
calc.pl.  The Prolog file is simple:

________________________________________________________________________|                                                                        |
|calc(Atom) :-                                                           |

|        term_to_atom(Expr, Atom),                                       |
|        A is Expr,                                                      |
|        write(A),                                                       |
||_______nl.____________________________________________________________ ||

The  C  part  of  the  application  parses  the  command  line  options,
initialises the  Prolog engine, locates  the calc/1 predicate and  calls
it.  The coder is in figure ????.

________________________________________________________________________|                                                                        |
|#include <stdio.h>                                                      |
|#include <SWI-Prolog.h>                                                 |
|                                                                        |
|#define MAXLINE 1024                                                    |

|                                                                        |
|int                                                                     |
|main(int argc, char **argv)                                             |
|{ char expression[MAXLINE];                                             |
|  char *e = expression;                                                 |
|  char *program = argv[0];                                              |
|  char *plav[2];                                                        |

|  int n;                                                                |
|                                                                        |
|  /* combine all the arguments in a single string */                    |
|                                                                        |
|  for(n=1; n<argc; n++)                                                 |
|  { if ( n != 1 )                                                       |
|      *e++ = ' ';                                                       |
|    strcpy(e, argv[n]);                                                 |

|    e += strlen(e);                                                     |
|  }                                                                     |
|                                                                        |
|  /* make the argument vector for Prolog */                             |
|                                                                        |
|  plav[0] = program;                                                    |
|  plav[1] = NULL;                                                       |

|                                                                        |
|  /* initialise Prolog */                                               |
|                                                                        |
|  if ( !PL_initialise(1, plav) )                                        |
|    PL_halt(1);                                                         |
|                                                                        |
|  /* Lookup calc/1 and make the arguments and call */                   |
|                                                                        |

|  { predicate_t pred = PL_predicate("calc", 1, "user");                 |
|    term_t h0 = PL_new_term_refs(1);                                    |
|    int rval;                                                           |
|                                                                        |
|    PL_put_atom_chars(h0, expression);                                  |
|    rval = PL_call_predicate(NULL, PL_Q_NORMAL, pred, h0);              |
|                                                                        |

|    PL_halt(rval ? 0 : 1);                                              |
|  }                                                                     |
|                                                                        |
|  return 0;                                                             |
|}|_____________________________________________________________________ | |

            Figure 11.4:  C source for the calc application

The application is now created using the following command line:

________________________________________________________________________|                                                                        |
|%|swipl-ld_-o_calc_calc.c_calc.pl______________________________________ | |

The following indicates the usage of the application:

________________________________________________________________________|                                                                        |

|% calc pi/2                                                             |
|1.5708|________________________________________________________________ |      |


1111..66 TThhee PPrroolloogg ``hhoommee'' ddiirreeccttoorryy

Executables  embedding SWI-Prolog  should  be able  to find  the  `home'
directory of the  development environment unless a self-contained  saved
state  has been  added to  the executable  (see qsave_program/[1,2]  and
section ????).

If Prolog starts up, it will try to  locate the development environment.
To do so, it will try the following steps until one succeeds:

 1. If the --home=DIR is provided, use this.

 2. If  the environment variable  SWI_HOME_DIRis  defined and points  to
    an existing directory, use this.

 3. If  the  environment variable  SWIPL  is defined  and points  to  an
    existing directory, use this.

 4. Locate  the  primary   executable  or  (Windows  only)  a  component
    (_m_o_d_u_l_e)  thereof  and check  whether the  parent  directory of  the
    directory  holding this file contains the  file swipl.  If so,  this
    file  contains the (relative) path to  the home directory.  If  this
    directory  exists, use this.   This is the normal mechanism  used by
    the binary distribution.

 5. If  the precompiled path exists, use it.  This is only  useful for a
    source installation.

If  all fails  and  there is  no state  attached  to the  executable  or
provided Windows module (see PL_initialise()), SWI-Prolog gives up.   If
a state is attached, the current working directory is used.

The file_search_path/2 alias swi is set  to point to the home  directory
located.


1111..77 EExxaammppllee ooff UUssiinngg tthhee FFoorreeiiggnn IInntteerrffaaccee

Below is an example  showing all stages of the declaration of  a foreign
predicate that transforms atoms possibly holding  uppercase letters into
an atom only  holding lowercase letters.   Figure ???? shows the C  source
file, figure ???? illustrates compiling and loading of foreign code.
________________________________________________________________________|                                                                        |
|/*  Include file depends on local installation */                       |
|#include <SWI-Prolog.h>                                                 |
|#include <stdlib.h>                                                     |

|#include <string.h>                                                     |
|#include <ctype.h>                                                      |
|                                                                        |
|foreign_t                                                               |
|pl_lowercase(term_t u, term_t l)                                        |
|{ char *copy;                                                           |
|  char *s, *q;                                                          |
|  int rval;                                                             |

|                                                                        |
|  if ( !PL_get_atom_chars(u, &s) )                                      |
|    return PL_warning("lowercase/2: instantiation fault");              |
|  copy = malloc(strlen(s)+1);                                           |
|                                                                        |
|  for( q=copy; *s; q++, s++)                                            |
|    *q = (isupper(*s) ? tolower(*s) : *s);                              |

|  *q = '\0';                                                            |
|                                                                        |
|  rval = PL_unify_atom_chars(l, copy);                                  |
|  free(copy);                                                           |
|                                                                        |
|  return rval;                                                          |
|}                                                                       |
|                                                                        |

|install_t                                                               |
|install()                                                               |
|{ PL_register_foreign("lowercase", 2, pl_lowercase, 0);                 |
|}|_____________________________________________________________________ | |

                  Figure 11.5:  Lowercase source file

________________________________________________________________________|                                                                        |
|% gcc -I/usr/local/lib/swipl-\plversion/include -fpic -c lowercase.c    |
|% gcc -shared -o lowercase.so lowercase.o                               |
|% swipl                                                                 |
|Welcome to SWI-Prolog (...)                                             |

|...                                                                     |
|                                                                        |
|1 ?- load_foreign_library(lowercase).                                   |
|true.                                                                   |
|                                                                        |
|2 ?- lowercase('Hello World!', L).                                      |
|L|=_'hello_world!'.____________________________________________________ | |

    Figure 11.6:  Compiling the C source and loading the object file


1111..88 NNootteess oonn UUssiinngg FFoorreeiiggnn CCooddee


1111..88..11 FFoorreeiiggnn ddeebbuuggggiinngg ffuunnccttiioonnss

The  functions in  this  section are  primarily intended  for  debugging
foreign extensions  or embedded Prolog.    Violating the constraints  of
the foreign  interface often leads  to crashes  in a subsequent  garbage
collection.   If this  happens, the system needs  to be recompiled  with
the cflags -DO_DEBUG. This is normally achieved by  editing src/Makefile
and  changing the  definition  of  COFLAGS to  the  value  below.    The
-gdwarf-2 -g3 provides detailed  debugging information for gcc.   If you
use another C compiler you may need other flags.

________________________________________________________________________|                                                                        |
|COFLAGS=-DO_DEBUG|-gdwarf-2_-g3________________________________________ |                 |

After  recompiling the  Prolog  kernel all  functions listed  above  are
available to  use from  the debugger (e.g.    gdb) or can  be placed  at
critical location in your code or the system code.


void PPLL__bbaacckkttrraaccee(_i_n_t _d_e_p_t_h_, _i_n_t _f_l_a_g_s)
    Dump  a Prolog  backtrace to the  user_error  stream.   _D_e_p_t_h is  the
    number  of frames to dump.   _F_l_a_g_s is a bitwise or of  the following
    constants:

    PPLL__BBTT__SSAAFFEE
         (0x1) Do  not try  to print  _g_o_a_l_s.   Instead,  just print  the
         predicate name  and  arity.   This  reduces  the likelyhood  to
         crash if PL_backtrace() is called in a damaged environment.

    PPLL__BBTT__UUSSEERR
         (0x2) Only show `user' frames.  Default is to  also show frames
         of hidden built-in predicates.


char * PPLL__bbaacckkttrraaccee__ssttrriinngg(_i_n_t _d_e_p_t_h_, _i_n_t _f_l_a_g_s)
    As  PL_backtrace(),  but returns the stack as  a string.  The  string
    uses  UTF-8  encoding.   The  returned string  must  be freed  using
    PL_free().   This  function is was  added to  get stack traces  from
    running servers where  I/O is redirected or discarded.  For example,
    using  gdb, a stack trace is  printed in the gdb console  regardless
    of Prolog I/O redirection using the following command:

    ____________________________________________________________________|                                                                    |
    ||(gdb)_printf_"%s",_PL_backtrace_string(25,0)______________________ ||

    The  source distribution provides  the script scripts/swipl-bt  that
    exploits  gdb  and PL_backtrace_string() to  print stack  traces  in
    various formats for a SWI-Prolog process, given its process id.


int PPLL__cchheecckk__ddaattaa(_t_e_r_m___t _d_a_t_a)
    Check  the consistency  of  the term  _d_a_t_a.   Returns  TRUE this  is
    actually  implemented in  the current version  and FALSE  otherwise.
    The  actual implementation  only exists  if the  system is  compiled
    with  the  cflag  -DO_DEBUG  or -DO_MAINTENANCE.  This  is  _n_o_t  the
    default.


int PPLL__cchheecckk__ssttaacckkss()
    Check  the consistency of the runtime stacks of the  calling thread.
    Returns  TRUE this  is actually implemented  in the current  version
    and  FALSE otherwise.    The  actual implementation  only exists  if
    the  system is compiled with the cflag -DO_DEBUG or -DO_MAINTENANCE.
    This is _n_o_t the default.

The  Prolog kernel  sources use  the macro  DEBUG(_T_o_p_i_c_, _C_o_d_e).    These
macros  are disabled  in  the production  version  and must  be  enabled
by  recompiling  the  system  as  described  above.     Specific  topics
can  be enabled  and disabled  using the  predicates prolog_debug/1  and
prolog_nodebug/1.     In  addition,  they  can  be  activated  from  the
commandline  using  commandline option  -d topics,  where  _t_o_p_i_c_s  is  a
comma-separated list of debug  topics to enable.  For example,  the code
below adds  many consistency checks  and prints  messages if the  Prolog
signal handler dispatches signals.

________________________________________________________________________|                                                                        |

|$|swipl_-d_chk_secure,msg_signal_______________________________________ | |


pprroolloogg__ddeebbuugg((_+_T_o_p_i_c))


pprroolloogg__nnooddeebbuugg((_+_T_o_p_i_c))
    Enable/disable a debug topic.   _T_o_p_i_c is an atom that identifies the
    desired topic.   The available topics are defined in src/pl-debug.h.
    Please  search the sources to find out what is actually  printed and
    when.  We highlight one topic here:

    cchhkk__sseeccuurree((_A))
         dd many  expensive  consistency checks  to the  system.    This
         should typically be  used when the  system crashes, notably  in
         the garbage collector.  Garbage collection crashes  are in most
         cases caused by invalid data on the Prolog stacks.   This debug
         topic may help locating how the invalid data was created.


1111..88..22 MMeemmoorryy AAllllooccaattiioonn

SWI-Prolog's heap  memory allocation is based  on the malloc(3)  library
routines.  SWI-Prolog  provides the functions below as a  wrapper around
malloc().    Allocation  errors  in these  functions  trap  SWI-Prolog's
fatal-error handler,  in which case  PL_malloc() or PL_realloc() do  not
return.

Portable applications must use PL_free() to release strings  returned by
PL_get_chars()using  the BUF_MALLOC argument.   Portable applications may
use both PL_malloc() and friends or malloc() and friends  but should not
mix these two sets of functions on the same memory.


void * PPLL__mmaalllloocc(_s_i_z_e___t _b_y_t_e_s)
    Allocate  _b_y_t_e_s  of memory.    On  failure SWI-Prolog's  fatal-error
    handler  is  called  and  PL_malloc()  does  not  return.     Memory
    allocated  using these functions must use PL_realloc() and PL_free()
    rather than realloc() and free().


void * PPLL__rreeaalllloocc(_v_o_i_d _*_m_e_m_, _s_i_z_e___t _s_i_z_e)
    Change  the size of the  allocated chunk, possibly  moving it.   The
    _m_e_m  argument  must  be  obtained  from a  previous  PL_malloc()  or
    PL_realloc() call.


void PPLL__ffrreeee(_v_o_i_d _*_m_e_m)
    Release  memory.  The _m_e_m argument must be obtained from  a previous
    PL_malloc() or PL_realloc() call.


1111..88..22..11 BBooeehhmm--GGCC ssuuppppoorrtt

    This  section is  obsolete.   Although the  Boehm-GC interfaces
    still  exist, it  turns out  that the  scalability is  not good
    enough  for SWI-Prolog.   It  is unlikely that  SWI-Prolog will
    ever switch to Boehm-GC.

To  accommodate future  use  of the  Boehm  garbage collector  for  heap
memory  allocation,  the  interface  provides  the  functions  described
below.  Foreign extensions that wish to use  the Boehm-GC facilities can
use these wrappers.   Please note that if SWI-Prolog is not  compiled to
use Boehm-GC  (default), the user  is responsible for  calling PL_free()
to reclaim memory.


void* PPLL__mmaalllloocc__aattoommiicc(_s_i_z_e___t _b_y_t_e_s)


void* PPLL__mmaalllloocc__uunnccoolllleeccttaabbllee(_s_i_z_e___t _b_y_t_e_s)


void* PPLL__mmaalllloocc__aattoommiicc__uunnccoolllleeccttaabbllee(_s_i_z_e___t _b_y_t_e_s)
    If  Boehm-GC is  not used,  these are all  the same  as PL_malloc().
    With  Boehm-GC, these map  to the corresponding Boehm-GC  functions.
    _A_t_o_m_i_c  means that the content  should not be scanned for  pointers,
    and  _u_n_c_o_l_l_e_c_t_a_b_l_e means  that the  object should  never be  garbage
    collected.


void* PPLL__mmaalllloocc__ssttuubbbboorrnn(_s_i_z_e___t _b_y_t_e_s)


void PPLL__eenndd__ssttuubbbboorrnn__cchhaannggee(_v_o_i_d _*_m_e_m_o_r_y)
    These  functions  allow  creating objects,  promising  GC  that  the
    content will not change after PL_end_stubborn_change().


1111..88..33 CCoommppaattiibbiilliittyy bbeettwweeeenn PPrroolloogg vveerrssiioonnss

Great  care  is   taken  to  ensure  binary  compatibility  of   foreign
extensions  between different  Prolog  versions.    Only the  much  less
frequently  used  stream  interface  has  been  responsible  for  binary
incompatibilities.

Source  code  that relies  on  new  features of  the  foreign  interface
can use  the macro  PLVERSION to  find the version  of SWI-Prolog.h  and
PL_query() using  the  option PL_QUERY_VERSION to  find the  version  of
the  attached Prolog  system.   Both  follow the  same numbering  schema
explained with PL_query().


1111..88..44 DDeebbuuggggiinngg aanndd pprrooffiilliinngg ffoorreeiiggnn ccooddee ((vvaallggrriinndd))

This section  is only  relevant for  Unix users  on platforms  supported
by  http://valgrind.org/valgrind.    Valgrind  is  an  excellent  binary
instrumentation platform.  Unlike many  other instrumentation platforms,
valgrind can deal with code loaded through dlopen().

The callgrind  tool can  be used  to profile foreign  code loaded  under
SWI-Prolog.    Compile  the foreign  library  adding  -g option  to  gcc
or  swipl-ld.   By  setting the  environment variable  VALGRIND to  yes,
SWI-Prolog  will _n_o_t  release  loaded  shared objects  using  dlclose().
This trick is required to get source information on  the loaded library.
Without,  valgrind  claims  that  the shared  object  has  no  debugging
information.  Here is the complete sequence using bash as login shell:

________________________________________________________________________|                                                                        |
|% VALGRIND=yes valgrind --tool=callgrind pl <args>                      |

|<prolog interaction>                                                    |
|%|kcachegrind_callgrind.out.<pid>______________________________________ | |


1111..88..55 NNaammee CCoonnfflliiccttss iinn CC mmoodduulleess

In  the  current  version  of the  system  all  public  C  functions  of
SWI-Prolog are in the symbol table.  This can lead  to name clashes with
foreign code.    Someday I  should write a  program to  strip all  these
symbols from the symbol table  (why does Unix not have that?).   For now
I can  only suggest you  give your function  another name.   You can  do
this using the C preprocessor.  If---for  example---your foreign package
uses  a function  warning(), which  happens to  exist  in SWI-Prolog  as
well, the following macro should fix the problem:

________________________________________________________________________|                                                                        |
|#define|warning_warning________________________________________________ |       |

Note  that shared  libraries do  not  have this  problem as  the  shared
library loader  will only look  for symbols in  the main executable  for
symbols that are not defined in the library itself.


1111..88..66 CCoommppaattiibbiilliittyy ooff tthhee FFoorreeiiggnn IInntteerrffaaccee

The  term  reference   mechanism  was  first  used  by  Quintus   Prolog
version 3.   SICStus Prolog version 3  is strongly based on the  Quintus
interface.  The  described SWI-Prolog interface is similar to  using the
Quintus or SICStus interfaces, defining all  foreign-predicate arguments
of  type  +term.    SWI-Prolog  explicitly uses  type  functor_t,  while
Quintus  and SICStus  use  <_n_a_m_e> and  <_a_r_i_t_y>.    As  the  names of  the
functions differ  from Prolog to  Prolog, a  simple macro layer  dealing
with the names can also deal with this detail.  For example:

________________________________________________________________________|                                                                        |
|#define QP_put_functor(t, n, a) \                                       |

||_______PL_put_functor(t,_PL_new_functor(n,_a))________________________ ||

The  PL_unify_*()  functions are  lacking from  the  Quintus and  SICStus
interface.    They can  easily be  emulated, or  the put/unify  approach
should be used to write compatible code.

The PL_open_foreign_frame()/PL_close_foreign_frame() combination is lack-
ing from both other  Prologs.  SICStus has PL_new_term_refs(_0),  followed
by PL_reset_term_refs(), that allows for discarding term references.

The  Prolog interface  for  the graphical  user interface  package  XPCE
shares about  90% of the code  using a simple  macro layer to deal  with
different naming and calling conventions of the interfaces.


CChhaapptteerr 1122..  GGEENNEERRAATTIINNGG RRUUNNTTIIMMEE AAPPPPLLIICCAATTIIOONNSS

This  chapter  describes  the  features  of  SWI-Prolog  for  delivering
applications that can run without the development version  of the system
installed.

A SWI-Prolog runtime executable is a file consisting of two  parts.  The
first part  is the  _e_m_u_l_a_t_o_r, which  is machine-dependent.   The  second
part is the _r_e_s_o_u_r_c_e  _a_r_c_h_i_v_e, which contains the compiled program  in a
machine-independent format,  startup options  and possibly  user-defined
_r_e_s_o_u_r_c_e_s; see resource/3 and open_resource/3.

These two parts can be  connected in various ways.  The most  common way
for distributed  runtime applications is to  _c_o_n_c_a_t_e_n_a_t_e the two  parts.
This  can be  achieved using  external commands  (Unix:   cat,  Windows:
copy), or using  the stand_alone option to qsave_program/2.  The  second
option is  to attach  a startup  script in  front of  the resource  that
starts the emulator with the proper options.  This  is the default under
Unix.   Finally,  an emulator can  be told to  use a specified  resource
file using the -x command line switch.


qqssaavvee__pprrooggrraamm((_+_F_i_l_e_, _+_O_p_t_i_o_n_s))
    Saves  the current  state of  the program  to the  file _F_i_l_e.    The
    result  is  a   resource  archive  containing  a  saved  state  that
    expresses  all  Prolog   data  from  the  running  program  and  all
    user-defined  resources.   Depending on the stand_alone option,  the
    resource is headed  by the emulator, a Unix shell script or nothing.
    _O_p_t_i_o_n_s is a list of additional options:

    llooccaall((_+_K_B_y_t_e_s))
         Limit for the local stack.  See section ????.

    gglloobbaall((_+_K_B_y_t_e_s))
         Limit for the global stack.  See section ????.

    ttrraaiill((_+_K_B_y_t_e_s))
         Limit for the trail stack.  See section ????.

    ggooaall((_:_C_a_l_l_a_b_l_e))
         Initialization goal for the new executable (see -g).

    ttoopplleevveell((_:_C_a_l_l_a_b_l_e))
         Top-level goal for the new executable (see -t).

    iinniitt__ffiillee((_+_A_t_o_m))
         Default initialization file for the new executable.  See -f.

    ccllaassss((_+_C_l_a_s_s))
         If  runtime, only  read  resources  from the  state  (default).
         If  kernel, lock  all  predicates as  system  predicates.    If
         development, save  the predicates  in their  current state  and
         keep reading  resources from their  source (if  present).   See
         also resource/3.

    aauuttoollooaadd((_+_B_o_o_l_e_a_n))
         If true (default), run autoload/0 first.

    mmaapp((_+_F_i_l_e))
         Dump a human-readable trace of what has been saved in _F_i_l_e.

    oopp((_+_A_c_t_i_o_n))
         One of  save (default) to  save the  current operator table  or
         standard to use the initial table of the emulator.

    ssttaanndd__aalloonnee((_+_B_o_o_l_e_a_n))
         If true,  the emulator  is the  first part of  the state.    If
         the  emulator is  started  it will  test  whether a  boot  file
         (state)  is attached  to  the  emulator itself  and  load  this
         state.   Provided  the  application has  all libraries  loaded,
         the  resulting  executable is  completely  independent  of  the
         runtime environment or location  where it was built.   See also
         section ????.

    eemmuullaattoorr((_+_F_i_l_e))
         File to use  for the emulator.   Default is the running  Prolog
         image.

    ffoorreeiiggnn((_+_A_c_t_i_o_n))
         If save,  include shared objects (DLLs)  into the saved  state.
         See  current_foreign_library/2.     If   the  program  strip  is
         available, this is first used to reduce the size  of the shared
         object.   If  a state  is started,  use_foreign_library/1 first
         tries to locate the  foreign resource in the executable.   When
         found it  copies the  content of  the resource  to a  temporary
         file and loads  it.  If  possible (Unix), the temporary  object
         is deleted immediately after opening.


qqssaavvee__pprrooggrraamm((_+_F_i_l_e))
    Equivalent to qsave_program(File, []).


aauuttoollooaadd
    Check  the current Prolog program  for predicates that are  referred
    to,  are  undefined and  have a  definition in  the Prolog  library.
    Load the appropriate libraries.

    This  predicate is used  by qsave_program/[1,2] to ensure the  saved
    state  does  not depend  on  availability of  the  libraries.    The
    predicate  autoload/0 examines  all  clauses of  the loaded  program
    (obtained  with  clause/2)  and  analyzes the  body  for  referenced
    goals.  Such  an analysis cannot be complete in Prolog, which allows
    for  the creation of arbitrary terms at runtime and the use  of them
    as a goal.  The current analysis is limited to the following:

      o  Direct goals appearing in the body

      o  Arguments of declared  meta-predicates that are marked with  an
         integer (0..9).  See meta_predicate/1.

    The  analysis of meta-predicate arguments is limited to  cases where
    the  argument appears literally in  the clause or is assigned  using
    =/2  before  the meta-call.    That is,  the  following fragment  is
    processed correctly:

    ____________________________________________________________________|                                                                    |

    |         ...,                                                       |
    |         Goal = prove(Theory),                                      |
    |         forall(current_theory(Theory),                             |
    ||_______________Goal)),____________________________________________ ||

    But,  the calls to prove_simple/1 and prove_complex/1 in the example
    below  are _n_o_t discovered by the analysis and therefore  the modules
    that  define  these  predicates  must  be  loaded  explicitly  using
    use_module/1,2.

    ____________________________________________________________________|                                                                    |

    |         ...,                                                       |
    |         member(Goal, [ prove_simple(Theory),                       |
    |                        prove_complex(Theory)                       |
    |                      ]),                                           |
    |         forall(current_theory(Theory),                             |
    ||_______________Goal)),____________________________________________ ||

    It  is good practice  to use gxref/0 to  make sure that the  program
    has  sufficient  declarations  such  that the  analaysis  tools  can
    verify  that all required  predicates can be  resolved and that  all
    code  is  called.   See  meta_predicate/1, dynamic/1,  public/1  and
    prolog:called_by/2.


vvoollaattiillee _+_N_a_m_e_/_A_r_i_t_y_, _._._.
    Declare  that  the clauses  of specified  predicates  should nnoott  be
    saved to the program.   The volatile declaration is normally used to
    prevent  the clauses of dynamic  predicates that represent data  for
    the current session from being saved in the state file.


1122..11 LLiimmiittaattiioonnss ooff qqssaavvee__pprrooggrraamm

There  are  three  areas  that  require  special  attention  when  using
qsave_program/[1,2].

  o If  the  program  is an  embedded  Prolog  application or  uses  the
    foreign  language interface,  care has  to be taken  to restore  the
    appropriate foreign context.  See section ???? for details.

  o If  the program uses directives (:- goal. lines) that  perform other
    actions than  setting predicate attributes (dynamic, volatile, etc.)
    or  loading files  (consult,  etc.), the  directive may  need to  be
    prefixed with initialization/1.

  o Database  references as returned by clause/3, recorded/3,  etc., are
    not preserved and may thus not be part of the database when saved.


1122..22 RRuunnttiimmeess aanndd FFoorreeiiggnn CCooddee

Some  applications may  need  to  use the  foreign  language  interface.
Object code is  by definition machine-dependent and thus cannot  be part
of the saved program file.

To complicate the matter even further there are various  ways of loading
foreign code:

  o _U_s_i_n_g _t_h_e _l_i_b_r_a_r_y_(_s_h_l_i_b_) _p_r_e_d_i_c_a_t_e_s
    This  is the preferred way of dealing  with foreign code.   It loads
    quickly and ensures  an acceptable level of independence between the
    versions  of the emulator and the foreign code loaded.  It  works on
    Unix  machines supporting shared libraries and library  functions to
    load  them.  Most modern  Unixes, as well as Win32  (Windows 95/NT),
    satisfy this constraint.

  o _S_t_a_t_i_c _l_i_n_k_i_n_g
    This  mechanism works on  all machines,  but generally requires  the
    same  C compiler and linker to be  used for the external code  as is
    used to build SWI-Prolog itself.

To make  a runtime  executable that  can run on  multiple platforms  one
must make runtime  checks to find the correct  way of linking.   Suppose
we have a  source file myextension.c defining the installation  function
install().

If this file  is compiled into a  shared library, load_foreign_library/1
will load this library and call the installation  function to initialise
the  foreign code.    If it  is  loaded as  a static  extension,  define
install() as the predicate install/0:

________________________________________________________________________|                                                                        |

|static foreign_t                                                        |
|pl_install()                                                            |
|{ install();                                                            |
|                                                                        |
|  PL_succeed;                                                           |

|}                                                                       |
|                                                                        |
|PL_extension PL_extensions [] =                                         |
|{                                                                       |
|/*{ "name",     arity,  function,       PL_FA_<flags> },*/              |
|                                                                        |
|  { "install",  0,      pl_install,     0 },                            |
|  { NULL,       0,      NULL,           0 } /* terminating line */      |

|};|____________________________________________________________________ |  |

Now, use the following Prolog code to load the foreign library:

________________________________________________________________________|                                                                        |
|load_foreign_extensions :-                                              |
|        current_predicate(install, install), !, % static loaded         |
|        install.                                                        |
|load_foreign_extensions :-                      % shared library        |

|        load_foreign_library(foreign(myextension)).                     |
|                                                                        |
|:-|initialization_load_foreign_extensions._____________________________ |  |

The path  alias foreign  is defined by  file_search_path/2.   By  default
it  searches  the  directories <_h_o_m_e>/lib/<_a_r_c_h> and  <_h_o_m_e>/lib.     The
application can specify additional rules for file_search_path/2.


1122..33 UUssiinngg pprrooggrraamm rreessoouurrcceess

A _r_e_s_o_u_r_c_e  is very  similar to  a file.    Resources,  however, can  be
represented in two different formats:  on files, as well  as part of the
resource _a_r_c_h_i_v_e of a saved state (see qsave_program/2).

A resource has a _n_a_m_e  and a _c_l_a_s_s.  The _s_o_u_r_c_e data of the  resource is
a file.   Resources are declared by declaring the  predicate resource/3.
They are accessed using the predicate open_resource/3.

Before  going into  details,  let  us start  with  an  example.    Short
texts can  easily be  expressed in Prolog  source code,  but long  texts
are cumbersome.   Assume our application  defines a command `help'  that
prints a  helptext to the screen.   We put  the content of the  helptext
into a  file called help.txt.   The following  code implements our  help
command such that help.txt is incorporated into the runtime executable.

________________________________________________________________________|                                                                        |
|resource(help, text, 'help.txt').                                       |

|                                                                        |
|help :-                                                                 |
|        open_resource(help, text, In),                                  |
|        call_cleanup(copy_stream_data(In, user_output),                 |
||____________________close(In))._______________________________________ ||

The predicate  help/0 opens  the resource  as a Prolog  stream.   If  we
are executing this from the development environment,  this will actually
return a  stream to the file  help.txt itself.   When executed from  the
saved state, the stream will actually be a stream  opened on the program
resource file, taking care of the offset and length of the resource.


1122..33..11 RReessoouurrccee mmaanniippuullaattiioonn pprreeddiiccaatteess


rreessoouurrccee((_+_N_a_m_e_, _+_C_l_a_s_s_, _+_F_i_l_e_S_p_e_c))
    This  predicate is  defined  as a  dynamic predicate  in the  module
    user.    Clauses for  it may  be  defined in  any module,  including
    the  user module.    _N_a_m_e is  the name  of the  resource (an  atom).
    A  resource name  may contain  any character,  except for  $ and  :,
    which  are  reserved for  internal usage  by  the resource  library.
    _C_l_a_s_s  describes the  kind of  object stored in  the resource.    In
    the  current  implementation,  it is  just an  atom.    _F_i_l_e_S_p_e_c  is
    a  file  specification  that  may  exploit  file_search_path/2  (see
    absolute_file_name/2).

    Normally,  resources are  defined as unit  clauses (facts), but  the
    definition  of this  predicate also allows  for rules.   For  proper
    generation  of the  saved state,  it must be  possible to  enumerate
    the  available  resources by  calling this  predicate  with all  its
    arguments unbound.

    Dynamic  rules are useful to turn  all files in a certain  directory
    into  resources, without specifying a resource  for each file.   For
    example,  assume the file_search_path/2icons refers to  the resource
    directory  containing icon  files.   The following definition  makes
    all these images available as resources:

    ____________________________________________________________________|                                                                    |
    | resource(Name, image, icons(XpmName)) :-                           |

    |         atom(Name), !,                                             |
    |         file_name_extension(Name, xpm, XpmName).                   |
    | resource(Name, image, XpmFile) :-                                  |
    |         var(Name),                                                 |
    |         absolute_file_name(icons(.), [type(directory)], Dir)       |
    |         concat(Dir, '/*.xpm', Pattern),                            |
    |         expand_file_name(Pattern, XpmFiles),                       |
    ||________member(XpmFile,_XpmFiles).________________________________ ||


ooppeenn__rreessoouurrccee((_+_N_a_m_e_, _?_C_l_a_s_s_, _-_S_t_r_e_a_m))
    Opens the resource specified  by _N_a_m_e and _C_l_a_s_s.  If the latter is a
    variable,  it will  be unified to  the class  of the first  resource
    found that has the  specified _N_a_m_e.  If successful, _S_t_r_e_a_m becomes a
    handle to a  binary input stream, providing access to the content of
    the resource.

    The  predicate  open_resource/3  first  checks  resource/3.     When
    successful   it  will  open  the  returned  resource   source  file.
    Otherwise  it will look  in the program's  resource database.   When
    creating  a  saved state,  the system  normally  saves the  resource
    contents  into the resource archive, but does not save  the resource
    clauses.

    This   way,  the  development   environment  uses  the  files   (and
    modifications)   to   the  resource/3   declarations  and/or   files
    containing  resource info,  thus immediately  affecting the  running
    environment,  while the runtime  system quickly accesses the  system
    resources.


1122..33..22 TThhee swipl-rc pprrooggrraamm

The utility program swipl-rc  can be used to examine and  manipulate the
contents of  a SWI-Prolog resource  file.  The  options are inspired  by
the Unix ar program.  The basic command is:

________________________________________________________________________|                                                                        |
|%|swipl-rc_option_resource-file_member_..._____________________________ | |

The options are described below.

l
    List contents of the archive.

x
    Extract  named (or  all)  members of  the archive  into the  current
    directory.

a
    Add  files  to the  archive.    If the  archive already  contains  a
    member  with the  same name, the  contents are  replaced.   Anywhere
    in   the  sequence  of  members,   the  options  --class=_c_l_a_s_s   and
    --encoding=_e_n_c_o_d_i_n_g may appear.   They affect the class and encoding
    of subsequent files.  The initial class is data and encoding none.

d
    Delete named members from the archive.

This command is also described in the pl(1) Unix manual page.


1122..44 FFiinnddiinngg AApppplliiccaattiioonn ffiilleess

If your application  uses files that are  not part of the saved  program
such as database  files, configuration files, etc., the  runtime version
has to be able to  locate these files.  The file_search_path/2 mechanism
in combination with  the -palias command line argument is  the preferred
way to  locate runtime  files.   The first  step is to  define an  alias
for the  top-level directory  of your application.    We will call  this
directory gnatdir in our examples.

A  good  place  for storing  data  associated  with  SWI-Prolog  runtime
systems is  below the emulator's  home directory.   swi is a  predefined
alias for this directory.  The following is  a useful default definition
for the search path.

________________________________________________________________________|                                                                        |
|user:file_search_path(gnatdir,|swi(gnat))._____________________________ |                              |

The  application  should  locate   all  files  using  absolute_file_name.
Suppose  gnatdir  contains   a  file  config.pl  to  define  the   local
configuration.  Then use the code below to load this file:

________________________________________________________________________|                                                                        |

|configure_gnat :-                                                       |
|   (   absolute_file_name(gnatdir('config.pl'), ConfigFile)             |
|   ->  consult(ConfigFile)                                              |
|   ;   format(user_error, 'gnat: Cannot locate config.pl~n'),           |
|       halt(1)                                                          |
||__).__________________________________________________________________ ||


1122..44..11 SSppeecciiffyyiinngg aa ffiillee sseeaarrcchh ppaatthh ffrroomm tthhee ccoommmmaanndd lliinnee

Suppose   the  system   administrator  has   installed  the   SWI-Prolog
runtime  environment  in  /usr/local/lib/rt-pl-3.2.0.     A  user  wants
to  install  gnat,   but  gnat  will  look  for  its   configuration  in
/usr/local/lib/rt-pl-3.2.0/gnat where the user cannot write.

The user  decides to install the  gnat runtime files in  /users/bob/lib/
gnat.  For one-time  usage, the user may decide to start gnat  using the
command:

________________________________________________________________________|                                                                        |
|%|gnat_-p_gnatdir=/users/bob/lib/gnat__________________________________ | |


CChhaapptteerr 1133..  TTHHEE SSWWII--PPRROOLLOOGG LLIIBBRRAARRYY

This chapter documents  the SWI-Prolog library.  As  SWI-Prolog provides
auto-loading,  there is  little  difference between  library  predicates
and built-in predicates.   Part of  the library is therefore  documented
in the  rest of  the manual.   Library  predicates differ from  built-in
predicates in the following ways:

  o User  definition of a  built-in leads to  a permission error,  while
    using the name of a library predicate is allowed.

  o If  autoloading is disabled  explicitly or because trapping  unknown
    predicates  is disabled  (see unknown/2  and current_prolog_flag/2),
    library predicates must be loaded explicitly.

  o Using  libraries reduces  the footprint of  applications that  don't
    need them.

    _T_h_e  _d_o_c_u_m_e_n_t_a_t_i_o_n _o_f _t_h_e  _l_i_b_r_a_r_y _h_a_s _j_u_s_t _s_t_a_r_t_e_d_.   _M_a_t_e_r_i_a_l
    _f_r_o_m  _t_h_e _s_t_a_n_d_a_r_d _p_a_c_k_a_g_e_s _s_h_o_u_l_d _b_e _m_o_v_e_d _h_e_r_e_, _s_o_m_e _m_a_t_e_r_i_a_l
    _f_r_o_m  _o_t_h_e_r _p_a_r_t_s _o_f _t_h_e _m_a_n_u_a_l _s_h_o_u_l_d _b_e _m_o_v_e_d _t_o_o _a_n_d _v_a_r_i_o_u_s
    _l_i_b_r_a_r_i_e_s _a_r_e _n_o_t _d_o_c_u_m_e_n_t_e_d _a_t _a_l_l_.


1133..11 lliibbrraarryy((aaggggrreeggaattee))::     AAggggrreeggaattiioonn   ooppeerraattoorrss  oonn   bbaacckkttrraacckkaabbllee
     pprreeddiiccaatteess

    CCoommppaattiibbiilliittyy  Quintus,   SICStus  4.      The  forall/2  is  a
         SWI-Prolog built-in  and term_variables/3 is  a SWI-Prolog
         built-in with ddiiffffeerreenntt sseemmaannttiiccss.

    TToo bbee ddoonnee
         -  Analysing  the  aggregation  template and  compiling  a
         predicate for the list aggregation  can be done at compile
         time.
         -  aggregate_all/3 can  be rewritten  to  run  in constant
         space using non-backtrackable assignment on a term.

This  library provides  aggregating operators  over the  solutions of  a
predicate.  The operations are a generalisation of  the bagof/3, setof/3
and findall/3 built-in  predicates.  The defined aggregation  operations
are counting,  computing the sum, minimum,  maximum, a bag of  solutions
and a set of solutions.   We first give a simple example,  computing the
country with the smallest area:

________________________________________________________________________|                                                                        |

|smallest_country(Name, Area) :-                                         |
||_______aggregate(min(A,_N),_country(N,_A),_min(Area,_Name)).__________ ||

There  are  four   aggregation  predicates  (aggregate/3,   aggregate/4,
aggregate_all/3 and aggregate/4), distinguished on two properties.

aaggggrreeggaattee vvss..  aaggggrreeggaattee__aallll The   aggregate  predicates   use   setof/3
    (aggregate/4)  or bagof/3  (aggregate/3),  dealing with  existential
    qualified  variables  (Var^Goal)  and providing  multiple  solutions
    for  the  remaining free  variables in  Goal.   The  aggregate_all/3
    predicate  uses findall/3, implicitly qualifying all  free variables
    and  providing  exactly  one solution,  while  aggregate_all/4  uses
    sort/2  over  solutions  that Discriminator  (see  below)  generated
    using findall/3.

TThhee DDiissccrriimmiinnaattoorr aarrgguummeenntt  The versions  with 4  arguments  deduplicate
    redundant solutions of  Goal.  Solutions for which both the template
    variables  and Discriminator  are identical will  be treated as  one
    solution.   For example, if we wish to compute the  total population
    of  all countries,  and for  some reason  country(belgium, 11000000)
    may  succeed twice, we can use  the following to avoid counting  the
    population of Belgium twice:

    ____________________________________________________________________|                                                                    |
    ||____aggregate(sum(P),_Name,_country(Name,_P),_Total)______________ ||

All  aggregation predicates  support the  following  operators below  in
Template.    In addition,  they allow  for an  arbitrary named  compound
term,  where each  of  the arguments  is  a term  from the  list  below.
For example,  the term r(min(X), max(X))  computes both the minimum  and
maximum binding for X.

ccoouunntt
    Count number of solutions.  Same as sum(1).

ssuumm((_E_x_p_r))
    Sum of _E_x_p_r for all solutions.

mmiinn((_E_x_p_r))
    Minimum of _E_x_p_r for all solutions.

mmiinn((_E_x_p_r_, _W_i_t_n_e_s_s))
    A  term min(Min, Witness), where Min is the minimal version  of _E_x_p_r
    over  all solutions, and  _W_i_t_n_e_s_s is any  other template applied  to
    solutions  that produced  Min.   If multiple  solutions provide  the
    same minimum, _W_i_t_n_e_s_s corresponds to the first solution.

mmaaxx((_E_x_p_r))
    Maximum of _E_x_p_r for all solutions.

mmaaxx((_E_x_p_r_, _W_i_t_n_e_s_s))
    As min(Expr, Witness), but producing the maximum result.

sseett((_X))
    An ordered set with all solutions for _X.

bbaagg((_X))
    A list of all solutions for _X.

AAcckknnoowwlleeddggeemmeennttss

_T_h_e  _d_e_v_e_l_o_p_m_e_n_t   _o_f  _t_h_i_s  _l_i_b_r_a_r_y   _w_a_s  _s_p_o_n_s_o_r_e_d  _b_y   _S_e_c_u_r_i_t_E_a_s_e_,
http://www.securitease.com


aaggggrreeggaattee((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_R_e_s_u_l_t))                           _[_n_o_n_d_e_t_]
    Aggregate  bindings in _G_o_a_l according to _T_e_m_p_l_a_t_e.   The aggregate/3
    version performs bagof/3 on _G_o_a_l.


aaggggrreeggaattee((_+_T_e_m_p_l_a_t_e_, _+_D_i_s_c_r_i_m_i_n_a_t_o_r_, _:_G_o_a_l_, _-_R_e_s_u_l_t))           _[_n_o_n_d_e_t_]
    Aggregate  bindings in _G_o_a_l according to _T_e_m_p_l_a_t_e.   The aggregate/4
    version performs setof/3 on _G_o_a_l.


aaggggrreeggaattee__aallll((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_R_e_s_u_l_t))                       _[_s_e_m_i_d_e_t_]
    Aggregate   bindings  in   _G_o_a_l  according   to  _T_e_m_p_l_a_t_e.       The
    aggregate_all/3 version performs findall/3 on _G_o_a_l.   Note that this
    predicate fails if  _T_e_m_p_l_a_t_e contains one or more of min(X), max(X),
    min(X,Witness)  or max(X,Witness) and  _G_o_a_l has no solutions,  i.e.,
    the minumum and maximum of an empty set is undefined.


aaggggrreeggaattee__aallll((_+_T_e_m_p_l_a_t_e_, _+_D_i_s_c_r_i_m_i_n_a_t_o_r_, _:_G_o_a_l_, _-_R_e_s_u_l_t))       _[_s_e_m_i_d_e_t_]
    Aggregate   bindings  in   _G_o_a_l  according   to  _T_e_m_p_l_a_t_e.       The
    aggregate_all/4  version performs  findall/3 followed  by sort/2  on
    _G_o_a_l.    See aggregate_all/3 to  understand why  this predicate  can
    fail.


ffoorreeaacchh((_:_G_e_n_e_r_a_t_o_r_, _:_G_o_a_l))
    True  if conjunction  of results is  true.   Unlike forall/2,  which
    runs  a failure-driven loop  that proves _G_o_a_l  for each solution  of
    _G_e_n_e_r_a_t_o_r,  foreach/2 creates  a conjunction.   Each  member of  the
    conjunction  is  a  copy of  _G_o_a_l,  where  the variables  it  shares
    with  _G_e_n_e_r_a_t_o_r are  filled with the  values from the  corresponding
    solution.

    The  implementation executes forall/2 if  _G_o_a_l does not contain  any
    variables that are not shared with _G_e_n_e_r_a_t_o_r.

    Here is an example:

    ____________________________________________________________________|                                                                    |
    | ?- foreach(between(1,4,X), dif(X,Y)), Y = 5.                       |

    | Y = 5.                                                             |
    | ?- foreach(between(1,4,X), dif(X,Y)), Y = 3.                       |
    ||false.____________________________________________________________ ||

         bbuugg _G_o_a_l  is copied  repeatedly, which may  cause problems
             if attributed variables are involved.


ffrreeee__vvaarriiaabblleess((_:_G_e_n_e_r_a_t_o_r_, _+_T_e_m_p_l_a_t_e_, _+_V_a_r_L_i_s_t_0_, _-_V_a_r_L_i_s_t))         _[_d_e_t_]
    Find  free variables in  bagof/setof template.   In order to  handle
    variables  properly, we have to find all the  universally quantified
    variables  in  the _G_e_n_e_r_a_t_o_r.    All variables  as  yet unbound  are
    universally quantified, unless

     1.  they occur in the template

     2.  they are bound by X^P, setof/3, or bagof/3

    free_variables(Generator, Template, OldList, NewList)   finds   this
    set using OldList as an accumulator.

         aauutthhoorr
             - Richard O'Keefe
             - Jan Wielemaker (made some SWI-Prolog enhancements)

         lliicceennssee Public domain (from DEC10 library).

         TToo bbee ddoonnee
             -  Distinguish  between  control-structures  and  data
             terms.
             -   Exploit  our  built-in  term_variables/2  at  some
             places?


ssaannddbbooxx::ssaaffee__mmeettaa((_+_G_o_a_l_, _-_C_a_l_l_e_d))                    _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Declare  the aggregate meta-calls safe.   This cannot be proven  due
    to the manipulations of the argument _G_o_a_l.


1133..22 lliibbrraarryy((aappppllyy))::  AAppppllyy pprreeddiiccaatteess oonn aa lliisstt

    SSeeee aallssoo
         - apply_macros.pl provides compile-time expansion for part
         of this library.
         - http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm

    TToo bbee ddoonnee  Add include/4, include/5, exclude/4, exclude/5

This  module defines  meta-predicates  that  apply a  predicate  on  all
members of a list.


iinncclluuddee((_:_G_o_a_l_, _+_L_i_s_t_1_, _?_L_i_s_t_2))                                    _[_d_e_t_]
    Filter  elements for which  _G_o_a_l succeeds.   True if _L_i_s_t_2  contains
    those elements Xi of _L_i_s_t_1 for which call(Goal, Xi) succeeds.

         SSeeee aallssoo Older  versions of SWI-Prolog  had sublist/3 with
             the same arguments and semantics.


eexxcclluuddee((_:_G_o_a_l_, _+_L_i_s_t_1_, _?_L_i_s_t_2))                                    _[_d_e_t_]
    Filter elements for which  _G_o_a_l fails.  True if _L_i_s_t_2 contains those
    elements Xi of _L_i_s_t_1 for which call(Goal, Xi) fails.


ppaarrttiittiioonn((_:_P_r_e_d_, _+_L_i_s_t_, _?_I_n_c_l_u_d_e_d_, _?_E_x_c_l_u_d_e_d))                     _[_d_e_t_]
    Filter  elements  of _L_i_s_t  according  to _P_r_e_d.    True  if  _I_n_c_l_u_d_e_d
    contains all elements  for which call(Pred, X) succeeds and _E_x_c_l_u_d_e_d
    contains the remaining elements.


ppaarrttiittiioonn((_:_P_r_e_d_, _+_L_i_s_t_, _?_L_e_s_s_, _?_E_q_u_a_l_, _?_G_r_e_a_t_e_r))              _[_s_e_m_i_d_e_t_]
    Filter  _L_i_s_t according to _P_r_e_d in three  sets.  For each  element Xi
    of  _L_i_s_t, its  destination is  determined by  call(Pred, Xi, Place),
    where  Place must be  unified to one  of <, =  or >.   _P_r_e_d must  be
    deterministic.


mmaapplliisstt((_:_G_o_a_l_, _?_L_i_s_t))
    True  if _G_o_a_l can successfully be  applied on all elements of  _L_i_s_t.
    Arguments  are reordered to gain performance as well as to  make the
    predicate deterministic under normal circumstances.


mmaapplliisstt((_:_G_o_a_l_, _?_L_i_s_t_1_, _?_L_i_s_t_2))
    As maplist/2, operating on pairs of elements from two lists.


mmaapplliisstt((_:_G_o_a_l_, _?_L_i_s_t_1_, _?_L_i_s_t_2_, _?_L_i_s_t_3))
    As maplist/2, operating on triples of elements from three lists.


mmaapplliisstt((_:_G_o_a_l_, _?_L_i_s_t_1_, _?_L_i_s_t_2_, _?_L_i_s_t_3_, _?_L_i_s_t_4))
    As maplist/2, operating on quadruples of elements from four lists.


ccoonnvvlliisstt((_:_G_o_a_l_, _+_L_i_s_t_I_n_, _-_L_i_s_t_O_u_t))                                _[_d_e_t_]
    Similar  to maplist/3, but elements for  which call(Goal, ElemIn, _)
    fails are omitted from _L_i_s_t_O_u_t.  For example (using library(yall)):

    ____________________________________________________________________|                                                                    |
    | ?- convlist([X,Y]>>(integer(X), Y is X^2),                         |

    |             [3, 5, 4.4, 2], L).                                    |
    ||L_=_[9,_25,_4].___________________________________________________ ||

         CCoommppaattiibbiilliittyy Also  appears  in  YAP library(maplist)  and
             SICStus library(lists).


ffoollddll((_:_G_o_a_l_, _+_L_i_s_t_, _+_V_0_, _-_V))


ffoollddll((_:_G_o_a_l_, _+_L_i_s_t_1_, _+_L_i_s_t_2_, _+_V_0_, _-_V))


ffoollddll((_:_G_o_a_l_, _+_L_i_s_t_1_, _+_L_i_s_t_2_, _+_L_i_s_t_3_, _+_V_0_, _-_V))


ffoollddll((_:_G_o_a_l_, _+_L_i_s_t_1_, _+_L_i_s_t_2_, _+_L_i_s_t_3_, _+_L_i_s_t_4_, _+_V_0_, _-_V))
    Fold  a list, using  arguments of the  list as left  argument.   The
    foldl family of predicates is defined by:

    ____________________________________________________________________|                                                                    |
    | foldl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0, Vn) :-             |

    |       P(X11, ..., Xm1, V0, V1),                                    |
    |       ...                                                          |
    ||______P(X1n,_...,_Xmn,_V',_Vn).___________________________________ ||


ssccaannll((_:_G_o_a_l_, _+_L_i_s_t_, _+_V_0_, _-_V_a_l_u_e_s))


ssccaannll((_:_G_o_a_l_, _+_L_i_s_t_1_, _+_L_i_s_t_2_, _+_V_0_, _-_V_a_l_u_e_s))


ssccaannll((_:_G_o_a_l_, _+_L_i_s_t_1_, _+_L_i_s_t_2_, _+_L_i_s_t_3_, _+_V_0_, _-_V_a_l_u_e_s))


ssccaannll((_:_G_o_a_l_, _+_L_i_s_t_1_, _+_L_i_s_t_2_, _+_L_i_s_t_3_, _+_L_i_s_t_4_, _+_V_0_, _-_V_a_l_u_e_s))
    Left  scan  of  list.     The scanl  family  of  higher  order  list
    operations is defined by:

    ____________________________________________________________________|                                                                    |
    | scanl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0,                    |

    |       [V0,V1,...,Vn]) :-                                           |
    |       P(X11, ..., Xm1, V0, V1),                                    |
    |       ...                                                          |
    ||______P(X1n,_...,_Xmn,_V',_Vn).___________________________________ ||


        1133..33 lliibbrraarryy((aassssoocc))::  AAssssoocciiaattiioonn lliissttss

Authors: _R_i_c_h_a_r_d _A_. _O_'_K_e_e_f_e_, _L_._D_a_m_a_s_, _V_._S_._C_o_s_t_a _a_n_d _h_t_t_p_s_:_/_/_w_w_w_._m_e_t_a_l_e_v_e_l_._a_t_M_a_r_k_u_s _T_r_i_s_k_a


1133..33..11 IInnttrroodduuccttiioonn

An _a_s_s_o_c_i_a_t_i_o_n _l_i_s_t  as implemented by this  library is a collection  of
unique _k_e_y_s that are associated to _v_a_l_u_e_s.  Keys  must be ground, values
need not be.

An association list can be used to _f_e_t_c_h elements via  their keys and to
_e_n_u_m_e_r_a_t_e its elements in ascending order of their keys.

This library uses AAVVLL ttrreeeess to implement association lists.   This means
that

  o inserting a key

  o changing an association

  o fetching a single element

are all  _O_(log(N)_) _w_o_r_s_t_-_c_a_s_e  (and expected) time  operations, where  _N
denotes the number of elements in the association list.

The  logarithmic overhead  is often  acceptable in  practice.    Notable
advantages of association lists over several other methods are:

  o library(assoc) is written  entirely in Prolog, making it portable to
    other systems

  o the  interface  predicates fit  the  declarative nature  of  Prolog,
    avoiding destructive updates to terms

  o AVL  trees  scale very  predictably  and can  be used  to  represent
    sparse arrays efficiently.


1133..33..22 CCrreeaattiinngg aassssoocciiaattiioonn lliissttss

An assocation list is _c_r_e_a_t_e_d with one of the following predicates:


eemmppttyy__aassssoocc((_?_A_s_s_o_c))                                            _[_s_e_m_i_d_e_t_]
    Is true if _A_s_s_o_c is the empty association list.


lliisstt__ttoo__aassssoocc((_+_P_a_i_r_s_, _-_A_s_s_o_c))                                      _[_d_e_t_]
    Create  an association from a list  _P_a_i_r_s of Key-Value pairs.   List
    must not contain duplicate keys.

         EErrrroorrss domain_error(unique_key_pairs, List)  if  List con-
             tains duplicate keys


oorrdd__lliisstt__ttoo__aassssoocc((_+_P_a_i_r_s_, _-_A_s_s_o_c))                                   _[_d_e_t_]
    _A_s_s_o_c  is created  from an  ordered list _P_a_i_r_s  of Key-Value  pairs.
    The pairs must occur in strictly ascending order of their keys.

         EErrrroorrss domain_error(key_ordered_pairs, List)  if pairs are
             not ordered.


1133..33..33 QQuueerryyiinngg aassssoocciiaattiioonn lliissttss

An association list can be _q_u_e_r_i_e_d with:


ggeett__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_, _-_V_a_l_u_e))                                _[_s_e_m_i_d_e_t_]
    True if _K_e_y-_V_a_l_u_e is an association in _A_s_s_o_c.

         EErrrroorrss type_error(assoc, Assoc)   if   _A_s_s_o_c  is   not  an
             association list.


ggeett__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_0_, _?_V_a_l_0_, _?_A_s_s_o_c_, _?_V_a_l))                  _[_s_e_m_i_d_e_t_]
    True if _K_e_y-_V_a_l_0 is in _A_s_s_o_c_0 and _K_e_y-_V_a_l is in _A_s_s_o_c.


mmaaxx__aassssoocc((_+_A_s_s_o_c_, _-_K_e_y_, _-_V_a_l_u_e))                                _[_s_e_m_i_d_e_t_]
    True if _K_e_y-_V_a_l_u_e is in _A_s_s_o_c and _K_e_y is the largest key.


mmiinn__aassssoocc((_+_A_s_s_o_c_, _-_K_e_y_, _-_V_a_l_u_e))                                _[_s_e_m_i_d_e_t_]
    True if _K_e_y-_V_a_l_u_e is in assoc and _K_e_y is the smallest key.


ggeenn__aassssoocc((_?_K_e_y_, _+_A_s_s_o_c_, _?_V_a_l_u_e))                                 _[_n_o_n_d_e_t_]
    True  if _K_e_y-_V_a_l_u_e is an association  in _A_s_s_o_c.  Enumerates keys  in
    ascending order on backtracking.

         SSeeee aallssoo get_assoc/3.


1133..33..44 MMooddiiffyyiinngg aassssoocciiaattiioonn lliissttss

Elements of an association list can be changed and inserted with:


ppuutt__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_0_, _+_V_a_l_u_e_, _-_A_s_s_o_c))                           _[_d_e_t_]
    _A_s_s_o_c  is _A_s_s_o_c_0, except  that _K_e_y is associated  with _V_a_l_u_e.   This
    can be used to insert and change associations.


ddeell__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_0_, _?_V_a_l_u_e_, _-_A_s_s_o_c))                       _[_s_e_m_i_d_e_t_]
    True  if _K_e_y-_V_a_l_u_e is  in _A_s_s_o_c_0.   _A_s_s_o_c  is _A_s_s_o_c_0 with  _K_e_y-_V_a_l_u_e
    removed.


ddeell__mmiinn__aassssoocc((_+_A_s_s_o_c_0_, _?_K_e_y_, _?_V_a_l_, _-_A_s_s_o_c))                     _[_s_e_m_i_d_e_t_]
    True  if _K_e_y-Value is in _A_s_s_o_c_0 and _K_e_y is the smallest key.   _A_s_s_o_c
    is _A_s_s_o_c_0 with _K_e_y-Value  removed.  Warning:  This will succeed with
    _n_o bindings for _K_e_y or _V_a_l if _A_s_s_o_c_0 is empty.


ddeell__mmaaxx__aassssoocc((_+_A_s_s_o_c_0_, _?_K_e_y_, _?_V_a_l_, _-_A_s_s_o_c))                     _[_s_e_m_i_d_e_t_]
    True  if _K_e_y-Value is in _A_s_s_o_c_0 and _K_e_y is the greatest key.   _A_s_s_o_c
    is _A_s_s_o_c_0 with _K_e_y-Value  removed.  Warning:  This will succeed with
    _n_o bindings for _K_e_y or _V_a_l if _A_s_s_o_c_0 is empty.


1133..33..55 CCoonnvveerrssiioonn pprreeddiiccaatteess

Conversion of (parts of) an association list to _l_i_s_t_s is possible with:


aassssoocc__ttoo__lliisstt((_+_A_s_s_o_c_, _-_P_a_i_r_s))                                      _[_d_e_t_]
    Translate  _A_s_s_o_c to a list  _P_a_i_r_s of Key-Value pairs.   The keys  in
    _P_a_i_r_s are sorted in ascending order.


aassssoocc__ttoo__kkeeyyss((_+_A_s_s_o_c_, _-_K_e_y_s))                                       _[_d_e_t_]
    True  if _K_e_y_s is the list of keys in _A_s_s_o_c.  The keys  are sorted in
    ascending order.


aassssoocc__ttoo__vvaalluueess((_+_A_s_s_o_c_, _-_V_a_l_u_e_s))                                   _[_d_e_t_]
    True  if _V_a_l_u_e_s is the list of values in _A_s_s_o_c.   _V_a_l_u_e_s are ordered
    in  ascending  order  of the  key  to  which they  were  associated.
    _V_a_l_u_e_s may contain duplicates.


1133..33..66 RReeaassoonniinngg aabboouutt aassssoocciiaattiioonn lliissttss aanndd tthheeiirr eelleemmeennttss

Further inspection  predicates of an association  list and its  elements
are:


iiss__aassssoocc((_+_A_s_s_o_c))                                               _[_s_e_m_i_d_e_t_]
    True  if _A_s_s_o_c is an association  list.  This predicate checks  that
    the structure is valid,  elements are in order, and tree is balanced
    to  the extent  guaranteed by  AVL trees.   I.e.,  branches of  each
    subtree differ in depth by at most 1.


mmaapp__aassssoocc((_:_P_r_e_d_, _+_A_s_s_o_c))                                       _[_s_e_m_i_d_e_t_]
    True if _P_r_e_d(Value) is true for all values in _A_s_s_o_c.


mmaapp__aassssoocc((_:_P_r_e_d_, _+_A_s_s_o_c_0_, _?_A_s_s_o_c))                              _[_s_e_m_i_d_e_t_]
    Map  corresponding  values.    True if  _A_s_s_o_c  is _A_s_s_o_c_0  with  _P_r_e_d
    applied to all corresponding pairs of of values.


1133..44 lliibbrraarryy((bbrrooaaddccaasstt))::  BBrrooaaddccaasstt aanndd rreecceeiivvee eevveenntt nnoottiiffiiccaattiioonnss

The  broadcast  library   was  invented  to  realise  GUI   applications
consisting of  stand-alone components that use  the Prolog database  for
storing  the application  data.    Figure  ????  illustrates the  flow  of
information using this design

The  broadcasting service  provides two  services.    Using the  `shout'
service, an unknown number of agents may listen to  the message and act.
The broadcaster is not (directly) aware of the implications.   Using the
`request' service, listening  agents are asked for an  answer one-by-one
and the  broadcaster is allowed  to reject  answers using normal  Prolog
failure.

Shouting  is  often used  to  inform  about  changes made  to  a  common
database.  Other messages can be ``save yourself'' or ``show this''.

Requesting  is used  to get  information while  the  broadcaster is  not
aware who might  be able to answer the  question.  For example ``who  is
showing X?''.


bbrrooaaddccaasstt((_+_T_e_r_m))
    Broadcast  _T_e_r_m.   There are  no limitations to  _T_e_r_m, though  being
    a  global service,  it is  good practice  to use  a descriptive  and
    unique  principal  functor.     All  associated  goals  are  started
    and  regardless  of their  success  or failure,  broadcast/1  always
    succeeds.  Exceptions are passed.


bbrrooaaddccaasstt__rreeqquueesstt((_+_T_e_r_m))
    Unlike  broadcast/1,  this  predicate stops  if an  associated  goal
    succeeds.    Backtracking  causes it  to  try other  listeners.    A
    broadcast  request is used to fetch information without  knowing the
    identity  of the agent  providing it.   C.f. ``Is there someone  who
    knows the age of John?''  could be asked using

    ____________________________________________________________________|                                                                    |
    |         ...,                                                       |

    ||________broadcast_request(age_of('John',_Age)),___________________ ||

    If there is  an agent (_l_i_s_t_e_n_e_r) that registered an `age-of' service
    and knows about the age of `John' this question will be answered.


lliisstteenn((_+_T_e_m_p_l_a_t_e_, _:_G_o_a_l))
    Register  a  _l_i_s_t_e_n channel.    Whenever  a term  unifying  _T_e_m_p_l_a_t_e
    is  broadcasted,  call  _G_o_a_l.    The  following  example  traps  all
    broadcasted  messages as a variable unifies  to any message.  It  is
    commonly used to debug usage of the library.

    ____________________________________________________________________|                                                                    |
    | ?- listen(Term, (writeln(Term),fail)).                             |

    | ?- broadcast(hello(world)).                                        |
    | hello(world)                                                       |
    ||true._____________________________________________________________ ||


lliisstteenn((_+_L_i_s_t_e_n_e_r_, _+_T_e_m_p_l_a_t_e_, _:_G_o_a_l))
    Declare  _L_i_s_t_e_n_e_r as the  owner of  the channel.   Unlike a  channel
    opened  using listen/2,  channels that have  an owner can  terminate
    the  channel.  This  is commonly used if  an object is listening  to
    broadcast  messages.  In the  example below we define a  `name-item'
    displaying  the name of an  identifier represented by the  predicate
    name_of/2.

    ____________________________________________________________________|                                                                    |
    | :- pce_begin_class(name_item, text_item).                          |
    |                                                                    |
    | variable(id,    any,    get, "Id visualised").                     |

    |                                                                    |
    | initialise(NI, Id:any) :->                                         |
    |         name_of(Id, Name),                                         |
    |         send_super(NI, initialise, name, Name,                     |
    |                    message(NI, set_name, @arg1)),                  |
    |         send(NI, slot, id, Id),                                    |
    |         listen(NI, name_of(Id, Name),                              |

    |                send(NI, selection, Name)).                         |
    |                                                                    |
    | unlink(NI) :->                                                     |
    |         unlisten(NI),                                              |
    |         send_super(NI, unlink).                                    |
    |                                                                    |
    | set_name(NI, Name:name) :->                                        |
    |         get(NI, id, Id),                                           |

    |         retractall(name_of(Id, _)),                                |
    |         assert(name_of(Id, Name)),                                 |
    |         broadcast(name_of(Id, Name)).                              |
    |                                                                    |
    ||:-_pce_end_class._________________________________________________ ||


uunnlliisstteenn((_+_L_i_s_t_e_n_e_r))
    Deregister all entries created with listen/3 whose _L_i_s_t_e_n_e_r unify.


uunnlliisstteenn((_+_L_i_s_t_e_n_e_r_, _+_T_e_m_p_l_a_t_e))
    Deregister  all entries  created  with listen/3  whose _L_i_s_t_e_n_e_r  and
    _T_e_m_p_l_a_t_e unify.


uunnlliisstteenn((_+_L_i_s_t_e_n_e_r_, _+_T_e_m_p_l_a_t_e_, _:_G_o_a_l))
    Deregister  all   entries  created  with  listen/3  whose  _L_i_s_t_e_n_e_r,
    _T_e_m_p_l_a_t_e and _G_o_a_l unify.


lliisstteenniinngg((_?_L_i_s_t_e_n_e_r_, _?_T_e_m_p_l_a_t_e_, _?_G_o_a_l))
    Examine  the  current  listeners.    This  predicate is  useful  for
    debugging purposes.


1133..55 lliibbrraarryy((cchhaarrssiioo))::  II//OO oonn LLiissttss ooff CChhaarraacctteerr CCooddeess

    CCoommppaattiibbiilliittyy  The  naming  of  this  library  is not  in  line
         with the  ISO standard.   We  believe that  the SWI-Prolog
         native predicates form a more elegant alternative for this
         library.

This module emulates the Quintus/SICStus library  charsio.pl for reading
and writing from/to lists of character codes.   Most of these predicates
are straight calls  into similar SWI-Prolog primitives.   Some can  even
be replaced by ISO standard predicates.


ffoorrmmaatt__ttoo__cchhaarrss((_+_F_o_r_m_a_t_, _+_A_r_g_s_, _-_C_o_d_e_s))                            _[_d_e_t_]
    Use format/2 to write to a list of character codes.


ffoorrmmaatt__ttoo__cchhaarrss((_+_F_o_r_m_a_t_, _+_A_r_g_s_, _-_C_o_d_e_s_, _?_T_a_i_l))                     _[_d_e_t_]
    Use format/2 to write to a difference list of character codes.


wwrriittee__ttoo__cchhaarrss((_+_T_e_r_m_, _-_C_o_d_e_s))
    Write  a  term to  a  code list.    True  when _C_o_d_e_s  is a  list  of
    character codes written by write/1 on _T_e_r_m.


wwrriittee__ttoo__cchhaarrss((_+_T_e_r_m_, _-_C_o_d_e_s_, _?_T_a_i_l))
    Write  a term to a  code list.   _C_o_d_e_s\_T_a_i_l is a difference list  of
    character codes produced by write/1 on _T_e_r_m.


aattoomm__ttoo__cchhaarrss((_+_A_t_o_m_, _-_C_o_d_e_s))                                       _[_d_e_t_]
    Convert _A_t_o_m into a list of character codes.

         ddeepprreeccaatteedd Use ISO atom_codes/2.


aattoomm__ttoo__cchhaarrss((_+_A_t_o_m_, _-_C_o_d_e_s_, _?_T_a_i_l))                                _[_d_e_t_]
    Convert _A_t_o_m into a difference list of character codes.


nnuummbbeerr__ttoo__cchhaarrss((_+_N_u_m_b_e_r_, _-_C_o_d_e_s))                                   _[_d_e_t_]
    Convert Atom into a list of character codes.

         ddeepprreeccaatteedd Use ISO number_codes/2.


nnuummbbeerr__ttoo__cchhaarrss((_+_N_u_m_b_e_r_, _-_C_o_d_e_s_, _?_T_a_i_l))                            _[_d_e_t_]
    Convert _N_u_m_b_e_r into a difference list of character codes.


rreeaadd__ffrroomm__cchhaarrss((_+_C_o_d_e_s_, _-_T_e_r_m))                                     _[_d_e_t_]
    Read _C_o_d_e_s into _T_e_r_m.

         CCoommppaattiibbiilliittyy The  SWI-Prolog  version  does  not  require
             _C_o_d_e_s to end in a full-stop.


rreeaadd__tteerrmm__ffrroomm__cchhaarrss((_+_C_o_d_e_s_, _-_T_e_r_m_, _+_O_p_t_i_o_n_s))                       _[_d_e_t_]
    Read _C_o_d_e_s into _T_e_r_m.  _O_p_t_i_o_n_s are processed by read_term/3.

         CCoommppaattiibbiilliittyy sicstus


ooppeenn__cchhaarrss__ssttrreeaamm((_+_C_o_d_e_s_, _-_S_t_r_e_a_m))                                 _[_d_e_t_]
    Open _C_o_d_e_s as an input stream.

         SSeeee aallssoo open_string/2.


wwiitthh__oouuttppuutt__ttoo__cchhaarrss((_:_G_o_a_l_, _-_C_o_d_e_s))                                 _[_d_e_t_]
    Run  _G_o_a_l  as with  once/1.   Output  written  to current_output  is
    collected in _C_o_d_e_s.


wwiitthh__oouuttppuutt__ttoo__cchhaarrss((_:_G_o_a_l_, _-_C_o_d_e_s_, _?_T_a_i_l))                          _[_d_e_t_]
    Run  _G_o_a_l  as with  once/1.   Output  written  to current_output  is
    collected in _C_o_d_e_s\_T_a_i_l.


wwiitthh__oouuttppuutt__ttoo__cchhaarrss((_:_G_o_a_l_, _-_S_t_r_e_a_m_, _-_C_o_d_e_s_, _?_T_a_i_l))                 _[_d_e_t_]
    Same  as  with_output_to_chars/3 using  an  explicit stream.     The
    difference  list _C_o_d_e_s\_T_a_i_l contains  the character codes that  _G_o_a_l
    has written to _S_t_r_e_a_m.


1133..66 lliibbrraarryy((cchheecckk))::  CCoonnssiisstteennccyy cchheecckkiinngg

    SSeeee aallssoo
         - gxref/0 provides a graphical cross referencer
         - PceEmacs performs real time consistency checks while you
         edit
         -   library(prolog_xref)   implements   `offline'   cross-
         referencing
         - library(prolog_codewalk) implements `online' analysis

This  library provides  some consistency  checks for  the loaded  Prolog
program.   The predicate make/0 runs list_undefined/0 to find  undefined
predicates in `user' modules.


cchheecckk                                                             _[_d_e_t_]
    Run all consistency  checks defined by checker/2.  Checks enabled by
    default are:

      o  list_undefined/0 reports undefined predicates

      o  list_trivial_fails/0 reports  calls  for   which  there  is  no
         matching clause.

      o  list_redefined/0  reports   predicates   that  have   a   local
         definition and a  global definition.   Note that these are  nnoott
         errors.

      o  list_autoload/0  lists  predicates  that  will  be  defined  at
         runtime using the autoloader.


lliisstt__uunnddeeffiinneedd                                                     _[_d_e_t_]


lliisstt__uunnddeeffiinneedd((_+_O_p_t_i_o_n_s))                                           _[_d_e_t_]
    Report  undefined  predicates.     This  predicate  finds  undefined
    predciates  by decompiling  and analyzing the  body of all  clauses.
    _O_p_t_i_o_n_s:

    mmoodduullee__ccllaassss((_+_C_l_a_s_s_e_s))
         Process modules of the given _C_l_a_s_s_e_s.  The  default for classes
         is [user].    For example,  to include the  libraries into  the
         examination, use [user,library].

         SSeeee aallssoo
             - gxref/0 provides a graphical cross-referencer.
             - make/0 calls list_undefined/0


lliisstt__aauuttoollooaadd                                                      _[_d_e_t_]
    Report  predicates that may  be auto-loaded.   These are  predicates
    that are not defined, but will be loaded on demand if referenced.

         SSeeee aallssoo autoload/0

         TToo bbee ddoonnee This  predicate  uses  an  older mechanism  for
             finding undefined  predicates.  Should be synchronized
             with list undefined.


lliisstt__rreeddeeffiinneedd
    Lists predicates that  are defined in the global module user as well
    as  in a  normal module;  that is,  predicates for  which the  local
    definition overrules the global default definition.


lliisstt__vvooiidd__ddeeccllaarraattiioonnss                                             _[_d_e_t_]
    List predicates that have declared attributes, but no clauses.


lliisstt__ttrriivviiaall__ffaaiillss                                                 _[_d_e_t_]


lliisstt__ttrriivviiaall__ffaaiillss((_+_O_p_t_i_o_n_s))                                       _[_d_e_t_]
    List goals that  trivially fail because there is no matching clause.
    _O_p_t_i_o_n_s:

    mmoodduullee__ccllaassss((_+_C_l_a_s_s_e_s))
         Process modules of the given _C_l_a_s_s_e_s.  The  default for classes
         is [user].    For example,  to include the  libraries into  the
         examination, use [user,library].


ttrriivviiaall__ffaaiill__ggooaall((_:_G_o_a_l))                                     _[_m_u_l_t_i_f_i_l_e_]
    Multifile  hook that  tells list_trivial_fails/0 to  accept _G_o_a_l  as
    valid.


lliisstt__ssttrriinnggss                                                       _[_d_e_t_]


lliisstt__ssttrriinnggss((_+_O_p_t_i_o_n_s))                                             _[_d_e_t_]
    List  strings that appear  in clauses.   This  predicate is used  to
    find  portability issues for changing the Prolog  flag double_quotes
    from codes to  string, creating packed string objects.  Warnings may
    be suppressed using the following multifile hooks:

      o  string_predicate/1 to stop checking certain predicates

      o  valid_string_goal/1to tell the checker that a goal is safe.

         SSeeee aallssoo Prolog flag double_quotes.


ssttrriinngg__pprreeddiiccaattee((_:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r))                        _[_m_u_l_t_i_f_i_l_e_]
    Multifile  hook to  disable list_strings/0 on  the given  predicate.
    This is typically used for facts that store strings.


vvaalliidd__ssttrriinngg__ggooaall((_+_G_o_a_l))                             _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Multifile  hook  that qualifies  _G_o_a_l as  valid for  list_strings/0.
    For  example, format("Hello world~n")  is considered  proper use  of
    string constants.


cchheecckkeerr((_:_G_o_a_l_, _+_M_e_s_s_a_g_e_:_t_e_x_t))                               _[_m_u_l_t_i_f_i_l_e_]
    Register  code validation  routines.    Each clause  defines a  _G_o_a_l
    which  performs a consistency  check executed by  check/0.   _M_e_s_s_a_g_e
    is  a short description  of the  check.   For example, assuming  the
    my_checks module defines a predicate list_format_mistakes/0:

    ____________________________________________________________________|                                                                    |
    | :- multifile check:checker/2.                                      |

    | check:checker(my_checks:list_format_mistakes,                      |
    ||______________"errors_with_format/2_arguments").__________________ ||

    The predicate is  dynamic, so you can disable checks with retract/1.
    For example, to stop reporting redefined predicates:

    ____________________________________________________________________|                                                                    |
    ||retract(check:checker(list_redefined,_))._________________________ ||


1133..77 lliibbrraarryy((ccllppbb))::  CCLLPP((BB))::  CCoonnssttrraaiinntt LLooggiicc PPrrooggrraammmmiinngg oovveerr  BBoooolleeaann
     VVaarriiaabblleess

    aauutthhoorr  https://www.metalevel.atMarkus Triska


1133..77..11 IInnttrroodduuccttiioonn

This library provides CLP(B), Constraint Logic  Programming over Boolean
variables.   It can  be used to model  and solve combinatorial  problems
such as verification, allocation and covering tasks.

CLP(B)  is  an instance  of  the  general CLP(_X)  scheme  (section  ????),
extending logic programming with reasoning over specialised domains.

The  implementation is  based  on reduced  and ordered  Binary  Decision
Diagrams (BDDs).

Benchmarks  and usage  examples  of  this library  are  available  from:
https://www.metalevel.at/clpb/hhttttppss:://wwwwww..mmeettaalleevveell..aatt//ccllppbb//

We  recommend  the  following  reference  for  citing  this  library  in
scientific publications:

________________________________________________________________________|                                                                        |
|@inproceedings{Triska2016,                                              |

|  author    = "Markus Triska",                                          |
|  title     = "The {Boolean} Constraint Solver of {SWI-Prolog}:         |
|               System Description",                                     |
|  booktitle = "FLOPS",                                                  |
|  series    = "LNCS",                                                   |
|  volume    = 9613,                                                     |
|  year      = 2016,                                                     |
|  pages     = "45--61"                                                  |

|}|_____________________________________________________________________ | |

The            paper            is             available            from
https://www.metalevel.at/swiclpb.pdfhttps://www.metalevel.at/swiclpb.pdf


1133..77..22 BBoooolleeaann eexxpprreessssiioonnss

A _B_o_o_l_e_a_n _e_x_p_r_e_s_s_i_o_n is one of:

    __________________________________________________
    | 0              |false                           |
    | 1              |true                            |
    | _v_a_r_i_a_b_l_e       _|unknown truth value             |

    | _a_t_o_m           _|universally quantified variable |
    | ~ _E_x_p_r         _|logical NOT                     |
    | _E_x_p_r + _E_x_p_r    _|logical OR                      |
    | _E_x_p_r * _E_x_p_r    _|logical AND                     |
    | _E_x_p_r # _E_x_p_r    _|exclusive OR                    |
    | _V_a_r ^ _E_x_p_r     _|existential quantification      |
    | _E_x_p_r =:= _E_x_p_r  _|equality                        |

    | _E_x_p_r =\= _E_x_p_r  _|disequality (same as #)         |
    | _E_x_p_r =<  _E_x_p_r  _|less or equal (implication)     |
    | _E_x_p_r >= _E_x_p_r   _|greater or equal                |
    | _E_x_p_r < _E_x_p_r    _|less than                       |
    | _E_x_p_r > _E_x_p_r    _|greater than                    |
    | card(Is,Exprs) |_s_e_e _b_e_l_o_w                       _|
    _| +(Exprs)       |_s_e_e _b_e_l_o_w                       _|
    _|__*(Exprs)______________|_s_e_e___b_e_l_o_w_______________________________________________|

where _E_x_p_r again denotes a Boolean expression.

The Boolean  expression card(Is,Exprs) is  true iff  the number of  true
expressions in  the list _E_x_p_r_s is  a member of  the list _I_s of  integers
and integer ranges of the form From-To.

+(Exprs)  and  *(Exprs)  denote,   respectively,  the   disjunction  and
conjunction of all elements in the list _E_x_p_r_s of Boolean expressions.

Atoms denote  parametric values that  are universally  quantified.   All
universal  quantifiers  appear   implicitly  in  front  of  the   entire
expression.  In residual goals, universally  quantified variables always
appear on  the right-hand  side of equations.   Therefore,  they can  be
used to express functional dependencies on input variables.


1133..77..33 IInntteerrffaaccee pprreeddiiccaatteess

The most frequently used CLP(B) predicates are:

ssaatt((_+_E_x_p_r))
    True iff the Boolean expression _E_x_p_r is satisfiable.

ttaauutt((_+_E_x_p_r_, _-_T))
    If  _E_x_p_r is  a  tautology with  respect to  the posted  constraints,
    succeeds  with _T == 11.  If _E_x_p_r cannot be satisfied,  succeeds with _T
    == 00.  Otherwise, it fails.

llaabbeelliinngg((_+_V_s))
    Assigns  truth values to the variables _V_s such that  all constraints
    are satisfied.

The unification of  a CLP(B) variable _X with  a term _T is equivalent  to
posting the constraint sat(X=:=T).


1133..77..44 EExxaammpplleess

Here is an example session with a few queries and their answers:

________________________________________________________________________|                                                                        |
|?- use_module(library(clpb)).                                           |

|true.                                                                   |
|                                                                        |
|?- sat(X*Y).                                                            |
|X = Y, Y = 1.                                                           |
|                                                                        |
|?- sat(X * ~X).                                                         |
|false.                                                                  |
|                                                                        |

|?- taut(X * ~X, T).                                                     |
|T = 0,                                                                  |
|sat(X=:=X).                                                             |
|                                                                        |
|?- sat(X^Y^(X+Y)).                                                      |
|sat(X=:=X),                                                             |
|sat(Y=:=Y).                                                             |

|                                                                        |
|?- sat(X*Y + X*Z), labeling([X,Y,Z]).                                   |
|X = Z, Z = 1, Y = 0 ;                                                   |
|X = Y, Y = 1, Z = 0 ;                                                   |
|X = Y, Y = Z, Z = 1.                                                    |
|                                                                        |
|?- sat(X =< Y), sat(Y =< Z), taut(X =< Z, T).                           |
|T = 1,                                                                  |

|sat(X=:=X*Y),                                                           |
|sat(Y=:=Y*Z).                                                           |
|                                                                        |
|?- sat(1#X#a#b).                                                        |
|sat(X=:=a#b).|_________________________________________________________ |             |

The  pending residual  goals constrain  remaining  variables to  Boolean
expressions  and are  declaratively equivalent  to  the original  query.
The last example  illustrates that when applicable, remaining  variables
are expressed as functions of universally quantified variables.


1133..77..55 OObbttaaiinniinngg BBDDDDss

By default,  CLP(B) residual goals  appear in (approximately)  algebraic
normal form (ANF).  This projection is often computationally  expensive.
We  can set  the Prolog  flag clpb_residuals  to the  value  bdd to  see
the  BDD representation  of all  constraints.   This  results in  faster
projection  to residual  goals, and  is also  useful  for learning  more
about BDDs.  For example:

________________________________________________________________________|                                                                        |
|?- set_prolog_flag(clpb_residuals, bdd).                                |

|true.                                                                   |
|                                                                        |
|?- sat(X#Y).                                                            |
|node(3)- (v(X, 0)->node(2);node(1)),                                    |
|node(1)- (v(Y, 1)->true;false),                                         |
|node(2)-|(v(Y,_1)->false;true).________________________________________ |        |

Note that  this representation cannot  be pasted  back on the  toplevel,
and its details are  subject to change.  Use  copy_term/3to  obtain such
answers as Prolog terms.

The variable order  of the BDD is determined  by the order in which  the
variables first appear in  constraints.  To obtain different orders,  we
can for example use:

________________________________________________________________________|                                                                        |

|?- sat(+[1,Y,X]), sat(X#Y).                                             |
|node(3)- (v(Y, 0)->node(2);node(1)),                                    |
|node(1)- (v(X, 1)->true;false),                                         |
|node(2)-|(v(X,_1)->false;true).________________________________________ |        |


1133..77..66 EEnnaabblliinngg mmoonnoottoonniicc CCLLPP((BB))

In the  default execution  mode, CLP(B) constraints  are _n_o_t  monotonic.
This  means that  _a_d_d_i_n_g  constraints can  yield  new  solutions.    For
example:

________________________________________________________________________|                                                                        |
|?-          sat(X=:=1), X = 1+0.                                        |

|false.                                                                  |
|                                                                        |
|?- X = 1+0, sat(X=:=1), X = 1+0.                                        |
|X|=_1+0._______________________________________________________________ | |

This  behaviour is  highly problematic  from a  logical  point of  view,
and it  may render  https://www.metalevel.at/prolog/debuggingddeeccllaarraattiivvee
ddeebbuuggggiinngg techniques inapplicable.

Set the flag clpb_monotonic  to true to make CLP(B) mmoonnoottoonniicc.   If this
mode is enabled,  then you must wrap  CLP(B) variables with the  functor
v/1.  For example:

________________________________________________________________________|                                                                        |
|?- set_prolog_flag(clpb_monotonic, true).                               |
|true.                                                                   |

|                                                                        |
|?- sat(v(X)=:=1#1).                                                     |
|X|=_0._________________________________________________________________ | |


1133..77..77 EExxaammppllee::  PPiiggeeoonnss

In this  example,  we are attempting  to place  _I pigeons  into _J  holes
in  such a  way  that each  hole  contains  at most  one  pigeon.    One
interesting property  of this task  is that it  can be formulated  using
only _c_a_r_d_i_n_a_l_i_t_y  _c_o_n_s_t_r_a_i_n_t_s (card/2).   Another interesting aspect  is
that this task has no short resolution refutations in general.

In the  following, we use https://www.metalevel.at/prolog/dcgPPrroolloogg  DDCCGG
nnoottaattiioonn to describe  a list _C_s of  CLP(B) constraints that must all  be
satisfied.

________________________________________________________________________|                                                                        |
|:- use_module(library(clpb)).                                           |
|:- use_module(library(clpfd)).                                          |
|                                                                        |

|pigeon(I, J, Rows, Cs) :-                                               |
|        length(Rows, I), length(Row, J),                                |
|        maplist(same_length(Row), Rows),                                |
|        transpose(Rows, TRows),                                         |
|        phrase((all_card1(Rows),all_max1(TRows)), Cs).                  |
|                                                                        |
|all_card1([]) --> [].                                                   |
|all_card1([Ls|Lss]) --> [card([1],Ls)], all_card1(Lss).                 |

|                                                                        |
|all_max1([]) --> [].                                                    |
|all_max1([Ls|Lss])|-->_[card([0,1],Ls)],_all_max1(Lss).________________ |                  |

Example queries:

________________________________________________________________________|                                                                        |
|?- pigeon(9, 8, Rows, Cs), sat(*(Cs)).                                  |
|false.                                                                  |

|                                                                        |
|?- pigeon(2, 3, Rows, Cs), sat(*(Cs)),                                  |
|   append(Rows, Vs), labeling(Vs),                                      |
|   maplist(portray_clause, Rows).                                       |
|[0, 0, 1].                                                              |
|[0,|1,_0]._____________________________________________________________ |   |


1133..77..88 EExxaammppllee::  BBoooolleeaann cciirrccuuiitt

Consider a  Boolean circuit that express  the Boolean function XOR  with
4 NAND gates.   We can model  such a circuit with CLP(B) constraints  as
follows:

________________________________________________________________________|                                                                        |
|:- use_module(library(clpb)).                                           |
|                                                                        |
|nand_gate(X, Y, Z) :- sat(Z =:= ~(X*Y)).                                |

|                                                                        |
|xor(X, Y, Z) :-                                                         |
|        nand_gate(X, Y, T1),                                            |
|        nand_gate(X, T1, T2),                                           |
|        nand_gate(Y, T1, T3),                                           |
||_______nand_gate(T2,_T3,_Z).__________________________________________ ||

Using universally  quantified variables,  we can show  that the  circuit
does compute XOR as intended:

________________________________________________________________________|                                                                        |

|?- xor(x, y, Z).                                                        |
|sat(Z=:=x#y).|_________________________________________________________ |             |


1133..77..99 AAcckknnoowwlleeddggmmeennttss

The  interface  predicates  of  this  library  follow   the  example  of
https://sicstus.sics.seSSIICCSSttuuss PPrroolloogg.

Use SICStus Prolog for higher performance in many cases.


1133..77..1100 CCLLPP((BB)) pprreeddiiccaattee iinnddeexx

In the following, each CLP(B) predicate is described in more detail.

We recommend the following link to refer to this manual:

http://eu.swi-prolog.org/man/clpb.html


ssaatt((_+_E_x_p_r))                                                    _[_s_e_m_i_d_e_t_]
    True iff _E_x_p_r is a satisfiable Boolean expression.


ttaauutt((_+_E_x_p_r_, _-_T))                                               _[_s_e_m_i_d_e_t_]
    Tautology  check.   Succeeds with  _T = 0  if the Boolean  expression
    _E_x_p_r  cannot be satisfied,  and with _T  = 1 if  _E_x_p_r is always  true
    with respect to the current constraints.  Fails otherwise.


llaabbeelliinngg((_+_V_s))                                                   _[_m_u_l_t_i_]
    Enumerate  concrete solutions.  Assigns truth values to  the Boolean
    variables _V_s such that all stated constraints are satisfied.


ssaatt__ccoouunntt((_+_E_x_p_r_, _-_C_o_u_n_t))                                           _[_d_e_t_]
    _C_o_u_n_t  the number of  admissible assignments.   _C_o_u_n_t is the  number
    of  different assignments of  truth values to  the variables in  the
    Boolean  expression _E_x_p_r,  such  that _E_x_p_r  is true  and all  posted
    constraints are satisfiable.

    A  common form  of  invocation is  sat_count(+[1|Vs], Count):   This
    counts  the number of admissible assignments to _V_s  without imposing
    any further constraints.

    Examples:

    ____________________________________________________________________|                                                                    |
    | ?- sat(A =< B), Vs = [A,B], sat_count(+[1|Vs], Count).             |

    | Vs = [A, B],                                                       |
    | Count = 3,                                                         |
    | sat(A=:=A*B).                                                      |
    |                                                                    |
    | ?- length(Vs, 120),                                                |
    |    sat_count(+Vs, CountOr),                                        |
    |    sat_count(*(Vs), CountAnd).                                     |
    | Vs = [...],                                                        |

    | CountOr = 1329227995784915872903807060280344575,                   |
    ||CountAnd_=_1._____________________________________________________ ||


wweeiigghhtteedd__mmaaxxiimmuumm((_+_W_e_i_g_h_t_s_, _+_V_s_, _-_M_a_x_i_m_u_m))                        _[_m_u_l_t_i_]
    Enumerate  weighted optima over admissible assignments.   Maximize a
    linear  objective function  over Boolean variables  _V_s with  integer
    coefficients  _W_e_i_g_h_t_s.    This  predicate assigns  0  and 1  to  the
    variables in _V_s  such that all stated constraints are satisfied, and
    _M_a_x_i_m_u_m  is the  maximum  of sum(Weight_i*V_i)  over all  admissible
    assignments.    On  backtracking,  all admissible  assignments  that
    attain the optimum are generated.

    This  predicate  can  also be  used  to  _m_i_n_i_m_i_z_e a  linear  Boolean
    program, since negative integers can appear in _W_e_i_g_h_t_s.

    Example:

    ____________________________________________________________________|                                                                    |
    | ?- sat(A#B), weighted_maximum([1,2,1], [A,B,C], Maximum).          |

    ||A_=_0,_B_=_1,_C_=_1,_Maximum_=_3._________________________________ ||


rraannddoomm__llaabbeelliinngg((_+_S_e_e_d_, _+_V_s))                                        _[_d_e_t_]
    Select a single  random solution.  An admissible assignment of truth
    values  to the Boolean variables in _V_s is chosen in such a  way that
    each  admissible assignment is equally likely.  _S_e_e_d is  an integer,
    used as the initial seed for the random number generator.


1133..88 lliibbrraarryy((ccllppffdd))::  CCLLPP((FFDD)):: CCoonnssttrraaiinntt LLooggiicc PPrrooggrraammmmiinngg  oovveerr FFiinniittee
     DDoommaaiinnss

    aauutthhoorr  https://www.metalevel.atMarkus Triska

DDeevveellooppmmeenntt ooff tthhiiss lliibbrraarryy hhaass mmoovveedd ttoo SSIICCSSttuuss PPrroolloogg..
Please see https://github.com/triska/clpzCCLLPP((ZZ)) for more information.


1133..88..11 IInnttrroodduuccttiioonn

This  library  provides  CLP(FD):  Constraint  Logic   Programming  over
Finite  Domains.      This  is  an   instance  of  the  general   CLP(_X)
scheme (section  ????), extending  logic programming  with reasoning  over
specialised domains.   CLP(FD)  lets us reason about  iinntteeggeerrss in a  way
that honors the relational nature of Prolog.

Read https://www.metalevel.at/prologTThhee  PPoowweerr ooff  PPrroolloogg to  understand
how this library is meant to be used in practice.

There are two major use cases of CLP(FD) constraints:

 1. ddeeccllaarraattiivvee iinntteeggeerr aarriitthhmmeettiicc (section ????)

 2. solving  ccoommbbiinnaattoorriiaall  pprroobblleemmss such  as planning,  scheduling  and
    allocation tasks.

The predicates of this library can be classified as:

  o _a_r_i_t_h_m_e_t_i_c constraints like #=/2, #>/2  and #\=/2 (section ????)

  o the _m_e_m_b_e_r_s_h_i_p constraints in/2 and ins/2 (section ????)

  o the  _e_n_u_m_e_r_a_t_i_o_n  predicates  indomain/1,   label/1  and  labeling/2
    (section ????)

  o _c_o_m_b_i_n_a_t_o_r_i_a_l      constraints      like     all_distinct/1      and
    global_cardinality/2 (section ????)

  o _r_e_i_f_i_c_a_t_i_o_n predicates such as #<==>/2  (section ????)

  o _r_e_f_l_e_c_t_i_o_n predicates such as fd_dom/2 (section ????)

In  most  cases,  _a_r_i_t_h_m_e_t_i_c  _c_o_n_s_t_r_a_i_n_t_s  (section  ????)  are  the  only
predicates  you will  ever  need from  this  library.    When  reasoning
over  integers,  simply  replace low-level  arithmetic  predicates  like
(is)/2 and (>)/2 by the corresponding CLP(FD) constraints  like #=/2 and
#>/2  to honor  and preserve  declarative properties  of your  programs.
For  satisfactory performance,  arithmetic  constraints  are  implicitly
rewritten at compilation time so that low-level  fallback predicates are
automatically used whenever possible.

Almost all Prolog  programs also reason about  integers.  Therefore,  it
is highly advisable  that you make CLP(FD) constraints available  in all
your programs.  One way to do this is to  put the following directive in
your ~/.swiplrc initialisation file:

________________________________________________________________________|                                                                        |
|:-|use_module(library(clpfd))._________________________________________ |  |

All example  programs that  appear in the  CLP(FD) documentation  assume
that you have done this.

Important concepts  and principles  of this library  are illustrated  by
means of usage examples  that are available in a public  git repository:
https://github.com/triska/clpfdggiitthhuubb..ccoomm//ttrriisskkaa//ccllppffdd

If  you are  used  to the  complicated operational  considerations  that
low-level  arithmetic primitives  necessitate,  then moving  to  CLP(FD)
constraints may,  due to their power and  convenience, at first feel  to
you excessive  and almost like  cheating.   It _i_s_n_'_t.   Constraints  are
an integral part  of all popular Prolog  systems, and they are  designed
to help you  eliminate and avoid the  use of low-level and less  general
primitives by  providing declarative alternatives that  are meant to  be
used instead.

When  teaching   Prolog,  CLP(FD)   constraints  should  be   introduced
_b_e_f_o_r_e explaining low-level  arithmetic predicates and their  procedural
idiosyncrasies.    This  is because  constraints  are easy  to  explain,
understand and use due to their purely relational nature.   In contrast,
the modedness and directionality of low-level  arithmetic primitives are
impure limitations that are better deferred to more advanced lectures.

We       recommend       the       following       reference       (PDF:
https://www.metalevel.at/swiclpfd.pdfmetalevel.at/swiclpfd.pdf)      for
citing this library in scientific publications:

________________________________________________________________________|                                                                        |

|@inproceedings{Triska12,                                                |
|  author    = {Markus Triska},                                          |
|  title     = {The Finite Domain Constraint Solver of {SWI-Prolog}},    |
|  booktitle = {FLOPS},                                                  |
|  series    = {LNCS},                                                   |
|  volume    = {7294},                                                   |

|  year      = {2012},                                                   |
|  pages     = {307-316}                                                 |
|}|_____________________________________________________________________ | |

More information about  CLP(FD) constraints and their implementation  is
contained in:  https://www.metalevel.at/drt.pdfmmeettaalleevveell..aatt//ddrrtt..ppddff

The   best   way  to   discuss   applying,   improving   and   extending
CLP(FD)   constraints  is   to   use   the  dedicated   clpfd   tag   on
http://stackoverflow.comstackoverflow.com.     Several  of  the  world's
foremost CLP(FD) experts regularly participate in  these discussions and
will help you for free on this platform.


1133..88..22 AArriitthhmmeettiicc ccoonnssttrraaiinnttss

In modern Prolog  systems, aarriitthhmmeettiicc ccoonnssttrraaiinnttss subsume and  supersede
low-level predicates  over integers.   The main advantage of  arithmetic
constraints is  that they  are true  _r_e_l_a_t_i_o_n_s and  can be  used in  all
directions.   For  most programs,  arithmetic constraints  are the  only
predicates you will ever need from this library.

The most  important arithmetic constraint is  #=/2, which subsumes  both
(is)/2 and (=:=)/2 over  integers.  Use #=/2 to make your  programs more
general.  See declarative integer arithmetic (section ????).

In total, the arithmetic constraints are:

    ___________________________________________________________
    | Expr1 #= Expr2  |Expr1 equals Expr2                      |
    | Expr1 #\= Expr2 |Expr1 is not equal to Expr2             |
    | Expr1 #>= Expr2 |Expr1 is greater than or equal to Expr2 |

    | Expr1 #=< Expr2 |Expr1 is less than or equal to Expr2    |
    | Expr1 #> Expr2  |Expr1 is greater than Expr2             |
    |_Expr1_#<_Expr2__|Expr1_is_less_than_Expr2________________|

_E_x_p_r_1 and _E_x_p_r_2 denote aarriitthhmmeettiicc eexxpprreessssiioonnss, which are:

    _______________________________________________________

    | _i_n_t_e_g_e_r        _|Given value                          |
    | _v_a_r_i_a_b_l_e       _|Unknown integer                      |
    | ?(_v_a_r_i_a_b_l_e)    |Unknown integer                      |
    | -Expr          |Unary minus                          |
    | Expr + Expr    |Addition                             |
    | Expr * Expr    |Multiplication                       |
    | Expr - Expr    |Subtraction                          |
    | Expr ^ Expr    |Exponentiation                       |

    | min(Expr,Expr) |Minimum of two expressions           |
    | max(Expr,Expr) |Maximum of two expressions           |
    | Expr mod Expr  |Modulo induced by floored division   |
    | Expr rem Expr  |Modulo induced by truncated division |
    | abs(Expr)      |Absolute value                       |
    | Expr // Expr   |Truncated integer division           |
    |_Expr_div_Expr__|Floored_integer_division_____________|

where _E_x_p_r again denotes an arithmetic expression.

The bitwise  operations (\)/1,  (/\)/2, (\/)/2,  (>>)/2, (<<)/2,  lsb/1,
msb/1, popcount/1 and (xor)/2 are also supported.


1133..88..33 DDeeccllaarraattiivvee iinntteeggeerr aarriitthhmmeettiicc

The _a_r_i_t_h_m_e_t_i_c _c_o_n_s_t_r_a_i_n_t_s  (section ????) #=/2, #>/2  etc.  are meant  to
be used  _i_n_s_t_e_a_d of the  primitives (is)/2,  (=:=)/2, (>)/2  etc.   over
integers.    Almost  all Prolog  programs  also reason  about  integers.
Therefore,  it  is recommended  that  you  put the  following  directive
in  your ~/.swiplrc  initialisation  file  to make  CLP(FD)  constraints
available in all your programs:

________________________________________________________________________|                                                                        |
|:-|use_module(library(clpfd))._________________________________________ |  |

Throughout the following, it is assumed that you have done this.

The most  basic use of CLP(FD)  constraints is _e_v_a_l_u_a_t_i_o_n of  arithmetic
expressions involving integers.  For example:

________________________________________________________________________|                                                                        |

|?- X #= 1+2.                                                            |
|X|=_3._________________________________________________________________ | |

This could in principle also be achieved with  the lower-level predicate
(is)/2.    However,  an important  advantage of  arithmetic  constraints
is  their purely  relational nature:   Constraints  can be  used in  _a_l_l
_d_i_r_e_c_t_i_o_n_s, also  if one or more of  their arguments are only  partially
instantiated.  For example:

________________________________________________________________________|                                                                        |
|?- 3 #= Y+2.                                                            |
|Y|=_1._________________________________________________________________ | |

This relational  nature makes  CLP(FD) constraints easy  to explain  and
use, and  well suited for  beginners and experienced Prolog  programmers
alike.  In contrast, when using low-level integer arithmetic, we get:

________________________________________________________________________|                                                                        |

|?- 3 is Y+2.                                                            |
|ERROR: is/2: Arguments are not sufficiently instantiated                |
|                                                                        |
|?- 3 =:= Y+2.                                                           |
|ERROR:|=:=/2:_Arguments_are_not_sufficiently_instantiated______________ |      |

Due  to the  necessary  operational  considerations,  the use  of  these
low-level  arithmetic predicates  is considerably  harder to  understand
and should therefore be deferred to more advanced lectures.

For supported expressions, CLP(FD) constraints are  drop-in replacements
of these  low-level arithmetic predicates,  often yielding more  general
programs.  See n_factorial/2 (section ????) for an example.

This library uses goal_expansion/2 to automatically  rewrite constraints
at  compilation  time  so  that  low-level   arithmetic  predicates  are
_a_u_t_o_m_a_t_i_c_a_l_l_y used whenever possible.  For example, the predicate:

________________________________________________________________________|                                                                        |

|positive_integer(N)|:-_N_#>=_1.________________________________________ |                   |

is executed as if it were written as:

________________________________________________________________________|                                                                        |
|positive_integer(N) :-                                                  |
|        (   integer(N)                                                  |
|        ->  N >= 1                                                      |
|        ;   N #>= 1                                                     |
||_______)._____________________________________________________________ ||

This illustrates  why the performance of  CLP(FD) constraints is  almost
always completely satisfactory when  they are used in modes that  can be
handled by  low-level arithmetic.   To disable the automatic  rewriting,
set the Prolog flag clpfd_goal_expansion to false.

If  you are  used  to the  complicated operational  considerations  that
low-level  arithmetic primitives  necessitate,  then moving  to  CLP(FD)
constraints may,  due to their power and  convenience, at first feel  to
you excessive  and almost like  cheating.   It _i_s_n_'_t.   Constraints  are
an integral part  of all popular Prolog  systems, and they are  designed
to help you  eliminate and avoid the  use of low-level and less  general
primitives by  providing declarative alternatives that  are meant to  be
used instead.


1133..88..44 EExxaammppllee::  FFaaccttoorriiaall rreellaattiioonn

We  illustrate the  benefit of  using #=/2  for more  generality with  a
simple example.

Consider  first  a  rather  conventional  definition  of  n_factorial/2,
relating each natural number _N to its factorial _F:

________________________________________________________________________|                                                                        |
|n_factorial(0, 1).                                                      |

|n_factorial(N, F) :-                                                    |
|        N #> 0,                                                         |
|        N1 #= N - 1,                                                    |
|        n_factorial(N1, F1),                                            |
||_______F_#=_N_*_F1.___________________________________________________ ||

This program  uses CLP(FD) constraints  _i_n_s_t_e_a_d of low-level  arithmetic
throughout,  and  everything  that  _w_o_u_l_d  _h_a_v_e  _w_o_r_k_e_d  with  low-level
arithmetic _a_l_s_o  works with CLP(FD)  constraints, retaining roughly  the
same performance.  For example:

________________________________________________________________________|                                                                        |
|?- n_factorial(47, F).                                                  |

|F = 258623241511168180642964355153611979969197632389120000000000 ;      |
|false.|________________________________________________________________ |      |

Now  the point:   Due  to the  increased flexibility  and generality  of
CLP(FD) constraints, we are free to _r_e_o_r_d_e_r the goals as follows:

________________________________________________________________________|                                                                        |
|n_factorial(0, 1).                                                      |
|n_factorial(N, F) :-                                                    |
|        N #> 0,                                                         |
|        N1 #= N - 1,                                                    |

|        F #= N * F1,                                                    |
||_______n_factorial(N1,_F1).___________________________________________ ||

In  this concrete  case,  _t_e_r_m_i_n_a_t_i_o_n properties  of the  predicate  are
improved.  For example, the following queries now both terminate:

________________________________________________________________________|                                                                        |
|?- n_factorial(N, 1).                                                   |
|N = 0 ;                                                                 |
|N = 1 ;                                                                 |

|false.                                                                  |
|                                                                        |
|?- n_factorial(N, 3).                                                   |
|false.|________________________________________________________________ |      |

To make  the predicate terminate  if _a_n_y  argument is instantiated,  add
the (implied) constraint F #\= 0 before the recursive call.   Otherwise,
the query  n_factorial(N, 0) is  the only non-terminating  case of  this
kind.

The  value   of  CLP(FD)   constraints  does  _n_o_t   lie  in   completely
freeing  us  from   _a_l_l  procedural  phenomena.      For  example,   the
two  programs  do   not  even  have  the  same  _t_e_r_m_i_n_a_t_i_o_n   _p_r_o_p_e_r_t_i_e_s
in   all  cases.        Instead,   the   primary  benefit   of   CLP(FD)
constraints  is  that   they  allow  you  to  try  different   execution
orders  and  apply  https://www.metalevel.at/prolog/debuggingddeeccllaarraattiivvee
ddeebbuuggggiinngg  techniques  _a_t _a_l_l!     Reordering goals  (and  clauses)  can
significantly impact  the performance  of Prolog programs,  and you  are
free  to try  different  variants  if you  use  declarative  approaches.
Moreover, since all  CLP(FD) constraints _a_l_w_a_y_s _t_e_r_m_i_n_a_t_e, placing  them
earlier can  at most _i_m_p_r_o_v_e, never  worsen, the termination  properties
of  your programs.    An additional  benefit of  CLP(FD) constraints  is
that they eliminate the complexity of introducing (is)/2  and (=:=)/2 to
beginners, since  _b_o_t_h predicates  are subsumed by  #=/2 when  reasoning
over integers.

In  the  case  above,   the  clauses  are  mutually  exclusive   _i_f  the
first argument  is sufficiently  instantiated.   To  make the  predicate
deterministic  in such  cases while  retaining its  generality, you  can
use  zcompare/3  to _r_e_i_f_y  a  comparison,  making  the  different  cases
distinguishable by  pattern matching.    For example,  in this  concrete
case and others like  it, you can use zcompare(Comp, 0, N) to  obtain as
_C_o_m_p the symbolic outcome (<, =, >) of 0 compared to N.


1133..88..55 CCoommbbiinnaattoorriiaall ccoonnssttrraaiinnttss

In addition to subsuming and replacing  low-level arithmetic predicates,
CLP(FD)  constraints are  often  used  to solve  combinatorial  problems
such  as  planning,  scheduling  and  allocation   tasks.     Among  the
most  frequently  used  ccoommbbiinnaattoorriiaall  ccoonnssttrraaiinnttss  are  all_distinct/1,
global_cardinality/2 and  cumulative/2.    This  library  also  provides
several other  constraints like disjoint2/1  and automaton/8, which  are
useful in more specialized applications.


1133..88..66 DDoommaaiinnss

Each  CLP(FD) variable  has an  associated set  of admissible  integers,
which we  call the  variable's ddoommaaiinn.   Initially,  the domain of  each
CLP(FD) variable is the  set of _a_l_l integers.  CLP(FD)  constraints like
#=/2, #>/2 and #\=/2  can at most reduce, and never extend,  the domains
of their arguments.   The constraints  in/2 and ins/2 let us  explicitly
state domains  of CLP(FD)  variables.   The process  of determining  and
adjusting domains  of variables  is called  constraint pprrooppaaggaattiioonn,  and
it is  performed automatically by this  library.   When the domain of  a
variable contains only  one element, then the variable  is automatically
unified to that element.

Domains are taken into account when further constraints  are stated, and
by enumeration predicates like labeling/2.


1133..88..77 EExxaammppllee::  SSuuddookkuu

As  another example,  consider  _S_u_d_o_k_u:   It is  a popular  puzzle  over
integers that can be easily solved with CLP(FD) constraints.

________________________________________________________________________|                                                                        |
|sudoku(Rows) :-                                                         |

|        length(Rows, 9), maplist(same_length(Rows), Rows),              |
|        append(Rows, Vs), Vs ins 1..9,                                  |
|        maplist(all_distinct, Rows),                                    |
|        transpose(Rows, Columns),                                       |
|        maplist(all_distinct, Columns),                                 |
|        Rows = [As,Bs,Cs,Ds,Es,Fs,Gs,Hs,Is],                            |
|        blocks(As, Bs, Cs),                                             |
|        blocks(Ds, Es, Fs),                                             |

|        blocks(Gs, Hs, Is).                                             |
|                                                                        |
|blocks([], [], []).                                                     |
|blocks([N1,N2,N3|Ns1], [N4,N5,N6|Ns2], [N7,N8,N9|Ns3]) :-               |
|        all_distinct([N1,N2,N3,N4,N5,N6,N7,N8,N9]),                     |
|        blocks(Ns1, Ns2, Ns3).                                          |
|                                                                        |

|problem(1, [[_,_,_,_,_,_,_,_,_],                                        |
|            [_,_,_,_,_,3,_,8,5],                                        |
|            [_,_,1,_,2,_,_,_,_],                                        |
|            [_,_,_,5,_,7,_,_,_],                                        |
|            [_,_,4,_,_,_,1,_,_],                                        |
|            [_,9,_,_,_,_,_,_,_],                                        |
|            [5,_,_,_,_,_,_,7,3],                                        |
|            [_,_,2,_,1,_,_,_,_],                                        |

||___________[_,_,_,_,4,_,_,_,9]])._____________________________________ ||

Sample query:

________________________________________________________________________|                                                                        |
|?- problem(1, Rows), sudoku(Rows), maplist(portray_clause, Rows).       |
|[9, 8, 7, 6, 5, 4, 3, 2, 1].                                            |
|[2, 4, 6, 1, 7, 3, 9, 8, 5].                                            |
|[3, 5, 1, 9, 2, 8, 7, 4, 6].                                            |
|[1, 2, 8, 5, 3, 7, 6, 9, 4].                                            |

|[6, 3, 4, 8, 9, 2, 1, 5, 7].                                            |
|[7, 9, 5, 4, 6, 1, 8, 3, 2].                                            |
|[5, 1, 9, 2, 8, 6, 4, 7, 3].                                            |
|[4, 7, 2, 3, 1, 9, 5, 6, 8].                                            |
|[8, 6, 3, 7, 4, 5, 2, 1, 9].                                            |
|Rows|=_[[9,_8,_7,_6,_5,_4,_3,_2|...],_..._,_[...|...]].________________ |    |

In this concrete  case, the constraint solver  is strong enough to  find
the unique  solution without  any search.    For the  general case,  see
search (section ????).


1133..88..88 RReessiidduuaall ggooaallss

Here is an example session with a few queries and their answers:

________________________________________________________________________|                                                                        |
|?- X #> 3.                                                              |

|X in 4..sup.                                                            |
|                                                                        |
|?- X #\= 20.                                                            |
|X in inf..19\/21..sup.                                                  |
|                                                                        |
|?- 2*X #= 10.                                                           |
|X = 5.                                                                  |
|                                                                        |

|?- X*X #= 144.                                                          |
|X in -12\/12.                                                           |
|                                                                        |
|?- 4*X + 2*Y #= 24, X + Y #= 9, [X,Y] ins 0..sup.                       |
|X = 3,                                                                  |
|Y = 6.                                                                  |
|                                                                        |

|?- X #= Y #<==> B, X in 0..3, Y in 4..5.                                |
|B = 0,                                                                  |
|X in 0..3,                                                              |
|Y|in_4..5._____________________________________________________________ | |

The answers  emitted by the toplevel  are called _r_e_s_i_d_u_a_l _p_r_o_g_r_a_m_s,  and
the goals  that comprise  each answer  are called  rreessiidduuaall ggooaallss.    In
each case  above, and  as for  all pure programs,  the residual  program
is declaratively equivalent  to the original query.   From the  residual
goals, it  is clear  that the constraint  solver has deduced  additional
domain restrictions in many cases.

To inspect residual goals,  it is best to let the toplevel  display them
for us.   Wrap  the call of  your predicate  into call_residue_vars/2 to
make sure  that all constrained  variables are displayed.   To make  the
constraints a  variable is involved  in available as  a Prolog term  for
further reasoning within your program, use copy_term/3.  For example:

________________________________________________________________________|                                                                        |
|?- X #= Y + Z, X in 0..5, copy_term([X,Y,Z], [X,Y,Z], Gs).              |
|Gs = [clpfd: (X in 0..5), clpfd: (Y+Z#=X)],                             |

|X in 0..5,                                                              |
|Y+Z#=X.|_______________________________________________________________ |       |

This  library  also  provides   _r_e_f_l_e_c_t_i_o_n  predicates  (like  fd_dom/2,
fd_size/2 etc.)  with which we can inspect a  variable's current domain.
These  predicates can  be  useful if  you  want  to implement  your  own
labeling strategies.


1133..88..99 CCoorree rreellaattiioonnss aanndd sseeaarrcchh

Using  CLP(FD)  constraints  to  solve  combinatorial   tasks  typically
consists of two phases:

 1. MMooddeelliinngg.  In this phase, all relevant constraints are stated.

 2. SSeeaarrcchh.   In this phase,  _e_n_u_m_e_r_a_t_i_o_n _p_r_e_d_i_c_a_t_e_s are used to  search
    for concrete solutions.

It  is  good  practice to  keep  the  modeling  part,  via  a  dedicated
predicate called the ccoorree rreellaattiioonn, separate from the  actual search for
solutions.  This lets us observe termination  and determinism properties
of the core relation  in isolation from the search, and more  easily try
different search strategies.

As  an  example of  a  constraint  satisfaction  problem,  consider  the
cryptoarithmetic puzzle  SEND +  MORE = MONEY,  where different  letters
denote distinct integers between 0 and 9.  It can  be modeled in CLP(FD)
as follows:

________________________________________________________________________|                                                                        |

|puzzle([S,E,N,D] + [M,O,R,E] = [M,O,N,E,Y]) :-                          |
|        Vars = [S,E,N,D,M,O,R,Y],                                       |
|        Vars ins 0..9,                                                  |
|        all_different(Vars),                                            |
|                  S*1000 + E*100 + N*10 + D +                           |
|                  M*1000 + O*100 + R*10 + E #=                          |
|        M*10000 + O*1000 + N*100 + E*10 + Y,                            |

||_______M_#\=_0,_S_#\=_0.______________________________________________ ||

Notice that we  are _n_o_t using labeling/2  in this predicate, so that  we
can first execute  and observe the modeling  part in isolation.   Sample
query and its result (actual variables replaced for readability):

________________________________________________________________________|                                                                        |
|?- puzzle(As+Bs=Cs).                                                    |
|As = [9, A2, A3, A4],                                                   |
|Bs = [1, 0, B3, A2],                                                    |
|Cs = [1, 0, A3, A2, C5],                                                |

|A2 in 4..7,                                                             |
|all_different([9, A2, A3, A4, 1, 0, B3, C5]),                           |
|91*A2+A4+10*B3#=90*A3+C5,                                               |
|A3 in 5..8,                                                             |
|A4 in 2..8,                                                             |
|B3 in 2..8,                                                             |
|C5|in_2..8.____________________________________________________________ |  |

From this answer,  we see that this  core relation _t_e_r_m_i_n_a_t_e_s and is  in
fact _d_e_t_e_r_m_i_n_i_s_t_i_c.   Moreover, we see from the residual goals  that the
constraint solver has  deduced more stringent bounds for all  variables.
Such observations  are only possible  if modeling  and search parts  are
cleanly separated.

Labeling  can  then be  used  to  search  for solutions  in  a  separate
predicate or goal:

________________________________________________________________________|                                                                        |

|?- puzzle(As+Bs=Cs), label(As).                                         |
|As = [9, 5, 6, 7],                                                      |
|Bs = [1, 0, 8, 5],                                                      |
|Cs = [1, 0, 6, 5, 2] ;                                                  |
|false.|________________________________________________________________ |      |

In this  case, it suffices to  label a subset  of variables to find  the
puzzle's unique solution,  since the constraint solver is  strong enough
to reduce  the domains  of remaining variables  to singleton  sets.   In
general though, it is necessary to label all  variables to obtain ground
solutions.


1133..88..1100 EExxaammppllee::  EEiigghhtt qquueeeennss ppuuzzzzllee

We illustrate  the concepts of  the preceding sections  by means of  the
so-called _e_i_g_h_t _q_u_e_e_n_s _p_u_z_z_l_e.  The task is to place  8 queens on an 8x8
chessboard such  that none of the  queens is under  attack.  This  means
that no two queens share the same row, column or diagonal.

To  express this  puzzle via  CLP(FD) constraints,  we  must first  pick
a  suitable representation.     Since CLP(FD)  constraints  reason  over
_i_n_t_e_g_e_r_s,  we  must  find a  way  to  map  the positions  of  queens  to
integers.    Several  such  mappings  are conceivable,  and  it  is  not
immediately obvious  which we  should use.   On top  of that,  different
constraints can  be used  to express the  desired relations.   For  such
reasons, _m_o_d_e_l_i_n_g  combinatorial problems via CLP(FD) constraints  often
necessitates some creativity  and has been described  as more of an  art
than a science.

In our concrete  case, we observe that  there must be exactly one  queen
per column.    The following representation  therefore suggests  itself:
We are looking for  8 integers, one for each column, where  each integer
denotes the _r_o_w  of the queen that  is placed in the respective  column,
and which are subject to certain constraints.

In  fact, let  us now  generalize the  task  to the  so-called _N  _q_u_e_e_n_s
_p_u_z_z_l_e,  which is  obtained by  replacing 8  by _N  everywhere it  occurs
in the  above description.    We implement the  above considerations  in
the ccoorree  rreellaattiioonn n_queens/2,  where the first  argument is the  number
of queens  (which is  identical to  the number  of rows  and columns  of
the generalized  chessboard), and  the second  argument is a  list of  _N
integers that represents a solution in the form described above.

________________________________________________________________________|                                                                        |
|n_queens(N, Qs) :-                                                      |

|        length(Qs, N),                                                  |
|        Qs ins 1..N,                                                    |
|        safe_queens(Qs).                                                |
|                                                                        |
|safe_queens([]).                                                        |
|safe_queens([Q|Qs]) :- safe_queens(Qs, Q, 1), safe_queens(Qs).          |
|                                                                        |
|safe_queens([], _, _).                                                  |

|safe_queens([Q|Qs], Q0, D0) :-                                          |
|        Q0 #\= Q,                                                       |
|        abs(Q0 - Q) #\= D0,                                             |
|        D1 #= D0 + 1,                                                   |
||_______safe_queens(Qs,_Q0,_D1)._______________________________________ ||

Note  that all  these predicates  can be  used in  _a_l_l  _d_i_r_e_c_t_i_o_n_s:   We
can use  them to _f_i_n_d solutions,  _t_e_s_t solutions and _c_o_m_p_l_e_t_e  partially
instantiated solutions.

The original task can be readily solved with the following query:

________________________________________________________________________|                                                                        |
|?- n_queens(8, Qs), label(Qs).                                          |

|Qs|=_[1,_5,_8,_6,_3,_7,_2,_4]_.________________________________________ |  |

Using suitable  labeling strategies, we  can easily find solutions  with
80 queens and more:

________________________________________________________________________|                                                                        |
|?- n_queens(80, Qs), labeling([ff], Qs).                                |
|Qs = [1, 3, 5, 44, 42, 4, 50, 7, 68|...] .                              |
|                                                                        |
|?- time((n_queens(90, Qs), labeling([ff], Qs))).                        |

|% 5,904,401 inferences, 0.722 CPU in 0.737 seconds (98% CPU)            |
|Qs|=_[1,_3,_5,_50,_42,_4,_49,_7,_59|...]_._____________________________ |  |

Experimenting with different  search strategies is easy because we  have
separated the core relation from the actual search.


1133..88..1111 OOppttiimmiissaattiioonn

We can  use labeling/2 to  minimize or maximize the  value of a  CLP(FD)
expression,  and generate solutions  in increasing  or decreasing  order
of  the value.    See  the  labeling  options min(Expr)  and  max(Expr),
respectively.

Again,  to easily  try  different labeling  options in  connection  with
optimisation,  we  recommend  to introduce  a  dedicated  predicate  for
posting constraints,  and to use  labeling/2 in a separate  goal.   This
way, we  can observe properties of the  core relation in isolation,  and
try different labeling options without recompiling our code.

If   necessary,   we   can  use   once/1   to   commit  to   the   first
optimal  solution.     However,  it  is   often  very  valuable  to  see
alternative  solutions   that  are  _a_l_s_o   optimal,   so  that  we   can
choose  among  optimal solutions  by  other  criteria.    For  the  sake
of  https://www.metalevel.at/prolog/purityppuurriittyy  and  completeness,  we
recommend to avoid  once/1 and other constructs that lead  to impurities
in CLP(FD) programs.

Related  to optimisation  with  CLP(FD) constraints  are  http://eu.swi-
prolog.org/man/simplex.htmllibrary(simplex)  and  CLP(Q)   which  reason
about _l_i_n_e_a_r constraints over rational numbers.


1133..88..1122 RReeiiffiiccaattiioonn

The constraints in/2, #=/2, #\=/2,  #</2, #>/2, #=</2, and #>=/2  can be
_r_e_i_f_i_e_d, which means  reflecting their truth values into  Boolean values
represented by  the integers  0 and 1.    Let P and  Q denote  reifiable
constraints or Boolean variables, then:

    __________________________________________________
    | #\ Q       |True iff Q is false                  |
    | P #\/ Q    |True iff either P or Q               |
    | P #/\ Q    |True iff both P and Q                |

    | P #\ Q     |True iff either P or Q, but not both |
    | P #<==>  Q |True iff P and Q are equivalent      |
    | P #==>  Q  |True iff P implies Q                 |
    |_P_#<==_Q___|True_iff_Q_implies_P________________ |

The constraints of this table are reifiable as well.

When   reasoning   over   Boolean    variables,   also    consider   us-
ing    CLP(B)     constraints    as    provided    by     http://eu.swi-
prolog.org/man/clpb.htmllibrary(clpb).


1133..88..1133 EEnnaabblliinngg mmoonnoottoonniicc CCLLPP((FFDD))

In the  default execution mode,  CLP(FD) constraints still exhibit  some
non-relational properties.   For example,  _a_d_d_i_n_g constraints can  yield
new solutions:

________________________________________________________________________|                                                                        |
|?-          X #= 2, X = 1+1.                                            |
|false.                                                                  |
|                                                                        |

|?- X = 1+1, X #= 2, X = 1+1.                                            |
|X|=_1+1._______________________________________________________________ | |

This behaviour is highly  problematic from a logical point of view,  and
it may render declarative debugging techniques inapplicable.

Set the Prolog  flag clpfd_monotonic to true to make  CLP(FD) mmoonnoottoonniicc:
This  means that  _a_d_d_i_n_g  new constraints  _c_a_n_n_o_t yield  new  solutions.
When this flag is true, we must wrap variables  that occur in arithmetic
expressions with the functor (?)/1 or (#)/1.  For example:

________________________________________________________________________|                                                                        |
|?- set_prolog_flag(clpfd_monotonic, true).                              |
|true.                                                                   |
|                                                                        |
|?- #(X) #= #(Y) + #(Z).                                                 |

|#(Y)+ #(Z)#= #(X).                                                      |
|                                                                        |
|?-          X #= 2, X = 1+1.                                            |
|ERROR:|Arguments_are_not_sufficiently_instantiated_____________________ |      |

The wrapper  can be omitted for  variables that are already  constrained
to integers.


1133..88..1144 CCuussttoomm ccoonnssttrraaiinnttss

We can  define custom  constraints.   The mechanism  to do  this is  not
yet finalised, and we welcome suggestions and descriptions  of use cases
that are important to you.

As an  example of  how it can  be done  currently, let us  define a  new
custom constraint oneground(X,Y,Z), where  Z shall be 1 if at  least one
of X and Y is instantiated:

________________________________________________________________________|                                                                        |
|:- multifile clpfd:run_propagator/2.                                    |
|                                                                        |
|oneground(X, Y, Z) :-                                                   |

|        clpfd:make_propagator(oneground(X, Y, Z), Prop),                |
|        clpfd:init_propagator(X, Prop),                                 |
|        clpfd:init_propagator(Y, Prop),                                 |
|        clpfd:trigger_once(Prop).                                       |
|                                                                        |
|clpfd:run_propagator(oneground(X, Y, Z), MState) :-                     |
|        (   integer(X) -> clpfd:kill(MState), Z = 1                     |
|        ;   integer(Y) -> clpfd:kill(MState), Z = 1                     |

|        ;   true                                                        |
||_______)._____________________________________________________________ ||

First,  clpfd:make_propagator/2  is used  to  transform  a  user-defined
representation  of  the new  constraint  to  an  internal form.     With
clpfd:init_propagator/2, this internal  form is then  attached to X  and
Y. From now on,  the propagator will be invoked whenever the  domains of
X or  Y are changed.    Then, clpfd:trigger_once/1 is  used to give  the
propagator its first  chance for propagation even though the  variables'
domains  have  not yet  changed.    Finally,  clpfd:run_propagator/2  is
extended to define the actual propagator.  As  explained, this predicate
is automatically called  by the constraint solver.   The first  argument
is  the  user-defined  representation  of  the  constraint  as  used  in
clpfd:make_propagator/2, and  the  second argument  is a  mutable  state
that can be used  to prevent further invocations of the  propagator when
the constraint has become  entailed, by using clpfd:kill/1.   An example
of using the new constraint:

________________________________________________________________________|                                                                        |
|?- oneground(X, Y, Z), Y = 5.                                           |
|Y = 5,                                                                  |
|Z = 1,                                                                  |

|X|in_inf..sup._________________________________________________________ | |


1133..88..1155 AApppplliiccaattiioonnss

CLP(FD)  applications that  we find  particularly  impressive and  worth
studying include:

  o Michael   Hendricks    uses   CLP(FD)   constraints   for   flexible
    reasoning   about   _d_a_t_e_s   and   _t_i_m_e_s   in   the   http://www.swi-
    prolog.org/pack/list?p=julianjulian package.

  o Julien  Cumin uses  CLP(FD)  constraints for  integer arithmetic  in
    https://github.com/JCumin/BrachylogBrachylog.


1133..88..1166 AAcckknnoowwlleeddggmmeennttss

This      library     gives      you     a      glimpse     of      what
https://sicstus.sics.se/SSIICCSSttuuss  PPrroolloogg  can  do.     The   API  is  in-
tentionally mostly compatible with  that of SICStus Prolog, so  that you
can easily switch  to a much more  feature-rich and much faster  CLP(FD)
system  when you  need  it.    I thank  https://www.sics.se/  matsc/Mats
Carlsson,  the   designer  and  main  implementor  of   SICStus  Prolog,
for  his  elegant  example.      I  first  encountered  his   system  as
part of the  excellent http://www.complang.tuwien.ac.at/ulrich/gupu/GGUUPPUU
teaching  environment by  http://www.complang.tuwien.ac.at/ulrich/Ulrich
Neumerkel.    Ulrich  was also  the  first  and most  determined  tester
of  the present  system,  filing hundreds  of comments  and  suggestions
for  improvement.     https://people.cs.kuleuven.be/  tom.schrijvers/Tom
Schrijvers has contributed  several constraint libraries to  SWI-Prolog,
and I learned a  lot from his coding style and  implementation examples.
https://people.cs.kuleuven.be/  bart.demoen/Bart Demoen  was  a  driving
force behind the  implementation of attributed variables in  SWI-Prolog,
and this library could not even have started without  his prior work and
contributions.  Thank you all!


1133..88..1177 CCLLPP((FFDD)) pprreeddiiccaattee iinnddeexx

In the following, each CLP(FD) predicate is described in more detail.

We recommend the following link to refer to this manual:

http://eu.swi-prolog.org/man/clpfd.html


1133..88..1177..11 AArriitthhmmeettiicc ccoonnssttrraaiinnttss

_A_r_i_t_h_m_e_t_i_c constraints  are the most  basic use  of CLP(FD). Every  time
you use  (is)/2 or one of  the low-level arithmetic comparisons  ((<)/2,
(>)/2 etc.)  over integers, consider using  CLP(FD) constraints _i_n_s_t_e_a_d.
This  can at  most  _i_n_c_r_e_a_s_e  the generality  of  your  programs.    See
declarative integer arithmetic (section ????).


_?_X #= _?_Y
    The  arithmetic expression _X  equals _Y. This  is the most  important
    arithmetic  constraint (section  ????), subsuming  and replacing  both
    (is)/2  _a_n_d  (=:=)/2   over  integers.     See  declarative  integer
    arithmetic (section ????).


_?_X #\= _?_Y
    The  arithmetic expressions _X and  _Y evaluate to distinct  integers.
    When  reasoning over integers,  replace (=\=)/2  by #\=/2 to  obtain
    more  general  relations.      See  declarative  integer  arithmetic
    (section ????).


_?_X #>= _?_Y
    Same  as _Y #=<  _X. When reasoning over  integers, replace (>=)/2  by
    #>=/2  to obtain more  general relations.   See declarative  integer
    arithmetic (section ????).


_?_X #=< _?_Y
    The  arithmetic  expression _X  is  less than  or  equal to  _Y.  When
    reasoning   over  integers,  replace  (=<)/2  by  #=</2   to  obtain
    more  general  relations.      See  declarative  integer  arithmetic
    (section ????).


_?_X #> _?_Y
    Same as _Y #<  _X. When reasoning over integers, replace (>)/2 by #>/2
    to obtain more  general relations See declarative integer arithmetic
    (section ????).


_?_X #< _?_Y
    The  arithmetic expression  _X is  less than _Y.  When reasoning  over
    integers,  replace (<)/2 by #</2  to obtain more general  relations.
    See declarative integer arithmetic (section ????).

    In  addition  to its  regular use  in tasks  that require  it,  this
    constraint can also  be useful to eliminate uninteresting symmetries
    from  a problem.   For example,  all possible matches between  pairs
    built from four players in total:

    ____________________________________________________________________|                                                                    |
    | ?- Vs = [A,B,C,D], Vs ins 1..4,                                    |

    |         all_different(Vs),                                         |
    |         A #< B, C #< D, A #< C,                                    |
    |    findall(pair(A,B)-pair(C,D), label(Vs), Ms).                    |
    | Ms = [ pair(1, 2)-pair(3, 4),                                      |
    |        pair(1, 3)-pair(2, 4),                                      |
    ||_______pair(1,_4)-pair(2,_3)].____________________________________ ||


1133..88..1177..22 MMeemmbbeerrsshhiipp ccoonnssttrraaiinnttss

If you are  using CLP(FD) to model  and solve combinatorial tasks,  then
you typically need to specify the admissible domains of  variables.  The
_m_e_m_b_e_r_s_h_i_p _c_o_n_s_t_r_a_i_n_t_s in/2 and ins/2 are useful in such cases.


_?_V_a_r iinn _+_D_o_m_a_i_n
    _V_a_r is an element of _D_o_m_a_i_n.  _D_o_m_a_i_n is one of:

    _I_n_t_e_g_e_r
         Singleton set consisting only of _I_n_t_e_g_e_r.

    _L_o_w_e_r ....  _U_p_p_e_r
         All integers _I such  that _L_o_w_e_r =< _I =<  _U_p_p_e_r.  _L_o_w_e_r must  be
         an integer or  the atom iinnff,  which denotes negative  infinity.
         _U_p_p_e_r  must be  an  integer  or the  atom  ssuupp,  which  denotes
         positive infinity.

    _D_o_m_a_i_n_1 \/ _D_o_m_a_i_n_2
         The union of _D_o_m_a_i_n_1 and _D_o_m_a_i_n_2.


_+_V_a_r_s iinnss _+_D_o_m_a_i_n
    The  variables in the list  _V_a_r_s are elements of  _D_o_m_a_i_n.  See  in/2
    for the syntax of _D_o_m_a_i_n.


1133..88..1177..33 EEnnuummeerraattiioonn pprreeddiiccaatteess

When modeling  combinatorial tasks, the  actual search for solutions  is
typically performed by _e_n_u_m_e_r_a_t_i_o_n _p_r_e_d_i_c_a_t_e_s like labeling/2.   See the
the section about _c_o_r_e _r_e_l_a_t_i_o_n_s and search for more information.


iinnddoommaaiinn((_?_V_a_r))
    Bind _V_a_r to all  feasible values of its domain on backtracking.  The
    domain of _V_a_r must be finite.


llaabbeell((_+_V_a_r_s))
    Equivalent to labeling([], Vars).  See labeling/2.


llaabbeelliinngg((_+_O_p_t_i_o_n_s_, _+_V_a_r_s))
    Assign  a  value   to  each  variable  in  _V_a_r_s.     Labeling  means
    systematically  trying out  values for the  finite domain  variables
    _V_a_r_s  until all of them are ground.  The domain of  each variable in
    _V_a_r_s  must be finite.   _O_p_t_i_o_n_s  is a list of  options that let  you
    exhibit  some control over the  search process.  Several  categories
    of options exist:

    The  variable selection strategy lets you specify which  variable of
    _V_a_r_s is labeled next and is one of:

    lleeffttmmoosstt
         Label the variables in the  order they occur in _V_a_r_s.   This is
         the default.

    ffff
         _F_i_r_s_t _f_a_i_l.   Label the leftmost variable with  smallest domain
         next, in order to detect infeasibility early.  This  is often a
         good strategy.

    ffffcc
         Of  the  variables with  smallest  domains,  the  leftmost  one
         participating in most constraints is labeled next.

    mmiinn
         Label the  leftmost variable  whose lower bound  is the  lowest
         next.

    mmaaxx
         Label the leftmost  variable whose upper  bound is the  highest
         next.

    The value order is one of:

    uupp
         Try the elements of  the chosen variable's domain in  ascending
         order.  This is the default.

    ddoowwnn
         Try the domain elements in descending order.

    The branching strategy is one of:

    sstteepp
         For each variable X, a  choice is made between X = V and  X #\=
         V, where V is determined  by the value ordering options.   This
         is the default.

    eennuumm
         For each variable X, a  choice is made between X = V_1, X = V_2
         etc.,  for all  values V_i  of  the domain  of X.  The order  is
         determined by the value ordering options.

    bbiisseecctt
         For each variable X, a choice is made between X #=< M  and X #>
         M, where M is the midpoint of the domain of X.

    At most one option  of each category can be specified, and an option
    must not occur repeatedly.

    The order of solutions can be influenced with:

      o  min(Expr)

      o  max(Expr)

    This generates  solutions in ascending/descending order with respect
    to the evaluation  of the arithmetic expression Expr.  Labeling _V_a_r_s
    must make Expr ground.   If several such options are specified, they
    are interpreted from left to right, e.g.:

    ____________________________________________________________________|                                                                    |
    ||?-_[X,Y]_ins_10..20,_labeling([max(X),min(Y)],[X,Y])._____________ ||

    This  generates solutions  in descending  order of X,  and for  each
    binding  of X, solutions are generated  in ascending order of Y.  To
    obtain  the incomplete  behaviour  that other  systems exhibit  with
    "maximize(Expr)" and "minimize(Expr)", use once/1, e.g.:

    ____________________________________________________________________|                                                                    |

    ||once(labeling([max(Expr)],_Vars))_________________________________ ||

    Labeling  is  always  complete,  always terminates,  and  yields  no
    redundant  solutions.   See core relations  and search (section  ????)
    for usage advice.


1133..88..1177..44 GGlloobbaall ccoonnssttrraaiinnttss

A _g_l_o_b_a_l  _c_o_n_s_t_r_a_i_n_t expresses a relation  that involves many  variables
at once.   The most frequently  used global constraints of this  library
are the  combinatorial constraints  all_distinct/1,  global_cardinality/2
and cumulative/2.


aallll__ddiissttiinncctt((_+_V_a_r_s))
    True  iff _V_a_r_s are pairwise  distinct.  For  example, all_distinct/1
    can  detect that not all variables can assume distinct  values given
    the following domains:

    ____________________________________________________________________|                                                                    |
    | ?- maplist(in, Vs,                                                 |

    |            [1\/3..4, 1..2\/4, 1..2\/4, 1..3, 1..3, 1..6]),         |
    |    all_distinct(Vs).                                               |
    ||false.____________________________________________________________ ||


aallll__ddiiffffeerreenntt((_+_V_a_r_s))
    Like  all_distinct/1,  but   with  weaker  propagation.     Consider
    using  all_distinct/1  instead,  since all_distinct/1  is  typically
    acceptably efficient and propagates much more strongly.


ssuumm((_+_V_a_r_s_, _+_R_e_l_, _?_E_x_p_r))
    The  sum of elements of  the list _V_a_r_s is  in relation _R_e_l to  _E_x_p_r.
    _R_e_l is one of #=, #\=, #<, #>, #=<  or #>=.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- [A,B,C] ins 0..sup, sum([A,B,C], #=, 100).                      |

    | A in 0..100,                                                       |
    | A+B+C#=100,                                                        |
    | B in 0..100,                                                       |
    ||C_in_0..100.______________________________________________________ ||


ssccaallaarr__pprroodduucctt((_+_C_s_, _+_V_s_, _+_R_e_l_, _?_E_x_p_r))
    True  iff the  scalar product of  _C_s and  _V_s is in  relation _R_e_l  to
    _E_x_p_r.   _C_s  is a list  of integers,  _V_s is a  list of variables  and
    integers.  _R_e_l is #=, #\=, #<, #>, #=<  or #>=.


lleexx__cchhaaiinn((_+_L_i_s_t_s))
    _L_i_s_t_s are lexicographically non-decreasing.


ttuupplleess__iinn((_+_T_u_p_l_e_s_, _+_R_e_l_a_t_i_o_n))
    True  iff all  _T_u_p_l_e_s are  elements of _R_e_l_a_t_i_o_n.    Each element  of
    the  list _T_u_p_l_e_s is a list  of integers or finite domain  variables.
    _R_e_l_a_t_i_o_n  is  a  list  of  lists of  integers.     Arbitrary  finite
    relations,  such as  compatibility tables,  can be  modeled in  this
    way.    For example,  if 1  is compatible  with 2  and 5,  and 4  is
    compatible with 0 and 3:

    ____________________________________________________________________|                                                                    |
    | ?- tuples_in([[X,Y]], [[1,2],[1,5],[4,0],[4,3]]), X = 4.           |

    | X = 4,                                                             |
    ||Y_in_0\/3.________________________________________________________ ||

    As another example,  consider a train schedule represented as a list
    of  quadruples, denoting departure and arrival places and  times for
    each  train.   In the  following program, Ps  is a feasible  journey
    of  length 3  from A  to D  via trains that  are part  of the  given
    schedule.

    ____________________________________________________________________|                                                                    |

    | trains([[1,2,0,1],                                                 |
    |         [2,3,4,5],                                                 |
    |         [2,3,0,1],                                                 |
    |         [3,4,5,6],                                                 |
    |         [3,4,2,3],                                                 |
    |         [3,4,8,9]]).                                               |

    |                                                                    |
    | threepath(A, D, Ps) :-                                             |
    |         Ps = [[A,B,_T0,T1],[B,C,T2,T3],[C,D,T4,_T5]],              |
    |         T2 #> T1,                                                  |
    |         T4 #> T3,                                                  |
    |         trains(Ts),                                                |
    ||________tuples_in(Ps,_Ts).________________________________________ ||

    In this example, the unique solution is found without labeling:

    ____________________________________________________________________|                                                                    |

    | ?- threepath(1, 4, Ps).                                            |
    ||Ps_=_[[1,_2,_0,_1],_[2,_3,_4,_5],_[3,_4,_8,_9]].__________________ ||


sseerriiaalliizzeedd((_+_S_t_a_r_t_s_, _+_D_u_r_a_t_i_o_n_s))
    Describes  a set of non-overlapping  tasks.  _S_t_a_r_t_s  = [S_1,...,S_n],
    is  a list of variables  or integers, _D_u_r_a_t_i_o_n_s =  [D_1,...,D_n] is  a
    list  of non-negative integers.  Constrains _S_t_a_r_t_s and  _D_u_r_a_t_i_o_n_s to
    denote a  set of non-overlapping tasks, i.e.:  S_i + D_i =< S_j or S_j
    + D_j =< S_i for all 1 =< i < j =< n.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- length(Vs, 3),                                                  |

    |    Vs ins 0..3,                                                    |
    |    serialized(Vs, [1,2,3]),                                        |
    |    label(Vs).                                                      |
    | Vs = [0, 1, 3] ;                                                   |
    | Vs = [2, 0, 3] ;                                                   |
    ||false.____________________________________________________________ ||

         SSeeee aallssoo Dorndorf  et al.   2000,  "Constraint Propagation
             Techniques for the Disjunctive Scheduling Problem"


eelleemmeenntt((_?_N_, _+_V_s_, _?_V))
    The  _N-th element of  the list of finite  domain variables _V_s is  _V.
    Analogous to nth1/3.


gglloobbaall__ccaarrddiinnaalliittyy((_+_V_s_, _+_P_a_i_r_s))
    Global     Cardinality     constraint.             Equivalent     to
    global_cardinality(Vs, Pairs, []).  See global_cardinality/3.

    Example:

    ____________________________________________________________________|                                                                    |
    | ?- Vs = [_,_,_], global_cardinality(Vs, [1-2,3-_]), label(Vs).     |

    | Vs = [1, 1, 3] ;                                                   |
    | Vs = [1, 3, 1] ;                                                   |
    ||Vs_=_[3,_1,_1].___________________________________________________ ||


gglloobbaall__ccaarrddiinnaalliittyy((_+_V_s_, _+_P_a_i_r_s_, _+_O_p_t_i_o_n_s))
    Global  Cardinality  constraint.   _V_s  is a  list  of finite  domain
    variables,  _P_a_i_r_s  is a  list  of Key-Num  pairs,  where Key  is  an
    integer  and Num is a finite domain variable.  The  constraint holds
    iff each V in _V_s  is equal to some key, and for each Key-Num pair in
    _P_a_i_r_s, the number of  occurrences of Key in _V_s is Num.  _O_p_t_i_o_n_s is a
    list of options.  Supported options are:

    ccoonnssiisstteennccyy((_v_a_l_u_e))
         A weaker form of consistency is used.

    ccoosstt((_C_o_s_t_, _M_a_t_r_i_x))
         _M_a_t_r_i_x is a list of  rows, one for each variable, in  the order
         they occur in _V_s.   Each of these  rows is a list of  integers,
         one for  each key,  in  the order  these keys  occur in  _P_a_i_r_s.
         When variable  v_i is  assigned the value  of key  k_j, then  the
         associated cost is _M_a_t_r_i_x__{ij}.  _C_o_s_t is the sum of all costs.


cciirrccuuiitt((_+_V_s))
    True  iff  the   list  _V_s  of  finite  domain  variables  induces  a
    Hamiltonian  circuit.  The k-th element of _V_s denotes  the successor
    of node k.  Node indexing starts with 1.  Examples:

    ____________________________________________________________________|                                                                    |
    | ?- length(Vs, _), circuit(Vs), label(Vs).                          |

    | Vs = [] ;                                                          |
    | Vs = [1] ;                                                         |
    | Vs = [2, 1] ;                                                      |
    | Vs = [2, 3, 1] ;                                                   |
    | Vs = [3, 1, 2] ;                                                   |
    ||Vs_=_[2,_3,_4,_1]_._______________________________________________ ||


ccuummuullaattiivvee((_+_T_a_s_k_s))
    Equivalent to cumulative(Tasks, [limit(1)]).  See cumulative/2.


ccuummuullaattiivvee((_+_T_a_s_k_s_, _+_O_p_t_i_o_n_s))
    Schedule  with  a limited  resource.    _T_a_s_k_s is  a list  of  tasks,
    each  of the  form task(S_i, D_i, E_i, C_i, T_i).   S_i denotes  the
    start  time, D_i the  positive duration,  E_i the  end time,  C_i  the
    non-negative  resource  consumption,  and T_i the  task  identifier.
    Each  of  these arguments  must  be a  finite domain  variable  with
    bounded  domain, or an  integer.  The  constraint holds iff at  each
    time slot during the  start and end of each task, the total resource
    consumption  of all tasks running at  that time does not exceed  the
    global  resource limit.  _O_p_t_i_o_n_s is  a list of options.   Currently,
    the only supported option is:

    lliimmiitt((_L))
         The integer _L is the global resource limit.  Default is 1.

    For example, given  the following predicate that relates three tasks
    of durations 2 and 3 to a list containing their starting times:

    ____________________________________________________________________|                                                                    |

    | tasks_starts(Tasks, [S1,S2,S3]) :-                                 |
    |         Tasks = [task(S1,3,_,1,_),                                 |
    |                  task(S2,2,_,1,_),                                 |
    ||_________________task(S3,2,_,1,_)]._______________________________ ||

    We can use cumulative/2 as follows, and obtain a schedule:

    ____________________________________________________________________|                                                                    |

    | ?- tasks_starts(Tasks, Starts), Starts ins 0..10,                  |
    |    cumulative(Tasks, [limit(2)]), label(Starts).                   |
    | Tasks = [task(0, 3, 3, 1, _G36), task(0, 2, 2, 1, _G45), ...],     |
    ||Starts_=_[0,_0,_2]_.______________________________________________ ||


ddiissjjooiinntt22((_+_R_e_c_t_a_n_g_l_e_s))
    True  iff _R_e_c_t_a_n_g_l_e_s are not overlapping.   _R_e_c_t_a_n_g_l_e_s is a list  of
    terms  of the form F(X_i, W_i, Y_i, H_i), where F is any  functor, and
    the  arguments are finite domain variables or integers  that denote,
    respectively,  the X coordinate, width,  Y coordinate and height  of
    each rectangle.


aauuttoommaattoonn((_+_V_s_, _+_N_o_d_e_s_, _+_A_r_c_s))
    Describes  a list of finite  domain variables with a finite  automa-
    ton.    Equivalent to  automaton(Vs, _, Vs, Nodes, Arcs, [], [], _),
    a  common use  case of  automaton/8.   In the  following example,  a
    list of binary  finite domain variables is constrained to contain at
    least two consecutive ones:

    ____________________________________________________________________|                                                                    |
    | two_consecutive_ones(Vs) :-                                        |
    |         automaton(Vs, [source(a),sink(c)],                         |
    |                   [arc(a,0,a), arc(a,1,b),                         |

    |                    arc(b,0,a), arc(b,1,c),                         |
    ||___________________arc(c,0,c),_arc(c,1,c)]).______________________ ||

    Example query:

    ____________________________________________________________________|                                                                    |
    | ?- length(Vs, 3), two_consecutive_ones(Vs), label(Vs).             |
    | Vs = [0, 1, 1] ;                                                   |
    | Vs = [1, 1, 0] ;                                                   |
    ||Vs_=_[1,_1,_1].___________________________________________________ ||


aauuttoommaattoonn((_+_S_e_q_u_e_n_c_e_, _?_T_e_m_p_l_a_t_e_, _+_S_i_g_n_a_t_u_r_e_, _+_N_o_d_e_s_, _+_A_r_c_s_, _+_C_o_u_n_t_e_r_s_, _+_I_n_i_t_i_a_l_s_, _?_F_i_n_a_l_s))
    Describes   a  list  of  finite  domain  variables  with   a  finite
    automaton.    True iff  the finite  automaton induced  by _N_o_d_e_s  and
    _A_r_c_s  (extended with  _C_o_u_n_t_e_r_s) accepts  _S_i_g_n_a_t_u_r_e.   _S_e_q_u_e_n_c_e is  a
    list  of  terms, all  of the  same shape.    Additional  constraints
    must  link  _S_e_q_u_e_n_c_e  to  _S_i_g_n_a_t_u_r_e,  if  necessary.    _N_o_d_e_s  is  a
    list  of source(Node)  and  sink(Node) terms.    _A_r_c_s is  a list  of
    arc(Node,Integer,Node)  and arc(Node,Integer,Node,Exprs) terms  that
    denote  the automaton's transitions.   Each  node is represented  by
    an  arbitrary term.   Transitions  that are not  mentioned go to  an
    implicit  failure node.  _E_x_p_r_s is a list of  arithmetic expressions,
    of  the same  length as  _C_o_u_n_t_e_r_s.   In  each expression,  variables
    occurring  in   _C_o_u_n_t_e_r_s  symbolically  refer  to  previous  counter
    values,  and variables  occurring in _T_e_m_p_l_a_t_e  refer to the  current
    element  of  _S_e_q_u_e_n_c_e.    When  a transition  containing  arithmetic
    expressions  is  taken, each  counter is  updated  according to  the
    result  of the corresponding expression.  When a  transition without
    arithmetic  expressions  is taken,  all  counters remain  unchanged.
    _C_o_u_n_t_e_r_s  is a  list of variables.    _I_n_i_t_i_a_l_s is a  list of  finite
    domain  variables  or integers  denoting,  in  the same  order,  the
    initial  value of each counter.  These values are related  to _F_i_n_a_l_s
    according to the arithmetic expressions of the taken transitions.

    The  following example is taken from Beldiceanu,  Carlsson, Debruyne
    and   Petit:    "Reformulation   of  Global  Constraints  Based   on
    Constraints  Checkers", Constraints  10(4), pp 339-362  (2005).   It
    relates  a sequence of integers  and finite domain variables to  its
    number of inflexions,  which are switches between strictly ascending
    and strictly descending subsequences:

    ____________________________________________________________________|                                                                    |
    | sequence_inflexions(Vs, N) :-                                      |

    |         variables_signature(Vs, Sigs),                             |
    |         automaton(Sigs, _, Sigs,                                   |
    |                   [source(s),sink(i),sink(j),sink(s)],             |
    |                   [arc(s,0,s), arc(s,1,j), arc(s,2,i),             |
    |                    arc(i,0,i), arc(i,1,j,[C+1]), arc(i,2,i),       |
    |                    arc(j,0,j), arc(j,1,j),                         |
    |                    arc(j,2,i,[C+1])],                              |
    |                   [C], [0], [N]).                                  |

    |                                                                    |
    | variables_signature([], []).                                       |
    | variables_signature([V|Vs], Sigs) :-                               |
    |         variables_signature_(Vs, V, Sigs).                         |
    |                                                                    |
    | variables_signature_([], _, []).                                   |
    | variables_signature_([V|Vs], Prev, [S|Sigs]) :-                    |

    |         V #= Prev #<==> S #= 0,                                    |
    |         Prev #< V #<==> S #= 1,                                    |
    |         Prev #> V #<==> S #= 2,                                    |
    ||________variables_signature_(Vs,_V,_Sigs).________________________ ||

    Example queries:

    ____________________________________________________________________|                                                                    |
    | ?- sequence_inflexions([1,2,3,3,2,1,3,0], N).                      |
    | N = 3.                                                             |

    |                                                                    |
    | ?- length(Ls, 5), Ls ins 0..1,                                     |
    |    sequence_inflexions(Ls, 3), label(Ls).                          |
    | Ls = [0, 1, 0, 1, 0] ;                                             |
    ||Ls_=_[1,_0,_1,_0,_1]._____________________________________________ ||


cchhaaiinn((_+_Z_s_, _+_R_e_l_a_t_i_o_n))
    _Z_s  form a chain with respect to _R_e_l_a_t_i_o_n.   _Z_s is a list  of finite
    domain variables that  are a chain with respect to the partial order
    _R_e_l_a_t_i_o_n,  in the order they appear in  the list.  _R_e_l_a_t_i_o_n  must be
    #=, #=<, #>=, #<  or #>.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- chain([X,Y,Z], #>=).                                            |

    | X#>=Y,                                                             |
    ||Y#>=Z.____________________________________________________________ ||


1133..88..1177..55 RReeiiffiiccaattiioonn pprreeddiiccaatteess

Many  CLP(FD)  constraints can  be  _r_e_i_f_i_e_d.    This  means  that  their
truth  value is  itself  turned into  a  CLP(FD) variable,  so  that  we
can explicitly  reason about  whether a constraint  holds or  not.   See
reification (section ????).


#\ _+_Q
    _Q does _n_o_t hold.  See reification (section ????).

    For example, to obtain the complement of a domain:

    ____________________________________________________________________|                                                                    |
    | ?- #\ X in -3..0\/10..80.                                          |

    ||X_in_inf.._-4\/1..9\/81..sup._____________________________________ ||


_?_P #<==> _?_Q
    _P and _Q are equivalent.  See reification (section ????).

    For example:

    ____________________________________________________________________|                                                                    |
    | ?- X #= 4 #<==> B, X #\= 4.                                        |

    | B = 0,                                                             |
    ||X_in_inf..3\/5..sup.______________________________________________ ||

    The  following example uses reified constraints to relate a  list of
    finite  domain variables  to the  number of occurrences  of a  given
    value:

    ____________________________________________________________________|                                                                    |

    | vs_n_num(Vs, N, Num) :-                                            |
    |         maplist(eq_b(N), Vs, Bs),                                  |
    |         sum(Bs, #=, Num).                                          |
    |                                                                    |
    ||eq_b(X,_Y,_B)_:-_X_#=_Y_#<==>_B.__________________________________ ||

    Sample queries and their results:

    ____________________________________________________________________|                                                                    |

    | ?- Vs = [X,Y,Z], Vs ins 0..1, vs_n_num(Vs, 4, Num).                |
    | Vs = [X, Y, Z],                                                    |
    | Num = 0,                                                           |
    | X in 0..1,                                                         |
    | Y in 0..1,                                                         |
    | Z in 0..1.                                                         |

    |                                                                    |
    | ?- vs_n_num([X,Y,Z], 2, 3).                                        |
    | X = 2,                                                             |
    | Y = 2,                                                             |
    ||Z_=_2.____________________________________________________________ ||


_?_P #==> _?_Q
    _P implies _Q. See reification (section ????).


_?_P #<== _?_Q
    _Q implies _P. See reification (section ????).


_?_P #/\ _?_Q
    _P and _Q hold.  See reification (section ????).


_?_P #\/ _?_Q
    _P or _Q holds.  See reification (section ????).

    For  example,  the  sum  of  natural numbers  below  1000  that  are
    multiples of 3 or 5:

    ____________________________________________________________________|                                                                    |
    | ?- findall(N, (N mod 3 #= 0 #\/ N mod 5 #= 0, N in 0..999,         |

    |                indomain(N)),                                       |
    |            Ns),                                                    |
    |    sum(Ns, #=, Sum).                                               |
    | Ns = [0, 3, 5, 6, 9, 10, 12, 15, 18|...],                          |
    ||Sum_=_233168._____________________________________________________ ||


_?_P #\ _?_Q
    Either  _P  holds  or  _Q  holds,  but not  both.     See  reification
    (section ????).


zzccoommppaarree((_?_O_r_d_e_r_, _?_A_, _?_B))
    Analogous to compare/3, with finite domain variables _A and _B.

    Think  of zcompare/3  as _r_e_i_f_y_i_n_g  an arithmetic  comparison of  two
    integers.    This  means that  we can  explicitly  reason about  the
    different cases _w_i_t_h_i_n our  programs.  As in compare/3, the atoms <,
    >  and = denote the different cases of the trichotomy.   In contrast
    to compare/3 though,  zcompare/3 works correctly for _a_l_l _m_o_d_e_s, also
    if  only a subset  of the  arguments is instantiated.   This  allows
    you  to make  several predicates over  integers deterministic  while
    preserving their generality and completeness.  For example:

    ____________________________________________________________________|                                                                    |
    | n_factorial(N, F) :-                                               |

    |         zcompare(C, N, 0),                                         |
    |         n_factorial_(C, N, F).                                     |
    |                                                                    |
    | n_factorial_(=, _, 1).                                             |
    | n_factorial_(>, N, F) :-                                           |
    |         F #= F0*N,                                                 |
    |         N1 #= N - 1,                                               |
    ||________n_factorial(N1,_F0).______________________________________ ||

    This  version   of  n_factorial/2 is  deterministic   if  the  first
    argument is  instantiated, because argument indexing can distinguish
    the  different  clauses that  reflect  the possible  and  admissible
    outcomes of a comparison of _N against 0.  Example:

    ____________________________________________________________________|                                                                    |

    | ?- n_factorial(30, F).                                             |
    ||F_=_265252859812191058636308480000000.____________________________ ||

    Since  there is no clause  for <, the predicate automatically  _f_a_i_l_s
    if  _N is  less than  0.   The  predicate can  still be  used in  all
    directions, including the most general query:

    ____________________________________________________________________|                                                                    |
    | ?- n_factorial(N, F).                                              |
    | N = 0,                                                             |

    | F = 1 ;                                                            |
    | N = F, F = 1 ;                                                     |
    ||N_=_F,_F_=_2_.____________________________________________________ ||

    In this case,  all clauses are tried on backtracking, and zcompare/3
    ensures  that the respective ordering between N and 0 holds  in each
    case.

    The  truth value of a comparison can also be reified with  (#<==>)/2
    in combination with  one of the _a_r_i_t_h_m_e_t_i_c _c_o_n_s_t_r_a_i_n_t_s (section ????).
    See  reification (section ????).   However,  zcompare/3 lets you  more
    conveniently distinguish the cases.


1133..88..1177..66 RReefflleeccttiioonn pprreeddiiccaatteess

Reflection predicates let us obtain, in a  well-defined way, information
that  is  normally internal  to  this  library.    In  addition  to  the
predicates explained below, also  take a look at call_residue_vars/2 and
copy_term/3 to reason about CLP(FD) constraints that arise  in programs.
This can be useful in program analyzers and declarative debuggers.


ffdd__vvaarr((_+_V_a_r))
    True iff _V_a_r is a CLP(FD) variable.


ffdd__iinnff((_+_V_a_r_, _-_I_n_f))
    _I_n_f is the infimum of the current domain of _V_a_r.


ffdd__ssuupp((_+_V_a_r_, _-_S_u_p))
    _S_u_p is the supremum of the current domain of _V_a_r.


ffdd__ssiizzee((_+_V_a_r_, _-_S_i_z_e))
    Reflect  the  current size  of a  domain.   _S_i_z_e  is  the number  of
    elements  of the  current domain  of _V_a_r,  or  the atom  ssuupp if  the
    domain is unbounded.


ffdd__ddoomm((_+_V_a_r_, _-_D_o_m))
    _D_o_m  is the current  domain (see in/2)  of _V_a_r.   This predicate  is
    useful  if you  want to  reason about  domains.   It  is _n_o_t  needed
    if  you only want  to display remaining  domains; instead,  separate
    your  model from the search part  and let the toplevel display  this
    information via residual goals.

    For  example, to implement a custom labeling strategy, you  may need
    to  inspect the current  domain of a finite  domain variable.   With
    the  following code, you  can convert a _f_i_n_i_t_e  domain to a list  of
    integers:

    ____________________________________________________________________|                                                                    |
    | dom_integers(D, Is) :- phrase(dom_integers_(D), Is).               |

    |                                                                    |
    | dom_integers_(I)      --> { integer(I) }, [I].                     |
    | dom_integers_(L..U)   --> { numlist(L, U, Is) }, Is.               |
    ||dom_integers_(D1\/D2)_-->_dom_integers_(D1),_dom_integers_(D2).___ ||

    Example:

    ____________________________________________________________________|                                                                    |
    | ?- X in 1..5, X #\= 4, fd_dom(X, D), dom_integers(D, Is).          |
    | D = 1..3\/5,                                                       |

    | Is = [1,2,3,5],                                                    |
    ||X_in_1..3\/5._____________________________________________________ ||


1133..88..1188 CClloossiinngg aanndd ooppeenniinngg wwoorrddss aabboouutt CCLLPP((FFDD))

CLP(FD) constraints  are one of the  main reasons why logic  programming
approaches  are picked  over  other  paradigms for  solving  many  tasks
of high  practical relevance.    The usefulness  of CLP(FD)  constraints
for  scheduling,  allocation  and combinatorial  optimization  tasks  is
well-known both in academia and industry.

With  this library,  we take  the applicability  of CLP(FD)  constraints
one  step  further,  following  the road  that  visionary  systems  like
SICStus Prolog have already clearly outlined:  This  library is designed
to completely  subsume and _r_e_p_l_a_c_e  low-level predicates over  integers,
which were in  the past repeatedly found  to be a major stumbling  block
when introducing logic programming to beginners.

Embrace  the change  and new  opportunities that  this paradigm  allows!
Use  CLP(FD)  constraints  in  your  programs.     The  use  of  CLP(FD)
constraints instead of low-level arithmetic is also a  good indicator to
judge the quality of any introductory Prolog text.


1133..99 lliibbrraarryy((ccllppqqrr))::   CCoonnssttrraaiinntt LLooggiicc  PPrrooggrraammmmiinngg oovveerr RRaattiioonnaallss  aanndd
     RReeaallss

    Author:   _C_h_r_i_s_t_i_a_n _H_o_l_z_b_a_u_r, ported to SWI-Prolog by _L_e_s_l_i_e _D_e
    _K_o_n_i_n_c_k, K.U. Leuven

This CLP(Q,R) system is a port of the CLP(Q,R)  system of Sicstus Prolog
by Christian  Holzbaur:   Holzbaur C.:   OFAI  clp(q,r) Manual,  Edition
1.3.3, Austrian Research Institute for Artificial  Intelligence, Vienna,
TR-95-09,  1995.   This manual  is roughly  based on the  manual of  the
above mentioned CLP(Q,R) implementation.

The CLP(Q,R) system consists of two components:  the  CLP(Q) library for
handling constraints  over the rational numbers  and the CLP(R)  library
for handling  constraints over  the real numbers  (using floating  point
numbers as  representation).  Both  libraries offer the same  predicates
(with exception  of bb_inf/4 in  CLP(Q) and bb_inf/5  in CLP(R)). It  is
allowed to use both libraries in one program, but  using both CLP(Q) and
CLP(R) constraints on the same variable will result in an exception.

Please  note that  the clpqr  library  is _n_o_t  an _a_u_t_o_l_o_a_d  library  and
therefore this library must be loaded explicitly before using it:

________________________________________________________________________|                                                                        |

|:-|use_module(library(clpq)).__________________________________________ |  |

or

________________________________________________________________________|                                                                        |

|:-|use_module(library(clpr)).__________________________________________ |  |


1133..99..11 SSoollvveerr pprreeddiiccaatteess

The following predicates are provided to work with constraints:


{}((_+_C_o_n_s_t_r_a_i_n_t_s))
    Adds the constraints given by _C_o_n_s_t_r_a_i_n_t_s to the constraint store.


eennttaaiilleedd((_+_C_o_n_s_t_r_a_i_n_t))
    Succeeds  if  _C_o_n_s_t_r_a_i_n_t  is  necessarily true  within  the  current
    constraint  store.    This means  that adding  the  negation of  the
    constraint to the store results in failure.


iinnff((_+_E_x_p_r_e_s_s_i_o_n_, _-_I_n_f))
    Computes  the infimum of _E_x_p_r_e_s_s_i_o_n within the current state  of the
    constraint  store and returns that infimum  in _I_n_f.  This  predicate
    does not change the constraint store.


ssuupp((_+_E_x_p_r_e_s_s_i_o_n_, _-_S_u_p))
    Computes the supremum  of _E_x_p_r_e_s_s_i_o_n within the current state of the
    constraint  store and returns that supremum in _S_u_p.   This predicate
    does not change the constraint store.


mmiinniimmiizzee((_+_E_x_p_r_e_s_s_i_o_n))
    Minimizes  _E_x_p_r_e_s_s_i_o_n within the current constraint store.   This is
    the  same as computing  the infimum and  equating the expression  to
    that infimum.


mmaaxxiimmiizzee((_+_E_x_p_r_e_s_s_i_o_n))
    Maximizes  _E_x_p_r_e_s_s_i_o_n within the current constraint store.   This is
    the  same as computing the  supremum and equating the expression  to
    that supremum.


bbbb__iinnff((_+_I_n_t_s_, _+_E_x_p_r_e_s_s_i_o_n_, _-_I_n_f_, _-_V_e_r_t_e_x_, _+_E_p_s))
    This  predicate  is  offered  in  CLP(R) only.     It  computes  the
    infimum of _E_x_p_r_e_s_s_i_o_n  within the current constraint store, with the
    additional  constraint that in that  infimum, all variables in  _I_n_t_s
    have  integral values.   _V_e_r_t_e_x will contain  the values of _I_n_t_s  in
    the  infimum.   _E_p_s  denotes how  much a  value may  differ from  an
    integer to be considered  an integer.  E.g. when _E_p_s = 0.001, then X
    =  4.999 will be  considered as an  integer (5 in this  case).   _E_p_s
    should be between 0 and 0.5.


bbbb__iinnff((_+_I_n_t_s_, _+_E_x_p_r_e_s_s_i_o_n_, _-_I_n_f_, _-_V_e_r_t_e_x))
    This  predicate is offered in CLP(Q) only.   It behaves the  same as
    bb_inf/5 but does not use an error margin.


bbbb__iinnff((_+_I_n_t_s_, _+_E_x_p_r_e_s_s_i_o_n_, _-_I_n_f))
    The  same as bb_inf/5 or  bb_inf/4 but without returning the  values
    of the integers.  In CLP(R), an error margin of 0.001 is used.


dduummpp((_+_T_a_r_g_e_t_, _+_N_e_w_v_a_r_s_, _-_C_o_d_e_d_A_n_s_w_e_r))
    Returns the constraints  on _T_a_r_g_e_t in the list _C_o_d_e_d_A_n_s_w_e_r where all
    variables  of _T_a_r_g_e_t have been replaced by _N_e_w_V_a_r_s.   This operation
    does not change the constraint store.  E.g. in

    ____________________________________________________________________|                                                                    |
    ||dump([X,Y,Z],[x,y,z],Cons)________________________________________ ||

    Cons  will  contain the  constraints  on X,  Y  and Z,  where  these
    variables have been replaced by atoms x, y and z.


1133..99..22 SSyynnttaaxx ooff tthhee pprreeddiiccaattee aarrgguummeennttss

The arguments  of the  predicates defined  in the  subsection above  are
defined in table  ????.  Failing to  meet the syntax rules will result  in
an exception.
 _______________________________________________________________________
 | <_C_o_n_s_t_r_a_i_n_t_s>::=  <_C_o_n_s_t_r_a_i_n_t>                   |single constraint |
 |                 | <_C_o_n_s_t_r_a_i_n_t> , <_C_o_n_s_t_r_a_i_n_t_s>    |conjunction       |
 |                 | <_C_o_n_s_t_r_a_i_n_t> ; <_C_o_n_s_t_r_a_i_n_t_s>    |disjunction       |
 | <_C_o_n_s_t_r_a_i_n_t> ::=  <_E_x_p_r_e_s_s_i_o_n> < <_E_x_p_r_e_s_s_i_o_n>     |less than         |
 |                 | <_E_x_p_r_e_s_s_i_o_n> > <_E_x_p_r_e_s_s_i_o_n>     |greater than      |

 |                 | <_E_x_p_r_e_s_s_i_o_n> =< <_E_x_p_r_e_s_s_i_o_n>    |less or equal     |
 |                 | <=(<_E_x_p_r_e_s_s_i_o_n>, <_E_x_p_r_e_s_s_i_o_n>)  |less or equal     |
 |                 | <_E_x_p_r_e_s_s_i_o_n> >= <_E_x_p_r_e_s_s_i_o_n>    |greater or equal  |
 |                 | <_E_x_p_r_e_s_s_i_o_n> =\= <_E_x_p_r_e_s_s_i_o_n>   |not equal         |
 |                 | <_E_x_p_r_e_s_s_i_o_n> =:= <_E_x_p_r_e_s_s_i_o_n>   |equal             |
 |                 | <_E_x_p_r_e_s_s_i_o_n> = <_E_x_p_r_e_s_s_i_o_n>     |equal             |
 | <_E_x_p_r_e_s_s_i_o_n> ::=  <_V_a_r_i_a_b_l_e>                     |Prolog variable   |
 |                 | <_N_u_m_b_e_r>                       |Prolog number     |

 |                 | +<_E_x_p_r_e_s_s_i_o_n>                  |unary plus        |
 |                 | -<_E_x_p_r_e_s_s_i_o_n>                  |unary minus       |
 |                 | <_E_x_p_r_e_s_s_i_o_n> + <_E_x_p_r_e_s_s_i_o_n>     |addition          |
 |                 | <_E_x_p_r_e_s_s_i_o_n> - <_E_x_p_r_e_s_s_i_o_n>     |substraction      |
 |                 | <_E_x_p_r_e_s_s_i_o_n> * <_E_x_p_r_e_s_s_i_o_n>     |multiplication    |
 |                 | <_E_x_p_r_e_s_s_i_o_n> / <_E_x_p_r_e_s_s_i_o_n>     |division          |
 |                 | abs(<_E_x_p_r_e_s_s_i_o_n>)              |absolute value    |

 |                 | sin(<_E_x_p_r_e_s_s_i_o_n>)              |sine              |
 |                 | cos(<_E_x_p_r_e_s_s_i_o_n>)              |cosine            |
 |                 | tan(<_E_x_p_r_e_s_s_i_o_n>)              |tangent           |
 |                 | exp(<_E_x_p_r_e_s_s_i_o_n>)              |exponent          |
 |                 | pow(<_E_x_p_r_e_s_s_i_o_n>)              |exponent          |
 |                 | <_E_x_p_r_e_s_s_i_o_n> ^ <_E_x_p_r_e_s_s_i_o_n>     |exponent          |
 |                 | min(<_E_x_p_r_e_s_s_i_o_n>, <_E_x_p_r_e_s_s_i_o_n>) |minimum           |
 |_________________|_max(<_E_x_p_r_e_s_s_i_o_n>,_<_E_x_p_r_e_s_s_i_o_n>)_|maximum___________|

                  Table 13.1:  CLP(Q,R) constraint BNF


1133..99..33 UUssee ooff uunniiffiiccaattiioonn

Instead  of using  the {}/1  predicate, you  can also  use the  standard
unification mechanism to store constraints.  The  following code samples
are equivalent:

    ____________________________________________________________________|                                                                    |
  o _U_n_i_f_i_c_a_t_i_o_n_|_w_i_t_h{_aX_v_a_r_i_a_b_l_e=:= Y}                                                          |

    | {X = Y}                                                            |
    ||X_=_Y_____________________________________________________________ ||

    ____________________________________________________________________|                                                                    |
  o _U_n_i_f_i_c_a_t_i_o_n_|_w_i_t_h{_aX_n_u_m_b_e_r=:= 5.0}                                                        |

    | {X = 5.0}                                                          |
    ||X_=_5.0___________________________________________________________ ||


1133..99..44 NNoonn--lliinneeaarr ccoonnssttrraaiinnttss

The CLP(Q,R)  system deals only  passively with non-linear  constraints.
They remain in  a passive state until certain conditions  are satisfied.
These conditions,  which are called the  isolation axioms, are given  in
table ????.
     ______________________________________________________________
     | A =B *C     |B or C is ground       |A = 5 *  C or A = B * |
     |             |                       |4                     |
     |              |A  and  (B or  C)  are|20 = 5  * C or 20 = B |
     |______________|ground________________|*_4___________________|_
     | A =B=C      |C is ground            |A = B / 3             |
     |______________|A_and_B_are_ground____|4_=_12_/_C____________|_

     | X =min(Y; Z) |Y and Z are ground    |X = min(4,3)          |
     | X =max(Y; Z) |Y and Z are ground    |X = max(4,3)          |
     |_X_=abs(Y_)___|Y_is_ground___________|X_=_abs(-7)___________|_
     | X =pow(Y; Z) |X and Y are ground    |8 = 2 ^ Z             |
     | X =exp(Y; Z) |X and Z are ground    |8 = Y ^ 3             |
     |_X_=Y__^_Z___|Y_and_Z_are_ground_____|X_=_2_^_3_____________|_
     | X =sin(Y )   X|is ground            |1 = sin(Y)            |

     | X =cos(Y )   Y|is ground            |X = sin(1.5707)       |
     |_X_=tan(Y_)___|______________________|______________________|_
                 Table 13.2:  CLP(Q,R) isolating axioms


1133..99..55 SSttaattuuss aanndd kknnoowwnn pprroobblleemmss

The clpq  and clpr libraries are  `orphaned', i.e., they currently  have
no maintainer.

  o _T_o_p_-_l_e_v_e_l _o_u_t_p_u_t
    The  top-level  output  may contain  variables  not present  in  the
    original query:

    ____________________________________________________________________|                                                                    |

    | ?- {X+Y>=1}.                                                       |
    | {Y=1-X+_G2160, _G2160>=0}.                                         |
    |                                                                    |
    ||?-________________________________________________________________ ||

    Nonetheless,  for  linear  constraints  this kind  of  answer  means
    unconditional satisfiability.

  o _D_u_m_p_i_n_g _c_o_n_s_t_r_a_i_n_t_s
    The  first argument of dump/3 has to be a list of free  variables at
    call-time:

    ____________________________________________________________________|                                                                    |
    | ?- {X=1},dump([X],[Y],L).                                          |
    | ERROR: Unhandled exception: Unknown message:                       |
    |        instantiation_error(dump([1],[_G11],_G6),1)                 |

    ||?-________________________________________________________________ ||


1133..1100 lliibbrraarryy((ccssvv))::  PPrroocceessss CCSSVV ((CCoommmmaa--SSeeppaarraatteedd VVaalluueess)) ddaattaa

    SSeeee aallssoo  RFC 4180

    TToo bbee ddoonnee
         - Implement immediate assert of the data to avoid possible
         stack overflows.
         -  Writing  creates an  intermediate  code-list,  possibly
         overflowing resources.  This waits for pure output!

This library parses and generates CSV data.  CSV  data is represented in
Prolog as a list of  rows.  Each row is a compound term, where  all rows
have the same name and arity.


ccssvv__rreeaadd__ffiillee((_+_F_i_l_e_, _-_R_o_w_s))                                        _[_d_e_t_]


ccssvv__rreeaadd__ffiillee((_+_F_i_l_e_, _-_R_o_w_s_, _+_O_p_t_i_o_n_s))                              _[_d_e_t_]
    Read  a CSV file into  a list of  rows.  Each  row is a Prolog  term
    with  the same  arity.   _O_p_t_i_o_n_s  is handed  to csv//2.    Remaining
    options  are processed by phrase_from_file/3.   The default separator
    depends  on the file name extension and  is \t for .tsv files  and ,
    otherwise.

    Suppose  we want to create a predicate table/6 from a CSV  file that
    we  know contains 6 fields per record.   This can be done  using the
    code  below.   Without the  option arity(6),  this would generate  a
    predicate  table/N, where N  is the number  of fields per record  in
    the data.

    ____________________________________________________________________|                                                                    |
    | ?- csv_read_file(File, Rows, [functor(table), arity(6)]),          |
    ||___maplist(assert,_Rows)._________________________________________ ||


ccssvv((_?_R_o_w_s)) //                                                     _[_d_e_t_]


ccssvv((_?_R_o_w_s_, _+_O_p_t_i_o_n_s)) //                                           _[_d_e_t_]
    Prolog DCG to `read/write' CSV data.  _O_p_t_i_o_n_s:

    sseeppaarraattoorr((_+_C_o_d_e))
         The comma-separator.   Must be  a character code.   Default  is
         (of course) the comma.  Character codes can  be specified using
         the 0' notion.   E.g., using separator(0';) parses  a semicolon
         separated file.

    iiggnnoorree__qquuootteess((_+_B_o_o_l_e_a_n))
         If true  (default  false),  threat double  quotes as  a  normal
         character.

    ssttrriipp((_+_B_o_o_l_e_a_n))
         If  true (default  false),  strip  leading and  trailing  blank
         space.  RFC4180 says that blank space is part of the data.

    ccoonnvveerrtt((_+_B_o_o_l_e_a_n))
         If  true (default),  use  name/2  on  the  field data.     This
         translates the field into a number if possible.

    ccaassee((_+_A_c_t_i_o_n))
         If down,  downcase atomic values.   If up,  upcase them and  if
         preserve (default), do not change the case.

    ffuunnccttoorr((_+_A_t_o_m))
         Functor to use for creating row terms.  Default is row.

    aarriittyy((_?_A_r_i_t_y))
         Number  of fields  in  each  row.    This  predicate  raises  a
         domain_error(row_arity(Expected), Found)  if  a  row  is  found
         with different arity.

    mmaattcchh__aarriittyy((_+_B_o_o_l_e_a_n))
         If false (default  true), do not  reject CSV files where  lines
         provide a varying  number of fields (columns).   This can be  a
         work-around to use some incorrect CSV files.


ccssvv__rreeaadd__ffiillee__rrooww((_+_F_i_l_e_, _-_R_o_w_, _+_O_p_t_i_o_n_s))                         _[_n_o_n_d_e_t_]
    True  when _R_o_w is a row in _F_i_l_e.   First unifies _R_o_w with  the first
    row  in _F_i_l_e.   Backtracking  yields the  second, ...   row.    This
    interface  is an alternative to  csv_read_file/3that avoids  loading
    all  rows in memory.   Note that  this interface does not  guarantee
    that all rows in _F_i_l_e have the same arity.

    In  addition  to  the  options  of csv_read_file/3,  this  predicate
    processes the option:

    lliinnee((_-_L_i_n_e))
         _L_i_n_e is unified with the 1-based line-number from  which _R_o_w is
         read.  Note that _L_i_n_e is not the physical line,  but rather the
         _l_o_g_i_c_a_l record number.

         TToo bbee ddoonnee Input  is  read  line by  line.    If  a record
             separator  is embedded in a quoted  field, parsing the
             record  fails and another line is  added to the input.
             This  does  not  nicely deal  with  other  reasons why
             parsing the row may fail.


ccssvv__rreeaadd__rrooww((_+_S_t_r_e_a_m_, _-_R_o_w_, _+_C_o_m_p_i_l_e_d_O_p_t_i_o_n_s))                      _[_d_e_t_]
    Read the next CSV  record from _S_t_r_e_a_m and unify the result with _R_o_w.
    _C_o_m_p_i_l_e_d_O_p_t_i_o_n_s  is created  from options defined  for csv//2  using
    csv_options/2.   _R_o_w is unified  with end_of_file upon reaching  the
    end of the input.


ccssvv__ooppttiioonnss((_-_C_o_m_p_i_l_e_d_, _+_O_p_t_i_o_n_s))                                   _[_d_e_t_]
    _C_o_m_p_i_l_e_d  is  the  compiled  representation of  the  CSV  processing
    options  as they may  be passed  into csv//2, etc.   This  predicate
    is  used  in  combination  with  csv_read_row/3  to  avoid  repeated
    processing of the options.


ccssvv__wwrriittee__ffiillee((_+_F_i_l_e_, _+_D_a_t_a))                                       _[_d_e_t_]


ccssvv__wwrriittee__ffiillee((_+_F_i_l_e_, _+_D_a_t_a_, _+_O_p_t_i_o_n_s))                             _[_d_e_t_]
    Write  a list  of Prolog terms  to a CSV  file.   _O_p_t_i_o_n_s are  given
    to  csv//2.   Remaining options are  given to open/4.   The  default
    separator  depends on  the file name  extension and  is \t for  .tsv
    files and , otherwise.


ccssvv__wwrriittee__ssttrreeaamm((_+_S_t_r_e_a_m_, _+_D_a_t_a_, _+_O_p_t_i_o_n_s))                         _[_d_e_t_]
    Write   the  rows  in  _D_a_t_a  to   _S_t_r_e_a_m.     This  is  similar   to
    csv_write_file/3,   but  can  deal  with   data  that  is   produced
    incrementally.     The example  below  saves  all answers  from  the
    predicate data/3 to File.

    ____________________________________________________________________|                                                                    |
    | save_data(File) :-                                                 |

    |    setup_call_cleanup(                                             |
    |        open(File, write, Out),                                     |
    |        forall(data(C1,C2,C3),                                      |
    |               csv_write_stream(Out, [row(C1,C2,C3)], [])),         |
    ||_______close(Out)),_______________________________________________ ||


1133..1111 lliibbrraarryy((ddeebbuugg))::  PPrriinntt ddeebbuugg mmeessssaaggeess aanndd tteesstt aasssseerrttiioonnss

    aauutthhoorr  Jan Wielemaker

This library is a replacement for format/3 for  printing debug messages.
Messages are  assigned a _t_o_p_i_c.   By  dynamically enabling or  disabling
topics  the user  can select  desired messages.    Debug statements  are
removed when the code is compiled for optimization.

See manual for details.  With XPCE, you can use  the call below to start
a graphical monitoring tool.

________________________________________________________________________|                                                                        |

|?-|prolog_ide(debug_monitor).__________________________________________ |  |

Using  the predicate  assertion/1 you  can make  assumptions about  your
program explicit, trapping the debugger if the condition does not hold.


ddeebbuuggggiinngg((_+_T_o_p_i_c))                                             _[_s_e_m_i_d_e_t_]


ddeebbuuggggiinngg((_-_T_o_p_i_c))                                              _[_n_o_n_d_e_t_]


ddeebbuuggggiinngg((_?_T_o_p_i_c_, _?_B_o_o_l))                                       _[_n_o_n_d_e_t_]
    Examine  debug topics.   The form  debugging(+Topic) may be used  to
    perform more complex debugging tasks.  A typical usage skeleton is:

    ____________________________________________________________________|                                                                    |
    |       (   debugging(mytopic)                                       |

    |       ->  <perform debugging actions>                              |
    |       ;   true                                                     |
    |       ),                                                           |
    ||______..._________________________________________________________ ||

    The  other two calls  are intended to  examine existing and  enabled
    debugging tokens and are typically not used in user programs.


ddeebbuugg((_+_T_o_p_i_c))                                                     _[_d_e_t_]


nnooddeebbuugg((_+_T_o_p_i_c))                                                   _[_d_e_t_]
    Add/remove  a topic  from  being printed.    nodebug(_) removes  all
    topics.   Gives a warning if  the topic is not defined unless  it is
    used  from a directive.   The latter allows placing debug topics  at
    the start of a (load-)file without warnings.

    For  debug/1, _T_o_p_i_c can be a term _T_o_p_i_c  > Out, where Out is either
    a  stream or  stream-alias or  a filename  (atom).   This  redirects
    debug information on this topic to the given output.


lliisstt__ddeebbuugg__ttooppiiccss                                                  _[_d_e_t_]
    List currently known debug topics and their setting.


ddeebbuugg__mmeessssaaggee__ccoonntteexxtt((_+_W_h_a_t))                                       _[_d_e_t_]
    Specify  additional  context  for  debug  messages.    _W_h_a_t  is  one
    of  +Context  or  -Context,  and  Context is  one  of  thread,  time
    or  time(Format),   where  Format  is  a  format  specification  for
    format_time/3 (default  is %T.%3f).   Initially, debug/3 shows  only
    thread information.


ddeebbuugg((_+_T_o_p_i_c_, _+_F_o_r_m_a_t_, _:_A_r_g_s))                                     _[_d_e_t_]
    _F_o_r_m_a_t a message if  debug topic is enabled.  Similar to format/3 to
    user_error,  but only prints if _T_o_p_i_c is activated  through debug/1.
    _A_r_g_s  is  a  meta-argument to  deal  with  goal for  the  @-command.
    Output  is first handed  to the hook prolog:debug_print_hook/3.   If
    this  fails, _F_o_r_m_a_t+_A_r_g_s  is translated to  text using the  message-
    translation  (see print_message/2) for the term  debug(Format, Args)
    and  then  printed  to  every matching  destination  (controlled  by
    debug/1) using print_message_lines/3.

    The message is preceded by '% ' and terminated with a newline.

         SSeeee aallssoo format/3.


pprroolloogg::ddeebbuugg__pprriinntt__hhooookk((_+_T_o_p_i_c_, _+_F_o_r_m_a_t_, _+_A_r_g_s))      _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Hook  called  by debug/3.     This hook  is  used by  the  graphical
    frontend that can be activated using prolog_ide/1:

    ____________________________________________________________________|                                                                    |
    ||?-_prolog_ide(debug_monitor)._____________________________________ ||


aasssseerrttiioonn((_:_G_o_a_l))                                                  _[_d_e_t_]
    Acts  similar  to C  assert()  macro.    It has  no effect  if  _G_o_a_l
    succeeds.    If _G_o_a_l  fails or  throws an  exception, the  following
    steps are taken:

      o  call prolog:assertion_failed/2.   If  prolog:assertion_failed/2
         fails, then:

           {{ If  this  is  an  interactive  toplevel  thread,   print  a
             message, the stack-trace, and finally trap the debugger.

           {{ Otherwise, throw  error(assertion_error(Reason, G),_) where
             Reason is one of fail or the exception raised.


pprroolloogg::aasssseerrttiioonn__ffaaiilleedd((_+_R_e_a_s_o_n_, _+_G_o_a_l))              _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    This  hook is called if  the _G_o_a_l of assertion/1  fails.  _R_e_a_s_o_n  is
    unified with either  fail if _G_o_a_l simply failed or an exception call
    otherwise.   If this hook fails, the default behaviour is activated.
    If  the hooks  throws an exception  it will  be propagated into  the
    caller of assertion/1.


1133..1122 lliibbrraarryy((eerrrroorr))::  EErrrroorr ggeenneerraattiinngg ssuuppppoorrtt

    aauutthhoorr
         - Jan Wielemaker
         - Richard O'Keefe
         - Ulrich Neumerkel

    SSeeee aallssoo
         - library(debug) and library(prolog_stack).
         - print_message/2 is used to print (uncaught) error terms.

This  module  provides  predicates  to  simplify  error  generation  and
checking.     It's  implementation is  based  on  a  discussion  on  the
SWI-Prolog  mailinglist  on best  practices  in  error handling.     The
utility predicate  must_be/2 provides simple  run-time type  validation.
The *_error predicates are  simple wrappers  around throw/1 to  simplify
throwing the most common ISO error terms.


ttyyppee__eerrrroorr((_+_T_y_p_e_, _+_T_e_r_m))
    Tell the user that  _T_e_r_m is not of the expected _T_y_p_e.  This error is
    closely  related to  domain_error/2 because the  notion of types  is
    not  really set in  stone in  Prolog.   We introduce the  difference
    using a simple example.

    Suppose  an argument must be a non-negative integer.  If  the actual
    argument  is not  an integer,  this is  a _t_y_p_e___e_r_r_o_r.   If  it is  a
    negative integer, it is a _d_o_m_a_i_n___e_r_r_o_r.

    Typical  borderline cases are predicates accepting a  compound term,
    e.g.,   point(X,Y). One  could  argue  that  the  basic  type  is  a
    compound-term  and any other compound term is a domain error.   Most
    Prolog  programmers  consider  each compound  as  a type  and  would
    consider a compoint that is not point(_,_) a _t_y_p_e___e_r_r_o_r.


ddoommaaiinn__eerrrroorr((_+_T_y_p_e_, _+_T_e_r_m))
    The argument is of  the proper type, but has a value that is outside
    the  supported  values.    See  type_error/2 for  a  more  elaborate
    discussion of the distinction between type- and domain-errors.


eexxiisstteennccee__eerrrroorr((_+_T_y_p_e_, _+_T_e_r_m))
    _T_e_r_m  is of the  correct type  and correct domain,  but there is  no
    existing (external) resource that is represented by it.


eexxiisstteennccee__eerrrroorr((_+_T_y_p_e_, _+_T_e_r_m_, _+_S_e_t))
    _T_e_r_m  is  of the  correct  type and  correct  domain, but  there  is
    no  existing (external) resource  that is represented  by it in  the
    provided set.

         CCoommppaattiibbiilliittyy This error is not in ISO.


ppeerrmmiissssiioonn__eerrrroorr((_+_A_c_t_i_o_n_, _+_T_y_p_e_, _+_T_e_r_m))
    It  is not allowed to perform _A_c_t_i_o_n  on the object _T_e_r_m that  is of
    the given _T_y_p_e.


iinnssttaannttiiaattiioonn__eerrrroorr((_+_T_e_r_m))
    An  argument is under-instantiated.  I.e.   it is not  acceptable as
    it  is, but  if some variables  are bound  to appropriate values  it
    would be acceptable.

    ___________________________________________________________Arguments_
     _T_e_r_m  is the term that needs (further)  instantiation.
           Unfortunately, the ISO error does not allow  for
           passing  this  term along  with the  error,  but
           we  pass it to this predicate for  documentation
           purposes and to allow for future enhancement.


uunniinnssttaannttiiaattiioonn__eerrrroorr((_+_T_e_r_m))
    An  argument is over-instantiated.   This  error is used for  output
    arguments  whose value cannot  be known upfront.   For example,  the
    goal open(File, read, input)  cannot succeed because the system will
    allocate  a new  unique  stream handle  that will  never unify  with
    input.


rreepprreesseennttaattiioonn__eerrrroorr((_+_R_e_a_s_o_n))
    A  representation error  indicates a limitation  of the  implementa-
    tion.   SWI-Prolog has no such limits that are not covered  by other
    errors,  but an example of a representation error in  another Prolog
    implementation  could be an attempt to  create a term with an  arity
    higher than supported by the system.


ssyynnttaaxx__eerrrroorr((_+_C_u_l_p_r_i_t))
    A text has invalid syntax.  The error is described by _C_u_l_p_r_i_t.

         TToo bbee ddoonnee Deal  with proper  description of  the location
             of  the  error.     For  short  texts,  we  allow  for
             Type(Text),  meaning Text is  not a valid Type.   E.g.
             syntax_error(number('1a'))  means  that  1a  is not  a
             valid number.


rreessoouurrccee__eerrrroorr((_+_C_u_l_p_r_i_t))
    A goal cannot be completed due to lack of resources.


mmuusstt__bbee((_+_T_y_p_e_, _@_T_e_r_m))                                              _[_d_e_t_]
    True  if _T_e_r_m  satisfies the  type constraints  for _T_y_p_e.    Defined
    types   are  atom,  atomic,  between,   boolean,  callable,   chars,
    codes,   text,   compound,   constant,   float,   integer,   nonneg,
    positive_integer,  negative_integer,  nonvar, number,  oneof,  list,
    list_or_partial_list,  symbol,  var,  rational, encoding,  dict  and
    string.

    Most of these  types are defined by an arity-1 built-in predicate of
    the same name.  Below is a brief definition of the other types.

         ______________________________________________________________________________________________________
         | acyclic                |Acyclic term (tree); see acyclic_term/1                                     |
         | any                    |                                                                           |
         | between(FloatL,FloatU) |Number [FloatL..FloatU]                                                     |

         | between(IntL,IntU)     |Integer [IntL..IntU]                                                        |
         | boolean                |One of true or false                                                        |
         | char                   |Atom of length 1                                                            |
         | chars                  |Proper list of 1-character atoms                                            |
         | code                   |Representation Unicode code point                                           |
         | codes                  |Proper list of Unicode character codes                                      |
         | constant               |Same as atomic                                                              |

         | cyclic                 |Cyclic term (rational tree); see cyclic_term/1                              |
         | dict                   |A dictionary term; see is_dict/1                                            |
         | encoding               |Valid name for a character encoding; see current_encoding/1                 |
         | list                   |A (non-open) list; see is_list/1                                            |
         | negative_integer       I|nteger < 0                                                                |
         | nonneg                 |Integer >= 0                                                                |
         | oneof(L)               |Ground term that is member of L                                             |
         | positive_integer       I|nteger > 0                                                                |

         | proper_list            S|ame as list                                                                |
         | list(Type)             |Proper list with elements of _T_y_p_e                                           _|
         _| list_or_partial_list   A |list or an open list (ending in a variable); see is_list_or_partial_list/1|
         | stream                 |A stream name or valid stream handle; see is_stream/1                       |
         | symbol                 |Same as atom                                                                |
         |_text___________________|One_of_atom,_string,_chars_or_codes_________________________________________|

    Note:   The Windows version  can only represent Unicode code  points
    up  to 2^16-1.  Higher  values cause a representation error on  most
    text handling predicates.

         tthhrroowwss instantiation_error  if   _T_e_r_m   is  insufficiently
             instantiated  and  type_error(Type, Term)  if _T_e_r_m  is
             not of _T_y_p_e.


iiss__ooff__ttyyppee((_+_T_y_p_e_, _@_T_e_r_m))                                       _[_s_e_m_i_d_e_t_]
    True if _T_e_r_m satisfies _T_y_p_e.


hhaass__ttyyppee((_+_T_y_p_e_, _@_T_e_r_m))                               _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    True if _T_e_r_m satisfies _T_y_p_e.


ccuurrrreenntt__ttyyppee((_?_T_y_p_e_, _@_V_a_r_, _-_B_o_d_y))                                _[_n_o_n_d_e_t_]
    True  when _T_y_p_e is a currently  defined type and _V_a_r satisfies  _T_y_p_e
    of the body term _B_o_d_y succeeds.


1133..1133 lliibbrraarryy((ggeennssyymm))::  GGeenneerraattee uunniiqquuee iiddeennttiiffiieerrss

Gensym  (GGeennerate SSyymmbols)  is  an  old library  for  generating  unique
symbols (atoms).    Such symbols are  generated from  a base atom  which
gets a sequence number  appended.  Of course there is no  guarantee that
`catch22'  is not  an already  defined atom  and therefore  one must  be
aware these atoms are only unique in an isolated context.

The SWI-Prolog gensym library is thread-safe.  The  sequence numbers are
global over  all threads and therefore  generated atoms are unique  over
all threads.


ggeennssyymm((_+_B_a_s_e_, _-_U_n_i_q_u_e))
    Generate  a unique  atom from base  _B_a_s_e and  unify it with  _U_n_i_q_u_e.
    _B_a_s_e  should be an  atom.  The  first call will  return <_b_a_s_e>1,  the
    next <_b_a_s_e>2, etc.  Note that this is no guarantee  that the atom is
    unique in the system.


rreesseett__ggeennssyymm((_+_B_a_s_e))
    Restart  generation of identifiers  from _B_a_s_e  at <_B_a_s_e>1.   Used to
    make  sure a program produces  the same results on subsequent  runs.
    Use with care.


rreesseett__ggeennssyymm
    Reset  gensym for all registered keys.  This predicate  is available
    for  compatibility only.  New code is strongly advised to  avoid the
    use  of reset_gensym or at least to reset only the keys  used by your
    program to avoid unexpected side effects on other components.


1133..1144 lliibbrraarryy((iioossttrreeaamm))::  UUttiilliittiieess ttoo ddeeaall wwiitthh ssttrreeaammss

    SSeeee aallssoo  library(archive),   library(process),  library(zlib),
         library(http/http_stream)

This  library  contains  utilities  that  deal  with  streams,   notably
originating from non-built-in  sources such as URLs, archives,  windows,
processes, etc.

The predicate open_any/5 acts as a _b_r_o_k_e_r between applications  that can
process data from  a stream and libraries  that can create streams  from
diverse sources.    Without this predicate,  processing data  inevitally
follows the pattern below.   As _c_a_l_l___s_o_m_e___o_p_e_n___v_a_r_i_a_t_i_o_n can  be anything,
this blocks us from writing predicates such  as load_xml(From, DOM) that
can operate on arbitrary input sources.

________________________________________________________________________|                                                                        |

|setup_call_cleanup(                                                     |
|    call_some_open_variation(Spec, In),                                 |
|    process(In),                                                        |
||___close(In)).________________________________________________________ ||

Libraries   that    can   open    streams   can    install   the    hook
iostream:open_hook/6  to  make  their  functionality  available  through
open_any/5.


ooppeenn__aannyy((_+_S_p_e_c_i_f_i_c_a_t_i_o_n_, _+_M_o_d_e_, _-_S_t_r_e_a_m_, _-_C_l_o_s_e_, _+_O_p_t_i_o_n_s))
    Establish  a stream from _S_p_e_c_i_f_i_c_a_t_i_o_n  that should be closed  using
    _C_l_o_s_e,   which  can either  be  called  or  passed  to  close_any/1.
    _O_p_t_i_o_n_s processed:

    eennccooddiinngg((_E_n_c))
         Set stream to encoding _E_n_c.

    Without  loaded  plugins,  the  open_any/5 processes  the  following
    values for  _S_p_e_c_i_f_i_c_a_t_i_o_n.  If no rule matches, open_any/5 processes
    _S_p_e_c_i_f_i_c_a_t_i_o_n as file(Specification).

    _S_t_r_e_a_m
         A plain  stream  handle.   Possisible  post-processing  options
         such  as encoding  are  applied.    _C_l_o_s_e  does _n_o_t  close  the
         stream, but resets other side-effects such as the encoding.

    ssttrreeaamm((_S_t_r_e_a_m))
         Same as a plain _S_t_r_e_a_m.

    _F_i_l_e_U_R_L
         If _S_p_e_c_i_f_i_c_a_t_i_o_n is  of the form  =file://...=, the pointed  to
         file is  opened  using open/4.    Requires  library(uri) to  be
         installed.

    ffiillee((_P_a_t_h))
         Explicitly open the file _P_a_t_h.  _P_a_t_h can be  an _P_a_t_h(File) term
         as accepted by absolute_file_name/3.

    ssttrriinngg((_S_t_r_i_n_g))
         Open a Prolog string,  atom, list of characters or codes  as an
         _i_n_p_u_t stream.

    The  typical  usage  scenario is  given  in the  code  below,  where
    <process> processes the input.

    ____________________________________________________________________|                                                                    |
    | setup_call_cleanup(                                                |

    |     open_any(Spec, read, In, Close, Options),                      |
    |     <process>(In),                                                 |
    ||____Close)._______________________________________________________ ||

    Currently, the following libraries extend this predicate:

    lliibbrraarryy((_h_t_t_p_/_h_t_t_p___o_p_e_n))
         Adds support for URLs using the http and https schemes.


cclloossee__aannyy((_+_G_o_a_l))
    Execute  the  _C_l_o_s_e closure  returned by  open_any/5.    The  closure
    can  also be called directly.   Using close_any/1 can be  considered
    better style and enhances tractability of the source code.


ooppeenn__hhooookk((_+_S_p_e_c_, _+_M_o_d_e_, _-_S_t_r_e_a_m_, _-_C_l_o_s_e_, _+_O_p_t_i_o_n_s_0_, _-_O_p_t_i_o_n_s))_[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Open _S_p_e_c in _M_o_d_e, producing _S_t_r_e_a_m.

    ___________________________________________________________Arguments_
     _C_l_o_s_e     is  unified to  a goal  that must  be called  to
               undo  the  side-effects  of  the action,   e.g.,
               typically the term close(Stream)
     _O_p_t_i_o_n_s_0  are the options passed to open_any/5
     _O_p_t_i_o_n_s   are  passed to the post processing filters  that
               may be installed by open_any/5.


1133..1155 lliibbrraarryy((lliissttss))::  LLiisstt MMaanniippuullaattiioonn

    CCoommppaattiibbiilliittyy  Virtually     every     Prolog    system     has
         library(lists),   but  the  set   of  provided  predicates
         is diverse.   There is  a fair agreement  on the semantics
         of most of  these predicates, although  error handling may
         vary.

This  library  provides  commonly accepted  basic  predicates  for  list
manipulation  in   the  Prolog   community.      Some  additional   list
manipulations are built-in.  See e.g., memberchk/2, length/2.

The implementation of  this library is copied  from many places.   These
include:  "The Craft  of Prolog", the DEC-10 Prolog  library (LISTRO.PL)
and the YAP lists  library.  Some predicates are reimplemented  based on
their specification by Quintus and SICStus.


mmeemmbbeerr((_?_E_l_e_m_, _?_L_i_s_t))
    True  if  _E_l_e_m is  a member  of  _L_i_s_t.   The  SWI-Prolog  definition
    differs  from the classical  one.   Our definition avoids  unpacking
    each  list  element  twice  and provides  determinism  on  the  last
    element.  E.g.  this is deterministic:

    ____________________________________________________________________|                                                                    |
    ||____member(X,_[One])._____________________________________________ ||

         aauutthhoorr Gertjan van Noord


aappppeenndd((_?_L_i_s_t_1_, _?_L_i_s_t_2_, _?_L_i_s_t_1_A_n_d_L_i_s_t_2))
    _L_i_s_t_1_A_n_d_L_i_s_t_2 is the concatenation of _L_i_s_t_1 and _L_i_s_t_2


aappppeenndd((_+_L_i_s_t_O_f_L_i_s_t_s_, _?_L_i_s_t))
    Concatenate  a list of lists.   Is true if _L_i_s_t_O_f_L_i_s_t_s is a  list of
    lists, and _L_i_s_t is the concatenation of these lists.

    ___________________________________________________________Arguments_
     _L_i_s_t_O_f_L_i_s_t_s  must be a list of _p_o_s_s_i_b_l_y partial lists


pprreeffiixx((_?_P_a_r_t_, _?_W_h_o_l_e))
    True iff _P_a_r_t is  a leading substring of _W_h_o_l_e.  This is the same as
    append(Part, _, Whole).


sseelleecctt((_?_E_l_e_m_, _?_L_i_s_t_1_, _?_L_i_s_t_2))
    Is true when _L_i_s_t_1, with _E_l_e_m removed, results in _L_i_s_t_2.


sseelleeccttcchhkk((_+_E_l_e_m_, _+_L_i_s_t_, _-_R_e_s_t))                                _[_s_e_m_i_d_e_t_]
    Semi-deterministic  removal of  first element in  _L_i_s_t that  unifies
    with _E_l_e_m.


sseelleecctt((_?_X_, _?_X_L_i_s_t_, _?_Y_, _?_Y_L_i_s_t))                                 _[_n_o_n_d_e_t_]
    Select  from  two lists  at the  same positon.    True  if _X_L_i_s_t  is
    unifiable  with _Y_L_i_s_t apart  a single element  at the same  position
    that  is unified with  _X in _X_L_i_s_t and  with _Y in  _Y_L_i_s_t.  A  typical
    use  for  this predicate  is  to _r_e_p_l_a_c_e  an  element, as  shown  in
    the  example below.    All possible substitutions  are performed  on
    backtracking.

    ____________________________________________________________________|                                                                    |
    | ?- select(b, [a,b,c,b], 2, X).                                     |

    | X = [a, 2, c, b] ;                                                 |
    | X = [a, b, c, 2] ;                                                 |
    ||false.____________________________________________________________ ||

         SSeeee aallssoo selectchk/4 provides a semidet version.


sseelleeccttcchhkk((_?_X_, _?_X_L_i_s_t_, _?_Y_, _?_Y_L_i_s_t))                             _[_s_e_m_i_d_e_t_]
    Semi-deterministic version of select/4.


nneexxttttoo((_?_X_, _?_Y_, _?_L_i_s_t))
    True if _Y directly follows _X in _L_i_s_t.


ddeelleettee((_+_L_i_s_t_1_, _@_E_l_e_m_, _-_L_i_s_t_2))                                     _[_d_e_t_]
    Delete  matching elements from a  list.  True  when _L_i_s_t_2 is a  list
    with all elements  from _L_i_s_t_1 except for those that unify with _E_l_e_m.
    Matching  _E_l_e_m with  elements of _L_i_s_t_1  is uses \+ Elem \= H,  which
    implies that _E_l_e_m is not changed.

         SSeeee aallssoo select/3, subtract/3.

         ddeepprreeccaatteedd There  are  too many  ways in  which  one might
             want  to delete  elements from a  list to  justify the
             name.     Think  of  matching  (= vs.     ==),  delete
             first/all, be deterministic or not.


nntthh00((_?_I_n_d_e_x_, _?_L_i_s_t_, _?_E_l_e_m))
    True when _E_l_e_m is  the _I_n_d_e_x'th element of _L_i_s_t.  Counting starts at
    0.

         EErrrroorrss type_error(integer, Index)   if  _I_n_d_e_x  is  not  an
             integer or unbound.

         SSeeee aallssoo nth1/3.


nntthh11((_?_I_n_d_e_x_, _?_L_i_s_t_, _?_E_l_e_m))
    Is true when _E_l_e_m  is the _I_n_d_e_x'th element of _L_i_s_t.  Counting starts
    at 1.

         SSeeee aallssoo nth0/3.


nntthh00((_?_N_, _?_L_i_s_t_, _?_E_l_e_m_, _?_R_e_s_t))                                     _[_d_e_t_]
    Select/insert  element  at  index.    True  when _E_l_e_m  is  the  _N'th
    (0-based)  element  of _L_i_s_t  and _R_e_s_t  is the  remainder  (as in  by
    select/3) of _L_i_s_t.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- nth0(I, [a,b,c], E, R).                                         |

    | I = 0, E = a, R = [b, c] ;                                         |
    | I = 1, E = b, R = [a, c] ;                                         |
    | I = 2, E = c, R = [a, b] ;                                         |
    ||false.____________________________________________________________ ||

    ____________________________________________________________________|                                                                    |

    | ?- nth0(1, L, a1, [a,b]).                                          |
    ||L_=_[a,_a1,_b].___________________________________________________ ||


nntthh11((_?_N_, _?_L_i_s_t_, _?_E_l_e_m_, _?_R_e_s_t))                                     _[_d_e_t_]
    As nth0/4, but counting starts at 1.


llaasstt((_?_L_i_s_t_, _?_L_a_s_t))
    Succeeds  when _L_a_s_t is the last element of _L_i_s_t.  This  predicate is
    semidet if _L_i_s_t is a list and multi if _L_i_s_t is a partial list.

         CCoommppaattiibbiilliittyy There   is  no  de-facto  standard  for  the
             argument  order of  last/2.   Be careful  when porting
             code  or  use  append(_, [Last], List)  as a  portable
             alternative.


pprrooppeerr__lleennggtthh((_@_L_i_s_t_, _-_L_e_n_g_t_h))                                  _[_s_e_m_i_d_e_t_]
    True when _L_e_n_g_t_h is  the number of elements in the proper list _L_i_s_t.
    This is equivalent to

    ____________________________________________________________________|                                                                    |
    | proper_length(List, Length) :-                                     |

    |       is_list(List),                                               |
    ||______length(List,_Length)._______________________________________ ||


ssaammee__lleennggtthh((_?_L_i_s_t_1_, _?_L_i_s_t_2))
    Is  true when  _L_i_s_t_1 and  _L_i_s_t_2 are lists  with the  same number  of
    elements.   The  predicate is deterministic if  at least one of  the
    arguments  is  a proper  list.    It  is non-deterministic  if  both
    arguments are partial lists.

         SSeeee aallssoo length/2


rreevveerrssee((_?_L_i_s_t_1_, _?_L_i_s_t_2))
    Is true when the  elements of _L_i_s_t_2 are in reverse order compared to
    _L_i_s_t_1.


ppeerrmmuuttaattiioonn((_?_X_s_, _?_Y_s))                                          _[_n_o_n_d_e_t_]
    True  when  _X_s  is  a  permutation  of _Y_s.     This  can  solve  for
    _Y_s  given  _X_s  or  _X_s  given  _Y_s,   or  even  enumerate  _X_s  and  _Y_s
    together.     The  predicate  permutation/2  is  primarily  intended
    to  generate  permutations.    Note  that a  list  of length  N  has
    N!  permutations,   and  unbounded  permutation  generation  becomes
    prohibitively  expensive,  even  for rather  short  lists  (10!    =
    3,628,800).

    If both _X_s and  _Y_s are provided and both lists have equal length the
    order  is |_X_s|^2.  Simply testing whether _X_s is a permutation  of _Y_s
    can  be achieved  in order  log(|_X_s|) using  msort/2 as  illustrated
    below with the semidet predicate is_permutation/2:

    ____________________________________________________________________|                                                                    |
    | is_permutation(Xs, Ys) :-                                          |

    |   msort(Xs, Sorted),                                               |
    ||__msort(Ys,_Sorted).______________________________________________ ||

    The  example below illustrates that _X_s and _Y_s being proper  lists is
    not a sufficient condition to use the above replacement.

    ____________________________________________________________________|                                                                    |
    | ?- permutation([1,2], [X,Y]).                                      |
    | X = 1, Y = 2 ;                                                     |
    | X = 2, Y = 1 ;                                                     |
    ||false.____________________________________________________________ ||

         EErrrroorrss type_error(list, Arg)  if either argument  is not a
             proper or partial list.


ffllaatttteenn((_+_N_e_s_t_e_d_L_i_s_t_, _-_F_l_a_t_L_i_s_t))                                   _[_d_e_t_]
    Is  true if _F_l_a_t_L_i_s_t  is a non-nested version  of _N_e_s_t_e_d_L_i_s_t.   Note
    that  empty lists  are removed.   In standard  Prolog, this  implies
    that  the atom '[]' is  removed too.  In  SWI7, [] is distinct  from
    '[]'.

    Ending  up  needing flatten/2  often  indicates, like  append/3  for
    appending  two lists, a bad design.   Efficient code that  generates
    lists  from generated small lists  must use difference lists,  often
    possible through grammar rules for optimal readability.

         SSeeee aallssoo append/2


mmaaxx__mmeemmbbeerr((_-_M_a_x_, _+_L_i_s_t))                                        _[_s_e_m_i_d_e_t_]
    True when _M_a_x is  the largest member in the standard order of terms.
    Fails if _L_i_s_t is empty.

         SSeeee aallssoo
             - compare/3
             - max_list/2 for the maximum of a list of numbers.


mmiinn__mmeemmbbeerr((_-_M_i_n_, _+_L_i_s_t))                                        _[_s_e_m_i_d_e_t_]
    True  when  _M_i_n is  the smallest  member in  the  standard order  of
    terms.  Fails if _L_i_s_t is empty.

         SSeeee aallssoo
             - compare/3
             - min_list/2 for the minimum of a list of numbers.


ssuumm__lliisstt((_+_L_i_s_t_, _-_S_u_m))                                              _[_d_e_t_]
    _S_u_m is the result of adding all numbers in _L_i_s_t.


mmaaxx__lliisstt((_+_L_i_s_t_:_l_i_s_t_(_n_u_m_b_e_r_)_, _-_M_a_x_:_n_u_m_b_e_r))                      _[_s_e_m_i_d_e_t_]
    True if _M_a_x is the largest number in _L_i_s_t.  Fails if _L_i_s_t is empty.

         SSeeee aallssoo max_member/2.


mmiinn__lliisstt((_+_L_i_s_t_:_l_i_s_t_(_n_u_m_b_e_r_)_, _-_M_i_n_:_n_u_m_b_e_r))                      _[_s_e_m_i_d_e_t_]
    True  if _M_i_n  is the  smallest number  in _L_i_s_t.   Fails  if _L_i_s_t  is
    empty.

         SSeeee aallssoo min_member/2.


nnuummlliisstt((_+_L_o_w_, _+_H_i_g_h_, _-_L_i_s_t))                                   _[_s_e_m_i_d_e_t_]
    _L_i_s_t is a list [_L_o_w, _L_o_w+1, ...  _H_i_g_h].  Fails if _H_i_g_h < _L_o_w.

         EErrrroorrss
             - type_error(integer, Low)
             - type_error(integer, High)


iiss__sseett((_@_S_e_t))                                                   _[_s_e_m_i_d_e_t_]
    True  if _S_e_t is  a proper list without  duplicates.  Equivalence  is
    based  on  ==/2.   The  implementation  uses sort/2,  which  implies
    that  the  complexity is  N*log(N)  and the  predicate may  cause  a
    resource-error.  There are no other error conditions.


lliisstt__ttoo__sseett((_+_L_i_s_t_, _?_S_e_t))                                           _[_d_e_t_]
    True when _S_e_t has  the same elements as _L_i_s_t in the same order.  The
    left-most copy of  duplicate elements is retained.  _L_i_s_t may contain
    variables.   Elements _E_1 and _E_2 are considered duplicates iff  _E_1 ==
    _E_2 holds.  The complexity of the implementation is N*log(N).

         EErrrroorrss _L_i_s_t is type-checked.

         SSeeee aallssoo sort/2  can  be used  to create  an  ordered set.
             Many  set  operations  on  ordered  sets  are order  N
             rather  than order N**2.   The list_to_set/2 predicate
             is  more expensive  than  sort/2 because  it involves,
             two sorts and a linear scan.

         CCoommppaattiibbiilliittyy Up   to  version  6.3.11,  list_to_set/2 had
             complexity N**2 and equality was tested using =/2.


iinntteerrsseeccttiioonn((_+_S_e_t_1_, _+_S_e_t_2_, _-_S_e_t_3))                                 _[_d_e_t_]
    True  if _S_e_t_3 unifies with the intersection  of _S_e_t_1 and _S_e_t_2.   The
    complexity of this predicate  is |_S_e_t_1|*|_S_e_t_2|.  A _s_e_t is defined to
    be  an unordered list without  duplicates.  Elements are  considered
    duplicates if they can be unified.

         SSeeee aallssoo ord_intersection/3.


uunniioonn((_+_S_e_t_1_, _+_S_e_t_2_, _-_S_e_t_3))                                        _[_d_e_t_]
    True  if _S_e_t_3 unifies  with the  union of the  lists _S_e_t_1 and  _S_e_t_2.
    The  complexity  of this  predicate  is |_S_e_t_1|*|_S_e_t_2|.    A  _s_e_t  is
    defined  to be an unordered list  without duplicates.  Elements  are
    considered duplicates if they can be unified.

         SSeeee aallssoo ord_union/3


ssuubbsseett((_+_S_u_b_S_e_t_, _+_S_e_t))                                         _[_s_e_m_i_d_e_t_]
    True  if all elements of _S_u_b_S_e_t belong  to _S_e_t as well.   Membership
    test  is based on  memberchk/2.   The complexity is  |_S_u_b_S_e_t|*|_S_e_t|.
    A  _s_e_t  is  defined to  be  an  unordered list  without  duplicates.
    Elements are considered duplicates if they can be unified.

         SSeeee aallssoo ord_subset/2.


ssuubbttrraacctt((_+_S_e_t_, _+_D_e_l_e_t_e_, _-_R_e_s_u_l_t))                                  _[_d_e_t_]
    _D_e_l_e_t_e  all elements  in  _D_e_l_e_t_e from  _S_e_t.   Deletion  is based  on
    unification  using memberchk/2.   The complexity is  |_D_e_l_e_t_e|*|_S_e_t|.
    A  _s_e_t  is  defined to  be  an  unordered list  without  duplicates.
    Elements are considered duplicates if they can be unified.

         SSeeee aallssoo ord_subtract/3.


1133..1166 lliibbrraarryy((mmaaiinn))::  PPrroovviiddee eennttrryy ppooiinntt ffoorr ssccrriippttss

    SSeeee aallssoo  XPCE users  should have a  look at library(pce_main),
         which  starts  the  GUI  and processes  events  until  all
         windows have gone.

This library is  intended for supporting PrologScript on Unix  using the
#! magic  sequence for  scripts using  commandline options.   The  entry
point main/0 calls the user-supplied predicate main/1 passing  a list of
commandline options.   Below is `echo' in Prolog  (adjust /usr/bin/swipl
to where SWI-Prolog is installed)

________________________________________________________________________|                                                                        |

|#!/usr/bin/env swipl                                                    |
|                                                                        |
|:- initialization(main, main).                                          |
|                                                                        |
|main(Argv) :-                                                           |
|        echo(Argv).                                                     |
|                                                                        |

|echo([]) :- nl.                                                         |
|echo([Last]) :- !,                                                      |
|        write(Last), nl.                                                |
|echo([H|T]) :-                                                          |
|        write(H), write(' '),                                           |
||_______echo(T)._______________________________________________________ ||


mmaaiinn
    Call  main/1  using  the  passed command-line  arguments.     Before
    calling  main/1 this predicate installs a signal handler  for SIGINT
    (Control-C) that terminates the process with status 1.


aarrggvv__ooppttiioonnss((_+_A_r_g_v_, _-_R_e_s_t_A_r_g_v_, _-_O_p_t_i_o_n_s))                           _[_d_e_t_]
    Generic  transformation of  long commandline  arguments to  options.
    Each  --Name=Value is  mapped to Name(Value).    Each plain name  is
    mapped  to Name(true), unless  Name starts with  no-, in which  case
    the  option is  mapped to Name(false).    Numeric option values  are
    mapped to Prolog numbers.

         SSeeee aallssoo library(optparse)   provides   a   more  involved
             option   library,   providing  both  short   and  long
             options,  help and error handling.   This predicate is
             more for quick-and-dirty scripts.


1133..1177 lliibbrraarryy((nnbb__sseett))::  NNoonn--bbaacckkttrraacckkaabbllee sseett

The  library  nb_set  defines  _n_o_n_-_b_a_c_k_t_r_a_c_k_a_b_l_e  _s_e_t_s,  implemented  as
binary  trees.     The  sets  are  represented  as  compound  terms  and
manipulated  using  nb_setarg/3.     Non-backtrackable  manipulation  of
datastructures  is   not  supported   by  a  large   number  of   Prolog
implementations, but it has several advantages over  using the database.
It  produces less  garbage,  is thread-safe,  reentrant and  deals  with
exceptions without leaking data.

Similar to  the assoc library, keys  can be any  Prolog term, but it  is
not allowed to instantiate or modify a term.

One of  the ways to  use this  library is to  generate unique values  on
backtracking  _w_i_t_h_o_u_t generating  _a_l_l solutions  first,  for example  to
act as  a filter between  a generator producing  many duplicates and  an
expensive test routine, as outlined below:

________________________________________________________________________|                                                                        |
|generate_and_test(Solution) :-                                          |

|        empty_nb_set(Set),                                              |
|        generate(Solution),                                             |
|        add_nb_set(Solution, Set, true),                                |
||_______test(Solution).________________________________________________ ||


eemmppttyy__nnbb__sseett((_?_S_e_t))
    True if _S_e_t is a non-backtrackable empty set.


aadddd__nnbb__sseett((_+_K_e_y_, _!_S_e_t))
    Add  _K_e_y to _S_e_t.   If _K_e_y  is already a member  of _S_e_t, add_nb_set/3
    succeeds without modifying _S_e_t.


aadddd__nnbb__sseett((_+_K_e_y_, _!_S_e_t_, _?_N_e_w))
    If  _K_e_y is not in _S_e_t  and _N_e_w is unified  to true, _K_e_y is added  to
    _S_e_t.   If _K_e_y is  in _S_e_t, _N_e_w is unified to  false.  It can  be used
    for many purposes:

             add_nb_set(+, +, false) Test membership
             add_nb_set(+, +, true)  Succeed only if new member
             add_nb_set(+, +, Var)   Succeed, binding _V_a_r


ggeenn__nnbb__sseett((_+_S_e_t_, _-_K_e_y))
    Generate  all members of _S_e_t  on backtracking in the standard  order
    of terms.  To test membership, use add_nb_set/3.


ssiizzee__nnbb__sseett((_+_S_e_t_, _-_S_i_z_e))
    Unify _S_i_z_e with the number of elements in _S_e_t.


nnbb__sseett__ttoo__lliisstt((_+_S_e_t_, _-_L_i_s_t))
    Unify _L_i_s_t with a  list of all elements in _S_e_t in the standard order
    of terms (i.e., an _o_r_d_e_r_e_d _l_i_s_t).


1133..1188 lliibbrraarryy((wwwwww__bbrroowwsseerr))::  AAccttiivvaattiinngg yyoouurr WWeebb--bbrroowwsseerr

This library deals with the very system-dependent task of  opening a web
page in a browser.  See also url and the HTTP package.


wwwwww__ooppeenn__uurrll((_+_U_R_L))
    Open  _U_R_L in  an external web  browser.   The reason  to place  this
    in  the library  is  to centralise  the maintenance  on this  highly
    platform-  and browser-specific task.  It distinguishes  between the
    following cases:

      o  _M_S_-_W_i_n_d_o_w_s
         If it detects MS-Windows  it uses win_shell/2 to open the  _U_R_L.
         The behaviour  and browser  started depends on  the version  of
         Windows  and Windows-shell  configuration,  but in  general  it
         should be the behaviour expected by the user.

      o  _O_t_h_e_r _p_l_a_t_f_o_r_m_s
         On  other platforms  it  tests  the environment  variable  (see
         getenv/2) named BROWSER  or uses netscape  if this variable  is
         not  set.    If the  browser  is  either mozilla  or  netscape,
         www_open_url/1 first tries to  open a new  window on a  running
         browser using the  -remote option of Netscape.   If this  fails
         or the  browser is not  mozilla or  netscape the system  simply
         passes the URL as first argument to the program.


1133..1199 lliibbrraarryy((ooppttiioonn))::  OOppttiioonn lliisstt pprroocceessssiinngg

    SSeeee aallssoo
         - library(record)
         - Option processing capabilities may be declared using the
         directive predicate_options/3.

    TToo bbee ddoonnee  We should consider putting many options in an assoc
         or record with appropriate preprocessing to achieve better
         performance.

The  library(option)  provides  some  utilities  for  processing  option
lists.     Option  lists  are  commonly  used  as   an  alternative  for
many  arguments.    Examples  of  built-in  predicates  are  open/4  and
write_term/3.  Naming the  arguments results in more readable code,  and
the list  nature makes it  easy to extend the  list of options  accepted
by a  predicate.   Option lists come  in two styles,  both of which  are
handled by this library.

NNaammee((VVaalluuee))  This is the preferred style.

NNaammee == VVaalluuee  This is often used, but deprecated.

Processing options inside  time-critical code (loops) can cause  serious
overhead.  One  possibility is to define a record  using library(record)
and initialise  this using  make_<record>/2.   In  addition to providing
good  performance,   this  also   provides  type-checking  and   central
declaration of defaults.

________________________________________________________________________|                                                                        |
|:- record atts(width:integer=100, shape:oneof([box,circle])=box).       |
|                                                                        |
|process(Data, Options) :-                                               |
|        make_atts(Options, Attributes),                                 |
|        action(Data, Attributes).                                       |

|                                                                        |
|action(Data, Attributes) :-                                             |
|        atts_shape(Attributes, Shape),                                  |
||_______...____________________________________________________________ ||

Options  typically  have  exactly  one  argument.     The  library  does
support options  with 0  or more  than one argument  with the  following
restrictions:

  o The  predicate   option/3  and  select_option/4,   involving  default
    are   meaningless.      They  perform  an   arg(1, Option, Default),
    causing  failure  without  arguments  and  filling  only  the  first
    option-argument otherwise.

  o meta_options/3 can only qualify options with exactly one argument.


ooppttiioonn((_?_O_p_t_i_o_n_, _+_O_p_t_i_o_n_L_i_s_t_, _+_D_e_f_a_u_l_t))                        _[_s_e_m_i_d_e_t_]
    Get  an _O_p_t_i_o_n from _O_p_t_i_o_n_L_i_s_t.   _O_p_t_i_o_n_L_i_s_t can use the  Name=Value
    as well as the Name(Value) convention.

    ___________________________________________________________Arguments_
     _O_p_t_i_o_n  Term of the form Name(?Value).


ooppttiioonn((_?_O_p_t_i_o_n_, _+_O_p_t_i_o_n_L_i_s_t))                                  _[_s_e_m_i_d_e_t_]
    Get  an _O_p_t_i_o_n from _O_p_t_i_o_n_L_i_s_t.   _O_p_t_i_o_n_L_i_s_t can use the  Name=Value
    as  well  as the  Name(Value) convention.    Fails  silently if  the
    option does not appear in _O_p_t_i_o_n_L_i_s_t.

    ___________________________________________________________Arguments_
     _O_p_t_i_o_n  Term of the form Name(?Value).


sseelleecctt__ooppttiioonn((_?_O_p_t_i_o_n_, _+_O_p_t_i_o_n_s_, _-_R_e_s_t_O_p_t_i_o_n_s))                 _[_s_e_m_i_d_e_t_]
    Get  and remove _O_p_t_i_o_n from an  option list.  As option/2,  removing
    the matching option  from _O_p_t_i_o_n_s and unifying the remaining options
    with _R_e_s_t_O_p_t_i_o_n_s.


sseelleecctt__ooppttiioonn((_?_O_p_t_i_o_n_, _+_O_p_t_i_o_n_s_, _-_R_e_s_t_O_p_t_i_o_n_s_, _+_D_e_f_a_u_l_t))           _[_d_e_t_]
    Get  and remove _O_p_t_i_o_n with default value.   As select_option/3, but
    if  _O_p_t_i_o_n is not in _O_p_t_i_o_n_s, its value is unified with  _D_e_f_a_u_l_t and
    _R_e_s_t_O_p_t_i_o_n_s with _O_p_t_i_o_n_s.


mmeerrggee__ooppttiioonnss((_+_N_e_w_, _+_O_l_d_, _-_M_e_r_g_e_d))                                 _[_d_e_t_]
    Merge  two option lists.  _M_e_r_g_e_d  is a sorted list of  options using
    the  canonical format Name(Value) holding  all options from _N_e_w  and
    _O_l_d, after removing conflicting options from _O_l_d.

    Multi-values  options (e.g.,  proxy(Host, Port)) are allowed,  where
    both option-name and arity define the identity of the option.


mmeettaa__ooppttiioonnss((_+_I_s_M_e_t_a_, _:_O_p_t_i_o_n_s_0_, _-_O_p_t_i_o_n_s))                         _[_d_e_t_]
    Perform   meta-expansion  on  options  that  are   module-sensitive.
    Whether an option  name is module-sensitive is determined by calling
    call(IsMeta, Name).  Here is an example:

    ____________________________________________________________________|                                                                    |
    |         meta_options(is_meta, OptionsIn, Options),                 |

    |         ...                                                        |
    |                                                                    |
    ||is_meta(callback).________________________________________________ ||

    Meta-options must have  exactly one argument.  This argument will be
    qualified.

         TToo bbee ddoonnee Should  be  integrated  with declarations  from
             predicate_options/3.


ddiicctt__ooppttiioonnss((_?_D_i_c_t_, _?_O_p_t_i_o_n_s))                                      _[_d_e_t_]
    Convert  between  an option  list and  a  dictionary.   One  of  the
    arguments  must be instantiated.  If the option list is  created, it
    is  created in canonical  form, i.e.,  using Option(Value) with  the
    _O_p_t_i_o_n_s  sorted in  the  standard order  of terms.    Note that  the
    conversion  is not always possible due to different  constraints and
    convertion may thus lead to (type) errors.

      o  _D_i_c_t keys can  be integers.   This is not allowed in  canonical
         option lists.

      o  _O_p_t_i_o_n_s can hold multiple options  with the same key.   This is
         not allowed in dicts.

      o  _O_p_t_i_o_n_s can have  more than one value  (name(V1,V2)).  This  is
         not allowed in dicts.

    Also  note that  most system  predicates and  predicates using  this
    library  for  processing  the option  argument  can both  work  with
    classical Prolog options and dicts objects.


1133..2200 lliibbrraarryy((ooppttppaarrssee))::  ccoommmmaanndd lliinnee ppaarrssiinngg

    aauutthhoorr  Marcus Uneson

    vveerrssiioonn  0.20 (2011-04-27)

    TToo bbee ddoonnee  :  validation?   e.g, numbers; file path existence;
         one-out-of-a-set-of-atoms

This  module   helps  in  building  a   command-line  interface  to   an
application.  In  particular, it provides functions that take  an option
specification and  a list  of atoms,  probably given to  the program  on
the command  line, and  return a  parsed representation (a  list of  the
customary Key(Val) by default;  or optionally, a list of Func(Key,  Val)
terms in the style of  current_prolog_flag/2).  It can also  synthesize a
simple help text from the options specification.

The  terminology  in  the following  is  partly  borrowed  from  python,
see  http://docs.python.org/library/optparse.html#terminology .     Very
briefly,   _a_r_g_u_m_e_n_t_s  is   what  you   provide  on   the  command   line
and  for   many  prologs   show  up  as   a  list   of  atoms  Args   in
current_prolog_flag(argv, Args).    For  a typical  prolog  incantation,
they can be divided into

  o _r_u_n_t_i_m_e  _a_r_g_u_m_e_n_t_s, which controls  the prolog runtime;  convention-
    ally, they are ended by '--';

  o _o_p_t_i_o_n_s,  which are key-value pairs  (with a boolean value  possibly
    implicit)  intended to control your  program in one way or  another;
    and

  o _p_o_s_i_t_i_o_n_a_l  _a_r_g_u_m_e_n_t_s,  which  is  what remains  after  all  runtime
    arguments and options  have been removed (with implicit arguments --
    true/false for booleans -- filled in).

Positional  arguments are  in particular  used  for mandatory  arguments
without  which your  program  won't work  and  for  which there  are  no
sensible  defaults (e.g,,  input file  names).   Options,  by  contrast,
offer flexibility  by letting  you change  a default setting.    Options
are optional  not only  by etymology:   this  library has  no notion  of
mandatory or required options (see the python docs  for other rationales
than laziness).

The command-line arguments  enter your program as  a list of atoms,  but
the programs perhaps  expects booleans, integers, floats or  even prolog
terms.   You tell the parser  so by providing an _o_p_t_i_o_n_s  _s_p_e_c_i_f_i_c_a_t_i_o_n.
This is just a list of individual option specifications.   One of those,
in turn, is a  list of ground prolog terms in the  customary Name(Value)
format.  The following terms are recognized (any others raise error).

oopptt((_K_e_y))
    _K_e_y  is what the  option later  will be accessed  by, just like  for
    current_prolog_flag(Key, Value).   This term is mandatory  (an error
    is thrown if missing).

sshhoorrttffllaaggss((_L_i_s_t_O_f_F_l_a_g_s))
    _L_i_s_t_O_f_F_l_a_g_s  denotes any single-dashed, single letter  args specify-
    ing  the current  option  (-s , -K, etc).    Uppercase letters  must
    be  quoted.    Usually _L_i_s_t_O_f_F_l_a_g_s  will be  a singleton  list,  but
    sometimes aliased flags may be convenient.

lloonnggffllaaggss((_L_i_s_t_O_f_F_l_a_g_s))
    _L_i_s_t_O_f_F_l_a_g_s  denotes  any  double-dashed  arguments  specifying  the
    current  option (--verbose, --no-debug, etc).  They are  basically a
    more readable alternative to short flags, except

 1. long  flags can  be specified as  --flag value or --flag=value  (but
    not  as  --flagvalue);  short  flags as  -f val  or -fval  (but  not
    -f=val)

 2. boolean  long  flags  can be  specified  as --bool-flag  or  --bool-
    flag=true   or  --bool-flag true;   and  they  can  be  negated   as
    --no-bool-flag or --bool-flag=false or --bool-flag false.

    Except  that shortflags must  be single characters, the  distinction
    between long and  short is in calling convention, not in namespaces.
    Thus, if you have  shortflags([v]), you can use it as -v2 or -v 2 or
    --v=2 or --v 2 (but not -v=2 or --v2).

    Shortflags  and longflags both default to [].   It can be  useful to
    have flagless options -- see example below.

mmeettaa((_M_e_t_a))
    _M_e_t_a  is  optional  and  only relevant  for  the  synthesized  usage
    message  and is  the name  (an atom) of  the metasyntactic  variable
    (possibly)  appearing in  it together  with type  and default  value
    (e.g,  x:integer=3, interest:float=0.11).  It may be useful  to have
    named  variables (x,  interest)  in case  you wish  to mention  them
    again  in the help text.  If not given the Meta:  part is suppressed
    -- see example below.

ttyyppee((_T_y_p_e))
    _T_y_p_e  is one  of  boolean, atom, integer, float, term.   The  corre-
    sponding  argument  will be  parsed  appropriately.   This  term  is
    optional; if not given, defaults to term.

ddeeffaauulltt((_D_e_f_a_u_l_t))
    _D_e_f_a_u_l_t  value.  This  term is optional; if  not given, or if  given
    the  special value '_', an uninstantiated  variable is created  (and
    any type declaration is ignored).

hheellpp((_H_e_l_p))
    _H_e_l_p is (usually) an  atom of text describing the option in the help
    text.   This  term is optional  (but obviously strongly  recommended
    for all options which have flags).

    Long  lines are  subject to basic  word wrapping  -- split on  white
    space,  reindent,  rejoin.   However, you  can get  more control  by
    supplying  the line breaking  yourself:  rather  than a single  line
    of  text, you can provide  a list of lines (as  atoms).  If you  do,
    they  will be joined with the appropriate indent but  otherwise left
    untouched (see the option mode in the example below).

Absence of mandatory option  specs or the presence of more than  one for
a  particular option  throws an  error, as  do  unknown or  incompatible
types.

As a concrete  example from a fictive  application, suppose we want  the
following options to be read from the command line  (long flag(s), short
flag(s), meta:type=default, help)

________________________________________________________________________|                                                                        |
|--mode                  -m     atom=SCAN       data gathering mode,     |
|                                               one of                   |
|                                                SCAN: do this           |

|                                                READ: do that           |
|                                                MAKE: make numbers      |
|                                                WAIT: do nothing        |
|--rebuild-cache         -r     boolean=true    rebuild cache in         |
|                                               each iteration           |
|--heisenberg-threshold  -t,-h  float=0.1       heisenberg threshold     |
|--depths, --iters       -i,-d  K:integer=3     stop after K             |
|                                               iterations               |

|--distances                    term=[1,2,3,5]  initial prolog term      |
|--output-file           -o     FILE:atom=_     write output to FILE     |
|--label                 -l     atom=REPORT     report label             |
|--verbosity             -v     V:integer=2     verbosity level,         |
||______________________________________________1_<=_V_<=_3_____________ ||

We  may also  have  some  configuration parameters  which  we  currently
think  not  needs   to  be  controlled  from   the  command  line,   say
path('/some/file/path').

This  interface is  described  by  the following  options  specification
(order   between  the   specifications  of   a   particular  option   is
irrelevant).

________________________________________________________________________|                                                                        |
|ExampleOptsSpec =                                                       |

|    [ [opt(mode    ), type(atom), default('SCAN'),                      |
|        shortflags([m]),   longflags(['mode'] ),                        |
|        help([ 'data gathering mode, one of'                            |
|             , '  SCAN: do this'                                        |
|             , '  READ: do that'                                        |
|             , '  MAKE: fabricate some numbers'                         |
|             , '  WAIT: don''t do anything'])]                          |
|                                                                        |

|    , [opt(cache), type(boolean), default(true),                        |
|        shortflags([r]),   longflags(['rebuild-cache']),                |
|        help('rebuild cache in each iteration')]                        |
|                                                                        |
|    , [opt(threshold), type(float), default(0.1),                       |
|        shortflags([t,h]),  longflags(['heisenberg-threshold']),        |
|        help('heisenberg threshold')]                                   |

|                                                                        |
|    , [opt(depth), meta('K'), type(integer), default(3),                |
|        shortflags([i,d]),longflags([depths,iters]),                    |
|        help('stop after K iterations')]                                |
|                                                                        |
|    , [opt(distances), default([1,2,3,5]),                              |
|        longflags([distances]),                                         |
|        help('initial prolog term')]                                    |

|                                                                        |
|    , [opt(outfile), meta('FILE'), type(atom),                          |
|        shortflags([o]),  longflags(['output-file']),                   |
|        help('write output to FILE')]                                   |
|                                                                        |
|    , [opt(label), type(atom), default('REPORT'),                       |
|        shortflags([l]), longflags([label]),                            |

|        help('report label')]                                           |
|                                                                        |
|    , [opt(verbose),  meta('V'), type(integer), default(2),             |
|        shortflags([v]),  longflags([verbosity]),                       |
|        help('verbosity level, 1 <= V <= 3')]                           |
|                                                                        |
|    , [opt(path), default('/some/file/path/')]                          |
||___]._________________________________________________________________ ||

The       help       text       above       was        accessed       by
opt_help(ExamplesOptsSpec, HelpText).     The  options  appear   in  the
same order as in the OptsSpec.

Given   ExampleOptsSpec,   a   command  line   (somewhat   syntactically
inconsistent,  in order  to demonstrate  different calling  conventions)
may look as follows

________________________________________________________________________|                                                                        |

|ExampleArgs = [ '-d5'                                                   |
|              , '--heisenberg-threshold', '0.14'                        |
|              , '--distances=[1,1,2,3,5,8]'                             |
|              , '--iters', '7'                                          |
|              , '-ooutput.txt'                                          |
|              , '--rebuild-cache', 'true'                               |

|              , 'input.txt'                                             |
|              , '--verbosity=2'                                         |
||_____________]._______________________________________________________ ||

opt_parse(ExampleOptsSpec, ExampleArgs, Opts, PositionalArgs)      would
then succeed with

________________________________________________________________________|                                                                        |
|Opts =    [ mode('SCAN')                                                |
|          , label('REPORT')                                             |
|          , path('/some/file/path')                                     |
|          , threshold(0.14)                                             |

|          , distances([1,1,2,3,5,8])                                    |
|          , depth(7)                                                    |
|          , outfile('output.txt')                                       |
|          , cache(true)                                                 |
|          , verbose(2)                                                  |
|          ],                                                            |
|PositionalArgs|=_['input.txt'].________________________________________ |              |

Note  that path('/some/file/path')  showing  up in  Opts has  a  default
value  (of  the  implicit  type  'term'),  but  no  corresponding  flags
in  OptsSpec.      Thus  it  can't   be  set  from  the  command   line.
The  rest  of  your program  doesn't  need  to  know  that,  of  course.
This  provides  an  alternative to  the  common  practice  of  asserting
such  hard-coded  parameters  under a  single  predicate  (for  instance
setting(path, '/some/file/path')),  with  the  advantage  that  you  may
seamlessly  upgrade them  to command-line  options, should  you one  day
find this  a good  idea.   Just  add an appropriate  flag or  two and  a
line of  help text.   Similarly,  suppressing an  option in a  cluttered
interface amounts to commenting out the flags.

opt_parse/5 allows more control  through an additional argument list  as
shown in the example below.

________________________________________________________________________|                                                                        |

|?- opt_parse(ExampleOptsSpec, ExampleArgs,  Opts, PositionalArgs,       |
|             [ output_functor(appl_config)                              |
|             ]).                                                        |
|                                                                        |
|Opts =    [ appl_config(verbose, 2),                                    |
|          , appl_config(label, 'REPORT')                                |

|          ...                                                           |
||_________]____________________________________________________________ ||

This representation may be preferable with  the empty-flag configuration
parameter style above (perhaps with asserting appl_config/2).


1133..2200..11 NNootteess aanndd ttiippss

  o In  the example  we were  mostly explicit about  the types.    Since
    the  default is  term, which subsumes  integer, float, atom, it  may
    be  possible to get  away cheaper (e.g.,  by only giving  booleans).
    However,   it is  recommended  practice  to  always  specify  types:
    parsing  becomes more reliable and error messages will be  easier to
    interpret.

  o Note  that -sbar is taken to mean -s bar, not -s -b -a -r,  that is,
    there is no clustering of flags.

  o -s=foo  is  disallowed.     The  rationale  is  that  although  some
    command-line  parsers will silently interpret this as -s =foo,  this
    is  very seldom what  you want.   To have  an option argument  start
    with '=' (very un-recommended), say so explicitly.

  o The  example specifies  the option  depth twice:   once  as -d5  and
    once  as --iters 7.  The default when encountering  duplicated flags
    is  to keeplast (this  behaviour can  be controlled, by  ParseOption
    duplicated_flags).

  o The  order of the options returned  by the parsing functions is  the
    same  as given  on the  command line,  with non-overridden  defaults
    prepended  and duplicates removed as in  previous item.  You  should
    not rely on this, however.

  o Unknown  flags (not appearing in OptsSpec) will throw errors.   This
    is  usually a Good Thing.  Sometimes, however, you may wish  to pass
    along  flags to an  external program (say,  one called by  shell/2),
    and  it means duplicated effort  and a maintenance headache to  have
    to  specify all possible flags  for the external program  explicitly
    (if  it even can  be done).   On the other  hand, simply taking  all
    unknown  flags as  valid makes  error checking  much less  efficient
    and  identification of  positional arguments  uncertain.   A  better
    solution  is to collect all arguments intended for passing  along to
    an  indirectly called program as  a single argument, probably as  an
    atom  (if you don't need to inspect them first) or as a  prolog term
    (if you do).


oopptt__aarrgguummeennttss((_+_O_p_t_s_S_p_e_c_, _-_O_p_t_s_, _-_P_o_s_i_t_i_o_n_a_l_A_r_g_s))                   _[_d_e_t_]
    Extract  commandline options  according to  a specification.    Con-
    venience  predicate,  assuming that  command-line  arguments can  be
    accessed  by current_prolog_flag/2 (as  in swi-prolog).   For  other
    access  mechanisms and/or more control,  get the args and pass  them
    as a list of atoms to opt_parse/4 or opt_parse/5 instead.

    _O_p_t_s  is a list of  parsed options in the  form Key(Value).   Dashed
    args  not in _O_p_t_s_S_p_e_c  are not permitted  and will raise error  (see
    tip  on  how  to pass  unknown  flags  in the  module  description).
    _P_o_s_i_t_i_o_n_a_l_A_r_g_s  are the  remaining non-dashed args  after each  flag
    has  taken its  argument (filling  in true or  false for  booleans).
    There  are no restrictions on  non-dashed arguments and they may  go
    anywhere  (although it  is good  practice to put  them last).    Any
    leading  arguments for the  runtime (up to  and including '--')  are
    discarded.


oopptt__ppaarrssee((_+_O_p_t_s_S_p_e_c_, _+_A_p_p_l_A_r_g_s_, _-_O_p_t_s_, _-_P_o_s_i_t_i_o_n_a_l_A_r_g_s))            _[_d_e_t_]
    Equivalent to opt_parse(OptsSpec, ApplArgs, Opts, PositionalArgs, []).


oopptt__ppaarrssee((_+_O_p_t_s_S_p_e_c_, _+_A_p_p_l_A_r_g_s_, _-_O_p_t_s_, _-_P_o_s_i_t_i_o_n_a_l_A_r_g_s_, _+_P_a_r_s_e_O_p_t_i_o_n_s))_[_d_e_t_]
    Parse  the arguments Args (as list of atoms) according  to _O_p_t_s_S_p_e_c.
    Any runtime arguments  (typically terminated by '--') are assumed to
    be removed already.

    _O_p_t_s  is a list of parsed  options in the form Key(Value),  or (with
    the  option  functor(Func)  given) in  the  form  Func(Key,  Value).
    Dashed  args not in _O_p_t_s_S_p_e_c are not permitted and will  raise error
    (see  tip on how to pass  unknown flags in the module  description).
    _P_o_s_i_t_i_o_n_a_l_A_r_g_s  are the  remaining non-dashed args  after each  flag
    has  taken its  argument (filling  in true or  false for  booleans).
    There  are  no restrictions  on non-dashed  arguments  and they  may
    go  anywhere  (although  it is  good  practice  to put  them  last).
    _P_a_r_s_e_O_p_t_i_o_n_s are

    oouuttppuutt__ffuunnccttoorr((_F_u_n_c))
         Set the functor  _F_u_n_c of the returned options  _F_u_n_c(Key,Value).
         Default  is the  special  value  'OPTION'  (upper-case),  which
         makes the returned options have form Key(Value).

    dduupplliiccaatteedd__ffllaaggss((_K_e_e_p))
         Controls how  to handle  options given  more than  once on  the
         commad line.  _K_e_e_p is one  of keepfirst, keeplast, keepall with
         the obvious meaning.  Default is keeplast.

    aallllooww__eemmppttyy__ffllaagg__ssppeecc((_B_o_o_l))
         If true  (default), a  flag specification is  not required  (it
         is allowed  that both  shortflags  and longflags  be either  []
         or absent).   Flagless options  cannot be manipulated from  the
         command  line and  will  not show  up  in the  generated  help.
         This  is useful  when  you  have (also)  general  configuration
         parameters in your _O_p_t_s_S_p_e_c,  especially if you think they  one
         day might  need to be  controlled externally.   See example  in
         the module  overview.   allow_empty_flag_spec(false) gives  the
         more customary behaviour of raising error on empty flags.


oopptt__hheellpp((_+_O_p_t_s_S_p_e_c_, _-_H_e_l_p_:_a_t_o_m))                                    _[_d_e_t_]
    True when _H_e_l_p is a help string synthesized from _O_p_t_s_S_p_e_c.


ppaarrssee__ttyyppee((_+_T_y_p_e_, _+_C_o_d_e_s_:_l_i_s_t_(_c_o_d_e_)_, _-_R_e_s_u_l_t))        _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Hook to parse option text _C_o_d_e_s to an object of type _T_y_p_e.


1133..2211 lliibbrraarryy((oorrddsseettss))::  OOrrddeerreedd sseett mmaanniippuullaattiioonn

Ordered  sets are  lists with  unique elements  sorted  to the  standard
order of  terms (see  sort/2).   Exploiting  ordering, many  of the  set
operations can  be expressed  in order  N rather than  N^2 when  dealing
with unordered sets  that may contain duplicates.   The library(ordsets)
is available in a number of Prolog implementations.   Our predicates are
designed to be compatible with common practice in  the Prolog community.
The implementation  is incomplete  and relies  partly on  library(oset),
an  older  ordered  set  library  distributed  with  SWI-Prolog.     New
applications are advised to use library(ordsets).

Some  of   these  predicates  match   directly  to  corresponding   list
operations.    It  is advised  to use  the  versions from  this  library
to  make clear  you are  operating on  ordered sets.    An exception  is
member/2.  See ord_memberchk/2.

The ordsets  library is  based on  the standard order  of terms.    This
implies  it can  handle all  Prolog terms,  including variables.    Note
however, that  the ordering is not  stable if a  term inside the set  is
further  instantiated.   Also  note that  variable  ordering changes  if
variables in the  set are unified with each  other or a variable in  the
set is unified with a variable that is `older'  than the newest variable
in  the set.    In practice,  this implies  that  it is  allowed to  use
member(X, OrdSet) on an ordered set that holds variables only  if X is a
fresh variable.  In  other cases one should cease using it as  an ordset
because the order it relies on may have been changed.


iiss__oorrddsseett((_@_T_e_r_m))                                               _[_s_e_m_i_d_e_t_]
    True  if _T_e_r_m is  an ordered set.   All  predicates in this  library
    expect  ordered sets as  input arguments.   Failing to fullfil  this
    assumption results in  undefined behaviour.  Typically, ordered sets
    are created by predicates from this library, sort/2 or setof/3.


oorrdd__eemmppttyy((_?_L_i_s_t))                                               _[_s_e_m_i_d_e_t_]
    True  when _L_i_s_t is the empty ordered set.  Simply unifies  list with
    the empty list.  Not part of Quintus.


oorrdd__sseetteeqq((_+_S_e_t_1_, _+_S_e_t_2))                                        _[_s_e_m_i_d_e_t_]
    True  if  _S_e_t_1  and _S_e_t_2  have  the same  elements.    As  both  are
    canonical sorted lists, this is the same as ==/2.

         CCoommppaattiibbiilliittyy sicstus


lliisstt__ttoo__oorrdd__sseett((_+_L_i_s_t_, _-_O_r_d_S_e_t))                                     _[_d_e_t_]
    Transform  a list into an ordered set.  This is the  same as sorting
    the list.


oorrdd__iinntteerrsseecctt((_+_S_e_t_1_, _+_S_e_t_2))                                    _[_s_e_m_i_d_e_t_]
    True if both ordered sets have a non-empty intersection.


oorrdd__ddiissjjooiinntt((_+_S_e_t_1_, _+_S_e_t_2))                                     _[_s_e_m_i_d_e_t_]
    True  if  _S_e_t_1 and  _S_e_t_2  have no  common  elements.   This  is  the
    negation of ord_intersect/2.


oorrdd__iinntteerrsseecctt((_+_S_e_t_1_, _+_S_e_t_2_, _-_I_n_t_e_r_s_e_c_t_i_o_n))
    _I_n_t_e_r_s_e_c_t_i_o_n holds the common elements of _S_e_t_1 and _S_e_t_2.

         ddeepprreeccaatteedd Use ord_intersection/3


oorrdd__iinntteerrsseeccttiioonn((_+_P_o_w_e_r_S_e_t_, _-_I_n_t_e_r_s_e_c_t_i_o_n))
    _I_n_t_e_r_s_e_c_t_i_o_n  of a powerset.   True when _I_n_t_e_r_s_e_c_t_i_o_n is an  ordered
    set holding all elements common to all sets in _P_o_w_e_r_S_e_t.

         CCoommppaattiibbiilliittyy sicstus


oorrdd__iinntteerrsseeccttiioonn((_+_S_e_t_1_, _+_S_e_t_2_, _-_I_n_t_e_r_s_e_c_t_i_o_n))                      _[_d_e_t_]
    _I_n_t_e_r_s_e_c_t_i_o_n  holds the  common elements  of _S_e_t_1  and _S_e_t_2.    Uses
    ord_disjoint/2 if _I_n_t_e_r_s_e_c_t_i_o_n is bound to [] on entry.


oorrdd__iinntteerrsseeccttiioonn((_+_S_e_t_1_, _+_S_e_t_2_, _?_I_n_t_e_r_s_e_c_t_i_o_n_, _?_D_i_f_f_e_r_e_n_c_e))         _[_d_e_t_]
    _I_n_t_e_r_s_e_c_t_i_o_n and difference  between two ordered sets.  _I_n_t_e_r_s_e_c_t_i_o_n
    is  the  intersection between  _S_e_t_1 and  _S_e_t_2,  while _D_i_f_f_e_r_e_n_c_e  is
    defined by ord_subtract(Set2, Set1, Difference).

         SSeeee aallssoo ord_intersection/3 and ord_subtract/3.


oorrdd__aadddd__eelleemmeenntt((_+_S_e_t_1_, _+_E_l_e_m_e_n_t_, _?_S_e_t_2))                            _[_d_e_t_]
    Insert   an  element  into   the  set.      This  is  the  same   as
    ord_union(Set1, [Element], Set2).


oorrdd__ddeell__eelleemmeenntt((_+_S_e_t_, _+_E_l_e_m_e_n_t_, _-_N_e_w_S_e_t))                           _[_d_e_t_]
    Delete  an  element from  an  ordered set.    This  is the  same  as
    ord_subtract(Set, [Element], NewSet).


oorrdd__sseelleeccttcchhkk((_+_I_t_e_m_, _?_S_e_t_1_, _?_S_e_t_2))                             _[_s_e_m_i_d_e_t_]
    Selectchk/3,   specialised  for  ordered   sets.     Is  true   when
    select(Item, Set1, Set2)  and  _S_e_t_1,  _S_e_t_2  are  both  sorted  lists
    without  duplicates.  This  implementation is only expected to  work
    for  _I_t_e_m  ground  and  either _S_e_t_1  or  _S_e_t_2  ground.    The  "chk"
    suffix  is meant to  remind you of  memberchk/2, which also  expects
    its  first  argument  to  be  ground.    ord_selectchk(X, S, T)  =>
    ord_memberchk(X, S) & \+ ord_memberchk(X, T).

         aauutthhoorr Richard O'Keefe


oorrdd__mmeemmbbeerrcchhkk((_+_E_l_e_m_e_n_t_, _+_O_r_d_S_e_t))                               _[_s_e_m_i_d_e_t_]
    True  if _E_l_e_m_e_n_t is  a member of  _O_r_d_S_e_t, compared using  ==.   Note
    that  _e_n_u_m_e_r_a_t_i_n_g  elements of  an  ordered set  can be  done  using
    member/2.

    Some  Prolog  implementations also  provide  ord_member/2,  with  the
    same  semantics  as  ord_memberchk/2.     We believe  that  having  a
    semidet  ord_member/2 is  unacceptably  inconsistent with  the *_chk
    convention.  Portable code should use ord_memberchk/2 or member/2.

         aauutthhoorr Richard O'Keefe


oorrdd__ssuubbsseett((_+_S_u_b_, _+_S_u_p_e_r))                                       _[_s_e_m_i_d_e_t_]
    Is true if all elements of _S_u_b are in _S_u_p_e_r


oorrdd__ssuubbttrraacctt((_+_I_n_O_S_e_t_, _+_N_o_t_I_n_O_S_e_t_, _-_D_i_f_f))                           _[_d_e_t_]
    _D_i_f_f  is the  set holding  all elements of  _I_n_O_S_e_t that  are not  in
    _N_o_t_I_n_O_S_e_t.


oorrdd__uunniioonn((_+_S_e_t_O_f_S_e_t_s_, _-_U_n_i_o_n))                                      _[_d_e_t_]
    True  if  _U_n_i_o_n  is  the  union of  all  elements  in  the  superset
    _S_e_t_O_f_S_e_t_s.   Each member  of _S_e_t_O_f_S_e_t_s must  be an ordered set,  the
    sets need not be ordered in any way.

         aauutthhoorr Copied  from  YAP, probably  originally  by Richard
             O'Keefe.


oorrdd__uunniioonn((_+_S_e_t_1_, _+_S_e_t_2_, _?_U_n_i_o_n))                                    _[_d_e_t_]
    _U_n_i_o_n is the union of _S_e_t_1 and _S_e_t_2


oorrdd__uunniioonn((_+_S_e_t_1_, _+_S_e_t_2_, _-_U_n_i_o_n_, _-_N_e_w))                              _[_d_e_t_]
    True          iff          ord_union(Set1, Set2, Union)          and
    ord_subtract(Set2, Set1, New).


oorrdd__ssyymmddiiffff((_+_S_e_t_1_, _+_S_e_t_2_, _?_D_i_f_f_e_r_e_n_c_e))                             _[_d_e_t_]
    Is  true when  _D_i_f_f_e_r_e_n_c_e is  the symmetric difference  of _S_e_t_1  and
    _S_e_t_2.    I.e.,  _D_i_f_f_e_r_e_n_c_e contains  all elements  that  are not  in
    the  intersection of _S_e_t_1 and  _S_e_t_2.  The  semantics is the same  as
    the  sequence below (but the  actual implementation requires only  a
    single scan).

    ____________________________________________________________________|                                                                    |
    |       ord_union(Set1, Set2, Union),                                |

    |       ord_intersection(Set1, Set2, Intersection),                  |
    ||______ord_subtract(Union,_Intersection,_Difference).______________ ||

    For example:

    ____________________________________________________________________|                                                                    |
    | ?- ord_symdiff([1,2], [2,3], X).                                   |
    ||X_=_[1,3].________________________________________________________ ||


1133..2222 lliibbrraarryy((ppaaiirrss))::  OOppeerraattiioonnss oonn kkeeyy--vvaalluuee lliissttss

    aauutthhoorr  Jan Wielemaker

    SSeeee aallssoo  keysort/2, library(assoc)

This  module  implements common  operations  on  Key-Value  lists,  also
known as  _P_a_i_r_s.   Pairs have great practical  value, especially due  to
keysort/2 and the library assoc.pl.

This  library is  based  on  disussion in  the  SWI-Prolog  mailinglist,
including specifications from Quintus and a library  proposal by Richard
O'Keefe.


ppaaiirrss__kkeeyyss__vvaalluueess((_?_P_a_i_r_s_, _?_K_e_y_s_, _?_V_a_l_u_e_s))                          _[_d_e_t_]
    True if _K_e_y_s holds the keys of _P_a_i_r_s and _V_a_l_u_e_s the values.

    Deterministic  if any argument is instantiated to a finite  list and
    the others are either  free or finite lists.  All three lists are in
    the same order.

         SSeeee aallssoo pairs_values/2 and pairs_keys/2.


ppaaiirrss__vvaalluueess((_+_P_a_i_r_s_, _-_V_a_l_u_e_s))                                      _[_d_e_t_]
    Remove  the  keys  from  a  list  of  Key-Value  pairs.     Same  as
    pairs_keys_values(Pairs, _, Values)


ppaaiirrss__kkeeyyss((_+_P_a_i_r_s_, _-_K_e_y_s))                                          _[_d_e_t_]
    Remove  the  values  from  a list  of  Key-Value  pairs.    Same  as
    pairs_keys_values(Pairs, Keys, _)


ggrroouupp__ppaaiirrss__bbyy__kkeeyy((_+_P_a_i_r_s_, _-_J_o_i_n_e_d_:_l_i_s_t_(_K_e_y_-_V_a_l_u_e_s_)))                _[_d_e_t_]
    Group values with equivalent (==/2) consecutive keys.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- group_pairs_by_key([a-2, a-1, b-4, a-3], X).                    |

    |                                                                    |
    ||X_=_[a-[2,1],_b-[4],_a-[3]]_______________________________________ ||

    Sorting  the list of pairs before grouping can be used to  group _a_l_l
    values  associated with  a key.    For example,  finding all  values
    associated with the largest key:

    ____________________________________________________________________|                                                                    |
    | ?- sort(1, @>=, [a-1, b-2, c-3, a-4, a-5, c-6], Ps),               |
    |    group_pairs_by_key(Ps, [K-Vs|_]).                               |
    | K = c,                                                             |
    ||Vs_=_[3,_6].______________________________________________________ ||

    In  this example, sorting by key  only (first argument of sort/4  is
    1)  ensures that the  order of  the values in  the original list  of
    pairs is maintained.

    ___________________________________________________________Arguments_
     _P_a_i_r_s   _K_e_y-Value list
     _J_o_i_n_e_d  List  of _K_e_y-Group, where  Group is the list  of
             _V_a_l_u_e_s  associated with  equivalent  consecutive
             Keys in the same order as they appear in _P_a_i_r_s.


ttrraannssppoossee__ppaaiirrss((_+_P_a_i_r_s_, _-_T_r_a_n_s_p_o_s_e_d))                               _[_d_e_t_]
    Swap  Key-Value to Value-Key.   The  resulting list is sorted  using
    keysort/2 on the new key.


mmaapp__lliisstt__ttoo__ppaaiirrss((_:_F_u_n_c_t_i_o_n_, _+_L_i_s_t_, _-_K_e_y_e_d))
    Create  a Key-Value  list  by mapping  each element  of _L_i_s_t.    For
    example,  if  we have  a  list of  lists  we can  create a  list  of
    Length-_L_i_s_t using

    ____________________________________________________________________|                                                                    |
    ||________map_list_to_pairs(length,_ListOfLists,_Pairs),____________ ||


1133..2233 lliibbrraarryy((ppeerrssiisstteennccyy))::  PPrroovviiddee ppeerrssiisstteenntt ddyynnaammiicc pprreeddiiccaatteess

    TToo bbee ddoonnee
         - Provide type safety while loading
         - Thread  safety must now  be provided at  the user-level.
         Can we  provide generic  thread safety?    Basically, this
         means that  we must  wrap all exported  predicates.   That
         might better be done outside this library.
         - Transaction management?
         - Should  assert_<name>  only assert if  the database  does
         not contain a variant?

This module provides  simple persistent storage for one or  more dynamic
predicates.   A database is always associated  with a module.  A  module
that wishes to  maintain a database must  declare the terms that can  be
placed in the database using the directive persistent/1.

The persistent/1 expands each declaration into four predicates:

  o name(Arg, ...)

  o assert_name(Arg, ...)

  o retract_name(Arg, ...)

  o retractall_name(Arg, ...)

As  mentioned, a  database can  only be  accessed from  within a  single
module.   This limitation is on purpose,  forcing the user to provide  a
proper API for accessing the shared persistent data.

Below is a simple example:

________________________________________________________________________|                                                                        |
|:- module(user_db,                                                      |
|          [ attach_user_db/1,           % +File                         |
|            current_user_role/2,        % ?User, ?Role                  |

|            add_user/2,                 % +User, +Role                  |
|            set_user_role/2             % +User, +Role                  |
|          ]).                                                           |
|:- use_module(library(persistency)).                                    |
|                                                                        |
|:- persistent                                                           |
|        user_role(name:atom, role:oneof([user,administrator])).         |
|                                                                        |

|attach_user_db(File) :-                                                 |
|        db_attach(File, []).                                            |
|                                                                        |
|%%      current_user_role(+Name, -Role) is semidet.                     |
|                                                                        |
|current_user_role(Name, Role) :-                                        |
|        with_mutex(user_db, user_role(Name, Role)).                     |

|                                                                        |
|add_user(Name, Role) :-                                                 |
|        assert_user_role(Name, Role).                                   |
|                                                                        |
|set_user_role(Name, Role) :-                                            |
|        user_role(Name, Role), !.                                       |
|set_user_role(Name, Role) :-                                            |
|        with_mutex(user_db,                                             |

|                   (  retractall_user_role(Name, _),                    |
||_____________________assert_user_role(Name,_Role))).__________________ ||


ppeerrssiisstteenntt _+_S_p_e_c
    Declare dynamic database  terms.  Declarations appear in a directive
    and have the following format:

    ____________________________________________________________________|                                                                    |
    | :- persistent                                                      |

    |         <callable>,                                                |
    |         <callable>,                                                |
    ||________..._______________________________________________________ ||

    Each specification is  a callable term, following the conventions of
    library(record), where each argument is of the form

    ____________________________________________________________________|                                                                    |
    ||name:type_________________________________________________________ ||

    Types are defined by library(error).


ccuurrrreenntt__ppeerrssiisstteenntt__pprreeddiiccaattee((_:_P_I))                               _[_n_o_n_d_e_t_]
    True  if _P_I is  a predicate that  provides access to the  persistent
    database DB.


ddbb__aattttaacchh((_:_F_i_l_e_, _+_O_p_t_i_o_n_s))
    Use  _F_i_l_e  as persistent  database  for the  calling  module.    The
    calling  module must  defined persistent/1 to  declare the  database
    terms.  Defined options:

    ssyynncc((_+_S_y_n_c))
         One  of close  (close  journal after  write),  flush  (default,
         flush journal after  write) or none  (handle as fully  buffered
         stream).

    If  _F_i_l_e is  already  attached this  operation may  change the  sync
    behaviour.


ddbb__aattttaacchheedd((_:_F_i_l_e))                                             _[_s_e_m_i_d_e_t_]
    True  if  the context  module attached  to  the persistent  database
    _F_i_l_e.


ddbb__ddeettaacchh                                                          _[_d_e_t_]
    Detach  persistency from the calling  module and delete all  persis-
    tent  clauses from  the  Prolog database.    Note that  the file  is
    not  affected.  After this  operation another file may be  attached,
    providing it satisfies the same persistency declaration.


ddbb__ssyynncc((_:_W_h_a_t))
    Synchronise database with the associated file.  _W_h_a_t is one of:

    rreellooaadd
         Database is reloaded from  file if the file was  modified since
         loaded.

    uuppddaattee
         As reload,  but  use incremental  loading if  possible.    This
         allows for  two processes  to examine the  same database  file,
         where one writes the database and the  other periodycally calls
         db_sync(update) to follow the modified data.

    ggcc
         Database was  re-written, deleting  all retractall  statements.
         This is the same as gc(50).

    ggcc((_P_e_r_c_e_n_t_a_g_e))
         GC DB if  the number of deleted  terms is the given  percentage
         of the total number of terms.

    cclloossee
         Database stream was closed

    ddeettaacchh
         Remove all registered persistency for the calling module

    nnoopp
         No-operation performed

    With  unbound  _W_h_a_t,  db_sync/1  reloads  the  database  if  it  was
    modified  on disk,  gc  it if  it is  dirty and  close it  if it  is
    opened.


ddbb__ssyynncc__aallll((_+_W_h_a_t))
    Sync all registered databases.


1133..2244 lliibbrraarryy((ppiioo))::  PPuurree II//OO

This library provides  pure list-based I/O processing for Prolog,  where
the communication  to the actual I/O  device is performed  transparently
through coroutining.   This  module itself is just  an interface to  the
actual implementation modules.


1133..2244..11 lliibbrraarryy((ppuurree__iinnppuutt))::  PPuurree IInnppuutt ffrroomm ffiilleess aanndd ssttrreeaammss

    TToo bbee ddoonnee  Provide support for alternative input readers, e.g.
         reading terms, tokens, etc.

This module  is part  of pio.pl,  dealing with _p_u_r_e  _i_n_p_u_t:   processing
input  streams from  the outside  world using  pure predicates,  notably
grammar  rules  (DCG). Using  pure  predicates  makes  non-deterministic
processing of input much simpler.

Pure input  uses attributed variables  to read  input from the  external
source into  a list _o_n  _d_e_m_a_n_d.   The overhead of  lazy reading is  more
than compensated for by using block reads based on read_pending_codes/3.

Ulrich Neumerkel came up  with the idea to use coroutining  for creating
a  _l_a_z_y  _l_i_s_t.    His  implementation  repositioned  the  file  to  deal
with re-reading  that can  be necessary  on backtracking.   The  current
implementation uses destructive assignment together with  more low-level
attribute handling to realise pure input on any (buffered) stream.


pphhrraassee__ffrroomm__ffiillee((_:_G_r_a_m_m_a_r_, _+_F_i_l_e))                               _[_n_o_n_d_e_t_]
    Process  the content of _F_i_l_e using the DCG rule _G_r_a_m_m_a_r.   The space
    usage  of this mechanism depends on the length of the  not committed
    part  of  _G_r_a_m_m_a_r.    Committed  parts  of the  temporary  list  are
    reclaimed  by the garbage collector,  while the list is extended  on
    demand  due to unification of the  attributed tail variable.   Below
    is  an example that counts the  number of times a string appears  in
    a  file.    The library  dcg/basics provides  string//1 matching  an
    arbitrary  string and  remainder//1 which matches  the remainder  of
    the input without parsing.

    ____________________________________________________________________|                                                                    |
    | :- use_module(library(dcg/basics)).                                |

    |                                                                    |
    | file_contains(File, Pattern) :-                                    |
    |         phrase_from_file(match(Pattern), File).                    |
    |                                                                    |
    | match(Pattern) -->                                                 |
    |         string(_),                                                 |
    |         string(Pattern),                                           |
    |         remainder(_).                                              |

    |                                                                    |
    | match_count(File, Pattern, Count) :-                               |
    ||________aggregate_all(count,_file_contains(File,_Pattern),_Count)._||

    This can be called  as (note that the pattern must be a string (code
    list)):

    ____________________________________________________________________|                                                                    |
    ||?-_match_count('pure_input.pl',_`file`,_Count).___________________ ||


pphhrraassee__ffrroomm__ffiillee((_:_G_r_a_m_m_a_r_, _+_F_i_l_e_, _+_O_p_t_i_o_n_s))                     _[_n_o_n_d_e_t_]
    As  phrase_from_file/2,  providing additional _O_p_t_i_o_n_s.   _O_p_t_i_o_n_s  are
    passed to open/4.


pphhrraassee__ffrroomm__ssttrreeaamm((_:_G_r_a_m_m_a_r_, _+_S_t_r_e_a_m))
    Run  Grammer against the character codes on _S_t_r_e_a_m.  _S_t_r_e_a_m  must be
    buffered.


ssyynnttaaxx__eerrrroorr((_+_E_r_r_o_r)) //
    Throw  the syntax error _E_r_r_o_r at the current location of  the input.
    This  predicate  is  designed  to  be called  from  the  handler  of
    phrase_from_file/3.

         tthhrroowwss error(syntax_error(Error), Location)


llaazzyy__lliisstt__llooccaattiioonn((_-_L_o_c_a_t_i_o_n)) //                                   _[_d_e_t_]
    Determine  current  (error) location  in a  lazy list.    True  when
    _L_o_c_a_t_i_o_n  is an  (error) location term  that represents the  current
    location in the DCG list.

    ___________________________________________________________Arguments_
     _L_o_c_a_t_i_o_n  is   a  term   file(Name, Line, LinePos, CharNo)
               or  stream(Stream, Line, LinePos, CharNo) if  no
               file  is associated to the stream  RestLazyList.
               Finally, if the Lazy list is fully  materialized
               (ends   in  []),   _L_o_c_a_t_i_o_n   is  unified   with
               end_of_file-CharCount.

         SSeeee aallssoo lazy_list_character_count//1  only  provides  the
             character count.


llaazzyy__lliisstt__cchhaarraacctteerr__ccoouunntt((_-_C_h_a_r_C_o_u_n_t)) //
    True  when _C_h_a_r_C_o_u_n_t  is  the current  character count  in the  Lazy
    list.   The character count  is computed by finding the distance  to
    the next frozen tail of the lazy list.  _C_h_a_r_C_o_u_n_t is one of:

      o  An integer

      o  A term end_of_file-Count

         SSeeee aallssoo lazy_list_location//1  provides  full details  of
             the location for error reporting.


ssttrreeaamm__ttoo__llaazzyy__lliisstt((_+_S_t_r_e_a_m_, _-_L_i_s_t))                                 _[_d_e_t_]
    Create  a  lazy list  representing the  character  codes in  _S_t_r_e_a_m.
    _L_i_s_t  is a partial list ending in an attributed variable.   Unifying
    this  variable reads the next  block of data.   The block is  stored
    with the attribute value such that there is no need to re-read it.

         CCoommppaattiibbiilliittyy Unlike  the previous version  of this predi-
             cate  this version  does not require  a repositionable
             stream.   It  does require a  buffer size  of at least
             the  maximum number of bytes  of a multi-byte sequence
             (6).


1133..2255 lliibbrraarryy((pprreeddiiccaattee__ooppttiioonnss))::   DDeeccllaarree  ooppttiioonn--pprroocceessssiinngg ooff  pprreeddii--
      ccaatteess

               _D_i_s_c_u_s_s_i_o_n_s _w_i_t_h _J_e_f_f _S_c_h_u_l_t_z _h_e_l_p_e_d _s_h_a_p_i_n_g _t_h_i_s _l_i_b_r_a_r_y


1133..2255..11 TThhee ssttrreennggtthh aanndd wweeaakknneessss ooff pprreeddiiccaattee ooppttiioonnss

Many  ISO  predicates  accept   options,  e.g.,   open/4,  write_term/3.
Options  offer an  attractive  alternative  to proliferation  into  many
predicates and using high-arity predicates.  Properly  defined and used,
they also  form a  mechanism for extending  the API  of both system  and
application predicates without  breaking portability.  I.e.,  previously
fixed behaviour  can be replaced by  dynamic behaviour controlled by  an
option  where the  default is  the previously  defined fixed  behaviour.
The  alternative to  using  options is  to  add an  additional  argument
and maintain  the previous  definition.   While a  series of  predicates
with  increasing arity  is adequate  for a  small  number of  additional
parameters, the untyped  positional argument handling of Prolog  quickly
makes this unmanageable.

The ISO standard  uses the extensibility offered by options  by allowing
implementations to extend  the set of accepted  options.  While  options
form a  perfect solution to  maintain backward  portability in a  linear
development  model, it  is not  well equipped  to  deal with  concurrent
branches because

 1. There is no API  to find which options are supported in a particular
    implementation.

 2. While  the  portability problem  caused by  a  missing predicate  in
    Prolog _A can  easily be solved by implementing this predicate, it is
    much harder to  add processing of an additional option to an already
    existing predicate.

Different Prolog implementations  can be seen as concurrent  development
branches of the  Prolog language.   Different sets of supported  options
pose a serious  portability issue.   Using an option _O that  establishes
the desired behaviour  on system _A leads  (on most systems) to an  error
or system _B. Porting may require several actions:

  o Drop  _O (if the option is not  vital, such as the layout  options to
    write_term/3)

  o Replace _O by _O_2 (i.e., a differently named option doing the same)

  o Something  else  (cannot be  ported;  requires a  totally  different
    approach, etc.)

Predicates that process options are particularly a  problem when writing
a compatibility layer to  run programs developed for System _A  on System
_B  because  complete  emulation is  often  hard,  may  cause  a  serious
slowdown and  is often not  needed because the  application-to-be-ported
only uses options that are shared by all  target Prolog implementations.
Unfortunately,  the  consequences  of  a  partial  emulation  cannot  be
assessed by tools.


1133..2255..22 OOppttiioonnss aass aarrgguummeennttss oorr eennvviirroonnmmeenntt??

We distinguish two views on  options.  One is to see them  as additional
parameters that require  strict existence, type and domain-checking  and
the other  is to consider them  `locally scoped environment  variables'.
Most systems  adopt the  first option.   SWI-Prolog  adopts the  second:
it silently  ignores options that  are not supported  but does type  and
domain checking  of option-values.   The `environment' view is  commonly
used in applications to create predicates supporting  more options using
the skeleton  below.   This way of programming  requires that _p_r_e_d_1  and
_p_r_e_d_2 do  not interpret  the same option  differently.   In cases  where
this is  not true,  the options  must be distributed  by _s_o_m_e___p_r_e_d.    We
have been using  this programming style for  many years and in  practice
it  turns out  that  the need  for  active  distribution of  options  is
rare.  I.e.,  options either have distinct names or  multiple predicates
implement the same option  but this has the desired effect.   An example
of  the latter  is the  encoding  option, which  typically needs  to  be
applied consistently.

________________________________________________________________________|                                                                        |
|some_pred(..., Options) :-                                              |

|      pred1(..., Options),                                              |
||_____pred2(...,_Options)._____________________________________________ ||

As stated before,  options provide a readable alternative  to high-arity
predicates and offer  a robust mechanism to  evolve the API, but at  the
cost  of some  runtime overhead  and weaker  consistency checking,  both
at compiletime  and runtime.    From our  experience, the  `environment'
approach is  productive, but  the consequence is  that mistyped  options
are  silently ignored.    The option  infrastructure  described in  this
section tries to remedy these problems.


1133..2255..33 IImmpprroovviinngg oonn tthhee ccuurrrreenntt ssiittuuaattiioonn

Whether  we see  options  as  arguments or  locally  scoped  environment
variables, the most obvious  way to improve on the current  situation is
to provide  reflective support for options:   discover that an  argument
is  an option-list  and find  what options  are supported.    Reflective
access  to  options  can  be  used  by  the   compiler  and  development
environment as well as by the runtime system to warn or throw errors.


1133..2255..33..11 OOppttiioonnss aass ttyyppeess

An obvious  approach to  deal with  options is to  define the  different
possible option values  as a type and  type the argument that  processes
the option  as list(<option_type>),  as illustrated below.   Considering
options as  types fully  covers the  case where we  consider options  as
additional parameters.

________________________________________________________________________|                                                                        |
|:- type open_option ---> type(stream_type) |                            |

|                         alias(atom) | ... .                            |
|:-|pred_open(source_sink,_open_mode,_stream,_list(open_option))._______ |  |

There are three reasons for considering a different approach:

  o There  is no  consensus about  types  in the  Prolog world,  neither
    about  what types  should look  like, nor  whether or  not they  are
    desirable.    It is  not likely that  this debate  will be  resolved
    shortly.

  o Considering  options as  types  does not  support the  `environment'
    view, which we consider the most productive.

  o Even  when using types,  we need reflective  access to what  options
    are  provided  in order  to  be able  to  write compile  or  runtime
    conditional code.


1133..2255..33..22 RReefflleeccttiivvee aacccceessss ttoo ooppttiioonnss

From  the above,  we  conclude  that  we require  reflective  access  to
find  out whether  an option  is supported  and valid  for a  particular
predicate.  Possible option  values must be described by types.   Due to
lack of a type system, we use library(error)  to describe allowed option
values.  Predicate options are declared using predicate_options/3:


pprreeddiiccaattee__ooppttiioonnss((_:_P_I_, _+_A_r_g_, _+_O_p_t_i_o_n_s))                             _[_d_e_t_]
    Declare that the predicate  _P_I processes options on _A_r_g.  _O_p_t_i_o_n_s is
    a list of options processed.  Each element is one of:

      o  Option(ModeAndType)  _P_I processes  Option.    The  option-value
         must comply to ModeAndType.  Mode is one of + or  - and Type is
         a type as accepted by must_be/2.

      o  pass_to(:_P_I,_A_r_g)  The  option-list is  passed to  the  indicated
         predicate.

    Below  is an example that  processes the option header(boolean)  and
    passes all options to open/4:

    ____________________________________________________________________|                                                                    |

    | :- predicate_options(write_xml_file/3, 3,                          |
    |                      [ header(boolean),                            |
    |                        pass_to(open/4, 4)                          |
    |                      ]).                                           |
    |                                                                    |

    | write_xml_file(File, XMLTerm, Options) :-                          |
    |     open(File, write, Out, Options),                               |
    |     (   option(header(true), Options, true)                        |
    |     ->  write_xml_header(Out)                                      |
    |     ;   true                                                       |
    |     ),                                                             |
    ||____...___________________________________________________________ ||

    This  predicate may only be used as a _d_i_r_e_c_t_i_v_e and is  processed by
    expand_term/2.  Option processing can be  specified at runtime using
    assert_predicate_options/3,  which is  intended to  support  program
    analysis.


aasssseerrtt__pprreeddiiccaattee__ooppttiioonnss((_:_P_I_, _+_A_r_g_, _+_O_p_t_i_o_n_s_, _?_N_e_w))            _[_s_e_m_i_d_e_t_]
    As  predicate_options(:_P_I, +_A_r_g,   +_O_p_t_i_o_n_s).    _N_e_w  is  a  boolean
    indicating  whether  the  declarations have  changed.    If  _N_e_w  is
    provided and false,  the predicate becomes semidet and fails without
    modifications if modifications are required.

The  predicates  below  realise the  support  for  compile  and  runtime
checking for supported options.


ccuurrrreenntt__pprreeddiiccaattee__ooppttiioonn((_:_P_I_, _?_A_r_g_, _?_O_p_t_i_o_n))                    _[_n_o_n_d_e_t_]
    True  when _A_r_g of _P_I processes  _O_p_t_i_o_n.  For example,  the following
    is true:

    ____________________________________________________________________|                                                                    |
    | ?- current_predicate_option(open/4, 4, type(text)).                |
    ||true._____________________________________________________________ ||

    This predicate is  intended to support conditional compilation using
    if/1  ...   endif/0.  The  predicate current_predicate_options/3 can
    be used to access the full capabilities of a predicate.


cchheecckk__pprreeddiiccaattee__ooppttiioonn((_:_P_I_, _+_A_r_g_, _+_O_p_t_i_o_n))                         _[_d_e_t_]
    Verify    predicate   options    at   runtime.         Similar    to
    current_predicate_option/3,   but   intended  to   support   runtime
    checking.

         EErrrroorrss
             -  existence_error(option, OptionName)  if  the option
             is not supported by _P_I.
             -  type_error(Type, Value) if the  option is supported
             but  the value does  not match the  option type.   See
             must_be/2.

The predicates below can be used in a development  environment to inform
the user  about supported  options.   PceEmacs uses  this for  colouring
option names and values.


ccuurrrreenntt__ooppttiioonn__aarrgg((_:_P_I_, _?_A_r_g))                                   _[_n_o_n_d_e_t_]
    True when _A_r_g of  _P_I processes predicate options.  Which options are
    processed can be accessed using current_predicate_option/3.


ccuurrrreenntt__pprreeddiiccaattee__ooppttiioonnss((_:_P_I_, _?_A_r_g_, _?_O_p_t_i_o_n_s))                  _[_n_o_n_d_e_t_]
    True  when _O_p_t_i_o_n_s is the  current active option declaration for  _P_I
    on _A_r_g.   See predicate_options/3for the  argument descriptions.  If
    _P_I  is ground and refers  to an undefined predicate, the  autoloader
    is used to obtain a definition of the predicate.

The  library  can  execute  a  complete  check  of  your  program  using
check_predicate_options/0:


cchheecckk__pprreeddiiccaattee__ooppttiioonnss                                            _[_d_e_t_]
    Analyse  loaded  program  for erroneous  options.    This  predicate
    decompiles the current  program and searches for calls to predicates
    that  process options.  For  each option list, it validates  whether
    the  provided  options  are  supported and  validates  the  argument
    type.   This predicate  performs partial dataflow analysis to  track
    option-lists inside a clause.

         SSeeee aallssoo derive_predicate_options/0 can be  used to derive
             declarations   for  predicates   that   pass  options.
             This  predicate   should  normally  be  called  before
             check_predicate_options/0.

The library  offers predicates that may  be used to create  declarations
for your application.   These predicates are designed to  cooperate with
the module system.


ddeerriivvee__pprreeddiiccaattee__ooppttiioonnss                                           _[_d_e_t_]
    Derive  new predicate option declarations.  This  predicate analyses
    the  loaded program to find  clauses that process options using  one
    of  the predicates from library(option)  or passes options to  other
    predicates  that  are known  to process  options.    The process  is
    repeated until no new declarations are retrieved.

         SSeeee aallssoo autoload/0  may  be used  to complete  the loaded
             program.


rreettrraaccttaallll__pprreeddiiccaattee__ooppttiioonnss                                       _[_d_e_t_]
    Remove all dynamically (derived) predicate options.


ddeerriivveedd__pprreeddiiccaattee__ooppttiioonnss((_:_P_I_, _?_A_r_g_, _?_O_p_t_i_o_n_s))                  _[_n_o_n_d_e_t_]
    Derive  option arguments using static  analysis.  True when  _O_p_t_i_o_n_s
    is the current _d_e_r_i_v_e_d active option declaration for _P_I on _A_r_g.


ddeerriivveedd__pprreeddiiccaattee__ooppttiioonnss((_+_M_o_d_u_l_e))                                 _[_d_e_t_]
    Derive  predicate option  declarations for  a module.   The  derived
    options are printed to the current_output stream.


1133..2266 lliibbrraarryy((pprroolloogg__ppaacckk))::  AA ppaacckkaaggee mmaannaaggeerr ffoorr PPrroolloogg

    SSeeee aallssoo  Installed   packages  can   be  inspected   using  ?-
         doc_browser.

    TToo bbee ddoonnee
         - Version logic
         - Find and resolve conflicts
         - Upgrade git packages
         - Validate git packages
         - Test packages:  run tests from directory `test'.

The library(prolog_pack) provides the SWI-Prolog package manager.   This
library lets  you inspect installed  packages, install packages,  remove
packages, etc.   It is complemented by the  built-in attach_packs/0 that
makes installed packages available as libaries.


ppaacckk__lliisstt__iinnssttaalllleedd                                                _[_d_e_t_]
    List  currently  installed  packages.     Unlike  pack_list/1,  only
    locally  installed packages are displayed and no connection  is made
    to the internet.

         SSeeee aallssoo Use pack_list/1 to find packages.


ppaacckk__iinnffoo((_+_P_a_c_k))
    Print more detailed information about _P_a_c_k.


ppaacckk__sseeaarrcchh((_+_Q_u_e_r_y))                                                _[_d_e_t_]


ppaacckk__lliisstt((_+_Q_u_e_r_y))                                                  _[_d_e_t_]
    _Q_u_e_r_y  package server  and installed packages  and display  results.
    _Q_u_e_r_y  is matches case-insensitively against  the name and title  of
    known  and installed packages.  For each matching package,  a single
    line is displayed that provides:

      o  Installation status

           {{ pp:  package, not installed

           {{ ii:  installed package; up-to-date with public version

           {{ UU: installed package; can be upgraded

           {{ AA: installed package; newer than publically available

           {{ ll:  installed package; not on server

      o  Name@Version

      o  Name@Version(ServerVersion)

      o  Title

    Hint:  ?- pack_list(''). lists all packages.

    The  predicates pack_list/1 and  pack_search/1 are synonyms.    Both
    contact  the  package server  at http://www.swi-prolog.org  to  find
    available packages.

         SSeeee aallssoo pack_list_installed/0 to  list installed packages
             without contacting the server.


ppaacckk__iinnssttaallll((_+_S_p_e_c_:_a_t_o_m))                                           _[_d_e_t_]
    Install a package.  _S_p_e_c is one of

      o  Archive file name

      o  HTTP URL of an archive file name.  This URL  may contain a star
         (*) for the  version.   In this case pack_install asks for  the
         deirectory content and selects the latest version.

      o  GIT URL (not well supported yet)

      o  A local directory name given as file:// URL.

      o  A  package name.     This  queries the  package  repository  at
         http://www.swi-prolog.org

    After  resolving the type of  package, pack_install/2 is used to  do
    the actual installation.


ppaacckk__iinnssttaallll((_+_N_a_m_e_, _+_O_p_t_i_o_n_s))                                      _[_d_e_t_]
    Install  package  _N_a_m_e.    Processes the  options  below.    Default
    options as  would be used by pack_install/1are  used to complete the
    provided _O_p_t_i_o_n_s.

    uurrll((_+_U_R_L))
         Source for downloading the package

    ppaacckkaaggee__ddiirreeccttoorryy((_+_D_i_r))
         Directory into which to install the package

    iinntteerraaccttiivvee((_+_B_o_o_l_e_a_n))
         Use  default answer  without  asking the  user  if there  is  a
         default action.

    ssiilleenntt((_+_B_o_o_l_e_a_n))
         If  true  (default  false),   suppress  informational  progress
         messages.

    uuppggrraaddee((_+_B_o_o_l_e_a_n))
         If true  (default  false),  upgrade package  if it  is  already
         installed.

    ggiitt((_+_B_o_o_l_e_a_n))
         If true  (default false  unless _U_R_L ends  with =.git=),  assume
         the URL is a GIT repository.

    Non-interactive  installation can  be established  using the  option
    interactive(false).    It is  adviced to install  from a  particular
    _t_r_u_s_t_e_d   URL  instead  of  the  plain  pack  name   for  unattented
    operation.


ppaacckk__uurrll__ffiillee((_+_U_R_L_, _-_F_i_l_e))                                         _[_d_e_t_]
    True  if _F_i_l_e is  a unique id for  the referenced pack and  version.
    Normally, that is  simply the base name, but GitHub archives destroy
    this picture.  Needed by the pack manager.


ppaacckk__rreebbuuiilldd((_+_P_a_c_k))                                                _[_d_e_t_]
    Rebuilt possible foreign components of _P_a_c_k.


ppaacckk__rreebbuuiilldd                                                       _[_d_e_t_]
    Rebuild foreign components of all packages.


eennvviirroonnmmeenntt((_-_N_a_m_e_, _-_V_a_l_u_e))                           _[_n_o_n_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Hook   to  define  the  environment  for  building  packs.      This
    Multifile hook extends  the process environment for building foreign
    extensions.    A  value  provided by  this hook  overrules  defaults
    provided  by  def_environment/2.     In  addition  to  changing  the
    environment,  this  may be  used to  pass additional  values to  the
    environment, as in:

    ____________________________________________________________________|                                                                    |
    | prolog_pack:environment('USER', User) :-                           |
    ||____getenv('USER',_User)._________________________________________ ||

    ___________________________________________________________Arguments_
     _N_a_m_e   is an atom denoting a valid variable name
     _V_a_l_u_e  is  either an  atom or  number representing  the
            value of the variable.


ppaacckk__uuppggrraaddee((_+_P_a_c_k))                                            _[_s_e_m_i_d_e_t_]
    Try to upgrade the package _P_a_c_k.

         TToo bbee ddoonnee Update  dependencies when updating  a pack from
             git?


ppaacckk__rreemmoovvee((_+_N_a_m_e))                                                 _[_d_e_t_]
    Remove the indicated package.


ppaacckk__pprrooppeerrttyy((_?_P_a_c_k_, _?_P_r_o_p_e_r_t_y))                                 _[_n_o_n_d_e_t_]
    True  when  _P_r_o_p_e_r_t_y is  a property  of  an installed  _P_a_c_k.    This
    interface  is intended for programs  that wish to interact with  the
    package manager.  Defined properties are:

    ddiirreeccttoorryy((_D_i_r_e_c_t_o_r_y))
         _D_i_r_e_c_t_o_r_y into which the package is installed

    vveerrssiioonn((_V_e_r_s_i_o_n))
         Installed version

    ttiittllee((_T_i_t_l_e))
         Full title of the package

    aauutthhoorr((_A_u_t_h_o_r))
         Registered author

    ddoowwnnllooaadd((_U_R_L))
         Official download _U_R_L

    rreeaaddmmee((_F_i_l_e))
         Package README file (if present)

    ttooddoo((_F_i_l_e))
         Package TODO file (if present)


1133..2277 lliibbrraarryy((pprroolloogg__xxrreeff))::  CCrroossss--rreeffeerreennccee ddaattaa ccoolllleeccttiioonn lliibbrraarryy

This library collects information on defined and used  objects in Prolog
source  files.    Typically these  are  predicates,  but we  expect  the
library  to deal  with  other types  of  objects in  the  future.    The
library  is a  building block  for tools  doing  dependency tracking  in
applications.  Dependency tracking is useful to reveal  the structure of
an unknown  program or detect  missing components  at compile time,  but
also for program  transformation or minimising a program saved  state by
only saving the reachable objects.

This section gives  a partial description of the library  API, providing
some insight  in how you  can use it  for analysing your  program.   The
library should be  further modularized, moving its knowledge about,  for
example, XPCE  into a different file  and allowing for adding  knowledge
about other  libraries such  as Logtalk.   PPlleeaassee  ddoo nnoott ccoonnssiiddeerr  tthhiiss
iinntteerrffaaccee rroocckk--ssoolliidd..

The  library is  exploited  by two  graphical  tools in  the  SWI-Prolog
environment:   the XPCE front-end  started by  gxref/0 and described  in
section ????, and  PceEmacs (section ????), which exploits this  library for
its syntax colouring.

For  all predicates  described  below,  _S_o_u_r_c_e  is the  source  that  is
processed.    This is  normally a  filename in  any notation  acceptable
to the  file loading  predicates (see  load_files/2).    Using the  hooks
defined in  section ???? it  can be anything else  that can be  translated
into  a Prolog  stream  holding  Prolog source  text.    _C_a_l_l_a_b_l_e  is  a
callable  term (see  callable/1).    Callables  do  not carry  a  module
qualifier unless  the referred predicate  is not  in the module  defined
_S_o_u_r_c_e.


xxrreeff__ssoouurrccee((_+_S_o_u_r_c_e))
    Gather information on  _S_o_u_r_c_e.  If _S_o_u_r_c_e has already been processed
    and  is still up-to-date according to the file timestamp,  no action
    is  taken.     This  predicate  must be  called  on  a  file  before
    information can be gathered.


xxrreeff__ccuurrrreenntt__ssoouurrccee((_?_S_o_u_r_c_e))
    _S_o_u_r_c_e has been processed.


xxrreeff__cclleeaann((_+_S_o_u_r_c_e))
    Remove the information gathered for _S_o_u_r_c_e


xxrreeff__ddeeffiinneedd((_?_S_o_u_r_c_e_, _?_C_a_l_l_a_b_l_e_, _-_H_o_w))
    _C_a_l_l_a_b_l_e is defined in _S_o_u_r_c_e.  _H_o_w is one of

             dynamic(_L_i_n_e)       Declared dynamic at _L_i_n_e

             thread_local(_L_i_n_e)  Declared thread local at _L_i_n_e
             multifile(_L_i_n_e)     Declared multifile at _L_i_n_e
             local(_L_i_n_e)         First clause at _L_i_n_e
             foreign(_L_i_n_e)       Foreign library loaded at _L_i_n_e
             constraint(_L_i_n_e)    CHR Constraint at _L_i_n_e
             imported(_F_i_l_e)      Imported from _F_i_l_e


xxrreeff__ccaalllleedd((_?_S_o_u_r_c_e_, _?_C_a_l_l_a_b_l_e_, _?_B_y))
    _C_a_l_l_a_b_l_e is called in _S_o_u_r_c_e by _B_y.


xxrreeff__eexxppoorrtteedd((_?_S_o_u_r_c_e_, _?_C_a_l_l_a_b_l_e))
    _C_a_l_l_a_b_l_e is public (exported from the module).


xxrreeff__mmoodduullee((_?_S_o_u_r_c_e_, _?_M_o_d_u_l_e))
    _S_o_u_r_c_e is a module file defining the given module.


xxrreeff__bbuuiilltt__iinn((_?_C_a_l_l_a_b_l_e))
    True  if  _C_a_l_l_a_b_l_e is  a  built-in predicate.    Currently  this  is
    assumed  for all predicates defined in the system module  and having
    the  property built_in.  Built-in  predicates are not registered  as
    `called'.


1133..2277..11 EExxtteennddiinngg tthhee lliibbrraarryy

The library provides hooks  for extending the rules it uses  for finding
predicates called by some programming construct.


pprroolloogg::ccaalllleedd__bbyy((_+_G_o_a_l_, _-_C_a_l_l_e_d))
    _G_o_a_l is a  non-var subgoal appearing in the called object (typically
    a  clause body).   If  it succeeds it  must return  a list of  goals
    called  by _G_o_a_l.    As a  special construct,  if a  term Callable +N
    is  returned,  N variable  arguments are  added to  _C_a_l_l_a_b_l_e before
    further  processing.  For simple meta-calls a single  fact suffices.
    Complex  rules as  used in  the html_write library  provided by  the
    HTTP  package examine  the  arguments and  create a  list of  called
    objects.

    The  current  system   cannot  deal  with  the  same  name/arity  in
    different  modules that  behave differently with  respect to  called
    arguments.


1133..2288 lliibbrraarryy((qquuaassii__qquuoottaattiioonnss))::  DDeeffiinnee QQuuaassii QQuuoottaattiioonn ssyynnttaaxx

    aauutthhoorr  Jan Wielemaker.    Introduction of Quasi  Quotation was
         suggested by Michael Hendricks.

    SSeeee aallssoo  http://www.cs.tufts.edu/comp/150FP/archive/geoff-
         mainland/quasiquoting.pdfWhy  it's  nice   to  be  quoted:
         quasiquoting for haskell

Inspired  by   http://www.haskell.org/haskellwiki/QuasiquotationHaskell,
SWI-Prolog  support  _q_u_a_s_i  _q_u_o_t_a_t_i_o_n.     Quasi  quotation  allows  for
embedding  (long) strings  using  the  syntax of  an  external  language
(e.g., HTML,  SQL) in Prolog text  and syntax-aware embedding of  Prolog
variables in this  syntax.  At  the same time, quasi quotation  provides
an alternative to represent long strings and atoms in Prolog.

The basic  form of a  quasi quotation is  defined below.   Here,  _S_y_n_t_a_x
is an  arbitrary Prolog term  that must parse into  a _c_a_l_l_a_b_l_e (atom  or
compound) term  and Quotation  is an arbitrary  sequence of  characters,
not including the sequence  |}.  If this sequence needs to  be embedded,
it must be escaped according to the rules of the  target language or the
`quoter' must provide an escaping mechanism.

________________________________________________________________________|                                                                        |

|{|Syntax||Quotation|}|_________________________________________________ |                     |

While reading  a Prolog  term, and  if the Prolog  flag quasi_quotes  is
set to true  (which is the case if  this library is loaded), the  parser
collects  quasi quotations.    After reading  the final  full stop,  the
parser makes  the call  below.   Here,  _S_y_n_t_a_x_N_a_m_e is  the functor  name
of _S_y_n_t_a_x above  and _S_y_n_t_a_x_A_r_g_s is a  list holding the arguments,  i.e.,
Syntax =.. [SyntaxName|SyntaxArgs].  Splitting the syntax  into its name
and arguments  is done to  make the quasi  quotation parser a  predicate
with  a consistent  arity  4, regardless  of  the number  of  additional
arguments.

________________________________________________________________________|                                                                        |
|call(+SyntaxName,|+Content,_+SyntaxArgs,_+VariableNames,_-Result)______ |                 |

The arguments are defined as

  o _S_y_n_t_a_x_N_a_m_e  is the principal functor of the quasi  quotation syntax.
    This  must be declared using quasi_quotation_syntax/1and  there must
    be a predicate SyntaxName/4.

  o _C_o_n_t_e_n_t  is an  opaque term that  carries the  content of the  quasi
    quoted material and  position information about the source code.  It
    is passed to with_quasi_quote_input/3.

  o _S_y_n_t_a_x_A_r_g_s  carries the additional arguments  of the _S_y_n_t_a_x.   These
    are  commonly used to make the parameter passing between  the clause
    and the quasi quotation explicit.  For example:

    ____________________________________________________________________|                                                                    |

    |     ...,                                                           |
    |     {|html(Name, Address)||                                        |
    |      <tr><td>Name<td>Address</tr>                                  |
    ||_____|}___________________________________________________________ ||

  o _V_a_r_i_a_b_l_e_N_a_m_e_s  is the  complete  variable dictionary  of the  clause
    as  it   is  made  available  throug  read_term/3  with  the  option
    variable_names.  It is a list of terms Name = Var.

  o _R_e_s_u_l_t  is  a  variable that  must  be  unified to  resulting  term.
    Typically,  this  term  is structured  Prolog  tree that  carries  a
    (partial)  representation of the abstract syntax tree  with embedded
    variables  that pass the Prolog parameters.   This term is  normally
    either  passed to  a predicate that  serializes the abstract  syntax
    tree,  or a  predicate that  processes the  result in Prolog.    For
    example,  HTML  is  commonly  embedded for  writing  HTML  documents
    (see  library(http/html_write)).  Examples of languages that  may be
    embedded  for processing  in Prolog  are SPARQL,  RuleML or  regular
    expressions.

The  file library(http/html_quasiquotations)  provides the,  suprisingly
simple, quasi quotation parser for HTML.


wwiitthh__qquuaassii__qquuoottaattiioonn__iinnppuutt((_+_C_o_n_t_e_n_t_, _-_S_t_r_e_a_m_, _:_G_o_a_l))                _[_d_e_t_]
    Process  the  quasi-quoted  _C_o_n_t_e_n_t  using _S_t_r_e_a_m  parsed  by  _G_o_a_l.
    _S_t_r_e_a_m is a temporary stream with the following properties:

      o  Its initial _p_o_s_i_t_i_o_n  represents the position  of the start  of
         the quoted material.

      o  It is a text stream, using utf8 _e_n_c_o_d_i_n_g.

      o  It allows for repositioning

      o  It will be closed after _G_o_a_l completes.

    ___________________________________________________________Arguments_
     _G_o_a_l  is  executed as once(Goal).  _G_o_a_l must  succeed.
           Failure or exceptions from _G_o_a_l are  interpreted
           as syntax errors.

         SSeeee aallssoo phrase_from_quasi_quotation/2  can  be   used  to
             process a quotation using a grammar.


pphhrraassee__ffrroomm__qquuaassii__qquuoottaattiioonn((_:_G_r_a_m_m_a_r_, _+_C_o_n_t_e_n_t))                     _[_d_e_t_]
    Process  the quasi quotation using the DCG _G_r_a_m_m_a_r.  Failure  of the
    grammar is interpreted as a syntax error.

         SSeeee aallssoo with_quasi_quotation_input/3 for  processing quo-
             tations from stream.


qquuaassii__qquuoottaattiioonn__ssyynnttaaxx((_:_S_y_n_t_a_x_N_a_m_e))                                _[_d_e_t_]
    Declare the predicate  _S_y_n_t_a_x_N_a_m_e/4 to implement the the quasi quote
    syntax _S_y_n_t_a_x_N_a_m_e.  Normally used as a directive.


qquuaassii__qquuoottaattiioonn__ssyynnttaaxx__eerrrroorr((_+_E_r_r_o_r))
    Report  syntax_error(Error) using the current location in  the quasi
    quoted input parser.

         tthhrroowwss error(syntax_error(Error), Position)


1133..2299 lliibbrraarryy((rraannddoomm))::  RRaannddoomm nnuummbbeerrss

    aauutthhoorr  R.A. O'Keefe, V.S. Costa, L. Damas, Jan Wielemaker

    SSeeee aallssoo  Built-in function random/1:  A is random(10)

This  library  is  derived  from the  DEC10  library  random.     Later,
the  core random  generator was  moved to  C. The  current version  uses
the SWI-Prolog  arithmetic functions  to realise  this library.    These
functions are based on the GMP library.


rraannddoomm((_-_R_:_f_l_o_a_t))                                                  _[_d_e_t_]
    Binds _R to a new random float in the _o_p_e_n interval (0.0,1.0).

         SSeeee aallssoo
             -  setrand/1, getrand/1 may  be used  to fetch/set the
             state.
             -  In  SWI-Prolog,  random/1  is  implemented  by  the
             function random_float/0.


rraannddoomm__bbeettwweeeenn((_+_L_:_i_n_t_, _+_U_:_i_n_t_, _-_R_:_i_n_t))                         _[_s_e_m_i_d_e_t_]
    Binds  _R to a random  integer in [_L,_U]  (i.e., including both _L  and
    _U). Fails silently if _U<_L.


rraannddoomm((_+_L_:_i_n_t_, _+_U_:_i_n_t_, _-_R_:_i_n_t))                                    _[_d_e_t_]


rraannddoomm((_+_L_:_f_l_o_a_t_, _+_U_:_f_l_o_a_t_, _-_R_:_f_l_o_a_t))                              _[_d_e_t_]
    Generate a random integer or  float in a range.  If _L and _U are both
    integers, _R is a  random integer in the half open interval [_L,_U). If
    _L and _U are both floats, _R is a float in the open interval (_L,_U).

         ddeepprreeccaatteedd Please  use  random/1 for  generating  a random
             float  and  random_between/3 for  generating  a random
             integer.     Note that  random_between/3  includes the
             upper bound, while this predicate excludes it.


sseettrraanndd((_+_S_t_a_t_e))                                                   _[_d_e_t_]


ggeettrraanndd((_-_S_t_a_t_e))                                                   _[_d_e_t_]
    Query/set  the state of the random generator.  This is  intended for
    restarting  the generator  at a  known state  only.   The  predicate
    setrand/1  accepts an opaque term returned by getrand/1.   This term
    may  be asserted, written  and read.   The application may not  make
    other assumptions about this term.

    For  compatibility  reasons with  older  versions of  this  library,
    setrand/1  also accepts  a term rand(A,B,C),  where A,  B and C  are
    integers in the range  1..30,000.  This argument is used to seed the
    random generator.  Deprecated.

         EErrrroorrss existence_error(random_state, _)  is raised  if the
             underlying  infrastructure  cannot  fetch  the  random
             state.   This is  currently the case  if SWI-Prolog is
             not compiled with the GMP library.

         SSeeee aallssoo set_random/1  and  random_property/1 provide  the
             SWI-Prolog native implementation.


mmaayybbee                                                         _[_s_e_m_i_d_e_t_]
    Succeed/fail with equal probability (variant of maybe/1).


mmaayybbee((_+_P))                                                     _[_s_e_m_i_d_e_t_]
    Succeed with probability _P, fail with probability 1-_P


mmaayybbee((_+_K_, _+_N))                                                 _[_s_e_m_i_d_e_t_]
    Succeed with probability _K/_N (variant of maybe/1)


rraannddoomm__ppeerrmm22((_?_A_, _?_B_, _?_X_, _?_Y))                                   _[_s_e_m_i_d_e_t_]
    Does _X=_A,_Y=_B or _X=_B,_Y=_A with equal probability.


rraannddoomm__mmeemmbbeerr((_-_X_, _+_L_i_s_t_:_l_i_s_t))                                  _[_s_e_m_i_d_e_t_]
    _X  is  a random  member of  _L_i_s_t.   Equivalent  to random_between(1,
    |_L_i_s_t|), followed by nth1/3.  Fails of _L_i_s_t is the empty list.

         CCoommppaattiibbiilliittyy Quintus and SICStus libraries.


rraannddoomm__sseelleecctt((_-_X_, _+_L_i_s_t_, _-_R_e_s_t))                                _[_s_e_m_i_d_e_t_]


rraannddoomm__sseelleecctt((_+_X_, _-_L_i_s_t_, _+_R_e_s_t))                                    _[_d_e_t_]
    Randomly  select or insert an element.  Either _L_i_s_t or _R_e_s_t  must be
    a list.  Fails if _L_i_s_t is the empty list.

         CCoommppaattiibbiilliittyy Quintus and SICStus libraries.


rraannddsseett((_+_K_:_i_n_t_, _+_N_:_i_n_t_, _-_S_:_l_i_s_t_(_i_n_t_)))                             _[_d_e_t_]
    _S  is a sorted list of _K  unique random integers in the  range 1.._N.
    Implemented  by enumerating  1.._N and  deciding whether  or not  the
    number should be part of the set.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- randset(5, 5, S).                                               |

    | S = [1, 2, 3, 4, 5].          (always)                             |
    | ?- randset(5, 20, S).                                              |
    ||S_=_[2,_7,_10,_19,_20].___________________________________________ ||

         SSeeee aallssoo randseq/3.

         bbuugg Slow if _N is large and _K is small.


rraannddsseeqq((_+_K_:_i_n_t_, _+_N_:_i_n_t_, _-_L_i_s_t_:_l_i_s_t_(_i_n_t_)))                          _[_d_e_t_]
    S  is a  list of _K  unique random  integers in the  range 1.._N.  The
    order is random.  Works as if defined by the following code.

    ____________________________________________________________________|                                                                    |
    | randseq(K, N, List) :-                                             |

    |       randset(K, N, Set),                                          |
    ||______random_permutation(Set,_List).______________________________ ||

         SSeeee aallssoo randset/3.


rraannddoomm__ppeerrmmuuttaattiioonn((_+_L_i_s_t_, _-_P_e_r_m_u_t_a_t_i_o_n))                            _[_d_e_t_]


rraannddoomm__ppeerrmmuuttaattiioonn((_-_L_i_s_t_, _+_P_e_r_m_u_t_a_t_i_o_n))                            _[_d_e_t_]
    _P_e_r_m_u_t_a_t_i_o_n  is a random permutation of  _L_i_s_t.  This is intended  to
    process  the elements of  _L_i_s_t in  random order.   The predicate  is
    symmetric.

         EErrrroorrss instantiation_error, type_error(list, _).


1133..3300 lliibbrraarryy((rreeaadduuttiill))::  RReeaaddiinngg lliinneess,, ssttrreeaammss aanndd ffiilleess

This library contains  primitives to read lines, files,  multiple terms,
etc.   The package clib provides  a shared object (DLL) named  readutil.
If the  library can locate  this shared object it  will use the  foreign
implementation for  reading character codes.   Otherwise  it will use  a
Prolog implementation.    Distributed applications should  make sure  to
deliver the  readutil shared object if  performance of these  predicates
is critical.


rreeaadd__lliinnee__ttoo__ccooddeess((_+_S_t_r_e_a_m_, _-_C_o_d_e_s))
    Read  the  next line  of  input from  _S_t_r_e_a_m  and unify  the  result
    with  _C_o_d_e_s _a_f_t_e_r the  line has  been read.   A line  is ended by  a
    newline character or end-of-file.  Unlike  read_line_to_codes/3, this
    predicate removes a trailing newline character.

    On  end-of-file  the  atom  end_of_file  is  returned.     See  also
    at_end_of_stream/[0,1].


rreeaadd__lliinnee__ttoo__ccooddeess((_+_S_t_r_e_a_m_, _-_C_o_d_e_s_, _?_T_a_i_l))
    Difference-list  version  to  read  an  input  line  to  a  list  of
    character  codes.    Reading  stops at  the newline  or  end-of-file
    character,  but unlike read_line_to_codes/2, the newline  is retained
    in  the output.  This  predicate is especially useful for reading  a
    block  of lines up to some  delimiter.  The following example  reads
    an HTTP header ended by a blank line:

    ____________________________________________________________________|                                                                    |
    | read_header_data(Stream, Header) :-                                |

    |         read_line_to_codes(Stream, Header, Tail),                  |
    |         read_header_data(Header, Stream, Tail).                    |
    |                                                                    |
    | read_header_data("\r\n", _, _) :- !.                               |
    | read_header_data("\n", _, _) :- !.                                 |
    | read_header_data("", _, _) :- !.                                   |
    | read_header_data(_, Stream, Tail) :-                               |
    |         read_line_to_codes(Stream, Tail, NewTail),                 |

    ||________read_header_data(Tail,_Stream,_NewTail).__________________ ||


rreeaadd__ssttrreeaamm__ttoo__ccooddeess((_+_S_t_r_e_a_m_, _-_C_o_d_e_s))
    Read all input until end-of-file and unify the result to _C_o_d_e_s.


rreeaadd__ssttrreeaamm__ttoo__ccooddeess((_+_S_t_r_e_a_m_, _-_C_o_d_e_s_, _?_T_a_i_l))
    Difference-list version of read_stream_to_codes/2.


rreeaadd__ffiillee__ttoo__ccooddeess((_+_S_p_e_c_, _-_C_o_d_e_s_, _+_O_p_t_i_o_n_s))
    Read  a  file  to a  list  of  character codes.    _S_p_e_c  is  a  file
    specification  for  absolute_file_name/3.    _C_o_d_e_s is  the  resulting
    code  list.  _O_p_t_i_o_n_s  is a list of  options for absolute_file_name/3
    and open/4.   In addition, the option tail(_T_a_i_l) is defined, forming
    a difference-list.


rreeaadd__ffiillee__ttoo__tteerrmmss((_+_S_p_e_c_, _-_T_e_r_m_s_, _+_O_p_t_i_o_n_s))
    Read  a  file  to  a list  of  Prolog  terms  (see read/1).     _S_p_e_c
    is  a file  specification for  absolute_file_name/3.    _T_e_r_m_s is  the
    resulting  list of  Prolog  terms.   _O_p_t_i_o_n_s  is a  list of  options
    for  absolute_file_name/3 and  open/4.    In  addition,  the  option
    tail(_T_a_i_l) is defined, forming a difference-list.


1133..3311 lliibbrraarryy((rreeccoorrdd))::  AAcccceessss nnaammeedd ffiieellddss iinn aa tteerrmm

The  library  record  provides  named  access  to  fields  in  a  record
represented as a  compound term such as  point(X, Y).  The Prolog  world
knows various  approaches to solve this  problem, unfortunately with  no
consensus.   The approach taken by  this library is proposed by  Richard
O'Keefe on the SWI-Prolog mailinglist.

The  approach  automates  a  technique  commonly   described  in  Prolog
text-books,  where access and  modification predicates  are defined  for
the record type.   Such predicates  are subject to normal  import/export
as well as  analysis by cross-referencers.   Given the simple nature  of
the access  predicates, an  optimizing compiler can  easily inline  them
for optimal preformance.

A record  is defined  using the directive  record/1.   We introduce  the
library with a short example:

________________________________________________________________________|                                                                        |
|:- record point(x:integer=0, y:integer=0).                              |

|                                                                        |
|        ...,                                                            |
|        default_point(Point),                                           |
|        point_x(Point, X),                                              |
|        set_x_of_point(10, Point, Point1),                              |
|                                                                        |
||_______make_point([y(20)],_YPoint),___________________________________ ||

The principal functor  and arity of the  term used defines the name  and
arity of  the compound  used as  records.   Each  argument is  described
using a term of the format below.

    <_n_a_m_e>[:<_t_y_p_e>][=<_d_e_f_a_u_l_t>]

In this definition, <_n_a_m_e> is an atom defining the name of the argument,
<_t_y_p_e> is  an optional type  specification as  defined by must_be/2 from
library error,  and <_d_e_f_a_u_l_t> is the default  initial value.   The <_t_y_p_e>
defaults to  any.  If  no default value is  specified the default is  an
unbound variable.

A  record  declaration  creates  a  set  of   predicates  through  _t_e_r_m_-
_e_x_p_a_n_s_i_o_n.   We describe these predicates  below.  In this  description,
<_c_o_n_s_t_r_u_c_t_o_r> refers to  the name of the record  (`point' in the example
above) and <_n_a_m_e> to the name of an argument (field).

  o _d_e_f_a_u_l_t__<_c_o_n_s_t_r_u_c_t_o_r>_(_-_R_e_c_o_r_d_)
    Create  a new  record where  all fields have  their default  values.
    This is the same as make_<_c_o_n_s_t_r_u_c_t_o_r>([], Record).

  o _m_a_k_e__<_c_o_n_s_t_r_u_c_t_o_r>_(_+_F_i_e_l_d_s_, _-_R_e_c_o_r_d_)
    Create  a  new  record where  specified  fields have  the  specified
    values  and  remaining  fields  have  their default  value.     Each
    field  is specified as  a term <_n_a_m_e>(<_v_a_l_u_e>).   See example  in the
    introduction.

  o _m_a_k_e__<_c_o_n_s_t_r_u_c_t_o_r>_(_+_F_i_e_l_d_s_, _-_R_e_c_o_r_d_, _-_R_e_s_t_F_i_e_l_d_s_)
    Same as  make_<_c_o_n_s_t_r_u_c_t_o_r>/2, but named fields that do not appear in
    _R_e_c_o_r_d  are returned in _R_e_s_t_F_i_e_l_d_s.  This predicate is  motivated by
    option-list processing.  See library option.

  o <_c_o_n_s_t_r_u_c_t_o_r>_<_n_a_m_e>_(_R_e_c_o_r_d_, _V_a_l_u_e_)
    Unify _V_a_l_u_e with argument in _R_e_c_o_r_d named <_n_a_m_e>.

  o <_c_o_n_s_t_r_u_c_t_o_r>__d_a_t_a_(_?_N_a_m_e_, _+_R_e_c_o_r_d_, _?_V_a_l_u_e_)
    True  when _V_a_l_u_e is  the value for the  field named _N_a_m_e in  _R_e_c_o_r_d.
    This predicate does not perform type-checking.

  o _s_e_t__<_n_a_m_e>__o_f__<_c_o_n_s_t_r_u_c_t_o_r>_(_+_V_a_l_u_e_, _+_O_l_d_R_e_c_o_r_d_, _-_N_e_w_R_e_c_o_r_d_)
    Replace  the value for  <_n_a_m_e> in  _O_l_d_R_e_c_o_r_d by _V_a_l_u_e  and unify the
    result with _N_e_w_R_e_c_o_r_d.

  o _s_e_t__<_n_a_m_e>__o_f__<_c_o_n_s_t_r_u_c_t_o_r>_(_+_V_a_l_u_e_, _!_R_e_c_o_r_d_)
    Destructively  replace the argument <_n_a_m_e> in  _R_e_c_o_r_d by _V_a_l_u_e based
    on setarg/3.  Use with care.

  o _n_b___s_e_t__<_n_a_m_e>__o_f__<_c_o_n_s_t_r_u_c_t_o_r>_(_+_V_a_l_u_e_, _!_R_e_c_o_r_d_)
    As   above,   but  using  non-backtrackable   assignment  based   on
    nb_setarg/3.  Use with _e_x_t_r_e_m_e care.

  o _s_e_t__<_c_o_n_s_t_r_u_c_t_o_r>__f_i_e_l_d_s_(_+_F_i_e_l_d_s_, _+_R_e_c_o_r_d_0_, _-_R_e_c_o_r_d_)
    Set  multiple fields using  the same syntax  as make_<_c_o_n_s_t_r_u_c_t_o_r>/2,
    but starting with _R_e_c_o_r_d_0 rather than the default record.

  o _s_e_t__<_c_o_n_s_t_r_u_c_t_o_r>__f_i_e_l_d_s_(_+_F_i_e_l_d_s_, _+_R_e_c_o_r_d_0_, _-_R_e_c_o_r_d_, _-_R_e_s_t_F_i_e_l_d_s_)
    Similar  to  set_<_c_o_n_s_t_r_u_c_t_o_r>_fields/4, but  fields  not  defined by
    <_c_o_n_s_t_r_u_c_t_o_r> are returned in _R_e_s_t_F_i_e_l_d_s.

  o _s_e_t__<_c_o_n_s_t_r_u_c_t_o_r>__f_i_e_l_d_(_+_F_i_e_l_d_, _+_R_e_c_o_r_d_0_, _-_R_e_c_o_r_d_)
    Set a single field specified as a term <_n_a_m_e>(<_v_a_l_u_e>).


rreeccoorrdd((_+_S_p_e_c))
    The  construct  :- record Spec, ...  is  used to  define  access  to
    named  fields in a compound.   It is subject to term-expansion  (see
    expand_term/2) and cannot be called as a predicate.   See section ????
    for details.


1133..3322 lliibbrraarryy((rreeggiissttrryy))::  MMaanniippuullaattiinngg tthhee WWiinnddoowwss rreeggiissttrryy

The registry is only available on the MS-Windows  version of SWI-Prolog.
It loads  the foreign extension  plregtry.dll, providing the  predicates
described below.   This  library only makes  the most common  operations
on the registry available  through the Prolog user.  The  underlying DLL
provides a  more complete coverage of  the Windows registry API.  Please
consult  the  sources  in  pl/src/win32/foreign/plregtry.c  for  further
details.

In  all these  predicates,  _P_a_t_h refers  to a  `/' separated  path  into
the registry.   This  is _n_o_t an atom  containing `/'-characters as  used
for  filenames, but  a term  using the  functor  //2.   Windows  defines
the  following  roots for  the  registry:   classes_root,  current_user,
local_machine and users.


rreeggiissttrryy__ggeett__kkeeyy((_+_P_a_t_h_, _-_V_a_l_u_e))
    Get  the principal (default)  value associated to  this key.   Fails
    silently if the key does not exist.


rreeggiissttrryy__ggeett__kkeeyy((_+_P_a_t_h_, _+_N_a_m_e_, _-_V_a_l_u_e))
    Get a named value associated to this key.


rreeggiissttrryy__sseett__kkeeyy((_+_P_a_t_h_, _+_V_a_l_u_e))
    Set the principal (default)  value of this key.  Creates (a path to)
    the key if it does not already exist.


rreeggiissttrryy__sseett__kkeeyy((_+_P_a_t_h_, _+_N_a_m_e_, _+_V_a_l_u_e))
    Associate  a named value to this key.   Creates (a path to)  the key
    if it does not already exist.


rreeggiissttrryy__ddeelleettee__kkeeyy((_+_P_a_t_h))
    Delete the indicated key.


sshheellll__rreeggiisstteerr__ffiillee__ttyyppee((_+_E_x_t_, _+_T_y_p_e_, _+_N_a_m_e_, _+_O_p_e_n_A_c_t_i_o_n))
    Register  a file-type.   _E_x_t is  the extension to  associate.   _T_y_p_e
    is  the type name,  often something like prolog.type.   _N_a_m_e is  the
    name visible in  the Windows file-type browser.  Finally, _O_p_e_n_A_c_t_i_o_n
    defines  the action to  execute when a  file with this extension  is
    opened in the Windows explorer.


sshheellll__rreeggiisstteerr__ddddee((_+_T_y_p_e_, _+_A_c_t_i_o_n_, _+_S_e_r_v_i_c_e_, _+_T_o_p_i_c_, _+_C_o_m_m_a_n_d_, _+_I_f_N_o_t_R_u_n_n_i_n_g))
    Associate DDE actions to  a type.  _T_y_p_e is the same type as used for
    the 2nd argument of shell_register_file_type/4, _A_c_t_i_o_n is the action
    to  perform, _S_e_r_v_i_c_e  and _T_o_p_i_c  specify the DDE  topic to  address,
    and  _C_o_m_m_a_n_d is  the command  to execute on  this topic.    Finally,
    _I_f_N_o_t_R_u_n_n_i_n_g  defines the  command to  execute if  the required  DDE
    server is not present.


sshheellll__rreeggiisstteerr__pprroolloogg((_+_E_x_t))
    Default registration of  SWI-Prolog, which is invoked as part of the
    initialisation  process on  Windows  systems.   As  the source  also
    includes the above predicates, it is given as an example:

    ____________________________________________________________________|                                                                    |
    | shell_register_prolog(Ext) :-                                      |

    |         current_prolog_flag(argv, [Me|_]),                         |
    |         atomic_list_concat(['"', Me, '" "%1"'], OpenCommand),      |
    |         shell_register_file_type(                                  |
    |             Ext, 'prolog.type', 'Prolog Source', OpenCommand),     |
    |         shell_register_dde(                                        |
    |             'prolog.type', consult,                                |
    |             prolog, control, 'consult(''%1'')', Me),               |
    |         shell_register_dde(                                        |

    |             'prolog.type', edit,                                   |
    ||____________prolog,_control,_'edit(''%1'')',_Me)._________________ ||


1133..3333 lliibbrraarryy((ssiimmpplleexx))::  SSoollvvee lliinneeaarr pprrooggrraammmmiinngg pprroobblleemmss

    aauutthhoorr  https://www.metalevel.atMarkus Triska


1133..3333..11 IInnttrroodduuccttiioonn

A lliinneeaarr pprrooggrraammmmiinngg pprroobblleemm or simply lliinneeaarr pprrooggrraamm (LP) consists of:

  o a set of _l_i_n_e_a_r ccoonnssttrraaiinnttss

  o a set of vvaarriiaabblleess

  o a _l_i_n_e_a_r oobbjjeeccttiivvee ffuunnccttiioonn.

The goal  is to assign  values to  the variables so  as to _m_a_x_i_m_i_z_e  (or
minimize)  the value  of  the objective  function while  satisfying  all
constraints.

Many optimization  problems can be modeled  in this way.   As one  basic
example,  consider a knapsack  with fixed  capacity C, and  a number  of
items with  sizes s(i)  and values v(i).   The  goal is  to put as  many
items as  possible in the  knapsack (not  exceeding its capacity)  while
maximizing the sum of their values.

As another example,  suppose you are given  a set of _c_o_i_n_s with  certain
values, and you are to find the minimum number of  coins such that their
values  sum up  to a  fixed amount.    Instances of  these problems  are
solved below.

Solving  an  LP  or integer  linear  program  (ILP)  with  this  library
typically comprises 4 stages:

 1. an initial state is generated with gen_state/1

 2. all relevant constraints are added with constraint/3

 3. maximize/3  or minimize/3  are used  to obtain a  _s_o_l_v_e_d _s_t_a_t_e  that
    represents an optimum solution

 4. variable_value/3  and objective/2 are  used on  the solved state  to
    obtain variable values and the objective function at the optimum.

The most frequently used predicates are thus:


ggeenn__ssttaattee((_-_S_t_a_t_e))
    Generates  an  initial   state  corresponding  to  an  empty  linear
    program.


ccoonnssttrraaiinntt((_+_C_o_n_s_t_r_a_i_n_t_, _+_S_0_, _-_S))
    Adds  a  linear  or integrality  constraint  to the  linear  program
    corresponding  to state  _S_0.   A linear  constraint is  of the  form
    Left Op C,  where  _L_e_f_t  is  a list  of  Coefficient*Variable  terms
    (variables  in  the  context of  linear  programs  can be  atoms  or
    compound terms) and _C  is a non-negative numeric constant.  The list
    represents  the sum of its elements.   _O_p can be  =, =< or >=.   The
    coefficient  1 can  be omitted.    An integrality  constraint is  of
    the  form integral(Variable) and constrains Variable to  an integral
    value.


mmaaxxiimmiizzee((_+_O_b_j_e_c_t_i_v_e_, _+_S_0_, _-_S))
    Maximizes   the   objective   function,   stated   as  a   list   of
    Coefficient*Variable terms that  represents the sum of its elements,
    with  respect  to  the linear  program  corresponding to  state  _S_0.
    \arg{_S}  is unified  with an internal  representation of  the solved
    instance.


mmiinniimmiizzee((_+_O_b_j_e_c_t_i_v_e_, _+_S_0_, _-_S))
    Analogous to maximize/3.


vvaarriiaabbllee__vvaalluuee((_+_S_t_a_t_e_, _+_V_a_r_i_a_b_l_e_, _-_V_a_l_u_e))
    _V_a_l_u_e  is unified with the value obtained for _V_a_r_i_a_b_l_e.   _S_t_a_t_e must
    correspond to a solved instance.


oobbjjeeccttiivvee((_+_S_t_a_t_e_, _-_O_b_j_e_c_t_i_v_e))
    Unifies  _O_b_j_e_c_t_i_v_e with the result of the objective function  at the
    obtained extremum.  _S_t_a_t_e must correspond to a solved instance.

All numeric  quantities are  converted to  rationals via  rationalize/1,
and rational arithmetic is used throughout solving linear programs.   In
the  current implementation,  all variables  are implicitly  constrained
to  be  _n_o_n_-_n_e_g_a_t_i_v_e.     This  may  change  in  future  versions,   and
non-negativity constraints should therefore be stated explicitly.


1133..3333..22 DDeellaayyeedd ccoolluummnn ggeenneerraattiioonn

_D_e_l_a_y_e_d _c_o_l_u_m_n _g_e_n_e_r_a_t_i_o_n  means that more constraint columns are  added
to an  existing LP. The  following predicates  are frequently used  when
this method is applied:


ccoonnssttrraaiinntt((_+_N_a_m_e_, _+_C_o_n_s_t_r_a_i_n_t_, _+_S_0_, _-_S))
    Like  constraint/3, and attaches the name _N_a_m_e (an atom  or compound
    term) to the new constraint.


sshhaaddooww__pprriiccee((_+_S_t_a_t_e_, _+_N_a_m_e_, _-_V_a_l_u_e))
    Unifies  _V_a_l_u_e with  the shadow  price corresponding  to the  linear
    constraint  whose name is _N_a_m_e.   _S_t_a_t_e must correspond to a  solved
    instance.


ccoonnssttrraaiinntt__aadddd((_+_N_a_m_e_, _+_L_e_f_t_, _+_S_0_, _-_S))
    _L_e_f_t  is a list of Coefficient*Variable terms.  The terms  are added
    to  the left-hand side of the constraint  named _N_a_m_e.  _S  is unified
    with the resulting state.

An    example     application    of     _d_e_l_a_y_e_d    _c_o_l_u_m_n     _g_e_n_e_r_a_t_i_o_n
to    solve    a     _b_i_n    _p_a_c_k_i_n_g    task    is    available     from:
https://www.metalevel.at/various/colgen/mmeettaalleevveell..aatt//vvaarriioouuss//ccoollggeenn//


1133..3333..33 SSoollvviinngg LLPPss wwiitthh ssppeecciiaall ssttrruuccttuurree

The following predicates allow  you to solve specific kinds of  LPs more
efficiently:


ttrraannssppoorrttaattiioonn((_+_S_u_p_p_l_i_e_s_, _+_D_e_m_a_n_d_s_, _+_C_o_s_t_s_, _-_T_r_a_n_s_p_o_r_t))
    Solves  a transportation  problem.    _S_u_p_p_l_i_e_s and  _D_e_m_a_n_d_s must  be
    lists  of non-negative  integers.    Their respective  sums must  be
    equal.    _C_o_s_t_s is  a list of  lists representing  the cost  matrix,
    where  an entry (_i,_j) denotes  the integer cost of transporting  one
    unit  from _i to  _j.   A transportation plan  having minimum cost  is
    computed  and unified with _T_r_a_n_s_p_o_r_t in the form of a list  of lists
    that  represents  the  transportation matrix,  where  element  (_i,_j)
    denotes how many units to ship from _i to _j.


aassssiiggnnmmeenntt((_+_C_o_s_t_, _-_A_s_s_i_g_n_m_e_n_t))
    Solves  a  linear assignment  problem.    _C_o_s_t is  a list  of  lists
    representing   the  quadratic  cost  matrix,  where   element  (i,j)
    denotes  the integer  cost of  assigning entity $i$  to entity  $j$.
    An  assignment  with  minimal  cost is  computed  and  unified  with
    _A_s_s_i_g_n_m_e_n_t as a list of lists, representing an adjacency matrix.


1133..3333..44 EExxaammpplleess

We include a few examples for solving LPs with this library.


1133..3333..44..11 EExxaammppllee 11

This  is the  "radiation therapy"  example, taken  from _I_n_t_r_o_d_u_c_t_i_o_n  _t_o
_O_p_e_r_a_t_i_o_n_s _R_e_s_e_a_r_c_h by Hillier and Lieberman.

https://www.metalevel.at/prolog/dcgPPrroolloogg  DDCCGG   nnoottaattiioonn  is  used   to
_i_m_p_l_i_c_i_t_l_y thread the state through posting the constraints:

________________________________________________________________________|                                                                        |
|:- use_module(library(simplex)).                                        |

|                                                                        |
|radiation(S) :-                                                         |
|        gen_state(S0),                                                  |
|        post_constraints(S0, S1),                                       |
|        minimize([0.4*x1, 0.5*x2], S1, S).                              |
|                                                                        |
|post_constraints -->                                                    |
|        constraint([0.3*x1, 0.1*x2] =< 2.7),                            |

|        constraint([0.5*x1, 0.5*x2] = 6),                               |
|        constraint([0.6*x1, 0.4*x2] >= 6),                              |
|        constraint([x1] >= 0),                                          |
||_______constraint([x2]_>=_0)._________________________________________ ||

An example query:

________________________________________________________________________|                                                                        |
|?- radiation(S), variable_value(S, x1, Val1),                           |
|                 variable_value(S, x2, Val2).                           |

|Val1 = 15 rdiv 2,                                                       |
|Val2|=_9_rdiv_2._______________________________________________________ |    |


1133..3333..44..22 EExxaammppllee 22

Here  is an  instance of  the knapsack  problem described  above,  where
C = 8,  and we  have two types  of items:   One  item with  value 7  and
size 6, and  2 items each having size 4  and value 4.  We  introduce two
variables, x(1)  and x(2)  that denote how  many items  to take of  each
type.

________________________________________________________________________|                                                                        |
|:- use_module(library(simplex)).                                        |

|                                                                        |
|knapsack(S) :-                                                          |
|        knapsack_constraints(S0),                                       |
|        maximize([7*x(1), 4*x(2)], S0, S).                              |
|                                                                        |
|knapsack_constraints(S) :-                                              |
|        gen_state(S0),                                                  |
|        constraint([6*x(1), 4*x(2)] =< 8, S0, S1),                      |

|        constraint([x(1)] =< 1, S1, S2),                                |
||_______constraint([x(2)]_=<_2,_S2,_S).________________________________ ||

An example query yields:

________________________________________________________________________|                                                                        |
|?- knapsack(S), variable_value(S, x(1), X1),                            |
|                variable_value(S, x(2), X2).                            |
|X1 = 1                                                                  |
|X2|=_1_rdiv_2._________________________________________________________ |  |

That is, we are to take the one item of the first  type, and half of one
of the items of the  other type to maximize the total value of  items in
the knapsack.

If items can not be split, integrality constraints have to be imposed:

________________________________________________________________________|                                                                        |

|knapsack_integral(S) :-                                                 |
|        knapsack_constraints(S0),                                       |
|        constraint(integral(x(1)), S0, S1),                             |
|        constraint(integral(x(2)), S1, S2),                             |
||_______maximize([7*x(1),_4*x(2)],_S2,_S)._____________________________ ||

Now the result is different:

________________________________________________________________________|                                                                        |

|?- knapsack_integral(S), variable_value(S, x(1), X1),                   |
|                         variable_value(S, x(2), X2).                   |
|                                                                        |
|X1 = 0                                                                  |
|X2|=_2_________________________________________________________________ |  |

That  is,  we are  to  take  only the  _t_w_o  items of  the  second  type.
Notice in particular  that always choosing the remaining item  with best
performance (ratio  of value to  size) that still  fits in the  knapsack
does  not necessarily  yield  an optimal  solution  in the  presence  of
integrality constraints.


1133..3333..44..33 EExxaammppllee 33

We are given:

  o 3 coins each worth 1 unit

  o 20 coins each worth 5 units and

  o 10 coins each worth 20 units.

The task is to find  a _m_i_n_i_m_a_l number of these coins that amount  to 111
units in total.   We introduce  variables c(1), c(5) and c(20)  denoting
how many coins to take of the respective type:

________________________________________________________________________|                                                                        |

|:- use_module(library(simplex)).                                        |
|                                                                        |
|coins(S) :-                                                             |
|        gen_state(S0),                                                  |
|        coins(S0, S).                                                   |

|                                                                        |
|coins -->                                                               |
|        constraint([c(1), 5*c(5), 20*c(20)] = 111),                     |
|        constraint([c(1)] =< 3),                                        |
|        constraint([c(5)] =< 20),                                       |
|        constraint([c(20)] =< 10),                                      |
|        constraint([c(1)] >= 0),                                        |
|        constraint([c(5)] >= 0),                                        |

|        constraint([c(20)] >= 0),                                       |
|        constraint(integral(c(1))),                                     |
|        constraint(integral(c(5))),                                     |
|        constraint(integral(c(20))),                                    |
||_______minimize([c(1),_c(5),_c(20)])._________________________________ ||

An example query:

________________________________________________________________________|                                                                        |

|?- coins(S), variable_value(S, c(1), C1),                               |
|             variable_value(S, c(5), C5),                               |
|             variable_value(S, c(20), C20).                             |
|                                                                        |
|C1 = 1,                                                                 |
|C5 = 2,                                                                 |
|C20|=_5._______________________________________________________________ |   |


1133..3344 lliibbrraarryy((ssoolluuttiioonn__sseeqquueenncceess))::  MMooddiiffyy ssoolluuttiioonn sseeqquueenncceess

    SSeeee aallssoo
         - all solution predicates findall/3, bagof/3 and setof/3.
         - library(aggregate)

The meta  predicates of this  library modify  the sequence of  solutions
of a  goal.   The  modifications and the  predicate names  are based  on
the classical database operations DISTINCT, LIMIT, OFFSET,  ORDER BY and
GROUP BY.

These   predicates   were    introduced   in   the   context   of    the
http://swish.swi-prolog.orgSWISH  Prolog   browser-based  shell,   which
can  represent the  solutions  to  a predicate  as  a  table.    Notably
wrapping a goal in distinct/1 avoids duplicates in the  result table and
using order_by/2 produces a nicely ordered table.

However,  the predicates  from this  library can  also be  used to  stay
longer  within the  clean  paradigm where  non-deterministic  predicates
are  composed from  simpler  non-deterministic  predicates by  means  of
conjunction and disjunction.   While evaluating a conjunction,  we might
want  to eliminate  duplicates of  the first  part  of the  conjunction.
Below we  give both  the classical  solution for  solving variations  of
(a(X), b(X)) and the ones using this library side-by-side.

    ____________________________________________________________________|                                                                    |
AAvvooiidd||dduupplliiccaatteesssooffeeeaarrlliieerrtsstteeppssof(X, a(X), Xs),               distinct(a(X)),                |

    |   member(X, Xs),                    b(X)                           |
    ||__b(X).___________________________________________________________ ||

    Note that the  distinct/1 based solution returns the first result of
    distinct(a(X))  immediately after a/1  produces a result, while  the
    setof/3 based solution will first compute all results of a/1.

    ____________________________________________________________________|                                                                    |
OOnnllyy|ttrryysb(X)eoonnllyytffoorrotthheefttoopp--1100(a(X)X, a(X), Xs),               limit(10, order_by([desc(X)], a(X))),|
    |   reverse(Xs, Desc),                b(X)                           |
    |   first_max_n(10, Desc, Limit),                                    |
    |   member(X, Limit),                                                |

    ||__b(X)____________________________________________________________ ||

    Here  we see  power of  composing primitives from  this library  and
    staying  within the  paradigm of  pure non-deterministic  relational
    predicates.


ddiissttiinncctt((_:_G_o_a_l))


ddiissttiinncctt((_?_W_i_t_n_e_s_s_, _:_G_o_a_l))
    True  if  _G_o_a_l  is true  and  no  previous solution  of  _G_o_a_l  bound
    _W_i_t_n_e_s_s  to the same value.  As previous answers need to  be copied,
    equivalence testing is  based on _t_e_r_m _v_a_r_i_a_n_c_e (=@=/2).  The variant
    distinct/1 is equivalent to distinct(Goal,Goal).

    If  the answers are ground terms, the predicate behaves as  the code
    below,  but answers are  returned as soon  as they become  available
    rather than first computing the complete answer set.

    ____________________________________________________________________|                                                                    |
    | distinct(Goal) :-                                                  |

    |     findall(Goal, Goal, List),                                     |
    |     list_to_set(List, Set),                                        |
    ||____member(Goal,_Set).____________________________________________ ||


rreedduucceedd((_:_G_o_a_l))


rreedduucceedd((_?_W_i_t_n_e_s_s_, _:_G_o_a_l_, _+_O_p_t_i_o_n_s))
    Similar  to distinct/1,  but does  not guarantee  unique results  in
    return  for  using a  limited amount  of memory.    Both  distinct/1
    and  reduced/1 create  a table that  block duplicate  results.   For
    distinct/1,  this  table may  get  arbitrary large.    In  contrast,
    reduced/1 discards the table  and starts a new one of the table size
    exceeds  a specified  limit.   This  filter is  useful for  reducing
    the  number of answers when  processing large or infinite long  tail
    distributions.  _O_p_t_i_o_n_s:

    ssiizzee__lliimmiitt((_+_I_n_t_e_g_e_r))
         Max number of elements kept in the table.  Default is 10,000.


lliimmiitt((_+_C_o_u_n_t_, _:_G_o_a_l))
    Limit  the number of  solutions.   True if  _G_o_a_l is true,  returning
    at  most _C_o_u_n_t solutions.   Solutions are  returned as soon as  they
    become available.


ooffffsseett((_+_C_o_u_n_t_, _:_G_o_a_l))
    Ignore  the  first _C_o_u_n_t  solutions.    True  if  _G_o_a_l is  true  and
    produces  more than _C_o_u_n_t  solutions.   This predicate computes  and
    ignores the first _C_o_u_n_t solutions.


oorrddeerr__bbyy((_S_p_e_c_, _G_o_a_l))
    Order  solutions according to _S_p_e_c.  _S_p_e_c is a list of  terms, where
    each  element is one  of.   The ordering of  solutions of _G_o_a_l  that
    only  differ  in variables  that are  _n_o_t shared  with  _S_p_e_c is  not
    changed.

    aasscc((_T_e_r_m))
         Order solution according to ascending _T_e_r_m

    ddeesscc((_T_e_r_m))
         Order solution according to descending _T_e_r_m


ggrroouupp__bbyy((_+_B_y_, _+_T_e_m_p_l_a_t_e_, _:_G_o_a_l_, _-_B_a_g))                           _[_n_o_n_d_e_t_]
    Group  bindings of _T_e_m_p_l_a_t_e that have the  same value for _B_y.   This
    predicate  is almost the same as bagof/3, but instead  of specifying
    the  existential  variables  we specify  the  free  variables.    It
    is  provided for  consistency and  complete coverage  of the  common
    database vocabulary.


1133..3355 lliibbrraarryy((ttaabblliinngg))::  TTaabblleedd eexxeeccuuttiioonn ((SSLLGG))

The  library  tabling  provides support  for  _T_a_b_l_e_d  _e_x_e_c_u_t_i_o_n  of  one
or  more Prolog  predicates,  also called  _S_L_G _r_e_s_o_l_u_t_i_o_n.    Tabling  a
predicate provides two properties:

 1. Re-evaluation  of a  tabled predicate  is avoided  by _m_e_m_o_i_z_i_n_g  the
    answers.     This  can  realise  huge  performance  enhancements  as
    illustrated  in section ????.  It also comes with two downsides:   the
    memoized  answers are  not automatically updated  or invalidated  if
    the  world (set of predicates  on which the answers depend)  changes
    and the answer tables must be stored (in memory).

 2. _L_e_f_t  _r_e_c_u_r_s_i_o_n, a goal calling a _v_a_r_i_a_n_t of itself  recursively and
    thus  _l_o_o_p_i_n_g under the normal  Prolog SLD resolution is avoided  by
    suspending  the variant call and  resuming it with answers from  the
    table.  This is illustrated in section ????.

Tabling  is particularly  suited  to simplify  inference over  a  highly
entangled set of  predicates that express axioms  and rules in a  static
(not changing)  world.   When  using SLD resolution  for such  problems,
it is  hard to ensure  termination and  avoid frequent recomputation  of
intermediate results.    A solution  is to use  Datalog style  bottom-up
evaluation, i.e., applying  rules on the axioms and derived  facts until
a  fixed point  is reached.    However,  bottom-up evaluation  typically
derives  many facts  that  are never  used.    Tabling provides  a  _g_o_a_l
_o_r_i_e_n_t_e_d resolution strategy for such problems and is  enabled simply by
adding a table/1 directive to the program.


1133..3355..00..11 EExxaammppllee 11::  uussiinngg ttaabblliinngg ffoorr mmeemmooiizziinngg

As a first  classical example we use tabling for  _m_e_m_o_i_z_i_n_g intermediate
results.   We use  Fibonacci numbers  to illustrate the  approach.   The
Fibonacci number I  is defined as  the sum of the Fibonacci  numbers for
I- 1 and I- 2, while the Fibonacci number of 0 and 1 are both defined to
be 1.  This can be translated naturally into Prolog:

________________________________________________________________________|                                                                        |
|fib(0, 1) :- !.                                                         |

|fib(1, 1) :- !.                                                         |
|fib(N, F) :-                                                            |
|        N > 1,                                                          |
|        N1 is N-1,                                                      |
|        N2 is N-2,                                                      |
|        fib(N1, F1),                                                    |
|        fib(N2, F2),                                                    |
||_______F_is_F1+F2.____________________________________________________ ||

The complexity  of executing  this using  SLD resolution  however is 2N
and thus becomes prohibitively slow rather quickly,  e.g., the execution
time  for N = 30  is already  0.4  seconds.    Using tabling,  fib(_N_,_F)
for each  value of N  is computed  only once and  the algorithm becomes
linear.  Tabling effectively inverts the execution order  for this case:
it suspends  the final addition  (F is F1+F2)  until the two  preceeding
Fibonacci numbers have  been added to the answer  tables.  Thus, we  can
reduce the complexity  from the show-stopping 2N  to linear by  adding a
tabling directive and  otherwise not changing the  algorithm.  The  code
becomes:

________________________________________________________________________|                                                                        |

|:- use_module(library(tabling)).                                        |
|:- table fib/2.                                                         |
|                                                                        |
|fib(0, 1) :- !.                                                         |
|fib(1, 1) :- !.                                                         |
|fib(N, F) :-                                                            |
|        N > 1,                                                          |

|        N1 is N-1,                                                      |
|        N2 is N-2,                                                      |
|        fib(N1, F1),                                                    |
|        fib(N2, F2),                                                    |
||_______F_is_F1+F2.____________________________________________________ ||

The price  that we  pay is  that a table  fib(_I_,_F) is  created for  each
I  in 0::N.   The  execution time  for N = 30 is now  1 millisecond  and
computing the Fibonacci number for N =1000 is doable (output edited for
readability).

________________________________________________________________________|                                                                        |
|1 ?- time(fib(1000, X)).                                                |

|% 52,991 inferences, 0.013 CPU in 0.013 seconds                         |
|X = 70330367711422815821835254877183549770181269836358                  |
|    73274260490508715453711819693357974224949456261173                  |
|    34877504492417659910881863632654502236471060120533                  |
|    74121273867339111198139373125598767690091902245245                  |
||___323403501._________________________________________________________ ||

In the  case of  Fibonacci numbers  we can still  rather easily  achieve
linear complexity using  program transformation, where we use  bottom-up
instead of  top-down evaluation, i.e.,  we compute fib(_N_,_F) for  growing
N, where we pass the last  two Fibonacci numbers to the next iteration.
Not having  to create the  tables and not having  to suspend and  resume
goals makes  this implementation about 25  times faster than the  tabled
one.    However, even  in this  simple  case the  transformation is  not
obvious and it  is far more difficult  to recognise the algorithm as  an
implementation of Fibonacci numbers.

________________________________________________________________________|                                                                        |

|fib(0, 1) :- !.                                                         |
|fib(1, 1) :- !.                                                         |
|fib(N, F) :-                                                            |
|        fib(1,1,1,N,F).                                                 |
|                                                                        |
|fib(_F, F1, N, N, F1) :- !.                                             |
|fib(F0, F1, I, N, F) :-                                                 |

|        F2 is F0+F1,                                                    |
|        I2 is I + 1,                                                    |
||_______fib(F1,_F2,_I2,_N,_F)._________________________________________ ||


1133..3355..00..22 EExxaammppllee 22::  aavvooiiddiinngg nnoonn--tteerrmmiinnaattiioonn

SLD  resolution  easily  results  in  an  infinite  loop   due  to  _l_e_f_t
_r_e_c_u_r_s_i_o_n,  a  goal that  (indirectly)  calls  a variant  of  itself  or
cycles in  the input data.   Thus, if we  have a series of  connection/2
statements  that  define railway  connections  between  two  cities,  we
cannot use the  most natural logical definition  to express that we  can
travel between two cities:

________________________________________________________________________|                                                                        |
|% :- use_module(library(tabling)).                                      |
|% :- table connection/2.                                                |
|                                                                        |

|connection(X, Y) :-                                                     |
|        connection(X, Z),                                               |
|        connection(Z, Y).                                               |
|connection(X, Y) :-                                                     |
|        connection(Y, X).                                               |
|                                                                        |
|connection('Amsterdam', 'Schiphol').                                    |
|connection('Amsterdam', 'Haarlem').                                     |

|connection('Schiphol', 'Leiden').                                       |
|connection('Haarlem',|'Leiden')._______________________________________ |                     |

After  enabling   tabling  however,  the   above  works  just  fine   as
illustrated  in the  session below.    Where is  the magic  and what  is
the price  we paid?   The magic is,  again, the fact  that new goals  to
the tabled predicate  suspend.  So,  all recursive goals are  suspended.
Eventually, a table  for connection(_'_A_m_s_t_e_r_d_a_m_'_, _X) is created  with the
two  direct connections  from Amsterdam.    Now,  it resumes  the  first
clause  using the  tabled solutions,  continuing  the last  connection/2
subgoal  with connection(_'_S_c_h_i_p_h_o_l_'_,  _X) and  connection(_'_H_a_a_r_l_e_m_'_,  _X).
These two go through the same process, creating  new suspended recursive
calls  and  creating  tables  for  the  connections  from  Schiphol  and
Haarlem.   Eventually,  we end up  with a  set of tables  for each  call
variant that  is involved  in computing  the transitive  closure of  the
network starting in  Amsterdam.  However,  if the Japanese rail  network
would have been in  our data as well, we would not have  produced tables
for that.

________________________________________________________________________|                                                                        |
|1 ?- connection('Amsterdam', X).                                        |
|X = 'Haarlem' ;                                                         |
|X = 'Schiphol' ;                                                        |
|X = 'Amsterdam' ;                                                       |
|X|=_'Leiden'.__________________________________________________________ | |

Again, the fact that  a simple table/1 directive turns the  pure logical
specification into  a fairly efficient algorithm  is a clear  advantage.
Without tabling the program  needs to be _s_t_r_a_t_i_f_i_e_d, introducing  a base
layer  with the  raw connections,  a second  layer  that introduces  the
_c_o_m_m_u_t_a_t_i_v_e  property of  a railway  (if you  can  travel from  A to  B
you  can also  travel from  B  to A  and  a final  layer that  realises
_t_r_a_n_s_i_t_i_v_i_t_y (if you  can travel from A to  B and from B  to C you can
also travel from  A to C).   The third and final layer  must keep track
which cities  you have already  visited to  avoid traveling in  circles.
The transformed program however uses little memory (the  list of already
visited cities  and the still  open choices) and does  not need to  deal
with maintaining consistency between the tables and ground facts.


1133..3355..00..33 MMooddee ddiirreecctteedd ttaabblliinngg

Tabling  as defined  above  has a  serious  limitation.    Although  the
definition  of connection/2  from  section section  ???? can  compute  the
transitive closure  of connected cities,  it cannot  provide you with  a
route to travel.   The reason is  that there are infinitely many  routes
if there  are cycles in  the network  and each new  route found will  be
added to  the answer table and  cause the tabled execution's  completion
algorithm to search for more routes, eventually running out of memory.

The solution to this  problem is called _m_o_d_e _d_i_r_e_c_t_e_d _t_a_b_l_i_n_g  or _a_n_s_w_e_r
_s_u_b_s_u_m_p_t_i_o_n.   In  this execution model  one or  more arguments are  _n_o_t
added to the table.  Instead, we remember a  single _a_g_g_r_e_g_a_t_e_d value for
these arguments.    The example  below is  derived from  section ????  and
returns the connection  as a list of cities.   This argument is  defined
as  a _m_o_d_e_d  argument  using the  lattice(_P_I) mode.    This  causes  the
tabling engine each  time that it finds  an new path to call  shortest/3
and keep the shortest route.

________________________________________________________________________|                                                                        |
|:- use_module(library(tabling)).                                        |

|:- table                                                                |
|    connection(_,_,lattice(shortest/3)).                                |
|                                                                        |
|shortest(P1, P2, P):-                                                   |
|    length(P1, L1),                                                     |
|    length(P2, L2),                                                     |
|    (   L1 < L2                                                         |
|    ->  P = P1                                                          |

|    ;   P = P2                                                          |
|    ).                                                                  |
|                                                                        |
|connection(X, Y, [X,Y]) :-                                              |
|    connection(X, Y).                                                   |
|connection(X, Y, P) :-                                                  |
|    connection(X, Z, P0),                                               |

|    connection(Z, Y),                                                   |
||___append(P0,_[Y],_P).________________________________________________ ||

The  mode   declation  scheme   is  equivalent  to   XSB  with   partial
compatibility support  for YAP and  B-Prolog.   The lattice(_P_I) mode  is
the  most general  mode.   The  YAP all  (B-Prolog @)  mode  is not  yet
supported.  The  list below describes the supported modes  and indicates
the portability.

VVaarr
+

iinnddeexx
    A  variable (XSB), the  atom index (YAP)  or a + (B-Prolog)  declare
    that the argument is tabled normally.

llaattttiiccee((_P_I))
    _P_I  must be  the predicate indicator  of a  predicate with arity  3.
    On  each answer,  _P_I is called  with three  arguments:  the  current
    aggregated answer and the  new answer are inputs.  The last argument
    must  be unified  with  a term  that represents  the new  aggregated
    answer.    In SWI-Prolog  the arity  (3) may be  omitted.   See  the
    example above.

ppoo((_P_I))
    _P_a_r_t_i_a_l  _O_r_d_e_n_i_n_g.    The new  answer is  added  iff call(_P_I_,  _+_O_l_d_,
    _+_A_n_s_w_e_r)  succeeds.  For example, po('<'/2) accumulates  the largest
    result.   In SWI-Prolog the  arity (2) may be omitted,  resulting in
    po(<).

-
ffiirrsstt((_T))
    he  atom -  (B-Prolog) and  first (YAP)  declare to  keep the  first
    answer for this argument.

llaasstt
    The atom last (YAP) declares to keep the last answer.

mmiinn
    The  atom min (YAP) declares  to keep the smallest answer  according
    to the standard order of terms  (see @</2).  Note that in SWI-Prolog
    the standard order of terms orders numbers by value.

mmaaxx
    The atom max  (YAP) declares to keep the largest answer according to
    the  standard order of terms  (see @>/2).   Note that in  SWI-Prolog
    the standard order of terms orders numbers by value.

ssuumm
    The atom sum (YAP) declares to sum numeric answers.


1133..3355..11 TTaabblliinngg pprreeddiiccaattee rreeffeerreennccee


ttaabbllee _+_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_s
    Prepare  the given  _P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_s for  tabling.   Can only  be
    used  as a  directive.   The  example below  prepares the  predicate
    edge/2 and the non-terminal statement//1 for tabled execution.

    ____________________________________________________________________|                                                                    |
    ||:-_table_edge/2,_statement//1.____________________________________ ||

    In  addition  to using  _p_r_e_d_i_c_a_t_e  _i_n_d_i_c_a_t_o_r_s,  a predicate  can  be
    declared for _m_o_d_e  _d_i_r_e_c_t_e_d _t_a_b_l_i_n_g using a term where each argument
    declares the intended mode.  For example:

    ____________________________________________________________________|                                                                    |

    ||:-_table_connection(_,_,min)._____________________________________ ||

    _M_o_d_e  _d_i_r_e_c_t_e_d  _t_a_b_l_i_n_g is  discussed  in the  general  introduction
    section about tabling.


aabboolliisshh__aallll__ttaabblleess
    Remove  all tables.  This is  normally used to free up the  space or
    recompute  the result after predicates on which the result  for some
    tabled predicates depend.

         EErrrroorrss permission_error(abolish, table, all)   if  tabling
             is in progress.


aabboolliisshh__ttaabbllee__ssuubbggooaallss((_:_S_u_b_g_o_a_l))                                   _[_d_e_t_]
    Abolish all tables that unify with SubGoal.


1133..3355..11..11 AAbboouutt tthhee ttaabblliinngg iimmpplleemmeennttaattiioonn

The  SWI-Prolog   implementation  uses   _D_e_l_i_m_i_t_e_d  _c_o_n_t_i_n_u_a_t_i_o_n_s   (see
section ???? to realise suspension of variant calls.   The initial version
was written  by Benoit  Desouter and  described in [??].    We moved  the
main  data structures  required  for  tabling,  the _a_n_s_w_e_r  _t_a_b_l_e_s  (see
section ????)  and the  _w_o_r_k_l_i_s_t to SWI-Prolog's  C core.   _M_o_d_e  _d_i_r_e_c_t_e_d
_t_a_b_l_i_n_g (section ????) is based on a prototype  implementation by Fabrizio
Riguzzi.

The  table/1 directive  causes the  creation of  a  wrapper calling  the
renamed original  predicate.   For example,  the program  in section  ????
is translated  into the  following program.   We  give this  information
to improve  your understanding  of the  current tabling  implementation.
Future versions are likely  to use a more low-level translation  that is
not based on wrappers.

________________________________________________________________________|                                                                        |
|connection(A, B) :-                                                     |

|        start_tabling(user:connection(A, B),                            |
|                      'connection tabled'(A, B)).                       |
|                                                                        |
|'connection tabled'(X, Y) :-                                            |
|        connection(X, Z),                                               |
|        connection(Z, Y).                                               |
|'connection tabled'(X, Y) :-                                            |
|        connection(Y, X).                                               |

|                                                                        |
|'connection tabled'('Amsterdam', 'Schiphol').                           |
|'connection tabled'('Amsterdam', 'Haarlem').                            |
|'connection tabled'('Schiphol', 'Leiden').                              |
|'connection|tabled'('Haarlem',_'Leiden').______________________________ |           |


1133..3355..11..22 SSttaattuuss ooff ttaabblliinngg

The  current implementation  is merely  a  first prototype.    It  needs
several enhancements before  we can consider it a serious  competitor to
Prolog systems with  mature tabling such as XSB,  YAP and B-Prolog.   In
particular,

  o The performance needs to be improved.

  o Memory usage needs to be reduced.

  o Tables  must be  shared between  threads, both to  reduce space  and
    avoid recomputation.

  o Tables must be invalidated and reclaimed automatically.

  o Notably   XSB   supports  incremental   tabeling  and   well-founded
    semantics under negation.


1133..3366 lliibbrraarryy((tthhrreeaadd__ppooooll))::  RReessoouurrccee bboouunnddeedd tthhrreeaadd mmaannaaggeemmeenntt

    SSeeee aallssoo  http_handler/3 and http_spawn/2.

The  module library(thread_pool)  manages  threads in  pools.    A  pool
defines  properties of  its member  threads and  the  maximum number  of
threads that can coexist  in the pool.  The call  thread_create_in_pool/4
allocates a thread in the pool, just  like thread_create/3.   If the pool
is fully allocated it can be asked to wait or raise an error.

The library  has been  designed to  deal with  server applications  that
receive a variety of requests, such as HTTP servers.   Simply starting a
thread for each request is a bit too simple minded for such servers:

  o Creating  many  CPU intensive  threads often  leads  to a  slow-down
    rather than a speedup.

  o Creating many memory intensive threads may exhaust resources

  o Tasks  that require little CPU and memory but take long  waiting for
    external resources can run many threads.

Using this  library, one can define  a pool for  each set of tasks  with
comparable characteristics and create threads in this pool.   Unlike the
worker-pool model,  threads are not started  immediately.  Depending  on
the design, both approaches can be attractive.

The  library is  implemented  by means  of  a  manager thread  with  the
fixed  thread id  __thread_pool_manager.   All  state  is maintained  in
this manager  thread, which  receives and processes  requests to  create
and destroy  pools, create threads  in a pool  and handle messages  from
terminated threads.   Thread pools  are _n_o_t saved  in a saved state  and
must  therefore be  recreated using  the  initialization/1 directive  or
otherwise during startup of the application.


tthhrreeaadd__ppooooll__ccrreeaattee((_+_P_o_o_l_, _+_S_i_z_e_, _+_O_p_t_i_o_n_s))                         _[_d_e_t_]
    Create  a pool  of threads.    A pool  of threads  is a  declaration
    for  creating  threads  with  shared properties  (stack  sizes)  and
    a   limited  number  of  threads.      Threads  are  created   using
    thread_create_in_pool/4.   If all threads  in the  pool are in  use,
    the  behaviour depends on the wait option of  thread_create_in_pool/4
    and  the backlog  option described  below.   _O_p_t_i_o_n_s  are passed  to
    thread_create/3, except for

    bbaacckklloogg((_+_M_a_x_B_a_c_k_L_o_g))
         Maximum number of requests  that can be suspended.   Default is
         infinite.  Otherwise it must be a non-negative integer.   Using
         backlog(0) will never delay thread creation for this pool.

    The  pooling mechanism does _n_o_t interact with the detached  state of
    a thread.   Threads can be created both detached and normal and must
    be joined using thread_join/2 if they are not detached.


tthhrreeaadd__ppooooll__ddeessttrrooyy((_+_N_a_m_e))                                         _[_d_e_t_]
    Destroy the thread pool named _N_a_m_e.

         EErrrroorrss existence_error(thread_pool, Name).


ccuurrrreenntt__tthhrreeaadd__ppooooll((_?_N_a_m_e))                                      _[_n_o_n_d_e_t_]
    True if _N_a_m_e refers to a defined thread pool.


tthhrreeaadd__ppooooll__pprrooppeerrttyy((_?_N_a_m_e_, _?_P_r_o_p_e_r_t_y))                          _[_n_o_n_d_e_t_]
    True  if  _P_r_o_p_e_r_t_y is  a property  of  thread pool  _N_a_m_e.    Defined
    properties are:

    ooppttiioonnss((_O_p_t_i_o_n_s))
         Thread creation options for this pool

    ffrreeee((_S_i_z_e))
         Number of free slots on this pool

    ssiizzee((_S_i_z_e))
         Total number of slots on this pool

    mmeemmbbeerrss((_L_i_s_t_O_f_I_D_s))
         _L_i_s_t_O_f_I_D_s is the list or threads running in this pool

    rruunnnniinngg((_R_u_n_n_i_n_g))
         Number of running threads in this pool

    bbaacckklloogg((_S_i_z_e))
         Number of delayed thread creations on this pool


tthhrreeaadd__ccrreeaattee__iinn__ppooooll((_+_P_o_o_l_, _:_G_o_a_l_, _-_I_d_, _+_O_p_t_i_o_n_s))                  _[_d_e_t_]
    Create  a thread in _P_o_o_l.  _O_p_t_i_o_n_s overrule default  thread creation
    options  associated to the pool.  In addition, the  following option
    is defined:

    wwaaiitt((_+_B_o_o_l_e_a_n))
         If true (default) and the pool is full, wait until  a member of
         the pool completes.  If false, throw a resource_error.

         EErrrroorrss
             -  resource_error(threads_in_pool(Pool)) is  raised if
             wait is false or the backlog limit has been reached.
             - existence_error(thread_pool, Pool)  if _P_o_o_l does not
             exist.


ccrreeaattee__ppooooll((_+_P_o_o_l_N_a_m_e))                               _[_s_e_m_i_d_e_t_,_m_u_l_t_i_f_i_l_e_]
    Hook  to  create a  thread  pool lazily.    The  hook is  called  if
    thread_create_in_pool/4 discovers  that  the  thread pool  does  not
    exist.     If  the  hook  succeeds,  thread_create_in_pool/4 retries
    creating  the  thread.    For  example,  we can  use  the  following
    declaration  to create  threads in  the  pool media,  which holds  a
    maximum of 20 threads.

    ____________________________________________________________________|                                                                    |
    | :- multifile thread_pool:create_pool/1.                            |
    |                                                                    |
    | thread_pool:create_pool(media) :-                                  |

    ||____thread_pool_create(media,_20,_[]).____________________________ ||


1133..3377 lliibbrraarryy((uuggrraapphhss))::  UUnnwweeiigghhtteedd GGrraapphhss

                          Authors:  _R_i_c_h_a_r_d _O_'_K_e_e_f_e _& _V_i_t_o_r _S_a_n_t_o_s _C_o_s_t_a

    _I_m_p_l_e_m_e_n_t_a_t_i_o_n  _a_n_d  _d_o_c_u_m_e_n_t_a_t_i_o_n _a_r_e  _c_o_p_i_e_d _f_r_o_m  _Y_A_P _5_._0_._1_.
    _T_h_e   ugraph  _l_i_b_r_a_r_y  _i_s  _b_a_s_e_d  _o_n  _c_o_d_e  _o_r_i_g_i_n_a_l_l_y  _w_r_i_t_t_e_n
    _b_y  _R_i_c_h_a_r_d  _O_'_K_e_e_f_e_.     _T_h_e  _c_o_d_e  _w_a_s  _t_h_e_n _e_x_t_e_n_d_e_d  _t_o  _b_e
    _c_o_m_p_a_t_i_b_l_e  _w_i_t_h _t_h_e _S_I_C_S_t_u_s _P_r_o_l_o_g _u_g_r_a_p_h_s  _l_i_b_r_a_r_y_.  _C_o_d_e _a_n_d
    _d_o_c_u_m_e_n_t_a_t_i_o_n  _h_a_v_e _b_e_e_n _c_l_e_a_n_e_d _a_n_d _s_t_y_l_e  _h_a_s _b_e_e_n _c_h_a_n_g_e_d _t_o
    _b_e _m_o_r_e _i_n _l_i_n_e _w_i_t_h _t_h_e _r_e_s_t _o_f _S_W_I_-_P_r_o_l_o_g_.

    _T_h_e  _u_g_r_a_p_h_s  _l_i_b_r_a_r_y  _w_a_s _o_r_i_g_i_n_a_l_l_y  _r_e_l_e_a_s_e_d  _i_n  _t_h_e _p_u_b_l_i_c
    _d_o_m_a_i_n_.    _T_h_e  _Y_A_P  _v_e_r_s_i_o_n _i_s  _c_o_v_e_r_e_d _b_y  _t_h_e  _P_e_r_l _A_r_t_i_s_t_i_c
    _l_i_c_e_n_s_e_,  _v_e_r_s_i_o_n _2_._0_.   _T_h_i_s  _c_o_d_e _i_s  _d_u_a_l_-_l_i_c_e_n_s_e_d _u_n_d_e_r _t_h_e
    _m_o_d_i_f_i_e_d  _G_P_L _a_s _u_s_e_d _f_o_r _a_l_l  _S_W_I_-_P_r_o_l_o_g _l_i_b_r_a_r_i_e_s _o_r _t_h_e _P_e_r_l
    _A_r_t_i_s_t_i_c _l_i_c_e_n_s_e_, _v_e_r_s_i_o_n _2_._0_.

The  routines   assume  directed  graphs;   undirected  graphs  may   be
implemented by using two edges.

Originally graphs were represented in two formats.   The SICStus library
and  this version  of ugraphs.pl  only use  the _S_-_r_e_p_r_e_s_e_n_t_a_t_i_o_n.    The
S-representation  of a  graph  is a  list of  (vertex-neighbors)  pairs,
where the pairs are  in standard order (as produced by keysort)  and the
neighbors of  each vertex  are also  in standard order  (as produced  by
sort).   This form  is convenient  for many calculations.   Each  vertex
appears in the S-representation, even if it has no neighbors.


vveerrttiicceess__eeddggeess__ttoo__uuggrraapphh((_+_V_e_r_t_i_c_e_s_, _+_E_d_g_e_s_, _-_G_r_a_p_h))
    Given a graph with  a set of _V_e_r_t_i_c_e_s and a set of _E_d_g_e_s, _G_r_a_p_h must
    unify  with the corresponding S-representation.  Note  that vertices
    without  edges will appear in _V_e_r_t_i_c_e_s but not in _E_d_g_e_s.   Moreover,
    it is sufficient for a vertex to appear in _E_d_g_e_s.

    ____________________________________________________________________|                                                                    |
    | ?- vertices_edges_to_ugraph([],[1-3,2-4,4-5,1-5], L).              |

    ||L_=_[1-[3,5],_2-[4],_3-[],_4-[5],_5-[]]___________________________ ||

    In this case all  vertices are defined implicitly.  The next example
    shows three unconnected vertices:

    ____________________________________________________________________|                                                                    |

    | ?- vertices_edges_to_ugraph([6,7,8],[1-3,2-4,4-5,1-5], L).         |
    ||L_=_[1-[3,5],_2-[4],_3-[],_4-[5],_5-[],_6-[],_7-[],_8-[]]_?_______ ||


vveerrttiicceess((_+_G_r_a_p_h_, _-_V_e_r_t_i_c_e_s))
    Unify _V_e_r_t_i_c_e_s with all vertices appearing in _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- vertices([1-[3,5],2-[4],3-[],4-[5],5-[]], L).                   |
    ||L_=_[1,_2,_3,_4,_5]_______________________________________________ ||


eeddggeess((_+_G_r_a_p_h_, _-_E_d_g_e_s))
    Unify _E_d_g_e_s with all edges appearing in _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- edges([1-[3,5],2-[4],3-[],4-[5],5-[]], L).                      |

    ||L_=_[1-3,_1-5,_2-4,_4-5]__________________________________________ ||


aadddd__vveerrttiicceess((_+_G_r_a_p_h_, _+_V_e_r_t_i_c_e_s_, _-_N_e_w_G_r_a_p_h))
    Unify  _N_e_w_G_r_a_p_h with  a new  graph obtained  by adding  the list  of
    _V_e_r_t_i_c_e_s to _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- add_vertices([1-[3,5],2-[]], [0,1,2,9], NG).                    |

    ||NG_=_[0-[],_1-[3,5],_2-[],_9-[]]__________________________________ ||


ddeell__vveerrttiicceess((_+_G_r_a_p_h_, _+_V_e_r_t_i_c_e_s_, _-_N_e_w_G_r_a_p_h))
    Unify  _N_e_w_G_r_a_p_h  with a  new  graph obtained  by deleting  the  list
    of  _V_e_r_t_i_c_e_s and  all edges that  start from  or go to  a vertex  in
    _V_e_r_t_i_c_e_s from _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- del_vertices([2,1],                                             |

    |                 [1-[3,5],2-[4],3-[],4-[5],                         |
    |                  5-[],6-[],7-[2,6],8-[]],                          |
    |                 NL).                                               |
    ||NL_=_[3-[],4-[5],5-[],6-[],7-[6],8-[]]____________________________ ||


aadddd__eeddggeess((_+_G_r_a_p_h_, _+_E_d_g_e_s_, _-_N_e_w_G_r_a_p_h))
    Unify  _N_e_w_G_r_a_p_h with  a new  graph obtained  by adding  the list  of
    _E_d_g_e_s to _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- add_edges([1-[3,5],2-[4],3-[],4-[5],                            |

    |               5-[],6-[],7-[],8-[]],                                |
    |              [1-6,2-3,3-2,5-7,3-2,4-5],                            |
    |              NL).                                                  |
    | NL = [1-[3,5,6], 2-[3,4], 3-[2], 4-[5],                            |
    ||______5-[7],_6-[],_7-[],_8-[]]____________________________________ ||


ddeell__eeddggeess((_+_G_r_a_p_h_, _+_E_d_g_e_s_, _-_N_e_w_G_r_a_p_h))
    Unify  _N_e_w_G_r_a_p_h with a  new graph obtained  by removing the list  of
    _E_d_g_e_s from _G_r_a_p_h.  Notice that no vertices are deleted.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- del_edges([1-[3,5],2-[4],3-[],4-[5],5-[],6-[],7-[],8-[]],       |

    |              [1-6,2-3,3-2,5-7,3-2,4-5,1-3],                        |
    |              NL).                                                  |
    ||NL_=_[1-[5],2-[4],3-[],4-[],5-[],6-[],7-[],8-[]]__________________ ||


ttrraannssppoossee__uuggrraapphh((_+_G_r_a_p_h_, _-_N_e_w_G_r_a_p_h))
    Unify  _N_e_w_G_r_a_p_h with a  new graph obtained  from _G_r_a_p_h by  replacing
    all  edges of the form V1-V2 by edges  of the form V2-V1.   The cost
    is  O(|V|2).  Notice  that an undirected graph is  its own transpose.
    Example:

    ____________________________________________________________________|                                                                    |
    | ?- transpose_ugraph([1-[3,5],2-[4],3-[],4-[5],                     |

    |               5-[],6-[],7-[],8-[]], NL).                           |
    ||NL_=_[1-[],2-[],3-[1],4-[2],5-[1,4],6-[],7-[],8-[]]_______________ ||


nneeiigghhbboouurrss((_+_V_e_r_t_e_x_, _+_G_r_a_p_h_, _-_V_e_r_t_i_c_e_s))
    Unify  _V_e_r_t_i_c_e_s with  the  list of  neighbours of  vertex _V_e_r_t_e_x  in
    _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- neighbours(4,[1-[3,5],2-[4],3-[],                               |

    |                  4-[1,2,7,5],5-[],6-[],7-[],8-[]], NL).            |
    ||NL_=_[1,2,7,5]____________________________________________________ ||


nneeiigghhbboorrss((_+_V_e_r_t_e_x_, _+_G_r_a_p_h_, _-_V_e_r_t_i_c_e_s))
    American version of neighbours/3.


ccoommpplleemmeenntt((_+_G_r_a_p_h_, _-_N_e_w_G_r_a_p_h))
    Unify _N_e_w_G_r_a_p_h with the graph complementary to _G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- complement([1-[3,5],2-[4],3-[],                                 |

    |                4-[1,2,7,5],5-[],6-[],7-[],8-[]], NL).              |
    | NL = [1-[2,4,6,7,8],2-[1,3,5,6,7,8],3-[1,2,4,5,6,7,8],             |
    |       4-[3,5,6,8],5-[1,2,3,4,6,7,8],6-[1,2,3,4,5,7,8],             |
    ||______7-[1,2,3,4,5,6,8],8-[1,2,3,4,5,6,7]]________________________ ||


ccoommppoossee((_+_L_e_f_t_G_r_a_p_h_, _+_R_i_g_h_t_G_r_a_p_h_, _-_N_e_w_G_r_a_p_h))
    Compose  _N_e_w_G_r_a_p_h  by  connecting the  _d_r_a_i_n_s  of _L_e_f_t_G_r_a_p_h  to  the
    _s_o_u_r_c_e_s of _R_i_g_h_t_G_r_a_p_h.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- compose([1-[2],2-[3]],[2-[4],3-[1,2,4]],L).                     |

    ||L_=_[1-[4],_2-[1,2,4],_3-[]]______________________________________ ||


uuggrraapphh__uunniioonn((_+_G_r_a_p_h_1_, _+_G_r_a_p_h_2_, _-_N_e_w_G_r_a_p_h))
    _N_e_w_G_r_a_p_h is the union of _G_r_a_p_h_1 and _G_r_a_p_h_2.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- ugraph_union([1-[2],2-[3]],[2-[4],3-[1,2,4]],L).                |

    ||L_=_[1-[2],_2-[3,4],_3-[1,2,4]]___________________________________ ||


ttoopp__ssoorrtt((_+_G_r_a_p_h_, _-_S_o_r_t))
    Generate  the set of nodes _S_o_r_t  as a topological sorting of  _G_r_a_p_h,
    if  one is possible.   A  toplogical sort is  possible if the  graph
    is  connected and acyclic.   In the example we show how  topological
    sorting works for a linear graph:

    ____________________________________________________________________|                                                                    |
    | ?- top_sort([1-[2], 2-[3], 3-[]], L).                              |

    ||L_=_[1,_2,_3]_____________________________________________________ ||


ttoopp__ssoorrtt((_+_G_r_a_p_h_, _-_S_o_r_t_0_, _-_S_o_r_t))
    Generate the difference  list Sort-Sort0 as a topological sorting of
    _G_r_a_p_h, if one is possible.


ttrraannssiittiivvee__cclloossuurree((_+_G_r_a_p_h_, _-_C_l_o_s_u_r_e))
    Generate  the  graph Closure  as the  transitive  closure of  _G_r_a_p_h.
    Example:

    ____________________________________________________________________|                                                                    |
    |  ?- transitive_closure([1-[2,3],2-[4,5],4-[6]],L).                 |

    ||L_=_[1-[2,3,4,5,6],_2-[4,5,6],_4-[6]]_____________________________ ||


rreeaacchhaabbllee((_+_V_e_r_t_e_x_, _+_G_r_a_p_h_, _-_V_e_r_t_i_c_e_s))
    Unify  _V_e_r_t_i_c_e_s  with the  set of  all vertices  in  _G_r_a_p_h that  are
    reachable from _V_e_r_t_e_x.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- reachable(1,[1-[3,5],2-[4],3-[],4-[5],5-[]],V).                 |

    ||V_=_[1,_3,_5]_____________________________________________________ ||


1133..3388 lliibbrraarryy((uurrll))::  AAnnaallyyssiinngg aanndd ccoonnssttrruuccttiinngg UURRLL

    aauutthhoorr
         - Jan Wielemaker
         - Lukas Faulstich

    ddeepprreeccaatteedd  New code  should use library(uri),  provided by the
         clib package.

This  library  deals  with the  analysis  and  construction  of  a  URL,
Universal  Resource  Locator.    URL  is  the  basis  for  communicating
locations of resources (data) on the web.  A URL  consists of a protocol
identifier (e.g.    HTTP, FTP,  and a  protocol-specific syntax  further
defining the location.  URLs are standardized in RFC-1738.

The implementation in  this library covers only  a small portion of  the
defined protocols.  Though the initial  implementation followed RFC-1738
strictly, the current  is more relaxed to deal with  frequent violations
of the standard encountered in practical use.


gglloobbaall__uurrll((_+_U_R_L_, _+_B_a_s_e_, _-_G_l_o_b_a_l))                                   _[_d_e_t_]
    Translate a possibly relative _U_R_L into an absolute one.

         EErrrroorrss syntax_error(illegal_url) if _U_R_L is not legal.


iiss__aabbssoolluuttee__uurrll((_+_U_R_L))
    True  if _U_R_L is an absolute _U_R_L.  That is, a _U_R_L that starts  with a
    protocol identifier.


hhttttpp__llooccaattiioonn((_?_P_a_r_t_s_, _?_L_o_c_a_t_i_o_n))
    Construct  or  analyze  an  HTTP  location.    This  is  similar  to
    parse_url/2, but only  deals with the location part of an  HTTP URL.
    That  is, the  path, search and  fragment specifiers.   In the  HTTP
    protocol, the first line of a message is

    ____________________________________________________________________|                                                                    |
    ||<Action>_<Location>_HTTP/<version>________________________________ ||

    ___________________________________________________________Arguments_
     _L_o_c_a_t_i_o_n  Atom or list of character codes.


ppaarrssee__uurrll((_?_U_R_L_, _?_A_t_t_r_i_b_u_t_e_s))                                       _[_d_e_t_]
    Construct  or analyse  a _U_R_L.  _U_R_L is  an atom  holding a  _U_R_L or  a
    variable.   _A_t_t_r_i_b_u_t_e_s is a list  of components.  Each  component is
    of the format Name(Value).  Defined components are:

    pprroottooccooll((_P_r_o_t_o_c_o_l))
         The used  protocol.    This is,  after  the optional  url:,  an
         identifier  separated  from the  remainder  of  the  _U_R_L  using
         :.   parse_url/2 assumes the  http protocol  if no protocol  is
         specified and  the  _U_R_L can  be  parsed as  a valid  HTTP  url.
         In  addition to  the  RFC-1738 specified  protocols,  the  file
         protocol is supported as well.

    hhoosstt((_H_o_s_t))
         _H_o_s_t-name  or IP-address  on  which  the resource  is  located.
         Supported by all network-based protocols.

    ppoorrtt((_P_o_r_t))
         Integer port-number  to access on  the \arg{Host}.    This only
         appears  if  the port  is  explicitly  specified  in  the  _U_R_L.
         Implicit default  ports (e.g., 80  for HTTP)  do _n_o_t appear  in
         the part-list.

    ppaatthh((_P_a_t_h))
         (File-) path addressed  by the _U_R_L.  This is supported for  the
         ftp, http and file protocols.  If no path  appears, the library
         generates the path /.

    sseeaarrcchh((_L_i_s_t_O_f_N_a_m_e_V_a_l_u_e))
         Search-specification of HTTP  _U_R_L. This is  the part after  the
         ?, normally used to transfer data from HTML forms  that use the
         HTTP GET method.  In the _U_R_L it consists  of a www-form-encoded
         list of Name=Value pairs.   This is mapped to a list  of Prolog
         Name=Value terms with decoded names and values.

    ffrraaggmmeenntt((_F_r_a_g_m_e_n_t))
         _F_r_a_g_m_e_n_t specification of HTTP _U_R_L. This is the  part after the
         # character.

    The example below illustrates all of this for an HTTP _U_R_L.

    ____________________________________________________________________|                                                                    |

    | ?- parse_url('http://www.xyz.org/hello?msg=Hello+World%21#x',      |
    |        P).                                                         |
    |                                                                    |
    | P = [ protocol(http),                                              |
    |       host('www.xyz.org'),                                         |

    |       fragment(x),                                                 |
    |       search([ msg = 'Hello World!'                                |
    |              ]),                                                   |
    |       path('/hello')                                               |
    ||____]_____________________________________________________________ ||

    By  instantiating  the  parts-list this  predicate  can be  used  to
    create a _U_R_L.


ppaarrssee__uurrll((_+_U_R_L_, _+_B_a_s_e_U_R_L_, _-_A_t_t_r_i_b_u_t_e_s))                             _[_d_e_t_]
    Similar  to parse_url/2 for relative URLs.   If _U_R_L is relative,  it
    is resolved using the absolute _U_R_L _B_a_s_e_U_R_L.


wwwwww__ffoorrmm__eennccooddee((_+_V_a_l_u_e_, _-_X_W_W_W_F_o_r_m_E_n_c_o_d_e_d))                          _[_d_e_t_]


wwwwww__ffoorrmm__eennccooddee((_-_V_a_l_u_e_, _+_X_W_W_W_F_o_r_m_E_n_c_o_d_e_d))                          _[_d_e_t_]
    En/decode to/from  application/x-www-form-encoded.  Encoding encodes
    all  characters  except   RFC  3986  _u_n_r_e_s_e_r_v_e_d  (ASCII  alnum  (see
    code_type/2)),  and one of "-._~" using percent  encoding.   Newline
    is  mapped to  %OD%OA. When  decoding, newlines appear  as a  single
    newline (10) character.

    Note that a space  is encoded as %20 instead of +.  Decoding decodes
    both to a space.

         ddeepprreeccaatteedd Use uri_encoded/3 for new code.


sseett__uurrll__eennccooddiinngg((_?_O_l_d_, _+_N_e_w))                                   _[_s_e_m_i_d_e_t_]
    Query  and set the  encoding for URLs.   The default  is utf8.   The
    only other defined value is iso_latin_1.

         TToo bbee ddoonnee Having  a global  flag is  highly inconvenient,
             but  a work-around  for  old sites  using ISO  Latin 1
             encoding.


uurrll__iirrii((_+_E_n_c_o_d_e_d_, _-_D_e_c_o_d_e_d))                                        _[_d_e_t_]


uurrll__iirrii((_-_E_n_c_o_d_e_d_, _+_D_e_c_o_d_e_d))                                        _[_d_e_t_]
    Convert between a URL,  encoding in US-ASCII and an IRI. An IRI is a
    fully  expanded Unicode string.   Unicode strings are first  encoded
    into UTF-8, after which %-encoding takes place.


ppaarrssee__uurrll__sseeaarrcchh((_?_S_p_e_c_, _?_F_i_e_l_d_s_:_l_i_s_t_(_N_a_m_e_=_V_a_l_u_e_)))                  _[_d_e_t_]
    Construct or analyze  an HTTP search specification.  This deals with
    form  data using the MIME-type application/x-www-form-urlencoded  as
    used in HTTP GET requests.


ffiillee__nnaammee__ttoo__uurrll((_+_F_i_l_e_, _-_U_R_L))                                       _[_d_e_t_]


ffiillee__nnaammee__ttoo__uurrll((_-_F_i_l_e_, _+_U_R_L))                                   _[_s_e_m_i_d_e_t_]
    Translate between a filename and a file:// _U_R_L.

         TToo bbee ddoonnee Current   implementation  does  not  deal  with
             paths that need special encoding.


1133..3399 lliibbrraarryy((vvaarrnnuummbbeerrss))::  UUttiilliittiieess ffoorr nnuummbbeerreedd tteerrmmss

    SSeeee aallssoo  numbervars/4, =@=/2 (variant/2).

    CCoommppaattiibbiilliittyy  This  library  was  introduced  by  Quintus  and
         available in  many related  implementations,  although not
         with exactly the same set of predicates.

This  library  provides  the  inverse  functionality   of  the  built-in
numbervars/3.   Note  that this  library suffers from  the known  issues
that  '$VAR'(X) is  a  normal  Prolog term  and,  -unlike  the  built-in
numbervars-, the  inverse predicates do _n_o_t process  cyclic terms.   The
following  predicate is  true  for any  acyclic  term that  contains  no
'$VAR'(X), integer(X) terms and no constraint variables:

________________________________________________________________________|                                                                        |

|always_true(X) :-                                                       |
|      copy_term(X, X2),                                                 |
|      numbervars(X),                                                    |
|      varnumbers(X, Copy),                                              |
||_____Copy_=@=_X2._____________________________________________________ ||


nnuummbbeerrvvaarrss((_+_T_e_r_m))                                                 _[_d_e_t_]
    Number   variables    in   _T_e_r_m   using   $VAR(N).   Equivalent   to
    numbervars(Term, 0, _).

         SSeeee aallssoo numbervars/3, numbervars/4


vvaarrnnuummbbeerrss((_+_T_e_r_m_, _-_C_o_p_y))                                          _[_d_e_t_]
    Inverse of numbervars/1.  Equivalent to varnumbers(Term, 0, Copy).


vvaarrnnuummbbeerrss((_+_T_e_r_m_, _+_S_t_a_r_t_, _-_C_o_p_y))                                  _[_d_e_t_]
    Inverse  of numbervars/3.   True when  _C_o_p_y is a  copy of _T_e_r_m  with
    all  variables  numbered >=  _S_t_a_r_t  consistently replaced  by  fresh
    variables.    Variables in  _T_e_r_m are  _s_h_a_r_e_d with  _C_o_p_y rather  than
    replaced by fresh variables.

         EErrrroorrss domain_error(acyclic_term, Term)    if    _T_e_r_m   is
             cyclic.

         CCoommppaattiibbiilliittyy Quintus,  SICStus.   Not  in YAP  version of
             this library


mmaaxx__vvaarr__nnuummbbeerr((_+_T_e_r_m_, _+_S_t_a_r_t_, _-_M_a_x))                                _[_d_e_t_]
    True  when _M_a_x is the max of _S_t_a_r_t and the highest  numbered $VAR(N)
    term.

         aauutthhoorr Vitor Santos Costa

         CCoommppaattiibbiilliittyy YAP


vvaarrnnuummbbeerrss__nnaammeess((_+_T_e_r_m_, _-_C_o_p_y_, _-_V_a_r_i_a_b_l_e_N_a_m_e_s))                     _[_d_e_t_]
    If  _T_e_r_m  is a  term with  numbered and  named  variables using  the
    reserved  term  '$VAR'(X),  _C_o_p_y  is  a  copy  of  _T_e_r_m  where  each
    '$VAR'(X) is consistently  replaced by a fresh variable and Bindings
    is  a list X = Var,  relating the  _X terms with  the variable it  is
    mapped to.

         SSeeee aallssoo numbervars/3, varnumbers/3,  read_term/3using the
             variable_names option.


1133..4400 lliibbrraarryy((yyaallll))::  LLaammbbddaa eexxpprreessssiioonnss

    aauutthhoorr  Paulo Moura and Jan Wielemaker

    TToo bbee ddoonnee  Extend optimization support

Prolog  realizes _h_i_g_h_-_o_r_d_e_r  programming with  meta-calling.   The  core
predicate of this is call/1, which simply calls its argument.   This can
be used to define higher-order predicates such as  ignore/1 or forall/2.
The  call/N construct  calls a  _c_l_o_s_u_r_e with  N-1 _a_d_d_i_t_i_o_n_a_l  _a_r_g_u_m_e_n_t_s.
This is  used to define  higher-order predicates  such as the  maplist/N
family or foldl/N.

The  problem   with  higher   order  predicates  based   on  call/N   is
that  the  additional   arguments  are  always  added  to  the   end  of
the   closure's  argument   list.      This   often  requires   defining
trivial  helper  predicates to  get  the  argument  order right.     For
example,   if   you  want   to  add   a  common   postfix   to  a   list
of   atoms  you   need   to   apply  atom_concat(In,Postfix,Out),    but
maplist(x(PostFix),ListIn,ListOut)  calls x(PostFix,In,Out).    This  is
where this library comes in, which allows us to write

________________________________________________________________________|                                                                        |

|?- maplist([In,Out]>>atom_concat(In,'_p',Out), [a,b], ListOut).         |
|ListOut|=_[a_p,_b_p].__________________________________________________ |       |

The {...}  specifies which variables are  _s_h_a_r_e_d between the lambda  and
the context.    This allows us  to write the  code below.   Without  the
{PostFix} a free variable would be passed to atom_concat/3.

________________________________________________________________________|                                                                        |
|add_postfix(PostFix, ListIn, ListOut) :-                                |
|    maplist({PostFix}/[In,Out]>>atom_concat(In,PostFix,Out),            |
||___________ListIn,_ListOut).__________________________________________ ||

This introduces the second application area of lambda  expressions:  the
ability  to stop  binding  variables in  the  context.    This  features
shines when  combined with bagof/3  or setof/3  where you normally  have
to specify  the the variables  in whose binding  you are _n_o_t  interested
using the  Var^Goal construct (marking  _V_a_r as existential  quantified).
Lambdas allow  doing the reverse:   specify the  variables in which  you
are interested.

Lambda expressions use the syntax below

________________________________________________________________________|                                                                        |

|{...}/[...]>>Goal.|____________________________________________________ |                  |

The {...} optional  part is used for  lambda-free variables.  The  order
of variables doesn't matter hence the {...} set notation.

The  [...]  optional part  lists  lambda  parameters.    Here  order  of
variables matters hence the list notation.

As / and >> are standard infix operators, no new  operators are added by
this library.  An  advantage of this syntax is that we can  simply unify
a lambda expression  with Free/Parameters>>Lambda to access each of  its
components.  Spaces in the lambda expression are  not a problem although
the goal may need to be written between ()'s.   Goals that are qualified
by a module prefix also need to be wrapped inside parentheses.

Combined  with   library(apply_macros),  library(yall)  allows   writing
one-liners for  many list operations that  have the same performance  as
hand written code.

The module name, _y_a_l_l, stands for Yet Another Lambda Library.

This  module  implements  Logtalk's lambda  expressions  syntax.     The
development of this module was sponsored by Kyndi, Inc.


_+_P_a_r_a_m_e_t_e_r_s >> _+_L_a_m_b_d_a


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1))


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1_, _?_A_2))


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3))


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4))


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4_, _?_A_5))


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4_, _?_A_5_, _?_A_6))


>>((_+_P_a_r_a_m_e_t_e_r_s_, _+_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4_, _?_A_5_, _?_A_6_, _?_A_7))
    Calls  a copy of  _L_a_m_b_d_a.   This is similar to  call(Lambda,A1,...),
    but arguments are reordered according to the list _P_a_r_a_m_e_t_e_r_s:

      o  The  first length(Parameters)  arguments  from  _A_1, ...     are
         unified with (a copy of) _P_a_r_a_m_e_t_e_r_s, which _m_a_y  share them with
         variables in _L_a_m_b_d_a.

      o  Possible excess arguments are passed by position.

    ___________________________________________________________Arguments_
     _P_a_r_a_m_e_t_e_r_s  is  either a plain list of parameters or a  term
                 {Free}/List.    _F_r_e_e represents  variables  that
                 are  shared between the  context and the  _L_a_m_b_d_a

                 term.    This  is  needed for  compiling  _L_a_m_b_d_a
                 expressions.


_+_F_r_e_e / _:_L_a_m_b_d_a


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1))


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1_, _?_A_2))


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3))


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4))


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4_, _?_A_5))


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4_, _?_A_5_, _?_A_6))


/((_+_F_r_e_e_, _:_L_a_m_b_d_a_, _?_A_1_, _?_A_2_, _?_A_3_, _?_A_4_, _?_A_5_, _?_A_6_, _?_A_7))
    Shorthand for Free/[]>>Lambda.   This is the same as applying call/N
    on  _L_a_m_b_d_a, except that only  variables appearing in _F_r_e_e are  bound
    by the call.  For example

    ____________________________________________________________________|                                                                    |
    | p(1,a).                                                            |

    | p(2,b).                                                            |
    |                                                                    |
    | ?- {X}/p(X,Y).                                                     |
    | X = 1;                                                             |
    ||X_=_2.____________________________________________________________ ||

    This  can  in  particularly be  combined  with bagof/3  and  setof/3
    to  _s_e_l_e_c_t particular  variables to be  concerned rather than  using
    existential  quantification  (^/2)   to  _e_x_c_l_u_d_e  variables.     For
    example, the two calls below are equivalent.

    ____________________________________________________________________|                                                                    |
    | setof(X, Y^p(X,Y), Xs)                                             |

    ||setof(X,_{X}/p(X,_),_Xs)__________________________________________ ||


iiss__llaammbbddaa((_@_T_e_r_m))                                               _[_s_e_m_i_d_e_t_]
    True if _T_e_r_m is a valid Lambda expression.


llaammbbddaa__ccaallllss((_+_L_a_m_b_d_a_E_x_p_r_e_s_s_i_o_n_, _-_G_o_a_l))                             _[_d_e_t_]


llaammbbddaa__ccaallllss((_+_L_a_m_b_d_a_E_x_p_r_e_s_s_i_o_n_, _+_E_x_t_r_a_A_r_g_s_, _-_G_o_a_l))                 _[_d_e_t_]
    _G_o_a_l  is the goal called  if call/N is applied to  _L_a_m_b_d_a_E_x_p_r_e_s_s_i_o_n,
    where  _E_x_t_r_a_A_r_g_s are the  additional arguments to call/N.  _E_x_t_r_a_A_r_g_s
    can  be an integer or a list of concrete arguments.   This predicate
    is used for cross-referencing and code highlighting.


CChhaapptteerr 1144..  HHAACCKKEERRSS CCOORRNNEERR

This  appendix  describes  a  number  of  predicates  which  enable  the
Prolog  user  to  inspect the  Prolog  environment  and  manipulate  (or
even redefine)  the debugger.    They can be  used as  entry points  for
experiments with debugging  tools for Prolog.  The  predicates described
here should  be handled  with some  care as it  is easy  to corrupt  the
consistency of the Prolog system by misusing them.


1144..11 EExxaammiinniinngg tthhee EEnnvviirroonnmmeenntt SSttaacckk


pprroolloogg__ccuurrrreenntt__ffrraammee((_-_F_r_a_m_e))                                       _[_d_e_t_]
    Unify  _F_r_a_m_e with  an integer  providing a reference  to the  parent
    of  the  current local  stack  frame.    A  pointer to  the  current
    local   frame  cannot   be  provided  as   the  predicate   succeeds
    deterministically  and therefore its frame is  destroyed immediately
    after succeeding.


pprroolloogg__ccuurrrreenntt__cchhooiiccee((_-_C_h_o_i_c_e))                                 _[_s_e_m_i_d_e_t_]
    Unify  _C_h_o_i_c_e  with an  integer  provided a  reference to  the  last
    choice  point.    Fails if  the current  environment  has no  choice
    points.  See also prolog_choice_attribute/3.


pprroolloogg__ffrraammee__aattttrriibbuuttee((_+_F_r_a_m_e_, _+_K_e_y_, _:_V_a_l_u_e))
    Obtain  information  about  the local  stack  frame  _F_r_a_m_e.    _F_r_a_m_e
    is  a  frame reference  as obtained  through prolog_current_frame/1,
    prolog_trace_interception/4 or this predicate.   The key values  are
    described below.

    aalltteerrnnaattiivvee
         _V_a_l_u_e is unified with  an integer reference to the  local stack
         frame in  which execution  is  resumed if  the goal  associated
         with _F_r_a_m_e  fails.    Fails  if the  frame has  no  alternative
         frame.

    hhaass__aalltteerrnnaattiivveess
         _V_a_l_u_e is unified  with true if _F_r_a_m_e  still is a candidate  for
         backtracking; false otherwise.

    ggooaall
         _V_a_l_u_e is  unified with  the  goal associated  with _F_r_a_m_e.    If
         the  definition module  of  the  active predicate  is  not  the
         calling context,  the  goal is  represented as  <_m_o_d_u_l_e>:<_g_o_a_l>.
         Do  not instantiate  variables in  this  goal unless  you  kknnooww
         what you are  doing!  Note  that the returned term may  contain
         references to  the frame  and  should be  discarded before  the
         frame terminates.

    ppaarreenntt__ggooaall
         If _V_a_l_u_e  is  instantiated to  a callable  term,  find a  frame
         executing  the  predicate described  by  _V_a_l_u_e  and  unify  the
         arguments of _V_a_l_u_e  to the goal  arguments associated with  the
         frame.    This  is  intended  to check  the  current  execution
         context.  The user  must ensure the checked parent goal  is not
         removed from  the stack  due to last-call  optimisation and  be
         aware of the slow operation on deeply nested calls.

    pprreeddiiccaattee__iinnddiiccaattoorr
         Similar     to    goal,      but     only     returning     the
         [<_m_o_d_u_l_e>:]<_n_a_m_e>/<_a_r_i_t_y>   term   describing  the   term,    not
         the actual arguments.   It avoids  creating an illegal term  as
         goal and is used by the library prolog_stack.

    ccllaauussee
         _V_a_l_u_e is  unified with  a  reference to  the currently  running
         clause.    Fails  if the  current  goal  is associated  with  a
         foreign  (C) defined  predicate.    See  also nth_clause/3  and
         clause_property/2.

    lleevveell
         _V_a_l_u_e is unified  with the recursion level  of _F_r_a_m_e.  The  top
         level frame is at level `0'.

    ppaarreenntt
         _V_a_l_u_e is unified with an integer reference to  the parent local
         stack frame of _F_r_a_m_e.  Fails if _F_r_a_m_e is the top frame.

    ccoonntteexxtt__mmoodduullee
         _V_a_l_u_e is  unified with the  name of the  context module of  the
         environment.

    ttoopp
         _V_a_l_u_e is  unified with  true if _F_r_a_m_e  is the  top Prolog  goal
         from a  recursive call back  from the  foreign language;  false
         otherwise.

    hhiiddddeenn
         _V_a_l_u_e is  unified with  true if the  frame is  hidden from  the
         user, either  because a  parent has  the hide-childs  attribute
         (all  system  predicates),  or  the  system   has  no  trace-me
         attribute.

    sskkiippppeedd
         _V_a_l_u_e is true if this frame was skipped in the debugger.

    ppcc
         _V_a_l_u_e  is unified  with the  program  pointer saved  on  behalf
         of  the parent  goal if  the  parent goal  is  not owned  by  a
         foreign predicate  or belongs  to a  compound meta-call  (e.g.,
         call((a,b))).

    aarrgguummeenntt((_N))
         _V_a_l_u_e is  unified with the _N-th  slot of the  frame.   Argument
         1 is  the first  argument of  the goal.    Arguments above  the
         arity refer to local variables.  Fails silently if _N  is out of
         range.


pprroolloogg__cchhooiiccee__aattttrriibbuuttee((_+_C_h_o_i_c_e_P_o_i_n_t_, _+_K_e_y_, _-_V_a_l_u_e))
    Extract  attributes of a choice point.   _C_h_o_i_c_e_P_o_i_n_t is a  reference
    to  a  choice  point  as  passed  to prolog_trace_interception/4  on
    the  3rd argument  or obtained  using prolog_current_choice/1.    _K_e_y
    specifies the requested information:

    ppaarreenntt
         Requests a reference to the first older choice point.

    ffrraammee
         Requests a  reference to the  frame to  which the choice  point
         refers.

    ttyyppee
         Requests  the type.     Defined  values are  clause  (the  goal
         has alternative  clauses),  foreign (non-deterministic  foreign
         predicate),  jump (clause  internal choice  point), top  (first
         dummy choice point), catch  (catch/3 to allow for undo),  debug
         (help the debugger), or none (has been deleted).

    This  predicate  is used  for  the graphical  debugger to  show  the
    choice point stack.


ddeetteerrmmiinniissttiicc((_-_B_o_o_l_e_a_n))
    Unifies  its argument with  true if no  choice point exists that  is
    more  recent  than the  entry of  the clause  in  which it  appears.
    There  are few realistic  situations for using  this predicate.   It
    is  used by the  prolog/0 top level  to check whether Prolog  should
    prompt  the user for alternatives.  Similar results can  be achieved
    in a more portable fashion using call_cleanup/2.


1144..22 AAnncceessttrraall ccuuttss


pprroolloogg__ccuutt__ttoo((_+_C_h_o_i_c_e))
    Prunes  all  choice  points created  since  _C_h_o_i_c_e.    Can  be  used
    together  with prolog_current_choice/1 to implement _a_n_c_e_s_t_r_a_l  cuts.
    This  predicate is in  the hackers corner  because it should not  be
    used  in normal  Prolog code.   It may  be used  to create new  high
    level control structures, particularly for compatibility purposes.

    Note  that in the current  implementation, the pruned choice  points
    and  environment frames are _n_o_t reclaimed.  As a  consequence, where
    predicates  that are  deterministic due to  clause indexing,  normal
    cuts  or (if\send{then};else) and and tail recursive run  in bounded
    local  stack space, predicates using prolog_cut_to/1will  run out of
    stack.


1144..33 IInntteerrcceeppttiinngg tthhee TTrraacceerr


pprroolloogg__ttrraaccee__iinntteerrcceeppttiioonn((_+_P_o_r_t_, _+_F_r_a_m_e_, _+_C_h_o_i_c_e_, _-_A_c_t_i_o_n))
    Dynamic  predicate, normally not defined.  This predicate  is called
    from  the SWI-Prolog  debugger  just before  it would  show a  port.
    If  this predicate  succeeds, the  debugger assumes  that the  trace
    action  has been taken care of and continues execution  as described
    by  _A_c_t_i_o_n.    Otherwise  the  normal  Prolog debugger  actions  are
    performed.

    _P_o_r_t  denotes  the reason  to  activate the  tracer (`port'  in  the
    4/5-port, but with some additions):

    ccaallll
         Normal entry through the call port of the 4-port debugger.

    rreeddoo((_P_C))
         Normal entry  through the  redo  port of  the 4-port  debugger.
         The  redo  port  signals  resuming  a  predicate   to  generate
         alternative solutions.  If _P_C is 0 (zero),  clause indexing has
         found another clause  that will be tried  next.  Otherwise,  _P_C
         is the program  counter in the  current clause where  execution
         continues.    This implies  we are  dealing  with an  in-clause
         choice point left by, e.g., ;/2.  Note  that non-determinism in
         foreign predicates are  also handled using an in-clause  choice
         point.

    uunniiffyy
         The  unify port  represents  the _n_e_c_k  instruction,  signalling
         the end of  the head-matching process.   This port is  normally
         invisible.  See leash/1 and visible/1.

    eexxiitt
         The exit port signals the  goal is proved.  It is  possible for
         the goal to have alternatives.  See prolog_frame_attribute/3 to
         examine the goal stack.

    ffaaiill
         The fail port signals final failure of the goal.

    eexxcceeppttiioonn((_E_x_c_e_p_t))
         An  exception is  raised  and still  pending.    This  port  is
         activated on  each parent  frame  of the  frame generating  the
         exception until the  exception is caught  or the user  restarts
         normal  computation  using  retry.     _E_x_c_e_p_t  is  the  pending
         exception term.

    bbrreeaakk((_P_C))
         A break instruction is executed.  _P_C is program counter.   This
         port is used by the graphical debugger.

    ccuutt__ccaallll((_P_C))
         A cut is encountered at _P_C. This port is used  by the graphical
         debugger to visualise the effect of the cut.

    ccuutt__eexxiitt((_P_C))
         A cut has  been executed.   See cut_call(_P_C) for more  informa-
         tion.

    _F_r_a_m_e  is  a  reference to  the  current local  stack  frame,  which
    can  be  examined  using  prolog_frame_attribute/3.     _C_h_o_i_c_e  is  a
    reference  to  the  last choice  point  and  can be  examined  using
    prolog_choice_attribute/3.  _A_c_t_i_o_n must be unified with  a term that
    specifies  how execution must continue.   The following actions  are
    defined:

    aabboorrtt
         Abort execution.  See abort/0.

    ccoonnttiinnuuee
         Continue (i.e., _c_r_e_e_p in the command line debugger).

    ffaaiill
         Make the current goal fail.

    iiggnnoorree
         Step over the current goal without executing it.

    nnooddeebbuugg
         Continue execution in normal nodebugging mode.  See nodebug/0.

    rreettrryy
         Retry the current frame.

    rreettrryy((_F_r_a_m_e))
         Retry the given  frame.  This must  be a parent of the  current
         frame.

    sskkiipp
         Skip over  the current  goal (i.e.,  _s_k_i_p in  the command  line
         debugger).

    uupp
         Skip  to  the  parent  goal  (i.e.,  _u_p  in  the  command  line
         debugger).

    Together  with the predicates described in section ???? and  the other
    predicates  of this chapter, this predicate enables the  Prolog user
    to  define  a  complete new  debugger  in  Prolog.    Besides  this,
    it  enables the  Prolog  programmer to  monitor the  execution of  a
    program.  The  example below records all goals trapped by the tracer
    in the database.

    ____________________________________________________________________|                                                                    |
    | prolog_trace_interception(Port, Frame, _PC, continue) :-           |
    |         prolog_frame_attribute(Frame, goal, Goal),                 |
    |         prolog_frame_attribute(Frame, level, Level),               |

    ||________recordz(trace,_trace(Port,_Level,_Goal))._________________ ||

    To  trace the execution of `go' this way the following  query should
    be given:

    ____________________________________________________________________|                                                                    |
    ||?-_trace,_go,_notrace.____________________________________________ ||


pprroolloogg__sskkiipp__ffrraammee((_-_F_r_a_m_e))
    Indicate  _F_r_a_m_e as  a skipped frame  and set  the `skip level'  (see
    prolog_skip_level/2 to the recursion depth of _F_r_a_m_e.   The effect of
    the skipped flag is  that a redo on a child of this frame is handled
    differently.   First,  a redo trace is  called for the child,  where
    the skip  level is set to redo_in_skip.  Next, the  skip level is set
    to skip level of the skipped frame.


pprroolloogg__sskkiipp__lleevveell((_-_O_l_d_, _+_N_e_w))
    Unify  _O_l_d  with  the  old  value  of  `skip  level'  and  then  set
    this  level  according  to  _N_e_w.    _N_e_w  is  an  integer,  the  atom
    very_deep  (meaning  don't  skip)  or  the  atom  skip_in_redo  (see
    prolog_skip_frame/1).  The `skip level' is a setting  of each Prolog
    thread  that disables  the debugger on  all recursion levels  deeper
    than the level of the variable.  See also prolog_skip_frame/1.


1144..44 BBrreeaakkppooiinntt aanndd wwaattcchhppooiinntt hhaannddlliinngg

SWI-Prolog support  _b_r_e_a_k_p_o_i_n_t_s.   Breakpoints can  be manipulated  with
the  library  prolog_breakpoints.     Setting  a  breakpoint  replaces  a
virtual  machine instruction  with  the D_BREAK  instruction.    If  the
virtual machine executes a D_BREAK, it performs a callback  to decide on
the action  to perform.   This section  describes this callback,  called
prolog:break_hook/6.


pprroolloogg::bbrreeaakk__hhooookk((_+_C_l_a_u_s_e_, _+_P_C_, _+_F_R_, _+_B_F_R_, _+_E_x_p_r_e_s_s_i_o_n_, _-_A_c_t_i_o_n))_[_h_o_o_k_,_s_e_m_i_d_e_t_]
    _E_x_p_e_r_i_m_e_n_t_a_l  This hook is called if the virtual machine  executes a
    D_BREAK,  set using set_breakpoint/4.   _C_l_a_u_s_e  and _P_C identify  the
    breakpoint.   _F_R and _B_F_R  provide the environment frame and  current
    choicepoint.   _E_x_p_r_e_s_s_i_o_n identifies the action that is interrupted,
    and is one of the following:

    ccaallll((_G_o_a_l))
         The instruction will call  _G_o_a_l.  This is generated  for nearly
         all instructions.   Note that  _G_o_a_l is semantically  equivalent
         to the  compiled  body term,  but  might differ  syntactically.
         This  is  notably the  case  when  arithmetic  expressions  are
         compiled in  optimized mode  (see  optimise).   In  particular,
         the  arguments  of arithmetic  expressions  have  already  been
         evaluated.   Thus,  _A is  3*_B, where _B  equals 3  results in  a
         term call(A is 9) if the clause was compiled  with optimization
         enabled.

    !
         The instruction will  call the cut.   Because the semantics  of
         metacalling  the cut  differs from  executing  the cut  in  its
         original context we do not wrap the cut in call/1.

    :-
         The  breakpoint  is  on  the  _n_e_c_k  instruction,  i.e.,   after
         performing the head unifications.

    eexxiitt
         The breakpoint is on the _e_x_i_t instruction, i.e., at  the end of
         the clause.  Note that the exit instruction may  not be reached
         due to last-call optimisation.

    uunniiffyy__eexxiitt
         The breakpoint is on the completion of  an in-lined unification
         while the system  is not in  debug mode.   If the system is  in
         debug mode, inlined unification is returned as call(Var=Term).

    If  prolog:break_hook/6 succeeds, it  must unify _A_c_t_i_o_n with a  value
    that  describes how execution  must continue.   Possible values  for
    _A_c_t_i_o_n are:

    ccoonnttiinnuuee
         Just continue as if no breakpoint was present.

    ddeebbuugg
         Continue in _d_e_b_u_g _m_o_d_e.  See debug/0.

    ttrraaccee
         Continue in _t_r_a_c_e _m_o_d_e.  See trace/0.

    ccaallll((_G_o_a_l))
         Execute  _G_o_a_l instead  of  the  goal that  would  be  executed.
         _G_o_a_l is  executed as call/1,  preserving (non-)determinism  and
         exceptions.

    If  this  hook throws  an  exception,  the exception  is  propagated
    normally.  If  this hook is not defined or fails, the default action
    is  executed.  This  implies that, if the  thread is in debug  mode,
    the  tracer will be enabled (trace) and otherwise the  breakpoint is
    ignored (continue).

    This hook allows  for injecting various debugging scenarios into the
    executable  without recompiling.   The hook can access variables  of
    the  calling context using  the frame inspection  predicates.   Here
    are some examples.

      o  Create _c_o_n_d_i_t_i_o_n_a_l  breakpoints by  imposing conditions  before
         deciding the return trace.

      o  Watch variables  at a specific  point in the  execution.   Note
         that  binding  of  these  variables  can  be   monitored  using
         _a_t_t_r_i_b_u_t_e_d _v_a_r_i_a_b_l_e_s, see section ????.

      o  Dynamically add _a_s_s_e_r_t_i_o_n_s on variables using assertion/1.

      o  Wrap the  _G_o_a_l into  a meta-call  that traces  progress of  the
         _G_o_a_l.


1144..55 AAddddiinngg ccoonntteexxtt ttoo eerrrroorrss::  pprroolloogg__eexxcceeppttiioonn__hhooookk

The hook prolog_exception_hook/4 has been introduced in SWI-Prolog 5.6.5
to  provide  dedicated exception  handling  facilities  for  application
frameworks, for  example non-interactive  server applications that  wish
to provide extensive context for exceptions for offline debugging.


pprroolloogg__eexxcceeppttiioonn__hhooookk((_+_E_x_c_e_p_t_i_o_n_I_n_, _-_E_x_c_e_p_t_i_o_n_O_u_t_, _+_F_r_a_m_e_, _+_C_a_t_c_h_e_r_F_r_a_m_e))
    This  hook predicate,  if  defined in  the module  user, is  between
    raising  an  exception   and  handling  it.     It  is  intended  to
    allow  a  program  adding  additional context  to  an  exception  to
    simplify  diagnosing  the problem.    _E_x_c_e_p_t_i_o_n_I_n  is the  exception
    term  as  raised  by throw/1  or  one  of the  built-in  predicates.
    The  output  argument  _E_x_c_e_p_t_i_o_n_O_u_t  describes  the  exception  that
    is  actually  raised.      _F_r_a_m_e  is  the  innermost  frame.     See
    prolog_frame_attribute/3 and  the library  prolog_stack for  getting
    information  from this.   _C_a_t_c_h_e_r_F_r_a_m_e is  a reference to the  frame
    calling  the matching catch/3, none  if the exception is not  caught
    or  'C' if the  exception is  caught in C  calling Prolog using  the
    flag PL_Q_CATCH_EXCEPTION.

    The hook is run  in `nodebug' mode.  If it succeeds, _E_x_c_e_p_t_i_o_n_O_u_t is
    considered the current  exception.  If it fails, _E_x_c_e_p_t_i_o_n_I_n is used
    for further processing.   The hook is _n_e_v_e_r called recursively.  The
    hook is _n_o_t allowed  to modify _E_x_c_e_p_t_i_o_n_O_u_t in such a way that it no
    longer unifies with the catching frame.

    Typically,   prolog_exception_hook/4 is  used  to  fill  the  second
    argument  of error(_F_o_r_m_a_l_, _C_o_n_t_e_x_t) exceptions.   _F_o_r_m_a_l is  defined
    by  the  ISO  standard,   while  SWI-Prolog  defines  _C_o_n_t_e_x_t  as  a
    term  context(_L_o_c_a_t_i_o_n_,  _M_e_s_s_a_g_e).    _L_o_c_a_t_i_o_n is  bound to  a  term
    <_n_a_m_e>/<_a_r_i_t_y>  by the kernel.    This hook can  be used to  add more
    information on the calling context, such as a full stack trace.

    Applications  that use exceptions as part of normal  processing must
    do  a  quick  test  of the  environment  before  starting  expensive
    gathering information on the state of the program.

    The  hook can call  trace/0 to  enter trace mode  immediately.   For
    example,  imagine an application performing an unwanted  division by
    zero while all other  errors are expected and handled.  We can force
    the  debugger using the hook definition  below.  Run the program  in
    debug  mode (see  debug/0) to preserve  as much  as possible of  the
    error context.

    ____________________________________________________________________|                                                                    |
    | user:prolog_exception_hook(                                        |
    |          error(evaluation_error(zero_divisor), _),                 |
    |          _, _, _) :-                                               |

    ||________trace,_fail.______________________________________________ ||


1144..66 HHooookkss uussiinngg tthhee eexxcceeppttiioonn pprreeddiiccaattee

This section describes  the predicate exception/3, which can  be defined
by the  user in the module  user as a multifile  predicate.  Unlike  the
name suggests,  this is actually a _h_o_o_k  predicate that has no  relation
to  Prolog exceptions  as  defined by  the  ISO predicates  catch/3  and
throw/1.

The  predicate exception/3  is  called by  the  kernel  on a  couple  of
events, allowing the user  to `fix' errors just-in-time.   The mechanism
allows for _l_a_z_y creation of objects such as predicates.


eexxcceeppttiioonn((_+_E_x_c_e_p_t_i_o_n_, _+_C_o_n_t_e_x_t_, _-_A_c_t_i_o_n))
    Dynamic  predicate,  normally not  defined.   Called  by the  Prolog
    system  on run-time exceptions that can be  repaired `just-in-time'.
    The values for _E_x_c_e_p_t_i_o_n  are described below.  See also catch/3 and
    throw/1.

    If  this  hook predicate  succeeds it  must  instantiate the  _A_c_t_i_o_n
    argument  to the  atom  fail to  make the  operation fail  silently,
    retry  to tell Prolog  to retry the operation  or error to make  the
    system generate an exception.   The action retry only makes sense if
    this  hook modified the environment such that the operation  can now
    succeed without error.

    uunnddeeffiinneedd__pprreeddiiccaattee
         _C_o_n_t_e_x_t   is    instantiated   to    a   predicate    indicator
         ([module]:<_n_a_m_e>/<_a_r_i_t_y>).  If the  predicate fails, Prolog will
         generate an  existence_error exception.   The hook is  intended
         to implement alternatives  to the built-in autoloader, such  as
         autoloading code  from a database.    Do _n_o_t use  this hook  to
         suppress existence errors on predicates.  See  also unknown and
         section ????.

    uunnddeeffiinneedd__gglloobbaall__vvaarriiaabbllee
         _C_o_n_t_e_x_t  is instantiated  to the  name  of the  missing  global
         variable.  The hook  must call nb_setval/2 or b_setval/2 before
         returning with the action retry.


1144..77 HHooookkss ffoorr iinntteeggrraattiinngg lliibbrraarriieess

Some libraries  realise an entirely new  programming paradigm on top  of
Prolog.   An example is  XPCE which adds an  object system to Prolog  as
well as an extensive  set of graphical primitives.   SWI-Prolog provides
several hooks to  improve the integration of  such libraries.  See  also
section  ???? for  editing  hooks and  section  ????  for hooking  into  the
message system.


pprroolloogg__lliisstt__ggooaall((_:_G_o_a_l))
    Hook, normally not defined.   This hook is called by the 'L' command
    of  the  tracer in  the module  user to  list  the currently  called
    predicate.   This hook may be defined to list only  relevant clauses
    of  the indicated  _G_o_a_l and/or  show the  actual source  code in  an
    editor.  See also portray/1 and multifile/1.


pprroolloogg::ddeebbuugg__ccoonnttrrooll__hhooookk((_:_A_c_t_i_o_n))
    Hook for the  debugger control predicates that allows the creator of
    more  high-level programming languages  to use the common  front-end
    predicates  to control the debugger.   For example, XPCE uses  these
    hooks  to allow for spying methods  rather than predicates.   _A_c_t_i_o_n
    is one of:

    ssppyy((_S_p_e_c))
         Hook in  spy/1.  If  the hook succeeds  spy/1 takes no  further
         action.

    nnoossppyy((_S_p_e_c))
         Hook  in nospy/1.    If  the  hook  succeeds nospy/1  takes  no
         further action.  If  spy/1 is hooked, it is advised to  place a
         complementary hook for nospy/1.

    nnoossppyyaallll
         Hook in nospyall/0.   Should remove all spy points.   This hook
         is called in a failure-driven loop.

    ddeebbuuggggiinngg
         Hook in  debugging/0.   It can  be used in  two ways.   It  can
         report the  status of  the additional  debug points  controlled
         by the  above  hooks and  fail  to let  the system  report  the
         others,  or it  succeeds, overruling  the  entire behaviour  of
         debugging/0.


pprroolloogg::hheellpp__hhooookk((_+_A_c_t_i_o_n))
    Hook  into help/0 and help/1.   If  the hook succeeds, the  built-in
    actions are not  executed.  For example, ?- help(picture). is caught
    by  the XPCE help hook to give  help on the class _p_i_c_t_u_r_e.   Defined
    actions are:

    hheellpp
         User entered plain  help/0 to give default  help.  The  default
         performs help(help/1), giving help on help.

    hheellpp((_W_h_a_t))
         Hook in help/1 on the topic _W_h_a_t.

    aapprrooppooss((_W_h_a_t))
         Hook in apropos/1 on the topic _W_h_a_t.


1144..88 HHooookkss ffoorr llooaaddiinngg ffiilleess

All loading  of source  files is  achieved by  load_files/2.   The  hook
prolog_load_file/2 can be  used to  load Prolog code  from non-files  or
even load entirely different information, such as foreign files.


pprroolloogg__llooaadd__ffiillee((_+_S_p_e_c_, _+_O_p_t_i_o_n_s))
    Load  a single object.  If this  call succeeds, load_files/2 assumes
    the  action has been  taken care of.   This hook  is only called  if
    _O_p_t_i_o_n_s  does not contain the stream(_I_n_p_u_t)  option.  The hook  must
    be defined in the module user.

    This  can  be used  to  load  from unusual  places.    For  example,
    library  http/http_load  loads Prolog directly  from an HTTP  server.
    It  can  also be  used to  load  source in  unusual forms,  such  as
    loading  compressed files without decompressing  them first.   There
    is currently no example of that.


pprroolloogg::ccoommmmeenntt__hhooookk((_+_C_o_m_m_e_n_t_s_, _+_P_o_s_, _+_T_e_r_m))
    This  hook  allows   for  processing  comments  encountered  by  the
    compiler.   If this hook is defined,  the compiler calls read_term/2
    with  the  option  comments(_C_o_m_m_e_n_t_s).    If  the list  of  comments
    returned  by read_term/2  is not empty  it calls  this comment  hook
    with the following arguments.

      o  _C_o_m_m_e_n_t_s is the  non-empty list of comments.   Each comment  is
         a pair _P_o_s_i_t_i_o_n-_S_t_r_i_n_g,  where _S_t_r_i_n_g is  a string object  (see
         section ????)  that  contains the  comment _i_n_c_l_u_d_i_n_g  delimiters.
         Consecutive line comments are returned as a single comment.

      o  _P_o_s  is a  stream-position  term  that describes  the  starting
         position of _T_e_r_m

      o  _T_e_r_m is the term read.

    This   hook  is  exploited  by  the  documentation  system.      See
    stream_position_data/3.  See also read_term/3.


CChhaapptteerr 1155..  CCOOMMPPAATTIIBBIILLIITTYY WWIITTHH OOTTHHEERR PPRROOLLOOGG DDIIAALLEECCTTSS

This  chapter explains  issues  for  writing portable  Prolog  programs.
It was  started after discussion  with Vitor  Santos Costa, the  leading
developer  of  YAP   Prolog  YAP  and  SWI-Prolog  have  expressed   the
ambition to enhance the portability beyond the  trivial Prolog examples,
including complex libraries involving foreign code.

Although it  is our  aim to enhance  compatibility, we  are still  faced
with many incompatibilities between the dialects.  As  a first step both
YAP and SWI will provide some instruments that  help developing portable
code.   A first  release of these tools  appeared in SWI-Prolog  5.6.43.
Some of  the facilities are  implemented in the  base system, others  in
the library dialect.pl.

  o The  Prolog flag dialect is an unambiguous and fast way to  find out
    which  Prolog dialect executes your program.   It has the value  swi
    for SWI-Prolog and yap on YAP.

  o The  Prolog flag version_data is bound  to a term swi(_M_a_j_o_r_,  _M_i_n_o_r_,
    _P_a_t_c_h_, _E_x_t_r_a)

  o Conditional   compilation  using  :- if(Condition)  ...:- endif   is
    supported.  See section ????.

  o The  predicate  expects_dialect/1 allows  for specifying  for  which
    Prolog system the code was written.

  o The  predicates exists_source/1 and source_exports/2 can be used  to
    query  the library content.  The require/1 directive can be  used to
    get access to predicates without knowing their location.

  o The  module predicates use_module/1,  use_module/2have  been extended
    with  a  notion  for  `import-except'  and `import-as'.     This  is
    particularly  useful  together  with reexport/1  and  reexport/2  to
    compose modules from other modules and mapping names.

  o Foreign  code can expect __SWI_PROLOG__ when compiled for  SWI-Prolog
    and  __YAP_PROLOG__when compiled on YAP.


::-- eexxppeeccttss__ddiiaalleecctt((_+_D_i_a_l_e_c_t))
    This  directive  states that  the code  following  the directive  is
    written  for the  given Prolog  _D_i_a_l_e_c_t.   See  also dialect.    The
    declaration  holds until the  end of the  file in which it  appears.
    The current dialect is available using prolog_load_context/2.

    The   exact  behaviour  of  this  predicate  is  still   subject  to
    discussion.   Of course, if _D_i_a_l_e_c_t matches the running  dialect the
    directive  has no  effect.   Otherwise  we check  for the  existence
    of  library(_d_i_a_l_e_c_t_/_D_i_a_l_e_c_t)  and  load it  if  the file  is  found.
    Currently, this file has this functionality:

      o  Define system  predicates of  the requested dialect  we do  not
         have.

      o  Apply goal_expansion/2  rules that  map conflicting  predicates
         to versions emulating the  requested dialect.  These  expansion
         rules  reside in  the  dialect compatibility  module,  but  are
         applied if prolog_load_context(dialect, Dialect) is active.

      o  Modify  the  search  path  for  library  directories,   putting
         libraries compatible with the target dialect before  the native
         libraries.

      o  Setup  support  for  the  default  filename  extension  of  the
         dialect.


eexxiissttss__ssoouurrccee((_+_S_p_e_c))
    Is  true if  _S_p_e_c exists as  a Prolog source.    _S_p_e_c uses the  same
    conventions as  load_files/2.  Fails without error  if _S_p_e_c cannot be
    found.


ssoouurrccee__eexxppoorrttss((_+_S_p_e_c_, _+_E_x_p_o_r_t))
    Is  true  if source  _S_p_e_c  exports _E_x_p_o_r_t,  a  predicate  indicator.
    Fails without error otherwise.


1155..11 SSoommee ccoonnssiiddeerraattiioonnss ffoorr wwrriittiinngg ppoorrttaabbllee ccooddee

The  traditional  way  to  write  portable  code  is  to  define  custom
predicates  for  all  potentially non-portable  code  and  define  these
separately for  all Prolog  dialects one wishes  to support.   Here  are
some considerations.

  o Probably  the  best reason  for this  is that  it  allows to  define
    minimal  semantics required by  the application for the  portability
    predicates.   Such functionality can often be mapped  efficiently to
    the  target dialect.    Contrary, if  code was  written for  dialect
    X,  the defined semantics are  those of dialect X.   Emulating all
    extreme  cases and full error handling compatibility may  be tedious
    and  result in a much slower  implementation that needed.  Take  for
    example  call_cleanup/2.   The SICStus  definition is  fundamentally
    different from the  SWI definition, but 99% of the applications just
    want to make  calls like below to guarantee _S_t_r_e_a_m_I_n is closed, even
    if process/1 misbehaves.

    ____________________________________________________________________|                                                                    |

    ||________call_cleanup(process(StreamIn),_close(In))________________ ||

  o As  a drawback,  the code becomes  full of _m_y___c_a_l_l___c_l_e_a_n_u_p, etc.  and
    every  potential portability conflict  needs to be  abstracted.   It
    is  hard for people  who have to maintain  such code later to  grasp
    the  exact semantics  of the  _m_y___* predicates  and applications  that
    combine  multiple libraries  using this  compatibility approach  are
    likely  to encounter conflicts  between the portability  layers.   A
    good  start  is not  to  use _m_y___*, but  a  prefix derived  from  the
    library  or  application name  or names  that  explain the  intended
    semantics more precisely.

  o Another  problem  is   that  most  code  is  initially  not  written
    with  portability  in  mind.     Instead,  ports  are  requested  by
    users   or  arise  from  the   desire  to  switch  Prolog   dialect.
    Typically,  we want  to achieve  compatibility with  the new  Prolog
    dialect  with  minimal  changes,  often keeping  compatibility  with
    the  original  dialect(s).   This  problem is  well  known from  the
    C/Unix  world  and  we advise  anyone  to  study the  philosophy  of
    http://www.gnu.org/software/autoconf/GNU  autoconf,  from  which  we
    will illustrate some highlights below.

The  GNU autoconf  suite, known  to  most people  as configure,  was  an
answer to the frustrating life of Unix/C programmers  when Unix dialects
were  about as  abundant  and  poorly standardised  as  Prolog  dialects
today.   Writing a portable  C program can  only be achieved using  cpp,
the C  preprocessor.   The  C preprocessor  performs two  tasks:   macro
expansion and conditional compilation.  Prolog  realises macro expansion
through term_expansion/2 and goal_expansion/2.   Conditional compilation
is achieved  using :- if(Condition)  as explained  in section ????.    The
situation appears similar.

The important lesson learned  from GNU autoconf is that the  _l_a_s_t resort
for conditional compilation  to achieve portability is to switch  on the
platform or dialect.   Instead, GNU  autoconf allows you to write  tests
for specific  properties of  the platform.   Most  of these are  whether
or  not some  function  or file  is  available.    Then there  are  some
standard tests  for difficult-to-write-portable  situations and  finally
there  is a  framework that  allows you  to write  arbitrary C  programs
and check  whether they  can be  compiled and/or whether  they show  the
intended behaviour.   Using  a separate configure  program is needed  in
C, as  you cannot  perform C  compilation step  or run  C programs  from
the C  preprocessor.  In  most Prolog environments  we do not need  this
distinction as the  compiler is integrated into the runtime  environment
and Prolog has excellent reflexion capabilities.

We  must learn  from the  distinction to  test for  features instead  of
platform (dialect), as this makes the platform-specific  code robust for
future changes of the dialect.  Suppose we need  compare/3 as defined in
this manual.   The compare/3 predicate is not part of the  ISO standard,
but  many systems  support it  and it  is not  unlikely  it will  become
ISO standard  or the  intended dialect will  start supporting  it.   GNU
autoconf strongly advises to test for the availability:

________________________________________________________________________|                                                                        |
|:- if(\+current_predicate(_, compare(_,_,_))).                          |
|compare(<, Term1, Term2) :-                                             |

|        Term1 @< Term2, !.                                              |
|compare(>, Term1, Term2) :-                                             |
|        Term1 @> Term2, !.                                              |
|compare(=, Term1, Term2) :-                                             |
|        Term1 == Term2.                                                 |
|:-|endif.______________________________________________________________ |  |

This code is  mmuucchh more robust against  changes to the intended  dialect
and, possibly  at least  as important,  will provide compatibility  with
dialects you didn't even consider porting to right now.

In a  more challenging case,  the target Prolog  has compare/3, but  the
semantics  are different.    What to  do?    One option  is  to write  a
my_compare/3 and change all occurrences in the code.   Alternatively you
can rename  calls using  goal_expansion/2 like  below.   This  construct
will not  only deal with  Prolog dialects lacking  compare/3 as well  as
those that  only implement  it for  numeric comparison  or have  changed
the argument order.   Of course,  writing rock-solid code would  require
a  complete  test-suite,  but  this  example  will  probably  cover  all
Prolog dialects  that allow for conditional  compilation, have core  ISO
facilities and  provide goal_expansion/2, the things  we claim a  Prolog
dialect should have to start writing portable code for it.

________________________________________________________________________|                                                                        |

|:- if(\+catch(compare(<,a,b), _, fail)).                                |
|compare_standard_order(<, Term1, Term2) :-                              |
|        Term1 @< Term2, !.                                              |
|compare_standard_order(>, Term1, Term2) :-                              |
|        Term1 @> Term2, !.                                              |
|compare_standard_order(=, Term1, Term2) :-                              |
|        Term1 == Term2.                                                 |

|                                                                        |
|goal_expansion(compare(Order, Term1, Term2),                            |
|               compare_standard_order(Order, Term1, Term2)).            |
|:-|endif.______________________________________________________________ |  |


CChhaapptteerr 1166..  GGLLOOSSSSAARRYY OOFF TTEERRMMSS

aannoonnyymmoouuss [[vvaarriiaabbllee]]
    The  variable  _  is  called  the  _a_n_o_n_y_m_o_u_s  variable.     Multiple
    occurrences of _ in a single _t_e_r_m are not _s_h_a_r_e_d.

aarrgguummeennttss
    Arguments  are _t_e_r_m_s that appear in a _c_o_m_p_o_u_n_d _t_e_r_m.  _A_1  and _a_2 are
    the first and second argument of the term myterm(_A_1_, _a_2).

aarriittyy
    Argument count (= number of arguments) of a _c_o_m_p_o_u_n_d _t_e_r_m.

aasssseerrtt
    Add a _c_l_a_u_s_e to  a _p_r_e_d_i_c_a_t_e.  Clauses can be added at either end of
    the clause-list of a _p_r_e_d_i_c_a_t_e.  See asserta/1 and assertz/1.

aattoomm
    Textual  constant.   Used as name for  _c_o_m_p_o_u_n_d terms, to  represent
    constants or text.

bbaacckkttrraacckkiinngg
    Search  process used  by Prolog.    If a  predicate offers  multiple
    _c_l_a_u_s_e_s  to  solve  a _g_o_a_l,  they  are  tried one-by-one  until  one
    _s_u_c_c_e_e_d_s.    If  a subsequent  part of  the proof  is not  satisfied
    with  the resulting _v_a_r_i_a_b_l_e _b_i_n_d_i_n_g, it may ask for  an alternative
    _s_o_l_u_t_i_o_n (= _b_i_n_d_i_n_g  of the _v_a_r_i_a_b_l_e_s), causing Prolog to reject the
    previously chosen _c_l_a_u_s_e and try the next one.

bbiinnddiinngg [[ooff aa vvaarriiaabbllee]]
    Current value of the _v_a_r_i_a_b_l_e.  See also _b_a_c_k_t_r_a_c_k_i_n_g and _q_u_e_r_y.

bbuuiilltt--iinn [[pprreeddiiccaattee]]
    Predicate  that is part of the  Prolog system.  Built-in  predicates
    cannot  be redefined  by the  user, unless this  is overruled  using
    redefine_system_predicate/1.

bbooddyy
    Part of a _c_l_a_u_s_e behind the _n_e_c_k operator (:-).

cchhooiiccee ppooiinntt
    A  _c_h_o_i_c_e _p_o_i_n_t represents  a choice in  the search for a  _s_o_l_u_t_i_o_n.
    Choice  points are  created  if multiple  clauses match  a _q_u_e_r_y  or
    using  disjunction (;/2).   On _b_a_c_k_t_r_a_c_k_i_n_g, the execution state  of
    the  most recent _c_h_o_i_c_e _p_o_i_n_t is restored and search  continues with
    the next alternative (i.e., next clause or second branch of ;/2).

ccllaauussee
    `Sentence'  of a Prolog program.   A _c_l_a_u_s_e  consists of a _h_e_a_d  and
    _b_o_d_y  separated by  the _n_e_c_k operator  (:-) or it  is a _f_a_c_t.    For
    example:

    ____________________________________________________________________|                                                                    |
    | parent(X) :-                                                       |

    ||________father(X,__)._____________________________________________ ||

    Expressed  as ``X is a  parent if X is a  father of someone''.   See
    also _v_a_r_i_a_b_l_e and _p_r_e_d_i_c_a_t_e.

ccoommppiillee
    Process  where  a Prolog  _p_r_o_g_r_a_m  is translated  to a  sequence  of
    instructions.   See  also _i_n_t_e_r_p_r_e_t_e_d.   SWI-Prolog always  compiles
    your program before executing it.

ccoommppoouunndd [[tteerrmm]]
    Also  called  _s_t_r_u_c_t_u_r_e.    It  consists of  a  name followed  by  _N
    _a_r_g_u_m_e_n_t_s,  each of which are _t_e_r_m_s.   _N is called the _a_r_i_t_y  of the
    term.

ccoonntteexxtt mmoodduullee
    If  a _t_e_r_m  is referring  to a _p_r_e_d_i_c_a_t_e  in a  _m_o_d_u_l_e, the  _c_o_n_t_e_x_t
    _m_o_d_u_l_e  is used to find the target module.  The context  module of a
    _g_o_a_l  is the module in which  the _p_r_e_d_i_c_a_t_e is defined, unless  this
    _p_r_e_d_i_c_a_t_e  is _m_o_d_u_l_e _t_r_a_n_s_p_a_r_e_n_t, in  which case the _c_o_n_t_e_x_t  _m_o_d_u_l_e
    is  inherited from the parent  _g_o_a_l.  See  also module_transparent/1
    and _m_e_t_a_-_p_r_e_d_i_c_a_t_e.

ddccgg
    Abbreviation for _D_e_f_i_n_i_t_e _C_l_a_u_s_e _G_r_a_m_m_a_r.

ddeett [[ddeetteerrmmiinniissmm]]
    Short for _d_e_t_e_r_m_i_n_i_s_t_i_c.

ddeetteerrmmiinniissmm
    How  many solutions a _g_o_a_l can  provide.  Values are `nondet'  (zero
    to  infinite), `multi'  (one to infinite),  `det' (exactly one)  and
    `semidet' (zero or one).

ddeetteerrmmiinniissttiicc
    A  _p_r_e_d_i_c_a_t_e  is  _d_e_t_e_r_m_i_n_i_s_t_i_c  if it  succeeds  exactly  one  time
    without leaving a _c_h_o_i_c_e _p_o_i_n_t.

ddyynnaammiicc [[pprreeddiiccaattee]]
    A _d_y_n_a_m_i_c predicate  is a predicate to which _c_l_a_u_s_e_s may be _a_s_s_e_r_ted
    and  from  which  _c_l_a_u_s_e_s may  be  _r_e_t_r_a_c_ted  while the  program  is
    running.  See also _u_p_d_a_t_e _v_i_e_w.

eexxppoorrtteedd [[pprreeddiiccaattee]]
    A  _p_r_e_d_i_c_a_t_e is  said to  be _e_x_p_o_r_t_e_d from  a _m_o_d_u_l_e  if it  appears
    in  the  _p_u_b_l_i_c _l_i_s_t.     This implies  that  the predicate  can  be
    _i_m_p_o_r_t_e_d  into another module  to make it visible  there.  See  also
    use_module/[1,2].

ffaacctt
    _C_l_a_u_s_e  without a _b_o_d_y.  This is called a fact  because, interpreted
    as logic, there is  no condition to be satisfied.  The example below
    states john is a person.

    ____________________________________________________________________|                                                                    |
    ||person(john)._____________________________________________________ ||

ffaaiill
    A _g_o_a_l is said to haved failed if it could not be _p_r_o_v_e_n.

ffllooaatt
    Computer's  crippled representation of a  real number.   Represented
    as `IEEE double'.

ffoorreeiiggnn
    Computer code expressed  in languages other than Prolog.  SWI-Prolog
    can only cooperate directly with the C and C++ computer languages.

ffuunnccttoorr
    Combination  of name and _a_r_i_t_y of a _c_o_m_p_o_u_n_d term.  The  term foo(_a_,
    _b_,  _c) is said to be a  term belonging to the functor foo/3.   foo/0
    is used to refer to the _a_t_o_m foo.

ggooaall
    Question  stated to the  Prolog engine.   A _g_o_a_l  is either an  _a_t_o_m
    or  a _c_o_m_p_o_u_n_d  term.   A _g_o_a_l  either succeeds, in  which case  the
    _v_a_r_i_a_b_l_e_s  in the  _c_o_m_p_o_u_n_d terms  have a  _b_i_n_d_i_n_g, or  it _f_a_i_l_s  if
    Prolog fails to prove it.

hhaasshhiinngg
    _I_n_d_e_x_i_n_g technique used for quick lookup.

hheeaadd
    Part of a _c_l_a_u_s_e before the  _n_e_c_k operator (:-).  This is an _a_t_o_m or
    _c_o_m_p_o_u_n_d term.

iimmppoorrtteedd [[pprreeddiiccaattee]]
    A  _p_r_e_d_i_c_a_t_e is said to be _i_m_p_o_r_t_e_d  into a _m_o_d_u_l_e if it  is defined
    in  another _m_o_d_u_l_e  and made  available in this  _m_o_d_u_l_e.   See  also
    chapter ????.

iinnddeexxiinngg
    Indexing is a  technique used to quickly select candidate _c_l_a_u_s_e_s of
    a  _p_r_e_d_i_c_a_t_e for a specific _g_o_a_l.  In most Prolog  systems, indexing
    is done (only) on  the first _a_r_g_u_m_e_n_t of the _h_e_a_d.  If this argument
    is  instantiated to an  _a_t_o_m, _i_n_t_e_g_e_r, _f_l_o_a_t  or _c_o_m_p_o_u_n_d term  with
    _f_u_n_c_t_o_r,  _h_a_s_h_i_n_g is used  to quickly select  all _c_l_a_u_s_e_s where  the
    first  argument  may _u_n_i_f_y  with  the first  argument of  the  _g_o_a_l.
    SWI-Prolog  supports just-in-time and multi-argument indexing.   See
    section ????.

iinntteeggeerr
    Whole number.   On all implementations of SWI-Prolog integers are at
    least  64-bit signed values.   When linked  to the GNU GMP  library,
    integer  arithmetic is unbounded.    See also current_prolog_flag/2,
    flags bounded, max_integer and min_integer.

iinntteerrpprreetteedd
    As  opposed  to  _c_o_m_p_i_l_e_d,   interpreted  means  the  Prolog  system
    attempts  to prove  a _g_o_a_l  by directly reading  the _c_l_a_u_s_e_s  rather
    than executing instructions  from an (abstract) instruction set that
    is not or only indirectly related to Prolog.

iinnssttaannttiiaattiioonn [[ooff aann aarrgguummeenntt]]
    To  what  extend  a term  is  bound to  a  value.    Typical  levels
    are  `unbound' (a  _v_a_r_i_a_b_l_e), `ground'  (term without variables)  or
    `partially bound' (term with embedded variables).

mmeettaa--pprreeddiiccaattee
    A  _p_r_e_d_i_c_a_t_e that reasons about other _p_r_e_d_i_c_a_t_e_s, either  by calling
    them, (re)defining them or querying _p_r_o_p_e_r_t_i_e_s.

mmooddee [[ddeeccllaarraattiioonn]]
    Declaration  of an argument  _i_n_s_t_a_n_t_i_a_t_i_o_n pattern for a  _p_r_e_d_i_c_a_t_e,
    often accompanied with a _d_e_t_e_r_m_i_n_i_s_m.

mmoodduullee
    Collection  of predicates.    Each module defines  a name-space  for
    predicates.   _b_u_i_l_t_-_i_n predicates  are accessible from all  modules.
    Predicates  can be published (_e_x_p_o_r_t_e_d)  and _i_m_p_o_r_t_e_d to make  their
    definition available to other modules.

mmoodduullee ttrraannssppaarreenntt [[pprreeddiiccaattee]]
    A  _p_r_e_d_i_c_a_t_e that  does not change  the _c_o_n_t_e_x_t  _m_o_d_u_l_e.   Sometimes
    also called a _m_e_t_a_-_p_r_e_d_i_c_a_t_e.

mmuullttii [[ddeetteerrmmiinniissmm]]
    A  _p_r_e_d_i_c_a_t_e is said  to have _d_e_t_e_r_m_i_n_i_s_m  multi if it generates  at
    _l_e_a_s_t one answer.

mmuullttiiffiillee [[pprreeddiiccaattee]]
    Predicate  for which  the  definition is  distributed over  multiple
    source files.  See multifile/1.

nneecckk
    Operator (:-) separating _h_e_a_d from _b_o_d_y in a _c_l_a_u_s_e.

nnoonnddeett
    Short for _n_o_n _d_e_t_e_r_m_i_n_i_s_t_i_c.

nnoonn ddeetteerrmmiinniissttiicc
    A  _n_o_n _d_e_t_e_r_m_i_n_i_s_t_i_c  predicate  is a  predicate that  mail fail  or
    succeed any number of times.

ooppeerraattoorr
    Symbol (_a_t_o_m) that  may be placed before its _o_p_e_r_a_n_d (prefix), after
    its _o_p_e_r_a_n_d (postfix) or between its two _o_p_e_r_a_n_d_s (infix).

    In  Prolog, the expression a+b is exactly the same as  the canonical
    term +(a,b).

ooppeerraanndd
    _A_r_g_u_m_e_n_t of an _o_p_e_r_a_t_o_r.

pprreecceeddeennccee
    The  _p_r_i_o_r_i_t_y  of an  _o_p_e_r_a_t_o_r.    Operator  precedence is  used  to
    interpret a+b*c as +(a, *(b,c)).

pprreeddiiccaattee
    Collection  of _c_l_a_u_s_e_s  with the same  _f_u_n_c_t_o_r (name/_a_r_i_t_y).   If  a
    _g_o_a_l  is proved,  the system  looks for  a _p_r_e_d_i_c_a_t_e  with the  same
    functor,  then uses  _i_n_d_e_x_i_n_g to select  candidate _c_l_a_u_s_e_s and  then
    tries these _c_l_a_u_s_e_s one-by-one.  See also _b_a_c_k_t_r_a_c_k_i_n_g.

pprreeddiiccaattee iinnddiiccaattoorr
    Term  of the form Name/Arity  (traditional) or Name//Arity (ISO  DCG
    proposal),  where Name is an atom and Arity a  non-negative integer.
    It acts as an _i_n_d_i_c_a_t_o_r (or reference) to a predicate or _D_C_G rule.

pprriioorriittyy
    In the context of _o_p_e_r_a_t_o_r_s a synonym for _p_r_e_c_e_d_e_n_c_e.

pprrooggrraamm
    Collection of _p_r_e_d_i_c_a_t_e_s.

pprrooppeerrttyy
    Attribute  of  an object.    SWI-Prolog  defines  various _*___p_r_o_p_e_r_t_y
    predicates to query the status of predicates, clauses.  etc.

pprroovvee
    Process  where Prolog attempts to prove a _q_u_e_r_y using  the available
    _p_r_e_d_i_c_a_t_e_s.

ppuubblliicc lliisstt
    List of _p_r_e_d_i_c_a_t_e_s exported from a _m_o_d_u_l_e.

qquueerryy
    See _g_o_a_l.

rreettrraacctt
    Remove  a _c_l_a_u_s_e from a  _p_r_e_d_i_c_a_t_e.   See also _d_y_n_a_m_i_c, _u_p_d_a_t_e  _v_i_e_w
    and _a_s_s_e_r_t.

sseemmiiddeett
    Shorthand for

sseemmii ddeetteerrmmiinniissttiicc
    .

sseemmii ddeetteerrmmiinniissttiicc
    A  _p_r_e_d_i_c_a_t_e that  is _s_e_m_i  _d_e_t_e_r_m_i_n_i_s_t_i_c either  fails or  succeeds
    exactly once without a _c_h_o_i_c_e _p_o_i_n_t.  See also _d_e_t_e_r_m_i_n_i_s_t_i_c.

sshhaarreedd
    Two  _v_a_r_i_a_b_l_e_s  are called  _s_h_a_r_e_d after  they are  _u_n_i_f_i_e_d.    This
    implies  if either of them is _b_o_u_n_d, the other is bound to  the same
    value:

    ____________________________________________________________________|                                                                    |
    | ?- A = B, A = a.                                                   |
    ||A_=_B,_B_=_a._____________________________________________________ ||

ssiinngglleettoonn [[vvaarriiaabbllee]]
    _V_a_r_i_a_b_l_e  appearing only one time in a _c_l_a_u_s_e.   SWI-Prolog normally
    warns  for  this to  avoid  you  making spelling  mistakes.    If  a
    variable  appears on  purpose only  once in  a clause,  write it  as
    _  (see _a_n_o_n_y_m_o_u_s).    Rules for naming  a variable  and avoiding  a
    warning are given in section ????.

ssoolluuttiioonn
    _B_i_n_d_i_n_g_s resulting from a successfully _p_r_o_v_en _g_o_a_l.

ssttrruuccttuurree
    Synonym for _c_o_m_p_o_u_n_d term.

ssttrriinngg
    Used  for the  following representations  of text:   a packed  array
    (see section ????,  SWI-Prolog specific), a list of character codes or
    a list of one-character _a_t_o_m_s.

ssuucccceeeedd
    A _g_o_a_l is said to have _s_u_c_c_e_e_d_e_d if it has been _p_r_o_v_e_n.

tteerrmm
    Value in Prolog.   A _t_e_r_m is either a _v_a_r_i_a_b_l_e, _a_t_o_m, _i_n_t_e_g_e_r, _f_l_o_a_t
    or  _c_o_m_p_o_u_n_d term.   In addition,  SWI-Prolog also defines the  type
    _s_t_r_i_n_g.

ttrraannssppaarreenntt
    See _m_o_d_u_l_e _t_r_a_n_s_p_a_r_e_n_t.

uunniiffyy
    Prolog  process to make  two terms equal  by assigning variables  in
    one term to  values at the corresponding location of the other term.
    For example:

    ____________________________________________________________________|                                                                    |

    | ?- foo(a, B) = foo(A, b).                                          |
    | A = a,                                                             |
    ||B_=_b.____________________________________________________________ ||

    Unlike  assignment (which does not exist in Prolog),  unification is
    not directed.

uuppddaattee vviieeww
    How  Prolog behaves when a _d_y_n_a_m_i_c _p_r_e_d_i_c_a_t_e is changed while  it is
    running.   There are two models.   In most older Prolog  systems the
    change  becomes immediately visible to  the _g_o_a_l, in modern  systems
    including  SWI-Prolog, the running _g_o_a_l is  not affected.  Only  new
    _g_o_a_l_s `see' the new definition.

vvaarriiaabbllee
    A  Prolog  variable is  a value  that `is  not yet  bound'.    After
    _b_i_n_d_i_n_g a variable, it  cannot be modified.  _B_a_c_k_t_r_a_c_k_i_n_g to a point
    in  the execution before  the variable was  bound will turn it  back
    into a variable:

    ____________________________________________________________________|                                                                    |
    | ?- A = b, A = c.                                                   |
    | false.                                                             |
    |                                                                    |
    | ?- (A = b; true; A = c).                                           |

    | A = b ;                                                            |
    | true ;                                                             |
    ||A_=_c_.___________________________________________________________ ||

    See also _u_n_i_f_y.


CChhaapptteerr 1177..  SSWWII--PPRROOLLOOGG LLIICCEENNSSEE CCOONNDDIITTIIOONNSS AANNDD TTOOOOLLSS

As of  version 7.4.0,  the SWI-Prolog source  code is distributed  under
the https://opensource.org/licenses/BSD-2-ClauseSimplified BSD license:

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in
       the documentation and/or other materials provided with the
       distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.

This, unfortunately,  ddooeess nnoott  mmeeaann yyoouu ccaann  aannyy vveerrssiioonn ooff  SSWWII--PPrroolloogg
uunnddeerr  tthhee  aabboovvee lliicceennssee.     The  SWI-Prolog core  may  be  linked  to
libraries that are more  restrictive and in addition your code  may have
loaded extension  packages that have  more restrictive  conditions.   In
particular, the core is by default  linked to https://gmplib.org/libgmp,
distributed under the Lesser GNU Public license.

The  above  implies you  need  to  configure and  recompile  the  system
without these components.  For this we provide  options to the configure
script:

________________________________________________________________________|                                                                        |

|./configure --without-gpl                                               |
|./configure|--without-lgpl_____________________________________________ |           |

The  GNU  MP  Bignum  Library  provides  unbounded  integers,   rational
numbers and some  cryptographical functionality.  As libgmp  is provided
under the  Lesser GNU  Public license  it may legally  be combined  with
proprietary software as  long as libgmp is _d_y_n_a_m_i_c_a_l_l_y _l_i_n_k_e_d  (default)
and the  end user  can replace  the libgmp  shared object  and use  your
application  with their  (possibly  modified) version  of  libgmp.    In
practice this  leads to problems  if the  application is not  accessible
(e.g., embedded  in closed hardware) or you  want to avoid customers  to
peek around in the process  memory as they can easily do so by  adding a
backdoor to the  modified LGPL component.   Note that such a  protection
is  in general  not possible  anyway if  the  customer has  unrestricted
access to the machine on which the application runs.


1177..11 CCoonnttrriibbuuttiinngg ttoo tthhee SSWWII--PPrroolloogg pprroojjeecctt

To reach  maximal coherence we  will, as  a rule of  thumb, only  accept
new code that  has the Simplified BSD  license and existing code with  a
_p_e_r_m_i_s_s_i_v_e license  such as  MIT, Apache,  BSD-3, etc.   In  exceptional
cases  we may  accept code  with  GPL or  LGPL conditions.    Such  code
must  be tagged  using  a license/1  directive  (Prolog)  or a  call  to
PL_license() for foreign  code and, if  they are part  of the core,  the
code must be excluded using the --without-gpl or --without-lgpl option.


1177..22 SSooffttwwaarree ssuuppppoorrtt ttoo kkeeeepp ttrraacckk ooff lliicceennssee ccoonnddiittiioonnss

Given the above, it is possible that SWI-Prolog  packages and extensions
rely  on  the GPL,  LGPL  or  other  licenses.    The  predicates  below
allow for registering license requirements for Prolog  files and foreign
modules.   The  predicate license/0  reports which  components from  the
currently configured  system are  distributed under non-permissive  open
source  licenses and  therefore may  need to  be replaced  to suit  your
requirements.


lliicceennssee
    Evaluate  the license conditions of all  loaded components.  If  the
    system  contains  one or  more components  that  are licenced  under
    GPL-like  restrictions the  system indicates this  program may  only
    be  distributed under the  GPL license as  well as which  components
    prohibit  the use  of other license  conditions.   Likewise for  for
    LGPL components.


lliicceennssee((_+_L_i_c_e_n_s_e_I_d_, _+_C_o_m_p_o_n_e_n_t))
    Register  the fact  that _C_o_m_p_o_n_e_n_t  is distributed  under a  license
    identified  by _L_i_c_e_n_s_e_I_d.   Known license identifiers can be  listed
    using known_licenses/0.  A new license can  be registered as a known
    language  using  a declaration  like  below.   The  second  argument
    defines  the _c_a_t_e_g_o_r_y  if the license,  which is one  of gpl,  lgpl,
    permissive or proprietary.

    ____________________________________________________________________|                                                                    |
    | :- multifile license:license/3.                                    |

    |                                                                    |
    | license:license(mylicense, permissive,                             |
    |                 [ comment('My personal license'),                  |
    |                   url('http://www.mine.org/license.html')          |
    |                 ]).                                                |
    |                                                                    |
    ||:-_license(mylicense).____________________________________________ ||


lliicceennssee((_+_L_i_c_e_n_s_e_I_d))
    Intended  as a  directive  in Prolog  source files.    It takes  the
    current filename and calls license/2.


void PPLL__lliicceennssee(_c_o_n_s_t _c_h_a_r _*_L_i_c_e_n_s_e_I_d_, _c_o_n_s_t _c_h_a_r _*_C_o_m_p_o_n_e_n_t)
    Intended  for the install()  procedure of foreign  libraries.   This
    call can be made _b_e_f_o_r_e PL_initialise().


kknnoowwnn__lliicceennsseess
    List  all  licenses _k_n_o_w_n  to  the  system.    This does  not  imply
    the  system  contains code  covered by  the listed  licenses.    See
    license/2.


1177..33 LLiicceennssee ccoonnddiittiioonnss iinnhheerriitteedd ffrroomm uusseedd ccooddee


1177..33..11 CCrryyppttooggrraapphhiicc rroouuttiinneess

Cryptographic routines  are used  in variant_sha1/2  and crypt.    These
routines are provided under the following conditions:

Copyright (c) 2002, Dr Brian Gladman, Worcester, UK.   All rights reserved.

LICENSE TERMS

The free distribution and use of this software in both source and binary
form is allowed (with or without changes) provided that:

   1. distributions of this source code include the above copyright
      notice, this list of conditions and the following disclaimer;

   2. distributions in binary form include the above copyright
      notice, this list of conditions and the following disclaimer
      in the documentation and/or other associated materials;

   3. the copyright holder's name is not used to endorse products
      built using this software without specific written permission.

ALTERNATIVELY, provided that this notice is retained in full, this product
may be distributed under the terms of the GNU General Public License (GPL),
in which case the provisions of the GPL apply INSTEAD OF those given above.

DISCLAIMER

This software is provided 'as is' with no explicit or implied warranties
in respect of its properties, including, but not limited to, correctness
and/or fitness for purpose.


CChhaapptteerr 1188..  SSUUMMMMAARRYY


1188..11 PPrreeddiiccaatteess

The  predicate summary  is used  by the  Prolog  predicate apropos/1  to
suggest predicates from a keyword.

 @/2    Call using calling context
 !/0    Cut (discard choicepoints)
 ,/2    Conjunction of goals
 ->/2   If-then-else
 *->/2  Soft-cut
 ./2    Consult.  Also functional notation
 :</2   Select keys from a dict
 ;/2    Disjunction of two goals

 </2    Arithmetic smaller
 =/2    True when arguments are unified
 =../2  ``Univ.''  Term to list conversion
 =:=/2  Arithmetic equality
 =</2   Arithmetic smaller or equal
 ==/2   Test for strict equality
 =@=/2  Test for structural equality (variant)

 =\=/2  Arithmetic not equal
 >/2    Arithmetic larger
 >=/2   Arithmetic larger or equal
 >:</2  Partial dict unification
 ?=/2   Test of terms can be compared now
 @</2                     Standard order smaller
 @=</2                    Standard order smaller or equal
 @>/2                     Standard order larger

 @>=/2                    Standard order larger or equal
 \+/1                     Negation by failure.  Same as not/1
 \=/2                     True if arguments cannot be unified
 \==/2                    True if arguments are not strictly equal
 \=@=/2                   Not structural identical
 ^/2                      Existential quantification (bagof/3, setof/3)
 |/2                      Disjunction in DCGs.  Same as ;/2

 {}/1                     DCG escape; constraints
 abolish/1                Remove predicate definition from the database
 abolish/2                Remove predicate definition from the database
 abolish_all_tables/0     Abolish computed tables
 abolish_table_subgoals/1 Abolish tables for a goal
 abort/0                  Abort execution, return to top level
 absolute_file_name/2     Get absolute path name
 absolute_file_name/3     Get absolute path name with options

 access_file/2            Check access permissions of a file
 acyclic_term/1           Test term for cycles
 add_import_module/3      Add module to the auto-import list
 add_nb_set/2             Add term to a non-backtrackable set
 add_nb_set/3             Add term to a non-backtrackable set
 append/1                 Append to a file
 apply/2                  Call goal with additional arguments

 apropos/1                online_help Search manual
 arg/3                    Access argument of a term
 assoc_to_list/2          Convert association tree to list
 assert/1                 Add a clause to the database
 assert/2                 Add a clause to the database, give reference
 asserta/1                Add a clause to the database (first)
 asserta/2                Add a clause to the database (first)
 assertion/1              Make assertions about your program

 assertz/1                Add a clause to the database (last)
 assertz/2                Add a clause to the database (last)
 attach_console/0         Attach I/O console to thread
 attach_packs/0           Attach add-ons
 attach_packs/1           Attach add-ons from directory
 attach_packs/2           Attach add-ons from directory
 attribute_goals/3        Project attributes to goals

 attr_unify_hook/2        Attributed variable unification hook
 attr_portray_hook/2      Attributed variable print hook
 attvar/1                 Type test for attributed variable
 at_end_of_stream/0       Test for end of file on input
 at_end_of_stream/1       Test for end of file on stream
 at_halt/1                Register goal to run at halt/1
 atom/1                   Type check for an atom
 atom_chars/2             Convert between atom and list of characters

 atom_codes/2             Convert between atom and list of characters codes
 atom_concat/3            Contatenate two atoms
 atom_length/2            Determine length of an atom
 atom_number/2            Convert between atom and number
 atom_prefix/2            Test for start of atom
 atom_string/2            Conversion between atom and string
 atom_to_term/3           Convert between atom and term

 atomic/1                 Type check for primitive
 atomic_concat/3          Concatenate two atomic values to an atom
 atomic_list_concat/2     Append a list of atomics
 atomic_list_concat/3     Append a list of atomics with separator
 atomics_to_string/2      Concatenate list of inputs to a string
 atomics_to_string/3          Concatenate list of inputs to a string
 autoload/0                   Autoload all predicates now
 autoload_path/1              Add directories for autoloading

 b_getval/2                   Fetch backtrackable global variable
 b_set_dict/3                 Destructive assignment on a dict
 b_setval/2                   Assign backtrackable global variable
 bagof/3                      Find all solutions to a goal
 between/3                    Integer range checking/generating
 blob/2                       Type check for a blob
 break/0                      Start interactive top level

 break_hook/6                 (hook) Debugger hook
 byte_count/2                 Byte-position in a stream
 call/1                       Call a goal
 call/[2..]                   Call with additional arguments
 call_cleanup/3               Guard a goal with a cleaup-handler
 call_cleanup/2               Guard a goal with a cleaup-handler
 call_dcg/3                   As phrase/3 without type checking
 call_residue_vars/2          Find residual attributed variables

 call_shared_object_function/2UNIX: Call C-function in shared (.so) file
 call_with_depth_limit/3      Prove goal with bounded depth
 call_with_inference_limit/3  Prove goal in limited inferences
 callable/1                   Test for atom or compound term
 cancel_halt/1                Cancel halt/0 from an at_halt/1 hook
 catch/3                      Call goal, watching for exceptions
 char_code/2                  Convert between character and character code

 char_conversion/2            Provide mapping of input characters
 char_type/2                  Classify characters
 character_count/2            Get character index on a stream
 chdir/1                      Compatibility:  change working directory
 chr_constraint/1             CHR Constraint declaration
 chr_show_store/1             List suspended CHR constraints
 chr_trace/0                  Start CHR tracer
 chr_type/1                   CHR Type declaration

 chr_notrace/0                Stop CHR tracer
 chr_leash/1                  Define CHR leashed ports
 chr_option/2                 Specify CHR compilation options
 clause/2                     Get clauses of a predicate
 clause/3                     Get clauses of a predicate
 clause_property/2            Get properties of a clause
 close/1                      Close stream

 close/2                      Close stream (forced)
 close_dde_conversation/1     Win32:  Close DDE channel
 close_shared_object/1        UNIX: Close shared library (.so file)
 collation_key/2              Sort key for locale dependent ordering
 comment_hook/3               (hook) handle comments in sources
 compare/3                    Compare, using a predicate to determine the order
 compile_aux_clauses/1        Compile predicates for goal_expansion/2
 compile_predicates/1         Compile dynamic code to static

 compiling/0                  Is this a compilation run?
 compound/1                   Test for compound term
 compound_name_arity/3        Name and arity of a compound term
 compound_name_arguments/3    Name and arguments of a compound term
 code_type/2                  Classify a character-code
 consult/1                    Read (compile) a Prolog source file
 context_module/1             Get context module of current goal

 convert_time/8               Break time stamp into fields
 convert_time/2               Convert time stamp to string
 copy_stream_data/2           Copy all data from stream to stream
 copy_stream_data/3           Copy n bytes from stream to stream
 copy_predicate_clauses/2     Copy clauses between predicates
 copy_term/2                   Make a copy of a term
 copy_term/3                   Copy a term and obtain attribute-goals
 copy_term_nat/2               Make a copy of a term without attributes

 create_prolog_flag/3          Create a new Prolog flag
 current_arithmetic_function/1 Examine evaluable functions
 current_atom/1                Examine existing atoms
 current_blob/2                Examine typed blobs
 current_char_conversion/2     Query input character mapping
 current_engine/1              Enumerate known engines
 current_flag/1                Examine existing flags

 current_foreign_library/2     shlib Examine loaded shared libraries (.so files)
 current_format_predicate/2    Enumerate user-defined format codes
 current_functor/2             Examine existing name/arity pairs
 current_input/1               Get current input stream
 current_key/1                 Examine existing database keys
 current_locale/1              Get the current locale
 current_module/1              Examine existing modules
 current_op/3                  Examine current operator declarations

 current_output/1              Get the current output stream
 current_predicate/1           Examine existing predicates (ISO)
 current_predicate/2           Examine existing predicates
 current_signal/3              Current software signal mapping
 current_stream/3              Examine open streams
 current_trie/1                Enumerate known tries
 cyclic_term/1                 Test term for cycles

 day_of_the_week/2             Determine ordinal-day from date
 date_time_stamp/2             Convert date structure to time-stamp
 date_time_value/3             Extract info from a date structure
 dcg_translate_rule/2          Source translation of DCG rules
 dcg_translate_rule/4          Source translation of DCG rules
 dde_current_connection/2      Win32:  Examine open DDE connections
 dde_current_service/2         Win32:  Examine DDE services provided
 dde_execute/2                 Win32:  Execute command on DDE server

 dde_register_service/2        Win32:  Become a DDE server
 dde_request/3                 Win32:  Make a DDE request
 dde_poke/3                    Win32:  POKE operation on DDE server
 dde_unregister_service/1      Win32:  Terminate a DDE service
 debug/0                       Test for debugging mode
 debug/1                       Select topic for debugging
 debug/3                       Print debugging message on topic

 debug_control_hook/1          (hook) Extend spy/1, etc.
 debugging/0                   Show debugger status
 debugging/1                   Test where we are debugging topic
 default_module/2              Query module inheritance
 del_attr/2                    Delete attribute from variable
 del_attrs/1                   Delete all attributes from variable
 del_dict/4                    Delete Key-Value pair from a dict
 delete_directory/1            Remove a folder from the file system

 delete_file/1                 Remove a file from the file system
 delete_import_module/2        Remove module from import list
 deterministic/1               Test deterministicy of current clause
 dif/2                         Constrain two terms to be different
 directory_files/2             Get entries of a directory/folder
 discontiguous/1               Indicate distributed definition of a predicate
 divmod/4                      Compute quotient and remainder of two integers

 downcase_atom/2               Convert atom to lower-case
 duplicate_term/2              Create a copy of a term
 dwim_match/2                  Atoms match in ``Do What I Mean'' sense
 dwim_match/3                  Atoms match in ``Do What I Mean'' sense
 dwim_predicate/2              Find predicate in ``Do What I Mean'' sense
 dynamic/1                     Indicate predicate definition may change
 edit/0                        Edit current script- or associated file
 edit/1                        Edit a file, predicate, module (extensible)

 elif/1                        Part of conditional compilation (directive)
 else/0                        Part of conditional compilation (directive)
 empty_assoc/1                 Create/test empty association tree
 empty_nb_set/1                Test/create an empty non-backtrackable set
 encoding/1                    Define encoding inside a source file
 endif/0                       End of conditional compilation (directive)
 engine_create/3               Create an interactor

 engine_create/4               Create an interactor
 engine_destroy/1              Destroy an interactor
 engine_fetch/1                Get term from caller
 engine_next/2                 Ask interactor for next term
 engine_next_reified/2         Ask interactor for next term
 engine_post/2                 Send term to an interactor
 engine_post/3                 Send term to an interactor and wait for reply
 engine_self/1                 Get handle to running interactor

 engine_yield/1                Make term available to caller
 ensure_loaded/1               Consult a file if that has not yet been done
 erase/1                       Erase a database record or clause
 exception/3                   (hook) Handle runtime exceptions
 exists_directory/1            Check existence of directory
 exists_file/1                 Check existence of file
 exists_source/1               Check existence of a Prolog source

 expand_answer/2               Expand answer of query
 expand_file_name/2            Wildcard expansion of file names
 expand_file_search_path/2     Wildcard expansion of file paths
 expand_goal/2                 Compiler:  expand goal in clause-body
 expand_goal/4                 Compiler:  expand goal in clause-body
 expand_query/4                Expanded entered query
 expand_term/2                 Compiler:  expand read term into clause(s)
 expand_term/4                 Compiler:  expand read term into clause(s)

 expects_dialect/1             For which Prolog dialect is this code written?
 explain/1                     explain Explain argument
 explain/2                     explain 2nd argument is explanation of first
 export/1                      Export a predicate from a module
 fail/0                        Always false
 false/0                       Always false
 fast_term_serialized/2        Fast term (de-)serialization

 fast_read/2                   Read binary term serialization
 fast_write/2                  Write binary term serialization
 current_prolog_flag/2         Get system configuration parameters
 file_base_name/2              Get file part of path
 file_directory_name/2         Get directory part of path
 file_name_extension/3         Add, remove or test file extensions
 file_search_path/2            Define path-aliases for locating files
 find_chr_constraint/1         Returns a constraint from the store

 findall/3                     Find all solutions to a goal
 findall/4                     Difference list version of findall/3
 findnsols/4                   Find first _N solutions
 findnsols/5                   Difference list version of findnsols/4
 fill_buffer/1                 Fill the input buffer of a stream
 flag/3                        Simple global variable system
 float/1                       Type check for a floating point number

 flush_output/0                Output pending characters on current stream
 flush_output/1                Output pending characters on specified stream
 forall/2                      Prove goal for all solutions of another goal
 format/1                      Formatted output
 format/2                      Formatted output with arguments
 format/3                      Formatted output on a stream
 format_time/3                 C strftime() like date/time formatter
 format_time/4                 date/time formatter with explicit locale

 format_predicate/2            Program format/[1,2]
 term_attvars/2                Find attributed variables in a term
 term_variables/2              Find unbound variables in a term
 term_variables/3              Find unbound variables in a term
 text_to_string/2              Convert arbitrary text to a string
 freeze/2                      Delay execution until variable is bound
 frozen/2                      Query delayed goals on var

 functor/3                     Get name and arity of a term or construct a term
 garbage_collect/0             Invoke the garbage collector
 garbage_collect_atoms/0       Invoke the atom garbage collector
 garbage_collect_clauses/0     Invoke clause garbage collector
 gen_assoc/3                   Enumerate members of association tree
 gen_nb_set/2                  Generate members of non-backtrackable set
 gensym/2                      Generate unique atoms from a base
 get/1                         Read first non-blank character

 get/2                         Read first non-blank character from a stream
 get_assoc/3                   Fetch key from association tree
 get_assoc/5                   Fetch key from association tree
 get_attr/3                    Fetch named attribute from a variable
 get_attrs/2                   Fetch all attributes of a variable
 get_byte/1                    Read next byte (ISO)
 get_byte/2                    Read next byte from a stream (ISO)

 get_char/1                    Read next character as an atom (ISO)
 get_char/2                    Read next character from a stream (ISO)
 get_code/1                    Read next character (ISO)
 get_code/2                    Read next character from a stream (ISO)
 get_dict/3                    Get the value associated to a key from a dict
 get_dict/5                    Replace existing value in a dict
 get_flag/2                    Get value of a flag
 get_single_char/1             Read next character from the terminal

 get_string_code/3             Get character code at index in string
 get_time/1                    Get current time
 get0/1                        Read next character
 get0/2                        Read next character from a stream
 getenv/2                      Get shell environment variable
 goal_expansion/2              Hook for macro-expanding goals
 goal_expansion/4              Hook for macro-expanding goals

 ground/1                      Verify term holds no unbound variables
 gdebug/0                      Debug using graphical tracer
 gspy/1                        Spy using graphical tracer
 gtrace/0                      Trace using graphical tracer
 guitracer/0                   Install hooks for the graphical debugger
 gxref/0                       Cross-reference loaded program
 halt/0                        Exit from Prolog
 halt/1                        Exit from Prolog with status

 term_hash/2                   Hash-value of ground term
 term_hash/4                   Hash-value of term with depth limit
 help/0                        Give help on help
 help/1                        Give help on predicates and show parts of manual
 help_hook/1                   (hook) User-hook in the help-system
 if/1                          Start conditional compilation (directive)
 ignore/1                      Call the argument, but always succeed

 import/1                      Import a predicate from a module
 import_module/2               Query import modules
 in_pce_thread/1               Run goal in XPCE thread
 in_pce_thread_sync/1          Run goal in XPCE thread
 include/1                     Include a file with declarations
 initialization/1              Initialization directive
 initialization/2              Initialization directive
 initialize/0                  Run program initialization

 instance/2                    Fetch clause or record from reference
 integer/1                     Type check for integer
 interactor/0                  Start new thread with console and top level
 is/2                          Evaluate arithmetic expression
 is_absolute_file_name/1       True if arg defines an absolute path
 is_assoc/1                    Verify association list
 is_engine/1                   Type check for an engine handle

 is_list/1                     Type check for a list
 is_dict/1                     Type check for a dict
 is_dict/2                     Type check for a dict in a class
 is_stream/1                   Type check for a stream handle
 is_trie/1                     Type check for a trie handle
 is_thread/1                   Type check for an thread handle
 join_threads/0                Join all terminated threads interactively
 keysort/2                     Sort, using a key

 known_licenses/0              Print known licenses
 last/2                        Last element of a list
 leash/1                       Change ports visited by the tracer
 length/2                      Length of a list
 library_directory/1           (hook) Directories holding Prolog libraries
 license/0                     Evaluate licenses of loaded modules
 license/1                     Define license for current file

 license/2                     Define license for named module
 line_count/2                  Line number on stream
 line_position/2               Character position in line on stream
 list_debug_topics/0           List registered topics for debugging
 list_to_assoc/2               Create association tree from list
 list_to_set/2                 Remove duplicates from a list
 list_strings/0                Help porting to version 7
 listing/0                     List program in current module

 listing/1                     List predicate
 load_files/1                  Load source files
 load_files/2                  Load source files with options
 load_foreign_library/1        shlib Load shared library (.so file)
 load_foreign_library/2        shlib Load shared library (.so file)
 locale_create/3               Create a new locale object
 locale_destroy/1              Destroy a locale object

 locale_property/2             Query properties of locale objects
 locale_sort/2                 Language dependent sort of atoms
 make/0                        Reconsult all changed source files
 make_directory/1              Create a folder on the file system
 make_library_index/1          Create autoload file INDEX.pl
 make_library_index/2          Create selective autoload file INDEX.pl
 map_assoc/2                   Map association tree
 map_assoc/3                   Map association tree

 dict_create/3                 Create a dict from data
 dict_pairs/3                  Convert between dict and list of pairs
 max_assoc/3                   Highest key in association tree
 memberchk/2                   Deterministic member/2
 message_hook/3                Intercept print_message/2
 message_line_element/2        (hook) Intercept print_message_lines/3
 message_property/2            (hook) Define display of a message

 message_queue_create/1        Create queue for thread communication
 message_queue_create/2        Create queue for thread communication
 message_queue_destroy/1       Destroy queue for thread communication
 message_queue_property/2      Query message queue properties
 message_to_string/2           Translate message-term to string
 meta_predicate/1              Declare access to other predicates
 min_assoc/3                   Lowest key in association tree
 module/1                      Query/set current type-in module

 module/2                      Declare a module
 module/3                      Declare a module with language options
 module_property/2             Find properties of a module
 module_transparent/1          Indicate module based meta-predicate
 msort/2                       Sort, do not remove duplicates
 multifile/1                   Indicate distributed definition of predicate
 mutex_create/1                Create a thread-synchronisation device

 mutex_create/2                Create a thread-synchronisation device
 mutex_destroy/1               Destroy a mutex
 mutex_lock/1                  Become owner of a mutex
 mutex_property/2              Query mutex properties
 mutex_statistics/0            Print statistics on mutex usage
 mutex_trylock/1               Become owner of a mutex (non-blocking)
 mutex_unlock/1                Release ownership of mutex
 mutex_unlock_all/0            Release ownership of all mutexes

 name/2                        Convert between atom and list of character codes
 nb_current/2                  Enumerate non-backtrackable global variables
 nb_delete/1                   Delete a non-backtrackable global variable
 nb_getval/2                   Fetch non-backtrackable global variable
 nb_link_dict/3                Non-backtrackable assignment to dict
 nb_linkarg/3                  Non-backtrackable assignment to term
 nb_linkval/2                  Assign non-backtrackable global variable

 nb_set_to_list/2              Convert non-backtrackable set to list
 nb_set_dict/3                 Non-backtrackable assignment to dict
 nb_setarg/3                   Non-backtrackable assignment to term
 nb_setval/2                   Assign non-backtrackable global variable
 nl/0                          Generate a newline
 nl/1                          Generate a newline on a stream
 nodebug/0                     Disable debugging
 nodebug/1                     Disable debug-topic

 noguitracer/0                 Disable the graphical debugger
 nonground/2                   Term is not ground due to witness
 nonvar/1                      Type check for bound term
 noprofile/1                   Hide (meta-) predicate for the profiler
 noprotocol/0                  Disable logging of user interaction
 normalize_space/2             Normalize white space
 nospy/1                       Remove spy point

 nospyall/0                     Remove all spy points
 not/1                          Negation by failure (argument not provable).  Same as \+/1
 notrace/0                      Stop tracing
 notrace/1                      Do not debug argument goal
 nth_clause/3                   N-th clause of a predicate
 nth_integer_root_and_remainder/4Integer root and remainder
 number/1                       Type check for integer or float
 number_chars/2                 Convert between number and one-char atoms

 number_codes/2                 Convert between number and character codes
 number_string/2                Convert between number and string
 numbervars/3                   Number unbound variables of a term
 numbervars/4                   Number unbound variables of a term
 on_signal/3                    Handle a software signal
 once/1                         Call a goal deterministically
 op/3                           Declare an operator

 open/3                         Open a file (creating a stream)
 open/4                         Open a file (creating a stream)
 open_dde_conversation/3        Win32:  Open DDE channel
 open_null_stream/1             Open a stream to discard output
 open_resource/3                Open a program resource as a stream
 open_shared_object/2           UNIX: Open shared library (.so file)
 open_shared_object/3           UNIX: Open shared library (.so file)
 open_string/2                  Open a string as a stream

 ord_list_to_assoc/2            Convert ordered list to assoc
 parse_time/2                   Parse text to a time-stamp
 parse_time/3                   Parse text to a time-stamp
 pce_dispatch/1                 Run XPCE GUI in separate thread
 pce_call/1                     Run goal in XPCE GUI thread
 peek_byte/1                    Read byte without removing
 peek_byte/2                    Read byte without removing

 peek_char/1                    Read character without removing
 peek_char/2                    Read character without removing
 peek_code/1                    Read character-code without removing
 peek_code/2                    Read character-code without removing
 peek_string/3                  Read a string without removing
 phrase/2                       Activate grammar-rule set
 phrase/3                       Activate grammar-rule set (returning rest)
 phrase_from_quasi_quotation/2  Parse quasi quotation with DCG

 please/3                       Query/change environment parameters
 plus/3                         Logical integer addition
 portray/1                      (hook) Modify behaviour of print/1
 portray_clause/1               Pretty print a clause
 portray_clause/2               Pretty print a clause to a stream
 predicate_property/2           Query predicate attributes
 predsort/3                     Sort, using a predicate to determine the order

 print/1                        Print a term
 print/2                        Print a term on a stream
 print_message/2                Print message from (exception) term
 print_message_lines/3          Print message to stream
 profile/1                      Obtain execution statistics
 profile/2                      Obtain execution statistics
 profile_count/3                Obtain profile results on a predicate
 profiler/2                     Obtain/change status of the profiler

 prolog/0                       Run interactive top level
 prolog_alert_signal/2          Query/set unblock signal
 prolog_choice_attribute/3      Examine the choice point stack
 prolog_current_choice/1        Reference to most recent choice point
 prolog_current_frame/1         Reference to goal's environment stack
 prolog_cut_to/1                Realise global cuts
 prolog_edit:locate/2           Locate targets for edit/1

 prolog_edit:locate/3           Locate targets for edit/1
 prolog_edit:edit_source/1      Call editor for edit/1
 prolog_edit:edit_command/2     Specify editor activation
 prolog_edit:load/0             Load edit/1 extensions
 prolog_exception_hook/4        Rewrite exceptions
 prolog_file_type/2             Define meaning of file extension
 prolog_frame_attribute/3       Obtain information on a goal environment
 prolog_ide/1                   Program access to the development environment

 prolog_list_goal/1             (hook) Intercept tracer 'L' command
 prolog_load_context/2          Context information for directives
 prolog_load_file/2             (hook) Program load_files/2
 prolog_skip_level/2            Indicate deepest recursion to trace
 prolog_skip_frame/1            Perform `skip' on a frame
 prolog_stack_property/2        Query properties of the stacks
 prolog_to_os_filename/2        Convert between Prolog and OS filenames

 prolog_trace_interception/4    user Intercept the Prolog tracer
 project_attributes/2           Project constraints to query variables
 prompt1/1                      Change prompt for 1 line
 prompt/2                       Change the prompt used by read/1
 protocol/1                     Make a log of the user interaction
 protocola/1                    Append log of the user interaction to file
 protocolling/1                 On what file is user interaction logged
 public/1                       Declaration that a predicate may be called

 put/1                          Write a character
 put/2                          Write a character on a stream
 put_assoc/4                    Add Key-Value to association tree
 put_attr/3                     Put attribute on a variable
 put_attrs/2                    Set/replace all attributes on a variable
 put_byte/1                     Write a byte
 put_byte/2                     Write a byte on a stream

 put_char/1                     Write a character
 put_char/2                     Write a character on a stream
 put_code/1                     Write a character-code
 put_code/2                     Write a character-code on a stream
 put_dict/3                     Add/replace multiple keys in a dict
 put_dict/4                     Add/replace a single key in a dict
 qcompile/1                     Compile source to Quick Load File
 qcompile/2                     Compile source to Quick Load File

 qsave_program/1                Create runtime application
 qsave_program/2                Create runtime application
 quasi_quotation_syntax/1       Declare quasi quotation syntax
 quasi_quotation_syntax_error/1 Raise syntax error
 random_property/1              Query properties of random generation
 rational/1                     Type check for a rational number
 rational/3                     Decompose a rational

 read/1                         Read Prolog term
 read/2                         Read Prolog term from stream
 read_clause/3                  Read clause from stream
 read_history/6                 Read using history substitution
 read_link/3                    Read a symbolic link
 read_pending_codes/3           Fetch buffered input from a stream
 read_pending_chars/3           Fetch buffered input from a stream
 read_string/3                  Read a number of characters into a string

 read_string/5                  Read string upto a delimiter
 read_term/2                    Read term with options
 read_term/3                    Read term with options from stream
 read_term_from_atom/3          Read term with options from atom
 recorda/2                      Record term in the database (first)
 recorda/3                      Record term in the database (first)
 recorded/2                     Obtain term from the database

 recorded/3                     Obtain term from the database
 recordz/2                      Record term in the database (last)
 recordz/3                      Record term in the database (last)
 redefine_system_predicate/1    Abolish system definition
 reexport/1                     Load files and re-export the imported predicates
 reexport/2                     Load predicates from a file and re-export it
 reload_foreign_libraries/0     Reload DLLs/shared objects
 reload_library_index/0         Force reloading the autoload index

 rename_file/2                  Change name of file
 repeat/0                       Succeed, leaving infinite backtrack points
 require/1                      This file requires these predicates
 reset/3                        Wrapper for delimited continuations
 reset_gensym/1                 Reset a gensym key
 reset_gensym/0                 Reset all gensym keys
 reset_profiler/0               Clear statistics obtained by the profiler

 resource/3                     Declare a program resource
 retract/1                      Remove clause from the database
 retractall/1                   Remove unifying clauses from the database
 same_file/2                    Succeeds if arguments refer to same file
 same_term/2                    Test terms to be at the same address
 see/1                          Change the current input stream
 seeing/1                       Query the current input stream
 seek/4                         Modify the current position in a stream

 seen/0                         Close the current input stream
 select_dict/2                  Select matching attributes from a dict
 select_dict/3                  Select matching attributes from a dict
 set_end_of_stream/1            Set physical end of an open file
 set_flag/2                     Set value of a flag
 set_input/1                    Set current input stream from a stream
 set_locale/1                   Set the default local

 set_module/1                   Set properties of a module
 set_output/1                   Set current output stream from a stream
 set_prolog_IO/3                Prepare streams for interactive session
 set_prolog_flag/2              Define a system feature
 set_prolog_gc_thread/1         Control the gc thread
 set_prolog_stack/2             Modify stack characteristics
 set_random/1                   Control random number generation
 set_stream/2                   Set stream attribute

 set_stream_position/2          Seek stream to position
 setup_call_cleanup/3           Undo side-effects safely
 setup_call_catcher_cleanup/4   Undo side-effects safely
 setarg/3                       Destructive assignment on term
 setenv/2                       Set shell environment variable
 setlocale/3                    Set/query C-library regional information
 setof/3                        Find all unique solutions to a goal

 shell/1                        Execute OS command
 shell/2                        Execute OS command
 shift/1                        Shift control to the closest reset/3
 show_profile/1                 Show results of the profiler
 size_file/2                    Get size of a file in characters
 size_nb_set/2                  Determine size of non-backtrackable set
 skip/1                         Skip to character in current input
 skip/2                         Skip to character on stream

 sleep/1                        Suspend execution for specified time
 sort/2                         Sort elements in a list
 sort/4                         Sort elements in a list
 source_exports/2               Check whether source exports a predicate
 source_file/1                  Examine currently loaded source files
 source_file/2                  Obtain source file of predicate
 source_file_property/2         Information about loaded files

 source_location/2              Location of last read term
 split_string/4                 Break a string into substrings
 spy/1                          Force tracer on specified predicate
 stamp_date_time/3              Convert time-stamp to date structure
 statistics/0                   Show execution statistics
 statistics/2                   Obtain collected statistics
 stream_pair/3                  Create/examine a bi-directional stream
 stream_position_data/3         Access fields from stream position

 stream_property/2              Get stream properties
 string/1                       Type check for string
 string_concat/3                atom_concat/3 for strings
 string_length/2                Determine length of a string
 string_chars/2                 Conversion between string and list of characters
 string_codes/2                 Conversion between string and list of character codes
 string_code/3                  Get or find a character code in a string

 string_lower/2                 Case conversion to lower case
 string_upper/2                 Case conversion to upper case
 string_predicate/1             (hook) Predicate contains strings
 strip_module/3                 Extract context module and term
 style_check/1                  Change level of warnings
 sub_atom/5                     Take a substring from an atom
 sub_atom_icasechk/3            Case insensitive substring match
 sub_string/5                   Take a substring from a string

 subsumes_term/2                One-sided unification test
 succ/2                         Logical integer successor relation
 swritef/2                      Formatted write on a string
 swritef/3                      Formatted write on a string
 tab/1                          Output number of spaces
 tab/2                          Output number of spaces on a stream
 table/1                        Declare predicate to be tabled

 tdebug/0                       Switch all threads into debug mode
 tdebug/1                       Switch a thread into debug mode
 tell/1                         Change current output stream
 telling/1                      Query current output stream
 term_expansion/2               (hook) Convert term before compilation
 term_expansion/4               (hook) Convert term before compilation
 term_singletons/2              Find singleton variables in a term
 term_string/2                  Read/write a term from/to a string

 term_string/3                  Read/write a term from/to a string
 term_subsumer/3                Most specific generalization of two terms
 term_to_atom/2                 Convert between term and atom
 thread_at_exit/1               Register goal to be called at exit
 thread_create/2                Create a new Prolog task
 thread_create/3                Create a new Prolog task
 thread_detach/1                Make thread cleanup after completion

 thread_exit/1                  Terminate Prolog task with value
 thread_get_message/1           Wait for message
 thread_get_message/2           Wait for message in a queue
 thread_get_message/3           Wait for message in a queue
 thread_initialization/1        Run action at start of thread
 thread_join/1                  Wait for Prolog task-completion
 thread_join/2                  Wait for Prolog task-completion
 thread_local/1                 Declare thread-specific clauses for a predicate

 thread_message_hook/3          Thread local message_hook/3
 thread_peek_message/1          Test for message
 thread_peek_message/2          Test for message in a queue
 thread_property/2              Examine Prolog threads
 thread_self/1                  Get identifier of current thread
 thread_send_message/2          Send message to another thread
 thread_send_message/3          Send message to another thread

 thread_setconcurrency/2        Number of active threads
 thread_signal/2                Execute goal in another thread
 thread_statistics/3            Get statistics of another thread
 threads/0                      List running threads
 throw/1                        Raise an exception (see catch/3)
 time/1                         Determine time needed to execute goal
 time_file/2                    Get last modification time of file
 tmp_file/2                     Create a temporary filename

 tmp_file_stream/3              Create a temporary file and open it
 tnodebug/0                     Switch off debug mode in all threads
 tnodebug/1                     Switch off debug mode in a thread
 told/0                         Close current output
 tprofile/1                     Profile a thread for some period
 trace/0                        Start the tracer
 trace/1                        Set trace point on predicate

 trace/2                        Set/Clear trace point on ports
 tracing/0                      Query status of the tracer
 trie_delete/3                  Remove term from trie
 trie_destroy/1                 Destroy a trie
 trie_gen/3                     Get all terms from a trie
 trie_insert/3                  Insert term into a trie
 trie_insert/4                  Insert term into a trie
 trie_lookup/3                  Lookup a term in a trie

 trie_new/1                     Create a trie
 trie_property/2                Examine a trie's properties
 trie_update/3                  Update associated value in trie
 trie_term/2                    Get term from a trie by handle
 trim_stacks/0                  Release unused memory resources
 true/0                         Succeed
 tspy/1                         Set spy point and enable debugging in all threads

 tspy/2                         Set spy point and enable debugging in a thread
 tty_get_capability/3           Get terminal parameter
 tty_goto/2                     Goto position on screen
 tty_put/2                      Write control string to terminal
 tty_size/2                     Get row/column size of the terminal
 ttyflush/0                     Flush output on terminal
 unify_with_occurs_check/2      Logically sound unification
 unifiable/3                    Determining binding required for unification

 unix/1                         OS interaction
 unknown/2                      Trap undefined predicates
 unload_file/1                  Unload a source file
 unload_foreign_library/1       shlib Detach shared library (.so file)
 unload_foreign_library/2       shlib Detach shared library (.so file)
 unsetenv/1                     Delete shell environment variable
 upcase_atom/2                  Convert atom to upper-case

 use_foreign_library/1          Load DLL/shared object (directive)
 use_foreign_library/2          Load DLL/shared object (directive)
 use_module/1                   Import a module
 use_module/2                   Import predicates from a module
 valid_string_goal/1            (hook) Goal handles strings
 var/1                          Type check for unbound variable
 var_number/2                   Check that var is numbered by numbervars
 var_property/2                 Variable properties during macro expansion

 variant_sha1/2                 Term-hash for term-variants
 variant_hash/2                 Term-hash for term-variants
 version/0                      Print system banner message
 version/1                      Add messages to the system banner
 visible/1                      Ports that are visible in the tracer
 volatile/1                     Predicates that are not saved
 wait_for_input/3               Wait for input with optional timeout

 when/2                         Execute goal when condition becomes true
 wildcard_match/2               Csh(1) style wildcard match
 win_add_dll_directory/1        Add directory to DLL search path
 win_add_dll_directory/2        Add directory to DLL search path
 win_remove_dll_directory/1     Remove directory from DLL search path
 win_exec/2                     Win32:  spawn Windows task
 win_has_menu/0                 Win32:  true if console menu is available
 win_folder/2                   Win32:  get special folder by CSIDL

 win_insert_menu/2              swipl-win.exe:  add menu
 win_insert_menu_item/4         swipl-win.exe:  add item to menu
 win_shell/2                    Win32:  open document through Shell
 win_shell/3                    Win32:  open document through Shell
 win_registry_get_value/3       Win32:  get registry value
 win_window_pos/1               Win32:  change size and position of window
 window_title/2                 Win32:  change title of window

 with_mutex/2                   Run goal while holding mutex
 with_output_to/2               Write to strings and more
 with_quasi_quotation_input/3   Parse quasi quotation from stream
 working_directory/2            Query/change CWD
 write/1                        Write term
 write/2                        Write term to stream
 writeln/1                      Write term, followed by a newline
 writeln/2                      Write term, followed by a newline to a stream

 write_canonical/1              Write a term with quotes, ignore operators
 write_canonical/2              Write a term with quotes, ignore operators on a stream
 write_length/3                 Dermine #characters to output a term
 write_term/2                   Write term with options
 write_term/3                   Write term with options to stream
 writef/1                       Formatted write
 writef/2                       Formatted write on stream

 writeq/1                       Write term, insert quotes
 writeq/2                       Write term, insert quotes on stream


1188..22 LLiibbrraarryy pprreeddiiccaatteess


1188..22..11 lliibbrraarryy((aaggggrreeggaattee))

 aggregate/3      Aggregate bindings in Goal according to Template.
 aggregate/4      Aggregate bindings in Goal according to Template.
 aggregate_all/3  Aggregate bindings in Goal according to Template.
 aggregate_all/4  Aggregate bindings in Goal according to Template.
 foreach/2        True if conjunction of results is true.
 free_variables/4 Find free variables in bagof/setof template.


1188..22..22 lliibbrraarryy((aappppllyy))

 convlist/3   Similar to maplist/3, but elements for which call(Goal, ElemIn, _) fails are omitted from ListOut.
 exclude/3    Filter elements for which Goal fails.
 foldl/4      Fold a list, using arguments of the list as left argument.
 foldl/5      Fold a list, using arguments of the list as left argument.
 foldl/6      Fold a list, using arguments of the list as left argument.
 foldl/7      Fold a list, using arguments of the list as left argument.
 include/3    Filter elements for which Goal succeeds.
 maplist/2    True if Goal can successfully be applied on all elements of List.

 maplist/3    As maplist/2, operating on pairs of elements from two lists.
 maplist/4    As maplist/2, operating on triples of elements from three lists.
 maplist/5    As maplist/2, operating on quadruples of elements from four lists.
 partition/4  Filter elements of List according to Pred.
 partition/5  Filter List according to Pred in three sets.
 scanl/4      Left scan of list.
 scanl/5      Left scan of list.

 scanl/6      Left scan of list.
 scanl/7      Left scan of list.


1188..22..33 lliibbrraarryy((aassssoocc))

 assoc_to_list/2    Translate assoc into a pairs list
 assoc_to_keys/2    Translate assoc into a key list
 assoc_to_values/2  Translate assoc into a value list
 empty_assoc/1      Test/create an empty assoc
 gen_assoc/3        Non-deterministic enumeration of assoc
 get_assoc/3        Get associated value
 get_assoc/5        Get and replace associated value
 list_to_assoc/2    Translate pair list to assoc

 map_assoc/2        Test assoc values
 map_assoc/3        Map assoc values
 max_assoc/3        Max key-value of an assoc
 min_assoc/3        Min key-value of an assoc
 ord_list_to_assoc/2Translate ordered list into an assoc
 put_assoc/4        Add association to an assoc


1188..22..44 lliibbrraarryy((bbrrooaaddccaasstt))

 broadcast/1         Send event notification
 broadcast_request/1 Request all agents
 listen/2            Listen to event notifications
 listen/3            Listen to event notifications
 unlisten/1          Stop listening to event notifications
 unlisten/2          Stop listening to event notifications
 unlisten/3          Stop listening to event notifications
 listening/3         Who is listening to event notifications?


1188..22..55 lliibbrraarryy((cchhaarrssiioo))

 atom_to_chars/2       Convert Atom into a list of character codes.
 atom_to_chars/3       Convert Atom into a difference list of character codes.
 format_to_chars/3     Use format/2 to write to a list of character codes.
 format_to_chars/4     Use format/2 to write to a difference list of character codes.
 number_to_chars/2     Convert Atom into a list of character codes.
 number_to_chars/3     Convert Number into a difference list of character codes.
 open_chars_stream/2   Open Codes as an input stream.
 read_from_chars/2     Read Codes into Term.

 read_term_from_chars/3Read Codes into Term.
 with_output_to_chars/2Run Goal as with once/1.
 with_output_to_chars/3Run Goal as with once/1.
 with_output_to_chars/4Same as with_output_to_chars/3 using an explicit stream.
 write_to_chars/2      Write a term to a code list.
 write_to_chars/3      Write a term to a code list.


1188..22..66 lliibbrraarryy((cchheecckk))

 check/0                  Run all consistency checks defined by checker/2.
 checker/2                Register code validation routines.
 list_autoload/0          Report predicates that may be auto-loaded.
 list_redefined/0         Lists predicates that are defined in the global module =user= as well as in a normal module; that is, predicates for which the@
 list_strings/0           List strings that appear in clauses.
 list_strings/1           List strings that appear in clauses.
 list_trivial_fails/0     List goals that trivially fail because there is no matching clause.
 list_trivial_fails/1     List goals that trivially fail because there is no matching clause.

 list_undefined/0         Report undefined predicates.
 list_undefined/1         Report undefined predicates.
 list_void_declarations/0 List predicates that have declared attributes, but no clauses.
 string_predicate/1       Multifile hook to disable list_strings/0 on the given predicate.
 trivial_fail_goal/1      Multifile hook that tells list_trivial_fails/0 to accept Goal as valid.
 valid_string_goal/1      Multifile hook that qualifies Goal as valid for list_strings/0.


1188..22..77 lliibbrraarryy((ccllppbb))

 labeling/1         Enumerate concrete solutions.
 random_labeling/2  Select a single random solution.
 sat/1              True iff Expr is a satisfiable Boolean expression.
 sat_count/2        Count the number of admissible assignments.
 taut/2             Tautology check.
 weighted_maximum/3 Enumerate weighted optima over admissible assignments.


1188..22..88 lliibbrraarryy((ccllppffdd))

 #/\/2           P and Q hold.
 #</2            The arithmetic expression X is less than Y.
 #<==/2          Q implies P.
 #<==>/2         P and Q are equivalent.
 #=/2            The arithmetic expression X equals Y.
 #=</2           The arithmetic expression X is less than or equal to Y.
 #==>/2          P implies Q.
 #>/2            Same as Y #< X.

 #>=/2           Same as Y #=< X.
 #\/1            Q does _not_hold.
 #\/2            Either P holds or Q holds, but not both.
 #\//2           P or Q holds.
 #\=/2           The arithmetic expressions X and Y evaluate to distinct integers.
 all_different/1 Like all_distinct/1, but with weaker propagation.
 all_distinct/1  True iff Vars are pairwise distinct.

 automaton/3     Describes a list of finite domain variables with a finite automaton.
 automaton/8     Describes a list of finite domain variables with a finite automaton.
 chain/2         Zs form a chain with respect to Relation.
 circuit/1       True iff the list Vs of finite domain variables induces a Hamiltonian circuit.
 cumulative/1    Equivalent to cumulative(Tasks, [limit(1)]).
 cumulative/2         Schedule with a limited resource.
 disjoint2/1          True iff Rectangles are not overlapping.
 element/3            The N-th element of the list of finite domain variables Vs is V.

 fd_dom/2             Dom is the current domain (see in/2) of Var.
 fd_inf/2             Inf is the infimum of the current domain of Var.
 fd_size/2            Reflect the current size of a domain.
 fd_sup/2             Sup is the supremum of the current domain of Var.
 fd_var/1             True iff Var is a CLP(FD) variable.
 global_cardinality/2 Global Cardinality constraint.
 global_cardinality/3 Global Cardinality constraint.

 in/2                 Var is an element of Domain.
 indomain/1           Bind Var to all feasible values of its domain on backtracking.
 ins/2                The variables in the list Vars are elements of Domain.
 label/1              Equivalent to labeling([], Vars).
 labeling/2           Assign a value to each variable in Vars.
 lex_chain/1          Lists are lexicographically non-decreasing.
 scalar_product/4     True iff the scalar product of Cs and Vs is in relation Rel to Expr.
 serialized/2         Describes a set of non-overlapping tasks.

 sum/3                The sum of elements of the list Vars is in relation Rel to Expr.
 transpose/2          Transpose a list of lists of the same length.
 tuples_in/2          True iff all Tuples are elements of Relation.
 zcompare/3           Analogous to compare/3, with finite domain variables A and B.


1188..22..99 lliibbrraarryy((ccllppqqrr))

 entailed/1  Check if constraint is entailed
 inf/2       Find the infimum of an expression
 sup/2       Find the supremum of an expression
 minimize/1  Minimizes an expression
 maximize/1  Maximizes an expression
 bb_inf/3    Infimum of expression for mixed-integer problems
 bb_inf/4    Infimum of expression for mixed-integer problems
 bb_inf/5    Infimum of expression for mixed-integer problems

 dump/3      Dump constraints on variables


1188..22..1100 lliibbrraarryy((ccssvv))

 csv_options/2      Compiled is the compiled representation of the CSV processing options as they may be passed into csv//2, etc.
 csv_read_file/2    Read a CSV file into a list of rows.
 csv_read_file/3    Read a CSV file into a list of rows.
 csv_read_file_row/3True when Row is a row in File.
 csv_read_row/3     Read the next CSV record from Stream and unify the result with Row.
 csv_write_file/2   Write a list of Prolog terms to a CSV file.
 csv_write_file/3   Write a list of Prolog terms to a CSV file.
 csv_write_stream/3 Write the rows in Data to Stream.

 csv//1             Prolog DCG to `read/write' CSV data.
 csv//2             Prolog DCG to `read/write' CSV data.


1188..22..1111 lliibbrraarryy((ddeebbuugg))

 assertion/1             Acts similar to C assert() macro.
 assertion_failed/2      This hook is called if the Goal of assertion/1 fails.
 debug/1                 Add/remove a topic from being printed.
 debug/3                 Format a message if debug topic is enabled.
 debug_message_context/1 Specify additional context for debug messages.
 debug_print_hook/3      Hook called by debug/3.
 debugging/1             Examine debug topics.
 debugging/2             Examine debug topics.

 list_debug_topics/0     List currently known debug topics and their setting.
 nodebug/1               Add/remove a topic from being printed.


1188..22..1122 lliibbrraarryy((eerrrroorr))

 current_type/3          True when Type is a currently defined type and Var satisfies Type of the body term Body succeeds.
 domain_error/2          The argument is of the proper type, but has a value that is outside the supported values.
 existence_error/2       Term is of the correct type and correct domain, but there is no existing (external) resource that is represented by it.
 existence_error/3       Term is of the correct type and correct domain, but there is no existing (external) resource that is represented by it in the p@
 has_type/2              True if Term satisfies Type.
 instantiation_error/1   An argument is under-instantiated.
 is_of_type/2            True if Term satisfies Type.
 must_be/2               True if Term satisfies the type constraints for Type.

 permission_error/3      It is not allowed to perform Action on the object Term that is of the given Type.
 representation_error/1  A representation error indicates a limitation of the implementation.
 resource_error/1        A goal cannot be completed due to lack of resources.
 syntax_error/1          A text has invalid syntax.
 type_error/2            Tell the user that Term is not of the expected Type.
 uninstantiation_error/1 An argument is over-instantiated.


1188..22..1133 lliibbrraarryy((iioossttrreeaamm))


1188..22..1144 lliibbrraarryy((ssuummmmaarriieess..dd//iioossttrreeaamm//tteexx))


1188..22..1155 lliibbrraarryy((lliissttss))

 append/2        Concatenate a list of lists.
 append/3        List1AndList2 is the concatenation of List1 and List2.
 delete/3        Delete matching elements from a list.
 flatten/2       Is true if FlatList is a non-nested version of NestedList.
 intersection/3  True if Set3 unifies with the intersection of Set1 and Set2.
 is_set/1        True if Set is a proper list without duplicates.
 last/2          Succeeds when Last is the last element of List.
 list_to_set/2   True when Set has the same elements as List in the same order.

 max_list/2      True if Max is the largest number in List.
 max_member/2    True when Max is the largest member in the standard order of terms.
 member/2        True if Elem is a member of List.
 min_list/2      True if Min is the smallest number in List.
 min_member/2    True when Min is the smallest member in the standard order of terms.
 nextto/3        True if Y directly follows X in List.
 nth0/3          True when Elem is the Index'th element of List.

 nth0/4          Select/insert element at index.
 nth1/3          Is true when Elem is the Index'th element of List.
 nth1/4          As nth0/4, but counting starts at 1.
 numlist/3       List is a list [Low, Low+1, ...  High].
 permutation/2   True when Xs is a permutation of Ys.
 prefix/2        True iff Part is a leading substring of Whole.
 proper_length/2 True when Length is the number of elements in the proper list List.
 reverse/2       Is true when the elements of List2 are in reverse order compared to List1.

 same_length/2   Is true when List1 and List2 are lists with the same number of elements.
 select/3        Is true when List1, with Elem removed, results in List2.
 select/4        Select from two lists at the same positon.
 selectchk/3     Semi-deterministic removal of first element in List that unifies with Elem.
 selectchk/4     Semi-deterministic version of select/4.
 subset/2        True if all elements of SubSet belong to Set as well.
 subtract/3      Delete all elements in Delete from Set.

 sum_list/2      Sum is the result of adding all numbers in List.
 union/3         True if Set3 unifies with the union of the lists Set1 and Set2.


1188..22..1166 lliibbrraarryy((mmaaiinn))

 argv_options/3 Generic transformation of long commandline arguments to options.
 main/0         Call main/1 using the passed command-line arguments.


1188..22..1177 lliibbrraarryy((ooppttiioonn))

 dict_options/2  Convert between an option list and a dictionary.
 merge_options/3 Merge two option lists.
 meta_options/3  Perform meta-expansion on options that are module-sensitive.
 option/2        Get an Option from OptionList.
 option/3        Get an Option from OptionList.
 select_option/3 Get and remove Option from an option list.
 select_option/4 Get and remove Option with default value.


1188..22..1188 lliibbrraarryy((ooppttppaarrssee))

 opt_arguments/3 Extract commandline options according to a specification.
 opt_help/2      True when Help is a help string synthesized from OptsSpec.
 opt_parse/4     Equivalent to opt_parse(OptsSpec, ApplArgs, Opts, PositionalArgs, []).
 opt_parse/5     Parse the arguments Args (as list of atoms) according to OptsSpec.
 parse_type/3    Hook to parse option text Codes to an object of type Type.


1188..22..1199 lliibbrraarryy((oorrddsseettss))

 is_ordset/1        True if Term is an ordered set.
 list_to_ord_set/2  Transform a list into an ordered set.
 ord_add_element/3  Insert an element into the set.
 ord_del_element/3  Delete an element from an ordered set.
 ord_disjoint/2     True if Set1 and Set2 have no common elements.
 ord_empty/1        True when List is the empty ordered set.
 ord_intersect/2    True if both ordered sets have a non-empty intersection.
 ord_intersect/3    Intersection holds the common elements of Set1 and Set2.

 ord_intersection/2 Intersection of a powerset.
 ord_intersection/3 Intersection holds the common elements of Set1 and Set2.
 ord_intersection/4 Intersection and difference between two ordered sets.
 ord_memberchk/2    True if Element is a member of OrdSet, compared using ==.
 ord_selectchk/3    Selectchk/3, specialised for ordered sets.
 ord_seteq/2        True if Set1 and Set2 have the same elements.
 ord_subset/2       Is true if all elements of Sub are in Super.

 ord_subtract/3     Diff is the set holding all elements of InOSet that are not in NotInOSet.
 ord_symdiff/3      Is true when Difference is the symmetric difference of Set1 and Set2.
 ord_union/2        True if Union is the union of all elements in the superset SetOfSets.
 ord_union/3        Union is the union of Set1 and Set2.
 ord_union/4        True iff ord_union(Set1, Set2, Union) and ord_subtract(Set2, Set1, New).


1188..22..2200 lliibbrraarryy((ppeerrssiisstteennccyy))

 current_persistent_predicate/1 True if PI is a predicate that provides access to the persistent database DB.
 db_attach/2                    Use File as persistent database for the calling module.
 db_attached/1                  True if the context module attached to the persistent database File.
 db_detach/0                    Detach persistency from the calling module and delete all persistent clauses from the Prolog database.
 db_sync/1                      Synchronise database with the associated file.
 db_sync_all/1                  Sync all registered databases.
 persistent/1                   Declare dynamic database terms.


1188..22..2211 lliibbrraarryy((pprreeddiiccaattee__ooppttiioonnss))

 assert_predicate_options/4     As predicate_options(:PI, +Arg, +Options).
 check_predicate_option/3       Verify predicate options at runtime.
 check_predicate_options/0      Analyse loaded program for erroneous options.
 current_option_arg/2           True when Arg of PI processes predicate options.
 current_predicate_option/3     True when Arg of PI processes Option.
 current_predicate_options/3    True when Options is the current active option declaration for PI on Arg.
 derive_predicate_options/0     Derive new predicate option declarations.
 derived_predicate_options/1    Derive predicate option declarations for a module.

 derived_predicate_options/3    Derive option arguments using static analysis.
 predicate_options/3            Declare that the predicate PI processes options on Arg.
 retractall_predicate_options/0 Remove all dynamically (derived) predicate options.


1188..22..2222 lliibbrraarryy((pprroollooggppaacckk))

 environment/2         Hook to define the environment for building packs.
 pack_info/1           Print more detailed information about Pack.
 pack_install/1        Install a package.
 pack_install/2        Install package Name.
 pack_list/1           Query package server and installed packages and display results.
 pack_list_installed/0 List currently installed packages.
 pack_property/2       True when Property is a property of an installed Pack.
 pack_rebuild/0        Rebuild foreign components of all packages.

 pack_rebuild/1        Rebuilt possible foreign components of Pack.
 pack_remove/1         Remove the indicated package.
 pack_search/1         Query package server and installed packages and display results.
 pack_upgrade/1        Try to upgrade the package Pack.
 pack_url_file/2       True if File is a unique id for the referenced pack and version.


1188..22..2233 lliibbrraarryy((pprroollooggxxrreeff))

 prolog:called_by/2    (hook) Extend cross-referencer
 xref_built_in/1       Examine defined built-ins
 xref_called/3         Examine called predicates
 xref_clean/1          Remove analysis of source
 xref_current_source/1 Examine cross-referenced sources
 xref_defined/3        Examine defined predicates
 xref_exported/2       Examine exported predicates
 xref_module/2         Module defined by source

 xref_source/1         Cross-reference analysis of source


1188..22..2244 lliibbrraarryy((ppaaiirrss))

 group_pairs_by_key/2Group values with equivalent (==/2) consecutive keys.
 map_list_to_pairs/3 Create a Key-Value list by mapping each element of List.
 pairs_keys/2        Remove the values from a list of Key-Value pairs.
 pairs_keys_values/3 True if Keys holds the keys of Pairs and Values the values.
 pairs_values/2      Remove the keys from a list of Key-Value pairs.
 transpose_pairs/2   Swap Key-Value to Value-Key.


1188..22..2255 lliibbrraarryy((ppiioo))


1188..22..2255..11 lliibbrraarryy((ppuurree__iinnppuutt))

 phrase_from_file/2          Process the content of File using the DCG rule Grammar.
 phrase_from_file/3          As phrase_from_file/2, providing additional Options.
 phrase_from_stream/2        Run Grammer against the character codes on Stream.
 stream_to_lazy_list/2       Create a lazy list representing the character codes in Stream.
 lazy_list_character_count//1True when CharCount is the current character count in the Lazy list.
 lazy_list_location//1       Determine current (error) location in a lazy list.
 syntax_error//1             Throw the syntax error Error at the current location of the input.


1188..22..2266 lliibbrraarryy((rraannddoomm))

 getrand/1            Query/set the state of the random generator.
 maybe/0              Succeed/fail with equal probability (variant of maybe/1).
 maybe/1              Succeed with probability P, fail with probability 1-P.
 maybe/2              Succeed with probability K/N (variant of maybe/1).
 random/1             Binds R to a new random float in the _open_interval (0.0,1.0).
 random/3             Generate a random integer or float in a range.
 random_between/3     Binds R to a random integer in [L,U] (i.e., including both L and U).
 random_member/2      X is a random member of List.

 random_perm2/4       Does X=A,Y=B or X=B,Y=A with equal probability.
 random_permutation/2 Permutation is a random permutation of List.
 random_select/3      Randomly select or insert an element.
 randseq/3            S is a list of K unique random integers in the range 1..N.
 randset/3            S is a sorted list of K unique random integers in the range 1..N.
 setrand/1            Query/set the state of the random generator.


1188..22..2277 lliibbrraarryy((rreeaadduuttiill))

 read_line_to_codes/2  Read line from a stream
 read_line_to_codes/3  Read line from a stream
 read_stream_to_codes/2Read contents of stream
 read_stream_to_codes/3Read contents of stream
 read_file_to_codes/3  Read contents of file
 read_file_to_terms/3  Read contents of file to Prolog terms


1188..22..2288 lliibbrraarryy((rreeccoorrdd))

 record/1  Define named fields in a term


1188..22..2299 lliibbrraarryy((rreeggiissttrryy))

This library is only available on Windows systems.

 registry_get_key/2        Get principal value of key
 registry_get_key/3        Get associated value of key
 registry_set_key/2        Set principal value of key
 registry_set_key/3        Set associated value of key
 registry_delete_key/1     Remove a key
 shell_register_file_type/4Register a file-type
 shell_register_dde/6      Register DDE action
 shell_register_prolog/1   Register Prolog


1188..22..3300 lliibbrraarryy((ssiimmpplleexx))

 assignment/2      Solve assignment problem
 constraint/3      Add linear constraint to state
 constraint/4      Add named linear constraint to state
 constraint_add/4  Extend a named constraint
 gen_state/1       Create empty linear program
 maximize/3        Maximize objective function in to linear constraints
 minimize/3        Minimize objective function in to linear constraints
 objective/2       Fetch value of objective function

 shadow_price/3    Fetch shadow price in solved state
 transportation/4  Solve transportation problem
 variable_value/3  Fetch value of variable in solved state


1188..22..3311 lliibbrraarryy((uuggrraapphhss))

 vertices_edges_to_ugraph/3Create unweighted graph
 vertices/2                Find vertices in graph
 edges/2                   Find edges in graph
 add_vertices/3            Add vertices to graph
 del_vertices/3            Delete vertices from graph
 add_edges/3               Add edges to graph
 del_edges/3               Delete edges from graph
 transpose_ugraph/2        Invert the direction of all edges

 neighbors/3               Find neighbors of vertice
 neighbours/3              Find neighbors of vertice
 complement/2              Inverse presense of edges
 compose/3
 top_sort/2                Sort graph topologically
 top_sort/3                Sort graph topologically
 transitive_closure/2      Create transitive closure of graph

 reachable/3               Find all reachable vertices
 ugraph_union/3            Union of two graphs


1188..22..3322 lliibbrraarryy((uurrll))

 file_name_to_url/2 Translate between a filename and a file:// URL.
 global_url/3       Translate a possibly relative URL into an absolute one.
 http_location/2    Construct or analyze an HTTP location.
 is_absolute_url/1  True if URL is an absolute URL.
 parse_url/2        Construct or analyse a URL.
 parse_url/3        Similar to parse_url/2 for relative URLs.
 parse_url_search/2 Construct or analyze an HTTP search specification.
 set_url_encoding/2 Query and set the encoding for URLs.

 url_iri/2          Convert between a URL, encoding in US-ASCII and an IRI.
 www_form_encode/2  En/decode to/from application/x-www-form-encoded.


1188..22..3333 lliibbrraarryy((wwwwww__bbrroowwsseerr))

 www_open_url/1 Open a web-page in a browser


1188..22..3344 lliibbrraarryy((ssoolluuttiioonn__sseeqquueenncceess))

 distinct/1  True if Goal is true and no previous solution of Goal bound Witness to the same value.
 distinct/2  True if Goal is true and no previous solution of Goal bound Witness to the same value.
 group_by/4  Group bindings of Template that have the same value for By.
 limit/2     Limit the number of solutions.
 offset/2    Ignore the first Count solutions.
 order_by/2  Order solutions according to Spec.
 reduced/1   Similar to distinct/1, but does not guarantee unique results in return for using a limited amount of memory.
 reduced/3   Similar to distinct/1, but does not guarantee unique results in return for using a limited amount of memory.


1188..22..3355 lliibbrraarryy((tthhrreeaadd__ppooooll))

 create_pool/1          Hook to create a thread pool lazily.
 current_thread_pool/1  True if Name refers to a defined thread pool.
 thread_create_in_pool/4Create a thread in Pool.
 thread_pool_create/3   Create a pool of threads.
 thread_pool_destroy/1  Destroy the thread pool named Name.
 thread_pool_property/2 True if Property is a property of thread pool Name.


1188..22..3366 lliibbrraarryy((vvaarrnnuummbbeerrss))

 max_var_number/3   True when Max is the max of Start and the highest numbered $VAR(N) term.
 numbervars/1       Number variables in Term using $VAR(N).
 varnumbers/2       Inverse of numbervars/1.
 varnumbers/3       Inverse of numbervars/3.
 varnumbers_names/3 If Term is a term with numbered and named variables using the reserved term '$VAR'(X), Copy is a copy of Term where each '$VAR'(X) i@


1188..22..3377 lliibbrraarryy((yyaallll))

 //2            Shorthand for `Free/[]>>Lambda`.
 //3            Shorthand for `Free/[]>>Lambda`.
 //4            Shorthand for `Free/[]>>Lambda`.
 //5            Shorthand for `Free/[]>>Lambda`.
 //6            Shorthand for `Free/[]>>Lambda`.
 //7            Shorthand for `Free/[]>>Lambda`.
 //8            Shorthand for `Free/[]>>Lambda`.
 //9            Shorthand for `Free/[]>>Lambda`.

 >>/2           Calls a copy of Lambda.
 >>/3           Calls a copy of Lambda.
 >>/4           Calls a copy of Lambda.
 >>/5           Calls a copy of Lambda.
 >>/6           Calls a copy of Lambda.
 >>/7           Calls a copy of Lambda.
 >>/8           Calls a copy of Lambda.

 >>/9           Calls a copy of Lambda.
 is_lambda/1    True if Term is a valid Lambda expression.
 lambda_calls/2 Goal is the goal called if call/N is applied to LambdaExpression, where ExtraArgs are the additional arguments to call/N.
 lambda_calls/3 Goal is the goal called if call/N is applied to LambdaExpression, where ExtraArgs are the additional arguments to call/N.


1188..33 AArriitthhmmeettiicc FFuunnccttiioonnss

 */2      Multiplication
 **/2     Power function

 +/1      Unary plus (No-op)
 +/2      Addition
 -/1      Unary minus
 -/2      Subtraction
 //2      Division
 ///2     Integer division
 /\/2     Bitwise and
 <</2     Bitwise left shift

 >>/2     Bitwise right shift
 ./2      List of one character:  character code
 \/1      Bitwise negation
 \//2     Bitwise or
 ^/2      Power function
 abs/1    Absolute value
 acos/1   Inverse (arc) cosine

 acosh/1  Inverse hyperbolic cosine
 asin/1   Inverse (arc) sine
 asinh/1  Inverse (arc) sine
 atan/1                  Inverse hyperbolic sine
 atan/2                  Rectangular to polar conversion
 atanh/1                 Inverse hyperbolic tangent
 atan2/2                 Rectangular to polar conversion
 ceil/1                  Smallest integer larger than arg

 ceiling/1               Smallest integer larger than arg
 cos/1                   Cosine
 cosh/1                  Hyperbolic cosine
 copysign/2              Apply sign of N2 to N1
 cputime/0               Get CPU time
 div/2                   Integer division
 e/0                     Mathematical constant

 erf/1                   Gauss error function
 erfc/1                  Complementary error function
 epsilon/0               Floating point precision
 eval/1                  Evaluate term as expression
 exp/1                   Exponent (base e)
 float/1                 Explicitly convert to float
 float_fractional_part/1 Fractional part of a float
 float_integer_part/1    Integer part of a float

 floor/1                 Largest integer below argument
 gcd/2                   Greatest common divisor
 getbit/2                Get bit at index from large integer
 inf/0                   Positive infinity
 integer/1               Round to nearest integer
 lgamma/1                Log of gamma function
 log/1                   Natural logarithm

 log10/1                 10 base logarithm
 lsb/1                   Least significant bit
 max/2                   Maximum of two numbers
 min/2                   Minimum of two numbers
 msb/1                   Most significant bit
 mod/2                   Remainder of division
 nan/0                   Not a Number (NaN)
 powm/3                  Integer exponent and modulo

 random/1                Generate random number
 random_float/0          Generate random number
 rational/1              Convert to rational number
 rationalize/1           Convert to rational number
 rdiv/2                  Ration number division
 rem/2                   Remainder of division
 round/1                 Round to nearest integer

 truncate/1              Truncate float to integer
 pi/0                    Mathematical constant
 popcount/1              Count 1s in a bitvector
 sign/1                  Extract sign of value
 sin/1                   Sine
 sinh/1                  Hyperbolic sine
 sqrt/1                  Square root
 tan/1                   Tangent

 tanh/1                  Hyperbolic tangent
 xor/2                   Bitwise exclusive or


1188..44 OOppeerraattoorrss

 $      1    fx  Bind top-level variable
 ^    200   xfy  Existential qualification
 ^    200   xfy  Arithmetic function
 mod  300   xfx  Arithmetic function
 *    400   yfx  Arithmetic function
 /    400   yfx  Arithmetic function
 //   400   yfx  Arithmetic function
 <<   400   yfx  Arithmetic function

 >>   400   yfx  Arithmetic function
 xor  400   yfx  Arithmetic function
 +    500    fx  Arithmetic function
 -    500    fx  Arithmetic function
 ?    500    fx  XPCE: obtainer
 \    500    fx  Arithmetic function
 +    500   yfx  Arithmetic function

 -    500   yfx  Arithmetic function
 /\   500   yfx  Arithmetic function
 \/   500   yfx  Arithmetic function
 :    600   xfy  module:term separator
 <    700   xfx  Predicate
 =     700   xfx  Predicate
 =..   700   xfx  Predicate
 =:=   700   xfx  Predicate

 <     700   xfx  Predicate
 ==    700   xfx  Predicate
 =@=   700   xfx  Predicate
 =\=   700   xfx  Predicate
 >     700   xfx  Predicate
 >=    700   xfx  Predicate
 @<    700   xfx  Predicate

 @=<   700   xfx  Predicate
 @>    700   xfx  Predicate
 @>=   700   xfx  Predicate
 is    700   xfx  Predicate
 \=    700   xfx  Predicate
 \==   700   xfx  Predicate
 =@=   700   xfx  Predicate
 not   900    fy  Predicate

 \+    900    fy  Predicate
 ,    1000   xfy  Predicate
 ->                 1050   xfy   Predicate
 *->                1050   xfy   Predicate
 ;                  1100   xfy   Predicate
 |                  1105   xfy   DCG disjunction
 discontiguous      1150    fx   Directive

 dynamic            1150    fx   Directive
 module_transparent 1150    fx   Directive
 meta_predicate     1150    fx   Head
 multifile          1150    fx   Directive
 thread_local       1150    fx   Directive
 volatile           1150    fx   Directive
 initialization     1150    fx   Directive
 :-                 1200    fx   Introduces a directive

 ?-                 1200    fx   Introduces a directive
 -->                1200   xfx   DCGrammar:  rewrite
 :-                 1200   xfx   head :- body.  separator


Bibliography

[Anjewierden & Wielemaker, 1989]  A.  Anjewierden  and  J.   Wielemaker.
                                  Extensible  objects.  ESPRIT   Project
                                  1098 Technical Report  UvA-C1-TR-006a,
                                  University of Amsterdam, March 1989.

[BIM, 1989]                       _B_I_M  _P_r_o_l_o_g  _r_e_l_e_a_s_e  _2_._4.   Everberg,
                                  Belgium, 1989.

[Bowen & Byrd, 1983]              D. L. Bowen and L. M. Byrd. A portable
                                  Prolog compiler.  In  L.  M.  Pereira,
                                  editor,  _P_r_o_c_e_e_d_i_n_g_s   _o_f  _t_h_e   _L_o_g_i_n
                                  _P_r_o_g_r_a_m_m_i_n_g  _W_o_r_k_s_h_o_p  _1_9_8_3,  Lisabon,
                                  Portugal, 1983.  Universidade nova  de
                                  Lisboa.

[Bratko, 1986]                    I. Bratko. _P_r_o_l_o_g _P_r_o_g_r_a_m_m_i_n_g _f_o_r  _A_r_-
                                  _t_i_f_i_c_i_a_l _I_n_t_e_l_l_i_g_e_n_c_e. Addison-Wesley,
                                  Reading, Massachusetts, 1986.

[Butenhof, 1997]                  David R.  Butenhof.  _P_r_o_g_r_a_m_m_i_n_g  _w_i_t_h
                                  _P_O_S_I_X _t_h_r_e_a_d_s.  Addison-Wesley,  Read-
                                  ing, MA, USA, 1997.

[Clocksin & Melish, 1987]         W.  F.  Clocksin  and  C.  S.  Melish.
                                  _P_r_o_g_r_a_m_m_i_n_g   _i_n  _P_r_o_l_o_g.    Springer-
                                  Verlag, New York,  Third, Revised  and
                                  Extended edition, 1987.

[Demoen, 2002]                    Bart Demoen. Dynamic attributes, their
                                  hProlog implementation,  and  a  first
                                  evaluation. Report CW 350,  Department
                                  of  Computer   Science,    K.U.Leuven,
                                  Leuven,  Belgium,  oct  2002.   URL  =
                                  http://www.cs.kuleuven.ac.be/publicaties/rapporten/cw/CW350.abs.html.

[Deransart _e_t _a_l_., 1996]          P.  Deransart,    A.  Ed-Dbali,    and
                                  L. Cervoni.  _P_r_o_l_o_g_:    _T_h_e  _S_t_a_n_d_a_r_d.
                                  Springer-Verlag, New York, 1996.

[Fr"uhwirth, ]                    T.   Fr"uhwirth.   Thom    Fruehwirth's
                                  constraint   handling    rules    web-
                                  site.       http://www.informatik.uni-
                                  ulm.de/pm/mitarbeiter/fruehwirth/chr-
                                  intro.html.

[Fr"uhwirth, 1998]                T.  Fr"uhwirth.  Theory  and   Practice
                                  of  Constraint  Handling   Rules.   In
                                  P. Stuckey  and K.  Marriot,  editors,
                                  _S_p_e_c_i_a_l  _I_s_s_u_e  _o_n  _C_o_n_s_t_r_a_i_n_t   _L_o_g_i_c
                                  _P_r_o_g_r_a_m_m_i_n_g, volume 37, October 1998.

[Graham _e_t _a_l_., 1982]             Susan L. Graham, Peter B. Kessler, and
                                  Marshall K. McKusick.  gprof:  a  call
                                  graph execution  profiler. In  _S_I_G_P_L_A_N
                                  _S_y_m_p_o_s_i_u_m  _o_n  _C_o_m_p_i_l_e_r  _C_o_n_s_t_r_u_c_t_i_o_n,
                                  pages 120--126, 1982.

[Hodgson, 1998]                   Jonathan Hodgson. validation suite for
                                  conformance with part  1 of the  stan-
                                  dard,  1998,  http://www.sju.edu/{\tt\
                                  string~}jhodgson/pub/suite.tar.gz.

[Holzbaur, 1990]                  Christian  Holzbaur.  Realization   of
                                  forward  checking  in  logic  program-
                                  ming  through  extended   unification.
                                  Report  TR-90-11,    Oesterreichisches
                                  Forschungsinstitut fuer Artificial In-
                                  telligence, Wien, Austria, 1990.

[Kernighan & Ritchie, 1978]       B. W. Kernighan and D. M. Ritchie. _T_h_e
                                  _C _P_r_o_g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e. Prentice-Hall,
                                  Englewood Cliffs, New Jersey, 1978.

[O'Keefe, 1990]                   R. A.  O'Keefe. _T_h_e  _C_r_a_f_t _o_f  _P_r_o_l_o_g.
                                  MIT Press, Massachussetts, 1990.

[Pereira, 1986]                   F. Pereira.  _C_-_P_r_o_l_o_g  _U_s_e_r_'_s  _M_a_n_u_a_l,
                                  1986.

[Qui, 1997]                       _Q_u_i_n_t_u_s   _P_r_o_l_o_g_,   _U_s_e_r   _G_u_i_d_e   _a_n_d
                                  _R_e_f_e_r_e_n_c_e  _M_a_n_u_a_l.  Berkhamsted,   UK,
                                  1997.

[Sterling & Shapiro, 1986]        L.  Sterling  and   E.  Shapiro.   _T_h_e
                                  _A_r_t _o_f _P_r_o_l_o_g.  MIT Press,  Cambridge,
                                  Massachusetts, 1986.

                                  1969