[m-rev.] for review: improve the declarative debugger user interface

[Julien Fischer]

On Sun, 1 May 2005, Ian MACLARTY wrote:

> For review by anyone.
>
> Estimated hours taken: 7
> Branches: main
>
> Improve the declarative debugger interface.
>
> The two main changes are to use the mdb help system and not re-display
> the question after the user issues a command which does not answer the
> question.  For example if the user issues an `info' command, then previously
> the question would be redisplayed after the requested information and if the
> question is big then the information would be scrolled off the screen.
>
> browser/declarative_analyser.m:
>  	Remove extra new line characters when printing info.  These are
>  	no longer necessary since the question is not redisplayed.
>
> browser/declarative_debugger.m:
>  	Pass the help system from mdb to the oracle state when
>  	initialising the diagnoser.
>
> browser/declarative_oracle.m:
>  	Pass the help system to the user state when initialising the
>  	oracle state.
>
> browser/declarative_user.m:
>  	Add two new fields to the user state: one to keep a reference to
>  	the help system and one to indicate whether the current question
>  	should be displayed when getting a user input.
>
>  	Allow the user to redisplay the question by issuing a `print' command
>  	with no arguments.  If the question is not to be displayed the show
>  	a "dd>" prompt.
>
>  	Change the `abort' command to `quit'.  This is more consistent
>  	with the rest of mdb.
>
I suggest leaving `abort' in as synonym for `quit', at least for
the time being.


