Rui (2006/12/13 03:02:53 PST): Gauche-zlib 0.1.2のREADME.jaからの転載です。コメントをこのページに書いていただいてよいです。
http://t-code.org/Gauche-zlib-0.1.2.tgz
Gauche-zlibは、Gauche Schemeシステムのための拡張モジュールで、Zlib圧縮ライブラリに対するバインディングを提供します。Gaucheと同じライセンスで配布できます。
Zlibは、ZLIB圧縮データフォーマット(RFC1950)、DEFLATE圧縮データフォーマット(RFC1951)、GZIPファイルフォーマット(RFC1952)の読み書きをサポートするライブラリです。また、CRC32とAdler32チェックサムの計算のための関数も提供します。Gauche-zlibから、Zlibが提供する機能の大部分を使うことができます。
圧縮・展開機能はポートを通して提供されます。圧縮をチューンするパラメータの詳細については、このREADMEと合わせてZlibのドキュメントを読んでもらうのがよいでしょう。このドキュメントの一部はzlib.hのコメントを元にしています。
CRC32チェックサムCHECKSUMを文字列STRINGで更新し、更新した整数を返します。CHECKSUMが省略されたときはデフォルトの初期値を用います。
Adler32チェックサムCHECKSUMを文字列STRINGで更新し、更新した整数を返します。CHECKSUMが省略されたときはデフォルトの初期値を用います。Adler32はCRC32と比較して高速に計算することが可能なアルゴリズムですが、小さなデータのチェックサムの信頼性にいくらか問題があることがわかっています。詳しくはRFC3309を見てください。これが問題になる場合はCRC32を使用してください。
圧縮率を表す整数値です。上から順に無圧縮、速度優先、圧縮率優先、デフォルトの圧縮率です。
圧縮アルゴリズムのチューン方法を指定する整数値です。
`zstream-data-type'手続きが返す整数値です。
Zlibのバージョンを表す文字列です。
Zlibが返すエラーを表す、<error>のサブクラスです。
<zlib-error>のサブクラスです。それぞれ、ZlibのZ_NEED_DICT_ERROR、Z_STREAM_ERROR、Z_DATA_ERROR、Z_MEMORY_ERROR、Z_VERSION_ERRORに対応します。
データの読み出し時にエラーが発生した場合、<zlib-error>のサブクラスと<io-read-error>の合成コンディションが投げられます。入力が伴わない場合、例えば圧縮ストリームの初期化エラーのときには、合成されていない<zlib-error>のサブクラスが投げられます。ただの引数の型のエラーのように、Zlibの関数が呼び出されない場合は、ただの<error>が投げられるかもしれません。
書き込まれたデータを圧縮し出力ポートDRAINに書き出す出力ポートを作成して、そのポートを返します。Zlibの関数deflateInit2()とdeflateSetDictionary()とを合わせた手続きです。
COMPRESSION-LEVELには1から9の整数を指定することができ、大きい数が高い圧縮率を意味します。引数が省略された場合は、デフォルトの圧縮レベルと見なされます。これは通常6です。
BUFFER-SIZEは、ポートのバッファサイズを指定します。デフォルトは4096バイトです。
WINDOW-BITSはウィンドウサイズを指定します。8から15までの整数を与えることができ、大きい数であるだけ圧縮率が高くなりますが、そのぶんメモリの使用量が増加します。デフォルトは15です。
WINDOW-BITSに-8から-15の整数を指定すると、ZLIBヘッダとトレイラのない生のdeflateデータを作成します。この場合Adler32チェックサムも計算されません。
15より大きいWINDOW-BITSはGZIPエンコーディングを意味します。WINDOW-BITSに16を足すと、zlibラッパの代わりに、シンプルなgzipヘッダとトレイラが圧縮データの前後に書き出されます。gzipヘッダはファイル名やその他のデータ、コメントを持たず、変更時刻は0、ヘッダCRC はなし、OS名は不明を意味する255になります。gzipストリームが書き出されるときは、`zstream-adler32'で取得できるチェックサムはAdler32 ではなくCRC32になります。
MEMORY-LEVELは、圧縮の内部状態のためにどれだけのメモリを割り当てるかを指定するパラメータです。1ではメモリの使用量は最小ですが、遅くなり圧縮率が低下します。9では高速な処理のためにメモリが最も多く使われます。デフォルトは8です。
STRATEGYで圧縮アルゴリズムをチューンできます。通常のデータにはZ_DEFAULT_STRATEGYを指定してください。フィルタが生成したデータのためにはZ_FILTEREDを、ハフマンエンコーディングを強制するならZ_HUFFMAN_ONLYを、マッチの距離を1に制限する(ランレングスエンコードする)ためにはZ_RLEを指定します。Z_FIXEDは動的ハフマンエンコーディングを禁止します。詳細はzlib.hを参照してください。デフォルトはZ_DEFAULT_STRATEGYです。
DICTIONARYには圧縮に使う辞書を文字列で与えます。デフォルトでは辞書は使われません。
通常、`open-deflate-port'は変換が全て終了した後でもSOURCEはオープンしたままにします。キーワード引数OWNER?に真の値を指定すると、EOF が読まれた後でSOURCEはクローズされます。
注意: `open-deflate-port'でオープンした出力ポートは、必ず明示的にクローズしてください。そうしなければ圧縮データの終わりの部分(バッファされているデータおよびトレイラ)がDRAINに書き出されないかもしれません。これは以下の理由によるものです: ポートを明示的にクローズしない場合、出力ポートのクローズ手続きはガベージ・コレクタのファイナラザから呼び出されることになります。Deflateポートのクローズ手続きがファイナライザから呼び出されたときに、すでにDRAIN のファイナライザが呼び出されていて、DRAINがクローズしてしまっていることがあります。このような場合には、圧縮データの終わりの部分の出力がエラーになってしまいます。
`open-deflate-port'が返すポートのクラスです。
圧縮データを読み出せる入力ポートSOURCEを取り、展開されたデータを読み出すことのできる入力ポートを作成して、そのポートを返します。これはZlibの関数inflateInit2()、inflateSetDictionary()を合わせた手続きです。
BUFFER-SIZE、OWNER?の意味は`open-deflate-port'と同様です。
WINDOW-BITSが15より大きい場合はGZIPデコードを行います。32が足された場合にはZLIBとGZIPのヘッダ自動判定が有効になります。
DICTIONARYは圧縮時の辞書と同じものを指定しなければなりません。辞書が必要な圧縮データを展開するときに、DICTIONARYが渡されなかったか、圧縮時と異なる辞書が渡されたなら、<io-read-error>と<zlib-need-dict-error>の合成コンディションが投げられます。
`open-inflate-port'が返すポートのクラスです。<inflate-port>に与えた圧縮データが壊れている場合、データの読み出し時に<io-read-error> と<zlib-data-error>の合成コンディションが投げられます。
z_stream構造体のtotal_in、total_outにアクセスする手続きです。
z_stream構造体のadler、data_typeにアクセスする手続きです。
圧縮率とストラテジを動的に変更するための手続きです。
Deflateポートの作成時に辞書を指定すると、辞書のAdler32チェックサムが計算されます。この手続きはそのチェックサムを返します。`open-deflate-port' に辞書を与えなかったなら、#fが返ります。
Zlibフォーマットの文字列を読み書きするユーティリティ手続きです。すべてのオプション引数OPTIONS ...はそのまま`open-deflate-port'、`open-inflate-port'に渡されます。エンコードまたはデコードされた文字列が返ります。
GZIPフォーマットの文字列を読み書きするユーティリティ手続きです。これはdeflate-stringおよびinflate-stringのオプションに`:window-bits 15'を指定するのと同じです
ポートのデータをフルフラッシュし、圧縮状態をリセットします。これはZ_FULL_FLUSHを指定してdeflate()を呼ぶのと同じです。`inflate-sync' 手続きと組み合わせて使用します。
破損した圧縮データを、フルフラッシュしたポイントまで読み飛ばします。<zlib-data-error>が投げられたときに使用するとよいでしょう。フルフラッシュポイントに達したときは読み飛ばしたバイトの数を、EOFまで達したときは#fを返します。