exceptions: improve non-error @(throw) and @(assert).

When @(throw) generates a non-error exception that is
unhandled, we just want it to continue. In the same situation,
an @(assert) should behave as a failed match; that is, the
failure of the query material that follows the assert, which
activated it, should propagate through the assert.

* match.c (v_throw): Return next_spec_k if uw_rthrow
returns.
(v_assert, h_assert): Return nil if uw_rthrow returns.

* txr.1: Expanded @(throw) and @(assert) documentation with
discussion of unhandled exceptions.

2 files changed, 42 insertions, 3 deletions

diff --git a/match.c b/match.c
index 39e0dfa2..394843c3 100644
--- a/match.c
+++ b/match.c
@@ -4092,7 +4092,8 @@ static val v_throw(match_files_ctx *c)
   {
     val values = mapcar(pa_123_2(func_n3(txeval_allow_ub),
                                     specline, c->bindings), args);
-    return uw_rthrow(type, values);
+    uw_rthrow(type, values);
+    return next_spec_k;
   }
 }
 
@@ -4311,7 +4312,7 @@ static val v_assert(match_files_ctx *c)
     } else if (type) {
       val values = mapcar(pa_123_2(func_n3(txeval_allow_ub),
                                       specline, c->bindings), args);
-      uw_rthrow(type, values);
+      return uw_rthrow(type, values);
     } else {
       if (c->curfile)
         typed_error(assert_s, first_spec, lit("assertion (at ~a:~d)"), c->curfile, c->data_lineno, nao);
@@ -4548,7 +4549,7 @@ static val h_assert(match_line_ctx *c)
   } else if (type) {
     val values = mapcar(pa_123_2(func_n3(txeval_allow_ub),
                                  c->specline, c->bindings), elem);
-    uw_rthrow(type, values);
+    return uw_rthrow(type, values);
   } else {
     if (c->file)
       typed_error(assert_s, elem, lit("assertion (at ~a:~d)"), c->file, c->data_lineno, nao);
diff --git a/txr.1 b/txr.1
index 963b2f89..308777a6 100644
--- a/txr.1
+++ b/txr.1
@@ -10593,6 +10593,25 @@ if
 .code abc
 matches.
 
+If
+.code throw
+is used to generate an exception derived from type
+.code error
+and that exception is not handled, \*(TX will issue diagnostics on the
+.code *stderr*
+stream and terminate. If an exception derived from
+.code warning
+is not handled, \*(TX will generate diagnostics on the
+.code *stderr*
+stream, after which control returns to the
+.code throw
+directive, and proceeds with the next directive.
+If an exception not derived from
+.code error
+is thrown, control returns to the
+.code throw
+directive and proceeds with the next directive.
+
 .dir defex
 
 The
@@ -10856,6 +10875,25 @@ followed by a successful match for
 .strn "d@x" ,
 or else an exception is thrown.
 
+If the exception is not handled, and is derived from
+.code error
+then \*(TX issues diagnostics on the
+.code *stderr*
+stream and terminates. If the exception is derived from
+.code warning
+and not handled, \*(TX issues a diagnostic on
+.code *stderr*
+after which control returns to the
+.code assert
+directive. Control silently returns to the
+.code assert
+directive if an exception of any other kind is not handled.
+
+When control returns to
+.code assert
+due to an unhandled exception, it behaves like a failed match,
+similarly to the require directive.
+
 .SH* TXR LISP
 The \*(TX language contains an embedded Lisp dialect called \*(TL.