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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Subject: bug#75041: closed (Re: [PATCH] doc/srfi-64: Fix typos and add
 examples.)
Date: Fri, 24 Jan 2025 18:30:02 +0000

[Message part 1 (text/plain, inline)]

Your bug report

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

which was filed against the guile package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 75041 <at> debbugs.gnu.org.

-- 
75041: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=75041
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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

[Message part 3 (message/rfc822, inline)]

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

Previous Next

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