(use eggdoc) (define license "Copyright (c) 2005-2007 Oskar Schirmer. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.") (define doc `((eggdoc:begin (name "z3") (description (p "A gzip (RFC1951 + RFC1952) compression and decompression library")) (author "Oskar Schirmer and felix winkelmann") (history (version "1.39" "Fix eof bug in port interface") (version "1.38" "Fix minor bug in error handling and clarify documentation (trac tickets 81, 82)") (version "1.37" "ported to CHICKEN 4") (version "1.36" "Should compile now on Windows with mingw") (version "1.35" "Fixed bug in " (tt "z3:encode-buffer") " [reported by Mario Domenech Goulart]") (version "1.34" "Added whole-buffer encoding/decoding") (version "1.33" "Fixed setup script and meta file [Thanks to Peter Busser]") (version "1.32" "Fixed bug in z3lib code, related to 64-bit architectures") (version "1.31" "Fixed bug in " (tt "z3:encode")) (version "0.9" "Initial release") ) (usage) (documentation (p "Provides functions to read and write compressed data using the RFC 1951 (DEFLATE) and RFC 1952 (gzip) compression standards." " This extension includes code from Oskar Schirmers excellent " (a (@ (href "http://scara.com/~schirmer/o/z3lib/")) "z3lib") "library.") (p "RFC1952 is popularly used in the gzip file format and in compression of replies from web servers. RFC1951 (DEFLATE) is the underlying compression technique which is also used by PKZIP.") (p "NOTE: RFC1952 is essentially a file wrapper around a RFC1951 stream. Attempting to use the RFC1952 interfaces on RFC1951 data or vice versa will result in errors.") (p "Errors occurring in inflation/deflation procedures will result in a composite" " condition of the kinds " (tt "exn") " and " (tt "z3") ".") (subsection "Raw data interface - RFC1951" (group (procedure "(z3:encode-init #!key buffer buffer-size tellwhen thrmin thrmax initialgrant preferlonger)" (p "Initializes RFC1951 compression of data into a memory buffer. Various keyword arguments can be supplied" " to control compression:") (dl (dt "buffer") (dd "The target buffer for the compressed data") (dt "buffer-size") (dd "maximal size of the compressed data") (dt "tellwhen") (dd "Frequency for code size estimation (0 for none, i.e. full block usage)") (dt "thrmin, thrmax") (dd "Threshold for block close decision") (dt "initialgrant") (dd "For threshold comparison, all but the first slice are asumed to be " "incremented by this value to roughly compensate RFC1951 block dynamic " "table size") (dt "preferlonger") (dd "When non-zero, the compressor will try to find a longer match at " " n+1 and prefer it over a previous match at n") ) (p "Returns a z3 handle.") ) (procedure "(z3:encode Z3HANDLE RECEIVER DATA [LENGTH])" (p "Encode data (a string) into a memory buffer using RFC1951 compression and returns the number of bytes written. If less" " data has been commpressed than given in the call, invoke " (tt "z3:encode") " repeatedly with" " the remaining data. Returns " (tt "#f") " when finished. Each time some compressed data is" " available, the one-argument procedure " (tt "RECEIVER") " is called with a string containing" " a chunk of compressed data.") ) (procedure "(z3:decode-init)" (p "Initialize an in-memory RFC1951 decompression and return a z3 handle for it.") ) (procedure "(z3:decode Z3HANDLE RECEIVER BUFFER [LENGTH])" (p "Decode the RFC1951 compressed data in " (tt "BUFFER") " (a string) and return the number of" " bytes decompressed.") ) (procedure "(z3:handle? X)" (p "Returns " (tt "#t") " if " (tt "X") " is a z3 handle or " (tt "#f") " otherwise.") ) ) ) (subsection "Buffer interface - RFC1951" (grooup (procedure "(z3:encode-buffer STRING [START [END [DESTINATION]]])" (p "Encodes the data in " (tt "STRING") " using RFC1951 encoding with optional start- and end-positions." " If " (tt "DESTINATION") " is given, then the compressed data will be stored in" " that argument (which should be a string of sufficient size) and " (tt "z3:encode-buffer") " returns the length of the compressed data. If no destination is given then a freshly allocated" " string is returned that contains the compressed data.") ) (procedure "(z3:decode-buffer STRING [START [END]])" (p "Decodes the RFC1951 compressed data in " (tt "STRING") " and returns the uncompressed" " data. Optional start- and end-position may be given.") ) ) ) (subsection "File-system interface - RFC1952" (group (procedure "(z3:encode-file FILENO #!key level filename comment ostype extra)" (p "Open a RFC1952 compressed "gzip" file (specified by the file-descriptor in " (tt "FILENO") ") for encoded data. " "The keyword arguments have the following meaning:") (dl (dt "level") (dd "Desired compression-level in the range 1 .. 9, or 0 for selecting the default compression level") (dt "filename") (dd "The name of the file to compress, will be included in the gzip-file header") (dt "comment") (dd "An arbitrary comment") (dt "ostype") (dd "Operating system indicator byte (defaults to -1)") (dt "extra") (dd "Extra data to be encoded in the header") ) (p "Returns a z3 file-handle.") ) (procedure "(z3:write-encoded Z3FHANDLE DATA [LENGTH])" (p "Writes " (tt "DATA") " (a string) into a RFC1952 (gzip) compressed file, optionally limited in length." " Before a file has been encoded completely, this procedure must be called once more with " (tt "DATA") " being " (tt "#f") " to indicate that the compression process is finished.") ) (procedure "(z3:decode-file FILENO)" (p "Returns a z3 file-handle for reading the gzip file designated by the file-descriptor " (tt "FILENO") ".") ) (procedure "(z3:read-decoded Z3FHANDLE [LENGTH])" (p "Reads a chunk of decoded data from a gzip compressed file. The length of the chunk can be given as" " an optional argument and defaults to 4096 bytes. Returns a string or the end-of-file object.") ) (procedure "(z3:file-handle? X)" (p "Returns " (tt "#t") " if " (tt "X") " is a z3 file handle or " (tt "#f") " otherwise.") ) (procedure "(z3:file-handle-fileno Z3FHANDLE)" (p "Returns the file-descriptor associated with a z3 file-handle.") ) ) ) (subsection "Port interface - RFC1952" (group (procedure "(z3:open-compressed-input-file FILENAME)" (p "Opens a RFC1952 compressed "gzip" input file and returns a port that automatically" " decompresses the data as it is read.") ) (procedure "(z3:open-compressed-output-file FILENAME #!key level comment ostype extra)" (p "Creates a RFC1952 compressed "gzip" file and returns an output-port. The keyword arguments have the same" " meaning as for the " (tt "z3:encode-file") " procedure.") ) ) ) )) (section "License" (pre ,license)))) (eggdoc->html doc)