
                                              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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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
    D_i_sert  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  sourc