swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / library / MANUAL

                                              University of Amsterdam

                                                Kruislaan 419, 1098
                                                   VA  Amsterdam

                                              VU University Amsterdam
                                                De Boelelaan 1081a,

                                                1081 HV  Amsterdam
                                                  The Netherlands

                        SSWWII--PPrroolloogg 55..1100

                        RReeffeerreennccee MMaannuuaall

             _U_p_d_a_t_e_d _f_o_r _v_e_r_s_i_o_n _5_._1_0_._4_, _M_a_r_c_h _2_0_1_1

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

SWI-Prolog  is  a Prolog  implementation based  on a  subset of
the  WAM (Warren Abstract  Machine).   SWI-Prolog was developed
as  an _o_p_e_n  Prolog environment,  providing a powerful  and bi-
directional  interface to C in an era this was unknown to other
Prolog  implementations.  This environment  is required to deal
with  XPCE,  an object-oriented  GUI system  developed  at SWI.
XPCE  is used at SWI for the development of knowledge-intensive
graphical  applications.   As  SWI-Prolog became  more popular,
a   large  user-community  provided  requirements  that  guided
its  development.    Compatibility,  portability,  scalability,
stability  and  providing  a  powerful development  environment
have   been  the  most  important  requirements.     Edinburgh,
Quintus,  SICStus and the ISO-standard guide the development of
the  SWI-Prolog primitives.  This document gives an overview of
the features, system limits and built-in predicates.

Copyright Oc 1990--2011, University of Amsterdam


CChhaapptteerr 11..  IINNTTRROODDUUCCTTIIOONN


11..11 SSWWII--PPrroolloogg

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

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

SWI-Prolog  extends  the  minimal  set  of   instructions  described  in
[Bowen _e_t _a_l_., 1983]  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..11..11 BBooookkss aabboouutt PPrroolloogg

This manual does not  describe the full syntax and semantics  of Prolog,
nor how  one should  write a  program in Prolog.    These subjects  have
been  described extensively  in  the literature.    See  [Bratko, 1986],
[Sterling & Shapiro, 1986],   and   [Clocksin & Melish, 1987].       For
more  advanced  Prolog  material  see  [O'Keefe, 1990].      Syntax  and
standard  operator declarations  conform  to the  `Edinburgh  standard'.
Most  built-in  predicates  are  compatible  with   those  described  in
[Clocksin & Melish, 1987].      SWI-Prolog  also  offers  a  number   of
primitive  predicates compatible  with  Quintus Prolog  [Qui, 1997]  and
BIM_Prolog [BIM, 1989].

ISO  compliant  predicates  are based  on  ``Prolog:    The  Standard'',
[Deransart _e_t _a_l_., 1996], validated using [Hodgson, 1998].


11..22 SSttaattuuss

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

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

11..33 CCoommpplliiaannccee ttoo tthhee IISSOO ssttaannddaarrdd

SWI-Prolog 3.3.0 implements  all predicates described in ``Prolog:   The
Standard'' [Deransart _e_t _a_l_., 1996].

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

11..44 SShhoouulldd yyoouu bbee uussiinngg SSWWII--PPrroolloogg??

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

  o _S_W_I_-_P_r_o_l_o_g _i_s _n_o_t _s_u_p_p_o_r_t_e_d
    Although  I usually fix bugs shortly  after a bug report arrives,  I
    cannot  promise anything.   Now that the  sources are provided,  you
    can always dig into them yourself.

  o _M_e_m_o_r_y _r_e_q_u_i_r_e_m_e_n_t_s _a_n_d _p_e_r_f_o_r_m_a_n_c_e _a_r_e _y_o_u_r _f_i_r_s_t _c_o_n_c_e_r_n_s
    A  number  of  commercial compilers  are  more  keen on  memory  and
    performance  than SWI-Prolog.   I do not  wish to sacrifice some  of
    the  nice features of the system, nor its portability to  compete on
    raw performance.

  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
    In  this case you  may wish to  give me suggestions for  extensions.
    If  you  have great  plans, please  contact me  (you  might have  to
    implement them yourself however).

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

  o _N_i_c_e _e_n_v_i_r_o_n_m_e_n_t
    This includes `Do  What I Mean', automatic completion of atom names,
    history mechanism and  a tracer that operates on single key-strokes.
    Interfaces  to  some  standard  editors are  provided  (and  can  be
    extended), as well as a facility to maintain programs (see make/0).

  o _V_e_r_y _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 a Quick Load Format that
    is slightly more compact and loading is almost always I/O bound.

  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.  Also, performance  is much better than the  performance of
    most interpreters.

  o _P_r_o_f_i_l_i_n_g
    SWI-Prolog offers tools  for performance analysis, which can be very
    useful  to optimise  programs.   Unless you  are very familiar  with
    Prolog  and Prolog  performance  considerations this  might be  more
    helpful than a better compiler without these facilities.

  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  9).  It can also be _e_m_b_e_d_d_e_d embedded in  external programs
    (see  section 9.5).  System  predicates can be redefined locally  to
    provide compatibility with other Prolog systems.

  o _I_n_t_e_g_r_a_t_i_o_n _w_i_t_h _X_P_C_E
    SWI-Prolog   offers  a   tight  integration  to   the  Object   Ori-
    ented   Package  for   User  Interface   Development,  called   XPCE
    [Anjewierden & Wielemaker, 1989].    XPCE  allows you  to  implement
    graphical  user  interfaces  that are  source-code  compatible  over
    Unix/X11,  Win32  (Windows  95/98/ME  and NT/2000/XP)  and  MacOS  X
    (darwin).


11..55 TThhee XXPPCCEE GGUUII ssyysstteemm ffoorr PPrroolloogg

The  XPCE GUI  system  for dynamically  typed  languages has  been  with
SWI-Prolog for  a long time.   It is  developed by Anjo Anjewierden  and
Jan  Wielemaker from  the department  of SWI,  University of  Amsterdam.
It  aims at  a  high-productive  development environment  for  graphical
applications based on Prolog.

Object  oriented  technology has  proven  to  be a  suitable  model  for
implementing GUIs, which  typically deal with things Prolog is  not very
good  at:   event-driven  control  and global  state.    With  XPCE,  we
designed  a system  that has  similar characteristics  that make  Prolog
such  a powerful  tool:   dynamic typing,  meta-programming and  dynamic
modification of the running system.

XPCE is  an object-system written  in the C-language.   It provides  for
the implementation of methods  in multiple languages.  New  XPCE classes
may be defined from Prolog using a simple, natural syntax.   The body of
the method is executed  by Prolog itself, providing a  natural interface
between the two systems.  Below is a very simple class definition.

________________________________________________________________________|                                                                        |
|:- pce_begin_class(prolog_lister, frame,                                |

|                   "List Prolog predicates").                           |
|                                                                        |
|initialise(Self) :->                                                    |
|        "As the C++ constructor"::                                      |
|        send_super(Self, initialise, 'Prolog Lister'),                  |
|        send(Self, append, new(D, dialog)),                             |
|        send(D, append,                                                 |
|             text_item(predicate, message(Self, list, @arg1))),         |

|        send(new(view), below, D).                                      |
|                                                                        |
|list(Self, From:name) :->                                               |
|        "List predicates from specification"::                          |
|        (   catch(term_to_atom(Term, From), _, fail)                    |
|        ->  get(Self, member, view, V),                                 |
|            current_output(Old),                                        |

|            pce_open(V, write, Fd),                                     |
|            set_output(Fd),                                             |
|            listing(Term),                                              |
|            close(Fd),                                                  |
|            set_output(Old)                                             |
|        ;   send(Self, report, error, 'Syntax error')                   |
|        ).                                                              |
|                                                                        |

|:- pce_end_class.                                                       |
|                                                                        |
|test|:-_send(new(prolog_lister),_open).________________________________ |    |

Its  165  built-in   classes  deal  with  the  meta-environment,   data-
representation  and---of  course---graphics.     The   graphics  classes
concentrate on direct-manipulation of diagrammatic representations.

AAvvaaiillaabbiilliittyy.. XPCE  runs on  most  Unixtm platforms,  Windows  95/98/ME,
Windows NT/2000/XP and MacOS  X (using X11).  In the past,  versions for
Quintus- and SICStus Prolog as well as some Lisp  dialects have existed.
After discontinuing  active Lisp  development at SWI  the Lisp  versions
have died.   Active development on the Quintus and SICStus  versions has
been stopped  due to lack  of standardisation  in the Prolog  community.
If adequate  standards emerge  we are  happy to  actively support  other
Prolog implementations.

IInnffoo.. further    information   is    available   from    http://www.swi-
prolog.org/packages/xpce/ or by E-mail to info@www.swi-prolog.org.


11..66 RReelleeaassee NNootteess

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

VVeerrssiioonn 11..88 RReelleeaassee NNootteess

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

VVeerrssiioonn 11..99 RReelleeaassee NNootteess

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

  o _R_e_d_e_f_i_n_i_t_i_o_n _o_f _s_y_s_t_e_m _p_r_e_d_i_c_a_t_e_s
    Redefinition  of system  predicates  was allowed  silently in  older
    versions.    Version 1.9  only allows it  if the  new definition  is
    headed by a :- redefine_system_predicate/1 directive.top-level

  o _`_A_n_s_w_e_r_' _r_e_u_s_e
    The  top-level maintains a table  of bindings returned by  top-level
    goals  and  allows for  reuse  of these  bindings by  prefixing  the
    variables with the $ sign.  See section 2.8.

  o _B_e_t_t_e_r _s_o_u_r_c_e _c_o_d_e _a_d_m_i_n_i_s_t_r_a_t_i_o_n
    Allows  for proper updating of multifile predicates and  finding the
    sources of individual clauses.


VVeerrssiioonn 22..00 RReelleeaassee NNootteess

New features offered:

  o _3_2_-_b_i_t _V_i_r_t_u_a_l _M_a_c_h_i_n_e
    Removes various limits and improves performance.

  o _I_n_l_i_n_e _f_o_r_e_i_g_n _f_u_n_c_t_i_o_n_s
    `Simple'  foreign predicates no  longer build a Prolog  stack-frame,
    but are directly  called from the VM. Notably provides a speedup for
    the test predicates such as var/1, etc.

  o _V_a_r_i_o_u_s _c_o_m_p_a_t_i_b_i_l_i_t_y _i_m_p_r_o_v_e_m_e_n_t_s

  o _S_t_r_e_a_m _b_a_s_e_d _I_/_O _l_i_b_r_a_r_y
    All  SWI-Prolog's I/O is now  handled by the stream-package  defined
    in  the foreign include file SWI-Stream.h.   Physical I/O of  Prolog
    streams  may be  redefined through the  foreign language  interface,
    facilitating much simpler integration in window environments.


VVeerrssiioonn 22..55 RReelleeaassee NNootteess

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

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

  o _I_S_O _c_o_m_p_a_t_i_b_i_l_i_t_y
    Many   ISO  compatibility  features   have  been  added:     open/4,
    arithmetic functions, syntax, etc.

  o _W_i_n_3_2
    Many  fixes for the Win32 (NT,  '95 and win32s) platforms.   Notably
    many  problems related  to pathnames  and a problem  in the  garbage
    collector.

  o _P_e_r_f_o_r_m_a_n_c_e
    Many  changes to  the clause  indexing system:   added  hash-tables,
    lazy computation of the index information, etc.

  o _P_o_r_t_a_b_l_e _s_a_v_e_d_-_s_t_a_t_e_s
    The   predicate  qsave_program/[1,2] allows  for   the  creating  of
    machine independent saved-states that load very quickly.


VVeerrssiioonn 22..66 RReelleeaassee NNootteess

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

  o _3_2_-_b_i_t _i_n_t_e_g_e_r _a_n_d _d_o_u_b_l_e _f_l_o_a_t _a_r_i_t_h_m_e_t_i_c
    The  biggest change is the  support for full 32-bit signed  integers
    and  raw  machine-format  double precision  floats.    The  internal
    data  representation as well as  the arithmetic instruction set  and
    interface to the arithmetic functions has been changed for this.

  o _E_m_b_e_d_d_i_n_g _f_o_r _W_i_n_3_2 _a_p_p_l_i_c_a_t_i_o_n_s
    The  Win32 version has been reorganised.   The Prolog kernel is  now
    implemented  as Win32  DLL that may  be embedded in  C-applications.
    Two front ends  are provided, one for window-based operation and one
    to run as a Win32 console application.

  o _C_r_e_a_t_i_n_g _s_t_a_n_d_-_a_l_o_n_e _e_x_e_c_u_t_a_b_l_e_s
    Version  2.6.0 can create  stand-alone executables by attaching  the
    saved-state to the emulator.  See qsave_program/2.


VVeerrssiioonn 22..77 RReelleeaassee NNootteess

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

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

VVeerrssiioonn 22..88 RReelleeaassee NNootteess

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

VVeerrssiioonn 22..99 RReelleeaassee NNootteess

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

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

VVeerrssiioonn 33..00 RReelleeaassee NNootteess

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

VVeerrssiioonn 33..11 RReelleeaassee NNootteess

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

VVeerrssiioonn 33..33 RReelleeaassee NNootteess

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

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

As of version  3.3, SWI-Prolog adheres the  ISO _l_o_g_i_c_a_l _u_p_d_a_t_e _v_i_e_w  for
dynamic predicates.  See section 4.12.1 for details.

SWI-Prolog  3.3  includes garbage  collection  on  atoms,  removing  the
last serious memory  leak especially in text-manipulation  applications.
See  section 9.4.2.1.    In addition,  both the  user-level and  foreign
interface supports atoms holding _0_-_b_y_t_e_s.

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

IInnccoommppaattiibbllee cchhaannggeess

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

  o !/0_, call/1
    The  cut now behaves  according to the ISO  standard.  This  implies
    it  works in compound  goals passed  to call/1 and  is local to  the
    _c_o_n_d_i_t_i_o_n part of if-then-else as well as the argument of \+/1.

  o _a_t_o_m___c_h_a_r_s_/_2
    This  predicate  is now  ISO  compliant and  thus generates  a  list
    of  one-character atoms.    The behaviour  of the  old predicate  is
    available  in the  ---also ISO compliant---  atom_codes/2 predicate.
    Safest  repair is a  replacement of all  atom_chars  into atom_codes.
    If you do not want to change any source-code, you might want to use

    ____________________________________________________________________|                                                                    |

    ||user:goal_expansion(atom_chars(A,B),_atom_codes(A,B)).____________ ||

  o _n_u_m_b_e_r___c_h_a_r_s_/_2
    Same applies for number_chars/2 and number_codes/2.

  o feature/2_, set_feature/2
    These  are replaced by  the ISO  compliant current_prolog_flag/2 and
    set_prolog_flag/2.   The library  backcomp provides definitions  for
    these predicates, so no source mmuusstt be updated.

  o _A_c_c_e_s_s_i_n_g _c_o_m_m_a_n_d_-_l_i_n_e _a_r_g_u_m_e_n_t_s
    This  used  to   be  provided  by  the  undocumented  '$argv'/1  and
    Quintus  compatible library unix/1.   Now  there is also  documented
    current_prolog_flag(_a_r_g_v_, _A_r_g_v).

  o _d_u_p___s_t_r_e_a_m_/_2
    Has  been deleted.   New  stream-aliases can deal  with most of  the
    problems  for which  dup_stream/2 was  designed and  dup/2 from  the
    _c_l_i_b package can with most others.

  o _o_p_/_3
    Operators  are now llooccaall ttoo mmoodduulleess.  This implies  any modification
    of  the operator-table does  not influence other  modules.  This  is
    consistent  with the proposed ISO behaviour and a necessity  to have
    any usable handling of operators in a multi-threaded environment.

  o _s_e_t___p_r_o_l_o_g___f_l_a_g_(_c_h_a_r_a_c_t_e_r___e_s_c_a_p_e_s_, _B_o_o_l_)
    This  Prolog flag is now an interface to changing attributes  on the
    current source-module,  effectively making this flag module-local as
    well.   This is required for consistent handling of  sources written
    with  ISO (obligatory) character-escape sequences together  with old
    Edinburgh code.

  o _c_u_r_r_e_n_t___s_t_r_e_a_m_/_3 _a_n_d _s_t_r_e_a_m___p_o_s_i_t_i_o_n
    These predicates have been moved to quintus.


VVeerrssiioonn 33..44 RReelleeaassee NNootteess

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

  o _A_r_g_u_m_e_n_t _o_r_d_e_r _i_n select/3
    The  list-processing  predicate select/3  somehow  got into  a  very
    early  version of SWI-Prolog  with the wrong  argument order.   This
    has been fixed in  3.4.0.  The correct order is select(?Elem, ?List,
    ?Rest).

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

    This   library   can    be   loaded   explicitly   or   by   calling
    check_old_select/0.


VVeerrssiioonn 44..00 RReelleeaassee NNootteess

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

Some useful tricks in the integrated environment:

  o _R_e_g_i_s_t_e_r _t_h_e _G_U_I _t_r_a_c_e_r
    Using  a call to guitracer/0,  hooks are installed that replace  the
    normal command-line driven tracer with a graphical front-end.

  o _R_e_g_i_s_t_e_r _P_c_e_E_m_a_c_s _f_o_r _e_d_i_t_i_n_g _f_i_l_e_s
    From  your initialisation file.  you  can load emacs/swi_prolog that
    cause edit/1 to use the built-in PceEmacs editor.


VVeerrssiioonn 55..00 RReelleeaassee NNootteess

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

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

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

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

VVeerrssiioonn 55..11 RReelleeaassee NNootteess

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

VVeerrssiioonn 55..22 RReelleeaassee NNootteess

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

VVeerrssiioonn 55..33 RReelleeaassee NNootteess

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

VVeerrssiioonn 55..44 RReelleeaassee NNootteess

Version 5.4 consolidates the 5.3.x beta series.


VVeerrssiioonn 55..55 RReelleeaassee NNootteess

Version  5.5.x provides  support  for  _w_i_d_e _c_h_a_r_a_c_t_e_r_s  with  UTF-8  and
UNICODE I/O  (section 2.17.1).   On both 32  and 64-bit hardware  Prolog
integers are now at  minimum 64-bit integers.  If available,  SWI-Prolog
arithmetic  uses the  GNU  GMP  library to  provided  _u_n_b_o_u_n_d_e_d  integer
arithmetic  as well  as rational  arithmetic.    Adding GMP  support  is
sponsored  by Scientific  Software and  Systems Limited,  www.sss.co.nz.
This version also incorporates clp(r) by Christian  Holzbaur, brought to
SWI-Prolog by Tom Schrijvers and Leslie De Koninck (section 11.8).


VVeerrssiioonn 55..66 RReelleeaassee NNootteess

Version 5.6 consolidates the 5.5.x beta series.


VVeerrssiioonn 55..77 RReelleeaassee NNootteess

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

VVeerrssiioonn 55..1100 RReelleeaassee NNootteess

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

11..77 DDoonnaattee ttoo tthhee SSWWII--PPrroolloogg pprroojjeecctt

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

    http://www.swi-prolog.org/donate.html


11..88 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.

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

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

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

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

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

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

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

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

Markus Triska has contributed to various libraries.

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

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:

________________________________________________________________________|                                                                        |
|machine% swipl                                                          |

|Welcome to SWI-Prolog (Version \plversion)                              |
|...                                                                     |
|                                                                        |
|1|?-___________________________________________________________________ | |

After  starting Prolog,  one  normally loads  a  program into  it  using
consult/1, which  --- for historical reasons  --- may be abbreviated  by
putting the  name of  the program  file between  square brackets.    The
following  goal loads  the  file  likes.pl containing  clauses  for  the
predicates likes/2:

________________________________________________________________________|                                                                        |
|?- [likes].                                                             |
|% likes compiled, 0.00 sec, 596 bytes.                                  |

|                                                                        |
|Yes                                                                     |
|?-|____________________________________________________________________ |  |

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

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  pl  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 DOS-box.

  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  with   the  likes.pl  file  mentioned   in
section 2.1.1.1  is by simply double-clicking  this file in the  Windows
explorer.


22..11..22 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  (;) if (s)he wants  another solution, or return  if
(s)he is satisfied, after which Prolog will say YYeess.   If Prolog answers
NNoo,  it  indicates it  cannot  find any  (more)  answers to  the  query.
Finally, Prolog can answer using an error message  to indicate the query
or program contains an error.

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

|                                                                        |
|X = dahl ;                                                              |
|                                                                        |
|X = tandoori ;                                                          |
|                                                                        |
|...                                                                     |
|                                                                        |
|X = chips ;                                                             |

|                                                                        |
|No                                                                      |
|?-|____________________________________________________________________ |  |


22..22 TThhee uusseerr''ss iinniittiiaalliissaattiioonn ffiillee

After  the necessary  system  initialisation  the system  consults  (see
consult/1) the user's startup file.  The base-name  of this file follows
conventions of  the operating  system.   On MS-Windows,  it is the  file
pl.ini  and on  Unix systems  .plrc.   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__________________________||
                   || llooccaall ||.    |.                   |
                   |_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.

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

22..33 IInniittiiaalliissaattiioonn ffiilleess aanndd ggooaallss

Using  command-line  arguments (see  section  2.4),  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  an
initialisation  goal 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  -q  may be  used  to
suppress all informational messages.

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  2.10.2.1 discusses  further scripting  options  and chapter  10
discusses the  generation of runtime executables.   Runtime  executables
are  a mean  to  deliver executables  that  do  not require  the  Prolog
system.


22..44 CCoommmmaanndd--lliinnee ooppttiioonnss

The full set of command-line options is given below:

--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
    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  9.5).   Below is a typical  example of using this  feature.
    Also available as -dump-runtime-variables.

    ____________________________________________________________________|                                                                    |

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

--home=DIR
    Use DIR as home directory.  See section 9.6 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 9.4.21.1 for details.

-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.   This flag  is sometimes required  for
    smooth interaction with other applications.

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

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

--
    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..11 CCoonnttrroolllliinngg tthhee ssttaacckk--ssiizzeess

As of SWI-Prolog 5.9.8,  the default limit for the stack-sizes  is 128Mb
on 32-bit  and 256Mb  on 64-bit  hardware.   The 128Mb  limit on  32-bit
system  is the  highest possible  value and  this option  can thus  only
be used  to lower  the limit.   On  64-bit systems, the  limit can  both
be reduced  and enlarged.   See section  2.18.   Here are two  examples,
the first  reducing the local stack  limit to catch unbounded  recursion
really quickly and the second using a really big  (32Gb) global limit on
a 64-bit machine:

________________________________________________________________________|                                                                        |
|$ 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.


22..44..22 RRuunnnniinngg ggooaallss ffrroomm tthhee ccoommmmaannddlliinnee

-g _g_o_a_l
    _G_o_a_l  is executed just before entering the top level.  Default  is a
    predicate  which prints the  welcome message.   The welcome  message
    can  be 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 here:

    ____________________________________________________________________|                                                                    |
    ||%_swipl_<options>_-g_go,halt_-t_'halt(1)'_________________________ ||

-t _g_o_a_l
    Use  _g_o_a_l  as  interactive top-level  instead  of the  default  goal
    prolog/0.    _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 toplevel raises an exception, this  is printed
    as an uncaught error  and the toplevel is restarted.  This flag also
    determines the goal started  by break/0 and abort/0.  If you want to
    stop  the user from entering interactive mode start  the application
    with `-g goal' and give `halt' as top-level.


22..44..33 CCoommppiilleerr ooppttiioonnss

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

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

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

-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 .plrc (Unix)
    or pl.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 2.2.

-F _s_c_r_i_p_t
    Selects  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
    bootfile 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,  _p_a_t_h_1 _._._.  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.


22..44..44 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 _l_e_v_e_l
    Set  debug  level to  _l_e_v_e_l.    Only  has effect  if the  system  is
    compiled with the -DO_DEBUG flag.  System maintenance only.


22..55 GGNNUU EEmmaaccss IInntteerrffaaccee

The default  Prolog mode for  GNU-Emacs can be  activated by adding  the
following rules to your Emacs initialisation file:

________________________________________________________________________|                                                                        |
|(setq auto-mode-alist                                                   |

|      (append                                                           |
|       '(("\\.pl" . prolog-mode))                                       |
|       auto-mode-alist))                                                |
|(setq prolog-program-name "swipl")                                      |
|(setq prolog-consult-string "[user].\n")                                |
|;If you want this.  Indentation is either poor or I don't use           |
|;it as intended.                                                        |
|;(setq|prolog-indent-width_8)__________________________________________ |      |

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

  o http://turing.ubishops.ca/home/bruda/emacs-prolog/

  o http://stud4.tuwien.ac.at/ e0225855/ediprolog/ediprolog.html

  o http://stud4.tuwien.ac.at/ e0225855/pceprolog/pceprolog.html

  o http://stud4.tuwien.ac.at/ e0225855/etrace/etrace.html


22..66 OOnnlliinnee HHeellpp

Online  help  provides a  fast  lookup  and browsing  facility  to  this
manual.   The online  manual can show predicate  definitions as well  as
entire sections of the manual.

The online help  is displayed from the  file 'MANUAL'. The file  helpidx
provides  an index  into  this  file.    'MANUAL'  is created  from  the
LaTeX sources  with a modified version  of dvitty, using overstrike  for
printing bold  text and  underlining for  rendering italic text.    XPCE
is shipped  with swi_help,  presenting the information  from the  online
help in a hypertext  window.  The Prolog flag  write_help_with_overstrike
controls whether  or not help/1  writes its  output using overstrike  to
realise bold  and underlined  output or  not.   If this  Prolog flag  is
not  set it  is initialised  by the  help library  to true  if the  TERM
variable equals  xterm and false  otherwise.  If  this default does  not
satisfy you, add the  following line to your personal startup  file (see
section 2.2):

________________________________________________________________________|                                                                        |
|:-|set_prolog_flag(write_help_with_overstrike,_true).__________________ |  |


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 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  sec-
                           tions 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 called `history'.   The
availability of  this feature is controlled  by set_prolog_flag/2,  using
the  history Prolog  flag.   By  default,  history is  available if  the
Prolog flag  readline is  false.   To enable  this feature,  remembering
the last  50 commands,  put the  following into your  startup file  (see
section 2.2):

________________________________________________________________________|                                                                        |
|:-|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 2.1.   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.   These values  may be  reused in  further
top-level  queries as  $Var.    Only the  latest binding  is  available.
Example:
________________________________________________________________________|                                                                        |
|1 ?- maplist(plus(1), "hello", X).                                      |
|                                                                        |
|X = [105,102,109,109,112]                                               |

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

                Figure 2.1:  Reusing top-level bindings

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

________________________________________________________________________|                                                                        |

|6 ?- X = statistics.                                                    |
|                                                                        |
|X = statistics                                                          |
|                                                                        |
|Yes                                                                     |
|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             |
|                                                                        |
|Yes                                                                     |
|8|?-___________________________________________________________________ | |


22..99 OOvveerrvviieeww ooff tthhee DDeebbuuggggeerr

SWI-Prolog has a 6-port  tracer, extending the standard 4-port  Byrd box
model tracer  [Byrd, 1980, Clocksin & Melish, 1987] 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 4.9.

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.

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_print_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 5.

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 5).  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_print_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_print_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_print_options     to
    [quoted(true), attributes(write), priority(699)],          bypassing
    portray/1, etc.

The  ideal 4  port Byrd  box  model [Byrd, 1980]  as described  in  many
Prolog books  [Clocksin & Melish, 1987] 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 4.37.


22..1100 CCoommppiillaattiioonn


22..1100..11 DDuurriinngg pprrooggrraamm ddeevveellooppmmeenntt

During  program   development,  programs   are  normally  loaded   using
consult/1, or the list abbreviation.  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>                                                  |
|                                                                        |
|Yes                                                                     |
|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.


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

New in  version 4.0.5  is the possibility  to use  a Prolog source  file
directly  as a  Unix  script-file.   The  same  mechanism is  useful  to
specify additional parameters for running a Prolog file on Windows.

If the  first letter of a  Prolog file is #,  the first line is  treated
as comment.  To  create a Prolog script, make the first line  start like
this:

    #!/path/to/pl <_o_p_t_i_o_n_s> -s

Prolog recognises this  starting sequence and causes the interpreter  to
receive the following argument-list:

    /path/to/pl <_o_p_t_i_o_n_s> -s <_s_c_r_i_p_t> -- <_S_c_r_i_p_t_A_r_g_u_m_e_n_t_s>

Instead of  -s, the user may  use -f to stop  Prolog from looking for  a
personal initialisation file.

Here is a simple script doing expression evaluation:

________________________________________________________________________|                                                                        |
|#!/usr/bin/pl -q -t main -f                                             |

|                                                                        |
|eval :-                                                                 |
|        current_prolog_flag(argv, Argv),                                |
|        append(_, [--|Args], Argv),                                     |
|        concat_atom(Args, ' ', SingleArg),                              |
|        term_to_atom(Term, SingleArg),                                  |
|        Val is Term,                                                    |
|        format('~w~n', [Val]).                                          |

|                                                                        |
|main :-                                                                 |
|        catch(eval, E, (print_message(error, E), fail)),                |
|        halt.                                                           |
|main :-                                                                 |
||_______halt(1)._______________________________________________________ ||

And here are two example runs:

________________________________________________________________________|                                                                        |

|% eval 1+2                                                              |
|3                                                                       |
|% eval foo                                                              |
|ERROR: Arithmetic: `foo/0' is not a function                            |
|%|_____________________________________________________________________ | |

TThhee  WWiinnddoowwss  vveerrssiioonn supports  the  #!  construct  too,   but  here  it
serves  a rather  different role.    The  Windows shell  already  allows
the  user to  start Prolog  source files  directly  through the  Windows
file-type  association.   Windows  however makes  it rather  complicated
to provide  additional parameters, such  as the required stack-size  for
an individual  Prolog file.   The #! line  provides for this,  providing
a  more flexible  approach  than changing  the  global  defaults.    The
following starts  Prolog with unlimited stack-size  on the given  source
file:

________________________________________________________________________|                                                                        |
|#!/usr/bin/pl -L0 -T0 -G0 -s                                            |
|                                                                        |

|....|__________________________________________________________________ |    |

Note the  use of  /usr/bin/pl, which  specifies the interpreter.    This
argument is ignored in the Windows version, but  required to ensure best
cross-platform compatibility.


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  2.10.2.1),  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=pl                                                                   |
|                                                                        |
|exec $PL -f none -g "load_files(['$base/load'],[silent(true)])" \       |
||________-t_go_--_$*___________________________________________________ ||

________________________________________________________________________|                                                                        |
|go :-                                                                   |
|        current_prolog_flag(argv, Arguments),                           |
|        append(_SytemArgs, [--|Args], Arguments), !,                    |
|        go(Args).                                                       |

|                                                                        |
|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  using the linker  swipl-ld(1).
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 10.


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_...___________________________ | |

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  `Key' instantiated, it unifies  the value of the Prolog  flag.
    Flag  values are typed.   Flags marked as  bool can have the  values
    true and false.   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>                                     |
    ||________)_________________________________________________________ ||

    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  has  been created  since  the  last
         atom-garbage collection,  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().

    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
         was 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_)
         List  is a  list of  atoms  representing the  command-line  ar-
         guments  used to  invoke  SWI-Prolog.    Please note  that  aallll
         arguments are included in the list returned.

    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 9.2.3 and file_search_path/2.

    aassssoocciiaattee _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         On Windows  systems,  this  is set  to the  filename  extension
         (pl  (default) or  pro  (can  be selected  in  the  installer))
         associated with swipl-win.exe.

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

    bbaacckkqquuootteedd__ssttrriinngg _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true  (default false),  read translates  text between  back-
         quotes into a string object  (see section 4.22).  This  flag is
         mainly for compatibility with LPA Prolog.

    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 4.25.2.1.

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

    cc__llddffllaaggss _(_a_t_o_m_)
         Special linker  flags  passed to  link SWI-Prolog.    See  sec-
         tion 9.5.

    cc__lliibbss _(_a_t_o_m_)
         Libraries passed  to the C-linker  when SWI-Prolog was  linked.
         May  be  used to  determine  the  libraries  needed  to  create
         statically linked extensions for SWI-Prolog.  See section 9.5.

    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.

    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 the console  supports
         menus.  See also section 4.33.2.

    ccppuu__ccoouunntt _(_i_n_t_e_g_e_r_, _c_h_a_n_g_e_a_b_l_e_)
         Number of  physical CPUs in  the system.   Unfortunately  there
         is  no standard  to  get  this number,  so  on  most  operating
         systems this flag  is not available.   It is marked  read-write
         both  to  allow  obtaining  this  value  later   and  to  allow
         pretending the system  has more or less  processors.  See  also
         thread_setconcurrency/2 and the library thread.  Currently this
         flag is  supported in Windows  and Linux  if /proc is  enabled.
         If  you can  provide  us with  a  C-code fragment  getting  the
         number for a specific  OS, please submit an enhancement  report
         at http://gollem.science.uva.nl/bugzilla/

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

    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 fileerrors/2  and  the
         Prolog flag report_error.   May be changed.   Default is  true,
         except for the runtime version.

    ddeebbuuggggeerr__pprriinntt__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--- maintained  for each
         module.    If codes  (default), a  list  of character-codes  is
         returned,  if chars  a list  of  one-character atoms,  if  atom
         double  quotes  are the  same  as  single-quotes  and  finally,
         string reads the text into a Prolog string  (see section 4.22).
         See also atom_chars/2 and atom_codes/2.

    eeddiittoorr _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         Determines the  editor used  by edit/1.   See  section 4.4  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 2.17.1 for details.

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

    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.

    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.

    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.   The  predicate load_files/2 restores  the value  of
         this  flag  after loading  a  file,  causing  modifications  to
         be  local to  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 9.4.8.

    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  2.7.    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 return a  float, even  if
             applied to integers that can be divided.

           o In  the standard order  of terms (see  section 4.6.1),  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.

    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 to access 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.

    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 4.25.2.1.

    mmaaxx__ttaaggggeedd__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Maximum integer value represented as a `tagged' value.   Tagged
         integers  require  1  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 4.25.2.1.

    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.

         Currently   optimise   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).

    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.

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

    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 _(_b_o_o_l_)
         If true, SWI-Prolog is linked with the readline library.   This
         is  done by  default  if you  have  this library  installed  on
         your system.    It  is also  true for  the Win32  swipl-win.exe
         version of SWI-Prolog, which realises a subset  of the readline
         functionality.

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

    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 9.4.21.1 for details.

    ssyysstteemm__tthhrreeaadd__iidd _(_i_n_t_)
         Available  in  multi-threaded version  (see  section  8)  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.

    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 equal  to 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.

    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 convert_time/2.

    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 substution.   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)).__________________________________________________ | |

    ttoopplleevveell__pprriinntt__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__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 2.8.

    ttrraaccee__ggcc _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If  true  (false  is  the  default),  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|_

    ttttyy__ccoonnttrrooll _(_b_o_o_l_)
         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.  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.

    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 predicates  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 inherits  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  adviced  to  keep  the
         error default and  use dynamic/1 and/or multifile/1 to  specify
         possible non-existence of a predicate.

    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.

    vveerrbboossee _(_A_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         This flags 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 _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If false normal consult  messages will be suppressed.   Default
         is true.  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
         Note  that  in   releases  up  to   2.7.10  this  Prolog   flag
         yielded an atom  holding the three  numbers separated by  dots.
         The  current representation  is  much easier  for  implementing
         version-conditional statements.

    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 13.  _E_x_t_r_a  provides platform specific
         version information.  Currently it is simply unified to [].

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

    wwiinnddoowwss _(_b_o_o_l_)
         If present and true, the operating system  is an implementation
         of Microsoft  Windows (NT/2000/XP, etc.).    This flag is  only
         available on MS-Windows based versions.

    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.


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.

    Originally,  SWI-Prolog's  set_prolog_flag/2 created  a  new  Prolog
    flag  if the  flag _K_e_y  did not  exist.    It still  does this,  but
    now  prints a warning.    New code must  use create_prolog_flag/3 to
    introduce  new flags.   Future versions  are likely to replace  this
    printed warning with an existence error.


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 following options:

    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.

    This  predicate  behaves as  set_prolog_flag/2 if the  flag  already
    exists.  See also user_flags.


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 _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 system).

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

  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 _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 _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 some 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 _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 _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
    Defines 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 6.1 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.  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/2verbose_autoload is  provided
to  get verbose  loading.    The Prolog  flag autoload  can  be used  to
enable/disable the auto-load system.

Autoloading  only handles  (library) source  files that  use the  module
mechanism  described  in  chapter  5.     The  files   are  loaded  with
use_module/2 and only the  trapped undefined predicate will be  imported
to 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 a completely indexed library directory.

________________________________________________________________________|                                                                        |

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

If  there  are  more than  one  library  files  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.


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.


22..1144 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..1155 SSyynnttaaxx NNootteess

SWI-Prolog  syntax is  close to  ISO-Prolog  standard syntax,  which  is
closely compatible with Edinburgh Prolog syntax.  A  description of this
syntax can be found in the Prolog books referenced  in the introduction.
Below are some  non-standard or non-common constructs that are  accepted
by SWI-Prolog:

  o /* .../* ...*/ ...*/
    The  /* ...*/  comment statement  can be  nested.    This is  useful
    if  some  code with  /* ...*/  comment statements  in it  should  be
    commented out.


22..1155..11 IISSOO SSyynnttaaxx SSuuppppoorrtt

SWI-Prolog offers ISO compatible extensions to the Edinburgh syntax.


22..1155..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
use UCS/Unicode as  provided by the C-library  wchar_t based  primitives.
See also section 2.17.


22..1155..11..22 CChhaarraacctteerr EEssccaappee SSyynnttaaxx

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

\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.  For compatibility with
    Quintus Prolog.  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')________ ||

\<RETURN>
    No  output.  Skips input to the next non-layout character or  to the
    end  of the next line.  ISO  demands skipping only the newline.   We
    advice  to use \c or  put 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')______________ ||

\e
    Escape character (ASCII 27).

\f
    Form-feed character.

\n
    Next-line character.

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

\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 of all, 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.

