GNU bug report logs - #75041
[PATCH] doc/srfi-64: Fix typos and add examples.

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 23 Dec 2024 04:59:40 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sun Dec 22 23:59:40 2024
Received: from localhost ([127.0.0.1]:52843 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1tPaXc-00069x-42
	for submit <at> debbugs.gnu.org; Sun, 22 Dec 2024 23:59:40 -0500
Received: from lists.gnu.org ([209.51.188.17]:38754)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <maxim.cournoyer@HIDDEN>) id 1tPaXZ-00069n-P1
 for submit <at> debbugs.gnu.org; Sun, 22 Dec 2024 23:59:38 -0500
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 <maxim.cournoyer@HIDDEN>)
 id 1tPaXZ-0006TB-Ir
 for bug-guile@HIDDEN; Sun, 22 Dec 2024 23:59:37 -0500
Received: from mail-pf1-x42d.google.com ([2607:f8b0:4864:20::42d])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <maxim.cournoyer@HIDDEN>)
 id 1tPaXX-0006N3-2u
 for bug-guile@HIDDEN; Sun, 22 Dec 2024 23:59:36 -0500
Received: by mail-pf1-x42d.google.com with SMTP id
 d2e1a72fcca58-728e1799d95so4252221b3a.2
 for <bug-guile@HIDDEN>; Sun, 22 Dec 2024 20:59:34 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=gmail.com; s=20230601; t=1734929973; x=1735534773; darn=gnu.org;
 h=content-transfer-encoding:mime-version:message-id:date:subject:cc
 :to:from:from:to:cc:subject:date:message-id:reply-to;
 bh=b0DsOgHwhQJE8gKN2RMg2ORqhVvgzj/Dpy9vK86bFFc=;
 b=GgNUzpQDNl/wH2PQSn1Nf79bDmg9KRXN/q38IetIV4jNXOej8LVzCOd1Q4d/4K8Ff8
 ejZnHult9Ka/iTkP2hRLQD02ZmVh5yxliZgGGkHs3HUUXw6Bo6GlpZBKvo94huHaS+Hg
 Ar+P33VnKcE6HxAiKWhJXDfijD1b+lHtWkfpGJ44Y4C7rcy2iz0g/afZYA2RpBZBBd9q
 TfFsc4AIzakSf+1VPv02NVbNIlwBo7N7zfzm/LOvckW3Qmc6eURN2FkAOLl9RUd7l+Iw
 pFpEvYwJ3+wrmyc9PlxlEf93CCSaKjJnulE1KRQQ3ykcOEbb3JImW/0omXnxd+rxIll/
 VxwA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1734929973; x=1735534773;
 h=content-transfer-encoding:mime-version:message-id:date:subject:cc
 :to:from:x-gm-message-state:from:to:cc:subject:date:message-id
 :reply-to;
 bh=b0DsOgHwhQJE8gKN2RMg2ORqhVvgzj/Dpy9vK86bFFc=;
 b=QkPuozzY/yLkMV2TcjLFqpOmw73SWHPnszWoUFFnjII3TQFNcW6eFl1clG/4gcZLaN
 rJ86/p8J4PAT6sZyMt620no5auqpFMe1jwgJWwVRIPe4PR/ordutEf3oV1FPEtzAbGud
 gXkEnPwc1OCfZ+iGjeb4tlDPLAciZVwlltSMUK++yAwBXM7WStY9t3gltKegj58uwIJP
 0IYHNRpl9Ph0C44bDLIFzQpkcya0hDyV97iWEPautedl2kHF8OoLBRoTjg/DhXMI/WwJ
 L47h/iHemzzbBH6HOJ8OLwmAj2j1Omw/kRojAsEFTis40haQR3TtPGaO+C7anlEbXc9a
 LhCw==
X-Gm-Message-State: AOJu0YwvjcgSVAmibO1FJlKe5wgbSM0X1jU43Z42DpSRFHY9HaAl4CYt
 MKiJJMl7WcnO0KWMnNE21RjbzSuQLjXK1lPwFUFwE3xs+OGG04uo8LDZvw==
X-Gm-Gg: ASbGncsjoJNWZRUBpb8BCPzobunR6LJBEkszFOo8y7oGJQsX+u2bmttDpETWycIRYl0
 lZrsnSo+1k5x6TiQXRDx/4TQOLmLHXndu8yZ4gE0mcyNBo7wUum7z0cHOEWoZoMmO0vmbkLtP3I
 70JCYGMc5zdO1Ek5yYIc53kL0ObW9a0qgD822aBvc6VisDiR7F8h4vIMJU2jL+QR1BpvAn8ghoE
 +KBrI7Y8JTAAlUXJMTFQ16F72L/Yjk3GCHEW6VhB31+3EOy/8EyjZZdmmEZuRDqv1Kg9fCheX4=
X-Google-Smtp-Source: AGHT+IE4MSz/zVDmQ1WwGjAeAtxFlqeWg4oczgom4W1pZxnV5e/jOgbBtovaELb2R+87q5cYCa5rdA==
X-Received: by 2002:a05:6a00:44cc:b0:725:df1a:275 with SMTP id
 d2e1a72fcca58-72abdeb7016mr18367942b3a.23.1734929972906; 
 Sun, 22 Dec 2024 20:59:32 -0800 (PST)
Received: from localhost.localdomain ([2405:6586:be0:0:c8ff:1707:9b9:af89])
 by smtp.gmail.com with ESMTPSA id
 41be03b00d2f7-842b2b3e83dsm5437059a12.32.2024.12.22.20.59.31
 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
 Sun, 22 Dec 2024 20:59:32 -0800 (PST)
