proposed command set for the internal trace based debugger

[Zoltan Somogyi]

At a meeting on friday, some of us have talked about what commands the
debugger should support. (The current debugger command set was not designed;
it is just what was convenient at the time.) Below is the result of our
discussion, with two exceptions:

- We agreed that the debugger should have an alias facility, and that
  the command names the users should use should all be aliases, with the
  real commands names long enough to be unusuable by humans and therefore
  extremely unlikely to conflict with their choice of aliases (probably
  by using a prefix).

  We will supply at least one standard set of aliases. Aliases can
  come from a standard startup file or from the session. Consider the
  proposal below to be for the standard aliases.

  Unlike alternative alias designs, this allows people to swap the meaning of
  two "command" names (because they will be swapping the definitions of
  two standard aliases).

- We agreed that the debugger should use a readline library (flavour undecided)
  to implement history.

Please send your comments to the developers list and to Harald and Mireille,
especially on the parts marked with XXX. Once things have stabilised, we can
take the updated proposal to mercury-users.

Zoltan.

COMMAND SYNTAX

When the debugger (as opposed to the program being debugged) is interacting
with the user, the debugger prints a prompt and reads in a line of text,
which it will interpret as its next command. Each command line consists
of several words separated by white space. The first word is the name of
the command, while any other words give options and/or parameters to the
command.

Some commands take a number as their first parameter. For such commands,
users can type "number command" as well as "command number". The debugger
will internally transform the former into the latter, even if the number
and the command are not separated by white space.

CONCEPTS

spy points:
The user may associate a spy point with a predicate. A spy point on a
predicate affects how the debugger handles events that occur inside that
predicate. The effect of a spy point depends on the state of the spy point.
If the state of the spy point is "stop", execution will stop and user
interaction will start at any event within the predicate, unless the
current debugger command has specifically disabled this behavior (see
the concept "strict commands" below). If the state of the spy point is "print",
the debugger will print any event within the predicate, unless the
current debugger command has specifically disabled this behavior (see
the concept "print level" below). If the state of the spy point is "none",
the debugger will ignore the spy point.

break points:
The user may associate a break point with a specific goal path within
a predicate. Break points have the same states and the same effects as spy
points. XXX should an empty goal path cause a break on all of the
CALL, EXIT and FAIL ports (the interface ports), or only on the CALL port?

print level:
When a debugger command steps over some events without user interaction at
those events, the *print level* controls under what circumstances the stepped
over events will be printed. When the print level is "none", none of the
stepped over events will be printed. When the print level is "all", all the
stepped over events will be printed. When the print level is "some",
the debugger will print the event only if a spy point or a break point
with a state of "stop" or "print" applies to the event. Regardless of the
print level, the debugger will print the event that causes execution to stop
and user interaction to start.

strict commands:
When a debugger command steps over some events without user interaction at
those events, the *strictness* of the command controls whether the debugger
will stop execution and resume user interaction at events to which a spy point
or break point with state "stop" applies. By default, the debugger will stop
at such events. However, if the debugger is executing a strict command,
it will not stop at an event just because a spy point or break point in
the stop state applies to it.

default print level:
The debugger maintains a default print level. The initial value of this
variable is "some", but this value can be overridden by the user.

interrupts:
If the debugger recieves an interrupt, it will stop at the next event
regardless of what it command it is executing at the time.

FORWARD MOVEMENT COMMANDS

skip [<num>]
	If this command is given at event <cur>, continues execution until
	event <cur> + <num>. The default value of <num> is 1.

	The options -none, -selected, -all specify the print level to use
	for the duration of the command, while the options -strict and
	-nostrict specify the strictness of the command.

	By default, this command is not strict, and it uses the default print
	level.

	A command line containing only a number <num> is interpreted as
	if it were "skip <num>".

	An empty command line is interpreted as "skip 1".
	XXX or maybe an empty command should do nothing?

goto <num>
	Continues execution until event <num> provided that the number
	of the current event is smaller than <num>. Otherwise it reports
	an error.

	The options -none, -selected, -all specify the print level to use
	for the duration of the command, while the options -strict and
	-nostrict specify the strictness of the command.

	By default, this command is strict and uses the default print level.

finish
	Continues execution until it reaches a final (EXIT or FAIL) port
	of the call to which the current event refers. Reports an error
	if the current event refers to a final port.

	The options -none, -selected, -all specify the print level to use
	for the duration of the command, while the options -strict and
	-nostrict specify the strictness of the command.

	By default, this command is strict and uses the default print level.

