
                                              University of Amsterdam

                                                 Dept.  of Social
                                                Science Informatics

                                                       (SWI)
                                               Roeterstraat 15, 1018
                                                   WB  Amsterdam
                                                  The Netherlands
                                              Tel.  (+31) 20 5256121

                         SSWWII--PPrroolloogg 55..22
                        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_._2_._1_1_, _N_o_v_e_m_b_e_r _2_0_0_3

                         _J_a_n _W_i_e_l_e_m_a_k_e_r
                       jan@swi.psy.uva.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.   Compat-
ibility,  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{2003,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  restricted  form  of the  WAM  (Warren
Abstract Machine) described  in [Bowen & Byrd, 1983] which defines  only
7  instructions.   Prolog  can  easily be  compiled into  this  language
and the  abstract machine code  is easily  decompiled back into  Prolog.
As  it is  also  possible to  wire a  standard  4-port debugger  in  the
WAM interpreter  there is  no need  for a  distinction between  compiled
and interpreted  code.   Besides  simplifying the design  of the  Prolog
system  itself this  approach has  advantages  for program  development:
the  compiler is  simple and  fast, the  user  does not  have to  decide
in  advance whether  debugging  is required  and  the system  only  runs
slightly  slower when  in debug  mode.   The  price we  have  to pay  is
some  performance degradation  (taking  out the  debugger from  the  WAM
interpreter improves performance  by about 20%) and somewhat  additional
memory usage to help the decompiler and debugger.

SWI-Prolog  extends  the  minimal  set  of   instructions  described  in
[Bowen & Byrd, 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  [OKeefe, 1990].     Syntax   and
standard  operator declarations  confirm  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 [??].


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

This manual describes  version 5.2 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 we experienced  rather
obvious and  critical bugs can  remain unnoticed  for a remarkable  long
period, we assume  the basic Prolog system is  fairly stable.  Bugs  can
be expected in infrequently used built-in predicates.

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

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  7.  It can  also be _e_m_b_e_d_d_e_d embedded in external  programs
    (see  section 7.7).  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  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.


11..66..11 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.


11..66..22 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.

  o _`_A_n_s_w_e_r_' _r_e_u_s_e
    The  toplevel maintains  a table  of bindings  returned by  toplevel
    goals  and  allows for  reuse  of these  bindings by  prefixing  the
    variables with the $ sign.  See 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.


11..66..33 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.


11..66..44 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
to 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.


11..66..55 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.


11..66..66 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.


11..66..77 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.


11..66..88 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.


11..66..99 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].


11..66..1100 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.


11..66..1111 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 descriped  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.13.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 7.6.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 6.


11..66..1111..11 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 atom_chars/2
    This  predicate  is now  ISO  compliant and  thus generates  a  list
    of  one-character atoms.    The behaviour  of the  old predicate  is
    available  in the  ---also ISO compliant---  atom_codes/2 predicate.
    Safest  repair is a  replacement of all  atom_chars  into atom_codes.
    If you do not want to change any souce-code, you might want to use

    user:goal_expansion(atom_chars(A,B), atom_codes(A,B)).

  o number_chars/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
    feature/2 and set_feature/2, so no source hhaass to 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 dup_stream/2
    Has  been deleted.   New  stream-aliases can deal  with most of  the
    problems  for which  dup_stream/2 was  designed and  dup/2 from  the
    _c_l_i_b package can with most others.

  o op/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 current_stream/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.


11..66..1122 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   explicitely   or   by   calling
    check_old_select/0.


11..66..1133 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 forntend.

  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.


11..66..1144 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 phylosophy,  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


11..66..1155 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 6.   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.


11..66..1166 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.


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

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 `pl',  though some administrators
call  it  `swipl'  or `swi-prolog'.     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% pl
Welcome to SWI-Prolog (Version 5.2.0)
Copyright (c) 1990-2003 University of Amsterdam.
SWI-Prolog comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to redistribute it under certain conditions.
Please visit http://www.swi-prolog.org for details.

For help, use ?- help(Topic). or ?- apropos(Word).

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  plwin.exe,  providing  a  window  for  interaction  with
    Prolog.  The  program plcon.exe is a version of SWI-Prolog that runs
    in a DOS-box.

  o The  file-extension .pl  is associated with  the program  plwin.exe.
    Opening  a .pl file will cause plwin.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.

     _______________________________________________________________
     |________________|UUnniixx__||WWiinnddoowwss________________________________________________________________________________||
     || llooccaall  ||.    |.                                              |

     | hhoommee   ||~    |%HOME% or %HOMEDRIVE%\%HOMEPATH%               |
     |_global_|____|SWI-Home_directory_or_%WINDIR%_or_%SYSTEMROOT%_|_

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.


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

machine% pl -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 toplevel---
exit  after completing  go/0.    The  -q  may  be used  to  supress  all
informational messages.

In  MS-Windows,  the  same  can  be  achieved  using  a  short-cut  with
appropriately  defined  commandline   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  8
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:

--hheellpp
    When  given as  the only  option, it summarises  the most  important
    options.

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

--aarrcchh
    When   given  as  the  only  option,  it  prints   the  architecture
    identifier  (see  current_prolog_flag(arch,  Arch)) and  exits.    See
    also -dump-runtime-variables.

--dduummpp--rruunnttiimmee--vvaarriiaabblleess
    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 plld (see section  7.7).
    Below is a typical example of using this feature.

    eval `pl -dump-runtime-variables`
    cc -I$PLBASE/include -L$PLBASE/runtime/$PLARCH ...

--qq
    Set the prolog-flag  verbose to silent, supressing informational and
    banner messages.

--LL_s_i_z_e_[_k_m_]
    Give  local stack limit (2 Mbytes default).   Note that there  is no
    space  between the size option  and its argument.   By default,  the
    argument  is interpreted in  Kbytes.   Postfixing the argument  with
    m  causes the argument to be  interpreted in Mbytes.  The  following
    example specifies 32 Mbytes local stack.

    % pl -L32m

    A maximum is  useful to stop buggy programs from claiming all memory
    resources.   -L0 sets the limit to the highest possible value.   See
    section 2.16.

--GG_s_i_z_e_[_k_m_]
    Give  global  stack limit  (4 Mbytes  default).    See -L  for  more
    details.

--TT_s_i_z_e_[_k_m_]
    Give  trail  stack  limit  (4  Mbytes  default).     This  limit  is
    relatively  high because trail-stack overflows are not  often caused
    by program bugs.  See -L for more details.

--AA_s_i_z_e_[_k_m_]
    Give  argument stack limit (1 Mbytes  default).  The argument  stack
    limits  the  maximum  nesting of  terms  that  can be  compiled  and
    executed.    SWI-Prolog does `last-argument  optimisation' to  avoid
    many  deeply nested  structure  using this  stack.   Enlarging  this
    limit is only necessary in extreme cases.  See -L for more details.

--cc _f_i_l_e _._._.
    Compile files into an `intermediate code file'.  See section 2.10.

--oo _o_u_t_p_u_t
    Used  in combination  with -c  or -b  to determine  output file  for
    compilation.

--OO
    Optimised compilation.  See current_prolog_flag/2.

--s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 _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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.

--g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  thus be suppressed by  giving -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 Unix shell.

--tt _g_o_a_l
    Use  _g_o_a_l  as  interactive  toplevel instead  of  the  default  goal
    prolog/0.    _g_o_a_l  can be  a complex  term.   If  the toplevel  goal
    succeeds  SWI-Prolog exits  with status  0.   If it  fails the  exit
    status  is  1.    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 toplevel.

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

--nnoossiiggnnaallss
    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 7.6.18.1 for defails.

--x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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-seperator 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.

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

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

--b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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 "pl")
(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.
An  alternative  prolog.el  file for  GNU-Emacs  20  is  available  from
http://www.freesoft.cz/ pdm/software/emacs/prolog-mode/  and  for   GNU-
Emacs 19 from http://w1.858.telia.com/ u85810764/Prolog-mode/index.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  will
    try to explain the predicate as well as possible references to it.


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 QQuueerryy SSuubbssttiittuuttiioonnss

SWI-Prolog  offers a  query substitution  mechanism similar  to that  of
Unix csh (csh(1)), 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.   It also allows to  correct
queries and  syntax errors.    SWI-Prolog does  not offer  the Unix  csh
capabilities to  include arguments.   This is omitted  as it is  unclear
how the first, second, etc. argument should be defined.

The available history commands are shown in table 2.1.
       __________________________________________________________
       | !!.            |Repeat last query                        |

       | !nr.           |Repeat query numbered <_n_r>               |
       | !str.          |Repeat last query starting with <_s_t_r>    |
       | !?str.         |Repeat last query holding <_s_t_r>          |
       | ^old^new.      |Substitute <_o_l_d> into <_n_e_w> in last query |
       | !nr^old^new.   |Substitute in query numbered <_n_r>        |
       | !str^old^new.  |Substitute in query starting with <_s_t_r>  |
       | !?str^old^new. |Substitute in query holding <_s_t_r>        |
       | h.             |Show history list                        |

       |_!h.____________|Show_this_list__________________________ |

                      Table 2.1:  History commands


22..77..11 LLiimmiittaattiioonnss ooff tthhee HHiissttoorryy SSyysstteemm

History expansion  is executed  after _r_a_w_-_r_e_a_d_i_n_g.   This  is the  first
stage of read_term/2 and friends,  reading the term into a  string while
deleting comment  and canonising blank.   This makes  it hard to use  it
for correcting  syntax errors.   Command-line editing as provided  using
the GNU-readline library is  more suitable for this.   History expansion
is first  of all useful  for executing or  combining commands from  long
ago.


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

Bindings resulting from the successful execution of a  toplevel goal are
asserted in a database.  These values may be  reused in further toplevel
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 toplevel 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  tracer
[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  toplevel 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.
1 ?- visible(+all), leash(-exit).

Yes
2 ?- trace, min([3, 2], X).
  Call:  ( 3) min([3, 2], G235) ? creep
  Unify: ( 3) min([3, 2], G235)
  Call:  ( 4) min([2], G244) ? creep
  Unify: ( 4) min([2], 2)
  Exit:  ( 4) min([2], 2)

  Call:  ( 4) min(3, 2, G235) ? creep
  Unify: ( 4) min(3, 2, G235)
  Call:  ( 5) 3 < 2 ? creep
  Fail:  ( 5) 3 < 2 ? creep
  Redo:  ( 4) min(3, 2, G235) ? creep
  Exit:  ( 4) min(3, 2, 2)
  Exit:  ( 3) min([3, 2], 2)

Yes
[trace] 3 ?-

                       Figure 2.2:  Example trace

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),
    portray(true), max_depth(10)].  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)],
    bypassing portray/1, etc.