> doc/commands:
>  	Add a script to print all the commands in a section in the
>  	user guide.
>
> doc/generate_mdb_doc:
>  	Generate help for the declarative debugger.
>
> doc/mdb_categories:
>  	Add a category, `decl', for commands that can be executed inside
>  	the declarative debugger.  Change the `dd' category to mdb_dd,
>  	because 1) `help dd' used to show help about the `dd' category AND
>  	the `dd' command and 2) `dd' is too general a category name now that we
>  	have a `decl' category.
>
>  	Add an item, `decl_debug' to the concepts category.
>
> doc/user_guide.texi:
>  	Document some dd commands which previously weren't documented here.
>
>  	Add a short overview of the declarative debugger.  This is
>  	displayed when the user issues a `help' command from within the
>  	dd.
>
>  	Move the bit about the behaviour when no command is given to
>  	before the list of commands.  This is necessary so util/info_to_mdb.c
>  	doesn't include this in the help of the last command in the list.
>
> tests/debugger/declarative/app.exp:
> tests/debugger/declarative/app.inp:
> tests/debugger/declarative/browse_arg.exp:
> tests/debugger/declarative/browse_arg.inp:
> tests/debugger/declarative/browser_mode.exp:
> tests/debugger/declarative/browser_mode.inp:
> tests/debugger/declarative/confirm_abort.exp:
> tests/debugger/declarative/confirm_abort.inp:
> tests/debugger/declarative/dependency.exp:
> tests/debugger/declarative/dependency.inp:
> tests/debugger/declarative/find_origin.exp:
> tests/debugger/declarative/find_origin.exp2:
> tests/debugger/declarative/info.exp:
> tests/debugger/declarative/info.inp:
> tests/debugger/declarative/io_stream_test.exp:
> tests/debugger/declarative/io_stream_test.exp2:
> tests/debugger/declarative/mapinit.exp:
> tests/debugger/declarative/mapinit.inp:
> tests/debugger/declarative/output_term_dep.exp:
> tests/debugger/declarative/output_term_dep.inp:
> tests/debugger/declarative/resume.exp:
> tests/debugger/declarative/resume.inp:
> tests/debugger/declarative/skip.exp:
> tests/debugger/declarative/skip.inp:
> tests/debugger/declarative/solutions.exp3:
> tests/debugger/declarative/tabled_read_decl.exp:
>  	Update tests.
>
> trace/mercury_trace_declarative.c:
> trace/mercury_trace_help.c:
> trace/mercury_trace_help.h:
>  	Pass the help system to the frontend.

...

> Index: browser/declarative_debugger.m
> Index: doc/commands
> ===================================================================
> RCS file: doc/commands
> diff -N doc/commands
> --- /dev/null	1 Jan 1970 00:00:00 -0000
> +++ doc/commands	30 Apr 2005 08:28:07 -0000
> @@ -0,0 +1,7 @@
> +#!/bin/sh
> +#
> +# Print a list of commands in a portion of mdb help text.
> +# Usage: commands file
> +#
> +grep "^\`" $1 | sed "s/^\(\`[a-z]\+\>\).*$/\"\1',\"/" | sort -u \
> +| xargs echo | sed "s/, \(\`[a-z]\+'\)\,$/ and \1\./"
> Index: doc/generate_mdb_doc
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/generate_mdb_doc,v
> retrieving revision 1.8
> diff -u -b -r1.8 generate_mdb_doc
> --- doc/generate_mdb_doc	16 Nov 2004 00:45:11 -0000	1.8
> +++ doc/generate_mdb_doc	30 Apr 2005 06:48:58 -0000
> @@ -14,6 +14,18 @@
>   info -f ./mercury_user_guide.info -o $tmp -n "Mercury debugger concepts"
>   ../util/info_to_mdb concepts $tmp >> mdb_doc
>
> +# Document the declarative debugger.
> +info -f ./mercury_user_guide.info -o $tmp -n "Declarative debugging overview"
> +echo "document concepts 10 decl_debug"                           >> mdb_doc
> +sed 's/^   //' < $tmp | sed -n '6,1000s/^/     /p'               >> mdb_doc
> +echo                                                             >> mdb_doc
> +info -f ./mercury_user_guide.info -o $tmp -n "Declarative debugging commands"
> +echo "The following commands are available from within the \
> +declarative debugger:" `./commands $tmp` | \
> +fold -w72 -s | sed "s/^/     /"                                  >> mdb_doc
> +echo end                                                         >> mdb_doc
> +../util/info_to_mdb decl $tmp >> mdb_doc
> +
>   debug_cmd_path="debug debugger"
>   for section in interactive forward backward browsing breakpoint \
>   	i/o parameter help declarative misc exp developer
> @@ -21,7 +33,7 @@
>   	case $section in
>   		interactive)	category=queries ;;
>   		i/o)		category=table_io ;;
> -		declarative)	category=dd ;;
> +		declarative)	category=mdb_dd ;;
>   		*)		category=$section ;;
>   	esac
>   	info -f ./mercury_user_guide.info -o $tmp $debug_cmd_path $section
> Index: doc/mdb_categories
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/mdb_categories,v
> retrieving revision 1.25
> diff -u -b -r1.25 mdb_categories
> --- doc/mdb_categories	14 Apr 2005 11:29:36 -0000	1.25
> +++ doc/mdb_categories	30 Apr 2005 07:48:27 -0000
> @@ -3,7 +3,7 @@
>                The concepts for which documentation is available are
>                `break_points', `strict_commands', `print_level',
>                `default_print_level', `current_environment',
> -             and `procedure_specification'.
> +             `procedure_specification' and `decl_debug'.
>
>   end
>   document_category 150 queries
> @@ -54,9 +54,15 @@
>                For help on the `help' command, type `help help help'.
>
>   end
> -document_category 850 dd
> -dd         - Commands related to declarative debugging.  These are `dd',
> +document_category 850 mdb_dd
> +mdb_dd     - mdb commands related to declarative debugging.  These are `dd',
>                `trust', `trusted' and `untrust'.
> +
> +end
> +document_category 860 decl
> +decl       - Commands available from within the declarative debugger.  These
> +	     are `yes', `no', `inadmissible', `trust', `skip', `browse',
> +	     `print', `set', `help', `info', `ask', `mark', `pd' and `quit'.
>
>   end
>   document_category 900 misc
> Index: doc/user_guide.texi
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
> retrieving revision 1.432
> diff -u -b -r1.432 user_guide.texi
> --- doc/user_guide.texi	27 Apr 2005 03:21:22 -0000	1.432
> +++ doc/user_guide.texi	30 Apr 2005 08:32:02 -0000
> @@ -3907,9 +3907,9 @@
>
>   Note that this is a work in progress,
>   so there are some limitations in the implementation.
> -The main limitations are pointed out in the following sections.
>
>   @menu
> +* Declarative debugging overview::
>   * Declarative debugging concepts::
>   * Oracle questions::
>   * Declarative debugging commands::
> @@ -3918,6 +3918,21 @@
>   * Improving the search::
>   @end menu
>
> + at node Declarative debugging overview
> + at subsection Overview
> +
> +The declarative debugger tries to find a bug in your program by asking
> +questions about the correctness of calls executed in your program.