From: Maxim Cournoyer <maxim.cournoyer@HIDDEN>
To: bug-guile@HIDDEN
Subject: [PATCH] doc/srfi-64: Fix typos and add examples.
Date: Mon, 23 Dec 2024 13:59:14 +0900
Message-ID: <20241223045914.16142-1-maxim.cournoyer@HIDDEN>
X-Mailer: git-send-email 2.46.0
MIME-Version: 1.0
X-Debbugs-CC: ludo@HIDDEN
X-Debbugs-CC: arne_bab@HIDDEN
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Received-SPF: pass client-ip=2607:f8b0:4864:20::42d;
 envelope-from=maxim.cournoyer@HIDDEN; helo=mail-pf1-x42d.google.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, FREEMAIL_FROM=0.001,
 RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001,
 SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -1.3 (-)
X-Debbugs-Envelope-To: submit
Cc: Arne Babenhauserheide <arne_bab@HIDDEN>,
 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: -2.3 (--)

* doc/ref/srfi-modules.texi (SRFI-64 Writing Basic Test Suites): Fix
typo.  Add default test runner example.  Add test-approximate and
test-error examples.  Document valid error types in Guile for test-error.
(SRFI-64 Conditonal Test Suites and Other Advanced Features): Fix typo.

Suggested-by: Arne Babenhauserheide <arne_bab@HIDDEN>
---
 doc/ref/srfi-modules.texi | 83 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index d77bc1c90..537ec9059 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -5387,13 +5387,31 @@ is also easy to add new tests, without having to name individual tests
 (though that is optional).
 
 Test cases are executed in the context of a @dfn{test runner}, which is
-a object that accumulates and reports test results.  This specification
+an object that accumulates and reports test results.  This specification
 defines how to create and use custom test runners, but implementations
 should also provide a default test runner.  It is suggested (but not
 required) that loading the above file in a top-level environment will
 cause the tests to be executed using an implementation-specified default
 test runner, and @code{test-end} will cause a summary to be displayed in
-an implementation-specified manner.
+an implementation-specified manner.  The SRFI 64 implementation used in
+Guile provides such a default test runner; running the above snippet at
+the REPL prints:
+
+@example
+*** Entering test group: vec-test ***
+$1 = #t
+* PASS:
+$2 = ((pass . 1))
+* PASS:
+$3 = ((pass . 2))
+* PASS:
+$4 = ((pass . 3))
+*** Leaving test group: vec-test ***
+*** Test suite finished. ***
+*** # of expected passes    : 3
+@end example
+
+It also returns the @code{<test-runner>} object.
 
 @subsubheading Simple test-cases
 
@@ -5455,6 +5473,14 @@ once):
   (and (>= test-expr (- expected error))
        (<= test-expr (+ expected error))))
 @end lisp
+
+Here's an example:
+@lisp
+(test-approximate "is 22/7 within 1% of π?"
+ 3.1415926535
+ 22/7
+ 1/100)
+@end lisp
 @end deffn
 
 @subsubheading Tests for catching errors
@@ -5492,8 +5518,59 @@ classes:
 
 An implementation that cannot catch exceptions should skip
 @code{test-error} forms.
+
+@cindex test-error error types
+@cindex error types, test-error, srfi-64
+The SRFI-64 implementation in Guile supports specifying @var{error-type}
+as either:
+@iterate
+@item
+@code{#f}, meaning the test is @emph{not} expected to produce an error
+@item
+@code{#t}, meaning the test is expected to produce an error, of any type
+@item
+A native exception type, as created via @code{make-exception-type} or
+@code{make-condition-type} from SRFI-35
+@item
+A predicate, which will be applied to the exception caught
+to determine whether is it of the right type
+@item
+A symbol, for the exception kind of legacy
+@code{make-exception-from-throw} style exceptions.
 @end deffn
 
+Below are some examples valid in Guile:
+
+@lisp
+(test-error "expect old-style exception kind"
+ 'numerical-overflow
+ (/ 1 0))
+@end lisp
+
+@lisp
+(use-modules (ice-9 exceptions)) ;for standard exception types
+
+(test-error "expect a native exception type"
+ &warning
+ (raise-exception (make-warning)))
+
+(test-error "expect a native exception, using predicate"
+ warning?
+ (raise-exception (make-warning)))
+@end lisp
+
+@lisp
+(use-modules (srfi srfi-35))
+
+(test-error "expect a serious SRFI 35 condition type"
+ &serious
+ (raise-exception (condition (&serious))))
+
+(test-error "expect a serious SRFI 35 condition type, using predicate"
+ serious-condition?
+ (raise-exception (condition (&serious))))
+@end lisp
+
 @subsubheading Testing syntax
 
 Testing syntax is tricky, especially if we want to check that invalid
@@ -5617,7 +5694,7 @@ or specifying that some tests are @emph{expected} to fail.
 @subsubheading Test specifiers
 
 Sometimes we want to only run certain tests, or we know that certain
-tests are expected to fail.  A @dfn{test specifier} is one-argument
+tests are expected to fail.  A @dfn{test specifier} is a one-argument
 function that takes a test-runner and returns a boolean.  The specifier
 may be run before a test is performed, and the result may control
 whether the test is executed.  For convenience, a specifier may also be

base-commit: f6359a4715d023761454f1bf945633ce4cca98fc
-- 
2.46.0