The   ideal  4   port  model   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, tail  recursion optimisation  is
switched off.

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

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:

% pl
<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  plwin.exe to  be started  in the  directory
holding load.pl.  Prolog loads load.pl before entering the toplevel.


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 then  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  plld(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 8.


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dl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:

% pl [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

% pl --goal=main --stand_alone=true -o myprog -c load.pl

This performs exactly the same as executing

% pl
<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))
    The   predicate  current_prolog_flag/2  defines   an  interface   to
    installation   features:    options  compiled  in,  version,   home,
    etc.    With both arguments  unbound, it  will generate all  defined
    prolog-flags.    With  the  `Key' instantiated  it unify  the  value
    of  the  prolog-flag.    Features  come  in three  types:    boolean
    prolog-flags,  prolog-flags  with  an  atom value  and  prolog-flags
    with  an integer  value.    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.   Currently
    defined keys in alphabetical order:

    aabboorrtt__wwiitthh__eexxcceeppttiioonn _(_b_o_o_l_, _c_h_a_n_g_e_a_b_l_e_)
         Determines how  abort/0 is realised.    See the description  of
         abort/0 for details.

    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
         arguments 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 7.4 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
         (e.g. pl or pro associated with plwin.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.
         See section 2.13.

    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
         backquotes into a string object (see section 4.23).   This flag
         is mainly for compatibility to LPA Prolog.

    bboouunnddeedd _(_t_r_u_e_)
         ISO prolog-flag describing  integer representation is bound  by
         min_integer and min_integer.

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

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

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

    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 plwin.exe  to  indicate the  console  supports
         menus.  See also section 4.35.2.

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

    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,  tail-recursion
         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)].

    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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-quotes  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.23).
         See also atom_chars/2 and atom_codes/2.

    ddyynnaammiicc__ssttaacckkss _(_b_o_o_l_)
         If true,  the system uses some  form of `sparse-memory  manage-
         ment' to realise the stacks.  If  false, malloc()/realloc() are
         used for  the stacks.   In earlier  days this had  consequenses
         for foreign code.   As  of version 2.5,  this is no longer  the
         case.

         Systems using  `sparse-memory management' are  a bit faster  as
         there is no  stack-shifter, and checking the stack-boundary  is
         often realised  by the hardware  using a  `guard-page'.   Also,
         memory  is actually  returned to  the  system after  a  garbage
         collection or call  to trim_stacks/0 (called by prolog/0  after
         finishing a user-query).

    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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   $varname  and   ~   in
         arguments  of  builtin-predicates  that  accept  a   file  name
         (open/3, exists_file/1,  access_file/2,  etc.).   The  predicate
         expand_file_name/2  should  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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  commandline editor.   The default  is to set  this
         prolog-flag  to 0  if a  commandline  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  it's  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 plwin.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  to
         normal SWI-Prolog behaviour.   Currently  it has the  following
         effect:

           o is/2  and  evaluation  under flag/3  do  not  automatically
             convert  floats  to integers  if  the float  represents  an
             integer.

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

    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.     Most  arithmetic  operations  will
         automatically convert  to floats if  integer values above  this
         are returned.

    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  4-bytes storage  and are  used for  indexing.
         Larger integers are represented as `indirect data'  and require
         16-bytes  on  the  stacks  (though  a  copy   requires  only  4
         additional bytes).

    mmiinn__iinntteeggeerr _(_i_n_t_e_g_e_r_)
         Minimum integer value.

    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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 commandline 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 dependent.

    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.

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

    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  plwin.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_error prolog-flag.   Default
         is true, except for the runtime version.

    rruunnttiimmee _(_b_o_o_l_)
         If 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  true,   Prolog  is   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siiggnnaallss _(_b_o_o_l_)
         Determine  whether   Prolog  is   handling  signals   (software
         interrupts).   This flag is  false if the  hosting OS does  not
         support signal handling  or the command-line option  -nosignals
         is active.  See section 7.6.18.1 for details.

    ssyysstteemm__tthhrreeaadd__iidd _(_i_n_t_)
         On MT systems (section 6, refers to  the thread-identifier used
         by the system for the calling thread.  See also thread_self/1.

    ttaaiill__rreeccuurrssiioonn__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  tail-recursion   optimisation  is
         enabled.     Normally the  value  of  this  flag  is  equal  to
         the  debug  flag.      As  programs   may  run  out  of   stack
         if  tail-recursion optimisation  is  omitted, it  is  sometimes
         necessary to enable it during debugging.

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

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

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

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

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

    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 supressed.   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__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.

    wwiinnddoowwss _(_b_o_o_l_)
         If  true,   the  operating  system  is  an  implementation   of
         Microsoft Windows (3.1, 95/98/ME, NT/2000/XP, etc.).

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

    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.


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 portray/1
    Hook into write_term/3 to alter the way terms are printed (ISO).

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

  o library_directory/1
    Hook  into absolute_file_name/3 to define  new library  directories.
    (most Prolog system).

  o file_search_path/2
    Hook   into   absolute_file_name/3  to   define   new   search-paths
    (Quintus/SICStus).

  o term_expansion/2
    Hook  into  load_files/1  to  modify  read  terms  before  they  are
    compiled (macro-processing) (most Prolog system).

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

  o prolog_load_file/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 prolog_edit:locate/3
    Hook into edit/1 to locate objects (SWI).

  o prolog_edit:edit_source/1
    Hook into edit/1 to call some internal editor (SWI).

  o prolog_edit:edit_command/2
    Hook into edit/1 to define the external editor to use (SWI).

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

  o prolog_trace_interception/4
    Hook into the tracer to handle trace-events (SWI).

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

  o prolog:help_hook/1
    Hook in help/0, help/1 and apropos/1 to extend the help-system.

  o resource/3
    Defines a new resource (not really a hook, but similar) (SWI).

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

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 and  file_search_path/2).     If  the
undefined predicate  can be  located in  the 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 entire auto load system.

The auto-loader only  works if the unknown  flag (see unknown/2) is  set
to  trace (default).    A more  appropriate interaction  with this  flag
should be considered.

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 !$
% pl -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/2,
    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  standard `Edinburgh'  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 0'<_c_h_a_r>
    This  construct is not accepted by all Prolog systems that  claim to
    have  Edinburgh compatible syntax.  It describes the  character code
    of <_c_h_a_r>.   To test whether C is a lower case character one can use
    between(0'a, 0'z, C).

  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 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:   '<_a_t_o_m>'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).

