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

ODD-STREAMS together with this documentation can be downloaded from http://weitz.de/files/odd-streams.tar.gz. The current version is 0.1.2.

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...
 

Support and mailing lists

There is no dedicated mailing list for ODD-STREAMS, so for questions, bug reports, feature requests, improvements, or patches please use the flexi-streams-devel mailing list. If you want to be notified about future releases, subscribe to the flexi-streams-announce mailing list. These mailing lists were made available thanks to the services of common-lisp.net.

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

Limitations


 

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.4 2013-01-11 17:14:37 edi Exp $

BACK TO MY HOMEPAGE