[m-rev.] for review: new mdb commands "hold" and "diff"

[Julien Fischer]

On Mon, 11 Jul 2005, Zoltan Somogyi wrote:

> For review by anyone. The diff to the expected output files for debug grades
> aren't final yet.
>
You should ignore the failing test cases in the term directory in debug
grades though, they're likely to be failing for completely unrelated
reasons.

>
> Add two new capabilities to the debugger.
>
> The first capability is the idea of "held variables", variables that the
> debugger holds onto even when execution has left the event they came from.
> You can hold onto a variable via the mdb command "hold varname heldvarname".
> You can suffix the name of the existing variable with a term path, in which
> case the new held variable will refer only to the specified part of the term.
> Later mdb commands can refer to the held variable by prefixing its name with
> a dollar sign. For example, after "hold HeadVar__1^2 x", "$x" will refer to
> the term that was the second argument of HeadVar__1 at the program point
> at which the "hold" command was executed.
>
> The second capability is the ability to compute the diff of two terms and
> express those diffs as the term paths of the function symbols at which the two
> terms differ, instead of the line numbers you get by using save_to_file and the
> usual Unix diff command. The mdb command is "diff var1 var2". We limit the
> number of term paths of difference sites that we display at any one time;
> the mdb diff command has options to control this.
>
Great! I've lost count of the number of times I've needed something like
this.

> doc/user_guide.texi:
> 	Document the new mdb commands "hold" and "diff", the new mdb command
> 	"held_vars" which simply lists the names of all the held variables
> 	(just as "vars" lists the names of all the nonheld variables currently
> 	accessible), and the concept of held variables.
>
> 	Update this file for the new mdb commands and concepts.
>

...

> Index: doc/user_guide.texi
> ===================================================================
> RCS file: /home/mercury/mercury1/repository/mercury/doc/user_guide.texi,v
> retrieving revision 1.441
> diff -u -b -r1.441 user_guide.texi
> --- doc/user_guide.texi	8 Jul 2005 04:22:13 -0000	1.441
> +++ doc/user_guide.texi	10 Jul 2005 12:20:08 -0000
> @@ -2016,6 +2016,18 @@
>  The exception is the subterm specification "^..",
>  which goes one level up, to the parent of the current directory.
>  @sp 1
> + at item held variables
> + at cindex held variables (in mdb)
> +Normally, the only variables from the program accessible in the debugger
> +are the variables in the current environment at the current program point.
> +However, the user can @emph{hold} variables,
> +causing their values -or selected parts of their values-
> +to stay available for the rest of the debugger session.

I suggest also mentioning that held variables also maintain their
values with respect to retries.

> +All the commands that accept variable names
> +also accept the names of held variables;
> +users can ask for a held variable
> +by prefixing the name of the held variable with a dollar sign.
> + at sp 1
>  @item procedure specification
>  @cindex procedure specification (in mdb)
>  @cindex debugger procedure specification
> @@ -2516,6 +2528,9 @@
>  @kindex vars (mdb command)
>  Prints the names of all the known variables in the current environment,
>  together with an ordinal number for each variable.
> + at item held_vars
> + at kindex held_vars (mdb command)
> +Prints the names of all the held variables.
>  @sp 1
>  @item print [-fpv] @var{name}[@var{termpath}]
>  @itemx print [-fpv] @var{num}[@var{termpath}]
> @@ -2782,11 +2797,32 @@
>  The option @samp{-t} (or @samp{--timeout}) specifies
>  the maximum number of seconds to wait for the server to start.
>  @sp 1
> +ZZZ

Delete that.

> + at item hold @var{name}[@var{termpath}] [@var{heldname}]
> + at kindex hold (mdb command)
> +Holds on to the variable @var{name} of the current event,
> +or the part of the specified by @var{termpath},
> +even after execution leaves the current event.
> +The held value will stay accessible via the name @var{$heldname}.
> +If @var{heldname} is not specified, it defaults to @var{name}.

What happens if heldname is reused, or is that not allowed?

> + at sp 1
> + at item diff [-s @var{start}] [-m @var{max}] @var{name1}[@var{termpath1}] @var{name2}[@var{termpath2}]
> + at kindex diff (mdb command)
> +Prints a list of some of the term paths
> +at which the (specified parts of) the specified terms differ.
> +Normally this command prints the term paths of the first 20 differences.
> + at sp 1
> +The option @samp{-s} (or @samp{--start}), if present,
> +specifies how many of the initial differences to skip.
> + at sp 1
> +The option @samp{-m} (or @samp{--max}), if present,
> +specifies how many differences to print.
> + at sp 1
>  @item save_to_file [-x] goal @var{filename}
>  @kindex save_to_file (mdb command)
>  Writes the goal of the current call in its present state of instantiation
> -to the specified file.  The option @samp{-x} (or @samp{--xml}) causes the
> -output to be in XML.
> +to the specified file.
> +The option @samp{-x} (or @samp{--xml}) causes the output to be in XML.
>  @sp 1
>  @item save_to_file [-x] exception @var{filename}
>  Writes the value of the exception at an EXCP port

That looks fine to me 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
--------------------------------------------------------------------------