@node Library modules - Utilities, References, Library modules - SRFIs, Top
@chapter Library modules - Utilities
@c NODE ライブラリモジュール - ユーティリティ


@c ----------------------------------------------------------------------
@menu
* Binary I/O::                  binary.io
* Packing Binary Data::         binary.pack
* Rational-less arithmetic::    compat.norational
* A common job descriptor for control modules::  control.job
* Thread pools::                control.thread-pool
* Password hashing::            crypt.bcrypt
* Database independent access layer::  dbi
* Generic DBM interface::       dbm
* File-system dbm::             dbm.fsdbm
* GDBM interface::              dbm.gdbm
* NDBM interface::              dbm.ndbm
* Original DBM interface::      dbm.odbm
* Filtering file content::      file.filter
* Filesystem utilities::        file.util
* Mathematic constants::        math.const
* Mersenne-Twister random number generator::  math.mt-random
* Windows support::             os.windows
* RFC822 message parsing::      rfc.822
* Base64 encoding/decoding::    rfc.base64
* HTTP cookie handling::        rfc.cookie
* FTP::                         rfc.ftp
* HMAC keyed-hashing::          rfc.hmac
* HTTP::                        rfc.http
* IP packets::                  rfc.ip
* ICMP packets::                rfc.icmp
* JSON parsing and construction::  rfc.json
* MD5 message digest::          rfc.md5
* MIME message handling::       rfc.mime
* Quoted-printable encoding/decoding::  rfc.quoted-printable
* SHA message digest::          rfc.sha
* URI parsing and construction::  rfc.uri
* Zlib compression library::    rfc.zlib
* SLIB::                        slib
* Functional XML parser::       sxml.ssax
* SXML Query Language::         sxml.sxpath
* Manipulating SXML structure::  sxml.tools
* Serializing XML and HTML from SXML::  sxml.serializer
* CSV tables::                  text.csv
* Calculate difference of text streams::  text.diff
* Localized messages::          text.gettext
* Simple HTML document construction::  text.html-lite
* Parsing input stream::        text.parse
* Showing progress on text terminals::  text.progress
* SQL parsing and construction::  text.sql
* Transliterate characters::    text.tr
* Lazy text construction::      text.tree
* Unicode utilities::           text.unicode
* Combination library::         util.combinations
* Message digester framework::  util.digest
* Determine isomorphism::       util.isomorph
* The longest common subsequence::  util.lcs
* Additional list library::     util.list
* Pattern matching::            util.match
* Queue::                       util.queue
* Red black tree::              util.rbtree
* SLIB-compatible record type::  util.record
* Relation framework::          util.relation
* Sparse data containers::      util.sparse
* Stream library::              util.stream
* Trie::                        util.trie
* Topological sort::            util.toposort
* CGI Utility::                 www.cgi
* CGI testing::                 www.cgi.test
@end menu

@c ----------------------------------------------------------------------
@node Binary I/O, Packing Binary Data, Library modules - Utilities, Library modules - Utilities
@section @code{binary.io} - Binary I/O
@c NODE バイナリI/O, @code{binary.io} - バイナリI/O

@deftp {Module} binary.io
@mdindex binary.io
@c EN
This module provides basic procedures to perform binary I/O
of numeric data.  Each datum can be read from or written to a port,
and got from or put to a uniform vector (see @ref{Uniform vectors}).
For structured binary data I/O,
more convenient @code{pack} utility is implemented
on top of this module (see @ref{Packing Binary Data}).
You might want to use this module directly if you need
speed or want a flexible control of endianness.

See also @ref{Uniform vectors}, which provides binary block I/O.
@c JP
このモジュールは数値データを読み書きするバイナリ入出力用の基本手続きを提
供します。各データはポートあるいはユニフォームベクタ
(@ref{Uniform vectors}参照)から読み込み、あるいはそれらへ書き出すことが
できます。
構造をもつバイナリデータの入出力については、便利な
@code{pack}ユーティリティがこのモジュールを使って実装されています
(@ref{Packing Binary Data}を参照してください)。
スピードあるいはエンディアンの柔軟な制御などをやりたいときにこのモジュー
ルが使えます。

バイナリのブロック入出力については@ref{Uniform vectors}を参照してくだ
さい。
@c COMMON
@end deftp

@c EN
@subheading Endianness
Most procedures of this module take an optional @var{endian} argument,
specifying the byte order of the binary input.
It must be either one of symbols @code{big-endian}, @code{little-endian},
or @code{arm-little-endian}.
If the endian argument is omitted, the current value of the builtin
parameter @code{default-endian} is used (@xref{Endianness}).
(For 8-bit I/O procedures like @code{read-u8} the endian
argument has no effect, but is accepted for consistency).
@c JP
@subheading エンディアン
このモジュールのほとんどの手続はオプション引数として@var{endian}引数を
とります。これは@code{big-endian}、@code{little-endian}、
@code{arm-little-endian}のいずれかのシンボルでなければなりません。
エンディアン引数が省略された場合には、組込みパラメータ@code{default-endian}
の現在値が使われます (@ref{Endianness}参照)。
(@code{read-u8}の ような
8ビット入出力手続ではエンディアン引数は意味がありませんが、
一貫性のため受け入れるようにしてあります。)
@c COMMON

@c EN
@subheading I/O using port
@c JP
@subheading ポートを用いたI/O
@c COMMON

@defun read-u8 :optional port endian
@defunx read-u16 :optional port endian
@defunx read-u32 :optional port endian
@defunx read-u64 :optional port endian
@c EN
Reads 8, 16, 32 or 64 bit unsigned integer from @var{port}
with specified endian, respectively.  If @var{port} is omitted, 
current input port is used.  If @var{port} reaches EOF before
a complete integer is read, EOF is returned.
@c JP
それぞれ指定したエンディアンで@var{port}から8、16、32、64ビット符号無
整数を読み込みます。@var{port}が省略された場合は、現在の入力ポートが使
われます。@var{port}が整数の読み込みが完了する前にEOFに到達してしまっ
た場合にはEOFが返ります。
@c COMMON
@end defun

@defun read-s8 :optional port endian
@defunx read-s16 :optional port endian
@defunx read-s32 :optional port endian
@defunx read-s64 :optional port endian
@c EN
Reads 8, 16, 32 or 64 bit 2's complement signed integer from @var{port}
with specified endian, respectively.  If @var{port} is omitted, 
current input port is used.  If @var{port} reaches EOF before
a complete integer is read, EOF is returned.
@c JP
それぞれ指定したエンディアンで@var{port}から8、16、32、64ビット、2の補
数符号付き整数を読み込みます。@var{port}が省略された場合は、現在の入力
ポートが使われます。@var{port}が整数の読み込みが完了する前にEOFに到
達してしまった場合にはEOFが返ります。 
@c COMMON
@end defun

@defun read-uint size :optional port endian
@defunx read-sint size :optional port endian
@c EN
More flexible version.  Reads @var{size}-octet unsigned
or signed integer from @var{port} with specified endian.
If @var{port} reaches EOF before a complete integer is read,
EOF is returned.
@c JP
さらに柔軟性が高く、@var{size}オクテットの符号無しあるいは符号付き整数
を@var{port}から指定のエンディアンで読み込みます。
@var{port}が整数の読み込みが完了する前にEOFに到
達してしまった場合にはEOFが返ります。 
@c COMMON
@end defun

@defun read-ber-integer :optional port
@c EN
Reads BER compressed integer a la X.209.
A BER compressed integer is an unsigned integer in base 128,
most  significant digit first, where the high bit is set on all but the
final (least significant) byte.
@c JP
X.209のBER圧縮形式整数を読み込みます。BER圧縮形式整数は128進符号無し整
数です。最上位桁が最初にきます。最下位桁のバイトをのぞき、すべてのバイ
トの最上位ビットはオンになっています。
@c COMMON
@end defun

@defun write-u8 val :optional port endian
@defunx write-u16 val :optional port endian
@defunx write-u32 val :optional port endian
@defunx write-u64 val :optional port endian
@c EN
Writes a nonnegative integer @var{val} as 8, 16, 32 or 64 bit
unsigned integer
to @var{port} with specified endian, respectively.  @var{Val} must be within
the range of integers representable by the specified bits.
When @var{port} is omitted, current output port is used.
@c JP
それぞれ指定したエンディアンで@var{port}へ 8、16、32、64ビット、符号無
し整数として表現されている非負整数@var{val}を書き出します。
@var{val}はそれぞれ指定したビット数の範囲で表現できる値でなければなり
ません。@var{port}が省略された場合は、現在の出力ポートが使われます。
@c COMMON
@end defun

@defun write-s8 val :optional port endian
@defunx write-s16 val :optional port endian
@defunx write-s32 val :optional port endian
@defunx write-s64 val :optional port endian
@c EN
Writes an integer @var{val} as 8, 16, 32 or 64 bit
as 2's complement signed integer to @var{port} with specified endian,
respectively.  @var{Val} must be within
the range of integers representable by the specified bits.
When @var{port} is omitted, current output port is used.
@c JP
それぞれ指定したエンディアンで@var{port}へ 8、16、32、64ビット、2の補
数符号付き整数として表現されている整数@var{val}を書き出します。
@var{val}はそれぞれ指定したビット数の範囲で表現できる値でなければなり
ません。@var{port}が省略された場合は、現在の出力ポートが使われます。
@c COMMON
@end defun

@defun write-uint size val :optional port endian
@defunx write-sint size val :optional port endian
@c EN
More flexible version.  Writes an integer @var{val} as unsigned
or signed integer of @var{size} bytes to @var{port} with
specified endian.
When @var{port} is omitted, current output port is used.
@c JP
さらに柔軟性が高く、@var{size}オクテットの符号無しあるいは符号付き整数
@var{val}を@var{port}へ、指定のエンディアンで書き出します。
@var{port}が省略された場合は、現在の出力ポートが使われます。
@c COMMON
@end defun

@defun write-ber-integer val :optional port
@c EN
Writes a nonnegative integer @var{val} in BER compressed integer
to @var{port}.  See @code{read-ber-integer} above for BER format.
@c JP
BER圧縮形式の非負整数@var{val}を@var{port}へ書き出します。
BER圧縮形式については前述の@code{read-ber-integer}を見てください。
@c COMMON
@end defun

@defun read-f16 :optional port endian
@defunx read-f32 :optional port endian
@defunx read-f64 :optional port endian
@c EN
Reads 16, 32, or 64-bit floating point numbers, respectively.
32bit is IEEE754 single-precision, and 64bit is
IEEE754 double-precision numbers.  16-bit floating
point number consists of 1-bit sign, 5-bit exponent and
10-bit mantissa, as used in some HDR image format.

If @var{port} is omitted, 
current input port is used.  If @var{port} reaches EOF before
a complete number is read, EOF is returned.
@c JP
それぞれ、16、32、64ビットの浮動小数点数を読み込みます。
32ビットはIEEE754単精度、64ビットは倍精度の浮動小数点数です。
16ビット浮動小数点数は、1ビットの符号、5ビットの指数、10ビットの仮数からなる、
HDRイメージフォーマット等に使われている形式です。

@var{port}が省略された場合には、
現在の入力ポートが使われます。@var{port}が数値の読み込みが完了する前に
EOFに到達してしまった場合にはEOFが返ります。 
@c COMMON
@end defun

@defun write-f16 val :optional port endian
@defunx write-f32 val :optional port endian
@defunx write-f64 val :optional port endian
@c EN
Writes a real number @var{val} to @var{port} in 16, 
32, or 64-bit floating point number, respectively.
If @var{port} is omitted, current output port is used. 
@c JP
実数値@var{val}を、それぞれ16、32、64ビットの浮動小数点数として
書き出します。
@var{port}が省略された場合には、現在の出力ポートが使われます。
@c COMMON
@end defun


@c EN
@subheading I/O using uniform vectors
@c JP
@subheading ユニフォームベクタを用いたI/O
@c COMMON

@c EN
In the following routines, the argument @var{uv} can be any
type of uniform vector; if it is not a @code{u8vector}, it is
treated as if @code{(uvector-alias <u8vector> @var{uv})} is
called---that is, it reads directly from the memory image
that holds the uvector's content.  The @var{pos} argument
specifies the byte position from the beginning of the memory
area (it is always byte position, regardless of the uniform
vector's element size).
@c JP
以下のルーチンでは、引数 @var{uv} は任意の型のユニフォームベクタをとり
えます。@code{u8vector} ではない場合には @code{(uvector-alias
<u8vector> @var{uv})} が呼ばれたのと同様の扱いになります。すなわち、
uvectorの内容を保持するメモリイメージから直接読み込まれます。@var{pos}
引数は当該のメモリ領域の最初からのバイト位置を指定するのに使います(こ
れはユニフォームベクタの要素のサイズにかかわらず、つねにバイト位置です)。
@c COMMON

@defun get-u8 uv pos :optional endian
@defunx get-u16 uv pos :optional endian
@defunx get-u32 uv pos :optional endian
@defunx get-u64 uv pos :optional endian
@defunx get-s8 uv pos :optional endian
@defunx get-s16 uv pos :optional endian
@defunx get-s32 uv pos :optional endian
@defunx get-s64 uv pos :optional endian
@defunx get-f16 uv pos :optional endian
@defunx get-f32 uv pos :optional endian
@defunx get-f64 uv pos :optional endian
@c EN
Reads a number of a specific format from a uniform vector @var{uv},
starting at a byte position @var{pos}.  An error is signalled
if the specified position makes reference outside of the uniform
vector's content.  Returns the read number.
@c JP
ユニフォームベクタ @var{uv} のバイト位置 @var{pos} から指定したフォー
マットで数値を読み込み、その数値を返します。指定した位置が当該ユニフォー
ムベクタの内容のある範囲外を参照するものであった場合、エラーを示すシグ
ナルがあがります。
@c COMMON
@end defun

@defun get-u16be uv pos
@defunx get-u16le uv pos
@defunx get-u32be uv pos
@defunx get-u32le uv pos
@defunx get-u64be uv pos
@defunx get-u64le uv pos
@defunx get-s16be uv pos
@defunx get-s16le uv pos
@defunx get-s32be uv pos
@defunx get-s32le uv pos
@defunx get-s64be uv pos
@defunx get-s64le uv pos
@defunx get-f16be uv pos
@defunx get-f16le uv pos
@defunx get-f32be uv pos
@defunx get-f32le uv pos
@defunx get-f64be uv pos
@defunx get-f64le uv pos
@c EN
These are big-endian (@code{be}) or little-endian (@code{le}) specific
versions of @code{get-*} procedures.  In speed-sensitive code,
you might want to use these to avoid the overhead of optional-argument
handling.
@c JP
これらは、@code{get-*} 手続のエンディアン(ビッグエンディアン @code{be}
あるいはリトルエンディアン @code{le})を指定した版です。スピードを要求
されるコードではオプション引数処理のオーバーヘッドを避けるためこちらを
使うのがいいでしょう。
@c COMMON
@end defun

@defun put-u8! uv pos val :optional endian
@defunx put-u16! uv pos val :optional endian
@defunx put-u32! uv pos val :optional endian
@defunx put-u64! uv pos val :optional endian
@defunx put-s8! uv pos val :optional endian
@defunx put-s16! uv pos val :optional endian
@defunx put-s32! uv pos val :optional endian
@defunx put-s64! uv pos val :optional endian
@defunx put-f16! uv pos val :optional endian
@defunx put-f32! uv pos val :optional endian
@defunx put-f64! uv pos val :optional endian
@c EN
Writes a number @var{val} into a uniform vector @var{uv} in
a specific format, starting at a byte position @var{pos}.
An error is signalled
if the specified position makes reference outside of the uniform
vector's content.
@c JP
数値 @var{val} をユニフォームベクタ @var{uv} のバイト位置 @var{pos} か
ら指定されたフォーマットで書き出します。指定した位置が当該ユニフォーム
ベクタの内容のある範囲外を参照するものであった場合、エラーを示すシグナ
ルがあがります。
@c COMMON
@end defun

@defun put-u16be! uv pos val
@defunx put-u16le! uv pos val
@defunx put-u32be! uv pos val
@defunx put-u32le! uv pos val
@defunx put-u64be! uv pos val
@defunx put-u64le! uv pos val
@defunx put-s16be! uv pos val
@defunx put-s16le! uv pos val
@defunx put-s32be! uv pos val
@defunx put-s32le! uv pos val
@defunx put-s64be! uv pos val
@defunx put-s64le! uv pos val
@defunx put-f16be! uv pos val
@defunx put-f16le! uv pos val
@defunx put-f32be! uv pos val
@defunx put-f32le! uv pos val
@defunx put-f64be! uv pos val
@defunx put-f64le! uv pos val
@c EN
These are big-endian (@code{be}) or little-endian (@code{le}) specific
versions of @code{put-*} procedures.  In speed-sensitive code,
you might want to use these to avoid the overhead of optional-argument
handling.
@c JP
これらは、@code{put-*} 手続のエンディアン(ビッグエンディアン @code{be}
あるいはリトルエンディアン @code{le})を指定した版です。スピードを要求
されるコードではオプション引数処理のオーバーヘッドを避けるためこちらを
使うのがいいでしょう。
@c COMMON
@end defun

@c EN
@subheading Compatibility notes
@c JP
@subheading 互換性への注
@c COMMON

@c EN
@code{read-u8} etc. were called @code{read-binary-uint8} etc., and 
@code{read-f32} and @code{read-f64} were called @code{read-binary-float}
and @code{read-binary-double}, respectively.
These old names are still supported for the backward compatibility
but their use is deprecated.  The reason of the changes is
for brevity and for consistency with the uniform vectors.
@c JP
@code{read-u8} などは @code{read-binary-uint8} と呼ばれていたもので、
@code{read-f32} や @code{read-f64} はそれぞれ @code{read-binary-float}、
@code{read-binary-double} と呼ばれていたものです。
これらの古い名前は後方互換のためいまのところサポートされていますが、使
用については非推奨とします。この変更は名前の短縮とユニフォームベクタと
の一貫性維持のために行われました。
@c COMMON

@c ----------------------------------------------------------------------
@node Packing Binary Data, Rational-less arithmetic, Binary I/O, Library modules - Utilities
@section @code{binary.pack} - Packing Binary Data
@c NODE バイナリデータのパック, @code{binary.pack} - バイナリデータのパック

@deftp {Module} binary.pack
@mdindex binary.pack
@c EN
This module provides an interface for packing and unpacking (writing
and reading) binary data with templates.  The functionality was
inspired largely by the Perl pack/unpack functions, with comparison of
similar features from other languages, however an effort was made to
make it more general and more efficient, to be usable for
database-like processing.  To that end, the most notable differences
are that any packable value is unpackable (and vice versa), and the
default behavior is to pack and unpack using port I/O, so you can seek
in a large file and unpack from it.  Also, templates may be stored as
dispatch closures to pack, unpack or even skip over values without
re-parsing the template.
@c JP
このモジュールは、バイナリデータをテンプレートを使って
パック/アンパック(読み書き)するためのインタフェースを提供します。
この機能は、その多くをPerlのpack/unpack関数から着想し、他の言語での
同じような機能と比較しながら、しかし、データベースライクな処理に
便利なように、より一般的でより効率が良くなるように実装しました。
これを受けて、最も大きな相違点は、全てのパック可能な値はアンパック
可能で(逆も同様)、パック/アンパックのデフォルトの振る舞いはポートI/Oを
使うので、巨大なファイルを読みながらそこからアンパックすることが
できます。また、テンプレートはディスパッチクロージャとして格納でき、
パック、アンパック、あるいは値のスキップさえも、テンプレートを
パーズし直すことなく行えます。
@c COMMON

@c See also binary.io - Binary I/O for utilities to read and write
@c individual binary values.
@end deftp

@defun pack template list :key :output :to-string?
@c EN
Writes the values in @var{list} to the current output port, according
to the format specified by the string @var{template}.  The template
string is a series of single character codes, optionally followed by a
numeric count (which defaults to 1).
@c JP
@var{list}にある値を、文字列@var{template}で指定されたフォーマットに
したがって、現在の出力ポートに書き出します。テンプレート文字列は、
1文字のコードの連続で、オプションで(デフォルトが1である)カウント用の数字
が続きます。

@c EN
The format characters can generally be divided into string types,
which interpret the count as a string byte size, and object types,
which treat the count as a repetition indicator.  The count may be
specified as the character @code{*}, which means to use the full
size of the string for string types, and use all remaining values for
object types.
@c JP
フォーマット文字は一般的に、カウントを文字のバイト数と解釈する
文字列型と、カウントを繰り返し指示子と解釈するオブジェクト型に
分けられます。カウントは文字@code{*}で指定され、文字列型では
文字列の全体の長さを、オブジェクト型では残りの全ての値を使うことを
意味します。

@c EN
Counts may also be specified as a template enclosed in brackets, which
means the count is the byte size of the enclosed template.  For
example, @code{x[L]} skips a long.
@c JP
カウントは大括弧に囲まれたテンプレートとしても指定でき、その場合
カウントはその大括弧を囲んでいるテンプレートのバイト数を意味します。
例えば、@code{x[L]}はlongをスキップします。

@c EN
The special format character @code{/} may be used to indicate a
structure where the packed data contains a dynamic count followed by
the value itself.  The template is written as
@code{<count-item>/<value-item>}, where @code{<count-item>} is any
template character to be interpreted as a numeric count, and
@code{<value-item>} is any other template character to use this count.
If a normal count is given after @code{<value-item>} it is ignored.
@c JP
特別なフォーマット文字@code{/}は、パックされたデータが、値に続く
動的なカウント分を含むという構造を表すために使われます。
テンプレートは、@code{<count-item>/<value-item>}のように書かれ、
ここでは@code{<count-item>}は数値のカウントと解釈されるいかなる
テンプレート文字、@code{<value-item>}はこのカウントを使ういかなる
他のテンプレート文字です。
@code{<value-item}>の後に通常のカウントが与えられても、無視されます。

@c EN
The format character @code{@@} may be used with a count to pad to an
absolute position since the start of the template.
@c JP
フォーマット文字@code{@@}は、カウントとともに使われ、テンプレートの
最初からの絶対位置までパディングします。

@c EN
Sub-templates may be grouped inside parentheses.  If angle-brackets
are used, then they also behave as group operators but recursively
operate on nested lists.
@c JP
サブテンプレートは、括弧の中にグループ化されます。<>が使われると、
ネストされたリストに再帰的に適用されるグループ化オペレータとしても
振舞います。

@c EN
The string types:
@c JP
文字列型:

@c COMMON
@table @code
@item a
@c EN
An arbitrary incomplete string, null padded.
@c JP
任意の不完全文字列。NULLでパディングされます。
@c COMMON

@item A
@c EN
A text string, space padded.
@c JP
テキスト文字列。空白スペースでパディングされます。
@c COMMON

@item Z
@c EN
A null terminated (ASCIZ) string, null padded.
@c JP
NULL終端(ASCIZ)文字列。NULLでパディングされます。
@c COMMON

@item b
@c EN
A bit string (ascending bit order inside each byte).
@c JP
ビット文字列(それぞれのバイトにおけるビットオーダーは昇順)。
@c COMMON

@item B
@c EN
A bit string (descending bit order inside each byte).
@c JP
ビット文字列(それぞれのバイトにおけるビットオーダーは降順)。
@c COMMON

@item h
@c EN
A hex string (low nybble first).
@c JP
16進文字列(低いニブルが先)。
@c COMMON

@item H
@c EN
A hex string (high nybble first).
@c JP
16進文字列(高いニブルが先)。
@c COMMON
@end table

@c EN
The object types:
@c JP
オブジェクト型:
@c COMMON

@table @code
@item c
@c EN
A signed 8bit integer.
@c JP
符号付き8ビット整数。
@c COMMON

@item C
@c EN
An unsigned 8bit integer.
@c JP
符号なし8ビット整数。
@c COMMON

@item s
@c EN
A signed short (16 bit) value.
@c JP
符号付き16ビット整数。
@c COMMON

@item S
@c EN
An unsigned short (16 bit) value.
@c JP
符号なし16ビット整数。
@c COMMON

@item i
@c EN
A signed integer (>= 32 bit) value.
@c JP
符号付き整数(>= 32ビット)。
@c COMMON

@item I
@c EN
An unsigned integer (>= 32 bit) value.
@c JP
符号なし整数(>= 32ビット)。
@c COMMON

@item l
@c EN
A signed long (32 bit) value.
@c JP
符号付きlong(32ビット)。
@c COMMON

@item L
@c EN
An unsigned long (32 bit) value.
@c JP
符号なしlong(32ビット)。
@c COMMON

@item n, n!
@c EN
An unsigned and signed short (16 bit) in "network" (big-endian) order.
@c JP
ネットワークオーダー(ビッグエンディアン)での符号なし/符号つきshort(16ビット)。
@c COMMON

@item N, N!
@c EN
An unsigned and signed long (32 bit) in "network" (big-endian) order.
@c JP
ネットワークオーダー(ビッグエンディアン)での符号なし/符号つきlong(32ビット)。
@c COMMON

@item v, v!
@c EN
An unsigned and signed short (16 bit) in "VAX" (little-endian) order.
@c JP
VAXオーダー(リトルエンディアン)での符号なし/符号つきshort(16ビット)。
@c COMMON

@item V, V!
@c EN
An unsigned and signed long (32 bit) in "VAX" (little-endian) order.
@c JP
VAXオーダー(リトルエンディアン)での符号なし/符号つきlong(32ビット)。
@c COMMON

@item q
@c EN
A signed quad (64 bit) value.
@c JP
符号付きquad(64ビット)。
@c COMMON

@item Q
@c EN
An unsigned quad (64 bit) value.
@c JP
符号なしquad(64ビット)。
@c COMMON

@item f
@c EN
A single-precision float in the native format.
@c JP
ネイティブ形式の単精度float。
@c COMMON

@item d
@c EN
A double-precision float in the native format.
@c JP
ネイティブ形式の倍精度float。
@c COMMON

@item w
@c EN
A BER compressed integer.  An unsigned integer in base 128, most
significant digit first, where the high bit is set on all but the
final (least significant) byte.  Thus any size integer can be encoded,
but the encoding is efficient and small integers don't take up any
more space than they would in normal char/short/int encodings.
@c JP
BER圧縮された整数。ベース128における符号なし整数で、最も大きな桁が
最初で、高いビットが最後の(一番小さな)バイト以外にセットされる。
したがって、どのような大きさの整数もエンコードできるが、
エンコーディングは効率的で、小さな整数は通常のchar/short/int
エンコーディングの場合よりも占有する空間が少ない。
@c COMMON

@item x
@c EN
A null byte.
@c JP
NULLバイト。
@c COMMON

@item o
@c EN
An sexp, handled with @code{read} and @code{write}.
@c JP
S式。@code{read}と@code{write}で扱われる。
@c COMMON

@end table

@c EN
If the optional keyword @var{:output} is given that port is used
instead of the current output port.  If @var{:to-string?} is given and
true, then pack accumulates and returns the output as a string.

Note that the returned string may be an incomplete string
if the packed string contains a byte sequence invalid as
a character sequence.
@c JP
オプションのキーワード@var{:output}が与えられると、
現在の出力ポートの代わりにそのポートが使われます。
@var{:to-string?}が与えられそれが真である場合は、
パックは蓄積され、その出力は文字列として返ります。
@c COMMON

@example
(pack "CCCC" '(65 66 67 68) :to-string? #t)
 @result{} "ABCD"

(pack "C/a*" '("hello") :to-string? #t)
 @result{} "\x05hello"
@end example
@end defun

@defun unpack template :key :input :from-string
@c EN
The complement of pack, unpack reads values from the current input
port assuming they've been packed according to the string template and
returns the values as a list.  unpack accepts the same format strings
as pack.  Further, the following tautology holds:
@c JP
packの逆を行うもので、unpackは現在の入力ポートから、値が文字列の
templateでパックされているものとして読み込み、その値をリストとして
返します。unpackはpackと同じフォーマット文字列を受け付けます。
また、いかなるリスト@var{x}とフォーマット文字列@var{fmt}においても、
次のようなトートロジーが維持されます。
@c COMMON

@example
(equal? x (unpack fmt :from-string (pack fmt x :to-string? #t)))
@end example

@c EN
for any list @var{x} and format string @var{fmt}.  The only exceptions
to this are when the template includes a @code{*} and when the
@code{o} template is used, since Scheme numeric literals cannot be
reliably delimited (though future versions of @code{pack} may
circumvent this by registering a new read syntax).

If the optional keyword @var{:input} is given that port is used
instead of the current input port.  If @var{:from-string} is given,
then pack reads input from that string.
@c JP
ただ一つの例外は、テンプレートが@code{*}を含み、@code{o}テンプレートが
使われている場合です。これは、Schemeの数値リテラルは確実に区切られる
ことができないからです(@code{pack}の将来のバージョンでは、
新しいread構文を登録することによってこれは回避されるでしょう)。

オプションのキーワード@var{:input}が与えられると、現在の入力ポートの
代わりにそのポートが使われます。@var{:from-string}が与えられると、
packはその文字列を入力とします。
@c COMMON

@example
(unpack "CCCC" :from-string "ABCD")
 @result{} '(65 66 67 68)

(unpack "C/a*" :from-string "\x05hello")
 @result{} '("hello")
@end example

@c EN
@emph{Note:} in the current version, @code{@@} in @code{unpack}
template has a bug and does not work as supposed.  It will
be fixed in the future version.
@c JP
@emph{註:} 現在のバージョンには、@code{unpack}のテンプレートの
@code{@@}が想定したように動かないというバグがあります。
将来のバージョンでfixされます。
@c COMMON
@end defun

@defun unpack-skip template :key :input
@c EN
unpack-skip is the same as unpack except it does not return the
values.  In some cases, particularly with fixed-size templates, this
can be much more efficient when you just want to skip over a value.
@c JP
unpack-skipは、値を返さないことを除いてunpackと同じです。
いくつかのケースでは、特に固定サイズのテンプレートを使うときには、
単に値を読み飛ばしたいときにより効率的です。
@c COMMON
@end defun

@defun make-packer template
@c EN
The low-level interface.  This function returns a dispatch closure
that can be used to pack, unpack and skip over the same cached
template.  The dispatch closure accepts symbol methods as follows:
@c JP
低レベルなインタフェースです。この関数は、pack、unpackやキャッシュ
された同じテンプレートを読み飛ばす時に使われるディスパッチクロージャを
返します。ディスパッチクロージャは、以下のようにシンボルメソッドを
受け付けます。
@c COMMON

@table @code
@item 'pack list
@c EN
pack the items in list to the current output port.
@c JP
listにあるアイテムを、現在の出力ポートへpackします。
@c COMMON

@item 'unpack
@c EN
unpack items from the current input port.
@c JP
現在の入力ポートからアイテムをunpackします。
@c COMMON

@item 'skip
@c EN
skip items from the current input port.
@c JP
現在の入力ポートからのアイテムをスキップします。
@c COMMON

@item 'packer
@c EN
return the cached 'pack closure
@c JP
キャッシュされた'packクロージャを返します。
@c COMMON

@item 'unpacker
@c EN
return the cached 'unpack closure.
@c JP
キャッシュされた'unpackクロージャを返します。
@c COMMON

@item 'skipper
@c EN
return the cached 'skip closure.
@c JP
キャッシュされた'skipクロージャを返します。
@c COMMON

@item 'length
@c EN
return the known fixed length of the template.
@c JP
テンプレートの知られている固定された長さを返します。
@c COMMON

@item 'variable-length?
@c EN
return #t if the template has variable length elements.
@c JP
テンプレートが可変長の要素を持っている場合に#tを返します。
@c COMMON
@end table
@end defun

@c ----------------------------------------------------------------------

@node Rational-less arithmetic, A common job descriptor for control modules, Packing Binary Data, Library modules - Utilities
@section @code{compat.norational} - Rational-less arithmetic
@c NODE @code{compat.norational} - 有理数のない算術演算

@deftp {Module} compat.norational
@mdindex compat.norational

@c EN
Until release 0.8.7, Gauche didn't have exact rational numbers.
It was able to read the rational number literals such as
@code{2/3}, but they are immediately coerced to inexact real
numbers (except when it represents a whole integer).
And if you divided an exact integer by another exact integer,
the result could be coerced to an inexact real if the result
wasn't a whole integer.
@c JP
リリース 0.8.7 までは、Gauche は正確な有理数をサポートしていませんでし
た。@code{2/3}のような有理数リテラルを読み込むことはできていましたが、
約分して整数になる場合をのぞいては、その場で不正確な実数に変換されてい
ました。正確な整数を正確な整数で割った場合も約分して整数になる場合をの
ぞき、結果は不正確な実数になりました。
@c COMMON

@c EN
As of 0.8.8, this is not the case anymore.  Exact division
always yields exact result, except when the divisor is zero.
@c JP
リリース 0.8.8 ではもうこのようなことはありません。正確な数同士の割り
算の結果は常に正確な数になります。ゼロで割ったときはもちろん例外です。
@c COMMON
@example
(/ 2 3)  @result{} 2/3
(/ 5)    @result{} 1/5
(/ 4 2)  @result{} 2
@end example

@c EN
This is more precise, but has one drawback: exact rational
arithmetic is much slower than the integer and inexact real
arithmetic.  If you inadvertently produce
a rational number in the early stage of calculation, and
continue to apply exact arithmetic, performance would be
degraded miserably.
@c JP
計算は正確な値でできますが、ひとつ欠点もあります。正確有理数演算は整
数演算や不正確実数同士の演算にくらべてはるかに遅いのです。意図せず、計
算の初期段階で有理数を生成してしまうとその後の計算にはすべて正確な演算
が適用されてしまい性能は悲惨なことになります。
@c COMMON

@c EN
The proper way to solve this is to insert @code{exact->inexact}
to appropriate places.  However, to ease the transition, you can
just import this module and the division @code{/} behaves
in the way it used to.
@c JP
この問題を解決する適切は方法は適切な場所に@code{exact->inexact}を挿入
することです。しかし、この変換を簡単におこなうには、このモジュールをイ
ンポートし、割り算に@code{/}を使うだけですみます。
@c COMMON

@example
(use compat.norational)

(/ 2 3)  @result{} 0.6666666666666666
(/ 5)    @result{} 0.2
(/ 4 2)  @result{} 2
@end example

@c EN
The effect is not global, but only to the modules you explicitly
import @code{compat.norational}.
@c JP
効果はグローバルには起こらず、明示的に@code{compat.norational}をインポー
トしたモジュールでのみ有効です。
@c COMMON

@c EN
This module only redefines @code{/}.  So if your code has
exact rational literals, they are treated as exact rationals
rather than coerced to inexact reals.  You should prefix
rational literals with @code{#i} to force Gauche to coerce
them to inexact reals:
@c JP
このモジュールは@code{/}を再定義しているだけです。したがって、コードに
正確な有理数のリテラルが含まれていても、それは不正確な実数に変換される
ことはなく、正確な有理数としてあつかわれます。Gaucheに不正確な実数とし
て有理数リテラルを扱わせるには、@code{#i}という接頭辞を追加しなければ
なりません。
@c COMMON
@example
gosh> 1/3
1/3
gosh> #i1/3
0.3333333333333333
@end example
@end deftp

@c ----------------------------------------------------------------------
@node A common job descriptor for control modules, Thread pools, Rational-less arithmetic, Library modules - Utilities
@section @code{control.job} - A common job descriptor for control modules

@deftp {Module} control.job
@mdindex control.job
This module provides a @code{job} record type, a lightweight
structure to be used in the control flow subsystems
(@code{control.*} modules).
Currently the only user is @code{control.thread-pool}, but
some other modules are planned to use @code{job} records.

A @code{job} record may be returned to an application
by other @code{control.*} modules so that the application
can keep track of the job.  It's not meant for
general use, however.   An application isn't supposed to
create a new job, or to modify its content; it can just query
the job's properties.

In this section we only describe procedures an application
needs to know.  The interface for control subsystems is still
fluid and may be changed as more subsystems are developed.

Different control flow subsystems may use job structure differently.
This section only describes the common properties.  Check the
individual control flow module to know how to handle returned job
objects.
@end deftp

@deftp {Record type} job
A record type denotes the job.  Applications should treat it
as an opaque structure.
@end deftp

@defun job? obj
Returns @code{#t} iff @var{obj} is a job record, @code{#f} otherwise.
@end defun

@defun job-status job
Returns the status of the job.  It may be either one of the followings.
@table @code
@item #f
Newborn or orphaned job.  Usually an application won't see a job
in this status.
@item acknowledged
A job is recognized by a control flow library, but haven't yet
been run.
@item running
A job is being processed.
@item done
A job is finished.  An application can retrieve its result
by @code{job-result}.
@item error
A job is terminated by an error.  An application can retrieve the
error causing condition by @code{job-result}.
@item killed
A job is killed by external force.  An application can retrieve the
reason of kill (which is specific to a particular control flow
subsystem) by @code{job-result}.
@end table
@end defun

@defun job-result job
If the job is in @code{done} status, it returns the result of the job.
If the job is in @code{error} status, it returns the condition object
that describes the error.
If the job is in @code{killed} status, it returns an object describing
the reason of kill.  The details of the object depends on a particular
control flow library.
Calling @code{job-result} on a job in any other status may return
anything; you can't rely on the result.
@end defun

@defun job-wait job :optional timeout timeout-val
Suspends the calling thread until the job becomes either
@code{done}, @code{error} or @code{killed} status.  If the job
is already in one of those status, it returns immediately.
Returns job's status.

If @var{timeout} is given and not @code{#f}, it must be
a valid timeout spec (a @code{<time>} object that represents
an absolute time point, or a real number that represents a
relative time in seconds.)  The meaning of @var{timeout} is
the same as in @code{mutex-unlock!} (@xref{Synchronization primitives}).
Once the timeout reaches, @code{job-wait} returns no matter
how the job's status is, and returns the value specified
to @var{timeout-val}, which defaults to @code{#f}.

Depending on the control flow subsystem, jobs created by it
may not be waitable; check out each subsystem's documentation for the details.
@end defun

@defun job-acknowledge-time job
@defunx job-start-time job
@defunx job-finish-time job
If the control flow subsystem keeps track of timestamps,
these procedure returns the time (in @code{<time>} objects)
when the job is acknowledged, started and finished (either normally,
or abnormally by an error or by being killed).  If the job hasn't
reached to certain status, @code{#f} is returned instead.

If the subsystem does not trak timestamps, these procedures
always returns @code{#f}.
@end defun

@c ----------------------------------------------------------------------
@node Thread pools, Password hashing, A common job descriptor for control modules, Library modules - Utilities
@section @code{control.thread-pool} - Thread pools
@c NODE スレッドプール, @code{control.thread-pool} - スレッドプール

@deftp {Module} control.thread-pool
@mdindex control.thread-pool
@c EN
Provides thread pools.  Only available when Gauche is compiled
with pthreads support.
@c JP
スレッドプールを提供します。Gaucheがpthreadサポート付きでコンパイルされている
場合にのみ利用可能です。
@c COMMON
@end deftp

@deftp {Class} <thread-pool>
@clindex thread-pool
@c EN
A class for thread pool objects.   It maintains a set of worker threads, and
let them work on the jobs you ask to do asynchronously.

Currently the size of pool (number of threads) is fixed
and you have to specify it when creating a pool.
In future we might add a feature to grow or shrink the pool.

You can also set maximum backlog of the job queue.  You cannot
put a job when the queue already reaches the max length (see
@code{add-job!} below).
@c JP
スレッドプールオブジェクトのクラスです。ワーカースレッドのセットを保持し、
投入されたジョブを非同期に実行します。

現在の実装では、プールのサイズ (スレッド数) は固定で、プール作成時に
指定しなければなりません。いずれスレッド数を動的に増減させる機能を
追加する予定です。

また、ジョブのキューの最大長を指定することもできます。ジョブのキューが
一杯になると、空きができるまでは新たなジョブを投入することができなくなります
(下記の@code{add-job!}参照)。
@c COMMON
@end deftp


@deftp {Condition type} <thread-pool-shut-down>
@c EN
A condition indicating that a thread pool is already shut down
by @code{terminate-all!} and no longer accepting new jobs.
Inherits @code{<error>}.  The following slot is provided.
@c JP
スレッドプールが@code{terminate-all!}によって停止され、
新規のジョブを受け付けていないことを示すコンディションです。
@code{<error>}を継承します。次のスロットが提供されます。
@c COMMON

@defivar <thread-pool-shut-down> pool
@c EN
The thread pool object that caused the condition.
@c JP
例外の原因となったスレッドプールオブジェクト
@c COMMON
@end defivar
@end deftp

@defun make-thread-pool size :key (max-backlog 0)
@c EN
Creates a new thread pool of size @var{size} (the number of
worker threads).  Optionally you can give a nonnegative integer
to the maximum backlog; 0 means unlimited.
@c JP
大きさ(ワーカースレッド数)@var{size}のスレッドプールを作成して返します。
省略可能引数@var{max-backlog}によってジョブのバックログの最大値を
指定することもできます。0を与えた場合(デフォルト)は無制限です。
@c COMMON
@end defun

@defun thread-pool-results pool
@c EN
When you put a job to a thread pool, you can specify
whether you need to check its result or not.  If you say you need
a result, the terminated job is queued to a @emph{result queue},
an @code{<mt-queue>} object, in the pool.
This procedure returns the pool's result queue.
@xref{Queue}, for the details of @code{<mt-queue>}.
@c JP
ジョブをスレッドプールに投入する際に、ジョブの結果を知る必要があるかどうかを
指定することができます。結果を要求した場合は、終了したジョブレコードが
プール中の結果キュー(@code{<mt-queue>}オブジェクト)にエンキューされます。
この手続きは、プールの結果キューを返します。
@code{<mt-queue>}の詳細については@ref{Queue}を参照してください。
@c COMMON
@end defun

@defun thread-pool-shut-down? pool
@c EN
Returns @code{#t} if the thread pool is shut down and no longer
accepting new jobs, or @code{#f} otherwise.
@c JP
スレッドプールが停止され、新規のジョブを受け付けていない場合に@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun add-job! pool thunk :optional (need-result #f) (timeout #f)
@c EN
Add a @var{thunk} to be executed in the thread pool @var{pool}.
Returns a @code{job} record (@xref{A common job descriptor for control modules}).
@c JP
@var{thunk}がスレッドプール@var{pool}のスレッドにより実行されるように設定します。
@code{job}レコードを返します。
(@ref{A common job descriptor for control modules}参照)。
@c COMMON

@c EN
The returned job record is not waitable; if you need to track
its result, you have to give a true value to @var{need-result}
argument.  Then when the job is terminated (either normally or
abnormally) the job is queued to the @code{result-queue} of
the pool, and you can check the queue.   If you don't pass
a true value to @var{need-result}, the job won't be queued
to @code{result-queue} even it is terminated.
@c JP
返される@code{job}レコードはwaitableにはなっていません。結果を知る必要が
ある場合は、省略可能引数@var{need-result}に真の値を渡してください。
そうするとジョブが終了した時点 (正常終了でも異常終了でも) で、
@code{job}レコードがスレッドプールの@code{result-queue}に
入るので、そのキューから結果を受け取ることができます。
@var{need-result}を省略したり偽値を渡した場合は、ジョブが終了しても
@code{job}レコードは@code{result-queue}に入れられません。
@c COMMON

@c EN
The returned job is timestamped.  You can examine acknowledged
time, start time and finish time of the job (if the job hasn't
been started and/or finished, the corresponding timestamp fields
are @code{#f}.)  It's sometimes
handy to find out how long the job was waiting in the
queue and how long it took to run.
@c JP
返される@code{job}レコードにはタイムスタンプが付加され、
受付時間、実行開始時間、実行終了時間が記録されます。
(ジョブがまだ実行されていなかったり、終了されていない場合は、対応する
タイムスタンプは@code{#f}になっています)。
ジョブがどのくらいキューの中で待たされ、どのくらい実行にかかったかを
知るのに便利でしょう。
@c COMMON

@c EN
If the pool has positive @code{max-backlog} value, and it
already has that many jobs to be waiting, then @code{add-job!}
blocks until some jobs are start being executed.
You can give a real number in seconds, or a @code{<time>} object
as an absolute point of time, to the @var{timeout} argument 
to set the time limit of blocking.  If timeout is reached,
@code{add-job!} returns @code{#f} without creating any job.
Omitting @var{timeout}
or giving @code{#f} to it sets no timeout.
@c JP
スレッドプールが非負の@code{max-backlog}値を持ち、
既にその数だけジョブが待ち行列に入っている場合は、
@code{add-job!}は待ち行列に空きができるまでブロックします。
@var{timeout}引数に、実数値の秒数、あるいは絶対時刻を指定する@code{<time>}
オブジェクトを渡すことでタイムアウトを指定できます。タイムアウトに
達した場合は、@code{add-job!}はジョブを作らずに@code{#f}を返します。
@var{timeout}引数を省略するか、@code{#f}を渡した場合はタイムアウトが設定されません。
@c COMMON

@c EN
(Note: This behavior is different from 0.9.1, in which @code{add-job!}
didn't take the timeout argument and always behaved as if zero 
timeout value was given.  To achieve the same behavior, you have
to give 0 to the @var{timeout} argument explicitly.)
@c JP
(註: この動作は0.9.1から変更されました。0.9.1では、@code{add-job!}は
タイムアウト引数を取らず、常にタイムアウトに0秒が指定されたかのように
振る舞っていました。現在のバージョンで同じ動作をさせるには、@var{timeout}引数
に0を明示的に渡します。)
@c COMMON

@c EN
If the thread pool is shut down, this procedure
raises @code{<thread-pool-shut-down>} condition.
@c JP
スレッドプールが停止していた場合、この手続きは
@code{<thread-pool-shut-down>}コンディションを投げます。
@c COMMON
@end defun

@defun wait-all pool :optional (timeout #f) (check-interval #e5e8)
@c EN
Wait for the job queue to be empty and
all worker threads to finish.  It is done by polling the
pool's status in every @var{check-interval} nanoseconds.
Returns @code{#t} if all jobs are finished.

You can give a real number in seconds, or a @code{<time>} object
as an absolute point of time, in @var{timeout} optional argument.
When timeout is reached, @code{wait-all} returns @code{#f}.
@c JP
ジョブ待ち行列が空になり、すべての実行中のジョブも終了するまで待ちます。
終了待ちは@var{check-interval}にナノ秒で指定される間隔でスレッドプールを
ポールすることで行われます。すべてのジョブが終了したら@code{#t}を返します。

秒数を表す実数か、絶対時刻を表す@code{<time>}オブジェクトを@var{timeout}
引数に渡すことで、タイムアウトを指定できます。タイムアウトに達した場合は、
@code{wait-all}は@code{#f}を返します。
@c COMMON
@end defun

@defun terminate-all! pool :key (force-timeout #f) (cancel-queued-jobs #f)
@c EN
Wait for all the queued jobs to be finished, then ask all threads
to terminate.  After calling this procedure, the pool no longer
accepts new jobs.  Calling @code{add-job!} on this module would
raise a @code{<thread-pool-shut-down>} condition.
This is intended to be called when shutting down the application.

By default, this procedure first waits for all queued jobs
to be handled, then tries to terminate threads gracefully.

Giving a true value to the @var{cancel-queued-jobs} argument
immediately cancels queued but not started jobs; the status
of such jobs is set @code{killed}.
It does not cancels already started jobs, though.

If you want to cancel already started jobs, 
you can give a timeout value (either @code{<time>} object to
specify absolute point of time, or a real number indicating
relative time in seconds) to the @var{force-timeout} argument.
Once timeout is reached, it forcefully terminates the threads
and the jobs handled at that time are also killed.

Forcing termination of threads is an extreme measure; the terminated
thread may not have a chance to clean up properly.  So it is usually
better to give some time for the thread to finish the executing jobs.
@c JP
投入されたジョブがすべて終了するのを待ち、すべてのスレッドを終了させます。
ひとたびこの手続きを呼ぶと、スレッドプール@var{pool}は新規のジョブを受けつけ
ません。この状態のスレッドプールに対して@code{add-job!}を呼ぶと
@code{<thread-pool-shut-down>}コンディションが投げられます。
この手続きはアプリケーションのシャットダウン時などに呼ばれることを意図しています。

デフォルトでは、この手続きはまずキューに既に投入されたジョブが全て処理されるのを
待ち、それからスレッドを穏やかに終了させます。

真の値を@var{cancel-queued-jobs}引数に与えると、キューに入っているが
まだ開始されていないジョブは直ちにキャンセルされます。それらのジョブの
ステータスには@code{killed}がセットされます。
ただし、既に開始されたジョブについてはキャンセルされません。

既に開始されたジョブも中断したい場合は、
タイムアウト値(秒数を表す実数か、絶対時刻を表す@code{<time>}オブジェクト)を
@var{force-timeout}引数に渡します。
タイムアウトに達した時点で残っているスレッドは強制終了され、実行中のジョブも
キャンセルされます。

スレッドの強制終了は極端な処置です。終了されるスレッドは、適切なクリーンアップを
行う機会も与えられないかもしれません。したがって通常は、
スレッドが処理中のジョブを終わらせるための適切な時間的猶予を与えるのが良いでしょう。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Password hashing, Database independent access layer, Thread pools, Library modules - Utilities
@section @code{crypt.bcrypt} - Password hashing
@c NODE パスワードハッシュ, @code{crypt.bcrypt} - パスワードハッシュ

@deftp {Module} crypt.bcrypt
@mdindex crypt.bcrypt
@c EN
This module implements a password hashing algorithm using blowfish,
and compatible to OpenBSD's bcrypt algorithm (version 2a).
@c JP
このモジュールは、blowfishを使ったパスワードハッシュアルゴリズムを実装します。
OpenBSDのbcryptアルゴリズム(version 2a)と互換です。
@c COMMON

@c EN
The typical usage of this module is simple enough.
To get a new password hash value (e.g. for a new user), pass the
password string to @code{bcrypt-hashpw} as the only argument:
@c JP
典型的な使い方は非常にシンプルです。新しいパスワードハッシュ値を
得たい場合 (例えば新しいユーザのために、など) は、パスワード文字列を
唯一の引数として@code{bcrypt-hashpw}を呼び出してください。
@c COMMON

@example
(bcrypt-hashpw @var{password})
  @result{} @r{hashed-string}
@end example

@c EN
The routine automatically adds a salt value.  The returned hash
string can be stored in the user database.  To check if the given
password matches the stored one, pass the
hashed string as the second argument of @code{bcrypt-hashpw} to
check the password.
@c JP
このルーチンは自動的にソルト値を付加します。戻り値の文字列はそのままユーザ
データベースに格納できます。与えられたパスワードがハッシュ値に一致するか
どうかを調べるには、ハッシュ値そのものを第二引数として@code{bcrypt-hashpw}に
渡します。
@c COMMON

@example
(bcrypt-hashpw @var{password} @var{hashed-string}) 
  @result{} @r{hashed-string}
@end example

@c EN
If the given password is correct, the returned value should
exactly matches @var{hash-string}.
@c JP
パスワードが正しければ、戻り値は@var{hashed-string}と完全に一致するはずです。
@c COMMON
@end deftp

@defun bcrypt-hashpw password :optional setting
@c EN
Calculates a hash value of @var{password}, using the salt value
and parameters included in @var{setting}.  If @var{setting} is
omitted, a suitable default settings and random salt value is
chosen automatically.

The returned hash value contains the salt value and parameters,
and can be used as @var{setting}.  So, to check the password
against existing hash value, just pass the hash value to
@var{setting}; if the password is correct, the returned hash value
should match the one you passed in.

The bcrypt algorithm supports up to 72 octets for the password.

To tweak parameters when you calculate a new hash value,
use @code{bcrypt-gensalt} below to get the initial @var{setting}
value.
@c JP
@var{password}のハッシュ値を計算します。@var{setting}は
ソルト値とパラメータを指定する文字列です。@var{setting}が
省略された場合は、適切なデフォルトのパラメータとランダムなソルト値が
自動的に選択されます。

戻り値のハッシュ値文字列にはソルト値とパラメータが含まれているので、
それを再び@var{setting}に渡すことができます。したがって、パスワードを
既存のハッシュ値に一致するかチェックしたい場合は、ハッシュ値を@var{setting}に渡し、
戻ってきた文字列が渡したハッシュ値と一致するかを見れば良いことになります。

bcryptアルゴリズムは最大72オクテットまでのパスワードを使えます。

新しいハッシュ値を計算する際にパラメータを指定したい場合は、次に説明する
@code{bcrypt-gensalt}を使うと@var{setting}に使える文字列を得ることができます。
@c COMMON
@end defun

@defun bcrypt-gensalt &key prefix count entropy-source
@c EN
Returns a string that contains given parameters and suitable to
pass to the @var{setting} argument of @code{bcrypt-hashpw}.

The @var{prefix} argument specifies the version/scheme of
password hashing.  Currently only @code{$2a$} is supported,
which means the blowfish algorithm compatible to bcrypt.

The @var{count} arugment specifies the amount of iterations;
the larger the value is, the more time is required to calculate
the hash value.  Note that for the password hashing, taking more
time is actually a good thing, for it works against the dictionary attack.
For normal password checking you need to run the hash routine only 
once per login, so it doesn't matter if the calculation takes a fraction
of second.
The bcrypt algorithm iterates @code{(expt 2 @var{count})} times.

The @var{entropy-source} argument is a @code{u8vector} to feed
a random bytes.  For bcrypt algorithm it must be at least 16 octet long.
@c JP
与えられたパラメータを折り込んだ、
@code{bcrypt-hashpw}の@var{setting}引数に使える文字列を返します。

@var{prefix}引数はハッシュ関数およびそのバージョンを指定する文字列です。
現在のところ、@code{bcrypt}互換である@code{$2a$}のみがサポートされています。

@var{count}引数はハッシュの繰り返し回数に関係します。大きな値を指定すれば、
ハッシュ値の計算により長い時間がかかります。パスワードハッシュにおいては、
時間をかけた方が良いことに注意してください。一回のハッシュの時間が長くなれば
辞書攻撃への防御になります。一方で、通常のパスワードチェックでは
ログインの度にたかだか一回しはハッシュ関数を呼ばないので、それがたとえコンマ数秒
かかったとしてもたいした負荷ではありません。
bcryptアルゴリズムでは、@code{(expt 2 @var{count})}回ハッシュが繰り返されます。

@var{entropy-source}引数はランダムなバイト列を格納した@code{u8vector}です。
bcryptアルゴリズムでは少なくとも16バイトの長さが必要です。
@c COMMON
@end defun

@c ----------------------------------------------------------------------

@node Database independent access layer, Generic DBM interface, Password hashing, Library modules - Utilities
@section @code{dbi} - Database independent access layer
@c NODE @code{dbi} - データベース非依存アクセス層

@deftp {Module} dbi
@mdindex dbi
@c EN
This module provides the unified interface to access various 
relational database systems (RDBMS).  The operations specific
to individual database systems are packaged
in database driver (DBD) modules, which is usually loaded
implicitly by DBI layer.
@c JP
このモジュールはさまざまなリレーショナルデータベースシステム(RDBMS)に
アクセスするための統一されたインタフェースを提供します。個々のデータベー
スシステムに特有の操作についてはデータベースドライバ(DBD)モジュールに
パッケージされています。DBDのモジュールは通常暗黙裏にDBIの層からロード
されます。
@c COMMON

@c EN
The module is strongly influenced by Perl's DBI/DBD architecture.
If you have used Perl DBI, it would be easy to use this module.
@c JP
このモジュールは Perl の DBI/DBD アーキテクチャに強く影響を受けていま
す。Perl DBIを使った経験があるなら、このモジュールを使うのはたやすいで
しょう。
@c COMMON
@end deftp

@c EN
It's better to look at the example.  This is a simple outline
of accessing a database by @code{dbi} module:
@c JP
まず例を見るほうがよいでしょう。以下は@code{dbi}モジュールを使ったデー
タベースアクセス例の概要です。
@c COMMON

@example
(guard (e ((<dbi-error> e)
           ;; handle error
           ))
  (let* ((conn   (dbi-connect "dbi:mysql:test;host=dbhost"))
         (query  (dbi-prepare conn
                   "SELECT id, name FROM users WHERE department = ?"))
         (result (dbi-execute query "R&D"))
         (getter (relation-accessor result)))
    (map (lambda (row)
           (list (getter row "id")
                 (getter row "name")))
         result)))
@end example

@c EN
There's nothing specific to the underlying database system
except the argument @code{"dbi:mysql:test;host=dbhost"}
passed to @code{dbi-connect}, from which @code{dbi} module
figures out that it is an access to @code{mysql} database,
loads @code{dbd.mysql} module, and let it handle the mysql-specific
stuff.  If you want to use whatever database system, you can just
pass @code{"dbi:@var{whatever}:@var{parameter}"} to @code{dbi-connect}
instead, and everything stays the same as far as you have
@code{dbd.whatever} installed in your system.
@c JP
@code{dbi-connect}にわたす、@code{"dbi:mysql:test;host=dbhost"}引数以
外は使用するデータベースシステムに依存する部分はありません。この引数に
より、@code{dbi}モジュールはこのアクセスが@code{mysql}データベースに対
するものであると判断します。そして、mysql-特有の手続を扱うようにします。
別のデータベースシステムwhateverを使いたいのであれば、単に
@code{"dbi:@var{whatever}:@var{parameter}"}を@code{dbi-connect}に渡せ
ばよく、@code{dbd.whatever}がシステムにインストールされていれば同じよ
うにできます。
@c COMMON

@c EN
A query to the database can be created by @code{dbi-prepare}.
You can issue the query by @code{dbi-execute}.  This two-phase
approach allows you to create a prepared query, which is a kind of
parameterized SQL statement.  In the above example the query
takes one parameter, denoted as @code{'?'} in the SQL.
The actual value is given in @code{dbi-execute}.  When you
issue similar queries a lot, creating a prepared query and
execute it with different parameters may give you performance gain.
Also the parameter is automatically quoted.
@c JP
データベースに対するクエリは@code{dbi-prepare}を使って作成します。
クエリの発行は@code{dbi-execute}で行います。このような2つのフェーズを
使うことで、パラメータ化されたSQL文の一種であるプリペアドクエリを
作ることができます。上の例ではクエリはSQL文の中で@code{'?'}で表現され
ている部分に、ひとつの引数をわりあてます。実引数の値は
@code{dbi-execute}で設定されます。類似のクエリを大量に発行するような場
合にはプリペアドクエリをひとつ生成し、それにさまざまなパラメータを渡し
て実行するとパフォーマンスがかせげます。このパラメータは自動的にクォー
トされます。
@c COMMON

@c EN
When the query is a @code{SELECT} statement,
its result is returned as a collection that implements 
the relation protocol.  See @ref{Collection framework}
and @ref{Relation framework} for the details.
@c JP
クエリが@code{SELECT}文の場合、その結果は関係プロトコルを実装するコレ
クションとして返されます。詳細は@ref{Collection framework}および
@ref{Relation framework}を見てください。
@c COMMON

@c EN
The outermost @code{guard} is to catch errors.  The @code{dbi} related
errors are supposed to inherit @code{<dbi-error>} condition.
There are a few specific errors defined in @code{dbi} module.
A specific @code{dbd} layer may define more specific errors.
@c JP
いちばん外側にある@code{guard}はエラーを捕捉するためのものです。
@code{dbi}に関連したエラーは@code{<dbi-error>}コンディションを継承して
いるものと見なされます。いくつかの特有のエラーは@code{dbi}モジュールで
定義されています。特定の@code{dbd}層はさらに固有のエラーを定義していま
す。
@c COMMON

@c EN
In the next section we describe user-level API, that is,
the procedures you need to concern when you're using @code{dbi}.
The following section is for the driver API, which you need to use
to write a specific @code{dbd} driver to make it work with @code{dbi}
framework.
@c JP
次節ではユーザレベルのAPIについて説明します。すなわち、@code{dbi}を使
う際に必要となる手続に関する説明です。そのあとのセクションではドライバ
APIを説明をします。すなわち特定の@code{dbd}ドライバを@code{dbi}フレー
ムワークで使えるようにするために使うAPIの説明です。
@c COMMON

@menu
* DBI user API::                
* Writing drivers for DBI::     
@end menu

@node DBI user API, Writing drivers for DBI, Database independent access layer, Database independent access layer
@subsection DBI user API
@c NODE DBIのユーザAPI

@c EN
@subsubheading DBI Conditions
@c JP
@subsubheading DBIのコンディション
@c COMMON

@c EN
There are several predefined conditions @code{dbi} API may throw.
See @ref{Exceptions} for the details of conditions.
@c JP
@code{dbi} API が投げる可能性のあるコンディションがいくつか定義されて
います。コンディションの詳細については@ref{Exceptions}を見てください。
@c COMMON

@deftp {Condition Type} <dbi-error>
@c EN
The base class of @code{dbi}-related conditions.  Inherits @code{<error>}.
@c JP
@code{dbi}-関連のコンディションのベースクラス。@code{<error>}を継承し
ています。
@c COMMON
@end deftp

@deftp {Condition Type} <dbi-nonexistent-driver-error>
@c EN
This condition is thrown by @code{dbi-connect} when it cannot
find the specified driver.  Inherits @code{<dbi-error>}.
@c JP
@code{dbi-connect}は指定されたドライバが見つからない場合にこのコンディ
ションを投げます。@code{<dbi-error>}を継承しています。
@c COMMON

@defivar <dbi-nonexistent-driver-error> driver-name
@c EN
Holds the requested driver name as a string.
@c JP
要求されたドライバの名前を文字列として保持している。
@c COMMON
@end defivar
@end deftp

@deftp {Condition Type} <dbi-unsupported-error>
@c EN
This condition is thrown when the called method isn't supported 
by the underlying driver.  Inherits @code{<dbi-error>}.
@c JP
呼び出されたメソッドが基盤となるドライバでサポートされていない場合、こ
のコンディションが投げられます。@code{<dbi-error>}を継承しています。
@c COMMON
@end deftp

@deftp {Condition Type} <dbi-parameter-error>
@c EN
This condition is thrown when the number of parameters given to
the prepared query doesn't match the ones in the prepared statement.
@c JP
プリペアドクエリへ渡されたパラメータの数がプリペアドステートメントの中
のものと一致しないとき、このコンディションが投げられます。
@c COMMON
@end deftp

@c EN
Besides these errors, if a driver relies on @code{dbi} to
parse the prepared SQL statement, @code{<sql-parse-error>} may 
be thrown if an invalid SQL statement is passed to @code{dbi-prepare}.
(@xref{SQL parsing and construction}).
@c JP
上の3つのエラー以外に、@code{dbi}がプリペアドSQL文を構文解析するのにド
ライバを利用す場合、不正なSQL文が@code{dbi-prepare}に渡されると、
@code{<sql-parse-error>}が投げられます
(@ref{SQL parsing and construction}参照)。
@c COMMON

@c EN
@subsubheading Connecting to the database
@c JP
@subsubheading データベースへの接続
@c COMMON

@defun dbi-connect dsn :key username password
@c EN
Connect to a database using a data source specified by @var{dsn}
(data source name).  @var{Dsn} is a string with the following syntax:
@c JP
@var{dsn}(データソース名)で指定されたデータソースを使ってデータベース
に接続します。@var{dsn}は以下の構文をもつ文字列です。
@c COMMON
@example
dbi:@var{driver}:@var{options}
@end example

@c EN
@var{Driver} part names a specific driver.  You need to have the
corresponding driver module, @code{dbd.@var{driver}}, installed in
your system.  For example, if @var{dsn} begins with @code{"dbi:mysql:"},
@code{dbi-connect} tries to load @code{dbd.mysql}.
@c JP
@var{driver}は特定のドライバ名です。対応するドライバモジュールがなけれ
ばなりません。すなわち、@code{dbd.@var{driver}}がシステムにインストー
ルされていなければなりません。たとえば、@var{dsn}が@code{"dbi:mysql:"}
ではじまるとすると、@code{dbi-connect}は@code{dbd.mysql}をロードしよう
とします。 
@c COMMON

@c EN
Interpretation of the @var{options} part is up to the driver.
Usually it is in the form of @code{key1=value1;key2=value2;...},
but some driver may interpret it differently.  For example,
@code{mysql} driver allows you to specify a database name
at the beginning of @var{options}.   You have to check out
the document of each driver for the exact specification of
@var{options}.
@c JP
@var{options}部分の解釈はドライバに依存します。通常この部分のフォーマッ
トは@code{key1=value1;key2=value2;...}のようになっていますが、ドライバ
によっては別の解釈になります。たとえば、@code{mysql}ドライバでは、
@var{options}の最初の部分でデータベース名を指定することができます。
@var{options}の正確な仕様については各ドライバのドキュメントをチェック
してください。
@c COMMON

@c EN
The keyword arguments gives extra information required for
connection.  The @var{username} and @var{password} are commonly
supported arguments.  The driver may recognize more keyword arguments.
@c JP
接続のために必要な追加情報はキーワード引数であたえます。
@var{username}および@var{password}は共通でサポートされている引数です。
ドライバは他にもキーワード引数を認識します。
@c COMMON

@c EN
If a connection to the database is successfully established,
a connection object (an instance of a subclass of @code{<dbi-connection>})
is returned.  Otherwise, an error is signalled.
@c JP
データベースへの接続が成功したら、コネクションオブジェクト
(@code{<dbi-connection>}のサブクラスのインスタンス)が返ります。さもな
ければ、エラーがあがります。
@c COMMON
@end defun

@deftp {Class} <dbi-connection>
@c EN
The base class of a connection to a database system.
Each driver defines a subclass of this to keep information about
database-specific connections.
@c JP
データベースシステムへの接続のベースクラス。各ドライバはこのクラスのサ
ブクラスを定義し、これにデータベース特有のコネクションに関する情報を持
たせます。
@c COMMON
@end deftp

@deffn {Method} dbi-open? (c <dbi-connection>)
@c EN
Queries whether a connection to the database is still open (active).
@c JP
データベースへの接続がオープン状態(アクティブ状態)にあるかどうかを確か
めます。
@c COMMON
@end deffn

@deffn {Method} dbi-close (c <dbi-connection>)
@c EN
Closes a connection to the database.  This causes releasing resources
related to this connection.   Once closed, @var{c} cannot
be used for any dbi operations (except passing to @code{dbi-open?}).
Calling @code{dbi-close} on an already closed connection has no effect.
@c JP
データベースへの接続を閉じます。これによりこの接続に関連付けられたリソー
スが解放されます。いったん閉じた@var{c}に対してはどのようなdbi操作もで
きません。(@code{dbi-open?}だけは例外)。すでに閉じられたコネクションに
対して@code{dbi-close}を呼んでもなにも起りません。
@c COMMON

@c EN
Although a driver usually closes a connection when @code{<dbi-connection>}
object is garbage-collected, it is not a good idea to rely on that,
since the timing of GC is unpredictable.  The user program must make
sure that it calls @code{dbi-close} at a proper moment.
@c JP
ドライバは通常@code{<dbi-connection>}がガベージコレクションされたとき
にコネクションを閉じますが、このことを期待したコードを書くのはいただけ
ません。GCのタイミングというのは予測不可能だからです。ユーザプログラム
は適切なタイミングで@code{dbi-close}を呼ぶようにすべきです。
@c COMMON
@end deffn

@defun dbi-list-drivers
@c EN
Returns a list of module names of known drivers.
@c JP
解っているドライバのモジュール名のリストを返します。
@c COMMON
@end defun

@deftp {Class} <dbi-driver>
@c EN
The base class of a driver.  You usually don't need to see this
as far as you're using the high-level @code{dbi} API.
@c JP
ドライバのベースクラス。高レベルの@code{dbi} APIを使うかぎり、これが必
要になることはありません。
@c COMMON
@end deftp

@defun dbi-make-driver driver-name
@c EN
This is a low-level function called from @code{dbi-connect} method,
and usually a user doesn't need to call it.
@c JP
@code{dbi-connect}から呼ばれる低レベル関数、通常この関数を呼ぶ必要はあ
りません。
@c COMMON

@c EN
Loads a driver module specified by @var{driver-name}, and
instantiate the driver class and returns it.
@c JP
@var{driver-name}で指定されたドライバモジュールをロードし、当該のドラ
イバクラスのインスタンスを生成してそれを返します。
@c COMMON
@end defun

@c EN
@subsubheading Preparing and issuing queries
@c JP
@subsubheading クエリの準備と発行
@c COMMON

@deffn {Method} dbi-prepare conn sql :key pass-through @dots{}
@c EN
From a string representation of SQL statement @var{sql},
creates and returns a query object (an instance of @code{<dbi-query>}
or its subclass) for the database connection @code{conn}
@c JP
SQL文の文字列表現@var{sql}からデータベースコネクション@code{conn}用の
クエリオブジェクト(@code{<dbi-query>}のインスタンスもしくはそのサブク
ラスのインスタンス)を生成してそれを返します。
@c COMMON

@c EN
@var{Sql} may contain parameter slots, denoted by @code{?}.
@c JP
@var{sql}は@code{?}であらわされているパラメータスロットを持ちます。
@c COMMON
@example
(dbi-prepare conn "insert into tab (col1, col2) values (?, ?)")

(dbi-prepare conn "select * from tab where col1 = ?")
@end example

@c EN
They will be filled when you actually issue the query by
@code{dbi-execute}.
There are some advantages of using parameter
slots: (1) The necessary quoting is done automatically.
You don't need to concern about security holes caused by
improper quoting, for example.
(2) Some drivers support a feature to send the template SQL
statement to the server at the preparation stage, and send
only the parameter values at the execution stage.  It would be
more efficient if you issue similar queries lots of time.
@c JP
これらのスロットは@code{dbi-execute}を使って実際にクエリを発行したとき
に埋められます。パラメータスロットを使うのは以下の利点があるからです。
(1) クォートが自動的にほどこされます。不適切なクォートによるセキュリティ
ホールを気にする必要はありません。
(2) いくつかのドライバでは準備の段階でサーバへテンプレートSQL文を送る
機能がサポートされていて、実行段階ではパラメータを送るだけで済みます。
これは似たようなクエリを大量に一度に発行するときには効率のよいやりかた
です。
@c COMMON

@c EN
If the backend does't support prepared statements (SQL templates
having @code{?} parameters), the driver may use @code{text.sql}
module to parse @var{sql}.  It may raise @code{<sql-parse-error>}
condition if the given SQL is not well formed.
@c JP
バックエンドでプリペアド文がサポートされていない場合(でSQLテンプレー
トが@code{?}パラメータを持つ場合)、ドライバは@var{sql}を解析するのに
@code{text.sql}モジュールを使います。与えられたSQL文が正しい構文でなけ
れば、@code{<sql-parse-error>}コンディションが発生します。
@c COMMON

@c EN
You may pass a true value to the keyword argument @var{pass-through}
to suppress interpretation of SQL and pass @var{sql} as-is to the
back end database system.  It is useful if the back-end supports
extension of SQL which @code{text.sql} doesn't understand.
@c JP
キーワード引数@var{pass-through}に真の値を渡して、SQLの解釈を抑制し、
@var{sql}をそのままバックエンドのデータベースシステムに渡すことができ
ます。@code{text.sql}で理解できないようなSQLの拡張をバックエンドがサポー
トしている場合に役立ちます。
@c COMMON

@c EN
If the driver lets prepared statement handled in back-end,
without using @code{text.sql}, the @code{pass-through} argument
may be ignored.
The driver may also take other keyword arguments.  Check out
the documentation of individual drivers.
@c JP
ドライバがプリペアド文を@code{text.sql}抜きでバックエンドに処理させた
場合、@code{pass-through}引数は無視されます。ドライバは他のキーワード
引数を取ることもあります。詳細はそれぞれのドライバのドキュメントを参照
してください。
@c COMMON

@c EN
@emph{Note:} Case folding of SQL statement
is implementation dependent.  Some DBMS may treat table
names and column names in case insensitive way, while
others do in case sensitive way.  To write a portable
SQL statement, make them quoted identifiers, that is,
always surround names by double quotes.
@c JP
@emph{注意}：SQL文のケース畳み込みは実装依存です。DBMSのなかにはテーブ
ル名やカラム名は大文字小文字の区別をしないものもあり、一方で区別するも
のもあります。ポータブルなSQL文を書きたいのなら、識別子をクォートしま
しょう。すなわち常に名前をダブルクォートで囲むようにします。
@c COMMON
@end deffn

@deftp {Class} <dbi-query>
@c EN
Holds information about prepared query, created by @code{dbi-prepare}.
The following slots are defined.
@c JP
@code{dbi-prepare}によって作成されたプリペアドクエリに関する情報を保持
します。以下のスロットが定義されています。
@c COMMON

@defivar <dbi-query> connection
@c EN
Contains the @code{<dbi-connection>} object.
@c JP
@code{<dbi-connection>}オブジェクトを含みます。
@c COMMON
@end defivar

@defivar <dbi-query> prepared
@c EN
If the driver prepares query by itself, this slot may contain
a prepared statement.  It is up to each driver how to use
this slot, so the client shouldn't rely on its value.
@c JP
ドライバがクエリを準備する場合、このスロットがプリペアド文を保持します。
このスロットをどのように使うかはおのおののドライバによります。したがっ
て、クライアントはこの値に依存してはいけません。
@c COMMON
@end defivar

@end deftp

@deffn {Method} dbi-open? (q <dbi-query>)
@c EN
Returns @code{#t} iff the query can still be passed to
@code{dbi-execute}.
@c JP
クエリが@code{dbi-execute}に渡せる状態になっているときにのみ、
@code{#t}を返します。
@c COMMON
@end deffn

@deffn {Method} dbi-close (q <dbi-query>)
@c EN
Destroy the query and free resources associated to the query.
After this operation, @code{dbi-open?} returns @code{#f} for @var{q},
and the query can't be used in any other way.  Although the resource
may be freed when @var{q} is garbage-collected, it is strongly recommended
that the application closes queries explicitly.
@c JP
クエリを破棄し、当該クエリに関連づけられたリソースを解放します。この操
作を実行後は、@code{dbi-open?}は@var{q}に対して@code{#f}を返します。
そして、当該クエリは他の用途にはつかえません。@var{q}がガベージコレク
ションにより回収された場合、リソースは解放されますが、アプリケーション
が明示的にクエリを閉じるようにすることを強く勧めます。
@c COMMON
@end deffn

@deffn {Method} dbi-execute (q <dbi-query>) parameter @dots{}
@c EN
Executes a query created by @code{dbi-prepare}.  You should pass
the same number of @var{parameter}s as the query expects.
@c JP
@code{dbi-prepare}によって作成さればクエリを実行します。当該クエリが期
待するのと同じ数のパラメータを渡す必要があります。
@c COMMON

@c EN
If the issued query is @code{select} statement, @code{dbi-execute}
returns an object represents a @emph{relation}.
A relation encapsulates the values in
rows and columns, as well as meta information like column names.
See "Retrieving query results" below for how to access the result.
@c JP
発行されたクエリが@code{select}文の場合@code{dbi-execute}は
@emph{リレーション}を表わすオブジェクトを返します。リレーションは
行とカラムの値をカプセル化したもので、カラム名のようなメタ情報も同様で
す。結果へアクセスの方法については後述の「クエリの結果を見る」を見てく
ださい。
@c COMMON

@c EN
If the query is other types, such as @code{create}, @code{insert} 
or @code{delete}, the return value of the query closure is unspecified.
@c JP
クエリがSELECT以外の@code{create}、@code{insert}、@code{delete}などの
場合、クエリクロージャー返り値は不定です。
@c COMMON
@end deffn

@deffn {Method} dbi-do conn sql :optional options parameter-value @dots{}
@c EN
This is a convenience procedure when you create a query
and immediately execute it.   It is equivalent to the following
expression, although the driver may overload this method to avoid
creating intermediate query object to avoid the overhead.
@c JP
この手続はクエリを作成し、すぐに実行したいときに便利です。これは次の式
と同じですが、この場合はドライバはオーバーヘッドを避けるため、中間のク
エリを作らないようにこのメソッドをオーバーロードします。
@c COMMON
@example
(dbi-execute (apply dbi-prepare conn sql options)
             parameter-value @dots{})
@end example
@end deffn

@deffn {Method}  dbi-escape-sql conn str
@c EN
Returns a string where special characters in @var{str} are escaped.
@c JP
@var{str}中の特殊文字をエスケープした文字列を返します。
@c COMMON

@c EN
The official SQL standard only specify a single quote (@code{'}) as
such character.  However, it doesn't specify non-printable characters,
and the database system may use other escaping characters.  So 
it is necessary to use this method rather than doing escaping
by your own.
@c JP
SQLの公式標準ではこのような文字としてはシングルクォート(@code{'})につ
いてだけ規定しています。しかし、印字可能文字ではない文字については規定
がありません。また、データベースシステムによっては他のエスケープ文字を
使うものもあります。それゆえ、自分でエスケープしようとせずに、このメソッ
ドを使う必要があります。
@c COMMON

@c EN
@example
;; assumes c is a valid DBI connection
(dbi-escape-sql c "don't know")
  @result{} "don''t know"
@end example
@c JP
@example
;; c を利用可能なDBIコネクションとする
(dbi-escape-sql c "don't know")
  @result{} "don''t know"
@end example
@c COMMON
@end deffn

@c EN
@subsubheading Retrieving query results
@c JP
@subsubheading クエリの結果を見る
@c COMMON

@c EN
If the query is a @code{select} statement, it returns an object
of both @code{<collection>} and @code{<relation>}.   
It is a collection of rows (that is, it implements @code{<collection>} API),
so you can use @code{map}, @code{for-each} or other generic functions
to access rows.  You can also use the relation API to retrieve column
names and accessors from it.  See @ref{Relation framework}, for the relation
API, and @ref{Collection framework}, for the collection API.
@c JP
クエリが@code{select}文である場合、@code{<collection>}と
@code{<relation>}の両方のオブジェクトが返ります。行のコレクション
(すなわち、@code{<collection>} APIの実装)ですから、行にアクセスするに
は@code{map}、@code{for-each}、その他のジェネリック関数が使えます。
また、カラム名やアクセサを取り出すにはリレーションAPIが使えます。
リレーションAPIについては@ref{Relation framework}をコレクションAPIにつ
いては@ref{Collection framework}を見てください。
@c COMMON

@c EN
The actual class of the object returned from a query depends on
the driver, but you may use the following method on it.
@c JP
クエリから戻ったオブジェクトの実際のクラスはドライバによりますが、
以下のメソッドを使うことができます。
@c COMMON

@deffn {Method} dbi-open? result
@c EN
Check whether the result of a query is still active.
The result may become inactive when it is explicitly closed
by @code{dbi-close} and/or the connection to the database is
closed.
@c JP
クエリの結果がまだアクティブであるかどうかをチェックします。
結果は@code{dbi-close}によって明示的に閉じられるかデータベースへのコネ
クションが閉じられると非アクティブになります。
@c COMMON
@end deffn

@deffn {Method} dbi-close result
@c EN
Close the result of the query.  This may cause releasing resources
related to the result.   You can no longer use @var{result} once it is
closed, except passing it to @code{dbi-open?}.
@c JP
クエリの結果を閉じます。結果に関連付けられていたリソースが解放されます。
@var{result}は、いったん閉じると使えなくなります。ただし、
@code{dbi-open?}にだけは渡せます。
@c COMMON

@c EN
Although a driver usually releases resources when the result is
garbage-collected, the application shouldn't rely on that and
is recommended call @code{dbi-close} explicitly when it is done
with the result.
@c JP
ドライバは通常、結果がガベージコレクタによって回収される時にリソースを
解放しますが、アプリケーションはこれに依存してはいけません。結果を使い
おわったら明示的に@code{dbi-close}を呼ぶことをおすすめします。
@c COMMON
@end deffn

@node Writing drivers for DBI,  , DBI user API, Database independent access layer
@subsection Writing drivers for DBI
@c NODE DBI用のドライバを書く

@c EN
Writing a driver for a specific database system means implementing
a module @code{dbd.@var{foo}}, where @var{foo} is the name of the driver.
@c JP
特定のデータベースシステムのドライバを書くということは、
@code{dbd.@var{foo}}モジュールを実装することです。ここで@var{foo}はド
ライバの名前になります。
@c COMMON

@c EN
The module have to implement several classes and methods, as explained below.
@c JP
このモジュールは以下に説明するいくつかのクラスとメソッドを実装しなけれ
ばなりません。
@c COMMON

@c EN
@subsubheading DBI classes to implement
@c JP
@subsubheading 実装するDBIクラス
@c COMMON

@c EN
You have to define the following classes.
@c JP
以下のクラスを定義しなければなりません。
@c COMMON

@c EN
@itemize @bullet
@item
Subclass @code{<dbi-driver>}.  
The class name @emph{must} be @code{<@var{foo}-driver>}, where
@var{foo} is the name of the driver.  
Usually this class produces a singleton instance, 
and is only used to dispatch @code{dbi-make-connection}
method below.
@item
Subclass @code{<dbi-connection>}.  An instance of this class is created
by @code{dbi-make-connection}.  It needs to keep the information about
the actual connections.
@item
Subclass @code{<relation>} and @code{<collection>} to represent
query results suitable for the driver.  (In most cases, the order of
the result of SELECT statement is significant, since it may be 
sorted by ORDER BY clause.  Thus it is more appropriate to
inherit @code{<sequence>}, rather than @code{<collection>}).
@item
Optionally, subclass @code{<dbi-query>} to keep driver-specific
information of prepared queries.
@end itemize
@c JP
@itemize @bullet
@item
@code{<dbi-driver>}のサブクラス。このクラスの名前は@emph{必ず}
@code{<@var{foo}-driver>}でなければなりません。ここで、@var{foo}は
ドライバの名前です。通常このクラスはシングルトンインスタンスを生成し、
後述の@code{dbi-make-connection}メソッドをディスパッチするためにのみ利
用されます。
@item
@code{<dbi-connection>}のサブクラス。このクラスのインスタンスは
@code{dbi-make-connection}によって生成されます。そのためには、実際のコ
ネクションに関する情報を保持する必要があります。
@item
ドライバにあったクエリ結果を表現するための@code{<relation>}および
@code{<collection>}のサブクラス。(ほとんどの場合、SELECT文の結果は順序
が重要です。それは、ORDER BY 節によってソートされる可能性があるからで
す。したがって、@code{<sequence>}を継承するほうが、@code{<collection>}
を継承するよりも適切です。)
@item
オプションとして、プリペアドクエリのドライバ特有の情報を保持するため
@code{<dbi-query>}のサブクラスを実装します。
@end itemize
@c COMMON

@c EN
@subsubheading DBI methods to implement
@c JP
@subsubheading 実装するDBIメソッド
@c COMMON

@c EN
The driver need to implement the following methods.
@c JP
ドライバは以下のメソッドを実装しなければなりません。
@c COMMON

@deffn {Method} dbi-make-connection (d <foo-driver>) (options <string>) (option-alist <list>) :key username password @dots{} 
@c EN
This method is called from @code{dbi-connect}, and responsible to
connect to the database and to create a connection object.
It must return a connection object, or raise an @code{<dbi-error>} if
it cannot establish a connection.
@c JP
このメソッドは@code{dbi-connect}から呼ばれ、データベースへの接続を担い、
コネクションオブジェクトを作成します。コネクションオブジェクトを返さな
ければなりません。コネクションが確立できない場合には、
@code{<dbi-error>}をあげなければなりません。
@c COMMON

@c EN
@var{Options} is the option part of the data source name (DSN) given to
@code{dbi-connect}.  @var{Option-alist} is an assoc list of
the result of parsing @var{options}.  Both are provided so that
the driver may interpret @var{options} string in nontrivial way.
@c JP
@var{options}は@code{dbi-connect}に与えられるデータソースネーム(DSN)の
オプションパートです。@var{option-alist}は@var{options}を解析した結果
の連想リストです。両方ともに用意して、ドライバが自明ではない方法で
@var{options}文字列を解釈できるようにします。
@c COMMON

@c EN
For example, given @code{"dbi:foo:myaddressbook;host=dbhost;port=8998"}
as DSN, foo's @code{dbi-make-connection} will receive
@code{"myaddressbook;host=dbhost;port=8998"} as @var{options},
and @code{(("myaddressbook" . #t) ("host" . "dbhost") ("port" . "8998"))}
as @var{optons-alist}.
@c JP
たとえば、DSNとして
@code{"dbi:foo:myaddressbook;host=dbhost;port=8998"}が与えられたとする
と、fooの@code{dbi-make-connection}は@var{options}として
@code{"myaddressbook;host=dbhost;port=8998"}を受け取り、
@var{optons-alist}として
@code{(("myaddressbook" . #t) ("host" . "dbhost") ("port" . "8998"))}
を受け取ります。
@c COMMON

@c EN
After @var{options-alist}, whatever keyword arguments given to
@code{dbi-connect} are passed.  DBI protocol currently 
specifies only @var{username} and @var{password}.
The driver may define other keyword arguments.
It is recommended to name the driver-specific keyword arguments
prefixed by the driver name, e.g. for @code{dbd.foo}, it may take
a @code{:foo-whatever} keyword argument.
@c JP
@var{options-alist}の後ろならどのようなキーワード引数でも
@code{dbi-connect}に渡せます。DBIプロトコルは現在のところは
@var{username}および@var{password}のみを指定します。
ドライバはその他のキーワード引数を定義できます。
ドライバ特有のキーワード引数にはドライバ名を接頭辞として付けることをお
勧めします。たとえば、@code{dbd.foo}なら、@code{:foo-whatever}のように
です。
@c COMMON

@c EN
It is up to the driver writer to define what options are available and
the syntax of the options.  The basic idea is that the DSN
identifies the source of the data; it's role is like URL in WWW.
So, it may include the hostname and port number of the database,
and/or the name of the database, etc.  However, it shouldn't include
information related to authentication, such as username and password.
That's why those are passed via keyword arguments.
@c JP
どのようなオプションを使えるようにするか、あるいはオプションの構文をど
うするかはドライバを書く人しだいです。基本的な考え方は、DSN はデータの
ソースを識別するためのものであり、その役割りはWWWにおけるURLのようなも
のだということです。それゆえ、データベースのホスト名、ポート番号、それ
にデータベース名などが含まれることになるでしょう。しかし、ユーザ名やパ
スワードのような認証に関する情報を含めてはいけません。というわけで、そ
の手の情報はキーワード引数で渡すのです。
@c COMMON
@end deffn

@deffn {Method} dbi-prepare (c <foo-connection>) (sql <string>) :key pass-through @dots{}
@c EN
This method should create and return a prepared query object,
which is an instance of @code{<dbi-query>} or its subclass.
The query specified by @var{sql} is issued to the database system
when the prepared query object is passed to @code{dbi-execute}.
@c JP
このメソッドは@code{<dbi-query>}あるいはそのサブクラスのインスタンスで
あるプリペアドクエリオブジェクトを生成し、それを返すものでなくてはなり
ません。@var{sql}によるクエリがデータベースに発行されるのは、プリペア
ドクエリオブジェクトが@code{dbi-execute}に渡されたときです。
@c COMMON

@c EN
The method must set @var{c} to the @code{connection} slot of 
the returned query object.
@c JP
このメソッドは返されるクエリオブジェクトの@code{connection}スロットに
@var{c}を設定しなけばなりません。
@c COMMON

@c EN
@var{Sql} is an SQL statement.  It may contain placeholders represented
by @code{'?'}.  The query closure should take the same number of arguments
as of the placeholders.   It is up to the driver whether it parses
@var{sql} internally and construct a complete SQL statement when
the query closure is called, or it passes @var{sql} to the back-end
server to prepare the statement and let the query closure just send
parameters.
@c JP
@var{sql}はSQL文です。これには@code{'?'}で表現されたプレイスホルダが含
まれることがあります。クエリクロージャはこのプレイスホルダと同じ数の引
数をとらなければなりません。内部的に@var{sql}をどのようにパーズするか、
クエリクロージャが呼ばれたとき完全なSQL文を構築するか、@var{sql}をバッ
クエンドのサーバに送って文を準備し、クエリクロージャはパラメータだけを
送るようにするかなどはドライバに依存します。
@c COMMON

@c EN
If the driver parses SQL statement internally, it should recognize
a keyword argument @code{pass-through}.  If a true value is given,
the driver must treat @code{sql} opaque and pass it as is when
the query closure is called.
@c JP
ドライバがSQL文を内部的にわたす場合、キーワード引数@code{pass-through}
を認識しなければいけません。もし、真の値が与えられたら、ドライバは
@code{sql}を不透明なものとして扱い、これをそのままクエリクロージャが呼
ばれた際に渡さなければなりません。
@c COMMON

@c EN
The driver may define other keyword arguments.
It is recommended to name the driver-specific keyword arguments
prefixed by the driver name, e.g. for @code{dbd.foo}, it may take
a @code{:foo-whatever} keyword argument.
@c JP
ドライバがその他のキーワード引数を定義することもできます。
その場合、ドライバ特有のキーワード引数にはドライバ名を接頭辞として付け
ることをお勧めします。たとえば、@code{dbd.foo}なら、
@code{:foo-whatever}のようにです。
@c COMMON
@end deffn

@deffn {Method} dbi-execute-using-connection (c <foo-connection>) (q <dbi-query>) (params <list>)
@c EN
This method is called from @code{dbi-execute}.
It must issue the query kept in @var{q}.  If the query is parameterized,
the actual parameters given to @var{dbi-execute} are passed to
@var{params} argument.
@c JP
このメソッドは@code{dbi-execute}から呼ばれます。@var{q}が保持するクエ
リを発行しなければなりません。クエリがパラメータ化されている場合、
@var{dbi-execute}に与えられた実際のパラメータは@var{params}引数に渡さ
れます。
@c COMMON

@c EN
If @var{q} is a @code{select}-type query, this method must return
an appropriate relation object.
@c JP
@var{q}が@code{select}-型のクエリの場合は、このメソッドは適切なリレー
ションオブジェクトを返さなければなりません。
@c COMMON
@end deffn

@deffn {Method} dbi-escape-sql (c <foo-connection>) str
@c EN
If the default escape method isn't enough, the driver may
overload this method to implement a specific escaping.
For example, MySQL treats backslash characters specially
as well as single quotes, so it has its @code{dbi-escape-sql} 
method.
@c JP
デフォルトのエスケープメソッドでは十分でないとき、ドライバは特別のエス
ケープを行うためにこのメソッドをオーバーロードすることができます。たと
えば、MySQLではバックスラッシュ文字はシングルクォートと同様に特別あつ
かいしますので、@code{dbi-escape-sql}メソッドを持っています。
@c COMMON
@end deffn

@deffn {Method} dbi-open? (c <foo-connection>)
@deffnx {Method} dbi-open? (q <foo-query>)
@deffnx {Method} dbi-open? (r <foo-result>)
@deffnx {Method} dbi-close (c <foo-connection>)
@deffnx {Method} dbi-close (q <foo-query>)
@deffnx {Method} dbi-close (r <foo-result>)
@c EN
Queries open/close status of a connection and a result, and
closes a connection and a result.  The close methods should cause
releasing resources used by connection/result.  The driver
has to allow @code{dbi-close} to be called on a connection or a
result which has already been closed.
@c JP
これらのメソッドでコネクションおよび結果の状態を調べ、コネクションおよ
び結果を閉じます。closeメソッドはコネクションや結果が利用しているリソー
スを解放しなければなりません。ドライバは@code{dbi-close}がすでに閉じら
れたコネクションや結果に対しても適用できるようにしておかなければなりま
せん。
@c COMMON
@end deffn

@deffn {Method} dbi-do (c <foo-connection>) (sql <string>) :optional options parameter-value @dots{}
@c EN
The default method uses @code{dbi-prepare} and @code{dbi-execute}
to implement the function.  It just works,
but the driver may overload this method in order to skip
creating intermediate query object for efficiency.
@c JP
この機能を実装するのにデフォルトメソッドは@code{dbi-prepare}および
@code{dbi-execute}を使っています。これだけでも動きますが、
ドライバは効率のために中間のクエリオブジェクトの生成をスキップするため
にこのメソッドをオーバーロードできます。
@c COMMON
@end deffn

@c EN
@subsubheading DBI utility functions
@c JP
@subsubheading DBIのユーティリティ関数
@c COMMON

@c EN
The following functions are low-level utilities which you may
use to implement the above methods.
@c JP
以下の関数は上述のメソッドを実装するための低レベルのユーティリティです。
@c COMMON

@defun dbi-parse-dsn data-source-name
@c EN
Parse the data source name (DSN) string given to @code{dbi-connect},
and returns tree values: (1) The driver name in a string. (2)
'options' part of DSN as a string.  (3) parsed options in an assoc
list.  This may raise @code{<dbi-error>} if the given string doesn't
conform DSN syntax.
@c JP
@code{dbi-connect}に与えられたデータソースネーム(DSN)文字列を解析し、
以下の3つの値を返す。(1) ドライバ名(文字列) (2) DSNのオプション部分(文
字列) (3) 解析済オプション(連想リスト)。与えられた文字列がDSN構文に準
拠していない場合には@code{<dbi-error>}があがります。
@c COMMON

@c EN
You don't need to use this to write a typical driver, for the
parsing is done before @code{dbi-make-connection} is called.
This method may be useful if you're writing a kind of meta-driver,
such as a proxy.
@c JP
典型的なドライバを書く場合には必要ありません。構文解析は
@code{dbi-make-connection}を呼ぶ前にすんでいるからです。このメソッドは
プロキシのようなメタドライバという類のものを書くときに便利です。
@c COMMON
@end defun

@defun dbi-prepare-sql connection sql
@c EN
Parses an SQL statement @var{sql} which may contain placeholders,
and returns a closure, which generates a complete SQL statement when
called with actual values for the parameters.  If the back-end
doesn't support prepared statements, you may use this function
to prepare queries in the driver.
@c JP
プレイスホルダを含むSQL文 @var{sql} をパーズし、実際の値をパラメータと
して渡されたときに完全なSQLを生成するクロージャを作成します。
バックエンドがプリペアド文をサポートしていない場合は、ドライバ中でクエ
リを準備するのにこの関数を使うことになります。
@c COMMON

@c EN
@var{Connection} is a DBI connection to the database.  It is required
to escape values within SQL properly (see @code{dbi-escape-sql} above).
@c JP
@var{connection}はデータベースへのDBIコネクションです。SQL中の値は適切
にエスケープされている必要があります(上述の@code{dbi-escape-sql}をみて
ください)。
@c COMMON

@c EN
@example
;; assume c contains a valid dbi connection
((dbi-prepare-sql c "select * from table where id=?") "foo'bar")
 => "select * from table where id='foo''bar'"
@end example
@c JP
@example
;; c は正しいdbiコネクションを持っているとする
((dbi-prepare-sql c "select * from table where id=?") "foo'bar")
 => "select * from table where id='foo''bar'"
@end example
@c COMMON
@end defun

@c ----------------------------------------------------------------------

@node Generic DBM interface, File-system dbm, Database independent access layer, Library modules - Utilities
@section @code{dbm} - Generic DBM interface
@c NODE 汎用DBMインタフェース, @code{dbm} - 汎用DBMインタフェース

@deftp {Module} dbm
@mdindex dbm
@c EN
DBM-like libraries provides an easy way to store values to a file,
indexed by keys.  You can think it as a persistent associative memory.
@c JP
DBM系のライブラリはキーでインデックスされた値をファイルに格納する簡単な方法を
提供します。一種の永続的な連想記憶と言えるでしょう。
@c COMMON

@c EN
This modules defines @code{<dbm>} abstract class, which has
a common interface to use various DBM-type database packages.
As far as you operate on the already opened database,
importing @code{dbm} module is enough.
@c JP
このモジュールが定義する抽象クラス@code{<dbm>}は、DBM系ライブラリへの
統一されたインタフェースを提供します。@code{dbm}モジュールだけをインポートすれば、
既にオープンされたデータベースを操作することができます。
@c COMMON

@c EN
To create or open a database, you need a concrete implementation
of the database.  Gauche currently has the following implementations.
Each module defines its own low-level accessing functions
as well as the common interface.
Note that your system may not have one or more of those DBM libraries;
Gauche defines only what the system provides.
@c JP
データベースをオープンしたり作成したりするには、dbmインタフェースを実装した
モジュールが必要になります。今のところGaucheでは以下の実装が使えます。
それぞれのモジュールは、dbmインタフェース共通の手続きの他に、
直接実装を操作できる低レベルの手続きも提供します。
システムによっては以下のインタフェースの全てが実装されているわけではないことに
注意してください。Gaucheではシステムが提供する実装のみを定義します。
@c COMMON

@table @code
@item dbm.fsdbm
@c EN
file-system dbm (@xref{File-system dbm}).
@c JP
ファイルシステムdbm (@ref{File-system dbm}参照).
@c COMMON

@item dbm.gdbm
@c EN
GDBM library (@xref{GDBM interface}).
@c JP
GDBMライブラリ (@ref{GDBM interface}参照).
@c COMMON

@item dbm.ndbm
@c EN
NDBM library (@xref{NDBM interface}).
@c JP
NDBMライブラリ (@ref{NDBM interface}参照).
@c COMMON

@item dbm.odbm
@c EN
DBM library  (@xref{Original DBM interface}).
@c JP
DBMライブラリ  (@ref{Original DBM interface}参照).
@c COMMON
@end table
@end deftp

@c EN
The following code shows a typical usage of the database.
@c JP
以下にdbmデータベースの使用例を示します。
@c COMMON

@example
(use dbm)         ; @r{dbm abstract interface}
(use dbm.gdbm)    ; @r{dbm concrete interface}

; @r{open the database}
(define *db* (dbm-open <gdbm> :path "mydb" :rw-mode :write))

; @r{put the value to the database}
(dbm-put! *db* "key1" "value1")

; @r{get the value from the database}
(define val (dbm-get *db* "key1"))

; @r{iterate over the database}
(dbm-for-each *db* (lambda (key val) (foo key val)))

; @r{close the database}
(dbm-close *db*)
@end example

@menu
* Opening and closing a dbm database::  
* Accessing a dbm database::    
* Iterating on a database::     
* Managing dbm database instance::  
* Dumping and restoring dbm database::  
* Writing a dbm implementation::  
@end menu

@node Opening and closing a dbm database, Accessing a dbm database, Generic DBM interface, Generic DBM interface
@subsection Opening and closing a dbm database
@c NODE DBMデータベースのオープンとクローズ

@deftp {Class} <dbm>
@clindex dbm
@c EN
An abstract class for dbm-style database.  Defindes the common
database operations.   This class has the following instance slots.
They must be set before the database is actually opened by
@code{dbm-open}.

The concrete class may add more slots for finer control on the database,
such as locking.
@c JP
DBM系のデータベースのための抽象クラスです。データベースへの共通のオペレーションを
定義します。以下のインスタンススロットを持ちます。これらのスロットの値は
@code{dbm-open}によってデータベースがオープンされる前にセットされて
いなければなりません。

具体クラスは、データベースの操作をより細かく行うための追加のスロット(例えばロックを
行うかどうか)を持つかもしれません。
@c COMMON

@defivar <dbm> path
@c EN
Pathname of the dbm database.  Some dbm implementation may append
suffixes to this.
@c JP
データベースファイルのパス名。dbmの実装によっては、このパスにサフィックスが追加されます。
@c COMMON
@end defivar

@defivar <dbm> rw-mode
@c EN
Specifies read/write mode.  Can be either one of the following keywords:
@table @code
@item :read
The database will be opened in read-only mode.  The database file must
exist when @code{dbm-open} is called.
@item :write
The database will be opened in Read-write mode.
If the database file does not exist, @code{dbm-open} creates one.
@item :create
The database will be created and opened in Read-write mode.
If the database file exists, @code{dbm-open} truncates it.
@end table
@c JP
読み書きのモードを指定します。以下の値のいずれかを取ります。
@table @code
@item :read
データベースは@code{dbm-open}によって読みだし専用モードでオープンされます。
オープンされる時点でデータベースは存在していなければなりません。
@item :write
データベースは@code{dbm-open}によって読み書き可能なモードでオープンされます。
データベースが存在しなければ、@code{dbm-open}は新しいデータベースを作成します。
@item :create
@code{dbm-open}によって新しいデータベースが作成され、読み書き可能なモードでオープンされます。
既にデータベースが存在していた場合、その内容はクリアされます。
@end table
@c COMMON
@end defivar

@defivar <dbm> file-mode
@c EN
Specifies the file permissions (as @code{sys-chmod}) to create the
database.  The default value is @code{#o664}.
@c JP
データベースが作成されるときのファイルパーミッションを指定します。
デフォルトは@code{#o664}です。
@c COMMON
@end defivar

@defivar <dbm> key-convert
@defivarx <dbm> value-convert
@c EN
By default, you can use only strings for both key and values.  With this
option, however, you can specify how to convert other Scheme values to/from
string to be stored in the database.   The possible values are the
followings:
@table @asis
@item @code{#f}
The default value.  Keys (values) are not converted.  They must be
a string.
@item @code{#t}
Keys (values) are converted to its string representation, using 
@code{write}, to store in the database, and converted
back to Scheme values, using @code{read}, to retrieve from the database.
The data must have an external representation that can be read back.
(But it is not checked when the data is written; you'll get an error
when you read the data).  The key comparison is done in the string
level, so the external representation of the same key must match.
@item a list of two procedures
Both procedure must take a single argument.  The first procedure must
receive a Scheme object and returns a string.  It is used to convert
the keys (values) to store in the database.  The second procedure
must receive a string and returns a Scheme object.  It is used to
convert the stored data in the database to a Scheme object.
The key comparison is done in the string
level, so the external representation of the same key must match.
@end table
@c JP
デフォルトでは、dbmデータベースはキーにも値にも文字列しか使うことはできません。
これらのスロットによって、それ以外のSchemeオブジェクトを取り扱う方法を指定することが
できます。以下の値のいずれかが可能です。
@table @asis
@item @code{#f}
デフォルトの値です。キーあるいは値は変換されません。それらは文字列でなければなりません。
@item @code{#t}
キーあるいは値は@code{write}を使って文字列に変換されデータベースに格納されます。
そして@code{read}を使って文字列からSchemeオブジェクトへと変換されます。
後で@code{read}で読みこめるようなキーあるいは値のみを扱うことができます。
(但し、dbmライブラリは書き込み時にそれが後で読み込めるかどうかのチェックは行いません)。
キーの比較は文字列に変換された後で行われるので、同じ値となるキーは同じ文字列表現を
持つ必要があります。
@item 二つの手続きのリスト
どちらの手続きも一つの引数を取ります。最初の手続きはSchemeオブジェクトを受け取り、
文字列を返します。キーあるいは値をデータベースに格納する時に呼ばれます。
二つ目の手続きは文字列を受け取りSchemeオブジェクトを返します。データベースから
キーあるいは値を取り出す時に呼ばれます。
キーの比較は文字列に変換された後で行われるので、同じ値となるキーは同じ文字列に
変換される必要があります。
@end table
@c COMMON
@end defivar
@end deftp

@deftp {Metaclass} <dbm-meta>
@clindex dbm-meta
@c EN
A metaclass of @code{<dbm>} and its subclasses.
@c JP
@var{<dbm>}クラス及びそのサブクラスのメタクラスです。
@c COMMON
@end deftp

@deffn {Method} dbm-open (dbm <dbm>)
@c EN
Opens a dbm database.  @var{dbm} must be an instance of
one of the concrete classes that derived from the @code{<dbm>} class,
and its slots must be set appropriately.   On success, it returns
the @var{dbm} itself.  On failure, it signals an error.
@c JP
DBMデータベースをオープンします。@var{dbm}は、@code{<dbm>}クラスを継承した
具体クラスのインスタンスでなければなりません。また、そのスロットには適切な値が
セットされている必要があります。オープンに成功したら@var{dbm}自身が返されます。
失敗した場合はエラーが報告されます。
@c COMMON
@end deffn

@deffn {Method} dbm-open (dbm-class <dbm-meta>) options @dots{}
@c EN
A convenient method that creates dbm instance and opens it.
It is defined as follows.
@c JP
DBMインスタンスを作成してオープンするための便利なメソッドです。
次のように定義されます。
@c COMMON
@example
(define-method dbm-open ((class <class>) . initargs)
  (dbm-open (apply make class initargs)))
@end example
@end deffn

@c EN
Database file is closed when it is garbage collected.
However, to ensure the modification is properly synchronized,
you should close the database explicitly.
@c JP
データベースファイルはガベージコレクトされる際にクローズされますが、
変更を正しくデータベースに反映するには、明示的にクローズした方が良いでしょう。
@c COMMON

@deffn {Method} dbm-close (dbm @code{<dbm>})
@c EN
Closes a database @var{dbm}.  Once the database is closed, any
operation to access the database content raises an error.
@c JP
データベース@var{dbm}をクローズします。データベースがクローズされると、
それ以降のアクセスオペレーションはエラーとなります。
@c COMMON
@end deffn

@deffn {Method} dbm-closed? (dbm @code{<dbm>})
@c EN
Returns true if a database @var{dbm} is already closed, false otherwise.
@c JP
データベース@var{dbm}が既にクローズされていたら@code{#t}を返します。
@c COMMON
@end deffn

@defun dbm-type->class dbmtype
Sometimes you don't know which type of dbm implementation you
need to use in your application beforehand, but rather you need to
determine the type according to the information given at run-time.
This procedure fulfills the need.

The @var{dbmtype} argument is a symbol that names the type
of dbm implementation; for example, @code{gdbm} for @code{dbm.gdbm},
and @code{fsdbm} for @code{dbm.fsdbm}.   We assume that the
dbm implementation of type @code{@var{foo}} is provided as 
a module @code{dbm.@var{foo}}, and its class is named
as @code{<@var{foo}>}.

This procedure first checks if the required module has been
loaded, and if not, it tries to load it.   If the module
loads successfully, it returns the class object of the
named dbm implementation.   If it can't load the module,
or can't find the dbm class, this procedure returns #f.

@example
(use dbm)

(dbm-type->class 'gdbm)
  @result{} @code{#<class <gdbm>>}

(dbm-type->class 'nosuchdbm)
  @result{} @code{#f}
@end example
@end defun

@node Accessing a dbm database, Iterating on a database, Opening and closing a dbm database, Generic DBM interface
@subsection Accessing a dbm database
@c NODE DBMデータベースのアクセス

@c EN
Once a database is opened, you can use the following methods
to access individual key/value pairs.
@c JP
データベースがオープンされたら、以下のアクセスメソッドが使えます。
@c COMMON

@deffn {Method} dbm-put! (dbm @code{<dbm>}) key value
@c EN
Put a @var{value} with @var{key}.
@c JP
値@var{value}をキー@var{key}と関連付けて保存します。
@c COMMON
@end deffn

@deffn {Method} dbm-get (dbm @code{<dbm>}) key :optional default
@c EN
Get a value associated with @var{key}.  If no value exists for @var{key}
and @var{default} is specified, it is returned.  If no value exists for
@var{key} and @var{default} is not specified, an error is signalled.
@c JP
キー@var{key}に関連付けられた値を返します。もし値が存在しなければ、@var{default}が
与えられていればそれを返し、そうでなければエラーを報告します。
@c COMMON
@end deffn

@deffn {Method} dbm-exists? (dbm @code{<dbm>}) key
@c EN
Return true if a value exists for @var{key}, false otherwise.
@c JP
キー@var{key}に関連付けられた値が存在すれば@code{#t}を返します。
@c COMMON
@end deffn

@deffn {Method} dbm-delete! (dbm @code{<dbm>}) key
@c EN
Delete a value associated with @var{key}.  
@c JP
キー@var{key}に関連付けられた値を消去します。値が存在しない場合は何もしません。
@c COMMON
@end deffn

@node Iterating on a database, Managing dbm database instance, Accessing a dbm database, Generic DBM interface
@subsection Iterating on a dbm database
@c NODE DBMデータベース上の繰り返し処理

@c EN
To walk over the entire database, following methods are provided.
@c JP
全データベースを渡り歩く処理のために、以下のメソッドが用意されています。
@c COMMON

@deffn {Method} dbm-fold (dbm @code{<dbm>}) procedure knil
@c EN
The basic iterator.
For each key/value pair, @var{procedure} is called as
@code{(@var{procedure} @var{key} @var{value} @var{r})},
where @var{r} is @var{knil} for the fist call of @var{procedure},
and the return value of the previous call for subsequent calls.
Returns the result of the last call of @var{procedure}.
If no data is in the database, @var{knil} is returned.

The following method returns the sum of all the integer values.
@c JP
基本的な繰り返し処理です。データベース内の各キー／値のペアに関して、手続き
@var{procedure}が @code{(@var{procedure} @var{key} @var{value} @var{r})},
のように呼ばれます。ここで@var{r}は、最初の@var{procedure}の呼び出しの時には@var{knil}
が、以降の呼び出しの時にはその直前の@var{procedure}が返した値が渡されます。
最後の@var{procedure}の戻り値が@code{dbm-fold}の戻り値となります。
データベース中にデータがひとつもなければ@var{knil}がそのまま返されます。

次の例は、データベース中の整数の値を全て加算します。
@c COMMON
@example
(dbm-fold dbm (lambda (k v r) (if (integer? v) (+ v r) r)) 0)
@end example
@end deffn

@deffn {Method} dbm-for-each (dbm @code{<dbm>}) procedure
@c EN
For each key/value pair in the database @var{dbm}, @var{procedure}
is called.  Two arguments are passed to @var{procedure}---a key and
a value.   The result of @var{procedure} is discarded.
@c JP
データベース内の各キー／値のペアに関して、手続き@var{procedure}を呼び出します。
@var{procedure}にはキーと値が渡されます。@var{procedure}の戻り値は捨てられます。
@c COMMON
@end deffn

@deffn {Method} dbm-map (dbm @code{<dbm>}) procedure
@c EN
For each key/value pair in the database @var{dbm}, @var{procedure}
is called.  Two arguments are passed to @var{procedure}---a key and
a value.   The result of @var{procedure} is accumulated to a list
which is returned as a result of @code{dbm-map}.
@c JP
データベース内の各キー／値のペアに関して、手続き@var{procedure}を呼び出します。
@var{procedure}にはキーと値が渡されます。@var{procedure}の戻り値はリストに
集められて@code{dbm-map}の戻り値となります。
@c COMMON
@end deffn

@node Managing dbm database instance, Dumping and restoring dbm database, Iterating on a database, Generic DBM interface
@subsection Managing dbm database instance
@c NODE DBMデータベースインスタンスの管理

@c EN
Each dbm implementation has its own way to store the
database.  Legacy dbm uses two files, whose names are
generated by adding @file{.dir} and @file{.pag} to the
value of @var{path} slot.  @code{Fsdbm} creates a directory
under @var{path}.  If dbm database is backed up by
some database server, @var{path} may be used only as
a key to the database in the server.
@c JP
各DBM実装は、データベースを格納するのに独自の方法を使います。
レガシーなDBMは、@var{path}スロットの値にそれぞれ@file{.dir}と
@file{.pag}を付けた名前の2つのファイルを使います。
@code{fsdbm}は@var{path}の下にディレクトリを作ります。
DBMデータベースが他のデータベースサーバによってバック
アップされる場合は、@var{path}はそのサーバで単なるキーと
して使われるでしょう。

@c EN
The following methods hide such variations and provides
a convenient way to manage a database itself.   You have to
pass a class that implements a concrete dbm database to their
first argument.
@c JP
以下のメソッドは、そのようなバリエーションを隠し、
データベースそれ自体を管理する簡易な方法を提供します。
最初の引数に、具体的なDBMデータベースを実装している
クラスを渡す必要があります。
@c COMMON

@deffn {Generic Function} dbm-db-exists? class name
@c EN
Returns @code{#t} if a database of class @var{class}
specified by @var{name} exists.
@c JP
@var{name}で指定された@var{class}クラスのデータベースが
存在する場合は@code{#t}を返します。
@c COMMON

@example
;; Returns #t if testdb.dir and testdb.pag exist
(dbm-db-exists? <odbm> "testdb")
@end example
@end deffn

@deffn {Generic Function} dbm-db-remove class name
@c EN
Removes an entire database of class @var{class} specified by
@var{name}.
@c JP
@var{name}で指定される@var{class}クラスのデータベース
全体を削除します。
@c COMMON
@end deffn

@deffn {Generic Function} dbm-db-copy class from to
@c EN
Copy a database of class @var{class} specified by
@var{from} to @var{to}.  The integrity of @var{from}
is guaranteed if the @var{class}'s dbm implementation supports
locking (i.e. you won't get a corrupted database even if
some other process is trying to write to @var{from}
during copy).   If the destination database @var{to} exists,
its content is destroyed.  If this function is interrupted,
whether @var{to} is left in incomplete state or not depends
on the dbm implementation.   The implementation usually tries
its best to provide transactional behavior, that is,
to recover original @var{to} when the copy fails.  However,
for the robust operations the caller have to check the state 
of @var{to} if @code{dbm-db-copy} fails.
@c JP
@var{from}で指定された@var{class}クラスのデータベースを
@var{to}へコピーします。
@var{class}のdbm実装がロックをサポートしている限り、@var{from}の一貫性は
保たれます (つまり、コピー中に他のプロセスが@var{from}を
変更しようとした場合であっても、@var{to}が壊れたデータベースになることは
ありません)。  もしコピー先の@var{to}が既に存在するデータベースで
あった場合、@var{to}の元の内容は失われます。
コピーが中断された場合に@var{to}が不完全な状態のままになるかどうかは
dbm実装に依存します。dbm実装の多くはトランザクショナルな振る舞い、
すなわち、コピーが失敗した場合に元の@var{to}を復元することを試みます。
しかし確実な操作のためには、コピーが失敗した場合には呼び出し側で@var{to}の
状態を確認することが必要です。
@c COMMON

@example
(dbm-db-copy <gdbm> "testdb.dbm" "backup.dbm")
@end example
@end deffn

@deffn {Generic Function} dbm-db-move class from to
@c EN
Moves or renames a database of class @var{class} specified by
@var{from} to @var{to}.  Like @code{dbm-db-copy}, the database
integrity is guaranteed as far as @var{class}'s dbm implementation
supports locking.  If the destination database @var{to} exists,
its content is destroyed.
@c JP
@var{from}で指定された@var{class}クラスのデータベースを
@var{to}へ移動、あるいはリネームします。@code{dbm-db-copy}と同じく、
@var{class}のdbm実装がロックをサポートしていれば
データベースの一貫性は保証されます。移動先の@var{to}が既に
存在していた場合、その元の内容は失われます。
@c COMMON
@end deffn

@node Dumping and restoring dbm database, Writing a dbm implementation, Managing dbm database instance, Generic DBM interface
@subsection Dumping and restoring dbm database
@c NODE DBMデータベースのダンプとリストア

Most dbm implementations use some kind of binary format, and
some of them are architecture dependent.   
That makes it difficult to pass around dbm databases
between different machines.
A safe way is to write out the content of a dbm database
into some portable format on the source machine,
and rebuild another dbm databse from it on the destination
machine.

The operation is so common that Gauche provides convenience
scripts that does the job.  They are installed into the
standard Gauche library directory, so it can be invoked
by @code{gosh <scriptname>}.

To write out the content of a dbm database named by @var{dbm-name}, 
you can use @code{dbm/dump} script:

@example
$ gosh dbm/dump [-o @var{outfile}][-t @var{type}] @var{dbm-name}
@end example

The @var{outfile} argument names the output file.  If omitted,
the output is written out to stdout.  The @var{type} argument
specifies the implementation type of the dbm database; e.g.
@code{gdbm} or @code{fsdbm}.  The program calls
@code{dbm-type->class} (@xref{Opening and closing a dbm database})
on the @var{type} argument to load the necessary dbm implementation.

The dumped format is simply a series of S-expressions,
each of which is a dotted pair of string key and string value.
Character encodings are assumed to be the same as
@code{gosh}'s native character encoding.

The dumped output may contain S-expressions other than dotted pair
of strings to include meta information.  For now, programs
that deals with dumped output should just ignore S-expressions
other than dotted pairs.

To read back the dumped dbm format, you can use @code{dbm/restore}
script:

@example
$ gosh dbm/restore [-i @var{infile}][-t @var{type}] @var{dbm-name}
@end example

The @var{infile} argument names the dumped file to be read.
If omitted, it reads from stdin.  The @var{type} argument
specifies the dbm type, as in @code{dbm/dump} script.
The @var{dbm-name} argument names the dbm database; if the
database already exists, its content is cleared, so be careful.


@node Writing a dbm implementation,  , Dumping and restoring dbm database, Generic DBM interface
@subsection Writing a dbm implementation
@c NODE DBM実装を書く

When you write an extension module that behaves like
a persistent hashtable, it is a good idea to adapt it
to the dbm interface, so that the application can use
the module in a generic way.

The minimum procedures to conform the dbm interface
are as follow:

@itemize @bullet
@item
Define a metaclass @code{<@var{foo}-meta>}.   It doesn't
need to inherit anything except @code{<class>}.
@item
Define a dbm class @code{<@var{foo}>} that inherits @code{<dbm>}
and whose metaclass is @code{<@var{foo}-meta>}.
@item
Define methods for @code{dbm-open}, @code{dbm-close},
@code{dbm-put!}, @code{dbm-get}, @code{dbm-exists},
@code{dbm-delete!}, @code{dbm-fold}, @code{dbm-closed?},
specialized for @code{<@var{foo}>}.
(The case of @code{dbm-open} for @code{<@var{foo}-meta>} is
handled automatically, so you don't need to define it unless
you want something special).
Also note that the specialized @code{dbm-open} must call
@code{next-method} in it to set up dbm base class internals.
@item
Define methods for @code{dbm-db-exists?} and
@code{dbm-db-remove} on @code{<@var{foo}-meta>}.
@end itemize

Besides above, you may define the following methods.

@itemize @bullet
@item
Methods for @code{dbm-for-each} and @code{dbm-map}.
If you don't define them, a generic implementation
by @code{dbm-fold} is used.  There may be an implementation
specific way which is more efficient.
@item
Methods for @code{dbm-db-copy} and @code{dbm-db-move}.
If you don't define them, a fallback method
opens the specified databases and copies elements one by
one, and removes the original if the method is  @code{dbm-db-move}.
Note that the fallback method is not only inefficient,
but also it may not copy any implementation-specific 
meta information.  It is highly recommended for the
dbm implementation to provide these methods as well.
@end itemize

It is generally recommended to name the implementation module 
as @code{dbm.@var{foo}}, and the class of the implementation
as @code{<@var{foo}>}.  With this convention it is easier to
write an application that dynamically loads and uses
dbm implementation specified at runtime.

@c ----------------------------------------------------------------------
@node File-system dbm, GDBM interface, Generic DBM interface, Library modules - Utilities
@section @code{dbm.fsdbm} - File-system dbm
@c NODE ファイルシステムdbm, @code{dbm.fsdbm} - ファイルシステムdbm

@deftp {Module} dbm.fsdbm
@mdindex dbm.fsdbm
Implements fsdbm.  Extends @code{dbm}.
@end deftp

@deftp {Class} <fsdbm>
@clindex fsdbm
@c EN
@code{Fsdbm} is a dbm implementation that directly uses
the filesystem.  Basically, it uses file names for keys,
and file content for values.   Unlike other dbm implementations,
this doesn't depend on external libraries---it is pure Scheme 
implementation---so it is always available, while other dbm
implementations may not.
@c JP
@code{fsdbm}は、直接ファイルシステムを扱うDBM実装です。
基本的には、ファイル名をキー、ファイルの内容を値として使います。
他のDBM実装とは違い、これは他の特別なライブラリに依存しません
(純粋にSchemeのみにより実装されています)。
したがって、他のDBM実装が使えないときでも、いつでも使うことが
できます。

@c EN
Obviously, it is not suitable for the database that has
lots of entries, or has entries deleted and added very frequently.
The advantage is when the number of entries
are relatively small, and the values are relatively large while
keys are small.
@c JP
明らかに、たくさんのエントリを持っていたり、エントリの追加や
削除が頻繁に起こるようなデータベースには向いていません。
エントリの数が相対的に小さく、キーが小さいのに値が大きいような
場合に向いています。

@c EN
The database name given to @code{<fsdbm>} instance
is used as a directory name that stores the data.
@c JP
@code{<fsdbm>}のインスタンスに与えられるデータベース名は、
データを格納するディレクトリの名前として使われます。

@c EN
The data files are stored in subdirectories under @var{path} of
@code{fsdbm} instance, hashed by the key.  Non-alphanumeric characters
in the key is encoded like @code{_3a} for '@code{:}', for example.
If a key is too long to be a file name, it is chopped to chunks,
and each chunk but the last one is used as a directory name.
Note that a long key name may still cause a problem, for example,
some of old 'tar' command can't deal with pathnames (not each
pathname components, but the entire pathname) longer than 256
characters.
@c JP
データのファイルは、@code{fsdbm}インスタンスの@var{path}の
サブディレクトリに格納され、キーによりハッシュされます。
キーに英数字でない文字がある場合はエンコードされます。
例えば、'@code{:}'は、@code{_3a}にエンコードされます。
キーがファイル名としては長すぎる場合は、いくつかに
分割され、その最後の文字列片以外はディレクトリ名として
使われます。長いキー名は問題を引き起こすかも知れないことに
注意して下さい。例えば、いくつかの古い'tar'コマンドは、256文字
を越える長いパス名を扱えません(それぞれのパスコンポーネント
ではなく、パス名全体でです)。
@c COMMON
@end deftp

@c EN
Fsdbm implements all of the dbm protocol 
(see @ref{Generic DBM interface}).
It doesn't have any fsdbm-specific procedures.
@c JP
fsdbmは、全てのDBMプロトコルを実装しています
(@ref{Generic DBM interface}参照)。
fsdbm特有の手続きというものはありません。
@c COMMON

@c ----------------------------------------------------------------------
@node GDBM interface, NDBM interface, File-system dbm, Library modules - Utilities
@section @code{dbm.gdbm} - GDBM interface
@c NODE GDBMインタフェース, @code{dbm.gdbm} - GDBMインタフェース

@deftp {Module} dbm.gdbm
@mdindex dbm.gdbm
Provides interface to the gdbm library.  Extends @code{dbm}.
@end deftp

@deftp {Class} <gdbm>
@clindex gdbm
@c EN
Inherits @code{<dbm>}.  Provides an implementation for GDBM library.
This module is only installed when your system already has GDBM
(1.8.0 is preferred, but works with older 1.7.x with some limitations).
@c JP
@code{<dbm>} を継承します。GDBM ライブラリのための実装を提供します。
このモジュールは、すでにあなたのシステムにすでに GDBM がある場合にのみ
インストールされます(バージョン 1.8.0 が推奨されますが、いくつかの制限が
あるだけで古い 1.7.x でも動作します)。
@c COMMON

@defivar <gdbm> sync
@end defivar
@defivar <gdbm> nolock
@end defivar
@defivar <gdbm> bsize
@end defivar
@end deftp

@c EN
Besides the unified DBM interface (@xref{Generic DBM interface}),
this module provides the following low-level functions that provides
direct access to the gdbm API.  See gdbm manual for details of these
APIs.
@c JP
統合された DBM インターフェース (@xref{Generic DBM interface}) の
他に、このモジュールでは GDBM API への直接のアクセスを提供する以下の
低レベルな手続きを提供しています。これらの API の詳細については GDBM の
マニュアルを見て下さい。
@c COMMON

@defun gdbm-open path :optional size rwmode fmode error-callback

@defvar GDBM_READER
@end defvar

@defvar GDBM_WRITER
@end defvar

@defvar GDBM_WRCREAT
@end defvar

@defvar GDBM_NEWDB
@end defvar

@defvar GDBM_FAST
@end defvar

@defvar GDBM_SYNC
@end defvar

@defvar GDBM_NOLOCK
@end defvar
@end defun

@defun gdbm-close gdbm-object
@end defun

@defun gdbm-closed? gdbm-object
@end defun

@defun gdbm-store key value :optional flag


@defvar GDBM_INSERT
@end defvar

@defvar GDBM_REPLACE
@end defvar

@end defun


@defun gdbm-fetch gdbm-object key
@end defun


@defun gdbm-delete gdbm-object key
@end defun


@defun gdbm-firstkey gdbm-object
@end defun


@defun gdbm-nextkey gdbm-object key
@end defun


@defun gdbm-reorganize gdbm-object
@end defun


@defun gdbm-sync gdbm-object
@end defun


@defun gdbm-exists? gdbm-object key
@end defun


@defun gdbm-strerror errno
@end defun


@defun gdbm-setopt gdbm-object option value

@defvar GDBM_CACHESIZE
@end defvar

@defvar GDBM_FASTMODE
@end defvar

@defvar GDBM_SYNCMODE
@end defvar

@defvar GDBM_CENTFREE
@end defvar

@defvar GDBM_COALESCEBLKS
@end defvar
@end defun

@defun gdbm-version
@end defun

@defun gdbm-errno
@end defun

@c ----------------------------------------------------------------------
@node NDBM interface, Original DBM interface, GDBM interface, Library modules - Utilities
@section @code{dbm.ndbm} - NDBM interface
@c NODE NDBMインタフェース, @code{dbm.ndbm} - NDBMインタフェース

@deftp {Module} dbm.ndbm
@mdindex dbm.ndbm
Provides interface to the 'new' dbm library, a.k.a. ndbm.
Extends @code{dbm}.
@end deftp

@deftp {Class} <ndbm>
@clindex ndbm
@c EN
Inherits @code{<dbm>}.  Provides an implementation for NDBM library.
This module is only installed when your system already has NDBM.
@c JP
@code{<dbm>} を継承します。NDBM ライブラリのための実装を提供します。
このモジュールはあなたのシステムにすでに NDBM がある場合にのみ
インストールされます。
@c COMMON
@end deftp

@c EN
Besides the unified DBM interface (@xref{Generic DBM interface}),
this module provides the following low-level functions that provides
direct access to the ndbm API.  See ndbm manual for details of these
APIs.
@c JP
統合された DBM インターフェース (@xref{Generic DBM interface}) の
他に、このモジュールでは NDBM API への直接のアクセスを提供する以下の
低レベルな手続きを提供しています。これらの API の詳細については NDBM の
マニュアルを見て下さい。
@c COMMON

@defun ndbm-open path flags mode
@end defun

@defun ndbm-close ndbm-object
@end defun

@defun ndbm-closed? ndbm-object
@end defun

@defun ndbm-store ndbm-object key content :optional flag
@end defun

@defun ndbm-fetch ndbm-object key
@end defun

@defun ndbm-delete ndbm-object key
@end defun

@defun ndbm-firstkey ndbm-object
@end defun

@defun ndbm-nextkey ndbm-object
@end defun

@defun ndbm-error ndbm-object
@end defun

@defun ndbm-clear-error ndbm-object
@end defun

@c ----------------------------------------------------------------------
@node Original DBM interface, Filtering file content, NDBM interface, Library modules - Utilities
@section @code{dbm.odbm} - Original DBM interface
@c NODE オリジナルのDBMインタフェース, @code{dbm.odbm} - オリジナルのDBMインタフェース

@deftp {Module} dbm.odbm
@mdindex dbm.odbm
Provides interface to the legacy dbm library.
Extends @code{dbm}.
@end deftp

@deftp {Class} <odbm>
@clindex odbm
@c EN
Inherits @code{<dbm>}.  Provides an implementation for legacy DBM
library.
This module is only installed when your system already has DBM.

The biggest limitation of the legacy DBM is that you can only open
one database at a time.  You can create a multiple @code{<odbm>}
instances, but you can open at most one of it at a time, or
you'll get an error.
@c JP
@code{<dbm>} を継承しています。レガシーな DBM ライブラリのための実装を
提供します。このモジュールは、あなたのシステムにすでに DBM がある場合にのみ
インストールされます。

レガシー DBM の最大の制限は、データベースを一時に一つしか開けないことです。
複数の @code{<odbm>} のインスタンスを作ることができますが、一時に一つしか
開くことが出来ず、一つ以上開こうとするとエラーになります。
@c COMMON
@end deftp

@c EN
Besides the unified DBM interface (@xref{Generic DBM interface}),
this module provides the following low-level functions that provides
direct access to the dbm API.  See dbm manual for details of these
APIs.
@c JP
統合された DBM インターフェース (@xref{Generic DBM interface}) の
他に、このモジュールでは DBM API への直接のアクセスを提供する以下の
低レベルな手続きを提供しています。これらの API の詳細については DBM の
マニュアルを見て下さい。
@c COMMON

@defun odbm-init path
@end defun

@defun odbm-close
@end defun

@defun odbm-store key value
@end defun

@defun odbm-fetch key
@end defun

@defun odbm-delete key
@end defun

@defun odbm-firstkey
@end defun

@defun odbm-nextkey key
@end defun


@c ----------------------------------------------------------------------
@c @node Pseudo DBM interface, gauche.charconv - Character code conversion, Original DBM interface, Library modules
@c @section @code{dbm.pdbm} - Pseudo DBM interface

@c ----------------------------------------------------------------------
@node Filtering file content, Filesystem utilities, Original DBM interface, Library modules - Utilities
@section @code{file.filter} - Filtering file content
@c NODE ファイルのフィルタ, @code{file.filter} - ファイルのフィルタ

@deftp {Module} file.filter
@mdindex file.filter
@c EN
This module provides utilities for a common pattern in
filter-type commands, that is, to take an input, to process
the content, and to write the result.   The common occurring
pattern is:

@itemize @bullet
@item
Input may be a specified file, or an input port
(the current input port by default).
@item
Output may be a specified file, or an output port
(the current output port by default).
@item
Output may be a temporary file, which will be renamed
upon completion of the processing.
@item
Output file may be removed when an error occurs
in the processing.
@end itemize
@c JP
このモジュールは、フィルター型のコマンド、
すなわち入力を読み込み、処理をして結果を書き出すような場合に
共通するパターンに使えるユーティリティ手続きを提供します。
共通するパターンとは：

@itemize @bullet
@item
入力は指定されたファイルかポートで、デフォルトはカレント入力ポート。
@item
出力は指定されたファイルかポートで、デフォルトはカレント出力ポート。
@item
出力は一時ファイルに書き出すこともできて、
その場合は処理が終了した時点で指定されたファイルにリネーム。
@item
処理途中でエラーが起こった場合に出力ファイルを削除
@end itemize
@c COMMON
@end deftp

@defun file-filter proc :key input output temporary-file keep-output?
@c EN
Calls @var{proc} with two arguments, an input port and 
an output port.   Returns the result(s) of @var{proc}.
The input port and output port are chosen depending on the keyword arguments.
@c JP
二つの引数、入力ポートと出力ポートを引数として@var{proc}を呼び出し、
その結果を返します。
入力ポートと出力ポートはキーワード引数により決定されます。
@c COMMON

@table @code
@item input
@c EN
The argument must be either an input port or a string
that specifies a file name.
If it's an input port, it is passed to @var{proc} as is.
If it's a string, the named file is opened for input and the resulting
port is passed to @var{proc}, and the port is closed when @var{proc}
returns.
If this argument is omitted, the current input port is passed.
@c JP
この引数は入力ポートかファイル名を示す文字列でなければなりません。
入力ポートの場合、それはそのまま@var{proc}に渡されます。
文字列が渡された場合は、そのファイル名を持つファイルを入力用にオープンし、
そのポートが@var{proc}に渡され、またこのポートは@var{proc}が戻った時に閉じられます。
この引数が省略された場合は、現在の入力ポートが渡されます。
@c COMMON
@item output
@c EN
The argument must be either an output port or a string
that specifies a file name.
If it's an output port, it is passed to @var{proc} as is.
If it's a string, the named file is opened for output
(unless @var{temporary-file} is given, in that case
a temporary file is opened instead), and the resulting port
is passed to @var{proc}.  This port is closed when @var{proc} returns.
If this argument is omitted, the current output port is passed.
@c JP
この引数は出力ポートかファイル名を示す文字列でなければなりません。
出力ポートの場合、それはそのまま@var{proc}に渡されます。
文字列が渡された場合は、そのファイル名を持つファイルを出力用にオープンし、
そのポートが@var{proc}に渡されます (但し、@var{temporary-file}
引数が渡された時はそれに指定されるファイルが一時ファイルとしてオープンされます)。
オープンされたポートは@var{proc}が戻った時に閉じられます。
この引数が省略された場合は、現在の出力ポートが渡されます。
@c COMMON
@item temporary-file
@c EN
If a string file name is given to this argument, the named file
is opened for output during the processing, instead of the file
name as @var{output}.   The output port @var{proc} receives
is connected to this file.  When @var{proc}
returns normally, the file is renamed to the name given to @var{output}
keyword argument.

If the given file name begins with characters except @code{"/"}, @code{"./"}
or @code{"../"}, the directory of the file name given to @var{output} argument
is attached before it.
Furthermore, a unique name is attached to the temporary file name
(the temporary file is opened by @code{sys-mkstemp}.)

This argument is ignored when @var{output} argument is not a string
file name.
@c JP
文字列でファイル名が渡された場合、処理の間の出力先として@var{output}に指定された
ファイルのかわりにそのファイルがオープンされます。
@var{proc}にはその一時ファイルへの出力ポートが渡されます。
@var{proc}が正常に返って来た時点で、一時ファイルは@var{output}に指定された
ファイルへとリネームされます。

もし一時ファイル名が@code{"/"}、@code{"./"}、@code{"../"}以外の
文字で始まっていた場合は、@var{output}に与えられたファイル名のディレクトリが
一時ファイルの前に追加されます。さらに、ユニークなサフィックスが一時ファイルの後に
追加されます(一時ファイルは@code{sys-mkstemp}を使ってオープンされます)。

この引数は、@var{output}にファイル名が与えられなかった場合は無視されます。
@c COMMON
@item keep-output?
@c EN
If a true value is given, the output is not deleted even
when @var{proc} signals an error.
By default, the output (or the temporary file when
@var{temporary-file} is given) will be deleted on error.
@c JP
真の値が与えられた場合、@var{proc}がエラーになった場合でも出力ファイルを削除しません。
デフォルトでは、出力ファイル(もしくは@var{temporary-file}が与えられた場合は
そのファイル)はエラーの場合には削除されます。
@c COMMON
@end table
@end defun

@c ----------------------------------------------------------------------
@node Filesystem utilities, Mathematic constants, Filtering file content, Library modules - Utilities
@section @code{file.util} - Filesystem utilities
@c NODE ファイルシステムユーティリティ, @code{file.util} - ファイルシステムユーティリティ

@deftp {Module} file.util
@mdindex file.util
@c EN
Provides convenient utility functions handling files and directories.
Those functions are built on top of the primitive system
procedures described in @ref{Filesystems}.
@c JP
ファイルやディレクトリを扱う便利な手続き群を提供します。
これらの手続きは@ref{Filesystems}で述べられたプリミティブなシステム手続きの上に
構築されています。
@c COMMON

@c EN
Many procedures in this module takes a keyword argument @var{follow-link?},
which specifies the behavior when the procedure sees a symbolic link.
If true value is given to @var{follow-link?} (which is the default),
the procedure operates on the file referenced by the link; if false is 
given, it operates on the link itself.
@c JP
このモジュール内の多くの手続きは@var{follow-link?}というキーワード引数を取ります。
これは手続きがシンボリックリンクに出会ったときの動作を指定します。@var{follow-link?}が
真であれば、手続きはリンクの指す先のファイルに作用します。これがデフォルトの振舞いです。
@var{follow-link?}に@code{#f}が渡された場合は手続きはリンクそのものに作用します。
@c COMMON
@end deftp

@c EN
Note on the naming convention: Some Scheme implementations "create"
new directories and files, while the others "make" them.
Some implementations "delete" them, while the others "remove" them.
It seems that both conventions are equally popular.
So Gauche provides @emph{both}.
@c JP
名前つけ規則に関する注記：ファイルやディレクトリを
作成するのに@code{"create"}という語を使う処理系と@code{"make"}を
使う処理系があります。ファイルやディレクトリを削除するのにも@code{"remove"}と
@code{"delete"}の流派があります。どちらも同じくらい広く使われているようなので、
Gaucheでは@emph{両方の}名前を提供することにしました。
@c COMMON

@menu
* Directory utilities::         
* Pathname utilities::          
* File attribute utilities::    
* File operations::             
* Lock files::                  
@end menu

@node Directory utilities, Pathname utilities, Filesystem utilities, Filesystem utilities
@subsection Directory utilities
@c NODE ディレクトリユーティリティ

@defun current-directory :optional new-directory
@c EN
When called with no argument, this returns the pathname of the current
working directory.  When called with a string argument @var{new-directory},
this sets the current working directory of the process to it.
If the process can't change directory to @var{new-directory}, an error is
signalled.

This function is in ChezScheme, MzScheme and some other Scheme
implementations.
@c JP
引数無しで呼ばれた場合、カレントディレクトリを返します。
文字列@var{new-directory}が与えられた場合はプロセスのカレントディレクトリを
@var{new-directory}に変更します。変更が出来なかった場合はエラーとなります。

この関数はChezSchemeやMzSchemeなどいくつかのScheme処理系に見られます。
@c COMMON
@end defun

@defun home-directory :optional user
@c EN
Returns the home directory of the given @var{user},
which may be a string user name or an integer user id.
If @var{user} is omitted, the current user is assumed.
If the given user cannot be found, or the home directory
of the user cannot be determined, @code{#f} is returned.
@c JP
名前または整数のユーザidで与えられたユーザ@var{user}のホームディレクトリを
返します。@var{user}が省略された場合はカレントユーザが使われます。
与えられたユーザが見付けられないか、ホームディレクトリを決定できなかった場合は
@code{#f}が返されます。
@c COMMON

@c EN
On Windows native platforms, this function is only supported
to query the current user's directory.
@c JP
Windowsネイティブ環境では、この関数はカレントユーザに対してのみ動作します。
@c COMMON
@end defun

@deffn {Parameter} temporary-directory
@c EN
A parameter that keeps the name of the directory that can be used
to create a temporary files.   The default value is
the one returned from @code{sys-tmpdir} (@xref{Pathnames}).
The difference of @code{sys-tmpdir} is that, since this is a parameter,
it can be overridden by application during execution.
Libraries are recommended to use this instead of @code{sys-tmpdir}
for greater flexibility.
@c JP
一時ファイルを作るのに適したディレクトリ名を保持しているパラメータです。
デフォルトの値は@code{sys-tmpdir}の戻り値です (@ref{Pathnames}参照)。
@code{sys-tmpdir}との違いは、これはパラメータなので
アプリケーションが実行時に変更できることです。
ライブラリは柔軟性を高めるためにできるだけ@code{sys-tmpdir}よりは
こちらを利用するのが良いでしょう。
@c COMMON
@end deffn

@defun directory-list path :key children? add-path? filter filter-add-path?
@c EN
Returns a list of entries in the directory @var{path}.
The result is sorted by dictionary order.

By default, only the basename (the last component) of the entries
returned.   If @var{add-path?} is given and true, @var{path} is appended
to each entry.  If @var{children?} is given and true, @code{"."} and 
@code{".."} are excluded from the result.  

If @var{filter} is given, it must be a predicate that takes one argument.  
It is called on every element of the directory entry,
and only the entries on which
@var{filter} returns true are included in the result.
The argument passed to @var{filter} is a basename of the directory entry
by default, but when @var{filter-add-path?} is true, @var{path} is 
appended to the entry.

If @var{path} is not a directory, an error is signalled.
@c JP
ディレクトリ@var{path}中のエントリのリストを返します。
リストは文字列順にソートされます。

デフォルトではエントリのベースネーム(パスの最後のコンポーネント)のみが
返されますが、キーワード引数@var{add-path?}に真の値が与えられた時は
@var{path}が各エントリの前に追加されます。
@var{children?}に真の値が与えられた時は、カレントディレクトリと親ディレクトリが
リストから除かれます。

@var{filter}引数は、もし与えられれば、一つの引数を取る
手続きでなければなりません。ディレクトリ中の各エントリを引数としてその手続きが呼ばれ、
真を返したエントリのみが結果に含まれます。
@var{filter}に与えられるエントリはデフォルトではベース名のみですが、
引数@var{filter-add-path?}が真ならば@var{path}が前に追加された名前となります。

@var{path}がディレクトリでない場合はエラーが報告されます。
@c COMMON

@example
(directory-list "test")
 @result{} ("." ".." "test.scm" "test.scm~")

(directory-list "test" :add-path? #t)
 @result{} ("test/." "test/.." "test/test.scm" "test/test.scm~")

(directory-list "test" :children? #t)
 @result{} ("test.scm" "test.scm~")

(directory-list "test" :children? #t :add-path? #t
   :filter (lambda (e) (not (string-suffix? "~" e))))
 @result{} ("test/test.scm")
@end example
@end defun

@defun directory-list2 path :key children? add-path? filter follow-link?
@c EN
Like @code{directory-list}, but returns two values; the first one is a list
of subdirectories, and the second one is a list of the rest.
The keyword arguments @var{children?}, @code{add-path?} and @var{filter}
are the same as @code{directory-list}.

Giving false value to @var{follow-link?} makes @code{directory-list2}
not follow the symbolic links; if the @var{path} contains a
symlink to a directory,
it will be included in the first list if @var{follow-link?}
is omitted or true,
while it will be in the second list if @var{follow-link?} is false.
@c JP
@code{directory-list}に似ていますが、ふたつの値を返します。最初の値は
@var{path}内にあるサブディレクトリのリストで、次の値はそれ以外のエントリのリストです。
キーワード引数@var{children?}、@code{add-path?}、@var{filter}は
@code{directory-list}と同じ意味をもちます。

偽の値を@var{follow-link?}に与えると、@var{path}内のシンボリックリンクを
辿りません；すなわち、@var{path}内にディレクトリへのシンボリックリンクがあった場合、
デフォルト、もしくは@var{follow-link?}に真の値が与えられた場合は
それは最初のリスト(サブディレクトリ)に入りますが、@var{follow-link?}
に偽の値が与えられた場合は後者のリスト(その他のエントリ)に入ります。
@c COMMON
@end defun

@defun directory-fold path proc seed :key lister follow-link?
@c EN
A fundamental directory traverser.
Conceptually it works as follows, in recursive way.
@c JP
ディレクトリ探索の最も基本的な手続きです。基本的な動作は以下に示すような再帰的なものです。
@c COMMON

@c EN
@itemize @bullet
@item
If @var{path} is not a directory, calls 
@code{(@var{proc} @var{path} @var{seed})} and returns the result.
@item
If @var{path} is a directory, calls
@code{(@var{lister} @var{path} @var{seed})}.  The procedure @var{lister}
is expected to return two values: a list of pathnames, and the 
next seed value.   Then
@code{directory-fold} is called on each returned pathname,
passing the returned seed value to the @var{seed} argument of the
next call of @code{directory-fold}.
Returns the result of the last seed value.
@end itemize
@c JP
@itemize @bullet
@item
@var{path}がディレクトリでない場合は@code{(@var{proc} @var{path} @var{seed})} を
評価し、結果を返します。
@item
@var{path}がディレクトリであった場合、まず
@var{(@var{lister} @var{path} @var{seed})} を評価します。
手続き@var{lister}は2つの値、パス名のリストと次のseedとなる値を
返さなければなりません。
続いて、@code{directory-fold}が各パス名に対して再帰的に呼ばれます。
各呼び出しの結果が次の再帰呼び出しの@var{seed}の値に使われます。
@end itemize
@c COMMON

@c EN
The default procedure of @var{lister} is just a call to @code{directory-list},
as follows.
@c JP
デフォルトの@var{lister}は@code{directory-list}を次のように呼び出すものです。
@c COMMON
@example
(lambda (path seed)
  (values (directory-list path :add-path? #t :children? #t)
          seed))
@end example

@c EN
Note that @var{lister} shouldn't return the given path itself (@code{"."})
nor the parent directory (@code{".."}), or the recursion wouldn't
terminate.  Also note @var{lister} is expected to return a path accessible
from the current directory, i.e. if @var{path} is @code{"/usr/lib/foo"} and
it contains @code{"libfoo.a"} and @code{"libfoo.so"}, @var{lister} should
return @code{'("/usr/lib/foo/libfoo.a" "/usr/lib/foo/libfoo.so")}.
@c JP
@var{lister}は@var{path}自身への参照 (@code{"."}) やその親ディレクトリへの参照を
返してはなりません。また、@var{lister}の戻り値は現在のディレクトリからアクセス可能な
パス名でなければなりません。例えば@var{path}が@code{"/usr/lib/foo"}であり、
そのディレクトリが@code{"libfoo.a"}と@code{"libfoo.so"}を含んでいた場合、
@var{lister}は@code{'("/usr/lib/foo/libfoo.a" "/usr/lib/foo/libfoo.so")}
のようなリストを返す必要があります。
@c COMMON

@c EN
The keyword argument @var{follow-link?} is used to determine whether
@var{lister} should be called on a symbolic link pointing to a directory.
When @var{follow-link?} is true (default), @var{lister} is called
with the symbolic link if it points to a directory.
When @var{follow-link?} is false, @var{proc} is not called.
@c JP
キーワード引数@var{follow-link?}はディレクトリを指しているシンボリックリンクに対して
@var{lister}を呼ぶかどうかを決定します。@var{follow-link?}が真(デフォルト値)である
場合はそのようなシンボリックリンクに対しても@var{lister}が呼ばれます。
一方、@var{follow-link?}が偽であればシンボリックリンクに対しては@var{proc}が呼ばれます。
@c COMMON

@c EN
The following example returns a list of pathnames of the emacs backup files
(whose name ends with "~") under the given path.
@c JP
次の例は、与えられたpath以下からemacsのバックアップファイル ("~"で終る名を持つファイル)
のリストを返します。
@c COMMON
@example
(use srfi-13) ;; for string-suffix?
(directory-fold path
                (lambda (entry result) 
                  (if (string-suffix? "~" entry)
                      (cons entry result)
                      result))
                '())
@end example

@c EN
The following example lists all the files and directories under the
given pathname.   Note the use of @var{lister} argument to include
the directory path itself in the result.
@c JP
次の例は与えられたpath以下全てのファイルとディレクトリ名をリストにして
返します。@var{lister}引数を使ってディレクトリ名そのものを結果に
含めていることに注目して下さい。
@c COMMON
@example
(directory-fold path cons '()
  :lister (lambda (path seed)
            (values (directory-list path :add-path? #t :children? #t)
                    (cons path seed))))
@end example

@end defun

@defun make-directory* name :optional perm
@defunx create-directory* name :optional perm
@c EN
Creates a directory @var{name}.  If the intermediate path to the
directory doesn't exist, they are also created
(like @code{mkdir -p} command on Unix).   If the directory
@var{name} already exist, these procedure does nothing.
@var{Perm} specifies the integer flag for permission bits of the
directory.
@c JP
ディレクトリ@var{name}を作成します。@var{name}に至るパスが存在しない
場合は必要なディレクトリが作成されます (Unixの@code{mkdir -p}コマンドと
同様です)。ディレクトリ@var{name}が既に存在していた場合は何もしません。
@var{perm}は作成されるディレクトリのパーミッションビットを指定します。
@c COMMON
@end defun


@defun remove-directory* name
@defunx delete-directory* name 
@c EN
Deletes directory @var{name} and its content recursively 
(like @code{rm -r} command on Unix).   Symbolic links are not
followed.
@c JP
ディレクトリ@var{name}とその内容を再帰的に消去します
(Unixの@code{rm -r}コマンドと同様です)。シンボリックリンクは辿られません。
@c COMMON
@end defun

@defun copy-directory* src dst :key if-exists backup-suffix safe keep-timestamp keep-mode follow-link?
@c EN
If @var{src} is a regular file, copies its content to @var{dst}, just like
@code{copy-file} does.  If @var{src} is a directory, recursively
desends it and copy the file tree to @var{dst}.  Basically
it mimics the behavior of @code{cp -r} command.

If there's any symbolic links under @var{src}, the link itself
is copied instead of the file pointed to by it, unless a true value
is given to the @var{follow-link?} keyword argument,
i.e. the default value of @var{follow-link?} is @code{#f}.
(Note that this is opposite to the @code{copy-file}, in which
@var{follow-link?} is true by default.)
@c JP
@var{src}が通常のファイルであれば、@code{copy-file}と同じように
その内容を@var{dst}にコピーします。しかし@var{src}がディレクトリの場合は、
再帰的にディレクトリを辿り、その全てを@var{dst}へとコピーします。
@code{cp -r}コマンドに相当するものだと考えて良いでしょう。

@var{src}がディレクトリの場合、デフォルトではその下にあるシンボリックリンクは
辿られず、リンクそのものがコピーされます。リンク先の内容をもコピーしたい
場合は@var{follow-link?}キーワード引数に真の値を与えてください。
つまり、@var{follow-link?}キーワード引数のデフォルト値は@code{#f}です。
(このデフォルト値は@code{copy-file}と逆であることに注意してください。
@code{copy-file}では@var{follow-link?}はデフォルトで真であり、
リンクそのものをコピーしたい場合に明示的に@code{#f}を与える必要があります。)
@c COMMON

@c EN
The meanings of the other keyword arguments are the same as
@code{copy-file}.  See the entry of @code{copy-file} for the details.
@c JP
他のキーワード引数の意味は@code{copy-file}と同じです。
詳細は@code{copy-file}を参照してください。
@c COMMON
@end defun

@defun create-directory-tree dir spec
@c EN
Creates a directory tree under @var{dir} according to @var{spec}.
This procedure is useful to set up certain directory hierarchy at once.

The @var{spec} argument is an S-expression with the following structure:

@example
<spec> : <name>                             ; empty file
       | (<name> <option> ...)              ; empty file
       | (<name> <option> ... <string>)     ; file with content
       | (<name> <option> ... <procedure>)  ; file with generated content
       | (<name> <option> ... (<spec> ...)) ; directory

<name> : string or symbol

<option> ... : keyword-value alternating list
@end example
@c JP
@var{spec}で指定されるディレクトリツリーを@var{dir}の下に作成します。
特定のディレクトリ構造を一気にセットアップする際に便利です。

@var{spec}引数は次に示される構造をもつS式です。

@example
<spec> : <name>                             ; 空のファイル
       | (<name> <option> ...)              ; 空のファイル
       | (<name> <option> ... <string>)     ; 固定内容のファイル
       | (<name> <option> ... <procedure>)  ; 内容を生成するファイル
       | (<name> <option> ... (<spec> ...)) ; ディレクトリ

<name> : 文字列かシンボル

<option> ... : キーワードと値の交代リスト
@end example
@c COMMON

@c EN
With the first and second form of @var{spec}, an empty file is created
with the given name.
With the third form of @var{spec}, the string becomes the
content of the file.  

With the fourth form of @var{spec}, the procedure is called with the
pathname as an argument, and output to the current output
port within the procedure is written to the created file.
The pathname is relative to the @var{dir} argument.
At the time the procedure is called, its parent directory
is already created.

The last form of @var{spec} creates a named directory,
then creates its children recursively according to the specs.
@c JP
@var{spec}の最初と2番目の形式では、名前@var{name}を持つ空のファイルが作られます。
3番目の形式では与えられた文字列がファイルの内容となります。

4番目の形式では、手続きがファイルのパス名を引数として呼び出され、
その手続きがcurrent output portに出力した内容がファイルの内容となります。
引数に渡されるパス名は@var{dir}引数からの相対パスです。
手続きが呼ばれる時、その親ディレクトリは既につくられています。

最後の形式は、名前@var{name}を持つディレクトリを作成し、
その子供として再帰的に指定された@var{spec}によるファイル/ディレクトリを作成します。
@c COMMON

@c EN
With @var{option}s you can control attributes of created files/directories.
Currently the following options are recognized.

@table @code
@item :mode @var{mode}
Takes integer as permission mode bits.
@item :owner @var{uid}
@itemx :group @var{gid}
Takes integer uid/gid of the owner/group of the file/directory.
Calling process may need special priviledge to change the owner
and/or group.
@item :symlink @var{path}
This is only valid for file spec, and it causes 
@code{create-directory-tree} to create a named symbolic link
whose content is @var{path}.
@end table
@c JP
@var{option}によって、作られるファイル/ディレクトリの属性を細かく指定できます。
今のところ、次のオプションが認識されます。

@table @code
@item :mode @var{mode}
整数@var{mode}でパーミッションのモードビットを指定します。
@item :owner @var{uid}
@itemx :group @var{gid}
整数@var{uid}/@var{gid}で作成されるエントリのオーナー/グループを指定します。
作成されるエントリのオーナー/グループを変更するには、
呼び出すプロセスに特権が必要かもしれません。
@item :symlink @var{path}
ファイルを作成する@var{spec}でのみ有効なオプションで、
@var{path}を指すシンボリックリンクを作成します。
@end table
@c COMMON
@end defun

@defun check-directory-tree dir spec
@c EN
Checks if a directory hierarchy according to @var{spec} exists
under @var{dir}.  Returns @code{#t} if it exists, or @var{#f} otherwise.

The format of @var{spec} is the same
as @code{create-directory-tree} described above.

If @var{spec} contains options, the attributes of existing 
files/directories are also checked if they match the given options.
@c JP
@var{spec}で記述されるディレクトリ階層が@var{dir}の下に存在するかどうかを
調べ、存在すれば@code{#t}、そうでなければ@code{#f}を返します。

@var{spec}の形式は上で説明した@code{create-directory-tree}と同じです。

@var{spec}がオプションを含んでいる場合、該当するファイル/ディレクトリの
属性もそのオプションに合致するかどうかチェックされます。
@c COMMON
@end defun


@node Pathname utilities, File attribute utilities, Directory utilities, Filesystem utilities
@subsection Pathname utilities
@c NODE パスネームユーティリティ

@defun build-path base-path component @dots{}
@c EN
Appends pathname components @var{component} to the @var{base-path}.
@var{Component} can be a symbol @code{up} or @code{same};
in Unix, they are synonym to @code{".."} and @code{"."}.
This API is taken from MzScheme.
@c JP
パス名のコンポーネント@var{component}を@var{base-path}に追加します。
@var{Component}はシンボル@code{up}または@code{same}であっても
構いません; Unixではそれらは@code{".."}または@code{"."}と等価です。
このAPIはMzSchemeから採られました。
@c COMMON
@end defun

@defun absolute-path? path
@defunx relative-path? path
@c EN
Returns @code{#t} if @var{path} is absolute or relative, respectively.
@c JP
@var{path}がそれぞれ絶対パスまたは相対パスならば@code{#t}を返します。
@c COMMON
@end defun

@defun expand-path path
@c EN
Expands tilda-notation of @var{path} if it contains one.
Otherwise, @var{path} is returned.  This function does not
check if @var{path} exists and/or readable.
@c JP
@var{path}がチルダ表記を含んでいたらそれを展開したものを返します。
そうでなければ@var{path}そのものを返します。この手続きは@var{path}が
存在しアクセス可能であるかどうかはチェックしません。
@c COMMON
@end defun

@defun resolve-path path
@c EN
Expands @var{path} like @code{expand-path},
then resolve symbolic links for every components
of the path.  If @var{path} does not exist, or contains dangling link,
or contains unreadable directory, an error is signalled.
@c JP
@var{path}を@code{expand-path}と同様に展開し、
続いて@var{path}の各コンポーネントに対してそれがシンボリックリンクであればリンク先の
ものに置き換えてゆきます。@var{path}が存在しないパスを指していたり、
シンボリックリンクの先が存在しなかったり、読み出せないディレクトリがあった場合は
エラーとなります。
@c COMMON
@end defun

@defun simplify-path path
@c EN
Remove 'up' (@code{".."}) components and 'same' (@code{"."}) components
from @var{path} as much as possible.
This function does not access the filesystem.
@c JP
@var{path}から、親ディレクトリへの参照(@code{".."})と自分自身への参照(@code{"."})を
出来る限り取り除きます。この手続きはファイルシステムへはアクセスしません。
@c COMMON
@end defun

@defun decompose-path path
@c EN
Returns three values; the directory part of @var{path},
the basename without extension of @var{path}, and
the extension of @var{path}.    If the pathname doesn't have an extension,
the third value is @code{#f}.  If the pathname ends with a directory
separator, the second and third values are @code{#f}. (Note: This treatment
of the trailing directory separator differs from 
@code{sys-dirname}/@code{sys-basename}; those follow popular shell's
convention, which ignores trailing slashes.)
@c JP
パス名@var{path}のディレクトリ部、拡張子を除いたファイル名、
そして拡張子の3つの値を返します。パス名が拡張子を持たない場合、
最後の値は@code{#f}になります。パス名がディレクトリセパレータで
終わっている場合は2番目と3番目の値が@code{#f}になります。
(後置されたディレクトリセパレータに関するこの取扱いは、
@code{sys-dirname}/@code{sys-basename}と異なることに注意して下さい。
@code{sys-dirname}等は後置されたディレクトリセパレータを無視するという
シェル等の慣習に従っています。)
@c COMMON
@example
(decompose-path "/foo/bar/baz.scm")
  @result{} "/foo/bar", "baz", "scm"
(decompose-path "/foo/bar/baz")
  @result{} "/foo/bar", "baz", #f

(decompose-path "baz.scm")
  @result{} ".", "baz", "scm"
(decompose-path "/baz.scm")
  @result{} "/", "baz", "scm"

;; Boundary cases
(decompose-path "/foo/bar/baz.")
  @result{} "/foo/bar", "baz", ""
(decompose-path "/foo/bar/.baz")
  @result{} "/foo/bar", ".baz", #f
(decompose-path "/foo/bar.baz/")
  @result{} "/foo/bar.baz", #f, #f
@end example
@end defun

@defun path-extension path
@defunx path-sans-extension path
@c EN
Returns an extension of @var{path},
and  a pathname of @var{path} without extension, respectively.
If @var{path} doesn't have an extension, @code{#f} and @var{path}
is returned respectively.
@c JP
それぞれ、@var{path}の拡張子と、@var{path}から拡張子を除いたものを返します。
@var{path}が拡張子を持っていない場合はそれぞれ@code{#f}と@var{path}が返されます。
@c COMMON

@example
(path-extension "/foo/bar.c")       @result{} "c"
(path-sans-extension "/foo/bar.c")  @result{} "/foo/bar"

(path-extension "/foo/bar")         @result{} #f
(path-sans-extension "/foo/bar")    @result{} "/foo/bar"
@end example
@end defun

@defun path-swap-extension path newext
@c EN
Returns a pathname in which the extension of @var{path} is replaced
by @var{newext}.  If @var{path} doesn't have an extension,
"." and @var{newext} is appended to @var{path}.  

If @var{newext} is @code{#f}, it returns @var{path} without extension.
@c JP
@var{path}の拡張子が@var{newext}に置換されたものが返されます。@code{path}が
拡張子を持たない場合は、@var{path}に "." と@var{newext}が追加されます。

@var{newext}が@code{#f}の場合は、@var{path}の拡張子が除かれたものが
返されます。すなわち、
@c COMMON

@example
(path-swap-extension "/foo/bar.c" "o")  @result{} "/foo/bar.o"
(path-swap-extension "/foo/bar.c" #f)   @result{} "/foo/bar"
@end example
@end defun

@defun find-file-in-paths name :key paths pred
@c EN
Looks for a file that has name @var{name} in the given list of pathnames
@var{paths} and that satisfies a predicate @var{pred}.  If found,
the absolute pathname of the file is returned.  Otherwise, @code{#f}
is returned.

If @var{name} is an absolute path, only the existence of @var{name}
and whether it satisfies @var{pred} are checked.

The default value of @var{paths} is taken from the environment variable
@code{PATH}, and the default value of @var{pred} is @code{file-is-executable?}
(@xref{File attribute utilities}).  That is, @code{find-file-in-paths}
searches the named executable file in the command search paths
by default.
@c JP
名前@var{name}を持ち、述語@var{pred}を満たすファイルをパス名のリスト@var{paths}
から探します。見つかった場合はファイルの絶対パス名を、見つからなかった場合は
@code{#f}を返します。

@var{name}が絶対パス名で与えられた場合はそれが存在するかどうかと
@var{pred}を満たすかどうかのみがチェックされます。

@var{paths}のデフォルト値は環境変数@code{PATH}から取られます。また、
@var{pred}のデフォルト値は@code{file-is-executable?}
(@ref{File attribute utilities}参照)です。すなわち、デフォルトでは
この手続きはコマンドサーチパスから実行可能ファイルを探すのに使えます。
@c COMMON

@example
(find-file-in-paths "ls")
  @result{} "/bin/ls"

@c EN
;; @r{example of searchin user preference file of my application}
@c JP
;; @r{アプリケーション"myapp"のユーザプレファレンスファイルを探す例}
@c COMMON
(find-file-in-paths "userpref"
  :paths `(,(expand-path "~/.myapp")
           "/usr/local/share/myapp"
           "/usr/share/myapp")
  :pred  file-is-readable?)
@end example
@end defun

@defun null-device
@c EN
Returns a name of the @emph{null} device.  
On unix platforms (including cygwin) it returns @code{"/dev/null"},
and on Windows native platforms (including mingw) it returns @code{"NUL"}.
@c JP
nullデバイス名を返します。cygwinを含むunixプラットフォームでは
@code{"/dev/null"}、mingwを含むWindowsネイティブプラットフォームでは
@code{"NUL"}が返されます。
@c COMMON
@end defun

@defun console-device
@c EN
Returns a name of the console device.
On unix platforms (including cygwin) it returns @code{"/dev/tty"},
and on Windows native platforms (including mingw) it returns @code{"CON"}.

This function does not guarantee the device is actually available
to the calling process.
@c JP
コンソールデバイス名を返します。cygwinを含むunixプラットフォームでは
@code{"/dev/tty"}、mingwを含むWindowsネイティブプラットフォームでは
@code{"CON"}が返されます。

そのデバイスが実際に現在のプロセスから利用可能であるかどうかはチェックされません。
@c COMMON
@end defun


@node File attribute utilities, File operations, Pathname utilities, Filesystem utilities
@subsection File attribute utilities
@c NODE ファイル属性ユーティリティ

@defun file-type path :key follow-link?
@defunx file-perm path :key follow-link?
@defunx file-mode path :key follow-link?
@defunx file-ino path :key follow-link?
@defunx file-dev path :key follow-link?
@defunx file-rdev path :key follow-link?
@defunx file-nlink path :key follow-link?
@defunx file-uid path :key follow-link?
@defunx file-gid path :key follow-link?
@defunx file-size path :key follow-link?
@defunx file-atime path :key follow-link?
@defunx file-mtime path :key follow-link?
@defunx file-ctime path :key follow-link?
@c EN
These functions return the attribute of file/directory specified by
@var{path}.  The attribute name corresponds to the slot name of
@code{<sys-stat>} class (@xref{File stats}).
If the named path doesn't exist, @code{#f} is returned.

If @var{path} is a symbolic link, these functions queries the
attributes of the file pointed by the link, unless
an optional argument @var{follow-link?} is given and false.

MzScheme and Chicken have @code{file-size}.  Chicken also has
@code{file-modification-time}, which is @code{file-mtime}.
@c JP
これらの手続きは@var{path}で示されるファイルやディレクトリのアトリビュートを
返します。アトリビュート名は@code{<sys-stat>}のスロット名に対応しています。
@ref{File stats}を参照して下さい。@var{path}で示されるファイルが
存在しなければ@code{#f}が返されます。

@var{path}がシンボリックリンクだった場合、オプショナルな引数
@var{follow-link?} に偽の値が与えられていない限り、これらの手続きは
リンクの指す先のファイルに関する情報を返します。

MzSchemeとChickenには@code{file-size}があります。
Chickenには@code{file-modification-time}があり、これは@code{file-mtime}と
同じです。
@c COMMON
@end defun

@defun file-is-readable? path
@defunx file-is-writable? path
@defunx file-is-executable? path
@c EN
Returns @code{#t} if @var{path} exists and readable/writable/executable
by the current effective user, respectively.
This API is taken from STk.
@c JP
@var{path}が存在して、現在の実効ユーザがそれぞれ読み取り/書き込み/実行可能なら@code{#t}を
返します。
このAPIはSTkから取られました。
@c COMMON
@end defun

@defun file-is-symlink? path
@c EN
Returns @code{#t} if @var{path} exists and a symbolic link.
See also @code{file-is-regular?} and @code{file-is-directory?} in
@ref{File stats}.
@c JP
@var{path}が存在して、それがシンボリックリンクなら@code{#t}を返します。
(参照：@ref{File stats}の@code{file-is-regular?}, @code{file-is-directory?}).
@c COMMON
@end defun

@defun file-eq? path1 path2
@defunx file-eqv? path1 path2
@defunx file-equal? path1 path2
@c EN
Compares two files specified by @var{path1} and @var{path2}.
@code{file-eq?} and @code{file-eqv?} checks if @var{path1} and @var{path2}
refers to the identical file, that is, whether they are on the same
device and have the identical inode number.  The only difference is
when the last component of @var{path1} and/or @var{path2} is a symbolic
link, @code{file-eq?} doesn't resolve the link (so compares the links
themselves) while @var{file-eqv?} resolves the link and compares the
files referred by the link(s).
@c JP
@var{path1}と@var{path2}で示されるファイルを比較します。
@code{file-eq?}と@code{file-eqv?}は@var{path1}と@var{path2}が
全く同一のファイルを参照しているかどうか、すなわち、同じデバイス上にあり同じ
inode番号を持つかどうかをチェックします。二つの手続きの違いは、
@code{path1}や@var{path2}の最後のコンポーネントがシンボリックリンクで
あった場合に、@var{file-eq?}はリンクそのものの比較をするが
@code{file-eqv?}はリンクを辿った先のファイルの比較をする、という点です。
@c COMMON

@c EN
@code{file-equal?} compares @var{path1} and @var{path2} considering their
content, that is, when two are not the identical file in the sense of
@code{file-eqv?}, @code{file-equal?} compares their content and returns
@code{#t} if all the bytes match.
@c JP
@code{file-equal?}は@var{path1}と@var{path2}をその内容まで考慮して比較します。
すなわち、二つのファイルが@code{file-eqv?}の意味で同一でなかった場合、
@code{file-equal?}はファイルの内容を比較し、全てが一致した場合に@code{#t}を返します。
@c COMMON

@c EN
The behavior of @code{file-equal?} is undefined
when @var{path1} and @var{path2} are both directories.
Later, it may be extended to scan the directory contents.
@c JP
@var{path1}と@var{path2}ともにディレクトリが与えられた場合の
@code{file-equal?}の動作は未定義です。将来、ディレクトリ内容を
スキャンするような拡張が加えられるかもしれません。
@c COMMON
@end defun

@deffn {Generic Function} file-mtime=? f1 f2
@deffnx {Generic Function} file-mtime<? f1 f2
@deffnx {Generic Function} file-mtime<=? f1 f2
@deffnx {Generic Function} file-mtime>? f1 f2
@deffnx {Generic Function} file-mtime>=? f1 f2
@c EN
Compares file modification time stamps.  There are a bunch of methods defined,
so each argument can be either one of the followings.

@itemize @bullet
@item
String pathname.   The mtime of the specified path is used.
@item
@code{<sys-stat>} object (@xref{File stats}).
The mtime is taken from the stat structure.
@item
@code{<time>} object.  The time is used as the mtime.
@item
Number.  It is considered as the number of seconds since Unix Epoch, and
used as mtime.
@end itemize
@c JP
二つのファイルの変更時間を比較します。それぞれの引数に対して、
次のような型のオブジェクトが渡せるようなメソッドが定義されています。

@itemize @bullet
@item
文字列のパス名。そのパス名で示されるファイルから変更時間が取られます。
@item
@code{<sys-stat>}オブジェクト (@xref{File stats})。
stat構造体から変更時間が取られます。
@item
@code{<time>}オブジェクト。その示す時間が変更時間と考えられます。
@item
数値。変更時間をUnix Epochからの秒数で表したものと見なされます。
@end itemize
@c COMMON

@example
@c EN
;; @r{compare "foo.c" is newer than "foo.o"}
@c JP
;; @r{"foo.c" より "foo.o" が新しいかどうか調べる}
@c COMMON
(file-mtime>? "foo.c" "foo.o")

@c EN
;; @r{see if "foo.log" is updated within last 24 hours}
@c JP
;; @r{"foo.log"が過去24時間以内に更新されたかどうかを調べる}
@c COMMON
(file-mtime>? "foo.c" (- (sys-time) 86400))
@end example
@end deffn

@deffn {Generic Function} file-ctime=? f1 f2
@deffnx {Generic Function} file-atime=? f1 f2
@findex file-ctime<?
@findex file-ctime<=?
@findex file-ctime>?
@findex file-ctime>=?
@findex file-atime<?
@findex file-atime<=?
@findex file-atime>?
@findex file-atime>=?
@c EN
Same as @code{file-mtime=?}, except these checks file's change time
and access time, respectively.
All the variants of @code{<}, @code{<=}, @code{>}, @code{>=} are also
defined.
@c JP
@code{file-mtime=?}と同じですが、ファイルの属性変更時間とアクセス時間に
関して比較します。
@code{<}, @code{<=}, @code{>}, @code{>=}を使う関数も同様に定義されています。
@c COMMON
@end deffn

@node File operations, Lock files, File attribute utilities, Filesystem utilities
@subsection File operations
@c NODE ファイル操作

@defun touch-file path
@defunx touch-files paths
@c EN
Updates timestamp of @var{path}, or each path in the list @var{paths},
to the current time.  If the specified path
doesn't exist, a new file with size zero is created.
See also @code{sys-utime} (@xref{File stats}).
@c JP
@var{path}もしくはリスト@var{paths}中の各パスの
タイムスタンプを現在の時刻に更新します。
指定されたパスが存在しなかった場合はその名前で大きさゼロのファイルが作成されます。
@ref{File stats}の@code{sys-utime}も参照して下さい。
@c COMMON
@end defun

@defun copy-file src dst :key if-exists backup-suffix safe keep-timestamp keep-mode follow-link?
@c EN
Copies file from @var{src} to @var{dst}.  The source file @var{src} must exist.
The behavior when the destination @var{dst} exists varies by the keyword
argument @var{if-exists};

@table @code
@item :error
(Default) Signals an error when @var{dst} exists.
@item :supersede
Replaces @var{dst} to the copy of @code{src}. 
@item :backup
Keeps @var{dst} by renaming it.
@item #f
Doesn't copy and returns @code{#f} when @var{dst} exists.
@end table
@c JP
ファイル@var{src}を@var{dst}へコピーします。コピー元ファイル@var{src}は
存在していなければなりません。コピー先ファイル@var{dst}が存在していた場合の
ふるまいはキーワード引数@var{if-exists}によって以下のように指定されます。

@table @code
@item :error
(デフォルト) @var{dst}が存在していたらエラーを通知する。
@item :supersede
@var{dst}を@code{src}のコピーで置き換える。
@item :backup
@var{dst}の名前を変えてキープする。
@item #f
@var{dst}が存在していたらコピーをせず@code{#f}を返す。
@end table
@c COMMON

@c EN
@code{Copy-file} returns @code{#t} after completion.
@c JP
@code{copy-file}はコピーが完了したら@code{#t}を返します。
@c COMMON

@c EN
If @var{src} is a symbolic link, @code{copy-file} follows the
symlink and copies the actual content by default.  An error
is raised if @var{src} is a dangling symlink.

Giving @code{#f} to the keyword argument @var{follow-link?} 
makes @code{copy-file} to copy the link itself.
It is possible that @var{src} is a dangling 
symlink in this case.
@c JP
@var{src}がシンボリックリンクであった場合、@code{copy-file}は
デフォルトでリンクを辿ります。つまり、ファイルの実体がコピーされます。
@var{src}が存在しないパスを指すシンボリックリンクであった場合は
エラーが通知されます。

キーワード引数@var{follow-link?}に@code{#f}を与えることで、
@code{copy-link}にシンボリックリンクそのものをコピーさせることも
できます。この場合、@var{src}が存在しないパスを指すシンボリックリンクで
あっても構いません。
@c COMMON

@c EN
If @var{if-exists} is @code{:backup}, the keyword argument @var{backup-suffix}
specifies the suffix attached to the @var{dst} to be renamed.
The default value is @code{".orig"}.
@c JP
@var{if-exists}が@code{:backup}である場合、
@var{dst}がリネームされる名前は
@var{dst}にキーワード引数@var{backup-suffix}で指定されるサフィックスを
付けたものとなります。デフォルト値は@code{".orig"}です。
@c COMMON

@c EN
By default, @code{copy-file} starts copying to @var{dst} directly.
However, if the keyword argument @var{safe} is a true value,
it copies the file to a temporary file in the same directory of @var{dst},
then renames it to @var{dst} when copy is completed.
If copy is interrupted for some reason, the filesystem is "rolled back"
properly.
@c JP
デフォルトでは@code{copy-file}は直接@var{dst}にコピーを行いますが、
キーワード引数@var{safe}に真の値が与えられた場合は、@var{dst}と同じディレクトリ
内の一時ファイルにまずコピーし、それが完了した時点で@var{dst}へとリネームします。
コピーが何らかの理由で中断された場合、ファイルシステムはコピー前の状態へと
「ロールバック」されます。
@c COMMON

@c EN
If the keyword argument @var{keep-timestamp} is true, @code{copy-file}
sets the destination's timestamp to the same as the source's timestamp
after copying.
@c JP
キーワード引数@var{keep-timestamp}に真の値が与えられた場合は、
@code{copy-file}はコピー後にコピー先のファイルのタイムスタンプを
コピー元のタイムスタンプに合わせます。
@c COMMON

@c EN
If the keyword argument @var{keep-mode} is true, the destination file's 
permission bits are set to the same as the source file's.  If it is false
(default), the destination file's permission remains the same if
the destination already exists and the @var{safe} argument is false,
otherwise it becomes @code{#o666} masked by umask settings.
@c JP
キーワード引数@var{keep-mode}に真の値が与えられた場合は、
コピー先のファイルのパーミッションビットはコピー元のそれに合わせられます。
@var{keep-mode}が偽の場合(デフォルト)は、コピー先が既に存在して
@var{safe}引数が偽の場合にコピー先のもとのパーミッションが保持され、
そうでなければ@code{#o666}がumaskセッティングによってマスクされた
値となります。
@c COMMON
@end defun

@c @defun copy-files files dstdir :key if-exists backup-suffix safe keep-timestamp keep-mode follow-link?
@c @c EN
@c Copies each file in a list @var{files} to the destination @var{dstdir}, which
@c must be an existing directory.  The keyword arguments are passed
@c to @code{copy-file}.
@c @c JP
@c リスト@var{files}中の各ファイルをディレクトリに@var{dstdir}にコピーします。
@c @var{dstdir}は既に存在しなければなりません。
@c キーワード引数はそのまま@code{copy-file}に渡されます。
@c @c COMMON
@c @end defun

@defun move-file src dst :key if-exists backup-suffix
@c EN
Moves file @var{src} to @var{dst}.   The source @var{src} must exist.
The behavior when @var{dst} exists varies by the keyword argument
@var{if-exists}, as follows.
@table @code
@item :error
(Default) Signals an error when @var{dst} exists.
@item :supersede
Replaces @var{dst} by @code{src}. 
@item :backup
Keeps @var{dst} by renaming it.
@item #f
Doesn't move and returns @code{#f} when @var{dst} exists.
@end table
@c JP
ファイル@var{src}を@var{dst}へ移動します。移動元ファイル@var{src}は
存在していなければなりません。移動先ファイル@var{dst}が存在した場合の
ふるまいはキーワード引数@var{if-exists}によって以下のように指定されます。
@table @code
@item :error
(デフォルト) @var{dst}が存在していたらエラーを通知する。
@item :supersede
@var{dst}を@code{src}で置き換える。
@item :backup
@var{dst}の名前を変えてキープする。
@item #f
@var{dst}が存在していたら移動をせず@code{#f}を返す。
@end table
@c COMMON

@c EN
@code{Move-file} returns @code{#t} after completion.
@c JP
@code{move-file}は移動が完了したら@code{#t}を返します。
@c COMMON

@c EN
If @var{if-exists} is @code{:backup}, the keyword argument @var{backup-suffix}
specifies the suffix attached to the @var{dst} to be renamed.
The default value is @code{".orig"}.
@c JP
@var{if-exists}が@code{:backup}である場合、@var{dst}がリネームされる
名前は@var{dst}にキーワード引数@var{backup-suffix}で指定されるサフィックスを
付けたものとなります。デフォルト値は@code{".orig"}です。
@c COMMON

@c EN
The file @var{src} and @var{dst} can be on the different filesystem.
In such a case, @code{move-file} first copies @var{src} to the
temporary file on the same directory as @var{dst}, then renames
it to @var{dst}, then removes @var{src}.
@c JP
ファイル@var{src}と@var{dst}は別のファイルシステム上にあっても構いません。
その場合、@code{move-file}はまず@var{src}を@var{dst}と同じディレクトリの
一時ファイルにコピーし、それを@var{dst}にリネームし、それから
@var{src}を消去します。
@c COMMON
@end defun

@c @defun move-files files dstdir :key if-exists backup-suffix
@c @c EN
@c Moves each file in a list @var{files} to @var{dstdir},
@c which must be an existing directory.  Keyword arguments
@c are passed to @code{move-file}.
@c @c JP
@c リスト@var{files}中の各ファイルをディレクトリ@var{dstdir}に移動します。
@c @var{dstdir}は既に存在しなければなりません。
@c キーワード引数はそのまま@code{move-file}に渡されます。
@c @c COMMON
@c @end defun

@defun remove-files paths
@defunx delete-files paths
@c EN
Removes each path in a list @var{paths}.  If the path is 
a file, it is @code{unlink}ed.  If it is a directory,
its contents are recursively removed by @code{remove-directory*}.
If the path doesn't exist, it is simply ignored.

@code{delete-files} is just an alias of @code{remove-files}.
@c JP
リスト@var{paths}中の各パスを削除します。パスがファイルの場合は
@code{unlink}し、ディレクトリの場合は@code{remove-directory*}を
使って再帰的にその内容を消去します。存在しないパスは単に無視されます。

@code{delete-files}は@code{remove-files}の別名です。
@c COMMON
@end defun


@defun file->string filename options @dots{}
@defunx file->list reader filename options @dots{}
@defunx file->string-list filename options @dots{}
@defunx file->sexp-list filename options @dots{}
@c EN
Convenience procedures to read from a file @var{filename}.
They first open the named file, then call @code{port->string},
@code{port->list}, @code{port->string-list} and @code{port->sexp-list}
on the opened file, respectively.  (@xref{Input utility functions}).
The file is closed if all the content is read or an error is
signalled during reading.
@c JP
ファイル @var{filename} から読み込むための便利手続き。
これらの手続きは、まず、指定された名前のファイルをオープンし、その
オープンしたファイルに対してそれぞれ @code{port->string}、
@code{port->list}、@code{port->string-list} および @code{port->sexp-list}
を呼びます(@ref{Input utility functions}参照)。すべての内容が読み込まれる
かまたは読み込み中にエラーシグナルがあがれば、ファイルはクローズされます。
@c COMMON

@c EN
Those procedures take the same keyword arguments as
@code{call-with-input-file}.
When the named file doesn't exist, the behavior depends on 
@var{:if-does-not-exist} keyword argument---an error is signalled
if it is @code{:error}, and @code{#f} is returned if the argument is
@code{#f}.
@c JP
これらの手続きは@code{call-with-input-file}と同じキーワード引数を取ります。
ファイルが見つからなかった場合の振舞いは
キーワード引数@code{:if-does-not-exist}によって指定できます。
それが@code{:error}ならエラーが報告され、
@code{#f}なら@code{#f}が返されます。
@c COMMON
@end defun

@node Lock files,  , File operations, Filesystem utilities
@subsection Lock files
@c NODE ロックファイル

Exclusive creation of files or directories is often used
for inter-process locking.   The following procedure provides
a packaged interface for it.

@defun with-lock-file lock-name thunk :key type retry-interval @
                      retry-limit secondary-lock-name retry2-interval @
                      retry2-limit perms abandon-timeout

Exclusively creates a file or a directory (@emph{lock file})
with @var{lock-name}, then executes @var{thunk}.
After @var{thunk} returns, or an error is thrown in it,
the lock file is removed.  When @var{thunk} returns normally,
its return values become the return values of @code{with-lock-file}.

If the lock file already exists, @code{with-lock-file} waits and retries
getting the lock until timeout reaches.  It can be configured by
the keyword arguments.

There's a chance that @code{with-lock-file} leaves the lock file
when it gets a serious error situation and doesn't have the opportunity
to clean up.  You can allow @code{with-lock-file} to @emph{steal}
the lock if its timestamp is too old; say, if you know that the
applications usually locks just for seconds, and you find the lock
file is 10 minutes old, then it's likely that the previous
process was terminated abruptly and couldn't clean it up.
You can also configure this behavior by the keyword arguments.

Internally, @emph{two} lock files are used to implement this
stealing behavior safely.  The creation and removal of the primary
lock file (named by @var{lock-name} argument) are guarded by
the secondary lock file (named by @var{secondary-lock-file} argument,
defaulted by @code{.2} suffix attached to @var{lock-name}).
The secondary lock is aquired for a very short period so there's
much less chance to be left behind by abnormal terminations.
If it happens, however, we just give up; we don't steal the
secondary lock.

If @code{with-lock-file} couldn't get a lock before timeout,
a @code{<lock-file-failure>} condition is thrown.

Here's a list of keyword arguments.

@table @var
@item type

It can be either one of the symbols @code{file} or @code{directory}.

If it is @code{file}, we use a lock file, relying on the @code{O_EXCL}
exclusive creation flag of @code{open(2)}.  It works for most platforms;
however, some NFS implementation may not implement the exclusive
semantics properly.   This is the default value.

If it is @code{directory}, we use a lock directory, relying on the
atomicity of @code{mkdir(2)}.  It should work for any platforms,
but it may be slower than @code{file}.

@item retry-interval
@itemx retry-limit

Accepts a nonnegative real number that specifies either
the interval to attempt to acquire the primary lock, or the maximum
time we should keep retrying, respecively, in seconds.
The default value is 1 second interval and 10 second limit.
To prevent retrying, give 0 to @var{retry-limit}.

@item secondary-lock-name

The name of the secondary lock file (or directory).  If omitted,
@var{lock-name} with a suffix @code{.2} attached is used.

@item retry2-interval
@itemx retry2-limit

Like @var{retry-interval} and @var{retry-limit}, but these specify
interval and timeout for the secondary lock file.  The possibility
of secondary lock file collision is usually pretty low, so
you would hardly need to tweak these.  The default values are
1 second interval and 10 second limit.

@item perms

Specify the permission bitmask of the lock file or directory,
in a nonnegative exact integer.  The default is @code{#o644} for
a lock file and @code{#o755} for a lock directory.

Note that to control who can acquire/release/steal the lock,
what matters is
the permission of the directory in which the lock file/directory,
not the permission of the lock file/directory itself.

@item abandon-timeout

Specifies the period in seconds.  If the primary lock file is
older than that, @code{with-lock-file} steals the lock.
To prevent stealing, give @code{#f} to this argument.
The default value is 600 seconds.

@end table

@end defun

@deftp {Condition type} <lock-file-failure>
A condition indicating that @code{with-lock-file} couldn't
obtain the lock.  Inherits @code{<error>}.

@defivar <lock-file-failure> lock-file-name
The primary lock file name.
@end defivar
@end deftp

Gauche also provides OS-supported file locking feature,
@code{fcntl} lock, via @code{gauche.fcntl} module.
Whether you want to use @code{fcntl} lock or @code{with-lock-file}
will depend on your application.

These are the advantages of the @code{fcntl} lock:

@itemize
@item
The lock is removed when the process dies without explicitly unlocking it.
@item
You can directly lock the file you're touching.
@item
You can lock a part of a file.
@item
You can have shared and exclusive locks.
@end itemize

In common situations, probably the most handy property is the
first one; you don't need to worry about leaving lock behind
unexpected process termination.

However, there are a couple of shortcomings in @code{fcntl} locks.

@itemize
@item
It is not guaranteed to work across different platforms, 
and/or NFS-mounted filesystems.
@item
The lock is per-process, per-file.  If you have a lock in a file,
then calls a library that also locks the file, the lock always
succeeds.  Worse, if the library unlocks the file, 
the lock is completely removed, while the caller doesn't know
about it.  It also means that, in order to prevent multiple threads
in a process from accessing the same file, you have to use
mutex along the fcntl lock.
@end itemize

Especially because of the second point, it is very difficult
to use @code{fcntl} lock unless you have total control over and knowledge
of the entire application.
It is ok to use the @code{fcntl} lock by the application code to lock
the application-specific file.  
Library developers have difficulty, however, to make sure any potential
user of the library won't try to lock the same file as the library tries
to lock (usually it can't be done).


@c ----------------------------------------------------------------------
@node Mathematic constants, Mersenne-Twister random number generator, Filesystem utilities, Library modules - Utilities
@section @code{math.const} - Mathematic constants
@c NODE 定数, @code{math.const} - 定数

@deftp {Module} math.const
@mdindex math.const
@c EN
This module defines several commonly-used mathematic constants.
@c JP
いくつかの一般的に用いられる数学定数を定義しています。
@c COMMON
@end deftp

@defvr {Constant} pi
@defvrx {Constant} pi/2
@defvrx {Constant} pi/4
@defvrx {Constant} pi/180
@defvrx {Constant} 1/pi
@defvrx {Constant} 180/pi
@c EN
Bound to pi, pi/2, pi/4, pi/180, 1/pi and 180/pi, respectively.
@c JP
それぞれ、π、π/2、π/4、π/180、1/π、180/πです。
@c COMMON
@end defvr

@defvr {Constant} e
Napier's constant.
@end defvr

@c ----------------------------------------------------------------------
@node Mersenne-Twister random number generator, Windows support, Mathematic constants, Library modules - Utilities
@section @code{math.mt-random} - Mersenne Twister Random number generator
@c NODE Mersenne Twister乱数発生器, @code{math.mt-random} - Mersenne Twister乱数発生器

@deftp {Module} math.mt-random
@mdindex math.mt-random
@c EN
Provides a pseudo random number generator (RNG) based on 
"Mersenne Twister" algorithm developed by Makoto Matsumoto and
Takuji Nishimura.   It is fast, and has huge period of 2^19937-1.
See @ref{MT,,MT}, for details about the algorithm.
@c JP
Makoto MatsumotoとTakuji Nishimuraにより開発された、
``Mersenne Twister''アルゴリズムに基づく、
仮想的な乱数発生器(RNG)を提供します。
高速で、2^19937-1という極めて長大な周期を持ちます。
アルゴリズムの詳細については、@ref{MT,,MT}を参照して下さい。
@c COMMON
@end deftp

@deftp {Class} <mersenne-twister>
@clindex mersenne-twister
@c EN
A class to encapsulate the state of Mersenne Twister RNG.
Each instance of this class has its own state, and can be used
as an independent source of random bits if initialized
by individual seed.

The random seed value can be given at the instantiation time
by @code{:seed} initialization argument, or by using
@code{mt-random-set-seed!} described below.
@c JP
Mersenne Twister RNGの状態をカプセル化するクラスです。
このクラスのそれぞれのインスタンスは独自の状態を持ち、
個別のシードで初期化されていれば、それぞれがランダムビットの
独立したソースになり得ます。

ランダムシードの値は初期化引数@code{:seed}により初期化時に与えるか、
以下で説明する@code{mt-random-set-seed!}を使います。
@c COMMON

@example
(define m (make <mersenne-twister> :seed (sys-time)))

(mt-random-real m) @result{} 0.10284287848537865
(mt-random-real m) @result{} 0.463227748348805
(mt-random-real m) @result{} 0.8628500643709712
@dots{}
@end example
@end deftp

@defun mt-random-set-seed! mt seed
@c EN
Sets random seed value @var{seed} to the Mersenne Twister RNG @var{mt}.
@var{Seed} can be an arbitrary positive exact integer,
or arbitrary length of u32vector (@xref{Homogeneous vectors}).
If it is an integer, the lower 32bits are used for initialization.
If it is a u32vector, up to 624 elements are used for initialization.
@c JP
Mersenne Twister RNG @var{mt}にランダムシードの値@var{seed}をセットします。
@var{seed}は任意の正の正確整数か、任意長のu32vector
(@ref{Homogeneous vectors}参照)が使えます。
整数の場合は、初期化のために低位の32ビットが使われます。
u32vectorの場合は、初期化のために624までの要素が使われます。
@c COMMON
@end defun

@defun mt-random-get-state mt
@defunx mt-random-set-state! mt state
@c EN
Retrieves and reinstalls the state of Mersenne Twister RNG @var{mt}.
The state is represented by a u32vector of 625 elements.  The state
can be stored elsewhere, and then restored to an instance of
@code{<mersenne-twister>} to continue to generate the pseudo random
sequence.
@c JP
Mersenne Twister RNG @var{mt}を取り出して再インストールします。
状態は、625要素のu32vectorで表現されます。
状態はどこにでも保存することができ、仮想的なランダムシーケンスの
生成を続行するために、@code{<mersenne-twister>}のインスタンスとして
リストアできます。
@c COMMON
@end defun

@defun mt-random-real mt
@defunx mt-random-real0 mt
@c EN
Returns a random real number between 0.0 and 1.0.
1.0 is not included in the range.  @code{Mt-random-real} doesn't
include 0.0 either, while @code{mt-random-real0} does.
Excluding 0.0 is from the draft SRFI-27.
@c JP
0.0と1.0の間のランダムな実数を返します。
1.0は範囲に含まれません。
@code{mt-random-real}は、0.0も範囲に含みませんが、
@code{mt-random-real0}は含みます。
0.0を含まないのは、SRFI-27ドラフトに依拠しています。
@c COMMON
@end defun

@defun mt-random-integer mt range
@c EN
Returns a random exact positive integer between 0 and @var{range}-1.
@var{Range} can be any positive exact integer.
@c JP
0から@var{range}-1までの正の正確整数をランダムに返します。
@var{range}はいかなる正の正確整数でも構いません。
@c COMMON
@end defun

@defun mt-random-fill-u32vector! mt u32vector
@defunx mt-random-fill-f32vector! mt f32vector
@defunx mt-random-fill-f64vector! mt f64vector
@c EN
Fills the given uniform vector by the random numbers.
For @code{mt-random-fill-u32vector!}, the elements are filled
by exact positive integers between 0 and 2^32-1.
For @code{mt-random-fill-f32vector!} and
@code{mt-random-fill-f64vector!}, it is filled by an inexact
real number between 0.0 and 1.0, exclusive.

If you need a bunch of random numbers at once, these are much
faster than getting one by one.
@c JP
与えられたユニフォームベクタをランダムな数値で埋めます。
@code{mt-random-fill-u32vector!}では、要素は0と2^32-1の間の
正の正確整数で埋められます。
@code{mt-random-fill-f32vector!}と@code{mt-random-fill-f64vector!}
では、0.0と1.0(含まれない)の間の不正確実数で埋められます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Windows support, RFC822 message parsing, Mersenne-Twister random number generator, Library modules - Utilities
@section @code{os.windows} - Windows support
@c NODE Windowsのサポート, @code{os.windows} - Windowsのサポート

@deftp {Module} os.windows
@mdindex os.windows
This module is only available on Windows-native Gauche, and
provides Windows-specific procedures.
You can check @code{gauche.os.windows} feature with
 @code{cond-expand} macro (@xref{Feature conditional})
to conditionalize windows-specific code.

@example
(cond-expand
  [gauche.os.windows
   (use os.windows)
   ... Windows-specific code ...]
  [else
   ... Unix code ...])
@end example

Currently there aren't enough procedures provided here, but
eventually we want to support simple scripting on Windows.

Unless otherwise noted,
when Windows API returns an error value, a @code{<system-error>} condition
is thrown.
@end deftp

@menu
* Windows dialogs::             
* Windows console API::         
@end menu

@node Windows dialogs, Windows console API, Windows support, Windows support
@subsection Windows dialogs

Currenly we only have MessageBox API.

@defun sys-message-box window message :optional caption flags
Calls Windows MessageBox API.   The @var{window} argument should
be a handle for a window, or @code{#f}; at the moment we don't
provide any API that retrieves window handles, so you should always
pass @code{#f} here.  The @var{message} argument takes a string
for the content of the message box.  Optional @var{caption}
argument takes a string to be used in the window title.

The @var{flags} argument is an integer; it should be @code{logior}
of values from one or more of the following groups.  See the
Windows reference manual for the details.

@table @emph
@item Buttons
@code{MB_ABORTRETRYIGNORE},
@code{MB_CANCELTRYCONTINUE},
@code{MB_HELP},
@code{MB_OK} (default),
@code{MB_OKCANCEL},
@code{MB_RETRYCANCEL},
@code{MB_YESNO},
@code{MB_YESNOCANCEL}
@item Icon
Default is no icon.  Possible values:
@code{MB_ICONEXCLAMATION},
@code{MB_ICONWARNING},
@code{MB_ICONINFORMATION},
@code{MB_ICONASTERISK},
@code{MB_ICONQUESTION},
@code{MB_ICONSTOP},
@code{MB_ICONERROR},
@code{MB_ICONHAND}
@item Default button
@code{MB_DEFBUTTON1} (default),
@code{MB_DEFBUTTON2},
@code{MB_DEFBUTTON3},
@code{MB_DEFBUTTON4}
@item Modality
@code{MB_APPLMODAL} (default),
@code{MB_SYSTEMMODAL},
@code{MB_TASKMODAL}
@item Other options
@code{MB_DEFAULT_DESKTOP_ONLY},
@code{MB_RIGHT},
@code{MB_RTLREADING},
@code{MB_SETFOREGROUND},
@code{MB_TOPMOST},
@code{MB_SERVICE_NOTIFICATION}
@end table

Return value is one of the following integer constants,
indicating which button is pressed:
@code{IDABORT},
@code{IDCANCEL},
@code{IDCONTINUE},
@code{IDIGNORE},
@code{IDNO},
@code{IDOK},
@code{IDRETRY},
@code{IDTRYAGAIN}, or
@code{IDYES}
@end defun

@node Windows console API,  , Windows dialogs, Windows support
@subsection Windows console API

Most of these procedures corresponds to Windows Console API one-to-one.
See the Windows reference for the detail description of what each API does.

@subsubheading Attaching and detaching

@defun sys-alloc-console 
@defunx sys-free-console 
[Windows] 
Calls @code{AllocConsole} and @code{FreeConsole}, respectively.
@end defun

@defun sys-generate-console-ctrl-event event pgid
[Windows] 
@end defun

@defvr {Constant} CTRL_C_EVENT
@defvrx {Constant} CTRL_BREAK_EVENT
[Windows] 
@end defvr

@subsubheading Console codepage

@defun sys-get-console-cp
@defunx sys-get-console-output-cp
@defunx sys-set-console-cp codepage
@defunx sys-set-console-output-cp codepage
[Windows] 
@end defun

@defun sys-get-console-cursor-info handle
@defunx sys-set-console-cursor-info handle size visible
[Windows] 
@end defun

@defun sys-set-console-cursor-position handle x y
[Windows] 
@end defun

@subsubheading Console mode

@defun sys-get-console-mode handle
@defunx sys-set-console-mode handle mode
[Windows] 
@end defun

@defvr {Constant} ENABLE_LINE_INPUT
@defvrx {Constant} ENABLE_ECHO_INPUT
@defvrx {Constant} ENABLE_PROCESSED_INPUT
@defvrx {Constant} ENABLE_WINDOW_INPUT
@defvrx {Constant} ENABLE_MOUSE_INPUT
@defvrx {Constant} ENABLE_PROCESSED_OUTPUT
@defvrx {Constant} ENABLE_WRAP_AT_EOL_OUTPUT
[Windows] 
@end defvr

@subsubheading Screen buffer

@defun sys-create-console-screen-buffer desired-access share-mode inheritable
[Windows] 
@end defun

@defvr {Constant} GENERIC_READ
@defvrx {Constant} GENERIC_WRITE
[Windows] 
@end defvr

@defvr {Constant} FILE_SHARE_READ
@defvrx {Constant} FILE_SHARE_WRITE
[Windows] 
@end defvr

@defun sys-set-console-active-screen-buffer handle
[Windows] 
@end defun

@defun sys-scroll-console-screen-buffer handle scroll-rectangle clip-rectangle x y fill
[Windows] 
@end defun

@deftp {Class} <win:console-screen-buffer-info>
[Windows] 

@defivar {<win:console-screen-buffer-info>} size.x
@defivarx {<win:console-screen-buffer-info>} size.y
@end defivar

@defivar {<win:console-screen-buffer-info>} cursor-position.x
@defivarx {<win:console-screen-buffer-info>} cursor-position.y
@end defivar

@defivar {<win:console-screen-buffer-info>} attributes
@end defivar

@defivar {<win:console-screen-buffer-info>} window.left
@defivarx {<win:console-screen-buffer-info>} window.top
@defivarx {<win:console-screen-buffer-info>} window.right
@defivarx {<win:console-screen-buffer-info>} window.bottom
@end defivar

@defivar {<win:console-screen-buffer-info>} maximum-window-size.x
@defivarx {<win:console-screen-buffer-info>} maximum-window-size.y
@end defivar

@end deftp

@defvr {Constant} FOREGROUND_BLUE
@defvrx {Constant} FOREGROUND_GREEN
@defvrx {Constant} FOREGROUND_RED
@defvrx {Constant} FOREGROUND_INTENSITY
@defvrx {Constant} BACKGROUND_BLUE
@defvrx {Constant} BACKGROUND_GREEN
@defvrx {Constant} BACKGROUND_RED
@defvrx {Constant} BACKGROUND_INTENSITY
[Windows] 
@end defvr

@defun sys-get-console-screen-buffer-info handle
[Windows] 
@end defun

@defun sys-get-largest-console-window-size handle
[Windows] 
@end defun

@defun sys-set-screen-buffer-size handle x y
[Windows] 
@end defun

@subsubheading Console input/output

@deftp {Class} <win:input-record>
[Windows] 

@defivar {<win:input-record>} event-type
@end defivar

@defivar {<win:input-record>} key.down
@defivarx {<win:input-record>} key.repeat-count
@defivarx {<win:input-record>} key.virtual-key-code
@defivarx {<win:input-record>} key.unicode-char
@defivarx {<win:input-record>} key.ascii-char
@defivarx {<win:input-record>} key.control-key-state
@end defivar

@defivar {<win:input-record>} mouse.x
@defivarx {<win:input-record>} mouse.y
@defivarx {<win:input-record>} mouse.button-state
@defivarx {<win:input-record>} mouse.event-flags
@end defivar

@defivar {<win:input-record>} window-buffer-size.x
@defivarx {<win:input-record>} window-buffer-size.y
@end defivar

@defivar {<win:input-record>} menu.command-id
@end defivar

@defivar {<win:input-record>} focus.set-focus
@end defivar

@end deftp

@defun sys-get-number-of-console-input-events handle
[Windows] 
@end defun

@defun sys-get-number-of-console-mouse-buttons
[Windows] 
@end defun

@defun sys-peek-console-input handle
@defunx sys-read-console-input handle
[Windows] 
@end defun

@defun sys-read-console handle buf
[Windows] 
@end defun

@defun sys-read-console-output handle buf w h x y region
[Windows] 
@end defun

@defun sys-read-console-output-attribute handle buf x y
[Windows] 
@end defun

@defun sys-read-console-output-character handle len x y
[Windows] 
@end defun

@defun sys-set-console-text-attribute handle attr
[Windows] 
@end defun

@defun sys-set-console-window-info handle absolute window
[Windows] 
@end defun

@defun sys-write-console handle string
[Windows] 
@end defun

@defun sys-write-console-output-character handle string x y
[Windows] 
@end defun

@defun sys-get-console-title 
[Windows] 
@end defun

@subsubheading Standard handles

@defun sys-get-std-handle which
@defunx sys-set-std-handle which handle
[Windows] 
@end defun

@defvr {Constant} STD_INPUT_HANDLE
@defvrx {Constant} STD_OUTPUT_HANDLE
@defvrx {Constant} STD_ERROR_HANDLE
@end defvr


@c ----------------------------------------------------------------------
@c @node Parser combinators for PEG, RFC822 message parsing, Mersenne-Twister random number generator, Library modules - Utilities
@c @section @code{parser.peg} - Parser combinators for PEG
@c @c NODE PEGパーザコンビネータ, @code{parser.peg} - PEGパーザコンビネータ

@c @deftp {Module} parser.peg
@c @mdindex parser.peg
@c This module implements a parser combinator library
@c to build parsers based on Parsing Expression Grammer, or PEG.

@c PEG is a @emph{formal grammer} to define a language, like regular 
@c expressions or context-free grammers, although PEG is more powerful
@c than those.  An interesting characteristic of PEG is that it can
@c be directly mapped to a recursive decent parser, which is exactly
@c what this library does---each production rule is a Scheme expression
@c that takes parsers and returns a combined parser.  One advantage of
@c this approach is that you can freely mix ordinary Scheme code
@c within the parser, that is, there's no special ``parser description
@c language'' distinct from the base Scheme langauge, nor you need to
@c run separate tools like parser generators to obtain a runnable parser code.

@c Although PEG can directly parse the character string, the parser
@c combinators are not tied to it.  In fact, it can take any
@c stream of tokens, where the exact meaning of token depends on
@c the application; you can have separate lexer that generates
@c token stream that PEG parser can parse.  See @ref{PEG stream}
@c for the details of the stream abstraction layer

@c This library is specifically written to get a good performance
@c on Gauche.  The parser created by @code{parser.peg} is
@c no slower than the parser written manually from scratch, or
@c even faster.  However, you have to watch out some traps; see
@c @ref{PEG performance tips}, for the details.
@c @end deftp

@c @menu
@c * PEG Walkthrough::             
@c * PEG high-level API::          
@c * PEG combinators::             
@c * PEG stream::                  
@c * PEG performance tips::        
@c @end menu

@c @node PEG Walkthrough, PEG high-level API, Parser combinators for PEG, Parser combinators for PEG
@c @subsection Walkthrough

@c In @code{parser.peg}, a parser is merely a Scheme procedure
@c that takes an input (peg stream) as an argument and returns
@c a result (well, in fact, it returns three values, but we'll go
@c into the details later.)

@c Typically you don't need to write parsers directly in
@c procedural style.  Instead, you can use procedures that
@c generates parsers.   A parser can be as simple as the 
@c following, which accepts a character @code{#\a}.

@c @example
@c ($char #\a)   ; => a parser
@c @end example

@c A parser can be invoked by a @emph{parser driver}.  For example,
@c you can use @code{peg-parse-string} to invoke the above parser
@c on a string:

@c @example
@c gosh> (peg-parse-string ($char #\a) "abc")
@c #\a
@c @end example

@c The parsing succeeds, and returns the matched value---@code{#\a} in this case.
@c If the parser can't accept the input, the driver throws an error
@c @code{<parse-error>}.

@c @example
@c gosh> (peg-parse-string ($char #\a) "xyz")
@c *** PARSE-ERROR: expecting #\a at 0
@c @end example

@c A parser can also be constructed by combining simpler parsers,
@c using @emph{parser combinators}.   For example, @code{$seq} takes
@c zero or more parsers and apply them sequentially, returning
@c the last result.

@c @example
@c gosh> (peg-parse-string ($seq ($char #\a) ($char #\b) ($char #\c)) "abc")
@c #\c
@c @end example

@c The combinator @code{$many} takes a parser and returns a new parser
@c that accepts zero or more occurrence of the string the original parser
@c accepts.

@c @example
@c gosh> (peg-parse-string ($many ($char #\a)) "aaaaabc")
@c (#\a #\a #\a #\a #\a)
@c gosh> (peg-parse-string ($many ($char #\a)) "xxxxxyz")
@c ()
@c @end example

@c A parser is just an ordinary Scheme procedure, so it can be bound
@c to a variable, then can be used to construct more complex parsers.

@c @example
@c (define digits    ($many1 ($one-of #[\d])))
@c (define ws        ($skip-many ($one-of #[\s])))
@c (define separator ($seq ws ($char #\,) ws))
@c @end example

@c I leave explanation of @code{$many1}, @code{$one-of}, and
@c @code{$skip-many} for the later section, 
@c but I guess you can imagine what those parsers do; 
@c @code{digits} accepts a sequence of digits, and
@c @code{ws} accepts whitespaces.   The @code{separator}
@c parser accepts a comma, optionally surrounded by whitespaces.

@c The @code{digits} parser returns a list of accepted
@c characters:

@c @example
@c gosh> (peg-parse-string digits "12345")
@c (#\1 #\2 #\3 #\4 #\5)
@c @end example

@c Can we create a parser that returns an integer as
@c a parsed result?    Yes, we can use the @code{$do} form
@c and the @code{$return} combinator.

@c @example
@c (define integer
@c   ($do [ds digits]
@c        ($return (x->integer (list->string ds)))))
@c @end example

@c The @code{$do} form works somewhat like @code{and-let*}; it takes
@c a form of @code{($do [@var{var} @var{parser}] @dots{} @var{expr})},
@c applying the @var{parser}s in order, binding the result of each
@c parser to @var{var}.  The @code{$return} combinator is create a
@c parser that doesn't consume input and returns the given value; 
@c you can think that @code{$do} is to pull out a value from,
@c and @code{$return} to put back a value to, the chain of parsers.
@c (Note: If you know Monads, you can recognize the pattern.
@c It is also no coincidence that @code{$do} is similar to @code{and-let*},
@c since @code{and-let*} is just a Maybe monad in disguise.)

@c @example
@c gosh> (peg-parse-string integer "12345")
@c 12345
@c @end example

@c Now you can combine those parsers to build more complex one, such
@c as a list of integers:

@c @example
@c (define integers1 ($seq integer
@c                         ($many ($seq separator integer))))

@c gosh> (peg-parse-string integers1 "123, 456, 789")
@c (456 789)
@c @end example

@c Oops, where's 123?  Well, remember that 
@c @code{$seq} discards the results but the last one.
@c We can use @code{$do} again to keep all the results.

@c @example
@c (define integers2 ($do [n  integer]
@c                        [ns ($many ($seq separator integer))]
@c                        ($return (cons n ns))))

@c gosh> (peg-parse-string integers2 "123, 456, 789")
@c (123 456 789)
@c @end example

@c This parser doesn't handle the case when the list contains no
@c integers.   Using the @code{$or} form, which represents a choice,
@c we can modify it to handle zero-element case.

@c @example
@c (define integers3 ($or ($do [n  integer]
@c                             [ns ($many ($seq separator integer))]
@c                             ($return (cons n ns)))
@c                        ($return '())))
@c @end example

@c By the way, ``list of stuff separated by something'' is a very common
@c pattern, so we can extract the pattern to name it:

@c @example
@c (define (sep-by stuff separator)
@c   ($or ($do [n  stuff]
@c             [ns ($many ($seq separator stuff))]
@c             ($return (cons n ns)))
@c        ($return '()))
@c @end example

@c Then the list of integers can be written this simple:

@c @example
@c (define integers4 (sep-by integer separator))
@c @end example

@c In fact, @code{parser.peg} provides @code{$sep-by} to do the above,
@c but we've just shown the definition to demonstrate
@c the power of the combinatorial approach; 
@c you can use ordinary procedural abstraction to factor out common patterns.

@c There's one catch in the @code{$or} form.
@c It tries the next alternative only when the
@c parser fails without consuming the input.  Once the input is
@c consumed, @code{$or} commits to that choice.   For example,
@c the following fails even if the input seems to match the
@c second alternative:

@c @example
@c gosh> (peg-parse-string ($or ($string "(a)") ($string "(b)")) "(b)")
@c *** PARSE-ERROR: expecting (a) at 1
@c @end example

@c It's because when @code{$or} tries the first branch, it reads the initial
@c open paren from the input, so @code{$or} commits to the first branch.
@c When the branch fails, @code{$or} doesn't bother to try the second branch.
@c (In other words, @code{$or} does not backtrack.)

@c You may factor out the common prefix:

@c @example
@c ($seq ($char #\()
@c       ($or ($string "a") ($string "b"))
@c       ($char #\)))
@c @end example

@c But it complicates the syntax, and it is not always trivial to
@c factor out like above.  The better way is to use the @code{$try}
@c combinator: @code{($try @var{p})} runs a parser @var{p}, and if
@c it fails, @code{$try} rolls back the input as if it didn't
@c consume input at all.  Using with @code{$or}, you can do arbitrary
@c lookahead.

@c @example
@c ($or ($try ($string "(a)"))
@c      ($string "(b)"))
@c @end example

@c Now, let's get back to the integer list example and make
@c it more intersting.
@c Suppose the list of integers are surrounded by brackets.  
@c We can just put open and close bracket around the
@c comma-separated integers (you can omit the parentheses around
@c the clauses in @code{$do} form, if the parser expression consists
@c of single symbol and you don't need the result):

@c @example
@c (define begin-list  ($seq ($char #\[ ) ws))
@c (define end-list    ($seq ws ($char #\] )))

@c (define int-list1 ($do begin-list
@c                        [ns ($sep-by integer separator)]
@c                        end-list
@c                        ($return ns)))

@c gosh> (peg-parse-string int-list1 "[123, 456, 789]")
@c (123 456 789)
@c @end example

@c The above pattern is also common, so there's a pre-defined combinator:
@c @code{$between}:

@c @example
@c (define int-list2 ($between begin-list
@c                             ($sep-by integer separator)
@c                             end-list))
@c @end example

@c What if we want a nested list?  In BNF, we could write
@c something like this:

@c @example
@c list : '[' (elem (separator elem)* )? ']'
@c elem : integer | list
@c @end example

@c Unfortunately, the straightforward translation won't work:

@c @example
@c ;; Does not work
@c (define list1 ($between begin-list
@c                         ($sep-by elem separator)
@c                         end-list))
@c (define elem  ($or integer list1))
@c @end example

@c We need the parser @code{elem} to construct @code{list1}, but
@c we need the parser @code{list1} to construct @code{elem}.
@c In lazy languages like Haskell this doesn't matter, but we Schemers
@c are @emph{eager}!

@c The solution is to delay the parser construciton until it is
@c actually used.  The @code{$lazy} combinator does the job:

@c @example
@c (define list2 ($lazy
@c                ($between begin-list
@c                          ($sep-by elem separator)
@c                          end-list)))
@c (define elem  ($or integer list2))

@c gosh> (peg-parse-string list2 "[123, [456, [], 789], 987]")
@c (123 (456 () 789) 987)
@c @end example


@c @node PEG high-level API, PEG combinators, PEG Walkthrough, Parser combinators for PEG
@c @subsection High-level API

@c @defun peg-parse-string parser input-string
@c @end defun

@c @defun peg-parse-port parser input-string
@c @end defun

@c @defun peg-run-parser parser peg-stream
@c @end defun

@c @deftp {Condition type} <parse-error>
@c @end deftp

@c @defun make-peg-parse-error type objs stream
@c @end defun


@c @node PEG combinators, PEG stream, PEG high-level API, Parser combinators for PEG
@c @subsection Combinators

@c In the following entries, @var{p}, @var{p1}, @var{p2}, @dots{} in
@c the arguments must be parsers, and @var{ps} must be a list of parsers.

@c @subsubheading Generic combinators

@c @defmac $do clause @dots{} expr
@c @end defmac

@c @defmac $do* clause @dots{} expr
@c @end defmac

@c @defun $fold proc seed ps
@c @end defun

@c @defun $fold-right proc seed ps
@c @end defun

@c @defun $seq p1 p2 @dots{}
@c @end defun

@c @defmac $or p1 p2 @dots{}
@c @end defmac

@c @defun $try p
@c Returns a parser that accepts the same input
@c the parser @var{p} accepts, but when @var{p} fails
@c the returned parser doesn't consume input.  Used with @code{$or},
@c you can explicitly implement a backtrack behavior.
@c @end defun

@c @defun $many p :optional min max
@c @end defun

@c @defun $skip-many p :optional min max
@c @end defun

@c @defun $optional p
@c @end defun

@c @defun $repeat p count
@c @end defun

@c @defun $count p count
@c @end defun

@c @defun $sep-by p psep :optional min max
@c @end defun

@c @defun $alternate p psep
@c @end defun

@c @defun $end-by p psep :rest p2 @dots{}
@c @end defun

@c @defun $sep-end-by p psep :rest p2 @dots{}
@c @end defun

@c @defun $not p
@c @end defun

@c @defun $many-till p pend :rest p2 @dots{}
@c @end defun

@c @defun $chain-left p p-op
@c @end defun

@c @defun $chain-right p p-op
@c @end defun

@c @defmac $lazy p
@c @end defmac

@c @defun $->rope p
@c @end defun

@c @subsubheading Semantic predicate

@c @defmac $satisfy p expect
@c @end defmac

@c @subsubheading String parsers

@c @defun $char c
@c @defunx $char-ci c
@c Returns a parser that accepts a single character, @var{c}.
@c @code{$char-ci} ignores case.
@c On success, the semantic value is the input character.
@c @end defun

@c @defun $string str
@c @defunx $string-ci str
@c Returns a parser that accepts an input that matches 
@c a string @var{str}.  @code{$string-ci} ignores case.
@c On success, the semantic value is the input string.

@c The parsing of string is atomic: When the parser fails,
@c it doesn't consume the input.  That is,
@c @code{($string "ab")} is not the same as
@c @code{($do [a ($char #\a)] [b ($char #\b)] ($return (string a b)))};
@c you may think it is surrouned by implicit @code{$try}.
@c (If you've used Parsec, 
@c @end defun

@c @defun $one-of cset
@c Returns a parser that accepts any character in the character set @var{cset}.
@c @end defun

@c @defun $none-of cset
@c @end defun

@c @defmac $many-chars cset
@c @end defmac

@c @defvar anychar
@c @defvarx upper
@c @defvarx lower
@c @defvarx letter
@c @defvarx alphanum
@c @defvarx digit
@c @defvarx hexdigit
@c @defvarx newline
@c @defvarx tab
@c @defvarx space
@c @defvarx spaces
@c @defvarx eof
@c @end defvar


@c @node PEG stream, PEG performance tips, PEG combinators, Parser combinators for PEG
@c @subsection PEG stream

@c @defun make-peg-steram generator :optional fini
@c @end defun

@c @defun string->peg-stream string
@c @end defun

@c @defun port->peg-stream port &key (reader read-char)
@c @end defun

@c @defun list->peg-stream lis
@c @end defun

@c @defun peg-stream-position s
@c @end defun

@c @defun peg-stream-peek! s
@c @end defun

@c @node PEG performance tips,  , PEG stream, Parser combinators for PEG
@c @subsection Performance



@c ----------------------------------------------------------------------
@node RFC822 message parsing, Base64 encoding/decoding, Windows support, Library modules - Utilities
@section @code{rfc.822} - RFC822 message parsing
@c NODE RFC822メッセージ形式, @code{rfc.822} - RFC822メッセージ形式

@deftp {Module} rfc.822
@mdindex rfc.822
@c EN
Defines a set of functions that parses and constructs the ``Internet
Message Format'', a text format used to exchange e-mails.
The most recent specification can be found in
RFC2822 (@ref{rfc2822,[RFC2822],RFC2822}).
The format was originally defined in RFC 822, and people still 
call it ``RFC822 format'', hence I named this module.
In the following document, I also refer to the format as ``RFC822 format''.
@c JP
電子メールを交換する際に使用されるテキストのフォーマットである、``インターネット・
メッセージ・フォーマット''をパーズ/生成する手続きを定義しています。
最新の仕様は、RFC2822 (@ref{rfc2822,[RFC2822],RFC2822}) にあります。
このフォーマットは最初 RFC 822 で定義されたため、未だに``RFC822形式''と
呼ばれています。それがこのモジュール名の由来です。
以下では、このフォーマットを``RFC822形式''と呼びます。
@c COMMON
@end deftp

@c EN
@subheading Parsing message headers
@c JP
@subheading メッセージヘッダのパーズ
@c COMMON

@defun rfc822-read-headers iport :key strict? reader
@c EN
Reads RFC822 format message from an input port @var{iport},
until it reaches the end of the message header.
The header fields are broken into a list of the following
format:
@c JP
入力ポート @var{iport} から、メッセージ・ヘッダの終わりに達するまで、
RFC822 形式のメッセージを読み込みます。
ヘッダ・フィールドは以下のフォーマットのリストに展開、分離されます。
@c COMMON
@example
((name body) @dots{})
@end example
@c EN
@var{Name} @dots{} are the field names, and @var{body} @dots{} are
the corresponding field body, both as strings.
Field names are converted to lower-case characters.
Field bodies are not modified, except the folded line is unfolded.
The order of fields are preserved.
@c JP
@var{Name} @dots{} はフィールド名で、@var{body} @dots{} は対応するフィールドの
ボディ、ともに文字列です。
フィールド名は小文字に変換されます。フィールドのボディは、行折り返しが
取り除かれる以外は変更されません。
フィールドの順番は保存されます。
@c COMMON

@c EN
By default, the parser works permissively.  If EOF is encountered
during parsing header, it is taken as the end of the message.
And if a line that doesn't consist neither continuing (folded) line
nor start a new header field, it is simply ignored.
You can change this behavior by giving true value to
the keyword argument @var{strict?}; then the parser raises an error
for such a malformed header.

The keyword argument @var{reader} takes a procedure that reads
a line from @var{iport}.  Its default is @code{read-line}, which
should be enough for most cases.
@c JP
デフォルトでは、パーザの動作は寛容です。ヘッダをパーズ中に EOF に
出会うとそれをメッセージの終端とみなします。継続(折り返し)行でもなく、
新しいヘッダフィールドの始端でもない行は無視します。このふるまいは
キーワード引数 @var{strict?} に真の値を渡すことで変更することができます。
真を渡すと、このような不正な形式のヘッダに対してエラーを発生させるように
なります。

キーワード引数 @var{reader} は @var{iport} から一行読み込む手続きを
とります。デフォルトは @code{read-line} です。ほとんどの場合これで
十分のはずです。
@c COMMON
@end defun

@defun rfc822-header->list iport :key strict? reader
@c EN
This is an old name of @code{rfc822-read-headers}.  This is kept
for the backward compatibility.  The new code should use
@code{rfc822-read-headers} instead.
@c JP
これは@code{rfc822-read-headers}の古い名前です。
互換性のために残してありますが、新しいコードは
@code{rfc822-read-headers}を使って下さい。
@c COMMON
@end defun


@defun rfc822-header-ref header-list field-name :optional default
@c EN
An utility procedure to get a specific field from the parsed
header list, which is returned by @code{rfc822-read-headers}.

@var{Field-name} specifies the field name in a lowercase string.
If the field with given name is in @var{header-list}, the procedure
returns its value in a string.  Otherwise, if @var{default} is given,
it is returned, and if not, @code{#f} is returned.
@c JP
@code{rfc822-read-headers} が返すパーズ済みのヘッダリストから
特定のフィールドを得るためのユーティリティ手続きです。

@var{Field-name} は小文字の文字列でフィールド名を指定します。
与えられた名前をもつフィールドが @var{header-list} 中にあれば、
その値を文字列で返します。そうでない場合、もし @var{default} が
与えられていればそれが返り、与えられていなければ @code{#f} が返されます。
@c COMMON
@end defun

@c EN
@subheading Basic field parsers
@c JP
@subheading 基本的なフィールドパーザ
@c COMMON

@c EN
Several procedures are provided to parse "structured" header fields
of RFC2822 messages.  These procedures deal with the body of
a header field, i.e. if the header field is 
"@code{To: Wandering Schemer <schemer@@example.com>}",
they parse "@code{Wandering Schemer <schemer@@example.com>}".

Most of procedures take an input port.  Usually you first parse
the entire header fields by @code{rfc822-read-headers},
obtain the body of the header by @code{rfc822-header-ref},
then open an input string port for the body and use those
procedures to parse them.

The reason for this complexity is because you need
different tokenization schemes depending on the type of the field.
Rfc2822 also allows comments to appear between tokens for most cases,
so a simple-minded regexp won't do the job,
since rfc2822 comment can be nested 
and can't be represented by regular grammar.
So, this layer of procedures are designed flexible enough
to handle various syntaxes.  For the standard header types,
high-level parsers are also provided; see "specific field parsers" below.
@c JP
RFC2822メッセージの「構造化」されたヘッダフィールドをパーズするために、
いくつかの手続きが提供されています。これらの手続きはヘッダフィールドの
本体部を処理します。たとえば、ヘッダフィールドが、
"@code{To: Wandering Schemer <schemer@@example.com>}" であれば、これらの
手続きは "@code{Wandering Schemer <schemer@@example.com>}" をパーズします。

ほとんどの手続きは入力ポートを引数にとります。通常は最初に、ヘッダフィールド
全部を @code{rfc822-read-headers} でパーズし、ヘッダの本体を
@code{rfc822-header-ref} で取得してから、その本体用に入力文字列ポートを
オープンして、それをこれらの手続きを用いてパーズします。

このように複雑になっているのは、フィールドのタイプによって別々の
トークン化スキームが必要になるからです。RFC2822 では多くの場合
トークン間にコメントがあらわれことを許しているので、初心な正規表現では
うまくいきません。RFC2822 のコメントはネスト可能で、正規表現では表現
しきれないからです。
そういうわけで、このレイヤの手続きは、いろいろな構文に対応できるよう
十分な柔軟性があるように設計されています。標準的なタイプのヘッダについては
高水準のパーザも提供されています。後述の「特定フィールド用パーザ」を
参照してください。
@c COMMON

@defun rfc822-next-token iport :optional tokenizer-specs
@c EN
A basic tokenizer.  First it skips whitespaces and/or
comments (@code{CFWS}) from @var{iport}, if any.  Then
reads one token according to @var{tokenizer-specs}.  If @var{iport}
reaches EOF before any token is read, EOF is returned.

@var{Tokenizer-specs} is a list of tokenizer spec, which is
either a char-set or a cons of a char-set and a procedure.

After skipping @code{CFWS}, the procedure peeks a character
at the head of @var{iport}, and checks it
against the char-sets in @var{tokenizer-specs} one by one.
If a char-set that contains the character belongs to is found,
then a token is retrieved as follows: 
If the tokenizer spec is just a char-set, a sequence of characters
that belong to the char-set consists a token.
If it is a cons, the procedure is called with @var{iport} to
read a token.

If the head character doesn't match any char-sets,
the character is taken from @var{iport} and returned.

The default @var{tokenizer-specs} is as follows:
@c JP
基本的なトークナイザです。まず、もしあれば、白空白および/または
コメント (@code{CFWS}) を @var{iport} から読み飛ばします。それから、
@var{tokenizer-specs} にしたがってトークンをひとつ読み込みます。
トークンを読み込む前に、@var{iport} が EOF に到達したら、EOF が
返されます。

@var{tokenizer-specs} はトークナイザ仕様のリストです。
トークナイザ仕様は、文字集合または文字集合と手続きのペアのどちらかです。

@code{CFWS} を読み飛ばしたあと、この手続きは @var{iport} の先頭の一文字
を見て、@var{tokenizer-specs} のひとつひとつに対してチェックします。
その文字が含まれている文字集合がみつかれば、トークンを次のようにして
引き出します。トークナイザ仕様が文字集合だけの場合、その文字集合に
属している文字の並びがトークンを構成します。トークナイザ仕様が文字集合と
手続きのペアだったら、その手続きを @var{iport} とともに呼びだし、
トークンを読み込みます。

もし、先頭の文字がどの文字集合ともマッチしなければ、その文字が
@var{iport} から取り出され、それが返されます。

デフォルトの @var{tokenizer-specs} は以下のようになっています。
@c COMMON
@example
(list (cons #["] rfc822-quoted-string)
      (cons *rfc822-atext-chars* rfc822-dot-atom))
@end example
@c EN
Where @code{rfc822-quoted-string} and @code{rfc822-dot-atom}
are tokenizer procedures described below, and @code{*rfc822-atext-chars*}
is bound to a char-set of @code{atext} specified in rfc2822.
This means @code{rfc822-next-token} retrieves a token
either @code{quoted-string} or @code{dot-atom} specified in rfc2822
by default.

Using @var{tokenizer-specs}, you can customize how the header
field is parsed.  For example, if you want to retrieve a token
that is either (1) a word constructed by alphabetic characters, or
(2) a quoted string, then you can call @code{rfc822-next-token}
by this:
@c JP
ここで @code{rfc822-quoted-string} および @code{rfc822-dot-atom} は
後述するトークナイザ手続きで、@code{*rfc822-atext-chars*} は RFC2822 で
規定された @code{atext} の文字集合に束縛されています。
つまり、@code{rfc822-next-token} はデフォルトでは RFC2822 で規定された
@code{quoted-string} あるいは @code{dot-atom} のトークンを引き出します。

@var{tokenizer-specs} をつかって、ヘッダフィールドのパーズ方法を
カスタマイズすることができます。たとえば、(1) 英字で構成された単語、または
(2) クウォート文字列、のトークンを取り出したいときには、
@code{rfc822-next-token} をこんなふうに呼べます。
@c COMMON

@example
(rfc822-next-token iport
   `(#[[:alpha:]] (#["] . ,rfc822-quoted-string)))
@end example
@end defun

@defun rfc822-field->tokens field :optional tokenizer-specs
@c EN
A convenience procedure.  Creates an input string port for
a field body @var{field}, and calls @code{rfc822-next-token}
repeatedly on it until it consumes all input, then returns
a list of tokens.   @var{Tokenizer-specs} is passed to
@code{rfc822-next-token}.
@c JP
これは便利関数です。フィールド本体 @var{field} に対応する入力文字列ポート
を生成し、それに対して、@code{rfc822-next-token} を全入力を消費するまで、
繰り返しよび、トークンのリストを返します。@var{Tokenizer-specs} は、
@code{rfc822-next-token} に渡されます。
@c COMMON
@end defun

@defun rfc822-skip-cfws iport
@c EN
A utility procedure that consumes any comments and/or whitespace
characters from @var{iport}, and returns the head character
that is neither a whitespece nor a comment.  The returned character
remains in @var{iport}.
@c JP
@var{iport} から、すべてのコメントおよび/または白空白文字を消費し、
白空白でもコメントでもない、先頭の文字を返します。返された文字は、
@var{iport}に残ります。
@c COMMON
@end defun

@defvr {Constant} *rfc822-atext-chars*
@c EN
Bound to a char-set that is a valid constituent of @code{atom}.
@c JP
@code{atom} を構成する有効な文字集合に束縛されています。
@c COMMON
@end defvr

@defvr {Constant} *rfc822-standard-tokenizers*
@c EN
Bound to the default @var{tokenizer-specs}.
@c JP
デフォルトの @var{tokenizer-specs} に束縛されています。
@c COMMON
@end defvr

@defun rfc822-atom iport
@defunx rfc822-dot-atom iport
@defunx rfc822-quoted-string iport
@c EN
Tokenizers for @code{atom}, @code{dot-atom} and @code{quoted-string},
respectively.  The double-quotes and escaping backslashes within
@code{quoted-string} are removed by @code{rfc822-quoted-string}.
@c JP
それぞれ、@code{atom}、@code{dot-atom} および @code{quoted-string} に
対応するトークナイザです。@code{quoted-string} 中の二重引用符および
エスケープのためのバックスラッシュは @code{rfc822-quoted-string} に
よって取り除かれます。
@c COMMON
@end defun

@c EN
@subheading Specific field parsers
@c JP
@subheading 特定フィールド用パーザ
@c COMMON

@defun rfc822-parse-date string
@c EN
Takes RFC-822 type date string, and returns eight values:
@c JP
RFC822 形式の日付文字列を取り、8つの値を返します。
@c COMMON
@example
year, month, day-of-month, hour, minutes, seconds, timezone,
day-of-week.
@end example

@c EN
@emph{Timezone} is an offset from UT in minutes.
@emph{Day-of-week} is a day from sunday,
and may be #f if that information is not available.
@emph{Month} is an integer between 1 and 12, inclusive.
If the string is not parsable, all the elements are #f.
@c JP
@emph{timezone} は UT(グリニッジ標準時)からの分単位のオフセットです。
@emph{day-of-week} は日曜日から数えた曜日で、情報が不足している場合は #f です。
@emph{month}は1から12までの整数です。
文字列がパーズ不可能ならば、全ての要素が #f になります。
@c COMMON
@end defun

@defun rfc822-date->date string
@c EN
Parses RFC822 type date format and returns SRFI-19 @code{<date>} object
(see @ref{SRFI-19 Date}).  If @var{string} can't be parsed, 
returns @code{#f} instead.

To consturct rfc822 date string from SRFI-19 date, you can use
@code{date->rfc822-date} below.
@c JP
RFC822形式の日付フォーマットをパーズし、SRFI-19 の @code{<date>} オブジェクト
(@ref{SRFI-19 Date} 参照) を返します。@var{string} がパーズできないときは
かわりに @code{#f} を返します。

SRFI-19の日付からRFC822形式の日付文字列を作成するには、
後で述べる@code{date->rfc822-date}が使えます。
@c COMMON
@end defun

@c EN
@subheading Message constructors
@c JP
@subheading メッセージの構築
@c COMMON

@defun rfc822-write-headers headers :key output continue check
This is a sort of inverse function of @code{rfc822-read-headers}.
It receives a list of header data, in which each header data
consists of @code{(<name> <body>)}, and writes them out in RFC822 header
field format to the output port specified by the @var{output} keyword
argument.  The default output is the current output port.

By default, the procedure assumes @var{headers} contains all the
header fields, and adds an empty line in the end of output
to indicate the end of the header.  You can pass a true value to
the @var{continue} keyword argument to prevent this, enabling
more headers can be added later.

I said ``a sort of'' above.  That's because this function doesn't
(and can't) do the exact inverse.
Specifically, the caller is responsible for line folding and
make sure each header line doesn't exceed the ``hard limit'' defined
by RFC2822 (998 octets).  This procedure cannot do the line 
folding on behalf of the caller, because the places where 
line folding is possible depend on the semantics of each
header field.

It is also the caller's responsibility to make sure header
field bodies don't have any characters except non-NUL US-ASCII
characters.  If you want to include characters outside of that
range, you should convert them in the way allowed by the
protocol, e.g. MIME.  The @code{rfc.mime} module 
(@xref{MIME message handling}) provides a convenience procedure
@code{mime-encode-text} for such purpose.
Again, this procedure cannot do the encoding automatically,
since the way the field
should be encoded depends on header fields.

What this procedure can do is to check and report such violations.
By default, it runs several checks and signals an error if it finds any
violations of RFC2822.  You can control this checking behavior
by the @var{check} keyword argument.  It can take one of the
following values:

@table @code
@item :error
Default.  Signals an error if a violation is found.
@item #f, :ignore
Doesn't perform any check.  Trust the caller.
@item @var{procedure}
When @code{rfc822-write-headers} finds a violation, the procedure
is called with three arguments; the header field name,
the header field body, and the type of violation explained below.
The procedure may correct the problem and return two values,
the corrected header field name and body.  The returned values
are checked again.  If the procedure returns the
header field name and body unchanged, an error is signalled
in the same way as @code{:error} is specified.
@end table

The third argument passed to the procedure given to the @var{check}
argument is one of the following symbols.  New symbols may be
added in future versions for more checks.

@table @code
@item incomplete-string
Incomplete string is passed.
@item bad-character
Header field contains characters outside of US-ASCII or NUL.
@item line-too-long
Line length exceeds 998 octet limit.
@item stray-crlf
The string contains CR and/or LF character that doesn't consist of 
proper line folding.
@end table

@end defun

@defun date->rfc822-date date
@c EN
Takes SRFI-19 @code{<date>} object (see @ref{SRFI-19 Date})
and returns a string of its rfc822 date representation.
This is a reverse operation of @code{rfc822-date->date}.
@c JP
SRFI-19の@code{<date>}オブジェクト(@ref{SRFI-19 Date}参照)
を取り、そのrfc822日付形式表現の文字列を返します。
@code{rfc822-date->date}の逆関数です。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Base64 encoding/decoding, HTTP cookie handling, RFC822 message parsing, Library modules - Utilities
@section @code{rfc.base64} - Base64 encoding/decoding
@c NODE Base64エンコーディング, @code{rfc.base64} - Base64エンコーディング

@deftp {Module} rfc.base64
@mdindex rfc.base64
@c EN
This module defines a few functions to encode/decode Base64 format,
defined in RFC 2045 (@ref{rfc2045, [RFC2045], RFC2045}), section 6.3
and RFC3548 (@ref{rfc3548, [RFC3548], RFC3548})
@c JP
このモジュールでは、RFC 2045 (@ref{rfc2045, [RFC2045], RFC2045})の6.3節
およびRFC 3548 (@ref{rfc3548, [RFC3548], RFC3548})で
定義されている Base64 フォーマットへエンコード/デコードするいくつかの
手続きを定義しています。
@c COMMON
@end deftp

@defun base64-encode :key line-width
@c EN
Reads byte stream from the current input port, encodes it in Base64
format and writes the result character stream to the current output port.
The conversion ends when it reads EOF from the current input port.

Newline characters can be inserted to keep the maximum line width to
the value given to the @var{line-width} keyword argument.  The default
value of @var{line-width} is 76, as specified in RFC2045.  You can give
@code{#f} or zero to @var{line-width} to suppress line splitting.
@c JP
現在の入力ポートからバイト・ストリームを読み込み、それを Base64 フォーマットに
エンコードし、現在の出力ポートに文字ストリームとして書き出します。
現在の入力ポートから EOF を読み込むと変換を終了します。

一行あたりの文字数が@var{line-width}に与えられた文字数を越えないように、
改行文字が適切に出力に挿入されます。@var{line-width}のデフォルト値は
RFC2045に従い76となっています。@var{line-width}に@code{#f}または@code{0}
を与えることで改行を抑制することができます。
@c COMMON
@end defun

@defun base64-encode-string string :key line-width
@c EN
Converts contents of @var{string} to Base64 encoded format.
Input string can be either complete or incomplete string;
it is always interpreted as a byte sequence.
@c JP
@var{string} の内容を Base64 でエンコードされたフォーマットに変換します。
入力となる文字列は、完全文字列でも不完全文字列でも良いです。
常にバイト・シーケンスとして扱われます。
@c COMMON
@end defun

@defun base64-decode
@c EN
Reads character stream from the current input port, decodes it from Base64
format and writes the result byte stream to the current output port.
The conversion ends when it reads EOF or the termination character
(@code{=}).  The characters which does not in legal Base64 encoded character
set are silently ignored.
@c JP
現在の入力ポートから文字ストリームを読み込み、それを Base64 フォーマットとして
デコードし、現在の出力ポートにバイトストリームとして書き出します。
変換は EOF か、終端文字 (@code{=}) を読み込むと終了します。
Base64 でエンコードされた文字として適当でない文字は沈黙のまま無視されます。
@c COMMON
@end defun

@defun base64-decode-string string
@c EN
Decodes a Base64 encoded string @var{string} and returns
the result as a string.
The conversion terminates at the end of @var{string} or
the termination character (@code{=}).
The characters which does not in legal Base64 encoded character
set are silently ignored.
@c JP
Base64 でエンコードされた文字列 @var{string} をデコードして文字列を返します。
変換は @var{string} の終わりか、終端文字 (@code{=}) で終了します。
Base64 でエンコードされた文字として適当でない文字は沈黙のまま無視されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node HTTP cookie handling, FTP, Base64 encoding/decoding, Library modules - Utilities
@section @code{rfc.cookie} - HTTP cookie handling
@c NODE HTTPクッキー, @code{rfc.cookie} - HTTPクッキー

@deftp {Module} rfc.cookie
@mdindex rfc.cookie
@c EN
Defines a set of functions to parse and construct a ``cookie'' information
defined in RFC 6265.
@c JP
RFC 6265で定義されている「クッキー」情報を
パースしたり構築したりするための手続きを定義しています。
@c COMMON
@end deftp

@defun parse-cookie-string string :optional version
@c EN
Parse a cookie string @var{string}, which is the value of ``Cookie''
request header.  Usually, the same information is available to CGI
program via the environemnt variable @code{HTTP_COOKIE}.

If the cookie version is known, via ``Cookie2'' request header,
the integer version must be passed to @var{version}.  Otherwise,
@code{parse-cookie} figures out the version from @var{string}.

The result has the following format.
@c JP
リクエスト・ヘッダの Cookie の値のクッキー文字列 @var{string} を
パースします。通常、CGI プログラムでは、同じ情報は環境変数
@var{HTTP_COOKIE} を通して利用できます。

リクエスト・ヘッダ Cookie2 を通してクッキーのバージョンが分かる
場合は、@var{version} へ整数のバージョンとして渡されなければなりません。
そうでなければ、@code{parse-cookie} は @var{string} からバージョンを
取り出します。

結果は以下のフォーマットを持ちます。
@c COMMON
@example
((<name> <value> [:path <path>] [:domain <domain>] [:port <port>])
 @dots{})
@end example
@c EN
where @var{<name>} is the attribute name, and @var{<value>} is
the corresponding value.  If the attribute doesn't have value,
@var{<value>} is @code{#f}.  (Note that it differs from the attribute
having null value, @code{""}.)
If the attribute has path, domain or port options, it is given
as a form of keyword-value pair.
@c JP
@var{<name>} は属性名で、@var{<value>} は対応する値です。
属性が値を持たない場合、@var{<value>} は @code{#f} になります。
(属性が NULL 値を持つ場合は、@code{""} となることに注意。)
属性がパスやドメイン、ポート番号のオプションを持つ場合は、
キーワード-値のペアの形式で与えられます。
@c COMMON
@end defun

@defun construct-cookie-string specs :optional version
@c EN
Given list of cookie specs, creates a cookie string suitable for
@code{Set-cookie2} or @code{Set-cookie} header.

Optional @var{version} argument specifies cookie protocol version.
0 for the old Netscape style format, and 1 for RFC2965 style format.
When omitted, version 1 is assumed.

Each cookie spec has the following format.
@c JP
与えられたクッキーの仕様のリストから、@code{Set-cookie2} か
@code{Set-cookie} ヘッダに適切なクッキー文字列を作ります。

オプションの @var{version} 引数は、クッキー・プロトコルのバージョンを
指定するものです。0 は古い Netscape スタイルのフォーマットで、1 は
RFC2965 スタイルのフォーマットです。省略された場合、1 が指定されたものと
されます。

クッキーの仕様は以下のフォーマットを持ちます。
@c COMMON
@example
(<name> <value> [:comment <comment>] [:comment-url <url>]
                [:discard <bool>] [:domain <domain>]
                [:max-age <age>] [:path <path>]
                [:port <port-list>] [:secure <bool>] [:http-only <bool>]
                [:version <version>] [:expires <date>])
@end example
@c EN
Where,
@table @code
@item <name>
A string.  Name of the cookie.
@item <value>
Value of the cookie.  May be a string, or @code{#f} if no value is needed.
@item <comment> <url> <domain> <path> <port-list>
Strings.
@item <bool>
Boolean value
@item <age> <version>
Integers
@item <date>
Either an integer (seconds since Epoch) or a formatted date string
following the netscape cookie specification.
@end table
@c JP
@table @code
@item <name>
文字列。クッキーの名前。
@item <value>
クッキーの値。文字列か、値が必要なければ @code{#f} 。
@item <comment> <url> <domain> <path> <port-list>
文字列。
@item <bool>
真偽値。
@item <age> <version>
整数。
@item <date>
整数(エポックからの秒数)か、Netscape のクッキー仕様に従うフォーマットされた
日付文字列。
@end table
@c COMMON

@c EN
The attribute values are quoted appropriately.  If the specified attribute
is irrelevant for the @var{version}, it is ignored.  So you can pass
the same specs to generate both old-style and new-style cookie strings.

Return value is a list of cookie strings, each of which stands for
each cookie.  For old-style protocol (using @code{Set-cookie} header)
you must send each of them by individual header.  For new-style
protocol (using @code{Set-cookie2} header), you can join them
with comma and send it at once.  See RFC6265 for further details.

Some examples:
@c JP
属性値は適切にクォートされます。指定された属性が @var{version} に不適切な
場合は無視されます。古いスタイルと新しいスタイルの両方のクッキー文字列を
作るために同じ仕様を渡すことができます。

戻り値はそれぞれのクッキー文字列のリストです。(@code{Set-cookie} を使う)
古いスタイルのプロトコルでは、それぞれを独立したヘッダとして送らなければ
なりません。(@code{Set-cookie2} ヘッダを使う)新しいプロトコルでは、
それらをカンマで繋ぎ、一度に送ることができます。詳細は RFC6265 を見て下さい。

いくつかの例を示します。
@c COMMON
@example
(construct-cookie-string
   `(("name" "foo" :domain "foo.com" :path "/"
                   :expires ,(+ (sys-time) 86400) :max-age 86400)))
 @result{} ("name=foo;Domain=foo.com;Path=/;Max-age=86400")

(construct-cookie-string
   `(("name" "foo" :domain "foo.com" :path "/"
                   :expires ,(+ (sys-time) 86400) :max-age 86400))
   0)
 @result{}
 ("name=foo;Domain=foo.com;Path=/;Expires=Sun, 09-Sep-2001 01:46:40 GMT")
@end example
@end defun

@c ----------------------------------------------------------------------
@node FTP, HMAC keyed-hashing, HTTP cookie handling, Library modules - Utilities
@section @code{rfc.ftp} - FTP client
@c NODE FTPクライアント, @code{rfc.ftp} - FTPクライアント

@deftp {Module} rfc.ftp
@mdindex rfc.ftp
@c EN
This module provides a set of convenient functions to access ftp
servers.
@c JP
このモジュールはFTPサーバーにアクセスするための便利関数群を提供します。
@c COMMON
@end deftp

@deftp {Class} <ftp-connection>
@clindex ftp-connection
@c EN
An object to keep FTP connection to a server.  It has the following
public slots.
@c JP
ひとつのサーバーへのFTPコネクションを保持するオブジェクト。以下の公開
スロットがあります。
@c COMMON

@defivar {<ftp-connection>} transfer-type
@c EN
FTP transfer type.  Must be one of the following symbols:
@code{ascii}, @code{binary} (default), and @code{image}.
@c JP
FTPの転送タイプ。以下のシンボルのどれかひとつでなければなりません。
@code{ascii}、@code{binary} (デフォルト)、および@code{image}。
@c COMMON
@end defivar

@defivar {<ftp-connection>} passive
@c EN
True if the client uses passive connection.c
@c JP
パッシブコネクションを使うとき真。
@c COMMON
@end defivar

@defivar {<ftp-connection>} log-drain
@c EN
This slot must hold a @code{<log-drain>} instance (@xref{User-level logging})
or @code{#f}.  If it has a @code{<log-drain>} instance, ftp communication
logs are put to it.
@c JP
このスロットは@code{<log-drain>}のインスタンス(@ref{User-level logging}参照)
を保持しているかあるいは@code{#f}でなければなりません。@code{<log-drain>}
のインスタンスを保持している場合、FTP通信のログがそこに記録されます。
@c COMMON

@end defivar
@end deftp

@deftp {Condition Type} <ftp-error>
@clindex ftp-error
@c EN
This type of exception is thrown when the ftp server returns an error code.
Inherits @code{<error>}.  The message field contains the server reply,
including the status code.
@c JP
このタイプの例外はFTPサーバーがエラーコードを返したときに投げられます。
@code{<error>}を継承しています。メッセージフィールドにはステータスコー
ドを含むサーバーからの返答が含まれます。
@c COMMON
@end deftp

@defun call-with-ftp-connection host proc :key passive port username password account log-drain
@c EN
A high-level convenience routine to open an ftp connection to
an ftp server and calls the given procedure.
@c JP
高水準の便利関数で、ひとつのFTPサーバーへのFTPコネクションをオープンし、
与えられた手続きを呼びます。
@c COMMON

@c EN
The server is specified by @var{host}.  Optionally, you can add user
name and/or port number by the form 
@code{@var{user}@@@var{servername}:@var{port}}.
If present, user and port portion in @var{host} supersedes the
keyword arguments.
@c JP
接続するサーバーは@var{host}で指定します。オプションでユーザー名、ポー
ト番号を@code{@var{user}@@@var{servername}:@var{port}}という形式で指定
できます。もしあれば、@var{host}の部分をキーワード引数にすることもでき
ます。
@c COMMON

@c EN
If ftp connection to @var{host} is established successfully, 
@var{proc} is called with one argument, which is an instance
of @code{<ftp-connection>}.  When @var{proc} returns, 
the connection is closed and the return value(s) of @var{proc}
is/are returned from @code{call-with-ftp-connection}.
When an exception is thrown, the ftp connection is closed
before the exception escapes from @code{call-with-ftp-connection}.
@c JP
@var{host}へのFTPコネクション確立が成功したら、@var{proc}が引数を1つとっ
て呼ばれます。この引数は@code{<ftp-connection>}のインスタンスです。
@var{proc}から返ったときにこのコネクションはクローズされ、@var{proc}の
返り値が@code{call-with-ftp-connection}から返されます。例外がなげられ
たら、その例外が@code{call-with-ftp-connection}から外へでる前にFTPコネ
クションはクローズされます。
@c COMMON

@c EN
When a true value is given to the keyword argument @var{passive},
created ftp connection will use passive mode to send/receive
data.  The default is the active mode.
@c JP
キーワード引数@var{passive}に真値を与えると、FTPコネクションはパッシブ
モードになります。デフォルトではアクティブモードです。
@c COMMON

@c EN
The keyword argument @var{port}, @var{username}, and @var{password}
specify the port number, username, and password, respectively.
When omitted, the port number defaults to 21, @var{username} to
@code{"anonymous"}, and @var{password} to @code{"anonymous@@"}.
Note that the port number and/or username are ignored when
those information is given in the @var{host} argument.
@c JP
キーワード引数@var{port}、@var{username}および@var{password}は
それぞれ、ポート番号、ユーザー名、パスワードを指定するのに使います。
省略された場合のデフォルトは、ポート番号が21,@var{username}が
@code{"anonymous"}、@var{password}が@code{"anonymous@@"}にセットされま
す。ポート番号とユーザー名は@var{host}引数で指定されたものが優先されま
す。
@c COMMON

@c EN
If the keyword arugment @var{account} is given, its value
is passed to ftp @code{ACCT} command when requested by
the server at login time.  The defalut value is a null string @code{""}.
@c JP
キーワード引数@var{account}が与えられた場合には、その値が、ログイン時
にサーバーからの要求でFTPの@code{ACCT}コマンドに渡されます。デフォルト
では空文字列@code{""}です。
@c COMMON

@c EN
The keyword argument @var{log-drain} is set to the created
ftp connection's @code{log-drain} slot.
@c JP
キーワード引数@var{log-drain}が生成したFTPコネクションの
@code{log-drain}スロットに設定されます。
@c COMMON
@end defun

@defun ftp-transfer-type conn
@c EN
Returns the transfer type of the ftp connection @code{conn}.
Can be used with setter, e.g. @code{(set! (ftp-transfer-type conn) 'ascii)}.
@c JP
指定したFTPコネクション@code{conn}の転送タイプを返します。セッターを適
用することもできます。たとえば、@code{(set! (ftp-transfer-type conn) 'ascii)}
とします。
@c COMMON
@end defun

@defun ftp-passive? conn
@c EN
Returns true iff ftp connection uses passive data retrieval.
@c JP
指定したFTPコネクションがパッシブモードである場合でその場合に限り真を
返します。
@c COMMON
@end defun

@defun ftp-login host :key passive port username password account log-drain
@c EN
Connects to the ftp server specified by @var{host}, authenticate the user,
and returns a newly created @code{<ftp-connection>} instance.
This procedure is called implicitly when you use
@code{call-with-ftp-connection}.  The semantics of
the @var{host} argument and the keyword arguments are
the same as @code{call-with-ftp-connection}.
@c JP
@var{host}で指定されたFTPサーバーに接続し、ユーザー認証をすませ、新し
く生成した@code{<ftp-connection>}のインスタンスを返します。この手続き
は@code{call-with-ftp-connection}を使ったときに暗黙の内に呼ばれます。
@var{host}引数およびキーワード引数のセマンティクスは
@code{call-with-ftp-connection}と同じです。
@c COMMON
@end defun

@defun ftp-quit conn
@c EN
Sends ftp @code{QUIT} command to the connection @var{conn} and
shutdown the connection.
This procedure is called implicitly when you use
@code{call-with-ftp-connection}.
@c JP
FTPの@code{QUIT}コマンドをコネクション@var{conn}に送り、コネクションを
シャットダウンします。この手続きは@code{call-with-ftp-connection}を使っ
たときに暗黙の内に呼ばれます。
@c COMMON

@c EN
Once a connection is shut down, you cannot communicate through
this connection.
@c JP
いったんシャットダウンしたコネクションをつかっての通信はできません。
@c COMMON
@end defun

@defun ftp-chdir conn dirname
@c EN
Changes the remote directory to @var{dirname}.
@c JP
リモートディレクトリを@var{dirname}に変更します。
@c COMMON
@end defun

@defun ftp-remove conn path
@c EN
Removes the remote file named by @var{path}.
@c JP
@var{path}で指定したリモートファイルを削除します。
@c COMMON
@end defun

@defun ftp-help conn :optional option @dots{}
@c EN
Sends ftp @code{HELP} commands.  @var{Option}s must be strings,
and will be passed to the @code{HELP} command arguments.
@c JP
FTPコマンド@code{HELP}を送ります。@var{Option}は文字列でなければなりま
せん。これは@code{HELP}コマンドの引数にわたされます。
@c COMMON
@end defun

@defun ftp-mkdir conn dirname
@c EN
Creates a directory @var{dirname}.  Returns the created directory
name.
@c JP
ディレクトリ@var{dirname}を作成します。作成されたディレクトリ名が返り
ます。
@c COMMON
@end defun

@defun ftp-current-directory conn
@c EN
Returns the current remote directory.
@c JP
現在のリモートディレクトリを返します。
@c COMMON
@end defun

@defun ftp-site conn arg
@c EN
Sends ftp @code{SITE} command with the argument @var{arg}.
The @code{SITE} command's semantics depends on the server.
Returns the server reply.
@c JP
FTPコマンド@code{SITE}を引数@var{arg}とともに送ります。@code{SITE}コマ
ンドのセマンティクスはサーバーに依存します。返り値はサーバーのリプライ
です。
@c COMMON
@end defun

@defun ftp-rmdir conn dirname
@c EN
Removes remote directory specified by @var{dirname}.
Returns the server reply.
@c JP
@var{dirname}で指定したリモートディレクトリを削除します。返り値はサー
バーのリプライです。
@c COMMON
@end defun

@defun ftp-stat conn :optional pathname
@c EN
Sends ftp @code{STAT} command to the server.
RFC959 defines several different semantics of this command.
See RFC959 for the details.
Returns the server reply.
@c JP
FTPコマンド@code{STAT}をサーバーに送信します。
RFC959ではこのコマンドのセマンティクスをいくつか定義しています。詳細は
RFC959を見てください。返り値はサーバーのリプライです。
@c COMMON
@end defun

@defun ftp-system conn
@c EN
Queries the server's operating system by ftp @code{SYST} command.
Returns the server reply without status code.
@c JP
FTPコマンド@code{SYST}をつかってサーバーのオペレーティングシステムを問
合せます。返り値はステータスコードを含まないサーバーのリプライです。
@c COMMON

@example
(call-with-ftp-connection "localhost" ftp-system)
  @result{} "UNIX Type: L8"
@end example
@end defun

@defun ftp-size conn path
@c EN
Queries the size of the remote file specified by @var{path}.
Returns the integer value.

Note: The size may differ whether the connection is in ascii mode
or binary mode; furthermore, some ftp server may returns the value
only if the connection is in binary mode.  Make sure you have
desired transfer type in the connection.
@c JP
@var{path}で指定したリモートファイルのサイズを問合せます。
整数値が返ります。

註：コネクションがasciiモードかbinaryモードかによって、返されるサイズは
異なるかもしれません。ftpサーバによっては、binaryモードでしか
sizeリクエストに答えないものもあります。この関数を呼ぶ際には、
コネクションに望みのtransfer typeがセットされているようにしてください。
@c COMMON
@end defun

@defun ftp-mdtm conn path
@c EN
Queries the modification time of the remote file specified by @var{path}.
This function returns the server's reply as is, including the status
code.  Use @code{ftp-mtime} below to obtain a parsed result.
@c JP
@var{path}で指定したリモートファイルの更新時刻を問合せます。この関数は
サーバーからのリプライをステータスコードも含めそのまま返します。解析済
みの結果が欲しいときは後述の@code{ftp-mtime}を使ってください。
@c COMMON
@end defun

@defun ftp-mtime conn path :optional local-time?
@c EN
Queries the modification time of the remote file specified by @var{path},
and returns the result in a @code{<date>} object 
(@xref{Time data types and procedures}).
If a true value is given to @code{local-time?}, the returned date is
in local time.  Otherwise, the returned date is in UTC.
@c JP
@var{path}で指定したリモートファイルの更新日時を問合せます。結果は
@code{<date>}オブジェクト(@ref{Time data types and procedures}参照)で
返ります。@code{local-time?}が真値に設定されている場合、日付はローカル
時刻で返ります。そうでない場合は日付はUTCです。
@c COMMON
@end defun

@defun ftp-noop conn
@c EN
Sends ftp @code{NOOP} command and returns the server's reply.
@c JP
FTPコマンド@code{NOOP}を送り、サーバーからのリプライを返します。
@c COMMON
@end defun

@defun ftp-list conn :optional path
@c EN
Returns the information about the files within the remote file 
or directory specified by @var{path}, or the current remote directory,
much like @code{ls(1)} format.  Returns a list of strings, where
each string is for each line of the server's reply.  The exact
format depends on the server.
@c JP
@var{path}で指定されたリモートディレクトリあるいはリモートファイル内の
ファイルに関する情報を返します。@var{path}指定がない場合は現在のリモー
トディレクトリで、結果のフォーマットは@code{ls(1)}のフォーマットと非常
によく似ています。文字列のリストが返り、それぞれの文字列はサーバーのリ
プライの行に対応します。正確なフォーマットについてはサーバーに依存しま
す。
@c CoMMON
@end defun

@defun ftp-name-list conn :optional path
@defunx ftp-ls conn :optional path
@c EN
Return the list of names in the specfied @var{path}, or the current
remote directory, without any other information.  @code{ftp-ls}
is just an alias of @code{ftp-name-list} for the convenience.
@c JP
@var{path}で指定したパスもしくは現在のリモートディレクトリにあるファイ
ル名リストを返します。ただし、他の情報は含みません。@code{ftp-ls}は
@code{ftp-name-list}の別名です。便利なので定義してあります。
@c COMMON

@c EN
Note that the server may return an error if there's no files
in the remote directory.
@c JP
リモートディレクトリにファイルが含まれていないときにはサーバーはエラー
を返すことがあることに注意してください。
@c COMMON
@end defun

@defun ftp-get conn path :key sink flusher
@c EN
Retrieves a remote file @var{path}.  The retrieved data is
sent to an output port given to @var{sink}.  Once all the data
is retrieved, a procedure given to @var{flusher} is called
with the port @var{sink} as an argument, and its return value(s)
is/are returned from @code{ftp-get}.  
@c JP
リモートファイル@var{path}を検索します。検索データは@var{sink}で与えら
れた出力ポートに送られます。すべてのデータが検索されたあと、
@var{flusher}で与えられた手続きをポート@var{sink}を引数として呼びます。
返り値は@code{ftp-get}から返されたものです。
@c COMMON

@c EN
The default values of @var{sink} and @var{flusher} are
a newly created string port and @code{get-output-string}, respectively.
That is, @code{ftp-get} returns the retrieved data as a string
by default.
You don't want this behavior if the retrieved file is huge.
@c JP
@var{sink}および@var{flusher}のデフォルト値はそれぞれ、新しく作成され
た文字列ポートと@code{get-output-string}です。すなわち、@code{ftp-get}
はデフォルトでは検索データを文字列として返します。巨大なファイルの場合
このデフォルトの挙動ではありがたくありません。
@c COMMON
@end defun

@defun ftp-put conn from-file :optional to-file
@c EN
Sends the local file specified by @var{from-file} to the remote
server as the name specified by @var{to-file}.  If @var{to-file}
is omitted, the basename of @var{from-file} is used.
Returns the server response.
@c JP
@var{from-file}で指定したローカルファイルを@var{to-file}で指定した名前
でリモートサーバーに送信します。@var{to-file}が省略された場合にはベー
ス名として@var{from-file}が使われます。返り値はサーバーのレスポンスで
す。
@c COMMON
@end defun

@defun ftp-put-unique conn from-file
@c EN
Sends the local file specified by @var{from-file} to the 
remote server.  The remote side filename is guaranteed to 
be unique.  Returns two values---the final server response,
and the remote file name.  The second value can be @code{#f}
if the remote host doesn't support RFC1123 (which must be rare).
@c JP
@var{from-file}で指定したローカルファイルをリモートサーバーへ送信しま
す。リモート側のファイル名重複しないことを保証します。返り値は2つで、
最終的なリモートサーバーからのレスポンスとリモートファイル名です。2つ
めの値は、リモートサーバーがRFC1123をサポートしていない(ほとんどない)
場合に@code{#f}になります。
@c COMMON
@end defun

@defun ftp-rename conn from-name to-name
@c EN
Renames the remote file specified by @var{from-name} to the
name @var{to-name}.  Returns the final response of the server.
@c JP
@var{from-name}で指定したリモートファイル名を@var{to-name}に変更する。
返り値は最終的なサーバーのレスポンスです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node HMAC keyed-hashing, HTTP, FTP, Library modules - Utilities
@section @code{rfc.hmac} - HMAC keyed-hashing
@c NODE HMAC鍵付きハッシング, @code{rfc.hmac} - HMAC鍵付きハッシング

@deftp {Module} rfc.hmac
@mdindex rfc.hmac
@c EN
This module implements HMAC algorithm,
Keyed-hashing for message authentication, defined in RFC 2104.

For simple batched keyed hashing, you can use high-level API 
@code{hmac-digest} and @code{hmac-digest-string}.
Or you can create @code{<hmac>} object and update its state
as the data coming in.
@c JP
このモジュールは、RFC 2104で定義されている、メッセージ認証のための
鍵付きハッシングのHMACアルゴリズムを実装しています。

シンプルなバッチ処理での鍵付きハッシングでは、高レベルなAPIである
@code{hmac-digest}と@code{hmac-digest-string}が使えます。
あるいは、@code{<hmac>}オブジェクトを作成して、入力となるデータで
その状態を更新することもできます。
@c COMMON
@end deftp

@deftp {Class} <hmac>
@clindex hmac
@c EN
Keeps state information of HMAC algorithm.
Key and the hashing algorithm should be given at the construction
time, using @code{:key} and @code{:hasher} keyword-arguments respectively.
You can pass any class object that implements message digest 
interface (@xref{Message digester framework}),
such as @code{<md5>} (@xref{MD5 message digest})
or @code{<sha256>} (@xref{SHA message digest}).

Example:
@c JP
HMACアルゴリズムの状態情報を保持します。
鍵とハッシングアルゴリズムは、キーワード引数@code{:key}と@code{:hasher}を
それぞれ使って、生成時に与えます。
@code{<md5>} (@ref{MD5 message digest}参照)や
@code{<sha256>} (@ref{SHA message digest}参照)などのような
ダイジェストインタフェース(@ref{Message digester framework}参照)を
実装するいかなるクラスオブジェクトを渡すこともできます。

例:
@c COMMON
@example
(make <hmac> :key (make-byte-string 16 #x0b) :hasher <md5>)
@end example
@end deftp

@deffn {Method} hmac-update! (hmac <hmac>) data
@c EN
Updates the internal state of @var{hmac} by @var{data},
which must be represented by a (possibly incomplete) string.
@c JP
(不完全かもしれない)文字列で表現される@var{data}により、
@var{hmac}の内部状態を更新します。
@c COMMON
@end deffn

@deffn {Method} hmac-final! (hmac <hmac>)
@c EN
Finalizes the internal state of @var{hmac} and returns the
hashed string in incomplete string.
You can use @code{digest-hexify}
(@xref{Message digester framework}) to obtain "hexified"
result.
Once finalized, you can't call @code{hmac-update!} or @code{hmac-final!}
on @var{hmac}.
@c JP
@var{hmac}の内部状態を終了させ、不完全文字列でハッシュされた文字列を
返します。
``hexified''(16進化)された結果を得るために、@code{digest-hexify}
(@ref{Message digester framework}参照)を使うことが
できます。
一旦終了されると、@var{hmac}に対しては@code{hmac-update!}や
@code{hmac-final!}を呼ぶことはできません。
@c COMMON
@end deffn

@deffn {Method} hmac-digest :key key hasher
@c EN
Creates an @code{<hmac>} object and hash the data stream
from the current input port, then returns the hashed result
in an incomplete string.
@c JP
@code{<hmac>}オブジェクトを作り、現在の入力ポートからの
データストリームをハッシュし、不完全文字列でそのハッシュされた
結果を返します。
@c COMMON
@end deffn

@deffn {Method} hmac-digest-string string :key key hasher
@c EN
Creates an @code{<hmac>} object and hash the data in @var{string},
then returns the hashed result in an incomplete string.
@c JP
@code{<hmac>}オブジェクトを作り、@var{string}にあるデータをハッシュし、
不完全文字列でそのハッシュされた結果を返します。
@c COMMON
@end deffn

@c ----------------------------------------------------------------------
@node HTTP, IP packets, HMAC keyed-hashing, Library modules - Utilities
@section @code{rfc.http} - HTTP

@deftp {Module} rfc.http
@mdindex rfc.http
@c EN
This module provides a simple client API for
HTTP/1.1, defined in RFC2616, "Hypertext Transfer Protocol -- HTTP/1.1"
@c JP
このモジュールは、RFC2616 "Hypertext Transfer Protocol -- HTTP/1.1"
で定義されているHTTP/1.1に対する簡単なクライアントAPIを提供します。
@c COMMON
(@ref{rfc2616, [RFC2616], RFC2616}).

@c EN
Current API implements only a part of the protocol.
It doesn't talk with HTTP/1.0 server yet,
and it doesn't support HTTP/1.1 advanced features
such as persistent connection.
Support for those features may be added in the future versions.
@c JP
現在のAPIは、プロトコルの一部のみ実装されています。
HTTP/1.0のサーバーとはうまく通信できません。
また、HTTP/1.1の先進的機能、例えば永続的接続などはサポートしていません。
これらの機能は、将来のバージョンで追加されるでしょう。
@c COMMON
@end deftp

@deftp {Condition Type} <http-error>
@clindex http-error
@c EN
This type of condition is raised when the server terminates
connection prematurely or server's response has invalid
header fields.  Inherits @code{<error>}.
@c JP
サーバから接続が切られた場合や、サーバの返したHTTPレスポンスのフォーマットが
正しくない場合に投げられるコンディションです。@code{<error>}を継承します。
@c COMMON
@end deftp

@defun http-get server request-uri :key sink flusher no-redirect secure @dots{}
@defunx http-head server request-uri :key no-redirect secure @dots{}
@defunx http-post server request-uri body :key sink flusher no-redirect secure @dots{}
@defunx http-put server request-uri body :key sink flusher secure @dots{}
@defunx http-delete server request-uri :key sink flusher secure @dots{}

@c EN
Send http GET, HEAD, POST, PUT and DELETE requests to the http @var{server},
respectively, and returns the server's reply.

If the server returns "3xx" redirection reply, these procedures
try to follow the URI returned in the "location" reply message header
by default.  See the "keyword arguments" heading below to suppress
redirection following.
@c JP
@var{server}に、それぞれHTTPのGET、HEAD、POST、PUT、DELETEリクエストを送り、
サーバの応答を返します。

サーバが "3xx" のリダイレクトを指示する応答を返した場合、これらの手続きは
デフォルトで、応答のメッセージヘッダの "location" で返されるURIに従うよう
試みます。リダイレクションを抑制するには、下の"キーワード引数"を参照してください。
@c COMMON

@c EN
@strong{Required arguments:}
The @var{server} argument specifies http server name in a string.
A server name can be optionally followed by colon and a port number.
@c JP
@strong{必須の引数:}
@var{server}引数では、文字列でHTTPサーバ名を指定します。
サーバ名は、オプションでコロンに続いてポート番号を付加できます。
@c COMMON
Examples: @code{"w3c.org"}, @code{"mycompany.com:8080"}.

@c EN
The @var{request-uri} argument can be a string or a list.
If it is a string, it's @emph{request-uri} specified in
RFC2616; usually, this is the path part of http url.
The string is passed to the server as is, so the caller must
properly convert character encodings and perform necessary
url encodings.

If @var{request-uri} is a list, it must be in the following form:
@c JP
@var{request-uri}引数は文字列かリストです。
文字列の場合、RFC2616で規定されているリクエストURIと解釈されます。
通常これはHTTP URLのパス部分です。
文字列はそのままサーバに渡されるので、呼び出し側で必要な
文字コード変換やurlエンコーディングを行う必要があります。

@var{request-uri}がリストの場合は、次の形式でなければなりません。
@c COMMON

@example
(@var{path} (@var{name} @var{value}) ...)
@end example

@c EN
Here, @var{path} is a string specifying up to the path component
of the request-uri.
From provided alist of @var{name}s and @var{value}s,
http procedures compose a query string in 
@code{application/x-www-form-urlencoded} format
as defined in HTML4, and append it to @var{path}.
For example, the following two requests have the same effect.
Note that url escaping is automatically handled in the second call.
@c JP
ここで@var{path}はリクエストURIのパスコンポーネントまでを指定する
文字列です。与えられた@var{name}と@var{value}のalistから、
httpリクエスト手続きはHTML4で定められた
@code{application/x-www-form-urlencoded}形式の
クエリ文字列を構成し、@var{path}にアペンドします。
例えば次のふたつのリクエストは同じ効果を持ちます。
二番目の呼び出しではurlエスケープが自動的に行われることに注目してください。
@c COMMON

@example
(http-get "example.com" "/search?q=foo%20bar&n=20")

(http-get "example.com" '("/search" (q "foo bar") (n 20)))
@end example

@c EN
If @var{request-encoding} keyword argument is also given,
@var{name}s and @var{value}s 
are converted into the specified character encoding before url escaping.
If it is omitted, gauche's internal character encoding is used.
@c JP
@var{request-encoding}キーワード引数が与えられた場合、
@var{name}と@var{value}はまずその文字エンコーディングに変換されたのちに
urlエスケープされます。そうでない場合はgaucheの内部
エンコーディングがそのまま使われます。
@c COMMON

@c EN
Some procedures take the third argument, @var{body}, 
to specify the body of the request message.
It can be a string, which will be copied verbatim to the request body,
or a list, which will be encoded in @code{multipart/form-data} message.

If @var{body} is a list, it is a list of parameter specs.  Each parameter
spec is either a list of name and value, e.g.
@code{("submit" "OK")} or a name followed by keyword-value list,
e.g. @code{("upload" :file "logo.png" :content-type "image/png")}.

The first form is for the convenience.  It is also compatible to the
query parameter list in @var{request-uri}, so that you can use the
same format for GET and POST request.  Each value is put
in a MIME part with @code{text/plain} media type, with the
character encoding specified by @code{request-encoding} keyword argument
described below.

The second form allows further control over each MIME part's attributes.
The following keywords are treated specially.

@table @code
@item :value
Speficies the value of the parameter.  The convenience form,
@code{(@var{name} @var{val})}, is just an abbreviation of
@code{(@var{name} :value @var{val})}.
@item :file
Specifies the pathname of the file, whose content is inserted
as the value of the parameter.  Useful to upload a file.
This option has precedence over @code{:value}.
MIME type of the part is set to @code{application/octet-stream}
unless specified otherwise.
@item :content-type
Overrides the MIME type of the part.  A charset parameter is
added to the content-type if not given in this argument.
@item :content-transfer-encoding
Specifies the value of content-transfer-encoding; currently the
following values are supported: @code{7bit},
@code{binary}, @code{quoted-printable} and @code{base64}.
If omitted, @code{binary} is used.
@end table

Other keywords are used as the header of the MIME part.
@c JP
いくつかの手続きは、リクエストメッセージのボディを指定する@var{body}を第3引数として
取ります。@var{body}は文字列かリストで、文字列の場合はそのまま送られ、
リストの場合は@code{multipart/form-data}形式にエンコードされて送られます。

@var{body}がリストの場合、それはパラメータ指定のリストです。
各パラメータ指定は、@code{("submit" "OK")}のような名前と値のリスト、
もしくは@code{("upload" :file "logo.png" :content-type "image/png")}
のように名前の後にキーワード-値リストを付加したものです。

最初の形式は使うのが簡単で、また@var{request-uri}のクエリパラメータリストと
同じ形式なのでGETとPOSTでルーチンを共有したい場合にも便利でしょう。
この形式では、各値はMIMEパーとに@code{text/plain}として置かれます。
文字コードは下に述べる@code{request-encoding}キーワード引数により変換されます。

二番目の形式では、MIMEパートの属性についてより細かな指定を行うことができます。
以下のキーワードが特別に扱われます。

@table @code
@item :value
パラメータの値を指定します。簡潔な@code{(@var{name} @var{val})}形式は
@code{(@var{name} :value @var{val})}の省略形です。
@item :file
指定された名前のファイルの中身をパラメータの値として挿入します。
ファイルのアップロードに便利です。このオプションは@code{:value}より
優先されます。MIMEタイプは、指定が無ければ
@code{application/octet-stream}となります。
@item :content-type
MIMEタイプをオーバライドします。与えられた値にcharsetパラメータが
ついていない場合は自動的に付加されます。
@item :content-transfer-encoding
content-transfer-encodingを
@code{7bit}、@code{binary}、@code{quoted-printable}、@code{base64}の
いずれかで指定します。指定が無ければ@code{binary}が使われます。
@end table

残りのキーワードはMIMEパートのヘッダにそのまま使われます。
@c COMMON

@c EN
@strong{Return values:}
All procedures return three values.

The first value is the status code defined in RFC2616
in a string (such as "200" for success, "404" for "not found").
@c JP
@strong{戻り値:}
全ての手続きは3つの値を返します。

1つ目は、RFC2616で定義されているステータスコードの文字列値(例えば、成功時の
200、"Not found"の404など)です。
@c COMMON

@c EN
The second value is a list of parsed headers---each element of list
is a list of @code{(@var{header-name} @var{value} @dots{})}, 
where @var{header-name} is a string name of the header
(such as "content-type" or "location"), and @var{value} is
the corresponding value in a string.  The header name is converted
to lowercase letters.  The value is untouched except that "soft line breaks"
are removed, as defined in RFC2822.   If the server returns
more than one headers with the same name, their values are
consolidated to one list.  Except that, the order of the header list
in the second return value is the same as the order in the server's reply.
@c JP
2つ目は、パーズされたヘッダのリストで、リストの要素は@code{(@var{header-name}
@var{value} @dots{})}です。@var{header-name}はヘッダの文字列名(例えば、
"content-type"や"location"など)で、@var{value}は対応する値の文字列値です。
ヘッダ名は小文字に変換されます。値は、RFC2822で定義されている無指定行区切
(ソフト・ライン・ブレイク)が除かれる以外はそのままです。
サーバが同じ名前のヘッダを1つ以上返した場合は、
1つのリストに統合されます。それ以外では、2つ目の戻り値に
おけるヘッダのリストの順番は、サーバの応答での順番と同じです。
@c COMMON

@c EN
The third value is for the message body of the server's reply.
By default, it is a message body itself in a string.   If the server's
reply doesn't have a body, the third value is @code{#f}.  You can
change how the message body is handled by keyword arguments; for example,
you can directly store the returned message body to a file without
creating intermediate string.  The details are explained below.
@c JP
3つ目の戻り値は、サーバの応答におけるメッセージボディです。
デフォルトでは、文字列で表現されたメッセージボディそのものです。
サーバの応答がボディを持たない場合、3つ目の戻り値は@code{#f}です。
キーワード引数によって、メッセージボディがどのように扱われるかを制御できます。
例えば、中間的な文字列を作らずに、返されたメッセージボディを直接ファイルに
格納することが出来ます。詳細は以下で説明しています。
@c COMMON

@c EN
@strong{Keyword arguments:}
By default, these procedures only attaches @code{"Host"} header
field to the request message.  You can give keyword arguments
to add more header fields.
@c JP
@strong{キーワード引数:}
デフォルトで、これらの手続きはリクエストメッセージに@code{"Host"}ヘッダ・フィールドを
追加するだけです。他のヘッダ・フィールドを追加するためにキーワード引数を
与えることができます。
@c COMMON
@example
(http-get "foo.bar.com" "/index.html"
  :accept-language "ja"
  :user-agent "My Scheme Program/1.0")
@end example

@c EN
The following keyword arguments are recognized by the procedure
and do not appear in the request headers.
@c JP
以下のキーワード引数は手続きによって解釈され、リクエストヘッダには現れません。
@c COMMON

@table @var
@item request-encoding
@c EN
When a list is given to the @var{request-uri} or @var{body} arguments,
the characters in names and values of the parameters are first 
converted to the character encoding specified by this keyword
argument, then encoded into @code{application/x-www-form-urlencoded}
or @code{multipart/form-data} MIME formats.
If this argument is omitted, Gauche's internal character encoding is used.

For @code{multipart/form-data}, you can override character encodings
for individual parameters by giving @code{content-type} header.
See the description of @var{body} arguments above.

If you give a string to @var{request-uri} or @var{body}, 
it is used without encoding conversion.  It is caller's responsibility
to ensure desired character encodings are used.
@c JP
@var{request-uri}や@var{body}がリストで与えられた場合、パラメータの
名前や値はまずこの引数で指定される文字エンコーディングへと変換され、
その後、@code{application/x-www-form-urlencoded}や
@code{multipart/form-data} MIME形式にしたがったエンコーディングが行われます。
この引数が省略された場合はGaucheの内部文字エンコーディングが使われます。

@code{multipart/form-data}については、パラメータに@code{content-type}ヘッダを
与えることでパラメータごとに文字エンコーディングの設定をオーバライドできます。
詳しくは上の@var{body}引数の説明を参照してください。

@var{request-uri}や@var{body}に文字列を与えた場合は、文字エンコーディング変換は
行われません。呼び出し側で望みの文字コードにあらかじめ変換しておいてください。
@c COMMON
@item proxy
@c EN
Specify http proxy server in a string of a form @code{hostname} or
@code{hostname:port}.
@c JP
httpプロキシサーバを、@code{hostname}または@code{hostname:port}形式の
文字列で指定します。
@c COMMON
@item no-redirect
@c EN
If a true value is given, suppress the redirection tracking;
i.e. the procedures return "3xx" message as is.
@c JP
真の値が与えられた場合、リダイレクションには従わなくなります。すなわち、
手続きは"3xx"のメッセージをそのまま返します。
@c COMMON
@item secure
@c EN
If a true value is given, use secure connection (https).
If a secure connection is not available on the running platform,
an error is signalled.  See the ``Secure connection'' section below.
@c JP
真の値が与えられた場合、セキュアな接続(https)を使います。
セキュアな接続が実行中のプラットフォームで利用できない場合はエラーが投げられます。
下の「セキュアな接続」の項も参照してください。
@c COMMON
@item sink, flusher
@c EN
You can customize how the reply message body is handled by these
keyword arguments.  You have to pass an output port to @var{sink},
and a procedure that takes two arguments to @var{flusher}.

When the procedure starts receiving the message body, it
feeds the received chunk to @var{sink}.  When the procedure
receives entire message body, @var{flusher} method is called
with @var{sink} and a list of message header fields (in the
same format to be returned in the second value from the procedure).
The return value of @var{flusher} becomes the third return value
from the procedure.

So, the default value of @var{sink} is a newly opened string
port and the default value of @var{flusher} is
@code{(lambda (sink headers) (get-output-string sink))}.

The following example saves the message body directly to a file,
without allocating (potentially very big) string buffer.
@c JP
これらのキーワード引数によりリプライメッセージ・ボディがどのように扱われるかを
カスタマイズできます。@var{sink}には出力ポートを、@var{flusher}には2引数を
取る手続きを渡さなければなりません。

手続きがメッセージ・ボディを受信し始めると、@var{sink}へ受け取った
データ片をフィードします。手続きがメッセージ・ボディを受信し終わると、
@var{flusher}に与えられた手続きが、@var{sink}と(手続きからの2つ目の
戻り値と同じフォーマットの)メッセージ・ヘッダ・フィールドのリストとともに
呼び出されます。@var{flusher}の戻り値が、手続きからの3つ目の戻り値と
なります。

したがって、@var{sink}のデフォルト値は、新しく開かれた文字列ポートで、
@var{flusher}のデフォルト値は@code{(lambda (sink headers) (get-output-string sink))}
とも言えます。

以下のサンプルは、(とても大きい可能性のある)文字列バッファを作らずに、
メッセージ・ボディを直接ファイルに保存します。
@c COMMON
@example
(call-with-output-file "page.html"
  (lambda (out)
    (http-get "www.schemers.org" "/"
       :sink out :flusher (lambda _ #t))))
@end example

@end table

@end defun

The module also provides some utility procedures.

@deffn {Parameter} http-user-agent :optional value
@c EN
The value of this parameter is used as a default value
to pass to the user-agent header.
The default value is something like @code{gauche.http/*},
where @code{*} is Gauche's version.
An application is encouraged to set this parameter appropriately.
@c JP
user-agentヘッダに渡される値のデフォルト値を指定するパラメータです。
デフォルトの値は@code{gauche.http/*} (@code{*}部分はGaucheのバージョン)
になっています。
各アプリケーションは適切な値を設定するようにしてください。
@c COMMON
@end deffn

@defun http-compose-query path params :optional encoding
A helper procedure to create a request-uri from
a list of query parameters.  @var{Encoding} specifies
the character encodings to be used.

@example
(http-compose-query "/search" '((q "$foo") (n 20)))
 @result{} "/search?q=%24foo&n=20"
@end example
@end defun

@defun http-compose-form-data params port :optional encoding
A helper procedure to create @code{multipart/form-data}
from a list of parameters.  The format of @var{params} argument 
is the same as the list format of @var{body} argument of
http request procedures.  The result is written to an output
port @var{port}, and the boundary string used to compose
MIME message is returned.  Alternatively you can pass @code{#f}
to the @var{port} to get the result in a string.
In that case, two values are returned, the MIME message string
and the boundary string.

@var{Encoding} specifies the character encodings to be used.
@end defun

@c EN
@subheading Secure connection
@c JP
@subheading セキュアな接続
@c COMMON

When you pass a true value to @code{secure} keyword argument,
The request-making APIs such as @code{http-get} use a secure
connection.  That is, it connects with @code{https} instead of
@code{http}.

Currently Gauche relies on an external program @code{stunnel}
(either version 3 or 4)
to handle secure connections.  So when you request a secure
connection, Gauche looks for @code{stunnel} program in @code{PATH}.
On some systems a newer version of it is called @code{stunnel4},
and Gauche looks for it, too.
If you want to add certificates, for example, you have to
adjust @code{stunnel} settings.

A plan is to provide the means of secure connections as long as
@code{stunnel}, including native SSL support, and the higher-level
library automatically choose whatever is available and best.

Use the following procedure to check if you can use secure
connections:

@defun http-secure-connection-available?
Returns @code{#t} if running Gauche can use secure connection,
@code{#f} otherwise.
@end defun

@c ----------------------------------------------------------------------
@node IP packets, ICMP packets, HTTP, Library modules - Utilities
@section @code{rfc.ip} - IP packets
@c NODE IPパケット, @code{rfc.ip} - IPパケット

@deftp {Module} rfc.ip
@mdindex rfc.ip
@c EN
This module provides some basic utilities to parse raw IP packets.
@c JP
このモジュールは生のIPパケットを解析する基本的なユーティリティを提供し
ます。
@c COMMON
@end deftp

@c EN
The @var{packet} argument in the following functions must be
any type of uniform vector (@xref{Uniform vectors}), containing
a raw IP packet including its IP header.
Those functions work for both IPv4 and IPv6 packets; however,
reading from a raw IPv6 socket returns a packet without IPv6 header,
so you usually don't need to use these functions.
@c JP
次からの関数における@var{packet}引数はユニフォームベクタ
(@ref{Uniform vectors}参照)型でなければなりません。これにはIPヘッダを
含む生のIPパケットが入ります。以下の関数はIPv4およびIPv6パケットの両方
で動きます。しかしながら、生のIPv6ソケットから読むときは、IPv6ヘッダを
含まないパケットが返ります。とうわけで、通常これらの関数が必要になるこ
とはないでしょう。
@c COMMON

@c EN
The @var{offset} argument specifies the beginnig of the IP packet
in @var{packet}.  If @var{packet} contains only one IP packet
you can pass 0.  It is not an optional argument, since these routines
may be used in speed-sensitive inner loop.
@c JP
@c COMMON

@defun ip-version packet offset
@c EN
Returns the IP version number (either 4 or 6) of the given IP packet.
@c JP
与えられたIPパケットのIPバージョン番号(4または6)が返ります。
@c COMMON
@end defun

@defun ip-header-length packet offset
@c EN
Returns the size of IP header of the given packet in octets,
including any IP header options.
@c JP
与えられたパケットのIPヘッダ(IPヘッダオプションもすべて含む)のオクテッ
トで数えたサイズを返します。
@c COMMON
@end defun

@defun ip-protocol packet offset
@c EN
Returns the IP protocol number of the given packet.
@c JP
与えられたパケットのIPプロトコル番号を返します。
@c COMMON
@end defun

@defun ip-source-address packet offset
@defunx ip-destination-address packet offset
@c EN
Returns the source and destination address in the given packet
in an integer, respectively.
@c JP
与えられたパケットの送信元アドレスと送信先アドレスをそれぞれ整数で返し
ます。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node ICMP packets, JSON parsing and construction, IP packets, Library modules - Utilities
@section @code{rfc.icmp} - ICMP packets
@c NODE ICMPパケット, @code{rfc.icmp} - ICMPパケット

@deftp {Module} rfc.icmp
@mdindex rfc.icmp
@c EN
This module provides some basic utilities to construct and parse ICMP
packets.
@c JP
このモジュールではICMPパケットの構築および解析用の基本的ユーティリティ
を提供しています。
@c COMMON
@end deftp

@c EN
For the functions below, @var{buffer} should be a writable 
u8vector of the enough size.
@c JP
以下の関数の@var{buffer}は十分なサイズの書き込み可能なu8vectorでなけれ
ばなりません。
@c COMMON

@c EN
Parsing functions takes @var{offset} as well as @var{buffer},
which specifies the beginning of the ICMP packet.  Using the offset
you can carry the whole IP packet in @var{buffer}, without
creating a new buffer to extract ICMP portion.
@c JP
解析用の関数は@var{buffer}のほかに@var{offset}を引数としてとります。こ
れはICMPパケットの開始位置を示すものです。このオフセットを用いて、ICMP
部分を取り出して新しいバッファを作るということなしに、IPパケット全体を
@var{buffer}内に格納できます。
@c COMMON

@defun icmp4-fill-echo! buffer ident sequence data
@c EN
Fills @var{buffer} with the ICMPv4 Echo Request packet.
@var{Data} must be a u8vector.  The checksum field is
left to be zero, which can be filled by @code{icmp4-fill-checksum!}.
@c JP
@var{buffer}にICMPv4のエコーリクエストパケットを詰め込みます。
@var{Data}はu8vectorでなければなりません。チェックサムフィールドはゼロ
のままです。チェックサムは@code{icmp4-fill-checksum!}を使って埋め込み
ます。
@c COMMON
@end defun

@defun icmp4-fill-checksum! buffer size
@c EN
Calculates the ICMPv4 checksum of the packet in the @var{buffer},
of @var{size} length (the size of the packet, not the buffer),
and fills the checksum field of the packet.
@c JP
@var{buffer}中の@var{size}(バッファではなくパケットの長さ)分のパケット
のICMPv4チェックサムを計算し、そのパケットのチェックサムフィールドをう
めます。
@c COMMON
@end defun

@defun icmp6-fill-echo! buffer ident sequence data
@c EN
Fills @var{buffer} with the ICMPv6 Echo Request packet.
@var{Data} must be a u8vector.  The checksum field is
left to be zero, which is to be filled by the kernel
(so you don't need to fill by yourself).
@c JP
@var{buffer}にICMPv6のエコーリクエストパケットを詰め込みます。
@var{Data}はu8vectorでなければなりません。チェックサムフィールドは
ゼロのままで、ここはカーネルが埋めることになっています。したがって、
ユーザーが自分で埋める必要はありません。
@c COMMON
@end defun

@defun icmp-packet-type buffer offset
@defunx icmp-packet-code buffer offset
@defunx icmp-packet-ident buffer offset
@defunx icmp-packet-sequence buffer offsetj
@c EN
Extracts type, code, ident and sequence fields of ICMP packet.
These functions are common to both ICMPv4/v6.
@c JP
それぞれICMPパケットのタイプ、コード、識別子、シーケンスフィールドを抜
き出します。これらの関数はICMPv4/v6で共通です。
@c COMMON
@end defun

@defun icmp4-describe-packet buffer offset
@defunx icmp6-describe-packet buffer offset
@c EN
Prints out a simple text description of the given ICMPv4 and v6 packet,
respectively.
@c JP
それぞれ与えられたICMPv4およびICMPv6パケットの簡単な説明を印字します。
@c COMMON
@end defun

@defun icmp4-message-type->string type
@defunx icmp4-unreach-code->string code
@defunx icmp4-redirect-code->string code
@defunx icmp4-router-code->string code
@defunx icmp4-exceeded-code->string code
@defunx icmp4-parameter-code->string code
@defunx icmp4-security-code->string code
@defunx icmp6-message-type->string type
@defunx icmp6-unreach-code->string code
@defunx icmp6-exceeded-code->string code
@defunx icmp6-parameter-code->string code
@c EN
Returns a text description of ICMPv4 and ICMPv6 types and codes.
@c JP
ICMPv4およびICMPv6のタイプとコードの説明テキストを返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node JSON parsing and construction, MD5 message digest, ICMP packets, Library modules - Utilities
@section @code{rfc.json} - JSON parsing and construction
@c NODE JSONのパーズと構築, @code{rfc.json} - JSONのパーズと構築

@deftp {Module} rfc.json
@mdindex rfc.json
@c EN
Procedures to parse JSON (RFC4627) data to S-expressions,
and convert S-expressions to JSON representation, are provided.
@c JP
RFC4627で規定される、JSON形式をパーズしてS式に直す手続きと、
S式をJSON形式に変換する手続きが提供されます。
@c COMMON
@end deftp

@deftp {Condition type} <json-parse-error>
@c EN
The parser @code{parse-json} and @code{parse-json-string} raise
this condition when they encounter
invalid JSON syntax.  It inherits @code{<error>}, and adds the following
slot.
@c JP
パーズ手続き@code{parse-json}と@code{parse-json-string}は、
無効なJSON構文に出会った時にこのコンディションを投げます。
@code{<error>}を継承し、次のスロットを追加で持ちます。
@c COMMON

@defivar {<json-parse-error>} position
@c EN
The input position, counted in characters, where the error occurred.
@c JP
エラーが起きた入力位置(文字数)。
@c COMMON
@end defivar
@end deftp

@defun parse-json :optional input-port
@c EN
Reads and parses the JSON representation from @var{input-port} (default is
the current input port), and returns the result in an S-expression.
May raise a @code{<json-parse-error>} condition when parse error occurs.
@c JP
JSON表記を@var{input-port} (省略された場合はcurrent-input-port)から
読み込みパーズして、結果をS式で返します。
パーズエラーが起きた場合は@code{<json-parse-error>}コンディションを投げます。
@c COMMON

@c EN
The following table shows how JSON datatypes are
mapped to Scheme objects.  (In future, we might add
some mechanism to customize the mapping.)
@c JP
下のテーブルに、JSONのデータ型がどのようにSchemeにマップされるかを示します。
(将来は、このマッピングをカスタマイズできるようにするかもしれません。)
@c COMMON

@table @asis
@c EN
@item @code{true}, @code{false}, @code{null}
Symbols @code{true}, @code{false} and @code{null}.
@item Arrays
Scheme vectors.
@item Objects
Scheme assoc-lists, in which keys are strings, and values
are Scheme objects.
@item Numbers
Scheme inexact real numbers.
@item Strings
Scheme strings.
@c JP
@item @code{true}, @code{false}, @code{null}
シンボル@code{true}, @code{false} and @code{null}。
@item 配列
Schemeのベクタ。
@item オブジェクト
Schemeの連想リスト。キーは文字列で、値はSchemeオブジェクト。
@item 数値
Schemeの不正確な実数。
@item 文字列
Schemeの文字列。
@c COMMON
@end table

@end defun

@defun parse-json-string str
@c EN
Parses the JSON string and resurns the result in an S-expression.
May raise a @code{<json-parse-error>} condition when parse error occurs.

See @code{parse-json} above for the mappings from JSON datatypes
to Scheme types.
@c JP
文字列@var{str}をJSONとしてパーズし、結果をS式で返します。
パーズエラーが起きた場合は@code{<json-parse-error>}コンディションを投げます。

JSONのデータ型とSchemeの型とのマッピングについては上の@code{parse-json}
を参照してください。
@c COMMON
@end defun

@deftp {Condition type} <json-construct-error>
@c EN
The converters @code{construct-json} and
@code{construct-json-string} raise this condition
when they cannot convert given Scheme object to JSON.
It inherits @code{<error>}, and adds the following slot.
@c JP
@code{construct-json}と@code{construct-json-string}は、
JSONに変換できないSchemeオブジェクトを見つけるとこのコンディションを投げます。
@code{<error>}を継承し、次のスロットを追加で持ちます。
@c COMMON

@defivar {<json-construct-error>} object
@c EN
The Scheme object that cannot convert to JSON representation.
@c JP
JSON表現に変換できなかったSchemeオブジェクト。
@c COMMON
@end defivar
@end deftp

@defun construct-json obj :optional output-port
@defunx construct-json-string obj
@c EN
Creates JSON representation of Scheme object @var{obj}.
@code{construct-json} writes out the result to @var{output-port},
whose default is the current output port.  @code{construct-json-string}
returns the result in a string.
Note that RFC4627 defines JSON text to be an object or an array;
so @var{obj} must be a Scheme object that can be mapped to
either a JSON object or a JSON array.

If @var{obj} contains a Scheme object that cannot be mapped
to JSON representation, a @code{<json-construct-error>} condition
is raised.
See the entry of @code{parse-json} above for the mapping between
JSON and Scheme.
@c JP
Schemeオブジェクト@var{obj}のJSON表現を作ります。
@code{construct-json}は結果を@var{output-port}に書き出します。デフォルトは
current-output-portです。@code{construct-json-string}は結果を文字列で返します。
RFC4627はJSONテキストはobjectかarrayであると定めているので、
@var{obj}はJSONオブジェクトかJSON配列へと変換できるSchemeオブジェクト
でなければなりません。

@var{obj}がJSONにマップできないオブジェクトを含んでいた場合は
@code{<json-consturct-error>}コンディションが投げられます。
JSONとScheme間のマッピングについては上の@code{parse-json}のエントリを
参照してください。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node MD5 message digest, MIME message handling, JSON parsing and construction, Library modules - Utilities
@section @code{rfc.md5} - MD5 message digest
@c NODE MD5メッセージダイジェスト, @code{rfc.md5} - MD5メッセージダイジェスト

@deftp {Module} rfc.md5
@mdindex rfc.md5
@c EN
This module implements MD5 message digest algorithm, defined in
RFC 1321 (@ref{rfc1321, [RFC1321], RFC1321}).
The module extends util.digest 
(@xref{Message digester framework}).
@c JP
このモジュールは、RFC 1321(@ref{rfc1321, [RFC1321], RFC1321}参照)で
定義されている、MD5メッセージダイジェストアルゴリズムを実装しています。
このモジュールは、util.digest (@ref{Message digester framework}参照)
を拡張しています。
@c COMMON
@end deftp

@deftp {Class} <md5>
@clindex md5
@c EN
The instance of this class keeps internal state of MD5 digest algorithm.

This class implements @code{util.digest} framework interface,
@code{digest-update!}, @code{digest-final!}, 
@code{digest}, and @code{digest-string}.
@xref{Message digester framework}, for detailed explanation
of these methods.
@c JP
このクラスのインスタンスは、MD5ダイジェストアルゴリズムの内部状態を
保持しています。

このクラスは、@code{util.digest}フレームワークのインターフェースである、
@code{digest-update!}、@code{digest-final!}、@code{digest}、
@code{digest-string}を実装しています。
これらのメソッドの詳細な説明は、@ref{Message digester framework}
を参照して下さい。
@c COMMON
@end deftp

@c EN
Besides the digester framework, this module provides to 
short-cut procedures.
@c JP
ダイジェスタフレームワークに加えて、このモジュールはショートカット手続きを
提供します。
@c COMMON

@defun md5-digest
@c EN
Reads data from the current input port until EOF, and returns
its digest in an incomplete string.
@c JP
現在の入力ポートからEOFまで読み込み、そのダイジェストを不完全文字列で
返します。
@c COMMON
@end defun

@defun md5-digest-string string
@c EN
Digest the data in @var{string}, and returns the result 
in an incomplete string.
@c JP
@var{string}にあるデータをダイジェストし、その結果を不完全文字列で
返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node MIME message handling, Quoted-printable encoding/decoding, MD5 message digest, Library modules - Utilities
@section @code{rfc.mime} - MIME message handling
@c NODE MIMEメッセージ処理, @code{rfc.mime} - MIMEメッセージ処理

@deftp {Module} rfc.mime
@mdindex rfc.mime
@c EN
This module provides utility procedures to handle
Multipurpose Internet Mail Extensions (MIME) messages,
defined in RFC2045 thorough RFC2049.
Provided APIs include procedures to parse or compose MIME-specific
header fields, and parse or compose MIME-encoded message bodies.
@c JP
RFC2045からRFC2049で定義されている、
多目的インターネットメール拡張(Multipurpose Internet Mail Extensions; MIME)
メッセージを扱う便利な手続きです。MIME特有のヘッダフィールドやメッセージボディを
パーズしたり作成したりするAPIが提供されます。
@c COMMON

@c EN
This module mainly focuses on providing low-level building-block procedures,
on top of which application-specific modules are to be built.
For example, @code{rfc.http} uses this module to compose
@code{multipart/form-data} message for the body of POST requests
(@xref{HTTP}).
@c JP
このモジュールは主としてビルディングブロックとなる低レベルの手続きに
フォーカスしており、アプリケーション特有のモジュールがこの上に
構築されることを意図しています。例えば@code{rfc.http}はPOSTリクエストの
ボディを@code{multipart/form-data}として構築する際にこのモジュールを
利用します(@ref{HTTP}参照)。
@c COMMON

@c EN
This module is supposed to be used with @code{rfc.822} module
(@xref{RFC822 message parsing}).
@c JP
このモジュールは、@code{rfc.822}モジュールと一緒に使うことを
想定しています(@ref{RFC822 message parsing}参照)。
@c COMMON
@end deftp

@subheading Utilities for header fields

@c EN
A few utility procedures to parse and generate MIME-specific header fields.
@c JP
MIME特有のヘッダフィールドをパーズしたり生成したりする便利な手続き。
@c COMMON

@defun mime-parse-version field
@c EN
If @var{field} is a valid header field for MIME-Version, returns
its major and minor versions in a list.  Otherwise, returns @code{#f}.
It is allowed to pass @code{#f} to @var{field}, so that 
you can directly pass the result of @code{rfc822-header-ref} to it.
Given parsed header list by @code{rfc822-read-headers}, you can
get mime version (currently, it should be @code{(1 0)}) by the
following code.
@c JP
@var{field}がそのMIMEバージョンのヘッダフィールドとして有効であれば、
そのメジャーバージョン番号とマイナーバージョン番号をリストにして
返します。そうでなければ、@code{#f}を返します。
@var{field}には@code{#f}を渡せるので、@code{rfc822-header-ref}の
戻り値を直接渡すこともできます。@code{rfc822-read-headers}により
返されるパーズ済みヘッダのリストを渡すことで、以下のように
MIMEのバージョンを得ることができます。(現在は、@code{(1 0)}です。)
@c COMMON
@example
(mime-parse-version (rfc822-header-ref headers "mime-version"))
@end example

@c EN
Note: simple regexp such as @code{#/\d+\.\d+/} doesn't do this job,
for @var{field} may contain comments between tokens.
@c JP
注意: @var{field}はトークンの間にコメントを含むかもしれないので、
@code{#/\d+\.\d+/}のような単純な正規表現では不十分です。
@c COMMON
@end defun

@defun mime-parse-content-type field
@c EN
Parses the "content-type" header field, and returns a list such as:
@c JP
``content-type''ヘッダフィールドをパーズし、次のようなリストを
返します。
@c COMMON
@example
(@i{type} @i{subtype} (@i{attribute} . @i{value}) @dots{})
@end example
@c EN
where @i{type} and @i{subtype} are MIME media type and
subtype in a string, respectively
@c JP
ここで、@i{type}と@i{subtype}はそれぞれ、MIMEメディアタイプと
サブタイプを文字列で表したものになります。
@c COMMON

@example
(mime-parse-content-type "text/html; charset=iso-2022-jp")
 @result{} ("text" "html" ("charset" . "iso-2022-jp"))
@end example

@c EN
If @var{field} is not a valid content-type field, @code{#f} is
returned.
@c JP
@var{field}が有効なcontent-typeフィールドでない場合は、
@code{#f}が返ります。
@c COMMON
@end defun

@defun mime-parse-content-disposition field
@c EN
Parses Content-disposition header field as specified in RFC2183.
@c JP
RFC2183に定められたContent-Dispositionヘッダフィールドをパーズします。
@c COMMON
(mime-parse-content-disposition "attachment; filename=genome.jpeg;\
  modification-date=\"Wed, 12 Feb 1997 16:29:51 -0500\";")
 @result{} ("attachment"
      ("filename" . "genome.jpeg")
      ("modification-date" . "Wed, 12 Feb 1997 16:29:51 -0500"))
@end defun


@defun mime-parse-parameters :optional iport
@defunx mime-compose-parameters params :optional oport &key start-column
@c EN
These are low-level utility procedures to parse and compose @emph{parameter}
part of header fields (as appeared in RFC2045 Section 5.1 etc).

@code{Mime-parse-parameters} reads the parameter
part of the header body from an input port @var{iport}, and
returns an assoc list of the parameter names and values.
Conversely, @code{mime-compose-parameters} takes an assoc
list of names and values, compose parameter part and
emit it to @var{oport}.   When omitted, the current input
port and the current output port are used for @var{iport}
and @var{oport}, respectively.  You can pass @code{#f} to
@var{oport} and @code{mime-compose-parameters} returns the
result in a string instead of emitting it to a port.
@c JP
これらは、(RFC2045の5.1節にあるような)ヘッダフィールドの値の@emph{parameter}
部分をパーズしたり作成したりするための低レベルのユーティリティ手続きです。

@code{mime-parse-parameters}はヘッダフィールドの値のパラメータ部分を
入力ポート@var{iport}から読んでパーズし、パラメータの名前と値の
連想リストを返します。
@code{mime-compose-parameters}はその逆で、連想リストをとり、
パラメータ部分を構成して@var{oport}へと書き出します。
@var{iport}、@var{oport}はそれぞれ省略された場合、
@code{current-input-port}と@code{current-output-port}を
デフォルトとします。また、@var{oport}に@code{#f}を渡すと
@code{mime-compose-parameters}は結果をポートに書き出すかわりに
文字列として返します。
@c COMMON

@example
(call-with-input-string 
   "; name=foo; filename=\"foo/bar/baz\""
   mime-parse-parameters)
 @result{} (("name" . "foo") ("filename" . "foo/bar/baz"))

(mime-compose-parameters
 '(("name" . "foo") ("filename" . "foo/bar/baz"))
 #f)
 @result{} "; name=foo; filename=\"foo/bar/baz\""
@end example

@c EN
@code{Mime-compose-parameters} tries to insert folding line breaks
between parameters to avoid the header line becomes too long.
You can pass the beginning column position of the parameter
part via @var{start-column} argument.
@c JP
@var{mime-compose-parameters}はヘッダ行が長くなりすぎる場合に
パラメータ間に折り返し改行を入れようとします。パラメータ部分が始まる
カラム数は@var{start-column}で与えることができます。
@c COMMON

@c EN
We plan to make these procedures handle RFC2231's parameter value
extension transparentlyk in future.
@c JP
将来は、これらの手続きにRFC2231のパラメータ値拡張を透過的に処理させる予定です。
@c COMMON
@end defun


@defun mime-decode-word word
@c EN
Decodes RFC2047-encoded word.  If @var{word} isn't an encoded word,
it is returned as is.

Note that this procedure decodes only if the entire @var{word} is
an ``encoded word'' defined in RFC2047.  If you are dealing with
a field that may contain multiple encoded word and/or unencoded parts,
use @code{mime-decode-text} below.
@c JP
RFC2047でエンコードされた@var{word}をデコードします。
@var{word}がRFC2047でエンコードされたものでない場合は、そのまま
返されます。

この手続きは@var{word}全体がRFC2047の規定する``encoded-word''である場合にのみ
デコードを行うことに注意してください。複数のエンコードされた部分や
エンコードされていない部分が混ざっているフィールドを扱う場合は、
下に示す@code{mime-decode-text}を使います。
@c COMMON

@example
(mime-decode-word "=?iso-8859-1?q?this=20is=20some=20text?=")
 @result{} "this is some text"
@end example

@end defun
@defun mime-decode-text text
@c EN
Returns a string in which 
all encoded words contained within @var{text} are decoded.
This procedure can deal with a header field body that may contain
mixture of non-encoded and encoded parts, and/or multiple encoded
parts.  One of such header field is the Subject field of email.

@example
(mime-decode-text "This is =?US-ASCII?q?some=20text?=")
 @result{} "This is some text"
@end example
@c JP
@var{text}中に含まれるすべてのencoded wordをデコードした文字列を返します。
この手続きは、エンコードされていない部分とエンコードされている部分が混ざっていたり、
複数のエンコードされている部分を持つヘッダフィールドボディを処理することが
できます。そのようなフィールドの例はemailのSubjectフィールドです。

@example
(mime-decode-text "Yamada Taro (=?utf-8?B?5bGx55SwIOWkqumDjg==?=)")
 @result{} "Yamada Taro (山田 太郎)"
@end example
@c COMMON

@c EN
Care should be taken if you apply this procedure to a ``structured''
header field body (see RFC2822 section 2.2.2).  
The proper way of parsing a structured header field body is
to tokenize it first, then to decode each word using @code{mime-decode-word}.
since the decoded text may contain characters that affects the tokenization.
(However, if you can just show the header field in human readable way
for informational purposes, you may just use @code{mime-decode-text}
on entire header field for the convenience).
@c JP
この手続きを「構造化された」ヘッダフィールドボディ (RFC2822 2.2.2節参照)
に適用する際には注意が必要です。
構造化されたヘッダフィールドボディをパーズする正式な方法は、
最初にトークンに分割して、それから各wordを
@code{mime-decode-word}を使ってデコードするというものです。
なぜならデコード後のテキスト中に、パージングに影響を与える文字が含まれている
かもしれないからです。
(ただし、単に参考情報を人間にわかりやすいように表示するだけの目的の場合は、
簡便のためにヘッダフィールド全体をこの手続きで一度にデコードしてしまっても
良いでしょう)。
@c COMMON
@end defun

@defun mime-encode-word word :key charset transfer-encoding
@c EN
Encodes @var{word} in the RFC2047 format.  The keyword
argument @var{charset} specifies the character encoding scheme
in string or symbol.
whose default is @code{utf-8}.  If @var{charset} differs from
Gauche's internal encoding and @var{word} is a complete string,
the procedure convers the character encoding to @var{charset},
then performs transfer encoding.
@c JP
@var{word}をRFC2047フォーマットにエンコードします。キーワード引数
@var{charset}は文字列かシンボルで文字エンコーディングスキームを指定します。
デフォルトは@code{utf-8}です。@var{charset}の指定がGaucheの
内部文字エンコーディングと異なっており、@var{word}が完全な文字列である場合は、
まず@var{word}が@var{charset}のエンコーディングへと変換され、
その上でトランスファーエンコーディングがかけられます。
@c COMMON

@example
(mime-encode-word "this is some text")
 @result{} "=?utf-8?B?dGhpcyBpcyBzb21lIHRleHQ=?="
@end example

@c EN
The keyword argument @var{transfer-encoding} specifies how
the octets are encoded to transfer-safe characters.  You can
give a symbol @code{b}, @code{B} or @code{base64} for Base64,
and @code{Q}, @code{q}, @code{quoted-printable} for Quoted-printable
transfer encodings.  An error is raised if you pass values other
than those.  The default is Base64 encoding.
@c JP
キーワード引数@var{transfer-encoding}は各オクテットを伝達上安全な
文字列へどエンコードする方法を指定します。サポートされている値は、
Base64を指定するシンボル@code{b}、@code{B}、@code{base64}、
およびQuoted printableを指定する
@code{Q}、@code{q}、@code{quoted-printable}です。
これ以外の値を渡した場合はエラーが通知されます。デフォルトはBase64です。
@c COMMON

@c EN
This procedure does not consider the length of the resulting
encoded word, which RFC2047 recommends to be less than 75 octets.
Use @code{mime-encode-text} below to conform the line length limit.
@c JP
この手続きは結果のencoded wordの長さを気にしませんが、
RFC2047によればencoded wordは75オクテットまでに収めることが
要請されています。この要請に対応するには下に示す
@code{mime-encode-text}を使って下さい。
@c COMMON

@c EN
(Note: In most Gauche procedures, a keyword argument @code{encoding}
is used to specify character encodings.  In this context we have
two encodings, however, and to avoid the confusion we chose to use
the terms ``charset'' and ``transfer-encoding'' that appear in
RFC documents.)
@c JP
(註：ほとんどのGaucheの手続きでは、キーワード引数@code{encoding}により
文字エンコーディングを指定します。しかしこの手続きの文脈では
2つの「エンコーディング」が存在しているので、混乱を避けるために
RFC文書で使われている``charset''および``transfer-encoding''の用語を
使うこととしました。)
@c COMMON
@end defun

@defun mime-encode-text text :key charset transfer-encoding line-width start-column force
@c EN
Encode @var{text} in RFC2047 format if necessary, and considering
line foling if the result gets too long.

The keyword arguments @var{charset} and @var{transfer-encoding} are the same
as @code{mime-encode-word}.
@c JP
@var{text}を、必要ならばRFC2047フォーマットに従いエンコードします。
また、結果が長すぎる場合の行の折り返しも考慮します。

キーワード引数@var{charset}と@var{transfer-encoding}の意味は
@code{mime-encode-word}と同じです。
@c COMMON

@c EN
If the @var{text} only consists of printable ASCII characters,
no encoding is done, and only line folding is considered.
However, if a true value is given to the @var{force} argument,
even ASCII-only @var{text} is encoded.
@c JP
もし@var{word}が印字可能なASCII文字のみで構成されていた場合は
エンコーディングは行われず、行の折り返しのみが処理されます。
但し、@var{force}引数に真の値が与えられた場合はASCIIのみの@var{text}も
エンコードされます。
@c COMMON

@c EN
The @var{line-width} specifies the maximum line width of the result.
Its default is 76.
If the encoded word gets too long, it is splitted to multiple encoded
words and CR LF SPC sequence (``folding white space'' defined in RFC2822)
are inserted inbetween.
You can suppress this behavior by passing @code{#f} or @code{0} to
@var{line-width}.
Since encoded word needs some overhead characters, it doesn't make much sense
to specify small value to @code{line-width}.  Current implementation
rejects @code{line-width} smaller than 30.
@c JP
@var{line-width}は結果に現れる行の最大値を指定します。デフォルトは76です。
encoded wordがこれを越える場合は、複数のencoded wordへと結果は分割され、
間にCR LF SPCシーケンス(RFC2822で定義される``folding white space'')が挿入されます。
@var{line-width}に@code{#f}か@code{0}を渡すことで
行の折り返しを抑制することができます。
encoded wordには文字数でいくらかのオーバヘッドがあるため、
あまり小さい@code{line-width}には意味がありません。現在の実装では
30以下の値は拒否されます。
@c COMMON

@c EN
The @var{start-column} keyword argument can be used to 
shorten the first of folded
lines to make room for header field name.  For example, if
you want to encode the body of a Subject header field,
you can pass the value of @code{(string-length "Subject: ")} so that
the encoded result can directly concatenated after the header
field name.  The default value is 0.
@c JP
@var{start-column}キーワード引数は、ヘッダフィールド名を入れるために
エンコード結果の最初の行だけを短くするのに使えます。
例えばSubjectヘッダフィールドのボディをエンコードする際に、
@code{(string-length "Subject: ")}の値を渡してやれば、
結果を直接"Subject: "の後に連結することができるわけです。
デフォルトの値は0です。
@c COMMON

@c EN
This procedure is not designed to encode parts of structured
header fields, which have further restrictions such as which parts
can be encoded and where the folding white spaces can be inserted.
The robust way is to encode some parts first, then construct
a structured header fields, considering line folding.
@c JP
この手続きはstructured header fieldをエンコードするようには設計
されていません。structured header fieldには、どの部分がエンコード
可能でどの部分にfolding white spaceが挿入可能かについてさらなる
制約があるためです。安全な方法は、まず必要な部分をエンコードし、
それから折り返しを考慮しつつstructured header fieldを組み立てることです。
@c COMMON
@end defun

@subheading Streaming parser

@c EN
The streaming parser is designed so that you can decide how
to do with the message body before the entire message is read.
@c JP
メッセージ全体が読み込まれる前にメッセージボディをどのように
扱うかをコントロールできるように、ストリームパーザが用意されて
います。
@c COMMON

@defun mime-parse-message port headers handler
@c EN
The fundamental streaming parser.  @var{Port} is an input port
from where the message is read.  @var{Headers} is a list of headers
parsed by @code{rfc822-read-headers}; that is, this procedure
is supposed to be called after the header part of the message
is parsed from @var{port}:
@c JP
基本的なストリームパーザです。@var{port}は、メッセージを読み込む
入力ポートです。@var{headers}は@code{rfc822-read-headers}により
パーズされたヘッダのリストです。つまり、この手続きは、
@var{port}から読み込まれたメッセージのヘッダ部分がパーズされた
後に使われることを想定しています。
@c COMMON
@example
(let* ((headers (rfc822-read-headers port)))
  (if (mime-parse-version (rfc822-header-ref headers "mime-version"))
     ;; parse MIME message
     (mime-parse-message port headers handler)
     ;; retrieve a non-MIME body
     ...))
@end example

@c EN
@code{Mime-parse-message} analyzes @var{headers}, and calls
@var{handler} on each message body with two arguments:
@c JP
@code{mime-parse-message}は@var{headers}を解析し、
メッセージボディのそれぞれについて、2引数をもって
@var{handler}を呼び出します。
@c COMMON

@example
(handler @var{part-info} @var{xport})
@end example

@c EN
@var{Part-Info} is a @code{<mime-part>} structure described below
that encapsulates the information of this part of the message.
@c JP
@var{part-info}は、以下で説明するような、メッセージのこのパートの
情報をカプセル化した@code{<mime-part>}ストラクチャです。

@c EN
@var{Xport} is an input port, initially points to the beginning
of the body of message.  The handler can read from the port
as if it is reading from the original @var{port}.  However,
@var{xport} recognizes MIME boundary internally, and returns EOF
when it reaches the end of the part.
(Do not read from the original @var{port} directly, or it will mess up
the internal state of @var{vport}).
@c JP
@var{xport}は入力ポートで、最初はメッセージボディの先頭を指しています。
ハンドラはこのポートからメッセージボディを読み込むことが出来ます。
@var{xport}はMIMEバウンダリを認識し、パートの最後に到達したら
EOFを返します。
(元の@var{port}から直接読み込まないようにして下さい。
そうしてしまうと、@var{vport}の内部状態がおかしくなります)。
@c COMMON

@c EN
@var{Handler} can read the part into the memory, or
save it to the disk, or even discard the part.
Whatever it does, it has to read from @var{vport} until it
returns EOF.

The return value of @var{handler} will be set in
the @code{content} slot of @var{part-info}.
@c JP
@var{handler}は、パートをメモリに読み込んだり、ディスクに保存したり、
あるいはそのパートを無視したりできます。ただ、何をするにせよ、
@var{vport}がEOFを返すまでデータを読まなければなりません。

@var{handler}の戻り値は、@var{part-info}の@code{content}スロットに
セットされます。

@c EN
If the message has nested multipart messages, @var{handler} is
called for each "leaf" part, in depth-first order.  @var{Handler}
can know its nesting level by examining @var{part-info} structure.
@c JP
メッセージが、ネストしたマルチパートメッセージを含んでいる場合は、
@var{handler}は深さ優先でそれぞれの``葉''のパートに対して呼ばれます。
@var{handler}は、@var{part-info}ストラクチャを調べることで、
そのネストのレベルを知ることができます。

@c EN
The message doesn't need to be a multipart type; if it is a
MIME @code{message} type, @var{handler} is called on the body
of enclosed message.  If it is other media types such as @code{text}
or @code{application}, @var{handler} is called on the (only) message body.
@c JP
メッセージはマルチパートである必要はありません。メッセージが
MIME @code{mesasge}タイプである場合は、@var{handler}は囲まれたメッセージの
ボディに対して呼ばれます。メッセージが、@code{text}や@code{application}
などの他のメディアタイプの場合は、@var{handler}は単にメッセージボディに
対して呼ばれます。
@c COMMON
@end defun

@deftp {Class} <mime-part>
@clindex mime-message
@c EN
A structure that encloses metainformation about a MIME part.
It is constructed when the header of the part is read, and
passed to the handler that reads the body of the part.

It has the following slots:
@c JP
MIMEパートのメタ情報を含むストラクチャです。
これは、そのパートのヘッダが読み込まれた時点で構築され、
そのパートのボディを読み込むハンドラに渡されます。

以下のスロットを持ちます。
@c COMMON

@defivar {<mime-part>} type
@c EN
MIME media type string.  If @code{content-type} header is omitted
to the part, an appropriate default value is set.
@c JP
MIMEメディアタイプの文字列。そのパートの@code{content-type}ヘッダが
省略された場合は、適切なデフォルト値がセットされます。
@c COMMON
@end defivar

@defivar {<mime-part>} subtype
@c EN
MIME media subtype string.  If @code{content-type} header is omitted
to the part, an appropriate default value is set.
@c JP
MIMEメディアのサブタイプの文字列。そのパートの@code{content-type}
ヘッダが省略された場合は、適切なデフォルト値がセットされます。
@c COMMON
@end defivar

@defivar {<mime-part>} parameters
@c EN
Associative list of parameters given to @code{content-type} header field.
@c JP
@code{content-type}ヘッダフィールドに渡されるパラメータの連想リスト。
@c COMMON
@end defivar

@defivar {<mime-part>} transfer-encoding
@c EN
The value of @code{content-transfer-encoding} header field.
If the header field is omitted, an appropriate default value is set.
@c JP
@code{content-transfer-encoding}ヘッダフィールドの値。
このヘッダフィールドが省略された場合は、適切なデフォルト値が
セットされます。
@c COMMON
@end defivar

@defivar {<mime-part>} headers
@c EN
The list of header fields, as parsed by @code{rfc822-read-headers}.
@c JP
@code{rfc822-read-headers}によりパーズされた、ヘッダフィールドのリスト。
@c COMMON
@end defivar

@defivar {<mime-part>} parent
@c EN
If this is a part of multipart message or encapsulated message,
points to the enclosing part's @code{<mime-part>} structure.
Otherwise @code{#f}.
@c JP
それがマルチパートメッセージあるいはカプセル化されたメッセージの
パートである場合は、それを含んでいるパートの@code{<mime-part>}
ストラクチャを指します。そうでなければ@code{#f}を返します。
@c COMMON
@end defivar

@defivar {<mime-part>} index
@c EN
Sequence number of this part within the same parent.
@c JP
同じ親を持つパートの中でのそのパートのシーケンス番号。
@c COMMON
@end defivar

@defivar {<mime-part>} content
@c EN
If this part is multipart/* or message/* media type,
this slot contains a list of parts within it.
Otherwise, the return value of @var{handler} is stored.
@c JP
そのパートのメディアタイプがmultipart/*あるいはmessage/*で
ある場合は、このスロットにはそれに含まれるパートのリストが
入っています。そうでなければ、@var{handler}の戻り値が
格納されています。
@c COMMON
@end defivar

@defivar {<mime-part>} source
@c EN
This slot is only used when composing a MIME message.
The caller can set this slot a name of the file to be inserted
into this part, instead of setting the entire content of the
file to the @code{content} slot.   See 
@code{mime-compose-message} below for the more details.
@c JP
このスロットはMIMEメッセージを作成する時のみ使われます。
呼び出し元は、このスロットにファイル名をセットすることで、
MIMEメッセージのこのパートにファイルの内容を挿入することができます。
詳しくは下の@code{mime-compose-message}の項を参照してください。
@c COMMON
@end defivar
@end deftp

@defun mime-retrieve-body part-info xport outp
@c EN
A procedure to retrieve message body.  It is intended to
to be a building block of @var{handler} to be passed to
@code{mime-parse-message}.

@var{Part-info} is a @code{<mime-part>} object.
@var{Xport} is an input port passed to the handler,
from which the MIME part can be read.
@c JP
メッセージボディを取得するための手続きです。
@code{mime-parse-message}へ渡される、@var{handler}の
ビルディングブロックとなることを意図しています。

@var{part-info}は、@code{<mime-part>}のオブジェクトです。
@var{xport}はハンドラに渡された入力ポートで、
そこからMIMEパートが読みこまれるものです。

@c EN
This procedure read from @var{xport}
until it returns EOF.  It also looks at the
@code{transfer-encoding} of @var{part-info}, and decodes
the body accordingly; that is, base64 encoding and
quoted-printable encoding is handled.  The result is
written out to an output port @var{outp}.

This procedure does not handle charset conversion.
The caller must use CES conversion port as @var{outp}
(@xref{Character code conversion}) if desired.
@c JP
この手続きは、@var{xport}からEOFに達するまで読み込み、
@var{part-info}の@code{transfer-encoding}も見て、
ボディを適切にデコードします。つまり、base64やquoted-printable
のエンコーディングは適切に処理されます。結果が出力ポート@var{outp}へと
出力されます。

この手続きは文字セットの変換は扱いません。
必要であれば、呼び出し側が@var{outp}としてCES変換ポートを
使う必要があります(@ref{Character code conversion}参照)。

@c COMMON
@end defun

@c EN
A couple of convenience procedures are defined for typical
cases on top of @code{mime-retrieve-body}.
@c JP
典型的なケースのために、いくつかの便利な手続きが@code{mime-retrieve-body}
の上に定義されています。
@c COMMON

@defun mime-body->string part-info xport
@defunx mime-body->file part-info xport filename
@c EN
Reads in the body of mime message, decoding transfer encoding,
and returns it as a string or writes it to a file, respectively.
@c JP
MIMEメッセージのボディを読み込み、転送(transfer)エンコーディングを
デコードし、それぞれ文字列として返すか、ファイルへ書き出します。
@c COMMON
@end defun

@c EN
The simplest form of MIME message parser would be like this:
@c JP
MIMEメッセージパーザの最もシンプルな使い方は次のように
なります。
@c COMMON

@example
(let ((headers (rfc822-read-headers port)))
  (mime-parse-message port headers
                      (cut mime-body->string <> <>)))
@end example

@c EN
This reads all the message on memory (i.e. the "leaf" @code{<mime-part>}
objects' @code{content} field would hold the part's body as a string),
and returns the top @code{<mime-part>} object.  Content transfer encoding
is recognized and handled, but character set conversion isn't done.

You may want to feed the message body to a file directly,
or even want to skip some body according to mime media types and/or
other header information.  Then you can put the logic in the handler
closure.  That's the reason that this module provides building
blocks, instead of all-in-one procedure.
@c JP
これは、メッセージの全てをメモリに読み込み、
一番上層の@code{<mime-part>}オブジェクトを返します。
(``葉''である@code{<mime-part>}オブジェクトの@code{content}フィールドは、
そのパートのボディを文字列として保持しています。)
内容の転送エンコーディング(content transfer encoding)は認識され処理
されますが、文字セットの変換は行われません。

メッセージボディを直接ファイルに書き出したり、MIMEメディアタイプや
他のヘッダ情報に基づいていくつかのボディをスキップしたいかもしれません。
その場合は、ロジックをハンドラのクロージャに入れることができます。
それが、このモジュールが、オールインワンの手続きではなく、
ビルディングブロックを提供している理由です。
@c COMMON

@subheading Message composer

@defun mime-compose-message parts :optional port &key boundary
@defunx mime-compose-message-string parts &key boundary
Composes a MIME multipart message.  @code{Mime-compose-message}
emits the result to an output port @var{port}, whose default
is the current output port.  @code{Mime-compose-message-string}
makes the result into a string.   You can give a boundary string
via @var{boundary} argument; when omitted, a fresh boundary string
is automatically generated by @code{mime-make-boundary} below.

@code{Mime-compose-message} returns the boundary string.
@code{Mime-compose-message-string} returns two values, the result
string and the boundary string.

The content of the message is provided by the @var{parts} argument,
which can be a list of instances of @code{<mime-part>} (see above)
or lists that describe parts.  The list form is supported for
the caller's convenience, and internally it is converted to
a list of @code{<mime-part>}s.

The syntax of each part element in @var{parts} are defined as follow.

@example
<part>           : <mime-part> | <mime-part-desc>

<mime-part>      : @r{an instance of the class} <mime-part>

<mime-part-desc> : (<content-type> (<header> ...) <body>)
<content-type>   : (<type> <subtype> <header-param> ...)
<header-param>   : (<key> . <value>) ...
<header>         : (<header-name> <encoded-header-value>)
                 | (<header-name> (<header-value> <header-param> ...))
<body>           : @r{a string}
                 | (file <filename>)
                 | (subparts <part> ...)
@end example

Note: In the first form of @code{<header>},
@code{<encoded-header-value>} must already be encoded using RFC2047
or RFC2231 if the original value contains non-ascii characters.
In the second form, we plan to do RFC2231 encoding on behalf of
the caller; but the current version does not implement it.  The
caller should not pass encoded words in this form, since it may
result double-encoding when we implement the auto encoding feature;
for the time being, the second form restricts ASCII-only values.

If @code{<body>} is a string, it is used as the part's content.
If @code{<body>} is @code{(file @var{filename})}, the content is
read from the named file.   If @code{<body>} is 
@code{(subparts @var{part} @dots{})}, the part becomes nested
MIME part.

It is the caller's responsibility to give the proper content.
For example, if @code{<body>} is in the third form, the
part must have @code{multipart} content type.

The caller needs to provide proper @code{content-transfer-encoding}
header, depending on the application.  If none is given, the content
is inserted into the message as is, which may be appropriate for
some applications, but if you want to use the result in email 
message you certainly want to encode binary part with base64,
for example.
@end defun

@defun mime-make-boundary
@c EN
Returns a unique string that can be used as a boundary of a MIME multipart
message.
@c JP
MIMEマルチパートメッセージのboundaryとして使えるユニークな文字列を返します。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Quoted-printable encoding/decoding, SHA message digest, MIME message handling, Library modules - Utilities
@section @code{rfc.quoted-printable} - Quoted-printable encoding/decoding
@c NODE Quoted-printableエンコーディング, @code{rfc.quoted-printable} - Quoted-printableエンコーディング

@deftp {Module} rfc.quoted-printable
@mdindex rfc.quoted-printable
@c EN
This module defines a few functions to encode/decode Quoted-printable format,
defined in RFC 2045 (@ref{rfc2045, [RFC2045], RFC2045}), section 6.7.
@c JP
このモジュールでは、RFC 2045 (@ref{rfc2045, [RFC2045], RFC2045}参照)の
セクション6.7で定義されている、Quoted-printableフォーマットにエンコード/から
デコードするためのいくつかの関数を定義しています。
@c COMMON
@end deftp

@defun quoted-printable-encode :key line-width binary
@c EN
Reads byte stream from the current input port, encodes it in Quoted-printable
format and writes the result character stream to the current output port.
The conversion ends when it reads EOF from the current input port.
@c JP
現在の入力ポートからバイトストリームを読み込み、それをQuoted-printable
フォーマットにエンコードし、現在の出力ポートへ結果の文字ストリームを
書き出します。この変換は、現在の入力ポートからEOFを読み出すと終了します。
@c COMMON
@c EN
The keyword argument @var{line-width} specifies the maximum 
line width of the generated output in characters.  If the encoded
output creates a long line, the procedure inserts a ``soft line break''
so that the each line is equal to or shorter than this number.
Soft line breaks are removed when quoted-printable text is
decoded.
The default line width is 76.  (The minimum meaningful number of
line-width is 4).  You can suppress soft line breaks by
giving @code{#f} or @code{0} to @var{line-width}.
@c JP
キーワード引数@var{line-width}は、出力に現れる行の最大長を指定します。
エンコードされた行の長さがこの値を越えそうな場合は、「ソフトラインブレーク」が
適宜挿入され、各行の長さがこの値を越えないように調整されます。
ソフトラインブレークはquoted-printableフォーマットのデコード時に
取り除かれます。
@var{line-width}のデフォルト値は76です。(最小の意味のある値は4です。)
@var{line-width}に@code{#f}または@code{0}を渡せば、
ソフトラインブレークは挿入されません。
@c COMMON
@c EN
By default, @code{quoted-printable-encode} generates @code{CR-LF} sequence
for each line break in the input (``hard line break'').
When a true value is given to the keyword argument @var{binary},
however, octets @code{#x0a} and @code{#x0d} in the input are encoded
as @code{=0A} and @code{=0D}, respectively.  See RFC2045 section 6.7
for the details.
@c JP
デフォルトでは、@code{quoted-printable-encode}は入力中の改行に対して
@code{CR-LF}シーケンスを出力します(「ハードラインブレーク」)。
しかし、@var{binary}キーワード引数に真の値が与えられた場合、
入力中のオクテット@code{#x0a}および@code{#x0d}はそれぞれ
@code{=0A}、@code{=0D}のようにエンコードされます。
詳しくはRFC2045の6.7節を参照してください。
@c COMMON
@end defun

@defun quoted-printable-encode-string string :key line-width binary
@c EN
Converts contents of @var{string} to Quoted-printable encoded format.
Input string can be either complete or incomplete string;
it is always interpreted as a byte sequence.

The keyword arguments are the same as @code{quoted-printable-encode}.
@c JP
@var{string}の内容をQuoted-printableエンコードされたフォーマットに
変換します。入力の文字列は、完全文字列でも不完全文字列でも構いません。
常にバイトシーケンスとして処理されます。

キーワード引数は@code{quoted-printable-encode}と同じです。
@c COMMON
@end defun

@defun quoted-printable-decode
@c EN
Reads character stream from the current input port,
decodes it from Quoted-printable
format and writes the result byte stream to the current output port.
The conversion ends when it reads EOF.
If it encounters illegal character sequence (such as '=' followed 
by non-hexadecimal characters), it copies them literally to the output.
@c JP
現在の入力ポートから文字ストリームを読み込み、それをQuoted-printable
フォーマットからデコードし、結果のバイトストリームを現在の出力ポートへ
書き出します。
この変換は、EOFを読み出すと終了します。
不正なシーケンス('='の後に16進文字が続かない、など)に出会うと、それらを
リテラルのまま出力へコピーします。
@c COMMON
@end defun

@defun quoted-printable-decode-string string
@c EN
Decodes a Quoted-printable encoded string @var{string} and returns
the result as a string.
@c JP
Quoted-printableエンコードされた文字列@var{string}をデコードし、
その結果を文字列で返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SHA message digest, URI parsing and construction, Quoted-printable encoding/decoding, Library modules - Utilities
@section @code{rfc.sha} - SHA message digest
@c NODE SHAメッセージダイジェスト, @code{rfc.sha} - SHAメッセージダイジェスト

@deftp {Module} rfc.sha
@mdindex rfc.sha
@c EN
This module implements US Secure Hash Algorithm 
defined in RFC 4634.  It provides SHA-1, SHA-224, SHA-256, 
SHA-384 and SHA-512 (the latter four are sometimes referred
as SHA-2 collectively).

The module extends util.digest 
(@xref{Message digester framework}).
@c JP
このモジュールは、RFC 4634で定義されている
US Secure Hash Algorithmを実装しています。
提供されるアルゴリズムはSHA-1, SHA-224, SHA-256, SHA-384および
SHA-512です (後の4つを総称してSHA-2と呼ぶこともあります)。

このモジュールは、util.digest (@ref{Message digester framework}参照)
を拡張しています。
@c COMMON
@end deftp

@deftp {Module} rfc.sha1
@mdindex rfc.sha1
@c EN
This is the old module that provided only SHA-1.  It is kept as
an alias of @code{rfc.sha} for the backward compatibility.  New code
should use @code{rfc.sha}.
@c JP
これはSHA-1だけを提供していた古いモジュールです。互換性のため、
この名前は@code{rfc.sha}の別名として残されています。
新たに書くコードは@code{rfc.sha}を使ってください。
@c COMMON
@end deftp


@deftp {Class} <sha1>
@deftpx {Class} <sha224>
@deftpx {Class} <sha256>
@deftpx {Class} <sha384>
@deftpx {Class} <sha512>
@clindex sha1
@clindex sha224
@clindex sha256
@clindex sha384
@clindex sha512
@c EN
An instance of these class keeps internal state of SHA digest algorithm.

This class implements @code{util.digest} framework interface,
@code{digest-update!}, @code{digest-final!}, 
@code{digest}, and @code{digest-string}.
@xref{Message digester framework}, for detailed explanation
of these methods.
@c JP
これらのクラスのインスタンスは、SHAダイジェストアルゴリズムの内部状態を
保持しています。

このクラスは、@code{util.digest}フレームワークのインターフェース、
@code{digest-update!}、@code{digest-final!}、@code{digest}、
@code{digest-string}を実装しています。
これらのメソッドの詳細な説明は、@ref{Message digester framework}を
参照して下さい。
@c COMMON
@end deftp

@c EN
Besides the digester framework, this module provides to 
short-cut procedures.
@c JP
ダイジェスタフレームワークに加えて、このモジュールはショートカット
手続きを提供します。
@c COMMON

@defun sha1-digest
@defunx sha224-digest
@defunx sha256-digest
@defunx sha384-digest
@defunx sha512-digest
@c EN
Reads data from the current input port until EOF, and returns
its digest in an incomplete string.
@c JP
現在の入力ポートからデータをEOFまで読み込み、そのダイジェストを
不完全文字列で返します。
@c COMMON
@end defun

@defun sha1-digest-string string
@defunx sha224-digest-string string
@defunx sha256-digest-string string
@defunx sha384-digest-string string
@defunx sha512-digest-string string
@c EN
Digest the data in @var{string}, and returns the result 
in an incomplete string.
@c JP
@var{string}のデータをダイジェストし、その結果を不完全文字列で
返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node URI parsing and construction, Zlib compression library, SHA message digest, Library modules - Utilities
@section @code{rfc.uri} - URI parsing and construction
@c NODE URIの解析と作成, @code{rfc.uri} - URIの解析と作成

@deftp {Module} rfc.uri
@mdindex rfc.uri
@c EN
Provides a set of functions to parse Uniform Resource Identifiers
defined in RFC 2396 (@ref{rfc2396, [RFC2396], RFC2396}).
@c JP
RFC 2396 (@ref{rfc2396, [RFC2396], RFC2396})で定義されている
Uniform Resource Identifiers をパーズする関数を提供します。
@c COMMON
@end deftp

@defun uri-parse uri
@defunx uri-scheme&specific uri
@defunx uri-decompose-hierarchical specific
@defunx uri-decompose-authority authority
@c EN
General parser of URI.  These functions does not decode
URI encoding, since the parts to be decoded differ among
the uri schemes.   After parsing uri, use @code{uri-decode} below
to decode them.
@c JP
URIの一般的なパーザです。これらの関数はURIエンコーディングを
デコードしません。URIスキームによってどの部分をデコードすべきかが
異なるからです。パージングを行った後に、後述の@code{uri-decode}等を
使ってデコードを行ってください。
@c COMMON

@c EN
@code{uri-parse} is the most handy procedure.  It breaks the uri
into the following parts and returns them as multiple values.
If the uri doesn't have the corresponding
parts, @code{#f} are returned for the parts.

@itemize @bullet
@item
URI scheme as a string
(e.g. @code{"mailto"} in @code{"mailto:foo@@example.com"}).
@item
User-info in the authority part (e.g. @code{"anonymous"}
in @code{ftp://anonymous@@ftp.example.com/pub/foo}).
@item
Hostname in the authority part (e.g. @code{"ftp.example.com"}
in @code{ftp://anonymous@@ftp.example.com/pub/foo}).
@item
Port number in the authority part, as an integer (e.g. @code{8080}
in @code{http://www.example.com:8080/}).
@item
Path part (e.g. @code{"/index.html"} in
@code{http://www.example.com/index.html}).
@item
Query part (e.g. @code{"key=xyz&lang=en"} in
@code{http://www.example.com/search?key=xyz&lang=en}).
@item
Fragment part (e.g. @code{"section4"} in
@code{http://www.example.com/document.html#section4}).
@end itemize
@c JP
@code{uri-parse}は最も手軽な手続きで、uriを以下に示す部分に
分割し、多値で返します。
もし該当する部分がuriに無かった場合は、その部分には@code{#f}が返ります。
@itemize @bullet
@item
URIスキームを文字列で。
(例： @code{"mailto:foo@@example.com"}の@code{"mailto"})。
@item
authorityパートのuser-infoを文字列で。
(例： @code{ftp://anonymous@@ftp.example.com/pub/foo}の@code{"anonymous"})。
@item
authorityパートのhostnameを文字列で。
(例： @code{ftp://anonymous@@ftp.example.com/pub/foo}の
@code{"ftp.example.com"})。
@item
authorityパートのport番号を整数で。
(例： @code{http://www.example.com:8080/}の@code{8080})。
@item
pathパート。
(例： @code{http://www.example.com/index.html}の@code{"/index.html"})。
@item
queryパート。
(例： @code{http://www.example.com/search?key=xyz&lang=en}の
@code{"key=xyz&lang=en"})。
@item
fragmentパート。
(例： @code{http://www.example.com/document.html#section4}の
@code{"section4"})。
@end itemize
@c COMMON

@c EN
The following procedures are finer grained and break up
uris with different stages.
@c JP
以下の手続きはより詳細に、段階をふんでuriを分割してゆくものです。
@c COMMON

@c EN
@code{uri-scheme&specific} takes a URI @var{uri}, and
returns two values, its scheme part and its scheme-specific part.
If @var{uri} doesn't have a scheme part, @var{#f} is returned for it.
@c JP
@code{uri-scheme&specific} は URI @var{uri} を引数に取り、
スキーム部分と、そのスキーム特有の部分を表す2つの値を返します。
@var{uri} がスキーム部分を持たない場合、@var{#f} を返します。
@c COMMON
@example
(uri-scheme&specific "mailto:sclaus@@north.pole")
  @result{} "mailto" @r{and} "sclaus@@north.pole"
(uri-scheme&specific "/icons/new.gif")
  @result{} #f @r{and} "/icons/new.gif"
@end example

@c EN
If the URI scheme uses hierarchical notation, i.e.
``@code{//@var{authority}/@var{path}?@var{query}#@var{fragment}}'',
you can pass
the scheme-specific part to @code{uri-decompose-hierarchical}
and it returns four values, @var{authority}, @var{path}, @var{query}
and @var{fragment}.
@c JP
URI が階層的な記法を用いている場合、すなわち、
``@code{//@var{authority}/@var{path}?@var{query}#@var{fragment}}''
のような場合、スキーム特有の部分を @code{uri-decompose-hierarchical}
に渡すと、@var{authority}、@var{path}、@var{query}、@var{fragment}
の4つの値が返ります。
@c COMMON
@example
(uri-decompose-hierarchical "//www.foo.com/about/company.html")
  @result{} "www.foo.com"@r{,} "/about/company.html"@r{,} #f @r{and} #f
(uri-decompose-hierarchical "//zzz.org/search?key=%3fhelp")
  @result{} "zzz.org"@r{,} "/search"@r{,} "key=%3fhelp" @r{and} #f
(uri-decompose-hierarchical "//jjj.jp/index.html#whatsnew")
  @result{} "jjj.jp"@r{,} "/index.html"@r{,} #f @r{and} "whatsnew"
(uri-decompose-hierarchical "my@@address")
  @result{} #f@r{,} #f@r{,} #f @r{and} #f
@end example

@c EN
Furthermore, you can parse @var{authority} part of the
hierarchical URI by @code{uri-decompose-authority}.
It returns @var{userinfo}, @var{host} and @var{port}.
@c JP
さらに、階層的 URI の @var{authority} の部分を
@code{uri-decompose-authority} に渡すと、@var{userinfo}、
@var{host}、@var{port} が返ります。
@c COMMON
@example
(uri-decompose-authority "yyy.jp:8080")
  @result{} #f@r{,} "yyy.jp" @r{and} "8080"
(uri-decompose-authority "mylogin@@yyy.jp")
  @result{} "mylogin"@r{,} "yyy.jp" @r{and} #f
@end example
@end defun

@defun uri-compose :key scheme userinfo host port authority path path* query fragment specific
@c EN
Compose a URI from given components.
There can be various combinations of components to create a valid
URI---the following diagram shows the possible 'paths' of
combinations:
@c JP
与えられたコンポーネントから URI を構成します。
妥当な URI を作成するためのコンポーネントの組み合わせはたくさんあります。
以下のダイアグラムは、考え得る組み合わせの方法を示しています。
@c COMMON

@example
        /-----------------specific-------------------\
        |                                            |
 scheme-+------authority-----+-+-------path*---------+-
        |                    | |                     |
        \-userinfo-host-port-/ \-path-query-fragment-/
@end example

@c EN
If @code{#f} is given to a keyword argument, it is
equivalent to the absence of that keyword argument.
It is particularly useful to pass the results of
parsed uri.

If a component contains a character that is not appropriate
for that component, it must be properly escaped before
being passed to @code{url-compose}.

Some examples:
@c JP
キーワード引数に @code{#f} が与えられた場合、それはキーワード引数が
指定されないことと等価です。これは URI をパーズした結果を渡す場合に
特に有用です。

コンポーネントに適切でない文字が含まれている場合は、
@code{url-compose} に渡す前に正しくエスケープされなければなりません。

いくつかの例を示します。
@c COMMON
@example
(uri-compose :scheme "http" :host "foo.com" :port 80
             :path "/index.html" :fragment "top")
  @result{} "http://foo.com:80/index.html#top"

(uri-compose :scheme "http" :host "foo.net"
             :path* "/cgi-bin/query.cgi?keyword=foo")
  @result{} "http://foo.net/cgi-bin/query.cgi?keyword=foo"

(uri-compose :scheme "mailto" :specific "a@@foo.org")
  @result{} "mailto:a@@foo.org"

(receive (authority path query fragment)
   (uri-decompose-hierarchical "//foo.jp/index.html#whatsnew")
 (uri-compose :authority authority :path path
              :query query :fragment fragment))
  @result{} "//foo.jp/index.html#whatsnew"
@end example
@end defun


@defun uri-merge base-uri relative-uri relative-uri2 @dots{}
@c EN
Arguments are strings representing
full or part of URIs.  This procedure resolves @var{relative-uri}
in relative to @var{base-uri}, as defined in RFC3986 Section 5.2. 
``Relative Resolution''.

If more @var{realtive-uri2}s are given, first @var{relative-uri}
is merged to @var{base-uri}, then the next argument is merged
to the resulting uri, and so on.
@c JP
引数は、完全な、あるいは部分的なURIを表す文字列です。
この手続きは、RFC3986 Section 5.2. ``Relative Resolution'' に
示されるアルゴリズムに従い、@var{relative-uri}を@var{base-uri}からの相対
として解決します。

@var{relative-uri2} @dots{} が与えられた場合は、まず@var{relative-uri}
が@var{base-uri}を基準に解決され、その結果を新たな基準として次の
@var{relative-uri2}を解決し、以下同様に続けます。
@c COMMON

@example
(uri-merge "http://example.com/foo/index.html" "a/b/c")
 @result{} "http://example.com/foo/a/b/c"

(uri-merge "http://example.com/foo/search?q=abc" "../about#me")
 @result{} "http://example.com/about#me"

(uri-merge "http://example.com/foo" "http://example.net/bar")
 @result{} "http://example.net/bar"

(uri-merge "http://example.com/foo/" "q" "?xyz")
 @result{} "http://example.com/foo/q?xyz"
@end example
@end defun


@defun uri-decode :key :cgi-decode
@defunx uri-decode-string string :key :cgi-decode :encoding
@c EN
Decodes ``URI encoding'', i.e. @code{%}-escapes.
@code{uri-decode} takes input from the current input port,
and writes decoded result to the current output port.
@code{uri-decode-string} takes input from @var{string} and
returns decoded string.

If @var{cgi-decode} is true, also replaces @code{+} to a space character.

To @code{uri-decode-string} you can provide the external character
encoding by the @var{encoding} keyword argument.  When it is given,
the decoded octet sequence is assumed to be in the specified encoding
and converted to the Gauche's internal character encoding.
@c JP
URI エンコーディング、すなわち、@code{%}でエスケープされた URI 文字列を
デコードします。@code{uri-decode} は現在の入力ポートから入力を受け取り、
デコードした結果を現在の出力ポートに書き出します。
@code{uri-decode-string} は @var{string} を入力とし、デコードした
文字列を返します。

@var{cgi-decode} が真の場合は、@code{+} がスペース文字に置換されます。

@code{uri-decode-string}には、外部の文字エンコーディングを指定する
@var{encoding}キーワード引数を与えることができます。この引数が与えれた
場合、デコードされたオクテットの列を指定された文字エンコーディングであると
してGaucheの内部文字エンコーディングへと変換したものが返されます。
@c COMMON
@end defun

@defun uri-encode :key :noescape
@defunx uri-encode-string string :key :noescape :encoding
@c EN
Encodes unsafe characters by @code{%}-escape.  @code{uri-encode}
takes input from the current input port and writes the result to
the current output port.  @code{uri-encode-string} takes input
from @var{string} and returns the encoded string.

By default, characters that are not specified ``unreserved'' in
RFC3986 are escaped.  You can pass different character
set to @var{noescape} argument to keep from being encoded.
For example, the older RFC2396 has several more ``unreserved''
characters, and passing @code{*rfc2396-unreserved-char-set*} (see below)
prevents those characters from being escaped.

The multibyte characters are encoded as the octet stream of Gauche's
native multibyte representation by default.  However, you can pass
the @code{encoding} keyword argument to @code{uri-encode-string},
to convert @var{string} to the specified character encoding.
@c JP
安全でない文字を、@code{%}によるエスケープでエンコードします。
@code{uri-encode} は現在の入力ポートから入力を受け取り、
結果を現在の出力ポートに書き出します。
@code{uri-encode-string} は @var{string} を入力とし、エンコードした
文字列を返します。

デフォルトでは、RFC3986 で"非予約文字"として規定されていない文字は
エスケープされます。@var{noescape} 引数に異なる文字セットを渡すことで、
それらがエンコードされるのを抑止することができます。
例えば古いRFC2396では"非予約文字"がいくつか多かったのですが、
@code{*rfc2396-unreserved-char-set*} (下記参照) を渡すことで
それらの文字がエスケープされるのを防ぐことができます。

マルチバイト文字は、デフォルトではGauche のネイティブなマルチバイト表現の
オクテット・ストリームとしてエンコードされます。ただし
@code{uri-encode-string}には@var{encoding}キーワード引数を渡すことができて、
その場合はまず@var{string}が指定された文字エンコーディングへと変換されます。
@c COMMON
@end defun

@defvr {Constant} *rfc2396-unreserved-char-set*
@defvrx {Constant} *rfc3986-unreserved-char-set*
@c EN
These constants are bound to character sets that represents
``unreserved'' characters defined in RFC2396 and RFC3986, respectively.
(See @ref{Character set}, and @ref{Character-set library}, for
operations on character sets).
@c JP
これらの定数はそれぞれ、RFC2396とRFC3986で定義されている
「非予約文字」の文字集合に束縛されています。
(文字集合の操作については、@ref{Character set}および@ref{Character-set library}
を参照して下さい。)
@c COMMON
@end defvr

@c ----------------------------------------------------------------------
@node Zlib compression library, SLIB, URI parsing and construction, Library modules - Utilities
@section @code{rfc.zlib} - zlib compression library
@c NODE zlib圧縮ライブラリ, @code{rfc.zlib} - zlib圧縮ライブラリ

@deftp {Module} rfc.zlib
@mdindex rfc.zlib
@c EN
This module provides bindings to zlib compression library.
Most features of zlib can be used through this module.

Zlib supports reading and writing of
Zlib compressed data format (RFC1950),
DEFLATE compressed data format (RFC1951),
and GZIP file format (RFC1052).  It also provides
procedures to calculate CRC32 and Adler32 checksums.

Compression and decompression are done through specialized ports.
There are number of parameters to fine-tune compression; refer
to zlib documentation for the details.
@c JP
このモジュールは、Zlib圧縮ライブラリに対するバインディングを提供します。
Zlibのほとんどの機能がこのモジュールを通して利用可能です。

Zlibは、ZLIB圧縮データフォーマット(RFC1950)、DEFLATE圧縮データフォー
マット(RFC1951)、GZIPファイルフォーマット(RFC1952)の読み書きをサポー
トするライブラリです。また、CRC32とAdler32チェックサムの計算のための
関数も提供します。

圧縮・展開機能はポートを通して提供されます。圧縮をチューンするパラ
メータの詳細については、Zlibのドキュメントも合わせて参照してください。
@c COMMON
@end deftp

@subheading Condition types

@c EN
The following condition types are defined to represent errors
during processing by zlib.
@c JP
Zlib処理中のエラーを示すために、以下のコンディションタイプが定義されています。
@c COMMON

@deftp {Condition Type} <zlib-error>
@c EN
Subclass of @code{<error>} and superclass of the following
condition types.  This class is an abstract class to catch any of the
zlib-specific errors.  Zlib-specific errors raised by
procedures in @code{rfc.zlib} are always an instance (or a compound
condition including) one of the following specific classes.
@c JP
@code{<error>}のサブクラスで、以下のコンディションタイプのスーパークラスです。
このクラスはzlib特有のエラーをまとめて捕捉するための抽象クラスとして設けられています。
@code{rfc.zlib}が投げるZlib固有のエラーは常に以下の特定のクラスのインスタンス、
もしくはそのインスタンスを含む複合コンディションです。
@c COMMON
@end deftp

@deftp {Condition Type} <zlib-need-dict-error>
@deftpx {Condition Type} <zlib-stream-error>
@deftpx {Condition Type} <zlib-data-error>
@deftpx {Condition Type} <zlib-memory-error>
@deftpx {Condition Type} <zlib-version-error>
@c EN
Subclasses of @code{<zlib-error>}.  Those condition type correspond
to zlib's 
@code{Z_NEED_DICT_ERROR},
@code{Z_STREAM_ERROR},
@code{Z_DATA_ERROR},
@code{Z_MEMORY_ERROR}, and
@code{Z_VERSION_ERROR} errors.
@c JP
@code{<zlib-error>}のサブクラスです。それぞれ、Zlibの
@code{Z_NEED_DICT_ERROR}、
@code{Z_STREAM_ERROR}、
@code{Z_DATA_ERROR}、
@code{Z_MEMORY_ERROR}、
@code{Z_VERSION_ERROR}
に対応します。
@c COMMON

@c EN
When an error occurs during reading data, a compound 
condition of a subclass of @code{<zlib-error>} and
@code{<io-read-error>} is raised.
When an error occurs without I/O, a simple condition
of a subclass of @code{<zlib-error>} is raised.
Errors unrelated to zlib, such as invalid argument error,
would be a simple @code{<error>} condition.
@c JP
データの読み出し時にエラーが発生した場合、
@code{<zlib-error>}のサブクラスと
@code{<io-read-error>}の合成コンディションが投げられます。入力が伴わ
ない場合、例えば圧縮ストリームの初期化エラーのときには、合成され
ていない@code{<zlib-error>}のサブクラスが投げられます。ただの引数の型の
エラーのように、Zlibの関数が呼び出されない場合は、ただの@code{<error>}が
投げられるかもしれません。
@c COMMON
@end deftp

@subheading Compression/decompression ports

@deftp {Class} <deflating-port>
@deftpx {Class} <inflating-port>
@c EN
Compression and decompression functions are provided
via ports.  A @emph{deflating port} is an output port
that compresses the output data.  An @emph{inflating port}
is an input that reads compressed data and decompress it.

When an inflating port encounters a corrupted compressed
data, a compound condition of @code{<io-read-error>}
and @code{<zlib-data-error>} is raised during read operation.
@c JP
圧縮と展開の機能はポートを通じて提供されます。
@emph{deflating port}は出力されたデータを圧縮する出力ポートです。
@emph{inflating port}は圧縮されたデータソースからデータを展開しつつ
読み込む入力ポートです。

inflating portが読み出す圧縮データが壊れていた場合、読み出し時に
@code{<io-read-error>}と@code{<zlib-data-error>}の
合成コンディションが投げられます。
@c COMMON
@end deftp


@defun open-deflating-port drain :key compression-level buffer-size window-bits memory-level strategy dictionary owner?
@c EN
Creates and returns an instance of @code{<deflating-port>},
an output port that compresses the output data and sends 
the compressed data to another output port @var{drain}.
This combines the functionality of zlib's @code{deflateInit2()}
and @code{deflateSetDictionary()}.
@c JP
新たな@code{<deflating-port>}のインスタンス、
すなわち書き込まれたデータを圧縮し出力ポート@var{drain}に書き出す出力ポートを作成して、
そのポートを返します。Zlibの関数@code{deflateInit2()}と
@code{deflateSetDictionary()}とを合わせた手続きです。
@c COMMON

@c EN
You can specify an exact integer between 1 and 9 (inclusive) to
@var{compression-level}.  Larger integer means larger compression ratio.
When omitted, a default compression level is used, which is usually 6.
@c JP
@var{compression-level}には1から9の整数を指定することができ、
大きい数が高い圧縮率を意味します。引数が省略された場合は、
デフォルトの圧縮レベルと見なされます。これは通常6です。
@c COMMON

@c EN
The following constants are defined to specify @var{compression-level}
conveniently:
@c JP
@var{compression-level}をわかりやすく指定するために以下の定数が定義されています。
@c COMMON

@defvr {Constant} Z_NO_COMPRESSION
@defvrx {Constant} Z_BEST_SPEED
@defvrx {Constant} Z_BEST_COMPRESSION
@defvrx {Constant} Z_DEFAULT_COMPRESSION
@end defvr

@c EN
The @var{buffer-size} argument specifies the buffer size of the port in bytes.
The default is 4096.
@c JP
@var{buffer-size}は、ポートのバッファサイズを指定します。デフォルトは4096バイトです。
@c COMMON

@c EN
The @var{window-bits} argument specifies the size of the window in
exact integer.   Typically the value should be 
between 8 and 15, inclusive, and it specifies the base two logarithm
of the window size used in compression.
Larger number yields better compression ratio, but more memory usage.
The default value is 15.
@c JP
@var{window-bits}はウィンドウサイズを指定します。
通常この値は8から15までの整数で、圧縮に使われるウィンドウサイズの
2を底とするlogをとった値です。
大きい数であるだけ圧縮率が高くなりますが、
そのぶんメモリの使用量が増加します。デフォルトは15です。
@c COMMON

@c EN
There are a couple of special modes specifiable by @var{window-bits}.
When an integer between -8 and -15 is given to
@var{window-bits}, the port produces a raw deflated data,
that lacks zlib header and trailer.  In this case, Adler32 checksum isn't
calculated.  The actual window size is determiend by the absolute value of 
@var{window-bits}.
@c JP
@var{window-bits}よって、2つばかり特別なモードを指定することができます。
@var{window-bits}に-8から-15の整数を指定された場合は、
ZLIBヘッダとトレイラのない生のdeflateデータを作成します。
この場合Adler32チェックサムも計算されません。
実際のウィンドウサイズは@var{window-bits}の絶対値によって計算されます。
@c COMMON

@c EN
When @var{window-bits} is between 24 and 31, the port uses GZIP encoding; 
that is, instead of zlib wrapper,
the compressed data is enveloped by simple gzip header and trailer.
The gzip header added by this case doesn't have filenames, comments,
header CRC and other data, and have zero modified time, and 255 (unknown)
in the OS field.  The @code{zstream-adler32} procedure will return
CRC32 checksum instead of Adler32.
The actual window size is determined by @var{window-bits}-16.
@c JP
@var{window-bits}が24から31の間である場合、
ポートはgzipエンコーディングを使うようになります。すなわち、
zlibラッパの代わりに、シンプルなgzipヘッダとトレイラが圧縮データの前後に書き出されます。
gzipヘッダはファイル名やその他のデータ、コメントを持たず、変更時刻は0、
ヘッダCRCはなし、OS名は不明を意味する255になります。gzipストリームが書き出
されるときは、@code{zstream-adler32}で取得できるチェックサムはAdler32
ではなくCRC32になります。
実際のウィンドウサイズは @var{window-bits}-16 で決定されます。
@c COMMON

@c EN
The @var{memory-level} argument specifies how much memory
should be allocated to keep the internal state during compression.
1 means smallest memory, which causes slow and less compression.
9 means fastest and best compression with largest amount of memory.
The default value is 8.
@c JP
@var{memory-level}は、圧縮の内部状態のためにどれだけのメモリを割り当て
るかを指定するパラメータです。1ではメモリの使用量は最小ですが、遅
くなり圧縮率が低下します。9では高速な処理のためにメモリが最も多く
使われます。デフォルトは8です。
@c COMMON

@c EN
To fine tune compression algorithm, you can use the @var{strategy}
argument.  The following constants are defined as the valid
value as @var{strategy}:
@c JP
@var{strategy}で圧縮アルゴリズムをチューンできます。
以下の定数が@var{strategy}に有効な値として定義されています。
@c COMMON

@defvr {Constant} Z_DEFAULT_STRATEGY
@c EN
The default strategy, suitable for most ordinary data.
@c JP
通常のデータに適する、デフォルトのアルゴリズムを使います。
@c COMMON
@end defvr

@defvr {Constant} Z_FILTERED
@c EN
Suitable for data genereated by filters.
Filtered data consists mostly of small values with a
random distribution, and this makes the compression algorithm
to use more huffman encoding and less string match.
@c JP
フィルタにより生成されたデータに適したアルゴリズムを使います。
このようなデータは小さな値とランダムな分散を持つことが多いため、
このアルゴリズムではハフマンエンコーディングをより優先し、
文字列一致の使用をやや抑えます。
@c COMMON
@end defvr

@defvr {Constant} Z_HUFFMAN_ONLY
@c EN
Force huffman encoding only (no string match).
@c JP
ハフマンエンコーディングのみを使います (文字列一致を使いません)。
@c COMMON
@end defvr

@defvr {Constant} Z_RLE
@c EN
Limit match distance to 1 (that is, to force run-length encoding).
It is as fast as @code{Z_HUFFMAN_ONLY} and gives better compression
for png image data.
@c JP
マッチ距離を1に制限します (ランレングスエンコーディングを強制することになります)。
@code{Z_HUFFMAN_ONLY}と同じくらい高速で、かつpngイメージデータに対して
良い圧縮率が得られます。
@c COMMON
@end defvr

@defvr {Constant} Z_FIXED
@c EN
Prohibits dynamic huffman encoding.  It allows a simple decoder
for special applications.
@c JP
動的ハフマンエンコーディングを禁止します。特殊なアプリケーションで、
単純なデコーダを使いたい場合に便利です。
@c COMMON
@end defvr

@c EN
The choice of @var{strategy} only affects compression ratio and
speed.  Any choice produces correct and decompressable data.
@c JP
@var{strategy}の選択は圧縮率と速度にのみ影響を与えます。
どの値を選んでも圧縮されたデータは正しく展開できます。
@c COMMON

@c EN
You can give an initial dictionary to the @var{dictionary}
argument to be used in compression.  
The compressor and decompressor must use exactly the same dictionary.
See the zlib documentation for the details.
@c JP
@var{dictionary}には圧縮に使う辞書を文字列で与えます。辞書を与える場合、
圧縮と展開で全く同じものを使う必要があります。
辞書の詳細についてはzlibのドキュメントを参照してください。
@c COMMON

@c EN
By default, a deflating port leaves @var{drain} open
after all conversion is done, i.e. the deflating port itself is
closed.  If you don't want to bother closing @var{drain},
give a true value to the @var{owner?} argument; then @var{drain}
is closed after the deflating port is closed and all data
is written out.
@c JP
デフォルトでは、deflating portはそれ自身がクローズされても
@var{drain}をクローズしません。@var{drain}の後始末を気にしたくない
場合は@var{owner?}引数に真の値を与えてください。
その場合、deflating portがクローズされすべてのデータが書き出されたのちに
@var{drain}は自動的にクローズされます。
@c COMMON

@c EN
Note: You @emph{must} close a deflating port explicitly,
or the compressed data can be chopped prematurely. 
When you leave a deflating port open to be GCed, the
finalizer will close it; however, the order in which
finalizers are called is undeterministic, and it is
possible that the @var{drain} port is closed before
the deflating port is closed.  In such cases, 
the deflating port's attempt to flush the buffered data
and trailer will fail.
@c JP
注意: deflating portは必ず明示的にクローズしてください。
そうしなければ圧縮データの終わりの部分(バッファされているデータおよびトレイラ)が
@var{drain}に書き出されないかもしれません。
ポートを明示的にクローズせずにガベージ・コレクタに任せた場合、
出力ポートのクローズ手続きはファイナラザから呼び出されることになります。
複数のごみに対してファイナライザの呼ばれる順番は不定なので、
deflating portより先に@var{drain}のファイナライザが呼ばれて
そのポートがクローズされてしまうことがあります。
こうなると、圧縮データの終わりの部分の出力がエラーになってしまいます。
@c COMMON
@end defun

@defun open-inflating-port source :key buffer-size window-bits dictionary owner?
@c EN
Takes an input port @var{source} from which a compressed data
can be read, and creates and returns a new instance of
@code{<inflating-port>}, that is, a port that allows
decompressed data from it.
This procedure covers zlib's functionarity of
@code{inflateInit2()} and @code{inflateSetDictionary()}.
@c JP
圧縮データを読み出せる入力ポート@var{source}を取り、
新たな@code{<inflating-port>}のインスタンス、すなわち
展開されたデータを読み出すことのできる入力ポートを作成し、そのポートを返します。
これはZlibの関数@code{inflateInit2()}、@code{inflateSetDictionary()}
を合わせた手続きです。
@c COMMON

@c EN
The meaning of @var{buffer-size} and @var{owner} are
the same as @code{open-deflating-port}.
@c JP
@var{buffer-size}、@var{owner?}の意味は
@code{open-deflating-port}と同じです。
@c COMMON

@c EN
The meaning of @var{window-bits} is almost the same,
except that if a value incresed by 32 is given, the inflating port
automatically detects whether the source stream is
zlib or gzip by its header.
@c JP
@var{window-bits}の意味もほぼ同じですが、
32が足された値が与えられた場合にはZLIBとGZIPのヘッダ自動判定が有効になります。
@c COMMON

@c EN
If the input data is compressed with specified dictionary,
the same dictionary must be given to the @var{dictionary} argument.
Otherwise, a compound condition of
@code{<io-read-error>} and @code{<zlib-need-dict-error>} will be raised.
@c JP
@var{dictionary}は圧縮時の辞書と同じものを指定しなければなりません。
辞書を使って圧縮されたデータを展開する際に、@var{dictionary}引数
を指定しなかったり、異なる辞書を与えた場合は
@code{<io-read-error>}と@code{<zlib-need-dict-error>}の
合成コンディションが投げられます。
@c COMMON
@end defun

@subheading Operations on inflating/deflating ports

@defun zstream-total-in xflating-port
@defunx zstream-total-out xflating-port
@defunx zstream-adler32 xflating-port
@defunx zstream-data-type xflating-port
@c EN
The @var{xflating-port} argument must be either 
inflating and deflating port, or an error is raised.

Returns the value of @code{total_in}, @code{total_out},
@var{adler32}, and @code{data_type} fields of the @code{z_stream} 
structure associated to the given inflating or deflating port,
respectively.
@c JP
@var{xflating-port}はinflating portかdeflating portでなければ
なりません。さもなくばエラーが通知されます。

@code{z_stream}構造体の@code{total_in}、@code{total_out}、
@code{adlre32}および@code{data_type}フィールドの値を返します。
@c COMMON

@c EN
The value of @code{data_type} can be one of the following
constants:
@c JP
@code{data_type}フィールドの値は以下の定数のうちのいずれかです。
@c COMMON

@defvr {Constant} Z_BINARY
@defvrx {Constant} Z_TEXT
@defvrx {Constant} Z_ASCII
@defvrx {Constant} Z_UNKNOWN
@end defvr

@end defun

@defun zstream-params-set! deflating-port :key compression-level strategy
@c EN
Changes compression level and/or strategy during compressing.
@c JP
圧縮率とストラテジを動的に変更するための手続きです。
@c COMMON
@end defun

@defun zstream-dictionary-adler32 deflating-port
@c EN
When a dictionary is given to @code{open-deflating-port}, the
dictionary's adler32 checksum is calculated.  This
procedure returns the checksum.  If no dictionary has been given,
this procedure returns @code{#f}.
@c JP
deflating portの作成時に辞書を指定すると、辞書のAdler32チェックサム
が計算されます。この手続きはそのチェックサムを返します。
@code{open-deflating-port}に辞書を与えなかったなら、@code{#f}が返ります。
@c COMMON
@end defun

@defun deflating-port-full-flush deflating-port
@c EN
Flush the data buffered in the @var{deflating-port}, and
resets compression state.  The decompression routine can
skip the data to the full-flush point by @code{inflate-sync}.
@c JP
ポートのデータをフルフラッシュし、圧縮状態をリセットします。
展開ルーチンは@code{inflate-sync}手続きを使って
入力をこの地点までスキップすることができます。
@c COMMON
@end defun

@defun inflate-sync inflating-port
@c EN
Skip the (possibly corrupted) compressed data up to the 
next full-flush point marked by @code{deflating-port-full-flush}.
You may want to use this procedure when you get 
@code{<zlib-data-error>}.  Returns the number of bytes
skipped when the next full-flush point is found, or
@code{#f} when the input reaches EOF before finding the next point.
@c JP
圧縮データを、@code{deflating-port-full-flush}によって
フルフラッシュしたポイントまで読み飛ばします。
@code{<zlib-data-error>}が投げられたときに使用するとよいでしょう。
フルフラッシュポイントに達したときは読み飛ばしたバイトの数を、EOFまで達
したときは@code{#f}を返します。
@c COMMON
@end defun

@subheading Miscellaneous API

@defun zlib-version
@c EN
Returns Zlib's version in string.
@c JP
Zlibのバージョンを文字列で返します。
@c COMMON
@end defun

@defun deflate-string string options @dots{}
@c EN
Compresses the given string and returns zlib-compressed data
in a string.  All optional arguments are passed to
@code{open-deflating-port} as they are.
@c JP
与えられた文字列を圧縮し、zlib圧縮されたデータを文字列で返します。
すべてのオプション引数はそのまま@code{open-deflating-port}に渡されます。
@c COMMON
@end defun

@defun inflate-string string options @dots{}
@c EN
Takes zlib-compressed data in string, and returns decompressed data
in a string.  All optional arguments are passed to
@code{open-inflating-port} as they are.
@c JP
Zlib圧縮されたデータを文字列で受け取り、展開されたデータを文字列で
返します。
すべてのオプション引数はそのまま@code{open-deflating-port}に渡されます。
@c COMMON
@end defun

@defun gzip-encode-string string options @dots{}
@defunx gzip-decode-string string options @dots{}
@c EN
Like @code{deflate-string} and @code{inflate-string}, but 
uses the gzip format instead.  It is same as giving
more than 15 to the @var{window-bits} argument of @code{deflate-string}
and @code{inflate-string}.
@c JP
@code{deflate-string}および@code{inflate-string}と似ていますが、
GZIPフォーマットを使います。これは
@code{deflate-string}および@code{inflate-string}の
@var{window-bits}に15以上の値指定するのと同じです。
@c COMMON
@end defun

@defun crc32 string :optional checksum
@c EN
Returns CRC32 checksum of @var{string}.  If optional @var{checksum}
is given, the returned checksum is an update of @var{checksum} by
@var{string}.
@c JP
文字列@var{string}のCRC32チェックサムを計算して返します。@var{checksum}
引数が与えられた場合は、それを@var{string}によるチェックサムで更新した
値が返されます。
@c COMMON
@end defun

@defun adler32 string :optional checksum
@c EN
Returns Adler32 checksum of @var{string}.  If optional @var{checksum}
is given, the returned checksum is an update of @var{checksum} by
@var{string}.

Calculating Adler32 is faster than CRC32, but it is known to produce
uneven distribution of hash values for small input.
See RFC3309 for the detailed description.  If it matters,
use CRC32 instead.
@c JP
文字列@var{string}のAdler32チェックサムを計算して返します。@var{checksum}
引数が与えられた場合は、それを@var{string}によるチェックサムで更新した
値が返されます。

Adler32はCRC32と比較して高速に計算することが可能なアルゴリズムです
が、小さなデータのチェックサムの信頼性にいくらか問題があることがわ
かっています。詳しくはRFC3309を見てください。これが問題になる場合
はCRC32を使用してください。
@c COMMON
@end defun






@c ----------------------------------------------------------------------
@node SLIB, Functional XML parser, Zlib compression library, Library modules - Utilities
@section @code{slib} - SLIB interface
@c NODE SLIBインタフェース, @code{slib} - SLIBインタフェース

@deftp {Module} slib
@mdindex slib
@c EN
This module is the interface to the Aubrey Jaffer's SLIB.
To use SLIB, say @code{(use slib)}.   SLIB itself is not included
in Gauche distribution.   If you don't have it on your system,
get it from @uref{http://www-swiss.ai.mit.edu/~jaffer/SLIB.html}.
@c JP
このモジュールはAubrey Jaffer氏のSLIBへのインタフェースです。
SLIBがインストールされている場合、@code{(use slib)} とすれば
SLIBの機能が使えるようになります。
SLIBそのものはGaucheのディストリビューションには含まれていません。
あなたのシステムにまだインストールされていない場合は
@uref{http://www-swiss.ai.mit.edu/~jaffer/SLIB.html}から入手することができます。
@c COMMON

@c EN
This module redefines @code{require}, shadowing the Gauche's original
@code{require}.  If it gets a symbol as an argument, it works as
SLIB's @code{require}, while if it gets a string, it works as
Gauche's @code{require}.   The same applies to @code{provide} and
@code{provided?}.
@c JP
このモジュールは@code{require}を再定義し、Gaucheオリジナルの@code{require}を
シャドウします。@code{require}にシンボルが渡された場合はSLIBの@code{require}
のように動作します。@code{require}に文字列が渡された場合はGaucheの@code{require}
のように動作します。@code{provide}と@code{provided?}についても同様です。
@c COMMON

@c EN
All SLIB symbol bindings, loaded by @code{require}, stay in the
module @code{slib}.
@c JP
@code{require}でロードされる、SLIBで導入されるすべての定義は、
@code{slib}モジュール内で行われます。
@c COMMON
@end deftp

@example
(use slib)         ; @r{load and set up slib}
(require 'getopt)  ; @r{load SLIB's getopt module}
(require "foo")    ; @r{load Gauche's foo module}
@end example

@c ----------------------------------------------------------------------
@node Functional XML parser, SXML Query Language, SLIB, Library modules - Utilities
@section @code{sxml.ssax} - Functional XML parser
@c NODE 関数的なXMLパーザ, @code{sxml.ssax} - 関数的なXMLパーザ

@deftp {Module} sxml.ssax
@mdindex sxml.ssax
@c EN
@code{sxml.*} modules are the adaptation of
Oleg Kiselyov's SXML framework (@ref{ssax,,SSAX}),
which is based on S-expression representation of XML structure.
@c JP
@code{sxml.*}モジュールは、XML構造のS式表現に基づく
Oleg KiselyovのSXMLフレームワーク(@ref{ssax,,SSAX}参照)の適合です。
@c COMMON

@c EN
SSAX is a parser part of SXML framework.
This is a quote from SSAX webpage:
@c JP
SSAXは、SXMLフレームワークのパーザ部分です。以下は、
SSAXのウェブページからの引用です。
@c COMMON

@quotation
@c EN
A SSAX functional XML parsing framework consists of a DOM/SXML parser,
a SAX parser, and a supporting library of lexing and parsing procedures.
The procedures in the package can be used separately to tokenize or parse
various pieces of XML documents.
The framework supports XML Namespaces, character, internal
and external parsed entities, attribute value normalization,
processing instructions and CDATA sections. The package includes
a semi-validating SXML parser : a DOM-mode parser that is an
instantiation of a SAX parser (called SSAX).
@c JP
SSAXは関数的なXMLパージングフレームワークで、DOM/SXMLパーザ、SAXパーザ、
字句解析・構文解析手続きのサポートライブラリから構成されます。
パッケージ内の手続きは、XML文書の様々な部分をトークナイズ、あるいは
パーズするために独立して使うことができます。
このフレームワークは、XML名前空間、文字、内部および外部解析済み実体、
属性値の正規化、処理命令とCDATAセクションをサポートしています。
パッケージは、ある程度の妥当性検査を行うSXMLパーザ: SAXパーザの
インスタンスであるDOMモードのパーザ(SSAXと呼ばれます)を含んでいます。
@c COMMON
@end quotation

@c EN
The current version is based on the SSAX CVS version newer than
the last 'official' release of SXML toolset (4.9), and
SXML-gauche-0.9 package which was based on SXML-4.9.
There is an important change from that release.
Now the API uses lowercase letter suffix @code{ssax:}
instead of uppercase @code{SSAX:}---the difference matters since
Gauche is case sensitive by default.
Alias names are defined for backward compatibility,
but the use of uppercase suffixed names are deprecated.
@c JP
現在のバージョンは、SXMLツールセットの最新の'公式な'リリース(4.9)よりも
新しい、SSAXのCVSバージョンをベースにしており、パッケージSXML-gauche-0.9は、
SXML-4.9をベースにしています。
SXMLのリリース4.9以降では、重要な変更があります。
現在のAPIでは、大文字の接頭辞@code{SSAX:}の代わりに小文字の@code{ssax:}を
使います。Gaucheはデフォルトで文字の大小を区別するために、この違いは
問題となります。
後方互換性のためにエイリアスされた名前が定義されていますが、
大文字の接頭辞付きの名前の使用は推奨されません。
@c COMMON
@end deftp

@c EN
I derived the content of this part of the manual from SSAX
source code, just by converting its comments into texinfo format.
The original text is by Oleg Kiselyov.  Shiro Kawai
should be responsible for any typographical error or formatting error
introduced by conversion.
@c JP
マニュアルのこのパートの内容はSSAXのソースコードから抽出されたもので、
単にそのコメントをTexinfoのフォーマットに変換しただけです。
オリジナルのテキストは、Oleg Kiselyovによるものです。
変換により生じた誤字・誤植やフォーマットエラーの責任は、
Shiro Kawaiにあります。
@c COMMON

@c EN
The manual entries are ordered in "bottom-up" way, beginning from
the lower-level constructs towards the high-level utilities.
If you just want to parse XML document and obtain SXML,
check out @code{ssax:xml->sxml} in @ref{SSAX Highest-level parsers - XML to SXML}.
@c JP
このマニュアルのエントリは、低レベルの構造から高レベルのユーティリティへと
``ボトムアップ''の方法で並べられています。
もし、あなたが単にXMLドキュメントをパーズしたりSXMLを得たいだけならば、
@ref{SSAX Highest-level parsers - XML to SXML}の@code{ssax:xml->sxml}を
チェックして下さい。
@c COMMON

@c ----------------------------------------------------------------------
@menu
* SSAX data types::             
* SSAX low-level parsing code::  
* SSAX higher-level parsers and scanners::  
* SSAX Highest-level parsers - XML to SXML::  
@end menu

@node SSAX data types, SSAX low-level parsing code, Functional XML parser, Functional XML parser
@subsection SSAX data types
@c NODE SSAXデータタイプ

@table @emph
@item TAG-KIND
@c EN
a symbol '@code{START}, '@code{END}, '@code{PI}, '@code{DECL}, '@code{COMMENT}, '@code{CDSECT}
or '@code{ENTITY-REF} that identifies a markup token.
@c JP
シンボル'@code{START}、'@code{END}、'@code{PI}、'@code{DECL}、'@code{COMMENT}、
'@code{CDSECT}は、マークアップトークンを識別するものです。
@c COMMON
@item UNRES-NAME
@c EN
a name (called @code{GI} in the XML Recommendation) as given in an xml
document for a markup token: start-tag, @code{PI} target, attribute name.
If a @code{GI} is an @code{NCName}, @var{UNRES-NAME} is this @code{NCName} converted into
a Scheme symbol. If a @code{GI} is a @code{QName}, @var{UNRES-NAME} is a pair of
symbols: (@var{PREFIX} . @var{LOCALPART})
@c JP
XML文書で、マークアップトークン: 開始タグ、@code{PI}ターゲット、属性名に
与えられる名前(XML勧告では@code{GI}と呼ばれます)です。
@code{GI}が@code{NCName}である場合、@var{UNRES-NAME}はこの@code{NCName}が
Schemeのシンボルに変換されたものになります。
@code{GI}が@code{QName}ならば、@var{UNRES-NAME}は、シンボルのペア、
(@var{PREFIX} . @var{LOCALPART})となります。
@c COMMON
@item RES-NAME
@c EN
An expanded name, a resolved version of an @var{UNRES-NAME}.
For an element or an attribute name with a non-empty namespace URI,
@var{RES-NAME} is a pair of symbols, (@var{URI-SYMB} . @var{LOCALPART}).
Otherwise, it's a single symbol.
@c JP
展開された名前、つまり@var{UNRES-NAME}の解決されたバージョンです。
名前空間URIが空でない場合の要素や属性名では、@var{RES-NAME}はシンボルのペア、
(@var{URI-SYMB} . @var{LOCALPART})です。そうでない場合は、1つのシンボルです。
@c COMMON
@item ELEM-CONTENT-MODEL
@c EN
A symbol:
@c JP
以下のシンボルのうちの1つです。
@c COMMON
@c EN
@multitable @columnfractions .3 .7
@item @code{ANY}
@tab anything goes, expect an END tag.
@item @code{EMPTY-TAG} 
@tab no content, and no END-tag is coming.
@item @code{EMPTY} 
@tab no content, expect the END-tag as the next token.
@item @code{PCDATA}
@tab expect character data only, and no children elements.
@item @code{MIXED}
@tab
@item @code{ELEM-CONTENT}
@tab
@end multitable
@c JP
@multitable @columnfractions .3 .7
@item @code{ANY}
@tab 何でもよく、ENDタグがあるもの。
@item @code{EMPTY-TAG}
@tab 内容がなく、ENDタグのないもの。
@item @code{EMPTY}
@tab 内容がなく、次のトークンがENDタグであるもの。
@item @code{PCDATA}
@tab 文字データのみで、子要素がないもの。
@item @code{MIXED}
@tab
@item @code{ELEM-CONTENT}
@tab
@end multitable
@c COMMON
@item URI-SYMB
@c EN
A symbol representing a namespace URI -- or other symbol chosen
by the user to represent URI. In the former case,
@var{URI-SYMB} is created by @code{%}-quoting of bad URI characters and
converting the resulting string into a symbol.
@c JP
名前空間を表すシンボル、あるいはURIを表すためにユーザが選んだ他のシンボルです。
前者の場合、@var{URI-SYMB}は不正なURI文字が@code{%}でクォートされた
文字列をシンボルに変換したものです。
@c COMMON
@item NAMESPACES
@c EN
A list representing namespaces in effect. An element of the list
has one of the following forms:
@c JP
効力を持つ名前空間を表すリストです。リストの要素は、以下のフォームのうちの1つです。
@c COMMON

@c EN
@table @code
@item (@var{prefix} @var{uri-symb} . @var{uri-symb})
or,
@item (@var{prefix} @var{user-prefix} . @var{uri-symb})
@var{user-prefix} is a symbol chosen by the user
to represent the URI.
@item (#f @var{user-prefix} . @var{uri-symb})
Specification of the user-chosen prefix and a @var{uri-symbol}.
@item (*DEFAULT* @var{user-prefix} . @var{uri-symb})
Declaration of the default namespace
@item (*DEFAULT* #f . #f)
Un-declaration of the default namespace. This notation
represents overriding of the previous declaration
@end table
@c JP
@table @code
@item (@var{prefix} @var{uri-symb} . @var{uri-symb})
あるいは、
@item (@var{prefix} @var{user-prefix} . @var{uri-symb})
@var{user-prefix}は、そのURIを表現するためにユーザにより選ばれたシンボル。
@item (#f @var{user-prefix} . @var{uri-symb})
ユーザが選んだプリフィックスと@var{uri-symbol}の指定。
@item (*DEFAULT* @var{user-prefix} . @var{uri-symb})
デフォルト名前空間の宣言。
@item (*DEFAULT* #f . #f)
デフォルト名前空間を宣言しない。この記法は、それ以前の宣言を上書き
することを表す。
@end table
@c COMMON

@c EN
A @var{NAMESPACES} list may contain several elements for the same @var{PREFIX}.
The one closest to the beginning of the list takes effect.
@c JP
@var{NAMESPACES}のリストは、同じ@var{PREFIX}についていくつかの要素を含むかも
しれません。リストの先頭に近いものが効力を持ちます。
@c COMMON

@item ATTLIST
@c EN
An ordered collection of (@var{NAME} . @var{VALUE}) pairs, where @var{NAME} is
a @var{RES-NAME} or an @var{UNRES-NAME}. The collection is an ADT.
@c JP
ペア(@var{NAME} . @var{VALUE})の順序付きのコレクションで、@var{NAME}は
@var{RES-NAME}か@var{UNRES-NAME}です。このコレクションはADTです。
@c COMMON
@item STR-HANDLER
@c EN
A procedure of three arguments:
@code{(@var{string1} @var{string2} @var{seed})}
returning a new @var{seed}.
The procedure is supposed to handle a chunk of character data
@var{string1} followed by a chunk of character data @var{string2}.
@var{string2} is a short string, often "\n" and even ""
@c JP
3引数の手続き @code{(@var{string1} @var{string2} @var{seed})}で、
新しい@var{seed}を返します。
この手続きは、文字データ@var{string2}が後に続く、文字データ@var{string1}を
扱うものです。@var{string2}は、``\n''や``''のような短い文字列です。
@c COMMON
@item ENTITIES
@c EN
An assoc list of pairs:
@example
  (@var{named-entity-name} . @var{named-entity-body})
@end example
where @var{named-entity-name} is a symbol under which the entity was
declared, @var{named-entity-body} is either a string, or
(for an external entity) a thunk that will return an
input port (from which the entity can be read).
@var{named-entity-body} may also be @code{#f}. This is an indication that a
@var{named-entity-name} is currently being expanded. A reference to
this @var{named-entity-name} will be an error: violation of the
WFC nonrecursion.
@c JP
ペア (@var{named-entity-name} . @var{named-entity-body})の連想リストで、
@var{named-entity-name}はその実体が宣言されたシンボル、
@var{named-entity-body}は文字列か、(外部実体の場合は)
(そこから実体が読み込める)入力ポートを返す手続きです。
@var{named-entity-body}はまた、@code{#f}かも知れません。
これは、@var{named-entity-name}がその時点で展開されていることを
示します。
この@var{named-entity-name}への参照は、WFC非再帰違反としてエラーに
なります。
@c COMMON
@item XML-TOKEN
@c EN
A record with two slots, @var{kind} and @var{token}.
This record represents a markup, which is, according to the XML
Recommendation, "takes the form of start-tags, end-tags, empty-element tags,
entity references, character references, comments, CDATA section delimiters,
document type declarations, and processing instructions."
@c JP
@var{kind}と@var{token}という2つのスロットを持つレコードです。
このレコードは、XML勧告によれば、「開始タグ、終了タグ、空要素タグ、
実体参照、文字参照、コメント、CDATAセクションの区切り、
文書型宣言、処理命令の形を取る」マークアップを表します。
@c COMMON
@table @var
@item kind
@c EN
a @var{TAG-KIND}
@c JP
@var{TAG-KIND}。
@c COMMON
@item head
@c EN
an @var{UNRES-NAME}. For xml-tokens of kinds '@code{COMMENT} and
'@code{CDSECT}, the head is @code{#f}
@c JP
@var{UNRES-NAME}。'@code{COMMENT}と'@code{CDSECT}というkindのXMLトークンでは、
そのheadは@code{#f}になります。
@c COMMON
@end table

@c EN
For example,
@c JP
例を示します。
@c COMMON
@example
<P>  => kind='START, head='P
</P> => kind='END, head='P
<BR/> => kind='EMPTY-EL, head='BR
<!DOCTYPE OMF ...> => kind='DECL, head='DOCTYPE
<?xml version="1.0"?> => kind='PI, head='xml
&my-ent; => kind = 'ENTITY-REF, head='my-ent
@end example
@c EN
Character references are not represented by xml-tokens as these references
are transparently resolved into the corresponding characters.
@c JP
文字参照は、対応する文字へと透過的に解決されるので、XMLトークンとしては
表現されません。
@c COMMON
@item XML-DECL
@c EN
A record with three slots, @var{elems}, @var{entities}, and @var{notations}.

The record represents a datatype of an XML document: the list of
declared elements and their attributes, declared notations, list of
replacement strings or loading procedures for parsed general
entities, etc. Normally an xml-decl record is created from a DTD or
an XML Schema, although it can be created and filled in in many other
ways (e.g., loaded from a file).
@c JP
@var{elems}、@var{entities}、@var{notations}という3つのスロットを持つレコードです。

このレコードは、XML文書のデータタイプを表現します。それは、
宣言された要素とその属性のリスト、宣言された記法、
解析済み一般実体の置換文字列やロードされる手続きのリストなどです。
通常、xml-declレコードは、それを作るには他にたくさんの方法
(例えばファイルからロードするなど)があるにも関わらず、DTDかXML Schemaから
作られます。
@c COMMON

@c EN
@var{elems}: an (assoc) list of decl-elem or @code{#f}. The latter instructs
the parser to do no validation of elements and attributes.
@c JP
@var{elems}: decl-elemか@code{#f}の(連想)リスト。後者は、パーザに、
要素と属性の妥当性検査を行わないように指示します。
@c COMMON

@c EN
@var{decl-elem}: declaration of one element:
@code{(@var{elem-name} @var{elem-content} @var{decl-attrs})};
@var{elem-name} is an @var{UNRES-NAME} for the element.
@var{elem-content} is an @var{ELEM-CONTENT-MODEL}.
@var{decl-attrs} is an @var{ATTLIST},
of @code{(@var{attr-name} . @var{value})} associations.
This element can declare a user procedure to handle parsing of an
element (e.g., to do a custom validation, or to build a hash of
IDs as they're encountered).
@c JP
@var{decl-elem}: 1つの要素の宣言:
@code{(@var{elem-name} @var{elem-content} @var{decl-attrs})};
@var{elem-name}はその要素の@var{UNRES-NAME}。
@var{elem-content}は@var{ELEM-CONTENT-MODEL}。
@var{decl-attrs}は@var{ATTLIST}か、@code{(@var{attr-name} . @var{value})}の
連想リスト。
この要素は、要素のパージングを扱うユーザ手続きを宣言できます。
(例えば、カスタムな妥当性検査を行ったり、タグに出会うたびに
IDのハッシュを構築するなど。)
@c COMMON

@c EN
@var{decl-attr}: an element of an @var{ATTLIST}, declaration of one attribute
@code{(@var{attr-name} @var{content-type} @var{use-type} @var{default-value})}:
@var{attr-name} is an @var{UNRES-NAME} for the declared attribute;
@var{content-type} is a symbol: @code{CDATA}, @var{NMTOKEN}, @var{NMTOKENS}, ...;
or a list of strings for the enumerated type.
@var{use-type} is a symbol: @code{REQUIRED}, @code{IMPLIED}, @code{FIXED}
default-value is a string for the default value, or @code{#f} if not given.
@c JP
@var{decl-attr}: @var{ATTLIST}の要素で、1つの属性
@code{(@var{attr-name} @var{content-type} @var{use-type} @var{default-value})}
の宣言:
@var{attr-name}はその宣言された属性の@var{UNRES-NAME}、
@var{content-type}はシンボル@code{CDATA}、@var{NMTOKEN}、@var{NMTOKENS}、
あるいは列挙されたタイプの文字列のリスト。
@var{use-type}はシンボル@code{REQUIRED}、@code{IMPLIED}、@code{FIXED}。
default-valueは、デフォルト値としての文字列か、与えられなければ@code{#f}。
@c COMMON
@end table

@defun make-empty-attlist
@defunx attlist-add attlist name-value
@defunx attlist-null?
@defunx attlist-remove-top attlist
@defunx attlist->alist attlist
@defunx attlist-fold
@c EN
Utility procedures to deal with attribute list, which
keeps name-value association.
@c JP
名前-値の属性リストを扱うユーティリティ手続きです。
@c COMMON
@end defun

@defun make-xml-token kind head
@defunx xml-token? token
@c EN
A constructor and a predicate for a @var{XML-TOKEN} record.
@c JP
@var{XML-TOKEN}レコードのコンストラクタと述語です。
@c COMMON
@end defun

@defmac xml-token-kind token
@defmacx xml-token-head token
@c EN
Accessor macros of a @var{XML-TOKEN} record.
@c JP
@var{XML-TOKEN}レコードのアクセッサマクロです。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node SSAX low-level parsing code, SSAX higher-level parsers and scanners, SSAX data types, Functional XML parser
@subsection SSAX low-level parsing code
@c NODE SSAXの低レベルパージングコード

@c EN
They deal with primitive lexical units (Names, whitespaces, tags)
and with pieces of more generic productions. Most of these parsers
must be called in appropriate context. For example, @code{ssax:complete-start-tag}
must be called only when the start-tag has been detected and its @code{GI}
has been read.
@c JP
これらは、プリミティブな字句解析ユニット(名前、空白、タグ)や、
より一般的な断片を扱います。
これらのパーザのほとんどは、適切なコンテキストで呼ばれなければなりません。
例えば、@code{ssax:complete-start-tag}は、開始タグが検知されその@code{GI}が
読み込まれたときにのみ呼ばれなければなりません。
@c COMMON

@defun ssax:skip-S port
@c EN
Skip the S (whitespace) production as defined by
@c JP
次のように定義されるS(空白)をスキップします。
@c COMMON
@example
 [3] S ::= (#x20 | #x9 | #xD | #xA)
@end example
@c EN
The procedure returns the first not-whitespace character it
encounters while scanning the @var{port}. This character is left
on the input stream.
@c JP
この手続きは、@var{port}のスキャン中に遭遇した最初の空白ではない文字を
返します。この文字は、入力ストリームに残されます。
@c COMMON
@end defun

@defun ssax:ncname-starting-char? a-char
@c EN
Check to see if a-char may start a @code{NCName}.
@c JP
@code{NCName}がa-charで始まるかどうかを検査します。
@c COMMON
@end defun

@defun ssax:read-NCName port
@c EN
Read a @code{NCName} starting from the current position in the @var{port} and
return it as a symbol.
@c JP
@var{port}で現在の位置から始まる@code{NCName}を読み込み、それをシンボルとして
返します。
@c COMMON
@end defun

@defun ssax:read-QName port
@c EN
Read a (namespace-) Qualified Name, @code{QName}, from the current
position in the @var{port}.

From REC-xml-names:
@c JP
(名前空間)完全修飾名、@code{QName}を@var{port}の現在の位置から読み込みます。

REC-xml-namesは、
@c COMMON
@example
 [6] QName ::= (Prefix ':')? LocalPart
 [7] Prefix ::= NCName
 [8] LocalPart ::= NCName
@end example

@c EN
Return: an @var{UNRES-NAME}.
@c JP
戻り値は、@var{UNRES-NAME}です。
@c COMMON
@end defun

@defvar ssax:Prefix-XML
@c EN
The prefix of the pre-defined XML namespace, i.e. '@code{xml}.
@c JP
定義済みのXML名前空間の接頭辞、つまり、'@code{xml}です。
@c COMMON
@end defvar

@defun ssax:read-markup-token port
@c EN
This procedure starts parsing of a markup token. The current position
in the stream must be @code{#\<}. This procedure scans enough of the input stream
to figure out what kind of a markup token it is seeing. The procedure returns
an xml-token structure describing the token. Note, generally reading
of the current markup is not finished! In particular, no attributes of
the start-tag token are scanned.

Here's a detailed break out of the return values and the position in the @var{port}
when that particular value is returned:
@c JP
この手続きは、マークアップトークンのパージングを開始します。
ストリームの現在の位置は、@code{#\<}でなければなりません。
この手続きは、見ているマークアップトークンがどの種類のものか見当を
つけるに十分な程度、入力ストリームをスキャンします。
この手続きは、そのトークンを表現するxml-token構造を返します。
通常、その時点のマークアップの読み込みは完了していないことに注意して下さい。
特に、開始タグトークンの属性はスキャンされていません。

特定の値が返されたときの戻り値と@var{port}での位置を詳細に説明します。
@c COMMON
@table @code
@item PI-token
@c EN
only @code{PI}-target is read.
To finish the Processing Instruction and disregard it,
call @code{ssax:skip-pi}. @code{ssax:read-attributes} may be useful
as well (for @code{PI}s whose content is attribute-value
pairs)
@c JP
@code{PI}ターゲットのみが読み込まれました。
処理命令の読み込みを完了してそれを無視するためには、@code{ssax:skip-pi}を呼びます。
(@code{PI}の内容が、属性-値のペアの場合は、)@code{ssax:read-attributes}も
便利です。
@c COMMON
@item END-token
@c EN
The end tag is read completely; the current position
is right after the terminating @code{#\>} character.
@c JP
終了タグが完全に読み込まれました。
現在の位置は、終了の@code{#\>}文字の直後です。
@c COMMON
@item COMMENT
@c EN
is read and skipped completely. The current position
is right after "@code{-->}" that terminates the comment.
@c JP
コメントが完全に読み込まれスキップされました。
現在の位置は、コメントが終了する``@code{-->}''の直後です。
@c COMMON
@item CDSECT
@c EN
The current position is right after "@code{<!CDATA[}".
Use @code{ssax:read-cdata-body} to read the rest.
@c JP
現在の位置は、"@code{<!CDATA[}"の直後です。
残りを読むためには、@code{ssax:read-cdata-body}を使います。
@c COMMON
@item DECL
@c EN
We have read the keyword (the one that follows "@code{<!}")
identifying this declaration markup. The current
position is after the keyword (usually a
whitespace character)
@c JP
この宣言マークアップを識別するキーワード(``@code{<!}''に続くもの)を
読み込んだところです。現在の位置は、(通常は空白文字である)
そのキーワードの直後です。
@c COMMON
@item START-token
@c EN
We have read the keyword (@code{GI}) of this start tag.
No attributes are scanned yet. We don't know if this
tag has an empty content either.
Use @code{ssax:complete-start-tag} to finish parsing of
the token.
@c JP
この開始タグのキーワード(@code{GI})を読み込んだところです。
属性はまだスキャンされていません。
また、このタグが空の要素を持つかどうかも分かりません。
このトークンのパージングを終了するためには、
@code{ssax:complete-start-tag}を使います。
@c COMMON
@end table
@end defun

@defun ssax:skip-pi port
@c EN
The current position is inside a @code{PI}. Skip till the rest of the @code{PI}.
@c JP
現在の位置は、@code{PI}の内側です。
@code{PI}の残りをスキップします。
@c COMMON
@end defun

@defun ssax:read-pi-body-as-string port
@c EN
The current position is right after reading the @code{PITarget}. We read the
body of @code{PI} and return it as a string. The port will point to the
character right after '@code{?>}' combination that terminates @code{PI}.
@c JP
現在の位置は、@code{PITarget}を読み込んだ直後です。
@code{PI}のボディを読み込んで、それを文字列として返します。
ポートでは、@code{PI}を終了する'@code{?>}'の直後の文字を指します。
@c COMMON
@example
 [16] PI ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
@end example
@end defun

@defun ssax:skip-internal-dtd port
@c EN
The current pos in the port is inside an internal DTD subset
(e.g., after reading @code{#\[ }that begins an internal DTD subset)
Skip until the "@code{]>}" combination that terminates this DTD
@c JP
ポートでの現在の位置は、内部DTDサブセットの内側です
(例えば、内部DTDサブセットの始まりである@code{#\[ }を読み込んだところ)。
このDTDを終了する、組み合わせとなる``@code{]>}''までをスキップします。
@c COMMON
@end defun

@defun ssax:read-cdata-body port str-handler seed
@c EN
This procedure must be called after we have read a string "@code{<![CDATA[}"
that begins a @code{CDATA} section. The current position must be the first
position of the @code{CDATA} body. This function reads @emph{lines} of the @code{CDATA}
body and passes them to a @var{STR-HANDLER}, a character data consumer.
@c JP
この手続きは、@code{CDATA}セクションを開始する文字列、"@code{<![CDATA[}"を
読み込んだ後に呼ばれなければなりません。
現在の位置は、@code{CDATA}のボディの最初の位置です。
この手続きは、@code{CDATA}のボディの@emph{データ}を読み込み、それらを
@var{STR-HANDLER}(文字データのコンシューマ)へ渡します。
@c COMMON

@c EN
The str-handler is a @var{STR-HANDLER}, a procedure @code{string1} @var{string2} @var{seed}.
The first @var{string1} argument to @var{STR-HANDLER} never contains a newline.
The second @var{string2} argument often will. On the first invocation of
the @var{STR-HANDLER}, the seed is the one passed to @code{ssax:read-cdata-body}
as the third argument. The result of this first invocation will be
passed as the seed argument to the second invocation of the line
consumer, and so on. The result of the last invocation of the
@var{STR-HANDLER} is returned by the @code{ssax:read-cdata-body}.  Note a
similarity to the fundamental '@code{fold}' iterator.
@c JP
str-handlerは、@code{string1} @var{string2} @var{seed}を取る手続き
@var{STR-HANDLER}です。
@var{STR-HANDLER}の最初の引数@var{string1}は、改行を含みません。
2番目の引数@var{string2}は、改行を含むことがよくあります。
@var{STR-HANDLER}の最初の呼び出しでは、seedは@code{ssax:read-cdata-body}の
第3引数として渡されるものです。
この最初の呼び出しの結果は、文字データのコンシューマの引数seedとして渡され、
以降同じように続きます。
@var{STR-HANDLER}の最後の呼び出しの結果は、@code{ssax:read-cdata-body}
から返されるものです。
基本的な'@code{fold}'イテレータに似ています。
@c COMMON

@c EN
Within a @code{CDATA} section all characters are taken at their face value,
with only three exceptions:
@c JP
@code{CDATA}セクションでは、以下の3つだけの例外を除いて、全ての文字は
その表面上の値を持ちます。
@c COMMON
@itemize @bullet
@item
@c EN
@code{CR}, @code{LF}, and @code{CRLF} are treated as line delimiters, and passed
as a single @code{#\newline} to the @var{STR-HANDLER}.
@c JP
@code{CR}、@code{LF}、@code{CRLF}は行区切りとして扱われ、@var{STR-HANDLER}へは
1つの@code{#\newline}として渡されます。
@c COMMON
@item
@c EN
"@code{]]>}" combination is the end of the @code{CDATA} section.
@c JP
組み合わせとなる``@code{]]>}''は、@code{CDATA}セクションの終わりであると
されます。
@c COMMON
@item
@c EN
@code{&gt;} is treated as an embedded @code{#\>} character.
Note, @code{&lt;} and @code{&amp;} are not specially recognized (and are not expanded)!
@c JP
@code{&gt;}は、@code{#\>}文字の埋め込みとして扱われます。
@code{&lt;}と@code{&amp;}は特別なものとして認識されない(よって展開されない)ことに
注意が必要です!
@c COMMON
@end itemize
@end defun

@defun ssax:read-char-ref port
@example
 [66]  CharRef ::=  '&#' [0-9]+ ';' 
                  | '&#x' [0-9a-fA-F]+ ';'
@end example
@c EN
This procedure must be called after we we have read "@code{&#}" 
that introduces a char reference.
The procedure reads this reference and returns the corresponding char.
The current position in @var{port} will be after "@code{;}" that terminates
the char reference.
Faults detected: @code{WFC: XML-Spec.html#wf-Legalchar}.
@c JP
この手続きは、文字参照を表す``@code{&#}''を読み込んだ後に呼ばれなければ
なりません。
この手続きは、この参照を読み込んで対応する文字を返します。
@var{port}での現在の位置は、文字参照の終わりとなる``@code{;}''の後と
なります。
@code{WFC: XML-Spec.html#wf-Legalchar}も参照のこと。
@c COMMON

@c EN
According to Section "4.1 Character and Entity References"
of the XML Recommendation:
@c JP
XML勧告のセクション``4.1 文字と実体参照''によると、
@c COMMON
@quotation
@c EN
"[Definition: A character reference refers to a specific character
 in the ISO/IEC 10646 character set, for example one not directly
 accessible from available input devices.]"
@c JP
``[定義: 文字参照は、ISO/IEC 10646文字セットにある特定の文字を参照する。
例えば、利用できる入力デバイスからは直接アクセスできないものなど。]''
@c COMMON
@end quotation
@c EN
Therefore, we use a @code{ucscode->char} function to convert a character
code into the character -- @emph{regardless} of the current character
encoding of the input stream.
@c JP
したがって、入力ストリームの現在の文字エンコーディングに@emph{関係なく}、
文字コードを文字に変換するために関数@code{ucscode->char}を使います。
@c COMMON
@end defun

@defun ssax:handle-parsed-entity port name entities content-handler str-handler seed
@c EN
Expand and handle a parsed-entity reference
@c JP
解析済み実体参照を展開し処理します。
@c COMMON
@itemize @bullet
@item
@c EN
@var{port} - a PORT
@c JP
@var{port} - ポート
@c COMMON
@item
@c EN
@var{name} - the name of the parsed entity to expand, a symbol.
@c JP
@var{name} - 展開する解析済み実体の名前。シンボル。
@c COMMON
@item
@c EN
@var{entities} - see @var{ENTITIES}
@c JP
@var{entities} - @var{ENTITIES}を参照。
@c COMMON
@item
@c EN
@var{content-handler} - procedure @var{port} @var{entities} @var{seed}
that is supposed to return a @var{seed}.
@c JP
@var{content-handler} - @var{port} @var{entities} @var{seed}を取る手続きで、
@var{seed}を返す。
@c COMMON
@item
@c EN
@var{str-handler} - a @var{STR-HANDLER}. It is called if the entity in question
turns out to be a pre-declared entity
@c JP
@var{str-handler} - @var{STR-HANDLER}。対象となる実体が宣言済み実体となった
場合に呼ばれる。
@c COMMON
@end itemize
@c EN
The result is the one returned by @var{content-handler} or @var{str-handler}.
@c JP
戻り値は、@var{content-handler}か@var{str-handler}から返された値です。
@c COMMON

@c EN
Faults detected:
@c JP
こちらも参照のこと。
@c COMMON
@example
  WFC: XML-Spec.html#wf-entdeclared
  WFC: XML-Spec.html#norecursion
@end example
@end defun

@defun ssax:read-attributes port entities
@c EN
This procedure reads and parses a production @code{Attribute*}
@c JP
この手続きは、@code{Attribute*}を読み込みパーズします。
@c COMMON
@example
 [41] Attribute ::= Name Eq AttValue
 [10] AttValue ::=  '"' ([^<&"] | Reference)* '"' 
                 | "'" ([^<&'] | Reference)* "'"
 [25] Eq ::= S? '=' S?
@end example
@c EN
The procedure returns an @var{ATTLIST}, of @var{Name} (as @var{UNRES-NAME}),
@var{Value} (as string) pairs.
The current character on the @var{port} is a non-whitespace character
that is not an ncname-starting character.
@c JP
この手続きは、@var{Name}(@var{UNRES-NAME})と@var{Value}(文字列)のペアである
@var{ATTLIST}を返します。
@var{port}での現在の文字は、NCNameの開始文字ではなく、空白ではない文字です。
@c COMMON

@c EN
Note the following rules to keep in mind when reading an 'AttValue'
"Before the value of an attribute is passed to the application
or checked for validity, the XML processor must normalize it as follows:
@c JP
'AttValue'を読み込むときには、以下のルールに留意して下さい。
``属性の値がアプリケーションに渡されるか妥当性が検査される前に、
XMLプロセッサはそれを以下のように正規化しなければならない:
@c COMMON
@itemize @bullet
@item
@c EN
a character reference is processed by appending the referenced
character to the attribute value
@c JP
文字参照は、属性値に参照された文字を追加することで処理される。
@c COMMON
@item
@c EN
an entity reference is processed by recursively processing the
replacement text of the entity [see @var{ENTITIES}]
[named entities amp lt gt quot apos are assumed pre-declared]
@c JP
実体参照は、その実体のテキストの置換を再帰的に行うことにより
処理される。[@var{ENTITIES}参照] [名前付きのエンティティ、amp lt gt
quot aposは定義済みと想定される]
@c COMMON
@item
@c EN
a whitespace character (@code{#x20}, @code{#xD}, @code{#xA}, @code{#x9}) is processed by appending @code{#x20}
to the normalized value, except that only a single @code{#x20} is appended for a
"@code{#xD#xA}" sequence that is part of an external parsed entity or the
literal entity value of an internal parsed entity
@c JP
空白文字(@code{#x20}、@code{#xD}、@code{#xA}、@code{#x9})は、
外部解析済み実体か内部解析済み実体のリテラルの実体の値の一部である
``@code{#xD#xA}''のシーケンスにただ1つの@code{#x20}が追加されることを
除いて、正規化された値に@code{#x20}を追加することで処理される。
@c COMMON
@item
@c EN
other characters are processed by appending them to the normalized value "
@c JP
他の文字は、正規化された値をそれらに追加することにより処理される''
@c COMMON
@end itemize

@c EN
Faults detected:
@c JP
こちらも参照のこと。
@c COMMON
@example
 WFC: XML-Spec.html#CleanAttrVals
 WFC: XML-Spec.html#uniqattspec
@end example
@end defun

@defun ssax:resolve-name port unres-name namespaces apply-default-ns?
@c EN
Convert an @var{unres-name} to a @var{res-name} given the appropriate @var{namespaces}
declarations.
The last parameter @var{apply-default-ns?} determines if the default
namespace applies (for instance, it does not for attribute names)

Per @code{REC-xml-names/#nsc-NSDeclared}, "xml" prefix is considered pre-declared
and bound to the namespace name "@url{http://www.w3.org/XML/1998/namespace}".

This procedure tests for the namespace constraints:
@url{http://www.w3.org/TR/REC-xml-names/#nsc-NSDeclared}.
@c JP
与えられた適切な@var{namespaces}の宣言を用いて、@var{unres-name}を
@var{res-name}に変換する。
最後の引数@var{apply-default-ns?}は、デフォルト名前空間の適用を行うか
どうかを決めます(例えば、属性名には適用しないなど)。

@code{REC-xml-names/#nsc-NSDeclared}によれば、接頭辞``xml''は
名前空間名``@url{http://www.w3.org/XML/1998/namespace}''に定義済みで束縛されていると
されます。

この手続きは、名前空間の制約をテストします:
@url{http://www.w3.org/TR/REC-xml-names/#nsc-NSDeclared}。
@c COMMON
@end defun

@defun ssax:uri-string->symbol uri-str
@c EN
Convert a @var{uri-str} to an appropriate symbol.
@c JP
@var{uri-str}を適切なシンボルに変換します。
@c COMMON
@end defun

@defun ssax:complete-start-tag tag port elems entities namespaces
@c EN
This procedure is to complete parsing of a start-tag markup. The
procedure must be called after the start tag token has been
read. @var{Tag} is an @var{UNRES-NAME}.
@var{Elem
s} is an instance of @code{xml-decl::elems};
it can be @code{#f} to tell the function to do @emph{no} validation of elements
and their attributes.
@c JP
この手続きは、開始タグのマークアップのパージングを完了するためのものです。
この手続きは、開始タグトークンが読み込まれた後に呼ばれなければなりません。
@var{tag}は@var{UNRES-NAME}です。
@var{elems}は@code{xml-decl::elems}のインスタンスで、
手続きに、要素とそれらの属性の妥当性検査を@emph{行わない}ように
指示するために、@code{#f}を指定することができます。
@c COMMON

@c EN
This procedure returns several values:
@c JP
この手続きはいくつかの値を返します。
@c COMMON
@table @var
@item elem-gi
@c EN
a @var{RES-NAME}.
@c JP
@var{RES-NAME}。
@c COMMON
@item attributes
@c EN
element's attributes, an @var{ATTLIST} of @code{(@var{res-name} . @var{string})}
pairs. The list does @emph{not} include @code{xmlns} attributes.
@c JP
要素の属性。@code{(@var{res-name} . @var{string})}というペアの@var{ATTLIST}。
このリストは、@code{xmlns}属性を@emph{含みません}。
@c COMMON
@item namespaces
@c EN
the input list of namespaces amended with namespace
(re-)declarations contained within the start-tag under parsing
@var{ELEM-CONTENT-MODEL}.
@c JP
パージング中の開始タグに含まれる名前空間(再)宣言により修正された後の
名前空間の入力リスト。
@c COMMON
@end table

@c EN
On exit, the current position in @var{port} will be the first character after
@code{#\>} that terminates the start-tag markup.
@c JP
終了時の@var{port}での現在の位置は、開始タグのマークアップを終了する
@code{#\>}の後になります。
@c COMMON

@c EN
Faults detected:
@c JP
こちらも参照のこと。
@c COMMON
@example
 VC: XML-Spec.html#enum 
 VC: XML-Spec.html#RequiredAttr
 VC: XML-Spec.html#FixedAttr
 VC: XML-Spec.html#ValueType
 WFC: XML-Spec.html#uniqattspec (after namespaces prefixes are resolved)
 VC: XML-Spec.html#elementvalid 
 WFC: REC-xml-names/#dt-NSName
@end example

@c EN
Note, although XML Recommendation does not explicitly say it,
@var{xmlns} and @var{xmlns:} attributes don't have to be declared (although they
can be declared, to specify their default value).
@c JP
XML勧告では明示されていませんが、@var{xmlns}と@var{xmlns:}属性は、
(そのデフォルト値を指定するために宣言されることが出来ますが)
宣言される必要がないことに注意して下さい。
@c COMMON
@end defun

@defun ssax:read-external-id port
@c EN
This procedure parses an @code{ExternalID} production.
@c JP
この手続きは、@code{ExternalID}をパーズします。
@c COMMON
@example
 [75] ExternalID ::= 'SYSTEM' S SystemLiteral
                 | 'PUBLIC' S PubidLiteral S SystemLiteral
 [11] SystemLiteral ::= ('"' [^"]* '"') | ("'" [^']* "'") 
 [12] PubidLiteral ::=  '"' PubidChar* '"' | "'" (PubidChar - "'")* "'"
 [13] PubidChar ::=  #x20 | #xD | #xA | [a-zA-Z0-9]
                | [-'()+,./:=?;!*#@@$_%]
@end example
@c EN
This procedure is supposed to be called when an @code{ExternalID} is expected;
that is, the current character must be either @code{#\S} or @code{#\P} that start
correspondingly a @code{SYSTEM} or @code{PUBLIC} token. This procedure returns the
@code{SystemLiteral} as a string. A @code{PubidLiteral} is disregarded if present.
@c JP
この手続きは、@code{ExternalID}が期待されるところで呼ばれます。
つまり、現在の文字は、それぞれ@code{SYSTEM}か@code{PUBLIC}トークンを開始する
@code{#\S}か@code{#\P}でなければなりません。
この手続きは、@code{SystemLiteral}を文字列として返します。
@code{PubidLiteral}は、存在したとしても無視されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SSAX higher-level parsers and scanners, SSAX Highest-level parsers - XML to SXML, SSAX low-level parsing code, Functional XML parser
@subsection SSAX higher-level parsers and scanners
@c NODE SSAXの高レベルのパーザとスキャナ

@c EN
They parse productions corresponding to the whole (document) entity
or its higher-level pieces (prolog, root element, etc).
@c JP
これらは、全体的な実体(ドキュメント)あるいはその高レベルな断片
(プロローグ、ルート要素など)をパーズします。
@c COMMON

@defun ssax:scan-Misc port
@c EN
Scan the @code{Misc} production in the context:
@c JP
そのコンテキストでの@code{Misc}をスキャンします。
@c COMMON
@example
[1]  document ::=  prolog element Misc*
[22] prolog ::= XMLDecl? Misc* (doctypedec l Misc*)?
[27] Misc ::= Comment | PI |  S
@end example
@c EN
The following function should be called in the prolog or epilog contexts.
In these contexts, whitespaces are completely ignored.
The return value from @code{ssax:scan-Misc} is either a @code{PI}-token,
a @code{DECL}-token, a @code{START} token, or EOF.
Comments are ignored and not reported.
@c JP
以下の関数は、プロローグかエピローグのコンテキストで呼ばれます。
これらのコンテキストでは、空白文字は完全に無視されます。
@code{ssax:scan-Misc}からの戻り値は、@code{PI}トークンか@code{DECL}トークン、
@code{START}トークン、EOFのいずれかです。
コメントは無視され報告されません。
@c COMMON
@end defun

@defun ssax:read-char-data port expect-eof? str-handler seed
@c EN
This procedure is to read the character content of an XML document
or an XML element.
@c JP
この手続きは、XML文書かXML要素の文字内容を読むためのものです。
@c COMMON
@example
 [43] content ::= 
        (element | CharData | Reference | CDSect | PI
         | Comment)*
@end example
@c EN
To be more precise, the procedure reads @code{CharData}, expands @code{CDSect}
and character entities, and skips comments. The procedure stops
at a named reference, EOF, at the beginning of a @code{PI} or a start/end tag.
@c JP
具体的には、この手続きは@code{CharData}を読み込み、@code{CDSect}と
文字実体を展開し、コメントをスキップします。
この手続きは、名前付き参照、EOF、@code{PI}あるいは開始/終了タグの開始地点で
停止します。
@c COMMON

@table @var
@item port
@c EN
a port to read
@c JP
読み込むポート。
@c COMMON
@item expect-eof?
@c EN
a boolean indicating if EOF is normal, i.e., the character
data may be terminated by the EOF. EOF is normal
while processing a parsed entity.
@c JP
EOFがノーマルかどうか、つまり、文字データがEOFで終わるかどうかを
表す真偽値。解析済み実体を処理している間はEOFはノーマル。
@c COMMON
@item str-handler
@c EN
a @var{STR-HANDLER}.
@c JP
@var{STR-HANDLER}。
@c COMMON
@item seed
@c EN
an argument passed to the first invocation of @var{STR-HANDLER}.
@c JP
@var{STR-HANDLER}の最初の呼び出し時に渡される引数。
@c COMMON
@end table

@c EN
The procedure returns two results: @var{seed} and @var{token}.

The @var{seed} is the result of the last invocation of @var{str-handler}, or the
original seed if @var{str-handler} was never called.
@c JP
この手続きは2つの結果、@var{seed}と@var{token}を返します。

@var{seed}は@var{str-handler}の最後の呼び出しの結果、あるいは
@var{str-handler}が一度も呼ばれなかった場合はオリジナルのseedです。
@c COMMON

@c EN
@var{Token} can be either an eof-object (this can happen only if
@var{expect-eof?} was @code{#t}), or:
@c JP
@var{token}はEOFオブジェクト(これは@var{expect-eof?}が@code{#t}の場合のみ)か、
@c COMMON
@itemize @bullet
@item
@c EN
an xml-token describing a @var{START} tag or an @var{END}-tag;
For a start token, the caller has to finish reading it.
@c JP
@var{START}タグか@var{END}タグを表すxml-token。
開始トークンの場合は、呼び出し側が読み込みを完了する必要がある。
@c COMMON
@item
@c EN
an xml-token describing the beginning of a @code{PI}. It's up to an
application to read or skip through the rest of this @code{PI};
@c JP
@code{PI}の開始を表すxml-token。
この@code{PI}の残りを読み込むかスキップするかはアプリケーションに
任される。
@c COMMON
@item
@c EN
an xml-token describing a named entity reference.
@c JP
名前付き実体参照を表すxml-token。
@c COMMON
@end itemize

@c EN
@code{CDATA} sections and character references are expanded inline and
never returned. Comments are silently disregarded.

As the XML Recommendation requires, all whitespace in character data
must be preserved. However, a @code{CR} character (@code{#xD}) must be disregarded
if it appears before a @code{LF} character (@code{#xA}), or replaced by a @code{#xA} character
otherwise. See Secs. 2.10 and 2.11 of the XML Recommendation. See also
the canonical XML Recommendation.
@c JP
@code{CDATA}セクションと文字参照はインラインで展開され返されません。
コメントは無視されます。

XML勧告が要求するように、文字データ中の全ての空白文字は保存されなければなりません。
しかし、@code{CR}文字(@code{#xD})は、@code{LF}文字(@code{#A})の前に現れるか
@code{#xA}文字で置き換えられた場合は、無視されなければなりません。
XML勧告のセクション2.10と2.11を参照して下さい。
また、正規のXML勧告も参照して下さい。
@c COMMON
@end defun

@defun ssax:assert-token token kind gi error-cont
@c EN
Make sure that @var{token} is of anticipated @var{kind} and has anticipated @var{gi}.
Note @var{gi} argument may actually be a pair of two symbols, Namespace
URI or the prefix, and of the localname.
If the assertion fails, @var{error-cont} is evaluated by passing it
three arguments: @var{token} @var{kind} @var{gi}.
The result of @var{error-cont} is returned.
@c JP
@var{token}が、予想された@var{kind}のもので、予想された@var{gi}を
持つことを確認します。@var{gi}引数は、実際には2つのシンボル、
名前空間URIかその接頭辞と、そのローカル名のペアでしょう。
アサーションが失敗したら、@var{error-cont}に3つの引数、@var{token} @var{kind} @var{gi}
を渡されて評価されます。
@var{error-cont}の結果が返されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SSAX Highest-level parsers - XML to SXML,  , SSAX higher-level parsers and scanners, Functional XML parser
@subsection SSAX Highest-level parsers - XML to SXML
@c NODE SSAXの高レベルのパーザ - XMLからSXMLへ

@c EN
These parsers are a set of syntactic forms to instantiate a SSAX parser.
A user can instantiate the parser to do the full validation, or
no validation, or any particular validation. The user specifies
which @code{PI} he wants to be notified about. The user tells what to do
with the parsed character and element data. The latter handlers
determine if the parsing follows a SAX or a DOM model.
@c JP
これらのパーザは、SSAXパーザをインスタンス化するための構文的フォームのセットです。
ユーザは、完全な妥当性検査、妥当性検査なし、特定の妥当性検査を行うために
このパーザをインスタンス化できます。
ユーザは、どの@code{PI}について通知されたいかを指定します。
ユーザは、解析済み文字と要素のデータで何をしたいかを知らせます。
後者のハンドラは、パージングがSAXやDOMモデルに従うかを決定します。
@c COMMON

@defmac ssax:make-pi-parser my-pi-handlers
@c EN
Create a parser to parse and process one Processing Element (@code{PI}).
@c JP
1つの処理命令(@code{PI})をパーズして処理するパーザを作ります。
@c COMMON

@c EN
@var{My-pi-handlers}:
An assoc list of pairs (@var{PI-TAG} . @var{PI-HANDLER})
where @var{PI-TAG} is an @var{NCName} symbol, the @code{PI} target, and
@var{PI-HANDLER} is a procedure @var{port} @var{pi-tag} @var{seed}
where @var{port} points to the first symbol after the @code{PI} target.
The handler should read the rest of the @code{PI} up to and including
the combination '@code{?>}' that terminates the @code{PI}. The handler should
return a new seed.
One of the @var{PI-TAG}s may be a symbol @code{*DEFAULT*}. The corresponding
handler will handle @code{PI}s that no other handler will. If the
@code{*DEFAULT*} @var{PI-TAG} is not specified,
@code{ssax:make-pi-parser} will make
one, which skips the body of the @code{PI}.
@c JP
@var{my-pi-handlers}:
(@var{PI-TAG} . @var{PI-HANDLER})のペアの連想リスト。
@var{PI-TAG}は@var{NCName}のシンボル、@code{PI}ターゲット。
@var{PI-HANDLER}は@var{port} @var{pi-tag} @var{seed}を引数とする手続きで、
@var{port}では@code{PI}ターゲットの後の最初のシンボルを指しています。
ハンドラは、@code{PI}を終了する組み合わせとなる'@code{?>}'を含む、
@code{PI}の残りを読み込みます。ハンドラは新しいseedを返します。
@var{PI-TAG}の1つは、シンボル@code{*DEFAULT*}でしょう。
これに対応するハンドラは、他のハンドラが扱わない@code{PI}を処理します。
@code{*DEFAULT*} @var{PI-TAG}が指定されていない場合は、
@code{ssax:make-pi-parser}は、@code{PI}のボディをスキップするパーザを
作ります。
@c COMMON

@c EN
The output of the @code{ssax:make-pi-parser} is a procedure
@var{port} @var{pi-tag} @var{seed},
that will parse the current @code{PI} accoding to user-specified handlers.
@c JP
@code{ssax:make-pi-parser}が返すのは、@var{port} @var{pi-tag} @var{seed}を
取る手続きで、ユーザ指定のハンドラに従い現在の@code{PI}をパーズします。
@c COMMON
@end defmac

@defmac ssax:make-elem-parser my-new-level-seed my-finish-element my-char-data-handler my-pi-handlers
@c EN
Create a parser to parse and process one element, including its
character content or children elements. The parser is typically
applied to the root element of a document.
@c JP
その文字内容や子要素をも含む１つの要素をパーズし処理するパーザを作ります。
このパーザは通常、ドキュメントのルート要素の適用されます。
@c COMMON

@table @var
@item my-new-level-seed
@c EN
procedure @var{elem-gi} @var{attributes} @var{namespaces} @var{expected-content} @var{seed} @*
where @var{elem-gi} is a @var{RES-NAME} of the element
about to be processed.
This procedure is to generate the seed to be passed
to handlers that process the content of the element.
@c JP
@var{elem-gi} @var{attributes} @var{namespaces} @var{expected-content} @var{seed} @*
を引数に取る手続きで、@var{elem-gi}は処理されようとしている要素の@var{RES-NAME}です。
この手続きは、要素の内容を処理するハンドラに渡されるseedを生成します。
@c COMMON
@c This is the function identified as 'fdown' in the denotational
@c semantics of the XML parser given in the title comments to this
@c file.

@item my-finish-element
@c EN
procedure @var{elem-gi} @var{attributes} @var{namespaces} @var{parent-seed} @var{seed} @*
This procedure is called when parsing of @var{elem-gi} is finished.
The @var{seed} is the result from the last content parser (or
from @var{my-new-level-seed} if the element has the empty content).
@var{Parent-seed} is the same seed as was passed to @var{my-new-level-seed}.
The procedure is to generate a seed that will be the result
of the element parser.
@c JP
@var{elem-gi} @var{attributes} @var{namespaces} @var{parent-seed} @var{seed} @*
を引数に取る手続きです。この手続きは、@var{elem-gi}のパージングが完了した時に
呼ばれます。
@var{seed}は、最後に呼ばれたパーザからの(あるいは、
要素が空要素であった場合は、@var{my-new-level-seed}からの)結果です。
@var{parent-seed}は、@var{my-new-level-seed}へ渡されたのと同じseedです。
この手続きは、パーザの結果となるseedを生成するためのものです。
@c COMMON
@c This is the function identified as 'fup' in the denotational
@c semantics of the XML parser given in the title comments to this
@c file.

@item my-char-data-handler
@c EN
A @var{STR-HANDLER}.
@c JP
@var{STR-HANDLER}。
@c COMMON

@item my-pi-handlers
@c EN
See @code{ssax:make-pi-handler} above.
@c JP
@code{ssax:make-pi-handler}を参照して下さい。
@c COMMON
@end table

@c EN
The generated parser is a:
procedure @var{start-tag-head} @var{port} @var{elems} @var{entities}
@var{namespaces} @var{preserve-ws?} @var{seed}. @*
The procedure must be called after the start tag token has been
read. @var{Start-tag-head} is an @var{UNRES-NAME} from the start-element tag.
@var{Elems} is an instance of @code{xml-decl::elems}.
See @code{ssax:complete-start-tag::preserve-ws?}
@c JP
生成されたパーザは:
@var{start-tag-head} @var{port} @var{elems} @var{entities} @var{namespaces}
@var{preserve-ws?} @var{seed} @*
を引数に取る手続きです。
この手続きは、開始タグのトークンが読み込まれた後に呼ばれなければなりません。
@var{start-tag-head}は要素の開始タグの@var{UNRES-NAME}です。
@var{elems}は@code{xml-decl::elems}のインスタンスです。
@code{ssax:complete-start-tag::preserve-ws?}も参照して下さい。
@c COMMON

@c EN
Faults detected:
@c JP
こちらも参照のこと。
@c COMMON
@example
 VC: XML-Spec.html#elementvalid 
 WFC: XML-Spec.html#GIMatch
@end example
@end defmac

@defmac ssax:make-parser user-handler-tag user-handler-proc ...
@c EN
Create an XML parser, an instance of the XML parsing framework.
This will be a SAX, a DOM, or a specialized parser depending
on the supplied user-handlers.

@var{user-handler-tag} is a symbol that identifies a procedural expression
that follows the tag. Given below are tags and signatures of the
corresponding procedures. Not all tags have to be specified. If some
are omitted, reasonable defaults will apply.
@c JP
XMLパージングフレームワークのインスタンスである、XMLパーザを作ります。
これは、提供されるユーザハンドラによって、SAX、DOM、あるいは特化された
パーザになります。

@var{user-handler-tag}はシンボルで、タグに続く手続き的な式を識別します。
以下にタグと対応する手続きのシグネチャを示します。
全てのタグが指定される必要はありません。
いくつかが省略されると、合理的なデフォルトのものが適用されます。
@c COMMON

@table @code
@item tag: @var{DOCTYPE}
@c EN
handler-procedure: @var{port} @var{docname} @var{systemid} @var{internal-subset?} @var{seed}

If @var{internal-subset?} is @code{#t}, the current position in the port
is right after we have read @code{#\[} that begins the internal DTD subset.
We must finish reading of this subset before we return
(or must call skip-internal-subset if we aren't interested in reading it).
The port at exit must be at the first symbol after the whole
DOCTYPE declaration.

The handler-procedure must generate four values: @*
@var{elems} @var{entities} @var{namespaces} @var{seed}@*
See @code{xml-decl::elems} for @var{elems}.
It may be @code{#f} to switch off the validation.
@var{namespaces} will typically contain @var{USER-PREFIX}es for selected @var{URI-SYMB}s.
The default handler-procedure skips the internal subset,
if any, and returns @code{(values #f '() '() seed)}.
@c JP
ハンドラ手続きの引数: @var{port} @var{docname} @var{systemid} @var{internal-subset?} @var{seed}

@var{internal-subset?}が@code{#t}なら、ポートでの現在の位置は内部DTDサブセットの
開始となる@code{#\[}を読んだ直後です。
手続きから戻る前に、このサブセットの残りの読み込みを完了しなければなりません
(あるいは、それを読むことに興味がなければ、skip-internal-subsetを呼ばなければなりません)。
終了時のポートでの位置は、DOCTYPE宣言全体のあとの最初のシンボルでなければなりません。

ハンドラ手続きは4つの値: @*
@var{elems} @var{entities} @var{namespaces} @var{seed} @*
を生成しなければなりません。
@var{elems}については、@code{xml-decl::elems}を参照して下さい。
妥当性検査をオフにするためには、@code{#f}になるでしょう。
@var{namespaces}は、通常、選択された@var{URI-SYMB}に対して@var{USER-PREFIX}を含む
でしょう。
デフォルトのハンドラ手続きは、内部サブセットがあってもそれをスキップし、
@code{(values #f '() '() seed)}を返します。
@c COMMON

@item tag: @var{UNDECL-ROOT}
@c EN
handler-procedure: @var{elem-gi} @var{seed} @*
where @var{elem-gi} is an @var{UNRES-NAME} of the root element. This procedure
is called when an XML document under parsing contains @emph{no} @code{DOCTYPE}
declaration.
The handler-procedure, as a DOCTYPE handler procedure above,
must generate four values: @*
@var{elems} @var{entities} @var{namespaces} @var{seed}@*
The default handler-procedure returns @code{(values #f '() '() seed)}.
@c JP
ハンドラ手続きの引数: @var{elem-gi} @var{seed} @*
@var{elem-gi}はルート要素の@var{UNRES-NAME}です。
この手続きは、パージング中のXML文書が@code{DOCTYPE}宣言を@emph{含まない}時に
呼ばれます。
ハンドラ手続きは、上ではDOCTYPEハンドラですが、4つの値: @*
@var{elems} @var{entities} @var{namespaces} @var{seed}@*
を生成しなければなりません。
デフォルトのハンドラ手続きは、@code{(values #f '() '() seed)}を返します。
@c COMMON

@item tag: @var{DECL-ROOT}
@c EN
handler-procedure: @var{elem-gi} @var{seed} @*
where @var{elem-gi} is an @var{UNRES-NAME} of the root element. This procedure
is called when an XML document under parsing does contains the @code{DOCTYPE}
declaration.
The handler-procedure must generate a new @code{seed} (and verify
that the name of the root element matches the doctype, if the handler
so wishes). 
The default handler-procedure is the identity function.
@c JP
ハンドラ手続きの引数: @var{elem-gi} @var{seed} @*
@var{elem-gi}は、ルート要素の@var{UNRES-NAME}です。
この手続きは、パージング中のXML文書が@code{DOCTYPE}宣言を含む場合に呼ばれます。
このハンドラ手続きは、新しい@code{seed}を生成しなければなりません
(そして、ハンドラが望めば、ルート要素の名前がDOCTYPEにマッチするかを
検証します)。
デフォルトのハンドラ手続きは、それ自身を返す手続きです。
@c COMMON

@item tag: @var{NEW-LEVEL-SEED}
@c EN
handler-procedure: see @code{ssax:make-elem-parser}, @var{my-new-level-seed}
@c JP
ハンドラ手続きの引数: @code{ssax:make-elem-parser}と@var{my-new-level-seed}を参照して下さい。
@c COMMON

@item tag: @var{FINISH-ELEMENT}
@c EN
handler-procedure: see @code{ssax:make-elem-parser}, @var{my-finish-element}
@c JP
ハンドラ手続きの引数: @code{ssax:make-elem-parser}と@var{my-finish-element}を参照して下さい。
@c COMMON

@item tag: @var{CHAR-DATA-HANDLER}
@c EN
handler-procedure: see @code{ssax:make-elem-parser}, @var{my-char-data-handler}
@c JP
ハンドラ手続きの引数: @code{ssax:make-elem-parser}と@var{my-char-data-handler}を参照して下さい。
@c COMMON

@item tag: @var{PI}
@c EN
handler-procedure: see @code{ssax:make-pi-parser}. @*
The default value is @code{'()}.
@c JP
ハンドラ手続きの引数: @code{ssax:make-pi-parser}を参照して下さい。@*
デフォルトの値は、@code{'()}です。
@c COMMON
@end table

@c EN
The generated parser is a @*
procedure @var{PORT} @var{SEED}

This procedure parses the document prolog and then exits to
an element parser (created by ssax:make-elem-parser) to handle
the rest.
@c JP
生成されるパーザは、@*
@var{PORT} @var{SEED}を取る手続き、@*
です。

この手続きは、ドキュメントのプロローグをパーズして、
その残りを処理するために(ssax:make-elem-parserで作られた)パーザへ
引き継いで終了します。
@c COMMON

@example
 [1]  document ::=  prolog element Misc*
 [22] prolog ::= XMLDecl? Misc* (doctypedec | Misc*)?
 [27] Misc ::= Comment | PI |  S

 [28] doctypedecl ::=  '<!DOCTYPE' S Name (S ExternalID)? S? 
                        ('[' (markupdecl | PEReference | S)* ']' S?)? '>'
 [29] markupdecl ::= elementdecl | AttlistDecl
                      | EntityDecl
                      | NotationDecl | PI
                      | Comment 
@end example
@end defmac

@c EN
A few utility procedures that turned out useful.
@c JP
いくつかの便利なユーティリティ手続きがあります。
@c COMMON

@defun ssax:reverse-collect-str fragments
@c EN
given the list of @var{fragments} (some of which are text strings)
reverse the list and concatenate adjacent text strings.
@c JP
@var{fragments}(そのいくつかはテキスト文字列)のリストを渡すと、
そのリストを逆順にして隣り合ったテキスト文字列を連結します。
@c COMMON
@end defun

@defun ssax:reverse-collect-str-drop-ws fragments
@c EN
given the list of fragments (some of which are text strings)
reverse the list and concatenate adjacent text strings.
We also drop "unsignificant" whitespace, that is, whitespace
in front, behind and between elements. The whitespace that
is included in character data is not affected.
We use this procedure to "intelligently" drop "insignificant"
whitespace in the parsed SXML. If the strict compliance with
the XML Recommendation regarding the whitespace is desired, please
use the @code{ssax:reverse-collect-str} procedure instead.
@c JP
fragments(そのいくつかはテキスト文字列)のリストを渡すと、
そのリストを逆順にして隣り合ったテキスト文字列を連結します。
``重要でない''空白文字、つまり、最初や最後、要素の間にある空白文字を
削除します。文字データに含まれる空白文字には影響を与えません。
この手続きは、パーズされたSXMLにある``重要でない''空白文字を
``知的に''削除するために使います。空白文字に関して、厳密に
XML勧告に準拠したい場合は、代わりに手続き
@code{ssax:reverse-collect-str}を使って下さい。
@c COMMON
@end defun

@defun ssax:xml->sxml port namespace-prefix-assig
@c EN
This is an instance of a SSAX parser above that returns an SXML
representation of the XML document to be read from @var{port}.
@var{Namespace-prefix-assig} is a list of
@code{(@var{USER-PREFIX} . @var{URI-STRING})}
that assigns @var{USER-PREFIX}es to certain namespaces identified by
particular @var{URI-STRING}s. It may be an empty list.
The procedure returns an SXML tree. The port points out to the
first character after the root element.
@c JP
これは、上のSSAXパーザのインスタンスで、@var{port}から読み込まれる
XMLドキュメントのSXML表現を返します。
@var{namespace-prefix-assig}は、@code{(@var{USER-PREFIX} . @var{URI-STRING})}
のリストで、特定の@var{URI-STRING}で識別されるある名前空間を
@var{USER-PREFIX}に割り当てます。これは空リストでも構いません。
この手続きは、SXMLツリーを返します。
ポートでの位置は、ルート要素の後の最初の文字を指します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXML Query Language, Manipulating SXML structure, Functional XML parser, Library modules - Utilities
@section @code{sxml.sxpath} - SXML Query Language
@c NODE SXMLクエリ言語, @code{sxml.sxpath} - SXMLクエリ言語

@deftp {Module} sxml.sxpath
@mdindex sxml.sxpath
@c EN
SXPath is a query language for SXML, an instance of XML Information
set (Infoset) in the form of s-expressions. 

It is originally written by Oleg Kiselyov, and
improved by Dmitry Lizorkin and Kirill Lisovsky.
This module also incorporates
various procedures written for SXPath by Dmitry Lizorkin and Kirill Lisovsky.

Current version is based on sxpathlib.scm,v 3.915,
sxpath.scm,v 1.1, and sxpath-ext.scm,v 1.911.
@c JP
SXPathは、XML Information set (Infoset)のインスタンスのS式フォームである
SXMLのためのクエリ言語です。

これは最初にOleg Kiselyovによって書かれ、Dmitry LizorkinとKirill Lisovsky
によって改良されました。
このモジュールにはまた、Dmitry LizorkinとKirill LisovskyによりSXPathのために
書かれたたくさんの手続きが盛り込まれています。

現在のバージョンは、sxpathlib.scm v3.915、sxpath.scm v1.1、sxpath-ext.scm v1.911を
ベースにしています。
@c COMMON
@end deftp

@c EN
This manual is mostly derived from the comments in the
original source files.

The module consists of three layers.
@c JP
このマニュアルは、そのほとんどがオリジナルのソースファイルのコメントより
導出されています。

このモジュールは3つのレイヤから構成されます。
@c COMMON
@enumerate
@item
@c EN
Basic converters and applicators, which provides the means to
access and translate SXML tree.
@c JP
SXMLツリーへのアクセスやその変換の手段を提供する基本的なコンバータや
アプリケータ(適用子)。
@c COMMON
@item
@c EN
High-level query language compiler,
which takes abbreviated SXPath and
returns a Scheme function that selects a nodeset
that satisfies the specified path from the given nodeset.
@c JP
省略形のSXPathを取り、与えられたノードセットから指定されたパスを満足する
ノードセットを選択するScheme関数を返す、高レベルなクエリ言語コンパイラ。
@c COMMON
@item
@c EN
Extension libraries, which implements
SXML counterparts to W3C XPath Core Functions Library.
@c JP
W3CのXPathコア関数ライブラリのSXML版を実装する拡張ライブラリ。
@c COMMON
@end enumerate

@c ----------------------------------------------------------------------
@menu
* SXPath basic converters and applicators::  
* SXPath query language::       
* SXPath extension::            
@end menu

@node SXPath basic converters and applicators, SXPath query language, SXML Query Language, SXML Query Language
@subsection SXPath basic converters and applicators
@c NODE SXPathの基本的なコンバータとアプリケータ

@c EN
A converter is a function
@c JP
コンバータは、以下を満たす関数です。
@c COMMON
@example
  type Converter = Node|Nodeset -> Nodeset
@end example
@c EN
A converter can also play a role of a predicate: in that case, if a
converter, applied to a node or a nodeset, yields a non-empty
nodeset, the converter-predicate is deemed satisfied. Throughout
this file a nil nodeset is equivalent to @code{#f} in denoting a failure.
@c JP
コンバータは、述語としての役割を担うこともあります。
その場合、コンバータが、ノードやノードセットに適用され、空ではないノードセットを
返す場合、述語としてのコンバータは満足したものとみなされます。
このファイルを通して、nilノードセットは失敗を表す@code{#f}と等価です。
@c COMMON

@defun nodeset? x
@c EN
Returns @code{#t} if given object is a nodeset.
@c JP
与えられたオブジェクトがノードセットならば、@code{#t}を返します。
@c COMMON
@end defun

@defun as-nodeset x
@c EN
If @var{x} is a nodeset - returns it as is, otherwise wrap it in a list.
@c JP
@var{x}がノードセットならば、それをそのまま返し、そうでなければそれを
リストでラップして返します。
@c COMMON
@end defun

@defun sxml:element? obj
@c EN
Predicate which returns @var{#t}
if @var{obj} is SXML element, otherwise returns @var{#f}.
@c JP
@var{obj}がSXMLの要素であれば@var{#t}を返し、そうでなければ@var{#f}を
返す述語です。
@c COMMON
@end defun

@defun ntype-names?? crit
@c EN
The function @code{ntype-names??} takes a list of acceptable node names as a
criterion and returns a function, which, when applied to a node, 
will return @code{#t} if the node name is present in criterion list
and @code{#f} othervise.
@c JP
関数@code{ntype-names??}は、判定基準として受け付け可能なノード名のリストを取り、
関数を返します。この関数は、ノードに適用された際、そのノード名が判定基準リストに
含まれていれば@code{#t}を、含まれていなければ@code{#f}を返す関数です。
@c COMMON
@example
 ntype-names?? :: ListOfNames -> Node -> Boolean
@end example
@end defun

@defun ntype?? crit
@c EN
The function @code{ntype??} takes a type criterion and returns
a function, which, when applied to a node, will tell if the node satisfies
the test.
@c JP
関数@code{ntype??}は、型に関する判定基準を取り、関数を返します。
この関数は、ノードに適用された際、そのノードがそのテストを満足するかを
返します。
@c COMMON
@example
  ntype?? :: Crit -> Node -> Boolean
@end example

@c EN
The criterion @var{crit} is 
one of the following symbols:
@c JP
判定基準@var{crit}は、以下のシンボルのうちの1つです。
@c COMMON
@table @code
@item id
@c EN
tests if the Node has the right name (id)
@c JP
そのノードが正しい名前(id)を持っているかをテストします。
@c COMMON
@item @@
@c EN
tests if the Node is an @var{attributes-list}.
@c JP
そのノードが@var{attributes-list}であるかをテストします。
@c COMMON
@item *
@c EN
tests if the Node is an @var{Element}.
@c JP
そのノードが@var{Element}であるかをテストします。
@c COMMON
@item *text*
@c EN
tests if the Node is a text node.
@c JP
そのノードがテキストノードであるかをテストします。
@c COMMON
@item *data*
@c EN
tests if the Node is a data node 
(text, number, boolean, etc., but not pair).
@c JP
そのノードがデータノード(テキスト、数値、真偽値などで、ペアではない)であるか
をテストします。
@c COMMON
@item *PI*
@c EN
tests if the Node is a @code{PI} node.
@c JP
そのノードが@code{PI}ノードであるかをテストします。
@c COMMON
@item *COMMENT*
@c EN
tests if the Node is a @code{COMMENT} node.
@c JP
そのノードが@code{COMMENT}ノードであるかをテストします。
@c COMMON
@item *ENTITY*
@c EN
tests if the Node is a @code{ENTITY} node.
@c JP
そのノードが@code{ENTITY}ノードであるかをテストします。
@c COMMON
@item *any*
@c EN
@code{#t} for any type of Node.
@c JP
どんなタイプのノードに対しても@code{#t}を返します。
@c COMMON
@end table
@end defun

@defun ntype-namespace-id?? ns-id
@c EN
This function takes a namespace-id, and returns a predicate
@code{Node -> Boolean}, which is @code{#t}
for nodes with this very namespace-id.
@var{ns-id} is a string.
@code{(ntype-namespace-id?? #f)} will be @code{#t}
for nodes with non-qualified names.
@c JP
この関数は、名前空間IDを取り、述語@code{Node -> Boolean}を
返します。この述語はまさにその名前空間IDを持つノードに対しては
@code{#t}を返します。@var{ns-id}は文字列です。
@code{(ntype-namespace-id?? #f)}は、完全修飾されていない名前を
持つノードに対して@code{#t}を返します。
@c COMMON
@end defun

@defun sxml:invert pred
@c EN
This function takes a predicate and returns it inverted .
That is if the given predicate yields @code{#f} or '@code{()} the inverted one  
yields the given node (@code{#t}) and vice versa.
@c JP
この関数は、述語を取り、それを反対にして返します。
与えられた述語が@code{#f}や'@code{()}を返す場合、反対にされたものは
与えられたノード(@code{#t})を返します。
@c COMMON
@end defun

@defun node-eq? other
@defunx node-equal? other
@c EN
Curried equivalence converter-predicates, i.e.
@c JP
等価な述語としてのコンパータにカリー化します。すなわち、
@c COMMON
@example
  ((node-eq? a) b)    @equiv{} (eq? a b)
  ((node-equal? a) b) @equiv{} (equal? a b)
@end example
@end defun

@defun node-pos n

@example
 node-pos:: N -> Nodeset -> Nodeset, or
 node-pos:: N -> Converter
@end example

@c EN
Select the @var{N}'th element of a Nodeset and return as a singular Nodeset;
Return an empty nodeset if the Nth element does not exist.
@code{((node-pos 1) Nodeset)} selects the node at the head of the Nodeset,
if exists;
@code{((node-pos 2) Nodeset)} selects the Node after that, if
exists.
@var{N} can also be a negative number: in that case the node is picked from
the tail of the list.
@code{((node-pos -1) Nodeset)} selects the last node of a non-empty nodeset;
@code{((node-pos -2) Nodeset)} selects the last but one node, if exists.
@c JP
ノードセットの@var{N}番目の要素を選択し、1つの要素を持つノードセットを返します。
N番目の要素が存在しなければ、空のノードセットを返します。
@code{((node-pos 1) Nodeset)}は、ノードセットの先頭ノードがあればそれを選択します。
@code{((node-pos 2) Nodeset)}は、2番目のノードがあればそれを選択します。
@var{N}は負の数でも構いません。その場合、ノードはリストの末尾から数えられます。
@code{((node-pos -1) Nodeset)}は、空ではないノードセットの最後のノードを選択します。
@code{((node-pos -2) Nodeset)}は、最後から2番目のノードがあればそれを選択します。
@c COMMON
@end defun

@defun sxml:filter pred?

@example
 filter:: Converter -> Converter
@end example

@c EN
A filter applicator, which introduces a filtering context. The argument
converter is considered a predicate, with either @code{#f}
or nil result meaning failure.
@c JP
フィルタリングを行う、フィルタアプリケータです。
引数のコンバータは、@code{#f}あるいはnilとなることが失敗を意味する述語と
みなされます。
@c COMMON
@end defun

@defun take-until pred?

@example
 take-until:: Converter -> Converter, or
 take-until:: Pred -> Node|Nodeset -> Nodeset
@end example

@c EN
Given a converter-predicate and a nodeset, apply the predicate to
each element of the nodeset, until the predicate yields anything but
@var{#f} or nil. Return the elements of the input nodeset that have
been processed
till that moment (that is, which fail the predicate).
@code{take-until} is a variation of the filter above:
@code{take-until} passes
elements of an ordered input set till (but not including) the first
element that satisfies the predicate.
The nodeset returned by @code{((take-until (not pred)) nset)} is a subset -- 
to be more precise, a prefix -- of the nodeset returned by
@code{((filter pred) nset)}.
@c JP
述語としてのコンバータとノードセットが与えられると、
ノードセットの各要素に述語を適用し、
述語が@var{#f}あるいはnil以外を返すと、
(その述語が失敗した)その時点までに処理された要素を返します。
@code{take-until}は、上のフィルタのバリエーションの1つです。
@code{take-until}は、その述語を満足する最初の要素(それ自体は含まない)まで、
順序付けられた入力のセットの要素をパスします。
@code{((take-until (not pred)) nset)}により返されるノードセットは、
@code{((filter pred) nset)}により返されるノードセットのサブセット
-- 具体的には接頭辞 --になります。
@c COMMON
@end defun

@defun take-after pred?

@example
take-after:: Converter -> Converter, or
take-after:: Pred -> Node|Nodeset -> Nodeset
@end example

@c EN
Given a converter-predicate and a nodeset, apply the predicate to
each element of the nodeset, until the predicate yields anything but
@code{#f} or
nil. Return the elements of the input nodeset that have not been processed:
that is, return the elements of the input nodeset that follow the first
element that satisfied the predicate.
@code{take-after} along with @code{take-until}
partition an input nodeset into three
parts: the first element that satisfies a predicate, all preceding
elements and all following elements.
@c JP
述語としてのコンバータとノードセットを与えると、
述語をノードセットの各要素に適用し、
述語が@code{#f}かnil以外を返すと、
まだ述語が適用されていない要素を返します。
つまり、述語を満足する最初の要素の後に続く要素を返します。
@code{take-after}と@code{take-until}を一緒に使うと、
入力のノードセットを3つのパート:
述語を満足する最初の要素、その要素の前の部分、その要素の後の部分に
分けます。
@c COMMON
@end defun

@defun map-union proc lst
@c EN
Apply proc to each element of lst and return the list of results.
If proc returns a nodeset, splice it into the result.

From another point of view,
@code{map-union} is a function Converter->Converter,
which places an argument-converter in a joining context.
@c JP
procをlstの各要素に適用し、結果のリストを返します。
procがノードセットを返す場合、それを結果につなぎ合わせます。

別の観点から見ると、@code{map-union}はConverter->Converter関数で、
結合を行いたいコンテキストでの引数としてのコンバータに
位置します。
@c COMMON
@end defun

@defun node-reverse node-or-nodeset

@example
node-reverse :: Converter, or
node-reverse:: Node|Nodeset -> Nodeset
@end example

@c EN
Reverses the order of nodes in the nodeset.
This basic converter is needed to implement a reverse document order
(see the XPath Recommendation).
@c JP
ノードセットでのノードの順番を逆順にします。
この基本的なコンバータは、逆順のドキュメントオーダーを実装するために
必要です。(XPath勧告を参照して下さい。)
@c COMMON
@end defun

@defun node-trace title

@example
 node-trace:: String -> Converter
@end example

@c EN
@code{(node-trace title)} is an identity converter. In addition it prints out
a node or nodeset it is applied to, prefixed with the 'title'.
This converter is very useful for debugging.
@c JP
@code{(node-trace title)}は、それ自身を返すコンバータです。
また、自身が適用されるノードやノードセットを、'title'という
プリフィックスを付けてプリントします。
このコンバータは、デバッグの際にとても便利です。
@c COMMON
@end defun

@c EN
What follow are Converter combinators,
higher-order functions that transmogrify a converter
or glue a sequence of converters into a single, non-trivial
converter. The goal is to arrive at converters that correspond to
XPath location paths.

From a different point of view, a combinator is a fixed, named
@emph{pattern} of applying converters. Given below is a complete set of
such patterns that together implement XPath location path
specification. As it turns out, all these combinators can be built
from a small number of basic blocks: regular functional composition,
map-union and filter applicators, and the nodeset union.
@c JP
コンバータの組み合わせに続くものは、コンバータを一変させる、
あるいはコンバータのシーケンスを1つの強力なコンバータにつなぎ合わせる
高階関数です。そのゴールは、XPathのロケーションパスに対応する
コンバータとなることです。

別の観点から見ると、コンバータは、コンバータ群の適用の固定され
名前の付いた@emph{パターン}とみなせます。
以下に挙げるのは、XPathのロケーションパスの仕様を実装する
そのようなパターンの完全なセットです。
結局のところ、これら全てのコンビネータはいくつかの基本的なブロック、
通常の関数的なコンポジション、map-unionとfilterアプリケータ、
ノードセットユニオンなどから構築することができます
@c COMMON

@defun select-kids test-pred?

@example
select-kids:: Pred -> Node -> Nodeset
@end example
@c EN
Given a Node, return an (ordered) subset its children that satisfy
the Pred (a converter, actually).
@c JP
ノードを与えると、述語(実際はコンバータ)を満足するその子要素の
(順序付けられた)サブセットを返します。
@c COMMON

@example
select-kids:: Pred -> Nodeset -> Nodeset
@end example
@c EN
The same as above, but select among children of all the nodes in
the Nodeset.
@c JP
上と同じですが、ノードセットの全てのノードの子要素から選択します。
@c COMMON
@end defun

@defun node-self pred

@example
 node-self:: Pred -> Node -> Nodeset, or
 node-self:: Converter -> Converter
@end example

@c EN
Similar to select-kids but apply to the Node itself rather
than to its children. The resulting Nodeset will contain either one
component, or will be empty (if the Node failed the Pred).
@c JP
select-kidsに似ていますが、自身をその子要素に適用するのでは
なく、ノードそれ自身に適用します。
結果のノードセットは、1つのコンポーネントを含むか、
空(ノードが述語を満足しない場合)になります。
@c COMMON
@end defun

@defun node-join . selectors

@example
 node-join:: [LocPath] -> Node|Nodeset -> Nodeset, or
 node-join:: [Converter] -> Converter
@end example

@c EN
join the sequence of location steps or paths as described
in the title comments above.
@c JP
上のタイトルコメントで説明されるようなロケーションステップ
あるいはロケーションパスのシーケンスをつなぎ合わせます。
@c COMMON
@end defun

@defun node-reduce . converters

@example
 node-reduce:: [LocPath] -> Node|Nodeset -> Nodeset, or
 node-reduce:: [Converter] -> Converter
@end example

@c EN
A regular functional composition of converters.
From a different point of view,
@code{((apply node-reduce converters) nodeset)}
is equivalent to
@code{(foldl apply nodeset converters)}
i.e., folding, or reducing, a list of converters with the nodeset
as a seed.
@c JP
コンバータの通常の関数的なコンポジションです。
見方を変えると、@code{((apply node-reduce converters) nodeset)}は
@code{(foldl apply nodeset converters)}と等価です。
すなわち、コンバータのリストをノードセットをseedとして畳み込みや分解
を行うようなものです。
@c COMMON
@end defun

@defun node-or . converters

@example
 node-or:: [Converter] -> Converter
@end example

@c EN
This combinator applies all converters to a given node and
produces the union of their results.
This combinator corresponds to a union, '@code{|}' operation for XPath
location paths.
@c JP
このコンビネータは、全てのコンバータを与えられたノードに適用し、
それらの結果のユニオンを作ります。
このコンビネータは、XPathのロケーションパスでの'@code{|}'オペレーション
であるユニオンに対応します。
@c COMMON
@end defun

@defun node-closure test-pred?

@example
 node-closure:: Converter -> Converter
@end example

@c EN
Select all @emph{descendants} of a node that satisfy a converter-predicate.
This combinator is similar to @code{select-kids} but applies to
grand... children as well.
This combinator implements the "@code{descendant::}" XPath axis.
Conceptually, this combinator can be expressed as
@c JP
述語としてのコンバータを満足するノードの全ての@emph{子孫}を選択します。
このコンビネータは@code{select-kids}に似ていますが、孫要素やその
子要素達にも適用を行います。
このコンビネータは、XPathの軸である``@code{descendant::}''を実装します。
概念的には、このコンビネータは以下のように表現することができます。
@c COMMON
@example
 (define (node-closure f)
      (node-or
        (select-kids f)
	 (node-reduce (select-kids (ntype?? '*)) (node-closure f))))
@end example

@c EN
This definition, as written, looks somewhat like a fixpoint, and it
will run forever.  It is obvious however that sooner or later
@code{(select-kids (ntype?? '*))} will return an empty nodeset. At
this point further iterations will no longer affect the result and
can be stopped.
@c JP
この定義は、字面の通り、フィックスポイントのような何かで、
永久に実行し続けます。しかし、いつかは@code{(select-kids (ntype?? '*))}
が空のノードセットを返すことは明白です。その時点では、以降の
イテレーションはその結果に影響を及ぼさず停止されることができます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXPath query language, SXPath extension, SXPath basic converters and applicators, SXML Query Language
@subsection SXPath query language
@c NODE SXPathクエリ言語

@defun sxpath abbrpath . ns-binding
Evaluates an abbreviated SXPath

@example
 sxpath:: AbbrPath -> Converter, or
 sxpath:: AbbrPath -> Node|Nodeset -> Nodeset
@end example

@c EN
@var{AbbrPath} is a list. It is translated to the full SXPath according
to the following rewriting rules:
@c JP
@var{AbbrPath}はリストです。これは、以下の書き換えルールに従って
完全なSXPathに変換されます。
@c COMMON
@example
 (sxpath '()) -> (node-join)
 (sxpath '(path-component ...)) ->
                (node-join (sxpath1 path-component) (sxpath '(...)))
 (sxpath1 '//) -> (node-or 
                     (node-self (ntype?? '*any*))
                     (node-closure (ntype?? '*any*)))
 (sxpath1 '(equal? x)) -> (select-kids (node-equal? x))
 (sxpath1 '(eq? x))    -> (select-kids (node-eq? x))
 (sxpath1 '(or@@ ...))  -> (select-kids (ntype-names??
                                          (cdr '(or@@ ...))))
 (sxpath1 '(not@@ ...)) -> (select-kids (sxml:invert 
                                         (ntype-names??
                                          (cdr '(not@@ ...)))))
 (sxpath1 '(ns-id:* x)) -> (select-kids 
                                      (ntype-namespace-id?? x))
 (sxpath1 ?symbol)     -> (select-kids (ntype?? ?symbol))
 (sxpath1 ?string)     -> (txpath ?string)
 (sxpath1 procedure)   -> procedure
 (sxpath1 '(?symbol ...)) -> (sxpath1 '((?symbol) ...))
 (sxpath1 '(path reducer ...)) ->
                (node-reduce (sxpath path) (sxpathr reducer) ...)
 (sxpathr number)      -> (node-pos number)
 (sxpathr path-filter) -> (filter (sxpath path-filter))
@end example
@end defun

@c EN
Some wrapper functions around @code{sxpath}:
@c JP
@code{sxpath}には、いくつかのラッパ関数があります。
@c COMMON

@defun if-sxpath path
@c EN
@code{sxpath} always returns a list, which is @code{#t} in Scheme.
@code{if-sxpath} returns @code{#f} instead of empty list.
@c JP
@code{sxpath}は、常にリストを返し、それはSchemeでは@code{#t}となります。
@code{if-sxpath}は、空リストの代わりに@code{#f}を返します。
@c COMMON
@end defun

@defun if-car-sxpath path
@c EN
Returns first node found, if any.
Otherwise returns @code{#f}.
@c JP
もし存在すれば、最初に見つかったノードを返します。
そうでなければ、@code{#f}を返します。
@c COMMON
@end defun

@defun car-sxpath path
@c EN
Returns first node found, if any.
Otherwise returns empty list.
@c JP
もし存在すれば、最初に見つかったノードを返します。
そうでなければ、空リストを返します。
@c COMMON
@end defun

@defun sxml:id-alist node . lpaths
@c EN
Built an index as a list of
@code{(@var{ID_value} . @var{element})} pairs for given
node.  @var{lpaths} are location paths for attributes of type ID.
@c JP
与えられたノードについて、@code{(@var{ID_value} . @var{element})}の
ペアのリストをインデックスとして構築します。
@var{lpaths}は、タイプIDの属性のロケーションパスです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXPath extension,  , SXPath query language, SXML Query Language
@subsection SXPath extension
@c NODE SXPathの拡張

@c EN
SXML counterparts to W3C XPath Core Functions Library.
@c JP
W3CのXPathコア関数ライブラリのSXML版です。
@c COMMON

@defun sxml:string object
@c EN
The counterpart to XPath @code{string} function (section 4.2 XPath Rec.)
Converts a given object to a string.
NOTE:
@c JP
XPathの@code{string}関数(XPath勧告のセクション4.2)に対応するものです。
与えられたオブジェクトを文字列に変換します。
注意:
@c COMMON
@enumerate
@item
@c EN
When converting a nodeset - a document order is not preserved
@c JP
ノードセットを変換する時は、ドキュメントオーダーは保持されません。
@c COMMON
@item
@c EN
@var{number->string} function returns the result in a form which is slightly
different from XPath Rec. specification
@c JP
@var{number->string}関数は、その結果をXPath勧告の仕様とは少し違った
フォームで返します。
@c COMMON
@end enumerate
@end defun

@defun sxml:boolean object
@c EN
The counterpart to XPath @code{boolean} function (section 4.3 XPath Rec.)
Converts its argument to a boolean.
@c JP
XPathの@code{boolean}関数(XPath勧告のセクション4.3)に対応するものです。
引数を真偽値に変換します。
@c COMMON
@end defun

@defun sxml:number obj
@c EN
The counterpart to XPath @code{number} function (section 4.4 XPath Rec.)
Converts its argument to a number
NOTE:
@c JP
XPathの@code{number}関数(XPath勧告のセクション4.4)に対応するものです。
引数を数値に変換します。
注意:
@c COMMON
@enumerate
@item
@c EN
The argument is not optional (yet?).
@c JP
引数は(まだ?)オプションではありません。
@c COMMON
@item
@c EN
@code{string->number} conversion is not IEEE 754 round-to-nearest.
@c JP
@code{string->number}の変換は、IEEE 754の四捨五入ではありません。
@c COMMON
@item
@c EN
NaN is represented as 0.
@c JP
NaNは、0として表現されます。
@c COMMON
@end enumerate
@end defun

@defun sxml:string-value node
@c EN
Returns a string value for a given node in accordance to
XPath Rec. 5.1 - 5.7
@c JP
XPath勧告のセクション5.1 - 5.7にしたがって、与えられたノードの
文字列値を返します。
@c COMMON
@end defun


@defun sxml:node? node
@c EN
According to XPath specification 2.3, this test is true for any
XPath node.
For SXML auxiliary lists and lists of attributes has to be excluded.
@c JP
XPathの仕様2.3にしたがい、このテストはいかなるXPathノードに
対しても真を返します。
SXMLの補助的なリストや属性のリストは除外されます。
@c COMMON
@end defun

@defun sxml:attr-list obj
@c EN
Returns the list of attributes for a given SXML node.
Empty list is returned if the given node is not an element,
or if it has no list of attributes
@c JP
与えられたSXMLノードの属性のリストを返します。
与えられたノードが要素ではないか、属性のリストを持っていない場合は、
空リストが返されます。
@c COMMON
@end defun

@defun sxml:id id-index
@c EN
Select SXML element by its unique IDs.  (XPath Rec. 4.1)
Returns a converter that takes @var{object},
which is a nodeset or a datatype which can be converted to a string by means
of a '@code{string}' function.

@var{id-index} is @code{( (id-value . element) (id-value . element) ... )}.

This index is used for selection of an element by its unique ID.
@c JP
SXML要素を、そのユニークなIDによって選択します(XPath勧告 4.1)。
@var{object}を引数に取るコンバータを返します。
この@var{object}は、ノードセットか、'@code{string}'関数により
文字列に変換できるデータタイプです。

@var{id-index}は、@code{( (id-value . element) (id-value . element) ... )}です。

このインデックスは、要素をそのユニークなIDによって選択するために使われます。
@c COMMON
@end defun

@c EN
Comparators for XPath objects:
@c JP
XPathオブジェクトの比較子:
@c COMMON

@defun sxml:equality-cmp bool-op number-op string-op
@c EN
A helper for XPath equality operations: @code{=} , @code{!=}
@var{bool-op}, @var{number-op} and
@var{'string-op} are comparison operations for 
a pair of booleans,  numbers and strings respectively.
@c JP
XPathの等値比較: @code{=}、@code{!=}のためのヘルパです。
@var{bool-op}、@var{number-op}、@var{'string-op}はそれぞれ、
真偽値、数値、文字列のペアのための比較子です。
@c COMMON
@end defun

@defun sxml:equal? a b
@defunx sxml:not-equal? a b
@c EN
Counterparts of XPath equality operations: @code{=} , @code{!=},
using default equality tests.
@c JP
XPathの等値比較: @code{=}、@code{!=}に対応するもので、
デフォルトの等値テストを使います。
@c COMMON
@end defun

@defun sxml:relational-cmp op
@c EN
Creates a relational operation ( @code{<} , @code{>} , @code{<=} , @code{>=} )
for two XPath objects.
@code{op} is comparison procedure: @code{<} , @code{>} , @code{<=} or @code{>=}.
@c JP
2つのXPathオブジェクトの関係比較( @code{<}、@code{>}、@code{<=}、@code{>=} )
を作ります。
@code{op}は、比較を行う手続き: @code{<}、@code{>}、@code{<=}、@code{>=}です。
@c COMMON
@end defun

@c EN
XPath axises.
An order in resulting nodeset is preserved.
@c JP
XPathの軸。
結果のノードセットにおける順序は維持されます。
@c COMMON

@defun sxml:attribute test-pred?
@c EN
Attribute axis.
@c JP
属性の軸です。
@c COMMON
@end defun

@defun sxml:child test-pred?
@c EN
Child axis.
This function is similar to '@code{select-kids}', but it returns an empty
child-list for PI, Comment and Entity nodes.
@c JP
子要素の軸です。
この関数は、'@code{select-kids}'に似ていますが、処理命令やコメント、
実体ノードについては、空の子リストを返します。
@c COMMON
@end defun

@defun sxml:parent test-pred?
@c EN
Parent axis.

Given a predicate, it returns a function 
@code{RootNode -> Converter}
which yields a 
@code{ node -> parent }
converter then applied to a rootnode.

Thus, such a converter may be constructed using
@code{ ((sxml:parent test-pred) rootnode) }
and returns a parent of a node it is applied to.
If applied to a nodeset, it returns the 
list of parents of nodes in the nodeset. The rootnode does not have
to be the root node of the whole SXML tree -- it may be a root node
of a branch of interest.
The @code{parent::} axis can be used with any SXML node.
@c JP
親の軸です。

述語を与えると、@code{RootNode -> Converter}関数を返します。
この関数は、rootnodeに適用されると、@code{node -> parent}と
なります。

このようなコンバータは、@code{ ((sxml:parent test-pred) rootnode) }
を使って構築され、それが適用されたノードの親を帰します。
ノードセットに適用された場合、そのノードセットにあるノードの
親のリストを返します。
rootnodeはSXMLツリー全体のルートノードである必要はありません。
興味の対象となるブランチ(枝)のルートノードでも構いません。
@code{parent::}軸は、どんなSXMLノードにも使えます。
@c COMMON
@end defun

@defun sxml:ancestor test-pred?
@c EN
Ancestor axis
@c JP
祖先の軸です。
@c COMMON
@end defun

@defun sxml:ancestor-or-self test-pred?
@c EN
Ancestor-or-self axis
@c JP
祖先と自分の軸です。
@c COMMON
@end defun

@defun sxml:descendant test-pred?
@c EN
Descendant axis
@c JP
子孫の軸です。
@c COMMON
@end defun

@defun sxml:descendant-or-self test-pred?
@c EN
Descendant-or-self axis
@c JP
子孫と自分の軸です。
@c COMMON
@end defun

@defun sxml:following test-pred?
@c EN
Following axis
@c JP
後続するものの軸です。
@c COMMON
@end defun

@defun sxml:following-sibling test-pred?
@c EN
Following-sibling axis
@c JP
後続する兄弟の軸です。
@c COMMON
@end defun

@defun sxml:namespace test-pred?
@c EN
Namespace axis
@c JP
名前空間の軸です。
@c COMMON
@end defun

@defun sxml:preceding test-pred?
@c EN
Preceding axis
@c JP
先行するものの軸です。
@c COMMON
@end defun

@defun sxml:preceding-sibling test-pred?
@c EN
Preceding-sibling axis
@c JP
先行する兄弟の軸です。
@c COMMON
@end defun

@c EN
Popular shortcuts:
@c JP
ポピュラーなショートカット:
@c COMMON

@defun sxml:child-nodes nodeset
@example
((sxml:child sxml:node?) nodeset)
@end example
@end defun

@defun sxml:child-elements nodeset
@example
((select-kids sxml:element?) nodeset)
@end example
@end defun


@c ----------------------------------------------------------------------
@node Manipulating SXML structure, Serializing XML and HTML from SXML, SXML Query Language, Library modules - Utilities
@section @code{sxml.tools} - Manipulating SXML structure
@c NODE SXML構造を操作する, @code{sxml.tools} - SXML構造を操作する

@deftp {Module} sxml.tools
@mdindex sxml.tools

@c EN
This module is a port of Kirill Lisofsky's sxml-tools,
a collection of convenient procedures that work on
SXML structure.
The current version is derived from sxml-tools CVS revision 3.13.

The manual entry is mainly derived from the comments in the original
source code.
@c JP
現在のバージョンは、sxml-toolsのCVSのリビジョン3.13から導出されています。

マニュアルのエントリは主に、オリジナルのソースコードから導出されています。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@menu
* SXML predicates::             
* SXML accessors::              
* SXML modifiers::              
* SXPath auxiliary utilities::  
* SXML to markup conversion::   
@end menu

@c ----------------------------------------------------------------------
@node SXML predicates, SXML accessors, Manipulating SXML structure, Manipulating SXML structure
@subsection SXML predicates
@c NODE SXMLの述語

@defun sxml:empty-element? obj
@c EN
A predicate which returns @var{#t} if given element @var{obj} is empty. 
Empty element has no nested elements, text nodes, @code{PI}s,
Comments or entities
but it may contain attributes or namespace-id.
It is a SXML counterpart of XML @code{empty-element}.
@c JP
与えられた要素@var{obj}が空なら@var{#t}を返す述語です。
空要素は、ネストした要素、テキストノード、@code{PI}、コメントや実体を
持ちませんが、属性や名前空間IDは持つかもしれません。
それは、XMLの@code{empty-element}のSXML版です。
@c COMMON
@end defun

@defun sxml:shallow-normalized? obj
@c EN
Returns @code{#t} if the given @var{obj} is shallow-normalized SXML element.
The element itself has to be normalized but its nested elements are not tested.
@c JP
与えられた@var{obj}が浅く正規化されたSXML要素であれば@code{#t}を返します。
要素それ自体は正規化されていなければなりませんが、ネストした要素は
テストされません。
@c COMMON
@end defun

@defun sxml:normalized? obj
@c EN
Returns @code{#t} if the given @var{obj} is normalized SXML element.
The element itself and all its nested elements have to be normalised.
@c JP
与えられた@var{obj}が正規化されたSXML要素であれば@code{#t}を返します。
要素それ自体とその全てのネストした要素が正規化されていなければなりません。
@c COMMON
@end defun

@defun sxml:shallow-minimized? obj
@c EN
Returns @code{#t} if the given @var{obj} is shallow-minimized SXML element.
The element itself has to be minimised but its nested elements are not tested.
@c JP
与えられた@var{obj}が浅く最小化されたSXML要素であれば@code{#t}を返します。
要素それ自体は最小化されていなければなりませんが、そのネストした要素は
テストされません。
@c COMMON
@end defun

@defun sxml:minimized? obj
@c EN
Returns @code{#t} if the given @var{obj} is minimized SXML element.
The element itself and all its nested elements have to be minimised.
@c JP
与えられた@var{obj}が最小化されたSXML要素であれば@code{#t}が返されます。
要素それ自体とその全てのネストした要素が最小化されていなければなりません。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXML accessors, SXML modifiers, SXML predicates, Manipulating SXML structure
@subsection SXML accessors
@c NODE SXMLへのアクセッサ

@defun sxml:name obj
@c EN
Returns a name of a given SXML node.
It's just an alias of @code{car}, but introduced for the sake of encapsulation.
@c JP
与えられたSXMLノードの名前を返します。
これは単に@code{car}のエイリアスに過ぎませんが、カプセル化のために導入されています。
@c COMMON
@end defun

@defun sxml:element-name obj
@c EN
A version of @code{sxml:name}, which returns @code{#f}
if the given @var{obj} is not a SXML element.
Otherwise returns its name.
@c JP
@code{sxml:name}の、与えられた@var{obj}がSXML要素ではない場合は@code{#f}を返す
バージョンです。@var{obj}がSXML要素であれば、その名前を返します。
@c COMMON
@end defun

@defun sxml:node-name obj
@c EN
Safe version of @code{sxml:name}, which returns @code{#f}
if the given @var{obj} is not a SXML node.
Otherwise returns its name.
@c JP
@code{sxml:name}の、与えられた@var{obj}がSXMLノードでない場合は@code{#f}を返す、
安全なバージョンです。@var{obj}がSXMLノードであれば、その名前を返します。
@c COMMON
@end defun

@defun sxml:ncname obj
@c EN
Returns Local Part of Qualified Name (Namespaces in XML production [6])
for given obj, which is "@code{:}"-separated suffix of its Qualified Name.
If a name of a node given is @code{NCName} (Namespaces in XML production [4]),
then it is returned as is.
Please note that while SXML name is a symbol this function returns a string.
@c JP
与えられたobjの完全修飾名(Namespaces in XML production [6])のローカルパート、
つまりその完全修飾名を``@code{:}''で分割した後ろの部分を返します。
与えられたノードの名前が@code{NCName}(Namespaces in XML production [4])であれば、
それをそのまま返します。
SXMLの名前はシンボルですが、この関数は文字列を返すことに注意して下さい。
@c COMMON
@end defun

@defun sxml:name->ns-id sxml-name
@c EN
Returns namespace-id part of given name, or @var{#f} if it's LocalName
@c JP
与えられた名前の名前空間ID部分を返します。与えられた名前がLocalNameの
場合は@var{#f}を返します。
@c COMMON
@end defun

@defun sxml:content obj
@c EN
Returns the content of given SXML element or nodeset (just text and element
nodes) representing it as a list of strings and nested elements in document 
order.  This list is empty if @var{obj} is empty element or empty list.
@c JP
与えられたSXML要素かノードセット(テキストノードと要素ノードのみ)の内容を、
ドキュメントオーダーにしたがった文字列のリストとネストした要素として
返します。このリストは、@var{obj}が空要素や空リストの場合は空です。
@c COMMON
@end defun

@defun sxml:content-raw obj
@c EN
Returns all the content of normalized SXML element except
@var{attr-list} and @var{aux-list}.
Thus it includes @code{PI}, @code{COMMENT} and @code{ENTITY}
nodes as well as @code{TEXT} and @code{ELEMENT} nodes
returned by @code{sxml:content}.
Returns  a list of nodes in document order or empty list if @var{obj} is empty 
element or empty list.
This function is faster than @code{sxml:content}.
@c JP
正規化されたSXML要素の全ての内容を、@var{attr-list}と@var{aux-list}を除いて
返します。
したがってそれは、@code{PI}、@code{COMMENT}、@code{ENTITY}
ノードとともに、@code{sxml:content}によって返される@code{TEXT}や@code{ELEMENT}も含みます。
戻り値は、ドキュメントオーダーにしたがったノードのリストか、
@var{obj}が空要素や空リストの場合は空リストになります。
この関数は、@code{sxml:content}よりも高速です。
@c COMMON
@end defun

@c EN
In SXML normal form, an element is represented by a list as this:
@c JP
SXMLの通常のフォームでは、1つの要素は次のようなリストで表現されます。
@c COMMON
@example
  (@var{name} @var{attr-list} @var{aux-list} @var{content} @dots{})
@end example
@c EN
where @var{attr-list} is a list beginning with @code{@@},
and @var{aux-list} is a list beginning with @code{@@@@}.

In the minimized form,
@var{Aux-list} can be omitted when it is empty.
@var{Attr-list} can be omitted when it is empty @emph{and}
@var{aux-list} is absent.

The following procedures extract @var{attr-list} and @var{aux-list}.
@c JP
@var{attr-list}は@code{@@}で始まるリストで、@var{aux-list}は@code{@@@@}で
始まるリストです。

最小化されたフォームでは、@var{aux-list}は空であれば省略できます。
@var{attr-list}は、それが空で@emph{かつ}@var{aux-list}がなければ省略できます。

以下の手続きは、@var{attr-list}と@var{aux-list}を抽出するものです。
@c COMMON

@defun sxml:attr-list-node obj
@c EN
Returns @var{attr-list} for a given @var{obj},
or @code{#f} if it is absent
@c JP
与えられた@var{obj}の@var{attr-list}を返します。
@var{attr-list}が存在しなければ@code{#f}を返します。
@c COMMON
@end defun

@defun sxml:attr-as-list obj
@c EN
Returns @var{attr-list} wrapped in list,
or '@code{((@@))} if it is absent and @var{aux-list} is present,
or '@code{()} if both lists are absent.
@c JP
@var{attr-list}をリストにラップして返します。
@var{attr-list}が存在せず@var{aun-list}がある場合は'@code{((@@))}を返します。
両方とも存在しない場合には'@code{()}を返します。
@c COMMON
@end defun

@defun sxml:aux-list-node obj
@c EN
Returns @var{aux-list} for a given @var{obj},
or @code{#f} if it is absent.
@c JP
与えられた@var{obj}の@var{aux-list}を返します。
@var{attr-list}が存在しなければ@code{#f}を返します。
@c COMMON
@end defun

@defun sxml:aux-as-list obj
@c EN
Returns @var{aux-list} wrapped in list,
or '@code{()} if it is absent.
@c JP
@var{aux-list}をリストにラップして返します。
@var{aux-list}が存在しなければ'@code{()}を返します。
@c COMMON
@end defun

@defun sxml:attr-list-u obj
@c EN
Returns the list of attributes for given element or nodeset.
Analog of @code{((sxpath '(@@ *)) @var{obj})}.
Empty list is returned if there is no list of attributes.

The @code{-u} suffix indicates it can be used for non-normalized
SXML node.  ('u' stands for 'universal').
@c JP
与えられた要素かノードセットの属性のリストを返します。
@code{((sxpath '(@@ *)) @var{obj})}と類似です。
属性のリストがない場合は空リストが返されます。
@c COMMON
@end defun

@defun sxml:aux-list obj
@c EN
Returns the list of auxiliary nodes for given element or nodeset.
Analog of @code{((sxpath '(@@@@ *)) @var{obj})}.
Empty list is returned if a list of auxiliary nodes is absent.
@c JP
与えられた要素かノードセットの補助ノードのリストを返します。
@code{((sxpath '(@@@@ *)) @var{obj})}と類似です。
補助ノードのリストがない場合は空リストが返されます。
@c COMMON
@end defun

@defun sxml:aux-list-u obj
@c EN
Returns the list of auxiliary nodes for given element or nodeset.
Analog of @code{((sxpath '(@@@@ *)) @var{obj})}.
Empty list is returned if a list of auxiliary nodes is absent.

The @code{-u} suffix indicates it can be used for non-normalized
SXML node.  ('u' stands for 'universal').
@c JP
与えられた要素かノードセットの補助ノードのリストを返します。
@code{((sxpath '(@@@@ *)) @var{obj})}と類似です。
補助ノードのリストがない場合は空リストが返されます。

@code{-u}が付くものは、正規化されていないSXMLノードに対しても
使えるということを示しています。('u'は'universal'の意味です。)
@c COMMON
@end defun

@defun sxml:aux-node obj aux-name
@c EN
Return the first aux-node with @var{aux-name}
given in SXML element @var{obj}
or @code{#f} is such a node is absent.
Note: it returns just the @emph{first} node found even if multiple nodes are
present, so it's mostly intended for nodes with unique names .
@c JP
与えられたSXML要素@var{obj}で@var{aux-name}という名前の付いている最初の
補助ノードを返します。そのようなノードがない場合は@code{#f}を返します。
注意: 複数のノードがあっても@emph{最初に}見つかったノードのみを
返します。したがって、ユニークな名前を持っているノード群に対して
使われることを意図しています。
@c COMMON
@end defun

@defun sxml:aux-nodes obj aux-name
@c EN
Return a list of aux-node with @var{aux-name}
given in SXML element @var{obj} 
or '@code{()} if such a node is absent.
@c JP
与えられたSXML要素@var{obj}で@var{aux-name}とうい名前の付いている補助ノードの
リストを返します。そのようなノードがなければ'@code{()}を返します。
@c COMMON
@end defun

@defun sxml:attr obj attr-name
@c EN
Accessor for an attribute @var{attr-name} of
given SXML element @var{obj}.
It returns: 
the value of the attribute if the attribute is present, or
@var{#f} if there is no such an attribute in the given element.
@c JP
与えられたSXML要素@var{obj}の@var{attr-name}という属性へのアクセッサです。
戻り値は、その属性が存在すればその属性の値、与えられた要素に
そのような属性がなければ@var{#f}です。
@c COMMON
@end defun

@defun sxml:num-attr obj attr-name
@c EN
Accessor for a numerical attribute @var{attr-name}
of given SXML element @var{obj}.
It returns: 
a value of the attribute as the attribute as a number if the attribute 
is present and its value may be converted to number using @code{string->number},
or @code{#f} if there is no such an attribute in the given element or
its value can't be converted to a number.
@c JP
与えられたSXML要素@var{obj}の@var{attr-name}という数値の属性への
アクセッサです。
戻り値は、その属性が存在してその値が@code{string->number}により数値へ
変換できる場合はその属性を数値としてその属性の値、
与えられた要素にそのような属性がないかその値が数値へ変換できない場合は
@code{#f}です。
@c COMMON
@end defun

@defun sxml:attr-u obj attr-name
@c EN
Accessor for an attribute @var{attr-name}
of given SXML element @var{obj} which 
may also be an attributes-list or nodeset (usually content of SXML element).

It returns: 
the value of the attribute if the attribute is present,
or @code{#f} if there is no such an attribute in the given element.

The @code{-u} suffix indicates it can be used for non-normalized
SXML node.  ('u' stands for 'universal').
@c JP
与えられたSXML要素@var{obj}の@var{attr-name}という名前の属性への
アクセッサです。@var{obj}は、(通常はSXML要素の内容である)
属性リストやノードセットでも構いません。

戻り値は、その属性が存在すればその属性の値、与えられた要素に
そのような属性がない場合は@code{#f}です。

@code{-u}が付くものは、正規化されていないSXMLノードに対しても
使えるということを示しています。('u'は'universal'の意味です。)
@c COMMON
@end defun

@defun sxml:ns-list obj
@c EN
Returns the list of namespaces for given element.
Analog of @code{((sxpath '(@@@@ *NAMESPACES* *)) @var{obj})}
Empty list is returned if there is no list of namespaces.
@c JP
与えられた要素の名前空間のリストを返します。
@code{((sxpath '(@@@@ *NAMESPACES* *)) @var{obj})}と類似です。
名前空間のリストがない場合は空リストが返されます。
@c COMMON
@end defun

@defun sxml:ns-id->nodes obj namespace-id
@c EN
Returns the list of namespace-assoc's for given @var{namespace-id} in 
SXML element @var{obj}.
Analog of @code{((sxpath '(@@@@ *NAMESPACES* namespace-id)) @var{obj})}.
Empty list is returned if there is no namespace-assoc with
@var{namespace-id} given.
@c JP
SXML要素@var{obj}で、与えられた@var{namespace-id}に対応する名前空間の
連想リストのリストを返します。
@code{((sxpath '(@@@@ *NAMESPACES* namespace-id)) @var{obj})}と類似です。
与えられた@var{namespace-id}に対応する名前空間の連想リストがない場合は
空リストが返されます。
@c COMMON
@end defun

@defun sxml:ns-id->uri obj namespace-id
@c EN
Returns a URI for @var{namespace-id} given, or
@code{#f} if there is no namespace-assoc with @var{namespace-id} given.
@c JP
与えられた@var{namespace-id}に対応するURIを返します。
与えられた@var{namespace-id}に対応する名前空間の連想リストがない場合は
@code{#f}を返します。
@c COMMON
@end defun

@defun sxml:ns-uri->id obj uri
@c EN
Returns a namespace-id for namespace URI given.
@c JP
与えられた名前空間URIに対応する名前空間IDを返します。
@c COMMON
@end defun

@defun sxml:ns-id ns-assoc
@c EN
Returns namespace-id for given namespace-assoc list.
@c JP
与えられた名前空間連想リストに対応する名前空間IDを返します。
@c COMMON
@end defun

@defun sxml:ns-uri ns-assoc
@c EN
Returns URI for given namespace-assoc list.
@c JP
与えられた名前空間連想リストに対応するURIを返します。
@c COMMON
@end defun

@defun sxml:ns-prefix ns-assoc
@c EN
It returns namespace prefix for given namespace-assoc list.
Original (as in XML document) prefix for namespace-id given 
has to be strored as the third element in namespace-assoc list 
if it is different from namespace-id.
If original prefix is omitted in namespace-assoc then
namespace-id is used instead.
@c JP
与えられた名前空間連想リストに対応する名前空間接頭辞を返します。
与えられた名前空間IDの(XML文書における)オリジナルの接頭辞は、
それが名前空間IDと異なる場合は、名前空間連想リストの3番目の要素として
格納されなければなりません。
名前空間連想リストでオリジナルの接頭辞が省略されている場合は、
代わりに名前空間IDが使われます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXML modifiers, SXPath auxiliary utilities, SXML accessors, Manipulating SXML structure
@subsection SXML modifiers
@c NODE SXMLのモディファイヤ

@c EN
Constructors and mutators for normalized SXML data.
These functions are optimized for normalized SXML data.
They are not applicable to arbitrary non-normalized SXML data.

Most of the functions are provided in two variants:
@c JP
正規化されたSXMLデータのコンストラクタやミューテータです。
これらの関数は、正規化されたSXMLデータに最適化されています。
任意の正規化されていないSXMLデータには適用できません。

ほとんどの関数には2つのバージョンがあります。
@c COMMON
@enumerate
@item
@c EN
side-effect intended functions for linear update of given elements.
Their names are ended with exclamation mark.
Note that the returned value of this variant is unspecified,
unless explicitly noted.
An example: @code{sxml:change-content!}.
@c JP
与えられた要素のその場での更新のために副作用が意図された関数。
これらの名前はエクスクラメーションマークで終わっています。
このバージョンの戻り値は、特に断りのない限り未定義です。
例としては、@code{sxml:change-content!}が挙げられます。
@c COMMON
@item
@c EN
pure functions without side-effects which return modified elements.
An example: @code{sxml:change-content}.
@c JP
変更された要素を返す、副作用のない純粋な関数。
例としては、@code{sxml:change-content}が挙げられます。
@c COMMON
@end enumerate

@defun sxml:change-content obj new-content
@defunx sxml:change-content! obj new-content
@c EN
Change the content of given SXML element to @var{new-content}.
If @var{new-content} is an empty list then the @var{obj} is transformed
to an empty element.
The resulting SXML element is normalized.
@c JP
与えられたSXML要素の内容を、@var{new-content}に変更します。
@var{new-content}が空リストの場合は、@var{obj}は空要素に変更されます。
結果のSXML要素は正規化されています。
@c COMMON
@end defun

@defun sxml:change-attrlist obj new-attrlist
@defunx sxml:change-attrlist! obj new-attrlist
@c EN
The resulting SXML element is normalized.
If @var{new-attrlist} is empty,
the cadr of @var{obj} is @code{(@@)}.
@c JP
結果のSXML要素は正規化されています。
@var{new-attrlist}が空の場合は、@var{obj}のcadrは@code{(@@)}になります。
@c COMMON
@end defun

@defun sxml:change-name obj new-name
@defunx sxml:change-name! obj new-name
@c EN
Change a name of SXML element destructively.
@c JP
SXML要素の名前を破壊的に変更します。
@c COMMON
@end defun

@defun sxml:add-attr obj attr
@c EN
Returns SXML element @var{obj} with attribute @var{attr} added,
or @code{#f} if the attribute with given name already exists.
@var{attr} is @code{(@var{attr-name} @var{attr-value})}.
Pure functional counterpart to @code{sxml:add-attr!}.
@c JP
属性@var{attr}が追加されたSXML要素@var{obj}を返します。
与えられた名前の属性がすでに存在する場合は@code{#f}を返します。
@var{attr}は@code{(@var{attr-name} @var{attr-value})}です。
@code{sxml:add-attr!}に対応する純粋関数的な関数です。
@c COMMON
@end defun

@defun sxml:add-attr! obj attr
@c EN
Add an attribute @var{attr} for an element @var{obj}.
Returns @code{#f} if the attribute with given name already exists. 
The resulting SXML node is normalized.
Linear update counterpart to @code{sxml:add-attr}.
@c JP
要素@var{obj}に属性@var{attr}を追加します。
与えられた名前の属性がすでに存在する場合は@code{#f}を返します。
結果のSXMLノードは正規化されています。
@code{sxml:add-attr}に対応するその場で更新する関数です。
@c COMMON
@end defun

@defun sxml:change-attr obj attr
@c EN
Returns SXML element @var{obj} with changed value of
attribute @var{attr}, or @code{#f}
if where is no attribute with given name. 
@var{attr} is @code{(@var{attr-name} @var{attr-value})}.
@c JP
属性@var{attr}の値が変更されたSXML要素@var{obj}を返します。
与えられた名前の属性がない場合は@code{#f}を返します。
@var{attr}は@code{(@var{attr-name} @var{attr-value})}です。
@c COMMON
@end defun

@defun sxml:change-attr! obj attr
@c EN
Change value of the attribute for element @var{obj}.
@var{attr} is @code{(@var{attr-name} @var{attr-value})}.
Returns @code{#f} if where is no such attribute.
@c JP
要素@var{obj}の属性の値を変更します。
@var{attr}は@code{(@var{attr-name} @var{attr-value})}です。
そのような属性がない場合は@code{#f}を返します。
@c COMMON
@end defun

@defun sxml:set-attr obj attr
@defunx sxml:set-attr! obj attr
@c EN
Set attribute @var{attr} of element @var{obj}.
If there is no such attribute the new one is added.
@c JP
要素@var{obj}の属性@var{attr}をセットします。
そのような属性がない場合は新しい属性として追加されます。
@c COMMON
@end defun

@defun sxml:add-aux obj aux-node
@c EN
Returns SXML element @var{obj}
with an auxiliary node @var{aux-node} added.
@c JP
補助ノード@var{aux-node}が追加されたSXML要素@var{obj}を返します。
@c COMMON
@end defun

@defun sxml:add-aux! obj aux-node
@c EN
Add an auxiliary node @var{aux-node} for an element @var{obj}.
@c JP
要素@var{obj}に補助ノード@var{aux-node}を追加します。
@c COMMON
@end defun

@defun sxml:squeeze obj
@defunx sxml:squeeze! obj
@c EN
Eliminates empty lists of attributes and aux-lists for given SXML element 
@var{obj} and its descendants ("minimize" it).
Returns a minimized and normalized SXML element.
@c JP
与えられたSXML要素@var{obj}とその子孫について、空のリストである属性
および補助リストを排除します(最小化)。
最小化され、正規化されたSXML要素が返されます。
@c COMMON
@end defun

@defun sxml:clean obj
@c EN
Eliminates empty lists of attributes and all aux-lists for given SXML element 
@var{obj} and its descendants.
Returns a minimized and normalized SXML element.
@c JP
与えられたSXML要素@var{obj}とその子孫について、空リストである属性と、
全ての補助リストを削除します。
最小化され、正規化されたSXML要素が返されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXPath auxiliary utilities, SXML to markup conversion, SXML modifiers, Manipulating SXML structure
@subsection SXPath auxiliary utilities
@c NODE SXPathの補助的ユーティリティ

@c EN
These are convenience utilities to extend SXPath functionalities.
@c JP
これらは、SXPathの機能を拡張する便利なユーティリティです。
@c COMMON

@defun sxml:add-parents obj . top-ptr
@c EN
Returns an SXML nodeset with a 'parent pointer' added.
A parent pointer is an aux node of the form @code{(*PARENT* @var{thunk})},
where @var{thunk} returns the parent element.
@c JP
SXMLノードセットに'親へのポインタ'を追加したものを返します。
親へのポインタは、@code{(*PARENT* @var{thunk})}というフォームを持つ
補助ノードです。@var{thunk}は親要素を返します。
@c COMMON
@end defun

@defun sxml:node-parent rootnode
@c EN
Returns a fast 'node-parent' function, i.e.
a function of one argument - SXML element - which returns its parent
node using @code{*PARENT*} pointer in aux-list.
'@code{*TOP-PTR*} may be used as a pointer to root node.
It return an empty list when applyed to root node.
@c JP
高速な'node-parent'関数を返します。
すなわち、SXML要素を1引数として取り、補助リストで
@code{*PARENT*}ポインタを使ってその親ノードを返す関数を返します。
'@code{*TOP-PTR*}はルートノードへのポインタとして使われます。
ルートノードに対して適用されると空リストを返します。
@c COMMON
@end defun

@defun sxml:lookup id index
@c EN
Lookup an element using its ID.
@c JP
要素をそのIDを使って探します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node SXML to markup conversion,  , SXPath auxiliary utilities, Manipulating SXML structure
@subsection SXML to markup conversion
@c NODE SXMLからマークアップへの変換

@c EN
Procedures to generate XML or HTML marked up text from SXML.
For more advanced conversion, see the SXML serializer
(@ref{Serializing XML and HTML from SXML}).

@c JP
SXMLからXMLやHTMLなどのマークアップされたテキストを生成する手続き。
もっと高尚な変換器を得たいだけならば、
@ref{Serializing XML and HTML from SXML}をチェックして下さい。
@c COMMON

@defun sxml:clean-feed . fragments
@c EN
Filter the 'fragments'.
The fragments are a list of strings, characters,
numbers, thunks, @code{#f} -- and other fragments.
The function traverses the tree depth-first, and returns a list
of strings, characters and executed thunks,
and ignores @code{#f} and '@code{()}.

If all the meaningful fragments are strings, then
@var{(apply string-append ... )}
to a result of this function will return its string-value.

It may be considered as a variant of Oleg Kiselyov's
@code{SRV:send-reply}:
While @code{SRV:send-reply} displays fragments, this function returns the list 
of meaningful fragments and filter out the garbage.
@c JP
'fragments'をフィルタします。
fragmentsは、文字列、文字、数値、手続き、@code{#f}、他のフラグメントの
リストです。
この関数はツリーを深さ優先でトラバースし、
文字列、文字、実行された手続きのリストを返し、
@code{#f}と'@code{()}を無視します。

全ての意味のあるフラグメントは文字列で、
この関数の結果に@var{(apply string-append ... )}を
適用すると、そのstring-valueを返します。

これは、Oleg Kiselyovの@code{SRV:send-reply}の変種であるとみなすことが
できるでしょう。
@code{SRV:send-reply}はフラグメントを印字(display)しますが、
この関数は意味のあるフラグメントのリストを返し、ごみをふるい落とします。
@c COMMON
@end defun

@defun sxml:attr->xml attr
@c EN
Creates the XML markup for attributes.
@c JP
属性のXMLマークアップを作ります。
@c COMMON
@end defun

@defun sxml:string->xml string
@c EN
Return a string or a list of strings where all the occurences of 
characters @code{<}, @code{>},
@code{&}, @code{"}, or @code{'} in a given string are
replaced by corresponding 
character entity references. See also @code{sxml:string->html}.
@c JP
与えられた文字列中の全ての@code{<}、@code{>}、@code{&}、@code{``}、
@code{'}を対応する文字実体参照に置き換えた、文字列あるいは
文字列のリストを返します。
@code{sxml:string->html}も参照して下さい。
@c COMMON
@end defun

@defun sxml:sxml->xml tree
@c EN
A version of dispatch-node specialized and optimized for SXML->XML
transformation.
@c JP
SXML->XML変換に特化され最適化されたバージョンのノードディスパッチです。
@c COMMON
@end defun

@defun sxml:attr->html attr
@c EN
Creates the HTML markup for attributes.
@c JP
属性のHTMLマークアップを作ります。
@c COMMON
@end defun

@defun sxml:string->html string
@c EN
Given a string, check to make sure it does not contain characters
@var{<}, @var{>}, @var{&},
@var{"} that require encoding.
See also @code{html-escape-string}
in @ref{Simple HTML document construction}.
@c JP
与えられた文字列で、それがエンコーディングを必要とする文字、
@var{<}、@var{>}、@var{&}、@var{``}を含まないことをチェックします。
@ref{Simple HTML document construction}の
@code{html-escape-string}も参照して下さい。
@c COMMON
@end defun

@defun sxml:non-terminated-html-tag? tag
@c EN
This predicate yields @code{#t} for "non-terminated" HTML 4.0 tags.
@c JP
この述語は、``終了タグのない''HTML 4.0のタグに対して@code{#t}を
返します。
@c COMMON
@end defun

@defun sxml:sxml->html tree
@c EN
A version of dispatch-node specialized and optimized for SXML->HTML
transformation.
@c JP
SXML->HTML変換に対して特化され最適化されたバージョンのノードディスパッチ
です。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Serializing XML and HTML from SXML, CSV tables, Manipulating SXML structure, Library modules - Utilities
@section @code{sxml.serializer} -  Serializing XML and HTML from SXML
@c NODE SXMLからXMLとXHTMLのシリアライゼーション, @code{sxml.serializer} - SXMLからXMLとXHTMLのシリアライゼーション

@deftp {Module} sxml.serializer
@mdindex sxml.serializer
@c EN
This module contains a full-featured serializer from SXML into XML and
HTML, partially conforming to XSLT 2.0 and XQuery 1.0 Serialization
(@uref{http://www.w3.org/TR/2005/CR-xslt-xquery-serialization-20051103/}).
It's more powerful than sxml:sxml->xml and sxml:sxml->html from
sxml.tools.

The manual entry is mainly derived from the comments in the original
source code.
@c JP
このモジュールはSXMLからXMLとHTMLへの変換を行う、様々な機能を持つ
シリアライザを提供します。XSLT2.0とXQuery1.0に部分的に適合しています。
(@uref{http://www.w3.org/TR/2005/CR-xslt-xquery-serialization-20051103/})。
sxml.toolsのsxml:sxml->xmlとsxml:sxml->htmlよりも強力です。

マニュアルのエントリは主に、オリジナルのソースコードから取られてています。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@menu
* Simple SXML serializing::     
* Custom SXML serializing::     
@end menu

@c ----------------------------------------------------------------------
@node Simple SXML serializing, Custom SXML serializing, Serializing XML and HTML from SXML, Serializing XML and HTML from SXML
@subsection Simple SXML serializing
@c NODE 簡単なSXML変換

@c EN
The SXML serializer provides some convenient high-level converters which
should be enough for most tasks.
@c JP
高レベルの、簡単に使えるシリアライザです。大抵の目的にはこれで十分使えるでしょう。
@c COMMON

@defun srl:sxml->xml sxml-obj :optional port-or-filename
@c EN
Serializes the @var{sxml-obj} into XML, with indentation to facilitate
readability by a human.

If @var{port-or-filename} is not supplied, the functions return a
string that contains the serialized representation of the
@var{sxml-obj}.

If @var{port-or-filename} is supplied and is a port, the functions
write the serialized representation of @var{sxml-obj} to this port and
return an unspecified result.

If @var{port-or-filename} is supplied and is a string, this string is
treated as an output filename, the serialized representation of
@var{sxml-obj} is written to that filename and an unspecified result
is returned. If a file with the given name already exists, the effect
is unspecified.
@c JP
@var{sxml-obj}をXMLへと変換します。出力は人間が読みやすいように
インデントされます。

@var{port-or-filename}が与えられなければ、
戻り値は@var{sxml-obj}の変換結果の文字列になります。

@var{port-or-filename}がポートならば、そのポートにXMLを書き出します。
戻り値は不定です。

@var{port-or-filename}が文字列ならば、その名のファイルにXMLを書き出し
ます。戻り値は不定です。そのようなファイルが既に存在する場合、
結果は不定です。
@c COMMON
@end defun

@defun srl:sxml->xml-noindent sxml-obj :optional port-or-filename
@c EN
Serializes the @var{sxml-obj} into XML, without indentation.

Argument @var{port-or-filename} works like described in
@code{srl:sxml->xml}.
@c JP
@code{srl:sxml->xml}と同じように動作しますが、インデントを行いません。

引数@var{port-or-filename}は@code{srl:sxml->xml}と同様に動作します。
@c COMMON
@end defun

@defun srl:sxml->html sxml-obj :optional port-or-filename
@c EN
Serializes the @var{sxml-obj} into HTML, with indentation to
facilitate readability by a human.

Argument @var{port-or-filename} works like described in @code{srl:sxml->xml}.
@c JP
@var{sxml-obj}をHTMLへと変換します。出力は人間が読みやすいように
インデントされます。

引数@var{port-or-filename}は@code{srl:sxml->xml}と同様に動作します。
@c COMMON
@end defun

@defun srl:sxml->html-noindent sxml-obj :optional port-or-filename
@c EN
Serializes the @var{sxml-obj} into HTML, without indentation.

Argument @var{port-or-filename} works like described in @code{srl:sxml->xml}.
@c JP
@code{srl:sxml->html}と同じように動作しますが、インデントを行いません。

引数@var{port-or-filename}は@code{srl:sxml->xml}と同様に動作します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Custom SXML serializing,  , Simple SXML serializing, Serializing XML and HTML from SXML
@subsection Custom SXML serializing
@c NODE カスタムSXML変換

@c EN
These functions provide full access to all configuration parameters of
the XML serializer.
@c JP
以下の手続きはXMLシリアライザの全ての設定パラメータへのアクセスを提供
します。
@c COMMON

@defun srl:parameterizable sxml-obj :optional port-or-filename params*
@c EN
Generalized serialization procedure, parameterizable with all the
serialization parameters supported by this implementation.
@c JP
汎用シリアライズ手続、この実装でサポートするすべてのシリアライズパラメー
タのパラメータ化。
@c COMMON

@c EN
@var{sxml-obj} - an SXML object to serialize
@c JP
@var{sxml-obj} - シリアライズするSXMLオブジェクト。
@c COMMON

@c EN
@var{port-or-filename} - either @code{#f}, a port or a string; works
like in srl:sxml->xml (@ref{Simple SXML serializing}).
@c JP
@var{port-or-filename} - @code{#f}あるいはポートあるいは文字列のどれか。
srl:sxml->xmlのものと同じ働きをします(@ref{Simple SXML serializing})。
@c COMMON

@c EN
@var{params} - each parameter is a cons of param-name (a symbol) and
param-value.  The available parameter names and their values are
described below:
@c JP
@var{params} - 各パラメータはパラメータ名(シンボル)とパラメータ値との
コンス対。利用可能なパラメータ名とその値については後述。
@c COMMON

@c EN
@code{method} - Either the symbol @code{xml} or @code{html}.  For a
detailed explanation of the difference between XML and HTML methods,
see XSLT 2.0 and XQuery 1.0 Serialization (@uref{http://www.w3.org/TR/2005/CR-xslt-xquery-serialization-20051103/}).
@c JP
@code{method} - シンボル@code{xml}か@code{html}のどちらか。XMLメソッド
とHTMLメソッドの相違についての詳しい説明は、XSLT 2.0 と XQuery
Serialization 
(@uref{http://www.w3.org/TR/2005/CR-xslt-xquery-serialization-20051103/})
を参照してください。
@c COMMON

@c EN
@code{indent} - Whether the output XML should include whitespace for
human readability (@code{#t} or @code{#f}).  You can also supply a
string, which will be used as the indentation unit.
@c JP
@code{indent} - 出力の XML が読みやすさのために空白を含むかどうか
(@code{#t}あるいは@code{#f})。文字列を設定することもでき、その場合
インデント単位に使われます。
@c COMMON

@c EN
@code{omit-xml-declaration?} - Whether the XML declaration should be
omitted.  Default: @code{#t}.
@c JP
@code{omit-xml-declaration?} - XML宣言を省略するかどうか。デフォルトは
@code{#t}。
@c COMMON

@c EN
@code{standalone} - Whether to define the XML document as standalone in
the XML declaration.  Should be one of the symbols @code{yes},
@code{no} or @code{omit}, the later causing standalone declaration to
be supressed.  Default: @code{omit}.
@c JP
@code{standalone} - XML ドキュメントを XML 宣言でスタンドアローンとし
て定義するかどうか。@code{yes}、@code{no}、@code{omit}のうちいづれかの
シンボルでなければならない。デフォルトは @code{omit}
@c COMMON

@c EN
@code{version} - The XML version used in the declaration.  A string or
a number.  Default: @code{"1.0"}.
@c JP
@code{version} - XML宣言中のXMLバージョン。文字列または数。デフォルト
は@code{"1.0"}。
@c COMMON

@c EN
@code{cdata-section-elements} - A list of SXML element names (as
symbols).  The contents of those elements will be escaped as CDATA
sections.
@c JP
@code{cdata-section-elements} - SXML要素の名前(シンボル)のリスト。これ
らの要素の中身はCDATAセクションと同様にエスケープされる。
@c COMMON

@c EN
@code{ns-prefix-assig} - A list of @code{(cons prefix namespace-uri)},
where each @code{prefix} is a symbol and each @code{namespace-uri} a
string.  Will serialize the given namespaces with the corresponding
prefixes.
@c JP
@code{ns-prefix-assig} - @code{(cons prefix namespace-uri)}のリスト。
各@code{prefix}はシンボルで、@code{namespace-uri}は文字列。
対応する接頭辞をつけて与えられた名前空間をシリアライズする。
@c COMMENT

@c EN
ATTENTION: If a parameter name is unexpected or a parameter value is
ill-formed, the parameter is silently ignored!
@c JP
注意： パラメータ名が期待された名前ではない場合、あるいはパラメータ値
が不正な形式である場合にはそのようなパラメータは警告なしで無視されます。
@c COMMON

@c EN
Example usage:

@lisp
(srl:parameterizable
  '(tag (@@ (attr "value")) (nested "text node") (empty))
  (current-output-port)
  '(method . xml)  ; XML output method is used by default
  '(indent . "\t")  ; use a single tabulation to indent
  '(omit-xml-declaration . #f)  ; add XML declaration
  '(standalone . yes)  ; denote a standalone XML document
  '(version . "1.0"))  ; XML version
@end lisp
@c JP
使用実例：
@lisp
(srl:parameterizable
  '(tag (@@ (attr "value")) (nested "text node") (empty))
  (current-output-port)
  '(method . xml)  ; XML出力をデフォールト
  '(indent . "\t")  ; インデントは一つのタブ
  '(omit-xml-declaration . #f)  ; XML宣言をつける
  '(standalone . yes)  ; 「standalone」宣言もつける
  '(version . "1.0"))  ; XMLのバージョン
@end lisp
@c COMMON

@lisp
param ::= (cons param-name param-value)
param-name ::= symbol

cdata-section-elements
value ::= (listof sxml-elem-name)
sxml-elem-name ::= symbol

indent
value ::= 'yes | #t | 'no | #f | whitespace-string

method
value ::= 'xml | 'html

ns-prefix-assig
value ::= (listof (cons prefix namespace-uri))
prefix ::= symbol
namespace-uri ::= string

omit-xml-declaration?
value ::= 'yes | #t | 'no | #f

standalone
value ::= 'yes | #t | 'no | #f | 'omit

version
value ::= string | number
@end lisp
@end defun

@defun srl:sxml->string sxml-obj cdata-section-elements indent method ns-prefix-assig omit-xml-declaration? standalone version
@c EN
Same as @code{srl:parameterizable} returning a string and without the
overhead of parsing parameters.  This function interface may change in
future versions of the library.
@c JP
@code{srl:parameterizable}と同様ですが、文字列を返し、パラメータ解析のオーバヘッ
ドはありません。この関数のインタフェースはこのライブラリの将来のバージョ
ンでは変更されるかもしれません。
@c COMMON
@end defun

@defun srl:display-sxml sxml->obj port-or-filename cdata-section-elements indent method ns-prefix-assig omit-xml-declaration? standalone version

@c EN
Same as @code{srl:parameterizable} writing output to
@var{port-or-filename} and without the overhead of parsing parameters. 
This function interface may change in
future versions of the library.
@c JP
@code{srl:parameterizable}と同様ですが、結果を
@var{port-or-filename}に書き出します。パラメータ解析のオーバーヘッドはありません。
この関数のインタフェースはこの
ライブラリの将来のバージョンでは変更されるかもしれません。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node CSV tables, Calculate difference of text streams, Serializing XML and HTML from SXML, Library modules - Utilities
@section @code{text.csv} - CSV tables
@c NODE CSVテーブル, @code{text.csv} - CSVテーブル

@deftp {Module} text.csv
@mdindex text.csv
@c EN
Provides a function to parse/generate CSV (comma separated value) tables,
including the format defined in RFC4180.  You can customize the
separator and quoter character to deal with variations of CSV formats.

CSV table is consisted by a series of @var{records}, separated by
a newline.  Each record contains number of @var{fields}, separated
by a separator character (by default, a comma).  A field can contain
comma or newline if quoted, i.e. surrounded by double-quote characters.
To include double-quote character in a quoted field, use two
consecutive double-quote character.   Usually, the whitespaces around
the field are ignored.
@c JP
RFC4180に定義されたフォーマットを含む、
CSV (カンマ区切りの値) の表をパーズ/生成するための手続きを提供します。
区切り文字やクオート文字をカスタマイズすることで、CVSに似たフォーマットを
広くカバーすることができます。

CSV の表は、改行で区切られた @var{record} の連続で構成されます。
それぞれのレコードは、区切り文字(デフォルトではカンマ)で区切られた
複数の @var{field} を含みます。フィールドは、クォートされている
(二重引用符で囲まれている)場合は、カンマや改行を含むことができます。
クォートされたフィールドに二重引用符を含めるには、2つの連続する
二重引用符を使います。通常、フィールドの前後の空白は無視されます。
@c COMMON
@c example here

@end deftp

@c EN
Right now, the following two low-level procedures are exported.
A plan is to provide higher features, such as labelling fields
and automatic conversions.
@c JP
現時点では、以下の2つの低レベルな手続きが提供されています。
フィールドにラベル付けをしたり、自動的に変換するなどの
より高レベルな機能の提供を計画しています。
@c COMMON

@defun make-csv-reader separator :optional (quote-char #\")
@c EN
Returns a procedure with one argument, input port.
When the procedure is called, it reads one record from the port,
and returns a list of fields.
If input reaches EOF, it returns EOF.
@c JP
入力ポートを唯一の引数として取る手続きを返します。
手続きが呼ばれると、ポートからレコードを1つ読み込み、フィールドの
リストを返します。入力ポートが EOF に達すると、EOF を返します。
@c COMMON
@end defun

@defun make-csv-writer separator :optional newline (quote-char #\")
@c EN
Returns a procedure with two arguments, output port and
a list of fields.  When the procedure is called, it
outputs a @var{separator}-separated fields with proper escapes,
to the output port.   You can also specify the record delimiter
string by @var{newline}; for example, you can pass @code{"\r\n"}
to prepare a file to be read by Windows programs.
@c JP
出力ポートとフィールドのリストの2つの引数を取る手続きを返します。
手続きが呼ばれると、@var{separator} で区切られたフィールドを
正しくエスケープして出力ポートに出力します。レコードの区切り文字列を
@var{newline} で指定することもできます。例えば、ファイルが Windows の
プログラムでも読めるように、@code{"\r\n"} を渡すことができます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Calculate difference of text streams, Localized messages, CSV tables, Library modules - Utilities
@section @code{text.diff} - Calculate difference of text streams
@c NODE テキストストリームの相違点を計算する, @code{text.diff} - テキストストリームの相違点を計算する

@deftp {Module} text.diff
@mdindex text.diff
@c EN
This module calculates the difference of two text streams or strings,
using @code{util.lcs} (@xref{The longest common subsequence}).
@c JP
このモジュールでは、@code{util.lcs} (@ref{The longest common subsequence}参照)を
使って、2つのテキストストリーム、あるいは2つの文字列の相違点を計算します。
@c COMMON
@end deftp

@defun diff src-a src-b :key reader eq-fn
@c EN
Generates an "edit list" from text sources @var{src-a} and @var{src-b}.

Each of text sources, @var{src-a} and @var{src-b}, can be either an input
port or a string.  If it is a string, it is converted to a string input
port internally.  Then, the text streams from both sources are converted
to sequences by calling @var{reader} repeatedly on them; the default
of @var{reader} is @code{read-line}, and those sequences are
passed to @code{lcs-edit-list} to calculate the edit list.
The equality function @var{eq-fn} is also passed to @code{lcs-edit-list}.

An edit list is a set of commands that turn the text sequence
from @code{src-a} to the one from @code{src-b}.
See the description of @code{lcs-edit-list} for
the detailed explanation of the edit list.
@c JP
テキストソース@var{src-a}と@var{src-b}から``編集リスト''を生成します。

それぞれのテキストソース、@var{src-a}と@var{src-b}は入力ポートか文字列です。
もし文字列であれば、それは内部的に文字列ポートに変換されます。
そして、2つのソースからのテキストストリームは、それらに対して@var{reader}を繰り返し
呼ぶことによってシーケンスに変換されます。デフォルトの@var{reader}は@var{read-line}で、
2つのシーケンスは編集リストを計算するために@code{lcs-edit-list}に渡されます。
@code{lcs-edit-list}には、等値を検査する関数@var{eq-fn}も渡されます。

編集リストとは、@code{src-a}から@code{src-b}へテキストシーケンスを
変更するためのコマンドのセットです。編集リストの詳細な説明は、
@code{lcs-edit-list}を参照してください。
@c COMMON

@example
(diff "a\nb\nc\nd\n" "b\ne\nd\nf\n")
@result{}
  (((- 0 "a"))
   ((- 2 "c") (+ 1 "e"))
   ((+ 3 "f")))
@end example
@end defun

@defun diff-report src-a src-b :key reader eq-fn writer
@c EN
A convenience procedure to take the diff of two text sources
and display the result nicely.  This procedure calls @code{lcs-fold}
to calculate the difference of two text sources.  The meanings of
@var{src-a}, @var{src-b}, @var{reader} and @var{eq-fn} are the
same as @code{diff}'s.
@c JP
2つのテキストソースのdiffをとって、その結果をきれいに表示するための
簡易手続きです。この手続きは、2つのテキストソースの相違点を計算する
ために@code{lcs-fold}を呼び出します。@var{src-a}、@var{src-b}、
@var{reader}、@var{eq-fn}の意味は、@code{diff}の場合と同じです。
@c COMMON

@c EN
@var{Writer} is a procedure that takes two arguments, the text element
and a type, which is either a symbol @code{+}, 
a symbol @code{-}, or @code{#f}.   If the text element is only
in @var{src-a}, @var{writer} is called with the element and
@code{-}.  If the text element is only in @var{src-b}, 
it is called with the element and @code{+}.  If the text element
is in both sources, it is called with the element and
@code{#f}.   The default procedure of @var{writer} prints
the passed text element to the current output port
in unified-diff-like format:
@c JP
@var{writer}は2つの引数、テキスト要素とタイプ(シンボル@code{+}、
シンボル@code{-}、あるいは@code{#f}のいずれか)を取る手続きです。
テキスト要素が@var{src-a}にしかない場合は、@var{writer}がそのテキスト要素と
@code{-}とともに呼ばれます。テキスト要素が@var{src-b}にしかない場合は、
@var{writer}はそのテキスト要素と@code{+}とともに呼ばれます。
テキスト要素が両方のソースにある場合は、@var{writer}はそのテキスト要素と
@code{#f}とともに呼ばれます。@var{writer}のデフォルトの手続きは、
渡されたテキスト要素を現在の出力ポートにユニファイドdiffのようなフォーマットで
出力します。
@c COMMON
@example
(diff-report "a\nb\nc\nd\n" "b\ne\nd\nf\n")
@end example
displays: 
@example
- a
  b
- c
+ e
  d
+ f
@end example
@end defun


@c ----------------------------------------------------------------------
@node Localized messages, Simple HTML document construction, Calculate difference of text streams, Library modules - Utilities
@section @code{text.gettext} - Localized messages
@c NODE 地域化メッセージ, @code{text.gettext} - 地域化メッセージ

@deftp {Module} text.gettext
@mdindex text.gettext
@c EN
This module provides utilities to deal with localized messages.
The API is compatible to GNU's gettext, and the messages
are read from @file{*.po} and @file{*.mo} files,
so that you can use the GNU gettext
toolchain to prepare localized messages.
However, the code is written from scratch by Alex Shinn and
doesn't depend on GNU's gettext library.
@c JP
このモジュールは地域化メッセージを扱うユーティリティを提供します。
API は GNU の gettext と互換性があり、メッセージは @file{*.po} および
@file{*.mo} ファイルから読み込まれます。それゆえ、GNU の gettext toolchain
をつかって地域化メッセージを準備することができます。しかし、このコードは
Alex Shinn によってスクラッチから書き起こされたものであり、GNU の
gettext ライブラリには依存していません。
@c COMMON

@c EN
This implementation extends GNU's gettext API in the following ways:
@itemize @bullet
@item
It can read from multiple message files in cascaded way,
allowing applications to share a part of message files.
@item
It supports multiple locale/domain simultaneously.
@end itemize
@c JP
この実装は GNU の gettext API を以下のように拡張したものです。
@itemize @bullet
@item
複数のメッセージファイルから、カスケードされた方法で読み込むことができます。
これにより、アプリケーションはメッセージファイルの部分を共有できます。
@item
複数のロケール/ドメインを同時に扱えます。
@end itemize
@c COMMON

@c EN
SRFI-29 (@xref{Localization}) provides another means of message
localization.  A portable program may wish to use srfi-29, but
generally @code{text.gettext} is recommended in Gauche scripts
because of its flexibility and compatibility to existing message files.
@c JP
SRFI-29 (@ref{Localization}参照) はこれとは別のメッセージの地域化
機構を提供しています。ポータブルなプログラムでは、SRFI-29 の方がよいこと
もありますが、一般には、Gauche スクリプトでは、@code{text.gettext} の
方を推奨します。それは、既存のメッセージファイルとの互換性と柔軟性の
ためです。
@c COMMON
@end deftp

@c EN
@subheading Gettext-compatible API
@c JP
@subheading gettext-互換の API
@c COMMON

@defun textdomain domain-name :optional locale dirs cdir cached? lookup-cached?
@c EN
Sets up the default domain and other parameters for
the application.  The setting affects to the following @code{gettext}
call.

@var{Domain} is a string or list of strings specifying the domain
(name of @file{.mo} or @file{.po} files) as in C gettext.
You can pass @code{#f} as @var{domain-name} just to get the default
domain accessor procedure.
You can alo pass multiple domains to @var{domain-name}.
@c JP
アプリケーション用に、デフォルトのドメインとそのほかのパラメータを
設定します。この設定は、以降の @code{gettext} の呼出しに影響を与えます。

@var{domain} は文字列または文字列のリストで、ドメイン(@file{.mo} あるいは
@file{.po} ファイル名)を C の gettext と同じように指定します。
@code{#f} を @var{domain-name} として渡すと、デフォルトのドメインアクセサ
手続きが得られます。また、複数のドメインを @var{domain-name}にあたえる
ことができます。
@c COMMON
@example
(textdomain '("myapp" "gimp"))  ; search 1st myapp, then gimp
(gettext "/File/Close")         ; "Close" from gimp unless overridden
@end example

@c EN
@var{Locale} is a string or list of strings in the standard Unix format of
@code{LANG[_REGION][.ENCODING]}.  You can also pass a list of locales
to specify fallbacks.
@c JP
@var{locale} は文字列または文字列のリストで、標準的なUnixのフォーマット
@code{LANG[_REGION][.ENCODING]} です。フォールバックを指定するロケール
のリストを渡すこともできます。
@c COMMON

@example
(textdomain "myapp" '("ru" "uk"))  ; search 1st Russian then Ukranian,
(gettext "Hello, World!")          ; which are somewhat similar
@end example

@c EN
@var{Dirs} is the search path of directories which should hold the
@file{LOCALE/CDIR/} directories which contain the actual message catalogs.
This is always appended with the system default, e.g.
@file{"/usr/share/locale"}, and may also inherit from the 
@code{GETTEXT_PATH} colon-delimited environment variable.

@var{Cdir} is the category directory, defaulting to either the 
@code{LC_CATEGORY}
environment variable or the appropriate system default
(e.g. @code{LC_MESSAGES}).  You generally won't need this.

@var{Cached?}
means to cache individual messages, and defaults to @code{#t}.

@var{Lookup-cached?}
means to cache the lookup dispatch generated by these
parameters, and defaults to @code{#t}.

@code{Textdomain} just passes these parameters to the internal
@code{make-gettext},
and binds the result to the global dispatch used by @code{gettext}.  
You may build these closures manually for convenience in using multiple
separate domains or locales at once (useful for server environments).
See the description of @code{make-gettext} below.

@code{Textdomain} returns an @emph{accessor procedure} which
packages information of the domain.  See @code{make-gettext} below
for the details.
@c JP
@var{dirs} は実際のメッセージカタログを含む @file{LOCALE/CDIR/}
ディレクトリのサーチパスです。これは常にシステムのデフォルト(たとえば、
@file{"/usr/share/locale"})に追加されます。そして、コロンで区切られた
@code{GETTEXT_PATH} 環境変数を継承します。

@var{cdir} はカテゴリーディレクトリで、既定値を @code{LC_CATEGORY}
環境変数または、適当なシステム既定値(たとえば @code{LC_MESSAGES})に
設定します。一般にはこれを指定する必要はありません。

@var{cached?} は個別のメッセージをキャッシュするかを意味し、デフォルトは
@code{#t} です。

@var{lookup-cached?}
は、これらのパラメータで生成されるディスパッチをキャッシュするかどうか
を意味し、デフォルトは @code{#t} です。

@code{textdomain} はこれらのパラメータを内部の @code{make-gettext} に
渡し、その結果を、@code{gettext} で使われるグローバルなディスパッチに
束縛します。これらのクロージャを複数の別々のドメインやロケールを一度に
扱うのに便利なように、手で構築することができます。(これらは
サーバ環境で便利です。) 後述の @code{make-gettext} を参照してください。

@code{textdomain} はそのドメインの情報をもつ @emph{アクセサ手続き}を
返します。詳細については、後述の @code{make-gettext} を参照してください。
@c COMMON
@end defun

@defun gettext msg-id
@c EN
Returns a translated message of @var{msg-id}.  If there's no
translated message, @var{msg-id} itself is returned.
@c JP
@var{msg-id} の翻訳されたメッセージを返します。もし、翻訳された
メッセージがなければ、@var{msg-id} それ自身を返します。
@c COMMON
@end defun

@defun ngettext msg-id :optional msg-id2 num
@c EN
Similar to @var{gettext}, but it can be used to handle
plural forms.
Pass a singular form to @var{msg-id}, and plural form to
@code{msg-id2}.  The @var{num} argument is used to determine
the plural form.  If no message catalog is found, @var{msg-id}
is returned when @var{num} is 1, and @var{msg-id2} otherwise.
@c JP
@var{gettext}と似ていますが、複数形を処理するのに使うことが
できます。単数形のメッセージを @var{msg-id} へ、複数形のメッセージを
@code{msg-id2} に渡します。@var{num} 引数は、複数形を決定
するのに使われます。もし、メッセージカタログが見つからなければ、
@var{num} が 1 のときは、@var{msg-id} が返り、そうでなければ、
@var{msg-id2} が返ります。
@c COMMON
@end defun

@defun bindtextdomain domain dirs
@c EN
Sets the search path of domain @var{domain} to @var{dirs}, which 
may be just a single directory name or a list of directory names.
@c JP
ドメイン @var{domain} のサーチパスを @var{dirs} に設定します。
単一のディレクトリ名であったり、ディレクトリのリストであったりします。
@c COMMON
@end defun

@defun dgettext domain msg-id
@defunx dcgettext domain msg-id locale
@c EN
Returns a translated message of @var{msg-id} in @var{domain}.
@code{Dcgettext} takes @var{locale} as well.
@c JP
@var{domain} 中の @var{msg-id} の翻訳されたメッセージを返します。
@code{dcgettext} は @var{locale} も引数としてとります。
@c COMMON
@end defun

@c EN
@subheading Low-level flexible API
@c JP
@subheading 低水準の柔軟な API
@c COMMON

@c EN
The following procedure is more flexible interface, on top of which
the gettext-compatible APIs are written.
@c JP
以下の手続きはより柔軟性のあるインタフェースで、この上で、gettext-互換の
API が書かれています。
@c COMMON

@defun make-gettext :optional domain locale dirs gettext-cached? lookup-cached?
@c EN
Creates and returns an @emph{accessor procedure}, which encapsulates
methods to retrieve localized messages.

The meaning of arguments are the same as @code{textdomain} above.
Indeed, @code{textdomain} just calls @code{make-gettext}, and later
it binds the result to the global parameter.   If you wish to have
multiple independent domains within a single program, you can
call @code{make-gettext} directly and manage the created
accessor procedure by yourself.
@c JP
@emph{アクセサ手続き} を生成して返します。返された手続きは、
地域化されたメッセージを検索するメソッドをカプセル化しています。

引数の意味は上述の @code{textdomain} と同じです。
実際は、@code{textdomain} は @code{make-gettext} を呼び、その後、
それは、結果をこのグローバルパラメータに束縛します。@code{make-gettext}
を直接呼んで、自分自身で、アクセサ手続きを管理することもできます。
@c COMMON

@example
(define my-gettext (make-gettext "myapp"))
(define _ (my-gettext 'getter))
(_ "Hello, World!")
@end example
@end defun

@c ----------------------------------------------------------------------
@node Simple HTML document construction, Parsing input stream, Localized messages, Library modules - Utilities
@section @code{text.html-lite} - Simple HTML document construction
@c NODE シンプルなHTMLドキュメントの構築, @code{text.html-lite} - シンプルなHTMLドキュメントの構築

@deftp {Module} text.html-lite
@mdindex text.html-lite
@c EN
Provides procedures to construct an HTML document easily.
For example, you can construct an HTML table by the following code:
@c JP
HTML ドキュメントを簡単に構築するための手続きを提供します。
例えば、以下のコードは HTML のテーブルを構築します。
@c COMMON
@example
(html:table
  (html:tr (html:th "Item No") (html:th "Quantity"))
  (html:tr (html:td 1) (html:td 120))
  (html:tr (html:td 2) (html:td 30))
  (html:tr (html:td 3) (html:td 215)))
@end example
@c EN
See the description of @code{html:@var{element}} below for details.

This module does little check for the constructed html documents,
such as whether the attributes are valid, and whether the content
of the element matches DTD.  It does not provide a feature to parse
the html document neither.  Hence the name `lite'.
@c JP
詳細については、以下の @code{html:@var{element}} の説明を見てください。

このモジュールでは生成されたHTMLドキュメントに関して、
例えばアトリビュートに有効な値が入っているか、要素の内容はDTDを満たしているか、
等のチェックをほとんど行いません。また、HTMLをパーズする関数も提供されません。
それが「lite」の名の由来です。
@c COMMON
@end deftp

@defun html-escape
@defunx html-escape-string string
@c EN
Escapes the ``unsafe'' characters in HTML.  @code{html-escape}
reads input string from the current input port and writes the result
to the current output port.   @code{html-escape-string} takes the
input from @var{string} and returns the result in a string.
@c JP
HTML に含まれる"安全でない"文字をエスケープします。
@code{html-escape} は、現在の入力ポートから文字列を読み込み、
結果を現在の出力ポートへ書き出します。@code{html-escape-string} は
@var{string} を入力とし、文字列を返します。
@c COMMON
@end defun

@defun html-doctype :key type
@c EN
Returns a doctype declaration for an HTML document.
@var{type} can be either one of the followings (default is 
@code{:html-4.01-strict}).
@c JP
HTML ドキュメントの文書型宣言を返します。
@var{type} は、以下のいずれかを指定します (デフォルトは@code{:html-4.01-strict}
です)。
@c COMMON
@table @code
@item :html-4.01-strict, :html-4.01, :strict
HTML 4.01 Strict DTD
@item :html-4.01-transitional, :transitional
HTML 4.01 Transitional DTD
@item :html-4.01-frameset, :frameset
HTML 4.01 Frameset DTD
@item :xhtml-1.0-strict, :xhtml-1.0
XHTML 1.0 Strict DTD
@item :xhtml-1.0-transitional
XHTML 1.0 Transitional DTD
@item :xhtml-1.0-frameset
XHTML 1.0 Frameset DTD
@item :xhtml-1.1
XHTML 1.1 DTD
@end table
@end defun

@deftp {Function} html:@var{element} @var{args} @dots{}
@findex html:a
@findex html:abbr
@findex html:acronym
@findex html:address
@findex html:area
@findex html:b
@findex html:base
@findex html:bdo
@findex html:big
@findex html:blockquote
@findex html:body
@findex html:br
@findex html:button
@findex html:caption
@findex html:cite
@findex html:code
@findex html:col
@findex html:colgroup
@findex html:dd
@findex html:del
@findex html:dfn
@findex html:div
@findex html:dl
@findex html:dt
@findex html:em
@findex html:fieldset
@findex html:form
@findex html:frame
@findex html:frameset
@findex html:h1
@findex html:h2
@findex html:h3
@findex html:h4
@findex html:h5
@findex html:h6
@findex html:head
@findex html:hr
@findex html:html
@findex html:i
@findex html:iframe
@findex html:img
@findex html:input
@findex html:ins
@findex html:kbd
@findex html:label
@findex html:legend
@findex html:li
@findex html:link
@findex html:map
@findex html:meta
@findex html:noframes
@findex html:noscript
@findex html:object
@findex html:ol
@findex html:optgroup
@findex html:option
@findex html:p
@findex html:param
@findex html:pre
@findex html:q
@findex html:samp
@findex html:script
@findex html:select
@findex html:small
@findex html:span
@findex html:strong
@findex html:style
@findex html:sub
@findex html:sup
@findex html:table
@findex html:tbody
@findex html:td
@findex html:textarea
@findex html:tfoot
@findex html:th
@findex html:thead
@findex html:title
@findex html:tr
@findex html:tt
@findex html:ul
@findex html:var
@c EN
Construct an HTML element @var{element}.  Right now,
the following elements are provided.
(The elements defined in HTML 4.01 DTD,
@uref{http://www.w3.org/TR/html4/sgml/dtd.html}).
@c JP
@var{element} の HTML 要素を構築します。現時点では以下の要素が
サポートされています。
(HTML 4.01 DTD @uref{http://www.w3.org/TR/html4/sgml/dtd.html}
に定義されている要素です)。
@c COMMON
@example
a        abbr       acronym    address     area      b
base     bdo        big        blockquote  body      br
button   caption    cite       code        col       colgroup
dd       del        dfn        div         dl        dt
em       fieldset   form       frame       frameset  
h1       h2         h3         h4          h5        h6
head     hr         html       i           iframe    img
input    ins        kbd        label       legend    li
link     map        meta       nofrmaes    noscript  object
ol       optgroup   option     p           param     pre
q        samp       script     select      small     span
strong   style      sub        sup         table     tbody
td       textarea   tfoot      th          thead     title
tr       tt         ul         var
@end example

@c EN
The result of these functions is a tree of text segments,
which can be written out to a port by @code{write-tree} or
can be converted to a string by @code{tree->string}
(@xref{Lazy text construction}).

You can specify attributes of the element by using a keyword-value
notation before the actual content.
@c JP
これらの手続きは、テキスト・セグメントのツリーを返すので、
@code{write-tree} でポートに書き出したり、@code{tree->string} で
文字列に変換したりできます
(@ref{Lazy text construction}参照)。

要素のアトリビュートは要素の内容に先立つキーワード-値の表記で指定することができます。
@c COMMON
@example
(tree->string (html:a :href "http://foo/bar" "foobar"))
  @result{}
  "<a href=\"http://foo/bar\">foobar</a\n>"

(tree->string
  (html:table :width "100%" :cellpading 0 "content here"))
  @result{}
  "<table width=\"100%\" cellpadding=\"0\">content here</table\n>"
@end example

@c EN
The boolean value given to the attribute has a special meaning.
If @code{#t} is given, the attribute is rendered without a value.
If @code{#f} is given, the attribute is not rendered.
@c JP
属性に与える真偽値は特別な意味を持ちます。
@code{#t} が与えられると、属性は値なしでレンダリングされます。
@code{#f} が与えられると、属性それ自体がレンダリングされません。
@c COMMON
@example
(tree->string (html:table :border #t))
  @result{} "<table border></table\n>"

(tree->string (html:table :border #f))
  @result{} "<table></table\n>"
@end example

@c EN
Special characters in attribute values are escaped by the function,
but the ones in the content are not.  It is caller's responsibility
to escape them.

The functions signal an error if a content is given to the
HTML element that doesn't take a content.   They do not
check if the given attribute is valid, neither
if the given content is valid for the element.
@c JP
属性の値における特別な文字は、手続きによってエスケープされますが、
要素の内容にある特別な文字はエスケープされません。それをエスケープ
するのは呼び出し側の責任です。

内容を持たない HTML 要素に内容を与えると手続きはエラーを通知します。
手続きは、与えられた属性が妥当であるか、与えられた内容がその要素に
とって妥当であるかのチェックはしません。
@c COMMON

@c EN
@emph{Note:}
You might have noticed that these procedures insert a newline
before @code{>} of the closing tag.  That is, the rendered
HTML would look like this:
@c JP
@emph{注意:}
これらの手続は改行を終了タグの@code{>}の前に挿入することに注意してくだ
さい。つまり、HTMLをレンダリングすると以下のようになります。
@c COMMON

@example
<table><tr><td>foo</td
><td>bar</td
></tr
></table
>
@end example

@c EN
We intentionally avoid inserting newlines after the closing
tag, since @emph{it depends on the surrounding context whether
the newline is significant or not}.  We may be able to insert newlines
after the elements directly below a @code{<head>} element,
for example, but we cannot in a @code{<p>} element.
@c JP
終了ダグの後に改行をいれないのは意図的なものです。@emph{改行が意味をも
つかどうかは外側の文脈に依存するからです}。たとえば、@code{<head>}要素
の直下にある要素の後に改行をいれることはできますが、@code{<p>}要素のな
かにあればできません。
@c COMMON

@c EN
There are three possible solutions: (1) not to insert newlines
at all, (2) to insert newlines within tags, and (3) to insert
newlines only at the safe position.  The first one creates one
long line of HTML, and although it is still valid HTML, it is
inconvenient to handle it with line-oriented tools.
The third one requires the
rendering routine to be aware of DTD.  So we took the second
approach.
@c JP
3つ可能性があって、(1) 改行は全く入れない、(2) タグの中だけで改行を入
れる。(3) 安全な場所にのみ改行をいれる。最初の場合はHTMLは一行になり、
正当なHTMLではあるものの、行指向のツールで処理するには不便です。3番目
の場合はレンダリングするのにDTDをちゃんと見るツールが必要になります。
というわけで、ここでは2番目のアプローチを取っています。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node Parsing input stream, Showing progress on text terminals, Simple HTML document construction, Library modules - Utilities
@section @code{text.parse} - Parsing input stream
@c NODE 入力ストリームのパージング, @code{text.parse} - 入力ストリームのパージング

@deftp {Module} text.parse
@mdindex text.parse
@c EN
A collection of utilities that does simple parsing from
the input port.   The API is inspired, and compatible with
Oleg Kiselyov's input parsing library (@ref{oleg1,,OLEG1}).
His library is used in lots of other libraries, notably,
a full-Scheme XML parser/generator SSAX (@ref{ssax,,SSAX}).

You can use this module in place of his
@code{input-parse.scm} and @code{look-for-str.scm}.

I reimplemented the functions to be efficient on Gauche.
Especially, usage of @code{string-set!} is totally avoided.
I extended the interface a bit so that they can deal with character sets
and predicates, as well as a list of characters.

These functions work sequentially on the given input port,
that is, they read from the port as much as they need, without
buffering extra characters.
@c JP
入力ポートに対して単純な解析を行うユーティリティのコレクションです。
API は Oleg Kiselyov 氏の入力解析ライブラリ (@ref{oleg1,,OLEG1}) に
触発され、互換性を持つものです。氏のライブラリは、他のたくさんの
ライブラリで使われています。特に、Scheme のみで書かれたパーサ/ジェネレータ
である SSAX (@ref{ssax,,SSAX}) が挙げられます。

このモジュールは、氏の @code{input-parse.scm} や @code{look-for-str.scm}
の代わりに使うことができます。

Gauche で効果的になるように手続きを再実装しました。特に、@code{string-set!}
の使用は完全に取り除きました。インターフェースを少し拡張したので、
文字セットや述語、文字のリストにも使うことができます。

これらの手続きは、与えられた入力ポートに対してシーケンシャルに動作します。
それは、ポートから必要なだけ読み、余分な文字をバッファリングしないということです。
@c COMMON
@end deftp

@defun find-string-from-port? str in-port :optional max-no-chars
@c EN
Looks for a string @var{str} from the input port @var{in-port}.
The optional argument @var{max-no-chars} limits the maximum number of
characters to be read from the port; if omitted, the search span is
until EOF.

If @var{str} is found, this function returns the number of characters
it has read.   The next read from @var{in-port} returns the next char
of @var{str}.  If @var{str} is not found, it returns @code{#f}.

Note: Although this procedure has `@code{?}' in its name,
it may return non-boolean value, contrary to the Scheme convention.
@c JP
入力ポート @var{in-port} から、文字列 @var{str} を探します。
オプショナル引数 @var{max-no-chars} は、ポートから読み込まれる最大文字数を
制限します。省略されると、検索する範囲は EOF までとなります。

@var{str} が見つかると、手続きはすでに読み込んだ文字の数を返します。
@var{in-port} の次回の読み込みは、@var{str} の次の文字を返します。
@var{str} が見つからない場合、@code{#f} が返ります。

注意: この手続きはその名前に「@code{?}」がつきますが、Scheme の慣習に反し、
真偽値ではない値を返すことがあります。
@c COMMON
@end defun

@defun peek-next-char :optional port
@c EN
Discards the current character and peeks the next character from @var{port}.
Useful to look ahead one character.
If @var{port} is omitted, the current input port is used.
@c JP
現在の文字を破棄し、@var{port} から次の文字を読みます。一文字先読みするのに
便利です。@var{port} が省略されると、現在の入力ポートが使われます。
@c COMMON
@end defun

@c EN
In the following functions, @var{char-list} refers to one of the
followings:
@itemize @bullet
@item
A character set.
@item
A list of characters, character sets and/or symbol @code{*eof*}.
@end itemize
That denotes a set of characters.  If a symbol @code{*eof*} is
included, the EOF condition is also included.  Without @code{*eof*},
the EOF condition is regarded as an error.
@c JP
以下の手続きでは、@var{char-list} は次のどれかを意味します。
@itemize @bullet
@item
文字セット。
@item
文字、文字セット、シンボル @code{*eof*} の任意の組み合わせのリスト。
@end itemize
[That denotes a set of characters.] シンボル @code{*eof*} が含まれる場合、
EOF の条件もまた含まれます。@code{*eof*} が含まれない場合、EOF の条件は
エラーとして扱われます。
@c COMMON

@defun assert-curr-char char-list string :optional port
@c EN
Reads a character from @var{port}.  If it is included in @var{char-list},
returns the character.  Otherwise, signals an error with a message
containing @var{string}.
If @var{port} is omitted, the current input port is used.
@c JP
@var{port} から文字を読みます。その文字が @var{char-list} に含まれている場合は
その文字を返します。そうでなければ、@var{string} を含むメッセージとともに
エラーを通知します。
@c COMMON
@end defun

@defun skip-until char-list/number :optional port
@c EN
@var{char-list/number} is either a char-list or a number.
If it is a number; it reads that many characters and returns @code{#f}.
If the input is not long enough, an error is signalled.
If @var{char-list/number} is a char-list, it reads from @var{port}
until it sees a character that belongs to the char-list.
Then the character is returned.
If @var{port} is omitted, the current input port is used.
@c JP
@var{char-list/number} は、文字のリストか数です。
数の場合、たくさんの文字を読んで、@code{#f} を返します。
入力が十分に長くない場合は、エラーが通知されます。
@var{char-list/number} が文字のリストの場合、その文字リストに属する文字に
出会うまで @var{port} を読み込み、その文字を返します。
@var{port} が省略された場合、現在の入力ポートが使われます。
@c COMMON
@end defun

@defun skip-while char-list :optional port
@c EN
Reads from @var{port} until it sees a character that does not
belong to @var{char-list}.  The character remains in the stream.
If it reaches EOF, an EOF is returned.
If @var{port} is omitted, the current input port is used.

This example skips whitespaces from input.  Next read from
port returns the first non-whitespace character.
@c JP
@var{char-list} に属しない文字に出会うまで、@var{port} を読み込みます。
文字はストリームに残されます。EOF に達したら EOF が返されます。
@var{port} が省略された場合、現在の入力ポートが使われます。

この例では、入力から空白スペースをスキップしています。ポートからの次の
読み込みは、最初の空白スペースでない文字を返します。
@c COMMON
@example
(skip-while #[\s] port)
@end example
@end defun

@defun next-token prefix-char-list break-char-list :optional comment port
@c EN
Skips any number of characters in @var{prefix-char-list},
then collects the characters until it sees @var{break-char-list}.
The collected characters are returned as a string.
The break character remains in the @var{port}.

If the function encounters EOF and @code{*eof*} is not included in
@var{break-char-list}, an error is signalled with @var{comment} is
included in the message.
@c JP
@var{prefix-char-list} に含まれる文字はいくつでもスキップします。
そして、@var{break-char-list} に含まれる文字に出会うまで、文字を
蓄積します。蓄積された文字群は文字列として返されます。
中断文字は @var{port} に残されます。

手続きが EOF に達し、@code{*eof*} が @var{break-char-list} に含まれていない
場合、@var{comment} が含まれたメッセージとともにエラーが通知されます。
@c COMMON
@end defun

@defun next-token-of char-list/pred :optional port
@c EN
Reads and collects the characters as far as
it belongs to @var{char-list/pred}, then returns them as a string.
The first character that doesn't belong to @var{char-list/pred} remains
on the port.

@var{char-list/pred} may be a char-list or a predicate that takes
a character.   If it is a predicate, each character is passed to it,
and the character is regarded to ``belong to'' @var{char-list/pred}
when it returns a true value.
@c JP
読み込んだ文字が @var{char-list/pred} にある限り蓄積し、文字列として
返します。@var{char-list/pred} に含まれない最初の文字はポートに残されます。

@var{char-list/pred} は文字のリストか文字を取る述語です。述語の場合、
それぞれの文字がその述語に渡され、真の値が返る場合はその文字は
@var{char-list/pred} に属するとみなされます。
@c COMMON
@end defun

@defun read-string n :optional port
@c EN
Reads up to @var{n} characters, collects them into a string, and returns it.
If the input stream contains less characters, the returns string contains
as many characters available.
@c JP
@var{n} 文字まで読み込み、文字列として蓄積しそれを返します。
入力ストリームに含まれる文字のほうが少ない場合、有効な文字を可能な限り
含む文字列が返ります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Showing progress on text terminals, SQL parsing and construction, Parsing input stream, Library modules - Utilities
@section @code{text.progress} - Showing progress on text terminals
@c NODE @code{text.progress} - テキスト端末上でプログレスを表示する

@deftp {Module} text.progress
@mdindex text.progress
@c EN
This module provides a utility to report a progress of processing
on a text terminal, using characters to display bar chart.
@c JP
このモジュールはバーチャートを文字を用いて表示し、テキスト端末上に処理
の進行状況を出すためのユーティリティです。
@c COMMENT

@c EN
The generic format of a progress bar consists of a single line
of text, which is splitted into several parts; a header, which
displays the title; followed by a bar, a numeric part, and a time part,
as shown in the followig example (only the line beginning with ``foo''
is actually displayed).
@c JP
プログレスバーの汎用的なフォーマット1行のテキストで構成されます。この1
行はいくつかの部分に分解できます。タイトルを表示するヘッダ部、その後に
プログレスバーがあって、数値部、時間部と続きます。以下がその例です(foo
からはじまる1行だけが実際に表示されます。
@c COMMON
@example
<-header-> <-------bar---------> <-num-><-time->      <---info---->
foo       |#############        |123/211   01:21 ETA  compiling...
          ^
          separator
@end example

@c EN
Various things like the character used in the bar chart or
the format of the numeric progress can be configured.
@c JP
バーチャートに使う文字などのいろいろなバリエーションや、数値で表わす
進捗のフォーマットなども設定可能です。
@c COMMON

@c EN
Internally a progress bar maintains two numbers, the maximum (goal)
value and the current value.  The bar shows the proportion of
the current value relative to the maximum value.  The numeric progress
shows the current value over the maximum value by default, but you
can configure it to show only the current value or percentage, for example.
@c JP
内部的にはプログレスバーは2つの数値、最大値(ゴール)と現在の値を保持し
ています。バーは最大値に対する現在の値の比を示すものです。数値で表わす
進捗はデフォルトでは最大値の上に現在の値を表示します。しかし、たとえば、
現在の値だけを表示するとか、100分率で表示するなどの設定が可能です。
@c COMMON

@c EN
A progress bar also has two states, ``in progress'' and ``finished''.
When it is in progress, every time the text is displayed it is
followed by @code{#\return}, so that the next display overwrites
the bar, and the time part shows ETA (estimated time of arrival).
Once it becomes finished, the last line of text is displayed
with @code{#\newline}, and the time part shows the actual time
it took to finish.
@c JP
プログレスバーは2つの状態「進捗中」および「終了」のどちらかの状態を保
持しています。「進捗中」なら、どの時点でも表示されるテキストには
@code{#\return}が続きます。これにより次の表示が前の表示を上書きするこ
とになります。時間部はETA(残り時間)を表示します。終了してしまえば、最
後の行の後に@code{#\newline}が続きます。時間部には終了までにかかった時
間が表示されます。
@c COMMON
@end deftp

@c EN
This module provides only one procedure, @code{make-text-progress-bar},
which packages the progress bar feature in a closure and returns it.
@c JP
このモジュールは@code{make-text-progress-bar}という手続きを1つだけ提供
します。この手続きはプログレスバーの機能をクロージャに包んでそれを返し
ます。
@c COMMON

@defun make-text-progress-bar :key header header-width bar-char bar-width num-width num-format time-width info info-width separator-char max-value port

@c EN
Returns a procedure that packages operations on the progress bar.
The procedure can be called with a symbol indicating an operation,
and an optional numeric argument.
@c JP
プログレスバー上の操作を包んだ手続きを返します。返された手続きに操作を
示すシンボルとオプションで数値を引数として渡して使います。
@c COMMON

@table @code
@item @var{proc} 'show
@c EN
Redisplays the progress bar.  All other operations implies redisplay,
so you don't need to use this unless you have a specific reason to 
redisplay the current state.
@c JP
プログレスバーを再表示する。他のどの操作も状態の再表示を行います。
したがって、現在のステータスを再表示しなければない特別な理由がないかぎ
りこれを使う必要はありません。
@c COMMON

@item @var{proc} 'set @var{value}
@c EN
Sets the current value to @var{value}, then redisplays the progress bar.
If @var{value} exceeds the max value, it is clipped by the max value.
@c JP
現在の値を@var{value}にセットし、プログレスバーを再表示します。
@var{value}が最大値を超えていたら、超過分を切り捨て最大値にします。
@c COMMON

@item @var{proc} 'inc @var{value}
@c EN
Increments the current value by @var{value}, then redisplays the progress bar.
If the current value exceeds the max value, it is clipped by the max value.
@c JP
@var{value}分だけ現在の値を増し、プログレスバーを再表示します。現在の
値が最大値を超えたら、超過分を切り捨て最大値にします。
@c COMMON

@item @var{proc} 'finish
@c EN
Puts the progress bar to the ``finished'' state, then redisplays it.
The time part shows the total elapsed time, and the line is terminated
by @code{#\newline} so that it won't be clobbered.   Once a progress
bar becomes ``finished'', there's no way to put it back ``in progress''.
@c JP
プログレスバーを「終了」状態にし、再表示します。時間部はトータルの経過
時間を表示します。また、表示行末は@code{#\newline}とし、上書きされない
ようにします。プログレスバーはいったん「終了」状態になれば、「進捗中」
状態に戻す方法はありません。
@c COMMON

@item @var{proc} 'set-info @var{text}
@c EN
Changes the text displayed in the ``info'' part.  To use the info part,
you have to give a positive value to @var{info-width} keyword argument
of @code{make-text-progress-bar}.
@c JP
``info''部に表示されるテキストを変更します。
info部を使うには、@code{make-text-progress-bar}の@var{info-width}キーワード
引数に正の値が指定されている必要があります。
@c COMMON


@item @var{proc} 'set-header @var{text}
@c EN
Changes the text displayed in the ``header' area.
@c JP
``header''部に表示されるテキストを変更します。
@c COMMON
@end table

@c EN
The keyword arguments are used to customize the display:
@c JP
キーワード引数を使って表示をカスタマイズできます。
@c COMMON
@table @var
@item header
@c EN
The text to be displayed in the header part.
This can be changed later, by sending @code{set-header} message
to the created progress bar.
@c JP
ヘッダ部に表示するテキスト。このテキストは、作られたプログレスバーに
@code{set-header}メッセージを送ることで後で変更可能です。
@c COMMON

@item header-width
@c EN
The width of the header part, in number of characters.
The header text is displayed left-aligned in the part.
If the header text is longer than the width, the excess characters
are omitted.  The default is 14.
@c JP
ヘッダ部の幅、文字数で指定します。ヘッダ部のテキストは左詰めです。ヘッ
ダ部に置くテキストが幅よりも長い場合には超過分の文字は切り捨てられます。
デフォルトは14文字です。
@c COMMON

@item bar-char
@c EN
A character used to draw a bar chart.  The default is @code{#\#}.
@c JP
バーチャートを描くのに使う文字。デフォルトは@code{#\#}です。
@c COMMON

@item bar-width
@c EN
The width of the bar chart part, in number of characters.
The default is 40.
@c JP
バーチャート部の幅で、文字数で指定します。デフォルトでは40文字です。
@c COMMON

@item num-width
@c EN
The width of the numeric part, in number of characters.
The default is 9.  Setting this to 0 hides the numeric part.
@c JP
数値部の幅で、文字数で指定します。デフォルトでは9で、これを0に設定する
と数値部を隠せます。
@c COMMON

@item num-format
@c EN
A procedure to format the numeric part.  Two arguments are
passed; the current value and the maximum value.  It must return
a string.  The default is the following procedure.
@c JP
数値部を整形する手続き。引数が2つ渡されます。ひとつは現在の値、もうひ
とつは最大値です。この手続きは文字列を返さなければなりません。デフォル
トでは以下の手続きです。
@c COMMON
@example
(lambda (cur max)
  (format "~d/~d" cur max))
@end example

@item time-width
@c EN
The width of the time part, in number of characters.
The default is 7.  Settings this to 0 hides the time part.
@c JP
時間部の幅で、文字数で指定します。デフォルトでは7文字で、これを0に設定
すると時間部を隠せます。
@c COMMON

@item info
@c EN
The text to be displayed in the info part.  This text can be
changed later by sending @code{set-info} message to the created
progress bar.  Note that you have to give a positive number
to @var{info-width} keyword argument to enable the info part.
@c JP
info部に表示されるテキストです。このテキストは、作られたプログレスバーに
@code{set-info}メッセージを送ることで後から変更できます。
info部を表示するには、@var{info-width}キーワード引数に正の値を
与えておく必要があります。
@c COMMON

@item info-width
@c EN
The width of the info part.  The default value is zero,
which means the info part is not displayed.
@c JP
info部の表示幅です。デフォルトは0で、info部は表示されません。
@c COMMON

@item separator-char
@c EN
A character put around the bar part.  Default is @code{#\|}.
You can pass @code{#f} not to display the separators.
@c JP
バー部分の前後に置く文字です。デフォルトでは@code{#\|}です。
セパレータを表示したくなければ、@code{#f}を渡します。
@c COMMON

@item max-value
@c EN
The maximum value of the progress bar.  Default is 100.
@c JP
プログレスバーの最大値です。デフォルトでは100です。
@c COMMON

@item port
@c EN
An output port to which the progress bar is displayed.  The default value
is the current output port when @code{make-text-progress-bar} is called.
@c JP
プログレスバーを表示する出力ポートです。デフォルト値は
@code{make-text-progress-bar}が呼ばれた時点での現在の出力ポートです。
@c COMMON
@end table
@end defun

@c EN
Here's a simple example, using customized numeric part:
@c JP
以下は簡単なカスタマイズをした例です。
@c COMMON

@example
(use text.progress)

(define (main args)
  (define (num-format cur max)
    (format "~d/~d(~3d%)" cur max
            (round->exact (/. (* cur 100) max))))
  
  (let ((p (make-text-progress-bar :header "Example"
                                   :header-width 10
                                   :bar-char #\o
                                   :num-format num-format
                                   :num-width 13
                                   :max-value 256)))
    (do ((i 0 (+ i 1)))
        ((= i 256) (p 'finish))
      (p 'inc 1)
      (sys-select #f #f #f 50000))))
@end example

@c ----------------------------------------------------------------------
@node SQL parsing and construction, Transliterate characters, Showing progress on text terminals, Library modules - Utilities
@section @code{text.sql} - SQL parsing and construction
@c NODE @code{text.sql} - SQLのパーズと構築

@deftp {Module} text.sql
@mdindex text.sql
@c EN
This module provides a utility to parse and construct SQL statement.
@c JP
このモジュールはSQL文のパーズと構築のためのユーティリティを提供します。
@c COMMON

@c EN
It is currently under development, and we only have a tokenization routine.
The plan is to define S-expression syntax of SQL and provides a routine
to translate one form to the other.
@c JP
このモジュールは現在まだ開発途上にあります。まだトークン列を生成するルー
チンしかありません。SQLのS式構文を定義して、SQLとその構文との間の変換
ルーチンを提供する計画です。
@c COMMON

@c EN
Note: If you're looking for a routine to escape strings to be
safe in SQL, see @code{dbi-escape-sql} in @ref{DBI user API}.
@c JP
註: SQLに安全に渡せるように文字列をエスケープするルーチンをお探しなら、
@ref{DBI user API}の@code{dbi-escape-sql}を見てください。
@c COMMON
@end deftp

@defun sql-tokenize sql-string
@c EN
Tokenize a SQL statement @var{sql-string}.  The return value is
a list of tokens, where each token is 
represented by one of the following forms.
@c JP
SQL文@var{sql-string}をトークン列に分解します。返り値はトークンのリス
トで、各トークンは以下の形式のひとつで表現されます。
@c COMMON

@c EN
@example
<symbol>              Special delimiter.  One of the followings:
                      + - * / < = > <> <= >= ||
<character>           Special delimiter.  One of the followings:
                      #\, #\. #\( #\) #\;
<string>              Regular identifier
(delimited <string>)  Delimited identifier
(parameter <num>)     Positional parameter (?)
(parameter <string>)  Named parameter (:foo)
(string    <string>)  Character string literal
(number    <string>)  Numeric literal
(bitstring <string>)  Binary string.  <string> is like "01101"
(hexstring <string>)  Binary string.  <string> is like "3AD20"
@end example
@c JP
@example
<symbol>              特殊区切り子、以下のどれか
                      + - * / < = > <> <= >= ||
<character>           特殊区切り子、以下のどれか
                      #\, #\. #\( #\) #\;
<string>              通常の識別子
(delimited <string>)  区切られた識別子
(parameter <num>)     位置パラメータ (?)
(parameter <string>)  名前つきパラメータ (:foo)
(string    <string>)  文字列リテラル
(number    <string>)  数値リテラル
(bitstring <string>)  バイナリ文字列  <string> は "01101" な感じ
(hexstring <string>)  Binary string.  <string> は "3AD20" な感じ
@end example
@c COMMON

@c EN
If it encounters an untokenizable string, it raises an
@code{<sql-parse-error>} condition.
@c JP
トークンに分解できない文字列がくると@code{<sql-parse-error>}コンディショ
ンがあがります。
@c COMMON
@end defun

@deffn {Condition Type} <sql-parse-error>
@c EN
A condition to indicate an SQL parse error.  Inherits @code{<error>}.
@c JP
SQLパーズエラーを示すコンディション。@code{<error>}を継承。
@c COMMON
@defivar <sql-parse-error> sql-string
@c EN
Holds the source SQL string.
@c JP
元のSQL文字列を保持。
@c COMMON
@end defivar
@end deffn

@c ----------------------------------------------------------------------
@node Transliterate characters, Lazy text construction, SQL parsing and construction, Library modules - Utilities
@section @code{text.tr} - Transliterate characters
@c NODE 文字変換, @code{text.tr} - 文字変換

@deftp {Module} text.tr
@mdindex text.tr
@c EN
This module implements a transliterate function,
that substitutes characters of the input string.
This functionality is realized in Unix @code{tr(1)} command,
and incorporated in various programs such as @code{sed(1)}
and @code{perl}.

Gauche's @code{tr} is aware of multibyte characters.
@c JP
このモジュールは、入力ストリームから指定の文字を置き換えて出力する、
文字変換(transliterate)機能を提供します。
Unixの@code{tr(1)}コマンドで実装され、@code{sed}や@code{perl}にも
採り入れられている機能です。

Gaucheの@code{tr}はマルチバイト文字／文字列を正しく扱います。
@c COMMON
@end deftp

@defun tr from-list to-list :key :complement :delete :squeeze :table-size :input :output
@c EN
Reads from @var{input} and writes to @var{output},
with transliterating characters in @var{from-list} to the
corresponding ones in @var{to-list}.  Characters that doesn't
appear in @var{from-list} are passed through.
@c JP
@var{input}から文字を読み込み、その文字が@var{from-list}内にあれば
対応する@var{to-list}内の文字に置き換えて、@var{output}へと書き出します。
@var{from-list}に無い文字はそのまま@var{output}へと渡されます。
@c COMMON

@c EN
The default values of @var{input} and @var{output} are
current input port and current output port, respectively.
@c JP
@var{input}と@var{output}の既定値はそれぞれ現在の入力ポートと
出力ポートです。
@c COMMON

@c EN
Both @var{from-list} and @var{to-list} must be strings.
They may contain the following special syntax.
Other characters that doesn't fits in the syntax are taken as they are.
@c JP
@var{from-list}と@var{to-list}は文字列でなければなりません。
その中には次のような表記を使うことができます。それ以外の文字はそのまま使われます。
@c COMMON

@table @code
@item @b{x-y}
@c EN
Expanded to the increasing sequence of characters from @code{x} to @code{y},
inclusive.  The order is determined by the internal character
encoding system; generally it is safer to limit use of this within
the range of the same character class.   The character @code{x}
must be before @code{y}.
@c JP
文字@code{x}から文字@code{y}までの文字の昇順の並びと解釈されます。
@code{x}と@code{y}は含まれます。文字の並びはGaucheの内部文字エンコーディングに
よって決定されるので、一般には@code{x}と@code{y}は同じキャラクタクラスの中に
止めておいた方が安全でしょう。@code{x}は@code{y}より小さくなければなりません。
@c COMMON

@item @b{x*n}
@c EN
Repeat @code{x} for @code{n} times.  @code{n} is a decimal number notation.
Meaningful only in
@var{to-list}; it is an error to use this form in @var{from-list}.
If @code{n} is omitted or zero, @code{x} is repeated until @var{to-list}
matches the length of @var{from-list} (any character after it is ignored).
@c JP
文字@code{x}の@code{n}個の並び。@code{n}は10進数で表記された数値です。
これは@var{to-list}でのみ有効で、@var{from-list}で使うとエラーになります。
@code{n}が省略されるか0の場合、@code{x}は@var{to-list}の長さが@var{from-list}
の長さに達するまで繰り返されます(その場合、@var{to-list}の残りは無視されます)。
@c COMMON

@item @b{@code{\}x}
@c EN
Represents @code{x} itself.  Use this escape to avoid a special
character to be interpreted as itself.   Note that if you place
a backslash in a string, you must write @code{\\}, for the Scheme
reader also interprets backslash as a special character.

There's no special sequence to represent non-graphical characters,
for you can put such characters by the string syntax.
@c JP
文字@code{x}それ自身。特殊文字そのものを埋め込みたい場合に使います。
文字列のリーダも@code{\}を解釈するので、@code{\\}と書かねばならないことに注意
して下さい。

グラフィカルでない文字のための構文はありません。文字列リーダの構文を使って
そのような文字を文字列に含めることができます。
@c COMMON
@end table

@c EN
Here's some basic examples.
@example
;; @r{swaps case of input}
(tr "A-Za-z" "a-zA-Z")

;; @r{replaces 7-bit non-graphical characters to `?'}
(tr "\x00-\x19\x7f" "?*")
@end example
@c JP
いくつか例を挙げます。
@example
;; @r{大文字と小文字を交換します}
(tr "A-Za-z" "a-zA-Z")

;; @r{ひらがなとかたかなを交換します}
(tr "ぁ-んァ-ン" "ァ-ンぁ-ん")

;; @r{7ビットのノングラフィカルな文字を`?'に変換します}
(tr "\x00-\x19\x7f" "?*")
@end example
@c COMMON

@c EN
If @var{to-list} is shorter than @var{from-list}, the behavior
depends on the keyword argument @var{delete}.  If a true value is
given,  characters that appear in @var{from-list} but not
in @var{to-list} are deleted.   Otherwise, 
the extra characters in @var{from-list} are just passed through.
@c JP
@var{to-list}が@var{from-list}より短い場合、動作はキーワード引数@var{delete}に
依存します。もし真の値が@var{delete}に与えられれば、@var{from-list}に現われて
@var{to-list}に対応するものがない文字は入力から取り除かれます。そうでなければ
そのような文字はそのまま出力されます。
@c COMMON

@c EN
When a true value is specified to @var{complement},
the character set in @var{from-list} is complemented.
Note that it implies @emph{huge} set of characters,
so it is not very useful unless either output character
set is a single character (using `*') or used with
@code{delete} keyword.
@c JP
真の値が@var{complement}に与えられた場合、@var{from-list}の文字の
補集合が@var{from-list}として使われます。この文字集合は極めて大きくなる
可能性があることに注意してください。従って、一般にこのオプションは
@var{to-list}に`*'を使ってそれらの文字を一文字にマッピングするか、
@code{delete}オプションと併用するかしないとあまり意味がありません。
@c COMMON

@c EN
When a true value is specified to @var{squeeze},
the sequence of the same replaced characters is squeezed to one.
If @var{to-list} is empty, the sequence of the same characters
in @var{from-list} is squeezed.
@c JP
真の値が@var{squeeze}に与えられた場合、同じ文字への置換が2つ以上並ぶ場合に
2つめ以降の文字が削除されます。@var{to-list}が空の場合は、@var{from-list}
に含まれる文字で同一文字が並んだ場合に2つめ以降の文字が削除されます。
@c COMMON

@c EN
Internally, @code{tr} builds a table to map the characters for
efficiency.  Since Gauche can deal with potentially huge set
of characters, it limits the use of the table for only smaller
characters (<256 by default).  If you want to transliterate
multibyte characters on the large text, however, you might want 
to use larger table, trading off the memory usage.  You can specify
the internal table size by @var{table-size} keyword argument.
For example, if you transliterate lots of EUC-JP hiragana text
to katakana, you may want to set table size greater than 42483
(the character code of the last katakana).
@c JP
内部的に、@code{tr}はキャラクタのマッピングのためにテーブルを使用します。
但し、Gaucheでは極めて大きな文字セットを扱うため、テーブルはキャラクタコードの
小さい文字のみに対して使われます(デフォルトではコード255以下の文字)。
もし、より大きな文字を頻繁に変換することが分かっていて、メモリを余分に使っても
速度を上げたい場合は、このテーブルの大きさを@var{table-size}キーワード引数で
指定することができます。例えばEUC-JPコードで大量の平仮名と片仮名を変換する場合は、
@var{table-size}を42483以上にすると、全ての変換がテーブルルックアップで
行われます。
@c COMMON

@c EN
Note that the pre-calculation to build the transliterate table
needs some overhead.  If you want to call @code{tr} many times
inside loop, consider to use @code{build-transliterator} described below.
@c JP
@code{tr}が変換テーブルを計算するのにいくらかオーバーヘッドがあることに
注意して下さい。内側のループで@code{tr}を繰り返し呼ぶような場合は
下に示す@code{build-transliterator}を使った方が良いでしょう。
@c COMMON
@end defun

@defun string-tr string from-list to-list :key :complement :delete :squeeze :table-size
@c EN
Works like @code{tr}, except that input is taken from a string @var{string}.
@c JP
入力を@var{string}から取って変換結果を文字列で返す以外は@code{tr}と同じです。
@c COMMON
@end defun

@defun build-transliterator from-list to-list :key :complement :delete :squeeze :table-size :input :output
@c EN
Returns a procedure that does the actual transliteration.  This effectively
``pre-compiles'' the internal data structure.   If you want to run
@code{tr} with the same sets repeatedly, you may build the procedure
once and apply it repeatedly, saving the overhead of initialization.
@c JP
実際の変換動作をする手続きを作成して返します。内部データのセットアップを済ませるため、
同じ文字変換セットに対して@code{tr}を繰り返し呼ぶような場合は、この手続きを用いることで
初期化のオーバヘッドを軽減することができます。
@c COMMON

@c EN
A note for an edge case:
When @var{input} and/or @var{output} keyword arguments are omitted,
the created transliterator is set up to use current-input-port and/or
current-output-port at the time transliterator is called.
@c JP
註記：@var{input}や@var{output}キーワード引数が省略された場合、
作成される変換手続きは、それが使用された時点でのカレント入出力ポート
を参照します。
@c COMMON

@example
(with-input-from-file "huge-file.txt"
  (lambda ()
    (let loop ((line (read-line)))
      (unless (eof-object? line) (tr "A-Za-z" "a-zA-Z")))))

@c EN
;; @r{runs more efficiently...}
@c JP
;; @r{以下の方が効率良く動作します...}
@c COMMON

(with-input-from-file "huge-file.txt"
  (lambda ()
    (let ((ptr (build-transliterator "A-Za-z" "a-zA-Z")))
      (let loop ((line (read-line)))
        (unless (eof-object? line) (ptr))))))
@end example

@end defun

@c ----------------------------------------------------------------------
@node Lazy text construction, Unicode utilities, Transliterate characters, Library modules - Utilities
@section @code{text.tree} - Lazy text construction
@c NODE 怠惰なテキスト構築, @code{text.tree} - 怠惰なテキスト構築

@deftp {Module} text.tree
@mdindex text.tree
@c EN
Defines simple but commonly used functions for a text construction.

When you generate a text by a program, 
It is a very common operation to concatenate text segments.
However, using string-append repeatedly causes unnecessary
copying of intermediate strings, and sometimes such intermediate
strings are discarded due to the error situation (for example,
think about constructing an HTML document in the CGI script).

The efficient technique is to delay concatenation of those
text segments until it is needed.  In Scheme it is done very
easily by just consing the text segments together, thus forming
a tree of text, and then traverse the tree to construct a text.
You can even directly writes out the text during traversal,
avoiding intermediate string buffer.
(Hans Boehm's ``cord'' library, which comes with his garbage
collector library, uses this technique and proves it is very
efficient for editor-type application).

Although the traversal of the tree can be written in a
few lines of Scheme, I provide this module in the spirits
of OnceAndOnlyOnce.   Also it's easier if we have a common interface.
@c JP
テキストを生成する場合によく使われるシンプルな手続きを定義します。

プログラムでテキストを生成する場合、テキストの断片をつなぎ合わせて行く操作が
非常に多く現われます。しかし単純に@code{string-append}を繰り返し
呼んでしまうと、中間結果の文字列を保持するためだけにメモリアロケーションが多発しますし、
途中でエラーが発生した場合にその中間結果は結局捨てられてしまうかもしれません
(例えば、CGIスクリプト中でHTMLドキュメントを構築してゆくような場合を考えてみて下さい)。

よく知られた効率の良い方法は、テキストの断片をつなぎ合わせるのを本当に必要に
なるまで遅らせることです。Schemeではそれは非常に簡単です。単に断片をコンス
していって木構造を作り、最後にそれをトラバースしてテキストを作成するのです。
場合によっては、トラバースしながらテキストを出力すれば事足りてしまうので、
中間結果のバッファを持つ必要さえありません。
(Hans Boehmのガベージコレクションライブラリに附属している ``cord'' ライブラリ
はこのテクニックを実装したもので、エディタ等のアプリケーションで非常に効率良く
動作することが知られています)。

木構造をトラバースする手続きなどほんの2〜3行で書けてしまいますが、
「一度、そして一度だけ」の精神の下に、このモジュールを提供します。
インタフェースが統一されてたほうが便利ですしね。
@c COMMON
@end deftp

@deffn {Generic Function} write-tree tree :optional out
@c EN
Writes out an @var{tree} as a tree of text, to the output port @var{out}.
If @var{out} is omitted, the current output port is used.

Two methods are defined for this generic function, as shown below.
If you have more complex behavior, you can define more methods
to customize the behavior.
@c JP
@var{tree}をテキストの木構造とみなして、出力ポート@var{out}に出力します。
@var{out}が省略された場合は現在の出力ポートが使われます。

下に示す2つのメソッドが定義されています。より複雑な動作をさせたい場合は、
単純なリストの替わりにノードとなるクラスを定義して、それにメソッドを定義するようにすれば
動作をカスタマイズできます。
@c COMMON
@end deffn

@deffn {Method} write-tree ((tree <list>) out)
@deffnx {Method} write-tree ((tree <top>) out)
@c EN
Default methods.  For a list, @code{write-tree} is recursively
called for each element.  Any objects other than list is written out
using @code{display}.
@c JP
@code{write-tree}の既定の動作です。@var{tree}がリストなら、その要素それぞれに
ついて@code{write-tree}を呼び出します。それ以外のオブジェクトに関しては
@code{display}を呼んで出力します。
@c COMMON
@end deffn

@defun tree->string tree
@c EN
Just calls the @code{write-tree} method for @var{tree} using
an output string port, and returns the result string.
@c JP
出力文字列ポートを作成して@code{write-tree}を呼び、生成された文字列を返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Unicode utilities, Combination library, Lazy text construction, Library modules - Utilities
@section @code{text.unicode} - Unicode utilities
@c NODE Unicodeユーティリティ, @code{text.unicode} - Unicodeユーティリティ

@deftp {Module} text.unicode
@mdindex text.unicode
This module provides various operations on a sequence of Unicode codepoints.

Gauche can be compiled with a native encoding other than Unicode,
and the full Unicode-compatible behavior on characters and strings may
not be available on such systems.  So we provide most operations in two
flavors: Operations on characters and strings, or operations on
codepoints represented as a sequence of integers.

If Gauche is compiled with its native encoding being @code{none},
@code{euc-jp} or @code{sjis}, character-and-string operations
are likely to be partial functions of the operations defined
in Unicode standard.  That is, if the operation can yield a
character that are not supported in the native encoding, it
may be remapped to an alternative character.  Each manual entry
explains the detailed behavior.

The codepoint operations are independent from Gauche's native
encoding and supports full spec as defined in Unicode standard.
If Gauche is compiled with the @code{utf-8} native encoding,
the operations are essentially the same as character-and-string flavors
when you convert codepoints and characters by @code{char->integer} and
@code{integer->char}.  The codepoint operations are handy when
you need to support the algorithms described in Unicode standard
fully, no matter what the running Gauche's native encoding is.
@end deftp

@menu
* Unicode transfer encodings::  
* Unicode text segmentation::   
* Full string case conversion::      
@end menu

@node Unicode transfer encodings, Unicode text segmentation, Unicode utilities, Unicode utilities
@subsection Unicode transfer encodings

The procedures in this group operate on codepoints represented as integers.
In the following descriptions, `octets' refers to an integer
between 0 to 255, inclusive.

They take optional @var{strictness} argument.  It specifies
what to do when the procedure encounters a datum outside
of the defined domain.  Its value can be either one of the
following symbols:

@table @code
@item strict
Raises an error when the procedure encounters such input.
This is the default behavior.
@item permissive
Whenever possible, treat the date as if it is a valid value.
For example, codepoint value beyond @code{#x10ffff} is invalid
in Unicode standard, but it may be useful for some other purpose
that just want to use UTF-8 as an encoding scheme of binary data.
@item ignore
Whenver possible, treat the invalid input as if they do not exist.
@end table

The procedure may still raise an error in @code{permissive} or
@code{ignore} strictness mode, if there can't be a sensible
way to handle the input data.

@defun ucs4->utf8 codepoint :optional strictness
Takes an integer codepoint and returns list of octets that
encodes the input in UTF-8.

@example
(ucs4->utf8 #x3bb)  @result{} (206 187)
(ucs4->utf8 #x3042) @result{} (227 129 130)
@end example

If @var{strictness} is @code{strict} (default), input codepoint
between @code{#xd800} to @code{#xdfff}, and beyond @code{#x110000},
are rejected.  If @var{strictness} is @code{permissive}, it accepts
input between @code{0} and @code{#x7fffffff}, inclusive; it may produce
5 or 6 octets if the input is large (as the original UTF-8 definition).
If @var{strictness} is @code{ignore}, it returns an empty list
for invalid codepoints.
@end defun

@defun utf8-length octet :optional strictness
Takes @var{octet} as the first octet of UTF-8 sequence, and
returns the number of total octets requried to decode
the codepoint.

If @var{strictness} is @code{strict} (default), this
procedure returns either 1, 2, 3 or 4.   An error is
thrown if @var{octet} cannot be a leading octet of
a proper UTF-8 encoded Unicode codepoint.

If @var{strictness} is @code{permissive}, this procedure
may return an integer between 0 and 6, inclusive.
It allows the codepoint range @code{#x110000} to
@code{#x7fffffff} as the original utf-8 spec, so
the maximum number of octets can be up to 6.
If the input is in the range between @code{#xc0} 
and @code{#xdf}, inclusive, this procedure returns
1--it's up to the application how to treat these illegal
octets.  For other values, it returns @code{0}.

If @var{strictness} is @var{ignore}, this procedure
returns @code{0} when it would raise an error if
@var{strictness} is @code{strict}.  Other than that,
it works the same as the default case.
@end defun

@defun utf8->ucs4 octet-list :optional strictness
Takes a list of octets, and decodes it as a utf-8 sequence.
Returns two values: The decoded ucs4 codepoint, and the
rest of the input list.

An invalid utf8 sequence causes an error if @var{strictness}
is @code{strict}, or skipped if it is @code{ignore}.
If @var{strictness} is @code{permissive}, the procedure accepts
the original utf-8 sequence which can produce surrogated pair
range (between @code{#xd800} and @code{#dfff}) and the range
between @code{#x110000} to @code{#x7fffffff}.  The invalid
octet sequence is still an error with @code{permissive} mode.
@end defun

@defun ucs4->utf16 codepoint :optional strictness
@end defun

@defun utf16-length octet :optional strictness
@end defun

@defun utf16->ucs4 octet-list :optional strictness
@end defun

@node Unicode text segmentation, Full string case conversion, Unicode transfer encodings, Unicode utilities
@subsection Unicode text segmentation

These procedures implements grapheme-cluster and
word breaking algorithms defined in UAX #29: Unicode Text Segmentation.

@defun string->words string
@defunx codepoints->words sequence
From given string or codepoint sequence (a @code{<sequence>}
object containing list of codepoints), returns a list of
words.  Each cluster is represented as a string, or 
a sequence of the same type as input, respectively.

@example
(string->words "That's it.")
 @result{} ("That's" " " "it" ".")
(codepoints->words '(84 104 97 116 39 115 32 105 116 46)
 @result{} ((84 104 97 116 39 115) (32) (105 116) (46))
@end example

In the second example, the list is a list of codepoints
of characters in "That's it."
@end defun


@defun string->grapheme-clusters string
@defunx codepoints->grapheme-clusters sequence
From given string or codepoint sequence (a @code{<sequence>}
object containing list of codepoints), returns a list of
grapheme clusters.  Each cluster is represented as a string,
or a sequence of the same type as input, respectively.
@end defun


The following procedures are low-level building blocks
to build the above @code{string->words} etc.
A @var{generator} argument is a procedure
with no arguments, and returns a value (or some values) at at time
for every call, until it returns EOF.

@defun make-word-breaker generator
@defunx make-grapheme-cluster-breaker generator
From given @var{generator} is a generator of characters or codepoints,
returns a generator that returns two values: The first value is the
character or codepoint generated from the original generator, and the
second value is a boolean flag, which is @code{#t} if a word
or a grapheme cluster
breaks before the character/codepoint, and @code{#f} otherwise.

Suppose a generator @var{g} returns characters in a string
@code{That's it.}, one at a time.  Then the created generator
will work as follows:

@example
(define brk (make-word-breaker g))
(brk)  @result{}  #\T     and #t
(brk)  @result{}  #\h     and #f
(brk)  @result{}  #\a     and #f
(brk)  @result{}  #\t     and #f
(brk)  @result{}  #\'     and #f
(brk)  @result{}  #\s     and #f
(brk)  @result{}  #\space and #t
(brk)  @result{}  #\i     and #t
(brk)  @result{}  #\t     and #f
(brk)  @result{}  #\.     and #t
(brk)  @result{}  #<eof>  and #t
@end example

It shows the word breaks at those character boundaries shown
by the caret @code{^} below (for clearity, I use @code{_} to indicate
the space).

@example
  T h a t ' s _ i t .
 ^           ^ ^   ^ ^
@end example
@end defun

@defun make-word-reader generator return
@defunx make-grapheme-cluster-reader generator return
The input @var{generator} is a generator of characters or codepoints,
and @var{return} is a procedure that takes a list of characters or
codepoints, and returns an object.   These procedures creates a
generator that returns an object at at time, each consists of a
word or a grapheme cluster, respectively.

Suppose a generator @var{g} returns characters in a string
@code{That's it.}, one at a time, again.
Then the created generator works as follows:

@example
(define brk (make-word-reader g list->string))
(brk)  @result{}  "That's"
(brk)  @result{}  " "
(brk)  @result{}  "it"
(brk)  @result{}  "."
(brk)  @result{}  #<eof>
@end example

@end defun


@node Full string case conversion,  , Unicode text segmentation, Unicode utilities
@subsection Full string case conversion

@defun string-upcase string
@defunx string-downcase string
@defunx string-titlecase string
@defunx string-foldcase string
[R6RS]
Converts given @var{string} to upper case, using language-independent
full case folding defined by Unicode standard.
They differ from srfi-13's procedures
with the same names (@xref{SRFI-13 String case mapping}),
which simply uses character-by-character case mapping.
Notably, the length of resulting string may differ from the source string,
and some conversions are sensitive to whether the character is at the
word boundary or not.  The word boundaries are determined according
to UAX #29 text segmentation rules.

@example
(string-upcase "straße")
 @result{} "STRASSE"
(string-downcase "ΧΑΟΣΧΑΟΣ.ΧΑΟΣ. Σ.")
 @result{} "χαοσχαοσ.χαος. σ."
(string-titlecase "You're talking about R6RS, right?")
 @result{} "You're Talking About R6rs, Right?"
(string-foldcase "straße")
 @result{} "strasse"
(string-foldcase "ΧΑΟΣΣ")
 @result{} "χαοσσ"
@end example

@end defun

@defun codepoints-upcase sequence
@defunx codepoints-downcase sequence
@defunx codepoints-titlecase sequence
@defunx codepoints-foldcase sequence
Like @code{string-upcase} etc, but these work on a sequence of
codepoints instead.  Returns a sequence of the same type of the input.

@example
(codepoints-upcase '#(115 116 114 97 223 101))
 @result{} #(83 84 82 65 83 83 69)
@end example
@end defun


@c ----------------------------------------------------------------------
@node Combination library, Message digester framework, Unicode utilities, Library modules - Utilities
@section @code{util.combinations} - Combination library
@c NODE 組み合わせ, @code{util.combinations} - 組み合わせ

@deftp {Module} util.combinations
@mdindex util.combinations
@c EN
This module implements several useful procedures of
combinations, permutations and related operations.

Most procedures in the module have two variants: a procedure without
star (e.g. @code{permutations}) treats all elements in the given
set distinct, while a procedure with star (e.g. @code{permutations*})
considers duplication.  The procedures with star take optional @var{eq}
argument that is used to test equality, which defaults to @code{eqv?}.
@c JP
このモジュールは、いくつかの便利なコンビネーションや順列とそれに関連する
操作の手続きを実装しています。

このモジュールのほとんどの手続きは2つのバージョンを持っています。
1つはアスタリスクの付かない手続き(例えば、@code{permutations})で、
与えられたセットにある全ての要素を区別して扱います。もう1つは、
アスタリスクの付く手続き(例えば、@code{permutations*})で、重複を
考慮します。アスタリスクの付く手続きは、オプショナルな@var{eq}引数を取り
ます。それは等値性のテストに使われ、デフォルトは@code{eqv?}です。
@c COMMON
@end deftp

@defun permutations set
@defunx permutations* set :optional eq
@c EN
Returns a list of all permutations of a list @var{set}.
@c JP
リスト@var{set}の全ての順列のリストを返します。
@c COMMON

@example
(permutations '(a b c))
  @result{} ((a b c) (a c b) (b a c) (b c a) (c a b) (c b a))

(permutations '(a a b))
  @result{} ((a a b) (a b a) (a a b) (a b a) (b a a) (b a a))

(permutations* '(a a b))
  @result{} ((a a b) (a b a) (b a a))
@end example

@c EN
The number of possible permutations explodes if @var{set} has
more than several elements.  Use with care.  If you want to process
each permutation at a time, consider @code{permutations-for-each} below.
@c JP
@var{set}がある程度の要素を持っている場合、可能性のある順列の数は
爆発的に大きくなります。注意して使って下さい。
一度にそれぞれの順列を処理したい場合は、下記の@code{permutations-for-each}の
使用を考慮して下さい。
@c COMMON
@end defun

@defun permutations-for-each proc set
@defunx permutations*-for-each proc set :optional eq
@c EN
For each permutation of a list @var{set}, calls @var{proc}.
Returns an undefined value.
@c JP
リスト@var{set}のそれぞれの順列に対して、@var{proc}を呼び出します。
戻り値は未定義値です。
@c COMMON
@end defun

@defun combinations set n
@defunx combinations* set n :optional eq
@c EN
Returns a list of all possible combinations of @var{n} elements out
of a list @var{set}.
@c JP
リスト@var{set}の@var{n}個の要素の可能性のある全ての順列のリストを
返します。
@c COMMON

@example
(combinations '(a b c) 2)
  @result{} ((a b) (a c) (b c))

(combinations '(a a b) 2)
  @result{} ((a a) (a b) (a b))

(combinations* '(a a b) 2)
  @result{} ((a a) (a b))
@end example

@c EN
Watch out the explosion of combinations when @var{set} is large.
@c JP
@var{set}が大きいときは、組み合わせの爆発について注意して下さい。
@c COMMON
@end defun

@defun combinations-for-each proc set n
@defunx combinations*-for-each proc set n :optional eq
@c EN
Calls @var{proc} for each combination of @var{n} elements out of @var{set}.
Returns an undefined value.
@c JP
@var{set}の@var{n}個の要素のそれぞれの組み合わせについて@var{proc}を
呼び出します。戻り値は未定義値です。
@c COMMON
@end defun

@defun power-set set
@defunx power-set* set :optional eq
@c EN
Returns power set (all subsets) of a list @var{set}.
@c JP
リスト@var{set}の累乗集合(全てのサブセット)を返します。
@c COMMON

@example
(power-set '(a b c))
  @result{} (() (a) (b) (c) (a b) (a c) (b c) (a b c))

(power-set* '(a a b)
  @result{} (() (a) (b) (a a) (a b) (a a b))
@end example
@end defun

@defun power-set-for-each proc set
@defunx power-set*-for-each proc set :optional eq
@c EN
Calls @var{proc} for each subset of @var{set}.
@c JP
@var{set}のそれぞれのサブセットについて@var{proc}を呼び出す。
@c COMMON
@end defun

@defun power-set-binary set
@c EN
Returns power set of @var{set}, like @code{power-set}, but in different order.
@code{Power-set-binary} traverses subset space in depth-first order,
while @code{power-set} in breadth-first order.
@c JP
@code{power-set}のように、@var{set}の累乗集合を返しますが、順番が異なります。
@code{power-set-binary}はサブセットの空間を深さ優先でトラバースしますが、
@code{power-set}は横型探索を行います。
@c COMMON

@example
(power-set-binary '(a b c))
  @result{} (() (c) (b) (b c) (a) (a c) (a b) (a b c))
@end example
@end defun

@defun cartesian-product list-of-sets
@defunx cartesian-product-right list-of-sets
@c EN
Returns a cartesian product of sets in @var{list-of-sets}.
@code{Cartesian-product} construct the result in left fixed order
(the rightmost element varies first), while 
@code{cartesian-product-right} in right fixed order
(the leftmost element varies first).
@c JP
@var{list-of-sets}にあるセットのデカルト積を返します。
@code{cartesian-product}は左固定順で結果を構築しますが
(一番右の要素がまず異なる)、
@code{cartesian-product-right}は右固定順で行います
(一番左の要素がまず異なる)。
@c COMMON

@example
(cartesian-product '((a b c) (0 1)))
  @result{} ((a 0) (a 1) (b 0) (b 1) (c 0) (c 1))

(cartesian-product-right '((a b c) (0 1)))
  @result{} ((a 0) (b 0) (c 0) (a 1) (b 1) (c 1))
@end example
@end defun

@c ----------------------------------------------------------------------
@node Message digester framework, Determine isomorphism, Combination library, Library modules - Utilities
@section @code{util.digest} - Message digester framework
@c NODE メッセージダイジェストフレームワーク, @code{util.digest} - メッセージダイジェストフレームワーク

@deftp {Module} util.digest
@mdindex util.digest
@c EN
This module provides a base class and common interface for 
message digest algorithms, such as MD5 (@xref{MD5 message digest})
and SHA (@xref{SHA message digest}).
@c JP
このモジュールは、MD5 (@ref{MD5 message digest}参照)や
SHA (@ref{SHA message digest}参照)などの、メッセージ
ダイジェストアルゴリズムのためのベースクラスと一般的なインターフェースを
提供します。
@c COMMON
@end deftp

@deftp {Class} <message-digest-algorithm-meta>
@clindex message-digest-algorithm-meta
@c EN
A metaclass of message digest algorithm implementation.
@c JP
メッセージダイジェストアルゴリズムの実装のメタクラスです。
@c COMMON
@end deftp

@deftp {Class} <message-digest-algorithm>
@clindex message-digest-algorithm
@c EN
A base class of message digest algorithm implementation.
@c JP
メッセージダイジェストアルゴリズムの実装のベースクラスです。
@c COMMON
@end deftp

@c EN
The concrete subclass of message digest algorithm has to
implement the following methods.
@c JP
メッセージダイジェストアルゴリズムの具体サブクラスは、以下のメソッドを
実装しなければなりません。
@c COMMON

@deffn {Generic function} digest-update! algorithm data
@c EN
Takes the instance of massage-digest algorithm, and updates it
with the data @var{data}, represented in a (possibly incomplete) string.
@c JP
メッセージダイジェストアルゴリズムのインスタンスを取り、
それを(不完全な可能性のある)文字列で表されるデータ@var{data}で
更新します。
@c COMMON
@end deffn

@deffn {Generic function} digest-final! algorithm
@c EN
Finalizes the instance of message-digest algorithm, and
returns the digest result in an incomplete string.
@c JP
メッセージダイジェストアルゴリズムのインスタンスを終了させ、
そのダイジェストの結果を不完全文字列で返します。
@c COMMON
@end deffn

@deffn {Generic function} digest class
@c EN
A wrapper of digest routines.  Given message-digest algorithm @var{class},
this function reads the input data from current input port until EOF,
and returns the digest result in an incomplete string.
@c JP
ダイジェストルーチンのラッパです。メッセージダイジェストアルゴリズム
@var{class}を与え、現在の入力ポートから入力データをEOFまで読み込み、
そのダイジェストの結果を不完全文字列で返します。
@c COMMON
@end deffn

@deffn {Generic function} digest-string class string
@c EN
A wrapper of digest routines.  Given message-digest algorithm @var{class},
this function reads the input data from @var{string},
and returns the digest result in an incomplete string.
@c JP
ダイジェストルーチンのラッパです。メッセージダイジェストアルゴリズム
@var{class}を与え、入力データを@var{string}から読み込み、
そのダイジェストの結果を不完全文字列で返します。
@c COMMON
@end deffn

@defun digest-hexify digest-result
@c EN
An utility procedure.  Given the result of digest, @var{digest-result},
converts it to a hexified string.
@c JP
ユーティリティ手続きです。ダイジェストの結果、@var{digest-result}を
与えると、それを16進文字列に変換します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Determine isomorphism, The longest common subsequence, Message digester framework, Library modules - Utilities
@section @code{util.isomorph} - Determine isomorphism
@c NODE 同型判定, @code{util.isomorph} - 同型判定

@deftp {Module} util.isomorph
@mdindex util.isomorph
@c EN
Provides a procedure that determines whether two structures are
isomorphic.
@c JP
二つの構造が同型かどうかを判定する手続きを提供するモジュールです。
@c COMMON
@end deftp

@defun isomorphic? obj1 obj2 :optional context
@c EN
Returns @code{#t} if @var{obj1} and @var{obj2} are isomorphic.

@var{context} is used if you want to call @code{isomorphic?}
recursively inside @code{object-isomorphic?} described below.
@c JP
@var{obj1}と@var{obj2}が同型であれば@code{#t}を返します。

省略可能な引数@var{context}は、下で説明する@code{object-isomorphic?}
の中から@code{isomorphic?}を再帰的に呼び出す場合に使います。
@c COMMON

@example
(isomorphic? '(a b) '(a b)) @result{} #t

(define x (cons 0 0))
(define y (cons 0 0))
(isomorphic? (cons x x)
             (cons x y))
 @result{} #f
(isomorphic? (cons x x)
             (cons y y))
 @result{} #t
@end example
@end defun

@deffn {Generic Function} object-isomorphic? obj1 obj2 context
@c EN
With this method, you can customize how to determine isomorphism of
two objects.  Basically, you will call @code{isomorphic?} recursively
for each slots of object you want to traverse; the method should return
@code{#t} if all of the test succeeds, or return @code{#f} otherwise.
@var{context} is an opaque structure
that keeps the traversal context, and you should pass it to
@code{isomorphic?} as is.

The default method returns @code{#t} if @var{obj1} and @var{obj2} are
equal (in the sense of @code{equal?}).
@c JP
このメソッドで、二つのオブジェクトの同型判定処理をカスタマイズできます。
基本的には、オブジェクトのトラバースしたいスロットに対して@code{isomorphic?}を順に適用し、
全てが成功すれば@code{#t}を、一つでも失敗すれば@code{#f}を返すようにします。
@var{context}はトラバースのコンテクストを保持しているオブジェクトです。そのまま
@code{isomorphic?}に渡して下さい。

デフォルトメソッドは、@var{obj1}と@var{obj2}が@code{equal?}の意味で等しければ
@code{#t}を返します。
@c COMMON
@end deffn

@c ----------------------------------------------------------------------
@node The longest common subsequence, Additional list library, Determine isomorphism, Library modules - Utilities
@section @code{util.lcs} - The longest common subsequence
@c NODE 最長共通サブシーケンス, @code{util.lcs} - 最長共通サブシーケンス

@deftp {Module} util.lcs
@mdindex util.lcs
@c EN
This module implements the algorithm to find the longest common subsequence
of two given sequences.  The implemented algorithm is based on
Eugene Myers' O(ND) algorithm (@ref{myers86,[Myers86],Myers86}).

One of the applications of this algorithm is to calculate
the difference of two text streams;
see @ref{Calculate difference of text streams}.
@c JP
このモジュールは、与えられた2つのシーケンスの最長共通サブシーケンスを見つける
アルゴリズムを実装しています。アルゴリズムは、Eugene Myersの
O(ND)アルゴリズムに基づいています(@ref{myers86,[Myers86],Myers86})。

このアルゴリズムを使うアプリケーションの1つは、2つのテキストストリームの
相違点を計算する@ref{Calculate difference of text streams}です。
@c COMMON
@end deftp

@defun lcs seq-a seq-b :optional eq-fn
@c EN
Calculates and returns the longest common sequence of
two lists, @var{seq-a} and @var{seq-b}.
Optional @var{eq-fn} specifies
the comparison predicate; if omitted, @code{equal?} is used.
@c JP
2つのリスト、@var{seq-a}と@var{seq-b}の最長共通シーケンスを計算して
返します。オプションの@var{eq-fn}では、比較を行う述語を指定します。
省略されると、@code{equal?}が使われます。
@c COMMON

@example
(lcs '(x a b y) '(p a q b))
 @result{} (a b)
@end example
@end defun

@defun lcs-with-positions seq-a seq-b :optional eq-fn
@c EN
This is the detailed version of @code{lcs}.
The arguments are the same.

Returns a list of the following structure:
@c JP
@code{lcs}の詳細バージョンです。引数は同じです。

以下の構造のリストを返します。
@c COMMON

@example
(@var{length} ((@var{elt} @var{a-pos} @var{b-pos}) @dots{}))
@end example

@c EN
@var{Length} is an integer showing the length of the found LCS.
What follows is a list of elements of LCS; each sublist
consists of the element, the integer position of the element
in @var{seq-a}, then the integer position of the element in @var{seq-b}.
@c JP
@var{length}は、見つかったLCS(最長共通サブシーケンス)の長さを表す整数です。
それに続くのは、LCSの要素のリストで、その要素を構成するそれぞれのサブリスト、
@var{seq-a}の中での要素の位置(整数)、@var{seq-b}の中での要素の位置(整数)
となります。
@c COMMON

@example
(lcs-with-positions '(a) '(a))
 @result{} (1 ((a 0 0)))

(lcs-with-positions '(x a b y) '(p q a b))
 @result{} (2 ((a 1 2) (b 2 3)))

(lcs-with-positions '(x a b y) '(p a q b))
 @result{} (2 ((a 1 1) (b 2 3)))

(lcs-with-positions '(x y) '(p q))
 @result{} (0 ())
@end example
@end defun

@defun lcs-fold a-proc b-proc both-proc seed a b :optional eq-fn
@c EN
A fundamental iterator over the "edit list" derived from
two lists @var{a} and @var{b}.

@var{A-proc}, @var{b-proc}, @var{both-proc} are all procedures
that take two arguments.   The second argument is a intermediate
state value of the calculation.  The first value is an element
only in @var{a} for @var{a-proc}, or an element only in @var{b}
for @var{b-proc}, or an element in both @var{a} and @var{b}
for @var{both-proc}.  The return value of each procedure is used
as the state value of the next call of either one of the procedures.
@var{Seed} is used as the initial value of the state value.
The last state value is returned from @code{lcs-fold}.

The three procedures are called in the following order: Suppose the sequence
@var{a} consists of @var{a'}@var{c}@var{a''}, and @var{b} consists of 
@var{b'}@var{c}@var{b''}, where @var{a'}, @var{b'}, @var{a''}, and @var{b''}
are subsequences, and @var{c} is the head of the 
LCS of @var{a} and @var{b}.   Then @var{a-proc} is called first on
each element in @var{a'}, @var{b-proc} is called second on
each element in @var{b'}, then @var{both-proc} is called on @var{c}.
Afterwards, the process is repeated using @var{a''} and @var{b''}.
@c JP
2つのリスト@var{a}と@var{b}から引き出された``編集リスト''に対する
基本的なイテレータです。

@var{a-proc}、@var{b-proc}、@var{both-proc}は全て2引数を取る手続きです。
2番目の引数は、計算の中間の値です。最初の値は、@var{a-proc}では@var{a}にしかない要素、
@var{b-proc}では@var{b}にしかない要素、@var{both-proc}では@var{a}と@var{b}の両方に
ある要素となります。それぞれの手続きが返す値は、次に呼び出される手続きのうちの1つの
状態を表す値として使われます。@var{seed}は、状態を表す値の初期値として使われます。
@code{lcs-fold}が返す値は、最後の状態を表す値です。

これらの3つの手続きは、以下の順番で呼ばれます。ここでは、シーケンス@var{a}は
@var{a'}@var{c}@var{a''}、@var{b}は@var{b'}@var{c}@var{b''}となっているとすると、
ここでは@var{a'}、@var{b'}、@var{a''}、@var{b''}はサブシーケンスで、
@var{c}は@var{a}と@var{b}のLCSの先頭になります。そして、@var{a-proc}はまず
@var{a'}のそれぞれの要素に対して呼ばれ、@var{b-proc}が@var{b'}のそれぞれの
要素に対して呼ばれ、@var{both-proc}が@var{c}に対して呼ばれます。
その後、このプロセスは@var{a''}と@var{b''}を使って繰り返されます。
@c COMMON
@end defun

@defun lcs-edit-list a b :optional eq-fn
@c EN
Calculates 'edit-list' from two lists @var{a} and @var{b}, which is
the smallest set of commands (additions and deletions) that changes
@var{a} into @var{b}.
This procedure is built on top of @code{lcs-fold} above.

Returns a list of @emph{hunk}s, which is a contiguous section of
additions and deletions.  Each hunk consists of a list of
directives, which is a form of:
@c JP
2つのリスト@var{a}と@var{b}から``編集リスト''を計算します。それは、
@var{a}を@var{b}に変更するためのコマンド(追加と削除)の最小セットです。
この手続きは、上の@code{lcs-fold}の上に構築されています。
@c COMMON
@example
(@var{+}|@var{-} @var{position} @var{element})
@end example

@c EN
Here's an example.  Suppose @var{a} and @var{b} are the following
lists, respectively.
@c JP
例を挙げます。@var{a}と@var{b}がそれぞれ以下のようなリストだとします。
@c COMMON

@example
@var{a} @equiv{} ("A" "B" "C" "E" "H" "J" "L" "M" "N" "P")
@var{b} @equiv{} ("B" "C" "D" "E" "F" "J" "K" "L" "M" "R" "S" "T")
@end example

@c EN
Then, @code{(lcs-edit-list a b equal?)} returns the following list.
@c JP
すると、@code{(lcs-edit-list a b equal?)}は以下のリストを返します。
@c COMMON
@example
(((- 0 "A"))
 ((+ 2 "D"))
 ((- 4 "H") (+ 4 "F"))
 ((+ 6 "K"))
 ((- 8 "N") (- 9 "P") (+ 9 "R") (+ 10 "S") (+ 11 "T"))
)
@end example
@c EN
The result consists of five hunks.  The first hunk consists of
one directive, @code{(- 0 "A")}, which means the element @code{"A"}
at the position 0 of list @var{a} has to be deleted.
The second hunk also consists of one directive, @code{(+ 2 "D")},
meaning the element @code{"D"} at the position 2 of list @var{b}
has to be added.  The third hunk means @code{"H"} at the position
4 of list @var{a} should be removed and @code{"F"} at the position
4 of list @var{b} should be added, and so on.

If you are familiar with Perl's Algorithm::Diff module, you may 
notice that this is the same structure that its @code{diff} procedure
returns.
@c JP
結果は5つの片からなります。最初のものは1つのディレクティブ、@code{(- 0 ``A'')}から
なり、これはリスト@var{a}の位置0にある要素@code{``A''}が削除されることを意味します。
2番目のものはまた1つのディレクティブ、@code{(+ 2 ``D'')}からなり、これは
リスト@var{b}の位置2にある要素@code{``D''}が追加されることを意味します。
3番目のものは、リスト@var{a}の位置4にある@code{``H''}は削除され、リスト@var{b}の
位置4にある@code{``F''}が追加される、などとなります。

もしあなたがPerlのAlgorithm::Diffモジュールを良く知っていれば、
その@code{diff}手続きが返すものと同じ構造だということが分かるでしょう。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Additional list library, Pattern matching, The longest common subsequence, Library modules - Utilities
@section @code{util.list} - Additional list library
@c NODE その他のリストライブラリ, @code{util.list} - その他のリストライブラリ

@deftp {Module} util.list
@mdindex util.list
@c EN
This module provides list utility functions which are not in srfi-1
(@xref{List library}) but generally useful.

See also @ref{Collection framework}
and @ref{Sequence framework}, for
these modules also defines useful generic functions that can
be used for lists.
@c JP
このモジュールは、srfi-1 (@ref{List library}参照)にはないが、
一般的に便利なリストユーティリティ関数を提供します。

リストに対して用いることができる便利なジェネリック関数を定義している
@ref{Collection framework}と@ref{Sequence framework}も
見て下さい。
@c COMMON
@end deftp

@defun take* list k :optional fill? padding
@c EN
Returns a list that consists of the first @var{k} elements in
@var{list}, like SRFI-1's @code{take}, except this procedure
is more tolerant.  That is, if @var{list}
is shorter than @var{k}, @code{take*} doesn't signals an error.
Instead, it returns a copy of @var{list} by default (or the optional
argument @var{fill?} is @code{#f}).   If @var{fill?} is true,
@var{padding} is added to the result to make its length @var{k}.
The default value of @var{padding} is @code{#f}.
@c JP
@var{list}の最初の@var{k}個の要素で構成されるリストを返します。
これは、SRFI-1の@code{take}に似ていますが、この手続きのほうが
寛容です。つまり、@var{list}が@var{k}よりも短いとき、@code{take*}は
エラーを通知しません。その代わり、デフォルトで(あるいは、オプショナル
引数@var{fill?}が@code{#f}の場合)@var{list}のコピーを返します。
@var{fill?}が真の場合、その長さを@var{k}にするために、@var{padding}が
その結果に追加されます。@var{padding}のデフォルト値は@code{#f}です。
@c COMMON

@example
(take* '(a b c d) 3)       @result{} (a b c)
(take* '(a b c d) 6)       @result{} (a b c d)
(take* '(a b c d) 6 #t)    @result{} (a b c d #f #f)
(take* '(a b c d) 6 #t 'z) @result{} (a b c d z z)
@end example

@c EN
Note: For generic subsequence extraction from any sequence, 
see @code{subseq} in @ref{Slicing sequence}.
@c JP
注意: 一般的な、いかなるシーケンスからのサブシーケンスの抽出については、
@ref{Slicing sequence}の@code{subseq}を見て下さい。
@c COMMON
@end defun

@defun drop* list k
@c EN
Returns a list that the first @var{k} elements of @var{list} is
dropped, like SRFI-1's @code{drop}, except this procedure
is more tolerant.  If @var{list} is shorter than @var{k},
an empty list is returned.
@c JP
@var{list}の最初の@var{k}個の要素が削除されたリストを返します。
これは、SRFI-1の@code{drop}に似ていますが、この手続きのほうが
寛容です。@var{list}が@var{k}よりも短い場合、空リストが返されます。
@c COMMON

@example
(drop* '(a b c d) 3)       @result{} (d)
(drop* '(a b c d) 5)       @result{} ()
@end example
@end defun

@defun take-right* list k :optional fill? padding
@c EN
Like @code{take*}, but counts from right of @var{list}.
If needed, @var{padding} is added on left of the result.
@c JP
@code{take*}と同じですが、@var{list}の右端からカウントします。
必要ならば、結果の左に@var{padding}が追加されます。
@c COMMON
@end defun

@defun drop-right* list k
@c EN
Like @code{drop*}, but counts from right of @var{list}.
@c JP
@code{drop*}と同じですが、@var{list}の右端からカウントします。
@c COMMON
@end defun

@defun split-at* list k :optional fill? padding
@c EN
More tolerant version of SRFI-1's @code{split-at}.
Returns the results of @code{take*} and @var{drop*}.
@c JP
SRFI-1の@code{split-at}の寛容なバージョンです。
@code{take*}と@var{drop*}の結果を返します。
@c COMMON

@example
(split-at* '(a b c d) 6 #t 'z)
  @result{} (a b c d z z) @r{and} ()
@end example
@end defun

@defun slices list k :optional fill? padding
@c EN
Splits @var{list} into the sublists (slices) where the length of
each slice is @var{k}.
If the length of @var{list} is not a multiple of @var{k},
the last slice is dealt in the same way as @code{take*}; that is,
it is shorter than @var{k} by default, or added @var{padding} if
@var{fill?} is true.
@c JP
@var{list}を、それぞれの長さが@var{k}であるようなサブリスト(スライス)に
分割します。
@var{list}の長さが@var{k}の整数倍でない場合は、最後のスライスは
@code{take*}と同じ方法で扱われます。つまり、デフォルトでは@var{k}より
短いもの、あるいは@var{fill?}が真ならば@var{padding}が追加されます。
@c COMMON

@example
(slices '(a b c d e f g) 3)
  @result{} ((a b c) (d e f) (g))
(slices '(a b c d e f g) 3 #t 'z)
  @result{} ((a b c) (d e f) (g z z))
@end example
@end defun

@defun intersperse item list
@c EN
Inserts @var{item} between elements in the @var{list}.
(The order of arguments is taken from Haskell's intersperse).
@c JP
@var{list}の要素の間に@var{item}を挿入します。
(引数の順番は、Haskellのintersperseと同じです。)
@c COMMON

@example
(intersperse '+ '(1 2 3))  @result{} (1 + 2 + 3)
(intersperse '+ '(1))      @result{} (1)
(intersperse '+ '())       @result{} ()
@end example
@end defun

@defmac cond-list clause @dots{}
@c EN
Construct a list by conditionally adding entries.
Each @var{clause} has a test and expressions.  When its test
yields true, the result of associated expression is used to
construct the resulting list.  When the
test yields false, nothing is inserted.
@c JP
条件によりエントリを追加することによりリストを構築します。
それぞれの@var{clause}は条件と式を持ちます。
条件が真であれば、関連する式の結果が結果のリストの構築に使われます。
条件が偽であれば、何も挿入されません。
@c COMMON

@c EN
@var{Clause} must be either one of the following form:
@table @code
@item (@var{test} @var{expr} @dots{})
@var{Test} is evaluated, and when it is true,
@var{expr} @dots{} are evaluated, and the return value
becomes a part of the result.  If no @var{expr} is given,
the result of @var{test} is used if it is not false.
@item (@var{test} => @var{proc})
@var{Test} is evaluated, and when it is true,
@var{proc} is called with the value, and the return
value is used to construct the result.
@item (@var{test} @@ @var{expr} @dots{})
Like @code{(test expr @dots{})}, except that the result of
the last @var{expr} must be a list, and it is spliced into
the resulting list, like unquote-splicing.
@item (@var{test} => @@ @var{proc})
Like @code{(test => proc)}, except that the result of
@var{proc} must be a list, and and it is spliced into
the resulting list, like unquote-splicing.
@end table
@c JP
@var{clause}は、以下のフォームのうちの1つでなければなりません。
@table @code
@item (@var{test} @var{expr} @dots{})
@var{test}が評価され、それが真ならば@var{expr} @dots{}が評価され、
戻り値が結果の一部となります。@var{expr}が与えられなければ、
@var{test}の結果が偽でなければその結果が使われます。
@item (@var{test} => @var{proc})
@var{test}が評価され、それが真ならば@var{proc}がその値とともに
呼ばれ、その戻り値が結果を構築するために使われます。
@item (@var{test} @@ @var{expr} @dots{})
@code{(test expr @dots{})}のように動作しますが、最後の@var{expr}の
値はリストでなければならず、それは結果のリストに(unquote-splicingのように)
スプライスされます。
@item (@var{test} => @@ @var{proc})
@code{(test => proc)}のように動作しますが、@var{proc}の戻り値
はリストでなければならず、それは結果のリストに(unquote-splicingのように)
スプライスされます。
@end table
@c COMMON

@example
(let ((alist '((x 3) (y -1) (z 6))))
 (cond-list ((assoc 'x alist) 'have-x)
            ((assoc 'w alist) 'have-w)
            ((assoc 'z alist) => cadr)))
  @result{} (have-x 6)

(let ((x 2) (y #f) (z 5))
  (cond-list (x @@ `(:x ,x))
             (y @@ `(:y ,y))
             (z @@ `(:z ,z))))
  @result{} (:x 2 :z 5)
@end example
@end defmac

@defun alist->hash-table alist :optional cmp
@c EN
Creates and returns a hash table that has entries of
each element in alist, using its car as the key and
its cdr as the value.  @var{Cmp} is a symbol specifying
the comparison function of the created hash table;
currently @code{eq?}, @code{eqv?}, @code{equal?} and @code{string=?}
are supported.
@c JP
alistに含まれるそれぞれの要素をエントリとして持つハッシュテーブルを
作成して返します。その時、要素のcarがキーとして、要素のcdrが値として
使われます。@var{cmp}は作成されたハッシュテーブルの比較関数を
指定するシンボルで、現在は@code{eq?}、@code{eqv?}、@code{equal?}、
@code{string=?}がサポートされています。
@c COMMON
@end defun

@defun hash-table->alist hash-table
@example
  (hash-table-map h cons)
@end example
@end defun

@defun rassoc key alist :optional eq-fn
@defunx rassq key alist
@defunx rassv key alist
@c EN
Reverse associations---given @var{key} is matched to the @emph{cdr}
of each element in @var{alist}, instead of the @emph{car}.
Handy to realize bidirectional associative list.
@code{Rassoc} takes an optional comparison function, whose default is
@code{equal?}.  @code{Rassq} and @code{rassv} uses @var{eq?} and @var{eqv?}.
@c JP
与えられる@var{key}が@var{alist}のそれぞれの要素で、@emph{car}の代わりに
@emph{cdr}にマッチするような逆になった連想リストです。
両方向の連想リストと理解すると簡単です。
@code{rassoc}は、そのデフォルトが@code{equal?}である、オプションの
比較関数を取ります。@code{rassq}は@var{eq?}、@code{rassv}は@var{eqv?}を
使います。
@c COMMON
@end defun


@defun assoc-ref alist key :optional default eq-fn
@defunx assq-ref alist key :optional default
@defunx assv-ref alist key :optional default
@c EN
These procedures provide the access to the assoc list
symmetric with other *-ref procedures.
This captures the common pattern of alist access:
@c JP
これらの手続きは、他の*-ref手続きと対照的な連想リストへの
アクセスを提供します。これは、一般的な連想リストアクセスのパターン
です。
@c COMMON
@example
(assoc-ref alist key default eq-fn)
 @equiv{}
  (cond ((assoc key alist eq-fn) => cdr)
        (else default))))
@end example

@c EN
If @var{default} is omitted, @code{#f} is used.

@code{Assoc-ref} takes an optional comparison function @var{eq-fn},
whose default is @code{equal?}.  @code{Assq-ref} and @code{assv-ref}
uses @code{eq?} and @code{eqv?}, respectively.
@c JP
@var{default}が省略されると、@code{#f}が使われます。

@code{assoc-ref}は、そのデフォルトが@code{equal?}である、オプションの
比較関数@var{eq-fn}を取ります。@code{assq-ref}は@code{eq?}を、
@code{assv-ref}は@code{eqv?}をそれぞれ使います。
@c COMMON
@end defun

@defun rassoc-ref alist key :optional default eq-fn
@defunx rassq-ref alist key :optional default
@defunx rassv-ref alist key :optional default
@c EN
Reverse association version of @code{assoc-ref}.
@c JP
@code{assoc-ref}の逆連想リストバージョンです。
@c COMMON
@example
(rassoc-ref alist key default eq-fn)
 @equiv{}
  (cond ((rassoc key alist eq-fn) => car)
        (else default))))
@end example
@c EN
The meanings of optional arguments are the same as @code{assoc-ref}.
@c JP
オプショナル引数の意味は、@code{assoc-ref}と同じです。
@c COMMON
@end defun

@defun assoc-set! alist key val :optional eq-fn
@defunx assq-set! alist key val
@defunx assv-set! alist key val
@c EN
Returns an alist who has @code{(key . val)} pair added to the @code{alist}.
If @code{alist} already has an element with @var{key}, the element's
@emph{cdr} is destructively modified for @var{val}.
If @var{alist} doesn't have an element with @var{key}, a new pair
is created and appended in front of @var{alist}; so you should use
the return value to guarantee @var{key}-@var{val} pair is added.

@code{Assoc-set!} takes optional comparison function @var{eq-fn},
whose default is @code{equal?}.  @code{Assq-set!} and @code{assv-set!}
uses @code{eq?} and @code{eqv?}, respectively.
@c JP
@code{alist}に@code{(key . val)}のペアが追加された連想リストを返します。
@code{alist}がすでに@var{key}をキーとする要素を持っている場合、
その要素の@emph{cdr}は破壊的に@var{val}に変更されます。
@var{alist}が@var{key}をキーとする要素を持っていない場合は、
新しいペアが作成され、@var{alist}の一番前に追加されます。
したがって、@var{key}-@var{val}ペアが追加されたことを保証するために
その戻り値を使うべきです。

@code{assoc-set!}は、そのデフォルトが@code{equal?}である、オプションの
比較関数@var{eq-fn}を取ります。@code{assq-set!}は@code{eq?}を、
@code{assv-set!}は@code{eqv?}を、それぞれ使います。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Pattern matching, Queue, Additional list library, Library modules - Utilities
@section @code{util.match} - Pattern matching
@c NODE パターンマッチング, @code{util.match} - パターンマッチング

@deftp {Module} util.match
@mdindex util.match
@c EN
This module is a port of Andrew Wright's pattern matching macro library.
It is widely used in Scheme world, and ported to various Scheme
implementations, including Chez Scheme, PLT Scheme, Scheme48, Chicken,
and SLIB.
It is similar to, but more powerful than
Common Lisp's @code{destructuring-bind}.
@c JP
このモジュールは Andrew Wright のパターンマッチングマクロライブラリを
ポートしたものです。このライブラリは Scheme 界では広くつかわれており、
Chez Scheme、PLT Scheme、Scheme48、Chicken および SLIB を含む、様々な
Scheme の実装にポートされています。この機能は Common Lisp の
@code{destructuring-bind} に似ていますがより強力です。
@c COMMON

@c EN
This version retains compatibility of the original Wright's macro,
except (1) @var{box} is not supported since Gauche doesn't have one,
and (2) structure matching is integrated to Gauche's object system.
@c JP
この版では、オリジナルの Wright's macro のマクロとの互換性が保たれて
います。ただし、例外がふたつあって、それは、(1) @var{box} はサポートされて
いません。Gauche にそれがないからです。(2) 構造のマッチングは Gauche の
オブジェクトシステムに統合されています。
@c COMMON
@end deftp

@c EN
We show a list of APIs first, then the table of complete syntax of 
patterns, followed by examples.
@c JP
まず API のリストを示し、それからパターンの完全な構文のテーブルを示し、
そして例を示します。
@c COMMON

@c EN
@subheading Pattern matching API
@c JP
@subheading パターンマッチング API
@c COMMON

@defmac match expr clause @dots{}

@c EN
Each @var{clause} is either one of the followings:
@c JP
それぞれの @var{clause} は以下のうちどちらかです。
@c COMMON
@example
(@var{pat} @var{body} @dots{})
(@var{pat} (=> @var{identifier}) @var{body} @dots{})
@end example

@c EN
First, the @var{expr} is matched against @var{pat} of each clauses.
The detailed syntax of the pattern is explained below.
@c JP
まず、@var{expr} を各節の @var{pat} に照合します。パターンの詳しい
構文については後述します。
@c COMMON

@c EN
If a matching @var{pat} is found, the @emph{pattern variables} in
@var{pat} are bound to the corresponding elements in @var{expr}, then
@var{body} @dots{} are evaluated.  Then @code{match} returns the value(s)
of the last expression of @var{body} @dots{}.
@c JP
@var{pat} にマッチする部分が見つかれば、@var{pat} 中の @emph{パターン変数}
は、@var{expr} 中の対応する要素に束縛され、その後、@var{body} @dots{} 
が評価されます。@code{match}は@var{body} @dots{}の最後の式の値を返します。
@c COMMON

@c EN
If the clause is the second form, @var{identifier} is also bound
to the failure continuation of the @var{clause}.  It is a
procedure with no arguments, and when called, it jumps back to
the matcher as if the matching of @var{pat} is failed, and
@code{match} continues to try the rest of clauses.
So you can perform extra tests
within @var{body} @dots{} and if you're not satisfied you can reject
the match by calling @code{(@var{identifier})}.  See the examples
below for more details.
@c JP
節が 2つ目の形式である場合、@var{identifier} は @var{clause} の失敗継続
に束縛されます。これは引数をもたない手続きで、呼ばれると、あたかも、
@var{pat} の照合に失敗したかの如くマッチャーに戻り、@code{match} が
残りの節について試行を続けます。それゆえ、@var{body} @dots{} 内部で
追加のテストを実行することが可能で、もし、満足いくものでなければ、
@code{(@var{identifier})} を呼ぶことで、照合結果を拒絶することができます。
より詳しくは、後述の例を見てください。
@c COMMON

@c EN
If no @var{pat} matches, @code{match} reports an error.
@c JP
どの @var{pat} もマッチしなければ、@code{match} はエラーを報告します。
@c COMMON
@end defmac

@defmac match-lambda clause @dots{}
@c EN
Creates a function that takes one argument and performs @code{match} on it,
using @var{clause} @dots{}.  It's functionally equivalent to the following
expression:
@c JP
ひとつの引数をとり、それに対して @var{clause} @dots{} を用いて、
@code{match} を実行する関数を生成します。機能としては以下の式と同等です。
@c COMMON
@example
(lambda (expr) (match expr @var{clause} @dots{}))
@end example

@c EN
Example:
@c JP
例:
@c COMMON

@example
(map (match-lambda
       ((item price-per-lb (quantity 'lbs))
        (cons item (* price-per-lb quantity)))
       ((item price-per-lb (quantity 'kg))
        (cons item (* price-per-lb quantity 2.204))))
     '((apple      1.23 (1.1 lbs))
       (orange     0.68 (1.4 lbs))
       (cantaloupe 0.53 (2.1 kg))))
 @result{} ((apple . 1.353) (orange . 0.952)
            (cantaloupe . 2.4530520000000005))
@end example
@end defmac

@defmac match-lambda* clause @dots{}
@c EN
Like @code{match-lambda}, but performs @code{match} on the list of
whole arguments.
It's functionally equivalent to the following expression:
@c JP
@code{match-lambda} と同じですが、@code{match} をすべての引数のリスト
に対して実行します。機能としては以下の式と同等です。
@c COMMON
@example
(lambda expr (match expr @var{clause} @dots{}))
@end example
@end defmac

@defmac match-let ((pat expr) @dots{}) body-expr @dots{}
@defmacx match-let name ((pat expr) @dots{}) body-expr @dots{}
@defmacx match-let* ((pat expr) @dots{}) body-expr @dots{}
@defmacx match-letrec ((pat expr) @dots{}) body-expr @dots{}
@c EN
Generalize @code{let}, @code{let*}, and @code{letrec} to allow
patterns in the binding position rather than just variables.
Each @var{expr} is evaluated, and then matched to @var{pat},
and the bound pattern variables are visible in 
@var{body-expr} @dots{}.
@c JP
束縛部分が単なる変数ではなく、パターンを許す、一般化された @code{let}、
@code{let*} および @code{letrec} です。
各 @var{expr} が評価され、その後、@var{pat} と照合され、束縛された
パターン変数が @var{body-expr} @dots{} から見えるようになります。
@c COMMON

@example
(match-let (
             (((ca . cd) ...)   '((a . 0) (b . 1) (c . 2)))
           )
  (list ca cd))
 @result{} ((a b c) (0 1 2))
@end example

@c EN
If you're sick of parenthesis, try @code{match-let1} below.
@c JP
括弧はうんざりという向きには、以下の @code{match-let1} をおためしあれ。
@c COMMON
@end defmac

@defmac match-let1 pat expr body-expr @dots{}
@c EN
This is a Gauche extension and isn't found in the original Wright's code.
This one is equivalent to the following code:
@c JP
これは Gauche での拡張で、オリジナルの Wright のコードにはありません。
これは以下のコードと同等です。
@c COMMON
@example
(match-let ((@var{pat} @var{expr})) @var{body-expr} @dots{})
@end example

@c EN
Syntactically, @code{match-let1} is very close to the Common Lisp's
@code{destructuring-bind}.
@c JP
構文としては @code{match-let1} は Common Lisp の @code{destructuring-bind}
に非常によく似ています。
@c COMMON

@example
(match-let1 ('let ((var val) ...) body ...)
            '(let ((a b) (c d)) foo bar baz)
  (list var val body))
 @result{} ((a c) (b d) (foo bar baz))
@end example
@end defmac

@defmac match-define pat expr
@c EN
Like toplevel @code{define}, but allows a pattern instead of variables.
@c JP
トップレベルの @code{define} と同様ですが、変数の代りにパターンが許されます。
@c COMMON

@example
(match-define (x . xs) (list 1 2 3))

x  @result{} 1
xs @result{} (2 3)
@end example

@end defmac

@c EN
@subheading Pattern syntax
@c JP
@subheading パターンの構文
@c COMMON

@c EN
Here's a summary of pattern syntax. The asterisk @code{(*)}
after explanation means Gauche's extension which does not present
in the original Wright's code.
@c JP
ここにあるのはパターンの構文の要約です。説明の後にあるアスタリスク
@code{(*)} はオリジナルの Wright のコードにはない、Gauche の拡張で
あることを意味します。
@c COMMON

@c EN
@example
pat : @var{patvar}                       ;; anything, and binds pattern var
    | @b{_}                            ;; anything
    | ()                           ;; the empty list
    | #t                           ;; #t
    | #f                           ;; #f
    | @var{string}                       ;; a string
    | @var{number}                       ;; a number
    | @var{character}                    ;; a character
    | @var{keyword}                      ;; a keyword (*)
    | '@var{sexp}                        ;; an s-expression
    | '@var{symbol}                      ;; a symbol (special case of s-expr)
    | (@var{pat1} ... @var{patN})              ;; list of n elements
    | (@var{pat1} ... @var{patN} . @var{patN+1})     ;; list of n or more
    | (@var{pat1} ... @var{patN} @var{patN+1} ooo)   ;; list of n or more, each element
                                   ;;   of remainder must match @var{patN+1}
    | #(@var{pat1} ... @var{patN})             ;; vector of n elements
    | #(@var{pat1} ... @var{patN} @var{patN+1} ooo)  ;; vector of n or more, each element
                                   ;;   of remainder must match @var{patN+1}
    | (@b{$} @var{class} @var{pat1} ... @var{patN})      ;; an object (@var{patK} matches in slot order)
    | (@b{struct} @var{class} @var{pat1} ... @var{patN}) ;; ditto (*)
    | (@b{@@} @var{class} (@var{slot1} @var{pat1}) ...)   ;; an object (using slot names) (*)
    | (@b{object} @var{class} (@var{slot1} @var{pat1}) ...) ;; ditto (*)
    | (@b{=} @var{proc} @var{pat})                 ;; apply proc, match the result to pat
    | (@b{and} @var{pat} ...)                ;; if all of pats match
    | (@b{or} @var{pat} ...)                 ;; if any of pats match
    | (@b{not} @var{pat} ...)                ;; if all pats don't match at all
    | (@b{?} @var{predicate} @var{pat} ...)        ;; if predicate true and all pats match
    | (@b{set!} @var{patvar})                ;; anything, and binds setter
    | (@b{get!} @var{patvar})                ;; anything, and binds getter
    | `qp                          ;; a quasi-pattern

patvar : a symbol except @b{_}, @b{quote}, @b{$}, @b{struct}, @b{@@}, @b{object}, @b{=}, @b{and}, @b{or},
         @b{not}, @b{?}, @b{set!}, @b{get!}, @b{quasiquote}, @b{...}, @b{___}, @b{..@i{k}}, @b{__@i{k}}.

@c @b doesn't work well in pdf version, so we conditionalize...
@ifnottex
ooo : @b{...}                          ;; zero or more
    | @b{___}                          ;; zero or more
    | @b{..@i{k}}                          ;; @i{k} or more, where @i{k} is an integer.
                                   ;;   Example: @b{..1}, @b{..2} ...
    | @b{__@i{k}}                          ;; @i{k} or more, where @i{k} is an integer. 
                                   ;;   Example: @b{__1}, @b{__2} ...
@end ifnottex
@iftex
ooo : ...                          ;; zero or more
    | ___                          ;; zero or more
    | ..@slanted{k}                          ;; @i{k} or more, where @i{k} is an integer.
                                   ;;   Example: ..1, ..2 ...
    | __@slanted{k}                          ;; @i{k} or more, where @i{k} is an integer. 
                                   ;;   Example: __1, __2 ...
@end iftex

@end example
@c JP
@example
pat : @var{patvar}                       ;; 任意のオブジェクトにマッチし、patvarを束縛
    | @b{_}                            ;; 任意のオブジェクト
    | ()                           ;; 空リスト
    | #t                           ;; #t
    | #f                           ;; #f
    | @var{string}                       ;; 文字列
    | @var{number}                       ;; 数
    | @var{character}                    ;; 文字
    | @var{keyword}                      ;; キーワード (*)
    | '@var{sexp}                        ;; Ｓ式
    | '@var{symbol}                      ;; シンボル(Ｓ式の特殊ケース)
    | (@var{pat1} ... @var{patN})              ;; n 要素のリスト
    | (@var{pat1} ... @var{patN} . @var{patN+1})     ;; n 以上の要素を含むリスト
    | (@var{pat1} ... @var{patN} @var{patN+1} ooo)   ;; n 以上の要素を含むリスト、残りの各要素は
                                   ;; @var{patN+1} にマッチしなければならない
    | #(@var{pat1} ... @var{patN})             ;; n 要素のベクタ
    | #(@var{pat1} ... @var{patN} @var{patN+1} ooo)  ;; n 以上の要素を含むベクタ、残りの各要素は
                                   ;; @var{patN+1} にマッチしなければならない
    | (@b{$} @var{class} @var{pat1} ... @var{patN})      ;; オブジェクト (@var{patK} はスロット順でマッチ)
    | (@b{struct} @var{class} @var{pat1} ... @var{patN}) ;; 同上 (*)
    | (@b{@@} @var{class} (@var{slot1} @var{pat1}) ...)  ;; オブジェクト (スロット名を使う) (*)
    | (@b{object} @var{class} (@var{slot1} @var{pat1}) ...) ;; 同上 (*)
    | (@b{=} @var{proc} @var{pat})                 ;; procを適用し、結果を pat にマッチさせる
    | (@b{and} @var{pat} ...)                ;; すべての pat にマッチするか
    | (@b{or} @var{pat} ...)                 ;; マッチする pat があるか
    | (@b{not} @var{pat} ...)                ;; どの pat もマッチしないか
    | (@b{?} @var{predicate} @var{pat} ...)        ;; predicate が真、かつ、全 pat がマッチ
    | (@b{set!} @var{patvar})                ;; 任意のオブジェクトにマッチし、セッタを束縛
    | (@b{get!} @var{patvar})                ;; 任意のオブジェクトにマッチし、ゲッタを束縛
    | `qp                          ;; 擬似パターン

patvar : a symbol except @b{_}, @b{quote}, @b{$}, @b{struct}, @b{@@}, @b{object}, @b{=}, @b{and}, @b{or},
         @b{not}, @b{?}, @b{set!}, @b{get!}, @b{quasiquote}, @b{...}, @b{___}, @b{..k}, @b{__k}.

@c @b doesn't work well in pdf version, so we conditionalize...
@ifnottex
ooo : @b{...}                          ;; ゼロまたはそれ以上
    | @b{___}                          ;; ゼロまたはそれ以上
    | @b{..@i{k}}                          ;; @i{k} またはそれ以上。@i{k}は整数。
                                   ;;   例: @b{..1}, @b{..2} ...
    | @b{__@i{k}}                          ;; @i{k} またはそれ以上。@i{k}は整数。
                                   ;;   例: @b{__1}, @b{__2} ...
@end ifnottex
@iftex
ooo : ...                          ;; ゼロまたはそれ以上
    | ___                          ;; ゼロまたはそれ以上
    | ..@slanted{k}                          ;; @i{k} またはそれ以上。@i{k}は整数。
                                   ;;   例: ..1, ..2 ...
    | __@slanted{k}                          ;; @i{k} またはそれ以上。@i{k}は整数。
                                   ;;   例: __1, __2 ...
@end iftex

@end example
@c COMMON

@itemize @bullet
@item
@c EN
A bare symbol is a "pattern variable"; it matches anything, and
the matched part of the expression is bound to the symbol.
The following symbols have special meanings and cannot be used
as a pattern variable: @code{_}, @code{quote}, @code{$}, @code{struct},
@code{@@}, @code{object}, @code{=}, @code{and}, @code{or},
@code{not}, @code{?}, @code{set!}, @code{get!}, @code{quasiquote},
@code{...}, @code{___}, and @code{..k} and @code{__k} where @emph{k} is
an integer.
@c JP
素のシンボルは「パターン変数」で、あらゆるものとマッチし、
式のマッチした部分がそのシンボルに束縛されます。
以下のシンボルは特別な意味をもち、パターン変数としては使えません。
@code{_}、@code{quote}、@code{$}、@code{struct}、@code{@@}、@code{object}、
@code{=}、@code{and}、@code{or}、@code{not}、@code{?}、@code{set!}、
@code{get!}、@code{quasiquote}、@code{...}、@code{___} および
@code{..k} と @code{__k} (ここで、@emph{k} は整数)。
@c COMMON

@item
@c EN
A symbol @code{_} matches anything, without binding a patter variable.
It can be used to show "don't care" placeholder.
@c JP
シンボル @code{_} はあらゆるものマッチし、パターン変数は束縛しません。
プレースホルダであることを示すのに用います。
@c COMMON

@item
@c EN
Literals such as emptylist, booleans, strings, numbers, characters and
keywords match the same object (in the sense of @code{equal?}).
@c JP
空リスト、真偽値、文字列、数、文字およびキーワードのリテラルは
(@code{equal?}という意味で)同じオブジェクトとマッチします。
@c COMMON

@item
@c EN
Quoted expression matches the same experssion (in the sense of @code{equal?}).
You can use a quoted symbol to match the symbol itself.
@c JP
クウォートされた式は(@code{equal?} という意味で)同じ式とマッチします。
クウォートされたシンボルをそれ自身とマッチさせるのに使えます。
@c COMMON

@item
@c EN
A list and a vector in general match a list or a vector whose elements
matches the elements in the pattern recursively, unless the first element
of the list is one of the special symbols listed above, it has a special
meaning.
@c JP
通常リストおよびベクタは、それぞれ、パターン中の要素にマッチする要素を
もつリストまたはベクタとマッチします。ただし、最初の要素が上であげた
特別なシンボルではない限りです。そのような場合には特別な意味を持ちます。
@c COMMON

@c EN
As a special case, the last element of a vector or a list can be
followed by a symbol @code{...}.  In that case, the pattern just before
the symbol @code{...} can be applied repeatedly until it consumes all the
elements in the given expression.  A symbol @code{___} can be used
in place of @code{...}; it is useful when you want to produce a pattern
by syntax-rules macro.
@c JP
特別な場合として、ベクタあるいはリストの最後の要素のあとにシンボル
@code{...} を付加することができます。この場合には、@code{...} シンボル
直前のパターンが与えられた式のすべての要素を尽すまで繰り返し適用されます。
シンボル @code{___} は @code{...} の場所で使えます。構文規則マクロによって
パターンを生成したいときに便利です。
@c COMMON

@c EN
For a list pattern, you can also use a symbol @code{..1}, @code{..2},
@dots{}, which specifies the minimum number of repetition.
@c JP
リストのパターンに対しては、シンボル @code{..1}、@code{..2}、@dots{} が
使えます。これは繰り返しの最小値を指定するものです。
@c COMMON

@item
@c EN
@code{($ class pat1 @dots{})} matches an instance of a class @code{class}.
Each pattern @code{pat1} @dots{} matches each value of slots,
in order of @code{(class-slots class)}.
@c JP
@code{($ class pat1 @dots{})} は @code{class} クラスのインスタンスと
マッチします。各パターン @code{pat1} @dots{} はスロットの各値と
@code{(class-slots class)} の順にマッチします。
@c COMMON

@c EN
@code{(struct class pat1 @dots{})} has the same meaning.  Although
the original Wright's code doesn't have @code{struct}, PLT Scheme has
it in its extended match feature, and it is more descriptive.
@c JP
@code{(struct class pat1 @dots{})} は同じ意味です。オリジナルの
Wright のコードには、@code{struct} はありませんが、PLT Scheme の拡張
照合機能にはそなわっています。こちらの方がより説明的です。
@c COMMON

@c EN
This is an adaptation of the original feature that can match structures.
It is useful to match a simple instance that you know the order of
slots; for example, a simple record created by @code{define-record-type}
(@xref{Record types}) would be easy to match by positioned values.
@c JP
これはオリジナルの機能を構造(structure)にもマッチするように調整した
ものです。スロットの順番が予め分るような単純なインスタンスをマッチする
のに便利です。たとえば、@code{define-record-type} (@ref{Record types}参照)で作成した
簡単なレコードは簡単に位置指定された値でマッチすることができます。
@c COMMON

@c EN
If the instance's class uses inheritances, it is a bit difficult to
match by positions.  You can use @code{@@} or @code{object} pattern
below to match using slot names.
@c JP
インスタンスのクラスが継承を使っている場合、位置によるマッチを
おこなうのは少々難しくなります。以下の @code{@@} あるいは @code{object}
パターンを使って、スロット名でマッチを行うことができます。
@c COMMON

@item
@c EN
@code{(object class (slot1 pat1) @dots{})} matches an instance
of a class @code{class} whose value of @var{slot1} @dots{} matches
@var{pat1} @dots{}.  This is Gauche's extension.  @code{@@} can be
used in place of @code{object}, but @code{object} is recommended
because of descriptiveness.
@c JP
@code{(object class (slot1 pat1) @dots{})} は
@var{slot1} @dots{} の値が @var{pat1} @dots{} にマッチするような
@code{class} クラスのインスタンスとマッチします。これは、
Gauche の拡張です。@code{@@} は @code{object} と同じ場所で使えます。
ただし、@code{object} の方が説明的でわかりやすいので、こちらを
推奨します。
@c COMMON

@item
@c EN
@code{(= proc pat)} first applies @var{proc} to the corresponding
expression, then match the result with @var{pat}.
@c JP
@code{(= proc pat)} は最初に @var{proc} を対応する式に適用し、
その結果と @var{pat} をマッチさせます。
@c COMMON

@item
@c EN
@code{(and pat @dots{})}, @code{(or pat @dots{})}, and
@code{(not pat @dots{})} are boolean operations of patterns.
@c JP
@code{(and pat @dots{})}、@code{(or pat @dots{})} および 
@code{(not pat @dots{})} はパターンの真偽値演算子です。
@c COMMON

@item
@c EN
@code{(? predicate pat @dots{})} first applies a predicate to the
corresponding expression, and if it returns true, applies each
@code{pat} @dots{} to the expression.
@c JP
@code{(? predicate pat @dots{})} は最初、述語を対応する式に適用し、
真が返れば、各 @code{pat} @dots{} をその式に適用します。
@c COMMON

@item
@c EN
@code{(set! patvar)} matches anything, and binds an one-argument
procedure to a pattern variable @var{patvar}.  If the procedure is
called, it replaces the value of matched pattern for the given argument.
@c JP
@code{(set! patvar)} はあらゆるものにマッチし、一引数の手続きを
パターン変数 @var{patvar} に束縛します。その手続きが呼ばれると、
マッチしたパターンの値を与えられた引数で置き換えます。
@c COMMON

@item
@c EN
@code{(get! patvar)} matches anything, and binds a zero-argument
procedure to a pattern variable @var{patvar}.  If the procedure is
called, it returns the matched value.
@c JP
@code{(get! patvar)} はあらゆるものにマッチし、引数なしの手続きを
パターン変数 @var{patvar} に束縛します。その手続きが呼ばれると、
マッチしたパターンの値を返します。
@c COMMON

@item
@c EN
@code{`qp} is a quasipattern.  @var{qp} is quoted, in the sense
that it matches itself, @emph{except} the pattern that is unquoted.
(Don't confuse quasipatern to quasiquote, though the functions are
similar.  Quasiquote turns off evaluation except unquoted subtree.
Quasiquote turns off the special pattern syntax except unquoted subtree.
See the examples below).
@c JP
@code{`qp}はquasipatternです。@var{qp}は、クオートされたパターンと同様、
それそのものにマッチしますが、その中にアンクオートされているパターンがあると、
その部分だけは通常のパターンとして解釈されます。
(準クオート(quasiquote)とquasipatternを混同しないようにしてください。
機能的に両者は似ていますが、準クオートがアンクオートされた部分木以外の
部分の評価をoffにするのに対し、quasipatternはアンクオートされた部分木
以外の部分のパターン構文を無効にします。下の例も参照して下さい。)
@c COMMON
@end itemize

@c EN
@subheading Pattern examples
@c JP
@subheading パターン例
@c COMMON

@c EN
A simple structure decomposition:
@c JP
単純な構造の分解
@c COMMON
@example
(match '(0 (1 2) (3 4 5))
  [(a (b c) (d e f))
   (list a b c d e f)])
 @result{} (0 1 2 3 4 5)
@end example

@c EN
Using predicate patterns:
@c JP
述語パターンの使用
@c COMMON
@example
(match 123
  [(? string? x) (list 'string x)]
  [(? number? x) (list 'number x)])
 @result{} (number 123)
@end example

@c EN
Extracting variables and expressions from @code{let}.
Uses repetition and predicate patterns:
@c JP
@code{let} から変数と式を取り出す
反復および述語パターンの利用
@c COMMON
@example
(define let-analyzer
  (match-lambda
    [('let (? symbol?)
           ((var expr) ...)
       body ...)
     (format "named let, vars=~s exprs=~s" var expr)]
    [('let ((var expr) ...)
       body ...)
     (format "normal let, vars=~s exprs=~s" var expr)]
    [_
     (format "malformed let")]))

(let-analyzer '(let ((a b) (c d)) e f g))
 @result{} "normal let, vars=(a c) exprs=(b d)"

(let-analyzer '(let foo ((x (f a b)) (y (f c d))) e f g))
 @result{} "named let, vars=(x y) exprs=((f a b) (f c d))"

(let-analyzer '(let (a) b c d))
 @result{} "malformed let"
@end example

@c EN
Using @code{=} function application.  The pattern variable @var{m}
is matched to the result of application of the regular expression.
@c JP
@code{=} 関数適用。パターン変数 @var{m} は正規表現の適用結果にマッチする
@c COMMON
@example
(match "gauche-ref.texi"
  ((? string? (= #/(.*)\.([^.]+)$/ m))
   (format "base=~a suffix=~a" (m 1) (m 2))))
 @result{} "base=gauche-ref suffix=texi"
@end example

@c EN
An example of quasipattern.   In the first expression, the
pattern except @code{value} is quoted, so the symbols @code{the},
@code{answer}, and @code{is} are not pattern variables but literal
symbols.   The second expression shows that; input symbol @code{was} 
does not match the literal symbol @code{is} in the pattern.
If we don't use quasiquote, all symbols in the pattern are pattern
variables, so any four-element list matches as the third expression shows.
@c JP
quasipatternの例です。最初の式では、パターンのうち@code{value}以外の
部分がクオートされたことになり、従ってシンボル@code{the}, @code{answer},
@code{is}はパターン変数ではなくリテラルシンボルとなります。
2番目の式がそのことを示しています。入力にあるシンボル@code{was}は
パターンの@code{is}とマッチしません。もしクオートを行わないと、
全てのシンボルはパターン変数となるので、3番目の例に示すように
任意の4つの要素を持つリストとマッチしてしまいます。
@c COMMON
@example
(match '(the answer is 42)
  [`(the answer is ,value) value]
  [else #f])
 @result{} 42

(match '(the answer was 42)
  [`(the answer is ,value) value]
  [else #f])
 @result{} #f

(match '(a b c d)
  [(the answer is value) value]
  [else #f])
 @result{} d
@end example


@c ----------------------------------------------------------------------
@node Queue, Red black tree, Pattern matching, Library modules - Utilities
@section @code{util.queue} - Queue
@c NODE キュー, @code{util.queue} - キュー

@deftp {Module} util.queue
@mdindex util.queue
@c EN
Provides a queue (FIFO).  You can create a simple queue,
which is lightweight but not thread-safe, or an MTqueue,
a thread-safe queue.  Basic queue operations work on
both type of queues.  When an mtqueue is passed to the
procedures listed in this section, each operation is
done in atomic way, unless otherwise noted.

There are also a set of procedures for mtqueues that
can be used for thread synchronization; for example,
you can let the consumer thread block if an
mtqueue is empty, and/or the producer thread block if the number
of items in the mtqueue reaches a specified limit.
Using these procedures allows the program to use an mtqueue
as a @emph{channel}.

The simple queue API is a superset of SLIB's queue implementation.
@c JP
キュー(FIFO)機能を提供します。
極めて軽量ですがスレッドセーフでないシンプルなキューと、
スレッドセーフなmtqueueがあります。基本的なキュー操作手続きは
どちらのキューに対しても使うことができます。本節で説明されている
手続きをmtqueueに適用した場合、特に断りが無い限り、操作は
アトミックに行われます。

また、スレッド間同期に使えるmtqueue用の手続きも用意されています。
例えばキューが空の時に読み出しスレッドをブロックさせたり
キューの長さが指定値に達した場合に書き込みスレッドをブロックさせることができ、
いわゆる「チャネル」としてキューを使うことができます。

シンプルキューのAPIはSLIBのキュー実装の上位互換になっています。
@c COMMON
@end deftp

@deftp {Class} <queue>
@clindex queue
@c EN
A class of simple queue.
@c JP
シンプルなキューのクラスです。
@c COMMON

@defivar {<queue>} length
@c EN
A read-only slot that returns the number of items in the queue.
@c JP
キュー中の要素の数を返す、読み取り専用のスロットです。
@c COMMON
@end defivar
@end deftp

@deftp {Class} <mtqueue>
@clindex mtqueue
@c EN
A class of mtqueue.  Inherits @code{<queue>}.
@c JP
mtqueueのクラスです。@code{<queue>}を継承しています。
@c COMMON

@defivar {<mtqueue>} max-length
@c EN
If positive integer, this slot sets the upper bound of the number of
items in the queue.
@c JP
正の整数の場合、このスロットの値はキュー中の要素数の上限を示します。
@c COMMON
@end defivar
@end deftp

@defun make-queue
@c EN
Creates and returns an empty simple queue.
@c JP
空のシンプルなキューを作って返します。
@c COMMON
@end defun

@defun make-mtqueue &key max-length
@c EN
Creates and returns an empty mtqueue.  When an integer is given
to the keyword argument @var{max-length}, it is used to 
initialize the @code{max-length} slot (Zero indicates unlimited length).
@c JP
空のmtqueueを作って返します。整数が@var{max-length}に与えられた場合は、
それが@code{max-length}スロットの値となります (ゼロは無制限を意味します)。
@c COMMON
@end defun

@defun queue? obj
@c EN
Returns @code{#t} if @var{obj} is a queue (either a simple queue 
or an mtqueue).
@c JP
@var{obj}がキューであれば(シンプルなキューでもmtqueueでも)@code{#t}を返します。
@c COMMON
@end defun

@defun mtqueue? obj
@c EN
Returns @code{#t} if @var{obj} is an mtqueue.
@c JP
@var{obj}がmtqueueであれば@code{#t}を返します。
@c COMMON
@end defun

@defun queue-empty? queue
@c EN
Returns @code{#t} if @var{obj} is an empty queue.
@c JP
@var{obj}が空のキューであれば@code{#t}を返します。
@c COMMON
@end defun

@defun queue-length queue
@c EN
Returns the number of the items in the queue.
@c JP
キューの中にある要素の数を返します。
@c COMMON
@end defun

@defun mtqueue-max-length mtqueue
@c EN
Returns the maximum number of items the mtqueue can hold.
Zero indicates unlimited.
@c JP
キューが保持できる要素の最大数を返します。限度がない場合はゼロが返ります。
@c COMMON
@end defun

@defun mtqueue-room mtqueue
@c EN
Returns the number of elements the mtqueue can accept at this moment
before it hits its maximum length.   For example, if the queue
already has the maximum number of elements, 0 is returned.
If the queue doesn't have the limit, @code{+inf.0} is returned.
@c JP
保持できる最大容量に達するまであといくつ要素を受け入れることができるかを
示す整数を返します。例えば、既にキューがいっぱいであれば0が返ります。
キューに最大容量が設定されていなければ@code{+inf.0}が返ります。
@c COMMON
@end defun


@defun copy-queue queue
@c EN
Returns a copy of the queue.
@c JP
キューqueueのコピーを返します。
@c COMMON
@end defun

@defun enqueue! queue obj :optional more-objs @dots{}
@c EN
Add @var{obj} to the end of @var{queue}.  You may give more than
one object, and each of them are enqueued in order.
@c JP
@var{obj}をキュー@var{queue}の末尾に追加します。
一つ以上の@var{obj}を与えることができ、その場合はそれらが順にenqueueされます。
@c COMMON

@c EN
If @var{queue} is an mtqueue, all the objects are enqueued
atomically; no other objects from other threads can be inserted
between the objects given to a single @code{enqueue!} call.
Besides, if the value of its @code{max-length} slot
is positive, and adding @var{obj}s makes the number of
elements in @var{queue} exceeds @code{max-length}, 
an error is signalled and @var{queue} won't be modified.
@c JP
@var{queue}がmtqueueの場合、渡されたオブジェクト全ての追加は
アトミックに行われます。すなわち、途中に別スレッドが要素を挿入する
ことはありません。さらに、@code{max-length}スロットが正の値を
持っており、この@code{enqueue!}の実行によってキューの要素数が
@code{max-length}を越えることになる場合は、@var{queue}は
変更されずエラーとなります。
@c COMMON
@end defun

@defun queue-push! queue obj :optional more-objs @dots{}
@c EN
Add @var{obj} in front of @var{queue}.  You may give more than
one object, and each of them are pushed in order.

Like @code{enqueue!}, when @var{queue} is an mtqueue,
all objects are added atomically, and the value of
@code{max-length} slot is checked.  See @code{enqueue!} above
for the details.
@c JP
@var{obj}をキュー@var{queue}の先頭に追加します。
一つ以上の@var{obj}を与えることができ、その場合はそれらが順にpushされます。

@code{enqueue!}と同様に、@var{queue}がmtqueueの場合は
全てのオブジェクトはアトミックに追加され、また@code{max-length}の値も
チェックされます。詳しくは上の@code{enqueue!}の説明を参照してください。
@c COMMON
@end defun

@defun enqueue-unique! queue eq-proc obj :optional more-objs @dots{}
@defunx queue-push-unique! queue eq-proc obj :optional more-objs @dots{}
@c EN
Like @code{enqueue!} and @code{queue-push!}, respectively, except that these
don't modify @var{queue} if it already contains @var{obj}
(elements are compared by two-argument procedure @var{eq-proc}).

When @var{queue} is an mtqueue, all objects are added atomically,
and the value of
@code{max-length} slot is checked.  See @code{enqueue!} above
for the details.
@c JP
@var{obj}が既に@var{queue}の中に含まれている場合には@var{queue}を
変更しないことを以外には、@code{enqueue!}および@code{queue-push!}と同じ
動作をします。@var{obj}が含まれているかどうかの検査は
2引数の関数@var{eq-proc}で行います。

@var{queue}がmtqueueの場合は
全てのオブジェクトはアトミックに追加され、また@code{max-length}の値も
チェックされます。詳しくは上の@code{enqueue!}の説明を参照してください。
@c COMMON
@end defun

@defun dequeue! queue :optional fallback
@defunx queue-pop! queue :optional fallback
@c EN
Take one object from the front of the queue @var{queue} and returns it.
Both function works the same, but @code{queue-pop!} may be used to
emphasize it works with @code{queue-push!}.

If @var{queue} is empty, @var{fallback} is returned if given,
otherwise an error is signalled.
@c JP
キュー@var{queue}の先頭からひとつ要素を取って返します。
二つの手続きは全く同じ動作をします。@code{queue-pop!}は@code{queue-push!}と
ペアで使われていることを強調したいときに使うと良いでしょう。

キューが空の場合は、@var{fallback}が与えられていればそれが返され、
そうでなければエラーが報告されます。
@c COMMON
@end defun

@defun dequeue-all! queue
@c EN
Returns the whole content of the queue by a list, with emptying
@var{queue}.   If @var{queue} is already empty, returns an empty list.
See also @code{queue->list} below.
@c JP
キューの全ての内容をリストにして返します。キューそのものは空になります。
キューが既に空の場合は空リストが返されます。
下の@code{queue->list}も参照してください。
@c COMMON
@end defun

@defun queue-front queue :optional fallback
@defunx queue-rear queue :optional fallback
@c EN
Peek the head or the tail of the queue and returns the object, respectively.
@var{util.queue - Queue} is not modified.  
If @var{queue} is empty, @var{fallback} is returned if it is given,
otherwise an error is signalled.
@c JP
キュー@var{queue}の先頭もしくは末尾の要素を返します。キューそのものは変更されません。
キューが空の場合、@var{fallback}が与えられていればその値を返し、
そうでなければエラーを報告します。
@c COMMON
@end defun

@defun list->queue list :optional class :rest initargs
@c EN
Returns a new queue whose content is the elements in @var{list},
in the given order.

By default the created queue is a simple queue, but you
can create mtqueue or instances of other subclasses of @code{<queue>}
by giving the class to the optional @var{class} arguments.
The optional @var{initargs} arguments are passed to the constructor
of @var{class}.
@c JP
与えられたリスト@var{list}の各要素をその順で持つようなキューを作成して返します。

デフォルトではシンプルキューが作られますが、@var{class}に@code{<class>}の
サブクラスを渡すことで他のキュークラスのインスタンスを作ることができます。
@var{initargs}は@var{class}のコンストラクタに渡されます。
@c COMMON
@end defun

@defun queue->list queue
@c EN
Returns a list whose content is the items in the queue in order.
Unlike @code{dequeue-all!}, the content of @var{queue} remains intact.

In Gauche, @code{queue->list} copies the content of the queue to a
freshly allocated list, while @code{dequeue-all!} doesn't copy but
directly returns the queue's internal list.   There are some Scheme
systems that has @code{queue->list} but doesn't guarantee the content
is copied, so if you're planning to share the code among these
implementations, it's better not to rely on the fact that
@code{queue->list} copies the content.
@c JP
キュー@var{queue}の内容をリストにして返します。
@code{dequeue-all!}と異なり、キューそのものの内容は変化しません。

Gaucheでは@code{queue->list}は新しいリストをアロケートしてキューの
内容をコピーします (@code{dequeue-all!}はコピーをせずにキューの内部の
リストをそのまま返します)。組込みで@code{queue->list}を持っているScheme
実装がいくつかありますが、その中には@code{queue->list}がキューの
内容をコピーすることを保証していないものがあるので、それらの処理系と
共有するコードでは@code{queue->list}がリストをコピーすることを
あてにしない方が良いでしょう。
@c COMMON
@end defun

@defun find-in-queue pred queue
@c EN
Returns the first item in @var{queue} that satisfies a
predicate @var{pred}.  The order of arguments follows
@code{find} in SRFI-1 (@xref{SRFI-1 Searching}).
@c JP
キュー内の要素のうち述語@var{pred}を満たす最初の要素を返します。
引数の順序はSRFI-1の@code{find}に揃えました (@ref{SRFI-1 Searching}参照)。
@c COMMON
@end defun

@defun any-in-queue pred queue
@c EN
Like @code{any} in SRFI-1, apply @var{pred} on each item
in @var{queue} until it evaluates true, and returns that
true value (doesn't necessarily be @code{#t}).  If no
items in the queue satisfies @var{pred}, @code{#f} is returned.
@c JP
SRFI-1の@code{any}のように、@var{queue}中の各要素に
順に@var{pred}を適用し、それが真の値 (@code{#t}である必要はありません) に
評価されたらその値を返します。@var{pred}を満たす要素が無ければ@code{#f}が
返ります。
@c COMMON
@end defun

@defun every-in-queue pred queue
@c EN
Like @code{every} in SRFI-1, apply @var{pred} on each item
in @var{queue}.  If @var{pred} returns @code{#f}, stops
iteration and returns @code{#f} immediately.
Otherwise, returns the result of the application of
@var{pred} on the last item of the queue.  If the queue
is empty, @code{#t} is returned.
@c JP
SRFI-1の@code{every}のように、@var{queue}中の各要素に
順に@var{pred}を適用し、それが@code{#f}を返したらすぐ@code{#f}を返します。
@var{pred}に対し@code{#f}を返す要素が無ければ、最後の要素に@var{pred}を
適用した結果が返ります。キューが空なら@code{#f}が返ります。
@c COMMON
@end defun

@defun remove-from-queue! pred queue
@c EN
Removes all items in the queue that satisfies @var{pred}.
Returns @code{#t} if any item is removed.  Otherwise returns @code{#f}.
The order of arguments follows
@code{remove} in SRFI-1 (@xref{SRFI-1 Filtering & Partitioning}).
@c JP
キューから、述語@var{pred}を満たす要素を全て取り除きます。
要素が削除された場合は@code{#t}が、そうでなければ@code{#f}が返されます。
引数の順序はSRFI-1の@code{remove}に揃えました (@ref{SRFI-1 Filtering & Partitioning}参照)。
@c COMMON
@end defun

@c EN
Note on portability:
Scheme48 has @code{delete-from-queue!}, which takes object to remove
rather than predicate, and also takes arguments in reversed order
(i.e. queue comes first).   Avoid conflicting with that I intentionally
left out @code{delete-from-queue!}; it's easy to write one in either
Scheme48 compatible way or consistent to SRFI-1 argument order.
@c JP
移植性に関する註：Scheme48には、述語ではなく削除するオブジェクトそのものを取る
@code{delete-from-queue!}がありますが、引数の順序が逆(キューが先)になっています。
まぎらわしい衝突を避けるため、敢えて@code{delete-from-queue!}は
提供しませんでした。@code{remove-from-queue!}を使えば、Scheme48互換の方法でも、
あるいはSRFI-1と一貫性のある方法でも@code{delete-from-queue!}を簡単に書けるでしょう。
@c COMMON

@defun enqueue/wait! mtqueue obj :optional timeout timeout-val
@defunx queue-push/wait! mtqueue obj :optional timeout timeout-val
@defunx dequeue/wait! mtqueue :optional timeout timeout-val
@defunx queue-pop/wait! mtqueue :optional timeout timeout-val
@c EN
These synchronizing variants work on an mtqueue and
make the caller thread block when the mtqueue has reached
its maximum length (for @code{enqueue/wait!} and @code{queue-push/wait!}),
or the mtqueue is empty (for @code{dequeue/wait!} and
@code{queue-pop/wait!}).   The blocked caller thread is unblocked
either when the blocking condition is resolved, or the timeout
condition is met.

The optional @var{timeout} argument specifies the timeout condition.
If it is @code{#f}, those procedures wait indefinitely.
If it is a real number, they wait at least the given number of
seconds.  If it is a @code{<time>} object (@xref{Time}),
they wait until the absolute point of time the argument specifies.

In case the call is blocked then timed out, the value of 
@var{timeout-val} is returned, which defaults to @code{#f}.
@c JP
これらの手続きは@var{mtqueue}に対して使うことができ、
スレッド間同期を実現できます。
@code{enqueue/wait!}と@code{queue-push/wait!}は、
キューの要素数が@var{max-length}を越える場合に、キューに空きができるまで、
@code{dequeue/wait!}と@code{queue-pop/wait!}は、
キューが空の場合に、キューに要素が追加されるまで、
呼び出しスレッドをブロックします。

@var{timeout}引数で、ブロックされたスレッドのタイムアウトを指定することができます。
@code{#f}は指定しなかった場合と同じで、キューの状態が変化するまで
無期限に待ちます。実数が渡された場合はそれが秒数と解釈され、最低限
その時間経過するまでは待ちます。渡されたのが@code{<time>}オブジェクト
(@ref{Time}参照)である場合は、そのオブジェクトが指定する絶対時刻を
経過するまで待ちます。
 
タイムアウトによりブロックが解かれた場合は、@var{timeout-val}で
指定した値が返されます。@var{timeout-val}の省略時値は@code{#f}です。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Red black tree, SLIB-compatible record type, Queue, Library modules - Utilities
@section @code{util.rbtree} - Red black tree
@c NODE 赤黒木, @code{util.rbtree} - 赤黒木

@c EN
As of version 0.8.10, a balanced-tree object is built-in as @code{<tree-map>}
(@xref{Treemaps}), which uses red-black tree internally.  It is recommended
for applications to use @code{<tree-map>} instead of @code{<rbtree>}.
This module is only kept for backward compatibility.
@c JP
バージョン0.8.10から、バランス木オブジェクトは@code{<tree-map>}として
組込みになっています (@ref{Treemaps}参照)。内部的には赤黒木が使われています。
アプリケーションは@code{<rbtree>}ではなく@code{<tree-map>}を使うことが
推奨されます。このモジュールは互換性のために残されています。
@c COMMON

@deftp {Module} util.rbtree
@mdindex util.rbtree
@c EN
This module provides procedures to handle red black trees.
@c JP
このモジュールは、赤黒木 (red-black tree、2色木)を扱う手続きを提供します。
@c COMMON

@c EN
Red black tree is a kind of balanced binary tree.
For a tree with @var{n} nodes, the basic operations
such as searching, inserting, deleting, obtaining minimum
and maximum element, and sequential access, can be done in
O(log @var{n}).  The keys used for red black trees
must have total order.
@c JP
赤黒木は平衡な(バランスの取れた) 2分木の一種です。nノードからなる木
に対する基本的な操作(要素の探索、挿入、削除、最初および最大の要素の
取得、要素の順次アクセス)は、O(log n)で行われます。赤黒木に追加する
要素のキーは、要素間に全順序関係が定義されていなければなりません。
@c COMMON

@c EN
API of @code{util.rbtree} is similar to the hash table API
(@xref{Hashtables}), so the user can use a red black tree
as if it is a hashtable, with its entries are ordered 
by the keys.
@c JP
util.rbtreeのAPIはハッシュテーブルのAPIに似せて作られており、ユーザ
は赤黒木を、キーの大小で順序付けられたハッシュテーブルのように扱う
ことができます (@ref{Hashtables}参照)。
@c COMMON
@end deftp

@deftp {Class} <rbtree>
@c EN
A class for red black trees.  Inherits @code{<sequence>},
so that you can apply sequence APIs on a red black tree.
When treated as a sequence, each element is a pair of
a key and a value.
@c JP
赤黒木のクラスです。@code{<sequence>}を継承しているので、
@code{gauche.sequence}で定義されるAPIを使うことができます。
シーケンスとして扱うときの各要素は、キーと値のペアです。
@c COMMON
@end deftp

@defun make-rbtree key=? key<?
@c EN
Creates and returns an instance of @code{<rbtree>}.
The arguments @var{key=?} and @var{key<?} are both
procedures that take two arguments, which are the keys.
The @code{key=?} procedure should return @code{#t} if
two arguments are equivalent, or @code{#f} otherwise.
The @code{key<?} procedure should return @code{#t} if
the first argument is strictly less than the second argument,
or @code{#f} otherwise.
@c JP
@code{<rbtree>}オブジェクトを作成して返します。@var{key=?}、@var{key<?}はそれぞれ引
数を2つ受け取り真偽値を返す手続きであり、要素のキーが渡されます。
@var{key=?}は、2つの引数a, b が同値の場合に真を、それ以外の場合に@code{#f}を
返す手続きです。@var{key<?}は、@code{a < b}が成り立つ場合に真を、それ以外の
場合に@code{#f}を返す手続きです。
@c COMMON
@end defun

@defun rbtree-copy rbtree
@c EN
Copies and returns a red black tree @var{rbtree}.  Modification
on the returned tree doesn't affect the original tree.
@c JP
赤黒木@var{rbtree}のコピーを作り、それを返します。返された赤黒木に対す
る破壊的操作は、元の赤黒木に影響を与えません。
@c COMMON
@end defun

@defun rbtree-empty? rbtree
@c EN
Returns @code{#t} if @var{rbtree} doesn't have any elements,
or @code{#f} otherwise.
@c JP
赤黒木@var{rbtree}が要素を持たないなら@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun rbtree-num-entries rbtree
@c EN
Returns the number of elements in @var{rbtree}.
@c JP
赤黒木@var{rbtree}内の要素の個数を返します。
@c COMMON
@end defun

@defun rbtree-exists? rbtree key
@c EN
Returns @code{#t} if @var{rbtree} has an entry with @var{key},
or @code{#f} otherwise.
@c JP
赤黒木@var{rbtree}にキー@var{key}を持つエントリがあれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun rbtree-get rbtree key :optional fallback
@c EN
Looks for @var{key} in @var{rbtree}.  If the entry is found,
returns a value corresponding to the key.  Otherwise, returns
@var{fallback} if it is provided, or signals an error.
@c JP
キー@var{key}を赤黒木@var{rbtree}から探します。見つかれば@var{key}に対応する値を返
します。キーが見つからなかった場合、@var{fallback}が与えられていればそれ
を返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun rbtree-put! rbtree key value
@c EN
Inserts an entry with a @var{key} and corresponding @var{value}
into @var{rbtree}.  If there already exists an entry with a
key which is equivalent (under @var{key=?}), the entry is modified
to have @var{value}.
@c JP
キー@var{key}と対応する値@var{value}を赤黒木@var{rbtree}に挿入します。もし、@var{key}と、
@var{key=?}における意味で同じキーがすでに存在する場合、キーに対応する値
は新たな値に置き換えられます。
@c COMMON
@end defun

@defun rbtree-delete! rbtree key
@c EN
Deletes an entry with @var{key} from @var{rbtree} if such an entry
exists, and returns @code{#t}.
If @var{rbtree} doesn't have such an entry, @code{#f} is returned.
@c JP
赤黒木@var{rbtree}からキー@var{key}を持つエントリを削除します。@var{key}を持つエン
トリが実際に存在して削除された場合は@code{#t}を、エントリが存在しなかっ
た場合は@code{#f}を返します。
@c COMMON
@end defun

@defun rbtree-update! rbtree key proc :optional fallback
@c EN
A generalized version of @code{rbtree-push!} etc.
It works like the following code, except that searching
for the key is done only once.
@c JP
@code{rbtree-push!}等のより一般的なバージョンです。赤黒木の探索が一度
しか行われないことを除いては、基本的に次のように動作します。
@c COMMON
@example
(let ((tmp (proc (rbtree-get @var{rbtree} @var{key} @var{fallback}))))
  (rbtree-put! @var{rbtree} @var{key} tmp)
  tmp)
@end example
@end defun

@defun rbtree-push! rbtree key value
@c EN
Looks for an entry with @var{key} in @var{rbtree}.  If it exists,
the procedure conses @var{value} to the original value and makes
it as a new value.
Otherwise, the procedure creates a new entry for the @var{key}
and makes @code{(list @var{value})} its value.
@c JP
赤黒木@var{rbtree}中の、キー@var{key}に対応する値に@var{value}をコンスし、それを@var{key}
に対する新たな値とします。もし@var{key}に対応する値がまだ無ければ、新た
なエントリが作成され、@code{(list @var{value})}がその値となります。
@c COMMON
@end defun

@defun rbtree-pop! rbtree key :optional fallback
@c EN
Looks for an entry with @var{key} in @var{rbtree}.  If it exists
and its value is a pair, then the procedure updates
its value with @code{cdr} of the original value, and returns
@code{car} of the original entry.   If such an entry does not
exist, or has a non-pair value, the procedure doesn't
modify @var{rbtree} and returns @var{fallback} if it is given,
otherwise reports an error.
@c JP
赤黒木@var{rbtree}中のキー@var{key}に対応する値が存在し、かつペアであった場合
に、そのエントリの値を元の値のcdrで置き換え、元の値のcarを返します。
@var{key}に対応する値が存在しないかペアではなかった場合、赤黒木@var{rbtree}は
変更されず、@var{fallback}が与えられていればそれが返され、与えられていな
ければエラーが報告されます。
@c COMMON
@end defun

@defun rbtree-min rbtree :optional fallback
@defunx rbtree-max rbtree :optional fallback
@c EN
Returns a pair of a key and its value with the minimum
or maximum key, respectively.   If @var{rbtree} is empty,
returns @var{fallback} if it is given, otherwise reports
an error.
@c JP
それぞれ、赤黒木@var{rbtree}に含まれる最小および最大のキーを探索し、その
キーと値のペアを返します。赤黒木@var{rbtree}が空だった場合は、@var{fallback}が
指定されていればそれを返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun rbtree-extract-min! rbtree :optional fallback
@defunx rbtree-extract-max! rbtree :optional fallback
@c EN
Looks for an entry with minimum or maximum key, respectively,
then deletes the entry from @var{rbtree} and returns 
a pair of the key and its value of the original entry.
If @var{rbtree} is empty,
returns @var{fallback} if it is given, otherwise reports
an error.
@c JP
それぞれ、赤黒木@var{rbtree}に含まれる最小および最大のキーを探索し、そ
のエントリを赤黒木@var{rbtree}から削除したうえで、そのキーと値のペアを
返します。赤黒木@var{rbtree}が空だった場合は、@var{fallback}が指定されていれば
それを返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun rbtree-fold rbtree proc seed
@defunx rbtree-fold-right rbtree proc seed
@c EN
Iterate over elements in @var{rbtree}, applying 
@var{proc} which has a type @code{(key, value, seed) -> seed}.
The difference of @code{rbtree-fold} and @code{rbtree-fold-right}
is the same as @code{fold} and @code{fold-right}---that is,
the associative order of applying @code{proc}.
@c JP
@var{rbtree}の各要素に対し、@code{(key, value, seed) -> seed} の型を持つ
@var{proc}を適用してゆきます。
@code{rbtree-fold}と@code{rbtree-fold-right}の違いは
@code{fold}の@code{fold-right}違いと同じ、すなわち
結合の方向にあります。
@c COMMON
@example
rbtree-fold:
  (proc Kn Vn (proc Kn-1 Vn-1 ... (proc K0 V0 seed)))

rbtree-fold-right
  (proc K0 V0 (proc K1 V1 ... (proc Kn Vn seed)))
@end example

@c EN
Some examples:
@c JP
例:
@c COMMON
@example
(define tree (alist->rbtree '((3 . a) (7 . b) (5 . c)) = <))

(rbtree-fold tree list* '()) 
   @result{} (7 b 5 c 3 a)
(rbtree-fold-right tree list* '()) 
   @result{} (3 a 5 c 7 b)
@end example
@end defun

@defun rbtree-keys rbtree
@defunx rbtree-values rbtree
@c EN
Returns a list of all keys and all values, respectively.
The keys and values are in ascending order of the keys.
@c JP
それぞれ、赤黒木@var{rbtree}内の全てのキーまたは値をリストにして返しま
す。返されるリストの要素はキーの昇順に並んでいます。
@c COMMON
@end defun

@defun rbtree->alist rbtree
@c EN
Returns a list of pairs of keys and values for all entries.
The pairs are in ascending order of the keys.
@c JP
赤黒木@var{rbtree}含まれる要素を連想リストにして返します。返される連
想リストのキーは昇順に並んでいます。
@c COMMON
@end defun

@defun alist->rbtree alist key=? key<?
@c EN
Creates a new red black tree with @var{key=?} and @var{key<?},
then populates it with @var{alist}, each pair in which are
interpreted as a cons of a key and its value.  Returns the
created red black tree.
@c JP
@var{key=?}, @var{key<?} によって新たな赤黒木を作成し、
連想リスト@var{alist}に含まれる要素を追加し、その木を返します。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node SLIB-compatible record type, Relation framework, Red black tree, Library modules - Utilities
@section @code{util.record} - SLIB-compatible record type
@c NODE SLIB-互換のレコード型, @code{util.record} - SLIB-互換のレコード型

@deftp {Module} util.record
@mdindex util.record
@c EN
This module provides a Guile and SLIB compatible record type API.
It is built on top of Gauche's object system.

See also @ref{Record types}, which provides a convenience macro
@code{define-record-type}.
@c JP
このモジュールは、Guile と SLIB とに互換性のあるレコード型 API を提供します。
これは、Gauche のオブジェクトシステム上に構築されています。

便利なマクロ @code{define-record-type} を提供する @ref{Record types} も
参照してください。
@c COMMON
@end deftp

@defun make-record-type type-name field-names
@c EN
Returns a new class which represents a new record type.
(It is what is called @emph{record-type descriptor} in SLIB).
In Gauche, the new class is a subclass of @code{<record>}
(see @ref{Record types}).

@var{type-name} is a string that is used for debugging purposes.
It is converted to a symbol and set as the name of the new class.
@var{field-names} is a list of symbols of the names of fields.
Each field is implemented as a slot of the new class.
@c JP
あらしいレコード型を表わす新しいクラスを返します。
(これは SLIB では @emph{レコード型記述子}とよばれているものです。)
Gauche では、この新しいクラスは @code{<record>} のサブクラスです
(@ref{Record types} 参照)。

@var{type-name} はデバッグの目的で使われる文字列です。
これは、シンボルに変換され、この新しいクラスの名前として設定されます。
@var{field-names} はフィールド名のシンボルのリストです。
各々のフィールドはこの新しいクラスのスロットとして実装されます。
@c COMMON
@end defun

@c EN
In the following procedures, @var{rtd} is the record class
created by @code{make-record-type}.
@c JP
以下の手続きでは、@var{rtd} は @code{make-record-type} によって
生成されたクラスです。
@c COMMON

@defun record-constructor rtd :optional field-names
@c EN
Returns a procedure that constructs an instance
of the record type of given @var{rtd}.  The returned
procedure takes exactly as many arguments as @var{field-names},
which defaults to @code{'()}.  Each argument sets the initial
value of the corresponding field in @var{field-names}.
@c JP
与えられた @var{rtd} レコード型のインスタンスを構築する手続きを
返します。返された手続きは @var{field-names} とちょうど同じ数の
引数をとります。@var{field-names} のデフォルトは @code{'()} です。
それぞれの引数は @var{field-names} の対応するフィールドの初期値を
設定します。
@c COMMON
@end defun

@defun record-predicate rtd
@c EN
Returns a procedure that takes one argument, which returns @code{#t}
iff the given argument is of type of @var{rtd}.
@c JP
一つの引数をとり、与えられた引数が @var{rtd} と同じ型であり、その場合に
限り @code{#t} を返す手続きを返します。
@c COMMON
@end defun

@defun record-accessor rtd field-name
@c EN
Returns an accessor procedure for the field named by @var{field-name}
of type @var{rtd}.  The accessor procedure takes an instance of
@var{rtd}, and returns the value of the field.
@c JP
@var{rtd} 型の @var{field-name} によって名付けられたフィールドへの
アクセサ手続きを返します。このアクセサ手続きは、@var{rtd} のインスタンスを
一つとり、そのフィールドの値を返します。
@c COMMON
@end defun

@defun record-modifier rtd field-name
@c EN
Returns a modifier procedure for the field named by @var{field-name}
of type @var{rtd}.  The modifier procedure takes two arguments,
an instance of @var{rtd} and a value, and sets the value to
the specified field.
@c JP
@var{rtd} 型の @var{field-name} によって名付けられたフィールドへの
モディファイア手続きを返します。このモディファイア手続きは、
@var{rtd} のインスタンスと値のふたつの引数をとり、その引数を
指定されたフィールドに設定します。
@c COMMON
@end defun

@example
(define rtd (make-record-type "my-record" '(a b c)))

rtd @result{} #<class my-record>

(define make-my-record (record-constructor rtd '(a b c)))

(define obj (make-my-record 1 2 3))

obj @result{} #<my-record 0x819d9b0>

((record-predicate? rtd) obj)  @result{} #t

((record-accessor rtd 'a) obj) @result{} 1
((record-accessor rtd 'b) obj) @result{} 2
((record-accessor rtd 'c) obj) @result{} 3

((record-modifier rtd 'a) obj -1)

((record-accessor rtd 'a) obj) @result{} -1
@end example

@c ----------------------------------------------------------------------
@node Relation framework, Sparse data containers, SLIB-compatible record type, Library modules - Utilities
@section @code{util.relation} - Relation framework
@c NODE @code{util.relation} - リレーションフレームワーク

@deftp {Module} util.relation
@mdindex util.relation
@c EN
Provides a set of common operations for relations.
@c JP
リレーションに対する共通の操作を提供します。
@c COMMON

@c EN
Given set of values S1, S2, ..., Sn, a relation R is a set of tuples
such that the first element of a tuple is from S1, the second from
S2, ..., and the n-th from Sn.  In another word, R is a subset of
Cartesian product of S1, ..., Sn.
(The definition, as well as the term @emph{relation}, is taken 
from the Codd's 1970 paper, 
"A Relational Model of Data for Large Shared Data Banks", in
CACM 13(6) pp.377--387.)
@c JP
値の集合を S1, S2, ..., Sn とするとリレーション R はタプルの集合で、
タプルの最初の要素は S1 からの値で、2番目は S2 から、で n 番目は
Sn からとなっている。いいかえれば、R は S1, ..., Sn の直積です。
(この定義と@emph{リレーション}という用語は 1970年のCoddのペーパー
"A Relational Model of Data for Large Shared Data Banks", in
CACM 13(6) pp.377--387.によるものです。)
@c COMMON

@c EN
This definition can be applied to various datasets: A set of Gauche
object system instances is a relation, if you view each instance as
a tuple and each slot value as the actual values.  A list of lists can be a
relation.  A stream that reads from CSV table produces a relation.
Thus it would be useful to provide a module that implements generic
operations on relations, no matter how the actual representation is.
@c JP
この定義はいろいろなデータベースセットにあてはまります。各インスタンス
をタプルとみなし、各スロット値を実際の値と見ると、Gaucheのオブジェクト
システムの集合はリレーションです。リストのリストもリレーションです。
CSVテーブルからの読み出しストリームはリレーションを生成します。このよ
うことから、表現に依存しないリレーション上のジェネリックな操作を実装す
るモジュールを用意することは有意義です。
@c COMMON

@c EN
From the operational point of view, we can treat any datastructure
that provides the following four methods; @code{relation-rows},
which retrieves a collection of tuples (rows);
@code{relation-column-names}, @code{relation-accessor}, and
@code{relation-modifier}, which provide the means to access
meta-information.
All the rest of relational operations are built on top of
those primitive methods.
@c JP
操作という観点からいえば、以下の4つのメソッドがあれば、どのようなデー
タ構造もあつかえます。タプルのコレクション(行)を取り出す
@code{relation-rows}、それから、@code{relation-column-names}、
@code{relation-accessor}、@code{relation-modifier}、これらはメタ情報に
アクセスする方法を提供しています。これ以外のすべてのリレーション操作は
上のプリミティブメソッドを使って組まれています。
@c COMMON

@c EN
A concrete implementation of relation can use duck typing,
i.e. it doesn't need to inherit a particular base class to
use the relation methods.  However, for the convenience,
a base class @code{<relation>} is provided in this module.
It works as a mixin class---a concrete class typically wants
to inherit @code{<relation>} and @code{<collection>} or
@code{<sequence>}.  Check out the sample implementations
in the @file{lib/util/relation.scm} in the source tree, if
you're curious.
@c JP
リレーションの具体的な実装にはダックタイピングが適用できます。
すなわち、リレーションメソッドを使うのに特定のベースクラスを継承する必
要はありません。しかし、利便のためにこのモジュールには、ベースクラス
@code{<relation>}が用意されています。これは、ミックスインクラスのよう
な働きをします。具象クラスは典型的には@code{<relation>}および
@code{<collection>}または@code{<sequence>}を継承することになるでしょう。
興味があれば、ソースツリーにある@file{lib/util/relation.scm}に含まれる
サンプル実装をチェックするとよいでしょう。
@c COMMON

@c EN
This module is still under development.
The plan is to build useful relational operations on top of the
common methods.
@c JP
このモジュールは現時点では開発途上にあります。計画では共通メソッド上に
有用なリレーション操作関数群を構築することになっています。
@c COMMON
@end deftp

@c EN
@subheading Basic class and methods
@c JP
@subheading 基本となるクラスとメソッド
@c COMMON

@deftp {Class} <relation>
@c EN
An abstract base class of relations.
@c JP
リレーションの抽象ベースクラス
@c COMMON
@end deftp

@deffn {Method} relation-column-names (r <relation>)
@c EN
A subclass must implement this method.
It should return a sequence of names of the columns.
The type of column names is up to the relation; we don't
place any restriction on it, as far as they are different
each other in terms of @code{equal?}.
@end deffn
@c JP
サブクラスではこのメソッドを必ず実装しなければなりません。
カラムの名前のシーケンスを返す必要があります。カラム名の型はリレーショ
ンによります。@code{equal?}の意味で相互に異っているかぎり、カラム名に
ついて特に制限はありません。
@end deffn
@c COMMON

@deffn {Method} relation-accessor (r <relation>)
@c EN
A subclass must implement this method.
It should return a procedure that takes two arguments, a row from
the relation @var{r} and a column name, and returns the value
of the specified column.
@c JP
サブクラスではこのメソッドは必ず実装しなければなりまん。2つの引数をと
り、リレーション@var{r}の行とカラム名をとり、指定したカラムの値を返す
手続を返さなければなりません。
@c COMMON
@end deffn

@deffn {Method} relation-modifier (r <relation>)
@c EN
A subclass must implement this method. It should returns a procedure
that takes three arguments, a row from the relation @var{r}, a column
name, and a value to set. 
@c JP
サブクラスではこのメソッドは必ず実装しなければなりまん。
3つの引数、リレーション@var{r}の行、カラム名、値をとり、その値をセット
する手続を返さなければなりません。
@c COMMON

@c EN
If the relation is read-only, this method returns @code{#f}.
@c JP
リレーションが読み込み専用の場合はこのメソッドは@code{#f}を返します。
@c COMMON
@end deffn

@deffn {Method} relation-rows (r <relation>)
@c EN
A subclass must implement this method.
It should return the underlying instance of @code{<collection>} or
its subclass (e.g.  @code{<sequence>}) 
@c JP
サブクラスではこのメソッドは必ず実装しなければなりまん。
基盤となっている@code{<collection>}クラスまたはそのサブクラス(たとえば
@code{<sequence>})のインスタンスを返さなければなりません。
@c COMMON
@end deffn

@c EN
The rest of method are built on top of the above four methods.
A subclass of @code{<relation>} may overload some of the
methods below for better performance, though.
@c JP
のこりのメソッドは上の4つのメソッドを使って組まれています。とはいえ、
@code{<relation>} のサブクラスでは以下のメソッドを性能を得るためにオー
バーロードすることもできます。
@c COMMON

@deffn {Method} relation-column-name? (r <relation>) column
@c EN
Returns true iff @var{column} is a valid column name for the relation
@var{r}.
@c JP
@var{column}がリレーション@var{r}において有効なカラム名である場合にの
み真を返します。
@c COMMON
@end deffn

@deffn {Method} relation-column-getter (r <relation>) column
@deffnx {Method} relation-column-setter (r <relation>) column
@c EN
Returns a procedure to access the specified column of a row
from the relation @var{r}.  @code{Relation-column-getter}
should return a procedure that takes one argument, a row.
@code{Relation-column-setter} should return a procedure that
takes two arguments, a row and a new value to set.
@c JP
リレーション@var{r}の行の指定したカラムにアクセスする手続を返します。
@code{Relation-column-getter}は、1つの引数、行をとる手続きを返さなけれ
ばなりません。@code{Relation-column-setter}は2つの引数、行と新しくセッ
トする値を取る手続きを返さなければなりません。
@c COMMON

@c EN
If the relation is read-only, @code{relation-column-setter}
returns @code{#f}.
@c JP
リレーションが読み込み専用の場合は@code{relation-column-setter}
は@code{#f}を返します。
@c COMMON
@end deffn

@deffn {Method} relation-ref (r <relation>) row column :optional default
@c EN
@var{Row} is a row from the relation @var{r}.  Returns value of
the @var{column} in @var{row}.  If @var{column} is not a valid
column name, @var{default} is returned if it is given, otherwise
an error is signalled.
@c JP
@var{row}はリレーション@var{r}の行です。@var{row}の@var{column}の値を
返します。@var{column}が不正なカラム名である場合、@var{default}が与え
られていればそれを返し、そうでなければ、エラーを示すシグナルがあがりま
す。
@c COMMON
@end deffn

@deffn {Method} relation-set! (r <relation>) row column value
@c EN
@var{Row} is a row from the relation @var{r}.  Sets @var{value}
as the value of @var{column} in @var{row}.  This may signal
an error if the relation is read-only.
@c JP
@var{row}はリレーション@var{r}の行です。@var{value}を@var{row}の
@var{column}に設定します。リレーションが読み込み専用の場合には
エラーを示すシグナルがあがります。
@c COMMON
@end deffn

@deffn {Method} relation-column-getters (r <relation>)
@deffnx {Method} relation-column-setters (r <relation>)
@c EN
Returns full list of getters and setters.  Usually the default
method is sufficient, but the implementation may want to cache
the list of getters, for example.
@c JP
ゲッタとセッタの完全なリストを返します。通常はデフォルトのメソッドで十
分ですが、たとえばゲッタのリストをキャッシュしたいときもあるでしょう。
@c COMMON
@end deffn

@deffn {Method} relation-coercer (r <relation>)
@c EN
Returns a procedure that coerces a row into a sequence.
If the relation already uses a sequence to represent a row,
it can return row as is.
@c JP
行をシーケンスに変換する手続きを返します。行がすでにシーケンスで表現さ
れているリレーションであれば、行をそのまま返す手続きです。
@c COMMON
@end deffn

@deffn {Method} relation-insertable? (r <relation>)
@c EN
Returns true iff new rows can be inserted to the relation @var{r}.
@c JP
リレーション@var{r}に新しい行を挿入可能な場合にのみ真を返します。
@c COMMON
@end deffn

@deffn {Method} relation-insert! (r <relation>) row
@c EN
Insert a row @var{row} to the relation @var{r}.
@c JP
リレーション@var{r}に行@var{row}を挿入します。
@c COMMON
@end deffn

@deffn {Method} relation-deletable? (r <relation>)
@c EN
Returns true iff rows can be deleted from the relation @var{r}.
@c JP
リレーション@var{r}から行を削除可能である場合にのみ真を返します。
@c COMMON
@end deffn

@deffn {Method} relation-delete! (r <relation>) row
@c EN
Deletes a row @var{row} from the relation @var{r}.
@c JP
リレーション@var{r}から行@var{row}を削除します。
@c COMMON
@end deffn

@deffn {Method} relation-fold (r <relation>) proc seed column @dots{}
@c EN
Applies @var{proc} to the values of @var{column} @dots{} of each row,
passing @var{seed} as the state value.  That is, for each row in 
@var{r}, @var{proc} is called as follows:
@c JP
@var{proc}を各行のカラム@var{column} @dots{} の値に適用します。
@var{seed}は状態の値として渡されます。すなわち、リレーション@var{r}の
各行ごとに以下のように@var{proc}を呼びます。
@c COMMON
@example

(@var{proc} @var{v_0} @var{v_1} @dots{} @var{v_i} @var{seed})

 where @var{v_k} = (relation-ref @var{r} @var{row} @var{column_k})

@end example

@c EN
The result of the call becomes a new seed value, and the final result
is returned from @var{relation-fold}.
@c JP
呼び出しの結果があたらしいシードの値となり、最終の結果が
@var{relation-fold}から返ります。
@c COMMON

@c EN
For example, if a relation has a column named @code{amount},
and you want to sum up all of them in a relation @var{r},
you can write like this:
@c JP
たとえば、リレーションが @code{amount} という名前のカラムをもつものと
し、リレーション @var{r} 内にあるそのカラムをすべて足しあわせたいとす
ると以下のように書けます。
@c COMMON
@example
(relation-fold r + 0 'amount)
@end example
@end deffn

@c EN
@subheading Concrete classes
@c JP
@subheading 具象クラス
@c COMMON

@deftp {Class} <simple-relation>
@end deftp

@deftp {Class} <object-set-relation>
@end deftp

@c ----------------------------------------------------------------------
@node Sparse data containers, Stream library, Relation framework, Library modules - Utilities
@section @code{util.sparse} - Sparse data containers
@c NODE @code{util.sparse} - 疎なデータコンテナ

@deftp {Module} util.sparse
@mdindex util.sparse
This module provides a @emph{sparse vector}, a space efficient
data containter indexed by nonnegative integer, and
a @emph{sparse table}, a hash table using a sparse vector
as a backing storage.
@end deftp

A sparse vector associates a nonnegative integer index 
to a value.  It has @emph{vector} in its name since it is indexed
by an integer, but it isn't like a flat array on contiguous memory;
it's more like an associative array.  (Internally, the current
implementation uses compact trie structure.)
It is guaranteed that you can store a value with index at least
up to @code{2^32-1}; the actual maximum bits of indexes can
be queried by @code{sparse-vector-max-index-bits}.

Unlike ordinary vectors, you don't need to specify the size
of a sparse vector when you create one.  You can just set
a value to any index in the supported range.

@example
(define v (make-sparse-vector))

(sparse-vector-set! v 0 'a)
(sparse-vector-ref v 0) @result{} a

(sparse-vector-set! v 100000000 'b)
(sparse-vector-ref v 100000000) @result{} b
@end example

If you try to access an element that hasn't been set,
an error is signalled by default.  You can give a
fallback value to @code{sparse-vector-ref} to suppress
the error.

@example
(sparse-vector-ref v 1)        @result{} @r{error}
(sparse-vector-ref v 1 'noval) @result{} noval
@end example

A sparse table works just like a hash table, but it uses
a sparse vector to store the values using hashed number of keys.

The main reason of these sparse data containers are for
memory efficiency.   If you want to store values in a vector
but knows you'll use only some entries sparsely, obviously it
is waste to allocate a large vector and to leave many entries unused.
But it is worse than that; Gauche's GC doesn't like a large 
contiguous region of memory.  Using lots of large vectors adds 
GC overhead quickly.  It becomes especially visible when you
store large number of entries (like >100,000) into hash tables,
since Gauche's builtin hash tables use a flat vector as a backing
storage.   You'll see the heap size grows quickly and
GC runs more frequently and longer.
On the other hand, sparse table works pretty stable with
large number of entries.  

Sparse data containers does have overhead on access speed.
They are a bit slower than the ordinary hash tables,
and much slower than ordinary vectors.  We should note, however,
as the number of entries grow, access speed on ordinary hash
tables grows quicker than sparse tables and eventually two become
comparable.

It depends on your application which you should use, and
if you're not sure, you need to benchmark.
As a rule of thumb, if you use more than several hashtables
each of which contains more than a few tens of thousands of
entries, sparse tables may work better.
If you see GC Warnings telling ``repeated allocation of large
blocks'', you should definitely consider sparse tables.

@menu
* Sparse vectors::              
* Sparse tables::               
@end menu

@node Sparse vectors, Sparse tables, Sparse data containers, Sparse data containers
@subsection Sparse vectors
@c NODE 疎なベクタ

@deftp {Class} <sparse-vector-base>
@clindex sparse-vector-base
An abstract base class of sparse vectors. 
Inherits @code{<dictionary>} and @code{<collection>}.
Note that sparse vectors are @emph{not} @code{<sequence>}; even
they can be indexable by integers, they don't have
means of @emph{ordered} access.

Sparse vector may be a general vector
that can contain any Scheme objects (like @code{<vector>}), 
or a specialized vector that can contain only certain
types of numbers (like @code{<s8vector>} etc.).

All of these sparse vectors can be accessed by the same API.

Sparse vectors also implements the Collection API
(@xref{Collection framework}) and the Dictionary API
(@xref{Dictionary framework}).
@end deftp

@deftp {Class} <sparse-vector>
@deftpx {Class} <sparse-@var{TAG}vector>
@clindex sparse-vector
@clindex sparse-s8vector
@clindex sparse-u8vector
@clindex sparse-s16vector
@clindex sparse-u16vector
@clindex sparse-s32vector
@clindex sparse-u32vector
@clindex sparse-s64vector
@clindex sparse-u64vector
@clindex sparse-f16vector
@clindex sparse-f32vector
@clindex sparse-f64vector
The actual sparse vector classes.  Inherits @code{<sparse-vector-base>}.
An instance of @code{<sparse-vector>} can contain any Scheme objects.

@var{TAG} either one of @code{s8}, @code{u8},
@code{s16}, @code{u16}, @code{s32}, @code{u32},
@code{s64}, @code{u64}, @code{f16}, @code{f32}, or @code{f64}.
The range of values an instance of those classes can hold
is the same as the corresponding @code{<@var{TAG}vector>} class
in @code{gauche.uvector} (@xref{Uniform vectors}).  That is,
@code{<sparse-u8vector>} can have exact integer values 
between 0 and 255.
@end deftp

@defun make-sparse-vector :optional type
Creates an empty sparse vector.  The @var{type} argument can be
@code{#f} (default), one of subclasses of @code{<sparse-vector-base>},
or a symbol of either one of @code{s8}, @code{u8},
@code{s16}, @code{u16}, @code{s32}, @code{u32},
@code{s64}, @code{u64}, @code{f16}, @code{f32}, or @code{f64}.

If @var{type} is omitted or @code{#f}, a @code{<sparse-vector>} is
created.  If it is a class, an instance of the class is created
(It is an error to pass a class that is not a subclass of
@code{<sparse-vector-base>}.)
If it is a symbol, an instance of corresponding @code{<sparse-@var{TAG}vector>}
is created.
@end defun

@defun sparse-vector-max-index-bits
Returns maximum number of bits of allowed integer.  If this 
returns 32, the index up to @code{(expt 2 32)} is supported.
It is guaranteed that this is at least 32.
@end defun

In the following entries, the argument @var{sv} denotes
an instance of sparse vector; an error is signalled if other
object is passed.

@defun sparse-vector-copy sv
Returns a copy of a sparse vector @var{sv}.
@end defun
 
@defun sparse-vector-ref sv k :optional default
Returns @var{k}-th element of a sparse vector @var{sv}, where
@var{k} must be a nonnegative exact integer.  If @var{k} is
equal to or greater than the allowed index range, an error
is signalled.

If @var{k} is within the allowed range but the sparse vector
doesn't have a value for @var{k}, @var{default} is returned
if it is provided, otherwise an error is signalled.
@end defun

@defun sparse-vector-set! sv k value
Sets @var{value} for @var{k}-th element of a sparse vector @var{sv}.
@var{K} must be a nonnegative exact integer, and below the maximum
allowed index.

If @var{sv} is a numeric sparse vector, @var{value} must also be
within the allowed range, or an error is signalled.
@end defun

@defun sparse-vector-num-entries sv
Returns the number of entries in @var{sv}.
@end defun

@defun sparse-vector-exists? sv k
Returns @code{#t} if @var{sv} has an entry for index @var{k},
@code{#f} otherwise.
@end defun

@defun sparse-vector-delete! sv k
Deletes the @var{k}-th entry of @var{sv}.  If @var{sv} had the entry ,
returns @code{#t}.  If @var{sv} didn't have the entry, returns @code{#f}.
@end defun

@defun sparse-vector-clear! sv
Empties a sparse vector.
@end defun

@defun sparse-vector-inc! sv k delta :optional (fallback 0)
This is a shortcut of the following.  It is especially efficient
for numeric sparse vectors.

@example
(sparse-vector-set! sv k (+ (sparse-vector-ref sv k fallback) delta))
@end example

If the result of addition exceeds the allowed value range of @var{sv},
an error is signalled.  In future we'll allow an option to clamp
the result value within the range.
@end defun

@defun sparse-vector-update! sv k proc :optional fallback
@defunx sparse-vector-push! sv k val
@defunx sparse-vector-pop! sv k :optional fallback
Convenience routines to fetch-and-update an entry of
a sparse vector.  Works just like @code{hash-table-update!},
@code{hash-table-push!} and @code{hash-table-pop!}; 
(@xref{Hashtables}).
@end defun


The following procedures traverses a sparse vector.
Note that elements are not visited in the order of index;
it's just like hash table traversers.

At this moment, if you want to walk a sparse vector with
increasing/decreasing index order, you have to get a list
of keys by @code{sparse-vector-keys}, sort it, then use
it to retrieve values.
We may add an option in future to @code{make-sparse-vector} so that
those walk operation

@defun sparse-vector-fold sv proc seed
For each entry in @var{sv}, calls @var{proc} as
@code{(proc @var{k_n} @var{v_n} @var{seed_n})}, where 
@var{k_n} is an index and @var{v_n} is a value for it,
and @var{seed_n} is the returned value of the previous
call to @code{proc} if @var{n} @code{>=} 1, and @var{seed} if @var{n} = 0.
Returns the value of the last call of @code{proc}.
@end defun

@defun sparse-vector-for-each sv proc
@defunx sparse-vector-map sv proc
Calls @code{proc} with index and value, e.g. @code{(proc k value)},
for each element of @var{sv}.

The results of @var{proc} are discarded by @code{sparse-vector-for-each},
and gathered to a list and returned by @code{sparse-vector-map}.
@end defun

@defun sparse-vector-keys sv
@defunx sparse-vector-values sv
Returns a list of all keys and all values in @var{sv}, respectively.
@end defun

@node Sparse tables,  , Sparse vectors, Sparse data containers
@subsection Sparse tables
@c NODE 疎なテーブル

@deftp {Class} <sparse-table>
@clindex sparse-table
A class for sparse table.  Inherits @code{<dictionary>} and
@code{<collection>}.

Operationally sparse tables are the same as hash tables, but
the former consumes less memory in trade of slight slower access.
(Roughly x1.5 to x2 access time when the table is small.
As the table gets larger the difference becomes smaller.)
@end deftp

@defun make-sparse-table type
Creates and returns an empty sparse table.  The @var{type} argument
specifies how to compare the elements; currently it can be
one of the symbols @code{eq?}, @code{eqv?}, @code{equal?} and
@code{string=?}, like hash tables (@xref{Hashtables}).
@end defun

@defun sparse-table-copy st
Returns a copy of a sparse table @var{st}.
@end defun

@defun sparse-table-num-entries st
Returns the number of entries in a sparse table @var{st}.
@end defun

@defun sparse-table-ref st key :optional fallback
Retrieves a value associated to the @var{key} in @var{st}.
If no entry with @var{key} exists, @var{fallback} is returned
when it is provided, or an error is signalled otherwise.
@end defun

@defun sparse-table-set! st key value
Sets @var{value} with @var{key} in @var{st}.
@end defun

@defun sparse-table-exists? st key
Returns @code{#t} if an entry with @var{key} exists in @var{st},
@code{#f} otherwise.
@end defun

@defun sparse-table-delete! st key
Deletes an entry with @var{key} in @var{st} if it exists.
Returns @code{#t} if an entry is actually deleted, or @code{#f}
if there hasn't been an entry with @var{key}.
@end defun

@defun sparse-table-clear! st
Empties @var{st}.
@end defun

@defun sparse-table-update! st key proc :optional fallback
@defunx sparse-table-push! st key val
@defunx sparse-table-pop! st key :optional fallback
@end defun

@defun sparse-table-fold st proc seed
@defunx sparse-table-for-each st proc
@defunx sparse-table-map st proc
@end defun

@defun sparse-table-keys st
@defunx sparse-table-values st
@end defun


@c ----------------------------------------------------------------------
@node Stream library, Trie, Sparse data containers, Library modules - Utilities
@section @code{util.stream} - Stream library
@c NODE ストリームライブラリ, @code{util.stream} - ストリームライブラリ

@deftp {Module} util.stream
@mdindex util.stream
@c EN
This module provides a library of lazy streams, including the
functions and syntaxes defined in srfi-40.
@c JP
このモジュールは遅延ストリームのライブラリを提供します。このモジュール
には SRFI-40 で定義されている関数および構文が含まれています。
@c COMMON
@end deftp

@defun stream? obj
[SRFI-40]
@c EN
Returns @code{#t} iff @var{obj} is a stream created by a procedure
of @code{util.stream}.
@c JP
@var{obj}が@code{util.stream}の手続きによって作成されたストリームであ
る場合にかぎり@code{#t}を返します。
@c COMMON
@end defun

@defvar stream-null
[SRFI-40]
@c EN
The singleton instance of NULL stream.
@c JP
NULLストリームのシングルトンインスタンス。
@c COMMON
@end defvar

@defmac stream-cons object stream
[SRFI-40]
@c EN
A fundamental constructor of a stream.  Adds @var{object} to the
head of a @var{stream}, and returns a new stream.
@c JP
ストリームの基本構成子。@var{object}を@var{stream}の先頭に追加し、新し
いストリームを返します。
@c COMMON
@end defmac

@defun stream-null? obj
[SRFI-40]
@c EN
Returns @code{#t} iff @var{obj} is the null stream.
@c JP
@var{obj}がNULLストリームの場合にのみ@code{#t}を返します。
@c COMMON
@end defun

@defun stream-pair? obj
[SRFI-40]
@c EN
Returns @code{#t} iff @var{obj} is a non-null stream.
@c JP
@var{obj}がNULLストリームではないストリームのときにのみ@code{#t}を返します。
@c COMMON
@end defun

@defun stream-car s
[SRFI-40]
@c EN
Returns the first element of the stream @var{s}.
@c JP
ストリーム@var{s}の最初の要素を返します。
@c COMMON
@end defun

@defun stream-cdr s
[SRFI-40]
@c EN
Returns the remaining elements of the stream @var{s}, as a stream.
@c JP
ストリーム@var{s}の最初の要素をのぞいたのこりの要素をストリームとして
返します。
@c COMMON
@end defun

@defmac stream-delay expr
[SRFI-40]
@c EN
Returns a stream which is a delayed form of @var{expr}.
@c JP
@var{expr}の遅延形式であるストリームを返します。
@c COMMON

@c EN
As a rule of thumb, any stream-producing functions should
wrap the resulting expression by @code{stream-delay}.
@c JP
原則として、ストリームを生成する関数はすべからく結果を
@code{stream-delay}でラップすべきです。
@c COMMON
@end defmac

@defun stream obj @dots{}
[SRFI-40]
@c EN
Returns a new stream whose elements are @var{obj} @dots{}.
@c JP
要素が@var{obj} @dots{}であるような新しいストリームを返します。
@c COMMON
@end defun

@defun stream-unfoldn generator seed n
[SRFI-40]
@c EN
Creates @var{n} streams related each other, whose contents are
generated by @var{generator} and @var{seed}.
@c JP
互いに関連する @var{n} 本のストリームを生成します。それぞれの内容は
@var{generator}および@var{seed}を使って生成します。
@c COMMON

@c EN
The @var{generator} is called with the current seed value,
and returns @code{@var{n}+1} values:
@c JP
@var{generator}は現在のシード値とともに呼ばれ、@code{@var{n}+1}個の値
を返します。
@c COMMON
@example
(@var{generator} @var{seed})
  => seed result_0 result_1 @dots{} result_n-1
@end example

@c EN
The first value is to be the next seed value.
@var{Result_k} must be one of the following forms:
@table @code
@item (val)
@var{val} will be the next car of @var{k}-th stream.
@item #f
No new information for @var{k}-th stream.
@item ()
The end of @var{k}-th stream has been reached.
@end table
@c JP
最初の値は次のシード値になります。@var{Result_k}は以下の形式のどれかで
なければなりません。
@table @code
@item (val)
@var{val}は@var{k}-番目のストリームの次のcar部になります。
@item #f
@var{k}-番目のストリームの新しい情報はありません。
@item ()
@var{k}-番目のストリームの最後に到達しました。
@end table
@c COMMON

@c EN
The following example creates two streams, the first one produces
an infinite series of odd numbers and the second produces evens.
@c JP
以下の例では2つのストリームが作られます。最初のものは奇数の無限ストリー
ムで、2つめのものは偶数の無限ストリームです。
@c COMMON

@example
gosh> (define-values (s0 s1)
        (stream-unfoldn (lambda (i)
                          (values (+ i 2)          ;; next seed
                                  (list i)         ;; for the first stream
                                  (list (+ i 1)))) ;; for the second stream
                        0 2))
#<undef>
gosh> (stream->list (stream-take s0 10))
(0 2 4 6 8 10 12 14 16 18)
gosh> (stream->list (stream-take s1 10))
(1 3 5 7 9 11 13 15 17 19)
@end example

@end defun

@defun stream-map func . streams
[SRFI-40]
@c EN
Returns a new stream, whose elements are calculated by
applying @var{func} to each element of @var{streams}.
@c JP
@var{streams}の各要素に@var{func}を適用した値を要素とする新しいストリー
ムを返します。
@c COMMON
@end defun

@defun stream-for-each func . streams
[SRFI-40]
@c EN
Applies @var{func} for each element of @var{streams}.
Terminates if one of @var{streams} reaches the end.
@c JP
@var{func}を@var{streams}の各要素に適用します。
@var{streams}が終端にたっしたところで停止します。
@c COMMON
@end defun

@defun stream-filter pred? stream
[SRFI-40]
@c EN
Returns a new stream including only elements passing @var{pred?}.
@c JP
@var{pred?}をパスする要素のみからなる新しいストリームを返す。
@c COMMON
@end defun

@c EN
The following procedures are taken from the library written by
Alejandro Forero Cuervo for Chicken Scheme.  They follow
the naming conventions of srfi-1 (@ref{List library}).
@c JP
以下の手続きは Alejandro Forero Cuervo が Chicken Schemeのために書いた
ライブラリから取ってきたものです。これらの手続きの名前は srfi-1
(@ref{List library})の命名規則にならったものです。
@c COMMON

@defun stream-xcons a b
@c EN
@code{(stream-cons b a)}.  Just for convenience.
@c JP
@code{(stream-cons b a)}のこと。利便性のためだけにある。
@c COMMON
@end defun

@defun stream-cons* elt @dots{} stream
@c EN
Creates a new stream which appends @var{elt} @dots{} before @var{stream}.
@c JP
@var{stream}の前に@var{elt} @dots{}を連結した新しいストリームを生成し
ます。
@c COMMON
@end defun

@defun make-stream n :optional init
@c EN
Creates a new stream of @var{n} elements of @var{init}.
If @var{init} is omitted, @code{#f} is used.
Specifying a negative number to @var{n} creates an infinite stream.
@c JP
@var{n}個の@var{init}を要素とする新しいストリームを生成します。
@var{init}が省略された場合@code{#f}が使われます。@var{n}を負の値にする
と無限ストリームが生成されます。
@c COMMON
@end defun

@defun stream-tabulate n init-proc
@c EN
Creates a new stream of @var{n} elements.
The @var{k}-th element is obtained by applying @var{init-proc}
to @var{k}.  Specifying a negative number to @var{n} creates
an infinite stream.
@c JP
@var{n}個の要素をもつ新しいストリームを生成します。@var{k}-番目の要素
は @var{init-proc} を @var{k} に適用して得られます。@var{n}を負の値にする
と無限ストリームが生成されます。
@c COMMENT
@end defun

@defun stream-iota count :optional start step
@c EN
Creates a new stream of integers, starting from @var{start}
and incrementing @var{step}.  The length of stream is @var{count}
if it is positive, or infinite if @var{count} is negative.
The default values of @var{start} and @var{step} are 0 an 1,
respectively.
@c JP
@var{start}からはじまり、@var{step}ずつ要素が増加する整数のストリーム
を生成します。ストリームの長さは@var{count}が正ならその値になります。
@var{count}が負なら無限ストリームになります。@var{start}のデフォルト値
は 0、@var{step}のデフォルト値は 1 です。
@c COMMON
@end defun

@defun stream-format fmt arg @dots{}
@c EN
Returns a stream which is a result of applying @code{string->stream}
to @code{(format fmt arg @dots{})}.
@c JP
@code{string->stream}を@code{(format fmt arg @dots{})}に適用した結果の
ストリームを返します。
@c COMMON
@end defun

@defun stream->list stream
@defunx stream->string stream
Converts a stream to a list or a string.  All of @var{stream}'s
elements are @code{force}d; if @var{stream} is infinite, these
procedures won't terminate.  For @code{stream->string},
all @var{stream} must be characters, or an error is signalled.
@end defun

@defun list->stream list
Converts a list to a stream of its elements.
@end defun

@defun string->stream string :optional stream
Convers a string to a stream of characters.  If an optional
@var{stream} is given, it becomes the tail of the resulting
stream.

@example
@end example
(stream->list (string->stream "abc" (list->stream '(1 2 3))))
 @result{} (#\a #\b #\c 1 2 3)
@end defun

@defun port->stream :optional iport reader closer
Creates a stream, whose elements consist of the items
read from the input port @var{iport}.
The default @var{iport} is the current input port.
The default @var{reader} is @code{read-char}.

The result stream terminates at the point where @var{reader}
returns EOF (EOF itself is not included in the stream).
If @var{closer} is given, it is called with @var{iport} as
an argument just after @var{reader} reads EOF.
@end defun

@defun iterator->stream iter
A generic procedure to turn an internal iterator @var{iter}
into a stream of iterated results.

The @var{iter} argument is a procedure that takes two arguments,
@var{next} and @var{end}, where @var{next} is a procedure that takes
one argument and @var{end} is a thunk.
@var{Iter} is supposed to iterate over some set and call @var{next}
for each argument, then call @var{end} to indicate the end of
the iteration.  Here's a contrived example:

@example
(stream->list
 (iterator->stream 
  (lambda (next end) (for-each next '(1 2 3 4 5)) (end))))
 @result{} (1 2 3 4 5)
@end example

Internally @code{iterator->stream} uses the ``inversion of iterator''
technique, so that @var{iter} only iterates to the element that
are needed by the stream.  Thus @var{iter} can iterate over 
an infinite set.  In the following example, @var{iter} is
an infinite loop calling @var{next} with increasing integers,
but only the first 10 elements are calculated because of
@code{stream-take}:

@example
(stream->list 
 (stream-take
  (iterator->stream
   (lambda (next end)
     (let loop ((n 0)) (next n) (loop (+ n 1))))) 
  10))
 @result{} (0 1 2 3 4 5 6 7 8 9)
@end example
@end defun

@defun stream-lines stream
Splits @var{stream} where its element equals to @code{#\n}, and 
returns a stream of splitted streams.

@example
(stream->list 
 (stream-map stream->string 
             (stream-lines (string->stream "abc\ndef\nghi"))))
 @result{} ("abc" "def" "ghi")
@end example
@end defun

@defun stream= elt= stream @dots{}
Returns true iff each corresponding element of @var{stream} @dots{}
are the same in terms of @var{elt=}.  This procedure won't terminate
if any of @var{stream}s is infinite.
@end defun

@defun stream-prefix= stream prefix :optional elt=
Compares initial elements of @var{stream} against
a list @var{prefix} by @var{elt=}.  Only as many elements of @var{stream}
as @var{prefix} has are checked.
@end defun

@defun stream-caar s
@defunx stream-cadr s
@findex stream-cdar
@findex stream-cddr
@findex stream-caaar
@findex stream-caadr
@findex stream-cadar
@findex stream-caddr
@findex stream-cdaar
@findex stream-cdadr
@findex stream-cddar
@findex stream-cdddr
@findex stream-caaaar
@findex stream-caaadr
@findex stream-caadar
@findex stream-caaddr
@findex stream-cadaar
@findex stream-cadadr
@findex stream-caddar
@findex stream-cadddr
@findex stream-cdaaar
@findex stream-cdaadr
@findex stream-cdadar
@findex stream-cdaddr
@findex stream-cddaar
@findex stream-cddadr
@dots{}
@end defun
@defun stream-cdddar s
@defunx stream-cddddr s
@code{(stream-caar s)} = @code{(stream-car (stream-car s))} etc.
@end defun

@defun stream-ref stream pos
Returns the @var{pos}-th element in the stream.  @var{Pos}
must be a nonnegative exact integer.
@end defun

@defun stream-first s
@defunx stream-second s
@defunx stream-third s
@defunx stream-fourth s
@defunx stream-fifth s
@defunx stream-sixth s
@defunx stream-seventh s
@defunx stream-eighth s
@defunx stream-ninth s
@defunx stream-tenth s
@code{(stream-first s)} = @code{(stream-ref s 0)} etc.
@end defun

@defun stream-take stream count
@defunx stream-take-safe stream count
Returns a new stream that consists of the first @var{count} elements 
of the given stream.   If the given stream has less than
@var{count} elements, the stream returned by @code{stream-take} 
would raise an error when the elements beyond the original stream
is accessed.  On the other hand, the stream returned by 
@code{stream-take-safe} will return a shortened stream when
the given steram has less than @var{count} elements.

@example
(stream->list (stream-take (stream-iota -1) 10))
 @result{} (0 1 2 3 4 5 6 7 8 9)

(stream-take (stream 1 2) 5)
 @result{} @r{stream}

(stream->list (stream-take (stream 1 2) 5))
 @result{} @r{error}

(stream->list (stream-take-safe (stream 1 2) 5))
 @result{} (1 2)
@end example

@end defun

@defun stream-drop stream count
@defunx stream-drop-safe stream count
Returns a new stream that consists of the elements in the given 
stream except the first @var{count} elements.
If the given stream has less than @var{count} elements,
@code{stream-drop} returns a stream that raises an error
if its element is accessed, and @code{stream-drop-safe}
returns an empty stream.
@end defun

@defun stream-intersperse stream element
Returns a new stream in which @var{element} is
inserted between elements of @var{stream}.
@end defun

@defun stream-split stream pred
@end defun

@defun stream-last stream
@end defun

@defun stream-last-n stream count
@end defun

@defun stream-butlast stream
@end defun

@defun stream-butlast-n stream count
@end defun

@defun stream-length stream
@end defun

@defun stream-length>= stream n
@end defun

@defun stream-append stream @dots{}
@end defun

@defun stream-concatenate streams
@end defun

@defun stream-reverse stream :optional tail-stream
@end defun

@defun stream-count pred stream @dots{}
@end defun

@defun stream-remove pred stream
@end defun

@defun stream-partition pred stream
@end defun

@defun stream-find pred stream
@end defun

@defun stream-find-tail pred stream
@end defun

@defun stream-take-while pred stream
@end defun

@defun stream-drop-while pred stream
@end defun

@defun stream-span pred stream
@end defun

@defun stream-break pred stream
@end defun

@defun stream-any pred stream @dots{}
@end defun

@defun stream-every pred stream @dots{}
@end defun

@defun stream-index pred stream @dots{}
@end defun

@defun stream-member obj stream :optional elt=
@defunx stream-memq obj stream
@defunx stream-memv obj stream
@end defun

@defun stream-delete obj stream :optional elt=
@end defun

@defun stream-delete-duplicates stream :optional elt=
@end defun

@defun stream-grep re stream
@end defun

@defun write-stream stream :optional oport writer
@end defun

@c ----------------------------------------------------------------------
@node Trie, Topological sort, Stream library, Library modules - Utilities
@section @code{util.trie} - Trie
@c NODE @code{util.trie} - Trie

@deftp {Module} util.trie
@mdindex util.trie
@c EN
This module provides @emph{Trie}, a dictionary-like data
structure that maps keys to values, where a key is an arbitrary sequence.
Internally it stores the data as a tree where each node corresponds 
to each element in the key sequence.
Key lookup is O(n) where n is the length of the key, and not affected
much by the number of total entries.
Also it is easy to find a set of values whose keys have a common prefix.
@c JP
このモジュールは@emph{Trie}を提供します。@emph{Trie}はディレクトリに似
たデータ構造で、キーを値に写像します。また、キーは任意のシーケンスです。
内部的にはデータはツリーとして保持されます。このとき各ノードがキーシー
ケンスの各要素に対応します。キーの検索は O(n) で、n はキーの長さです。
したがって、全体のエントリ数には余り影響を受けません。また、キーが共通
の接頭辞をもつような値の集合を簡単にみつけられます。
@c COMMON

@c EN
The following example may give you the idea.
@c JP
以下のサンプルを見れば考え方が理解できると思います。
@c COMMON

@example
(define t (make-trie))   ;; create a trie

(trie-put! t "pho" 3)    ;; populate the trie
(trie-put! t "phone" 5)
(trie-put! t "phrase" 6)

(trie-get t "phone")  @result{} 5  ;; lookup

(trie-common-prefix t "pho")       ;; common prefix search
  @result{} (("phone" . 5) ("pho" . 3))
(trie-common-prefix-keys t "ph")
  @result{} ("phone" "pho" "phrase")
@end example

@c EN
Tries are frequently used with string keys, but you are not
limited to do so; any sequence (@xref{Sequence framework}) can be
a key.  If the types of keys differ, they are treated as different
keys:
@c JP
Trieでは文字列キーを使うことが多いですが、それに限定される必要はありま
せん。あらゆるシーケンス(@xref{Sequence framework})をキーにすることが
できます。キーの型が違えば、別のキーとして扱われます。
@c COMMON

@example
(trie-put! t '(#\p #\h #\o) 8)  ;; different key from "pho"
@end example

@c EN
Trie inheris @code{<collection>} and implements collection framework
including the builder. So you can apply generic collection 
operations on a trie (@xref{Collection framework}).
When iterated, each element of a trie appears as a pair of a key
and a value.
@c JP
Trieは@code{<collection>}を継承しており、コレクションフレームワークを
ビルダも含めて実装しています。それゆえ、ジェネリックなコレクション操作
をTrieに適用することが可能です(@ref{Collection framework}参照)。
反復するとTrieの各要素がキーと値の対として現れます。
@c COMMON
@end deftp

@deftp {Class} <trie>
@c EN
A class for Trie.  No slots are intended for public.  
Use the following procedures to operate on tries.
@c JP
Trieクラス。パブリックなスロットはありません。trieを操作するには以下の
手続きを使ってください。
@c COMMON
@end deftp

@defun make-trie :optional tab-make tab-get tab-put! tab-fold
@c EN
Creates and returns an empty trie.  The optional four arguments
are procedures to customize how the nodes of the internal
tree are managed.
@c JP
空のtrieを生成し返します。4つのオプション引数があり、これらは、
内部木のノードをどのようにマージするかをカスタマイズする手続きです。
@c COMMON

@c EN
Each node can have a table to store its child nodes, indexed
by an element of the key sequence (e.g. if the trie uses strings
as keys, a node's table is indexed by characters).
@c JP
それぞれのノードは子のノードを格納するテーブルを持つことができます。
キーシーケンスの要素でインデックスできます。(たとえば、trieがキーとし
え文字列を使っているとすると、ノードのテーブルは文字でインデックスされ
ています。)
@c COMMON

@c EN
@table @code
@item tab-make
A procedure with no arguments.  When called, creates and
returns an empty table for a node.
@item tab-get @var{tab} @var{elt}
Returns a child node indexed by @var{elt}, or returns @code{#f}
if the table doesn't have a child for @var{elt}.
@item tab-put! @var{tab} @var{elt} @var{child-node}
If @var{child-node} isn't @code{#f}, 
stores a @var{child-node} with index @var{elt}.  
If @var{child-node} is @code{#f}, 
removes the entry with index @var{elt}. 
In both cases, this procedure should return the updated table.
@item tab-fold @var{tab} @var{proc} @var{seed}
Calls @var{proc} for every index and node in @var{tab}, while
passing a seed value, whose initial value is @var{seed}.
That is, @var{proc} has a type of @code{(index, node, seed) -> seed}.
Should return the last result of @var{proc}.
@end table
@c JP
@table @code
@item tab-make
引数なしの手続き。呼ばれるとノード用の空テーブルを生成し返します。
@item tab-get @var{tab} @var{elt}
@var{elt}でインデックスされた子ノードを返すか、あるいは@var{elt}に対応
する子がテーブルにない場合には @code{#f}を返します。
@item tab-put! @var{tab} @var{elt} @var{child-node}
@var{child-node}が@code{#f}でなければ、@var{child-node}に@var{elt}とい
うインデックスをつけて保存します。@var{child-node}が@code{#f}なら
@var{elt}のインデックスをもつエントリを削除します。どちらの場合にも
この手続きは更新されたテーブルを返します。
@item tab-fold @var{tab} @var{proc} @var{seed}
@var{tab}内の各インデックスと要素ごとに@var{proc}を呼びます。シード値
が順に渡されていきます。シード値の初期値は@var{seed}です。すなわち、
@var{proc}の型は@code{(index, node, seed) -> seed} のような型というこ
とになります。返り値は最後の@var{proc}の適用結果です。
@end table
@c COMMON

@c EN
The default assumes @code{eqv?}-hashtables, i.e. the
following procedures are used.
@c JP
デフォルトでは@code{eqv?}-ハッシュ可能であることが仮定されます。すなわ
ち、以下の手続きが使われます。
@c COMMON

@example
tab-make: (lambda () (make-hash-table 'eqv?))

tab-get:  (lambda (tab k) (hash-table-get tab k #f))

tab-put!: (lambda (tab k v)
            (if v
              (hash-table-put! tab k v)
              (hash-table-delete! tab k))
            tab)

tab-fold: hash-table-fold
@end example

@c EN
The following example creates a trie using
assoc list to manage children, while comparing
string keys with case-insensitive way:
@c JP
以下の例では子を管理するのに連想リストを用いるtrieを作成しています。
文字列キーの比較は大文字小文字を無視する方法で行っています。
@c COMMON

@example
(make-trie list
           (cut assoc-ref <> <> #f char-ci=?)
           (lambda (t k v)
             (if v
               (assoc-set! t k v char-ci=?)
               (alist-delete! k t char-ci=?)))
           (lambda (t f s) (fold f s t)))
@end example

@c EN
It is important that @code{tab-put!} must return an updated
table---by that, you can replace the table structure on the fly.
For example, you may design a table which uses assoc list when
the number of children are small, and then switches to a vector
(indexed by character code) once the number of children grows over
a certain threshold.
@c JP
@code{tab-put!}が更新されたテーブルを返すというのは重要で、これのおか
げで、テーブル構造をおてがるに置き換えることができます。たとえば、
子の数が少い場合にはテーブルに連想リストを使い、いったん子の数がある閾
値を越えたら、(文字コードでインデックスされた)ベクタを使うように設計す
ることができます。
@c COMMON
@end defun

@defun trie params kv @dots{}
@c EN
Construct a trie with the initial contents
@var{kv} @dots{}, where each @var{kv} is a pair of a key and a value.
@var{Params} are a list of arguments
which will be given to @code{make-trie} to create the trie.
The following example creates a trie with two entries
and the default table procedures.
@c JP
初期の内容が@var{kv} @dots{} であるようなtrieを構成します。ここで、
@var{kv}はキーと値の対です。@var{params}はtrieを生成するときに
@code{make-trie}に渡される引数のリストです。以下の例は2つのエントリ
とデフォルトのテーブル手続をもつtrieを生成します。
@c COMMON

@example
(trie '() '("foo" . a) '("bar" . b))
@end example
@end defun

@defun trie-with-keys params key @dots{}
@c EN
A convenient version of @code{trie} when you only concern
the keys.  Each value is the same as its key.
The following example creates a trie with two entries
and the default table procedures.
@c JP
キーにだけ関心がある場合には便利な@code{trie}。各値はキーと同じ。以下
の例では2つのエントリとデフォルトのテーブル手続をもつtrieを生成します。
@c COMMON

@example
(trie-with-keys '() "foo" "bar")
@end example
@end defun

@defun trie? obj
@c EN
Returns @code{#t} if @var{obj} is a trie, or @code{#f} otherwise.
@c JP
@var{obj}がtrieなら@code{#t}を返し、さもなければ@code{#f}を返します。
@c COMMON
@end defun

@defun trie-num-entries trie
@c EN
Returns the number of entries in @var{trie}.
@c JP
@var{trie}中のエントリの数を返します。
@c COMMON
@end defun

@defun trie-exists? trie key
@c EN
Returns @code{#t} if @var{trie} contains an entry with @var{key},
or returns @code{#f} otherwise.
@c JP
@var{trie}が@var{key}というキーのエントリを含む場合には@code{#t}を返し、
さもなければ、@code{#f}を返します。
@c COMMON
@end defun

@defun trie-get trie key :optional fallback
@c EN
Returns the value associated with @var{key} in @var{trie}, if 
such an entry exists.  When there's no entry for @var{key},
if @var{fallback} is given, it is returned; otherwise,
an error is signalled.
@c JP
@var{trie}中の@var{key}をもつエントリがあれば、それにむすびついている
値を返します。そのようなエントリがない場合、@var{fallback}が与えられて
いればそれを返し、さもなければ、エラーシグナルがあがります。
@c COMMON
@end defun

@defun trie-put! trie key value
@c EN
Puts @var{value} associated to @var{key} into @var{trie}.
@c JP
@var{key}に結びついた@var{value}を@var{trie}に挿入します。
@c COMMON
@end defun

@defun trie-update! trie key proc :optional fallback
@c EN
Works like the following code, except that the
lookup of entry in @var{trie} is done only once.
@c JP
@var{trie}中のエントリの検索が一度きりしか起らないことをのぞけば以下の
コードのように動きます。
@c COMMON

@example
(let ((val (trie-get trie key fallback)))
  (trie-put! trie key (proc val)))
@end example
@end defun

@defun trie-delete! trie key
@c EN
Removes an entry associated with @var{key} from @var{trie}.
If there's no such entry, this procedure does nothing.
@c JP
@var{trie}から@var{key}に関連するエントリを削除します。
そのようなエントリがない場合にはこの手続きはなにもしません。
@c COMMON
@end defun

@defun trie->list trie
@c EN
Makes each entry in @var{trie} to a pair @code{(@var{key} . @var{value})}
and returns a list of pairs of all entries.  The order of entries
are undefined.
@c JP
@var{trie}の各エントリを@code{(@var{key} . @var{value})}という対にして
すべてのエントリの対のリストを返します。エントリの順序は未定義です。
@c COMMON
@end defun

@defun trie-keys trie
@defunx trie-values trie
@c EN
Returns a list of all keys and values in @var{trie}, respectively.
The order of keys/values are undefined.
@c JP
それぞれ、@var{trie}のすべてのキーのリスト、すべての値のリストを返しま
す。順序は未定義です。
@c COMMON
@end defun

@defun trie->hash-table trie ht-type
@c EN
Creates a hash table with type @var{ht-type} (see @ref{Hashtables}, 
about hash table types), and populates it with every key and value
pair in @var{trie}.
@c JP
@var{ht-type}タイプのハッシュテーブル(ハッシュテーブルのタイプについて
は@ref{Hashtables}を参照)を作成し、@var{trie}のすべてのキーと値の対を
セットします。
@c COMMON
@end defun

@defun trie-common-prefix trie prefix
@defunx trie-common-prefix-keys trie prefix
@defunx trie-common-prefix-values trie prefix
@c EN
Gathers all entries whose keys begin with @var{prefix};
@code{trie-common-prefix} returns those entries in a list of
pairs @code{(key . value)}; @code{trie-common-prefix-keys} returns
a list of keys; and @code{trie-common-prefix-values} returns a list
of values.   The order of entries in a returned list is undefined.
If @var{trie} contains no entry whose key has @var{prefix}, an
empty list is returned.
@c JP
@var{prefix}ではじまるキーをもつエントリをすべて集め、
@code{trie-common-prefix}はその各エントリを@code{(key . value)}の対にし
たリストを返します。@code{trie-common-prefix-keys}は、キーのリストを
@code{trie-common-prefix-values}は値のリストを返します。返されるリスト
のエントリの順序は未定義です。
@var{trie}に指定した@var{prefix}をもつキーのエントリがなければ、
空リストが返されます。
@c COMMON

@c EN
Note that prefix matching doesn't consider the type of sequence;
if @var{trie} has entries for @code{"foo"} and @code{(#\f #\o #\o)},
@code{(trie-common-prefix trie "foo")} will return both entries.
@c JP
接頭辞照合ではシーケンスの型を考慮しないことに注意してください。
@var{trie}のなかに@code{"foo"}と@code{(#\f #\o #\o)}に対応するエントリ
があれば、@code{(trie-common-prefix trie "foo")}はその両方を返します。
@c COMMON
@end defun

@defun trie-common-prefix-fold trie prefix proc seed
@c EN
For each entry whose key begins with @var{prefix},
calls @var{proc} with three argments, the entry's key,
its value, and the current seed value.  @var{Seed} is
used for the first seed value, and the value @var{proc}
returns is used for the seed value of the next call of @var{proc}.
The last returned value from @var{proc} is returned from 
@code{trie-common-prefix-fold}.
The order of entries on which @var{proc} is called is undefined.
If @var{trie} contains no entry whose key has @var{prefix}, 
@var{proc} is never called and @var{seed} is returned.
@c JP
@var{prefix}ではじまるキーをもつ各エントリに対して、@var{proc}を3つの
引数、エントリのキー、値、現在のシード値で呼びます。@var{seed}は最初の
シード値として使われ、@var{proc}が返す値は次の@var{proc}の呼び出しのシー
ド値として使われます。@var{proc}が返した最後の値が
@code{trie-common-prefix-fold}から返ります。
@var{proc}が適用される順序は未定義です。@var{trie}が@var{prefix}を持つ
キーのエントリを含まない場合には@var{proc}が呼ばれることはなく、
@var{seed}が返ります。
@c COMMON
@end defun

@defun trie-common-prefix-map trie prefix proc
@defunx trie-common-prefix-for-each trie prefix proc
@c EN
These are to @var{trie-common-prefix-fold} as @code{map} and @code{for-each}
are to @code{fold}; @code{trie-common-prefix-map} calls
@var{proc} with key and value for matching entries and
gathers its result to a list; @code{trie-common-prefix-for-each}
also applies @var{proc}, but discards its results.
@c JP
@code{map}や@code{for-each}を@code{fold}を合せたのと同じように、
@var{trie-common-prefix-fold}に合せたものです。
@code{trie-common-prefix-map}は@var{proc}をマッチするエントリのキーと
値に適用し結果をリストにあつめます。
@code{trie-common-prefix-for-each}も同じく@var{proc}を適用しますが
結果は捨てます。
@c COMMON
@end defun

@defun trie-fold trie proc seed
@defunx trie-map trie proc
@defunx trie-for-each trie proc
@c EN
These procedures are like their common-prefix versions, but
traverse entire @var{trie} instead.
@c JP
これらの手続きはcommon-prefix版とおなじような働きをしますが、
@var{trie}全体をトラバースします。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Topological sort, CGI Utility, Trie, Library modules - Utilities
@section @code{util.toposort} - Topological sort
@c NODE トポロジカルソート, @code{util.toposort} - トポロジカルソート

@deftp {Module} util.toposort
@mdindex util.toposort
@c EN
Implements topological sort algorithm.
@c JP
トポロジカルソートのアルゴリズムを実装します。
@c COMMON
@end deftp

@defun topological-sort graph :optional eqproc
@c EN
@var{Graph} represents a directed acyclic graph (DAG) by a list
of connections, where each connection is the form
@example
(<node> <downstream> <downstream2> ...)
@end example
that means a node @code{<node>} is connected to other nodes
@code{<downstream>} etc.   @code{<node>} can be arbitrary
object, as far as it can be compared by the procedure @var{eqproc},
which is @var{eqv?} by default (@xref{Equivalence}).
Returns a list of @code{<node>}s sorted topologically.

If the graph contains circular reference, an error is signalled.
@c JP
@var{Graph}は有向非循環グラフ(DAG)を表現するリストです。
リストの各要素は次の形をしています。
@example
(<node> <downstream> <downstream2> ...)
@end example
これで、ノード@code{<node>}から別のノード@code{<downstream>}等への接続が
あることを表現します。@code{<node>}はどんなオブジェクトであっても構いませんが、
同一性の判定が@var{eqproc}で行えなければなりません。@var{eqproc}の既定値は
@code{eqv?}です (@ref{Equivalence}参照)。
トポロジカルにソートされたノードのリストを返します。

グラフに循環が検出された場合はエラーとなります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node CGI Utility, CGI testing, Topological sort, Library modules - Utilities
@section @code{www.cgi} - CGI utility
@c NODE CGIユーティリティ, @code{www.cgi} - CGIユーティリティ

@deftp {Module} www.cgi
@mdindex www.cgi
@c EN
Provides a few basic functions useful to write a CGI script.

In order to write CGI script easily, you may want to use
other modules, such as @code{rfc.uri} (@xref{URI parsing and construction}),
@code{text.html-lite} (@xref{Simple HTML document construction}) and
@code{text.tree} (@xref{Lazy text construction}).

Note: it seems that there is no active formal specification for CGI.
See @uref{http://w3c.org/CGI/} for more information.
@c JP
CGIスクリプトを書くのに便利ないくつかの基本的な手続きを提供します。

CGIスクリプトを手軽に書くにはこのモジュールの他に、
@code{rfc.uri} (@ref{URI parsing and construction})、
@code{text.html-lite} (@ref{Simple HTML document construction})、
@code{text.tree} (@ref{Lazy text construction}) 等のモジュールを併せて
使うとよいでしょう。

注：現在有効な、CGIに関する「正式な」仕様というのはどうも無いようです。
@uref{http://w3c.org/CGI/}あたりを参照して下さい。
@c COMMON
@end deftp

@c EN
@subheading Metavariables
@c JP
@subheading メタ変数
@c COMMON

@deffn {Parameter} cgi-metavariables :optional metavariables
@c EN
Normally, httpd passes a cgi program various information
via environment variables.
Most procedures in @code{www.cgi} refer to them (meta-variables). 
However, it is sometimes inconvenient to require environment variable access
while you're developing cgi-related programs.
With this parameter, you can overrides the information of meta-variables.

@var{Metavariables} should be a list of two-element lists.
Car of each inner list names the variable, and its cadr gives the
value of the variable by string.

For example, the following code overrides @code{REQUEST_METHOD}
and @code{QUERY_STRING} meta-variables during execution of
@code{my-cgi-procedure}.  (@xref{Parameters},
for the details of @code{parameterize}).
@c JP
通常、httpdはcgiプログラムに様々な情報を環境変数経由で渡します。
@code{www.cgi}中の多くの手続きはその情報(メタ変数)を参照します。
しかし、cgiに関連するプログラムを開発中に環境変数にアクセスするのは
不便な場合もあります。
このパラメータを使うと、メタ変数をオーバライドすることができます。

@var{Metavariables}は2要素のリストのリストです。
内側のリストは、最初の要素が変数名を、2つめの要素がその値を、それぞれ
文字列で与えます。

例えば次のコードは@code{REQUEST_METHOD}と
@code{QUERY_STRING}のメタ変数を@code{my-cgi-procedure}の実行期間中に
上書きします。(@code{parameterize}の詳細については
@ref{Parameters}を参照して下さい)。
@c COMMON

@example
(parameterize ((cgi-metavariables '(("REQUEST_METHOD" "GET")
                                    ("QUERY_STRING" "x=foo"))))
  (my-cgi-procedure))
@end example
@end deffn

@defun cgi-get-metavariable name
@c EN
Returns a value of cgi metavariable @var{name}.
This function first searches the parameter @code{cgi-metavariables},
and if the named variable is not found, calls @code{sys-getenv}.

CGI scripts may want to use @code{cgi-get-metavariable} instead
of directly calling @code{sys-getenv}; doing so makes reuse of
the script easier. 
@c JP
@var{name}で指定されるCGIメタ変数の値を返します。
この関数はまずパラメータ@code{cgi-metavariables}を探し、
指定されたメタ変数が見つからなければ@code{sys-getenv}を呼びます。

CGIスクリプトは、なるべく@code{sys-getenv}を直接呼ぶのではなく
@code{cgi-get-metavariable}を使うのが良いでしょう。
スクリプトの再利用もしやすくなります。
@c COMMON
@end defun

@c EN
@subheading Parameter extraction
@c JP
@subheading パラメータの取得
@c COMMON

@defun cgi-parse-parameters :key :query-string :merge-cookies :part-handlers
@c EN
Parses query string and returns associative list of parameters.
When a keyword argument @var{query-string} is given, it is used
as a source query string.  Otherwise, the function checks the 
metavariable @code{REQUEST_METHOD} and obtain the query string
depending on the value (either from stdin or from the
metavariable @code{QUERY_STRING}).
If such a metavariable is not defined and
the current input port is a terminal, the function prompts the user
to type parameters; it is useful for interactive debugging.
@c JP
CGIプログラムに渡されたquery stringをパーズして、パラメータの連想リストにして
返します。文字列がキーワード引数@var{query-string}に与えられればそれがパーズすべき
query stringとなります。その引数が渡されなければこの手続きは
メタ変数@code{REQUEST_METHOD}を参照し、その値によって標準入力もしくは
メタ変数@code{QUERY_STRING}からquery stringが取られます。
そのようなメタ変数が定義されておらず、かつ現在の入力ポートが端末である場合、
インタラクティブにデバッグをしているものと考えて、
この手続きはプロンプトを出してユーザにパラメータの入力を促します。
@c COMMON

@c EN
If @code{REQUEST_METHOD} is @code{POST}, this procedure can handle
both @code{application/x-www-from-urlencoded} and 
@code{multipart/form-data} as the enctype.  The latter is usually
used if the form has file-uploading capability.

When the post data is sent by @code{multipart/form-data}, 
each content of the part is treated as a value of the parameter.
That is, the content of uploaded file will be seen as one big 
chunk of a string.  The other information, such as the original file
name, is discarded.   If it is not desirable to read entire file
into a string, you can customize the behavior by the @var{part-handler}
argument.  The details are explained in the "Handling file uploads"
section below.
@c JP
@code{REQUEST_METHOD}が@code{POST}の場合、この手続きはenctypeとして
@code{application/x-www-from-urlencoded}と@code{multipart/form-data}の
両方を処理できます。後者は通常、ファイルアップロード機能を持つフォームに使われます。

POSTデータが@code{multipart/form-data}で送られて来た場合、
各パートの内容がパラメータの値となります。すなわち、アップロードされた
ファイルはその内容がひとつの文字列として得られることになります。
元のファイル名のようなその他の情報は捨てられます。これが望ましい動作で
ない場合は、@var{part-handlers}引数によって動作をカスタマイズすることができます。
詳しくは下の「ファイルアップロードの処理」で説明します。
@c COMMON

@c EN
When a true value is given to @var{merge-cookies}, the cookie
values obtained from the metavariable @code{HTTP_COOKIE}
are appended to the result.
@c JP
キーワード引数@var{merge-cookies}に真の値が与えられた場合は、
メタ変数@code{HTTP_COOKIE}からクッキーの値が読まれ、解析されて
結果に追加されます。
@c COMMON

@c EN
Note that the query parameter may have multiple values,
so @code{cdr} of each element in the result is a list, not an atom.
If no value is given to the parameter, @code{#t} is placed as its value.
See the following example:
@c JP
パラメータは複数の値を取り得るため、結果のパラメータに対応する値は常にリストになります。
パラメータに値が与えられていなければ、結果のパラメータに対する値には@code{#t}が置かれます。
次の例を参照して下さい。
@c COMMON
@example
(cgi-parse-parameters
  :query-string "foo=123&bar=%22%3f%3f%22&bar=zz&buzz")
 @result{} (("foo" "123") ("bar "\"??\"" "zz") ("buzz" #t))
@end example
@end defun


@defun cgi-get-parameter name params :key :default :list :convert
@c EN
A convenient function to obtain a value of the parameter @var{name} from
parsed query string @var{params}, which is the value
@code{cgi-parse-parameters} returns.  @var{Name} should be a string.
@c JP
@code{cgi-parse-parameters}が返す、パーズされたQuery文字列@var{params}から、
名前@var{name}を持つパラメータの値を簡単に取り出すための手続きです。
@var{name}は文字列です。
@c COMMON

@c EN
Unless true value is given to @var{list}, the returned value is
a scalar value.  If more than one value is associated to @var{name},
only the first value is returned.  If @var{list} is true, the
returned value is always a list, even @var{name} has only one value.
@c JP
キーワード引数@var{list}に真の値が与えられていなければ、
返される値はスカラー値です。パラメータ@var{name}に複数の値が与えられた場合でも、
最初の値のみが返されます。@var{list}に真の値が与えられれば、返されるのは
常に値のリストとなります。
@c COMMON

@c EN
After the value is retrieved, you can apply a procedure to
convert the string value to the appropriate type by giving
a procedure to the @var{convert} argument.  The procedure must
take one string argument.  If @var{list} is true, the convert
procedure is applied to each values.
@c JP
キーワード引数@var{convert}に手続きを与えると、対応する値が取り出された後でその
手続きが値を引数として呼ばれます。これによって値を文字列から必要な型へと変換することが
できます。@var{list}に真の値が与えられている場合、変換手続きは各値に対して呼ばれ、
その結果のリストが@var{cgi-get-parameter}から返されます。
@c COMMON

@c EN
If the parameter @var{name} doesn't appear in the query,
a value given to the keyword argument @var{default} is returned;
the default value of @var{default}
is @code{#f} if @var{list} is false, or @code{()} otherwise.
@c JP
パラメータ@var{name}がQuery中に現れなかった場合は、
@var{default}に与えられた値がそのまま
返されます。@var{default}が省略された場合、@var{list}が偽であれば@code{#f}が、
真であれば@code{()}が返されます。
@c COMMON
@end defun

@c EN
@subheading Output generation
@c JP
@subheading 出力の生成
@c COMMON


@defun cgi-header :key status content-type location cookies
@c EN
Creates a text tree (@xref{Lazy text construction}) for the
HTTP header of the reply message.  The most simple form is
like this:
@c JP
HTTPリプライメッセージのヘッダを、テキストツリー形式(@ref{Lazy text construction}参照)
で作成して返します。最も簡単な呼び出しでは次のようになります。
@c COMMON
@example
(tree->string (cgi-header))
  @result{} "Content-type: text/html\r\n\r\n"
@end example

@c EN
You can specify alternative content-type by the keyword argument
@var{content-type}.   If you want to set cookies to the client,
specify a list of cookie strings to the keyword argument @var{cookies}.
You can use @code{construct-cookie-string} (@xref{HTTP cookie handling})
to build such a list of cookie strings.
@c JP
キーワード引数@var{content-type}によってContent typeを指定できます。
また、@var{cookies}にクッキー文字列のリストを渡すことにより、
クライアントにクッキーを設定できます。クッキー文字列を構築するには手続き
@code{construct-cookie-string} (@ref{HTTP cookie handling}参照)
が使えます。
@c COMMON

@c EN
The keyword argument @var{location} may be used to generate
a @code{Location:} header to redirect the client to the specified URI.
You can also specify the @code{Status:} header by the keyword argument
@var{status}.   A typical way to redirect the client is as follows:
@c JP
キーワード引数@var{location}は、@code{Location}ヘッダを作成して
クライアントを別のURIに誘導するのに使えます。また、@code{Status}ヘッダを
指定するために@var{status}キーワード引数が使えます。クライアントを
別URIに転送するよくある方法は次のようなものです。
@c COMMON

@example
(cgi-header :status "302 Moved Temporarily"
            :location target-uri)
@end example

@end defun

@deffn {Parameter} cgi-output-character-encoding :optional encoding
@c EN
The value of this parameter specifies the character encoding scheme (CES)
used for CGI output by @code{cgi-main} defined below.
The default value is Gauche's native encoding.
If the parameter is set other than the native encoding, @code{cgi-main}
converts the output
encoding by @code{gauche.charconv} module
(@xref{Character code conversion}).
@c JP
このパラメータの値は次に説明する@code{cgi-main}が出力するデータの
文字符合化法(CES)を指定します。デフォルトの値はGaucheのネイティブエンコーディング
です。それ以外の値がセットされている場合、@code{cgi-main}は
@code{gauche.charconv}モジュールを用いて出力のエンコーディングの変換を
行います。
(@ref{Character code conversion}参照)。
@c COMMON
@end deffn


@c EN
@subheading Convenience procedures
@c JP
@subheading 便利な手続き
@c COMMON

@defun cgi-main proc :key on-error merge-cookies output-proc part-handlers
@c EN
A convenient wrapper function for CGI script.
This function calls @code{cgi-parse-parameters}, then calls
@var{proc} with the result of @code{cgi-parse-parameters}.
The keyword argument @var{merge-cookies} is passed to
@code{cgi-parse-parameters}.
@c JP
CGIスクリプトのための便利なラッパー手続きです。
この手続きは、まず@code{cgi-parse-parameters}を呼び出してCGIスクリプトに
渡されたパラメータを解析し、続いてその結果を引数として@var{proc}を呼び出します。
キーワード引数@var{merge-cookies}は、与えられればそのまま
@code{cgi-parse-parameters}に渡されます。
@c COMMON

@c EN
@var{proc} has to return a tree of strings
(@xref{Lazy text construction}), including the HTTP header.
@code{cgi-main} outputs the returned tree to the current output port
by @code{write-tree}, then returns zero.
@c JP
手続き@var{proc}はHTTPヘッダを含むドキュメントを
テキストツリー構造(@ref{Lazy text construction}参照)で
返さなければなりません。@code{cgi-main}はそれを@code{write-tree}を使って
現在の出力ポートに書き出し、0を返します。
@c COMMON

@c EN
If an error is signalled in @var{proc}, it is caught and an HTML
page reporting the error is generated.  You can customize the
error page by providing a procedure to the @var{on-error} keyword argument.
The procedure takes an @code{<condition>} object (@xref{Conditions}),
and has to return a tree of string for the error reporting HTML
page, including an HTTP header.
@c JP
もし@var{proc}内でエラーが起こった場合、そのエラーは捕捉されて、エラーを報告する
HTMLページが作成されて出力されます。このエラーページは、@var{on-error}キーワード引数に
手続きを渡すことでカスタマイズできます。@var{on-error}に渡された手続きは
エラー発生時に@code{<condition>}オブジェクト(@ref{Conditions}参照)
を引数として呼ばれ、HTTPヘッダを含むドキュメントをテキストツリー構造で返さねばなりません。
@c COMMON

@c EN
When output the result, @code{cgi-main} refers to
the value of the parameter @code{cgi-output-character-encoding}, 
and converts the character encoding if necessary.
@c JP
@code{cgi-main}は最終的な結果を出力を書き出す時に
パラメータ@code{cgi-output-character-encoding}を参照し、
必要ならば出力の文字エンコーディングを変換します。
@c COMMON

@c EN
The output behavior of @code{cgi-main} can be customized
by a keyword argument @var{output-proc}; if it is given,
the text tree (either the normal return value of @var{proc},
or an error page constructed by ther error handler) is passed
to the procedure given to @var{output-proc}.  The procedure
is responsible to format and output a text to the current
output port, including character conversions, if necessary.
@c JP
@code{cgi-main}の出力のふるまいはキーワード引数@var{output-proc}で
カスタマイズできます。@var{output-proc}が渡された場合、それは
@var{proc}の戻り値、あるいはエラーハンドラが作成したテキストツリー構造を
受け取る手続きでなければなりません。その手続きはテキストツリーを
フォーマットして現在の出力ポートに出力しなければなりません。
必要ならば文字エンコーディングの変換もその手続き内で行います。
@c COMMON

@c EN
The keyword argument @var{part-handlers} are simply passed to
@code{cgi-parse-parameters}, by which you can customize
how the file uploads should be handled.  See the "Handling file
uploads" section below for the details.

If you specify to use temporary file(s) by it, @code{cgi-main}
makes sure to clean up them whenever @var{proc} exits,
even by error.   See @code{cgi-add-temporary-file} below
to utilize this feature for other purpose.
@c JP
キーワード引数@var{part-handlers}は、そのまま@code{cgi-parse-parameters}
に渡されます。この引数によって、ファイルアップロードの際の動作をカスタマイズ
できます。詳しくは下の「ファイルアップロードの処理」の項を参照して下さい。

この引数で、一時ファイルを使うように指定した場合、@code{cgi-main}は
@var{proc}から抜ける際に(エラーでも正常終了でも)一時ファイルを
消去します。この機能を他でも利用するには@code{cgi-add-temporary-file}の項を
参考にして下さい。
@c COMMON

@c EN
Before calling @var{proc}, @code{cgi-main} changes the buffering mode
of the current error port to @code{:line} (See @code{port-buffering}
in @ref{Common port operations} for the details about the buffering mode).
This makes the error output easier for web servers to capture.
@c JP
@var{proc}を呼ぶ前に、@code{cgi-main}はカレントエラーポートの
バッファリングモードを@code{:line}に変更します。
(バッファリングモードの詳細については@ref{Common port operations}の
@code{port-buffering}の項を参照してください)。
これはwebサーバがcgiスクリプトのエラー出力を捕捉しやすくするためです。
@c COMMON

@c EN
The following example shows the parameters given to the CGI program.
@c JP
以下の例はCGIに渡されたパラメータ全てをテーブルにして表示します。
@c COMMON

@example
#!/usr/local/bin/gosh

(use text.html-lite)
(use www.cgi)

(define (main args)
  (cgi-main
    (lambda (params)
      `(,(cgi-header)
        ,(html-doctype)
        ,(html:html
          (html:head (html:title "Example"))
          (html:body
           (html:table
            :border 1
            (html:tr (html:th "Name") (html:th "Value"))
            (map (lambda (p)
                   (html:tr
                    (html:td (html-escape-string (car p)))
                    (html:td (html-escape-string (x->string (cdr p))))))
                 params))))
       ))))
@end example
@end defun


@defun cgi-add-temporary-file filename
@c EN
This is supposed to be called inside @var{proc} of @code{cgi-main}.
It registers @var{filename} as a temporary file, which should be
unlinked when @var{proc} exits.  It is a convenient way to ensure
that your cgi script won't leave garbages even if it throws an error.
It is OK in @var{proc} to unlink or rename @var{filename} after
calling this procedure.
@c JP
この手続きは@code{cgi-main}に渡される@var{proc}中で呼ばれることを
想定しています。
この手続きは、@var{filename}を一時ファイルとして登録し、@var{proc}が
終了する際に消去されるようにします。cgiスクリプトがエラー終了した場合
などでもごみを残さないようにする便利な方法です。
この手続きを呼んだ後で、@var{proc}が@var{filename}を消去したり
名前を変えたりしても構いません。
@c COMMON
@end defun

@deffn {Parameter} cgi-temporary-files
@c EN
Keeps a list of filenames registered by @code{cgi-add-temporary-file}.
@c JP
@code{cgi-add-temporary-file}で登録された一時ファイルを保持するパラメータです。
@c COMMON
@end deffn

@c EN
@subheading Handling file uploads
@c JP
@subheading ファイルアップロードの処理
@c COMMON

@c EN
As explained in @code{cgi-parse-parameters} above, file uploads
are handled transparently by default, taking the file content
as the value of the parameter.   Sometimes you might want to change this
behavior, for the file might be quite big and you don't want 
to keep around a huge chunk of a string in memory.  It is possible to
customize handling of file uploads of @code{cgi-parse-parameters}
and @code{cgi-main} by @var{part-handlers} argument.
(The argument is only effective for the form data submitted by
@code{multipart/form-data} enctype)
@c JP
@code{cgi-parse-parameters}の項で説明したように、ファイルアップロードは
デフォルトでは透過的に扱われます。すなわち、アップロードされた
ファイルの内容がパラメータの値となります。
これは望みの動作ではないかもしれません。例えばアップロードされるファイルが
巨大であることが予想されるなら、それを全てメモリに読み込んで持ち回りたくは
ないかもしれません。@code{cgi-parse-parameters}や@code{cgi-main}の
@var{part-handlers}引数によって、ファイルアップロードの
処理をカスタマイズすることが可能です。
(この引数は、フォームデータが@code{multipart/form-data} enctypeで
送られた場合にのみ意味を持ちます)。
@c COMMON

@c EN
The @var{part-handlers} argument is, if given, a list of lists;
each inner list is a form of 
@code{(@var{name-pattern} @var{action} @var{kv-list} @dots{})}.
Each uploaded file with a matching parameter name with @var{name-pattern} is
handled according to @var{action}.  (Here, a parameter name
is the 'name' attribute given to the @code{input} element in the
submitted form, not the name of the uploaded file).
@c JP
@var{part-handlers}引数が与えられている場合、それはリストのリストで、
内部のリストは@code{(@var{name-pattern} @var{action} @var{kv-list} @dots{})} の形式で
なければなりません。
アップロードされたファイルは、そのパラメータ名が@var{name-pattern}に
マッチした場合に@var{action}で指示されるように処理されます。
(ここで、パラメータ名とはsubmitされたフォームの@code{input}要素に与えられた
'name'属性のことです。アップロードされたファイルの名前ではありません)。
@c COMMON

@c EN
@var{Name-pattern} must be either a list of string (matches one of them),
a regexp, or @code{#t} (matches anything).
@c JP
@var{name-pattern}は文字列のリストか、正規表現か、@code{#t}です。
文字列のリストの場合はそれのいずれかとパラメータ名が等しければマッチと
みなされます。@code{#t}は全てのものにマッチします。
@c COMMON

@c EN
@var{Action} must be either one of the followings:
@table @code
@item #f
Default action, i.e. the content of the uploaded file is turned into
a string and becomes the value of the parameter.
@item ignore
The uploaded content is discarded.
@item file
The uploaded content is saved in a temporary file.  The value of
the parameter is the pathname of the temporary file.

For this action, you can write an entry like
@code{(@var{name-pattern} file @var{prefix})}, to specify the
prefix of the pathname of the temporary file.  For example, if you
specify @code{("image" file "/var/mycgi/incoming/img")}, 
the file uploaded as @code{"image"} parameter will be stored as
something like @file{/var/mycgi/incoming/img49g2Ua}.

The application should move the temporary file to appropriate
location; if you're using @code{cgi-main}, the temporary files
created by this action will be unlinked when @code{cgi-main} exits.

@item file+name
Like @code{file}, but the value of the parameter is a list of
tempoary filename and the filename passed by the client.
It is useful if you want to use client's filename (but do not
blindly assume the client sends a valid pathname; for example,
you shouldn't use it to rename the uploaded file without 
validating it).

@item @var{procedure}
In this case, @var{procedure} is called to handle the uploaded
contents.  It is called with four arguments:
@code{(procedure @var{name} @var{filename} @var{part-info} @var{iport})}.

@var{Name} is the name of the parameter.  @var{Filename} is
the name of the original file (pathname in the client).
@var{Part-info} is a @code{<mime-part>} object that keeps information
about this mime part,  and @var{iport} is where the body can be
read from.
For the details about these arguments, 
see @ref{MIME message handling}; you might be able to
use procedures provided by @code{rfc.mime}, such as @code{mime-retrieve-body},
to construct your own procedure.

If you create a temporary file in @var{procedure}, you can call
@code{cgi-add-temporary-file} to make sure it is removed even if
an error occurs during cgi processing.
@end table
@c JP
@code{action}は次のいずれかの値でなければなりません。
@table @code
@item #f
デフォルトのアクションです。すなわち、アップロードされたファイルの内容が
文字列として読み込まれ、パラメータの値となります。
@item ignore
アップロードされたファイルの内容を無視します。
@item file
アップロードされたファイルの内容は一時ファイルへと格納されます。
パラメータの値は、一時ファイルの名前となります。

このアクションを使う場合は、エントリを
@code{(@var{name-pattern} file @var{prefix})} のように書くことも
でき、その場合は@var{prefix}が一時ファイルのパス名のプリフィクスとして
使われます。例えば@code{("image" file "/var/mycgi/incoming/img")}
のようにしておくと、@code{"image"}パラメータとしてアップロードされた
ファイルが@file{/var/mycgi/incoming/img49g2Ua}のような一時ファイルに
格納されることになります。

アプリケーションは、この一時ファイルを(必要ならば)適切な場所に
移動しなければなりません。@code{cgi-main}を用いている場合は、
一時ファイルは@code{cgi-main}を抜ける際に(まだあれば)unlinkされます。

@item file+name
@code{file}と同様ですが、パラメータの値が一時ファイル名と
クライアントが送ってきたファイル名からなるリストになります。
クライアントが送信したファイル名を利用したい場合に便利です
(ただ、クライアントが常に正しいファイル名を送って来ると仮定しては
いけません。例えば、アップロードされたファイルを
チェック無しにクライアントが送ってきた名前にrenameするというような
ことは避けてください)。


@item @var{procedure}
この場合、アップロードされた内容を処理するために、手続き@var{procedure}が
呼ばれます。手続きは4つの引数を伴って呼ばれます：
@code{(procedure @var{name} @var{filename} @var{part-info} @var{iport})}.

@var{name}はパラメータの名前、@var{filename}はオリジナルファイルの名前
(クライアント側でのパス名)です。@var{part-info}は@code{<mime-part>}オブジェクトで、
このMIMEパートの情報を保持しており、そして@var{iport}は内容を読むための入力ポートです。
これらの引数の詳しい意味については@ref{MIME message handling}を
参照して下さい。独自の@var{procedure}を書く際に、@code{rfc.mime}の
@code{mime-retrieve-body}のような手続きが使えるかもしれません。

@var{procedure}内で一時ファイルを作る場合は、それを
@code{cgi-add-temporary-file}で登録しておけば、cgi処理中に
エラーが起きた場合でも一時ファイルが消去されるようにすることができます。
@end table
@c COMMON

@c EN
If @var{kv-list} is given after @var{action}, it must be a
keyword-value list and further modifies action.  The following
keywords are supported.
@c JP
@var{action}の後ろに@var{kv-list}が与えられた場合、それは
キーワード-値リストでなければなりません。次のキーワードがサポートされています。
@c COMMON

@table @code
@item :prefix
@c EN
Valid only if @var{action} is either @code{file} or @code{file+name}.
Specifies the prefix of the temporary file.  If you give
@code{:prefix "/tmp/foo"}, for example, the file is saved
as something like @file{/tmp/fooxAgjeQ}.
@c JP
@var{action}が@code{file}か@code{file+name}の時のみ有効です。
一時ファイルのプリフィクスを指定します。例えば@code{:prefix "/tmp/foo"}を
与えると、ファイルは@file{/tmp/fooxAgjeQ}のような名前でセーブされます。
@c COMMON
@item :mode
@c EN
Valid only if @var{action} is either @code{file} or @code{file+name}.
Specifies the mode of the temporary file in unix-style integer.  By default 
it is @code{#o600}.
@c JP
@var{action}が@code{file}か@code{file+name}の時のみ有効です。
一時ファイルのモードをunix式の整数で指定します。デフォルトは@code{#o600}です。
@c COMMON
@end table


@c EN
Note that the parameters that are not file uploads are not the subject
of @var{part-handlers}; such parameter values are always turned into a string.
@c JP
ファイルアップロード以外のパラメータは@var{part-handlers}の対象外である
ことに注意して下さい。それらのパラメータの値は常に文字列へと変換されます。
@c COMMON


@c EN
Here's a short example.  Suppose you have a form like this:
@c JP
簡単な例を示します。例えば次のようなフォームがあったとします。
@c COMMON

@example
<form enctype="multipart/form-data" method="POST" action="mycgi.cgi">
<input type="file" name="imagefile" />
<input type="text" name="description" />
<input type="hidden" name="mode" value="normal" />
</form>
@end example

@c EN
If you use @code{cgi-parse-parameters} in @file{mycgi.cgi}
without @var{part-handlers} argument,
you'll get something like the following as the result.
(The actual values depend on how the web client filled the form).
@c JP
@file{mycgi.cgi}内で、@code{cgi-parse-parameters}を
@var{part-handlers}引数なしで使った場合は、
例えば次のようなリストがパラメータパージングの結果として得られるでしょう。
(実際の値は、webクライアントがどのようにフォームを埋めたかに依存します)。
@c COMMON

@example
(("imagefile" #*".....(image file content as a string)....")
 ("description" "my image")
 ("mode" "normal"))
@end example

@c EN
If you pass @code{'(("imagefile" file :prefix "/tmp/mycgi"))}
to @var{part-handlers} 
instead,
you might get something like the following, with the
content of uploaded file saved in @file{/tmp/mycgi7gq0B}
@c JP
ここでもし、@code{'(("imagefile" file :prefix "/tmp/mycgi"))}を
@var{part-handlers}に
渡したなら、替わりに次のような結果が得られるでしょう。
ここで、アップロードされたファイルは@file{/tmp/mycgi7gq0B}にセーブ
されていることになります。
@c COMMON

@example
(("imagefile" "/tmp/mycgi7gq0B")
 ("description" "my image")
 ("mode" "normal"))
@end example

@c EN
If you use a symbol @code{file+name} instead of @code{file} above,
you'll get something like @code{("/tmp/mycgi7gq0B" "logo.jpg")} as
the value of @code{"imagefile"}, where @code{"logo.jpg"} is the
client-side filename.   (Note: the client can send any string
as the name of the file, so @emph{never} assume it is a valid
pathname).
@c JP
上の例でシンボル@code{file}のかわりに@code{file+name}を使えば、
例えば@code{"imagefile"}の値として@code{("/tmp/mycgi7gq0B" "logo.jpg")}
のようなものが得られるでしょう。ここで@code{"logo.jpg"}は
アップロードされたファイルのクライアント側でのパス名です。
(注意：クライアントは任意の文字列をファイル名として送信することが
できるため、その文字列が有効なパス名であることを仮定してはなりません。)

@c COMMON

@c @c EN
@c Now, you pass the following structure to @var{part-handlers}:
@c @c JP
@c 次のような構造を@var{part-handlers}に渡した場合：
@c @c COMMON

@c @example
@c `(("imagefile" 
@c   ,(lambda (name fname info iport)
@c      (receive (outp tmpfile) (sys-mkstemp "/var/log/mycgi/tmp")
@c        (mime-retrieve-body info iport outp)
@c        (close-output-port outp)
@c        (cgi-add-temporary-file tmpfile)
@c        (string-append fname ":" tmpfile))))
@c  )
@c @end example

@c @c EN
@c You'll get something like the following; i.e. the cgi application
@c can see the client-side file name as well as the temporary file name.
@c @c JP
@c 例えば次のようなパーズ結果が得られるでしょう。つまり、
@c cgiアプリケーションは一時ファイル名と同時に
@c クライアント側でのファイル名も参照することができます。
@c @c COMMON

@c @example
@c (("imagefile" "logo.jpg:/var/log/mycgi/tmp820iQj")
@c  ("description" "my image")
@c  ("mode" "normal"))
@c @end example


@c ----------------------------------------------------------------------
@node CGI testing,  , CGI Utility, Library modules - Utilities
@section @code{www.cgi.test} - CGI testing
@c NODE CGIのテスト, @code{www.cgi.test} - CGIのテスト

@deftp {Module} www.cgi.test
@mdindex www.cgi.test
@c EN
This module defines a useful procedures to test CGI script.
The test actually runs the named script, with specified enviornment
variable settings, and retrieve the output.  Your test procedure
then examine whether the output is as expected or not.
@c JP
CGIスクリプトをテストするための便利な手続きを定義しています。
このテストは、指定された環境変数をセットし、実際にスクリプトを
実行し、出力を取得します。ユーザのテスト手続きは、その出力が
期待したものであるかどうかを検査します。
@c COMMON
@end deftp

@defun cgi-test-enviornment-ref envvar-name
@defunx {(setter cgi-test-enviornment-ref)} envvar-name value
@c EN
The module keeps a table of default values of enviornment variables
with which the cgi script will be run.  These procedures allow
the programmer to get/set those default values.

Note that you can override these default values and/or pass additional
environment variables for each call of cgi script.
@c JP
モジュールにより、CGIスクリプトが実行される際の環境変数の
デフォルト値のテーブルが保持されます。プログラマは、これらの
手続きを使ってそのデフォルト値を取得したり設定したりできます。

CGIスクリプトの呼び出し毎に、これらのデフォルト値を上書きしたり、
追加の環境変数を渡したりできます。

@c EN
The following environment variables are set by default.
@c JP
デフォルトでは、下記の環境変数が設定されています。
@c COMMON
@multitable @columnfractions .5 .5
@item Name @tab Value
@item @code{SERVER_SOFTWARE}   
@tab @code{cgitest/1.0}
@item @code{SERVER_NAME}       
@tab @code{localhost}
@item @code{GATEWAY_INTERFACE} 
@tab @code{CGI/1.1}
@item @code{SERVER_PROTOCOL}   
@tab @code{HTTP/1.1}
@item @code{SERVER_PORT}       
@tab @code{80}
@item @code{REQUEST_METHOD}    
@tab @code{GET}
@item @code{REMOTE_HOST}       
@tab @code{remote}
@item @code{REMOTE_ADDR}       
@tab @code{127.0.0.1}
@end multitable
@end defun

@defun call-with-cgi-script script proc :key (environment ()) (parameters #f)
@c EN
Runs a script with given enviornment, and calls @var{proc} with
one argument, an input port which is connected to the pipe of script's
standard output.
@c JP
与えられた環境でスクリプトを実行し、そのスクリプトの標準出力のパイプに
接続された入力ポートを1つ引数に取る @var{proc} を呼び出します。

@c EN
The argument @var{script} should be a list of 
program name and its arguments.  Each element are
passed to @code{x->string} first to stringify.
@c JP
引数 @var{script} は、プログラムの名前とその引数のリストでなければ
なりません。リストの要素はそれぞれ、文字列化されるためにまず
@code{x->string}に渡されます。

@c EN
The script is run under the enviornment given by @var{enviornment}
variable and the default test environment described above.
The @var{environment} argument must be an associative list, in which each
key (@code{car}) is the name of the enviornment variable and
its @code{cdr} is the value.  Both are passed to @code{x->string} first.
If the same environment variable appears in @var{environment} and
the default test enviornment, the one in @var{environment} is used.
@c JP
スクリプトは、変数 @var{environment} で与えられる環境と、上述した
デフォルトのテスト環境の下で実行されます。
@var{environment}は、キー(@code{car})がその環境変数の名前、
@code{cdr}が対応する値であるような連想リストでなければなりません。
両方ともまず @code{x->string} に渡されます。
@var{environment} とデフォルトのテスト環境に同じ環境変数がある場合は、
@var{environment} にあるものが使われます。

@c EN
Additionally, if an associative list is given to the @var{parameters}
argument, a query string is built from it and passed the script.
The actual method to pass the query string depends on the value
of @code{REQUEST_METHOD} environment variable in the setting.
If @code{REQUEST_METHOD} is either @code{GET} or @code{HEAD},
the query string is put in an environment variable @code{QUERY_STRING}.
If it is @code{POST}, the query string is fed to the standard
input of the script.  In the latter case, @code{CONTENT_TYPE}
is set to @code{application/x-www-form-urlencoded} and
@code{CONTENT_LENGTH} are set to the length of @code{QUERY_STRING}
automatically.  If @code{REQUEST_METHOD} is other values,
@var{parameters} is ignored.
You can bypass this mechanism and set up enviornment variable
@code{QUERY_STRING} directly, if you wish.
@c JP
さらに、引数 @var{parameters} に連想リストが渡された場合、そこから
クエリストリングが作られスクリプトに渡されます。
クエリストリングを渡す実際のメソッドは、環境変数 @code{REQUEST_METHOD}の
値に依存します。@code{REQUEST_METHOD} が @code{GET} か @code{HEAD} で
ある場合は、クエリストリングは環境変数 @code{QUERY_STRING} に置かれます。
@code{REQUEST_METHOD} が @code{POST} の場合は、クエリストリングは
スクリプトの標準入力から取得されます。後者の場合、@code{CONTENT_TYPE} には
@code{application/x-www-form-urlencoded}が、
@code{CONTENT_LENGTH} には @code{QUERY_STRING}の長さが、それぞれ自動的に
セットされます。@code{REQUEST_METHOD} がその他の値の場合は、
@var{parameters} は無視されます。
必要であれば、このメカニズムをバイパスして、環境変数 @code{QUERY_STRING} を
直接セットアップすることも可能です。
@c COMMON
@end defun

@defun run-cgi-script->header&body script reader :key environment parameters
@c EN
A convenient wrapper of @code{call-with-cgi-script}.
The @var{script}, @var{environment} and @var{parameters} are passed
to @code{call-with-cgi-script} as they are.
The output of the script is parsed by 
@code{run-cgi-script->header&body}.  
First, the RFC2822 header fields are parsed by 
@code{rfc822-read-headers} (@xref{RFC822 message parsing}).
Then, the @var{reader} is called with an input port which
is piped to the script's output.
@c JP
@code{call-with-cgi-script} の便利なラッパー手続きです。
@var{script}、@var{environment}、@var{parameters}は、
そのまま @code{call-with-cgi-script}に渡されます。
スクリプトの出力は、@code{run-cgi-script->header&body}により
パーズされます。
最初に、RFC2822ヘッダフィールドが @code{rfc822-read-headers}
(@ref{RFC822 message parsing}参照)によりパーズされます。
次に、@var{reader}が、スクリプトの出力にパイプされた入力ポートと
ともに呼ばれます。

@c EN
@code{Run-cgi-script->header&body} returns two values,
the list of headers (as parsed by @code{rfc822-read-headers}),
and the return value of @var{reader}.
@c JP
@code{run-cgi-script->header&body}は、ヘッダのリスト
(@code{rfc822-read-headers}によりパーズされたもの)と
@var{reader}の戻り値の2つの値を返します。
@c COMMON
@end defun

@defun run-cgi-script->sxml script :key environment parameters
@c EN
This is a procedure that uses @code{ssax:xml->sxml}
(@xref{Functional XML parser}) as the @var{reader}
in @code{run-cgi-script->header&body}.  
Useful when you're testing a cgi script that produces
well-formed HTML and/or XML document.
@c JP
この手続きでは、@code{run-cgi-script->header&body}の
@var{reader}として、@code{ssax:xml->sxml}
(@ref{Functional XML parser}参照)を使います。
整形式(Well-formed)のHTMLやXMLドキュメントを生成する
CGIスクリプトをテストする場合に便利です。
@c COMMON
@end defun

@defun run-cgi-script->string script :key environment parameters
@defunx run-cgi-script->string-list script :key environment parameters
@c EN
These procedures use @code{port->string} 
and @code{port->string-list}
(@xref{Input utility functions}) as the @var{reader}
in @code{run-cgi-script->header&body}, respectively.
@c JP
これらの手続きは、@code{run-cgi-script->header&body}の
@var{reader}として、それぞれ @code{port->string}、
@code{port->string-list}を使います。
@c COMMON
@end defun

@c EN
An example:
@c JP
例:
@c COMMON
@example
(run-cgi-script->string-list "bbs.cgi"
                             :environment '((REMOTE_ADDR . "12.34.56.78"))
                             :parameters '((command . "view")
                                           (page . 1234)))
@end example


@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
