PLOGHELP POPLOG          Chris Mellish and Jonathan Laventhol March 1984
                                 Revised by Kathryn Seifert  August 1986

Features specific to Poplog Prolog


         CONTENTS - (Use <ENTER> g to access required sections)

 -- INTRODUCTION
 -- WHERE TO FIND DOCUMENTATION
 -- HOW PROLOG TERMS ARE READ
 -- COMMANDS
 -- PREDICATE NAMES TO BE AVOIDED
 -- GRAMMAR RULES
 -- TRACING AND DEBUGGING
 -- DEC10 PREDICATES WHICH ARE MISSING FROM POPLOG PROLOG
 -- THE CUT
 -- ARITHMETIC EXPRESSIONS
 -- VARIABLE AS A GOAL
 -- HOW PROLOG TERMS ARE WRITTEN
 -- ERRORS
 -- INITIALISATION
 -- RELATED DOCUMENTATION


-- INTRODUCTION -------------------------------------------------------

The Prolog sub-system is modelled on the "core" Prolog system described
in PROGRAMMING IN PROLOG by Clocksin and Mellish. This is very close to
both DEC System-10 Prolog and PDP-11 Prolog. The major deviations of
Poplog Prolog from the standards of these systems are listed below.


-- WHERE TO FIND DOCUMENTATION ----------------------------------------

Most facilities in Poplog Prolog have HELP files.  To get help on a
topic, type

    ?- help <topic>

or from VED

    <ENTER> help <topic>

Help files are usually cross referenced thus: PLOGHELP * <topic>. You
can access the cross-referenced file by placing your cursor on the
asterisk (*) after the word PLOGHELP which identifies what kind of
documentation file it is (other words identifying different kinds of
documentation are HELP, REF, and DOC), and typing <esc> h .

HELP * DOCUMENTATION gives more information about Poplog documentation.
PLOGHELP * PLOGINDEX gives a list of HELP files currently in the Prolog
system.


-- HOW PROLOG TERMS ARE READ ------------------------------------------

