Salza
-----

The salza home page is:

   http://www.xach.com/lisp/salza/

Visit that page for software updates and documentation.

Salza is an implementation of the DEFLATE compressed data format,
described in RFC 1951, and the ZLIB compressed data format, described
in RFC 1950. Currently, only output is supported.

Brief documentation is below; more is coming. See also
examples/png.lisp and examples/gzip.lisp for uses of the interfaces
for DEFLATE and ZLIB functionality.


ZLIB API Overview
-----------------

All functions are in the SALZA package, which has a nickname of ZLIB.

In general:

   - create a backing buffer; compressed data will be output to this
     buffer one or more bytes at a time

   - create a callback function; it will be called when the backing
     buffer is full and at the end of compression

   - create a zlib-stream object that references the backing buffer
     and the callback

   - use the zlib-write-sequence and zlib-write-string functions to
     write uncompressed data into the zlib-stream

   - call finish-zlib-stream to finish compression

The callback function is called with the zlib-stream object as its
only argument. Since the callback function may be called when the
zlib-stream buffer is not full, zlib-stream-position should be used to
determine the index after the last compressed byte in the buffer.

Here is the implementation of COMPRESS-STREAM from zlib.lisp:

   (defun compress-stream (input output)
     "Read input from the stream INPUT and write it in ZLIB format to the
   stream OUTPUT. Both streams must have element-types of '(unsigned-byte
   8)."
     (flet ((flush-stream (zlib-stream)
              (write-sequence (zlib-stream-buffer zlib-stream) output
                              :end (zlib-stream-position zlib-stream))
              (setf (zlib-stream-position zlib-stream) 0)))
       (let* ((input-buffer (make-array 8192 :element-type 'octet))
              (output-buffer (make-array 8192 :element-type 'octet))
              (zlib-stream (make-zlib-stream output-buffer
                                             :callback #'flush-stream)))
         (loop
          (let ((end (read-sequence input-buffer input)))
            (zlib-write-sequence input-buffer zlib-stream :end end)
            (when (zerop end)
              (finish-zlib-stream zlib-stream)
              (return)))))))

In this case, the local variable OUTPUT-BUFFER is the backing buffer
and the local function FLUSH-STREAM is the callback. Data is read
from the stream INPUT into the array INPUT-BUFFER and then written to
the zlib-stream with ZLIB-WRITE-SEQUENCE. When there is no more data
(READ-SEQUENCE returned zero), FINISH-ZLIB-STREAM finishes up
compression and may call the callback function one or more times in
the process.