forward
	Continues the program until the program resumes forward execution,
	i.e. until it reaches a non-final port inside any predicate. Reports
	an error if the current event refers to a non-final port.

	The options -none, -some, -all specify the print level to use
	for the duration of the command, while the options -strict and
	-nostrict specify the strictness of the command.

	By default, this command is strict and uses the default print level.

continue
	Continues execution until it reaches the end of the program.

	The options -none, -some, -all specify the print level to use
	for the duration of the command, while the options -strict and
	-nostrict specify the strictness of the command.

	By default, this command is not strict. The print level used
	by the command by default depends on the strictness level:
	if the command is strict, it is "none", otherwise it is "some".

BACKWARD MOVEMENT COMMANDS

redo
	Restarts execution at the call port of the call corresponding to the
	current event. Reports an error if the current event refers to a call
	port.

	The command will report an error unless the values of all the input
	arguments are available at the current port. (The compiler will keep
	the values of the input arguments of traced predicates as long as
	possible, but it cannot keep them beyond the point where they are
	destructively updated.) The exception is values of type io__state;
	the debugger can perform a redo if the only missing value is of
	type io__state (there can be only one io__state at any given time).
	Such a redo has the following effects:

	-	Any input and/or output actions in the repeated code
		will be repeated.

	-	Any file close actions in the repeated code for which the
		corresponding file open action is not also in the repeated
		code may cause later I/O actions referring to the file to fail.

	-	Any file open actions in the repeated code for which the
		corresponding file close action is not also in the repeated
		code may cause later file open actions to fail due to file
		descriptor leak.

	For implementation reasons XXX, the command may also fail if the
	current event represents an execution point inside a commit
	in the code of a predicate that uses the deterministic stack.
	(This limitation can be fixed by letting the program continue
	*forward* execution until it reaches a port on the relevant predicate
	that is outside the commit, and then performing a redo. This
	may require a noticeable amount of time, and although IO states
	cannot be updated inside commits, may result in the execution of
	user-written C code that nevertheless performs I/O and/or has other
	side-effects.)

BROWSING COMMANDS

print
	Prints the values of the known variables in the current environment.
	By default, when execution stops at an event, the current environment
	is the stack frame of the call specified by the event.

	At the moment this command prints the entire value of every variable,
	even if this is very big. Later it will merely invoke a configurable
	dynamic term browser, which will eventually have its own sublanguage.

stack
	Prints the names of the ancestors of the call specified by the
	current event. If two or more ancestor calls are for the same
	predicate, the predicate name will be printed once with the
	appropriate multiplicity annotation.

	This command will report an error if there is no stack trace
	information available about any ancestor.

up [<num>]
	Sets the current environment to the stack frame of the <num>'th
	level ancestor of the current environment (the immediate caller
	is the first-level ancestor).

	If <num> is not specified, the default value is one.

	This command will report an error if the current environment
	doesn't have the required number of ancestors, or if there is
	no execution trace information about the requested ancestor,
	or if there is no stack trace information about any of the ancestors
	between the current environment and the requested ancestor.

down [<num>]
	Sets the current environment to the stack frame of the <num>'th
	level descendant of the current environment (the immediate caller
	is the first-level ancestor).

	If <num> is not specified, the default value is one.

	This command will report an error if the current environment
	doesn't have the required number of descendants,

XXX There should also be commands to browse frames on the nondet stack
that aren't part of the success branch

DEBUGGER STATE MANIPULATION COMMANDS

spy <module name> <predicate name>
	Puts a spy point on the named predicate in the named module.

	The options -stop, -print and -none specify the initial state of
	the spy point.

	By default, the initial state of the spy point is "stop".

break <module name> <predicate name>
	Puts a break point on the CALL port of the named predicate in the
	named module. (XXX Should it be on all the interface ports, i.e.
	CALL, EXIT and FAIL?)

	The options -stop, -print and -none specify the initial state of
	the break point.

	By default, the initial state of the break point is "stop".

here
	Puts a break point on the predicate referred to by the current event
	at the goal path named by the current event.

	The options -stop, -print and -none specify the initial state of
	the break point.

	By default, the initial state of the break point is "stop".

list
	Lists all current spy and break points, their numbers and their states.

change <num> <state>
	Sets the spy or break point with the given number to the named state.
	reports an error if there is no spy or break point with that number,
	or if it already has that state.

changeall <state>
	Sets all spy and break points to the named state.

printlevel <printlevel>
	Sets the default print level to the named level.

MISCELLANEOUS COMMANDS

help
	Prints information about the available commands.

quit
	Quits the debugger and aborts the execution of the program.
	Asks confirmation first, which is given by any answer starting
	with "y" or EOF.

	EOF on the debugger's input is considered a quit command.