s/tried to find a/searches for a/?

> +
> +Because pure Mercury code does not have any side effects, the declarative
> +debugger can make inferences such as ``if a call produces incorrect output
> +from correct input, then there must be a bug in the code executed by one of
> +the descendents of the call''.
> +
I suggest adding something like:

	i.e the code called during the call.

there.

> +The declarative debugger is therefore able to automate much of the
> +`detective work' that must be done manually when using the
> +procedural debugger.
> +
>   @node Declarative debugging concepts
>   @subsection Concepts
>
> @@ -4048,15 +4063,20 @@
>   @subsection Commands
>
>   At the above mentioned prompts, the following commands may be given.
> -Each command (with the exception of @samp{pd})
> -can also be abbreviated to just its first letter.
> - at sp 1
> +Most commands can be abbreviated by their first letter.
> +
> +It is also legal to press return without specifying a command.
> +If there is a default answer (@pxref{Oracle questions}),
> +pressing return is equivalent to giving that answer.
> +If there is no default answer,
> +pressing return is equivalent to the skip command.
> +
>   @table @code
>   @item yes
> -Answer that the assertion is correct.
> +Answer `yes' to the current question.
>   @sp 1
>   @item no
> -Answer that the assertion is wrong.
> +Answer `no' to the current question.
>   @sp 1
>   @item inadmissible
>   Answer that the call is inadmissible.
> @@ -4074,7 +4094,7 @@
>   @item skip
>   Skip this question and ask a different one if possible.
>   @sp 1
> - at item browse [@var{n}]
> + at item browse [--xml] [@var{n}]
>   Start the interactive term browser and browse the @var{n}th argument
>   before answering.  If the argument number
>   is omitted then browse the whole call as if it were a data term.
> @@ -4086,12 +4106,30 @@
>   in @ref{Browsing commands} or type @samp{help} from within the
>   interactive query browser.
>   @sp 1
> +Giving the @samp{--xml} or @samp{-x} option causes the term to be displayed
> +in an XML browser.
> + at sp 1
> + at item browse io [--xml] @var{n}
> +Browse the @var{n}th IO action.
> + at sp 1
> + at item print [@var{n}]
> +Print the @var{n}th argument of the current question.  If no
> +argument is given then display the current question.
> + at sp 1
> + at item print io @var{n}
> +Print the @var{n}th IO action.
> + at sp 1
> + at item set @var{param} @var{value}
> +Updates the given configuration parameter.
s/Updates/Update/

> +The parameters that can be configured are
> + at samp{format}, @samp{depth}, @samp{size}, @samp{width} and @samp{lines}.
> + at sp 1
>   @item mark [@var{term-path}]
>   The @samp{mark} command can only be given from within the interactive
>   term browser and asserts that the marked subterm is incorrect.  The
> -debugger uses this information to better direct the bug search.  If no
> -argument is given the the current subterm is taken to be incorrect.  If a
> - at var{term-path} is given then the subterm at @var{tern-path} relative to
> +declarative debugger uses this information to better direct the bug search.
> +If no argument is given the the current subterm is taken to be incorrect.
> +If a @var{term-path} is given then the subterm at @var{tern-path} relative to
>   the current subterm will be considered incorrect.
>   @sp 1
>   @item pd
> @@ -4099,10 +4137,10 @@
>   This command is notionally the inverse of the @samp{dd} command
>   in the procedural debugger.
>   The session can be resumed with a @samp{dd --resume} command.
> - at item abort
> + at item quit
>   End the declarative debugging session and return to
>   the event at which the @samp{dd} command was given.
> -The session can be resume with a @samp{dd --resume} command.
> +The session can be resumed with a @samp{dd --resume} command.
>   @sp 1
>   @item info
>   List the filename and line number of the predicate the current questiona

That looks fine otherwise.

Julien.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------