@node Library modules - Gauche extensions, Library modules - SRFIs, Library modules - Overview, Top
@chapter Library modules - Gauche extensions
@c NODE ライブラリモジュール - Gauche拡張モジュール

@c ----------------------------------------------------------------------
@menu
* Arrays::                      gauche.array
* Character code conversion::   gauche.charconv
* Generating C code::           gauche.cgen
* Collection framework::        gauche.collection
* Configuration parameters::    gauche.config
* Dictionary framework::        gauche.dictionary
* Low-level file operations::   gauche.fcntl
* Hooks::                       gauche.hook
* Interactive session::         gauche.interactive
* Listener::                    gauche.listener
* User-level logging::          gauche.logger
* Propagating slot access::     gauche.mop.propagate
* Singleton::                   gauche.mop.singleton
* Slot with validator::         gauche.mop.validator
* Networking::                  gauche.net
* Parameters::                  gauche.parameter
* Parsing command-line options::  gauche.parseopt
* Partial continuations::       gauche.partcont
* High Level Process Interface::  gauche.process
* Record types::                gauche.record
* Reloading modules::           gauche.reload
* Simple dispatcher::           gauche.selector
* Sequence framework::          gauche.sequence
* Syslog::                      gauche.syslog
* Terminal control::            gauche.termios
* Unit testing::                gauche.test
* Threads::                     gauche.threads
* Measure timings::             gauche.time
* Uniform vectors::             gauche.uvector
* Comparing version numbers::   gauche.version
* Virtual ports::               gauche.vport
@end menu

@node Arrays, Character code conversion, Library modules - Gauche extensions, Library modules - Gauche extensions
@section @code{gauche.array} - Arrays
@c NODE 配列, @code{gauche.array} - 配列

@deftp {Module} gauche.array
@mdindex gauche.array
@c EN
This module provides multi-dimensional array data type and operations.
The primitive API follows SRFI-25. 
Besides a generic srfi-25 array that can store any Scheme objects,
this module also provides array classes that stores numeric objects
efficiently, backed up by
homogeneous numeric vectors (@xref{Uniform vectors}).
An external representation of arrays, using SRFI-10 mechanism,
is also provided.
@c JP
このモジュールは多次元配列のデータタイプとそれに関する操作を提供します。
プリミティブなAPIはSRFI-25で定義されているものに従います。
任意のSchemeオブジェクトを保持できるSRFI-25の汎用配列の他に、
均一な数値ベクタ(@ref{Uniform vectors}参照)を使って
数値要素を効率良く保持する配列型も提供されます。
また、SRFI-10を使った配列の外部表現も実装されます。
@c COMMON

@c EN
Each element of an @var{N}-dimensional array can be accessed
by @var{N} integer indices,
@code{[ @var{i_0} @var{i_1} @dots{} @var{i_N-1} ]}.
An array has associated @var{shape} that knows lower-bound @var{s_k} and
upper-bound @var{e_k} of index of each dimension, where
@var{s_k} <= @var{e_k}, and the index @var{i_k} must satisfy
@var{s_k} <= @var{i_k} < @var{e_k}.
(Note: it is allowed to have @var{s_k} == @var{e_k}, but such array can't
store any data.  It is also allowed to have zero-dimensional array,
that can store a single data.).
The shape itself is a [ @var{D} x 2 ] array, where @var{D} is the
dimension of the array which the shape represents.
@c JP
@var{N}次元の配列の各エレメントは@code{N}個の整数のインデックス
@code{[ @var{i_0} @var{i_1} @dots{} @var{i_N-1} ]}でアクセスされます。
配列は、各次元のインデックスの下限@var{s_k}および上限@var{e_k}を決める
@var{shape}を持っています。ここで、@var{s_k} <= @var{e_k}であり、
@var{k}次元目のインデックス@var{i_k}は
@var{s_k} <= @var{i_k} < @var{e_k} を満たすものとします。
(@var{s_k} == @var{e_k} であるような配列も作れますが、
その配列にはデータをストアすることはできません。
また、0次元の配列は作れます。それは一つだけデータを保持できます)。
Shapeはそれ自体が [ @var{D} x 2 ] の配列です。
ここで@var{D}はそのshapeが表現する配列の次元数です。
@c COMMON

@c EN
You can pass index(es) to array access primitives in a few ways;
each index can be passed as individual argument,
or can be 'packed' in a vector or one-dimensional array.
In the latter case, such a vector or an array is called an "index object".
Using a vector is efficient in Gauche when you iterate over the elements
by changing the vector elements, for it won't involve memory allocation.
@c JP
配列のプリミティブに対しインデックスを渡すにはいくつか方法があります。
各インデックスをばらばらの引数として渡すこともできますし、
ベクタや1次元の配列にパックして渡すこともできます。
後者においてインデックスがパックされたベクタや配列を「インデックスオブジェクト」
と呼ぶことがあります。Gaucheでは、配列の要素に次々とアクセスするような処理では
ベクタをインデックスオブジェクトとして使うと若干効率が良いでしょう。
@c COMMON

@c EN
Arrays can be compared by the @code{equal?} procedure.
@code{Equal?} returns @code{#t} if two arrays have the same
shape and their corresponding elements are the same
in the sense of @code{equal?}.
@c JP
配列は@code{equal?}手続きで比較することが出来ます。
二つの配列のshapeが等しく、また対応する各要素が@code{equal?}の意味で
等しい場合に二つの配列は@code{equal?}であると見なされます。
@c COMMON

@c EN
Internally, an array consists of a backing storage and a mapping procedure.
A backing storage is an object of aggregate type that can be accessed
by an integer index.  A mapping procedure takes
multi-dimensional indices (or index object) and 
returns a scalar index into the backing storage.
@c JP
内部的には、配列は1次元のインデックスでアクセスされるバッキングストレージと、
多次元のインデックスをバッキングストレージへのインデックスにマップする手続きとから
構成されています。
@c COMMON
@end deftp

@deftp {Class} <array-base>
@clindex array-base
@c EN
An abstract base class of array types, that implements generic operations
on the array.   To create an array instance,
you should use one of the following concrete array classes.
@c JP
配列に関する汎用操作を実装している、抽象ベースクラスです。
実際に配列のインスタンスを作るには、以下のいずれかの具体クラスを使って下さい。
@c COMMON
@end deftp

@deftp {Class} <array>
@deftpx {Class} <u8array>
@deftpx {Class} <s8array>
@deftpx {Class} <u16array>
@deftpx {Class} <s16array>
@deftpx {Class} <u32array>
@deftpx {Class} <s32array>
@deftpx {Class} <u64array>
@deftpx {Class} <s64array>
@deftpx {Class} <f16array>
@deftpx {Class} <f32array>
@deftpx {Class} <f64array>
@clindex array
@clindex u8array
@clindex s8array
@clindex u16array
@clindex s16array
@clindex u32array
@clindex s32array
@clindex u64array
@clindex s64array
@clindex f16array
@clindex f32array
@clindex f64array
@c EN
Concrete array classes.  The @code{<array>} class implements srfi-25
compatible array, i.e. an array that can store any Scheme objects.
The @code{<u8array>} class through @code{<f64array>} classes uses
a @code{<u8vector>} through @code{<f64vector>} as a backing storage,
and can only store a limited range of integers or inexact real numbers,
but they are space efficient.
@c JP
具体配列クラスです。@code{<array>}クラスはsrfi-25互換の配列、
すなわち、任意のSchemeオブジェクトを格納できる配列を実装します。
@code{<u8array>}から@code{<f64array>}までは、
それぞれ@code{<u8vector>}から@code{<f64vector>}をバッキングストレージとして
用いる配列を実装し、制限された範囲の整数もしくは不正確な実数のみを
効率良く格納することができます。
@c COMMON
@end deftp


@deftp {Reader syntax} @code{#,(<array> @var{shape} @var{obj} @dots{})}
@c EN
An array is written out in this format.  (Substitute @code{<array>} for
@code{<u8array>} if the array is @code{<u8array>}, etc.)
@var{shape} is a list
of even number of integers, and each 2@var{n}-th integer
and 2@var{n}+1-th integer specifies the
inclusive lower-bound and exclusive upper-bound of @var{n}-th dimension,
respectively.  The following @var{obj} @dots{} are the values in the array
listed in row-major order.
@c JP
配列はこの形式で書き出されます。
(配列が例えば@code{<u8array>}であるなら、@code{<array>}の部分は@code{<u8array>}
となります。)
@var{shape}は偶数個の整数のリストで、
2@var{n}番目の整数が@var{n}次元目のインデックスの下限を、2@var{n}+1番目の
整数が@var{n}次元目のインデックスの上限(+1)を表します。
その後に、配列の要素がrow-majorの順で書き出されます。
@c COMMON

@c EN
When read back, this syntax is read as an array with the same shape
and content, so it is @code{equal?} to the original array.
@c JP
この構文が読み込まれると、もとの配列と@code{equal?}である配列が作成されます。
@c COMMON

@example
@c EN
; an array such that:
@c JP
; 次のような配列：
@c COMMON
;   8 3 4
;   1 5 9
;   6 7 2
#,(<array> (0 3 0 3) 8 3 4 1 5 9 6 7 2)

@c EN
; a 4x4 identity matrix
@c JP
; 4x4の単位行列
@c COMMON
#,(<array> (0 4 0 4) 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1)
@end example
@end deftp

@defun array? obj
[SRFI-25]
@c EN
Returns @code{#t} if @var{obj} is an array, @var{#f} otherwise.
It is equivalent to @code{(is-a? obj <array-base>)}.
@c JP
@var{obj}が配列であれば@var{#t}が、そうでなければ@var{#f}が返されます。
@code{(is-a? obj <array-base>)}と等価です。
@c COMMON
@end defun

@defun make-array shape :optional init
[SRFI-25]
@c EN
Creates an array of shape @var{shape}.
@var{Shape} must be a [ @var{D} x 2 ] array, and for each @var{k}
(0 <= @var{k} < @var{D}), the [ @var{k} 0 ] element must be less than or
equal to the [ @var{k} 1] element.
If @var{init} is given, all the elements are initialized by it.
Otherwise, the initial value of the elements are undefined.
@c JP
Shapeが@var{shape}である配列を作成します。
@var{Shape}は [ @var{D} x 2 ] の配列で、
0 <= @var{k} < @var{D} なる各@var{k}に対して要素 [ @var{k} 0 ] は
要素[ @var{k} 1 ]以下でなければなりません。
@var{init}が与えられた場合は、配列の各要素が@var{init}で初期化されます。
@var{init}が与えられなかった場合の配列の要素の初期値は不定です。
@c COMMON

@example
(make-array (shape 0 2 0 2 0 2) 5)
 @result{} #,(<array> (0 2 0 2 0 2) 5 5 5 5 5 5 5 5)
@end example
@end defun

@defun make-u8array shape :optional init
@defunx make-s8array shape :optional init
@findex make-u16array
@findex make-s16array
@findex make-u32array
@findex make-s32array
@findex make-u64array
@findex make-s64array
@dots{}
@end defun
@defun make-f32array shape :optional init
@defunx make-f64array shape :optional init
@c EN
Like @code{make-array}, but creates and returns an uniform numeric array.
@c JP
@code{make-array}と似ていますが、均一な数値配列を返します。
@c COMMON
@end defun

@defun shape bound @dots{}
[SRFI-25]
@c EN
Takes even number of exact integer arguments, and returns
a two-dimensional array that is suitable for representing the shape
of an array.
@c JP
偶数個の正確な整数を引数に取り、配列のshapeとして使える2次元の配列を返します。
@c COMMON

@example
(shape 0 2 1 3 3 5)
 @result{} #,(<array> (0 3 0 2) 0 2 1 3 3 5)

(shape)
 @result{} #,(<array> (0 0 0 2))
@end example
@end defun

@defun array shape init @dots{}
[SRFI-25]
@c EN
Creates an array of shape @var{shape}, initializing its elements by
@var{init} @dots{}.
@c JP
Shapeが@var{shape}であるような配列を作成し、
その要素を@var{init} @dots{}で初期化します。
@c COMMON

@example
(array (shape 0 2 1 3) 'a 'b 'c 'd)
 @result{} #,(<array> (0 2 1 3) a b c d)
@end example
@end defun

@defun array-rank array
[SRFI-25]
@c EN
Returns the number of dimensions of an array @var{array}.
@c JP
配列@var{array}の次元数を返します。
@c COMMON

@example
(array-rank (make-array (shape 0 2 0 2 0 2))) @result{} 3
(array-rank (make-array (shape))) @result{} 0
@end example
@end defun

@defun array-shape array
@c EN
Returns a shape array of @var{array}.
@c JP
配列@var{array}のshapeを表す配列を返します。
@c COMMON
@end defun

@defun array-start array dim
@defunx array-end array dim
@defunx array-length array dim
[SRFI-25+]
@c EN
@code{Array-start} returns the inclusive lower bound of index of
@var{dim}-th dimension of an array @var{array}.
@code{Array-end} returns the exclusive upper bound.
And @code{array-length} returns the difference between two.
@code{Array-start} and @code{array-end} are defined in SRFI-25.
@c JP
@code{array-start}は配列@var{array}の@var{dim}番目の次元の
インデックスの下限を返します。
@code{array-end}は上限+1を、そして@code{array-length}は両者の差を返します。
@code{array-start}と@code{array-end}はSRFI-25で定義されています。
@c COMMON

@example
(define a (make-array (shape 1 5 0 2)))

(array-start a 0)  @result{} 1
(array-end a 0)    @result{} 5
(array-length a 0) @result{} 4
(array-start a 1)  @result{} 0
(array-end a 1)    @result{} 2
(array-length a 1) @result{} 2
@end example
@end defun

@defun array-size array
@c EN
Returns the total number of elements in the array @var{array}.
@c JP
配列@var{array}の全要素数を返します。
@c COMMON

@example
(array-size (make-array (shape 5 9 1 3))) @result{} 8
(array-size (make-array (shape))) @result{} 1
(array-size (make-array (shape 0 0 0 2))) @result{} 0
@end example
@end defun

@defun array-ref array k @dots{}
@defunx array-ref array index
[SRFI-25]
@c EN
Gets the element of array @code{array}.  In the first form,
the element is specified by indices @var{k} @dots{}.
In the second form, the element is specified by an index object
@var{index}, which must be a vector or an one-dimensional array.
@c JP
配列@var{array}の要素を取り出します。最初の形式では、
要素は整数のインデックス@var{k} @dots{}で指定されます。
2番目の形式では、要素はベクタまたは1次元配列のインデックスオブジェクト@var{index}
で指定されます。
@c COMMON
@end defun

@defun array-set! array k @dots{} value
@defunx array-set! array index value
[SRFI-25]
@c EN
Sets the element of array @var{array} to @var{value}.  In the first form,
the element is specified by indices @var{k} @dots{}.
In the second form, the element is specified by an index object
@var{index}, which must be a vector or an one-dimensional array.
@c JP
配列@var{array}の要素に@var{value}をセットします。
最初の形式では、
要素は整数のインデックス@var{k} @dots{}で指定されます。
2番目の形式では、要素はベクタまたは1次元配列のインデックスオブジェクト@var{index}
で指定されます。
@c COMMON
@end defun

@defun share-array array shape proc
[SRFI-25]
@c EN
Creates and returns a new array of shape @var{shape}, that shares
the backing storage with the given array @var{array}.
The procedure @var{proc} maps the indices of the new array to
the indices to the original array, i.e. @var{proc} must be a @var{n}-ary
procedure that returns @var{m} values, where @var{n} is the dimension
of the new array and @var{m} is the one of the original array.
Furthermore, @var{proc} must be an affine function; each mapping
has to be a linear combination of input arguments plus optional constant.
(@code{Share-array} optimizes the mapping function based on the affinity
assumption, so @var{proc} won't be called every time the new array
is accessed).
@c JP
Shapeが@var{shape}であり、与えられた配列@var{array}とバッキングストレージを
共有する新しい配列を作成して返します。
@var{proc}は、新しい配列へのインデックスを古い配列へのインデックスへ
マップする手続きです。新しい配列の次元数を@var{n}、古い配列の次元数を@var{m}と
した時、@var{proc}は@var{n}個の引数を取り@var{m}個の値を返す手続きでなければ
なりません。さらに、各マッピングはaffineマッピング、すなわち、
出力は入力の線形合成(プラス定数)でなければなりません。
(@code{share-array}は@var{proc}がaffineマッピングであるという事実に基づいた
最適化を行います。新しい配列にアクセスする度に@var{proc}が呼ばれるというわけでは
ありません)。
@c COMMON
@end defun

@defun array-for-each-index array proc :optional index
@c EN
Calls @var{proc} with every index of @var{array}.
If no @var{index} argument is provided, @var{proc} is called
as @code{(@var{proc} @var{i} @var{j} @var{k} @dots{})}, in which
(@var{i}, @var{j},@var{k},@dots{}) walks over the index.
@c JP
@var{array}の各インデックスに対して@var{proc}を呼びます。
@var{index}引数が省略された場合は、
@var{proc}はインデックス (@var{i}, @var{j},@var{k},@dots{}) に対して
@code{(@var{proc} @var{i} @var{j} @var{k} @dots{})} のように呼ばれます。
@c COMMON

@example
gosh> (define a (array (shape 0 2 0 2) 1 2 3 4))
a
gosh> a
#,(<array> (0 2 0 2) 1 2 3 4)
gosh> (array-for-each-index a (^(i j) (print i","j))) 
0,0
0,1
1,0
1,1
@end example

@c EN
This form of passing indexes is simple but not very efficient, though.
For better performance,
you can pass an index object to an optional
argument @var{index},
which is modified for each index and passed to @var{proc}.
The index object must be mutable, and
either a vector, an one-dimensional array, an s8vector, an s16vector
or an s32vector.  The length of the index object must match the
rank of the array.  Using index object is efficient since the loop
won't allocate.  Don't forget that the index object is destructively
modified within the loop.
@c JP
この形式の呼び出しは簡単なのですが、あまり効率が良くありません。
インデックスオブジェクトを省略可能引数@var{index}に渡すことで、
より良い性能を引き出すことができます。
インデックスオブジェクトはループの度に、各インデックスを表す値に書き換えられます。
インデックスオブジェクトに使えるのは、変更可能な、ベクタ・1次元の配列・
s8vector・s16vectorあるいはs32vectorで、その長さは配列@var{array}の
ランクと一致していなければなりません。インデックスオブジェクトを使うと、
ループ中に一切アロケーションが行われないため速度的に有利です。
ただし、ループの度にインデックスオブジェクトの内容が書き換えられることに
注意する必要があります。
@c COMMON

@example
gosh> (array-for-each-index a (cut format #t "~s\n" <>) (vector 0 0))
#(0 0)
#(0 1)
#(1 0)
#(1 1)

gosh> (array-for-each-index a (cut format #t "~s\n" <>) (s8vector 0 0))
#s8(0 0)
#s8(0 1)
#s8(1 0)
#s8(1 1)
@end example

@c EN
The procedure returns an unspecified value.
@c JP
戻り値は未定義です。
@c COMMON
@end defun

@defun shape-for-each shape proc :optional index
@c EN
Calls @var{proc} with all possible indexes represented by the shape
@var{shape}.
The optional @var{index} argument works the same
way as @code{array-for-each-index}.  Returns an unspecified value.
@c JP
シェイプ@var{shape}が表現する全ての可能なインデックスに対して@var{proc}を呼びます。
省略可能な@var{index}引数の動作は@code{array-for-each-index}と同様です。
戻り値は未定義です。
@c COMMON

@example
gosh> (shape-for-each (shape 0 2 0 2) (^(i j) (print i","j)))
0,0
0,1
1,0
1,1
@end example
@end defun

@defun tabulate-array shape proc :optional index
@c EN
Calls @var{proc} over each index represented by the shape @var{shape},
and creates an array from the result of @var{proc}.  The optional
index object can be used in the same way as @code{array-for-each-index}.
The following example creates an identity matrix of the given shape:
@c JP
@var{shape}が表現する各インデックスについて@var{proc}を呼び出し、
その戻り値から配列を構築して返します。省略可能なインデックスオブジェクトの用途は
@code{array-for-each-index}と同じです。
次の例は与えられたシェイプに対する単位行列を生成します:
@c COMMON

@example
(tabulate-array (shape 0 3 0 3) (^(i j) (if (= i j) 1 0)))
  @result{} #,(<array> (0 3 0 3) 1 0 0 0 1 0 0 0 1)
@end example
@end defun

@defun array-retabulate! array proc :optional index
@defunx array-retabulate! array shape proc :optional index
@c EN
Calls @var{proc} over each index of the given @var{array}, and
modifies the array's element by the returned value of @var{proc}.
The optional index object can be used in
the same way as @code{array-for-each-index}.
The second form takes a shape; it must match
the @var{array}'s shape.  It is redundant, but may allow some
optimization in future in case @var{shape} is a literal.
Returns an unspecified value.
@c JP
配列@var{array}の各インデックスに対して@var{proc}を呼び、その戻り値で
@var{array}の要素を置き換えます。
省略可能なインデックスオブジェクトの用途は
@code{array-for-each-index}と同じです。
二番目の呼び出し形式は第二引数にシェイプを取ります。
それは@var{array}のシェイプと一致しなければなりません。
意味的には冗長ですが、@var{shape}がリテラルである場合、
何らかの最適化がなされる可能性があります。
戻り値は未定義です。
@c COMMON
@end defun

@defun array-map proc array0 array1 @dots{}
@defunx array-map shape proc array0 array1 @dots{}
@c EN
The arguments @var{array0}, @var{array1}, @dots{} must be arrays
with the same shape.  For each set of corresponding elements of
the input arrays, @var{proc} is called, and a new array of the
same shape is created by the returned values.
The second form takes a shape argument, which must match the
shape of input array(s).  It is redundant, but may allow some
optimization in future in case @var{shape} is a literal.
@c JP
引数@var{array0}, @var{array1}, @dots{}は同じシェイプを持つ
配列でなければなりません。各入力配列の対応する要素について、
それらを引数として@var{proc}が呼ばれ、その戻り値から
新たな配列が作られて返されます。
二番目の呼び出し形式は第二引数にシェイプを取ります。
それは入力配列のシェイプと一致しなければなりません。
意味的には冗長ですが、@var{shape}がリテラルである場合、
何らかの最適化がなされる可能性があります。
@c COMMON

@example
(array-map - (array (shape 0 2 0 2) 1 2 3 4))
  @result{} #,(<array> (0 2 0 2) -1 -2 -3 -4)
@end example
@end defun

@defun array-map! array proc array0 array1 @dots{}
@defunx array-map! array shape proc array0 array1 @dots{}
@c EN
Like @code{array-map}, but the results of @var{proc} are stored by the
given @var{array}, whose shape must match the shape of input array(s).
Returns unspecified value.
@c JP
@code{array-map}と似ていますが、@var{proc}の結果は
与えられた@var{array}に格納されます。@var{array}のシェイプは
入力配列のシェイプと同じでなければなりません。
戻り値は未定義です。
@c COMMON
@end defun

@defun array->vector array
@defunx array->list array
@c EN
Returns a fresh vector or a fresh list of all elements in @var{array}.
@c JP
@var{array}の全要素を並べたベクタもしくはリストを作って返します。
@c COMMON

@example
(array->vector
 (tabulate-array (shape 1 3 1 4)
                 (^(i j) (+ (* 10 i) j))))
 @result{} #(11 12 13 21 22 23)
@end example
@end defun

@defun array-concatenate a b :optional dimension
@c EN
Concatenates arrays at the specified dimension.  The sizes of the 
specified dimension of two arrays must match, although the shapes
can be different.   Arrays can be of any ranks, but two ranks must
match.
@c JP
指定の次元で配列を結合します。指定の次元の大きさは一致していなければなりません。
それ以外のシェイプは異なっていても構いません。配列のランクはいくつであっても
構いませんが、両配列のランクは同じでなければなりません。
@c COMMON

@example
;;  [a b]              [a b]
;;  [c d] (+)       => [c d]
;;            [e f]    [e f]
(array-concatenate
 (array (shape 0 2 0 2) 'a 'b 'c 'd)
 (array (shape 0 1 0 2) 'e 'f))
 @result{} #,(<array> (0 3 0 2) a b c d e f)

;;  [a b]     [e]    [a b e]
;;  [c d] (+) [f] => [c d f]
(array-concatenate
 (array (shape 0 2 0 2) 'a 'b 'c 'd)
 (array (shape 0 2 0 1) 'e 'f)
 1)
 @result{} #,(<array> (0 2 0 3) a b e c d f)

@c EN
;; The index range can differ, as far as the sizes match
@c JP
;; 結合次元の大きさが同じであればインデックスの範囲は異なっていてもよい
@c COMMON
(array-concatenate
 (array (shape 0 2 0 2) 'a 'b 'c 'd) 
 (array (shape 1 3 0 1) 'e 'f) 1)
 @result{} #,(<array> (0 2 0 3) a b e c d f)
@end example
@end defun

@defun array-transpose array :optional dim1 dim2
@c EN
The given array must have a rank greater than or equal to 2.
Transpose the array's @var{dim1}-th dimension and
@var{dim2}-th dimension.  The default is 0 and 1.
@c JP
@var{array}はランク2以上の配列でなければなりません。
配列の@var{dim1}番目の次元と@var{dim2}番目の次元を転置します。
デフォルトは0番目と1番目です。
@c COMMON
@end defun

@defun array-rotate-90 array :optional dim1 dim2
@c EN
The given array must have a rank greater than or equal to 2.
We regard the array as a matrix with @var{dim1}-th dimension
as rows and @var{dim2}-th dimension as columns, and returns
a fresh array whose content is filled by @emph{rotating}
@var{array} 90 degree clockwise.   The defaults of 
@var{dim1} and @var{dim2} are 0 and 1, respectively.
@c JP
@var{array}はランク2以上の配列でなければなりません。
配列の@var{dim1}番目の次元と@var{dim2}番目の次元をそれぞれ行と列とみなした行列を
考え、その行列を時計まわりに90度回転した新たな配列を作って返します。
@c COMMON

@example
;; [1 2 3]      [4 1]
;; [4 5 6]  =>  [5 2]
;;              [6 3]
(array-rotate-90 (array (shape 0 2 0 3) 1 2 3 4 5 6))
 @result{} #,(<array> (0 3 0 2) 4 1 5 2 6 3)
@end example

@c EN
If @var{array} has a rank greater than 2, the array is
treated as a matrix of subarrays.
@c JP
@var{array}のランクが2より大きい場合は、@var{array}は「部分配列の行列」
と考えられます。
@c COMMON
@end defun

@defun array-flip array :optional dimension
@defunx array-flip! array :optional dimension
@c EN
Flips the content of the array across the @var{dimension}-th dimension.
(default is 0).   @code{array-flip!} modifies the content of @var{array}
and return it.  @code{array-flip} doesn't modify @var{array} but creates
a fresh array with the flipped content and returns it.
@c JP
配列の内容を、指定番目の次元 (デフォルトは0) で裏返しにします。
@code{array-flip!}は@var{array}を直接変更してそれを返します。
@code{array-flip}は@var{array}には触らず、裏返した内容で新たな配列を作って返します。
@c COMMON

@example
;; [1 2 3]  =>  [4 5 6]
;; [4 5 6]      [1 2 3]
(array-flip (array (shape 0 2 0 3) 1 2 3 4 5 6))
 @result{} #,(<array> (0 2 0 3) 4 5 6 1 2 3)

;; [1 2 3]  =>  [3 2 1]
;; [4 5 6]      [6 5 4]
(array-flip (array (shape 0 2 0 3) 1 2 3 4 5 6) 1)
 @result{} #,(<array> (0 2 0 3) 3 2 1 6 5 4)
@end example
@end defun

@defun identity-array dimension :optional class
@c EN
Returns a fresh identity array of rank 2, with the given dimension.
You can pass one of array classes to @var{class} to make the result
the instance of the class; the default class is @code{<array>}.
@c JP
ランク2で行列ともに@var{dimension}である単位行列を作って返します。
配列のクラスを@var{class}に渡せば、結果はそのインスタンスになります。
デフォルトは@code{<array>}クラスです。
@c COMMON

@example
(identity-array 3)
 @result{} #,(<array> (0 3 0 3) 1 0 0 0 1 0 0 0 1)

(identity-array 3 <f32array>)
 @result{} #,(<f32array> (0 3 0 3) 1.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 1.0)
@end example
@end defun

@defun array-inverse array
@c EN
Regards the @var{array} as a matrix, and returns its inverse matrix;
@var{array} must be 2-dimensional, and must have square shape.  If
@var{array} doesn't satisfy these conditions, an error is thrown.

If @var{array} isn't a regular matrix, @code{#f} is returned.
@c JP
@var{array}を行列とみなし、その逆行列を返します。
@var{array}は2次元で、正方行列となるシェイプを持っていなければなりません。
そうでない場合はエラーが投げられます。

@var{array}が正則行列でない場合は@code{#f}が返されます。
@c COMMON
@end defun

@defun determinant array
@defunx determinant! array
@c EN
Regards the @var{array} as a matrix, and calculates its determinant;
@var{array} must be 2-dimensional, and must have square shape.  If
@var{array} doesn't satisfy these conditions, an error is thrown.

@code{determinant!} destructively modifies the given array during
calculation.  It is faster than @code{determinant}, which copies
@var{array} before calculation to preserve it.
@c JP
@var{array}を行列とみなし、その行列式を計算します。
@var{array}は2次元で、正方行列となるシェイプを持っていなければなりません。
そうでない場合はエラーが投げられます。

また、@code{determinant!}は計算過程で@var{array}の内容を破壊します。
@code{determinant}は計算の前に@var{array}をコピーするオーバヘッドが
ありますが、@var{array}は変更されません。
@c COMMON
@end defun

@defun array-mul a b
@c EN
Arrays @var{a} and @var{b} must be rank 2.   Regarding them
as matrices, multiply them together.  The number of rows of @var{a}
and the number of columns of @var{b} must match.
@c JP
配列@var{a}と@var{b}はともに2次元でなければなりません。
それらを行列とみなして乗算を行います。@var{a}の行数と@var{b}の列数は
一致していなければなりません。
@c COMMON

@example
;;           [6 5]
;; [1 2 3] x [4 3] => [20 14]
;; [4 5 6]   [2 1]    [56 41]

(array-mul (array (shape 0 2 0 3) 1 2 3 4 5 6)
           (array (shape 0 3 0 2) 6 5 4 3 2 1))
 @result{} #,(<array> (0 2 0 2) 20 14 56 41)
@end example
@end defun

@defun array-expt array pow
@c EN
Raises @var{array} to the power of @var{pow}; @var{array} must be
a square matrix, and @var{pow} must be a nonnegative exact integer.
@c JP
@var{array}の@var{pow}乗を返します。@var{array}は正方行列、
@var{pow}は非負の正確な整数でなければなりません。
@c COMMON
@end defun

@defun array-div-left a b
@defunx array-div-right a b
@end defun

@defun array-add-elements array array-or-scalar @dots{}
@defunx array-add-elements! array array-or-scalar @dots{}
@end defun

@defun array-sub-elements array array-or-scalar @dots{}
@defunx array-sub-elements! array array-or-scalar @dots{}
@defunx array-mul-elements array array-or-scalar @dots{}
@defunx array-mul-elements! array array-or-scalar @dots{}
@defunx array-div-elements array array-or-scalar @dots{}
@defunx array-div-elements! array array-or-scalar @dots{}
@end defun

@c ----------------------------------------------------------------------
@node Character code conversion, Generating C code, Arrays, Library modules - Gauche extensions
@section @code{gauche.charconv} - Character Code Conversion
@c NODE 文字コード変換, @code{gauche.charconv} - 文字コード変換

@deftp {Module} gauche.charconv
@mdindex gauche.charconv
@c EN
This module defines a set of functions that converts character encoding
schemes (CES) of the given data stream.

This module is implicitly loaded when @code{:encoding} keyword argument
is given to the file stream creating functions
(such as @code{open-input-file} and @code{call-with-output-file}).
@c JP
与えられたデータストリームの文字エンコーディングを変換するための手続き群を提供する
モジュールです。

このモジュールはまた、@code{open-input-file}や
@code{call-with-output-file}等のファイルストリームを作成する手続きに
@code{:encoding}キーワード引数が与えられた場合に暗黙にロードされます。
@c COMMON

@c EN
As of release 0.5.6, Gauche natively supports conversions between
typical Japanese character encodings: ISO2022JP, ISO2022JP-3,
EUC-JP (EUC-JISX0213), Shift_JISX0213, UTF-8 (Unicode 3.2).
Conversions between other encodings are handled by @code{iconv(3)}.
@xref{Supported character encoding schemes}, for details.
@c JP
リリース0.5.6より、Gaucheは日本語の主要エンコーディング
(ISO2022JP, ISO2022JP-3, EUC-JP (EUC-JISX0213), Shift_JIS (Shift_JISX0213), 
UTF-8 (Unicode 3.2))間の変換を自前で持つようになりました。
上記以外のコードとの変換は@code{iconv(3)}を利用します。
サポートされるコーディングシステムに関する詳細は
@ref{Supported character encoding schemes}を参照して下さい。
@c COMMON
@end deftp

@menu
* Supported character encoding schemes::  
* Autodetecting the encoding scheme::  
* Conversion ports::            
@end menu

@node Supported character encoding schemes, Autodetecting the encoding scheme, Character code conversion, Character code conversion
@subsection Supported character encoding schemes
@c NODE サポートされる文字エンコーディング

@c EN
A CES is represented by its name as a string or a symbol.
Case is ignored.  There may be several aliases defined for a single encoding.
@c JP
CESの名前は文字列またはシンボルで指定します。大文字小文字の違いは無視されます。
同じCESにいくつかの別名がついていることがあります。
@c COMMON

@c EN
A CES name "none" is special.  When Gauche's native encoding is @code{none},
Gauche just treats a string as a byte sequence, and it's up to the application
to interpret the sequence in an appropriate encoding.  So, conversion
to and from CES "none" does nothing.
@c JP
CES名 "none" は特殊です。Gaucheのネイティブエンコーディングが@code{none}の
場合、Gaucheは文字列を単なるバイト列として扱い、そのエンコーディングの解釈は
アプリケーションに任されます。したがって、CES "none" への変換、および "none"
からの変換は「何もしない」変換として扱われます。
@c COMMON

@c EN
You can check whether the specific conversion is supported on
your system or not, by the following function.
@c JP
特定の変換がシステムでサポートされているかどうかは次の手続きで調べることができます。
@c COMMON

@defun ces-conversion-supported? from-ces to-ces
@c EN
Returns @code{#t} if conversion from the character encoding scheme
(CES) @var{from-ces} to @var{to-ces} is supported in this system.

Note that this procedure may return true even if system only supports
partial conversion between @var{from-ces} and @var{to-ces}.
In such case, actual conversion might lose information by coercing
characters in @var{from-ces} which are not supported in @var{to-ces}.
(For example, conversion from Unicode to EUC-JP is "supported",
although Unicode has characters that are not in EUC-JP).

Also note that this procedure always returns @code{#t} 
if @var{from-ces} and/or @var{to-ces} is "none",
for conversion to/from CES "none" always succeeds (in fact, it does nothing).

@example
;; see if you can convert the internal encoding to EUC-JP
(ces-conversion-supported? (gauche-character-encoding) "euc-jp")
@end example
@c JP
CES @var{from-ces}から@var{to-ces}への変換がサポートされていれば@code{#t}を、
そうでなければ@code{#f}を返します。

システムが@var{from-ces}から@var{to-ces}への変換を部分的にしか
サポートしていない場合でもこの手続きは@code{#t}を返すことに注意して下さい。
そのような場合、実際の変換作業は@var{from-ces}にあって@var{to-ces}にない
コードを置換文字に置き換える等で情報を失うかもしれません
(例えば、UnicodeからEUC-JPへの変換はサポートされていますが、
UnicodeにはEUC-JPにない文字も含まれています)。

@var{from-ces}か@var{to-ces}が "none" ならばこの手続きは常に@code{#t}を
返します。なぜならそのような変換は常に成功するからです(何も変換しないわけですが)。

@example
;; 内部エンコーディングからEUC-JPに変換できるか?
(ces-conversion-supported? (gauche-character-encoding) "euc-jp")
@end example
@c COMMON
@end defun

@c EN
Also there are two useful procedures to deal with CES names.
@c JP
また、CESを扱う二つの便利な手続きが用意されています。
@c COMMON

@defun ces-equivalent? ces-a ces-b :optional unknown-value
@c EN
Returns true if two CESes @var{ces-a} and @var{ces-b} are equivalent
to the knowledge of the system.  Returns false if they are not.
If the system doesn't know about equivalency, @var{unknown-value}
is returned, whose default is @code{#f}.

CES "none" works like a wild card; it is "equivalent" to any CES.
(Thus, @code{ces-equivalent?} is not transitive.  
The intended use of @code{ces-equivalent?}
is to compare two given CES names and see if conversion is required or not).
@c JP
CES @var{ces-a}と@var{ces-b}がシステムの知る限りで等価だった場合に
@code{#t}を、等価でない場合に@code{#f}を返します。
システムがその等価性を判断出来ない場合は@var{unknown-value}に与えられた
値を返します。そのデフォルトは@code{#f}です。

CES名 "none" はワイルドカードのように動作します。それはどんなCESとも
等価と見倣されます。(従って、@code{ces-equivalent?} は遷移的ではありません。
この手続きは、二つのCESを知った時に相互の変換が
必要かどうかを判断するためのものです)。
@c COMMON

@example
(ces-equivalent? 'eucjp "EUC-JP")            @result{} #t
(ces-equivalent? 'shift_jis "EUC-JP")        @result{} #f
(ces-equivalent? "NoSuchEncoding" 'utf-8 '?) @result{} ?
@end example
@end defun

@defun ces-upper-compatible? ces-a ces-b :optional unknown-value
@c EN
Returns true if a string encoded in CES @var{ces-b} can also
be regarded as a string encoded in @var{ces-a} without conversion,
to the knowledge of the system.  
Returns false if not.  Returns @var{unknown-value}
if the system can't determine which is the case.

Like @code{ces-equivalent?}, CES "none" works like a wildcard.
It is upper-compatible to any CES, and any CES is upper-compatible to
"none".
@c JP
CES @var{ces-b}でエンコードされた文字列が、システムの知る限りで
変換無しに@var{ces-a}でエンコードされたものと見倣せる場合に@code{#t}を
返します。見倣せない場合は@var{#f}を返します。
システムが判断できない場合は@var{unknown-value}に与えられた
値を返します。そのデフォルトは@code{#f}です。

@code{ces-equivalent?}と同様に、CES名 "none" はワイルドカードとして
働きます。@var{ces-a} か @var{ces-b} が "none" であれば、
常に@code{#t}が返されます。
@c COMMON

@example
(ces-upper-compatible? "eucjp" "ASCII")             @result{} #t
(ces-upper-compatible? "eucjp" "utf-8")             @result{} #f
(ces-upper-compatible? "utf-8" "NoSuchEncoding" '?) @result{} ?
@end example
@end defun

@c EN
Conversion between common japanese CESes (EUC_JP, Shift JIS, UTF-8
and ISO2022-JP) of the character set JIS X 0201 and JIS X 0213
is handled by Gauche's built-in algorithm (see below for details).
When other CES name is given, Gauche uses
@code{iconv(3)} if it is linked.
@c JP
日本語の文字セットJIS X 0201及びJIS X 0213のエンコーディング
(EUC_JP、Shift JIS、UTF-8及びISO2022-JP) 間の変換に関しては、
Gaucheが内部に変換アルゴリズムを持っています (詳細は下の注記を参照)。
それ以外のCESに関しては、リンクされていればGaucheは@code{iconv(3)}を用いて
変換を行います。
@c COMMON

@c EN
When Gauche's conversion routine encounters a character that can't
be mapped, it replaces the character for "geta mark" (U+3013)
if it's a multibyte character in the input encoding, or for '?' if it's
a singlebyte character in the input encoding.
If that happens in iconv, handling of such character depends
on iconv implementation (glibc implementation returns an error).
@c JP
出力CESへマップ不可能な入力文字に出会った場合、Gaucheの変換ルーチンは
その文字が入力CESでマルチバイトである場合はgeta mark '〓' (U+3013) に、
入力CESでシングルバイトである場合は '?' に置換します。
iconvによる変換でマップ不可能な文字に出会った場合の処理はiconvの実装に
依存します(例えばglibcではエラーとなります)。
@c COMMON

@c EN
If the conversion routine encounters an input sequence that
is illegal in the input CES, an error is signalled.
@c JP
変換ルーチンが、入力CESとして不正な入力文字列に出会った場合は
エラーが報告されます。
@c COMMON

@c EN
@strong{Details of Gauche's native conversion algorithm:}
Between EUC_JP, Shift JIS and ISO2022JP, Gauche uses arithmetic
conversion whenever possible.  This even maps the undefined codepoint
properly.  Between Unicode (UTF-8) and EUC_JP, Gauche uses lookup tables.
Between Unicode and Shift JIS or ISO2022JP, Gauche converts the
input CES to EUC_JP, then convert it to the output CES.
If the same CES is specified for input and output, Gauche's conversion
routine just copies input characters to output characters, without 
checking the validity of the encodings.
@c JP
@strong{Gaucheの内部変換アルゴリズムの詳細:}
EUC_JP、Shift JIS、及びISO2022JP間の変換は可能な限り計算で行います。
文字が未定義のコードポイントも計算式に従って変換されます。
Unicode(UTF-8)とEUC_JP間の変換はテーブルルックアップによって行われます。
UnicodeとShift JISまたはISO2022JP間の変換は、入力CESを一度EUC_JPに
変換し、それを出力CESに変換することによって行います。
入力と出力のCESがGaucheの内部アルゴリズムがサポートする範囲で等しかった場合、
Gaucheの変換ルーチンはエンコーディングの正当性はチェックせず、
単に入力を出力にコピーします。
@c COMMON

@table @code
@item EUC_JP, EUCJP, EUCJ, EUC_JISX0213
@c EN
Covers ASCII, JIS X 0201 kana, JIS X 0212 and JIS X 0213 character sets.
JIS X 0212 character set is supported merely because it uses
the code region JIS X 0213 doesn't use, and JIS X 0212 characters
are not converted properly to Shift JIS and UTF-8.
Use JIS X 0213.
@c JP
ASCII, JIS X 0201カナ、JIS X 0212、及びJIS X 0213文字セットをカバーします。
JIS X 0212は、単にJIS X 0213と重ならないコードを使っているためにサポート
されていますが、他のCESへの変換は行われないので注意して下さい。
なるべくJIS X 0213の使用をおすすめします。
@c COMMON

@item SHIFT_JIS, SHIFTJIS, SJIS
@c EN
Covers Shift_JISX0213, except that 0x5c and 0x7e is mapped to ASCII
character set (REVERSE SOLIDUS and TILDE),
instead of JIS X 0201 Roman (YEN SIGN and OVERLINE).
@c JP
Shift_JISX0213をカバーします。但し、0x5cと0x7eに関しては
JIS X 0201 Roman (YEN SIGNとOVERLINE) ではなく
ASCII (REVERSE SOLIDUSとTILDE) にマップされます。
@c COMMON

@item UTF-8, UTF8
@c EN
Unicode 3.2.  Note that some JIS X 0213 characters are mapped to Extension B
(U+20000 and up).
Some JIS X 0213 characters are mapped to two
unicode characters (one base character plus a combining character).
@c JP
Unicode 3.2です。JIS X 0213中の文字のいくつかはExtension B (U+20000〜)
にマップされます。JIS X 0213中の他の文字のいくつかは2つのUnicode文字
(base character + combining character)にマップされます。
@c COMMON

@item ISO2022JP, CSISO2022JP, ISO2022JP-1, ISO2022JP-2, ISO2022JP-3
@c EN
These encodings differ a bit
(except ISO2022JP and CSISO2022JP, which are synonyms), but
Gauche handles them same.  If one of these CES is specified as input,
Gauche recognizes escape sequences of any of CES.
ISO2022JP-2 defines several non-Japanese escape sequences, and
they are recognized by Gauche, but mapped to substitution character
('?' or geta mark).
@c JP
これらのエンコーディングは、CSISO2022JPがISO2022JPのエイリアスであることを除き
異なるエスケープシーケンスを使いますが、Gaucheの中では同じルーチンで処理されます。
これらのエンコーディングのいずれかが入力CESに指定された場合、
Gaucheは全てのバリエーションのエスケープシーケンスを認識します。
但し、ISO2022JP-2に定義された日本語以外の言語のエスケープシーケンスに関しては、
Gaucheはエスケープシーケンスの認識だけを行い、
文字は'?'あるいは'〓' に置換します。
@c COMMON

@c EN
For output, Gauche assumes ISO2022JP first, and uses ISO2022JP-1
escape sequence to put JIS X 0212 character, or uses ISO2022JP-3
escape sequence to put JIS X 0213 plane 2 character.
Thus, if the string contains only JIS X 0208 characters, 
the output is compatible to ISO2022JP.
Precisely speaking, JIS X 0213 specifies some characters in JIS X 0208
codepoint that shouldn't be mixed with JIS X 0208 characters;
Gauche output those characters as JIS X 0208 for compatibility.
(This is the same policy as Emacs-Mule's iso2022jp-3-compatible mode).
@c JP
出力に関してはGaucheは出来る限りISO2022JPでエンコードし、
JIS X 0212文字に出会ったらISO2022JP-1のエスケープシーケンスを、
JIS X 0213の第2面の文字に出会ったらISO2022JP-3のエスケープシーケンスを
用います。したがって、文字列がJIS X 0208の範囲だけで構成されていた場合は
出力はISO2022JP互換となります。
厳密には、JIS X 0213では包摂基準の変更により、
「JIS X 0208と同じコードポイントを用いるがJIS X 0208のエスケープシーケンスを
使ってはいけない文字」というのが定義されています。
Gaucheでは互換性のため、これらの文字もJIS X 0208のエスケープシーケンスを
用いてエンコードします (これは、Emacs-Muleにおけるiso2022jp-3-compatible
モードと同じ方針です)。
@c COMMON
@end table

@node Autodetecting the encoding scheme, Conversion ports, Supported character encoding schemes, Character code conversion
@subsection Autodetecting the encoding scheme
@c NODE 文字エンコーディングの自動判定

@c EN
There are cases that you don't know the CES of the input, but
you know it is one of several possible encodings.
The charconv module has a mechanism
to guess the input encoding.  There can be multiple algorithms,
and each algorithm has the name (wildcard CES).  Right now, there's only one
algorithm implemented:
@c JP
しばしば、入力のCESが未知であり、可能性のあるいくつかの候補から入力のCESを
推測しなければならない場合があります。推測するアルゴリズムはいくつも考えられるので、
それぞれに名前がついています(ワイルドカードCES)。
今のところ、一つのアルゴリズムしか実装されていません。
@c COMMON
@table @code
@item "*JP"
@c EN
To guess the character encoding from japanese text, among either
ISO2022-JP(-1,2,3), EUCJP, SHIFT_JIS or UTF-8.
@c JP
日本語のテキストのCESを、ISO2022-JP(-1,2,3), EUCJP, SHIFT_JIS または UTF-8の
いずれかであるとして推測する。
@c COMMON
@end table

@c EN
The wildcard CES can be used in place of CES name for some conversion functions.
@c JP
ワイルドカードCESは、いくつかの変換関数においてCES名の代わりに使うことができます。
@c COMMON


@defun ces-guess-from-string string scheme
@c EN
Guesses the CES of @var{string} by the character guessing scheme
@var{scheme} (e.g. "*JP").  Returns CES name that can be used
by other charconv functions.   It may return @code{#f} if the
guessing scheme finds no possible encoding in @var{string}.
Note that if there may be more than one possible encoding in
@var{string}, the guessing scheme returns one of them,
usually in favor of the native CES.
@c JP
文字列@var{string}のCESを、CES推測アルゴリズム@var{scheme} ("*JP"など)
を使って推測し、結果のCES名を返します。もしどのCESにも該当しないデータが
含まれていれば@code{#f}が返されます。複数のCESが可能である場合、
ネイティブエンコーディングが含まれていればそれを、
そうでなければ可能なCESからどれかひとつが選んで返されます。
@c COMMON
@end defun


@node Conversion ports,  , Autodetecting the encoding scheme, Character code conversion
@subsection Conversion ports
@c NODE 変換ポート

@defun open-input-conversion-port source from-code :key to-code buffer-size owner?
@c EN
Takes an input port @var{source}, which feeds characters
encoded in @var{from-code}, and returns another input port,
from which you can read characters encoded in @var{to-code}.
@c JP
文字が符号化方法@var{from-code}で符号化されているデータを読み出せる
入力ポート@var{source}を取り、符号化方法@var{to-code}で符号化されたデータを
読み出せるポートを作成して返します。
@c COMMON

@c EN
If @var{to-code} is omitted, the native CES is assumed.
@c JP
@var{to-code}が省略された場合はネイティブのCESと見なされます。
@c COMMON

@c EN
@var{buffer-size} is used to allocate internal buffer size for
conversion.  The default size is about 1 kilobytes and it's suitable
for typical cases.
@c JP
@var{buffer-size}は変換のための内部バッファのサイズを指定します。
省略時のサイズは1Kバイト程で、通常の使用には問題ないサイズです。
@c COMMON

@c EN
If you don't know the @var{source}'s CES, you can specify
CES guessing scheme, such as @code{"*JP"}, in place of @var{from-code}.
The conversion port tries to guess the encoding, by prefetching
the data from @var{source} up to the buffer size.  It signals an error
if the code guessing routine finds no appropriate CES.
If the guessing routine finds ambiguous input, however, it silently
assume one of possible CES's, in favor of the native CES.
Hence it is possible that the guessing is wrong if the buffer
size is too small.  The default size is usually enough for most
text documents, but it may fail if the large text contains mostly ASCII
characters and multibyte characters appear only at the very end of
the document.
To be sure for the worst case,
you have to specify the buffer size large enough to
hold entire text.
@c JP
入力のCESが不明な場合、@code{"*JP"}などのCES推測アルゴリズム名を@var{from-code}
として指定することができます。変換ポートは最高でバッファサイズまでのデータを先読みし、
CESを推測しようとします。そのアルゴリズムで推測されるどのCESにも該当しないデータが
検出された場合はエラーが報告されます。もし複数のCESが可能であるようなデータであった
場合は、Gaucheのネイティブエンコーディングが可能なCESに含まれていればそれが選ばれ、
そうでなければいずれかのCESが適当に選ばれます。従って、バッファサイズが小さすぎると
誤った判定をする可能性が高くなります。大抵のテキストドキュメントに対して、
既定のバッファサイズは十分ですが、大きなテキストのほとんどがASCII文字で最後だけ
マルチバイト文字が現われるようなテキストでは誤判定の可能性があります。
最悪の場合でも結果を保証するには、テキスト全体が格納できるバッファサイズを指定すると
良いでしょう。
@c COMMON

@c EN
By default, @code{open-input-conversion-port} leaves @var{source} open.
If you specify true value to @var{owner?}, the function closes
@var{source} after it reads EOF from the port.
@c JP
通常、@code{open-input-conversion-port}は変換が全て終了した後でも@var{source}
はオープンしたままにします。キーワード引数@var{owner?}に真の値を指定すると、
EOFが読まれた後で@var{source}はクローズされます。
@c COMMON

@c EN
For example, the following code copies a file @file{unknown.txt} to a file
@file{eucjp.txt}, converting unknown japanese CES to EUC-JP.
@c JP
例を示しましょう。以下のコードは未知のCES(但しEUC-JP, SJIS, ISO2022-JP, UTF8の
いずれかであることは分かっている)で書かれたテキストファイル@file{unknown.txt}を
読みだし、文字エンコーディングをEUC-JPに変換して@file{eucjp.txt}に書き出します。
@c COMMON
@example
(call-with-output-file "eucjp.txt"
  (lambda (out)
    (copy-port (open-input-conversion-port
                 (open-input-file "unknown.txt")
                 "*jp"             ;@r{guess code}
                 :to-code "eucjp"
                 :owner? #t)       ;@r{close unknown.txt afterwards}
               out)))
@end example
@end defun


@defun open-output-conversion-port sink to-code :key from-code buffer-size owner?
@c EN
Creates and returns an output port that converts
given characters from @var{from-code} to @var{to-code}
and feed to an output port @var{sink}.
If @var{from-code} is omitted, the native CES is assumed.
You can't specify a character guessing scheme (such as "*JP") to
neither @var{from-code} nor @var{to-code}.
@c JP
文字のエンコーディングを@var{from-code}から@var{to-code}に変換して
出力ポート@var{sink}に書き出すような出力変換ポートを作成して返します。
@var{from-code}が省略された場合はネイティブのCESと見なされます。
@var{from-code}にも@var{to-code}にも、CES推測アルゴリズム名を
使用することはできません。
@c COMMON

@c EN
@var{buffer-size} specifies the size of internal conversion buffer.
The characters put to the returned port may stay in the buffer,
until the port is explicity flushed (by @code{flush}) or
the port is closed.
@c JP
@var{buffer-size}は内部で変換に使われるバッファサイズを指定します。
出力変換ポートに書き出された文字は、@code{flush}を使って明示的に
フラッシュするか出力変換ポートが閉じられるまで、バッファ内に残っている可能性があります。
@c COMMON

@c EN
By default, the returned port doesn't closes @var{sink} when
itself is closed.  If a keyword argument @var{owner?} is provided
and true, however, it closes @var{sink} when it is closed.
@c JP
通常、出力変換ポートがクローズされても@var{sink}はクローズされません。
@var{owner?}に真の値を与えれば、出力変換ポートのクローズ時に@var{sink}を
クローズするようにできます。
@c COMMON
@end defun

@defun ces-convert string from-code :optional to-code
@c EN
Convert @var{string}'s character encoding from @var{from-code}
to @var{to-code}, and returns the converted string.
The returned string may be a byte-string if @var{to-code}
is different from the native CES.
@c JP
@var{from-code}でエンコーディングされた文字列@var{string}を
@var{to-code}でエンコーディングされた文字列に変換します。
@var{to-code}がネイティブエンコーディングで無い場合、返される文字列は
バイト文字列(不完全な文字列)であるかもしれません。
@c COMMON

@c EN
@var{from-code} can be a name of character guessing scheme
(e.g. "*JP").  when @var{to-code} is omitted, the native CES is
assumed.
@c JP
@var{from-code}にはCES推測アルゴリズム名("*JP"など)を与えることができます。
@var{to-code}が省略された場合はネイティブエンコーディングと見なされます。
@c COMMON
@end defun

@defun call-with-input-conversion iport proc :key encoding conversion-buffer-size
@defunx call-with-output-conversion oport proc :key encoding conversion-buffer-size
@c EN
These procedures can be used to perform character I/O with
different encoding temporary from the original port's encoding.

@code{call-with-input-conversion} takes an input port @var{iport}
which uses the character encoding @var{encoding}, and
calls @var{proc} with one argument, a conversion input port. 
From the port, @var{proc} can read characters in
Gauche's internal encoding. 
Note that once @var{proc} is called, it has to read all the 
characters until EOF; see the note below.

@code{call-with-output-conversion} takes an output port @var{oport}
which expects the character encoding @var{encoding}, and
calls @var{proc} with one argument,
a temporary conversion output port.  
To the port, @var{proc} can write characters in
Gauche's internal encoding.  
When @var{proc} returns, or it exits with an error, 
the temporary conversion output port is flushed and closed.  
The caller of @code{call-with-output-conversion}
can continue to use @var{oport} with original encoding afterwards.

Both procedure returns the value(s) that @var{proc} returns.
The default value of @var{encoding} is Gauche's internal
encoding.  Those procedures don't create a conversion port
when it is not necessary.   If @var{conversion-buffer-size} is given, 
it is used as the @var{buffer-size} argument when the conversion
port is open.

You shouldn't use @var{iport}/@var{oport} directly
while @var{proc} is active---character encoding is a
stateful process, and mixing I/O from/to the conversion port and
the underlying port will screw up the state.

@emph{Note:} for the @code{call-with-input-conversion}, you can't
use @var{iport} again unless @var{proc} reads EOF from it.
It's because a conversion port needs to buffer the input, and
there's no way to undo the buffered input to @var{iport}
when @var{proc} returns.
@c JP
この2つの手続きを使うと、元のポートのエンコーディングとは異る一時的な
エンコーディングをもつ文字I/Oを行うことが可能です。

@code{call-with-input-conversion} は、文字エンコード@var{encoding} を
もつ入力ポート @var{iport} をとり、@var{proc}を一つの引数、すなわち、
変換入力ポートとともに呼びだします。このポートから、@var{proc} は文字を
Gauche の内部エンコーディングで読み込むことができます。いったん、
@var{proc}が呼ばれたら、EOFまでのすべての文字を読み込まなくてはなりません。
後述の注意を参照してください。

@code{call-with-output-conversion} は、文字エンコーディング @var{encoding}
を期待する出力ポート @var{oport} をとり、@var{proc}を一つの引数、すなわち、
一時的な変換出力ポートとともに呼びだします。このポートへ、@var{proc}は
Gauche の内部エンコーディングをもつ文字を書き込むことができます。
@var{proc} が戻るか、エラーで抜けると、この一時的な変換出力ポートは
フラッシュされて、クローズされます。@code{call-with-output-conversion}
の呼出し側は、その後、元のエンコーディングのポート@var{oport}を使い
続けること可能です。

どちらの手続きも @var{proc} が返す値を返します。@var{encoding}
のデフォルト値は Gauche の内部エンコーディングです。この2つの手続きは
必要がなければ、変換ポートを作成しません。もし
@var{conversion-buffer-size} が与えられていれば、変換ポートがオープン
されるときに、@var{buffer-size} 引数として使われます。

@var{proc} がアクティブであるあいだは、@var{iport}/@var{oport} を直接
使うべきではありません。文字のエンコーディングはステートフルなプロセスで
変換ポート(から/へ)の入出力を混在させると元にあるポートの状態がおかしく
なってしまいます。

@emph{注意:} @code{call-with-input-conversion} については、
@var{proc} が EOF を読むまでは、@var{iport} を再度利用することはできません。
これは、変換ポートがバッファを必要とし、@var{proc} がもどったときに
@var{iport}へのバッファ付き入力をアンドゥする方法がないからです。
@c COMMON
@end defun

@defun with-input-conversion iport thunk :key encoding conversion-buffer-size
@defunx with-output-conversion oport thunk :key encoding conversion-buffer-size
@c EN
Similar to @code{call-with-*-conversion},
but these procedures call @var{thunk} without arguments,
while the conversion port is set as the current input or output port,
respectively.
The meaning of keyword arguments are the same as @code{call-with-*-conversion}.
@c JP
@code{call-with-*-conversion} と似ていますが、この2つの手続きは、
@var{thunk} を引数なしで呼びます、また、変換ポートはそれぞれ標準入力、標準
出力のポートにセットされます。
キーワード引数の意味は @code{call-with-*-conversion} と同じです。
@c COMMON
@end defun

@defun wrap-with-input-conversion port from-code :key to-code owner? buffer-size
@defunx wrap-with-output-conversion port to-code :key from-code owner? buffer-size
@c EN
Convenient procedures to avoid adding unnecessary conversion port.
Each procedure works like @code{open-input-conversion-port}
and @code{open-output-conversion-port}, respectively,
except if system knows no conversion is needed,
no conversion port is created and @var{port} is returned as is.

When a conversion port is created, @var{port} is always owned by the port.
When you want to close the port, always close the port returned
by @code{wrap-with-*-conversion}, instead the original @var{port}.
If you close the original @var{port} first, the pending conversion
won't be flushed.  (Some conversion requires trailing sequence that
is generated only when the conversion port is closing, so simply
calling @code{flush} isn't enough.)

The @var{buffer-size} argument is passed to 
the @code{open-*-conversion-port}.
@c JP
不要な変換ポートを作らないようにする便利な手続きです。
各手続きはそれぞれ@code{open-input-conversion-port}と
@code{open-output-conversion-port}のように動作します。
但し、指定されたCES間の変換が必要でないとシステムが知っている場合は、
変換ポートは作られず、@var{port}がそのまま返されます。

変換ポートが作られた場合、@var{port}は常に変換ポートに所有されます
(@code{:owner #t}となる)。ポートを閉じる場合は@var{port}ではなく
常に@code{wrap-with-*-conversion}が返したポートを閉じるようにして下さい。
元の@var{port}が先に閉じられた場合、変換中の結果が書き出されない可能性があります。
(変換によっては、ポートが閉じられる時点で終了シーケンスを書き出すものがあるので、
単にポートを@code{flush}するだけでは不十分です)。

@code{:buffer-size} 引数はそのまま
変換ポート作成手続きに渡されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Generating C code, Collection framework, Character code conversion, Library modules - Gauche extensions
@section @code{gauche.cgen} - Generating C code
@c NODE Cコードの生成, @code{gauche.cgen} - Cコードの生成

Significant part of Gauche is written in Gauche or S-expression
based DSL.  During the building process, they are converted
into C sources and then compiled by C compiler.
The @code{gauche.cgen} module and its submodules expose
the functionality Gauche build process is using to the general use.

Required features for a C code generator differ greatly among
applications, and too much scaffolding could be a constraint
for the module users.  So, instead of providing a single
solid framework, we provide a set of loosely coupled modules
so that you can combine necessary features freely.  In fact,
some of Gauche build process only use @code{gauche.cgen.unit}
and @code{gauche.cgen.literal} (see @file{src/builtin-syms.scm},
for example).

@deftp {Module} gauche.cgen
@mdindex gauche.cgen
This is a convenience module that extends
@code{gauche.cgen.unit}, @code{gauche.cgen.literal},
@code{gauche.cgen.type} and @code{gauche.cgen.cise} together.
@end deftp

Usually you can just use @code{gauche.cgen} and don't need
to think about individual submodules.
The following subsections are organized by submodules
only for the convenience of explanation.

@menu
* Generating C source files::   gauche.cgen.unit
* Generating Scheme literals::  gauche.cgen.literals
* Conversions between Scheme and C::  gauche.cgen.type
* C in S expression::           gauche.cgen.cise
@end menu

@node Generating C source files, Generating Scheme literals, Generating C code, Generating C code
@subsection Generating C source files

One of the tricky issues about generating C source is that
you have to put several fragments of code in different
parts of the source file, even you want to say just one thing---that is,
sometimes you have to put declaration before the actual definition,
plus some setup code that needs to be run at initialization time.

@subsubheading Creating a frame

@deftp {Class} <cgen-unit>
@clindex cgen-unit
A @emph{cgen-unit} is a unit of C source generation.
It corresponds to one .c file, and optionally one .h file.
During the processing, a "current unit" is kept in a parameter
@code{cgen-current-unit}, and most cgen APIs implicitly work to it.

The following slot are for public use.  They are used to tailor
the output.  Usually you set those slots at initializatoin time.
The effect is undefined if you change them in the middle of
code geneartion process.

@defivar {<cgen-unit>} name
A string to name this unit.  This is used for the default name
of the generated files (@file{@var{name}.c} and @file{@var{name}.h})
and the suffix of the default name of initialization function.
Other cgen modules may use this to generate names.  Avoid using
characters that are valid for C identifiers.

You can override those default names by setting the other slots.
@end defivar

@defivar {<cgen-unit>} c-file
@defivarx {<cgen-unit>} h-file
The name of the C source file and header file, in strings.
If they are @code{#f} (by default), the value of name slot
is used as the file name, with extension @code{.c} or @code{.h}
is attached, respectively.

To get the file names to be generated, use @code{cgen-unit-c-file}
and @code{cugen-unit-h-file} generic functions, instead of reading
these slots.
@end defivar

@defivar {<cgen-unit>} preamble
A list of strings to be inserted at the top of the generated sources.
The default value is @code{("/* Generated by gauche.cgen */")}.
Each string appears in its
own line.  Usually you don't need anything
@end defivar

@defivar {<cgen-unit>} init-prologue
@defivarx {<cgen-init>} init-epilogue
A string to start or to end the initialization function, respectively.
The default value of @code{init-prologue} is
@code{"void Scm_Init_NAME(void) @{"} where @code{NAME} is the
value of the @code{name} slot.  The default value of @code{init-epilogue}
is just @code{"@}"}.  Each appears in its own line.

To get the default initialization function name, use @code{cgen-unit-init-name}
generic function.

To customize initialization function name, arguments and/or return type,
set @code{init-prologue}.

The content of initialization function is filled by the code
fragments registered by @code{cgen-init}.
@end defivar
@end deftp

@deffn {Parameter} cgen-current-unit
A parameter to keep the current cgen-unit.
@end deffn

A typical flow of generating C code is as follows:

@enumerate
@item
Create a @code{<cgen-unit>} and make it the current unit.
@item
Call code insertion APIs with code fragments.  Fragments are accumulated
in the current unit.
@item
Call @emph{emit} method on the unit, which generates a C file
and optionally a header file.
@end enumerate

@deffn {Generic Function} cgen-emit-c cgen-unit
@deffnx {Generic Function} cgen-emit-h cgen-unit
Write the accumulated code fragments in @var{cgen-unit} to a
C source file and C header file.  The name of the files are
determined by calling @code{cgen-unit-c-file} and @code{cgen-unit-h-file},
respectively.  If the files already exist, its content is overwritten;
you can't gradually write to the files.
So, usually these procedures are called at the last step of the code
generation.

We'll explain the details of how each file is organized under
``Filling the content'' section below.
@end deffn

@deffn {Generic Function} cgen-unit-c-file cgen-unit
@deffnx {Generic Function} cgen-unit-h-file cgen-unit
Returns a string that names C source and header file for
@var{cgen-unit}, respectively.  The default method first
looks at @code{c-file} or @code{h-file} slot of the
@var{cgen-unit}, and if it is @code{#f}, use the value of @code{name}
slot and appends an extension @code{.c} or @code{.h}.
@end deffn

@deffn {Generic Function} cgen-unit-init-name cgen-unit
Returns a string that names the initialization function
generated to C.  It is used to create the default
@code{init-prologue} value. 
@end deffn

@subsubheading Filling the content

There are four parts to which you can add C code
fragment.  Within each part, code fragments are rendered in the
same order as added.

@table @asis
@item extern
This part is put into the header file, if exists.
@item decl
Placed at the beginning of the C source, after the standard
prologue.
@item body
Placed in the C source, following the 'decl' part.
@item init
Placed inside the initialization function, which appears at
the end of the C source.
@end table

The following procedures are the simple way to put a souce
code fragments in an appropriate part:

@defun cgen-extern code @dots{}
@defunx cgen-decl code @dots{}
@defunx cgen-body code @dots{}
@defunx cgen-init code @dots{}
Put code fragments @var{code} @dots{} to the appropriate parts.
Each fragment must be a string.
@end defun

This is an almost minimal example to show the typical usage.  
After running this code you'll get @code{my-cfile.c} and 
@code{my-cfile.h} in the current directory.

@example
(use gauche.cgen)

(define *unit* (make <cgen-unit> :name "my-cfile"))

(parameterize ([cgen-current-unit *unit*])
  (cgen-decl "#include <stdio.h>")
  (cgen-init "printf(stderr, \"initialization function\\n\");")
  (cgen-body "void foo(int n) @{ printf(stderr, \"got %d\\n\", n); @}")
  (cgen-extern "void foo(int n);")
  )

(cgen-emit-c *unit*)
(cgen-emit-h *unit*)
@end example

These are handy escaping procedures; they are useful even
if you don't use other parts of the @code{cgen} modules.

@defun cgen-safe-name string
@defunx cgen-safe-name-friendly string
@defunx cgen-safe-comment string
Escapes characters invalid in C identifiers or C comments.

With @code{cgen-safe-name}, characters other than ASCII alphabets
and digits are converted to a form @code{_XX}, where @code{XX} is
hexadecimal notation of the character code.  (Note that the character
@code{_} is also converted.)  So the returned string can be used
safely as a C identifier.  The mapping is injective, that is,
if the source strings differ, the result string always differ.

On the other hand, @code{cgen-safe-name-friendly} convers
the input string into more readable C identifier.  @code{->} becomes
@code{_TO} (e.g. @code{char->integer} becomes @code{char_TOinteger}),
other @code{-} and @code{_} become @code{_},
@code{?} becomes @code{P} (e.g. @code{char?} becomes @code{charP}),
@code{!} becomes @code{X} (e.g. @code{set!} becomes @code{setX}),
@code{<} and @code{>} become @code{_LT} and @code{_GT} respectively.
Other special characters except @code{_} are converted to @code{_XX}
as in @code{cgen-safe-name}.  The mapping is not injective; e.g.
both @code{read-line} and @code{read_line} map to @code{read_line}.
Use this only when you think some human needs to read the generated
C code (which is not recommended, by the way.)

Much simpler is @code{c-safe-comment}, which just converts
@code{/*} and @code{*/} into @code{/ *} and @code{* /} (a space
between those two characters), so that it won't terminate the
comment inadvertently.  (Technically, escaping only @code{*/} suffice,
but some simple-minded C parser might be confused by @code{/*} in the
comments).   The conversion isn't injective as well.
@end defun

If you want to conditionalize a fragment by C preprocessor
@code{#ifdef}s, use the following macro:

@defmac cgen-with-cpp-condition cpp-expr body @dots{}
Code fragments submitted in @var{body} @dots{} are protected
by @code{#if @var{cpp-expr}} and @code{#endif}.

If @var{cpp-expr} is a string, it is emitted literally:

@example
(cgen-with-cpp-condition "defined(FOO)"
  (cgen-init "foo();"))

;; will generate:
#if defined(FOO)
foo();
#endif /* defined(FOO) */
@end example

You can also construct @var{cpp-expr} by S-expr.

@example
<cpp-expr> : <string>
           | (defined <cpp-expr>)
           | (not <cpp-expr>)
           | (<n-ary-op> <cpp-expr> <cpp-expr> ...)
           | (<binary-op> <cpp-expr> <cpp-expr>)

<n-ary-op> : and | or | + | * | - | /

<binary-op> : > | >= | == | < | <= | !=
            | logand | logior | lognot | >> | <<
@end example

Example:

@example
(cgen-with-cpp-condition '(and (defined FOO)
                               (defined BAR))
  (cgen-init "foo();"))

;; will generate:
#if ((defined FOO)&&(defined BAR))
foo();
#endif /* ((defined FOO)&&(defined BAR)) */
@end example

You can nest @code{cgen-with-cpp-condition}.
@end defmac

@subsubheading Submitting code fragments for more than one parts

When you try to abstract code generation process,
calling individual procedures for each parts (e.g. @code{cgen-body}
or @code{cgen-init}) becomes tedious, since such higher-level
constructs are likely to require generating code fragments
to various parts.  Instead, you can create a customized class
that handles submission of fragments to appropriate parts.

@deftp {Class} <cgen-node>
@clindex cgen-node
A base class to represent a set of code fragments.

The state of C preprocessor condition (set by @code{with-cgen-cpp-condition})
is captured when an instance of the subclass of this class is
created, so generating appropriate @code{#if}s and @code{#endif}s are
automatically handled.
@end deftp

You subclass @code{<cgen-node>}, then define method(s) to
one or more of the following generic functions:

@deffn {Generic Function} cgen-emit-xtrn cgen-node
@deffnx {Generic Function} cgen-emit-decl cgen-node
@deffnx {Generic Function} cgen-emit-body cgen-node
@deffnx {Generic Function} cgen-emit-init cgen-node
These generic functions are called during writing out
the C source within @code{cgen-emit-c} and @code{cgen-emit-h}.
Inside these methods, anything written out to the
current output port goes into the output file.

While generating @code{.h} file by @code{cgen-emit-h}, 
@code{cgen-emit-xtrn} method for all submitted nodes are
called in order of submission.

While generating @code{.c} file by @code{cgen-emit-c},
@code{cgen-emit-decl} method for all submitted nodes are
called first, then @code{cgen-emit-body} method, then
@code{cgen-emit-init} method.

If you don't specialize any one of these method, it doesn't
generate code in that part.
@end deffn

Once you define your subclass and create an instace,
you can submit it to the current cgen unit by this procedure:

@defun cgen-add! cgen-node
Submit @var{cgen-node} to the current cgen unit.
If the current unit is not set, @var{cgen-node} is simply ignored.
@end defun

In fact, the procedures @code{cgen-extern}, @code{cgen-decl},
@code{cgen-body} and @code{cgen-init} are just a convenience
wrapper to create an internal subclass specialized to generate
code fragment only to the designated part.


@node Generating Scheme literals, Conversions between Scheme and C, Generating C source files, Generating C code
@subsection Generating Scheme literals

Sometimes you want to refer to a Scheme constant value in C code.
It is trivial if the value is a simple thing like Scheme boolean
(@code{SCM_TRUE}, @code{SCM_FALSE}), characters (@code{SCM_MAKE_CHAR(code)}),
small integers (@code{SCM_MAKE_INT(value)}), etc.  You can directly
write it in C code.  However, once you step outside of these simple
values, it gets tedious quickly, involving static data declarations
and/or runtime initialization code.  

For example, to get a Scheme value of a list of symbols @code{(a b c)}, 
you have to (1) create @code{ScmString}s for the names of the symbols,
(2) pass them to @code{Scm_Intern} to get Scheme symbols, then
(3) call @code{Scm_Cons}es (or a convenience macro @code{SCM_LIST3}) to
build a list.

With @code{gauche.cgen}, those code can be generated automatically.

NOTE: If you use @code{cgen-literal}, make sure you call
@code{(cgen-decl "#include <gauche.h>")} to include @file{gauche.h}
before the first call of @code{cgen-literal}, which may insert
declarations that ness @file{gauche.h}.

@defun cgen-literal obj
Returns an @code{<cgen-literal>} object for a Scheme object @var{obj},
and submit necessary declarations and initialization code to the
current cgen unit.
@end defun

For the above example, you can just call @code{(cgen-literal '(a b c))}
and the C code to set up the Scheme literal of the list of three
symbols will be generated.

The result of @code{cgen-literal} is an instance of @code{<cgen-literal>};
the detail of the class isn't for public use, but you can use it
to refer the created literal in C code.

@deffn {Generic Function} cgen-cexpr cgen-literal
Returns a C code expression fragment of type @code{ScmObj},
which represents the Scheme literal value.

The following example creates a C function @code{printabc} that prints
the literal value @code{(a b c)}, created by @code{cgen-literal}.

@example
(define *unit* (make <cgen-unit> :name "foo"))
(parameterize ((cgen-current-unit *unit*))
  (let1 lit (cgen-literal '(a b c))
    (cgen-body 
     (format "void printabc() @{ Scm_Printf(SCM_CUROUT, \"%S\", ~a); @}"
             (cgen-c-name lit)))))
(cgen-emit-c *unit*)
@end example

If you examine the generated file @file{foo.c}, you'll get a
general idea of how it is handled.
@end deffn

One advantage of @code{cgen-literal} is that it tries to share
the same literal whenever possible.  If you call
@code{(cgen-literal '(a b c))} twice in the same cgen unit,
you'll get one instance of cgen-literal.  If you call
@code{(cgen-literal '(b c))} then, it will share the tail
of the original list @code{(a b c)}.  So you can just use
@code{cgen-literal} whenever you need to have Scheme literal
values, without worrying about generating excessive amount of
duplicated code.

Certain Scheme objects cannot be generated as a literal; for example,
an opened port can't, since it carries lots of runtime information.

(There's a machinery to allow programmers to extend the cgen-literal
behavior for new types.  The API isn't fixed yet, though.)


@node Conversions between Scheme and C, C in S expression, Generating Scheme literals, Generating C code
@subsection Conversions between Scheme and C

In the C world, any Scheme object is uniformly of type @code{ScmObj}.
But it is often the case that you need to narrow down to the
specific type and convert it to a C value.  Gauche maintains
a database of how to typecheck and map Scheme value to C value and
vice versa.

Note that the mapping isn't one-to-one: Scheme @code{<integer>}
can be mapped to C's @code{short}, @code{long}, @code{unsigned int},
or even just @code{ScmObj} if the C routine wants to cover bignums.
So each mapping has its own name.  For historical reasons, each
mapping is called @emph{stub type}.  The names of stub types look
like Scheme type but its semantics differ from Scheme type.
Remember: Each stub type represents a specific mapping between a
Scheme type and a C type.

Each stub type has a @emph{C-predicate},
a @emph{boxer} and an @emph{unboxer}, each of them is a Scheme
string for the name of a C function or C macro.
A C-predicate takes @var{ScmObj} object and returns C boolean
value that if the given object has a valid type and range for the
stub type.
A boxer takes C object and converts it to a Scheme object; it
usually involves wrapping or @emph{boxing} the C value in a
tagged pointer or object, hence the name.
An unboxer does the opposite: takes a Scheme object and convert
it to a C value.  The Scheme object must be checked by the C-predicate
before being passed to the unboxer.

The following table shows the predefined stub types.
Note that the most of aggregate types has one to one mappings.
The difficult ones are numeric types and strings.
Scheme numbers can represent much wider range of numbers
than C, so you have to narrow down according to the capability
of C routine.  Scheme strings have byte size and character length,
and the body may not be NULL-terminated; so the @code{<string>}
stub type maps Scheme string to @code{ScmString*}.  For the convenience,
you can use @code{<const-cstring>}, which creates NUL-terminated
C string; beware that it may incur some copying cost.

@example
Stub type    Scheme       C           Notes
-----------------------------------------------------------------
<fixnum>     <integer>    int         Integers within fixnum range
<integer>    <integer>    ScmObj      Any exact integers
<real>       <real>       double      Value converted to double
<number>     <number>     ScmObj      Any numbers

<int>        <integer>    int         Integers representable in C
<int8>       <integer>    int
<int16>      <integer>    int
<int32>      <integer>    int
<short>      <integer>    short
<long>       <integer>    long
<uint>       <integer>    uint        Integers representable in C
<uint8>      <integer>    uint
<uint16>     <integer>    uint
<uint32>     <integer>    uint
<ushort>     <integer>    ushort
<ulong>      <integer>    ulong
<float>      <real>       float       Unboxed value casted to float
<double>     <real>       double      Alias of <real>

<boolean>    <boolean>    int         Boolean value
<char>       <char>       ScmChar     Note: not a C char

<void>       -            void        (Used only as a return type.
                                        Scheme function returns #<undef>)

<string>     <string>     ScmString*  Note: not a C string

<const-cstring> <string>  const char* For arguments, string is unboxed
                                      by Scm_GetStringConst.
                                      For return values, C string is boxed
                                      by SCM_MAKE_STR_COPYING.

<pair>       <pair>       ScmPair*
<list>       <list>       ScmObj
<string>     <string>     ScmString*
<symbol>     <symbol>     ScmSymbol*
<keyword>    <keyword>    ScmKeyword*
<vector>     <vector>     ScmVector*
<uvector>    <uvector>    ScmUVector*
<s8vector>   <s8vector>   ScmS8Vector*
<u8vector>   <u8vector>   ScmU8Vector*
<s16vector>  <s16vector>  ScmS16Vector*
<u16vector>  <u16vector>  ScmU16Vector*
<s32vector>  <s32vector>  ScmS32Vector*
<u32vector>  <u32vector>  ScmU32Vector*
<s64vector>  <s64vector>  ScmS64Vector*
<u64vector>  <u64vector>  ScmU64Vector*
<f16vector>  <f16vector>  ScmF16Vector*
<f32vector>  <f32vector>  ScmF32Vector*
<f64vector>  <f64vector>  ScmF64Vector*

<hash-table> <hash-table> ScmHashTable*
<tree-map>   <tree-map>   ScmTreeMap*

<char-set>   <char-set>   ScmCharSet*
<regexp>     <regexp>     ScmRegexp*
<regmatch>   <regmatch>   ScmRegMatch*
<port>       <port>       ScmPort*
<input-port>  <input-port> ScmPort*
<output-port> <output-port> ScmPort*
<procedure>  <procedure>  ScmProcedure*
<closure>    <closure>    ScmClosure*
<promise>    <promise>    ScmPromise*

<class>      <class>      ScmClass*
<method>     <method>     ScmMethod*
<module>     <module>     ScmModule*
<thread>     <thread>     ScmVM*
<mutex>      <mutex>      ScmMutex*
<condition-variable> <condition-variable> ScmConditionVariable*
@end example

A stub type can have a @emph{maybe} variation, denoted by
@code{?} suffix; e.g. @code{<string>?}.  It is a union type of
the base type and boolean false (for @code{<string>?}, it
can be either @code{<string>} or @code{#f}.)   In the C world,
boolean false is mapped to @code{NULL} pointer.  It is convenient
to pass a C value that allowed to be NULL back and forth---if
you pass @code{#f} from the Scheme world it comes out @code{NULL} to
the C world, and vice versa.   The maybe variation is only
meaningful when the C type is a pointer type.

@deftp {Class} <cgen-type>
An instance of this class represents a stub type.
It can be looked up by name such as @code{<const-cstring>} by
@code{cgen-type-from-name}.
@end deftp

@defun cgen-type-from-name name
Returns an instance of @code{<cgen-type>} that has @var{name}.
If the name is unknown, @code{#f} is returned.
@end defun

@defun cgen-box-expr cgen-type c-expr
@defunx cgen-unbox-expr cgen-type c-expr
@defunx cgen-pred-expr cgen-type c-expr
@var{c-expr} is a string denotes a C expression.
Returns a string of C expression that boxes, unboxes, or
typechecks the @var{c-expr} according to the @var{cgen-type}.

@example
@end example
;; suppose foo() returns char*
(cgen-box-expr
 (cgen-type-from-name '<const-cstring>)
 "foo()")
 @result{} "SCM_MAKE_STR_COPYING(foo())"
@end defun


@node C in S expression,  , Conversions between Scheme and C, Generating C code
@subsection CiSE - C in S expression




@c ----------------------------------------------------------------------
@node Collection framework, Configuration parameters, Generating C code, Library modules - Gauche extensions
@section @code{gauche.collection} - Collection framework
@c NODE コレクションフレームワーク, @code{gauche.collection} - コレクションフレームワーク

@deftp {Module} gauche.collection
@mdindex gauche.collection
@c EN
This module provides a set of generic functions (GFs) that iterate over
various collections.   The Scheme standard [R5RS] has some iterative
primitives such as @code{map} and @code{for-each},
and SRFI-1 (@xref{List library} adds a rich set of such functions,
but they work only on lists.

Using the method dispatch of the object system, this module
efficiently extends those
functions for other collection classes such as vectors and hash tables.
It also provides a simple way for user-defined class to adapt
those operations.
So far, the following operations are defined.
@c JP
このモジュールは、様々なコレクションに対して繰り返し処理を行う総称関数を提供します。
Schemeの規格は@code{map}や@code{for-each}などの繰り返し手続きを定義しており、
またSRFI-1(@ref{List library}参照)は更に数多くの繰り返し手続きを提供しますが、
それらはリストに対してしか動作しません。

このモジュールはオブジェクトシステムのメソッドディスパッチを利用して、
これらの手続きをベクタやハッシュテーブルのような一般のコレクションタイプに対しても
効率良く動作するように拡張します。また、ユーザ定義のクラスにこれらの操作を実装するための
簡単な方法も提供します。今のところ、次のような総称関数が提供されています。
@c COMMON

@table @asis
@c EN
@item Mapping
@c JP
@item マッピング
@c COMMON
@code{fold}, @code{fold2}, @code{fold3}, 
@code{map}, @code{map-to}, @code{map-accum}, @code{for-each}
@c EN
@item Selection and searching
@c JP
@item 選択と探索
@c COMMON
@code{find}, @code{find-min}, @code{find-max}, @code{find-min&max},
@code{filter}, @code{filter-to},
@code{remove}, @code{remove-to}, @code{partition}, @code{partition-to}
@code{group-collection}
@c EN
@item Conversion
@c JP
@item 変換
@c COMMON
@code{coerce-to}
@c EN
@item Miscellaneous
@c JP
@item その他
@c COMMON
@code{size-of}, @code{lazy-size-of}
@c EN
@item Fundamental iterator creator
@c JP
@item 基礎的なイテレータ構築メソッド
@c COMMON
@code{call-with-iterator}, @code{call-with-builder},
@code{with-iterator}, @code{with-builder}, @code{call-with-iterators}.
@end table

@c EN
Those operations work on @emph{collections} and its subclass,
@emph{sequences}.  A collection is a certain form of a set
of objects that you can traverse all the object in it in a certain way.
A sequence is a collection that all its elements are ordered, so that
you can retrieve its element by index.
@c JP
これらの操作は、@emph{コレクション}とそのサブクラスである
@emph{シーケンス}に対して動作します。コレクションは、その要素を全て
訪れる方法が用意されているようなオブジェクトの集合です。
シーケンスは、要素間に全順序関係が定義されておりインデックスで要素を取り出すことが
できるようなコレクションです。
@c COMMON

@c EN
The following Gauche built-in objects are treated as collections and/or
sequences.
@c JP
次にあげるGaucheの組み込みオブジェクトはシーケンスあるいはコレクションとして動作します。
@c COMMON
@table @code
@item <list>
@c EN
A sequence.
@c JP
シーケンス
@c COMMON
@item <vector>
@c EN
A sequence.
@c JP
シーケンス
@c COMMON
@item <string>
@c EN
A sequence (of characters)
@c JP
文字のシーケンス
@c COMMON
@item <hash-table>
@c EN
A collection.  Each element is a pair of a key and a value.
@c JP
コレクション。各要素はキーと値のペア。
@c COMMON
@item <s8vector>, <u8vector>, @dots{} <f64vector>
@c EN
A sequence (methods defined in @code{srfi-4} module,
@xref{Homogeneous vectors}).
@c JP
シーケンス。メソッドは@code{srfi-4}モジュール内で定義されます。
@ref{Homogeneous vectors}参照。
@c COMMON
@end table

@c EN
@xref{Sequence framework}, for it adds more sequence specific
methods.
@c JP
@ref{Sequence framework}も参照してください。シーケンス特有のメソッドが
追加されます。
@c COMMON

@c EN
The methods that needs to return a set of objects, i.e. 
@code{map}, @code{filter}, @code{remove} and @code{partition}.
returns a list (or lists).  The corresponding ``-to'' variant
(@code{map-to}, @code{filter-to}, @code{remove-to} and @code{partition-to}.
takes a collection class argument and returns the collection of the class.
@c JP
オブジェクトの集合を返すようなメソッド、すなわち
@code{map}、@code{filter}、@code{remove}および@code{partition}は、
リストを返します。対応する``-to''がつくメソッド
(@code{map-to}、@code{filter-to}、@code{remove-to}、@code{partition-to})
はコレクションクラスも引数に取り、そのクラスのコレクションを返します。
@c COMMON
@end deftp

@menu
* Mapping over collection::     
* Selection and searching in collection::  
* Miscellaneous operations on collection::  
* Fundamental iterator creators::  
* Implementing collections::    
@end menu

@node Mapping over collection, Selection and searching in collection, Collection framework, Collection framework
@subsection Mapping over collection
@c NODE コレクションに対するマッピング

@c EN
These generic functions extends the standard mapping procedures.
See also @ref{Mapping over sequences}, if you care the index
as well as elements.
@c JP
これらのジェネリックファンクションは標準のマッピング手続きを拡張します。
要素だけでなくそのインデックスも必要な場合は@ref{Mapping over sequences}を
参照して下さい。
@c COMMON

@deffn {Generic function} fold proc knil coll coll2 @dots{}
@c EN
This is a natural extension of @var{fold} in SRFI-1 (@xref{SRFI-1 Fold}).
@c JP
SRFI-1で定義される@var{fold} (@ref{SRFI-1 Fold}参照) の自然な拡張です。
@c COMMON

@c EN
For each element @var{Ei} in the collection @var{coll}, @var{proc} is
called as (@var{proc} @var{Ei} @var{Ri-1}), where @var{Ri-1} is the 
result of (@var{i}-1)-th invocation of @var{proc} for @var{i} > 0, 
and @var{R0} is @var{knil}.  Returns the last invocation of @var{proc}.
@c JP
コレクション@var{coll}の各要素@var{Ei}に対して、手続き@var{proc}が
(@var{proc} @var{Ei} @var{Ri-1}) のように呼ばれます。ここで、
@var{Ri-1} は @var{i} > 0 に対しては (@var{i}-1)番目の@var{proc}の呼び出しの
結果であり、@var{R0}は@var{knil}です。最後の@var{proc}の戻り値を返します。
@c COMMON
@example
(fold + 0 '#(1 2 3 4)) @result{} 10
(fold cons '() "abc")  @result{} (#\c #\b #\a)
@end example

@c EN
If the @var{coll} is a sequence, it is guaranteed that
the elements are traversed in order.  Otherwise, the order
of iteration is undefined.
@c JP
@var{coll}がシーケンスでもある場合、要素はシーケンスの順に@var{proc}に渡されます。
そうでなければ繰り返しの順序は未定義です。
@c COMMON

@c EN
Note: We don't provide @code{fold-right} on collections, since the order
of elements doesn't matter, so only @code{fold} is sufficient for 
meaningful traversal.
However, sequences do have @code{fold-right};
see @ref{Mapping over sequences}.
@c JP
註：コレクションに対する@code{fold-right}は提供されません。コレクションでは
要素の順序は定義されないため、意味のあるトラバースをするのには
@code{fold}だけあれば十分だからです。
しかし、シーケンスに対しては@code{fold-right}が定義されます。
@ref{Mapping over sequences}を参照して下さい。
@c COMMON

@c EN
You can fold more than one collection, although it doesn't make
much sense unless all of the collections are sequences.
Suppose @var{E(k, i)} for @var{i}-th element
of @var{k}-th collection.  @var{proc} is called as
@c JP
複数のコレクションを@code{fold}に渡すこともできます (但し、その全てがシーケンスで
なければあまり意味のある操作では無いでしょう)。
@var{k}番目のコレクションの@var{i}番目の要素を@var{E(k, i)}とするとき、
@var{proc}は以下のように呼ばれます。
@c COMMON
@example
(@var{proc} @var{E(0,i)} @var{E(1,i)} @dots{} @var{E(K-1,i)} @var{Ri-1})
@end example

@c EN
Different types of collections can be mixed together.
@c JP
異なる型のコレクションを混ぜて扱うことができます。
@c COMMON

@example
(fold acons '() "abc" '#(1 2 3))
  @result{} ((#\c 3) (#\b 2) (#\a 1))

@c EN
;; @r{calculates dot product of two vectors}
@c JP
;; @r{二つのベクタの内積を計算}
@c COMMON
(fold (lambda (a b r) (+ (* a b) r)) 0
      '#(3 5 7) '#(2 4 6))
  @result{} 68
@end example

@c EN
When more than one collection is given, @code{fold} terminates
as soon as at least one of the collections exhausted.
@c JP
複数のコレクションが与えられた場合、@code{fold}は少なくともひとつのコレクションが
終了した時点で終了します。
@c COMMON
@end deffn

@deffn {Generic function} fold2 proc knil1 knil2 coll coll2 @dots{}
@deffnx {Generic function} fold3 proc knil1 knil2 knil3 coll coll2 @dots{}
@c EN
Like @code{fold}, but they can carry two and three state values
instead of one, respectively.  The state values are
initialized by @var{knilN}.  The procedure @var{proc} is called
with each element of @var{collN}, and the state values.  It must return
two (@code{fold2}) or three (@code{fold3}) values, which will be used
as the state values of next iteration.  The values returned in the
last iteration will be the return values of @code{fold2} and @code{fold3}.
@c JP
@code{fold}と似ていますが、1つではなくそれぞれ2, 3個の状態値を
持ち回ります。状態値は@var{knilN}によって初期化されます。
手続き@var{proc}はコレクション@var{collN}の各要素値と状態値を
引数として取り、@code{fold2}の場合は2個、@code{fold3}の場合は3個の
値を返さねばなりません。返された値が次の繰り返しでの状態値として
使われます。最後に返された値が@code{fold2}, @code{fold3}の戻り値と
なります。
@c COMMON

@example
(fold2 (lambda (elt a b) (values (min elt a) (max elt b)))
       256 0 '#u8(33 12 142 1 74 98 12 5 99))
 @result{} 1 and 142  ;; find minimum and maximum values
@end example

@c EN
See also @code{map-accum} below.
@c JP
下の@code{map-accum}も参照。
@c COMMON
@end deffn


@deffn {Generic function} map proc coll coll2 @dots{}
@c EN
This extends the built-in @code{map} (@xref{Procedures}).
Apply @var{proc} for each element in the collection @var{coll}, and
returns a list of the results.
@c JP
組み込み手続き@code{map} (@ref{Procedures}参照) を拡張します。
コレクション@var{coll}の各要素に手続き@var{proc}を適用し、その結果をリストにして
返します。
@c COMMON

@c EN
If the @var{coll} is a sequence, it is guaranteed that
the elements are traversed in order.  Otherwise, the order
of iteration is undefined.
@c JP
@var{coll}がシーケンスでもある場合、要素はシーケンスの順に@var{proc}に渡されます。
そうでなければ繰り返しの順序は未定義です。
@c COMMON

@c EN
If more than one collection is passed, @var{proc} is called with
elements for each collection.  In such case, @code{map} terminates
as soon as at least one of the collection is exhausted.  Note that passing
more than one collection doesn't make much sense unless
all the collections are sequences.
@c JP
複数のコレクションが与えられた場合、@var{proc}は各コレクションからの要素を引数として
呼び出されます。@code{map}はひとつでもコレクションの最後に到達したら終了します。
複数のコレクションを渡すのは、コレクションの全てがシーケンスでないとあまり意味がないでしょう。
@c COMMON

@example
(map (lambda (x) (* x 2)) '#(1 2 3))
  @result{} #(2 4 6)

(map char-upcase "abc")
  @result{} (#\A #\B #\C)

(map + '#(1 2 3) '#(4 5 6))
  @result{} (5 7 9)
@end example

@c EN
@code{map} @emph{always} returns a list.  If you want to get the result
in a different type of collection, use @code{map-to} described below.
If you wonder why @code{(map char-upcase "abc")} doesn't return
@code{"ABC"}, read the discussion in the bottom of this subsection.
@c JP
@code{map}は常にリストを返します。別のコレクション型で結果を得たい場合は、
次に示す@code{map-to}を使って下さい。何故@code{(map char-upcase "abc")}が
@code{"ABC"}を返さないのか疑問なら、この最後にあるディスカッションを参照してください。
@c COMMON
@end deffn

@deffn {Generic function} map-to class proc coll coll2 @dots{}
@c EN
This works the same as @code{map}, except the result is returned
in a collection of class @var{class}.   @code{Class} must be a
collection class and have a builder interface
(@xref{Fundamental iterator creators}).
@c JP
@code{map}と同じように動作しますが、結果はクラス@var{class}のインスタンスとして返されます。
@var{class}はコレクションクラスでなければなりません。
また、ビルダーインタフェースを持っている必要があります
(@ref{Fundamental iterator creators}参照).
@c COMMON

@example
(map-to <vector> + '#(1 2 3) '#(4 5 6))
  @result{} #(5 7 9)

(map-to <string> char-upcase "def")
  @result{} "DEF"

(map-to <vector> char=? "bed" "pet")
  @result{} #(#f #t #f)
@end example
@end deffn

@deffn {Generic function} map-accum proc seed coll1 coll2 @dots{}
@c EN
Collects results of @var{proc} over collections, while passing
a state value.  @var{proc} is called like this:
@c JP
状態値を持ち回りながら@var{proc}のコレクションの各要素への呼び出しを集めます。
@var{proc}は次のように呼ばれます。
@c COMMON
@example
(@var{proc} @var{elt1} @var{elt2} @dots{} @var{seed})
@end example
@c EN
Where @var{elt1} @var{elt2} @dots{} are the elements of 
@var{coll1} @var{coll2} @dots{}.
It must return two values; the first value is collected into
a list (like @code{map}), while the second value is passed as
@var{seed} to the next call of @var{proc}.  
@c JP
ここで@var{elt1} @var{elt2} @dots{}は
@var{coll1} @var{coll2} @dots{}の各要素です。
@var{proc}は2つの値を返さねばなりません。最初の値が@code{map}のように
リストへと集められます。2つ目の値は次の@var{proc}の呼び出しの@var{seed}
として使われます。
@c COMMON

@c EN
When one of the collections is exhausted, @code{map-accum} returns
two values, the list of the first return values from @var{proc},
and the second return value of the last call of @var{proc}.
@c JP
いずれかのコレクションの要素を使い切った時点で、@code{map-accum}は
2つの値を返します。最初の値は@var{proc}の最初の戻り値をリストにしたもの、
2番目の値は@var{proc}の最後の呼び出しの2番目の戻り値です。
@c COMMON

@c EN
If the given collections are sequences, it is guaranteed that
@var{proc} is applied in order of the sequence.
@c JP
もし与えられたコレクションがシーケンスであった場合は、
@var{proc}はシーケンスの順序通りに適用されます。
@c COMMON

@c EN
This is similar to Haskell's @code{mapAccumL}, but note that
the order of @code{proc}'s argument and return values are
reversed.
@c JP
この手続きはHaskellの@code{mapAccumL}と似ています。但し、
@code{proc}の引数と戻り値の順が逆転していることに注意して下さい。
@c COMMON
@end deffn


@deffn {Generic function} for-each proc coll coll2 @dots{}
@c EN
Extension of built-in @code{for-each} (@xref{Procedures}).
Applies @var{proc} for each elements in the collection(s).
The result of @var{proc} is discarded.  The return value of
@code{for-each} is undefined.
@c JP
組み込み手続き@code{for-each} (@ref{Procedures}参照) を拡張します。
コレクション@var{coll}の各要素に手続き@var{proc}を適用します。
@var{proc}の結果は捨てられます。@code{for-each}の結果は未定義です。
@c COMMON

@c EN
If the @var{coll} is a sequence, it is guaranteed that
the elements are traversed in order.  Otherwise, the order
of iteration is undefined.
@c JP
@var{coll}がシーケンスでもある場合、要素はシーケンスの順に@var{proc}に渡されます。
そうでなければ繰り返しの順序は未定義です。
@c COMMON

@c EN
If more than one collection is passed, @var{proc} is called with
elements for each collection.  In such case, @code{for-each} terminates
as soon as one of the collection is exhausted.  Note that passing
more than one collection doesn't make much sense unless
all the collections are sequences.
@c JP
複数のコレクションが与えられた場合、@var{proc}は各コレクションからの要素を引数として
呼び出されます。@code{for-each}はひとつでもコレクションの最後に到達したら終了します。
複数のコレクションを渡すのは、コレクションの全てがシーケンスでないとあまり意味がないでしょう。
@c COMMON
@end deffn


@deffn {Generic Function} fold$ proc
@deffnx {Generic Function} fold$ proc knil
@deffnx {Generic Function} map$ proc
@deffnx {Generic Function} for-each$ proc
@c EN
Partial-application version of @code{fold}, @code{map} and @code{for-each}.
@c JP
@code{fold}、@code{map}、@code{for-each}の部分評価版です。
@c COMMON
@end deffn


@c EN
@emph{Discussion:}  It is debatable what type of collection @code{map}
should return when it operates on the collections other than lists.
It may seem more ``natural'' if @code{(map * '#(1 2) '#(3 4))}
returns a vector, and @code{(map char-upcase "abc")} returns a string.
@c JP
@emph{Discussion:}  @code{map}がリスト以外に対して適用されたとき、どういう
コレクション型を返すべきでしょう。
@code{(map * '#(1 2) '#(3 4))} がベクタを返し、
@code{(map char-upcase "abc")} が文字列を返すようにするほうが「自然」でしょうか。
@c COMMON

@c EN
Although such interface seems work for simple cases, it'll become
problematic for more general cases.  What type of collection should
be returned if a string and a vector are passed?  Furthermore,
some collection may only have iterator interface but no builder
interface, so that the result can't be coerced to the argument type
(suppose you're mapping over database records, for example).
And Scheme programmers are used to think @code{map} returns a list,
and the result of @code{map} are applied to the procedures that
takes list everywhere.
@c JP
そのようなインタフェースは単純な場合には動作するように思えますが、
一般的な拡張は困難です。文字列とベクタが同時に渡されたらどうします?
更に、コレクションクラスによっては繰り返しインタフェースは持っていても
ビルダーインタフェースを持っていない場合があり、結果をそのコレクションクラスとして
返せない場合もあります (データベースレコードのコレクションに対してマップする、
といった用法を考えてみて下さい)。また、Schemeプログラマは@code{map}が
リストを返すという事実に慣れ親しんでおり、既存のコードも@var{map}の戻り値を
リストを受け取る手続きに渡すことがよく行われています。
@c COMMON

@c EN
So I decided to add another method, @code{map-to}, to specify
the return type explicitly
The idea of passing the return type is taken from CommonLisp's @code{map}
function, but taking a class metaobject, @code{map-to} is much flexible
to extend using method dispatch.
This protocol (``-to'' variant takes a class metaobject
for the result collection) is used thoughout the collection framework.
@c JP
そこで、結果の型を明示的に指定する@code{map-to}という別のメソッドを定義しました。
結果の型を渡すのは、CommonLispの@code{map}関数にならっていますが、
Gaucheではクラスメタオブジェクトを渡すようにしたため、メソッドディスパッチを使って
拡張することが容易です。``-to'' のつくメソッドは結果のコレクションのクラスを
取るというインタフェースはコレクションフレームワーク中で統一的に使われています。
@c COMMON

@node Selection and searching in collection, Miscellaneous operations on collection, Mapping over collection, Collection framework
@subsection Selection and searching in collection
@c NODE コレクションからの選択と探索

@deffn {Generic function} find pred coll
@c EN
Applies @var{pred} for each element of a collection @var{coll} until
@var{pred} returns a true value.  Returns the element on which @var{pred}
returned a true value, or @code{#f} if no element satisfies @var{pred}.
@c JP
@var{pred}をコレクション@var{coll}の要素に適用してゆきます。@var{pred}が
真の値を返したらそこで打ち切り、その要素を返します。@var{pred}が真の値を返す
要素が無かった場合は@code{#f}を返します。
@c COMMON

@c EN
If @var{coll} is a sequence, it is guaranteed that @var{pred} is
applied in order.  Otherwise the order of application is undefined.
@c JP
@var{coll}がシーケンスでもある場合、要素はシーケンスの順に@var{proc}に渡されます。
そうでなければ繰り返しの順序は未定義です。
@c COMMON

@example
(find char-upper-case? "abcDe") @result{} #\D
(find even? '#(1 3 4 6)) @result{} 4
(find even? '(1 3 5 7))  @result{} #F
@end example
@end deffn

@deffn {Generic function} find-min coll :key key compare default
@deffnx {Generic function} find-max coll :key key compare default
@c EN
Returns a minimum or maximum element in the collection @var{coll}.

A one-argument procedure @var{key}, whose default is @code{identity},
is applied for each element to obtain a comparison value.
Then a compaison value is compared by a two-argument procedure
@var{compare}, whose default is @code{<}.
If the collection has zero or one element, the @var{compare} procedure
is never called.

When the collection is empty, a value given to @var{default} is
returned, whose default is @code{#f}.
@c JP
コレクション@var{coll}から最小もしくは最大の要素を探して返します。

コレクションの各要素に対し、1引数の手続き@var{key}が適用され、
その戻り値が比較対象となります。@var{key}のデフォルトは@code{identity}です。
比較対象の値は2引数の手続き@var{compare}で比較されます。
@var{compare}のデフォルトは@code{<}です。コレクション中の要素数が
1つ以下の場合は@var{compare}は呼ばれません。

コレクションが空の場合は、@var{default}で指定した値が返されます。
@var{default}のデフォルト値は@code{#f}です。
@c COMMON

@example
(find-min '((a . 3) (b . 9) (c . -1) (d . 7)) :key cdr) @result{} (c . -1)
@end example
@end deffn

@deffn {Generic function} find-min&max coll :key key compare default default-min default-max
@c EN
Does @code{find-min} and @code{find-max} simultaneously, and returns
two values, the minimum element and the maximum element.
The keyword arguments @var{key}, @var{compare}, and @var{default} are
the same as @code{find-min} and @code{find-max}.  Alternatively
you can give default values for minimum and maximum separately,
by @var{default-min} and @var{default-max}.
@c JP
@code{find-min}と@code{find-max}の動作を同時に行い、
最小と最大の要素をふたつの値として返します。
キーワード引数@var{key}、@var{compare}、@var{default}の意味は
@code{find-min}、@code{find-max}と同じです。
また、@var{default-min}と@var{default-max}を使って
最小要素と最大要素のデフォルト値を別々に指定することもできます。
@c COMMON
@end deffn

@deffn {Generic function} filter pred coll
@c EN
Returns a list of elements of collection @var{coll} that satisfies
the predicate @var{pred}.   If the collection is a sequence,
the order is preserved in the result.
@c JP
コレクション@var{coll}中の要素のうち、述語手続き@var{pred}が真の値を返したものの
リストを返します。コレクションがシーケンスであれば、結果の要素の順序は元のシーケンスの
順序と同じになります。
@c COMMON

@example
(filter char-upper-case? "Hello, World")
  @result{} (#\H #\W)
(filter even? '#(1 2 3 4)) @result{} (2 4)
@end example
@end deffn

@deffn {Generic function} filter-to class pred coll
@c EN
Same as @code{filter}, but the result is returned 
as a collection of class @var{class}.
@c JP
@code{filter}と同じですが、結果のコレクションが@var{class}のインスタンスで
返されます。
@c COMMON

@example
(filter-to <vector> even? '#(1 2 3 4)) @result{} #(2 4)
(filter-to <string> char-upper-case? "Hello, World") 
  @result{} "HW"
@end example
@end deffn

@deffn {Generic function} remove pred coll
@c EN
Returns a list of elements of collection @var{coll} that does not
satisfy the predicate @var{pred}.   If the collection is a sequence,
the order is preserved in the result.
@c JP
コレクション@var{coll}中の要素のうち、述語手続き@var{pred}が偽の値を返したものの
リストを返します。コレクションがシーケンスであれば、結果の要素の順序は元のシーケンスの
順序と同じになります。
@c COMMON

@example
(remove char-upper-case? "Hello, World")
  @result{} (#\e #\l #\l #\o #\, #\space #\o #\r #\l #\d)
(remove even? '#(1 2 3 4)) @result{} (1 3)
@end example
@end deffn

@deffn {Generic function} remove-to class pred coll
@c EN
Same as @code{remove}, but the result is returned 
as a collection of class @var{class}.
@c JP
@code{remove}と同じですが、結果のコレクションが@var{class}のインスタンスで
返されます。
@c COMMON

@example
(remove-to <vector> even? '#(1 2 3 4)) @result{} #(1 3)
(remove-to <string> char-upper-case? "Hello, World") 
  @result{} "ello, orld"
@end example
@end deffn

@deffn {Generic function} partition pred coll
@c EN
Does @code{filter} and @code{remove} the same time.
Returns two lists, the first consists of elements of the collection
@var{coll} that satisfies the predicate @var{pred}, and the second
consists of elements that doesn't.
@c JP
@code{filter}と@code{remove}を同時に行います。
二つのリストを返します。最初のリストはコレクション@var{coll}の要素のうち
述語手続き@var{pred}が真の値を返したものから構成され、二つ目のリストは
そうでない要素から構成されます。
@c COMMON

@example
(partition char-upper-case? "PuPu")
  @result{} (#\P #\P) @r{and} (#\u #\u)
(partition even? '#(1 2 3 4))
  @result{} (2 4) @r{and} (1 3)
@end example
@end deffn

@deffn {Generic function} partition-to class pred coll
@c EN
Same as @code{partition}, except the results are returned
in the collections of class @var{class}.
@c JP
@code{partition}と同じですが、結果がクラス@var{class}のコレクションとして
返されます。
@c COMMON

@example
(partition-to <string> char-upper-case? "PuPu")
  @result{} "PP" @r{and} "uu"
(partition-to <vector> even? '#(1 2 3 4))
  @result{} #(2 4) @r{and} #(1 3)
@end example
@end deffn

@deffn {Generic function} group-collection coll :key key test
@c EN
Generalized @code{partition}.  Groups elements in @var{coll}
into those who has the same key value, and returns the groups as
of lists.  Key values are calculated by applying the procedure @var{key}
to each element of @var{coll}.  The default value of @var{key} is
@code{identity}.   For each element of @var{coll}, @var{key} is applied
exactly once.
The equal-ness of keys are compared by
@var{test} procedure, whose default is @code{eqv?}.
@c JP
@code{partition}を汎化したものです。@var{coll}内の要素を同じキーを
持つ値同士でグループ化し、リストのリストにして返します。
キーの値は要素に手続き@var{key}を適用することで得られます。@var{key}の
デフォルト値は@code{identity}です。@var{coll}の各要素に対して、
@var{key}は正確に一回だけ呼ばれます。
キーの等価性判定には手続き@var{test}が使われます。デフォルト値は@code{eqv?}です。
@c COMMON

@c EN
If @var{coll} is a sequence, then the order of elements in each group
of the result is the same order in @var{coll}.
@c JP
@var{coll}がシーケンスである場合、結果の各グループに含まれる要素の順は
もとのシーケンス内での順と同じになります。
@c COMMON

@example
(group-collection '(1 2 3 2 3 1 2 1 2 3 2 3))
  @result{} ((1 1 1) (2 2 2 2 2) (3 3 3 3))

(group-collection '(1 2 3 2 3 1 2 1 2 3 2 3) :key odd?)
  @result{} ((1 3 3 1 1 3 3) (2 2 2 2 2))

(group-collection '(("a" 2) ("b" 5) ("c" 1) ("b" 3) ("a" 6))
  :key car :test string=?)
  @result{} ((("a" 2) ("a" 6)) (("b" 5) ("b" 3)) (("c" 1)))
@end example

@c EN
See also @code{group-sequence} in @code{gauche.sequence}
(@xref{Other operations over sequences}),
which only groups adjacent elements.
@c JP
@code{gauche.sequence}の@code{group-sequence}も参照して下さい
(@ref{Other operations over sequences}参照)。
隣り合う要素同士でグループ化するものです。
@c COMMON
@end deffn


@node Miscellaneous operations on collection, Fundamental iterator creators, Selection and searching in collection, Collection framework
@subsection Miscellaneous operations on collection
@c NODE コレクションに対する様々な操作

@deffn {Generic function} size-of coll
@c EN
Returns the number of elements in the collection.  Default method iterates over
the collection to calculate the size, which is not very efficient
and may diverge if the collection is infinite.
Some collection classes overload the method for faster calculation.
@c JP
コレクションの要素数を返します。
デフォルトのメソッドは、コレクション中の要素をすべて数え上げるものですが、
あまり効率は良くないでしょう。また、無限個の要素を持つコレクションでは
帰ってきません。多くのコレクションクラスはより効率の良い方法でこのメソッドを定義しています。
@c COMMON
@end deffn

@deffn {Generic function} lazy-size-of coll
@c EN
Returns either the size of the collection, or a promise to
calculate it.  The intent of this method is to avoid
size calculation if it is expensive.  In some cases, the caller
wants to have size just for optimization, and it is not desirable
to spend time to calculate the size.  Such caller uses this method
and just discards the information if it is a promise.
@c JP
コレクションの要素数か、もしくはそれを計算するプロミスを返します。
このメソッドの目的は、要素数の計算が高価な場合にそれを避けることにあります。
しばしば、呼び出し側では最適化のための参考値として要素数が欲しい場合があり、
そういった場合は要素数を計算するために時間を費すのは望ましくありません。
このメソッドを代わりに呼び出して、結果がプロミスであればそれを使わない、
という選択ができます。
@c COMMON
@end deffn

@deffn {Generic function} coerce-to class coll
@c EN
Convert a collection @var{coll} to another collection
which is an instance of @var{class}.
If @var{coll} is a sequence and @var{class} is a sequence class,
the order is preserved.
@c JP
コレクション@var{coll}を、クラス@var{class}のインスタンスである
別のコレクションへと変換します。@var{coll}がシーケンスであり、
@var{class}がシーケンスクラスであれば、元のシーケンスの順序は保存されます。
@c COMMON

@example
(coerce-to <vector> '(1 2 3 4))
  @result{} #(1 2 3 4)

(coerce-to <string> '#(#\a #\b #\c))
  @result{} "abc"
@end example
@end deffn

@node Fundamental iterator creators, Implementing collections, Miscellaneous operations on collection, Collection framework
@subsection Fundamental iterator creators
@c NODE 基礎的なイテレータ構築メソッド

@c EN
These are fundamental methods on which all the rest of
iterative method are built.  The method interface is not intended
to be called from general code, but suitable for building
other iterator construct.   The reason why I chose this interface
as fundamental methods are explained at the bottom of this subsection.
@c JP
ここに挙げるメソッドは、他のコレクションメソッドの基礎となるものです。
メソッドのインタフェースは一般のコードで使われることよりも、
効率良く他の繰り返しメソッドを記述するのに便利なように設計されています。
何故このインタフェースを基礎のメソッドとして選んだかについてはこの章の最後に説明します。
@c COMMON

@deffn {Generic function} call-with-iterator collection proc :key start
@c EN
A fundamental iterator creator.   This creates two procedures
from @var{collection}, both take no argument, and then call
@var{proc} with those two procedures.   The first procedure is
terminate predicate, which returns @code{#t} if the iteration
is exhausted, or @code{#f} if there are still elements to be visited.
The second procedure is an incrementer,
which returns one element from the collection and sets the
internal pointer to the next element.
The behavior is undefined if you call the incrementer after
the terminate predicate returns @code{#t}.
@c JP
基礎となるイテレータ構築メソッドです。このメソッドはコレクション@var{collection}
から繰り返しのための二つの手続きを作成し、それらを引数として手続き@var{proc}を
呼びます。作られる最初の手続きは終了判定手続きで、引数無しで呼び出され、繰り返しが
終了していれば@code{#t}を、まだ要素が残っていれば@code{#f}を返します。
作られる二番目の手続きはインクリメント手続きで、呼ばれる度に現在の要素を返し、
内部のポインタを次の要素へと進めます。終了判定手続きが@code{#t}を返した後に
インクリメント手続きを呼んだ場合の動作は未定義です。
@c COMMON

@c EN
If the collection is actually a sequence, the incrementer is guaranteed
to return elements in order, from 0-th element to the last element.
If a keyword argument @var{start} is given, however, the iteration
begins from @var{start}-th element and ends at the last element.
If the collection is not a sequence, the iteration order is
arbtrary, and @var{start} argument has no effect.
@c JP
コレクションがシーケンスでもある場合、インクリメント手続きはシーケンスの順番に要素を取り出します。
キーワード引数@var{start}が与えられていればイテレーションの範囲は
@var{start}番目の要素から最後の要素までとなります。シーケンスでないコレクションに
対しては@var{start}引数は意味を持ちません。
@c COMMON

@c EN
An implementation of @var{call-with-iterator} method may
limit the extent of the iterator inside the dynamic scope of the method.
For example, it allocates some resource (e.g. connect to a database)
before calling @var{proc}, and deallocates it (e.g. disconnect from a database)
after @var{proc} returns.
@c JP
@var{call-with-iterator}のメソッド実装は、イテレータのエクステントを
そのメソッドのダイナミックスコープ内に限ることを許されます。例えば、
メソッドは@var{proc}を呼ぶ前に何らかのリソースを確保し(データベースへのコネクションなど)、
@var{proc}から戻った後でそれを解放するということができます。
@c COMMON

@c EN
This method returns the value(s) @var{proc} returns.
@c JP
このメソッドは @var{proc} が返した値をそのまま返します。
@c COMMON

@example
(call-with-iterator '(1 2 3 4 5)
  (lambda (end? next)
    (do ((odd-nums 0))
        ((end?) odd-nums)
      (when (odd? (next)) (inc! odd-nums)))))
 @result{} 3
@end example

@c EN
See also @code{with-iterator} macro below, for it is easier to use.
@c JP
下に示す@code{with-iterator}マクロも参照してください。
@c COMMON
@end deffn

@deffn {Macro} with-iterator (collection end? next args @dots{}) body @dots{}
@c EN
A convenience macro to call @code{call-with-iterator}.
@c JP
@code{call-with-iterator}を簡潔に呼び出すマクロです。
@c COMMON
@example
(with-iterator (coll end? next args @dots{}) body @dots{})
 @equiv{}
(call-with-iterator coll
  (lambda (end? next) body @dots{})
   args @dots{})
@end example
@end deffn

@defun call-with-iterators collections proc
@c EN
A helper function to write n-ary iterator method.
This function applies @code{call-with-iterator} for each @var{collection}s,
and makes two lists, the first consists of terminate predicates
and the second of incrementers.  Then @var{proc} is called
with those two lists.  Returns whatever @var{proc} returns.
@c JP
N-aryのイテレータメソッドを書くのに便利な手続きです。
この手続きはコレクションのリスト@var{collections}の各コレクションに対して
@code{call-with-iterator}を呼び、二つのリストを作ります。最初のリストには
終了判定手続きが順に集められており、二つ目のリストにはインクリメント手続きが
順に集められています。そして、これらのリストを引数として@var{proc}を呼び出します。
@var{proc}が返した値を返します。
@c COMMON
@end defun

@deffn {Generic function} call-with-builder collection-class proc :key size
@c EN
A fundamental builder creator.  Builder is a way to construct
a collection incrementally.  Not all collection classes provide
this method.
@c JP
基礎的なビルダー構築メソッドです。ビルダーはコレクションをインクリメンタルに
作成する方法です。コレクションクラスによってはこの手続きを提供しないものもあります。
@c COMMON

@c EN
@var{Collection-class} is a class of the collection to be built.
This method creates two procedures, adder and getter, then calls
@var{proc} with those procedures.
Adder procedure takes one argument and adds it to the collection
being built.  Getter takes no argument and returns a built collection object.
The effect is undefined if adder is called after getter is called.
@c JP
@var{Collection-class}は作成されるコレクションのクラスです。
このメソッドは、追加手続きと結果手続きの二つの手続きを作成し、それらを
引数として@var{proc}を呼びます。追加手続きは一つ引数を取り、それを作成中の
コレクションに追加します。結果手続きは引数を取らず、作成されたコレクションを返します。
結果手続きが呼ばれた後で追加手続きを呼んだ場合の動作は未定義です。
@c COMMON

@c EN
A keyword argument @var{size} may be specified if the size of
the result collection is known.  Certain collections may be
built much more efficiently if the size is known; other collections
may just ignore it.   The behavior is undefined if more than
@var{size} elements are added, or the collection is retrieved before
@var{size} elements are accumulated.
@c JP
作られるコレクションのサイズが分かっている場合、キーワード引数@var{size}を与える
ことができます。コレクションクラスによってはその情報を使って効率的にコレクションを
作成することができます。その情報を単に無視するコレクションクラスもあります。
@var{size}個より多くの要素が追加されたり、@var{size}個の要素が追加される前に
結果手続きが呼ばれたりした場合の動作は未定義です。
@c COMMON

@c EN
If the collection class is actually a sequence class,
adder is guaranteed to add elements in order.  Otherwise,
the order of elements are insignificant.
@c JP
コレクションクラスがシーケンスクラスであった場合、追加手続きは要素を
シーケンスの順に追加してゆきます。
@c COMMON

@c EN
Some collection class may take more keyword arguments to
initialize the collection.
@c JP
コレクションクラスによっては、コレクションオブジェクトの初期化のために
他のキーワード引数を取るかもしれません。
@c COMMON

@c EN
This method returns the value(s) @var{proc} returned.
@c JP
このメソッドは@var{proc}が返す値を返します。
@c COMMON

@example
(call-with-builder <list>
  (lambda (add! get)
    (add! 'a) (add! 'b) (add! 'c) (get)))
 @result{} (a b c)

(call-with-builder <vector>
  (lambda (add! get)
    (add! 'a) (add! 'b) (add! 'c) (get)))
 @result{} #(a b c)
@end example

@c EN
See also @code{with-builder} macro below, for it is much easier to use.
@c JP
下に示す@code{with-builder}マクロも参照してください。
@c COMMON
@end deffn

@deffn {Macro} with-builder (collection add! get args @dots{}) body @dots{}
@c EN
A convenience macro to call @code{call-with-builder}.
@c JP
@code{call-with-builder}を簡潔に呼び出すマクロです。
@c COMMON
@example
(with-builder (coll add! get args @dots{}) body @dots{})
 @equiv{}
(call-with-builder coll
  (lambda (add! get) body @dots{})
  args @dots{})
@end example
@end deffn

@emph{Discussion}:
@c EN
Other iterator methods are built on top of call-with-iterator and
call-with-builder.
By implementing those methods, you can easily adapt your own collection
class to all of those iterative
operations.   Optionally you can overload some of higher-level
methods for efficiency.
@c JP
他のイテレータメソッドは全てこのcall-with-iteratorとcall-with-builderの上に構築可能です。
最低限これらのメソッドを定義すれば、そのクラスはコレクションとして振舞うことができます。
もちろん最適化のために他のイテレータメソッドを定義しても構いませんが。
@c COMMON

@c EN
It is debatable that which set of operations should be primitives.
I chose call-with-iterator style for efficiency of the applications
I see most.   The following is a discussion of other possible
primitive iterators.
@c JP
どの操作を基礎的なメソッドとするかには議論の余地があります。
Gaucheでは、作者がよく見るパターンで最も効率が良くなるように考えて現在のスタイルを
選びました。以下に、他の基礎的なメソッドの可能性を検討します。
@c COMMON

@table @asis
@item @code{fold}
@c EN
It is possible to make @code{fold} a primitive method, and
build other iterator method on top of it.
Collection-specific iterating states can be kept in the
stack of @code{fold}, thus it runs efficiently.  The method
to optimize a procedure that uses @code{fold} as a basic
iterator construct.
However, it is rather cumbersome to derive
generator-style interface from it.   It is also tricky
to iterate irregularly over more than one collections.
@c JP
@code{fold}を最も基礎的なメソッドとして、他のイテレータメソッドをその上に
構築することも可能です。繰り返しの状態はスタックに置かれるので効率良く走ります。
@code{fold}を基礎とした繰り返し関数を最適化する方法は良く知られています。
しかし、@code{fold}を元にしてジェネレータスタイルのインタフェースを
作成するのは複雑です。また、複数のコレクションに対しての繰り返しを書くのも
面倒です。
@c COMMON

@item CPS
@c EN
Passes iteratee the continuation procedure that continues
the iteration.   The iteratee just returns when it want
to terminate the iteration.
It has resource management problem described in
Oleg Kiselyov's article (@ref{oleg2,,OLEG2}).
@c JP
繰り返しの中身の手続きに対し、繰り返しを続けるための継続手続きを渡す方法です。
繰り返しを続けたくなければ、手続きは継続を呼ばすにそのまま戻ります。
Oleg Kiselyovの記事(@ref{oleg2,,OLEG2})に指摘されているような、
リソース管理の問題があります。
@c COMMON

@item Iterator object
@c EN
Like C++ iterator or Common Lisp generator.
Easy to write loop.   The problem is that every call of
checking termination or getting next element must be dispatched.
@c JP
C++のイテレータやCommon Lispのジェネレータのようなオブジェクトを使う方法です。
ループを書くのは容易ですが、終了判定や要素取り出しの度にメソッドディスパッチが
起こってしまいます。
@c COMMON

@item Series
@c EN
Common Lisp's series can be very efficient if the compiler can statically
analyze the usage of series.  Unfortunately it is not the case in
Gauche.  Even if it could, the extension mechanism doesn't blend well
with Gauche's object system.
@c JP
Common Lispのシリーズはコンパイラがシリーズの使われかたを追跡できれば
非常に効率の良いコードに変換できます。Gaucheのコンパイラはそこまでのデータフロー解析を
行っていません。また、それをやったとしても、コレクションクラスを拡張するための方法が
Gaucheのオブジェクトシステムとはうまく調和しません。
@c COMMON

@item Macros
@c EN
Iterator can be implemented as macros, and that will be very efficient;
e.g. Scheme48's iterator macro.  It uses macros to extend, however,
and that doesn't blend well with Gauche's object system.
@c JP
効率を気にするなら、イテレータをマクロで書いてしまう方法もあります
(例えばScheme48の@code{iterator}マクロなど)。
効率は良いのですが、拡張するにはマクロを書くことが必要となり、
Gaucheのオブジェクトシステムとうまく調和しません。
@c COMMON
@end table

@c EN
The current implementation is close to the iterator object approach,
but using closures instead of iterator objects so that avoiding
dispatching in the inner loop.  Also it allows the iterator
implementator to take care of the resource problem.
@c JP
現在の実装はイテレータオブジェクトアプローチに近いですが、イテレータオブジェクトを
作る代わりにクロージャを使うことで内部のループでのメソッドディスパッチを
避けています。また、現在のインタフェースはリソース管理の問題を解決しています。
@c COMMON

@node Implementing collections,  , Fundamental iterator creators, Collection framework
@subsection Implementing collections
@c NODE コレクションの実装

@c EN
The minimum requirements of the collection class implementation
is as follow:
@itemize @bullet
@item
The class inherits @code{<collection>} abstract class.
@item
A method @code{call-with-iterator} is implemented.
@end itemize

This makes iterator methods such as @code{map}, @code{for-each},
@code{find} and @code{filter} to work.
@c JP
コレクションクラスの実装に最低限要求されるものには、以下のものがあります。
@itemize @bullet
@item
抽象クラス@code{<collection>}を継承している。
@item
メソッド@code{call-with-iterator}が実装されている。
@end itemize

これにより、@code{map}、@code{for-each}、@code{find}、@code{filter}などの
イテレータメソッドが動作するようになります。
@c COMMON

@c EN
In order to make the constructive methods (e.g. @code{map-to} to
create your collection), you have to implement @code{call-with-builder}
method as well.  Note that @code{call-with-builder} method must work
a sort of class method, dispatched by class, rather than normal method
dispatched by instance.   In Gauche, you can implement it by using a
metaclass.   Then the minimal code will look like this:
@c JP
建設的なメソッド(例えば、コレクションを作るための@code{map-to}など)を
作るためには、メソッド@code{call-with-builder}も実装しなければなりません。
メソッド@code{call-with-builder}は、クラスによりディスパッチされるクラスメソッドの
一種で、インスタンスによりディスパッチされる通常のメソッドとは異なります。
Gaucheでは、これはメタクラスを使うことによって実装できます。
最小限のコードは次のようになります。
@c COMMON

@example
(define-class <your-collection-meta> (<class>) ())

(define-class <your-collection> (<collection>)
 (...) ;; @r{slots}
 :metaclass <your-collection-meta>)

(define-method call-with-iterator
    ((coll <your-collection>) proc . options)
  @dots{}
  )

(define-method call-with-builder
     ((coll <your-collection-meta>) proc . options)
  @dots{}
  )
@end example

@c EN
Optionally, you can overload other generic functions to optimize
performance.
@c JP
パフォーマンスの最適化のために、他のジェネリック関数をオーバロードすることも
できます。
@c COMMON

@c ----------------------------------------------------------------------
@node Configuration parameters, Dictionary framework, Collection framework, Library modules - Gauche extensions
@section @code{gauche.config} - Configuration parameters
@c NODE コンフィグレーション情報, @code{gauche.config} - コンフィグレーション情報

@deftp {Module} gauche.config
@mdindex gauche.config
@c EN
This module allows the Scheme program to access the configuration information
the same as you can get from the @code{gauche-config} program.
@c JP
このモジュールは、@code{gauche-config} プログラム経由で得られるのと
同等の情報をSchemeプログラムから取得すること可能にします。
@c COMMON
@end deftp

@defun gauche-config option
@c EN
Returns the configured value of the @var{option}.

See the manpage of @code{gauche-config}, or run @code{gauche-config}
without any argument from the shell, to find out the valid options.
@c JP
@var{option}に対応するコンフィグレーション値を返します。

有効なオプションについては、@code{gauche-config} のマニュアルページを
見るか、シェルで @code{gauche-config} を引数なしで実行して下さい。
@c COMMON
@example
(gauche-config "--cc")
  @result{} "gcc"
(gauche-config "-L")
  @result{} "-L/usr/lib/gauche/0.6.5/i686-pc-linux-gnu"
(gauche-config "-l")
  @result{} "-ldl -lcrypt -lm -lpthread"
@end example
@end defun

@c ----------------------------------------------------------------------
@node Dictionary framework, Low-level file operations, Configuration parameters, Library modules - Gauche extensions
@section @code{gauche.dictionary} - Dictionary framework
@c NODE @code{gauche.dictionary} - ディクショナリフレームワーク

@deftp {Module} gauche.dictionary
@mdindex gauche.dictionary
@c EN
A dictionary is an abstract class for objects that can
map a key to a value.  This module provides some useful generic
functions for dictionaries, plus generic dictionary classes
built on top of other dictionary classes.
@c JP
ディクショナリはキーから値への写像ができるオブジェクトを表わす抽象クラ
スです。このモジュールではディクショナリに対してよく使うジェネリック関数、
および他のディクショナリクラスの上に構築される汎用的なディクショナリクラスを
提供します。
@c COMMON
@end deftp

@menu
* Generic functions for dictionaries::  
* Generic dictionaries::        
@end menu

@node Generic functions for dictionaries, Generic dictionaries, Dictionary framework, Dictionary framework
@subsection Generic functions for dictionaries
@c NODE ディクショナリのためのジェネリック関数

These generic functions are useful to implement algorithms
common to any dictionary-like objects.
Among built-in classes, @code{<hash-table>} and @code{<tree-map>}
implement the dictionary interface.  All the @code{<dbm>} classes
provided by @code{dbm} module also implement it.

To make your own class implement the dictionary interface, you have
to provide at least @code{dict-get}, @code{dict-put!}, @code{dict-exists?},
@code{dict-delete!} and @code{dict-fold}.   Other generic functions
have default behavior built on top of these.  Of course your can
implement other methods as well, potentially to gain better performance.

@deffn {Generic function} dict-get (dict @code{<dictionary>}) key :optional default
Returns the value corresponding to the @var{key}.  
If the dictionary doesn't have an entry with @var{key},
returns @var{default} when it is provided, or raises an error
if not.
@end deffn

@deffn {Generic function} dict-put! (dict @code{<dictionary>}) key value
Puts the mapping from @var{key} to @var{value} into the dictionary.
@end deffn

@deffn {Generic function} {(setter dict-get)} (dict @code{<dictionary>}) key value
This works the same as @code{dict-put!}.
@end deffn

@deffn {Generic function} dict-exists? (dict @code{<dictionary>}) key
Returns @code{#t} if the dictionary has an entry with @var{key},
@code{#f} if not.
@end deffn

@deffn {Generic function} dict-delete! (dict @code{<dictionary>}) key
Removes an entry with @var{key} form the dictionary.
If the dictionary doesn't have such an entry, this function is noop.
@end deffn

@deffn {Generic function} dict-fold (dict @code{<dictionary>}) proc seed
@c EN
Calls a procedure @var{proc} over each entry in a dictionary @var{dict},
passing a seed value.  Three arguments are given to @var{proc}; 
an entry's key, an entry's value, and a seed value.  Initial
seed value is @var{seed}.  The value returned from @var{proc} is used
for the seed value of the next call of @var{proc}.  The result of the
last call of @var{proc} is returned from @var{dict-fold}.
@c JP
@var{dict}の各要素に対して@var{proc}を呼びシード値を次に渡します。
@var{proc}は引数を3つとります。エントリーのキー、エントリーの値、それ
にシード値です。最初のシード値は@var{seed}です。@var{proc}からの返り値
は次の@var{proc}の呼び出しでシード値として使われます。最後の@var{proc}
の呼び出しの結果が@var{dict-fold}の返り値として返されます。
@c COMMON

@c EN
If @var{dict} is @code{<ordered-dictionary>}, @var{proc} is called
in the way to keep the following associative order, where
the key is ordered from @var{K0} (minimum) to @var{Kn} (maximum), and
the corresponding values is from @var{V0} to @var{Vn}:
@c JP
@var{dict}が@code{<ordered-dictionary>}であれば、@var{proc}は以下のよ
うな結合で呼ばれます。ここで、キーは@var{K0}(最小)から@var{Kn}(最大)ま
でで、それに対応する値が@var{V0}から@var{Vn}までであるとします。
@c COMMON
@example
(proc Kn Vn (proc Kn-1 Vn-1 ... (proc K0 V0 seed)))
@end example
@end deffn

@deffn {Generic function} dict-fold-right (dict @code{<ordered-dictionary>}) proc seed
@c EN
Like @code{dict-fold}, but the associative order of applying @var{proc}
is reversed as follows:
@c JP
@code{dict-fold}と同じですが、@var{proc}を適用する結合の順が以下のよう
に逆になります。
@c COMMON
@example
(proc K0 V0 (proc K1 V1 ... (proc Kn Vn seed)))
@end example

@c EN
This generic function is only defined on @code{<ordered-dictionary>}.
@c JP
このジェネリック関数は@code{<ordered-dictionary>}上にのみ定義されてい
ます。
@c COMMON
@end deffn

@deffn {Generic function} dict-for-each (dict @code{<dictionary>}) proc
@c EN
Calls @var{proc} with a key and a value of every entry in
the dictionary @var{dict}.  For ordered dictionaries, @var{proc}
is guaranteed to be called in the increasing order of keys.
@c JP
ディクショナリ@var{dict}の各エントリーのキーと値に対して@var{proc}を呼
びます。順序付きディクショナリに対しては@var{proc}がキーの昇順に呼ばれ
ることが保証されています。
@c COMMON
@end deffn

@deffn {Generic function} dict-map (dict @code{<dictionary>}) proc
@c EN
Calls @var{proc} with a key and a value of every entry in
the dictionary @var{dict}, and gathers the result into a list 
and returns it.  For ordered dictionaries, the result is in
the increasing order of keys (it doesn't necessarily mean @var{proc}
is called in that order).
@c JP
ディクショナリ@var{dict}の各エントリーのキーと値に対して@var{proc}を呼
び、結果をリストにまとめて返します。順序付きディクショナリに対しては結
果が最初のキーの順にならびます(が、@var{proc}がキーの昇順に呼ばれるこ
とを保証するものではありません)。 
@c COMMON
@end deffn

@deffn {Generic function} dict-keys (dict @code{<dictionary>})
@deffnx {Generic function} dict-values (dict @code{<dictionary>})
@c EN
Returns a list of all keys or values of a dictionary @var{dict}, 
respectively.  For ordered dictionaries, the returned list is
in the increasing order of keys.
@c JP
それぞれ@var{dict}内にあるすべてのキーのリスト、すべての値のリストを返
します。順序付きディクショナリについてはリストの要素はキーの昇順になら
んでいます。
@c COMMON
@end deffn

@node Generic dictionaries,  , Generic functions for dictionaries, Dictionary framework
@subsection Generic dictionaries
@c NODE 汎用ディクショナリ

@deftp {Class} <bimap> 
Provides a bidirectional map (@emph{bimap}), a relation between two
set of values, of which you can lookup both ways.

Internally, a bimap consists of two dictionaries, @emph{left} map
and @emph{right} map.  Think a bimap as a relation between @var{x}s
and @var{y}s.  The left map takes an @var{x} as a key and returns
corresponding @var{y} as its value.  The right map takes an @var{y}
as a key and returns corresponding @var{x} as its value.

Currently, @code{<bimap>} only supports strict one-to-one mapping.
Mutating interface (@code{bimap-*-put!}, @code{bimap-*-delete!} etc)
modifies both left and right maps to maintain this one-to-one mapping.
(In future, we may provide an option to make many-to-one and
many-to-many mappings).

A bimap can be used as a dictionary, with the generic dictionary
functions such as @code{dict-get}.  In such cases, the left map takes
precedence; that is, the key given to @code{dict-get} etc. is 
regarded as the key to the left map.
@end deftp

@defun make-bimap left-map right-map
Creates a new bimap consists of two dictionaries, @var{left-map}
and @var{right-map}.   It is the caller's responsibility to
choose appropriate type of dictionaries; for example, if you want
to create a relation between a string and a number, you man want
to create it like this:

@example
(make-bimap (make-hash-table 'string=?)  ; string -> number
            (make-hash-table 'eqv?))     ; number -> string
@end example
@end defun

@defun bimap-left bimap
@defunx bimap-right bimap
Returns the left or right map of @var{bimap}, respectively.
Do not mutate the returned map, or you'll break
the consistency of the bimap.
@end defun

@defun bimap-left-get bimap key :optional default
@defunx bimap-right-get bimap key :optional default
Lookup the value corresponding to the @var{key} in the left or right
map of @var{bimap}.   If no entry is found for @var{key}, 
@var{default} is returned if provided, otherwise an error is
raised.
@end defun

@defun bimap-left-exists? bimap key
@defunx bimap-right-exists? bimap key
Returns @code{#f} if the left or right map of @var{bimap} has an entry of
the key, @code{#t} otherwise.
@end defun

@defun bimap-put! bimap x y &key (on-conflict :supersede)
Put a relation (@var{x}, @var{y}) into the bimap.
After this, @code{(bimap-left-get @var{x})} will return @var{y},
and @code{(bimap-left-get @var{y})} will return @var{x}.

If there's already a relation (@var{x}, _) and/or (_, @var{y}),
the behavior depends on the value of the keyword argument @var{on-conflit}.

@table @code
@item :supersede
This is the default behavior.  Duplicate relations are silently
removed in order to maintain one-to-one mapping.  For example,
suppose a bimap between strings and numbers has had
@code{("foo", 1)} and @code{("bar", 2)}.  When you try to
put @code{("bar", 2)} with this option, the first two entries
are removed.  Returns @code{#t}.

@item :error
Raises an error when duplicate relations are found.

@item #f
When duplicate relations are found, does nothing and returns @code{#f}.
@end table

@end defun

@defun bimap-left-delete! bimap key
@defunx bimap-right-delete! bimap key
Deletes an relation with the given left key or right key from @var{bimap}.
Both left and right maps are modified so that the consistency is maintained.
If there's no relations with given key, these are noop.
@end defun

@c ----------------------------------------------------------------------
@node Low-level file operations, Hooks, Dictionary framework, Library modules - Gauche extensions
@section @code{gauche.fcntl} - Low-level file operations
@c NODE 低レベルファイル操作, @code{gauche.fcntl} - 低レベルファイル操作

@deftp {Module} gauche.fcntl
@mdindex gauche.fcntl
@c EN
Provides an interface to @code{fcntl(2)}, including
advisory file locking.
@c JP
アドバイザリ・ファイルロックを含む、
@code{fcntl(2)}へのインタフェースを提供します。
@c COMMON
@end deftp

@defun sys-fcntl port-or-fd operation :optional arg
@c EN
Performs certain operation on the file specified by @var{port-or-fd},
which should be a port object or an integer
that specifies a system file descriptor.  If it is a port, it must
be associated to the opened file (i.e. @code{port-type}
returns @code{file}, see @ref{Common port operations}).

The operation is specified by an integer @var{operation}.
Several variables are defined for valid @var{operation}.
@c JP
@var{port-or-fd} で指定されたファイルに対して特定の操作をおこないます。
ファイル指定は、ポートオブジェクトもしくはシステムのファイルディスクリプタ
である整数でなくてはなりません。それがポートである場合には、すでにオープン
されたファイルを結びついていなければなりません。
(@code{port-type} が @code{file} を返すようなポートということです。
@ref{Common port operations}参照。)

操作は整数 @var{operation} で指定します。
いくつかの変数が定義されいて、@var{operation} に使用できます。
@c COMMON

@table @code
@item F_GETFD
@vindex F_GETFD
@vindex FD_CLOEXEC
@c EN
Returns flags associated to the file descriptor of @var{port-or-fd}.
The optional argument @var{arg} is not used.   The return value is 
an integer whose definition is system specific, except one flag,
@code{FD_CLOEXEC}, which indicates the file descriptor should be
closed on @code{exec}.  See the manual entry of @code{fcntl(2)} of
your system for the details.
@c JP
@var{port-or-fd} のファイルディスクリプタに結びついているフラグを返します。
オプション引数の@var{arg}は使われません。返り値は整数で、その定義はシステム
によります。ただし、@code{FD_CLOEXEC}だけは例外で、これは@code{exec}で
クローズされたことを示しています。
詳しくはあなたのシステムの@code{fcntl(2)}のマニュアルエントリを
参照してください。
@c COMMON

@item F_SETFD
@vindex F_SETFD
@c EN
Sets the file descriptor flags given as @var{arg} to @var{port-or-fd}.
For example, the portable way of setting @code{FL_CLOEXEC} flag is
as follows:
@c JP
@var{port-or-fd}のファイルディスクリプタのフラグを与えられた@var{arg}に
します。たとえば、@code{FL_CLOEXEC}フラグを設定する、互換性のある方法では
次のようにします。
@c COMMON
@example
(sys-fcntl port F_SETFD
          (logior FD_CLOEXEC
                  (sys-fcntl port F_GETFD)))
@end example

@item F_GETFL
@vindex F_GETFL
@c EN
Returns flags associated to the open files specified by @var{port-or-fd}.
The flags includes the following information:
@c JP
@var{port-or-fd}によって指定されたオープンしたファイルに結びついている
フラグを返します。このフラグには以下のような情報が含まれています。
@c COMMON

@itemize @bullet
@item
@vindex O_ACCMODE
@vindex O_RDONLY
@vindex O_WRONLY
@vindex O_RDWR
@c EN
File access mode.  When masked by @code{O_ACCMODE}, 
it's either one of @code{O_RDONLY}, @code{O_WRONLY} or @code{O_RDWR}.
@c JP
ファイルのアクセスモード。@code{O_ACCMODE} でマスクしたとき、
これは、@code{O_RDONLY}、@code{O_WRONLY}、@code{O_RDWR}のうちどれかひとつです。
@c COMMON
@item
@vindex O_CREAT
@vindex O_EXCL
@vindex O_TRUNC
@c EN
File creation options.  @code{O_CREAT}, @code{O_EXCL} and/or
@c JP
ファイルの作成オプション。@code{O_CREAT}、@code{O_EXCL}のどちらか、または両方。
@c COMMON
@code{O_TRUNC}.
@item
@vindex O_APPEND
@c EN
Whether appending is allowed or not, by @code{O_APPEND}
@c JP
@code{O_APPEND}でマスクしたとき、追記が許されているかどうか。
@c COMMON
@item
@vindex O_NONBLOCK
@c EN
Whether I/O is blocking or non-blocking, by @code{O_NONBLOCK}.
@c JP
@code{O_NONBLOCK}でマスクしたとき、I/O が非ブロックモードかブロックモードか。
@c COMMON
@item
@vindex O_NOCTTY
@c EN
Whether it grabs terminal control, by @code{O_NOCTTY}.
@c JP
@code{O_NOCTTY}でマスクしたとき、端末制御を切離しているかどうか。
@c COMMON
@end itemize

@c EN
The system may define system-specific flags.
@c JP
システムが、そのシステム特有のフラグを定義していることがあります。
@c COMMON

@item F_SETFL
@vindex F_SETFL
@c EN
Sets flags to the open files specified by @var{port-or-fd}.
Among the flags listed above, only @code{O_NONBLOCK} and @code{O_APPEND}
can be changed.

Note that @code{F_GETFD}/@code{F_SETFD} concern flags associated
to the file descriptor itself, while @code{F_GETFL}/@code{F_SETFL}
concern flags associated to the opened file itself.  This makes difference
when more than one file descriptor points to the same opened file.
@c JP
@var{port-or-fd}で指定したオープンされたファイルのフラグを設定します。
上に列挙されたフラグのうち、@code{O_NONBLOCK} と @code{O_APPEND} だけが
変更可能です。

@code{F_GETFD}/@code{F_SETFD} はファイルディスクリプタそのものに結びついた
フラグについてであり、一方、@code{F_GETFL}/@code{F_SETFL} はオープンされた
ファイルそのものに結びついているフラグについての操作であることに注意して
ください。この違いは、2つ以上のファイルディスクリプタが同じオープンされた
ファイルを指しているような場合にあらわれます。
@c COMMON

@item F_DUPFD
@vindex F_DUPFD
@c EN
Creates new file descriptor that points to the same file referred by
@var{port-or-fd}.
An integer must be provided as @var{arg}, and that specifies
the minimum value of file descriptor to be assigned.
@c JP
@var{port-or-fd}で参照しているのと同じファイルを指す新しいファイル
ディスクリプタを生成します。
@var{arg}で整数を与えなければなりません。この数は割り当てられる
ファイルディスクリプタの最小値を指定します。
@c COMMON

@item F_GETLK
@vindex F_GETLK
@c EN
The third argument must be provided and be an instance of @code{<sys-flock>}
object described below.  It searches the lock information specified by
@var{arg}, and modifies @var{arg} accordingly.
@c JP
3つめの引数を与えなければなりません。これは、以下に述べる@code{<sys-flock>}
オブジェクトのインスタンスでなければなりません。@var{arg}で指定された
ロック情報を検索し、それにしかるべく変更します。
@c COMMON

@item F_SETLK
@itemx F_SETLKW
@vindex F_SETLK
@vindex F_SETLKW
@c EN
The third argument must be provided and be an instance of @code{<sys-flock>}
object described below.  Sets the advisory file lock according to 
@var{arg}.   If the lock is successfully obtained, @code{#t} is returned.
If the other process has the lock conflicting the request,
@code{F_SETLK} returns @code{#f}, while @code{F_SETLKW} waits until
the lock is available.
@c JP
3つめの引数を与えなければなりません。これは、以下に述べる@code{<sys-flock>}
オブジェクトのインスタンスでなければなりません。@var{arg}にしたがって、
アドバイザリロックを設定します。ロックの取得に成功すれば、@code{#t}が
返ります。もし、別のプロセスがロックをもっていて要求したものと衝突した
場合には @code{F_SETLK} のときは @code{#f} を返します。一方、@code{F_SETLKW}
のときはロックが利用可能になるまで待ちます。
@c COMMON

@item F_GETOWN
@vindex F_GETOWN
@c EN
Returns the process id or process group that will receive
SIGIO and SIGURG signals for events on the file descriptor.
Process group is indicated by a negative value.
This flag is only available on the systems that has this 
feature (BSD and Linux have this).
@c JP
当該ファイルディスクリプタ上のイベント用シグナル、SIGIO および SIGURG を
受けとることになるプロセスのプロセスIDあるいはプロセスグループを返します。
プロセスグループは負の値で表示されます。このフラグはシステムにこのような
機能がある場合にのみ利用可能です(BSD や Linux にはこの機能があります)。
@c COMMON

@item F_SETOWN
@vindex F_SETOWN
@c EN
Sets the process id or process group that will receive SIGIO
and SIGURG signals for events on the file descriptor.
Process group is indicated by a negative value.
This flag is only available on the systems that has this 
feature (BSD and Linux have this).
Check out fcntl(2) manpage of your system for the details.
@c JP
当該ファイルディスクリプタ上のイベント用シグナル、SIGIO および SIGURG を
受けとることになるプロセスのプロセスIDあるいはプロセスグループを設定します。
プロセスグループは負の値で表示されます。このフラグはシステムにこのような
機能がある場合にのみ利用可能です(BSD や Linux にはこの機能があります)。
詳細については、お使いのシステムの fcntl(2) のマニュアルページをチェック
してください。
@c COMMON

@end table

@c EN
Other value for @var{operation} causes an error.
@c JP
これ以外の値を @var{operation} で指定しようとするとエラーになります。
@c COMMON
@end defun

@deftp {Builtin Class} <sys-flock>
@clindex sys-flock
@c EN
A structure represents POSIX advisory record locking.
Advisory record locking means the system may not prevents the process
from operating on files that it doesn't have an appropriate lock.
All the processes are expected to use @code{fcntl} to check locks
before it operates on the files that may be shared.

The following slots are defined.
@c JP
POSIX のアドバイザリレコードロックを表わす構造体です。アドバイザリレコードロック
というのは、適切なロックをもたないプロセスが対象ファイルを操作しても
システムは関知しない、ということです。すべてのプロセスが、共有される可能性
のあるファイルを操作する前にロックを@code{fcntl}を使って検査することが
期待されています。
@c COMMON

@c EN
Note that @code{fcntl} lock is per-process, per-file.  If you try
to lock the same file more than once within the same process, it always
succeeds.  But it's not a recursive lock, so the process loses
any locks to the file as soon as any of such lock is released,
or any of such file is closed.   It makes @code{fcntl} lock difficult
to use in libraries.  See @code{with-lock-file} (@xref{Lock files}) for
an alternative way to realize inter-process locks.
@c JP
@code{fcntl}によるロックは、プロセスごと、ファイルごとであることに注意してください。
同一プロセス内で同じファイルを複数回ロックすることはできますが、再帰ロックではないので
いずれかのロックがアンロックされるか、どこかでそのファイルがクローズされるかすると
プロセスはそのファイルに対するロックを失います。これは、@code{fcntl}ロックを
ライブラリで使うことを難しくします。プロセス間排他制御を実現する別の方法として
@code{with-lock-file} (@ref{Lock files}参照) があります。
@c COMMON

@defivar {<sys-flock>} type
@c EN
An integer represents lock type.  Following variables are predefined
for the valid values:
@c JP
ロックのタイプを表す整数です。利用可能な値として以下の変数があらかじめ
定義されています。
@c COMMON

@table @code
@item F_RDLCK
@vindex F_RDLCK
@c EN
Read locking
@c JP
読み込みのロック
@c COMMON
@item F_WRLCK
@vindex F_WRLCK
@c EN
Write locking
@c JP
書き込みのロック
@c COMMON
@item F_UNLCK
@vindex F_UNLCK

@c EN
To remove a lock by @code{F_SETLK}, or to indicate the record is not
locked by @code{F_GETLK}.
@c JP
@code{F_SETLK}によるロックを除去するか、あるいはレコードが@code{F_GETLK}
でロックされていないことを示す。
@c COMMON
@end table
@end defivar

@defivar {<sys-flock>} whence
@c EN
Indicates from where @code{start} is measured.
@c JP
@code{start}の計測が開始される位置を示す。
@c COMMON
@end defivar

@defivar {<sys-flock>} start
@c EN
The offset of beginning of the locked region.
@c JP
ロックされる領域の開始位置オフセット
@c COMMON
@end defivar

@defivar {<sys-flock>} len
@c EN
The number of bytes to lock.  Zero means ``until EOF''.
@c JP
ロックされるバイト数。ゼロは「EOFまで」という意味。
@c COMMON
@end defivar

@defivar {<sys-flock>} pid
@c EN
An integer process id that holding the lock; used only by @code{F_GETLK}.
@c JP
当該のロックをもっている整数のプロセスID。@code{F_GETLK}でのみ使用。
@c COMMON
@end defivar
@end deftp

@c ----------------------------------------------------------------------
@node Hooks, Interactive session, Low-level file operations, Library modules - Gauche extensions
@section @code{gauche.hook} - Hooks
@c NODE フック, @code{gauche.hook} - フック

@deftp {Module} gauche.hook
@mdindex gauche.hook
@c EN
Provides a hook object, which manages a list of closures to be
called at certain time.

This API of hooks are upper-compatible of Guile's, with the
following extensions.
@c JP
フックオブジェクトを提供します。これは、特定のタイミングで
呼び出されるクロージャのリストを管理するものです。

フックのAPIはGuileのそれと上方互換で、下記のように拡張されています。
@c COMMON
@itemize @bullet
@item
@c EN
Based on Gauche's object system.  Most APIs are methods
so you can extend the hook features.
@c JP
Gaucheのオブジェクトシステムをベースにしています。
ほとんどのAPIはメソッドなので、フックの機能を拡張することが
できます。
@c COMMON
@item
@c EN
Hook object itself is applicable.  You don't need to use @code{run-hook}.
@c JP
フックオブジェクトはそれ自身適用可能です。@code{run-hook}を使う必要は
ありません。
@c COMMON
@item
@c EN
The method to remove a procedure from a hook is called @code{delete-hook!},
for consistency with SRFI-1 and others.  @code{remove-hook!} is
defined as an alias of @code{delete-hook!} for compatibility with Guile.
@c JP
フックから手続きを削除するメソッドは、SRFI-1やその他との一貫性の
ために@code{delete-hook!}と呼ばれます。
Guileとの互換性のために、@code{remove-hook!}が@code{delete-hook!}の
エイリアスとして定義されています。
@c COMMON
@end itemize
@end deftp

@deftp {Class} <hook>
@clindex hook
@c EN
A hook class, which keeps a list of procedures to be called at once.

The @code{object-apply} method is defined on @code{<hook>} class,
so you can "apply" a hook object as if it were a procedure---which
causes all the registered procedure to be invoked.
@c JP
フックのクラスで、一度に呼び出される手続きのリストを保持しています。

@code{<hook>}クラスには@code{object-apply}メソッドが定義されているので、
あたかもそれが手続きであるかのようにフックオブジェクトを``適用''できます。
フックオブジェクトを適用すると、登録されている全ての手続きが呼び出されます。
@c COMMON
@end deftp

@defun make-hook :optional (arity 0)
@c EN
Creates a new hook object with given arity, which should be a
non-negative integer.
@c JP
与えられたアリティ(正の整数でなければなりません)とともに新しい
フックオブジェクトを作成します。
@c COMMON
@end defun

@defun hook? obj
@c EN
Returns true if @var{obj} is a hook object.
@c JP
@var{obj}がフックオブジェクトであれば、真を返します。
@c COMMON
@end defun

@defun hook-empty? hook
@c EN
Returns true if @var{hook}'s procedure list is empty.
@c JP
@var{hook}の手続きリストが空なら、真を返します。
@c COMMON
@end defun

@deffn {Method} add-hook! (hook <hook>) proc :optional (append? #f)
@c EN
Adds a procedure @var{proc} to @var{hook}.  If @var{append?}
is given and true, @var{proc} is added at the end of the list.
Otherwise, @var{proc} is added at the front of the list.
The @var{proc} has to be called with the arity given 
at the @code{make-hook}.
@c JP
手続き@var{proc}を@var{hook}に追加します。
@var{append?}が与えられ真であれば、@var{proc}はリストの最後に
追加されます。そうでなければ、@var{proc}はリストの最初に追加
されます。
@var{proc}は、@code{make-hook}時に与えられたアリティとともに
呼ばれなければなりません。
@c COMMON
@end deffn

@deffn {Method} delete-hook! (hook <hook>) proc
@deffnx {Method} remove-hook! (hook <hook>) proc
@c EN
Removes @var{proc} from the procedure list of @var{hook}.
@code{Remove-hook!} is an alias of @code{delete-hook!} just for
compatibility with Guile.
@c JP
@var{hook}の手続きリストから@var{proc}を削除します。
Guileとの互換性のためだけに、@code{remove-hook!}が@code{delete-hook!}の
エイリアスとなっています。
@c COMMON
@end deffn

@deffn {Method} reset-hook! (hook <hook>)
@c EN
Empties @var{hook}'s procedure list.
@c JP
@var{hook}の手続きリストを空にします。
@c COMMON
@end deffn

@deffn {Method} hook->list (hook <hook>)
@c EN
Returns a copy of @var{hook}'s procedure list.
@c JP
@var{hook}の手続きリストのコピーを返します。
@c COMMON
@end deffn

@deffn {Method} run-hook (hook <hook>) arg @dots{}
@c EN
Calls @var{hook}'s procedures in order, with arguments @var{arg} @dots{}.
The number of arguments must match the arity given at @code{make-hook}.
@c JP
@var{hook}の手続きを、@var{arg} @dots{}を引数として順番に呼び出します。
引数の数は、@code{make-hook}時に与えられたアリティにマッチしなければ
なりません。
@c COMMON
@end deffn

@c ----------------------------------------------------------------------
@node Interactive session, Listener, Hooks, Library modules - Gauche extensions
@section @code{gauche.interactive} - Utilities for interactive session
@c NODE インタラクティブセッション, @code{gauche.interactive} - インタラクティブセッション

@deftp {Module} gauche.interactive
@mdindex gauche.interactive
@c EN
Provides useful utilities for the interactive session.

This module is automatically loaded when you run @code{gosh}
interactively.

This module also sets autoloads for functions defined in
@code{gauche.reload} module 
(see @ref{Reloading modules}), so that
those functions can be used by default in interactive development.
@c JP
インタラクティブセッションで便利なユーティリティ手続きを提供します。

@code{gosh}をインタラクティブモードで起動した場合、
このモジュールは自動的にロードされます。

また、このモジュールは@code{gauche.reload}
(@ref{Reloading modules}参照)で定義される
手続きに対してautoloadを設定し、それらの手続きが
インタラクティブな開発時にデフォルトで使えるようにします。
@c COMMON
@end deftp

@defmac apropos pattern :optional module
@c EN
Show a list of defined variables whose name matches @var{pattern}.
If you give a module or a module name @var{module}, only the variables
defined in that module are listed.  Without @var{module},
the variables "visible" from the current module are listed.
@c JP
名前が@var{pattern}にマッチするような定義された変数のリストを表示します。
@var{module}にモジュールオブジェクトまたはモジュール名を与えた場合は、
そのモジュール内で定義されている変数のみが表示されます。@var{module}が
省略された場合は、カレントモジュールから「見える」変数が全て表示されます。
@c COMMON

@c EN
@var{pattern} may be a symbol or a regexp object.
If it is a symbol, the variables whose name contains the
substring that matches the symbol's name are listed.
If it is a regexp object, the variables whose name matches
the regexp are listed.
@c JP
@var{pattern}はシンボルか正規表現オブジェクトでなければなりません。
シンボルの場合、そのシンボル名を部分文字列として名前に含むような変数が
リストされます。正規表現オブジェクトの場合は、その正規表現にマッチする
名前を持つ変数がリストされます。
@c COMMON

@c EN
Some examples:
@c JP
いくつか例を示します。
@c COMMON
@example
@c EN
;; @r{List variables that contains "string" in their name}
@c JP
;; @r{"string"を名前に含む変数を表示}
@c COMMON
(apropos 'string)

@c EN
;; @r{Search in srfi-14 module}
@c JP
;; @r{srfi-14モジュールの中のみを検索}
@c COMMON
(apropos 'char 'srfi-14)
@end example
@end defmac

@deffn {Generic Function} describe obj
@deffnx {Generic Function} d obj
@c EN
Prints the detail information about a Scheme object @var{obj}.
The default method shows @var{obj}'s class, and if it has
any slots, the list of slot names and their values.
You can specialize this method for customized display.
@c JP
Schemeオブジェクト@var{obj}の詳細情報を表示します。
既定メソッドは@var{obj}のクラスを表示し、さらに@var{obj}がスロットを
持っていればその名前と内容をリストします。
このメソッドをスペシャライズすることによりクラス毎に表示をカスタマイズできます。
@c COMMON
@end deffn

@defun info symbol
@c EN
Displays a page of Gauche's info file that contains definition of
the function or syntax specified by @var{symbol}.
If an environment variable @code{INFOPATH} is defined,
this function searches for the info file from the directories in it.
Otherwise, this function guesses info file location from the
@code{gosh}'s library directory.   If the info file can't be
found, an error is signalled.   If the info file is found,
but @var{symbol} is not in its index, an error is signalled as well.
So this function doesn't work if you haven't installed info file.
@c JP
Gaucheのinfoドキュメント中から、
@var{symbol}で指定される手続きか構文要素の定義を含んでいるページを表示します。
infoドキュメントは、もし環境変数@code{INFOPATH}が定義されていればそこに
示されるディレクトリ中から探され、そうでなければ@code{gosh}のライブラリディレクトリ
から推測されるディレクトリ中から探されます。infoドキュメントが見付からなかったり、
見付かっても@var{symbol}がIndexページ中に無かった場合はエラーとなります。
つまり、この手続きはinfoファイルがインストールされていないと動作しません。
@c COMMON

@c EN
If the current output port is a tty, the info page is displayed by
a paging software.  If an environment variable @code{PAGER} is defined,
it is used as a paging software.  Otherwise, this function looks for
@code{less} and @code{more} in this order from the directories in
@code{PATH}.  If none of them is found, or the output port is not
a tty, this function just displays the page.
@c JP
現在の出力ポートが端末である場合、infoドキュメントの該当ページは
ページングプログラムを用いて表示されます。環境変数@code{PAGER}が指定されていれば
それを用い、そうでなければコマンドサーチパスから@code{less}及び@code{more}を
この順で探します。いずれも見付からなかった場合や、出力ポートが端末では
ない場合には、単にページがそのまま出力されます。
@c COMMON

@c EN
The first invocation of this function in a session takes some time
to parse the info file.
@c JP
この手続きのセッション中での最初の呼び出しは、infoファイルをパーズするために
多少時間がかかります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Listener, User-level logging, Interactive session, Library modules - Gauche extensions
@section @code{gauche.listener} - Listener
@c NODE リスナー, @code{gauche.listener} - リスナー

@deftp {Module} gauche.listener
@mdindex gauche.listener
@c EN
This module provides a convenient way to enable multiple
read-eval-print loop (repl) concurrently.
@c JP
このモジュールは、
複数のread-eval-printループ(repl)を並行して動作させるのに便利な機能を提供します。
@c COMMON

@c EN
An obvious way to run multiple repls is to use threads;
creating as many threads as sessions and calling
@code{read-eval-print-loop} (@xref{Eval and repl}) from each thread.
Nevertheless, sometimes single threaded implementation is preferred.
For instance, you're using a library which is not MT-safe,
or your application already uses select/poll-based dispatching mechanism.
@c JP
複数のreplを実現する自明な方法は、セッション毎にスレッドを生成して
各スレッド上で@code{read-eval-print-loop} (@ref{Eval and repl}参照)を
呼ぶことですが、シングルスレッドでの実装が好ましい場合もあります。
例えばアプリケーションがMT-safeでないライブラリに大きく依存していたり、
既にアプリケーションがselectやpollをベースにしたディスパッチメカニズムを
持っているような場合です。
@c COMMON

@c EN
To implement repl in the single-threaded selection-base application,
usually you register a handler that is called when data is available
in the listening port.  The handler reads the data and add them into
a buffer.  Then it examines if the data in the buffer consists a
complete expression, and if so, it reads the expression from the
buffer, evaluates it, then prints the result to the reporting port.
The @code{<listener>} class in this module provides this handler mechanism,
so all you need to do is to register the handler to your dispatching
mechanism.
@c JP
シングルスレッドのselectionベースのアプリケーションでreplを実装するには、
通常、listenしているポートにデータが到着した時に呼ばれるハンドラを登録します。
ハンドラはポートからデータを読み、内部バッファに追加します。
そして内部バッファをスキャンし、データが完全な式を構成した場合は
それをS式として読みだし、評価して結果をポートに流します。
このモジュールの@code{<listener>}クラスはこのハンドラのメカニズムを提供するので、
アプリケーション側はそれを自分のディスパッチメカニズムに登録するだけで済みます。
@c COMMON

@c EN
Note: it may also be desirable to buffer the output sometimes,
but the current version doesn't implement it.
@c JP
註：場合によっては、出力もバッファリングする必要があるかもしれませんが、
現在はそれは実装されていません。
@c COMMON
@end deftp

@subheading Listener API

@deftp {Class} <listener>
@c EN
An object that maintains the state of a repl session.
It has many external slots to customize its behavior.
Those slot values can be set at construction time
by using the keyword of the same name as the slot,
or can be set by @code{slot-set!} afterwards.  However,
most of them should be set before calling 
@code{listener-read-hander}.
@c JP
Replセッションの状態を維持するオブジェクトです。
オブジェクトのふるまいをカスタマイズするためにいくつもの外部スロットがあります。
これらのスロットの値は、スロットの名前と同名のキーワード引数を用いて
オブジェクトの構築時に指定することもできますし、オブジェクト構築後に
@code{slot-set!}で設定することもできますが、@code{listener-read-handler}
を呼ぶ前に確定していなければなりません。
@c COMMON

@defivar <listener> input-port
@c EN
Specifies the input port from which the listener get the input.
The default value is the current input port when the object is
constructed.
@c JP
リスナーが入力を受けとる入力ポートを指定します。デフォルト値は、
オブジェクトが構築された時のカレント入力ポートです。
@c COMMON
@end defivar

@defivar <listener> output-port
@c EN
Specifies the output port to which the listener output will go.
The default value is the current output port when the object is
constructed.
@c JP
リスナーが出力をおこなう出力ポートを指定します。デフォルト値は、
オブジェクトが構築された時のカレント出力ポートです。
@c COMMON
@end defivar

@defivar <listener> error-port
@c EN
Specifies the output port to which the listener's error messages will go.
The default value is the current error port when the object is
constructed.
@c JP
リスナーのエラーメッセージを出力するポートを指定します。デフォルト値は、
オブジェクトが構築された時のカレントエラー出力ポートです。
@c COMMON
@end defivar

@defivar <listener> reader
@c EN
A procedure with no arguments.  It should read a Scheme expression
from the current input port when called.
The default value is system's @code{read} procedure.
@c JP
引数を取らない手続きです。呼び出し時のカレント入力ポートからScheme式を
読み込まなければなりません。デフォルト値はシステムの@code{read}手続きです。
@c COMMON
@end defivar

@defivar <listener> evaluator
@c EN
A procedure that takes two arguments, a Scheme expression and
an environment specifier.  It should evaluate the expression in
the given environment and returns zero or more value(s).
The default value is system's @code{eval} procedure.
@c JP
Scheme式と環境指定子のふたつの引数をとる手続きです。
式を与えられた環境で評価し、0個以上の値を返さなければなりません。
デフォルト値はシステムの@code{eval}手続きです。
@c COMMON
@end defivar

@defivar <listener> printer
@c EN
A procedure that takes zero or more argument(s) and prints them
out to the current output port.  The default value is a procedure
that prints each value by @code{write}, followed by a newline.
@c JP
0以上の引数をとり、カレント出力ポートに印字する手続きです。
デフォルト値は、各値を@code{write}で印字したのち、改行する手続きです。
@c COMMON
@end defivar

@defivar <listener> prompter
@c EN
A procedure with no arguments.  It should prints a prompt
to the current output port.  The output is flushed by the listener
object so this procedure doesn't need to care about it.
The default procedure prints @code{"listener> "}.
@c JP
引数をとらない手続きです。カレント出力ポートにプロンプトを
印字しなければなりません。リスナーは、この手続きが面倒を見なくてよいように、
出力をフラッシュします。
デフォルトの手続きは @code{"listener> "} を印字します。
@c COMMON
@end defivar

@defivar <listener> environment
@c EN
An environment specifier where the expressions will be
evaluated.  The default value is the value returned by
@code{(interaction-environment)}.
@c JP
式を評価する環境指定子です。デフォルト値は@code{(interaction-environment)}が
返す値です。
@c COMMON
@end defivar

@defivar <listener> finalizer
@c EN
A thunk that will be called when EOF is read from @code{input-port}.
During the execution of @var{finalizer}, the current input, output
and error ports are restored to the ones when
@code{listener-read-handler} is called.

It can be @code{#f} if no such procedure is needed.
The default value is @code{#f}.
@c JP
@code{input-port}からEOFが読み込まれたときに呼び出されるサンクです。
@var{finalizer}実行中は、現在の入力、出力、エラー出力ポートは、
@code{listener-read-handler}が呼ばれたときのものに戻っています。

このような手続きが必要ない場合は@code{#f}にしておいて構いません。
デフォルトの値は@code{#f}です。
@c COMMON
@end defivar

@defivar <listener> error-handler
@c EN
A procedure that takes one argument, an error exception.  It is
called when an error occurs during read-eval-print stage,
with the same dynamic environment as the error is signalled.
The default value is a procedure that simply prints the
error exception by @code{report-error}.
@c JP
エラー例外をひとつ引数としてとる手続きです。read-eval-printの最中に
エラーが発生すると、エラーシグナルが発生すのと同じ動的環境で、
呼び出されます。
デフォルト値はエラー例外を@code{report-error}を使って印字する手続きです。
@c COMMON
@end defivar

@defivar <listener> fatal-handler
@c EN
A procedure that takes one argument, an error exception.
It is called when a @emph{fatal} error occurred (see below
for the precise definition).  If this handler is
called, you should assume you can no longer continue the listener
session safely, even write messages to the client.  This handler
is to log such condition or to clean up the listener.
During the execution of @var{fatal-handler}, the current input, output
and error ports are restored to the ones when
@code{listener-read-handler} is called.
@c JP
エラー例外をひとつの引数としてとる手続です。
@emph{fatal}エラー(詳しい定義については後述)が発生したときに呼び出され
ます。このハンドラが呼び出された場合、リスナーセッションは安全に続ける
ことはできないと思ってください。クライアントへのメッセージを書くこと
もできません。このハンドラはこういう状況でログを残したりリスナーの
クリーンアップするためのものです。@var{fatal-handler}を実行中は現在の
入力、出力、エラー出力は@code{listener-read-handler}が呼ばれたときのも
のに戻ります。
@c COMMON

@c EN
If @var{fatal-handler} returns @code{#f}, @var{finalizer} is
called afterwards.  With this, you can implement a common
cleanup work in @var{finalizer}.  If @var{fatal-handler} returns
a true value, @var{finalizer} will not be called.
@c JP
@var{fatal-handler}が@code{#f}を返す場合、@var{finalizer}は後で呼ばれ
ます。これを利用して@var{finalizer}で共通のクリーンアップを実行するよ
うな実装ができます。@var{fatal-handler}が真の値を返した場合には、
@var{finalizer}は呼ばれません。
@c COMMON

@end defivar

@end deftp


@deffn {Method} listener-read-handler (listener <listener>)
@c EN
Returns a thunk that is to be called when a data is available
from @code{input-port} of the listener.

The returned thunk (read handler) does the following steps.
Note that the first prompt is @emph{not} printed by this
procedure.  See @code{listener-show-prompt} below.
@enumerate
@item
Reads available data from @code{input-port} and appends it to the
listener's internal buffer.
@item
Scans the buffer to see if it has a complete S-expression.
If not, returns.
@item
Reads the S-expression from the buffer.
The read data is removed from the buffer.
@item
Evaluates the S-expression, then prints the result to
@code{output-port}.
@item
Prints the prompt by prompter procedure to @code{output-port},
then flush @code{output-port}.
@item
Repeats from 2.
@end enumerate
@c JP
リスナーの@code{input-port}から読み込んだデータが正しい時に
呼ばれるサンクを返します。

返されたサンク(readハンドラ)は、以下のように実行されます。
この手続きは最初のプロンプトを印字@emph{しない}ことに
注意してください。これについては後述の@code{listener-show-prompt}を
参照してください。
@enumerate
@item
@code{input-port}にあるデータを読み、これをリスナーの内部バッファに
連結する。
@item
バッファをスキャンして、それが完結したS式であるかを確かめ、
完結していなければ、リターンする。
@item
バッファからそのS式を読み込み、そのバッファからは
そのデータを除去する。
@item
そのS式を評価して、結果を@code{output-port}へ印字する。
@code{output-port}.
@item
プロンプタ手続きを使って、プロンプトを@code{output-port}に印字したのち、
@code{output-port}をフラッシュする。
@item
2から繰り返す。
@end enumerate
@c COMMON
@end deffn

@deffn {Method} listener-show-prompt (listener <listener>)
@c EN
Shows a prompt to the listener's output port, by using
listener's prompter procedure.  Usually you want to use
this procedure to print the first prompt, for instance,
when the client is connected to the listener socket.
@c JP
リスナーの出力ポートにプロンプトを表示します。表示にはリスナーの
プロンプタ手続きを使います。通常この手続きは最初のプロンプトを
印字するために使います。たとえば、クライアントがリスナーソケットに
接続してきたときです。
@c COMMON
@end deffn

@defun complete-sexp? str
@c EN
Returns @code{#t} if @var{str} contains a complete S-expression.
This utility procedure is exported as well, since it might be useful
for other purposes.

Note that this procedure only checks syntax of the expressions,
and doesn't rule out erroneous expressions (such as containing
invalid character name, unregistered SRFI-10 tag, etc.).
This procedure may raise an error if the input contains
'@code{#<}' character sequence.
@c JP
もし、@var{str}が完結したＳ式を含んでいれば@code{#t}を返します。
このユーティリティ手続きは、他の目的にも有用なので、
他の手続きといっしょにエクスポートしてあります。

この手続きは構文のチェックをするだけで、(不正な文字名を含んだり、
登録されていないSRFI-10のタグを含むなど)誤りのある式を判別するわけでは
ないことに注意してください。この手続きは入力が'@code{#<}'文字の
シーケンスを含むと、エラーを発生させます。
@c COMMON
@end defun

@c EN
@subheading Error handling
@c JP
@subheading エラー処理
@c COMMON

@c EN
There are a few error situations the listener handles diffetently.
@c JP
エラー状況によりリスナーのエラー処理法が異ります。
@c COMMON

@itemize @bullet
@item
@c EN
@emph{Fatal error} - An error situation that the listener session 
can no longer go on safely.  You cannot even tell so to the
listener client, since the connection to the client may be broken.
All you can do is to clean up the listener session (e.g. removes
the handler).   This case happens in (1) a low-level system error
occurrs during reading from @var{input-port}. (A syntax error
of the input isn't count as fatal, and handled as REPL error described
below.), (2) a @code{SIGPIPE} signal is raised during writing to
@var{output-port}, or (3) an unhandled error occurred during executing
@var{error-handler}.
@c JP
@emph{致命的エラー} - もはやリスナーセッションを安全に続けることが不可
能なエラー状況です。リスナーのクライアントとの接続が切れてしまうこと
になるので、状況を知らせることもできません。できることはリスナーセッショ
ンをクリーンアップする(たとえばハンドラを削除する)ことだけです。このエ
ラーは以下の場合に発生します。(1) @var{input-port}からの読み込み中に低
レベルのシステムエラーが発生した場合。(入力の構文エラーは致命的エラー
とはみなさず、後述のREPLエラーとして処理されます。) (2)
@var{output-port} へ書き出し中に @code{SIGPIPE} シグナルがあがった場合
(3) @var{error-handler} を実行中に処理未設定エラーが発生した場合。
@c COMMON

@c EN
When this situation happens, the @var{fatal-handler} is called
if it is given.  If @var{fatal-handler} returns @code{#f}, or
@var{fatal-handler} isn't given, @var{finalizer} is also called.
@c JP
このような状況が起こると、@var{fatal-handler}が与えられていればそれが
呼ばれます。@var{fatal-handler}が@code{#f}を返すか、
@var{fatal-handler}が与えられていなければ、@var{finalizer}が呼ばれます。
@c COMMON

@item
@c EN
@emph{Leaked error} - If an error occurrs during executing
@var{fatal-handler} or @var{finalizer}, we don't have no more
safety net.  The error is 'leaked' outside the listener handler,
and should be handled by the user of @code{gauche.listener}.
@c JP
@emph{リークエラー} - @var{fatal-handler}あるいは@var{finalizer}を実行
中にエラーが起こるともはやセーフティネットはありません。このエラーはリ
スナーハンドラの外に漏れだしますので、@code{gauche.listener}のユーザが
自ら処理しなければなりません。
@c COMMON

@c EN
Generally this situation should be considered as a bug of
the program; you should make sure to catch foreseeable errors within
@var{fatal-handler} and @var{finalizer}.
@c JP
一般的にはこのような状況はプログラムのバグだと考えるべきです。したがっ
て、想定されたエラーとして@var{fatal-handler}および@var{finalizer}内で
捕捉されるべきです。
@c COMMON

@item
@c EN
@emph{REPL error} - Other errors are handled by @var{error-handler}.
@c JP
@emph{REPLエラー} - @var{error-handler}で処理されるその他のエラー
@c COMMON
@end itemize

@c EN
@subheading Listener example
@c JP
@subheading リスナーの例
@c COMMON

@c EN
The following code snippet opens a server socket, and opens
a Scheme interactive session when a client is connected.
(Note: this code is just for demonstration.  Do not run
this program on the machine accessible from outside network!)
@c JP
以下のコード断片は、サーバソケットをオープンし、クライアントが
接続してきたときにSchemeの対話的セッションをオープンするというものです。
(註: このコードはdemo用のコードです。決して、外のネットワークから
アクセス可能なマシン上で走らせてはいけません！)
@c COMMON

@example
(use gauche.net)
(use gauche.selector)
(use gauche.listener)

(define (scheme-server port)
  (let ((selector (make <selector>))
        (server   (make-server-socket 'inet port :reuse-addr? #t))
        (cid      0))

    (define (accept-handler sock flag)
      (let* ((client (socket-accept server))
             (id     cid)
             (input  (socket-input-port client :buffering :none))
             (output (socket-output-port client))
             (finalize (lambda ()
                         (selector-delete! selector input #f #f)
                         (socket-close client)
                         (format #t "client #~a disconnected\n" id)))
             (listener (make <listener>
                         :input-port input
                         :output-port output
                         :error-port output
                         :prompter (lambda () (format #t "client[~a]> " id))
                         :finalizer finalize))
             (handler (listener-read-handler listener))
             )
        (format #t "client #~a from ~a\n" cid (socket-address client))
        (inc! cid)
        (listener-show-prompt listener)
        (selector-add! selector input (lambda _ (handler)) '(r))))

    (selector-add! selector
                   (socket-fd server)
                   accept-handler
                   '(r))
    (format #t "scheme server started on port ~s\n" port)
    (do () (#f) (selector-select selector))))
@end example

@c ----------------------------------------------------------------------
@node User-level logging, Propagating slot access, Listener, Library modules - Gauche extensions
@section @code{gauche.logger} - User-level logging
@c NODE ユーザレベルのロギング, @code{gauche.logger} - ユーザレベルのロギング

@deftp {Module} gauche.logger
@mdindex gauche.logger
@c EN
Provides a simple interface to log the program's activity.
The information can be written to the specified file,
or to the system logger using @code{syslog(3)}.
When a file is used, syslog-like prefix string is added
to each message, which is configurable.  It can also takes care of
locking of the file (see the description of @code{lock-policy} below).
@c JP
プログラムからログを書き出す簡単なインタフェースを提供します。
情報は指定されたファイルへ書き出されるか、もしくは@code{syslog(3)}を
使ってシステムログへと送られます。
ファイルに書き出される場合は、
syslogに似たプレフィクスが各メッセージの前に追加されます。
プレフィクスはカスタマイズすることもできます。
また、ログファイルの排他制御も行われます (下の@code{lock-policy}の説明を
参照して下さい)。
@c COMMON
@end deftp

@deftp {Class} <log-drain>
@clindex log-drain
@c EN
Represents the destination of log messages.
There's one implicit global @code{<log-drain>} instance, which is
used by default.  However, you can create as many instances
by @code{make} method as you want, in case if you want to log
to more than one destination.
@c JP
ログメッセージの行き先を表現するオブジェクトです。
デフォルトのログの行き先として、グローバルな@code{<log-drain>}のインスタンスが
ひとつ作られます。
ログをいくつかにわけて出力する場合などは@code{make}メソッドを使って
いくつでも@code{<log-drain>}のインスタンスを作ることができます。
@c COMMON

@defivar {<log-drain>} path
@c EN
Path of the log file.  It can be also @code{#t}, which means 
the current error port, or @code{#f}, which makes @code{log-format}
to return the formatted message but not write to any log files,
or a symbol @code{syslog}, which means the messages are sent to
the system logger.

By default, this slot is @code{#f}.
@c JP
ログファイルのパス名か、@code{#t}、@code{#f}、あるいはシンボル@code{syslog}
の値を取ります。このスロットが@code{#t}の場合、ログメッセージは現在のエラーポートに
書き出されます。@code{#f}の場合は@code{log-format}は
ログを書き出すかわりにフォーマットされたログメッセージを文字列として返します。
シンボル@code{syslog}の場合はメッセージがシステムログへと送られます。

このスロットの初期値は@code{#f}です。
@c COMMON
@end defivar

@defivar {<log-drain>} prefix
@c EN
Specifies the prefix string that is attached to the beginning of every
message.  If the message spans to several lines, the prefix is
attached to each line.   The value of this slot can also be a procedure
that takes @code{<log-drain>} object and returns a string to be used as
the prefix.  The procedure is called every time prefix is needed.
@c JP
各メッセージの前に追加されるプレフィクス文字列を指定します。
メッセージが複数行に渡る場合、プレフィクスは各行の頭に追加されます。
またこのスロットには手続きをセットすることもできます。
その場合、プレフィクス文字列が必要とされる度にその手続きが@code{<log-drain>}
を引数として呼び出され、戻り値の文字列がプレフィクスとして使われます。
@c COMMON

@c EN
When the @code{path} slot is a symbol @code{syslog}, the value of this slot
is ignored.  System logger will attach an appropriate prefix.
@c JP
@code{path}スロットの値がシンボル@code{syslog}の場合は、
このスロットの値は無視されます。システムのログ機構が適切なプレフィクスを付けるからです。
@c COMMON

@c EN
When the value of the prefix slot is a string, the following character sequences
have special meanings and replaced by @code{log-format} for appropriate
information when written out.
@c JP
prefixスロットの値が文字列の場合、以下に挙げる文字シーケンスは特別な意味を持ち、
@code{log-format}によって置換されます。
@c COMMON

@table @code
@item ~T
@c EN
Current time, in the format of "Mmm DD hh:mm:ss" where "Mmm" is
an abbreviated month, "DD" is the day of month, "hh", "mm" and
"ss" are hours (in 24 hour basis), minutes and seconds, respectively.
This format is compatible with system logs.
@c JP
現在の時刻を"Mmm DD hh:mm:ss"という形式で表したもの。
ここで"Mmm" は英語の月名の省略形、"DD" は日、"hh"、"mm"、
"ss" は時間(24時間制)、分、秒です。
このフォーマットはシステムログと同じです。
@c COMMON

@item ~Y
@c EN
Current 4-digit year.
@c JP
4桁で表した現在の西暦。
@c COMMON

@item ~P
@c EN
The program name.  The default value is the basename of
@code{*program-name*} (@xref{Writing Scheme scripts}), 
but you can change it by the @code{program-name}
slot described below.
@c JP
プログラム名。初期値は@code{*program-name*}の値のbasenameが使われます
(@ref{Writing Scheme scripts}参照)。
下に述べる@code{program-name}スロットの値を変えれば
ここに現れる文字列を変えることができます。
@c COMMON

@item ~$
@c EN
The process id of this program.
@c JP
このプログラムのプロセスID。
@c COMMON

@item ~U
@c EN
The name of the effective user of the process.
@c JP
このプロセスの実行ユーザ名。
@c COMMON

@item ~H
@c EN
The hostname the process is running.
@c JP
このプロセスが走っているホスト名。
@c COMMON
@end table

@c EN
The default value of this slot is "@code{~T ~P[~$]: }".  For example,
if a string "this is a log message.\nline 2\nline 3" is given as the
message, it produces something like the following log entry.
@c JP
このスロットの初期値は"@code{~T ~P[~$]: }"です。例えば
"this is a log message.\nline 2\nline 3"というメッセージが
与えられると、次のようなログが書き出されます。
@c COMMON

@example
Sep  1 17:30:23 myprogram[441]: this is a log message
Sep  1 17:30:23 myprogram[441]: line 2
Sep  1 17:30:23 myprogram[441]: line 3
@end example

@end defivar

@defivar {<log-drain>} program-name
@c EN
Specifies the program name written by @code{~P} directive of
the prefix slot.
@c JP
プレフィクス文字列の@code{~P}が置換されるプログラム名を指定します。
@c COMMON
@end defivar

@defivar {<log-drain>} lock-policy
@c EN
Specifies the way the log file should be locked.
If the value of this slot is a symbol @code{fcntl},
the log file is locked using
fcntl() (@xref{Low-level file operations}).
If the value is a symbol @code{file}, the log file is locked by
creating auxiliary lock file, whose name is generated by appending ".lock"
after the log file path.  The logging
process needs a write permission to the log file directory.
Note that if the process is killed forcibly during writing the
log file, a stale lock file may remain.  @code{Log-format}
silently removes the lock file if it is unusually old (currently 10 minutes).
If the value is @code{#f}, no locking is performed.

The default value is @code{fcntl}, except MacOSX which doesn't
support fcntl()-style locking and thus @code{file} is default.

The locking isn't performed if the destination is not a file.
@c JP
ログファイルのロックの方法を指定します。
このスロットの値がシンボル@code{fcntl}だった場合は、
fcntl()によるファイルロックが使われます
(@ref{Low-level file operations}参照)。
このスロットの値がシンボル@code{file}だった場合は、
ログファイルのパス名に ".lock" を追加したロックファイルを作成することによる
排他制御が行われます。この場合、ログを行うプロセスはログファイルの
置かれるディレクトリに書き込み権限が必要です。
また、プロセスがログファイル書き込み中に強制的に終了させられた場合、
ロックファイルが残ってしまう恐れがあります。
@code{Log-format}はロックファイルが十分に古い場合(現在は10分をリミットとしています)
ロックファイルを自動的に削除します。
このスロットの値が@code{#f}だった場合は、排他制御は行われません。

デフォルトの値は@code{fcntl}です。但しMacOSXではfcntlスタイルのロックが
サポートされていないため、@code{file}がデフォルト値となります。

ログの行き先がファイルでない場合は排他制御は行われません。
@c COMMON
@end defivar

@defivar {<log-drain>} syslog-option
@defivarx {<log-drain>} syslog-facility
@defivarx {<log-drain>} syslog-priority
@c EN
The value of these slots are used when the destination of the drain
is the system logger.   @xref{Syslog}, for the detailed information
about these values.  The default values of these slots
are @code{LOG_PID}, @code{LOG_USER} and @code{LOG_INFO}, respectively.
@c JP
これらのスロットの値は、ログの行き先がシステムログの場合にのみ使われます。
これらの値に関する説明は@ref{Syslog}を参照して下さい。
デフォルトの値はそれぞれ@code{LOG_PID}、@code{LOG_USER}、@code{LOG_INFO}です。
@c COMMON
@end defivar
@end deftp


@defun log-open path :key prefix program-name
@c EN
Sets the destination of the default log message to the path @var{path}.
It can be a string or a boolean, as described above.
You can also set prefix and program name by corresponding keyword 
arguments.
@c JP
デフォルトのログの行き先を@var{path}に指定します。
@var{path}は文字列かboolean値あるいはシンボル@code{syslog}で、
上の@code{path}スロットで述べたものと
おなじ意味を持ちます。またプレフィクスとプログラム名をキーワード引数で
指定することもできます。
@c COMMON

@c EN
Despite its name, this function doesn't open the specified file
immediately.  The file is opened and closed every time @code{log-format}
is called.
@c JP
名前に"open"とありますが、この手続きは指定されたファイルをオープンしません。
ファイルは@code{log-format}が呼ばれるたびにオープンされクローズされます。
@c COMMON
@end defun

@deffn {Parameter} log-default-drain
@c EN
When called with no argument, returns the current default log-drain
@code{log-format} uses when the explicit drain is omitted.  
It may return @code{#f} if the default log drain hasn't been
opened by @code{log-open}.

Calling with new @code{<log-drain>} object or
@code{#f} alters the default log-drain.
You can also use @code{parameterize} (@ref{Parameters}) to change
the log drain temporary.
@c JP
引数無しで呼ばれると、@code{log-format}が使う、
現在のデフォルトのログの行き先が返されます。
まだデフォルトのログの行き先が@code{log-open}で指定されていない場合は
@code{#f}が返ります。

新たな@code{<log-drain>}オブジェクトか@code{#f}を引数にして呼び出すと、
デフォルトのログの行き先がそれに変更されます。
@code{parameterize} (@ref{Parameters}) を使えば、一時的にデフォルトの
ログの行き先を変更できます。
@c COMMON
@end deffn


@deffn {Method} log-format (format <string>) arg @dots{}
@deffnx {Method} log-format (drain <log-drain>) (format <string>) arg @dots{}
@c EN
Formats a log message by @var{format} and @var{arg @dots{}}, by using
@code{format} (@xref{Output}).    In the first form, the output goes
to the default destination.  In the second form, the output goes to
the specfied drain.
@c JP
ログメッセージを@code{format}手続きでフォーマットし(@ref{Output}参照)、
指定された行き先に書き出します。最初の形式ではデフォルトの行き先が使われます。
@c COMMON

@c EN
The file is opened and closed every time.  You can safely move
the log file while your program that touches the log file is running.
Also @code{log-format} acquires a write lock of the log file by
@code{sys-fcntl} (@xref{Low-level file operations}).
@c JP
ファイルはこの手続きが呼ばれるたびにオープンされクローズされます。
したがって、ログファイルに書き出すプログラムが走っている最中でも
ログファイルをmoveすることができます。
また、@code{log-format}は@code{sys-fcntl} (@ref{Low-level file operations}参照)
を使ってファイルロックを獲得します。
@c COMMON

@c EN
If the first form of @code{log-format} is called before @code{log-open}
is called, @code{log-format} does nothing.
It is useful to embed debug stubs in your code; once your code is
past the debugging stage, you just comment out @code{log-open} and
the code runs without logging.
@c JP
@code{log-open}が呼ばれる前に@code{log-format}が最初の形式で呼ばれた場合、
@code{log-format}は何もしません。したがって、@code{log-format}をデバッグに
活用し、必要なくなったら@code{log-open}だけをコメントアウトする、というような
使用法も可能です。
@c COMMON
@end deffn

@c ----------------------------------------------------------------------
@node Propagating slot access, Singleton, User-level logging, Library modules - Gauche extensions
@section @code{gauche.mop.propagate} - Propagating slot access
@c NODE スロットアクセスの伝播, @code{gauche.mop.propagate} - スロットアクセスの伝播

@deftp {Module} gauche.mop.propagate
@mdindex gauche.mop.propagate
Provides a metaclass to add @code{:propagated} slot allocation option.

When a slot allocation has @code{:propagated}, access
to the slot is redirected to other object's slot.
It is handy for composite objects to keep external
interface simple, for access to the slot of inner objects
can be disguised as if it is a slot of the parent object.
@end deftp

An example would work better than explanation.
Suppose you have a @code{<rect>} class to represent
generic rectangular area, and you want to use it when you create
a @code{<viewport>} class by composition, instead of
inheritance.  A simple way would be as follows:

@example
(define-class <rect> ()
  ((width  :init-keyword :width)
   (height :init-keyword :height)))

(define-class <viewport> ()
  ((dimension :init-form (make <rect>))
   ;;   ... other slots ...
   )) 
@end example

With this definition, whenever you want to access the viewport's
width or height, you have to go through @code{<rect>} object, e.g.
@code{(~ viewport'dimension'width)}.  This is not only cumbersome,
but the users of viewport class have to know that how the
viewport is composed (it's not necessarily a bad thing,
but sometimes you may want to hide it).

Using @code{gauche.mop.propagate}, you can define slots
@code{width} and @code{height} in @code{<viewport>} class
that are proxies of @code{<rect>}'s slots.

@example
(use gauche.mop.propagate)

(define-class <rect> ()
  ((width  :init-keyword :width)
   (height :init-keyword :height)))

(define-class <viewport> (<propagate-mixin>)
  ((dimension :init-form (make <rect>))
   (width     :allocation :propagated :propagate 'dimension
              :init-keyword :width)
   (height    :allocation :propagated :propagate 'dimension
              :init-keyword :height)))
@end example

With @code{:propagated} allocation, the slots are not actually
allocated in @code{<viewport>} instance, and accesses to the
slots are redirected to the object in the slot specified by 
@code{:propagate} slot option---in this case, the @code{dimension} slot.
It is somewhat similar to the virtual slots, but it's more convenient
for you don't explicitly write procedures to redirect the access.

Now you can treat @code{width} and @code{height} as if they
are slots of @code{<viewport>}.   You can even make them
initialize via @code{init-keyword} (but you can't use
@code{:init-form} or @code{:init-value}; if you want to specify
default values, give the default values to the actual object).

@example
gosh> (define vp (make <viewport> :width 640 :height 480))
vp
gosh> (d vp)
#<<viewport> 0xc5a1e0> is an instance of class <viewport>
slots:
  dimension : #<<rect> 0xc5a130>
  width     : 640
  height    : 480
gosh> (set! (~ vp'width) 800)
#<undef>
gosh> (~ vp'width)
800
@end example

Here's two classes that enables this feature.
Usually all you have to do is to inherit @code{<propagate-mixin>} class.

@deftp {Class} <propagate-meta>
@clindex propagate-meta
Adds @code{:propagated} slot allocation.  
The propagated slot has to have @code{:propagate} slot option
which specifies the name of the slot that points to an object
that actually holds the value of the slot.
If a slot has @code{:propagated} slot allocation but
does not have @code{:propagate} slot option, an error is signalled.

The @code{:propagate} slot option should have a value
of either a symbol, or a list of two symbols.

If it is a symbol, it names the slot that contains an
object, whose slot with the same name of the propagate slot
holds the value.

If it is a list of two symbols as @code{(X Y)}, then 
the access to this propagated slot actually works as
@code{(slot-ref (slot-ref obj X) Y)}.

If you want to make a propagated slot initializable by
init-keywords, make sure the slot holding the actual object
comes before the propagated slots.  Slot initialization proceeds
in the order of appearance by default, and you want the
actual object is created before setting values.
@end deftp

@deftp {Class} <propagate-mixin>
@clindex propagate-mixin
This is a convenience mixin class.   Instead of giving 
@code{:metaclass <propagate-meta>}, you can just inherit
this calss to make propagated slots available.
@end deftp

@c ----------------------------------------------------------------------
@node Singleton, Slot with validator, Propagating slot access, Library modules - Gauche extensions
@section @code{gauche.mop.singleton} - Singleton
@c NODE シングルトン, @code{gauche.mop.singleton} - シングルトン

@deftp {Module} gauche.mop.singleton
@mdindex gauche.mop.singleton
@c EN
Provides a metaclass to define a singleton class.
@c JP
シングルトンクラスを定義するためのメタクラスを提供します。
@c COMMON
@end deftp

@deftp {Class} <singleton-meta>
@clindex singleton-meta
@c EN
Creates a singleton class.  A singleton class is a class that is
guaranteed to create only one instance.
The first invocation of @code{make} creates the single instance,
and further attempt of creation returns the same instance.
@c JP
シングルトンクラスを生成します。シングルトンクラスはそのインスタンスが
ただ一つしかないことを保証するクラスです。 @code{make} の
最初の呼び出しで、唯一のインスタンスを生成し、その後の呼出しでは
最初に生成したものと同一のインスタンスを返します。
@c COMMON
@example
(define-class single () () :metaclass <singleton-meta>)

(define a (make single))
(define b (make single))

(eq? a b) @result{} #t
@end example

@c EN
The slots of the instance are initialized at the first invocation
of @code{make}.  Initargs of @code{make} are effective only in the
fist invocation, and ignored in the subsequent invocation.
@c JP
インスタンスのスロットは最初の @code{make} の呼び出し時に
初期化されます。@code{make}への初期引数は最初の呼び出しのときに
だけ効果があり、それ以降の呼び出しでは無視されます。
@c COMMON
@end deftp

@deffn {Method} instance-of (class <singleton-meta>) :rest initargs
@c EN
This method just calls @code{make} with the passed arguments.
It is more obvious in the program that you're dealing with singleton.
@c JP
このメソッドは渡された引数とともに @code{make} を呼んでいるだけです。
シングルトンを扱うプログラム中ではこちらの方が分りやすいでしょう。
@c COMMON
@end deffn

@deftp {Class} <singleton-mixin>
@clindex singleton-mixin
@c EN
An instance of @code{<singleton-meta>}.  Instead of specifying
@code{<singleton-meta>} as the @code{:metaclass} argument of
@code{define-class}, you can inherit this class to give your
class the property of singleton.
@c JP
@code{<singleton-meta>}のインスタンスです。@code{<singleton-meta>}
を @code{define-class} の @code{:metaclass} 引数として指定せずに、
このクラスを継承することで、定義しようとするクラスにシングルトンの
性質を与えることができます。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node Slot with validator, Networking, Singleton, Library modules - Gauche extensions
@section @code{gauche.mop.validator} - Slot with validator
@c NODE Validator付きスロット, @code{gauche.mop.validator} - Validator付きスロット

@deftp {Module} gauche.mop.validator
@mdindex gauche.mop.validator
@c EN
Provides a metaclass that adds @code{:validator} and @code{:observer}
slot options.
@c JP
@code{:validator}および@code{:observer}
スロットオプションを追加するメタクラスを提供するモジュールです。
@c COMMON
@end deftp

@deftp {Class} <validator-meta>
@clindex validator-meta
@c EN
This metaclass adds a feature that you can specify callbacks that are
called before and after the slot value is set.
For example, if you want to guarantee
that a certain slot always holds a string value, you can make a procedure
be called before the slot is modified, either by @code{slot-ref} or
by a setter method.  In the procedure you can either rejects a
value except string, or coerce the value to a string.

A @emph{validator} procedure is a callback procedure that is called
before the slot value is set.   It can be specified by @code{:validator}
slot option.  The procedure takes two values, the instance and
the value to be set.  Whatever the procedure returns is set to
the actual slot value.

A @emph{observer} procedure is a callback procedure that is called
after the slot value is set.  It can be specified by @code{:observer}
slot option.  The procedure also takes two values, the instance
and the new value.  Result of the observer procedure is discarded.

See the following example:
@c JP
このメタクラスは、スロットの値がセットされる前後に呼ばれるコールバックを
指定する機能を提供します。例えば、あるスロットに常に文字列のみが
セットされているようにしたい場合、そのスロットに、@code{slot-ref}経由であれ
アクセサメソッド経由であれ値がセットされようとした時に指定の手続きが呼ばれるように
し、その手続きの中で、値が文字列でなかったらエラーとするか、強制的に値を
文字列に変換してしまうことができます。その手続きが返した値が実際にスロットに
セットされます。

スロットに値がセットされる前に呼ばれる@emph{validator}手続きは、
@code{:validator}スロットオプションによって指定できます。
手続きは、インスタンスとセットされようとしている値の二つを引数に取ります。
その手続きが返した値が実際にスロットにセットされる値となります。

スロットに値がセットされた後に呼ばれる@emph{observer}手続きは
@code{:observer}スロットオプションによって指定できます。
手続きは、インスタンスとセットされた値の二つを引数に取ります。
戻り値は捨てられます。

下の例を参照して下さい。
@c COMMON

@example
(define-class <v> ()
  ((a :accessor a-of
      :validator (lambda (obj value) (x->string value)))
   (b :accessor b-of
      :validator (lambda (obj value)
                   (if (integer? value)
                       value
                       (error "integer required for slot b")))))
  :metaclass <validator-meta>)

(define v (make <v>))
(slot-set! v 'a 'foo)
(slot-ref v 'a) @result{} "foo"

(set! (a-of v) 1234)
(a-of v) @result{} "1234"

(slot-set! v 'b 55)
(slot-ref v 'b) @result{} 55

(slot-set! v 'b 3.4) @result{} @r{error}
(set! (b-of v) 3.4)  @result{} @r{error}
@end example

@c EN
You can specify default slot value (@code{:init-value} etc.) with
@code{:validator}.  In that case, the initialization method of the
instance calls the validator with the specified default value,
if :init-keyword is not given.
@c JP
@code{:validator} が指定されたスロットにも、@code{:init-value}等を
使って既定の初期値を指定しておくことができます。
その場合、インスタンスの初期化ルーチンは、
init-keywordによる初期値指定が無ければ既定の初期値を引数としてvalidator手続きを
呼び出します。
@c COMMON

@example
(define-class <v> ()
  ((a :initform 'foo :init-keyword :a
      :validator (lambda (obj value) (x->string value)))))

(slot-ref (make <v>) 'a)        @result{} "foo"
(slot-ref (make <v> :a 555) 'a) @result{} "555"
@end example

@c EN
It looks similar to the virtual slot, but note that a slot with
validator has an actual storage in the instance, while a virtual
slot doesn't.

It is also a good example of customizing how the slots are accessed
using the metaobject protocol.  This feature is implemented by
only a couple of dozen lines of code.
@c JP
仮想スロットに似ていますが、validatorを持つスロットはインスタンス内に実際に
値を格納している点が異なります。

このモジュールはまた、スロットのアクセスをメタオブジェクトプロトコルを使って
カスタマイズする例でもあります。この機能は20行ほどのコードで実現されています。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node Networking, Parameters, Slot with validator, Library modules - Gauche extensions
@section @code{gauche.net} - Networking
@c NODE ネットワーキング, @code{gauche.net} - ネットワーキング

@deftp {Module} gauche.net
@mdindex gauche.net
@c EN
Provides a set of functions necessary for network communications
based on BSD socket interface.

The API is provided in two different levels.  Lower level routines
reflect traditional BSD socket interface, such as @code{bind(2)}.
Higher level routines provides more convenient way to create
typical connection-oriented server/client sockets.

This module also provides APIs to obtain various information
about hostnames, service ports, and protocols.
@c JP
BSDソケットに基づいたネットワーキングに必要な手続きを提供するモジュールです。

2つのレベルのAPIが定義されています。低レベルの手続きは@code{bind(2)}のような
BSDソケットインタフェースに近いインタフェースを提供し、高レベルの手続きは
典型的なコネクション指向のクライアントサーバアプリケーションに便利な
インタフェースを提供します。

また、ホストネームやプロトコルに関する情報にアクセスするAPIも定義されます。
@c COMMON

@c EN
Gauche can handle IPv6 if it is compiled 
with the @code{--enable-ipv6} configuration option.
To check whether IPv6 is enabled or not, 
you can use @code{cond-expand} with
@code{gauche.net.ipv6} feature identifier
after loading @code{gauche.net}, as shown below.

@example
(use gauche.net)
(cond-expand
  (gauche.net.ipv6
    ... code to use ipv6 ...)
  (else
    ... ipv4 only code ...))
@end example

See @ref{Feature conditional} for the details of @code{cond-expand}.
@c JP
Gaucheは、@code{--enable-ipv6}コンフィギュアオプションつきで
コンパイルされていれば、IPv6を扱うことができます。
IPv6が使えるかどうかを調べるには、
@code{cond-expand}中で@code{gauche.net.ipv6} feature identifierを
使うことができます。次の例を見てください。

@example
(use gauche.net)
(cond-expand
  (gauche.net.ipv6
    ... ipv6を使うコード ...)
  (else
    ... ipv4のみのコード ...))
@end example

@code{cond-expand}の詳細については@ref{Feature conditional}を
参照してください。
@c COMMON

@end deftp


@menu
* Socket address::              
* High-level network functions::  
* Low-level socket interface::  
* Netdb interface::             
@end menu

@node Socket address, High-level network functions, Networking, Networking
@subsection Socket address
@c NODE ソケットアドレス

@c EN
@subsubheading Socket address objects
@c JP
@subsubheading ソケットアドレスオブジェクト
@c COMMON

@deftp {Builtin Class} <sockaddr>
@clindex sockaddr
@c EN
An abstract base class of socket addresses.  Each socket address family
is implemented as a subclass of this class.

Although socket addresses are built-in classes, you can use
@code{make} method to create an instance of a
specific socket address family.
@c JP
ソケットアドレスの抽象ベースクラスです。
ソケットアドレスファミリはこのクラスのサブクラスとして実装されます。

ソケットアドレスはビルトインクラスですが、@code{make}メソッドで
特定のソケットアドレスファミリのインスタンスを作成することができます。
@c COMMON
@end deftp

@deffn {Generic Function} sockaddr-family addr
@c EN
Returns a symbol that indicates the family of the socket address
@var{addr}.
@c JP
ソケットアドレス@var{addr}のファミリを表すシンボルを返します。
@c COMMON
@end deffn

@deffn {Generic Function} sockaddr-name addr
@c EN
Returns a string which represents the content of the socket address
@var{addr}.
@c JP
ソケットアドレス@var{addr}の名前を表す文字列を返します。
@c COMMON
@end deffn

@deftp {Builtin Class} <sockaddr-in>
@clindex sockaddr-in
@c EN
AF_INET family socket address.  To create an instance of this class,
use @code{make} method as follows:
@c JP
AF_INETファミリのソケットアドレスです。このクラスのインスタンスを
作成するには、次のようにして@code{make}メソッドを呼びます。
@c COMMON
@example
(make <sockaddr-in> :host @var{host} :port @var{port})
@end example
@c EN
@var{host} can be a string, an integer IP address, a
@code{u8vector} IP address, or one of the keywords
@code{:any}, @code{:broadcast}, @code{:none} or @code{:loopback}.
If it is a string, it is either a host name or a dotted IP notation.
Gauche uses @code{gethostbyname(3)} to obtain the actual IP address from
@var{host} parameter.  If it is a keyword @code{:any}, 
or @code{:broadcast}, the address
uses @code{INADDR_ANY}, or @code{INADDR_BROADCAST}
respectively.  The keyword @code{:loopback} is a synonym to the
IPv4 loopback address "127.0.0.1".
@c JP
@var{host}は文字列、整数のIPアドレス、@code{u8vector}のIPアドレス、
もしくは@code{:any}、@code{:broadcast}、@code{:none}、@code{:loopback}の
いずれかのキーワードでなければなりません。
文字列の場合、それはホスト名かIPアドレスのドット表記です。
Gaucheは@code{gethostbyname(3)}を使って実際のIPアドレスを得ます。
この値がキーワード@code{:any}か@code{:broadcast}なら、それぞれ
@code{INADDR_ANY}か@code{INADDR_BROADCAST}がアドレスとして使われます。
キーワード@code{:loopback}はIPv4のループバックアドレス"127.0.0.1"を表します。
@c COMMON

@c EN
@var{port} must be a positive integer indicating the port number.
@c JP
@var{port}はポート番号を示す正の整数です。
@c EN
See also @code{make-sockaddrs} below, to create multiple
socket addresses on the machine which may have more than one
protocol stack.
@c JP
2つ以上のプロトコルスタックを持つようなマシン上で複数のソケットアドレスを
生成するには、後述の @code{make-sockaddrs} も参照してください。
@c COMMON
@end deftp

@deffn {Method} sockaddr-family (addr <sockaddr-in>)
@c EN
Returns a symbol @code{inet}.
@c JP
シンボル@code{inet}を返します。
@c COMMON
@end deffn

@deffn {Method} sockaddr-name (addr <sockaddr-in>)
@c EN
Returns a string in the form "@var{a}.@var{b}.@var{c}.@var{d}:@var{port}",
 where "@var{a}.@var{b}.@var{c}.@var{d}" is dotted decimal notion of
the IP address and @var{port} is the port number.
@c JP
文字列"@var{a}.@var{b}.@var{c}.@var{d}:@var{port}"を返します。
コロンの前はIPアドレスのドット表記で、@var{port}はポート番号です。
@c COMMON
@end deffn

@deffn {Method} sockaddr-addr (addr <sockaddr-in>)
@deffnx {Method} sockaddr-port (addr <sockaddr-in>)
@c EN
Returns the IP address and the port number as an integer, respectively.
@c JP
それぞれ、IPアドレスとポート番号を整数で返します。
@c COMMON
@end deffn

@deftp {Builtin Class} <sockaddr-un>
@clindex sockaddr-un
@c EN
AF_UNIX family socket address.  To create an instance of this class,
use @code{make} method as follows:
@c JP
AF_UNIXファミリのソケットアドレスです。このクラスのインスタンスを作成するには、
@code{make}メソッドを次のように呼んで下さい。
@c COMMON
@example
(make <sockaddr-un> :path @var{path})
@end example
@c EN
@var{path} must be a string specifying pathname of the socket.
@c JP
@var{path}はソケットのパス名を表す文字列です。
@c COMMON
@end deftp

@deffn {Method} sockaddr-family (addr <sockaddr-un>)
@c EN
Returns a symbol @code{unix}.
@c JP
シンボル@code{unix}を返します。
@c COMMON
@end deffn

@deffn {Method} sockaddr-name (addr <sockaddr-un>)
@c EN
Returns a pathname of the socket address.
@c JP
ソケットアドレスのパス名を返します。
@c COMMON
@end deffn

@deftp {Builtin Class} <sockaddr-in6>
@clindex sockaddr-in6
@c EN
AF_INET6 family socket address.  This is only available if
gauche is configured with --enable-ipv6 configure option.
The constructor and the slots are the same as @code{<sockaddr-in>}.
@c JP
AF_INET6ファミリのソケットアドレスです。
このクラスはgaucheが--enable-ipv6つきでconfigureされている場合に使えます。
コンストラクタとスロットは@code{<sockaddr-in>}と同じです。
@c EN
See also @code{make-sockaddrs} below, to create multiple
socket addresses on the machine which may have more than one
protocol stack.
@c JP
2つ以上のプロトコルスタックを持つようなマシン上で複数のソケットアドレスを
生成するには、後述の @code{make-sockaddrs} も参照してください。
@c COMMON
@end deftp

@defun make-sockaddrs host port :optional proto
@c EN
This is a higher-level utility procedure to create all possible
inet domain socket addresses that point to @code{@var{host}:@var{port}}
of protocol @var{proto}.  Particularly, if the specified host has
both IPv4 and IPv6 addresses, and the running system supports both,
then both IPv4 and IPv6 socket addresses are returned.   If @var{host} has
multiple IP addresses, socket addresses are created for each of these
IP address.   You can make your network application much more portable
among different network stack configurations.

Passing @code{#f} to @var{host} creates the local
(server) address.  You can also pass a service name (e.g. @code{"http"})
instead of an integer, to the @var{port} argument.
The value of @var{proto} can be either a symbol @code{tcp} or @code{udp},
and the default is @code{tcp}.

It always returns a list of socket addresses.  If the lookup of @var{host}
is failed, null list is returned.
@c JP
これは上位レベルのユーティリティ手続きで、プロトコル @var{proto} の
@code{@var{host}:@var{port}} を指す、可能なすべてのドメインソケット
アドレスを生成します。特に、指定したホストが IPv4 および IPv6 の両方の
アドレスを持ち、稼働中のシステムがその両方をサポートしている場合、IPv4 と
IPv6 の両方のソケットアドレスが返ります。もし、@var{host} が複数の
IP アドレスをもつ場合、ソケットアドレスはそれぞれのIPアドレス毎に生成
されます。自分のネットワークアプリケーションを異るネットワークスタックの
設定の間でこれまでよりはるかにポータブルなものにすることができます。

@var{host} に @code{#f} を渡すと、ローカルな(サーバ)アドレスが生成されます。
@var{port} 引数に整数のかわりに、サービス名(たとえば、@code{"http"})を
わたすこともできます。@var{proto} の値は、@code{tcp} あるいは @code{udp}
のどちらかのシンボルになります。デフォルトでは、@code{tcp} です。

この手続きは常にソケットアドレスのリストを返します。もし、@var{host} の
検索に失敗した場合には、空リストが返ります。
@c COMMON
@end defun

@c EN
@subsubheading Address and string conversion
@c JP
@subsubheading アドレスと文字列との変換
@c COMMON

@defun inet-string->address address
@c EN
Converts string representating of the internet address @var{address}
to an integer address.  If @var{address} is parsed successfully,
returns two values: the integer address value and the recognized
protocol (the constant value @code{2} (= @code{AF_INET})
for IPv4 addresses, and @code{10} (= @code{AF_INET6}) 
for IPv6 addresses).  If @var{address} can't be
parsed, @code{#f} and @code{#f} are returned.
@c JP
文字列で表現されたインターネットアドレス@var{address}を整数のアドレス
に変換します。@var{address}のパーズが成功した場合には値を2つ返します。
ひとつは整数で表現されたアドレスの値、もうひとつは認識されたプロトコル
(定数値で、@code{2} (= @code{AF_INET})ならIPv4アドレス、@code{10} (=
@code{AF_INET6})ならIPv6アドレス)です。@var{address}のパーズに失敗した
ら、@code{#f}と@code{#f}との2つが返ります。
@c COMMON

@example
(inet-string->address "192.168.1.1")
 @result{} 3232235777 and 2
(inet-string->address "::1")
 @result{} 1 and 10
(inet-string->address "::192.168.1.1")
 @result{} 3232235777 and 10
(inet-string->address "ffe0::1")
 @result{} 340116213421465348979261631549233168385 and 10
(inet-string->address "::192.168.1.1")
 @result{} 3232235777 and 10
@end example
@end defun

@defun inet-string->address! address buf
@c EN
Like @code{inet-string->address}, but fills the given u8vector
@var{buf} by the parsed address instead of returning it as
an integer value.  The integer representation of inet addresses 
is likely to be a bignum, and you can avoid creating bignums
with this function.  The given u8vector @var{buf} must be mutable.
Returns the protocol on success, or @code{#f} on failure.
@c JP
@code{inet-string->address}と同じですが、整数値を返すかわりに、与えら
れたu8vectorである@var{buf}をパーズしたアドレスで埋めるところが違いま
す。inetアドレスの整数表現はbignumと同じやりかたです。この関数を使えば
bignumを生成しなくてすみます。与えられたu8vector@var{buf}は変更可能で
なければなりません。変換に成功した場合はプロトコルが、失敗した場合は
@code{#f}が返ります。
@c COMMON

@c EN
The caller must provide big enough buffer.  If @var{buf}
is larger than required, the result is filled from the top
of the u8vector and the rest of the vector remains intact.
@c JP
呼び出し側は格納に十分なバッファを用意しなければなりません。@var{buf}
が必要な分より大きい場合には結果は先頭から詰められ、ベクタの他の部分は
そのままになります。
@c COMMON

@example
(let* ((buf (make-u8vector 16 0))
       (proto (inet-string->address! "192.168.1.1" buf)))
  (list proto buf))
 @result{} (2 #u8(192 168 1 1 0 0 0 0 0 0 0 0 0 0 0 0))
@end example
@end defun


@defun inet-address->string address protocol
@c EN
Converts the given @var{address} to its string representation
of the protocol @var{protocol}, which can be either
@code{2} (the constant @code{AF_INET}) or @code{10}
(the constant @code{AF_INET6}).
An integer or a u8vector can be used as @var{address}.  If it is
a u8vector, only the necessary portion of the vector is read; i.e.
the vector can be longer than the required length.
@c JP
与えれれた@var{address}をプロトコル@var{protocol}の文字列表現に変換し
ます。プロトコルとしては@code{2} (定数@code{AF_INET})または@code{10}
(定数@code{AF_INET6})が指定可能です。@var{address}としては整数または
u8vectorが使えます。u8vectorをつかった場合には必要な部分だけが読み込ま
れます。したがって、必要な長さ以上あるベクタでもかまいません。
@c COMMON

@example
(inet-address->string 3232235777 AF_INET)
  @result{} "192.168.1.1"

(inet-address->string '#u8(192 168 1 1) AF_INET)
  @result{} "192.168.1.1"

(inet-address->string 3232235777 AF_INET6)
  @result{} "::c0a8:101"
@end example
@end defun


@node High-level network functions, Low-level socket interface, Socket address, Networking
@subsection High-level network functions
@c NODE 高レベルネットワーク手続き

@deftp {Builtin Class} <socket>
@clindex socket
@c EN
Abstracts a socket, a communication endpoint.

For a connection-oriented socket, you can access the communication
channel by two ports associated to the socket, one for input and
another for output.  @code{socket-input-port} and @code{socket-output-port}
returns those ports, respectively.
@c JP
通信の終端であるところのソケットを表すクラスです。

コネクション型のソケットには、入力用と出力用の2つのポートが結び付いており、
それらを使って通信路にアクセスできます。
@code{socket-input-port}と@code{socket-output-port}はそれぞれ
入力用、出力用のポートを返します。

@c COMMON
@end deftp

@c EN
The following three functions are convenient ways to create
a connection-oriented socket.  Those functions
are to provide an easy methods for typical cases,
but have less control.  If you need more than these functions
provide, use low-level interface.
@c JP
以下の3つは手軽にコネクション型のソケットを作成する
ための手続きです。 大抵の場合はこれらの手続きで間に合いますが、
より細かい制御が必要な場合は低レベルAPIを使用して下さい。
@c COMMON

@defun make-client-socket :optional address-spec @dots{}
@c EN
Creates and returns a client socket, connected to the address
specified by @var{address-spec} @dots{}.
@c JP
引数@var{address-spec} @dots{}によって指定されるアドレスと接続する
クライアントソケットを作成して返します。
@c COMMON

@table @code
@item (make-client-socket 'unix @var{path})
@c EN
The client socket is connected to the unix domain server socket
of address @var{path}.
@c JP
@var{path}で待っているUnixドメインのサーバーソケットに接続します。
@c COMMON
@item (make-client-socket 'inet @var{host} @var{port})
@c EN
The client socket is connected to the inet domain server socket
with hostname @var{host} and port @var{port}.   TCP protocol is
assumed.   @var{host} can be either a hostname, or
a dotted decimal notation of IPv4 address.
If gauche is compiled with --enable-ipv6, IPv6 address notation
can also be used.  @var{Port} must be an exact integer specifying
a port number, or a string service name (e.g. @code{"http"}).

If gauche is compiled with --enable-ipv6, and the hostname is given,
and the hostname has both IPv6 and IPv4 addresses, then
IPv6 connection is tried first, and IPv4 is used when IPv6 fails.
@c JP
ホスト@var{host}のポート@var{port}にTCPで接続します。
@var{host}はIPv4アドレスのドット表記でもホスト名でも
構いません。Gaucheが--enable-ipv6でコンパイルされていれば、
IPv6形式のアドレス表記も受け付けます。
@var{port}はポート番号を指定する正確な整数か、文字列のサービス名
(@code{"http"}等)でなければなりません。

Gaucheが--enable-ipv6でコンパイルされており、ホスト名が渡されて、
そのホスト名がIPv6とIPv4の両方のアドレスを持っていた場合は、
最初にIPv6での接続が試みられ、それが失敗した場合にIPv4での接続が試みられます。
@c COMMON
@item (make-client-socket @var{host} @var{port})
@c EN
This works the same as above.  This form is for compatibility with STk.
@c JP
上と同じです。この形式はSTkとの互換性のために提供されています。
@c COMMON
@item (make-client-socket @var{sockaddr})
@c EN
If an instance of @code{<sockaddr>} is passed,
a socket suitable for @var{sockaddr} is opened and then connected
to the given address.
@c JP
@code{<sockaddr>}クラスのインスタンスが渡された場合には、それに対応する
ソケットをオープンし、そのアドレスへ接続します。
@c COMMON
@end table

@c EN
This function raises an error if it cannot create a socket,
or cannot connect to the specified address.
@c JP
ソケットを作成できなかったり、指定されたアドレスに接続できなかった場合は
エラーが報告されます。
@c COMMON

@example
(make-client-socket 'inet "www.w3.com" 80)
  @result{} ;@r{a socket connected to www.w3.com, port 80}
(make-client-socket "127.0.0.1" 23)
  @result{} ;@r{a socket connected to localhost, port 23}
(make-client-socket 'unix "/tmp/.sock"
  @result{} ;@r{a socket connected to a unix domain socket "/tmp/.sock"}
@end example
@end defun

@defun make-server-socket :optional address-spec @dots{}
@c EN
Creates and returns a server socket, listening the address
specified by @var{address-spec}.
@c JP
@var{address-spec}にて接続を待つサーバソケットを作成して返します。
@c COMMON

@table @code
@item (make-server-socket 'unix @var{path} [:backlog @var{num}])
@c EN
The socket is bound to a unix domain socket with a name @var{path}.
The keyword argument @var{backlog} is passed to @code{socket-listen}
to specify the maximum number of connection request the server can keep
befor accepting them.  The default is 5.  If your server is very busy
and you see "connection refused" often, you might want to increase it.
@c JP
パス名@var{path}を持つUnixドメインソケットが作成されます。
キーワード引数@var{backlog}に渡された数値は@code{socket-listen}に渡され、
サーバが接続要求を貯めておくキューの最大長を指定します。
デフォルトは5です。多忙なサーバーで、"connection refused"が頻発する場合は
この数値を増やしてみて下さい。
@c COMMON
@item (make-server-socket 'inet @var{port} [:reuse-addr? @var{flag}] [:sock-init @var{proc}] [:backlog @var{num}])
@c EN
The socket is bound to an inet domain TCP socket, listening
port @var{port}, which must be a non-negative exact integer
or a string service name (e.g. @code{"http"}).
If @var{port} is zero, the system assigns one of available port numbers.
If a keyword argument @var{reuse-addr?} is given and true,
@code{SO_REUSEADDR} option is set to the socket before bound to
the port.  This allows the process to bind the server socket
immediately after other process releases the port.
@c JP
ポート@var{port}にて接続を待つInetドメインのTCPソケットが作成されます。
@var{port}は非負の正確な整数か、文字列のサービス名(@code{"http"}等)でなければなりません。
@var{port}が零の場合はシステムが適当なポート番号を割り当てます。
キーワード引数@var{reuse-addr?}に真の値が与えられた場合は、
ソケットに@code{SO_REUSEADDR}オプションがセットされます。
その場合、他のプロセスが解放したばかりの(TCP)ポートでも
エラーとならずに使うことができます。
@c COMMON

@c EN
If keyword argument @code{sock-init} is given, it should be a procedure
that takes two arguments, a created socket and the socket address.
The procedure is called just after the socket is created.  It is
useful to set some special socket options.
@c JP
キーワード引数@code{sock-init}が与えられた場合、@code{proc} が出来たての
ソケットとそのソケットアドレスを引数にして呼び出されます。
つまり、@code{proc} はそのような2つの引数を取る手続きでなければなりません。
ソケットに特殊なオプションを設定したいような場合に便利です。

@c EN
The keyword argument @var{backlog} is the same as in unix sockets;
see the description above.
@c JP
キーワード引数@var{backlog}はunixソケットと同じです。上の記述を参照して下さい。

@c COMMON
@item (make-server-socket @var{port} [:reuse-addr? @var{flag}] [:sock-init @var{proc}][:backlog @var{num}])
@c EN
This is a synonym to the above form (except @var{port} must be 
an integer).  This form is backward-compatible
with STk's @code{make-server-socket}.
@c JP
これは、@var{port}が整数でなければならないことを除けば、
上の形式と同じ動作をします。STkの@code{make-server-socket}との
互換性のために提供されています。
@c COMMON
@item (make-server-socket @var{sockaddr} [:reuse-addr? @var{flag}][:sock-init @var{proc}][:backlog @var{num}])
@c EN
This form explicitly specifies the socket address to listen
by an instance of @code{<sockaddr>}.
@c JP
この形式は、listenするソケットアドレスを@code{<sockaddr>}のインスタンスで
明示的に指定します。
@c COMMON
@end table

@example
(make-server-socket 'inet 8080)
  @result{} #<socket (listen "0.0.0.0:8080")>
(make-server-socket 8080)
  @result{} #<socket (listen "0.0.0.0:8080")>
(make-server-socket 'inet 0)
  @result{} #<socket (listen "0.0.0.0:35628")>
(make-server-socket 'unix "/tmp/.sock")
  @result{} #<socket (listen "/tmp/.sock")>
@end example
@end defun

@defun make-server-sockets host port :key reuse-addr? sock-init
@c EN
Creates one or more sockets that listen at @var{port}
on all available network interfaces of @var{host}.
You can specify a service name (such as "@code{http}") to
@var{port}, as well as an integer port number.
Returns a list of opened, bound and listened sockets.

This procedure is particularly useful when the host
has multiple protocol stacks, such as IPv4 and IPv6.

The meaning of keyword arguments are the same as of @code{make-server-socket}.
@c JP
@var{host} が持つすべての利用可能なネットワークインタフェース上の
@var{port} で接続を待つソケットを生成し、それらのリストを返します。
@var{port} には数字のポート番号のほか、"@code{http}"などの
サービス名も指定できます。

この手続きは、ホストが複数のプロトコルスタック(IPv4とIPv6など)を
持つ場合に特に便利です。

キーワード引数の意味は@code{make-server-socket}のと同じです。
@c COMMON
@end defun

@c EN
Several accessors are available on the returned socket object.
@c JP
上記の手続きによって返されたソケットオブジェクトに対して、
以下のようなアクセサがあります。
@c COMMON

@defun socket-address socket
@c EN
Returns a socket address associated with @var{socket}.
If no address has been associated to the socket, @code{#f} is returned.
@c JP
ソケット@var{socket}のソケットアドレスを返します。
ソケットにアドレスがまだバインドされていない場合は@code{#f}が返ります。
@c COMMON
@end defun

@defun socket-input-port socket :key (buffering :modest)
@defunx socket-output-port socket :key (buffering :line)
@c EN
Returns an input and output port associated with @var{socket},
respectively.
@c JP
それぞれ、@var{socket}からデータを読みだす入力ポート、および
@var{socket}にデータを書き出す出力ポートを返します。
@c COMMON

@c EN
The keyword argument @var{buffering} specifies the buffering mode
of the port.  @xref{File ports}, for explanation of the
buffering mode.
@c JP
キーワード引数@var{buffering}はポートのバッファリングモードを
指定します。バッファリングモードの説明は@ref{File ports}にあります。
@c COMMON
@end defun

@defun socket-close socket
@c EN
Closes @var{socket}.  All the ports associated to
@var{socket} are closed as well.
@c JP
ソケット@var{socket}をクローズします。@var{socket}の入出力ポートも
クローズされます。

@c EN
Note: as of release 0.7.2, this procedure does not shutdown
the connection.  It is because @var{socket} may be referenced
by forked process(es) and you might want to close it without
interfering the existing connection.   You can call
@code{socket-shutdown} to shutdown the connection explicitly.
@c JP
注意: リリース 0.7.2 より、この手続きは接続をシャットダウンしないように
なりました。その理由は、@var{socket} が fork した別プロセスから参照され
ている可能性があり、既存の接続を妨害することなくクローズしたい場合がある
からです。@code{socket-shutdown} を呼べば接続を明示的にシャットダウンできます。
@c COMMON
@end defun

@defun call-with-client-socket socket proc :key input-buffering output-buffering
@c EN
@var{socket} must be a connected client socket.  @var{proc} is called
with two arguments, an input port that reads from the socket
and an output port that writes to the socket.
The socket is closed after @var{proc} returns or @var{proc}
raises an error.
@c JP
@var{socket}は接続されたクライアントソケットでなければなりません。
@var{proc}がソケットから読み出す入力ポートと、
ソケットに書き出す出力ポートを引数として呼ばれます。
@var{proc}が正常終了するか、エラーを投げた場合にソケットはクローズされます。
@c COMMON

@c EN
The keyword arguments @var{input-buffering} and @var{output-buffering}
are, if given, passed as the @var{buffering} keyword arguments
of @code{socket-input-port} and @code{socket-output-port}, respectively.
@c JP
キーワード引数@var{input-buffering}と@var{output-buffering}が与えられた場合、
それらはそれぞれ@code{socket-input-port}と@code{socket-output-port}の
@var{buffering}キーワード引数へと渡されます。
@c COMMON
@end defun

@c EN
This is an example of usage of high-level socket functions,
a very simple http client.
@c JP
これは高レベルソケット手続きを使った、非常に単純なhttpクライアントです。
@c COMMON

@example
#!/usr/bin/env gosh
(use gauche.net)

(define (usage)
  (display "Usage: swget url\n" (current-error-port))
  (exit 1))

;; Returns three values: host, port, and path.
(define (parse-url url)
  (rxmatch-let (rxmatch #/^http:\/\/([-A-Za-z\d.]+)(:(\d+))?(\/.*)?/ url)
      (#f host #f port path)
    (values host port path)))

(define (get url)
  (receive (host port path) (parse-url url)
    (call-with-client-socket
        (make-client-socket 'inet host (string->number (or port "80")))
      (lambda (in out)
        (format out "GET ~a HTTP/1.0\r\n" path)
        (format out "host: ~a\r\n\r\n" host)
        (flush out)
        (copy-port in (current-output-port))))))

(define (main args)
  (if (= (length args) 2)
      (get (cadr args))
      (usage))
  0)
@end example


@node Low-level socket interface, Netdb interface, High-level network functions, Networking
@subsection Low-level socket interface
@c NODE 低レベルソケットインタフェース

@c EN
These functions provide APIs similar to the system calls.
Those who are familiar to programming with socket APIs will
find these functions useful since you can have more detailed control over
the sockets.
@c JP
ここにある関数群はシステムコールと類似した API を提供します。
ソケット API プログラミングに慣れていれば、ソケットをより細かく
制御できるので、役に立つでしょう。
@c COMMON

@defun make-socket domain type :optional protocol
@c EN
Returns a socket with specified parameters.
@c JP
パラメータで指定したソケットを返します。
@c COMMON
@end defun

@defvr {Constant} PF_UNIX
@defvrx {Constant} PF_INET
@defvrx {Constant} PF_INET6
@c EN
These constants are bound to the system's constants
@code{PF_UNIX}, @code{PF_INET} and @code{PF_INET6}.
You can use those values for @var{domain} argument of @code{make-socket}.

(@code{PF_INET6} is defined only if the underlying operating
system supports IPv6.)
@c JP
これらの定数はそれぞれシステムが提供する@code{PF_UNIX}、@code{PF_INET}、
@code{PF_INET6}に束縛されています。
これらの値を@var{make-socket}の@var{domain}引数に使うことができます。

(@code{PF_INET6}はオペレーティングシステムがIPv6をサポートしている場合にのみ
定義されます。)
@c COMMON
@end defvr

@defvr {Constant} AF_UNIX
@defvrx {Constant} AF_INET
@defvrx {Constant} AF_INET6
@c EN
These constants are bound to @code{AF_UNIX}, 
@code{AF_INET} and @code{AF_INET6}.

(@code{AF_INET6} is defined only if the underlying operating
system supports IPv6.)
@c JP
これらの定数はそれぞれ、@code{AF_UNIX}、@code{AF_INET}、@code{AF_INET6}
に束縛されています。

(@code{AF_INET6}はオペレーティングシステムがIPv6をサポートしている場合にのみ
定義されます。)
@c COMMON
@end defvr

@defvr {Constant} SOCK_STREAM
@defvrx {Constant} SOCK_DGRAM
@defvrx {Constant} SOCK_RAW
@c EN
These constants are bound to @code{SOCK_STREAM}, @code{SOCK_DGRAM}
and @code{SOCK_RAW}, and suitable to pass to the @var{type} argument
of @code{make-socket}.
@c JP
これらの定数はそれぞれ、@code{SOCK_STREAM}、@code{SOCK_DGRAM}、
@code{SOCK_RAW} に束縛されており、
@var{make-socket}の@var{type}引数に使うことができます。
@c COMMON
@end defvr

@defun socket-fd socket
@c EN
Returns an integer system file descriptor of the underlying socket.
@c JP
ソケットのもつ整数のシステムファイルディスクリプタを返します。
@c COMMON
@end defun


@defun socket-status socket
@c EN
Returns a internal status of @var{socket}, by one of the following
symbols.
@multitable {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item none
@tab The socket is just created.
@item bound
@tab The socket is bound to an address by @code{socket-bind}
@item listening
@tab The socket is listening a connection by @code{socket-listen}
@item connected 
@tab The socket is connected by @code{socket-connect} or @code{socket-accept}.
@item shutdown
@tab The socket is shutdown by @code{socket-shutdown}
@item closed
@tab The socket is closed by @code{socket-close}.
@end multitable
@c JP
@var{socket} の内部状態を、以下のシンボルのどれかで返します。
@multitable {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item none
@tab 生成直後
@item bound
@tab @code{socket-bind} によって、あるアドレスに束縛されている
@item listening
@tab @code{socket-listen} によって、接続をリッスンしている
@item connected 
@tab @code{socket-connect} あるいは @code{socket-accept} によって接続されている
@item shutdown
@tab @code{socket-shutdown} によってシャットダウンされた
@item closed
@tab @code{socket-close} によってクローズされた
@end multitable
@c COMMON
@end defun

@defun socket-bind socket address
@c EN
Binds @var{socket} to the local network address @var{address}.
It is usually used to associate specific address to the server port.
If binding failed, an error is signalled (most likely the address is
already in use).

For the inet domain address, you can pass @var{address} with port=0;
the system assigns the port number and sets the actual address to
the @code{address} slot of @var{socket}.
@c JP
@var{socket} をローカルネットワークアドレス @var{address} に束縛します。
通常は、特定のアドレスをこのサーバのポートに結びつけるのに用います。
もし、束縛が失敗したら(多くの場合、そのアドレスが既に使用されている)、
エラーシグナルが発生します。

INET ドメインアドレスの場合には port=0 とした @var{address} を
渡せます。システムがポート番号を割当て、@var{socket} の
@code{address} スロットに実際のアドレスをセットします。
@c COMMON
@end defun

@defun socket-listen socket backlog
@c EN
Listens @var{socket}.  The socket must be already bound to some
address.  @var{backlog} specifies maximum number of connection
requests to be queued.
@c JP
@var{socket} をリッスンします。ソケットは既になんらかのアドレスに
束縛されていなければなりません。@var{backlog} はキューに入れる
接続要求の最大数を指定します。
@c COMMON
@end defun

@defun socket-accept socket
@c EN
Accepts a connection request coming to @var{socket}.
Returns a new socket that is connected to the remote entity.
The original @var{socket} keeps waiting for further connections.
If there's no connection requests, this call waits for one to come.

You can use @code{sys-select} to check if there's a pending connection
request.
@c JP
@var{socket}に来た接続要求をアクセプトします。リモートエンティティへ
接続している新しいソケットを返します。元の @var{socket} は引き続き
次の接続要求を待ちます。接続要求がないとき、これの呼出しは要求が
一つ来るまで待ちます。

接続要求をペンディングしているかどうかをチェックするのに
@code{sys-select}が使えます。
@c COMMON
@end defun

@defun socket-connect socket address
@c EN
Connects @var{socket} to the remote address @var{address}.
This is the way for a client socket to connect to the remote entity.
@c JP
@var{socket} をリモートアドレス @var{address} に接続します。
これは、クライアントソケットをリモートエンティティに接続するための
方法です。
@c COMMON
@end defun

@defun socket-shutdown socket how
@c EN
Shuts down connection of @var{socket}.  If @var{how} is @code{SHUT_RD} (or 0),
the receive channel of @var{socket} is disallowed.
If @var{how} is @code{SHUT_WR} (or 1), the send channel of
@var{socket} is disallowed.
If @var{how} is @code{SHUT_RDWR} (or 2), both receive and send channels are
disallowed.  It is an error to call this function on a non-connected socket.

If you shut down the send channel of the socket, the remote peer
sees EOF from its receive channel.  This is useful if the remote peer
expects EOF before sending something back to you.
@c JP
@var{socket} の接続をシャットダウンします。@var{how} が@code{SHUT_RD} (0) なら、
@var{socket} の受信チャネルが不許可となります。@var{how} が@code{SHUT_WR} (1)なら、
@var{socket} の送信チャネルが不許可となります。@var{how} が@code{SHUT_RDWR} (2)なら、
@var{socket} の送受信チャネルの両方が不許可となります。
接続していないソケットに対して、この手続きを呼ぶとエラーになります。

ソケットの送信チャネルをシャットダウンすると、リモート側の受信チャネル
に EOF があらわれます。これは、リモート側が何かを送り返す前に EOF
を受けとることを期待している場合、便利です。
@c COMMON
@end defun

@defun socket-getsockname socket
@c EN
Returns a @code{<sockaddr>} instance that is the local address of
@var{socket}.
@c JP
@var{socket}のローカル側アドレスを表す@code{<sockaddr>}インスタンスを返します。
@c COMMON
@end defun

@defun socket-getpeername socket
@c EN
Returns a @code{<sockaddr>} instance that is the peer address of
@var{socket}.
@c JP
@var{socket}の通信相手のアドレスを表す@code{<sockaddr>}インスタンスを返します。
@c COMMON
@end defun

@defun socket-send socket msg :optional flags
@defunx socket-sendto socket msg to-address :optional flags.
@c EN
Interfaces to @code{send(2)} and @code{sendto(2)}, respectively.
Transmits the content of @var{msg} through @var{socket}.
@var{msg} can be either a string or a uniform vector; if you send
binary packets, uniform vectors are recommended.

When @code{socket-send} is used, @var{socket} must already be connected.
On the other hand, @code{socket-sendto} can be used for non-connected
socket, and the destination address is specified by 
a @code{<sockaddr>} instance @var{to-address}.
@c JP
それぞれ、@code{send(2)} および @code{sendto(2)} へのインタフェース。
@var{msg} の内容を @var{socket} を通じて送出します。
@var{msg}は文字列もしくはユニフォームベクタでなければなりません。
バイナリパケットを送る場合はユニフォームベクタの使用を推奨します。

@code{socket-send} を使うときには、@var{socket} は既に接続されて
いなければなりません。他方、@code{socket-sendto} は未接続の
ソケットに対して使用でき、送出先アドレスは @code{<sockaddr>} のインスタンス
@var{to-address} で指定します。
@c COMMON

@c EN
The optional @var{flags} can be a bitwise OR of the integer
constants @code{MSG_*}.  See the system's manpage of @code{send(2)}
and @code{sendto(2)} for the details.
@c JP
オプション引数 @var{flags} は整数定数 @code{MSG_*} のビット毎のORで
指定できます。詳しくはシステムの man ページ @code{send(2)} および
@code{sendto(2)} を見て下さい。
@c COMMON
@end defun

@defun socket-sendmsg socket msghdr :optional flags
@c EN
Sends a packet described by @var{msghdr} through @var{socket}
using @code{sendmsg(3)}.  The @var{msghdr} argument must be a
string or u8vector, and it must be prepared as a binary representation
of @code{struct msghdr}.  A reliable way to build a @var{msghdr} is
to use @code{socket-buildmsg} described below.

The @var{flags} argument is the same as @code{socket-send} and
@code{socket-sendto}.

Returns number of octets sent.
@c JP
@code{sendmsg(3)}を使って、@var{msghdr}で記述されるパケットを@var{socket}
を通じて送ります。@var{msghdr}引数は文字列かu8vectorで、
@code{struct msghdr}構造体のバイナリ表現でなければなりません。
@var{msghdr}引数に適したデータを構築する確かな方法は、下に述べる
@code{socket-buildmsg}を使うことです。

@var{flags}引数は@code{socket-send}および@code{socket-sendto}と同じです。

送り出されたオクテット数を返します。
@c COMMON

@c EN
This procedure is not yet supported under the Windows native platform.
You can use the feature identifier @code{gauche.os.windows} to check
availability of this procedure (@xref{Platform-dependent features}).
@c JP
この手続きはWindowsネイティブ環境では(まだ)サポートされません。
これが使えるかどうかは、機能識別子@code{gauche.os.windows}を使って判定
できます (@ref{Platform-dependent features}参照)。
@c COMMON
@end defun

@defun socket-buildmsg addr iov control flags :optional buf
@c EN
Builds a binary representation of @code{struct msghdr} which is
suitable to be given to @code{socket-sendmsg}.
You have to be familiar with @code{sendmsg(3)} system call
to understand this procedure.

The @var{addr} argument must be an instance of @code{<sockaddr>}
or @code{#f}.  If it is a sockaddr, the @code{msg_name} field
of the msghdr is filled with the address.

The @var{iov} argument must be a vector or @code{#f}.  If it is
a vector, each element must be either a string or a u8vector.
They are used to fill @code{msg_iov} field of the msghdr.
Their contents will be concatenated in the kernel to make a payload.

The @var{control} argument represents ancillary data, a.k.a. cmsg.
It can be @code{#f} if you don't need ancillary data.  Otherwise,
it must be a list in the following form:
@example
((@var{level} @var{type} @var{data}) @dots{})
@end example
Where @var{level} and @var{type} are exact integers,
and @var{data} is either a string or a u8vector.
The former two are used to fill cmsg's @code{cmsg_level}
and @code{cmsg_type} fields.  The @var{data} is for
cmsg's data (@code{cmsg_len} is calculated from @var{data}).
 
The @var{flags} argument is used to fill @code{msg_flags}.

If the @var{buf} argument is @code{#f} or omitted, new memories
are allocated to construct the msghdr.  If a mutable
u8vector is given to @var{buf}, @code{socket-buildmsg} tries
to use it to construct the msghdr as much as possible; it allocates
memory only if @var{buf} is used up.

Returns the constructed msghdr as a u8vector.
@c JP
@code{struct msghdr}構造体のバイナリ表現を構築します。
作られたmsghdrは@code{socket-sendmsg}に渡すことができます。
この手続きを理解するには、@code{sendmsg(3)}の動作をよく知っていることが必要です。

@var{addr}引数は@code{<sockaddr>}のインスタンスか@code{#f}でなければ
なりません。@code{<sockaddr>}のインスタンスである場合、そのアドレスが
msghdrの@code{msg_name}フィールドに使われます。

@var{iov}引数はベクタか@code{#f}でなければなりません。ベクタの場合、
各要素は文字列かu8vectorでなければなりません。これはmsghdrの
@code{msg_iov}フィールドに使われます。各要素の内容はカーネル内で
結合されてペイロードとなります。

@var{control}引数は補助データ(cmsg)を指定します。補助データが必要ない
場合は@code{#f}を渡せます。そうでなければ、@var{control}引数は
次の形式を持つリストでなければなりません。
@example
((@var{level} @var{type} @var{data}) @dots{})
@end example
@var{level}と@var{type}は正確な整数で、@var{data}は文字列かu8vectorの
いずれかです。
最初の2つはそれぞれcmsgの@code{cmsg_level}と
@code{cmsg_type}フィールドを指定します。@var{data}はcmsgのデータとなります。
(@code{cmsg_len}は@var{data}から計算されます)。
 
@var{flags}引数は@code{msg_flags}フィールドに使われます。

@var{buf}引数が省略されるか@code{#f}の場合、msghdrを構築するのに
必要なメモリがアロケートされます。書き換え可能なu8vectorが@var{buf}
に渡されれば、@code{socket-buildmsg}はできるだけそれをバッファに使って
msghdrを構築しようとします。@var{buf}で領域が不足する場合のみ
新たなメモリをアロケートします。

この手続きは構築されたmsghdrをu8vectorとして返します。
@c COMMON

@c EN
This procedure is not yet supported under the Windows native platform.
You can use the feature identifier @code{gauche.os.windows} to check
availability of this procedure (@xref{Platform-dependent features}).
@c JP
この手続きはWindowsネイティブ環境では(まだ)サポートされません。
これが使えるかどうかは、機能識別子@code{gauche.os.windows}を使って判定
できます (@ref{Platform-dependent features}参照)。
@c COMMON
@end defun

@defun socket-recv! socket buf :optional flags
@c EN
Interface to @code{recv(2)}.  Receives a message from @var{socket},
and stores it into @var{buf}, which must be a mutable uniform vector.
Returns the number of bytes actually written.   @var{socket} must
be already connected.  If the size of @var{buf} isn't enough to
store the entire message, the rest may be discarded depending on
the type of @var{socket}.
@c JP
@code{recv(2)}へのインタフェースです。@var{socket}からメッセージを
受信し、それを変更可能なユニフォームベクタ@var{buf}へと書き込みます。
そして実際に書き込まれたバイト数を返します。
@var{socket}は既にコネクトされていなければなりません。
@var{buf}の大きさが受信したメッセージより小さい場合、@var{socket}の
タイプによっては残りのメッセージは捨てられる可能性があります。
@c COMMON

@c EN
The optional @var{flags} can be a bitwise OR of the integer
constants @code{MSG_*}.  See the system's manpage of @code{recv(2)}
for the details.
@c JP
オプション引数 @var{flags} は整数定数 @code{MSG_*} のビット毎のORで
指定できます。詳しくはシステムの man ページ @code{recv(2)}を見て下さい。
@c COMMON
@end defun

@defun socket-recvfrom! socket buf addrs :optional flags
@c EN
Interface to @code{recvfrom(2)}.  Receives a message from
@var{socket}, which may be unconnected, and stores it to
a mutable uniform vector @var{buf}.  Like @var{socket-recv},
if the size of @var{buf} isn't enough to store the entire message, 
the rest may be discarded depending on the type of @var{socket}.

Returns two values; the number of bytes actually written into
@var{buf}, and an instance of a subclass of @code{<sys-sockaddr>}
which shows the sender's address.

The @var{addrs} argument must be a list of instances of socket
addresses, optionally its last cdr being @code{#t} (as a special
case, if there's zero addresses to pass, just @code{#t} may be given).
The content of each address doesn't matter; if the protocol family
of one of them matches the sender's address, the sender's address
is written into the passed sockaddr object.  By listing sockaddrs
of possible families, you can count on @code{socket-recvfrom!}
to allocate no memory on successful operation.  It is useful if
you call @code{socket-recvfrom!} in a speed-sensitive inner loop.

If the sender's address family doesn't match any of the addresses
given to @var{addrs}, the behavior depends on whether the list is
terminated by @code{()} or @code{#t}.  If it is terminated by @code{()},
(i.e. @var{addrs} is a proper list), the sender's address is simply
discarded and @code{socket-recvfrom!} returns @code{#f} as the
second value.  If the list is terminated by @code{#t}, 
@code{socket-recvfrom!} allocates a fresh sockaddr object and
returns it as the second value.  

Two simple cases: If you pass @code{()} to @var{addrs}, the sender's
address is always discarded, which is useful if @var{socket} is
connected (that is, you already know your sender's address).
If you pass @code{#t} to @var{addrs}, a new socket address
object is always allocated for the sender's address,
which is convenient if you don't mind memory allocation.
@c JP
@code{recvfrom(2)}へのインタフェースです。@var{socket}からメッセージを
受け取り、変更可能なユニフォームベクタへ書き込みます。@var{socket}は
コネクトされていなくても構いません。@code{socket-recv}と同様に、
@var{buf}の大きさがメッセージ全てを保持するのに十分でない場合、
@var{socket}のタイプによっては残りのメッセージは捨てられます。

ふたつの値を返します。実際に@var{buf}に書かれたバイト数と、
送信者のアドレスを示す@code{<sys-sockaddr>}のサブクラスのインスタンスです。

@var{addrs}引数はソケットアドレスインスタンスのリストでなければなりません。
ただし、リストの終端 (最後の@code{cdr}) は@code{#t}であっても許されます。
(この特殊な場合として、@var{addrs}引数にただ@code{#t}を渡すことも許されます)。
@var{addrs}引数に渡されたソケットアドレスの中身は何でも構いません。
送信者のアドレスファミリーに一致するソケットアドレスインスタンスが@var{addrs}
中にあった場合、@code{socket-recvfrom!}はそのインスタンスに直接
送信者のアドレスを書き込みます。受信し得る全てのアドレスファミリのソケットアドレスを
リストで渡しておけば、@code{socket-recvfrom!}が(成功時には)
メモリアロケーションを行わないことが保証されます。これは
速度が重要となるタイトなループ内で@code{socket-recvfrom!}を呼ぶ場合に
重要です。

送信者のアドレスファミリに一致するソケットアドレスがあたえられなかった場合、
@code{socket-recvfrom!}の振舞いは@var{addrs}のリスト終端の値によります。
@var{addrs}が@code{()}で終端されていた場合 (@var{addrs}が真性リストで
あった場合)、送信者のアドレスは捨てられ、@code{socket-recvfrom!}は
二番めの値として@code{#f}を返します。@var{addrs}が@code{#t}で終端
されていた場合、@code{socket-recvfrom!}は新たなソケットアドレス
インスタンスを作成して返します。

簡単な場合として次の二つがあります：@var{addrs}に@code{()}が渡された場合、
送信者のアドレスは常に捨てられます。@var{socket}がコネクトされていれば
送信者のアドレスは既にわかっているので、そういう場合に便利でしょう。
一方@var{addrs}に@code{#t}を渡せば、常に新しいソケットアドレスが
アロケートされて返されます。メモリアロケーションについて気にしなくても
良い場合は便利でしょう。
@c COMMON

@c EN
The optional @var{flags} can be a bitwise OR of the integer
constants @code{MSG_*}.  See the system's manpage of @code{recvfrom(2)}
for the details.
@c JP
オプション引数 @var{flags} は整数定数 @code{MSG_*} のビット毎のORで
指定できます。詳しくはシステムの man ページ @code{recvfrom(2)}を見て下さい。
@c COMMON
@end defun


@defun socket-recv socket bytes :optional flags
@defunx socket-recvfrom socket bytes :optional flags
@c EN
Like @code{socket-recv!} and @code{socket-recvfrom!}, but
these returns the received message as a (possibly incomplete)
string, up to @var{bytes} size.  Additionally,
@code{socket-recvfrom} always allocates a socket address
object for the sender's address.
@c JP
@code{socket-recv!}や@code{socket-recvfrom!}と似ていますが、
受け取ったメッセージを(不完全かもしれない)文字列として返します。
@var{bytes}は受信する上限のバイト数を指定します。
@code{socket-recvfrom}はそれに加えて、送信者のアドレスのために
常に新たなソケットアドレスオブジェクトを生成します。
@c COMMON

@c EN
The use of these procedures are discouraged, since they
often returns incomplete strings for binary messages.
Using strings for binary data creates many pitfalls.
Uniform vectors (especially @code{u8vector}s) are for binary data.
(The reason these procedures return strings is merely historical.)
@c JP
これらの手続きの使用はお薦めしません。というのは、バイナリメッセージを
不完全な文字列の形で扱うことになりがちだからです。文字列で
バイナリメッセージを取り扱うことは多くの落とし穴を作ります。
バイナリデータを扱う場合はユニフォームベクタ (特に@code{u8vector}) 
を使うべきでしょう。
(これらの手続きが文字列を返すのは単に歴史的な理由によります)。
@c COMMON
@end defun

@defvar MSG_CTRUNC
@defvarx MSG_DONTROUTE
@defvarx MSG_EOR
@defvarx MSG_OOB
@defvarx MSG_PEEK
@defvarx MSG_TRUNC
@defvarx MSG_WAITALL
@c EN
Pre-defined integer constants to be used as @var{flags} values
for @code{socket-send}, @code{socket-sendto}, @code{socket-recv}
and @code{socket-recvfrom}.   Some of these constants may not be
defined if the underlying operating system doesn't provide them.
@c JP
@code{socket-send}、@code{socket-sendto}、@code{socket-recv} および
@code{socket-recvfrom} の @var{flag} として使う定義済み整数定数。
これらの定数のいくつかは、基盤のＯＳが提供していなければ未定義に
なっています。
@c COMMON
@end defvar

@c EN
Further control over sockets and protocol layers is possible
by getsockopt/setsockopt interface, as described below.
@c JP
以下に解説する getsockopt/setsockopt インタフェースを使えば、
ソケットやプロトコルをさらに制御することができます。
@c COMMON

@defun socket-setsockopt socket level option value
@defunx socket-getsockopt socket level option rsize
@c EN
These are the interface to setsockopt() and getsockopt() calls.
The interface is a bit clumsy, in order to allow full access to
those low-level calls.

@var{socket} must be a non-closed socket object.
@var{level} and @var{option} is an exact integer to specify
the level of protocol stack and the option you want to deal with.
There are several variables pre-bound to system constants listed below.

To set the socket option, you can pass either an exact integer or
a string to @var{value}.  If it is an integer, the value is passed
to setsockopt(2) as C @code{int} value.  If it is a string, the
byte sequence is passed as is.  The required type of value depends on
the option, and Gauche can't know if the value you passed is expected
by setsockopt(2); it is your responsibility to pass the correct values.

To get the socket option, you need to tell the maximum length of expected
result by @var{rsize} parameter, for Gauche doesn't know the amount
of data each option returns.
@code{socket-getsockopt} returns the option value as a byte string.
If you know the option value is an integer, you can pass 0 to @var{rsize};
in that case @code{socket-getsockopt} returns the value as an exact integer.

Note about the name: I tempted to name these function socket-@{set|get@}opt
or socket-@{set|get@}-option,
but I rather took the naming consistency.  Hence duplicated "sock"s.

@c JP
これらは、setsockopt() および getsockopt() を呼ぶための
インタフェースです。このインタフェースが少々ぎこちないのは、
低レベルの呼び出しすべてにアクセスできるようにしているためです。

@var{socket} および @var{option} は、処理する対象の
プロトコルスタックのレベルおよびオプションを指定する
正確な整数です。以下にリストアップしたシステム定数に束縛された
変数があります。

ソケットオプションを設定するには、@var{value} に正確な整数を渡す方法と
文字列を渡す方法があります。それが、整数なら、その値は、C の
@code{int} として setsockopt (2) に渡されます。文字列なら、バイト列が
そのまま渡されます。どの型の値が要求されるかは、オプションに依存します。
Gauche 側では渡された値が setsockopt (2) で期待された型であるかどうかは
知ることができません。正しい値が渡されるかどうかはプログラマの責任です。

ソケットオプションを知るには、結果として期待する最大の長さを @var{rsize}
を使って教える必要があります。Gauche 側は返されるそれぞれのオプションの
合計を知らないからです。
@code{socket-getsockopt} はオプションの値をバイト列として返します。
オプションの値が整数だと、わかっているなら @var{rsize} に0を渡すこと
ができます。その場合 @code{socket-getsockopt} は正確な整数として値を返します。

関数名に関する註: これらの関数の名前を socket-@{set|get@}opt あるいは
socket-@{set|get@}-option にしようかとも思いましたが、結局、命名の
一貫性をとることにしました。それで、"sock" が重複しています。
@c COMMON

@end defun

@c EN
The following predefined variables are provided.
Note that some of them are not available on all platforms.
See manpages @code{socket(7)}, @code{tcp(7)} or @code{ip(7)} of
your system to find out exact specification of those values.

For ``level'' argument:
@c JP
以下のような定義済みの変数が用意されています。
すべてのプラットフォームで利用できるわけではないものも含まれている
ことに注意してください。
これらの値の正確な使用は、お使いのシステムの man ページ @code{socket(7)}、
@code{tcp(7)} あるいは @code{ip(7)} を参照してください。

``level'' 引数
@c COMMON
@defvar SOL_SOCKET
@defvarx SOL_TCP
@defvarx SOL_IP
@c EN
These variables are bound to @code{SOL_SOCKET}, @code{SOL_TCP} and
@code{SOL_IP}, respectively.
@c JP
これらの変数は、それぞれ、@code{SOL_SOCKET}、@code{SOL_TCP} および
@code{SOL_IP} に束縛されています。
@c COMMON
@end defvar

@c EN
For ``option'' argument:
@c JP
``option'' 引数
@c COMMON
@defvar SO_KEEPALIVE
@c EN
Expects integer value.  If it is not zero, enables sending  of
keep-alive messages on connection-oriented sockets.
@c JP
整数が期待されています。0でなければ、コネクション指向ソケットに
キープアライブ(keep-alive)メッセージを送ることができます。
@c COMMON
@end defvar

@defvar SO_OOBINLINE
@c EN
Expects integer value.  If it is not zero, out-of-band data is
directly placed into the receive data stream.  Otherwise
out-of-band  data  is  only passed when the
MSG_OOB flag is set during receiving.
@c JP
整数が期待されています。0でなければ、帯域外データは直接
受信データストリームに乗ります。さもなければ、帯域外データは、受信中に
MSG_OOBフラグが設定されてたときにのみ渡されます。
@c COMMON
@end defvar

@defvar SO_REUSEADDR
@c EN
Expects integer value.  If it is not zero, @code{socket-bind}
allows to reuse local addresses, unless an active listening
socket bound to the address.
@c JP
整数が期待されています。0ではない場合、@code{socket-bind}は、
ローカル・アドレスが、アクティブソケットにリッスンされていない
場合にかぎり、そのアドレスを再利用することを許可されます。

@c COMMON
@end defvar

@defvar SO_TYPE
@c EN
Gets the socket type as an integer (like @code{sock_stream}).
Can be only used with @code{socket-getsockopt}.
@c JP
ソケットの型(@code{sock_stream}など)を整数として取得します。
@code{socket-getsockopt}でのみ使用可能です。
@c COMMON
@end defvar

@defvar SO_BROADCAST
@c EN
Expects integer value.  If it is not zero, datagram sockets
are allowed to send/receive broadcast packets.
@c JP
整数が期待されています。0でなければ、データグラムソケットは
ブロードキャストパケットを送受信することを許されます。
@c COMMON
@end defvar

@defvar SO_PRIORITY
@c EN
Expects integer value, specifying the protocol-defined priority
for all packets to be sent on this socket.
@c JP
整数が期待されています。このソケットで送信されるすべてのパケットに
ついてプロトコル定義の優先順位を指定します。
@c COMMON
@end defvar

@defvar SO_ERROR
@c EN
Gets and clears the pending socket error as an integer.
Can be only used with @code{socket-getsockopt}.
@c JP
保留状態のソケットエラー(整数値)を取得し、それをクリアします。
@code{socket-getsockopt}でのみ使用可能です。
@c COMMON
@end defvar


@defun inet-checksum packet size
@c EN
Calculates one's complement of Internet Checksum (RFC1071) of the
@var{packet}, which must be given as a uniform vector.  First
@var{size} bytes of @var{packet} are used for calculation.
Returned value is in network byte order (big-endian).
It is an error if @var{size} is greater than the size of @var{packet}.

Note: The used algorithm assumes @var{packet} is not too big (< 64K).
@c JP
ユニフォームベクタで与えられる@var{packet}のインターネットチェックサム(RFC1071)
の1の補数を計算して返します。@var{packet}の最初の@var{size}バイトのみが
計算の対象となります。返される値はネットワークバイトオーダ (ビッグエンディアン)
です。@var{packet}より大きな値を@var{size}に指定するとエラーとなります。

註: 使われているアルゴリズムは、@var{packet}がそれほど大きくないこと (< 64K) を
仮定しています。
@c COMMON
@end defun


@node Netdb interface,  , Low-level socket interface, Networking
@subsection  Netdb interface
@c NODE Netdbインタフェース




@deftp {Builtin Class} <sys-hostent>
@clindex sys-hostent
@c EN
A class of objects for network hosts.  Corresponding to
@code{struct hostent} in C.  The following slots are available read-only.
@c JP
このクラスはネットワークホストのオブジェクト用で、
C の @code{struct hostent}
に対応しています。以下のスロットは読み込み専用です。
@c COMMON

@defivar {<sys-hostent>} name
@c EN
The formal name of the host (string).
@c JP
ホストの正式名(文字列)
@c COMMON
@end defivar
@defivar {<sys-hostent>} aliases
@c EN
A list of alias names of the host (list of strings).
@c JP
ホストの別名リスト(文字列のリスト)
@c COMMON
@end defivar
@defivar {<sys-hostent>} addresses
@c EN
A list of addresses (list of strings).  Only ipv4 address is 
supported currently.  Each address is represented by dotted decimal
notation.
@c JP
アドレスのリスト(文字列のリスト)。現時点では IPv4 のアドレスのみサポート
しています。それぞれのアドレスは、ドットつき十進記法で表記されています。
@c COMMON
@end defivar
@end deftp

@defun sys-gethostbyname name
@c EN
Looks up a host named @var{name}.
If found, returns a @code{<sys-hostent>} object.
Otherwise, returns @code{#f}.
@c JP
@var{name}という名前のホストを探し、見つかれば、@code{<sys-hostent>}
オブジェクトを返します。見つからなければ、@code{#f} を返します。
@c COMMON
@example
(let ((host (sys-gethostbyname "www.w3c.org")))
  (list (slot-ref host 'name)
        (slot-ref host 'aliases)
        (slot-ref host 'addresses)))
  @result{} ("www.w3.org" ("www.w3c.org") ("18.29.1.34" "18.29.1.35"))
@end example
@end defun

@defun sys-gethostbyaddr addr proto
@c EN
Looks up a host that has an address @var{addr} of protocol @var{proto}.
@var{addr} is a natural string representation of the address;
for ipv4, it is a dotted decimal notation.  @var{proto} is a
protocol number; only @code{AF_INET} is supported currently.
If the host is found, returns a @code{<sys-hostent>} object.
Otherwise, returns @code{#f}.
@c JP
@var{proto}というプロトコルの、@var{addr}というアドレスを持つホストを
探します。@var{addr}はアドレスの自然な文字列表現で、IPv4 については、
ドットつき十進記法です。@var{proto}はプロトコル番号で、現時点では
@code{AF_INET}のみサポートされています。ホストが見つかれば、
@code{<sys-hostent>}オブジェクトを返します。
見つからなければ、@code{#f} を返します。
@c COMMON
@example
(let ((host (sys-gethostbyaddr "127.0.0.1" AF_INET)))
  (list (slot-ref host 'name)
        (slot-ref host 'aliases)
        (slot-ref host 'addresses))
  @result{} ("localhost" ("localhost.localdomain") ("127.0.0.1"))
@end example
@end defun

@deftp {Builtin Class} <sys-servent>
@clindex sys-servent
@c EN
An entry of the network service database.  Corresponding to
@code{struct servent} in C.  The following slots are available read-only.
@c JP
ネットワークサービスデータベースのエントリです。
C の @code{struct servent}に対応しています。
以下のスロットは読み込み専用です。
@c COMMON

@defivar {<sys-servent>} name
@c EN
The formal name of the service (string).
@c JP
サービスの正式名(文字列)
@c COMMON
@end defivar
@defivar {<sys-servent>} aliases
@c EN
A list of alias names of the service (list of strings).
@c JP
サービスの別名リスト(文字列のリスト)
@c COMMON
@end defivar
@defivar {<sys-servent>} port
@c EN
A port number registered for this service (exact integer).
@c JP
サービスに割り当てられたポート番号(正確な整数)
@c COMMON
@end defivar
@defivar {<sys-servent>} proto
@c EN
A protocol name for this service (string).
@c JP
このサービス用のプロトコル名(文字列)
@c COMMON
@end defivar
@end deftp

@defun sys-getservbyname name proto
@c EN
Looks up the network service database with a service name @var{name} and
a protocol @var{proto}.  Both @var{name} and @var{proto} must be a string.
If a service is found, an instance of @code{<sys-servent>} is returned.
Otherwise, @code{#f} is returned.
@c JP
ネットワークサービスデータベースをサービス名 @var{name} および
プロトコル @var{proto} で検索します。@var{name} および @var{proto}
は文字列でなければなりません。サービスが見つかれば、@code{<sys-servent>}
のインスタンスを返します。見つからなければ、@code{#f} を返します。
@c COMMON
@example
(let ((serv (sys-getservbyname "http" "tcp")))
  (list (slot-ref serv 'name)
        (slot-ref serv 'aliases)
        (slot-ref serv 'port)
        (slot-ref serv 'proto)))
  @result{} ("http" () 80 "tcp")
@end example
@end defun

@defun sys-getservbyport port proto
@c EN
Looks up the network service database with a service port @var{port} and
a protocol @var{proto}.  @var{port} must be an exact integer, and
@var{proto} must be a string.
If a service is found, an instance of @code{<sys-servent>} is returned.
Otherwise, @code{#f} is returned.
@c JP
ネットワークサービスデータベースをサービス名 @var{port} および
プロトコル @var{proto} で検索します。@var{port} は正確な整数でなければ
なりません。また、@var{proto} は文字列でなければなりません。
サービスが見つかれば、@code{<sys-servent>}
のインスタンスを返します。見つからなければ、@code{#f} を返します。
@c COMMON
@example
(let ((serv (sys-getservbyport 6000 "tcp")))
  (list (slot-ref serv 'name)
        (slot-ref serv 'aliases)
        (slot-ref serv 'port)
        (slot-ref serv 'proto)))
  @result{} ("x-server" () 6000 "tcp")
@end example
@end defun

@deftp {Builtin Class} <sys-protoent>
@clindex sys-protoent
@c EN
An entry of the protocol database.   Corresponds to @code{struct protoent}
in C.   The following slots are available read-only.
@c JP
プロトコルデータベースのエントリです。C の @code{struct protoent}に
対応しています。以下のスロットは読み込み専用です。
@c COMMON

@defivar {<sys-servent>} name
@c EN
The formal name of the protocol (string).
@c JP
プロトコルの正式名(文字列)
@c COMMON
@end defivar
@defivar {<sys-servent>} aliases
@c EN
A list of alias names of the protocol (list of strings).
@c JP
プロトコルの別名のリスト(文字列のリスト)
@c COMMON
@end defivar
@defivar {<sys-servent>} proto
@c EN
A protocol number (exact integer).
@c JP
プロトコル番号(正確な整数)
@c COMMON
@end defivar
@end deftp

@defun sys-getprotobyname name
@c EN
Looks up the network protocol database with a name @var{name},
which must be a string.
If a protocol is found, an instance of @code{<sys-protoent>} is returned.
Otherwise, @code{#f} is returned.
@c JP
名前 @var{name} でネットワークプロトコルデータベースを検索します。
名前 @var{name} は文字列でなければなりません。
プロトコルが見つかれば、@code{<sys-protoent>}
のインスタンスを返します。見つからなければ、@code{#f} を返します。
@c COMMON
@example
(let ((proto (sys-getprotobyname "icmp")))
  (list (slot-ref proto 'name)
        (slot-ref proto 'aliases)
        (slot-ref proto 'proto)))
  @result{} ("icmp" ("ICMP") 1)
@end example
@end defun

@defun sys-getprotobynumber number
@c EN
Looks up the network protocol database with a protocol number @var{number},
which must be an exact integer.
If a protocol is found, an instance of @code{<sys-protoent>} is returned.
Otherwise, @code{#f} is returned.
@c JP
プロトコル番号 @var{number} でネットワークプロトコルデータベースを検索
する。プロトコル番号 @var{number} は正確な整数でなければなりません。
プロトコルが見つかれば、@code{<sys-protoent>}
のインスタンスを返します。見つからなければ、@code{#f} を返します。
@c COMMON
@example
(let ((proto (sys-getprotobynumber 17)))
  (list (slot-ref proto 'name)
        (slot-ref proto 'aliases)
        (slot-ref proto 'proto)))
  @result{} ("udp" ("UDP") 17)
@end example
@end defun

@deftp {Builtin Class} <sys-addrinfo>
@clindex sys-addrinfo
@c EN
The new interface to keep address information.
Corresponds to @code{struct addrinfo} in C.
This is only available if gauche is configured with --enable-ipv6 option.
The following slots are provided.
@c JP
アドレス情報を保持する新しいインタフェースです。C の @code{struct addrinfo}
に対応しています。これは gauche が --enable-ipv6 オプションで設定され、
ビルドされた場合にのみ利用可能です。以下のスロットが提供されます。
@c COMMON

@defivar {<sys-addrinfo>} flags
@end defivar
@defivar {<sys-addrinfo>} family
@end defivar
@defivar {<sys-addrinfo>} socktype
@end defivar
@defivar {<sys-addrinfo>} protocol
@end defivar
@defivar {<sys-addrinfo>} addrlen
@end defivar
@defivar {<sys-addrinfo>} addr
@end defivar
@end deftp

@defun sys-getaddrinfo nodename servname hints
@c EN
Returns a list of @code{<sys-addrinfo>} instances from the given @var{nodename},
@var{servname} and @var{hints}.
This is only available if gauche is compiled with --enable-ipv6 option.
@c JP
与えられた @var{nodename}、@var{servname} および @var{hints} から
@code{<sys-addrinfo>} のインスタンスのリストを返します。
これは gauche が --enable-ipv6 オプションで設定され、
ビルドされた場合にのみ利用可能です。
@c COMMON
@end defun

@defun sys-ntohs integer
@defunx sys-ntohl integer
@defunx sys-htons integer
@defunx sys-htonl integer
@c EN
Utility functions to convert 16bit (@code{s}) or 32bit (@code{l}) integers
between @emph{network} byte order (@code{n}) and @emph{host} byte order
(@code{h}).

Scheme API to the netdb interface calls those byte order conversion
functions internally, so you don't usually need them so much as in C 
programs.  However, it may be useful when you're constructing or
analyzing binary packets.  See also @ref{Packing Binary Data} to handle
binary data.
@c JP
16bit (@code{s})もしくは32bit (@code{l}) の整数を
ネットワークバイト順 (@code{n}) とホストバイト順 (@code{h}) の間で
相互変換するユーティリティ関数です。

netdbインタフェースのScheme APIは必要な箇所ではこれらの関数を内部的に
呼んでいるので、Cでプログラミングしている時ほどこれらの関数を必要とする
ことはないでしょう。ただ、バイナリデータパケットを構築したり解析したり
する際は便利かもしれません。バイナリデータの扱いについては
@ref{Packing Binary Data}も参照して下さい。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Parameters, Parsing command-line options, Networking, Library modules - Gauche extensions
@section @code{gauche.parameter} - Parameters
@c NODE パラメータ, @code{gauche.parameter} - パラメータ

@deftp {Module} gauche.parameter
@mdindex gauche.parameter
@c EN
A @emph{parameter} is something like a stateful procedure that takes zero or
one argument.
If no argument is given, the parameter returns the current value it is keeping.
If single argument is given, it will be the current value of the parameter.
A parameter has several advantages over global variables to store
states.
@c JP
「パラメータ」は基本的にゼロもしくは一個の引数を取る状態を持つ手続きとみなせます。
引数が与えられなかった場合、それは内部に保持した値を返します。
一つの引数が与えられた場合、その値が新たなパラメータ内部の値となり、
変更前の値が返されます。
パラメータは状態を保持する手段として、
単なるグローバル変数に比べていくつかの利点を持っています。
@c COMMON

@c EN
Value of parameters are kept for each thread, so you can use
a parameter as a thread-local storage.  When a new thread is
created, it inherits a copy of parameters from its creator thread.
@c JP
パラメータの値はスレッド毎に保持されるので、
パラメータをスレッドローカルな格納領域として利用することができます。
新たに作られたスレッドは、その作成元のスレッドのパラメータのコピーを
受け取ります。
@c COMMON

@c EN
You can give a "filter procedure" that checks the new
value before setting it as the parameter value,
so that you can guarantee the value of the parameter is always sane.
@c JP
パラメータに値がセットされるときに、指定の「フィルタ手続き」を呼んで
値を検査することができます。これにより、パラメータの値が常に正当なもので
あることを保証できます。
@c COMMON

@c EN
With the macro @code{parameterize}, you can change the parameter's
value within certain dynamic scope.   It can effectively
replace dynamically scoped variables.
@c JP
マクロ@code{parameterize}により、特定のダイナミックスコープの中だけ
パラメータの値を変えることができます。これは、実質的にダイナミックスコープを
持つ変数を置き換えることができます。
@c COMMON

@c EN
You can also register callback procedures to be called whenever
the value of the parameter is changed.   It can effectively
replace so-called "traced variables"
@c JP
また、パラメータの値が変更されたときに呼ばれるコールバック手続きを
登録しておくこともできます。これによって実質的に、いわゆる
「traceされた変数」を置き換えることができます。
@c COMMON

@c EN
The basic parameter object feature is defined in SRFI-39.
It also can be found in other Scheme implementations,
including ChezScheme, Chicken and MzScheme.
Gauche's one is upper compatible to SRFI-39.
@c JP
パラメータオブジェクトの基本的な機能はSRFI-39で定義されています。
この機能はまた、ChezScheme、Chicken、MzSchemeなどいくつかのScheme処理系に
見られます。GaucheのパラメータはSRFI-39の上位互換になっています。
@c COMMON
@end deftp

@deftp {Class} <parameter>
@clindex parameter
@c EN
A parameter class.  A @code{object-apply} method is defined
so that a parameter can be used as if it were a procedure.
@c JP
パラメータのクラスです。@code{object-apply}メソッドが定義されているので、
パラメータオブジェクトは普通の手続きと同様に使うことが出来ます。
@c COMMON

@example
;; p is a parameter with initial value 2
(define p (make-parametre 2))

;; calling p with no arguments returns the current value
(p) @result{} 2

;; modify p's value to 3
(p 3)

(p) @result{} 3

;; you can also use generalized set (srfi-17)
(set! (p) 5)

(p) @result{} 5

;; using parameterize dynamically changes p's value.

(define (get-p) (p))

(parameterize ([p 7])
  (get-p)) @result{} 7

(get-p)    @result{} 5
@end example


@end deftp

@defun make-parameter value :optional filter
[SRFI-39]
@c EN
Creates a parameter whose initial value is @var{value}.
If an optional argument @var{filter} is given, it must be
a procedure that takes one argument and returns one value;
whenever the parameter's value is about to change, the procedure
is called with the given value, and the value the procedure
returns will be the parameter's value.  The filter procedure
can raise an error or reject to change the parameter's value.
@c JP
初期値が@var{value}であるパラメータを作成します。
もし省略可能な引数@var{filter}が与えられた場合、
それは一つの引数を取る手続きでなければなりません。
パラメータの値が変更されようとした時、@var{filter}は与えられた値を
引数として呼ばれ、@var{filter}が返した値がパラメータの新しい値と
なります。@var{filter}はエラーを報告したりパラメータの値を変えずに置くことも
可能です。
@c COMMON
@end defun

@defmac parameterize ((param value) @dots{}) body @dots{}
[SRFI-39]
@c EN
Evaluages @var{body} @dots{}, with
change parameter @var{param}'s value to the given @var{value} within
the dynamic scope of @var{body} @dots{}.
Returns the value(s) of the result of the last @var{body}.
@c JP
@var{body} @dots{}を評価します。
但し、@var{body} @dots{} の実行中のみ、パラメータ@var{param}の値を
@var{value}に変更します。最後@var{body}の返した値を返します。
@c COMMON
@end defmac

@c EN
Some examples:
@c JP
例：
@c COMMON
@example
(define a (make-parameter 1))
(a) @result{} 1
(a 2) @result{} 1
(a) @result{} 2
(parameterize ((a 3))
  (a)) @result{} 3
(a) @result{} 2
@end example

@deffn {Method} parameter-observer-add! (p <parameter>) proc :optional when where
@c EN
Adds @var{proc} to "observer" procedures of a parameter @var{p}.
Observer procedures are called either (1) just before
a new value is set to the parameter, or (2) just after the new value
is set to the parameter.   In case of (1), a filter procedure is
already applied before a callback is called.
In either case, observer procedures are called with two arguments,
the old value and the new value.  The return value(s) of observer
procedures are discarded.
@c JP
@var{proc}をパラメータ@var{p}の``オブザーバ''手続きに追加します。
オブザーバ手続きは、(1)パラメータに新しい値がセットされる直前、
あるいは(2)パラメータに新しい値がセットされた直後、に呼ばれます。
(1)の場合、コールバックが呼ばれる前にフィルタ手続きがすでに適用
されています。どちらの場合も、オブザーバ手続きは、古い値と新しい
値の2引数を伴って呼ばれます。オブザーバ手続きの戻り値は無視されます。
@c COMMON

@c EN
The optional @var{when} argument must be either a symbol @code{before}
or @code{after}, to specify whether @var{proc} should be called
before or after the value is changed.   If omitted, @code{after} is
assumed.
@c JP
オプショナル引数@var{when}は、シンボル@code{before}か@code{after}の
いずれかでなければならず、値が変更された前と後のどちらで@var{proc}が
呼ばれるかを指定します。省略されると、@code{after}を指定したものと
されます。
@c COMMON

@c EN
The optional @var{where} argument must be either a symbol
@code{append} or @code{prepend}, to specify whether @var{proc} should
be prepended or appended to the existing observer procedure list.
If omitted, @code{append} is assumed.
@c JP
オプショナル引数@var{where}は、シンボル@code{append}か@code{prepend}の
いずれかでなければならず、@var{proc}が既存のオブザーバ手続きのリストの
前に追加されるか後に追加されるかを指定します。省略されると、@code{append}
を指定したものとされます。
@c COMMON

@c EN
@emph{Note}: Although the parameter value itself is thread-local,
the observer list is shared by all threads.
@c JP
@emph{注意}: パラメータの値自身がスレッドローカルであっても、
オブザーバのリストは全てのスレッドで共有されます。
@c COMMON
@end deffn

@deffn {Method} parameter-observer-delete! (p <parameter>) proc :optional when
@c EN
Deletes @var{proc} from observer procedure list of a parameter @var{p}.
If @var{proc} is not in the list, nothing happens.
You can give either a symbol @code{before} or @code{after} to
@var{when} argument to specify from which list @var{proc} should be
deleted.  If @var{when} argument is omitted, @var{proc} is deleted
from both lists.
@c JP
パラメータ@var{p}のオブザーバ手続きのリストから@var{proc}を削除します。
@var{proc}がリストになければ、何も起こりません。
@var{when}引数にシンボル@code{before}か@code{after}を与えて、
@var{proc}をどちらのリストから削除するかを指定することができます。
@var{when}引数が省略されると、@var{proc}は両方のリストから削除されます。
@c COMMON
@end deffn

@deffn {Method} parameter-pre-observers (p <parameter>)
@deffnx {Method} parameter-post-observers (p <parameter>)
@c EN
Returns a hook object (@xref{Hooks}) that keeps
"before" or "after" observers, respectively.

@emph{Note}: Although the parameter value itself is thread-local,
these hook objects are shared by all threads.
@c JP
``before''か``after''オブザーバをそれぞれキープするフックオブジェクト
(@ref{Hooks}参照)を返します。

@emph{注意}: パラメータの値自身がスレッドローカルであっても、
オブザーバのリストは全てのスレッドで共有されます。
@c COMMON
@end deffn

@c ----------------------------------------------------------------------
@node Parsing command-line options, Partial continuations, Parameters, Library modules - Gauche extensions
@section @code{gauche.parseopt} - Parsing command-line options
@c NODE コマンドライン引数の解析, @code{gauche.parseopt} - コマンドライン引数の解析

@deftp {Module} gauche.parseopt
@mdindex gauche.parseopt
@c EN
This module defines a convenient way to parse command-line options.
The interface is hinted by Perl, and conveniently handles long-format
options with multiple option arguments.

Actually, you have a few choices to parse command-line
options in Gauche.
SRFI-37 (@xref{A program argument processor}) provides
functional interface to parse POSIX/GNU compatible argument syntax.
SLIB has @code{getopt}-compatible utility.
Required features may differ from application to application,
so choose whichever fits your requirement.
@c JP
このモジュールでは、コマンドラインオプションをパースするための便利な方法を定義
しています。インタフェースは Perl にヒントを受けたもので、複数のオプション引数を
伴う長い形式のオプションを便利に扱うことができます。

実際、Gauche でコマンドラインオプションをパースするにはいくつかの選択肢が
あります。SRFI-37 (@ref{A program argument processor}参照)では、
POSIX/GNU 互換の引数構文をパースするための関数的なインタフェースを提供しています。
SLIB は、@code{getopt} 互換のユーティリティを持っています。
要求される機能はアプリケーションごとに異なるので、
あなたの要求にフィットするものを選んで下さい。
@c COMMON
@end deftp

@subheading High-level API

@defmac let-args args (bind-spec @dots{} [. rest]) body @dots{}
@c EN
This macro captures the most common pattern of argument processing.
It takes a list of arguments, @var{args}, and scans it to find
Unix-style command-line options and binds their values to local
variables according to @var{bind-spec}, then executes @var{body} @dots{}.
@c JP
このマクロはコマンドライン引数処理の最も典型的なパターンを扱います。
引数のリスト@var{args}を取り、@var{bind-spec}で示される仕様をもとに
コマンドラインオプションを探してその値を変数に束縛し、それから
@var{body} @dots{}を実行します。
@c COMMON

@c EN
Let's look at a simple example first, which gives you a good idea of
what this form does. (See the ``Examples'' section below for more
examples).
@c JP
まず簡単な例を見てみましょう。このフォームが何をするか、だいたい想像できるのでは
ないかと思います。(より多くの例については下の``Examples''の項を参照して
ください)。
@c COMMON

@example
(define (main args)
  (let-args (cdr args)
      ((verbose     "v|verbose")
       (outfile     "o|outfile=s")
       (debug-level "d|debug-level=i" 0)
       (help        "h|help" => (cut show-help (car args)))
       . restargs
      )
    ....))

(define (show-help progname)
  ...)
@end example

@c EN
The local variable @var{verbose} will be bound to @code{#t} if
a command-line argument @code{-v} or @code{--verbose} is given, 
and to @code{#f} otherwise.
The variable @var{output} is specified to take one option argument;
if the command-line arguments are given like @code{-o out.txt}, 
@var{outfile} receives
@code{"out.txt"}.  The @var{debug-level} one is similar, but the
option argument is coerced to an integer, and also it has default
value 0 when the option isn't given.  The @var{help} clause
invokes an action rather than merely binding the value.
@c JP
ローカル変数@var{verbose}は、コマンドラインオプション@code{-v}や@code{--verbose}
が与えられれば@code{#t}に、そうでなければ@code{#f}に束縛されます。
変数@var{output}はオプション引数を取ると指定されており、例えば
@code{-o out.txt}のようにコマンドラインに指定されれば値@code{"out.txt"}が
束縛されます。@var{debug-level}も似ていますが、オプション引数は
整数へと変換され、またデフォルト値0が指定されています。
@var{help}節では、単に値を束縛するだけでなくアクションを起動しています。
@c COMMON

@c EN
(Note: Currently @code{let-args} does not distinguish so-called 
short and long options, e.g. @code{-v} and @code{--v} have the same
effect, so as @code{-verbose} and @code{--verbose}.  In future we
may add an option to make it compatible with @code{getopt_long(3)}.)
@c JP
(註: 今のところ@code{let-args}は@code{-v}と@code{--v}を区別しません。
@code{-verbose}と@code{--verbose}も同様です。将来、@code{getopt_long(3)}と
互換になるオプションを追加するかもしれません。)
@c COMMON

@c EN
The final @var{restargs} variable after the dot receives a list of
non-optional command-line arguments.
@c JP
最後のドットの後の@var{restargs}は、オプションでないコマンドライン引数のリストを
受け取ります。
@c COMMON

@c EN
Let's look at @var{bind-spec} in detail.  
It must be one of the following forms.
@c JP
@var{bind-spec}について詳しく見てみましょう。
@var{bind-spec}は次のいずれかの形式でなければなりません。
@c COMMON

@example
1. (@var{var} @var{option-spec})
2. (@var{var} @var{option-spec} @var{default})
3. (@var{var} @var{option-spec} => @var{callback})
4. (@var{var} @var{option-spec} @var{default} => @var{callback})

5. (else => @var{handler})
6. (else @var{formals} @var{body} ...)
@end example

@c EN
A list of command-line arguments passed to @var{args} are parsed
according to @var{option-spec}s.  If the corresponding option
is given, a variable @var{var} is bound to a value as follows:

@example
(a) If the @var{bind-spec} is 1. or 2., then
  (a1) If @var{option-spec} doesn't require an argument, then @code{#t}:
  (a2) If @var{option-spec} requires one argument, then the value of
       the argument:
  (a3) If @var{option-spec} requires more than one argument,
       the list of the values of the arguments.
(b) If the @var{bind-spec} is 3. or 4., then @var{callback} is called with
  the value(s) of arguments, and its return value.
@end example
@c JP
コマンドライン引数のリストが@var{args}に渡されると、それが
@var{option-spec}に基づいてパーズされます。該当するオプションが見付かれば、
変数@var{var}が次に述べる値に束縛されます：

@example
(a) @var{bind-spec}の形式が上の1. または2. の場合：
  (a1) @var{option-spec}が引数を要求しない場合は、@code{#t}。
  (a2) @var{option-spec}がひとつの引数を要求する場合は、その引数の値。
  (a3) @var{option-spec}がそれ以上の引数を要求する場合は、引数の値のリスト。
(b) @var{bind-spec}の形式が上の3. または4. の場合、@var{callback}を
  引数の値を伴って呼び出し、その戻り値。
@end example
@c COMMON

@c EN
We'll explain the details of @var{option-spec} later.
@c JP
@var{option-spec}の詳細については後で説明します。
@c COMMON

@c EN
As a special case, @var{var} can be @code{#f}, in which case
the value is ignored.  It is only useful for side effects in
@var{callback}.
@c JP
特別な場合として、@var{var}を@code{#f}とすることもできます。
その場合、値は無視されます。
@var{callback}での副作用だけに関心がある場合に使えるでしょう。
@c COMMON

@c EN
If the corresponding option is not given in @var{args},
@var{var} is bound to @var{default} if it is given, or
@code{#f} otherwise.
@c JP
対応するオプションが@var{args}に与えられなかった場合、
@var{var}は@var{default}が与えられていればその値に、
そうでなければ@code{#f}に束縛されます。
@c COMMON

@c EN
The last @var{bind-spec} may be the form 5 or 6. in which case
the clause is selected when no other @var{option-spec} matches
a given command-line option.  
In the form 5, @var{handler} will be called with three arguments;
the given option, a list of remaining command-line arguments,
and a continuation procedure.  The @var{handler}
is supposed to handle the given option, and it may call the
continuation procedure with the remaining arguments to continue
processing, or it may return a list of arguments which will
be treated as non-optional command-line arguments.
The form 6 is a shorthand notion of 
@code{(else => (lambda @var{formals} @var{body} ...))}.
@c JP
最後の@var{bind-spec}には5か6の形式も許されます。
この節は、どの@var{option-spec}にもマッチしないコマンドラインオプションが
与えられた場合に選択されます。
5番目の形式では、@var{handler}が3つの引数を伴って呼び出されます。
引数は、マッチしなかったコマンドラインオプション、
残りのコマンドライン引数、そして引数処理に戻るための継続手続きです。
@var{handler}は与えられたコマンドラインオプションを処理した後、
オプション処理を続けたければ継続手続きに残りのコマンドライン引数を渡し、
オプション処理を打ちきりたければ残りのコマンドライン引数を戻り値として
返します。返された値は通常の(オプションでない)コマンドライン引数として扱われます。
@c COMMON

@c EN
The @var{bind-spec} list can be an improper list, whose last cdr is
a symbol.  In which case, a list of the rest of the command-line arguments
is bound to the variable named by the symbol.
@c JP
束縛リストは、最後のcdrにシンボルを持つ不完全なリストであっても良く、
その場合はコマンドライン引数の残りのリストがその変数にと束縛されます。
@c COMMON

@c EN
Note that the @var{default}, @var{callback}, and forms in @code{else}
clause is evaluated outside of the scope of binding of @var{var}s
(as the name @code{let-args} implies).
@c JP
@var{default}、@var{callback}、@code{else}節のフォーム等は
@var{var}の束縛の外側のスコープで評価されることに注意して下さい。
@c COMMON

@c EN
Unlike typical @code{getopt} or @code{getopt_long} implementation in C,
@code{let-args} does not permute the given command-line arguments.
It stops parsing when it encounters a non-option argument (argument without
starting with a minus sign).
@c JP
C における典型的な @code{getopt} や @code{getopt_long} の実装とは異なり、
@code{let-args} は与えられたコマンドライン引数の順番を変えません。
オプションでない引数(ハイフンで始まらない引数)に遭遇した時点でパースを
中止します。
@c COMMON

@c EN
If the parser encounters an argument with only two minus signs `@code{--}',
it stops argument parsing and returns a list of arguments after `@code{--}'.
@c JP
パーサは、ハイフン2つのみの引数 `@code{--}' に遭遇すると、引数パーシングを
中止して`@code{--}' の後の引数のリストを返します。
@c COMMON


@c EN
After all the bindings is done, @var{body} @dots{} are evaluated.
@var{Body} may began with internal define forms.
@c JP
全ての束縛が終了した後、@var{body} @dots{} が評価されます。
@var{body}は内部defineで始まっていても構いません。
@c COMMON
@end defmac

@subheading Option spec

@c EN
@var{option-spec} is a string that specifies the name of the option and
how the option takes the arguments.  An alphanumeric characters, underscore,
plus and minus sign is allowed for option's names, except that
minus sign can't be the first character, i.e. the valid option name
matches a regexp @code{#/[\w+][-\w+]*/}.
@c JP
@var{option-spec} は、オプションの名前とそのオプションがどのように引数を取るか
を指定する文字列です。オプションの名前には、アルファベット文字、数字、
アンダースコア、プラス記号、ハイフンが許されますが、ハイフンは最初の文字としては
使えません。すなわち、有効なオプションの名前は、@code{#/[\w+][-\w+]*/} という
正規表現にマッチするものです。
@c COMMON

@c EN
If the option takes argument(s), it can be specified by attaching 
equal character and a character (or characters) that represents
the type of the argument(s) after the name.  The option
can take more than one arguments.
The following characters are recognized as a type specifier of
the option's argument.
@c JP
オプションが引数を取る場合、名前の後ろに等号文字と引数の型を表現する文字を
付けることで指定できます。オプションは一つ以上の引数を取ることができます。
以下の文字がオプションの引数の型を表現するものとして認識されます。
@c COMMON

@table @code
@item s
@c EN
String.
@c JP
文字列。
@c COMMON
@item n
@c EN
Number.
@c JP
数値。
@c COMMON
@item f
@c EN
Real number (coerced to flonum).
@c JP
実数 (flonumに変換されます)。
@c COMMON
@item i
@c EN
Exact integer.
@c JP
正確な整数。
@c COMMON
@item e
@c EN
S-expression.
@c JP
S式。
@c COMMON
@item y
@c EN
Symbol (argument is converted by @code{string->symbol}).
@c JP
シンボル (引数は@code{string->symbol}により変換される)。
@c COMMON
@end table

@c EN
Let's see some examples of @var{option-spec}:
@c JP
@var{option-spec}の例を見てみましょう：
@c COMMON

@table @code
@item "@var{name}"
@c EN
Specifies option @var{name}, that doesn't take any argument.
@c JP
引数を取らないオプションの @var{name} を指定します。
@c COMMON

@item "@var{name}=s"
@c EN
Option @var{name} takes one argument, and it is passed as a string.
@c JP
オプション @var{name} は引数を一つ取り、それは文字列として渡されます。
@c COMMON

@item "@var{name}=i"
@c EN
Option @var{name} takes one argument, and it is passed as an exact integer.
@c JP
オプション @var{name} は引数を一つ取り、それは正確整数として渡されます。
@c COMMON

@item "@var{name}=ss"
@c EN
Option @var{name} takes two arguments, both string.
@c JP
オプション @var{name} は引数を二つ取り、両方とも文字列です。
@c COMMON

@item "@var{name}=iii"
@c EN
Option @var{name} takes three integer arguments.
@c JP
オプション @var{name} は3つの整数の引数を取ります。
@c COMMON

@item "@var{name}=sf"
@c EN
Option @var{name} takes two arguments, the first is a string and the
second is a number.
@c JP
オプション @var{name} は2つの引数を取ります。一つ目は文字列で、
二つ目は数値です。
@c COMMON
@end table

@c EN
If the option has alternative names, they can be concatenated by "|".
For example, an option spec @code{"h|help"} will match both
"h" and "help".
@c JP
オプションにいくつかの別名がある場合は、"|" でつなげて書いておくことができます。
例えば@code{"h|help"}という@var{option-spec}は
"h"にも"help"にもマッチします。
@c COMMON

@c EN
In the command line, the option may appear with preceding
single or double minus signs.  The option's argument may be combined
by the option itself with an equal sign.  For example, all the following
command line arguments match an option spec @code{"prefix=s"}.
@c JP
コマンドラインでは、オプションは一つか二つのハイフンに続いて与えられます。
オプションの引数は、オプションそのものと等号記号でつながれていても構いません。
例えば、以下の全てのコマンドライン引数は、オプションの仕様、@code{"prefix=s"} に
マッチします。
@c COMMON
@example
-prefix /home/shiro
-prefix=/home/shiro
--prefix /home/shiro
--prefix=/home/shiro
@end example

@subheading Error handling

@deftp {Condition Type} <parseopt-error>
@c EN
When @code{let-args} encounters an argument that cannot be
processed as specified by option specs, an error of condition type
@code{<parseopt-error>} is raised.   The cases include
when a mandatory option argument is missing, or when
an option argument has a wrong type.
@c JP
@code{let-args}が、@code{option-spec}に従わない引数を見つけた場合は、
コンディションタイプ@code{<parseopt-error>}のエラーを投げます。
例えば、必須のオプション引数が与えられていなかったり、異なる型であった
場合などです。
@c COMMON

@example
(let-args '("-a" "foo") ((a "a=i")) ; option a requires integer
  (list a))
 @result{} @r{parseopt-error}
@end example

@c EN
Note that this condition is about parsing the given @var{args}.
If an invalid @var{option-spec} is given,
an ordinary error is thrown.
@c JP
このコンディションはあくまで@var{args}に渡された引数をパーズする際に発生するものです。
@var{option-spec}が不正であった場合は通常のエラーが投げられます。
@c COMMON
@end deftp

@subheading Examples

@c EN
This example is taken from @code{gauche-install} script.  
The @var{mode} option takes numbers in octal, so it 
uses the callback procedure to convert it.
See also the @code{else} clause how to handle unrecognized option.
@c JP
これは@code{gauche-install}スクリプトから取った例です。
@var{mode}オプションは8進数のオプション引数を取るので、コールバック
手続きを使って変換しています。また、認識できないオプションをelse節で
処理しています。
@c COMMON

@example
  (let-args (cdr args)
      ((#f      "c")        ;; ignore for historical reason
       (mkdir   "d|directory")
       (mode    "m|mode=s" #o755 => (cut string->number <> 8))
       (owner   "o|owner=s")
       (group   "g|group=s")
       (srcdir  "S|srcdir=s")
       (target  "T|target=s")
       (utarget "U|uninstall=s")
       (shebang "shebang=s")
       (verb    "v")
       (dry     "n|dry-run")
       (#f      "h|help" => usage)
       (else (opt . _) (print "Unknown option : " opt) (usage))
       . args)
    ...)
@end example

@c EN
The next example is a small test program to show the usage of
@code{else} clause.  It gathers all options into the variable @var{r},
except that when it sees @code{-c} it stops argument processing and
binds the rest of the arguments to @var{restargs}.
@c JP
次の例は@code{else}節の使い方を示す小さなプログラムです。
コマンドラインオプションを変数@var{r}に集めてゆきますが、
オプション @code{-c} に出会うとオプション処理を中止して残りを
@var{restargs}へと渡します。
@c COMMON

@example
(use gauche.parseopt)

(define (main args)
  (let1 r '()
    (let-args (cdr args)
      ((else (opt rest cont) 
         (cond [(equal? opt "c") rest]
               [else (push! r opt) (cont rest)]))
       . restargs)
     (print "options: " (reverse r))
     (print "restargs: " restargs)
     0)))
@end example

@c EN
Sample session of the above script (suppose it is saved as @file{example}).
@c JP
上のスクリプトの実行例です (@file{example}というファイル名で保存されていると
します)。
@c COMMON

@example
$ ./example -a -b -c -d -e foo
options: (a b)
restargs: (-d -e foo)
$ ./example -a -b -d -e foo
options: (a b d e)
restargs: (foo)
@end example


@subheading Low-level API

The followings are lower-level API used to build @code{let-args}
macro.  


@defmac parse-options args (option-clause @dots{})
@c EN
@var{args} is an expression that contains a list of command-line arguments.
This macro scans the command-line options (an argument that begins with
`@code{-}') and processes it as specified in @var{option-clause}s, then
returns the remaining arguments.
@c JP
@var{args} は、コマンドライン引数のリストを含む式です。
このマクロは、コマンドラインオプション(`@code{-}' で始まる引数)をスキャンし、
@var{option-clause} の指定に従って処理し、残りの引数を返します。
@c COMMON

@c EN
Each @var{option-clause} is consisted by a pair of @var{option-spec}
and its action.

If a given command-line option matches one of @var{option-spec}, then
the associated action is evaluated.  An action can be one of the
following forms.
@c JP
それぞれの @var{option-clause} は、@var{option-spec} とそのアクションのペアで
構成されます。

与えられたコマンドラインオプションが @var{option-spec} の一つにマッチすると、
関連付けられたアクションが評価されます。アクションは以下のフォームの一つです。
@c COMMON

@table @code
@item @var{bind-spec} @var{body} @dots{}
@c EN
@var{bind-spec} is a proper or dotted list of variables like lambda-list.
The option's arguments are bound to @var{bind-spec}, then
then @var{body} @dots{} is evaluated. 
@c JP
@var{bind-spec} は、ラムダリストのような変数の正しいリストかドット対リストです。
オプションの引数は @var{bind-spec} に束縛され、@var{body} @dots{} が評価されます。
@c COMMON

@item => @var{proc}
@c EN
If a command-line option matches @var{option-spec}, calls a procedure
@var{proc} with a list of the option's arguments.
@c JP
コマンドラインオプションが @var{option-spec} にマッチすると、
@var{proc} がオプションの引数のリストとともに呼び出されます。
@c COMMON
@end table

@c EN
If a symbol @code{else} is at the position of @var{option-spec},
the clause is selected when no other option clause matches a given
command-line option.  Three ``arguments'' are associated to
the clause; the unmatched option, the rest of arguments, and
a procedure that represents the option parser.
@c JP
シンボル @code{else} が @var{option-spec} の位置にある場合、その節は、
与えられたコマンドラインオプションにマッチする他のオプション節が
ない場合に選択されます。その節には3つの``引数''が関連付けられます。
それらは、マッチしなかったオプション、引数の残り、オプションパーサを
表す手続きです。
@c COMMON

@end defmac

@defmac make-option-parser (option-clause @dots{})
@c EN
This is a lower-level interface.  @var{option-clause}s are the
same as @code{parse-options}.  This macro returns a procedure
that can be used later to parse the command line options.

The returned procedure takes one required argument and one
optional argument.  The required argument is a list of strings,
for given command-line arguments.  The optional argument may
be a procedure that takes more than three arguments, and if given,
the procedure is used as if it is the body of @code{else} option clause.
@c JP
これは低レベルのインタフェースです。@var{option-clause} は、
@code{parse-options} と同じです。このマクロは、コマンドラインオプションを
後でパースするために使うことができる手続きを返します。

返される手続きは、一つの必須の引数と一つのオプション引数を取ります。
必須の引数は、与えられたコマンドライン引数としての文字列のリストです。
オプションの引数は、三つ以上の引数を取る手続きで、それが与えられると
手続きはそれが @code{else} オプション節のボディであるかのように使われます。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node Partial continuations, High Level Process Interface, Parsing command-line options, Library modules - Gauche extensions
@section @code{gauche.partcont} - Partial continuations
@c NODE 部分継続, @code{gauche.partcont} - 部分継続

@deftp {Module} gauche.partcont
@mdindex gauche.partcont
@c EN
Gauche internally supports partial continuations
(a.k.a. delimited continuations) natively.
This module exposes the feature for genreal use.
@c JP
Gaucheは内部的に、部分継続(限定継続と呼ばれることもあります)を
ネイティブでサポートしています。このモジュールはその機能を
一般的に使えるように公開するものです。
@c COMMON
@end deftp

@c EN
Note:
Partial continuations use two operators, @code{reset} and @code{shift}.
Those names are introduced in the original papers, and stuck in the
programming world.  Unfortunately those names are too generic as
library function names.  We thought giving them more descriptive names,
but decided to keep them after all; when you talk about partial
continuations you can't get away from those names.  If these names
conflict to other names in your program, you can use @code{:prefix}
import specifier (@xref{Using modules}), for example as follows:
@c JP
註: 部分継続はふたつのオペレータ、@code{reset}と@code{shift}を使います。
これらは元の論文で導入された名前ですが、既に用語として定着した感があります。
ライブラリ関数名としては一般的に過ぎる名前なので、よりわかりやすい名前を
つけようかとも考えたのですが、部分継続を話題にする際にはこれらの用語が
使われるのが普通なので、最終的にこの名前をキープすることにしました。
プログラム中で他の識別子とぶつかったり紛らわしい場合は、モジュールのimport
時に@code{:prefix}インポート指示子(@ref{Using modules}参照)を
次のように使うと良いでしょう。
@c COMMON

@example
;; Add prefix pc: to the 'reset' and 'shift' operators.
(use gauche.partcont :prefix pc:)

(pc:reset ... (pc:shift k ....) )
@end example

@defmac reset expr @dots{}
@c EN
Saves the current continuation, and executes @var{expr} @dots{} with
a @emph{null continuation} or @emph{empty continuation}.
The @code{shift} operator captures the continuation from the @code{shift}
expression to this null continuation.
@c JP
現在の継続を保存し、@var{expr} @dots{} を@emph{空の継続}を伴って実行します。
空の継続は@code{shift}オペレータが捕捉する継続の終端になります。
@c COMMON

@c EN
Note on @emph{implicit delimited continuations}:
There's an occasion Gauche effectively calls @code{reset} internally:
When C routine calls back to Scheme in non-CPS manner.
(If you know C API, it is @code{Scm_EvalRec()}, @code{Scm_ApplyRec*()}, 
@code{Scm_Eval()} and @code{Scm_Apply()} family of functions.)  The callers
of such routines expect the result is returned at most once, which won't
work well with Scheme's continuations that have unlimited extent.
Such calls create delimited continuations implicitly.

For example, the @code{main} routine of @code{gosh} calls Scheme REPL by
@code{Scm_Eval()}, which means the entire REPL is effectively surrounded
by a @code{reset}.  So, if you call @code{shift} without corresponding
@code{reset}, the continuation of @code{shift} becomes the continuation
of the entire REPL---which is to exit from @code{gosh}.  
This may be surprising if you don't know about the implicit delimited
continuation.

Other places the implicit delimited continuations are created 
are the handlers virtual ports (@xref{Virtual ports}), 
@code{object-apply} methods called from @code{write} and @code{display},
and GUI callbacks such as the one registered by @code{glut-display-func}
(See the document of Gauche-gl for the details), to name a few.

In general you don't need to worry about it too much, since most
built-in and extension routines written in C calls back Scheme in CPS manner,
and works with both full and delimited continuations.
@c JP
@emph{暗黙の限定継続}について:
Gaucheは内部的に、@code{reset}相当の操作を行う場合があります。
CルーチンがSchemeを継続渡し形式でない方法で呼び出す場合です。
(C APIをご存知の方へ: @code{Scm_EvalRec()}, @code{Scm_Apply*Rec()},
@code{Scm_Eval()}、および@code{Scm_Apply()}が相当する関数です。)
これらの関数はCの呼び出し側へ、値をたかだか1度だけ返すことが期待されています。
Schemeの継続は無限エクステントを持ち、一度返ったルーチンから再び返ることが
あり得るため、こういったC関数とは相性が良くありません。
これらの関数を呼び出す時に、Gaucheは限定継続を自動的に作成します。

例えば、@code{gosh}の@code{main}関数はSchemeのREPLを
@code{Scm_Eval()}を通じて呼び出します。ということは、
REPL全体が@code{reset}で囲まれているということです。
従って@code{reset}の外側で@code{shift}を呼び出すと、その@code{shift}の
継続はREPL全体の継続と同じになります。すなわち、@code{gosh}が終了するということです。
暗黙の限定継続に気づかないと、この振る舞いにはびっくりするかもしれません。

他に暗黙の限定継続が作られる例をいくつかあげます。
仮想ポートのハンドラ (@ref{Virtual ports}参照)、
@code{write}や@code{display}から呼ばれる@code{object-apply}メソッド、
@code{glut-display-func}により登録されたGUIコールバック
(詳しくはGauche-glのマニュアル参照)などです。

そのような暗黙の限定継続を心配する必要は滅多にありません。Cで実装された
組み込み関数や拡張関数のほとんどは継続渡し形式でSchemeを呼んでいるため、
通常継続も限定継続も制限なく使うことができます。
@c COMMON
@end defmac

@defmac shift var expr @dots{}
@c EN
Packages the continuation of this expression until the current null
continuation marked by the most recent @code{reset} into a procedure,
binds the procedure to @var{var}, then executes @var{expr} @dots{}
with the continuation saved by the most recent @code{reset}.
@c JP
この式からもっとも最近の@code{reset}により切り取られた空の継続までの継続を
手続きに包み、それを@var{var}に束縛します。
そしてもっとも最近の@var{reset}式の継続を伴って@var{expr} @dots{}を実行します。
@c COMMON

@c EN
That is, after executing @var{expr} @dots{}, the value is passed
to the expression waiting for the value of the most recent @code{reset}.
When a partial continuation bound to @var{var} is executed, its
argument is passed to the continuation waiting for the value
of this @code{shift}.   When the execution of the partial continuation 
reaches its end, it returns from the expression waiting
for the value of invocation of @var{var}.
@c JP
すなわち、@var{expr} @dots{}を実行後、その結果の値はもっとも最近の@code{reset}
の戻り値を待っている式に直ちに渡されます。
@var{var}に束縛されている部分継続が実行されると、それに渡された値は
@code{shift}の戻り値を待っている継続に直ちに渡されます。
その部分継続の実行が終了すると、その結果の値は@var{var}を呼び出した式の
戻り値となります。
@c COMMON
@end defmac

@defun call/pc proc
@c EN
This is a wrapper of @code{shift}.  @code{(shift k expr @dots{})}
is equivalent to @code{(call/pc (lambda (k) expr @dots{}))}.
Sometimes this similarity of @code{call/cc} comes handy.
@c JP
これは@code{shift}のラッパーです。
@code{(shift k expr @dots{})}は@code{(call/pc (lambda (k) expr @dots{}))}
等価です。@code{call/cc}と似た形の呼び出し形式の方が便利な場合があるので
用意しました。
@c COMMON
@end defun

@c EN
Well, @dots{} I bet you feel like your brain is twisted hard
unless you are one of those rare breed from the land of continuation.
Let me break down what's happening here informally and intuitively.
@c JP
さてと… もしあなたが、継続の国の血を引く珍しい種族の一員でなければ、
たぶんここまで読んできて、脳みそがこんがらがっていることでしょう。
何が起きているか、厳密ではないが直感的な説明を試みてみます。
@c COMMON

@c EN
Suppose a procedure A calls an expression B.   If A expects a return
value from B and continue processing, we split the part after returning
from B into a separate chunk A', then we can think of the whole
control flow as this straight chain:
@c JP
手続きAが式Bを呼び出すとします。AがBの戻り値を受け取ってさらに計算を続ける場合、
Bが戻ってからの残りの計算部分をA'として分離することにすれば、全体の制御の流れは
次のように一本の鎖で表現できるでしょう。
@c COMMON

@example
A -> B -> A'
@end example

@c EN
@code{A -> B} is a procedure call and @code{B -> A'} is a return,
but we all know procedure call and return is intrinsically the
same thing, right?
@c JP
@code{A -> B}は手続き呼び出しで、@code{B -> A'}は手続きからのリターンですが、
手続き呼び出しとリターンは本質的には同じものでしたね。
@c COMMON

@c EN
Procedure B may call another procedure C, and so on.  So when
you look at an execution of particular piece of code, you can
think of a chain of control flow like this:
@c JP
Bはその中から別の手続きCをさらに呼び出しているかもしれません。
コードのある部分に着目した場合、そこにある制御の鎖を
次のようにイメージすることができるでしょう。
@c COMMON

@example
... -> A -> B -> C -> .... -> C' -> B' -> A' -> ...
@end example

@c EN
The magic procedure @code{call/cc} picks the head of the chain
following its execution (marked as @code{*} in the figure blow),
and passes it to the given procedure (denoted @code{k} in the figure
below).
So, whenever @code{k} is invoked, the control goes through the
chain from @code{*}.
@c JP
魔法の手続き@code{call/cc}は、そのフォームの直後に来る鎖の先頭
(下の図で@code{*}で示されている部分)を取り上げて、それを
与えられた手続きに引数として渡すものです (下の図の@code{k})。
従って、@code{k}が呼び出されると、制御は直ちに@code{*}へとジャンプします。
@c COMMON

@example
... -> A -> B -> (call/cc -> (lambda (k) ... ) ) -> B' -> A' -> ...
                                      |             ^
                                      \-----------> *
@end example

@c EN
One difficulty with @code{call/cc} is that the extracted chain
is only one-ended---we don't know what is chained to the
right.  In fact, what will come after that depends
on the whole program; it's outside of local control.  This global
attribute of @code{call/cc} makes it difficult to deal with.
@c JP
@code{call/cc}で難しいのは、制御の鎖の片方しか取り出せないことです。
もう一方、鎖の右側がどこにつながっているのか、コードは知ることができません。
そもそも、鎖の右側に何が来るかは、プログラム全体を知らないとわからないのです。
この、グローバルな性質が、@code{call/cc}を扱い辛いものにしています。
@c COMMON

@c EN
The @code{reset} primitive @emph{cuts} this chain of 
continuation.  The original chain of continuation (the @code{x}-end
in the following figure) is saved somewhere, and the continuation
of @code{reset} itself becomes open-ended (the @code{o}-end
in the following figure).
@c JP
@code{reset}プリミティブはこの継続の鎖を@emph{切断}します。
元の鎖 (下の図の@code{x}で示される端) は保存され、
@code{reset}式の継続自体は宙ぶらりんになります (下の図の@code{o}で示される端)。
@c COMMON

@example
... -> A -> B -> (reset ... ) -> o

                                 x -> B ' -> A' -> ...
@end example

@c EN
A rule: If control reaches to the @code{o}-end, we pick the
@code{x}-end @emph{most recently saved}.
Because of this, @code{reset} alone doesn't show any
difference in the program behavior.
@c JP
ここでひとつ規則を導入します。制御が@code{o}の端に達した場合、
もっとも最近保存された@code{x}の端から制御を再開するとします。
従って、単に@code{reset}を挿入するだけでは、目に見える違いは生じません。
@c COMMON

@c EN
Now what happens if we insert @code{shift} inside @code{reset}?
This is a superficial view of inserting @code{shift} into
somewhere down the chain of reset:
@c JP
@code{reset}の中に@code{shift}を挿入したらどうなるでしょう。
resetの内部の鎖に@code{shift}を形式的に挿入してみるとこうなります。
@c COMMON

@example
... -> (reset ... X -> Y -> (shift k ... ) -> Y' -> X' ) -> o
@end example

@c EN
What actually happens is as follows.
@c JP
実際には次のような動作となります。
@c COMMON

@enumerate
@item
@c EN
@code{shift} packages @emph{the rest of the chain of work} until the
end of @code{reset}, and bind it to the variable @var{k}.
@c JP
@code{shift}は、@code{reset}の終端までの@emph{仕事の残りの部分}を取り出し、
それを変数@var{k}に束縛します。
@c COMMON
@item
@c EN
The continuation of @code{shift} becoms a null continuation as well,
so after @code{shift} returns, the control skips the rest of
operations until the corresponding @code{reset}.
@c JP
@code{shift}自身の継続は、空の継続となります。したがって@code{shift}から抜けると、
@code{shift}以降対応する@code{reset}までの操作はスキップされます。
@c COMMON
@end enumerate

@example
... -> (reset ... X -> Y -> (shift k ... ) ---------> ) -> o
                                   |
                                   \-------> Y' -> X' ) -> o
@end example

@c EN
In other words, when you consider the @code{reset} form as
one chunk of task, then @code{shift} in it
@emph{stashes away} the rest of the task and immediately
returns from the task.  
@c JP
別の言い方をすれば、@code{reset}フォームをひとつの仕事の単位とすれば、
その中の@code{shift}は、その仕事の残りの部分を@emph{一時保存}して
仕事を中断して戻ってくるのです。
@c COMMON

@c EN
Let's see an example.  The @var{walker} argument in
the following example is a procedure that takes a procedure
and some kind of collection,
and applies the procedure to the each element in the collection.
We ignore the return value of @var{walker}.
@c JP
例を見てみます。次に示す@var{walker}引数は、
「手続きと何らかのコレクションを取り、手続きをコレクションの各要素に
適用してゆく」という手続きとします。
@var{walker}の戻り値は無視します。
@c COMMON

@example
(define (inv walker)
  (lambda (coll)
    (define (continue)
      (reset (walker (lambda (e) (shift k (set! continue k) e)) coll)
             (eof-object)))
    (lambda () (continue))))
@end example

@c EN
A typical example of @var{walker} is @code{for-each}, which takes
a list and applies the procedure to each element of the list.
If we pass @code{for-each} to @code{inv}, we get a procedure
that is inverted @emph{inside-out}.  What does that mean?
See the following session:
@c JP
@var{walker}の典型的な例は@code{for-each}です。手続きとリストを取り、
リストの各要素に手続きを適用するからです。
@code{for-each}を上の@code{inv}に渡すと、@code{for-each}を
@emph{裏返した}手続きが得られます。どういうことでしょう?
下のやりとりを見てみましょう。
@c COMMON

@example
gosh> (define inv-for-each (inv for-each))
inv-for-each
gosh> (define iter (inv-for-each '(1 2 3)))
iter
gosh> (iter)
1
gosh> (iter)
2
gosh> (iter)
3
gosh> (iter)
#<eof>
@end example

@c EN
When you pass a list to @code{inv-for-each}, you get an iterator
that returns each element in the list for each call.  That's because every
time @code{iter} is called, @code{shift} in @code{inv}
stashes away the task of @emph{walking the rest of the collection}
and set it to @code{continue}, then returns the current element @var{e}.
@c JP
リストを@code{inv-for-each}に渡すと、呼ばれる度にリストの各要素を順に返す
イテレータ手続きが得られます。というのも、@code{iter}が呼ばれる度に、
@code{inv}の中で作られた@code{shift}は@emph{リストの残りの部分をたどって行く}
という仕事の残りを@code{countine}に束縛して、現在の要素@var{e}を返すからです。
@c COMMON

@c EN
@var{walker} doesn't need to work just on list.  The following
function @code{for-each-leaf} traverses a tree and
apply @var{f} on each non-pair element.
@c JP
@var{walkre}はリストを取る必要はありません。次に示す@code{for-each-leaf}は
木を取って、@var{f}をペアでない要素に適用してゆく手続きです。
@c COMMON

@example
(define (for-each-leaf f tree)
  (match tree
   [(x . y) (for-each-leaf f x) (for-each-leaf f y)]
   [x (f x)]))
@end example

@c EN
And you can inverse it just like @code{for-each}.
@c JP
これも@code{for-each}と同じように裏返すことができます。
@c COMMON

@example
gosh> (define iter2 ((inv for-each-leaf) '((1 . 2) . (3 . 4))))
iter2
gosh> (iter2)
1
gosh> (iter2)
2
gosh> (iter2)
3
gosh> (iter2)
4
gosh> (iter2)
#<eof>
@end example

@c EN
The @code{util.combinations} module (@xref{Combination library})
provides a procedure that @emph{calls} a given procedure with
every permutation of the given collection.  If you pass
it to @code{inv}, you get a procedure that @emph{returns}
every permutation each time.
@c JP
@code{util.combinations}モジュール (@ref{Combination library}参照) には、
コレクションの全ての並べ替えに対して与えられた手続きを@emph{呼び出す}手続きがあります。
それを@code{inv}に渡せば、呼ばれる度に並べ替えを@emph{返す}手続きが得られます。
@c COMMON

@example
gosh> (define next ((inv permutations-for-each) '(a b c)))
next
gosh> (next)
(a b c)
gosh> (next)
(a c b)
gosh> (next)
(b a c)
gosh> (next)
(b c a)
gosh> (next)
(c a b)
gosh> (next)
(c b a)
gosh> (next)
#<eof>
@end example



@c ----------------------------------------------------------------------
@node High Level Process Interface, Record types, Partial continuations, Library modules - Gauche extensions
@section @code{gauche.process} - High Level Process Interface
@c NODE 高レベルプロセスインタフェース, @code{gauche.process} - 高レベルプロセスインタフェース

@deftp {Module} gauche.process
@mdindex gauche.process
@c EN
This module provides a higher-level API of Unix process control,
implemented on top of low-level system calls such as @code{sys-fork}
and @code{sys-exec}.   This module also provides ``process ports'', 
a convenient way to send/receive information to/from subprocesses.
@c JP
このモジュールは、@code{sys-fork} や @code{sys-exec} などの低レベルな
システムコールの上に実装された、Unix プロセス制御の高レベル API を提供します。
また、このモジュールは、サブプロセスに情報を送ったり、サブプロセスから
情報を受け取ったりするのに便利な「プロセスポート」を提供します。
@c COMMON
@end deftp

@menu
* Running subprocess::          
* Process object::              
* Process ports::               
@end menu

@node Running subprocess, Process object, High Level Process Interface, High Level Process Interface
@subsection Running subprocess

@defun run-process cmd/args :key redirects input output error @
                   fork wait directory host sigmask
@c EN
Runs a command with arguments given to @var{cmd/args} in a subprocess
and returns a @code{<process>} object, which is explained in the
next section.
The @var{cmd/args} argument must be a list, whose car specifies
the command name and whose cdr is the command-line arguments.

If the command name contains a slash, it is taken as the
pathname of the executable.  Otherwise the named command
is searched from the directories in the @code{PATH} environment variable.

Each element in @var{cmd/args} are converted to a string
by @code{x->string}, for the convenience.
@c JP
サブプロセスで、@var{cmd/args}に与えられたコマンドと引数を実行し、
@code{<process>}オブジェクトを返します。
@code{<process>}オブジェクトについては次節で説明します。

@var{cmd/args}引数はリストで、その@code{car}がコマンド名を、
@code{cdr}がコマンドラインに渡す引数を指定します。

コマンド名がスラッシュを含んでいた場合、それは実行可能ファイルへの
パス名と解釈されます。そうでなければ、コマンド名が@code{PATH}環境変数
にあるディレクトリから探されます。

@var{cmd/args}の各要素は、@code{x->string}で文字列に変換されます。
@c COMMON

@c EN
For example, the following expression runs @code{ls -al}.
@c JP
例えば、次の式は@code{ls -al}を実行します。
@c COMMON

@example
(run-process '(ls -al))
@end example

@c EN
If you run the above expression in REPL, you'll likely to see
its return value before the output of @code{ls}.
By default, @code{run-process} does not wait the child process
to finish, but it rather returns immediately.  If you need to
synchronize, pass the @code{wait} keyword argument.
@c JP
上の式をREPLで実行したなら、おそらく戻り値が@code{ls}の出力より先に表示されるでしょう。
デフォルトでは、@code{run-process}は子プロセスの
終了を待たずに、直ちに戻ります。子プロセスの終了を待ちたい場合は@code{wait}キーワード
引数を使います。
@c COMMON

@example
(run-process '(ls -al) :wait #t)
@end example

@c EN
Alternatively, you can keep the returned @code{<process>} object
and call @code{process-wait} on it to wait for its termination.
@xref{Process object}, for the details of @code{process-wait}.
@c JP
あるいは戻り値の@code{<process>}オブジェクトを保持しておいて、後で
@code{process-wait}を呼ぶことによって子プロセスの終了を待つこともできます。
@code{process-wait}については@ref{Process object}で説明します。
@c COMMON

@example
(let1 p (run-process '(ls -al))
  ... do some other work ...
  (process-wait p))
@end example

@c EN
Note that @code{-i} is read as an imaginary number,
so be careful to pass @code{-i} as a command-line
argument; you should use a string, or write @code{|-i|} to make it
a symbol.
@c JP
ところで、@code{-i}は虚数として読まれることに注意してください。
@code{-i}を引数として渡したい場合は文字列にするか、@code{|-i|}のように
エスケープしてシンボルにする必要があります。
@c COMMON

@example
(run-process '(ls "-i"))
@end example

@c EN
Note: Old version of this procedure took arguments differently,
like @code{(run-process "ls" "-al" :wait #t)}, which was compatible
to STk.  This is still supported but deprecated.
@c JP
注：以前のバージョンのこの手続きは引数の取りかたが若干異なっており、
例えば@code{(run-process "ls" "-al" :wait #t)}のように呼び出しました。
これはSTkとの互換性によるものです。現在でもこの呼び出しはサポートされていますが、
非推奨です。
@c COMMON

@c EN
Large number of keyword arguments can be passed to @code{run-process}
to control execution of the child process.  We describe them by
categories.
@c JP
子プロセスの実行を細かく制御するために、@code{run-process}はたくさんの
キーワード引数を取ります。以下でそれらをいくつかのカテゴリに分類して説明します。
@c COMMON
@end defun


@c EN
@subsubheading Synchronization
@c JP
@subsubheading 同期
@c COMMON

@deftp {run-process argument} wait @var{flag}
@c EN
If @var{flag} is true, @code{run-process} waits until the
subprocess terminates.  Othewise the subprocess runs asynchronously
and @code{run-process} returns immediately, which is the default behavior.

Note that if the subprocess is running asynchronously, it is the
caller's responsibility to call @code{process-wait} at a certain
timing to collect its exit status.
@c JP
@var{flag} が真の場合、@code{run-process} はサブプロセスが終了するまで待ちます。
そうでなければ、サブプロセスは非同期に実行され、@code{run-process} は
すぐに返ります。これがデフォルトの振る舞いになります。

サブプロセスが非同期に実行している場合、その終了ステータスを回収するために
適切なタイミングで @code{process-wait} を呼ぶことは、呼び出し側の責任であることに
注意してください。
@c COMMON

@example
;; This returns after wget terminates.
(define p (run-process '(wget http://practical-scheme.net/) :wait #t))

;; Check the exit status
(let1 st (process-exit-status p)
  (cond [(sys-wait-exited? st)
         (print "wget exitted with status " (sys-wait-exit-status st))]
        [(sys-wait-signaled? st)
         (print "wget interrupted by signal " (sys-wait-termsig st))]
        [else
         (print "wget terminated with unknown status " st)]))
@end example
@end deftp

@deftp {run-process argument} fork @var{flag}
@c EN
If @var{flag} is true, @code{run-process} forks to run
the subprocess, which is the default behavior.  If @var{flag} is
false, @code{run-process} directly calls @code{sys-exec}, so
it never returns.
@c JP
@var{flag} が真の場合、@code{run-process} はサブプロセスを実行するために
フォークします。これはデフォルトの振る舞いです。@var{flag} が偽の場合、
@code{run-process} は直接 @code{sys-exec} を呼ぶので、それは返りません。
@c COMMON
@end deftp

@c EN
@subsubheading I/O redirection
@c JP
@subsubheading I/Oリダイレクト
@c COMMON

@deftp {run-process argument} redirects (@var{iospec} @dots{})
@c EN
Specifies how to redirect child process's I/Os.  
Each @var{iospec}
can be one of the followings, where @var{fd}, @var{fd0}, and @var{fd1}
are nonnegative integers referring to the file descriptr 
@emph{of the child process}.
@c JP
子プロセスのI/Oをどのようにリダイレクトするかを指定します。
各@var{iospec}は次の形式のいずれかです。ここで@var{fd}, @var{fd0}および@var{fd1}は
@emph{子プロセスにおける}ファイルディスクリプタを指定する非負の整数です。
@c COMMON

@table @code
@item (< @var{fd} @var{source})
@c EN
@var{source} can be a string, a symbol, a keyword @code{:null},
an integer, or an input port.

If it is a string, it names a file opened for read
and the child process can reads the content of the file from @var{fd}.
An error is signalled if the file does not exist or cannot open for read.

If it is a symbol, an unidirectional pipe is created, whose reader end
is connected to the child's @var{fd}, and whose writer end is
available as an output port returned from
@code{(process-input @var{process} @var{source})}.

If it is @code{:null}, the child's @var{fd} is connected to the
null device.

If it is an integer, it should specify a parent's file descriptor
opened for read.  The child sees the duped file descriptor as @var{fd}.

If it is an input port, the underlying file descriptor is duped
into child's @var{fd}.  It is an error to pass an input port without
associated file descriptor (See @code{port-file-number} in 
@ref{Common port operations}).
@c JP
@var{source}は文字列、シンボル、キーワード@code{:null}、整数、入力ポートのいずれかです。

文字列の場合、それはファイル名を指定します。そのファイルが読み込み用にオープンされ、
子プロセスはfdからその内容を読み込みます。指定されたファイルが存在しないか
読み込み用にオープンできなければエラーが報告されます。

シンボルの場合、一方向のパイプが作られ、その読み出し側の端が子プロセスのfdへと
接続されます。書き込み側の端は
@code{(process-input @var{process} @var{source})}
を呼び出すことで入手できます。

@code{:null}の場合、@var{fd}はシステムのヌルデバイスからの
読み込みになります。

整数の場合は、現プロセスの読み込み用ファイルディスクリプタを指定します。
そのファイルディスクリプタの読み込み元が@code{dup}されて、子プロセスからは@var{fd}として
見えます。

入力ポートの場合は、入力元のファイルディスクリプタが@code{dup}されて
子プロセスの@var{fd}になります。ファイルディスクリプタを持たないポートを渡した
場合はエラーになります(@ref{Common port operations}の@code{port-file-number}参照)。
@c COMMON

@item (<< @var{fd} @var{value})
@itemx (<<< @var{fd} @var{obj})
@c EN
Feeds @var{value} or @var{obj} to the input file
descriptor @var{fd} of the child process.

With @code{<<}, @var{value} must be either a string or a uniform
vector (@xref{Uniform vectors}).  It is sent to the child process as is.
Using a uniform vector is good to pass binary content.

With @code{<<<}, @var{obj} can be any Scheme object, and
the result of @code{(write-to-string obj)} is sent to the child process.
@c JP
@var{value}または@var{obj}を子プロセスの入力ファイルディスクリプタ@var{fd}への
入力とします。

@code{<<}を使う場合、@var{value}は文字列かユニフォームベクタ
(@xref{Uniform vectors})でなければなりません。その内容がそのまま
子プロセスの入力へと送られます。ユニフォームベクタはバイナリデータを渡すのに便利です。

@code{<<<}を使う場合、@var{obj}には任意のSchemeオブジェクトを渡せます。
@code{(write-to-string obj)}の結果の文字列が子プロセスの入力へと送られます。
@c COMMON

@item (<& @var{fd0} @var{fd1})
@c EN
Makes child process's file descriptor @var{fd0} refer to the same input
as its file descriptor @var{fd1}.  Note the difference from @code{<}; 
@code{(< 3 0)} makes the parent's stdin (file descriptor 0) be read
by the child's file descriptor 3, while  @code{(<& 3 0)} makes
the child's file descriptor 3 refer to the same input as child's stdin
(which may be redirected to a file or something else by another @var{iospec}).

See the note below on the order of processing @code{<&}.
@c JP
子プロセスのファイルディスクリプタ@var{fd0}が、
同じく子プロセスのファイルディスクリプタ@var{fd1}が指しているものと
同じ入力を参照するようにします。
@var{<}との違いに注意してください。@code{(< 3 0)}とすると、
現プロセスのstdin (ファイルディスクリプタ0) が子プロセスからはファイルディスクリプタ3
として見えるようになります。@code{(<& 3 0)}とすると、子プロセスのファイルディスクリプタ3
は子プロセスのstdinと同じものを見るようになります (それは他の@var{iospec}によって
ファイル等にリダイレクトされているかもしれません)。

@code{<&}の処理の順番について、下の方にある註も参照してください。
@c COMMON

@item (> @var{fd} @var{sink})
@itemx (>> @var{fd} @var{sink})
@c EN
@var{sink} must be either a string, a symbol, a keyword @code{:null},
an integer or a file output port.

If it is a string, it names a file.  The output of the child to
the file descriptor @var{fd} is written to the file.
If the named file already exists, @code{>} first truncates its
content, whlie @code{>>} appends to the existing content.

For other arguments, @code{>} and @code{>>} works the same.

If @var{sink} is a symbol, an unidirectional pipe is created
whose writer end is connected to the child's @var{fd}, and whose
reader end is available as an input port returned by 
@code{(process-output @var{process} @var{sink})}.

If @var{sink} is @code{:null}, child's @var{fd} is connected
to the system's null device.

If @var{sink} is an integer, it must specify a parent's file
descriptor opened for output.  The child sees the duped file descriptor
as @var{fd}.

If @var{sink} is an output port, the underlying file descriptor is
duped into @var{fd} in the child process.
@c JP
@var{sink}は文字列、シンボル、キーワード@code{:null}、整数、あるいは
ファイル出力ポートでなければなりません。

文字列の場合、それはファイル名です。指定されたファイルが書き込み用にオープンされ、
子プロセスのファイルディスクリプタ@var{fd}からそこに書き込むことができます。
指定のファイルが既に存在している場合、@code{>}はファイルをまず空にするのに対し、
@code{>>}はファイルの後に追加します。
@code{>}と@code{>>}の違いが出るのは@var{sink}がファイルの場合のみです。

@var{sink}が@code{:null}なら、@var{fd}はシステムのヌルデバイスへの
書き出しになります。

整数の場合、それは現プロセスの書き込み用ファイルディスクリプタを
指定します。それが@code{dup}されて子プロセスの@var{fd}となります。

出力ポートの場合は、出力先のファイルディスクリプタが@code{dup}されて
子プロセスの@var{fd}になります。ファイルディスクリプタを持たないポートを渡した
場合はエラーになります(@ref{Common port operations}の@code{port-file-number}参照)。
@c COMMON

@item (>& @var{fd0} @var{fd1})
@c EN
Makes child process's file descriptor @var{fd0} refer to the same output
as its file descriptor @var{fd1}.  Note the difference from @code{>}; 
@code{(> 2 1)} makes the child's stderr go to parent's stdout,
while  @code{(>& 2 1)} makes the child's stderr go to the same
output as child's stdout (which may be redirected by another @var{iospec}).
@c JP
子プロセスのファイルディスクリプタ@var{fd0}が、子プロセスのファイルディスクリプタ@var{fd1}
が参照するのと同じ出力先を参照するようにします。
@var{>}との違いに注意: @code{(> 2 1)}は子プロセスのstderrが現プロセスのstdout
と同じところに送られるようにするのに対し、@code{(>& 2 1)}は子プロセスのstderr
が子プロセスのstdoutに送られます (それは別の@var{iospec}によってリダイレクト
されているかもしれません)。
@c COMMON

@example
@c EN
;; Read both child's stdout and stderr 
@c JP
;; 子プロセスのstdoutとstderrを一緒にして読み込む
@c COMMON
(let1 p (run-process '(command arg)
                     :redirects '((>& 2 1) (> 1 out)))
  (begin0 (port->string (process-output p 'out))
          (process-wait p)))
@end example

@end table

@c EN
Note: I/O redirections are processed @emph{at once}, unlike the way
unix shell does.  For example, both of the following expression
works the same way, that is, they redirect
both stdout and stderr to a file @file{out}.
@c JP
註: I/Oリダイレクト指定は、unixのシェルと違って、
全て@emph{同時に}処理されます。つまり、以下の式はどちらも同じように、
stdoutとstderrをファイル@file{out}に書き出す処理となります。
@c COMMON

@example
(run-process '(command arg) :redirects '((>& 2 1) (> 1 "out")))
(run-process '(command arg) :redirects '((> 1 "out") (>& 2 1)))
@end example

@c EN
Most unix shells process redirections @emph{in order}, so the following
two command line works differently: The first one redirects child's
stderr to the @emph{current} stdout, which is the same as the parent's
stdout, then redirects child's stdout to a file @file{out}.  So the
error messages appear in the parent's stdout.  The second one first
redirects the child's stdout to a file @file{out}, so at the time
of processing @code{2>&1}, the child's stderr also goes to the file.
@c JP
unixのシェルではリダイレクト指定は@emph{順に}処理されるので、
次の二つのコマンドラインは異なる動作となります。最初の例では
子プロセスのstderrが@emph{現時点での}stdout (それは現プロセスのstdoutでもある)
へと向けられ、次に子プロセスのstdoutがファイル@file{out}に向けられます。
従ってエラーメッセージは現プロセスのstdoutへと現れます。二番目の例では
最初に子プロセスのstdoutがファイル@file{out}へ向けられるので、
@code{2>&1}が処理される時にはstderrの行き先はやはり@file{out}となります。
@c COMMON

@example
$ command arg 2>&1 1>out
$ command arg 1>out 2>&1
@end example

@c EN
You can say @code{run-process} always works like the latter,
regardless of the order in @var{redirects} argument.

If you want to redirect child's stderr to parent's stdout,
you can use @code{>} like the following:
@c JP
@code{run-process}は@var{redirects}引数の順番にかかわらず
常に後者のように動作すると言ってもよいでしょう。

もし前者の例のように子プロセスのstderrだけを親プロセスのstdoutに
向けたいのであれば、次のように@code{>}を使うことで実現できます。
@c COMMON

@example
(run-process '(command arg) :redirects '((> 2 1) (> 1 "out")))
@end example

@end deftp


@deftp {run-process argument} input @var{source}
@deftpx {run-process argument} output @var{sink}
@deftpx {run-process argument} error @var{sink}
@c EN
Redirects child's standard i/o.
@var{source} and @var{sink} may be either a string, a keyword @code{:null},
a keyword @code{:pipe}, an integer file descriptor or a symbol.

These are really shorthand notations of the @var{redirects} argument:
@c JP
サブプロセスの標準入出力を制御します。
@var{source}及び@var{sink}は、文字列、キーワード @code{:pipe}、
キーワード@code{:null}、整数のファイルディスクリプタ、もしくはシンボルです。

実のところ、これらは@var{redirects}引数の略記にすぎません。
@c COMMON

@example
:input x   @equiv{} :redirects '((< 0 x))
:output x  @equiv{} :redirects '((> 1 x))
:error x   @equiv{} :redirects '((> 2 x))
@end example

@c EN
The keyword @code{:pipe} as @var{source} or @var{sink} is supported
just for the backward compatibility.  They work as if a symbol
@code{stdin}, @code{stdout} or @code{stderr} is given, respectively:
@c JP
キーワード@code{:pipe}は互換性のためだけにサポートされています。
それぞれ、シンボル@code{stdin}、@code{stdout}、@code{stderr}が
指定されたかのように振る舞います。
@c COMMON

@example
:input :pipe   @equiv{} :redirects '((< 0 stdin))
:output :pipe  @equiv{} :redirects '((> 1 stdout))
:error :pipe   @equiv{} :redirects '((> 2 stderr))
@end example

@c EN
That is, a pipe is created and its one end is connected to the
child process's stdio, and the other end is available
by calling @code{(process-input @var{process})},
@code{(process-output @var{process})} or @code{(process-error @var{process})}.
(That is because @code{process-input} and @code{process-output}
uses @code{stdin} and @code{stdout} respectively when @var{name} argument
is omitted, and @code{(process-error p)} is equivalent
to @code{(process-output p 'stderr)}.)
@c JP
すなわち、パイプが作成され、その一方が子プロセスの標準入出力のいずれかに接続されます。
もう一方の端は@code{(process-input @var{process})}、
@code{(process-output @var{process})}および
@code{(process-error @var{process})}によって得ることができます。
(@code{process-input}, @code{process-output}は@var{name}引数が
省略されるとそれぞれ@code{stdin}, @code{stdout}をデフォルトとし、
また@code{(process-error p)}は@code{(process-output p 'stderr)}と
等価だからです)
@c COMMON

@c EN
See the description of @var{redirects} above for the meanings
of the argument values.
@c JP
引数の意味の詳しい説明については上の@var{redirects}の項を参照してください。
@c COMMON
@end deftp


@c EN
@subsubheading Execution environment
@c JP
@subsubheading 実行環境
@c COMMON

@deftp {run-process argument} directory @var{directory}
@c EN
If a string is given to @var{directory},
the process starts with @var{directory} as its working directory.
If @var{directory} is @code{#f}, this argument is ignored.
An error is signalled if @var{directory} is other type of objects,
or it is a string but is not a name of a existing directory.

When @var{host} keyword argunmet is also given, this argument
specifies the working directory of the @emph{remote} process.

Note: @code{run-process} checks the validity of @var{directory},
but actual @code{chdir(2)} is done just before @code{exec(2)},
and it is possible that @code{chdir} fails in spite of previous
checks.  At the moment when @code{chdir} fails, there's no
reliable way to raise an exception to the caller of @code{run-process},
so it writes out an error message to standard error port and exits.
A robust program may take this case into account.
@c JP
@var{directory}に文字列が与えられた場合、
そのディレクトリが起動されるプロセスのワーキングディレクトリとなります。
@code{#f}が与えられた場合はの引数は何もしません。
文字列か@code{#f}以外が与えられた場合、もしくは文字列が存在するディレクトリの
名前でない場合はエラーが報告されます。

@var{host}キーワード引数も与えられている場合、この引数は
リモートプロセスのワーキングディレクトリを指定します。

註: @code{run-process}は@var{directory}が有効な値であることを事前に
チェックしますが、実際の@code{chdir(2)}は@code{exec(2)}の直前に
行われます。事前のチェックにもかかわらず@code{chdir}が失敗する可能性が
あります。その時点では@code{run-process}の呼び出し元にエラーを伝える
確実な方法が無いため、Gaucheは標準エラー出力にメッセージを印字して
exitします。頑健なプログラムを書く場合、そのようなケースにも留意して下さい。
@c COMMON
@end deftp


@deftp {run-process argument} sigmask @var{mask}
@c EN
@var{Mask} must be either an instance of @code{<sys-sigset>},
a list of integers, or 
@code{#f}.  If an instance of @code{<sys-sigset>} is given, the
signal mask of executed process is set to it.   A list of integers
are treated as a list of signals to mask.  It is important
to set an appropriate mask if you call @code{run-process} from
multithreaded application.
See the description of @code{sys-exec} (@ref{Process management})
for the details.

If the @var{host} keyword argument is specified, this argument
merely sets the signal mask of the local process (@code{ssh}).
@c JP
@var{mask}は@code{<sys-sigset>}のインスタンス、整数のリスト、
あるいは@code{#f}でなければなりません。
@code{<sys-sigset>}のインスタンスである場合、それが実行する
プロセスのシグナルマスクになります。整数のリストの場合は各整数が
マスクすべきシグナル番号とみなされます。マルチスレッドアプリケーションで
@code{run-process}を使う場合はシグナルマスクを適切に設定することが重要です。
@code{sys-exec}の説明を参照して下さい (@ref{Process management})。

@var{host}キーワード引数が与えられている場合は、この引数は
ローカル側のプロセス(@code{ssh})のみのシグナルマスクをセットします。
@c COMMON
@end deftp

@deftp {run-process argument} detached @var{flag}
@c EN
When a true value is given, the new process is detached from
the parent's process group and belongs to its own group.
It is useful when you run a daemon process.
See @code{sys-fork-and-exec} (@xref{Process management}), for
the detailed description of @var{detached} argument.
@c JP
真の値が渡されると、作られるプロセスは親プロセスのプロセスグループから
切り離され、独自のプロセスグループを作ります。
デーモンプロセスを作る際に便利です。@var{detached}引数の詳しい動作については、
@code{sys-fork-and-exec} を見てください (@ref{Process management}参照)。
@c COMMON
@end deftp


@deftp {run-process argument} host @var{hostspec}
@c EN
This argument is used to execute @var{command} on the remote host.
The full syntax of @var{hostspec} is @code{protocol:user@@hostname:port},
where @var{protocol:}, @var{user@@}, or @var{:port} part can be
omitted.  

The @var{protocol} part specifies the protocol to commnucate
with the remote host; currently only @code{ssh} is supported, and
it is also the default when @var{protocol} is omitted.
The @var{user} part specifies the login name of the remote host.
The @var{hostname} specifies the remote host name, and the
@var{port} part specifies the alternative port number which
@var{protocol} connects to.

The command line arguments are interpreted on the remote host.
On the other hand, the I/O redirection is done on the local end.
For example, the following code reads the file @file{/foo/bar} on
the remote machine and copies its content into the local file
@file{baz} in the current working directory.
@c JP
この引数は、@var{command}をリモートホストで実行させるのに使います。
@var{hostspec}の完全な構文は@code{protocol:user@@hostname:port}で、
@var{protocol:}、@code{user@@}、@code{:port}の部分は省略可能です。

@var{protocol}はリモートに接続するプロトコルを指定します。現在のところ
@code{ssh}だけがサポートされており、また省略された場合も@code{ssh}が
使われます。@var{user}はリモートでのユーザ名を、@var{hostname}は
リモートホスト名を指定します。@var{port}は@var{protocol}のデフォルト
以外のポートを使いたい場合に指定します。

コマンドライン引数はリモートホスト上で解釈されます。
一方、I/Oリダイレクトはローカル側で処理されす。
例えば、次のコードはリモートマシンの@file{/foo/bar}の内容を読み、
それをローカルのワーキングディレクトリ内のファイル@file{baz}へとコピーします。
@c COMMON

@example
(run-process '(cat "bar")
             :host "remote-host.example.com"
             :directory "/foo"
             :output "baz")
@end example
@end deftp

@node Process object, Process ports, Running subprocess, High Level Process Interface
@subsection Process object

@deftp {Class} <process>
@clindex process
@c EN
An object to keep the status of a child process.  You can create
the process object by @code{run-process} procedure described below.
The process ports explained in the next section also use process objects.
@c JP
子プロセスの状態を保持するためのオブジェクト。以下で説明される
@code{run-process} 手続きにより、プロセスを作ることができます。
次章で説明するプロセスポートもプロセスオブジェクトを用いています。
@c COMMON

@c EN
The @code{<process>} class keeps track of
the child processes spawned by high-level APIs such
as @code{run-process} or @code{open-input-process}.
The exit status of such children must be collected by
@code{process-wait} or @code{process-wait-any} calls,
which also do some bookkeeping.   Using
the low-level process calls such as @code{sys-wait} or
@code{sys-waitpid} directly will cause inconsistent state.
@c JP
@code{<process>}クラスは、@code{run-process}や@code{open-input-process}
といった高レベルAPIで作られた子プロセスの状態を管理しています。
それらの子プロセスの終了ステータスをとるには、
@code{process-wait}や@code{process-wait-any}といった
高レベルAPIを利用してください。これらの手続きはシステムコール以外の情報管理も
行います。@code{sys-wait}や@code{sys-waitpid}といった低レベルAPIで
直接子プロセスの終了ステータスを取ると、@code{<process>}クラスの
内部状態に矛盾が生じます。
@c COMMON
@end deftp

@deftp {Class} <process-abnormal-exit>
@clindex process-abnormal-exit
@c EN
A condition type mainly used by the process port utility procedures.
Inherits @code{<error>}.  This type of condition is thrown when
the high-level process port utilities detect the child proces exitted
with non-zero status code.
@c JP
主にプロセスポートユーティリティ関数で使われるコンディション型。
@code{<error>}を継承。このコンディション型は高レベルプロセスポートユーティ
リティが子プロセスが非ゼロのexitステータスで終了したことを検知したとき
に投げられます。
@c COMMON

@defivar {<process-abnormal-exit>} process
@c EN
A process object.
@c JP
プロセスオブジェクト。
@c COMMON
@end defivar

@c EN
Note: In Unix terms, exitting a process by calling @code{exit(2)} or 
returning from @code{main()} is a normal exit, regardless of the
exit status.  Some commands do use non-zero exit status
to tell one of the normal results of execution (such as @code{grep(1)}).  
However, large number of commands uses non-zero exit status to
indicate that they couldn't carry out the required operation,
so we treat them as exceptional situations.
@c JP
注: Unix用語では，exitステータスにかかわらず，プロセスがcalling
@code{exit(2)}を呼ぶか，@code{main()}から帰った場合を「正常な終了」と
しています。コマンドによっては非ゼロのexitステータスで何らかの正常な実行結果を
示すものもあります(@code{grep(1)}など)。しかし，ほとんどのコマ
ンドでは，非ゼロの exit ステータスは要求された操作が実行できなかったこ
とを表わします。それゆえ上のような場合を例外的な場合として扱います。
@c COMMON
@end deftp


@defun process? obj
@equiv{} @code{(is-a? @var{obj} <process>)}
@end defun

@deffn {Method} process-pid (process <process>)
@c EN
Returns the process ID of the subprocess @var{process}.
@c JP
サブプロセス @var{process} のプロセスIDを返します。
@c COMMON
@end deffn

@deffn {Method} process-command (process <process>)
@c EN
Returns the command invoked in the subprocess @var{process}.
@c JP
サブプロセス @var{process} 内で起動されたコマンドを返します。
@c COMMON
@end deffn

@deffn {Method} process-input (process <process>) :optional name
@deffnx {Method} process-output (process <process>) :optional name
@c EN
Retrieves one end of a pipe, whose another end is connected
to the process's input or output, respectively.
@var{name} is a symbol given to the @var{redirects} argument
of @code{run-process} to distinguish the pipe.  See the following
example:
@c JP
プロセスの入力もしくは出力に一方の端がつながれたパイプの、もう一方の端を取り出します。
@var{name}は@code{run-process}の@var{redirects}引数に与えた
識別用の名前です。次の例を見てください。
@c COMMON

@example
(let1 p (run-process '(command arg)
                     :redirects '((< 3 aux-in)
                                  (> 4 aux-out)))
  (let ([auxin  (process-input p 'aux-in)]
        [auxout (process-output p 'aux-out)])
    ;; feed something to the child's input
    (display 'something auxin)
    ;; read data from the child's output
    (read-line auxout)
    @dots{}
    )
  (process-wait p))
@end example

@c EN
The symbols @code{aux-in} and @code{aux-out} is used to 
identify the pipes.  Note that @code{process-input} returns
@emph{output} port, and @code{process-output} returns
@emph{input} port.
@c JP
シンボル@code{aux-in}と@code{aux-out}がパイプを識別するのに
使われています。@code{process-input}が返すのは@emph{出力}ポートであり、
@code{process-output}が返すのは@emph{入力}ポートであることに注意してください。
@c COMMON

@c EN
When @var{name} is omitted, @code{stdin} is used for @code{process-input}
and @code{stdout} is used for @code{process-output}.  These are
the names used if child's stdin and stdout are redirected by
@code{:input :pipe} and @code{:output :pipe} arguments, respectively.
@c JP
@var{name}が省略された場合、@code{process-input}は@code{stdin}を、
@code{process-output}は@code{stdout}を使います。これらは
子プロセスの標準入力/出力をそれぞれ@code{:input :pipe}/@code{:output :pipe}で
リダイレクトした場合に使われる名前です。
@c COMMON

@c EN
If there's no pipe with the given name, @code{#f} is returned.
@c JP
名前に対応するパイプが無い場合は@code{#f}が返ります。
@c COMMON

@example
(let* ((process (run-process '("date") :output :pipe))
       (line (read-line (process-output process))))
  (process-wait process)
  line)
 @result{} "Fri Jun 22 22:22:22 HST 2001"
@end example
@end deffn

@deffn {Method} process-error (process <process>)
@c EN
This is equivalent to @code{(process-output @var{process} 'stderr)}.
@c JP
これは@code{(process-output @var{process} 'stderr)}と等価です。
@c COMMON
@end deffn


@defun process-alive? process
@c EN
Returns true if @var{process} is alive.  Note that Gauche can't
know the subprocess' status until it is explicitly checked by
@code{process-wait}.
@c JP
@var{process} が生きている場合は真を返します。@code{process-wait} によって
明示的にチェックされない限り、Gauche はサブプロセスのステータスを知ることが
できないことに注意してください。
@c COMMON
@end defun

@defun process-list
@c EN
Returns a list of active processes.  The process remains active
until its exit status is explicitly collected by @code{process-wait}.
Once the process's exit status is collected and its state changed
to inactive, it is removed from the list @code{process-list} returns.
@c JP
アクティブなプロセスのリストを返します。プロセスは、その終了ステータスが
@code{process-wait} によって明示的に回収されない場合は、アクティブなまま
残ります。
ひとたび終了ステータスが回収され、プロセスの状態がインアクティブに
変更されると、そのプロセスは@code{process-list}が返すリストからは除かれます。
@c COMMON
@end defun

@defun process-wait process :optional nohang error-on-nonzero-status
@c EN
Obtains the exit status of the subprocess @var{process}, and stores it
to @var{process}'s status slot.  The status can be obtained by
@code{process-exit-status}.

This suspends execution until @var{process} exits by default.
However, if a true value is given to the optional argument @var{nohang},
it returns immediately if @var{process} hasn't exit.

If a true value is given to the optional argument
@var{error-on-nonzero-status}, and the obtained status code is not zero,
this procedure raises @code{<process-abnormal-exit>} error.

Returns @code{#t} if this call actually obtains the exit status,
or @code{#f} otherwise.
@c JP
サブプロセス @var{process} の終了ステータスを取得し、@var{process}
のstatusスロットに値を格納します。statusスロットの値は
@code{process-exit-status}で得ることができます。

デフォルトでは、この手続きは@var{process} が終了するまで実行を一時停止します。
しかし、@var{nohang}に真の値が与えられた場合は、@var{process}が終了して
いない場合にも直ちに返ります。

オプショナル引数@var{error-on-nonzero-status}に真の値が与えられた場合、
この手続きは得られた終了ステータスが0で無い場合に
@code{<process-abnormal-exit>}エラーを投げます。

この呼び出しによって@var{process}の終了ステータスが実際に取得された場合は
@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun process-wait-any :optional nohang
@c EN
Obtains the exit status of any of the subprocesses created by
@code{run-process}.
Returns a process object whose exit status is collected.

If a true value is given to the optional argument @var{nohang}, this procedure
returns @code{#f }immediately even if no child process has exit.
If @var{nohang} is omitted or
@code{#f}, this procedure waits for any of children exits.

If there's no child processes, this procedure immediately returns @code{#f}.
@c JP
@code{run-process}で作られたサブプロセスのどれかの終了ステータスを取得します。
終了ステータスが取得できたプロセスのプロセスオブジェクトを返します。

真の値が@var{nohang}に与えられた場合は、どの子プロセスも終了していない場合は
直ちに@code{#f}を返します。そうでなければ、この手続きはいずれかの子プロセスが
終了するまで待ちます。

子プロセスが存在しない場合は、この手続きは直ちに@code{#f}を返します。
@c COMMON
@end defun


@defun process-exit-status process
@c EN
Returns exit status of @var{process} retrieved by @code{process-wait}.
If this is called before @code{process-wait} is called on @var{process},
the result is undefined.

The meaning of exit status depends on the platform.  You need to
use @code{sys-wait-exited?} or @code{sys-wait-signaled?} to
see if it is terminated voluntarily or by a signal, and
use @code{sys-wait-exit-status} or @code{sys-wait-termsig}
to extract the exit code or the terminating signal
(@xref{Process management}).
@c JP
@code{process-wait}によって取得された@var{process}の終了ステータスを
返します。@var{process}に対して@code{process-wait}を呼ぶ前にこの手続きを
呼んだ場合の結果は未定義です。

終了ステータスの解釈はプラットフォームに依存します。プロセスが自発的に
(@code{exit}を呼んで)終了したか、それともシグナルによって終了させられたかを
確かめるには@code{sys-wait-exited?}か@code{sys-wait-signaled?}を
使ってください。また、終了コードもしくは終了と原因となったシグナルを
知るには@code{sys-wait-exit-status}を@code{sys-wait-termsig}
使ってください (@ref{Process management}参照)。
@c COMMON
@end defun

@defun process-send-signal process signal
@c EN
Sends a signal @var{signal} to the subprocess @var{process}.
@var{signal} must be an exact integer for signal number.
@xref{Signal}, for predefined variables of signals.
@c JP
サブプロセス @var{process} にシグナル @var{signal} を送ります。
@var{signal} は正確整数のシグナルナンバーでなければなりません。
シグナルの定義済み変数については、@ref{Signal}を参照して下さい。
@c COMMON
@end defun

@defun process-kill process
@defunx process-stop process
@defunx process-continue process
@c EN
Sends SIGKILL, SIGSTOP and SIGCONT to @var{process}, respectively.
@c JP
それぞれ、@var{process} に、SIGKILL、SIGSTOP、SIGCONT を送ります。
@c COMMON
@end defun

@node Process ports,  , Process object, High Level Process Interface
@subsection Process ports

@defun open-input-process-port command :key input error encoding conversion-buffer-size
@c EN
Runs @var{command} asynchronously in a subprocess.  Returns
two values, an input port which is connected to the stdout of the
running subprocess, and a process object.  
@c JP
@var{command} を子プロセスで非同期に実行します。
走らせた子プロセスの標準出力につながれた入力ポートと、
プロセスオブジェクトの二つの値を返します。
@c COMMON

@c EN
@var{Command} can be a string or a list.

If it is a string, it is passed to @code{/bin/sh}.
You can use shell metacharacters in this form, such as
environment variable interpolation, globbing, and redirections.
If you create the command line by concatenating strings,
it's your responsibility to ensure escaping special characters
if you don't want the shell to interpret them.  
The @code{shell-escape-string} function described below might
be a help.
@c JP
@var{command}は文字列かリストです。

文字列の場合、それは@code{/bin/sh}に渡されます。
環境変数の置換やグロブパターン、リダイレクトなどのシェルの機能が
文字列中で使えます。
文字列をつなぎ合わせてコマンドラインを作成する場合、
特殊文字をシェルに解釈してほしくなければ、それを正しくエスケープするのは
呼び出し元の責任です。下で説明する@code{shell-escape-string}は
助けになるかもしれません。
@c COMMON

@c EN
If @var{command} is a list, each element is converted to a
string by @code{x->string} and then passed directly to @code{sys-exec}
(the @code{car} of the list is used as both the command path
and the first element of argv, i.e. @code{argv[0]}).
Use this form if you want to avoid the shell from interfering;
i.e. you don't need to escape special characters.
@c JP
@var{command}がリストの場合は、各要素が@code{x->string}で文字列に
変換された後に、@code{sys-exec}を使って直接コマンドを起動します
(リストの@code{car}がコマンドのパス名と@code{argv[0]}の両方に使われます)。
シェルの介入を避けたい場合はこの形式を使うと良いでしょう。
特殊文字をエスケープする必要はありません。
@c COMMON

@c EN
The subprocess's stdin is redirected from @code{/dev/null}, 
and its stderr shares the calling process's stderr by default.
You can change these by giving file pathnames to @var{input} and
@var{error} keyword arguments, respectively.
@c JP
デフォルトでは、子プロセスの標準入力は@code{/dev/null}にリダイレクトされ、
標準エラー出力は呼び出したプロセスと共有されます。
@var{input}と@var{error}キーワード引数にパス名を与えることで、
これらの出力をリダイレクトすることができます。
@c COMMON

@c EN
You can also give the @var{encoding} keyword argument
to specify character encoding of the process output.  If it differs
from the Gauche's internal encoding format,
@code{open-input-process-port} inserts a character encoding
conversion port.  
If @var{encoding} is given, the @var{conversion-buffer-size} keyword
argument can control the conversion buffer size.
See @ref{Character code conversion}, for
the details of character encoding conversions.
@c JP
また、プロセスの出力の文字エンコーディングを指定するために
@var{encoding}キーワード引数を与えることもできます。
それがGaucheの内部エンコーディングと異なっていた場合、
@code{open-input-process-port}は文字コード変換ポートを挿入します。
@var{encoding}が与えられた場合、@var{conversion-buffer-size}キーワード引数で
変換バッファの大きさを指定することも可能です。文字コード変換の詳細については
@ref{Character code conversion}を参照して下さい。
@c COMMON
@example
(receive (port process) (open-input-process-port "ls -l Makefile")
  (begin0 (read-line port)
          (process-wait process)))
 @result{} "-rw-r--r--   1 shiro    users        1013 Jun 22 21:09 Makefile"

(receive (port process) (open-input-process-port '(ls -l "Makefile"))
  (begin0 (read-line port)
          (process-wait process)))
 @result{} "-rw-r--r--   1 shiro    users        1013 Jun 22 21:09 Makefile"

(open-input-process-port "command 2>&1")
 @result{} ;@r{the port reads both stdout and stderr}

(open-input-process-port "command 2>&1 1>/dev/null")
 @result{} ;@r{the port reads stderr}
@end example
@c EN
The exit status of subprocess is not automatically collected.
It is the caller's responsibility to issue @code{process-wait},
or the subprocess remains in a zombie state.  If it bothers you,
you can use one of the following functions.
@c JP
サブプロセスの終了ステータスは自動的に回収されません。
@code{process-wait} を呼ぶことは呼び出し側の責任であり、これを怠ると
サブプロセスはゾンビプロセスになります。それが面倒であれば、以下の
手続きを使うことができます。
@c COMMON
@end defun

@defun call-with-input-process command proc :key input error encoding conversion-buffer-size on-abnormal-exit
@c EN
Runs @var{command} in a subprocess and pipes its stdout
to an input port, then call @var{proc} with the port as an argument.
When @var{proc} returns, it collects its exit status,
then returns the result @var{proc} returned.
The cleanup is done even if @var{proc} raises an error.

The keyword argument @var{on-abnormal-exit} specifies what happens
when the child process exits with non-zero status code.
It can be either @code{:error} (default), @code{:ignore}, or
a procedure that takes one argument.  If it is @code{:error},
a @code{<process-abnormal-exit>} error condition is thrown by
non-zero exit status; the @code{process} slot of the condition
holds the process object.  If it is @code{:ignore}, nothing is done
for non-zero exit status.  If it is a procedure, it is called with
a process object; when the procedure returns, @code{call-with-input-process}
returns normally.

The semantics of @var{command} and other keyword arguments are the same
as @code{open-input-process-port} above.
@c JP
子プロセスで@var{command} を実行し、その標準出力と入力ポートを
パイプで繋ぎ、そのポートを引数として @var{proc} を呼び出します。
@var{proc} が返るとその終了ステータスを回収し、@var{proc} が返した
結果を返します。@var{proc} がエラーを通知しても、クリーンアップは
行われます。

キーワード引数@var{on-abnormal-exit}は子プロセスが0以外の終了ステータス
を返した場合の振舞いを指定します。その値は@code{:error}(デフォルト)、
@code{:ignore}、もしくは一引数の手続きでなければなりません。
値が@code{:error}の場合、0以外の終了ステータスは
@code{<process-abnormal-exit>}エラーコンディションを発生させます。
コンディションオブジェクトの@code{process}スロットには子プロセスオブジェクトが
保持されます。値が@code{:ignore}の場合、0以外の終了ステータスに対して
特別なアクションは取られません。値が手続きの場合、0以外の終了ステータスに対して
子プロセスオブジェクトを引数にしてその手続きが呼ばれます。その手続きが
戻れば、@code{call-with-input-process}は正常動作と同じように戻ります。

@var{command}および他のキーワード引数の意味は@code{open-input-process-port}と
同じです。
@c COMMON
@example
(call-with-input-process "ls -l *"
  (lambda (p) (read-line p)))
@end example
@end defun

@defun with-input-from-process command thunk :key input error encoding conversion-buffer-size on-abnormal-exit
@c EN
Runs @var{command} in a subprocess, and calls @var{thunk}
with its current input port connected to the command's stdout.
The command is terminated and its exit status is collected,
after @var{thunk} returns or raises an error.

The semantics of @var{command} and keyword arguments are the same
as @code{call-with-input-process} above.
@c JP
子プロセスで @var{command} を実行し、コマンドの標準出力に
接続された現在の入力ポートとともに @var{thunk} を呼び出します。
@var{thunk}が終了するかエラーを投げた後に、コマンドの終了ステータスが
回収されます。

@var{command}およびキーワード引数の意味は@code{call-with-input-process}と
同じです。
@c COMMON
@example
(with-input-from-process "ls -l *" read-line)
@end example
@end defun

@defun open-output-process-port command :key output error encoding conversion-buffer-size
@c EN
Runs @code{command} in a subprocess asynchronously.  Returns two values,
an output port which is connected to the stdin of the subprocess.
and the process object.

The semantics of @var{command} is the same as
@code{open-input-process-port}.  The semantics of
@var{encoding} and @var{conversion-buffer-size} are also the same.

The subprocess's stdout is redirected to @code{/dev/null} by default,
and its stderr shares the calling process's stderr.
You can change these by giving file pathnames to @var{output} and
@var{error} keyword arguments, respectively.

The exit status of the subprocess is not automatically collected.
The caller should call @code{process-wait} on the subprocess
at appropriate time.
@c JP
子プロセスで @code{command} を非同期に実行します。
子プロセスの標準入力に接続された出力ポートと、
プロセスオブジェクトの二つの値を返します。

@var{command}引数、および@var{encoding}と@var{conversion-buffer-size}の
意味は、@code{open-input-process-port}と同じです。

デフォルトでは、子プロセスの標準出力は@code{/dev/null}にリダイレクトされ、
標準エラー出力は呼び出したプロセスと共有されます。
@var{output}と@var{error}キーワード引数にパス名を与えることで、
これらの出力をリダイレクトすることができます。

サブプロセスの終了ステータスは自動的には回収されません。
適切なタイミングで、サブプロセスに対して @code{process-wait} を呼ぶ
必要があります。
@c COMMON
@end defun

@defun call-with-output-process command proc :key output error encoding conversion-buffer-size on-abnormal-exit
@c EN
Runs @code{command} in a subprocess, and calls @var{proc} 
with an output port which is connected to the stdin of the command.
The exit status of the command is collected after either @var{proc}
returns or raises an error.

The semantics of keyword arguments are the same as
@code{open-output-process-port}, except @var{on-abnormal-exit},
which is the same as described in @code{call-with-input-process}.
@c JP
@code{command} を子プロセスで実行し、コマンドの標準入力に
接続された出力ポートとともに @var{proc} を呼び出します。
コマンドの終了ステータスは、@var{proc} が返るかエラーを通知した
後に回収されます。

キーワード引数の意味は@var{open-output-process-port}と同じです。
ただし@var{on-abnormal-exit}については@code{call-with-input-process}
で説明したのと同じ意味です。
@c COMMON
@example
(call-with-output-process "/usr/sbin/sendmail"
  (lambda (out) (display mail-body out)))
@end example
@end defun

@defun with-output-to-process command thunk :key output error encoding conversion-buffer-size on-abnormal-exit
@c EN
Same as @code{call-with-output-process}, except that the
output port which is connected to the stdin of the command
is set to the current output port while executing @var{thunk}.
@c JP
コマンドの標準入力に接続された出力ポートが、@var{thunk} の実行中は
現在の出力ポートにセットされることを除いて、@code{call-with-output-process}
と同じです。
@c COMMON
@end defun

@defun call-with-process-io command proc :key error encoding conversion-buffer-size on-abnormal-exit
@c EN
Runs @var{command} in a subprocess, and calls @var{proc}
with two arguments; the first argument is an input port which
is connected to the command's stdout, and the second is an output
port connected to the command's stdin.  The error output from
the command is shared by the calling process's, unless
an alternative pathname is given to the @var{error} keyword argument.

The exit status of the command is collected when @var{proc}
returns or raises an error.
@c JP
@var{command} をサブプロセスで実行し、@var{proc} を2つの引数と
ともに呼び出します。最初の引数は入力ポートで、コマンドの標準出力に
接続されたものです。2番目の引数は出力ポートでコマンドの標準入力に
接続されたものです。コマンドからのエラー出力は、@var{error}キーワード
引数でパス名が指定されない限り、呼び出したプロセスのエラー出力が共有されます。

コマンドの終了ステータスは、@var{proc}が戻るかエラーを投げた場合に
回収されます。
@c COMMON
@end defun

@defun process-output->string command :key error encoding conversion-buffer-size on-abnormal-exit
@defunx process-output->string-list command :key error encoding conversion-buffer-size on-abnormal-exit
@c EN
Runs @var{command} and collects its output (to stdout) and returns them.
@code{process-output->string} concatenates all the output from @var{command}
to one string, replacing any sequence of whitespace characters to
single space.   The action is similar to ``command substitution''
in shell scripts.
@code{process-output->string-list} collects the output from
@var{command} line-by-line and returns the list of them.  Newline
characters are stripped.

Internally, @var{command} is run by @code{call-with-input-process},
to which keyword arguments are passed.
@c JP
@var{command} を実行し、その(標準出力への)出力を回収して返します。
@code{process-output->string} は @var{command} からの全ての出力を連結し
1つの文字列とします。その際、空白文字からなるシーケンスは1つの空白に
置換されます。このアクションは、シェルスクリプトにおける「コマンド置換」
に似たものです。
@code{process-output->string-list} は @var{command} からの出力を行ごとに
回収し、それらをリストにしたものを返します。改行文字は削除されます。

内部的には、@var{command} は @code{call-with-input-process} により
実行されます。キーワード引数は@code{call-with-input-process}に
そのまま渡されます。
@c COMMON
@example
(process-output->string '(uname -smp))
  @result{} "Linux i686 unknown"

(process-output->string '(ls))
  @result{} "a.out foo.c foo.c~ foo.o"

(process-output->string-list '(ls))
  @result{} ("a.out" "foo.c" "foo.c~" "foo.o")
@end example

@end defun

@defun shell-escape-string arg
@c EN
If @var{arg} contains characters that affects shell's command-line
argument parsing, escape @var{arg} to avoid shell's interpretation.
Otherwise, returns @var{arg} itself.

Use this procedure when you need to build a command-line string by yourself.
(If you pass a command-line argument list, instead of a single
command-line string, you don't need to escape them since we
bypass the shell.)

On Windows native build, this procedure is compatible to
the argument parsing convention of Windows standard C runtime.
@c JP
@var{arg}がシェルのコマンドライン引数解析に影響を与える文字を含んでいる場合、
それらがシェルによって解釈されないようにエスケープされた文字列を返します。
そうでなければ@var{arg}自体を返します。

自分でコマンドライン文字列を組み立てる必要がある場合に使ってください。
(単一のコマンドライン文字列でなく、コマンドライン引数のリストを渡す場合は
エスケープの必要はありません。引数はシェルを通さずに子プロセスに渡される
からです。)

Windowsネイティブビルドの場合、この手続きはWindowsの標準Cランタイムの
引数解析に合わせてあります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Record types, Reloading modules, High Level Process Interface, Library modules - Gauche extensions
@section @code{gauche.record} - Record types
@c NODE レコード型, @code{gauche.record} - レコード型

@deftp {Module} gauche.record
@mdindex gauche.record
This module provides a facility to define @emph{record types}, 
user-defined aggregate types.  
The API is upper compatible to SRFI-9 (Defining Record Types) and 
SRFI-99 (ERR5RS Records).
@end deftp

Record types are implemented as Gauche's classes, 
but have different characteristics from the general classes.
@xref{Record types introduction}, for when you want to
use record types.

The record API consists of three layers, following
SRFI-99 and R6RS design.  

The syntactic layer is the @code{define-record-type} macro
that conveniently defines a record type and related procedures
(a constructor, a predictate, accessors and modifiers) all at once
declaratively.   Knowing this macro alone is sufficient for
most common usage of records.

The inspection layer defines common procedures
to query information to the records and record types.

The procedural layer is a low-level machinery to implement
the syntactic layer; you don't usually need to use them
in day-to-day programming, but they might be handy to
create record types on-the-fly at runtime.

@menu
* Record types introduction::   
* Record types syntactic layer::  
* Record types inspection layer::  
* Record types procedural layer::  
* Pseudo record types::         
@end menu

@node Record types introduction, Record types syntactic layer, Record types, Record types
@subsection Introduction

Gauche provides a general way for users to define new types as new
classes, using object system (@xref{Object system}), and indeed
record types are implemented as Gauche's classes.
However, using record types instead of classes has several advantages.

@itemize
@item
It is portable.  The API conforms two major record SRFIs,
SRFI-9 and SRFI-99, so the code using record types can run on
various Scheme systems.
@item
It is efficient.  Record types are less flexibile than classes,
but that allows Gauche to optimize more.  Hence creating records and
accessing/modifying them are much faster than creating instances
of general classes and accessing/modifying them.  It makes record
types preferable choice when you only need a mechanism to bundle
several related values to carry around, and don't need fancier
mechanisms such as class redefinitions.
@item
As Gauche's extention, you can define pseudo record types,
which interpretes ordinary aggregate types such as vectors and lists
as records.  (For Common Lisp users; it is like the @code{:type}
option of @code{defstruct}).
This helps flexibility of interface.  For example, you can ask
your library's users to pass a point in a vector of three numbers,
instead of asking users to pack their point data into your
custom point record type.  Yet inside your library you can
treat the passed data as if it is your point record type.
See @ref{Pseudo record types}, for more details.
@end itemize

The disadvantage of record types is that 
they don't obey Gauche's class redefinition
protocol (@xref{Class redefinition}).
That is, if you redefine a record with the same name,
it creates a new record type unrelated to the old one.
The record instances created from the old definition
won't be updated according to the new definition.

More importantly, record constructors, accessors and modifiers
are tend to be inlined where they are used, to achieve
better performance.   Since they are inlined, the code
that uses those procedures are not affected when
the record type is redefined.
This means if you redefine a record type, you have to 
reload (recompile) the sources that uses any of
record constructors, accessors or modifiers.


@node Record types syntactic layer, Record types inspection layer, Record types introduction, Record types
@subsection Syntactic Layer


@defmac define-record-type type-spec ctor-spec pred-spec field-spec @dots{}
[SRFI-9][SRFI-99+]
Defines a record type, and optionally defines
a constructor, a predicate, and field accessors and modifiers.

The @var{type-spec} argument names the record type,
and optionally specifies the supertype (@var{parent}).

@example
@var{type-spec} : @var{type-name} | (@var{type-name} @var{parent})

@var{type-name} : @r{identifier}
@var{parent} : @r{expression}
@end example

The @var{type-name} identifier will be bound to a
@emph{record type descriptor}, or rtd,
which can be used for introspection and reflection.
See @ref{Record types inspection layer} and @ref{Record types procedural layer}
for possible operations for record types.
In Gauche, a record type descriptor is a @code{<class>} with a metaclass
@code{<record-meta>}.

The @var{parent} expression should evaluate to a record type descriptor.
If given, the defined record type inherits it; that is, all the
slots defined in the parent type are available to the @var{type-name}
as well, and the instance of @var{type-name} answers @code{#t} to the
predicate of the parent type.

Since a record type is also a class, parent type is also a superclass
of the defined record type.  However, record types are limited to
have single inheritance.

You can give a pseudo record base type as @var{parent} to define a
pseudo record type, which allows you to access ordinary aggregates
like vectors as records.  See @ref{Pseudo record types} for more details.

The @var{ctor-spec} defines the constructor of the record instance.

@example
@var{ctor-spec} : #f | #t | @var{ctor-name}
          | (@var{ctor-name} @var{field-name} @dots{})

@var{ctor-name} : @r{identifier}
@var{field-name} : @r{identifier}
@end example

If it is @code{#f}, no constructor is created.
If it is @code{#t}, a default constructor is created with a name
@code{make-@var{type-name}}.  If it is a single identifier 
@var{ctor-name}, a default constructor is created with the name.
The default constructor takes as many arguments as
the number of fields of the record, including inherited ones if any.
When called, it allocates an instance of the record, and initialize its
fields with the given arguments in the order (inhertied fields comes
first), and returns the record.

The last variation of @var{ctor-spec} creates a custom
constructor with the name @var{ctor-name}.  The custom constructor
takes as many arguments as the given @var{field-name}s, and initializes
the named fields.  If the inherited record type has a field of the same name
as the ancestor record type, only the inherited ones are initialized.
In Gauche, uninitialized fields remains unbound until some value is
set to it.

The @var{pred-spec} defines the predicate of the record instance,
which takes one argument and returns @code{#t} iff it is an instance
of the defined record type or its descendants.

@example
@var{pred-spec} : #f | #t | @var{pred-name}

@var{pred-name} : @r{identifier}
@end example

If it is @code{#f}, no predicate is created.
If it is @code{#t}, a predicate is created with a name
@code{@var{type-name}?}.  If it is a single identifier,
a predicate is created with the given name.

The rest of the arguments specify fields (slots) of the record.

@example
@var{field-spec}
 : @var{field-name}   ; @r{immutable, with default accessor}
 | (@var{field-name}) ; @r{mutable, with default accessor/modifier}
 | (@var{field-name} @var{accessor-name}); @r{immutable}
 | (@var{field-name} @var{accessor-name} @var{modifier-name}); @r{mutable}

@var{field-name}    : @r{identifier}
@var{accessor-name} : @r{identifier}
@var{modifier-name} : @r{identifier}
@end example

The first and the third forms define immutable fields, which can only
be intialized by the constructor but cannot be modified afterwards
(thus such fields don't have modifiers).
The second and the fourth forms define multable fields.

The third and fourth forms explicitly name the accessor and modifier.
With the first and second forms, on the other hand,
the accessor is named as
@code{@var{type-name}-@var{field-name}}, and the modifier is named
as @code{@var{type-name}-@var{field-name}-set!}.
@end defmac

Let's see some examples.  Here's a definition of a record
type @code{point}.

@example
(define-record-type point #t #t
  x y z)
@end example

The variable @code{point} is bound to a record type descriptor,
which is just a class.  But you can take its class and see it is
indeed an instance of @code{<record-meta>} metaclass.

@example
point            @result{} #<class point>
(class-of point) @result{} #<class <record-meta>>
@end example

You can create an instance of @code{point} by the default
constructor @code{make-point}.  The predicate is given the
default name @code{point?}, and you can access the fields
of the created record by @code{point-x} etc.

@example
(define p (make-point 1 2 3))

(point? p)  @result{} #t
(point-x p) @result{} 1
(point-y p) @result{} 2
(point-z p) @result{} 3
@end example

Since we defined all fields immutable, we cannot modify 
the instance @code{p}.

Here's a mutable version of point, @code{mpoint}.
You can modify its fields by modifier procedures and
generalized @code{set!}.

@example
(define-record-type mpoint #t #t
  (x) (y) (z))

(define p2 (make-mpoint 1 2 3)) ; @r{create an instance}

(mpoint-x p2)  @result{} 1

(mpoint-x-set! p2 4)            ; @r{default modifier}
(mpoint-x p2)  @result{} 4

(set! (mpoint-x p2) 6)          ; @r{generalized @code{set!} also works} 
(mpoint-x p2)  @result{} 6
@end example

Next one is an example of inheritance.  
Note that the default constructor takes arguments for
fields of the parent record as well.

@example
(define-record-type (qpoint mpoint) #t #t
  (w))

(define p3 (make-qpoint 1 2 3 4))

(qpoint? p3)  @result{} #t      ; @r{p3 is a qpoint}
(mpoint? p3)  @result{} #t      ; @r{... and also an mpoint}

(mpoint-x p3) @result{} 1       ; @r{accessing inherited field}
(mpoint-y p3) @result{} 2
(mpoint-z p3) @result{} 3
(qpoint-w p3) @result{} 4
@end example

A small caveat: Accessors and modifiers for inherited fields
(e.g. @code{qpoint-x} etc.) are not created.

Gauche's convention is to enclose class name by @code{<>}.
You can follow the convention and still explicitly gives
simpler names (instead of @code{make-<point>} or @code{<point>-x}):

@example
(define-record-type <point> make-point point?
  (x point-x)
  (y point-y)
  (z point-z))
@end example


@node Record types inspection layer, Record types procedural layer, Record types syntactic layer, Record types
@subsection Inspection layer

This layer provides common procedures that operates on record type
descriptors and record instances.

Note that a record type descriptor is a class in Gauche, so 
you can also use operators on classes (e.g. @code{class-name},
@code{class-slots} etc.) on record type descriptors as well.
However, these procedures are more portable.

@defun record? obj
[SRFI-99][R6RS]
Returns @code{#t} iff @var{obj} is an instance of record type,
@code{#f} otherwise.
@end defun

@defun record-rtd record
[SRFI-99][R6RS]
Returns the record type descriptor of the record instance.
@end defun

@defun rtd-name rtd
[SRFI-99]
Returns the name of the record type descriptor @var{rtd}.
@end defun

@defun rtd-parent rtd
[SRFI-99]
Returns the parent type of the record type descriptor @var{rtd}.
If @var{rtd} doesn't have a parent, @code{#f} is returned.
@end defun

@defun rtd-field-names rtd
[SRFI-99]
Returns a vector of symbols, each of which is the names of the direct
fields of the record represented by @var{rtd}.   The result doesn't
include inherited fields.
@end defun

@defun rtd-all-field-names rtd
[SRFI-99]
Returns a vector of symbols, each of which is the names of the
fields of the record represented by @var{rtd}.   The result includes
all inherited fields.
@end defun

@defun rtd-field-mutable? rtd field-name
[SRFI-99]
Returns @code{#t} iff the field with the name @var{field-name}
of a record represened by @var{rtd} is mutable.
@end defun


@node Record types procedural layer, Pseudo record types, Record types inspection layer, Record types
@subsection Procedural layer

These procedures are low-level machinery on top of which
@code{define-record-type} is implemented.  They can be used
to create a new record type at runtime.

@defun make-rtd name field-specs :optional parent
[SRFI-99]
Creates and returns a new record type descriptor with name @var{name} and
having fields specified by @var{field-specs}.  If @var{parent}
is given, it must be a record type descriptor or @code{#f}.
If it is a record type descriptor, the created record type
inherits from it.

The @var{field-specs} argument must be a vector, each
element of which is a @emph{field specifier}.  A field
specifier can be a symbol, a list @code{(mutable @var{symbol})},
or a list @code{(immutable @var{symbol})}.  The @var{symbol} names
the field.  A single symbol or @code{(mutable @var{symbol})} format
makes the field mutable, and @code{(immutable @var{symbol})} format
makes the field immutable.

Note: Gauche does not implement the extension suggested in
SRFI-99 yet, which is @code{sealed}, @code{opaque} and @code{uid}
arguments.
@end defun

@defun rtd? obj
[SRFI-99]
Returns @code{#t} if @var{obj} is a record type descriptor,
@code{#f} otherwise.
@end defun

@defun rtd-constructor rtd :optional field-specs
[SRFI-99]
Returns a procedure that creates an instance record of
the record type represented by @var{rtd}.
Without @var{field-specs}, it returns the default constructor,
which takes as many arguments as the number of fields of
the record to initialize them.  

You can give a vector of symbols as @var{field-specs}.  The @var{n}-th
symbol specifies which field of the instance should be initialized
by the @var{n}-th argument.   The @var{field-specs} vector cannot
contain duplicate names.  If the record type defines a field with
the same name as the one in the parent record type, the custom constructor
can only initialize the field of the derived type's instance.
@end defun

@defun rtd-predicate rtd
[SRFI-99]
Returns a predicate to test an object is an instance of @var{rtd}.

If @var{rtd} is a pseudo record type, the predicate merely tests
the given object is in an appropriate type and has enough size
to hold the contents.   See @ref{Pseudo record types} for the details.
@end defun

@defun rtd-accessor rtd field-name
[SRFI-99]
Returns a procedure that takes one argument, an instance of @var{rtd},
and returns the value of the @var{field-name} of the instance.

An error is signalled if the record type doesn't have the field
of name @var{field-name}.

If @var{rtd} is inherits other record types, and it defines a field
of the same name as inherited ones, then the accessor returned by
this procedure retrieves the value of the field of the derived record.
@end defun

@defun rtd-mutator rtd field-name
[SRFI-99]
Returns a procedure that takes two arguments, an instance of @var{rtd}
and a value, and sets the latter as the value of the @var{field-name}
of the instance.

An error is signalled if the record type doesn't have the field
of name @var{field-name}, or the named field is immutable.

Like @code{rtd-accessor}, if the record has a field with the same
name as inherited one, the modifier returned by this procedure
only modifies the field of the derived record.
@end defun


@node Pseudo record types,  , Record types procedural layer, Record types
@subsection Pseudo record types

A pseudo record type is a record type that does not create 
an instance.  Instead it treats an object of other collection
types, such as a vector, as if it had named fields.  It's easier
to understand by an example:

@example
(define-record-type (vpoint (pseudo-rtd <vector>)) #t #t
  (x) (y) (z))

(make-vpoint 1 2 3)  @result{} #(1 2 3)
(vpoint-x #(1 2 3))  @result{} 1

(rlet1 v (make-vpoint 1 2 3)
  (set! (vpoint-y v) -1))
 @result{} #(1 -1 3)
@end example

To create a pseudo record type, specify another pseudo
record type as a parent.   The procedure @code{pseudo-rtd}
can be used to obtain a base pseudo record type of
the suitable instance class.

@defun pseudo-rtd instance-class
Returns a pseudo rtd suitable to use @var{instance-class} as
a pseudo record.
@end defun



@c ----------------------------------------------------------------------
@node Reloading modules, Simple dispatcher, Record types, Library modules - Gauche extensions
@section @code{gauche.reload} - Reloading modules
@c NODE モジュールの再ロード, @code{gauche.reload} - モジュールの再ロード

@deftp {Module} gauche.reload
@mdindex gauche.reload
@c EN
In the development cycle, you often have to reload modules frequently.
This module supports it.

Note that some part of semantics of the program depends on
the order of loading modules, so reloading arbitrary modules
may change the program behavior unexpectedly.  This module
is for developers who knows what they are doing.
@c JP
開発のサイクルのなかで、モジュールを再ロードしなければならないことは
頻繁におこります。このモジュールはそれを支援するものです。

プログラムのいくつかの部分のセマンティクスはモジュールのロードの順に
依存します。それで、任意のモジュールを再ロードすることはプログラムの
ふるまいを予期せぬものに変えてしまう可能性があります。このモジュールは
自分がなにをしようとしているか判っている開発者向けのものです。
@c COMMON

@c EN
@strong{Redefinition rules}: Reloading a module resets all
the binding in the module by default.
Sometimes it is not desirable, however.  For example,
you might want to keep an intermediate results in some variable.
You can specify rules for the reloading procedure to determine
which binding to keep.

The rule is described in the following syntax.
@c JP
@strong{再定義ルール}: モジュールを再ロードすると、デフォルトでは、その
モジュール内のすべての束縛はリセットされます。
しかしながら、場合によってこれは望ましいことではありません。たとえば、
中間結果をある変数に残したままにしておきたい場合です。
再ロード手続きにどの束縛を保存するかを決めるためのルールを指定することが
できます。

このルールは以下の構文で記述します。
@c COMMON
@example
  <module-rules> : (<module-rule> @dots{})
  <module-rule>  : (<module-pattern> <rule> @dots{})
  <module-pattern> : @r{a symbol module name, or a symbol containing glob pattern}
  <rule>         : @r{procedure} | @r{symbol} | @r{regexp}
                 | (and <rule> @dots{})
                 | (or  <rule> @dots{})
                 | (not <rule>)
@end example

@c EN
@code{<module-rules>} is the global rule to determine per-module
rules.  @code{<module-pattern>} is either a symbol module name
or a symbol that contains glob pattern (e.g. @code{mylib.*}).
If @code{<rule>} is a procedure, it is used as a predicate
and the bindings whose value satisfies the predicate are kept from
redefinition.   If @code{<rule>} is a symbol, the binding of
the variable whose name is the symbol is kept.  If @code{<rule>}
is a regexp, the bindings of the variable whose name matches the
regexp are kept.

Note that the mechanism to prevent redefinition is kind of ad-hoc
hack and semantically unclean.  Especially, the right-hand expressions
of @code{define}s are still evaluated, so any side effects they have
will be in effect (e.g. @code{define-class} would still redefine a class).
It's just for your convenience.
Take a look at the code if you want to know the exact behavior.
@c JP
@code{<module-rules>} はモジュールごとのルールをきめるグローバルルール
です。@code{<module-pattern>} はモジュール名シンボルまたは(@code{mylib.*}
のような)グロブパターンを含むシンボルのどちらかです。@code{<rule>} が
手続きであれば、述語として使われ、この述語を満す値の束縛は再定義から
保護されます。@code{<rule>} がシンボルであれば、それと同じ名前の
変数の束縛は保護されます。@code{<rule>} が正規表現の場合、この正規表現に
マッチする名前の変数は保護されます。

再定義からの保護機構は、場当たり的なもので、セマンティクスとしても
不透明なものであることに注意してください。特に@code{define}の右辺式は
評価されてしまうので、そこで起きる副作用は効果を持ちます (例えば
@code{define-class}はクラスの再定義を行ってしまいます)。
これは利便のためだけのものだと考えて下さい。
正確な振舞いを知りたければ、コードを見てください。
@c COMMON
@end deftp

@defun reload module-name :optional rule @dots{}
@c EN
Reloads the specified module.   You can optionally specify
redefinition rules by @var{rule} @dots{},
where each @var{rule} is the term @code{<rule>} defined above.
@c JP
指定されたモジュールを再ロードします。オプションで
@var{rule} @dots{} をつかって再定義ルールを指定することができます。
ここで、それぞれの @var{rule} は上の @code{<rule>} で定義されたものです。
@c COMMON
@end defun

@defun reload-modified-modules :optional module-rules
@c EN
Reloads module(s) that have been modified since they are loaded
last time.  If optional @var{module-rules} is given, it is
used to determine the redefinition rules for reloaded modules.
If @var{module-rules} is omitted, the current rules are used.
The default of current rules is empty.   You can set the current
rules by @code{module-reload-rules}.
@c JP
前回ロードしたときより変更のあったモジュールを再ロードします。
オプション引数 @var{module-rules} が与えられていれば、再ロードした
モジュールに適用する再定義ルールを決定するために使います。
@var{module-rules}が省略された場合、現在のルールが適用されます。
デフォルトの現在のルールは空です。現在のルールは
@code{module-reload-rules}をつかって設定できます。

@c COMMON
@end defun

@defun module-reload-rules :optional module-rules
@c EN
This is a parameter (@xref{Parameters}) that keeps
the default module rules for @code{reload-modified-modules}.
If called without arguments, returns the current module rules.
If called with @var{module-rules}, sets the argument to the
current module rules.
@c JP
これは一種の「パラメータ」(@ref{Parameters}参照)で、
@code{reload-modified-modules}に対応するデフォルトのモジュールルールを
保持しています。引数なしで呼ばれたときには、現在のモジュールルールを
返します。@var{module-rules}とともに呼ばれたきにはその引数を
現在のモジュールルールにします。
@c COMMON
@end defun

@defun reload-verbose :optional flag
@c EN
This is a parameter to control verbosity of the reloading procedures.
If called without arguments, returns the current verbosity flag.
If called with @var{flag}, it is set to the current verbosity flag.
@c JP
これは再ロード手続きのメッセージ出力レベルを制御するパラメータです。
引数なしで呼ばれると現在の出力レベルフラグを返します。@var{flag}と
ともに呼ばれると現在の出力レベルをこれに設定します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Simple dispatcher, Sequence framework, Reloading modules, Library modules - Gauche extensions
@section @code{gauche.selector} - Simple dispatcher
@c NODE 簡単なディスパッチャ, @code{gauche.selector} - 簡単なディスパッチャ

@deftp {Module} gauche.selector
@mdindex gauche.selector
@c EN
This module provides a simple interface to dispatch I/O events to
registered handlers, based on @code{sys-select} (@xref{I/O multiplexing}).
@c JP
このモジュールは、@code{sys-select} (@ref{I/Oの多重化}参照)に基づき、
登録されたハンドラにI/Oイベントをディスパッチするためのシンプルな
インタフェースを提供します。
@c COMMON
@end deftp

@deftp {Class} <selector>
@clindex selector
@c EN
A dispatcher instance that keeps watching I/O ports with associated
handlers.  A new instance can be created by @code{make} method.
@c JP
ディスパッチャのインスタンスで、ハンドラを携えてI/Oポートを監視します。
@code{make}メソッドで新しいインスタンスを作れます。
@c COMMON
@end deftp


@deffn {Method} selector-add! (self <selector>) port-or-fd proc flags
@c EN
Add a handler @var{proc} to the selector.  @var{proc} is called
when @var{port-or-fd}, which should be a port object or an integer
that specifies a system file descriptor,  meets a certain condition
specified by @var{flags}.
@var{flags} must be a list of one or more of the following symbols.
@c JP
セレクタにハンドラ@var{proc}を追加します。@var{proc}は、@var{port-or-fd}
(ポートオブジェクトかシステムのファイルディスクリプタを表す整数)が
@var{flags}で指定された条件に合致した場合に呼ばれます。
@var{flags}は、以下のシンボルの1つ以上のリストでなければなりません。
@c COMMON
@c EN
@table @code
@item r
Calls @var{proc} when data is available at @var{port-or-fd} to read.
@item w
Calls @var{proc} when @var{port-or-fd} is ready to be written.
@item x
Calls @var{proc} when an exceptional condition occurs on @var{port-or-fd}.
@end table
@c JP
@table @code
@item r
@var{port-or-fd}が読み取り可能になった時点で@var{proc}が呼ばれます。
@item w
@var{port-or-fd}が書き込み可能になった時点で@var{proc}が呼ばれます。
@item x
@var{port-or-fd}で例外的な状況が発生した場合に@var{proc}が呼ばれます。
@end table
@c COMMON

@c EN
@var{proc} is called with two arguments.  The first one is @var{port-or-fd}
itself, and the second one is a symbol @code{r}, @code{w} or @code{x},
indicating the condition.
@c JP
@var{proc}は、2引数で呼ばれます。1つ目は@var{port-or-fd}そのもので、
2つ目は条件を表すシンボル、@code{r}、@code{w}あるいは@code{x}です。
@c COMMON

@c EN
If a handler is already associated with @var{port-or-fd} under the
same condition, the previous handler is replaced by @var{proc}.
@c JP
同じ条件の下ですでに@var{port-or-fd}にハンドラが関連付けられていた場合は、
以前のハンドラが@var{proc}で置き換えられます。
@c COMMON
@end deffn

@deffn {Method} selector-delete! (self <selector>) port-or-fd proc flags
@c EN
Deletes the handler entries that matches @var{port-or-fd}, @var{proc}
and @var{flags}.   One or more of the arguments may be @code{#f},
meaning ``don't care''.  For example,
@c JP
@var{port-or-fd}、@var{proc}、@var{flags}にマッチするハンドラエントリを
削除します。引数のいずれかが@code{#f}である場合は、それが何でも良いことを
意味します。例えば、
@c COMMON
@example
(selector-delete! selector the-port #f #f)
@end example
@c EN
deletes all the handlers associated to @var{the-port}, and
@c JP
@var{the-port}に関連付けられた全てのハンドラを削除します。
@c COMMON
@example
(selector-delete! selector #f #f '(w))
@end example
@c EN
deletes all the handlers waiting for writable condition.
@c JP
書き込み可能になるのを待っている全てのハンドラを削除します。
@c COMMON
@end deffn


@deffn {Method} selector-select (self <selector>) :optional (timeout #f)
@c EN
Dispatcher body.  Waits for the conditions registered in @var{self},
and when it occurs, calls the associated handler.
@c JP
ディスパッチャのボディです。@var{self}に登録された条件を待ち、条件が合致すると
それに関連付けられたハンドラを呼びます。
@c COMMON
@c EN
If the @var{timeout} argument is omitted or false, this method waits
indefinitely.  Alternatively you can give a timeout value, that can
be a real number in microseconds, or a list of two integers that
represents seconds and microseconds.
@c JP
@var{timeout}引数が省略されるか偽の場合、このメソッドは永久に待ちます。
タイムアウトの値を与える場合は、マイクロ秒を表す実数か、秒とマイクロ秒を
表す2つの整数のリストを与えます。
@c COMMON

@c EN
Returns the number of handlers called.  Zero means the selector has been
timed out.
@c JP
戻り値は、ハンドラが呼ばれた回数です。0(ゼロ)は、セレクタがタイムアウト
したことを意味します。
@c COMMON

@c EN
It is safe to modify @var{self} inside handler.  The change will be
effective from the next call of @code{selector-select}
@c JP
ハンドラの中で@var{self}を変更することは安全です。その変更は、次回の
@code{selector-select}の呼び出し以降に反映されます。
@c COMMON
@end deffn

@c EN
This is a simple example of "echo" server:
@c JP
echoサーバのシンプルな例を示します。
@c COMMON

@example
(use gauche.net)
(use gauche.selector)

(define (echo-server port)
  (let ((selector (make <selector>))
        (server   (make-server-socket 'inet port :reuse-addr? #t)))

    (define (accept-handler sock flag)
      (let* ((client (socket-accept server))
             (output (socket-output-port client)))
        (selector-add! selector
                       (socket-input-port client :buffering #f)
                       (lambda (input flag)
                         (echo client input output))
                       '(r))))

    (define (echo client input output)
      (let ((str (read-block 4096 input)))
        (if (eof-object? str)
            (begin (selector-delete! selector input #f #f)
                   (socket-close client))
            (begin (display str output)
                   (flush output)))))

    (selector-add! selector
                   (socket-fd server)
                   accept-handler
                   '(r))
    (do () (#f) (selector-select selector))))
@end example

@c ----------------------------------------------------------------------
@node Sequence framework, Syslog, Simple dispatcher, Library modules - Gauche extensions
@section @code{gauche.sequence} - Sequence framework
@c NODE シーケンスフレームワーク, @code{gauche.sequence} - シーケンスフレームワーク

@deftp {Module} gauche.sequence
@mdindex gauche.sequence
@c EN
Provides a generic operations on @emph{sequences}.
A sequence is a collection with ordered elements.
Besides all the operations applicable on collections,
you can associate integer index to each element,
and apply order-aware operations on the elements.
@c JP
@emph{シーケンス}に関するジェネリックな操作を提供するモジュールです。
シーケンスとは、コレクションのうち要素の順序が規定されているものです。
コレクションの操作全てに加え、シーケンスに対しては、
各要素に整数のインデックスを関連づけること、
それから要素の順序が影響する操作を適用することができます。
@c COMMON

@c EN
This module inherits @code{gauche.collection} (@xref{Collection framework}).
All the collection generic operations can be applied to a sequence as well.
@c JP
このモジュールは@code{gauche.collection}を継承しています
(@ref{Collection framework}参照)。
コレクションに使えるジェネリックな操作は全てシーケンスに対しても適用可能です。
@c COMMON

@c EN
Among Gauche builtin class, lists, vectors and strings are sequences
and the specialized methods are defined for them.   Other extension
types, such as SRFI-4 uniform vector, have the methods as well.
@c JP
Gauche組み込みクラスのうち、リスト、ベクター、そして文字列は
シーケンスであり、このモジュールでメソッドが定義されます。
また@code{gauche.uvector}のユニフォームベクタ等、
いくつかの拡張データタイプはシーケンスとなっています。
@c COMMON
@end deftp

@menu
* Fundamental sequence accessors::  
* Slicing sequence::            
* Mapping over sequences::      
* Other operations over sequences::  
* Implementing sequence::       
@end menu

@node Fundamental sequence accessors, Slicing sequence, Sequence framework, Sequence framework
@subsection Fundamental sequence accessors
@c NODE 基本的なシーケンスのアクセサ

@deffn {Method} ref (seq <sequence>) index :optional fallback
@c EN
Returns @var{index}-th element of the sequence @var{seq}.
This method enables uniform access for any sequence types.

When @var{index} is less than zero, or greater than or equal to the
size of the sequence, @var{fallback} is returned if provided, or
an error is signalled if not.
@c JP
シーケンス@var{seq}の@var{index}番目の要素を返します。
このメソッドによって、全てのシーケンスが統一的にアクセスできます。

@var{index}が負値だったりシーケンスのサイズ以上だった場合は、
@var{fallback}が与えられていればそれが返され、
そうでなければエラーとなります。
@c COMMON

@example
(ref '(a b c) 1)  @result{} b
(ref '#(a b c) 1) @result{} b
(ref "abc" 1)     @result{} #\b
@end example
@end deffn

@deffn {Method} {(setter ref)} (seq <sequence>) index value
@c EN
Sets @var{value} to the @var{index}-th element of the sequence @var{seq}.
This is the uniform sequence modifier.

Note: Some sequences may not support arbitrary modification by index.
For example, if you have a sequence representing a set of sorted integers,
you cannot modify @var{i}-th element with arbitrary value.  Yet such
sequence may provide other means of modification, such as inserting
or deleting elements.
@c JP
統一的なシーケンスの変更メソッドです。
シーケンス@var{seq}の@var{index}番目の要素に@var{value}をセットします。

註: シーケンスによってはインデックスによる変更をサポートしていない
場合があります。例えば「ソートされた整数」を表すシーケンスがあった場合、
@code{i}番目の要素を適当な整数で置き換えることはできないでしょう。
そのようなシーケンスでも、要素の挿入や削除など、別の方法でシーケンスを
変更する手段が与えられるかもしれません。
@c COMMON

@example
(let ((x (list 'a 'b 'c)))
  (set! (ref x 1) 'z)
  x) @result{} (a z c)

(let ((x (vector 'a 'b 'c)))
  (set! (ref x 1) 'z)
  x) @result{} #(a z c)

(let ((x (string #\a #\b #\c)))
  (set! (ref x 1) #\z)
  x) @result{} "azc"
@end example
@end deffn

@deffn {Method} referencer (seq <sequence>)
@end deffn

@deffn {Method} modifier (seq <sequence>)
@end deffn

@node Slicing sequence, Mapping over sequences, Fundamental sequence accessors, Sequence framework
@subsection Slicing sequence
@c NODE シーケンスのスライス

@deffn {Method} subseq (seq <sequence>) :optional start end
@c EN
Retrieve a subsequence of the sequence @var{seq}, from
@var{start}-th element (inclusive) to @var{end}-th element (exclusive).
If @var{end} is omitted, up to the end of sequence is taken.
The type of the returned sequence is the same as @var{seq}.
@c JP
シーケンス@var{seq}の、@var{start}番目の要素から@var{end}番目の要素の直前
までの部分シーケンスを返します。@var{end}が省略された場合はシーケンスの
最後までが取られます。返されるシーケンスの型は@var{seq}と同じになります。
@c COMMON

@example
(subseq '(a b c d e) 1 4)   @result{} (b c d)
(subseq '#(a b c d e) 1 4)  @result{} #(b c d)
(subseq "abcde" 1 4)        @result{} "bcd"

(subseq '(a b c d e) 3)     @result{} (d e)
@end example
@end deffn

@deffn {Method} {(setter subseq)} (seq <sequence>) start end value-seq
@deffnx {Method} {(setter subseq)} (seq <sequence>) start value-seq
@c EN
Sets the elements of @var{value-seq} from the @var{start}-th element
(inclusive) to the @var{end}-th element (exclusive) of the sequence @var{seq}.
@var{Value-seq} can be any sequence, but its size
must be larger than (@var{end} - @var{start}).

In the second form, @var{end} is figured out by the length of @var{value-seq}.
@c JP
@var{value-seq}の各要素を、シーケンス@var{seq}の@var{start}番目から
@var{end}番目の直前まで順にセットします。
@var{value-seq}はどんなシーケンスでも構いませんが、
(@var{end} - @var{start}) よりは長くなくてはなりません。

2番目の形式では、@var{end}が@var{value-seq}の長さから算出されます。
@c COMMON

@example
(define s (vector 'a 'b 'c 'd 'e))
(set! (subseq s 1 4) '(4 5 6))
s @result{} #(a 4 5 6 e)
(set! (subseq s 0)   "ab")
s @result{} #(#\a #\b 5 6 e)
@end example
@end deffn

@node Mapping over sequences, Other operations over sequences, Slicing sequence, Sequence framework
@subsection Mapping over sequences
@c NODE シーケンス上のマップ

@c EN
You can use extended @code{fold}, @code{map}, @code{for-each} and other
generic functions on sequences, since a sequence is also a collection.
However, sometimes you want to have index as well as the element itself
during iteration.   There are several generic functions for it.
@c JP
シーケンスはまたコレクションでもあるので、シーケンスについて
@code{fold}、@code{map}、@code{for-each}や他のジェネリック関数を
拡張することができます。しかし、時にはイテレーション中に要素そのものと
そのインデックスを知りたいことでしょう。そのためのジェネリック関数が
いくつかあります。
@c COMMON

@deffn {Method} fold-with-index kons knil (seq <sequence>) @dots{}
@c EN
Like generic @code{fold}, except @var{kons} is given
the index within @var{seq}, as the first argument,
as well as each element from @var{seq}s and the accrued value.
@c JP
ジェネリックな@code{fold}と似ていますが、@var{kons}には@var{seq}の
インデックス内から、第1引数として@var{seq}の要素と増加する値が渡る
点が異なります。
@c COMMON

@example
(fold-with-index acons '() '(a b c))
  @result{} ((2 . c) (1 . b) (0 . a))
@end example
@end deffn

@deffn {Method} map-with-index proc (seq <sequence>) @dots{}
@deffnx {Method} map-to-with-index class proc (seq <sequence>) @dots{}
@deffnx {Method} for-each-with-index proc (seq <sequence>) @dots{}
@c EN
Like @code{map}, @code{map-to} and @code{for-each}, except @var{proc}
receives the index as the first argument.
@c JP
@code{map}、@code{map-to}、@code{for-each}と似ていますが、@var{proc}が
第1引数としてインデックスを受け取る点が違います。
@c COMMON

@example
(map-with-index list '(a b c d) '(e f g h))
  @result{} ((0 a e) (1 b f) (2 c g) (3 d h))

(map-to-with-index <vector> cons '(a b c d))
  @result{} #((0 . a) (1 . b) (2 . c) (3 . d))
@end example
@end deffn

@deffn {Method} find-with-index pred (seq <sequence>)
@c EN
Finds the first element in @var{seq} that satisfies @var{pred}
like @code{find}, but returns two values, the index of the element
and the element itself.   If no element satisfies @var{pred},
two @code{#f}'s are returned.
@c JP
@code{find}のように、@var{seq}の中で@var{pred}を満足する最初の要素を
探しますが、2つの値、要素のインデックスと要素自身を返します。
@var{pred}を満足する要素がなかったら、2つの@code{#f}が返ります。
@c COMMON

@example
(find-with-index char-upper-case? "abraCadabra")
  @result{} 4 and #\C

(find-with-index char-numeric? "abraCadabra")
  @result{} #f and #f
@end example
@end deffn

@deffn {Method} find-index pred (seq <sequence>)
@c EN
Like @code{find}, but returns the index of the first element
that satisfies @var{pred} in @var{seq}, instead of the element itself.
If no element in @var{seq} satisfies @var{pred}, @code{#f} is returned.
@c JP
@code{find}に似ていますが、@var{seq}の中で@var{pred}を満足する最初の、
要素自身ではなくインデックスを返す点が異なります。
@var{seq}の中に@var{pred}を満足する要素がなかったら、@code{#f}が返ります。
@c COMMON

@example
(find-index char-upper-case? "abraCadabra")
  @result{} 4 

(find-index char-numeric? "abraCadabra")
  @result{} #f
@end example

@c EN
See also @code{list-index} in SRFI-1 (@xref{SRFI-1 Searching}).
@c JP
SRFI-1 (@ref{SRFI-1 Searching}参照)の@code{list-index}も見て下さい。
@c COMMON
@end deffn

@deffn {Method} fold-right kons knil (seq <sequence>) @dots{}
@c EN
Generalization of @code{fold-right} on lists.
Like @code{fold}, this method applies a higher-order function
@var{kons} over given sequence(s), passing the "seed" value
whose default is @var{knil}.  The difference between @code{fold}
and @code{fold-right} is the associative order of elements on
which @var{kons} is applied.

When we have one sequence, @code{[E0, E1, ..., En]}, @code{fold}
and @code{fold-right} work as follows, respectively.
@c JP
リストに対する@code{fold-right}の総称関数版です。
@code{fold}と同じように、このメソッドは種となる値 (初期値は@var{knil})
を受渡しながら、高階関数@var{kons}を与えられたシーケンスの各要素に
適用してゆきます。@code{fold}と@code{fold-right}の違いは
要素間の結合の順序にあります。

ひとつだけのシーケンス@code{[E0, E1, ..., En]}に適用する場合、
@code{fold}と@code{fold-right}はそれぞれ以下のように動作します。
@c COMMON

@example
fold:
  (kons En (kons En-1 (kons ... (kons E1 (kons E1 knil)) ...)))

fold-right
  (kons E0 (kons E1 (kons ... (kons En-1 (kons En knil)) ...)))
@end example

@c EN
This method isn't defined on @code{<collection>}, since
collections don't care the order of elements.
@c JP
このメソッドは@code{<collection>}に対しては提供されていません。
コレクションは要素の順序を規定しないからです。
@c COMMON
@end deffn


@node Other operations over sequences, Implementing sequence, Mapping over sequences, Sequence framework
@subsection Other operations over sequences
@c NODE その他のシーケンス上の操作

@subsubheading Selection and searching

@c EN
Note that selection and searching methods for collections 
can also be applied to sequences.
See @ref{Selection and searching in collection}.
@c JP
コレクションに対する選択と探索はシーケンスにも使えます。
@ref{Selection and searching in collection}を参照して下さい。
@c COMMON

@subsubheading Grouping

@deffn {Generic function} group-sequence seq :key key test
@c EN
Groups consecutive elements in a sequence @var{seq} which
have the common key value.  A key value of an element is
obtained by applying the procedure @var{key} to the element;
the default procedure is @code{identity}.
For each element in @var{seq}, @var{key} is applied exactly once.
The equal-ness of keys are compared by @var{test} procedure,
whose default is @code{eqv?}.
@c JP
シーケンス@var{seq}の連続する要素で、同じキー値を持つもの同士を
グループ化します。
キーの値は要素に手続き@var{key}を適用することで得られます。@var{key}の
デフォルト値は@code{identity}です。@var{sedq}の各要素に対して、
@var{key}は正確に一回だけ呼ばれます。
キーの等価性判定には手続き@var{test}が使われます。デフォルト値は@code{eqv?}です。
@c COMMON

@example
(group-sequence '(1 1 1 2 3 4 4 2 2 3 1 1 3))
  @result{} ((1 1 1) (2) (3) (4 4) (2 2) (3) (1 1) (3))

(group-sequence '(1 1 1 2 3 4 4 2 2 3 1 1 3) 
                :key (cut modulo <> 2)))
  @result{} ((1 1 1) (2) (3) (4 4 2 2) (3 1 1 3))

(group-sequence '#("a" "a" "b" "b" "c" "d" "d") 
                :test string=?)
  @result{} (("a" "a") ("b" "b") ("c") ("d" "d"))

(group-sequence "aabbcdd"
                :test char=?)
  @result{} ((#\a #\a) (#\b #\b) (#\c) (#\d #\d))
@end example

@c EN
This method is similar to Haskell's @code{group}.
If you want to group elements that are not adjacent, 
use @code{group-collection} 
(@xref{Selection and searching in collection}).
@c JP
このメソッドはHaskellの@code{group}と似ています。
隣り合っていない要素もグループ化したい場合は、
@code{group-collection} 
(@ref{Selection and searching in collection}参照)を使って下さい。
@c COMMON
@end deffn


@subsubheading Permutation and shuffling

@deffn {Generic function} permute (src <sequence>) (permuter <sequence>) :optional fallback
Returns a newly created sequence of the same type as @var{src}, in which
the elements are permuted from @var{src} according to @var{permuter}.

@var{Permuter} is a sequence of exact integers.  When the @var{k}-th element
of @var{permuter} is @var{i}, the @var{k}-th element of the result
is @code{(ref @var{src} @var{i})}.   Therefore, the size of the result
sequence is the same as the size of @var{permuter}.  @var{Permuter}
can be any kind of sequence, unrelated to the type of @var{src}.

It is allowed that the same index @var{i} can appear more than once
in @var{permuter}.

@example
(permute '(a b c d) '(3 2 0 1))     @result{} (d c a b)
(permute '(a b c d) '(0 2))         @result{} (a c)
(permute '(a b c d) '(0 0 1 1 2 2)) @result{} (a a b b c c)
@end example

If an integer in @var{permuter} is out of the valid range as the index
of @var{src}, then an error is signalled unless @var{fallback} is given.
If @var{fallback} is given, what value is used depends on the result of
@code{(ref @var{src} @var{i} @var{fallback})}---which usually returns
@var{fallback} for the out-of-range index @var{i}.

@example
(permute '#(a b c) '(3 2 1 0) 'foo) @result{} #(foo c b a)

(permute "!,HWdelor" #(2 5 6 6 7 1 -1 3 7 8 6 4 0) #\space)
  @result{} "Hello, World!"
@end example
@end deffn

@deffn {Generic function} permute-to (class <class>) (src <sequence>) (permuter <sequence>) :optional fallback
Like @code{permute}, but the result will be an instance of the given @var{class}
instead of the class of @var{src}.

@example
(permute-to <string> '(#\a #\b #\c #\d #\r)
            '(0 1 4 0 2 0 3 0 1 4 0))
  @result{} "abracadabra"
@end example
@end deffn

@deffn {Generic function} permute! (src <sequence>) (permuter <sequence>) :optional fallback
Also like @code{permute}, but the result is stored back to @var{src}.
@var{Src} must be a mutable sequence, and the length of @var{src} and
@var{permuter} must be the same.
@end deffn

@deffn {Generic function} shuffle (src <sequence>) :optional random-source
Returns a new sequence of the same type and size as @var{src},
in which elements are randomly permuted.

@example
(shuffle '(a b c d e))  @result{} (e b d c a)
(shuffle "abcde")       @result{} "bacde"
@end example

This generic function uses @code{srfi-27} (@xref{Sources of random bits}).
By default it uses @code{default-random-source}, but you can pass
an alternative random source by the optional argument.
@end deffn

@deffn {Generic function} shuffle-to (class <class>) (src <sequence>) :optional random-source
Like @code{shuffle}, except that the result will be an instance of 
@var{class} instead of the class of @var{src}.
@end deffn

@deffn {Generic function} shuffle! (src <sequence>) :optional random-source
Like @code{shuffle}, but the result is stored back to @var{src}.
@var{Src} must be a mutable sequence.
@end deffn


@node Implementing sequence,  , Other operations over sequences, Sequence framework
@subsection Implementing sequence
@c NODE シーケンスを実装する



@c ----------------------------------------------------------------------
@c @node Serializer, Terminal control, Simple dispatcher, Library modules
@c @section @code{gauche.serializer} - Serializer

@c @deftp {Module} gauche.serializer
@c @mdindex gauche.serializer
@c @end deftp

@c ----------------------------------------------------------------------
@node  Syslog, Terminal control, Sequence framework, Library modules - Gauche extensions
@section @code{gauche.syslog} - Syslog
@c NODE Syslog, @code{gauche.syslog} - Syslog

@deftp {Module} gauche.syslog
@mdindex gauche.syslog
@c EN
This module provides syslog(3) system logger interface.

For the common applications, you might find @code{gauche.logger} module
easier to use (@xref{User-level logging}).  This module is for those
who need direct access to the syslog API.

The procedures are only defined if the undelying system supports them.
@c JP
このモジュールは syslog(3) のシステムロガーのインタフェースを提供します。

一般的なアプリケーションについては、@code{gauche.logger} モジュールの
ほうが使いやすいでしょう(@ref{User-level logging}参照)。
このモジュールは syslog の API に直接アクセスする必要のある人向きです。

手続き群は基盤になっているシステムで syslog がサポートされている場合に
のみ定義されます。
@c COMMON
@end deftp

@defun sys-openlog ident option facility
[POSIX]
@c EN
Opens a connection to the system logger.  A string argument
@var{ident} is used for the prefix of the log, and usually is
the program name.  @var{Option} is an integer flag to control
the behavior of logging, and @var{facility} is an integer
that specify the type of the program.

The flag for @var{option} can be composed by @code{logior}-ing
one or more of the following integer constants:
@code{LOG_CONS}, @code{LOG_NDELAY}, @code{LOG_NOWAIT},
@code{LOG_ODELAY}, @code{LOG_PERROR} and @code{LOG_PID}.
(Some of the constants may not be defined if the underlying system
doesn't support them).

The @var{facility} argument can be one of the following integer
constants: @code{LOG_AUTH}, @code{LOG_AUTHPRIV}, @code{LOG_CRON},
@code{LOG_DAEMON}, @code{LOG_FTP}, @code{LOG_KERN}, @code{LOG_LOCAL0}
through @code{LOG_LOCAL7}, @code{LOG_LPR}, @code{LOG_MAIL}, @code{LOG_NEWS},
@code{LOG_SYSLOG}, @code{LOG_USER} and @code{LOG_UUCP}.
(Some of the constants may not be defined if the underlying system
doesn't support them).

See your system's manpage of openlog(3) for detail description about
these constants.
@c JP
システムロガーへのコネクションをオープンします。文字列の引数 @var{ident}
はログの接頭辞に使われます。通常はプログラムを名前にします。@var{option}
は整数のフラグで、ログの振舞いを制御します。@var{facility} はプログラムの
タイプを指定する整数です。

@var{option}のフラグは以下の整数定数の1つまたは複数を @code{logior} で
合成することができます：
@code{LOG_CONS}、@code{LOG_NDELAY}、@code{LOG_NOWAIT}、
@code{LOG_ODELAY}、@code{LOG_PERROR} および @code{LOG_PID} です
(これらの定数のいくつかは基盤となるシステムがサポートしていなければ
定義されません)。

@var{facility} 引数は以下の整数定数のどれかひとつです。
@code{LOG_AUTH}、@code{LOG_AUTHPRIV}、@code{LOG_CRON},
@code{LOG_DAEMON}、@code{LOG_FTP}、@code{LOG_KERN}、@code{LOG_LOCAL0}、
から @code{LOG_LOCAL7}、@code{LOG_LPR}、@code{LOG_MAIL}、@code{LOG_NEWS},
@code{LOG_SYSLOG}、@code{LOG_USER}、@code{LOG_UUCP} までです。
(これらの定数のいくつかは基盤となるシステムがサポートしていなければ
定義されません)。

これらの定数の詳しい説明については、システムの openlog(3) の
マニュアル・ページを見てください。
@c COMMO
@end defun

@defun sys-syslog priority message
[POSIX]
@c EN
Log the string @var{message}.  Unlike syslog(3), this procedure doesn't
do formatting---you can use @code{format} (@xref{Output}) to create
a formatted message, or use higher-level routine @code{log-format}
(@xref{User-level logging}).

An integer argument @var{priority} can be composed by @code{logior}-ing
one of the @var{facility} constants described above and
the @var{level} constants: @code{LOG_EMERG}, @code{LOG_ALERT},
@code{LOG_CRIT}, @code{LOG_ERR}, @code{LOG_WARNING}, @code{LOG_NOTICE},
@code{LOG_INFO}, @code{LOG_DEBUG}.
@c JP
文字列 @var{message} をログに記録します。syslog(3) とは違って、この手続きは
フォーマットを行いません。フォーマットされた文字列を生成するなら
@code{format} (@ref{Output}参照)が使えます。あるいは、より高水準の
ルーチン @code{log-format} (@ref{User-level logging}参照)
を使うこともできます。

整数の引数 @var{priority} は上述の @var{facility} 定数のどれかひとつ
と、以下の@var{level}定数と@code{logior}して、合成することができます：
@code{LOG_EMERG}、@code{LOG_ALERT}、@code{LOG_CRIT}、@code{LOG_ERR}、
@code{LOG_WARNING}、@code{LOG_NOTICE}、@code{LOG_INFO}、@code{LOG_DEBUG}
@c COMMON

@end defun

@defun sys-closelog
[POSIX]
@c EN
Closes the connection to the logging system.
@c JP
ロギングシステムとのコネクションをクローズします。
@c COMMON
@end defun

@defun sys-setlogmask mask
[POSIX]
@c EN
Sets the process's log priority mask that determines which calls to
@code{sys-syslog} may be logged.
An priority @var{mask} can be composed by @code{logior}-ing
bitmasks corresponding to the @var{level} argument of @code{sys-syslog}.
You can use @code{sys-logmask} below to obtain a bitmask
from the level.
@c JP
どの @code{sys-syslog}への呼び出しを記録できるかを決める、プロセスのログ
優先度マスクを設定します。
優先度マスク@var{mask}は@code{sys-syslog}の@var{level}引数に
対応するビットマスクを@code{logior}することで作成できます。
レベルに対応するビットマスクは下の@code{sys-logmask}から
取得することができます。
@c COMMON
@end defun

@defun sys-logmask level
[POSIX]
@c EN
Returns an integer bitmask for @code{sys-setlogmask} from 
the log level @var{level}.
@c JP
ログレベル @var{level} から @code{sys-setlogmask} に対する
ビットマスク整数を返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Terminal control, Unit testing, Syslog, Library modules - Gauche extensions
@section @code{gauche.termios} - Terminal control
@c NODE 端末の制御, @code{gauche.termios} - 端末の制御

@deftp {Module} gauche.termios
@mdindex gauche.termios
@c EN
This module provides procedures to control terminals.
On Unix platforms, the low-level API provides POSIX termios interface
as the module name suggests.  This module also provides
pseudo tty interface, if the system supports it.
@c JP
このモジュールは端末の制御のための手続きを提供します。
Unix環境では、低レベルAPIはモジュール名からわかるように
POSIX termiosへのインタフェースを提供しています。
さらに、このモジュールでは、システムがサポートしている場合には
擬似 tty のインタフェースも提供しています。
@c COMMON

@c EN
On Windows native platforms, POSIX termios interface is not
available.  It is too different from Windows console API to
provide a meaningful emulation.  The low-level Windows console
API is available in the @code{os.windows} module
(@xref{Windows support}).   You can still use high-level
terminal control procedures in this module.
@c JP
Windowsネイティブ環境ではPOSIX termiosインタフェースは使えません。
Windows console APIは大きく違っているので、意味のあるエミュレーションを
提供するのが難しいためです。低レベルのWindows console APIは
@code{os.windows}モジュールで使うことができます(@ref{Windows support}参照)。
ただし、このモジュールの高レベル端末制御手続きは、
Windowsネイティブ環境でも使うことができます。
@c COMMON
@end deftp

@menu
* Posix termios interface::     
* Common high-level terminal control::  
@end menu

@node Posix termios interface, Common high-level terminal control, Terminal control, Terminal control
@subsection Posix termios interface
@c NODE POSIX termiosインタフェース

@c EN
These procedures are available when the feature identifier
@code{gauche.os.windows} is @emph{not} defined.   See @code{cond-expand}
in @ref{Feature conditional} for how to switch code using
feature identifiers.
@c JP
ここに挙げる手続きは、機能シンボル@code{gauche.os.windows}が定義されて@emph{いない}
場合にのみ利用可能です。機能シンボルによってコードを切り替える方法は
@ref{Feature conditional}の@code{cond-expand}を参照してください。
@c COMMON

@deftp {Builtin Class} <sys-termios>
@clindex sys-termios
@c EN
POSIX termios(7) structure.
@c JP
POSIX termios(7) の構造体です。
@c COMMON

@defivar {<sys-termios>}  iflag
@end defivar
@defivar {<sys-termios>}  oflag
@end defivar
@defivar {<sys-termios>}  cflag
@end defivar
@defivar {<sys-termios>}  lflag
@end defivar
@defivar {<sys-termios>}  cc
@end defivar

@c EN
The slots @code{iflag}, @code{oflag}, @code{cflag} and @code{lflag}
contains non-negative integers representing bitmasks.

The slot @code{cc} contains a @emph{copy} of @code{c_cc} array
of @code{struct termios}, as an u8vector (see @ref{Uniform vectors}
for the details about u8vector).
Since @code{cc} slot is a copy of the internal structure, you have
to @code{set!} an u8vector to the slot explicitly to make
changes to the @code{c_cc} array.
@c JP
@code{iflag}、@code{oflag}、@code{cflag}、@code{lflag}の各スロットは、
対応するビットマスクを非負の整数で表現した値を保持しています。

また、@code{cc}スロットは@code{struct termios}の@code{c_cc}配列の
@emph{コピー}を返します。
@code{c_cc}配列の値を変えたい場合は、変更したu8vectorを明示的に
@code{cc}スロットに@code{set!}して下さい。
@c COMMON

@end deftp

@c EN
Throughout this section, argument @var{port-or-fd} refers to
either a port object or a small integer representing system's file 
descriptor.  If @var{port} is not associated
to the system terminal, an error is signalled.  (You can check if @var{port}
has an associated terminal by @code{sys-isatty?}.
@xref{Other file operations}).
@c JP
このセクションを通じて、引数 @var{port-or-fd} はポートオブジェクトか
システムのファイルディスクリプタを表現する小さい整数かのどちらかです。
@var{port}がシステム端末に結びついていないければ、エラーになります。
(@code{sys-isatty?}を使えば@var{port}が端末と結びついているか
どうかチェックできます。 @ref{Other file operations}参照)
@c COMMON

@defun sys-tcgetattr port-or-fd
@c EN
Returns terminal parameters in a @code{<sys-termios>} object,
associated to @var{port-or-fd}.
@c JP
@var{port-or-fd} と結びついている @code{<sys-termios>}オブジェクトの
端末パラメータを返します。
@c COMMON
@end defun

@defun sys-tcsetattr port-or-fd when termios
@c EN
Sets terminal parameters associated to @var{port-or-fd} by @var{termios},
which must be an instance of @code{<sys-termios>}.

An integer argument @var{when} specifies when the changes take effect.
Three variables are pre-defined for the argument:
@c JP
@var{port-or-fd}と結びついている端末のパラメータを @var{termios} に設定します。
@var{termios} は @code{<sys-termios>} のインスタンスでなければなりません。

整数の引数@var{when}はいつ変更を有効にするかを指定します。
この引数用に3つの変数があらかじめ定義されています。
@c COMMON
@table @code
@item TCSANOW
@vindex TCSANOW 
@c EN
The change is reflected immediately.
@c JP
変更を直ちに反映します。
@c COMMON
@item TCSADRAIN
@vindex TCSADRAIN
@c EN
The change is reflected after all pending output is flushed.
@c JP
変更を、すべてのペンディングになっている出力がフラッシュされた後に反映します。
@c COMMON
@item TCSAFLUSH
@vindex TCSAFLUSH
@c EN
The change is reflected after all pending output is flushed,
and all pending input is discarded.
@c JP
変更を、すべてのペンディングになっている出力がフラッシュされ、かつ、
すべてのペンディングになっている入力が破棄されたあとに反映します。
@c COMMON
@end table
@end defun

@defun sys-tcsendbreak port-or-fd duration
@c EN
Transmits a zero stream for the specified duration
to the terminal associated to @var{port-or-fd}.
The unit of duration depends on the system; see man tcsendbreak(3) of
your system for details.
@c JP
ゼロストリームを指定した時間、@var{port-or-fd}と結びついている端末に
送出します。時間の単位はシステム依存です。詳しくは、お使いの
システムのマニュアルページ tcsendbreak(3)を参照してください。
@c COMMON
@end defun

@defun sys-tcdrain port-or-fd
@c EN
Waits until all output written to @var{port-or-fd} is transmitted.
@c JP
@var{port-or-fd}へのすべての出力が送出されるまで待ちます。
@c COMMON
@end defun

@defun sys-tcflush port-or-fd queue
@c EN
Discards data in the buffer of @var{port-or-fd}, specified by 
@var{queue}, which may be one of the following values.
@c JP
@var{port-or-fd}のバッファ内のデータを破棄します。@var{queue}には以下の値の
どれかを指定します。
@c COMMON
@table @code
@item TCIFLUSH
@vindex TCIFLUSH
@c EN
Discards data received but not read.
@c JP
受信データしたが読み込んではいないデータを破棄します。
@c COMMON
@item TCOFLUSH
@vindex TCOFLUSH
@c EN
Discards data written but not transmitted.
@c JP
書き出したが送出していないデータを破棄します。
@c COMMON
@item TCIOFLUSH
@vindex TCIOFLUSH
@c EN
Do both @code{TCIFLUSH} and @code{TCOFLUSH} action.
@c JP
@code{TCIFLUSH} と @code{TCOFLUSH} の両方の動作をします。
@c COMMON
@end table
@end defun

@defun sys-tcflow port-or-fd action
@c EN
Controls data flow of @var{port-or-fd} by @var{action}, which may be
one of the following values:
@c JP
@var{port-or-fd}のデータフローを@var{action}で制御します。@var{action}は
以下の値のうちどれかです。
@c COMMON
@table @code
@item TCOOFF
@vindex TCOOFF
@c EN
Suspends output transmission.
@c JP
出力の送出をサスペンドします。
@c COMMON
@item TCOON
@vindex TCOON
@c EN
Restarts output transmission.
@c JP
出力の送出を再開します。
@c COMMON
@item TCIOFF
@vindex TCIOFF
@c EN
Transmits a STOP character to make the terminal device stop transmitting
data to the system.
@c JP
端末デバイスがシステムへの送出を止めるよう STOP 文字を送出する。
@c COMMON
@item TCION
@vindex TCION
@c EN
Transmits a START character to make the terminal device resume transmitting
data to the system.
@c JP
端末デバイスがシステムへの送出を再開するよう START 文字を送出する。
@c COMMON
@end table
@end defun

@defun sys-tcgetpgrp port-or-fd
@c EN
Returns process group ID of the terminal associated to @var{port-or-fd}.
@c JP
@var{port-or-fd}の結びついている端末のプロセスのグループIDを返します。
@c COMMON
@end defun

@defun sys-tcsetpgrp port-or-fd pgrp
@c EN
Sets process group ID of the terminal associated to @var{port-or-fd}
to @var{pgrp}.
@c JP
@var{port-or-fd}の結びついている端末のプロセスのグループIDを@var{pgrp}に
設定します。
@c COMMON
@end defun

@defun sys-cfgetispeed termios
@defunx sys-cfsetispeed termios speed
@defunx sys-cfgetospeed termios
@defunx sys-cfsetospeed termios speed
@c EN
Gets/sets input/output speed (baud rate) parameter stored in @var{termios}
object.   Speed is represented by the following predefined numbers:
@code{B0}, @code{B50}, @code{B75}, @code{B110}, @code{B134}, 
@code{B150}, @code{B200}, @code{B300}, @code{B600}, @code{B1200}, 
@code{B1800}, @code{B2400}, @code{B4800}, @code{B9600},
@code{B19200}, @code{B38400}.
@c JP
@var{termios}内の入出力スピード(ボーレート)を取得/設定します。スピードは
以下の定義ずみの数値で表現されてます：
@code{B0}、@code{B50}、@code{B75}、@code{B110}、@code{B134}、
@code{B150}、@code{B200}、@code{B300}、@code{B600}、@code{B1200}、
@code{B1800}、@code{B2400}、@code{B4800}、@code{B9600}、
@code{B19200}、@code{B38400}。
@c COMMON

@c EN
Some system may support higher baud rate, such as @code{B57600},
@code{B115200} or @code{B230400}.  You can use @code{symbol-bound?}
to check these options are defined.  @code{B0} is used to
terminate the connection.
@c JP
もっと速いボーレート、たとえば、@code{B57600}、
@code{B115200} あるいは @code{B230400} をサポートしている
システムもあります。@code{symbol-bound?}をつかえば、これらの
オプションが定義されているかどうかをチェックできます。@code{B0}
はコネクションを終了するのに使われます。
@c COMMON
@end defun

@defun sys-openpty :optional term
@c EN
Opens a pair of pseudo ttys, one for master and the other for slave,
then returns two integers which are their file descriptors.
An optional argument @var{term} must be, if passed, a @code{<sys-termios>}
object; it sets the slave pty's parameters.

You can use @code{open-input-fd-port} and/or @code{open-output-fd-port}
to create a port around the returned file descriptor (@xref{File ports}).
To obtain pseudo tty's name, use @code{sys-ttyname}
(@xref{Other file operations}).

This function is available only if the system supports @code{openpty(3)}.
@c JP
擬似 tty のペア、マスターとスレーブをオープンし、2つの
ファイルディスクリプタの整数を返します。オプション引数 @var{term} 
が渡される場合は、@code{<sys-termios>}オブジェクトでなければなりません。
これは、pty パラメータを設定します。

@code{open-input-fd-port}と@code{open-output-fd-port}の両方またはどちらか
を返されたファイルディスクリプタに対するポートを生成するために使うことが
できます(@ref{File ports}参照)。擬似端末の名前を得るには @code{sys-ttyname}
を使います(@ref{Other file operations}参照)。

この関数はシステムが @code{openpty(3)} をサポートしている場合にのみ利用
可能です。
@c COMMON
@end defun

@defun sys-forkpty :optional term
@c EN
Opens a pair of pseudo ttys, one for master and the other for slave,
sets the slave pty suitable for login terminal, then fork(2).

Returns two integers; the first value is a child pid for the parent process,
and 0 for the child process.  The second value is a file descriptor
of the master pty.

An optional argument @var{term} must be, if passed, a @code{<sys-termios>}
object; it sets the slave pty's parameters.

This function is available only if the system supports @code{forkpty(3)}.
@c JP
擬似 ttyのペア、マスターとスレーブをオープンし、スレーブ sty を
ログイン端末になるよう設定し、fork(2) します。

二つの整数、最初の値は親プロセスに対しては子の pid の値で、0ならば
子プロセスです。ふたつ目の値はマスター pty のファイルディスクリプタの
値です。

オプション引数 @var{term}が渡される場合は、それは@code{<sys-termios>}オブジェクト
でなければなりません。これはスレーブ pty のパラメータを設定します。

この関数はシステムが @code{forkpty(3)} をサポートしている場合にのみ利用
可能です。
@c COMMON

@c EN
Note: @code{sys-forkpty} has the same MT hazard as @code{sys-fork}
(see @ref{Process management}, for details).  If you're
running multiple threads, use @code{sys-forkpty-and-exec} below.
@c JP
注意: @code{sys-forkpty}には@code{sys-fork}と同様のマルチスレッドハザー
ドの危険性があります。(詳細については@ref{Process management}参照
してください)。マルチスレッドプログラムでは後述の
@code{sys-forkpty-and-exec}を利用してください。
@c COMMON
@end defun

@defun sys-forkpty-and-exec command args :key iomap term sigmask
@c EN
Does @code{sys-forkpty}, and lets the child process
immediately @code{exec}s the specified @var{command}
with arguments @var{args}.   This function doesn't have
the hazard in multi-thread environment.
@c JP
@code{sys-forkpty}して、ただちに指定した@var{command}を引数
@var{args}で子プロセスで@code{exec}します。この関数にはマルチスレッド
環境でもハザードを起こしません。
@c COMMON

@c EN
The meanings of arguments @var{command}, @var{args}, @var{iomap} and
@var{sigmask}
are the same as @code{sys-exec} (see @ref{Process management}).
If the keyword argument @var{term} is given, it is used to initialize
the slave pty.
@c JP
引数@var{command}、@var{args}、@var{iomap}、@var{sigmask}の意味は
@code{sys-exec}のものと同じです。(@ref{Process management}を見て
ください)。キーワード引数@var{term}が与えられれば、スレーブptyの初期化
に使われます。
@c COMMON
@end defun

@node Common high-level terminal control,  , Posix termios interface, Terminal control
@subsection Common high-level terminal control
@c NODE 共通の高レベル端末制御

Currently we only have one high-level API.  We may add more as needed.

@defun without-echoing iport proc
If @var{iport} is an input port connected to a terminal, 
sets the terminal mode non-echoing and call @var{proc} with
@var{iport} as an argument.  Before returning from
@code{without-echoing}, or throwing an error,
the terminal mode is reset to the original state when this
procedure is called.  The procedure returns whatever value(s)
@var{proc} returns.

You can also pass @code{#f} to @var{iport}.  In that case,
this procedure tries to open a console (@code{/dev/tty} on Unix,
@code{CON} on Windows) and set the console mode, then calls
@var{proc} with the opened input port.  An error is thrown
if the procedure can not open a console.

If @var{iport} is other than above, this procedure
simply calls @var{proc} with @var{iport}.  This allows
the caller to read password from redirected input, 
for example.

Note: Because of an implementation issue, on Windows native
platforms this procedure always changes console mode
of the standard input handle when @code{iport} is either
@code{#f} or a terminal input port.
@end defun


@c ----------------------------------------------------------------------
@node Unit testing, Threads, Terminal control, Library modules - Gauche extensions
@section @code{gauche.test} - Unit Testing
@c NODE 単体テスト, @code{gauche.test} - 単体テスト

@deftp {Module} gauche.test
@mdindex gauche.test
@c EN
Defines a set of functions to write test scripts.
A test script will look like this:
@c JP
テストスクリプトを書くための手続きを提供します。
テストスクリプトは次のような形になります。
@c COMMON

@lisp
(use gauche.test)
(test-start "my feature")
@c EN
(load "my-feature")  ; @r{load your program}
(import my-feature)  ; @r{if your program defines a module.}

(test-module 'my-feature) ; @r{tests consistency in your module.}
@c JP
(load "my-feature")  ; @r{テストすべきプログラムをロード}
(import my-feature)  ; @r{モジュールを定義している場合はインポート}

(test-module 'my-feature) ; @r{モジュールの一貫性チェック}
@c COMMON

(test-section "feature group 1")
(test "feature 1-1" EXPECT (lambda () TEST-BODY))
(test "feature 1-2" EXPECT (lambda () TEST-BODY))
 @dots{}

(test-section "feature group 2")
(define test-data ...)
(test "feature 2-1" EXPECT (lambda () TEST-BODY))
(test "feature 2-2" (test-error) (lambda () TEST-THAT-SIGNALS-ERROR))
 @dots{}

(test-end)
@end lisp

@c EN
With this convention, you can run test both interactively or
in batch.   To run a test interactively, just load the file
and it reports a result of each test, as well as the summary
of failed test at the end.  To run a test in batch, it is
convenient to redirect the stdout to some file
If stdout is redirected to other than tty, all the verbose logs will go
there, and only a small amount of messages go to stderr.
@c JP
このテストスクリプトは、バッチ処理でもインタラクティブセッションからでも
実行できます。インタラクティブセッションの場合はこのテストスクリプトを
ただロードすれば、各テストの結果とサマリーが報告されます。
バッチテストの場合は、標準出力を別のファイルにリダイレクトしておくと良いでしょう。
標準出力が端末でない場合、テスト手続きは詳しい結果をstdoutに出力し、簡単な
メッセージを標準エラー出力に書き出します。
@c COMMON

@c EN
It is recommended to have a "check" target always in Makefile
of your module/program, so that the user of your program can run a
test easily.  The rule may look like this:
@c JP
モジュールやプログラムを書いたら、Makefileに"check"ターゲットを作ることを
お薦めします。ルールはこんな感じになるでしょう：
@c COMMON

@example
check :
        gosh my-feature-test.scm > test.log
@end example
@end deftp

@c EN
@subheading Structuring a test file
@c JP
@subheading テストファイルの構造
@c COMMON

@defun test-start module-name
@c EN
Initializes internal state and prints a log header.
This should be called before any tests.
@var{Module-name} is used only for logging purpose.
@c JP
テストの状態を初期化して、ヘッダをログに書き出します。テストを呼ぶ前に呼んで下さい。
@var{module-name}はログのために使われる文字列です。
@c COMMON
@end defun

@defun test-section section-name
@c EN
Marks beginning of the group of tests.  This is just for logging.
@c JP
一群のテストの開始をマークします。単にログに使われるだけです。
@c COMMON
@end defun

@defun test-end
@c EN
Prints out list of failed tests, and returns the number of failed tests.
@c JP
失敗したテストのリストを報告し、その総数を返します。
@c COMMON
@end defun

@defun test-record-file file
@c EN
Suppose you have several test scripts.  Normally you run them
as a group and what you want to know is a concise summary of
the whole results, instead of each result of individual test files.

A @emph{test record file} is an auxiliary file used to
gather summary of the result.   It holds a one-line summary
of tests like this:
@c JP
テストスクリプトがいくつかある場合を考えます。通常は、それらのテストスクリプト
をひとつづつ走らせて結果を確かめるのではなく、全部を一気に走らせて
簡単な結果のまとめだけを知りたいと思うでしょう。

@emph{test record file}はテスト結果を集積するための補助ファイルです。
その内容は次のような一行のサマリになっています。
@c COMMON

@example
Total:  9939 tests,  9939 passed,     0 failed,     0 aborted.
@end example

@c EN
When a test record file exists,
@code{test-start} reads and parses it, and remembers the numbers.
Then @code{test-end} adds the count of the results and
writes them back to the same test record file.
@c JP
test record fileが既に存在していると、@code{test-start}は
それを読みこんで数字を覚えておきます。そして@code{test-end}が
そのスクリプト中のテスト結果の数字を加算して、同じtest record fileに書き戻します。
@c COMMON

@c EN
If you writes the @code{check} target in your makefile as follows,
you will get the final one-line summary every time you run
@code{make check}, assuming that @file{test1.scm}, @file{test2.scm}, 
and @file{test3.scm} all has @code{(test-record-file "test.record")}
before a call to @code{test-start}.
@c JP
makefileの@code{check}ターゲットを次のように書いておけば、
@code{make check}を実行するたびにテスト結果の一行サマリを
得ることができます。
ただし、@file{test1.scm}、@file{test2.scm}、@file{test3.scm}はいずれも
@code{test-start}呼び出し前に@code{(test-record-file "test.record")}を
評価しているものとします。
@c COMMON

@example
check:
        @@rm -f test.record test.log
        gosh test1.scm >> test.log
        gosh test2.scm >> test.log
        gosh test3.scm >> test.log
        @@cat test.record
@end example

@c EN
Note that to make @code{test-record-file} work, it must be placed
before the call to @code{test-start}.

Alternatively, you can use the envionment variable
@code{GAUCHE_TEST_RECORD_FILE} to specify the test record file.
@c JP
@code{test-record-file}手続きがうまく動作するためには、それが
@code{test-start}より前に呼ばれなければならないことに注意してください。

この手続きのかわりに、環境変数@code{GAUCHE_TEST_RECORD_FILE}を使って
test record fileを指定することもできます。
@c COMMON
@end defun

@deftp {Environment Variable} GAUCHE_TEST_RECORD_FILE
@c EN
If this environment varaible is set when the test script is run,
its value is used as the name of the test record file.

If the test script calls @code{test-record-file}, it takes precedence
and this environment variable is ignored.
@c JP
テストスクリプトが走る時にこの環境変数が指定されていれば、
その値がtest record fileの名前として使われます。

ただしテストスクリプト中に@code{test-record-file}の呼び出しがあると
そちらが優先され、この環境変数は無視されます。
@c COMMON
@end deftp

@c EN
@subheading Individual tests
@c JP
@subheading 個々のテスト
@c COMMON

@defmac test* name expected expr :optional check
@c EN
A convenience macro that wraps @var{expr} by lambda.
@c JP
@var{expr}をlambdaでくるんでくれる便利なマクロです。
@c COMMON

@example
(test* name expected expr)
  @equiv{} (test name expected (lambda () expr))
@end example
@end defmac

@defun test name expected thunk :optional check
@c EN
Calls @var{thunk}, and checks its result fits @var{expected}
using a procedure @var{check}, which
is called as follows:
@example
(@var{check} @var{expected} @var{result-of-thunk})
@end example
It should return @code{#t} if the given result agrees with the 
expected value, or @code{#f} otherwise.
The default check procedure is @code{test-check}, explained
below.  It compares @var{expected} and @var{result-of-thunk}
with @code{equal?}, except when @var{expected} is some
of special case test objects.  (See ``testing ambiguous results''
and ``testing abnormal cases''
paragraphs below for this special treatment.)

One typical usage of the custom check
procedure is to compare inexact numbers tolerating small error.
@c JP
@var{thunk}を呼び、その結果が@var{expected}に沿っているかを
@var{check}を次のとおり呼び出すことで確認します。
@example
(@var{check} @var{expected} @var{result-of-thunk})
@end example
この手続きは、渡された結果が期待する値と合致する場合に@code{#t}を、
そうでなければ@code{#f}を返さなければなりません。
デフォルトの@var{check}手続きは下で述べる@code{test-check}です。
これは、@var{expected}がいくつかの特殊なテストオブジェクトである場合をのぞき、
@var{expected}と@var{result-of-thunk}が@code{equal?}
である場合に@code{#t}を返します。すなわち、通常はテスト式の結果が
期待するものと@code{equal?}であればテストは成功である、ということです。
(特別な場合については下の ``曖昧な結果をテストする'' および
``異常系をテストする'' の項を見てください)。

特別な比較手続きのひとつの用法は、不正確な数値を、多少の誤差を許して
比較するような場合です。
@c COMMON

@example
(test "test 1" (/ 3.141592653589 4)
      (lambda () (atan 1))
      (lambda (expected result)
        (< (abs (- expected result)) 1.0e-10)))
@end example

@c EN
@var{Name} is a name of the test, for the logging purpose.
@c JP
@var{name}はログに残すためのテストの名前です。
@c COMMON

@c EN
When @var{thunk} signals an uncaptured error, it is catched and
yields a special error object @code{<test-error>}.
You can check it with another error object created by
@code{test-error} function to see if it is an expected type
of error.  See the entry of @code{test-error} below for the details.
@c JP
@var{thunk}内で捕捉されないエラーが発生した場合、それは捕捉され、
特別なエラーオブジェクト@code{<test-error>}に置き換えられます。
その結果を、下で説明する@code{test-error}手続きで作った@code{<test-error>}
オブジェクトと比較することにより、エラーが期待されたものであるか、
また適切な例外が上がっているかをテストすることができます。
@c COMMON
@end defun

@defun test-check expected result :optional fallback
@c EN
The default procedure @code{test} and @code{test*} use
to check the result of the test expression conforms the
expected value.  By default, @code{test-check} just compares
@var{expected} and @var{result} with a procedure @var{fallback},
which is defaulted to @code{equal?}.   @code{test-check} behaves
differently if @var{expected} is one of special test objects
described below.
@c JP
テスト式の結果が期待された値に合致していることをチェックするために
@code{test}と@code{test*}が使うデフォルトの手続きです。
基本的に、@code{test-check}は@var{expected}と@var{result}を
@var{fallback}に渡された手続きで比較するだけです。@var{fallback}の
デフォルト値は@code{equal?}です。
ただし、以下に述べるとおり、@var{expected}が特殊なテストオブジェクト
だった場合には特別な振る舞いをします。
@c COMMON
@end defun

@c EN
@subheading Testing ambiguous results
@c JP
@subheading 曖昧な結果をテストする
@c COMMON

@defun test-one-of choice @dots{}
@c EN
Sometimes the result of test expression depends on various
external environment, and you cannot put an exact expected value.
This procedure supports to write such tests conveniently.
@c JP
時々、テスト式@var{expr}の結果が外部の環境に左右されるため、
ひとつの確定した値を期待値@code{expected}として書いておけない場合があります。
この手続きはそのようなテストを簡単に書けるようにします。
@c COMMON

@c EN
Returns a special object represents @emph{either one of choices}.
The default check procedure, @code{test-check}, recognizes the object
when it is passed in the @var{expected} argument, and returns true
if any one of @var{choice} @dots{} passes the check against the result.

For example, the following test passes if @code{proc} returns either
1 or 2.
@c JP
@emph{@var{choice} @dots{} のいずれか} を表現する特別なオブジェクトを返します。
デフォルトの検査手続きである@code{test-check}は、@var{expected}引数に
そのオブジェクトが渡ってきた場合には、テスト結果と@var{choice} @dots{}を
ひとつづつ照合し、どれかがマッチすれば真を返します。

例えば次のテストは、@code{proc}が1か2を返せば成功となります。
@c COMMON

@example
(test* "proc returns either 1 or 2" (test-one-of 1 2) (proc))
@end example
@end defun

@c EN
@subheading Testing abnormal cases
@c JP
@subheading 異常系をテストする
@c COMMON

@defun test-error :optional (condition-type <error>)
@c EN
Returns a new @code{<test-error>} object that mathes with
other @code{<test-error>} object with the given @var{condition-type}.
@c JP
与えられた@var{condition-type}と適合する@code{<test-error>}オブジェクト
とマッチするような、新たな@code{<test-error>}オブジェクトを作成して返します。
@c COMMON

@c EN
The @code{test-check} procedure treats @code{<test-error>} objects
specially.  When @code{err-expected} and @code{err-actual}
are @code{<test-error>} objects,
@code{(test-check err-expected err-actual)} returns @code{#t}
if @code{err-expected}'s
condition type is the same as or supertype of @code{err-actual}'s.
@c JP
テスト結果をチェックする@code{test-check}手続きは@code{<test-error>}オブジェクトを
特別に扱います。@code{err-expected}と@code{err-actual}が
ともに@code{<test-error>}のインスタンスであるとき、
@code{(test-check err-expected err-actual)}は
@code{err-expected}の持つcondition typeが@code{err-actual}の
それと同じであるか、スーパータイプである場合に@code{#t}を返します。
@c COMMON

@c EN
For example, if you want to test a call to @code{foo} raises
an @code{<io-error>} (or its condition subtype), you can write
as the following example:
@c JP
例えば@code{foo}の呼び出しが@code{<io-error>} (もしくはそのサブタイプ) の
コンディションを投げるかどうかをテストしたければ、次のように書くことができます。
@c COMMON

@example
(test "see if foo raises <io-error>" (test-error <io-error>) (foo))
@end example
@end defun

@defvar *test-error*
@c EN
(Deprecated) Bounded to an instance of @code{<test-error>} with
condition type @code{<error>}.  This is only provided for the
backward compatibility; new code should use @code{test-error}
procedure above.
@c JP
(非推奨) condition typeとして@code{<error>}を持つ@code{<test-error>}
オブジェクトに束縛されています。この変数は互換性のためにのみ残されています。
新しいコードは上に述べた@code{test-error}手続きを使ってください。
@c COMMON
@end defvar

@defvar *test-report-error*
@c EN
If this variable is true, the @code{test} routine prints stack trace
to the current error port when it captures an error.  It is useful
when you got an unexpected test-error object and want to check out
where the error is occurring.

This variable is initialized by the environment variable
@code{GAUCHE_TEST_REPORT_ERROR} when the @code{gauche.test} module
is loaded.  For example, you can use the environment variable to check out
an unexpected error from your test script as follows (the value
of the environment variable doesn't matter).
@c JP
この変数が真であれば、@code{test}ルーチンはエラーを捕捉した際に
スタックトレースをカレントエラーポートに出力します。
期待しない状況でtest-errorオブジェクトが返された際に、そのエラーが
どこで起こったかを知るのに役立つでしょう。

この変数は@code{gauche.test}モジュールが読み込まれた時点で
環境変数@code{GAUCHE_TEST_REPORT_ERROR}の値により初期化されます。
例えば、テストスクリプト中の予期せぬエラーを調べるのに、
次のようにすることができるでしょう (環境変数がセットされていれば、値は関係ありません)。
@c COMMON

@example
env GAUCHE_TEST_REPORT_ERROR=1 gosh mytest.scm
@end example
@end defvar

@c EN
@subheading Testing modules
@c JP
@subheading モジュールのテスト
@c COMMON

@defun test-module module :key allow-undefined
@c EN
@var{Module} must be a symbol module name or a module.
This procedure performs some heuristic consistency check of
the given module: (1) whether symbols set as autoload
in @var{module} can actually be loaded, (2) whether
the symbols declared in export list is actually defined
in the module, and (3) whether the global variable referenced
within functions are all defined.   Although not perfect, 
this test can catch some careless typo in symbol names.
@c JP
@var{Module}はモジュール名のシンボルかモジュールでなければなりません。
この手続きはモジュール@var{module}に関していくつかの経験的な一貫性チェックを
行います：(1) autoloadに設定されたシンボルがちゃんとロードできるか、
(2) exportにリストされたシンボルがモジュール内で定義されているか、
(3) 関数中で参照されているグローバル変数が全て定義されたものであるか。
この手続きは完璧ではないものの、
ケアレスミスによる名前の綴り間違いを発見することができます。
@c COMMON

@c EN
Sometimes you have a global vaiable that may not be
defined depending on compiler options or platforms, and
you check its existence at runtime before using it.
The undefined variable reference check by @code{test-module}
doesn't follow such logic, and reports an error whenever
it finds your code referring to undefined variable.  In such case,
you can give a list of symbols to the @var{allow-undefined}
keyword argument; the test will excludes them from the check.
@c JP
しばしば、プラットフォームやコンパイルオプションによって
グローバル変数が定義されるかどうかが異なる場合があります。
コード中では実行時にその変数の存在を確認してから使うように
コーディングしてあったとしても、@code{test-module}は
そのようなロジックを追わないため、未定義変数の参照を報告して
しまいます。そのような場合は、チェックから外す変数名のリストを
@var{allow-undefined}キーワード引数に渡して下さい。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Threads, Measure timings, Unit testing, Library modules - Gauche extensions
@section @code{gauche.threads} - Threads
@c NODE スレッド, @code{gauche.threads} - スレッド

@c EN
If enabled at compilation time, Gauche can use threads
built on top of POSIX threads (pthreads).
@c JP
Gaucheでは、コンパイル時に有効にしていれば、POSIXスレッド(pthreads)の
上に構築されるスレッドを使うことができます。
@c COMMON

@deftp {Module} gauche.threads
@mdindex gauche.threads
@c EN
Provides thread API.   You can 'use' this module regardless
whether the thread support is compiled in or not; if threads are not
supported, many thread-related procedures simply signals a 
"not supported" error.
@c JP
スレッドを扱うAPIを提供します。コンパイル時にスレッドのサポートを
指定したか否かに関わらず、このモジュールを'use'することができます。
スレッドがサポートされていない場合は、多くのスレッド関連の手続きは
単に``not supported''エラーを通知するだけです。
@c COMMON
@end deftp

@c EN
If you want to switch code depending on whether pthreads are
available or not, you can use a feature identifier @code{gauche.sys.pthreads}
with @code{cond-expand} form (@xref{Feature conditional}).

@example
(cond-expand
 [gauche.sys.pthreads
   ;; Code that uses thread API (@code{gauche.threads} is automatically
   ;; loaded at this moment).
  ]
 [else
   ;; Code that doesn't use thread API
  ])
@end example
@c JP
pthreadが使えるかどうかによって実行するコードを切り替えたい場合は、
@code{cond-expand}フォームで@code{gauche.sys.pthreads}という
feature identifierを使うことができます (@ref{Feature conditional}参照)。

@example
(cond-expand
 [gauche.sys.pthreads
   ;; Thread APIを使うコード (@code{gauche.threads}はこの時点で
   ;; 自動的にロードされます).
  ]
 [else
   ;; Thread APIを使わないコード
  ])
@end example
@c COMMON

@c EN
To check if threads are available at runtime,
instead of compile time, use the following procedure.
@c JP
コンパイル時ではなく実行時にスレッドが有効かどうかをチェックするためには、
次の手続きを使います。
@c COMMON

@defun gauche-thread-type
@c EN
Returns a symbol that indicates the supported thread type.
In the current version, the return value may be @code{pthread}
when threads on top of POSIX threads are available, or
@code{none} when threads are not available.
@c JP
サポートされているスレッドのタイプを表すシンボルを返します。
現在のバージョンでは、POSIXスレッドの上に構築されるスレッドが
有効な場合は@code{pthread}を返し、スレッドが有効でない場合は
@code{none}を返します。
@c COMMON
@end defun

@c EN
Scheme-level thread API conforms SRFI-18, "Multithreading support"
(@ref{srfi-18,,[SRFI-18]}), wrapped around Gauche's object interface.
@c JP
SchemeレベルのスレッドAPIはSRFI-18、``マルチスレッドサポート''
(@ref{srfi-18,,[SRFI-18]})を満たし、Gaucheのオブジェクトの
インターフェースでラップされます。
@c COMMON

@menu
* Thread programming tips::     
* Thread procedures::           
* Synchronization primitives::  
* Thread exceptions::           
@end menu

@node Thread programming tips, Thread procedures, Threads, Threads
@subsection Thread programming tips
@c NODE スレッドプログラミングTips

@c EN
Although the surface API of threads looks simple and portable,
you need to know how the threads are implemented in order to utilize
the feature's potential.   Some languages support threads as
language's built-in construct and encourage programmers
to express the calculation in terms of threads.
However, it should be noted that in many cases there are
alternative ways than threads to implement the desired
algorithm, and you need to compare advantages and
disadvantages of using threads depending on how the threads
are realized in the underlying system.
@c JP
スレッドのAPIは外見上シンプルでポータブルに見えますが、
その機能の潜在的な力を活用するためには、スレッドがどのように
実装されているかを知る必要があります。
いくつかの言語では言語組み込みの機能としてスレッドをサポートし、
プログラマによるスレッドの利用を推奨しています。
しかし、多くの場合、実現したいアルゴリズムをスレッドを使わずに
実装する方法があります。
スレッドを使うことの利点と欠点を、そのスレッドがシステムによってどのように
実現されているかを考慮した上で比較する必要があります。
@c COMMON

@c EN
In Gauche, the primary purpose of threads is to write programs
that @emph{require} preemptive scheduling, therefore are
difficult to express in other ways.  Preemptive threads may
be required, for example, when you have to call a module that 
does blocking I/O which you can't intercept, or may spend
nondeterministic amount of calculation time that you want
to interrupt.
@c JP
Gaucheでは、スレッドを使う一番の目的は、他の方法で表現することが
難しい、プリエンプティブなスケジューリングを@emph{必要}とする
プログラムを書くことです。プリエンプティブなスレッドは、
例えば、中断できないブロッキングI/Oを行うモジュールを
使わなければならないときや、実行時間の分からない計算に
割り込みを行いたいときなどに必要となります。
@c COMMON

@c EN
For each Gauche's thread, an individual VM is allocated
and it is run by the dedicated POSIX thread.  Thus there
is not much overhead in context switch than the native
thread, but the creation of threads costs much higher than,
say, lightweight threads built on top of call/cc.
So Gauche's preemptive threads are @emph{not} designed for
applications that want to create thousands of threads
for fine-grained calculation.
@c JP
それぞれのGaucheのスレッドには、個別の仮想マシンが割り当てられ、
専用のPOSIXスレッドにより実行されます。したがって、コンテキスト
スイッチのオーバヘッドは、ネイティブスレッドとほとんど変わりません。
しかし、スレッドの生成は、例えばcall/ccによる軽量スレッドよりは
ずっとコストのかかる処理です。
このように、Gaucheのプリエンプティブなスレッドは、
きめ細かい計算のために幾千ものスレッドを生成したいアプリケーション
向けでは@emph{ありません}。
@c COMMON

@c EN
The recommended usage is the technique so called "thread pool",
that you create a set of threads and keep them around for
long time and dispatch jobs to them as needed.  Gauche provides
a thread pool implementation in @code{control.thread-pool} module
(@xref{Thread pools}).
@c JP
推奨される使用方法は、いわゆる``スレッドプール''と呼ばれる
テクニックです。つまり、スレッドの集合を作って長時間それを
保持し、必要になったときにジョブをそこへディスパッチする
というものです。Gaucheは@code{control.thread-pool}モジュール
(@ref{Thread pools}参照) でスレッドプールの実装を提供しています。
@c COMMON

@c EN
Preemptive threads have other difficulties
(e.g. see @ref{fairthreads,[FairThreads],FairThreads}),
and sometimes the alternatives may be a better fit
than the native preemptive threads.
@c JP
プリエンプティブなスレッドには他にも難しい点があり
(@ref{fairthreads,[FairThreads],FairThreads}参照)、
しばしばネイティブなプリエンプティブスレッドよりも
より良くフィットする代替策があります。
@c COMMON

@itemize @bullet
@item
@c EN
If what you need is just a concurrent calculation, you
might be able to use cooperative thread technique built
on top of @code{call/cc}.   Creating call/cc-based threads
is much faster than creating native threads.
@c JP
単に同時実行が必要なだけなら、@code{call/cc}による協調スレッド
テクニックが使えるでしょう。call/ccベースのスレッドの生成は、
ネイティブスレッドを生成するよりも高速です。
@c COMMON

@item
@c EN
If what you need is to deal with blocking I/O, and you have
all your code at hand, it is sometimes easier to use good old
@code{select}-based dispatching (@xref{Simple dispatcher},
for example).
@c JP
ブロッキングI/Oを扱う必要があり、全てのコードが手元にある場合は、
古き良き@code{select}ベースのディスパッチ(@ref{Simple dispatcher}に
例があります)を使うほうが簡単なことがあります。
@c COMMON

@item
@c EN
If what you need is to control the resource consumption in the
subsystem, and the subsystem works fairly independently from
the main system, you may be able to use Unix processes instead of threads.
It may sound to go backward, but Unix process does provide
higher "shield" between the subsystem and the main system
(e.g. the main system can keep running even if subsystem segfaults).
@c JP
サブシステムにおけるリソースの消費をコントロールする必要がある場合で、
サブシステムがメインシステムとほとんど独立に動作する場合は、
スレッドの代わりにUnixプロセスが使えることでしょう。
時代に逆行するように聞こえますが、Unixプロセスはサブシステムと
メインシステムの間に高度な``防御壁''を提供します。
(例えば、サブシステムがセグメンテーション違反を起こしても、
メインシステムは実行しつづけられます。)
@c COMMON

@end itemize

@c EN
Of course, these technique are not mutually exclusive with
native threads.  You can use dispatcher with "thread pool" technique,
for example.   Just keep it in your mind that the native threads
are not only but one of the ways to realize those features.
@c JP
もちろん、これらのテクニックはネイティブスレッドとは相互排他ではありません。
例えば、``スレッドプール''テクニックと一緒にディスパッチャを使うこともできます。
それらの機能を実現するために、ネイティブスレッドが唯一の方法ではないということを
心に留め置いて下さい。
@c COMMON


@node Thread procedures, Synchronization primitives, Thread programming tips, Threads
@subsection Thread procedures
@c NODE スレッド手続き

@deftp {Builtin Class} <thread>
@clindex thread
@c EN
A thread.  Each thread has an associated thunk which is evaluated by
a POSIX thread.  When thunk returns normally, the result is stored
in the internal 'result' slot, and can be retrieved by @code{thread-join!}.
When thunk terminates abnormally, either by raising an exception or
terminated by @code{thread-terminate!}, the exception condition is
stored in their internal 'result exception' slot, and will be passed
to the thread calling @code{thread-join!} on the terminated thread.
@c JP
スレッドを表すクラスです。それぞれのスレッドは、POSIXスレッドにより
評価される関連付けられた手続きを持ちます。手続きが正常に戻ると、
その結果は内部的な``結果''スロットに格納され、@code{thread-join!}により
取得することができます。例外が投げられるか
@code{thread-terminate!}により終了されるかで、手続きが異常終了すると、
例外条件が内部的な``結果としての例外''スロットに格納され、
その例外条件は終了したスレッドに対して@code{thread-join!}を
呼ぶスレッドへと渡されます。
@c COMMON

@c EN
Each thread has its own dynamic environment and dynamic handler stack.
When a thread is created, its dynamic environment is initialized by
the creator's dynamic environment.  The thread's dynamic handler
stack is initially empty.
@c JP
それぞれのスレッドは独自の動的環境と動的なハンドラスタックを持っています。
あるスレッドが生成されると、その動的な環境は生成者の動的な環境によって
初期化されます。そのスレッドの動的なハンドラスタックは初期においては空です。
@c COMMON

@c EN
A thread is in one of the following four states at a time.
You can query the thread state by the @code{thread-state} procedure.
@c JP
スレッドは以下の4つの状態のうちのひとつを取ります。@code{thread-state}手続きで
スレッドの状態を調べることができます。
@c COMMON

@table @code
@item new
@c EN
A thread hasn't started yet.  A thread returned from @code{make-thread}
is in this state.  
Once a thread is started it will never be in this state again.
At this point, no POSIX thread has been created; @code{thread-start!}
creates a POSIX thread to run the Gauche thread.
@c JP
まだ作られたばかりで起動されてない状態です。@code{make-thread}が返すスレッドは
この状態です。スレッドがひとたび起動されると、そのスレッドがこの状態に戻ることは
決してありません。
この時点ではPOSIXスレッドはまだ作られません。@code{thread-start!}によって
POSIXスレッドが作られ、Gaucheのスレッドを実行します。
@c COMMON
@item runnable
@c EN
When a thread is started by @code{thread-start!}, it becomes to this
state.   Note that a thread blocked by a system call is still in
@code{runnable} state.
@c JP
@code{thread-start!}によって起動されたスレッドはこの状態になります。
スレッドがシステムコールによるブロックされている時もその状態は@code{runnable}
であることに注意してください。
@c COMMON
@item stopped
@c EN
A thread becomes in this state when it is stopped by @code{thread-stop!}.
A thread in this state can go back to @code{runnable} state by
@code{thread-cont!}, resuming execution from the point when
it is stopped.
@c JP
スレッドが@code{thread-stop!}によって止められるとこの状態になります。
この状態のスレッドは@code{thread-cont!}によって再び@code{runnable}になり、
止められた時点から実行を再開することができます。
@c COMMON
@item terminated
@c EN
When the thread finished executing associated code, or
is terminated by @code{thread-terminate!}, it becomes in this state.
Once a thread is in this state, the state can no longer be changed.
@c JP
割り当てられたコードの実行が終了したり、@code{thread-terminate!}によって
強制的に終了させられた時に、スレッドはこの状態になります。
一度この状態になると他の状態に遷移することはありません。
@c COMMON
@end table

@c EN
Access to the resouces shared by multiple threads must be protected
explicitly by synchronization primitives.
@xref{Synchronization primitives}.
@c JP
複数のスレッドで共有されるリソースへのアクセスは、同期化プリミティブにより
明示的に保護されなければなりません。@ref{Synchronization primitives}参照。
@c COMMON

@c EN
Access to ports are serialized by Gauche. If multiple threads attempt
to write to a port, their output may be interleaved but no output
will be lost, and the state of the port is kept consistent.
If multiple threads attempt to read from a port, a single read
primitive (e.g. @code{read}, @code{read-char} or @code{read-line})
works atomically.
@c JP
ポートへのアクセスはGaucheによりシリアライズされます。
複数のスレッドが1つのポートへの書き込みを試みた場合、それらの出力は
混じることもありますが、失われる出力はなく、そのポートのステータスは
一貫性が保たれます。複数のスレッドが1つのポートからの読み込みを試みた
場合、1つの読み込みプリミティブ(例えば、@code{read}や@code{read-char}、
@code{read-line}など)がアトミックに実行されます。
@c COMMON

@c EN
Signal handlers are shared by all threads, but each thread has
its own signal mask.  @xref{Signals and threads}, for details.
@c JP
シグナルハンドラは全てのスレッドで共有されますが、それぞれのスレッドは
独自のシグナルマスクを持ちます。詳細は、@ref{Signals and threads}を参照。
@c COMMON

@c EN
A thread object has the following external slots.
@c JP
スレッドオブジェクトは以下の外部スロットを持ちます。
@c COMMON

@defivar <thread> name
@c EN
A name can be associated to a thread.
This is just for the convenience of the application.
The primordial thread has the name "@code{root}".
@c JP
スレッドに関連付けられる名前。
これは単にアプリケーションにとっての便宜を図るためのものです。
原始となるスレッドは``@code{root}''という名前を持ちます。
@c COMMON
@end defivar

@defivar <thread> specific
@c EN
A thread-local slot for use of the application.
@c JP
アプリケーションが使うスレッドローカルなスロット。
@c COMMON
@end defivar
@end deftp

@defun current-thread
@c EN
[SRFI-18], [SRFI-21]
Returns the current thread.
@c JP
[SRFI-18]、[SRFI-21]
現在のスレッドを返します。
@c COMMON
@end defun

@defun thread? obj
@c EN
[SRFI-18], [SRFI-21]
Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise.
@c JP
[SRFI-18]、[SRFI-21]
@var{obj}がスレッドなら@code{#t}、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun make-thread thunk :optional name
@c EN
[SRFI-18], [SRFI-21]
Creates and returns a new thread to execute @var{thunk}.
To run the thread, you need to call @code{thread-start!}.
The result of @var{thunk} may be retrieved by calling @var{thread-join!}.
@c JP
[SRFI-18]、[SRFI-21]
@var{thunk}を実行するための新しいスレッドを生成して返します。
そのスレッドの実行を開始するには、@code{thread-start!}を呼ぶ必要があります。
@var{thunk}の実行結果は、@var{thread-join!}を呼ぶことで回収できます。
@c COMMON

@c EN
You can provide the name of the thread by the optional argument @var{name}.
@c JP
オプション引数@var{name}を与えることで、そのスレッドに名前を与えることができます。
@c COMMON

@c EN
The created thread inherits the signal mask of the calling thread
(@xref{Signals and threads}), and has a copy of
parameters of the calling thread at the time of creation
(@xref{Parameters}).
@c JP
作成されたスレッドは、呼び出したスレッドのシグナルマスクを継承し
(@ref{Signals and threads}参照)、また呼び出したスレッドの持つ
その時点でのパラメータのコピーを受けとります。
@c COMMON

@c EN
Other than those initial setups, there will be no relationship between
the new thread and the calling thread; there's no parent-child 
relationship like Unix process.   Any thread can call @code{thread-join!}
on any other thread to receive the result.  If nobody issues
@code{thread-join!} and nobody holds a
reference to the created thread, it will be garbage collected
after the execution of the thread terminates.
@c JP
これらの初期化操作以外に、作られるスレッドと呼び出したスレッド間の関係は
ありません。Unixのプロセスのような親子関係があるわけではないのです。
どのスレッドも、他のスレッドに対して@code{thread-join!}を発行
して結果を受け取ることができます。
もし誰も@code{thread-join!}を発行せず、また作られたスレッドに対する
参照を保持していなかった場合、スレッドは実行が終了した後にガベージコレクトされます。
@c COMMON

@c EN
If a thread execution is terminated because of uncaught exception,
and its result is never retrieved by @code{thread-join!}, a warning
will be printed to the standard error port notifying 
``thread dies a lonely death'':  It usually indicates some coding
error.  If you don't collect the result of threads, you have to
make sure that all the exceptions are captured and handled within @var{thunk}.
@c JP
もしスレッドが捕捉されない例外のために実行を終了し、その結果が@code{thread-join!}で
回収されなかった場合、標準エラーポートに``thread dies a lonely death'' という
警告メッセージが出力されます。そのようなケースは通常何らかのコーディングエラーで
あるからです。スレッドの結果を回収しない場合は、
@var{thunk}中ですべての例外を捕捉し処理しなければなりません。
@c COMMON

@c EN
Internally, this procedure just allocates and initializes a Scheme
thread object; the POSIX thread is not created until @code{thread-start!}
is called.
@c JP
内部的に、この手続きは単にSchemeスレッドオブジェクトを割り当て初期化している
だけです。POSIXスレッドは@code{thread-start!}が呼ばれるまで生成されません。
@c COMMON
@end defun

@defun thread-state thread
@c EN
Returns one of symbols @code{new}, @code{runnable}, @code{stopped}
or @code{terminated}, indicating the state of @var{thread}.
@c JP
@var{thread}の状態を示す、@code{new}、@code{runnable}、@code{stopped}、
@code{terminated}のいずれかのシンボルを返します。
@c COMMON
@end defun

@defun thread-name thread
@c EN
[SRFI-18], [SRFI-21]
Returns the value of @var{name} slot of @var{thread}.
@c JP
[SRFI-18]、[SRFI-21]
@var{thread}のスロット@var{name}の値を返します。
@c COMMON
@end defun

@defun thread-specific thread
@defunx thread-specific-set! thread value
@c EN
[SRFI-18], [SRFI-21]
Gets/sets the value of the @var{thread}'s specific slot.
@c JP
[SRFI-18]、[SRFI-21]
@var{thread}の指定したスレッドの値を取得/設定します。
@c COMMON
@end defun

@defun thread-start! thread
@c EN
[SRFI-18], [SRFI-21]
Starts the @var{thread}.  It is an error if @var{thread} is already started.
Returns @var{thread}.
@c JP
[SRFI-18]、[SRFI-21]
@var{thread}を開始します。@var{thread}がすでに開始されていればエラーになります。
@var{thread}を返します。
@c COMMON
@end defun

@defun thread-yield!
@c EN
[SRFI-18], [SRFI-21]
Suspends the execution of the calling thread and yields CPU to other
waiting runnable threads, if any.
@c JP
[SRFI-18]、[SRFI-21]
呼び出しているスレッドの実行を中断し、他に待機中の実行可能なスレッドがあれば、
CPUにそれを処理させます。
@c COMMON
@end defun

@defun thread-sleep! timeout
@c EN
[SRFI-18], [SRFI-21]
Suspends the calling thread for the period specified by @var{timeout},
which must be either a @code{<time>} object (@xref{Time}) that
specifies absolute point of time, or a real number that specifies
relative point of time from the time this procedure is called
in number of seconds.
@c JP
[SRFI-18]、[SRFI-21]
呼び出しているスレッドを@var{timeout}に指定した時間だけ中断します。
@var{timeout}は絶対的な時間を表す@code{<time>}オブジェクト(@ref{Time}参照)か、
この手続きが呼ばれた時刻からの相対的な秒数を表す実数でなければなりません。
@c COMMON

@c EN
After the specified time passes, @code{thread-sleep!} returns with
unspecified value.
@c JP
指定された時間が経過すると、@code{thread-sleep!}は未定義値を返します。
@c COMMON

@c EN
If @var{timeout} points a past time, @code{thread-sleep!} returns
immediately.
@c JP
@var{timeout}が過去の時間を指していたら、@code{thread-sleep!}はすぐに戻ります。
@c COMMON
@end defun

@defun thread-stop! thread :optional timeout timeout-val
Stops execution of the target @var{thread} temporarily.
You can resume the execution of the @var{thread} by @code{thread-cont!}.

The stop request is handled synchronously; that is,
Gauche VM only checks the request at the ``safe'' point
of the VM and stops itself.  It means if the @var{thread} is
blocked by a system call, it won't become @code{stopped} state
until the system call returns.

By default, @code{thread-stop!} returns after the target
thread stops.  Since it may take indefinitely, you can give optional 
@var{timeout} argument to specify timeout.   The @var{timeout}
argument can be @code{#f}, which means no timeout, or 
a @code{<time>} object that specifies an absolute point of time,
or a real number specifying the number of seconds to wait.

The return value of @code{thread-stop!} is @var{thread} if
it could successfully stop the target, or @var{timeout-val}
if timeout reached.   When @var{timeout-val} is omitted, @code{#f}
is assumed.

If the target @var{thread} has already been stopped by the caller
thread, this procedure returns immediately.

When @var{thread-stop!} is timed out, the request remains
effective even after @var{thread-stop!} returns.
That is, the target thread may stop at some point in future.  
The caller thread is expected to call @var{thread-stop!}
again to complete the stop operation.

An error is signalled if the target thread has already been
stopped by another thread (including the ``pending'' stop
request issued by other threads), or the target thread
is in neither @code{runnable} nor @code{stopped} state.
@end defun

@defun thread-cont! thread
Resumes execution of @var{thread} which has been stopped by
@code{thread-stop!}.  An error is raised if @var{thread} 
is not in stopped state, or it is stopped by another thread.

If the caller thread has already requested to stop the target
thread but timed out, calling @code{thread-cont!} cancels
the request.
@end defun

@defun thread-terminate! thread
@c EN
[SRFI-18], [SRFI-21]
Terminates the specified thread @var{thread}.
The @var{thread} is terminated and an instance of 
@code{<terminated-thread-exception>} is stored in the result exception
field of @var{thread}.
@c JP
[SRFI-18]、[SRFI-21]
指定されたスレッド@var{thread}を終了します。
@var{thread}は終了され、@code{<terminated-thread-exception>}のインスタンスが
@var{thread}の結果例外のフィールドに格納されます。
@c COMMON

@c EN
If @var{thread} is the same as the calling thread, this procedure
won't return.  Otherwise, this procedure returns unspecified value.
@c JP
@var{thread}が呼び出しているスレッドと同じ場合、この手続きは戻りません。
そうでなければ、この手続きは未定義値を返します。
@c COMMON

@c EN
This procedure should be used with care, since
@var{thread} won't have a chance to call cleanup
procedures (such as 'after' thunks of @code{dynamic-wind}).
If @var{thread} is in a critical section, it can leave some state
inconsistent.  However, once a thread is terminated, any mutex
that the thread has kept becomes 'abandoned' state, and an attempt
to lock such a mutex by other thread raises an 'abandoned mutex exception',
so that you will know the situation.  @xref{Synchronization primitives}.
@c JP
@var{thread}には(@code{dynamic-wind}での'after'手続きのような)クリーンアップ手続きを
呼ぶチャンスがないので、この手続きは注意して使って下さい。
@var{thread}がクリティカルセクションにあるならば、一貫性のない状態を残すことに
なります。
しかし、あるスレッドが一旦終了すると、そのスレッドが保持していたmutexは
'abandoned'(放棄された)状態になり、そのようなmutexをロックしようとするスレッドは
'abandoned mutex exception'を投げるので、その状況を知ることができます。
@ref{Synchronization primitives}参照。
@c COMMON
@end defun


@defun thread-join! thread :optional timeout timeout-val
@c EN
[SRFI-18], [SRFI-21]
Waits termination of @var{thread}, or until the timeout is reached
if @var{timeout} is given.
@c JP
[SRFI-18]、[SRFI-21]
@var{thread}の終了、あるいは@var{timeout}が与えられていればtimeoutが
それに達するのを待ちます。
@c COMMON

@c EN
@var{Timeout} must be either a @code{<time>} object (@xref{Time})
that specifies absolute point of time, or a real number that specifies
relative point of time from the time this procedure is called
in number of seconds, or @code{#f} that indicates no timeout (default).
@c JP
@var{Timeout}は絶対的な時間を表す@code{<time>}オブジェクト(@ref{Time}参照)か、
この手続きが呼ばれた時刻からの相対的な時間を秒数で表した実数でなければなりません。
タイムアウトが指定されていない(デフォルト)は@code{#f}です。
@c COMMON

@c EN
If @var{thread} terminates normally, @code{thread-join!} returns
a value which is stored in the result field of @var{thread}.
If @var{thread} terminates abnormally, @code{thread-join!} raises
an exception which is stored in the result exception field of @var{thread}.
It can be either a @code{<terminated-thread-exception>} or
@code{<uncaught-exception>}.
@c JP
@var{thread}が正常に終了したら、@code{thread-join!}は@var{thread}の
結果フィールドに格納されている値を返します。
@var{thread}が異常終了したら、@code{thread-join!}は@var{thread}の結果例外
フィールドに格納されている例外を投げます。それは
@code{<terminated-thread-exception>}か
@code{<uncaught-exception>}のどちらかです。
@c COMMON

@c EN
If the timeout is reached, @var{thread-join!} returns @var{timeout-val}
if given, or raises @code{<join-timeout-exception>}.
@c JP
タイムアウトに達すると、@var{timeout-val}が与えられていれば@var{timeout-val}を返し、
与えられていなければ@code{<join-timeout-exception>}を投げます。
@c COMMON

@c EN
@xref{Thread exceptions}, for the details of these exceptions.
@c JP
これらの例外の詳細については@ref{Thread exceptions}を参照してください。
@c COMMON
@end defun

@node Synchronization primitives, Thread exceptions, Thread procedures, Threads
@subsection Synchronization primitives
@c NODE 同期プリミティブ

@subsubheading Mutex

@deftp {Builtin Class} <mutex>
@clindex mutex
@c EN
A primitive synchronization device.  It can take one of four states:
locked/owned, locked/not-owned, unlocked/abandoned and unlocked/not-abandoned.
A mutex can be locked (by @code{mutex-lock!}) only if it is in unlocked state.
An 'owned' mutex keeps a thread that owns it.
Typically an owner thread is the one that locked the mutex,
but you can make a thread other than the locking thread own a mutex.
A mutex becomes unlocked either by @code{mutex-unlock!} or the owner
thread terminates.  In the former case, a mutex becomes unlocked/not-abandoned
state.  In the latter case, a mutex becomes unlocked/abandoned state.
@c JP
同期のための基本的デバイスです。次の4つの状態のいずれかを持ちます:
locked/owned、locked/not-owned、unlocked/abandoned、unlocked/not-abandoned。
Mutexは、それがunlocked(ロックされていない状態)であるときのみ、
(@code{mutex-lock!}により)ロックされます。
所有されている(owned) mutexは、そのmutexを所有しているスレッドを記憶しています。
通常、所有者となるスレッドはmutexをロックしたスレッドですが、
ロックしたのとは別のスレッドがmutexを所有するようにすることもできます。
ロックは@code{mutex-unlock!}によるか、所有するスレッドが終了すると解放されます。
前者の場合、mutexはunlocked/not-abandoned(ロックされておらず、放棄されていない状態)
になります。
後者の場合、mutexはunlocked/abandoned(ロックされておらず、放棄された状態)になります。
@c COMMON

@c EN
A mutex has the following external slots.
@c JP
Mutexは、以下の外部スロットを持ちます。
@c COMMON

@defivar <mutex> name
@c EN
The name of the mutex.
@c JP
Mutexの名前。
@c COMMON
@end defivar

@defivar <mutex> state
@c EN
The state of the mutex.  This is a read-only slot.
See the description of @code{mutex-state} below.
@c JP
Mutexの状態。これは読み取りのみ可能なスロットです。
下記の@code{mutex-state}の説明を参照して下さい。
@c COMMON
@end defivar

@defivar <mutex> specific
@c EN
A slot an application can keep arbitrary data.  For example, an application
can implement a 'recursive' mutex using the specific field.
@c JP
アプリケーションが任意のデータを保持することのできるスロットです。
例えば、アプリケーションはこの固有フィールドで'再帰的な' mutexを
実装することができます。
@c COMMON
@end defivar
@end deftp

@defun mutex? obj
@c EN
[SRFI-18], [SRFI-21]
Returns @code{#t} if @var{obj} is a mutex, @code{#f} otherwise.
@c JP
[SRFI-18]、[SRFI-21]
@var{obj}がmutexであれば@code{#t}、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun make-mutex :optional name
@c EN
[SRFI-18], [SRFI-21]
Creates and returns a new mutex object.
When created, the mutex is in unlocked/not-abandoned state.
Optionally, you can give a name to the mutex.
@c JP
[SRFI-18]、[SRFI-21]
新しいmutexオブジェクトを生成して返します。
生成時には、mutexの状態は、unlocked/not-abandoned(ロックされておらず、
放棄されていない状態)です。オプションで、このmutexに名前を付けることができます。
@c COMMON
@end defun

@defun mutex-name mutex
@c EN
[SRFI-18], [SRFI-21]
Returns the name of the mutex.
@c JP
[SRFI-18]、[SRFI-21]
Mutexの名前を返します。
@c COMMON
@end defun

@defun mutex-specific mutex
@defunx mutex-specific-set! mutex value
@c EN
[SRFI-18], [SRFI-21]
Gets/sets the specific value of the mutex.
@c JP
[SRFI-18]、[SRFI-21]
Mutexの固有の値を取得/セットできます。
@c COMMON
@end defun

@defun mutex-state mutex
@c EN
[SRFI-18], [SRFI-21]
Returns the state of @var{mutex}, which may be one of the followings:
@c JP
[SRFI-18]、[SRFI-21]
@var{mutex}の状態を返します。状態は以下のうちの1つです。
@c COMMON

@table @asis
@c EN
@item a thread
The mutex is locked/owned, and the owner is the returned thread.
@item symbol @code{not-owned}
The mutex is locked/not-owned.
@item symbol @code{abandoned}
The mutex is unlocked/abandoned.
@item symbol @code{not-abandoned}
The mutex is unlocked/not-abandoned.
@c JP
@item あるスレッド
Mutexはlocked/owned(ロックされ所有されている)で、所有者は返されたスレッド。
@item シンボル @code{not-owned}
Mutexはlocked/not-owned(ロックされているが所有されていない)。
@item シンボル @code{abandoned}
Mutexはunlocked/abandoned(ロックされておらず、放棄されている)。
@item シンボル @code{not-abandoned}
Mutexはunlocked/not-abandoned(ロックされておらず、放棄されていない)。
@c COMMON
@end table
@end defun

@defun mutex-lock! mutex :optional timeout thread
@c EN
[SRFI-18], [SRFI-21]
Locks @var{mutex}.  If @var{mutex} is in unlocked/not-abandoned
state, this procedure changes its state to locked state exclusively.
By default, @var{mutex} becomes locked/owned state, owned by the
calling thread.  You can give other owner thread as @var{thread} argument.
If @var{thread} argument is given and @code{#f}, the mutex becomes
locked/not-owned state.
@c JP
[SRFI-18]、[SRFI-21]
@var{mutex}をロックします。@var{mutex}がunlocked/not-abandoned(
ロックされておらず放棄されていない状態)なら、
この手続きはその状態を排他的なlocked(ロックされた状態)に変更します。
デフォルトでは、@var{mutex}はlocked/owned(ロックされ、所有された状態)になり、
所有者は呼び出したスレッドです。
他の所有しているスレッドを、引数@var{thread}を与えることもできます。
引数@var{thread}に@code{#f}が与えられると、mutexはlocked/not-owned
(ロックされ所有されていない状態)になります。
@c COMMON

@c EN
If @var{mutex} is in unlocked/abandoned state, that is, some other
thread has been terminated without unlocking it, this procedure
signals 'abandoned mutex exception' (@xref{Thread exceptions})
after changing the state of @var{mutex}.
@c JP
@var{mutex}がunlocked/abandoned(ロックされておらず放棄された状態)ならば、それはつまり、
他の何らかのスレッドがそのロックを解放せずに終了した場合、
この手続きは@var{mutex}の状態を変更した後に、'abandoned mutex exception'
(@ref{Thread exceptions}参照)を通知します。
@c COMMON

@c EN
If @var{mutex} is in locked state and
@var{timeout} is omitted or @code{#f}, this procedure blocks until
@var{mutex} becomes unlocked.   If @var{timeout} is specified,
@code{mutex-lock!} returns when the specified time reaches in
case it couldn't obtain a lock.  You can give @var{timeout}
an absolute point of time (by @code{<time>} object, @xref{Time}),
or a relative time (by a real number).
@c JP
@var{mutex}がlocked(ロックされた状態)で、@var{timeout}が省略されるか@code{#f}ならば、
この手続きは@var{mutex}のロックが解放されるまでブロックします。
@var{timeout}が指定されている場合は、ロックが獲得できなかったケースでは
指定された時間に達した時に@code{mutex-lock!}は戻ります。
@var{timeout}には、絶対的な時間(@code{<time>}オブジェクト、@ref{Time}参照)か、
相対的な時間を(実数で)指定できます。
@c COMMON

@c EN
@code{Mutex-lock!} returns @code{#t} if @var{mutex} is successfully
locked, or @code{#f} if timeout reached.
@c JP
@var{mutex}のロックが成功すると@code{mutex-lock!}は@code{#t}を返し、
タイムアウトに達すると@code{#f}が返ります。
@c COMMON

@c EN
Note that @var{mutex} itself doesn't implements a 'recursive lock'
feature; that is, if a thread that has locked @var{mutex} tries to lock
@var{mutex} again, the thread blocks.  It is not difficult, however,
to implement a recursive lock semantics on top of this mutex.
The following example is taken from SRFI-18 document:
@c JP
@var{mutex}それ自身は'再帰的なロック'の機能は実装していません。
つまり、@var{mutex}をロックしたスレッドが再度@var{mutex}をロックしようと
すると、そのスレッドはブロックします。しかし、このmutexに
基づいて再帰的なロックのセマンティクスを実装することは難しくありません。
次の例は、SRFI-18のドキュメントから引用したものです。
@c COMMON

@example
(define (mutex-lock-recursively! mutex)
  (if (eq? (mutex-state mutex) (current-thread))
      (let ((n (mutex-specific mutex)))
        (mutex-specific-set! mutex (+ n 1)))
      (begin
        (mutex-lock! mutex)
        (mutex-specific-set! mutex 0))))

(define (mutex-unlock-recursively! mutex)
  (let ((n (mutex-specific mutex)))
    (if (= n 0)
        (mutex-unlock! mutex)
        (mutex-specific-set! mutex (- n 1)))))
@end example
@end defun

@defun mutex-unlock! mutex :optional condition-variable timeout
@c EN
[SRFI-18], [SRFI-21]
Unlocks @var{mutex}.  The state of @var{mutex} becomes unlocked/not-abandoned.
It is allowed to unlock a mutex that is not owned by the calling thread.
@c JP
[SRFI-18]、[SRFI-21]
@var{mutex}をアンロックします。@var{mutex}の状態は、unlocked/not-abandoned
(ロックされておらず、放棄されていない状態)となります。
呼び出しているスレッドにより所有されていないmutexをアンロックすることは
許されています。
@c COMMON

@c EN
If optional @var{condition-variable} is given, @code{mutex-unlock!}
serves the "condition variable wait" operation (e.g. @code{pthread_cond_wait}
in POSIX threads).   The current thread atomically wait on
@var{condition-variable} and unlocks @var{mutex}.
The thread will be unblocked when other thread signals on
@var{condition-variable} (see @code{condition-variable-signal!}
and @code{condition-variable-broadcast!} below), or @var{timeout}
reaches if it is supplied.  The @var{timeout} argument can be either
a @code{<time>} object to represent an absolute time point (@xref{Time}),
a real number to represent a relative time in seconds, or @code{#f} which
means never.  The calling thread may be unblocked prematurely,
so it should reacquire the lock of @var{mutex} and checks the
condition, as in the following example (it is taken from SRFI-18 document):
@c JP
オプショナル引数の@var{conditional-variable}が与えられている場合、
@code{mutex-unlock!}は``条件変数待機''の動作も行います(例えば、POSIXスレッドの
@code{pthread_cond_wait})。
現在のスレッドは@var{mutex}をアンロックし、
@var{condition-variable}の待ち状態に入る動作をアトミックに行います。
スレッドは、他のスレッドが@var{condition-variable}にシグナルを通知するか
(下記の@code{condition-variable-signal!}と@code{condition-variable-broadcast!}を
見て下さい)、
@var{timeout}が与えられていてそれに達すると、ブロックが解除されます。
引数@var{timeout}は、絶対的な時間を表す@code{<time>}オブジェクト(@ref{Time}参照)、
相対的な時間を秒数で表す実数、タイムアウトしないことを表す@code{#f}のいずれかです。
ブロックが解除された時に、必ずしも条件が満たされているとは限らないので、
次に挙げる例(SRFI-18のドキュメントより引用)のように、
呼び出したスレッドは@var{mutex}のロックを再獲得して条件を検査するべきです。
@c COMMON

@example
(let loop ()
  (mutex-lock! m)
  (if (condition-is-true?)
      (begin
        (do-something-when-condition-is-true)
        (mutex-unlock! m))
      (begin
        (mutex-unlock! m cv)
        (loop))))
@end example

@c EN
The return value of @code{mutex-unlock!} is @code{#f} when it returns
because of timeout, and @code{#t} otherwise.
@c JP
@code{mutex-unlock!}の戻り値は、タイムアウトした場合に@code{#f}、
それ以外の場合は@code{#t}となります。
@c COMMON
@end defun

@defun with-locking-mutex mutex thunk
@c EN
Calls @var{thunk} with locking a mutex @var{mutex}.  This is defined as
follows.
@c JP
@var{mutex}をロックして@var{thunk}を呼びます。次のように実装されています。
@c COMMON
@example
(define (with-locking-mutex mutex thunk)
  (dynamic-wind
   (lambda () (mutex-lock! mutex))
   thunk
   (lambda () (mutex-unlock! mutex))))
@end example
@end defun

@c EN
@subsubheading Condition variable
@c JP
@subsubheading 条件変数
@c COMMON

@deftp {Builtin Class} <condition-variable>
@clindex condition-variable
@c EN
A condition variable keeps a set of threads that are waiting for
a certain condition to be true.  When a thread modifies the state 
of the concerned condition, it can call @code{condition-variable-signal!}
or @code{condition-variable-broadcast!}, which unblock one or more
waiting threads so that they can check if the condition is satisfied.
@c JP
条件変数は、ある条件が真になるのを待っているスレッドの集合を保持します。
あるスレッドがその条件を変更する時、@code{condition-variable-signal!}あるいは
@code{condition-variable-broadcast!}が呼ばれ、それは1つ以上の待機中の
スレッドのブロックを解除するため、それらのスレッドは条件が満足するかどうか
検査できます。
@c COMMON

@c EN
A condition variable object has the following slots.
@c JP
条件変数オブジェクトは以下のスロットを持ちます。
@c COMMON

@defivar <condition-variable> name
@c EN
The name of the condition variable.
@c JP
条件変数の名前。
@c COMMON
@end defivar

@defivar <condition-variable> specific
@c EN
A slot an application can keep arbitrary data.
@c JP
アプリケーションが任意のデータを保持できるスロット。
@c COMMON
@end defivar

@c EN
Note that SRFI-18 doesn't have a routine equivalent to pthreads'
@code{pthread_cont_wait}.  If you want to wait on condition variable,
you can pass a condition variable to @code{mutex-unlock!} as an
optional argument (see above), then acquire mutex again by
@code{mutex-lock!}.  This design is for flexibility; see 
SRFI-18 document for the details.
@c JP
SRFI-18は、pthreadの@code{pthread_cond_wait}に相当する手続きを
持たないことに注意してください。条件変数を待つのは、
@code{mutex-unlock!}の省略可能引数に条件変数を渡し、
その後mutexを再び@code{mutex-lock!}で得ることで行います。
この設計は柔軟性のためです。詳しくはSRFI-18を参照して下さい。
@c COMMON

@c EN
This is the common usage of pthreads' condition variable:
@c JP
このような、pthreadで条件変数を使う定石は：
@c COMMON
@example
while (some_condition != TRUE) @{
  pthread_cond_wait(condition_variable, mutex);
@}
@end example
@c EN
And it can be translated to SRFI-18 as follows:
@c JP
SRFI-18では次のようなコードになります。
@c COMMON
@example
(let loop ()
  (unless some-condition
    (mutex-unlock! mutex condition-variable)
    (mutex-lock! mutex)
    (loop)))
@end example
@end deftp

@defun condition-variable? obj
@c EN
[SRFI-18], [SRFI-21]
Returns @code{#t} if @var{obj} is a condition variable,
@code{#f} otherwise.
@c JP
[SRFI-18]、[SRFI-21]
@var{obj}が条件変数なら@code{#t}、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun make-condition-variable :optional name
@c EN
[SRFI-18], [SRFI-21]
Returns a new condition variable.  You can give its name by
optional @var{name} argument.
@c JP
[SRFI-18]、[SRFI-21]
新しい条件変数を返します。オプショナル引数@var{name}で
その名前を与えることができます。
@c COMMON
@end defun

@defun condition-variable-name cv
@c EN
[SRFI-18], [SRFI-21]
Returns the name of the condition variable.
@c JP
[SRFI-18]、[SRFI-21]
条件変数の名前を返します。
@c COMMON
@end defun

@defun condition-variable-specific cv
@defunx condition-variable-specific-set! cv value
@c EN
[SRFI-18], [SRFI-21]
Gets/sets the specific value of the condition variable.
@c JP
[SRFI-18]、[SRFI-21]
条件変数の固有の値を取得/セットします。
@c COMMON
@end defun

@defun condition-variable-signal! cv
@c EN
[SRFI-18], [SRFI-21]
If there are threads waiting on @var{cv}, causes the scheduler to select
one of them and to make it runnable.
@c JP
[SRFI-18]、[SRFI-21]
@var{cv}で待機しているスレッドがある場合は、それらのうちの1つがスケジューラに
より選択され、実行可能にされます。
@c COMMON
@end defun

@defun condition-variable-broadcast! cv
@c EN
[SRFI-18], [SRFI-21]
Unblocks all the threads waiting on @var{cv}.
@c JP
[SRFI-18]、[SRFI-21]
@var{cv}で待機している全てのスレッドのブロックを解除します。
@c COMMON
@end defun

@c EN
@subsubheading Atom
@c JP
@subsubheading アトム
@c COMMON

An atom is a convenient wrapper to make operations on a
given set of objects thread-safe.  Instead of defining
thread-safe counterparts of every structure, you can easily
wrap an existing data structures to make it thread-safe.

@defun atom val @dots{}
Creates and returns an atom object with @var{val} @dots{} as the
initial values.
@end defun

@defun atom? obj
Returns @code{#t} iff @var{obj} is an atom.
@end defun

The following procedures can be used to @emph{atomically} 
access and update the content of an atom.   They commonly
takes optional @var{timeout} and @var{timeout-val} arguments,
both are defaulted to @code{#f}, which causes those procedures
to block until they acquire a lock.

Those arguments can be used to modify the behavior when
the lock cannot be acquired in timely manner.
@var{timeout} may be a @code{<time>} object (@xref{Time})
to specify an absolute point of time, or a real number
to specify the relative time in seconds.  If timeout is
expired, those procedures give up acquiring the lock,
and the value given to @var{timeout-val} is returned.

@defun atom-ref atom :optional index timeout timeout-val
Returns @var{index}-th value of @var{atom}.
See above for @var{timeout} and @var{timeout-val} arguments.

@example
(define a (atom 'a 'b))

(atom-ref a 0) @result{} a
(atom-ref a 1) @result{} b
@end example
@end defun

@defun atomic atom proc :optional timeout timeout-val
Calls @var{proc} with the current values in @var{atom},
while locking @var{atom}.  @var{proc} must take
as many arguments as the number of values @var{atom} has.

The returned value(s) of @var{proc} is the result of
@code{atomic}, unless timeout occurs.
See above for @var{timeout} and @var{timeout-val} arguments.

For example, the @code{ref/count} procedure
in the following example counts the number of times
the hashtable is referenced in thread-safe way.

@example
(define a (atom (make-hash-table 'eq?) (list 0)))

(define (ref/count a key)
  (atomic a
   (lambda (ht count-cell)
     (inc! (car count-cell))
     (hash-table-get h key))))
@end example
@end defun

@defun atomic-update! atom proc :optional timeout timeout-val
Calls @var{proc} with the current values in @var{atom}
while locking @var{atom}, and updates the values in @var{atom}
by the returned values from @var{proc}.
@var{proc} must take as many arguments as the number of
values @var{atom} has, and must return the same number of
values.

The returned value(s) of @var{proc} is the result of
@code{atomic}, unless timeout occurs.
See above for @var{timeout} and @var{timeout-val} arguments.

The following example shows a thread-safe counter.

@example
(define a (atom 0))

(atomic-update! a (cut + 1 <>))
@end example
@end defun


Note: The term @emph{atom} in historical Lisps
meant objects that are not a cons cell (pair).  Back then 
cons cells were the only aggregated datatype and there were
few other datatypes (numbers and symbols), so having a
complementary term to cells made sense.

Although it still appears in introductory Lisp tutorials,
modern Lisps, including Scheme, has so many datatypes and it makes
little sense to have a specific term for non-aggregate types.

Clojure adopted the term @emph{atom} for thread-safe (atomic)
primitive data, and we followed it.

Note: The constructor of atom is not @code{make-atom}
but @code{atom}, following the convention of @code{list}/@code{make-list},
@code{vector}/@code{make-vector}, and @code{string}/@code{make-string}; 
that is, the name without @code{make-} takes its elements as
variable number of arguments.

@node Thread exceptions,  , Synchronization primitives, Threads
@subsection Thread exceptions
@c NODE スレッド例外

@c EN
Some types of exceptions may be thrown from thread-related procedures.
These exceptions can be handled by Gauche's exception mechanism
(@xref{Exceptions}).
@c JP
例外のいくつかのタイプは、スレッド関連の手続きから投げられます。
これらの例外は、Gaucheの例外メカニズム(@ref{Exceptions}参照)により
扱われます。
@c COMMON

@deftp {Builtin Class} <thread-exception>
@clindex thread-exception
@c EN
A base class of thread-related exceptions.  Inherits @code{<exception>} class.
It has one slot.
@c JP
スレッド関連の例外の基底クラスです。@code{<exception>}クラスを継承しています。
スロットを1つ持っています。
@c COMMON

@defivar <thread-exception> thread
@c EN
A thread that threw this exception.
@c JP
この例外を投げたスレッド。
@c COMMON
@end defivar
@end deftp

@deftp {Builtin Class} <join-timeout-exception>
@clindex join-timeout-exception
@c EN
An exception thrown by @code{thread-join!} when a timeout reaches
before the waited thread returns.  Inherits @code{<thread-exception>}.
@c JP
待機していたスレッドが戻る前にタイムアウトに達した時に@code{thread-join!}によって
投げられる例外。@code{<thread-exception>}を継承しています。
@c COMMON
@end deftp

@deftp {Builtin Class} <abandoned-mutex-exception>
@clindex abandoned-mutex-exception
@c EN
An exception thrown by @code{mutex-lock!} when a @var{mutex} to be
locked is in unlocked/abandoned state.  Inherits @code{<thread-exception>}.
It has one additional slot.
@c JP
ロックされる@var{mutex}が、unlocked/abandoned(ロックされておらず、放棄された状態)
であるときに@code{mutex-lock!}により投げられる例外。
@code{<thread-exception>}を継承しています。スロットを1つ持ちます。
@c COMMON

@defivar <abandoned-mutex-exception> mutex
@c EN
A mutex that caused this exception.
@c JP
この例外の原因となったmutex。
@c COMMON
@end defivar
@end deftp

@deftp {Builtin Class} <terminated-thread-exception>
@clindex terminated-thread-exception
@c EN
An exception thrown by @code{thread-join!} when the waited thread
is terminated abnormally (by @code{thread-terminate!}).
Inherits @code{<thread-exception>}.  It has one additional slot.
@c JP
待機していたスレッドが(@code{thread-terminate!}により)異常終了した
場合に(@code{thread-join!}により)投げられる例外。
@code{<thread-exception>}を継承し、スロットを1つ持ちます。
@c COMMON

@defivar <terminated-thread-exception> terminator
@c EN
A thread that terminated the thread that causes this exception.
@c JP
この例外の原因となったスレッドを終了したスレッド。
@c COMMON
@end defivar
@end deftp

@deftp {Builtin Class} <uncaught-exception>
@clindex uncaught-exception
@c EN
An exception thrown by @code{thread-join!} when the waited thread
is terminated by an uncaught exception.
Inherits @code{<thread-exception>}.  It has one additional slot.
@c JP
待機していたスレッドが捕捉されない例外により終了された場合に
@code{thread-join!}により投げられる例外。
@code{<thread-exception>}を継承し、スロットを1つ持ちます。
@c COMMON

@defivar <uncaught-exception> reason
@c EN
An exception that caused the termination of the thread.
@c JP
そのスレッドの終了の原因となった例外。
@c COMMON
@end defivar
@end deftp

@defun join-timeout-exception? obj
@defunx abandoned-mutex-exception? obj
@defunx terminated-thread-exception? obj
@defunx uncaught-exception? obj
@c EN
[SRFI-18], [SRFI-21]
These procedures checks if @var{obj} is a certain type of exception.
Provided for the compatibility to SRFI-18.
@c JP
[SRFI-18]、[SRFI-21]
これらの手続きは、@var{obj}が特定のタイプの例外かどうかを検査します。
SRFI-18との互換性のために提供されています。
@c COMMON
@end defun

@defun uncaught-exception-reason exc
@c EN
[SRFI-18], [SRFI-21]
Returns the value of @code{reason} slot of @code{<uncaught-exception>}
object.
Provided for the compatibility to SRFI-18.
@c JP
[SRFI-18]、[SRFI-21]
@code{<uncaught-exception>}オブジェクトの@code{reason}スロットの値を
返します。
SRFI-18との互換性のために提供されています。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Measure timings, Uniform vectors, Threads, Library modules - Gauche extensions
@section @code{gauche.time} - Measure timings
@c NODE 時間の計測, @code{gauche.time} - 時間の計測

@deftp {Module} gauche.time
@mdindex gauche.time
@c EN
Provides three ways to measure execution time of Scheme code.
A macro @code{time}, which is convenient for interactive use,
a set of procedures for benchmarking,
and @code{<time-counter>} objects which are useful to be embedded
in the program.
@c JP
Schemeコードの実行時間を測る3つの方法を提供します。
インタラクティブな使用に便利な@code{time}マクロ、
ベンチマークのための手続きのセット、
プログラム中に埋め込んで使える@code{<time-counter>}オブジェクトです。
@c COMMON
@end deftp

@c EN
@subheading Interactive measurement of execution time
@c JP
@subheading インタラクティブな実行時間の計測
@c COMMON

@c EN
Note: The @code{time} macro is pre-defined to autoload @code{gauche.time}
for the convenience; you don't need to say @code{(use gauche.time)}
to use the @code{time} macro.
@c JP
註: @code{time}マクロは@code{gauche.time}モジュールをオートロードする
ようにあらかじめ定義されているので、@code{time}マクロを使うだけなら
@code{(use gauche.time)}としておく必要はありません。
@c COMMON

@defmac time expr expr2 @dots{}
@c EN
Evaluates @var{expr} @var{expr2} @dots{} sequentially, as @code{begin},
and returns the result(s) of the last expression.
Before returning the value(s), the macro reports the elapsed (real) time
and CPU times in the user space and the kernel space to the current
error port, much like the bourne shell's time command.
@c JP
式@var{expr} @var{expr2} @dots{} を順に評価し、最後の式の結果を返します。
結果が返される前に、全ての式の評価にかかった実(経過)時間および
ユーザースペース、カーネルスペースで費されたCPU時間がカレントエラーポートに
報告されます。
@c COMMON

@c EN
The current version uses @code{sys-gettimeofday} (@xref{Time}) to
calculate the elapsed time, and @code{sys-times} (@xref{System inquiry})
to calculate user and system CPU times.  So the resolution of these numbers
depends on these underlying system calls.  Usually the CPU
time has 10ms resolution, while the elapsed time might have higher
resolution.  On the systems that doesn't have gettimeofday(2) support,
however, the elapsed time resolution can be as bad as a second.
@c JP
現在の実装は、経過時間に対しては@code{sys-gettimeofday}
(@ref{Time}参照)を、CPU時間に対しては@code{sys-times}
(@ref{System inquiry}参照)を用いています。従って、
それぞれの数値の分解能はこれらの手続きが用いているシステムコールに依存します。
CPU時間は10ms単位で、経過時間はそれより細かいことが多いです。
但しgettimeofday(2)コールをサポートしていないOSでは経過時間が最悪の場合
秒単位になります。
@c COMMON

@smallexample
gosh> (time (length (sort (call-with-input-file "/usr/share/dict/words"
                                                port->string-list))))
;(time (length (sort (call-with-input-file "/usr/share/dict/words" port- ...
; real   0.357
; user   0.350
; sys    0.000
45427
@end smallexample
@end defmac

@c EN
@subheading Benchmarking
@c JP
@subheading ベンチマーク
@c COMMON

It is not unusual that the routine you want to measure takes only
a fraction of second, so you have to run it many times for better
measurement.  It is also common that you want to compare results
of measurement of two or more implementation strategies.
Here are useful procedures to do so.

The name and behavior of those benchmarking routines are inspired
by Perl's Benchmark module.

@defun time-this how thunk
Calls @var{thunk} many times and measure its execution time.
The argument @var{how} can be one of the following forms.

@table @code
@item @var{integer}
It calls @var{thunk} as many times as the given number.
@item (cpu @var{real})
It calls @var{thunk} as many times as the total cpu time exceeds
the given number of seconds.
@end table

It also runs an empty loop as the same times and subtract the
time took for the empty loop from the measured time, to get
more accurate result.

The result is returned in a @code{<time-result>} record, described below.
Here are some examples:
@smallexample
;; Run the thunk 1,000,000 times
(time-this 1000000 (lambda () (expt 100 30)))
  @result{} #<time-result 1000000 times/  1.030 real/  1.040 user/  0.000 sys>

;; Run the thunk at least 5.0 cpu seconds
(time-this '(cpu 5.0) (lambda () (expt 100 30)))
  @result{} #<time-result 4903854 times/  5.090 real/  5.050 user/  0.010 sys>
@end smallexample
@end defun

@deftp {Record} <time-result>
A record to hold the benchmark result.
Following slots are defined.

@defivar {<time-result>} count
@fnindex time-result-count
The number of times the thunk was run.   This slot is also
accessed by a procedure @code{time-result-count}.
@end defivar

@defivar {<time-result>} real
@fnindex time-result-real
The total real (elapsed) time running the thunk took.
This slot is also accessed by a procedure @code{time-result-real}.
@end defivar

@defivar {<time-result>} user
@fnindex time-result-user
The total user cpu time running the thunk took.
This slot is also accessed by a procedure @code{time-result-user}.
@end defivar

@defivar {<time-result>} sys
@fnindex time-result-sys
The total system cpu time running the thunk took.
This slot is also accessed by a procedure @code{time-result-sys}.
@end defivar
@end deftp

@defun make-time-result count real user sys
The constructor of @code{<time-result>} records.
@end defun

@defun time-result? obj
The predicate of @code{<time-result>} records.
@end defun

@defun time-result+ t1 t2 :key (with-count #f)
@defunx time-result- t1 t2 :key (with-count #f)
Add or subtract two @code{<time-result>} records and returns a new record.

If @var{with-count} is false,
only the real, user and sys slots are added or subtracted,
and the result's count slot is set to the same as @var{t1}'s count slot.
It is supposed to be used to calculate on measurement
from different chunk of code.

If @var{with-count} is true,
then the values of count slot is also added or subtracted.
It is supposed to calculate on
multiple benchmark results of the same code.
@end defun

@defun time-these how alist
@defunx time-these/report how alist
These procedures benchmarks multiple chunks of code to compare.

The @var{alist} argument must be the form of
@code{((key . thunk) @dots{})}, where @code{key} is a symbol
and @var{thunk} is a procedure taking no arguments.

The @var{how} argument is the same as @code{time-this}; that is,
either an integer for number of iterations, or a list
@code{(cpu @var{x})} to indicate @var{x} seconds of cpu time.

@code{time-these} runs benchmarks for each thunk in @var{alist}
using @code{time-this}, and returns the result in a list of
the form
@code{(@var{how} (@var{key1} . @var{result1}) (@var{key2} . @var{result2}) @dots{})},
where each @var{result} is a @code{<time-result>} object.

@code{time-these/report} outputs the benchmark results and
comparison matrix in human readable way to the current output port.

@smallexample
gosh> (time-these/report '(cpu 3.0)
        `((real1 . ,(cut expt 100 20))
          (real2 . ,(cut %expt 100 20))
          (imag  . ,(cut expt +100i 20))))
Benchmark: ran real1, real2, imag, each for at least 3.0 cpu seconds.
  real1: 3.312 real, 3.320 cpu (3.320 user + 0.000 sys)@@ 1694277.11/s n=5625000
  real2: 2.996 real, 3.010 cpu (3.010 user + 0.000 sys)@@35595634.55/s n=107142860
   imag: 3.213 real, 3.190 cpu (3.190 user + 0.000 sys)@@  862068.97/s n=2750000

              Rate  real1 real2   imag
  real1  1694277/s     -- 0.048  1.965
  real2 35595635/s 21.009    -- 41.291
   imag   862069/s  0.509 0.024     --
@end smallexample

The first part of the report shows, for each thunks,
the real (elapsed) time,
the cpu time used (and its breakdown of user and system time),
the rate of iteration per second, and the total number of iterations.

The second part compares the speed between each pair of the benchmarks.
For example, its first row tells that the benchmark @code{real1} is
0.048 times faster than @code{real2} and 1.965 times faster than
@code{imag}.
@end defun

@defun report-time-results result
This is a utility procedure to create a report from
the result of @code{time-these}.  Actually, @code{time-these/report}
is just a combination of @code{time-these} and this procedure:

@example
(define (time-these/report how samples)
  (report-time-results (time-these how samples)))
@end example
@end defun


@c EN
@subheading Finer measurement
@c JP
@subheading より細かい計測
@c COMMON

@deftp {Class} <time-counter>
@clindex time-counter
@c EN
An abstract class of time counters.  Time counter is a kind of timer
whose value is incremented as the time passes.  The counting
can be started and stopped any number of times.
The value of the counter can be read
when the timer is stopping.
You can have multiple time counters.  It is useful, for example,
to measure the time in two parts inside a loop independently.
@c JP
時間カウンタの抽象クラスです。時間カウンタは
時間の経過と共にその値が増加してゆく一種のタイマーです。
何度でもカウントを止めたり開始したりできます。
カウンタの値はカウントが止まっている時に読み出すことができます。
複数の時間カウンタを使えば、
例えばループ中の二つの部分について費される時間を別々に計測することもできます。
@c COMMON

@c EN
The concrete subclass determines which time it is counting.
You have to instantiate one of those subclasses described below
to use the time counter.
@c JP
具体的なサブクラスが、どの時間をカウントするかを決定します。
時間カウンタを使うには、下に挙げるサブクラスのいずれかを
インスタンシエイトしなければなりません。
@c COMMON
@end deftp

@deftp {Class} <real-time-counter>
@deftpx {Class} <user-time-counter>
@deftpx {Class} <system-time-counter>
@deftpx {Class} <process-time-counter>
@clindex real-time-counter
@clindex user-time-counter
@clindex system-time-counter
@clindex process-time-counter
@c EN
Classes for time counters that count real (elapsed) time, user-space CPU time,
kernel-space CPU time, and total CPU time (user + system), respectively.
@c JP
それぞれ、実経過時間、ユーザースペースCPU時間、カーネルスペースCPU時間、
総CPU時間 (ユーザー+カーネル)を計測する時間カウンタのクラスです。
@c COMMON
@end deftp

@deffn {Method} time-counter-start! (counter <time-counter>)
@deffnx {Method} time-counter-stop! (counter <time-counter>)
@c EN
Starts and stops the @var{counter}.  The time during the counter is
running is accumulated to the counter value when the counter is stopped.
@c JP
時間カウンタ@var{counter}を開始/停止します。カウンタが走っている間の時間が、
カウンタが停止した時点でカウンタの値に加算されます。
@c COMMON

@c EN
Start/stop pairs can be nested,
but only the outermost pair takes the effect.  That is, if you call
@code{time-counter-start!} on the counter that is already started,
it doesn't have any effect except that to stop such a counter
you have to call @code{time-counter-stop!} one more time.  It is useful
when you want to measure the time spent in the larger block that
may already contain timer start/stop pairs.
@c JP
開始/停止の対はネストすることができます。その場合は、一番外側の対のみが
有効です。
つまり、既に走っているカウンタに対し@code{time-counter-start!}を呼んでも
何も起こりませんが、一度余分に@code{time-counter-stop!}を呼ばないと
カウンタは止まりません。
これは、内部に既に開始/停止の対を含んでいるかもしれない大きなコードブロックの
全体の時間を計測したいというような場合に便利です。
@c COMMON

@c EN
Calling @code{time-counter-stop!} on the already stopped counter
has no effect.
@c JP
既に停止しているカウンタに対して@code{time-counter-stop!}を呼んでも
何も起こりません。
@c COMMON
@end deffn

@deffn {Method} time-counter-reset! (counter <time-counter>)
@c EN
Resets the value of @var{counter}.  If @var{counter} is already
running, it is forced to stop before being reset.
@c JP
カウンタ@var{counter}の値をリセットします。既に@var{counter}が走っている
場合は、リセットの前にカウンタは停止させられます。
@c COMMON
@end deffn

@deffn {Method} time-counter-value (counter <time-counter>)
@c EN
Returns the current value of the counter as the number of seconds,
in a real number.  The resolution depends on the source of the counter.
@c JP
カウンタ@var{counter}の現在の値(秒数)を実数で返します。
分解能はそれぞれのカウンタが用いているシステムコールに依存します。
@c COMMON
@end deffn

@defmac with-time-counter counter expr @dots{}
@c EN
A convenience macro to run the @var{counter} while @var{expr} @dots{}
are evaluated.  Returns the result(s) of the last expression.
It is defined as follows.
@c JP
式@var{expr} @dots{}が評価される間だけ@var{counter}を走らせる、
便利なマクロです。最後の式の結果を返します。このマクロは次のように
定義されます。
@c COMMON
@example
(define-syntax with-time-counter
  (syntax-rules ()
    ((_ counter . exprs)
     (dynamic-wind
      (lambda () (time-counter-start! counter))
      (lambda () . exprs)
      (lambda () (time-counter-stop! counter))))
    ))
@end example
@end defmac

@c EN
The following example measures approximate times
spend in process-A and process-B inside a loop.
@c JP
下の例では、ループ内でのprocess-Aとprocess-Bにて費された
概略の時間をそれぞれ計測します。
@c COMMON

@example
(let ((ta (make <real-time-counter>))
      (tb (make <real-time-counter>)))
  (dotimes (i 100000)
    (with-time-counter ta
      (process-A))
    (with-time-counter tb
      (process-B)))
  (format #t "Time spent in process-A: ~s\n" (time-counter-value ta))
  (format #t "Time spent in process-B: ~s\n" (time-counter-value tb))
  )
@end example


@c ----------------------------------------------------------------------
@node Uniform vectors, Comparing version numbers, Measure timings, Library modules - Gauche extensions
@section @code{gauche.uvector} - Uniform vectors
@c NODE ユニフォームベクタ, @code{gauche.uvector} - ユニフォームベクタ

@deftp {Module} gauche.uvector
@mdindex gauche.uvector
@c EN
Provides vectors whose elements are of the same numeric type,
as defined in SRFI-4 (@ref{srfi-4,,SRFI-4}).

Gauche's implementation is a superset of SRFI-4 in a few ways:
@itemize @bullet
@item
Some routines takes optional parameters: @code{@var{TAG}vector->list}
takes optional start and end indices, and @code{@var{TAG}vector-ref}
takes optional fallback value.
@item
Additional functions: copy procedures (@code{@var{TAG}vector-copy} and
@code{@var{TAG}vector-copy!}), conversion procedures
(@code{@var{TAG}vector->vector} and @code{vector->@var{TAG}vector}),
and some arithmetic functions (@code{@var{TAG}vector-add}, etc.)
@item
Implements the collection framework (@xref{Collection framework})
and the sequence framework (@xref{Sequence framework}).  So the
methods like @code{map}, @code{for-each}, @code{ref} or @code{subseq}
can be used on the SRFI-4 vector types.
@item
Support of @code{f16vector}, a vector of 16-bit floating point number
as used in high-dynamic range image format (1 sign bit, 5 exponent bits,
and 10 mantissa bits).
@end itemize
@c JP
SRFI-4(@ref{srfi-4,,SRFI-4})に定義されている、
要素が同一の数値型であるようなベクタを提供します。

Gaucheの実装は、SRFI-4の仕様を次のように拡張しています。
@itemize @bullet
@item
いくつかの手続きはSRFI-4に無い省略可能な引数を取ります。
@code{@var{TAG}vector->list}は省略可能なstartとendのインデックスを取り、
@code{@var{TAG}vector-ref}は省略可能なデフォルト値を取ります。
@item
追加の手続き： コピー(@code{@var{TAG}vector-copy},
@code{@var{TAG}vector-copy!})、
変換 (@code{@var{TAG}vector->vector}, @code{vector->@var{TAG}vector})、
及び各種算術演算(@code{@var{TAG}vector-add}等)。
@item
コレクションフレームワーク (@ref{Collection framework}参照)と
シーケンスフレームワーク (@ref{Sequence framework}参照)の実装。
例えば @code{map}, @code{for-each}, @code{ref}, @code{subseq}等の
メソッドがSRFI-4ベクタに対して使えます。
@item
16ビット浮動小数点数のベクタ@code{f16vector}のサポート。
フォーマットはハイダイナミックレンジイメージ等に使われている、
1符号ビット、5指数ビット、10仮数ビットです。
@end itemize
@c COMMON

@c EN
There are some advantages of using SRFI-4 vectors over normal
(heterogeneous) vectors.  It may be more compact than the normal
vectors.  Some operations (especially Gauche's extension of vector
arithmetic operations) can bypass type check and conversion of
individual elements, thus be more efficient.  And it is much easier
and efficient to communicate with external libraries that require
homogeneous array of numbers; for example, OpenGL binding of Gauche
uses SRFI-4 vectors extensively.
@c JP
通常のベクタではなくSRFI-4ベクタを使うことにより得られる利点がいくつかあります。
まず、SRFI-4ベクタは通常のベクタよりもコンパクトです。
いくつかのオペレーション(特に、Gaucheの拡張仕様であるベクタ上の数値演算)では、
型検査と型変換を個々の要素に対して行わなくても良いため、
極めて効率の良い演算が可能です。さらに、
数値の配列を扱う外部のライブラリとのインタフェースが容易です。
例えば、GaucheのOpenGLバインディングではSRFI-4ベクタを多用しています。
@c COMMON
@end deftp
@c EN
The following ten types of vectors are defined.
@table @emph
@item s8vector
Elements are exact integers in the range between -2^7 and 2^7-1
@item u8vector
Elements are exact integers in the range between 0 and 2^8-1
@item s16vector
Elements are exact integers in the range between -2^15 and 2^15-1
@item u16vector
Elements are exact integers in the range between 0 and 2^16-1
@item s32vector
Elements are exact integers in the range between -2^31 and 2^31-1
@item u32vector
Elements are exact integers in the range between 0 and 2^32-1
@item s64vector
Elements are exact integers in the range between -2^63 and 2^63-1
@item u64vector
Elements are exact integers in the range between 0 and 2^64-1
@item f16vector
Elements are inexact real numbers representable in 16bits float
(a.k.a half float)
@item f32vector
Elements are inexact real numbers representable in the @code{float} of
C compiler that compiles Gauche.  Usually it is a single precision
IEEE floating point number.
@item f64vector
Elements are inexact real numbers representable in the @code{double} of
C compiler that compiles Gauche.  Usually it is a double precision
IEEE floating point number.
@end table
@c JP
以下の10タイプのベクタが定義されます。
@table @emph
@item s8vector
要素が -2^7 から 2^7-1 の間の正確な整数であるベクタ
@item u8vector
要素が 0 から 2^8-1 の間の正確な整数であるベクタ
@item s16vector
要素が -2^15 から 2^15-1 の間の正確な整数であるベクタ
@item u16vector
要素が 0 から 2^16-1 の間の正確な整数であるベクタ
@item s32vector
要素が -2^31 から 2^31-1 の間の正確な整数であるベクタ
@item u32vector
要素が 0 から 2^32-1 の間の正確な整数であるベクタ
@item s64vector
要素が -2^63 から 2^63-1 の間の正確な整数であるベクタ
@item u64vector
要素が 0 から 2^64-1 の間の正確な整数であるベクタ
@item f16vector
要素が、16ビット浮動小数点数(half floatとしても知られている)で表現
し得るような不正確な実数であるベクタ
@item f32vector
要素が、GaucheをコンパイルしたCコンパイラの@code{float}で表現し得るような
不正確な実数(通常IEEE単精度浮動少数点数)であるベクタ
@item f64vector
要素が、GaucheをコンパイルしたCコンパイラの@code{double}で表現し得るような
不正確な実数(通常IEEE倍精度浮動少数点数)であるベクタ
@end table
@c COMMON

@c EN
When you try to store a number out of the range of the vector type,
an error is signalled by default.  However, some procedures take
an optional argument @var{clamp} that specifies alternative behavior
in such a case.  @var{Clamp} argument may take one of the following values.
@c JP
ベクタの型が許す範囲外の値を格納しようとした場合、通常はエラーとなります。
いくつかの手続きは省略可能な引数@var{clamp}によって、
そのような場合に別のふるまいを指定することができます。
@var{clamp}には以下のいずれかの値を与えることが出来ます。
@c COMMON
@table @code
@item #f
@c EN
Default behavior (signals an error).
@c JP
デフォルト (エラーを通知)
@c COMMON
@item high
@c EN
Clamps high bound; i.e. if the value to be stored is beyond the higher bound
of the range, the maximum value is stored instead.
@c JP
高い方の値をクランプ、すなわち、格納しようとする値が許される値の最大値より大きかった
場合は、可能な最大値を代わりに格納します。
@c COMMON
@item low
@c EN
Clamps low bound; i.e. if the value to be stored is below the lower bound
of the range, the minimum value is stored instead.
@c JP
低い方の値をクランプ、すなわち、格納しようとする値が許される値の最小値より大きかった
場合は、可能な最小値を代わりに格納します。
@c COMMON
@item both
@c EN
Clamps both sides; does both @code{high} and @code{low}.
@c JP
高いほうと低いほうの両方の値をクランプします。
@c COMMON
@end table

@example
(list->u8vector '(-1))         @result{} @r{error}
(list->u8vector '(-1) 'low)    @result{} #u8(0)
(list->u8vector '(-1) 'high)   @result{} @r{error}
(list->u8vector '(3000) 'high) @result{} #u8(255)
(list->u8vector '(-100 20 300) 'both) @result{} #u8(0 20 255)
@end example

@c EN
In the following description, @code{@var{TAG}} can be replaced
for any of @code{s8}, @code{u8}, @code{s16}, @code{u16}, 
@code{s32}, @code{u32}, @code{s64}, @code{u64}, 
@code{f16}, @code{f32}, @code{f64}.
@c JP
以下の記述では、@code{@var{TAG}}は
@code{s8}, @code{u8}, @code{s16}, @code{u16}, 
@code{s32}, @code{u32}, @code{s64}, @code{u64}, 
@code{f16}, @code{f32}, @code{f64}
のいずれにも置き換えて読むことができるものとします。
@c COMMON

@menu
* Uvector basic operations::    
* Uvector conversion operations::  
* Uvector numeric operations::  
* Uvector block I/O::           
@end menu

@node Uvector basic operations, Uvector conversion operations, Uniform vectors, Uniform vectors
@subsection Uvector basic operations
@c NODE ユニフォームベクタの基本操作

@deftp {Builtin Class} <@var{TAG}vector>
@clindex s8vector
@clindex u8vector
@clindex s16vector
@clindex u16vector
@clindex s32vector
@clindex u32vector
@clindex s64vector
@clindex u64vector
@clindex f16vector
@clindex f32vector
@clindex f64vector
@c EN
A class for @var{TAG}vector.  It inherits @code{<sequence>}.
@c JP
@var{TAG}vectorのクラス。@code{<sequence>}を継承します。
@c COMMON
@end deftp

@deftp {Reader Syntax} @code{#@var{TAG}(@var{n} @dots{})}
@c EN
Denotes a literal homogeneous vector.
@c JP
リテラルの単一型のベクタを記述します。
@c COMMON
@example
#s8(3 -2 4)
#u32(4154 88357 2 323)
#f32(3.14 0.554525 -3.342)
@end example
@end deftp

@deftp {Function} {@var{TAG}vector?} @r{@var{obj}}
@findex s8vector?
@findex u8vector?
@findex s16vector?
@findex u16vector?
@findex s32vector?
@findex u32vector?
@findex s64vector?
@findex u64vector?
@findex f16vector?
@findex f32vector?
@findex f64vector?
[SRFI-4]
@c EN
Returns @code{#t} if @var{obj} is a @var{TAG}vector, @code{#f} otherwise.
@c JP
@var{obj}が@var{TAG}vectorなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end deftp

@deftp {Function} {@var{TAG}vector} @r{@var{x} @dots{}}
@findex s8vector 
@findex u8vector
@findex s16vector
@findex u16vector
@findex s32vector
@findex u32vector
@findex s64vector
@findex u64vector
@findex f16vector
@findex f32vector
@findex f64vector
[SRFI-4]
@c EN
Constructs @var{TAG}vector whose elements are numbers @var{x} @dots{}.
The numbers must be exact integer for exact integer vectors, 
and in the valid range of the vector.
@c JP
数値@var{x} @dots{} を要素に持つ@var{TAG}vectorを作成して返します。
正確な整数のベクタに対しては、数値は正確な整数でなければならず、
また有効な範囲内の値でなければなりません。
@c COMMON
@example
(s8vector 1 2 3) @result{} #s8(1 2 3)
@end example
@end deftp

@deftp {Function} make-@var{TAG}vector @r{@var{len} @var{:optional} @var{fill}}
@findex make-s8vector
@findex make-u8vector
@findex make-s16vector
@findex make-u16vector
@findex make-s32vector
@findex make-u32vector
@findex make-s64vector
@findex make-u64vector
@findex make-f16vector
@findex make-f32vector
@findex make-f64vector
[SRFI-4]
@c EN
Constructs a @var{TAG}vector of length @var{len}.  The elements are
initialized by a number @var{fill}.   For exact integer vectors,
@var{fill} must be an exact integer and in the valid range.
If @var{fill} is omitted, the content of the vector is undefined.
@c JP
長さ@var{len}の@var{TAG}vectorを作成して返します。各要素は@var{fill}で
初期化されます。正確な整数のベクタに対しては、@var{fill}は正確な整数でなければならず、
また有効な範囲内の値でなければなりません。
@var{fill}が省略された場合、各要素の初期値は不定です。
@c COMMON
@example
(make-u8vector 4 0) @result{} #u8(0 0 0 0)
@end example
@end deftp

@deftp {Function} @var{TAG}vector-length @r{@var{vec}}
@findex s8vector-length 
@findex u8vector-length
@findex s16vector-length
@findex u16vector-length
@findex s32vector-length
@findex u32vector-length
@findex s64vector-length
@findex u64vector-length
@findex f16vector-length
@findex f32vector-length
@findex f64vector-length
[SRFI-4]
@c EN
Returns the length of the @var{TAG}vector @var{vec}.

Note that the generic function @code{size-of} can be used 
to obtain the length of @var{vec} as well,
if you import @code{gauche.collection}
(@xref{Collection framework}).
@c JP
@var{TAG}vector @var{vec}の長さを返します。

モジュール@code{gauche.collection}をインポートしていれば、
@var{vec}の長さを知るのに、総称関数@code{size-of}を使うこともできます
(@ref{Collection framework}参照)。
@c COMMON
@example
(s16vector-length '#s16(111 222 333)) @result{} 3

(use gauche.collection)
(size-of '#s16(111 222 333)) @result{} 3
@end example
@end deftp

@defun uvector-size uvector :optional start end
@c EN
This function can be applied to any type of uniform vectors, and
returns the raw size of the @var{uvector} in number of octets.

When @var{start} and/or @var{end} is/are given, the size of data
between those indices are calculated.  The special value @code{-1}
for @var{end} indicates the end of the vector.
The returned value matches the number of octets to be written out
by @code{(write-block @var{uvector} port @var{start} @var{end})}.
@c JP
この手続きは全てのユニフォームベクタに適用することができます。
@var{uvector}のバイナリデータとしてのサイズをオクテット数で返します。

@var{start}および/または@var{end}が与えられた場合は、
これらのインデックスの間のデータについてのみサイズが計算されます。
@var{end}には、ベクタ終端を示すために@code{-1}を与えることもできます。
返される値は
@code{(write-block @var{uvector} port @var{start} @var{end})} によって
出力されるオクテット数と一致します。
@c COMMON

@example
(uvector-size '#u8(1 2 3))        @result{} 3
(uvector-size '#u64(1 2 3))       @result{} 24

(uvector-size '#u32(0 1 2 3) 2)   @result{} 8
(uvector-size '#u32(0 1 2 3) 0 1) @result{} 4
@end example
@end defun

@deftp {Function} @var{TAG}vector-ref @r{@var{vec} @var{k} :optional @var{fallback}}
@findex s8vector-ref
@findex u8vector-ref
@findex s16vector-ref
@findex u16vector-ref
@findex s32vector-ref
@findex u32vector-ref
@findex s64vector-ref
@findex u64vector-ref
@findex f16vector-ref
@findex f32vector-ref
@findex f64vector-ref
[SRFI-4+]
@c EN
Returns the @var{k}-th element of @var{TAG}vector @var{vec}.

If the index @var{k} is out of the valid range, an error is signalled
unless an optional argument @var{fallback} is given; in that case,
@var{fallback} is returned.

Note that the generic function @code{ref} can be used as well,
if you import @code{gauche.collection}.
@c JP
@var{TAG}vector @var{vec}の@var{k}番目の要素を返します。

@var{k}が有効な範囲外であった場合、通常はエラーが通知されますが、
省略可能な引数@var{fallback}が与えられている場合はそれが返されます。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{ref}を使うこともできます。
@c COMMON

@example
(u16vector-ref '#u16(111 222 333) 1) @result{} 222

(use gauche.collection)
(ref '#u16(111 222 333) 1) @result{} 222
@end example
@end deftp

@deftp {Function} @var{TAG}vector-set! @r{@var{vec} @var{k} @var{n} :optional @var{clamp}}
@findex s8vector-set!
@findex u8vector-set!
@findex s16vector-set!
@findex u16vector-set!
@findex s32vector-set!
@findex u32vector-set!
@findex s64vector-set!
@findex u64vector-set!
@findex f16vector-set!
@findex f32vector-set!
@findex f64vector-set!
[SRFI-4+]
@c EN
Sets a number @var{n} to the @var{k}-th element of @var{TAG}vector @var{vec}.
Optional @var{clamp} argument specifies the behavior when
@var{n} is out of valid range.   Default is to signal an error.

Note that the setter of the generic function @code{ref} can be used as well,
if you import @code{gauche.collection}.
@c JP
@var{TAG}vector @var{vec}の@var{k}番目の要素に数値@var{n}をセットします。
省略可能な引数@var{clamp}が、@var{n}が正しい範囲外の数であった場合の動作を指定します。
デフォルトではエラーが通知されます。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{ref}のsetter手続きを使うこともできます。
@c COMMON
@example
(let ((v (s32vector -439 852 8933)))
  (s32vector-set! v 1 4)
  v)
 @result{} #s32vector(-439 4 8933)

(use gauche.collection)
(let ((v (s32vector -439 852 8933)))
  (set! (ref v 1) 4)
  v)
 @result{} #s32vector(-439 4 8933)
@end example
@end deftp

@deftp {Function} @var{TAG}vector-fill! @r{@var{vec} @var{fill} :optional @var{start} @var{end}}
@findex s8vector-fill!
@findex u8vector-fill!
@findex s16vector-fill!
@findex u16vector-fill!
@findex s32vector-fill!
@findex u32vector-fill!
@findex s64vector-fill!
@findex u64vector-fill!
@findex f16vector-fill!
@findex f32vector-fill!
@findex f64vector-fill!
@c EN
Stores @var{fill} in every element of @var{vec},
ranging from @var{start} to @var{end} of @var{vec},
if they are given. 
@c JP
@var{vec}のすべて要素に@var{fill}をセットします。
@var{start}と@var{end}で要素の範囲を指定することも出来ます。
@c COMMON
@end deftp

@deftp {Function} @var{TAG}vector-copy @r{@var{vec} :optional @var{start} @var{end}}
@findex s8vector-copy
@findex u8vector-copy
@findex s16vector-copy
@findex u16vector-copy
@findex s32vector-copy
@findex u32vector-copy
@findex s64vector-copy
@findex u64vector-copy
@findex f16vector-copy
@findex f32vector-copy
@findex f64vector-copy
@c EN
Copies the srfi-4 vector @var{vec}.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be copied.
@c JP
ベクタ@var{vec}をコピーします。
省略可能な引数@var{start}と@var{end}が与えられた場合、
それらは取り出される要素の範囲を制限します。
@c COMMON

@example
(u8vector-copy '#u8(1 2 3 4))     @result{} #u8(1 2 3 4)
(u8vector-copy '#u8(1 2 3 4) 2)   @result{} #u8(3 4)
(u8vector-copy '#u8(1 2 3 4) 1 3) @result{} #u8(2 3)
@end example
@end deftp

@deftp {Function} @var{TAG}vector-copy! @r{@var{target} @var{tstart} @var{source} :optional @var{sstart} @var{send}}
@findex s8vector-copy!
@findex u8vector-copy!
@findex s16vector-copy!
@findex u16vector-copy!
@findex s32vector-copy!
@findex u32vector-copy!
@findex s64vector-copy!
@findex u64vector-copy!
@findex f16vector-copy!
@findex f32vector-copy!
@findex f64vector-copy!
@c EN
Both @var{target} and @var{source} must be @i{TAG}vectors, and
@var{target} must be mutable.
This procedure copies the elements of @var{source}, beginning from index
@var{sstart} (inclusive) and up to @var{send}, into @var{target},
beginning from index @var{tstart}.  @var{sstart} and @var{send}
may be omitted, and in that case 0 and the length of @var{source}
are assumed, respectively.
@c JP
@var{target} および @var{source} はともに @i{TAG}vector でなければ
なりません。さらに、@var{target} は変更可能でなければなりません。
この手続きは、@var{source}の要素を、インデックス@var{sstart}から(これを含み)
@var{send} までを、@var{target} へインデックス @var{tstart}からコピーします。
@var{sstart}および@var{send}は省略可能で、その場合には、それぞれ、
0 および @var{source}の長さが仮定されます。
@c COMMON

@example
(let ((target (u8vector 0 1 2 3 4 5 6)))
  (u8vector-copy! target 2 '#u8(10 11 12 13 14) 1 4)
  target)
 @result{} #u8(0 1 11 12 13 6)
@end example

@c EN
If the number of elements in the source vector between @var{sstart}
and @var{send} is larger than the target vector beginning from @var{tstart},
the excess elements are silently discarded.
@c JP
もし、コピー元のベクタの @var{sstart} と @var{send} の間にある要素の
数がコピー先のベクタの@var{tstart}以降の部分よりも大きければ、超過分の
ベクタはだまって捨てられます。
@c COMMON

@c EN
@emph{Note:} This procedure used to take just two uniform vectors, @var{target}
and @var{source}, and just copies contents of @var{source} to @var{target}.
Both vectors had to be the same type and same length.  The API is revised
to the current form to make it parallel with @code{string-copy!} (SRFI-13)
and @code{vector-copy!} (SRFI-43).  The old interface is still supported
for the backward compatibility, but it is deprecated and will be gone
in the future releases.
@c JP
@emph{注意事項:} この手続きは以前はユニフォームベクタ @var{target} および
@var{source} のみを引数としてとり、@var{source} の内容を @var{target} へ
コピーするためだけに使われました。両方のベクタは同じ型で、同じ長さでなけ
ればなりませんでした。この API は @code{string-copy!} (SRFI-13) および
@code{vector-copy!} (SRFI-43)にあわせて現在の形式に改訂されています。
旧来のインタフェースもバックワードコンパチビリティのためにサポートされて
いますが、これは廃止予定で、将来のリリースではサポートされなくなります。
@c COMMON
@end deftp

@c EN
Using collection and sequence framework, you can perform
various operations on the homogeneous vectors.
@c JP
コレクションやシーケンスフレームワークを使うと、さらに様々な操作を
行うことができます。
@c COMMON

@example
(use gauche.collection)
(use gauche.sequence)

(fold + 0 '#s32(1 2 3 4)) @result{} 10

(map-to <f32vector> * '#f32(3.2 1.1 4.3) '#f32(-4.3 2.2 9.4))
  @result{} #f32(-13.760001 2.420000 40.420002)

(subseq #u32(1 4 3 4 5) 2 4) @result{} #u32(3 4)
@end example


@defun uvector-copy! target tstart source :optional sstart send
@c EN
This is a generic version of @code{@i{TAG}vector-copy!}.  
The destination @var{target} and the source @var{source} can be
any type of uniform vectors, and they don't need to match.
The copy is done bit-by-bit.  So if you copy to a different type
of uvector, the result depends on how the numbers are represented
internally.  This is mainly to manipulate binary data.

@var{Tstart} is interpreted according to the type of @var{target},
and @var{sstart} and @var{send} are interpreted according to the
type of @var{source}.
@c JP
これは@code{@i{TAG}vector-copy!}の汎用バージョンです。
コピー元@var{source}とコピー先@var{target}はユニフォームベクタであれば
どの型でも許され、また両者の型が異なっていても構いません。
ビット表現がそのままコピーされます。従って異なる型のユニフォームベクタ間で
コピーした場合は、結果は数値の内部表現に依存します。
そのような用法は、バイナリデータを扱う時には便利でしょう。

@var{tstart}は@var{target}の型によって解釈され、
@var{sstart}と@var{send}は@var{source}の型によって解釈されます。
@c COMMON

@example
(rlet1 v (make-u8vector 6 0)
  (uvector-copy! v 1 '#u32(0 #x01020304 0) 1 2))
 @result{} #u8(0 1 2 3 4 0) or #u8(0 4 3 2 1 0)
@end example
@end defun



@node Uvector conversion operations, Uvector numeric operations, Uvector basic operations, Uniform vectors
@subsection Uvector conversion operations
@c NODE ユニフォームベクタの変換

@deftp {Function} @var{TAG}vector->list @r{@var{vec} :optional @var{start} @var{end}}
@findex s8vector->list
@findex u8vector->list
@findex s16vector->list
@findex u16vector->list
@findex s32vector->list
@findex u32vector->list
@findex s64vector->list
@findex u64vector->list
@findex f16vector->list
@findex f32vector->list
@findex f64vector->list
[SRFI-4+]
@c EN
Converts @var{TAG}vector @var{vec} to a list.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be extracted.

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@c JP
@var{TAG}vector @var{vec}をリストに変換します。
省略可能な引数@var{start}と@var{end}が与えられた場合、
それらは取り出される要素の範囲を制限します。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{coerce-to}を使うこともできます。
@c COMMON
@example
(u32vector->list '#u32(9 2 5)) @result{} (9 2 5)

(use gauche.collection)
(coerce-to <list> '#u32(9 2 5)) @result{} (9 2 5)
@end example
@end deftp

@deftp {Function} @var{TAG}vector->vector @r{@var{vec} :optional @var{start} @var{end}}
@findex s8vector->vector
@findex u8vector->vector
@findex s16vector->vector
@findex u16vector->vector
@findex s32vector->vector
@findex u32vector->vector
@findex s64vector->vector
@findex u64vector->vector
@findex f16vector->vector
@findex f32vector->vector
@findex f64vector->vector
@c EN
Converts @var{TAG}vector @var{vec} to a vector.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be copied.

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@c JP
@var{TAG}vector @var{vec}をベクタに変換します。
省略可能な引数@var{start}と@var{end}が与えられた場合、
それらは取り出される要素の範囲を制限します。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{coerce-to}を使うこともできます。
@c COMMON
@example
(f32vector->vector '#f32(9.3 2.2 5.5))   @result{} #(9.3 2.2 5.5)
(f32vector->vector '#f32(9.3 2.2 5.5) 2) @result{} #(5.5)

(use gauche.collection)
(coerce-to <vector> '#f32(9.3 2.2 5.5)) @result{} #(9.3 2.2 5.5)
@end example
@end deftp

@deftp {Function} list->@var{TAG}vector @r{@var{list} :optional @var{clamp}}
@findex list->s8vector
@findex list->u8vector
@findex list->s16vector
@findex list->u16vector
@findex list->s32vector
@findex list->u32vector
@findex list->s64vector
@findex list->u64vector
@findex list->f16vector
@findex list->f32vector
@findex list->f64vector
[SRFI-4+]
@c EN
Converts a list @var{list} to a @var{TAG}vector.
Optional argument @var{clamp} specifies the behavior when
the element of @var{list} is out of the valid range.

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@c JP
リスト@var{list}を@var{TAG}vectorに変換します。
省略可能な引数@var{clamp}が、リスト内の要素が正しい範囲外の数であった場合の
動作を指定します。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{coerce-to}を使うこともできます。
@c COMMON
@example
(list->s64vector '(9 2 5)) @result{} #s64(9 2 5)

(use gauche.collection)
(coerce-to <s64vector> '(9 2 5)) @result{} #s64(9 2 5)
@end example
@end deftp

@deftp {Function} vector->@var{TAG}vector @r{@var{vec} :optional @var{start} @var{end} @var{clamp}}
@findex vector->s8vector
@findex vector->u8vector
@findex vector->s16vector
@findex vector->u16vector
@findex vector->s32vector
@findex vector->u32vector
@findex vector->s64vector
@findex vector->u64vector
@findex vector->f16vector
@findex vector->f32vector
@findex vector->f64vector
@c EN
Converts a vector @var{vec} to a @var{TAG}vector.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be copied.
Optional argument @var{clamp} specifies the behavior when
the element of @var{vec} is out of the valid range.

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@c JP
ベクタ@var{vec}を@var{TAG}vectorに変換します。
省略可能な引数@var{start}と@var{end}が与えられた場合、
それらは取り出される要素の範囲を制限します。
省略可能な引数@var{clamp}が、ベクタ内の要素が正しい範囲外の数であった場合の
動作を指定します。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{coerce-to}を使うこともできます。
@c COMMON
@example
(vector->f64vector '#(3.1 5.4 3.2)) @result{} #f64(3.1 5.4 3.2)

(use gauche.collection)
(coerce-to <f64vector> '#(3.1 5.4 3.2)) @result{} #f64(3.1 5.4 3.2)
@end example
@end deftp

@defun string->s8vector string :optional start end
@defunx string->u8vector string :optional start end
@c EN
Returns an s8vector or u8vector whose byte sequence is the same
as the internal representation of the given string.
Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} inside @var{string} to be
converted.

These procedures are useful when you want to access byte
sequence of the string randomly.
@c JP
与えられた文字列の内部表現のバイト列と同じバイト列を持つs8vectorもしくは
u8vectorを返します。省略可能な範囲引数@var{start}、@var{end}は、
変換される文字列中の文字位置を指定します。

これらの手続きは、文字を構成するバイト列をランダムにアクセスしたい場合などに
有用です。
@c COMMON

@example
(string->u8vector "abc") @result{} #u8(97 98 99)

@c JP
;; 内部コードがEUCの場合
(string->u8vector "いろは") @result{} #u8(164 164 164 237 164 207)
@c COMMON
@end example
@end defun

@defun string->s8vector! target tstart string :optional start end
@defunx string->u8vector! target tstart string :optional start end
@c EN
@var{Target} must be an s8vector or a u8vector, respectively.
@var{Target} must be mutable.
Like copies the raw byte representation of @var{string}
into @var{target} beginning from index @var{tstart}.
@c JP
@var{target} は、それぞれ s8vector あるいは u8vector でなければなりません。
@var{target} は、変更可能でなければなりません。
@var{string} の生バイト表現を @var{target} へインデックス @var{tstart}
からコピーします。
@c COMMON

@c EN
Returns @var{target}.
@c JP
@var{target} を返します。
@c COMMON

@example
(let ((target (make-u8vector 10 0)))
  (string->u8vector! target 3 "abcde"))
 @result{} #u8(0 0 0 97 98 99 100 101 0 0)
@end example

@end defun

@defun s8vector->string vec :optional start end
@defunx u8vector->string vec :optional start end
@c EN
Converts a byte sequence in s8vector or u8vector to a string that
has the same byte sequence.  Optional range arguments @var{start} and
@var{end} specifies the byte position in @var{vec} to be converted.

Note that these procedure may result an incomplete string if
@var{vec} contains a byte sequence invalid as the internal encoding
of the string.
@c JP
与えられたs8vectorもしくはu8vector @var{vec}のバイト列と同じ内部バイト列を
持つ文字列を作成して返します。省略可能な範囲引数@var{start}、@var{end}は、
@var{vec}中の変換されるべき範囲をバイト位置で指定します。

@var{vec}中のバイト列が文字列の内部表現として不正な値を持っていた場合は、
不完全な文字列が返されます。
@c COMMON
@end defun

@defun string->s32vector string :optional start end
@defunx string->u32vector string :optional start end
@c EN
Returns an s32vector or u32vector whose elements are
the internal codes of the characters in the string.
Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} inside @var{string} to be
converted.

These procedures are useful when you want to access
the characters in the string randomly.
@c JP
与えられた文字列@var{string}の各文字の内部コードを値として持つ
s32vectorもしくはu32vectorを返します。
省略可能な範囲引数@var{start}、@var{end}は、
変換される文字列中の文字位置を指定します。

これらの手続きは、文字列中の文字をランダムにアクセスする場合に便利です。
@c COMMON
@end defun

@defun s32vector->string vec :optional start end
@defunx u32vector->string vec :optional start end
@c EN
Without @var{start} and @var{end}, these procedures work like this:
@c JP
@var{start}と@var{end}を考えなければ、
これらの手続きは次のコードのような動作をします：
@c COMMON
@example
(lambda (vec) (map-to <string> integer->char vec)))
@end example
@c EN
Optional range arguments @var{start} and @var{end} limits
the range of conversion between them.
@c JP
省略可能な範囲引数@var{start}、@var{end}は、
@var{vec}中の変換されるべき範囲を指定します。
@c COMMON
@end defun

@defun uvector-alias uvector-class vec :optional start end
@c EN
This procedure creates an uvector of class @var{uvector-class}
that shares the storage of the given uniform vector @var{vec}.
If optional @var{start} and @var{end} arguments are given,
only the specified range of @var{vec} is used for the new vector.
Since the storage is shared, modification of the original vector
can be seen from the new vector, or vice versa.
@c JP
この手続きは、クラスが@var{uvector-class}であり、
ユニフォームベクタ@var{vec}のメモリ領域を共有するような
新しいユニフォームベクタを作成して返します。
省略可能な引数@var{start}と@var{end}が与えられた場合は
@var{vec}の内容のうちそれらのインデックスで指定される範囲のみが使われます。
メモリ領域が共有されているので、@var{vec}に加える変更は
新しいベクタから見えますし、その逆も可能です。
@c COMMON

@c EN
The class @var{uvector-class} must be either one of the uniform
vector class, but is not necessary match the class of the
source vector @var{vec}.   In such case, the new vector looks at the same
region of @var{vec}'s memory, but interprets it differently.
For example, the following code determines whether Gauche
is running on big-endian or little-endian machine:
@c JP
クラス@var{uvector-class}はユニフォームベクタのクラスでなければなりませんが、
@var{vec}のクラスと一致している必要はありません。
そのような場合は、新しいベクタは@var{vec}と同じメモリ領域の値を
異なる値と解釈するかもしれません。
例えば、次のコードはGaucheが走っているマシンが
リトルエンディアンであるかビッグエンディアンであるかを判定します。
@c COMMON

@example
(let ((u8v (uvector-alias <u8vector> #u32(1))))
  (if (zero? (u8vector-ref u8v 0))
      'big-endian 
      'little-endian))
@end example

@c EN
If the @var{uvector-class} is other than s8vector or u8vector,
the region the new vector points has to meet the alignment
requirement.  You can assume the beginning of the source vector
is aligned suitable for any uniform vectors.  So, for example,
if you're creating u32vector from u8vector, the @var{start} and
@var{end} must be multiple of 4 (or, if they're omitted, the length
of the original u8vector must be multiple of 4).
An error is signalled when the given parameters doesn't satisfy
alignment constraint.
@c JP
@var{uvector-class}がs8vectorかu8vector以外の場合、
新しいベクタが指す領域は、そのベクタの要素のアラインメントの要請に
したがっていなければなりません。
ユニフォームベクタの開始点は常に全てのユニフォームベクタのアラインメント要請を
満たします。したがって、例えばu8vectorからu32vectorを作成する場合、
@var{start}および@var{end}は4の倍数でなければなりません
(あるいは、@var{start}/@var{end}が省略された場合、@var{vec}の長さが
4の倍数でなければなりません)。
与えられたパラメータでアラインメントの要請が満たせない場合はエラーが通知されます。
@c COMMON
@end defun


@node Uvector numeric operations, Uvector block I/O, Uvector conversion operations, Uniform vectors
@subsection Uvector numeric operations
@c NODE ユニフォームベクタの数値演算

@deftp {Function} @var{TAG}vector-add @r{@var{vec} @var{val} :optional @var{clamp}}
@deftpx {Function} @var{TAG}vector-add! @r{@var{vec} @var{val} :optional @var{clamp}}
@deftpx {Function} @var{TAG}vector-sub @r{@var{vec} @var{val} :optional @var{clamp}}
@deftpx {Function} @var{TAG}vector-sub! @r{@var{vec} @var{val} :optional @var{clamp}}
@deftpx {Function} @var{TAG}vector-mul @r{@var{vec} @var{val} :optional @var{clamp}}
@deftpx {Function} @var{TAG}vector-mul! @r{@var{vec} @var{val} :optional @var{clamp}}
@findex s8vector-add
@findex s8vector-add!
@findex s8vector-sub
@findex s8vector-sub!
@findex s8vector-mul
@findex s8vector-mul!
@findex u8vector-add
@findex u8vector-add!
@findex u8vector-sub
@findex u8vector-sub!
@findex u8vector-mul
@findex u8vector-mul!
@findex s16vector-add
@findex s16vector-add!
@findex s16vector-sub
@findex s16vector-sub!
@findex s16vector-mul
@findex s16vector-mul!
@findex u16vector-add
@findex u16vector-add!
@findex u16vector-sub
@findex u16vector-sub!
@findex u16vector-mul
@findex u16vector-mul!
@findex s32vector-add
@findex s32vector-add!
@findex s32vector-sub
@findex s32vector-sub!
@findex s32vector-mul
@findex s32vector-mul!
@findex u32vector-add
@findex u32vector-add!
@findex u32vector-sub
@findex u32vector-sub!
@findex u32vector-mul
@findex u32vector-mul!
@findex s64vector-add
@findex s64vector-add!
@findex s64vector-sub
@findex s64vector-sub!
@findex s64vector-mul
@findex s64vector-mul!
@findex u64vector-add
@findex u64vector-add!
@findex u64vector-sub
@findex u64vector-sub!
@findex u64vector-mul
@findex u64vector-mul!
@findex f16vector-add
@findex f16vector-add!
@findex f16vector-sub
@findex f16vector-sub!
@findex f16vector-mul
@findex f16vector-mul!
@findex f32vector-add
@findex f32vector-add!
@findex f32vector-sub
@findex f32vector-sub!
@findex f32vector-mul
@findex f32vector-mul!
@findex f64vector-add
@findex f64vector-add!
@findex f64vector-sub
@findex f64vector-sub!
@findex f64vector-mul
@findex f64vector-mul!
@c EN
Element-wise arithmetic.  @var{Vec} must be a @var{TAG}vector,
and @var{val} must be either a @var{TAG}vector, a vector, or a list
of the same length as @var{vec}, or a number
(an exact integer for integer vectors, 
and a real number for f32- and f64-vectors).
@c JP
要素毎の計算手続きです。@var{vec}は@var{TAG}vectorでなければなりません。
また、@var{val}は@var{vec}と同じ長さの@var{TAG}vectorかベクタかリスト、
あるいは数値(整数ベクタに対しては正確な整数、実数ベクタに対しては実数)
でなければなりません。
@c COMMON

@c EN
If @var{val} is a @var{TAG}vector, its elements are 
added to, subtracted from, or multiplied by the corresponding
elements of @var{vec}, respectively,
and the results are gathered to a @var{TAG}vector 
and returned.  The destructive version (those have bang `!' in the name)
reuses @var{vec} to store the result.
If the result of calculation goes out of the range of @var{TAG}vector's
element, the behavior is specified by @var{clamp} optional argument.
(For f32vector and f64vector, @var{clamp} argument is ignored and
the result may contain infinity).
@c JP
@var{val}が@var{TAG}vectorの場合、
@var{vec}と対応する要素毎に加算、減算、乗算が行われ、
結果が@var{TAG}vectorとして返されます。
破壊的なバージョン(名前に`!'がついているもの)では、@var{vec}が
結果を格納するために再利用されます。
演算の結果が@var{TAG}vectorの要素の値域外になった場合の動作は
省略可能な引数@var{clamp}によって指定されます。
(f32vectorとf64vectorでは、値域外になった要素にはinfinityが格納され、
@var{clamp}の値は無視されます)。
@c COMMON

@c EN
If @var{val} is a number, it is added to, subtracted from, or
multiplied by each element of @var{vec}, respectively.
@c JP
@var{val}が数値である場合、@var{vec}の各要素とその数値の間で演算が行われます。
@c COMMON

@example
(s8vector-add '#s8(1 2 3 4) '#s8(5 6 7 8)) @result{} #s8(6 8 10 12)
(u8vector-sub '#u8(1 2 3 4) '#u8(2 2 2 2)) @result{} @r{error}
(u8vector-sub '#u8(1 2 3 4) '#u8(2 2 2 2) 'both) @result{} #u8(0 0 1 2)

(f32vector-mul '#f32(3.0 2.0 1.0) 1.5) @result{} #f32(4.5 3.0 1.5)
@end example
@end deftp

@deftp {Function} @var{TAG}vector-div @r{@var{vec} @var{val}}
@deftpx {Function} @var{TAG}vector-div! @r{@var{vec} @var{val}}
@findex f16vector-div
@findex f16vector-div!
@findex f32vector-div
@findex f32vector-div!
@findex f64vector-div
@findex f64vector-div!
@c EN
Element-wise division of flonum vectors.   These are only defined
for f16, f32 and f64vector.  @var{val} must be a @var{TAG}vector,
a vector or a list of the same length as @var{vec}, or a real number.
@c JP
要素毎の除算です。これらはf32vectorとf64vectorのみに対して定義されます。
@var{val}は@var{vec}と同じ大きさの@var{TAG}vectorかベクタかリスト、
あるいは実数でなければなりません。
@c COMMON

@example
(f32vector-div '#f32(1.0 2.0 3.0) 2.0) @result{} #f32(0.5 1.0 1.5)
@end example
@end deftp


@deftp {Function} @var{TAG}vector-and @r{@var{vec} @var{val}}
@deftpx {Function} @var{TAG}vector-and! @r{@var{vec} @var{val}}
@deftpx {Function} @var{TAG}vector-ior @r{@var{vec} @var{val}}
@deftpx {Function} @var{TAG}vector-ior! @r{@var{vec} @var{val}}
@deftpx {Function} @var{TAG}vector-xor @r{@var{vec} @var{val}}
@deftpx {Function} @var{TAG}vector-xor! @r{@var{vec} @var{val}}
@findex s8vector-and
@findex s8vector-and!
@findex s8vector-ior
@findex s8vector-ior!
@findex s8vector-xor
@findex s8vector-xor!
@findex u8vector-and
@findex u8vector-and!
@findex u8vector-ior
@findex u8vector-ior!
@findex u8vector-xor
@findex u8vector-xor!
@findex s16vector-and
@findex s16vector-and!
@findex s16vector-ior
@findex s16vector-ior!
@findex s16vector-xor
@findex s16vector-xor!
@findex u16vector-and
@findex u16vector-and!
@findex u16vector-ior
@findex u16vector-ior!
@findex u16vector-xor
@findex u16vector-xor!
@findex s32vector-and
@findex s32vector-and!
@findex s32vector-ior
@findex s32vector-ior!
@findex s32vector-xor
@findex s32vector-xor!
@findex u32vector-and
@findex u32vector-and!
@findex u32vector-ior
@findex u32vector-ior!
@findex u32vector-xor
@findex u32vector-xor!
@findex s64vector-and
@findex s64vector-and!
@findex s64vector-ior
@findex s64vector-ior!
@findex s64vector-xor
@findex s64vector-xor!
@findex u64vector-and
@findex u64vector-and!
@findex u64vector-ior
@findex u64vector-ior!
@findex u64vector-xor
@findex u64vector-xor!
@c EN
Element-wise logical (bitwise) operation.
These procedures are only defined for integral vectors.
@var{val} must be a @var{TAG}vector, a vector or a list
of the same length as @var{vec},
or an exact integer.  Bitwise and, inclusive or or exclusive or
is calculated between each element in @var{vec} and the corresponding
element of @var{val} (when @var{val} is a non-scalar value),
or @var{val} itself (when @var{val} is an integer).
The result is returned in a @var{TAG}vector.
The destructive version reuses @var{vec} to store the result.
@c JP
要素毎の論理(ビット)演算です。
これらの手続きは整数ベクタに対してのみ定義されています。
@var{val}は@var{vec}と同じ大きさの@var{TAG}vectorかベクタかリスト、
あるいは正確な整数でなければなりません。@var{vec}の各要素と、対応する@var{val}の要素
(@var{val}が非スカラー値の場合)もしくは@var{val}自身
(@var{val}が整数の場合)とのビット毎のand, inclusive orまたはexclusive or
が計算され、結果が@var{TAG}vectorで返されます。
破壊的なバージョン(名前に`!'がついているもの)では、@var{vec}が
結果を格納するために再利用されます。
@c COMMON
@end deftp

@deftp {Function} @var{TAG}vector-dot @r{@var{vec0} @var{vec1}}
@findex s8vector-dot
@findex s16vector-dot
@findex s32vector-dot
@findex s64vector-dot
@findex u8vector-dot
@findex u16vector-dot
@findex u32vector-dot
@findex u64vector-dot
@findex f16vector-dot
@findex f32vector-dot
@findex f64vector-dot
@c EN
Calculates the dot product of two @var{TAG}vectors.
The length of @var{vec0} and @var{vec1} must be the same.
@c JP
ふたつの@var{TAG}vectorの内積を計算します。
@var{vec0}と@var{vec1}の長さは等しくなければなりません。
@c COMMON
@end deftp

@deftp {Function} @var{TAG}vector-range-check @r{@var{vec} @var{min} @var{max}}
@findex s8vector-range-check
@findex s16vector-range-check
@findex s32vector-range-check
@findex s64vector-range-check
@findex u8vector-range-check
@findex u16vector-range-check
@findex u32vector-range-check
@findex u64vector-range-check
@findex f16vector-range-check
@findex f32vector-range-check
@findex f64vector-range-check
@c EN
@var{Vec} must be a @var{TAG}vector, and each of @var{min} and @var{max}
must be either a @var{TAG}vector, a vector or a list of the same length
as @var{vec}, or a number, or @code{#f}.

For each element in @var{vec}, this procedure checks if the value
is between @var{minval} and @var{maxval} inclusive, where
@var{minval} and @var{maxval} are the corresponding values of
@var{min} and @var{max} (when @var{min} and/or @var{max} is/are
non-scalar value) or @var{min} and @var{max} themselves (when
@var{min} and/or @var{max} is/are a number).
When @var{min} is @code{#f}, negative infinity is assumed.
When @var{max} is @code{#f}, positive infinity is assumed.

If all the elements in @var{vec} are within the range, @code{#f} is
returned.  Otherwise, the index of the leftmost element of @var{vec}
that is out of range is returned.
@c JP
@var{vec}は@var{TAG}vectorでなければなりません。
@var{min}と@var{max}はそれぞれ、@var{vec}と同じ長さの@var{TAG}vector、
ベクタ、リストのいずれかか、実数もしくは@code{#f}でなければなりません。

@var{vec}の各要素に対して、この手続きはそれが対応する@var{minval}と@var{maxval}
の間にあるかどうかを検査します。@var{minval}と@var{maxval}も範囲に含みます。
ここで、@var{minval}と@var{maxval}は、@var{min}/@var{max}が非スカラー値
であれば@var{vec}の要素に対応するそれぞれの要素、
@var{min}/@var{max}が数値であればその数値そのものです。
@var{min}が@code{#f}の場合、最小値はマイナス無限大と考えられます。
@var{max}が@code{#f}の場合、最大値はプラス無限大と考えられます。

@var{vec}の全ての要素が範囲内であった場合は@var{#f}が返されます。
そうでなければ、範囲を外れた要素のうちもっとも左のものの@var{vec}内での
インデックスが返されます。
@c COMMON

@example
(u8vector-range-check '#u8(3 1 0 2) 0 3)  @result{} #f
(u8vector-range-check '#u8(3 1 0 2) 1 3)  @result{} 2

(u8vector-range-check '#u8(4 32 64 98) 0 '#u8(10 40 70 90))
  @result{} 3

;; Range check in a program
(cond
 ((u8vector-range-check u8v 1 31)
  => (lambda (i)
      (errorf "~sth vector element is out of range: ~s"
              i (u8vector-ref u8v i))))
 (else (do-something u8v)))
@end example
@end deftp

@deftp {Function} @var{TAG}vector-clamp @r{@var{vec} @var{min} @var{max}}
@deftpx {Function} @var{TAG}vector-clamp! @r{@var{vec} @var{min} @var{max}}
@findex s8vector-clamp
@findex s16vector-clamp
@findex s32vector-clamp
@findex s64vector-clamp
@findex u8vector-clamp
@findex u16vector-clamp
@findex u32vector-clamp
@findex u64vector-clamp
@findex f32vector-clamp
@findex f64vector-clamp
@findex s8vector-clamp!
@findex s16vector-clamp!
@findex s32vector-clamp!
@findex s64vector-clamp!
@findex u8vector-clamp!
@findex u16vector-clamp!
@findex u32vector-clamp!
@findex u64vector-clamp!
@findex f16vector-clamp!
@findex f32vector-clamp!
@findex f64vector-clamp!
@c EN
@var{Vec} must be a @var{TAG}vector, and each of @var{min} and @var{max}
must be either a @var{TAG}vector, a vector or a list of the same length
as @var{vec}, or a number, or @code{#f}.

Like @var{TAG}vector-range-check, these procedures check if
each element of @var{vec} are within the range between @var{minval}
and @var{maxval} inclusive, which are derived from @var{min} and @var{max}.
If the value is less than @var{minval}, it is replaced by @var{minval}.
If the value is grater than @var{maxval}, it is replaced by @var{maxval}.

@var{TAG}vector-clamp creates a copy of @var{vec} and do clamp
operation on it, while @var{TAG}vector-clamp! modifies @var{vec}.
Both return the clamped vector.
@c JP
@var{vec}は@var{TAG}vectorでなければなりません。
@var{min}と@var{max}はそれぞれ、@var{vec}と同じ長さの@var{TAG}vector、
ベクタ、リストのいずれかか、実数もしくは@code{#f}でなければなりません。

@var{TAG}vector-range-checkと同じように、この手続きは@var{vec}の各要素が
@var{min}および@var{max}で指定される最小値と最大値の間にあるかどうかを
検査します。要素が最小値より小さかった場合はそれが最小値に置き換えられます。
要素が最大値より大きかった場合はそれが最大値に置き換えられます。

@var{TAG}vector-clampは@var{vec}のコピーを作ってそれに対して
クランプ操作を行います。@var{TAG}vector-clamp!は@var{vec}を直接
変更します。どちらもクランプ操作が行われた後の@var{TAG}vectorを返します。
@c COMMON

@example
(s8vector-clamp '#s8(8 14 -3 -22 0) -10 10) @result{} #s8(8 10 -3 -10 0)
@end example
@end deftp

@node Uvector block I/O,  , Uvector numeric operations, Uniform vectors
@subsection Uvector block I/O
@c NODE ユニフォームベクタのブロック入出力

@c EN
A uniform vector can be seen as an abstraction of a chunk of memory.
So you might want to use it for binary I/O.  Yes, you can do it.
@c JP
ユニフォームベクタは、メモリの固まりを抽象化しているものと考えることも
できます。それなら、それをバイナリI/Oに使えないでしょうか。もちろんできます。
@c COMMON

@defun read-block! vec :optional iport start end endian
@c EN
Reads a chunk of data from the given input port @var{iport},
and stores it to the uniform vector @var{vec}.
You can give any uniform vector.
If optional @var{start} and @var{end}
arguments are given, they specify the index range in @var{vec}
that is to be filled, and the rest of the vector remains untouched.
Otherwise, entire vector is used.  A special value -1 for @var{end}
indicates the end of @var{vec}.
If @var{iport} is omitted, the current input port is used.
@c JP
与えられた入力ポート@var{iport}からデータの固まりを読みだし、それを
ユニフォームベクタ@var{vec}に格納します。
どんな種類のユニフォームベクタでも与えることができます。
省略可能な引数@var{start}と@var{end}が与えられた場合は、
それらが@var{vec}中でデータが格納されるべき領域のインデックスの範囲を
示します。@var{end}については-1で@var{vec}の最後を示すこともできます。
その範囲外の@var{vec}の値は変更されません。
@var{start}、@var{end}が与えられなかった場合は@var{vec}全体が使われます。
@var{iport}が省略された場合はカレント入力ポートが使われます。
@c COMMON

@c EN
If the input reached EOF before the required region of @var{vec}
is filled, the rest of the vector is untouched.
@c JP
要求された領域を埋め終る前に入力がEOFに達した場合は、ベクタの残りの部分は
変更されません。
@c COMMON

@c EN
If @var{iport} is already reached EOF when @code{read-block!} is
called, an EOF object is returned.  Otherwise,
the procedure returns the number of @emph{elements} read (not bytes).
@c JP
@code{read-block!}が呼ばれた時既に@var{iport}がEOFに達していた場合は
EOFが、そうでなければ読まれた要素の数 (バイト数ではありません) が返されます。
@c COMMON

@c EN
If the @var{iport} is a buffered port with `modest' or `none'
buffering mode (@xref{File ports}), @code{read-block!} may return
before all the elements in @var{vec} is filled, even if @var{iport}
hasn't reached EOF.  The ports connected to a pipe or a network socket
behave so by default.  If you know there will be enough data arriving and
want to make sure @var{vec} is filled, change the buffering mode of
@var{iport} to `full'.
@c JP
@var{iport}がバッファードポートであり、そのバッファリングモードが
`modest' か `none' であった場合、@code{read-block!}は@var{iport}が
EOFに達していなくても、@var{vec}を埋める前に戻ることがあります
(バッファリングモードについては@ref{File ports})を参照して下さい。
パイプやネットワークに接続されたポートはデフォルトでそのように振舞います。
もし、十分なデータが到着することがわかっており、@var{vec}を確実に埋めたい場合は
ポートのバッファリングモードを`full'に変更して下さい。
@c COMMON

@c EN
The data is read as a byte stream, so if you give uniform vectors
other than s8vector or u8vector, your result may affected by
the endianness.  If the optional argument @var{endian} is
given, the input is interpreted in that endianness.
When omitted, the value of the parameter @code{default-endian}
is used.  @xref{Endianness}, for more about endian handling.
@c JP
データはバイトストリームとして読まれるので、
s8vectorとu8vector以外のユニフォームベクタを与えた場合は
結果がエンディアンに影響を受けることに注意して下さい。
省略可能引数@var{endian}によって、入力データのエンディアンを指定
することができます。省略した場合はパラメータ@code{default-endian}の
値が使われます。エンディアンの扱いについてより詳しくは@ref{Endianness}を参照して
ください。
@c COMMON
@end defun

@defun write-block vec :optional oport start end endian
@c EN
Writes out the content of the uniform vector @var{vec} 'as is'
to the output port @var{oport}.   If @var{oport} is omitted,
the current output port is used.
If optional @var{start} and @var{end} arguments are given,
they specify the index range in @var{vec} to be written out.
A special value -1 for @var{end} indicates the end of @var{vec}.
This procedure returns an unspecified value.
@c JP
ユニフォームベクタ@var{vec}の内容を「そのまま」@var{oport}に書き出します。
@var{oport}が省略された場合はカレント出力ポートが使われます。
省略可能な引数@var{start}と@var{end}が与えられた場合は、
それらのインデックスの範囲が示す@var{vec}の内容のみが出力されます。
@var{end}に-1を渡して@var{vec}の最後を示すこともできます。
この手続きの返す値は未定義です。
@c COMMON

@c EN
If you write out a uniform vector except s8vector and u8vector, the 
care should be taken about the endianness, as in @code{read-block!}.
The optional argument @var{endian} specifies the output endian.
When it is omitted, the value of the parameter @code{default-endian}
is used (@xref{Endianness}).
@c JP
@code{s8vector}と@code{u8vector}以外のユニフォームベクタを与えた場合、
@code{read-block!}と同じようにエンディアンの影響を受けることに注意して
下さい。省略可能引数@var{endian}によって出力のエンディアンを
指定できます。省略した場合はパラメータ@code{default-endian}の値が
使われます (@xref{Endianness}参照)。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Comparing version numbers, Virtual ports, Uniform vectors, Library modules - Gauche extensions
@section @code{gauche.version} - Comparing version numbers
@c NODE バージョン番号の比較, @code{gauche.version} - バージョン番号の比較

@deftp {Module} gauche.version
@mdindex gauche.version
@c EN
This module provides a convenient procedure to compare
@emph{version numbers} or @emph{revision numbers},
such as "@code{0.5.1}", "@code{3.2-3}" or "@code{8.2pl1}".
Usually each release of software component has
a version number, and you can define order between them.
For example, version "1.2.3" is newer than "1.2" and
older than "2.1".   You can compare those version numbers like this:
@c JP
このモジュールは、バージョン番号(リリース番号)を比較する便利な手続きを提供します。
ここでのバージョン番号とはソフトウェアのリリースにつけられる
"@code{0.5.1}"、"@code{3.2-3}"、"@code{8.2pl1}"といった文字列で、
通常これらの番号間には順序関係が定義できます。
例えば "1.2.3" は "1.2" より新しいが "2.1" より古い、といった具合です。
以下のようにこれらの文字列の順序を比較することができるようになります。
@c COMMON

@example
(version<? "2.2.3" "2.2.11")     @result{} #t
(version<? "2.3.1" "2.3")        @result{} #f
(version<? "2.3.1-1" "2.3.1-10") @result{} #t
(version<? "13a" "5b")           @result{} #f
@end example

@c EN
There are no standard way to name versions, so I chose
one convention.   This won't work for all possible
variations, but I think it covers typical cases.
@c JP
バージョン番号の付け方には特に標準というものはありませんが、
よく使われている方法を採用しました。全ての場合に使えるとはいきませんが、
大抵の場合はカバーできるのではないかと思います。
@c COMMON

@c EN
Strictly speaking, you can only define partial order between
version numbers, for there can be branches.   This module
uses simple measure and just assumes the version numbers
can be fully ordered.
@c JP
厳密に言えば、分岐などの場合があるのでバージョン番号間の関係は半順序関係にしかなりません。
このモジュールでは単純な定義を使って、全順序関係があるものとして扱います。
@c COMMON

@c EN
The version number here is defined by the following syntax.
@c JP
まず、ここでのバージョン番号は以下の構文に従うものとします。
@c COMMON
@example
 <version> : <principal-release>
           | <version> <post-subrelease>
           | <version> <pre-subrelease>
 <principal-release> : <relnum>
 <post-subrelease>   : [.-] <relnum>
 <pre-subrelease>    : _ <relnum>
 <relnum>            : [0-9A-Za-z]+
@end example

@c EN
Typically @code{<relnum>} is composed by numeric part and extension part.
For example, "23a" is composed by an integer 23 and extension "a".
If @code{<relnum>} doesn't begins with digits, we assume its
numeric part is -1.
@c JP
通常@code{<relnum>}は数字部分と、それに続く省略可能な拡張部分とからなります。
例えば "@code{23a}" は数字部分23と拡張部分"@code{a}"からなります。
もし@code{<relnum>}が数字で始まらない場合、その数字部分は-1であると考えることにします。
@c COMMON

@c EN
Then, the order of @code{<relnum>} is defined as follows:
@c JP
@code{<relnum>}の順序関係を次のように定義します。
@c COMMON
@enumerate
@item
@c EN
If relnum A and relnum B have different numeric part, we ignore the
extension and order them numerically, e.g.  "@code{3b}" < "@code{4a}".
@c JP
relnum Aとrelnum Bが異なる数字部分を持っている場合、拡張部分を無視して
数字部分を数値として比較します。例："@code{3b}" < "@code{4a}"。
@c COMMON
@item
@c EN
If relnum A and relnum B have the same numeric part, we compare
extension by alphabetically, e.g.  "@code{4c}" < "@code{4d}"
and "@code{5}" < "@code{5a}".
@c JP
relnum Aとrelnum Bの数字部分が等しい場合、拡張部分を辞書順に比較します。
例："@code{4c}" < "@code{4d}"、"@code{5}" < "@code{5a}"。
@c COMMON
@end enumerate

@c EN
Given the order of @code{<relnum>}, the order of version numbers
are defined as follows:
@c JP
@code{<relnum>}間の順序が定義できたところで、バージョン番号の順序を次のように定義します。
@c EN
@enumerate
@item
Decompose each version number into a list of @code{<principal-release>} and
subsequence subrelease components.   We call each element of
the list "release components".
@item
If the first release component of both lists are the same,
remove it from both.  Repeat this until the head of the lists differ.
@item
Now we have the following cases.
@enumerate
@item
Both lists are empty: versions are the same.
@item
One list (A) is empty and the other list (B) has post-subrelease
at head: A is prior to B
@item
One list (A) is empty and the other list (B) has pre-subrelease
at head: B is prior to A
@item
List A's head is post-subrelease and list B's head is
pre-subrelease: B is prior to A
@item
Both lists have post-subrelease or pre-subrelease at head:
compare their relnums.
@end enumerate
@end enumerate
Here are some examples:
@c JP
@enumerate
@item
各々のバージョン番号を分解して @code{<principal-release>} とそれに続く
サブリリース部品のリストに入れる。このリストの各要素のことを「リリース部品」
と呼びます。
@item
もし両方のリストの最初のリリース部品が同じなら、それを両方のリストから
取り除きます。これをリストの先頭が異るまでくりかえします。
@item
そうすると次のような場合に分られます。
@enumerate
@item
両方のリストが空： バージョンは同じ。
@item
一方のリスト (A) が空で、他方のリスト (B) の先頭がポストサブリリース：
A が B より前のバージョン。
@item
一方のリスト (A) が空で、他方のリスト (B) の先頭がプリサブリリース：
B が A より前のバージョン
@item
リスト A の先頭がポストサブリリースで、リスト B の先頭がプリサブリリース：
B が A より前のバージョン
@item
両方のリストとも先頭がポストサブリリースであるかプリサブリリース：
relnum を比較する。
@end enumerate
@end enumerate

以下はいくつかの例です。
@c COMMON
@example
"1" < "1.0" < "1.1" < "1.1.1" < "1.1.2" < "1.2" < "1.11"
"1.2.3" < "1.2.3-1" < "1.2.4"
"1.2.3" < "1.2.3a" < "1.2.3b"
"1.2_rc0" < "1.2_rc1" < "1.2" < "1.2-pl1" < "1.2-pl2"
"1.1-patch112" < "1.2_alpha"
@end example

@c EN
The reason of having @code{<pre-subrelease>} is to allow
"release candidate" or "pre-release" version.
@c JP
@code{<pre-subrelease>} があるのは、「リリース候補」あるいは
「プリリリース」のバージョンをつかえるようにするためです。
@c COMMON
@end deftp

@defun version=? ver1 ver2
@defunx version<? ver1 ver2
@defunx version<=? ver1 ver2
@defunx version>? ver1 ver2
@defunx version>=? ver1 ver2
@c EN
Returns a boolean value depending on the order of two version number
string @var{ver1} and @var{ver2}.  If the arguments contain invalid
strings as the defined version number, an error is signalled.
@c JP
ふたつのバージョン番号文字列 @var{ver1} と @var{ver2} の順序関係によって
真偽値を返します。もし引数が、バージョン番号を定義するのに不正な文字列を
含んでいたばあい、エラーが上ります。
@c COMMON
@end defun

@defun version-compare ver1 ver2
@c EN
Compares two version number strings @var{ver1} and @var{ver2},
and returns either -1, 0, or 1, depending whether @var{ver1} is
prior to @var{ver2}, @var{ver1} is the same as @var{ver2}, or
@var{ver1} is after @var{ver2}, respectively.
@c JP
ふたつのバージョン番号文字列 @var{ver1} と @var{ver2} を比較し、
@var{ver1} のほうが @var{ver2} より前、@var{ver1} と @var{ver2} は同じ、
@var{ver1} が @var{ver2} の後、の3つの場合によって、それぞれ、
-1、0、1 を返します。
@c COMMON
@end defun

@defun relnum-compare rel1 rel2
@c EN
This is lower-level procedure of @code{version-compare}.  Compares
two release numbers (relnums) @var{rel1} and @var{rel2}, 
and returns either -1, 0, or 1 depending whether  @var{rel1} is
prior to @var{rel2}, @var{rel1} is the same as @var{rel2}, or
@var{rel1} is after @var{rel2}, respectively.
@c JP
これは @code{version-compare}の下位レベルの手続きです。
ふたつのリリース番号 (relnum) @var{rel1} と @var{rel2} を比較し、
@var{rel1} が @var{rel2} より前、@var{rel1} と @var{rel2} が同じ、
@var{rel1} が @var{rel2} より後、の3つの場合によって、それぞれ、
-1、0、1 を返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Virtual ports,  , Comparing version numbers, Library modules - Gauche extensions
@section @code{gauche.vport} - Virtual ports
@c NODE 仮想ポート, @code{gauche.vport} - 仮想ポート

@deftp {Module} gauche.vport
@mdindex gauche.vport
@c EN
@emph{Virtual ports}, or procedural ports, are the ports
whose behavior can be programmed in Scheme.
@c JP
@emph{仮想ポート}あるいは手続き的ポートとは、その振舞いを
Scheme でプログラム可能なポートです。
@c COMMON

@c EN
This module provides two kinds of virtual ports:
Fully virtual ports, in which every I/O operation invokes
user-provided procedures, and virtual buffered ports,
in which I/O operations are done on an internal buffer and
user-provided procedures are called only when the buffer
needs to be filled or flushed.
@c JP
このモジュールは 2 種類の仮想ポートを提供します。ひとつは、
完全仮想ポートで、すべての I/O 操作でユーザが提供する手続きが
呼出されるものです。もうひとつは、仮想バッファポートで、
I/O 操作は内部バッファ上で行われ、ユーザが提供する手続きは
バッファを一杯にするかフラッシュする必要がある場合にのみ
呼出されます。
@c COMMON

@c EN
This module also provides virtual buffered ports backed up
by a uniform vector, as an example of the feature.
@c JP
このモジュールはさらに、ユニフォームベクタにより
バックアップされる仮想バッファポートも提供します。
これは仮想ポートの使用例でもあります。
@c COMMON
@end deftp

@c EN
@subsubheading Fully virtual ports
@c JP
@subsubheading 完全仮想ポート
@c COMMON

@c EN
This type of virtual ports are realized by classes
@code{<virtual-input-port>} and @code{<virtual-output-port>}.
You can customize the port behavior by setting 
appropriate slots with procedures.
@c JP
このタイプの仮想ポートは、@code{<virtual-input-port>} クラス
および @code{<virtual-output-port>} クラスで実現されています。
適切なスロットに手続きをセットすることでポートの振舞いをカスタマイズ
可能です。
@c COMMON

@deftp {Class} <virtual-input-port>
@clindex virtual-input-port
@c EN
An instance of this class can be used as an input port.
The behavior of the port depends on the settings of the
instance slot values.
@c JP
このクラスのインスタンスは入力ポートとして使えます。
このポートの振舞いはインスタンスのスロットに設定された値に依存します。
@c COMMON

@c EN
To work as a meaningful input port, at least either one of
@code{getb} or @code{getc} slot must be set.  Otherwise,
the port returns EOF for all input requests.
@c JP
まともな入力ポートとして動かすためには、少くとも、@code{getb} スロット
あるいは @code{getc} スロットのどちらか一方は設定しなければなりません。
さもなければ、このポートはすべての入力要求に対して EOF を返します。
@c COMMON

@defivar {<virtual-input-port>} getb
@c EN
If set, the value must be a procedure that takes no arguments.
Every time binary input is required, the procedure is called.
@c JP
設定されているのなら、その値は、引数を取らない手続きでなければなりません。
バイナリ入力の要求のたびに、この手続きが呼ばれます。
@c COMMON

@c EN
The procedure must return an exact integer between 0 and 255
inclusive, or @code{#f} or an EOF object.  If it returns an
integer, it becomes the value read from the port.  If it returns
other values, the port returns EOF.
@c JP
この手続きは、0 から 255 までの正確な整数を返すか、@code{#f}あるいは
EOF オブジェクトを返さなければなりません。整数を返す場合には、
それがこのポートから読みとられる値となります。それ以外の値を返す
場合は、このポートは EOF を返します。
@c COMMON

@c EN
If the port is requested a character input and it doesn't have
the @code{getc} procedure, the port calls this procedure, possibly
multiple times, to construct a whole character.
@c JP
このポートが文字入力を要求され、かつ、@code{getc} 手続きを持たない場合、
このポートはこの手続きを呼び(複数回の可能性もある)文字全体を構築します。
@c COMMON
@end defivar

@defivar {<virtual-input-port>} getc
@c EN
If set, the value must be a procedure that takes no arguments.
Every time character input is required, the procedure is called.
@c JP
設定されているのなら、その値は、引数を取らない手続きでなければなりません。
文字入力の要求のたびに、この手続きが呼ばれます。
@c COMMON

@c EN
The procedure must return a character,
@code{#f} or an EOF object.  If it returns a character,
it becomes the value read from the port.  If it returns
other values, the port returns EOF.
@c JP
この手続きは文字を返すか、または@code{#f}あるいはEOFオブジェクトを返さなければ
なりません。文字を返した場合には、それがこのポートから読みとられる値と
なります。それ以外の値を返す場合は、このポートは EOF を返します。
@c COMMON

@c EN
If the port is requested a binary input and it doesn't have
the @code{getb} procedure, the port calls this procedure, then converts
a character into a byte sequence, and use it as the binary
value(s) read from the port.
@c JP
このポートがバイナリ入力を要求され、かつ、@code{getb} 手続きを持たない場合、
このポートはこの手続きを呼び、文字をバイト列に変換し、それをこのポートから
読みだされる値として使います。
@c COMMON
@end defivar

@defivar {<virtual-input-port>} gets
@c EN
If set, the value must be a procedure that takes one argument,
a positive exact integer.  It is called when the block binary
input, such as @code{read-block}, is requested.
@c JP
設定されているなら、その値は、正の正確な整数の引数をひとつだけとる手続き
でなければなりません。ブロックバイナリ入力、たとえば、
@code{read-block}などが要求された場合に、呼出されます。

@c EN
It must return a (maybe incomplete) string up to the specified size, 
or @code{#f} or EOF object.  If it returns a null string, @code{#f}
or EOF object, 
the port thinks it reached EOF.  If it returns other string,
it is used as the result of block read.
It shouldn't return a string larger than the given size
(Note: you must count size (bytes), not the number of characters).
@c JP
そしてそれは文字列、 不完全文字列、 @code{#f}、 EOF オブジェクトを
返さなくてはなりません. 文字列を返す場合は上記正の正確な整数によって
指定された大きさを越えてはなりません。空文字列、 @code{#f}、EOF を
返した場合はポートの終端にたどり着いたものとみなされます。
(注意: 文字列大きさは文字数でなく文字列が占めるバイト数で指定されます。)

@c EN
The reason of this procedure is efficiency; if this procedure
is not provided, the port calls @code{getb} procedure repeatedly
to prepare the block of data.  In some cases, providing block input
can be much more efficient (e.g. suppose you're reading from
a block of memory chunk).
@c JP
この手続きは効率のためにあります。もし、この手続きが用意されて
いなければ、このポートは、データブロックを準備するのに @code{getb}を
繰り返し呼びます。場合によっては、ブロック入力を用意するほうが
はるかに効率的です。(たとえば、メモリチャンクのブロックからの読みだし
を行なうような場合です。)
@c COMMON

@c EN
You can leave this slot unset if you don't need to take such
advantage.
@c JP
こうした利点を必要としないのなら、このスロットは未設定のままにして
おいてもかまいません。
@c COMMON
@end defivar

@defivar {<virtual-input-port>} ready
@c EN
If set, the value must be a procedure that takes one boolean argument.
It is called when @code{char-ready?} or @code{byte-ready?} is
called on the port.   The value returned from your procedure will
be the result of these procedures.
@c JP
設定されているなら、その値は、真偽値をひとつだけとる手続きでなければ
なりません。この手続きは、このポートに対して、@code{char-ready?}
あるいは @code{byte-ready?} が呼ばれたときに呼出されます。設定した手続き
が返す値が、これらの手続きの結果になります。
@c COMMON

@c EN
The boolean argument is @code{#t} if
@code{char-ready?} is called, or @code{#f} if @code{byte-ready?} is called.
@c JP
@code{char-ready?} が呼ばれたのなら、真偽値引数は @code{#t} です。
@code{byte-ready?} が呼ばれたのなら、真偽値引数は @code{#f} になります。
@c COMMON

@c EN
If unset, @code{char-ready?} and @code{byte-ready?}
always return @code{#t} on the port
@c JP
未設定なら、@code{char-ready?} および @code{byte-ready?} は
このポートに対して常に、@code{#t} を返します。
@c COMMON
@end defivar

@defivar {<virtual-input-port>} close
@c EN
If set, the value must be a procedure that takes no arguments.
It is called when the port is closed.  Return value is discarded.
You can leave this unset
if you don't need to take an action when the port is closed.
@c JP
設定されているのなら、その値は引数を取らない手続きでなければなりません。
その手続きはこのポートがクローズされるときに呼びだされ、返り値は
捨てられます。このポートをクローズするときになんらかのアクションが
必要でないのなら、未設定にしておけます。
@c COMMON

@c EN
This procedure may be called from a finalizer, so you have to be
careful to write it.   See the note on finalization below.
@c JP
この手続きはファイナライザから呼ばれることもあり得ます。したがって、
この手続きは慎重に書く必要があります。後述のファイナライズに
関する注意を参照してください。
@c COMMON
@end defivar

@defivar {<virtual-input-port>} seek
@c EN
If set, the value must be a procedure that takes two arguments,
offset and whence.  The meaning of them is the same as the arguments
to @code{port-seek} (@xref{Common port operations}).
The procedure must adjust the port's internal read pointer
so that the next read begins from the new pointer.
It should return the updated pointer (the byte offset from the
beginning of the port).
@c JP
設定されているのなら、その値は、オフセット引数とそれがどこからかを示す引数
の 2つの引数をとる手続きでなければなりません。これらの引数の意味は、
@code{port-seek} (@ref{Common port operations} 参照) のそれと同じです。
この手続きは、次の読み出しが新しい位置から始められるように
内部のリードポインタを調整しなければなりません。そして
更新されたポインタ(ポート先頭からのバイトオフセット)
を返さなければなりません。
@c COMMON

@c EN
If unset, call of @code{port-seek} and @code{port-tell} on this
port will return @code{#f}.
@c JP
未設定なら、このポートに対する @code{port-seek} および @code{port-tell}
の呼び出しは @code{#f} になります。
@c COMMON

@c EN
Note that this procedure may be called for the purpose of merely
querying the current position, with 0 as @code{offset} and @code{SEEK_CUR}
as @code{whence}.  If your port knows the read pointer but cannot move it,
you can still provide this procedure, which returns the current pointer
position for such queries and returns @code{#f} for other arguments.
@c JP
この手続きは単に現在の位置を問合せるために、
@code{offset} として 0 を、@code{whence} として @code{SEEK_CUR} を与えて
呼び出すこともあることに注意してください。リードポインタの位置は知って
いるが、動かすことができないという場合にも、この手続きを提供することが
できます。上のような問合せには、現在位置を返し、そうでない場合には、
@code{#f} を返します。
@c COMMON
@end defivar

@end deftp


@deftp {Class} <virtual-output-port>
@clindex virtual-output-port
@c EN
An instance of this class can be used as an output port.
The behavior of the port depends on the settings of the
instance slot values.
@c JP
このクラスのインスタンスは出力ポートとして使えます。
このポートの振舞いはインスタンスのスロットに設定された値に依存します。
@c COMMON

@c EN
To work as an output port, at least either one of @code{putb} or
@code{putc} slot has to be set.
@c JP
まともな出力ポートとして動かすためには、少くとも、@code{putb} スロット
あるいは @code{putc} スロットのどちらか一方は設定しなければなりません。
@c COMMON

@defivar {<virtual-output-port>} putb
@c EN
If set, the value must be a procedure that takes one argument,
a byte value (exact integer between 0 and 255, inclusive).
Every time binary output is required, the procedure is called.
The return value of the procedure is ignored.
@c JP
設定されているなら、その値は、バイト値(0 から 255までの正確な整数)を
ひとつだけ引数としてとる手続きでなければなりません。バイナリ出力
の要求のたびに、この手続きが呼ばれます。この手続きの返り値は無視
されます。
@c COMMON

@c EN
If this slot is not set and binary output is requested,
the port may signal an @code{<io-unit-error>} error.
@c JP
このスロットが未設定の場合、バイナリ出力を要求されると、このポートは
@code{<io-unit-error>} エラーを発生させることがあります。
@c COMMON
@end defivar

@defivar {<virtual-output-port>} putc
@c EN
If set, the value must be a procedure that takes one argument,
a character.
Every time character output is required, the procedure is called.
The return value of the procedure is ignored.
@c JP
設定されているなら、それは文字をひとつ引数にとる手続きでなければなりません。
文字出力の要求があるたびにこの手続きがよばれます。この手続きの返り値は
無視されます。
@c COMMON

@c EN
If this slot is not set but @code{putb} slot is set,
the virtual port decomposes the character into a sequence of bytes
then calls @code{putb} procedures.
@c JP
このスロットが未設定であっても、@code{putb} スロットが設定されていれば、
この仮想ポートは文字をバイト列に展開してから、@code{putb} を呼びだします。
@c COMMON
@end defivar

@defivar {<virtual-output-port>} puts
@c EN
If set, the value must be a procedure that takes a
(possibly incomplete) string.
The return value of the procedure is ignored.
@c JP
設定されていれば、その値は、文字列(不完全なものである可能性もある)を
ひとつ引数としてとる手続きでなければなりません。この手続きの返り値は
無視されます。
@c COMMON

@c EN
This is for efficiency.  If this slot is not set, the virtual port
calls @code{putb} or @code{putc} repeatedly to output a chunk of data.
But if your code can perform chunked output efficiently, 
you can provide this procedure.
@c JP
これは、効率のためにあります。このスロットが未設定であれば、この
仮想ポートは、データのかたまりを出力するために、@code{putb} 
あるいは @code{putc} を繰り返し呼びます。もし、ひとかたまりの
出力を効率的に実行可能なコードであれば、この手続きを提供できます。
@c COMMON
@end defivar

@defivar {<virtual-output-port>} flush
@c EN
If set, the value must be a procedure that takes no arguments.
It is called when flushing a port is required (e.g. @code{flush}
is called on the port, or the port is being closed).
@c JP
設定されていれば、その値は引数をとらない手続きでなければなりません。
ポートのフラッシュを要求されたときに呼ばれます(たとえば、@code{flush}
がこのポートに対して呼ばれたとき、あるいは、このポートがクローズ
されるとき)。
@c COMMON

@c EN
This procedure is useful that your port does some sort of buffering,
or needs to keep some state.  If your port doesn't do stateful operation,
you can leave this unset.
@c JP
この手続きは、ポートが何らかのバッファリングをおこなうか、なんらかの
状態を持つような場合に便利です。ポートが状態をともなう操作を行わない
のなら、これは未設定にしておけます。
@c COMMON

@c EN
This procedure may be called from a finalizer, and needs a special
care.  See notes on finalizers below.
@c JP
この手続きはファイナライザから呼ばれることがあります。したがって、
特別な注意が必要です。後述のファイナライザに関する注意を
参照してください。
@c COMMON

@end defivar

@defivar {<virtual-output-port>} close
@c EN
The same as @code{<virtual-input-port>}'s @code{close} slot.
@c JP
@code{<virtual-input-port>} の @code{close} スロットと同様です。
@c COMMON
@end defivar

@defivar {<virtual-output-port>} seek
@c EN
The same as @code{<virtual-input-port>}'s @code{seek} slot.
@c JP
@code{<virtual-input-port>} の @code{seek} スロットと同様です。
@c COMMON
@end defivar

@end deftp

@c EN
@subsubheading Virtual buffered ports
@c JP
@subsubheading 仮想バッファポート
@c COMMON

@c EN
This type of virtual ports are realized by classes
@code{<buffered-input-port>} and @code{<buffered-output-port>}.
You can customize the port behavior by setting 
appropriate slots with procedures.
@c JP
このタイプの仮想ポートは @code{<buffered-input-port>} クラス
および @code{<buffered-output-port>} クラスで実現されています。
適切なスロットに手続きを設定するこでポートの振舞いをカスタマイズ
することができます。
@c COMMON

@c EN
Those ports have internal buffer and only calls Scheme procedures
when the buffer needs to be filled or flushed.  Generally it is 
far more efficient than calling Scheme procedures for every
I/O operation.   Actually, the internal buffering mechanism is
the same as Gauche's file I/O ports.
@c JP
これらのポートは、内部バッファを持っており、そのバッファを満たすか
フラッシュするかの必要があるときにのみ、Scheme の手続きが呼ばれます。
通常、I/O毎に Scheme の手続きを呼ぶよりも遥かに効率がいいものです。
実際の内部バッファリング機構は、GaucheのファイルI/Oポートと同じです。
@c COMMON

@c EN
These ports uses @code{u8vector} as a buffer.  See @ref{Uniform vectors}
for the details.
@c JP
これらのポートはバッファとして @code{u8vector} を使います。詳細は、
@ref{Uniform vectors} を参照してください。
@c COMMON

@deftp {Class} <buffered-input-port>
@clindex buffered-input-port

@c EN
An instance of this class behaves as an input port.
It has the following instance slots.  For a meaningful input
port, you have to set at least @code{fill} slot.
@c JP
このクラスのインスタンスは、入力ポートとして振舞います。
これは以下のようなインスタンススロットを持ちます。
意味のある入力ポートとして使うには少くとも、@code{fill} スロットを
設定しなければなりません。
@c COMMON

@defivar {<buffered-input-port>} fill
@c EN
If set, it must be a procedure that takes one argument,
a @code{u8vector}.  It must fill the data from the
beginning of the vector.  It doesn't need to fill the entire
vector if there's not so many data.  However, if there are remaining
data, it must fill at least one byte; if the data isn't readily
available, it has to wait until some data becomes available.
@c JP
設定されているなら、@code{u8vector} の引数を一つとる手続きでなければ
なりません。そのベクタの最初からデータを満たさなければなりません。
要求されたものよりデータの残りが少ない場合には、
ベクタ全体を満たす必要はありません。しかしながら、
データが残っている場合には少くとも1バイトは満たさなければなりません。
もしデータがまだ利用可能になっていなければ、なにがしかのデータが利用可能に
なるまで待たなければなりません。
@c COMMON

@c EN
The procedure must return a number of bytes it actually filled.
It may return 0 or an EOF object to indicate the port has reached EOF.
@c JP
この手続きは実際に満されたバイト数を返さなければなりません。ポートが
EOFに達したことを示すために、0 または EOFオブジェクトを返すこともできます。
@c COMMON
@end defivar

@defivar {<buffered-input-port>} ready
@c EN
If set, it must be a procedure that takes no arguments.
The procedure must return a true value if there are some data
readily available to read, or @code{#f} otherwise.
Unlike fully virtual ports, you don't need to distinguish
binary and character I/O.
@c JP
設定されているなら、引数をとらない手続きでなければなりません。
この手続きは、なにがしかの読み込み用データが利用可能になっていれば
真の値を返し、そうでなければ、@code{#f}を返します。完全仮想ポートとはちがい、
バイナリI/Oと文字I/Oを区別する必要はありません。
@c COMMON

@c EN
If this slot is not set, the port is regarded as it always has data ready.
@c JP
このスロットが未定義の場合、このポートは常にデータが利用可能になっている
とみなされます。
@c COMMON
@end defivar

@defivar {<buffered-input-port>} close
@c EN
If set, it must be a procedure that takes no arguments.
The procedure is called when the virtual buffered port is closed.
You don't need to set this slot unless you need some cleaning up
when the port is closed.
@c JP
設定されていれば、引数をとらない手続きでなければなりません。この手続きは
仮想バッファポートがクローズされるときに呼出されます。ポートがクローズ
されるときに、なにがしかのクリーンアップを行うのでなければ、設定する必要
はありません。
@c COMMON

@c EN
This procedure may be called from a finalizer, and
needs special care.  See the note on finalization below.
@c JP
この手続きは、ファイナライザから呼ばれる可能性がありますので、特別な
注意が必要です。後述のファイナライズに関する注意書きを参照してください。
@c COMMON
@end defivar

@defivar {<buffered-input-port>} filenum
@c EN
If set, it must be a procedure that returns underlying
file descriptor number (exact nonnegative integer).
The procedure is called when @code{port-file-number} is called
on the port.
@c JP
設定されているなら、このポートの使っているファイルディスクリプタ番号(正確な非負整数)
を返す手続きでなければなりません。この手続きは @code{port-file-number}
をこのポートに対して呼出したときに呼ばれます。
@c COMMON

@c EN
If there's no such underlying file descriptor, you can
return @code{#f}, or you can leave this slot unset.
@c JP
そのようなファイルディスクリプタが存在していなければ、
@code{#f} を返すことができます。
あるいは、このスロットを未設定にしておくこともできます。
@c COMMON
@end defivar

@defivar {<buffered-input-port>} seek
@c EN
If set, it must be a procedure that takes two arguments,
@var{offset} and @var{whence}.
It works the same way as @code{<virtual-input-port>}'s seek procedure;
see above.
@c JP
設定されているなら、オフセット引数とどこからかを示す引数の2つをとる
手続きでなければなりません。これは、前述の
@code{<virtual-input-port>}のseek 手続きと同じように動作します。
@c COMMON

@c EN
This procedure may be called from a finalizer, and
needs special care.  See the note on finalization below.
@c JP
この手続きはファイナライザから呼ばれる可能性があり、特別な注意が
必要です。後述のファイナライズに関する注意を参照してください。
@c COMMON
@end defivar

@c EN
Besides those slot values, you can pass an exact nonnegative integer
as the @code{:buffer-size} keyword argument to the @var{make} method
to set the size of the port's internal buffer.  If @code{:buffer-size}
is omitted, or zero is passed, the system's default buffer size
(something like 8K) is used.  @code{:buffer-size} is not an instance
slot and you cannot set it after the instance of the buffered port
is created.   The following example specifies the buffered port
to use a buffer of size 64K:
@c JP
これらのスロットの値以外に、当該ポートの内部バッファのサイズを設定する
のには@var{make}メソッドに@code{:buffer-size}というキーワード引数で非
負の正確な整数を渡します。@code{:buffer-size}が省略されるか、0 が渡さ
れた場合にはシステムのデフォルトのバッファサイズ(たとえば、8kとか)が使
われます。@code{:buffer-size}はインスタンススロットではないので、バッ
ファポートのインスタンスを生成したあとで設定することはできません。以下
は 64K のバッファを使うバッファの作り方の例です。
@c COMMON

@example
(make <buffered-input-port> :buffer-size 65536 :fill my-filler)
@end example
@end deftp

@deftp {Class} <buffered-output-port>
@clindex buffered-output-port

@c EN
An instance of this class behaves as an output port.
It has the following instance slots.
You have to set at least @code{flush} slot.
@c JP
このクラスのインスタンスは出力ポートとして振舞います。これは、以下のような
インスタンススロットを持ちます。少くとも @code{flush} は設定しなければ
なりません。
@c COMMON

@defivar {<buffered-output-port>} flush
@c EN
If set, it must be a procedure that takes two arguments,
an @code{u8vector} buffer and a flag.
The procedure must output data in the buffer to somewhere,
and returns the number of bytes actually output.
@c JP
設定されているなら、@code{u8vector}のバッファとフラグという2つの
引数をとる手続きでなければなりません。手続きはバッファ内のデータを
どこかへ出力しなければならず、実際に出力したバイト数を返します。
@c COMMON

@c EN
If the flag is false, the procedure may output less
than entire buffer (but at least one byte).  If the flag
is true, the procedure must output entire buffer.
@c JP
フラグが偽なら、この手続きはバッファ全体よりも少い(ただし、最低でも
1バイト)の出力を行ってもかまいません。もしフラグが真ならば、この手続きは、
バッファの内容をすべて出力しなければなりません。
@c COMMON
@end defivar

@defivar {<buffered-output-port>} close
@c EN
Same as @code{<buffered-input-port>}'s @code{close} slot.
@c JP
@code{<buffered-input-port>} の @code{close} スロットと同様です。
@c COMMON
@end defivar

@defivar {<buffered-output-port>} filenum
@c EN
Same as @code{<buffered-input-port>}'s @code{filenum} slot.
@c JP
@code{<buffered-input-port>} の @code{filenum} スロットと同様です。
@c COMMON
@end defivar

@defivar {<buffered-output-port>} seek
@c EN
Same as @code{<buffered-input-port>}'s @code{seek} slot.
@c JP
@code{<buffered-input-port>} の @code{seek} スロットと同様です。
@c COMMON
@end defivar

@c EN
Besides those slot values, you can pass an exact nonnegative integer
as the @code{:buffer-size} keyword argument to the @var{make} method
to set the size of the port's internal buffer.  See the description
of @code{<buffered-input-port>} above for the details.
@c JP
これらのスロットの値以外に、当該ポートの内部バッファのサイズを設定する
のには@var{make}メソッドに@code{:buffer-size}というキーワード引数で非
負の正確な整数を渡します。詳しくは前述 @code{<buffered-input-port>}
の項を見てください。
@c COMMON

@end deftp

@c EN
@subsubheading Uniform vector ports
@c JP
@subsubheading ユニフォームベクタポート
@c COMMON

@c EN
The following two procedures returns a buffered input/output port
backed up by a uniform vector.    The source or destination vector
can be any type of uniform vector, but they are aliased
to @code{u8vector} (see @code{uvector-alias} in
@ref{Uvector conversion operations}).
@c JP
以下の 2つの手続きは、ユニフォームベクタでバックアップされた、
バッファ入/出力ポートを返します。読み込み元のベクタあるいは
書き出し相手のベクタはどのようなユニフォームベクタであってもかまいませんが、
実際の入出力時には@code{u8vector} にaliasされます
(@ref{Uvector conversion operations} の @code{uvector-alias} 参照)。
@c COMMON

@c EN
If used together with @code{pack}/@code{unpack} 
(see @ref{Packing Binary Data}), it is useful to parse
or construct binary data structure.  It is also an
example of using virtual ports; read @file{gauche/vport.scm}
(or @file{ext/vport/vport.scm} in the source tree) if you're
curious about the implementation.
@c JP
@code{pack}/@code{unpack}(@ref{Packing Binary Data}参照) と一緒に使うと
バイナリのデータ構造をパースしたり、構築したりするのに便利です。
また、仮想ポートの使い方の例でもあります。実装法に興味があれば、
ソースツリーの @file{gauche/vport.scm}(あるいは @file{ext/vport/vport.scm})
を読んでください。 
@c COMMON

@defun open-input-uvector uvector
@c EN
Returns an input port that reads the content of the given
uniform vector @var{uvector} from its beginning.  If reading
operation reaches the end of @var{uvector}, EOF is returned.
Seek operation is also implemented.
@c JP
与えられたユニフォームベクタ @var{uvector}の最初からその内容を読む
入力ポートを返します。読み込み動作が、@var{uvector}の終端に到達したら
EOFが返されます。シーク操作も実装されています。
@c COMMON
@end defun

@defun open-output-uvector uvector
@c EN
Returns an output port that fills the given uvector by the
data output to the port.  If @var{uvector} is completely
filled, more data are silently discarded.
Seek operation is also implemented.
@c JP
与えられた uvector をポートへのデータ出力で満たす出力ポートを返します。
@var{uvector}が満杯になれば、それ以上のデータは黙って廃棄されます。
シーク操作も実装されています。
@c COMMON
@end defun

@c EN
@subsubheading Note on finalization
@c JP
@subsubheading ファイナライズに関する注意
@c COMMON

@c EN
If an unclosed virtual port is garbage collected, its close procedure
is called (in case of virtual buffered ports, its flush procedure
may also be called before close procedure).  It is done by
a finalizer of the port.  Since it is a part of garbage-collection
process (although the Scheme procedure itself is called outside of
the garbage collector main part), it requires special care.
@c JP
クローズされていない仮想ポートがガベージ・コレクションされると、
クローズ手続きが呼ばれます(仮想バッファポートの場合は、
フラッシュ手続きがクローズ手続きの前に呼ばれます)。これは、
そのポートのファイナライザによって行われます。これはガベージ・コレクション
処理の一部ですから(Scheme 手続きそのものはガーベッジ・コレクタの
メインパートの外側で呼ばれているのですが、それでも)特別な注意が必要です。
@c COMMON

@itemize @bullet
@item
@c EN
It is possible that the object the virtual port has a reference
may already be finalized.  For example, if a virtual port @var{X} 
holds the only reference to a @emph{sink} port @var{Y}, to which
the output goes.  @var{X}'s @code{flush} procedure sends its output to
@var{Y}.  However, if @code{flush} procedure can be called from a
finalizer, it may be possible that @var{Y}'s finalizer has already been
called and @var{Y} is closed.   So @var{X}'s @code{flush} procedure
has to check if @var{Y} has not been closed.
@c JP
仮想ポートが参照しているオブジェクトが既にファイナライズされて
しまっているということがあり得ます。たとえば、仮想ポート @var{X}
は、@emph{流し込み用}のポート @var{Y} への唯一の参照を保持しており、それに
出力するものとします。@var{X}の @code{flush} 手続きは、その出力を
@var{Y}へ送ります。もし@code{flush} 手続きがファイナライザから
呼ばれた場合、@var{Y} のファイナライザが既に
呼ばれていて、@var{Y} がクローズしてしまっていることがあるのです。
従って @var{X} の @code{flush} 手続きは、@var{Y} が既にクローズして
いるかどうかをチェックする必要があります。
@c COMMON

@item
@c EN
You cannot know when and in which thread the finalizer runs.  
So if the procedure like @code{close} or @code{flush} of virtual ports
need to lock or access the global resource, it needs to take
extra care of avoiding dead lock or conflict of access.
@c JP
いつ、どのスレッドでファイナライザが走るかを知ることはできません。
それゆえ、仮想ポートの @code{close} あるいは @code{flush} などの
手続きが、グローバルなリソースをロックしたり、アクセスしたりする
必要のある場合には、デッドロックやアクセスの衝突を回避するために
特に注意する必要があります。
@c COMMON

@c EN
Even in single thread programs, the finalizer can run anywhere
in Scheme programs, so effectively it should be considered as
running in a different thread.
@c JP
単一スレッドのプログラムにおいても、ファイナライザは、Schemeの
プログラムのいたるところで走る可能性があります。したがって、実質的に
それは別のスレッドで走っていると考えておくべきです。
@c COMMON
@end itemize

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