\x23
    Hexadecimal  specification of a character.   23 is just an  example.
    The  `x'  may be  followed by  a maximum  of  2 hexadecimal  digits.
    The  closing \  is optional.   The  code \xa\3  emits the  character
    10  (hexadecimal `a')  followed by  `3'.   The code  \x201 emits  32
    (hexadecimal  `20') followed by `1'.  According to ISO,  the closing
    \  is  obligatory and  the  number  of digits  is  unlimited.    The
    SWI-Prolog  definition allows for ISO compatible specification,  but
    is compatible with other implementations.

\40
    Octal   character  specification.     The  rules  and   remarks  for
    hexadecimal  specifications apply to  octal specifications too,  but
    the maximum allowed number of octal digits is 3.

\<_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..22 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>'<_n_u_m_b_e_r>, 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166 SSyysstteemm lliimmiittss


22..1166..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||2Mllooccaa||l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 of  with |             |            ||
       |        |                                                |             |            ||

       |        |                        the  !/0  predicate  or |             |            ||
       |        |                        no  choice points  have |             |            ||
       |        |                        been created  since the |             |            ||
       |        |                        invocation and the last |             |            ||
       |        |                        subclause  is   started |             |            ||
       |        |                        (tail recursion optimi- |             |            ||
       ||       ||      |               ||sation).                ||            |            ||

       |   -G   | 4M    |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   | 4M    |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 |
       ||       ||      ||              ||nor||needed any longer.  ||

       |   -A   | 1M    |aarrgguummeenntt ssttaacckk ||Theusargumentestackd isto|  store   one
       |        |       |               ||of   the   intermediate |
       |        |       |               ||code interpreter's reg- |
       |        |       |               ||isters.     The  amount |
       |        |       |               ||of space needed on this |
       |        |       |               ||stack is determined en- |
       |        |       |               ||                        |
       |        |       |               ||tirely by the  depth in |
       |        |       |               ||which terms  are nested |
       |        |       |               ||in  the   clauses  that |

       |        |       |               ||constitute the program. |
       |        |       |               ||Overflow is most likely |
       |        |       |               ||when using long strings |
       |________|_______|_______________||in_a_clause.____________|_

                        Table 2.2:  Memory areas


22..1166..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166..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 7.6.2.1.

AAddddrreessss ssppaaccee  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.

IInntteeggeerrss  Integers are 32-bit (64 on  64-bit machines) to the user,  but
    integers  up to the value of  the max_tagged_integer prolog-flag  are
    represented more efficiently.

FFllooaattss  Floating  point  numbers  are  represented  as  C-native  double
    precision floats, 64 bit IEEE on most machines.


22..1166..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).


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  ui-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..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 toplevel  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 explictely 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 sequence

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

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.


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.


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

33..77 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_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.


