BIT-IO

----------------------------------------------------------------
_BIT-IO_
----------------------------------------------------------------

(require (planet "bit-io.scm" ("soegaard" "bit-io.plt")))

This library provides operations for reading and writing bits
from and to files. It started as a PLT port of Oleg's bit-reader
   <http://okmij.org/ftp/Scheme/binary-io.html#bit-reader>
then a bit-writer was added, and finally bit-ports were 
introduced.


EXAMPLE
-------

> (require (planet "bit-io.scm" ("soegaard" "bit-io.plt")))

> (with-output-to-bit-file "tmp"
    (lambda ()
      (do ([i 1 (+ i 1)]) [(= i 9) 'done]
        (write-bits i i)))
    'replace)
done

> (with-input-from-bit-file "tmp"
    (lambda ()
      (do ([i 1 (+ i 1)]
           [ns '() (cons (read-bits i) ns)])
        [(= i 9) ns])))
(8 7 6 5 4 3 2 1)



_BIT PORTS_
-----------

Bit ports represent input and output devices. An input bit port is
a Scheme object that can deliver bits upon command, while an 
output bit port is a Scheme object that can accept bits.

> (call-with-input-bit-file path proc [option ...])
> (call-with-output-bit-file path proc [option ...])

Path should be a path to a file, and proc should be a procedure 
that accepts one argument. For call-with-input-bit-port, the
file should already exist; for call-with-output-file, the
effect is unspecified if the file already exists. These procedures
call proc with one argument: the port obtained by opening the named
file for input or output. If the file cannot be opened, an error is
signalled. If proc returns, then the port is closed automatically and
the value(s) yielded by the proc is(are) returned. If proc does not
return, them the port will not be closed automatically unless it is
possible to prove that the port will never again be used for a read
or write operation.

> (input-bit-port? obj) 
> (output-bit-port? obj) 

Returns #t if obj is an input bit port or output bit port respectively, 
otherwise returns #f.

> (current-input-port) 
> (current-output-port) 

Returns the current default bit input or output bit port.

> (with-input-from-bit-file path thunk [option ...]) 
> (with-output-to-bit-file path thunk [option ...]) 

Path should be a path to a file, and thunk should be a procedure
of no arguments. Fow with-input-from-bit-file, the file should
already exist; for with-output-to-file, the effect is unspecified
if the file already exists. The file is opened for bit input or
bit output, an input or output bit port is amde the default value
returned by current-input-bit-port or current-output-bit-port (and
is used by (read-bits, write-bits), and the thunk is called with
no parameters. When the thunk returns the port is closed and
the previous default is restored. With-input-from-bit-file and
with-output-to-file return(s) the value(s) yielded by thunk. If
an escape procedure is used to escape from the continuation of
these procedures, their behaviour is implementation dependent.

> (open-input-file filename [option ...]) 

Takes a string naming an existing file and returns an input bit port
capable of delivering bits from the file. If the file cannont be opened,
an error is signalled.

>  (open-output-file filename [option ...]) 

Takes a string naming an output file to be created and returns an output
bit port capable of writing bits to a new file by that name. If the
file cannot be opened, an error is signalled. If a file with the given
name already exists, the effect is unspecified.

> (close-input-bit-port bit-port) 
> (close-output-bit-port bit-port) 

Closes the file associated with bit-port, rendering the port incapable 
of delivering or accepting bits. These routine have no effect if the 
file has already been closed. The value returned is unspecified.

> (read-bits n) 
> (read-bits n bit-port) 

Returns the next n bits (as a single integer) available from the input 
bit port, updating the port to point to the following bits. If no more 
bits are available, an end of file object is returned. Bit-port may be 
omitted, in which case it defaults to the value returned by 
current-input-bit-port.

> (write-bits n bits) 
> (write-bits n bits bit-port) 

Bits should be an integer greater than or equal to zero. Writes the
n lower bits from bits to bit-port. If bit-port is omitted, the
bits are written to the bit-port returned by current-output-bit-port.

> (flush-bits)
> (flush-bits output-bit-port)

Flushes any bits in the cache by appending zeros until a whole byte
can by output.

> (bit-file-position bit-port)
> (bit-file-position bit-port n)

When called with one argument the bit-port's position is returned.
The position of an input-bit-port is the number of bits read so far;
for an output-bit-port is the number of written bits. If a second
argument is present the position is set to n [Restriction: the 
bit-port must in this case be an input-bit-port]


Keywords: _bit_ _port_ _io_ _file_ _bits_