
                                              University of Amsterdam

                                                Kruislaan 419, 1098
                                                   VA  Amsterdam

                                              VU University Amsterdam
                                                De Boelelaan 1081a,

                                                1081 HV  Amsterdam
                                                  The Netherlands

                        SSWWII--PPrroolloogg 55..1100

                        RReeffeerreennccee MMaannuuaall

             _U_p_d_a_t_e_d _f_o_r _v_e_r_s_i_o_n _5_._1_0_._1_, _J_u_l_y _2_0_1_0

                         _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--2010, University of Amsterdam


CChhaapptteerr 11..  IINNTTRROODDUUCCTTIIOONN


11..11 SSWWII--PPrroolloogg

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

11..11..11 BBooookkss aabboouutt PPrroolloogg

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

11..22 SSttaattuuss

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.


11..33 CCoommpplliiaannccee ttoo tthhee IISSOO ssttaannddaarrdd

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.


11..44 SShhoouulldd yyoouu bbee uussiinngg SSWWII--PPrroolloogg??

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

11..55 TThhee XXPPCCEE GGUUII ssyysstteemm ffoorr PPrroolloogg

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.

AAvvaaiillaabbiilliittyy.. 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.

IInnffoo.. further    information   is    available   from    http://www.swi-
prolog.org/packages/xpce/ or by E-mail to info@www.swi-prolog.org.


11..66 RReelleeaassee NNootteess

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.


VVeerrssiioonn 11..88 RReelleeaassee NNootteess

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.


VVeerrssiioonn 11..99 RReelleeaassee NNootteess

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.


VVeerrssiioonn 22..00 RReelleeaassee NNootteess

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.


VVeerrssiioonn 22..55 RReelleeaassee NNootteess

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.


VVeerrssiioonn 22..66 RReelleeaassee NNootteess

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.


VVeerrssiioonn 22..77 RReelleeaassee NNootteess

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.


VVeerrssiioonn 22..88 RReelleeaassee NNootteess

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.


VVeerrssiioonn 22..99 RReelleeaassee NNootteess

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.


VVeerrssiioonn 33..00 RReelleeaassee NNootteess

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

VVeerrssiioonn 33..11 RReelleeaassee NNootteess

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.


VVeerrssiioonn 33..33 RReelleeaassee NNootteess

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.


IInnccoommppaattiibbllee cchhaannggeess

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 mmuusstt 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 llooccaall ttoo mmoodduulleess.  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.


VVeerrssiioonn 33..44 RReelleeaassee NNootteess

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.


VVeerrssiioonn 44..00 RReelleeaassee NNootteess

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.


VVeerrssiioonn 55..00 RReelleeaassee NNootteess

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


VVeerrssiioonn 55..11 RReelleeaassee NNootteess

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.


VVeerrssiioonn 55..22 RReelleeaassee NNootteess

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

VVeerrssiioonn 55..33 RReelleeaassee NNootteess

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.


VVeerrssiioonn 55..44 RReelleeaassee NNootteess

Version 5.4 consolidates the 5.3.x beta series.


VVeerrssiioonn 55..55 RReelleeaassee NNootteess

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

VVeerrssiioonn 55..66 RReelleeaassee NNootteess

Version 5.6 consolidates the 5.5.x beta series.


VVeerrssiioonn 55..77 RReelleeaassee NNootteess

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.


VVeerrssiioonn 55..1100 RReelleeaassee NNootteess

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.


11..77 DDoonnaattee ttoo tthhee SSWWII--PPrroolloogg pprroojjeecctt

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


11..88 AAcckknnoowwlleeddggeemmeennttss

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.


CChhaapptteerr 22..  OOVVEERRVVIIEEWW


22..11 GGeettttiinngg ssttaarrtteedd qquuiicckkllyy


22..11..11 SSttaarrttiinngg SSWWII--PPrroolloogg


22..11..11..11 SSttaarrttiinngg SSWWII--PPrroolloogg oonn UUnniixx

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.


22..11..11..22 SSttaarrttiinngg SSWWII--PPrroolloogg oonn WWiinnddoowwss

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.


22..11..22 EExxeeccuuttiinngg aa qquueerryy

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 YYeess.   If Prolog answers
NNoo,  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                                                                      |
|?-|____________________________________________________________________ |  |


22..22 TThhee uusseerr''ss iinniittiiaalliissaattiioonn ffiillee

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

                   ___________________________________
                   |______________|UUnniixx__||WWiinnddoowwss__________________________||
                   || llooccaall ||.    |.                   |
                   |_hhoommee__||~____|<_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.


22..33 IInniittiiaalliissaattiioonn ffiilleess aanndd ggooaallss

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.


22..44 CCoommmmaanndd--lliinnee ooppttiioonnss

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

22..44..11 CCoonnttrroolllliinngg tthhee ssttaacckk--ssiizzeess

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.


22..44..22 RRuunnnniinngg ggooaallss ffrroomm tthhee ccoommmmaannddlliinnee

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

22..44..33 CCoommppiilleerr ooppttiioonnss

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

22..44..44 MMaaiinntteennaannccee ooppttiioonnss

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.


22..55 GGNNUU EEmmaaccss IInntteerrffaaccee

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


22..66 OOnnlliinnee HHeellpp

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

hheellpp
    Equivalent to help(help/1).