33..88 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 `+',  `-' or  `?'
sign.    `+'  indicates the  argument is  input  to the  predicate,  `-'
denotes output and  `?'  denotes `either  input or output'.   Constructs
like  `op/3' refer  to the  predicate `op'  with arity  `3'.    Finally,
arguments may  have the `:'   specifier, which  implies the argument  is
module-sensitive.  Normally the argument is a _c_a_l_l_a_b_l_e  term refering to
a predicate in  a specific module.   See section 5 for more  information
on module-handing.


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  betweem  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
(see current_prolog_flag/2) 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  a  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 oset.pl  (containing predicates for
manipulating ordered sets).

:- use_module(library(oset)).

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/2.   It  currently supports a  subset
    of  the options of Quintus load_files/2.  _F_i_l_e_s is  either specifies
    a  single,  or a  list of  source-files.   The  specification for  a
    source-file  is handled  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:

    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.

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

    iimmppoorrttss((_L_i_s_t_O_r_A_l_l))
         If  all and  the  file is  a  module file,  import  all  public
         predicates.  Otherwise import only the named predicates.   Each
         predicate is refered to  as <_n_a_m_e>/<_a_r_i_t_y>.  This  option has no
         effect if the file is not a module file.

    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.

    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.

    qqccoommppiillee((_B_o_o_l))
         If this call appears in a directive of a file  that is compiled
         into Quick Load Format using qcompile/1 and this  flag is true,
         the contents  of the argument  files are  included in the  .qlf
         file instead of the loading directive.

    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.

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

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

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

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.  It  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  may  wish to  change  the extension  used for  Prolog  source
    files  to avoid  conflicts (for  example with  perl) as  well as  to
    be  compatible with  some specific  implementation.   The  preferred
    alternative extension is .pro.


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

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))
    Determine loading context.  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               |
      | file          |File loaded                                    |
      | stream        |Stream identifier (see current_input/1)        |

      | directory     |Directory in which _F_i_l_e lives.                 |
      | term_position |Position of last  term read.  Term of  the form|
      |_______________|'$stream_position'(0,<_L_i_n_e>,0,0,0)_____________|

    Quintus compatibility predicate.  See also source_location/2.


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.


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  predicate, normally not defined.  When defined by  the user
    all  terms read during consulting that 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 a  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  to  perform
    preprocessing.   First it calls term_expansion/2.   If this predicate
    fails  it performs  a grammar-rule translation.    If this fails  it
    returns the first argument.


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.

    Only  goals  apearing   in  the  body  of  clauses  when  reading  a
    source-file  are expanded using mechanism,  and only if they  appear
    literally  in the clause, or  as an argument to the  meta-predicates
    not/1,  call/1,  once/1, ignore/1,  findall/3,  bagof/3, setof/3  or
    forall/2.    A real predicate  definition is  required to deal  with
    dynamically constructed calls.


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.   First it calls goal_expansion/2.  If this  fails it
    returns the first argument.


aatt__iinniittiiaalliizzaattiioonn((_+_G_o_a_l))
    Register   _G_o_a_l   to   be   run   when   the   system   initialises.
    Initialisation  takes place after  reloading a .qlf (formerly  .wic)
    file  as well as after reloading a  saved-state.  The hooks  are run
    in  the order they were registered.  A warning message is  issued if
    _G_o_a_l fails, but execution continues.  See also at_halt/1


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))
    Call  _G_o_a_l and  register it using  at_initialization/1.   Directives
    that  do  other things  than  creating clauses,  records,  flags  or
    setting  predicate attributes should normally be written  using this
    tag  to ensure the  initialisation is executed  when a saved  system
    starts.  See also qsave_program/[1,2].


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

pprreepprroocceessssoorr((_-_O_l_d_, _+_N_e_w))
    Read  the input file via a  Unix 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  resulting atom  is called as  a Unix  command and the  standard
    output  of this command is loaded.   To use the Unix  C preprocessor
    one should define:

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

    Old = none


44..33..11 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 single  file specification  like  consult/1 (i.e.,  accepts
    constructs like library(LibFile)  and creates a Quick Load File 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(+File)',   `:- [+File]'   or
    :- load_files(+File, [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.


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/3to  translate _S_p_e_c_i_f_i_c_a_t_i_o_n into
    a  list  of  _L_o_c_a_t_i_o_n_s.    If there  is  more than  one  `hit',  the
    user  is  asked  to select  from  the  locations found.     Finally,
    prolog_edit:edit_source/1 is  used  to invoke  the user's  preferred
    editor.   Typically, edit/1 can  be handed the name of  a predicate,
    module, basename of a file, XPCE class, XPCE method, etc.


eeddiitt
    Edit  the `default'  file using  edit/1.   The default  file is  the
    file loaded with the  commandline 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-sepecified
    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/3for  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>.  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))
    Succeeds if _T_e_r_m currently is a free variable.


nnoonnvvaarr((_+_T_e_r_m))
    Succeeds if _T_e_r_m currently is not a free variable.


iinntteeggeerr((_+_T_e_r_m))
    Succeeds if _T_e_r_m is bound to an integer.


ffllooaatt((_+_T_e_r_m))
    Succeeds if _T_e_r_m is bound to a floating point number.


nnuummbbeerr((_+_T_e_r_m))
    Succeeds if _T_e_r_m is bound to an integer or a floating point number.


aattoomm((_+_T_e_r_m))
    Succeeds if _T_e_r_m is bound to an atom.


ssttrriinngg((_+_T_e_r_m))
    Succeeds if _T_e_r_m is bound to a string.


aattoommiicc((_+_T_e_r_m))
    Succeeds  if _T_e_r_m is bound to  an atom, string, integer or  floating
    point number.


ccoommppoouunndd((_+_T_e_r_m))
    Succeeds  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))
    Succeeds  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))
    Succeeds if _T_e_r_m holds no free variables.


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orr TTeerrmmss


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 <_A_t_o_m_s <_S_t_r_i_n_g_s <_N_u_m_b_e_r_s <_T_e_r_m_s

 2. _O_l_d _V_a_r_i_a_b_l_e <_N_e_w _V_a_r_i_a_b_l_e

 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.   Integers  and floats are  treated
    identically.

 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.

If  the  prolog_flag  (see  current_prolog_flag/2)  iso  is  defined,  all
floating point numbers precede all integers.


_+_T_e_r_m_1 == _+_T_e_r_m_2
    Succeeds  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
    Equivalent to \+Term1 == Term2.


_+_T_e_r_m_1 = _+_T_e_r_m_2
    Unify _T_e_r_m_1 with _T_e_r_m_2.  Succeeds if the unification succeeds.


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

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

_+_T_e_r_m_1 =@= _+_T_e_r_m_2
    Succeeds  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


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

_+_T_e_r_m_1 @< _+_T_e_r_m_2
    Succeeds 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
    Succeeds 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
    Succeeds 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
    Succeeds  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..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
