diff options
Diffstat (limited to 'txr.1')
| -rw-r--r-- | txr.1 | 120 |
1 files changed, 120 insertions, 0 deletions
@@ -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 |