hheellpp((_+_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.


aapprrooppooss((_+_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.


eexxppllaaiinn((_+_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.


eexxppllaaiinn((_+_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.


22..77 CCoommmmaanndd--lliinnee hhiissttoorryy

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


22..88 RReeuussee ooff ttoopp--lleevveell bbiinnddiinnggss

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|?-___________________________________________________________________ | |


22..99 OOvveerrvviieeww ooff tthhee DDeebbuuggggeerr

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 wwiitthhoouutt waiting  for a
return, unless the command-line option -tty is active.  Tracer options:

+ ((SSppyy))
    Set a spy point (see spy/1) on the current predicate.

- ((NNoo ssppyy))
    Remove the spy point (see nospy/1) from the current predicate.

/ ((FFiinndd))
    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.

. ((RReeppeeaatt ffiinndd))
    Repeat the last find command (see `/').

A ((AAlltteerrnnaattiivveess))
    Show all goals that have alternatives.

C ((CCoonntteexxtt))
    Toggle  `Show Context'.   If on, the context  module of the goal  is
    displayed between square brackets (see section 5).  Default is off.

L ((LLiissttiinngg))
    List the current predicate with listing/1.

a ((AAbboorrtt))
    Abort Prolog execution (see abort/0).

b ((BBrreeaakk))
    Enter a Prolog break environment (see break/0).

c ((CCrreeeepp))
    Continue execution, stop at next port.  (Also return, space).

d ((DDiissppllaayy))
    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 ((EExxiitt))
    Terminate Prolog (see halt/0).

f ((FFaaiill))
    Force failure of the current goal.

g ((GGooaallss))
    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 ((HHeellpp))
    Show available options (also `?').

i ((IIggnnoorree))
    Ignore the current goal, pretending it succeeded.

l ((LLeeaapp))
    Continue execution, stop at next spy point.

n ((NNoo ddeebbuugg))
    Continue execution in `no debug' mode.

p ((PPrriinntt))
    Set  the Prolog  flag debugger_print_options to  [quoted(true), por-
    tray(true), max_depth(10), priority(699)].  This is the default.

r ((RReettrryy))
    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 ((SSkkiipp))
    Continue  execution,  stop  at the  next  port  of tthhiiss  goal  (thus
    skipping all calls to children of this goal).

u ((UUpp))
    Continue  execution, stop at the next port of tthhee ppaarreenntt  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 ((WWrriittee))
    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.


22..1100 CCoommppiillaattiioonn


22..1100..11 DDuurriinngg pprrooggrraamm ddeevveellooppmmeenntt

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.


22..1100..22 FFoorr rruunnnniinngg tthhee rreessuulltt

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

22..1100..22..11 UUssiinngg PPrroollooggSSccrriipptt

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                            |
|%|_____________________________________________________________________ | |

TThhee  WWiinnddoowwss  vveerrssiioonn 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.


22..1100..22..22 CCrreeaattiinngg aa sshheellll--ssccrriipptt

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.


22..1100..22..33 CCrreeaattiinngg aa ssaavveedd--ssttaattee

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.


22..1100..22..44 CCoommppiillaattiioonn uussiinngg tthhee --cc ccoommmmaanndd--lliinnee ooppttiioonn

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

22..1111 EEnnvviirroonnmmeenntt CCoonnttrrooll ((PPrroolloogg ffllaaggss))

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.


ccuurrrreenntt__pprroolloogg__ffllaagg((_?_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 aanndd  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>                                     |
    ||________)_________________________________________________________ ||

    aaddddrreessss__bbiittss _(_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.

    aaggcc__mmaarrggiinn _(_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().

    aallllooww__vvaarriiaabbllee__nnaammee__aass__ffuunnccttoorr _(_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.

    aarrggvv _(_l_i_s_t_)
         List  is a  list of  atoms  representing the  command-line  ar-
         guments  used to  invoke  SWI-Prolog.    Please note  that  aallll
         arguments are included in the list returned.

    aarrcchh _(_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.

    aassssoocciiaattee _(_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.

    aauuttoollooaadd _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         If true (default) autoloading of library functions is enabled.

    bbaacckkqquuootteedd__ssttrriinngg _(_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.

    bboouunnddeedd _(_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.

    cc__cccc _(_a_t_o_m_)
         Name of the  C-compiler used to  compile SWI-Prolog.   Normally
         either gcc or cc.  See section 9.5.

    cc__llddffllaaggss _(_a_t_o_m_)
         Special linker  flags  passed to  link SWI-Prolog.    See  sec-
         tion 9.5.

    cc__lliibbss _(_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.

    cchhaarr__ccoonnvveerrssiioonn _(_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.

    cchhaarraacctteerr__eessccaappeess _(_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.

    ccoommppiilleedd__aatt _(_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.

    ccoonnssoollee__mmeennuu _(_b_o_o_l_)
         Set to true in  swipl-win.exe to indicate the console  supports
         menus.  See also section 4.33.2.

    ccppuu__ccoouunntt _(_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/

    ddddee _(_b_o_o_l_)
         Set  to  true  if this  instance  of  Prolog  supports  DDE  as
         described in section 4.41.

    ddeebbuugg _(_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.

    ddeebbuugg__oonn__eerrrroorr _(_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.

    ddeebbuuggggeerr__pprriinntt__ooppttiioonnss _(_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)].

    ddeebbuuggggeerr__sshhooww__ccoonntteexxtt _(_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.

    ddiiaalleecctt _(_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).____ ||

    ddoouubbllee__qquuootteess _(_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.

    eeddiittoorr _(_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.

    eemmaaccss__iinnffeerriioorr__pprroocceessss _(_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.

    eennccooddiinngg _(_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.

    eexxeeccuuttaabbllee _(_a_t_o_m_)
         Path-name of the  running executable.  Used  by qsave_program/2
         as default emulator.

    ffiillee__nnaammee__vvaarriiaabblleess _(_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.

    ffllooaatt__ffoorrmmaatt _(_a_t_o_m_, _c_h_a_n_g_e_a_b_l_e_)
         C-library printf()  format  specification used  by write/1  and
         friends to  determine how floating  point numbers are  printed.
         The default is %g.   The specified value is passed  to printf()
         without  further checking.    For  example,  if you  want  more
         digits printed,  %.12g will  print all floats  using 12  digits
         instead of the default 6.

         When using  quoted-write, the output  is guaranteed to  contain
         a decimal  dot or exponent,  so read/1  reads a floating  point
         number.  See also format/[1,2], write_term/[2,3].

    ggcc _(_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.

    ggeenneerraattee__ddeebbuugg__iinnffoo _(_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.

    ggmmpp__vveerrssiioonn _(_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.7.

    gguuii _(_b_o_o_l_)
         Set to true if XPCE is around and can be used for graphics.

    hhiissttoorryy _(_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.

    hhoommee _(_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.

    hhwwnndd _(_i_n_t_e_g_e_r_)
         In swipl-win.exe, this  refers to the MS-Windows  window-handle
         of the console window.

    iinntteeggeerr__rroouunnddiinngg__ffuunnccttiioonn _(_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.

    iissoo _(_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.

    llaarrggee__ffiilleess _(_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.

    mmaaxx__aarriittyy _(_u_n_b_o_u_n_d_e_d_)
         ISO  Prolog  flag describing  there  is  no  maximum  arity  to
         compound terms.

    mmaaxx__iinntteeggeerr _(_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.

    mmaaxx__ttaaggggeedd__iinntteeggeerr _(_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.

    mmiinn__iinntteeggeerr _(_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.

    mmiinn__ttaaggggeedd__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Start of the tagged-integer value range.

    ooccccuurrss__cchheecckk _(_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.

    ooppeenn__sshhaarreedd__oobbjjeecctt _(_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).

    ooppttiimmiissee _(_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).

    ppiidd _(_i_n_t_)
         Process identifier of  the running Prolog  process.   Existence
         of this flag is implementation defined.

    ppiippee _(_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.

    pprroommpptt__aalltteerrnnaattiivveess__oonn _(_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.

    qqccoommppiillee _(_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.

    rreeaaddlliinnee _(_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.

    rreessoouurrccee__ddaattaabbaassee _(_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.

    rreeppoorrtt__eerrrroorr _(_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.

    rruunnttiimmee _(_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).

    ssaavveedd__pprrooggrraamm _(_b_o_o_l_)
         If present  and  true, Prolog  has been  started  from a  state
         saved with qsave_program/[1,2].

    sshhaarreedd__oobbjjeecctt__eexxtteennssiioonn _(_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.

    sshhaarreedd__oobbjjeecctt__sseeaarrcchh__ppaatthh _(_a_t_o_m_)
         Name of the environment  variable used by the system  to search
         for shared objects.

    ssiiggnnaallss _(_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.20.1 for details.

    ssyysstteemm__tthhrreeaadd__iidd _(_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.

    llaasstt__ccaallll__ooppttiimmiissaattiioonn _(_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.

    ttiimmeezzoonnee _(_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.

    ttoopplleevveell__pprriinntt__aannoonn _(_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.

    ttoopplleevveell__pprriinntt__ooppttiioonnss _(_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)].

    ttoopplleevveell__vvaarr__ssiizzee _(_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.

    ttrraaccee__ggcc _(_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|_

    ttttyy__ccoonnttrrooll _(_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.

    uunniixx _(_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.

    uunnkknnoowwnn _(_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.

    uusseerr__ffllaaggss _(_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.

    vveerrbboossee _(_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.

    vveerrbboossee__aauuttoollooaadd _(_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.

    vveerrbboossee__llooaadd _(_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.

    vveerrbboossee__ffiillee__sseeaarrcchh _(_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.

    vveerrssiioonn _(_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.

    vveerrssiioonn__ddaattaa _(_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 [].

    vveerrssiioonn__ggiitt _(_a_t_o_m_)
         Available if created from  a git repository.   See git-describe
         for details.

    wwiinnddoowwss _(_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.

    wwrriittee__aattttrriibbuutteess _(_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.

    wwrriittee__hheellpp__wwiitthh__oovveerrssttrriikkee _(_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.

    xxppccee _(_b_o_o_l_)
         Available  and set  to  true if  the  XPCE graphics  system  is
         loaded.

    xxppccee__vveerrssiioonn _(_a_t_o_m_)
         Available and set to the version of the loaded XPCE system.


sseett__pprroolloogg__ffllaagg((_:_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.


ccrreeaattee__pprroolloogg__ffllaagg((_+_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:

    aacccceessss((_+_A_c_c_e_s_s))
         Define access-rights for the  flag.  Values  are read_write  and
         read_only.  The default is read_write.

    ttyyppee((_+_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.


22..1122 AAnn oovveerrvviieeww ooff hhooookk pprreeddiiccaatteess

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.


22..1133 AAuuttoommaattiicc llooaaddiinngg ooff lliibbrraarriieess

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.


mmaakkee__lliibbrraarryy__iinnddeexx((_+_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.


mmaakkee__lliibbrraarryy__iinnddeexx((_+_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'                          |
    ||______________________])._________________________________________ ||


rreellooaadd__lliibbrraarryy__iinnddeexx
    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.


22..1144 GGaarrbbaaggee CCoolllleeccttiioonn

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

22..1155 SSyynnttaaxx NNootteess

SWI-Prolog uses 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.


22..1155..11 IISSOO SSyynnttaaxx SSuuppppoorrtt

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

22..1155..11..11 PPrroocceessssoorr CChhaarraacctteerr SSeett

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.


22..1155..11..22 CChhaarraacctteerr EEssccaappee SSyynnttaaxx

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 would look better if it was \c    |

    ||_______split_across_multiple_physical_lines_in_the_input')________ ||

\<RETURN>
    No  output.   Skips input till the  next non-layout character or  to
    the end of the next line.  Same intention as \c but ISO compatible.

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

22..1155..11..33 SSyynnttaaxx ffoorr nnoonn--ddeecciimmaall nnuummbbeerrss

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.


22..1155..11..44 UUnniiccooddee PPrroolloogg ssoouurrccee

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
4.1.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  in  the Unicode  tables  are
    handled as layout characters.

  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.  All other
    characters  not covered  by the  rules above  are considered  `solo'
    characters:   they form  single-character atoms.   We would like  to
    have a more  appropriate distinction between what is known to Prolog
    as `solo' characters and `symbol' characters.


22..1155..11..55 SSiinngglleettoonn vvaarriiaabbllee cchheecckkiinngg

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).__|__________________________________________________________|_


22..1166 IInnffiinniittee ttrreeeess ((ccyycclliicc tteerrmmss))

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

22..1177 WWiiddee cchhaarraacctteerr ssuuppppoorrtt

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.


22..1177..11 WWiiddee cchhaarraacctteerr eennccooddiinnggss oonn ssttrreeaammss

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:

oocctteett
    Default  encoding for binary streams.  This causes the stream  to be
    read and written fully untranslated.

aasscciiii
    7-bit  encoding  in 8-bit  bytes.   Equivalent  to  iso_latin_1,  but
    generates errors and warnings on encountering values above 127.

iissoo__llaattiinn__11
    8-bit  encoding supporting many western languages.  This  causes the
    stream to be read and written fully untranslated.

tteexxtt
    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.

uuttff88
    Multi-byte encoding of full UCS, compatible with ascii.  See above.

uunniiccooddee__bbee
    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.

uunniiccooddee__llee
    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.


22..1177..11..11 BBOOMM:: BByyttee OOrrddeerr MMaarrkk

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.   BBOOMM 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.


22..1188 SSyysstteemm lliimmiittss


22..1188..11 LLiimmiittss oonn mmeemmoorryy aarreeaass

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||16Mlloocc||aallTssttaacckkhe|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   |gglloobbaall ssttaacckk   ||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   |ttrraaiill ssttaacckk    ||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   |||aarrgguummeenntt ssttaacc||norkkneeded||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


22..1188..11..11 TThhee hheeaapp

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

22..1188..22 OOtthheerr LLiimmiittss

CCllaauusseess  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.

AAttoommss aanndd SSttrriinnggss  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.

MMeemmoorryy aarreeaass  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.

NNeessttiinngg ooff tteerrmmss  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.

IInntteeggeerrss  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.

FFllooaattiinngg ppooiinntt nnuummbbeerrss  Floating  point  numbers   are  represented   as
    C-native double precision floats, 64 bit IEEE on most machines.


22..1188..33 RReesseerrvveedd NNaammeess

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

22..1199 SSWWII--PPrroolloogg aanndd 6644--bbiitt mmaacchhiinneess

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.


22..1199..11 SSuuppppoorrtteedd ppllaattffoorrmmss

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.


22..1199..22 CCoommppaarriinngg 3322-- aanndd 6644--bbiittss PPrroolloogg

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.


22..1199..33 CChhoooossiinngg bbeettwweeeenn 3322-- aanndd 6644--bbiittss PPrroolloogg

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.


CChhaapptteerr 33..  IINNIITTIIAALLIISSIINNGG AANNDD MMAANNAAGGIINNGG AA PPRROOLLOOGG PPRROOJJEECCTT

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.


33..11 TThhee pprroojjeecctt ssoouurrccee--ffiilleess

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.


33..11..11 FFiillee NNaammeess aanndd LLooccaattiioonnss


33..11..11..11 FFiillee NNaammee EExxtteennssiioonnss

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:

IIff tthheerree iiss nnoo ccoonnfflliicctt  because  you   do   not   use   a   conflicting
    application  or the system does not force a unique  relation between
    extension and application, use .pl.

WWiitthh aa ccoonnfflliicctt  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.


33..11..11..22 PPrroojjeecctt DDiirreeccttoorriieess

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.


33..11..11..33 SSuubb--pprroojjeeccttss uussiinngg sseeaarrcchh--ppaatthhss

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.


33..11..22 PPrroojjeecctt SSppeecciiaall FFiilleess

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.


33..11..33 IInntteerrnnaattiioonnaall ssoouurrccee ffiilleess

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.


33..22 UUssiinngg mmoodduulleess

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

33..33 TThhee tteesstt--eeddiitt--rreellooaadd ccyyccllee

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.


33..33..11 LLooccaattiinngg tthhiinnggss ttoo eeddiitt

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?___________________________________________________________ |    |


33..33..22 EEddiittiinngg aanndd iinnccrreemmeennttaall ccoommppiillaattiioonn

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

33..44 UUssiinngg tthhee PPcceeEEmmaaccss bbuuiilltt--iinn eeddiittoorr


33..44..11 AAccttiivvaattiinngg PPcceeEEmmaaccss

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.


33..44..22 BBlluuffffiinngg tthhrroouugghh PPcceeEEmmaaccss

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

33..44..22..11 EEddiitt mmooddeess

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.


33..44..22..22 FFrreeqquueennttllyy uusseedd eeddiittoorr ccoommmmaannddss

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.


33..44..33 PPrroolloogg MMooddee

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 CCcheck SSyntax 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.

TThhee ccoolloouurr sscchheemmaa

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.   BBoolldd 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

LLaayyoouutt ssuuppppoorrtt 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.


33..44..33..11 FFiinnddiinngg yyoouurr wwaayy aarroouunndd

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.


33..55 TThhee GGrraapphhiiccaall DDeebbuuggggeerr

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.


33..55..11 IInnvvookkiinngg tthhee wwiinnddooww--bbaasseedd ddeebbuuggggeerr

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.


gguuiittrraacceerr
    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).


nnoogguuiittrraacceerr
    Disable  the hooks  installed by  guitracer/0,  reverting to  normal
    text-console based tracing.


ggttrraaccee
    Utility defined as guitracer,trace.


ggddeebbuugg
    Utility defined as guitracer,debug.


ggssppyy((_+_P_r_e_d_i_c_a_t_e))
    Utility defined as guitracer,spy(Predicate).


33..66 TThhee PPrroolloogg NNaavviiggaattoorr

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.


33..77 CCrroossss rreeffeerreenncceerr

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.


ggxxrreeff
    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 lleefftt wwiinnddooww  (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 FFiillee iinnffoo  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 DDeeppeennddeenncciieess  (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.

MMoodduullee  aanndd nnoonn--mmoodduullee  ffiilleess 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.

SSeettttiinnggss The  following settings  can be  controlled  from the  settings
menu:

WWaarrnn aauuttoollooaadd
    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.

WWaarrnn nnoott ccaalllleedd
    If  enabled (default),  the file-overview  shows an  alert icon  for
    files that have predicates that are not called.


33..88 AAcccceessssiinngg tthhee IIDDEE ffrroomm yyoouurr pprrooggrraamm

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:


pprroolloogg__iiddee((_+_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:

    ooppeenn__nnaavviiggaattoorr((_+_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.

    ooppeenn__ddeebbuugg__ssttaattuuss
         Open a window to edit spy- and trace-points.

    ooppeenn__qquueerryy__wwiinnddooww
         Opens  a  little  window to  run  Prolog  queries  from  a  GUI
         component.

    tthhrreeaadd__mmoonniittoorr
         Open a graphical  window indicating existing threads and  their
         status.

    ddeebbuugg__mmoonniittoorr
         Open a graphical front-end for the debug  library that provides
         an overview of the topics and catches messages.

    xxrreeff
         Open  a  graphical  front-end  for  the  cross-referencer  that
         provides an overview of predicates and their callers.


33..99 SSuummmmaarryy ooff tthhee IIDDEE

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.


CChhaapptteerr 44..  BBUUIILLTT--IINN PPRREEDDIICCAATTEESS


44..11 NNoottaattiioonn ooff PPrreeddiiccaattee DDeessccrriippttiioonnss

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.


44..22 CChhaarraacctteerr rreepprreesseennttaattiioonn

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.   Text-files are supposed  to
represent a sequence of character-codes.

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

The  current  version  of  SWI-Prolog  does  not   provide  support  for
multi-byte character encoding.  This implies for example  that it is not
capable of  breaking a  multi-byte encoded  atom into characters.    For
SWI-Prolog, bytes  and codes  are the same  and one-character-atoms  are
simple atoms containing one byte.

To  ease  the  pain  of  these  multiple  representations,  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)._________________________________________________ |                 |

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

44..33 LLooaaddiinngg PPrroolloogg ssoouurrccee ffiilleess

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:

 AA ttrraaddiittiioonnaall   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.

 AA mmoodduullee   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.

 AAnn iinncclluuddee   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.


llooaadd__ffiilleess((_:_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:

    aauuttoollooaadd((_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.

    ddeerriivveedd__ffrroomm((_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.

    eennccooddiinngg((_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.

    eexxppaanndd((_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.

    ffoorrmmaatt((_+_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).

    iiff((_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.

    iimmppoorrttss((_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.

    mmuusstt__bbee__mmoodduullee((_B_o_o_l))
         If true,  raise an  error if  the file  is not  a module  file.
         Used by use_module/[1,2].

    qqccoommppiillee((_A_t_o_m))
         How to  deal  with quick-load-file  compilation by  qcompile/1.
         Values are

         nneevveerr((_D))
             efault.  Do not use qcompile, unless called explicitely

         aauuttoo((_U))
             se qcompile for all writeable files.  See comment below.

         llaarrggee((_U))
             se  qcompile if  the file  is `large'.    Currently,  files
             larger than 100 Kbytes are considered large.

         ppaarrtt((_I))
             f  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.

    rreeddeeffiinnee__mmoodduullee((_+_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.

    rreeeexxppoorrtt((_B_o_o_l))
         If true re-export the  imported predicate.  Used  by reexport/1
         and reexport/2.

    ssiilleenntt((_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.

    ssttrreeaamm((_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.


ccoonnssuulltt((_:_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.


eennssuurree__llooaaddeedd((_:_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)]).


iinncclluuddee((_+_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.


rreeqquuiirree((_+_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 nnoott 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.


eennccooddiinngg((_+_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.


mmaakkee
    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.


lliibbrraarryy__ddiirreeccttoorryy((_?_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.


ffiillee__sseeaarrcchh__ppaatthh((_+_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.


eexxppaanndd__ffiillee__sseeaarrcchh__ppaatthh((_+_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.


pprroolloogg__ffiillee__ttyyppee((_?_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.


ssoouurrccee__ffiillee((_?_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.


ssoouurrccee__ffiillee((_?_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.


uunnllooaadd__ffiillee((_+_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.


pprroolloogg__llooaadd__ccoonntteexxtt((_?_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:

      ________________________________________________________________
      |__KKeeyy______________________||DDeessccrriippttiioonn________________________________________________________________________||
      || 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) ]),                      |
    ||________..._______________________________________________________ ||


ssoouurrccee__llooccaattiioonn((_-_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.


aatt__hhaalltt((_:_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.


::-- iinniittiiaalliizzaattiioonn((_:_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.


iinniittiiaalliizzaattiioonn((_:_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:

    nnooww
         Execute _G_o_a_l immediately.

    aafftteerr__llooaadd
         Execute _G_o_a_l after loading  program-text.  This is the  same as
         initialization/1.

    rreessttoorree
         Do not execute  _G_o_a_l while loading  the program, but _o_n_l_y  when
         restoring a state.


ccoommppiilliinngg
    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.


44..33..11 CCoonnddiittiioonnaall ccoommppiillaattiioonn aanndd pprrooggrraamm ttrraannssffoorrmmaattiioonn

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.


tteerrmm__eexxppaannssiioonn((_+_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.


eexxppaanndd__tteerrmm((_+_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.


ggooaall__eexxppaannssiioonn((_+_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.


eexxppaanndd__ggooaall((_+_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.


ccoommppiillee__aauuxx__ccllaauusseess((_+_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.


ddccgg__ttrraannssllaattee__rruullee((_+_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.


pprreepprroocceessssoorr((_-_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.


44..33..11..11 CCoonnddiittiioonnaall ccoommppiillaattiioonn

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.


::-- iiff((_:_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.


::-- eelliiff((_:_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._________________________________________________________ ||


::-- eellssee
    Start `else' branch.


::-- eennddiiff
    End of conditional compilation.


44..33..22 LLooaaddiinngg ffiilleess,, aaccttiivvee ccooddee aanndd tthhrreeaaddss

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 bb command

  o Fix the sources and reload them using make/0

  o Exit the break, _r_e_t_r_y using the rr 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.


ggaarrbbaaggee__ccoolllleecctt__ccllaauusseess
    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.


44..33..22..11 TThhrreeaaddss aanndd rreellooaaddiinngg rruunnnniinngg ccooddee

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.


44..33..33 QQuuiicckk llooaadd ffiilleess

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.


qqccoommppiillee((_:_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.


qqccoommppiillee((_:_F_i_l_e_, _+_O_p_t_i_o_n_s))
    As  qcompile/1,  but  processes  additional options  as  defined  by
    load_files/2.


44..44 LLiissttiinngg aanndd EEddiittoorr IInntteerrffaaccee

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.

   ___________________________________________________________________
   |__________________________________________FFuullllyy__ssppeecciiffiieedd__oobbjjeeccttss____________________________________________||
   || <_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___________|_
   |__________________________________________AAmmbbiigguuoouuss__ssppeecciiffiiccaattiioonnss__________________________________________||
   || <_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.____________________|_


eeddiitt((_+_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.


eeddiitt
    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.


pprroolloogg__eeddiitt::llooccaattee((_+_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).


pprroolloogg__eeddiitt::llooccaattee((_+_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.


pprroolloogg__eeddiitt::eeddiitt__ssoouurrccee((_+_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.


pprroolloogg__eeddiitt::eeddiitt__ccoommmmaanndd((_+_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.


pprroolloogg__eeddiitt::llooaadd
    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))._________________________ ||


lliissttiinngg((_+_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.


lliissttiinngg
    List all predicates of the database using listing/1.


ppoorrttrraayy__ccllaauussee((_+_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.


ppoorrttrraayy__ccllaauussee((_+_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.


44..55 VVeerriiffyy TTyyppee ooff aa TTeerrmm


vvaarr((_+_T_e_r_m))                                                        _[_I_S_O_]
    True if _T_e_r_m currently is a free variable.


nnoonnvvaarr((_+_T_e_r_m))                                                     _[_I_S_O_]
    True if _T_e_r_m currently is not a free variable.


iinntteeggeerr((_+_T_e_r_m))                                                    _[_I_S_O_]
    True if _T_e_r_m is bound to an integer.


ffllooaatt((_+_T_e_r_m))                                                      _[_I_S_O_]
    True if _T_e_r_m is bound to a floating point number.


rraattiioonnaall((_+_T_e_r_m))
    True  if _T_e_r_m  is  bound to  a rational  number.   Rational  numbers
    include integers.


rraattiioonnaall((_+_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.


nnuummbbeerr((_+_T_e_r_m))                                                     _[_I_S_O_]
    True if _T_e_r_m is bound to an integer or floating point number.


aattoomm((_+_T_e_r_m))                                                       _[_I_S_O_]
    True if _T_e_r_m is bound to an atom.


ssttrriinngg((_+_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_______________________________________________________________ ||


aattoommiicc((_+_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.


ccoommppoouunndd((_+_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.


ccaallllaabbllee((_+_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.


ggrroouunndd((_+_T_e_r_m))
    True if _T_e_r_m holds no free variables.


ccyycclliicc__tteerrmm((_+_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.


aaccyycclliicc__tteerrmm((_+_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.


44..66 CCoommppaarriissoonn aanndd UUnniiffiiccaattiioonn ooff TTeerrmmss

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.


44..66..11 SSttaannddaarrdd OOrrddeerr ooff TTeerrmmss

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.


ccoommppaarree((_?_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.


44..66..22 SSppeecciiaall uunniiffiiccaattiioonn aanndd ccoommppaarriissoonn pprreeddiiccaatteess

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 predicates subsumes/2
and  subsumes_chk/2 define  `one-sided-unification'  and  are  found  in
many  Prolog systems.    Finally,  unifiable/3  is a  `what-if'  version
of unification  that is  often used  as a building  block in  constraint
reasoners.


uunniiffyy__wwiitthh__ooccccuurrss__cchheecckk((_+_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  `structurally  equal' to  _T_e_r_m_2.     Structural
    equivalence  is weaker  than equivalence (==/2),  but stronger  than
    unification  (=/2).  Two terms are structurally equal if  their tree
    representation  is identical  and they  have the  same `pattern'  of
    variables.  Examples:

               a  =@=  A       false
               A  =@=  B       true
          x(A,A)  =@=  x(B,C)  false
          x(A,A)  =@=  x(B,B)  true
          x(A,B)  =@=  x(C,D)  true

    Note that a term  is always structurally equivalent to a copy of it.
    Term copying  takes place in e.g., copy_term/2, findall/3 or proving
    a  clause added  with assert/1.   In  the pure  Prolog world  (i,e,,
    without  attributed variables), =@=/2 behaves  as if defined by  the
    code  below.    With  attributed variables,  structural  equivalence
    of  the  attributes is  tested  rather than  trying to  satisfy  the
    constraints.

    ____________________________________________________________________|                                                                    |
    | A =@= B :-                                                         |
    |         subsumes_chk(A, B),                                        |

    ||________subsumes_chk(B,_A)._______________________________________ ||

    This  predicate  safely handles  cyclic terms.    A  cyclic term  is
    structurally equivalent to itself.

    The  predicates  =@=/2  and  \=@=/2  are  cycle-safe.     Attributed
    variables  are considered  structurally equal  iff their  attributes
    are  structurally  equal.    This predicate  is  known by  the  name
    variant/2 in some other Prolog systems.


_+_T_e_r_m_1 \=@= _+_T_e_r_m_2
    Equivalent to `\+Term1 =@= Term2'.


ssuubbssuummeess((_+_G_e_n_e_r_i_c_, _@_S_p_e_c_i_f_i_c))
    A  term is  told to  _s_u_b_s_u_m_e another  term if  instantiation in  the
    generic  term produces the specific term.  The  subsumption relation
    is  also  called _o_n_e  _s_i_d_e_d  _u_n_i_f_i_c_a_t_i_o_n or  _s_e_m_i_-_u_n_i_f_i_c_a_t_i_o_n.    It
    behaves as if defined by

    ____________________________________________________________________|                                                                    |
    | subsumes(General, Specific) :-                                     |

    |         term_variables(Specific, SVars),                           |
    |         General = Specific,                                        |
    |         term_variables(SVars, SVars2),                             |
    ||________SVars_==_SVars2.__________________________________________ ||


ssuubbssuummeess__cchhkk((_+_G_e_n_e_r_i_c_, _@_S_p_e_c_i_f_i_c))
    Equivalent to \+ \+ subsumes(Generic, Specific).


tteerrmm__ssuubbssuummeerr((_+_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.


uunniiffiiaabbllee((_@_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,[_|_]).


44..77 CCoonnttrrooll PPrreeddiiccaatteess

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

ffaaiill                                                              _[_I_S_O_]
    Always  fail.   The  predicate fail/0  is translated  into a  single
    virtual machine instruction.


ffaallssee
    Same as fail, but the name has a more declarative connotation.


ttrruuee                                                              _[_I_S_O_]
    Always  succeed.  The predicate  true/0 is translated into a  single
    virtual machine instruction.


rreeppeeaatt                                                            _[_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 nnoott 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 ; ffaaiill),  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).


44..88 MMeettaa--CCaallll PPrreeddiiccaatteess

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.


ccaallll((_:_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.


ccaallll((_:_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.


aappppllyy((_:_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.


nnoott((_:_G_o_a_l))
    True  if _G_o_a_l cannot  be proven.   Retained for compatibility  only.
    New code should use \+/1.


oonnccee((_:_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.________________________________________________ ||


iiggnnoorree((_:_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(_).________________________________________________________ ||


ccaallll__wwiitthh__ddeepptthh__lliimmiitt((_:_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.


sseettuupp__ccaallll__cclleeaannuupp((_:_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.


sseettuupp__ccaallll__ccaattcchheerr__cclleeaannuupp((_:_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.

    eexxiitt
         _G_o_a_l succeeded without leaving any choice-points.

    ffaaiill
         _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).

    eexxcceeppttiioonn((_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.

    eexxtteerrnnaall__eexxcceeppttiioonn((_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_____________ |      |


ccaallll__cclleeaannuupp((_:_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.


ccaallll__cclleeaannuupp((_:_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.


44..99 IISSOO ccoommpplliiaanntt EExxcceeppttiioonn hhaannddlliinngg

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.


ccaattcchh((_:_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.


tthhrrooww((_+_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().


44..99..11 DDeebbuuggggiinngg aanndd eexxcceeppttiioonnss

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.


44..99..22 TThhee eexxcceeppttiioonn tteerrmm

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.


44..99..33 PPrriinnttiinngg mmeessssaaggeess

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.


pprriinntt__mmeessssaaggee((_+_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.


pprriinntt__mmeessssaaggee__lliinneess((_+_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, []).

    nnll
         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.


mmeessssaaggee__hhooookk((_+_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.


mmeessssaaggee__ttoo__ssttrriinngg((_+_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.


44..99..33..11 PPrriinnttiinngg ffrroomm lliibbrraarriieess

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.


44..1100 HHaannddlliinngg ssiiggnnaallss

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

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

oonn__ssiiggnnaall((_+_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.


ccuurrrreenntt__ssiiggnnaall((_?_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).


44..1100..11 NNootteess oonn ssiiggnnaall hhaannddlliinngg

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

44..1111 DDCCGG GGrraammmmaarr rruulleess

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:


pphhrraassee((_+_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, []).


pphhrraassee((_+_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]______________________________ ||


44..1122 DDaattaabbaassee

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

aabboolliisshh((_:_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.


aabboolliisshh((_+_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.


rreeddeeffiinnee__ssyysstteemm__pprreeddiiccaattee((_+_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.


rreettrraacctt((_+_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.


rreettrraaccttaallll((_+_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.


aasssseerrtt((_+_T_e_r_m))
    Assert  a fact or clause in the  database.  _T_e_r_m is asserted  as the
    last fact or clause of the corresponding predicate.


aasssseerrttaa((_+_T_e_r_m))                                                    _[_I_S_O_]
    Equivalent  to assert/1,  but _T_e_r_m  is asserted as  first clause  or
    fact of the predicate.


aasssseerrttzz((_+_T_e_r_m))                                                    _[_I_S_O_]
    Equivalent to assert/1.


aasssseerrtt((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Equivalent  to  assert/1, but  _R_e_f_e_r_e_n_c_e is  unified  with a  unique
    reference  to the asserted clause.  This key can later be  used with
    clause/3 or erase/1.


aasssseerrttaa((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Equivalent  to assert/2,  but _T_e_r_m  is asserted as  first clause  or
    fact of the predicate.


aasssseerrttzz((_+_T_e_r_m_, _-_R_e_f_e_r_e_n_c_e))
    Equivalent to assert/2.


rreeccoorrddaa((_+_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).


rreeccoorrddaa((_+_K_e_y_, _+_T_e_r_m))
    Equivalent to recorda(_K_e_y, _V_a_l_u_e,  _).


rreeccoorrddzz((_+_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.


rreeccoorrddzz((_+_K_e_y_, _+_T_e_r_m))
    Equivalent to recordz(_K_e_y, _V_a_l_u_e,  _).


rreeccoorrddeedd((_?_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)___________________________ ||


rreeccoorrddeedd((_+_K_e_y_, _-_V_a_l_u_e))
    Equivalent to recorded(_K_e_y, _V_a_l_u_e,  _).


eerraassee((_+_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.


iinnssttaannccee((_+_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.


ffllaagg((_+_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.


44..1122..11 UUppddaattee vviieeww

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.


44..1122..22 IInnddeexxiinngg ddaattaabbaasseess

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.


tteerrmm__hhaasshh((_+_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.   The term_hash/2 predicate is  cycle-safe.
    Hashes for numbers differ between big and little endian machines.


tteerrmm__hhaasshh((_+_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.    Using
    _D_e_p_t_h = -1 makes term_hash/4 behave as  term_hash/2,  hashing ground
    terms to the full depth.

    _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]


vvaarriiaanntt__sshhaa11((_+_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.


44..1133 DDeeccllaarriinngg pprreeddiiccaatteess pprrooppeerrttiieess

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.


ddyynnaammiicc _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.
    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.


ccoommppiillee__pprreeddiiccaatteess((_:_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.


mmuullttiiffiillee _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.
    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.


ddiissccoonnttiigguuoouuss _:_P_r_e_d_i_c_a_t_e_I_n_d_i_c_a_t_o_r_, _._._.
    Informs  the system that the  clauses of the specified  predicate(s)
    might not be together in the source file.  See also style_check/1.


iinnddeexx((_+_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.


hhaasshh((_+_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.


44..1144 EExxaammiinniinngg tthhee pprrooggrraamm


ccuurrrreenntt__aattoomm((_-_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.


ccuurrrreenntt__bblloobb((_?_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.6 for details.


ccuurrrreenntt__ffuunnccttoorr((_?_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.


ccuurrrreenntt__ffllaagg((_-_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).


ccuurrrreenntt__kkeeyy((_-_K_e_y))
    Successively  unifies  _K_e_y  with  all keys  used  for  records  (see
    recorda/3, etc.).


ccuurrrreenntt__pprreeddiiccaattee((_:_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.


ccuurrrreenntt__pprreeddiiccaattee((_?_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.


pprreeddiiccaattee__pprrooppeerrttyy((_:_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:

    aauuttoollooaadd
         Is true if  the predicate can be  autoloaded.  Like  undefined,
         this property is _n_o_t generated.

    bbuuiilltt__iinn
         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.

    ddyynnaammiicc
         Is true  if assert/1 and  retract/1 may be  used to modify  the
         predicate.  This property is set using dynamic/1.

    eexxppoorrtteedd
         Is true if the predicate  is in the public list of  the context
         module.

    iimmppoorrtteedd__ffrroomm((_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.

    ffiillee((_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.

    ffoorreeiiggnn
         Is true if the predicate is defined in the C language.

    iinnddeexxeedd((_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.

    iinntteerrpprreetteedd
         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.

    iissoo
         Is  true if  the  predicate  is  covered by  the  ISO  standard
         (ISO/IEC 13211-1).

    lliinnee__ccoouunntt((_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.

    mmuullttiiffiillee
         Is true there  may be multiple  (or no) file providing  clauses
         for the predicate.  This property is set using multifile/1.

    mmeettaa__pprreeddiiccaattee((_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.

    nnooddeebbuugg
         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.

    nnoottrraaccee
         Do not show ports of this predicate in the debugger.

    nnuummbbeerr__ooff__ccllaauusseess((_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.

    tthhrreeaadd__llooccaall
         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.

    ttrraannssppaarreenntt
         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.

    uunnddeeffiinneedd
         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.

    vvoollaattiillee
         If  true, the  clauses  are not  saved  into a  saved-state  by
         qsave_program/[1,2].  This property is set using volatile/1.


ddwwiimm__pprreeddiiccaattee((_+_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.


ccllaauussee((_:_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.


ccllaauussee((_:_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.


nntthh__ccllaauussee((_?_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)_________________________________________ ||


ccllaauussee__pprrooppeerrttyy((_+_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:

    ffiillee((_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.

    lliinnee__ccoouunntt((_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.

    ffaacctt
         True if the clause has no body.

    eerraasseedd
         True if  the  clause has  been erased,  but  not yet  reclaimed
         because it is referenced.


44..1155 IInnppuutt aanndd oouuttppuutt

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.


44..1155..11 IISSOO IInnppuutt aanndd OOuuttppuutt SSttrreeaammss

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.


ooppeenn((_+_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:

    ttyyppee((_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.

    aalliiaass((_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),                                     |
         ||_______...___________________________________________________ ||

    eennccooddiinngg((_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.

    bboomm((_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.

    eeooff__aaccttiioonn((_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.

    bbuuffffeerr((_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.

    cclloossee__oonn__aabboorrtt((_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).

    lloocckk((_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.

    wwaaiitt((_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.


ooppeenn((_+_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.


ooppeenn__nnuullll__ssttrreeaamm((_?_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._______________________________________________ ||


cclloossee((_+_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.


cclloossee((_+_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.


ssttrreeaamm__pprrooppeerrttyy((_?_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:

    aalliiaass((_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.

    bbuuffffeerr((_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.

    bbuuffffeerr__ssiizzee((_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.

    bboomm((_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.

    eennccooddiinngg((_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.

    eenndd__ooff__ssttrreeaamm((_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].

    eeooff__aaccttiioonn((_A))
         Unify _A with one of  eof_code,  reset or error.  See  open/4 for
         details.

    ffiillee__nnaammee((_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.

    ffiillee__nnoo((_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.

    iinnppuutt
         True if _S_t_r_e_a_m has mode read.

    mmooddee((_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.

    nneewwlliinnee((_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.

    nnlliinnkk((_-_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.

    oouuttppuutt
         True if _S_t_r_e_a_m has mode write, append or update.

    ppoossiittiioonn((_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.

    rreeppoossiittiioonn((_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.

    rreepprreesseennttaattiioonn__eerrrroorrss((_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.

    ttiimmeeoouutt((_-_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.

    ttyyppee((_T))
         Unify _B_o_o_l with text or binary.

    ttttyy((_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.


ccuurrrreenntt__ssttrreeaamm((_?_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.


iiss__ssttrreeaamm((_+_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.


ssttrreeaamm__ppaaiirr((_?_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.


sseett__ssttrreeaamm__ppoossiittiioonn((_+_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.


ssttrreeaamm__ppoossiittiioonn__ddaattaa((_?_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.


sseeeekk((_+_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.


sseett__ssttrreeaamm((_+_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.

    aalliiaass((_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.

    bbuuffffeerr((_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.

    bbuuffffeerr__ssiizzee((_+_S_i_z_e))
         Set the  size of  the I/O buffer  of the  underlying stream  to
         _S_i_z_e bytes.

    cclloossee__oonn__aabboorrtt((_B_o_o_l))
         Determine whether or not the  stream is closed by abort/0.   By
         default streams are closed.

    eennccooddiinngg((_A_t_o_m))
         Defines the mapping between bytes and character  codes used for
         the stream.  See section 2.17.1 for supported encodings.

    eeooff__aaccttiioonn((_A_c_t_i_o_n))
         Set end-of-file handling to one of eof_code, reset or error.

    nneewwlliinnee((_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.

    ttiimmeeoouutt((_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_)_, __)

    ttyyppee((_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.

    rreeccoorrdd__ppoossiittiioonn((_B_o_o_l))
         Do/do  not  record   the  line-count  and  line-position   (see
         line_count/2 and line_position/2).

    rreepprreesseennttaattiioonn__eerrrroorrss((_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.

    ffiillee__nnaammee((_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.

    ttttyy((_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.


sseett__pprroolloogg__IIOO((_+_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.


44..1155..22 EEddiinnbbuurrgghh--ssttyyllee II//OO

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

CCoommppaattiibbiilliittyy nnootteess

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.


sseeee((_+_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.


tteellll((_+_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.


aappppeenndd((_+_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.


sseeeeiinngg((_?_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.


tteelllliinngg((_?_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.


sseeeenn
    Close  the  current input  stream.   The  new  input stream  becomes
    _u_s_e_r___i_n_p_u_t.


ttoolldd
    Close  the current  output stream.   The  new output stream  becomes
    _u_s_e_r___o_u_t_p_u_t.


44..1155..33 SSwwiittcchhiinngg BBeettwweeeenn EEddiinnbbuurrgghh aanndd IISSOO II//OO

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

sseett__iinnppuutt((_+_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).


sseett__oouuttppuutt((_+_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.


ccuurrrreenntt__iinnppuutt((_-_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.


ccuurrrreenntt__oouuttppuutt((_-_S_t_r_e_a_m))                                            _[_I_S_O_]
    Get the current output stream.


44..1155..44 WWrriittee oonnttoo aattoommss,, ccooddee--lliissttss,, eettcc..


wwiitthh__oouuttppuutt__ttoo((_+_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]_____________________________________ ||

    AA SSttrreeaamm hhaannddllee oorr aalliiaass
         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.

    aattoomm((_-_A_t_o_m))
         Create an atom  from the emitted characters.   Please note  the
         remark above.

    ssttrriinngg((_-_S_t_r_i_n_g))
         Create a string-object as defined in section 4.22.

    ccooddeess((_-_C_o_d_e_s))
         Create a list of  character codes from the emitted  characters,
         similar to atom_codes/2.

    ccooddeess((_-_C_o_d_e_s_, _-_T_a_i_l))
         Create a list of character codes as a difference-list.

    cchhaarrss((_-_C_h_a_r_s))
         Create a  list of  one-character-atoms codes  from the  emitted
         characters, similar to atom_chars/2.

    cchhaarrss((_-_C_h_a_r_s_, _-_T_a_i_l))
         Create a list of one-character-atoms as a difference-list.


44..1166 SSttaattuuss ooff ssttrreeaammss


wwaaiitt__ffoorr__iinnppuutt((_+_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)),   |

    ||________...,______________________________________________________ ||


bbyyttee__ccoouunntt((_+_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).


cchhaarraacctteerr__ccoouunntt((_+_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.


lliinnee__ccoouunntt((_+_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.


lliinnee__ppoossiittiioonn((_+_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.


44..1177 PPrriimmiittiivvee cchhaarraacctteerr II//OO

See section 4.2 for an overview of supported character representations.


nnll                                                                _[_I_S_O_]
    Write  a newline character  to the current output  stream.  On  Unix
    systems nl/0 is equivalent to put(10).


nnll((_+_S_t_r_e_a_m))                                                       _[_I_S_O_]
    Write a newline to _S_t_r_e_a_m.


ppuutt((_+_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.


ppuutt((_+_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.


ppuutt__bbyyttee((_+_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.


ppuutt__bbyyttee((_+_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.


ppuutt__cchhaarr((_+_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.


ppuutt__cchhaarr((_+_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.


ppuutt__ccooddee((_+_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.


ppuutt__ccooddee((_+_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.


ttaabb((_+_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).


ttaabb((_+_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.


fflluusshh__oouuttppuutt                                                       _[_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.


fflluusshh__oouuttppuutt((_+_S_t_r_e_a_m))                                              _[_I_S_O_]
    Flush  output on the specified stream.  The stream must be  open for
    writing.


ttttyyfflluusshh
    Flush pending output on stream _u_s_e_r.  See also flush_output/[0,1].


ggeett__bbyyttee((_-_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.


ggeett__bbyyttee((_+_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.


ggeett__ccooddee((_-_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.


ggeett__ccooddee((_+_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.


ggeett__cchhaarr((_-_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.


ggeett__cchhaarr((_+_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.


ggeett00((_-_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.


ggeett00((_+_S_t_r_e_a_m_, _-_C_h_a_r))
    Edinburgh  version  of  the ISO  get_code/2  predicate.    See  also
    get0/1.


ggeett((_-_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.


ggeett((_+_S_t_r_e_a_m_, _-_C_h_a_r))
    Read the next non-blank character from _S_t_r_e_a_m.


ppeeeekk__bbyyttee((_-_B_y_t_e))                                                   _[_I_S_O_]
    Reads  the next input byte  like get_byte/1, but does not remove  it
    from the input stream.


ppeeeekk__bbyyttee((_+_S_t_r_e_a_m_, _-_B_y_t_e))                                          _[_I_S_O_]
    Reads  the next input byte  like get_byte/2, but does not remove  it
    from the stream.


ppeeeekk__ccooddee((_-_C_o_d_e))                                                   _[_I_S_O_]
    Reads  the next input code  like get_code/1, but does not remove  it
    from the input stream.


ppeeeekk__ccooddee((_+_S_t_r_e_a_m_, _-_C_o_d_e))                                          _[_I_S_O_]
    Reads  the next input code  like get_code/2, but does not remove  it
    from the stream.


ppeeeekk__cchhaarr((_-_C_h_a_r))                                                   _[_I_S_O_]
    Reads the  next input character like get_char/1,  but does not remove
    it from the input stream.


ppeeeekk__cchhaarr((_+_S_t_r_e_a_m_, _-_C_h_a_r))                                          _[_I_S_O_]
    Reads the  next input character like get_char/2,  but does not remove
    it from the stream.


sskkiipp((_+_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.


sskkiipp((_+_S_t_r_e_a_m_, _+_C_o_d_e))
    Skip input (as skip/1) on _S_t_r_e_a_m.


ggeett__ssiinnggllee__cchhaarr((_-_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.


aatt__eenndd__ooff__ssttrreeaamm                                                    _[_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.


aatt__eenndd__ooff__ssttrreeaamm((_+_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).


sseett__eenndd__ooff__ssttrreeaamm((_+_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.


ccooppyy__ssttrreeaamm__ddaattaa((_+_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.


ccooppyy__ssttrreeaamm__ddaattaa((_+_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.


rreeaadd__ppeennddiinngg__iinnppuutt((_+_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                                               |
    ||____________).____________________________________________________ ||


44..1188 TTeerrmm rreeaaddiinngg aanndd wwrriittiinngg

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.

There are  two ways  to manipulate  the output  format.   The  predicate
print/[1,2] may be programmed  using portray/1.  The format  of floating
point numbers may be manipulated using the Prolog flag float_format.

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

wwrriittee__tteerrmm((_+_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:

    aattttrriibbuutteess((_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).

    bbaacckkqquuootteedd__ssttrriinngg((_B_o_o_l))
         If true,  write a string  object (see  section 4.22) as  `...`.
         The default depends on the Prolog flag backquoted_string.

    cchhaarraacctteerr__eessccaappeess((_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).

    iiggnnoorree__ooppss((_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.

    mmaaxx__ddeepptthh((_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.

    mmoodduullee((_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.

    nnuummbbeerrvvaarrss((_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.

    ppaarrttiiaall((_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._______________________________________ ||

    ppoorrttrraayy((_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.

    pprriioorriittyy((_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)])______ ||

    qquuootteedd((_B_o_o_l))
         If true, atoms and  functors that needs quotes will  be quoted.
         The default is false.

    ssppaacciinngg((_+_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.


wwrriittee__tteerrmm((_+_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.


wwrriittee__ccaannoonniiccaall((_+_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.


wwrriittee__ccaannoonniiccaall((_+_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.


wwrriittee((_+_T_e_r_m))                                                      _[_I_S_O_]
    Write  _T_e_r_m  to the  current output,  using  brackets and  operators
    where  appropriate.  The Prolog flag  float_format controls floating
    point output format.


wwrriittee((_+_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.


wwrriitteeqq((_+_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.


wwrriitteeqq((_+_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.


pprriinntt((_+_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.


pprriinntt((_+_S_t_r_e_a_m_, _+_T_e_r_m))
    Print _T_e_r_m to _S_t_r_e_a_m.


ppoorrttrraayy((_+_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.


rreeaadd((_-_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.


rreeaadd((_+_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.


rreeaadd__ccllaauussee((_-_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).


rreeaadd__ccllaauussee((_+_S_t_r_e_a_m_, _-_T_e_r_m))
    Read a clause from _S_t_r_e_a_m.  See read_clause/1.


rreeaadd__tteerrmm((_-_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:

    bbaacckkqquuootteedd__ssttrriinngg((_B_o_o_l))
         If true,  read `...`  to a  string object  (see section  4.22).
         The default depends on the Prolog flag backquoted_string.

    cchhaarraacctteerr__eessccaappeess((_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).

    ccoommmmeennttss((_-_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.

    ddoouubbllee__qquuootteess((_B_o_o_l))
         Defines  how to  read  "..." strings.     See the  Prolog  flag
         double_quotes.  (SWI-Prolog).

    mmoodduullee((_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).

    ssiinngglleettoonnss((_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.

    ssyynnttaaxx__eerrrroorrss((_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).

    ssuubbtteerrmm__ppoossiittiioonnss((_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).

         ssttrriinngg__ppoossiittiioonn((_F_r_o_m_, _T_o))
             Used  to indicate  the  position of  a string  enclosed  in
             double quotes (").

         bbrraaccee__tteerrmm__ppoossiittiioonn((_F_r_o_m_, _T_o_, _A_r_g))
             Term  of  the form  {...},  as used  in  DCG  rules.    _A_r_g
             describes the argument.

         lliisstt__ppoossiittiioonn((_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.

         tteerrmm__ppoossiittiioonn((_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.

    tteerrmm__ppoossiittiioonn((_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.

    vvaarriiaabblleess((_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).

    vvaarriiaabbllee__nnaammeess((_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).


rreeaadd__tteerrmm((_+_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.


rreeaadd__hhiissttoorryy((_+_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)__________ ||


pprroommpptt((_-_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.


pprroommpptt11((_+_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.


44..1199 AAnnaallyyssiinngg aanndd CCoonnssttrruuccttiinngg TTeerrmmss


ffuunnccttoorr((_?_T_e_r_m_, _?_F_u_n_c_t_o_r_, _?_A_r_i_t_y))                                  _[_I_S_O_]
    True  if _T_e_r_m is a  term with functor _F_u_n_c_t_o_r  and arity _A_r_i_t_y.   If
    _T_e_r_m  is a  variable  it is  unified with  a new  term holding  only
    variables.    functor/3 silently  fails on  instantiation faults  If
    _T_e_r_m  is an atom or  number, _F_u_n_c_t_o_r will  be unified with _T_e_r_m  and
    arity will be unified with the integer 0 (zero).


aarrgg((_?_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))________________________________________________ ||


nnuummbbeerrvvaarrss((_+_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.


nnuummbbeerrvvaarrss((_+_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:

    ffuunnccttoorr__nnaammee((_+_A_t_o_m))
         Name of the functor to use instead of $VAR.

    aattttvvaarr((_+_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.

    ssiinngglleettoonnss((_+_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.


tteerrmm__vvaarriiaabblleess((_+_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__________________________________________________________ ||


tteerrmm__vvaarriiaabblleess((_+_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.


ccooppyy__tteerrmm((_+_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.


44..1199..11 NNoonn--llooggiiccaall ooppeerraattiioonnss oonn tteerrmmss

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.


sseettaarrgg((_+_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.


nnbb__sseettaarrgg((_+_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)                                 |
    ||________).________________________________________________________ ||


nnbb__lliinnkkaarrgg((_+_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.


dduupplliiccaattee__tteerrmm((_+_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.


ssaammee__tteerrmm((_@_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.


44..2200 AAnnaallyyssiinngg aanndd CCoonnssttrruuccttiinngg AAttoommss

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

aattoomm__ccooddeess((_?_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.


aattoomm__cchhaarrss((_?_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]_______________________________________________ ||


cchhaarr__ccooddee((_?_A_t_o_m_, _?_C_o_d_e))                                            _[_I_S_O_]
    Convert  between character and character  code for a single  charac-
    ter.


nnuummbbeerr__cchhaarrss((_?_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.


nnuummbbeerr__ccooddeess((_?_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.


aattoomm__nnuummbbeerr((_?_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.


nnaammee((_?_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).


tteerrmm__ttoo__aattoomm((_?_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.


aattoomm__ttoo__tteerrmm((_+_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.


aattoomm__ccoonnccaatt((_?_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.


aattoommiicc__ccoonnccaatt((_+_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._______________________________________________________ ||


aattoommiicc__lliisstt__ccoonnccaatt((_+_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.


aattoommiicc__lliisstt__ccoonnccaatt((_+_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]___________________________________________________ ||


aattoomm__lleennggtthh((_+_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.


aattoomm__pprreeffiixx((_+_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.


ssuubb__aattoomm((_+_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.


44..2211 CChhaarraacctteerr pprrooppeerrttiieess

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.


cchhaarr__ttyyppee((_?_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.

    aallnnuumm
         _C_h_a_r is a letter (upper- or lowercase) or digit.

    aallpphhaa
         _C_h_a_r is a letter (upper- or lowercase).

    ccssyymm
         _C_h_a_r  is a  letter  (upper- or  lowercase),  digit or  the  un-
         derscore  (_).      These  are  valid  C-  and   Prolog  symbol
         characters.

    ccssyymmff
         _C_h_a_r is a letter  (upper- or lowercase) or the  underscore (_).
         These are valid first characters for C- and Prolog symbols

    aasscciiii
         _C_h_a_r is a 7-bits ASCII character (0..127).

    wwhhiittee
         _C_h_a_r is a space or tab.  E.i. white space inside a line.

    ccnnttrrll
         _C_h_a_r is an ASCII control-character (0..31).

    ddiiggiitt
         _C_h_a_r is a digit.

    ddiiggiitt((_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.

    xxddiiggiitt((_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.

    ggrraapphh
         _C_h_a_r produces  a visible mark  on a  page when printed.    Note
         that the space is not included!

    lloowweerr
         _C_h_a_r is a lower-case letter.

    lloowweerr((_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.

    ttoo__lloowweerr((_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.

    uuppppeerr
         _C_h_a_r is an upper-case letter.

    uuppppeerr((_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.

    ttoo__uuppppeerr((_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.

    ppuunncctt
         _C_h_a_r is  a punctuation character.   This  is a graph  character
         that is not a letter or digit.

    ssppaaccee
         _C_h_a_r  is some  form  of layout  character  (tab,  vertical-tab,
         newline, etc.).

    eenndd__ooff__ffiillee
         _C_h_a_r is -1.

    eenndd__ooff__lliinnee
         _C_h_a_r ends a line (ASCII: 10..13).

    nneewwlliinnee
         _C_h_a_r is a the newline character (10).

    ppeerriioodd
         _C_h_a_r counts as the end of a sentence (.,!,?).

    qquuoottee
         _C_h_a_r is a quote-character (", ', `).

    ppaarreenn((_C_l_o_s_e))
         _C_h_a_r is  an  open-parenthesis and  _C_l_o_s_e is  the  corresponding
         close-parenthesis.


ccooddee__ttyyppee((_?_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.


44..2211..11 CCaassee ccoonnvveerrssiioonn

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:


ddoowwnnccaassee__aattoomm((_+_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.


uuppccaassee__aattoomm((_+_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.


44..2211..22 WWhhiittee ssppaaccee nnoorrmmaalliizzaattiioonn


nnoorrmmaalliizzee__ssppaaccee((_-_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.


44..2211..33 LLaanngguuaaggee ssppeecciiffiicc ccoommppaarriissoonn

This  section  deals  with  predicates  for   language  specific  string
comparison operations.


ccoollllaattiioonn__kkeeyy((_+_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.


llooccaallee__ssoorrtt((_+_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.


44..2222 RReepprreesseennttiinngg tteexxtt iinn ssttrriinnggss

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.


ssttrriinngg__ttoo__aattoomm((_?_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.


ssttrriinngg__ttoo__lliisstt((_?_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.


ssttrriinngg__lleennggtthh((_+_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.


ssttrriinngg__ccoonnccaatt((_?_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.


ssuubb__ssttrriinngg((_+_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.


44..2233 OOppeerraattoorrss

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 nnoott influence  parsing
characters into atoms and  quoting an atom does nnoott stop it  from acting
as an operator.   To stop an atom  acting as an operator, enclose  it in
braces like this:  (myop).


oopp((_+_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,  yfy,
    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.     The  ISO
    standard  allows  for  redefining  all operators  except  the  comma
    (,).    Applications must  be extremely  careful with  (re-)defining
    operators  because changing operators may cause (other) files  to be
    interpreted  ddiiffffeerreennttllyy.  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.

    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


ccuurrrreenntt__oopp((_?_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.


44..2244 CChhaarraacctteerr CCoonnvveerrssiioonn

Although I  wouldn't really know  for what you would  like to use  these
features, they are provided for ISO compliance.


cchhaarr__ccoonnvveerrssiioonn((_+_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.


ccuurrrreenntt__cchhaarr__ccoonnvveerrssiioonn((_?_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.


44..2255 AArriitthhmmeettiicc

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.


44..2255..11 SSppeecciiaall ppuurrppoossee iinntteeggeerr aarriitthhmmeettiicc

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.


bbeettwweeeenn((_+_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.


ssuucccc((_?_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.


pplluuss((_?_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.


44..2255..22 GGeenneerraall ppuurrppoossee aarriitthhmmeettiicc

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 iiss _+_E_x_p_r                                                  _[_I_S_O_]
    True  if _N_u_m_b_e_r has successfully  been unified with the number  _E_x_p_r
    evaluates to.   If _E_x_p_r evaluates to a float that can be represented
    using  an integer (i.e,  the value is  integer and within the  range
    that can be  described by Prolog's integer representation),  _E_x_p_r is
    unified with the integer value.

    Note  that normally, 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.


44..2255..22..11 AArriitthhmmeettiicc ttyyppeess

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  denominator `1' and floating  point
numbers that can be  accurately converted to integers.  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


44..2255..22..22 RRaattiioonnaall nnuummbbeerr eexxaammpplleess

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

44..2255..22..33 AArriitthhmmeettiicc FFuunnccttiioonnss

Arithmetic functions  are terms  which are evaluated  by the  arithmetic
predicates described in  section 4.25.2.   SWI-Prolog tries to hide  the
difference  between integer  arithmetic  and floating  point  arithmetic
from the Prolog user.  Arithmetic is done as  integer arithmetic as long
as possible and  converted to floating point arithmetic whenever  one of
the arguments  or the combination of  them requires it.   If a  function
returns  a floating  point  value which  is  whole it  is  automatically
transformed into  an integer.    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 mmoodd _+_I_n_t_E_x_p_r_2                                           _[_I_S_O_]
    Modulo:     _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 rreemm _+_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:  _R_e_s_u_l_t is truncate(_E_x_p_r_1/_E_x_p_r_2)


_+_R_a_t_E_x_p_r rrddiivv _+_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 ggccdd _+_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.


aabbss((_+_E_x_p_r))                                                        _[_I_S_O_]
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_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.


mmaaxx((_+_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.


mmiinn((_+_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.


rraannddoomm((_+_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.


rroouunndd((_+_E_x_p_r))                                                      _[_I_S_O_]
    Evaluates _E_x_p_r and rounds the result to the nearest integer.


iinntteeggeerr((_+_E_x_p_r))
    Same as round/1 (backward compatibility).


ffllooaatt((_+_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.


rraattiioonnaall((_+_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_______________________ ||


rraattiioonnaalliizzee((_+_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_____________________________________________________ ||


ffllooaatt__ffrraaccttiioonnaall__ppaarrtt((_+_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).


ffllooaatt__iinntteeggeerr__ppaarrtt((_+_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.


ttrruunnccaattee((_+_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.


fflloooorr((_+_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.


cceeiilliinngg((_+_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.


cceeiill((_+_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 >< _+_I_n_t_E_x_p_r                                          _[_I_S_O_-_r_e_v_]
    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 xxoorr _+_I_n_t_E_x_p_r
    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.


ssqqrrtt((_+_E_x_p_r))                                                       _[_I_S_O_]
    _R_e_s_u_l_t =square root of _E_x_p_r


ssiinn((_+_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.


ccooss((_+_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.


ttaann((_+_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.


aassiinn((_+_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.


aaccooss((_+_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.


aattaann((_+_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.


aattaann((_+_Y_E_x_p_r_, _+_X_E_x_p_r))
    _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.


lloogg((_+_E_x_p_r))                                                        _[_I_S_O_]
    Natural logarithm.  _R_e_s_u_l_t =natural logarithm of _E_x_p_r


lloogg1100((_+_E_x_p_r))
    Base-10 logarithm.  _R_e_s_u_l_t =10 base logarithm of _E_x_p_r


eexxpp((_+_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.


ppoowwmm((_+_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).


ppii
    Evaluates to the mathematical constant pi (3.14159...).


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

eeppssiilloonn
    Evaluates to the  the difference between the float 1.0 and the first
    larger floating point number.


ccppuuttiimmee
    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.


eevvaall((_+_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.

BBiittvveeccttoorr ffuunnccttiioonnss

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.


mmssbb((_+_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.


llssbb((_+_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.


ppooppccoouunntt((_+_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.


44..2266 AAddddiinngg AArriitthhmmeettiicc FFuunnccttiioonnss

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.


aarriitthhmmeettiicc__ffuunnccttiioonn((_:_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______________________________________________________ ||


ccuurrrreenntt__aarriitthhmmeettiicc__ffuunnccttiioonn((_:_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._____________________________________________________________ ||


44..2277 MMiisscc aarriitthhmmeettiicc ssuuppppoorrtt pprreeddiiccaatteess


sseett__rraannddoomm((_+_O_p_t_i_o_n))
    Controls  the random  number generator that  accessible through  the
    function random.

    sseeeedd((_+_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.


44..2288 BBuuiilltt--iinn lliisstt ooppeerraattiioonnss

Most  list  operations  are  defined  in  the  library  lists  described
in  section 11.12.    Some  that  are  implemented with  more  low-level
primitives are built-in and described here.


iiss__lliisstt((_+_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)._______________________________________________ ||


mmeemmbbeerrcchhkk((_?_E_l_e_m_, _+_L_i_s_t))
    Same as once(member(_E_l_e_m, _L_i_s_t)).


lleennggtthh((_?_L_i_s_t_, _?_I_n_t))
    True if _I_n_t represents  the number of elements of list _L_i_s_t.  Can be
    used to create a list holding only variables.


ssoorrtt((_+_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.


mmssoorrtt((_+_L_i_s_t_, _-_S_o_r_t_e_d))
    Equivalent to sort/2, but  does not remove duplicates.  Fails with a
    type_error if _L_i_s_t is a cyclic list or not a list.


kkeeyyssoorrtt((_+_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.


pprreeddssoorrtt((_+_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.


44..2299 FFiinnddiinngg aallll SSoolluuttiioonnss ttoo aa GGooaall


ffiinnddaallll((_+_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.


ffiinnddaallll((_+_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,_[])_____________________________ ||


bbaaggooff((_+_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_?-______________________________________________________________ ||


sseettooff((_+_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.


44..3300 FFoorraallll


ffoorraallll((_:_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)._____________________________ ||


44..3311 FFoorrmmaatttteedd WWrriittee

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.


44..3311..11 WWrriitteeff


wwrriitteellnn((_+_T_e_r_m))
    Equivalent to write(Term), nl.


wwrriitteeff((_+_A_t_o_m))
    Equivalent to writef(Atom, []).


wwrriitteeff((_+_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_ddeecciimmaall)_|

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

sswwrriitteeff((_-_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"________________________________________ ||


sswwrriitteeff((_-_S_t_r_i_n_g_, _+_F_o_r_m_a_t))
    Equivalent to swritef(String, Format, []).


44..3311..22 FFoorrmmaatt

The format-family of  predicates is the most versatile and  portable way
to produce textual output.


ffoorrmmaatt((_+_F_o_r_m_a_t))
    Defined as `format(Format) :- format(Format, []).'


ffoorrmmaatt((_+_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  ww, 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 dd, 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 ee,  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 ee or ff notation, whichever is shorter.

      G  Floating point in EE or ff 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 rr, 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___ ||


ffoorrmmaatt((_+_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'___________________________________________________ ||


44..3311..33 PPrrooggrraammmmiinngg FFoorrmmaatt


ffoorrmmaatt__pprreeddiiccaattee((_+_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                                                   |
    ||________).________________________________________________________ ||


ccuurrrreenntt__ffoorrmmaatt__pprreeddiiccaattee((_?_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.


44..3322 TTeerrmmiinnaall CCoonnttrrooll

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.


ttttyy__ggeett__ccaappaabbiilliittyy((_+_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.


ttttyy__ggoottoo((_+_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.


ttttyy__ppuutt((_+_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).


sseett__ttttyy((_-_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.


ttttyy__ssiizzee((_-_R_o_w_s_, _-_C_o_l_u_m_n_s))
    Determine the size of the terminal.  Platforms:

    UUnniixx  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.

    WWiinnddoowwss  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.


44..3333 OOppeerraattiinngg SSyysstteemm IInntteerraaccttiioonn


sshheellll((_+_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 nnoott 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'


sshheellll((_+_C_o_m_m_a_n_d))
    Equivalent to `shell(Command, 0)'.


sshheellll
    Start  an  interactive  Unix  shell.     Default  is  /bin/sh,   the
    environment  variable SHELL overrides this  default.  Not  available
    for Win32 platforms.


wwiinn__eexxeecc((_+_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


wwiinn__sshheellll((_+_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.


wwiinn__sshheellll((_+_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)


wwiinn__rreeggiissttrryy__ggeett__vvaalluuee((_+_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__________________________________________________________ ||


wwiinn__ffoollddeerr((_?_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'________ ||


ggeetteennvv((_+_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.


sseetteennvv((_+_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.


uunnsseetteennvv((_+_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.


sseettllooccaallee((_+_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.


uunniixx((_+_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.

    ssyysstteemm((_+_C_o_m_m_a_n_d))
         Equivalent to calling shell/1.  Use for compatibility only.

    sshheellll((_+_C_o_m_m_a_n_d))
         Equivalent to calling shell/1.  Use for compatibility only.

    sshheellll
         Equivalent to calling shell/0.  Use for compatibility only.

    ccdd
         Equivalent to calling working_directory/2 to the expansion (see
         expand_file_name/2) of ~.  For compatibility only.

    ccdd((_+_D_i_r_e_c_t_o_r_y))
         Equivalent to calling working_directory/2.  Use for compatibil-
         ity only.

    aarrggvv((_-_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).________________________________________ ||


44..3333..11 DDeeaalliinngg wwiitthh ttiimmee aanndd ddaattee

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.


44..3333..11..11 TTiimmee aanndd ddaattee ddaattaa--ssttrruuccttuurreess

We use the following time representations

TTiimmeeSSttaammpp
    A  TimeStamp  is a  floating  point number  expression the  time  in
    seconds since the Epoch at 1970-1-1.

ddaattee((_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.

ddaattee((_Y_,_M_._D))
    Date  using the  same values as  described above.   Extracted  using
    date_time_value/3.

ttiimmee((_H_,_M_n_,_S))
    Time  using the  same values as  described above.   Extracted  using
    date_time_value/3.


44..3333..11..22 TTiimmee aanndd ddaattee pprreeddiiccaatteess


ggeett__ttiimmee((_-_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.


ssttaammpp__ddaattee__ttiimmee((_+_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.


ddaattee__ttiimmee__ssttaammpp((_+_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)__________________________________________ ||


ddaattee__ttiimmee__vvaalluuee((_?_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:

       ______________________________________________________________kkeeyyvvaalluuee
       ____________________________________________________________________________________________________________________________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)____________________________


ffoorrmmaatt__ttiimmee((_+_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.  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.  Required  to  emit
         RFC822-conforming dates (using "%a, %d %b %Y %H:%M:%S %z").

      Z  The time zone or name or abbreviation.

      +  The date and time in date(1) format.

      %  A literal `%' character.


ffoorrmmaatt__ttiimmee((_+_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.


ppaarrssee__ttiimmee((_+_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.


ppaarrssee__ttiimmee((_+_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.

                  _________________________________________
                  |__NNaammee________||EExxaammppllee______________________________________________||
                  ||_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______________________|


ddaayy__ooff__tthhee__wweeeekk((_+_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.


44..3333..22 CCoonnttrroolllliinngg tthhee swipl-win.exe ccoonnssoollee wwiinnddooww

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.


wwiinnddooww__ttiittllee((_-_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.


wwiinn__wwiinnddooww__ppooss((_+_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.

    ssiizzee((_W_, _H))
         Change the  size of  the window.    _W  and _H  are expressed  in
         character-units.

    ppoossiittiioonn((_X_, _Y))
         Change the  top-left corner  of  the window.    The values  are
         expressed in pixel units.

    zzoorrddeerr((_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.

    sshhooww((_B_o_o_l))
         If true, show the window, if false hide the window.

    aaccttiivvaattee
         If present, activate the window.


wwiinn__hhaass__mmeennuu
    True if win_insert_menu/2 and win_insert_menu_item/4are present.


wwiinn__iinnsseerrtt__mmeennuu((_+_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')__________________________ ||


wwiinn__iinnsseerrtt__mmeennuu__iitteemm((_+_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.


44..3344 FFiillee SSyysstteemm IInntteerraaccttiioonn


aacccceessss__ffiillee((_+_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.


eexxiissttss__ffiillee((_+_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.


ffiillee__ddiirreeccttoorryy__nnaammee((_+_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 ..


ffiillee__bbaassee__nnaammee((_+_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.


ssaammee__ffiillee((_+_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).


eexxiissttss__ddiirreeccttoorryy((_+_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.


ddeelleettee__ffiillee((_+_F_i_l_e))
    Remove _F_i_l_e from the file system.


rreennaammee__ffiillee((_+_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).


ssiizzee__ffiillee((_+_F_i_l_e_, _-_S_i_z_e))
    Unify _S_i_z_e with the size of _F_i_l_e in bytes.


ttiimmee__ffiillee((_+_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.


aabbssoolluuttee__ffiillee__nnaammee((_+_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.


aabbssoolluuttee__ffiillee__nnaammee((_+_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:

    eexxtteennssiioonnss((_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.

    rreellaattiivvee__ttoo((_+_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.

    aacccceessss((_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.

    ffiillee__ttyyppee((_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.

    ffiillee__eerrrroorrss((_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.

    ssoolluuttiioonnss((_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.

    eexxppaanndd((_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.


iiss__aabbssoolluuttee__ffiillee__nnaammee((_+_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.


ffiillee__nnaammee__eexxtteennssiioonn((_?_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.


ddiirreeccttoorryy__ffiilleess((_+_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.


eexxppaanndd__ffiillee__nnaammee((_+_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  does 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..


pprroolloogg__ttoo__ooss__ffiilleennaammee((_?_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.


rreeaadd__lliinnkk((_+_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.


ttmmpp__ffiillee((_+_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.


ttmmpp__ffiillee__ssttrreeaamm((_+_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.


mmaakkee__ddiirreeccttoorryy((_+_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).


ddeelleettee__ddiirreeccttoorryy((_+_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.


wwoorrkkiinngg__ddiirreeccttoorryy((_-_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.


cchhddiirr((_+_P_a_t_h))
    Compatibility predicate.  New code should use working_directory/2.


44..3355 UUsseerr TToopp--lleevveell MMaanniippuullaattiioonn


bbrreeaakk
    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).


aabboorrtt
    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_______________________________________________ ||


hhaalltt                                                              _[_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).


hhaalltt((_+_S_t_a_t_u_s))                                                     _[_I_S_O_]
    Terminate  Prolog  execution  with  given  status.    Status  is  an
    integer.  See also halt/0.


pprroolloogg
    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.


eexxppaanndd__qquueerryy((_+_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.


eexxppaanndd__aannsswweerr((_+_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.


44..3366 CCrreeaattiinngg aa PPrroottooccooll ooff tthhee UUsseerr IInntteerraaccttiioonn

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.


pprroottooccooll((_+_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.


pprroottooccoollaa((_+_F_i_l_e))
    Equivalent  to protocol/1,  but  does not  truncate the  _F_i_l_e if  it
    exists.


nnoopprroottooccooll
    Stop  making a protocol of the user interaction.  Pending  output is
    flushed on the file.


pprroottooccoolllliinngg((_-_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.


44..3377 DDeebbuuggggiinngg aanndd TTrraacciinngg PPrrooggrraammss

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.


ttrraaccee
    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'.


ttrraacciinngg
    True  if the tracer is currently switched on.  tracing/0  itself can
    not be seen in the tracer.


nnoottrraaccee
    Stop the tracer.  notrace/0 itself cannot be seen in the tracer.


gguuiittrraacceerr
    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.


nnoogguuiittrraacceerr
    Reverts back to the textual tracer.


ttrraaccee((_+_P_r_e_d))
    Equivalent to trace(_P_r_e_d, +all).


ttrraaccee((_+_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.


nnoottrraaccee((_:_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.


ddeebbuugg
    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.


nnooddeebbuugg
    Stop  debugger.   Implemented by the  Prolog flag debug.   See  also
    debug/0.


ddeebbuuggggiinngg
    Print  debug status and  spy points on current  output stream.   See
    also the Prolog flag debug.


ssppyy((_+_P_r_e_d))
    Put  a spy point on all predicates meeting the  predicate specifica-
    tion _P_r_e_d.  See section 4.4.


nnoossppyy((_+_P_r_e_d))
    Remove   spy  point  from  all  predicates  meeting   the  predicate
    specification _P_r_e_d.


nnoossppyyaallll
    Remove all spy points from the entire program.


lleeaasshh((_?_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.


vviissiibbllee((_+_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.


uunnkknnoowwnn((_-_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.


ssttyyllee__cchheecckk((_+_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.________________|


44..3388 OObbttaaiinniinngg RRuunnttiimmee SSttaattiissttiiccss


ssttaattiissttiiccss((_+_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 ]      |
| 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


ssttaattiissttiiccss
    Display a table of system statistics on the current output stream.


ttiimmee((_:_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.


44..3399 EExxeeccuuttiioonn pprrooffiilliinngg

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.


44..3399..11 PPrrooffiilliinngg pprreeddiiccaatteess

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.


pprrooffiillee((_:_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.


pprrooffiillee((_:_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.


sshhooww__pprrooffiillee((_+_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.


sshhooww__pprrooffiillee((_+_N_u_m_b_e_r))
    Compatibility.  Same as show_profile(_p_l_a_i_n_, _N_u_m_b_e_r).


pprrooffiilleerr((_-_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.


rreesseett__pprrooffiilleerr
    Switches the profiler to false and clears all collected statistics.


nnoopprrooffiillee((_+_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.


44..3399..22 VViissuuaalliizziinngg pprrooffiilliinngg ddaattaa

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.


44..3399..33 IInnffoorrmmaattiioonn ggaatthheerriinngg

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.


44..3399..33..11 PPrrooffiilliinngg iinn tthhee WWiinnddoowwss IImmpplleemmeennttaattiioonn

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.


44..4400 MMeemmoorryy MMaannaaggeemmeenntt


ggaarrbbaaggee__ccoolllleecctt
    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.


ggaarrbbaaggee__ccoolllleecctt__aattoommss
    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.


ttrriimm__ssttaacckkss
    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.


sseett__pprroolloogg__ssttaacckk((_+_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.

    lliimmiitt((_+_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.

    mmiinn__ffrreeee((_+_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.

    ssppaarree((_+_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  nnoott  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.


pprroolloogg__ssttaacckk__pprrooppeerrttyy((_?_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.


44..4411 WWiinnddoowwss DDDDEE iinntteerrffaaccee

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.


44..4411..11 DDDDEE cclliieenntt iinntteerrffaaccee

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.


ooppeenn__ddddee__ccoonnvveerrssaattiioonn((_+_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.


cclloossee__ddddee__ccoonnvveerrssaattiioonn((_+_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.


ddddee__rreeqquueesstt((_+_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.


ddddee__eexxeeccuuttee((_+_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.


ddddee__ppookkee((_+_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.


44..4411..22 DDDDEE sseerrvveerr mmooddee

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

ddddee__rreeggiisstteerr__sseerrvviiccee((_+_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.


ddddee__uunnrreeggiisstteerr__sseerrvviiccee((_+_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.


ddddee__ccuurrrreenntt__sseerrvviiccee((_-_S_e_r_v_i_c_e_, _-_T_o_p_i_c))
    Find currently registered services and the topics served on them.


ddddee__ccuurrrreenntt__ccoonnnneeccttiioonn((_-_S_e_r_v_i_c_e_, _-_T_o_p_i_c))
    Find currently open conversations.


44..4422 MMiisscceellllaanneeoouuss


ddwwiimm__mmaattcchh((_+_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)


ddwwiimm__mmaattcchh((_+_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.


wwiillddccaarrdd__mmaattcchh((_+_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_______________________________________________________________ ||


sslleeeepp((_+_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 aatt lleeaasstt _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.


CChhaapptteerr 55..  MMOODDUULLEESS

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.


55..11 WWhhyy UUssiinngg MMoodduulleess??

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.


55..22 DDeeffiinniinngg aa MMoodduullee

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.


::-- mmoodduullee((_+_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.


55..33 IImmppoorrttiinngg PPrreeddiiccaatteess iinnttoo aa MMoodduullee

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.


uussee__mmoodduullee((_+_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.


uussee__mmoodduullee((_+_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.


55..44 DDeeffiinniinngg aa mmeettaa--pprreeddiiccaattee

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

mmeettaa__pprreeddiiccaattee _+_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.

    00....99
         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.


55..55 OOvveerrrruulliinngg MMoodduullee BBoouunnddaarriieess

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

55..66 IInntteerraaccttiinngg wwiitthh mmoodduulleess ffrroomm tthhee ttoopplleevveell

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:


mmoodduullee((_+_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).                                |
    ||..._______________________________________________________________ ||


55..77 CCoommppoossiinngg mmoodduulleess ffrroomm ootthheerr mmoodduulleess

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

rreeeexxppoorrtt((_+_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.


rreeeexxppoorrtt((_+_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.


55..88 OOppeerraattoorrss aanndd mmoodduulleess

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,                                                    |
|            ...                                                         |
||_________]).__________________________________________________________ ||


55..99 DDyynnaammiicc iimmppoorrttiinngg uussiinngg iimmppoorrtt mmoodduulleess

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:


sseett__bbaassee__mmoodduullee((_:_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.


iimmppoorrtt__mmoodduullee((_+_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.


aadddd__iimmppoorrtt__mmoodduullee((_+_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.


ddeelleettee__iimmppoorrtt__mmoodduullee((_+_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.


55..1100 RReesseerrvveedd MMoodduulleess aanndd uussiinngg tthhee ``uusseerr'' mmoodduullee

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.


55..1111 AAnn aalltteerrnnaattiivvee iimmppoorrtt//eexxppoorrtt iinntteerrffaaccee

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.


eexxppoorrtt((_+_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.


iimmppoorrtt((_+_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.


55..1122 DDyynnaammiicc MMoodduulleess

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

55..1133 TTrraannssppaarreenntt pprreeddiiccaatteess::  ddeeffiinniittiioonn aanndd ccoonntteexxtt mmoodduullee

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:


::-- mmoodduullee__ttrraannssppaarreenntt((_+_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.


ccoonntteexxtt__mmoodduullee((_-_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.


ssttrriipp__mmoodduullee((_+_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.


55..1144 QQuueerryy tthhee mmoodduullee ssyysstteemm

The following  predicates can  be used  to query the  module system  for
reflexive programming:


ccuurrrreenntt__mmoodduullee((_?_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.


mmoodduullee__pprrooppeerrttyy((_?_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:

    ffiillee((_?_F_i_l_e))
         True if _M_o_d_u_l_e was loaded from _F_i_l_e.

    lliinnee__ccoouunntt((_-_L_i_n_e))
         True if _M_o_d_u_l_e was loaded from the N-th line of file.

    eexxppoorrttss((_-_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.


55..1155 CCoommppaattiibbiilliittyy ooff tthhee MMoodduullee SSyysstteemm

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

CChhaapptteerr 66..  SSPPEECCIIAALL VVAARRIIAABBLLEESS AANNDD CCOORROOUUTTIINNIINNGG

This  chapter  deals  with  extensions  primarily  designed  to  support
constraint logic programming (CLP).


66..11 AAttttrriibbuutteedd vvaarriiaabblleess

_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  little  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].

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.


aattttvvaarr((_@_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.


ppuutt__aattttrr((_+_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.


ggeett__aattttrr((_+_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.


ddeell__aattttrr((_+_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.


aattttrr__uunniiffyy__hhooookk((_+_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.


aattttrr__ppoorrttrraayy__hhooookk((_+_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.


aattttrriibbuuttee__ggooaallss((_+_V_a_r_, _-_G_s_, _+_G_s_R_e_s_t))
    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.


66..11..11 SSppeecciiaall ppuurrppoossee pprreeddiiccaatteess ffoorr aattttrriibbuutteess

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.


ggeett__aattttrrss((_+_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.


ppuutt__aattttrrss((_+_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.


ddeell__aattttrrss((_+_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.


tteerrmm__aattttvvaarrss((_+_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.   It  should be  noted
    that  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.


ccooppyy__tteerrmm((_+_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.


ccooppyy__tteerrmm__nnaatt((_+_T_e_r_m_, _-_C_o_p_y))
    As copy_term/2.  Attributes however, are _n_o_t  copied but replaced by
    fresh variables.


66..22 CCoorroouuttiinniinngg

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

ffrreeeezzee((_+_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.


ffrroozzeenn((_@_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.


wwhheenn((_@_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.


ddiiff((_@_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.


ccaallll__rreessiidduuee__vvaarrss((_:_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.


66..33 GGlloobbaall vvaarriiaabblleess

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.


bb__sseettvvaall((_+_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.


bb__ggeettvvaall((_+_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.


nnbb__sseettvvaall((_+_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.


nnbb__ggeettvvaall((_+_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.


nnbb__lliinnkkvvaall((_+_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)                                             |
    ||________).________________________________________________________ ||


nnbb__ccuurrrreenntt((_?_N_a_m_e_, _?_V_a_l_u_e))
    Enumerate  all defined  variables with their  value.   The order  of
    enumeration is undefined.


nnbb__ddeelleettee((_+_N_a_m_e))
    Delete the named global variable.


66..33..11 CCoommppaattiibbiilliittyy ooff SSWWII--PPrroolloogg GGlloobbaall VVaarriiaabblleess

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.


CChhaapptteerr 77..  CCHHRR:: CCOONNSSTTRRAAIINNTT HHAANNDDLLIINNGG RRUULLEESS

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.


77..11 IInnttrroodduuccttiioonn

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.


77..22 SSyynnttaaxx aanndd SSeemmaannttiiccss


77..22..11 SSyynnttaaxx

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.


77..22..22 SSeemmaannttiiccss

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.

RRuullee TTyyppeess 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.

RRuullee NNaammeess

Naming  a rule  is optional  and has  no semantical  meaning.   It  only
functions as documentation for the programmer.

PPrraaggmmaass The semantics of the pragmas are:

ppaassssiivvee((_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.


::-- cchhrr__ooppttiioonn((_+_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:

    cchheecckk__gguuaarrdd__bbiinnddiinnggss
         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.

    ooppttiimmiizzee
         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.

    ddeebbuugg
         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.


77..33 CCHHRR iinn SSWWII--PPrroolloogg PPrrooggrraammss


77..33..11 EEmmbbeeddddiinngg iinn PPrroolloogg PPrrooggrraammss

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.


77..33..22 CCoonnssttrraaiinntt ddeeccllaarraattiioonn


::-- cchhrr__ccoonnssttrraaiinntt((_+_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))._______________________ ||

MMooddeess

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.

TTyyppeess

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:

iinntt
    The corresponding argument  of every occurrence of the constraint is
    an integer number.

ddeennssee__iinntt
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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.


77..33..33 CCoommppiillaattiioonn

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,ises a  t
    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.

ffllooaatt
    ...a floating point number.

nnuummbbeerr
    ...a number.

nnaattuurraall
    ...a positive integer.

aannyy
    The  corresponding argument  of every occurrence  of the  constraint
    can have any type.  This is the default value.


::-- cchhrr__ttyyppee((_+_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))._______________________________ ||

TTyyppee CChheecckkiinngg

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