awk macro: bugfix: :output file stream not closed.

In the case when the :output clause of the awk macro opens a
stream, it isn't closing it. Why don't we treat such a stream
uniformly with redirections.

* share/txr/stdlib/awk.tl (sys:awk-state :postinit):
If a file is opened for output, then don't just install
this file as self.output. Also place it into the self.streams
hash, identified by using the key (:outf <name>), just
like a (-> "name") redirection. This ensures that it will
be closed when the awk macro terminates. It's also potentially
useful in that output redirections referring to the name will
use the same stream.

* txr.1: Documented that streams opened by :output are
closed, and that they are treated uniformly with redirections.

1 files changed, 32 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index bd1eeed8..a0cbd8e8 100644
--- a/txr.1
+++ b/txr.1
@@ -44734,6 +44734,38 @@ can rebind
 causing the definition provided by
 .code :output
 to be shadowed.
+
+In the case when the
+.code :output
+argument is a string such that a new stream is opened
+on the file, the
+.code awk
+macro will close that stream when it finishes executing.
+Moreover, that stream is treated uniformly as a member of
+the set of streams that are implicitly managed by the
+redirection macros in the same
+.code awk
+macro invocation. In brief, the implication is that if
+.code :output
+creates a stream for the file path name
+.str "out.txt"
+and somewhere in the same
+.code awk
+macro, there is a redirection of the form, or equivalent to
+.cblk
+(-> "out.txt")
+.cble
+then this redirection shall refer to the same stream
+that was established by
+.codn :output .
+Note also that in this example situation, the expression
+.cblk
+(-> "out.txt" :close)
+.cble
+has the effect of closing the
+.code :output
+stream.
+
 .meIP (:begin << form *)
 All
 .code :begin