Added HTMl documentation.
Fri Sep 5 18:34:09 PDT 2008 mail@chaitanyagupta.com
* Added HTMl documentation.
diff -rN -u old-cl-bzip2/bzip2.lisp new-cl-bzip2/bzip2.lisp
--- old-cl-bzip2/bzip2.lisp 2014-07-30 12:15:58.000000000 -0700
+++ new-cl-bzip2/bzip2.lisp 2014-07-30 12:15:58.000000000 -0700
@@ -125,7 +125,7 @@
(gethash (bz-error-code c) *bz-return-codes*)
(bz-error-code c))))
(:documentation "The default condition type for any BZIP2
- compression/decompression related errors."))
+ compression/decompression related error."))
(defun bz-error (code cfun)
(error 'bz-error
@@ -341,9 +341,10 @@
"Compresses data from IN to OUT. IN or OUT can either be a binary
stream or a pathname.
-BLOCK-SIZE-100K, VERBOSITY and WORK-FACTOR correspond to the
- parameters `blockSize100k', `verbosity' and `workFactor',
- respectively, for the libbzip2 function `BZ2_bzCompressInit'.
+BLOCK-SIZE-100K (default 9), VERBOSITY (default 0) and
+ WORK-FACTOR (default 30) correspond to the parameters
+ `blockSize100k', `verbosity' and `workFactor', respectively, for
+ the libbzip2 function `BZ2_bzCompressInit'.
From the bzip2 manual:
@@ -430,13 +431,14 @@
"Decompresses data from IN to OUT. IN or OUT can either be a binary
stream or a pathname.
-VERBOSITY and SMALLP correspond to the parameters `verbosity' and
- `workFactor', respectively, for the libbzip2 function
- `BZ2_bzDecompressInit'.
+VERBOSITY and SMALLP (default NIL) correspond to the parameters
+ `verbosity' and `small', respectively, for the libbzip2
+ function `BZ2_bzDecompressInit'.
For the meaning of VERBOSITY, see the documentation for
-COMPRESS. For SMALLP, here's the corresponding entry from
-the bzip2 manual:
+COMPRESS. A non-NIL value for SMALLP corresponds to a non-zero
+value for the parameter `small'. Here's what the bzip2 manual
+says about `small':
If `small' is nonzero, the library will use an alternative
decompression algorithm which uses less memory but at the cost of
diff -rN -u old-cl-bzip2/doc/index.html new-cl-bzip2/doc/index.html
--- old-cl-bzip2/doc/index.html 1969-12-31 16:00:00.000000000 -0800
+++ new-cl-bzip2/doc/index.html 2014-07-30 12:15:58.000000000 -0700
@@ -0,0 +1,161 @@
+<html>
+ <head>
+ <title>CL-BZIP2</title>
+ <link rel="stylesheet" type="text/css" href="style.css" />
+ </head>
+ <body>
+ <h2>CL-BZIP2 &#8212; BZIP2 compression/decompression for Common Lisp</h2>
+
+ <h3 id="introduction">Introduction</h3>
+
+ <p>cl-bzip2 provides <a href="http://common-lisp.net/project/cffi/"><span class="caps">CFFI</span></a> bindings for libbzip2 &#8212; the <a href="http://www.bzip.org/">bzip2</a> compression/decompression library.</p>
+
+ <h3 id="contents">Contents</h3>
+
+ <ol>
+ <li><a href="#download">Download and installation</a></li>
+ <li><a href="#support">Support and mailing lists</a></li>
+ <li><a href="#examples">Examples</a>
+ <ol>
+ <li><a href="#compression">Compression</a></li>
+ <li><a href="#decompression">Decompression</a></li>
+ <li><a href="#vectors">Working with vectors</a></li>
+ </ol></li>
+ <li><a href="#dictionary">The cl-bzip2 dictionary</a></li>
+ <li><a href="#limit">Limitations</a></li>
+ <li><a href="#acknowledgements">Acknowledgements</a></li>
+ </ol>
+
+ <h3 id="download">Download and installation</h3>
+
+ <p>Current release: <a href="http://common-lisp.net/project/cl-bzip2/cl-bzip2-0.1.0.tar.gz">Version 0.1.0</a></p>
+
+ <p>You can also <a href="http://common-lisp.net/cgi-bin/darcsweb/darcsweb.cgi?r=cl-bzip2-cl-bzip2;a=summary">browse the darcs repository</a> or get yourself a copy using darcs get:</p>
+
+<pre>
+darcs get http://common-lisp.net/project/cl-bzip2/darcs/cl-bzip2
+</pre>
+
+ <p>cl-bzip2 has a couple of dependencies:</p>
+
+ <ol>
+ <li><a href="http://common-lisp.net/project/cffi/"><span class="caps">CFFI</span></a> &#8212; the Common Foreign Function Interface, which provides C bindings for</li>
+ <li><a href="http://www.bzip.org/downloads.html">libbzip2</a> &#8212; The C library for compressing and decompressing data in the bzip2 format. Make sure the shared object library (libbz2.so/libbz2.dylib) is installed on your machine. The bzip2 manual can be found <a href="http://www.bzip.org/1.0.5/bzip2-manual-1.0.5.html">here</a>.</li>
+ </ol>
+
+ <p>To compile and load cl-bzip2, you can either use <span class="caps">ASDF</span>, or simply evaluate <code>(load (compile-file &#34;bzip2.lisp&#34;))</code> while in the cl-bzip2 source directory.</p>
+
+ <h3 id="support">Support and mailing lists</h3>
+
+ <p>Send questions, bug reports, patches, feature requests, etc. to <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/cl-bzip2-devel">cl-bzip2-devel</a>. Release announcements are made on <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/cl-bzip2-announce">cl-bzip2-announce</a>.</p>
+
+ <h3 id="examples">Examples</h3>
+
+ <h4 id="compression">Compression</h4>
+
+ <p>Use <span class="caps">COMPRESS</span> to compress data from a stream/pathname to another stream/pathname. Note that stream should be a binary stream. <span class="caps">COMPRESS</span> will not work with string streams i.e. a stream supplied by <span class="caps">WITH</span>-<span class="caps">INPUT</span>-<span class="caps">FROM</span>-<span class="caps">STRING</span> or <span class="caps">WITH</span>-<span class="caps">OUTPUT</span>-TO-<span class="caps">STRING</span> will most likely not work at all.</p>
+
+<pre><code>
+;;; Compression usage
+
+;;; No values are returned if execution was successful
+;;; Using pathnames
+CL-USER&#62; (bzip2:compress #p&#34;test.txt&#34; #p&#34;test.txt.bz2&#34;)
+; No value
+
+;;; Using binary streams
+CL-USER&#62; (with-open-file (in &#34;test.txt&#34; :direction :input :element-type &#39;(unsigned-byte 8))
+ (with-open-file (out &#34;test.txt.bz2&#34; :direction :output :element-type &#39;(unsigned-byte 8))
+ (bzip2:compress in out)))
+; No value
+
+;;; Mixing stream and pathname
+CL-USER&#62; (with-open-file (in &#34;test.txt&#34; :direction :input :element-type &#39;(unsigned-byte 8))
+ (bzip2:compress in #p&#34;test.txt.bz2&#34;))
+; No value
+</code></pre>
+
+ <h4 id="decompression">Decompression</h4>
+
+ <p>Use <span class="caps">DECOMPRESS</span> to decompress data from a stream/pathname to another stream/pathname. As with <span class="caps">COMPRESS</span>, stream should be a binary stream.</p>
+
+<pre><code>
+;;; Decompression usage is similar to that for compression
+
+;;; Using pathnames
+CL-USER&#62; (bzip2:decompress #p&#34;test.txt.bz2&#34; #p&#34;test.txt&#34;)
+; No value
+
+;;; Using binaray streams
+CL-USER&#62; (with-open-file (in &#34;test.txt.bz2&#34; :direction :input :element-type &#39;(unsigned-byte 8))
+ (with-open-file (out &#34;test.txt&#34; :direction :output :element-type &#39;(unsigned-byte 8))
+ (bzip2:decompress in out)))
+; No value
+</code></pre>
+
+ <h4 id="vectors">Working with vectors</h4>
+
+ <p>Compression/decompression of vectors can easily be done with in-memory binary streams by using, for example, <a href="http://weitz.de/flexi-streams/"><span class="caps">FLEXI</span>-<span class="caps">STREAMS</span></a>.</p>
+
+<pre><code>
+CL-USER&#62; (defvar *vec* #(87 101 32 108 111 118 101 32 98 104 97 107 99 104 111 100 46))
+*VEC*
+
+CL-USER&#62; (flex:with-input-from-sequence (in *vec*)
+ (flex:with-output-to-sequence (out)
+ (bzip2:compress in out)))
+#(66 90 104 57 49 65 89 38 83 89 229 1 241 105 0 0 1 147 128 64 1 0 128
+ 62 76 129 0 32 0 49 0 208 1 76 152 200 210 14 15 24 181 167 18 7 79
+ 197 220 145 78 20 36 57 64 124 90 64)
+
+CL-USER&#62; (flex:with-input-from-sequence (in *)
+ (flex:with-output-to-sequence (out)
+ (bzip2:decompress in out)))
+#(87 101 32 108 111 118 101 32 98 104 97 107 99 104 111 100 46)
+</code></pre>
+
+ <h3 id="dictionary">The cl-bzip2 dictionary</h3>
+
+ <p class="symbol">[Condition type]<br />
+<b>bz-error</b></p>
+
+ <blockquote>
+ <p>The default condition type for any BZIP2 compression/decompression related error.</p>
+ </blockquote>
+
+ <p class="symbol">[Function]<br />
+<b>compress</b> <i>in out <tt>&amp;key</tt> block-size-100k verbosity work-factor</i></p>
+
+ <blockquote>
+ <p>Compresses data from IN to <span class="caps">OUT</span>. IN or <span class="caps">OUT</span> can either be a binary stream or a pathname.</p>
+ <p><i><code>BLOCK-SIZE-100K</code></i> (default 9), <i><code>VERBOSITY</code></i> (default 0) and <i><code>WORK-FACTOR</code></i> (default 30) correspond to the parameters <i><code>blockSize100k</code></i>, <i><code>verbosity</code></i> and <i><code>workFactor</code></i>, respectively, for the libbzip2 function <i><code>BZ2_bzCompressInit</code></i>.</p>
+ <p>From the bzip2 manual:</p>
+ <p>Parameter <i><code>blockSize100k</code></i> specifies the block size to be used for compression. It should be a value between 1 and 9 inclusive, and the actual block size used is 100000 x this figure. 9 gives the best compression but takes most memory.</p>
+ <p>Parameter <i><code>verbosity</code></i> should be set to a number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.</p>
+ <p>Parameter <i><code>workFactor</code></i> controls how the compression phase behaves when presented with worst case, highly repetitive, input data. If compression runs into difficulties caused by repetitive data, the library switches from the standard sorting algorithm to a fallback algorithm. The fallback is slower than the standard algorithm by perhaps a factor of three, but always behaves reasonably, no matter how bad the input.</p>
+ </blockquote>
+
+ <p class="symbol">[Function]<br />
+<b>decompress</b> <i>in out <tt>&amp;key</tt> verbosity smallp</i></p>
+
+ <blockquote>
+ <p>Decompresses data from IN to <span class="caps">OUT</span>. IN or <span class="caps">OUT</span> can either be a binary stream or a pathname.</p>
+ <p><i><code>VERBOSITY</code></i> and <i><code>SMALLP</code></i> (default <span class="caps">NIL</span>) correspond to the parameters <i><code>verbosity</code></i> and <i><code>small</code></i>, respectively, for the libbzip2 function <i><code>BZ2_bzDecompressInit</code></i>.</p>
+ <p>For the meaning of <i><code>VERBOSITY</code></i>, see the documentation for <span class="caps">COMPRESS</span>. A non-<span class="caps">NIL</span> value for <i><code>SMALLP</code></i> corresponds to a non-zero value for the parameter <i><code>small</code></i>. Here&#8217;s what the bzip2 manual says about <i><code>small</code></i>:</p>
+ <p>If <i><code>small</code></i> is nonzero, the library will use an alternative decompression algorithm which uses less memory but at the cost of decompressing more slowly (roughly speaking, half the speed, but the maximum memory requirement drops to around 2300k).</p>
+ </blockquote>
+
+ <h3 id="limit">Limitations</h3>
+
+ <p>As of now, cl-bzip2 works only with binary streams. I haven&#8217;t figured out an easy way to make it work with string streams. If you know how that can be done, please <a href="#support">let us know</a>.</p>
+
+ <p>Also, performance is definitely not as great as it can be. If you want to fix that, the guts of the code lie in <span class="caps">COMPRESS</span>-<span class="caps">STREAM</span> and <span class="caps">COMPRESS</span>-<span class="caps">STREAM</span>-<span class="caps">AUX</span> (for compression), and <span class="caps">DECOMPRESS</span>-<span class="caps">STREAM</span> and <span class="caps">DECOMPRESS</span>-<span class="caps">STREAM</span>-<span class="caps">AUX</span> (for decompression). Any help would be greatly appreciated!</p>
+
+ <h3 id="acknowledgements">Acknowledgements</h3>
+
+ <p>Thanks to Julian Seward for the bzip2 compression format and the excellent libbzip2 interface.</p>
+
+ <p>Thanks also to <a href="http://piecesofrakesh.blogspot.com/">Rakesh Pai</a> for helping out with the <span class="caps">CSS</span> for this page. (And that became my introduction to <span class="caps">CSS</span>!). The markup for the cl-bzip2 dictionary was inspired from <a href="http://weitz.de/documentation-template/"><span class="caps">DOCUMENTATION</span>-<span class="caps">TEMPLATE</span></a>.</p>
+
+ </body>
+</html>
diff -rN -u old-cl-bzip2/doc/index.textile new-cl-bzip2/doc/index.textile
--- old-cl-bzip2/doc/index.textile 1969-12-31 16:00:00.000000000 -0800
+++ new-cl-bzip2/doc/index.textile 2014-07-30 12:15:58.000000000 -0700
@@ -0,0 +1,141 @@
+h2. CL-BZIP2 -- BZIP2 compression/decompression for Common Lisp
+
+h3(#introduction). Introduction
+
+cl-bzip2 provides "CFFI":http://common-lisp.net/project/cffi/ bindings for libbzip2 -- the "bzip2":http://www.bzip.org/ compression/decompression library.
+
+h3(#contents). Contents
+
+# "Download and installation":#download
+# "Support and mailing lists":#support
+# "Examples":#examples
+## "Compression":#compression
+## "Decompression":#decompression
+## "Working with vectors":#vectors
+# "The cl-bzip2 dictionary":#dictionary
+# "Limitations":#limit
+# "Acknowledgements":#acknowledgements
+
+h3(#download). Download and installation
+
+Current release: "Version 0.1.0":http://common-lisp.net/project/cl-bzip2/cl-bzip2-0.1.0.tar.gz
+
+You can also "browse the darcs repository":http://common-lisp.net/cgi-bin/darcsweb/darcsweb.cgi?r=cl-bzip2-cl-bzip2;a=summary or get yourself a copy using darcs get:
+
+<pre>
+darcs get http://common-lisp.net/project/cl-bzip2/darcs/cl-bzip2
+</pre>
+
+cl-bzip2 has a couple of dependencies:
+
+# "CFFI":http://common-lisp.net/project/cffi/ -- the Common Foreign Function Interface, which provides C bindings for
+# "libbzip2":http://www.bzip.org/downloads.html -- The C library for compressing and decompressing data in the bzip2 format. Make sure the shared object library (libbz2.so/libbz2.dylib) is installed on your machine. The bzip2 manual can be found "here":http://www.bzip.org/1.0.5/bzip2-manual-1.0.5.html.
+
+To compile and load cl-bzip2, you can either use ASDF, or simply evaluate @(load (compile-file "bzip2.lisp"))@ while in the cl-bzip2 source directory.
+
+h3(#support). Support and mailing lists
+
+Send questions, bug reports, patches, feature requests, etc. to "cl-bzip2-devel":http://common-lisp.net/cgi-bin/mailman/listinfo/cl-bzip2-devel. Release announcements are made on "cl-bzip2-announce":http://common-lisp.net/cgi-bin/mailman/listinfo/cl-bzip2-announce.
+
+h3(#examples). Examples
+
+h4(#compression). Compression
+
+Use COMPRESS to compress data from a stream/pathname to another stream/pathname. Note that stream should be a binary stream. COMPRESS will not work with string streams i.e. a stream supplied by WITH-INPUT-FROM-STRING or WITH-OUTPUT-TO-STRING will most likely not work at all.
+
+<pre><code>
+;;; Compression usage
+;;; No values are returned if execution was successful
+;;; Using pathnames
+CL-USER> (bzip2:compress #p"test.txt" #p"test.txt.bz2")
+; No value
+;;; Using binary streams
+CL-USER> (with-open-file (in "test.txt" :direction :input :element-type '(unsigned-byte 8))
+ (with-open-file (out "test.txt.bz2" :direction :output :element-type '(unsigned-byte 8))
+ (bzip2:compress in out)))
+; No value
+;;; Mixing stream and pathname
+CL-USER> (with-open-file (in "test.txt" :direction :input :element-type '(unsigned-byte 8))
+ (bzip2:compress in #p"test.txt.bz2"))
+; No value
+</code></pre>
+
+h4(#decompression). Decompression
+
+Use DECOMPRESS to decompress data from a stream/pathname to another stream/pathname. As with COMPRESS, stream should be a binary stream.
+
+<pre><code>
+;;; Decompression usage is similar to that for compression
+;;; Using pathnames
+CL-USER> (bzip2:decompress #p"test.txt.bz2" #p"test.txt")
+; No value
+;;; Using binaray streams
+CL-USER> (with-open-file (in "test.txt.bz2" :direction :input :element-type '(unsigned-byte 8))
+ (with-open-file (out "test.txt" :direction :output :element-type '(unsigned-byte 8))
+ (bzip2:decompress in out)))
+; No value
+</code></pre>
+
+h4(#vectors). Working with vectors
+
+Compression/decompression of vectors can easily be done with in-memory binary streams by using, for example, "FLEXI-STREAMS":http://weitz.de/flexi-streams/.
+
+<pre><code>
+CL-USER> (defvar *vec* #(87 101 32 108 111 118 101 32 98 104 97 107 99 104 111 100 46))
+*VEC*
+CL-USER> (flex:with-input-from-sequence (in *vec*)
+ (flex:with-output-to-sequence (out)
+ (bzip2:compress in out)))
+#(66 90 104 57 49 65 89 38 83 89 229 1 241 105 0 0 1 147 128 64 1 0 128
+ 62 76 129 0 32 0 49 0 208 1 76 152 200 210 14 15 24 181 167 18 7 79
+ 197 220 145 78 20 36 57 64 124 90 64)
+CL-USER> (flex:with-input-from-sequence (in *)
+ (flex:with-output-to-sequence (out)
+ (bzip2:decompress in out)))
+#(87 101 32 108 111 118 101 32 98 104 97 107 99 104 111 100 46)
+</code></pre>
+
+h3(#dictionary). The cl-bzip2 dictionary
+
+p(symbol). [Condition type]
+<b>bz-error</b>
+
+bq. The default condition type for any BZIP2 compression/decompression related error.
+
+p(symbol). [Function]
+<b>compress</b> <i>in out <tt>&amp;key</tt> block-size-100k verbosity work-factor</i>
+
+bq.. Compresses data from IN to OUT. IN or OUT can either be a binary stream or a pathname.
+
+<i>@BLOCK-SIZE-100K@</i> (default 9), <i>@VERBOSITY@</i> (default 0) and <i>@WORK-FACTOR@</i> (default 30) correspond to the parameters <i>@blockSize100k@</i>, <i>@verbosity@</i> and <i>@workFactor@</i>, respectively, for the libbzip2 function <i>@BZ2_bzCompressInit@</i>.
+
+From the bzip2 manual:
+
+Parameter <i>@blockSize100k@</i> specifies the block size to be used for compression. It should be a value between 1 and 9 inclusive, and the actual block size used is 100000 x this figure. 9 gives the best compression but takes most memory.
+
+Parameter <i>@verbosity@</i> should be set to a number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.
+
+Parameter <i>@workFactor@</i> controls how the compression phase behaves when presented with worst case, highly repetitive, input data. If compression runs into difficulties caused by repetitive data, the library switches from the standard sorting algorithm to a fallback algorithm. The fallback is slower than the standard algorithm by perhaps a factor of three, but always behaves reasonably, no matter how bad the input.
+
+p(symbol). [Function]
+<b>decompress</b> <i>in out <tt>&amp;key</tt> verbosity smallp</i>
+
+bq.. Decompresses data from IN to OUT. IN or OUT can either be a binary stream or a pathname.
+
+<i>@VERBOSITY@</i> and <i>@SMALLP@</i> (default NIL) correspond to the parameters <i>@verbosity@</i> and <i>@small@</i>, respectively, for the libbzip2 function <i>@BZ2_bzDecompressInit@</i>.
+
+For the meaning of <i>@VERBOSITY@</i>, see the documentation for COMPRESS. A non-NIL value for <i>@SMALLP@</i> corresponds to a non-zero value for the parameter <i>@small@</i>. Here's what the bzip2 manual says about <i>@small@</i>:
+
+If <i>@small@</i> is nonzero, the library will use an alternative decompression algorithm which uses less memory but at the cost of decompressing more slowly (roughly speaking, half the speed, but the maximum memory requirement drops to around 2300k).
+
+h3(#limit). Limitations
+
+As of now, cl-bzip2 works only with binary streams. I haven't figured out an easy way to make it work with string streams. If you know how that can be done, please "let us know":#support.
+
+Also, performance is definitely not as great as it can be. If you want to fix that, the guts of the code lie in COMPRESS-STREAM and COMPRESS-STREAM-AUX (for compression), and DECOMPRESS-STREAM and DECOMPRESS-STREAM-AUX (for decompression). Any help would be greatly appreciated!
+
+h3(#acknowledgements). Acknowledgements
+
+Thanks to Julian Seward for the bzip2 compression format and the excellent libbzip2 interface.
+
+Thanks also to "Rakesh Pai":http://piecesofrakesh.blogspot.com/ for helping out with the CSS for this page. (And that became my introduction to CSS!). The markup for the cl-bzip2 dictionary was inspired from "DOCUMENTATION-TEMPLATE":http://weitz.de/documentation-template/.
diff -rN -u old-cl-bzip2/doc/style.css new-cl-bzip2/doc/style.css
--- old-cl-bzip2/doc/style.css 1969-12-31 16:00:00.000000000 -0800
+++ new-cl-bzip2/doc/style.css 2014-07-30 12:15:58.000000000 -0700
@@ -0,0 +1,60 @@
+* {
+ margin: 0;
+ padding: 0;
+ font-size: 16px;
+ }
+
+body {
+ width: 950px;
+ padding: 20px;
+ font-family: helvetica;
+ line-height: 1.2em;
+ }
+
+ol {
+ margin-left: 30px;
+ }
+
+h2 {
+ margin: 10px 0;
+ border-bottom: 1px solid #000;
+ font-size: 22px;
+ }
+
+h3 {
+ margin: 15px 0 7px 0;
+ background: #ddd;
+ padding: 3px;
+ font-size: 20px;
+ font-weight: normal;
+ }
+
+h4 {
+ font-size: 19px;
+ margin: 15px 0 7px 0;
+ font-style: italic;
+ }
+
+pre {
+ background: #eee;
+ border: 1px solid #ccc;
+ margin: 10px;
+ padding: 5px;
+ }
+
+code {
+ font-size: 0.95em;
+ line-height: 1.2em;
+ }
+
+p {
+ margin: 10px;
+ }
+
+p.symbol {
+ margin-top: 20px;
+ }
+
+blockquote {
+ margin-left: 30px;
+ }
\ No newline at end of file