home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / language / sbprolog / Docs / MANUAL next >
Encoding:
Text File  |  1992-01-04  |  187.0 KB  |  4,979 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                         The SB-Prolog System, Version 3.1
  10.  
  11.                                   A User Manual
  12.  
  13.                                     edited by
  14.                                 Saumya K. Debray
  15.  
  16.                                 from material by
  17.  
  18.                                David Scott Warren
  19.                                 Suzanne Dietrich
  20.                                SUNY at Stony Brook
  21.  
  22.                                 Fernando Pereira
  23.                                 SRI International
  24.  
  25.  
  26.  
  27.                                   December 1989
  28.  
  29.  
  30.                          Department of Computer Science
  31.                               University of Arizona
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.                                 Tucson, AZ 85721
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.                           The SB-Prolog System, Version 3.1
  75.                                     A User Manual
  76.  
  77.  
  78.  
  79.  
  80.           Abstract: SB-Prolog is a Prolog system for Unix|-  based  systems.
  81.           The core of the system is an emulator, written in C for portabil-
  82.           ity, of a Prolog virtual machine that is an extension of the War-
  83.           ren Abstract Machine.  The remainder of the system, including the
  84.           translator from Prolog to the virtual  machine  instructions,  is
  85.           written  in  Prolog.  Parts of this manual, specifically the sec-
  86.           tions on Prolog syntax and descriptions of some of the  builtins,
  87.           are based on the C-Prolog User Manual by Fernando Pereira.
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.           ____________________
  97.              |- Unix is a trademark of AT&T.
  98.  
  99.  
  100.                                           1
  101.  
  102.  
  103.  
  104.  
  105.  
  106.           1.  Introduction
  107.  
  108.  
  109.           SB-Prolog is a Prolog system based on an extension of the  Warren
  110.           Abstract Machine[1].  The  WAM  simulator  is  written  in  C  to
  111.           enhance portability.  Prolog source programs can be compiled into
  112.           byte code files, which contain encodings of WAM instructions  and
  113.           are  interpreted  by  the simulator.  Programs can also be inter-
  114.           preted via consult.
  115.  
  116.                SB-Prolog offers several features that are not found on most
  117.           Prolog  systems  currently available.  These include: compilation
  118.           to object files; dynamic loading  of  predicates;  provision  for
  119.           generating  executable  code  on  the  global stack, which can be
  120.           later be reclaimed; an  extension  table  facility  that  permits
  121.           memoization  of  relations.  Other features include full integra-
  122.           tion between compiled and interpreted code, and  a  facility  for
  123.           the  definition  and expansion of macros that is fully compatible
  124.           with the runtime system.
  125.  
  126.                The system incorporates  tail  recursion  optimization,  and
  127.           performs  clause  indexing in both compiled and interpreted code.
  128.           However, there is no garbage  collector  for  the  global  stack.
  129.           This may be incorporated into a later version.
  130.  
  131.                One of the few luxuries afforded to a person giving software
  132.           away  for  free  is  the  ability  to  take philosophical stances
  133.           ____________________
  134.              [1] D. H. D. Warren, ``An Abstract Prolog  Instruction  Set'',
  135.           Tech. Note 309, SRI International, 1983.
  136.  
  137.                                           2
  138.  
  139.  
  140.  
  141.  
  142.  
  143.           without hurting his wallet.  Based on our faith in the ``declara-
  144.           tive  ideal'',  viz. that pure programs with declarative readings
  145.           are Good, we have attempted to encourage, where possible, a  more
  146.           declarative  style  of  programming.   To this end, we have deli-
  147.           berately chosen to not reward programs containing  cuts  in  some
  148.           situations  where more declarative code is possible (see Appendix
  149.           2, sS 3).  We have also resisted the  temptation  to  make  assert
  150.           less expensive.  We hope this will help promote a better program-
  151.           ming style.
  152.  
  153.           2.  Getting Started
  154.  
  155.  
  156.           This section is intended to give a  broad  overview  of  the  SB-
  157.           Prolog  system,  so  as to enable the new user to begin using the
  158.           system with a minimum of delay.  Many of the  topics  touched  on
  159.           here are covered in greater depth in later sections.
  160.  
  161.           2.1.  The Dynamic Loader Search Path
  162.  
  163.  
  164.           In SB-Prolog, it is not necessary for the user to  load  all  the
  165.           predicates  necessary to execute a program.  Instead, if an unde-
  166.           fined predicate foo is encountered during execution,  the  system
  167.           searches  the  user's  directories  in the order specified by the
  168.           environment variable SIMPATH until it finds a directory  contain-
  169.           ing a file foo whose name is that of the undefined predicate.  It
  170.           then dynamically loads and links the file foo (which is  expected
  171.           to be a byte code file defining the predicate foo), and continues
  172.  
  173.                                           3
  174.  
  175.  
  176.  
  177.  
  178.  
  179.           with execution; if no such file can be found, an error message is
  180.           given and execution fails.  This feature makes it unnecessary for
  181.           the user to have to explicitly link in all  the  predicates  that
  182.           might  be  necessary  in a program: instead, only those files are
  183.           loaded which are necessary to have the program execute.  This can
  184.           significantly reduce the memory requirements of programs.
  185.  
  186.                The key to this dynamic  search-and-load  behaviour  is  the
  187.           SIMPATH  environment variable, which specifies the order in which
  188.           directories are to be searched.  It may be set by adding the fol-
  189.           lowing line to the user's .cshrc file:
  190.  
  191.                       setenv SIMPATH path
  192.  
  193.  
  194.           where path is a sequence of directory names separated by colons:
  195.  
  196.                       dir<1>:dir<2>: ... :dir<n>
  197.  
  198.  
  199.           and dir<i> are full path names  to  the  respective  directories.
  200.           For example, executing the command
  201.                       setenv SIMPATH .:$HOME/prolog/modlib:$HOME/prolog/lib
  202.  
  203.  
  204.           sets the search order for undefined predicates to the  following:
  205.           first,  the  directory  in  which  the  program  is  executing is
  206.           searched; if the appropriate file is not found in this directory,
  207.           the  directories  searched  are,  in  order,  ~/prolog/modlib and
  208.  
  209.                                           4
  210.  
  211.  
  212.  
  213.  
  214.  
  215.           ~/prolog/lib.  If the appropriate file is not  found  in  any  of
  216.           these  directories,  the system gives an error message and execu-
  217.           tion fails.
  218.  
  219.                The beginning user is advised to include the  system  direc-
  220.           tories  (listed  in the next section) in his SIMPATH, in order to
  221.           be able to access the system libraries (see below).
  222.  
  223.           2.2.  System Directories
  224.  
  225.  
  226.           There are four basic system directories: cmplib, lib, modlib  and
  227.           sim.  cmplib contains the Prolog to byte code translator; lib and
  228.           modlib contain library routines.  The src subdirectory in each of
  229.           these  contains  the  corresponding  Prolog source programs.  The
  230.           directory sim contains the simulator,  the  subdirectory  builtin
  231.           contains code for the builtin predicates of the system.
  232.  
  233.                It is recommended that the beginning user include the system
  234.           directories in his SIMPATH, by setting SIMPATH to
  235.                            .:SBP/modlib:SBP/lib:SBP/cmplib
  236.  
  237.           where SBP denotes the path to the root of  the  SB-Prolog  system
  238.           directories.
  239.  
  240.           2.3.  Invoking the Simulator
  241.  
  242.  
  243.           The simulator is invoked by the command
  244.                       sbprolog bc_file
  245.  
  246.                                           5
  247.  
  248.  
  249.  
  250.  
  251.  
  252.           where bc_file is a byte code file resulting from the  compilation
  253.           of  a Prolog program.  In almost all cases, the user will wish to
  254.           interact with  the  SB-Prolog  query  evaluator,  in  which  case
  255.           bc_file will be $readloop, and the command will be
  256.                               sbprolog  Path/$readloop
  257.  
  258.           where Path is the path to the directory  containing  the  command
  259.           interpreter $readloop.  This directory, typically, is modlib (see
  260.           Section 2.2 above).
  261.  
  262.                The command interpreter reads in a query  typed  in  by  the
  263.           user, evaluates it and prints the answer(s), repeating this until
  264.           it encounters an end-of-file (the standard end-of-file  character
  265.           on  the system, e.g. ctrl-D), or the user types in end_of_file or
  266.           halt.
  267.  
  268.                The user should ensure that the the directory containing the
  269.           executable  file  sim  (typically,  the system directory sim: see
  270.           Section 2.2 above) is included in the  shell  variable  path;  if
  271.           not, the full path to the simulator will have to be specified.
  272.  
  273.                In general, the simulator may be invoked with a  variety  of
  274.           options, as follows:
  275.                        sbprolog -options bc_file
  276.               or
  277.                        sbprolog -option<1> -option<2> ... -option<n> bc_file
  278.  
  279.           The options recognized by the simulator are described in  Section
  280.           4.2.
  281.  
  282.  
  283.                                           6
  284.  
  285.  
  286.  
  287.  
  288.  
  289.                When called with a byte code  file  bc_file,  the  simulator
  290.           begins  execution  with the first clause in that file.  The first
  291.           clause in such a file, therefore, should be a clause without  any
  292.           arguments  in  the head (otherwise, the simulator will attempt to
  293.           dereference argument pointers in the head that are really  point-
  294.           ing into deep space, and usually come to a sad end).  If the user
  295.           is executing a file in this manner rather than using the  command
  296.           interpreter,  he  should also be careful to include the undefined
  297.           predicate handler, consisting of  the  predicates  `_$interrupt/2
  298.           and `_$undefined_pred'/1, which is normally defined in the files
  299.            modlib/src/$init_sys.P and modlib/src/$readloop.
  300.  
  301.           2.4.  Executing Programs
  302.  
  303.  
  304.           There are two ways of executing a program: a source file  may  be
  305.           compiled into a byte-code file, which can then be loaded and exe-
  306.           cuted; or, the source file may be interpreted via  consult.   The
  307.           system  supports  full  integration  of  compiled and interpreted
  308.           code, so that some predicates of a program may be compiled, while
  309.           others  may  be interpreted.  However, the unit of compilation or
  310.           consulting remains the  file.   The  remainder  of  this  section
  311.           describes each of these procedures in more detail.
  312.  
  313.           2.4.1.  Compiling Programs
  314.  
  315.  
  316.           The compiler is invoked through the Prolog predicate compile.  It
  317.           translates Prolog source programs into byte code that can then be
  318.  
  319.                                           7
  320.  
  321.  
  322.  
  323.  
  324.  
  325.           executed on the simulator.  The compiler may be invoked  as  fol-
  326.           lows:
  327.  
  328.                       | ?- compile(InFile [, OutFile ] [, OptionsList ]).
  329.               or
  330.                       | ?- compile(InFile, OutFile, OptionsList, PredList).
  331.  
  332.  
  333.           where optional parameters are enclosed in  brackets.   InFile  is
  334.           the  name of the input (i.e. source) file; OutFile is the name of
  335.           the output file (i.e. byte code) file; OptionsList is a  list  of
  336.           compiler  options,  and  PredList is a list of terms P/N denoting
  337.           the predicates defined in InFile, where P is a predicate name and
  338.           N its arity.
  339.  
  340.                The input and output file names must be Prolog  atoms,  i.e.
  341.           either  begin  with  a  lower  case  letter  and  consist only of
  342.           letters, digits, dollar signs and underscores;  or,  be  enclosed
  343.           within  single quotes.  If the output file name is not specified,
  344.           it defaults to InFile.out.  The list of options, if specified, is
  345.           a Prolog list, i.e. a term of the form
  346.  
  347.                       [ option<1>, option<2>, ..., option<n> ].
  348.  
  349.  
  350.           If left unspecified, it defaults to the empty list [].  PredList,
  351.           if specified, is usually given as an uninstantiated variable; its
  352.           principal use is for setting trace points on  the  predicates  in
  353.           the  file  (see Sections 6 and 8).  Notice that PredList can only
  354.  
  355.                                           8
  356.  
  357.  
  358.  
  359.  
  360.  
  361.           appear in compile/4.
  362.  
  363.                A list of compiler options appears in Section 8.3.
  364.  
  365.           2.4.2.  Loading Byte Code Files
  366.  
  367.  
  368.           Byte code files may be loaded into the simulator using the predi-
  369.           cate load:
  370.  
  371.                       | ?- load(ByteCode_File).
  372.  
  373.  
  374.           where ByteCode_File is a Prolog atom (see Section  3.1)  that  is
  375.           the name of a byte code file.
  376.  
  377.                The load predicate invokes the dynamic loader, which carries
  378.           out  a search according to the sequence specified by the environ-
  379.           ment variable SIMPATH (see Section 2.1).   It  is  therefore  not
  380.           necessary  to always specify the full path name to the file to be
  381.           loaded.
  382.  
  383.                Byte code files may  be  concatenated  together  to  produce
  384.           other  byte  code files.  Thus, for example, if foo1 and foo2 are
  385.           byte code files resulting from  the  compilation  of  two  Prolog
  386.           source  programs,  then  the  file foo, obtained by executing the
  387.           shell command
  388.                        cat foo1 foo2 > foo
  389.  
  390.           is a byte code file as well, and may be loaded and executed.   In
  391.  
  392.                                           9
  393.  
  394.  
  395.  
  396.  
  397.  
  398.           this case, loading and executing the file foo would give the same
  399.           result as loading foo1 and foo2 separately, which in  turn  would
  400.           be  the  same as concatenating the original source files and com-
  401.           piling this larger file.  This makes it easier to  compile  large
  402.           programs:  one  need only break them into smaller pieces, compile
  403.           the individual pieces, and concatenate the  resulting  byte  code
  404.           files together.
  405.  
  406.           2.4.3.  Consulting Programs
  407.  
  408.  
  409.           Instead of compiling a file to generate a byte  code  file  which
  410.           then  has  to be loaded, a program may be executed interpretively
  411.           by ``consulting'' the corresponding source file:
  412.                       | ?- consult(SourceFile [, OptionList ] ).
  413.               or
  414.                       | ?- consult(SourceFile, OptionList, PredList).
  415.  
  416.           where SourceFile is a Prolog atom which is the  name  of  a  file
  417.           containing  a  Prolog  source  program;  OptionList  is a list of
  418.           options to consult; and PredList is a list of terms P/N, where  P
  419.           is  a predicate name and N its arity, specifying which predicates
  420.           have been consulted from SourceFile; its  principal  use  is  for
  421.           setting  trace  points on the predicates in the file (see Section
  422.           6).  Notice that PredList can only appear in consult/3.
  423.  
  424.                At this point, the options recognized for  consult  are  the
  425.           following:
  426.  
  427.  
  428.  
  429.                                          10
  430.  
  431.  
  432.  
  433.  
  434.  
  435.           t    ``trace''.  Causes a trace point to be set on any  predicate
  436.                in the current file that does not already have a trace point
  437.                set.
  438.  
  439.           v    ``verbose''.  Causes information regarding which  predicates
  440.                have been consulted to be printed out. Default: off.
  441.  
  442.           In addition to the above, options for the macro expander are also
  443.           recognized (see Section 10)).
  444.  
  445.           consult will create an index on  the  printipal  functor  of  the
  446.           first  argument of the predicates being consulted, unless this is
  447.           changed using the index/3 directive.  In particular, note that if
  448.           no index is desired on a predicate foo/n, then the directive
  449.               :- index(foo, n, 0).
  450.  
  451.           should be given.
  452.  
  453.                It is important to note that SB-Prolog's  consult  predicate
  454.           is similar to that of Quintus Prolog, and behaves like C-Prolog's
  455.           reconsult.  This means that if a predicate is defined across  two
  456.           or more files, consulting them will result in only the clauses in
  457.           the file consulted last being used.
  458.  
  459.           2.5.  Execution Directives
  460.  
  461.  
  462.           Execution directives may be  specified  to  compile  and  consult
  463.           through  :-/1.   If,  in  the read phase of compile or consult, a
  464.           term with principal  functor  :-/1  is  read  in,  this  term  is
  465.  
  466.                                          11
  467.  
  468.  
  469.  
  470.  
  471.  
  472.           executed  directly  via call/1.  This enables the user to dynami-
  473.           cally modify the environment, e.g. via op declarations (see  Sec-
  474.           tion 3.2), asserts etc.
  475.  
  476.                A point to note is that if the environment is modified as  a
  477.           result  of  an execution directive, the modifications are visible
  478.           only in that environment.  This means that consulted code,  which
  479.           runs  in  the  environment in which the source program is read in
  480.           (and which is modified by such  execution  directives)  feel  the
  481.           effects of such execution directives.  However, byte code result-
  482.           ing from compilation, which, in general, executes in an  environ-
  483.           ment  different  from that in which the source was compiled, does
  484.           not inherit the effects of such directives.  Thus, an op declara-
  485.           tion  can be used in a source file to change the syntax and allow
  486.           the remainder of the program to be parsed according to the  modi-
  487.           fied  syntax;  however, these modifications will not, in general,
  488.           manifest themselves if the  byte  code  is  executed  in  another
  489.           environment.  Of course, if the byte code is loaded into the same
  490.           environment as that in which the  source  program  was  compiled,
  491.           e.g. through
  492.                       | ?- compile(foo, bar), load(bar).
  493.  
  494.           the effects of execution directives will continue to be felt.
  495.  
  496.           3.  Syntax
  497.  
  498.  
  499.  
  500.  
  501.                                          12
  502.  
  503.  
  504.  
  505.  
  506.  
  507.           3.1.  Terms
  508.  
  509.  
  510.           The syntax of SB-Prolog is by and large compatible with  that  of
  511.           C-Prolog.  The data objects of the language are called  terms.  A
  512.           term  is either a constant, a variable or a compound term.   Con-
  513.           stants  can  be  integers  or atoms.  The symbol for an atom must
  514.           begin with a lower case letter or the dollar sign $, and  consist
  515.           of  any  number of letters, digits, underscores and dollar signs;
  516.           if it contains  any  character  other  than  these,  it  must  be
  517.           enclosed  within  single  quotes.[2]  As  in  other   programming
  518.           languages,  constants  are definite elementary objects.
  519.  
  520.                Variables are distinguished by an  initial  capital   letter
  521.           or  by the initial character "_", for example
  522.               X   Value   A   A1   _3   _RESULT   _result
  523.  
  524.           If a variable is only referred to once, it does not need  to   be
  525.           named  and   may  be  written as an anonymous variable, indicated
  526.           by the underline character "_".
  527.  
  528.                A variable should be thought  of  as   standing   for   some
  529.           definite   but unidentified  object.  A variable  is  not  simply
  530.           a   writeable  storage   location   as   in    most   programming
  531.           languages;   rather  it is a local name for some data object, cf.
  532.           the variable of  pure  LISP  and constant declarations in Pascal.
  533.           ____________________
  534.              [2] Users are advised against using symbols beginning with `$'
  535.           or  `_$',  however,  in order to minimize the possibility of con-
  536.           flicts with symbols internal to the system.
  537.  
  538.  
  539.                                          13
  540.  
  541.  
  542.  
  543.  
  544.  
  545.                The structured data objects of the language are the compound
  546.           terms.  A compound term comprises a functor (called the principal
  547.           functor of the term) and a sequence of one or more  terms  called
  548.           arguments.   A  functor is characterised by its name, which is an
  549.           atom, and its arity or number of arguments.  For example the com-
  550.           pound  term whose functor is named `point' of arity 3, with argu-
  551.           ments X, Y and Z, is written
  552.               point(X,Y,Z)
  553.  
  554.           An atom is considered to be a functor of arity 0.
  555.  
  556.                A functor or predicate symbol is uniquely identified by  its
  557.           name and arity (in other words, it is possible for different sym-
  558.           bols having different arities to share the same name).  A functor
  559.           or predicate symbol p with arity n is usually written p/n.
  560.  
  561.                One  may  think  of  a  functor  as  a record type  and  the
  562.           arguments  of  a  compound  term  as  the  fields  of  a  record.
  563.           Compound terms are usefully pictured as trees.  For example,  the
  564.           term
  565.               s(np(john),vp(v(likes),np(mary)))
  566.  
  567.           would be pictured as the structure
  568.                                              s
  569.                                           /   \
  570.                                      np      vp
  571.                                       |      /  \
  572.                                    john    v     np
  573.                                            |     |
  574.                                         likes  mary
  575.  
  576.  
  577.  
  578.                                          14
  579.  
  580.  
  581.  
  582.  
  583.  
  584.                Sometimes it is convenient  to  write  certain  functors  as
  585.           operators  --  2-ary  functors may be declared as infix operators
  586.           and 1-ary functors as prefix or postfix operators.   Thus  it  is
  587.           possible to write
  588.               X+Y     (P;Q)     X<Y      +X     P;
  589.  
  590.           as optional alternatives to
  591.               +(X,Y)   ;(P,Q)   <(X,Y)   +(X)   ;(P)
  592.  
  593.           Operators are described fully in the next section.
  594.  
  595.                Lists form an important class of data structures in  Prolog.
  596.           They  are essentially  the  same  as  the  lists  of LISP: a list
  597.           either is the atom [], representing the empty list, or is a  com-
  598.           pound  term  with  functor  `.'/2 and  two  arguments  which  are
  599.           respectively the head and tail of the list.  Thus   a   list   of
  600.           the  first  three  natural  numbers  is  the structure
  601.                                            .
  602.                                          / \
  603.                                        1    .
  604.                                            / \
  605.                                          2    .
  606.                                              / \
  607.                                            3   []
  608.  
  609.           which  could  be  written,  using   the   standard   syntax,   as
  610.           .(1,.(2,.(3,[]))),  but  which  is normally written, in a special
  611.           list notation, as [1,2,3].  The special list notation in the case
  612.           when the tail of  a  list  is  a variable is exemplified by
  613.                                   [X|L]     [a,b|L]
  614.  
  615.           representing
  616.  
  617.                                          15
  618.  
  619.  
  620.  
  621.  
  622.                                    .                .
  623.                                   / \             / \
  624.                                X     L          a    .
  625.                                                     / \
  626.                                                  b     L
  627.  
  628.           respectively.
  629.  
  630.                Note that this list syntax is only syntactic sugar for terms
  631.           of  the  form  `.'(_,  _) and does not provide any new facilities
  632.           that were not available otherwise.
  633.  
  634.                For convenience, a further  notational  variant  is  allowed
  635.           for  lists   of   integers   which  correspond to ASCII character
  636.           codes.  Lists written in this notation are called  strings.   For
  637.           example,
  638.               "Prolog"
  639.  
  640.           represents exactly the same list as
  641.               [80,114,111,108,111,103]
  642.  
  643.           3.2.  Operators
  644.  
  645.  
  646.           Operators in Prolog are simply  a  notational  convenience.   For
  647.           example, the expression
  648.               2 + 1
  649.  
  650.           could also be written +(2,1).  It should  be  noticed  that  this
  651.           expression represents the structure
  652.                                            +
  653.                                          /   \
  654.                                        2     1
  655.  
  656.                                          16
  657.  
  658.  
  659.  
  660.  
  661.  
  662.           and not the number 3.  The addition would only  be  performed  if
  663.           the  structure  was  passed as an argument to an appropriate pro-
  664.           cedure (such as eval/2 - see Section 5.2).
  665.  
  666.                The Prolog syntax caters  for  operators   of   three   main
  667.           kinds   -  infix,  prefix and postfix.  An infix operator appears
  668.           between its two arguments, while a prefix operator  precedes  its
  669.           single  argument and a postfix operator is written after its sin-
  670.           gle argument.
  671.  
  672.                Each operator has a precedence, which is a  number  from   1
  673.           to   1200.   The   precedence  is  used  to  disambiguate expres-
  674.           sions  where  the  structure  of  the  term  denoted is not  made
  675.           explicit  through  parenthesization.   The  general  rule is that
  676.           the operator with the highest precedence is the  principal  func-
  677.           tor.   Thus  if  `+'   has   a  higher  precedence than `/', then
  678.           ``a+b/c'' and ``a+(b/c)'' are  equivalent  and  denote  the  term
  679.           "+(a,/(b,c))".    Note   that   the    infix  form  of  the  term
  680.           "/(+(a,b),c)"  must  be  written   with   explicit   parentheses,
  681.           ``(a+b)/c''.
  682.  
  683.                If there are two operators in the subexpression having   the
  684.           same  highest   precedence,   the ambiguity must be resolved from
  685.           the types of the operators.  The  possible  types  for  an  infix
  686.           operator are
  687.               xfx     xfy     yfx
  688.  
  689.           With an operator of type `xfx', it is a requirement that both  of
  690.           the  two   subexpressions which are the arguments of the operator
  691.  
  692.                                          17
  693.  
  694.  
  695.  
  696.  
  697.  
  698.           must be of lower precedence  than  the  operator   itself,   i.e.
  699.           their   principal  functors   must   be   of   lower  precedence,
  700.           unless the subexpression is explicitly  bracketed  (which   gives
  701.           it  zero  precedence).  With  an operator of type `xfy', only the
  702.           first or left-hand subexpression must  be  of  lower  precedence;
  703.           the  second can be of the same  precedence  as the main operator;
  704.           and vice versa for an operator of type `yfx'.
  705.  
  706.                For example, if the operators `+' and `-' both   have   type
  707.           `yfx'  and  are  of  the  same  precedence,  then  the expression
  708.           ``a-b+c'' is valid, and means ``(a-b)+c'', i.e.  ``+(-(a,b),c)''.
  709.           Note  that the expression would be invalid if the  operators  had
  710.           type `xfx', and would mean ``a-(b+c)'', i.e. ``-(a,+(b,c))'',  if
  711.           the types were both `xfy'.
  712.  
  713.                The possible types for a prefix operator are
  714.               fx        fy
  715.  
  716.           and for a postfix operator they are
  717.               xf        yf
  718.  
  719.           The meaning of the types should be clear by  analogy  with  those
  720.           for infix  operators.   As  an example, if `not' were declared as
  721.           a prefix operator of type `fy', then
  722.               not not P
  723.  
  724.           would be a permissible way to write "not(not(P))". If  the   type
  725.           were `fx', the preceding expression would not be legal, although
  726.               not P
  727.  
  728.                                          18
  729.  
  730.  
  731.  
  732.  
  733.  
  734.           would still be a permissible form for "not(P)".
  735.  
  736.                In SB-Prolog, a functor named  name  is   declared   as   an
  737.           operator  of  type  type and precedence precedence by calling the
  738.           evaluable predicate op:
  739.                       | ?- op(precedence, type, name).
  740.  
  741.           The argument name can also be a list of names of operators of the
  742.           same type and precedence.
  743.  
  744.                It is possible to have more than one operator of  the   same
  745.           name, so long as they are of different kinds, i.e.  infix, prefix
  746.           or postfix.  An operator of any kind may be redefined  by  a  new
  747.           declaration   of   the  same   kind.    This   applies equally to
  748.           operators which are provided as standard in SB-Prolog, namely:
  749.  
  750.           r  r  r  l.   :-   op(  1200,   xfx,    [   :-,   -->   ]).    :-
  751.           op(  1200,   fx,     [  :- ]).  :- op(  1198,   xfx,    [ ::- ]).
  752.           :-  op(  1150,    fy,     [  mode,  public,   dynamic   ]).    :-
  753.           op(  1100,   xfy,    [  ;  ]).   :- op(  1050,   xfy,    [ -> ]).
  754.           :- op(  1000,   xfy,    [ ',' ]).    /*  See  note  below  */  :-
  755.           op(  900,    fy,     [    not,    \+,    spy,   nospy   ]).    :-
  756.           op(  700,    xfx,    [ =, is, =.., ==, \==,  @<,  @>,  @=<,  @>=,
  757.                                      =:=, =\=, <, >, =<, >=, ?=, \= ]).  :-
  758.           op(  661,    xfy,    [ `.' ]).  :- op(  500,    yfx,    [  +,  -,
  759.           /\,   \/   ]).    :-   op(  500,    fx,     [   +,   -   ]).   :-
  760.           op(  400,    yfx,    [   *,   /,   //,    <<,    >>    ]).     :-
  761.           op(  300,    xfx,    [ mod ]).  :- op(  200,    xfy,    [ ^ ]).
  762.  
  763.  
  764.                Operator declarations are most usefully placed in directives
  765.           at  the  top  of  your  program files. In this case the directive
  766.           should be a command as shown  above.  Another  common  method  of
  767.           organisation  is  to  have  one  file just containing commands to
  768.           declare all the necessary operators. This  file  is  then  always
  769.  
  770.                                          19
  771.  
  772.  
  773.  
  774.  
  775.  
  776.           consulted first.
  777.  
  778.                Note that a  comma  written  literally  as   a   punctuation
  779.           character can be used as though it were an infix operator of pre-
  780.           cedence 1000 and type `xfy':
  781.               X,Y    ','(X,Y)
  782.  
  783.           represent the same compound term.  But note that a comma  written
  784.           as  a quoted atom is not a standard operator.
  785.  
  786.                Note also that the  arguments  of  a  compound  term   writ-
  787.           ten   in standard  syntax must be expressions of precedence below
  788.           1000. Thus it is necessary to parenthesize the expression  "P  :-
  789.           Q" in
  790.               assert((P :- Q))
  791.  
  792.           The following syntax  restrictions  serve   to  remove  potential
  793.           ambiguity associated with prefix operators.
  794.  
  795.                In a term written in standard syntax, the  principal   func-
  796.                tor   and its  following  "("  must  not be separated by any
  797.                whitespace.  Thus
  798.                    point (X,Y,Z)
  799.  
  800.                is invalid syntax (unless point were declared  as  a  prefix
  801.                operator).
  802.  
  803.                If the argument of a prefix  operator  starts  with  a  "(",
  804.                this   "("  must   be   separated   from  the operator by at
  805.                least one space or other non-printable character.  Thus
  806.  
  807.                                          20
  808.  
  809.  
  810.  
  811.  
  812.                    :-(p;q),r.
  813.  
  814.                (where `:-' is the prefix operator) is invalid  syntax,  and
  815.                must be written as
  816.                    :- (p;q),r.
  817.  
  818.                If a prefix  operator  is  written  without   an   argument,
  819.                as   an  ordinary   atom,   the   atom   is  treated  as  an
  820.                expression of the same precedence as  the  prefix  operator,
  821.                and   must   therefore  be  bracketed where necessary.  Thus
  822.                the brackets are necessary in
  823.                    X = (?-)
  824.  
  825.           4.  SB-Prolog: Operational Semantics
  826.  
  827.  
  828.           4.1.  Standard Execution Behaviour
  829.  
  830.  
  831.           The normal execution behaviour of  SB-Prolog  follows  the  usual
  832.           left  to right order of literals within a clause, and the textual
  833.           top to bottom order of clauses for a predicate.  This corresponds
  834.           to  a depth first search of the leftmost SLD-tree for the program
  835.           and the given query.  Unification without occurs check  is  used,
  836.           and  execution  backtracks  to  the most recent choice point when
  837.           unification fails.
  838.  
  839.  
  840.  
  841.  
  842.                                          21
  843.  
  844.  
  845.  
  846.  
  847.  
  848.           4.2.  Cuts and If-Then-Else
  849.  
  850.  
  851.           This standard execution behaviour of  SB-Prolog  can  be  changed
  852.           using  constructs like cut (`!') and if-then-else (`->').  In SB-
  853.           Prolog, cuts are usually treated as  hard,  i.e.  discard  choice
  854.           points  of  all the literals to the left of the cut in the clause
  855.           containing the cut being executed, and also the choice point  for
  856.           the  parent predicate, i.e.  any remaining clauses for the predi-
  857.           cate containing the cut being executed.  There  are  some  situa-
  858.           tions,  however,  where  the  scope  of a cut is restricted to be
  859.           smaller than this.  Restrictions apply under the following condi-
  860.           tions:
  861.  
  862.           (1)  The cut occurs in a term which has been constructed at  run-
  863.                time and called through call/1, e.g. in
  864.                         ..., X = (p(Y), !, q(Y)), ..., call(X), ...
  865.  
  866.                In this case, the scope of  the  cut  is  restricted  to  be
  867.                within  the  call,  unless  one  of the following cases also
  868.                apply and serve to restrict its scope further.
  869.  
  870.           (2)  The cut occurs in a negated goal, or within the scope of the
  871.                test  of  an  if-then-else  (in  an if-then-else of the form
  872.                ``Test -> TruePart ;  FalsePart'',  the  test  is  the  goal
  873.                Test).   In  these cases, the scope of the cut is restricted
  874.                to be within the negation or the test of  the  if-then-else,
  875.                respectively.
  876.  
  877.  
  878.                                          22
  879.  
  880.  
  881.  
  882.  
  883.  
  884.           In cases involving nested occurrences of  these  situations,  the
  885.           scope  of  the  cut  is  restricted  to that for the deepest such
  886.           nested construct, i.e. most restricted.  For example, in the con-
  887.           struct
  888.            ..., not( (p(X) -> not( (q(X), (r(X) -> s(X) ; (t(X), !, u(X)))) )) ), ...
  889.  
  890.           the scope of the cut is restricted to  the  inner  negation,  and
  891.           does  not  affect  any choice point that may have been set up for
  892.           p(X).
  893.  
  894.           4.3.  Unification of Floating Point Numbers
  895.  
  896.  
  897.           As far as unification is concerned, no type distinction  is  made
  898.           between integers and floating point numbers, and no explicit type
  899.           conversion is necessary when unifying an integer  with  a  float.
  900.           However,  due  to the finite precision representation of floating
  901.           point numbers and cumulative round-off errors in  floating  point
  902.           arithmetic,  comparisons involving floating point numbers may not
  903.           always give the expected results.  For the same reason, users are
  904.           warned  that indexing on predicate arguments (see Section 15) may
  905.           not give the expected  results  if  floating  point  numbers  are
  906.           involved.
  907.  
  908.           5.  Evaluable Predicates
  909.  
  910.  
  911.           This section describes (most of) the  evaluable  predicates  pro-
  912.           vided  by  SB-Prolog.   These  can be divided into three classes:
  913.  
  914.                                          23
  915.  
  916.  
  917.  
  918.  
  919.  
  920.           inline predicates, builtin predicates and library predicates.
  921.  
  922.                Inline predicates represent ``primitive'' operations in  the
  923.           WAM.   Calls to inline predicates are compiled into a sequence of
  924.           WAM instructions in-line, i.e. without actually making a call  to
  925.           the  predicate.   Thus,  for example, relational predicates (>/2,
  926.           >=/2, etc.) compile to, essentially, a subtraction and  a  condi-
  927.           tional  branch.   Inline  predicates  cannot  be redefined by the
  928.           user.  Table 1 lists the SB-Prolog inline predicates.
  929.  
  930.                Unlike inline predicates, builtin predicates are implemented
  931.           by  C  functions  in  the  simulator, and accessed via the inline
  932.           predicate `_$builtin'/1.  Thus, if a builtin predicate foo/3  was
  933.           defined  as builtin number 38, there would be a definition in the
  934.           system of the form
  935.  
  936.                       foo(X,Y,Z) :- '_$builtin'(38).
  937.  
  938.  
  939.                In effect, a builtin is simply a segment of code in a  large
  940.           case   (i.e.  switch)  statement.   Each  builtin  is  identified
  941.  
  942.           center tab(%) ; l l l l.  arg/3%=/2%</2%=</2 >=/2%>/2%/\/2%`\/'/2
  943.           <</2%>>/2%=:=/2%=\=/2                            is/2%?=/2%\=%\/1
  944.           `_$builtin'/1%`_$call'/1%nonvar/1%var/1
  945.           integer/1%real/1%halt/0%true/0 fail/0% % %
  946.  
  947.                        Table 1: Inline Predicates of SB-Prolog
  948.  
  949.  
  950.  
  951.                                          24
  952.  
  953.  
  954.  
  955.  
  956.  
  957.           internally by an integer, referred to as its ``builtin  number'',
  958.           associated with it.  The code for a builtin with builtin number k
  959.           corresponds to the k[th.] case  in  the  switch  statement.   SB-
  960.           Prolog limits the total number of builtins to 256.
  961.  
  962.                Builtins, unlike inline predicates,  can be redefined by the
  963.           user.   For  example,  the predicate foo/3 above can be redefined
  964.           simply by compiling the new definition into a directory such that
  965.           during  dynamic  loading, the new definition would be encountered
  966.           first and loaded.
  967.  
  968.                A list of the  builtins  currently  provided  is  listed  in
  969.           Appendix  1.   Section 7.4 describes the procedure to be followed
  970.           in order to define new builtin predicates.
  971.  
  972.                Like builtin predicates,  library  predicates  may  also  be
  973.           redefined  by the user.  The essential difference between builtin
  974.           and library predicates is that whereas the former are coded  into
  975.           the simulator in C, the latter are written in Prolog.
  976.  
  977.           5.1.  Input and Output
  978.  
  979.  
  980.           Input and output are done with respect to the current  input  and
  981.           output  streams.   These  can  be set, reset or checked using the
  982.           file handling predicates described below.  The default input  and
  983.           output  streams are denoted by user, and refer to the user's ter-
  984.           minal.
  985.  
  986.  
  987.                                          25
  988.  
  989.  
  990.  
  991.  
  992.  
  993.           5.1.1.  File Handling
  994.  
  995.  
  996.           see(F)
  997.  
  998.                F becomes the current input stream.  F must be  instantiated
  999.                to an atom at the time of the call.
  1000.  
  1001.           seeing(F) F is unified with the name of the current input file.
  1002.  
  1003.           seen Closes the current input stream.
  1004.  
  1005.           tell(F)
  1006.                F becomes the current output stream.  F must be instantiated
  1007.                to an atom at the time of the call.
  1008.  
  1009.           telling(F)
  1010.                F is unified with the name of the current output file.
  1011.  
  1012.           told
  1013.  
  1014.                Closes the current output stream.
  1015.  
  1016.           $exists(F)
  1017.                Succeeds if file F exists.
  1018.  
  1019.           5.1.2.  Term I/O
  1020.  
  1021.  
  1022.           read(X)
  1023.  
  1024.                The next term, delimited by a full stop (i.e.   a  "."  fol-
  1025.                lowed   by  a carriage-return or  a  space),  is  read  from
  1026.  
  1027.                                          26
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.                the current input stream and unified with X. The  syntax  of
  1034.                the  term  must accord  with  current operator declarations.
  1035.                If a call read(X) causes the end of the current input stream
  1036.                to  be reached, X is unified  with  the  atom `end_of_file'.
  1037.                Further  calls  to read for the same stream will then  cause
  1038.                an error failure.
  1039.  
  1040.           write(X)
  1041.                The term X is written to the current output stream   accord-
  1042.                ing  to operator declarations in force.
  1043.  
  1044.           display(X)
  1045.                The term X is displayed on the terminal.
  1046.  
  1047.           writeq(Term)
  1048.                Similar to write(Term), but the names of atoms and  functors
  1049.                are  quoted where necessary to make the result acceptable as
  1050.                input to read.
  1051.  
  1052.           print(Term)
  1053.                Prints out the term Term onto  the  current  output  stream.
  1054.                This  predicate  provides  a handle for user-defined pretty-
  1055.                printing.  If Term is a variable then it  is  written  using
  1056.                write/1;  otherwise,,  if a user-defined predicate portray/1
  1057.                is defined, then a call is made to portray(Term); otherwise,
  1058.                print/1 is equivalent to write/1.
  1059.  
  1060.           writename(Term)
  1061.                If Term is an uninstantiated variable, its name, which looks
  1062.  
  1063.                                          27
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.                a  lot like an address in memory, is written out; otherwise,
  1070.                the principal functor of Term is written out.
  1071.  
  1072.           writeqname(Term)
  1073.                As for writename, but the names are quoted where necessary.
  1074.  
  1075.           print_al(N, A)
  1076.  
  1077.                Prints A (which must be an atom or a number) left-aligned in
  1078.                a field of width N, with blanks padded to the right.  If A's
  1079.                print name is longer than the  field  width  N,  then  A  is
  1080.                printed but with no right padding.
  1081.  
  1082.           print_ar(N, A)
  1083.  
  1084.                Prints A (which must be an atom or a  number)  right-aligned
  1085.                in  a  field of width N, with blanks padded to the left.  If
  1086.                A's print name is longer than the field width N, then  A  is
  1087.                printed but with no left padding.
  1088.  
  1089.           portray_term(Term)
  1090.  
  1091.                Writes out the term  Term  on  the  current  output  stream.
  1092.                Variables  are treated specially: an uninstantiated variable
  1093.                is printed out as Vn, where n is a number.
  1094.  
  1095.           portray_clause(Term)
  1096.  
  1097.                Writes out the term Term, interpreted as a  clause,  on  the
  1098.                current   output   stream.   Variables  are  treated  as  in
  1099.                portray_term/1.
  1100.  
  1101.                                          28
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.           5.1.3.  Character I/O
  1108.  
  1109.  
  1110.           nl
  1111.  
  1112.                A new line is started on the current output stream.
  1113.  
  1114.           get0(N)
  1115.                N is the ASCII code of the next character from  the  current
  1116.                input stream. If the current input stream reaches its end of
  1117.                file, a -1 is returned (however,  unlike  in  C-Prolog,  the
  1118.                input stream is not closed on encountering end-of-file).
  1119.  
  1120.           get(N)
  1121.                N is the ASCII  code  of  the   next   non-blank   printable
  1122.                character  from  the  current  input stream. It has the same
  1123.                behaviour as get0 on end of file.
  1124.  
  1125.           put(N)
  1126.                ASCII character code N  is  output  to  the  current  output
  1127.                stream.  N must be an integer.
  1128.  
  1129.           tab(N)
  1130.                N spaces are output to the current output stream.  N must be
  1131.                an integer.
  1132.  
  1133.           5.2.  Arithmetic
  1134.  
  1135.  
  1136.           Arithmetic is performed by  evaluable predicates  which  take  as
  1137.           arguments    arithmetic  expressions    and   evaluate  them.  An
  1138.  
  1139.                                          29
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.           arithmetic expression is a term  built  from  evaluable functors,
  1146.           numbers  and variables.  At  the  time  of evaluation, each vari-
  1147.           able in an arithmetic expression must be bound to a number or  to
  1148.           an  arithmetic  expression.  Each evaluable functor stands for an
  1149.           arithmetic  operation.
  1150.  
  1151.                The evaluable  functors  are  as  follows,  where  X  and  Y
  1152.           are arithmetic expressions.
  1153.  
  1154.           X + Y
  1155.  
  1156.                addition.
  1157.  
  1158.           X - Y
  1159.  
  1160.                subtraction.
  1161.  
  1162.           X * Y
  1163.  
  1164.                multiplication.
  1165.  
  1166.           X / Y
  1167.  
  1168.                division.
  1169.  
  1170.           X // Y
  1171.  
  1172.                integer division.
  1173.  
  1174.           X mod Y
  1175.  
  1176.                X (integer) modulo Y.
  1177.  
  1178.  
  1179.                                          30
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.           -X
  1186.  
  1187.                unary minus.
  1188.  
  1189.           X /\ Y
  1190.  
  1191.                integer bitwise conjunction.
  1192.  
  1193.           X \/ Y
  1194.  
  1195.                integer bitwise disjunction.
  1196.  
  1197.           X << Y
  1198.  
  1199.                integer bitwise left shift of X by Y places.
  1200.  
  1201.           X >> Y
  1202.  
  1203.                integer bitwise right shift of X by Y places.
  1204.  
  1205.           \X
  1206.  
  1207.                integer bitwise negation.
  1208.  
  1209.           integer(X)
  1210.  
  1211.                If X is bound to a floating point number, this evaluates  to
  1212.                the  smallest  integer not greater than X.  (Syntactic sugar
  1213.                for floor/2 below.)
  1214.  
  1215.           float(X)
  1216.  
  1217.                If X is bound to an integer, evaluates to the smallest float
  1218.                not greater than X.  (Syntactic sugar for floor/2 below.)
  1219.  
  1220.                                          31
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.           exp(X)
  1227.  
  1228.                If X is instantiated to a number, evaluates to e[X], where e
  1229.                = 2.71828 ...  (Syntactic sugar for exp/2 below.)
  1230.  
  1231.           ln(X)
  1232.  
  1233.                If X is instantiated to a positive number, this evaluates to
  1234.                the  natural  logarithm  of  X.  (Syntactic  sugar for exp/2
  1235.                below.)
  1236.  
  1237.           sin(X)
  1238.  
  1239.                If X is instantiated to a number (representing an  angle  in
  1240.                radians),  evaluates  to sin(X).  (Syntactic sugar for sin/2
  1241.                below.)
  1242.  
  1243.           arcsin(X)
  1244.  
  1245.                If X is instantiated to a number  between  -i~i~/2      and  i~i~/2,
  1246.                evaluates to sin[-1](X).  (Syntactic sugar for sin/2 below.)
  1247.  
  1248.                As far as unification is concerned, no type  distinction  is
  1249.           made between integers and floating point numbers, and no explicit
  1250.           type conversion is necessary when  unifying  an  integer  with  a
  1251.           float.   However,  due  to the finite precision representation of
  1252.           floating point numbers and cumulative round-off errors in  float-
  1253.           ing   point  arithmetic,  comparisons  involving  floating  point
  1254.           numbers may not always give the expected results.
  1255.  
  1256.  
  1257.  
  1258.                                          32
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.                The arithmetic evaluable predicates are as follows, where  X
  1265.           and  Y  stand  for  arithmetic  expressions, and Z for some term.
  1266.           Note that this means that is only evaluates one of its  arguments
  1267.           as  an  arithmetic  expression (the right-hand side one), whereas
  1268.           all the comparison predicates evaluate both their arguments.
  1269.  
  1270.           Z is X
  1271.  
  1272.                Arithmetic expression X is evaluated and the result, is uni-
  1273.                fied  with  Z.  Fails  if X is not an arithmetic expression.
  1274.                Unlike many other Prolog systems, variables in  the  expres-
  1275.                sion  X may be bound to other arithmetic expressions as well
  1276.                as to numbers.
  1277.  
  1278.           eval(E, X)
  1279.                Evaluates the arithmetic expression E and unifies the result
  1280.                with  the  term  X.  Fails if E is not an arithmetic expres-
  1281.                sion. (Thus, eval/2 is, except  for  the  switched  argument
  1282.                order,  the same as is/2.  It's around mainly for historical
  1283.                reasons.)
  1284.  
  1285.           X =:= Y
  1286.  
  1287.                The values of X and Y are equal.  If either X or  Y  involve
  1288.                compound  subexpressions  that  are created at runtime, they
  1289.                should first be evaluated using eval/2.
  1290.  
  1291.           X =\= Y
  1292.  
  1293.  
  1294.  
  1295.                                          33
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.                The values of X and Y are not  equal.   If  either  X  or  Y
  1302.                involve compound subexpressions that are created at runtime,
  1303.                they should first be evaluated using eval/2.
  1304.  
  1305.           X < Y
  1306.  
  1307.                The value of X is less than the value of Y.  If either X  or
  1308.                Y  involve  compound subexpressions that are created at run-
  1309.                time, they should first be evaluated using eval/2.
  1310.  
  1311.           X > Y
  1312.  
  1313.                The value of X is greater than the value of Y.  If either  X
  1314.                or  Y  involve  compound  subexpressions that are created at
  1315.                runtime, they should first be evaluated using eval/2.
  1316.  
  1317.           X =< Y
  1318.  
  1319.                The value of X is less than or equal to the value of Y.   If
  1320.                either  X  or  Y  involve  compound  subexpressions that are
  1321.                created at runtime, they should  first  be  evaluated  using
  1322.                eval/2.
  1323.  
  1324.           X >= Y
  1325.  
  1326.                The value of X is greater than or equal to the value  of  Y.
  1327.                If  either  X  or Y involve compound subexpressions that are
  1328.                created at runtime, they should  first  be  evaluated  using
  1329.                eval/2.
  1330.  
  1331.  
  1332.  
  1333.                                          34
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.           floor(X, Y)
  1340.  
  1341.                If X is a floating point number in the call and Y  is  free,
  1342.                then Y is instantiated to the largest integer whose absolute
  1343.                value is not greater than the absolute value of X; if  X  is
  1344.                uninstantiated  in  the  call and Y is an integer, then X is
  1345.                instantiated to the smallest float not less than Y.
  1346.  
  1347.           floatc(F, M, E)
  1348.  
  1349.                If F is a number while M and E  are  uninstantiated  in  the
  1350.                call, then M is instantiated to a float m (of magnitude less
  1351.                than 1), and E to an integer n, such that
  1352.                                       F = m * 2[n].
  1353.  
  1354.                If F is uninstantiated in the call while M is a float and  E
  1355.                an integer, then F becomes instantiated to M * 2[E].
  1356.  
  1357.           exp(X, Y)
  1358.  
  1359.                If X is instantiated to a number and Y is uninstantiated  in
  1360.                the  call,  then  Y  is  instantiated  to  e[X]  (where  e =
  1361.                2.71828...); if X is uninstantiated in the call while  Y  is
  1362.                instantiated to a positive number, then X is instantiated to
  1363.                log<e>(Y).
  1364.  
  1365.           square(X, Y)
  1366.  
  1367.                If X is instantiated to a number while Y  is  uninstantiated
  1368.                in  the  call,  then Y becomes instantiated to X[2]; if X is
  1369.                uninstantiated in the call while  Y  is  instantiated  to  a
  1370.  
  1371.                                          35
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.                positive number, then X becomes instantiated to the positive
  1378.                square root of Y (if Y is negative in the  call,  X  becomes
  1379.                instantiated to 0.0).
  1380.  
  1381.           sin(X, Y)
  1382.  
  1383.                If X is instantiated to a number (representing an  angle  in
  1384.                radians) and Y is uninstantiated in the call, then Y becomes
  1385.                instantiated to sin(X) (the user should check the  magnitude
  1386.                of  X  to make sure that the result is meaningful).  If Y is
  1387.                instantiated to a number between -i~i~/2 and  i~i~/2  and  X  is
  1388.                uninstantiated  in  the call, then X becomes instantiated to
  1389.                sin[-1](Y).
  1390.  
  1391.           5.3.  Convenience
  1392.  
  1393.  
  1394.           P , Q
  1395.  
  1396.                P and then Q.
  1397.  
  1398.           P ; Q
  1399.  
  1400.                P or Q.
  1401.  
  1402.           true
  1403.  
  1404.                Always  succeeds.
  1405.  
  1406.           X = Y
  1407.  
  1408.  
  1409.  
  1410.                                          36
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.                Defined as if by the clause " Z=Z ", i.e. X and Y  are  uni-
  1417.                fied.
  1418.  
  1419.           X \= Y
  1420.  
  1421.                Succeeds if X and Y are not unifiable, fails if X and Y  are
  1422.                unifiable.  It is thus equivalent to not(X = Y), but is sig-
  1423.                nificantly more efficient.
  1424.  
  1425.           X ?= Y
  1426.  
  1427.                Succeeds if X and Y are unifiable and fails if they are not,
  1428.                but  does  not  instantiate  any  variables.  Thus, it tests
  1429.                whether X and Y are unifiable.  Equivalent  to  not(not(X  =
  1430.                Y)), but is significantly more efficient.
  1431.  
  1432.           5.4.  Extra Control
  1433.  
  1434.  
  1435.           !
  1436.  
  1437.                Cut (discard) all choice points made since the  parent  goal
  1438.                started  execution.  (The scope of cut in different contexts
  1439.                is discussed in Section 4.2).
  1440.  
  1441.           not P
  1442.  
  1443.                If the goal P has a  solution,  fail,   otherwise   succeed.
  1444.                It  is defined as if by
  1445.                    not(P) :- P, !, fail.
  1446.                    not(_).
  1447.  
  1448.  
  1449.                                          37
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.           P -> Q ; R
  1456.                Analogous to "if P then Q else R" i.e.  defined as if by
  1457.                    P -> Q ; R :- P, !, Q.
  1458.                    P -> Q ; R :- R.
  1459.  
  1460.           P -> Q
  1461.                When occurring other  than  as  one  of   the   alternatives
  1462.                of  a disjunction, is equivalent to
  1463.                    P -> Q ; fail.
  1464.  
  1465.           repeat
  1466.                Generates an  infinite  sequence  of  backtracking  choices.
  1467.                It is defined by the clauses:
  1468.                    repeat.
  1469.                    repeat :- repeat.
  1470.  
  1471.           fail Always fails.
  1472.  
  1473.           5.5.  Meta-Logical
  1474.  
  1475.  
  1476.           var(X)
  1477.  
  1478.                Tests whether X is currently instantiated to a variable.
  1479.  
  1480.           nonvar(X)
  1481.                Tests whether X is currently instantiated to a  non-variable
  1482.                term.
  1483.  
  1484.  
  1485.  
  1486.                                          38
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.           atom(X)
  1493.                Checks that X is   currently   instantiated   to   an   atom
  1494.                (i.e.    a  non-variable  term  of  arity  0,  other  than a
  1495.                number).
  1496.  
  1497.           integer(X)
  1498.                Checks that X is currently instantiated to an integer.
  1499.  
  1500.           real(X)
  1501.  
  1502.                Checks that X is currently instantiated to a floating  point
  1503.                number.
  1504.  
  1505.           float(X)
  1506.  
  1507.                Same as real/1, checks that X is currently instantiated to a
  1508.                floating point number.
  1509.  
  1510.           number(X)
  1511.                Checks that X is currently instantiated to  a  number,  i.e.
  1512.                that it is either an integer or a real.
  1513.  
  1514.           atomic(X)
  1515.                Checks that X  is  currently  instantiated  to  an  atom  or
  1516.                number.
  1517.  
  1518.           structure(X)
  1519.  
  1520.                Checks that X is currently instantiated to a compound  term,
  1521.                i.e. to a nonvariable term that is not atomic.
  1522.  
  1523.  
  1524.                                          39
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.           is_buffer(X)
  1531.  
  1532.                Succeeds if X is instantiated to a buffer.
  1533.  
  1534.           functor(T, F, N)
  1535.  
  1536.                The principal functor of term T has  name  F  and  arity  N,
  1537.                where  F is  either  an  atom or, provided N is 0, a number.
  1538.                Initially, either T must be instantiated to a  non-variable,
  1539.                or  F  and  N   must be   instantiated   to,   respectively,
  1540.                either  an  atom  and  a non-negative integer or an  integer
  1541.                and  0. If these conditions are not satisfied, an error mes-
  1542.                sage is given.  In the case where  T  is  initially  instan-
  1543.                tiated  to  a  variable,  the  result  of  the   call  is to
  1544.                instantiate  T  to the most general term having the  princi-
  1545.                pal functor indicated.
  1546.  
  1547.           arg(I, T, X)
  1548.  
  1549.                Initially, I must be instantiated to a positive integer  and
  1550.                T  to a  compound  term.  The result of the call is to unify
  1551.                X with the Ith argument of term  T.   (The   arguments   are
  1552.                numbered from  1 upwards.) If the initial conditions are not
  1553.                satisfied or I is out of range, the call merely fails.
  1554.  
  1555.           X =.. Y
  1556.                Y is a list whose head is  the  atom  corresponding  to  the
  1557.                principal  functor  of X and whose tail is the argument list
  1558.                of that functor in X. E.g.
  1559.  
  1560.  
  1561.                                          40
  1562.  
  1563.  
  1564.  
  1565.  
  1566.                    product(0,N,N-1) =.. [product,0,N,N-1]
  1567.                    N-1 =.. [-,N,1]
  1568.                    product =.. [product]
  1569.  
  1570.                If X is instantiated to a variable, then Y must  be  instan-
  1571.                tiated  either to a list of determinate length whose head is
  1572.                an atom, or to a list of length 1 whose head is a number.
  1573.  
  1574.           name(X,L)
  1575.                If X is an atom or a number then L is a list  of  the  ASCII
  1576.                codes of the characters comprising the name of X. E.g.
  1577.                    name(product,[112,114,111,100,117,99,116])
  1578.  
  1579.                i.e.  name(product,"product").
  1580.  
  1581.           If X is instantiated to a variable, L must be instantiated  to  a
  1582.           list of ASCII character codes.  E.g.
  1583.               | ?- name(X,[104,101,108,108,111])).
  1584.               X = hello
  1585.               | ?- name(X,"hello").
  1586.               X = hello
  1587.  
  1588.           call(X)
  1589.                If X is a nonvariable term in the program text, then  it  is
  1590.                executed  exactly  as  if  X  appeared  in  the program text
  1591.                instead of call(X), e.g.
  1592.                     ..., p(a), call( (q(X), r(Y)) ), s(X), ...
  1593.  
  1594.                is equivalent to
  1595.                     ..., p(a), q(X), r(Y), s(X), ...
  1596.  
  1597.  
  1598.                                          41
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.                However, if X is a variable in the program text, then if  at
  1605.                runtime  X  is instantiated to a term which would be accept-
  1606.                able as the body of a clause, the goal call(X)  is  executed
  1607.                as  if that term appeared textually in place of the call(X),
  1608.                except that any  cut (`!') occurring in X will  remove  only
  1609.                those  choice  points  in  X.  If X is not  instantiated  as
  1610.                described above, an error message is printed and call fails.
  1611.  
  1612.           X    (where X is a variable) Exactly the same as  call(X).   How-
  1613.                ever,  we  prefer  the explicit usage of call/1 as good pro-
  1614.                gramming practice, and the  use  of  a  top  level  variable
  1615.                subgoal elicits a warning from the compiler.
  1616.  
  1617.           conlength(C, L)
  1618.  
  1619.                Succeeds if the length of the print name of the  constant  C
  1620.                (which  can  be an atom, buffer or integer), in bytes, is L.
  1621.                If C is a buffer (see Section 5.8), it is the length of  the
  1622.                buffer;  if C is an integer, it is the length of the decimal
  1623.                representation of that integer, i.e., the  number  of  bytes
  1624.                that a $writename will use.
  1625.  
  1626.           5.6.  Sets
  1627.  
  1628.  
  1629.           When  there  are  many solutions to a problem, and when all those
  1630.           solutions  are  required  to  be  collected  together,  this  can
  1631.           be  achieved  by  repeatedly backtracking  and gradually building
  1632.           up  a  list of the solutions.  The following evaluable predicates
  1633.  
  1634.                                          42
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.           are provided to automate this process.
  1641.  
  1642.           setof(X, P, S)
  1643.  
  1644.                Read this as "S is the set of all instances of X  such  that
  1645.                P   is  provable''.   If  P  is  not  provable, setof(X,P,S)
  1646.                succeeds with S instantiated to the empty list [].  The term
  1647.                P  specifies  a  goal  or goals as in call(P). S is a set of
  1648.                terms represented as  a list  of those terms, without dupli-
  1649.                cates, in the standard order for terms (see Section 5.7). If
  1650.                there are uninstantiated variables in P which  do  not  also
  1651.                appear  in  X,  then a  call  to  this  evaluable  predicate
  1652.                may  backtrack,  generating   alternative   values   for   S
  1653.                corresponding  to different instantiations of the free vari-
  1654.                ables of P.  Variables occurring in P will not be treated as
  1655.                free if they are explicitly bound within P by an existential
  1656.                quantifier.  An existential quantification is written:
  1657.                    Y^Q
  1658.  
  1659.                meaning "there exists a Y such that Q is true", where  Y  is
  1660.                some  Prolog  term (usually, a variable, or tuple or list of
  1661.                variables).
  1662.  
  1663.           bagof(X, P, Bag)
  1664.  
  1665.                This is the same as setof except that the list (or  alterna-
  1666.                tive lists) returned will not be ordered,  and  may  contain
  1667.                duplicates.  If P is unsatisfiable, bagof  succeeds  binding
  1668.                Bag  to the empty list.  The effect of this relaxation is to
  1669.  
  1670.                                          43
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.                save considerable time and space in execution.
  1677.  
  1678.           findall(X, P, L)
  1679.  
  1680.                Similar to bagof/3, except that variables in P that  do  not
  1681.                occur  in  X are treated as local, and alternative lists are
  1682.                not returned for different bindings of such variables.   The
  1683.                list  L  is,  in  general, unordered, and may contain dupli-
  1684.                cates.  If P is unsatisfiable, findall succeeds binding S to
  1685.                the empty list.
  1686.  
  1687.           X^P
  1688.  
  1689.                The system recognises this as meaning  "there  exists  an  X
  1690.                such  that   P   is  true",  and  treats it as equivalent to
  1691.                call(P).  The use of this  explicit  existential  quantifier
  1692.                outside the setof and bagof constructs is superfluous.
  1693.  
  1694.           5.7.  Comparison of Terms
  1695.  
  1696.  
  1697.           These  evaluable  predicates  are  meta-logical.     They   treat
  1698.           uninstantiated variables as objects  with  values  which  may  be
  1699.           compared,  and  they  never instantiate  those  variables.   They
  1700.           should  not  be used when what you really want is arithmetic com-
  1701.           parison (Section 5.2)  or  unification.   The   predicates   make
  1702.           reference to a standard total ordering of terms, which is as fol-
  1703.           lows:
  1704.  
  1705.  
  1706.  
  1707.                                          44
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.                variables, in a standard order (roughly, oldest first -  the
  1714.                order  is not related to the names of variables);
  1715.  
  1716.                numbers, from -"infinity" to +"infinity";
  1717.  
  1718.                atoms, in alphabetical (i.e. ASCII) order;
  1719.  
  1720.                complex  terms, ordered first by arity, then by the name  of
  1721.                principal  functor,  then by the arguments (in left-to-right
  1722.                order).
  1723.  
  1724.           For example, here is a list of terms in the standard order:
  1725.               [ X, -9, 1, fie, foe, fum, X = Y, fie(0,2), fie(1,1) ]
  1726.  
  1727.           The basic predicates for comparison of arbitrary terms are:
  1728.  
  1729.           X == Y
  1730.  
  1731.                Tests if the terms currently  instantiating  X  and   Y  are
  1732.                literally identical  (in particular, variables in equivalent
  1733.                positions in the two terms must be identical).  For example,
  1734.                the question
  1735.                    | ?- X == Y.
  1736.  
  1737.                fails (answers "no") because X and Y  are   distinct   unin-
  1738.                stantiated variables.  However, the question
  1739.                    | ?- X = Y, X == Y.
  1740.  
  1741.                succeeds because the first goal unifies  the  two  variables
  1742.                (see page 42).
  1743.  
  1744.  
  1745.                                          45
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.           X \== Y
  1752.  
  1753.                Tests  if  the  terms  currently  instantiating  X   and   Y
  1754.                are not literally identical.
  1755.  
  1756.           T1 @< T2
  1757.  
  1758.                Term T1 is before term T2 in the standard order.
  1759.  
  1760.           T1 @> T2
  1761.  
  1762.                Term T1 is after term T2 in the standard order.
  1763.  
  1764.           T1 @=< T2
  1765.  
  1766.                Term T1 is not after term T2 in the standard order.
  1767.  
  1768.           T1 @>= T2
  1769.  
  1770.                Term T1 is not before term T2 in the standard order.
  1771.  
  1772.  
  1773.           Some further predicates involving comparison of terms are:
  1774.  
  1775.           compare(Op, T1, T2)
  1776.  
  1777.                The  result  of comparing terms T1 and T2 is Op,  where  the
  1778.                possible values for Op are:
  1779.                    `='   if T1 is identical to T2,
  1780.                    `<'   if T1 is before T2 in the standard order,
  1781.                    `>'   if T1 is after T2 in the standard order.
  1782.  
  1783.                Thus compare(=,T1,T2) is equivalent to T1 == T2.
  1784.  
  1785.                                          46
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.           sort(L1, L2)
  1792.  
  1793.                The elements of the list L1 are  sorted  into  the  standard
  1794.                order,  and  any  identical (i.e. `==') elements are merged,
  1795.                yielding  the  list L2.
  1796.  
  1797.           keysort(L1, L2)
  1798.  
  1799.                The list L1 must consist of items  of  the  form  Key-Value.
  1800.                These  items are sorted into order according to the value of
  1801.                Key, yielding the list L2.  No merging takes place.
  1802.  
  1803.           5.8.  Buffers
  1804.  
  1805.  
  1806.           SB-Prolog supports the concept of buffers.  A buffer is  actually
  1807.           a constant and the characters that make up the buffer is the name
  1808.           of the constant.  However, the symbol table entry for a buffer is
  1809.           not  hashed  and  thus  is not added to the obj-list, so two dif-
  1810.           ferent buffers will never unify.  Buffers can be allocated either
  1811.           in  permanent  space  or on the heap.  Buffers in permanent space
  1812.           stay there forever; buffers on the heap are deallocated when  the
  1813.           ``allocate buffer'' goal is backtracked over.
  1814.  
  1815.                A buffer allocated on  the  heap  can  either  be  a  simple
  1816.           buffer,  or  it can be allocated as a subbuffer of another buffer
  1817.           already on the heap.  A subbuffer will be  deallocated  when  its
  1818.           superbuffer is deallocated.
  1819.  
  1820.  
  1821.  
  1822.                                          47
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.                There are occasions  when  it  is  not  known,  in  advance,
  1829.           exactly  how  much space will be required and so how big a buffer
  1830.           should be allocated.  Sometimes this problem can be  overcome  by
  1831.           allocating  a  large  buffer  and then, after using as much as is
  1832.           needed, returning the rest of the buffer to the system. This  can
  1833.           be  done,  but only under very limited circumstances: a buffer is
  1834.           allocated from the end of the permanent space,  the  top  of  the
  1835.           heap,  or from the next available space in the superbuffer; if no
  1836.           more space has been used beyond the end of  the  buffer,  a  tail
  1837.           portion  of the buffer can be returned to the system. This opera-
  1838.           tion is called ``trimming'' the buffer.
  1839.  
  1840.                The following is a list of  library  predicates  for  buffer
  1841.           management:
  1842.  
  1843.  
  1844.           alloc_perm(Size, Buff)
  1845.                Allocates a buffer with a length Size in the permanent (i.e.
  1846.                program) area. Size must be bound to a number. On successful
  1847.                return, Buff will be bound to  the  allocated  buffer.   The
  1848.                buffer, being in the permanent area, is never de-allocated.
  1849.  
  1850.           alloc_heap(Size, Buff)
  1851.                Allocates a buffer of size Size on the heap and  binds  Buff
  1852.                to  it.  Since  it is on the heap, it will be deallocated on
  1853.                backtracking.
  1854.  
  1855.           trimbuff(Type, Buff, Newlen)
  1856.                This allows (in  some  very  restricted  circumstances)  the
  1857.  
  1858.                                          48
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.                changing of the size of a buffer. Type is 0 if the buffer is
  1865.                permanent, 1 if the buffer is  on  the  heap.  Buff  is  the
  1866.                buffer.   Newlen  is  an  integer: the size (which should be
  1867.                smaller than the original length of the buffer) to make  the
  1868.                buffer.  If  the  buffer  is at the top of the heap (if heap
  1869.                buffer) or the end of the program area (if  permanent)  then
  1870.                the  heap-top (or program area top) will be readjusted down.
  1871.                The length of the buffer will be modified to  Newlen.   This
  1872.                is (obviously) a very low-level primitive and is for hackers
  1873.                only to implement grungy stuff.
  1874.  
  1875.           conlength(Constant,Length)
  1876.  
  1877.                Succeeds if the length of the print  name  of  the  constant
  1878.                Constant  (which  can  be  an  atom,  buffer or integer), in
  1879.                bytes, is Length.  If Constant is a buffer, it is the length
  1880.                of  the  buffer; if Constant is an integer, it is the length
  1881.                of the decimal representation of  that  integer,  i.e.,  the
  1882.                number of bytes that a $writename will use.
  1883.  
  1884.           5.9.  Modification of the Program
  1885.  
  1886.  
  1887.           The predicates defined in this section allow modification of  the
  1888.           program  as  it is actually running.  Clauses can be added to the
  1889.           program (asserted) or removed from the program  (retracted).   At
  1890.           the  lowest  level,  the system supports the asserting of clauses
  1891.           with upto one literal in the body.  It does this by allocating  a
  1892.           buffer  and compiling code for the clause into that buffer.  Such
  1893.  
  1894.                                          49
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.           a buffer is called a ``clause reference'' (clref).  The clref  is
  1901.           then  added  to  a  chain  of  clrefs.  The chain of clrefs has a
  1902.           header, which is a small buffer called a ``predicate  reference''
  1903.           (prref),  which contains pointers to the beginning and end of its
  1904.           chain of clrefs.  Clause references are quite similar to  ``data-
  1905.           base references'' of C-Prolog, and can be called.
  1906.  
  1907.                When clauses are added to the  program  through  assert,  an
  1908.           index  is  normally created on the principal functor of the first
  1909.           argument in the head of the clause.  The argument  on  which  the
  1910.           index  is being created may be changed via the index/3 directive.
  1911.           In particular, if no index is desired on a predicate, this should
  1912.           be specified using the index/3 directive with the argument number
  1913.           set to zero, e.g. if no index is desired on  a  predicate  foo/3,
  1914.           then the directive
  1915.               :- index(foo, 3, 0).
  1916.  
  1917.           should be specified.
  1918.  
  1919.                The predicates that can be used to modify  the  program  are
  1920.           the following:
  1921.  
  1922.  
  1923.           assert(C)
  1924.  
  1925.                The current instance of C is interpreted as a clause and  is
  1926.                added  to  the program (with new private variables replacing
  1927.                any uninstantiated variables), at the end  of  the  list  of
  1928.                clauses  for  that  predicate.   C must be instantiated to a
  1929.  
  1930.                                          50
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.                non-variable.
  1937.  
  1938.           assert(C, Ref)
  1939.  
  1940.                As for assert/1, but also unifies Ref with the clause refer-
  1941.                ence of the clause asserted.
  1942.  
  1943.           asserti(C,N)
  1944.  
  1945.                The current instance of  C,  interpreted  as  a  clause,  is
  1946.                asserted to the program with an index on its N[th] argument.
  1947.                If N is zero, no index is created.
  1948.  
  1949.           asserta(C)
  1950.  
  1951.                Similar to assert(C), except that the new clause becomes the
  1952.                first clause of the procedure concerned.
  1953.  
  1954.           asserta(C, Ref)
  1955.  
  1956.                Similar to asserta(C), but also unifies Ref with the  clause
  1957.                reference of the clause asserted.
  1958.  
  1959.           assertz(C)
  1960.  
  1961.                Similar to assert(C), except that the new clause becomes the
  1962.                last clause of the procedure concerned.
  1963.  
  1964.           assertz(C, Ref)
  1965.  
  1966.                Similar to assertz(C), but also unifies Ref with the  clause
  1967.                reference of the clause asserted.
  1968.  
  1969.  
  1970.                                          51
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.           assert_union(P, Q)
  1977.  
  1978.                The clauses for Q are added to the clauses for P.  For exam-
  1979.                ple, the call
  1980.                            | ?- assert_union(p(X,Y),q(X,Y)).
  1981.  
  1982.                has the effect of adding the rule
  1983.                    p(X,Y) :- q(X,Y).
  1984.  
  1985.                as the last rule defining p/2.  If  P  is  not  defined,  it
  1986.                results in the call to Q being the only clause for P.
  1987.  
  1988.                The variables in the arguments  to  assert_union/2  are  not
  1989.                significant, e.g. the above would have been equivalent to
  1990.                            | ?- assert_union(p(Y,X),q(X,Y)).
  1991.                    or
  1992.                            | ?- assert_union(p(_,_),q(_,_)).
  1993.  
  1994.                However, the arities of the  two  predicates  involved  must
  1995.                match, e.g.  even though the goal
  1996.                            | ?- assert_union(p(X,Y), r(X,Y,Z)).
  1997.  
  1998.                will succeed, the predicate p/2 will not in any  way  depend
  1999.                on the clauses for r/3.
  2000.  
  2001.           assert(Clause,AZ,Index,Clref)
  2002.  
  2003.                Asserts a clause to a predicate.  Clause is  the  clause  to
  2004.                assert.   AZ  is  0 for insertion as the first clause, 1 for
  2005.                insertion as the last clause.  Index is the  number  of  the
  2006.                argument  on  which to  index (0 for no indexing).  Clref is
  2007.  
  2008.                                          52
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.                returned   as  the   clause  reference  of  the  fact  newly
  2015.                asserted.   If  the  main  functor symbol of Clause has been
  2016.                declared (by $assertf_alloc_t/2,  see  below)  to  have  its
  2017.                clauses  on  the heap, the clref will be allocated there. If
  2018.                the predicate symbol of Clause is undefined, it will be ini-
  2019.                tialized  and Clause added. If the predicate symbol has com-
  2020.                piled clauses, it is first converted to be dynamic (see sym-
  2021.                type/2,  Section  5.10) by adding a special clref that calls
  2022.                the compiled clauses.  Fact, AZ and Index  are  input  argu-
  2023.                ments, and should be instantiated at the time of call; Clref
  2024.                is an output argument, and should be uninstantiated  at  the
  2025.                time of call.
  2026.  
  2027.           clause(P,Q)
  2028.  
  2029.                P must  be  bound  to  a  non-variable  term,  and  the pro-
  2030.                gram  is searched for a clause Cl whose head matches P.  The
  2031.                head and body of the clause Cl  is  unified  with  P  and  Q
  2032.                respectively.    If  Cl  is a unit clause, Q will be unified
  2033.                with `true'.  Only interpreted clauses, i.e.  those  created
  2034.                through assert, can be accesed via clause/2.
  2035.  
  2036.           clause(Head,Body,Ref)
  2037.  
  2038.                Similar to clause(Head,Body) but also unifies Ref  with  the
  2039.                database reference of the clause concerned.  clause/3 can be
  2040.                executed in one of two modes: either Head  must  be  instan-
  2041.                tiated  to  a  non-variable term at the time of the call, or
  2042.                Ref must be instantiated to a database reference.  As in the
  2043.  
  2044.                                          53
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.                case  of  clause/2,  only  interpreted  clauses,  i.e. those
  2051.                created through assert, can be accesed via clause/3.
  2052.  
  2053.           retract(Clause)
  2054.  
  2055.                The first clause in the program that unifies with Clause  is
  2056.                deleted  from  the program.  This predicate may be used in a
  2057.                non-deterministic fashion, i.e. it will  successively  back-
  2058.                track  to retract clauses whose heads match Head.  Head must
  2059.                be initially instantiated to a non-variable. In the  current
  2060.                implementation,  retract  works only for asserted (e.g. con-
  2061.                sulted) clauses.
  2062.  
  2063.           abolish(P)
  2064.  
  2065.                Completely remove all clauses for the procedure with head  P
  2066.                (which should be a term). For example, the goal
  2067.                    | ?- abolish( p(_, _, _) ).
  2068.  
  2069.                removes all clauses for the predicate p/3.
  2070.  
  2071.           abolish(P, N)
  2072.  
  2073.                Completely remove all clauses for  the  predicate  P  (which
  2074.                should  be  an  atom)  with  arity  N  (which  should  be an
  2075.                integer).
  2076.  
  2077.           5.10.  Internal Database
  2078.  
  2079.  
  2080.  
  2081.  
  2082.                                          54
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.           recorded(Key, Term, Ref)
  2089.  
  2090.                The internal database is searched for terms  recorded  under
  2091.                the key Key.  These terms are successively unified with Term
  2092.                in the order they occur in the database; at the  same  time,
  2093.                Ref  is  unified with the database reference of the recorded
  2094.                item.  The key must be given, and may be an atom or  complex
  2095.                term.   If  it is a complex term, only the principal functor
  2096.                is significant.
  2097.  
  2098.           recorda(Key, Term, Ref)
  2099.  
  2100.                The term Term is recorded in the internal  database  as  the
  2101.                first item for the key Key, where Ref is its database refer-
  2102.                ence.  The key must be given, and only its principal functor
  2103.                is significant.
  2104.  
  2105.           recordz(Key, Term, Ref)
  2106.  
  2107.                The term Term is recorded in the internal  database  as  the
  2108.                last  item for the key Key, where Ref is its database refer-
  2109.                ence.  The key must be given, and only its principal functor
  2110.                is significant.
  2111.  
  2112.           erase(Clref)
  2113.  
  2114.                The recorded item or  clause  whose  database  reference  is
  2115.                Clref  is  deleted  from  the  internal database or program.
  2116.                Clref should be instantiated at the time of call.
  2117.  
  2118.  
  2119.                                          55
  2120.  
  2121.  
  2122.  
  2123.  
  2124.  
  2125.           instance(Ref, Term)
  2126.  
  2127.                A (most general) instance of the recorded term  whose  data-
  2128.                base  reference  is  Ref  is unified with Term.  Ref must be
  2129.                instantiated to a database reference.  Note that  instance/2
  2130.                will not be able to access terms that have been erased.
  2131.  
  2132.           5.11.  Information about the State of the Program
  2133.  
  2134.  
  2135.           listing
  2136.  
  2137.                Lists in the current output stream the clauses for  all  the
  2138.                interpreted  predicates  in  the  program, except predicates
  2139.                that are ``internal'', i.e. whose names begin  with  `$'  or
  2140.                `_$',  or  which  are  provided  as  predefined  (builtin or
  2141.                library) predicates.  A bug in the current  system  is  that
  2142.                even though the user is allowed to redefine such predicates,
  2143.                listing/0 does not know about such redefinitions,  and  will
  2144.                not  list  such  predicates  (they may, however, be accessed
  2145.                through listing/1 if they are interpreted).
  2146.  
  2147.           listing(A)
  2148.  
  2149.                The argument A may be a predicate specification of the  form
  2150.                Name/Arity  in which case only the clauses for the specified
  2151.                predicate are listed.  Alternatively, it is possible  for  A
  2152.                to be a list of predicate specifications, e.g.
  2153.                    | ?- listing([concatenate/3, reverse/2, go/0]).
  2154.  
  2155.  
  2156.                                          56
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.                Only interpreted clauses, i.e. clauses created  via  assert,
  2163.                can be accessed through listing/1.
  2164.  
  2165.           current_atom(Atom)
  2166.  
  2167.                Generates (through backtracking) all currently known  atoms,
  2168.                and  unifies  each  in  turn with Atom.  However, atoms con-
  2169.                sidered ``internal'' symbols, i.e. those whose  names  begin
  2170.                with  $  or  _$  are  not  returned.   The intrepid user who
  2171.                wishes to access such internal atoms as  well  can  use  the
  2172.                goal
  2173.                    ?- $current_atom(Atom, 1).
  2174.  
  2175.           current_functor(Name, Term)
  2176.  
  2177.                Generates (through backtracking) all currently  known  func-
  2178.                tors  (which  includes  function and predicate symbols), and
  2179.                for each one returns its name and most general term as  Name
  2180.                and   Term   respectively.    However,  functors  considered
  2181.                ``internal'' symbols, i.e. those whose names begin with $ or
  2182.                _$,  or which are provided as predefined predicates, are not
  2183.                returned if both arguments to  current_functor/2  are  vari-
  2184.                ables.    Internal symbols (of which there are a great many)
  2185.                as well as external ones may be accessed via
  2186.                    ?- $current_functor(Name, Term, 1).
  2187.  
  2188.                A bug in the current implementation is that even though  the
  2189.                user   is  allowed  to  redefine  ``internal''  (builtin  or
  2190.                library) predicates, current_functor/2 does not know whether
  2191.  
  2192.                                          57
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.                they  have  been  redefined,  and hence will not return such
  2199.                predicates if both arguments to current_functor/2 are  vari-
  2200.                ables.
  2201.  
  2202.           current_predicate(Name, Term)
  2203.  
  2204.                Generates (through backtracking) all currently known  predi-
  2205.                cates,  and  for  each one returns its name and most general
  2206.                term as Name and  Term  respectively.   However,  predicates
  2207.                considered ``internal'', i.e. those whose names begin with $
  2208.                or _$, or which are provided as predefined  predicates,  are
  2209.                not  returned  if  both arguments to current_predicate/2 are
  2210.                variables.   Internal symbols (of which there  are  a  great
  2211.                many) as well as external ones may be accessed via
  2212.                    ?- $current_predicate(Name, Term, 1).
  2213.  
  2214.                A bug in the current implementation is that even though  the
  2215.                user   is  allowed  to  redefine  ``internal''  (builtin  or
  2216.                library)  predicates,  current_predicate/2  does  not   know
  2217.                whether  they have been redefined, and hence will not return
  2218.                such predicates if both arguments to current_predicate/2 are
  2219.                variables.
  2220.  
  2221.           predicate_property(Term, Property)
  2222.  
  2223.                If Term is a term whose principal functor  is  a  predicate,
  2224.                Property  is  unified with the currently known properties of
  2225.                the corresponding predicate.  If Term is a variable, then it
  2226.                is  unified  (successively,  through  backtracking) with the
  2227.  
  2228.                                          58
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.                most general term for a predicate whose known properties are
  2235.                unified  with  Property.   For  example, all the interpreted
  2236.                predicates in the program may be enumerated using
  2237.                    ?- predicate_property(X, interpreted).
  2238.  
  2239.                If the first argument to predicate_property/2  is  uninstan-
  2240.                tiated at the time of the call, ``internal'' predicates will
  2241.                not be returned.  A bug in  the  current  implementation  is
  2242.                that  even  though  the  user  is  allowed  to redefine such
  2243.                ``internal'' predicates, predicate_property/2 does not  know
  2244.                about  such  redefinitions,  and will not return such predi-
  2245.                cates if its first argument is  uninstantiated.   Currently,
  2246.                the  only properties that are considered are interpreted and
  2247.                compiled.
  2248.  
  2249.           5.12.  Environmental
  2250.  
  2251.  
  2252.           op(priority, type, name)
  2253.  
  2254.                Treat name as an operator of the stated  type  and  priority
  2255.                (see  Section  3.2).   name  may also be a list of names, in
  2256.                which all are to be treated as operators of the stated  type
  2257.                and priority.
  2258.  
  2259.           break
  2260.  
  2261.                Causes the current execution to be  suspended  at  the  next
  2262.                procedure call.  Then the message ``[ Break (level 1) ]'' is
  2263.  
  2264.                                          59
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.                displayed.  The interpreter is then ready to accept input as
  2271.                though it was at the top level (except that at break level n
  2272.                > 0, the prompt is ``n: ?- '').  If another call of break is
  2273.                encountered,  it  moves  up to level 2, and so on.  To close
  2274.                the break and resume the execution which was suspended, type
  2275.                the  END-OF-INPUT  character.   Execution will be resumed at
  2276.                the procedure call where it had  been  suspended.   Alterna-
  2277.                tively,  the  suspended  execution can be aborted by calling
  2278.                the evaluable predicate abort, which causes a return to  the
  2279.                top level.
  2280.  
  2281.           abort
  2282.  
  2283.                Aborts the current execution, taking you back to top level.
  2284.  
  2285.           save(F)
  2286.  
  2287.                The system saves the current state of the system  into  file
  2288.                F.
  2289.  
  2290.           restore(F)
  2291.  
  2292.                The system restores the saved state in  file  F  to  be  the
  2293.                current  state.  One restriction imposed by the current sys-
  2294.                tem is that various system  parameters  (e.g.  stack  sizes,
  2295.                permanent  space,  heap space, etc.) of the saved state have
  2296.                to be the same as that of the current invocation.  Thus,  it
  2297.                is  not  possible  to  save a state from an invocation where
  2298.                50000 words of permanent space had been allocated, and  then
  2299.                restore the same state in an invocation with 100000 words of
  2300.  
  2301.                                          60
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.                permanent space.
  2308.  
  2309.           cputime(X)
  2310.  
  2311.                Unifies X with the time elapsed, in milliseconds, since  the
  2312.                system was started up.
  2313.  
  2314.           $getenv(Var,Val)
  2315.  
  2316.                Val is unified with the value of the Unix environment  vari-
  2317.                able Var.  Fails is Var is undefined.
  2318.  
  2319.           statistics
  2320.  
  2321.                Prints out the current allocations and amounts of space used
  2322.                for  each  of  the  four main areas: the permanent area, the
  2323.                local stack, the global stack and the trail stack.  Does not
  2324.                work  well  unless the simulator has been called with the -s
  2325.                option (see Section 7.2).
  2326.  
  2327.           statistics(Keyword, List)
  2328.  
  2329.                Usually used with Keyword instantiated to  a  keyword,  e.g.
  2330.                `runtime', and List unbound.  It unifies List with a list of
  2331.                statistics determined by Keyword.  The keys and  values  are
  2332.                summarized below.  Times are given in milliseconds and sizes
  2333.                are given in bytes.
  2334.  
  2335.                Keyword                                                 List
  2336.                runtime                                         [cpu time used by Prolog, cpu time since
  2337.                                                                        last call to statistics/2]
  2338.                memory                                          [total virtual memory, 0]
  2339.  
  2340.                                          61
  2341.  
  2342.  
  2343.  
  2344.  
  2345.                core                                            ( same as for the keyword memory )
  2346.                program                                 [program space in use, program space free]
  2347.                heap                                            ( same as for the keyword program )
  2348.                global_stack                                    [global stack in use, global stack free]
  2349.                local_stack                                     [local stack in use, local stack free]
  2350.                trail                                           [trail stack in use, trail stack free]
  2351.                garbage_collection                              [0, 0]
  2352.                stack_shifts                                    [0, 0]
  2353.  
  2354.                Note:
  2355.  
  2356.           (1)  For the keyword `memory' the second element of the  returned
  2357.                list is always 0.
  2358.  
  2359.           (2)  For the keyword `trail', the second element of the  returned
  2360.                list  is the amount of trail stack free.  This is similar to
  2361.                Sicstus Prolog (version 0.5),  but  different  from  Quintus
  2362.                Prolog (version 1.6).
  2363.  
  2364.           (3)  Currently, SB-Prolog does not  have  garbage  collection  or
  2365.                stack shifting, hence the list values returned for these are
  2366.                [0, 0].
  2367.  
  2368.           nodynload(P, N)
  2369.  
  2370.                Flags the predicate P with arity N as one that should not be
  2371.                attempted to be dynamically loaded if it is undefined.  If a
  2372.                predicate so flagged is undefined  when  a  call  to  it  is
  2373.                encountered, the call fails quietly without trying to invoke
  2374.                the dynamic loader or giving an  error  message.   P  and  N
  2375.                should  be  instantiated  to an atom and an integer, respec-
  2376.                tively, at the time of call to nodynload/2.
  2377.  
  2378.  
  2379.  
  2380.                                          62
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.           symtype(T, N)
  2387.  
  2388.                Unifies N with the ``internal type'' of the principal  func-
  2389.                tor of the term T, which must be instantiated at the time of
  2390.                the call.  N is bound to 0 if T does not have an entry point
  2391.                defined  (i.e.  cannot  be  executed); to 1 if the principal
  2392.                functor of T is ``dynamic'', i.e. has asserted code; to 2 if
  2393.                the  principal  functor for T is a compiled predicate; and 3
  2394.                if T denotes a buffer.  Thus, for example, if the  predicate
  2395.                p/2  is  a compiled predicate which has been loaded into the
  2396.                system, the goal
  2397.                            | ?- symtype(p(_,_), X).
  2398.  
  2399.                will succeed binding X to 2; on the other hand, the goal
  2400.                            | ?- assert(q(a,b,c)), symtype(q(_,_,_), X).
  2401.  
  2402.                will succeed binding X to 1.
  2403.  
  2404.           system(Call)
  2405.  
  2406.                Calls the operating system with the atom Call  as  argument.
  2407.                For example, the call
  2408.                    | ?- system('ls').
  2409.  
  2410.                will produce a directory listing.  Since  system/1  is  exe-
  2411.                cuted by forking off a shell process, it cannot be used, for
  2412.                example, to change the working directory of the simulator.
  2413.  
  2414.           syscall(N, Args, Res)
  2415.  
  2416.  
  2417.                                          63
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.                Executes the Unix system call number N with arguments  Args,
  2424.                and  returns  the result in Res. N is an integer, and Args a
  2425.                Prolog list of the arguments to the system call.  For  exam-
  2426.                ple,  to execute the system call ``creat(File,Mode)'', know-
  2427.                ing that the syscall number for the Unix command creat(2) is
  2428.                8, we execute the goal
  2429.                    | ?- syscall(8, [File, Mode], Des).
  2430.  
  2431.                where Des is the file descriptor  returned  by  creat.   The
  2432.                syscall  numbers  for  some  Unix  system calls are given in
  2433.                Table 2.
  2434.  
  2435.           5.13.  Global Values
  2436.  
  2437.  
  2438.           SB-Prolog has some primitives that permit the programmer to mani-
  2439.           pulate  global  values.  These are provided primarily as an effi-
  2440.           ciency hack, and needless to say, should be  used  with  a  great
  2441.  
  2442.           center  box  ;  le   n   |   le   n.    exit    1       fork    2
  2443.           read    3       write   4               open    5       close   6
  2444.           creat   8       link    9              unlink  10      chdir   12
  2445.           chmod   15      lseek   19             access  33      kill    37
  2446.           wait    84      socket  97             connect 98      accept  99
  2447.           send    101     recv    102   bind    104     setsockopt      105
  2448.           listen  106     recvmsg 113   sendmsg 114     getsockopt      118
  2449.           recvfrom        125     sendto  133
  2450.           socketpair      135     mkdir   136
  2451.           rmdir   137     getsockname     150
  2452.  
  2453.                 Table 2: Some Syscall Numbers for Unix Systems Calls
  2454.  
  2455.  
  2456.  
  2457.  
  2458.                                          64
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.           deal of care.
  2465.  
  2466.           globalset(Term)
  2467.  
  2468.                Allows the user to save a global value.  Term must be  bound
  2469.                to  a  compound term, say p(V). V must be a number or a con-
  2470.                stant or a variable.  If V is a number or  a  constant,  the
  2471.                effect of globalset(p(V)) can be described as:
  2472.                    retract(p(_)), assert(p(V)).
  2473.  
  2474.                I.e., p is a predicate that when called will,  from  now  on
  2475.                (until  some other change by globalset/1), deterministically
  2476.                return V.  If V is a variable, the effect is  to  make  V  a
  2477.                global  variable whose value is accessible by calling p. For
  2478.                example, executing  ``globalset(p(X))''  makes  X  a  global
  2479.                variable.  X can be set by unification with some other term.
  2480.                On backtracking, X will be restored to its earlier value.
  2481.  
  2482.           gennum(Newnum)
  2483.  
  2484.                gennum/1 sets its argument to a new integer every time it is
  2485.                invoked.
  2486.  
  2487.           gensym(C, Newsym)
  2488.  
  2489.                gensym/2 sets its second argument to an atom whose  name  is
  2490.                made  by concatenating the name of the atom C to the current
  2491.                gennum number. This new constant is bound  to  Newsym.   For
  2492.                example, if the current gennum number is 37, then the call
  2493.                    | ?- gensym(aaa,X)
  2494.  
  2495.                                          65
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.                will succeed binding X to the atom `aaa37'.
  2502.  
  2503.           5.14.  Exotica
  2504.  
  2505.  
  2506.           This section describes some low level routines that are sometimes
  2507.           useful  in  mucking  around  with buffers.  These are for serious
  2508.           hackers only.
  2509.  
  2510.           $alloc_buff(Size,Buff,Type,Supbuff,Retcode)
  2511.  
  2512.                Allocates a buffer.  Size is the length (in  bytes)  of  the
  2513.                buffer to allocate; Buff is the buffer allocated, and should
  2514.                be unbound at the time of the call; Type indicates where  to
  2515.                allocate  the buffer: a value of 0 indicates that the buffer
  2516.                is to be allocated in permanent space, 1 that it  should  be
  2517.                on  the  heap,  and  2 indicates that it should be allocated
  2518.                from a larger heap buffer; Supbuff is the larger  buffer  to
  2519.                allocate  a  subbuffer  out of, and is only looked at if the
  2520.                value of Type is 2; Retcode is the return code: a value of 0
  2521.                indicates  that the buffer has been allocated, while a value
  2522.                of 1 indicates that the buffer could not be allocated due to
  2523.                lack  of  space.   The arguments Size, Type, and Supbuff (if
  2524.                Type = 2) are input arguments, and should be  bound  at  the
  2525.                time of the call; Buff and Retcode are output arguments, and
  2526.                should be unbound at the time of the call.
  2527.  
  2528.           call_ref(Call, Ref)
  2529.  
  2530.  
  2531.                                          66
  2532.  
  2533.  
  2534.  
  2535.  
  2536.  
  2537.                Calls the predicate whose database reference (prref) is Ref,
  2538.                using  the  literal  Call  as  the call.  This is similar to
  2539.                call_ref(Call, Ref, 0).
  2540.  
  2541.           call_ref(Call, Ref, Tr)
  2542.  
  2543.                Calls the predicate whose database reference (prref) is Ref,
  2544.                using  the literal Call as the call.  Tr must be either 0 or
  2545.                1: if Tr is 0 then  the  call  Call  is  made  assuming  the
  2546.                ``trust''  optimization  will  be  made; if Tr is 1 then the
  2547.                ``trust'' optimization is not used, so  that  any  new  fact
  2548.                added  before  final  failure  will be seen by Call.  (Also,
  2549.                this currently does not take advantage of any indexing  that
  2550.                might have been constructed.) Call, Ref and Tr are all input
  2551.                arguments, and should be instantiated at the time of call.
  2552.  
  2553.           $assertf_alloc_t(Palist,Size)
  2554.  
  2555.                Declares  that  each  predicate  in  the  list   Palist   of
  2556.                predicate/arity pairs (terms of the form `/'(P,N) where P is
  2557.                a predicate symbol and N the arity of  P)  is  to  have  any
  2558.                facts asserted to them stored in a buffer on the heap, to be
  2559.                allocated here.  This allocates a superbuffer of  size  Size
  2560.                on  the  heap.   Future  assertions to these predicates will
  2561.                have their clauses put in this buffer.  When  this  call  is
  2562.                backtracked  over,  any clauses asserted to these predicates
  2563.                are deallocated, and a  subsequent  call  to  any  of  those
  2564.                predicates  will  cause the simulator to report an error and
  2565.                fail.  Both Palist and Size are input arguments, and  should
  2566.  
  2567.                                          67
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.                be instantiated at the time of call.
  2574.  
  2575.           $db_new_prref(Prref,Where,Supbuff)
  2576.  
  2577.                Creates an empty Prref, i.e. one with no  facts  in  it.  If
  2578.                called,  it  will  simply  fail.   Where indicates where the
  2579.                prref should be allocated:  a value of 0 indicates the  per-
  2580.                manent  area,  while a value of 2 indicates that it is to be
  2581.                allocated as a subbuffer.  Supbuff is the  superbuffer  from
  2582.                which  to  allocate  Prref  if  Where  is 2. Where should be
  2583.                instantiated at the time of  call,  while  Prref  should  be
  2584.                uninstantiated;  in  addition, if Where is 2, Supbuff should
  2585.                be instantiated at the time of call.
  2586.  
  2587.           $db_assert_fact(Fact,Prref,AZ,Index,Clref,Where,Supbuff)
  2588.  
  2589.                Fact is a fact to be asserted; Prref is a  predicate  refer-
  2590.                ence  to  which  to  add  the asserted fact; AZ is either 0,
  2591.                indicating the fact should be inserted as the  first  clause
  2592.                in  Prref,  or  1,  indicating  it should be inserted as the
  2593.                last; Index is 0 if no index is to be  built,  or  n  if  an
  2594.                index  on  the  n[th]  argument  of  the fact is to be used.
  2595.                (Asserting at the beginning of the chain  with  indexing  is
  2596.                not  yet  supported.)  Where indicates where the clref is to
  2597.                be allocated: a value of 0 indicates that it  should  be  in
  2598.                the  permanent  area,  while  a value of 2 indicates that it
  2599.                should be allocated as a subbuffer  of  Supbuff.   Clref  is
  2600.                returned and it  is  the  clause reference  of the  asserted
  2601.                fact.    Fact,  Prref,  AZ,  Index  and  Where   are   input
  2602.  
  2603.                                          68
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.                arguments,  and  should be instantiated at the time of call;
  2610.                in addition, if Where is 2,  then  Supbuff  should  also  be
  2611.                instantiated.   Clref  is  an output argument, and should be
  2612.                uninstantiated at the time of call.
  2613.  
  2614.           $db_add_clref(Fact,Prref,AZ,Index,Clref,Where,Supbuff)
  2615.  
  2616.                Adds the clref Clref to the prref Prref. Fact  is  the  fact
  2617.                that  has  been  compiled  into  Clref (used only to get the
  2618.                arity and for indexing).  The other parameters  are  as  for
  2619.                $db_assert_fact/7.
  2620.  
  2621.           $db_call_prref(Call,Prref)
  2622.  
  2623.                Calls the prref Prref using the literal Call  as  the  call.
  2624.                The  call  is  done by simply branching to the first clause.
  2625.                New facts added to  Prref  after  the  last  fact  has  been
  2626.                retrieved  by  Call, but before Call is failed through, will
  2627.                not be used.  Both Call and Prref are input  arguments,  and
  2628.                should be instantiated at the time of call.
  2629.  
  2630.           $db_call_prref_s(Call,Prref)
  2631.  
  2632.                This also  calls the prref Prref using  Call  as  the  call.
  2633.                The   difference  from  $db_call_prref is that this does not
  2634.                use the ``trust'' optimization, so that any new  fact  added
  2635.                before  final  failure  will  be  seen by Call.  (Also, this
  2636.                currently does not take advantage of any indexing that might
  2637.                have  been  constructed,  while  $db_call_prref does.)  Both
  2638.                Call  and  Prref  are  input  arguments,   and   should   be
  2639.  
  2640.                                          69
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.                instantiated at the time of call.
  2647.  
  2648.           $db_get_clauses(Prref,Clref,Dir)
  2649.  
  2650.                This returns, nondeterministically, all  the  clause  refer-
  2651.                ences  Clref for clauses asserted to prref Prref.  If Dir is
  2652.                0, then the first clref on the list is  returned  first;  if
  2653.                Dir  is  1,  then they are returned in reverse order.  Prref
  2654.                and Dir are input arguments, and should be  instantiated  at
  2655.                the time of call; Clref is an output argument, and should be
  2656.                uninstantiated at the time of call.
  2657.  
  2658.           6.  Debugging
  2659.  
  2660.  
  2661.           6.1.  High Level Tracing
  2662.  
  2663.  
  2664.                The preferred method of tracing  execution  is  through  the
  2665.           predicate  trace/1.  This predicate takes as argument a term P/N,
  2666.           where P is a predicate name and N its arity, and sets  a  ``trace
  2667.           point''  on  the  corresponding predicate; it can also be given a
  2668.           list of such terms, in which case a trace point is  set  on  each
  2669.           member of the list.  For example, executing
  2670.                       | ?- trace(pred1/2), trace([pred2/3, pred3/2]).
  2671.  
  2672.           sets trace points on predicates  pred1/2,  pred2/3  and  pred3/2.
  2673.           Only  those  predicates  are traced that have trace points set on
  2674.           them.
  2675.  
  2676.  
  2677.                                          70
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.                If all the predicates in a file are to be traced, it is usu-
  2684.           ally  convenient  to  use  the PredList parameter of compile/4 or
  2685.           consult/3, e.g.:
  2686.                       | ?- compile(foo, 'foo.out', [t,v], Preds), load('foo.out'), trace(Preds).
  2687.               or
  2688.                       | ?- consult(foo, [v], Preds), trace(Preds).
  2689.  
  2690.           Notice that in the first case, the t compiler option (see Section
  2691.           8.3)  should  be specified in order to turn off certain assembler
  2692.           optimizations and facilitate tracing.  In the  second  case,  the
  2693.           same  effect  may  be achieved by specifying the t option to con-
  2694.           sult.
  2695.  
  2696.                The trace points set on predicates  may  be  overwritten  by
  2697.           loading  byte  code  files via load/1, and in this case it may be
  2698.           necessary to explicitly set trace  points  again  on  the  loaded
  2699.           predicates.   This  does not happen with consult: predicates that
  2700.           were being traced continue to have trace points  set  after  con-
  2701.           sulting.
  2702.  
  2703.                The tracing facilities of SB-Prolog are in  many  ways  very
  2704.           similar  to  those  of  C-Prolog.   However, leashing is not sup-
  2705.           ported, and only those predicates can be traced  which  have  had
  2706.           trace points set on them through trace/1.  This makes trace/1 and
  2707.           spy/1 very similar: essentially, trace amounts to two  levels  of
  2708.           spy  points.  In SB-Prolog, tracing occurs at Call (i.e. entry to
  2709.           a predicate), successful Exit from a clause, and Failure  of  the
  2710.           entire  call.  The tracing options available during debugging are
  2711.           the following:
  2712.  
  2713.                                          71
  2714.  
  2715.  
  2716.  
  2717.  
  2718.  
  2719.           c, NEWLINE: Creep
  2720.                Causes the system to single-step  to  the  next  port  (i.e.
  2721.                either  the  entry  to a traced predicate called by the exe-
  2722.                cuted clause, or the  success  or  failure  exit  from  that
  2723.                clause).
  2724.  
  2725.           a: Abort
  2726.                Causes execution to abort and control to return to  the  top
  2727.                level interpreter.
  2728.  
  2729.           b: Break
  2730.                Calls the evaluable predicate break,  thus  invoking  recur-
  2731.                sively  a  new  incarnation  of the system interpreter.  The
  2732.                command prompt at break level n is
  2733.                            n: ?-
  2734.  
  2735.                The user may return to the previous break level by  entering
  2736.                the system end-of-file character (e.g. ctrl-D), or typing in
  2737.                the atom end_of_file; or to the  top  level  interpreter  by
  2738.                typing in abort.
  2739.  
  2740.           f: Fail
  2741.  
  2742.                Causes execution to fail, thus transferring control  to  the
  2743.                Fail port of the current execution.
  2744.  
  2745.           h: Help
  2746.                Displays the table of debugging options.
  2747.  
  2748.  
  2749.  
  2750.                                          72
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.           l: Leap
  2757.                Causes the system to resume running the program, only  stop-
  2758.                ping  when a spy-point is reached or the program terminates.
  2759.                This allows the user to follow the  execution  at  a  higher
  2760.                level than exhaustive tracing.
  2761.  
  2762.           n: Nodebug
  2763.                Turns off debug mode.
  2764.  
  2765.           q: Quasi-skip
  2766.                This is like Skip except that  it  does  not  mask  out  spy
  2767.                points.
  2768.  
  2769.           r: Retry (fail)
  2770.                Transfers to the Call port of the current goal.  Note,  how-
  2771.                ever,  that  side  effects,  such  as database modifications
  2772.                etc., are not undone.
  2773.  
  2774.           s: Skip
  2775.                Causes tracing to be turned off for the entire execution  of
  2776.                the  procedure.   Thus,  nothing is seen until control comes
  2777.                back to that procedure, either at the Success or the Failure
  2778.                port.
  2779.  
  2780.  
  2781.           Other predicates that are useful in debugging are:
  2782.  
  2783.  
  2784.           untrace(Preds)
  2785.                where Preds is a term P/N, where P is a predicate name and N
  2786.  
  2787.                                          73
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.                its  arity,  or  a list of such terms.  Turns off tracing on
  2794.                the specified predicates.  Preds must be instantiated at the
  2795.                time of the call.
  2796.  
  2797.           spy(Preds)
  2798.                where Preds is a term P/N, where P is a predicate name and N
  2799.                its  arity, or a list of such terms.  Sets spy points on the
  2800.                specified predicates.  Preds must  be  instantiated  at  the
  2801.                time of the call.
  2802.  
  2803.           nospy(Preds)
  2804.                where Preds is a term P/N, where P is a predicate name and N
  2805.                its  arity,  or a list of such terms.  Removes spy points on
  2806.                the specified predicates.  Preds must be instantiated at the
  2807.                time of the call.
  2808.  
  2809.           debug
  2810.                Turns on debugging mode.  This causes  subsequent  execution
  2811.                of  predicates with trace or spy points to be traced, and is
  2812.                a no-op if there are no  such  predicates.   The  predicates
  2813.                trace/1  and  spy/1  cause  debugging  mode  to be turned on
  2814.                automatically.
  2815.  
  2816.           nodebug
  2817.                Turns off debugging mode.  This causes trace and spy  points
  2818.                to be ignored.
  2819.  
  2820.           debugging
  2821.                Displays information about whether debug mode is on or  not,
  2822.  
  2823.                                          74
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.                and  lists  predicates  that have trace points or spy points
  2830.                set on them.
  2831.  
  2832.           tracepreds(L)
  2833.                Binds L to a list of terms P/N  where  the  predicate  P  of
  2834.                arity N has a trace point set on it.
  2835.  
  2836.           spypreds(L)
  2837.                Binds L to a list of terms P/N  where  the  predicate  P  of
  2838.                arity N has a spy point set on it.
  2839.  
  2840.  
  2841.                There is one known bug in the package: attempts to set trace
  2842.           points,  via  trace/1,  on system and library predicates that are
  2843.           used by the trace package can cause bizarre behaviour.
  2844.  
  2845.           6.2.  Low Level Tracing
  2846.  
  2847.  
  2848.           SB-Prolog also provides a facility for low level tracing of  exe-
  2849.           cution.  This can be activated by invoking the simulator with the
  2850.           -T option, or through the predicate $trace/0.   It  causes  trace
  2851.           information  to  be printed out at every call (including those to
  2852.           system trap handlers).  The volume of such trace information  can
  2853.           very  become large very quickly, so this method of tracing is not
  2854.           recommended in general.
  2855.  
  2856.                Low level tracing may be  turned  off  using  the  predicate
  2857.           untrace/0.
  2858.  
  2859.  
  2860.                                          75
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.           7.  The Simulator
  2867.  
  2868.  
  2869.           The simulator resides in the SB-Prolog system directory sim.  The
  2870.           following sections describe various aspects of the simulator.
  2871.  
  2872.           7.1.  Invoking the Simulator
  2873.  
  2874.  
  2875.           The simulator is invoked by the command
  2876.  
  2877.                       sbprolog bc_file
  2878.  
  2879.  
  2880.           where bc_file is a byte code file resulting from the  compilation
  2881.           of  a Prolog program.  In almost all cases, the user will wish to
  2882.           interact with  the  SB-Prolog  query  evaluator,  in  which  case
  2883.           bc_file will be $readloop, and the command will be
  2884.                                sbprolog Path/$readloop
  2885.  
  2886.           where Path is the path to the directory  containing  the  command
  2887.           interpreter  $readloop.  This directory, typically, is the system
  2888.           directory modlib.
  2889.  
  2890.                The command interpreter reads in a query  typed  in  by  the
  2891.           user, evaluates it and prints the answer(s), repeating this until
  2892.           it encounters an end-of-file (the standard end-of-file  character
  2893.           on  the system, e.g. ctrl-D), or the user types in end_of_file or
  2894.           halt.
  2895.  
  2896.  
  2897.                                          76
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.                The user should ensure that the the directory containing the
  2904.           executable  file  sim  (typically,  the  system directory sim) is
  2905.           included in the shell variable path; if not, the full path to the
  2906.           simulator will have to be specified.
  2907.  
  2908.                In general, the simulator may be invoked with a  variety  of
  2909.           options, as follows:
  2910.  
  2911.                       sbprolog -options bc_file
  2912.               or
  2913.                       sbprolog -option<1> -option<2> ... -option<n> bc_file
  2914.  
  2915.  
  2916.           The options recognized by the simulator are described below.
  2917.  
  2918.                When called with a byte code  file  bc_file,  the  simulator
  2919.           begins  execution  with the first clause in that file.  The first
  2920.           clause in such a file, therefore, should be a clause without  any
  2921.           arguments  in  the head (otherwise, the simulator will attempt to
  2922.           dereference argument pointers in the head that are really  point-
  2923.           ing into deep space, and usually come to a sad end).  If the user
  2924.           is executing a file in this manner rather than using the  command
  2925.           interpreter,  he  should also be careful to include the undefined
  2926.           predicate handler `_$undefined_pred'/1, which is normally defined
  2927.           in the file modlib/$init_sys.P.
  2928.  
  2929.           7.2.  Simulator Options
  2930.  
  2931.  
  2932.  
  2933.  
  2934.                                          77
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.           The following is a list of options recognized by the simulator.
  2941.  
  2942.           T    Generates a trace at entry to each called routine.
  2943.  
  2944.           d    Produces a disassembled dump of bc_file into  a  file  named
  2945.                `dump.pil' and exits.
  2946.  
  2947.           n    Adds machine addresses when producing trace and dump.
  2948.  
  2949.           s    Maintains  information   for   the   builtin   statistics/0.
  2950.                Default: off.
  2951.  
  2952.           m size
  2953.                Allocates size words (4 bytes) of space to the  local  stack
  2954.                and heap together.  Default: 100000.
  2955.  
  2956.           p size
  2957.                Allocates size words of space to the program area.  Default:
  2958.                100000.
  2959.  
  2960.           b size
  2961.                Allocates size words of space to the trail stack.   Default:
  2962.                m/5,  where  m is the amount of space allocated to the local
  2963.                stack and heap together.  This parameter, if specified, must
  2964.                follow the -m parameter.
  2965.  
  2966.  
  2967.           As an example, the command
  2968.                       sbprolog -s -p 60000 -m 150000 \$readloop
  2969.  
  2970.           starts the simulator executing the command interpreter with 60000
  2971.  
  2972.                                          78
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.           bytes  of  program  space, 150000 bytes of local and global stack
  2979.           space and (by default) 30000 bytes of trail stack  space;  the  s
  2980.           option also results in statistics information being maintained.
  2981.  
  2982.           7.3.  Interrupts
  2983.  
  2984.  
  2985.           SB-Prolog provides a facility for exception handling using  user-
  2986.           definable interrupt handlers.  This can be used both for external
  2987.           interrupts, e.g. those generated from the keyboard by the user or
  2988.           from  signals  other  processes;  or  internal  traps, e.g. those
  2989.           caused by stack  overflows,  encountering  undefined  predicates,
  2990.           etc.   For example, the ``undefined predicate'' interrupt is han-
  2991.           dled, by default, by the predicate `_$undefined_pred'/1, which is
  2992.           defined     in     the     files    modlib/src/$init_sys.P    and
  2993.           modlib/src/$readloop.P. The default  action  on  encountering  an
  2994.           undefined  predicate  is  to  attempt  to dynamically load a file
  2995.           whose name matches that of the undefined predicate.  However, the
  2996.           user  may easily alter this behaviour by redefining the undefined
  2997.           predicate handler.
  2998.  
  2999.                In  general,  interrupts  are  handled  by   the   predicate
  3000.           `_$interrupt'/2:  a  call  to  this  predicate  is  of  the  form
  3001.           `_$interrupt'(Call, Code), where Call is the call that  generated
  3002.           the  interrupt,  and  Code is an integer indicating the nature of
  3003.           the interrupt.  For each interrupt code,  the  interrupt  handler
  3004.           then  calls  a handler that is designed to handle that particular
  3005.           kind of interrupt.  At this point, the following interrupt  codes
  3006.  
  3007.                                          79
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.           have predefined meanings:
  3014.  
  3015.           0    undefined predicate;
  3016.  
  3017.           1    keyboard interrupt ( ^C );
  3018.  
  3019.           2    stack overflow.
  3020.  
  3021.           Other interrupt codes may be incorporated by modifying the defin-
  3022.           ition    of   the   predicate   `_$interrupt'/2   in   the   file
  3023.           modlib/src/$readloop.P.
  3024.  
  3025.                Interrupts during execution are signalled  from  within  the
  3026.           WAM  simulator.   The  general method for raising an interrupt is
  3027.           using the function set_intercode in the file  sim/sub_inst.c:  to
  3028.           raise an interrupt whose code is n, the line
  3029.               lpcreg = set_intercode(n);
  3030.  
  3031.           is added to the appropriate place in the main loop of the  inter-
  3032.           preter, defined in sim/main.c.
  3033.  
  3034.           8.  The Compiler
  3035.  
  3036.  
  3037.           The compiler translates Prolog source files into byte-code object
  3038.           files.   It is written entirely in Prolog.  The byte code for the
  3039.           compiler can be found in the SB-Prolog system  directory  cmplib,
  3040.           with the source code resident in cmplib/src.
  3041.  
  3042.                Byte code files may  be  concatenated  together  to  produce
  3043.           other  byte  code files.  Thus, for example, if foo1 and foo2 are
  3044.  
  3045.                                          80
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.           byte code files resulting from  the  compilation  of  two  Prolog
  3052.           source  programs,  then  the  file foo, obtained by executing the
  3053.           shell command
  3054.                       cat foo1 foo2 > foo
  3055.  
  3056.           is a byte code file as well, and may be loaded and executed.   In
  3057.           this case, loading and executing the file foo would give the same
  3058.           result as loading foo1 and foo2 separately, which in  turn  would
  3059.           be  the  same as concatenating the original source files and com-
  3060.           piling this larger file.  This makes it easier to  compile  large
  3061.           programs:  one  need only break them into smaller pieces, compile
  3062.           the individual pieces, and concatenate the byte files together.
  3063.  
  3064.                The following sections describe the various aspects  of  the
  3065.           compiler in more detail.
  3066.  
  3067.           8.1.  Invoking the Compiler
  3068.  
  3069.  
  3070.           The compiler is invoked through the Prolog predicate compile:
  3071.                       | ?- compile(InFile [, OutFile ] [, OptionsList ]).
  3072.  
  3073.           where optional parameters are enclosed in  brackets.   InFile  is
  3074.           the  name of the input (i.e. source) file; OutFile is the name of
  3075.           the output file (i.e. byte code) file; OptionsList is a  list  of
  3076.           compiler options (see below).
  3077.  
  3078.                The input and output file names must be Prolog  atoms,  i.e.
  3079.           either  begin  with  a  lower case letter or dollar sign `$', and
  3080.           consist only of letters, digits, and underscores; or, be enclosed
  3081.  
  3082.                                          81
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.           within  single quotes.  If the output file name is not specified,
  3089.           it defaults to InFile.out.  The list of options, if specified, is
  3090.           a Prolog list, i.e. a term of the form
  3091.                       [ option<1>, option<2>, ..., option<n> ].
  3092.  
  3093.           If left unspecified, it defaults to the empty list [].
  3094.  
  3095.                In fact, the output file name and the options  list  may  be
  3096.           specified in any order.  Thus, for example, the queries
  3097.                       | ?- compile('/usr/debray/foo', foo_out, [v]).
  3098.               and
  3099.                       | ?- compile('/usr/debray/foo', [v], foo_out).
  3100.  
  3101.           are  equivalent,  and  specify  that  the  Prolog   source   file
  3102.           `/usr/debray/foo'  is  to be compiled in verbose mode (see ``Com-
  3103.           piler Options'' below), and that the byte code is to be generated
  3104.           into the file foo_out.
  3105.  
  3106.                The compile predicate may  also  be  called  with  a  fourth
  3107.           parameter:
  3108.                       | ?- compile(InFile, OutFile, OptionsList, PredList).
  3109.  
  3110.           where InFile, OutFile and OptionsList are  as  before;  compile/4
  3111.           unifies PredList with a list of terms P/N denoting the predicates
  3112.           defined in InFile, where P is a predicate name and N  its  arity.
  3113.           PredList,  if  specified,  is  usually given as an uninstantiated
  3114.           variable; its principal use is for setting trace  points  on  the
  3115.           predicates in the file (see Section 6), e.g. by executing
  3116.                       | ?- compile('/usr/debray/foo', foo_out, [v], L), load(foo_out), trace(L).
  3117.  
  3118.           Notice that PredList can only appear in compile/4.
  3119.  
  3120.                                          82
  3121.  
  3122.  
  3123.  
  3124.  
  3125.  
  3126.           8.2.  Compiler Options
  3127.  
  3128.  
  3129.           The following options are currently recognized by the compiler:
  3130.  
  3131.           a    Specifies that an ``assembler'' file is to be created.   The
  3132.                name of the assembler file is obtained by appending ``.asl''
  3133.                to the source file name.  While the writing out of  assembly
  3134.                code  slows  down the compilation process to some extent, it
  3135.                allows the assembler to do a better job of  optimizing  away
  3136.                indirect  subroutine linkages (since in this case the assem-
  3137.                bler has assembly code for the entire program to  work  with
  3138.                at once, not just a single predicate).  This results in code
  3139.                that is faster and more compact.
  3140.  
  3141.           d    Dumps expanded macros to the user (see Section 10).
  3142.  
  3143.           e    Expand macros (see Section 10).
  3144.  
  3145.           t    If specified, turns off assembler optimizations  that  elim-
  3146.                inate  indirect  branches through the symbol table in favour
  3147.                of direct branches.  This is useful  in  debugging  compiled
  3148.                code.   It is necessary if the extension table feature is to
  3149.                be used.
  3150.  
  3151.           v    If specified, compiles in  ``verbose''  mode,  which  causes
  3152.                messages  regarding  progress  of  compilation to be printed
  3153.                out.
  3154.  
  3155.  
  3156.  
  3157.                                          83
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.           8.3.  Assembly
  3164.  
  3165.  
  3166.           The SB-Prolog assembler can be invoked by  loading  the  compiler
  3167.           and using the predicate $asm/3:
  3168.                       | ?- $asm(InFile, OutFile, OptionsList).
  3169.  
  3170.           where InFile is a Prolog atom which is the name of a WAM assembly
  3171.           source file (e.g.  the ``.asl'' file generated when a Prolog pro-
  3172.           gram is compiled with the ``a'' option), OutFile is an atom which
  3173.           is  the name of the intended byte code file, and OptionsList is a
  3174.           list of options.  The options recognized by the assembler are:
  3175.  
  3176.           v    ``Verbose'' mode.  Prints out information regarding progress
  3177.                of assembly.
  3178.  
  3179.           t    ``Trace''.  If specified, the assembler  generates  code  to
  3180.                force  procedure  calls  to branch indirectly via the symbol
  3181.                table, instead of using a direct branch.  This is useful for
  3182.                tracing  compiled  code.   It  is necessary if the extension
  3183.                table feature is to be used.
  3184.  
  3185.           The assembler is intended primarily to support the  compiler,  so
  3186.           the assembly language syntax is quirky in places.  The interested
  3187.           reader is advised to look at the assembly  files  resulting  from
  3188.           compilation with the ``a'' option for more on SB-Prolog assembler
  3189.           syntax.
  3190.  
  3191.  
  3192.  
  3193.                                          84
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.           8.4.  Compiler Directives
  3200.  
  3201.  
  3202.           8.4.1.  Mode Declarations
  3203.  
  3204.  
  3205.                The user may declare input and output  arguments  of  predi-
  3206.           cates  using mode declarations.  These declarations, for an n-ary
  3207.           predicate p, are of the form
  3208.               :- mode p( Mode ).
  3209.  
  3210.           where Mode consists of n mode values; or
  3211.               :- mode(p, n, ModeList)
  3212.  
  3213.           where ModeList is a list of mode values of length n.  Mode values
  3214.           may be the following:
  3215.  
  3216.           c, ++
  3217.  
  3218.                Indicates that the corresponding argument position is always
  3219.                a ground term in any call to the predicate.  The argument is
  3220.                therefore an input argument.
  3221.  
  3222.           nv, +
  3223.  
  3224.                Indicates that the corresponding argument position is always
  3225.                a nonvariable term (i.e. is instantiated) in any call in any
  3226.                call to the predicate.  The argument is therefore  an  input
  3227.                argument.
  3228.  
  3229.  
  3230.  
  3231.                                          85
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.           f, -
  3238.  
  3239.                Indicates that the corresponding argument position is always
  3240.                an  uninstantiated  variable  in  any call to the predicate.
  3241.                The argument is therefore an output argument.
  3242.  
  3243.           d, ?
  3244.  
  3245.                Indicates that the corresponding argument may be any term in
  3246.                calls to the predicate.
  3247.  
  3248.  
  3249.           For example, a 3-ary predicate p whose first argument is always a
  3250.           ground  term in a call, whose second argument is always uninstan-
  3251.           tiated, and whose third argument can be any term,  may  have  its
  3252.           mode declared as
  3253.               :- mode p(++, -, d)
  3254.  
  3255.           or as
  3256.               :- mode(p, 3, [c, f, d]).
  3257.  
  3258.           Currently, mode information is used by the compiler in two  ways.
  3259.           First,  it  often  allows more compact code to be generated.  The
  3260.           second use is in guiding program transformations that allow  fas-
  3261.           ter code to be generated.  For example, the predicate
  3262.               part([], _, [], []).
  3263.               part([E|L], M, [E|U1], U2) :- E =< M, part(L, M, U1, U2).
  3264.               part([E|L], M, U1, [E|U2]) :- E  > M, part(L, M, U1, U2).
  3265.  
  3266.           executes about 30% faster with the mode declaration
  3267.               :- mode part(++, ++, -, -).
  3268.  
  3269.                                          86
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.           than without.
  3276.  
  3277.           8.4.2.  Indexing Directives
  3278.  
  3279.  
  3280.           The compiler usually generates an index on the principal  functor
  3281.           of  the  first  argument of a predicate.  The user may direct the
  3282.           compiler to generate an index on any other argument by  means  of
  3283.           an indexing directive.  This is of the form
  3284.               :- index(Pred, Arity, IndexArg)
  3285.  
  3286.           indicating that an index should be created on  the  IndexArg[th.]
  3287.           argument  of  the  predicate Pred/Arity.  All of the values Pred,
  3288.           Arity and IndexArg should be bound in the directive: Pred  should
  3289.           be  an atom, Arity a nonnegative integer, and IndexArg an integer
  3290.           between 0 and Arity.  If IndexArg is 0, then no index is  created
  3291.           for  that  predicate.   As  an example, if we wished to create an
  3292.           index on the third argument of a 5-ary predicate  foo,  the  com-
  3293.           piler directive would be
  3294.               :- index(foo, 5, 3).
  3295.  
  3296.           An index directive may be placed anywhere in the file  containing
  3297.           the predicate it refers to.
  3298.  
  3299.           9.  Libraries
  3300.  
  3301.  
  3302.           To describe how libraries are currently supported in our  system,
  3303.           we  must  describe the _$undefined_pred/1 interrupt handler.  The
  3304.           system keeps a table of libraries and routines  that  are  needed
  3305.  
  3306.                                          87
  3307.  
  3308.  
  3309.  
  3310.  
  3311.  
  3312.           from  each.  When a predicate is found to be undefined, the table
  3313.           is searched to see if it is defined by some library file.  If so,
  3314.           that file is loaded (if it hasn't been previously loaded) and the
  3315.           association is made between the routine name as  defined  in  the
  3316.           library file, and the routine name as used by the invoker.
  3317.  
  3318.                The table of libraries and needed routines is:
  3319.           defined_mods(Modname, [pred<1>/arity<1>, ..., pred<n>/arity<n>]).
  3320.  
  3321.           where Modname is the name of the library.  It exports n predicate
  3322.           definitions.   The  first exported pred is of arity arity<>1, and
  3323.           needs to be invoked by the name of pred<1>.
  3324.  
  3325.                The table of libraries that  have  already  been  loaded  is
  3326.           given by
  3327.                       loaded_mods(Modname).
  3328.  
  3329.           A library file is a file of predicate definitions, together  with
  3330.           a fact defining a list of predicates exported by it; and a set of
  3331.           facts, each of which specifies, for some other library file,  the
  3332.           predicates  imported  from  that library file.  For example, con-
  3333.           sider a library name  `p'.  It  contains  a  single  fact,  named
  3334.           p_export,  that is true of the list of predicate/arity's that are
  3335.           exported.  E.g.
  3336.                       p_export([p1/2, p2/4])
  3337.  
  3338.           indicates that the module p exports the predicates p1/2 and p2/4.
  3339.           For  each  library  m  which  contains  predicates  needed by the
  3340.           library p, there is a fact for p_use, describing what library  is
  3341.  
  3342.                                          88
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.           needed  and  the  names  of the predicates defined there that are
  3349.           needed.  For example, if library p  needs  to  import  predicates
  3350.           ip1/2 and ip2/3 from library q, there would be a fact
  3351.                       p_use(q,[ip1/2, ip2/3])
  3352.  
  3353.           where q is a module that exports two predicates:  one  2-ary  and
  3354.           one  3-ary.   This list corresponds to the export list of library
  3355.           q.
  3356.  
  3357.                The correspondence between the predicates in the export list
  3358.           of an exporting library, and those in the import or use list of a
  3359.           library which imports one or more of them, is by  position,  i.e.
  3360.           the  predicate  names at the exporting and importing names may be
  3361.           different, and the association between names in the two lists  is
  3362.           by  the  position in the list.  If the importing library does not
  3363.           wish to import one or more of  the  predicates  exported  by  the
  3364.           exporting  module,  it  may  put  an  anonymous  variable  in the
  3365.           corresponding position in its use list.  Thus,  for  example,  if
  3366.           library  p  above  had  wished to import only the predicate ip2/3
  3367.           from library q, the corresponding use fact would be
  3368.                       p_use(q, [_, ip2/3]).
  3369.  
  3370.                The initial set of predicates and the libraries  from  which
  3371.           they  are  to  be loaded is set up by an initial call to $prorc/0
  3372.           (see the SB-Prolog system file modlib/src/$prorc.P).  This predi-
  3373.           cate  makes  initial calls to the predicate $define_mod which set
  3374.           up the tables described above so that the use of standard  predi-
  3375.           cates  will  cause  the  correct  libraries  to  be loaded in the
  3376.  
  3377.                                          89
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.           _$undefined_pred routine, and the correct names to be used.
  3384.  
  3385.           10.  Macros
  3386.  
  3387.  
  3388.           SB-Prolog features a facility for the definition and expansion of
  3389.           macros  that  is  fully  compatible with the runtime system.  Its
  3390.           basic mechanism is a simple partial evaluator.  It is  called  by
  3391.           both consult and compile, so that macro expansion occurs indepen-
  3392.           dently of whether the code is interpreted or  compiled  (but  not
  3393.           when  asserted).  Moreover, the macro definitions are retained as
  3394.           clauses at runtime, so that invocation of macros  via  call/1  at
  3395.           runtime (or from asserted clauses) does not pose a problem.  This
  3396.           means, however, that if the same macro is used in many  different
  3397.           files,  it  will be loaded more than once, thus leading to wasetd
  3398.           space.  This ought to be thought about and fixed.
  3399.  
  3400.                The source for the macro expander is in the SB-Prolog system
  3401.           file modlib/src/$mac.P.
  3402.  
  3403.           10.1.  Defining Macros
  3404.  
  3405.  
  3406.           `Macros', or predicates to  be  evaluated  at  compile-time,  are
  3407.           defined by clauses of the form
  3408.                       Head ::- Body
  3409.  
  3410.           where facts have `true' as their  body.   The  partial  evaluator
  3411.           will expand any call to a predicate defined by ::-/2 that unifies
  3412.           with the head of only one clause in ::-/2. If a call unifies with
  3413.  
  3414.                                          90
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.           the  head  of  more  than  one  clause  in  ::-/2, it will not be
  3421.           expanded Notice that this is not a fundamental restriction, since
  3422.           `;'  is permitted in the body of a clause.  The partial evaluator
  3423.           also converts each definition of the form
  3424.                       Head ::- Body.
  3425.  
  3426.           to a clause of the form
  3427.                       Head :- Body.
  3428.  
  3429.           and adds this second clause to the other ``normal'' clauses  that
  3430.           were read from the file.  This ensures that calls to the macro at
  3431.           runtime, e.g. through call/1 or from unexpanded calls in the pro-
  3432.           gram do not cause any problems.
  3433.  
  3434.                The partial evaluator is actually a Prolog interpreter writ-
  3435.           ten  `purely'  in   Prolog, i.e., variable assignments are expli-
  3436.           citly handled.  This is necessary to be  able  to  handle  impure
  3437.           constructs  such  as  `var(X),  X=a'.  As a result this is a very
  3438.           slow Prolog evaluator.
  3439.  
  3440.                Since naive partial evaluation can go into an infinite loop,
  3441.           SB-Prolog's  partial  evaluator  maintains a depth-bound and will
  3442.           not expand recursive calls deeper than that.  The depth is deter-
  3443.           mined  by  the globalset predicate $mac_depth.  The default value
  3444.           for $mac_depth is 50  This can be changed to some other  value  n
  3445.           by executing
  3446.                       | ?- globalset($mac_depth(n)).
  3447.  
  3448.  
  3449.  
  3450.                                          91
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.           10.2.  Macro Expander Options
  3457.  
  3458.  
  3459.           The following options are recognized by the macro expander:
  3460.  
  3461.           d    Dumps all clauses to the user after expansion.   Useful  for
  3462.                debugging.
  3463.  
  3464.           e    Expand macros.  If omitted,  the  expander  simply  converts
  3465.                each ::-/2 clause to a normal :-/2 clause.
  3466.  
  3467.           v    ``Verbose'' mode.  Prints  macros  that  are/are  not  being
  3468.                expanded.
  3469.  
  3470.           11.  Extension Tables: Memo Relations
  3471.  
  3472.  
  3473.           Extension tables store the calls and answers for a predicate.  If
  3474.           a  call  has  been  made  before,  answers are retrieved from the
  3475.           extension table instead of  being  recomputed.  Extension  tables
  3476.           provide  a  caching  mechanism for Prolog. In addition, extension
  3477.           tables affect the termination characteristics of  recursive  pro-
  3478.           grams.  Some  Prolog programs, which are logically correct, enter
  3479.           an infinite loop due to recursive predicates. An extension  table
  3480.           saved  on recursive predicates can find all answers (provided the
  3481.           set of such answers is finite) and terminate for some logic  pro-
  3482.           grams  for  which Prolog's evaluation strategy enters an infinite
  3483.           loop. Iterations over the extension table execution strategy pro-
  3484.           vides  complete  evaluation  of  queries  over function-free Horn
  3485.           clause programs.
  3486.  
  3487.                                          92
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.                To be able to use the simple extension table evaluation on a
  3494.           set of predicates, the source file should either be consulted, or
  3495.           compiled with the t option (the t option keeps the assembler from
  3496.           optimizing  subroutine  linkage  and  allows  the extension table
  3497.           facility to intercept calls to predicates).
  3498.  
  3499.                To use extension table execution, all predicates that are to
  3500.           be saved in the extension table must be passed to et/1. For exam-
  3501.           ple,
  3502.                       | ?- et([pred1/1, pred2/2]), et(pred3/2)
  3503.  
  3504.           will set up ``ET-points'' for the for predicates pred1/1, pred2/2
  3505.           and  pred3/2,  which will cause extension tables for these predi-
  3506.           cates to be maintained during execution. At the time of the  call
  3507.           to  et/1, these predicates must be defined, either by having been
  3508.           loaded, or through consult.
  3509.  
  3510.                The predicate noet/1 takes a list of  predicate/arity  pairs
  3511.           for  which  ET-points should be deleted.  Notice that once an ET-
  3512.           point has been set up for a  predicate,  it  will  be  maintained
  3513.           unless  explicitly  deleted  via  noet/1.  If the definition of a
  3514.           predicate which has an ET-point defined is  to  be  updated,  the
  3515.           ET-point  must  first  be  deleted via noet/1.  The predicate can
  3516.           then be  reloaded  and  a  new  ET-point  established.   This  is
  3517.           enforced  by  the  failure of the goal ``et(P/N)'' if an ET-point
  3518.           already exists for the argument predicate.   In  this  case,  the
  3519.           following error message will be displayed:
  3520.                       *et* already defined for: P/N
  3521.  
  3522.                                          93
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.                There are, in fact, two extension table algorithms: a simple
  3529.           one, which simply caches calls to predicates which have ET-points
  3530.           defined; and a complete ET algorithm, which iterates  the  simple
  3531.           extension  table  algorithm  until  no more answers can be found.
  3532.           The simple algorithm is more efficient  than  the  complete  one;
  3533.           however,  the  simple algorithm is not complete for certain espe-
  3534.           cially nasty forms of mutual recursion, while the complete  algo-
  3535.           rithm  is.   To  use the simple extension table algorithm, predi-
  3536.           cates can simply be called  as  usual.   The  complete  extension
  3537.           table algorithm may be used via the query
  3538.                       | ?- et_star(Query).
  3539.  
  3540.           The extension table algorithm is intended for predicates that are
  3541.           ``essentially  pure'',  and  results  are not guaranteed for code
  3542.           using impure code.  The  extension  table  algorithm  saves  only
  3543.           those  answers  which are not instances of what is already in the
  3544.           table, and uses these answers if the current call is an  instance
  3545.           of  a  call already made.  For example, if a call p(X, Y), with X
  3546.           and Y uninstantiated, is encountered and inserted into the exten-
  3547.           sion table, then a subsequent call p(X, b) will be computed using
  3548.           the answers for p(X, Y) already in the extension  table.   Notice
  3549.           that  this  might  not  work  if var/nonvar tests are used on the
  3550.           second argument in the evaluation of p.
  3551.  
  3552.                Another problem with using impure code  is  that  if  an  ET
  3553.           predicate  is  cut  over,  then  the  saved call implies that all
  3554.           answers for that predicate were  computed,  but  there  are  only
  3555.  
  3556.                                          94
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.           partial results in the ET because of the cut.  So on a subsequent
  3563.           call the incomplete extension table answers  are  used  when  all
  3564.           answers are expected.
  3565.               Example:
  3566.                       r(X,Y) :- p(X,Y),q(Y,Z),!,fail.
  3567.                       | ?-  r(X,Y) ; p(X,Y).
  3568.  
  3569.           Let p be an ET predicate whose evaluation yields many tuples.  In
  3570.           the  evaluation  of  the  query,  r(X,Y)  makes a call to p(X,Y).
  3571.           Assuming that there is a tuple such that q(Y,Z) succeeds with the
  3572.           first  p  tuple then the evaluation of p is cut over. The call to
  3573.           p(X,Y) in the query uses the extension table because of the  pre-
  3574.           vious call in the evaluation of r(X,Y). Only one answer is found,
  3575.           whereas the relation p contains many tuples, so  the  computation
  3576.           is  not complete.  Note that "cuts" used within the evaluation of
  3577.           an ET predicate are ok, as  long  as  they  don't  cut  over  the
  3578.           evaluation  of another ET predicate. The evaluation of the predi-
  3579.           cate that uses cuts does not cut over any et processing (such  as
  3580.           storing  or  retrieving answers) so that the tuples that are com-
  3581.           puted are saved. In the following example, the ET is used to gen-
  3582.           erate prime numbers where an ET point is put on prime/1.
  3583.               Example:
  3584.               prime(I) :- globalset(globalgenint(2)),fail.                    /* Generating Primes */
  3585.               prime(I) :- genint(I), not(div(I)).
  3586.               div(I) :- prime(X), 0 is I mod X.
  3587.               genint(N) :-
  3588.                   repeat,
  3589.                       globalgenint(N),
  3590.                       N1 is N+1,
  3591.                       globalset(globalgenint(N1)).
  3592.  
  3593.  
  3594.                                          95
  3595.  
  3596.  
  3597.  
  3598.  
  3599.  
  3600.           The following summarizes the library  predicates  supporting  the
  3601.           extension table facility:
  3602.  
  3603.  
  3604.           et(L)
  3605.  
  3606.                Sets up an ET-point on the predicates L, which causes  calls
  3607.                and anwers to these predicates to be saved in an ``extension
  3608.                table''.  L is either a term Pred/Arity,  where  Pred  is  a
  3609.                predicate symbol and Arity its arity, or a set of such terms
  3610.                represented as a list.  L  must  be  instantiated,  and  the
  3611.                predicates  specified in it defined, at the time of the call
  3612.                to et/1.  Gives error messages  and  fails  if  any  of  the
  3613.                predicates  in  L  is  undefined,  or if an ET-point already
  3614.                exists on any of them; in this case, no ET-point is  set  up
  3615.                on any of the predicates in L.
  3616.  
  3617.           et_star(Goal)
  3618.  
  3619.                Invokes the complete extension table algorithm on  the  goal
  3620.                Goal.
  3621.  
  3622.           et_points(L)
  3623.  
  3624.                Unifies L with a list of predicates for which an ET-point is
  3625.                defined.   L  is the empty list [] if there are no ET-points
  3626.                defined.
  3627.  
  3628.           noet(L)
  3629.  
  3630.  
  3631.                                          96
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.                Deletes ET-points on the predicates specified in  L.   L  is
  3638.                either  a term P/N, where P is the name of a predicate and N
  3639.                its arity, or a set of such terms  represented  as  a  list.
  3640.                Gives  error  messages  and fails if there is no ET-point on
  3641.                any of the predicates specified in L.  Deleting an  ET-point
  3642.                for a predicate also removes the calls and answers stored in
  3643.                the extension  table  for  that  predicate.   The  extension
  3644.                tables  for  all  predicates for which ET-points are defined
  3645.                may be deleted using et_points/1 in cojnunction with noet/1.
  3646.  
  3647.                L must be instantiated at the time of the call to noet/1.
  3648.  
  3649.           et_remove(L)
  3650.  
  3651.                Removes both calls and answers for the predicates  specified
  3652.                in  L.   In  effect, this results in the extension table for
  3653.                these predicates to be set to empty.  L must be instantiated
  3654.                at  the  time of the call to either a term P/N, where P is a
  3655.                predicate with arity N, or a list of such terms.   An  error
  3656.                occurs  if  any  of the predicates in L does not have an ET-
  3657.                point set.
  3658.  
  3659.                All extension tables can be emptied by using et_points/1  in
  3660.                conjunction with et_remove/1.
  3661.  
  3662.           et_answers(P/N, Term)
  3663.  
  3664.                Retrieves the answers stored in the extension table for  the
  3665.                predicate  P/N  in  Term one at a time.  Term is of the form
  3666.  
  3667.                                          97
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.                P(t<1>, ..., t<N>).  An error results and et_answers/2 fails
  3674.                if  P/N  is not fully specified (ground), or if P/N does not
  3675.                have an ET-point set.
  3676.  
  3677.           et_calls(P/N, Term)
  3678.  
  3679.                Retrieves the calls stored in the extension  table  for  the
  3680.                predicate  P/N  in  Term one at a time.  Term is of the form
  3681.                P(t<1>, ..., t<N>).  An error results and  et_calls/2  fails
  3682.                if  P/N  is not fully specified (ground), or if P/N does not
  3683.                have an ET-point set.
  3684.  
  3685.           12.  Definite Clause Grammars
  3686.  
  3687.  
  3688.           Definite clause grammars are an extension of context  free  gram-
  3689.           mars,  and  may  be  conveniently expressed in Prolog.  A grammar
  3690.           rule in Prolog has the form
  3691.               Head --> Body.
  3692.  
  3693.           with the interpretation ``a possible form  for  Head  is  Body''.
  3694.           Extra conditions, in the form of explicit Prolog literals or con-
  3695.           trol constructs such as if-then-else (`->') or cut (`!'), may  be
  3696.           included in Body.
  3697.  
  3698.                The syntax of DCGs supported by SB-Prolog is as follows:
  3699.  
  3700.           (1)  A non-terminal symbol may be any Prolog term  other  than  a
  3701.                variable.
  3702.  
  3703.  
  3704.                                          98
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.           (2)  A terminal symbol may be any Prolog  term.   To  distinguish
  3711.                terminals from nonterminals, a sequence of terminal symbols
  3712.                    a, b, c, d, . . .
  3713.  
  3714.                is written as a Prolog list [a, b, c, d, . . . ],  with  the
  3715.                empty  sequence written as the empty list [].  If the termi-
  3716.                nal symbols are ASCII character codes, they can  be  written
  3717.                (as elsewhere) as strings.
  3718.  
  3719.           (3)  Extra consitions, in the form of  Prolog  literals,  can  be
  3720.                included  in the right-hand side of a rule by enclosing such
  3721.                conditions in curly braces, { and }.  E.g., one can write
  3722.                    natnum(X) --> {integer(X), X >= 0}.
  3723.  
  3724.           (4)  The left hand side of a rule consists of a single  nontermi-
  3725.                nal.   Notice  that  ``push-back  lists''  are thus not sup-
  3726.                ported.
  3727.  
  3728.           (5)  The right hand side  of  a  rule  may  contain  alternatives
  3729.                (written  using  the  disjunction  operator `;' or `|'), and
  3730.                control primitives such as if-then-else  (`->'),  not/1  and
  3731.                cut (`!').  The use of not/1 on the right hand side of gram-
  3732.                mar rules is not recommended, however, because their  seman-
  3733.                tics  in  this  context is murky at best.  All other control
  3734.                primitives,  e.g.  repeat/0,  must  explicitly  be  enclosed
  3735.                within  curly  braces  if  they are not to be interpreted as
  3736.                nonterminals.
  3737.  
  3738.  
  3739.                                          99
  3740.  
  3741.  
  3742.  
  3743.  
  3744.  
  3745.                Except for the restriction of lists of terminals in the left
  3746.           hand sides of rules, the translation of DCGs in SB-Prolog is very
  3747.           similar to that in Quintus Prolog.
  3748.  
  3749.  
  3750.           Library predicates supporting DCGs are the following:
  3751.  
  3752.           dcg(Rule, Clause)
  3753.  
  3754.                Succeeds if the DCG rule  Rule  corresponds  to  the  Prolog
  3755.                clause Clause.  At the time of call, Rule must be bound to a
  3756.                term whose principal functor is `-->'/2.
  3757.  
  3758.           phrase(Phrase, List)
  3759.  
  3760.                The usual way to commence execution of grammar  rules.   The
  3761.                list  List  is  a  phrase (i.e., sequence of terminals) gen-
  3762.                erated by Phrase according to  the  current  grammar  rules.
  3763.                Phrase  is a nonterminal (in general, the right hand side of
  3764.                a grammar rule), and must be instantiated to  a  nonvariable
  3765.                term  in  the call.  If List is bound to a list of terminals
  3766.                in the call, then the goal corresponds to parsing  List;  if
  3767.                List  is unbound in the call, then the grammar is being used
  3768.                for generation.
  3769.  
  3770.           expand_term(T1, T2)
  3771.  
  3772.                This predicate is used to transform terms that are read  in,
  3773.                when  a  file is consulted or compiled.  The usual use is to
  3774.                transform grammar rules into Prolog  clauses:  if  T1  is  a
  3775.  
  3776.                                          100
  3777.  
  3778.  
  3779.  
  3780.  
  3781.  
  3782.                grammar  rule,  then  T2 is the corresponding Prolog clause.
  3783.                Users may define their own transformations by  defining  the
  3784.                predicate  term_expansion/2.  When a term T1 is read in when
  3785.                a file is being compiled or consulted,  expand_term/2  first
  3786.                calls  term_expansion/2:  if  the  expansion  succeeds,  the
  3787.                transformed term so obtained is used; otherwise, if T1 is  a
  3788.                grammar rule, then it is expanded using dcg/2; otherwise, T1
  3789.                is used as is.
  3790.  
  3791.           `C'(S1, Terminal, S2)
  3792.  
  3793.                Used to handle terminal symbols in the expansion of  grammar
  3794.                rules.   Not  usually  of  direct  use to the user.  This is
  3795.                defined as
  3796.                    `C'([X|S], X, S).
  3797.  
  3798.           13.  Profiling Programs
  3799.  
  3800.  
  3801.           There is an experimental utility for profiling programs  interac-
  3802.           tively.   Two kinds of profiling are supported: one may count the
  3803.           number of calls to a predicate, or compute the time  spent  in  a
  3804.           predicate.   It  is  important that the predicates being profiled
  3805.           are either consulted, or compiled with  the  t  option,  so  that
  3806.           calls  to  the relevant predicates can be intercepted by the pro-
  3807.           filer.
  3808.  
  3809.                To use the  profiler,  predicates  whose  calls  are  to  be
  3810.           counted must be passed to count/1, e.g.
  3811.  
  3812.                                          101
  3813.  
  3814.  
  3815.  
  3816.  
  3817.                       | ?- count([p/1, q/2]), count(r/3).
  3818.  
  3819.           will set up ``count-points'' on the predicates p/1, q/2 and  r/3.
  3820.           Predicates  whose  calls  are  to  be  timed have to be passed to
  3821.           time/1, e.g.
  3822.                       | ?- time([s/1, t/2]), time(u/3).
  3823.  
  3824.           will set up ``time-points'' on the predicates s/1, t/2  and  u/3.
  3825.           It  is  possible  to set both count-points and time-points on the
  3826.           same predicate.  After count-points  and  time-points  have  been
  3827.           set,  the  program  may be executed as many times as desired: the
  3828.           profiling system will accumulate call counts and execution  times
  3829.           for  the  appropriate  predicates.   Execution  profiles  may  be
  3830.           obtained  using  the  predicates  prof_stats/0  or  prof_stats/1.
  3831.           Using  prof_stats/0  to  display the execution profile will cause
  3832.           the call counts and execution times of predicates being  profiled
  3833.           to be reset to 0 (this may be avoided by using prof_stats/1).
  3834.  
  3835.                It should be noted that in  this  context,  the  ``execution
  3836.           time''  for a predicate is an estimate of the total time spent in
  3837.           the subtrees below calls to that predicate (including failed sub-
  3838.           trees):  thus, the execution time figures may be dilated slightly
  3839.           if the subtree below a timed predicate contains  predicates  that
  3840.           are  being  profiled,  because of the time taken for updating the
  3841.           call counts and execution times.  For each predicate, the  execu-
  3842.           tion time is displayed as the fraction of time spent, in computa-
  3843.           tion in subtrees under calls to that predicate, relative  to  the
  3844.           time  elapsed  from  the  last time profiling was timed on or the
  3845.           last time profiling statistics were  taken,  whichever  was  more
  3846.  
  3847.                                          102
  3848.  
  3849.  
  3850.  
  3851.  
  3852.  
  3853.           recent.
  3854.  
  3855.           Bugs: May behave bizarrely if a predicate being profiled contains
  3856.           cuts.
  3857.  
  3858.                The following summarizes the library  predicates  supporting
  3859.           profiling:
  3860.  
  3861.  
  3862.           count(L)
  3863.  
  3864.                Sets up a count-point on  the  predicates  L,  which  causes
  3865.                calls to these predicates to be counted, and turns profiling
  3866.                on.  L is either a term Pred/Arity, where Pred is  a  predi-
  3867.                cate  symbol  and  Arity  its  arity, or a set of such terms
  3868.                represented as a list.  L  must  be  instantiated,  and  the
  3869.                predicates  specified in it defined, at the time of the call
  3870.                to count/1.
  3871.  
  3872.           time(L)
  3873.  
  3874.                Sets up a time-point on the predicates L, which causes  exe-
  3875.                cution  times  for  calls  to these predicates to be accumu-
  3876.                lated,  and  turns  profiling  on.   L  is  either  a   term
  3877.                Pred/Arity,  where  Pred is a predicate symbol and Arity its
  3878.                arity, or a set of such terms represented as a list.  L must
  3879.                be instantiated, and the predicates specified in it defined,
  3880.                at the time of the call to time/1.
  3881.  
  3882.  
  3883.  
  3884.                                          103
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.           nocount(L)
  3891.  
  3892.                Deletes the count-point on the predicates L.  L is either  a
  3893.                term  Pred/Arity, where Pred is a predicate symbol and Arity
  3894.                its arity, or a set of such terms represented as a list.   L
  3895.                must  be  instantiated,  and  the predicates specified in it
  3896.                defined, at the time of the call to nocount/1.
  3897.  
  3898.           notime(L)
  3899.  
  3900.                Deletes the time-point on the predicates L.  L is  either  a
  3901.                term  Pred/Arity, where Pred is a predicate symbol and Arity
  3902.                its arity, or a set of such terms represented as a list.   L
  3903.                must  be  instantiated,  and  the predicates specified in it
  3904.                defined, at the time of the call to time/1.
  3905.  
  3906.           profiling
  3907.  
  3908.                Displays information about whether profile  mode  is  on  or
  3909.                not,  and  lists predicates that have count- and time-points
  3910.                set on them.
  3911.  
  3912.           prof_reset(L)
  3913.  
  3914.                Resets call counts and/or execution times for the predicates
  3915.                L.  L is either a term Pred/Arity, where Pred is a predicate
  3916.                symbol  and  Arity  its  arity,  or  a  set  of  such  terms
  3917.                represented  as  a  list.   L  must be instantiated, and the
  3918.                predicates specified in it defined, at the time of the  call
  3919.                to prof_reset/1.
  3920.  
  3921.                                          104
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.           resetcount(L)
  3928.  
  3929.                Resets call counts for the predicates L.  L is either a term
  3930.                Pred/Arity,  where  Pred is a predicate symbol and Arity its
  3931.                arity, or a set of such terms represented as a list.  L must
  3932.                be instantiated, and the predicates specified in it defined,
  3933.                at the time of the call to resetcount/1.
  3934.  
  3935.           resettime(L)
  3936.  
  3937.                Resets execution times for the predicates L.  L is either  a
  3938.                term  Pred/Arity, where Pred is a predicate symbol and Arity
  3939.                its arity, or a set of such terms represented as a list.   L
  3940.                must  be  instantiated,  and  the predicates specified in it
  3941.                defined, at the time of the call to resettime/1.
  3942.  
  3943.           profile
  3944.  
  3945.                Turns profiling on.  This  causes  subsequent  execution  of
  3946.                predicates with count- or time-points to be profiled, and is
  3947.                a no-op if there are no  such  predicates.   The  predicates
  3948.                count/1 and time/1 cause profiling to be turned on automati-
  3949.                cally.
  3950.  
  3951.           noprofile
  3952.  
  3953.                Turns profiling off.  This causes count- and time-points  to
  3954.                be ignored.
  3955.  
  3956.           timepreds(L)
  3957.  
  3958.  
  3959.                                          105
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.                Unifies L to a list of terms P/N where the  predicate  P  of
  3966.                arity N has a time point set on it.
  3967.  
  3968.           countpreds(L)
  3969.  
  3970.                Unifies L to a list of terms P/N where the  predicate  P  of
  3971.                arity N has a count point set on it.
  3972.  
  3973.           prof_stats
  3974.  
  3975.                Causes the call counts and/or  execution  times  accumulated
  3976.                since  the  last  call to prof_stats/0 to be printed out for
  3977.                predicates that are being profiled.  The execution times are
  3978.                given  as fractions of the total time elapsed since the last
  3979.                time profiling was turned on, or the  last  time  prof_stats
  3980.                was called, whichever was most recent.  This also results in
  3981.                the call counts and relative execution times of these predi-
  3982.                cates being reset to 0.  Equivalent to prof_stats(1).
  3983.  
  3984.           prof_stats(N)
  3985.  
  3986.                Causes the call counts and/or  execution  times  accumulated
  3987.                since  the  last  call to prof_stats/0 to be printed out for
  3988.                predicates that are being profiled.  The execution times are
  3989.                given  as fractions of the total time elapsed since the last
  3990.                time profiling was turned on, or the  last  time  prof_stats
  3991.                was called, whichever was most recent.  If N is 1, then this
  3992.                also results in the call counts and execution times of these
  3993.                predicates  being reset to 0; otherwise, the call counts and
  3994.                execution times are not reset.
  3995.  
  3996.                                          106
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.           14.  Other Library Utilities
  4003.  
  4004.  
  4005.           The SB-Prolog library contains various other utilities,  some  of
  4006.           which are listed below.
  4007.  
  4008.           append(X, Y, Z)
  4009.  
  4010.                Succeeds if list Z is the concatenation of lists X and Y.
  4011.  
  4012.           member(X, L)
  4013.  
  4014.                Checks whether  X  unifies  with  any  element  of  list  L,
  4015.                succeeding  more  than  once if there are multiple such ele-
  4016.                ments.
  4017.  
  4018.           $memberchk(X, L)
  4019.  
  4020.                Similar to member/2, except that $memberchk/2 is determinis-
  4021.                tic, i.e. does not succeed more than once for any call.
  4022.  
  4023.           $reverse(L, R)
  4024.  
  4025.                Succeeds if R is the reverse of list L.  If L is not a fully
  4026.                determined  list,  i.e. if the tail of L is a variable, this
  4027.                predicate can succeed arbitrarily many times.
  4028.  
  4029.           $merge(X, Y, Z)
  4030.  
  4031.                Succeeds if Z is the list resulting from ``merging'' lists X
  4032.                and Y, i.e. the elements of X together with any element of Y
  4033.                not occurring in X.  If X or Y  contain  duplicates,  Z  may
  4034.  
  4035.                                          107
  4036.  
  4037.  
  4038.  
  4039.  
  4040.  
  4041.                also contain duplicates.
  4042.  
  4043.           $absmember(X, L)
  4044.  
  4045.                Similar to $member/2, except that  it  checks  for  identity
  4046.                (through  ==/2)  rather than unifiability (through =/2) of X
  4047.                with elements of L.
  4048.  
  4049.           $nthmember(X, L, N)
  4050.  
  4051.                Succeeds if the N[th.] element of the list L unifies with X.
  4052.                Fails if N is greater than the length of L.  Either X and L,
  4053.                or L and N, should be instantiated at the time of the call.
  4054.  
  4055.           $member2(X, L)
  4056.  
  4057.                Checks whether X unifies with any of the actual elements  of
  4058.                L.   The  only  difference  between this and $member/2 is on
  4059.                lists with a variable tail, e.g. [a,  b,  c  |  _  ]:  while
  4060.                $member/2 would insert X at the end of such a list if it did
  4061.                not find it, $member2/2 only checks for membership but  does
  4062.                not insert it into the list if it is not there.
  4063.  
  4064.           length(L, N)
  4065.  
  4066.                Succeeds if the length of the list L is N.   This  predicate
  4067.                is  deterministic if L is instantiated to a list of definite
  4068.                length, but is nondeterministic if L is a variable or has  a
  4069.                variable tail.
  4070.  
  4071.  
  4072.  
  4073.                                          108
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.           subsumes(X, Y)
  4080.  
  4081.                Succeeds if the term X subsumes the term Y (i.e. if Y is  an
  4082.                instance of X).
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.                                          109
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.                                        CREDITS
  4114.  
  4115.  
  4116.           The initial development of SB-Prolog, from 1984 to  August  1986,
  4117.           was  at  SUNY  at  Stony  Brook,  where Versions 1.0 and 2.0 were
  4118.           developed.  Since August 1986, its development has  continued  at
  4119.           the University of Arizona, Tucson.
  4120.  
  4121.                A large number of people were  involved,  at  some  time  or
  4122.           another,  with  the Logic Programming group at SUNY, Stony Brook,
  4123.           and  deserve credit for helping to bring SB-Prolog to its present
  4124.           form.   David  Scott Warren led the project at Stony Brook.  Most
  4125.           of the simulator and builtins were written by Jiyang Xu and David
  4126.           S.  Warren (I added the later stuff, Versions 2.1 onwards).  Much
  4127.           of the library was also by David, with  some  contributions  from
  4128.           me.   Weidong  Chen  did  the  work  on clause indexing.  Suzanne
  4129.           Dietrich wrote the Extension Table package.  I wrote most of  the
  4130.           compiler.
  4131.  
  4132.                Several people helped  debug  previous  versions,  including
  4133.           Leslie  Rohde;  Bob Beck of Sequent Computers; and Mark Gooley of
  4134.           the University of Illinois at Urbana-Champaign.
  4135.  
  4136.                Special thanks are due to Richard O'Keefe,  who  contributed
  4137.           the  Prolog  code  for  the parser (in the form of the predicates
  4138.           read/1 and read/2), the C code for the tokenizer,  and  the  code
  4139.           for setof/3 and bagof/3.
  4140.  
  4141.  
  4142.  
  4143.                                          110
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.                I am grateful to Fernando  Pereira  for  permission  to  use
  4150.           material  from the C-Prolog manual for the descriptions of Prolog
  4151.           syntax and many of the builtins in this User Manual.
  4152.                                                             - S.K.D.
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.  
  4176.  
  4177.                                          111
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.           Appendix 1: Evaluable Predicates of SB-Prolog
  4184.  
  4185.  
  4186.  
  4187.                An entry of ``B'' indicates a builtin  predicate,  ``I''  an
  4188.           inline  predicate,  and ``L'' a library predicate.  A ``P'' indi-
  4189.           cates that the predicate is handled by  the  preprocessor  during
  4190.           compilation and/or consulting.  A ``D'' denotes a compiler direc-
  4191.           tive.
  4192.  
  4193.           (L)
  4194.                _$undefined_pred/1
  4195.                ....................    7
  4196.           (P)      :-/1 ...........   12
  4197.           (B)      $exists/1 ......   26
  4198.           (I)      =:=/2 ..........   33
  4199.           (I)      =\=/2 ..........   34
  4200.           (I)      </2 ............   34
  4201.           (I)      >/2 ............   34
  4202.           (I)      =</2 ...........   34
  4203.           (I)      >=/2 ...........   34
  4204.           (I)      `,'/2 ..........   36
  4205.           (I)      `;'/2 ..........   36
  4206.           (I)      =/2 ............   37
  4207.           (I)         \=/2 ........   37
  4208.           (I)         ?=/2 ........   37
  4209.           (P)      !/0 ............   37
  4210.           (P)      ->/2 ...........   38
  4211.           (L)      =../2 ..........   40
  4212.           (B)      ==/2 ...........   45
  4213.           (B)      \==/2 ..........   46
  4214.           (B)      @</2 ...........   46
  4215.           (B)      @>/2 ...........   46
  4216.           (B)      @=</2 ..........   46
  4217.           (B)      @>=/2 ..........   46
  4218.           (L)
  4219.                $current_atom/2
  4220.                ....................   57
  4221.           (L)
  4222.                $current_functor/3
  4223.                ....................   57
  4224.           (L)
  4225.                $current_predicate/3
  4226.                ....................   58
  4227.  
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.  
  4234.  
  4235.  
  4236.  
  4237.  
  4238.  
  4239.  
  4240.  
  4241.  
  4242.  
  4243.  
  4244.                                             (L)      $getenv/2 ......   61
  4245.                                             (L)      $alloc_buff/5
  4246.                                                  ....................   66
  4247.                                             (L)
  4248.                                                  $assertf_alloc_t
  4249.                                                  ....................   67
  4250.                                             (L)
  4251.                                                  $db_new_prref/3
  4252.                                                  ....................   68
  4253.                                             (L)
  4254.                                                  $db_assert_fact/5
  4255.                                                  ....................   68
  4256.                                             (L)
  4257.                                                  $db_add_clref/7
  4258.                                                  ....................   69
  4259.                                             (L)
  4260.                                                  $db_call_prref/2
  4261.                                                  ....................   69
  4262.                                             (L)
  4263.                                                  $db_call_prref_s/2
  4264.                                                  ....................   69
  4265.                                             (L)
  4266.                                                  $db_get_clauses/3
  4267.                                                  ....................   70
  4268.                                             (L)      $trace/0 .......   75
  4269.                                             (L)      $untrace/0 .....   75
  4270.                                             (L)          `_$inter-
  4271.                                                  rupt'/2 ............   79
  4272.                                             (P)      ::-/2 ..........   90
  4273.                                             (L)         $reverse/2
  4274.                                                  ....................  107
  4275.                                             (L)      $merge/3 .......  108
  4276.                                             (L)       $absmember/2
  4277.                                                  ....................  108
  4278.  
  4279.                                          112
  4280.  
  4281.  
  4282.  
  4283.  
  4284.           (L)       $nthmember/3
  4285.                ....................  108
  4286.  
  4287.           (B)      atom/1 .........   39
  4288.           (B)      atomic/1 .......   39
  4289.           (I)      arg/3 ..........   40
  4290.           (L)       alloc_perm/2
  4291.                ....................   48
  4292.           (L)       alloc_heap/2
  4293.                ....................   48
  4294.           (L)      assert/1 .......   50
  4295.           (L)      assert/2 .......   51
  4296.           (L)      asserti/2 ......   51
  4297.           (L)      asserta/1 ......   51
  4298.           (L)      asserta/2 ......   51
  4299.           (L)      assertz/1 ......   51
  4300.           (L)      assertz/2 ......   51
  4301.           (L)
  4302.                assert_union/2 .....   52
  4303.           (L)      assert/4 .......   52
  4304.           (L)      abolish/1 ......   54
  4305.           (L)      abolish/2 ......   54
  4306.           (B)      abort/0 ........   60
  4307.           (L)      append/3 .......  107
  4308.  
  4309.           (L)      bagof/3 ........   43
  4310.           (L)      break/0 ........   59
  4311.  
  4312.           (L)      compile/1 ......    8
  4313.           (L)      compile/2 ......    8
  4314.           (L)      compile/3 ......    8
  4315.           (L)      compile/4 ......    8
  4316.           (L)      consult/1 ......   10
  4317.           (L)      consult/2 ......   10
  4318.           (P)      call/1 .........   41
  4319.           (B)        conlength/2
  4320.                ....................   42
  4321.           (B)      compare/3 ......   46
  4322.           (L)      clause/2 .......   53
  4323.           (L)      clause/3 .......   53
  4324.           (L)
  4325.                current_atom/1 .....   57
  4326.           (L)
  4327.                current_functor/2
  4328.                ....................   57
  4329.           (L)
  4330.                current_predicate/2
  4331.                ....................   58
  4332.           (B)      cputime/1 ......   61
  4333.           (L)      call_ref/2 .....   66
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.                                             (L)      call_ref/3 .....   67
  4361.                                             (L)      `C'/3 ..........  101
  4362.                                             (L)      count/1 ........  103
  4363.                                             (L)       countpreds/1
  4364.                                                  ....................  106
  4365.  
  4366.                                             (L)      display/1 ......   27
  4367.                                             (L)      debug/0 ........   74
  4368.                                             (L)        debugging/0
  4369.                                                  ....................   75
  4370.                                             (L)      dcg/2 ..........  100
  4371.  
  4372.                                             (L)      eval/2 .........   33
  4373.                                             (B)     exp/2 ...........   35
  4374.                                             (L)      erase/1 ........   55
  4375.                                             (L)      et/1 ...........   96
  4376.                                             (L)      et_star/1 ......   96
  4377.                                             (L)        et_points/1
  4378.                                                  ....................   96
  4379.                                             (L)        et_remove/1
  4380.                                                  ....................   97
  4381.                                             (L)      et_calls/2 .....   98
  4382.                                             (L)      expand_term/2
  4383.                                                  ....................  100
  4384.  
  4385.                                             (B)     floor/2 .........   35
  4386.                                             (B)     floatc/3 ........   35
  4387.                                             (I)      fail/0 .........   38
  4388.                                             (I)     float/1 .........   39
  4389.                                             (L)      functor/3 ......   40
  4390.  
  4391.                                             (B)      get0/1 .........   29
  4392.                                             (B)      get/1 ..........   29
  4393.                                             (L)        globalset/1
  4394.                                                  ....................   65
  4395.                                             (L)      gennum/1 .......   65
  4396.                                             (L)      gensym/2 .......   65
  4397.  
  4398.                                             (I)      is/2 ...........   33
  4399.                                             (I)      integer/1 ......   39
  4400.                                             (B)        is_buffer/1
  4401.                                                  ....................   40
  4402.                                             (L)      instance/2 .....   56
  4403.                                             (D)      index/3 ........   87
  4404.  
  4405.                                             (L)      keysort/2 ......   47
  4406.  
  4407.  
  4408.                                          113
  4409.  
  4410.  
  4411.  
  4412.  
  4413.           (B)      load/1 .........    9
  4414.           (L)      listing/0 ......   56
  4415.           (L)      listing/1 ......   56
  4416.           (L)      length/2 .......  108
  4417.  
  4418.           (D)      mode/3 .........   85
  4419.           (L)      member/2 .......  107
  4420.  
  4421.           (B)      nl/0 ...........   29
  4422.           (P)      not/1 ..........   38
  4423.           (I)      nonvar/1 .......   38
  4424.           (B)      number/1 .......   39
  4425.           (B)      name/2 .........   41
  4426.           (L)        nodynload/2
  4427.                ....................   62
  4428.           (L)      nospy/1 ........   74
  4429.           (L)      nodebug/0 ......   74
  4430.           (L)      noet/1 .........   97
  4431.           (L)      nocount/1 ......  104
  4432.           (L)      notime/1 .......  104
  4433.           (L)        noprofile/0
  4434.                ....................  105
  4435.  
  4436.           (L)      op/3 ...........   19
  4437.  
  4438.           (L)      print/1 ........   27
  4439.           (L)      print_al/2 .....   28
  4440.           (L)      print_ar/2 .....   28
  4441.           (L)
  4442.                portray_term/2 .....   28
  4443.           (L)
  4444.                portray_clause/2
  4445.                ....................   28
  4446.           (B)      put/1 ..........   29
  4447.           (L)
  4448.                predicate_property/2
  4449.                ....................   58
  4450.           (L)      phrase/2 .......  100
  4451.           (L)        profiling/0
  4452.                ....................  104
  4453.           (L)       prof_reset/1
  4454.                ....................  104
  4455.           (L)      profile/0 ......  105
  4456.           (L)       prof_stats/0
  4457.                ....................  106
  4458.           (L)       prof_stats/1
  4459.                ....................  106
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.                                             (L)      read/1 .........   27
  4488.                                             (L)      repeat/0 .......   38
  4489.                                             (I)     real/1 ..........   39
  4490.                                             (L)      retract/1 ......   54
  4491.                                             (L)      recorded/3 .....   55
  4492.                                             (L)      recorda/3 ......   55
  4493.                                             (L)      recordz/3 ......   55
  4494.                                             (B)     restore/1 .......   60
  4495.                                             (L)       resetcount/1
  4496.                                                  ....................  105
  4497.                                             (L)        resettime/1
  4498.                                                  ....................  105
  4499.  
  4500.                                             (B)      see/1 ..........   26
  4501.                                             (B)      seen ...........   26
  4502.                                             (B)     square/2 ........   35
  4503.                                             (B)     sin/2 ...........   36
  4504.                                             (B)     structure/1 .....   39
  4505.                                             (L)      setof/3 ........   43
  4506.                                             (L)     sort/2 ..........   47
  4507.                                             (B)     save/1 ..........   60
  4508.                                             (B)       statistics/0
  4509.                                                  ....................   61
  4510.                                             (L)       statistics/2
  4511.                                                  ....................   61
  4512.                                             (B)      symtype/2 ......   63
  4513.                                             (B)      system/1 .......   63
  4514.                                             (B)      syscall/3 ......   64
  4515.                                             (L)      spy/1 ..........   74
  4516.                                             (L)      spypreds/1 .....   75
  4517.                                             (L)         subsumes/2
  4518.                                                  ....................  109
  4519.  
  4520.                                             (B)      tell/1 .........   26
  4521.                                             (B)      telling/1 ......   26
  4522.                                             (B)      told/0 .........   26
  4523.                                             (B)      tab/1 ..........   29
  4524.                                             (I)      true/0 .........   36
  4525.                                             (L)      trimbuff/3 .....   49
  4526.                                             (L)      trace/1 ........   70
  4527.                                             (L)       tracepreds/1
  4528.                                                  ....................   75
  4529.                                             (U)
  4530.                                                  term_expansion/2
  4531.                                                  ....................  101
  4532.                                             (L)      time/1 .........  103
  4533.                                             (L)        timepreds/1
  4534.                                                  ....................  105
  4535.  
  4536.                                             (L)      untrace/1 ......   73
  4537.  
  4538.                                          114
  4539.  
  4540.  
  4541.  
  4542.  
  4543.           (I)      var/1 ..........   38
  4544.  
  4545.           (L)      write/1 ........   27
  4546.           (L)      writeq/1 .......   27
  4547.           (B)        writename/1
  4548.                ....................   27
  4549.           (B)       writeqname/1
  4550.                ....................   28
  4551.  
  4552.           Appendix 2: A Note on Coding for Efficiency
  4553.  
  4554.  
  4555.                The SB-Prolog system tends to favour programs that are rela-
  4556.           tively  pure.  Thus, for example, asserts tend to be quite expen-
  4557.           sive, encouraging the user to avoid them if possible.  This  sec-
  4558.           tion  points  out some syntactic constructs that lead to the gen-
  4559.           eration of efficient code.  These involve (i) avoiding the  crea-
  4560.           tion  of  backtrack  points;  and  (ii)  minimizing data movement
  4561.           between registers.  Optimization of logic programs is an area  of
  4562.           ongoing  research,  and  we expect to enhance the capabilities of
  4563.           the system further in future versions.
  4564.  
  4565.           1.  Avoiding Creation of Backtrack Points
  4566.  
  4567.  
  4568.           Since the creation of backtrack points is  relatively  expensive,
  4569.           program  efficiency  may  be improved substantially by using con-
  4570.           structs that avoid the creation of backtrack points where  possi-
  4571.           ble.   The  SB-Prolog  compiler recognizes conditionals involving
  4572.           certain complementary inline tests, and generates code that  does
  4573.           not  create  choice  points  for  such  cases.   Two inline tests
  4574.           p(t<1>, . . ., t<n>) and q(t<1>, . . ., t<n>)  are  complementary
  4575.  
  4576.                                          115
  4577.  
  4578.  
  4579.  
  4580.  
  4581.  
  4582.           if  and only if p(t<1>, . . ., t<n>) =_ not(q(t<1>, . . ., t<n>)).
  4583.           For example, the literals `X > Y' and `X =< Y' are complementary.
  4584.           At this point, complementary tests are recognized as such only if
  4585.           their argument tuples are identical.  The inline predicates  that
  4586.           are  treated  in this manner, with their corresponding complemen-
  4587.           tary literals, are shown in Table 3.   The  syntactic  constructs
  4588.           recognized are:
  4589.  
  4590.           (i)  Disjuncts of the form
  4591.                    head( . . . ) :- (( test(t<1>, . . ., t<n>), . . . ) ; (( not(test(t<1>. . . ., t<n>), . . .)).
  4592.  
  4593.                or
  4594.                    head( . . . ) :- (( test(t<1>, . . ., t<n>), . . . ) ; (( comp_test(t<1>. . . ., t<n>), . . .)).
  4595.  
  4596.                where test is one of the inline tests in  the  table  above,
  4597.                and  comp_test  the  corresponding  complementary test (note
  4598.                that the arguments to test and comp_test have to be  identi-
  4599.                cal).
  4600.  
  4601.           (ii) Conditionals of the form
  4602.                    head :- (test<1>, ... , test<n>) -> True_Case ; False_Case.
  4603.  
  4604.                or
  4605.  
  4606.           allbox center tab(%); ce ce  le  le.   Inline  Test%Complementary
  4607.           Test  >/2%=</2 =</2%>/2 >=/2%</2 </2%>=/2 =:=/2%=\=/2 =\=/2%=:=/2
  4608.           ?=/2%\=/2 \=/2%?=/2 var/1%nonvar/1 nonvar/1%var/1
  4609.  
  4610.                Table 3: Complementary tests recognized by the compiler
  4611.  
  4612.  
  4613.  
  4614.                                          116
  4615.  
  4616.  
  4617.  
  4618.  
  4619.                    head :- (test<1>; ... ; test<n>) -> True_Case ; False_Case.
  4620.  
  4621.                where each test<i> is an inline test, as  mentioned  in  the
  4622.                table above.
  4623.  
  4624.                The code generated for these cases involves a test and  con-
  4625.           ditional  branch,  and  no  choice  point  is created.  We expect
  4626.           future versions of the translator to recognize a wider  class  of
  4627.           complementary tests.
  4628.  
  4629.                Notice that this discourages the use of explicit cuts.   For
  4630.           example, whereas a choice point will be created for
  4631.               part(M,[E|L],U1,U2) :-
  4632.                  ((E =< M, !, U1 = [E|U1a], U2 = U2a) ;
  4633.                   (U1 = U1a, U2 = [E|U2a])),
  4634.                  part(M,L,U1a,U2a).
  4635.  
  4636.           no choice point will be created for either
  4637.               part(M,[E|L],U1,U2) :-
  4638.                  (E =< M ->
  4639.                     (U1 = [E|U1a], U2 = U2a) ;
  4640.                     (U1 = U1a, U2 = [E|U2a])),
  4641.                  part(M,L,U1a,U2a).
  4642.  
  4643.           or
  4644.               part(M,[E|L],U1,U2) :-
  4645.                  ((E =< M, U1 = [E|U1a], U2 = U2a) ;
  4646.                   (E > M,  U1 = U1a, U2 = [E|U2a])),
  4647.                  part(M,L,U1a,U2a).
  4648.  
  4649.           Thus, either of the two later versions  will  be  more  efficient
  4650.           than the version with the explicit cut (this is a design decision
  4651.           we have consciously made, in the hope of  discouraging  blatantly
  4652.           non-declarative  code  where  efficient  declarative  code can be
  4653.           written).
  4654.  
  4655.                                          117
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.           2.  Minimizing Data Movement Between Registers
  4662.  
  4663.  
  4664.           Data movement between registers  for  parameter  passing  may  be
  4665.           minimized  by  leaving  variables  in  the same argument position
  4666.           wherever possible.  Thus, the clause
  4667.                       p(X,Y) :- p1(X,Y,0).
  4668.  
  4669.           is preferable to
  4670.                       p(X,Y) :- p1(0,X,Y).
  4671.  
  4672.           because the first definition leaves the variables X and Y in  the
  4673.           same  argument  positions (first and second, respectively), while
  4674.           the second definition does not.
  4675.  
  4676.           3.  Processing All Arguments of a Term
  4677.  
  4678.  
  4679.           It is often the case that we wish to process each  of  the  argu-
  4680.           ments  of  a term in turn.  For example, to decide whether a com-
  4681.           pound term is ground, we have to check that each of its arguments
  4682.           is  ground.   One  possibility is to create a list of those argu-
  4683.           ments, and traverse the list processing each element.  Using this
  4684.           approach, a predicate to check for groundness would be
  4685.               ground(T) :- atomic(T).
  4686.               ground(T) :- structure(T), T =.. [_ | Args], groundargs(Args).
  4687.               groundargs([]).
  4688.               groundargs([A | ARest]) :- ground(A), groundargs(ARest).
  4689.  
  4690.           This is not the most efficient way to process all  the  arguments
  4691.           of  a  term,  because  it  involves  the creation of intermediate
  4692.  
  4693.                                          118
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.           lists, which is expensive both in space and time.  A much  better
  4700.           alternative  is  to use arg/3 to index into the term and retrieve
  4701.           arguments.  Using this approach,  the  ground/1  predicate  above
  4702.           would be written as
  4703.               ground(T) :- atomic(T).
  4704.               ground(T) :- structure(T), functor(T, P, N), groundargs(1, N, T).
  4705.               groundargs(M, N, T) :-
  4706.                      M =< N ->
  4707.                           (arg(M, T, A), ground(A), M1 is M + 1, groundargs(M1, N, T)) ;
  4708.                           true.
  4709.  
  4710.           The second approach is likely to be more efficient than the first
  4711.           in SB-Prolog.
  4712.  
  4713.                If the arguments of the term do not need to be processed  in
  4714.           ascending  order,  then  it  is more efficient to process them in
  4715.           descending order using arg/3 to access them.   For  example,  the
  4716.           predicate for groundness checking could be written as
  4717.               ground(T) :- atomic(T).
  4718.               ground(T) :- structure(T), functor(T, P, N), groundargs(N, T).
  4719.               groundargs(M, T) :-
  4720.                      M =:= 0 ->
  4721.                           true ;
  4722.                           (arg(M, T, A), ground(A), M1 is M - 1, groundargs(M1, T)).
  4723.  
  4724.           This is even more efficient than the earlier version, because (i)
  4725.           groundargs needs to have one less parameter to be passed to it at
  4726.           each iteration; and (ii) testing ``M =:= 0'' is simpler and  more
  4727.           efficient  than  checking  ``M  =<  N'',  and takes fewer machine
  4728.           instructions.
  4729.  
  4730.  
  4731.  
  4732.  
  4733.                                          119
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.           4.  Testing Unifiability
  4740.  
  4741.  
  4742.           Often, it is necessary to check whether or not a term has a  par-
  4743.           ticular  value.   If  we  know  that  the term will be bound to a
  4744.           number, we can use the evaluable predicates =:=/2  or  =\=/2,  as
  4745.           explained earlier.  For other values, it may often be cheaper, in
  4746.           the appropriate circumstances, to  use  the  predicates  ?=/2  or
  4747.           \=/2.   For example, consider a predicate p/2 that calls q/1 with
  4748.           its second argument if its first argument unifies with a, and r/1
  4749.           otherwise.  A naive definition might be
  4750.               p(a, X) :- !, q(X).
  4751.               p(Y, X) :- r(X).
  4752.  
  4753.           However, the call to p/2 results in the (temporary) creation of a
  4754.           backtrack  point.   A  solution  that avoids this backtrack point
  4755.           creation is
  4756.               p(Y, X) :- Y ?= a -> q(X) ; r(X).
  4757.  
  4758.           Of course, if the argument order in p/2 could be reversed in this
  4759.           case,  then  data  movement  would  be  reduced even further (see
  4760.           above), and the code would be even more efficient:
  4761.               p(X, Y) :- Y ?= a -> q(X) ; r(X).
  4762.  
  4763.  
  4764.  
  4765.  
  4766.  
  4767.  
  4768.  
  4769.                                          120
  4770.  
  4771.  
  4772.  
  4773.  
  4774.  
  4775.           Appendix 3: Adding Builtins to SB-Prolog
  4776.  
  4777.  
  4778.           Adding a builtin involves writing the C code for the desired case
  4779.           and  installing it into the simulator.  The files in the irectory
  4780.           sim/builtin contain the C code for the  builtin  predicates  sup-
  4781.           ported  by the system.  The following procedure is to be followed
  4782.           when adding a builtin to the system:
  4783.  
  4784.  
  4785.           I. Installing C Code:
  4786.  
  4787.           (1)  Go to the directory sim/builtin.
  4788.  
  4789.           (2)  Look at the #defines in the file  builtin.h,  and  choose  a
  4790.                number  N1 (between 0 and 255) which is not in use to be the
  4791.                builtin number for the new builtin.
  4792.  
  4793.           (3)  Add to the file builtin.h the line
  4794.                            #define NEWBUILTIN N1
  4795.  
  4796.           (4)  The convention is that the code for builtin  will  be  in  a
  4797.                parameterless procedure named b_NEWBUILTIN.  Modify the file
  4798.                init_branch.c in the directory sim/builtin by  adding  these
  4799.                lines:
  4800.                            extern int b_NEWBUILTIN();
  4801.                    and
  4802.                            set_b_inst ( NEWBUILTIN, b_NEWBUILTIN );
  4803.  
  4804.                in the appropriate places.
  4805.  
  4806.  
  4807.                                          121
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.           (5)  The builtins are compiled together  into  one  object  file,
  4814.                builtin.   Update the file Makefile by appending the name of
  4815.                your object code file at the end of the line ``OBJS = ... ''
  4816.                and insert the appropriate commands to compile your C source
  4817.                file, e.g.:
  4818.                    OBJS = [ ... other file names ... ] newbuiltin.o
  4819.                     ...
  4820.                    newbuiltin.o: $(HS)
  4821.                            cc $(CFLAGS) newbuiltin.c
  4822.  
  4823.           (6)  Execute the updated make file to create  an  updated  object
  4824.                file builtin.
  4825.  
  4826.           (7)  Go to the directory sim and execute make to install the  new
  4827.                file builtin.
  4828.  
  4829.  
  4830.           II. Installing Prolog Code:
  4831.  
  4832.                Assume that the builtin predicate to be  added  is  newbuil-
  4833.           tin/4.   The procedure for installing the Prolog code for this is
  4834.           as follows:
  4835.  
  4836.           (1)  Go to the SB-Prolog system directory lib/src, where the Pro-
  4837.                log source for the library routines is kept.
  4838.  
  4839.           (2)  Each builtin definition is of the form
  4840.  
  4841.                            pred( ... ) :- '_$builtin'(N).
  4842.  
  4843.  
  4844.                                          122
  4845.  
  4846.  
  4847.  
  4848.  
  4849.  
  4850.                where N is an integer, the builtin number of pred.
  4851.  
  4852.           (3)  Create a Prolog source file newbuiltin.P (notice  correspon-
  4853.                dence with the name of the predicate being defined) contain-
  4854.                ing the definition
  4855.  
  4856.                            newbuiltin(A,B,C,D) :- '_$builtin'(N1).
  4857.  
  4858.  
  4859.                where N1 is the builtin number of the predicate  newbuiltin,
  4860.                obtained  when  installing  the  C code for the builtin (see
  4861.                above).
  4862.  
  4863.           (4)  Compile this Prolog predicate, using the simulator  and  the
  4864.                compile predicate, into a file newbuiltin (notice correspon-
  4865.                dence with the name of the predicate being defined)  in  the
  4866.                SB-Prolog directory lib.
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.                                          123
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.                                     TABLE OF CONTENTS
  4886.  
  4887.                  1 :  Introduction ...................................    2
  4888.                  2 :  Getting Started ................................    3
  4889.                    2.1 :  The Dynamic Loader Search Path .............    3
  4890.                    2.2 :  System Directories .........................    5
  4891.                    2.3 :  Invoking the Simulator .....................    5
  4892.                    2.4 :  Executing Programs .........................    7
  4893.                       2.4.1 :  Compiling Programs ....................    7
  4894.                       2.4.2 :  Loading Byte Code Files ...............    9
  4895.                       2.4.3 :  Consulting Programs ...................   10
  4896.                    2.5 :  Execution Directives .......................   11
  4897.                  3 :  Syntax .........................................   12
  4898.                    3.1 :  Terms ......................................   13
  4899.                    3.2 :  Operators ..................................   16
  4900.                  4 :  SB-Prolog: Operational Semantics ...............   21
  4901.                    4.1 :  Standard Execution Behaviour ...............   21
  4902.                    4.2 :  Cuts and If-Then-Else ......................   22
  4903.                    4.3 :  Unification of Floating Point Numbers ......   23
  4904.                  5 :  Evaluable Predicates ...........................   23
  4905.                    5.1 :  Input and Output ...........................   25
  4906.                       5.1.1 :  File Handling .........................   26
  4907.                       5.1.2 :  Term I/O ..............................   26
  4908.                       5.1.3 :  Character I/O .........................   29
  4909.                    5.2 :  Arithmetic .................................   29
  4910.                    5.3 :  Convenience ................................   36
  4911.                    5.4 :  Extra Control ..............................   37
  4912.                    5.5 :  Meta-Logical ...............................   38
  4913.                    5.6 :  Sets .......................................   42
  4914.                    5.7 :  Comparison of Terms ........................   44
  4915.                    5.8 :  Buffers ....................................   47
  4916.                    5.9 :  Modification of the Program ................   49
  4917.                    5.10 :  Internal Database .........................   54
  4918.                    5.11 :  Information about the State of the  Pro-
  4919.                     gram .............................................   56
  4920.                    5.12 :  Environmental .............................   59
  4921.                    5.13 :  Global Values .............................   64
  4922.                    5.14 :  Exotica ...................................   66
  4923.                  6 :  Debugging ......................................   70
  4924.                    6.1 :  High Level Tracing .........................   70
  4925.                    6.2 :  Low Level Tracing ..........................   75
  4926.                  7 :  The Simulator ..................................   76
  4927.                    7.1 :  Invoking the Simulator .....................   76
  4928.                    7.2 :  Simulator Options ..........................   77
  4929.                    7.3 :  Interrupts .................................   79
  4930.                  8 :  The Compiler ...................................   80
  4931.                    8.1 :  Invoking the Compiler ......................   81
  4932.                    8.2 :  Compiler Options ...........................   83
  4933.                    8.3 :  Assembly ...................................   84
  4934.                    8.4 :  Compiler Directives ........................   85
  4935.                       8.4.1 :  Mode Declarations .....................   85
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.                       8.4.2 :  Indexing Directives ...................   87
  4943.                  9 :  Libraries ......................................   87
  4944.                  10 :  Macros ........................................   90
  4945.                    10.1 :  Defining Macros ...........................   90
  4946.                    10.2 :  Macro Expander Options ....................   92
  4947.                  11 :  Extension Tables: Memo Relations ..............   92
  4948.                  12 :  Definite Clause Grammars ......................   98
  4949.                  13 :  Profiling Programs ............................  101
  4950.                  14 :  Other Library Utilities .......................  107
  4951.                Credits ...............................................  110
  4952.                Appendix 1: Evaluable Predicates of SB-Prolog .........  112
  4953.                Appendix 2: A Note on Coding for Efficiency ...........  115
  4954.                  1 :  Avoiding Creation of Backtrack Points ..........  115
  4955.                  2 :  Minimizing Data  Movement  Between  Registers
  4956.                     ..................................................  118
  4957.                  3 :  Processing All Arguments of a Term .............  118
  4958.                  4 :  Testing Unifiability ...........................  120
  4959.                Appendix 3: Adding Builtins to SB-Prolog ..............  121
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.