these constructs  are translated  into virtual  machine instructions  by
the compiler.   It is still  necessary to implement these constructs  as
true predicates  to support meta-calls,  as demonstrated in the  example
below.  The  predicate finds all currently defined atoms of  1 character
long.   Note that  the cut has no  effect when called  via one of  these
predicates (see !/0).

one_character_atoms(As) :-
        findall(A, (current_atom(A), atom_length(A, 1)), As).


ffaaiill
    Always  fail.   The  predicate fail/0  is translated  into a  single
    virtual machine instruction.


ttrruuee
    Always  succeed.  The predicate  true/0 is translated into a  single
    virtual machine instruction.


rreeppeeaatt
    Always succeed, provide an infinite number of choice points.


!
    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
    Conjunction.   Succeeds 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
    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
    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 choicepoint 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 branche,  is translated
    as the normal conjunction _A, _B.


\+ _+_G_o_a_l
    Succeeds  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))
    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/3, 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 true  predicates, so they can be  handled
    by interpreted code.


aappppllyy((_+_T_e_r_m_, _+_L_i_s_t))
    Append  the members of  _L_i_s_t to the arguments  of _T_e_r_m 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))
    Succeeds  when _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))
    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/3 may  still loop  inifitly  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_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.


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))
    Calls   _G_o_a_l.      If  _G_o_a_l  is  completely   finished,  either   by
    deterministic  success,   failure,  its  choicepoint  being  cut  or
    raising  an exception  and _C_a_t_c_h_e_r unifies  to the termination  code
    (see  below), _C_l_e_a_n_u_p  is called.    Success or  failure of  _C_l_e_a_n_u_p
    is  ignored and possibly choicepoints  it created are destroyed  (as
    once/1).    If  cleanup  throws an  exception  this is  executed  as
    normal.

    _C_a_t_c_h_e_r  is  unified  with  a  term  describing  how  the  call  has
    finished.  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 choicepoints.

    ffaaiill
         _G_o_a_l failed.

    !
         _G_o_a_l succeeded  with choicepoints and  these are now  discarded
         by the  execution of  a cut (or  orther 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.

    Typical  use of this predicate is cleanup of 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) :-
            open(File, read, In),
            call_cleanup(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  this  predicate is  impossible  to implement  in  Prolog
    other  then reading all terms into  a list, close the file  and call
    member/2  because without  call_cleanup/3 there  is no  way to  gain
    control if the choicepoint left by repeat is killed by a cut.

    This  predicate is a SWI-Prolog extension.   See also call_cleanup/2
    for compatibility to other Prolog implementations.


ccaallll__cclleeaannuupp((_:_G_o_a_l_, _:_C_l_e_a_n_u_p))
    This  predicate  is  equivalent to  call_cleanup(_G_o_a_l_,  ___,  _C_l_e_a_n_u_p),
    calling   _C_l_e_a_n_u_p   regardless  of   the  reason   for   termination
    and  without  providing   information.     This  predicate  provides
    compatibility to a number of other Prolog implementations.


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))
    Behaves  as call/1 if  no exception is  raised when executing  _G_o_a_l.
    If  a 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 choicepoints 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))
    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 aproach  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  7) 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 (see current_prolog_flag/2) debug_on_error
was 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  toplevel
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 toplevel 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.


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

Builtin  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  (see current_prolog_flag/2) 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.

    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 define  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.23.
    Primarily  intended  to  write  messages to  Windows  in  XPCE  (see
    section 1.5) or other GUI environments.


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

