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 v4] doc: Document the peek and pk procedures. Date: Mon, 14 Oct 2024 08:53:47 -0400 Message-ID: <20241014125422.19427-1-juli@incana.org> References: <87ttdfce14.fsf@gnu.org> 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="7867"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 71684@debbugs.gnu.org, Juliana Sims , maxim.cournoyer@gmail.com, zimon.toutoune@gmail.com To: janneke@gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Mon Oct 14 14:56:09 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 1t0KcK-0001rn-5W for guile-bugs@m.gmane-mx.org; Mon, 14 Oct 2024 14:56:08 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1t0Kbz-0005gR-Ew; Mon, 14 Oct 2024 08:55:47 -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 1t0Kby-0005gG-0S for bug-guile@gnu.org; Mon, 14 Oct 2024 08:55:46 -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 1t0Kbx-0005qv-OH for bug-guile@gnu.org; Mon, 14 Oct 2024 08:55:45 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=B6W6XzY7kgeT1y/GDbkrHunQ/gcfiFsNd2+xc8tfWNQ=; b=W8JtlUPpz1Y694CHtXRgtkiAQ28fbHqKIMEhN/9AaP25v4aLUGGnVV/VSsEyV5NfAyhH+TJ2XicQnEx9P2LOI7LWeJDrOUYEtKcB5nrNkcob+FbiDwpaNZICaxSqNS3IGgjOsHvsK4KrzP5gRawrDEWH3fxlK4dhBtQDUxk4USL1q4ZREYXjn/+zd2oR05fwcrS3WkNu8rtsd9unekpRYzdlPRBCBHNXuwO9GslA/12dvWVbhFondibNrAI0D+Lf2bVbeffQUYvWz+BU4EL9W13Mjkt9+q6VsLf8mhQyoCZZK6mevqFaMj/f7ePynZeAPxjUPnmuXw42tyrj8XZBNQ==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1t0KcE-0000pS-6h for bug-guile@gnu.org; Mon, 14 Oct 2024 08:56:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Juliana Sims Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Mon, 14 Oct 2024 12:56: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.17289105523166 (code B ref 71684); Mon, 14 Oct 2024 12:56:02 +0000 Original-Received: (at 71684) by debbugs.gnu.org; 14 Oct 2024 12:55:52 +0000 Original-Received: from localhost ([127.0.0.1]:37159 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t0Kc3-0000ox-JW for submit@debbugs.gnu.org; Mon, 14 Oct 2024 08:55:52 -0400 Original-Received: from out-181.mta0.migadu.com ([91.218.175.181]:10227) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1t0Kc1-0000oi-H4 for 71684@debbugs.gnu.org; Mon, 14 Oct 2024 08:55:50 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=incana.org; s=key1; t=1728910495; 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=B6W6XzY7kgeT1y/GDbkrHunQ/gcfiFsNd2+xc8tfWNQ=; b=BJbypuCKTNMpYtpJZRowxv5JZR/AWdO9ENWY7ldyxtc0/HJZEWXfr5c5rys14UMco0Fh8F /ITasJRToTLlKuDFv01bpZnD32dZ2o+IJ5cseZ+qjsIyZnzboId5/awnWapky6fRv/PfrL f9/iddXbp+ZmLWe6y5TFA+lECw+PZLpZ2h/FPCVwpZhXFFUBPCZGsu5WAahHIZOk7ZqD3t 38Vqk6KMlJuA8jSdyzYhq4zwDpHeOgwle6T4HGRiJWv6bopzo+ulnerHuEzXUppMU3KCjd e7G7BfVMx/kYLVRm+u7Xyg5jsQzeG2e+gCUjwP7KZVEJDrT+qxehUbtNHpKUbQ== In-Reply-To: <87ttdfce14.fsf@gnu.org> 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:11038 Archived-At: * doc/ref/api-debug.texi: Document the peek and pk procedures. --- doc/ref/api-debug.texi | 120 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 11 deletions(-) Hi Janneke, Thanks for the catch! That's fixed in this version :) Best, Juli diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index faa0c40bd..ca5175b35 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 lisp + +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 lisp + +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 lisp + +@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 lisp + +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 lisp + + @node Evaluation Model @subsection Evaluation and the Scheme Stack -- 2.46.0