From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Maxim Cournoyer Newsgroups: gmane.lisp.guile.bugs Subject: bug#71684: [PATCH v2] doc: Document the peek and pk procedures. Date: Mon, 08 Jul 2024 22:56:55 -0400 Message-ID: <87r0c3w9vs.fsf@gmail.com> References: <87jzi45tyn.fsf@gmail.com> <20240702164418.11886-1-juli@incana.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="32010"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 71684@debbugs.gnu.org To: Juliana Sims Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Tue Jul 09 04:59:16 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 1sR14V-000847-DJ for guile-bugs@m.gmane-mx.org; Tue, 09 Jul 2024 04:59:15 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sR14F-0006qC-4t; Mon, 08 Jul 2024 22:58:59 -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 1sR14D-0006kG-HD for bug-guile@gnu.org; Mon, 08 Jul 2024 22:58:57 -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 1sR14D-0005v6-9H for bug-guile@gnu.org; Mon, 08 Jul 2024 22:58:57 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1sR14I-0003Nv-F6 for bug-guile@gnu.org; Mon, 08 Jul 2024 22:59:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Tue, 09 Jul 2024 02:59: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.172049389212949 (code B ref 71684); Tue, 09 Jul 2024 02:59:02 +0000 Original-Received: (at 71684) by debbugs.gnu.org; 9 Jul 2024 02:58:12 +0000 Original-Received: from localhost ([127.0.0.1]:51826 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sR13T-0003Mm-EA for submit@debbugs.gnu.org; Mon, 08 Jul 2024 22:58:11 -0400 Original-Received: from mail-qv1-f48.google.com ([209.85.219.48]:47325) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sR13Q-0003MV-Kj for 71684@debbugs.gnu.org; Mon, 08 Jul 2024 22:58:09 -0400 Original-Received: by mail-qv1-f48.google.com with SMTP id 6a1803df08f44-6b5d3113168so26764906d6.2 for <71684@debbugs.gnu.org>; Mon, 08 Jul 2024 19:58:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1720493817; x=1721098617; darn=debbugs.gnu.org; h=mime-version:user-agent:message-id:date:references:in-reply-to :subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to; bh=B9TiOTR7ybGihEEfTRtiZOFojary03rcEs8jXCBNQgg=; b=NDD2rMKOMwPyO9ZkA/KPJCO8WCk+P1X/BdUVaj/oHCSbqEwQV+z7CEm2ylnWjV+Huy w2j6AUOwrpDfpSeb0xysXuHub1kXdY7OVFNIL2WjKH8h4tNpKmsRBKmmHurJ2sP4k6Is PQ1t2I6YLpi9pnx3IbtPDo4u+ajZ8iXfXSKCtKJ+8Vb6wBiIiXoWb4Ko0CZg/5GTpQXI JQCy6ORHhiOlzdpVGrojHTK0B1YHcTtp5boq0KSHNyooCFvgXt3XKqiPPu8OPv4xnFJL D/ZNsMXHLzRqxrvfM8L8QMhlw53KneW+j6ulBw7rtZ+84I6uC9h9qOenST1huEA7dNtB YyKw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1720493817; x=1721098617; h=mime-version:user-agent:message-id:date:references:in-reply-to :subject:cc:to:from:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=B9TiOTR7ybGihEEfTRtiZOFojary03rcEs8jXCBNQgg=; b=JfAE7ox6IDAMK+yLWIzhkiXGEOJPlslq91BPLrdBkq8iN0vxBR2C2DG8xrkTAhlzV0 BYvPI/JQtDL8P2TyFqy9PhWUKTaW7vY9zqrIsR0pBhTSPbHK/aX8ed3pdOxJEbVmb8lY Ow7+iTwZ4MwvT8jJGvNXhJL8v6IFW9i2msSzgC3ieFGgrJg4R7AEnfXfhBU95iYs5tAJ 041AI8+KZNXsbXOa0XWf1j+4rcKg/GphbEZgIJVYKAdmmW5tv+rCbcG99xcv8pkJjL7A 601ijamX+kBF0fqxUGprKdUhYtizXvNnqBcFWiJm5McfSl7qL0F3COzigJGMaPEbCW1J X5pg== X-Gm-Message-State: AOJu0YwV/Zv23WUzVtZ/yXqqqUQtvYhNT1hH0YNZBxzL0D7uMpLkC5JD tQ9oPdtBmt0RTxapdMvPCtl3Z0eSFYPguTEL9qzlZw1rG2kbkqi3kxfrIw== X-Google-Smtp-Source: AGHT+IFfQfp+5G1BGjI/TaEoA/KAgBcnVFWaucp/72OYScFPWGdUVp+ds9ZQ2NH5mStZoElo1XzFXA== X-Received: by 2002:a05:6214:20e9:b0:6b0:7d9a:79f1 with SMTP id 6a1803df08f44-6b61c1af4eamr16444736d6.42.1720493816585; Mon, 08 Jul 2024 19:56:56 -0700 (PDT) Original-Received: from hurd (dsl-205-236-230-124.b2b2c.ca. [205.236.230.124]) by smtp.gmail.com with ESMTPSA id 6a1803df08f44-6b61ba77767sm5052136d6.95.2024.07.08.19.56.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 08 Jul 2024 19:56:56 -0700 (PDT) In-Reply-To: <20240702164418.11886-1-juli@incana.org> (Juliana Sims's message of "Tue, 2 Jul 2024 12:28:17 -0400") 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:10887 Archived-At: Hi Juliana, Juliana Sims 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 -- Thanks, Maxim