PLOGHELP VED                                    Chris Mellish,  Sept 1982
                                      Revised by Simon Nichols, June 1987

Using the Poplog editor Ved with Prolog.

This file documents those Ved commands which are tailored specifically
to Prolog, and which are available in the Prolog subsystem of Poplog. It
assumes a familiarity with the basics of Ved -- moving the cursor,
<ENTER> commands, marking a range of text, and so on. For more
information on topics such as these, see the related documentation given
at the end of this file.


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

  1   Entering and Leaving Ved

  2   Reconsulting from within Ved

  3   Loading the Current File

  4   Loading a Marked Range

  5   Marking the Current Predicate Definition

  6   Loading the Current Predicate Definition

  7   Searching for a Predicate Definition

  8   Adding and Removing Spy Points

  9   Related Documentation


-----------------------------------------------------------------------
1  Entering and Leaving Ved
-----------------------------------------------------------------------

To invoke Ved from Prolog type the word "ved" followed by an optional
file name and <RETURN>. Note that the file name should not be enclosed
in quotes nor should it be terminated by a full stop, since it's a
command (see PLOGHELP * COMMANDS) not a Prolog goal. For example:

   ?- ved myfile.pl

HELP, TEACH and REF files are accessed in a similar way.

To get back to Prolog, use any of the normal ways of exiting from Ved
such as <ENTER> prolog, <ENTER> x or <ENTER> wq.

If you exit from Ved using <ENTER> x, then any files that have been
changed whose names end in ".pl" will automatically be reconsulted.


-----------------------------------------------------------------------
2  Reconsulting from within Ved
-----------------------------------------------------------------------

Providing your Prolog files have the extension ".pl", you can recompile
the whole or parts of your programs from within Ved, using the commands
described below.

N.B. Any output resulting from these commands is directed to an "output"
file, called "output.pl" by default in Prolog. This enables a record of
all activity to be maintained for later inspection. For more general
information, and details of how to change this default, see HELP * LMR.


-----------------------------------------------------------------------
3  Loading the Current File
-----------------------------------------------------------------------

The whole of the current file can be reconsulted using the commands
<ENTER> l1. Any syntax errors will be directed into the output file. You
will remain in Ved after the file has been loaded.


-----------------------------------------------------------------------
4  Loading a Marked Range
-----------------------------------------------------------------------

Marking a range of text and pressing the DOIT key (CTRL-D or <ENTER>
LMR) will cause the marked text to be reconsulted (see HELP * MARK for
details of how to mark a range in Ved).

N.B. Since the action of RECONSULT is to replace any existing definition
for a predicate with the new clauses, it is important to mark the WHOLE
of the new definition of a predicate that has changed.

Any output produced (e.g. syntax errors) is directed into the output
file.

Prolog goals can be included in a marked range to be reconsulted. Goals
are distinguished from definitions of facts or rules by being preceded
by the directives '?-' and ':-'. If the goal is a query (i.e. is invoked
using '?-') you will be prompted to approve solutions as normal: this
interaction takes place in the output file. If a goal invokes read/1,
the input will be taken from the marked range.


-----------------------------------------------------------------------
5  Marking the Current Predicate Definition
-----------------------------------------------------------------------

Using the <ENTER> mcp command will cause all of the "current" predicate
definition to be marked. A predicate is defined as a consecutive group
of clauses with the same functor name and arity. The current predicate
is that which "surrounds" the current cursor position, i.e. the cursor
lies somewhere on the definition of one of its clauses. If the cursor
does not lie on any clause, the nearest preceding predicate (if any) is
marked.

Note: at least the first clause of a predicate must start at the
beginning of a line, otherwise the predicate will not be marked. In fact
the preceding predicate in the file (assuming there is one and it meets
the above condition) will be marked instead.

If no predicate definition can be found between the current cursor
position and the top of the file, an error is displayed on Ved's status
line.

Because mcp parses each clause, it will stop marking a sequence of
clauses when it encounters one containing a syntax error. The clause
with the error will be marked, but no more.

It is possible to mark a sequence of goals using mcp. Any consecutive
group of goals starting with '?-' or ':-' can be marked if the cursor
lies on any of them.

The commands <ENTER> mbp and <ENTER> mep can be used to mark the
beginning and end (respectively) of a predicate.


-----------------------------------------------------------------------
6  Loading the Current Predicate Definition
-----------------------------------------------------------------------

Giving the <ENTER> mcp command, followed by pressing the DOIT key, will
load the current predicate. However, a simpler way is to give the
<ENTER> lcp command (usually bound to ESC-C) which loads (i.e.
reconsults) the current predicate without you first having to mark it.
In fact, it is done without disturbing any existing marked range you may
have. The rules by which the current predicate is determined is the same
as for mcp, above.

In a similar way to mcp, a sequence of goals may be reconsulted using
lcp.


-----------------------------------------------------------------------
7  Searching for a Predicate Definition
-----------------------------------------------------------------------

You can search for a predicate definition within the current file using
the <ENTER> f command. This command takes as an argument either the
functor name and arity of the predicate, expressed as name/arity, or a
leading substring of the functor name. For example, you could search for
append/3 using any of the following:

    <ENTER> f append/3
    <ENTER> f append
    <ENTER> f app

etc. But note that the last of these will also find any predicate whose
functor name starts with "app", and the second would find the definition
of append/2, if such a thing existed.

The command places the cursor at the start of the first line of the
first clause defining the predicate. If the required predicate cannot be
found, an error message is displayed on Ved's status line.

You can also search for a predicate defined in another file using the
<ENTER> source command. For example:

    <ENTER> source append/3

For this to work, the file containing the definition must have been
already compiled. The Prolog compiler automatically tags each predicate
with the name of the file in which it is defined. The source command
uses this information to determine which file contains the definition,
edits it, and then uses <ENTER> f to locate the procedure start. You
must supply the full predicate name to this command so that the right
file can be found.


-----------------------------------------------------------------------
8  Adding and Removing Spy Points
-----------------------------------------------------------------------

The commands <ENTER> spy and <ENTER> nospy provide an interface to the
spy debugger (see PLOGHELP * SPY).

Typing:

    <ENTER> spy

with no argument is equivalent to a call of spy/0 and places spy-points
on all currently-defined user predicates. The command:

    <ENTER> spy spec

is equivalent to a call of spy/1 and interprets its argument in the same
way as specifying a particular predicate (or set of predicates) to be
spied.

The commands:

    <ENTER> nospy
    <ENTER> nospy spec

can be used likewise to remove spy-points.


-----------------------------------------------------------------------
9  Related Documentation
-----------------------------------------------------------------------

PLOGHELP * CONSULT
    Reads clauses and goals from a file.

PLOGHELP * RECONSULT
    Reads clauses and goals from a file, replacing existing clauses.

PLOGHELP * DIRECTIVES
    Commands and queries to the Prolog system.

PLOGHELP * SPY
    The SPY debugger.

HELP * IM
    Immediate mode: interacting with Poplog in a Ved buffer.

HELP * INITIAL
    Tailoring Ved for individual files.

HELP * LCP
    Load the current procedure (from POP11).

HELP * LMR
    Load the marked range. Contains details on changing the destination
    of program output in Ved.

HELP * VEDCOMMS
    A complete list of available commands in Ved.

HELP * VEDKEYS
    Control characters and escape sequences.

HELP * VEDPROCS
    Ved system procedures.

HELP * VEDVARS
    Ved global variables.

See also TEACH * VED, * MOREVED.


--- C.all/plog/help/ved
--- Copyright University of Sussex 1995. All rights reserved.
