Hi Juliana, Juliana Sims <j...@incana.org> writes:
> * doc/ref/api-debug.texi: Document the peek and pk procedures. > --- > > Hi Maxim, > > Thanks for the quick review! I thought I'd made sure to double-space after > periods, but I guess my Emacs fill settings overwrote that when I made sure > everything flowed properly. The contemporary consensus on double spaces in > English is to not use them, and I write a lot so I have my text-mode settings > geared to that purpose. I used manual filling this time so hopefully that > issue > has been resolved. Thanks! It's a peculiar/historical typography choice that seems rooted in being able to navigate unambiguously between sentences in Emacs (and elsewhere where implemented). > I didn't use Emacs to regenerate all the menus in this file because it > produced > diffs in unrelated sections. Fair enough! > Otherwise, I've taken all of your feedback into > account. If someone chimes in to say they really liked the smores example, we > can always build out from the first version of the patch. There was a lot of > code involved in making that actually work (three record types, two > predicates, > and a utility function) so I don't think that's the right solution. Sounds good. [...] > diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi > index faa0c40bd..76d636d13 100644 > --- a/doc/ref/api-debug.texi > +++ b/doc/ref/api-debug.texi > @@ -1,27 +1,125 @@ > @c -*-texinfo-*- > @c This is part of the GNU Guile Reference Manual. > -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, > 2011, 2012, 2013, 2014, 2018, 2021 > +@c Copyright (C) 1996-1997, 2000-2004, 2007, 2010-2014, 2018, 2021, 2024 > @c Free Software Foundation, Inc. > @c See the file guile.texi for copying conditions. > > @node Debugging > @section Debugging Infrastructure > > -@cindex Debugging > -In order to understand Guile's debugging facilities, you first need to > -understand a little about how Guile represents the Scheme control stack. > -With that in place we explain the low level trap calls that the virtual > -machine can be configured to make, and the trap and breakpoint > -infrastructure that builds on top of those calls. > +@cindex debugging > +Guile provides facilities for simple print-based debugging as well as > +more advanced debugging features. In order to understand Guile's > +advanced debugging facilities, one first must understand a little about > +how Guile represents the Scheme control stack. With that in place, we > +can explain the low level trap calls that the virtual machine can be > +configured to make, and the trap and breakpoint infrastructure that > +builds on top of those calls. > > @menu > -* Evaluation Model:: Evaluation and the Scheme stack. > -* Source Properties:: From expressions to source locations. > +* Simple Debugging:: Print-based debugging. > +* Evaluation Model:: Evaluation and the Scheme stack. > +* Source Properties:: From expressions to source locations. > * Programmatic Error Handling:: Debugging when an error occurs. > -* Traps:: Breakpoints, tracepoints, oh my! > -* GDB Support:: C-level debugging with GDB. > +* Traps:: Breakpoints, tracepoints, oh my! > +* GDB Support:: C-level debugging with GDB. > @end menu > > + > +@node Simple Debugging > +@subsection Simple Debugging > + > +Guile offers powerful tools for introspection and debugging at the REPL, > +covered in the rest of this section and elsewhere in this manual > +(@pxref{Interactive Debugging}). Here we deal with a more primitive > +approach, commonly called ``print debugging,'' which is a quick way to > +diagnose simple errors by printing values during a program's execution. > +Guile provides the @code{peek} procedure, more commonly known as > +@code{pk} (pronounced by naming the letters), as a convenient and > +powerful tool for this kind of debugging. > + > +@deffn {Scheme Procedure} peek stuff @dots{} > +@deffnx {Scheme Procedure} pk stuff @dots{} > +Print @var{stuff} to the current output port using @code{write}. Return > +the last argument. > +@end deffn > + > +@code{pk} improves on using @code{write} directly because it enables > +inspection of the state of code as it runs without breaking the normal > +code flow. It is also more convenient than a full debugger because it > +does not require the program to be stopped for inspection. Here is a > +basic example: I hadn't commented on that last sentence before, but if I knew how to have the Guile debugger reliably break where I want it to (I don't, or somehow haven't managed to have it work well), I don't think using 'pk', which requires editing files before and after debugging, could be described as more convenient :-). > +@lisp > +(define fire 'burns) > + > +(pk fire) > +@result{} > + > +;;; (burns) > +burns > +@end > + > +Here is an example of inspecting a value in the midst of code flow: > + > +@lisp > +(map (lambda (v) > + (if (number? v) > + (number->string v) > + (pk v))) > + '(1 "2" "3" 4)) > +@result{} > + > +;;; ("2") > + > +;;; ("3") > +("1" "2" "3" "4") > +@end > + > +A common technique when using @code{pk} is to label values with symbols > +to keep track of where they're coming from. There's no reason these > +labels need to be symbols; symbols are just convenient. Here's a > +slightly more complex example demonstrating that pattern: > + > +@lisp > +(define (pk-identity x) > + (pk 'arg-to-identity x)) > + > +(pk-identity 42) > +@result{} > + > +;;; (arg-to-identity 42) > +42 > +@end > + > +@code{pk} has one small quirk of note. Currently, it only returns the > +first value returned from any multi-value returns. So for example: > + > +@lisp > +(pk 'vals (values 1 2 3)) > +@result{} > + > +;;; (vals 1) > +1 > +@end > + > +The way to get around this limitation is to bind such multi-value > +returns then inspect the results. Still, @code{pk} can only return a > +single value: > + > +@lisp > +(use-modules (srfi srfi-11)) > + > +(let-values (((x y z) > + (values 1 2 3))) > + (pk 'vals x y z)) > +@result{} > + > +;;; (vals 1 2 3) > +3 > +@end > + > + > @node Evaluation Model > @subsection Evaluation and the Scheme Stack I like the new, 'evaluatable' examples :-). It's also a much shorter read. Thanks for sending a v2! I would commit this if I was a committer, but I am not, so here's at least my reviewed trailer: Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail> -- Thanks, Maxim