\<_c_h_a_r_a_c_t_e_r>
    Any  character immediately preceded  by a \  and not covered by  the
    above  escape sequences is copied verbatim.   Thus, '\\' is  an atom
    consisting  of a single \ and  '\'' and '''' both describe the  atom
    with a single '.

Character      escaping      is     only      available      if      the
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  character
escapes  handling by  read has  already interpreted  as  32 (40  octal).
Also, \l is translated to  a single `l'.  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..1155..11..33 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..1155..11..44 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 3.1.3.

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 2.15.1.2) 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..1155..11..55 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 a variable  is known 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).__|__________________________________________________________|_


22..1166 IInnffiinniittee ttrreeeess ((ccyycclliicc tteerrmmss))

SWI-Prolog  has  limited support  for  infinite  trees,  also  known  as
cyclic  terms.   Full  support  requires special  code in  all  built-in
predicates that require  recursive exploration of a  term.  The  current
version  supports cyclic  terms  in  the pure  Prolog  kernel  including
the  garbage  collector  and  in  the  following   predicates:    =../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,4],
recorda/3,  recordz/3,   setof/3,  term_variables/2,  throw/1,   when/2,
write/1 (incomplete) .


22..1177 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-bits 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 4.22).   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 section 9 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..1177..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 influence 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  3.1.3  for  writing  Prolog
files  with non-US-ASCII  characters  and  section 2.15.1.4  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 write  the characters using Prolog  escape sequences while  other
streams generate an I/O exception.


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

From  section  2.17.1,  you  may  have  got  the  impression  text-files
are  complicated.   This  section  deals with  a related  topic,  making
live  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 of 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 telling 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..1188 SSyysstteemm lliimmiittss


22..1188..11 LLiimmiittss oonn mmeemmoorryy aarreeaass

SWI-Prolog has  a number of  memory areas which are  only enlarged to  a
certain limit.   The  default sizes for these  areas should suffice  for
most applications, but big  applications may require larger ones.   They
are  modified by  command-line options.    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 local-,  global- and  trail-stack are  limited to 128  Mbytes on  32
bit processors,  or more  generally to  2 to the power bits-per-long - 5
bytes.

The  PrologScript facility  described  in  section 2.10.2.1  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.
       ___________________________________________________________
       |_Option_|Default_|Area_name______|Description____________|_||-L||16Mlloocc||aallTssttaacckkhe|l||||ocal|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   | 32M   |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   | 32M   |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 ||
       ||| -A   |||1M   |||aarrgguummeenntt ssttaacc||norkkneeded||any||longer.Th|e||argument stack  is

       |        |        |               used || to   store   one |
       |        |        |               of   ||the   intermediate|
       |        |        |               code ||interpreter's reg-|
       |        |        |               ister||s.     The  amount|
       |        |        |               of sp||ace needed on this|
       |        |        |               stack||is determined en- |
       |        |        |               tirel||y by the  depth in|

       |        |        |               which||terms  are nested |
       |        |        |               in  t||he   clauses  that|
       |        |        |               const||itute the program.|
       |        |        |               Overf||low is most likely|
       |        |        |               when ||using long strings|
       |        |        |               in a ||clause.           |
       |        |        |               In ad||dition, this stack|
       |        |        |               is us||ed by  some built-|
       |        |        |                    ||                  |
       |        |        |               in pr||edicates to handle|

       |        |        |               cycli||c terms.   Its de-|
       |        |        |               fault|| size   limit  is |
       |        |        |               propo||rtional   to   the|
       |        |        |               globa||l stack limit such|
       |        |        |               that || it  will   never |
       |________|________|_______________overf||low.______________|_

                        Table 2.2:  Memory areas


22..1188..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.   As of  SWI-Prolog
2.8.5, no limits are  imposed on the addresses returned by  malloc() and
friends.

On  some machines,  the  runtime stacks  described above  are  allocated
using `sparse  allocation'.   Virtual space up to  the limit is  claimed
at startup and committed and released while the area  grows and shrinks.
On Win32  platform this  is realised using  VirtualAlloc() and  friends.
On Unix systems this is realised using mmap().


22..1188..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  sizes  of  atoms
    and  strings.   read/1  and its derivatives  however normally  limit
    the  number  of newlines  in  an  atom or  string  to 5  to  improve
    error  detection  and recovery.    This  can  be switched  off  with
    style_check/1.

    The  number  of  atoms  is  limited  to  16777216  (16M)  on  32-bit
    machines.   On  64-bit machines  this is virtually  unlimited.   See
    also section 9.4.2.1.

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  Many build-in  predicates process  nested terms  using
    recursive  C functions.  Too  deeply nested terms generally cause  a
    fatal crash.   All these functions avoid recursion on the right-most
    argument  and therefore terms are  not limited on the nesting  level
    of  the  last argument.    This notably  covers long  lists.    Most
    functions  use  a  stack  for correct  handling  of  rational  trees
    (cyclic  terms).  This stack is segmented, where  different segments
    are allocated using malloc().  Overflow causes a non-graceful exit.

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 clauses and records
    the difference is much smaller.

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

22..1188..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 [Pereira, 1986] all predicates,  database
keys, etc. that should  be hidden from the user start with a  dollar ($)
sign (see style_check/1).


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

SWI-Prolog support for  64-bit machines started with version 2.8  on DEC
Alpha  CPUs running  Linux.   Initially  64-bit  hardware was  developed
to  deal  with  the  addressing  demands  of  large  databases,  running
primarily on  expensive server hardware.   Recently  (2007) we see  CPUs
that support  64-bit addressing become  commonplace, even in  low-budget
desktop hardware.   Most todays 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..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

On  Unix  systems,  64-bit addressing  is  configured  using  configure.
Traditionally,  both  long and  void*  are  64-bits on  these  machines.
Version  5.6.26 introduces  support for  64-bit  MS-Windows (Windows  XP
and Vista  64-bit editions) on  amd64 (x64) hardware.   Win64 uses  long
integers of only  32-bits.  Version  5.6.26 introduces support for  such
platforms.


22..1199..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 than  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  128MB 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
todays CPUs and operating  systems.  This implies Prolog can  be started
with stacks sizes that use the full capabilities of your hardware.

Multi-threaded applications profit much more.   SWI-Prolog threads claim
the full stacksize limit in _v_i_r_t_u_a_l _a_d_d_r_e_s_s _s_p_a_c_e and  each thread comes
with its  own set  of stacks.    This approach  quickly exhaust  virtual
memory  on  32-bit systems  but  poses  no problems  when  using  64-bit
addresses.

The implications  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 is appears that the  loss is compensated for by  a
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.   Current  SWI-Prolog
(5.6.26) runs at practically the same speed on IA32 and AMD64.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss 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 the different characteristics of Prolog become important.

Prolog  applications  that  require more  than  the  128MB  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 to use  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.  Virtual memory  usage of SWI-Prolog
is roughly  the program size  (_h_e_a_p) plus the  sum of the  stack-limits.
If there are  multiple threads, each thread  has its own stacks and  the
stack-limits must be summed over the running threads.

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  128MB
per  stack,  use the  64-bit  edition.    If applications  approach  the
size  of physical  memory,  fit in  the  128MB 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 wants to explain 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 3.1 and section 3.2 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 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 their 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.

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 their
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  hitting the file-system  it uses prolog_to_os_filename/2 to
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  and finally 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))._______________________________ |                         |

For  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  using   use_module/1   calls  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  3.1.1.1).
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  call qsave_program/2to 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  2.17,  SWI-Prolog  supports   international
character  handling.   Its  internal encoding  is  UNICODE. I/O  streams
convert  to/from this  internal format.    This  sections discusses  the
options for source-files not in US-ASCII.

SWI-Prolog  can  read  files  in  any  of  the  encodings  described  in
section 2.17.    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  be using the  same _l_o_c_a_l_e or  the file is  unreadable.   There
    is  no elegant 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
    two ways of  this encoding, using a UTF-8 _B_O_M (see section 2.17.1.1)
    or  using  the  directive  :- encoding(utf8)..    Many  todays  text
    editors,  including PceEmacs,  are capable  of editing UTF-8  files.
    Projects  that started  using local conventions  can be be  re-coded
    using  the Unix iconv tool or often using a 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  have been  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 then 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  but the  name and  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 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 good understanding of resolution of terms to  predicates inside a
module is required.  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
down  Prolog  source  code.    Editors  are  complicated  programs  that
must  be mastered  in  detail for  real  productive programming  and  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 (see section 4.4).

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 normally aborts  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.  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.   Their 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/pl
    If  the  file  is a  _P_r_o_l_o_g  _S_c_r_i_p_t  file, starting  with  the  line
    #!/path/to/pl options -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 (y)ou  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 for next forwards.

    Control-R
         Search for next backwards.

    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  is  an important  feature of  Emacs clones  to
    support  programming.   After  typing the  first few  letters of  an
    identifier  you may hit Alt-/, causing PceEmacs to  search backwards
    for  identifiers that start  the same and  using 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 very fast  entering code
    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,  Hit 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  of 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 were the  most commonly used commands.   In section section  3.4.3
we discuss specific support for dealing with Prolog source code.


33..44..33 PPrroolloogg MMooddee

In  the previous  section (section  3.4.2) 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 CCcheck 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 commands  re-centers the window (scrolls the window to
    make  the caret the  center of  the window).   Hitting 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 for 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 3.4.3.
          _____________________________________________________
          |______________________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 not-defined 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 12.

Window-based tracing  provides 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 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 3.8.


33..77 CCrroossss rreeffeerreenncceerr

A  cross-referencers is  a  tool  examining the  caller-callee  relation
between predicates  and using this  information to explicate  dependency
relations between  source files, find  calls to non-existing  predicates
and predicates  for which no  callers can be  found.   Cross-referencing
is useful during  program development, reorganisation, cleanup,  porting
and  other program  maintenance tasks.    The dynamic  nature of  Prolog
makes the  task non-trivial.   Goals can  be created dynamically  call/1
after construction  of a  goal term.   Abtract  interpretation can  find
some  of such  calls, but  the ultimately  they can  come from  external
communication, making  it completely 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 11.19 and the XPCE

library pce_xref provides a graphical frontend 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 file  search path.   All  loaded files that  fall
outside these  categories are  below the  last branch  called /.    File
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 allows to edit 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 menu-command Header 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 their  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  will  be 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 \index{@prolog_ide}\objectname{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 3.6)  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
         Opens  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 _t_o _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  users
    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
    prolog_edit:edit_source/1.

  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 PrologNavigator.

  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 fully instantiated to a term that

            satisfies  the required argument  type.   Think of
            the argument as _i_n_p_u_t.
         -  Argument must  be unbound.   Think of the argument
            as _o_u_t_p_u_t.

         ?  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.
            E.g.  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

            section 5 for more information on module-handing.
         @  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 4.11),  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>/<arity+2>,  regardless on  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-bits  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.   I.e.,  if  get_code/1 reads from  a  stream encoded  as
KOI8-R (used  for the Cyrillic alphabet),  it returns the  corresponding
Unicode  code-points.     Similar,   assembling  or  deassembling  atoms
using  atom_codes/2  interprets the  codes  as  Unicode  points.     See
section 2.17.1 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 characters 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 are are  atom_chars/2,  atom_codes/2,
number_codes/2 and number_chars/2.   For character I/O on streams  there
is  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.   They are normally  loaded
    using consult/1 or ensure_loaded/1.

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

 AAnn iinncclluuddee   Prolog source file is loaded using the include/1 directive
    and normally contains only directives.

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
[Clocksin & Melish, 1987].   The user may define additional  compilation
of the source  file by defining the  dynamic predicates term_expansion/2
and  goal_expansion/2.     Transformations by  term_expansion/2  overrule
the systems  grammar rule  transformations.   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.

Directives  may be  placed  anywhere  in a  source  file,  invoking  any
predicate.    They are  executed when  encountered.    If the  directive
fails, a warning is printed.  Directives are specified  by :-/1 or ?-/1.
There is no difference between the two.

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.


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

    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.

    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  2.17.1
         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, 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 a  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_s 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.

    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 explicitely

         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 this  load_file/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 used 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
         that starts interaction  with the user.   Ask is only  provided
         if 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.

    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  remove all clauses  if the data  is
         re-consulted.

         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 other objects than  files.  See  prolog_load_file/2for  a
    description and http_load for an example.


ccoonnssuulltt((_:_F_i_l_e))
    Read _F_i_l_e as a Prolog  source file.  _F_i_l_e may be a list of files, in
    which  case all members are consulted in turn.  _F_i_l_e may  start with
    the  Unix shell special  sequences ~,  <_u_s_e_r> and $<_v_a_r>.  _F_i_l_e  may
    also be library(Name),  in which case the libraries are searched for
    a  file with the specified  name.  See  also library_directory/1 and
    file_search_path/2.  consult/1  may be abbreviated by just  typing a
    number of file names in a list.  Examples:

        ?- consult(load).       % consult load or load.pl
        ?- [library(quintus)].  % load Quintus compatibility library
        ?- [user].

    The  predicate  consult/1 is  equivalent  to load_files(Files,  []),
    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.


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 the semantics, we  hope to get as closely 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))
    Pretend  the  terms   in  _F_i_l_e  are  in  the  source-file  in  which
    :- include(File)  appears.  The  include construct is only  honoured
    if  it appears  as  a directive  in a  source-file.   Normally  _F_i_l_e
    contains a sequence of directives.


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 2.17.1.


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  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  2.13) 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  assert/1,
    asserta/1 or remove system defaults using retract/1.


ffiillee__sseeaarrcchh__ppaatthh((_+_A_l_i_a_s_, _?_P_a_t_h))
    Dynamic  predicate used to specify `path-aliases'.  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>)  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
    load_foreign_library/[1,2].

    ____________________________________________________________________|                                                                    |

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

    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))
    Unifies  _P_a_t_h  with   all  possible  expansions  of  the  file  name
    specification _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, _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  used 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))
    Is  true  if  the  predicate  specified  by  _P_r_e_d  was  loaded  from
    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.
    See also clause_property/2.


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  disassociates  it  from  the
    file.     _F_i_l_e  is  a  canonical  file-name.     See  source_file/1,
    module_property/2 and absolute_file_name/3.

    This  predicare shall be used with care.  The  multi-threaded nature
    of  SWI-Prolog makes removing  static code unsafe.   Attempts to  do
    this  should  be reserved  to 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.      See   also
    source_location/2 and if/1.  The following keys are defined:

      ________________________________________________________________
      |__KKeeyy______________________||DDeessccrriippttiioonn________________________________________________________________________||
      || module        |Module into which file is loaded               |

      | source        |File loaded.  Returns  the original Prolog file|
      |               |when  loading a  .qlf file.    Compatible  with|
      |               |SICStus Prolog.                                |
      | file          |Currently  equivalent to  source.    In  future|
      |               |versions it  may report a different  values for|
      |               |files being loaded using include/1.            |
      | stream        |Stream identifier (see current_input/1)        |
      | directory     |Directory in which source lives.               |

      | dialect       |Compatibility mode.  See expects_dialect/1.    |
      | term_position |Position of last  term read.  Term of  the form|
      |               |'$stream_position'(0,<_L_i_n_e>,0,0,0).    See  also|
      |               |stream_position_data/3.                        |
      | script        |Boolean  that  indicates whether  the  file  is|
      |_______________|loaded_as_a_script_file_(see_-s).______________|

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

    ____________________________________________________________________|                                                                    |
    | :- 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.


::-- 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.

    Upto  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  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  program-text.  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 state.


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 then the read term (_T_e_r_m_1).  _T_e_r_m_2  may be a
    term of the form `?-  _G_o_a_l' or `:- _G_o_a_l'.  _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 5 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  three
    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 4.3.1.1.

     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 DGC 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-
    expansion  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 on the user module.  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 user.

    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.


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
    compiled  the argument clauses  into static predicates,  associating
    the  predicates with the current file but avoid changing  the notion
    of current predicate and therefore discontiguous warnings.


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.


pprreepprroocceessssoorr((_-_O_l_d_, _+_N_e_w))
    Read   the  input  file  via  an  external  process  that   acts  as
    preprocessor.   A preprocessor is specified  as an atom.   The first
    occurrence  of the string `%f' is  replaced by the name of the  file
    to  be loaded.  The standard output of resulting command  is loaded.
    To use the Unix C preprocessor one should define:

    ____________________________________________________________________|                                                                    |
    | ?- preprocessor(Old, '/lib/cpp -C -P %f'), consult(...).           |

    |                                                                    |
    ||Old_=_none________________________________________________________ ||

    Using cpp for  Prolog preprocessing is not ideal as the tokenization
    rules  for comment and quoted  strings differ between C and  Prolog.
    Another  problem is  availability and compatibility  with regard  to
    option processing of cpp.


44..33..11..11 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 13 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 LLooaaddiinngg ffiilleess,, aaccttiivvee ccooddee aanndd tthhrreeaaddss

Traditionally,  Prolog environments  allow for  reloading files  holding
currently active code.   In particular, the following sequence  is 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 using the rr command

Goals running  during the  reload keep  running on  the old  definition,
while new  goals use  the reloaded definition,  which is  why the  _r_e_t_r_y
must be used _a_f_t_e_r the reload.  This implies  that clauses of predicates
that are  active during  the reload  cannot be  reclaimed.   Normally  a
small amount of dead clauses should not be an  issue during development.
Such clauses can be reclaimed with garbage_collect_clauses/0.


ggaarrbbaaggee__ccoolllleecctt__ccllaauusseess
    Cleanup  all _d_i_r_t_y  predicates, where  dirty predicates are  defined
    to  be predicates  that have  both old  and new  definitions due  to
    reloading  a  source  file while  the  predicate  was active.     Of
    course,  predicates that are  active using garbage_collect_clauses/0
    cannot  be reclaimed and remain _d_i_r_t_y.   Predicate are -like  atoms-
    shared resources and  therefore all threads are suspended during the
    execution of this predicate.


44..33..22..11 TThhrreeaaddss aanndd rreellooaaddiinngg rruunnnniinngg ccooddee

As of version 5.5.30, there is basic thread-safety  for reloading source
files while  other threads are  executing code  defined in these  source
files.   Reloading a file freezes  all threads after marking the  active
predicates originating from  the file being reloaded.   The threads  are
resumed after the file  has been loaded.  In addition,  after completing
loading the outermost file, the system runs garbage_collect_clauses/0.

What does that mean?   Unfortunately it does _n_o_t mean we  can `hot-swap'
modules.   Consider the case where thread  A is executing the recursive
predicate P.   We `fix'  P and reload.   The already  running goals for
P  continue to  run the  old definition,  but new  recursive calls  will
use the  new definition!   Many  similar cases  can be constructed  with
dependent predicates.

It provides  some basic security for  reloading files in  multi-threaded
applications during  development.   In  the above  scenarios the  system
does not crash  uncontrolled, but behaves like  any broken program:   it
may return the wrong bindings, wrong truth value or raise an exception.

Future versions  may have  an `update now'  facility.   Such a  facility
can be implemented  on top of the _l_o_g_i_c_a_l  _u_p_d_a_t_e _v_i_e_w.  It would  allow
threads to do a controlled update between processing independent jobs.


44..33..33 QQuuiicckk llooaadd ffiilleess

SWI-Prolog supports compilation of individual or  multiple Prolog source
files into `Quick Load Files'.  A `Quick Load  Files' (.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 4.3.   If consult is given  the explicit .pl file, it will  load
the Prolog  source.  When  given the .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  base name 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(true), ...])   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  2.10
    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 LLiissttiinngg aanndd 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 _t_h_e _e_d_i_t_o_r.

Any of  these parts may  be extended or redefined  by adding clauses  to
various multi-file  (see multifile/1) predicates  defined in the  module
prolog_edit.

The built-in  edit specifications for  edit/1 (see prolog_edit:locate/3)
are described below.

   ___________________________________________________________________
   |__________________________________________FFuullllyy__ssppeecciiffiieedd__oobbjjeeccttss____________________________________________||
   || <_M_o_d_u_l_e>:<_N_a_m_e>/<_A_r_i_t_y>R|efers 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 this predicate in any module      |
   | <_N_a_m_e>                |Refers  to  (1) 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  exploits prolog_edit:locate/3 to 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.


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 at  with  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 base-name  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  multi-file 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/dotplrc   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 edit_source/1), without  the full  path
    specification,  and without  possible (exe) extension.   _C_o_m_m_a_n_d  is
    an  atom describing  the command.   The  pattern %f  is replaced  by
    the  full file-name  of the  location, and  %d by  the line  number.
    If  the  editor can  deal with  starting at  a specified  line,  two
    clauses  should be provided,  one holding only  the %f pattern,  and
    one holding both patterns.

    The  default contains  definitions for vi,  emacs, emacsclient,  vim
    and notepad (latter without line-number version).

    Please contribute your specifications to jan@swi.psy.uva.nl.


pprroolloogg__eeddiitt::llooaadd
    Normally  not-defined  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))._________________________ ||


lliissttiinngg((_+_P_r_e_d))
    List  specified predicates  (when an  atom is  given all  predicates
    with  this name will  be listed).   The listing  is produced on  the
    basis of the  internal representation, thus losing user's layout and
    variable name information.  See also portray_clause/1.


lliissttiinngg
    List all predicates of the database using listing/1.


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..55 VVeerriiffyy TTyyppee ooff aa TTeerrmm


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 9.4.7.


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  4.22, Text
    in double quotes  such as "hello" creates a _l_i_s_t of _c_h_a_r_a_c_t_e_r _c_o_d_e_s.
    We illustrate the issues in the example queries below.

    ____________________________________________________________________|                                                                    |
    | ?- write("hello").                                                 |

    | [104, 101, 108, 108, 111]                                          |
    | ?- string("hello").                                                |
    | No                                                                 |
    | ?- is_list("hello").                                               |
    ||Yes_______________________________________________________________ ||


aattoommiicc((_+_T_e_r_m))                                                     _[_I_S_O_]
    True  if  _T_e_r_m is  bound to  an atom,  string,  integer or  floating
    point  number.  Note that string  refers to the built-in type.   See
    string/1.    Strings in  the classical  Prolog sense  are lists  and
    therefore compound.


ccoommppoouunndd((_+_T_e_r_m))                                                   _[_I_S_O_]
    True  if _T_e_r_m is bound to a  compound term.  See also  functor/3 and
    =../2.


ccaallllaabbllee((_+_T_e_r_m))
    True  if _T_e_r_m is bound to an atom  or a compound term, so it  can be
    handed without type-error to call/1, functor/3 and =../2.


ggrroouunndd((_+_T_e_r_m))
    True if _T_e_r_m holds no free variables.


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 2.16.


aaccyycclliicc__tteerrmm((_+_T_e_r_m))
    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 2.16.


44..66 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.  See also dif/2.


44..66..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 <_A_t_o_m_s <_S_t_r_i_n_g_s <_C_o_m_p_o_u_n_d _T_e_r_m_s

 2. Variables  are  sorted  by  address.     Attaching  attributes  (see
    section 6.1) does not affect the ordering.

 3. _A_t_o_m_s are compared alphabetically.

 4. _S_t_r_i_n_g_s are compared alphabetically.

 5. _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.

 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.


_+_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))
    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..66..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 goals below:

    ____________________________________________________________________|                                                                    |
    | 1 ?- A = f(A).                                                     |

    |                                                                    |
    | A = f(f(f(f(f(f(f(f(f(f(...))))))))))                              |
    | 2 ?- unify_with_occurs_check(A, f(A)).                             |
    |                                                                    |
    ||No________________________________________________________________ ||

    I.e.   the  first  creates  a  _c_y_c_l_i_c_-_t_e_r_m,  which  is   printed  as
    an  infinitely   nested  f/1  term  (see  the  max_depth  option  of
    write_term/2).  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.


_+_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 visa-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.   Unlike  ==, the variant  implementation does not  benefit
    from sharing subterms.

    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.


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
    handles 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..77 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_atom/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
    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 choice  points of  parent frame  and frames  created
    after the parent frame.   As of SWI-Prolog 3.3, the semantics of the
    cut  are compliant with  the ISO  standard.   This implies that  the
    cut  is transparent to ;/2, ->/2  and *->/2.  Cuts appearing  in the
    _c_o_n_d_i_t_i_o_n  part of ->/2 and  *->/2 as well  as in \+/1 are local  to
    the condition.

             t1 :- (a, !, fail ; b).        % cuts a/0 and t1/0
             t2 :- (a -> b, !  ; c).        % cuts b/0 and t2/0
             t3 :- call((a, !, fail ; b)).  % cuts a/0
             t4 :- \+(a, !, fail ; b).      % cuts 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  (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 defines by:

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

_:_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 _A *-> _B, i.e.  without an _E_l_s_e branch, is  translated
    as the normal conjunction _A, _B.


\+ _:_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..88 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_, _._._.))
    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, which implies
    that  redefinition as  a predicate has  no effect.   The  predicates
    call/[2-6]  are defined as real  predicates, so they can be  handled
    by interpreted code.


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]) will  call
    plus(1, 2, X).   apply/2 is  incorporated in the virtual machine  of
    SWI-Prolog.   This implies that the overhead can be compared  to the
    overhead  of call/1.  New code should use call/[2..]   if the length
    of _L_i_s_t is  fixed, which is more widely supported and faster because
    there is no need to build and examine the argument list.


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_]
    Defined as:

    ____________________________________________________________________|                                                                    |
    | once(Goal) :-                                                      |
    ||________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 are identical:

    ____________________________________________________________________|                                                                    |
    | 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  inlined  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   realise
    techniques  like  _i_t_e_r_a_t_i_v_e _d_e_e_p_e_n_i_n_g.    It  was implemented  after
    discussion with Steve Moyle smoyle@ermine.ox.ac.uk.


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.

    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
    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 of 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..99 IISSOO ccoommpplliiaanntt EExxcceeppttiioonn hhaannddlliinngg

SWI-Prolog defines the predicates catch/3 and throw/1  for ISO compliant
raising  and catching  of exceptions.    In  the current  implementation
(4.0.6), most of  the built-in predicates generate exceptions,  but some
obscure predicates merely print a message, start the  debugger and fail,
which was the normal behaviour before the introduction 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 very  comparable
    to  call/1.  Recovery from  an exception is much slower,  especially
    if the exception-term is large due to the copying thereof.


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 throw/1 to 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  making a  copy of _E_x_c_e_p_t_i_o_n  and
    backtracking  until it actually found 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 share variables.   We
    assume this to be  highly unlikely and could not think of a scenario
    where this is useful.

    If  an exception is raised in a callback from C (see chapter  9) and
    not  caught in the same call-back,  PL_next_solution()fails and  the
    exception context can be retrieved using PL_exception().


44..99..11 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 an non-interactive  callback 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 analysing 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..99..22 TThhee eexxcceeppttiioonn tteerrmm

Built-in  predicates generates  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..99..33 PPrriinnttiinngg mmeessssaaggeess

The predicate print_message/2 may be  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.    The most  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  defined 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 to  print messages,  notably
    from  exceptions  in  a human-readable  format.    _K_i_n_d  is  one  of
    informational,   banner,  warning,  error,   help  or  silent.     A
    human-readable message is printed to the stream user_error.

    If   the  Prolog  flag  verbose   is  silent,  messages  with   _K_i_n_d
    informational, or banner are treated as silent.  See -q.

    This  predicate first translates  the _T_e_r_m into  a list of  `message
    lines'  (see print_message_lines/3for  details).  Next it  will call
    the hook  message_hook/3to allow the  user intercepting the message.
    If  message_hook/3 fails it  will print 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 report errors  from your own predicates,  we advise you  to
    stick  to the existing error terms  if you can; but should  you need
    to  invent new ones, you can define corresponding error  messages by
    asserting clauses for  prolog:message.  You will need to declare the
    predicate as multifile.

    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 argument.
         Handed to format/3.

    flush
         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.

    at_same_line
         If this  appears as  first element,  no prefix  is printed  for
         the first line  and the line-position is  not forced to 0  (see
         format/1, ~N).

    <_F_o_r_m_a_t>
         Handed to format/3 as format(Stream, Format, []).

    nnll
         A new line  is started and if  the message is not complete  the
         _P_r_e_f_i_x is printed too.

    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 should  be defined  dynamic and  multifile to  allow
    other modules defining clauses for it too.


mmeessssaaggee__ttoo__ssttrriinngg((_+_T_e_r_m_, _-_S_t_r_i_n_g))
    Translates  a message-term into a string object (see  section 4.22).
    Primarily  intended  to  write  messages to  Windows  in  XPCE  (see
    section 1.5) or other GUI environments.


44..99..33..11 PPrriinnttiinngg ffrroomm lliibbrraarriieess

Libraries should _n_o_t  use format/3 or other output predicates  directly.
Libraries that print  informational output directory to the console  are
hard to use from code  that depend on your textual output, such as  a GI
script.   The  predicates in section  4.9.3 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  te
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., 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  commandline option -q, the user can  disable all
_i_n_f_o_r_m_a_t_i_o_n_a_l messages.


44..1100 HHaannddlliinngg ssiiggnnaallss

As  of  version  3.1.0,   SWI-Prolog  is  capable  to   handle  software
interrupts  (signals) in  Prolog as  well as  in foreign  (C) code  (see
section 9.4.13).

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   asynchronous
inter-process 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 inter-process  (or
inter-thread) 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 the
    <_N_a_m_e>/1  in  the 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 is explained below.

    Two  predicate-names have  special meaning.    throw implies  Prolog
    will  map  the  signal  onto  a Prolog  exception  as  described  in
    section  4.9.   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 structure

         error(signal(<_S_i_g_N_a_m_e>, <_S_i_g_N_u_m>), <_C_o_n_t_e_x_t>)

    The  signal  names are  defined  by the  POSIX standard  as  symbols
    of  the form  SIG<_S_I_G_N_A_M_E>.   The  Prolog name for  a signal  is the
    lowercase  version of <_S_I_G_N_A_M_E>.  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).


44..1100..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 9.4.13  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..1111 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 as for  generating a flat list from a term.   Unfortunately,
Definite  Clause  Grammar (DCG)  handling  is  not part  of  the  Prolog
standard.   Most Prolog  engines implement DCG,  but the details  differ
slightly.

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  argument to each term  for
representing the difference list.   We will illustrate the  behaviour by
defining a rule-set for parsing an integer.

________________________________________________________________________|                                                                        |
|integer(I) -->                                                          |

|        digit(D0),                                                      |
|        digits(D),                                                      |
|        { number_chars(I, [D0|D])                                       |
|        }.                                                              |
|                                                                        |
|digits([D|T]) -->                                                       |
|        digit(D), !,                                                    |
|        digits(T).                                                      |

|digits([]) -->                                                          |
|        [].                                                             |
|                                                                        |
|digit(D) -->                                                            |
|        [D],                                                            |
|        { code_type(D, digit)                                           |
||_______}._____________________________________________________________ ||

The  body of  a grammar  rule  can contain  three  types of  terms.    A
compound  term interpreted  as a  reference  to a  grammar-rule.    Code
between {...}  is interpreted  as a  reference to  ordinary Prolog  code
and finally,  a list  is interpreted  as a  sequence of literals.    The
Prolog control-constructs (\+/1,  ->/2, ;//2, ,/2  and !/0) can be  used
in grammar rules.

Grammar rule-sets are called using the built-in  predicates phrase/2 and
phrase/3:


pphhrraassee((_+_R_u_l_e_S_e_t_, _+_I_n_p_u_t_L_i_s_t))
    Equivalent to phrase(_R_u_l_e_S_e_t, _I_n_p_u_t_L_i_s_t, []).


pphhrraassee((_+_R_u_l_e_S_e_t_, _+_I_n_p_u_t_L_i_s_t_, _-_R_e_s_t))
    Activate  the rule-set with given name.  `InputList' is the  list of
    tokens to parse,  `Rest' is unified with the remaining tokens if the
    sentence is parsed  correctly.  The example below calls the rule-set
    `integer' defined above.

    ____________________________________________________________________|                                                                    |
    | ?- phrase(integer(X), "42 times", Rest).                           |

    |                                                                    |
    | X = 42                                                             |
    ||Rest_=_[32,_116,_105,_109,_101,_115]______________________________ ||


44..1122 DDaattaabbaassee

SWI-Prolog offers  three different database mechanisms.   The first  one
is  the common  assert/retract  mechanism  for manipulating  the  clause
database.    As facts  and clauses  asserted using  assert/1  or one  of
its  derivatives become  part of  the program  these predicates  compile
the term  given to them.    retract/1 and retractall/1  have to unify  a
term and  therefore have to  decompile the program.   For these  reasons
the assert/retract  mechanism is  expensive.   On the  other hand,  once
compiled, queries to the database are faster than  querying the recorded
database discussed below.  See also dynamic/1.

The second way of  storing arbitrary terms in the database is  using the
`recorded database'.  In this database terms are  associated with a _k_e_y.
A key can be an atom, small integer or term.  In  the last case only the
functor and  arity determine the  key.   Each key has  a chain of  terms
associated with it.   New terms  can be added either  at the head or  at
the tail of this chain.

Following the Edinburgh tradition, SWI-Prolog provides  database keys to
clauses and  records in  the recorded  database.   As  of 5.9.10,  these
keys are represented by non-textual atoms (`blobs',  see section 9.4.7),
which makes accessing the database through references safe.

The third mechanism is a special purpose one.   It associates an integer
or atom with  a key, which is  an atom, integer or  term.  Each key  can
only have one atom or integer associated with it.


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 has been 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.


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 context is discouraged.


rreettrraacctt((_+_T_e_r_m))                                                    _[_I_S_O_]
    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.


rreettrraaccttaallll((_+_H_e_a_d))
    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_]
    Assert  a fact or clause in the  database.  _T_e_r_m is asserted  as the
    firsr  fact or clause  of the corresponding  predicate.   Equivalent
    to  assert/1, but _T_e_r_m  is asserted as first  clause or fact of  the
    predicate.


aasssseerrttzz((_+_T_e_r_m))                                                    _[_I_S_O_]
    Equivalent to asserta/1,  but _T_e_r_m is asserted as the last clause or
    fact of the predicate.


aasssseerrtt((_+_T_e_r_m))
    Equivalent  to  assertz/1.     Deprecated:    new  code  should  use
    assertz/1.


aasssseerrttaa((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Asserts  a clause as asserta/1  and unifies _R_e_f_e_r_e_n_c_e with a  handle
    to  this clause.   The handle  can be used  to access this  specific
    clause using clause/3 and erase/1.


aasssseerrttzz((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Equivalent  to  asserta/1,  asserting the  new  clause as  the  last
    clause of the predicate.


aasssseerrtt((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Equivalent to assertz/2.


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, _V_a_l_u_e,  _).


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, _V_a_l_u_e,  _).


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.

    ____________________________________________________________________|                                                                    |
    |         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
    an  db-reference  returned  by recorda/3  or  recorded/3,  clause/3,
    assert/2,  asserta/2 or assertz/2.  Fail silently if  the referenced
    object no longer exists.


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 :- _B_o_d_y.


ffllaagg((_+_K_e_y_, _-_O_l_d_, _+_N_e_w))
    _K_e_y is an atom,  integer or term.  As with the recorded database, if
    _K_e_y is a term,  only the name and arity are used to locate the flag.
    Unify  _O_l_d with the old  value associated with _K_e_y.   If the key  is
    used  for the first time  _O_l_d is unified with  the integer 0.   Then
    store  the value  of _N_e_w, which  should be an  integer, float,  atom
    or  arithmetic expression, under  _K_e_y.   flag/3 is a fast  mechanism
    for  storing simple facts  in the  database.   The flag database  is
    shared  between threads and updates  are atomic, making it  suitable
    for generating unique integer counters.


44..1122..11 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 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 as
well as  the generation  it was  erased.   Only  clauses with  `created'
...`erased' interval  that encloses the generation  of the current  goal
are considered visible.


44..1122..22 IInnddeexxiinngg ddaattaabbaasseess

By  default,   SWI-Prolog,  as   most  other  implementations,   indexes
predicates  on their  first argument.    SWI-Prolog  allows indexing  on
other and multiple  arguments using the declaration index/1.   Dedicated
index schemas can be built using term_hash/2 or term_hash/4.


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  toplevel term  has depth 1,  its arguments have  depth 2,  etc.
    I.e.    _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  an 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 exeption  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.  I.e.,  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-colisions and thus  avoid
    storing the goal-term itself as well as testing using =@=/2.


44..1133 DDeeccllaarriinngg pprreeddiiccaatteess pprrooppeerrttiieess

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

________________________________________________________________________|                                                                        |
|:- dynamic                                                              |

|        foo/0,                                                          |
||_______baz/2._________________________________________________________ ||

On 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  multi-threaded version, the  clauses of dynamic predicates  are
    shared  between the threads.  The  directive thread_local/1 provides
    an  alternative where each threads  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_N_a_m_e_A_r_i_t_y))
    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  is generated  at runtime  but does  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.


iinnddeexx((_+_H_e_a_d))
    Index  the clauses  of the predicate  with the  same name and  arity
    as  _H_e_a_d  on the  specified arguments.    _H_e_a_d is  a  term of  which
    all  arguments  are  either  `1' (denoting  `index  this  argument')
    or  `0'  (denoting `do  not index  this argument').    Indexing  has
    no  implications  for the  semantics of  a  predicate, only  on  its
    performance.    If  indexing is  enabled on  a  predicate a  special
    purpose  algorithm  is used  to select  candidate  clauses based  on
    the  actual arguments of  the goal.   This algorithm checks  whether
    indexed  arguments might  unify in  the clause  head.   Only  atoms,
    integers  and compound  terms are  considered.   Compound terms  are
    indexed  on the combination  of their name and  arity.  Indexing  is
    very useful for predicates with many clauses representing facts.

    Due to the  representation technique used at most 4 arguments can be
    indexed.  All  indexed arguments should be in the first 32 arguments
    of  the predicate.    If  more than  4 arguments  are specified  for
    indexing only the first  4 will be accepted.  Arguments above 32 are
    ignored for indexing.

    Indexing   as  specified  by  this   predicate  uses  a  quick   but
    linear  scan.     Without explicit  specification  the  system  uses
    an  algorithm  depending  on the  structure  of the  first  argument
    and  number  of clauses,  In  particular,  for predicates  that  can
    be  indexed  on  the  first argument  and  have  many  clauses,  the
    system  will use  an  automatically resizing  hash-table to  provide
    access  time  independent from  the  number of  clauses.    If---for
    example---one  wants  to  represents  sub-types using  a  fact  list
    `sub_type(Sub, Super)' that  should be used  both to determine  sub-
    and super types one should declare sub_type/2 as follows:

    ____________________________________________________________________|                                                                    |
    | :- index(sub_type(1, 1)).                                          |

    |                                                                    |
    | sub_type(horse, animal).                                           |
    | ...                                                                |
    ||..._______________________________________________________________ ||

    Note that this  type of indexing makes selecting clauses much faster
    but  remains _l_i_n_e_a_r  with respect  to the number  of clauses,  while
    hashing  as described  with  hash/1 provides  constant access  time.
    See also hash/1 and term_hash/2.


hhaasshh((_+_H_e_a_d))
    Index  the given predicate by hashing  on the first argument.   This
    is done by default  on any predicate with more than 5 clauses having
    a  first argument  that  can be  indexed and  at most  two that  can
    not  be indexed.   On dynamic  predicates the hash-table is  resized
    as  the number  of clauses  grows,  providing roughly  constant-time
    access  regardless of the number  of clauses predicates that can  be
    indexed  on the first argument.   See also index/1,  term_hash/2 and
    predicate_property/2.


44..1144 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 9.4.7 for details.


ccuurrrreenntt__ffuunnccttoorr((_?_N_a_m_e_, _?_A_r_i_t_y))
    Successively unifies _N_a_m_e  with the name and _A_r_i_t_y with the arity of
    functors known to the system.


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  5.9).    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  auto-loadable
    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 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  if _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  auto-import  modules
    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))
         Is 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
         Is 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.

    ddyynnaammiicc
         Is true  if assert/1 and  retract/1 may be  used to modify  the
         predicate.  This property is set using dynamic/1.

    eexxppoorrtteedd
         Is 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.

    ffoorreeiiggnn
         Is true if the predicate is defined in the C language.

    iinnddeexxeedd((_H_e_a_d))
         Predicate is indexed (see index/1) according to _H_e_a_d.   _H_e_a_d is
         a term  whose name and  arity are  identical to the  predicate.
         The arguments are unified  with `1' for indexed arguments,  `0'
         otherwise.

    iinntteerrpprreetteedd
         Is 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
         Is  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.

    mmuullttiiffiillee
         Is true there  may be multiple  (or no) file 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.

    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.

    tthhrreeaadd__llooccaall
         If true  (only  possible on  the multi-threaded  version)  each
         thread has its  own clauses for the  predicate.  This  property
         is set using thread_local/1.

    ttrraannssppaarreenntt
         Is true  if the  predicate  is declared  transparent using  the
         module_transparent/1 or meta_predicate/1 declaration.   In  the
         latter case the property meta is also provided.   See chapter 5
         for details.

    uunnddeeffiinneedd
         Is  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 or the  predicate had
         a definition in  the past.   See the library package check  for
         example usage.

    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,
    which  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  style_check(+dollar) is  active.    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  indices and the  references of  all clauses of  the
    predicate.  The following example finds the 2nd clause of member/2:

    ____________________________________________________________________|                                                                    |
    | ?- nth_clause(member(_,_), 2, Ref), clause(Head, Body, Ref).       |

    |                                                                    |
    | Ref = 160088                                                       |
    | Head = system : member(G575, [G578|G579])                          |
    ||Body_=_member(G575,_G579)_________________________________________ ||


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.  _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  source file in which  the
         clause is defined.  Fails if the clause is not  associated to a
         file.

    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.

    ffaacctt
         True if the clause has no body.

    eerraasseedd
         True if  the  clause has  been erased,  but  not yet  reclaimed
         because it is referenced.


44..1155 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 4.15.2  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..1155..11 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 to the ISO standard,  either input or
output streams.    To accomodate 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  \bnfmeta{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 9.4.7).


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_]
    ISO  compliant predicate to  open a  stream.   _S_r_c_D_e_s_t is either  an
    atom,  specifying a file, or a term `pipe(_C_o_m_m_a_n_d)', like  see/1 and
    tell/1.    _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.  The  _O_p_t_i_o_n_s list can contain  the
    following options:

    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.

    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),                                     |
         ||_______...___________________________________________________ ||

    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 2.17.1.

    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  2.17.1.1 for
         a discussion on this feature.

    eeooff__aaccttiioonn((_A_c_t_i_o_n))
         Defines  what  happens  if the  end  of  the  input  stream  is
         reached.   Action eof_code 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.

    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,  it will  be flushed  however.   Useful  for
         logfiles and if  the stream is  associated to a process  (using
         the pipe/1 construct).

    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.

    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 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.    However, closing  a stream  multiple times  may
    crash  Prolog.     This  is  particularly  true  for  multi-threaded
    applications.

    If  the closed  stream is the  current input or  output stream,  the
    terminal is made the current input or output.


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 error  (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_]
    ISO  compatible predicate for querying  status of open I/O  streams.
    _S_t_r_e_a_m_P_r_o_p_e_r_t_y is one of:

    aalliiaass((_A_t_o_m))
         If _A_t_o_m is bound,  test of 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 of 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 2.17.1.1 for details.

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

    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((_T_e_r_m))
         Unify  _T_e_r_m  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  and  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 2.17.1 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))
         Unify _B_o_o_l with text or binary.

    ttttyy((_B_o_o_l))
         This property is reported  with _B_o_o_l equals true if  the stream
         is associated with a terminal.  See also set_stream/2.


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.   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
    both  streams of the pair.   Mode (+,-,-) can be used to  get access
    to the underlying streams.


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_i_t_i_o_n_, _-_D_a_t_a))
    Extracts  information  from  the  opaque  stream  position  term  as
    returned  by  stream_property/2  requesting  the  position(_P_o_s_i_t_i_o_n)
    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  then
    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.  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 is used, 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 2.17.1 for supported encodings.

    eeooff__aaccttiioonn((_A_c_t_i_o_n))
         Set end-of-file handling to one of eof_code, reset or error.

    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.

    rreeccoorrdd__ppoossiittiioonn((_B_o_o_l))
         Do/do  not  record   the  line-count  and  line-position   (see
         line_count/2 and line_position/2).

    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 2.17.1.

    ffiillee__nnaammee((_F_i_l_e_N_a_m_e))
         Set the file name 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.

    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..1155..22 EEddiinnbbuurrgghh--ssttyyllee II//OO

The  package for  implicit  input  and output  destination  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  stream.
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  streams  current value  can  be
obtained using telling/1 for output- and seeing/1 for input streams.

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([]).|_______________________________________________________ |               |


CCoommppaattiibbiilliittyy nnootteess

Unlike Edinburgh  Prolog systems, telling/1  and seeing/1 do not  return
the filename of the current input/output, but  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,  created using  tell/1 or see/1  exists,
output (input) is switch 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, 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 4.15.1.


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  makes  this
    stream  the current input.   See the introduction of section  4.15.2
    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 makes  this
    stream  the current output.  See the introduction of  section 4.15.2
    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 4.15.2 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 4.15.2 for details.


sseeeenn
    Close  the  current input  stream.   The  new  input stream  becomes
    _u_s_e_r___i_n_p_u_t.


ttoolldd
    Close  the current  output stream.   The  new output stream  becomes
    _u_s_e_r___o_u_t_p_u_t.


44..1155..33 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 to get 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..1155..44 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  is 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  multi-threaded 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
         Temporary switch current output to the given stream.   Redirec-
         tion 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 4.22.

    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 codes  from the  emitted
         characters, 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..1166 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))
    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.

    This  predicate can be used  to implement timeout while reading  and
    to  handle  input from  multiple  sources.   The  following  example
    will  wait for input from the  user and an explicitly opened  second
    terminal.  On return, _I_n_p_u_t_s may hold user or _P_4 or both.

    ____________________________________________________________________|                                                                    |
    | ?- open('/dev/ttyp4', read, P4),                                   |

    ||___wait_for_input([user,_P4],_Inputs,_0)._________________________ ||

    This  predicate  relies  on  the select()  call  on  most  operating
    systems.  On  Unix this call is implemented for any stream referring
    to  a file-handle,  which implies  all OS-based  streams:   sockets,
    terminals,  pipes, etc.   On non-Unix systems select() is  generally
    only  implemented for socket-based  streams.   See also socket  from
    the clib package.

    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  for within the timeout.  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..1177 PPrriimmiittiivvee cchhaarraacctteerr II//OO

See section 4.2 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.   Depreciated.   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 a stream.  _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 _S_t_r_e_a_m 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 _S_t_r_e_a_m 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))
    Writes  _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 4.25).


ttaabb((_+_S_t_r_e_a_m_, _+_A_m_o_u_n_t))
    Writes _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 _u_s_e_r.  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, returning 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))
    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))
    Edinburgh  version  of  the ISO  get_code/2  predicate.    See  also
    get0/1.


ggeett((_-_C_h_a_r))
    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.


ggeett((_+_S_t_r_e_a_m_, _-_C_h_a_r))
    Read the next non-blank character from _S_t_r_e_a_m.


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 multibyte
    sequence that might need to be buffered.


sskkiipp((_+_C_o_d_e))
    Read the input until  _C_h_a_r 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 stream (unbuffered  input streams  are
    rarely used, see open/4).


sseett__eenndd__ooff__ssttrreeaamm((_+_S_t_r_e_a_m))
    Sets  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  stream _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 take place  between two
    text files.  See section 2.17.1.


ccooppyy__ssttrreeaamm__ddaattaa((_+_S_t_r_e_a_m_I_n_, _+_S_t_r_e_a_m_O_u_t))
    Copy data all (remaining) data from stream _S_t_r_e_a_m_I_n to _S_t_r_e_a_m_O_u_t.


rreeaadd__ppeennddiinngg__iinnppuutt((_+_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.   I.e. the available  characters
    codes  are used to  create the list _C_o_d_e_s  ending in the tail  _T_a_i_l.
    This  predicate is  intended  for efficient  unbuffered copying  and
    filtering of input coming from network connections or devices.

    The following code  fragment realises efficient non-blocking copy 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,                                                    |
    |             (   at_end_of_stream(In)                               |
    |             ->  !                                                  |
    |             ;   read_pending_input(In, Chars, []),                 |
    |                 format(Out, '~s', [Chars]),                        |
    |                 flush_output(Out),                                 |
    |                 fail                                               |
    ||____________).____________________________________________________ ||


44..1188 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  datastructures  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 6.1)  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).

    bbaacckkqquuootteedd__ssttrriinngg((_B_o_o_l))
         If true,  write a string  object (see  section 4.22) as  `...`.
         The default depends on the Prolog flag backquoted_string.

    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 9.4.7.

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

    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,
         list-notation and  {}/1  will be  written using  their  special
         syntax.

    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
         for 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|...])                                       |
         |                                                               |
         |Yes|__________________________________________________________ |   |

         Used  by   the   top-level  and   debugger  to   limit   screen
         output.   See also the Prolog  flags toplevel_print_options and
         debugger_print_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.

    nnuummbbeerrvvaarrss((_B_o_o_l))
         If true, terms  of the format $VAR(N), where  <_N> is a positive
         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.

    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,  it correctly emits . ..   Similar
         problems appear  when emitting operators  using multiple  calls
         to write_term/3.

         _______________________________________________________________|                                                               |
         |write_value(Value) :-                                          |
         |        write_term(Value, [quoted(true)]),                     |

         ||_______write('.'),_nl._______________________________________ ||

    ppoorrttrraayy((_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 needs 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.


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__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<_N_N_N> 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.


pprriinntt((_+_T_e_r_m))
    Prints  _T_e_r_m on the  current output stream  similar to write/1,  but
    for each (sub)term  of _T_e_r_m first the dynamic predicate portray/1 is
    called.   If this predicate succeeds _p_r_i_n_t assumes the (sub)term has
    been written.   This allows for user defined term writing.  See also
    portray_text.


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 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((_-_T_e_r_m))
    Equivalent  to read/1, but warns the user for variables  only occur-
    ring  once in  a term  (singleton variables,  see section  2.15.1.5)
    which  do  not start  with an  underscore if  style_check(singleton)
    is  active  (default).    Used  to  read Prolog  source  files  (see
    consult/1).     New code  should  use  read_term/2 with  the  option
    singletons(warning).


rreeaadd__ccllaauussee((_+_S_t_r_e_a_m_, _-_T_e_r_m))
    Read a clause from _S_t_r_e_a_m.  See read_clause/1.


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  4.22).
         The default depends on the Prolog flag backquoted_string.

    cchhaarraacctteerr__eessccaappeess((_B_o_o_l))
         Defines  how  to  read  \  escape-sequences  in  quoted  atoms.
         See the Prolog  flags character_escapes, 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.

    ddoouubbllee__qquuootteess((_B_o_o_l))
         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).

    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.

    ssyynnttaaxx__eerrrroorrss((_A_t_o_m))
         If error  (default),  throw and  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  is 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 |<_T_a_i_l_T_e_r_m>, _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.

    tteerrmm__ppoossiittiioonn((_P_o_s))
         Unifies _P_o_s with the starting  position of the term read.   _P_o_s
         if of the same format as use by stream_property/2.

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

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__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 2.7 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..1199 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 Term is  a
    variable  it is  unified with  a new  term whose  arguments are  all
    different variables (such a  term is called a skeleton).  If Term is
    atomic,  Arity will be unified with the integer 0, and Name  will be
    unified  with Term.   Raises instantiation_error if term is  unbound
    and _N_a_m_e/_A_r_i_t_y is insufficiently instantiated.


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_then_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 which head is the functor of _T_e_r_m and  the remaining
    arguments  are the arguments  of the  term.   Each of the  arguments
    may  be a variable, but not both.  This predicate is  called `Univ'.
    Examples:

    ____________________________________________________________________|                                                                    |
    | ?- foo(hello, X) =.. List.                                         |
    |                                                                    |
    | List = [foo, hello, X]                                             |

    |                                                                    |
    | ?- Term =.. [baz, foo(1)]                                          |
    |                                                                    |
    ||Term_=_baz(foo(1))________________________________________________ ||


nnuummbbeerrvvaarrss((_+_T_e_r_m_, _+_S_t_a_r_t_, _-_E_n_d))
    Unify  the free variables  of _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.
    Example:

    ____________________________________________________________________|                                                                    |
    | ?- numbervars(foo(A, B, A), 0, End).                               |

    |                                                                    |
    | A = '$VAR'(0)                                                      |
    | B = '$VAR'(1)                                                      |
    ||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, but 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  thread it  as  a  normal
         variable and assign the next '$VAR'(N) term to  it or (default)
         error which raises the 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.


tteerrmm__vvaarriiaabblleess((_+_T_e_r_m_, _-_L_i_s_t))
    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.  For example:

    ____________________________________________________________________|                                                                    |
    | ?- term_variables(a(X, b(Y, X), Z), L).                            |

    |                                                                    |
    | L = [G367, G366, G371]                                             |
    | X = G367                                                           |
    | Y = G366                                                           |
    ||Z_=_G371__________________________________________________________ ||


tteerrmm__vvaarriiaabblleess((_+_T_e_r_m_, _-_L_i_s_t_, _?_T_a_i_l))
    Difference list  version of term_variables/2.  I.e.  _T_a_i_l is the tail
    of the variable-list _L_i_s_t.


ccooppyy__tteerrmm((_+_I_n_, _-_O_u_t))                                               _[_I_S_O_]
    Create  a version  if _I_n  with renamed (fresh)  variables and  unify
    it  to  _O_u_t.   Attributed  variables (see  section  6.1) have  their
    attributed  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..1199..11 NNoonn--llooggiiccaall ooppeerraattiioonnss oonn tteerrmmss

Prolog is not capable  to _m_o_d_i_f_y instantiated parts of a term.   Lacking
that capability makes that 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  6.3,
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  not copying 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.


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 _T_e_r_m  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  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  the  equivalent  and  will  remain  the
    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..2200 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/2behaved,  compatible with
Quintus and  SICStus Prolog,  like atom_codes.    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' accept 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,  if 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, it will _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.    Fails with  a
    syntax_error if _N_u_m_b_e_r  is unbound and _C_h_a_r_L_i_s_t does not  describe a
    number.   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.


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.   Calling  in mode  +,-
    to  convert  numbers  represented  as atoms  is  often  good  style.
    Converting  numbers  to atoms,  which  in  turn are  assembled  into
    larger  units before communication them to the outside world  is bad
    style.    Consider using streams  or with_output_to/2 to reduce  the
    number of expensive intermediate atoms.


nnaammee((_?_A_t_o_m_O_r_I_n_t_, _?_S_t_r_i_n_g))
    _S_t_r_i_n_g  is a list of character  codes representing the same text  as
    _A_t_o_m.  Each of  the arguments may be a variable, but not both.  When
    _S_t_r_i_n_g  is bound  to an  character code list  describing an  integer
    and  _A_t_o_m  is a  variable  _A_t_o_m will  be  unified with  the  integer
    value  described by  _S_t_r_i_n_g (e.g.,  `name(N, "300"), 400 is N + 100'
    succeeds).    New  code  should consider  using the  ISO  predicates
    atom_codes/2 or number_codes/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 converted  and then unified with _T_e_r_m.  If _A_t_o_m
    has no  valid syntax, a syntax_errorexception 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 and with_output_to/2.


aattoomm__ttoo__tteerrmm((_+_A_t_o_m_, _-_T_e_r_m_, _-_B_i_n_d_i_n_g_s))
    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.


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  3-th 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  atoms,  integers  or floating  point  numbers.
    Succeeds  if _A_t_o_m can be  unified with the concatenated elements  of
    _L_i_s_t.


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 atoms.  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.

    ____________________________________________________________________|                                                                    |

    | ?- 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 long.   This predicate
    also  works for  strings (see  section 4.22).   If  the prolog  flag
    iso  is _n_o_t  set, it  also accepts integers  and floats,  expressing
    the  number of characters  output when given  to write/1 as well  as
    code-lists and character-lists, expressing the length of the list.


aattoomm__pprreeffiixx((_+_A_t_o_m_, _+_P_r_e_f_i_x))
    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).  Depreciated.


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 very flexible predicate  that can do search, prefix-  and
    suffix-matching, etc.


44..2211 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 ctype  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.

    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-bits ASCII character (0..127).

    wwhhiittee
         _C_h_a_r is a space or tab.  E.i. white space inside a line.

    ccnnttrrll
         _C_h_a_r is an ASCII control-character (0..31).

    ddiiggiitt
         _C_h_a_r is a digit.

    ddiiggiitt((_W_e_i_g_t_h))
         _C_h_a_r is a digit with value  _W_e_i_g_t_h.  I.e. char_type(X, digit(6)
         yields _X = '6'.  Useful for parsing numbers.

    xxddiiggiitt((_W_e_i_g_t_h))
         _C_h_a_r  is  a  hexa-decimal  digit  with  value  _W_e_i_g_t_h.     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 lower-case letter.

    lloowweerr((_U_p_p_e_r))
         _C_h_a_r is a  lower-case 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 lower-case 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 upper-case letter.

    uuppppeerr((_L_o_w_e_r))
         _C_h_a_r is an upper-case 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  upper-case 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 the 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.


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  only will  instantiate with  an  integer code  or
    one-character  atom depending  of the version  used.   See also  the
    Prolog flag double_quotes, atom_chars/2 and atom_codes/2.


44..2211..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 upper-case.


44..2211..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 replaces by a single space (\u0020) character.   _O_u_t
    uses the same conventions as with_output_to/2 and format/3.


44..2211..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 4.22).  _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..2222 RReepprreesseennttiinngg tteexxtt iinn ssttrriinnggss

SWI-Prolog  supports the  data type  _s_t_r_i_n_g.   Strings  are  a time  and
space efficient mechanism to handle text in Prolog.   Strings are stored
as  a byte  array  on the  global (term)  stack  and thus  destroyed  on
backtracking and reclaimed by the garbage collector.

Strings were  added to  SWI-Prolog based on  an early  draft of the  ISO
standard,  offering a mechanism  to represent  temporary character  data
efficiently.    As  SWI-Prolog  strings can  handle  0-bytes,  they  are
frequently used through  the foreign language interface (section 9)  for
storing arbitrary byte-sequences.

Starting with version  3.3, SWI-Prolog offers garbage collection  on the
atom-space as well as  representing 0-bytes in atoms.   Although strings
and  atoms still  have  different  features,  new code  should  consider
using atoms to  avoid too many representations  for text as well as  for
compatibility with other Prolog implementations.  Below are  some of the
differences:

  o _c_r_e_a_t_i_o_n
    Creating  strings  is fast,  as the  data is  simply  copied to  the
    global  stack.   Atoms are  unique and  therefore more expensive  in
    terms  of memory  and time to  create.   On the other  hand, if  the
    same  text has  to be  represented  multiple times,  atoms are  more
    efficient.

  o _d_e_s_t_r_u_c_t_i_o_n
    Backtracking destroys strings at  no cost.  They are cheap to handle
    by  the garbage  collector, but  it should be  noted that  extensive
    use  of strings will cause many  garbage collections.  Atom  garbage
    collection is generally faster.

String objects  by default have no  lexical representation and thus  can
only  be created  using  the predicates  below  or through  the  foreign
language interface (See  chapter 9.  There  are two ways to make  read/1
read text into  strings, both controlled through  Prolog flags.  One  is
by setting the double_quotes flag to string and the other  is by setting
the backquoted_string flag  to true.   In latter case, `Hello world`  is
read into a  string and write_term/2 prints strings between  back-quotes
if quoted  is true.   This flag provides  compatibility with LPA  Prolog
string handling.


ssttrriinngg__ttoo__aattoomm((_?_S_t_r_i_n_g_, _?_A_t_o_m))
    Logical  conversion between  a string  and an atom.    At least  one
    of  the two arguments  must be instantiated.   _A_t_o_m  can also be  an
    integer or floating point number.


ssttrriinngg__ttoo__lliisstt((_?_S_t_r_i_n_g_, _?_L_i_s_t))
    Logical  conversion  between  a  string  and  a  list  of  character
    codes  characters.    At least  one  of the  two arguments  must  be
    instantiated.


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__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.


ssuubb__ssttrriinngg((_+_S_t_r_i_n_g_, _?_S_t_a_r_t_, _?_L_e_n_g_t_h_, _?_A_f_t_e_r_, _?_S_u_b))
    _S_u_b  is a substring of _S_t_r_i_n_g starting at _S_t_a_r_t, with  length _L_e_n_g_t_h
    and  _S_t_r_i_n_g has _A_f_t_e_r  characters left  after the match.   See  also
    sub_atom/5.


44..2233 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 lead  to 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.  This is an extension  specific to SWI-Prolog and
the recommended mechanism if portability is not an important concern.

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 systems:

________________________________________________________________________|                                                                        |
|:- module(prove,                                                        |

|          [ prove/1                                                     |
|          ]).                                                           |
|                                                                        |
|:-|op(900,_xfx,_user:(=>)).____________________________________________ |  |

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:  defining  an atom as an  operator does nnoott influence  parsing
characters into atoms and  quoting an atom does nnoott stop it  from acting
as an operator.   To stop an atom  acting as an operator, enclose  it in
braces like this:  (myop).


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 brackets (...) has precedence 0.

    The  predefined operators  are shown in  table 4.1.   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  5.8).   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  4.1 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 from operator changes to the user module.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |

     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic,    discontiguous,     initialization, |
     |      |     |meta_predicate,  module_transparent, multifile,|
     |      |     |thread_local, volatile                         |
     | 1100 |xfy  |;, |                                           |
     | 1050 |xfy  |->, op*->                                      |
     | 1000 |xfy  |,                                              |
     |  900 | fy  |\+                                             |

     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |
     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |?                                              |
     |  400 | yfx |*, /, //, rdiv, <<, >>, mod, rem               |

     |  200 |xfx  |**                                             |
     |  200 |xfy  |^                                              |
     |__200_|_fy__|+,_-,_\________________________________________|_

                      Table 4.1:  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..2244 CChhaarraacctteerr CCoonnvveerrssiioonn

Although I  wouldn't really know  for what 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..2255 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 4.25.2.3.


44..2255..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.


44..2255..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..2255..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 value
    on  the  global stack.    Integers that  do not  fit  in 64-bit  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 representing  rational  numbers
    allow  for passing rational numbers between computations as  well as
    to format/3 for printing.

    On  the long  term it is  likely that  rational numbers will  become
    _a_t_o_m_i_c  as  well as  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 today 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..2255..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  the  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..2255..22..33 AArriitthhmmeettiicc FFuunnccttiioonnss

Arithmetic functions  are terms  which are evaluated  by the  arithmetic
predicates  described in  section  4.25.2.    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  into
                  an integer.
       _R_a_t_E_x_p_r    Arbitrary expression that must evaluate  into a

                  rational number.
       _F_l_o_a_t_E_x_p_r  Arbitrary expression that must evaluate  into a
                  floating point.

For  systems using  bounded integer  arithmetic  (default is  unbounded,
see section 4.25.2.1  for details), integer operations that  would cause
overflow automatically convert to floating point arithmetic.


- _+_E_x_p_r                                                           _[_I_S_O_]
    _R_e_s_u_l_t =-_E_x_p_r


+ _+_E_x_p_r
    _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 The 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 (IntExpr1 -IntExpr1modIntExpr2)==IntExpr2.       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 4.25.2.2 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.


mmaaxx((_+_E_x_p_r_1_, _+_E_x_p_r_2))
    Evaluates  to the largest of both  _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))
    Evaluates to the smallest  of both _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).    This
    option  is available for  compatibility only.   It will not work  if
    `style_check(+string)'  is active as  "a" will  then be  transformed
    into a string object.   The recommended way to specify the character
    code of the letter `a' is 0'a.


rraannddoomm((_+_I_n_t_E_x_p_r))
    Evaluates  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.


rroouunndd((_+_E_x_p_r))                                                      _[_I_S_O_]
    Evaluates _E_x_p_r and rounds the result to the nearest integer.


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 4.25.2.2 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).  E.i.
    truncate rounds towards zero.


fflloooorr((_+_E_x_p_r))                                                      _[_I_S_O_]
    Evaluates  _E_x_p_r and returns the largest integer smaller or  equal to
    the result of the evaluation.


cceeiilliinngg((_+_E_x_p_r))                                                    _[_I_S_O_]
    Evaluates  _E_x_p_r and returns 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 >> _+_I_n_t_E_x_p_r                                              _[_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 bit.


_+_I_n_t_E_x_p_r << _+_I_n_t_E_x_p_r                                              _[_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 \/ _+_I_n_t_E_x_p_r                                              _[_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 /\ _+_I_n_t_E_x_p_r                                              _[_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 xxoorr _+_I_n_t_E_x_p_r                                             _[_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))
    _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))
    _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))
    _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.


aattaann((_+_Y_E_x_p_r_, _+_X_E_x_p_r))
    Same as atan2/2 (backward compatibility).


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.   With unbounded integers and in-
    teger values for  _E_x_p_r_1 and a non-negative integer _E_x_p_r_2, the result
    is  always  integer.    The  integer  expressions  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.


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.


_+_E_x_p_r_1 ^ _+_E_x_p_r_2
    Same as **/2 (backward compatibility).


ppii
    Evaluates to the mathematical constant pi (3.14159...).


ee
    Evaluates to the mathematical constant e (2.71828...).


eeppssiilloonn
    Evaluates to the  the difference between the float 1.0 and the first
    larger floating point number.


ccppuuttiimmee
    Evaluates  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 is compatible with hProlog.  The others  are private 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 IntExpr,  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.


44..2266 AAddddiinngg AArriitthhmmeettiicc FFuunnccttiioonnss

Prolog predicates  can be given  the role of arithmetic  function.   The
last  argument is  used  to  return the  result,  the  arguments  before
the last  are the  inputs.   Arithmetic  functions are  added using  the
predicate arithmetic_function/1, which takes  the head as its  argument.
Arithmetic  functions  are module  sensitive,  that  is  they  are  only
visible from the module  in which the function is defined  and declared.
Global  arithmetic  functions  should be  defined  and  registered  from
module user.   Global definitions can  be overruled locally in  modules.
The built-in functions described above can be redefined as well.


aarriitthhmmeettiicc__ffuunnccttiioonn((_:_H_e_a_d))
    Register  a Prolog  predicate as an  arithmetic function (see  is/2,
    >/2 , etc.).   The Prolog  predicate should  have one more  argument
    than  specified by _H_e_a_d, which it either a term _N_a_m_e_/_A_r_i_t_y,  an atom
    or  a complex term.   This last argument  is an unbound variable  at
    call  time and  should  be instantiated  to an  integer or  floating
    point  number.    The other  arguments  are the  parameters.    This
    predicate  is  module  sensitive  and will  declare  the  arithmetic
    function  only for the context  module, unless declared from  module
    user.  Example:

    ____________________________________________________________________|                                                                    |
    | 1 ?- [user].                                                       |

    | :- arithmetic_function(mean/2).                                    |
    |                                                                    |
    | mean(A, B, C) :-                                                   |
    |         C is (A+B)/2.                                              |
    | user compiled, 0.07 sec, 440 bytes.                                |
    |                                                                    |
    | Yes                                                                |
    | 2 ?- A is mean(4, 5).                                              |

    |                                                                    |
    ||A_=_4.500000______________________________________________________ ||


ccuurrrreenntt__aarriitthhmmeettiicc__ffuunnccttiioonn((_:_H_e_a_d))
    True if _H_e_a_d is  a function that is visible from the current module.
    Built-in functions are  visible from all modules, while user-defined
    functions  (see  arithmetic_function/1)  obey  the module  visibility
    rules.  E.g.,

    ____________________________________________________________________|                                                                    |
    | ?- current_arithmetic_function(sin(_)).                            |

    ||true._____________________________________________________________ ||


44..2277 MMiisscc aarriitthhmmeettiicc ssuuppppoorrtt pprreeddiiccaatteess


sseett__rraannddoomm((_+_O_p_t_i_o_n))
    Controls  the random  number generator that  accessible through  the
    _f_u_n_c_t_i_o_n  random/1.  Note that the library random  provides distinct
    support for random numbers that is not affected by set_random/1.

    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.________________________________________________________ | |


44..2288 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))
    Same as once(member(_E_l_e_m, _L_i_s_t)).  See member/2.


lleennggtthh((_?_L_i_s_t_, _?_I_n_t))
    True  if _I_n_t represents the number of  elements of list _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 _L_i_s_t  is not  a list  or partial list  or _I_n_t  is not  an
    integer or unbound.


ssoorrtt((_+_L_i_s_t_, _-_S_o_r_t_e_d))
    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  4.6).
    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.


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))
    List  is a proper list whose elements are _K_e_y-_V_a_l_u_e, that  is, terms
    whose  principal  functor is  (-)/2,  whose  first argument  is  the
    sorting  key, and whose second argument is the satellite data  to be
    carried  along with  the key.   keysort/2  sorts _L_i_s_t like  msort/2,
    but  only compares  the  keys.   It  is used  to sort  terms not  on
    standard  order, but  on any criterion  that can  be expressed on  a
    multi-dimensional scale.   Sorting on more than one criterion can be
    done  using terms as keys,  putting the first criterion as  argument
    1,  the second as argument 2,  etc.  The order of  multiple elements
    that have the same  _K_e_y is not changed.  The implementation is in C,
    using  _n_a_t_u_r_a_l _m_e_r_g_e _s_o_r_t.    Fails with a  type_error if _L_i_s_t is  a
    cyclic  list or not a list or one  of the elements of _L_i_s_t is  not a
    _p_a_i_r.


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 built-in predicate  compare/3 is used,  the
    result is the same as sort/2.  See also keysort/2.


44..2299 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_]
    Creates  a list of the instantiations _T_e_m_p_l_a_t_e gets  successively on
    backtracking  over _G_o_a_l and unifies 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 goal  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,_[])_____________________________ ||


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  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 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).                                                      |
    |                                                                    |
    | Yes                                                                |
    | 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] ;                                 |
    |                                                                    |
    | No                                                                 |
    | 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] ;                        |
    |                                                                    |
    | No                                                                 |
    ||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..3300 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 list _L  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)._____________________________ ||


44..3311 FFoorrmmaatttteedd WWrriittee

The  current  version   of  SWI-Prolog  provides  two  formatted   write
predicates.    The  first  is writef/[1,2],  which  is  compatible  with
Edinburgh C-Prolog.   The  second is  format/[1,2], which is  compatible
with Quintus  Prolog.   We hope  the Prolog  community will once  define
a  standard formatted  write predicate.    If you  want performance  use
format/[1,2] as this predicate is defined in  C. Otherwise compatibility
reasons might tell you which predicate to use.


44..3311..11 WWrriitteeff


wwrriitteellnn((_+_T_e_r_m))
    Equivalent to write(Term), nl.


wwrriitteeff((_+_A_t_o_m))
    Equivalent to writef(Atom, []).


wwrriitteeff((_+_F_o_r_m_a_t_, _+_A_r_g_u_m_e_n_t_s))
    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 then 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 character  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 2.15.1.2.

    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))
    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))
    Equivalent to swritef(String, Format, []).


44..3311..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, []).'


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, 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 4.25.2.2.   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 `70'.

    ____________________________________________________________________|                                                                    |
    | ?- format('~70f', [10 rdiv 3]).                                    |
    ||3.3333333333333333333333333333333333333333333333333333333333333333333333||_

      ~  Output the tilde itself.

      a  Output the next argument, which  must be an atom.   This option
         is equivalent to  ww, except for  that it requires the  argument
         to be an atom.

      c  Interpret the next argument as an character code and  add it to
         the output.   This argument should  be an integer in the  range
         [0, ..., 255] (including 0 and 255).

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

      D  Same as dd, but  makes large values easier to read  by inserting
         a comma every three digits left to the dot or right.

      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.    See C  library
         function printf().

      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.

      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 the  numeric argument  notation.   Thus
         ~16r prints its argument  hexadecimal.  The argument  should be
         in the range [2; :::;36].   Lower case letters are used for  digits
         above 9.

      R  Same as rr, but uses upper case letters for digits above 9.

      s  Output text  from a list  of character codes  or a string  (see
         string/1 and section 4.22) 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
         this 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 relative  to the current position.   Further the
         same as ~|.

      w  Give the next argument to write/1.

      W  Give  the   next   two  argument   to  write_term/2.       E.g.
         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..3311..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  derivatives will 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 an ascii  value,
    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 redefines ~n to produce _A_r_g times return  followed by
    linefeed (so a (Grr.)  DOS machine is happy with the output).

    ____________________________________________________________________|                                                                    |
    | :- format_predicate(n, dos_newline(_Arg)).                         |

    |                                                                    |
    | dos_newline(default) :- !,                                         |
    |         dos_newline(1).                                            |
    | dos_newline(N) :-                                                  |
    |         (   N > 0                                                  |
    |         ->  write('\r\n'),                                         |
    |             N2 is N - 1,                                           |
    |             dos_newline(N2)                                        |

    |         ;   true                                                   |
    ||________).________________________________________________________ ||


ccuurrrreenntt__ffoorrmmaatt__pprreeddiiccaattee((_?_C_o_d_e_, _?_:_H_e_a_d))
    Enumerates  all  user-defined  format  predicates.     _C_o_d_e  is  the
    character  code of the  format character.   _H_e_a_d  is unified with  a
    term  with  the same  name  and arity  as  the predicate.    If  the
    predicate  does not reside  in module user,  _H_e_a_d is qualified  with
    the definition module of the predicate.


44..3322 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 consoles 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  result 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).


sseett__ttttyy((_-_O_l_d_S_t_r_e_a_m_, _+_N_e_w_S_t_r_e_a_m))
    Set  the  output  stream,  used by  tty_put/2  and tty_goto/2  to  a
    specific stream.  Default is user_output.


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.    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 multi-threaded  version the console that is  associated
         with the user_input stream is used.


44..3333 OOppeerraattiinngg SSyysstteemm IInntteerraaccttiioonn


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  _W_i_n_3_2  systems,  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
    (command.exe  on  Windows  95/98  and  cmd.exe  on  Windows-NT)  and
    therefore  commands  built-in to  the command-interpreter  can  only
    be   activated  using  the  command  interpreter.      For  example:
    'command.exe /C copy file1.txt file2.txt'


sshheellll((_+_C_o_m_m_a_n_d))
    Equivalent to `shell(Command, 0)'.


sshheellll
    Start  an  interactive  Unix  shell.     Default  is  /bin/sh,   the
    environment  variable SHELL overrides this  default.  Not  available
    for Win32 platforms.


wwiinn__eexxeecc((_+_C_o_m_m_a_n_d_, _+_S_h_o_w))
    Win32  systems 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))
    Win32  systems 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))
    Win32  systems only.   Fetches  the value of  a Win32 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))
    Is  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'________ ||


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 2.17.1.    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 use  in  multi-threaded  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 provides 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 prolog Prolog flag argv.

         A  stand-alone program  could  use  the following  skeleton  to
         handle command-line arguments.  See also section 2.10.2.4.

         _______________________________________________________________|                                                               |

         |main :-                                                        |
         |        current_prolog_flag(argv, Argv),                       |
         |        append(_PrologArgs, [--|AppArgs], Argv), !,            |
         ||_______main(AppArgs).________________________________________ ||


44..3333..11 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  range from better then  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  deal with  comparison and  durations.   An  additional
advantage  of the  physicists 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 libtai  to realise conversion
between  time-stamps and  calendar  dates for  a  period of  10  million
years.


44..3333..11..11 TTiimmee aanndd ddaattee ddaattaa--ssttrruuccttuurreess

We use the following time representations

TTiimmeeSSttaammpp
    A  TimeStamp  is a  floating  point number  expression 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),  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..3333..11..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 4.33.1.1.


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 time zone.    See
    section 4.33.1.1 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 at  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)__________________________________________ ||


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 effective
        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  tilde (%)  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.      (Yecch    for  Americans   only.
         Americans  should note  that  in  other countries  %d/%m/%y  is
         rather common.   This means that in 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  time-zone  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 ISO8601.  The  sequence %:z is
         compatible to the GNU date(1) command.

      Z  The time zone 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 or  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_|
                  | 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   numbered
    from one to seven:  monday = 1, tuesday = 2, ..., sunday = 7.


44..3333..22 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 advice 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 conventions,  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 a
    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..3344 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  `Mode' 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.


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.


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 if _F_i_l_e does
    not contain any / characters is ..


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.


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

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  and 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 into _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.   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 file-name  into an  absolute path.    The  absolute
    path  is canonised:   references  to .  and ..  are deleted.    This
    predicate  ensures that  expanding a file-name  it returns the  same
    absolute  path regardless of how the file is addressed.   SWI-Prolog
    uses  absolute file  names to register  source files independent  of
    the  current working directory.  See also absolute_file_name/3.   See
    also absolute_file_name/3 and expand_file_name/2.


aabbssoolluuttee__ffiillee__nnaammee((_+_S_p_e_c_, _+_O_p_t_i_o_n_s_, _-_A_b_s_o_l_u_t_e))
    Converts  the  given  file  specification  into  an  absolute  path.
    _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  of  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  directory
         the  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 on  of
         read, write, append, 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 and  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  predicates leaves  no  choice-point.
         Otherwise a  choice-point  will be  left and  backtracking  may
         yield more solutions.

    eexxppaanndd((_t_r_u_e_/_f_a_l_s_e))
         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.

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

    Compatibility  considerations with common  argument-order in ISO  as
    well  as SICStus absolute_file_name/3forced us to  be flexible here.
    If  the last argument is a list  and the 2nd not, the  arguments are
    swapped,  making the call absolute_file_name(_+_S_p_e_c_,  _-_P_a_t_h_, _+_O_p_t_i_o_n_s)
    valid as well.


iiss__aabbssoolluuttee__ffiillee__nnaammee((_+_F_i_l_e))
    True  if _F_i_l_e specifies  and absolute path-name.   On Unix  systems,
    this   implies  the  path  starts  with  a  `/'.      For  Microsoft
    based   systems  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   be  done
    case-insensitive too.   _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))
    Unifies  _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
    interpreted  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 on  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))
    Converts  between the internal  Prolog pathname conventions and  the
    operating-system  pathname conventions.    The internal  conventions
    are  Unix and this predicates is  equivalent to =/2 (unify) on  Unix
    systems.   On  DOS systems it  will change the  directory-separator,
    limit  the filename length map dots,  except for the last one,  onto
    underscores.


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 alphanumerical 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 file  name  _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 after
    opening it for reading for cleanup):

    ____________________________________________________________________|                                                                    |
    | 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.    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..3355 UUsseerr TToopp--lleevveell MMaanniippuullaattiioonn


bbrreeaakk
    Recursively  start a new  Prolog top level.   This Prolog top  level
    has its own  stacks, but shares the heap with all break environments
    and  the top level.  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  the
    -t toplevel  command  line  option is  given  this goal  is  started
    instead of entering the default interactive top level (prolog/0).


aabboorrtt
    Abort  the Prolog  execution  and restart  the top  level.   If  the
    -t toplevel  command  line options  is given  this  goal is  started
    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'.

    ____________________________________________________________________|                                                                    |
    | ?- catch((repeat,fail), E, true).                                  |

    | ^CAction (h for help) ? abort                                      |
    ||%_Execution_Aborted_______________________________________________ ||


hhaalltt                                                              _[_I_S_O_]
    Terminate  Prolog  execution.   Open  files are  closed  and if  the
    command  line option  -tty is  not active the  terminal status  (see
    Unix  stty(1)) is restored.  Hooks may be registered both  in Prolog
    and  in foreign code.  Prolog hooks  are registered using at_halt/1.
    halt/0 is equivalent to halt(0).


hhaalltt((_+_S_t_a_t_u_s))                                                     _[_I_S_O_]
    Terminate  Prolog  execution  with  given  status.    Status  is  an
    integer.  See also halt/0.


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 2.8.


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
    <_N_a_m_e>= <_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..3366 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 on 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..3377 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 2.9.

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 can
    not 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  redirects 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
    Reverts 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  parameters  of  all  stacks  is  enlarged
    to  8  K-cells  if debugging  is  switched  off to  avoid  excessive
    GC.   GC  complicates   tracing  because   it  renames   the  __G<_N_N_N>
    variables   and  replaces  unreachable   variables  with  the   atom
    \bnfmeta{garbage_collected}.     Calling nodebug/0  does  _n_o_t  reset
    the  initial free-margin because several  parts of the toplevel  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 4.4.


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 port 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))
    Set  style checking options.   _S_p_e_c  is either  +<_o_p_t_i_o_n>, -<_o_p_t_i_o_n>,
    ?(<_o_p_t_i_o_n>) or  a list  of  such options.    +<_o_p_t_i_o_n> sets a  style
    checking  option,  -<_o_p_t_i_o_n> clears it  and ?(<_o_p_t_i_o_n>) succeeds  or
    fails  according to the current setting.  consult/1  and derivatives
    resets the style  checking options to their value before loading the
    file.   If---for  example---a file containing  long atoms should  be
    loaded the user can start the file with:

    ____________________________________________________________________|                                                                    |
    ||:-_style_check(-atom).____________________________________________ ||

    Currently available options are:

    ____________________________________________________________________
    |_Name__________|Default_|Description_______________________________|
    | singleton     |  on    |                                          |

    |               |        |read_clause/1 (used by  consult/1)  warns |
    |               |        |on variables  only  appearing once  in  a |
    |               |        |term  (clause)  which  have  a  name  not |
    |               |        |starting  with  an   underscore.      See |
    |               |        |section 2.15.1.5 for details on  variable |
    ||atom          || on    |handling|and warnings.                    ||

    |               |        |read/1 and  derivatives will  produce  an |
    |               |        |error message on quoted atoms or  strings |
    |               |        |longer than 5 lines.                      |
    | dollar        |  off   |Accept dollar as a lower case  character, |

    |               |        |thus avoiding the need for quoting  atoms |
    |               |        |with dollar  signs.   System  maintenance |
    |               |        |use only.                                 |
    | discontiguous |  on    |Warn if the clauses  for a predicate  are |
    |               |        |not together in the same source file.     |
    | string        |  off   |Backward    compatibility.            See |
    |               |        |the     Prolog     flag     double_quotes |
    |               |        |(current_prolog_flag/2).                  |

    | charset       |  off   |Warn on atoms and variables holding  non- |
    |               |        |ASCII characters  that  are  not  quoted. |
    |_______________|________|See_also_section_2.15.1.1.________________|


44..3388 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  4.2.   The  last part  of the  table
    contains  keys for compatibility  with other Prolog  implementations
    (Quintus)  for improved  portability.   Note that  the ISO  standard
    does  not  define  methods to  collect  system  statistics.    Space
    unit  is bytes.   Times  are in seconds,  represented as a  floating
    point  number.    The Quintus  compatibility keys  express times  in
    milliseconds.
_________________________________________________________________________
| agc                    |Number of atom garbage-collections performed   |
| agc_gained             N|umber of atoms removed                        |
| agc_time               T|ime spent in atom garbage-collections         |
| cputime                |(User) cpu  time since  Prolog  was started  in|
|                        |seconds                                        |
| inferences             |Total number  of passes via  the call and  redo|

|                        |ports since Prolog was started.                |
| heap                   |Estimated  total   size   of  the   heap   (see|
|                        |section 2.18.1.1)                              |
| heapused               |Bytes heap in use by Prolog.                   |
| heaplimit              |Maximum   size   of   the   heap    (see   sec-|
|                        |tion 2.18.1.1)                                 |
| c_stack                S|ystem (C-) stack limit.  0 if not known.      |
| stack                  |Total memory in use for stacks in all threads  |

| local                  |Allocated size of the local stack in bytes.    |
| localused              |Number of bytes in use on the local stack.     |
| locallimit             |Size to  which the  local stack  is allowed  to|
|                        |grow                                           |
| 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                                           |
| trail                  |Allocated size of the trail stack in bytes.    |
| trailused              |Number of bytes in use on the trail stack.     |
| traillimit             |Size to  which the  trail stack  is allowed  to|
|                        |grow                                           |
| atoms                  |Total number of defined atoms.                 |
| functors               |Total number of defined name/arity pairs.      |
| predicates             |Total number of predicate definitions.         |

| modules                |Total number of module definitions.            |
| codes                  |Total amount of byte codes in all clauses.     |
| threads                |MT-version:  number of active threads          |
| threads_created        M|T-version:  number of created threads         |
| thread_cputime         M|T-version:  seconds CPU time used  by finished|
|                        t|hreads.   Supported on  Windows-NT and  later,|
|                        L|inux and  possibly  a few  more.    Verify  it|

|________________________g|ives_plausible_results_before_using.__________|
|_______________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 |
|                        s|econds.  See 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, 0 ]                               |
| garbage_collection     [| number of  GC,  bytes  gained,  time  spent, |
|                        b|ytes left  ] The last  column is a  SWI-Prolog|

|                        e|xtension.     It  contains  the  sum   of  the|
|                        m|emory  left  after   each  collection,   which|
|                        c|an  be  divided  by  the  count  to  find  the|
|                        a|verage  working   set  size   after  GC.   Use|
|                        [|Count, Gained, Time|_]for compatiblity.       |
| stack_shifts           [|global  shifts,  local shifts,  time spent  ] |
|                        (|fails if no shifter in this version)          |
| atoms                  |[ number, memory use, 0 ]                      |
| atom_garbage_collection[|number of AGC, bytes gained, time spent ]     |

|_core___________________|Same_as_memory_________________________________|

                   Table 4.2:  Keys for statistics/2


ssttaattiissttiiccss
    Display a table of system statistics on the current output stream.


ttiimmee((_:_G_o_a_l))
    Execute  _G_o_a_l just  like once/1  (i.e., leaving  no choice  points),
    but  print used time, 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.


44..3399 EExxeeccuuttiioonn pprrooffiilliinngg

This section  describes the  hierarchical execution profiler  introduced
in  SWI-Prolog 5.1.10.    This profiler  is based  on  ideas from  gprof
described  in [Graham _e_t _a_l_., 1982].     The profiler  consists  of  two
parts:   the  information-gathering  is 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 representation of results.


44..3399..11 PPrrooffiilliinngg pprreeddiiccaatteess

Currently, the interface is  kept compatible with the old profiler.   As
experience grows, it is  likely that the old interface is  replaced with
one that  better reflects the  new capabilities.   Feel free to  examine
the internal interfaces and report useful application thereof.


pprrooffiillee((_:_G_o_a_l))
    Execute  _G_o_a_l just like time/1, collecting profiling  statistics and
    call  show_profile(_p_l_a_i_n_, _2_5).   With  XPCE installed  this opens  a
    graphical interface to the collected profiling data.


pprrooffiillee((_:_G_o_a_l_, _+_S_t_y_l_e_, _+_N_u_m_b_e_r))
    Execute  _G_o_a_l just like  time/1.   Collect profiling statistics  and
    show  the top _N_u_m_b_e_r  procedures on the  current output stream  (see
    show_profile/1) using _S_t_y_l_e.   The results are kept in  the database
    until  reset_profiler/0or  profile/3 is called and can  be displayed
    again  with show_profile/1.  The  profile/1 predicate is a  backward
    compatibility interface to  profile/1.  The other predicates in this
    section are low-level predicates for special cases.


sshhooww__pprrooffiillee((_+_S_t_y_l_e_, _+_N_u_m_b_e_r))
    Show  the collected  results  of the  profiler.   It  shows the  top
    _N_u_m_b_e_r predicates according  the percentage cpu-time used.  If _S_t_y_l_e
    is  plain the time spent in the predicates itself is displayed.   If
    _S_t_y_l_e  is cumulative  the time  spent in its  siblings (callees)  is
    added to the predicate.

    This  predicate first calls  prolog:show_profile_hook/2.   If XPCE  is
    loaded  this hook is used to  activate a GUI interface to  visualise
    the profile results.


sshhooww__pprrooffiillee((_+_N_u_m_b_e_r))
    Compatibility.  Same as show_profile(_p_l_a_i_n_, _N_u_m_b_e_r).


pprrooffiilleerr((_-_O_l_d_, _+_N_e_w))
    Query  or  change the  status of  the profiler.    The  status is  a
    boolean  (true or  false)  stating whether  or not  the profiler  is
    collecting  data.   It can  be used to  enable or disable  profiling
    certain parts of the program.


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  spend 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..3399..22 VViissuuaalliizziinngg pprrooffiilliinngg ddaattaa

Browsing the annotated  call-tree as described in section 4.39.3  itself
is  not very  attractive.    Therefore,  the  results are  combined  per
predicate,  collecting  all _c_a_l_l_e_r_s  and  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>
are  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  spend  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..3399..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 the 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 a some arbitrary 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 4.39.3.1 for details.


44..3399..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 milliseconds
CPU time  used by  Prolog since the  last time it  was fired.   If  this
value is non-zero, active predicates are incremented with this value.


44..4400 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 multi-threaded  versions
    the   actual  collection  is  delayed  until  there  there   are  no
    threads  performing  normal  garbage  collection.     In  this  case
    garbage_collect_atoms/0  returns immediately.    Note  this  implies
    there  is no guarantee  it will _e_v_e_r happen  as there may always  be
    threads performing garbage collection.


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(argValue)  pairs.    _V_a_l_u_e  can  be an  arithmetic  integer
    expression.   E.g., to specify a 2Gb 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.

    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..4411 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.

See also section 9.2.3 for loading Windows DLL's into SWI-Prolog.


44..4411..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")]').                       |
|                                                                        |

|Yes                                                                     |
|                                                                        |
|4 ?- close_dde_conversation(0).                                         |
|                                                                        |
|Yes|___________________________________________________________________ |   |

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.    If unsuccessful, _V_a_l_u_e  will be  unified with a  term
    of  form error(<_R_e_a_s_o_n>),  identifying the problem.   This call  uses
    SWI-Prolog  string objects  to return  the value  rather then  atoms
    to  reduce the  load on  the atom-space.    See section  4.22 for  a
    discussion on this data type.


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  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.   Command
    is passed as data of type CF_TEXT.


44..4411..22 DDDDEE sseerrvveerr mmooddee

The (autoload)  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 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..4422 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 `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 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%').           |
    |                                                                    |

    ||Yes_______________________________________________________________ ||


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..  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  is derived from  the Quintus Prolog module  system.   The
Quintus  module system  has  been the  starting  points for  the  module
systems of a number of mainstream Prolog systems, such  as SICStus, Ciao
and YAP.

This  chapter motivates  and  describes  the SWI-Prolog  module  system.
Novices can  start using  the module  system after  reading section  5.2
and section 5.3.   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 5.4.
Section 5.5  to section  5.8 describe  more advanced issues.    Starting
with section  5.9, we discuss more  low-level aspects of the  SWI-Prolog
module systems  that are used  to implement  the visible module  system,
and can be used to build other code reuse mechanisms.


55..11 WWhhyy UUssiinngg 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.


55..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  and exporting 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 4.23.

    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.


55..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.  I.e.,  modules are imported based on  their
file name rather than their module name.


uussee__mmoodduullee((_+_F_i_l_e_s))
    Load  the  file(s) specified  with _F_i_l_e  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 is not  a
    module file.


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 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  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  as
    possible  changes to  the  actual code.    See also  section 13  and
    section 5.7.

    ____________________________________________________________________|                                                                    |
    | :- use_module(library(lists), [ member/2,                          |
    |                                 append/2 as list_concat            |
    |                               ]).                                  |

    ||:-_use_module(library(option),_except([meta_options/3]))._________ ||

The  module/2 directive,  use_module/1 and  use_module/2 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.


55..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,  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  lookup 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 denotes  _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, G).                                            |
|                                                                        |

|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 bound (i.e.,  nonvar)
         on entry.

    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 <_a_t_o_m> is an atom denoting the  name
    of a  module and <_t_e_r_m> itself is not a :/2 term.  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 5.15.


55..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 5.12.

Direct addressing  of modules is  achieved using a  :/2 explicitly in  a
program  and rely  on the  module qualification  mechanism described  in
section 5.4.  Here are a few examples:

________________________________________________________________________|                                                                        |
|?- assert(world:done).  % asserts done/0 into module world              |

|?- world:assert(done).  % the same                                      |
|?-|world:done.__________%_calls_done/0_in_module_world_________________ |  |


55..66 IInntteerraaccttiinngg wwiitthh mmoodduulleess ffrroomm tthhee ttoopplleevveell

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 toplevel 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).                                                  |
    |                                                                    |
    | Yes                                                                |

    | tex: 2 ?- listing(file_of_label/2).                                |
    ||..._______________________________________________________________ ||


55..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_modules/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.


55..88 OOppeerraattoorrss aanndd mmoodduulleess

Operators  (section  4.23) are  local  to  modules,  where  the  initial
table  behaves  as   if  it  is  copied   from  the  module  user   (see
section 5.10).    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 7).  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,                                                    |
|            ...                                                         |
||_________]).__________________________________________________________ ||


55..99 DDyynnaammiicc iimmppoorrttiinngg uussiinngg iimmppoorrtt mmoodduulleess

Until now  we discussed the  public module interface  that is, at  least
to some  extent, portable  between Prolog implementation  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 5.10.

The list  of import  modules can  be manipulated and  queried using  the
following predicates:


sseett__bbaassee__mmoodduullee((_:_M_o_d_u_l_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.


iimmppoorrtt__mmoodduullee((_+_M_o_d_u_l_e_, _-_I_m_p_o_r_t))
    True  if _I_m_p_o_r_t  is defined as  an import  module for _M_o_d_u_l_e.    All
    normal  modules only import  from user,  which imports from  system.
    The predicates  add_import_module/3and delete_import_module/2 can be
    used to manipulate the import list.


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.


55..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.


55..1111 AAnn aalltteerrnnaattiivvee iimmppoorrtt//eexxppoorrtt iinntteerrffaaccee

The use_module/1 predicate  from section 5.3  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 5.12, 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.


55..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),                                          |

||__world_a:set_prolog_flag(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  specifying  the   import  module  as
described in section 5.9.

________________________________________________________________________|                                                                        |

|?- world_b:export(solve(_,_)).          % exports solve/2 from world_b  |
|?-|world_c:import(world_b:solve(_,_)).__%_and_import_it_to_world_c_____ |  |


55..1133 TTrraannssppaarreenntt pprreeddiiccaatteess::  ddeeffiinniittiioonn aanndd ccoonntteexxtt mmoodduullee

The   qualification  of   module   sensitive  arguments   described   in
section  5.4 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 is 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 5.4, 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  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.


55..1144 QQuueerryy tthhee mmoodduullee ssyysstteemm

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:

    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.


55..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  mechanisms can  be used  to realise a  simple object  oriented
    system or 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.

    ____________________________________________________________________|                                                                    |
    ||:-_op(precedence,_type,_user:(operatorname))._____________________ ||


CChhaapptteerr 66..  SSPPEECCIIAALL VVAARRIIAABBLLEESS AANNDD CCOORROOUUTTIINNIINNGG

This  chapter  deals  with  extensions  primarily  designed  to  support
constraint logic  programming (CLP).  The low-level attributed  variable
interface defined  in in  section 6.1  is not intended  for the  typical
Prolog programmer.   Instead, the  typical Prolog programmer should  use
the  coroutining predicates  and the  various  constraint solvers  built
on top  of attributed  variables.   CHR (section  7) provides a  general
purpose constraint handling language.

As a  rule of  thumb, constraint  programming reduces  the search  space
by reordering  goals and  joining goals based  on domain  knowledge.   A
typical example  is constraint reasoning  over integer  domains.   Plain
Prolog has no  efficient means to deal  with (integer) X >0  and X <3.
At best  it could translate  X >0 with  uninstantiated X  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.   Instead,  a constraint  system  will _d_e_l_a_y  an
uninstantated goal to X >0.  If,  later, it finds a value for _X it will
execute the test.   If it finds X <3 it will  combine this knowledge to
infer that X  is in 1..2 (see below).   If never finds a  concrete value
for _X it  can be asked to _l_a_b_e_l _X  and produce 1 and 2  on backtracking.
See section 11.7.

________________________________________________________________________|                                                                        |
|1 ?- [library(clpfd)].                                                  |
|...                                                                     |
|true.                                                                   |

|                                                                        |
|2 ?- X #> 0, X #< 3.                                                    |
|X|in_1..2._____________________________________________________________ | |

Using constraints generally makes your program more _d_e_c_l_a_r_a_t_i_v_e.   There
are some caveats though:

  o Constraints and cuts to  not merge well.  A cut after a goal that is
    delayed prunes the search-space before the condition is true.

  o Term-copying    operations   (assert/1,    restract/2,    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.


66..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  [Holzbaur, 1992]  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 [Demoen, 2002].   This interface is simple and  available on
all Prolog  systems that can  run the Leuven CHR  system (see section  7
and the Leuven 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 it can be  unified with.
In the second clause  first associates the domain with a  fresh variable
and then unifies X to this variable to deal with  the possibility that X
already has a domain.   The predicate attr_unify_hook/2is 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),
simply 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/3 is  used
to  translate remaining  attributes to  user-readable goals  that,  when
executed, reinstate these attributes.


66..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  a
    representation  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  whether or not the named attribute is
    present.


66..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 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))
    Hook  that must  be  defined in  the module  an attributed  variable
    refers  to.   Is 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.
    Normally  this  predicate  fails to  veto  binding the  variable  to
    _V_a_r_V_a_l_u_e,  forcing backtracking to  undo the binding.   If  _V_a_r_V_a_l_u_e
    is  another  attributed variable  the hook  often  combines the  two
    attribute and associates  the combined attribute with _V_a_r_V_a_l_u_e using
    put_attr/3.


aattttrr__ppoorrttrraayy__hhooookk((_+_A_t_t_V_a_l_u_e_, _+_V_a_r))
    Called by  write_term/2and 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.    New  infrastructure
    dealing  with  communicating  attribute  values  must  be  based  on
    copy_term/3 and its hook attribute_goals//1.


aattttrriibbuuttee__ggooaallss((_+_V_a_r)) //
    This  nonterminal,  if  it  is  defined in  a  module,  is  used  by
    copy_term/3 to project attributes of that  module to residual goals.
    It  is also  used by  the toplevel  to obtain  residual goals  after
    executing a query.


66..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,_G_s) 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  toplevel to  report  pending
    attributes  in  a   portable  and  understandable  fashion.     This
    predicate  is  the preferred  way to  reason  about and  communicate
    terms with constraints.


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.    I.e., 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.    I.e., scanning the  term is  aborted after the  first
    attributed variable is found.


66..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 variables.   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.


66..22 CCoorroouuttiinniinngg

Coroutining  deals with  having  Prolog  goals scheduled  for  execution
as  soon  as  some  conditions are  fulfilled.     In  Prolog  the  most
commonly used  condition is the instantiation  (binding) of a  variable.
Scheduling  a goal  to execute  immediately after  a  variable is  bound
can be used  to avoid instantiation errors for some  built-in predicates
(e.g. arithmetic),  do work _l_a_z_y, prevent  the binding of a variable  to
a particular  value, etc.   Using freeze/2 for  example we can define  a
variable can only be assigned an even number:

________________________________________________________________________|                                                                        |
|?- freeze(X, X mod 2 =:= 0), X = 3                                      |

|                                                                        |
|No|____________________________________________________________________ |  |


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   variable
    associated  with the module  when.   It is  defined in the  autoload
    library when.


ddiiff((_@_A_, _@_B))
    The  dif/2 predicate  provides  a constraint  stating that  _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
    and  finally, if _A and _B  can unify, goals are delayed  that prevent
    _A  and  _B to  become  equal.    The dif/2  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   variable
    associated  with the  module dif.   It  is defined  in the  autoload
    library dif.


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 debugging programs  using coroutining or  constraints.
    Consider   a  program  that  poses  contracting  constraints   on  a
    variable.   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 variables or whose  attributes
    are modified by  _G_o_a_l, regardless or not whether these variables are
    reachable from the arguments of _G_o_a_l.

    The  predicate has considerable implications.  During  the execution
    of   _G_o_a_l,  the  garbage  collector  does  not   reclaim  attributed
    variables.   This  causes some  degradation of GC  performance.   In
    a  well-behaved program there  are no such  variables, so the  space
    impact  is generally  minimal.   The  actual collection  of _V_a_r_s  is
    implemented using a scan of the trail- and global stacks.


66..33 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 from 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  to 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  called
exception/3.  The latter technique is by CHR (see chapter 7.


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  replaces  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 either  using  non-backtrackable  or
    backtrackable assignment,  using nb_getval/2can be  used to document
    that the variable is used non-backtrackable.


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.  Please 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.


nnbb__ddeelleettee((_+_N_a_m_e))
    Delete the named global variable.


66..33..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 if 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 constructing  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.


CChhaapptteerr 77..  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://www.cs.kuleuven.be/~toms/CHR/)
you can find more related papers, references and example programs.


77..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, 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  [Fr"uhwirth, 1998].   More background on CHR  can be found  at
[Fr"uhwirth,].

In  section 7.2  we present  the syntax  of CHR  in  Prolog and  explain
informally its  operational semantics.    Next, section  7.3 deals  with
practical issues  of writing  and compiling  Prolog programs  containing
CHR.  Section  7.4  explains  the  currently   primitive  CHR  debugging
facilities.  Section  7.4.3 provides a few useful predicates  to inspect
the constraint  store and section 7.5  illustrates CHR with two  example
programs.  In section 7.6 some compatibility issues  with older versions
of this system and SICStus' CHR system.   Finally, section 7.7 concludes
with a few practical guidelines for using CHR.


77..22 SSyynnttaaxx aanndd SSeemmaannttiiccss


77..22..11 SSyynnttaaxx

The syntax of CHR rules is the following:

________________________________________________________________________|                                                                        |
|rules --> rule, rules.                                                  |

|rules --> [].                                                           |
|                                                                        |
|rule --> name, actual_rule, pragma, [atom('.')].                        |
|                                                                        |
|name --> atom, [atom('@')].                                             |
|name --> [].                                                            |
|                                                                        |
|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 --> [].                                                           |
|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.


77..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 constraint can  be found, the matching  fails
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  their
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 semantical  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  behavior 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 options enables or  disables the possibility to debug  the
         CHR code.    Possible values  are on (default)  and off.    See
         section 7.4  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.


77..33 CCHHRR iinn SSWWII--PPrroolloogg PPrrooggrraammss


77..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.


77..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.  E.g.

    ____________________________________________________________________|                                                                    |
    | :- 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 by the type clash error:

    ____________________________________________________________________|                                                                    |
    | CHR compiler ERROR:                                                |
    |     `--> Type clash for variable _G5398 in rule foobar:            |
    |                 expected type foo in body goal def(_G5398, _G5448) |
    ||________________expected_type_bar_in_head_def(_G5448,__G5398)_____ ||

    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.__________________________________________ ||

    in  the head of the rule bar appears 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.   E.g.
    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.


77..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  of  the
format below.

________________________________________________________________________|                                                                        |
|:-|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.


77..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.


77..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  constraints  tries a  rule  with possibly  some  passive
    constraints.  The  try port is entered just before committing to the
    rule.

aappppllyy
    An  active constraints commits to a rule with possibly  some passive
    constraints.   The  apply port is  entered just after committing  to
    the rule.


77..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.


77..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
    De-activate 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 7.4.1 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.


77..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)                                              |
    |                                                                    |
    | X = _G23837{leq = ...}                                             |

    | Y = _G23838{leq = ...}                                             |
    | Z = _G23841{leq = ...}                                             |
    |                                                                    |
    ||Yes_______________________________________________________________ ||

    When  the  query  succeeds,  the  SWI-Prolog  top-level  prints  the
    content  of  the  CHR constraint  store  and displays  the  bindings
    generate  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                                                              |
    |                                                                    |
    ||Yes_______________________________________________________________ ||


77..66 BBaacckkwwaarrddss CCoommppaattiibbiilliittyy


77..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 programmer should be  aware
    of  the appropriate meaning of the  Prolog goals used in guards  and
    bodies of CHR rules.


77..66..22 TThhee OOlldd EECCLLiiPPSSee CCHHRR iimmpplleemmeennaattiioonn

The old  ECLiPSe CHR implementations  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.


77..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 loose  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 toplevel constraint symbol.


77..88 CCoommppiilleerr EErrrroorrss aanndd WWaarrnniinnggss

In  this section  we  summarize the  most  important error  and  warning
messages of the CHR compiler.


77..88..11 CCHHRR CCoommppiilleerr EErrrroorrss

TTyyppee ccllaasshh  for variable ...  in rule ...

    This  error indicates  an inconsistency  between declared  types;  a
    variable should 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 constrained 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 88..  MMUULLTTII--TTHHRREEAADDEEDD 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
    Todays   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 8.8.

  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  multi-threading  is  based  on  the  POSIX  thread  standard
[Butenhof, 1997] used  on most  popular systems  except for  MS-Windows.
On Windows  it uses the pthread-win32  emulation of POSIX threads  mixed
with the Windows native API for smoother and faster operation.


88..11 CCrreeaattiinngg aanndd ddeessttrrooyyiinngg PPrroolloogg tthhrreeaaddss


tthhrreeaadd__ccrreeaattee((_:_G_o_a_l_, _-_I_d_, _+_O_p_t_i_o_n_s))
    Create  a new Prolog thread  (and underlying C-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.   _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 named  may be
         used to refer to the thread and remains valid  until the thread
         is joined (see thread_join/2).

    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  _G_o_a_l is  called.    Using
         thread_at_exit/1,  the thread  may be  signalled or  run out  of
         resources before thread_at_exit/1is reached.

    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.

    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
    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_, _-_S_t_a_t_u_s))
    Wait  for the termination of thread with  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 not-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 6.3.   _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.    As  these  hooks  are run,  the  return-code  is
    already  available  through thread_property/2  using the  result  of
    thread_self/1  as thread-identifier.    See  also the  at_exit(_G_o_a_l)
    argument of thread_create/3.


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.


88..22 MMoonniittoorriinngg tthhrreeaaddss

Normal multi-threaded 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 8.5, describing more high-level primitives.


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 numerical 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.

    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.

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

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  and CPU  time  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  times the calling  thread has to wait  for
    the  mutex.   The  collision-count is not  available on  MS-Windows.
    Generally collision count is close to zero on single-CPU hardware.


88..33 TThhrreeaadd ccoommmmuunniiccaattiioonn


88..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.


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__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 not-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.


mmeessssaaggee__qquueeuuee__ccrreeaattee((_?_Q_u_e_u_e))
    If  _Q_u_e_u_e is an atom, create a  named queue.  To avoid  ambiguity of
    thread_send_message/2, the name  of a queue may  not be in use as  a
    thread-name.  If  _Q_u_e_u_e is unbound an anonymous queue is created and
    _Q_u_e_u_e is unified to its identifier.


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))
         Same as  message_queue_create(_A_l_i_a_s), but  according to the  ISO
         draft on Prolog threads.

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

tthhrreeaadd__ppeeeekk__mmeessssaaggee((_+_Q_u_e_u_e_, _?_T_e_r_m))
    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.

    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.

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 given Id and number of workers.              |
|                                                                        |
|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.                                                           |
|                                                                        |
|%       work(+Id, +Goal)                                                |
|%                                                                       |

|%       Post work to be done by the pool                                |
|                                                                        |
|work(Id, Goal) :-                                                       |
||_______thread_send_message(Id,_Goal)._________________________________ ||


88..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  multi-threaded   environments  should  be
handled  with  care as  the  receiving  thread  may hold  a  _m_u_t_e_x  (see
with_mutex).   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
    multi-threading,  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.


88..33..33 TThhrreeaaddss aanndd ddyynnaammiicc pprreeddiiccaatteess

Besides  queues (section  8.3.1)  threads can  share and  exchange  data
using dynamic  predicates.  The  multi-threaded 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  8.4
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 dynamic and volatile.

    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 feeling in favour or against, please  share them
    in the SWI-Prolog mailing list.


88..44 TThhrreeaadd ssyynncchhrroonniissaattiioonn

All  internal Prolog  operations  are thread-safe.    This  implies  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  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.

Here is how to realise a correct update:

________________________________________________________________________|                                                                        |
|:- initialization                                                       |

|        mutex_create(addressbook).                                      |
|                                                                        |
|change_address(Id, Address) :-                                          |
|        mutex_lock(addressbook),                                        |
|        retractall(address(Id, _)),                                     |
|        asserta(address(Id, Address)),                                  |
||_______mutex_unlock(addressbook)._____________________________________ ||


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.
    There is no limit to the number of mutexes that can be created.


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.    After this  call, _M_u_t_e_x_I_d  becomes invalid  and
    further references yield an existence_error exception.


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, the mutex becomes  available for
    locking  by other threads.   If another thread has locked the  mutex
    the calling thread is suspended until to 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
    Unlock  all  mutexes held  by the  current  thread.   This  call  is
    especially  useful  to handle  thread-termination using  abort/0  or
    exceptions.  See also thread_signal/2.


mmuutteexx__pprrooppeerrttyy((_?_M_u_t_e_x_I_d_, _?_P_r_o_p_e_r_t_y))
    True if Property is a property of MutexId.  Defined properties are:

    aalliiaass((_A_l_i_a_s))
         Mutex has  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  threads _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.


88..55 TThhrreeaadd--ssuuppppoorrtt lliibbrraarryy((tthhrreeaadduuttiill))

This library  defines a  couple of useful  predicates for  demonstrating
and debugging  multi-threaded 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.


88..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 3.5  (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.


88..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 4.39 for details on the
    execution profiler.


88..66 UUnnbboouunnddeedd tthhrreeaadd ccrreeaattiioonn

(SWI-)Prolog threads are  rather heavyweight objects, notably on  32-bit
systems,  because every  thread uses  a considerable  amount of  _v_i_r_t_u_a_l
address space.    SWI-Prolog threads  claim the stack  _l_i_m_i_t in  virtual
address space for  each of the runtime  stacks, while on 32-bit  systems
this resource  is generally limited  somewhere between  1GB and 3.5  GB,
depending on the operating system and operating configuration.

If SWI-Prolog starts  a thread it copies  the initial goal and starts  a
POSIX thread  which allocates a  new Prolog  engine that starts  proving
the given  goal.  If  allocation of the  engine fails, typically due  to
lack of virtual memory  space, the thread is still created  with minimal
(8 Kbyte)  stacks and  immediately calls  its exit  handlers.   See  the
option at_exit(_G_o_a_l).  Although this mechanism allows for  handling this
type of error  gracefully it is not safe to  rely on it.   Allocating an
engine that  nearly exhausts  virtual address space  may cause  failures
in normal memory  allocation that can appear  anywhere in Prolog or  the
foreign libraries used  by it.   Such errors typically kill the  process
with a fatal error.

Especially  on 32-bit  hardware,  the  design  of the  application  must
consider this issue and avoid ungraceful  termination being conservative
with the dynamic creation of new threads.


88..77 MMuullttii--tthhrreeaaddeedd mmiixxeedd CC aanndd PPrroolloogg aapppplliiccaattiioonnss

All foreign-code  linked to  the multi-threading  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 multi-threaded  C  and Prolog  application
you  should  first  familiarise  yourself  with  writing  multi-threaded
applications in C (C++).

If you are  using SWI-Prolog as an  embedded engine in a  multi-threaded
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 8.7.1 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 8.7.2 where threads  temporarily use a
Prolog engine.


88..77..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 8.7.2 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 exists or the unification result.


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.

    ____________________________________________________________________|                                                                    |
    | typedef struct                                                     |

    | { unsigned long     local_size;    /* Stack sizes (K-bytes) */     |
    |   unsigned long     global_size;                                   |
    |   unsigned long     trail_size;                                    |
    |   unsigned long     argument_size;                                 |
    |   char *            alias;         /* alias name */                |
    |   int              (*cancel)(int thread);                          |
    ||}_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  multi-threading,
    -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.


88..77..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 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.  Systems that use a large number of  threads that
    only infrequently need  to call Prolog, better 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  active
    internet  connection over a  pool of  threads.   If a Prolog  engine
    contains  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()  returned  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.


88..77..22..11 EEnnggiinneess iinn ssiinnggllee--tthhrreeaaddeedd SSWWII--PPrroolloogg

In  theory it  is possible  to  port the  API of  section  8.7.2 to  the
single-threaded  version of  SWI-Prolog.    This  allows  C-programs  to
control multiple  Prolog engines concurrently.   This  has not yet  been
realised.


88..88 MMuullttiitthhrreeaaddiinngg aanndd tthhee XXPPCCEE ggrraapphhiiccss ssyysstteemm

GUI applications  written in  XPCE can benefit  from the  multi-threaded
version of  XPCE/SWI-Prolog if  they need to  do expensive  computations
that block to UI in the single-threaded version.

Due  to  various  technical  problems  on  both   Windows  and  Unix/X11
threading is  best exploited by handing  long computations to their  own
thread.

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.

Some  tentative work  is  underway to  improve the  integration  between
XPCE  and multi-threaded  SWI-Prolog.   There  are two  sets of  support
predicates.    The  first model  assumes that  XPCE  is running  in  the
main thread  and background threads  are used for computation.   In  the
second model, XPCE  event dispatching runs in the background,  while the
foreground thread is used for Prolog.

XXPPCCEE  iinn  tthhee   ffoorreeggrroouunndd Using  XPCE  in  the  foreground   simplifies
debugging  of  the  UI  and  generally  provides  the  most  comfortable
development  environment.       The  GUI  creates   new  threads   using
thread_create/3  and,   after   work  in   the   thread  is   completed,
the  sub-thread  signals  the  main  thread  of   the  completion  using
in_pce_thread/1.


iinn__ppccee__tthhrreeaadd((_:_G_o_a_l))
    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.

XXPPCCEE iinn tthhee bbaacckkggrroouunndd

In this model a thread for  running XPCE is created using pce_dispatch/1
and actions are sent to this thread using pce_call/1.


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.


ppccee__ccaallll((_:_G_o_a_l))
    Post  _G_o_a_l to  the pce  thread,  executing it  synchronous with  the
    thread's  event-loop.  The pce_call/1 predicate returns  immediately
    without waiting.  Note that _G_o_a_l is _c_o_p_i_e_d to the pce thread.

For          further           information          about           XPCE
in         threaded         applications,           please         visit
http://gollem.science.uva.nl/twiki/pl/bin/view/Development/MultiThreadsXPCE


CChhaapptteerr 99..  FFOORREEIIGGNN LLAANNGGUUAAGGEE IINNTTEERRFFAACCEE

SWI-Prolog      offers      a     powerful      interface      to      C
[Kernighan & Ritchie, 1978].     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 an  query interface  and
an interface  to extract  multiple solutions  from an  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.


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

99..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 extensions calls  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..


99..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  9.2.3 for  a suitable  high-level interface  to
these predicates.


99..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 9.5 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.


99..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 plld(1)
utility  can be  used to  deal with  this in  a portable  manner.    The
typical commandline is:

________________________________________________________________________|                                                                        |
|plld|-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)),                        |
    ||______..._________________________________________________________ ||

    __________________________________________________________Parameters__F_i_l_e_S_p_e_cis  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.


99..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 9.2.3 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  (called dynamic  load
    library  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
    load_foreign_library/[1,2].

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

99..22..55 SSttaattiicc LLiinnkkiinngg

Below  is an  outline of  the files  structure  required for  statically
linking SWI-Prolog  with foreign extensions.    \ldots/pl 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.

    .../pl/runtime/<_a_r_c_h>/libswipl.a  SWI-Library
    .../pl/include/SWI-Prolog.h       Include file
    .../pl/include/SWI-Stream.h       Stream I/O include file
    .../pl/include/SWI-Exports        Export declarations (AIX only)
    .../pl/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  \ldots/pl/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_install_readline();                /* delete if not required */    |
|                                                                        |
|  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  using  the swipl-ld  utility  described  in
secrefplld.   If the  linking is performed  `by hand', the  command-line
option -dump-runtime-variables (see  section 2.4) can be used to  obtain
the  required paths,  libraries  and linking  options  to link  the  new
executable.


99..33 IInntteerrffaaccee DDaattaa ttyyppeess


99..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 the  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.

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 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   refs  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 9.2.

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

99..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 information
necessary to perform  its memory management without special  precautions
from the C-programmer.


99..33..22 OOtthheerr ffoorreeiiggnn iinntteerrffaaccee ttyyppeess

aattoomm__tt An atom in Prologs  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 C  a  character  string 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 loose their definition).

qqiidd__tt Query         Identifier.                          Used         by
    PL_open_query()/PL_next_solution()/PL_close_query() to  handle  back-
    tracking from C.

ffiidd__tt Frame         Identifier.                          Used         by
    PL_open_foreign_frame()/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 secrefshlib.

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
    outside  the long domain.  Robust code should not assume any  of the
    integer fetching functions  to succeed if the Prolog term is know to
    be an integer.


99..44 TThhee FFoorreeiiggnn IInncclluuddee FFiillee


99..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.


99..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((_l_o_n_g))
    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 30 bits  signed value (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.


_l_o_n_g PPLL__ffoorreeiiggnn__ccoonntteexxtt((_c_o_n_t_r_o_l___t))
    Extracts  the context from the context  argument.  In 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 as 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().

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 9.1 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 9.1:  Skeleton for non-deterministic foreign functions


99..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 9.4.2.1).


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

int PPLL__ffuunnccttoorr__aarriittyy(_f_u_n_c_t_o_r___t _f)
    Return the arity of the given functor.


99..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 multi-threaded  version (see  section 8),  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.


99..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.


99..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_ge_t*() 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) )                            |
    |         { ...;                                                     |
    ||________}_________________________________________________________ ||

    ___________________________________________________________________
    | PL_VARIABLE            |An unbound variable.   The value  of term|
    |                        |as such  is a  unique identifier  for the|
    |                        |variable.                                |
    | PL_ATOM                |A Prolog atom.                           |
    | PL_STRING              |A Prolog string.                         |
    | PL_INTEGER             |A Prolog integer.                        |

    | PL_FLOAT               |A Prolog floating point number.          |
    | PL_TERM                |A compound term.   Note that a  list is a|
    |________________________|compound_term_./2._______________________|

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__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 with functor ./2 or the
    atom [].  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 with functor ./2.   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).


99..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_, _i_n_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 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), 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 not needed any longer.

    With  the introduction of wide-characters (see section 2.17.1),  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.
    ___________________________________________________________________
    | CVT_ATOM               |Convert if term is an atom               |
    | CVT_STRING             |Convert if term is a string              |
    | CVT_LIST               |Convert  if term  is a  list of  integers|
    |                        |between 1 and 255                        |

    | CVT_INTEGER            |Convert if term is an integer (using %d) |
    | CVT_FLOAT              |Convert if term is a float (using %f)    |
    | CVT_NUMBER             |Convert if term is a integer or float    |
    | CVT_ATOMIC             |Convert if term is atomic                |
    | CVT_VARIABLE           |Convert variable to print-name           |
    | CVT_WRITE              |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.                                 |
    | CVT_WRITE_CANINICAL    |As CVT_WRITE, but use write_canonical/2. |
    | CVT_ALL                |Convert  if term  is  any  of the  above,|
    |________________________|except_for_CVT_VARIABLE_and_CVT_WRITE____|
    | CVT_EXCEPTION          |If conversion fails due  to a type error,|
    |                        |raise a  Prolog type  error exception  in|
    |________________________|addition_to_failure______________________|

    | BUF_DISCARDABLE        |Data must copied immediately             |
    | BUF_RING               |Data is stored in a ring of buffers      |
    | BUF_MALLOC             |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.|_
    | REP_ISO_LATIN_1        |(0,  default).   Text  is in ISO  Latin-1|
    |                        |encoding  and  the  call  fails  if  text|

    |                        |cannot be represented.                   |
    | REP_UTF8               |Convert  the  text  to  a  UTF-8  string.|
    |                        |This works for all text.                 |
    | REP_MB                 |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
    no 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.   Currently all Prolog  integers
    can  be  represented  using this  type,  but  this might  change  if
    SWI-Prolog introduces unbounded integers.


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 a 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  in-
    tegers,   but  need   some  manipulation  to   make  sure  they   do
    not  get  truncated   due  to  the  limited  Prolog  integer  range.
    PL_put_pointer()/PL_get_pointer() guarantees 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_, _i_n_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().


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 lookup or create the corresponding
    module and assign an opaque pointer to it over _m_o_d_u_l_e,.


int PPLL__ggeett__aarrgg(_i_n_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  (including),
    assign _a with a term-reference to the argument.


int _PPLL__ggeett__aarrgg(_i_n_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, nor whether  _t
    is actually a term, nor whether _i_n_d_e_x is a valid argument-index.


99..44..33..33 EExxcchhaannggiinngg tteexxtt uussiinngg lleennggtthh aanndd ssttrriinngg

All  internal text-representation  of  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 from length and characters.


const char * PPLL__aattoomm__nncchhaarrss(_a_t_o_m___t _a_, _s_i_z_e___t _*_l_e_n)
    Extract text and length of an atom.


99..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.


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.    Fails  (returns
    NULL)  if  _a_t_o_m  is  not  a  wide-character  atom.     This  is  the
    wide-character  version  of PL_atom_nchars().    Note  that only  one
    of  these functions  succeeds  on a  particular atom.    Especially,
    after  creating  an atom  with PL_new_atom_wchars(),  extracting  the
    text  using  PL_atom_wchars()will  fail  if the  atom only  contains
    ISO-Latin-1 characters.


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 _a_r_gtype 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.


99..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();      /* variable for the elements */|
|  term_t list = PL_copy_term_ref(l);    /* copy as we need to write */  |
|                                                                        |
|  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 [] */           |
|}|_____________________________________________________________________ | |


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 [] 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 [] 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 [] assign a term-reference to the tail to _t.


int PPLL__ggeett__nniill(_t_e_r_m___t _+_l)
    Succeeds if  represents the atom [].


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 [] and  _t_a_i_l is
         filled with []

    PPLL__PPAARRTTIIAALL__LLIISSTT
         The list is  `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.


99..44..33..66 AAnn eexxaammppllee::  ddeeffiinniinngg write/1 iinn CC

Figure  9.2 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 9.2:  A Foreign definition of display/1


99..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().


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 0-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 9.4.20.


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 ptr 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)
    Same as PL_put_functor(_l_, _P_L___n_e_w___f_u_n_c_t_o_r_(_P_L___n_e_w___a_t_o_m_(_"_._"), 2)).


void PPLL__ppuutt__nniill(_t_e_r_m___t _-_l)
    Same as PL_put_atom_chars(_"_[_]_").


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 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)
    Creates  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 and tail.   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.


99..44..55 UUnniiffyyiinngg ddaattaa

The  functions  of  this  sections  _u_n_i_f_y  terms  with  other  terms  or
translated C-data structures.   Except for PL_unify(), the functions  of
this section  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 show
    in the snippid 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.   Prolog types  is one of PL_ATOM, PL_STRING, PL_CODE_LIST  or
    PL_CHAR_LIST. Representations 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 0-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().


void 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 _*_c_h_a_r_s)
    Unify _t with  a Prolog string object created from the string created
    from  the _l_e_n/_c_h_a_r_s pair.  The data will be copied.   This interface
    can deal with 0-bytes in the string.  See also section 9.4.20.


int PPLL__uunniiffyy__iinntteeggeerr(_t_e_r_m___t _?_t_, _l_o_n_g _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__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  fails.
    Note  that this function does not  create a term if the argument  is
    already instantiated.


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 to _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
    is  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.    I.e. 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.   Similar, 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 an  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-bit 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 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  following
         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 build 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)");                                     |
    ||__..._____________________________________________________________ ||


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.


99..44..66 CCoonnvviieennccee ffuunnccttiioonnss ttoo ggeenneerraattee PPrroolloogg eexxcceeppttiioonnss

The  typical  implementation  of a  foreign  predicate  first  uses  the
PL_get_*() functions  to  extract  C  datatypes 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_atom_ex(), but raises a type or instantiation error if _t
    is not an atom.


int PPLL__ggeett__ffllooaatt__eexx(_t_e_r_m___t _t_, _d_o_u_b_l_e _*_f)
    ; As PL_get_atom_ex(), but raises a type or instantiation error if _t
    is not an atom.


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 not a variable.  See instantiation_error/1.


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.


99..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.


99..44..77..11 DDeeffiinniinngg aa BBLLOOBB ttyyppee

The  type PL_blob_t represents  a structure  with  the layout  displayed
above.  The structure contains additional fields at  the ...for internal
bookkeeping as well as future extension.

________________________________________________________________________|                                                                        |
|typedef struct PL_blob_t                                                |

|{ unsigned long         magic;          /* PL_BLOB_MAGIC */             |
|  unsigned long         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
or 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 field  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 then _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 and  respecting the
    _f_l_a_g_s.   The _f_l_a_g_s are a bitwise or  of zero or more of the PL_WRT_*
    flags  defined in SWI-Prolog.h.  This prototype is available if  the
    undocumented SWI-Stream.h is included _b_e_f_o_r_e SWI-Prolog.h.

    If  this function is not provided, write/1 emits the content  of the
    blob  for blobs of type PL_BLOB_TEXT or a string of  the format <#_h_e_x
    _d_a_t_a> for binary blobs.

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.


99..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  visa 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 9.4.7.1.


99..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  using
    mp_set_memory_functions().  This means SWI-Prolog must be initialised
    before  the  foreign  code  touches  any GMP  function.     You  can
    call  \funcref{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 allo-
    cation,  call \funcref{PL_action}{PL_GMP_SET_ALLOC_FUNCTIONS, FALSE}
    _b_e_f_o_r_e initializing 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 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  _T_R_U_E
    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  _T_R_U_E
    on  success.    Note  that  _t is  unified  with  an integer  if  the
    denominator is 1.  The _m_p_q argument is not changed.


99..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 next  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.


99..44..99..11 PPrreeddiiccaattee rreeffeerreenncceess

This  section  discusses   the  functions  used  to  communicate   about
predicates.   Though a Prolog predicate  may defined or not,  redefined,
etc., a Prolog predicate has a handle that is  not 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  a 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_, _i_n_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.


99..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 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 or  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_open_query() can return  a 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)
    Discards  the query,  but does not  delete any  of the data  created
    by  the query.  It just  invalidate _q_i_d, allowing for a new  call to
    PL_open_query() in this context.


void PPLL__cclloossee__qquueerryy(_q_i_d)
    As  PL_cut_query(), but  all data and  bindings created by the  query
    are destroyed.


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_, _m_o_d_u_l_e___t)
    Call term just like  the Prolog predicate once/1.  _T_e_r_m is called in
    the  specified module, or in the context  module if module_t  = NULL.
    Returns  TRUE if  the call succeeds,  FALSE otherwise.   Figure  9.3
    shows an example to  obtain the number of defined atoms.  All checks
    are omitted to improve readability.


99..44..1100 DDiissccaarrddiinngg DDaattaa

The Prolog  data created and  term-references needed  to setup the  call
and/or analyse  the result can  in most cases  be discarded right  after
the  call.   PL_close_query() allows  for  destructing the  data,  while
leaving the  term-references.   The calls below may  be used to  destroy
term-references and data.  See figure 9.3 for an example.


fid_t PPLL__ooppeenn__ffoorreeiiggnn__ffrraammee()
    Created  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  does not pop the frame.  I.e. the same frame
    can  be rewinded 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 9.3:  Calling Prolog


99..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 inner  most module  is  returned via  _m_o_d_u_l_e
    _*.   If  _r_a_w is  not a module  construct _a_r_g will  simply be put  in
    _p_l_a_i_n.   If _m_o_d_u_l_e _* is NULL  it will be set to the  context module.
    Otherwise  it will be left untouched.   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)
    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 or create a new module with name specified  by the
    atom _n_a_m_e.


99..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   to  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  and 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 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,    \funcref{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.


PL_clear_exception vvooiidd(_T)
    ells  Prolog that the encountered exception  must be ignored.   This
    function  must be called if control  remains in C after an  previous
    API calls fails with an exception..


99..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  4.10.
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.

Some versions of SWI-Prolog, notably running on  popular Unix platforms,
handle SIG_SEGV  for guarding  the Prolog stacks.    If the  application
wishes to handle  this signal too, it should use  PL_signal() to install
its handler  after initialising Prolog.   SWI-Prolog will  pass SIG_SEGV
to the user  code if it detected the  signal is not related to a  Prolog
stack overflow.

Any handler that  wishes to call one  of the Prolog interface  functions
should call PL_signal() for its installation.


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  or-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
    integer  signal number  in _s_i_g.   The  specification is an  integer,
    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.


99..44..1144 MMiisscceellllaanneeoouuss


99..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.


99..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.


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 accomodate 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 an 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 0-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.


99..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  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  a 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  file name in OS native (e.g.,  C:\x\y)
    notation.


99..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 4.9.


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.


99..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 in table 9.1.
    ___________________________________________________________________
    | PL_ACTION_TRACE        |Start Prolog tracer (trace/0).   Requires|
    |                        |no arguments.                            |
    | PL_ACTION_DEBUG        |Switch  on Prolog  debug mode  (debug/0).|
    |                        |Requires no arguments.                   |
    | PL_ACTION_BACKTRACE    |Print   backtrace   on   current   output|
    |                        |stream.   The  argument (an  int) is  the|
    |                        |number of frames printed.                |

    | PL_ACTION_HALT         |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.                                  |
    | PL_ACTION_ABORT        |Generate a Prolog abort  (abort/0).  This|

    |                        |call  does  not  return.     Requires  no|
    |                        |arguments.                               |
    | PL_ACTION_BREAK        |Create  a  standard  Prolog  break  envi-|
    |                        |ronment  (break/0).    Returns after  the|
    |                        |user  types  the  end-of-file  character.|
    ||                       |Requires|no arguments.                   ||

    | PL_ACTION_GUIAPP       |Win32:  Used to  indicate 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 simply  prints the|
    |                        |error and exits otherwise.               |
    | PL_ACTION_WRITE        |Write  the  argument,  a  char *  to  the|

    |                        |current output stream.                   |
    | PL_ACTION_FLUSH        |Flush  the current  output stream.    Re-|
    |                        |quires no arguments.                     |
    | PL_ACTION_ATTACH_CONSOLE|Attach a console  to a thread if  it does|
    ||                       |not|have one.  See attach_console/0.     ||
    | PL_GMP_SET_ALLOC_FUNCTIONS|TakesTRUandE,integertheargument.GMP  alIflocation|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  doc-|
    |                        |umentation.    The  action returns  FALSE|
    |                        |if  there is  no GMP  support  or GMP  is|
    |________________________|already_initialised._____________________|

                    Table 9.1:  PL_action() options


99..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 9.2.
    ___________________________________________________________________
    | 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  represented 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  encoding  of|
    |                        |Prolog (of type IOENC).                  |
    | PL_QUERY_USER_CPU      |Get  amount  of  user  CPU  time  of  the|
    |________________________|process_in_milliseconds._________________|

                     Table 9.2:  PL_query() options


99..44..1188 RReeggiisstteerriinngg FFoorreeiiggnn PPrreeddiiccaatteess


int PPLL__rreeggiisstteerr__ffoorreeiiggnn__iinn__mmoodduullee(_c_o_n_s_t _c_h_a_r _*_m_o_d_u_l_e_, _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)
    Register  a C-function 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_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.

    When  called in  Prolog, Prolog  will call  _f_u_n_c_t_i_o_n.   _f_l_a_g_s  forms
    bitwise or'ed list of options for the installation.  These are:
    ___________________________________________________________________
    | PL_FA_NOTRACE          |Predicate cannot be seen in the tracer   |
    | PL_FA_TRANSPARENT      |Predicate is module transparent          |
    | PL_FA_NONDETERMINISTIC |Predicate  is  non-deterministic.     See|
    |                        |also PL_retry().                         |

    |_PL_FA_VARARGS__________|Use_alternative_calling_convention.______|
    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  9.4.1.1).    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.


99..44..1199 FFoorreeiiggnn CCooddee HHooookkss

For various specific applications some hooks re 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(_v_o_i_d _(_*_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 on your operating  system)
    and  the _c_l_o_s_u_r_e argument passed to the PL_on_halt()call.   See also
    at_halt/1.


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);                                                |
    ||}_________________________________________________________________ ||


99..44..2200 SSttoorriinngg ffoorreeiiggnn ddaattaa

This section  provides some hints for  handling foreign data in  Prolog.
With foreign  data, we refer  to data that is  used by foreign  language
predicates  and  needs  to  be passed  around  in  Prolog.     Excluding
combinations, there are three principal options for storing such data

  o _N_a_t_u_r_a_l _P_r_o_l_o_g _d_a_t_a
    E.i.  using the  representation  one would  choose if  there was  no
    foreign interface required.

  o _O_p_a_q_u_e _p_a_c_k_e_d _P_r_o_l_o_g _d_a_t_a
    Data  can also be represented in  a foreign structure and stored  on
    the  Prolog stacks using  PL_put_string_nchars()and retrieved  using
    PL_get_string_chars().   It is generally good  practice to wrap  the
    string  in a compound term with arity 1, so Prolog can  identify the
    type.    portray/1 rules  may be  used to  streamline printing  such
    terms during development.

  o _N_a_t_u_r_a_l _f_o_r_e_i_g_n _d_a_t_a_, _p_a_s_s_i_n_g _a _p_o_i_n_t_e_r
    An  alternative is to pass  a pointer to the  foreign data.   Again,
    this functor may be 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  of which Prolog  never examines  the
    contents  of the  data itself.   If  the data is  opaque to  Prolog,
    the  chosen representation  does not  depend on  simple analysis  by
    Prolog,  and the selection  will be driven  solely by simplicity  of
    the interface and performance (both in time and space).

  o _H_o_w _b_i_g _i_s _t_h_e _d_a_t_a
    Is  efficient encoding required?   For examine, a boolean array  may
    be  expressed as  a compound  term, holding integers  each of  which
    contains a number of bits, or as a list of true and false.

  o _W_h_a_t _i_s _t_h_e _n_a_t_u_r_e _o_f _t_h_e _d_a_t_a
    For  examples in C,  constants are often  expressed using `enum'  or
    #define'd  integer values.   If  prolog needs  to handle this  data,
    atoms  are a more logical  choice.  Whether  or not this mapping  is
    used  depends on  whether Prolog  needs to interpret  the data,  how
    important debugging is and how important performance is.

  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
    We can distinguish three cases.

     1.  The lifetime is  dictated by the  accessibility of the data  on
         the Prolog stacks.   Their is no way by which the  foreign code
         when the  data becomes `garbage',  and the  data thus needs  to
         be represented  on the Prolog  stacks using Prolog  data-types.
         (2),

     2.  The  data lives  on  the  `heap' and  is  explicitly  allocated
         and deallocated.   In  this case,  representing the data  using
         native foreign representation and passing a pointer to  it is a
         sensible choice.

     3.  The data lives as  during the lifetime of a  foreign 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 9.4.1.1.


99..44..2200..11 EExxaammpplleess ffoorr ssttoorriinngg ffoorreeiiggnn ddaattaa

In this section, we will 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.   Finally,
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  and'ing and  or'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,
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  4.41) 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  using 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, not  to verify  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.


99..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)                                             |
|{                                                                       |
|#ifdef READLINE /* Remove if you don't want readline */                 |
|  PL_initialise_hook(install_readline);                                 |
|#endif                                                                  |
|                                                                        |
|  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
    at_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 9.5.

      o  Find the Prolog home  directory.  This process is  described in
         detail in section 9.6.

    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.


void PPLL__iinnssttaallll__rreeaaddlliinnee()
    Installs  the GNU-readline line-editor.  Embedded  applications that
    do  not use the Prolog  top-level should normally delete this  line,
    shrinking  the Prolog kernel significantly.   Note that the  Windows
    version does not use GNU readline.


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 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 PL_cleanup() is not called from  the
    main-thread.

    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 temporary 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()
    Close  file  descriptors associated  to  Prolog streams  except  for
    0,1  and 2.   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)
    Cleanup  the Prolog environment using PL_cleanup() and calls  exit()
    with  the status argument.  As PL_cleanup() can only be  called from
    the  main  thread,  this function  returns  FALSE when  called  from
    another thread as the main one.


99..44..2211..11 TThhrreeaaddiinngg,, SSiiggnnaallss aanndd eemmbbeeddddeedd PPrroolloogg

This section  applies to  Unix-based environments that  have signals  or
multi-threading.   The Windows version  is compiled for  multi-threading
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 applications however are by  nature multi-threaded
and appear to do signal-handling (software interrupts).

On Unix systems, SWI-Prolog uses three signals:

SSIIGGUUSSRR11  is used to sychronise atom- and clause garbage collection.  The
    handler  is installed at  the start  of GC and  reverted to the  old
    setting after completing.

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  to
    opportunity to react on thread-signals.

SSIIGGIINNTT  is used by the toplevel 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.

The --nosignals option can be used to inhibit processing  of SIGINT. The
other signals  are vital  for the functioning  of SWI-Prolog.   If  they
conflict with  other applications, signal  handling of either  component
must be modified.  The SWI-Prolog signals are defined  in pl-thread.h of
the source-distribution.


99..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 the normal  usage, a copy is  made of the default embedding  template
\ldots/pl/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++ sources (extensions  .cpp, .cxx, .cc or .C)  files
    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  passed -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.

 *
    I.e.  all other options.  These are passed as linker options  to the
    C-compiler.


99..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 9.4.

________________________________________________________________________|                                                                        |
|#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 9.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|________________________________________________________________ |      |


99..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 9.5).

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.


99..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 lower case letters.  Figure  9.5 shows the C-source
file, figure 9.6 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 9.5:  Lowercase source file

________________________________________________________________________|                                                                        |
|% gcc -I/usr/local/lib/pl-\plversion/include -fpic -c lowercase.c       |
|% gcc -shared -o lowercase.so lowercase.o                               |
|% swipl                                                                 |
|Welcome to SWI-Prolog (Version \plversion)                              |

|...                                                                     |
|                                                                        |
|1 ?- load_foreign_library(lowercase).                                   |
|                                                                        |
|Yes                                                                     |
|2 ?- lowercase('Hello World!', L).                                      |
|                                                                        |

|L = 'hello world!'                                                      |
|                                                                        |
|Yes|___________________________________________________________________ |   |

    Figure 9.6:  Compiling the C-source and loading the object file


99..88 NNootteess oonn UUssiinngg FFoorreeiiggnn CCooddee


99..88..11 MMeemmoorryy AAllllooccaattiioonn

SWI-Prolog's heap  memory allocation is based  on the malloc(3)  library
routines.     The  stacks  are  allocated  using  mmap()  on  most  Unix
machines and using  VirtualAlloc() on windows.  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.


99..88..22 CCoommppaattiibbiilliittyy bbeettwweeeenn PPrroolloogg vveerrssiioonnss

Great  care  is   taken  to  ensure  binary  compatibility  of   foreign
extensions  between  different   Prolog  versions.     Only  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().


99..88..33 DDeebbuuggggiinngg aanndd pprrooffiilliinngg ffoorreeiiggnn ccooddee ((vvaallggrriinndd))

This section  is only  relevant for  Unix users  on platforms  supported
by valgrind.   Valgrind is an excellent binary  intrumentation 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>______________________________________ | |


99..88..44 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 to 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.


99..88..55 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  uses <_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 1100..  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  different 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_, _+_L_i_s_t_O_f_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.

    _L_i_s_t_O_f_O_p_t_i_o_n_s  is a  list of  <_K_e_y>=<_V_a_l_u_e> or  <_K_e_y>(<_V_a_l_u_e>)  pairs.
    The available keys are described in table 10.1.
_________________________________________________________________________
|__KKeeyy________________||OOppttiioonn__||________TTyyppee____________||DDeessccrriippttiioonn__________________________________________________||
|| local      | --LL   ||    K-bytes    |Size (Limit) of local stack         |
| global     | --GG   ||    K-bytes    |Size (Limit) of global stack        |
| trail      | --TT   ||    K-bytes    |Size (Limit) of trail stack         |

| argument   | --AA   ||    K-bytes    |Size (Limit) of argument stack      |
| goal       | --gg   ||     atom      |Initialisation goal                 |
| toplevel   | --tt   ||     atom      |Prolog top-level goal               |
|_init_file___|--ff___||_____atom______|Personal_initialisation_file________||||||
| class      |      |     atom      |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.     |
| autoload   |      |     bool      |If true, run autoload/0 first       |
| map        |      |     file      |File to write info on dump          |
| op         |      | save/standard |Save operator declarations?         |

| stand_alone |     |     bool      |Include the emulator in the state   |
| emulator   |      |     file      |Emulator attached  to  the  (stand- |
|            |      |               |alone) executable.  Default  is the |
|____________|______|_______________|running_emulator.___________________|

          Table 10.1:  <_K_e_y> = <_V_a_l_u_e> pairs for qsave_program/2

    Before   writing  the  data   to  file,  qsave_program/2  will   run
    autoload/0  to all  required  autoloading the  system can  discover.
    See autoload/0.

    Provided  the  application  does  not  require  any  of  the  Prolog
    libraries  to  be  loaded  at  runtime,   the  only  file  from  the
    SWI-Prolog development  environment required is the emulator itself.
    The  emulator may  be built in  two flavours.   The  default is  the
    _d_e_v_e_l_o_p_m_e_n_t  _e_m_u_l_a_t_o_r.  The  _r_u_n_t_i_m_e _e_m_u_l_a_t_o_r is similar, but  lacks
    the tracer.

    If  the option  stand_alone(true) is  present, 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 build.

    See also section 2.10.2.4.


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  will not  depend  on one  of the  libraries.   The  predicate
    autoload/0  will find all ddiirreecctt references to predicates.   It does
    not  find predicates referenced via meta-predicates.   The predicate
    log/2  is  defined  in the  library(quintus)  to provide  a  quintus
    compatible means to compute  the natural logarithm of a number.  The
    following program will  behave correctly if its state is executed in
    an environment where the library(quintus) is not available:

    ____________________________________________________________________|                                                                    |
    | logtable(From, To) :-                                              |

    |         From > To, !.                                              |
    | logtable(From, To) :-                                              |
    |         log(From, Value),                                          |
    |         format('~d~t~8|~2f~n', [From, Value]),                     |
    |         F is From + 1,                                             |
    ||________logtable(F,_To).__________________________________________ ||

    However,  the following implementation  refers to log/2 through  the
    meta-predicate  maplist/3.   Autoload will not  be able to find  the
    reference.   This problem may be fixed either by loading  the module
    library(quintus)  explicitly or  use  require/1 to  tell the  system
    that the predicate log/2 is required by this module.

    ____________________________________________________________________|                                                                    |

    | logtable(From, To) :-                                              |
    |         findall(X, between(From, To, X), Xlist),                   |
    |         maplist(log, Xlist, SineList),                             |
    |         write_table(Xlist, SineList).                              |
    |                                                                    |
    | write_table([], []).                                               |
    | write_table([I|IT], [V|VT]) :-                                     |
    |         format('~d~t~8|~2f~n', [I, V]),                            |

    ||________write_table(IT,_VT).______________________________________ ||


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
    avoid  that the  clauses of dynamic  predicates that represent  data
    for the current session is saved in the state file.


1100..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 10.2 for details.

  o If  the program uses directives (:- goal. lines) that  perform other
    actions then  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.


1100..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.


1100..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.


1100..33..11 PPrreeddiiccaatteess DDeeffiinniittiioonnss


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  what  kind of  object  is  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 resources 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  programs 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  affect  the  running
    environment,  while the runtime  system quickly accesses the  system
    resources.


1100..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  is 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.


1100..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   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)                                                     |
||___________)._________________________________________________________ ||


1100..44..11 PPaassssiinngg aa ppaatthh ttoo tthhee aapppplliiccaattiioonn

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 1111..  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 explicitely or because  trapping unknown
    predicates  is disabled  (see unknown/2  and current_prolog_flag/2),
    library predicates must be loaded explicitely.

  o Using  libraries reduce  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 _i_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_.


1111..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
         with a ddiiffffeerreenntt ddeeffiinniittiioonn.

    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, 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 and  Distinguish (see below) generated  using
    findall/3.

TThhee DDiissttiinngguuiisshh aarrgguummeenntt  The  versions  with  4  arguments   provide  a
    Distinguish argument that  allow for keeping duplicate bindings of a
    variable  in the result.   For  example, if we  wish to compute  the
    total  population of all  countries we do  not want to lose  results
    because two countries have the same population.  Therefore we use:

    ____________________________________________________________________|                                                                    |
    ||____aggregate(sum(P),_Name,_country(Name,_P),_Total)______________ ||

All  aggregation predicates  support  the  following operator  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.  I.e.   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 Expr for all solutions.

mmiinn((_E_x_p_r))
    Minimum of Expr 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 Expr
    over  all Solution  and  Witness is  any other  template applied  to
    Solution that produced  Min.  If multiple solutions provide the same
    minimum, Witness corresponds to the first solution.

mmaaxx((_E_x_p_r))
    Maximum of Expr 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.


1111..11..00..11 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/3
    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.


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/3  version performs  findall/3 followed  by sort/2  on
    _G_o_a_l.


ffoorreeaacchh((_:_G_e_n_e_r_a_t_o_r_, _:_G_o_a_l))
    True  if the  conjunction of  instances of _G_o_a_l  using the  bindings
    from   _G_e_n_e_r_a_t_o_r  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  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.                       |
    ||No________________________________________________________________ ||

         bbuugg _G_o_a_l  is copied  repeatetly, 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_]
    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, or bagof

    free_variables(_G_e_n_e_r_a_t_o_r,  _T_e_m_p_l_a_t_e, 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?


1111..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 succeed.    True if _L_i_s_t_2  contains
    those elements Xi of _L_i_s_t_1 for which call(_G_o_a_l, 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(_G_o_a_l, 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(_P_r_e_d, 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  list according to _P_r_e_d in three  sets.  For each  element Xi
    of  _L_i_s_t, its  destination is determined  by call(_P_r_e_d, 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  succesfully 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))
    True  if _G_o_a_l can succesfully be  applied to all succesive pairs  of
    elements of _L_i_s_t_1 and _L_i_s_t_2.


mmaapplliisstt((_:_G_o_a_l_, _?_L_i_s_t_1_, _?_L_i_s_t_2_, _?_L_i_s_t_3))
    True if _G_o_a_l  can succesfully be applied to all succesive triples of
    elements of _L_i_s_t_1.._L_i_s_t_3.


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))
    True if _G_o_a_l  can succesfully be applied to all succesive quadruples
    of elements of _L_i_s_t_1.._L_i_s_t_4


1111..33 assoc::  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 _M_a_r_k_u_s _T_r_i_s_k_a

Elements of an association  list have 2 components:  A (unique)  _k_e_y and
a _v_a_l_u_e.   Keys should be  ground, values need not  be.  An  association
list can be used  to fetch elements via their keys and to  enumerate its
elements in ascending  order of their keys.   The assoc module uses  AVL
trees to  implement association lists.   This makes inserting,  changing
and fetching a single  element an O(log(N)) (where N denotes  the number
of elements in the list) expected time (and worst-case time) operation.


aassssoocc__ttoo__lliisstt((_+_A_s_s_o_c_, _-_L_i_s_t))
    _L_i_s_t is a  list of Key-Value pairs corresponding to the associations
    in _A_s_s_o_c in ascending order of keys.


aassssoocc__ttoo__kkeeyyss((_+_A_s_s_o_c_, _-_L_i_s_t))
    _L_i_s_t  is a list of Keys  corresponding to the associations in  _A_s_s_o_c
    in ascending order.


aassssoocc__ttoo__vvaalluueess((_+_A_s_s_o_c_, _-_L_i_s_t))
    _L_i_s_t is a  list of Values corresponding to the associations in _A_s_s_o_c
    in ascending order of the keys they are associated to.


eemmppttyy__aassssoocc((_-_A_s_s_o_c))
    _A_s_s_o_c is unified with an empty association list.


ggeenn__aassssoocc((_?_K_e_y_, _+_A_s_s_o_c_, _?_V_a_l_u_e))
    Enumerate  matching elements  of _A_s_s_o_c in  ascending order of  their
    keys via backtracking.


ggeett__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_, _?_V_a_l_u_e))
    _V_a_l_u_e  is the  value  associated with  _K_e_y in  the association  list
    _A_s_s_o_c.


ggeett__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_, _?_O_l_d_, _?_N_e_w_A_s_s_o_c_, _?_N_e_w))
    _N_e_w_A_s_s_o_c  is an association list identical to _A_s_s_o_c except  that the
    value associated with _K_e_y is _N_e_w instead of _O_l_d.


lliisstt__ttoo__aassssoocc((_+_L_i_s_t_, _?_A_s_s_o_c))
    _A_s_s_o_c  is an association list  corresponding to the Key-Value  pairs
    in _L_i_s_t.


mmaapp__aassssoocc((_:_G_o_a_l_, _+_A_s_s_o_c))
    _G_o_a_l_(_V_) is true for every value V in _A_s_s_o_c.


mmaapp__aassssoocc((_:_G_o_a_l_, _+_A_s_s_o_c_I_n_, _?_A_s_s_o_c_O_u_t))
    _A_s_s_o_c_O_u_t is _A_s_s_o_c_I_n  with _G_o_a_l applied to all corresponding pairs of
    values.


mmaaxx__aassssoocc((_+_A_s_s_o_c_, _?_K_e_y_, _?_V_a_l_u_e))
    _K_e_y and _V_a_l_u_e are  key and value of the element with the largest key
    in _A_s_s_o_c.


mmiinn__aassssoocc((_+_A_s_s_o_c_, _?_K_e_y_, _?_V_a_l_u_e))
    _K_e_y  and _V_a_l_u_e are  key and value of  the element with the  smallest
    key in _A_s_s_o_c.


oorrdd__lliisstt__ttoo__aassssoocc((_+_L_i_s_t_, _?_A_s_s_o_c))
    _A_s_s_o_c  is an association list  correpsond to the Key-Value pairs  in
    _L_i_s_t, which must occur in ascending order of their keys.


ppuutt__aassssoocc((_+_K_e_y_, _+_A_s_s_o_c_, _+_V_a_l_u_e_, _?_N_e_w_A_s_s_o_c))
    _N_e_w_A_s_s_o_c  is an association list identical to _A_s_s_o_c except  that _K_e_y
    is  associated with _V_a_l_u_e.   This can be  used to insert and  change
    associations.


1111..44 broadcast::  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)                                                       |
    |                                                                    |
    ||Yes_______________________________________________________________ ||


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.


1111..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))                            _[_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))
    _C_o_d_e_s is a list of character codes produced by write/1 on _T_e_r_m.


wwrriittee__ttoo__cchhaarrss((_+_T_e_r_m_, _-_C_o_d_e_s_, _?_T_a_i_l))
    _C_o_d_e_s  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((_+_A_t_o_m_, _-_C_o_d_e_s_, _?_T_a_i_l))                              _[_d_e_t_]
    Convert Number 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.

         bbuugg Depends  on  autoloading  library(memfile).    As many
             applications   do  not  need  this   predicate  we  do
             not  want  to  make the  entire  library  dependent on
             autoloading.


wwiitthh__oouuttppuutt__ttoo__cchhaarrss((_:_G_o_a_l_, _C_o_d_e_s))                                  _[_d_e_t_]
    Run  _G_o_a_l  with as  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  with as  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_]
    As  with_output_to_chars/2, but _S_t_r_e_a_m is unified with  the temporary
    stream.


1111..66 check::  EElleemmeennttaarryy ccoommpplleetteenneessss cchheecckkss

This library defines the predicate check/0 and a few  friends that allow
for a quick-and-dirty cross-referencing.


cchheecckk
    Performs  the three checking passes implemented by list_undefined/0,
    list_autoload/0 and  list_redefined/0.   Please check the  definition
    of these predicates for details.

    The  typical usage  of this  predicate is right  after loading  your
    program  to get a  quick overview on  the completeness and  possible
    conflicts in your program.


lliisstt__uunnddeeffiinneedd
    Scans  the  database for  predicates that  have no  definition.    A
    predicate  is  considered defined  if it  has clauses,  is  declared
    using  dynamic/1 or  multifile/1.   As a  program is compiled  calls
    are  translated to predicates.   If the called predicate is not  yet
    defined  it is created as a predicate without definition.   The same
    happens  with runtime  generated calls.   This  predicate lists  all
    such  undefined predicates  that are referenced  and not defined  in
    the  library.  See also  list_autoload/0.   Below is an example  from
    a  real program  and  an illustration  how to  edit the  referencing
    predicate using edit/1.

    ____________________________________________________________________|                                                                    |
    | ?- list_undefined.                                                 |

    | Warning: The predicates below are not defined. If these are defined|
    | Warning: at runtime using assert/1, use :- dynamic Name/Arity.     |
    | Warning:                                                           |
    | Warning: rdf_edit:rdfe_retract/4, which is referenced by           |
    | Warning:         1-st clause of rdf_edit:undo/4                    |
    | Warning: rdf_edit:rdfe_retract/3, which is referenced by           |
    | Warning:         1-st clause of rdf_edit:delete_object/1           |
    | Warning:         1-st clause of rdf_edit:delete_subject/1          |

    | Warning:         1-st clause of rdf_edit:delete_predicate/1        |
    |                                                                    |
    ||?-_edit(rdf_edit:undo/4)._________________________________________ ||


lliisstt__aauuttoollooaadd
    Lists  all undefined (see  list_undefined/0)  predicates that have  a
    definition  in the library along with the file from which  they will
    be autoloaded when accessed.  See also autoload/0.


lliisstt__rreeddeeffiinneedd
    Lists  predicates that  are  defined in  the global  module user  as
    well  as in a normal  module.  I.e.  predicates for which the  local
    definition overrules the global default definition.


1111..77 lliibbrraarryy((ccllppffdd))::  CCoonnssttrraaiinntt LLooggiicc PPrrooggrraammmmiinngg oovveerr FFiinniittee DDoommaaiinnss

    aauutthhoorr  Markus Triska

Constraint  programming  is  a  declarative  formalism   that  lets  you
describe conditions  a solution  must satisfy.    This library  provides
CLP(FD),  Constraint Logic  Programming over  Finite Domains.    It  can
be  used to  model  and solve  various  combinatorial problems  such  as
planning, scheduling and allocation tasks.

Most predicates  of this  library are finite  domain _c_o_n_s_t_r_a_i_n_t_s,  which
are relations over  integers.  They generalise arithmetic  evaluation of
integer expressions in  that propagation can proceed in all  directions.
This  library  also  provides  _e_n_u_m_e_r_a_t_i_o_n  _p_r_e_d_i_c_a_t_e_s,  which  let  you
systematically  search for  solutions on  variables  whose domains  have
become finite.  A finite domain _e_x_p_r_e_s_s_i_o_n is one of:

    _____________________________________________
    | an integer     |Given value                |

    | a variable     |Unknown value              |
    | -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                     |
    | abs(Expr)      |Absolute value             |
    |_Expr_/_Expr____|Integer_division___________|

The most important finite domain constraints are:

    ___________________________________________________________
    | Expr1 #>= Expr2 |Expr1 is larger than or equal to Expr2  |
    | Expr1 #=<  Expr2 |Expr1 is smaller than or equal to Expr2 |
    | Expr1 #= Expr2   |Expr1 equals Expr2                      |
    | Expr1 #\= Expr2  |Expr1 is not equal to Expr2             |
    | Expr1 #>  Expr2  |Expr1 is strictly larger than Expr2     |
    |_Expr1_#<__Expr2__|Expr1_is_strictly_smaller_than_Expr2___ |

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 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.   If a  variable
occurs  at the  place  of a  constraint that  is  being reified,  it  is
implicitly constrained to  the Boolean values 0  and 1.  Therefore,  the
following queries all fail:  ?- #\ 2., ?- #\ #\ 2.  etc.

Here is an example session with a few queries and their answers:

________________________________________________________________________|                                                                        |

|?- [library(clpfd)].                                                    |
|% library(clpfd) compiled into clpfd 0.06 sec, 3,308 bytes              |
|true.                                                                   |
|                                                                        |
|?- 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.                                                                  |
|                                                                        |
|?- Vs = [X,Y,Z], Vs ins 1..3, all_different(Vs), X = 1, Y #\= 2.        |
|Vs = [1, 3, 2],                                                         |
|X = 1,                                                                  |

|Y = 3,                                                                  |
|Z = 2.                                                                  |
|                                                                        |
|?- X #= Y #<==> B, X in 0..3, Y in 4..5.                                |
|B = 0,                                                                  |
|X in 0..3,                                                              |
|Y|in_4..5._____________________________________________________________ | |

In  each  case   (and  as  for  all   pure  programs),  the  answer   is
declaratively equivalent  to the original query,  and in many cases  the
constraint solver has deduced additional domain restrictions.

A common usage of this library is to first  post the desired constraints
among the variables of  a model, and then to use  enumeration predicates
to search  for solutions.   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:

________________________________________________________________________|                                                                        |

|:- use_module(library(clpfd)).                                          |
|                                                                        |
|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.______________________________________________ ||

Sample query and its result:

________________________________________________________________________|                                                                        |
|?- puzzle(As+Bs=Cs).                                                    |
|As = [9, _G10107, _G10110, _G10113],                                    |
|Bs = [1, 0, _G10128, _G10107],                                          |

|Cs = [1, 0, _G10110, _G10107, _G10152],                                 |
|_G10107 in 4..7,                                                        |
|1000*9+91*_G10107+ -90*_G10110+_G10113+ -9000*1+ -900*0+10*_G10128+ -1*_G10152#=0,|
|all_different([_G10107, _G10110, _G10113, _G10128, _G10152, 0, 1, 9]),  |
|_G10110 in 5..8,                                                        |
|_G10113 in 2..8,                                                        |
|_G10128 in 2..8,                                                        |

|_G10152|in_2..8._______________________________________________________ |       |

Here, the  constraint solver has deduced  more stringent bounds for  all
variables.   Keeping  the modeling  part separate from  the search  lets
you  view these  residual  goals,  observe termination  and  determinism
properties of the modeling  part in isolation from the search,  and more
easily experiment with  different search strategies.  Labeling  can then
be used to search for solutions:

________________________________________________________________________|                                                                        |

|?- 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.

You can also  use CLP(FD) constraints as a more  declarative alternative
for ordinary integer arithmetic with is/2, >/2 etc.  For example:

________________________________________________________________________|                                                                        |

|:- use_module(library(clpfd)).                                          |
|                                                                        |
|n_factorial(0, 1).                                                      |
|n_factorial(N,|F)_:-_N_#>_0,_N1_#=_N_-_1,_F_#=_N_*_F1,_n_factorial(N1,_F1).|           |

This predicate can be used in all directions.  For example:

________________________________________________________________________|                                                                        |
|?- n_factorial(47, F).                                                  |

|F = 258623241511168180642964355153611979969197632389120000000000 ;      |
|false.                                                                  |
|                                                                        |
|?- n_factorial(N, 1).                                                   |
|N = 0 ;                                                                 |
|N = 1 ;                                                                 |
|false.                                                                  |

|                                                                        |
|?- n_factorial(N, 3).                                                   |
|false.|________________________________________________________________ |      |

To make  the predicate terminate  if any  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.

This   library  uses   goal_expansion/2   to  rewrite   constraints   at
compilation  time.    The  expansion's  aim is  to  transparently  bring
the performance  of CLP(FD)  constraints close to  that of  conventional
arithmetic predicates (</2, =:=/2, is/2 etc.)   when the constraints are
used in  modes that  can also  be handled by  built-in arithmetic.    To
disable the expansion, set the flag clpfd_goal_expansion to false.

Use call_residue_vars/2 and  copy_term/3 to inspect  residual goals  and
the constraints  in which  a variable is  involved.   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 you  can inspect a  variable's current domain.   These  predicates
can be useful if you want to implement your own labeling strategies.

You can  also 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:

________________________________________________________________________|                                                                        |
|:- use_module(library(clpfd)).                                          |
|                                                                        |
|:- 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._________________________________________________________ | |


_?_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 Domain1 and Domain2.


_+_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.


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([], _V_a_r_s).


llaabbeelliinngg((_+_O_p_t_i_o_n_s_, _+_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:

    mmiinn((_E_x_p_r))

    mmaaxx((_E_x_p_r))

    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.


aallll__ddiiffffeerreenntt((_+_V_a_r_s))
    _V_a_r_s are pairwise distinct.


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,
    where _R_e_l is #=, #\=, #<, #>, #=<  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))
    _C_s  is a list of integers, _V_s  is a list of variables  and integers.
    True if the scalar  product of _C_s and _V_s is in relation _R_e_l to _E_x_p_r,
    where _R_e_l is #=, #\=, #<, #>, #=<  or #>=.


_?_X #>= _?_Y
    _X is greater than or equal to _Y.


_?_X #=< _?_Y
    _X is less than or equal to _Y.


_?_X #= _?_Y
    _X equals _Y.


_?_X #\= _?_Y
    _X is not _Y.


_?_X #> _?_Y
    _X is greater than _Y.


_?_X #< _?_Y
    _X  is  less than  _Y. In  addition  to its  regular use  in  problems
    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)]|_


#\ _+_Q
    The  reifiable constraint _Q does _n_o_t  hold.  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.  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:

    ____________________________________________________________________|                                                                    |

    | :- use_module(library(clpfd)).                                     |
    |                                                                    |
    | 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.


_?_P #<== _?_Q
    _Q implies _P.


_?_P #/\ _?_Q
    _P and _Q hold.


_?_P #\/ _?_Q
    _P  or _Q holds.  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._____________________________________________________ ||


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))
    _R_e_l_a_t_i_o_n  must be a list of lists of integers.  The  elements of the
    list  _T_u_p_l_e_s are constrained to be elements of _R_e_l_a_t_i_o_n.   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.

    ____________________________________________________________________|                                                                    |

    | :- use_module(library(clpfd)).                                     |
    |                                                                    |
    | 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]].__________________ ||


aallll__ddiissttiinncctt((_+_L_s))
    Like  all_different/1,  with stronger  propagation.    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.____________________________________________________________ ||


sseerriiaalliizzeedd((_+_S_t_a_r_t_s_, _+_D_u_r_a_t_i_o_n_s))
    Constrain a set  of intervals to a non-overlapping sequence.  _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))
    Equivalent to global_cardinality(_V_s, _P_a_i_r_s, []).  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))
    _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))
         Matrix 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 Matrix_{ij}.  Cost is the sum of all costs.


cciirrccuuiitt((_+_V_s))
    True   if  the  list  _V_s  of  finite  domain  variables   induces  a
    Hamiltonian  circuit,  where  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]_._______________________________________________ ||


aauuttoommaattoonn((_+_S_i_g_n_a_t_u_r_e_, _+_N_o_d_e_s_, _+_A_r_c_s))
    Equivalent  to automaton(_, _,  _S_i_g_n_a_t_u_r_e, _N_o_d_e_s,  _A_r_c_s, [],  [], _),
    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:

    ____________________________________________________________________|                                                                    |
    | :- use_module(library(clpfd)).                                     |
    |                                                                    |
    | 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)]).                       |
    |                                                                    |
    | ?- 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))
    True  if 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.    Exprs 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  correspond to old counter values, and  variables occurring
    in  _T_e_m_p_l_a_t_e correspond to the current element of _S_e_q_u_e_n_c_e.   When a
    transition containing expressions  is taken, counters are updated as
    stated.  By  default, counters remain unchanged.  _C_o_u_n_t_e_r_s is a list
    of variables that  must not occur anywhere outside of the constraint
    goal.     _I_n_i_t_i_a_l_s  is  a  list of  the  same  length  as  _C_o_u_n_t_e_r_s.
    Counter arithmetic on  the transitions relates the counter values in
    _I_n_i_t_i_a_l_s to _F_i_n_a_l_s.

    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:

    ____________________________________________________________________|                                                                    |
    | :- use_module(library(clpfd)).                                     |

    |                                                                    |
    | sequence_inflexions(Vs, N) :-                                      |
    |         variables_signature(Vs, Sigs),                             |
    |         automaton(_, _, 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]._____________________________________________ ||


ttrraannssppoossee((_+_M_a_t_r_i_x_, _?_T_r_a_n_s_p_o_s_e))
    _T_r_a_n_s_p_o_s_e a list of lists of the same length.  Example:

    ____________________________________________________________________|                                                                    |
    | ?- transpose([[1,2,3],[4,5,6],[7,8,9]], Ts).                       |

    ||Ts_=_[[1,_4,_7],_[2,_5,_8],_[3,_6,_9]].___________________________ ||

    This predicate is  useful in many constraint programs.  Consider for
    instance Sudoku:

    ____________________________________________________________________|                                                                    |

    | :- use_module(library(clpfd)).                                     |
    |                                                                    |
    | sudoku(Rows) :-                                                    |
    |         length(Rows, 9), maplist(length_(9), Rows),                |
    |         append(Rows, Vs), Vs ins 1..9,                             |
    |         maplist(all_distinct, Rows),                               |
    |         transpose(Rows, Columns), maplist(all_distinct, Columns),  |

    |         Rows = [A,B,C,D,E,F,G,H,I],                                |
    |         blocks(A, B, C), blocks(D, E, F), blocks(G, H, I).         |
    |                                                                    |
    | length_(L, Ls) :- length(Ls, L).                                   |
    |                                                                    |
    | blocks([], [], []).                                                |
    | blocks([A,B,C|Bs1], [D,E,F|Bs2], [G,H,I|Bs3]) :-                   |

    |         all_distinct([A,B,C,D,E,F,G,H,I]),                         |
    |         blocks(Bs1, Bs2, Bs3).                                     |
    |                                                                    |
    | 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(writeln, 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|...],_..._,_[...|...]].___________ ||


zzccoommppaarree((_?_O_r_d_e_r_, _?_A_, _?_B))
    Analogous  to  compare/3,  with finite  domain  variables _A  and  _B.
    Example:

    ____________________________________________________________________|                                                                    |
    | :- use_module(library(clpfd)).                                     |

    |                                                                    |
    |  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   is  deterministic   if   the  first   argument   is
    instantiated:

    ____________________________________________________________________|                                                                    |
    | ?- n_factorial(30, F).                                             |

    ||F_=_265252859812191058636308480000000.____________________________ ||


cchhaaiinn((_+_Z_s_, _+_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.____________________________________________________________ ||


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))
    _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 not  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.


1111..88 clpqr::  CCoonnssttrraaiinntt LLooggiicc PPrrooggrraammmmiinngg oovveerr RRaattiioonnaallss aanndd RReeaallss

    Author:  _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 explicitely before using it:

________________________________________________________________________|                                                                        |

|:-|use_module(library(clpq)).__________________________________________ |  |

or

________________________________________________________________________|                                                                        |

|:-|use_module(library(clpr)).__________________________________________ |  |


1111..88..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  equation 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 veen 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.


1111..88..22 SSyynnttaaxx ooff tthhee pprreeddiiccaattee aarrgguummeennttss

The arguments  of the  predicates defined  in the  subsection above  are
defined in table 11.1.  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 (float, integer)      |
|                 | +<_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 11.1:  CLP(Q,R) constraint BNF


1111..88..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___________________________________________________________ ||


1111..88..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 11.2.
     ______________________________________________________________
     | 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 11.2:  CLP(Q,R) isolating axioms


1111..99 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.

    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., separator(0';).

    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.

    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.


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.


1111..1100 debug::  SSoommee rreeuussaabbllee ccooddee ttoo hheellpp ddeebbuuggggiinngg aapppplliiccaattiioonnss

This  library provides  an  structured  alternative for  putting  print-
statements into  your source-code  to trace  what is  going on.    Debug
messages are organised in _t_o_p_i_c_s that can be  activated and de-activated
without  changing  the  source.     In  addition,   if  the  application
is  compiled  with  the -O  flag  these  predicates  are  removed  using
goal_expansion/2.

Although  this library  can be  used through  the normal  demand-loading
mechanism it is adviced  to load it explicitely before code using  it to
profit from goal-expansion,  which removes these calls if  compiled with
optimisation on and records the topics from debug/3  and debugging/1 for
list_debug_topics/0.


ddeebbuugg((_+_T_o_p_i_c_, _+_F_o_r_m_a_t_, _+_A_r_g_s))
    If  _T_o_p_i_c is a selected debugging  topic (see debug/1) a message  is
    printed using  print_message/2with level informational.   _F_o_r_m_a_t and
    _A_r_g_s are interpreted by format/2.  Here is a typical example:

    ____________________________________________________________________|                                                                    |
    |         ...,                                                       |

    |         debug(init, 'Initialised ~w', [Module]),                   |
    ||________...,______________________________________________________ ||

    _T_o_p_i_c  can be any Prolog term.   Compound terms can be used  to make
    categories of topics that can be activated using debug/1.


ddeebbuuggggiinngg((_+_T_o_p_i_c))
    Succeeds  if _T_o_p_i_c is  a selected debugging topic.   It is  intended
    to  execute  arbitrary  code  depending on  the  users  debug  topic
    selection.     The  construct  (debugging(Topic) -> _C_o_d_e ; true)  is
    removed if the code is compiled in optimise mode.


ddeebbuugg((_+_T_o_p_i_c))
    Select  all registered topics that  unify with _T_o_p_i_c for  debugging.
    This  call is normally  used from the  toplevel to activate a  topic
    for  debugging.   If no  matching _T_o_p_i_c is  registered a warning  is
    printed and the  topic is registered for debugging as matching debug
    statements  may be  loaded  later.   Topics  are de-activated  using
    nodebug/1.


nnooddeebbuugg((_+_T_o_p_i_c))
    Deactivates topics for debugging.  See debug/1 for the arguments.


lliisstt__ddeebbuugg__ttooppiiccss
    List   the  current  status  of   registered  topics.     See   also
    debugging/0.


aasssseerrttiioonn((_:_G_o_a_l))
    This  predicate  is   to  be  compared  to  the  C-library  assert()
    function.   By inserting this goal you explicitely state  you expect
    _G_o_a_l  to succeed at  this place.   As assertion/1 calls are  removed
    when compiling in  optimized mode _G_o_a_l should not have side-effects.
    Typical  examples are type-tests  and validating invariants  defined
    by your application.

    If   _G_o_a_l  fails  the  system  prints  a  message,  followed   by  a
    stack-trace and starts the debugger.

    In  older  versions  of  this  library  this  predicate  was  called
    assume/1.    Code using  assume/1 is  automatically converted  while
    printing a warning on the first occurrence.


1111..1111 gensym::  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 warrant 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 advice to avoid  the
    use  of reset_gensym or at least to reset only the keys  used by your
    program to avoid unexpected site-effects on other components.


1111..1122 lliibbrraarryy((lliissttss))::  LLiisstt MMaanniippuullaattiioonn

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.


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 concatination 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 Lists is a  list of lists,
    and _L_i_s_t is the concatenation of these lists.

    __________________________________________________________Parameters_
     _L_i_s_t_O_f_L_i_s_t_s  must be a list of -possibly- 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(_P_a_r_t, _, _W_h_o_l_e).


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
    _E_l_e_m.


sseelleecctt((_?_X_, _?_X_L_i_s_t_, _?_Y_, _?_Y_L_i_s_t))                                 _[_n_o_n_d_e_t_]
    Is  true when  select(_X, _X_L_i_s_t)  and  select(_Y, _Y_L_i_s_t)  are true,  _X
    and  _Y  appear  in the  same  locations  of their  respective  lists
    and  same_length(_X_L_i_s_t,  _Y_L_i_s_t) is  true.    A typical  use for  this
    predicate is to _r_e_p_l_a_c_e an element:

    ____________________________________________________________________|                                                                    |
    | ?- select(b, [a,b,c], 2, X).                                       |

    | X = [a, 2, c] ;                                                    |
    ||X_=_[a,_b,_c].____________________________________________________ ||


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 of _Y follows _X in _L_i_s_t.


ddeelleettee((_?_L_i_s_t_1_, _?_E_l_e_m_, _?_L_i_s_t_2))
    Is  true when Lis1, with all  occurences of _E_l_e_m deleted results  in
    _L_i_s_t_2.

         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 if _E_l_e_m is the _I_n_d_e_x'th element of _L_i_s_t.  Counting starts at

     1.  This is a faster version of the original SWI-Prolog predicate.


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.  This is  a faster version of the  original SWI-Prolog
    predicate.


llaasstt((_?_L_i_s_t_, _?_L_a_s_t))
    Succeeds if `_L_a_s_t' unifies with the last element of `_L_i_s_t'.

         CCoommppaattiibbiilliittyy There   is  no  de-facto  standard  for  the
             argument  order of  last/2.   Be careful  when porting
             code  or  use append(_, [_L_a_s_t],  _L_i_s_t)  as  a portable
             alternative.


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_]
    permutation(_X_s,  _Y_s) is 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.


ffllaatttteenn((_+_L_i_s_t_1_, _?_L_i_s_t_2))                                           _[_d_e_t_]
    Is true it _L_i_s_t_2 is a non nested version of _L_i_s_t_1.

         SSeeee aallssoo append/2

         ddeepprreeccaatteedd Ending  up  needing flatten/3  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.


ssuummlliisstt((_+_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))                          _[_d_e_t_]
    True if _M_a_x is the largest number in _L_i_s_t.


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))                          _[_d_e_t_]
    True if _M_i_n is the largest number in _L_i_s_t.


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, _L_o_w)
             - type_error(integer, _H_i_g_h)


iiss__sseett((_@_S_e_t))                                                       _[_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 element as _L_i_s_t in the same order.   The
    left-most  copy of  the duplicate is  retained.   The complexity  of
    this operation is |_L_i_s_t|^2.

         SSeeee aallssoo sort/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|

         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  _S_e_t_1  and  _S_e_t_2.    The
    complexity of this predicate is |_S_e_t_1|*|_S_e_t_2|

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

         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 from `_S_e_t' that  occur in `_D_e_l_e_t_e' (a set)  and
    unify  the result with `_R_e_s_u_l_t'.   Deletion is based on  unification
    using memberchk/2.  The complexity is |_D_e_l_e_t_e|*|_S_e_t|.

         SSeeee aallssoo ord_subtract/3.


1111..1133 nb_set::  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
implementation,  but  it  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 outlines 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 emoty 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, bindin _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 set in the standard order
    of terms (i.e. and _o_r_d_e_r_e_d _l_i_s_t).


1111..1144 www_browser::  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 Window  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
         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.


1111..1155 lliibbrraarryy((ooppttiioonn))::  OOppttiioonn lliisstt pprroocceessssiinngg

    SSeeee aallssoo  library(record)

    TToo bbee ddoonnee
         - We should  consider putting many options  in an assoc or
         record with  appropriate  preprocessing to  achieve better
         performance.
         -  We  should  provide   some  standard  to  do  automatic
         type-checking on option lists.

The  library(option)  provides  some  utilities  for  processing  option
lists.    Option lists  are commonly  used as  an  alternative for  many
arguments.   Examples 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),                                  |
||_______...____________________________________________________________ ||


ooppttiioonn((_?_O_p_t_i_o_n_, _+_O_p_t_i_o_n_L_i_s_t_, _+_D_e_f_a_u_l_t))
    Get an option from  a _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.

    __________________________________________________________Parameters_
     _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))
    Get an option from  a _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.

    __________________________________________________________Parameters_
     _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 option 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 option 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(_I_s_M_e_t_a, Name).  Here is an example:

    ____________________________________________________________________|                                                                    |
    |         meta_options(is_meta, OptionsIn, Options),                 |

    |         ...                                                        |
    |                                                                    |
    ||is_meta(callback).________________________________________________ ||


1111..1166 ordsets::  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 N2  when dealing
with  unordered sets  that  may contain  duplicates.    The  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 oset, an  older
ordered set library  distributed with SWI-Prolog.  New  applications are
advices to use ordsets.

Some  of   these  predicates  match   directly  to  corresponding   list
operations.   It is  adviced to  use the versions  from this library  to
make clear you are operating on ordered sets.


oorrdd__eemmppttyy((_?_S_e_t))
    True  if _S_e_t is an  empty ordered set.   _S_e_t unifies with the  empty
    list.


lliisstt__ttoo__oorrdd__sseett((_+_L_i_s_t_, _-_O_r_d_S_e_t))
    Convert a _L_i_s_t to an ordered set.  Same as sort/2.


oorrdd__aadddd__eelleemmeenntt((_+_S_e_t_, _+_E_l_e_m_e_n_t_, _-_N_e_w_S_e_t))
    Add  an element to  an ordered set.   _N_e_w_S_e_t is  the same as _S_e_t  if
    _E_l_e_m_e_n_t is already part of _S_e_t.


oorrdd__ddeell__eelleemmeenntt((_+_S_e_t_, _+_E_l_e_m_e_n_t_, _-_N_e_w_S_e_t))
    Delete _E_l_e_m_e_n_t from _S_e_t.   Succeeds without changing _S_e_t if _S_e_t does
    not contain _E_l_e_m_e_n_t.


oorrdd__iinntteerrsseecctt((_+_S_e_t_1_, _+_S_e_t_2))
    True if the intersection of _S_e_t_1 and _S_e_t_2 is non-empty.


oorrdd__iinntteerrsseeccttiioonn((_+_S_e_t_1_, _+_S_e_t_2_, _-_I_n_t_e_r_s_e_c_t_i_o_n))
    True if _I_n_t_e_r_s_e_c_t_i_o_n is the intersection of _S_e_t_1 and _S_e_t_2.


oorrdd__ddiissjjooiinntt((_+_S_e_t_1_, _+_S_e_t_2))
    True  if  _S_e_t_1  and  _S_e_t_2 have  no  common  element.    Negation  of
    ord_intersect/2.


oorrdd__ssuubbttrraacctt((_+_S_e_t_, _+_D_e_l_e_t_e_, _-_R_e_m_a_i_n_i_n_g))
    True  if _R_e_m_a_i_n_i_n_g contains the elements of _S_e_t that are not  in set
    _D_e_l_e_t_e.


oorrdd__uunniioonn((_+_S_e_t_1_, _+_S_e_t_2_, _-_U_n_i_o_n))
    True if _U_n_i_o_n contains all elements from _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))
    Defined  as  if  ord_union(_S_e_t_1_,  _S_e_t_2_,  _U_n_i_o_n),  ord_subtract(_S_e_t_2_,
    _S_e_t_1_, _N_e_w).


oorrdd__ssuubbsseett((_+_S_u_b_, _+_S_u_p_e_r))
    True if all elements of _S_u_b are in _S_u_p_e_r.


oorrdd__mmeemmbbeerrcchhkk((_+_E_l_e_m_e_n_t_, _+_S_e_t))
    True  if _E_l_e_m_e_n_t  appears in  _S_e_t.   Does not  backtrack.   Same  as
    memberchk/2.


1111..1177 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(_P_a_i_r_s, _, _V_a_l_u_e_s)


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(_P_a_i_r_s, _K_e_y_s, _)


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 the same key.   _P_a_i_r_s must be a  key-sorted list.
    For example:

    ____________________________________________________________________|                                                                    |
    | ?- group_pairs_by_key([a-2, a-1, b-4], X).                         |

    |                                                                    |
    ||X_=_[a-[2,1],_b-[4]]______________________________________________ ||

    __________________________________________________________Parameters__P_a_i_r_s_K_e_y-Value list, sorted to the standard order  of

             terms (as keysort/2 does)
     _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 _K_e_y.


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 and sort  the result on Value (the  new
    key) using keysort/2.


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),____________ ||


1111..1188 pio::  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.


1111..1188..11 lliibbrraarryy((ppuurree__iinnppuutt))::  PPuurree IInnppuutt ffrroomm ffiilleess

    aauutthhoorr
         - Ulrich Neumerkel
         - Jan Wielemaker

    TToo bbee ddoonnee
         -  Provide support  for  alternative  input readers,  e.g.
         reading terms, tokens, etc.
         - Support  non-repositioning streams, such  as sockets and
         pipes.

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  coroutining (freeze/2) 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_input/3.


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.   Here is a very simple definition for searching a string
    in a file:

    ____________________________________________________________________|                                                                    |
    | ... --> []|[_],... .                                               |
    |                                                                    |
    | file_contains(File, Pattern) :-                                    |

    |         phrase_from_file((..., Pattern, ...), File).               |
    |                                                                    |
    | match_count(File, Pattern, Count) :-                               |
    |         findall(x, file_contains(File, Pattern), Xs),              |
    ||________length(Xs,_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,  except  for buffer_size,  which  is  passed  to
    set_stream/2.   If  not specified,  the default buffer  size is  512
    bytes.   Of  particular importance are  the open/4 options type  and
    encoding.


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.   It
    must be possible to  reposition _S_t_r_e_a_m.  _L_i_s_t is a list that ends in
    a  delayed goal.   _L_i_s_t can be  unified completely transparent to  a
    (partial)  list and processed  transparently using DCGs, but  please
    be aware that a  lazy list is not the same as a materialized list in
    all respects.

    Typically, this predicate  is used as a building block for more high
    level safe predicates such as phrase_from_file/2.

         TToo bbee ddoonnee Enhance of lazy list throughout the system.


1111..1199 prolog_xref::  CCrroossss--rreeffeerreennccee ddaattaa ccoolllleeccttiioonn lliibbrraarryy

This library collects information on defined and used  objects in Prolog
sourcefiles.  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 frontend  started by gxref/0  and described  in
section 3.7 and  PceEmacs (section 3.4) 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  11.19.1  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'.


1111..1199..11 EExxtteennddiinngg tthhee lliibbrraarryy

The library provides hooks  for extending its rules it uses  for finding
predicates called by some programming construct.


pprroolloogg::ccaalllleedd__bbyy((_+_G_o_a_l_, _-_C_a_l_l_e_d))
    Where  _G_o_a_l  is   a  non-var  subgoal  appearing  in  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.


1111..2200 readutil::  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 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))
    Diference-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 readine  a block of  lines
    upto  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.


1111..2211 record::  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 _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 11.21 for details.


1111..2222 registry::  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 of 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 this does not already exist.


rreeggiissttrryy__sseett__kkeeyy((_+_P_a_t_h_, _+_N_a_m_e_, _+_V_a_l_u_e))
    Associated  a named value to this key.  Creates (a path  to) the key
    if this 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 link 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  a 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
    explains the above predicates, it is given as an example:

    ____________________________________________________________________|                                                                    |
    | shell_register_prolog(Ext) :-                                      |

    |         current_prolog_flag(argv, [Me|_]),                         |
    |         concat_atom(['"', 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).__ ||


1111..2233 simplex::  SSoollvvee lliinneeaarr pprrooggrraammmmiinngg pprroobblleemmss

                                                  Author:  _M_a_r_k_u_s _T_r_i_s_k_a

A linear programming problem consists of a set  of (linear) constraints,
a number  of variables and  a linear  objective function.   The goal  is
to assign values  to the variables so  as to maximize (or minimize)  the
value of the objective function while satisfying all constraints.

Many optimization problems can be modeled in this way.   Consider having
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 coins 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.

The simplex module provides the following predicates:


aassssiiggnnmmeenntt((_+_C_o_s_t_, _-_A_s_s_i_g_n_m_e_n_t))
    _C_o_s_t  is a  list of  lists representing the  quadratic cost  matrix,
    where  element  (i,j) denotes  the  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.


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 "Left"  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.


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.


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.


ggeenn__ssttaattee((_-_S_t_a_t_e))
    Generates  an  initial   state  corresponding  to  an  empty  linear
    program.


mmaaxxiimmiizzee((_+_O_b_j_e_c_t_i_v_e_, _+_S_0_, _-_S))
    Maximizes  the  objective function,  stated as  a  list of  "Coeffi-
    cient*Variable" terms that  represents the sum of its elements, with
    respect  to the  linear program  corresponding to state  _S_0.   _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.


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.


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.


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))
    _S_u_p_p_l_i_e_s  and _D_e_m_a_n_d_s  are both lists  of positive  numbers.   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 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.


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.

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  non-negative.     This  may  change  in  future  versions,   and
non-negativity constraints should therefore be stated explicitly.


1111..2233..11 EExxaammppllee 11

This is  the "radiation  therapy" example, taken  from "Introduction  to
Operations Research" by Hillier and Lieberman.  DCG  notation is used to
implicitly thread the state through posting the constraints:

________________________________________________________________________|                                                                        |
|:- use_module(library(simplex)).                                        |

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

|radiation(S) :-                                                         |
|        gen_state(S0),                                                  |
|        post_constraints(S0, S1),                                       |
||_______minimize([0.4*x1,_0.5*x2],_S1,_S)._____________________________ ||

An example query:

________________________________________________________________________|                                                                        |
|?- radiation(S), variable_value(S, x1, Val1), variable_value(S, x2, Val2).|
|                                                                        |
|Val1 = 15 rdiv 2                                                        |

|Val2|=_9_rdiv_2_;______________________________________________________ |    |


1111..2233..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.

________________________________________________________________________|                                                                        |
|knapsack_constrain(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).                                 |
|                                                                        |
|knapsack(S) :-                                                          |
|        knapsack_constrain(S0),                                         |
||_______maximize([7*x(1),_4*x(2)],_S0,_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_constrain(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  two  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.


1111..2233..33 EExxaammppllee 33

We are given 3 coins  each worth 1, 20 coins each worth 5, and  10 coins
each worth 20 units of  money.  The task is to find a minimal  number of
these coins that amount  to 111 units of money.  We  introduce variables
c(1), c(5) and c(20)  denoting how many coins to take of  the respective
type:

________________________________________________________________________|                                                                        |
|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)]).                                  |
|                                                                        |
|coins(S) :-                                                             |
|        gen_state(S0),                                                  |
||_______coins(S0,_S).__________________________________________________ ||

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________________________________________________________________ |   |


1111..2244 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 application  that
recieve 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.

         bbuugg The  thread  creation option  at_exit is  reserved for
             internal use by this library.


tthhrreeaadd__ppooooll__ddeessttrrooyy((_+_N_a_m_e))                                         _[_d_e_t_]
    Destroy the thread pool named _N_a_m_e.

         EErrrroorrss existence_error(thread_pool, _N_a_m_e).


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))
         ListOfIDs 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(_P_o_o_l))  is  raised  if
             wait is false or the backlog limit has been reached.
             -  existence_error(thread_pool,  _P_o_o_l) if  _P_o_o_l does not
             exist.


1111..2255 ugraphs::  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_.   _Y_A_P _i_s  _c_o_n_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_, _w_h_i_c_h
    _d_o_e_s  _n_o_t  _i_m_p_l_y _f_u_r_t_h_e_r  _r_e_s_t_r_i_c_t_i_o_n_s _o_n  _t_h_e  _S_W_I_-_P_r_o_l_o_g _L_G_P_L
    _l_i_c_e_n_s_e_.

The  routines   assume  directed  graphs,   undirected  graphs  may   be
implemented by using two edges.

Originally  graphs  where represented  in  two  formats.    The  SICStus
library and this  version of ugraphs.pl only uses 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, also 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 the
    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 vertice 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   graph  _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.    In  the  next
    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 the _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 the  edges that start  from or go  to a vertex  in
    _V_e_r_t_i_c_e_s to the _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
    edges _E_d_g_e_s to the graph _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 the _G_r_a_p_h.   Notice that no vertices are deleted.  In the
    next 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((_+_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([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,  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  graph
    _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
    graph _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  graph
    _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 graph _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]_____________________________________________________ ||


1111..2266 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>________________________________ ||

    __________________________________________________________Parameters_
     _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.  Parts  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))
         Host-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
         GET protocol.   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))
         Fragment specification of HTTP _U_R_L. This is the  part after the
         # character.

    The example below illustrates the all this for an HTTP _U_R_L.

    ____________________________________________________________________|                                                                    |

    | ?- parse_url('http://swi.psy.uva.nl/message.cgi?msg=Hello+World%21#x',|P).
    |                                                                    |
    | P = [ protocol(http),                                              |
    |       host('swi.psy.uva.nl'),                                      |
    |       fragment(x),                                                 |

    |       search([ msg = 'Hello World!'                                |
    |              ]),                                                   |
    |       path('/message.cgi')                                         |
    ||____]_____________________________________________________________ ||

    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  between native value and  application/x-www-form-encoded.
    Maps  space  to  +, keeps  alnum,  maps  anything  else to  %XX  and
    newlines  to  %OD%OA. When  decoding, newlines  appear  as a  single
    newline (10) character.


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.


CChhaapptteerr 1122..  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.


1122..11 EExxaammiinniinngg tthhee EEnnvviirroonnmmeenntt SSttaacckk


pprroolloogg__ccuurrrreenntt__ffrraammee((_-_F_r_a_m_e))
    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__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  user 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.

    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.

    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/4on  the
    3-th argument.  _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 choicepoint  exists that  is
    more  recent  than the  entry of  the clause  in  which is  appears.
    There are few realistic  situations for using this predicate.  It is
    used by the  prolog/0 toplevel to check whether Prolog should prompt
    the  user for alternatives.   Similar results  can be achieved in  a
    more portable fashion using call_cleanup/2.


1122..22 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 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
         Normal entry  through  the call-port  of the  4-port  debugger.
         The  redo  port  signals  resuming  a  predicate   to  generate
         alternative solutions.

    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 alternative.   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  should be unified  with one  of
    the  atoms  continue (just  continue  execution), retry  (retry  the
    current goal) or fail  (force the current goal to fail).  Leaving it
    a variable is identical to continue.

    Together  with  the predicates  described in  section  4.37 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 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  than  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.


1122..33 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  bullt-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 or  none  of  the exception  is  not
    caught.

    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 as 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.______________________________________________ ||


1122..44 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  Pro-
         log 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 2.13.

    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.


1122..55 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 4.4  for editing hooks  and section 4.9.3  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 de  debugger.  For  example, XPCE uses  these
    hooks  to allow for spying methods  rather then 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 spy/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 succeed, 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.


1122..66 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.

    The  http_load  provides an example, loading Prolog sources  directly
    from an HTTP server.


pprroolloogg::ccoommmmeenntt__hhooookk((_+_C_o_m_m_e_n_t_s_, _+_P_o_s_, _+_T_e_r_m))
    This  hook allows for  processing ---structured--- comments  encoun-
    tered  by the  compiler.   The  reader collects  all comments  found
    from  the current position to  the end of the  next term.  It  calls
    this  hook providing  a list  of _P_o_s_i_t_i_o_n-_C_o_m_m_e_n_t  in _C_o_m_m_e_n_t_s,  the
    start-position  of the  next term in  _P_o_s and  the next term  itself
    in  _T_e_r_m.  All  positions are stream-position terms.   This hook  is
    exploited  by the documentation system.  See stream_position_data/3.
    See also read_term/3.


1122..77 RReeaaddlliinnee IInntteerraaccttiioonn

The following  predicates are available if  SWI-Prolog is linked to  the
GNU  readline library.    This is  by default  the  case on  non-Windows
installations  and indicated  by the  Prolog flag  readline.   See  also
readline(3)


rrll__rreeaadd__iinniitt__ffiillee((_+_F_i_l_e))
    Read  a readline  initialisation file.   Readline  by default  reads
    ~/.inputrc.     This  predicate  may be  used  to  read  alternative
    readline initialisation files.


rrll__aadddd__hhiissttoorryy((_+_L_i_n_e))
    Add  a  line  to  the  Control-P/Control-N  history  system  of  the
    readline library.


rrll__wwrriittee__hhiissttoorryy((_+_F_i_l_e_N_a_m_e))
    Write  current history to _F_i_l_e_N_a_m_e.   Can be used  from at_halt/1 to
    save the history.


rrll__rreeaadd__hhiissttoorryy((_+_F_i_l_e_N_a_m_e))
    Read history from _F_i_l_e_N_a_m_e, appending to the current history.


CChhaapptteerr 1133..  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 4.3.1.1.

  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
    particulary  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.


1133..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  advice
    anyone  to study the philosophy of 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  4.3.1.1.
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 excelent 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, possible  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  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 1144..  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 (is 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 assert/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
    Searching  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 (:-).

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  ``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.

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
    Computers crippled representation  of a real number.  Represented as
    `IEEE double'.

ffoorreeiiggnn
    Computer code expressed  in other languages 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  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 _f_a_i_l_s if Prolog fails to prove
    the _g_o_a_l.

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  instruction.  This is an  atom 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 5.

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,
    including  SWI-Prolog, indexing  is done  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 quickly select
    all  _c_l_a_u_s_e_s of which  the first argument  may _u_n_i_f_y with the  first
    argument of the _g_o_a_l.

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.

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.

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.

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.

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 an  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.

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 = a,                                                             |
    ||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 2.15.1.5.

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 4.22),  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, integer, float
    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.                                                   |

    | No                                                                 |
    | ?- (A = b; true; A = c).                                           |
    | A = b ;                                                            |
    | A = _G283 ;                                                        |
    | A = c ;                                                            |
    ||No________________________________________________________________ ||

    See also _u_n_i_f_y.


CChhaapptteerr 1155..  SSWWII--PPRROOLLOOGG LLIICCEENNSSEE CCOONNDDIITTIIOONNSS AANNDD TTOOOOLLSS

SWI-Prolog licensing aims at a large audience, combining  ideas from the
Free Software Foundation and the less principal  Open Source Initiative.
The license aims at:

  o Make SWI-Prolog itself and its libraries are `As free as possible'.

  o Allow for easy integration of contributions.  See section 15.2.

  o Free software can build on SWI-Prolog without limitations.

  o Non-free  (open  or  proprietary)  software can  be  produced  using
    SWI-Prolog,  although contributed pure  GPL-ed components cannot  be
    used.

To achieve this, different parts of the system  have different licenses.
SWI-Prolog  programs consists  of  a mixture  of `native'  code  (source
compiled to  machine instructions)  and `virtual  machine' code  (Prolog
source  compiled to  SWI-Prolog virtual  machine instructions,  covering
both compiled SWI-Prolog libraries and your compiled application).

For  maximal coherence  between free  licenses, we  start  with the  two
prime  licenses from  the  Free  Software Foundation,  the  GNU  General
Public License (GPL)  and the Lesser GNU General Public  License (LGPL),
after which we add a proven (used by the  GNU-C compiler runtime library
as  well as  the  GNU _C_l_a_s_s_P_a_t_h  project)  exception  to deal  with  the
specific nature of compiled virtual machine code in a saved state.


1155..11 TThhee SSWWII--PPrroolloogg kkeerrnneell aanndd ffoorreeiiggnn lliibbrraarriieess

The SWI-Prolog  kernel and our foreign  libraries are distributed  under
the  LLGGPPLL. A  Prolog executable  consists of  the  combination of  these
`native'  code  components  and  Prolog  virtual  machine  code.     The
SWI-Prolog swipl-rc utility  allows for disassembling and  re-assembling
these parts, a process satisfying article 66bb of the LGPL.

Under  the LGPL  SWI-Prolog  can be  linked  to code  distributed  under
arbitrary licenses,  provided a number  of requirements are  fullfilled.
The most  important requirement is  that, if  an application replies  on
a _m_o_d_i_f_i_e_d  version of  SWI-Prolog, the  modified sources  must be  made
available.


1155..11..11 TThhee SSWWII--PPrroolloogg PPrroolloogg lliibbrraarriieess

Lacking a  satisfactory technical solution  to handle  article 66 of  the
LGPL, this  license cannot be  used for the Prolog  source code that  is
part of the  SWI-Prolog system (both libraries  and kernel code).   This
situation is  comparable to libgcc,  the runtime  library used with  the
GNU C-compiler.    Therefore, we use  the same  proven license terms  as
this library.    The libgcc  license is  the with  a special  exception.
Below we rephrased this exception adjusted to our needs:

    _A_s  _a _s_p_e_c_i_a_l  _e_x_c_e_p_t_i_o_n_, _i_f _y_o_u  _l_i_n_k _t_h_i_s  _l_i_b_r_a_r_y _w_i_t_h _o_t_h_e_r
    _f_i_l_e_s_,  _c_o_m_p_i_l_e_d  _w_i_t_h  _a _F_r_e_e  _S_o_f_t_w_a_r_e  _c_o_m_p_i_l_e_r_,  _t_o _p_r_o_d_u_c_e
    _a_n  _e_x_e_c_u_t_a_b_l_e_,  _t_h_i_s  _l_i_b_r_a_r_y  _d_o_e_s _n_o_t  _b_y  _i_t_s_e_l_f  _c_a_u_s_e _t_h_e
    _r_e_s_u_l_t_i_n_g  _e_x_e_c_u_t_a_b_l_e _t_o _b_e  _c_o_v_e_r_e_d _b_y _t_h_e  _G_N_U _G_e_n_e_r_a_l _P_u_b_l_i_c
    _L_i_c_e_n_s_e_.   _T_h_i_s _e_x_c_e_p_t_i_o_n _d_o_e_s _n_o_t _h_o_w_e_v_e_r _i_n_v_a_l_i_d_a_t_e _a_n_y _o_t_h_e_r
    _r_e_a_s_o_n_s  _w_h_y _t_h_e  _e_x_e_c_u_t_a_b_l_e _f_i_l_e _m_i_g_h_t  _b_e _c_o_v_e_r_e_d _b_y  _t_h_e _G_N_U
    _G_e_n_e_r_a_l _P_u_b_l_i_c _L_i_c_e_n_s_e_.


1155..22 CCoonnttrriibbuuttiinngg ttoo tthhee SSWWII--PPrroolloogg pprroojjeecctt

To  achieve maximal  coherence using  SWI-Prolog for  Free and  Non-Free
software we  advice the  use of  the LGPL for  contributed foreign  code
and the  use of the  GPL with SWI-Prolog exception  for Prolog code  for
contributed modules.

As a  rule of thumb  it is  advised to use  the above licenses  whenever
possible and only use a strict GPL compliant license  only if the module
contains other code under strict GPL compliant licenses.


1155..33 SSooffttwwaarree ssuuppppoorrtt ttoo kkeeeepp ttrraacckk ooff lliicceennssee ccoonnddiittiioonnss

Given the above, it is possible that SWI-Prolog  packages and extensions
will  rely  on the  GPL.  The  predicates below  allow  for  registering
license  requirements  for  Prolog files  and  foreign  modules.     The
predicate  eval_license/0 reports  which  components from  the  currenly
configured  system  are  distributed under  copy-left  and  open  source
enforcing  licenses (the  GPL)  and therefore  must be  replaced  before
distributing linked applications under non-free license conditions.


eevvaall__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.


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.  The most important _L_i_c_e_n_s_e_I_d's are:

    sswwiippll
         Indicates this  module  is distributed  under the  GNU  General
         Public License (GPL) with the SWI-Prolog exception:

             _A_s _a  _s_p_e_c_i_a_l _e_x_c_e_p_t_i_o_n_, _i_f _y_o_u _l_i_n_k _t_h_i_s _l_i_b_r_a_r_y _w_i_t_h
             _o_t_h_e_r  _f_i_l_e_s_, _c_o_m_p_i_l_e_d _w_i_t_h _S_W_I_-_P_r_o_l_o_g_,  _t_o _p_r_o_d_u_c_e _a_n
             _e_x_e_c_u_t_a_b_l_e_, _t_h_i_s  _l_i_b_r_a_r_y _d_o_e_s _n_o_t _b_y _i_t_s_e_l_f _c_a_u_s_e _t_h_e
             _r_e_s_u_l_t_i_n_g _e_x_e_c_u_t_a_b_l_e  _t_o _b_e _c_o_v_e_r_e_d _b_y _t_h_e _G_N_U _G_e_n_e_r_a_l
             _P_u_b_l_i_c  _L_i_c_e_n_s_e_.    _T_h_i_s  _e_x_c_e_p_t_i_o_n  _d_o_e_s  _n_o_t _h_o_w_e_v_e_r
             _i_n_v_a_l_i_d_a_t_e  _a_n_y _o_t_h_e_r _r_e_a_s_o_n_s _w_h_y  _t_h_e _e_x_e_c_u_t_a_b_l_e _f_i_l_e
             _m_i_g_h_t _b_e _c_o_v_e_r_e_d _b_y _t_h_e _G_N_U _G_e_n_e_r_a_l _P_u_b_l_i_c _L_i_c_e_n_s_e_.

         This should  be the  default  for software  contributed to  the
         SWI-Prolog  project  as it  allows  the  community  to  prosper
         both in  the free  and non-free  world.    Still, people  using
         SWI-Prolog  to create  non-free  applications  must  contribute
         sources to improvements they make to the community.

    llggppll
         This is the  default license for foreign-libraries linked  with
         SWI-Prolog.   Use PL_license() to  register the condition  from
         foreign code.

    ggppll
         Indicates this module is strictly Free Software,  which implies
         it  cannot   be  used   together  with  any   module  that   is
         incompatible with  the GPL.  Please only  use these  conditions
         when forced by other code used in the component.

    Other  licenses known to the system are guile,  gnu_ada,  x11, expat,
    sml,  public_domain,  cryptix, bsd,  zlib,  constlgpl_compatible  and
    gpl_compatible.    New licenses  can be  defined  by adding  clauses
    for  the  multifile  predicate  license:license/3.     Below  is  an
    example.   The  second argument  is either gpl  or lgpl to  indicate
    compatibility  with these licenses.  Other values cause  the license
    to  interpreted as _p_r_o_p_r_i_e_t_a_r_y.   Proprietary licenses are  reported
    by eval_license/0.  See the file boot/license.pl for details.

    ____________________________________________________________________|                                                                    |
    | :- multifile license:license/3.                                    |

    |                                                                    |
    | license:license(mylicense, lgpl,                                   |
    |                 [ comment('My personal license'),                  |
    |                   url('http://www.mine.org/license.html')          |
    |                 ]).                                                |
    |                                                                    |
    ||:-_license(mylicense).____________________________________________ ||


lliicceennssee((_+_L_i_c_e_n_s_e_I_d))
    Intented  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().


1155..44 LLiicceennssee ccoonnddiittiioonnss iinnhheerriitteedd ffrroomm uusseedd ccooddee


1155..44..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 1166..  SSUUMMMMAARRYY


1166..11 PPrreeddiiccaatteess

The  predicate summary  is used  by the  Prolog  predicate apropos/1  to
suggest predicates from a keyword.

 !/0                           Cut (discard choicepoints)
 ,/2                           Conjunction of goals
 ->/2                          If-then-else
 *->/2                         Soft-cut
 ./2                           Consult.  Also list constructor
 ;/2                           Disjunction of goals.  Same as |/2
 </2                           Arithmetic smaller
 =/2                           Unification

 =../2                         ``Univ.''  Term to list conversion
 =:=/2                         Arithmetic equal
 =</2                          Arithmetic smaller or equal
 ==/2                          Identical
 =@=/2                         Structural identical
 =\=/2                         Arithmetic not equal
 >/2                           Arithmetic larger

 >=/2                          Arithmetic larger or equal
 ?=/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                          Not unifiable

 \==/2                         Not identical
 \=@=/2                        Not structural identical
 ^/2                           Existential quantification (bagof/3, setof/3)
 |/2                           Disjunction of goals.  Same as ;/2
 abolish/1                     Remove predicate definition from the database
 abolish/2                     Remove predicate definition from the database
 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
 arithmetic_function/1         Register an evaluable function
 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
 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                 Append two atoms
 atom_length/2                 Determine length of an atom
 atom_prefix/2                 Test for start of atom
 atom_number/2                 Convert between atom and number
 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 atoms
 atomic_list_concat/3          Append a list of atoms with separator
 autoload/0                    Autoload all predicates now
 b_getval/2                    Fetch backtrackable global variable
 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
 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_residue_vars/2           Find residual attributed variables

 call_shared_object_function/2 UNIX: Call C-function in shared (.so) file
 call_with_depth_limit/3       Prove goal with bounded depth
 callable/1                    Test for atom or compound term
 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

 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_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_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_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
 cyclic_term/1                 Test term for cycles
 day_of_the_week/2             Determine ordinal-day from date

 date_time_stamp/2             Convert sate structure to time-stamp
 date_time_value/3             Extract info from a date structure
 dcg_translate_rule/2          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
 del_attr/2                    Delete attribute from variable
 del_attrs/1                   Delete all attributes from variable
 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
 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)
 ensure_loaded/1               Consult a file if that has not yet been done
 erase/1                       Erase a database record or clause
 eval_license/0                Evaluate licenses of loaded modules
 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_query/4                Expanded entered query
 expand_term/2                 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
 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
 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
 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
 get0/1                        Read next character
 get0/2                        Read next character from a stream
 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_single_char/1             Read next character from the terminal
 get_time/1                    Get current time

 getenv/2                      Get shell environment variable
 goal_expansion/2              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
 hash/1                        Index predicate using a hash-table
 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
 include/1                     Include a file with declarations

 index/1                       Change clause indexing
 initialization/1              Initialization directive
 initialization/2              Initialization directive
 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_list/1                     Type check for a list
 is_stream/1                   Type check for a stream handle
 join_threads/0                Join all terminated threads interactively
 keysort/2                     Sort, using a key
 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/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

 listing/0                     List program in current module
 listing/1                     List predicate
 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_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
 max_assoc/3                   Highest key in association tree
 memberchk/2                   Deterministic member/2
 message_hook/3                Intercept print_message/2

 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              Quintus compatibility
 min_assoc/3                   Lowest key in association tree

 module/1                      Query/set current type-in module
 module/2                      Declare a module
 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_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_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
 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
 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
 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)
 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
 phrase/2                      Activate grammar-rule set
 phrase/3                      Activate grammar-rule set (returning rest)
 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
 preprocessor/2                Install a preprocessor before the compiler

 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/3                     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_choice_attribute/3     Examine the choice-point stack
 prolog_current_frame/1        Reference to goal's environment stack
 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
 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

 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
 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/1                 Read clause
 read_clause/2                 Read clause from stream
 read_history/6                Read using history substitution
 read_link/3                   Read a symbolic link
 read_pending_input/3          Fetch buffered input from a stream
 read_term/2                   Read term with options
 read_term/3                   Read term with options from stream

 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_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
 set_base_module/1             Declare the associated global module
 set_end_of_stream/1           Set physical end of an open file
 set_input/1                   Set current input stream from a stream
 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_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
 set_tty/2                     Set `tty' stream
 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/0                       Execute interactive subshell
 shell/1                       Execute OS command

 shell/2                       Execute OS command
 show_profile/1                Show results of the profiler
 show_profile/2                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
 rl_add_history/1              Add line to readline(3) history

 rl_read_history/1             Read readline(3) history
 rl_read_init_file/1           Read readline(3) init file
 rl_write_history/1            Write readline(3) history
 sleep/1                       Suspend execution for specified time
 sort/2                        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_location/2             Location of last read term
 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_to_atom/2              Conversion between string and atom
 string_to_list/2              Conversion between string and list of character codes
 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_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
 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_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/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_initialization/1       Run action at start of thread

 thread_join/2                 Wait for Prolog task-completion
 thread_local/1                Declare thread-specific clauses for a predicate
 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_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
 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
 var/1                         Type check for unbound variable
 variant_sha1/2                Term-hash for term-variants
 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_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
 working_directory/2           Query/change CWD
 write/1                       Write term

 write/2                       Write term to stream
 writeln/1                     Write term, followed by a newline
 write_canonical/1             Write a term with quotes, ignore operators
 write_canonical/2             Write a term with quotes, ignore operators on a stream
 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


1166..22 LLiibbrraarryy pprreeddiiccaatteess


1166..22..11 aggregate

 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 the conjunction of instances of Goal using the bindings from Generator is true.
 free_variables/4 In order to handle variables properly, we have to find all the universally quantified variables in the Generator.


1166..22..22 apply

 exclude/3    Filter elements for which Goal fails.
 include/3    Filter elements for which Goal succeed.
 maplist/2    True if Goal can succesfully be applied on all elements of List.
 maplist/3    True if Goal can succesfully be applied to all succesive pairs of elements of List1 and List2.
 maplist/4    True if Goal can succesfully be applied to all succesive triples of elements of List1..List3.
 maplist/5    True if Goal can succesfully be applied to all succesive quadruples of elements of List1..List4.
 partition/4  Filter elements of List according to Pred.
 partition/5  Filter list according to Pred in three sets.


1166..22..33 assoc

 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/3Translate ordered list into an assoc
 put_assoc/4        Add association to an assoc


1166..22..44 broadcast

 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?


1166..22..55 charsio

 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/3     Use format/2 to write to a 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 with as once/1.

 with_output_to_chars/3Run Goal with as once/1.
 with_output_to_chars/4As with_output_to_chars/2, but Stream is unified with the temporary stream.
 write_to_chars/2      Codes is a list of character codes produced by write/1 on Term.
 write_to_chars/3      Codes is a difference-list of character codes produced by write/1 on Term.


1166..22..66 check

 check/0          Program completeness and consistency
 list_undefined/0 List undefined predicates

 list_autoload/0  List predicates that require autoload
 list_redefined/0 List locally redefined predicates


1166..22..77 csv

 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_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/3            Prolog DCG to `read/write' CSV data.
 csv/4            Prolog DCG to `read/write' CSV data.


1166..22..88 lists

 append/2        Concatenate a list of lists.
 append/3        List1AndList2 is the concatination of List1 and List2.

 delete/3        Is true when Lis1, with all occurences of Elem deleted results in List2.
 flatten/2       Is true it List2 is a non nested version of List1.
 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 if `Last' unifies with the last element of `List'.
 list_to_set/2   True when Set has the same element as List in the same order.
 max_list/2      True if Max is the largest number in List.
 member/2        True if Elem is a member of List.

 min_list/2      True if Min is the largest number in List.
 nextto/3        True of Y follows X in List.
 nth0/3          True if Elem is the Index'th element of List.
 nth1/3          Is true when Elem is the Index'th element of List.
 numlist/3       List is a list [Low, Low+1, ...  High].
 permutation/2   permutation(Xs, Ys) is true when Xs is a permutation of Ys.
 prefix/2        True iff Part is a leading substring of Whole.

 reverse/2       Is true when the elements of List2 are in reverse order compared to List1.
 select/3        Is true when List1, with Elem removed results in List2.
 select/4        Is true when select(X, XList) and select(Y, YList) are true, X and Y appear in the same locations of their respective lists and same_le@
 selectchk/3     Semi-deterministic removal of first element in List that unifies 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 from `Set' that occur in `Delete' (a set) and unify the result with `Result'.
 sumlist/2       Sum is the result of adding all numbers in List.

 union/3         True if Set3 unifies with the union of Set1 and Set2.


1166..22..99 option

 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 a OptionList.
 option/3        Get an option from a OptionList.
 select_option/3 Get and remove option from an option list.
 select_option/4 Get and remove option with default value.


1166..22..1100 ordsets

 ord_empty/1        Test empty ordered set
 list_to_ord_set/2  Create ordered set

 ord_add_element/3  Add element to ordered set
 ord_del_element/3  Delete element from ordered set
 ord_intersect/2    Test non-empty intersection
 ord_intersection/3 Compute intersection
 ord_disjoint/2     Test empty intersection
 ord_subtract/3     Delete set from set
 ord_union/3        Union of two ordered sets
 ord_union/4        Union and difference of two ordered sets

 ord_subset/2       Test subset
 ord_memberchk/2    Deterministically test membership


1166..22..1111 prologxref

 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


1166..22..1122 pairs

 group_pairs_by_key/2Group values with the same key.
 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 and sort the result on Value (the new key) using keysort/2.


1166..22..1133 pio


1166..22..1133..11 pure_input

 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.
 stream_to_lazy_list/2Create a lazy list representing the character codes in Stream.


1166..22..1144 readutil

 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


1166..22..1155 record

 record/1  Define named fields in a term


1166..22..1166 registry

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


1166..22..1177 ugraphs

 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/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


1166..22..1188 url

 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 between native value and application/x-www-form-encoded.


1166..22..1199 www_browser

 www_open_url/1 Open a web-page in a browser


1166..22..2200 clp/clpfd

 #/\/2                P and Q hold.
 #</2                 X is less than Y.
 #<==/2               Q implies P.
 #<==>/2              P and Q are equivalent.
 #=/2                 X equals Y.
 #=</2                X is less than or equal to Y.
 #==>/2               P implies Q.
 #>/2                 X is greater than Y.

 #>=/2                X is greater than or equal to Y.
 #\/1                 The reifiable constraint Q does _not_hold.
 #\//2                P or Q holds.
 #\=/2                X is not Y.
 all_different/1      Vars are pairwise distinct.
 all_distinct/1       Like all_different/1, with stronger propagation.
 automaton/3          Equivalent to automaton(_, _, Signature, Nodes, Arcs, [], [], _), a common use case of automaton/8.

 automaton/8          True if the finite automaton induced by Nodes and Arcs (extended with Counters) accepts Signature.
 chain/2              Zs is a list of finite domain variables that are a chain with respect to the partial order Relation, in the order they appear in t@
 circuit/1            True if the list Vs of finite domain variables induces a Hamiltonian circuit, where the k-th element of Vs denotes the successor o@
 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            Size is the number of elements of the current domain of Var, or the atom *sup* if the domain is unbounded.
 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 Equivalent to global_cardinality(Vs, Pairs, []).
 global_cardinality/3 Vs is a list of finite domain variables, Pairs is a list of Key-Num pairs, where Key is an integer and Num is a finite domain vari@
 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           Labeling means systematically trying out values for the finite domain variables Vars until all of them are ground.
 lex_chain/1          Lists are lexicographically non-decreasing.
 scalar_product/4     Cs is a list of integers, Vs is a list of variables and integers.
 serialized/2         Constrain a set of intervals to a non-overlapping sequence.
 sum/3                The sum of elements of the list Vars is in relation Rel to Expr, where Rel is #=, #\=, #<, #>, #=< or #>=.
 transpose/2          Transpose a list of lists of the same length.
 tuples_in/2          Relation must be a list of lists of integers.
 zcompare/3           Analogous to compare/3, with finite domain variables A and B.


1166..22..2211 clpqr

 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


1166..22..2222 clp/simplex

 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


1166..22..2233 thread_pool

 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.


1166..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 exclusive or
 >>/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
 asin/1                  Inverse (arc) sine
 atan/1                  Inverse (arc) tangent
 atan/2                  Rectangular to polar conversion
 atan2/2                 Rectangular to polar conversion
 ceil/1                  Smallest integer larger than arg
 ceiling/1               Smallest integer larger than arg
 cos/1                   Cosine

 cputime/0               Get CPU time
 div/2                   Integer division
 e/0                     Mathematical constant
 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
 integer/1               Round to nearest integer
 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
 powm/3                  Integer exponent and modulo
 random/1                Generate random number
 random/1                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
 sqrt/1                  Square root
 tan/1                   Tangent
 xor/2                   Bitwise exclusive or


1166..44 OOppeerraattoorrss

 $                     1    fx   Bind top-level variable
 ^                   200   xfy   Predicate
 ^                   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   Predicate
 discontiguous      1150    fx   Predicate

 dynamic            1150    fx   Predicate
 module_transparent 1150    fx   Predicate
 meta_predicate     1150    fx   Head
 multifile          1150    fx   Predicate
 thread_local       1150    fx   Predicate
 volatile           1150    fx   Predicate
 initialization     1150    fx   Predicate
 :-                 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]                       BIM  sa/nv,  Everberg,  Belgium.   _B_I_M
                                  _P_r_o_l_o_g _r_e_l_e_a_s_e _2_._4, 1989.

[Bowen _e_t _a_l_., 1983]              D.  L.   Bowen,   L.  M.   Byrd,   and
                                  WF.  Clocksin.   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_c  _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.

[Byrd, 1980]                      L.  Byrd.  Understanding  the  control
                                  flow   of  Prolog   programs.    _L_o_g_i_c
                                  _P_r_o_g_r_a_m_m_i_n_g _W_o_r_k_s_h_o_p, 1980.

[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     standard,     1998,
                                  http://www.sju.edu/~jhodgson/pub/suite.tar.gz.

[Holzbaur, 1992]                  Christian  Holzbaur.    Metastructures
                                  versus  attributed  variables  in  the
                                  context of extensible unification.  In
                                  _P_L_I_L_P,  volume  631,  pages  260--268.
                                  Springer-Verlag, 1992. LNCS 631.

[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.

[Neumerkel, 1993]                 Ulrich    Neumerkel.     The    binary
                                  WAM,   a    simplified   Prolog    en-
                                  gine.    Technical   report,     Tech-
                                  nische   Universit"at    Wien,    1993.
                                  http://www.complang.tuwien.ac.at/ulrich/papers/PDF/binwam-
                                  nov93.pdf.

[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.
                                  EdCaad, University of Edinburgh, 1986.

[Qui, 1997]                       AI  International  ltd.,  Berkhamsted,
                                  UK.  _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, 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.

                                  1514


Index

'MANUAL' _l_i_b_r_a_r_y, 49                 PL_quote(), 1016
-lswipl _l_i_b_r_a_r_y, 1131                PL_raise(), 1086
.pl, 98                              PL_raise_exception(), 1080
.pro, 98                             PL_realloc(), 1138
?=/2, 217                            PL_record(), 1094
=:=/2, 474                           PL_record_external(), 1097
/\/2, 511                            PL_recorded(), 1095
=\=/2, 473                           PL_recorded_external(), 1098
|/2, 226                             PL_register_atom(), 916
#/\/2, 1239                          PL_register_extensions(), 1113
#=/2, 1231                           PL_register_extensions_in_module(),
#<==>/2, 1236                              1112
#>=/2, 1229                          PL_register_foreign(), 1111
#>/2, 1233                           PL_register_foreign_in_module(), 1110
#=</2, 1230                          PL_representation_error(), 1034
#</2, 1234                           PL_reset_term_refs(), 896
#\=/2, 1232                          PL_retry(), 904
#\/1, 1235                           PL_retry_address(), 905
,/2, 224                             PL_rewind_foreign_frame(), 1073
#\//2, 1240                          PL_same_compound(), 1092
{}/1, 1261                           PL_set_engine(), 865
!/0, 223                             PL_signal(), 1085
/, 99                                PL_skip_list(), 977
//2, 484                             PL_strip_module(), 1076
./2, 495                             PL_succeed(), 901
=/2, 200                             PL_term_type(), 920
==/2, 203                            PL_thread_at_exit(), 861
>=/2, 472                            PL_thread_attach_engine(), 859
>/2, 469                             PL_thread_destroy_engine(), 860
^/2, 528                             PL_thread_self(), 857
///2, 487                            PL_throw(), 1081
->/2, 227                            PL_toplevel(), 1126
=</2, 471                            PL_type_error(), 1035
#<==/2, 1238                         PL_unify(), 998
<</2, 509                            PL_unify_arg(), 1013
</2, 470                             PL_unify_atom(), 999
-/1, 479                             PL_unify_atom_chars(), 1002
-/2, 482                             PL_unify_atom_nchars(), 960
\=/2, 201                            PL_unify_blob(), 1048
\/1, 513                             PL_unify_bool(), 1000
\==/2, 204                           PL_unify_bool_ex(), 1032
\+/1, 229                            PL_unify_chars(), 1001
\//2, 510                            PL_unify_float(), 1008
+/1, 480                             PL_unify_functor(), 1010
+/2, 481                             PL_unify_int64(), 1007
**/2, 526                            PL_unify_integer(), 1006
#==>/2, 1237                         PL_unify_list(), 1011
>>/2, 508                            PL_unify_list_chars(), 1003
;/2, 225                             PL_unify_list_ex(), 1030
*->/2, 228                           PL_unify_list_nchars(), 963
=@=/2, 212                           PL_unify_list_ncodes(), 962
\=@=/2, 213                          PL_unify_mpq(), 1056
@>=/2, 208                           PL_unify_mpz(), 1055
@>/2, 207                            PL_unify_nil(), 1012
*/2, 483                             PL_unify_nil_ex(), 1031
@=</2, 206                           PL_unify_pointer(), 1009
@</2, 205                            PL_unify_string_chars(), 1004
=../2, 411                           PL_unify_string_nchars(), 961, 1005
_PL_get_arg(), 951                   PL_unify_term(), 1014
\, 99                                PL_unify_thread_id(), 858
64-bits                              PL_unify_wchars(), 970
   platforms, 92                     PL_unify_wchars_diff(), 971

abolish/1, 17, 261, 262              PL_unregister_atom(),P917L_unregister_blob_type(), 1045
abolish/2, 262                       PL_warning(), 1104
abolish/[1                           plus/3, 467
   2], 66                            PLVERSION, 1140
abort/0,  45,  57, 310,  315,  322,  popcount/1, 536
      636, 787, 838, 1106, 1116      portable
abs/1, 491                              prolog code, 1468
absolute_file_name/2, 620            portray/1, 57, 101, 388, 396,  398,
absolute_file_name/3, 621                  1063, 1120, 1457
absolute_file_name/2, 34,  131, 143, portray_clause/1, 180
      622, 632, 1153                 portray_clause/2, 181
absolute_file_name/3, 66,  69,  123, portray_text _l_i_b_r_a_r_y, 396
      130,   140,  144,  145,  620,  portray_clause/1, 178, 181
      621, 1100, 1101, 1376, 1377    portray_clause/2, 180, 413
absolute_file_name/[2                powm/3, 527
   3], 66, 139, 621                  precedence, 1473
access_file/2, 610                   pred/1, 717
access_file/2, 66, 621               predicate, 1473
acos/1, 519                             dynamic, 1473
acquire(), 1041                         exported, 1473
acyclic_term/1, 198                     imported, 1473
acyclic_term/1, 82, 197              predicate indicator, 128, 1473
add_edges/3, 1416                    predicate_property/2, 302
add_import_module/3, 724             predicate_property/2,   293,    300,
add_nb_set/2, 1321                         302, 737
add_nb_set/3, 1322                   predsort/3, 549
add_vertices/3, 1414                 prefix/2, 1296
add_import_module/3, 723, 738        preprocessor/2, 158
add_nb_set/3, 1321, 1323             print/1, 388, 396,  398, 561,  566,
agent, 1191                                1063, 1486
aggregate _l_i_b_r_a_r_y, 1488              print/2, 397
aggregate/3, 1161                    print_message/2, 248, 1486
aggregate/4, 1162                    print_message_lines/3, 249
aggregate_all/3, 1163                print_message/2,  20, 66,  69,  131,
aggregate_all/4, 1164                      147,   247--250,  252,   403,
all_different/1, 1226                      686, 803, 805, 1282
all_distinct/1, 1243                 print_message_lines/3, 20,  248, 250,
Alpha                                      252
   DEC, 16                           priority, 1473
AMD64, 93                            profile file, 41
anonymous                            profile/1, 672, 673, 852, 1128
   variable, 81                      profile/3, 673
anonymous variable, 1473             profiler/2, 676
append/1, 324, 328                   profiling
append/2, 711, 1295                     foreign code, 1141
append/3, 433, 1294                  program, 1473
apply _l_i_b_r_a_r_y, 1489                  prolog/0, 45, 323,  635, 639,  640,
apply/2, 233                               716, 1126, 1447
apropos/1, 51, 52, 69, 1459, 1486    prolog:called_by/2, 1370
arg/3, 410                           prolog:comment_hook/3, 1462
arithmetic_function/1, 538           prolog:debug_control_hook/1, 1458
arithmetic_function/1,   537,   539, prolog:help_hook/1, 1459
      1079                           prolog_choice_attribute/3, 1446
arity, 1473                          prolog_current_frame/1, 1444
asin/1, 518                          prolog_edit:edit_command/2, 176
assert, 1473                         prolog_edit:edit_source/1, 175
assert/1, 130, 138,  260, 266, 268,  prolog_edit:load/0, 177
      281,   287,  288,  302,  705,  prolog_edit:locate/2, 174
      712, 739, 764, 829, 1473       prolog_edit:locate/3, 173
assert/2, 271, 278, 305              prolog_exception_hook/4, 1453
asserta/1, 46, 138,  212, 266, 267,  prolog_file_type/2, 141
      269, 270                       prolog_frame_attribute/3, 1445
asserta/2, 269, 278                  prolog_ide _c_l_a_s_s, 125
assertion/1, 1287                    prolog_ide/1, 125
assertions, 1287                     prolog_list_goal/1, 1457
assertz/1, 267, 268, 1473            prolog_load_context/2, 145
assertz/2, 270, 271, 278             prolog_load_file/2, 1461
assignment/2, 1390                   prolog_server _l_i_b_r_a_r_y, 323
assoc _l_i_b_r_a_r_y, 1176, 1319, 1490      prolog_skip_frame/1, 1450
assoc_to_keys/2, 1178                prolog_skip_level/2, 1451
assoc_to_list/2, 1177                prolog_stack _l_i_b_r_a_r_y, 1445, 1453
assoc_to_values/2, 1179              prolog_stack_property/2, 687
at_end_of_stream/0, 381              prolog_to_os_filename/2, 626
at_end_of_stream/1, 382              prolog_trace_interception/4, 1449
at_halt/1, 147                       prolog_xref _l_i_b_r_a_r_y, 122, 706, 1360
at_end_of_stream/1, 386              prolog_choice_attribute/3, 1449
at_end_of_stream/[0                  prolog_current_frame/1, 1445
   1], 315, 1372                     prolog_exception_hook/4,   245,  686,
at_halt/1,  637,  809,  1118,  1127,       1452, 1453
      1466                           prolog_file_type/2, 130, 141, 621
at_initialization/1, 1123            prolog_frame_attribute/3,  307, 1449,
atan/1, 520                                1453
atan/2, 522                          prolog_ide/1, 124
atan2/2, 521, 522                    prolog_load_context/2, 146, 1469
atom, 1473                           prolog_load_file/2, 131, 1460
atom/1, 190, 918                     prolog_skip_frame/1, 1451
atom_chars/2, 425                    prolog_skip_level/2, 1450
atom_codes/2, 424                    prolog_stack_property/2, 686
atom_concat/3, 433                   prolog_to_os_filename/2, 99, 622
atom_length/2, 437                   prolog_trace_interception/4,     114,
atom_number/2, 429                         651, 686, 1445, 1446
atom_prefix/2, 438                   prologxref _l_i_b_r_a_r_y, 1498
atom_to_chars/2, 1205                prompt
atom_to_chars/3, 1206                   alternatives, 66
atom_to_term/3, 432                  prompt/2, 405--407
atom_chars/2,  66,  129,  339,  366, prompt1/1, 407
      423, 427, 442                  property, 1473
atom_codes/2,   21,  66,  129,  339, protocol/1, 643, 644, 646
      423, 425, 429, 430, 442        protocola/1, 644, 646
atom_concat/3, 455                   protocolling/1, 646
atom_length/2, 66, 454               prove, 1473
atom_number/2, 339                   public list, 1473
atom_result/2, 731                   public/1, 291, 302
atomic/1, 193                        pure_input _l_i_b_r_a_r_y, 1501
atomic_concat/3, 434                 put/1, 349, 350
atomic_list_concat/2, 435            put/2, 350
atomic_list_concat/3, 436            put_assoc/4, 1190
atomic_concat/3, 433                 put_attr/3, 743
atomic_list_concat/2, 436            put_attrs/2, 756
attach_console/0, 845                put_byte/1, 351
attach_console/0, 843, 844, 1106     put_byte/2, 352
attr_portray_hook/2, 748             put_char/1, 353
attr_unify_hook/2, 747               put_char/2, 354
attr_portray_hook/2, 388             put_code/1, 355
attr_unify_hook/2, 740               put_code/2, 356
attribute_goals/1, 749               put_attr/3, 742, 747, 754
attribute_goals//1, 748, 751         put_byte/[1
attribute_goals/3, 740                  2], 129
attvar/1, 742                        put_char/1, 349, 355
autoload/0, 135, 1145, 1147, 1218    put_char/[1
automaton/3, 1249                       2], 129
automaton/8, 1250                    put_code/1, 349, 356

b_getval/2, 766                      put_code/2,p84,u384,t386_code/[1
b_setval/2, 765                         2], 129
b_getval/2, 766, 768
b_setval/2, 764, 1455                qcompile/1, 131, 150, 167--169, 798
backcomp _l_i_b_r_a_r_y, 17, 21             qcompile/2, 169
backtracking, 1473                   qsave_program/1, 1146
bagof/3, 82, 551, 553, 554, 1486     qsave_program/2, 1145
bb_inf/3, 1269                       qsave_program/1, 148
bb_inf/4, 1268                       qsave_program/2,  14, 64,  66,  101,
bb_inf/5, 1267                             124, 1144, 1145, 1151
between/3, 465                       qsave_program/[1
binding, 1473                           2],  13, 18,  46, 63,  66,  302,
bits                                       875, 1123, 1133, 1147, 1149
   64, 91                            query, 1473
blackboard, 1191                     quiet, 43, 248
blob/2, 191, 309                     quintus _l_i_b_r_a_r_y, 21
body, 1473
BOM, 85                              random _l_i_b_r_a_r_y, 541
break/0, 45, 57, 635, 787, 1106      random/1, 496, 541
broadcast, 1191                      rational
broadcast _l_i_b_r_a_r_y, 1191, 1491           number, 476
broadcast/1, 1192, 1193              rational/1, 187, 476, 477, 500, 501
broadcast_request/1, 1193            rational/3, 188, 476
built-in predicate, 1473             rationalize/1, 476, 477, 500,  501,
Byte Order Mark, 85                        1400
byte_count/2, 342                    rb_new/1, 66
byte_count/2, 320                    rbtrees _l_i_b_r_a_r_y, 66
call/1,  21,  122, 195,  231,  233,  RDFmemory usage, 94
      243,   655,  678,  680,  705,  rdiv/2, 476, 477, 484, 489
      759, 1057                      reachable/3, 1427
call/2, 232                          read/1, 66, 89, 309, 310, 359, 394,
call/[2-6], 232                            399,  401,  403,   406,  451,
call_cleanup/2, 240                        665, 772, 1377, 1486
call_cleanup/3, 241                  read/2, 341, 400
call_residue_vars/2, 763             read_clause/1, 401
call_shared_object_function/2, 889   read_clause/2, 402
call_with_depth_limit/3, 237         read_file_to_codes/3, 1376
call_cleanup/2,  238, 240, 241, 339, read_file_to_terms/3, 1377
      1447, 1472                     read_from_chars/2, 1209
call_residue_vars/2, 763             read_history/6, 405
call_with_depth_limit/3, 237         read_line_to_codes/2, 1372
call_with_time_limit/2, 238          read_line_to_codes/3, 1373
callable/1, 195, 1360                read_link/3, 627
catch/3,  17,  19,  242--245,  403,  read_pending_input/3, 386
      636,   678,  803,  811,  812,  read_stream_to_codes/2, 1374
      1446, 1453--1455, 1486         read_stream_to_codes/3, 1375
ceil/1, 507                          read_term/2, 403
ceiling/1, 506, 507                  read_term/3, 404
chain/2, 1253                        read_term_from_chars/3, 1210
char_code/2, 426                     read_clause/1, 402, 665
char_conversion/2, 461               read_history/6, 405
char_type/2, 441                     read_line_to_codes/2, 1373
char_code/2, 129                     read_line_to_codes/3, 1372
char_conversion/2, 66, 462           read_stream_to_codes/2, 1375
char_type/2, 80, 442--444            read_term/2, 66, 401, 403--405, 432
character set, 77                    read_term/3,  388,  403,  461,  640,
character_count/2, 343                     1462
character_count/2, 320, 342          read_term/[2
charsio _l_i_b_r_a_r_y, 1492                   3], 403
chdir/1, 632, 633                    readutil _l_i_b_r_a_r_y, 103, 1371, 1502
check _l_i_b_r_a_r_y, 137, 302, 1215, 1493  record _l_i_b_r_a_r_y, 1378, 1503
check/0, 135, 1215, 1216             record/1, 1378, 1379
check_old_select/0, 22               recorda/2, 273
checkselect _l_i_b_r_a_r_y, 22              recorda/3, 82, 272, 274, 278,  299,
chr _l_i_b_r_a_r_y, 784, 788                      764, 1093, 1094, 1097
chr_constraint/1, 782                recorded/2, 277
chr_leash/1, 791                     recorded/3, 276, 278, 1149
chr_notrace/0, 790                   recordz/2, 275
chr_option/2, 778                    recordz/3, 82, 274
chr_show_store/1, 792                redefine_system_predicate/1, 263
chr_trace/0, 789                     redefine_system_predicate/1,      11,
chr_type/1, 783                            1473
chr_constraint/1, 782, 796           reexport/1, 131, 718, 1468
chr_notrace/0, 787                   reexport/2, 131, 719, 1468
chr_option/2, 796                    registry, 87
chr_trace/0, 787                     registry _l_i_b_r_a_r_y, 1380, 1504
chr_type/1, 783                      registry_delete_key/1, 1385
circuit/1, 1248                      registry_get_key/2, 1381
clause, 1473                         registry_get_key/3, 1382
clause/2, 304, 305                   registry_set_key/2, 1383
clause/3, 269, 278, 305, 307, 1149   registry_set_key/3, 1384
clause/[2                            release(), 1042
   3], 66                            reload_foreign_libraries/0, 884
clause_property/2, 307               reload_library_index/0, 73
clause_property/2, 143, 1445         reload_library_index/0, 70, 73
close/1, 308, 313, 318               rem/2, 486
close/2, 314                         rename_file/2, 617
close_dde_conversation/1, 691        repeat/0, 218, 222, 237
close_shared_object/1, 888           representation_error/1, 1034
clp/clpfd _l_i_b_r_a_r_y, 1508              require/1, 135, 1147, 1468
clp/simplex _l_i_b_r_a_r_y, 1510            reset_gensym/0, 1291
clpfd _l_i_b_r_a_r_y, 720                   reset_gensym/1, 1290
clpqr _l_i_b_r_a_r_y, 1259, 1509            reset_profiler/0, 677
code_type/2, 442                     reset_profiler/0, 673
code_type/2, 440, 443                resource/3,  18,  66,  1144,  1145,
collate, 448                               1151, 1153, 1154
collation_key/2, 449                 restract/2, 739
collation_key/2, 449, 450, 589       retract, 1473
COM, 1039                            retract/1, 130, 138, 260, 261, 264,
commandline                                281, 287, 288, 302, 829
   arguments, 43                     retractall/1, 260, 261, 265
compare                              rev/3, 707
   language-specific, 448            reverse/2, 707, 1306
compare(), 1043                      rl_add_history/1, 1465
compare/3, 82, 209, 549, 1091, 1472  rl_read_history/1, 1467
compile_aux_clauses/1, 156           rl_read_init_file/1, 1464
compile_predicates/1, 288            rl_write_history/1, 1466
compile_predicates/1, 287            rlimit _l_i_b_r_a_r_y, 25
compiling/0, 150, 168                round/1, 497, 498
complement/2, 1421
completion                           same_file/2, 614
   TAB, 105                          same_term/2, 422
compose/3, 1422                      scalar_product/4, 1228
compound, 1473                       see/1, 20, 308, 310, 324--326
compound/1, 194                      seeing/1, 324, 325, 329
concat_atom/3, 436                   seek/4, 315, 319, 321
constraint/3, 1391, 1392             seen/0, 331
constraint/4, 1392                   select/3, 22, 1297
constraint_add/4, 1393               select/4, 1299
consult/1,  38,  41, 59,  69,  113,  select_option/3, 1331
      130--133,   167,   168,  289,  select_option/4, 1332
      401, 665                       selectchk/3, 1298
context module, 1473                 selectchk/4, 1300
context_module/1, 733                serialized/2, 1244
context_module/1, 713, 733, 1063     set_base_module/1, 722
convert_time/2, 66                   set_end_of_stream/1, 383
convert_time/[2                      set_input/1, 334
   8], 619                           set_output/1, 335
copy_stream_data/2, 385              set_prolog_flag/2, 67
copy_stream_data/3, 384              set_prolog_IO/3, 323
copy_term/2, 416                     set_prolog_stack/2, 686
copy_term/3, 751                     set_random/1, 541
copy_term_nat/2, 752                 set_stream/2, 322
copy_stream_data/2, 386              set_stream_position/2, 319
copy_stream_data/3, 321              set_tty/2, 575
copy_term/2,   82,  212,  416,  418, set_url_encoding/2, 1436
      421, 739, 752, 766             set_input/1, 322, 326
copy_term/3, 748, 749                set_output/1, 327
cos/1, 516                           set_prolog_flag/2,  21,  55,  65--68,
count_atom_results/3, 731                  468
count_atom_results/3, 731            set_prolog_stack/2, 656, 687
cputime/0, 532                       set_random/1, 496, 541
create_prolog_flag/3, 68             set_stream/2,  84,  310,  315,  323,
create_prolog_flag/3, 66, 67               341, 377
crypt _l_i_b_r_a_r_y, 1484                  set_stream_position/2, 315, 321
csv _l_i_b_r_a_r_y, 1494                    setarg/3, 128, 416, 418, 419,  421,
csv//1, 1277                               422, 743, 772, 1378
csv//2, 1278                         setenv/2, 587
csv_read_file/2, 1275                setlocale/3, 450, 589
csv_read_file/3, 1276                setof/3, 82, 554, 1486
csv_write_file/2, 1279               setup_call_catcher_cleanup/4, 239
csv_write_file/3, 1280               setup_call_cleanup/3, 238
ctype _l_i_b_r_a_r_y, 440                   setup_call_cleanup/3, 238,  240, 807,
current_arithmetic_function/1, 539         834, 835
current_atom/1, 295                  shadow_price/3, 1398
current_blob/2, 296                  shared, 1473
current_char_conversion/2, 462       shell/0, 580, 590
current_flag/1, 298                  shell/1, 99, 176, 579, 590
current_foreign_library/2, 883       shell/2, 578
current_format_predicate/2, 570      shell/[0-2], 587
current_functor/2, 297               shell/[1
current_input/1, 336                    2], 578
current_key/1, 299                   shell_register_dde/6, 1387
current_module/1, 736                shell_register_file_type/4, 1386
current_op/3, 459                    shell_register_prolog/1, 1388
current_output/1, 337                shell_register_file_type/4, 1387
current_predicate/1, 300             shlib _l_i_b_r_a_r_y, 1486
current_predicate/2, 301             show_profile/1, 675
current_prolog_flag/2, 66            show_profile/2, 674
current_signal/3, 255                show_profile/1, 673
current_stream/3, 316                sign/1, 492
current_thread_pool/1, 1407          silent, 248
current_atom/1, 295                  simplex _l_i_b_r_a_r_y, 1389
current_blob/2, 1040                 sin/1, 515
current_char_conversion/2, 461       singleton, 1473
current_input/1, 145, 329               variable, 81
current_module/1, 300                size_file/2, 618
current_output/1, 330                size_nb_set/2, 1324
current_predicate/1, 300--302        skip/1, 378, 379
current_predicate/2, 300, 301        skip/2, 379
current_prolog_flag/2, 21,  43,  46, sleep/1, 704
      65,  66,  70,  74,  78,  131,  socket _l_i_b_r_a_r_y, 341
      403,  665,  696,  874,  1158,  Solaris, 810
      1473                           solution, 1473
current_signal/3, 254                sort/2, 546, 547,  549, 554,  1335,
current_stream/3, 316                      1337
cyclic terms, 82                     source_exports/2, 1471
cyclic_term/1, 197                   source_file/1, 142
cyclic_term/1, 82, 198               source_file/2, 143

daemon, 1191                         source_location/2,s146ource_exports/2, 1468
date_time_stamp/2, 596               source_file/1, 144
date_time_value/3, 597               source_file/2, 168, 302
date_time_value/3, 592               source_location/2, 145
day_of_the_week/2, 602               spy/1, 57, 66,  69, 115, 116,  126,
DCG, 130, 257                              128,  659,  715,   850,  851,
dcg_translate_rule/2, 157                  1458, 1486
dcg_translate_rule/2, 153            sqrt/1, 514
dde_current_connection/2, 699        stack
dde_current_service/2, 698              memory management, 88
dde_execute/2, 693                   stamp_date_time/3, 595
dde_poke/4, 694                      stamp_date_time/3, 592, 596
dde_register_service/2, 696          startup file, 41
dde_request/3, 692                   statistics _l_i_b_r_a_r_y, 670
dde_unregister_service/1, 697        statistics/0, 668
debug _l_i_b_r_a_r_y, 125, 1281             statistics/2, 532, 667, 813
debug/0,  57, 245,  654, 656,  657,  stream_pair/3, 318
      686, 846, 1106, 1453           stream_position_data/3, 320
debug/1, 1282, 1284, 1285            stream_property/2, 315
debug/3, 1281, 1282                  stream_to_lazy_list/2, 1359
debugging                            stream_pair/3, 309
   exceptions, 245                   stream_position_data/3,   145,   315,
debugging/0,  69,  654, 658,  1286,        403, 1462
      1458                           stream_property/2,  85,  310,  319--
debugging/1, 1281, 1283                    322, 403
DEC                                  string/1, 192, 193, 566
   Alpha, 16                         string_concat/3, 455
del_attr/2, 745                      string_length/2, 454
del_attrs/1, 757                     string_to_atom/2, 452
del_edges/3, 1417                    string_to_list/2, 453
del_vertices/3, 1415                 strip_module/3, 734
del_attr/2, 754                      strip_module/3, 713, 731, 738
delete/3, 1302                       structure, 1473
delete_directory/1, 631              style_check/1, 665
delete_file/1, 616                   style_check/1, 81, 89, 90, 290
delete_import_module/2, 725          sub_atom/5, 439
delete_file/1, 629                   sub_string/5, 456
delete_import_module/2,  723,   724, sub_atom/5, 456
      738                            subset/2, 1317
deterministic/1, 238, 1447           subsumes_term/2, 214
Development environment, 95          subsumes_chk/2, 285
dialect.pl _l_i_b_r_a_r_y, 1468             subsumes_term/2, 210
dif _l_i_b_r_a_r_y, 762                     subtract/3, 1318
dif/2, 82, 201, 761, 762             succ/2, 466
directory_files/2, 624               succeed, 1473
discontiguous/1, 286, 290            sum/3, 1227
display/1, 561, 978                  sumlist/2, 1309
display/[1                           sup/2, 1264
   2], 17                            swi/pce_profile _l_i_b_r_a_r_y, 670
displayq/[1                          swi_edit _l_i_b_r_a_r_y, 177
   2], 17                            swi_help _l_i_b_r_a_r_y, 49
div/2, 488                           swritef/2, 563
do_not_use/1, 717                    swritef/3, 339, 562
domain_error/2, 1036
downcase_atom/2, 444                 TAB
downcase_atom/2, 441, 445               completion, 105
dump/3, 1270                         tab/1, 357
dup/2, 21                            tab/2, 358
dup_stream/2, 21                     tan/1, 517
duplicate_term/2, 421                tdebug/0, 847, 851
duplicate_term/2, 82, 416, 419, 767  tdebug/1, 846, 847, 850
dwim_match/2, 701                    tell/1, 20,  308,  310,  324,  325,
dwim_match/3, 702                          327, 328
dwim_predicate/2, 303                telling/1, 324, 325, 330
dwim_match/2, 303, 702               term, 1473
dynamic predicate, 1473              term//1, 339
dynamic/1,   66,  128,   260,  265,  term_attvars/2, 753
      286--288,   302,   732,  828,  term_expansion/2, 152
      829, 1217                      term_hash/2, 283

e/0, 530                             term_hash/4,t284erm_subsumer/3, 215
edges/2, 1413                        term_to_atom/2, 431
edit/0, 172                          term_variables/2, 414
edit/1, 23, 66,  69, 105, 108, 113,  term_variables/3, 415
      126,   137,   170--173,  175,  term_attvars/2, 753
      715, 1217, 1486                term_expansion/2,  69,  130,   150--
edit_source/1, 176                         154,  159,  168,   640,  784,
editor _c_l_a_s_s, 104, 109                     1472
element/3, 1245                      term_hash/2, 82, 282--285, 292, 293
elif/1, 161                          term_hash/4, 282
else/0, 162                          term_to_atom/2, 339, 1015
Emacs, 48                            term_variables/2, 82, 403, 415
emacs/[0                             term_variables/3, 414
   1], 108                           terms
emacs/prolog_colour _l_i_b_r_a_r_y, 112        cyclic, 82
emacs/swi_prolog _l_i_b_r_a_r_y, 23         thread _l_i_b_r_a_r_y, 66
empty_assoc/1, 1180                  thread_at_exit/1, 809
empty_nb_set/1, 1320                 thread_create/3, 803
encoding/1, 84, 136                  thread_create_in_pool/4, 1409
endif/0, 163                         thread_detach/1, 806
ensure_loaded/1, 133                 thread_exit/1, 807
ensure_loaded/1, 59, 130, 133, 710   thread_get_message/1, 818
entailed/1, 1262                     thread_get_message/2, 823
epsilon/0, 531                       thread_initialization/1, 808
erase/1, 269, 272, 278, 305          thread_join/2, 805
error _l_i_b_r_a_r_y, 1378                  thread_local/1, 829
eval/1, 533                          thread_peek_message/1, 819
eval_license/0, 1479                 thread_peek_message/2, 824
eval_license/0, 1478, 1480           thread_pool _l_i_b_r_a_r_y, 1511
exception/3, 764, 1454, 1455         thread_pool_create/3, 1405
exceptions                           thread_pool_destroy/1, 1406
   debugging, 245                    thread_pool_property/2, 1408
exclude/3, 1169                      thread_property/2, 812
exists_directory/1, 615              thread_self/1, 804
exists_file/1, 611                   thread_send_message/2, 817
exists_source/1, 1470                thread_setconcurrency/2, 810
exists_file/1, 66                    thread_signal/2, 827
exists_source/1, 1468                thread_statistics/3, 813
exp/1, 525                           thread_at_exit/1, 803, 861
expand_answer/2, 641                 thread_create/3, 806, 809, 867, 869
expand_file_name/2, 625              thread_detach/1, 803
expand_file_search_path/2, 140       thread_exit/1, 805, 812
expand_goal/2, 155                   thread_get_message/1, 823
expand_query/4, 640                  thread_get_message/2, 822
expand_term/2, 153                   thread_initialization/1, 764
expand_answer/2, 640                 thread_join/2, 803, 805, 807, 812
expand_file_name/2,  66,  131,  587, thread_local/1, 287, 302, 828
      590, 620, 621, 624             thread_peek_message/1, 818, 824
expand_goal/2, 66, 151--155, 160     thread_property/2,  805,  806,  809,
expand_term/2,  151, 152,  154, 157,       812
      257, 1379                      thread_self/1, 66, 806, 809, 817
expects_dialect/1, 1469              thread_send_message/2, 820, 821
expects_dialect/1, 145, 1468         thread_setconcurrency/2, 66
explain _l_i_b_r_a_r_y, 1486                thread_signal/2,   238,  827,   838,
explain/1, 53                              846, 1086, 1130
explain/2, 54                        threads/0, 841
export/1, 728--730                   throw/1, 17, 57, 82, 242--244, 252,
export_list/2, 729                         256,  807,  812,   826,  827,
exported predicate, 1473                   1080, 1082, 1453--1455

fact, 1473                           time/1,t532,i669,m672,e673_file/2, 619
fail/0, 155, 219                     tmp_file/2, 628
false/0, 220                         tmp_file_stream/3, 629
fd_dom/2, 1258                       tmp_file/2, 629
fd_inf/2, 1255                       tmp_file_stream/3, 628
fd_size/2, 1257                      tnodebug/0, 849
fd_sup/2, 1256                       tnodebug/1, 848, 851
fd_var/1, 1254                       told/0, 332
file_base_name/2, 613                top_sort/2, 1424
file_directory_name/2, 612           top_sort/3, 1425
file_name_extension/3, 623           tprofile/1, 852, 853
file_name_to_url/2, 1440, 1441       trace/0, 57,  66,  115,  116,  126,
file_search_path/2, 139                    648,  654,  789,   790,  827,
file_search_path/2, 41, 46,  66, 70,       1106, 1453
      73,  100, 123, 131, 132, 139,  trace/1, 66, 653
      141,  145, 1101,  1133, 1150,  trace/2, 654
      1153, 1156                     tracing/0, 649
fileerrors/2, 66                     transformation
find_chr_constraint/1, 793              of program, 151
findall/3, 82, 212,  218, 551, 552,  transitive_closure/2, 1426
      739, 1486                      transparent, 1473
findall/4, 552                       transportation/4, 1399
flag/3, 280, 298, 419                transpose/2, 1251, 1418
flag:address_bits, 66                transpose_pairs/2, 1353
flag:agc_margin, 66                  trim_stacks/0, 685
flag:allow_variable_name_as_functor, trim_stacks/0, 683, 686
      66                             true/0, 66, 155, 221, 237
flag:arch, 66                        truncate/1, 504
flag:argv, 66                        tspy/1, 844, 851
flag:associate, 66                   tspy/2, 850
flag:autoload, 66                    tty_get_capability/3, 572
flag:backquoted_string, 66           tty_goto/2, 573
flag:bounded, 66                     tty_put/2, 574
flag:c_cc, 66                        tty_size/2, 576
flag:c_ldflags, 66                   tty_get_capability/3, 574, 576
flag:c_libs, 66                      tty_goto/2, 575
flag:char_conversion, 66             tty_put/2, 575
flag:character_escapes, 66           tty_size/2, 576
flag:compiled_at, 66                 ttyflush/0, 361, 561
flag:console_menu, 66                tuples_in/2, 1242
flag:cpu_count, 66                   type_error/2, 252, 1035, 1037
flag:dde, 66
flag:debug, 66                       UCS, 83
flag:debug_on_error, 66              ugraph _l_i_b_r_a_r_y, 1410
flag:debugger_print_options, 66      ugraph_union/3, 1423
flag:debugger_show_context, 66       ugraphs _l_i_b_r_a_r_y, 1410, 1505
flag:dialect, 66                     ugraphs.pl _l_i_b_r_a_r_y, 1410
flag:double_quotes, 66               Unicode, 83
flag:editor, 66                      unifiable/3, 210, 216
flag:emacs_inferior_process, 66      unify, 1473
flag:encoding, 66                    unify_with_occurs_check/2, 211
flag:executable, 66                  unify_with_occurs_check/2, 66, 210
flag:file_name_variables, 66         union/3, 1316
flag:gc, 66                          Unix, 7
flag:generate_debug_info, 66         unix, 66
flag:gmp_version, 66                 unix/1, 21, 590
flag:gui, 66                         unknown/2, 664, 1158
flag:history, 66                     unlisten/1, 1196
flag:home, 66                        unlisten/2, 1197
flag:hwnd, 66                        unlisten/3, 1198
flag:integer_rounding_function, 66   unload_file/1, 144
flag:iso, 66                         unload_foreign_library/1, 881
flag:large_files, 66                 unload_foreign_library/2, 882
flag:last_call_optimisation, 66      unload_file/1, 131
flag:max_arity, 66                   unsetenv/1, 587, 588
flag:max_integer, 66                 upcase_atom/2, 445
flag:max_tagged_integer, 66          upcase_atom/2, 441
flag:min_integer, 66                 update view, 281, 1473
flag:min_tagged_integer, 66          URL, 582
flag:occurs_check, 66                url _l_i_b_r_a_r_y, 1326, 1506
flag:open_shared_object, 66          url_iri/2, 1437, 1438
flag:optimise, 66                    use_foreign_library/1, 879
flag:pid, 66                         use_foreign_library/2, 880
flag:pipe, 66                        use_module/1, 710
flag:prompt_alternatives_on, 66      use_module/2, 711
flag:qcompile, 66                    use_foreign_library/1, 148
flag:readline, 66                    use_module/1,  69,  100,  131,  709,
flag:report_error, 66                      711, 726, 727, 1468
flag:resource_database, 66           use_module/2,  70,  131,  709,  711,
flag:runtime, 66                           719, 1468
flag:saved_program, 66               use_module/[1
flag:shared_object_extension, 66        2],  59,  113,  130,  131,  133,
flag:shared_object_search_path, 66         728, 729, 1473
flag:signals, 66                     use_modules/1, 718
flag:system_thread_id, 66            user _l_i_b_r_a_r_y, 1486
flag:timezone, 66                    user profile file, 41
flag:toplevel_print_anon, 66         UTF-8, 83
flag:toplevel_print_factorized, 66   utf-8, 129
flag:toplevel_print_options, 66
flag:toplevel_var_size, 66           valgrind, 1141
flag:trace_gc, 66                    var/1, 12, 183, 742, 918
flag:tty_control, 66                 variable, 1473
flag:unix, 66                           anonymous, 1473
flag:unknown, 66                     variable_value/3, 1400
flag:user_flags, 66                  variant, 212
flag:verbose, 66                     variant_sha1/2, 285
flag:verbose_autoload, 66            variant_sha1/2, 1484
flag:verbose_file_search, 66         verbose, 43
flag:verbose_load, 66                vertices/2, 1412
flag:version, 66                     vertices_edges_to_ugraph/3, 1411
flag:version_data, 66                view
flag:version_git, 66                    update, 1473
flag:windows, 66                     visible/1, 663, 1449
flag:write_attributes, 66            void(), 1083
flag:write_help_with_overstrike, 66  volatile/1, 302, 829, 1148
flag:xpce, 66
flag:xpce_version, 66                wait_for_input/3, 341
flatten/2, 1308                      wait_for_input/3, 322, 341
float/1, 186, 499                    when _l_i_b_r_a_r_y, 761
float_fractional_part/1, 502         when/2, 82, 761
float_integer_part/1, 503            wildcard_match/2, 703
floor/1, 505                         win_exec/2, 581
flush_output/0, 359                  win_folder/2, 585
flush_output/1, 360                  win_has_menu/0, 606
flush_output/0, 359                  win_insert_menu/2, 607
flush_output/1, 249, 386             win_insert_menu_item/4, 608
flush_output/[0                      win_registry_get_value/3, 584
   1], 310, 361                      win_shell/2, 582, 583
forall/2, 556                        win_window_pos/1, 605
foreach/2, 1165                      win_exec/2, 578, 582
format/1, 249, 565                   win_folder/2, 41, 43
format/2, 566, 567, 1282             win_insert_menu/2, 606, 608
format/3, 249, 252,  339, 387, 431,  win_insert_menu_item/4, 606
      447, 476, 477, 566, 567        win_shell/2, 578, 1327
format/[1                            Window interface, 8
   2], 387, 557, 1486                window_title/2, 604
format/[2                            Windows, 7
   3], 78                            windows, 66
format_predicate/2, 569              with_mutex/2, 834
format_time/3, 598                   with_output_to/2, 339
format_time/4, 599                   with_output_to_chars/2, 1212
format_to_chars/3, 1201, 1202        with_output_to_chars/3, 1213
format_time/3, 589                   with_output_to_chars/4, 1214
format_time/4, 598                   with_mutex/2, 835, 855
free_variables/4, 1166               with_output_to/2,   309,  335,   339,
freeze/2, 758, 759, 761                    387, 429, 431, 447, 567, 598
frozen/2, 760                        working_directory/2, 632
functor, 1473                        working_directory/2, 590, 621, 633
functor/3, 6,  194, 195,  301, 409,  write(), 1044
      772                            write/1, 66,  82,  392,  396,  437,

garbage_collect/0, 683               write/561,2566,,938,3978,910443
garbage_collect_atoms/0, 684         write_canonical/1, 390
garbage_collect_clauses/0, 165       write_canonical/2, 391
garbage_collect_atoms/0, 684, 1119   write_term/2, 388
garbage_collect_clauses/0, 164--166  write_term/3, 389
gcd/2, 490                           write_to_chars/2, 1203
gdebug/0, 119                        write_to_chars/3, 1204
gen_assoc/3, 1181                    write_canonical/1, 390, 566
gen_nb_set/2, 1323                   write_canonical/2, 413, 938
gen_state/1, 1394                    write_canonical/[1
gensym _l_i_b_r_a_r_y, 1288                    2], 17
gensym/2, 1289                       write_term/2,  57,  66,  211,  388--
get/1, 370                                 390,  413,  431,   451,  561,
get/2, 371                                 566, 748
get0/1, 310, 368, 369                write_term/3, 66, 69, 388, 412
get0/2, 369                          write_term/[2
get_assoc/3, 1182                       3], 17
get_assoc/5, 1183                    writef/1, 560
get_attr/3, 744                      writef/2, 34, 78, 387, 561, 562
get_attrs/2, 755                     writef/[1
get_byte/1, 362                         2], 557
get_byte/2, 363                      writeln/1, 559
get_char/1, 366                      writeq/1, 394, 561, 566
get_char/2, 367                      writeq/2, 395
get_code/1, 364                      www_browser _l_i_b_r_a_r_y, 1326, 1507
get_code/2, 365                      www_form_encode/2, 1434, 1435
get_single_char/1, 380               www_open_url/1, 1327
get_time/1, 594                      www_open_url/1, 1327
get_attr/3, 754
get_attrs/2, 756                     X-Windows, 7
get_byte/1, 368                      X11, 8
get_byte/2, 367                      xor/2, 512
get_byte/[1                          XPCE, 8
   2], 129                           xref_built_in/1, 1368
get_char/1, 364                      xref_called/3, 1365
get_char/2, 367                      xref_clean/1, 1363
get_char/[1                          xref_current_source/1, 1362
   2], 129                           xref_defined/3, 1364
get_code/1, 129, 368, 378, 380       xref_exported/2, 1366
get_code/2, 84,  321, 367, 369, 384, xref_module/2, 1367
      386                            xref_source/1, 1361
get_code/[1
   2], 129                           YAP
get_single_char/1, 43, 66               prolog, 1468
get_time/1, 619, 667
getenv/2, 586, 587, 1327             zcompare/3, 1252
global_cardinality/2, 1246
global_cardinality/3, 1247
global_url/3, 1429
GMP, 476
GNU-Emacs, 48
goal, 1473
goal_expansion/2, 154, 1486
goal_expansion/2,   130,  151,  152,
      154--156,  159,  1281,  1469,
      1472
Graphics, 8
ground/1, 82, 196, 283, 922
group_pairs_by_key/2, 1352
gspy/1, 120
gtrace/0, 118, 844
GUI, 8
guitracer/0,  23,   115--117,  126,
      647, 651
gxref/0, 53, 123, 711, 1360

halt/0, 57, 637, 638
halt/1, 638, 1106, 1486
halt/[0
   1], 147
hash/1, 292, 293
hashing, 1473
head, 1473
help/0, 50, 69, 1151, 1459
help/1, 49--51, 66, 69, 1459
helpidx _l_i_b_r_a_r_y, 49
hooks, 69
html_write _l_i_b_r_a_r_y, 1370
http/http_error _l_i_b_r_a_r_y, 245
http/http_header _l_i_b_r_a_r_y, 598
http_load _l_i_b_r_a_r_y, 131, 1461
http_location/2, 1431
http_open/3, 252
http_timestamp/2, 598
IA32, 93
IDE, 95
if
   directive, 159
if/1, 145, 160
ignore/1, 236, 678, 803
immediate
   update view, 281
import/1, 729, 730
import_module/2, 723
import_module/2, 300, 724
imported predicate, 1473
in/2, 1221
in_pce_thread/1, 868
in_pce_thread/1, 867, 868
include/1, 130, 131, 134, 145
include/3, 1168
index/1, 282, 292, 293, 302
indexing, 1473
indomain/1, 1223
inf/2, 1263
infinite trees, 82
initialization/1,  148,  149,  764,
      808, 875, 1149
initialization/2, 149
ins/2, 1222
instance/2, 279
instantiation_error/1, 1033
integer, 1473
   unbounded, 476
integer/1, 185, 498
interactor/0, 322, 843
internationalization, 83
interpreted, 1473
intersection/3, 1315
is/2, 475, 476, 499, 538, 796
is_absolute_file_name/1, 622
is_absolute_url/1, 1430
is_list/1, 543
is_set/1, 1313
is_stream/1, 317
ISO Latin 1, 77

Java, 1039
join_threads/0, 842
join_threads/0, 842

keysort/2, 548, 549

label/1, 1224
labeling/2, 1225
last/2, 1305
leash/1, 57, 662, 663, 791, 1449
length/2, 545
lex_chain/1, 1241
library_directory/1, 138
library_directory/1, 70, 73, 132
license/1, 1481
license/2, 1480, 1481
line_count/2, 344
line_position/2, 345
line_count/2, 320, 322, 573
line_position/2, 320, 322, 573
list_autoload/0, 1218
list_debug_topics/0, 1286
list_redefined/0, 1219
list_to_assoc/2, 1184
list_to_ord_set/2, 1337
list_to_set/2, 1314
list_undefined/0, 1217
list_autoload/0, 1216, 1217
list_debug_topics/0, 1281
list_redefined/0, 1216
list_undefined/0, 137, 1216, 1218
listen/2, 1194, 1195
listen/3, 1195--1198
listening/3, 1199
listing/0, 179
listing/1, 57, 178, 179
lists _l_i_b_r_a_r_y, 542, 1495
load_files/2, 131, 1486
load_foreign_library/1, 877
load_foreign_library/2, 878
load_file/2, 131
load_files/2, 66,  69, 84, 131, 132,
      169,  711, 1360,  1460, 1461,
      1470
load_foreign_library/1,  148,  1131,
      1150
load_foreign_library/[1
   2], 139, 886
locale, 448
locale_sort/2, 450
locale_sort/2, 449, 589
log/1, 523
log10/1, 524
logical
   update view, 281
lsb/1, 535

MacOS X, 7
make/0, 7,  70, 73, 106,  113, 126,
      131, 137, 164
make_directory/1, 630
make_library_index/1, 71
make_library_index/2, 72
make_library_index/1, 70
make_library_index/2, 70
make_library_index/[1
   2], 73
manpce/0, 87
map_assoc/2, 1185
map_assoc/3, 1186
map_list_to_pairs/3, 1354
maplist/2, 1172
maplist/3, 712, 731, 1147, 1173
maplist/4, 1174
maplist/5, 1175
maplist_/3, 712, 731
max/2, 493, 494
max_assoc/3, 1187
max_list/2, 1310
maximize/1, 1266
maximize/3, 1395, 1396
member/2, 57,  238, 306,  544, 621,
      711, 1293, 1486
memberchk/2, 544, 1347
memory
   layout, 88
merge_options/3, 1333
message
   service, 1191
message_hook/3, 250
message_queue_create/1, 820
message_queue_create/2, 821
message_queue_destroy/1, 822
message_queue_property/2, 825
message_to_string/2, 251
message_hook/3,  20, 247--249,  252,
      686
message_queue_create/1, 816, 822
message_to_string/2, 248, 250
meta-predicate, 1473
meta_options/3, 1334
meta_predicate/1, 713
meta_options/3, 711
meta_predicate/1,   31,  154,   302,
      712, 713, 738, 1063
min/2, 494
min_assoc/3, 1188
min_list/2, 1311
minimize/1, 1265
minimize/3, 1396
mod/2, 485, 488
module, 1473
   contex, 1473
module transparent, 1473
module/1, 715, 716
module/2, 152, 457,  458, 707, 708,
      711, 720, 728, 738
module_property/2, 737
module_transparent/1, 732
module_property/2, 144
module_transparent/1,    302,   713,
      738, 1063, 1473
msb/1, 533, 534
msort/2, 547, 548
multifile/1,  66,  170,  286,  289,
      302, 1217, 1457, 1473
must_be/2, 1378
mutex_create/1, 831
mutex_create/2, 832
mutex_destroy/1, 833
mutex_lock/1, 835
mutex_property/2, 839
mutex_statistics/0, 814
mutex_trylock/1, 836
mutex_unlock/1, 837
mutex_unlock_all/0, 838
mutex_create/1, 834, 835
mutex_create/2, 839
mutex_lock/1, 836
my_compare/3, 1472
mypred/1, 717
name/1, 712
name/2, 423, 430
name_of/2, 1195
nb_current/2, 770
nb_delete/1, 771
nb_getval/2, 768
nb_linkarg/3, 420
nb_linkval/2, 769
nb_set _l_i_b_r_a_r_y, 1319
nb_set_to_list/2, 1325
nb_setarg/3, 419
nb_setval/2, 767
nb_getval/2, 768
nb_linkarg/3, 419, 421
nb_linkval/2, 420, 421, 772
nb_setarg/3,  128,  418,  420,  421,
      1319, 1378
nb_setval/2,  419,  421,  764,  769,
      772, 1455
neck, 1473
neighbors/3, 1420
neighbours/3, 1419, 1420
nextto/3, 1301
nl/0, 347
nl/1, 348
nl/[0
   1], 561
nodebug/0, 656, 657
nodebug/1, 1284, 1285
noguitracer/0, 115, 117, 126, 652
nonvar/1, 184
noprofile/1, 678
noprotocol/0, 645
normalize_space/2, 447
nospy/1, 57, 69, 660, 851, 1458
nospyall/0, 69, 661, 1458
not/1, 234, 1486
notrace/0, 650, 789, 790
notrace/1, 655
nth0/3, 1303
nth1/3, 1304
nth_clause/3, 306
nth_clause/3, 307, 1445
number
   rational, 476
number/1, 189
number_chars/2, 427
number_codes/2, 428
number_to_chars/2, 1207
number_to_chars/3, 1208
number_chars/2, 21, 129, 428
number_codes/2,  21, 129,  423, 429,
      430
numbervars/3, 388, 412, 413
numbervars/4, 390, 412, 413
numbervars/[3
   4], 82
numlist/3, 1312

objective/2, 1397
occurs_check, 211
on_signal/3, 254
on_signal/3, 19, 254, 255
once/1,  235, 236,  238, 339,  636,
      655, 669, 834, 1068
online_help _l_i_b_r_a_r_y, 1486
op/3, 286, 388, 458, 459, 720
open/3, 66, 308, 309, 311
open/4, 13, 84,  85, 129, 310, 311,
      315,  321,  322,  382,  1376,
      1377
open_chars_stream/2, 1211
open_dde_conversation/3, 690
open_null_stream/1, 312
open_resource/3, 1154
open_shared_object/2, 886
open_shared_object/3, 887
open_null_stream/1, 321
open_resource/3,   18,  1144,  1151,
      1154
open_shared_object/2, 66, 874, 887
operand, 1473
operator, 1473
   and modules, 457
option _l_i_b_r_a_r_y, 1378, 1496
option/2, 1330
option/3, 1329
ord_add_element/3, 1338
ord_del_element/3, 1339
ord_disjoint/2, 1342
ord_empty/1, 1336
ord_intersect/2, 1340
ord_intersection/3, 1341
ord_list_to_assoc/2, 1189
ord_memberchk/2, 1347
ord_subset/2, 1346
ord_subtract/3, 1343
ord_union/3, 1344
ord_union/4, 1345
ord_intersect/2, 1342
ordsets _l_i_b_r_a_r_y, 1335, 1497
oset _l_i_b_r_a_r_y, 1335

pairs _l_i_b_r_a_r_y, 1499
pairs_keys/2, 1351
pairs_keys_values/3, 1349
pairs_values/2, 1350
parse_time/2, 600
parse_time/3, 601
parse_url/2, 1432
parse_url/3, 1433
parse_url_search/2, 1439
parse_time/3, 600
partition/4, 1170
partition/5, 1171
pce_call/1, 870
pce_dispatch/1, 869
pce_xref _l_i_b_r_a_r_y, 122
pce_call/1, 868, 870
pce_dispatch/1, 868
peek_byte/1, 372
peek_byte/2, 373
peek_char/1, 376
peek_char/2, 377
peek_code/1, 374
peek_code/2, 375
peek_byte/[1
   2], 129
peek_char/[1
   2], 129
peek_code/[1
   2], 129
permission_error/3, 1038
permutation/2, 1307
phrase/2, 257, 258
phrase/3, 257, 259
phrase_from_file/2, 1357
phrase_from_file/3, 1358
pi/0, 529
pio _l_i_b_r_a_r_y, 1355, 1500
PL_abort_hook(), 1116
PL_abort_unhook(), 1117
PL_action(), 1106
PL_agc_hook(), 1119
PL_atom_chars(), 911
PL_atom_nchars(), 965
PL_atom_wchars(), 968
PL_blob_data(), 1051
PL_BLOB_NOCOPY, 1040
PL_BLOB_TEXT, 1040
PL_BLOB_UNIQUE, 1040
PL_call(), 1068
PL_call_predicate(), 1067
PL_chars_to_term(), 1015
PL_cleanup(), 1127
PL_cleanup_fork(), 1128
PL_close_foreign_frame(), 1071
PL_close_query(), 1066
PL_compare(), 1091
PL_cons_functor(), 994
PL_cons_functor_v(), 995
PL_cons_list(), 996
PL_context(), 1075
PL_copy_term_ref(), 895
PL_create_engine(), 863
PL_cut_query(), 1065
PL_CYCLIC_TERM, 977
PL_destroy_engine(), 864
PL_discard_foreign_frame(), 1072
PL_dispatch_hook(), 1115
PL_domain_error(), 1036
PL_erase(), 1096
PL_erase_external(), 1099
PL_exception(), 1082
PL_existence_error(), 1037
PL_fail(), 902
PL_foreign_context(), 907
PL_foreign_context_address(), 908
PL_foreign_control(), 906
PL_free(), 1139
PL_functor_arity(), 914
PL_functor_name(), 913
PL_get_arg(), 950
PL_get_atom(), 935
PL_get_atom_chars(), 936
PL_get_atom_ex(), 1018
PL_get_atom_nchars(), 953
PL_get_blob(), 1050
PL_get_bool(), 944
PL_get_bool_ex(), 1024
PL_get_char_ex(), 1026
PL_get_chars(), 938
PL_get_file_name(), 1101
PL_get_file_nameW(), 1102
PL_get_float(), 946
PL_get_float_ex(), 1025
PL_get_functor(), 947
PL_get_head(), 974
PL_get_int64(), 942
PL_get_int64_ex(), 1021
PL_get_integer(), 940
PL_get_integer_ex(), 1019
PL_get_intptr(), 943
PL_get_intptr_ex(), 1022
PL_get_list(), 973
PL_get_list_chars(), 939
PL_get_list_ex(), 1028
PL_get_list_nchars(), 954
PL_get_long(), 941
PL_get_long_ex(), 1020
PL_get_module(), 949
PL_get_mpq(), 1054
PL_get_mpz(), 1053
PL_get_name_arity(), 948
PL_get_nchars(), 955
PL_get_nil(), 976
PL_get_nil_ex(), 1029
PL_get_pointer(), 945
PL_get_pointer_ex(), 1027
PL_get_signum_ex(), 1088
PL_get_size_ex(), 1023
PL_get_string_chars(), 937
PL_get_tail(), 975
PL_get_wchars(), 969
PL_halt(), 1129
PL_handle_signals(), 1087
PL_initialise(), 1123
PL_install_readline(), 1125
PL_instantiation_error(), 1033
PL_is_acyclic(), 933
PL_is_atom(), 923
PL_is_atomic(), 931
PL_is_blob(), 1047
PL_is_compound(), 927
PL_is_float(), 926
PL_is_functor(), 928
PL_is_ground(), 922
PL_is_initialised(), 1124
PL_is_integer(), 925
PL_is_list(), 929
PL_is_number(), 932
PL_is_pair(), 930
PL_is_string(), 924
PL_is_variable(), 921
PL_license(), 1482
PL_LIST, 977
PL_malloc(), 1137
PL_module_name(), 1077
PL_new_atom(), 910
PL_new_atom_nchars(), 964
PL_new_atom_wchars(), 967
PL_new_functor(), 912
PL_new_module(), 1078
PL_new_term_ref(), 893
PL_new_term_refs(), 894
PL_next_solution(), 1064
PL_NOT_A_LIST, 977
PL_on_halt(), 1118
PL_open_foreign_frame(), 1070
PL_open_query(), 1063
PL_PARTIAL_LIST, 977
PL_permission_error(), 1038
PL_pred(), 1059
PL_predicate(), 1060
PL_predicate_info(), 1061
PL_put_atom(), 981
PL_put_atom_chars(), 982
PL_put_atom_nchars(), 956
PL_put_blob(), 1049
PL_put_float(), 989
PL_put_functor(), 990
PL_put_int64(), 987
PL_put_integer(), 986
PL_put_list(), 991
PL_put_list_chars(), 985
PL_put_list_nchars(), 959
PL_put_list_ncodes(), 958
PL_put_nil(), 992
PL_put_pointer(), 988
PL_put_string_chars(), 983
PL_put_string_nchars(), 957, 984
PL_put_term(), 993
PL_put_variable(), 980
PL_query(), 1108

                                  1515