buf: new buffer stream.

* buf.c (struct buf_strm): New struct type.
(buf_strm_mark, int buf_strm_put_byte_callback,
buf_strm_put_string, buf_strm_put_char, buf_strm_put_byte,
buf_strm_get_byte_callback, buf_strm_get_char,
buf_strm_get_byte, buf_strm_unget_char, buf_strm_unget_byte,
buf_strm_seek, buf_strm_truncate, buf_strm_get_prop,
buf_strm_set_prop, buf_strm_get_error,
buf_strm_get_error_str): New static functions.
(buf_strm_ops): New static struct.
(buf_strm): New static function.
(make_buf_stream, get_buf_from_stream): New functions.
(buf_init): Register new intrinsic functiions make-buf-stream
and get-buf-from-stream.
Call fill_stream_ops on new buf_strm_ops to fill
default operations in place of function pointers
that have been left null.

* buf.h (make_buf_stream, get_buf_from_stream): Declared.

* lisplib.c (with_stream_set_entries): Add with-out-buf-stream
and with-in-buf-stream to auto-load symbols for with-stream.tl
module.

* share/txr/stdlib/with-stream.tl (with-out-buf-stream,
with-in-buf-stream): New macros.

* txr.1: New section about buffer streams.

1 files changed, 120 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index d3ea01b9..ee6072f6 100644
--- a/txr.1
+++ b/txr.1
@@ -54697,6 +54697,126 @@ any bytes are read, then an exception is thrown.
 If an end-of-file condition occurs before any bytes are read, then zero
 is returned.
 
+.SS* Buffer streams
+A stream type exists which allows
+.code buf
+objects to be manipulated through the stream interface.
+A buffer stream is created using the
+.code make-buf-stream
+function, which can either attach the stream to an existing buffer,
+or create a new buffer that can later be retrieved from the stream
+using
+.codn get-buf-from-stream .
+
+Operations on the buffer stream treat the underlying buffer much like if it
+were a memory-based file. Unless the underlying buffer is a "borrowed buffer"
+referencing the storage belonging to another object
+(such as the buffer object produced by the
+.code buf-d
+FFI type's get semantics) the stream operations can change the buffer's size.
+Seeking beyond the end of the buffer an then writing one or more bytes
+extends the buffer's length, filling the newly allocated area with zero bytes.
+The
+.code truncate-stream
+function is supported also.
+Buffer streams also support the
+.code :byte-oriented
+property.
+
+Macros
+.code with-out-buf-stream
+and
+.code with-in-buf-stream
+are provided to simplify the steps involved in using buffer streams
+in some common scenarios. Note that in spite of the naming of these
+macros there is only one buffer stream type, which supports bidirectional I/O.
+
+.coNP Function @ make-buf-stream
+.synb
+.mets (make-buf-stream <> [ buf ])
+.syne
+.desc
+The
+.code make-buf-stream
+function return a new buffer stream. If the
+.meta buf
+argument is supplied, it must be a
+.code buf
+object. The stream is then associated with this object.
+If the argument is omitted, a buffer of length zero is created and associated
+with the stream.
+
+.coNP Function @ get-buf-from-stream
+.synb
+.mets (get-buf-from-stream << buf-stream )
+.syne
+.desc
+The
+.code get-buf-from-stream
+returns the buffer object associated with
+.meta buf-stream
+which must be a buffer stream.
+
+.coNP Macros @ with-out-buf-stream and @ with-in-buf-stream
+.synb
+.mets (with-out-buf-stream >> ( var <> [ buf-expr ])
+.mets \ \  << body-form *)
+.mets (with-in-buf-stream >> ( var << buf-expr )
+.mets \ \  << body-form *)
+.syne
+.desc
+The
+.code with-out-buf-stream
+and
+.code with-in-buf-stream
+macros both bind variable
+.meta var
+to an implicitly created buffer stream, and evaluate zero or more
+.metn body-form -s
+in the environment where the variable is visible.
+
+The
+.meta buf-expr
+argument, which may be omitted in the use of the
+.code with-out-buf-stream
+macro, must be an expression which evaluates to a
+.code buf
+object.
+
+The
+.meta var
+argument must be a symbol suitable for naming a variable.
+
+The implicitly allocated buffer stream is connected
+to the buffer specified by
+.meta buf-expr
+or, when
+.meta buf-expr
+is omitted, to a newly allocated buffer.
+
+The code generated by the
+.code with-out-buf-stream
+macro, if it terminates normally, yields the buffer object
+as its result value.
+
+The
+.code with-in-buf-stream
+returns the value of the last
+.metn body-form ,
+or else
+.code nil
+if no forms are specified.
+
+.TP* Examples:
+.cblk
+  (with-out-buf-stream (*stdout* (make-buf 24))
+    (put-string "Hello, world!"))
+  -> #b'48656c6c6f2c2077 6f726c6421000000 0000000000000000'
+
+  (with-out-buf-stream (*stdout*) (put-string "Hello, world!"))
+  -> #b'48656c6c6f2c2077 6f726c6421'
+.cble
+
 .coSS The @ cptr type
 
 Objects of type