New convenience I/O functions for buffers.

* lisplib.c (getput_set_entries): New autoload entries for
file-get-buf, file-put-buf, file-append-buf, command-get-buf
and command-put-buf.

* share/txr/stdlib/getput.tl (sys:get-buf-common): New
function.
(file-get-buf, file-put-buf, file-append-buf, command-get-buf,
command-put-buf): New functions.

* txr.1: Documented.

3 files changed, 101 insertions, 0 deletions

diff --git a/lisplib.c b/lisplib.c
index 1782e671..3e437542 100644
--- a/lisplib.c
+++ b/lisplib.c
@@ -440,9 +440,11 @@ static val getput_set_entries(val dlt, val fun)
     lit("file-get"), lit("file-put"), lit("file-append"),
     lit("file-get-string"), lit("file-put-string"), lit("file-append-string"),
     lit("file-get-lines"), lit("file-put-lines"), lit("file-append-lines"),
+    lit("file-get-buf"), lit("file-put-buf"), lit("file-append-buf"),
     lit("command-get"), lit("command-put"),
     lit("command-get-string"), lit("command-put-string"),
     lit("command-get-lines"), lit("command-put-lines"),
+    lit("command-get-buf"), lit("command-put-buf"),
     nil
   };
   set_dlt_entries(dlt, name, fun);
diff --git a/share/txr/stdlib/getput.tl b/share/txr/stdlib/getput.tl
index b42f6da7..cb3e621e 100644
--- a/share/txr/stdlib/getput.tl
+++ b/share/txr/stdlib/getput.tl
@@ -24,6 +24,18 @@
 ;; OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 ;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+(defun sys:get-buf-common (s)
+  (let ((b (make-buf 4096))
+        (o 0))
+    (while t
+      (let ((p (fill-buf b o s)))
+        (when (< p (len b))
+          (buf-set-length b (if (plusp p) p o))
+          (return))
+        (buf-set-length b (+ p (len b)))
+        (set o p)))
+    b))
+
 (defun file-get (name)
   (with-stream (s (open-file name))
     (read s)))
@@ -59,6 +71,18 @@
   (with-stream (s (open-file name "a"))
     (put-lines lines s)))
 
+(defun file-get-buf (name)
+  (with-stream (s (open-file name "rb"))
+    (sys:get-buf-common s)))
+
+(defun file-put-buf (name buf)
+  (with-stream (s (open-file name "wb"))
+    (put-buf buf 0 s)))
+
+(defun file-append-buf (name buf)
+  (with-stream (s (open-file name "ab"))
+    (put-buf buf 0 s)))
+
 (defun command-get (cmd)
   (with-stream (s (open-command cmd))
     (read s)))
@@ -81,3 +105,11 @@
 (defun command-put-lines (cmd lines)
   (with-stream (s (open-command cmd "w"))
     (put-lines lines s)))
+
+(defun command-get-buf (cmd)
+  (with-stream (s (open-command cmd))
+    (sys:get-buf-common s)))
+
+(defun command-put-buf (cmd buf)
+  (with-stream (s (open-command cmd "w"))
+    (put-buf buf 0 s)))
diff --git a/txr.1 b/txr.1
index d10a8153..53b0836b 100644
--- a/txr.1
+++ b/txr.1
@@ -43814,6 +43814,10 @@ The functions in this group create a stream, perform an I/O operation
 on it, and ensure that it is closed, in one convenient operation. They
 operate on files or command streams.
 
+Several other functions in this category exist, which operate with buffers.
+They are documented in the Buffer Functions subsection under the
+FOREIGN FUNCTION INTERFACE section.
+
 .coNP Functions @, file-get @ file-get-string and @ file-get-lines
 .synb
 .mets (file-get << name )
@@ -59173,6 +59177,69 @@ in order to extract the return value of foreign function
 calls, and by the FFI callback mechanism to extract the
 arguments coming into a callback.
 
+.coNP Functions @ file-get-buf and @ command-get-buf
+.synb
+.mets (file-get-buf << name )
+.mets (command-get-buf << cmd )
+.syne
+.desc
+The
+.code file-get-buf
+function opens a text stream over the file indicated by the string argument
+.meta name
+for reading. The entire file is read and its contents are returned as a
+buffer object. The buffer's length corresponds to the number of bytes
+read from the file.
+
+The
+.code command-get
+function opens text stream over an input command pipe created for
+the command string
+.metn cmd ,
+as if by the
+.code open-command
+function.  It read bytes from the pipe until the indication that no more
+input is available. The bytes are returned aggregated into a buffer object.
+
+.coNP Functions @, file-put-buf @ file-append-buf and @ command-put-buf
+.synb
+.mets (file-put-buf < name << buf )
+.mets (file-append-buf < name << buf )
+.mets (command-put-buf < cmd << buf )
+.syne
+.desc
+The
+.code file-put-buf
+function opens a text stream over the file indicated by the string argument
+.metn name ,
+writes the contents of the buffer object
+.meta buf
+into the file, and then closes the file.  If the file doesn't exist, it is
+created.  If it exists, it is truncated to zero length and overwritten.
+
+The
+.code file-append-buf
+function is similar to
+.code file-put-buf
+except that if the file exists, it isn't overwritten. Rather, the buffer
+is appended to the file.
+
+The
+.code command-put-buf
+function opens an output text stream over an output command pipe created
+for the command specified in the string argument
+.metn cmd ,
+as if by the
+.code open-command
+function.
+It then writes the contents of buffer
+.meta buf
+into the stream and closes the stream.
+
+The return value of all three functions is that of the
+.code put-buf
+operation which is implicitly performed.
+
 .SS* Foreign Arrays
 
 Functions in this area provide a means for working with