Signals are used to handle internal errors (execution  of a non-existing
CPU  intruction,  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  funtionality 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>.

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

    One possible usage of  this is, for example, to limit the time spent
    on  proving a goal.  This  requires a little C-code for  setting the
    alarm timer (see chapter 7):

    #include <SWI-Prolog.h>
    #include <unistd.h>

    foreign_t
    pl_alarm(term_t time)
    { double t;

      if ( PL_get_float(time, &t) )
      { alarm((long)(t+0.5));

        PL_succeed;
      }

      PL_fail;
    }

    install_t
    install()
    { PL_register_foreign("alarm", 1, pl_alarm, 0);
    }

    Next,  we can  define the  Prolog below.   This will  run _G_o_a_l  just
    as  once/1, throwing  the exception  error(_s_i_g_n_a_l_(_a_l_r_m_,  ___)_, __) if  a
    timeout occurs.

    :- load_foreign_library(alarm).

    :- on_signal(alrm, _, throw).

    :- module_transparent
            call_with_time_limit/2.

    call_with_time_limit(Goal, MaxTime) :-
            alarm(MaxTime),
            call_cleanup(Goal, _, alarm(0)), !.

    The  signal names are  defined by the  C-Posix standards 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:
    ill, fpe, segv, pipe, alrm, bus, 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_i_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.

  o _S_a_f_e_t_y
    Signal   handling   is   not   completely  safe   in   the   current
    implementation,  especially  if throw  is used  in combination  with
    external  foreign  code.    The  system  will use  the  C  longjmp()
    construct  to  direct control  to the  innermost PL_next_solution(),
    thus  forcing an external procedure to be abandoned at  an arbitrary
    moment.   Most likely not all SWI-Prologs own foreign code  is (yet)
    safe  too.   For  the multi-threaded  versions this  is even  worse:
    signals can easily violate thread synchronisation consistency.

    The  C-interface described  in  section 7.6.10  provides the  option
    PL_SIGSYNC for registering a signal handler  that delays delivery of
    signals  to a safe point.   Unfortunately this may cause signals  to
    be delayed for a long time if Prolog is executing foreign code.

  o _G_a_r_b_a_g_e _C_o_l_l_e_c_t_i_o_n
    The  garbage  collector  will block  all  signals that  are  handled
    by  Prolog.    While handling  a  signal, the  garbage-collector  is
    disabled.

  o _T_i_m_e _o_f _d_e_l_i_v_e_r_y
    Normally  delivery  is immediate  (or as  defined  by the  operating
    system  used).   Signals are blocked  when the garbage collector  is
    active,  and internally delayed if they occur within in  a `critical
    section'.  The critical sections are generally very short.


44..1111 TThhee ``bblloocckk'' ccoonnttrrooll--ssttrruuccttuurree

The  block/3 predicate  and  friends  have been  introduced  before  ISO
compatible  catch/3  exception  handling  for  compatibility  with  some
Prolog implementation.    The only  feature not covered  by catch/3  and
throw/1 is the posibility  to execute global cuts.  New code  should use
catch/3 and throw/1 to deal with exceptions.


bblloocckk((_+_L_a_b_e_l_, _+_G_o_a_l_, _-_E_x_i_t_V_a_l_u_e))
    Execute  _G_o_a_l in a _b_l_o_c_k.   _L_a_b_e_l is the name  of the block.   _L_a_b_e_l
    is  normally an  atom, but  the system imposes  no type  constraints
    and  may even be a variable.   _E_x_i_t_V_a_l_u_e is normally unified  to the
    second argument of an exit/2 call invoked by _G_o_a_l.


eexxiitt((_+_L_a_b_e_l_, _+_V_a_l_u_e))
    Calling  exit/2 makes the innermost _b_l_o_c_k which _L_a_b_e_l  unifies exit.
    The  block's _E_x_i_t_V_a_l_u_e is unified with  _V_a_l_u_e.  If this  unification
    fails the block fails.


ffaaiill((_+_L_a_b_e_l))
    Calling  fail/1 makes the innermost  _b_l_o_c_k which _L_a_b_e_l unifies  fail
    immediately.  Implemented as

    fail(Label) :- !(Label), fail.


!((_+_L_a_b_e_l))
    Cut  all  choice-points created  since the  entry  of the  innermost
    _b_l_o_c_k which _L_a_b_e_l unifies.


44..1122 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 then  :-/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 builtin 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(RuleSet, InputList, []).


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133 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, 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.   This mechanism  is considerably faster  than
the assert/retract mechanism as terms are not compiled,  but just copied
into the heap.

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.   It is faster  than
the mechanisms  described above, but  can only be  used to store  simple
status information like counters, etc.


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))
    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(Name/Arity).   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))
    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))
    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))
    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
    an  integer,  atom or  term.   _R_e_f_e_r_e_n_c_e  is unified  with a  unique
    reference to the record (see erase/1).


rreeccoorrddaa((_+_K_e_y_, _+_T_e_r_m))
    Equivalent to recorda(Key, Value,  _).


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(Key, Value,  _).


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))
    Unify  _V_a_l_u_e  with the  first  term recorded  under _K_e_y  which  does
    unify.    _R_e_f_e_r_e_n_c_e  is  unified with  the  memory location  of  the
    record.


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

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
    integer  returned by  recorda/3 or  recorded/3, clause/3,  assert/2,
    asserta/2  or assertz/2.    Other integers might  conflict with  the
    internal  consistency of the system.  Erase can only be  called once
    on  a record or clause.  A second call also might  conflict with the
    internal consistency of the system.


ffllaagg((_+_K_e_y_, _-_O_l_d_, _+_N_e_w))
    _K_e_y  is an  atom, integer or  term.   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 very  fast mechanism for storing simple  facts in
    the database.  Example:

    :- module_transparent succeeds_n_times/2.

    succeeds_n_times(Goal, Times) :-
            (   flag(succeeds_n_times, Old, 0),
                Goal,
                   flag(succeeds_n_times, N, N+1),
                fail
            ;   flag(succeeds_n_times, Times, Old)
            ).


44..1133..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133..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.

For advanced database indexing, it defines hash_term/2:


hhaasshh__tteerrmm((_+_T_e_r_m_, _-_H_a_s_h_K_e_y))
    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 succeeds  immediately, leaving
    _H_a_s_h_K_e_y an unbound variable.

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

44..1144 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 _+_N_a_m_e_/_+_A_r_i_t_y_, _._._.
    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 _+_N_a_m_e_/_+_A_r_i_t_y_, _._._.
    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 _+_N_a_m_e_/_+_A_r_i_t_y_, _._._.
    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.

    By  default all  predicates  with <_a_r_i_t_y>>= 1 are  indexed on  their
    first  argument.  It is possible to redefine indexing  on predicates
    that  already have clauses attached to  them.  This will initiate  a
    scan through the  predicates clause list to update the index summary
    information stored with each clause.

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

44..1155 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__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((_?_N_a_m_e_, _?_H_e_a_d))
    Successively  unifies _N_a_m_e  with  the name  of predicates  currently
    defined and _H_e_a_d with  the most general term built from _N_a_m_e and the
    arity of the  predicate.  This predicate succeeds for all predicates
    defined  in the specified module, imported  to it, or in one  of the
    modules from which the predicate will be imported if it is called.


ccuurrrreenntt__pprreeddiiccaattee((_:_N_a_m_e_/_A_r_i_t_y))
    ISO   compliant  implementation   of  current_predicate/2.       Un-
    like    current_predicate/2,    the   current   implementation    of
    current_predicate/1  does  not  consider  predicates   that  can  be
    autoloaded `current'.


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))
    Succeeds  if _H_e_a_d refers to a predicate that has  property _P_r_o_p_e_r_t_y.
    Can  be used  to test whether  a predicate  has a certain  property,
    obtain  all properties known  for _H_e_a_d,  find all predicates  having
    _p_r_o_p_e_r_t_y  or  even obtaining  all  information available  about  the
    current program.  _P_r_o_p_e_r_t_y is one of:

    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.

    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.

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

    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.

    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.

    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.

    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.

    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.

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

    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.

    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.

    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.

    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.

    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.


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))
    Succeeds  when  _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.   Normally clause/2 is  used to find clause definitions for  a
    predicate,  but it can  also be used to  find clause heads for  some
    body template.


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166 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 equiped with  a
clearer and  more robust specification,  new code  is encouraged to  use
these predicates for manipulation of I/O streams.

