Abstract
In theory Common Lisp allows binary streams to have arbitrary element types, but in practice - due to the way the underlying operating systems provide access to the file system - mosts Lisps nowadays will upgrade requested element types to(UNSIGNED-BYTE 8)
(henceforth called "octet") or multiples thereof. This library provides a Gray stream layer atop the implementation-provided binary streams which allows you to work with bytes of any size.The code comes with a BSD-style license so you can basically do with it whatever you want.
Download shortcut: http://weitz.de/files/odd-streams.tar.gz.
Before you install ODD-STREAMS you first need to install David Lichteblau's trivial-gray-streams library unless you already have it.
ODD-STREAMS comes with a system definition for ASDF so you can install the library with
(asdf:oos 'asdf:load-op :odd-streams)if you've unpacked it in a place where ASDF can find it. Installation via asdf-install should also be possible.
You can run a test suite which tests some (but not all) aspects of the library with
(asdf:oos 'asdf:test-op :odd-streams)This might take a while...
If you want to send patches, please read this first.
:DIRECTION :IO
, even if you don't intend to
read from the stream.
[Function]
make-odd-stream stream &key byte-size buffer-size => result
Creates and returns a new odd stream.stream
must be an open binary stream capable of reading/writing octets. The resulting odd stream is an input stream if and only ifstream
is an input stream. Likewise, it's an output stream if and only ifstream
is an output stream.byte-size
is the size of one stream element in bits, i.e. the stream will (try to) behave as if it had element type(UNSIGNED-BYTE BYTE-SIZE)
. The default value for this parameter is 1.
buffer-size
is the size of the stream's buffer in octets. It should usually be OK to just use the default (which depends on the byte size) for this parameter.
[Standard class]
odd-stream
Every stream returned byMAKE-ODD-STREAM
is of this type which is a subtype ofSTREAM
.
[Standard class]
odd-input-stream
An odd stream is of this type if its underlying stream is an input stream. This is a subtype ofODD-STREAM
.
[Standard class]
odd-output-stream
An odd stream is of this type if its underlying stream is an output stream. This is a subtype ofODD-STREAM
.
[Standard class]
odd-io-stream
An odd stream is of this type if it is both anODD-INPUT-STREAM
as well as anODD-OUTPUT-STREAM
.
[Readers]
odd-stream-byte-size odd-stream => byte-size
odd-stream-buffer-size odd-stream => buffer-size
These methods can be used to query an odd stream for its attributes.
[Macro]
with-open-odd-stream (var stream &key byte-size buffer-size) declaration* statement* => result
LikeWITH-OPEN-STREAM
, but for odd streams. SeeMAKE-ODD-STREAM
for the meaning of the parameters.
LikeWITH-OPEN-FILE
, but for odd streams. SeeMAKE-ODD-STREAM
for the meaning of the parameters.
[Generic function]
odd-file-length odd-stream => length
LikeFILE-LENGTH
, but using the odd stream'sbyte size
as its unit of measurement. This is an exported function as it can't be done with Gray streams.
[Condition]
odd-stream-condition
All conditions signalled by the library are of this type. This is a subtype ofCONDITION
.
[Error]
odd-stream-error
All errors signalled by the library are of this type. This is a subtype ofODD-STREAM-CONDITION
and ofSTREAM-ERROR
.
[Warning]
odd-stream-warning
All warnings signalled by the library are of this type. This is a subtype ofODD-STREAM-CONDITION
and ofWARNING
.
[Type]
octet
Just a shortcut for(UNSIGNED-BYTE 8)
.
This documentation was prepared with DOCUMENTATION-TEMPLATE.
$Header: /usr/local/cvsrep/odd-streams/doc/index.html,v 1.3 2007/12/31 01:16:50 edi Exp $