From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Juliana Sims via "Bug reports for GUILE, GNU's Ubiquitous Extension Language" Newsgroups: gmane.lisp.guile.bugs Subject: bug#71684: [PATCH v2] doc: Document the peek and pk procedures. Date: Tue, 2 Jul 2024 12:28:17 -0400 Message-ID: <20240702164418.11886-1-juli@incana.org> References: <87jzi45tyn.fsf@gmail.com> Reply-To: Juliana Sims Mime-Version: 1.0 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34440"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 71684@debbugs.gnu.org, Juliana Sims To: maxim.cournoyer@gmail.com Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Tue Jul 02 18:46:32 2024 Return-path: Envelope-to: guile-bugs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1sOgeF-0008gm-V9 for guile-bugs@m.gmane-mx.org; Tue, 02 Jul 2024 18:46:32 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sOgdo-0001fY-3U; Tue, 02 Jul 2024 12:46:04 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sOgdl-0001fH-Pf for bug-guile@gnu.org; Tue, 02 Jul 2024 12:46:02 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sOgdl-0001Cw-H6 for bug-guile@gnu.org; Tue, 02 Jul 2024 12:46:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1sOgdm-0003dU-IJ for bug-guile@gnu.org; Tue, 02 Jul 2024 12:46:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Juliana Sims Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Tue, 02 Jul 2024 16:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 71684 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Original-Received: via spool by 71684-submit@debbugs.gnu.org id=B71684.171993873613923 (code B ref 71684); Tue, 02 Jul 2024 16:46:02 +0000 Original-Received: (at 71684) by debbugs.gnu.org; 2 Jul 2024 16:45:36 +0000 Original-Received: from localhost ([127.0.0.1]:37525 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sOgdM-0003cV-2v for submit@debbugs.gnu.org; Tue, 02 Jul 2024 12:45:36 -0400 Original-Received: from out-177.mta0.migadu.com ([91.218.175.177]:37090) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sOgdJ-0003cC-A9 for 71684@debbugs.gnu.org; Tue, 02 Jul 2024 12:45:34 -0400 X-Envelope-To: maxim.cournoyer@gmail.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=incana.org; s=key1; t=1719938695; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=BKlDKNRy3281KJKUQRrrtbtrRe/dGAJRKEPMmioSXB4=; b=zkYPH8ohrbHNe4/5c2QjW4uc10QE+QAXF95ZQhpqZA4o1l34+9TiIgkAdUzVeD81KaMEP3 PaRO9YEjwM2gBaPGyi1IRb/3v2P8jpluRy/L3ONzZbwaPL/HViY30V7iQnaQzbICMgHS7q pH7eEo1WE5Fwp1uucLT/+oY47s+f0XEJ+WLhfuwbybqO/U3ABW+C2rp9HXZZ2hYPMlaua5 kh0OiIMXaMEH4OA88m+6uqsQf8iH6R2pOAGs1qpaDn12D7NjGBvkqgOnmOSY1x7o6ND1Vl 2iYh7xC6XZp01OzWAgACGTbbqVY/hz2zKzc3SrbACJ0AkFN9p0g8BjeK24/OYw== X-Envelope-To: 71684@debbugs.gnu.org X-Envelope-To: juli@incana.org X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. In-Reply-To: <87jzi45tyn.fsf@gmail.com> X-Migadu-Flow: FLOW_OUT X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.bugs:10881 Archived-At: * 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. I didn't use Emacs to regenerate all the menus in this file because it produced diffs in unrelated sections. 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. 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..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: + +@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 -- 2.45.1