Section 4.16.2  describes tell/1,  see/1 and friends,  providing I/O  in
the spirit  of the outdated  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166..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.   New code is adviced to  use
these predicates to manage input and output streams.


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))
    ISO  compliant predicate  to open  a stream.   _S_r_c_D_e_s  is either  an
    atom, specifying a  Unix file, or a term `pipe(Command)', 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.  Note  there
         is no difference between the two on Unix systems.

    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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, expecially  related  to NFS  (network
         file  system), please  study  the  fcntl() manual  page  before
         trusting your locks!

         The lock option is a SWI-Prolog extension.

    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))
    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  a stream that produces no output.  All counting  functions are
    enabled  on such a stream.   An attempt  to read from a  null-stream
    will  immediately signal  end-of-file.   Similar to Unix  /dev/null.
    _S_t_r_e_a_m can be an atom, giving the null-stream an alias name.


cclloossee((_+_S_t_r_e_a_m))
    Close the specified stream.   If _S_t_r_e_a_m is not open an error message
    is  displayed.  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))
    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))
    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:

    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.

    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.

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

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

    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.

    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  a  term   of  format  $stream_position(_C_h_a_r_I_n_d_e_x_,
         _L_i_n_e_N_o_, _L_i_n_e_P_o_s).  See also set_stream_position/2.

    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.

    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.

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

    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.

    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.


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.


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))
    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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,  _c_u_r_r_e_n_t or _e_o_f, 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.

    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 repostioned, a reposition error  is raised.
    The  predicate seek/4 is  compatible to  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.
         Buffering is one of full, line or false.

    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.

    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.

    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_)_, __)

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

    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 optained  by opening the file  directly
         but, for example, through a network service.


44..1166..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 to 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  to  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  channals should  consider
using the ISO I/O predicates defined in section 4.16.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.16.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.16.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.16.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.16.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166..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))
    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))
    Set the current output stream to become _S_t_r_e_a_m.


ccuurrrreenntt__iinnppuutt((_-_S_t_r_e_a_m))
    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))
    Get the current output stream.


44..1177 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)),
            ...,


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.


ffiilleeeerrrroorrss((_-_O_l_d_, _+_N_e_w))
    Define error behaviour  on errors when opening a file for reading or
    writing.   Valid values are the  atoms on (default) and off.   First
    _O_l_d  is unified with the current value.   Then the new value  is set
    to _N_e_w.

    With  the introduction of exception-handling,  it is adviced to  use
    catch/3  to catch possibly  file-errors and act  accordingly.   Note
    that if _f_i_l_e_e_r_r_o_r_s is off, _n_o exception is generated.


44..1188 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
    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))
    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  (0=<_C_h_a_r=< 255)
    or an atom of one character.


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.


ppuutt__bbyyttee((_+_B_y_t_e))
    Alias for put/1.


ppuutt__bbyyttee((_+_S_t_r_e_a_m_, _+_B_y_t_e))
    Alias for put/2


ppuutt__cchhaarr((_+_C_h_a_r))
    Alias for put/1.


ppuutt__cchhaarr((_+_S_t_r_e_a_m_, _+_C_h_a_r))
    Alias for put/2


ppuutt__ccooddee((_+_C_o_d_e))
    Alias for put/1.


ppuutt__ccooddee((_+_S_t_r_e_a_m_, _+_C_o_d_e))
    Alias for put/2


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

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
    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))
    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))
    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))
    Read the next byte from _S_t_r_e_a_m.


ggeett__ccooddee((_-_C_o_d_e))
    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))
    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))
    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))
    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_byte/1 predicate.


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

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))
    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))
    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))
    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))
    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))
    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))
    Reads the  next input character like get_char/2,  but does not remove
    it from the stream.


sskkiipp((_+_C_h_a_r))
    Read the input until  _C_h_a_r or the end of the file is encountered.  A
    subsequent call to get0/1 will read the first character after _C_h_a_r.


sskkiipp((_+_S_t_r_e_a_m_, _+_C_h_a_r))
    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_h_a_r))
    Get  a single character from input stream `user' (regardless  of the
    current  input stream).  Unlike get0/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
    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))
    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).


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 bytes from stream _S_t_r_e_a_m_I_n to _S_t_r_e_a_m_O_u_t.


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.


44..1199 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  term_to_atom/2,  atom_to_term/3  and  sformat/3  provide
means  for translating  atoms and  strings  to terms.    The  predicates
format/[1,2] and writef/2 provide formatted output.

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  (see
current_prolog_flag/2) 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))
    The  predicate  write_term/2  is  the generic  form  of  all  Prolog
    term-write predicates.  Valid options are:

    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.

    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.23) as  `...`.
         The default depends on the prolog flag with the same name.

    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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.  The default  is
         false.

    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.

    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 eclipse (...).  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   toplevel   and   debugger  to   limit   screen
         output.   See also the  prolog-flags toplevel_print_options  and
         debugger_print_options.


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))
    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))
    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 and quoted.


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))
    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))
    Write  _T_e_r_m  to the  current output,  using  brackets and  operators
    where  appropriate.     See  current_prolog_flag/2  for  controlling
    floating point output format.


wwrriittee((_+_S_t_r_e_a_m_, _+_T_e_r_m))
    Write _T_e_r_m to _S_t_r_e_a_m.


wwrriitteeqq((_+_T_e_r_m))
    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))
    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))
    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))
    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
    occurring  once in a term  (singleton variables) 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))
    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 to Quintus Prolog.   The
    argument order is  according to the ISO standard.  Syntax-errors are
    always reported using exception-handling (see catch/3).  Options:

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

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

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

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

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

    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-flags
         double_quotes, current_prolog_flag/2.  (SWI-Prolog).

    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.23).
         The default depends on the prolog flag with the same name.

    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.

    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  if 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Frroomm--TTo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.


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))
    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..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 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))
    Succeeds  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))
    _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, Arg)if _A_r_g <0.


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.

    This  predicate may  be used  for destructive  assignment to  terms,
    using  them as and  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.


_?_T_e_r_m =.. _?_L_i_s_t
    _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_, _+_F_u_n_c_t_i_o_n_S_y_m_b_o_l_, _+_S_t_a_r_t_, _-_E_n_d))
    As  numbervars/3, but instead of  using the fixed $VAR the  function
    symbol is determined by extra _F_u_n_c_t_i_o_n_S_y_m_b_o_l argument.


ffrreeee__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.  For example:

    ?- free_variables(a(X, b(Y, X), Z), L).

    L = [G367, G366, G371]
    X = G367
    Y = G366
    Z = G371


ccooppyy__tteerrmm((_+_I_n_, _-_O_u_t))
    Make a copy of  term _I_n and unify the result with _O_u_t.  Ground parts
    of  _I_n are  shared by  _O_u_t.   Provided _I_n  and _O_u_t  have no  sharing
    variables  before  this call  they will  have  no sharing  variables
    afterwards.  copy_term/2 is semantically equivalent to:

    copy_term(In, Out) :-
            recorda(copy_key, In, Ref),
            recorded(copy_key, Out, Ref),
            erase(Ref).

    Note  that as copy_term/2  does not create  copies for ground  terms
    setarg/3 affects both the copy and original.


44..2211 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.
Upto  version 3.2.x,  SWI-Prolog's atom_chars/2 behaved,  compatible  to
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))
    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))
    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))
    Convert   between  character  and   character  code  for  a   single
    character.


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))
    Similar  to  atom_chars/2,  but  converts between  a number  and  its
    representation  as a  list of  one-character atoms.    Fails with  a
    representation_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))
    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.


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

iinntt__ttoo__aattoomm((_+_I_n_t_, _+_B_a_s_e_, _-_A_t_o_m))
    Convert  _I_n_t to an textual representation using base _B_a_s_e  and unify
    the  result with _A_t_o_m.   If _B_a_s_e 6=10 the  base will be prepended  to
    _A_t_o_m.   _B_a_s_e= 0 will try to interpret _I_n_t as an character codes and
    return  0'<_c>.   Otherwise  2=<_B_a_s_e=< 36.   Some  examples are  given
    below.

                   int_to_atom(45, 2, A)  -!   A= 20101101
                   int_to_atom(97, 0, A)  -!   A= 00a
                   int_to_atom(56, 10, A) -!   A= 56


iinntt__ttoo__aattoomm((_+_I_n_t_, _-_A_t_o_m))
    Equivalent to int_to_atom(Int, 10, Atom).


