bug#71684: [PATCH v2] Add peek-error, pke.

[janneke]

Janneke Nieuwenhuizen writes:

With #71684 merged, this needs an update.  New in this version:
    * document it!

Greetings,
Janneke

>From c0a856ac60a672db53d3ab7df8098a323fbb999a Mon Sep 17 00:00:00 2001
From: Janneke Nieuwenhuizen <janneke@gnu.org>
Date: Fri, 3 Mar 2023 11:26:34 +0100
Subject: [PATCH v2] Add peek-error, pke.
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=UTF-8

Debuging using `pk' is popular in Guile, but not really usable if the
program is as (pseudo-)filter, i.e., writing its output to stdout.

* module/ice-9/boot-9.scm (peek-error, pke): New procedures.
* doc/ref/api-debug.texi (Simple Debugging): Document them.
---
 doc/ref/api-debug.texi  | 13 ++++++++++---
 module/ice-9/boot-9.scm | 10 ++++++++++
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index ca5175b35c..35092fbdaf 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -34,9 +34,10 @@ 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.
+Guile provides the @code{peek} and @code{peek-error} procedures, more
+commonly known as @code{pk} and @code{pke} respectively (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{}
@@ -44,6 +45,12 @@ Print @var{stuff} to the current output port using 
@code{write}.  Return
 the last argument.
 @end deffn
 
+@deffn {Scheme Procedure} peek-error stuff @dots{}
+@deffnx {Scheme Procedure} pke stuff @dots{}
+Print @var{stuff} to the current error 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
diff --git a/module/ice-9/boot-9.scm b/module/ice-9/boot-9.scm
index 04f84215c9..4b611f6a9d 100644
--- a/module/ice-9/boot-9.scm
+++ b/module/ice-9/boot-9.scm
@@ -183,6 +183,16 @@ This is handy for tracing function calls, e.g.:
 
 (define pk peek)
 
+(define (peek-error . stuff)
+  "Like PEEK (PK), writing to (CURRENT-ERROR-PORT)."
+  (newline (current-error-port))
+  (display ";;; " (current-error-port))
+  (write stuff (current-error-port))
+  (newline (current-error-port))
+  (car (last-pair stuff)))
+
+(define pke peek-error)
+
 (define (warn . stuff)
   (newline (current-warning-port))
   (display ";;; WARNING " (current-warning-port))
-- 
Janneke Nieuwenhuizen <janneke@gnu.org>  | GNU LilyPond https://LilyPond.org
Freelance IT https://www.JoyOfSource.com | Avatar® https://AvatarAcademy.com

-- 
Janneke Nieuwenhuizen <janneke@gnu.org>  | GNU LilyPond https://LilyPond.org
Freelance IT https://www.JoyOfSource.com | Avatar® https://AvatarAcademy.com