[PATCH] guile: Add 'history-push!' procedure

[Ludovic Courtès]

Eli Zaretskii <eliz@gnu.org> skribis:

>> From: ludo@gnu.org (Ludovic Courtès)
>> Date: Tue, 18 Feb 2014 23:40:14 +0100
>> 
>> This patch adds the ‘history-push!’ procedure to add a value in the
>> history.
>
> Thanks.
>
>> +@deffn {Scheme Procedure} history-push! value
>> +Push @var{value}, an instance of @code{<gdb:value>}, to @value{GDBN}'s
>> +value history.
>
> I think we should explain what "push" means in this context.  It is
> not self-evident.

Right.  How about s/push/append/?  (In the procedure name as well.)

>>                 Return its index in the history, or @code{#f} if it is
>> +not saved.
>
> Why would it not be saved?

Good question.  The doc above ‘record_latest_value’ mentions that it can
return -1, but I see no path leading to that.  Can I assume that -1 is
never returned?

>> +This function is useful to make it easier to access individual values
>> +from a set of values displayed by a user function.
>
> Not sure what this sentence is about.  "Easier" how, and what do you
> mean by "user function"?

By “user function”, I mean a Scheme procedure written by the user to
extend GDB functionality.  Such a procedure might display several
values–one example is the Guile VM stack walker, which displays local
variables.  Instead of simply displaying something like this:

--8<---------------cut here---------------start------------->8---
(gdb) gu (display-vm-frames)
#0 #<program 7ffff5d0e420>
  slot 0 -> "scheme@(guile-user)> "
  slot 1 -> #<port file 6f70a0>
  slot 2 -> #<port file 6f7070>
  slot 3 -> #<program bc8100>
[...]
--8<---------------cut here---------------end--------------->8---

it could instead display something like this:

--8<---------------cut here---------------start------------->8---
(gdb) gu (display-vm-frames)
#0 #<program 7ffff5d0e420>
  $12 -> "scheme@(guile-user)> "
  $13 -> #<port file 6f70a0>
  $14 -> #<port file 6f7070>
  $15 -> #<program bc8100>
[...]
--8<---------------cut here---------------end--------------->8---

... thus allowing users to directly refer to $12 etc.

How about simply this:

  Using this function is useful to provide convenient access to values
  manipulated by a Guile extension of GDB.

Thanks,
Ludo’.