* doc/ref/api-debug.texi: Document the peek and pk procedures. --- Hey y'all,
Thanks for the feedback! I've incorporated both suggestions in this new patch. Best, Juli doc/ref/api-debug.texi | 120 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 11 deletions(-) diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index faa0c40bd..df109d390 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 sometimes more practical than a full debugger +because it does not require the program to be stopped for inspection. +Here is a basic example: + +@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) + (pk 'number->string (number->string v)) + v)) + '(1 "2" "3" 4)) +@result{} + +;;; ("1") + +;;; ("4") +("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 base-commit: d0790d766bedf08fb65231eff53f6c8044eb94f1 -- 2.46.0