(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.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 gzip algorithm." " This extension includes code from Oskar Schirmers excellent " (a (@ (href "http://scara.com/~schirmer/o/z3lib/")) "z3lib") "library.") (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" (group (procedure "(z3:encode-init #!key buffer buffer-size tellwhen thrmin thrmax initialgrant preferlonger)" (p "Initializes 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 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 decompression and return a z3 handle for it.") ) (procedure "(z3:decode Z3HANDLE RECEIVER BUFFER [LENGTH])" (p "Decode the 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" (grooup (procedure "(z3:encode-buffer STRING [START [END [DESTINATION]]])" (p "Encodes the data in " (tt "STRING") " 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 compressed data in " (tt "STRING") " and returns the uncompressed" " data. Optional start- and end-position may be given.") ) ) ) (subsection "File-system interface" (group (procedure "(z3:encode-file FILENO #!key level filename comment ostype extra)" (p "Open a compressed 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 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 file designated by the file-descriptor " (tt "FILENO") ".") ) (procedure "(z3:read-decoded Z3FHANDLE [LENGTH])" (p "Reads a chunk of decoded data from a 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" (group (procedure "(z3:open-compressed-input-file FILENAME)" (p "Opens a compressed 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 compressed 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)