ODD-STREAMS - Lisp binary streams with "odd" byte sizes

 

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.

Contents

1. Download and installation
2. Support and mailing lists
3. Limitations
4. The ODD-STREAMS dictionary
   1. make-odd-stream
   2. odd-stream
   3. odd-input-stream
   4. odd-output-stream
   5. odd-io-stream
   6. odd-stream-byte-size
   7. odd-stream-buffer-size
   8. with-open-odd-stream
   9. with-open-odd-file
   10. odd-file-length
   11. odd-stream-condition
   12. odd-stream-error
   13. odd-stream-warning
   14. octet
5. Acknowledgements

Download and installation

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)

You can run a test suite which tests some (but not all) aspects of the library with

(asdf:oos 'asdf:test-op :odd-streams)

Support and mailing lists

If you want to send patches, please read this first.
 

Limitations

• The code is expected to be portable to most Lisps that have Gray streams, but so far it has only been used and tested with LispWorks.
• The library was originally written for and tested with file streams. With other ones (like, say, socket streams) you are likely to run into problems.
• If you're opening an odd stream for output to overwrite parts of an existing file in place, you can potentially ruin it due to "overlapping bits". The workaround is to use :DIRECTION :IO, even if you don't intend to read from the stream.
• Right now, this is simply a convenience layer and dog-slow. You have been warned...

The ODD-STREAMS dictionary

[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 if stream is an input stream. Likewise, it's an output stream if and only if stream 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 by MAKE-ODD-STREAM is of this type which is a subtype of STREAM.

[Standard class]
odd-input-stream

An odd stream is of this type if its underlying stream is an input stream. This is a subtype of ODD-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 of ODD-STREAM.

[Standard class]
odd-io-stream

An odd stream is of this type if it is both an ODD-INPUT-STREAM as well as an ODD-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

Like WITH-OPEN-STREAM, but for odd streams. See MAKE-ODD-STREAM for the meaning of the parameters.

[Macro]
with-open-odd-file (stream filespec &key byte-size buffer-size direction if-exists if-does-not-exist) declaration* statement* => result

Like WITH-OPEN-FILE, but for odd streams. See MAKE-ODD-STREAM for the meaning of the parameters.

[Generic function]
odd-file-length odd-stream => length

Like FILE-LENGTH, but using the odd stream's byte 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 of CONDITION.

[Error]
odd-stream-error

All errors signalled by the library are of this type. This is a subtype of ODD-STREAM-CONDITION and of STREAM-ERROR.

[Warning]
odd-stream-warning

All warnings signalled by the library are of this type. This is a subtype of ODD-STREAM-CONDITION and of WARNING.

[Type]
octet

Just a shortcut for (UNSIGNED-BYTE 8).

Acknowledgements

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 $

BACK TO MY HOMEPAGE