remove-path: exception semantics adjusted.

* stream.c (remove_path): The second argument now defaults to
false rather than true, and controls only whether an exception
is thrown in the non-existence case. Thus, the function throws
errors by default, as before, but doesn't throw by default if
the failure reason is that the path doesn't exist. Previously
it threw by default in all situations, and the flag turned all
errors into a nil return.

* txr.1: Documented.

2 files changed, 14 insertions, 8 deletions

diff --git a/stream.c b/stream.c
index d5886336..13b3e787 100644
--- a/stream.c
+++ b/stream.c
@@ -4217,7 +4217,7 @@ static val sh(val command)
 val remove_path(val path, val throw_on_error)
 {
   if (w_remove(c_str(path)) < 0) {
-    if (throw_on_error)
+    if (default_null_arg(throw_on_error) || errno != ENOENT)
       uw_throwf(file_error_s, lit("trying to remove ~a: ~d/~s"),
                   path, num(errno), string_utf8(strerror(errno)), nao);
     return nil;
diff --git a/txr.1 b/txr.1
index 83fcf372..fdf52365 100644
--- a/txr.1
+++ b/txr.1
@@ -47628,15 +47628,21 @@ which may be a file, directory or something else.
 If successful, it returns
 .codn t .
 
-A failure to remove the object results in an exception of type
-.codn file-error ,
-unless
-.meta throw-on-error-p
-is present, and its value is
+The optional Boolean parameter
+.metn throw-on-error-p ,
+which defaults to
 .codn nil .
-In that case, failure is indicated by a
+
+A failure to remove the object results in an exception of type
+.code file-error
+being thrown, unless the failure reason is that the object indicated by
+.meta path
+doesn't exist. In this non-existence case, the behavior is controlled by the
+.meta throw-on-error
+argument. If that argument is true, the exception is thrown. Otherwise,
+the function returns normally, producing the value
 .code nil
-return value.
+to indicate that it didn't perform a removal.
 
 .coNP Function @ rename-path
 .synb