/usr/share/doc/cl-chipz/index.html is in cl-chipz 20160318-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<HTML><HEAD><TITLE>Chipz</TITLE><LINK TYPE="text/css" TITLE="default" REL="stylesheet" MEDIA="screen" HREF="style.css" /></HEAD><BODY><H1>Chipz</H1><P>Chipz is a library for decompressing DEFLATE and BZIP2 data.
DEFLATE data, defined in <A HREF="http://www.ietf.org/rfc/rfc1951.txt">RFC1951</A>, forms the core of popular compression formats such as
zlib (<A HREF="http://www.ietf.org/rfc/rfc1950.txt">RFC 1950</A>) and
gzip (<A HREF="http://www.ietf.org/rfc/rfc1952.txt">RFC 1952</A>). As
such, Chipz also provides for decompressing data in those
formats as well. BZIP2 is the format used by the popular compression
tool <A HREF="http://www.bzip.org/">bzip2</A>.</P><P>Chipz is the reading complement to <A HREF="http://www.xach.com/salza2/">Salza</A>.</P><H2>Installation</H2><P>Chipz can be downloaded at <A HREF="http://www.method-combination.net/lisp/files/chipz.tar.gz">http://www.method-combination.net/lisp/files/chipz.tar.gz</A>. The latest version is 0.8.</P><P>It comes with an ASDF system definition, so <TT>(ASDF:OOS
'ASDF:LOAD-OP :CHIPZ)</TT> should be all that you need to get started.</P><H2>License</H2><P>Chipz is released under a MIT-like license; you can do pretty
much anything you want to with the code except claim that you wrote
it.</P><H2>Using the library</H2><P>The main function of the library is <TT>decompress</TT>:</P><DIV CLASS="lisp-symbol"><A NAME="decompress"></A><TT><STRONG>decompress</STRONG> <EM>output</EM> <EM>state</EM> <EM>input</EM> <EM><TT>&key</TT></EM> <EM><TT>&allow-other-keys</TT></EM> => <EM>output</EM></TT><BR /></DIV><P>Five distinct use cases are covered by this single function:</P><UL><LI>Decompressing from an octet vector to a fresh octet vector;</LI><LI>Decompressing from a stream to a fresh octet vector;</LI><LI>Decompressing from an octet vector to a user-specified octet vector;</LI><LI>Decompressing from an octet vector to a stream;</LI><LI>Decompressing from a stream to a stream;</LI></UL><TABLE CLASS="note"><TR><TD CLASS="title">Note</TD><TD CLASS="content">Chipz does not provide for decompressing data from a stream
to a user-specified buffer, as the buffer management involved cannot be
done automatically by the library--the application must be involved in
this case.</TD></TR></TABLE><H3><A NAME="one-shot"></A>One-shot decompression</H3><P>The first and second use cases above are intended to be convenient
"one-shot" decompression methods. Therefore, although the description
of the following methods attached to this generic function have an <TT>decompression-state</TT> parameter, as returned by <A HREF="#make-dstate" STYLE="symbol">make-dstate</A>,
respectively, the usual way to use them will be to provide a <TT>format</TT> argument. This <TT>format</TT> argument should be one of:</P><UL><LI><TT>chipz:bzip2</TT> for decompressing data in the bzip2 format;</LI><LI><TT>chipz:gzip</TT> for decompressing data in the gzip format;</LI><LI><TT>chipz:zlib</TT> for decompressing data in the zlib format;</LI><LI><TT>chipz:deflate</TT> for decompressing data in the deflate format.</LI></UL><P>The <TT>format</TT> argument can also be a keyword, such as <TT>:gzip</TT>, for backwards compatibility. Using symbols in the <TT>CHIPZ</TT> package is preferred, however.</P><P>Most applications will use <TT>chipz:gzip</TT> or <TT>chipz:bzip2</TT>, a
few applications will use <TT>chipz:zlib</TT>, and uses of <TT>chipz:deflate</TT> will probably be few and far between.</P><P>All the method signatures described below also accept a <TT>format</TT> argument in lieu of an <TT>decompression-state</TT> argument.</P><P>The signatures of the first two methods are as follows.</P><DIV CLASS="lisp-symbol"><A NAME="decompress"></A><TT><STRONG>decompress</STRONG> <EM>(output null)</EM> <EM>(state decompression-state)</EM> <EM>(input vector)</EM> <EM><TT>&key</TT></EM> <EM>(input-start 0)</EM> <EM>input-end</EM> <EM>buffer-size</EM> => <EM>output</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="decompress"></A><TT><STRONG>decompress</STRONG> <EM>(output null)</EM> <EM>(state decompression-state)</EM> <EM>(input stream)</EM> <EM><TT>&key</TT></EM> <EM>buffer-size</EM> => <EM>output</EM></TT><BR /></DIV><P>A simple function to retrieve the contents of a gzip-compressed
file, then, might be:</P><PRE>(defun gzip-contents (pathname)
(with-open-file (stream pathname :direction :input
:element-type '(unsigned-byte 8))
(chipz:decompress nil 'chipz:gzip stream)))</PRE><P>These one-shot methods also support a <TT>:buffer-size</TT> argument
as a hint of the size of decompressed data. The library uses this to
pre-allocate the output buffer to the hinted size. Therefore, if you
know the size of the decompressed data or have a good estimate, fewer
allocations will be done, leading to slightly better performance. If <TT>:buffer-size</TT> is not provided or proves to be too small, the library
will of course grow the output buffer as necessary.</P><H3>Decompressing to a vector</H3><P>An alternate way to deal with compressed data is to read in a
buffer's worth of data, decompress the buffer, and then deal with any
remaining input and the produced output, looping to read and process
more data as appropriate. This scheme is the third use case
described above and is handled in zlib with the <TT>inflate</TT>
function. In Chipz, it is just another method of <TT>decompress</TT>.</P><DIV CLASS="lisp-symbol"><A NAME="decompress"></A><TT><STRONG>decompress</STRONG> <EM>(output vector)</EM> <EM>(state decompression-state)</EM> <EM>(input vector)</EM> <EM><TT>&key</TT></EM> <EM>(input-start 0)</EM> <EM>input-end</EM> <EM>(output-start 0)</EM> <EM>output-end</EM> => <EM>n-bytes-consumed</EM>, <EM>n-bytes-produced</EM></TT><BR /></DIV><P>This method decompresses the data from <EM>input</EM> between <EM>input-start</EM> and <EM>input-end</EM> and place the uncompressed data in <EM>output</EM>, limited by <EM>output-start</EM> and <EM>output-end</EM>. Please
note that it is possible to consume some or all of the input without
producing any output and to produce some or all of the output without
consuming any input.</P><P>As above, you can use a <TT>format</TT> argument instead of an <TT>decompression-state</TT>. You will usually not want to do this unless
you know exactly how large the decompressed data is going to be;
otherwise, you will only decompress a portion of the data and any
intermediate state required to decompress the remainder of the data will
be thrown away.</P><H3>Decompressing to a stream</H3><P>Finally, <TT>decompress</TT> can also be used to write the
decompressed data directly to a stream, enabling a poor man's gunzip
function:</P><PRE>(defun gunzip (gzip-filename output-filename)
(with-open-file (gzstream gzip-filename :direction :input
:element-type '(unsigned-byte 8))
(with-open-file (stream output-filename :direction :output
:element-type '(unsigned-byte 8)
:if-exists :supersede)
(chipz:decompress stream 'chipz:gzip gzstream)
output-filename)))</PRE><P>The relevant methods in this case are:</P><DIV CLASS="lisp-symbol"><A NAME="decompress"></A><TT><STRONG>decompress</STRONG> <EM>(output stream)</EM> <EM>(state decompression-state)</EM> <EM>(input vector)</EM> <EM><TT>&key</TT></EM> <EM>(input-start 0)</EM> <EM>input-end</EM> => <EM>stream</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="decompress"></A><TT><STRONG>decompress</STRONG> <EM>(output stream)</EM> <EM>(state decompression-state)</EM> <EM>(input stream)</EM> => <EM>stream</EM></TT><BR /></DIV><P>Both return the output stream.</P><H3>Creating <TT>decompression-state</TT> objects</H3><P>The core data structure of Chipz is a <TT>decompression-state</TT>, which stores the internal state of an ongoing
decompression process. You create a <TT>decompression-state</TT> with <A HREF="#make-dstate" STYLE="symbol">make-dstate</A>.</P><DIV CLASS="lisp-symbol"><A NAME="make-dstate"></A><TT><STRONG>make-dstate</STRONG> <EM>format</EM> => <EM>dstate</EM></TT><BR /></DIV><P>Return an <TT>decompression-state</TT> object suitable for
uncompressing data in <EM>data-format</EM>. <EM>data-format</EM> should be:</P><UL><LI><TT>chipz:bzip2</TT> for decompressing data in the bzip2 format;</LI><LI><TT>chipz:gzip</TT> for decompressing data in the gzip format;</LI><LI><TT>chipz:zlib</TT> for decompressing data in the zlib format;</LI><LI><TT>chipz:deflate</TT> for decompressing data in the deflate format.</LI></UL><P>As with <A HREF="#decompress" STYLE="symbol">decompress</A>, you can use keywords instead, but doing so
is deprecated.</P><P>Prior to adding bzip2 support, Chipz supported only
deflate-based formats. <A HREF="#make-inflate-state" STYLE="symbol">make-inflate-state</A> was the primary
interface then; it is now deprecated, but kept around for backwards
compatibility.</P><DIV CLASS="lisp-symbol"><A NAME="make-inflate-state"></A><TT><STRONG>make-inflate-state</STRONG> <EM>format</EM> => <EM>inflate-state</EM></TT><BR /></DIV><P><A HREF="#make-inflate-state" STYLE="symbol">make-inflate-state</A> supports the same <EM>data-format</EM> arguments
as <A HREF="#make-dstate" STYLE="symbol">make-dstate</A> does, with the obvious exception of <EM>chipz:bzip2</EM>. The <TT>inflate-state</TT> object returned is a <TT>decompression-state</TT>, so it can be passed to <A HREF="#decompress" STYLE="symbol">decompress</A> and <A HREF="#finish-dstate" STYLE="symbol">finish-dstate</A>.</P><P>Once you are done with a <TT>decompression-state</TT> object, you must
call <A HREF="#finish-dstate" STYLE="symbol">finish-dstate</A> on it. <A HREF="#finish-dstate" STYLE="symbol">finish-dstate</A> checks that the
given <EM>state</EM> decompressed all the data in a given stream. It does
not dispose of any resources associated with <EM>state</EM>; it is meant
purely as an error-checking construct. Therefore, it is inappropriate
to call from, say, the cleanup forms of <TT>UNWIND-PROTECT</TT>. The
cleanup forms may be run when an error is thrown during decompression
and of course the stream will only be partially decompressed at that
point.</P><DIV CLASS="lisp-symbol"><A NAME="finish-dstate"></A><TT><STRONG>finish-dstate</STRONG> <EM>state</EM> => <EM>t</EM></TT><BR /></DIV><P><A HREF="#finish-inflate-state" STYLE="symbol">finish-inflate-state</A> does the same thing, but only for <TT>inflate-state</TT>. Its use, like that of <A HREF="#make-inflate-state" STYLE="symbol">make-inflate-state</A> is
deprecated.</P><DIV CLASS="lisp-symbol"><A NAME="finish-inflate-state"></A><TT><STRONG>finish-inflate-state</STRONG> <EM>state</EM> => <EM>t</EM></TT><BR /></DIV><H2>Gray streams</H2><P>Chipz includes support for creating Gray streams to wrap
streams containing compressed data and read the uncompressed data from
those streams. SBCL, Allegro, Lispworks, CMUCL, and OpenMCL are
supported at this time.</P><DIV CLASS="lisp-symbol"><A NAME="make-decompressing-stream"></A><TT><STRONG>make-decompressing-stream</STRONG> <EM>format</EM> <EM>stream</EM> => <EM>decompressing-stream</EM></TT><BR /></DIV><P>Return a stream that provides transparent decompression of the data
from <EM>stream</EM> in <EM>format</EM>. That is, <TT>read-byte</TT> and <TT>read-sequence</TT> will decompress the data read from <EM>stream</EM> and
return portions of the decompressed data as requested. <EM>format</EM> is
as in the <A HREF="#one-shot">one-shot decompression
methods</A>.</P><H2>Conditions</H2><DIV CLASS="lisp-symbol"><A NAME="chipz-error"></A><TT><STRONG>chipz-error</STRONG></TT><BR /></DIV><P>All errors signaled by Chipz are of this type.</P><DIV CLASS="lisp-symbol"><A NAME="invalid-format-error"></A><TT><STRONG>invalid-format-error</STRONG></TT><BR /></DIV><P>This error is signaled when the <EM>format</EM> argument to <A HREF="#decompress" STYLE="symbol">decompress</A> or <A HREF="#make-dstate" STYLE="symbol">make-dstate</A> is not one of the symbols specified
for <A HREF="#make-dstate" STYLE="symbol">make-dstate</A>. This error is also signaled in <A HREF="#make-inflate-state" STYLE="symbol">make-inflate-state</A> if the <EM>format</EM> argument is not valid for that
function.</P><DIV CLASS="lisp-symbol"><A NAME="decompression-error"></A><TT><STRONG>decompression-error</STRONG></TT><BR /></DIV><P>All errors signaled during decompression are of this type.</P><DIV CLASS="lisp-symbol"><A NAME="invalid-checksum-error"></A><TT><STRONG>invalid-checksum-error</STRONG></TT><BR /></DIV><P>The zlib, gzip, and bzip2 formats all contain checksums to verify
the integrity of the uncompressed data; this error is signaled when the
stored checksum is found to be inconsistent with the checksum computed
by Chipz. It indicates that the compressed data has probably
been corrupted in some fashion (or there is an error in Chipz).</P><DIV CLASS="lisp-symbol"><A NAME="premature-end-of-stream"></A><TT><STRONG>premature-end-of-stream</STRONG></TT><BR /></DIV><P>This error is signaled when <A HREF="#finish-dstate" STYLE="symbol">finish-dstate</A> is
called on an <TT>decompression-state</TT> that has not finished processing
an entire decompressed data stream.</P><DIV CLASS="lisp-symbol"><A NAME="inflate-error"></A><TT><STRONG>inflate-error</STRONG></TT><BR /></DIV><P>All errors signaled while decompressing deflate-based formats are
of this type.</P><DIV CLASS="lisp-symbol"><A NAME="invalid-zlib-header-error"></A><TT><STRONG>invalid-zlib-header-error</STRONG></TT><BR /></DIV><P>This error is signaled when an invalid zlib header is read.</P><DIV CLASS="lisp-symbol"><A NAME="invalid-gzip-header-error"></A><TT><STRONG>invalid-gzip-header-error</STRONG></TT><BR /></DIV><P>This error is signaled when an invalid gzip header is read.</P><DIV CLASS="lisp-symbol"><A NAME="reserved-block-type-error"></A><TT><STRONG>reserved-block-type-error</STRONG></TT><BR /></DIV><P>This error is signaled when a deflate block is read whose
type is 3. This type is reserved for future expansion and should
not be found in the wild.</P><DIV CLASS="lisp-symbol"><A NAME="invalid-stored-block-length-error"></A><TT><STRONG>invalid-stored-block-length-error</STRONG></TT><BR /></DIV><P>This error is signaled when the length of a deflate stored
block is found to be invalid.</P><DIV CLASS="lisp-symbol"><A NAME="bzip2-error"></A><TT><STRONG>bzip2-error</STRONG></TT><BR /></DIV><P>All errors signaled while decompressing bzip2-based formats are of
this type.</P><DIV CLASS="lisp-symbol"><A NAME="invalid-bzip2-data"></A><TT><STRONG>invalid-bzip2-data</STRONG></TT><BR /></DIV><P>This error is signaled when the compressed bzip2 data is found to
be corrupt in some way that prevents further decompression.</P></BODY></HTML>
|