Received: (at 71684) by debbugs.gnu.org; 23 Jul 2024 15:25:06 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Jul 23 11:25:06 2024 Received: from localhost ([127.0.0.1]:60552 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1sWHNx-0007YB-Ur for submit <at> debbugs.gnu.org; Tue, 23 Jul 2024 11:25:06 -0400 Received: from mx2.dismail.de ([159.69.191.136]:9457) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <jgart@HIDDEN>) id 1sWHNv-0007Xc-Pm for 71684 <at> debbugs.gnu.org; Tue, 23 Jul 2024 11:25:04 -0400 Received: from mx2.dismail.de (localhost [127.0.0.1]) by mx2.dismail.de (OpenSMTPD) with ESMTP id c2f4618f; Tue, 23 Jul 2024 17:24:51 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=dismail.de; h=from:to:cc :subject:in-reply-to:date:message-id:mime-version:content-type; s=20190914; bh=c1esEolH/oLkIKYUtsCkaWFbvNuc7x0Hf4aZbrOLEQA=; b= o7Lh/ixOCY1ZDunCg5incRhNAMfElLNOFIGyR8Zx3yrDRLkdgiN4NIj5F+i6C/BG KzKAodcm7pr8U6pqKUzPTSvYKFt9A0uG00bzIfgeNOXjKGnDGFb7OytvJlfiti1F vUQBskIvKNv7mguQcttCJmBh7cnO5AqoMMnahLR1uFcUADyTk6aoVqsA7ovfbB55 qhHDacnwzfTf4JbafyfATmdJKubePx+XCXLQeevuJjP475VLmnE7ANTAQPFHtRMw 4aczH6mGS9FIpC630oILUTZJzIy0v5pGhgnMM9Qw80Ts9qgQKbnbuLy8BMWssmqe xDrKd2PSzlo3z+4JwLjbkA== Received: from smtp1.dismail.de (<unknown> [10.240.26.11]) by mx2.dismail.de (OpenSMTPD) with ESMTP id f00bbcdc; Tue, 23 Jul 2024 17:24:51 +0200 (CEST) Received: from smtp1.dismail.de (localhost [127.0.0.1]) by smtp1.dismail.de (OpenSMTPD) with ESMTP id ff959676; Tue, 23 Jul 2024 17:24:51 +0200 (CEST) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 4092250c (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Tue, 23 Jul 2024 17:24:50 +0200 (CEST) From: jgart <jgart@HIDDEN> To: 71684 <at> debbugs.gnu.org Subject: Re: [PATCH] doc: Document the peek and pk procedures. In-Reply-To: <CP3PGS.SGM0LJUASK8Q2@HIDDEN> Date: Tue, 23 Jul 2024 10:24:44 -0500 Message-ID: <87y15st9kz.fsf@HIDDEN> MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 71684 Cc: Simon Tournier <zimon.toutoune@HIDDEN>, Maxim Cournoyer <maxim.cournoyer@HIDDEN>, Juliana Sims <juli@HIDDEN> X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -3.3 (---) hi, this looks good to me. let's merge it y'all! -- all best, jgart
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.Received: (at 71684) by debbugs.gnu.org; 16 Jul 2024 02:47:23 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 15 22:47:23 2024 Received: from localhost ([127.0.0.1]:60695 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1sTYDq-00032Y-Sn for submit <at> debbugs.gnu.org; Mon, 15 Jul 2024 22:47:23 -0400 Received: from out-179.mta0.migadu.com ([91.218.175.179]:22559) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <juli@HIDDEN>) id 1sTYDo-00032C-53 for 71684 <at> debbugs.gnu.org; Mon, 15 Jul 2024 22:47:21 -0400 X-Envelope-To: zimon.toutoune@HIDDEN DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=incana.org; s=key1; t=1721098001; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+uplF1hNFhWCtP+pFpxq7jfDQPelZAjyw8cKPPJhDs0=; b=RAKZCmhsZS2OqzF5mzYLSt5kqSnO8jY0NXbUjfp/3vQqEv7ozAySfrlfo+MKxWUGLHL1g9 k3T0nZegti2fxQWv5LETvw5V5hVYkpInMIuWNZyTDviF2WQpKs/GgAgpGQpTwSCW37mfNg 1ARTTHzu8aLoN3Qn/moMpOUfiMFw2lFB0SeS9q1n7V4YJNtb/3gSWYNnfNSkdc67SIT4WT Kirrmrmp1VmNYAXB9qKYtv0qJbxavz2jAfrwUyvqX7tiYnxVLMaL+sF+/nT9wWwc9nbJZD dDHdWxaa/DSNz5US1TagxuJzi+ymwKLgUjnYmTYYvjUIqxdoFQ5HzY3VBuQXcg== X-Envelope-To: maxim.cournoyer@HIDDEN X-Envelope-To: 71684 <at> debbugs.gnu.org Date: Mon, 15 Jul 2024 22:46:24 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@HIDDEN and include these headers. From: Juliana Sims <juli@HIDDEN> Subject: Re: bug#71684: [PATCH v2] doc: Document the peek and pk procedures. To: Simon Tournier <zimon.toutoune@HIDDEN> Message-Id: <CP3PGS.SGM0LJUASK8Q2@HIDDEN> In-Reply-To: <878qy8i9sz.fsf@HIDDEN> References: <87jzi45tyn.fsf@HIDDEN> <20240702164418.11886-1-juli@HIDDEN> <878qy9glbd.fsf@HIDDEN> <877cdtuixm.fsf@HIDDEN> <Maxim Cournoyer's message of "Wed, 10 Jul 2024 15:48:53 -0400"> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-13; format=flowed Content-Transfer-Encoding: quoted-printable X-Migadu-Flow: FLOW_OUT X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 71684 Cc: 71684 <at> debbugs.gnu.org, Maxim Cournoyer <maxim.cournoyer@HIDDEN> X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -1.0 (-) Hi y'all, Thanks for the (continued) reviews! > 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=20 > 'pk', > which requires editing files before and after debugging, could be > described as more convenient :-). A fair point! I can change that wording in a next version of the patch. > I would suggest to apply the =FFpk=FF on the other branch, something=20 > as: >=20 > --8<---------------cut here---------------start------------->8--- > (map (lambda (v) > (if (number? v) > (pk 'number v (number->string v)) > v)) > '(1 "2" "3" 4)) > --8<---------------cut here---------------end--------------->8--- I'm not sure I understand how this improves the demonstration of 'pk'. =20 What does this form of the example demonstrate that the version in the=20 patch does not? It's a minor change so I'm happy to make it; I just=20 want to ensure that we have the best possible version of the solution=20 to the problem you see. Best, Juli
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at 71684) by debbugs.gnu.org; 11 Jul 2024 09:59:41 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jul 11 05:59:41 2024
Received: from localhost ([127.0.0.1]:51096 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sRqaT-00071a-4d
for submit <at> debbugs.gnu.org; Thu, 11 Jul 2024 05:59:41 -0400
Received: from mail-wm1-f44.google.com ([209.85.128.44]:41275)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <zimon.toutoune@HIDDEN>) id 1sRqaQ-000719-JS
for 71684 <at> debbugs.gnu.org; Thu, 11 Jul 2024 05:59:39 -0400
Received: by mail-wm1-f44.google.com with SMTP id
5b1f17b1804b1-426593b99daso900695e9.1
for <71684 <at> debbugs.gnu.org>; Thu, 11 Jul 2024 02:59:38 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=gmail.com; s=20230601; t=1720691913; x=1721296713; darn=debbugs.gnu.org;
h=content-transfer-encoding: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=L03Y+3EKUcnwG16ZTYRNh3Hj4bMXRkGWQzyFSD9I+SE=;
b=US9hhA4HYUk7ltrExQKpYwfzJW7XuZZrz+TKhsjEv3GrTHkN92LNG4AjudqBDpGk92
jas2+iI0mS2YhcntNtogV4fqitAkJZTPEGbZy4x+4HzR9yYOMVW1Doxv1IoEvp5P1oS2
tWA4rNPxPvTnNMWYvsNmTlkhXzyweCU3TISoSIzCLZAGpKKlkf6+kNfXdTykSBDXNF8c
QI5VC9idtRFwDKj5c/y0kV9zIi5CbEvaSgm8ri1yHm/3yzgdi1ZME1AJQMzMkFh2mAhA
gBrSOdvZ6w/Swvqs3W3gARLMShfixPRsqMePEYtcQLspQ8DPYsvuLoe9emAEQZuWeq1i
DGjw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1720691913; x=1721296713;
h=content-transfer-encoding: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=L03Y+3EKUcnwG16ZTYRNh3Hj4bMXRkGWQzyFSD9I+SE=;
b=THsUx7RfxFt90dtfIHA38w5oO37YT7nT6ZKVN+N9YBlpqeid5fOUTfHoABOd8e6UHr
+1lIgI9aSjG+sqCnVujOuJC6JKust9UhfkCt117QFZZJfVK24WCofmGGJcAz10vrGLIZ
+mC2AdfHUPyJFK9b7JQdStyj7CF9OLRnJ7s3Qciv7wvueSoGAdH5QpqwwMQwRsrNlG89
sB6xLOkzEKhHqdwLwnHm8IY4oWWMbXWZ58ZNvcr4ZT8sAhCu51ay5o4UeecS4Dtj/4yd
lRIBCMg9QZiMFzMEV5iWOBX8GyeOxg8xgx21MFnYNvW/5Cr3C+5TFOJMF0k6pMp+KBLA
Ivdg==
X-Gm-Message-State: AOJu0Yw/YZ+afXj4RLxGnHz7pZcON6NYJ1+SW6IzeckM5JY8d1exy4bS
uojOYf/8DiaIlADHCQGKKGZiYJ0J/PJ97Uuw9WXJaWkAloxsUWb5HKGnrA==
X-Google-Smtp-Source: AGHT+IE3FaCo9nR7/s6dKWQ6RfYNwP9xaw00SekGZxQXWoax6RGuq6gm/UiB199aylRWt9H98Sy6nQ==
X-Received: by 2002:a05:6000:1849:b0:366:eb60:bd0c with SMTP id
ffacd0b85a97d-367ceab5f38mr5729177f8f.3.1720691912840;
Thu, 11 Jul 2024 02:58:32 -0700 (PDT)
Received: from lili ([2a01:e0a:59b:9120:a17c:5a42:b196:e92e])
by smtp.gmail.com with ESMTPSA id
ffacd0b85a97d-367cde84655sm7285072f8f.32.2024.07.11.02.58.31
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Thu, 11 Jul 2024 02:58:32 -0700 (PDT)
From: Simon Tournier <zimon.toutoune@HIDDEN>
To: Maxim Cournoyer <maxim.cournoyer@HIDDEN>
Subject: Re: bug#71684: [PATCH v2] doc: Document the peek and pk procedures.
In-Reply-To: <877cdtuixm.fsf@HIDDEN> (Maxim Cournoyer's message of "Wed, 10
Jul 2024 15:48:53 -0400")
References: <87jzi45tyn.fsf@HIDDEN>
<20240702164418.11886-1-juli@HIDDEN> <878qy9glbd.fsf@HIDDEN>
<877cdtuixm.fsf@HIDDEN>
Date: Thu, 11 Jul 2024 10:59:08 +0200
Message-ID: <878qy8i9sz.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 71684
Cc: 71684 <at> debbugs.gnu.org, Juliana Sims <juli@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
Hi Maxim,
On Wed, 10 Jul 2024 at 15:48, Maxim Cournoyer <maxim.cournoyer@HIDDEN> w=
rote:
> I think I'd prefer more simple examples than a single more complicated
> one, if we go that route. I think the text explained 'peek' clearly
> already, though, so I personally would opt to leave it as is, especially
> since adding a 'begin' block to showcase multiple 'pk' calls goes
> against the merit of peek of being least intrusive (it prints then
> returns the value, so the code structure needs not be changed).
Well, I do not have a strong opinion on the topic. :-)
I would suggest to apply the =E2=80=99pk=E2=80=99 on the other branch, some=
thing as:
--8<---------------cut here---------------start------------->8---
(map (lambda (v)
(if (number? v)
(pk 'number v (number->string v))
v))
'(1 "2" "3" 4))
--8<---------------cut here---------------end--------------->8---
Cheers,
simon
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at 71684) by debbugs.gnu.org; 10 Jul 2024 20:21:55 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Jul 10 16:21:54 2024
Received: from localhost ([127.0.0.1]:50384 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sRdp3-0000fN-6T
for submit <at> debbugs.gnu.org; Wed, 10 Jul 2024 16:21:54 -0400
Received: from mail-qt1-f173.google.com ([209.85.160.173]:56754)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <maxim.cournoyer@HIDDEN>) id 1sRdov-0000f5-45
for 71684 <at> debbugs.gnu.org; Wed, 10 Jul 2024 16:21:48 -0400
Received: by mail-qt1-f173.google.com with SMTP id
d75a77b69052e-449f23df593so815011cf.1
for <71684 <at> debbugs.gnu.org>; Wed, 10 Jul 2024 13:21:45 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=gmail.com; s=20230601; t=1720642839; x=1721247639; darn=debbugs.gnu.org;
h=content-transfer-encoding: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=VQpEO1CjFBJKEqjvJAhEIn4V7ZpOjdKIkHieZyg+Br0=;
b=Q0IShakeevJUE1ZY92Yy2Pz8y7sB4scxme+cgg8/YxCjRpIAC5oNf8TKmXoo5mHGkq
jBtGOoUYUljQrvc3owzw/WzJPm9HBBX8XhSFi1VSAuSCZXzObAub9uOLsiGQqcbC4zkc
J5d78HUKAPpJOaO27ltbYaosx04pPn8BonMO1NCv6cN/1x5oL9doMog5M+a444ImLyyc
IXTlIySgDExjAFVni1XN0p1/7qI2ZuM2AvL89GXRE3/vqMuY9/V1zP5NeNp7DFtoEzFg
ToQ8XE2ZMfmeTXxbDH5F5Fb5kXs7KLEIADXL9qYilRRU5xMXdO/zPVBZgpsa7+RSto3U
bzOA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1720642839; x=1721247639;
h=content-transfer-encoding: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=VQpEO1CjFBJKEqjvJAhEIn4V7ZpOjdKIkHieZyg+Br0=;
b=C30wFkbinYMPWMskAb4Hsi93XyfKxEuzuBoioR1mhCUdXn8XW2Tij/e9raWctoyX0w
kPEz0E0CO7cn3rwjcXUY3HcYY8qmLPBg/c3//ywD4dcwwKQz3vwskrzf8ymhnxKN8Kmk
h5ZQ/+z8K1AX9ESkUh/fa3WY+CtsqFN0lejE+1aqY+W94Pq3faFNs0vXI5i+q+HezSpz
AuqOzM0m8ptaUCcvRvgcPg3Es3A2JqC3Ey79AXIIa0QoZLMa/8z0xncZ020bEUNlAhwV
mibesKfr4Pclqu8t8LhSUTkmIAX10Ye7sAliLTBh0eY+C8YtVaIGnwrvnwXSW48g1vAJ
nx0w==
X-Forwarded-Encrypted: i=1;
AJvYcCVu2rexir0uWmN4JtZ6+okhMSPYy1HxqBtEa7tN3IJaK+oJ/ZnkgWli5HQZjU4ubY5HWzg+/vA3n3sCrjH1u3snqnyj5fw=
X-Gm-Message-State: AOJu0YyWdjjFEmpHEzFusUzJeSAjHwsIDzqmNlxczoEQA8eIM7qlh0oZ
Ifce+tmzLFEQDsVP1dmq+VO7yAJ+skTGL/rgEIE0rXl2mfG3RP21sBEw6w==
X-Google-Smtp-Source: AGHT+IFtsHTbQ5qdaRG3q9xtGh2+PxeKhDuwlt+ylylDupe5pZCi7z7iMIJnQuxCKynPsBxH+bTZOw==
X-Received: by 2002:a9d:6a45:0:b0:703:6c93:ac2 with SMTP id
46e09a7af769-70375b40388mr6817183a34.27.1720640935084;
Wed, 10 Jul 2024 12:48:55 -0700 (PDT)
Received: from hurd (dsl-205-236-230-213.b2b2c.ca. [205.236.230.213])
by smtp.gmail.com with ESMTPSA id
6a1803df08f44-6b61b9ebf36sm19715606d6.45.2024.07.10.12.48.54
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Wed, 10 Jul 2024 12:48:54 -0700 (PDT)
From: Maxim Cournoyer <maxim.cournoyer@HIDDEN>
To: Simon Tournier <zimon.toutoune@HIDDEN>
Subject: Re: bug#71684: [PATCH v2] doc: Document the peek and pk procedures.
In-Reply-To: <878qy9glbd.fsf@HIDDEN> (Simon Tournier's message of "Wed, 10
Jul 2024 20:21:10 +0200")
References: <87jzi45tyn.fsf@HIDDEN>
<20240702164418.11886-1-juli@HIDDEN> <878qy9glbd.fsf@HIDDEN>
Date: Wed, 10 Jul 2024 15:48:53 -0400
Message-ID: <877cdtuixm.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 71684
Cc: 71684 <at> debbugs.gnu.org, Juliana Sims <juli@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
Hi Simon,
Simon Tournier <zimon.toutoune@HIDDEN> writes:
[...]
>> +@lisp
>> +(map (lambda (v)
>> + (if (number? v)
>> + (number->string v)
>> + (pk v)))
>> + '(1 "2" "3" 4))
>> +@result{}
>> +
>> +;;; ("2")
>> +
>> +;;; ("3")
>> +("1" "2" "3" "4")
>> +@end
>
> For what it is worth, I would suggest something as:
>
> (map (lambda (v)
> (if (number? v)
> (number->string v)
> (begin
> (pk 'else v)
> (pk (string-append "-" v "0")))))
> '(1 "2" "3" 4))
>
> For two reasons:
>
> 1. =E2=80=99begin=E2=80=99 helps to mark a sequence of expressions; IMHO=
, that=E2=80=99s a good
> habit when playing with =E2=80=99pk=E2=80=99 for debugging purpose.
>
> 2. it exposes that =E2=80=99stuff=E2=80=99 above can be anything.
>
>
> Well, my suggestion could be two other examples in addition to the
> current one instead of the complexification.
I think I'd prefer more simple examples than a single more complicated
one, if we go that route. I think the text explained 'peek' clearly
already, though, so I personally would opt to leave it as is, especially
since adding a 'begin' block to showcase multiple 'pk' calls goes
against the merit of peek of being least intrusive (it prints then
returns the value, so the code structure needs not be changed).
--=20
Thanks,
Maxim
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at 71684) by debbugs.gnu.org; 10 Jul 2024 18:42:06 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Jul 10 14:42:06 2024
Received: from localhost ([127.0.0.1]:57158 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sRcGU-0005eW-1x
for submit <at> debbugs.gnu.org; Wed, 10 Jul 2024 14:42:06 -0400
Received: from mail-wm1-f48.google.com ([209.85.128.48]:40732)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <zimon.toutoune@HIDDEN>) id 1sRcGS-0005d9-04
for 71684 <at> debbugs.gnu.org; Wed, 10 Jul 2024 14:42:04 -0400
Received: by mail-wm1-f48.google.com with SMTP id
5b1f17b1804b1-4266ea4e4bdso98725e9.3
for <71684 <at> debbugs.gnu.org>; Wed, 10 Jul 2024 11:41:57 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=gmail.com; s=20230601; t=1720636852; x=1721241652; darn=debbugs.gnu.org;
h=content-transfer-encoding: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=g7ggMLZ7zOnunYvhCUsYkf+cpHCbcl2m+JXCm3Rd2wY=;
b=Qp9KSOUpw2MKYoiQdpm0yCyLS39Q+KUtZDUswRHVGaliAr7UjoXPeR/9utsYNb6ZfN
2uX1MU5uHAfiFMDUzyEut3j8z4TW4NDUWahVNEXB1G781LNbi6BbhVN9BMozlCKWB+pP
C6ep/aLxj+v2e1OLQ76RzMh4XxQFkrz4rUbZQxLJJ3SokPbSq91y9tJiChdZwW6qJvGC
kAW2AvGnLQIpGkcZdb1zS+OzSmB0wKkW2dHIX5wv5k3zEwEx6ACKpO/Ullsp1oww6Zwi
8uMeQ4H5Q70W2mytOy/OShMI3Idbn8phk908US3uzlqnV4mw/uo/wStYvHAuL8JxpCdM
L49w==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1720636852; x=1721241652;
h=content-transfer-encoding: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=g7ggMLZ7zOnunYvhCUsYkf+cpHCbcl2m+JXCm3Rd2wY=;
b=SahKEqrtub8+INuUFZTVpjqZcyXWrkcxjZXwDeBArkNzJ/gVJxdCp4A0w7tlQZA2Uy
JW67BWJ7nLVlxTLdegD1X9Ro1oJHYgATcO8GSOKfk+Lp9AmHPIXYhW+dsjqDnmtJRZZs
6Ne9C0ieM2dmUW3KM+gX+dgVBuoxtE76de2iKba2LDPLqwD8M9pFguDaIA+HdOiMiL2b
GArXlISkQ7+mlStvz/1yz6zO20BndNB8s+ryMfoXU9waDwRjv2caO5HH47rAJ4uvLGnl
yhkVVOi/i4a/UAK0sZJswcKsQ1ZmO8Vm5SK81FFPWNgitkfePiU2bgicOv8soBMS89Vf
B4pg==
X-Forwarded-Encrypted: i=1;
AJvYcCWx3FWTte0kVrvuLAMLoKbyMD71EZ4E7tB96bUQFPje0wdNm9a3zry8zm05bthrN2skImIO3pBm9B8KZGnvMmICmVUwFiU=
X-Gm-Message-State: AOJu0YwSEM84BUgr1+v/V+4+E0NIYdFAfsHPGrdu9E06fu+M0/ydhPGg
wjNoiZWuDME9yeQ5Mt3HAYkj4QQwqdzavs7YaSclKyUqO9YgRuqws1IVHw==
X-Google-Smtp-Source: AGHT+IHtS96LSzip/JvUmtpitDEGCPfhywXIiWoqHefQUCP5T4xswINUda7pCwCYKneCax5+KinCng==
X-Received: by 2002:a5d:6c63:0:b0:367:95e3:e4d5 with SMTP id
ffacd0b85a97d-367f058775dmr270807f8f.2.1720636851706;
Wed, 10 Jul 2024 11:40:51 -0700 (PDT)
Received: from lili (roam-nat-fw-prg-194-254-61-41.net.univ-paris-diderot.fr.
[194.254.61.41]) by smtp.gmail.com with ESMTPSA id
ffacd0b85a97d-367cdfab748sm5913669f8f.111.2024.07.10.11.40.50
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Wed, 10 Jul 2024 11:40:51 -0700 (PDT)
From: Simon Tournier <zimon.toutoune@HIDDEN>
To: Juliana Sims <juli@HIDDEN>
Subject: Re: bug#71684: [PATCH v2] doc: Document the peek and pk procedures.
In-Reply-To: <20240702164418.11886-1-juli@HIDDEN> (Juliana Sims's message
of "Tue, 2 Jul 2024 12:28:17 -0400")
References: <87jzi45tyn.fsf@HIDDEN> <20240702164418.11886-1-juli@HIDDEN>
Date: Wed, 10 Jul 2024 20:21:10 +0200
Message-ID: <878qy9glbd.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 71684
Cc: 71684 <at> debbugs.gnu.org, maxim.cournoyer@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
Hi,
On Tue, 02 Jul 2024 at 12:28, Juliana Sims <juli@HIDDEN> wrote:
> * doc/ref/api-debug.texi: Document the peek and pk procedures.
Cool! Thanks.
> 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 su=
re
> 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 sett=
ings
> geared to that purpose. I used manual filling this time so hopefully that=
issue
> has been resolved.
Yeah, that=E2=80=99s because double-space after period fixes ambiguous case=
s as
this example: =E2=80=9CThe author J. R. R. Tolkien wrote The Hobbit. George
R. R. Martin wrote many fantasy books.=E2=80=9D The brain is able to deter=
mine
it=E2=80=99s only two sentences, but it becomes more difficult otherwise; it
could count 7 sentences.
https://en.wikipedia.org/wiki/Sentence_spacing#Computer_era
Anyway. :-)
> +@lisp
> +(map (lambda (v)
> + (if (number? v)
> + (number->string v)
> + (pk v)))
> + '(1 "2" "3" 4))
> +@result{}
> +
> +;;; ("2")
> +
> +;;; ("3")
> +("1" "2" "3" "4")
> +@end
For what it is worth, I would suggest something as:
--8<---------------cut here---------------start------------->8---
(map (lambda (v)
(if (number? v)
(number->string v)
(begin
(pk 'else v)
(pk (string-append "-" v "0")))))
'(1 "2" "3" 4))
--8<---------------cut here---------------end--------------->8---
For two reasons:
1. =E2=80=99begin=E2=80=99 helps to mark a sequence of expressions; IMHO, =
that=E2=80=99s a good
habit when playing with =E2=80=99pk=E2=80=99 for debugging purpose.
2. it exposes that =E2=80=99stuff=E2=80=99 above can be anything.
Well, my suggestion could be two other examples in addition to the
current one instead of the complexification.
My 2 cents. :-)
Cheers,
simon
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at 71684) by debbugs.gnu.org; 9 Jul 2024 02:58:12 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 08 22:58:12 2024
Received: from localhost ([127.0.0.1]:51826 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sR13T-0003Mm-EA
for submit <at> debbugs.gnu.org; Mon, 08 Jul 2024 22:58:11 -0400
Received: from mail-qv1-f48.google.com ([209.85.219.48]:47325)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <maxim.cournoyer@HIDDEN>) id 1sR13Q-0003MV-Kj
for 71684 <at> debbugs.gnu.org; Mon, 08 Jul 2024 22:58:09 -0400
Received: by mail-qv1-f48.google.com with SMTP id
6a1803df08f44-6b5d3113168so26764906d6.2
for <71684 <at> 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)
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)
From: Maxim Cournoyer <maxim.cournoyer@HIDDEN>
To: Juliana Sims <juli@HIDDEN>
Subject: Re: [PATCH v2] doc: Document the peek and pk procedures.
In-Reply-To: <20240702164418.11886-1-juli@HIDDEN> (Juliana Sims's message
of "Tue, 2 Jul 2024 12:28:17 -0400")
References: <87jzi45tyn.fsf@HIDDEN> <20240702164418.11886-1-juli@HIDDEN>
Date: Mon, 08 Jul 2024 22:56:55 -0400
Message-ID: <87r0c3w9vs.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 71684
Cc: 71684 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
Hi Juliana,
Juliana Sims <juli@HIDDEN> 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 <maxim.cournoyer@gmail>
--
Thanks,
Maxim
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at 71684) by debbugs.gnu.org; 2 Jul 2024 16:45:36 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Jul 02 12:45:36 2024
Received: from localhost ([127.0.0.1]:37525 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sOgdM-0003cV-2v
for submit <at> debbugs.gnu.org; Tue, 02 Jul 2024 12:45:36 -0400
Received: from out-177.mta0.migadu.com ([91.218.175.177]:37090)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <juli@HIDDEN>) id 1sOgdJ-0003cC-A9
for 71684 <at> debbugs.gnu.org; Tue, 02 Jul 2024 12:45:34 -0400
X-Envelope-To: maxim.cournoyer@HIDDEN
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 <at> debbugs.gnu.org
X-Envelope-To: juli@HIDDEN
X-Report-Abuse: Please report any abuse attempt to abuse@HIDDEN and
include these headers.
From: Juliana Sims <juli@HIDDEN>
To: maxim.cournoyer@HIDDEN
Subject: [PATCH v2] doc: Document the peek and pk procedures.
Date: Tue, 2 Jul 2024 12:28:17 -0400
Message-ID: <20240702164418.11886-1-juli@HIDDEN>
In-Reply-To: <87jzi45tyn.fsf@HIDDEN>
References: <87jzi45tyn.fsf@HIDDEN>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-Migadu-Flow: FLOW_OUT
X-Spam-Score: -0.0 (/)
X-Debbugs-Envelope-To: 71684
Cc: 71684 <at> debbugs.gnu.org, Juliana Sims <juli@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
* 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
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at 71684) by debbugs.gnu.org; 2 Jul 2024 03:56:12 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 01 23:56:12 2024
Received: from localhost ([127.0.0.1]:35377 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sOUcl-000220-CO
for submit <at> debbugs.gnu.org; Mon, 01 Jul 2024 23:56:12 -0400
Received: from mail-qv1-f42.google.com ([209.85.219.42]:42412)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <maxim.cournoyer@HIDDEN>) id 1sOUcg-00021R-0j
for 71684 <at> debbugs.gnu.org; Mon, 01 Jul 2024 23:56:09 -0400
Received: by mail-qv1-f42.google.com with SMTP id
6a1803df08f44-6b4ffc2a7abso27789256d6.1
for <71684 <at> debbugs.gnu.org>; Mon, 01 Jul 2024 20:56:05 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=gmail.com; s=20230601; t=1719892498; x=1720497298; 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=9j/Pml5AwNNPAUsrr0H5DRoXeqWvRy8X7ihGwIFFXVE=;
b=eyYnVerbMo36bj2H5HOrffTAGmuZ5X6RCxNuC07uDe+08AtIuXDAyTnzk85B49JB5S
O6i3SbmGXyvSCNfibuNSobTbsJ2E2BCyVGZwUvnpOUfOIEXBprS6ZKcqEpbiB+nRE1Q6
VnDxR5Vf71Xly9WK6FvbdNDUlM+XGOvFblrgfTvflb9K2jtu2OGKE7+mKZmGRRVxGopM
u41Z0z3APjOm7eUG1Q75ZKtk4tQsXxsGokd6zkAN++YVukp2OrusTbLlSNo45U9j1680
YDTcekJpMPbMH/x6pQIIo5vv9aD1me/+4m9yzN6or76Dn2IO9OhPsXYL/YktnMzk6hh2
OwFQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1719892498; x=1720497298;
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=9j/Pml5AwNNPAUsrr0H5DRoXeqWvRy8X7ihGwIFFXVE=;
b=w2qNyoHK45j7phI2rxVh6+u5jwCqQ3zSR2rEVa9uykJx7fM9HA+adDRS3AVPnzLesZ
9uKFHTrVg14gzTu7DxN4Y2M+7qD6jGpeMuOkfIPup/BsYsJpd4Sy9Ns/50XlShDRCt7s
9hc1AqjakBHUyYQaEqBHnsIpuKg6tPmp3EjbEQ6gkl2+uRZMAlRIlxq8oOxdk/oSRi6f
6TikK5dopmGRLDdOZPJzKc3fTrvBiPN2IUebJczfx37GxG7IOXKeWZVoMZhwke9apk5P
bqUGV78JtTXzhsI2SJkQ6kJHtI/h6dwY5T2VWxGzB9txIJhy4kYn4lj0Tv/4XRezaxVC
OdUA==
X-Gm-Message-State: AOJu0Yy7rydVPjnjmO5Bhe1+fK7MFM5lCY34Guo5h+vMFjafgXe1AnY1
qTIbnGATMq3voAmnZi20K208HEXcPVKZQ/NlIaBU/smrgyFRNtpF46kcmA==
X-Google-Smtp-Source: AGHT+IEJgZnxPB/WpoUenZUCcrpBSayzgMbnFHjssat2LRI/heu0E9vTwEk8SYQrJlWElLpqbk9xOA==
X-Received: by 2002:a05:6214:27ce:b0:6b5:335e:8ae4 with SMTP id
6a1803df08f44-6b5b6e75deamr131264576d6.1.1719892498295;
Mon, 01 Jul 2024 20:54:58 -0700 (PDT)
Received: from hurd (dsl-159-108.b2b2c.ca. [66.158.159.108])
by smtp.gmail.com with ESMTPSA id
6a1803df08f44-6b59e5f262asm39567726d6.89.2024.07.01.20.54.57
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Mon, 01 Jul 2024 20:54:57 -0700 (PDT)
From: Maxim Cournoyer <maxim.cournoyer@HIDDEN>
To: Juliana Sims <juli@HIDDEN>
Subject: Re: bug#71684: [PATCH] doc: Document the peek and pk procedures.
In-Reply-To: <20240620185415.9088-1-juli@HIDDEN> (Juliana Sims's message
of "Thu, 20 Jun 2024 14:54:15 -0400")
References: <20240620185415.9088-1-juli@HIDDEN>
Date: Mon, 01 Jul 2024 23:54:56 -0400
Message-ID: <87jzi45tyn.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 71684
Cc: 71684 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
Hi Juliana!
Juliana Sims <juli@HIDDEN> writes:
> * doc/ref/api-debug.texi: Document the peek and pk procedures.
This looks very useful! Thanks for authoring it.
> ---
> doc/ref/api-debug.texi | 187 +++++++++++++++++++++++++++++++++++++++--
> 1 file changed, 179 insertions(+), 8 deletions(-)
>
> diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
> index faa0c40bd..486473cdb 100644
> --- a/doc/ref/api-debug.texi
> +++ b/doc/ref/api-debug.texi
> @@ -1,27 +1,198 @@
> @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.
The typographical convention for Texinfo/Guile documentation is to use
two spaces to separate sentences.
>
> @menu
> +* 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.
> +* Programmatic Error Handling:: Debugging when an error occurs.
To be valid, Texinfo menu entry description must be indented at least 2
spaces from the node name (so you should drop the above hunk). I use in
Emacs: Menu 'Texinfo -> Update all menus' to ease maintaining these, in
case it's useful.
> * 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.'' Let's be honest: for most
> +of us, this is our first line of debugging. And Guile doesn't judge us
> +for it! Instead, Guile provides a powerful and convenient tool to
> +facilitate print debugging: the @code{peek} procedure, more commonly
> +known as @code{pk} (pronounced by naming the letters).
> +
> +@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} allows us to look at the state of our code as it runs without
> +having to step through it or break the normal code flow. Let's take a
> +look at how one might use it. Let's say we have a procedure to make a
> +smore, perhaps as part of a mod for a cozy space exploration game.
I think using an impersonal tone would match better the style of the
rest of the manual (for example, replacing the above with "@code{pk}
allows looking at the state of a program as it runs without having to
[...]) -- that is, removing the 'we' and 'us'. I find it otherwise
reads a bit more like a tutorial (it's more engaging with the reader,
which isn't bad, but it clashes with the rest of this reference manual).
> +@lisp
> +(define (make-smore marshmallow graham-crackers chocolate fire)
> + "Toast @var{mashmallow} over @var{fire} then sandwich it and
> +@var{chocolate} between @var{graham-crackers}."
> + (let ((toasted-marshmallow
> + (toast marshmallow fire)))
> + (unless (or (burned? toasted-marshmallow)
> + (undercooked? toasted-marshmallow))
> + (cons (car graham-crackers)
> + (cons toasted-marshmallow
> + (cons chocolate
> + (cons (cdr graham-crackers) '())))))))
> +@end lisp
> +
> +We've run this procedure a few times, and it isn't doing what we expect.
> +Instead of getting a tasty smore, we get nothing. Let's use @code{pk} to
> +find out what's going on.
> +
> +@lisp
> +(pk (make-smore (grab-one marshmallow-bag)
> + (cons graham-cracker graham-cracker)
> + campfire))
> +
> +;;; (#<unspecified>)
> +@end lisp
> +
> +@code{#<unspecified>} is a value in Guile which indicates that no Scheme
> +standard specifies a return value for whatever is returning it. In this
> +case, it probably means that our @code{unless} check is not proving
> +true, so the procedure returns nothing. Let's add a @code{pk} around the
> +call to @code{toast} and see what happens.
> +
> +@lisp
> +(define (make-smore marshmallow graham-crackers chocolate fire)
> + "Toast @var{mashmallow} over @var{fire} then sandwich it and
> +@var{chocolate} between @var{graham-crackers}."
> + (let ((toasted-marshmallow
> + ;; Let's see what state the toasted-marshmallow is in
> + (pk 'toasted-marshmallow (toast marshmallow fire))))
> + (unless (or (burned? toasted-marshmallow)
> + (undercooked? toasted-marshmallow))
> + (cons (car graham-crackers)
> + (cons toasted-marshmallow
> + (cons chocolate
> + (cons (cdr graham-crackers) '())))))))
> +
> +(make-smore (grab-one marshmallow-bag)
> + (cons graham-cracker graham-cracker)
> + campfire)
> +
> +;;; (toasted-marshmallow #<<marshmallow> state: raw>)
> +@end lisp
> +
> +Our marshmallow isn't getting cooked at all! Let's see if we can find
> +out why. We'll check on the state of @var{fire} since we know that
> +@code{toast} just operates on the state of the fire and of the
> +marshmallow. @code{toasted-marshmallow} matches the state we expect for
> +a fresh marshmallow, so the problem is probably with the fire.
> +
> +@lisp
> +(define (make-smore marshmallow graham-crackers chocolate fire)
> + "Toast @var{mashmallow} over @var{fire} then sandwich it and
> +@var{chocolate} between @var{graham-crackers}."
> + (let ((toasted-marshmallow
> + ;; Now we'll check on the fire, too
> + (pk 'toasted-marshmallow (toast marshmallow (pk 'fire fire)))))
> + (unless (or (burned? toasted-marshmallow)
> + (undercooked? toasted-marshmallow))
> + (cons (car graham-crackers)
> + (cons toasted-marshmallow
> + (cons chocolate
> + (cons (cdr graham-crackers) '())))))))
> +
> +(make-smore (grab-one marshmallow-bag)
> + (cons graham-cracker graham-cracker)
> + campfire)
> +
> +;;; (fire #<<fire> state: unlit>)
> +
> +;;; (toasted-marshmallow #<<marshmallow> state: raw>)
> +@end lisp
> +
> +Oh, well that makes sense! A fire can't cook a marshmallow if it isn't
> +lit!
> +
> +Notice that the result of evaluating the @code{pk} around @code{fire} is
> +printed before the one around @code{toast}. This is just the result of
> +the normal process of evaluating s-expressions from the inside out. We
> +highlight it because it can be confusing at first, especially with more
> +@code{pk}s in more complex code.
> +
> +Let's add a guard to light the fire and run our procedure again.
> +
> +@lisp
> +(define (make-smore marshmallow graham-crackers chocolate fire)
> + "Toast @var{mashmallow} over @var{fire} then sandwich it and
> +@var{chocolate} between @var{graham-crackers}."
> + (let ((toasted-marshmallow
> + (toast marshmallow fire)))
> + (unless (lit? fire)
> + (light fire))
> + (unless (or (burned? toasted-marshmallow)
> + (undercooked? toasted-marshmallow))
> + (cons (car graham-crackers)
> + (cons toasted-marshmallow
> + (cons chocolate
> + (cons (cdr graham-crackers) '())))))))
> +
> +(make-smore (grab-one marshmallow-bag)
> + (cons graham-cracker graham-cracker)
> + campfire)
> +@result{} (#<<graham-cracker>> #<<marshmallow> state: cooked> #<<chocolate>> #<<graham-cracker>>)
> +@end lisp
> +
> +Yay! Now it works, and we have a tasty smore!
The examples were fun, but it's very verbose to explain what it does,
and the examples can't be evaluated at the REPL, which departs from the
rest of the manual. I think a simple example that can be evaluated at
the REPL may more succinctly express the effect of 'pk'.
> +As we demonstrated, you can pass in any number of arguments and the
> +result of evaluating the last argument is the value returned from
> +@code{pk}. This is handy to, as we showed, wrap code in-line without
> +needing to add extra steps along the way while still providing
> +informative labels about what, exactly, is getting printed. We could as
> +easily have put @code{pk}s completely on their own, rather than wrapping
> +other code. This is commonly used to, for example, test if a given
> +procedure or part of a procedure is entered. Earlier, we could have put
> +a @code{pk} in the body of the @code{unless} clause to let us know if we
> +entered it, such as:
> +
> +@lisp
> +(define (make-smore ...)
> + ...
> + (unless ...
> + (pk 'inside-unless)
> + ...))
> +@end lisp
> +
> +As a final note, labels don't have to be symbols. @code{pk} will happily
> +print any object we pass it. We could have used strings or anything else
> +we wanted alongside the code we were interested in.
> +
> +Hopefully this silly little example has shown the utility of @code{pk}.
> +Now that it's in your toolbox, go forth, newly empowered, and happy
> +hacking!
The last sentence reads like the end of a blog post rather than a
section of the manual, at least to me. Perhaps I have too many gray
hairs :-)
If you agree to my feedback, I think a v2 with a switch to impersonal
verbs, as well as using the two spaces convention would be an easy
improvement. I'd personally prefer a simpler, perhaps boring example
that can be evaluated directly at the REPL to the more verbose (but
funny) smore adventure that I can't readily experiment with, but I'll
leave others to comment.
--
Thanks,
Maxim
bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
Received: (at submit) by debbugs.gnu.org; 20 Jun 2024 18:55:03 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jun 20 14:55:03 2024
Received: from localhost ([127.0.0.1]:40361 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1sKMw2-0006Cb-Lt
for submit <at> debbugs.gnu.org; Thu, 20 Jun 2024 14:55:03 -0400
Received: from lists.gnu.org ([209.51.188.17]:37306)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <juli@HIDDEN>) id 1sKMvz-0006C6-Tq
for submit <at> debbugs.gnu.org; Thu, 20 Jun 2024 14:55:01 -0400
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 <juli@HIDDEN>) id 1sKMvv-0000M1-Ia
for bug-guile@HIDDEN; Thu, 20 Jun 2024 14:54:55 -0400
Received: from out-176.mta0.migadu.com ([2001:41d0:1004:224b::b0])
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <juli@HIDDEN>) id 1sKMvs-00079i-R0
for bug-guile@HIDDEN; Thu, 20 Jun 2024 14:54:55 -0400
X-Envelope-To: bug-guile@HIDDEN
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=incana.org; s=key1;
t=1718909688;
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;
bh=KpiGpSZmiyctv0wiOwbcy7ef2/mV+XkDhirN8stkQro=;
b=jEtS4GTk324yW+TgQ3V4BA0rEWXF6XJTs9AyHobxgspL3MDoiD0EPjyijBqqOb76++v2yG
KukXKqnvezhqKBsWT+k260CBJZQgNjXisLmYkCbz+F2e1rLqZGq2dpOj8y9IIHUXkSKLBE
rUy7jejR6J2aIROtqimoAzhftsXqusW6LMn7jxQMwqHAJ/vnKjU8JKHhnxPSywrZgkaZb2
OqT4JnQPtqp7wqxm1/E5h6x2eWkMxJl/OKGNHTv0CH+e+7cAepnUWQkWfaUEKDyieVtXJG
x4OOJAFz5nzZkdCrsJfawQsN4i4dK2eRgEbWUuMHSUYNNve2G5ZkHKwe9OdD4g==
X-Envelope-To: juli@HIDDEN
X-Report-Abuse: Please report any abuse attempt to abuse@HIDDEN and
include these headers.
From: Juliana Sims <juli@HIDDEN>
To: bug-guile@HIDDEN
Subject: [PATCH] doc: Document the peek and pk procedures.
Date: Thu, 20 Jun 2024 14:54:15 -0400
Message-ID: <20240620185415.9088-1-juli@HIDDEN>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-Migadu-Flow: FLOW_OUT
Received-SPF: pass client-ip=2001:41d0:1004:224b::b0;
envelope-from=juli@HIDDEN; helo=out-176.mta0.migadu.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001,
SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -1.4 (-)
X-Debbugs-Envelope-To: submit
Cc: Juliana Sims <juli@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.4 (--)
* doc/ref/api-debug.texi: Document the peek and pk procedures.
---
doc/ref/api-debug.texi | 187 +++++++++++++++++++++++++++++++++++++++--
1 file changed, 179 insertions(+), 8 deletions(-)
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index faa0c40bd..486473cdb 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -1,27 +1,198 @@
@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
+* 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.
+* Programmatic Error Handling:: Debugging when an error occurs.
* 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.'' Let's be honest: for most
+of us, this is our first line of debugging. And Guile doesn't judge us
+for it! Instead, Guile provides a powerful and convenient tool to
+facilitate print debugging: the @code{peek} procedure, more commonly
+known as @code{pk} (pronounced by naming the letters).
+
+@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} allows us to look at the state of our code as it runs without
+having to step through it or break the normal code flow. Let's take a
+look at how one might use it. Let's say we have a procedure to make a
+smore, perhaps as part of a mod for a cozy space exploration game.
+
+@lisp
+(define (make-smore marshmallow graham-crackers chocolate fire)
+ "Toast @var{mashmallow} over @var{fire} then sandwich it and
+@var{chocolate} between @var{graham-crackers}."
+ (let ((toasted-marshmallow
+ (toast marshmallow fire)))
+ (unless (or (burned? toasted-marshmallow)
+ (undercooked? toasted-marshmallow))
+ (cons (car graham-crackers)
+ (cons toasted-marshmallow
+ (cons chocolate
+ (cons (cdr graham-crackers) '())))))))
+@end lisp
+
+We've run this procedure a few times, and it isn't doing what we expect.
+Instead of getting a tasty smore, we get nothing. Let's use @code{pk} to
+find out what's going on.
+
+@lisp
+(pk (make-smore (grab-one marshmallow-bag)
+ (cons graham-cracker graham-cracker)
+ campfire))
+
+;;; (#<unspecified>)
+@end lisp
+
+@code{#<unspecified>} is a value in Guile which indicates that no Scheme
+standard specifies a return value for whatever is returning it. In this
+case, it probably means that our @code{unless} check is not proving
+true, so the procedure returns nothing. Let's add a @code{pk} around the
+call to @code{toast} and see what happens.
+
+@lisp
+(define (make-smore marshmallow graham-crackers chocolate fire)
+ "Toast @var{mashmallow} over @var{fire} then sandwich it and
+@var{chocolate} between @var{graham-crackers}."
+ (let ((toasted-marshmallow
+ ;; Let's see what state the toasted-marshmallow is in
+ (pk 'toasted-marshmallow (toast marshmallow fire))))
+ (unless (or (burned? toasted-marshmallow)
+ (undercooked? toasted-marshmallow))
+ (cons (car graham-crackers)
+ (cons toasted-marshmallow
+ (cons chocolate
+ (cons (cdr graham-crackers) '())))))))
+
+(make-smore (grab-one marshmallow-bag)
+ (cons graham-cracker graham-cracker)
+ campfire)
+
+;;; (toasted-marshmallow #<<marshmallow> state: raw>)
+@end lisp
+
+Our marshmallow isn't getting cooked at all! Let's see if we can find
+out why. We'll check on the state of @var{fire} since we know that
+@code{toast} just operates on the state of the fire and of the
+marshmallow. @code{toasted-marshmallow} matches the state we expect for
+a fresh marshmallow, so the problem is probably with the fire.
+
+@lisp
+(define (make-smore marshmallow graham-crackers chocolate fire)
+ "Toast @var{mashmallow} over @var{fire} then sandwich it and
+@var{chocolate} between @var{graham-crackers}."
+ (let ((toasted-marshmallow
+ ;; Now we'll check on the fire, too
+ (pk 'toasted-marshmallow (toast marshmallow (pk 'fire fire)))))
+ (unless (or (burned? toasted-marshmallow)
+ (undercooked? toasted-marshmallow))
+ (cons (car graham-crackers)
+ (cons toasted-marshmallow
+ (cons chocolate
+ (cons (cdr graham-crackers) '())))))))
+
+(make-smore (grab-one marshmallow-bag)
+ (cons graham-cracker graham-cracker)
+ campfire)
+
+;;; (fire #<<fire> state: unlit>)
+
+;;; (toasted-marshmallow #<<marshmallow> state: raw>)
+@end lisp
+
+Oh, well that makes sense! A fire can't cook a marshmallow if it isn't
+lit!
+
+Notice that the result of evaluating the @code{pk} around @code{fire} is
+printed before the one around @code{toast}. This is just the result of
+the normal process of evaluating s-expressions from the inside out. We
+highlight it because it can be confusing at first, especially with more
+@code{pk}s in more complex code.
+
+Let's add a guard to light the fire and run our procedure again.
+
+@lisp
+(define (make-smore marshmallow graham-crackers chocolate fire)
+ "Toast @var{mashmallow} over @var{fire} then sandwich it and
+@var{chocolate} between @var{graham-crackers}."
+ (let ((toasted-marshmallow
+ (toast marshmallow fire)))
+ (unless (lit? fire)
+ (light fire))
+ (unless (or (burned? toasted-marshmallow)
+ (undercooked? toasted-marshmallow))
+ (cons (car graham-crackers)
+ (cons toasted-marshmallow
+ (cons chocolate
+ (cons (cdr graham-crackers) '())))))))
+
+(make-smore (grab-one marshmallow-bag)
+ (cons graham-cracker graham-cracker)
+ campfire)
+@result{} (#<<graham-cracker>> #<<marshmallow> state: cooked> #<<chocolate>> #<<graham-cracker>>)
+@end lisp
+
+Yay! Now it works, and we have a tasty smore!
+
+As we demonstrated, you can pass in any number of arguments and the
+result of evaluating the last argument is the value returned from
+@code{pk}. This is handy to, as we showed, wrap code in-line without
+needing to add extra steps along the way while still providing
+informative labels about what, exactly, is getting printed. We could as
+easily have put @code{pk}s completely on their own, rather than wrapping
+other code. This is commonly used to, for example, test if a given
+procedure or part of a procedure is entered. Earlier, we could have put
+a @code{pk} in the body of the @code{unless} clause to let us know if we
+entered it, such as:
+
+@lisp
+(define (make-smore ...)
+ ...
+ (unless ...
+ (pk 'inside-unless)
+ ...))
+@end lisp
+
+As a final note, labels don't have to be symbols. @code{pk} will happily
+print any object we pass it. We could have used strings or anything else
+we wanted alongside the code we were interested in.
+
+Hopefully this silly little example has shown the utility of @code{pk}.
+Now that it's in your toolbox, go forth, newly empowered, and happy
+hacking!
+
+
@node Evaluation Model
@subsection Evaluation and the Scheme Stack
--
2.45.1
Juliana Sims <juli@HIDDEN>:bug-guile@HIDDEN.
Full text available.bug-guile@HIDDEN:bug#71684; Package guile.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.