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

Previous Next

Package: guile;

Reported by: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>

Date: Mon, 23 Dec 2024 05:00:02 UTC

Severity: normal

Tags: patch

Done: lloda <lloda <at> sarc.name>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 75041 in the body.
You can then email your comments to 75041 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to arne_bab <at> web.de, bug-guile <at> gnu.org:
bug#75041; Package guile. (Mon, 23 Dec 2024 05:00:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Maxim Cournoyer <maxim.cournoyer <at> gmail.com>:
New bug report received and forwarded. Copy sent to arne_bab <at> web.de, bug-guile <at> gnu.org. (Mon, 23 Dec 2024 05:00:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: bug-guile <at> gnu.org
Cc: Arne Babenhauserheide <arne_bab <at> web.de>,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Subject: [PATCH] doc/srfi-64: Fix typos and add examples.
Date: Mon, 23 Dec 2024 13:59:14 +0900
* 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 <at> web.de>
---
 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





Reply sent to lloda <lloda <at> sarc.name>:
You have taken responsibility. (Fri, 24 Jan 2025 18:30:02 GMT) Full text and rfc822 format available.

Notification sent to Maxim Cournoyer <maxim.cournoyer <at> gmail.com>:
bug acknowledged by developer. (Fri, 24 Jan 2025 18:30:02 GMT) Full text and rfc822 format available.

Message #10 received at 75041-done <at> debbugs.gnu.org (full text, mbox):

From: lloda <lloda <at> sarc.name>
To: 75041-done <at> debbugs.gnu.org
Subject: Re: [PATCH] doc/srfi-64: Fix typos and add examples.
Date: Fri, 24 Jan 2025 19:29:17 +0100
Applied in f109baebc005952a58726ee80b56bc5ef291af92. 

Thanks






Information forwarded to bug-guile <at> gnu.org:
bug#75041; Package guile. (Sat, 25 Jan 2025 01:18:02 GMT) Full text and rfc822 format available.

Message #13 received at 75041 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: lloda <lloda <at> sarc.name>
Cc: 75041 <at> debbugs.gnu.org
Subject: Re: bug#75041: closed (Re: [PATCH] doc/srfi-64: Fix typos and add
 examples.)
Date: Sat, 25 Jan 2025 10:17:09 +0900
Hello,

[...]

> From: lloda <lloda <at> sarc.name>
> Subject: Re: [PATCH] doc/srfi-64: Fix typos and add examples.
> To: 75041-done <at> debbugs.gnu.org
> Date: Fri, 24 Jan 2025 19:29:17 +0100 (6 hours, 47 minutes, 1 second ago)
>
>
> Applied in f109baebc005952a58726ee80b56bc5ef291af92. 

Excellent, thank you!

-- 
Maxim




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sat, 22 Feb 2025 12:24:23 GMT) Full text and rfc822 format available.

This bug report was last modified 113 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.