From: Juliana Sims via "Bug reports for GUILE, GNU's Ubiquitous Extension Language" <bug-guile@gnu.org>
To: zimon.toutoune@gmail.com
Cc: 71684@debbugs.gnu.org, maxim.cournoyer@gmail.com, juli@incana.org
Subject: bug#71684: [PATCH v3] doc: Document the peek and pk procedures.
Date: Fri, 13 Sep 2024 16:03:52 -0400 [thread overview]
Message-ID: <20240913200453.2965-1-juli@incana.org> (raw)
In-Reply-To: <CAJ3okZ1OoTWk3kvpNaCDMYCqRfUTkzXgYfe2R9UcWDvKSZ5e8A@mail.gmail.com>
* 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
prev parent reply other threads:[~2024-09-13 20:03 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-06-20 18:54 bug#71684: [PATCH] doc: Document the peek and pk procedures Juliana Sims via Bug reports for GUILE, GNU's Ubiquitous Extension Language
2024-07-02 3:54 ` Maxim Cournoyer
2024-07-02 16:28 ` bug#71684: [PATCH v2] " Juliana Sims via Bug reports for GUILE, GNU's Ubiquitous Extension Language
2024-07-09 2:56 ` Maxim Cournoyer
2024-09-13 15:47 ` Maxim Cournoyer
2024-07-10 18:21 ` Simon Tournier
2024-07-10 19:48 ` Maxim Cournoyer
2024-07-11 8:59 ` Simon Tournier
2024-07-16 2:46 ` Juliana Sims via Bug reports for GUILE, GNU's Ubiquitous Extension Language
2024-07-23 15:24 ` bug#71684: [PATCH] " jgart via Bug reports for GUILE, GNU's Ubiquitous Extension Language
2024-09-13 15:42 ` bug#71684: [PATCH v2] " Maxim Cournoyer
2024-09-13 16:03 ` Simon Tournier
2024-09-13 20:03 ` Juliana Sims via Bug reports for GUILE, GNU's Ubiquitous Extension Language [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240913200453.2965-1-juli@incana.org \
--to=bug-guile@gnu.org \
--cc=71684@debbugs.gnu.org \
--cc=juli@incana.org \
--cc=maxim.cournoyer@gmail.com \
--cc=zimon.toutoune@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).