Double quote characters (") appearing within strings and single quotes (')
appearing within quoted atoms must be preceded by the character "\",
rather than being doubled (see PLOGHELP * STRINGS).

Operator precedences are the same as for PDP-11 Prolog.  A full list of
operators that are declared when the system starts up is given in
PLOGHELP * OPERATORS.  Any operator declaration can be overridden by the user
(see PLOGHELP * OP).

When the predicate 'read' (see PLOGHELP * READ) encounters "end of
file", it acts as if it has read the special atom 'end_of_file'

When the predicate 'get0' (see PLOGHELP * GET0) encounters "end of
file", it acts as if it has read the character CTRL-Z (ASCII 26).

See the section below on arithmetic and PLOGHELP * ARITHMETIC for
information about numbers.

See PLOGHELP SYNTAX for a general description of the syntax of Poplog
Prolog.


-- COMMANDS -----------------------------------------------------------

Commands provide a convenient method of accessing features of the Poplog
environment from Prolog. A command is recognised by the Prolog compiler
whenever a special command name occurs as the first word of a clause or
top-level goal. See PLOGHELP * COMMANDS for details.

Note that it is not possible to define a predicate with the same name as
a command, irrespective of the predicate's arity, unless the name is
enclosed in atom quotes. Similarly, calls to a predicate so defined will
require the name to be quoted if it is being invoked as a top-level
goal.


-- PREDICATE NAMES TO BE AVOIDED --------------------------------------

It is recommended that the user avoids the use of any predicate name
which begins with

    prolog_

as it may clash with internal predicates used by the Prolog system.


-- GRAMMAR RULES ------------------------------------------------------

Grammar rules are allowed in files being consulted or reconsulted. They
are converted to ordinary Prolog clauses, with two extra arguments added
to the end of most goals. The predicate 'phrase' enables grammar rule
predicates to be queried conveniently, e.g.

      ?- phrase(s(X),[the,man,hit,me]).

is equivalent to

      ?- s(X,[the,man,hit,me],[]).

See PLOGHELP * PHRASE, PLOGHELP * GRAMMAR_RULE


-- TRACING AND DEBUGGING ----------------------------------------------

Poplog Prolog provides tracing in the form of a 'spy' facility for
interacting with the execution of selected predicates (see
PLOGHELP * SPY, and PLOGHELP * DEBUG). This is similar to the DEC10 and
PDP-11 systems. For non-specific tracing, you can use the predicate
'spy' with no argument - you will then be spying on all current
predicates. This is not recommended if you have a large program.
Procedure specifications (for arguments to 'spy', 'listing', etc) can be
either atoms, terms of the form <atom>/<arity> or lists of items of
these forms. This follows Dec10 Prolog usage. An example 'spy' goal
would be:

      ?- spy [append/3, reverse].

Note that it is not possible to spy on system predicates.

Spypoints can be "unleashed", that is, they do not prompt the user at every
port, they merely print out the message.  (See PLOGHELP * LEASH,
PLOGHELP * DEBUG).

'spy' and 'nospy' print messages indicating which predicates spypoints
have been placed on or removed from.  This can be switched off using
quitespy/1 (see PLOGHELP * QUIETSPY).


-- DEC10 PREDICATES WHICH ARE MISSING FROM POPLOG PROLOG --------------

Various predicates from the DEC10 system are not implemented in Poplog
Prolog. For suggestions and more information, see
PLOGHELP * COMPATIBILITY.


-- THE CUT ------------------------------------------------------------

A cut is allowed anywhere except as the value of a variable as a goal.

    So
            ?- X = !, X.        and
            ?- X = !, call(X).

are not allowed.


-- ARITHMETIC EXPRESSIONS ---------------------------------------------

Poplog supports a wide range of numerical data types -- including
integers, bigintegers, decimals, ddecimals, ratios and complex numbers
-- but the user will normally be unaware of this, since conversion
between the types is done automatically (see REF NUMBERS for details).
There is thus a significant difference from DEC10 Prolog, which only
supported integers, and smaller integers with a different low-level
representation at that.

Since the representation of integers is different in Poplog from that
used in DEC10 Prolog, those predicates concerned with the low-level
representation of integers (such as xwd/2) are not supported in Poplog
Prolog.

Neither does Poplog Prolog implement the (rather curious) DEC10 feature
whereby a singelton list whose sole element is an integer evaluates to
that integer.

With these exceptions, numerical evaluation in Poplog Prolog has
available all of the functions available in DEC10, as well as a full set
of floating point functions.

The predicates which evaluate integer expressions are:

    is/2  =:=/2  =\=/2  tab/1  </2  >/2  <=/2  =</2  put/1  ttyput/1

This is compatible with DEC10 Prolog.


-- VARIABLES AS GOALS -------------------------------------------------

Variables appearing as a goal are allowed:

      ?- X = foo(1, 5), X.

    is the same as

      ?- X = foo(1, 5), call(X).

(incore/1 has the same effect: it is included for compatibility)

If you need more facilities for calling variables as goals, there is a
library package: see PLOGHELP * DOLLAR.


-- HOW PROLOG TERMS ARE WRITTEN ---------------------------------------

Uninstantiated variables are written out in the form _<number>. Within
forward working of the program, variables written with the same number
are sharing.  If the program backtracks, the numbers get reused.

    So if this is the behaviour:

        ?- mygoal(X,Y,Z).
        X = [_1|_1]
        Y = foo(_1)
        Z = foo(_1,_2,_2) ? ;

        X = [_1|_1]
        Y = foo(_1)
        Z = foo(_1,_2,_2) ?


then we know that, in EACH SOLUTION, the first element of X is that same
as its tail, etc.  But we do not know whether the first element of X is
the same in the first solution as in the second solution.

WARNING: A Prolog term may not necessarily be written in such a way that
it can be read in again from the characters produced.  There are two
reasons: atoms which need quotes may not have them printed; and operator
declarations may be different when the term is read from when it was
written.

    Predicate   When output will be readable
    ---------   ---- ------ ---- -- --------
    write       No atoms which require quoting (eg 'Capital'); operator
                declarations are the same as when the term was written.
    writeq      Operators declarations are the same as when the term was
                written.
    display     Always.


-- ERRORS -------------------------------------------------------------

Calling a predicate which has no definition and has never had a
definition causes the goal to fail, and a dummy definition of the
predicate is made, which looks like this:

    foo(X,Y) :-
        fail,
        'UNDEFINED-PREDICATE'.

See PLOGHELP * ERROR for a detailed explanation of errors that may occur
in Prolog.


-- INITIALISATION -----------------------------------------------------

The initialisation behaviour of Poplog Prolog differs slightly from that
of the DEC10 system.  See HELP * INITIAL.


-- RELATED DOCUMENTATION ----------------------------------------------

PLOGHELP * HELPFILES
    An overview of the contents of the Poplog Prolog HELP files

PLOGHELP * LIBRARIES
    Overview of Prolog library programs


--- C.all/plog/help/poplog
--- Copyright University of Sussex 1993. All rights reserved. ----------