tteerrmm__ttoo__aattoomm((_?_T_e_r_m_, _?_A_t_o_m))
    Succeeds  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_error exception is  raised.
    Otherwise _T_e_r_m is ``written'' on _A_t_o_m using write/1.


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))
    _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, integers or  floating
    point  numbers.    For  ISO  compliance,  the  instantiation-pattern
    -, -, +  is allowed  too, non-deterministically  splitting the  3-th
    argument  into two parts  (as append/3  does for lists).   See  also
    string_concat/3.


ccoonnccaatt__aattoomm((_+_L_i_s_t_, _-_A_t_o_m))
    _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.    If _L_i_s_t  has exactly  2 elements  it  is equivalent  to
    atom_concat/3, allowing for variables in the list.


ccoonnccaatt__aattoomm((_?_L_i_s_t_, _+_S_e_p_a_r_a_t_o_r_, _?_A_t_o_m))
    Creates  an  atom just  like  concat_atom/2, but  inserts  _S_e_p_a_r_a_t_o_r
    between each pair of atoms.  For example:

    ?- concat_atom([gnu, gnat], ', ', A).

    A = 'gnu, gnat'

    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:

    ?- concat_atom(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))
    Succeeds  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.23).    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))
    Succeeds  if  _A_t_o_m starts  with the  characters from  _P_r_e_f_i_x.    Its
    behaviour  is equivalent  to ?- concat(Prefix, _, Atom), but  avoids
    the construction of an atom for the `remainder'.


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))
    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  minimalises  non-determinism  and  creation  of
    atoms.    This  is a  very flexible  predicate that  can do  search,
    prefix- and suffix-matching, etc.


44..2222 CCllaassssiiffyyiinngg cchhaarraacctteerrs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 to 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
         underscore  (_).     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  haxe-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222..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233 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, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 7.  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  backquotes
if quoted  is true.    This flag  provides compatibility  to 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244 OOppeerraattoorrss

Operators  are  defined  to  improve  the  readibility  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.   The  module-table  of the  module
user acts as  default table for all modules.   This global table can  be
modified explictly from inside a module:

:- module(prove,
          [ prove/1
          ]).

:- op(900, xfx, user:(=>)).

Unlike  what many  users  think,  operators  and quoted  atoms  have  no
relation:   defining a 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))
    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.   Note that  all
    operators can be redefined by the user.
     ______________________________________________________________
     | 1200 |xfx  |-->, :-                                        |
     | 1200 | fx  |:-, ?-                                         |
     | 1150 | fx  |dynamic, multifile, module_transparent, discon-|
     |      |     |tiguous, volatile, initialization              |
     | 1100 |xfy  |;, |                                           |

     | 1050 |xfy  |->                                             |
     | 1000 |xfy  |,                                              |
     |  954 |xfy  |\                                              |
     |  900 | fy  |\+                                             |
     |  900 | fx  |~                                              |
     |  700 |xfx  |<, =, =.., =@=,  =:=, =<, ==, =\=,  >, >=, @<, |
     |      |     |@=<, @>, @>=, \=, \==, is                      |
     |  600 |xfy  |:                                              |

     |  500 | yfx |+, -, /\, \/, xor                              |
     |  500 | fx  |+, -, ?, \                                     |
     |  400 | yfx |*, /, //, <<, >>, mod, rem                     |
     |  200 |xfx  |**                                             |
     |__200_|xfy__|^______________________________________________|_

                      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))
    Succeeds when _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255 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 complicancy.


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))
    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))
    Queries    the   current   character   conversion-table.         See
    char_conversion/2 for details.


44..2266 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  floating point  and  integer
arithmetic as  appropriate.  The  integer predicates are as  ``logical''
as possible.  Their usage is recommended  whenever applicable, resulting
in faster and more ``logical'' programs.

The  general arithmetic  predicates  are  optionally compiled  now  (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.

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

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.


ssuucccc((_?_I_n_t_1_, _?_I_n_t_2))
    Succeeds  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))
    Succeeds 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.


_+_E_x_p_r_1 > _+_E_x_p_r_2
    Succeeds  when 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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  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
    Succeeds  when 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
    Succeeds  when  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
    Succeeds  when  _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  will be used  with unbound left  operand.
    If equality is to be tested, =:=/2 should be used.  For example:

         ?- 1.0 is sin(pi/2).         Fails!.   sin(pi/2) evaluates
                                      to   1.0,   but   is/2   will
                                      represent this as the integer
                                      1,  after  which  unify  will
                                      fail.

         ?- 1.0 is float(sin(pi/2)).  Succeeds,   as   the  float/1
                                      function forces the result to
                                      be float.
         ?- 1.0 =:= sin(pi/2).        Succeeds as expected.


44..2277 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  above.   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 three  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 should  evaluate into
                 an integer.
        _I_n_t      An integer.

In  case integer  addition, subtraction  and  multiplication would  lead
to  an integer  overflow  the operands  are automatically  converted  to
floating point  numbers.   The floating  point functions (sin/1,  exp/1,
etc.)     form  a  direct  interface  to  the  corresponding  C  library
functions used  to compile SWI-Prolog.   Please refer  to the C  library
documentation for details on precision, error handling, etc.


- _+_E_x_p_r
    _R_e_s_u_l_t =-_E_x_p_r


_+_E_x_p_r_1 + _+_E_x_p_r_2
    _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
    _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
    _R_e_s_u_l_t =_E_x_p_r_1_*Expr2


_+_E_x_p_r_1 / _+_E_x_p_r_2
    _R_e_s_u_l_t =_E_x_p_r_1=_E_x_p_r_2


_+_I_n_t_E_x_p_r_1 mmoodd _+_I_n_t_E_x_p_r_2
    Modulo:   _R_e_s_u_l_t = _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 The
    function  mod/2  is  implemented using  the  C  % operator.     It's
    behaviour with negtive values is illustrated in the table below.

                              2  =   17  mod   5
                              2  =   17  mod  -5
                             -2  =  -17  mod   5
                             -2  =  -17  mod   5


_+_I_n_t_E_x_p_r_1 rreemm _+_I_n_t_E_x_p_r_2
    Remainder of division:  _R_e_s_u_l_t = float_fractional_part(_I_n_t_E_x_p_r_1/_I_n_t_E_x_p_r_2)


_+_I_n_t_E_x_p_r_1 // _+_I_n_t_E_x_p_r_2
    Integer division:  _R_e_s_u_l_t = truncate(_E_x_p_r_1/_E_x_p_r_2)


aabbss((_+_E_x_p_r))
    Evaluate _E_x_p_r and return the absolute value of it.


ssiiggnn((_+_E_x_p_r))
    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.


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.


.((_+_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 objectard, offerring  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 7)  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 to 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 represent