@node Core library, Object system, Macros, Top
@chapter Core library
@c NODE 組み込みライブラリ

@c ----------------------------------------------------------------------
@menu
* Equivalence::                 
* Numbers::                     
* Booleans::                    
* Undefined values::            
* Pairs and Lists::             
* Symbols::                     
* Keywords::                    
* Identifiers::                 
* Characters::                  
* Character set::               
* Strings::                     
* Regular expressions::          
* Vectors::                     
* Hashtables::                  
* Treemaps::                    
* Weak pointers::               
* Control features::            
* Exceptions::                  
* Eval and repl::               
* Input and output::            
* Loading Programs::            
* Comparison and sorting::      
* System interface::            
* Development helper API::      
@end menu

@node Equivalence, Numbers, Core library, Core library
@section Equivalence
@c NODE 等価

@c EN
Scheme has three different general equivalence test predicates.
Other than these, some types have their own comparison predicates.
@c JP
Schemeには等価性を判定する汎用的な述語が3つあります。
また、これらの他に、いくつかの型はその型同士で使える比較手続きを持っています。
@c COMMON

@defun eq? obj1 obj2
[R5RS]
@c EN
This is the fastest and finest predicate.
Returns @code{#t} if @var{obj1} and @var{obj2} are allocated objects of
the same types, and denote the same location.  Returns @code{#t}
if both objects are @code{#f}, @code{#t}, or @code{()}.
You can think @var{eq?} as a pointer comparison.
Note that the result is unspecified in Scheme standard when
both objects are characters or numbers.
@c JP
最も高速で、細かい区別ができる述語です。
@var{obj1}と@var{obj2}がアロケートされる同じ型のオブジェクトで、
かつ両者がメモリ上の全く同じ場所を占めるオブジェクトを指している場合に
@code{#t}を返します。また、@var{obj1}と@var{obj2}がともに
@code{#f}, @code{#t}あるいは@code{()}である場合も@code{#t}を返します。
ポインタ比較と考えても良いでしょう。
@var{obj1}と@var{obj2}がともに文字、あるいは数値であった場合の振るまいは
Schemeの標準では定められていません。
@c COMMON

@example
(eq? #t #t)               @result{} #t
(eq? #t #f)               @result{} #f
(eq? 'a 'a)               @result{} #t
(eq? 'a 'b)               @result{} #f
(eq? (list 'a) (list 'a)) @result{} #f
(let ((x (list 'a)))
  (eq? x x))              @result{} #t
@end example
@end defun

@defun eqv? obj1 obj2
[R5RS]
@c EN
When @var{obj1} and @var{obj2} are both exact or both inexact numbers
(except NaN),
@var{eqv?} returns @code{#t} iff @code{(= @var{obj1} @var{obj2})} is true.
When @var{obj1} and @var{obj2} are both characters,
@var{eqv?} returns @code{#t} iff @code{(char=? @var{obj1} @var{obj2})} is true.
Otherwise, @code{eqv?} is the same as @code{eq?} on Gauche.
@c JP
@var{obj1}と@var{obj2}がともに正確な数値、もしくはともに(NaN以外の)不正確な数値である場合、
@code{(= @var{obj1} @var{obj2})}が真であれば@code{#t}が、偽であれば@code{#f}が
返されます。
@var{obj1}と@var{obj2}がともに文字である場合、
@code{(char=? @var{obj1} @var{obj2})}が真であれば@code{#t}が、偽であれば@code{#f}が
返されます。
それ以外の場合は、Gaucheでは@code{eqv?}は@code{eq?}と同じです。
@c COMMON

@example
(eqv? #\a #\a)             @result{} #t
(eqv? #\a #\b)             @result{} #f
(eqv? 1.0 1.0)             @result{} #t
(eqv? 1 1)                 @result{} #t
(eqv? 1 1.0)               @result{} #f
(eqv? (list 'a) (list 'a)) @result{} #f
(let ((x (list 'a)))
  (eqv? x x))              @result{} #t
@end example

@c EN
Note that comparison of NaNs has some peculiarity.
Any numeric comparison fails if there's at least one NaN in its argument.
Therefore, @code{(= +nan.0 +nan.0)} is always @code{#f}.   However,
Gauche @emph{may} return @code{#t} for @code{(eq? +nan.0 +nan.0)}
or @code{(eqv? +nan.0 +nan.0)}.
@c JP
NaNの比較には少々奇妙なところがあります。数値比較は、引数に一つでもNaNが
含まれていれば失敗します。したがって@code{(= +nan.0 +nan.0)}は常に@code{#f}と
なります。けれども、@code{(eq? +nan.0 +nan.0)} や 
@code{(eqv? +nan.0 +nan.0)}は@code{#t}を返すことがあるかもしれません。
@c COMMON
@end defun

@defun equal? obj1 obj2
[R5RS+]
@c EN
If @var{obj1} and @var{obj2} are both aggregate types,
@code{equal?} compares its elements recursively.
Otherwise, @code{equal?} behaves the same as @code{eqv?}.

If @var{obj1} and @var{obj2} are other than booleans, numbers,
characters, pairs, strings and vectors, and the class of both
objects are the same, @code{equal?} calls the generic
function @code{object-equal?}.
By defining the method, users can extend the behavior of @code{equal?}
for user-defined classes.
@c JP
@var{obj1}と@var{obj2}がリストやベクタなどの複合型である場合、
@code{equal?}は再帰的に対応する要素同士を@code{equal?}で比較してゆきます。
そうでなければ、@code{equal?}は@code{eqv?}と同じようにふるまいます。

もし@code{obj1}と@var{obj2}が論理値、数値、文字、ペア、文字列、
ベクタのいずれでもなく、かつ両者のクラスが等しい場合、@code{equal?}は
ジェネリックファンクション@code{object-equal?}を呼びます。
@code{object-equal?}にメソッドを定義することにより、
ユーザ定義のデータ型に対する@code{equal?}の振るまいを拡張することができます。
@c COMMON

@example
(equal? (list 1 2) (list 1 2)) @result{} #t
(equal? "abc" "abc")           @result{} #t
(equal? 100 100)               @result{} #t
(equal? 100 100.0)             @result{} #f
@end example

@c EN
Note: If both @var{obj1} and @var{obj2} have circular structure,
@code{equal?} may diverge.  You might want to use @code{isomorph?}
instead (see @ref{Determine isomorphism}).
@c JP
註: @var{obj1}と@var{obj2}がともに循環構造を持っている場合、
@code{equal?}は発散する可能性があります。
かわりに@code{isomorph?} (@ref{Determine isomorphism}参照) が使える
かもしれません。
@c COMMON
@end defun

@deffn {Generic Function} object-equal? obj1 obj2
@c EN
This generic function is called when @code{equal?} is called on the objects
it doesn't know about.  You can define this method on your class
so that @code{equal?} can check equivalence.   This method is supposed
to return @code{#t} if @var{obj1} is equal to @var{obj2}, @code{#f}
otherwise.  If you want to check equivalence of elements recursively,
do not call @code{object-equal?} directly; call @code{equal?} on each element.
@c JP
@code{equal?}が未知のオブジェクトに対して呼ばれた場合、
このジェネリックファンクションが呼ばれます。自分で定義したクラスに対して
このメソッドを定義することにより、@code{equal?}で等価判定が行えるように
なります。メソッドは、@var{obj1}と@var{obj2}が等価ならば@code{#t}を、
そうでなければ@code{#f}を返さねばなりません。
オブジェクトの各要素に対して再帰的に等価判定を行いたい場合は、
@code{object-equal?}を直接呼ぶのではなく、@code{equal?}を各要素に対して
呼ぶようにして下さい。
@c COMMON

@example
(define-class <foo> ()
  ((x :init-keyword :x)
   (y :init-keyword :y)))

(define-method object-equal? ((a <foo>) (b <foo>))
  (and (equal? (slot-ref a 'x) (slot-ref b 'x))
       (equal? (slot-ref a 'y) (slot-ref b 'y))))

(equal? (make <foo> :x 1 :y (list 'a 'b))
        (make <foo> :x 1 :y (list 'a 'b)))
  @result{} #t

(equal? (make <foo> :x 1 :y (make <foo> :x 3 :y 4))
        (make <foo> :x 1 :y (make <foo> :x 3 :y 4)))
  @result{} #t
@end example
@end deffn

@c EN
Sometimes you want to test if two aggregate structures
are topologically equal, i.e., if one has a shared substructure,
the other has a shared substructure in the same way.
@code{Equal?} can't handle it; module @code{util.isomorph} 
provides a procedure @code{isomorphic?} which does the job
(@xref{Determine isomorphism}).
@c JP
しばしば、ふたつの複合型オブジェクトに関して、両者がトポロジー的に等しいこと、
すなわち一方が共有する部分構造を持っている場合にもう一方も同じように部分構造を
共有しているかどうかを調べたいことがあります。@code{equal?}はその目的には
使えません。モジュール@code{util.isomorph}の提供する@code{isomorphic?}が
その目的に使えます。(@ref{Determine isomorphism}参照)。
@c COMMON

@c ----------------------------------------------------------------------
@node Numbers, Booleans, Equivalence, Core library
@section Numbers
@c NODE 数値

@c EN
Gauche supports the following types of numbers
@table @asis
@item multi-precision exact integer
There's no limit of the size of number except the memory of the machine.
@item multi-precision exact non-integral rational numbers.
Both denominator and numerator are represented by exact integers.
There's no limit of the size of number except the memory of the machine.
@item inexact floating-point real numbers
Using @code{double}-type of underlying C compiler, usually IEEE 64-bit
floating point number.
@item inexact floating-point complex numbers
Real part and imaginary part are represented by inexact floating-point
real numbers.
@end table
@c JP
Gaucheは次のタイプの数値をサポートしています。
@table @asis
@item 多倍長の正確な整数
メモリの許す限りの精度が扱えます。
@item 多倍長の正確な非整数の有理数
分母と分子は正確な整数で表現されます。
メモリの許す限りの精度が扱えます。
@item 浮動小数点の不正確な実数
実装に使われるC言語の@code{double}型で表現されます。通常IEEE 64bit浮動小数点数です。
@item 浮動小数点の不正確な複素数
実部と虚部はそれぞれ浮動小数点の不正確な実数で表現されます。
@end table
@c COMMON

@menu
* Number classes::              
* Numerical predicates::        
* Numerical comparison::        
* Arithmetics::                 
* Numerical conversions::       
* Bitwise operations::          
* Endianness::                  
@end menu

@node Number classes, Numerical predicates, Numbers, Numbers
@subsection Number classes
@c NODE 数値クラス

@deftp {Builtin Class} <number>
@deftpx {Builtin Class} <complex>
@deftpx {Builtin Class} <real>
@deftpx {Builtin Class} <rational>
@deftpx {Builtin Class} <integer>
@clindex number
@clindex complex
@clindex real
@clindex rational
@clindex integer
@c EN
These classes consist a class hierarchy of number objects.
@code{<complex>} inherits @code{<number>}, @code{<real>} inherits
@code{<complex>},@code{<rational>} inherits @code{<real>}
 and @code{<integer>} inherits @code{<rational>}.

Note that these classes do not exactly correspond to the
number hierarchy defined in R5RS.  Especially, 
only exact integers are the instances of the @code{<integer>}
class.  That is,
@c JP
数値オブジェクトのクラス階層を構成します。@code{<complex>}は
@code{<number>}を継承し、@code{<real>}は@code{<complex>}を継承し、
@code{<rational>}は@code{<real>}を継承し、
@code{<integer>}は@code{<rational>}を継承します。

これらのクラスはR5RSで定義されている数値の階層とは必ずしも対応しません。
特に、@code{<integer>}クラスのインスタンスはR5RSでいうexact integerのみになります。
@c COMMON
@lisp
(integer? 1)        @result{} #t
(is-a? 1 <integer>) @result{} #t
(is-a? 1 <real>)    @result{} #t

(integer? 1.0)        @result{} #t
(is-a? 1.0 <integer>) @result{} #f
(is-a? 1.0 <real>)    @result{} #t

(class-of (expt 2 100)) @result{} #<class <integer>>
(class-of (sqrt -3)) @result{} #<class <complex>>
@end lisp
@end deftp

@node Numerical predicates, Numerical comparison, Number classes, Numbers
@subsection Numerical predicates
@c NODE 数値に関する述語

@defun number? obj
@defunx complex? obj
@defunx real? obj
@defunx rational? obj
@defunx integer? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a number, a complex number, a real number,
a rational number or an integer, respectively.   In Gauche, a set of
numbers is the same as a set of complex numbers.
A set of rational numbers is the same as a set of real numbers,
except @code{+inf.0}, @code{-inf.0} and @code{+nan.0}
(since we have only limited-precision floating numbers).
@c JP
@var{obj}がそれぞれ数、複素数、実数、有理数、整数ならば@code{#t}を返します。
Gaucheでは、数の集合は複素数の集合と同一であり、有理数の集合は
@code{+inf.0}, @code{-inf.0}, @code{+nan.0}を除いた実数の集合と同一
(浮動小数点数が有限精度であるため)です。
@c COMMON

@example
(complex? 3+4i)   @result{} #t
(complex? 3)      @result{} #t
(real? 3)         @result{} #t
(real? -2.5+0.0i) @result{} #t
(real? #e1e10)    @result{} #t
(integer? 3+0i)   @result{} #t
(integer? 3.0)    @result{} #t

(real? +inf.0)     @result{} #t
(real? +nan.0)     @result{} #t
(rational? +inf.0) @result{} #f
(rational? +nan.0) @result{} #f
@end example

@c EN
Note: R6RS adopts more strict definition on exactness,
and notably, it defines a complex number with non-exact zero imaginary
part is not a real number.   Currently Gauche doesn't have
exact complex numbers, and automatically coerces complex
numbers with zero imaginary part to a real number.
Thus R6RS code that relies on the fact that @code{(real? 1+0.0i)} is
@code{#f} won't work with Gauche.
@c JP
R6RSでは正確性についてより厳密な定義がなされ、特に
非正確なゼロを虚数部に持つ複素数は実数ではないと規定されています。
Gaucheは今のところ正確な複素数を持たず、虚部がゼロの複素数は
自動的に実数に変換されます。従ってR6RSのコードのうち、
@code{(real? 1+0.0i)}が@code{#f}であることを当てにしているものは
うまく動かないでしょう。
@c COMMON
@end defun

@defun real-valued? obj
@defunx rational-valued? obj
@defunx integer-valued? obj
[R6RS]
@c EN
In Gauche these are just an alias of @code{real?}, @code{rational?}
and @code{integer?}.  They are provided for R6RS compatibility.

The difference of those and non @code{-valued} versions in R6RS is
that these returns @code{#t} if @var{obj} is a complex number
with nonexact zero imaginary part.   Since Gauche doesn't distinguish
complex numbers with zero imaginary part and real numbers, we don't
have the difference.
@c JP
Gaucheではこれらの手続きはそれぞれ@code{real?}、@code{rational?}、
および@code{integer?}の別名となっています。これらはR6RSコードとの互換性のために
提供されています。

R6RSで規定されている、これらの手続きと@code{-valued}がついていない手続きの違いは、
これらの手続きは非正確なゼロの虚部を持つ複素数に対しても@code{#t}を返すという
ことです。Gaucheではゼロの虚部を持つ複素数は実数とみなしているので、
この違いは現れません。
@c COMMON
@end defun

@defun exact? obj
@defunx inexact? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is an exact number and an inexact number,
respectively.
@c JP
@var{obj}がそれぞれ正確な数、不正確な数ならば@code{#t}を返します。
@c COMMON

@example
(exact? 1)       @result{} #t
(exact? 1.0)     @result{} #f
(inexact? 1)     @result{} #f
(inexact? 1.0)   @result{} #t

(exact? (modulo 5 3)) @result{} #t
(inexact? (modulo 5 3.0)) @result{} #f
@end example
@end defun

@defun zero? z
[R5RS]
@c EN
Returns @code{#t} if a number @var{z} equals to zero.
@c JP
数値@var{z}がゼロに等しければ@code{#t}を返します。
@c COMMON

@example
(zero? 1)        @result{} #f
(zero? 0)        @result{} #t
(zero? 0.0)      @result{} #t
(zero? 0.0+0.0i) @result{} #t
@end example
@end defun

@defun positive? x
@defunx negative? x
[R5RS]
@c EN
Returns @code{#t} if a real number @var{x} is positive and negative,
respectively.  It is an error to pass a non-real number.
@c JP
実数@var{x}がそれぞれ正または負なら@code{#t}を返します。
非実数を渡すとエラーになります。
@c COMMON
@end defun

@defun finite? z
@defunx infinite? z
@defunx nan? z
[R6RS]
@c EN
For real numbers, returns @code{#f} iff the given number
is finite, infinite, or NaN, respectively.

For non-real complex numbers, @code{finite?} returns @code{#t} iff
both real and imaginary components are finite, @code{infinite?}
returns @code{#t} if at least either real or imagnary component
is infinite, and @code{nan?} returns @code{#t} if at least either
real or imagnary component is NaN.  (Note: It is incompatible
to R6RS, in which these procedures must raise an error if
the given arugment is non-real number.)
@c JP
実数に対して、それが有限、無限、NaNであればそれぞれ@code{#t}を返します。

非実数の複素数に対しては、@code{finite?}は実数部と仮数部がともに
有限なら@code{#t}を、@code{infinite?}は実数部と仮数部の少なくともどちらかが
無限なら@code{#t}を、@code{nan?}は実数部と仮数部の少なくともどちらかが
NaNなら@code{#t}を返します。(これはR6RSとは非互換です。R6RSでは
これらの手続きは引数に非実数の数が与えられた場合はエラーを通知しなければならないからです。)
@c COMMON
@end defun

@defun odd? n
@defunx even? n
[R5RS]
@c EN
Returns @code{#t} if an integer @var{n} is odd and even, 
respectively.  It is an error to pass a non-integral number.
@c JP
整数@var{n}がそれぞれ奇数または偶数なら@code{#t}を返します。
非整数を渡すとエラーになります。
@c COMMON

@example
(odd? 3)     @result{} #t
(even? 3)    @result{} #f
(odd? 3.0)   @result{} #t
@end example
@end defun

@defun fixnum? n
@defunx bignum? n
@c EN
Returns @code{#t} iff @var{n} is an exact integer whose internal
representation is @var{fixnum} and @var{bignum}, respectively.
Portable Scheme programs don't need to care about the internal
representation of integer.   These are for certain low-level
routines that does particular optimization.
@c JP
@var{n}が正確な整数で、かつ内部的にそれぞれ@var{fixnum}もしくは@var{bignum}
で表現されているときに@code{#t}を返します。
通常のSchemeプログラムは整数の内部表現を気にする必要はありません。
これらの手続きは、ある種の最適化を行う低レベル手続きのために用意されています。
@c COMMON
@end defun

@node Numerical comparison, Arithmetics, Numerical predicates, Numbers
@subsection Numerical comparison
@c NODE 数値の比較

@defun = z1 z2 z3 @dots{}
[R5RS]
@c EN
If all the numbers @var{z} are equal, returns @code{#t}.
@c JP
与えられた全ての数値@var{z}が等しければ@code{#t}を返します。
@c COMMON

@example
(= 2 2)          @result{} #t
(= 2 3)          @result{} #f
(= 2 2.0)        @result{} #t
(= 2 2.0 2.0+0i) @result{} #t
(= 2/4 1/2)      @result{} #t
@end example
@end defun

@defun < x1 x2 x3 @dots{}
@defunx <= x1 x2 x3 @dots{}
@defunx > x1 x2 x3 @dots{}
@defunx >= x1 x2 x3 @dots{}
[R5RS]
@c EN
Returns @code{#t} If all the real numbers @var{x} are
monotonically increasing,
monotonically nondecreasing, monotonically decreasing, or monotonically
nonincreasing, respectively.
@c JP
与えられた全ての実数@var{x}がそれぞれ単調増加、単調非減少、単調減少、単調非増加している
場合に@code{#t}を返します。
@c COMMON
@end defun


@defun max x1 x2 @dots{}
@defunx min x1 x2 @dots{}
[R5RS]
@c EN
Returns a maximum or minimum number in the given real numbers, respectively.
@c JP
与えられた実数のうち、それぞれ最大と最小のものを返します。
@c COMMON
@end defun

@defun min&max x1 x2 @dots{}
@c EN
Returns a maximum and minimum number in the given real numbers.
@c JP
与えられた実数から、最大値と最小値の二つの値を返します。
@c COMMON
@end defun

@node Arithmetics, Numerical conversions, Numerical comparison, Numbers
@subsection Arithmetics
@c NODE 数値の演算

@defun + z @dots{}
@defunx * z @dots{}
[R5RS]
@c EN
Returns the sum or the product of given numbers, respectively.
If no argument is given, @code{(+)} yields 0 and @code{(*)} yields 1.
@c JP
与えられた数の和と積をそれぞれ返します。引数が与えられない場合、
@code{(+)} は 0、 @code{(*)} は 1 となります。
@c COMMON
@end defun

@defun - z1 z2 @dots{}
@defunx / z1 z2 @dots{}
[R5RS]
@c EN
If only one number @var{z1} is given, returns its
negation and reciprocal, respectively.

If more than one number are given, returns:
@example
@var{z1} - @var{z2} - @var{z3} @dots{}
@var{z1} / @var{z2} / @var{z3} @dots{}
@end example
respectively.
@c JP
一つだけ数値が与えられた場合、それぞれnegationと逆数を返します。

2つ以上の数値が与えられた場合、それぞれ次の結果を返します。
@example
@var{z1} - @var{z2} - @var{z3} @dots{}
@var{z1} / @var{z2} / @var{z3} @dots{}
@end example
@c COMMON

@example
(- 3)       @result{} -3
(- -3.0)    @result{} 3.0
(- 5+2i)    @result{} -5.0-2.0i
(/ 3)       @result{} 1/3
(/ 5+2i)    @result{} 0.172413793103448-0.0689655172413793i

(- 5 2 1)     @result{} 2
(- 5 2.0 1)   @result{} 2.0
(- 5+3i -i)   @result{} 5.0+2.0i
(/ 14 6)      @result{} 7/3
(/ 6+2i 2)    @result{} 3.0+1.0i
@end example

@c EN
Note: Gauche didn't have exact rational number support until 0.8.8;
before that, @code{/} coerced the result to inexact even if both
divisor and dividend were exact numbers, when the result wasn't
a whole number.  It is not the case anymore.

If the existing code relies on the old behavior, it runs
very slowly on the newer versions of Gauche, since the calculation
proceeds with exact rational arithmetics that is much slower than
floating point arithmetics.  You want to use @code{/.} below
to use fast inexact arithmetics (unless you
need exact results).
@c JP
註：0.8.8までGaucheは正確な有理数をサポートしておらず、
それ以前は除数と被除数がともに正確な数であっても商が整数にならなければ
結果は非正確な数へと変換されていました。今のGaucheはそうではありません。

既存のコードが以前のGaucheのふるまいを当てにしていた場合、
速度が大きく低下する可能性があります。正確な有理数の演算は
浮動小数点数の演算よりはるかに遅いからです。
(正確な結果を得たいのでない場合は)下に述べる@code{/.}を使うと良いでしょう。
@c COMMON
@end defun

@defun +. z @dots{}
@defunx *. z @dots{}
@defunx -. z1 z2 @dots{}
@defunx /. z1 z2 @dots{}
@c EN
Like @code{+}, @code{*}, @code{-}, and @code{/}, but the arguments
are coerced to inexact number.  So they always return inexact number.
These are useful when you know you don't need exact calculation
and want to avoid accidental overhead of bignums and/or exact
rational numbers.
@c JP
@code{+}、@code{*}、@code{-}、@code{/}と同様ですが、引数は不正確な
数へと変換され、結果も常に不正確な数となります。
正確数による計算が不要で、bignumや正確な有理数をうっかり使ってしまう
ことによるオーバヘッドを避けたい時に便利です。
@c COMMON
@end defun

@defun abs z
[R5RS+]
@c EN
For real number @var{z}, returns an absolute value of it.
For complex number @var{z}, returns the magnitude of the number.
The complex part is Gauche extension.
@c JP
実数の@var{z}に対しては、その絶対値を返します。
複素数の@var{z}に対しては、そのmagnitudeを返します。
複素数を扱うのはGaucheの拡張です。
@c COMMON
@example
(abs -1)   @result{} 1
(abs -1.0) @result{} 1.0
(abs 1+i)  @result{} 1.4142135623731
@end example
@end defun

@defun quotient n1 n2
@defunx remainder n1 n2
@defunx modulo n1 n2
[R5RS]
@c EN
Returns the quotient, remainder and modulo of dividing an integer @var{n1}
by an integer @var{n2}.   The result is an exact number only if
both @var{n1} and @var{n2} are exact numbers.

Remainder and modulo differ when either one of the arguments is negative.
Remainder @var{R} and quotient @var{Q} have the following relationship.
@example
  @var{n1} = @var{Q} * @var{n2} + @var{R}
@end example
where @code{abs(@var{Q}) = floor(abs(@var{n1})/abs(@var{n2}))}.
Consequently, @var{R}'s sign is always the same as @var{n1}'s.

On the other hand, modulo works as expected for positive @var{n2},
regardless of the sign of @var{n1}
(e.g. @code{(modulo -1 @var{n2}) == @var{n2} - 1}).
If @var{n2} is negative, it is mapped to the positive case by
the following relationship.
@example
  modulo(@var{n1}, @var{n2}) = @minus{}modulo(@minus{}@var{n1}, @minus{}@var{n2})
@end example
Consequently, @var{modulo}'s sign is always the same as @var{n2}'s.
@c JP
整数@var{n1}を整数@var{n2}で割った商(quotient)および余り(remainder, modulo)
を返します。  @var{n1}と@var{n2}の両方が正確な数値の時のみ、戻り値は正確な数値になります。

@code{remainder}と@code{modulo} はどちらかの引数が負の時に異なる値を返します。
Remainder @var{R} と商 @var{Q} とは次の関係があります。
@example
  @var{n1} = @var{Q} * @var{n2} + @var{R}
@end example
ここで商について @code{abs(@var{Q}) = floor(abs(@var{n1})/abs(@var{n2}))}
ですから、@var{R}の符号は常に@var{n1}と同じになります。

一方、moduloは@var{n2}が正の時は@var{n1}の符号に関わらず期待したように動作します
(例: @code{(modulo -1 @var{n2}) == @var{n2} - 1})。
@var{n2}が負の場合は次の式によって正の場合にマップできます。
@example
  modulo(@var{n1}, @var{n2}) = @minus{}modulo(@minus{}@var{n1}, @minus{}@var{n2})
@end example
したがって、moduloの結果の符号は常に@var{n2}の符号と同じになります。
@c COMMON
@example
(remainder 10 3)    @result{} 1
(modulo 10 3)       @result{} 1

(remainder -10 3)   @result{} -1
(modulo -10 3)      @result{} 2

(remainder 10 -3)   @result{} 1
(modulo 10 -3)      @result{} -2

(remainder -10 -3)  @result{} -1
(modulo -10 -3)     @result{} -1
@end example
@end defun

@defun quotient&remainder n1 n2
@c EN
Calculates the quotient and the remainder of dividing integer @var{n1}
by integer @var{n2} simultaneously, and returns them as two values.
@c JP
整数@var{n1}を整数@var{n2}で割った商(quotient)および余り(remainder)
を同時に計算し、2つの値として返します。
@c COMMON
@end defun

@defun div x y
@defunx mod x y
@defunx div-and-mod x y
@defunx div0 x y
@defunx mod0 x y
@defunx div0-and-mod0 x y
[R6RS]
@c EN
These are integer division procedures introduced in R6RS.
Unlike @code{quotient}, @code{modulo} and @code{remainder},
these procedures can take non-integral values.
The dividend @var{x} can be an arbitrary real number,
and the divisor @var{y} can be non-zero real number.
@c JP
これらはR6RSで導入された整数除算手続きです。
@code{quotient}, @code{modulo}, @code{remainder}と違い、
これらの手続きは整数でない値を取ることもできます。
被除数@var{x}には任意の実数、除数@var{y}にはゼロ以外の実数が許されます。
@c COMMON

@c EN
@code{div} returns an integer @var{n}, and @code{mod} returns
a real number @var{m}, such that:

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}, and
@item
0 <= @var{m} < |@var{y}|.
@end itemize

Examples:
@c JP
@code{div}は整数@var{n}を、@code{mod}は実数@var{m}を返し、
それらは以下の関係を満たします。

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}
@item
0 <= @var{m} < |@var{y}|
@end itemize

例:
@c COMMON
@example
(div 123 10)     @result{} 12
(mod 123 10)     @result{} 3

(div 123 -10)    @result{} -12
(mod 123 -10)    @result{} 3

(div -123 10)    @result{} -13
(mod -123 10)    @result{} 7

(div -123 -10)   @result{} 13
(mod -123 -10)   @result{} 7

(div 123/7 10/9) @result{} 15
(mod 123/7 10/9) @result{} 19/21
;; 123/7 = 10/9 * 15 + 19/21

(div 14.625 3.75) @result{} 3.0
(mod 14.625 3.75) @result{} 3.375
;; 14.625 = 3.75 * 3.0 + 3.375
@end example

@c EN
For a nonnegative integer @var{x} and an integer @var{y},
The results of @code{div} and @code{mod} matches
those of @code{quotient} and @code{remainder}.  If @var{x}
is negative, they differ, though.
@c JP
@var{x}が非負の整数、@var{y}が整数である場合は、
@code{div}と@code{mod}の結果は@code{quotient}と@code{remainder}
の結果に一致します。しかし@var{x}が負になると結果は異なります。
@c COMMON

@c EN
@code{div-and-mod} calculates both @code{div} and @code{mod}
and returns their results in two values.
@c JP
@code{div-and-mod}は@code{div}と@code{mod}を同時に計算し、
結果を二つの値で返します。
@c COMMON

@c EN
@var{div0} and @var{mod0} are similar, except the range of @var{m}:
@c JP
@var{div0}と@var{mod0}は、@code{m}の値域が異なる以外は同じです。
@c COMMON

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}
@item
-|@var{y}|/2 <= @var{m} < |@var{y}|/2
@end itemize

@example
(div0 123 10)   @result{} 12
(mod0 123 10)   @result{} 3

(div0 127 10)   @result{} 13
(mod0 127 10)   @result{} -3

(div0 127 -10)  @result{} -13
(mod0 127 -10)  @result{} -3

(div0 -127 10)  @result{} -13
(mod0 -127 10)  @result{} 3

(div0 -127 -10) @result{} 13
(mod0 -127 -10) @result{} 3
@end example

@c EN
@code{div0-and-mod0} calculates both @code{div0} and @code{mod0}
and returns their results in two values.
@c JP
@code{div0-and-mod0}は@code{div0}と@code{mod0}を同時に計算し、
結果を二つの値で返します。
@c COMMON
@end defun

@defun gcd n @dots{}
@defunx lcm n @dots{}
[R5RS]
@c EN
Returns the greatest common divisor or the least common multiplier
of the given integers, respectively
@c JP
与えられた整数の、最大公約数と最小公倍数をそれぞれ返します。
@c COMMON
@end defun

@defun numerator q
@defunx denominator q
[R5RS]
@c EN
Returns the numerator and denominator of a rational number @var{q}.
@c JP
有理数@var{q}の分子と分母をそれぞれ返します。
@c COMMON
@end defun


@defun floor x
@defunx ceiling x
@defunx truncate x
@defunx round x
[R5RS]
@c EN
The argument @var{x} must be a real number.
@code{Floor} and @code{ceiling} return a maximum integer that
isn't greater than @var{x} and a minimum integer that isn't less
than @var{x}, respectively.
@var{Truncate} returns an integer that truncates
@var{x} towards zero.  @var{Round} returns an integer that is closest
to @var{x}.  If fractional part of @var{x} is exactly 0.5, @var{round}
returns the closest even integer.
@c JP
引数@var{x}は実数でなければなりません。@code{floor}と@code{ceiling}はそれぞれ
@var{x}を越えない最大の整数と、@var{x}を下回らない最小の整数を返します。
@var{truncate}は@var{x}の小数部をゼロの方向に向かって切捨てた整数を返します。
@var{round}は@var{x}に最も近い整数を返します。@var{x}の
小数部が0.5ぴったりだった場合は@var{round}は最も近い偶数を返します。
@c COMMON
@end defun

@defun floor->exact x
@defunx ceiling->exact x
@defunx truncate->exact x
@defunx round->exact x
@c EN
These are convenience procedures of the popular 
phrase @code{(inexact->exact (floor x))} etc.
@c JP
これらは、頻出する@code{(inexact->exact (floor x))} 等を簡潔に書くための
手続きです。
@c COMMON
@end defun

@defun clamp x :optional min max
@c EN
Returns
@example
 @var{min} @r{if} @var{x} @code{<} @var{min}
 @var{x}   @r{if} @var{min} @code{<=} @var{x} @code{<=} @var{max}
 @var{max} @r{if} @var{max} @code{<} @var{x}
@end example
If @var{min} or @var{max} is omitted or @code{#f}, it is regarded
as @var{-infinity} or @var{+infinity}, respectively.
Returns an exact integer only if all the given numbers are exact integers.
@c JP
@example
 @var{min} @r{if} @var{x} @code{<} @var{min}
 @var{x}   @r{if} @var{min} @code{<=} @var{x} @code{<=} @var{max}
 @var{max} @r{if} @var{max} @code{<} @var{x}
@end example
を返します。もし@var{min}または@var{max}が省略されるか@code{#f}が与えられたら、
それぞれ @var{-∞} もしくは @var{+∞} と解釈されます。
与えられた全ての数値が正確な整数の場合に限り正確な整数を返します。
@c COMMON
@example
(clamp 3.1 0.0 1.0) @result{} 1.0
(clamp 0.5 0.0 1.0) @result{} 0.5
(clamp -0.3 0.0 1.0) @result{} 0.0
(clamp -5 0)        @result{} 0
(clamp 3724 #f 256) @result{} 256
@end example
@end defun


@defun exp z
@defunx log z
@defunx log z1 z2
@defunx sin z
@defunx cos z
@defunx tan z
@defunx asin z
@defunx acos z
@defunx atan z
[R5RS][R6RS]
@c EN
Transcendental functions.  Work for complex numbers as well.
@c JP
超越関数です。複素数も扱えます。
@c COMMON

@c EN
The two-argument version of @code{log} is added in R6RS, and returns
base-@var{z2} logarithm of @var{z1}.
@c JP
2引数の@code{log}はR6RSで追加されたもので、@var{z2}を底とした@var{z1}の対数を
返します。
@c COMMON
@end defun

@defun atan y x
[R5RS]
@c EN
For real numbers @var{x} and @var{y}, 
returns @code{(angle (make-rectangular x y))}.
@c JP
実数@var{x}と@var{y}に対して
@code{(angle (make-rectangular x y))}を返します。
@c COMMON
@end defun

@defun sinh z
@defunx cosh z
@defunx tanh z
@defunx asinh z
@defunx acosh z
@defunx atanh z
@c EN
Hyperbolic trigonometric functions.  Work for complex numbers as well.
@c JP
双曲線関数です。複素数も扱えます。
@c COMMON
@end defun

@defun sqrt z
[R5RS]
@c EN
Returns a square root of a complex number @var{z}.
The branch cut scheme is the same as Common Lisp.
For real numbers, it returns a positive root.

If @var{z} is the square of an exact real number, the return value
is also an exact number.
@c JP
複素数@var{z}の平方根のひとつを返します。枝刈りの定義はCommon Lispと同じです。
実数に対しては正の平方根を返します。

@var{z} が正確な実数の平方である場合、戻り値は正確数となります。
@c COMMON

@example
(sqrt 2)      @result{} 1.4142135623730951
(sqrt -2)     @result{} 0.0+1.4142135623730951i
(sqrt 256)    @result{} 16
(sqrt 256.0)  @result{} 16.0
(sqrt 81/169) @result{} 9/13
@end example
@end defun

@defun exact-integer-sqrt k
[R6RS]
@c EN
Given an exact nonnegative integer @var{k},
returns two exact nonnegative integer @var{s} and @var{r}
that satisfy the following equations:
@c JP
非負の正確な整数@var{k}に対し、次の式を満たす
非負の正確な整数@var{s}と@var{r}を返します。
@c COMMON

@example
@var{k} = (+ (* @var{s} @var{s}) @var{r})
@var{k} < (* (+ @var{s} 1) (+ @var{s} 1))
@end example

@example
(exact-integer-sqrt 782763574)
  @result{} 27977 @r{and} 51045
@end example
@end defun


@defun expt z1 z2
[R5RS]
@c EN
Returns @var{z1}^@var{z2} (@var{z1} powered by @var{z2}),
where @var{z1} and @var{z2} are complex numbers.
@c JP
複素数@var{z1}, @var{z2}に対して、
@var{z1}^@var{z2} (@var{z1}の@var{z2}乗)を返します。
@c COMMON
@end defun

@c NB: These should be moved to a separate subsection once we got
@c more fixnum-specific operation support.

@defun fixnum-width
@defunx greatest-fixnum
@defunx least-fixnum
[R6RS]
These procedures return the width of fixnum (@var{w}),
the greatest integer representable by fixnum (@var{2^w - 1}),
and the least integer representable by fixnum (@var{- 2^w}),
respectively.  You might want to care the fixnum range when
you are writing a performance-critical section.

These names are defined in R6RS.  Common Lisp and ChezScheme have
@code{most-positive-fixnum} and @code{most-negative-fixnum}.
@end defun

@node Numerical conversions, Bitwise operations, Arithmetics, Numbers
@subsection Numerical conversions
@c NODE 数値の変換

@defun make-rectangular x1 x2
@defunx make-polar x1 x2
[R5RS]
@c EN
Creates a complex number from two real numbers, @var{x1} and @var{x2}.
@code{make-rectangular} returns @var{x1} + @b{i}@var{x2}.
@code{make-polar} returns @var{x1}@b{e}^(@b{i}@var{x2}).
@c JP
二つの実数@var{x1}と@var{x2}から複素数を作ります。
@code{make-rectangular} は @var{x1} + @b{i}@var{x2} を返します。
@code{make-polar} は @var{x1}@b{e}^(@b{i}@var{x2}) を返します。
@c COMMON
@end defun

@defun real-part z
@defunx imag-part z
@defunx magnitude z
@defunx angle z
[R5RS]
@c EN
Decompose a complex number @var{z} and returns a real number.
@code{real-part} and @code{imag-part} return @var{z}'s real and imaginary
part, respectively.  @code{magnitude} and @code{angle} return
@var{z}'s magnitude and angle, respectively.
@c JP
複素数@var{z}を取り、実数を返します。
@code{real-part}と@code{imag-part}は@var{z}の実数部と虚数部をそれぞれ返し、
@code{magnitude}と@code{angle}は@var{z}の絶対値と偏角をそれぞれ返します。
@c COMMON
@end defun

@defun decode-float x
@c EN
For a given floating-point number, returns
a vector of three exact integers, @code{#(@var{m}, @var{e}, @var{sign})},
where
@example
  @var{x} = (* @var{sign} @var{m} (expt 2.0 @var{e}))
  @var{sign} is either 1, 0 or -1.
@end example
The API is taken from ChezScheme.
@c JP
与えられた浮動小数点数@var{x}に対して、
3つの正確な整数からなるベクタ @code{#(@var{m}, @var{e}, @var{sign})}
を返します。ここで、
@example
  @var{x} = (* @var{sign} @var{m} (expt 2.0 @var{e}))
  @var{sign} は 1, 0 または -1.
@end example
です。このAPIはChezSchemeから取られました。
@c COMMON
@example
(decode-float 3.1415926)
 @result{} #(7074237631354954 -51 1)
(* 7074237631354954 (expt 2.0 -51))
 @result{} 3.1415926
@end example
@end defun

@defun fmod x y
@defunx modf x
@defunx frexp x
@defunx ldexp x n
[POSIX] 
@c EN
These procedures can be used to compose and decompose floating
point numbers.  @code{Fmod} computes the remainder of dividing @var{x}
by @var{y}, that is, it returns @var{x}-@var{n}*@var{y} where
@var{n} is the quotient of @var{x}/@var{y} rounded towards zero
to an integer.   @code{Modf} returns two values; a fractional
part of @var{x} and an integral part of @var{x}.   @code{Frexp}
returns two values, @var{fraction} and @var{exponent} of @var{x},
where @var{x} = @var{fraction} * 2^@var{exponent}, and
0 <= @var{fraction} <= 0.5.  @var{Ldexp} is a reverse operation of 
@code{frexp}; it returns a real number @var{x} * 2^@var{n}.
@c JP
これらの手続きは、浮動小数点数を分解したり合成するのに使えます。
@code{fmod}は実数@var{x}を実数@var{y}で割った余りを返します。すなわち、
@var{x}/@var{y}を0に近いほうの整数に丸めた値を@var{n}とするとき、
@var{x}-@var{n}*@var{y}を返します。
@code{modf}は@var{x}の少数部と整数部を返します。
@code{frexp}は実数@var{x}を、仮数部と指数部に分解して返します。すなわち、
@var{x} = @var{fraction} * 2^@var{exponent} かつ 0 <= @var{fraction} <= 0.5
であるところの@var{fraction}と@var{exponent}を返します。
@code{ldexp}は@code{frexp}の逆関数で、@var{x} * 2^@var{n} を返します。
@c COMMON
@example
(fmod 32.1 10.0)  @result{} 2.1
(fmod 1.5 1.4)    @result{} 0.1
(modf 12.5)       @result{} 0.5 @r{and} 12.0
(frexp 3.14)      @result{} 0.785 @r{and} 2
(ldexp 0.785 2)   @result{} 3.14
@end example
@end defun

@defun exact z
@defunx inexact z
[R6RS]
@c EN
Returns an exact or an inexact representation of the
given number @var{z}, respectively.

Since we have finite precision to represent floating numbers,
it is always possible to convert arbitrary inexact real number
to an exact rational number.  It may not be what you want, though.
See the following example:
@c JP
それぞれ数@var{z}の正確な表現および不正確な表現を返します。

浮動小数点数の表現が有限精度であるため、任意の不正確な実数を正確な
有理数に変換することは常に可能です。しかしそれはあなたの求めるもの
ではないかもしれません。次の例を見てください。
@c COMMON

@example
(exact 3.1415926535879)
  @result{} 7074237752024177/2251799813685248
@end example

@c EN
If you intend to obtain an exact integer by rounding an inexact
real number, you have to use one of @code{floor}, @code{ceiling},
@code{truncate} or @code{round} explicitly.  You may also use
@code{floor->exact}, @code{round->exact} etc.
@c JP
不正確な実数を丸めた正確な整数が欲しい場合は、@code{floor}、@code{ceiling}、
@code{truncate}もしくは@code{round}を明示的に使って下さい。
@code{floor->exact}、@code{round->exact}等を使うという手もあります。
@c COMMON

@example
(exact (round 3.1415926535879)) @result{} 3

(round->exact 3.1415926535879)  @result{} 3
@end example

@c EN
Gauche doesn't support exact complex numbers.  Passing an inexact
complex number with non-zero imaginary part to @code{exact}
causes an error.
@c JP
Gaucheは正確な複素数をサポートしません。虚数部がゼロでない不正確な
複素数を@code{exact}に渡すとエラーとなります。
@c COMMON
@end defun

@defun exact->inexact z
@defunx inexact->exact z
[R5RS]
@c EN
Converts exact number to inexact one, and vice versa.

In fact, @code{exact->inexact} returns the argument as is
if an inexact number is passed, and @code{inexact->exact}
returns the argument if an exact number is passed, so
in Gauche they are equivalent to @code{inexact} and @code{exact},
respectively.  Note that other R5RS implementation may raise
an error if passing an inexact number to @code{exact->inexact},
for example.

Generally @code{exact} and @code{inexact} are preferred,
for they are more concise, and you don't need to care
whether the argument is exact or inexact numbers.
These procedures are for compatibility with R5RS programs.
@c JP
それぞれ、正確数を非正確に変換、あるいはその逆を行います。

不正確な数を@code{exact->inexact}に渡したり、または正確な数を
@code{inexact->exact}に渡した場合、Gaucheではそれをエラーにせず
引数をそのまま返します。従ってこれらはGaucheでは
上の@code{inexact}および@code{exact}とそれぞれ等価です。
R5RS実装の中には、非正確数を@code{exact->inexact}に渡したりすると
エラーになるものもあり得るので、ポータブルなコードを書く場合は
注意してください。

一般的には、@code{exact}および@code{inexact}を使う方が
簡潔で良いでしょう。こちらの手続きはR5RSプログラムとの互換性の
ために用意されています。
@c COMMON
@end defun

@defun number->string z :optional radix use-upper?
@defunx string->number string :optional radix
[R5RS+]
@c EN
These procedures convert a number and its string representation
in radix @var{radix} system.
@var{radix} must be between 2 and 36 inclusive.
If @var{radix} is omitted, 10 is assumed.

@code{Number->string} takes a number @var{z} and returns a string.
If @var{z} is not an exact integer, @var{radix} must be 10.
For the numbers with radix more than 10, lower case alphabet
character is used for digits, unless the optional argument
@var{use-upper?} is true, in that case upper case characters are used.
The argument @var{use-upper?} is Gauche's extension.

@code{String->number} takes a string @var{string} and parses it
as a number in radix @var{radix} system.  If the number looks like
non-exact number, only radix 10 is allowed.  If the given string
can't be a number, @code{#f} is returned.
@c JP
これらの手続きは数値とそれを@var{radix}進数で表現する文字列とを変換します。
@var{radix}は2から36の間でなければなりません。省略された場合は10進数とみなされます。

@code{number->string}は数値@var{z}を取り文字列を返します。
@var{z}が正確な整数以外の場合、@var{radix}は10でなければなりません。
10より大きい@var{radix}に関しては、小文字のアルファベットが桁として使われます。
但し、省略可能な引数@var{use-upper?}に真の値が与えられた場合は大文字のアルファベットが
使われます。@var{use-upper?}引数はGaucheの拡張です。

@code{string->number}は文字列@var{string}を取り数値を返します。
不正確な数値は10進数表記しか認識されません。与えられた文字列が数値を構成しない
場合は@code{#f}が返されます。
@c COMMON
@end defun

@deffn {Generic Function} x->number obj
@deffnx {Generic Function} x->integer obj
@c EN
Generic coercion functions.  Returns `natural' interpretation of @var{obj}
as a number or an exact integer, respectively.
The default methods are defined for numbers and strings; a string is
interpreted by @var{string->number}, and if the string can't be
interpreted as a number, 0 is returned.
Other @var{obj} is simply converted to 0.
If @var{obj} is naturally interpreted
as a number that is not an exact integer, @code{x->integer} uses
@code{round} and @code{inexact->exact} to obtain an integer.

Other class may provide a method to customize the behavior.
@c JP
数値への強制型変換手続きです。
@var{obj}をそれぞれ数値もしくは正確な整数と解釈して返します。
数値と文字列に対してのメソッドは定義されています
(文字列は@var{string->number}を使って変換されます。
数値として解釈できない文字列に関しては0が返されます)。
その他の@var{obj}については単に0が返されます。
@code{x->integer}は、@var{obj}が数値として表現できるけれど正確な整数では
ない場合、@code{round}と@code{inexact->exact}によって正確な整数に変換します。

他のクラスはこのメソッドを定義することにより、独自の変換関数を提供することができます。
@c COMMON
@end deffn

@node Bitwise operations, Endianness, Numerical conversions, Numbers
@subsection Bitwise operations
@c NODE ビット演算

@c EN
These procedures treat integers as half-open bit vectors.
If an integer is positive, it is regarded as if infinite number
of zeros are padded to the left.  If an integer is negative,
it is regarded in 2's complement form, and infinite number of
1's are padded to the left.
@c JP
これらの手続きは整数を半無限のビットベクタとして扱います。
正の整数の場合、数値の左側に無限に0が続いていると見倣されます。
負の整数の場合、数値は2の補数で表現され、左側に無限に1が続いていると見倣されます。
@c COMMON

@c EN
In regard to the names of those operations, there are two groups
in the Scheme world; Gauche follows the names of the 
original SLIB's ``logical'' module, which was rooted in CL.
Another group uses a bit long but descriptive name such as
@code{arithmetic-shift}.
@c JP
これらの操作の名前に関しては、Scheme界には大きく二つの流儀があります。
GaucheはSLIBの元々の``logical''モジュールに合わせました。
その起源はCommon Lispです。
もう一つの流儀では、@code{arithmetic-shift}といった、より長く記述的な名前を使います。
@c COMMON

@c EN
SRFI-60 (@xref{Integers as bits}) defines both names, and also
some additional procedures.  If you're porting libraries written
for other Scheme, you might want to check it.
@c JP
SRFI-60 (@xref{Integers as bits}) は両方の流儀の名前を定義しており、
さらにいくつかの追加の手続きも用意しています。他のScheme向けに書かれた
コードをGaucheに移植する際には有用でしょう。
@c COMMON

@defun ash n count
[SRFI-60]
@c EN
Shifts integer @var{n} left with @var{count} bits.
If @var{count} is negative, @code{ash} shifts @var{n} right with
@minus{}@var{count} bits.
@c JP
整数@var{n}を左に整数@var{count}ビットだけシフトします。
@var{count}が負であれば、@minus{}@var{count}だけ@var{n}を右にシフトします。
@c COMMON

@example
; @r{Note: 6  @equiv{} [...00110], and}
; @r{      -6 @equiv{} [...11010]}
(ash 6 2)   @result{} 24  ;@r{[...0011000]}
(ash 6 -2)  @result{} 1   ;@r{[...0000001]}
(ash -6 2)  @result{} -24 ;@r{[...1101000]}
(ash -6 -2) @result{} -2  ;@r{[...1111110]}
@end example
@end defun
        
@defun logand n1 @dots{}
@defunx logior n1 @dots{}
@defunx logxor n1 @dots{}
[SRFI-60]
@c EN
Returns bitwise and, bitwise inclusive or and bitwise exclusive or
of integers @var{n1} @dots{}.   If no arguments are given, @code{logand}
returns @code{-1}, and @code{logior} and @code{logxor} returns @code{0}.
@c JP
整数@var{n1} @dots{}の、それぞれビット論理積、
ビット論理和、ビット排他的論理積を返します。
ゼロ個の引数が与えられた場合は、@code{logand}は@code{-1}を、
@code{logior}と@code{logxor}は@code{0}を返します。
@c COMMON
@end defun

@defun lognot n
[SRFI-60]
@c EN
Returns bitwise not of an integer @var{n}.
@c JP
整数@var{n}のビット否定を返します。
@c COMMON
@end defun

@defun logtest n1 n2 @dots{}
[SRFI-60]
@equiv{} @code{(not (zero? (logand @var{n1} @var{n2} @dots{})))}
@end defun

@defun logbit? index n
[SRFI-60]
@c EN
Returns @code{#t} if @var{index}-th bit of integer @var{n} is 1, 
@var{#f} otherwise.
@c JP
整数@var{n}の@var{index}目のビットが1ならば@code{#t}を、0ならば@code{#f}を
返します。
@c COMMON
@end defun

@defun bit-field n start end
[SRFI-60]
@c EN
Extracts @var{start}-th bit (inclusive) to @var{end}-th bit (exclusive) from
an exact integer @var{n}, where @var{start} < @var{end}.
@c JP
整数@var{n}の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までを
取り出した数値を返します。@var{start} < @var{end} でなければなりません。
@c COMMON
@end defun

@defun copy-bit index n bit
[SRFI-60]
@c EN
If @var{bit} is true, sets @var{index}-th bit of an exact integer @var{n}.
If @var{bit} is false, resets @var{index}-th bit of an exact integer @var{n}.
@c JP
@var{bit}が真の値なら、整数@var{n}の@var{index}ビット目をセットした数値を
返します。
@var{bit}が偽の値なら、整数@var{n}の@var{index}ビット目をリセットした数値を
返します。
@c COMMON
@end defun

@defun copy-bit-field n start end from
[SRFI-60]
@c EN
Returns an exact integer, each bit of which is the same as
@var{n} except the @var{start}-th bit (inclusive) to @var{end}-th
bit (exclusive), which is a copy of the lower
@code{(@var{end}-@var{start})}-th bits of an exact
integer @var{from}.
@c JP
正確な整数を返します。この整数の各ビットは@var{start}番目のビット(この
ビットを含む)から@var{end}番目のビット(このビットは含まない)の部分以外
は@var{n}と同じで、この区間のビットは、正確な数@var{from}の下位
@code{(@var{end}-@var{start})}ビットのコピーです。
@c COMMON

@example
(number->string (copy-bit-field #b10000000 1 5 -1) 2)
  @result{} "10011110"

(number->string (copy-bit-field #b10000000 1 7 #b010101010) 2)
  @result{} "11010100"
@end example
@end defun

@defun logcount n
[SRFI-60]
@c EN
If @var{n} is positive, returns the number of @code{1}'s in the
bits of @var{n}.  If @var{n} is negative, 
returns the number of @code{0}'s in the bits of 2's complement
representation of @var{n}.
@c JP
@var{n}が正なら、@var{n}のビットのうち@code{1}の個数を返します。@var{n}
が負なら、@var{n}の2に関する補数のビットのうち@code{0}の個数を返します。
@c COMMON

@c EN
@example
(logcount 0)      @result{} 0
(logcount #b0010) @result{} 1
(logcount #b0110) @result{} 2
(logcount #b1111) @result{} 4

(logcount #b-0001) @result{} 0  ;; 2's complement:  ....111111
(logcount #b-0010) @result{} 1  ;; 2's complement:  ....111110
(logcount #b-0011) @result{} 1  ;; 2's complement:  ....111101
(logcount #b-0100) @result{} 2  ;; 2's complement:  ....111100
@end example
@c JP
@example
(logcount 0)      @result{} 0
(logcount #b0010) @result{} 1
(logcount #b0110) @result{} 2
(logcount #b1111) @result{} 4

(logcount #b-0001) @result{} 0  ;; 2の補数:  ....111111
(logcount #b-0010) @result{} 1  ;; 2の補数:  ....111110
(logcount #b-0011) @result{} 1  ;; 2の補数:  ....111101
(logcount #b-0100) @result{} 2  ;; 2の補数:  ....111100
@end example
@c COMMON
@end defun

@defun integer-length n
[SRFI-60]
@c EN
Returns the minimum number of bits required to represent an
exact integer @var{n}.  Negative integer is assumed to be in
2's complement form.  A sign bit is not considered.
@c JP
正確な整数@var{n}を表現するのに必要な最小ビット数を返します。負の数は2
の補数で表現されるものと仮定しています。符号用のビットは考慮しません。
@c COMMON

@example
(integer-length 255)  @result{} 8
(integer-length 256)  @result{} 9

(integer-length -256)  @result{} 8
(integer-length -257)  @result{} 9
@end example
@end defun

@node Endianness,  , Bitwise operations, Numbers
@subsection Endianness
@c NODE エンディアン

@c EN
In the Scheme world you rarely need to know about how the numbers
are represented inside the machine.  However, it matters
when you have to exchange data to/from the outer world in
binary representation.
@c JP
Schemeの世界では、数値がマシン上でどのように表現されているかを気にする
必要はほとんどありません。しかし、外の世界とバイナリ表現でデータを
やりとりする場合はそれが問題になります。
@c COMMON

@c EN
Gauche's binary I/O procedures, such as in
the @code{binary.io} module (@xref{Binary I/O}) and
@code{write-block}/@code{read-block!}
(@xref{Uniform vectors}), take optional @var{endian} argument
to specify the endianness.
@c JP
@code{binary.io}モジュール(@ref{Binary I/O}参照)や
@code{write-block}/@code{read-block!}(@ref{Uniform vectors}参照)
等、Gaucheのバイナリ入出力手続きはエンディアンを指定する
省略可能な@var{endian}引数を取ります。
@c COMMON

@c EN
Currently Gauche recognizes the following endiannesses.
@c JP
エンディアンの指定には次のシンボルを使います。
@c COMMON

@table @code
@item big-endian
@c EN
Big endian.  With this endianness, a 32-bit integer @code{#x12345678}
will be written out as an octet sequence @code{#x12 #x34 #x56 #x78}.
@c JP
ビッグエンディアン。32ビット整数値@code{#x12345678}は@code{#x12 #x34 #x56 #x78}
のようなバイトシーケンスとして出力されます。
@c COMMON
@item little-endian
@c EN
Little endian.  With this endianness, a 32-bit integer @code{#x12345678}
is written out as an octet sequence @code{#x78 #x56 #x34 #x12}.
@c JP
リトルエンディアン。32ビット整数値@code{#x12345678}は@code{#x78 #x56 #x34 #x12}
のようなバイトシーケンスとして出力されます。
@c COMMON
@item arm-little-endian
@c EN
This is a variation of @code{little-endian}, and used in ARM
processors in some specific modes.  It works just like @code{little-endian},
except reading/writing double-precision floating point number (@code{f64}),
which is written as two little-endian 32bit words ordered by big-endian
(e.g. If machine register's representation is @code{#x0102030405060708},
it is written as @code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}.
@c JP
これは@code{little-endian}のバリエーションで、ARMプロセッサの
特定のモードで使われるものです。倍精度浮動小数点数以外は@code{little-endian}
と同様に動作します。倍精度浮動小数点数については、ふたつのリトルエンディアンワードが
ビッグエンディアンの順で書き出されます (例えばマシンレジスタ上でのビットパターンが
@code{#x0102030405060708}の場合、出力は
@code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}となります)。
@c COMMON
@end table

@c EN
When the @var{endian} argument is omitted, those procedures
use the parameter @code{default-endian}:
@c JP
@var{endian}引数が省略された場合は、これらの手続きはパラメータ@code{default-endian}の
値を使います。
@c COMMON

@deffn {Parameter} default-endian
@c EN
This is a dynamic parameter (@xref{Parameters}) to specify
the endianness the binary I/O routines use when its @var{endian}
argument is omitted.  The initial value of this parameter is
the system's native endianness.
@c JP
これは、バイナリ入出力ルーチンで@var{endian}指定が省略された場合に
共通して使われるエンディアンを指定する動的パラメータです
(@ref{Parameters}参照)。
このパラメータの初期値はシステムのネイティブエンディアンです。
@c COMMON
@end deffn

@c EN
The system's native endianness can be queried with the following
procedure:
@c JP
システムのネイティブエンディアンは次の手続きで得られます。
@c COMMON

@defun native-endian
@c EN
Returns a symbol representing the system's endianness.
@c JP
システムのエンディアンを示すシンボルを返します。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Booleans, Undefined values, Numbers, Core library
@section Booleans
@c NODE 論理値

@deftp {Builtin Class} <boolean>
@clindex boolean
@c EN
A boolean class.  Only @code{#t} and @code{#f} belong to this class.
@c JP
論理値のクラスです。@code{#t}と@code{#f}のみがこのクラスのインスタンスです。
@c COMMON
@end deftp

@defun not obj
[R5RS]
@c EN
Returns @code{#t} if and only if @var{obj} is @code{#f},
and returns @code{#f} otherwise.
@c JP
@var{obj}が@code{#f}の時のみ@code{#t}を返し、それ以外の場合は@code{#f}を
返します。
@c COMMON
@end defun

@defun boolean? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a boolean value.
@c JP
@var{obj}が論理値である場合に@code{#t}を返します。
@c COMMON
@end defun

@defun boolean obj
@c EN
Returns @code{#f} iff @var{obj} is @code{#f}, and returns @code{#t}
otherwise.  Convenient to coerce a value to boolean.
@c JP
@var{obj}が@code{#f}であるとき@code{#f}を返し、それ以外の場合は@code{#t}を
返します。値を論理値に変換したい場合に便利です。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Undefined values, Pairs and Lists, Booleans, Core library
@section Undefined values
@c NODE 未定義値

@c EN
While working with Gauche, sometimes you encounter 
a value printed as @code{#<undef>}, an @emph{undefined} value.
@c JP
Gaucheで作業していると、しばしば未定義値 @code{#<undef>} 
に出会うことがあるでしょう。
@c COMMON

@example
gosh> (if #f #t)
#<undef>
@end example

@c EN
It is a value used as a filler where the actual value doesn't matter,
or to indicate there's no other suitable value.
@c JP
この値は、値そのものに意味が無いこと、あるいは
とりたててほかにふさわしい値が無いことを意味します。
@c COMMON

@c EN
Do not confuse undefined values with unbound variables;
A variable can be bound to @code{#<undef>}, for it is just 
an ordinaly first-class value.  On the other hand, an 
unbound variable means there's no value associated with the variable.
@c JP
未定義値と未束縛の変数を混同しないようにしてください。
@code{#<undef>}は通常の第一級の値であり、変数に束縛しておくこともできます。
未束縛の変数は文字通り、変数が束縛されていない、すなわち値を持たないことを意味します。
@c COMMON

@c EN
However, @code{#<undef>} may be used in certain 
occasions to indicate that a value is not provided for
the variable.  For example, an optional procedure parameter
without default value is bound to @code{#<undef>} if an
actual argument is not given (@xref{Making Procedures}).
Note that it cannot be distinguished from the case 
a value is actually provided, and the value just happens
to be @code{#<undef>}.  If you get an @code{#<undef>},
you can say at most is that the value doesn't matter.
You shouldn't let it carry too much meanings.
@c JP
しかし、場合によっては、変数に特定の値が提供されていないことを
示すのに@code{#<undef>}が使われることもあります。
例えば、既定値をもたない省略可能引数に実引数が提供されなかった
場合、引数の値は@code{#<undef>}となります (@ref{Making Procedures}参照)。
これは実際に@code{#<undef>}が引数として渡された場合と区別がつかない
ことに注意してください。@code{#<undef>}を受け取ってわかることは、
せいぜいその値にたいした意味がないということくらいです。
@code{#<undef>}に大きな意味を持たせすぎないようにしましょう。
@c COMMON

@c EN
Being said that, there are a couple of procedures
to deal with undefined values.
@c JP
以上の注意を念頭においた上で、未定義値を扱うには
次の手続きが利用できます。
@c COMMON

@defun undefined? obj
@c EN
Returns @code{#t} iff @var{obj} is an undefined value.
@c JP
@var{obj}が未定義値である場合に限り@code{#t}を返します。
@c COMMON
@end defun

@defun undefined
@c EN
Returns an undefined value.
@c JP
未定義値を返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Pairs and Lists, Symbols, Undefined values, Core library
@section Pairs and Lists
@c NODE ペアとリスト

@c EN
Pairs and lists are one of the most fundamental data structure in Scheme.
Gauche core provides all standard list procedures, plus some useful
procedures that are commonly supported in lots of implementations.
If they are not enough, you can find more procedures in the modules
described in @ref{List library}, 
@ref{Additional list library}, and
@ref{Combination library}.
See also @ref{Collection framework} and
@ref{Sequence framework} for generic collection/sequence
operations.
@c JP
ペアとリストはSchemeにおける最も基本的なデータ構造のひとつです。
Gaucheのコアは全ての標準のリスト手続きと、多くのScheme実装に見られる
便利な手続きのいくつかを提供します。それらで足りない場合は
さらに多くの手続きが@ref{List library}、
@ref{Additional list library}、
@ref{Combination library}
といったモジュールで提供されています。
また、リストに限らないジェネリックなシーケンス/コレクションの操作が
@ref{Collection framework}と
@ref{Sequence framework}で提供されています。
@c COMMON

@menu
* Pair and null class::         
* List predicates::             
* List constructors::           
* List accessors and modifiers::  
* Other list procedures::       
@end menu

@node Pair and null class, List predicates, Pairs and Lists, Pairs and Lists
@subsection Pair and null class
@c NODE pairクラスとnullクラス

@deftp {Builtin Class} <list>
@clindex list
@c EN
An abstract class represents lists.   A parent class of @code{<null>}
and @code{<pair>}.   Inherits @code{<sequence>}.

Note that a circular list is also an instance of the @code{<list>} class,
while R5RS procedure @code{list?} returns false on the circular lists and
dotted lists.
@c JP
リストを表す抽象クラスで、クラス@code{<null>}とクラス@code{<pair>}の親クラスです。
クラス@code{<sequence>}を継承します。

循環リストやドットリストも@code{<list>}クラスのインスタンスですが、
@code{list?}は偽の値を返すことに注意して下さい。
@c COMMON
@lisp
(use srfi-1)
(list? (circular-list 1 2)) @result{} #f
(is-a? (circular-list 1 2) <list>) @result{} #t
@end lisp
@end deftp

@deftp {Builtin Class} <null>
@clindex null
@c EN
A class of empty list.  @code{()} is the only instance.
@c JP
空リストのクラスです。@code{()}がこのクラスの唯一のインスタンスです。
@c COMMON
@end deftp

@deftp {Builtin Class} <pair>
@clindex pair
@c EN
A class of pairs.
@c JP
ペアのクラスです。
@c COMMON
@end deftp

@node List predicates, List constructors, Pair and null class, Pairs and Lists
@subsection List predicates
@c NODE リストに関する述語

@defun pair? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a pair, @code{#f} otherwise.
@c JP
@var{obj}がペアなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun null? obj
[R5RS] 
@c EN
Returns @code{#t} if @var{obj} is an empty list, @code{#f} otherwise.
@c JP
@var{obj}が空リストなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun list? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a proper list, @code{#f} otherwise.
This function returns @code{#f} if @var{obj} is a dotted or circular list.

See also @code{proper-list?}, @code{circular-list?} and
@code{dotted-list?} in @ref{SRFI-1 List predicates}.
@c JP
@var{obj}が正しいリストなら@code{#t}を、そうでなければ@code{#f}を返します。
この手続きは@var{obj}がドットリストや循環リストなら@var{#f}を返します。

SRFI-1(@ref{SRFI-1 List predicates})には更に、
@code{proper-list?}、@code{circular-list?}、@code{dotted-list?}
といった手続きが定義されています。
@c COMMON
@end defun

@node List constructors, List accessors and modifiers, List predicates, Pairs and Lists
@subsection List constructors
@c NODE リストの作成

@defun cons obj1 obj2
[R5RS] 
@c EN
Constructs a pair of @var{obj1} and @var{obj2} and returns it.
@c JP
@var{obj1}と@var{obj2}のペアを作成します。
@c COMMON
@lisp
(cons 'a 'b) @result{} (a . b)
@end lisp
@end defun

@defun acons obj1 obj2 obj3
@c EN
Returns @code{(cons (cons @var{obj1} @var{obj2}) @var{obj3})}.
Useful to put an entry at the head of an associative list.
@c JP
@code{(cons (cons @var{obj1} @var{obj2}) @var{obj3})} を返します。
連想リストの先頭に新しいエントリを加えるのに便利です。
@c COMMON
@lisp
(acons 'a 'b '((c . d))) @result{} ((a . b) (c . d))
@end lisp
@end defun

@defun make-list len :optional fill
[SRFI-1]
@c EN
Makes a proper list of length @var{len}.  If optional argument
@var{fill} is provided, each element is initialized by it.  Otherwise
each element is undefined.
@c JP
長さ@var{len}の正規のリストを返します。引数@var{fill}が与えられていれば、各要素は
@var{fill}になります。そうでなければ各要素の値は不定です。
@c COMMON
@lisp
(make-list 5 #t) @result{} (#t #t #t #t #t)
@end lisp
@end defun

@defun list obj @dots{}
[R5RS]
@c EN
Makes a list, whose elements are @var{obj} @dots{}.
@c JP
要素が@var{obj} @dots{}であるリストを作成します。
@c COMMON
@lisp
(list 1 2 3) @result{} (1 2 3)
(list) @result{} ()
@end lisp
@end defun

@defun list* obj1 obj2 @dots{}
@c EN
Like @code{list}, but the last argument becomes cdr of the last pair.
SRFI-1 defines the same function with the name @code{cons*}.
@c JP
@code{list}とほぼ同じですが、最後の引数が作成されるリストの最後のペアのcdrになります。
SRFI-1ではこの手続きが@code{cons*}という名で定義されています。
@c COMMON
@lisp
(list* 1 2 3) @result{} (1 2 . 3)
(list* 1) @result{} 1
@end lisp
@end defun

@defun list-copy list
[SRFI-1]
@c EN
Shallow copies @var{list}.  If @var{list} is circular,
this function diverges.
@c JP
@var{list}の浅いコピーを行います。
@var{list}が循環リストの場合、この手続きは停止しません。
@c COMMON
@end defun


@node List accessors and modifiers, Other list procedures, List constructors, Pairs and Lists
@subsection List accessors and modifiers
@c NODE リストへのアクセスと変更

@defun car pair
@defunx cdr pair
[R5RS] 
@c EN
Returns car and cdr of @var{pair}, respectively.
@c JP
それぞれ@var{pair}のcarとcdrを返します。
@c COMMON
@end defun

@defun set-car! pair obj
@defunx set-cdr! pair obj
[R5RS] 
@c EN
Modifies car and cdr of @var{pair}, by @var{obj}, respectively.

Note: @code{(setter car)} @equiv{} @code{set-car!}, and
@code{(setter cdr)} @equiv{} @code{set-cdr!}.
@c JP
@var{pair}のcarもしくはcdrを@var{obj}で置き換えます。

注： @code{(setter car)} @equiv{} @code{set-car!} であり、
@code{(setter cdr)} @equiv{} @code{set-cdr!} です。
@c COMMON
@end defun

@defun caar pair
@defunx cadr pair
@findex cdar
@findex cddr
@findex caaar
@findex caadr
@findex cadar
@findex caddr
@findex cdaar
@findex cdadr
@findex cddar
@findex cdddr
@findex caaaar
@findex caaadr
@findex caadar
@findex caaddr
@findex cadaar
@findex cadadr
@findex caddar
@findex cadddr
@findex cdaaar
@findex cdaadr
@findex cdadar
@findex cdaddr
@findex cddaar
@findex cddadr
@dots{}
@end defun
@defun cdddar pair
@defunx cddddr pair
[R5RS]
@c EN
@code{caar} @equiv{} @code{(car (car x))},
@code{cadr} @equiv{} @code{(car (cdr x))}, and so on.

The corresponding setters are also defined.
@c JP
@code{caar} @equiv{} @code{(car (car x))},
@code{cadr} @equiv{} @code{(car (cdr x))}, 等々。

対応するsetterも定義されています。
@c COMMON
@example
(let ((x (list 1 2 3 4 5)))
  (set! (caddr x) -1)
  x)
  @result{} (1 2 -1 4 5)
@end example
@end defun

@defun length list
[R5RS]
@c EN
Returns the length of a proper list @var{list}.
If @var{list} is a dotted list, an error is signalled.
If @var{list} is a circular list, this function diverges.

If you want to handle circular lists as well, 
See @code{length+} in @ref{SRFI-1 List miscellaneous routines}.
@c JP
正規のリスト@var{list}の長さを返します。
@var{list}がドットリストならばエラーが起きます。
@var{list}が循環リストの場合、この関数は無限ループします。

循環リストも取り扱う場合は、SRFI-1の@code{length+}を使って下さい
(@ref{SRFI-1 List miscellaneous routines}参照)。
@c COMMON
@end defun

@defun list-tail list k :optional fallback
[R5RS]
@c EN
Returns @var{k}-th cdr of @var{list}.
@var{list} can be a proper, dotted or circular list.
(If @var{list} is a dotted list, its last @code{cdr} is simply ignored).

If @var{k} is negative or larger than the length of @var{list},
the behavior depends on whether the optional @var{fallback} argument
is given or not.  If @var{fallback} is given, it is returned.
Otherwise, an error is signalled.
@c JP
@var{list}の@var{k}番目のcdrを返します。@var{list}は
正規のリストでもドットリストでも循環リストでも構いません。
(@var{list}がドットリストの場合、最後の@code{cdr}は無視されます)。

@var{k}の値が負であったり@var{list}の長さ以上の場合、
@var{fallback}引数が与えられていればそれが返され、
そうでなければエラーが報告されます。
@c COMMON
@end defun

@defun list-ref list k :optional fallback
[R5RS+]
@c EN
Returns @var{k}-th element of @var{list}.
@var{list} can be a proper, dotted or circular list.

By default, @code{list-ref} signals an error if @var{k} is
negative, or greater than or equal to the length of @var{list}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.  This is an extension of Gauche.
@c JP
@var{list}の@var{k}番目の要素を返します。@var{list}は
正規のリストでもドットリストでも循環リストでも構いません。

もし@var{k}がリストの長さを超えていたり、負数であった場合は通常はエラーが起こります。
しかし、オプショナルな引数@var{fallback}が与えられていた場合は、エラーは起きず
@var{fallback}が返されます。これはGaucheの拡張です。
@c COMMON
@end defun

@defun last-pair list
[SRFI-1]
@c EN
Returns the last pair of @var{list}.
@var{list} can be a proper or dotted list.
@c JP
@var{list}の最後のペアを返します。@var{list}は
正規のリストかドットリストです。
@c COMMON
@end defun

@node Other list procedures,  , List accessors and modifiers, Pairs and Lists
@subsection Other list procedures
@c NODE 他のリスト手続き

@defun append list @dots{}
[R5RS]
@c EN
Returns a list consisting of the elements of the first @var{list} followed by
the elements of the other lists.  The resulting list is always newly
allocated, except that it shares structure with the last list argument.
The last argument may actually be any object; an improper list results
if the last argument is not a proper list. 
@c JP
渡されたリストの要素を繋げたリストを返します。最後の引数の部分以外は新しいセルがアロケート
されて使われます。最後の引数は正規のリストである必要がありません。その場合、結果は正規でない
リストとなります。
@c COMMON
@end defun

@defun append! list @dots{}
[SRFI-1]
@c EN
Returns a list consisting of the elements of the first @var{list} followed by
the elements of the other lists.  The cells in the lists except the last
one may be reused to construct the result.   The last argument may be
any object.
@c JP
渡されたリストの要素を繋げたリストを返します。最後の引数以外のリストのセルは、結果を
作成するために再利用されるかもしれません。
最後の引数は正規のリストである必要はありません。
@c COMMON
@end defun


@defun reverse list
[R5RS]
@c EN
Returns a newly allocated list consisting of the elements of @var{list}
in reverse order.
@c JP
@var{list}の各要素を逆順に持つリストを新しく作成して返します。
@c COMMON
@end defun

@defun reverse! list
[SRFI-1]
@c EN
Returns a list consisting of the elements of @var{list} in reverse order.
The cells of @var{list} may be reused to construct the returned list.
@c JP
@var{list}の各要素を逆順に持つリストを返します。結果を作成するために、
@var{list}のセルは再利用されるかもしれません。
@c COMMON
@end defun

@defun memq obj list
@defunx memv obj list
@defunx member obj list
[R5RS]
@c EN
Searches @var{obj} in the @var{list}.  If @code{n}-th element of
@var{list} equals to @var{obj} (in the sense of @code{eq?} for @code{memq},
@code{eqv?} for @code{memv}, and @code{equal?} for @code{member}), 
@code{(list-tail @var{list} @var{n})} is returned.
Otherwise, @code{#f} is returned.
@c JP
@var{list}から@var{obj}を探します。もし@var{list}の@var{n}番目の要素が
@var{obj}と同一ならば、@code{(list-tail @var{list} @var{n})}を返します。
@code{memq}は同一性の判定に@code{eq?}を、@code{memv}は@code{eqv?}を、
@code{member}は@code{equal?}を使います。
@var{obj}が@var{list}中に見つからなければ@code{#f}が返されます。
@c COMMON

@c EN
If you use SRFI-1 (@xref{List library}), @code{member} is extended
to take optional argument for a equality procedure.
@c JP
SRFI-1 (@ref{List library}) を使うと、@code{member}は
オプショナルな同一性判定手続きを取るように拡張されます。
@c COMMON
@example
(memq 'a '(a b c))          @result{} (a b c)
(memq 'b '(a b c))          @result{}  (b c)
(memq 'a '(b c d))          @result{} #f
(memq (list 'a) '(b (a) c)) @result{} #f
(memv 101 '(100 101 102))   @result{} (101 102)
@end example
@end defun

@defun assq obj list
@defunx assv obj list
@defunx assoc obj list
[R5RS]
@c EN
Each element in @var{list} must be a pair.
These procedures search a pair whose car matches @var{obj}
(in the sense of @code{eq?} for @code{assq},
@code{eqv?} for @code{assv}, and @code{equal?} for @code{assoc})
from left to right, and return the leftmost matched pair if any.
If no pair matches, these return @code{#f}.
@c JP
@var{list}の各要素はペアでなければなりません。
これらの手続きは、@var{list}の要素であるペアのうち、そのcarが
@var{obj}と一致するペアを左から探して行きます。もし見付かればそのペアが、
見付からなければ@code{#f}が返されます。
@code{assq}は比較関数に@code{eq?}を、@code{assv}は@var{eqv?}を、
@code{assoc}は@var{equal?}をそれぞれ用います。
@c COMMON

@c EN
If you use SRFI-1 (@xref{List library}), @code{assoc} is extended
to take optional argument for a equality procedure.
@c JP
SRFI-1 (@ref{List library}) を使うと、@code{assoc}は
オプショナルな同一性判定手続きを取るように拡張されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Symbols, Keywords, Pairs and Lists, Core library
@section Symbols
@c NODE シンボル

@deftp {Builtin Class} <symbol>
@clindex symbol
@c EN
A class for symbols.
@c JP
シンボルを表すクラスです。
@c COMMON
@end  deftp

@deftp {Reader Syntax} @code{|@i{name}|}
@c EN
Denotes a symbol that has weird name, i.e. the name including the
characters which is not allowed in the R5RS symbol syntax.
If the interpreter is running in case-insensitive mode, this syntax
can be used to include uppercase characters in a symbol
(@xref{Case-sensitivity}).

The syntax is taken from CommonLisp.  Some other Scheme implementation
use it as well.
@c JP
R5RSのシンボルの定義では許されていない文字を使った妙な名前のシンボルを表記するのに
使う構文です。インタプリタが大文字小文字を区別しないモードで走っている場合は、
大文字を含むシンボルを表記するときにも使えます (@ref{Case-sensitivity}参照)。

この表記はCommonLispから取られました。いくつかのSchemeでも同様の表記を採用しています。
@c COMMON
@end deftp

@deftp {Reader Syntax} @code{#:@i{name}}
@c EN
Denotes @emph{uninterned} symbol.  Uninterned symbols can be created
by @code{gensym} or @code{string->uninterned-symbol}.
@c JP
「インターンされていない」シンボルを表記します。インターンされていないシンボルは
@code{gensym}か@code{string->uninterned-symbol}で作ることができます。
@c COMMON

@c EN
Uninterned symbols are mainly for legacy macros to avoid
variable conflicts.   They are not registered in the internal
dictionary, so such symbols with the same name can't be @code{eq?}.
@c JP
インターンされていないシンボルは、良く伝統的なマクロで
変数衝突を避けるために使われます。インターンされていないシンボルは
内部のシンボルのテーブルに登録されないため、同じ名前のシンボルでも
@code{eq?}になりません。
@c COMMON

@example
(eq? '#:foo '#:foo) @result{} #f
(eq? '#:foo 'foo) @result{} #f
@end example

@c EN
When an S-expression including uninterned symbols are printed,
the srfi-38 syntax is used to indicate which uninterened symbol
is the same (@code{eq?}) to which.
@c JP
インターンされていないシンボルが含まれるS式を、シンボルの同一性を保って
表記するには、@code{srfi-38}記法が使えます。
@c COMMON

@example
(let1 s '#:foo) (list s s))
  @result{} @r{prints} (#0=#:foo #0#)

(let ((s '#:foo) (t '#:foo)) (list s t s t))
  @result{} @r{prints} (#0=#:foo #1=#:foo #0# #1#)
@end example
@end deftp


@defun symbol? obj
[R5RS] 
@c EN
Returns true if and only if @var{obj} is a symbol.
@c JP
@var{obj}がシンボルなら@code{#t}を返します。
@c COMMON
@example
(symbol? 'abc)     @result{} #t
(symbol? 0)        @result{} #f
(symbol? 'i)       @result{} #t
(symbol? '-i)      @result{} #f
(symbol? '|-i|)    @result{} #t
@end example
@end defun

@defun symbol-interned? symbol
@c EN
Returns @code{#t} if @var{symbol} is an interned symbol,
@code{#f} if it is an uninterned symbol.   An error is signalled
if @var{symbol} is not a symbol.
@c JP
シンボル@var{symbol}がインターンされていらば@code{#t}を、
そうでなければ@code{#f}を返します。シンボルでないものが渡された場合はエラーとなります。
@c COMMON
@end defun


@defun symbol->string symbol
[R5RS]
@c EN
Returns the name of @var{symbol} in a string.  Returned
string is immutable.
@c JP
@var{symbol}の名前を文字列で返します。返される文字列は変更不可です。
@c COMMON

@example
(symbol->string 'foo) @result{} foo
@end example
@end defun

@defun string->symbol string
[R5RS]
@c EN
Returns a symbol whose name is a string @var{string}.
@var{String} may contain weird characters.
@c JP
文字列@var{string}を名前に持つシンボルを返します。
@c COMMON

@example
(string->symbol "a") @result{} a
(string->symbol "A") @result{} A
(string->symbol "weird symbol name") @result{} |weird symbol name|
@end example
@end defun

@defun string->uninterned-symbol string
@c EN
Like @code{string->symbol}, but the created symbol is uninterned.
@c JP
@code{string->symbol}と似ていますが、作られたシンボルはインターンされません。
@c COMMON

@example
(string->uninterned-symbol "a") @result{} #:a
@end example
@end defun


@defun gensym :optional prefix
@c EN
Returns a fresh, uninterned symbol.  The returned symbol can never
be @code{eq?} to other symbol within the process.
If @var{prefix} is given, which must be a string, it is used
as a prefix of the name of the generated symbol.  It is mainly for
the convenience of debugging.
@c JP
インターンされてない、新しいシンボルを作って返します。
返されるシンボルは、他のシンボルとは決して@code{eq?}にならないことが保証されます。
@var{prefix}が与えられた場合は、それは文字列でなければならず、
それが作られるシンボルのプレフィクスに使われます。これは主としてデバッグを
容易にするためのものです。
@c COMMON
@end defun

@defun symbol-sans-prefix symbol prefix
@c EN
Both @var{symbol} and @var{prefix} must be symbols.
If the name of @var{prefix} matches the beginning part of the
name of @var{symbol}, this procedure returns a symbol whose
name is the name of @var{symbol} without the mached prefix.
Otherwise, it returns @code{#f}.
@c JP
@var{symbol}と@var{prefix}は共にシンボルでなければなりません。
@var{prefix}が@var{symbol}の先頭部分にマッチした場合、
@var{symbol}からマッチ部分を取り除いた名前を持つシンボルを返します。
マッチしない場合は@code{#f}を返します。
@c COMMON

@example
(symbol-sans-prefix 'foo:bar 'foo:) @result{} bar
(symbol-sans-prefix 'foo:bar 'baz:) @result{} #f
@end example
@end defun

@c ----------------------------------------------------------------------
@node Keywords, Identifiers, Symbols, Core library
@section Keywords
@c NODE キーワード

@deftp {Builtin Class} <keyword>
@clindex keyword
@c EN
A keyword is a sort of a special symbol that is automatically quoted.
It is extensively used in pass-by-name arguments (keyword arguments),
and keyword-value list.
Unlike CommonLisp, keywords and symbols are distinct types.

See also @ref{Making Procedures} for how Gauche supports keyword
arguments, and @code{let-keywords} macro (@ref{Optional argument parsing})
for parsing keyword-value list manually.
@c JP
キーワードは特別なシンボルの一種で、自動的にクォートされます。
名前で渡す引数(キーワード引数)や、キーワード-値のリストで広く使われて
います。
CommonLisp とは異なり、キーワードとシンボルは別々の型として扱われます。

Gaucheにおけるキーワード引数のサポートについては@ref{Making Procedures}を、
また独自にキーワード-値リストをパーズする方法については
@code{let-keywords} マクロ(@ref{Optional argument parsing}) も参照して下さい。
@c COMMON
@end  deftp

@deftp {Reader syntax} @code{:@var{name}}
@c EN
Read to a keyword whose name is @var{name}.
(Note that the preceding ':' is not a part of the keyword's name.)
@c JP
名前が @var{name} であるキーワードとして読み込まれます。
(先行する ':' は、キーワードの名前の一部ではないことに注意してください。)
@c COMMON
@end deftp

@defun keyword? obj
@c EN
Returns @code{#t} if @var{obj} is a keyword.
@c JP
@var{obj} がキーワードであれば、@code{#t} を返します。
@c COMMON
@end defun

@defun make-keyword name
@c EN
Returns a keyword whose name is @var{name}, which can be
can be a string or a symbol.
@c JP
名前が @var{name} であるキーワードを返します。@var{name}には
文字列かシンボルが許されます。
@c COMMON
@example
(make-keyword "foo")  @result{} :foo

(make-keyword 'foo)   @result{} :foo
@end example
@end defun

@defun keyword->string keyword
@c EN
Returns the name of the keyword @var{keyword}, in a string.
@c JP
キーワード @var{keyword} の名前を文字列で返します。
@c COMMON
@example
(keyword->string :foo) @result{} "foo"
@end example
@end defun

@defun get-keyword key kv-list :optional fallback
@c EN
A useful procedure to extract a value from key-value list.
A key-value list @var{kv-list} must contains even number of elements;
the first, third, fifth @dots{} elements are regarded as keys,
and the second, fourth, sixth @dots{} elements are the values of
the preceding keys.

This procedure looks for @var{key} from the keys, and if it finds one,
it returns the corresponding value.
If there are more than one matching keys, the leftmost one is taken.
If there is no matching key, it returns @var{fallback} if provided,
or signals an error otherwise.

It is an error if @var{kv-list} is not a proper, even-number element list.

Actually, `keywords' in the keyword-value list and the @var{key} argument
need not be a keyword---it can be any Scheme object.  Key comparison
is done by @code{eq?}.

This procedure is taken from STk.
@c JP
キー-値のリストから値を取り出すのに便利な手続きです。
キー-値のリスト @var{kv-list} は偶数個の要素を持たなければなりません。
1つ目、3つ目、5つ目、@dots{} の要素はキーとして扱われ、
2つ目、4つ目、6つ目、@dots{} の要素は、その前の要素をキーとした値と
なります。

この手続きは、キーの集合から @var{key} を探して、それが見つかれば、
対応する値を返します。
2つ以上のキーにマッチしたら、最左のものとなります。
マッチするキーがない場合、@var{fallback} が与えられていればそれを
返し、さもなければエラーを通知します。

@var{kv-list} が正しい偶数個の要素を持つリストでない場合は、エラーに
なります。

キーワード-値リストの `キーワード' と、@var{key} 引数は、実際には
キーワードである必要はありません。いかなる Scheme オブジェクトで
あっても良いです。キーの比較は、@code{eq?} によって行われます。

この手続きは、STk から導入されました。
@c COMMON

@example
(get-keyword :y '(:x 1 :y 2 :z 3))
  @result{} 2
(get-keyword 'z '(x 1 y 2 z 3))
  @result{} 3

(get-keyword :t '(:x 1 :y 2 :z 3))
  @result{} #<error>
(get-keyword :t '(:x 1 :y 2 :z 3) #f)
  @result{} #f
@end example
@end defun

@defmac get-keyword* key kv-list :optional fallback
@c EN
Like @code{get-keyword}, but @var{fallback} is evaluated only
if @var{kv-list} does not have @var{key}.
@c JP
@code{get-keyword} と同様ですが、@var{kv-list} が @var{key} を
含まない場合にのみ @var{fallback} が評価されることだけが違います。
@c COMMON
@end defmac

@defun delete-keyword key kv-list
@defunx delete-keyword! key kv-list
@c EN
Removes all the keys and values from @var{kv-list} for
keys that are @code{eq?} to @var{key}.
@c JP
@var{kv-list} から @var{key} に @code{eq?} であるキーをもつキーと値を
削除します。
@c COMMON

@c EN
@code{delete-keyword} doesn't change @var{kv-list}, but the returned
list may share the common tail of it.
@c JP
@code{delete-keyword} は @var{kv-list} を変更しません。しかし、
返されたリストは共通の末尾部分を共有します。
@c COMMON

@c EN
@code{delete-keyword!} doesn't allocate, and @emph{may} destructively
changes @var{kv-list}.  You still have to use the returned value,
for the original list may not be changed if its first key matches
@var{key}.
@c JP
@code{delete-keyword!} は新しくアロケートされることはありません。
そして、破壊的に @var{kv-list} を変更する@emph{可能性があります}。
最初のキーがマッチした場合元のリストは変更されないこともありえますが、
返り値のリストを使わなければいけません。
@c COMMON

@c EN
If there's no key that matches @var{key}, @var{kv-list} is returned.
@c JP
@var{key} にマッチするキーがない場合 @var{kv-list} が返ります。
@c COMMON

@example
(delete-keyword :y '(:x 1 :y 2 :z 3 :y 4))
 @result{} (:x 1 :z 3)
@end example

@end defun

@defun delete-keywords keys kv-list
@defunx delete-keywords! keys kv-list
@c EN
Similar to @code{delete-keyword} and @code{delete-keyword!}, but
you can specify a list of objects in @var{keys};
when a key in @var{kv-list} matches any of @var{keys},
the key and the following value is removed from @var{kv-list}.
@c JP
@code{delete-keyword}や@code{delete-keyword!}と似ていますが、
@var{keys}にオブジェクトのリストを指定できます。
@var{kv-list}中のキーが@var{keys}のうちのどれかに一致すれば、
そのキーと続く値が@var{kv-list}から取り除かれます。
@c COMMON

@example
(delete-keywords '(:x :y) '(:x 1 :y 2 :z 3 :y 4))
 @result{} (:z 3)
@end example

@end defun

@c ----------------------------------------------------------------------
@node Identifiers, Characters, Keywords, Core library
@section Identifiers
@c NODE Identifier

@deftp {Builtin Class} <identifier>
@clindex identifier
@end  deftp

@defun identifier? obj
@end defun

@defun identifier->symbol identifier
@end defun


@c ----------------------------------------------------------------------
@node Characters, Character set, Identifiers, Core library
@section Characters
@c NODE 文字

@deftp {Builtin Class} <char>
@clindex char
@end  deftp

@deftp {Reader Syntax} @code{#\@i{charname}}
[R5RS]
@c EN
Denotes a literal character.

When the reader reads @code{#\}, it fetches a subsequent character.
If it is one of @code{()[]@{@}" \|;#}, this is a character literal of itself.
Otherwise, the reader reads subsequent characters until it sees
a non word-constituent character.  If only one character is read,
it is the character.  Otherwise, the reader matches the read characters
with predefined character names.  If it doesn't match any, an error
is signalled.

The following character names are recognized.
These character names are case insensitive.
@table @code
@item space
Whitespace (ASCII #x20)
@item newline, nl, lf
Newline (ASCII #x0a)
@item return, cr
Carriage return (ASCII #x0d)
@item tab, ht
Horizontal tab (ASCII #x09)
@item page
Form feed (ASCII #x0c)
@item escape, esc
Escape (ASCII #x1b)
@item delete, del
Delete (ASCII #x7f)
@item null
NUL character (ASCII #x00)
@item x@var{N}
A character whose internal encoding is the integer @var{N},
when @var{N} is a hexadecimal integer.
Note that this notation is not portable among different
internal encoding schemes except ASCII character range.
@item u@var{N}
A character whose UCS character code is the integer @var{N},
where @var{N} is 4-digit or 8-digit hexadecimal number.
If Gauche is compiled with the internal encoding other than UTF-8,
the reader uses @code{gauche.charconv} module to convert Unicode
to the internal character code.  Note that the specified character
may not be defined in the internal encoding; in which case, either
a substitution character is used, or an error is signalled.
@end table
@c JP
リテラルの文字オブジェクトを表現します。

リーダーは@code{#\}に出会うと、まず次の文字を読み込みます。それが文字
@code{()[]@{@}" \|;#} のいずれかならば、その文字自身となります。
そうでなければ、単語を構成しない文字に出会うまで文字が続けて読み込まれます。
もし一文字しか読まれなければ、その文字自身となります。そうでなければ
その単語が文字の名前として解釈されます。
それが有効な文字の名前でなければエラーとなります。

以下の文字の名前が認識されます。これらの文字の名前は大文字小文字を区別しません。
@table @code
@item space
スペース (ASCII #x20)
@item newline, nl, lf
改行文字 (ASCII #x0a)
@item return, cr
復帰文字 (ASCII #x0d)
@item tab, ht
水平タブ (ASCII #x09)
@item page
フォームフィード、改ページ (ASCII #x0c)
@item escape, esc
エスケープ (ASCII #x1b)
@item delete, del
デリート (ASCII #x7f)
@item null
NUL文字 (ASCII #x00)
@item x@var{N}
@var{N} が16進表記の整数であるとき、内部エンコーディングが整数@var{N}
であるような文字。この表記はASCII文字の範囲の外では、内部エンコーディングが異なる
処理系間で互換性が無いことに注意して下さい。
@item u@var{N}
@var{N}が4桁または8桁の16進数整数であるとき、UCSコード@var{N}であるような文字。
Gaucheの内部エンコーディングがUTF-8以外でコンパイルされている場合には、
リーダーは@code{gauche.charconv}モジュールを使ってUnicodeを内部エンコーディングへと
変換します。Unicodeの該当する文字が内部エンコーディングで定義されていない場合、
代替文字に置換されるか、エラーとなります。
@end table
@c COMMON

@example
@c EN
#\newline @result{} #\newline ; @r{newline character}
#\x0a     @result{} #\newline ; @r{ditto}
#\x41     @result{} #\A       ; @r{ASCII letter 'A'}
#\u0041   @result{} #\A       ; @r{ASCII letter 'A', specified by UCS}
#\u3042   @result{} ; @r{Hiragana letter A, specified by UCS}
#\u0002a6b2 @result{} ; @r{JISX0213 Kanji 2-94-86, specified by UCS4}
@c JP
#\newline @result{} #\newline ; @r{改行文字}
#\x0a     @result{} #\newline ; @r{改行文字}
#\x41     @result{} #\A       ; @r{ASCII文字 'A'}
#\u0041   @result{} #\A       ; @r{ASCII文字 'A', UCSコード}
#\u3042   @result{} #\あ      ; @r{平仮名「あ」, UCSコード}
#\u0002a6b2 @result{} ; @r{JISX0213 2-94-86 UCS4コード}
@c COMMON
@end example

@c EN
You can denote multibyte characters with this syntax if
the program text is written in the same encoding as the internal
character encoding.
@c JP
プログラムテキストがGaucheの内部エンコーディングと同じエンコーディングで
書かれていれば、マルチバイト文字を直接表記することもできます。
@example
#\あ @result{} ; @r{文字「あ」}
@end example
@c COMMON
@end deftp

@defun char? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a character, @code{#f} otherwise.
@c JP
@var{obj}が文字なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun char=? char1 char2 char3 @dots{}
@defunx char<? char1 char2 char3 @dots{}
@defunx char<=? char1 char2 char3 @dots{}
@defunx char>? char1 char2 char3 @dots{}
@defunx char>=? char1 char2 char3 @dots{}
[R5RS,R6RS]
@c EN
Compares characters.  Character comparison is done in internal
character encoding.
@c JP
文字を比較します。比較は内部の文字エンコーディングで行われます。
@c COMMON
@end defun

@defun char-ci=? char1 char2 char3 @dots{}
@defunx char-ci<? char1 char2 char3 @dots{}
@defunx char-ci<=? char1 char2 char3 @dots{}
@defunx char-ci>? char1 char2 char3 @dots{}
@defunx char-ci>=? char1 char2 char3 @dots{}
[R5RS,R6RS]
@c EN
Compares characters in case-insensitive way.
The comparison is done in the internal character code
of the foldcase of the each character; see @code{char-foldcase} below.
@c JP
文字を、大文字小文字を区別せずに比較します。
比較はそれぞれの文字のfoldcaseの内部文字エンコーディングに基づいて行われます。
foldcaseについては下の@code{char-foldcase}を参照してください。
@c COMMON
@end defun

@defun char-alphabetic? char
@defunx char-numeric? char
@defunx char-whitespace? char
@defunx char-upper-case? char
@defunx char-lower-case? char
[R5RS]
@c EN
Returns true if a character @var{char} is an alphabetic character
(@code{[A-Za-z]}), a numeric character (@code{[0-9]}), a whitespace
character, an upper case character or a lower case character, respectively.
Currently, these procedures works only for ASCII characters.  They
return @code{#f} for all other characters.
@c JP
文字@var{char}がそれぞれ英字(@code{[A-Za-z]})、数字(@code{[0-9]})、
空白文字、大文字および小文字の時に真の値を返します。
今のところ、これらの手続きはASCII文字のみで動作します。
それ以外の文字に対しては@code{#f}が返されます。
@c COMMON
@end defun

@defun char->integer char
@defunx integer->char n
[R5RS]
@c EN
@code{char->integer} returns an exact integer that represents
internal encoding of the character @var{char}.
@code{integer->char} returns a character whose internal encoding
is an exact integer @var{n}.  The following expression is always
true for valid character @var{char}:
@example
(eq? char (integer->char (char->integer char)))
@end example

The result is undefined if you pass @var{n} to @code{integer->char}
that doesn't have a corresponding character.
@c JP
@code{char->integer}は文字@var{char}の内部エンコーディングに対応する
整数値を返します。@code{integer->char}は数値@var{n}と内部エンコーディングが
同じ文字を返します。有効な文字@var{char}に対して以下の式は常に真となります。
@example
(eq? char (integer->char (char->integer char)))
@end example

対応する内部エンコーディングを持つ文字が無い数値を@code{integer->char}に渡した
場合の結果は不定です。
@c COMMON
@end defun

@defun char->ucs char
@defunx ucs->char n
@c EN
Converts a character @var{char} to integer UCS codepoint,
and integer UCS codepoint @var{n} to a character, respectively.

If Gauche is compiled with UTF-8 encoding, these procedures are the 
same as @code{char->integer} and @code{integer->char}.

When Gauche's internal encoding differs from UTF-8, these procedures
implicitly loads @code{gauche.charconv} module to convert internal
character code to UCS or vice versa (@xref{Character code conversion}).
If @var{char} doesn't have corresponding UCS codepoint, 
@code{char->ucs} returns @code{#f}.  If UCS codepoint @var{n} can't
be represented in the internal character encoding, @code{ucs->char}
returns @code{#f}, unless the conversion routine provides a substitution
character.
@c JP
それぞれ、文字@var{char}をUCSコードポイントを表す整数へ変換し、
またUCSコードポイントを表す整数@var{n}を文字へと変換する手続きです。

Gaucheの内部文字エンコーディングがUTF-8でコンパイルされている場合は、
これらの手続きはそれぞれ@code{char->integer}および@code{integer->char}
と等価です。

Gaucheの内部文字エンコーディングがUTF-8でない場合、
これらの手続きは@code{gauche.charconv}モジュールを使って
内部文字コードとUCSとの変換を行います (@ref{Character code conversion}参照)。
@var{char}が対応するUCSコードを持っていない場合、@code{char->ucs}は@code{#f}を
返します。UCSコード@code{n}に対応する文字が内部エンコーディングで定義されていない
場合、変換ルーチンが代替文字を提供していればそれを、そうでなければ@code{#f}
が返されます。
@c COMMON
@end defun

@defun char-upcase char
@defunx char-downcase char
@defunx char-titlecase char
@defunx char-foldcase char
[R5RS+]
@c EN
Returns the upper case, lower case, title case and folded case of
@var{char}, respectively.  R5RS doesn't have
@code{char-titlecase} and @code{char-foldcase}.
Foldcase is the same as apply upcase, then downcase.

The mapping is done according to Unicode-defined character-by-character
case mapping whenever possible.  If the native encoding doesn't support
the mapped character defined in Unicode, the operation becomes no-op.
If the native encoding is 'none', we treat the characters as if they
are Latin-1 (ISO-8859-1) characters.  So, upcasing Latin-1 character
small y with diaresis (U+00ff) maps to capital y with diaresis
(U+039c) if the internal encoding is utf-8, but it is no-op if
the internal encoding is none.
@c JP
@var{char}の大文字、小文字、titlecase、foldcaseを
それぞれ返します。foldcaseは最初に大文字にしてそれから小文字にするのと同じ操作です。

変換は原則としてUnicodeで定義された文字対文字のマッピングに従います。
Unicodeに従って変換する先の文字が内部エンコーディングでサポートされていない
場合は、変換は行いません。内部エンコーディングが'none'の場合は、
文字をLatin-1 (ISO-8859-1) であるとみなします。Latin-1の
small y with diaresis (U+00ff) をupcaseすると、
内部エンコーディングがutf-8の場合はcapital y with diaresis (U+039c)にマップされますが、
内部エンコーディングがnoneであれば元の文字がそのまま返されます。
@c COMMON

@c EN
The character-by-character case mapping doesn't consider a character
that may map to more than one characters; a notable example is
eszett (latin small letter sharp S, U+00df), which is
is mapped to two capital S's in string context,
but @code{char-upcase #\ß} returns #\ß.  To get a full mapping,
use @code{string-upcase} etc. in @code{text.unicode} module
(@xref{Full string case conversion}).
@c JP
文字対文字のマッピングでは、一文字が複数文字に展開されるようなケースマッピングは
扱いません。有名な例はeszett (latin small letter sharp S, U+00df)で、
文字列のコンテキストでは二つの大文字のSへとマップされますが、
@code{char-upcase #\ß} は単に #\ß を返します。
完全なマッピングが必要なら、@code{text.unicode}モジュールの
@code{string-upcase}等が利用できます
(@ref{Full string case conversion}参照)。
@c COMMON
@end defun

@defun digit->integer char :optional (radix 10)
@c EN
If given character @var{char} is a valid digit character in radix
@var{radix} number, the corresponding integer is returned.  Otherwise
@code{#f} is returned.
@c JP
文字@var{char}が @var{radix}進数の数字を構成するのに有効な文字であれば、
対応する整数が、そうでなければ@code{#f}が返されます。
@c COMMON
@example
(digit->integer #\4) @result{} 4
(digit->integer #\e 16) @result{} 14
(digit->integer #\9 8) @result{} #f
@end example
@c EN
Note: CommonLisp has a similar function in rather confusing name,
@code{digit-char-p}.
@c JP
Common Lispには同様の手続きが@code{digit-char-p}というやや曖昧な名で定義されています。
@c COMMON
@end defun

@defun integer->digit integer :optional (radix 10)
@c EN
Reverse operation of @code{digit->integer}.  Returns a character that
represents the number @var{integer} in the radix @var{radix} system.
If @var{integer} is out of the valid range, @code{#f} is returned.
@c JP
@code{digit->integer}の逆です。整数@var{integer}を @var{radix}進数 ひと桁で
表現するのに使われる文字を返します。@var{integer}がひと桁で表現できない数値の場合は
@code{#f}が返されます。
@c COMMON
@example
(integer->digit 13 16) @result{} #\d
(integer->digit 10) @result{} #f
@end example
@c EN
Note: CommonLisp's @code{digit-char}.
@c JP
Common Lispの@code{digit-char}に当たります。
@c COMMON
@end defun

@defun gauche-character-encoding
@c EN
Returns a symbol designates the native character encoding, selected
at the compile time.
The possible return values are those:
@c JP
コンパイル時に選択された内部文字エンコーディングを表すシンボルを返します。
返される値は以下のいずれかです。
@c COMMON
@table @code
@item euc-jp
EUC-JP
@item utf-8
UTF-8
@item sjis
Shift JIS
@item none
@c EN
No multibyte character support (8-bit fixed-length character).
@c JP
マルチバイトキャラクタをサポートしない(8ビット固定長文字)。
@c COMMON
@end table
@end defun

@defun supported-character-encodings
@c EN
Returns a list of string names of character encoding schemes
that are supported in the native multibyte encoding scheme.
@c JP
ネイティブなマルチバイトエンコーディングスキームでサポートされている
文字エンコーディングスキームの名前を表す文字列のリストを返します。
@c COMMON
@end defun



@c ----------------------------------------------------------------------
@node Character set, Strings, Characters, Core library
@section Character Set
@c NODE 文字集合

@deftp {Builtin Class} <char-set>
@clindex char-set
@c EN
Character set class.  Character set object represents a set of characters.
Gauche provides built-in support of character set creation and
a predicate that tests whether a character is in the set or not.

Further operations, such as set algebra, is defined in SRFI-14
module (@xref{Character-set library}).
@c JP
文字の集合を取り扱う、文字集合(キャラクタセット)のクラスです。
Gaucheは文字集合オブジェクトのサポートと、
ある文字がその集合に属するかどうかを調べる手続きを言語組み込みで持っています。

文字集合に関する他の操作、例えば集合演算などは、SRFI-14モジュール
(@ref{Character-set library}参照) で提供されています。
@c COMMON
@end deftp

@deftp {Reader Syntax} @code{#[@i{char-set-spec}]}
@c EN
You can write a literal character set in this syntax.
@i{char-set-spec} is a sequence of characters to be included
in the set.  You can include the following special sequences:
@table @code
@item @var{x}-@var{y}
Characters between @var{x} and @var{y}, inclusive.
@var{x} must be smaller than @var{y} in the internal encoding.
@item ^
If @i{char-set-spec} begins with caret, the actual character set
is a complement of what the rest of @i{char-set-spec} indicates.
@item \x@var{NN}
A character whose internal code is a hexadecimal number @var{NN}.
@item \u@var{NNNN}
A character whose UCS-2 code is a 4-digit hexadecimal number @var{NNNN}.
@item \U@var{NNNNNNNN}
A character whose UCS-4 code is a 8-digit hexadecimal number @var{NNNNNNNN}.
@item \s
Whitespace characters.
@item \S
Complement of whitespace characters.
@item \d
Decimal digit characters.
@item \D
Complement of decimal digit characters.
@item \w
Word constituent characters.  Currently, it is alphanumeric characters
and underscore.
@item \W
Complement of word constituent characters.
@item \\
A backslash character.
@item \-
A minus character.
@item \^
A caret character.
@item [:alnum:] @dots{}
Character set a la POSIX.  The following character set name is
recognized: @code{alnum}, @code{alpha}, @code{blank}, @code{cntrl},
@code{digit}, @code{graph}, @code{lower}, @code{print}, @code{punct},
@code{space}, @code{upper} and @code{xdigit}.
@end table

@example
#[aeiou]     ; @r{a character set consists of vowels}
#[a-zA-Z]    ; @r{alphabet}
#[[:alpha:]] ; @r{alphabet (using POSIX notation)}
#[\x0d\x0a]  ; @r{newline and carriage return}
#[\\\-]      ; @r{backslash and minus}
#[]          ; @r{empty charset}
@end example
@c JP
この構文で、リテラル文字集合を記述することができます。
@i{char-set-spec}には集合に含める文字を列挙します。
次の特殊なシーケンスを含めることができます。
@table @code
@item @var{x}-@var{y}
文字@var{x}と文字@code{y}の間の文字全て。@var{x}と@var{y}も含みます。
@var{x}は@var{y}よりも内部文字コードで比較して小さくなければなりません。
@item ^
カレットが@i{char-set-spec}の最初に来た場合、以降に示される文字集合の
補集合がこの文字集合となります。
@item \x@var{NN}
内部文字コード@var{NN}(16進数表記)の文字。
@item \u@var{NNNN}
UnicodeのUCS-2で@var{NNNN}(16進数表記4桁)の文字。
@item \U@var{NNNNNNNN}
UnicodeのUCS-4で@var{NNNNNNNN}(16進数表記8桁)の文字。
@item \s
空白文字。
@item \S
空白でない文字。(@code{\s}の補集合)
@item \d
10進数の数字
@item \D
@code{\d}の補集合
@item \w
単語を構成する文字の集合(アルファベット、数字、アンダースコア)
@item \W
@code{\W}の補集合
@item \\
バックスラッシュ文字
@item \-
マイナス文字
@item \^
カレット文字
@item [:alnum:] @dots{}
POSIX流文字集合表記。以下の文字集合名が認識されます:
@code{alnum}, @code{alpha}, @code{blank}, @code{cntrl},
@code{digit}, @code{graph}, @code{lower}, @code{print}, @code{punct},
@code{space}, @code{upper}, @code{xdigit}。
@end table

@example
#[aeiou]     ; @r{母音文字'a', 'e', 'i', 'o', 'u'の集合}
#[a-zA-Z]    ; @r{アルファベット}
#[[:alpha:]] ; @r{アルファベット (POSIX表記)}
#[\x0d\x0a]  ; @r{改行とリターン}
#[\\\-]      ; @r{バックスラッシュとマイナス文字}
#[]          ; @r{空の文字集合}
#[ぁ-ん]     ; @r{平仮名の集合}
@end example
@c COMMON
@end deftp

@defun char-set? obj
[SRFI-14]
@c EN
Returns true if and only if @var{obj} is a character set object.
@c JP
@var{obj}が文字集合であれば真の値を返します。
@c COMMON
@end defun

@defun char-set-contains? char-set char
[SRFI-14]
@c EN
Returns true if and only if a character set object
@var{char-set} contains a character @var{char}.
@c JP
文字集合@var{char-set}が文字@var{char}を含んでいれば真の値を返します。
@c COMMON
@example
(char-set-contains? #[a-z] #\y) @result{} #t
(char-set-contains? #[a-z] #\3) @result{} #f

(char-set-contains? #[^ABC] #\A) @result{} #f
(char-set-contains? #[^ABC] #\D) @result{} #t

@c JP
(char-set-contains? #[あ-お] #\う) @result{} #t
(char-set-contains? #[あ-お] #\ぷ) @result{} #f
@c COMMON
@end example
@end defun

@defun char-set char @dots{}
[SRFI-14]
@c EN
Creates a character set that contains @var{char} @dots{}.
@c JP
文字@var{char} @dots{} からなる文字集合を作成して返します。
@c COMMON
@example
(char-set #\a #\b #\c)   @result{} #[a-c]
@c JP
(char-set #\あ #\い #\う) @result{} #[あいう]
@c COMMON
@end example
@end defun

@defun char-set-copy char-set
[SRFI-14]
@c EN
Copies a character set @var{char-set}.
@c JP
@var{char-set}のコピーを作って返します。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Strings, Regular expressions, Character set, Core library
@section Strings
@c NODE 文字列

@deftp {Builtin Class} <string>
@clindex string
@c EN
A string class.   In Gauche, a string can be viewed in two ways:
a sequence of characters, or a sequence of bytes.
@c JP
文字列のクラスです。Gaucheでは、文字列は文字のシーケンスともバイトのシーケンスとも
みなすことができます。
@c COMMON
@end deftp

@c EN
It should be emphasized that Gauche's @emph{internal} string object,
@emph{string body}, is immutable.  
To comply R5RS in which strings are mutable, a Scheme-level
string object is an indirect pointer to a string body.
Mutating a string means that Gauche creates a new immutable
string body that reflects the changes, then swap the pointer
in the Scheme-level string object.

This may affect some assumptions on the cost of string operations.

@itemize
@item
Copying string is O(1), no matter how long the string is, since
the same string body is shared.
@item
Taking substring usually is also O(1), for the resulting string
shares the substring of the original string body.  Gauche may copy
a part of the string for better memory management, but the visible
cost should stay pretty close to O(1).  (However, note that accessing
to a specific point by index within the original string may cost
O(N) because of multibyte string; which is a different story).
@item
On the other hand, mutating a string cost O(N) where N is the length
of string, even for replacing a character.  
@end itemize

Gauche does not attempt to make string mutation faster; 
@code{(string-set! s k c)} is exactly as slow as to take
two substrings, before and after of k-th character, and
concatenate them with a single-character string inbetween.
So, just avoid string mutations; we believe it's a better practice.
See also @ref{String Constructors}.
@c JP
GaucheではSchemeの文字列は、内部的には、変更不可能なオブジェクト(文字列実体)を
用いて表現されている、ということを強調しておきます。
文字列が変更可能であるR5RSの仕様を満たすために、Schemeレベルの文字列は
文字列実体への間接ポインタとなっています。文字列を変更すると、
変更を反映した新しいstring bodyが作成され、Schemeレベルの文字列が
新しい文字列実体を指すように変更されます。

このことから、文字列操作の性能を見積る場合に注意が必要です。

@itemize
@item
文字列のコピーは、それがどんなに長い文字列であっても常にO(1)です。
文字列実体は共有されるからです。
@item
部分文字列を取る操作も通常はO(1)です。文字列実体を部分的に共有するからです。
メモリ管理上の都合から文字列実体の一部がコピーされる可能性はありますが、
ほとんどの場合はO(1)とみなして構いません。(ただし、マルチバイト文字処理の都合上、
文字インデックスで文字列の途中を指定する操作は別途O(N)を要する場合があります)
@item
一方で、文字列の変更はたとえ1文字の変更であっても、文字列実体の長さNに
比例したO(N)のコストを必要とします。
@end itemize

Gaucheはそもそも文字列の変更に関して全く最適化を行っていません。
@code{(string-set! s k c)}は、k番目の文字の前後の部分文字列を取って、
c一文字の文字列を間に挟んで継ぎ足すことで新たな文字列を作るのと
全く同じコストがかかります。
文字列を変更不可として扱う方が良いプログラミングスタイルだと考えるからです。
@ref{String Constructors}も参照してください。
@c COMMON

@c EN
R5RS string operations are very minimal.  Gauche supports some
extra built-in operations, and also a rich string library
defined in SRFI-13.   @xref{String library}, for details about SRFI-13.
@c JP
R5RSに定義されている文字列操作は非常に限られています。
Gaucheでは追加の組込み手続きのほか、
SRFI-13に定義されている豊富な文字列ライブラリを備えています。
SRFI-13については@ref{String library}を参照してください。
@c COMMON

@menu
* String syntax::               
* String Predicates::           
* String Constructors::         
* String interpolation::        
* String Accessors & Modifiers::  
* String Comparison::           
* String utilities::            
* Incomplete strings::          
@end menu

@node String syntax, String Predicates, Strings, Strings
@subsection String syntax
@c NODE 文字列の表記

@deftp {Reader syntax} @code{"}@dots{}@code{"}
[R5RS+]
@c EN
Denotes a literal string.  Inside the double quotes, the following
backslash escape sequences are recognized.
@c JP
リテラル文字列です。ダブルクオートの中では、
以下のエスケープシーケンスが認識されます。
@c COMMON

@table @code
@item \"
@c EN
[R5RS] Double-quote character
@c JP
[R5RS] ダブルクオート文字
@c COMMON
@item \\
@c EN
[R5RS] Backslash character
@c JP
[R5RS] バックスラッシュ文字
@c COMMON
@item \n
@c EN
Newline character (ASCII 0x0a).
@c JP
改行文字 (ASCII 0x0a)
@c COMMON
@item \r
@c EN
Return character (ASCII 0x0d).
@c JP
復帰文字 (ASCII 0x0d)
@c COMMON
@item \f
@c EN
Form-feed character (ASCII 0x0c).
@c JP
フォームフィード (ASCII 0x0c)
@c COMMON
@item \t
@c EN
Tab character (ASCII 0x09)
@c JP
タブ文字 (ASCII 0x09)
@c COMMON
@item \0
@c EN
ASCII NUL character (ASCII 0x00).
@c JP
NUL文字 (ASCII 0x00)
@c COMMON
@item \<whitespace>*<newline><whitespace>*
@c EN
Ignored.  This can be used to break a long string literal for readability.
This escape sequence is introduced in R6RS.
@c JP
無視されます。長い文字列リテラルを読みやすさのために折り返す時に便利です。
このエスケープシーケンスはR6RSで導入されました。
@c COMMON
@item \x@var{NN}
@c EN
A byte represented by two-digit hexadecimal number @var{NN}.
The byte is interpreted as the internal multibyte encoding.
@c JP
2桁の16進数@var{NN}で指定されるバイト。
このバイトは内部エンコーディングによって解釈されます。
@c COMMON
@item \u@var{NNNN}
@c EN
A character whose UCS2 code is represented by four-digit
hexadecimal number @var{NNNN}.
@c JP
4桁の16進数@var{NNNN}によって示されるUCS2コードを持つ文字。
@c COMMON
@item \U@var{NNNNNNNN}
@c EN
A character whose UCS4 code is represented by eight-digit
hexadecimal number @var{NNNNNNNN}.
@c JP
8桁の16進数@var{NNNNNNNN}によって示されるUCS4コードを持つ文字。
@c COMMON
@end table

@c EN
If Gauche is compiled with internal encoding other than UTF-8,
the reader uses @code{gauche.charconv} module to interpret
@code{\uNNNN} and @code{\UNNNNNNNN} escape sequence.
@c JP
GaucheがUTF-8以外の内部エンコーディングでコンパイルされていた場合、
リーダーは@code{gauche.charconv}モジュールを使って
エスケープシーケンス@code{\uNNNN}と@code{\UNNNNNNNN}の解釈を行います。
@c COMMON

@c EN
The following code is an example of backslash-newline escape sequence:
@c JP
下はバックスラッシュ-改行エスケープシーケンスの使用例です。
@c COMMON
@example
(define *message* "\
  This is a long message \
  in a literal string.")

*message*  
  @result{} "This is a long message in a literal string."
@end example

@c EN
Note the whitespace just after `message'.   Since any whitespaces
before `in' is eaten by the reader, you have to put a whitespace
between `message' and the following backslash.  If you want to include
an actual newline character in a string, and any indentation after it,
you can put '\n' in the next line like this:
@c JP
`message' の後の空白に注意してください。`in'の前の空白は読み込みルーチンによって
無視されてしまうので、空白を入れたければ`message'と続くバックスラッシュの間に
入れる必要があります。もし文字列中に実際に改行文字を入れ、さらにその後の
文字列をインデントさせたい場合は次のようにすると良いでしょう:
@c COMMON

@example
(define *message/newline* "\
  This is a long message, \
  \n   with a line break.")
@end example
@end deftp

@deftp {Reader syntax} @code{#*"}@dots{}@code{"}
@c EN
Denotes incomplete string.  The same escape sequences as the complete
string syntax are recognized.
@c JP
不完全な文字列のリテラル表記です。完全な文字列と同様のエスケープシーケンスが
使えます。
@c COMMON

@c EN
Rationale of the syntax: '@code{#*}' is used for bit vector
in Common Lisp.  Since an incomplete strings is really a byte vector,
it has similarity.  (Bit vector can be added later, if necessary,
and two can coexist).
@c JP
'@code{#*}' という構文はCommon Lispでビットベクタの表記に使われています。
不完全な文字列は実際はバイトベクタであることから、類似点を認めてこの構文を
採用しました。(もし将来必要になってビットベクタが実装されたとしても、
この構文と共存できます)。
@c COMMON
@end deftp


@node String Predicates, String Constructors, String syntax, Strings
@subsection String Predicates
@c NODE 文字列に関する述語

@defun string? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a string, @code{#f} otherwise.
@c JP
@var{obj}が文字列なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun string-immutable? obj
@c EN
Returns @code{#t} if @var{obj} is an immutable string, @code{#f} otherwise
@c JP
@var{obj}が変更不可な文字列なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun string-incomplete? obj
@c EN
Returns @code{#t} if @var{obj} is an incomplete string, @code{#f} otherwise
@c JP
@var{obj}が不完全文字列なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@node String Constructors, String interpolation, String Predicates, Strings
@subsection String Constructors
@c NODE 文字列の作成

@defun make-string k :optional char
[R5RS]
@c EN
Returns a string of length @var{k}.  If optional @var{char} is given,
the new string is filled with it.  Otherwise, the string is filled with
a whitespace.  The result string is always complete.

@example
(make-string 5 #\x) @result{} "xxxxx"
@end example

Note that the algorithm to allocate a string by @code{make-string} and
then fills it one character at a time is @emph{extremely} inefficient
in Gauche, and should be avoided.   That kind of algorithms unnecessarily
assumes underlying string allocation and representation mechanism,
which Gauche doesn't follow.
You can use an output string port for a string construction
(@xref{String ports}).
Even creating a list of characters and
using @code{list->string} is faster than using @code{make-string} and
@code{string-set!}.
@c JP
長さ@var{k}の文字列を作成して返します。
@var{char}が与えられればそれで内容を満たします。@var{char}が与えられなければ
空白文字で満たされます。常に完全な文字列が返されます。

@example
(make-string 5 #\x) @result{} "xxxxx"
(make-string 5 #\ふ) @result{} "ふふふふふ"
@end example

@code{make-string}で必要な長さの文字列をアロケートして、@code{string-set!}
で順番に埋めて行くアルゴリズムは、Gaucheでは@emph{極めて}非効率であることに
注意してください。そのようなアルゴリズムは、文字列の内部表現とアロケーションメカニズムに
関して不必要な仮定を置いており、Gaucheはその仮定とは合致しません。
文字列の順次作成に適しているのは文字列ポートです
(@ref{文字列ポート}参照)。それが使えない場合、
文字のリストを作成し、@code{list->string}で変換する方がまだ@code{make-string}と
@code{string-set!}を使うより良いでしょう。
@c COMMON
@end defun

@defun make-byte-string k :optional byte
@c EN
Creates and returns an incomplete string o size @var{k}.
If @var{byte} is given,
which must be an exact integer, and its lower 8 bits
are used to initialize every byte in the created string.
@c JP
大きさ@var{k}の不完全な文字列を作成して返します。
@var{byte}が与えられた場合は、その下位1バイトで文字列の各バイトを初期化します。
@var{byte}は正確な整数でなければなりません。
@c COMMON
@end defun

@defun string char @dots{}
[R5RS]
@c EN
Returns a string consisted by @var{char} @dots{}.
@c JP
文字@var{char} @dots{} から構成された文字列を返します。
@c COMMON
@end defun

@deffn {Generic Function} x->string obj
@c EN
A generic coercion function.
Returns a string representation of @var{obj}.
The default methods are defined as follows: strings are returned
as is, numbers are converted by @code{number->string}, symbols are
converted by @code{symbol->string}, and other objects are
converted by @code{display}.

Other class may provide a method to customize the behavior.
@c JP
文字列への強制型変換手続きです。
@var{obj}の文字列表現を返します。
デフォルトのメソッドでは、文字列はそのまま返され、数値は@code{number->string}で、
シンボルは@code{symbol->string}で変換され、その他のオブジェクトは@code{display}表現
が使われます。

他のクラスはこのメソッドを定義することにより、独自の変換関数を提供することができます。
@c COMMON
@end deffn

@node String interpolation, String Accessors & Modifiers, String Constructors, Strings
@subsection String interpolation
@c NODE 文字列の補間

@c EN
The term "string interpolation" is used in various scripting languages
such as Perl and Python to refer to the feature to embed expressions
in a string literal, which are evaluated and then their results are
inserted into the string literal at run time.
@c JP
「文字列の補間(string interpolation)」という用語は、
PerlやPythonなど様々なスクリプト言語で、文字列リテラル内に式を埋め込んでおき
実行時に式を評価した値をそのリテラル内に埋め込む機能を指します。
@c COMMON

@c EN
Scheme doesn't define such a feature, but Gauche implements it as a
reader macro.
@c JP
Schemeはそのような機能を定義していませんが、Gaucheではリーダーマクロを使って
文字列の補間を実装しました。
@c COMMON

@deftp {Reader syntax} @code{#`}@var{string-literal}
@c EN
Evaluates to a string.  If @var{string-literal} contains the
character sequence @code{,@var{expr}}, where 
@var{expr} is a valid external representation
of a Scheme expression, @var{expr} is evaluated and
its result is inserted in the original place (by using @code{x->string},
see @ref{String Constructors}).
@c JP
文字列に評価されます。@var{string-literal}内に、@code{,@var{expr}}
というシーケンス(ここで@var{expr}は有効なScheme式の外部表現)が
現われたら、@var{expr}が評価されてその結果がもとの位置に埋め込まれます。
結果の文字列化には@code{x->string}が使われます(@ref{String Constructors}参照)。
@c COMMON

@c EN
The comma and the following expression must be adjacent (without containing
any whitespace characters), or it is not recognized as a special sequence.
@c JP
コンマと続く式とは、空白文字等を入れずに隣接していなければなりません。
そうでない場合は置換されません。
@c COMMON

@c EN
Two adjacent commas are converted to a single comma.  You can embed
a comma before a non-whitespace character in @var{string-literal}
by this.
@c JP
二つの連続するコンマは一つのリテラルのコンマ文字に置き換えられます。
これによって、コンマと非空白文字の連続を@var{string-literal}に入れることができます。
@c COMMON

@c EN
Other characters in the @var{string-literal} are copied as is.
@c JP
それ以外の@var{string-literal}内の文字シーケンスはそのままコピーされます。
@c COMMON

@c EN
If you use a variable as @var{expr} and need to delimit it from the
subsequent string, you can use the symbol escape syntax
using `|' character, as shown in the last two examples below.
@c JP
@var{Expr}に単独の変数を使う場合で、それに続く文字列と変数名を区切りたい
場合は、`|'文字を使ったシンボルエスケープ構文が使えます。下の例の最後の
2つを見て下さい。
@c COMMON

@example
#`"This is Gauche, version ,(gauche-version)."
 @result{} "This is Gauche, version @VERSION@."

#`"Date: ,(sys-strftime \"%Y/%m/%d\" (sys-localtime (sys-time)))"
 @result{} "Date: 2002/02/18"

(let ((a "AAA")
      (b "BBB"))
 #`"xxx ,a ,b zzz")
 @result{} "xxx AAA BBB zzz"

#`"123,,456,,789"
 @result{} "123,456,789"

(let ((n 5)) #`"R,|n|RS")
 @result{} "R5RS"

(let ((x "bar")) #`"foo,|x|.")
 @result{} "foobar"
@end example

@c EN
In fact, the reader expands this syntax into a macro call,
which is then expanded into a call of @code{string-append}
as follows:
@c JP
実は、リーダーはこの構文をマクロ呼び出しへと変換し、それが最終的には
@code{string-append}への呼び出しへと変換されます。
@c COMMON
@example
#`"This is Gauche, version ,(gauche-version)."
 @equiv{}
(string-append "This is Gauche, version "
               (x->string (gauche-version))
               ".")
@end example
@end deftp

@c EN
@emph{Rationale of the syntax:}
Some other scripting languages use `@code{$expr}' or '@code{#@{...@}}'.
I chose this syntax with respect to the quasiquote (@xref{Quasiquotation}).
Although it may be awkward to delimit variable names by `|',
the comma syntax should be easier to read than the other exotic syntax
for seasoned Scheme programmers.

Note that Scheme allows wider range of characters for valid identifier names
than usual scripting languages.
Consequently, you will almost always need to use `|' delimiters
when you interpolate the value of a variable.
For example, while you can write
@code{"$year/$month/$day $hour:$minutes:$seconds"} in Perl,
you should write @code{#`",|year|/,|month|/,day ,|hour|:,|minutes|:,seconds"}.
It may be better always to delimit direct variable references
in this syntax to avoid confusion.
@c JP
@emph{この構文を採用した理由:} 
他のスクリプト言語では、`@code{$expr}' や '@code{#@{...@}}' が良く使われています。
準クオート (@ref{Quasiquotation}参照) との類似性からこの構文を採用しました。
変数名の区切りを明確にするのに`|'を使う必要があるのは少々奇妙ですが、
慣れたSchemeプログラマならコンマ構文を読むのは他の言語から借りた構文よりも
楽だと思います。

Schemeは他のスクリプト言語より一般的により多くの文字を変数名に使うことが出来ることに注意して下さい。
結果として、変数の値を文字列に挿入する際、ほとんどの場合において変数名を`|'で区切る
必要があるでしょう。例えば、Perlでは
@code{"$year/$month/$day $hour:$minutes:$seconds"}
と書けたものが、Gaucheでは
@code{#`",|year|/,|month|/,day ,|hour|:,|minutes|:,seconds"}
と書かねばなりません。
混乱を避けるためには、この構文内では常に直接の変数参照は`|'で区切るようにしておくのが良いかもしれません。
@c COMMON

@node String Accessors & Modifiers, String Comparison, String interpolation, Strings
@subsection String Accessors & Modifiers
@c NODE 文字列のアクセスと変更

@defun string-length string
[R5RS]
@c EN
Returns a length of (possibly incomplete) string @var{string}.
@c JP
文字列@var{string}の長さ(文字数)を返します。
@var{string}は不完全な文字列であっても構いません。
@c COMMON
@end defun

@defun string-size string
@c EN
Returns a size of (possibly incomplete) @var{string}.
A size of string is a number of bytes @var{string} occupies on memory.
The same string may have different sizes if the native encoding scheme
differs.

For incomplete string, its length and its size always match.
@c JP
文字列@var{string}の大きさを返します。文字列の大きさは、
@var{string}が占めるメモリ上のバイト数で、これは文字列の内部エンコーディングに
依存します。同じ文字列であっても内部エンコーディングが違えば違う大きさになる場合も
あります。

不完全な文字列では、文字列の長さと大きさは常に一致します。
@c COMMON
@end defun

@defun string-ref cstring k :optional fallback
[R5RS+]
@c EN
Returns @var{k}-th character of a complete string @var{cstring}.
It is an error to pass an incomplete string.

By default, an error is signalled if @code{k} is out of range
(negative, or greater than or equal to the length of @var{cstring}).
However, if an optional argument @var{fallback} is given,
it is returned in such case.  This is Gauche's extension.
@c JP
完全な文字列@var{cstring}の@var{k}番目の文字を返します。
不完全な文字列を渡すのはエラーです。

@var{k}が負数であったり@var{cstring}の長さと同じかそれ以上であった場合には
エラーが報告されます。但し、引数@var{fallback}が与えられている場合にはエラーを
報告せず@var{fallback}が返されます。これはGaucheの拡張です。
@c COMMON
@end defun

@defun string-byte-ref string k
@c EN
Returns @var{k-th} byte of a (possibly incomplete) string @var{string}.
Returned value is an integer in the range between 0 and 255.
@var{k} must be greater than or equal to zero, and less than
@code{(string-size @var{string})}.
@c JP
(多分、不完全な)文字列@var{string}の@var{k番目}のバイトを返します。
戻り値は、0から255の範囲の整数です。@var{k}は0以上、
@code{(string-size @var{string})}より小でなければなりません。
@c COMMON
@end defun

@defun string-set! string k char
@c EN
[R5RS] Substitute @var{string}'s @var{k}-th character by @var{char}.
@var{k} must be greater than or equal to zero, and less than
@code{(string-length @var{string})}.
Return value is undefined.

If @var{string} is an incomplete string, integer value of the lower 8 bits
of @var{char} is used to set @var{string}'s @var{k}-th byte.

See the notes in @code{make-string} about performance consideration.
@c JP
[R5RS] @var{string}の@var{k}番目の文字を@var{char}で置き換えます。
@var{k}は0以上、@code{(string-length @var{string})}より小でなければ
なりません。戻り値は未定義です。

@var{string}が不完全文字列の場合、@var{char}の下位8ビットの整数値は、
@var{string}の@var{k}番目のバイトをセットするために使われます。

パフォーマンス上の考慮点について、@code{make-string}の説明を参照して下さい。
@c COMMON
@end defun

@defun string-byte-set! string k byte
@c EN
Substitute @var{string}'s @var{k}-th byte by integer @var{byte}.
@var{byte} must be in the range between 0 to 255, inclusive.
@var{k} must be greater than or equal to zero, and less than
@code{(string-size @var{string})}.
If @var{string} is a complete string, it is turned to incomplete string
by this operation.
Return value is undefined.
@c JP
@var{string}の@var{k}番目のバイトを整数@var{byte}で置き換えます。
@var{byte}は0から255の範囲(255を含む)でなければなりません。
@var{k}は0以上、@code{(string-size @var{string})}より小である必要があります。
@var{string}が完全文字列の場合、この操作により不完全文字列になります。
戻り値は未定義です。
@c COMMON
@end defun

@node String Comparison, String utilities, String Accessors & Modifiers, Strings
@subsection String Comparison
@c NODE 文字列の比較

@defun string=? string1 string2
@defunx string-ci=? string1 string2
[R5RS]
@end defun

@defun string<? string1 string2
@defunx string<=? string1 string2
@defunx string>? string1 string2
@defunx string>=? string1 string2
@defunx string-ci<? string1 string2
@defunx string-ci<=? string1 string2
@defunx string-ci>? string1 string2
@defunx string-ci>=? string1 string2
[R5RS]
@end defun

@node String utilities, Incomplete strings, String Comparison, Strings
@subsection String utilities
@c NODE 文字列を扱うその他の手続き

@defun substring string start end
[R5RS]
@c EN
Returns a substring of @var{string}, starting from @var{start}-th
character (inclusive) and ending at @var{end}-th character (exclusive).
The @var{start} and @var{end} arguments must satisfy 
@code{0 <= @var{start} < @var{N}},
@code{0 <= @var{end} <= @var{N}}, and
@code{@var{start} <= @var{end}}, where @var{N} is the length of the
string.
@c JP
@var{string}の@var{start}番目の文字(これを含む)から、@var{end}番目の文
字(これを含まない)までの部分文字列を返します。引数@var{start}および
@var{end}は以下を満さなければなりません。
@code{0 <= @var{start} < @var{N}}、
@code{0 <= @var{end} <= @var{N}}、
@code{@var{start} <= @var{end}}。ただし、@var{N}は与えられた文字列の長
さです。
@c COMMON

@c EN
When @var{start} is zero and @var{end} is @var{N}, this procedure
returns a copy of @var{string}.
@c JP
@var{start}がゼロでかつ@var{end}が@var{N}の場合には、@var{string}のコ
ピーが返ります。
@c COMMON

@c EN
Actually, extended @code{string-copy} explained below
is a superset of @code{substring}.  This procedure is 
kept mostly for compatibility of R5RS programs.
See also @code{subseq} in @ref{Sequence framework}, 
for the generic version.
@c JP
実は後述する拡張された@code{string-copy}は@code{substring}のスーパーセッ
トになっています。この手続きの役割は主にR5RSとの互換性のためです。
@ref{Sequence framework}のジェネリック版@code{subseq}も参照してください。
@c COMMON
@end defun

@defun string-append string @dots{}
[R5RS]
@c EN
Returns a newly allocated string whose content is concatenation of 
@var{string} @dots{}.
@c JP
@var{string} @dots{}を連結した内容を含む文字列を新しくアロケートして返
します。
@c COMMON

@c EN
See also @code{string-concatenate} in @ref{SRFI-13 String reverse & append}.
@c JP
@ref{SRFI-13 String reverse & append}の@code{string-concatenate}も参照
してください。
@c COMMON
@end defun

@defun string->list string :optional start end
@defunx list->string list
[R5RS+][SRFI-13]
@c EN
Converts a string to a list of characters or vice versa.
@c JP
文字列を文字のリストへ、またはその逆の変換をします。
@c COMMON

@c EN
You can give an optional start/end indexes to @code{string->list},
as specified in SRFI-13.
@c JP
@code{string->list}にはオプショナル引数として開始、終了位置のインデッ
クスを渡せます。これはSRFI-13で規定されています。
@c COMMON

@c EN
For @var{list->string}, every elements of @var{list} must be
a character, or an error is signalled.  If you want to build
a string out of a mixed list of strings and characters, you
may want to use @code{tree->string} in @ref{Lazy text construction}.
@c JP
@var{list->string}では@var{list}の要素はすべて文字でなければなりません。
そうでなければ、エラーシグナルがあがります。文字列や文字がまざったリス
トから文字列を構成したい場合には@ref{Lazy text construction}にある
@code{tree->string}が使えます。
@c COMMON
@end defun

@defun string-copy string :optional start end
[R5RS+][SRFI-13]
@c EN
Returns a copy of @var{string}.  You can give @var{start} and/or
@var{end} index to extract the part of the original string
(it makes @code{string-copy} a superset of @code{substring} effectively).
@c JP
@var{string}のコピーを返します。@var{start}および/あるいは@var{end}の
位置インデックスを渡すと元の文字列の部分文字列を取り出せます。
(したがって@code{string-copy}は事実上@code{substring}のスーパーセット
です)。
@c COMMON

@c EN
If only @var{start} argument is given, a substring beginning from
@var{start}-th character (inclusive) to the end of @var{string} is
returned.  If both @var{start} and @var{end} argument are given,
a substring from @var{start}-th character (inclusive) to
@var{end}-th character (exclusive) is returned.
See @code{substring} above for the condition that @var{start} and
@var{end} should satisfy.
@c JP
@var{start}引数のみを与えた場合には、部分文字列は@var{start}番目の文字
(これを含む)から@var{string}の最後までで、それが返ります。
@var{start}と@var{end}の両方を与えたときは、部分文字列は@var{start}番
目の文字(これを含む)から、@var{end}番目の文字(これを含まない)までで、
それが返ります。@var{start}と@var{end}が満すべき条件については
前述の@code{substring}の項を見てください。
@c COMMON
@end defun

@defun string-fill! string char :optional start end
@c EN
[R5RS+][SRFI-13] Fills @var{string} by @var{char}.  Optional
@var{start} and @var{end} limits the effective area.
@c JP
[R5RS+][SRFI-13] @var{string} を @var{char} で埋めます。
オプションの @var{start} と @var{end} は、影響を受ける領域を
制限します。
@c COMMON
@example
(string-fill! "orange" #\X)
  @result{} "XXXXXX"
(string-fill! "orange" #\X 2 4)
  @result{} "orXXge"
@end example
@end defun

@defun string-join strs :optional delim grammer
@c EN
[SRFI-13] Concatenate strings in the list @var{strs},
with a string @var{delim} as `glue'.

The argument @var{grammer} may be one of the following symbol
to specify how the strings are concatenated.
@c JP
[SRFI-13] リスト @var{strs} 中にある文字列を、文字列 @var{delim} を'糊'
として連結します。

引数 @var{grammer} は、文字列がどのように連結されるかを指定する
シンボルで、以下のうちの一つです。
@c COMMON
@table @code
@item infix
@c EN
Use @var{delim} between each string.  This mode is default.
Note that this mode introduce ambiguity when @var{strs}
is an empty string or a list with a null string.
@c JP
それぞれの文字列の間に @var{delim} を使います。このモードが
デフォルトです。@var{strs} が空文字列かヌル文字列を含むリスト
である場合は、曖昧に(適当に)動作します。
@c COMMON
@example
(string-join '("apple" "mango" "banana") ", ") 
  @result{} "apple, mango, banana"
(string-join '() ":")
  @result{} ""
(string-join '("") ":")
  @result{} ""
@end example
@item strict-infix
@c EN
Works like @code{infix}, but empty list is not allowed to @var{strs},
thus avoiding ambiguity.
@c JP
@code{infix} のように動作しますが、@var{strs} には空リストは
許されません。したがって、曖昧さはありません。
@c COMMON
@item prefix
@c EN
Use @var{delim} before each string.
@c JP
@var{delim} をそれぞれの文字列の前に補います。
@c COMMON
@example
(string-join '("usr" "local" "bin") "/" 'prefix)
  @result{} "/usr/local/bin"
(string-join '() "/" 'prefix)
  @result{} ""
(string-join '("") "/" 'prefix)
  @result{} "/"
@end example
@item suffix
@c EN
Use @var{delim} after each string.
@c JP
@var{delim} をそれぞれの文字列の後ろに補います。
@c COMMON
@example
(string-join '("a" "b" "c") "&" 'suffix)
  @result{} "a&b&c&"
(string-join '() "&" 'suffix)
  @result{} ""
(string-join '("") "&" 'suffix)
  @result{} "&"
@end example
@end table

@end defun

@defun string-scan string item :optional return
@c EN
Scan @var{item} (either a string or a character) in @var{string}.
The @var{return} argument specifies what value should be returned
when @var{item} is found in @var{string}.  It must be one of the
following symbols.
@c JP
@var{string} にある @var{item} (文字列あるいは文字)を探します。
引数 @var{return} は、@var{string} 中に @var{item} が見つかった
場合にどの値が返されるかを指定します。それは以下のシンボルのうちの
一つでなければなりません。
@c COMMON

@table @code
@item index
@c EN
Returns the index in @var{string} if @var{item} is found, or @code{#f}.
This is the default behavior.
@c JP
@var{item} が見つかった場合は@var{string} 内でのインデックス、
そうでなければ @code{#f} を返します。これがデフォルトの振る舞いです。
@c COMMON
@example
(string-scan "abracadabra" "ada") @result{} 5
(string-scan "abracadabra" #\c) @result{} 4
(string-scan "abracadabra" "aba") @result{} #f
@end example
@item before
@c EN
Returns a substring of @var{string} before @var{item}, or
@code{#f} if @var{item} is not found.
@c JP
@var{item} よりも前にある @var{string} の部分文字列、あるいは
@var{item} が見つからなければ @code{#f} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'before) @result{} "abrac"
(string-scan "abracadabra" #\c 'before) @result{} "abra"
@end example
@item after
@c EN
Returns a substring of @var{string} after @var{item}, or
@code{#f} if @var{item} is not found.
@c JP
@var{item} より後ろにある @var{string} の部分文字列、あるいは
@var{item} が見つからなければ @code{#f} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'after) @result{} "bra"
(string-scan "abracadabra" #\c 'after) @result{} "adabra"
@end example
@item before*
@c EN
Returns a substring of @var{string} before @var{item}, and
the substring after it.  If @var{item} is not found, returns
@code{(values #f #f)}.
@c JP
@var{item} の前にある @var{string} の部分文字列と後ろにある
@var{string} の部分文字列を返します。@var{item} が見つからない場合は、
@code{(values #f #f)} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'before*)
  @result{} "abrac" @r{and} "adabra"
(string-scan "abracadabra" #\c 'before*)
  @result{} "abra" @r{and} "cadabra"
@end example
@item after*
@c EN
Returns a substring of @var{string} up to the end of @var{item},
and the rest.  If @var{item} is not found, returns
@code{(values #f #f)}.
@c JP
@var{string} のうち、@var{item} の終端までの部分文字列とその残りを
返します。@var{item} が見つからなかった場合は、@code{(values #f #f)}
を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'after*)
  @result{} "abracada" @r{and} "bra"
(string-scan "abracadabra" #\c 'after*)
  @result{} "abrac" @r{and} "adabra"
@end example
@item both
@c EN
Returns a substring of @var{string} before @var{item} and
after @var{item}.  If @var{item} is not found, returns
@code{(values #f #f)}.
@c JP
@var{string} のうち、@var{item} の前と @var{item} の後ろの
部分文字列を返します。@var{item} が見つからない場合、
@code{(values #f #f)} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'both)
  @result{} "abrac" @r{and} "bra"
(string-scan "abracadabra" #\c 'both)
  @result{} "abra" @r{and} "adabra"
@end example
@end table
@end defun

@defun string-split string splitter
@c EN
Splits @var{string} by @var{splitter} and returns a list of strings.
@var{splitter} can be a character, a character set, a string,
a regexp, or a procedure.

If @var{splitter} is a character, the character is used as a delimiter.

If @var{splitter} is a character set, any consecutive characters
that are member of the character set are used as a delimiter.

If a procedure is given to @var{splitter}, it is called for each
character in @var{string}, and the consecutive characters that caused
@var{splitter} to return a true value are used as a delimiter.
@c JP
@var{string} を @var{splitter} で分割し、文字列のリストを返します。
@var{splitter} には、文字、文字セット、文字列、正規表現、手続きが
使えます。

@var{splitter} が文字の場合、その文字がデリミタとして使われます。

@var{splitter} が文字セットの場合は、その文字セットに含まれる文字の
連続がデリミタとして使われます。

@var{splitter} に手続きが与えられた場合、@var{string} にある各文字に
対してその手続きが呼ばれ、@var{splitter} が真の値を返すような連続した
文字群がデリミタとして使われます。
@c COMMON

@example
(string-split "/aa/bb//cc" #\/)    @result{} ("" "aa" "bb" "" "cc")
(string-split "/aa/bb//cc" "/")    @result{} ("" "aa" "bb" "" "cc")
(string-split "/aa/bb//cc" "//")   @result{} ("/aa/bb" "cc")
(string-split "/aa/bb//cc" #[/])   @result{} ("" "aa" "bb" "cc")
(string-split "/aa/bb//cc" #/\/+/) @result{} ("" "aa" "bb" "cc")
(string-split "/aa/bb//cc" #[\w])  @result{} ("/" "/" "//" "")
(string-split "/aa/bb//cc" char-alphabetic?) @result{} ("/" "/" "//" "")

;; some boundary cases
(string-split "abc" #\/) @result{} ("abc")
(string-split ""    #\/) @result{} ("")
@end example

@c EN
See also @code{string-tokenize} in
(@xref{SRFI-13 other string operations}).
@c JP
@code{string-tokenize} (@ref{SRFI-13 other string operations})
も参照して下さい。
@c COMMON
@end defun

@node Incomplete strings,  , String utilities, Strings
@subsection Incomplete strings
@c NODE 不完全文字列

@c EN
A string can be flagged as "incomplete" if it may contain
byte sequences that do not consist of a valid multibyte character
in the Gauche's native encoding.
@c JP
Gaucheの内部エンコーディングで正当なマルチバイト文字で構成されていない
ようなバイト列を含む文字列は「不完全文字列」となります。
@c COMMON

@c EN
Incomplete strings may be genereated in several circumstances;
reading binary data as a string, reading a string data that has
been 'chopped' in middle of a multibyte character, or 
concatenating a string with other incomplete strings, for example.
@c JP
不完全文字列が生成される状況はいくつかあります。たとえば、バイナリデー
タを文字列として読み込んだとき、マルチバイト文字の途中で切れた文字列を
読み込んだとき、別の不完全文字列が連結された場合などです。
@c COMMON

@c EN
Incomplete strings should be regarded as an exceptional case.
It used to be a way to handle byte strings, but now we have
u8vector (@xref{Uniform vectors}) for that purpose.
In fact, we're planning to remove it in the future releases.
@c JP
不完全文字列は例外的な状況であるとみなすべきです。これまではバイト列処
理を使っていましたが、現在はu8vector (@ref{Uniform vectors}参照)を使うこ
とができますので、将来のリリースでは削除する計画です。
@c COMMON

@c EN
Just in case, if you happen to get an incomplete string,
you can convert it to a complete string by the following 
procedure:
@c JP
万が一、不完全文字列に出会ってしまったら以下の手続を使って完全文字列に
変換することができます。
@c COMMON

@defun string-incomplete->complete str :optional handling
@c EN
Reinterpret the content of an incomplete string @var{str}
and returns a newly created complete string from it.
@c JP
不完全文字列@var{str}の内容を再解釈して、あらたに完全文字列を返す。
@c COMMON
@c EN
The @var{handling} argument specifies how to handle the illegal
byte sequences in @var{str}.
@c JP
@var{handling}引数で@var{str}中の不正なバイト列の扱いかたを指定します。
@c COMMON
@table @asis
@item @code{#f}
@c EN
If @var{str} contains an illegal byte sequence, give up the
conversion and returns @code{#f}.  This is the default behavior.
@c JP
@var{str}が不正なバイト列を含んでいる場合、変換を諦めて@code{#f}を返し
ます。これがデフォルトのふるまいです。
@c COMMON
@item @code{:omit}
@c EN
Omit any illegal byte sequences.  Always returns a complete string.
@c JP
不正なバイト列を捨てます。常に完全文字列を返します。
@c COMMON
@c EN
@item a character
Replace each byte in illegal byte sequences by the given character.
Always returns a complete string.
@c JP
@item 1文字
不正なバイト列中の各バイトを与えた文字で置き換えます。常に完全文字列を
返します。
@c COMMON
@end table
@c EN
If @var{str} is already a complete string, its copy is returned.
@c JP
@var{str}が完全文字列なら、そのコピーが返されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Regular expressions, Vectors, Strings, Core library
@section Regular expressions
@c NODE 正規表現

@c EN
Gauche has a built-in regular expression engine which is mostly
upper-compatible of POSIX extended regular expression, plus
some extensions from Perl 5 regexp.

A special syntax is provided for literal regular expressions.
Also regular expressions are applicable, that is, 
it works like procedures that match the given string to itself.
Combining with these two features enables writing some
string matching idioms compact.
@c JP
GaucheはPOSIXの拡張正規表現にほぼ上位互換で、さらに
Perl 5の正規表現から拡張機能を採り入れた正規表現エンジンを持っています。
Gaucheはまた、リテラル正規表現用の構文を備えています。

正規表現用のリテラル構文が用意されており、
また、正規表現オブジェクトは適用可能、つまり文字列に対して
手続きのように振る舞い、自分自身にマッチするかどうかを判定できるようになっています。
この二つの機能によって、文字列のマッチをスキャンするようなイディオムを
簡潔に書けるようになっています。
@c COMMON

@example
(find #/pattern/ list-of-strings)
  @result{} @i{match object} or #t
@end example

@menu
* Regular expression syntax::   
* Using regular expressions::   
* Inspecting and assembling regular expressions::  
@end menu

@node Regular expression syntax, Using regular expressions, Regular expressions, Regular expressions
@subsection Regular expression syntax
@c NODE 正規表現の構文

@deftp {Reader Syntax} @code{#/@i{regexp-spec}/}
@deftpx {Reader Syntax} @code{#/@i{regexp-spec}/i}
@c EN
Denotes literal regular expression object.  When read, it becomes
an instance of @code{<regexp>}.
@c JP
リテラルの正規表現オブジェクトを表記します。読まれた際に@code{<regexp>}の
インスタンスとなります。
@c COMMON

@c EN
If a letter '@code{i}' is given at the end, the created regexp
becomes @emph{case-folding regexp}, i.e. it matches in the case-insensitive
way.  (The current version only cares ASCII characters for case-folding---
beyond ASCII characters, the match is done in the same way as normal match.)
@c JP
末尾に文字@code{i}が与えられた場合は、マッチ時に大文字小文字を区別しない
正規表現オブジェクトとなります。(現在のバージョンでは、大文字小文字の
同一視はASCII文字のみに対して行われます。それ以外の文字は通常の方法でマッチします)。
@c COMMON

@c EN
The advantage of using this syntax over @code{string->regexp} is
that the regexp is compiled only once.  You can use literal regexp
inside loop without worrying about regexp compilation overhead.
If you want to construct regexp on-the-fly, however, use @code{string->regexp}.
@c JP
@code{string->regexp}に対してこの構文を使う利点は、
正規表現のコンパイルが一度しか行われない点です。この構文は、
内部ループの中でも、正規表現のコンパイルのオーバヘッドを気にせずに
使うことができます。動的に正規表現を作成したい場合のみ@code{string->regexp}を
使って下さい。
@c COMMON
@end deftp

@c EN
Gauche's built-in regexp syntax follows POSIX extended regular 
expression, with a bit of extensions taken from Perl.

Note that the syntax described here is just a surface syntax.
Gauche's regexp compiler works on the abstract syntax tree,
and alternative syntax such as SRE will be supported in the
future versions.
@c JP
Gaucheの組み込み正規表現構文はPOSIX拡張正規表現に準じたものに、
Perlの拡張の一部を採り入れたものです。

ここに示す構文は表面的な構文にすぎないことに注意して下さい。
Gaucheの正規表現コンパイラは抽象構文木を扱うようになっており、
将来はSREのような別の構文もサポートされる予定です。
@c COMMON

@table @code
@item @i{re}*
@c EN
Matches zero or more repetition of @i{re}.
@c JP
@i{re}の0回以上の繰り返しにマッチします。
@c COMMON

@item @i{re}+
@c EN
Matches one or more repetition of @i{re}.
@c JP
@i{re}の1回以上の繰り返しにマッチします。
@c COMMON

@item @i{re}?
@c EN
Matches zero or one occurrence of @i{re}.
@c JP
@i{re}の0回または1回の出現にマッチします。
@c COMMON

@item @i{re}@{@i{n}@}
@itemx @i{re}@{@i{n},@i{m}@}
@c EN
Bounded repetition.  @code{@i{re}@{@i{n}@}} matches exactly @i{n}
occurrences of @i{re}.
@code{@i{re}@{@i{n},@i{m}@}} matches at least @var{n} and at most
@var{m} occurrences of @i{re}, where @var{n} <= @var{m}.
In the latter form, either @var{n} or @var{m} can be omitted; omitted @var{n} 
is assumed as 0, and omitted @var{m} is assumed infinity.
@c JP
回数に範囲のある繰り返しです。
@code{@i{re}@{@i{n}@}}は@i{re}の@i{n}回の繰り返しにマッチします。
@code{@i{re}@{@i{n},@i{m}@}}は@i{re}の@i{n}回以上、@i{m}回以下の
繰り返しにマッチします。但し@var{n} <= @var{m}とします。
2番目の形式では@var{n}か@var{m}のどちらかを省略することが
できます。@var{n}が省略された場合は0とみなされます。
@var{m}が省略された場合は無限大とみなされます。
@c COMMON

@item @i{re}*?
@itemx @i{re}+?
@itemx @i{re}??
@itemx @i{re}@{@i{n},@i{m}@}?
@c EN
Same as the above repetition construct, but these syntaxes
use "non-greedy" or "lazy" match strategy.  That is, they try to match
the minimum number of occurrences of @i{re} first, then retry
longer ones only if it fails.  In the last form
either @var{n} or @var{m} can be omitted.
Compare the following examples:
@c JP
上記の繰り返し構造とほぼ同じですが、これらの構文は「non-greedy」または
「lazy」と呼ばれるマッチ戦略を用います。すなわち、まず@i{re}がマッチする
最小の回数を試し、それが失敗したら順に繰り返しの回数を増やしてゆきます。
最後の形式では@var{n}か@var{m}のどちらかは省略できます。
次の例を比べてみてください：
@c COMMON

@example
(rxmatch-substring (#/<.*>/ "<tag1><tag2><tag3>") 0)
  @result{} "<tag1><tag2><tag3>"

(rxmatch-substring (#/<.*?>/ "<tag1><tag2><tag3>") 0)
  @result{} "<tag1>"
@end example

@item (@i{re}@dots{})
@c EN
Clustering with capturing.  The regular expression enclosed
by parenthesis works as a single @i{re}.  Besides, the string
that matches @i{re} @dots{} is saved as a @emph{submatch}.
@c JP
捕捉クラスタリング。括弧でくくられた正規表現の列がグループとして
扱われ、またそれにマッチした文字列はサブマッチとして保存されます。
@c COMMON

@item (?:@i{re}@dots{})
@c EN
Clustering without capturing.   @code{@i{re} @dots{}} works as
a single @i{re}, but the matched string isn't saved.
@c JP
捕捉無しクラスタリング。@code{@i{re} @dots{}}はグループとして
扱われますが、サブマッチとして保存されません。
@c COMMON

@item (?<@i{name}>@i{re}@dots{})
@c EN
Named capture and clustering.  Like @code{(@i{re}@dots{})}, 
but adds the name @i{name} to the matched substring.
You can refer to the matched substring by both index number
and the name.

When the same name appears more than once in a regular
expression, it is undefined which matched substring is
returned as the submatch of the named capture.
@c JP
名前つきの捕捉とクラスタリング。@code{(@i{re}@dots{})}と同様ですが、
マッチした文字列に名前@i{name}がつけられます。マッチした文字列には
インデックスの数字と名前のどちらでも参照できます。

同じ名前が複数回正規表現内に出現した場合、どの名前付き捕捉にマッチした
部分文字列が返されるかは不定です。
@c COMMON

@item (?i:@i{re}@dots{})
@itemx (?-i:@i{re}@dots{})
@c EN
Lexical case sensitivity control.  
@code{(?i:@i{re}@dots{})} makes @i{re}@dots{} matches case-insensitively,
while @code{(?-i:@i{re}@dots{})} makes 
@i{re}@dots{} matches case-sensitively.

Perl's regexp allows several more flags to appear between '?' and ':'.
Gauche only supports above two, for now.
@c JP
大文字小文字の区別の制御。
@code{(?i:@i{re}@dots{})}は@i{re}@dots{}が大文字小文字にかかわらず
マッチするようにします。
@code{(?-i:@i{re}@dots{})}はその逆です。

Perlの正規表現では'?'と':'の間に他のいくつかのフラグを使うことが
できますが、Gaucheでは今のところこのフラグのみをサポートしています。
@c COMMON

@item @i{pattern1}|@i{pattern2}|@dots{}
@c EN
Alternation.  Matches either one of patterns, where each
pattern is @i{re} @dots{}.
@c JP
パターンのいずれかにマッチします。
@c COMMON

@item \@i{n}
@c EN
Backreference.  @i{n} is an integer.
Matches the substring captured by the @i{n}-th capturing group.
(counting from 1).  When capturing groups are nested, groups
are counted by their beginnings.
If the @i{n}-th capturing group is in a repetition and has mached
more than once, the last matched substring is used.
@c JP
バックリファレンス。@i{n}は整数です。
@i{n}番目(1から数える)の捕捉カッコに捕捉された文字列と一致する場合に、\@i{n}が
マッチします。補足カッコがネストしている場合、開きカッコの順番で数えます。
@i{n}番目のカッコが繰り返しの中にあり、複数回マッチ
している場合は、最後にマッチした文字列との比較が行われます。
@c COMMON

@item \k<@i{name}>
@c EN
Named backreference.  Matches the substring captured by
the capturing group with the name @i{name}.
If the named capturing group is in a repetition and has mached
more than once, the last matched substring is used.
If there are more than one capturing group with @i{name},
matching will succeed if the input matches either one of the substrings
captured by those groups.
@c JP
名前によるバックリファレンス。
名前@i{name}を持つ捕捉カッコで捕捉された文字列と一致する場合に、
\k<@i{name}>がマッチします。参照しているカッコが繰り返しの中にあり、
複数回マッチしている場合は、最後にマッチした文字列との比較が行わ
れます。同じ名前@i{name}を持つ捕捉カッコが複数ある場合には、
それらのカッコの最後にマッチした文字列のいずれかと一致する場合、
マッチが成功します。
@c COMMON

@item .
@c EN
Matches any character (including newline).
@c JP
任意の1文字にマッチします。改行文字にもマッチします。
@c COMMON

@item [@i{char-set-spec}]
@c EN
Matches any of the character set specified by @i{char-set-spec}.
@xref{Character set}, for the details of @i{char-set-spec}.
@c JP
@i{char-set-spec}で指定される文字セット内の文字にマッチします。
@i{char-set-spec}については@ref{Character set}を参照して下さい。
@c COMMON

@item \s, \d, \w
@c EN
Matches a whitespace character (@code{#[[:space:]]}),
a digit character (@code{#[[:digit:]]}), or
a word-constituent character (@code{#[[:alpha:][:digit:]_]}),
respectively.

Can be used both inside and outside of character set.
@c JP
それぞれ空白文字(@code{#[[:space:]]})、
数字(@code{#[[:digit:]]})、
単語を構成する文字(@code{#[[:alpha:][:digit:]_]})にマッチします。

文字セット内でも、その外でも使えます。
@c COMMON

@item \S, \D, \W
@c EN
Matches the complement character set of @code{\s}, @code{\d} and
@code{\w}, respectively.
@c JP
それぞれ@code{\s}、@code{\d}、@code{\w}で指定される文字セットの補集合の
文字にマッチします。
@c COMMON

@item ^, $
@c EN
Beginning and end of string assertion, 
when appears at the beginning or end of the pattern.
@c JP
それぞれ、パターンの最初または最後に指定された場合、
文字列の最初か最後にマッチします。
@c COMMON

@item \b, \B
@c EN
Word boundary and non word boundary assertion, respectively.
That is, @code{\b} matches an empty string between
word-constituent character and non-word-constituent character,
and @code{\B} matches an empty string elsewhere.
@c JP
@code{\b}は単語の境界の空文字列にマッチします。
@code{\B}はその逆です。
@c COMMON

@item \;
@itemx \"
@itemx \#
@c EN
These are the same as @code{;}, @code{"}, and @code{#}, respectively,
and can be used to avoid confusing Emacs or other syntax-aware editors 
that are not familiar with Gauche's extension.
@c JP
これらはそれぞれ@code{;}、@code{"}、および@code{#}と同じです。
Emacs等、Scheme構文を理解するエディタを混乱させないために使うことができます。
@c COMMON

@item (?=@i{pattern})
@itemx (?!@i{pattern})
@c EN
Positive/negative lookahead assertion.  
Match succeeds if @i{pattern} matches (or does not match) 
the input string from the current position, but this doesn't
move the current position itself, so that the following
regular expression is applied again from the current position.

For example, the following expression matches strings
that might be a phone number, except the numbers in Japan
(i.e. ones that begin with "81").
@c JP
肯定および否定の先読み。
@i{pattern}が文字列の現在の位置にマッチする(あるいはマッチ
しない)ときにマッチが成功しますが、現在の位置は変更しない
ので、後に続く正規表現は現在と同じ位置から適用されます。

例えば、次の表現は、電話番号のうち日本の番号("81"から始まるもの)
を除く文字列にマッチします。
@c COMMON

@example
\+(?!81)\d@{9,@}
@end example

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
@c EN
Positive/negative lookbehind assertion.
If the input string immediately before the current
input position matches @var{pattern}, this pattern
succeeds or fails, respectively.   Like lookahead
assertion, the input position isn't changed.

Internally, this match is tried by reversing
@var{pattern} and applies it to the backward
of input character sequence.  So you can
write any regexp in @var{pattern}, but if the
submatches depend on the matching order,
you may get different submatches from when
you match @var{pattern} from left to right.
@c JP
肯定および否定の後読み。
現在の位置の左側に@var{pattern}にマッチする文字列がある場合に
マッチが成功(あるいは失敗)します。先読みと同様、現在の位置は
変更しません。

内部的にこの表現は、@i{pattern}を逆転させたうえで、現在の位置
から左に向かってマッチを進めることで実現されています。したがって、
@i{pattern}には任意のものにマッチする表現を含めることができますが、
マッチの順番や長さが重要な場合(例えば2通りにマッチしうる捕捉の
カッコ)などは、左から右に現在位置が進むときとは異なる場所に
マッチするかもしれません。
@c COMMON

@item (?>@i{pattern})
@c EN
Atomic clustering.  Once @i{pattern} matches,
the match is fixed; even if the following pattern fails,
the engine won't backtrack to try the
alternative match in @i{pattern}.
@c JP
アトミックなクラスタリング。@i{pattern}がいったんマッチすると、
そのマッチは確定します。後続のパターンが失敗した場合でも、
@i{pattern}内にバックトラックして他のマッチが試みられることはありません。
@c COMMON

@item @i{re}*+
@itemx @i{re}++
@itemx @i{re}?+
@c EN
They are the same as (?>@i{re}*), (?>@i{re}+), (?>@i{re}?), respectively.
@c JP
それぞれ(?>@i{re}*)、(?>@i{re}+)、(?>@i{re}?)と同じです。
@c COMMON

@item (?@i{test-pattern} @i{then-pattern})
@itemx (?@i{test-pattern} @i{then-pattern}|@i{else-pattern})
@c EN
Conditional matching.   If @var{test-pattern} counts
true, @var{then-pattern} is tried; otherwise
@var{else-pattern} is tried when provided.

@var{test-pattern} can be either one of the following:

@table @code
@item (@i{integer})
Backreference.  If @var{integer}-th capturing group has a match,
this test counts true.

@item (?=@i{pattern})
@itemx (?!@i{pattern})
Positive/negative lookahead assertion.  It tries @var{pattern}
from the current input position without consuming input,
and if the match succeeds or fails, respectively, this
test counts true.

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
Positive/negative lookbehind assertion.  It tries @var{pattern}
backward from the left size of the current input position,
and if the match succeeds or fails, respectively, this
test counts true.
@end table
@c JP
条件つきマッチング。@var{test-pattern}が成功すれば
@var{then-pattern}へと、そうでなければ
@var{else-pattern}へと(もしあれば)マッチを進めます。

@var{test-pattern}には以下の形式が書けます。

@table @code
@item (@i{integer})
バックリファレンス。@var{integer}番目の捕捉クラスタリングのマッチに
成功していた場合に成功となります。

@item (?=@i{pattern})
@itemx (?!@i{pattern})
肯定および否定の先読み。入力の現在位置から、入力を消費することなく
@var{pattern}のマッチを試み、それがそれぞれ成功もしくは失敗した
場合に、この@var{test-pattern}を成功とみなします。

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
肯定および否定の後読み。入力の現在位置から左側に向かって、
@var{pattern}の逆向きにマッチを試みます、
それがそれぞれ成功もしくは失敗した場合に、
この@var{test-pattern}を成功とみなします。
@end table
@c COMMON
@end table

@node Using regular expressions, Inspecting and assembling regular expressions, Regular expression syntax, Regular expressions
@subsection Using regular expressions
@c NODE 正規表現を使う

@deftp {Builtin Class} <regexp>
@clindex regexp
@c EN
Regular expression object.  You can construct a regexp object
from a string by @code{string->regexp} at run time.  Gauche also 
has a special syntax to denote regexp literals, which construct
regexp object at loading time.

Gauche's regexp engine is fully aware of multibyte characters.
@c JP
正規表現オブジェクトのクラスです。@code{string->regexp}を使って実行時に
作成できます。また、Gaucheはリテラルの正規表現を表す構文を持っており、
ロード時に作成することもできます。

Gaucheの正規表現エンジンはマルチバイト文字列に対応しています。
@c COMMON
@end deftp

@deftp {Builtin Class} <regmatch>
@clindex regmatch
@c EN
Regexp match object.  A regexp matcher @code{rxmatch} returns
this object if match.  This object contains all the information
about the match, including submatches.

The advantage of using match object, rather than substrings or
list of indices, is efficiency.  The regmatch object keeps internal
state of match, and computes indices and/or substrings only when
requested.  This is particularly effective for mutibyte strings,
for index access is slow on them.
@c JP
正規表現マッチオブジェクトのクラスです。正規表現エンジン@code{rxmatch}は、
一致した場合にこのオブジェクトを返します。部分一致の情報を含めた
全てのマッチに関する情報がこのオブジェクトに含まれています。

一致した部分文字列やそのインデックスのリストではなく
マッチオブジェクトを返すことの利点は効率です。
regmatchオブジェクトはマッチの内部状態を保持しており、
要求された時にはじめて該当する部分文字列やインデックスを計算します。
これは特にマルチバイト文字列に有効です。マルチバイト文字列
へのインデックスアクセスは遅いからです。
@c COMMON
@end deftp

@defun string->regexp string :key case-fold
@c EN
Takes @var{string} as a regexp specification, and constructs
an instance of @code{<regexp>} object.
@c JP
文字列@var{string}を正規表現とみなして、@code{<regexp>}のインスタンスを
作成して返します。
@c COMMON

@c EN
If a true value is given to the keyword argument @var{case-fold},
the created regexp object becomes case-folding regexp.
(See the above explanation about case-folding regexp).
@c JP
キーワード引数@var{case-fold}に真の値が与えられた場合、作成される正規表現は
大文字小文字を区別しないものとなります。
(大文字小文字を区別しない正規表現に関しては上の説明を参照して下さい)。
@c COMMON
@end defun

@defun regexp? @var{obj}
@c EN
Returns true iff @var{obj} is a regexp object.
@c JP
@var{obj}が正規表現オブジェクトなら真の値を返します。
@c COMMON
@end defun

@defun regexp->string @var{regexp}
@c EN
Returns a source string describing the regexp @var{regexp}.
The returned string is immutable.
@c JP
正規表現@var{regexp}を記述する元になった文字列を返します。
返される文字列は変更不可な文字列です。
@c COMMON
@end defun

@defun rxmatch regexp string
@c EN
@var{Regexp} is a regular expression object.
A string @var{string} is matched by
@var{regexp}.  If it matches, the function returns a @code{<regmatch>}
object.  Otherwise it returns @code{#f}.
@c JP
正規表現オブジェクト@var{regexp}に一致するものを文字列@var{string}から
探します。一致が見付かった場合は@code{<regmatch>}オブジェクトを返し、
見付からなかった場合は@code{#f}を返します。
@c COMMON

@c EN
This is called @code{match}, @code{regexp-search} or @code{string-match}
in some other Scheme implementations.
@c JP
他のScheme処理系ではこれは
@code{match}、@code{regexp-search}、@code{string-match}など
様々な名で呼ばれています。
@c COMMON
@end defun

@deftp {Generic application} @var{regexp} @var{string}
@c EN
A regular expression object can be applied directly to the string.
This works the same as @code{(rxmatch @var{regexp} @var{string})},
but allows shorter notation.   @xref{Applicable objects}, for
generic mechanism used to implement this.
@c JP
正規表現オブジェクトは直接文字列に対して適用することもできます。
これは@code{(rxmatch @var{regexp} @var{string})}と同じ動作をしますが、
表記が短くて済みます。この機能は@ref{Applicable objects} で述べているメカニズムを
使って実装されています。
@c COMMON
@end deftp

@defun rxmatch-start match :optional (i 0)
@defunx rxmatch-end match :optional (i 0)
@defunx rxmatch-substring match :optional (i 0)
@c EN
@var{Match} is a match object returned by @code{rxmatch}.
If @var{i} equals to zero, the functions return
start, end or the substring of entire match, respectively.
With positive integer @var{I}, it returns those of @var{I}-th
submatches.  It is an error to pass other values to @var{I}.
@c JP
@code{rxmatch}が返すマッチオブジェクト@var{match}から情報を取り出します。
@var{i}が省略されるか0の場合、これらの手続きはそれぞれ一致した
文字列の開始インデックス、終了インデックス、および一致した部分文字列を
返します。@var{i}に正の整数が与えられた場合は、@var{i}番目のサブマッチ
に関する情報を返します。@var{i}にシンボルが与えられた場合は、名前
@var{i}を持つサブマッチの情報を返します。同じ名前@var{i}を持つ複数の
サブマッチがある場合には、成功したサブマッチの情報を返します。
@var{i}にそれ以外の値を与えるのはエラーです。
@c COMMON

@c EN
It is allowed to pass @code{#f} to @var{match} for convenience.
The functions return @code{#f} in such case.
@c JP
簡便のために、@var{match}に@code{#f}を渡すことも許されています。
その場合、これらの手続きは@code{#f}を返します。
@c COMMON

@c EN
These functions correspond to scsh's @code{match:start}, @code{match:end}
and @code{match:substring}.
@c JP
これらの手続きはScshで@code{match:start}、@code{match:end}、
@code{match:substring}と呼ばれているものと等価です。
@c COMMON
@end defun

@defun rxmatch-num-matches match
@c EN
Returns the number of matches in @var{match}.
The number includes the "whole match", so it is always a positive
integer for a @code{<regmatch>} object.  The number also includes
the submatches that don't have value (see the examples below).

For the convenience, @code{rxmatch-num-matches} returns 0
if @var{match} is @code{#f}.
@c JP
@var{match}の持つマッチの数を返します。この数には
「マッチ全体」も含まれるので、@code{<regmatch>}オブジェクトに対しては
常に正の整数が返ることになります。また、値を持たないマッチもカウントされます
(下の例を参照)。

簡便のために、@var{match}に@code{#f}を渡すこともできます。
その場合は0が返ります。
@c COMMON

@example
(rxmatch-num-matches (rxmatch #/abc/ "abc"))
  @result{} 1

(rxmatch-num-matches (rxmatch #/(a(.))|(b(.))/ "ba"))
  @result{} 5

(rxmatch-num-matches #f)
  @result{} 0
@end example

@end defun

@defun rxmatch-after match :optional (i 0)
@defunx rxmatch-before match :optional (i 0)
@c EN
Returns substring of the input string after or before @var{match}.
If optional argument is given, the @var{i}-th submatch is used
(0-th submatch is the entire match).
@c JP
マッチオブジェクト@var{match}の前および後の文字列を返します。
正の整数が@var{i}に与えられた場合はi番目のサブマッチの前および後の
文字列を返します。シンボルが与えられた場合は、その名前を持つ
サブマッチの前後の文字列を返します。
@c COMMON

@example
(define match (rxmatch #/(\d+)\.(\d+)/ "pi=3.14..."))

(rxmatch-after match) @result{} "..."
(rxmatch-after match 1) @result{} ".14..."

(rxmatch-before match) @result{} "pi="
(rxmatch-before match 2) @result{} "pi=3."
@end example
@end defun

@defun rxmatch->string regexp string :optional selector @dots{}
A convenience procedure to match a string to the given regexp,
then returns the matched substring, or @code{#f} if it doesn't match.

If no @var{selector} is given, it is the same as this:

@example
(rxmatch-substring (rxmatch @var{regexp} @var{string}))
@end example

If an integer is given as a selector, it returns the subtring
of the numbered submatch.

If a symbol @code{after} or @code{before} is given, it returns
the substring after or before the match.  You can give these symbols
and an integer to extract a substring before or after the numbered
submatch.

@example
gosh> (rxmatch->string #/\d+/ "foo314bar")
"314"
gosh> (rxmatch->string #/(\w+)@@([\w.]+)/ "foo@@example.com" 2)
"example.com"
gosh> (rxmatch->string #/(\w+)@@([\w.]+)/ "foo@@example.com" 'before 2)
"foo@@"
@end example
@end defun

@deftp {Generic application} @var{regmatch} :optional @var{index}
@deftpx {Generic application} @var{regmatch} @code{'before} :optional @var{index}
@deftpx {Generic application} @var{regmatch} @code{'after} :optional @var{index}
@c EN
A regmatch object can be applied directly to the integer index,
or a symbol @code{before} or @code{after}.
They works the same as @code{(rxmatch-substring @var{regmatch} @var{index})},
@code{(rxmatch-before @var{regmatch})}, and
@code{(rxmatch-after @var{regmatch})}, respectively.
This allows shorter notation.  @xref{Applicable objects}, for
generic mechanism used to implement this.
@c JP
マッチオブジェクトは直接整数のインデックスもしくはシンボルに対して適用することが
できます。整数に適用したときは@code{(rxmatch-substring @var{regmatch} @var{index})}、
シンボル@code{before}のときは@code{(rxmatch-before @var{regmatch})}、シンボル
@code{after}のときは@code{(rxmatch-after @var{regmatch})}、そのほかのシンボルのときは
@code{(rxmatch-substring @var{regmatch} @var{symbol})}と同じ動作をします。

表記が短くて済みます。
この機能は@ref{Applicable objects} で述べているメカニズムを使って実装されています。
@c COMMON

@example
(define match (#/(\d+)\.(\d+)/ "pi=3.14..."))

  (match)           @result{} "3.14"
  (match 1)         @result{} "3"
  (match 2)         @result{} "14"

  (match 'after)    @result{} "..."
  (match 'after 1)  @result{} ".14..."

  (match 'before)   @result{} "pi="
  (match 'before 2) @result{} "pi=3."

(define match (#/(?<integer>\d+)\.(?<fraction>\d+)/ "pi=3.14..."))

  (match 1)         @result{} "3"
  (match 2)         @result{} "14"

  (match 'integer)  @result{} "3"
  (match 'fraction) @result{} "14"

  (match 'after 'integer)   @result{} ".14..."
  (match 'before 'fraction) @result{} "pi=3."

@end example
@end deftp

@defun regexp-replace regexp string substitution
@defunx regexp-replace-all regexp string substitution
@c EN
Replaces the part of @var{string} that matched to @var{regexp}
for @var{substitution}.  @code{regexp-replace} just replaces
the first match of @var{regexp}, while @code{regexp-replace-all}
repeats the replacing throughout entire @var{string}.
@c JP
@var{string}中で@code{regexp}にマッチした部分を@var{substitution}で
置き換えます。@code{regexp-replace}は最初にマッチした部分のみを置き換え、
@code{regexp-replace-all}は全てのマッチを置き換えます。
@c COMMON

@c EN
@var{substitution} may be a string or a procedure.  If it is a string,
it can contain references to the submatches by
digits preceded by a backslash (e.g. @code{\2})
or the named submatch reference (e.g. @code{\k<@var{name}>}.
@code{\0} refers to the
entire match.  Note that you need two backslashes to include
backslash character in the literal string; if you want to include a backslash
character itself in the @var{substitution}, you need four backslashes.
@c JP
@var{substitution}は文字列か手続きです。
文字列の場合、バックスラッシュに続く数値、もしくは
@code{\k<@var{name}>}という形式でサブマッチ文字列を参照できます
@code{\0}はマッチ文字列全体を参照します。文字列リテラルにバックスラッシュを
埋め込む場合は二つのバックスラッシュが必要であることに注意して下さい。
バックスラッシュそのものを@var{substitution}中で使いたい場合は
二つのバックスラッシュを重ねます; 文字列リテラルの場合は4つのバックスラッシュが
必要になります。
@c COMMON

@example
(regexp-replace #/def|DEF/ "abcdefghi" "...")
  @result{} "abc...ghi"
(regexp-replace #/def|DEF/ "abcdefghi" "|\\0|")
  @result{} "abc|def|ghi"
(regexp-replace #/def|DEF/ "abcdefghi" "|\\\\0|")
  @result{} "abc|\\0|ghi"
(regexp-replace #/c(.*)g/ "abcdefghi" "|\\1|")
  @result{} "ab|def|hi"
(regexp-replace #/c(?<match>.*)g/ "abcdefghi" "|\\k<match>|")
  @result{} "ab|def|hi"
@end example

@c EN
If @var{substitution} is a procedure, for every match in @var{string}
it is called with one argument, regexp-match object.  The returned
value from the procedure is inserted to the output string using
@code{display}.
@c JP
@var{substitution}が手続きである場合、@var{string}中の各マッチについて、
マッチオブジェクトを引数としてその手続きが呼ばれます。その手続きが返す
値を@code{display}で表現したものが置換文字列として使われます。
@c COMMON

@example
(regexp-replace #/c(.*)g/ "abcdefghi" 
                (lambda (m)
                  (list->string
                   (reverse
                    (string->list (rxmatch-substring m 1))))))
 @result{} "abfedhi"
@end example

@c EN
Note: @code{regexp-replace-all} applies itself recursively to the remaining 
of the string after match.  So the beginning of string assertion
in @var{regexp} doesn't only mean the beginning of input string.
@c JP
註: @code{regexp-replace-all} は文字列でマッチした部分の後ろの部分に
ついて再帰的に自分自身を適用します。従って、@var{regexp}が
文字列先頭のアサーション (@code{^}) を含んでいても、それは@var{string}の
先頭だけにマッチするとは限りません。
@c COMMON
@end defun

@defun regexp-replace* string rx1 sub1 rx2 sub2 @dots{}
@defunx regexp-replace-all* string rx1 sub1 rx2 sub2 @dots{}
@c EN
First applies @code{regexp-replace} or @code{regexp-replace-all} to
@var{string} with a regular expression @var{rx1} substituting for
@var{sub1}, then applies the function on the result string
with a regular expression @var{rx2} substituting for @var{sub2}, and
so on.  These functions are handy when you want to apply
multiple substitutions sequentially on a string.
@c JP
まず、@code{regexp-replace} あるいは @code{regexp-replace-all} を
正規表現 @var{rx1}、置換 @var{sub1} で @var{string} に適用し、
その結果にさらに @code{regexp-replace} あるいは
@code{regexp-replace-all} を正規表現 @var{rx2}、置換 @var{sub2} で
適用し、以下同様です。これらの関数はひとつの文字列上で複数回置換を行う
ときに便利です。
@c COMMON
@end defun

@defun regexp-quote string
@c EN
Returns a string with the characters that are special to regexp escaped.
@c JP
@var{string}中で、正規表現において特別な意味を持つ文字を全てエスケープした
文字列を返します。
@c COMMON

@example
(regexp-quote "[2002/10/12] touched foo.h and *.c")
 @result{} "\\[2002/10/12\\] touched foo\\.h and \\*\\.c"
@end example
@end defun


@c EN
In the following macros, @var{match-expr} is an expression
which produces a match object or @code{#f}. Typically
it is a call of @code{rxmatch}, but it can be any expression.
@c JP
以下のマクロにおいて、@var{match-expr}はマッチオブジェクトか
@code{#f}を生成する式でなければなりません。通常それは
@code{rxmatch}を呼ぶ式になりますが、それだけに限られるわけではありません。
@c COMMON

@defmac rxmatch-let match-expr (var @dots{}) form @dots{}

@c EN
Evaluates @var{match-expr}, and if matched, binds @var{var @dots{}}
to the matched strings, then evaluates @var{form}s.
The first @var{var} receives the entire match, and subsequent
variables receive submatches.  If the number of submatches are
smaller than the number of variables to receive them, the rest
of variables will get @code{#f}.
@c JP
@var{match-expr}を評価し、それがマッチオブジェクトを返したら、
マッチした文字列を@var{var @dots{}}に束縛し、@var{form}を評価します。
最初の@var{var}はマッチした文字列全体に束縛され、
以降の変数はサブマッチ文字列に束縛されます。実際のサブマッチ文字列が
与えられた変数より少なかった場合は、余った変数は@code{#f}に束縛されます。
@c COMMON

@c EN
It is possible to put @code{#f} in variable position, which says
you don't care that match.
@c JP
特定のマッチ文字列を受け取る必要が無いときは、その場所の
変数の変わりに@code{#f}を置いておくこともできます。
@c COMMON

@example
(rxmatch-let (rxmatch #/(\d+):(\d+):(\d+)/
                      "Jan  1 23:59:58, 2001")
   (time hh mm ss)
  (list time hh mm ss))
 @result{} ("23:59:58" "23" "59" "58")

(rxmatch-let (rxmatch #/(\d+):(\d+):(\d+)/
                      "Jan  1 23:59:58, 2001")
   (#f hh mm)
  (list hh mm))
 @result{} ("23" "59")
@end example

@c EN
This macro corresponds to scsh's @code{let-match}.
@c JP
このマクロはscshの@code{let-match}に相当します。
@c COMMON
@end defmac

@defmac rxmatch-if match-expr (var @dots{}) then-form else-form
@c EN
Evaluates @var{match-expr}, and if matched, binds @var{var} @dots{}
to the matched strings and evaluate @var{then-form}.
Otherwise evaluates @var{else-form}.
The rule of binding @var{var}s is the same as @code{rxmatch-let}.
@c JP
@var{match-expr}を評価し、それがマッチオブジェクトを返したら
マッチした文字列を変数@var{var} @dots{}に束縛して@var{then-form}を
評価します。マッチオブジェクトが返されなければ束縛は行われず、
@var{else-form}が評価されます。変数@var{var}をマッチ文字列に
束縛するルールは@code{rxmatch-let}と同じです。
@c COMMON

@example
(rxmatch-if (rxmatch #/(\d+:\d+)/ "Jan 1 11:22:33")
    (time)
  (format #f "time is ~a" time)
  "unknown time")
 @result{} "time is 11:22"

(rxmatch-if (rxmatch #/(\d+:\d+)/ "Jan 1 11-22-33")
    (time)
  (format #f "time is ~a" time)
  "unknown time")
 @result{} "unknown time"
@end example

@c EN
This macro corresponds to scsh's @code{if-match}.
@c JP
このマクロはscshの@code{if-match}に相当します。
@c COMMON
@end defmac

@defmac rxmatch-cond clause @dots{}
@c EN
Evaluate condition in @var{clause}s one by one.
If a condition of a clause satisfies, rest portion of the clause
is evaluated and becomes the result of @code{rxmatch-cond}.
@var{Clause} may be one of the following pattern.
@c JP
@var{clause}の条件を順に評価してゆき、条件を満たすものが現れたら
その@var{clause}の残りのフォームを評価し、最後のフォームの値を
@code{rxmatch-cond}の値とします。@var{clause}は以下のいずれかの
形式でなければなりません。
@c COMMON

@table @code
@item (@var{match-expr} (@var{var} @dots{}) @var{form} @dots{})
@c EN
Evaluate @var{match-expr}, which may return a regexp match
object or @code{#f}.  If it returns a match object, the matches
are bound to @var{var}s, like @var{rxmatch-let}, and @var{form}s
are evaluated.
@c JP
@var{match-expr}を評価し、それがマッチオブジェクトを返した場合は
マッチ文字列を変数@var{var} @dots{}に束縛した上で
@var{form} @dots{}を評価します。
@c COMMON

@item (test @var{expr} @var{form} @dots{})
@c EN
Evaluates @var{expr}.  If it yields true, evaluates @var{form}s.
@c JP
@var{expr}を評価し、それが真の値を返した場合は@var{form} @dots{}を評価します。
@c COMMON

@item (test @var{expr} => @var{proc})
@c EN
Evaluates @var{expr} and if it is true,
calls @var{proc} with the result of @var{expr} as the only argument.
@c JP
@var{expr}を評価し、それが真の値を返した場合は
それを唯一の引数として手続き@var{proc}を呼びます。
@c COMMON

@item (else @var{form} @dots{})
@c EN
If this clause exists, it must be the last clause.
If other clauses fail, @var{form}s are evaluated.
@c JP
この@var{clause}は、もし与えられたとすれば最後の@var{clause}でなければ
なりません。全ての@var{clause}が失敗した場合に、@var{form} @dots{}が
評価されます。
@c COMMON
@end table

@c EN
If no @code{else} clause exists, and all the other clause fail,
an undefined value is returned.
@c JP
@code{else} @var{clause}が与えられず、かつ全ての@var{clause}が
失敗した場合の戻り値は未定義です。
@c COMMON

@example
@c EN
;; @r{parses several possible date format}
@c JP
;; @r{何通りかの日付のフォーマットをパーズする}
@c COMMON
(define (parse-date str)
  (rxmatch-cond
    ((rxmatch #/^(\d\d?)\/(\d\d?)\/(\d\d\d\d)$/ str)
        (#f mm dd yyyy)
      (map string->number (list yyyy mm dd)))
    ((rxmatch #/^(\d\d\d\d)\/(\d\d?)\/(\d\d?)$/ str)
        (#f yyyy mm dd)
      (map string->number (list yyyy mm dd)))
    ((rxmatch #/^\d+\/\d+\/\d+$/ str)
        (#f)
     (errorf "ambiguous: ~s" str))
    (else (errorf "bogus: ~s" str))))

(parse-date "2001/2/3") @result{} (2001 2 3)
(parse-date "12/25/1999") @result{} (1999 12 25)
@end example

@c EN
This macro corresponds to scsh's @code{match-cond}.
@c JP
このマクロはscshの@code{match-cond}に相当します。
@c COMMON
@end defmac

@defmac rxmatch-case string-expr clause @dots{}
@c EN
@var{String-expr} is evaluated, and @var{clause}s are interpreted
one by one.  A @var{clause} may be one of the following pattern.
@c JP
@var{string-expr}がまず評価され、続いて@var{clause}が順に検査されます。
@var{clause}は以下のいずれかの形式でなければなりません。
@c COMMON

@table @code
@item (@var{re} (@var{var} @dots{}) @var{form} @dots{})
@c EN
@var{Re} must be a literal regexp object (@xref{Regular expressions}).
If the result of @var{string-expr} matches @var{re},
the match result is bound to @var{var}s
and @var{form}s are evaluated, and @code{rxmatch-case} returns
the result of the last @var{form}.
@c JP
@var{re}はリテラル正規表現オブジェクトでなければなりません
(@ref{Regular expressions}参照)。@var{string-expr}の結果が文字列であり
@var{re}にマッチした場合は、マッチ文字列が変数@var{var} @dots{}に
束縛され、@var{form}が評価されます。最後の@var{form}の値が@code{rxmatch-case}
の値となります。
@c COMMON

@c EN
If @var{re} doesn't match the result of @var{string-expr},
@var{string-expr} yields non-string value, the interpretation proceeds
to the next clause.
@c JP
@var{string-expr}の結果の文字列が@var{re}にマッチしないか、
@var{string-expr}の結果が文字列以外であった場合は次の@var{clause}へと
処理が進みます。
@c COMMON

@item (test @var{proc} @var{form} @dots{})
@c EN
A procedure @var{proc} is applied on the result of @var{string-expr}.
If it yields true value, @var{form}s are evaluated, and
@code{rxmatch-case} returns the result of the last @var{form}.
@c JP
手続き@var{proc}が@var{string-expr}の結果を引数として呼ばれます。
それが真の値を返した場合は@var{form}が順に評価され、最後の@var{form}の
値が@code{rxmatch-case}の値として返されます。
@c COMMON

@c EN
If @var{proc} yieds @code{#f}, the interpretation proceeds
to the next clause.
@c JP
@var{proc}が@code{#f}を返した場合は次の@var{clause}へと
処理が進みます。
@c COMMON

@item (test @var{proc} => @var{proc2})
@c EN
A procedure @var{proc} is applied on the result of @var{string-expr}.
If it yields true value, @var{proc2} is applied on the result,
and its result is returned as the result of @code{rxmatch-case}.
@c JP
手続き@var{proc}が@var{string-expr}の結果を引数として呼ばれます。
それが真の値を返した場合は、その値を引数として@var{proc2}が呼ばれ、
その返り値が@code{rxmatch-case}の値として返されます。
@c COMMON

@c EN
If @var{proc} yields @code{#f}, the interpretation proceeds
to the next clause.
@c JP
@var{proc}が@code{#f}を返した場合は次の@var{clause}へと
処理が進みます。
@c COMMON

@item (else @var{form} @dots{})
@c EN
This form must appear at the end of @var{clause}s, if any.
If other clauses fail, @var{form}s are evaluated,
and the result of the last @var{form} becomes the result of
@code{rxmatch-case}.
@c JP
このフォームは、与えられる場合は最後の@var{clause}でなければなりません。
他の全ての@var{clause}が失敗した場合に、@var{form}が順に評価され、最後の@var{form}の
値が@code{rxmatch-case}の値として返されます。
@c COMMON

@item (else => @var{proc})
@c EN
This form must appear at the end of @var{clause}s, if any.
If other clauses fail, @var{proc} is evaluated, which should
yield a procedure taking one arugment.  The value of @var{string-expr}
is passed to @var{proc}, and its return values become the
return values of @code{rxmatch-case}.
@code{rx}
@c JP
このフォームは、与えられる場合は最後の@var{clause}でなければなりません。
他の全ての@var{clause}が失敗した場合に、@var{proc}が評価されます。
その値は一引数の手続きにならなければなりません。
その手続きが、@var{string-expr}の値を引数として呼ばれます。
@var{proc}の結果が@code{rxmatch-case}の値となります。
@c COMMON
@end table

@c EN
If no @code{else} clause exists, and all other clause fail,
an undefined value is returned.
@c JP
@code{else} @var{clause}が与えられず、かつ全ての@var{clause}が
失敗した場合の戻り値は未定義です。
@c COMMON

@c EN
The @code{parse-date} example above becomes simpler if you use
@code{rxmatch-case}
@c JP
上の@code{parse-date}の例は@code{rxmatch-case}を使うとより単純になります。
@c COMMON

@example
(define (parse-date2 str)
  (rxmatch-case str
    (test (lambda (s) (not (string? s))) #f)
    (#/^(\d\d?)\/(\d\d?)\/(\d\d\d\d)$/ (#f mm dd yyyy)
     (map string->number (list yyyy mm dd)))
    (#/^(\d\d\d\d)\/(\d\d?)\/(\d\d?)$/ (#f yyyy mm dd)
     (map string->number (list yyyy mm dd)))
    (#/^\d+\/\d+\/\d+$/                (#f)
     (errorf "ambiguous: ~s" str))
    (else (errorf "bogus: ~s" str))))
@end example
@end defmac

@node Inspecting and assembling regular expressions,  , Using regular expressions, Regular expressions
@subsection Inspecting and assembling regular expressions
@c NODE 正規表現の調査と合成

When Gauche reads regexp from string, first it parses
string representation and construct an abstract
syntax tree (AST), perform some optimizations on it,
then compiles into an instruction sequence to be
executed by the regexp engine.  

The following procedures expose this process to
user programs.  It may be easier for programs to
manipulate AST than string representation.

@defun regexp-parse string :key case-fold
Parses a string specification of regexp in @var{string}
and returns its AST, represented in S-expression.
See below for the spec of AST.

When a true value is given to the keyword argument @var{case-fold},
returned AST will match case-insensitively.
(Case insensitive regexp is handled in parser level,
not by the engine).
@end defun

@defun regexp-optimize ast
Performs some rudimental optimization on the regexp AST,
returning regexp AST.

Currently it only optimizes some obvious cases.  The plan is
to make it cleverer in future.
@end defun

@defun regexp-compile ast
Takes an regexp AST and returns a regexp object.
Currently the outermost form of @var{ast} must be
a zero-th capturing group.  It is always added
by @code{regexp-parse} to capture the entire regexp.

Note: The function does some basic check to see the given AST
is valid, but it may not reject invalid ASTs.  In such case,
the returned regexp object doesn't work properly.  It is
caller's responsibility to provide a properly constructed AST.
(Even if it rejects an AST, error messages are often
incomprehensible.)
@end defun

@defun regexp-ast regexp
Returns AST used for the regexp object @var{regexp}.
@end defun

@defun regexp-unparse ast :key (on-error :error)
From the regexp's @var{ast}, reconstruct the string representation
of the regexp.  The keyword argument @var{on-error} can be
a keyword @code{:error} (default) or @code{#f}.  If its the former,
an error is signalled when @var{ast} isn't valid regexp AST.
If it's the latter, @code{regexp-unparse} just returns @code{#f}.
@end defun

This is the structure of AST.  Note that this is originally
developed only for internal use, and not very convenient to manipulate
from the code (e.g. if you insert or delete a subtree, you have to 
renumber capturing groups to make them consitent.)  There's a plan
to provide a better representation, such as SRE, and a tool
to convert it to this AST back and forth.   Contributions are welcome.

@smallexample
<ast> : <clause>   ; special clause
      | <item>     ; matches <item>

<item> : <char>       ; matches char
       | <char-set>   ; matches char set
       | (comp . <char-set>) ; matches complement of char set
       | any          ; matches any char
       | bol | eol    ; beginning/end of line assertion
       | wb | nwb     ; word-boundary/negative word boundary assertion

<clause> : (seq <ast> ...)       ; sequence
       | (seq-uncase <ast> ...)  ; sequence (case insensitive match)
       | (seq-case <ast> ...)    ; sequence (case sensitive match)
       | (alt <ast> ...)         ; alternative
       | (rep <m> <n> <ast> ...) ; repetition at least <m> up to <n> (greedy)
                               ; <n> may be `#f'
       | (rep-min <m> <n> <ast> ...)
                               ; repetition at least <m> up to <n> (lazy)
                               ; <n> may be `#f'
       | (rep-while <m> <n> <ast> ...)
                               ; like rep, but no backtrack
       | (<integer> <symbol> <ast> ...)
                               ; capturing group.  <symbol> may be #f.
       | (cpat <condition> <ast> <ast>)
                               ; conditional expression
       | (backref . <integer>) ; backreference
       | (once <ast> ...)      ; standalone pattern.  no backtrack
       | (assert . <asst>)     ; positive lookahead assertion
       | (nassert . <asst>)    ; negative lookahead assertion

<condition> : <integer>     ; (?(1)yes|no) style conditional expression
       | (assert . <asst>)  ; (?(?=condition)...) or (?(?<=condition)...)
       | (nassert . <asst>) ; (?(?!condition)...) or (?(?<!condition)...)

<asst> : <ast> ...
       | ((lookbehind <ast> ...))
@end smallexample

@c ----------------------------------------------------------------------
@node Vectors, Hashtables, Regular expressions, Core library
@section Vectors
@c NODE ベクタ

@deftp {Builtin Class} <vector>
@clindex vector
@c EN
A vector is a simple 1-dimensional array of Scheme objects.
You can access its element by index in constant time.
Once created, a vector can't be resized.

Class @code{<vector>} inherits @code{<sequence>} and 
you can use various generic functions such as @code{map} and @code{fold}
on it.   @xref{Collection framework}, and @xref{Sequence framework}.

If you keep only a homogeneous numeric type, you may be able
to use SRFI-4 homogeneous vectors (@xref{Homogeneous vectors}).

@xref{Vector library}, for additional operations on vectors.
@c JP
ベクタはSchemeオブジェクトの単純な一次元配列です。
インデックスを用いて定数時間でその要素にアクセスできます。
一度作成されたベクタはその大きさを変えることはできません。

@code{<vector>}クラスはまた@code{<sequence>}クラスを継承し、
@code{map}や@code{fold}など様々な総称関数を使うことができます。
@ref{Collection framework} と
@ref{Sequence framework} を参照して下さい。

数値しか要素に持たないベクタを使う場合、SRFI-4の
単一型ベクタも使えるかもしれません (@ref{Homogeneous vectors}参照)。

より多くのベクタに対する操作が@ref{Vector library}で提供されています。
@c COMMON
@end deftp

@defun vector? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a vector, @code{#f} otherwise.
@c JP
@var{obj}がベクタなら@code{#t}を、そうでなければ@var{#f}を返します。
@c COMMON
@end defun

@defun make-vector k :optional fill
[R5RS]
@c EN
Creates and returns a vector with length @var{k}.
If optional argument @var{fill} is given, each element of the vector
is initialized by it.  Otherwise, the initial value of each element
is undefined.
@c JP
長さ@var{k}のベクタを作成して返します。
省略可能な引数@var{fill}が与えられていれば、ベクタの各要素はその値で
初期化されます。そうでなければベクタの各要素の値は不定です。
@c COMMON
@end defun

@defun vector obj @dots{}
[R5RS]
@c EN
Creates a vector whose elements are @var{obj} @dots{}.
@c JP
要素が@var{obj} @dots{}であるようなベクタを作成して返します。
@c COMMON
@end defun

@defun vector-length vector
[R5RS]
@c EN
Returns the length of a vector @var{vector}.

With @code{gauche.collection} module,
you can also use a method @code{size-of}.
@c JP
ベクタ@var{vector}の長さを返します。

@code{gauche.collection}モジュールをロードしていれば、
メソッド@code{size-of}も同じ目的で使えます。
@c COMMON
@end defun

@defun vector-ref vector k :optional fallback
[R5RS+]
@c EN
Returns @var{k}-th element of vector @var{vector}.

By default, @code{vector-ref} signals an error if @var{k} is
negative, or greater than or equal to the length of @var{vector}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.  This is an extension of Gauche.

With @code{gauche.sequence} module,
you can also use a method @code{ref}.
@c JP
ベクタ@var{vector}の@var{k}番目の要素を返します。

@code{vector-ref}は@var{k}が負の値であったりベクタの長さより
大きかったりした場合はエラーを通知します。但し、省略可能な引数@var{fallback}
が与えられている場合はその値が返されます。これはGaucheの拡張です。

@code{gauche.sequence}モジュールをロードしていれば、
メソッド@code{ref}も同じ目的で使えます。
@c COMMON
@end defun

@defun vector-set! vector k obj
[R5RS]
@c EN
Sets @var{k}-th element of the vector @var{vector} to @var{obj}.
It is an error if @var{k} is negative or greater than or equal to the
length of @var{vector}.

With @code{gauche.sequence} module, you can also use
a setter method of @code{ref}.
@c JP
ベクタ@var{vector}の@var{k}番目の要素を@var{obj}に変更します。
@var{k}が負数であったりベクタの長さより大きい場合はエラーとなります。

@code{gauche.sequence}モジュールをロードしていれば、
メソッド@code{ref}のsetterメソッドも使えます。
@c COMMON
@end defun

@defun vector->list vector :optional start end
@defunx list->vector list :optional start end
[R5RS+][SRFI-43+]
@c EN
Converts a vector to a list, or vice versa.

The optional @var{start} and @var{end} arguments
limit the range of the source.
@c JP
ベクタをリストに変換したり、その逆を行う手続きです。

省略可能な引数@var{start}と@var{end}を与えることにより、
値を取り出す範囲を制限することができます。

@c COMMON
@example
(vector->list '#(1 2 3 4 5))     @result{} (1 2 3 4 5)
(list->vector '(1 2 3 4 5))      @result{} #(1 2 3 4 5)
(vector->list '#(1 2 3 4 5) 2 4) @result{} (3 4)
(list->vector (circular-list 'a 'b 'c) 1 6)
  @result{} #(b c a b c)
@end example

@c EN
With @var{gauche.collection} module, you can use
@code{(coerce-to <list> @var{vector})} and 
@code{(coerce-to <vector> @var{list})} as well.
@c JP
@code{gauche.collection}モジュールをロードしていれば、
@code{(coerce-to <list> @var{vector})} と
@code{(coerce-to <vector> @var{list})} も同じ目的で使えます。
@c COMMON
@end defun

@defun vector-fill! vector fill :optional start end
[R5RS+][SRFI-43]
@c EN
Sets all elements in a vector @var{vector} to @var{fill}.

Optional @var{start} and @var{end} limits the range
of effect between @var{start}-th index (inclusive) to
@var{end}-th index (exclusive).  @var{Start} defaults to
zero, and @var{end} defaults to the length of @var{vector}.
These optional arguments are Gauche's extension.
@c JP
ベクタ@var{vector}の全ての要素を@var{fill}に変更します。

省略可能な引数@var{start}と@var{end}が与えられた場合、
@var{start}番目の要素から@var{end}-1番目の要素までのみに
@var{fill}を格納します。@var{start}と@var{end}の既定値は
それぞれ0と@var{vector}の大きさです。
@var{start}, @var{end}引数はGaucheの拡張です。
@c COMMON
@end defun

@defun vector-copy vector :optional start end fill
[SRFI-43]
@c EN
Copies a vector @var{vector}.  Optional @var{start} and @var{end}
arguments can be used to limit the range of @var{vector} to be copied.
If the range specified by @var{start} and @var{end} falls outside of
the original @var{vector}, the @var{fill} value is used to fill
the result vector.
@c JP
ベクタ@var{vector}をコピーします。引数@var{start}と@var{end}を与えることで
コピーされる範囲を制限することができます。
@var{start}と@var{end}で指定される範囲が元の@var{vector}の範囲を越えた
場合は、その部分が@var{fill}で埋められます。
@c COMMON

@example
(vector-copy '#(1 2 3 4 5))     @result{} #(1 2 3 4 5)
(vector-copy '#(1 2 3 4 5) 2 4) @result{} #(3 4)
(vector-copy '#(1 2 3 4 5) 3 7 #f) @result{} #(4 5 #f #f)
@end example
@end defun

@c ----------------------------------------------------------------------
@node Hashtables, Treemaps, Vectors, Core library
@section Hashtables
@c NODE ハッシュテーブル

@deftp {Builtin Class} <hash-table>
@clindex hash-table
@c EN
Hash table class.  Inherits @code{<collection>} and @code{<dictionary>}.
@c JP
ハッシュテーブルのクラスです。@code{<collection>}と@code{<dictionary>}を
継承します。
@c COMMON
@end deftp


@defun make-hash-table :optional type
@c EN
Creates a hash table.   A symbol @var{type} specifies the type of the table.
The following types are currently supported.
(If @var{type} is omitted, @code{eq?} is assumed.)
@c JP
ハッシュテーブルを作成します。シンボル@var{type}はテーブルのタイプを指定します。
現在、以下のようなタイプがサポートされています。
(@var{type}が省略された場合は@code{eq?}とみなされます。)
@c COMMON
@table @code
@item eq?
@c EN
Keys are compared by @code{eq?}.
@c JP
キーの比較に@code{eq?}を使います。
@c COMMON
@item eqv?
@c EN
Keys are compared by @code{eqv?}.
@c JP
キーの比較に@code{eqv?}を使います。
@c COMMON
@item equal?
@c EN
Keys are compared by @code{equal?}.
@c JP
キーの比較に@code{equal?}を使います。
@c COMMON
@item string=?
@c EN
Keys are compared by @code{string=?}.  Key must be a string.
@c JP
キーの比較に@code{string=?}を使います。キーは文字列でなければなりません。
@c COMMON
@end table

@c EN
Hash functions used for @code{eq?}, @code{eqv?} and
@code{string=?}-type hash tables are built in the system;
they can be called from Scheme as @code{eq-hash}, @code{eqv-hash},
and @code{string-hash} (SRFI-13).  Those functions can't be extended
for user-defined objects.   On the other hand, @code{equal?}-type
hash tables uses @code{hash} function below, with which you
define hash functions for user-defined objects.
@c JP
@code{eq?}、@code{eqv?}、@code{string=?}タイプのハッシュテーブルでは、
システム組み込みのハッシュ関数が使われます。Schemeからは、
それらのハッシュ関数はそれぞれ@code{eq-hash}、@code{eqv-hash}、
そしてSRFI-13の@code{string-hash}として呼ぶことができます。
これらの関数はユーザ定義型に対応するように拡張することはできません。
一方、@code{equal?}タイプのハッシュテーブルは
下に述べる@code{hash}関数を使います。後者では、ユーザ定義型に対するハッシュ関数を
独自に定義することができます。
@c COMMON

@end defun

@defun hash obj
@c EN
Returns a hash value of @var{obj}.  This is the hash function used
in @code{equal?}-type hash table.  The hash value is an exact
non-negative integer, and it has two properties:
@itemize
@item
For any object @var{a} and @var{b}, 
if @code{(equal? @var{a} and @var{b})}, 
then @code{(= (hash @var{a}) (hash @var{b}))},
while @code{hash} is defined for types of @var{a} and @var{b}.
@item
The value of @code{hash} is independent from the runtime state
of the machine (such as address of the data); so you can safely save
the hash value to file and read it again with different process
without losing validity of the hash value.
@end itemize
If @var{obj} is either a number, a boolean, a character, 
a symbol, a keyword, a string, a list or a vector,
internal hash function is used to calculate the hash value.
If @var{obj} is other than that, @code{hash} calls
a generic function @code{object-hash} to calculate the hash value.
@c JP
@var{obj} のハッシュ値を返します。@code{equal?}-タイプのハッシュテーブルで
利用するハッシュ関数です。この関数が返すハッシュ値は正確な非負整数で、
以下の二つの性質があります。
@itemize
@item
@var{a} および @var{b} の型について、@code{hash} が定義されているとき、
あらゆるオブジェクト @var{a} および  @var{b} に対して、
@code{(equal? @var{a} @var{b})} であれば
@code{(= (hash @var{a}) (hash @var{b}))}。
@item
@code{hash} は(そのデータのアドレスというような)実行時の計算機の状態とは
独立しています。それゆえ、その値をファイルに格納し、別のプロセスで読み込んで
利用しても、ハッシュ値の正当性を失うことがないので、安全です。
@end itemize
@var{obj} が、数値、真理値、文字、シンボル、キーワード、文字列、リスト、
ベクタのいずれかならば、そのハッシュ値を求めるのには内部ハッシュ関数を
使います。
@var{obj} が、それ以外であれば、 @code{hash} は総称関数 @code{object-hash}
を呼んで、そのハッシュ値を計算します。
@c COMMON
@end defun

@deffn {Generic Function} object-hash obj
@c EN
By defining a method for this generic function, objects of
user-defined types can have a hash value and can be used
in @code{equal?} hash table.  

The method has to return an exact non-negative integer, and
has to follow the same constraints as of @code{hash}.

If the method needs to get hash value of @var{obj}'s elements,
it has to call @code{hash} on them, not @code{object-hash}.
For the hashing of primitive objects are done in @code{hash}.
@c JP
この総称関数に対するメソッドを定義することにより、ユーザ定義された
型のオブジェクトはハッシュ値を持つことができ、@code{equal?}型のハッシュ
テーブルで利用することができるようになります。

メソッドは正確な非負整数を返さなければなりません。また、@code{hash} と
同じ制約に従わなければなりません。

メソッドが @var{obj} の要素のハッシュ値を必要とする場合には、
それらに対しては、@code{object-hash} ではなく、@code{hash} を
呼ばなければなりません。プリミティブなオブジェクトのハッシュ計算は
@code{hash} が行うからです。

@c COMMON
@example
(define-class <myclass> () (x y))

;; user-defined equality function
(define-method object-equal? ((a <myclass>) (b <myclass>))
  (and (equal? (ref a 'x) (ref b 'x))
       (eq?    (ref a 'y) (ref b 'y))))

;; user-defined hash function
(define-method object-hash ((a <myclass>))
  (hash (list (ref a 'x) (ref a 'y))))
@end example
@end deffn

@defun eq-hash obj
@defunx eqv-hash obj
@c EN
These are hash functions used for @code{eq?}-type and @code{eqv?}-type
hash tables.  Returns a non-negative integer up to 2^@emph{n}-1, where
@emph{n} is system-dependent value no less than 32.
The returned hash value is system- and process-dependent,
and can't be carried over the boundary of the running process.

Note: don't hash numbers by @code{eq-hash}.  Two numbers
are not guaranteed to be @code{eq?} even if they are numerically equal,
so they are not supposed to be used as a key in @code{eq?}-type hash table.
@c JP
この2つは @code{eq?}-タイプおよび @code{eqv?}-タイプのハッシュテーブル
用のハッシュ関数で、2^@emph{n}-1 以下の非負の整数を返します。ここで、
@emph{n} は 32 以上のシステム依存の値です。返り値のハッシュ値は、
システムおよびプロセスに依存する値です。動作しているプロセスの境界を
超えてもちまわることはできません。

注意: @code{eq-hash} をつかって、数をハッシュしてはいけません。
2つの数はたとえその値が等しくても @code{eq?} であることは保証されて
いません。したがって、@code{eq?}-タイプのハッシュテーブルで、
数のキーとしての使用はサポートされていません。
@c COMMON
@end defun

@defun hash-table? obj
@c EN
Returns @code{#t} if @var{obj} is a hash table.
@c JP
@var{obj}がハッシュテーブルであれば@code{#t}を返します。
@c COMMON
@end defun

@defun hash-table-type ht
@c EN
Returns one of symbols @code{eq?}, @code{eqv?}, @code{equal?} or
@code{string=?}, indicating the type of the hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}のタイプに応じて、シンボル
@code{eq?}、@code{eqv?}、@code{equal?}、@code{string=?}のいずれかを
返します。
@c COMMON
@end defun

@defun hash-table-num-entries ht
@c EN
Returns the number of entries in the hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}中の要素の個数を返します。
@c COMMON
@end defun

@defun hash-table type key&value @dots{}
@c EN
Constructs and returns a hash table of type @var{type} from given
list of arguments.
@var{Type} is the same as of @code{make-hash-table}.
Each @var{key&value} must be a pair, and its car is used as a key
and its cdr is used as a value.
@c JP
与えられたキーと値の列からタイプが@var{type}であるハッシュテーブルを構築して
返します。@var{type}の意味は@code{make-hash-table}と同じです。
各@var{key&value}はペアでなければならず、そのcarがキー、cdrが値として使われます。
@c COMMON

@example
(hash-table 'eq? '(a . 1) '(b . 2))
  @equiv{}
  (let ((h (make-hash-table 'eq?)))
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2)
     h)
@end example
@end defun

@defun hash-table-get ht key :optional default
@c EN
Search @var{key} from a hash table @var{ht}, and returns its value
if found.  If the key is not found in the table and @var{default} is
given, it is returned.  Otherwise an error is signalled.
@c JP
キー@var{key}をハッシュテーブル@var{ht}から探します。見つかればキーに対応する
値を返します。キーが見つからなかった場合、@var{default}が与えられていればそれを
返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun hash-table-put! ht key value
@c EN
Puts a key @var{key} with a value @var{value} to the hash table @var{ht}.
@c JP
キー@var{key}と対応する値@var{value}をハッシュテーブル@var{ht}に挿入します。
@c COMMON
@end defun

@deffn {Method} ref (ht <hash-table>) key :optional default
@deffnx {Method} {(setter ref)} (ht <hash-table>) key value
@c EN
Method versions of @code{hash-table-get} and @code{hash-table-put!}.
@c JP
@code{hash-table-get}と@code{hash-table-put!}のメソッド版です。
@c COMMON
@end deffn

@defun hash-table-exists? ht key
@c EN
Returns @code{#t} if a hash table @var{ht} has a key @var{key}.
@c JP
ハッシュテーブル@var{ht}にキー@var{key}を持つエントリがあれば@code{#t}を返します。
@c COMMON
@end defun

@defun hash-table-delete! ht key
@c EN
Deletes an entry that has a key @var{key} from the hash table @var{ht}.
Returns @code{#t} if the entry has exist, or @code{#f} if the entry
hasn't exist.   The same function is called @code{hash-table-remove!} in STk
(except that it returns an undefined value); I use `delete' for consistency
to SRFI-1, SRFI-13 and other parts of the libraries.
@c JP
ハッシュテーブル@code{ht}からキー@var{key}を持つエントリを削除します。
@var{key}を持つエントリが実際に存在して削除された場合は@code{#t}を、
エントリが存在しなかった場合は@code{#f}を返します。
この手続きはSTkで@code{hash-table-remove!}と呼ばれているものです
(STkのは戻り値が定義されていませんが)。GaucheではSRFI-1, SRFI-13やその他の
ライブラリとの一貫性のために `delete' を採用しました。
@c COMMON
@end defun

@defun hash-table-clear! ht
@c EN
Removes all entries in the hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}の全てのエントリを削除します。
@c COMMON
@end defun

@defun hash-table-push! ht key value
@c EN
Conses @var{value} to the existing value for the key @var{key} in the
hash table @var{ht} and makes it the new value for @var{key}.
If there's no entry for @var{key}, an entry
is created with the value @code{(list @var{value})}.

Works the same as the following code, except that this function
only looks up the @var{key} once, thus it's more efficient.
@c JP
ハッシュテーブル@var{ht}中の、キー@var{key}に対応する値に@var{value}をコンスし、
それを@var{key}に対する新たな値とします。もし@var{key}に対応する値がまだ無ければ、
新たなエントリが作成され、@code{(list @var{value})}がその値となります。

この手続きは次のコードと同じ動作をしますが、キーの探索が一度しか行われないためより高速です。
@c COMMON
@example
(hash-table-put! @var{ht} @var{key}
    (cons @var{value} (hash-table-get @var{ht} @var{key} '())))
@end example
@end defun

@defun hash-table-pop! ht key :optional default
@c EN
Looks for the value for the key @var{key} in the hash table @var{ht}.
If found and it is a pair, replaces the value for its cdr and returns
car of the original value.  If no entry for @var{key} is in the table,
or the value is not a pair, the table is not modified and
the procedure returns @var{default} if given, or signals an error otherwise.  

During the operation the key is looked for only once, thus runs
efficiently.
@c JP
ハッシュテーブル@var{ht}中のキー@var{key}に対応する値が存在し、かつペアで
あった場合に、そのエントリーを元の値のcdrで置き換え、元の値のcarを返します。
@var{key}に対応する値が存在しないかペアではなかった場合、テーブルは変更されず、
@var{default}が与えられていればそれが返され、与えられていなければエラーが報告されます。

値が置き換えれる場合でもキーの探索は一度しか行われないため効率が良いです。
@c COMMON
@end defun

@defun hash-table-update! ht key proc :optional default
@c EN
A more general version of @code{hash-table-push!} etc.
It works basically as the following code piece,
except that the lookup of @var{key} is only done once.
@c JP
@code{hash-table-push!}等のより一般的なバージョンです。
ハッシュテーブルの探索が一度しか行われないことを除いては、
基本的に次のように動作します。
@c COMMON
@example
(let ((tmp (@var{proc} (hash-table-get @var{ht} @var{key} @var{default}))))
  (hash-table-put! @var{ht} @var{key} tmp)
  tmp)
@end example

@c EN
For example, when you use a hash table to count the occurrences
of items, the following line is suffice to increment the counter
of the item, regardless of whether @var{item} has already appeared or not.
@c JP
例えば、ハッシュテーブルを使ってオブジェクトの個数を数えているとしましょう。
次の1行で、オブジェクト@var{item}が既に出現したかどうかを気にせずに
その個数をインクリメントできます。
@c COMMON

@example
(hash-table-update! ht item (cut + 1 <>) 0))
@end example

@end defun


@defun hash-table-for-each ht proc
@defunx hash-table-map ht proc
@c EN
A procedure @var{proc} is called with two arguments, a key and its associated
value, over all the entries in the hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}内の全てのエントリについて、各エントリのキーと値を
2つの引数として手続き@var{proc}を呼びます。
@c COMMON
@end defun

@defun hash-table-fold ht kons knil
@c EN
For all entries in the hash table @var{ht},
a procedure @var{kons} is called with three arguments;
a key, its associated value, and the previous return value of @var{kons}.
The first call of @var{kons} receives @var{knil} as the third argument.
The return value of the last call of @var{kons} is returned
from @code{hash-table-fold}.
@c JP
ハッシュテーブル@var{ht}内の全てのエントリについて@var{kons}を呼びます。
@var{kons}には3つの引数が渡されます。
各エントリのキーと値、および一つ前の@var{kons}の返り値です。
最初の@var{kons}の呼び出しの時には、第3引数に@var{knil}が渡されます。
最後の@var{kons}の返り値が@code{hash-table-fold}の返り値となります。
@c COMMON
@end defun

@defun hash-table-keys ht
@defunx hash-table-values ht
@c EN
Returns all the keys or values of hash table @var{ht} in a list,
 respectively.
@c JP
それぞれ、ハッシュテーブル@var{ht}内の全てのキーまたは値をリストにして返します。
@c COMMON
@end defun

@c EN
See also @ref{Additional list library}, where @code{hash-table->alist}
and @code{alist->hash-table} are defined.
@c JP
@ref{Additional list library}も参照して下さい。
@code{hash-table->alist}と@code{alist->hash-table}が定義されています。
@c COMMON

@c ----------------------------------------------------------------------
@node Treemaps, Weak pointers, Hashtables, Core library
@section Treemaps
@c NODE ツリーマップ

@deftp {Builtin Class} <tree-map>
@clindex tree-map
@c EN
Tree map class.   Tree maps are a data structure that maps key objects
to value objects.  It's like hash tables except tree maps uses
balanced tree internally.  Insertion and lookup is O(log n).
@c JP
ツリーマップクラス。ツリーマップはキーオブジェクトから値オブジェクトへ
の写像をあらわすデータ構造です。ツリーマップでは平衡木を使うということ
以外はハッシュテーブルと同じです。ツリーマップでは挿入と検索の手間は
O(log n)です。
@c COMMON

@c EN
Unlike hashtables, a tree map keeps the order of the keys, so
it is easy to traverse entries in the order of keys, to find 
minimum/maximum keys, or to find a key closest to the given value.
@c JP
ハッシュテーブルとはちがい、キーの順序は保存されます。したがってキーの
順序どおりにトラバースするのは簡単で、キーの最小値/最大値を見つけたり、
指定したキーにもっとも近いキーを探すのも簡単です。
@c COMMON

@c EN
The @code{<tree-map>} class inherits @code{<sequence>} and
@code{<ordered-dictionary>}.
@c JP
@code{<tree-map>}クラスは@code{<sequence>}および
@code{<ordered-dictionary>}を継承しています。
@c COMMON
@end deftp

@defun make-tree-map key=? key<?
@c EN
Creates and returns an instance of @code{<tree-map>}.
The arguments @var{key=?} and @var{key<?} are both
procedures that take two arguments, which are the keys.
The @code{key=?} procedure should return @code{#t} if
two arguments are equivalent, or @code{#f} otherwise.
The @code{key<?} procedure should return @code{#t} if
the first argument is strictly less than the second argument,
or @code{#f} otherwise.
@c JP
@code{<tree-map>}オブジェクトを作成して返します。
@var{key=?}、@var{key<?}はそれぞれ引
数を2つ受け取り真偽値を返す手続きであり、要素のキーが渡されます。
@var{key=?}は、2つの引数a, b が同値の場合に真を、それ以外の場合に@code{#f}を
返す手続きです。@var{key<?}は、@code{a < b}が成り立つ場合に真を、それ以外の
場合に@code{#f}を返す手続きです。
@c COMMON
@end defun

@defun tree-map-copy tree-map
@c EN
Copies and returns  @var{tree-map}.  Modification
on the returned tree doesn't affect the original tree.
@c JP
@var{tree-map}のコピーを作り、それを返します。返された木に対す
る破壊的操作は、元の木に影響を与えません。
@c COMMON
@end defun

@defun tree-map-empty? tree-map
@c EN
Returns @code{#t} if @var{tree-map} doesn't have any elements,
or @code{#f} otherwise.
@c JP
@var{tree-map}が要素を持たないなら@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun tree-map-num-entries tree-map
@c EN
Returns the number of elements in @var{tree-map}.
@c JP
@var{tree-map}内の要素の個数を返します。
@c COMMON
@end defun

@defun tree-map-exists? tree-map key
@c EN
Returns @code{#t} if @var{tree-map} has an entry with @var{key},
or @code{#f} otherwise.
@c JP
@var{tree-map}にキー@var{key}を持つエントリがあれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun tree-map-get tree-map key :optional fallback
@c EN
Looks for @var{key} in @var{tree-map}.  If the entry is found,
returns a value corresponding to the key.  Otherwise, returns
@var{fallback} if it is provided, or signals an error.
@c JP
キー@var{key}を@var{tree-map}から探します。見つかれば@var{key}に対応する値を返
します。キーが見つからなかった場合、@var{fallback}が与えられていればそれ
を返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun tree-map-put! tree-map key value
@c EN
Inserts an entry with a @var{key} and corresponding @var{value}
into @var{tree-map}.  If there already exists an entry with a
key which is equivalent (under @var{key=?}), the entry is modified
to have @var{value}.
@c JP
キー@var{key}と対応する値@var{value}を@var{tree-map}に挿入します。もし、@var{key}と、
@var{key=?}における意味で同じキーがすでに存在する場合、キーに対応する値
は新たな値に置き換えられます。
@c COMMON
@end defun

@defun tree-map-delete! tree-map key
@c EN
Deletes an entry with @var{key} from @var{tree-map} if such an entry
exists, and returns @code{#t}.
If @var{tree-map} doesn't have such an entry, @code{#f} is returned.
@c JP
@var{tree-map}からキー@var{key}を持つエントリを削除します。@var{key}を持つエン
トリが実際に存在して削除された場合は@code{#t}を、エントリが存在しなかっ
た場合は@code{#f}を返します。
@c COMMON
@end defun

@defun tree-map-clear! tree-map
@c EN
Removes all entries in @var{tree-map}.
@c JP
@var{tree-map}内の全てのエントリを削除します。
@c COMMON
@end defun

@defun tree-map-update! tree-map key proc :optional fallback
@c EN
A generalized version of @code{tree-map-push!} etc.
It works like the following code, except that searching
for the key is done only once.
@c JP
@code{tree-map-push!}等のより一般的なバージョンです。木の探索が一度
しか行われないことを除いては、基本的に次のように動作します。
@c COMMON
@example
(let ((tmp (proc (tree-map-get @var{tree-map} @var{key} @var{fallback}))))
  (tree-map-put! @var{tree-map} @var{key} tmp)
  tmp)
@end example
@end defun

@defun tree-map-push! tree-map key value
@c EN
Looks for an entry with @var{key} in @var{tree-map}.  If it exists,
the procedure conses @var{value} to the original value and makes
it as a new value.
Otherwise, the procedure creates a new entry for the @var{key}
and makes @code{(list @var{value})} its value.
@c JP
@var{tree-map}中の、キー@var{key}に対応する値に@var{value}をコンスし、
それを@var{key}
に対する新たな値とします。もし@var{key}に対応する値がまだ無ければ、新た
なエントリが作成され、@code{(list @var{value})}がその値となります。
@c COMMON
@end defun

@defun tree-map-pop! tree-map key :optional fallback
@c EN
Looks for an entry with @var{key} in @var{tree-map}.  If it exists
and its value is a pair, then the procedure updates
its value with @code{cdr} of the original value, and returns
@code{car} of the original entry.   If such an entry does not
exist, or has a non-pair value, the procedure doesn't
modify @var{tree-map} and returns @var{fallback} if it is given,
otherwise reports an error.
@c JP
@var{tree-map}中のキー@var{key}に対応する値が存在し、かつペアであった場合
に、そのエントリの値を元の値のcdrで置き換え、元の値のcarを返します。
@var{key}に対応する値が存在しないかペアではなかった場合、@var{tree-map}は
変更されず、@var{fallback}が与えられていればそれが返され、与えられていな
ければエラーが報告されます。
@c COMMON
@end defun

@defun tree-map-min tree-map
@defunx tree-map-max tree-map
@c EN
Returns a pair of a key and its value with the minimum
or maximum key, respectively.   If @var{tree-map} is empty,
@code{#f} is returned.
@c JP
それぞれ、@var{tree-map}に含まれる最小および最大のキーを探索し、その
キーと値のペアを返します。@var{tree-map}が空だった場合は@code{#f}が返されます。
@c COMMON
@end defun

@defun tree-map-pop-min! tree-map
@defunx tree-map-pop-max! tree-map
@c EN
Looks for an entry with minimum or maximum key, respectively,
then deletes the entry from @var{tree-map} and returns 
a pair of the key and its value of the original entry.
If @var{tree-map} is empty, @code{#f} is returned.
@c JP
それぞれ、@var{tree-map}に含まれる最小および最大のキーを探索し、そ
のエントリを@var{tree-map}から削除したうえで、そのキーと値のペアを
返します。@var{tree-map}が空だった場合は@code{#f}が返されます。
@c COMMON
@end defun

@defun tree-map-fold tree-map proc seed
@defunx tree-map-fold-right tree-map proc seed
@c EN
Iterate over elements in @var{tree-map}, applying 
@var{proc} which has a type @code{(key, value, seed) -> seed}.
The difference of @code{tree-map-fold} and @code{tree-map-fold-right}
is the associative order of applying @code{proc},
just like the difference between @code{fold} and @code{fold-right}.
@c JP
@var{tree-map}の各要素に対し、@code{(key, value, seed) -> seed} の型を持つ
@var{proc}を適用してゆきます。
@code{tree-map-fold}と@code{tree-map-fold-right}の違いは
@code{fold}の@code{fold-right}違いと同じ、すなわち
結合の方向にあります。
@c COMMON
@example
tree-map-fold:
  (proc Kn Vn (proc Kn-1 Vn-1 ... (proc K0 V0 seed)))

tree-map-fold-right
  (proc K0 V0 (proc K1 V1 ... (proc Kn Vn seed)))
@end example

@c EN
Some examples:
@c JP
例:
@c COMMON
@example
(define tree (alist->tree-map '((3 . a) (7 . b) (5 . c)) = <))

(tree-map-fold tree list* '()) 
   @result{} (7 b 5 c 3 a)
(tree-map-fold-right tree list* '()) 
   @result{} (3 a 5 c 7 b)
@end example
@end defun

@defun tree-map-map tree-map proc
Applies @var{proc} with each key/value pair in @var{tree-map},
and collect the results into a list and returns it.  The order
of results corresponds to the order of keys---that is, the first element
of the result list is what @var{proc} returns with minimum key and its value,
and the last element of the result list is what @var{proc} returns
with the maximum key and its value.
(Note: Like @code{map}, the order that @var{proc} is actually called
is unspecified; @var{proc} is better to be side-effect free.)
@end defun

@defun tree-map-for-each tree-map proc
Applies @var{proc} with each key/value pair in @var{tree-map},
in the increasing order of the keys.  @var{proc} is called purely
for side effects; the returned values are discarded.
@end defun

@defun tree-map-floor tree-map probe :optional fallback-key fallback-value
@defunx tree-map-ceiling tree-map probe :optional fallback-key fallback-value
@defunx tree-map-predecessor tree-map probe :optional fallback-key fallback-value
@defunx tree-map-successor tree-map probe :optional fallback-key fallback-value
These procedures search the entry which has the closest key
to the given @var{probe}.  If such an entry is found, returns
two values, its key and its value.  Otherwise, returns two values,
@var{fallback-key} and @var{fallback-value}, both defaulted to @code{#f}.

The criteria of ``closest'' differ slightly among these procedures;
@code{tree-map-floor} finds the maximum key which is no greater than
@var{probe}; @code{tree-map-ceiling} finds the minimum key which is 
no less than @var{probe}; @code{tree-map-predecessor} finds the
maximum key which is strictly less than @var{probe};
and @code{tree-map-successor} finds the minimum key which 
is strictly greater than @var{probe}.
@end defun

@defun tree-map-floor-key tree-map probe @var{optional} fallback-key
@defunx tree-map-ceiling-key tree-map probe @var{optional} fallback-key
@defunx tree-map-predecessor-key tree-map probe @var{optional} fallback-key
@defunx tree-map-successor-key tree-map probe @var{optional} fallback-key
Like @code{tree-map-floor} etc., but only returns the key of
the found entry (or @var{fallback-key} if there's no entry which satisfies
the criteria).
@end defun

@defun tree-map-floor-value tree-map probe @var{optional} fallback-value
@defunx tree-map-ceiling-value tree-map probe @var{optional} fallback-value
@defunx tree-map-predecessor-value tree-map probe @var{optional} fallback-value
@defunx tree-map-successor-value tree-map probe @var{optional} fallback-value
Like @code{tree-map-floor} etc., but only returns the value of
the found entry (or @var{fallback-value} if there's no entry which satisfies
the criteria).
@end defun

@defun tree-map-keys tree-map
@defunx tree-map-values tree-map
@c EN
Returns a list of all keys and all values, respectively.
The keys and values are in ascending order of the keys.
@c JP
それぞれ、@var{tree-map}内の全てのキーまたは値をリストにして返しま
す。返されるリストの要素はキーの昇順に並んでいます。
@c COMMON
@end defun

@defun tree-map->alist tree-map
@c EN
Returns a list of pairs of keys and values for all entries.
The pairs are in ascending order of the keys.
@c JP
@var{tree-map}含まれる要素を連想リストにして返します。返される連
想リストのキーは昇順に並んでいます。
@c COMMON
@end defun

@defun alist->tree-map alist key=? key<?
@c EN
Creates a new tree map with @var{key=?} and @var{key<?},
then populates it with @var{alist}, each pair in which are
interpreted as a cons of a key and its value.  Returns the
created tree map.
@c JP
@var{key=?}, @var{key<?} によって新たなtreemapを作成し、
連想リスト@var{alist}に含まれる要素を追加した上で返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Weak pointers, Control features, Treemaps, Core library
@section Weak pointers
@c NODE Weak ポインタ

@c EN
A weak pointer is a reference to an object that doesn't prevent
the object from being garbage-collected.
Gauche provides weak pointers as a @emph{weak vector} object.
A weak vector is like a vector of objects, except each object
can be garbage collected if it is not referenced from objects
other than weak vectors.   If the object is collected, the
entry of the weak vector is replaced for @code{#f.}
@c JP
Weak ポインタとは、それが参照しているオブジェクトがガベージコレクトされることを
許すようなポインタです。
Gaucheは@emph{weak ベクタ}オブジェクトによってweak ポインタの機能を提供します。
Weak ベクタは通常のベクタに似ていますが、要素のオブジェクトがweak ベクタ以外から
参照されていない場合、オブジェクトはガベージコレクトされ、weak ベクタの該当するエントリは
@code{#f}で置き換えられます。
@c COMMON
@example
gosh> (define v (make-weak-vector 1))
v
gosh> (weak-vector-ref v 0)
#f
gosh> (weak-vector-set! v 0 (cons 1 1))
#<undef>
gosh> (weak-vector-ref v 0)
(1 . 1)
gosh> (gc)
#<undef>
gosh> (gc)
#<undef>
gosh> (weak-vector-ref v 0)
#f
@end example

@deftp {Builtin Class} <weak-vector>
@clindex weak-vector
@c EN
The weak vector class.  Inherits @code{<sequence>} and @code{<collection>},
so you can use
@code{gauche.collection} (@xref{Collection framework}) and
@code{gauche.sequence} (@xref{Sequence framework}).
@c JP
Weak ベクタのクラスです。@code{<sequence>}と@code{<collection>}を継承しているので、
@code{gauche.collection} (@ref{Collection framework}参照) と
@code{gauche.sequence} (@ref{Sequence framework}参照) も使えます。
@c COMMON
@example
(coerce-to <weak-vector> '(1 2 3 4))
  @result{} a weak vector with four elements
@end example
@end deftp

@defun make-weak-vector size
@c EN
Creates and returns a weak vector of size @var{size}.
@c JP
大きさ@var{size}のweak ベクタを作成して返します。
@c COMMON
@end defun

@defun weak-vector-length wvec
@c EN
Returns the length of a weak vector @var{wvec}.
@c JP
weak ベクタ @var{wvec}の大きさを返します。
@c COMMON
@end defun

@defun weak-vector-ref wvec k &optioal fallback
@c EN
Returns @var{k}-th element of a weak vector @var{wvec}.

By default, @code{weak-vector-ref} signals an error if @var{k} is
negative, or greater than or equal to the size of @var{wvec}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.

If the element has been garbage collected, this procedure returns
@var{fallback} if it is provided,  @code{#f} otherwise.

With @code{gauche.sequence} module,
you can also use a method @code{ref}.
@c JP
weak ベクタ @var{wvec}の@var{k}番目の要素を返します。

@code{weak-vector-ref}は@var{k}が負の値であったりベクタの長さより
大きかったりした場合はエラーを通知します。但し、省略可能な引数@var{fallback}
が与えられている場合はその値が返されます。

該当する要素が既にガベージコレクトされていた場合、@var{fallback}が
与えられていればそれが、そうでなければ@code{#f}が返されます。

@code{gauche.sequence}モジュールをロードしていれば、
メソッド@code{ref}も同じ目的で使えます。
@c COMMON
@end defun

@defun weak-vector-set! wvec k obj
@c EN
Sets @var{k}-th element of the weak vector @var{wvec} to @var{obj}.
It is an error if @var{k} is negative or greater than or equal to the
size of @var{wec}.
@c JP
weak ベクタ @var{wvec}の@var{k}番目の要素を@var{obj}に変更します。
@var{k}が負数であったりベクタの長さより大きい場合はエラーとなります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Control features, Exceptions, Weak pointers, Core library
@section Control features
@c NODE 制御

@menu
* Procedures::                  
* Applicable objects::          
* Continuation::                
* Multiple values::             
* Delayed evaluation::          
@end menu

@node Procedures, Applicable objects, Control features, Control features
@subsection Procedures
@c NODE 手続き

@deftp {Builtin Class} <procedure>
@clindex procedure
@end deftp

@defun procedure? obj
[R5RS]
@c EN
Returns @code{#t} if @var{obj} is a procedure, @code{#f} otherwise.
@c JP
@var{obj}が手続きなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun apply proc arg1 @dots{} args
[R5RS]
@c EN
Calls a procedure @var{proc} with a list of arguments,
@code{(@var{arg1} @dots{} . @var{args})}.
The last argument @var{args} must be a proper list.
Returns (a) value(s) @var{proc} returns.
@c JP
@code{(@var{arg1} @dots{} . @var{args})}を引数として手続き@var{proc}を呼びます。
最後の引数@var{args}は正規のリストでなければなりません。 @var{proc}が返す
値をそのまま返します。
@c COMMON
@example
(apply list 'a 'b '(c d e)) @result{} (a b c d e)

(apply + 1 2 '(3 4 5))      @result{} 15
@end example
@end defun


@menu
* Universal accessor::          
* Mapping::                     
* Combinators::                 
* Optional argument parsing::   
* Procedure arity::             
@end menu

@node Universal accessor, Mapping, Procedures, Procedures
@subsubsection Universal accessor
@c NODE 万能アクセサ

@defun ~ obj key keys @dots{}
@defunx {(setter ~)} obj key keys @dots{}
The procedure @code{~} can be used to access a part of various
aggregate types.

@example
;; Access to an element of a sequence by index
(~ '(a b c) 0)       @result{} a
(~ '#(a b c) 2)      @result{} c
(~ "abc" 1)          @result{} #\b
(~ '#u8(10 20 30) 1) @result{} 20

;; Access to an element of a collection by key
(~ (hash-table 'eq? '(a . 1) '(b . 2)) 'a)
  @result{} 1

;; Access to a slot of an object by slot name
(~ (sys-localtime (sys-time)) 'hour)
  @result{} 20
@end example

The access can be chained:

@example
(~ '#((a b c) (d e f) (g h i)) 1 2) @result{} f

(~ (hash-table 'eq? '(a . "abc") '(d . "def")) 'a 2)
  @result{} #\c
@end example

You can think @code{~} as left-associative, that is,
@example
(~ x k j) @equiv{} (~ (~ x k) j)
@end example
and so on.

The generalized setter @code{set!} can be used with @code{~} to
replace the specified element.

@example
(define z (vector 'a 'b 'c))
(set! (~ z 1) 'Z)

z @result{} #(a Z c)

(define z (vector (list (vector 'a 'b 'c)
                        (vector 'd 'e 'f)
                        (vector 'g 'h 'i))
                  (list (vector 'a 'b 'c)
                        (vector 'd 'e 'f)
                        (vector 'g 'h 'i))))

z @result{} #((#(a b c) #(d e f) #(g h i))
     (#(a b c) #(d e f) #(g h i)))

(set! (~ z 1 2 0) 'Z)
z @result{}  #((#(a b c) #(d e f) #(g h i))
     (#(a b c) #(d e f) #(Z h i)))
@end example
@end defun

Internally, a call to @code{~} is implemented by a generic 
function @code{ref}.  See @ref{Object system} for more about
generic functions.

@deffn {Generic function} ref object key :optional args @dots{}
@deffnx {Generic function} {(setter ref)} object key value
Many aggregate types defines a specialized method of these
to provide uniform access and mutation.   Meaning of
optional arguments @var{args} of @code{ref} depends
on each specialized method,
but it is common that the first optional argument of @code{ref} 
is a @emph{fallback} value, which is to be returned when
@var{object} doesn't have a meaningful association with @var{key}.

The manual entry of each aggregate type shows the specialized
method and its semantics in detail.
@end deffn

Conceptually, @code{~} can be understood as follows:

@example
(define ~
  (getter-with-setter
   (case-lambda
     [(obj selector) (ref obj selector)]
     [(obj selector . more) (apply ~ (ref obj selector) more)])
   (case-lambda
     [(obj selector val) ((setter ref) obj selector val)]
     [(obj selector selector2 . rest)
      (apply (setter ~) (ref obj selector) selector2 rest)])))
@end example

(Gauche may use some short-cut for optimization, though,
so this code may not reflect the actual implementation.)


@node Mapping, Combinators, Universal accessor, Procedures
@subsubsection Mapping
@c NODE マッピング

@defun map proc list1 list2 @dots{}
[R5RS+]
@c EN
Applies @var{proc} for each element(s) of given list(s),
and returns a list of the results.  R5RS doesn't specify
the application order of @code{map}, but Gauche guarantees
@var{proc} is always applied in order of the list(s).
Gauche's @code{map} also terminates as soon as one of
the list is exhausted.
@c JP
与えられたリストの各要素に対して@var{proc}を適用し、その結果をリストにして
返します。R5RSでは@var{proc}の適用順序が定められていませんが、Gaucheでは
常に@var{proc}はリスト内の順番で呼ばれます。
複数のリストが与えられた場合、最も短いリストが終了した時点で@var{proc}の適用を
打ち切ります。
@c COMMON

@example
(map car '((a b) (c d) (e f))) @result{} (a c e)

(map cons '(a b c) '(d e f))
  @result{} ((a . d) (b . e) (c . f))
@end example

@c EN
Note that the @code{gauche.collection} module (@xref{Collection framework})
extends @code{map} to work on any type of collection.
@c JP
@code{gauche.collection}モジュール(@ref{Collection framework}参照)
を使うと、@code{map}がリスト以外のコレクション型に対しても動作するようになります。
@c COMMON
@end defun

@defun map* proc tail-proc list1 list2 @dots{}
@c EN
Like @code{map}, except that @var{tail-proc} is applied to the @code{cdr}
of the last pair in the argument(s) to get the @code{cdr} of
the last pair of the result list.  This procedure allows improper
list to appear in the arguments.   If a single list is given,
@var{tail-proc} always receives a non-pair object.
@c JP
@code{map}とほぼ同じですが、引数の最後のペアの@code{cdr}に@var{tail-proc}が
適用され、その返り値が結果のリストの最後のペアの@code{cdr}になります。
この手続きは正規でないリストを引数に取ることができます。
引数のリストがひとつだけの場合、@var{tail-proc}の引数は必ずペアでないオブジェクトです。
@c COMMON

@example
(map* - / '(1 2 3 . 4)) @result{} (-1 -2 -3 . 1/4)

(define (proper lis)
  (map* values
        (lambda (p) (if (null? p) '() (list p)))
        lis))

(proper '(1 2 3))     @result{} (1 2 3)
(proper '(1 2 3 . 4)) @result{} (1 2 3 4)
@end example

@c EN
If more than one list are given, the shortest one determines
how @var{tail-proc} is called.  When @code{map*} reaches the
last pair of the shortest list, @var{tail-proc} is called with
cdrs of the current pairs.
@c JP
二つ以上のリストが与えられた場合は、最も短いリストが@var{tail-proc}の呼び出しを
決めます。@code{map*}が最も短いリストの最後のペアに達した時点で、
その時のそれぞれのペアのcdrが@var{tail-proc}へと渡されます。
@c COMMON

@example
(map* + vector '(1 2 3 4) '(1 2 . 3))
  @result{} (3 6 . #((3 4) 3))
@end example

@c EN
Note: The name @code{map*} is along the line of
@code{list*}/@code{cons*} that can produce improper list
(@xref{List constructors}, @xref{SRFI-1 List constructors}).
@c JP
註: @code{map*}という名前は、正規でないリストを作り得る@code{list*}/@code{cons*}からの
連想でつけられました
(@ref{List constructors}、@ref{SRFI-1 List constructors}参照)。
@c COMMON
@end defun

@defun for-each proc list1 list2 @dots{}
[R5RS]
@c EN
Applies @var{proc} for each element(s) of given list(s) in order.
The results of @var{proc} are discarded.  The return value of
@code{for-each} is undefined.  When more than one list is given,
@code{for-each} terminates as soon as one of the list is exhausted.
@c JP
手続き@var{proc}をリストの各エレメントに対して順に適用します。
@var{proc}の結果は捨てられます。@code{for-each}の戻り値は定義されていません。
複数のリストが与えられた場合、一番短いリストが終了した時点で@code{for-each}は終了します。
@c COMMON

@c EN
Note that the @code{gauche.collection} module (@xref{Collection framework})
extends @code{for-each} to work on any type of collection.
@c JP
@code{gauche.collection}モジュール(@ref{Collection framework}参照)
を使うと、@code{for-each}がリスト以外のコレクション型に対しても動作するようになります。
@c COMMON
@end defun


@node Combinators, Optional argument parsing, Mapping, Procedures
@subsubsection Combinators
@c NODE コンビネータ

@c EN
Gauche has some primitive procedures that allows combinatory programming.
@c JP
Gaucheには、combinatory programmingに使えるいくつかの基本手続きがあります。
@c COMMON

@defun pa$ proc arg @dots{}
@c EN
Partial application.  Returns a procedure, and when it is
called with arguments @var{m} @dots{}, it is equivalent to call
@code{(proc arg @dots{} m @dots{})}.
@c JP
部分適用。手続きを返します。その手続きが引数@var{m} @dots{}を伴って
呼ばれた場合、それは@code{(proc arg @dots{} m @dots{})}と等価になります。
@c COMMON

@example
(define add3 (pa$ + 3))
(add3 4) @result{} 7

(map (pa$ * 2) '(1 2 3)) @result{} (2 4 6)
@end example

@c EN
Macros @code{cut} and @code{cute} defined in SRFI-26 provide
a similar abstraction, with a bit more flexible but less compact
notation.  @xref{Making Procedures}.
@c JP
SRFI-26で定義されているマクロ@code{cut}と@code{cute}も似たような抽象化の
方法を提供しますが、@code{pa$}より多少柔軟性が高く、その分やや冗長です。
@ref{Making Procedures}を参照して下さい。
@c COMMON
@end defun

@defun apply$ proc
@defunx map$ proc
@defunx for-each$ proc
@c EN
Partial application versions of @code{apply}, @code{map} and @code{for-each}.
@c JP
@code{apply}, @code{map}と@code{for-each}の部分適用版です。
@c COMMON

@example
(define map2* (map$ (pa$ * 2)))
(map2* '(1 2 3)) @result{} (2 4 6)
@end example

@end defun

@defun count$ pred
@defunx fold$ kons :optional knil
@defunx fold-right$ kons :optional knil
@defunx reduce$ f :optional ridentity
@defunx reduce-right$ f :optional ridentity
@defunx filter$ pred
@defunx remove$ pred
@defunx partition$ pred
@defunx member$ item
@defunx find$ pred
@defunx find-tail$ pred
@defunx any$ pred
@defunx every$ pred
@defunx delete$ pred
@defunx assoc$ item
@c EN
Partial application versions of some srfi-1 procedures
(@xref{List library}).
@c JP
SRFI-1(@ref{List library}参照)の手続に対応する部分適用版手続。
@c COMMON
@end defun

@defun .$ f @dots{}
@defunx compose f @dots{}
@c EN
Combine procedures.  All arguments must be procedures.
When two procedures are given, @code{(.$ f g)} is equivalent to
the following code:
@c JP
複数の手続きを結合します。引数は全て手続きでなければなりません。
2つの引数が渡された時、@code{(.$ f g)}は次の式と等価です。
@c COMMON
@example
(lambda args (call-with-values (lambda () (apply g args)) f))
@end example

@c EN
When more than two arguments are passed, they are composed
as follows:
@c JP
2つ以上の引数が渡された場合は、次のように結合されます。
@c COMMON
@example
(.$ f g h ...) @equiv{} (.$ (.$ f g) h ...)
@end example

@c EN
Some examples:
@c JP
いくつか例を示します。
@c COMMON

@example
(define not-zero? (.$ not zero?))
(not-zero? 3) @result{} #t
(not-zero? 0) @result{} #f

(define dot-product (.$ (apply$ +) (map$ *)))
(dot-product '(1 2 3) '(4 5 6)) @result{} 32
@end example

@c EN
A couple of edge cases: if only one argument is given, the argument
itself is returned.  If no arguments are given, the procedure @code{values} 
is returned.
@c JP
境界のケース：ひとつだけ引数が渡された場合は、その引数がそのまま返されます。
引数が全く渡されなかった場合は手続き@var{values}が返されます。
@c COMMON

@c EN
Note: The name @code{.$} comes from the fact that @code{.} is 
commonly used for function composition in literatures and some
programming languages, and that Gauche uses suffix @code{$} to
indicate combinators.   However, since it is not a valid R5RS/R6RS
identifier, portable programs may want to use the alias @code{compose},
with which you can easily add a portable definition using @code{srfi-0},
for example.
@c JP
註: @code{.$}という名前は、文献やいくつかの他のプログラミング言語で
@code{.}が関数合成によく使われること、そしてGaucheではコンビネータの末尾に
@code{$}をつける習慣があることから来ています。ただ、これはR5RS/R6RSの
範囲内では有効な識別子でないので、ポータビリティを考えるプログラムは
別名の@code{compose}を使った方が良いでしょう。そうすれば@code{srfi-0}などを
使って容易に移植が可能です。
@c COMMON
@end defun

@defun complement pred
@c EN
Returns a procedure that reverses the meaning of the predicate @var{pred}.
That is, for the arguments for which @var{pred} returns true return
false, and vice versa.
@c JP
述語@var{pred}の意味を逆にした手続きを返します。すなわち、@var{pred}が真を
返すような引数にたいして偽を返す、またその逆も同様であるような手続きです。
@c COMMON

@example
(map (complement even?) '(1 2 3)) @result{} '(#t #f #t)
(map (complement =) '(1 2 3) '(1 1 3)) @result{} '(#f #t #f)
((complement (lambda () #f))) @result{} #t
@end example
@end defun

@defun any-pred pred @dots{}
@c EN
Returns a procedure which applies given argument(s) to
each predicate @var{pred}.  If any @var{pred} returns
a non-@code{#f} value, the value is returned.  If all the @var{pred}s
return @code{#f}, @code{#f} is returned.
@c JP
与えられた引数をそれぞれ述語@var{pred}に適用する手続きを返します。
いずれかの@var{pred}が@code{#f}でない値を返す場合、その値を返します。
全ての@var{pred}が@code{#f}を返す場合、@code{#f}を返します。
@c COMMON

@example
(define string-or-symbol? (any-pred string? symbol?))
(string-or-symbol? "abc") @result{} #t
(string-or-symbol? 'abc)  @result{} #t
(string-or-symbol? 3)     @result{} #f

(define <> (any-pred < >))
(<> 3 4) @result{} #t
(<> 3 3) @result{} #f

((any-pred (cut memq <> '(a b c))
           (cut memq <> '(1 2 3)))
 'b)  @result{} '(b c)
@end example
@end defun

@defun every-pred pred @dots{}
@c EN
Returns a procedure which applies given argument(s) to
each predicate @var{pred}.  If every @var{pred} returns
a non-@code{#f} value, the value returned by the last @var{pred}
is returned.  If any @var{pred} returns @code{#f}, @code{every-pred}
returns @code{#f} without calling further @var{pred}s.
@c JP
与えられた引数をそれぞれ述語@var{pred}に適用する手続きを返します。
全ての@var{pred}が@code{#f}でない値を返す場合、戻り値は最後の
@var{pred}の戻り値になります。いずれかの@var{pred}が@code{#f}を
返す場合、@code{every-pred}はそれ以降の@var{pred}を呼び出さずに
@code{#f}を返します。
@c COMMON

@example
((every-pred odd? positive?) 3)  @result{} #t
((every-pred odd? positive?) 4)  @result{} #f
((every-pred odd? positive?) -3) @result{} #f

(define safe-length (every-pred list? length))
(safe-length '(a b c))  @result{} 3
(safe-length "aaa")     @result{} #f
@end example
@end defun

@node Optional argument parsing, Procedure arity, Combinators, Procedures
@subsubsection Optional argument parsing
@c NODE 省略可能引数のパージング

@c EN
Gauche supports optional and keyword arguments in extended
lambda syntax (@xref{Making Procedures}).  However, you can
also use the following macros to parse optional and keyword
arguments, without relying Gauche's extension.
@c JP
Gaucheは省略可能引数やキーワード引数を拡張lambda構文で
サポートしています (@ref{Making Procedures}参照)。
けれども、Gauche拡張に頼らずに、以下のマクロを使って独自にこれらの引数を
パーズすることもできます。
@c COMMON

@example
(define (foo a b :optional (c #f) (d 'none)) 
  body ...)

@c EN
;; is roughly equivalent to ...
@c JP
;; は次の式とだいたい同じ:
@c COMMON

(define (foo a b . args)
  (let-optionals* args ((c #f) (d 'none))
    body ...))
@end example

@c EN
Explicitly parsing the extended arguments may be useful for
portable programs, since it is rather straightforward to
implement those macros rather than extend lambda syntax.

Those macros can also be useful to factor out common
argument parsing routines.
@c JP
明示的に拡張引数をパーズする方法は、ポータブルなコードを書く時に
役に立つでしょう。以下のマクロを実装するのは、lambdaの構文を
拡張するより簡単だからです。

また、共通する拡張引数の処理ルーチンを括り出す場合にもこれらのマクロは有用です。
@c COMMON

@defmac let-optionals* restargs (var-spec @dots{}) body @dots{}
@defmacx let-optionals* restargs (var-spec @dots{} . restvar) body @dots{}
@c EN
Given a list of values @var{restargs}, binds variables according
to @var{var-spec}, then evaluates @var{body}.
@c JP
与えられた値のリスト@var{restargs}を、@var{var-spec}にしたがって
変数に束縛し、@var{body}を評価します。
@c COMMON

@c EN
@var{Var-spec} can be either a symbol, or a list of two elements
and its car is a symbol.  The symbol is the bound variable name.
The values in @var{restargs} are bound to the symbol in order.
If there are not as many values in @var{restargs} as @var{var-spec},
the rest of @var{symbol}s are bound to the default values, determined
as follows: If @var{var-spec} is just a symbol, the default value is
undefined.  If @var{var-spec} is a list, the default value is
the result of evaluation of the second element of the list.
In the latter case the second
element is only evaluated when there are not enough arguments.
The binding proceeds in the order of @var{var-spec}, so the second
element may refer to the bindings of previous @var{var-spec}.
@c JP
@var{var-spec}はシンボルか、そのcarがシンボルである2要素のリストの
いずれかです。シンボルは束縛された変数名です。
@var{restargs}にある値は、順番にシンボルに束縛されます。
@var{restargs}に@var{var-spec}に示される数の値がない場合は、
残りの@var{symbol}は以下に従ってデフォルト値が束縛されます。
@var{var-spec}が単なるシンボルなら、デフォルト値は未定義です。
@var{var-spec}がリストなら、デフォルト値はリストの2番目の要素を
評価した結果です。後者の場合、2番目の要素は十分な引数がない場合にのみ
評価されます。
束縛は@var{var-spec}の順番にしたがって行われるので、2番目の要素は
以前の@var{var-spec}のバインディングを参照するかも知れません。
@c COMMON

@c EN
In the second form, @var{restvar} must be a symbol and bound to
the list of values whatever left from @var{restargs} after binding
to @var{var-spec}.
@c JP
2番目のフォームでは、@var{restvar}はシンボルでなければならず、
@var{var-spec}に束縛された後、@var{restargs}に残っている値のリストに
束縛されます。
@c COMMON

@c EN
It is not an error if @var{restarg} has more values than @var{var-spec}s.
The extra values are simply ignored in the first form.
@c JP
@var{restarg}が@var{var-spec}よりも多い値を持っていてもエラーでは
ありません。最初のフォームでは、余分な値は単に無視されます。
@c COMMON

@example
(define (proc x . args)
  (let-optionals* args ((a 'a)
                        (b 'b)
                        (c 'c))
    (list x a b c)))

(proc 0)         @result{} (0 a b c)
(proc 0 1)       @result{} (0 1 b c)
(proc 0 1 2)     @result{} (0 1 2 c)
(proc 0 1 2 3)   @result{} (0 1 2 3)

(define (proc2 . args)
  (let-optionals* args ((a 'a) . b)
    (list a b)))

(proc2)          @result{} (a ())
(proc2 0)        @result{} (0 ())
(proc2 0 1)      @result{} (0 (1))
(proc2 0 1 2)    @result{} (0 (1 2))

(define (proc3 . args)
  (let-optionals* args ((a 0)
                        (b (+ a 1))
                        (c (+ b 1)))
    (list a b c)))

(proc3)          @result{} (0 1 2)
(proc3 8)        @result{} (8 9 10)
(proc3 8 2)      @result{} (8 2 3)
(proc3 8 2 -1)   @result{} (8 2 -1)
@end example
@end defmac

@defmac get-optional restargs default
@c EN
This is a short version of @var{let-optionals*} where you have only
one optional argument.  Given the optional argument list @var{restargs},
this macro returns the value of optional argument if one is given,
or the result of @var{default} otherwise.  @var{Default} is not
evaluated unless @var{restargs} is an empty list.
@c JP
これは@var{let-optionals*}の短いバージョンで、オプショナル引数が
1つしかないときに使います。オプショナル引数のリストとして@var{restargs}が
与えらると、このマクロはオプショナル引数が与えられていればその値を返し、
そうでなければ@var{default}の結果を返します。@var{default}は@var{restargs}が
空リストでなければ評価されません。
@c COMMON

@example
(define (proc x . maybe-opt)
  (let ((option (get-optional maybe-opt #f)))
    (list x option)))

(proc 0)         @result{} (0 #f)
(proc 0 1)       @result{} (0 1)
@end example
@end defmac

@defmac let-keywords restarg (var-spec @dots{}) body @dots{}
@defmacx let-keywords restarg (var-spec @dots{} . restvar) body @dots{}
@c EN
This macro is for keyword arguments.  @var{Var-spec} can be
one of the following forms:
@c JP
このマクロはキーワード引数のためのものです。@var{var-spec}は
以下のフォームのうちのいずれかです。
@c COMMON

@table @code
@item (@var{symbol} @var{expr})
@c EN
If the @var{restrag} contains keyword which has the same name as @var{symbol},
binds @var{symbol} to the corresponding value.  If such a keyword doesn't
appear in @var{restarg}, binds @var{symbol} to the result of @var{expr}.
@c JP
@var{restarg}が@var{symbol}と同じ名前を持つキーワードを含んでいる場合、
@var{symbol}を対応する値に束縛します。そのようなキーワードが@var{restarg}に
ない場合は、@var{symbol}を@var{expr}の結果に束縛します。
@c COMMON
@item (@var{symbol} @var{keyword} @var{expr})
@c EN
If the @var{restarg} contains keyword @var{keyword},
binds @var{symbol} to the corresponding value.  If such a keyword doesn't
appear in @var{restarg}, binds @var{symbol} to the result of @var{expr}.
@c JP
@var{restarg}がキーワード@var{keyword}を含む場合、
@var{symbol}を対応する値に束縛します。そのようなキーワードが@var{restarg}に
ない場合、@var{symbol}を@var{expr}の結果に束縛します。
@c COMMON
@end table

@c EN
The default value @var{expr} is only evaluated when the keyword is
not given to the @var{restarg}.
@c JP
デフォルト値@var{expr}は、@var{restarg}にキーワードが与えられてなかった
場合にのみ評価されます。
@c COMMON

@c EN
If you use the first form, @code{let-keyword} throws an error
when @code{restarg} contains a keyword argument that is not listed
in @var{var-spec}s.
When you want to allow keyword arguments other than listed in
@var{var-spec}s, use the second form.

In the second form, @var{restvar} must be either a symbol or @code{#f}.
If it is a symbol, it is bound to a list of keyword arguments
that are not processed by @var{var-spec}s.  If it is @code{#f},
such keyword arguments are just ignored.
@c JP
1番目のフォームでは、@var{var-spec}にないキーワード引数が@var{restarg}に
現れるとエラーとなります。
他のキーワード引数を許したい場合は次の2番目のフォームを使ってください。

2番目のフォームでは、@var{restvar}はシンボルか@code{#f}でなければなりません。
シンボルのときは、@var{var-spec}に束縛されなかった@var{restargs}のキーワード
リストが@var{restvar}に束縛されます。@code{#f}のときは、それらの@var{restargs}
のキーワードは単に無視されます。
@c COMMON

@example
(define (proc x . options)
  (let-keywords options ((a 'a)
                         (b :beta 'b)
                         (c 'c)
                         . rest)
    (list x a b c rest)))

(proc 0)         @result{} (0 a b c ())
(proc 0 :a 1)    @result{} (0 1 b c ())
(proc 0 :beta 1) @result{} (0 a 1 c ())
(proc 0 :beta 1 :c 3 :unknown 4) @result{} (0 a 1 3 (:unknown 4))
@end example
@end defmac

@defmac let-keywords* restarg (var-spec @dots{}) body @dots{}
@defmacx let-keywords* restarg (var-spec @dots{} . restvar) body @dots{}
@c EN
Like @code{let-keywords}, but the binding is done in the order of
@var{var-spec}s.  So each @var{expr} can refer to the variables bound by
preceding @var{var-spec}s.
@c JP
このマクロは@code{let-keywords}とほぼ同じですが、束縛が@var{var-spec}での
順番に行われるところが異なります。@var{expr}は以前の@var{var-spec}により
束縛された変数を参照できます。
@c COMMON
@end defmac

@node Procedure arity,  , Optional argument parsing, Procedures
@subsubsection Procedure arity
@c NODE 手続きのアリティ

@c EN
Interface to query procedure's arity.
The API is taken from MzScheme (PLT Scheme).
@c JP
手続きのアリティを問い合わせるインターフェースです。
APIは、MzScheme (PLT Scheme)を参考にしました。
@c COMMON

@defun arity @var{proc}
@c EN
Given procedure @var{proc},
returns an integer, an @emph{arity-at-least} object, or
a list of integer(s) and @emph{arity-at-least} objects.
@c JP
手続き@var{proc}を与え、整数、@emph{arity-at-least}オブジェクト、
整数と@emph{arity-at-least}オブジェクトからなるリストのいずれかを
返します。
@c COMMON

@c EN
An integer result indicates @var{proc} takes exactly that number
of arguments.  An @emph{arity-at-least} indicates @var{proc} takes
at least @code{(arity-at-least-value @emph{arity-at-least})}
arguments.   The list indicates there are multiple procedures
with different arities.
@c JP
整数の戻り値は、@var{proc}が正確にその数の引数を取ることを表します。
@emph{arity-at-least}は、@var{proc}が最低でも
引数@code{(arity-at-least-value @emph{arity-at-least})}を取ることを
表します。リストは、異なるアリティを持つ複数の手続きがあることを
表します。
@c COMMON

@c EN
Since one can add methods to an existing procedure or generic function
at any moment in Gauche, the value returned by @code{arity} only
indicates the current state of the procedure.  It will change
if new method is added to the procedure/generic-function.
@c JP
Gaucheではいつでも、既存の手続きやジェネリック関数にメソッドを追加
できるので、@code{arity}が返す値はその手続きの現在の状態を示すに
過ぎません。その手続きやジェネリック関数に新しいメソッドが追加
されると、それも変更されます。
@c COMMON

@example
(arity cons) @result{} 2
(arity list) @result{} #<arity-at-least 0>
(arity make) @result{} (#<arity-at-least 1>)
@end example
@end defun

@defun arity-at-least? @var{obj}
@c EN
Returns true if @var{obj} is an arity-at-least object.
@c JP
@var{obj}がarity-at-leastオブジェクトなら、真を返します。
@c COMMON
@end defun

@defun arity-at-least-value @var{arity-at-least}
@c EN
Returns the number of required arguments the arity-at-least object
indicates.
@c JP
arity-at-leastオブジェクトが表す必須引数の数を返します。
@c COMMON
@end defun

@defun procedure-arity-includes? @var{proc} @var{k}
@c EN
If a procedure @var{proc} can take @var{k} arguments, returns @code{#t}.
Otherwise returns @code{#f}.
@c JP
手続き@var{proc}が引数@var{k}を取れる場合、@code{#t}を返します。
そうでなければ@code{#f}を返します。
@c COMMON
@end defun


@node Applicable objects, Continuation, Procedures, Control features
@subsection Applicable objects
@c NODE 適用可能なオブジェクト

@c EN
Gauche has a special hook to make an arbitrary object @emph{applicable}.
@c JP
Gaucheでは、特別な組み込みの機構によって任意のオブジェクトを
「適用可能」にすることができます。
@c COMMON

@deffn {Generic Function} object-apply @var{object} @var{arg} @dots{}
@c EN
If an object that is neither a procedure nor a generic function
is applied to some arguments, 
the object and the arguments are passed to a generic function
@code{object-apply}.

This can be explained better by examples.
@c JP
手続きでもジェネリックファンクションでもないオブジェクトが何らかの引数に
適用されたとき、そのオブジェクトと引数がジェネリックファンクション@code{object-apply}
に渡されます。

この機能は、具体的な例を挙げた方が説明し易いでしょう。
@c COMMON
@end deffn

@c EN
For example, suppose you try to evaluate the
following expression:
@c JP
例えば、次のような式を評価しようとしたとします。
@c COMMON

@example
("abcde" 2)
@end example

@c EN
The operator evaluates to a string, which is neither a procedure
nor a generic function.  So Gauche interprets the expression
as if it were like this:
@c JP
オペレータは文字列に評価されますから、手続きでもジェネリックファンクションでも
ありません。そこで、Gaucheはこの式を、あたかも次のような式が与えられた
かのように解釈します。
@c COMMON

@example
(object-apply "abcde" 2)
@end example

@c EN
Gauche doesn't define a method of @code{object-apply} that takes
@code{<string>} and @code{<integer>} by default, so this signals an error.
However, if you define such a method:
@c JP
デフォルトでは、@code{<string>}と@code{<integer>}を引数とする
@code{object-apply}のメソッドは定義されていないので、
この式はエラーになります。しかし、次のようなメソッドを定義すると：
@c COMMON

@example
(define-method object-apply ((s <string>) (i <integer>))
  (string-ref s i))
@end example

@c EN
Then the first expression works as if a string is @emph{applied} on
the integer:
@c JP
最初の式はまるで文字列が整数に適用されたかのように動作します。
@c COMMON

@example
("abcde" 2) @result{} #\c
@end example

@c EN
This mechanism works on almost all occasions where a procedure is allowed.
@c JP
このメカニズムは手続きが許されるほとんどの箇所で使うことができます。
@c COMMON

@example
(apply "abcde" '(1))   @result{} (#\b)
(map "abcde" '(3 2 1)) @result{} (#\d #\c #\b)
@end example

@c EN
Among Gauche built-in objects, @code{<regexp>} object and
@code{<regmatch>} object have @code{object-apply} defined.
@xref{Regular expressions}.
@c JP
Gauche組み込みオブジェクトのうち、@code{<regexp>}オブジェクトと
@code{<regmatch>}オブジェクトに対しては@code{object-apply}メソッドが定義されて
います。@ref{Regular expressions}を参照して下さい。
@c COMMON

@deffn {Generic Function} {(setter object-apply)} @var{object} @var{arg} @dots{} @var{value}
@c EN
If a form of applying an applicable object appears in the first position
of @code{set!} form, this method is called, that is:
@c JP
適用可能オブジェクトを適用するフォームが@code{set!}フォームの第一ポジションに
現れた場合、そのフォームは下に示すように展開され、このメソッドが呼ばれます。
@c COMMON
@example
(set! (@var{object} @var{arg} @dots{}) @var{value})
 @result{} ((setter object-apply) @var{object} @var{arg} @dots{} @var{value})
@end example
@end deffn




@node Continuation, Multiple values, Applicable objects, Control features
@subsection Continuation
@c NODE 継続


@defun call-with-current-continuation proc
@defunx call/cc proc
[R5RS]
@c EN
Encapsulates the current continuation to a procedure
(``continuation procedure''), and calls @var{proc} with it.
When @var{proc} returns, its value becomes @code{call/cc}'s value.
When the continuation procedure is invoked with zero or more arguments
somewhere, the further calculation is abandoned and @code{call/cc} returns
with the arguments given to the continuation procedure.
@c JP
現在の継続を手続き (継続手続き) にパッケージ化して、それを引数として
@var{proc}を呼び出します。@var{proc}が戻ったら、その返り値が@code{call/cc}の
値となります。作成された継続手続きがどこかで0個または複数個の引数を伴って呼ばれたら、
あたかも@code{call/cc}から戻ったかのように実行が継続されます。その場合、
@code{call/cc}は、継続手続きに与えられた引数を複数の値として返します。  
@c COMMON

@c EN
First class continuation is one of the most distinct feature of Scheme, but
this margin is too small to contain explanation.
Please consult to the appropriate documents.
@c JP
ファーストクラスの継続はSchemeの最も特徴的な機能のひとつですが、それを
十分に説明するにはこの本の余白は狭すぎます。適切なドキュメントを参照してください。
@c COMMON

@c EN
There's a nontrivial interaction between C language runtime and
Scheme continuation.   Suppose the following scenario:
@c JP
Schemeの継続とC言語の実行環境との間に、ちょっとわかりずらい干渉が生じることがあります。
次のシナリオを考えます。
@c COMMON

@enumerate
@item
@c EN
An application's C runtime calls back a Scheme routine.  For example,
GUI framework calls back a draw routine written in Scheme.
@c JP
アプリケーションのCランタイムがSchemeで書かれた手続きをコールバックします。
例えば、GUIフレームワークがSchemeで書かれた描画ルーチンを呼ぶ、というようなケースを考えてください。
@c COMMON
@item
@c EN
A continuation is captured in the Scheme routine.
@c JP
そのSchemeルーチンで継続が捕捉される。
@c COMMON
@item
@c EN
The Scheme routine returns to the C runtime.
@c JP
Schemeルーチンが終了してCランタイムに制御を戻す。
@c COMMON
@item
@c EN
The continuation captured in 2 is invoked.
@c JP
2で捕捉した継続が起動される。
@c COMMON
@end enumerate

@c EN
It is no problem to invoke the continuation, but if the control
is about to return to the Scheme routine to the C runtime (that is,
to execute step 3 again), an error is signalled as follows.
@c JP
継続を起動すること自体には問題は無いのですが、
制御がSchemeからCへと再び戻ろうとすると (つまり、step 3が再び実行されようとすると)
次のようなエラーが投げられます。
@c COMMON

@example
*** ERROR: attempt to return from a ghost continuation.
@end example

@c EN
This is because C routines don't expect the calling function to return 
more than once.  The C stack frame on which the Scheme callbak was 
originally called
is likely to be deallocated or modified at the time the continuation
is invoked.

If you think of a continuation as a chain of control
frames, growing from root towards upward,
you can imagine that, once a control returns to the C world, the chain is
cut at the boundary.  You can still execute such rootless
continuations, but you have to move the control away from it before it tries
to return to its root that no longer exists.
You can call another continuation, or raise an exception, for example.
@c JP
これは、Cの世界では関数が1回より多く戻ってくることを想定していないからです。
最初にSchemeのコールバックが呼ばれた時のCのスタックフレームは、
継続が再び呼ばれた時には状態が変わっているか、捨てられてしまっているでしょう。

継続を、根から上へ向かって成長する制御フレームの連鎖のようにイメージした場合、
Cの世界へ戻った時点でその連鎖が断ち切られる、と考えることができます。
そのような根無しの継続も実行することはできますが、既に失った根に戻る前に
別の箇所へと制御を移さねばなりません。他の箇所で捕まえた継続を呼んだり、
例外を投げるといったことが考えられます。
@c COMMON

@c EN
Using partial continuations (or delimited continuations) is another
way to avoid such complications.
@xref{Partial continuations}.
@c JP
部分継続(限定継続)を使うのも手です。
@ref{Partial continuations}を参照してください。
@c COMMON
@end defun

@defmac let/cc var body @dots{}
@c EN
This macro expands to :
@c JP
このマクロは次のように展開されます :
@c COMMON
@code{(call/cc (lambda (@var{var}) @var{body} @dots{}))}.
@c EN
The API is taken from PLT Scheme.
@c JP
APIはPLT Schemeから取りました。
@c COMMON
@end defmac


@defun dynamic-wind before thunk after
[R5RS]
@c EN
@var{Before}, @var{thunk} and @var{after} are all procedures with
no arguments.
In normal situation, @code{dynamic-wind} calls @var{before}, then @var{thunk},
then @var{after}, then returns whatever value(s) @var{thunk} returned.

If a control flow goes out from @var{thunk} by invoking a continuation
captured outside of the dynamic scope of @code{dynamic-wind}
(for example, an error is signalled in @var{thunk}),
@var{after} is called.  

If a control flow goes into @var{thunk} by invoking a continuation
captured inside @var{thunk} from outside of the dynamic
scope of @code{dynamic-wind}, @var{before} is called.
@c JP
@var{before}、@var{thunk}および@var{after} は引数を取らない手続きです。
@code{dynamic-wind}はまず@var{before}を呼び出し、続いて@var{thunk}を呼び出し、
続いて@var{after}を呼び出します。そして@var{thunk}が返した値を返します。

もし@code{dynamic-wind}のダイナミックスコープの外で捕捉された継続が
@var{thunk}の中で呼ばれることにより制御が@var{thunk}から飛び出した場合、
(@var{thunk}の中でエラーが起こった場合などが考えられます)、
@var{after}が呼ばれます。

もし、@var{thunk}の中で捕捉された継続が@var{dynamic-wind}のダイナミックスコープの
外で呼ばれることにより制御が@var{thunk}の中へ飛び込んだ場合、
@var{before}が呼ばれます。
@c COMMON
@example
(letrec ((paths '())
         (c #f)
         (add (lambda (s) (push! paths s))))
  (dynamic-wind
   (lambda () (add 'connect))
   (lambda ()
     (add (call/cc (lambda (c0) (set! c c0) 'talk1))))
   (lambda () (add 'disconnect)))
  (if (< (length paths) 4)
      (c 'talk2)
      (reverse paths)))
 @result{} (connect talk1 disconnect connect talk2 disconnect)
@end example
@end defun


@node Multiple values, Delayed evaluation, Continuation, Control features
@subsection Multiple values
@c NODE 多値

@defun values obj @dots{}
[R5RS]
@c EN
Returns @var{obj} @dots{} as multiple values.
Caller can capture multiple values by a built-in syntax
@code{receive} (@ref{Binding constructs}), or the R5Rs procedure
@code{call-with-values} described below.
See also @ref{Let-values}.
@c JP
@var{obj} @dots{} を多値として返します。
呼び出し側は、組み込み構文の @code{receive} (@ref{Binding constructs}参照)か、
下に説明するR5RSの手続き@code{call-with-values}を使って多値を受け取ることが
できます。
@ref{Let-values}も参照してください。
@c COMMON
@example
(values 1 2) @result{} 1 @r{and} 2
@end example
@end defun

@defun call-with-values producer consumer
[R5RS]
@c EN
Call a procedure @var{producer} with no argument.
Then applies a procedure @var{consumer} on the
value(s) @var{producer} returned.  Returns the value(s) @var{consumer}
returns.
@c JP
手続き@var{producer}を引数無しで呼びます。そして、それが返した値
を引数として@var{consumer}を呼びます。@var{consumer}が返す値を
返します。
@c COMMON
@example
(call-with-values (lambda () (values 1 2)) cons)
  @result{} (1 . 2)
@end example
@end defun

@defmac values-ref mv-expr k
@c EN
Returns @var{k}-th value of what @var{mv-expr} returns.
Conceptually, it is the same as the following code.
@c JP
@var{mv-expr}が返す多値の@var{k}-番目の値を返します。概念としては、
以下のコードと同じです。
@c COMMON
@example
(call-with-values (lambda () mv-expr) (lambda r (list-ref r k)))
@end example
@c EN
This macro uses shortcuts for the typical cases like @var{k} is zero.

Similar to Common Lisp's @code{nth-value}, but the argument order
is flipped to match other Scheme's @code{*-ref} procedures.
@c JP
このマクロは k がゼロであるような典型的な場合にはより単純な形へと
展開されます。

Common Lisp の @code{nth-value} に似ていますが、引数の順が逆になっています。
Scheme の他の@code{*-ref} 手続きと合わせるためです。
@c COMMON
@end defmac

@node Delayed evaluation,  , Multiple values, Control features
@subsection  Delayed evaluation
@c NODE 遅延評価

@c EN
Gauche provides an extended lazy evaluation mechanism according
to srfi-45.  Instead of two primitives as R5RS, we have three:
@code{lazy}, @code{delay}, and @code{force}.
@c JP
GaucheではSRFI-45による拡張された遅延評価機構を用意しています。R5RSの
ふたつのプリミティブではなく、@code{lazy}、@code{delay}、@code{force}
の3つのプリミティブがあります。
@c COMMON

@c EN
It is found that the traditional mechanism that uses only
@code{delay} and @code{force} didn't mix well with tail-recursive
algorithms: It required unbound memory, despite that the
body of the algorithm could be expressed in iterative manner.
For the detailed explanation please look at the srfi-45 document.
Here we explain how to use those primitives.
@c JP
伝統的な@code{delay}および@code{force}だけを使ったのでは末尾再帰的なア
ルゴリズムとの相性がよくないことがわかっています。末尾再帰的なアルゴリ
ズムの本体が反復的に表現できるにもかかわらず、メモリを際限なく要求して
しまいます。詳しい説明はSRFI-45のドキュメントを見てください。ここでは3
つのプリミティブの使い方を説明します。
@c COMMON

@defspec lazy expression
@defspecx delay expression
[SRFI-45][R5RS]
@c EN
These forms creates a @emph{promise} that delays the evaluation
of @var{expression}.  @var{Expression} will be evaluated
when the promise is passed to @code{force}.
@c JP
これらの形式は@var{expression}の評価を遅延する@emph{プロミス}を生成し
ます。@var{Expression} はこのプロミスが@code{force}にわたったときに評
価されます。
@c COMMON

@c EN
If @var{expression} itself is expected to yield a promise,
you should use @code{lazy}.  Othewise, you should use @code{delay}.
If you can think in types, the difference may be clearer.
@c JP
@var{expression}自身がプロミスを評価するようになっている場合には、
@code{lazy}を使うべきです。そうでなければ、@code{delay}を使うべきです。
型で考えればその違いは明白でしょう。
@c COMMON

@example
lazy  : Promise a -> Promise a
delay : a -> Promise a
@end example

@c EN
Since we don't have static typing, we can't enforce this usage.
The programmer has to choose appropriate one from the context.
Generally, @code{lazy} appearers only to surround the entire
body of function that express a lazy algorithm.
@c JP
Schemeでは静的な型付けをしないので、この使い分けを強制することができま
せん。文脈にしたがってプログラマが適切に選択する必要があります。一般的
には@code{lazy}は遅延アルゴリズムを表現している関数本体全体を囲む場合
にのみ出現します。
@c COMMON

@c EN
For the real-world example of use of @code{lazy},
you may want to check the implementation of @code{util.stream}
(@xref{Stream library}).
@c JP
@code{lazy}の実用的な使用例については@code{util.stream}
(@ref{Stream library})の実装をチェックするといいでしょう。
@c COMMON
@end defspec

@defun force promise
[R5RS]
@c EN
If @var{promise} is not a promise, it is just returned.

Otherwise, if @var{promise}'s value hasn't been computed,
@code{force} makes @var{promise}'s encapsulated expression
be evaluated, and returns the result.

Once @var{promise}'s value is computed, it is memorized in it
so that subsequent @code{force} on it won't cause the computation.
@c JP
もし、@var{promise}がプロミスでなければ、それをそのまま返します。

そうではない場合で、もし@var{promise}の値がまだ計算されていない場合には、
@code{force}は@var{promise}が内包している式を評価し、その結果を返します。

いったん、@var{promise}の値が計算されると、その値はメモ化され、あとで
再び@code{force}されても、再計算がおこなわれることはありません。
@c COMMON
@end defun

@defun promise? obj
@c EN
Returns @code{#t} iff @var{obj} is a promise object.
@c JP
@var{obj}がプロミスオブジェクトである場合に
@code{#t}を返します。
@c COMMON
@end defun

@c EN
The following example represents Fibonacci numbers by
a lazy list.   The list @code{fib} is calculated by
adding @code{fib} itself shifted one element.
Since it uses cached result of previous elements, calculation
of n-th Fibonacci number can be done in O(n).
@c JP
以下の例は遅延リストによるFibonacci数です。リスト@code{fib}は
@code{fib}自身に1要素シフトして@code{fib}を足し合せることで計算されま
す。直前の要素をキャッシュとして使っているので、n番目のFibonacci数の計
算はO(n)ですみます。
@c COMMON

@example
(define (lcar lis)   ;; lazy car
  (car (force lis)))

(define (lcdr lis)   ;; lazy cdr
  (cdr (force lis)))

(define (ltake lis n)  ;; lazy take
  (if (<= n 0) '() (cons (lcar lis) (ltake (lcdr lis) (- n 1)))))

(define (lmap proc l1 l2)  ;; lazy map
  (if (null? l1)
    '()
    (cons (proc (lcar l1) (lcar l2))
          (delay (lmap proc (lcdr l1) (lcdr l2))))))

;; lazy list of fibonacci numbers
(define fibs (list* 1 1 (delay (lmap + fibs (cdr fibs)))))

;; take a look
(ltake fibs 20)
  @result{} (1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 
      987 1597 2584 4181 6765)
@end example

@c EN
Note that, although it is elegant, it also requires O(n) storage
even when you only need n-th Fibonacci number.  That's because
the @code{delay} expression in the tail of @code{fibs} is grabbing
the head of @code{fibs} list and never releases it.
@c JP
これはエレガントな例ですが、n番目のFibonacci数を求めるのにO(n)の空間が
必要になるということに注意してください。これは、@code{fibs}の末尾にあ
る@code{delay}式が@code{fibs}リストの先頭を掴んだまま離さないからです。
@c COMMON

@c ----------------------------------------------------------------------
@node Exceptions, Eval and repl, Control features, Core library
@section Exceptions
@c NODE 例外

@c EN
Gauche's exception system consists of three components;
(1) the way to signal an exceptional case has occurred,
(2) the way to specify how to handle such a case,
and (3) the standard objects (@emph{conditions}) 
to communicate the code that
signals an exceptional case and the code that handles it.
@c JP
Gaucheの例外システムは次の3つのコンポーネントから構成されています。
(1)例外状況が発生したことを通知する方法、
(2)例外状況をどのように処理するかを指定する方法、
(3)例外状況を知らせたコードとそれを処理するコードがやりとりするための
標準オブジェクト(@emph{コンディション})。
@c COMMON

@c EN
Those three components are typically used together, so first
we explain the typical usage patterns using examples.  Then
we describe each feature in detail.
@c JP
普通これらの3つのコンポーネントは一緒に使われます。
そこで、最初に例を用いて典型的な使い方について説明し、
そのあとでそれぞれの機能について詳しく解説します。
@c COMMON

@c EN
Note for terminology: some languages use the word @emph{exception}
to refer to an object used to communicate the code that encountered
an exceptional situation with a handler that deals with it.
Gauche uses a term @emph{condition} to refer to such objects,
following SRFI-35.  @emph{Exception} is the situation, and
@emph{condition} is a runtime object that describes it.
@c JP
用語について: いくつかの言語では@emph{例外(exception)}というと、
例外的状況に遭遇したコードとそのハンドラがやりとりをするために用られる
オブジェクトのことを指します。Gaucheではそのようなオブジェクトのことを言うときには、
SRFI-35にならって@emph{コンディション(condition)}を使います。
@emph{例外}というのは、状況であり、@emph{コンディション}はそれを記述する
実行時のオブジェクトです。
@c COMMON

@menu
* Exception handling overview::  
* Signalling exceptions::       
* Handling exceptions::         
* Conditions::                  
@end menu

@node Exception handling overview, Signalling exceptions, Exceptions, Exceptions
@subsection Exception handling overview
@c NODE 例外処理の概要

@c EN
@subsubheading Catching specific errors
@c JP
@subsubheading 特定のエラーを捕まえる
@c COMMON

@c EN
One of the most typical exception handling is to catch a
specific error raised by some built-in or library procedures.
A macro @code{guard} can be used for such a purpose.  The code
looks like this:
@c JP
最もよくある例外処理のひとつは、組み込みあるいは
ライブラリの手続きから発生した特定のエラーを捕捉するというものです。
@code{guard}マクロがこのような目的の場合に使えます。
コードは以下のような感じになるでしょう。
@c COMMON

@example
(guard (exc
        ((condition-has-type? exc <read-error>)
         (format #t "read error!")
         'read-error)
        (else 'other-error))
  (read-from-string "(abc"))
@end example

@c EN
The cadr of @code{guard} clause is a form of 
@code{(@var{variable} @var{clause} @dots{})}.  In this example,
the variable is @code{exc}, and it has two clauses.
Each @var{clause} has the form like the one in @code{cond}.
@c JP
@code{guard}節の cadr 部は @code{(@var{variable} @var{clause} @dots{})} という
形式です。この例では、変数は @code{exc}で、2つの節があります。
それぞれの @var{clause} は @code{cond} と似た形式になります。
@c COMMON

@c EN
The cddr of @code{guard} is the body, a list of expressions.  This
example has only one expression, @code{(read-from-string "(abc")}.
@c JP
@code{guard} の cddr 部は本体で、式のリストです。この例では、式は
@code{(read-from-string "(abc")} のひとつだけです。
@c COMMON

@c EN
@code{guard} starts executing its body.
@code{read-from-string} raises an error of type @code{<read-error>}
when it encounters syntactic errors.  The form @code{guard} intercepts
the error, and binds the condition object to the variable @var{exc},
then checks the clauses following @var{exc} in a similar manner
to @code{cond}---in this case, the thrown condition is of type
@code{<read-error>}, so the test of the first clause is satisfied,
and the rest of clause is executed, i.e. @code{"read error!"} is
printed and a symbol @code{read-error} is returned.
@c JP
@code{guard} はその本体部を実行するところから始めます。
@code{read-from-string} は構文エラーに出くわすと、@code{<read-error>}型の
エラーを発生させます。@code{guard}フォームがこのエラーを捕捉し、
そのコンディションオブジェクトを変数@var{exc}に束縛し、@var{exc}の後の
節を、@code{cond}と同じようにチェックします。この場合、投げられた
コンディションは @code{<read-error>}なので、最初の節のテストを満し、
その節の残りの部分が実行されます。すなわち、@code{"read error!"} が
印字され、シンボル @code{read-error} が返ります。
@c COMMON

@c EN
If you're familiar with other languages, you may recognize the
pattern.  The cddr of @code{guard} form is like @var{try} clause
of C++/Java or the cadr of @code{handler-case} of Common Lisp;
and the cdadr of @code{guard} form is like @code{catch} clauses
or the cddr of @code{handler-case}.
@c JP
他の言語を使い慣れていれば、同じパターンであることがわかると思います。
@code{guard} フォームの cddr 部は、C++やJavaの @var{try} 節、あるいは、
Common Lisp の @code{handler-case} の cadr 部に似ています。
また、@code{guard} フォームの cdadr 部は、@code{catch} 節あるいは、
@code{handler-case} の cddr 部に似ています。
@c COMMON

@c EN
In the test expressions it is common to check the type of
thrown condition.  The function @code{condition-has-type?} is
defined in SRFI-35 but it's rather lengthy.  Gauche's condition
classes can also work like a predicate, so you can write the
above expression like this.
@c JP
テスト式においては、投げられたコンディションのタイプをチェックする
のが普通です。@code{condition-has-type?} という関数が
SRFI-35 で定義されていますが、これはちょっと冗長です。Gauche の
コンディションクラスは述語のようにも使えるようになっており、上の
式は以下のように書くこともができます。
@c COMMON

@example
(guard (exc
        ((<read-error> exc) 'read-error)
        (else 'other-error))
  (read-from-string "(abc")))
@end example

@c EN
@emph{Note:} Generally you can't use @code{is-a?} to test if
the thrown condition is of a specific type, since a condition
may be @emph{compound}.  See @ref{Conditions} about compound
conditions.
@c JP
@emph{注意事項:} 一般的には、投げられたコンディションが特定の
タイプであるかをチェックするのに@code{is-a?}は使えません。
コンディションが合成されたものである可能性があるからです。
合成されたコンディションについての
詳細は @ref{Conditions} を参照してください。
@c COMMON

@c EN
If no tests of @var{clause}s satisfy and no @code{else} clause is given,
the exception `falls off' the @code{guard} construct, i.e. 
it will be handled by the outer level of @code{guard} form or
top-level.  For example, the following @code{guard} form
only handles @code{<read-error>} and @code{<system-error>};
if the body throws other type of conditions, it must be handled
by outer level.
@c JP
もし、@var{clause} のどのテストも満されず、かつ @code{else} 節があたえられて
いなければ、その例外は @code{guard} から「抜け」ます。すなわち、@code{guard}
の外側のレベルあるいはトップレベルで処理されることになります。たとえば、
以下の @code{guard} フォームでは、@code{<read-error>} と 
@code{<system-error>} としか処理できず、もし、本体が他のタイプのコンディション
を投げてきたら、その外側のレベルで処理しなければなりません。
@c COMMON

@example
(guard (exc
        ((<read-error> exc) (handle-read-error))
        ((<system-error> exc) (handle-system-error))
        )
  body @dots{})
@end example

@c EN
See @ref{Handling exceptions} for more details on @code{guard} and
other lower-level exception handling constructs.
@c JP
@code{guard}および他の低レベルの例外処理の構成についての詳細は
@ref{Handling exceptions} を参照してください。
@c COMMON


@c EN
@subsubheading Signalling exceptions from your code
@c JP
@subsubheading 自分のコードから例外を通知する
@c COMMON

@c EN
The generic way to signal an exception is to use @code{raise} procedure.
@c JP
例外を通知する一般的な方法は @code{raise}手続きを使うことです。
@c COMMON

@example
(raise @var{condition})
@end example

@c EN
You can pass any object to @var{condition}; its interpretation
solely depends on the exception handler.  If you know the code
raises an integer as a condition, you can catch it by @code{guard}
as this:
@c JP
@var{condition}にはどんなオブジェクトでも渡すことができます。
それをどのように解釈するかはひとえに例外ハンドラにかかってます。
もし、コンディションとして整数があがってくるというのが判っていれば、
@code{guard} で以下のように捕捉することができます。
@c COMMON

@example
(guard (exc
        ((integer? exc) 'raised))
  (raise 3))
@end example

@c EN
However, as a convention, it is preferable to use an instance
of @code{<condition>} or one of its subclasses.  A macro @code{condition}
can be used to create a condition object.  The following examples
show how to create a condition with some slot values and then raise it.
@c JP
とはいうものの、@code{<condition>} あるいはそのサブクラスのインスタンスを
使うのが好ましいというのが通例です。@code{condition} マクロはコンディション
オブジェクトを作成するのに使えます。以下の例は、いくつかのスロット値をもち
それらを発生させるコンディションの作りかたを示したものです。
@c COMMON

@example
;; create and raise an error condition
(raise (condition
        (<error> (message "An error occurred."))))

;; create and raise a system error condition
(raise (condition
        (<system-error> (message "A system error occurred.")
                        (errno EINTR))))
@end example

@c EN
See @ref{Conditions} for the details of @code{condition} macro
and what kind of condition classes are provided.
@c JP
@code{condition} マクロおよび、どのようなコンディションクラスが用意
されているかの詳細については @ref{Conditions} を参照してください。
@c COMMON

@c EN
The most common type of condition is an error condition, so
a convenience procedure @code{error} and @code{errorf} are
provided.  They create an error condition with a message and
raise it.
@c JP
最も一般的なコンディションのタイプはエラーコンディションなので、
@code{error} および @code{errorf} という便利な手続きが
用意されています。これらはメッセージ付きのエラーコンディションを
生成し、それを発生させます。
@c COMMON

@example
;; `error' concatenates the arguments into a message.
(unless (integer? obj)
  (error "Integer expected, but got:" obj))

;; `errorf' uses format to create a message.
(unless (equal? x y)
  (errorf "~s and ~s don't match" x y))
@end example

@c EN
@emph{Note:} unlike the exception throwing constructs in some languages,
such as @code{throw} of C++/Java, which abandons its continuation,
Scheme's @code{raise} may return to its caller.   If you don't
want @code{raise} to return, a rule of thumb is always to pass
one of error conditions to it; then Gauche guarantees @code{raise}
wont return.   See the description of @code{raise} in
@ref{Signalling exceptions} for more details.
@c JP
@emph{注意事項:} いくつかの言語での例外を投げる機構、たとえば、
Cl++やJavaの @code{throw} はその継続を破棄します。これとは違い
Schemeの @code{raise} はその呼び出し元へ戻ることができます。もし、
@code{raise} で元へもどらないで欲しいのなら、簡便な方法としては、
常にエラーコンディションの一つをわたるようにするというのがあります。
そうすると Gauche では @code{raise} は戻らないことを保証します。
@code{raise}の詳細については、@ref{Signalling exceptions}を参照してください。
@c COMMON


@c EN
@subsubheading Defining your own condition
@c JP
@subsubheading 独自のコンディションを定義する
@c COMMON

@c EN
You can also define your own condition classes
to pass application-specific information from the point of
raising exception to the handlers.
@c JP
独自のコンディションクラスを定義することが可能で、そうすることで、
アプリケーション固有の情報を例外が発生した点からハンドラへ渡すことが
できます。
@c COMMON

@c EN
To fit to Gauche's framework (SRFI-35), it is desirable that
the new condition class inherits a built-in @code{<condition>} class
or one of its descendants, and also is an instance of a metaclass
@code{<condition-meta>}.
@c JP
Gauche のフレームワーク(SRFI-35)に適合させるためには、新しく定義する
コンディションクラスは組み込みの @code{<condition>} クラスあるいは
その子孫を継承し、また、メタクラス @code{<condition-meta>}
のインスタンスであることが望まれます。
@c COMMON

@c EN
One way of ensuring the above convention as well as increasing 
portability is to use @code{define-condition-type} macro, defined
in @code{SRFI-35}.
@c JP
可搬性を増すと同時に上の慣例を確実にするための方法のひとつは、
@code{define-condition-type}マクロを使うことです。これは、
@code{SRFI-35}で定義されています。
@c COMMON

@example
(define-condition-type <myapp-error> <error>
  myapp-error?
  (debug-info myapp-error-debug-info)
  (reason myapp-error-reason))
@end example

@c EN
This defines a condition type (which is a class in Gauche)
@code{<myapp-error>}, with a predicate @code{myapp-error?}
and slots with accessors.   Then you can use the new
condition type like the following code:
@c JP
これは、(Gauche内のクラス)@code{<myapp-err>}を定義するもので、
このクラスには@code{myapp-error?}という述語とアクセサのあるスロット
があります。こうすれば、以下のようなコードで新しいコンディション
型が使えます。
@c COMMON

@example
(guard (exc
         ((myapp-error? exc)
          (let ((debug-info (myapp-error-debug-info exc))
                (reason (myapp-error-reason exc)))
            ... handle myapp-error ...)))
  ...
  ...
  (if (something-went-wrong)
    (raise (condition
             (<myapp-error> (debug-info "during processing xxx")
                            (reason "something went wrong")))))
  ...
  ...
  )
@end example

@c EN
If you don't mind to lose srfi compatibility, you can use
Gauche's extended @code{error} and @code{errorf} procedures to write
more concise code to raise a condition of subtype of @code{<error>}:
@c JP
SRFIとの互換性が重要でないなら、Gaucheの拡張された@code{error}手続きを
使うと@code{<error>}のサブタイプであるコンディションを投げるコードを
より簡潔に書くことができます。
@c COMMON

@example
  (if (something-went-wrong)
    (error <myapp-error>
           :debug-info "during processing xxx"
           :reason "something went wrong"))
@end example


@c EN
See the description of @code{define-condition-type} macro
for how the condition type is implemented in Gauche's object system.
@c JP
Gauche のオブジェクトシステムでコンディション型がどのように実装されているかは
@code{define-condition-type}マクロの解説を参照してください。
@c COMMON

@node Signalling exceptions, Handling exceptions, Exception handling overview, Exceptions
@subsection Signalling exceptions
@c NODE 例外の通知

@c EN
@subsubheading Signalling errors
@c JP
@subsubheading エラーの通知
@c COMMON

@c EN
The most common case of exceptions is an error.
Two convenience functions to signal an error condition
in simple cases are provided.
To signal a compound condition, you can use @code{raise} as explained below.
@c JP
最も良くある例外ケースはエラーです。単純なエラーを通知するために、
ふたつの簡単な関数が用意されています。
複合コンディションを通知する必要がある場合は
下で説明する@code{raise}手続きを使って下さい。
@c COMMON

@defun error string arg @dots{}
@defunx error condition-type keyword-arg @dots{} string arg @dots{}
@c EN
[SRFI-23+] Signals an error.  The first form creates an @code{<error>}
condition, with a message consists of @var{string} and @var{arg} @dots{},
and raises it.  It is compatible to srfi-23's @code{error} behavior.
@c JP
[SRFI-23+] エラーを通知します。最初の形式は、
@var{string}と@var{arg} @dots{}からなるメッセージを持つ
@code{<error>}コンディションを作成それを@code{raise}します。
この形式はsrfi-23の@code{error}と互換です。
@c COMMON

@example
gosh> (define (check-integer x)
        (unless (integer? x)
           (error "Integer required, but got:" x)))
check-integer
gosh> (check-integer "a")
*** ERROR: Integer required, but got: "a"
Stack Trace:
_______________________________________
@end example

@c EN
The second form can be used to raise an error other than the
@code{<error>} condition.  @var{condition-type} must be
a condition type (see @ref{Conditions} for more explanation of
condition types).  It may be followed by keyword-value list 
to initialize the condition slots, and then optionally followed by
a string and other objects that becomes an error message.
@c JP
2番目の形式は@code{<error>}以外のエラーコンディションを通知したいときに
使います。@var{condition-type}はコンディションタイプ
でなければなりません (コンディションタイプについては@ref{Conditions}を
参照して下さい)。その後に、キーワードと値のリストを与えることで
コンディションのスロットを初期化することができます。また、その後に
メッセージを構成する文字列と他のオブジェクトのリストを与えることができます。
@c COMMON

@example
(define-condition-type <my-error> <error> #f
  (reason)
  (priority))

...
  (unless (memq operation *supported-operations*)
    (error <my-error> 
           :reason 'not-supported :priority 'urgent
           "Operation not supported:" operation))
...
@end example
@end defun

@defun errorf fmt-string arg @dots{}
@defunx errorf condition-type keyword-arg @dots{} fmt-string arg @dots{}
@c EN
Similar to @code{error}, but the error message is formatted by
@code{format}, i.e. the first form is equivalent to:
@c JP
@code{error}に似ていますが、エラーメッセージは@code{format}によりフォーマット
されます。すなわち、最初のフォームは以下と等価です。
@c COMMON
@example
(define (errorf fmt . args)
  (error (apply format #f fmt args)))
@end example

@c EN
The second form can be used to raise an error other than an
@code{<error>} condition.  Meaning of @var{condition-type} and
@var{keyword-arg}s are the same as @code{error}.
@c JP
2番目の形式は@code{<error>}以外のエラーコンディションを通知するのに
使えます。@var{condition-type}, @var{keyword-arg}の意味については
@code{error}と同じです。
@c COMMON
@end defun

@c EN
@subsubheading Signalling generic conditions
@c JP
@subsubheading 一般的な条件の通知
@c COMMON

@defun raise condition
@c EN
[SRFI-18] 
This is the base mechanism of signalling exceptions.

The procedure invokes the current exception handler.
The argument @var{condition} represents the nature of the exception,
and passed to the exception handler.
Gauche's built-in and library functions always use
an instance of @code{<condition>} or one of its subclasses as @var{condition},
but you can pass any Scheme object to @code{raise}.  The interpretation
of @var{condition} is up to the exception handler.

@emph{Note:} Unlike some of the mainstream languages in which
"throwing" an exception never returns, you can set up an exception
handler in the way that @code{raise} may return.  The details
are explained in @ref{Handling exceptions}.

If you don't want @code{raise} to return, the best way is to
pass a condition which is an instance of @code{<serious-condition>} 
or one of its subclasses.  Gauche's internal mechanism
guarantees raising such an exception won't return.
See @ref{Conditions} for the hierarchy of built-in conditions.
@c JP
[SRFI-18]
これは、例外事態を通知する基本となるメカニズムです。

この手続きは現在の例外ハンドラを呼び出します。引数@var{condition}は
例外の性質を表現するのに使われ、例外ハンドラに渡されます。
Gaucheの組み込み手続きやライブラリ手続きは常に、@code{<condition>}クラス
もしくはそのサブクラスのインスタンスを@var{condition}として用いますが、
ユーザは任意のオブジェクトを@code{raise}に渡すこともできます。
渡された@var{condition}の解釈は例外ハンドラに任されます。

@emph{注意事項:} いくつかの主流の言語では、例外を「投げる」と制御はそこに
戻りません。Gaucheでは@code{raise}から戻って来れるように
セットアップすることが可能です。詳細は@ref{Handling exceptions}を
参照してください。

@code{raise}から戻って来ることが無いようにしたい場合は、
@code{<serious-condition>}やそのサブクラスのインスタンスを@var{condition}
として@code{raise}に渡すのが確実です。
組み込みコンディションのクラス階層については@ref{Conditions}を参照して下さい。
@c COMMON
@end defun


@node Handling exceptions, Conditions, Signalling exceptions, Exceptions
@subsection Handling exceptions
@c NODE 例外の処理

@c EN
@subsubheading High-level exception handling mechanism
@c JP
@subsubheading 上位レベルの例外処理機構
@c COMMON

@defmac guard (var clause @dots{}) body @dots{}
[SRFI-34]
@c EN
This is @emph{the} high-level form to handle errors in Gauche.
@c JP
これはGaucheでのエラー処理の高水準フォームです。
@c COMMON

@c EN
@var{var} is a symbol, and @var{clause}s are the same form as
@code{cond}'s clauses, i.e. each clause can be either one of
the following forms:
@c JP
@var{var} はシンボルで @var{clause} は @code{cond} 節と同じ形式です。
つまり、各節は以下の形式のどれかひとつです。
@c COMMON
@enumerate
@item
@code{(@var{test} @var{expr} @dots{})}
@item
@code{(@var{test} => @var{proc})}
@end enumerate

@c EN
The last @var{clause} may be @code{(else @var{expr} @dots{})}.
@c JP
最後の@var{clause}は@code{(else @var{expr} @dots{})}という形式も許されます。
@c COMMON

@c EN
This form evaluates @var{body} @dots{} and returns the value(s) of
the last @var{body} expression in normal case.
If an exception is raised during the evaluation of body expressions,
the raised exception is bound to a variable @var{var}, then
evaluates @var{test} expression of each clause.  If one of @var{test}
expressions returns true value, then the corresponding @var{expr}s
are evaluated if the clause is the first form above, or an @var{proc}
is evaluated and the result of @var{test} is passed to the procedure
@var{proc} if the clause is the second form.
@c JP
このフォームは通常の場合には @var{body} @dots{} を評価し最後の
@var{body} の式の値を返します。本体の式を評価している最中に例外が
発生した場合、発生した例外を変数 @var{var} に束縛し、その後
各節の @var{test} 式を評価します。もし、@var{test} 式のひとつが
真値を返したとき、その節が上述の最初の形式であれば、対応する
@var{expr} が評価されます。あるいは、節が二番目の形式であれば、
手続き@var{proc}に@var{test}の結果が渡されます。
@c COMMON

@c EN
When the @var{test}(s) and @var{expr}(s) in the clauses are evaluated,
the exception handler that is in effect of the caller of @code{guard} are
installed; that is, if an exception is raised again within @var{clause}s,
it is handled by the @emph{outer} exception handler or @code{guard} form.
@c JP
指定された節の @var{test} および @var{expr} が評価されるとき、
@code{guard}を呼び出した時点での例外ハンドラが設定されます。つまり、
@var{clause} 内部で再び例外が発生した場合、その例外は、@emph{外側の}
例外ハンドラまたは @code{guard} フォームで処理されます。
@c COMMON

@c EN
If no @var{test} returns true value and the last @code{clause} is
@code{else} clause, then the associated @var{expr}s are evaluated.
If no @var{test} returns true value and there's no @code{else} clause,
the raised exception is re-raised, to be handled by the outer exception
handler.
@c JP
もし、どの @var{test} も真値を返さず、最後の @code{clause} が
@code{else} 節であれば、それに結びつけられた @var{expr} が評価されます。
もし、どの @var{test} も真値を返さず、@code{else} 節がなければ、再び
例外が発生し、外側の例外ハンドラで処理されます。
@c COMMON

@c EN
When the exception is handled by one of @code{clause}s, @code{guard}
returns the value(s) of the last @var{expr} in the handling clause.
@c JP
例外が @code{clause} のどれかで処理された時には、@code{guard} は
それを処理した節の最後の @var{expr} の値を返します。
@c COMMON

@c EN
The @var{clause}s are evaluated in the same dynamic environment as
the @code{guard} form, i.e. any @code{dynamic-wind}s inside @code{body}
are unwound before evaluation of the @var{clause}s.  It is different
from the lower level forms
@code{with-error-handler} and @code{with-exception-handler}, whose
handler is evaluated before the dynamic environment are unwound.
@c JP
@var{clause}は@code{guard}と同じ動的環境で評価されます。すなわち、
@code{body}中の@code{dynamic-wind}は@var{clause}の評価の前に
巻戻されます。これは低レベル関数の@code{with-error-handler}や
@code{with-exception-handler}とは異なることに注意してください。
これら低レベル関数では例外ハンドラが呼ばれてから動的環境が巻戻されます。
@c COMMON

@example
(let ((z '()))
  (guard (e (else (push! z 'caught)))
    (dynamic-wind (lambda () (push! z 'pre))
                  (lambda () (error "foo"))
                  (lambda () (push! z 'post))))
  (reverse z))
 @result{} (pre post caught)

(guard (e (else (print 'OUTER) #f))
  (with-output-to-string ()
    (print 'INNER)
    (error "foo")))
@c EN
 @result{} prints OUTER to the current output port of guard,
      not to the string port.
@c JP
 @result{} OUTERを文字列ポートではなくguard実行時の
      current-output-portに出力。
@c COMMON
@end example
@end defmac

@defmac unwind-protect body cleanup
@c EN
Executes @var{body}, then executes @var{cleanup}, and
returns the result(s) of @var{body}.  If an exception is raised
within @var{body}, @var{cleanup} is executed before the
exception escapes from the @code{unwind-protect} form.
For example, the following code calls @code{start-motor},
@code{drill-a-hole}, and @code{stop-motor} in order if
everything goes ok, and if anything goes wrong in @code{start-motor}
or @code{drill-a-hole}, @code{stop-motor} is still called
before the exception escapes @code{unwind-protect}.
@c JP
@var{body}を実行してから@var{cleanup}を実行し、@var{body}の結果を返す。
@var{body}内で例外が挙がった場合、その例外が@code{unwind-protect}フォー
ムを抜ける前に、@var{cleanup}が実行されます。たとえば、以下のコードで
はなにも問題が起きなければ、@code{start-motor}、@code{drill-a-hole}、
@code{stop-motor}が、この順で呼ばれます。何か不具合が
@code{start-motor}あるいは@code{drill-a-hole}で起った場合でも、例外が
@code{unwind-protect}を抜ける前に@code{stop-motor}が呼ばれます。
@c COMMON

@example
(unwind-protect
  (begin (start-motor)
         (drill-a-hole))
  (stop-motor))
@end example

@c EN
The @var{cleanup} form is evaluated in the same dynamic environment
as @code{unwind-protect}.
If an exception is thrown within @var{cleanup}, it will be
handled outside of the @code{unwind-protect} form.
@c JP
@var{cleanup}フォームは@code{unwind-protect}と同じ動的環境で評価されま
す。例外が@var{cleanup}内で投げられた場合その例外は、
@code{unwind-protect}フォームの外側で処理されることになります。
@c COMMON

@c EN
Although this form looks similar to @code{dynamic-wind}, they
work at different layers and should not be confused.  
@code{dynamic-wind} is the bottom-level
building block and used to manage current exception handlers,
current i/o ports, parameters, etc.
@code{dynamic-wind}'s @var{before} and @var{after} thunks are
called whenever any of those control flow transition occurs.
On the other hand, @code{unwind-protect} only cares about
the Gauche's exception system.  @code{unwind-protect}'s @var{cleanup}
is called only when @var{body} exits normally or
throws Gauche's exception.
In the above example, if control escapes from @code{drill-a-hole} 
by calling a continuation captured outside of @code{unwind-protect},
@var{cleanup} is not called; because the control may return to
@code{drill-a-hole} again.  It can happen if user-level thread
system is implemented by @code{call/cc}, for example.
@c JP
このフォームは@code{dynamic-wind}と似ていますが、この2つは動作するレイ
ヤが違いますので混同しないようにしてください。
@code{dynamic-wind}は最下位レイヤのもので、現在の例外ハンドラ、現在の入出力
ポート、パラメータなどを管理するのに用います。
@code{dynamic-wind}の@var{before}および@var{after}のサンクは
対応する制御フローの遷移が起きたときに必ず呼ばれます。
一方、@code{unwind-protect}はGaucheの例外システムの面倒しか見ません。
@code{unwind-protect}の@var{cleanup}は@var{body}が正常終了するか
Gaucheの例外を投げたときにのみ呼びだされます。上述の例で、@code{unwind-protect}の外側で
補足された継続が呼ばれ、制御が@code{drill-a-hole}を抜けると、
@var{cleanup}は呼ばれません。制御が再び@code{drill-a-hole}に戻る可能性
があるからです。たとえば、ユーザレベルのスレッドシステムが
@code{call/cc}で実装されているような場合にこのようなことが起こる可能性
があります。
@c COMMON

@c EN
The name of this form is taken from Common Lisp.  Some Scheme
systems have similar macros in different names, such as
@code{try-finally}.
@c JP
このフォームの名前はCommon Lispから取りました。同様のマクロに
@code{try-finally}というような別の名前を使っているSchemeの処理系もあります。
@c COMMON
@end defmac


@defun with-error-handler handler thunk
@c EN
Makes @var{handler} the active error handler and executes @var{thunk}.
If @var{thunk} returns normally, the result(s) will be returned.
If an error is signalled during execution of @var{thunk},
@var{handler} is called with one argument, an exception object
representing the error, with the continuation of @code{with-error-handler}.
That is, @code{with-error-handler} returns whatever value(s) @var{handler}
returns.
@c JP
@var{handler}をアクティブなエラーハンドラにし、@var{thunk}を実行します。
@var{thunk}が正常に戻ったら、その結果が返されます。
@var{thunk}の実行中にエラーが通知されたら、エラーを表す例外オブジェクトを
1引数とする@var{handler}が、@code{with-error-handler}の継続とともに呼ばれます。
すなわち、@code{with-error-handler}は、@var{handler}が返す値を返します。
@c COMMON

@c EN
If @var{handler} signals an error, it will be handled by the
handler installed when @code{with-error-handler} called.
@c JP
@var{handler}がエラーを通知したら、それは@code{with-error-handler}が
呼ばれたときにインストールされていたハンドラにより処理されます。
@c COMMON

@c EN
The dynamic environment where @var{handler} is executed is
the same as the error occurs.  If @code{dynamic-wind} is used
in @var{thunk}, its @var{after} method is called after @var{handler}
has returned, and before @code{with-error-handler} returns.
@c JP
@var{handler}が実行される場合の動的な環境は、エラーが起きたときのそれと
同じです。@var{thunk}内で@code{dynamic-wind}が使われていたら、
その@var{after}メソッドは@var{handler}が戻った後、かつ@code{with-error-handler}が
戻る前に呼ばれます。
@c COMMON

@c EN
Note: Using this procedure directly is @emph{no longer recommended}, since
@code{guard} is more safe and portable.  We'll keep this for
a while for the backward compatibility, but we recommend to rewrite
code to use @code{guard} instead of this.
The common idiom of "cleanup on error"
code:
@c JP
註: この手続きを直接使うことはもはや@emph{推奨されません}。@code{guard}の方が
より安全でポータブルだからです。互換性を保つためまだしばらくは
この手続きを残しますが、この手続きを使っているコードを@code{guard}によって
書き直すことを推奨します。「エラー時に後始末をする」というよくある次のような処理は：
@c COMMON
@example
(with-error-handler (lambda (e) (cleanup) (raise e))
  (lambda () body @dots{}))
@end example
@c EN
should be written like this:
@c JP
次のように書き直すことができます。
@c COMMON
@example
(guard (e (else (cleanup) (raise e)))
  body @dots{})
@end example
@end defun


@c EN
@subsubheading Behavior of unhandled exception
@c JP
@subsubheading 処理されなかった例外のふるまい
@c COMMON

@c EN
If an exception is raised where no program-defined exception handler is
installed, the following action is taken.
@c JP
プログラムで定義した例外ハンドラを設定していないところで例外が発生した
場合以下のようなことが起ります。
@c COMMON

@itemize @bullet
@item 
@c EN
If the program is running interactively (in repl), the information
of the thrown exception and stack trace are displayed, and
the program returns to the toplevel prompt.
@c JP
プログラムが対話的に走っている場合(REPL)、投げられた例外の情報とスタッ
クトレースが表示され、プログラムはトップレベルのプロンプトに戻ります。
@c COMMON
@item
@c EN
If the program is running non-interactively, the information
of the thrown exception and stack trace are displayed, then
the program exits with an exit status @code{EX_SOFTWARE} (70).
@c JP
プログラムが対話的に走っているのではない場合は、投げられた例外の情報と
スタックトレースが表示された後、プログラムは終了コード
@code{EX_SOFTWARE} (70)で終了します。
@c COMMON
@end itemize

@c EN
@subsubheading Low-level exception handling mechanism
@c JP
@subsubheading 下位レベルの例外処理機構
@c COMMON

@c EN
This layer provides SRFI-18 compatible simple exception mechanism.
You can override the behavior of higher-level constructs such as
@code{with-error-handler} by using @code{with-exception-handler}.
@c JP
このレイヤはSRFI-18互換のシンプルな例外メカニズムを提供します。
@code{with-error-handler}のような高次元の構造の振る舞いを、
@code{with-exception-handler}を使って上書きすることができます。
@c COMMON

@c EN
Note that it is a double-edged sword.  You'll get a freedom to
construct your own exception handling semantics, but the Gauche
system won't save if something goes wrong.   Use these primitives
when you want to customize the system's higher-level semantics
or you are porting from other SRFI-18 code.
@c JP
これは諸刃の剣であることに注意して下さい。あなたは独自の例外処理
セマンティクスを構築する自由がありますが、Gaucheシステムは何か
間違いがあっても救ってくれません。システムの高次元のセマンティクスを
カスタマイズしたいか、他のSRFI-18準拠のコードを移植している場合にのみ、
これらのプリミティブを使って下さい。
@c COMMON

@defun current-exception-handler
@c EN
[SRFI-18]
Returns the current exception handler.
@c JP
[SRFI-18]
現在の例外ハンドラを返します。
@c COMMON
@end defun

@defun with-exception-handler handler thunk
@c EN
[SRFI-18]
A procedure @var{handler} must take one argument.  This procedure
sets @var{handler} to the current exception handler and calls
@var{thunk}.
@c JP
[SRFI-18]
@var{handler}は1引数を取る手続きです。この手続きは、@var{handler}を
現在の例外ハンドラにセットし、@var{thunk}を呼び出します。
@c COMMON
@end defun

@c EN
Generally, if you want to handle non-continuable exception such as
errors using this low-level mechanism,
you have to transfer the control from the handler explicitly
(See the explanation of @code{with-error-handler} above).
@code{raise} detects if the handler returns on the
non-continuable exceptions and reports an error using the
default error handler mechanism, but it is just a safety net.
@c JP
一般的に、エラーのような継続不可能な例外をこの低レベルなメカニズムで
扱いたい場合は、明示的にそのハンドラから制御を移さなければなりません
(前述の@code{with-error-handler}の説明を参照して下さい)。
@code{raise}は、ハンドラが継続不可能な例外を返したことを検知し、
デフォルトのエラーハンドラメカニズムを使ってエラーを報告しますが、
それは単に安全ネットにしか過ぎません。
@c COMMON

@c EN
Note also that @var{handler} is called in the same dynamic environment
of @code{raise}.  So if you raise an exception inside @var{handler},
it is captured by @var{handler} again.   It is the programmer's
responsibility to propagate the exception handling to the ``outer''
exception handlers.
@c JP
@var{handler}は@code{raise}の動的な環境と同じ環境で呼ばれることにも
注意して下さい。したがって、@var{handler}内部で例外を発生させると、
再度@var{handler}によって捕捉されます。その例外処理を``外側''の例外
ハンドラへ伝播させるのはプログラマの責任です。
@c COMMON

@c EN
The behavior of those procedures can be explained in
the following conceptual Scheme code.
@c JP
これらの手続きの振る舞いは、次の概念的なSchemeコードによって
説明されるでしょう。
@c COMMON

@example
@c EN
;; @r{Conceptual implementation of low-level exception mechanism.}
;; @r{Suppose %xh is a list of exception handlers}
@c JP
;; @r{低レベルな例外メカニズムの概念的な実装}
;; @r{%xhは例外ハンドラのリスト}
@c COMMON

(define (current-exception-handler) (car %xh))

(define (raise exn)
  (receive r ((car %xh) exn)
    (when (uncontinuable-exception? exn)
      (set! %xh (cdr %xh))
      (raise (@r{@i{make-error}} "returned from uncontinuable exception")))
    (apply values r)))

(define (with-exception-handler handler thunk)
  (let ((prev %xh))
    (dynamic-wind
      (lambda () (set! %xh (cons handler %xh)))
      thunk
      (lambda () (set! %xh prev)))))
@end example


@node Conditions,  , Handling exceptions, Exceptions
@subsection Conditions
@c NODE コンディション

@c EN
@subsubheading Built-in Condition classes
@c JP
@subsubheading 組み込みコンディションクラス
@c COMMON

@c EN
Gauche currently has the following hierarchy of built-in condition
classes.  It approximately reflects SRFI-35 and SRFI-36 condition hierarchy,
although they have Gauche-style class names.  If there's a corresponding
SRFI condition type, the class has the SRFI name as well.
@c JP
現在のところGaucheには以下の組み込みコンディションクラスの階層があります。
これは、おおよそのところ SRFI-35 および SRFI-36 のコンディションの階層を
反映したものですが、Gauche風のクラス名になっています。対応する SRFI の
コンディションタイプがあるものについては、SRFI でのクラス名も使えます。
@c COMMON

@example
  <condition>
    +- <compound-condition>
    +- <serious-condition>
    |    +- <serious-compound-condition> ; also inherits <compound-condition>
    +- <message-condition>
         +- <error>                      ; also inherits <serious-condition>
              +- <system-error>
              +- <unhandled-signal-error>
              +- <read-error>
              +- <io-error>
                   +- <port-error>
                        +- <io-read-error>
                        +- <io-write-error>
                        +- <io-closed-error>
                        +- <io-unit-error>
@end example

@c EN
Note that some conditions may occur simultaneously; for example,
error during reading from a file because of device failure may consist
both @code{<system-error>} @emph{and} @code{<io-read-error>}.
In such cases, a @emph{compound condition} is raised.
So you can't just use, for instance, @code{(is-a? obj <io-read-error>)}
to check if @code{<io-read-error>} is thrown. 
See the "Condition API" section below.
@c JP
いくつかのコンディションが同時に発生することがあることに注意してください。
たとえば、ファイルの読み込がデバイスの欠陥により失敗した場合は、
@code{<system-error>} @emph{および} @code{<io-read-error>} の両方からなる
エラーとなるでしょう。
このような場合、@emph{合成したコンディション (compound condition)} が発生します。
したがって、たとえば、@code{<io-read-error>} が投げられたかどうかをチェック
するのに、単に @code{(is-a? obj <io-read-error>)} を使えばよいというわけ
にはいきません。
後述の「コンディション API」の節を参照してください。
@c COMMON

@deftp {Metaclass} <condition-meta>
@clindex condition-meta
@c EN
Every condition class is an instance of this class.
This class defines @code{object-apply} so that you can use
a condition class as a predicate, e.g.:
@c JP
すべてのコンディションクラスはこのクラスのインスタンスです。
このクラスは @code{object-apply} を定義していますので、
コンディションクラスは述語として使うことができます。たとえば、
@c COMMON

@example
(<error> obj) @equiv{} (condition-has-type? obj <error>)
@end example
@end deftp


@deftp {Class} <condition>
@deftpx {Condition Type} &condition
@clindex condition
@vindex &condition
[SRFI-35]
@c EN
The root class of the condition hierarchy.
@c JP
コンディションの階層のルートクラスです。
@c COMMON
@end deftp

@deftp {Class} <compound-condition>
@clindex compound-condition
@c EN
Represents a compound condition.  A compound condition can be
created from one or more conditions by @code{make-compound-condition}.
Don't use this class directly.
@c JP
合成コンディションを表現します。合成コンディションは
@code{make-compound-condition} を用いて1つ以上のコンディションから
生成することができます。このクラスを直接使ってはいけません。
@c COMMON

@c EN
A compound condition returns @code{#t} for @code{condition-has-type?}
if any of the original conditions has the given type.
@c JP
合成コンディションは@code{condition-has-type?} に対して、
元のコンディションのどれかが、与えられたタイプなら、@code{#t} を返します。
@c COMMON
@end deftp

@deftp {Class} <serious-condition>
@deftpx {Condition Type} &serious
@clindex serious-condition
@vindex &serious
[SRFI-35]
@c EN
Conditions of this class are for the situations that are too serious
to ignore or continue.  Particularly, you can safely assume that
if you @code{raise} this type of condition, it never returns.
@c JP
このクラスのコンディションは無視して先を続けることはできない深刻な
状況のためにあります。特に、このタイプのコンディションを @code{raise}
したら、それは元には絶対に戻らないと考えて問題ありません。
@c COMMON
@end deftp

@deftp {Class} <serious-compound-condition>
@clindex serious-compound-condition
@c EN
This is an internal class to represent a compound condition
with any of its component condition is serious.   Inherits both
@code{<compound-condition>} and @code{<serious-condition>}.
@code{make-compound-condition} uses this class if the passed
conditions includes a serious one.  
Don't use this class directly.
@c JP
深刻なコンディションを含む合成コンディションを表現するための
内部クラスです。@code{<compound-condition>} および
@code{<serious-condition>} の両方を継承しています。
@code{make-compound-condition} は深刻なコンディションを含む複数の
コンディションを渡されると、このクラスを使います。このクラスを
直接使ってはいけません。
@c COMMON
@end deftp

@deftp {Class} <message-condition>
@deftpx {Condition Type} &message
@clindex message-condition
[SRFI-35]
@c EN
This class represents a condition with a message.  It has one slot.
@c JP
このクラスはメッセージ付のコンディションを表現し、スロットを一つ
もっています。
@c COMMON

@defivar {<message-condition>} message
@c EN
A message.
@c JP
メッセージ
@c COMMON

@end defivar
@end deftp

@deftp {Class} <error>
@deftpx {Condition Type} &error
@clindex error
@vindex &error
[SRFI-35]
@c EN
Indicates an error.  Inherits @code{<serious-condition>}
and @code{<message-condition>}, thus has @code{message} slot.
@c JP
エラーを表します。@code{<serious-condition>} および
@code{<message-condition>} を継承しています。したがって、
@code{message} スロットを持っています。
@c COMMON

@c EN
Note: SRFI-35 @code{&error} condition only inherits @code{&serious}
and not @code{&message}, so you have to use compound condition
to attach a message to the error condition.  Gauche uses multiple
inheritance here, largely because of backward compatibility.
To write a portable code, an error condition should be used
with a message condition, like this:
@c JP
注意事項: SRFI-35 の@code{&error}コンディションは @code{&serious}
のみを継承し、@code{&message} は継承していません。したがって、
このエラーコンディションにメッセージを付与するためには、
合成コンディションを使わなければなりません。Gauche は
主として過去のバージョンとの互換性を確保するために、
ここで多重継承を用いています。
可搬性のあるコードを書くには、以下のようにメッセージコンディション
付きのエラーコンディションを使うべきです。
@c COMMON

@example
(condition
  (&message (message "Error message"))
  (&error))
@end example
@end deftp

@deftp {Class} <system-error>
@clindex system-error
@c EN
A subclass of @code{<error>}.
When a system call returns an error, this type of exception is
thrown.  The @code{message} slot usually contains the description
of the error (like the one from @code{strerror(3)}).
Besides that, this class has one more instance slot:
@c JP
@code{<error>} のサブクラス。
システムコールがエラーを返したとき、この型の例外が投げられます。
@code{message} スロットには通常エラーの(@code{strerror(3)}のような)説明が
含まれています。それ以外に、このクラスにはもうひとつ次のような
インスタンススロットがあります。
@c COMMON

@defivar {<system-error>} errno
@c EN
Contains an integer value of system's error number.

Error numbers may differ among systems.  Gauche defines
constants for typical Unix error values (e.g. @code{EACCES}, @code{EBADF},
etc), so it is desirable to use them instead of literal numbers.
See the description of @code{sys-strerror} in @ref{System inquiry}
for available constants.
@c JP
システムのエラー番号の整数値を持ちます。

エラー番号はシステムによって異なる可能性があります。Gaucheは典型的な
Unixのエラー番号に対して定数を定義している(例: @code{EACCES}, @code{EBADF})ので、
それを使うと良いでしょう。定義されている定数に関しては
@ref{System inquiry}の@code{sys-strerror}の説明を参照してください。
@c COMMON
@end defivar

@c EN
This class doesn't have corresponding SRFI condition type,
but important to obtain OS's raw error code.  In some cases,
this type of condition is compounded with other condition
types, like @code{<io-read-error>}.
@c JP
このクラスには対応する SRFI のコンディションタイプがありませんが、
OSの生のエラーコードを取得するのに重要です。いくつかのケースで
このタイプのコンディションは他の、たとえば @code{<io-read-error>}
のようなコンディションと合成されます。
@c COMMON
@end deftp

@deftp {Class} <unhandled-signal-error>
@clindex unhandled-signal-error
@c EN
A subclass of @code{<error>}.  The default handler of most of
signals raises this condition.   See @ref{Handling signals} for
the details.
@c JP
@code{<error>}のサブクラス。多くのシグナルのデフォルトハンドラは
このコンディションを投げます。詳しくは@ref{Handling signals}を
参照してください。
@c COMMON
@defivar {<unhandled-signal-error>} signal
@c EN
An integer indicating the received signal number.
There are constants defined for typical signal numbers; see
@ref{Signals and signal sets}.
@c JP
受け取ったシグナル番号を示す整数値。典型的なシグナル番号については
定数が定義されています。@ref{Signals and signal sets}を参照のこと。
@c COMMON
@end defivar
@end deftp

@deftp {Class} <read-error>
@deftpx {Condition Type} &read-error
@clindex read-error
@vindex &read-error
[SRFI-36]
@c EN
A subclass of @code{<error>}.
When the reader detects a lexical or syntactic error during
reading an S-expression, this type of condition is raised.
@c JP
@code{<error>} のサブクラス。リーダがS式を読み込み中に、字句エラー
または構文エラーを検出したとき、この型のコンディションが投げられます。
@c COMMON

@defivar {<read-error>} port
@c EN
A port from which the reader is reading.
(NB: SRFI-36's @code{&read-error} doesn't have this slot.  Portable
program shouldn't rely on this slot).
@c JP
リーダがS式を読みこんでいたポート。
(註: SRFI-36 の @code{&read-error} はこのスロットを定義していません。
ポータブルなプログラムを書く場合はこのスロットを使わないで下さい)。
@c COMMON
@end defivar

@defivar {<read-error>} line
@c EN
A line count (1-base) of the input where the reader raised this error.
It may be -1 if the reader is reading from a port that doesn't keep
track of line count.
@c JP
リーダがこのエラーを発生させたときの入力行カウント(1がベース)。
リーダが行カウントを保持しないポートから読み込むときには、-1 となる。
@c COMMON
@end defivar

@defivar {<read-error>} column 
@defivarx {<read-error>} position
@defivarx {<read-error>} span
@c EN
These slots are defined in SRFI-36's @code{&read-error}.
For the time being, these slots always hold @code{#f}.
@c JP
これらのスロットは、SRFI-36 の @code{&read-error} で定義されています。
今のところ、これらのスロットは常に @code{#f} を保持するようになっています。
@c COMMON
@end defivar

@end deftp

@deftp {Class} <io-error>
@deftpx {Condition Type} &io-error
@clindex io-error
@vindex &io-error
[SRFI-36]
@c EN
A base class of I/O errors.  Inherits @code{<error>}.
@c JP
I/O エラーのベースとなるクラス。@code{<error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <port-error>
@deftpx {Condition Type} &io-port-error
@clindex port-error
@vindex &io-port-error
[SRFI-36]
@c EN
An I/O error related to a port.   Inherits @code{<io-error>}.
@c JP
ポート関連の I/O エラー。@code{<io-error>} を継承しています。
@c COMMON

@defivar <port-error> port
@c EN
Holds the port where the error occurred.
@c JP
エラーを起したポートを保持。
@c COMMON
@end defivar
@end deftp

@deftp {Class} <io-read-error>
@deftpx {Condition Type} &io-read-error
@clindex io-read-error
@vindex &io-read-error
[SRFI-36]
@c EN
An I/O error during reading from a port.  Inherits @code{<port-error>}.
@c JP
ポートから読み込み中の I/O エラー。@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <io-write-error>
@deftpx {Condition Type} &io-write-error
@clindex io-write-error
@vindex &io-write-error
[SRFI-36]
@c EN
An I/O error during writing to a port.  Inherits @code{<port-error>}.
@c JP
ポートへの書き出し中の I/O エラー。@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <io-closed-error>
@deftpx {Condition Type} &io-closed-error
@clindex io-closed-error
@vindex &io-closed-error
[SRFI-36]
@c EN
An I/O error when read/write is attempted on a closed port.
Inherits @code{<port-error>}.
@c JP
クローズされたポートで読み込み/書き出しをしようしたときの I/O エラー。
@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <io-unit-error>
@clindex io-unit-error
@c EN
An I/O error when the read/write is requested with a unit
that is not supported by the port (e.g. a binary I/O is requested
on a character-only port).   Inherits @code{<port-error>}.
@c JP
対象となるポートでサポートされていない単位での読み/書き要求
(たとえば、キャラクタ専用ポートでのバイナリ I/O 要求)の際の I/O エラー。
@code{<port-error>} を継承しています。
@c COMMON
@end deftp


@c EN
@subsubheading Condition API
@c JP
@subsubheading コンディションAPI
@c COMMON

@defmac define-condition-type name supertype predicate field-spec @dots{}
[SRFI-35+]
@c EN
Defines a new condition type.  In Gauche, a condition type is
a class, whose metaclass is @code{<condition-meta>}.
@c JP
新しいコンディションタイプを定義します。Gaucheでは、コンディションタイプは
クラスであり、そのメタクラスは @code{<condition-meta>} です。
@c COMMON

@c EN
@var{Name} becomes the name of the new type, and also the variable
of that name is bound to the created condition type.
@var{Supertype} is the name of the supertype (direct superclass)
of this condition type.  A condition type must inherit from
@code{<condition>} or its descendants.
(Multiple inheritance can't be specified by this form, and generally
should be avoided in condition type hierarchy.  Instead, you
can use compound conditions, which don't introduce multiple inheritance.)
@c JP
@var{name} が新しいタイプの名前になり、この名前の変数が作成された
コンディションタイプに束縛されます。@var{supertype} はこのコンディション
タイプのスーパータイプ(直接のスーパークラス)の名前です。コンディション
タイプは @code{<condition>} を継承するか、その子孫を継承しなければ
なりません。(この形式では、多重継承を指定することはできません。
一般的にいって、コンディションタイプの階層の中では多重継承は避ける
べきです。そのかわりに、合成コンディションを使えます。合成コンディションは
多重継承を使いません。)
@c COMMON

@c EN
A variable @var{predicate} is bound to a predicate procedure for
this condition type.
@c JP
変数 @var{predicate} はこのコンディションタイプ用の述語手続きに
束縛されます。
@c COMMON

@c EN
Each @code{field-spec} is a form of @code{(field-name accessor-name)},
and the condition will have fields named by @var{field-name}, and
a variable @var{accessor-name} will be bound to a procedure that
accesses the field.   In Gauche, each field becomes a slot of
the created class.

Gauche extends srfi-35 to allow @var{predicate} and/or @code{accessor-name}
to be @code{#f}, or @code{accessor-name} to be omitted,
if you don't need to them to be defined.
@c JP
各 @code{field-spec} は @code{(field-name accessor-name)} の形式で
このコンディションは、フィールド名は @var{field-name} で決まります。
変数 @var{accessor-name} はそのフィールドにアクセスする手続きに
束縛されます。Gauche では、それぞれのフィールドは生成された
クラスのスロットとなります。

Gaucheはsrfi-35を拡張して、@var{predicate}や@var{accessor-name}を
定義する必要が無い場合はその位置に@code{#f}を指定できるようにしています。
@var{accessor-name}が必要無い場合はそれを省略することもできます。
@c COMMON

@c EN
When @code{define-condition-type} is expanded into a class
definition, each slot gets a @code{:init-keyword} slot option
with the keyword whose name is the same as the slot name.
@c JP
@code{define-condition-type}がクラス定義に展開される際に、
各スロットは@code{:init-keyword}スロットオプションにスロット名と
同名のキーワードを取るように定義されます。
@c COMMON
@end defmac

@defun condition-type? obj
[SRFI-35]
@c EN
Returns @code{#t} iff @var{obj} is a condition type.  In Gauche,
it means @code{(is-a? obj <condition-meta>)}.
@c JP
@var{obj}がコンディションタイプである場合で、その場合にかぎり、
@code{#t} を返します。Gauche では @code{(is-a? obj <condition-meta>)}
と同じです。
@c COMMON
@end defun

@defun make-condition-type name parent field-names
[SRFI-35]
@c EN
A procedural version to create a new condition type. 
@c JP
新しいコンディションタイプを生成する手続き版です。
@c COMMON
@end defun

@defun make-condition type field-name value @dots{}
[SRFI-35]
@c EN
Creates a new condition of condition-type @var{type}, and
initializes its fields as specified by @code{field-name} and @code{value}
pairs
@c JP
コンディションタイプ @var{type} のコンディションを生成し、
@code{field-name} および @code{value} のペアで指定されたように
フィールドを初期化します。
@c COMMON.
@end defun

@defun condition? obj
[SRFI-35]
@c EN
Returns @code{#t} iff @var{obj} is a condition.  In Gauche,
it means @code{(is-a? obj <condition>)}.
@c JP
@var{obj} がコンディションである場合で、その場合にかぎり、
@code{#t} を返します。Gauche では @code{(is-a? obj <condition>)} と
同じです。
@c COMMON
@end defun

@defun condition-has-type? obj type
[SRFI-35]
@c EN
Returns @code{#t} iff @var{obj} belongs to a condition type @var{type}.
Because of compound conditions, this is not equivalent to @code{is-a?}.
@c JP
@var{obj} がコンディションタイプ @var{type} に属している場合で、その
場合にかぎり、@code{#t} を返します。合成コンディションがあるので、
これは、@code{is-a?} と同じではありません
@c COMMON
@end defun

@defun condition-ref condition field-name
[SRFI-35]
@c EN
Retrieves the value of field @var{field-name} of @var{condition}.
If @var{condition} is a compound condition, you can access to the
field of its original conditions; if more than one original condition
have @var{field-name}, the first one passed to @code{make-compound-condition}
has precedence.
@c JP
@var{condition} のフィールド @var{field-name} の値を検索します。
@var{condition} が合成コンディションであれば、元のコンディションの
フィールドにアクセスできます。もし、複数の元のコンディションが、
@var{field-name} を持つ場合には、最初に @code{make-compound-condition}
に渡されたものが優先されます。
@c COMMON

@c EN
You can use @var{slot-ref} and/or @var{ref} to access to the field
of conditions; compound conditions define a @code{slot-missing} method
so that @var{slot-ref} behaves as if the compound conditions have all the
slots of the original conditions.  Using @code{condition-ref} increases
portability, though.
@c JP
コンディションのフィールドにアクセスするには、@var{slot-ref} および
@var{ref} の両方あるいはどちらかを使えます。合成コンディションでは、
@code{slot-missing} メソッドが定義されますので、@var{slot-ref} は
あたかも、合成コンディションが元になったコンディションの全てのスロットを
もつかのように振舞います。しかしながら、@code{condition-ref} を
使う方が可搬性が増します。
@c COMMON
@end defun

@defun make-compound-condition condition0 condition1 @dots{}
[SRFI-35]
@c EN
Returns a compound condition that has all @var{condition0} @var{condition1}
@dots{}.  The returned condition's fields are the union of all the fields
of given conditions; if any conditions have the same name of fields,
the first one takes precedence.   The returned condition also has
condition-type of all the types of given conditions.
(This is not a multiple inheritance.  See @code{<compound-condition>} above.)
@c JP
@var{condition0} @var{condition1} @dots{} のすべてを持つ合成コンディション
を返します。返されたコンディションのフィールドは、与えられたコンディション
のすべてのフィールドの和集合になります。同じ名前のフィールドを持つ
コンディションがある場合には最初に与えられものが優先されます。
返されたコンディションは元になったコンディションのすべてのタイプの
コンディションタイプをもつことになります。
(これは多重継承ではありません。上の @code{<compound-condition>} を参照)
@c COMMON
@end defun

@defun extract-condition condition condition-type
[SRFI-35]
@c EN
@var{Condition} must be a condition and have type @var{condition-type}.
This procedure returns a condition of @var{condition-type},
with field values extracted from @var{condition}.
@c JP
@var{condition} はコンディションで、@var{condition-type}タイプで
なければなりません。この手続きは @var{condition-type} のコンディション
を返し、@var{condition} からとりだされた値のフィールドを持ちます。
@c COMMON
@end defun

@defmac condition type-field-binding @dots{}
[SRFI-35]
@c EN
A convenience macro to create a (possibly compound) condition.
@var{Type-field-binding} is a form of 
@code{(@var{condition-type} (@var{field-name} @var{value-expr}) @dots{})}.
@c JP
コンディションを生成するのに便利なマクロ。
合成されたコンディションも生成できます。
@var{Type-field-binding} は、
@code{(@var{condition-type} (@var{field-name} @var{value-expr}) @dots{})}
という形式になります。
@c COMMON

@example
(condition
  (type0 (field00 value00) ...)
  (type1 (field10 value10) ...)
  ...)
 @equiv{}
(make-compound-condition
  (make-condition type0 'field00 value00 ...)
  (make-condition type1 'field10 value10 ...)
  ...)
@end example
@end defmac


@c ----------------------------------------------------------------------
@node Eval and repl, Input and output, Exceptions, Core library
@section Eval and repl
@c NODE eval と repl

@defun eval expr env
@c EN
[R5RS]
Evaluate @var{expr}.   @var{env} must be a value returned by
the following procedures below.  Right now it is just a
@code{<module>} object, but it is possible that the Gauche
adopts a first-class environment object in future.
@c JP
[R5RS]
@var{expr}を評価します。@var{env}は下に述べる手続きにより
返される値でなければなりません。現時点では、それは単なる
@code{<module>}オブジェクトですが、Gaucheが将来、ファースト
クラスの環境オブジェクトを採用する可能性はあります。
@c COMMON
@end defun

@defun null-environment version
@defunx scheme-report-environment version
@defunx interaction-environment
@c EN
[R5RS]
Returns an environment specifier which can be used as the second
argument of @code{eval}.   Right now an environment specifier
is just a module.  @code{(null-environment 5)} returns
a @code{null} module, which contains just the syntactic bindings
specified in R5RS, @code{(scheme-report-environment 5)}
returns a @code{scheme} module, which contains syntactic and procedure
bindings in R5RS, and @code{(interaction-environment)} returns
a @code{user} module that contains all the Gauche built-ins plus
whatever the user defined.
It is possible that the Gauche adopts a first-class environment object
in future, so do not rely on the fact that the environment specifier
is just a module.
@c JP
[R5RS]
@code{eval}の第2引数として使われる環境識別子を返します。
現時点では、環境識別子は単にモジュールです。
@code{(null-environment 5)}は、R5RSで規定されている単なる構文的な
束縛を含む@code{null}モジュールを返します。
@code{(scheme-report-environment 5)}は、R5RSで規定されている
構文的な束縛と手続きの束縛を含む@code{scheme}モジュールを返します。
@code{(interaction-environment)}は、全てのGaucheのビルトインと
ユーザ定義の全てを含んだ@code{user}モジュールを返します。
将来、Gaucheがファーストクラスの環境オブジェクトを採用する可能性が
あるので、環境識別子が単なるモジュールであることを当てにしないで
下さい。
@c COMMON

@c EN
An error is signaled if a value other than 5 is passed as @var{version}
argument.
@c JP
引数@var{version}に5以外の値を渡すとエラーが通知されます。
@c COMMON

@end defun

@defun read-eval-print-loop :optional reader evaluator printer prompter
@c EN
This exports @code{Gosh}'s default read-eval-print loop to applications.
Each argument can be @code{#f}, which indicates it to use Gauche's
default procedure(s), or a procedure that satisfies the
following conditions.
@c JP
@code{gosh}のデフォルトのread-eval-printループをアプリケーションに
エクスポートします。それぞれの引数は、Gaucheのデフォルトの手続きを使うことを
示す@code{#f}であっても良いですし、以下の条件を満たす手続きであっても構いません。
@c COMMON

@table @emph
@item reader
@c EN
A procedure that takes no arguments.  It is supposed to read an expression
and returns it.
@c JP
引数を取らない手続きです。式を読み込んでそれを返すことを期待されます。
@c COMMON
@item evaluator
@c EN
A procedure that takes two arguments, an expression and an environment
specifier.  It is supposed to evaluate the expression and returns zero or
more value(s).
@c JP
式と環境識別子を2引数として取る手続きです。式を評価して、0個以上の値を
返すことを期待されます。
@c COMMON
@item printer
@c EN
A procedure that takes zero or more arguments.   It is supposed to
print out these values.   The result of this procedure is discarded.
@c JP
0個以上の引数を取る手続きです。それらの値を出力することを期待されます。
この手続きの戻り値は無視されます。
@c COMMON
@item prompter
@c EN
A procedure that takes no arguments.  It is supposed to print
out the prompt.   The result of this procedure is discarded.
@c JP
引数を取らない手続きです。プロンプトを出力することを期待されます。
この手続きの戻り値は無視されます。
@c COMMON
@end table

@c EN
Given those procedures, @code{read-eval-print-loop} runs as follows:
@c JP
これらの手続きが与えられると、@code{read-eval-print-loop}は以下のように
動作します。
@c COMMON

@enumerate
@item
@c EN
Prints the prompt by calling @var{prompter}.
@c JP
@var{prompter}を呼んでプロンプトを出力します。
@c COMMON
@item
@c EN
Reads an expression by calling @var{reader}.  If it returns EOF,
exits the loop and returns from @code{read-eval-print-loop}.
@c JP
@var{reader}を呼んで式を読み込みます。EOFが返されたら、ループを終了し
@code{read-eval-print-loop}から戻ります。
@c COMMON
@item
@c EN
Evaluates an expression by calling @var{evaluator}
@c JP
@var{evaluator}を呼んで式を評価します。
@c COMMON
@item
@c EN
Prints the result by calling @var{printer}, then repeats from 1.
@c JP
@var{printer}を呼んで結果を出力し、その後、1から繰り返します。
@c COMMON
@end enumerate

@c EN
When an error is signaled from one of those procedures, it is
captured and reported by the default escape handler, then
the loop restarts from 1.
@c JP
これらの手続きのうちの1つからエラーが通知されると、そのエラーは
デフォルトのエスケープハンドラにより捕捉・報告され、その後、
ループが1から再開します。
@c COMMON

@c EN
It is OK to capture a continuation within those procedures
and re-invoke them afterwards.
@c JP
これらの手続きの内部で継続を捕捉し、後で再起動することは
許されています。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Input and output, Loading Programs, Eval and repl, Core library
@section Input and Output
@c NODE 入出力

@menu
* Ports::                       
* Port and threads::            
* Common port operations::      
* File ports::                  
* String ports::                
* Coding-aware ports::          
* Input::                       
* Output::                      
@end menu

@node Ports, Port and threads, Input and output, Input and output
@subsection Ports
@c NODE ポート

@deftp {Builtin Class} <port>
@clindex port
@c EN
A port class.   A port is Scheme's way of abstraction of I/O channel.
Gauche extends a port in number of ways so that it can be used
in wide range of applications.
@c JP
Portは、Schemeにおいて抽象化された入出力のインタフェースを提供します。
Gaucheはportにいくつかの拡張を行い、いろいろなアプリケーションに対応できるようにしました。
@c COMMON

@c EN
Standard Scheme (R5RS) essentially defines a port as an entity that
you can fetch a character at a time and
look one character ahead from an input port, 
and put a character at a time to an output port.
Other R5RS I/O routines can be built on top of them.
@c JP
標準のSchemeでは、portはキャラクタを一文字づつ読み込む(一文字先読み可)、
もしくは書き出すだけのもので、他の入出力ルーチンはその上に構築されています。
@c COMMON

@c EN
Besides this basics, Gauche's port can handle the following
operations.
@c JP
Gaucheではさらに次のような操作がportに対して可能になっています。
@c COMMON

@table @asis
@c EN
@item Binary I/O
You can read/write one octet at a time, instead of a character.
(Remember, Gauche handles multibyte characters, so a character
may be consisted from more than one bytes).
Most ports allow you to mix binary I/O and character I/O, if needed.

The most basic binary I/O primitives are @code{read-byte} and
@code{write-byte}.  You can also use higher-level functionality,
such as @code{pack} and @code{unpack} in @ref{Packing Binary Data}.
@c JP
@item バイナリI/O
キャラクタ毎でなく、オクテット毎のI/Oが可能です(Gaucheではマルチバイト文字を
扱うので、この２つが異なることに注意して下さい)。大抵のポートでは
キャラクタI/OとバイナリI/Oを混ぜて使うことができます。

最も基本的なバイナリI/Oプリミティブは@code{read-byte}と@code{write-byte}です。
また、より高機能な@code{pack}や@code{unpack}といった手続きが
@ref{Packing Binary Data} で提供されています。
@c COMMON

@c EN
@item Block I/O
You can read/write a specified number of byte sequences.
This can be an efficient way of moving block of data,
if the port's underlying implementation supports block I/O
operation.
@c JP
@item ブロックI/O
ポートから指定した数のバイト列を読んだり、ポートへ書いたりできます。
ポートがブロックI/Oを行うデバイスに接続されている場合、ある程度大きなブロック毎に
読み書きすると効率の良いデータ転送ができます。
@c COMMON

@c EN
@item Conversion
Some ports can be used to convert a data stream from one format
to another; one of such applications is character code conversion
ports, provided by @code{gauche.charconv} module
(@xref{Character code conversion}, for details).
@c JP
@item 変換
ポートはまた、データストリームを変換するのにも使えます。例えば@code{gauche.charconv}
モジュールでは、文字コード間の変換を行うポートを提供しています
(詳しくは@ref{Character code conversion}を参照)。
@c COMMON

@c EN
@item Extra features
There are also a ports with special functionality.
A coding-aware port (@xref{Coding-aware ports}) recognizes a special
"magic comment" in the file to know which character encoding the
file is written.
Virtual ports (@xref{Virtual ports}) allows you to program the
behavior of the port in Scheme.
@c JP
@item 追加機能
また、特殊な機能を実現するポートもあります。
コーディング認識ポート(@ref{Coding-aware ports}参照)は
ファイル中の特殊なコメントを認識して、そのファイルがどの文字エンコーディング
で書かれているかを検出します。
仮想ポート(@ref{Virtual ports}参照)はSchemeでふるまいをプログラムできる
ポートを提供します。
@c COMMON
@end table

@end deftp

@node Port and threads, Common port operations, Ports, Input and output
@subsection Port and threads
@c NODE ポートとスレッド

@c EN
When Gauche is compiled with thread support, 
the builtin port operations locks the port, so that port access
from multiple threads will be serialized.   
(It is required by SRFI-18, BTW).
Here, "builtin port operations" are the port access functions
that takes a port and does some I/O or query on it,
such as @code{read}/@code{write}, @code{read-char}/@code{write-char}, 
@code{port->string}, etc.
Note that @code{call-with-*} and @code{with-*} procedures do not
lock the port during calling the given procedures, since the
procedure may pass the reference of the port to the other thread,
and Gauche wouldn't know if that's the case.
@c JP
GaucheがスレッドサポートをONにしてコンパイルされている場合、
組み込みのポート操作関数はポートをロックして、
複数のスレッドからの同一のポートへのアクセスがポートの内部状態を壊さないように
しています。
(SRFI-18によって要求されている動作です)。
ここで「組み込みのポート操作関数」はGaucheにより提供される、
ポートを引数に取り何らかのI/O動作や問い合わせを行う手続きで、
@code{read}/@code{write}、@code{read-char}/@code{write-char}、
@code{port->string}等を含みます。
但し、@code{call-with-*}や@code{with-*}系関数は、
与えられた手続きを呼ぶ際にはポートをロックしません。
その手続きが別のスレッドにポートを渡すかもしれず、Gaucheにはそれを知ることが
できないからです。
@c COMMON

@c EN
This means you don't need to be too paranoia to worry about
ports under multithreaded environment.  However, keep it in
mind that this locking mechanism is meant to be a safety net
from breaking the port's internal state, and not to be
a general mutex mechanism.  It assumes port accesses rarely
conflict, and uses spin lock to reduce the overhead of majority
cases.  If you know there will be more than one thread accessing
the same port, you should use explicit mutex to avoid conflicts.
@c JP
従って、マルチスレッド環境でポートへのアクセス競合により
ポートの内部状態を壊してしまうんじゃないか、などとあまり神経質に
なる必要はありません。但し、このロック機構はあくまで予想外の
アクセス競合によってポートがおかしな状態になってしまうことを
防ぐための安全ネットであって、一般的な排他制御機構として使われる
ことは想定していないのに注意して下さい。このロックの実装は、
ポートへのアクセス競合は例外的な場合のみであると仮定し、
通常のアクセスにおけるオーバヘッドを避けるために、スピンロックを
使用します。もし、意図的にポートアクセスが競合するようなコードを書く場合は、
明示的に排他制御をしてください。
@c COMMON

@defun with-port-locking port thunk
@c EN
Executes @var{thunk}, while making the calling thread
hold the exclusive lock of @var{port} during the dynamic extent
of @var{thunk}.

Calls of the builtin port functions during the lock is held
would bypass mutex operations and yield better performance.

Note that the lock is held during the dynamic extent of @var{thunk};
so, if @var{thunk} invokes a continuation captured outside of
@code{with-port-locking}, the lock is released.  If the continuation
captured within @var{thunk} is invoked afterwards, the lock is re-acquired.

@code{With-port-locking} may be nested.  The lock is valid during
the outermost call of @code{with-port-locking}.

Note that this procedure uses the port's built-in lock mechanism
which uses busy wait when port access conflicts.  It should be
used only for avoiding fine-grain lock overhead; use explicit
mutex if you know there will be conflicts.
@c JP
@var{port}をロックし、@var{thunk}を実行します。
ロックは@var{thunk}のダイナミックエクステントの期間有効です。

@var{port}がロックされている期間での組み込みのポートアクセス関数の
呼び出しは排他制御をバイパスするため、性能向上が見込まれます。

ロックの有効期間は@var{thunk}のダイナミックエクステントなので、
@var{thunk}内から@code{with-port-locking}の外で捕捉された
継続を呼んだ場合、ロックは解放されます。その後、@var{thunk}内で
捕捉された継続が呼ばれた場合、再びロックが獲得されます。

@code{with-port-locking}はネスト可能です。ロックは最も外側の
@code{with-port-locking}の期間中有効となります。

この手続きはポート組込みのロック機構を利用します。つまり、ポートアクセスが
競合した場合はbusy waitになるということです。この手続きはあくまで
頻繁なロックによるオーバヘッドを回避するためのものです。
もし本当に競合が予測される場合は明示的に排他制御を行ってください。
@c COMMON
@end defun

@node Common port operations, File ports, Port and threads, Input and output
@subsection Common port operations
@c NODE ポート共通の操作

@defun port? obj
@defunx input-port? obj
@defunx output-port? obj
[R5RS]
@c EN
Returns true if @var{obj} is a port, an input port and an output port,
respectively.  @code{Port?} is not listed in the
R5RS standard procedures, but mentioned in the "Disjointness of Types"
section.
@c JP
@var{obj} がそれぞれポート、入力ポート、出力ポートなら真を返します。
@code{port?}はR5RSの"Standard Procedures"の項には
載っていませんが、"Disjointness of Types"の項に挙げられています。
@c COMMON
@end defun

@defun port-closed? port
@c EN
Returns true if @var{obj} is a port and it is already closed.
A closed port can't be reopened.
@c JP
@var{obj}がポートであり、既に閉じられていた場合に真を返します。
一度閉じたポートは再び開くことはできません。
@c COMMON
@end defun

@defun current-input-port
@defunx current-output-port
[R5RS]
@c EN
Returns the current input port and the current output port, respectively.
@c JP
現在の入力ポートと出力ポートをそれぞれ返します。
@c COMMON
@end defun

@defun current-error-port
@c EN
Returns the current output port.
@c JP
現在のエラーポートを返します。
@c COMMON
@end defun

@defun standard-input-port :optional new-port
@defunx standard-output-port :optional new-port
@defunx standard-error-port :optional new-port
@c EN
Without arguments, returns standard i/o ports at the time the program started.
These ports are the default values
of @code{current-input-port}, @code{current-output-port}
and @code{current-error-port}, respectively.

Passing a port (an input port for @code{standard-input-port}
and an output port for @code{standard-output-port} and
@code{standard-error-port} changes the standard ports, returning
the current value.  Note that changing them from Scheme program usually
has little effect, since @code{current-input-port} etc. are already
initialized by the original values.  Changing standard ports neither
affects low-level C libraries that directly access stdio.
Change them only if you know what you're doing.
@c JP
引数無しで呼ぶと、プログラム開始時点の標準入出力ポートを返します。これらの値が
@code{current-input-port}、@code{current-output-port}、
@code{current-error-port}のデフォルトとなります。

引数にポート(@code{standard-input-port}には入力ポート、
@code{standard-output-port}と@code{standard-error-port}には
出力ポート)を渡すことで、これらの手続きが次回から返すポートを変えることができます。
引数ありで呼ばれた場合、これらの手続きは変更前の、現在の値を返します。
Schemeプログラムからこれらの値を変更する必要はほとんどないでしょう。
というのも、これらの値は通常は@code{current-input-port}などを初期化する際にだけ
使われるからです。また、低レベルのCライブラリが参照している標準入出力を
これらの手続きで置き換えることもできません。
どうしても必要がある場合にだけ変更を考えてください。
@c COMMON
@end defun

@defun with-input-from-port port thunk
@defunx with-output-to-port port thunk
@defunx with-error-to-port port thunk
@c EN
Calls @var{thunk}.  During evaluation of thunk, the current input port, current
output port and current error port are set to @var{port}, respectively.
@c JP
それぞれ入力、出力、エラーポートを@var{port}にセットした状態で@var{thunk}を呼び出します。
@c COMMON
@end defun

@defun with-ports iport oport eport thunk
@c EN
Does the above three functions at once.
Calls @var{thunk} while the current input, output, and error ports are
set to @var{iport}, @var{oport}, and @var{eport}, respectively.
You may pass @code{#f} to any port argument(s) if you don't need
to alter the port(s).
@c JP
上の3つの動作を同時に行う手続きです。
入力、出力、エラーの各ポートをそれぞれ@var{iport}, @var{oport}, @var{eport}に
セットして@var{thunk}を呼び出します。変更する必要がないポートの引数には
@code{#f}を渡すことができます。
@c COMMON
@end defun


@defun close-input-port port
@defunx close-output-port port
[R5RS]
@c EN
Closes input and output @var{port}, respectively
@c JP
それぞれ、入力ポートと出力ポートを閉じます。
@c COMMON
@end defun

@defun port-type port
@c EN
Returns the type of @var{port} in one of the symbols @code{file}, 
@code{string} or @code{proc}.
@c JP
@var{port}のタイプを、シンボル@code{file}、@code{string}、@code{proc}の
いずれかで返します。
@c COMMON
@end defun

@defun port-name port
@c EN
Returns the name of @var{port}.  If the port is associated to a file,
it is the name of the file.   Otherwise, it is some description of the port.
@c JP
@var{port}の名前を返します。ポートがファイルに関連付けられている場合は、ポートの名前は
ファイル名です。そうでない場合、ポートを説明する文字列が返されます。
@c COMMON
@end defun

@defun port-buffering port
@defunx {(setter port-buffering)} port buffering-mode
@c EN
If @var{port} is type of file port (i.e. @code{(port-type @var{port})}
returns @code{file}), these procedures gets and sets the port's
buffering mode.  For input ports, the port buffering mode may be
either one of @code{:full}, @code{:modest} or @code{:none}.
For output ports, @code{port-buffering}, it may be
one of @code{:full}, @code{:line} or @code{:none}.
@xref{File ports}, for explanation of those modes.

If @code{port-buffering} is applied to ports other than file ports,
it returns @code{#f}.  If the setter of port-buffering is
applied to ports other than file ports, it signals an error.
@c JP
ファイルポート(@code{(port-type @var{port})}が@code{file}を返すもの)
に対して、そのバッファリングモードを読みだし、もしくは変更します。
入力ポートではバッファリングモードは
@code{:full}、 @code{:modest}、@code{:none}のいずれかです。
出力ポートでは
@code{:full}、 @code{:line}、@code{:none}のいずれかです。
バッファリングモードの詳細な説明は、@ref{File ports} を参照してください。

@code{port-buffering}がファイルポート以外のポートに対して呼ばれた場合は
@code{#f}を返します。@code{port-buffering}のsetterが
ファイルポート以外のポートに対して呼ばれた場合はエラーとなります。
@c COMMON
@end defun

@defun port-current-line port
@c EN
Returns the current line count of @var{port}.  This information is
only available on file-based port, and as long as you're doing
sequential character I/O on it.  Otherwise, this returns -1.
@c JP
@var{port}の現在の行番号を返します。行番号は、ファイルに関連付けられたポートで
かつシーケンシャルなキャラクタI/Oを行っている場合のみ有効です。それ以外の場合は
-1を返します。
@c COMMON
@end defun

@defun port-file-number port
@c EN
Returns an integer file descriptor, if the @var{port} is associated
to the system file I/O.  Returns @code{#f} otherwise.
@c JP
@var{port}がファイルに関連付けられている場合、そのファイルディスクリプタ番号を
返します。それ以外の場合は@code{#f}を返します。
@c COMMON
@end defun

@defun port-seek port offset :optional whence
@c EN
If the given @var{port} allows random access, this procedure sets
the read/write pointer of the @var{port} according to the given @var{offset}
and @var{whence}, then returns the updated offset (number of bytes
from the beginning of the data).  If @var{port} is not random-accessible,
@code{#f} is returned.  In the current version, file ports and
input string ports are fully random-accessible.  You can only query
the current byte offset of output string ports.
@c JP
@var{port}がランダムアクセス可能なポートの場合、
この手続きは@var{port}のread/writeポインタを@var{offset}と@var{whence}の値によって
設定し、新たなread/writeポインタの値(データの先頭からのバイトオフセット)を
返します。@var{port}がランダムアクセス可能でない場合は@code{#f}が返されます。
現在のバージョンでは、ファイルポートおよび入力文字列ポートがランダムアクセス可能です。
出力文字列ポートは現在のポインタの値を問い合わせる動作だけが可能です。
@c COMMON

@c EN
Note that port position is represented by byte count, not character count.
@c JP
ポートのポインタはバイト数で表現され、文字数とは異なることに注意して下さい。
@c COMMON

@c EN
It is allowed to seek after the data if @var{port} is an output
file port.  See POSIX lseek(2) document for details of the behavior.
For input file port and input string port, you can't seek after the data.
@c JP
@var{port}が出力ファイルポートの場合は、データの終端を超えた位置までseek
することが可能です。その場合の動作はPOSIXのlseek(2)に準じます。
入力ファイルポートや入力文字列ポートではデータの終端以降にseekすることはできません。
@c COMMON

@c EN
The @var{whence} argument must be a small integer that represents
from where @var{offset} should be counted.   The following constant
values are defined.
@c JP
@var{whence}引数は、@var{offset}の基準を指定する小さな整数です。
以下の定数が定義されています。
@c COMMON

@table @code
@item SEEK_SET
@c EN
@var{Offset} represents the byte count from the beginning of the data.
This is the default behavior when @var{whence} is omitted.
@c JP
@var{offset}はデータ先頭からのバイト数を指定します。
@var{whence}が省略された場合のデフォルトの動作です。
@c COMMON

@item SEEK_CUR
@c EN
@var{Offset} represents the byte count relative to the current read/write
pointer.  If you pass 0 to @var{offset}, you can get the current
port position without changing it.
@c JP
@var{offset}は現在のread/writeポインタからの相対バイト数を指定します。
@var{offset}が0であれば、ポインタを動かさずに現在のポート位置を知ることができます。
@c COMMON

@item SEEK_END
@c EN
@var{Offset} represents the byte count relative to the end of the data.
@c JP
@var{offset}はデータの終端からの相対バイト数を指定します。
@c COMMON
@end table
@end defun

@defun port-tell port
@c EN
Returns the current read/write pointer of @var{port} in byte count,
if @var{port} is random-accessible.   Returns @code{#f} otherwise.
This is equivalent to the following call:
@c JP
@var{port}の現在のread/writeポインタの値をバイト数で返します。
@var{port}がランダムアクセス可能でない場合は@code{#f}が返されます。
これは以下の呼び出しと等価です。
@c COMMON
@example
(port-seek @var{port} 0 SEEK_CUR)
@end example
@end defun

@c EN
@emph{Note on the names}:  @code{Port-seek} is called
@code{seek}, @code{file-position} or @code{input-port-position}/
@code{output-port-position} on some implementations.
@code{Port-tell} is called @code{tell}, @code{ftell} or
@code{set-file-position!}.   Some implementations have
@code{port-position} for different functionality.
CommonLisp has @code{file-position}, but it is not suitable
for us since @var{port} need not be a file port.  @code{Seek} and
@code{tell} reflects POSIX name, and with Gauche naming convention
we could use @code{sys-seek} and @code{sys-tell}; however, @var{port}
deals with higher level of abstraction than system calls, so I dropped
those names, and adopted new names.
@c JP
@emph{名前に関するメモ}: @code{port-seek}は他の処理系で
@code{seek}、@code{file-position}、@code{input-port-position}/
@code{output-port-position}等と呼ばれています。
@code{port-tell}は@code{tell}、@code{ftell}、@code{set-file-position!}等と
呼ばれています。いくつかの処理系は@code{port-position}という手続きを
持っていますが、@code{port-seek}とは別の機能を実現しています。
@code{file-position}はCommonLisp由来の名前ですが、
fileポート以外のものも扱うため採用しませんでした。
また、@code{seek}と@code{tell}はPOSIXの名前由来であり、
Gaucheの名前付け規則を使って@code{sys-seek}と@code{sys-tell}としても
よさそうですが、portの操作はシステムコールレベルよりも抽象度が高いため
これも採用しませんでした。結局、新しい名前を採用することにしました。
@c COMMON

@defun copy-port src dst :key (unit 0) (size #f)
@c EN
Copies data from an input port @var{src} to an output port @var{dst},
until eof is read from @var{src}.
@c JP
@var{src}からEOFまでデータを読みだし、@var{dst}へ書き出します。
@c COMMON

@c EN
The keyword argument @var{unit} may be zero, a positive exact integer,
a symbol @code{byte} or a symbol @code{char}, to specify the unit
of copying.  If it is an integer, a buffer of the size
(in case of zero, a system default size) is used to copy,
using block I/O.  Generally it is the fastest if you copy
between normal files.   If @var{unit} is a symbol @code{byte},
the copying is done byte by byte, using C-verson of @code{read-byte}
and @code{write-byte}.  If @var{unit} is a symbol @code{char},
the copying is done character by character, using C-version of
@code{read-char} and @code{write-char}.
@c JP
キーワード引数@var{unit}は0以上の整数か、シンボル@code{byte}もしくは@code{char}
でなければなりません。これはデータをコピーする単位を指定します。
整数ならば、その大きさ(0の場合はシステム規定の大きさ)のバッファが確保され、
ブロックI/Oを使って転送が行われます。通常のファイルをコピーする場合などはこれが
速いでしょう。もし@var{unit}がシンボル@code{byte}であれば、バイト毎
に読みだし／書き込みが行われます。@var{unit}がシンボル@code{char}であれば、
キャラクタ毎に読みだし／書き込みが行われます。
@c COMMON

@c EN
If nonnegative integer is given to the keyword argument @var{size},
it specifies the maximum amount of data to be copied.  If @var{unit}
is a symbol @code{char}, @var{size} specifies the number of characters.
Otherwise, @var{size} specifies the number of bytes.
@c JP
キーワード引数@var{size}に非負の整数が与えられた場合、それはコピーされるデータの
最大量を指定します。@var{unit}がシンボル@code{char}の場合は@var{size}は
コピーされる文字数を、そうでない場合はバイト数を指定します。
@c COMMON
@end defun

@node File ports, String ports, Common port operations, Input and output
@subsection File ports
@c NODE ファイルポート

@defun open-input-file filename :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx open-output-file filename :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R5RS+]
@c EN
Opens a file @var{filename} for input or output, and
returns an input or output port associated with it, respectively.

The keyword arguments specify precise behavior.
@c JP
ファイル@var{filename}を入力または出力用にオープンし、
入力ポートまたは出力ポートを作成して返します。

キーワード引数により、動作を細かく指定できます。
@c COMMON

@table @code
@item :if-exists
@c EN
This keyword argument can be specified only for @code{open-output-file}, and
specifies the action when the @var{filename} already exists.
One of the following value can be given.
@c JP
このキーワード引数は@code{open-output-file}のみに指定でき、
@var{filename}が既に存在した場合の動作を指定します。次の値のいずれかを与えることができます。
@c COMMON
@table @code
@item :supersede
@c EN
The existing file is truncated.  This is the default behavior.
@c JP
既存のファイルが長さ0に縮められます。これが既定の動作です。
@c COMMON
@item :append
@c EN
The output data will be appended to the existing file.
@c JP
既存のファイルにこれから書き出す内容が追加されます。
@c COMMON
@item :overwrite
@c EN
The output data will overwrite the existing content.
If the output data is shorter than the existing file, the rest of
existing file remains.
@c JP
既存のファイルにこれから書き出す内容が上書きされます。
書き出されるデータが既存のファイルのデータよりも短い場合、
残りの部分はそのまま残されます。
@c COMMON
@item :error
@c EN
An error is signalled.
@c JP
エラーが報告されます。
@c COMMON
@item #f
@c EN
No action is taken, and the function returns @code{#f}.
@c JP
何もせず、@code{#f}を返します。
@c COMMON
@end table

@item :if-does-not-exist
@c EN
This keyword argument specifies the action when @var{filename} does not exist.
@c JP
このキーワード引数は@var{filename}が存在しない場合の動作を指定します。
@c COMMON
@table @code
@item :error
@c EN
An error is signalled.  This is the default behavior of
@code{open-input-file}.
@c JP
エラーを報告します。これが@code{open-input-file}の既定の動作です。
@c COMMON
@item :create
@c EN
A file is created.  This is the default behavior of @code{open-output-file}.
The check of file existence and creation is done atomically; you can
exclusively create the file by specifying @code{:error} or @code{#f} to
@var{if-exists}, along this option.
You can't specify this value for @code{open-input-file}.
@c JP
ファイルが作成されます。これが@code{open-output-file}の既定の動作です。
ファイルの存在のチェックと作成はアトミックに行われます。
このオプションに加え、@var{if-exists}オプションに@code{:error}か@code{#f}を
指定することで、排他的にファイルを作成することができます。
@code{open-input-file}に対してはこの値を指定することはできません。
@c COMMON
@item #f
@c EN
No action is taken, and the function returns @code{#f}.
@c JP
何もせず、@code{#f}を返します。
@c COMMON
@end table

@item :buffering
@c EN
This argument specifies the buffering mode.  The following values are
allowed.
The port's buffering mode can be get/set by @code{port-buffering}.
(@xref{Common port operations}).
@c JP
この引数はバッファリングモードを指定します。以下の値が設定できます。
ポートのバッファリングモードは手続き@code{port-buffering}
(@ref{Common port operations}参照)によって
読みだし/変更可能です。
@c COMMON
@table @code
@item :full
@c EN
Buffer the data as much as possible.  This is the default mode.
@c JP
出来る限りデータをバッファリングします。これがデフォルトのモードです。
@c COMMON
@item :none
@c EN
No buffering is done.  Every time the data is written (to an output port)
or read (from an input port), the underlying system call is used.
Process's standard error port is opened in this mode by default.
@c JP
バッファリングを行いません。出力ポートにデータが書き出されるか、
入力ポートからデータが読み込まれる度に、下位にあるシステムコールが呼ばれます。
プロセスの標準エラーポートはこのモードでオープンされています。
@c COMMON
@item :line
@c EN
This is valid only for output ports.  The written data is buffered, but
the buffer is flushed whenever a newline character is written.
This is suitable for interactive output port.  Process's standard
output port is opened in this mode by default.
(Note that this differs from the line buffering mode of C stdio, which
flushes the buffer as well when input is requested from the same file
descriptor.)
@c JP
このモードは出力ポートにのみ有効です。書き出されたデータはバッファに
貯められますが、改行文字が書かれたらフラッシュされます。
このモードは対話的な出力ポートなどに便利です。
プロセスの標準出力ポートはこのモードでオープンされています。
(これは、Cのstdioライブラリの「ラインバッファリング」とちょっと違うことに
注意してください。stdioでは同じファイルディスクリプタから入力が行われる時も
バッファはフラッシュされますが、Gaucheではそうはなりません)。
@c COMMON
@item :modest
@c EN
This is valid only for input ports.  This is almost the same as the mode
@code{:full}, except that @code{read-block} may return less data
than requested if the requested amount of data is not immediately available.
(In the @code{:full} mode, @code{read-block} waits the entire data to be
read).   This is suitable for the port connected to a pipe or network.
@c JP
このモードは入力ポートにのみ有効です。ほとんど@code{:full}バッファリングモードと
同じですが、@code{read-block}はポートに要求されたデータより少ないデータしか
無かった場合、要求された量がたまるまで待つのではなく、今あるデータだけを
返します。このモードはポートがパイプやネットワークに接続されている場合に
便利です。
@c COMMON
@end table

@item :element-type
@c EN
This argument specifies the type of the file.
@c JP
この引数はファイルのタイプを指定します。
@c COMMON
@table @code
@item :character
@c EN
The file is opened in "character" (or "text") mode.
@c JP
ファイルはキャラクタモード(テキストモード)でオープンされます。
@c COMMON
@item :binary
@c EN
The file is opened in "binary" mode.
@c JP
ファイルはバイナリモードでオープンされます。
@c COMMON
@end table
@c EN
@emph{In the current version, this argument is ignored and all files
are opened in binary mode.  It doesn't make difference in the Unix platforms.}
@c JP
@emph{現在のバージョンでは、この引数は無視され、全てのファイルはバイナリモードで
オープンされます。いずれにせよUnixプラットフォームでは違いはありません。}
@c COMMON

@item :encoding
@c EN
This argument specifies character encoding of the file.   The argument
must be a string or a symbol that names a character encoding scheme (CES).
For @code{open-input-file}, it can be a wildcard CES (e.g. @code{*jp})
to guess the file's encoding heuristically
(@xref{Autodetecting the encoding scheme}).

If this argument is given, Gauche automatically loads 
@code{gauche.charconv} module and converts the input/output characters
as you read to or write from the port.   
See @ref{Supported character encoding schemes}, for the details of
character encoding schemes.
@c JP
この引数はファイルの文字エンコーディングを指定します。引数は文字列かシンボルで、
文字エンコーディングスキーム(CES)の名前でなければなりません。
@code{open-input-file}では、ここにワイルドカードCES (例: @code{*jp}) を
渡して、入力ファイルのエンコーディングを推測させることもできます
(@ref{Autodetecting the encoding scheme}参照)。

この引数が与えられた場合、Gaucheは自動的に@code{gauche.charconv}モジュールを
ロードし、ポートの入出力時に文字コード変換を行います。
CESについて詳しくは@ref{Supported character encoding schemes}を参照してください。
@c COMMON

@item :conversion-buffer-size
@c EN
This argument may be used with the @var{encoding} argument to specify
the buffer size of character encoding conversion.  It is passed as
a @var{buffer-size} argument of the conversion port constructors
(@xref{Conversion ports}).

Usually you don't need to give this argument; but if you need to guess
the input file encoding, larger buffer size may work better since guessing
routine can have more data before deciding the encoding.
@c JP
この引数は、文字エンコーディング変換に使うバッファサイズを指定するために
@var{encoding}引数と共に使うことができます。渡された値はそのまま
文字コード変換ポートのコンストラクタの@var{buffer-size}引数に渡されます
(@ref{Conversion ports}参照)。

この引数を指定する必要は滅多にありませんが、入力ファイルの文字エンコーディングを
推測しなければならない場合、大きめのバッファサイズの方が精度が上がります。
推測ルーチンがより多くのデータを見て文字エンコーディングを決定できるからです。
@c COMMON
@end table

@c EN
By combination of @var{if-exists} and @var{if-does-not-exist} flags,
you can implement various actions:
@example
(open-output-file "foo" :if-exists :error)
 @result{} ;@r{opens "foo" exclusively, or error}

(open-output-file "foo" :if-exists #f)
 @result{} ;@r{opens "foo" exclusively, or returns} #f

(open-output-file "foo" :if-exists :append
                        :if-does-not-exist :error)
 @result{} ;@r{opens "foo" for append only if it already exists}
@end example
@c JP
@var{if-exists}と@var{if-does-not-exist}フラグの組合せにより、
色々な動作を実現できます。
@example
(open-output-file "foo" :if-exists :error)
 @result{} ;@r{"foo"を排他的にオープンするかエラーを報告する}

(open-output-file "foo" :if-exists #f)
 @result{} ;@r{"foo"を排他的にオープンするか}#f@r{を返す}

(open-output-file "foo" :if-exists :append
                        :if-does-not-exist :error)
 @result{} ;@r{"foo"が既に存在する場合に限り、それを追加モードでオープン}
@end example
@c COMMON

@c EN
To check the existence of a file without opening it,
use @code{sys-access} or @code{file-exists?} (@xref{File stats}).
@c JP
ファイルをオープンせずにその存在をチェックするには、
@code{sys-access}か@code{file-exists?}を使って下さい (@ref{File stats}参照)。
@c COMMON

@c EN
Note for portability: Some Scheme implementations (e.g. STk) allows
you to specify a command to @var{filename} and reads from, or
writes to, the subprocess standard input/output.  Some other scripting
languages (e.g. Perl) have similar features.  In Gauche,
@code{open-input-file} and @code{open-output-file} strictly operates
on files (what the underlying OS thinks as files).
However, you can use ``process ports'' to invoke
other command in a subprocess and to communicate it.
@xref{Process ports}, for details.
@c JP
移植性に関する註：Schemeシステムによっては、@var{filename}のところに
シェルコマンドを指定して、サブプロセスの標準入出力と通信できるようにするものが
あります。他のスクリプティング言語(例：Perl)にも同様の機能があります。
Gaucheでは、@code{open-input-file}と@code{open-output-file}は
あくまでファイル (OSがファイルとして扱うもの) のみに対して使えます。
サブプロセスと通信するためには、「プロセスポート」という機能が提供されています。
@ref{Process ports}を参照して下さい。
@c COMMON
@end defun

@defun call-with-input-file string proc :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx call-with-output-file string proc :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R5RS]
@c EN
Opens a file specified by @var{string} for input/output,
and call @var{proc} with one argument, the file port.  When @var{proc}
returns, or an error is signalled from @var{proc} that is not captured
within @var{proc}, the file is closed.
@c JP
@var{string}で示されるファイルを入力または出力用にオープンし、
作成されたポートを引数として手続き@var{proc}を呼び出します。
@var{proc}が正常終了するか、@var{proc}内で捕捉されないエラーが起きた場合に
ファイルはクローズされます。
@c COMMON

@c EN
The keyword arguments have the same meanings of
@code{open-input-file} and @code{open-output-file}'s.  Note that
if you specify @code{#f} to @var{if-exists} and/or @var{if-does-not-exist},
@var{proc} may receive @code{#f} instead of a port object when
the file is not opened.
@c JP
キーワード引数は
@code{open-input-file}及び@code{open-output-file}のものと同じ意味を持ちます。
@var{if-exists}や@var{if-does-not-exist}に@code{#f}を指定した場合、
ファイルがオープンされなかった場合は@var{proc}にポートではなく@code{#f}が渡される
ことに注意して下さい。
@c COMMON

@c EN
Returns the value(s) @code{proc} returned.
@c JP
@var{proc}が返す値を返します。
@c COMMON
@end defun

@defun with-input-from-file string thunk :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx with-output-to-file string thunk :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R5RS]
@c EN
Opens a file specified by @var{string} for input or output
and makes the opened port as the current input or output port,
then calls @var{thunk}.  The file is closed when @var{thunk}
returns or an error is signalled from @var{thunk} that is not
captured within @var{thunk}.

Returns the value(s) @code{thunk} returns.

The keyword arguments have the same
meanings of @code{open-input-file} and @code{open-output-file}'s,
except that when @code{#f} is given to @var{if-exists} and
@var{if-does-not-exist} and the opening port is failed,
@var{thunk} isn't called at all and @code{#f} is returned
as the result of @code{with-input-from-file} and
@code{with-output-to-file}.
@c JP
@var{string}で示されるファイルを入力または出力用にオープンし、オープンされた
ポートを現在の入力または出力ポートに設定して、@var{thunk}を呼び出します。
@var{thunk}が戻るか、@var{thunk}内で捕捉されないエラーが生じた際にファイルは閉じられます。

@var{thunk}が返す値を返します。

キーワード引数は
@code{open-input-file}及び@code{open-output-file}のものと同じ意味を持ちます。
但し@var{if-exists}や@var{if-does-not-exist}に@code{#f}が指定され、
ファイルがオープンできなかった場合は、@var{thunk}は呼ばれずに
直ちに@code{#f}が返されます。
@c COMMON
@end defun

@c EN
@emph{Notes on semantics of closing file ports:}
R5RS states, in the description of @code{call-with-input-file} et al., 
that @emph{"If @emph{proc} does not return, then the port will
not be closed automatically unless it is possible
to prove that the port will never again be used for read or write
operation."}
@c JP
@emph{ポートを閉じるセマンティクスについて:} 
R5RSは@code{call-with-input-file}等の説明において、次のように述べています。
「@emph{procが戻って来なかった場合、今後ポートが読み書きに一切使われないことが
証明できない限りは、ポートは自動的には閉じられない}」。
@c COMMON

@c EN
Gauche's implementation slightly misses this criteria; the mere fact
that an uncaptured error is thrown in @var{proc} does not prove
the port will never be used.  Nevertheless, it is very difficult
to think the situation that you can do meaningful operation on
the port after such an error is signalled; you'd have no idea
what kind of state the port is in.  In practical programs, you
should capture error explicitly inside @var{proc} if you still want
to do some meaningful operation with the port.
@c JP
Gaucheの実装は若干この条件には反しています。捕捉されないエラーが@var{proc}から
発せられたというだけでは、そのポートが今後一切使われないかどうかはわかりません。
しかし実際には、そのようなエラーが発せられた後でポートに対して意味のある操作をするのは
非現実的です。ポートがどのような状態にあるかわからないわけですから。
現実的なプログラムでは、ポートに対して意味のある操作をしつづけたいのなら、
@var{proc}の中で明示的にエラーをハンドルすべきでしょう。
@c COMMON

@c EN
Note that if a continuation captured outside @code{call-with-input-file}
et al. is invoked inside @var{proc}, the port is not closed.
It is possible that the control returns later into the @var{proc},
if a continuation is captured in it (e.g. coroutines).
The low-level exceptions (@xref{Handling exceptions})
also doesn't ensure closing the port.
@c JP
@code{call-with-input-file}の外で捕捉された継続を@var{proc}内で呼んだ場合には
ポートは閉じられないことに注意して下さい。後で@var{proc}へと制御が戻ってくるかも
しれないからです (コルーチン等)。また、
低レベルの例外メカニズム(@ref{Handling exceptions}
参照)を利用した場合、エラー時にポートを閉じるのはプログラマの責任になります。
@c COMMON


@defun open-input-fd-port fd :key buffering name owner?
@defunx open-output-fd-port fd :key buffering name owner?
@c EN
Creates and returns an input or output port on top of the given
file descriptor.  @var{Buffering} specifies the buffering mode
as described in @code{open-input-file} entry above; the default
is @code{:full}.  @var{Name} is used for the created port's name
and returned by @code{port-name}.  A boolean flag @code{owner?}
specifies whether @var{fd} should be closed when the port is closed.
@c JP
与えられたファイルディスクリプタにアクセスする入力または出力ポートを
作成して返します。@var{buffering} は@code{open-input-file} の項で
説明されたポートのバッファリングモードを指定します。デフォルトは@code{:full}です。
@var{name}は@code{port-name}によって返されるポートの名前を指定します。
@var{owner?} は、このポートを閉じた時に@var{fd}もクローズすべきかどうかを
指定するブーリアン値です。
@c COMMON
@end defun

@defun port-fd-dup! toport fromport
@c EN
Interface to the system call @code{dup2(2)}.
Atomically closes the file descriptor associated to @var{toport},
creates a copy of the file descriptor associated to @var{fromport}, 
and sets the new file descriptor to @var{toport}.
Both @var{toport} and @var{fromport} must be file ports.
Before the original file descriptor of @var{toport} is closed,
any buffered output (when @var{toport} is an output port) is flushed,
and any buffered input (when @var{toport} is an input port) is discarded.

`Copy' means that, even the two file descriptors differ in their values,
they both point to the same system's open file table entry.  For example
they share the current file position; after @var{port-fd-dup!}, 
if you call @code{port-seek} on @var{fromport}, the change is also visible
from @var{toport}, and vice versa.  Note that this 'sharing' is in the
system-level; if either @var{toport} or @var{fromport} is buffered,
the buffered contents are not shared.

This procedure is mainly intended for programs that needs to control 
open file descriptos explicitly; e.g. a daemon process would want to redirect
its I/O to a harmless device such as @file{/dev/null}, and a shell process
would want to set up file descriptors before executing the child process.
@c JP
システムの@code{dup2(2)}のインタフェースです。
アトミックに@var{toport}のファイルディスクリプタをクローズし、@var{fromport}の
ファイルディスクリプタを複製したものを@var{toport}に設定します。
@var{toport}、@var{fromport}はいずれもファイルポートでなければなりません。

ファイルディスクリプタが「複製」されると、ふたつのディスクリプタ番号が異なっていても
それらはシステムのオープンファイルテーブルの同じエントリを指します。
例えば、現在の(システムレベルでの)ファイル上の読み書き位置は共有されます。
@code{port-fd-dup!}の後で、@code{port-seek}を@var{fromport}に
対して呼び出せば、その変更は@var{toport}の読み書き位置にも影響を与えるでしょうし、
その逆もまたあります。ただし、共有されるのはシステムレベルの情報のみで、
@var{toport}や@var{fromport}がバッファリングされている場合、バッファの内容は
共有されません。

この手続きは、主にファイルディスクリプタを明示的に制御する必要のあるプログラム
のために用意されています。例えばデーモンプロセスがその入出力を@file{/dev/null}などの
無難なデバイスに切り替えたり、シェルプロセスが子プロセスを@code{exec}する前に
そのファイルディスクリプタをセットアップしたりするような場合です。
@c COMMON
@end defun

@node String ports, Coding-aware ports, File ports, Input and output
@subsection String ports
@c NODE 文字列ポート

@c EN
String ports are the ports that you can read from or write to
memory.
@c JP
文字列ポートは、メモリ上のデータと関連付けられたポートです。
@c COMMON

@defun open-input-string string
[SRFI-6]
@c EN
Creates an input string port that has the content @var{string}.
This is a more efficient way to access a string in order
rather than using @code{string-ref} with incremental index.

@example
(define p (open-input-string "foo x"))
(read p) @result{} foo
(read-char p) @result{} #\space
(read-char p) @result{} #\x
(read-char p) @result{} #<eof>
(read-char p) @result{} #<eof>
@end example
@c JP
@var{string}を内容とする入力文字列ポートを作って返します。
文字列に逐次的にアクセスする場合、インデックスをインクリメントしながら
@code{string-ref}を呼び出すより効率の良い方法です。
@example
(define p (open-input-string "文字 列"))
(read p) @result{} 文字
(read-char p) @result{} #\space
(read-char p) @result{} #\列
(read-char p) @result{} #<eof>
(read-char p) @result{} #<eof>
@end example
@c COMMON
@end defun

@defun get-remaining-input-string port
@c EN
@var{Port} must be an input string port.
Returns the remaining content of the input port.
The internal pointer of @var{port} isn't moved, so the
subsequent read from @var{port} isn't affected.
If @var{port} has already reached to EOF, a null string is returned.
@c JP
@var{port}は入力文字列ポートでなければなりません。
入力ポートに残っている文字列を返します。
@var{port}の内部ポインタは動かされないので、@var{port}に対するreadは
影響を受けません。@var{port}が既にEOFに達していた場合は、空文字列が返されます。
@c COMMON

@example
(define p (open-input-string "abc\ndef"))
(read-line p)                  @result{} "abc"
(get-remaining-input-string p) @result{} "def"
(read-char p)                  @result{} #\d
(read-line p)                  @result{} "ef"
(get-remaining-input-string p) @result{} ""
@end example
@end defun


@defun open-output-string
[SRFI-6]
@c EN
Creates an output string port.   Anything written to the
port is accumulated in the buffer, and can be obtained
as a string by @code{get-output-string}.
This is a far more efficient way to construct a string
sequentially than pre-allocate a string and fill it with
@code{string-set!}.
@c JP
出力文字列ポートを作成して返します。このポートに書き出された文字列は
内部のバッファにたくわえられ、@code{get-output-string} で取り出すことが
できます。
これは、順番に文字列を構成する方法として、あらかじめ文字列をアロケートして
@code{string-set!}で埋めて行くよりもずっと効率の良い方法です。
@c COMMON
@end defun

@defun get-output-string port
[SRFI-6]
@c EN
Takes an output string port @code{port} and returns a string
that has been accumulated to @code{port} so far.
If a byte data has been written to the port, this function
re-scans the buffer to see if it can consist a complete string;
if not, an incomplete string is returned.
@c JP
出力文字列ポート@code{port}を取り、それまでそのポートに蓄積された
文字列を返します。バイトデータがそのポートに書き出されていた場合、
この手続きはまず内部バッファをスキャンし、結果が完全な文字列で表現できるかどうかを
調べます。もし表現できなければ、不完全な文字列が返されます。
@c COMMON

@c EN
This doesn't affect the @var{port}'s operation, so you can keep
accumulating content to @var{port} after calling @code{get-output-string}.
@c JP
これは@var{port}の操作には影響をあたえません。@code{get-ouptut-string}を
呼んだ後でも、@var{port}に内容を蓄積しつづけることができます。
@c COMMON
@end defun

@defun call-with-input-string string proc
@defunx call-with-output-string proc
@defunx with-input-from-string string thunk
@defunx with-output-to-string thunk
@c EN
These utility functions are trivially defined as follows.
The interface is parallel to the file port version.
@c JP
これらのユーティリティ関数は次に定義されるような動作をします。
インタフェースはファイルポートを扱う類似の関数と揃えてあります。
@c COMMON
@example
(define (call-with-output-string proc)
  (let ((out (open-output-string)))
    (proc out)
    (get-output-string out)))

(define (call-with-input-string str proc)
  (let ((in (open-input-string str)))
    (proc in)))

(define (with-output-to-string thunk)
  (let ((out (open-output-string)))
    (with-output-to-port out thunk)
    (get-output-string out)))

(define (with-input-from-string str thunk)
  (with-input-from-port (open-input-string str) thunk))
@end example
@end defun

@defun call-with-string-io str proc
@defunx with-string-io str thunk
@example
(define (call-with-string-io str proc)
  (let ((out (open-output-string))
        (in  (open-input-string str)))
    (proc in out)
    (get-output-string out)))

(define (with-string-io str thunk)
  (with-output-to-string
    (lambda ()
      (with-input-from-string str
        thunk))))
@end example
@end defun

@defun write-to-string obj :optional writer
@defunx read-from-string string :optional start end
@c EN
These convenience functions cover common idioms using string ports.
@example
(write-to-string obj writer)
  @equiv{}
  (with-output-to-string (lambda () (writer obj)))

(read-from-string string)
  @equiv{}
  (with-input-from-string string read)
@end example
The default value of @var{writer} is the procedure @code{write}.
The default values of @var{start} and @var{end} is 0 and
the length of @var{string}.

Portability note: Common Lisp has these functions, with
different optional arguments.
STk has @code{read-from-string} without optional argument.
@c JP
文字列ポートを使う定型句をユーティリティ関数にしました。
@example
(write-to-string obj writer)
  @equiv{}
  (with-output-to-string (lambda () (writer obj)))

(read-from-string string)
  @equiv{}
  (with-input-from-string string read)
@end example
@var{writer}の既定値は@code{write}です。@var{start}, @var{end}は
省略されればそれぞれ0と文字列の長さになります。

移植性への註：Common Lispに同名の関数があります。必須引数の動作は同じですが、
省略可能な引数は異なります。
STkには@code{read-from-string}がありますが、省略可能な引数は取りません。
@c COMMON
@end defun

@node Coding-aware ports, Input, String ports, Input and output
@subsection Coding-aware ports
@c NODE コーディング認識ポート

@c EN
A coding-aware port is a special type of procedural input port that
is used by @code{load} to read a program source.  The port recognizes
the magic comment to specify the character encoding of the
program source, such as @code{;; -*- coding: utf-8 -*-}, and makes
an appropriate character encoding conversion.  
See @ref{Multibyte scripts} for the details of coding magic comment.
@c JP
コーディング認識ポートは特殊な手続的入力ポートで、@code{load}が
プログラムソースコードを読む際に使われています。このポートは
@code{;; -*- coding: utf-8 -*-}のような、プログラムソースの
文字エンコーディングを指定する特殊なコメントを認識し、適切な
文字エンコーディング変換を行います。
特殊なコメントでソースの文字エンコーディングを指定することについては、
@ref{Multibyte scripts}を参照して下さい。
@c COMMON

@defun open-coding-aware-port iport
@c EN
Takes an input port and returns an input coding aware port,
which basically just pass through the data from @var{iport} to
its reader.  However, if a magic comment appears within the
first two lines of data from @var{iport}, the coding aware port
applies the necessary character encoding conversion to the rest of the
data as they are read.
@c JP
入力ポートを引数としてとりコーディング認識入力ポートを返します。
基本的には @var{iport} からの入力データをリーダにわたしているだけです。
しかし、@var{iport} からの入力データの最初の2行以内に、特別な呪文コメント
が現れた場合、コーディング認識ポートは、その後に読み込まれるデータについて
必要な文字エンコーディング変換を行います。
@c COMMON

@c EN
The passed port, @var{iport}, is "owned" by the created coding-aware
port.  That is, when the coding-aware port is closed, @var{iport} is
also closed.  The content read from @var{iport} is buffered in the
coding-aware port, so other code shouldn't read from @var{iport}.
@c JP
引数として渡されたポート、@var{iport} は生成されたコーディング認識
ポートによって所有されます。つまり、コーディング認識ポートがクローズ
されると、@var{iport} もクローズされます。@var{iport} から読み込まれた
内容はコーディング認識ポート内でバッファリングさます、したがって、
別のコードで @var{iport} から読み出しを行うべきではありません。
@c COMMON

@c EN
By default, Gauche's @code{load} uses a coding aware port to read
the program source, so that the coding magic comment works for
the Gauche source programs (see @ref{Loading Scheme file}).
However, since the mechanism itself
is independent from @code{load}, you can use this port for
other purposes; it is particularly useful to write a function
that processes Scheme source programs which may have the coding
magic comment.
@c JP
デフォルトでは、Gauche の @code{load} はプログラムソースを読むのに
コーディング認識ポートを使います。したがって、文字エンコーディングを
示す特別な呪文コメントは、Gauche のソースプログラムでは有効になります
(@ref{Loading Scheme file}参照)。ただし、この機構自身は @code{load} とは
独立しており、このポートを別の目的で利用できます。特にコーディングの
呪文コメントがある Scheme のソースプログラムを処理する関数を書くときに
便利です。
@c COMMON
@end defun

@node Input, Output, Coding-aware ports, Input and output
@subsection Input 
@c NODE 入力

@c EN
For the input-related procedures, the optional @var{iport} argument must be
an input port, and when omitted, the current input port is assumed.
@c JP
入力に関する手続きで、省略可能な引数@var{iport}は入力ポートでなければなりません。
省略された場合が現在の入力ポートが使われます。
@c COMMON

@menu
* Reading data::                
* Read-time constructor::       
* Input utility functions::     
@end menu

@node Reading data, Read-time constructor, Input, Input
@subsubsection Reading data
@c NODE データの読み込み

@defun read :optional iport
[R5RS]
@c EN
Reads an S-expression from @var{iport} and returns it.
Gauche recognizes the lexical structure specified in R5RS,
and some additional lexical structures listed in @ref{Lexical structure}.

If @var{iport} has already reached to the end of file,
an eof object is returned.

The procedure reads up to the last character that consists the S-expression,
and leaves the rest in the port.  It's not like CommonLisp's @code{read},
which consumes whitespaces after S-expression by default.
@c JP
@var{iport}からS式をひとつ読み込んで返します。
GaucheはR5RSに定義されている構文要素に加え、@ref{Lexical structure}に
定義されている拡張構文要素を認識します。

@var{iport}が既にEOFに達していた場合は、EOFオブジェクトが返されます。

この手続きはS式を構成する最後の文字までを読み、その後の文字はポートに
残します。これは、S式に続く空白文字も読み込むCommonLispの@code{read}の
振る舞いとは異なります。
@c COMMON
@end defun

@defun read-with-shared-structure :optional iport
@defunx read/ss :optional iport
[SRFI-38]
@c EN
These procedures are defined in srfi-38 to recognize shared substructure
notation (@code{#n=}, @code{#n#}).   Gauche's builtin @code{read} recognizes
the srfi-38 notation, so these are just synonyms to @code{read}; these
are only provided for srfi-38 compatibility.
@c JP
これらの手続きは、SRFI-38 で定義されていて、共有構造を表す記法
(@code{#n=}, @code{#n#})を認識できます。Gauche の組み込み @code{read} は
この SRFI-38 の記法を認識します。それゆえ、これらの手続きは、@code{read}
と同じで、SRFI-38 との互換性のために用意されています。
@c COMMON
@end defun

@defun read-char :optional iport
[R5RS]
@c EN
Reads one character from @var{iport} and returns it.
If @var{iport} has already 
reached to the end, returns an eof object.
If the byte stream in @var{iport} doesn't consist a valid character,
the behavior is undefined.  (In future, a port will have a option
to deal with invalid characters).
@c JP
@var{iport}から1文字読み込んで返します。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@var{iport}にあるバイトストリームが正しい文字を構成しない場合、
ふるまいは未定義です。(将来はポート側に、不正な文字に対する対応を決める
オプションを設ける予定です)。
@c COMMON
@end defun

@defun peek-char :optional iport
[R5RS]
@c EN
Reads one character in @var{iport} and returns it, keeping the character
in the @var{port}.
If the byte stream in @var{iport} doesn't consist a valid character,
the behavior is undefined.  (In future, a port will have a option
to deal with invalid characters).
@c JP
@var{iport}から1文字読み込んで返します。文字はそのまま@var{iport}に留まります。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@var{iport}にあるバイトストリームが正しい文字を構成しない場合、
ふるまいは未定義です。(将来はポート側に、不正な文字に対する対応を決める
オプションを設ける予定です)。
@c COMMON
@end defun

@defun read-byte :optional iport
@c EN
Reads one byte from an input port @var{iport}, and returns it as an integer
in the range between 0 and 255.
If @var{iport} has already reached EOF, an eof object is returned.
@c JP
入力ポート@var{iport}から1バイト読み込み、0から255までの整数値として返します。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@c COMMON
@end defun

@defun peek-byte :optional iport
@c EN
Peeks one byte at the head of an input port @var{iport}, and returns 
it as an integer in the range between 0 and 255.
If @var{iport} has already reached EOF, an eof object is returned.
@c JP
入力ポート@var{iport}の先頭の1バイトを見て、それを0から255までの整数値として返します。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@c COMMON
@end defun

@defun read-line :optional iport allow-byte-string?
@c EN
Reads one line (a sequence of characters terminated by newline or EOF)
and returns a string.  The terminating newline is not included.
This function recognizes popular line terminators (LF only, CRLF, and CR only).
If @var{iport} has already reached EOF, an eof object is returned.
@c JP
入力ポートから、行末もしくはEOFまで読み込んで文字列として返します。
よく使われる行末 (LF only, CRLF, and CR only) を認識します。
戻り値にはこれらの行末文字は含まれません。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@c COMMON

@c EN
If a byte sequence is read from @var{iport}
which doesn't constitute a valid character in the native encoding,
@code{read-line} signals an error by default.  However, if a true value
is given to the argument @var{allow-byte-string?}, 
@code{read-line} returns a byte string (incomplete string) in such case,
without reporting an error.
It is particularly useful if you read from a source whose
character encoding is not yet known; for example, to read XML document,
you need to check the first line to see if there is a charset parameter
so that you can then use an appropriate character conversion port.
@c JP
@var{iport}から、内部文字エンコーディングでは文字を構成し得ないバイトシーケンスが
読まれた場合、デフォルトでは@code{read-line}はエラーを通知します。
しかし、省略可能な引数@var{allow-byte-string?}に真の値が与えられた場合は、
@code{read-line}はエラーを通知せず、かわりにバイト文字列 (不完全な文字列) を
返します。この動作は、特に文字エンコーディングが不明なソースから読み込む際に
便利です。例えばXMLドキュメントを読み込む際、最初の行のcharsetパラメータを
チェックしてから適切な文字エンコーディング変換ポートを使うといった用途などです。
@c COMMON
@end defun

@defun read-block nbytes :optional iport
@c EN
Reads @var{nbytes} bytes from @var{iport}, and returns an incomplete
string consisted by those bytes.  The size of returned string may
shorter than @var{nbytes} when @var{iport} doesn't have enough bytes
to fill.  
If @var{nbytes} is zero, a null string is always returned.

If @var{iport} has already reached EOF, an eof object is returned.
@c JP
@var{nbytes}バイトのデータを@var{iport}から読み込み、
不完全な文字列として返します。@var{iport}に十分なデータが無い場合、
返される文字列は@var{nbytes}より短いかもしれません。
@var{nbytes}が0の場合は、常に空文字列が返されます。

@var{iport}が既にEOFに達していた場合はEOFオブジェクトが返されます。
@c COMMON

@c EN
If @var{iport} is a file port, the behavior of @code{read-block}
differs by the buffering mode of the port (@xref{File ports}, for
the detail explanation of buffering modes).
@c JP
@var{iport}がファイルポートだった場合、@code{read-block}は
ポートのバッファリングモードによってふるまいが異なります
(バッファリングモードの詳細については@ref{File ports}を参照して下さい)。
@c COMMON
@itemize @bullet
@item
@c EN
If the buffering mode is @code{:full}, @code{read-block} waits 
until @var{nbytes} data is read, except it reads EOF.
@c JP
バッファリングモードが@code{:full}の場合、@code{read-block}は
EOFを読まない限り、@var{nbytes}のデータが読まれるまで待ちます。
@c COMMON
@item
@c EN
If the buffering mode is @code{:modest} or @code{:none}, @code{read-block}
returns shorter string than @var{nbytes} even if it doesn't reach EOF,
but the entire data is not available immediately.
@c JP
バッファリングモードが@code{:modest}か@code{:none}である場合、
@code{read-block}はEOFが読まれなくても、すぐに読めるデータが@var{nbytes}よりも
少ない場合はそのデータだけを返します。
@c COMMON
@end itemize

@c EN
@code{Read-block} returns newly allocated string every time.
If you want to avoid allocation and read the data into a pre-allocated
fixed-length buffer, you can use @code{read-block!}
in @code{gauche.uvector} module (@xref{Uvector block I/O}).
It uses a uniform vector as the buffer.
@c JP
@code{read-block}は呼ばれるたびに新たな文字列をアロケートします。
アロケーションを避け、あらかじめ用意された固定長のバッファにデータを読み込みたい
場合は、@code{gauche.uvector}モジュールの@code{read-block!}
を使って下さい (@ref{Uvector block I/O}参照)。
@code{Read-block!}はuniform vectorをバッファとして用います。
@c COMMON

@c EN
If you want to write a chunk of bytes to a port,
you can use either @code{display} if the data is in string,
or @code{write-block} in @code{gauche.uvector} (@xref{Uvector block I/O})
if the data is in uniform vector.
@c JP
データブロックをポートに書き出すには、データが文字列で表現されている
場合は単純に@code{display}が使えます。データがuniform vectorで表現されている
場合は@code{gauche.uvector}モジュールの@code{write-block}が
使えます (@ref{Uvector block I/O}参照)。
@c COMMON
@end defun

@defun eof-object
[R6RS]
@c EN
Returns an EOF object.
@c JP
EOFオブジェクトを返します。
@c COMMON
@end defun


@defun eof-object? obj
[R5RS]
@c EN
Returns true if @var{obj} is an EOF object.
@c JP
@var{obj}がEOFオブジェクトなら@code{#t}を返します。
@c COMMON
@end defun

@defun char-ready? port
[R5RS]
@c EN
If a character is ready to be read from @var{port}, returns @code{#t}.

For now, this procedure actually checks only if next @emph{byte} is
immediately available from @var{port}.   If the next byte is a part of
a multibyte character, the attempt to read the whole character may block,
even if @code{char-ready?} returns @code{#t} on the port.
(It is unlikely to happen in usual situation, but theoretically it can.
If you concern, use @code{read-block} to read the input as a byte
sequence, then use input string port to read characters.)
@c JP
@var{port}から文字が読み出せる状態ならば@code{#t}を返します。

今のところ、この手続きは@var{port}から少なくとも1バイト読み出せる状態なら@code{#t}
を返します。そのバイトがマルチバイト文字を構成する場合、@code{char-ready?}を返した
ポートから文字全てを読み込もうとすると、ブロックする可能性があります。
(通常の使用状況ではそのようなことは起きないでしょうが、理論的には起こり得ます。
慎重を期したい場合は@code{read-block}でバイトシーケンスとして読み込んだ後、
入力文字列ポート等を使って文字毎に読むようにして下さい。)
@c COMMON
@end defun

@defun byte-ready? port
If one byte (octet) is ready to be read from @var{port}, returns
@code{#t}.
@end defun

@node Read-time constructor, Input utility functions, Reading data, Input
@subsubsection Read-time constructor
@c NODE 読み込み時コンストラクタ

@c EN
Read-time constructor, defined in SRFI-10, provides an easy way
to create an external representation of user-defined structures.
@c JP
SRFI-10で定義されている読み込み時コンストラクタは、ユーザ定義の構造の
外部表現を作るための簡単な方法を提供します。
@c COMMON

@deftp {Reader Syntax} @code{#,(@var{tag} @var{arg} @dots{})}
@c EN
[SRFI-10]
Gauche maintains a global table that associates a @var{tag} (symbol)
to @emph{a constructor procedure}.
@c JP
[SRFI-10]
Gaucheは@var{tag} (シンボル)を@emph{コンストラクタ手続き}に関連付ける
グローバルなテーブルを管理しています。
@c COMMON

@c EN
When the reader encounters this syntax, it reads @var{arg} @dots{},
finds a reader constructor associated with @var{tag}, and
calls the constructor with @var{arg} @dots{} as arguments,
then inserts the value returned by the constructor as the result
of reading the syntax.
@c JP
リーダーがこの構文に出会ったとき、@var{arg} @dots{}を読み込み、
@var{tag}に関連付けられた読み込みコンストラクタを探し、
@var{arg} @dots{}を引数としてそのコンストラクタを呼び出し、
その構文を読み込んだ結果としてそのコンストラクタが返した値を挿入します。
@c COMMON

@c EN
Note that this syntax is processed inside the reader---the
evaluator doesn't see any of @var{arg}s, but only sees the object
the reader returns.
@c JP
この構文はリーダー内部で処理されることに注意して下さい。評価器は
@var{arg}を見ず、リーダーが返したオブジェクトしか見ません。
@c COMMON
@end deftp

@defun define-reader-ctor @var{tag} @var{procedure}
@c EN
[SRFI-10]
Associates a reader constructor @var{procedure} with @var{tag}.

Examples:
@c JP
[SRFI-10]
読み込みコンストラクタ@var{procedure}を@var{tag}に関連付けます。

例:
@c COMMON
@example
(define-reader-ctor 'pi (lambda () (* (atan 1) 4)))

#,(pi) @result{} 3.141592653589793

'(#,(pi)) @result{} (3.141592653589793)

(define-reader-ctor 'hash
  (lambda (type . pairs)
    (let ((tab (make-hash-table type)))
      (for-each (lambda (pair)
                  (hash-table-put! tab (car pair) (cdr pair)))
                pairs)
      tab)))

(define table
 #,(hash eq? (foo . bar) (duh . dah) (bum . bom)))

table @result{} #<hash-table eq? 0x80f9398>
(hash-table-get table 'duh) @result{} dah
@end example

@c EN
Combined with @code{write-object} method (@xref{Output}),
it is easy to make a user-defined class written in the form
it can be read back:
@c JP
@code{write-object}メソッド(@ref{Output}参照)と組み合わせて、
読み戻ることが可能なフォームで書かれたユーザ定義のクラスを
作ることが簡単になります。
@c COMMON

@example
(define-class <point> ()
  ((x :init-value 0 :init-keyword :x)
   (y :init-value 0 :init-keyword :y)))

(define-method write-object ((p <point>) out)
  (format out "#,(<point> ~s ~s)" (ref p 'x) (ref p 'y)))

(define-reader-ctor '<point>
  (lambda (x y) (make <point> :x x :y y)))
@end example

@end defun

@c EN
@emph{NOTE:} The extent of the effect of @code{define-reader-ctor}
is not specified in SRFI-10, and might pose a compatibility problem
among implementations that support SRFI-10.
(In fact, the very existence of @code{define-reader-ctor} is
up to an implementation choice.)
@c JP
@emph{注意:} @code{define-reader-ctor}の効果の範囲はSRFI-10には
規定されておらず、SRFI-10をサポートする実装においても互換性の問題を
起こすことがあるかもしれません。
(実際に、@code{define-reader-ctor}の存在そのものが実装の選択に
任されています。)
@c COMMON

@c EN
In Gauche, at least for the time being, @code{define-reader-ctor}
take effects as soon as the form is compiled and evaluated.  Since
Gauche compiles and evaluates each toplevel form in order, @var{tag}
specified in @code{define-reader-ctor} can be used immediately after that.
However, it doesn't work if the call of @code{define-reader-ctor} and
the use of @var{tag} is enclosed in a @code{begin} form, for the entire
@code{begin} form is compiled at once before being evaluated.
@c JP
Gaucheでは、現時点においては、@code{define-reader-ctor}はそのフォームが
コンパイルされ評価された時点で効力を持ちます。
Gaucheはトップレベルのフォームを順番にコンパイル・評価するので、
@code{define-reader-ctor}で指定された@var{tag}は、その指定の直後から
使えます。
しかし、@code{define-reader-ctor}の呼び出しと@var{tag}の使用が
@code{begin}フォームで囲まれている場合は、@code{begin}フォーム全体は
評価される前に一度にコンパイルされるため、うまく動作しません。
@c COMMON

@c EN
Other implementations may require to read the entire file before
making its @code{define-reader-ctor} call effective.  If so, it
effectively prevents one from using @code{define-reader-ctor} and
the defined @var{tag} in the same file.   It is desirable to separate
the call of @code{define-reader-ctor} and the use of @var{tag}
in the different files if possible.
@c JP
他の実装では、@code{define-reader-ctor}の呼び出しが効力を持つようにする
前にファイル全体を読み込むことを要求するかも知れません。
その場合は、@code{define-reader-ctor}と定義された@var{tag}の使用を
同じファイルに置く事は実質的に不可能です。
可能ならば、@code{define-reader-ctor}の呼び出しと、@var{tag}の使用は
異なるファイルに分離されることが望まれます。
@c COMMON

@c EN
Another issue about the current @code{define-reader-ctor} is that
it modifies the global table of Gauche system, hence it is not modular.
The code written by different people might use the same tags,
and yield an unexpected result.   In future versions, Gauche may
have some way to encapsulate the scope of @var{tag}, although
the author doesn't have clear idea yet.
@c JP
現在の@code{define-reader-ctor}に関するもう1つの問題は、それが
Gaucheシステムのグローバルテーブルを変更してしまうことで、それゆえに
モジュール性が良くありません。
複数人によって書かれたコードは同じタグを使っているかも知れず、
期待されない結果を引き起こすかも知れません。
作者にはまだ明確なアイデアがありませんが、将来のバージョンでは、
Gaucheには@var{tag}のスコープをカプセル化する方法が導入されるかも
しれません。
@c COMMON


@node Input utility functions,  , Read-time constructor, Input
@subsubsection Input utility functions
@c NODE 入力ユーティリティ手続き

@defun port->string port
@defunx port->list reader port
@defunx port->string-list port
@defunx port->sexp-list port
@c EN
Generally useful input procedures.  The API is taken from
scsh and STk.
@c JP
便利な入力手続きです。APIはScshとSTkから取りました。
@c COMMON

@c EN
@code{port->string} reads @var{port}
until EOF and returns the accumulated data as a string.
@c JP
@code{port->string}は@var{port}をEOFまで読み込み、
読んだものを文字列として返します。
@c COMMON

@c EN
@code{port->list} applies @var{reader} on @var{port} repeatedly, until
@var{reader} returns an EOF, then returns the list of objects
@var{reader} returned.
@c JP
@code{port->list}は手続き@var{reader}を@var{port}に繰り返し適用し、
結果をリストに蓄積します。@var{reader}がEOFを返したら
蓄積されたリストを返します。
@c COMMON

@c EN
@code{port->string-list} is a @code{port->list} specialized
by @code{read-line}, and 
@code{port->sexp-list} is a @code{port->list} specialized
by @code{read}.
@c JP
@code{port->string-list}は@code{port->list}を
@code{read-line}で特定化したもので、
@code{port->sexp-list}は@code{port->list}を
@code{read}で特定化したものです。
@c COMMON

@c EN
If the input contains an octet sequence that's not form a valid
character in the Gauche's native character encoding,
@code{port->string} and @code{port->string-list} may return
incomplete string(s).
@c JP
もし入力にGaucheの内部エンコーディングにおいて有効な文字をつくらない
バイト列が含まれていた場合、@code{port->string}と@code{port->string-list}
の返り値には不完全な文字列が含まれている可能性があります。
@c COMMON
@end defun

@defun port-fold fn knil reader
@defunx port-fold-right fn knil reader
@defunx port-for-each fn reader
@defunx port-map fn reader
@c EN
Convenient iterators over the input read by @var{reader}.
Basically, @var{reader} is called repeatedly without arguments
and @var{fn} is called for each item it returns, until @var{reader}
returns EOF.   Actually @var{reader} can be any thunk; it doesn't
need to be related to input port.
@c JP
@var{reader}によって読まれる入力に対する便利な繰り返し手続きです。
基本的に、@var{reader}が引数無しでEOFを返すまで繰り返し呼ばれ、
それが返した値に対して@var{fn}が呼ばれます。
@var{reader}はいずれEOFを返す手続きなら、入力ポートと関係している必要はありません。
@c COMMON

@c EN
Suppose @var{reader} returns a series of items
@{X0, X1, @dots{}, Xn@}.
@code{port-fold} returns the following:
@c JP
@var{reader}が要素 @{X0, X1, @dots{}, Xn@} を返したとすると、
@code{port-fold} は次の値を返します。
@c COMMON
@example
(fn Xn (fn Xn-1 @dots{} (fn X0 knil)))
@end example
@c EN
while @var{port-fold-right} returns the following:
@c JP
一方、@var{port-fold-right}は次の値を返します。
@c COMMON
@example
(fn X0 (fn X1 @dots{} (fn Xn knil)))
@end example
@c EN
That is, @code{(port-fold cons '() read)} returns a reverse
list of all the inputs, while @code{(port-fold-right cons '() read)}
returns the same thing as @code{(port->list read port)}.
@c JP
すなわち、@code{(port-fold cons '() read)}は全ての入力の逆リストを
返し、@code{(port-fold-right cons '() read)}は
@code{(port->list read port)}と同じものを返します。
@c COMMON

@c EN
On the other hand, @code{port-for-each} and @code{port-map}
applies @var{fn} to each item.  The former discards the results
@var{fn} returns, while the latter returns a list of results.
@c JP
@code{port-for-each}と@code{port-map}は@var{fn}を読まれた要素に
次々と適用します。前者は@code{fn}の結果を捨てますが、後者は@code{fn}の
結果をリストにして返します。
@c COMMON
@end defun

@node Output,  , Input, Input and output
@subsection Output
@c NODE 出力

@c EN
For the following procedures, the optional @var{port} argument must be
an output port, and when omitted, the current output port is assumed.
@c JP
以下の手続きで、省略可能な引数@var{port}は出力ポートでなければなりません。
省略された場合が現在の出力ポートが使われます。
@c COMMON

@defun write obj :optional port
@defunx display obj :optional port
[R5RS]
@c EN
Produces a printable representation of an object @var{obj} to the output port.
@code{Write} uses object's standard external representation
whenever possible, so that the written output would be
read back by @code{read},
whereas @code{display} produces more human-readable output.

When @code{write} and @code{display} encounter an object of
a user-defined class, they call the generic function @code{write-object}.

These procedures may not stop when @var{obj} contains a cyclic structure.
See @code{write/ss} below.
@c JP
オブジェクト@var{obj}の表示可能な表現を生成し、出力ポートに書き出します。
@code{write}は可能な限り、@var{obj}の標準的な外部表現を使い、
生成された出力が@code{read}で再び読み込めるようにします。
@var{display}はより人間にとって可読性の高い出力を生成します。

@code{write}や@code{display}が表示中にユーザ定義クラスのオブジェクトに
出会った場合は、ジェネリックファンクション@code{write-object}を呼び出します。

@var{obj}が循環する構造を持っていた場合、これらの手続きは停止しないかも
しれません。@code{write/ss}を参照して下さい。
@c COMMON
@end defun

@defun write-with-shared-structure obj :optional port
@defunx write/ss obj :optional port
@defunx write* obj :optional port
[SRFI-38]
@c EN
Produces the output like @code{write}, except that they recognize shared
substructures and/or cyclic structures, and use @code{#n=} and @code{#n#}
syntax to indicate them.
@c JP
@code{write}と同じような出力を生成しますが、これらの手続きはさらに
共有される部分構造や循環構造を認識し、@code{#n=}, @code{#n#}構文を使って
それらを表現します。
@c COMMON

@example
(write/ss 
  (let ((x (list 'a)))
    (list x x)))
 @result{} ;; writes (#0=(a) #0#)

(write/ss 
  (let ((x (list 'a)))
    (set-cdr! x x)
    x))
 @result{} ;; writes #0=(a . #0#)
@end example

@c EN
The @code{read} procedure can recognize this syntax, so when you
read it back, you can get a structure which is isomorphic to
the original one.
@c JP
@code{read}手続きもこの構文を認識するので、読み込めば
もとの構造と同型の構造が得られます。
@c COMMON

@c EN
Three procedures are the same.
Gauche has been used the name @code{write*} for long, which is
taken from STklos.  However, @code{write-with-shared-structure}
and @code{write/ss} have been introduced in srfi-38, so these names will
be more portable.
@c JP
3つの手続きは等価です。
Gaucheは、STklosから取った@code{write*}という名前を長く使ってきましたが、
srfi-38によって@code{write-with-shared-structure}と@code{write/ss}が
定義されました。今後は後者の名前を使った方がポータブルでしょう。
@c COMMON

@c EN
Note: The user-defined @code{write-object} methods work 
transparently for these procedures as well.
@c JP
註: ユーザ定義の@code{write-object}メソッドはこれらの手続きに対して
透過的に動作します。
@c COMMON
@end defun


@defun print expr @dots{}
@c EN
Displays @var{expr}s (using @code{display}) to the current output port,
then writes a newline.
@c JP
@var{expr} @dots{} を@code{display}を使って現在の出力ポートに表示し、
最後に改行を書き出します。
@c COMMON
@end defun

@deffn {Method} write-object (obj <object>) port
@c EN
You can customize how the object is printed out by this method.
@c JP
このメソッドをつかって、オブジェクトをどのように印字するかをカスタマイズ
できます。
@c COMMON
@end deffn

@defun newline :optional port
[R5RS]
@c EN
Writes a newline character to @var{port}
@c JP
@var{port}に改行文字を書き出します。
@c COMMON
@end defun

@defun flush :optional port
@defunx flush-all-ports
@c EN
Output the buffered data in @var{port}, or all ports, respectively.

The function "flush" is called in variety of ways on the various
Scheme implementations: @code{force-output} (Scsh, SCM),
@code{flush-output} (Gambit), or @code{flush-output-port} (Bigloo).
The name @code{flush} is taken from STk and STklos.
@c JP
それぞれ、@var{port}、および全てのポートにバッファされているデータを
全て書き出します。

手続き"flush"はScheme実装によって様々な名前で呼ばれています：
@code{force-output} (Scsh, SCM)、
@code{flush-output} (Gambit)、@code{flush-output-port} (Bigloo) 等。
@code{flush}の名前はSTkとSTklosから取りました。
@c COMMON
@end defun

@defun write-char char :optional port
[R5RS]
@c EN
Write a single character @var{char} to the output port @var{port}.
@c JP
文字@var{char}をポートに出力します。
@c COMMON
@end defun

@defun write-byte byte :optional port
@c EN
Write a byte @var{byte} to the port.
@var{byte} must be an exact integer in range between 0 and 255.
@c JP
出力ポートに1バイトのデータ@var{byte}を書き出します。
@var{byte}は0から255の間の正確な整数でなければなりません。
@c COMMON
@end defun

@defun format port string arg @dots{}
@defunx format string arg @dots{}
[SRFI-28+]
@c EN
Format @var{arg} @dots{} according to @var{string}.
This function is a subset of CommonLisp's @code{format} function,
with a bit of extension.  It is also a superset of SRFi-28,
Basic format strings (@ref{srfi-28,[SRFI-28],SRFI-28}).
@c JP
@var{string} の指示に従い、@var{arg} @dots{}をフォーマットします。
この手続きはCommonLispの@code{format}のサブセットに、Gauche独自の拡張を
加えたものです。また、これはSRFI-28 "Basic format strings" のスーパーセットに
なっています (@ref{srfi-28,[SRFI-28],SRFI-28})。
@c COMMON

@c EN
@var{port} specifies the destination; if it is an output port, the
formatted result is written to it; if it is @code{#t},
the result is written to the current output port;
if it is @code{#f}, the formatted result is returned as a string.
@var{Port} can be omitted, as SRFI-28 @code{format};
it has the same effects as giving @code{#f} to the @var{port}.
@c JP
@var{port}は出力先を指定します。それが出力ポートであれば、フォーマットされた
結果はそのポートに書き出されます。@var{port}が@code{#t}であれば、結果は
現在の出力ポートに書き出されます。@var{port}が@code{#f}であれば、結果は
文字列として@code{format}から返されます。
@var{port}は省略することもできます。その場合は、@code{port}に@code{#f}
を指定したのと同じ動作をします(SRFI-28の@code{format})。
@c COMMON

@c EN
@var{string} is a string that contains format directives.
A format directive is a character sequence begins with tilda, `@code{~}',
and ends with some specific characters.  A format directive takes
the corresponding @var{arg} and formats it.  The rest of string is
copied to the output as is.
@c JP
@var{string}はフォーマット指示子を含んだ文字列です。
フォーマット指示子はチルダ`@code{~}'から始まり、特定の文字で終了する文字の並びで、
それぞれのフォーマット指示子が対応する@var{arg}を取りフォーマットします。
@var{string}内のフォーマット指示子以外の文字列はそのまま出力されます。
@c COMMON

@example
(format #f "the answer is ~s" 42)
  @result{} "the answer is 42"
@end example

@c EN
The format directive can take one or more @var{parameters}, separated
by comma characters.  A parameter may be an integer or a character;
if it is a character, it should be preceded by a quote character.
Parameter can be omitted, in such case the system default value is
used.  The interpretation of the parameters depends on the 
format directive.
@c JP
フォーマット指示子は一つ以上のコンマで区切られたパラメータを取ることもできます。
パラメータは整数か文字です。文字の場合、クオート文字に続けてその文字を置きます。
パラメータが省略された場合は既定値が使われます。パラメータの意味はフォーマット指示子毎に
異なります。
@c COMMON

@c EN
Furthermore, a format directive can take two
additional flags: atmark `@code{@@}' and colon `@code{:}'.  One or
both of them may modify the behavior of the format directive.
Those flags must be placed immediately before the directive
character.
@c JP
さらに、フォーマット指示子は2種類のフラグ、`@code{@@}' と `@code{:}' を
取ることができます。これらの組合せでフォーマットの動作が変わります。フラグは
(もしあれば)パラメータの後、指示子の文字の直前に置かれなければなりません。
@c COMMON

@c EN
If a character `@code{v}' or `@code{V}' is in the place of the
parameter, the value of the parameter is taken from the format's
argument.  The argument must be either an integer, a character, or
@code{#f} (indicating that the parameter is effectively omitted).
@c JP
パラメータの位置に文字 `@code{v}' か `@code{V}' を置くこともできます。
その場合、パラメータの値が引数リストから取られます。対応する引数は整数か
文字、または@code{#f}でなければなりません。@code{#f}の場合はそのパラメータが
省略されたのと同じになります。
@c COMMON

@c EN
Some examples:

@table @code
@item ~10,2s
A format directive @code{~s}, with two parameters, 10 and 2.
@item ~12,,,'*A
A format directive @code{~a}, with 12 for the first parameter and
a character `@code{*}' for the fourth parameter.  The second and
third parameters are omitted.
@item ~10@@d
A format directive @code{~d}, with 10 for the first parameter and
`@code{@@}' flag.
@item ~v,vx
A format directive @code{~x}, whose first and second parameter will
be taken from the arguments.
@end table
@c JP
いくつかの例です。

@table @code
@item ~10,2s
パラメータ10と2を伴う、フォーマット指示子@code{~s}。
@item ~12,,,'*A
第1パラメータに数値12、第4パラメータに文字`@code{*}'を取るフォーマット指示子@code{~a}。
第2と第3のパラメータは省略されています。
@item ~10@@d
フォーマット指示子@code{~d}。パラメータ10と`@code{@@}'フラグがついています。
@item ~v,vx
フォーマット指示子@code{~x}。第1パラメータと第2パラメータは引数リストから取られます。
@end table
@c COMMON

@c EN
The following is a complete list of the supported format directives.
Either upper case or lower case character can be used for the format
directive; usually they have no distinction, except noted.
@c JP
以下にサポートされているフォーマット指示子を示します。フォーマット指示子の文字自体は
大文字であっても小文字であっても構いません。特に断りのない限り両者は同じ動作をします。
@c COMMON

@table @asis
@item @b{~}@var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}@b{A}
@c EN
Ascii output.  The corresponding argument is printed by @code{display}.
If an integer @var{mincol} is given, it specifies the minimum number
of characters to be output; if the formatted result is shorter than
@var{mincol}, a whitespace is padded to the right (i.e. the result
is left justified).
@c JP
ASCII出力。対応する引数が@code{display}を使ってフォーマットされます。
整数が@var{mincol}に与えられた場合、それは出力される最小の文字数を指定します。
引数のフォーマット結果が@var{mincol}より短ければ、空白が右に追加されます(つまり、
左詰めになります)。
@c COMMON

@c EN
The @var{colinc}, @var{minpad} and @var{padchar} parameters
control, if given, further padding.  A character @var{padchar} replaces
the padding character for the whitespace.  If an integer @var{minpad}
is given and greater than 0, at least @var{minpad} padding character
is used, regardless of the resulting width.  If an integer @var{colinc}
is given, the padding character is added (after @var{minpad}) in chunk
of @var{colinc} characters, until the entire width exceeds @var{mincol}.
@c JP
@var{colinc}、@var{minpad}、そして@var{padchar}は更に細かいパディング方法を
指定します。@var{padchar}に文字が与えられた場合、それが空白文字の代わりにパディング文字と
して使われます。@var{minpad}に0以上の整数が与えられた場合、少なくともその数だけの
パディング文字が追加されます。@var{colinc}が指定された場合、
追加されるパディング文字の数が@var{colinc}の倍数に調整されます。
@c COMMON

@c EN
If atmark-flag is given, the format result is right justified, i.e.
padding is added to the left.
@c JP
アトマーク `@code{@@}' フラグが与えられた場合、結果は右詰めになります。
@c COMMON

@c EN
The @var{maxcol} parameter, if given, limits the maximum number of characters
to be written.  If the length of formatted string exceeds
@var{maxcol}, only @var{maxcol} characters are written.
If colon-flag is given as well and the length of formatted string
exceeds @var{maxcol}, @var{maxcol} - 4 characters are written and
a string ``@code{ ...}'' is attached after it.
@c JP
@var{maxcol}パラメータは与えられていれば書かれる文字数の上限を指定します。
フォーマット後の文字列の長さが@var{maxcol}を超えた場合、@var{maxcol}文字だけが
書かれます。コロン `@code{:}' フラグが同時に与えられていれば、
@var{maxcol} - 4 文字が書かれた後、文字列``@code{ ...}''が書かれます。
@c COMMON

@example
(format #f "|~a|" "oops")
  @result{} "|oops|"
(format #f "|~10a|" "oops")
  @result{} "|oops      |"
(format #f "|~10@@a|" "oops")
  @result{} "|      oops|"
(format #f "|~10,,,'*@@a|" "oops")
  @result{} "|******oops|"
@c JP
(format #f "|~10,,,'☆a|" "oops")
  @result{} "|oops☆☆☆☆☆☆|"
@c COMMON

(format #f "|~,,,,10a|" '(abc def ghi jkl))
  @result{} "|(abc def gh|" 
(format #f "|~,,,,10:a|" '(abc def ghi jkl))
  @result{} "|(abc de ...|" 
@end example

@item @b{~}@var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}@b{S}
@c EN
S-expression output.  The corresponding argument is printed
by @code{write}.  The semantics of parameters and flags are the same
as @code{~A} directive.
@c JP
S式出力。対応する引数が@code{write}を使ってフォーマットされます。
パラメータの意味は@code{~A}指示子と同じです。
@c COMMON

@example
(format #f "|~s|" "oops")
  @result{} "|\"oops\"|"
(format #f "|~10s|" "oops")
  @result{} "|\"oops\"    |"
(format #f "|~10@@s|" "oops")
  @result{} "|    \"oops\"|"
(format #f "|~10,,,'*@@s|" "oops")
  @result{} "|****\"oops\"|"
@c JP
(format #f "|~10,,,'★s|" "oops")
  @result{} "|\"oops\"★★★★|"
@c COMMON
@end example

@item @b{~}@var{mincol},@var{padchar},@var{commachar},@var{interval}@b{D}
@c EN
Decimal output.  The argument is formatted as an decimal integer.
If the argument is not an integer, all parameters are ignored 
(after processing `@code{v}' parameters) and
it is formatted by @code{~A} directive.
@c JP
10進出力。対応する引数が10進数表記でフォーマットされます。もし引数が数値でなければ、
全てのパラメータは(`@code{v}'パラメータの処理後に)無視され、
引数は@code{~A}でフォーマットされます。
@c COMMON

@c EN
If an integer parameter @var{mincol} is given, it specifies minimum
width of the formatted result; if the result is shorter than it,
@var{padchar} is padded on the left (i.e. the result is right
justified).  The default of @var{padchar} is a whitespace.
@c JP
もし@var{mincol}に整数が与えられたら、それが最小の文字数を指定します。
結果の文字数がそれより少なければ、文字@var{padchar}が左に追加されます(右詰めになります)。
@var{padchar}が省略された場合は空白文字が使われます。
@c COMMON

@example
(format #f "|~d|" 12345)
  @result{} "|12345|"
(format #f "|~10d|" 12345)
  @result{} "|     12345|"
(format #f "|~10,'0d|" 12345)
  @result{} "|0000012345|"
@end example

@c EN
If atmark-flag is given, the sign `@code{+}' is printed for the
positive argument.
@c JP
アトマーク `@code{@@}' フラグが与えられた場合、正の引数に対して `@code{+}' が
先頭につけられます。
@c COMMON

@c EN
If colon-flag is given, every @var{interval}-th digit of
the result is grouped and @var{commachar} is inserted between them.
The default of @var{commachar} is `@code{,}', and the default of
@var{interval} is 3.
@c JP
コロンフラグ `@code{:}' が与えられた場合、結果の文字は@var{interval}文字毎に
まとめられ、間に文字@var{commachar}が挿入されます。デフォルトでは3文字毎にコンマが
挿入されます。
@c COMMON

@example
(format #f "|~:d|" 12345)
  @result{} "|12,345|"
(format #f "|~,,'_,4:d|" -12345678)
  @result{} "|-1234_5678|"
@end example

@item @b{~}@var{mincol},@var{padchar},@var{commachar},@var{interval}@b{B}
@c EN
Binary output.  The argument is formatted as a binary integer.
The semantics of parameters and flags are the same as
the @code{~D} directive.
@c JP
2進出力。対応する引数が2進数の整数としてフォーマットされます。
パラメータの意味は@code{~D}と同じです。
@c COMMON

@item @b{~}@var{mincol},@var{padchar},@var{commachar},@var{interval}@b{O}
@c EN
Octal output.  The argument is formatted as an octal integer.
The semantics of parameters and flags are the same as
the @code{~D} directive.
@c JP
8進出力。対応する引数が8進数の整数としてフォーマットされます。
パラメータの意味は@code{~D}と同じです。
@c COMMON

@item @b{~}@var{mincol},@var{padchar},@var{commachar},@var{interval}@b{X}
@item @b{~}@var{mincol},@var{padchar},@var{commachar},@var{interval}@b{x}
@c EN
Hexadecimal output.
The argument is formatted as a hexadecimal integer.
If `@code{X}' is used, upper case alphabets are used for
the digits larger than 10.  If `@code{x}' is used, lower case
alphabets are used.
The semantics of parameters and flags are the same as
the @code{~D} directive.
@c JP
16進出力。対応する引数が16進数の整数としてフォーマットされます。
フォーマット指示文字に `@code{X}' が与えられた場合は `@code{ABCDEF}' が桁文字として
使われ、 `@code{x}' が与えられた場合は `@code{abcdef}' が桁文字として使われます。
パラメータの意味は@code{~D}と同じです。
@c COMMON

@example
(format #f "~8,'0x" 259847592)
  @result{} "0f7cf5a8"
(format #f "~8,'0X" 259847592)
  @result{} "0F7CF5A8"
@end example

@item @b{~}@var{count}@b{*}
@c EN
Moves the argument counter @var{count} times forward, effectively skips
next @var{count} arguments.  The default value of @var{count} is 1,
hence skip the next argument.  If a colon-flag is given, moves the argument
counter backwards, e.g. @code{~:*} makes the next directive to process
last argument again.  If an atmark-flag is given, @var{count} specifies
absolute position of the arguments, starting from 0.
@c JP
引数のカウンタを@var{count}だけ後方にずらします。つまり、@var{count}個の引数が
無視されることになります。@var{count}のデフォルト値は1です。
コロンフラグが与えられた場合は引数カウンタを前方に動かします。
例えば@code{~:*}は次のディレクティブが直前に使った引数を再び使うようにします。
アトマークフラグが与えられた場合は、@var{count}が引数の絶対位置を示します。
0が最初の引数です。
@c COMMON
@end table

@end defun


@c ----------------------------------------------------------------------
@node Loading Programs, Comparison and sorting, Input and output, Core library
@section Loading Programs
@c NODE プログラムのロード

@menu
* Loading Scheme file::         
* Loading dynamic library::     
* Require and provide::         
* Autoload::                    
* Operations on libraries::     
@end menu

@node Loading Scheme file, Loading dynamic library, Loading Programs, Loading Programs
@subsection Loading Scheme file
@c NODE Schemeファイルのロード

@defun load file :key paths (error-if-not-found #t) environment ignore-coding
[R5RS+]
@c EN
Loads @var{file}, that is, read Scheme expressions in @var{file} and
evaluates them.
An extension ``@code{.scm}'' may be omitted from @var{file}.

If @var{file} doesn't begin with ``/'' or ``./'' or ``../'',
it is searched from the system file search list,
stored in a variable @code{*load-path*}.
Or you can explicitly specify the search path by passing
a list of directory names to the keyword argument @var{paths}.

On success, @code{load} returns @code{#t}.
If the specified file is not found, an error is signalled unless
the keyword argument @var{error-if-not-found} is @code{#f}, in
which case @code{load} returns @code{#f}.

By default, @code{load} uses a coding-aware port 
(@xref{Coding-aware ports}) so that the "@code{coding:}" magic 
comment at the beginning of the source file is effective.
(See @ref{Multibyte scripts}, for the details of
the coding magic comment).  If a true value is given to the
keyword argument @var{ignore-coding}, @code{load} doesn't
create the coding-aware port and directly reads from the
file port.

If a module is given to the keyword argument @var{environment},
@code{load} works as if the given module is selected at the beginning
of the loaded file.

The current module is preserved; even @code{select-module} is
called in @var{file}, the module in which @code{load} is called
is restored afterwards.

If you want to load a library file, it's better to use `@code{use}'
(@xref{Defining and selecting modules}), or `@code{require}' described below.
@xref{Compilation}, for difference between @code{load} and @code{require}.
@c JP
@var{file}をロードします。すなわち、@var{file}に書かれたScheme式を順次読み込んで
評価します。@var{file}の拡張子 (``@code{.scm}'') は省略できます。

@var{file}が ``/'', ``./'' または ``../'' で始まっていない場合は、
システムファイルサーチパス (変数@code{*load-path*} に格納されています)
の中から該当ファイルが探されます。あるいは、キーワード引数@var{paths}にディレクトリ名の
リストを渡すことによりサーチパスを指定することもできます。

ロードに成功した場合は@code{#t}が返されます。
指定ファイルがみつからない場合はエラーとなりますが、もしキーワード引数
@code{error-if-not-found}に@code{#f}が与えられていれば単に@code{load}から
@code{#f}が返されます。

デフォルトでは、@code{load}はコーディング認識ポート(@ref{Coding-aware ports}参照)を
使ってソースファイルを読み込むので、ファイル先頭の"@code{coding:}" コメントによる
文字エンコーディング指定が有効になります。
(codingコメントについては@ref{Multibyte scripts}を参照)。
但し、キーワード引数@var{ignore-coding}に真の値が渡された場合、
@code{load}はcoding-aware portを作成せず、直接ファイルポートから
ソースを読み込みます。

キーワード引数@var{environment}にモジュールが渡された場合は、
あたかもそのモジュールがファイルの先頭でselectされたかのように
@code{load}されます。

カレントモジュールは保存されます。つまり、@var{file}中で@code{select-module}によって
カレントモジュールを変更しても、@code{load}が終わったら@code{load}を読んだ時点の
モジュールに戻ります。

ライブラリファイルをロードする場合は、`@code{use}' (@ref{Defining and selecting modules}参照) を
使うか、下に説明する`@code{require}' を使う方が良いでしょう。
@code{load}と@code{require}の違いについては@ref{Compilation}を参照してください。
@c COMMON
@end defun

@defvar *load-path*
@c EN
Keeps a list of directories that are searched by @code{load} and
@code{require}.

If you want to add other directories to the search path,
do not modify this variable directly; use @code{add-load-path},
described below, instead.
@c JP
@code{load}と@code{require}がファイルを探すディレクトリのリストを保持しています。

もしサーチパスにディレクトリを追加したい場合は、この変数を直接変更せずに、下に説明する
@code{add-load-path}を用いて下さい。
@c COMMON
@end defvar

@defspec add-load-path path :optional (afterp #f)
@c EN
Adds a path @var{path} to the library load path list.
If a true value is given to @var{afterp}, @var{path} is added
after the existing paths; otherwise, @var{path} is added before the
existing paths.

Use this form instead of changing @code{*load-path*} directly.
This form is a special form and recognized by the compiler;
if you change @code{*load-path*}, it is in effect at run time,
and that may be too late for ``use'' or ``require''.

Furthermore,
@code{add-load-path} looks for the architecture dependent directories
under the specified path and if it exists, sets up the internal
path list for dynamic loading correctly.   Suppose you have
your Scheme module in @code{/home/yours/lib}, and that requires 
a dynamic loadable library.  You can put the library under
@code{/home/yours/lib/@var{ARCH}/}, where @var{ARCH} is
the value @code{(gauche-architecture)} returns (@xref{Environment Inquiry}).
Then you can have compiled libraries for multiple platforms and
Gauche can still find the right library.
@c JP
パス@var{path}をライブラリロードパスのリストに加えます。
@var{afterp}に真の値が与えられていれば@var{path}は既存のリストの末尾に
追加されます。そうでなければ@var{path}は既存のリストの先頭に追加されます。

ロードパスを変更したい場合、@code{*load-path*}を直接替えずにこのフォームを
使って下さい。このフォームはコンパイル時に解釈されるのに対し、@code{*load-path*}を
書き換えるコードは実行時に解釈されます。``@code{use}'' や ``@code{require}'' は
コンパイル時のロードパスを使うので、@code{*load-path*}への変更は反映されないかもしれません。

更に、@code{add-load-path}は@var{path}の下にアーキテクチャ依存のディレクトリが
ないかどうかを探し、あればそれを内部の共有ライブラリサーチパスに追加します。
例えばあなたが自分のSchemeモジュールを@code{/home/yours/lib}に入れていて、
それが共有ライブラリを必要としていたとします。手続き@code{gauche-architecture}
(@ref{Environment Inquiry}参照)が返す値を@var{ARCH}として、
共有ライブラリを@code{/home/yours/lib/@var{ARCH}/}に置いておくと、
共有ライブラリはそこからロードされます。この方法を取ると、複数のプラットフォーム用に
別々にコンパイルされた共有ライブラリを管理することができます。
@c COMMON
@end defspec

@defun load-from-port port
@c EN
Reads Scheme expressions from an input port @var{port} and evaluates
them, until EOF is read.

Note that unless you pass a coding-aware port to @var{port},
the "@code{coding:}" magic comment won't be handled.
@c JP
入力ポート@var{port}から、EOFを読むまで繰り返しScheme式を読み込み評価します。

@var{port}にコーディング認識ポートを渡さない限り、"@code{coding:}"コメント
による文字コード変換は行われないことに注意して下さい。
@c COMMON
@end defun

@defun current-load-port
@defunx current-load-path
@defunx current-load-history
@defunx current-load-next
@c EN
These procedures allows you to query the current context of loading.
They returns the following values when called inside a file being loaded:
@table @code
@item current-load-port
Returns the port object from which this form is being loaded.
@item current-load-path
Returns the pathname of the file from which this form is being loaded.
Note that this may return @code{#f} if the source of @code{load} is
not a file.
@item current-load-history
Returns a list of pairs of a port and a line number (integer),
representing the nesting of loads.  Suppose you load
@file{foo.scm}, and from its line 7 it loads @file{bar.scm}, 
and from its line 18 it loads @file{baz.scm}.   If you call
@code{current-load-history} in the file @file{baz.scm}, you'll get
@example
((#<port "foo.scm"> . 7) (#<port "bar.scm"> . 18))
@end example
@item current-load-next
Returns a list of remaining directories to be searched
at the time this file is found.   Suppose the @code{*load-path*}
is @code{("." "../lib" "/home/gauche/lib" "/share/gauche/lib")}
and you load @file{foo.scm}, which happens to be in @file{../lib/}.
Then, inside @file{foo.scm}, @code{current-load-next} returns:
@example
("/home/gauche/lib" "/share/gauche/lib")
@end example
@end table

When called outside of @code{load}, these procedures returns
@code{#f}, @code{#f}, @code{()} and @code{()}, respectively.
@c JP
これらの手続きによって、現在のロードのコンテクストを知ることができます。
ロードされているファイルの中でこれらの手続きを呼ぶと、次のような値が返されます。
@table @code
@item current-load-port
現在のフォームがロードされている入力ポート。
@item current-load-path
現在のフォームがロードされているファイル。
ロードのソースがファイルでない場合、この値は@code{#f}。
@item current-load-history
入力ポートと行番号のペアのリストで、ロードのネスティングを示したもの。
例えばあなたが@file{foo.scm}をロードし、そのファイルの7行目で
@file{bar.scm}がロードされ、そのファイルの18行目で@file{baz.scm}が
ロードされたとします。@code{current-load-history}を@file{baz.scm}中で
呼ぶと、それは次のような値を返します。
@example
((#<port "foo.scm"> . 7) (#<port "bar.scm"> . 18))
@end example
@item current-load-next
現在のファイルがロードされた時点での、ファイルサーチパスの残りを返します。
例えば @code{*load-path*} が
@code{("." "../lib" "/home/gauche/lib" "/share/gauche/lib")}で、
あなたが@file{foo.scm}をロードしたところ、それが@file{../lib/}中に見つかったと
しましょう。このとき、@file{foo.scm}中で@code{current-load-next}を呼べば
@example
("/home/gauche/lib" "/share/gauche/lib")
@end example
が返されます。
@end table

@code{load}されていない状態で呼ばれた時は、これらの手続きはそれぞれ@code{#f}、
@code{#f}、@code{()}、@code{()}を返します。
@c COMMON
@end defun


@node Loading dynamic library, Require and provide, Loading Scheme file, Loading Programs
@subsection Load dynamic library
@c NODE ダイナミックライブラリのロード

@defun dynamic-load file :key init-function export-symbols
@c EN
Loads and links a dynamic loadable library (shared library) @var{file}.
@var{File} shouldn't contain the suffix (``.so'' on most systems);
@code{dynamic-load} adds it, for it may differ among platforms.

The keyword argument @var{init-function} specifies the initialization
function name of the library in a string.  By default, if the file
basename (without extension) is ``foo'', the initialization function
name is ``Scm_Init_foo''.

The keyword argument @var{export-symbols} tells whether the dynamic loader
that the external symbols in @var{file} should be appended to
the symbol table of the running process.  (Note: I'm talking about
C function and variable names, not Scheme symbols).
By default, the symbols
in @var{file} are not visible from other dynamically loaded libraries.
If you want to allow other dynamically loaded libraries to call
C function in your library, you should give @code{#t} to this 
argument.  It sets @code{RTLD_GLOBAL} flag for @code{dlopen()}.

Usually a dynamic loadable library is provided with wrapping Scheme
module, so the user doesn't have to call this function directly.

There's no way to unload the loaded libraries.
@c JP
ダイナミックローダブルライブラリ(共有ライブラリ)@var{file}をロードしてリンクします。
@var{file}にはサフィックス(``.so'' 等) を含めないで下さい。システムによって
サフィックスは異なるため、@code{dynamic-load}がそれを追加します。

キーワード引数@var{init-function}は共有ライブラリ中の初期化関数の名前を
指定します。デフォルトでは、サフィックスを除くファイル名が ``foo'' の場合、
初期化関数名は ``Scm_Init_foo'' となります。

キーワード引数@var{export-symbols}は、ロードされるライブラリ中の外部シンボルを
プロセスのシンボルテーブルに追加すべきかどうかを指定します。(註：ここでの「シンボル」
とはCの関数名や変数名のことで、Schemeのシンボルのことではありません)。
デフォルトでは共有ライブラリの外部シンボルはプロセスのシンボルテーブルに追加されず、
それぞれの共有ライブラリは他の共有ライブラリのシンボルを見ることができません。
@var{export-symbols}に真の値を渡すと、フラグ@code{RTLD_GLOBAL}が
@code{dlopen()}に渡されて、その共有ライブラリ中のシンボルがこれからロードされる
共有ライブラリからも見えるようになります。

通常、共有ライブラリはSchemeモジュール中でロードされるので、モジュールユーザが
直接この手続きを呼ぶ必要はほとんどないでしょう。

一度ロードされた共有ライブラリをアンロードすることはできません。
@c COMMON
@end defun


@node Require and provide, Autoload, Loading dynamic library, Loading Programs
@subsection Require and provide
@c NODE requireとprovide

@c EN
@code{Require} and @code{provide} are a traditional Lisp way to ensure
loading a library file only once.  If you require a @emph{feature}
for the first time, a library file that provides it is loaded
and the fact that the @emph{feature} is provided is memorized.
Subsequent request of the same feature doesn't need to load the file.
@c JP
@code{require}と@code{provide}は、Lispでライブラリファイルを一度だけ
読み込むことを保証するための伝統的な方法です。
ある@emph{feature}を最初に@code{require}すると、その機能を提供する
ライブラリファイルがロードされ、その機能が提供されたということが記憶されます。
2回め以降のその@emph{feature}のリクエストではファイルはロードされません。
@c COMMON

@c EN
In Gauche, the @code{use} syntax (@xref{Using modules}) hides
the require mechanism under the hood so you hardly need to see
these forms.  These are provided just in case if you want to
do some non-trivial management of libraries and thus want to
bypass Gauche's standard mechanism.
@c JP
Gaucheでは@code{use}構文 (@ref{Using modules}参照) が
requireのメカニズムをボンネットの下に隠してくれるので、
これらの式を直接目にする必要はほとんどありません。
もしあなたがちょっと変わった方式でライブラリを構成したくて、したがって
Gaucheの標準的なメカニズムをバイパスしたい場合に限り、使うようにしてください。
@c COMMON

@defspec require feature
@c EN
If @var{feature} is not loaded, load it.  @var{Feature} must be a string,
and it is taken as a file name (without suffix) to be loaded.
This loading takes place at compile time.

If you load SLIB module, @code{require} is extended.  @xref{SLIB} for
details.
@c JP
@var{feature}がまだロードされていなければロードします。@var{feature}は文字列で
なければなりません。それがそのまま(サフィックスを除く)ファイル名としてロードパスから
探されます。@code{require}の解釈はコンパイル時に行われます。

SLIBモジュールをロードすると、@code{require}が拡張されます。詳しくは@ref{SLIB}を
参照して下さい。
@c COMMON

@c EN
If the loaded file does not contain @code{provide} form at all,
the @var{feature} is automatically provided, as if
@code{(provide @var{feature})} is called at the end of the loaded
file.  We call this @emph{autoprovide} feature.
@c JP
もしロードされたファイルが@code{provide}フォームを含んでいなかった場合、
あたかもファイルの最後に@code{(provide @var{feature})}があったかのように、
@var{feature}が自動的にprovideされます。これを
@emph{autoprovide}機能と呼んでいます。
@c COMMON
@end defspec

@defun provide feature
@c EN
Adds @var{feature} to the system's provided feature list, so that
the subsequent @code{require} won't load the same file again.
@c JP
@var{feature}をシステムのprovideされたフィーチャーリストに加えます。
以降、@var{feature}が@code{require}されてもファイルはふたたびロードされません。
@c COMMON

@c EN
Because of the autoproviding, i.e. @code{require}
automatically provides the required feature, you hardly need to
use a @code{provide} form explcitily.   There are a couple of scenarios that
you may want to use a @code{provide} form:
@c JP
@code{require}が要求された機能を自動的に@code{provide}されたかのように
扱うAutoprovide機能があるために、@code{provide}を明示的に呼ぶ必要は
ほとんど無いでしょう。@var{provide}を使いたいシチュエーションとしては
次のようなものが考えられます。

@c COMMON

@itemize
@item
@c EN
To provide a feature (or features) that is/are different from
the one that caused loading the file.  

Suppose feature X supesedes feature Y and providing
compatible APIs of Y but with different implementation.
Once @file{X.scm} is loaded, you don't want @file{Y.scm} to be loaded;
so you want to tell the user that @file{X.scm} also provides the feature Y.
Adding @code{(provide "X")} and @code{(provide "Y")} at the end of
@file{X.scm} accomplish that.  (Note: If you add a provide form,
@code{require} no longer autoprovides the feature, so you need
to specify @code{(provide "X")} in @file{X.scm} explicitly to
provide X as well.)

Of course, this doens't prevent users from loading @file{Y.scm} by
specifing @code{(require "Y")} before @code{(require "X")}.
It should be considered just as a workaround in a production
where other solutions are costly, instead of a permanent solution.
@c JP
そのファイルをロードすることになったfeatureとは異なるfeature (複数可) を
provideしたい場合。

例えばfeature Xがfeature Yを置き換えるものだとします。
XはYのAPIを全て提供しますが、実装は異なります。この場合、
@file{X.scm}が一度ロードされたら、@file{Y.scm}をロードしてほしくないと思うでしょう。
@file{X.scm}に @code{(provide "X")} と @code{(provide "Y")} の両方を
書いておくことで、@file{X.scm}がfeature Yもprovideすると明示すれば、それが実現できます。
(注：@code{provide}が呼ばれると、@code{require}のautoprovide機能は
抑制されるため、@file{X.scm}中で@code{(provide "X")}も指定する必要があります。)

もちろんの方法では、ユーザが @code{(require "Y")} を @code{(require "X")}
より先に書いてしまったら@file{Y.scm}はロードされてしまいます。
この方法は、現場において、永久的な解決が高コストになるような場合のとりあえずの
回避処置と考えるべきでしょう。
@c COMMON

@item
@c EN
To provide no features at all.  Passing @code{#f} as @var{feature}
prevents autoproviding by @code{require} without providing any
feature.

This should also be a temporary solution.  One possible scenario is
that you are changing @file{X.scm} very frequently during 
development and you want @code{(require "X")} always causes loading
the file.  Don't forget to remove @code{(provide #f)} when you release
the file, though.  Besides, for interactive reloading, consider
using @code{gauche.reload} (@xref{Reloading modules}) instead.
@c JP
featureを全く@code{provide}しない。
@var{feature}引数に@code{#f}を渡すことで、何のfeatureも@code{provide}することなく
@code{require}によるautoprovidingを抑制できます。

これもまた、何らかの一時的な解決と考えるべきです。たとえば開発中に、
@file{X.scm}を頻繁に変更するために@code{(require "X")}が常に
そのファイルをロードするようにさせたい、といった場合が考えられます。
@file{X.scm}のリリースの前に @code{(provide #f)} を消しておくことを
忘れないように。また、インタラクティブにリロードしたいならば
@code{gauche.reload} (@ref{Reloading modules}参照) を使うことを
おすすめします。
@c COMMON
@end itemize

@end defun

@defun provided? feature
@c EN
Returns @code{#t} if @var{feature} is already provided.
@c JP
@var{feature}が既にprovideされていれば@code{#t}を返します。
@c COMMON
@end defun

@node Autoload, Operations on libraries, Require and provide, Loading Programs
@subsection Autoload

@defmac autoload file/module item @dots{}
@c EN
Sets up @var{item} @dots{} to be autoloaded.
That is, when an @var{item} is referenced for the first time,
@var{file/module} is loaded before the @var{item} is evaluated.
This delays the loading of @var{file/module} until it is needed.
@c JP
@var{item} @dots{} がオートロードされるように設定します。すなわち、
次に@var{item}が参照された時、それが実際に評価される前に@var{file/module}がロード
されるようにします。これによって、必要とされる時まで@var{file/module}のロードを遅らせる
ことができます。
@c COMMON

@c EN
You can specify either a string file name or a symbol module name
to @var{file/module}.  If it is a string, the named file is
loaded.  If it is a symbol, the named module is loaded (using the
same rule as of @code{use}), then the binding of @var{item} in the
@var{file/module} is imported to the module used the autoload
(@xref{Defining and selecting modules}, for details of @code{use}).
@c JP
引数@var{file/module}には、文字列かシンボルを指定できます。文字列の場合は
そのファイルがロードされます。シンボルの場合、その名のモジュールが(@code{use}と
同じルールで)ロードされ、@var{item}が@var{file/module}から
オートロードを呼び出したモジュールへとインポートされます。
(モジュールの@code{use}の詳細については@ref{Defining and selecting modules}を参照して下さい)。
@c COMMON

@c EN
@var{Item} can be either a variable name (symbol), 
or a form @code{(:macro @var{symbol})}.  If it is a variable,
the named file/module is loaded when the variable is
about to be evaluated.  If it is the latter form,
the named file/module is loaded when a form
@code{(@var{symbol} arg @dots{})} is about to be @emph{compiled},
which enables autoloading macros.
@c JP
@var{item}は変数名(シンボル)か、@code{(:macro @var{symbol})}というフォーム
でなければなりません。変数名の場合は、その変数が評価されようとした時に
指定のファイル／モジュールがロードされます。後者のフォームの場合は、
@code{(@var{symbol} arg @dots{})} というフォームがコンパイルされようとした
時に指定のファイル／モジュールがロードされます。後者はマクロのオートロードになります。
@c COMMON

@c EN
@var{file/module} must define @var{symbol} in it, or an error is signalled
when @var{file/module} is autoloaded.
@c JP
@var{symbol}は@var{file/module}の中で定義されなければなりません。
そうでなければロード時にエラーが報告されます。
@c COMMON

@c EN
The following is an example of autoloading procedures.
@c JP
手続きのオートロードの例を示します。
@c COMMON
@example
(autoload "foo" foo0 foo1)
(autoload "bar" bar0 bar1)

(define (foobar x)
  (if (list? x)
      (map bar0 x)
      (foo0)))

@c EN
(foobar '(1 2)) ; @r{"bar" is loaded at this moment}

(foobar #f)     ; @r{"foo" is loaded at this moment}
@c JP
(foobar '(1 2)) ; @r{この時点で "bar" がロードされる}

(foobar #f)     ; @r{この時点で "foo" がロードされる}
@c COMMON
@end example

@c EN
Note that if you set to autoload macro, the file/module is loaded
immediately when such form that uses the macro is compiled,
regardless of the piece of
the code is executed or not.
@c JP
マクロのオートロードを設定した場合、指定のファイルまたはモジュールは、
そのマクロを使っているフォームが実行されるされないにかかわらず、
コンパイラがそのフォームを見た時点でロードされることに注意してください。
@c COMMON
@end defmac

@node Operations on libraries,  , Autoload, Loading Programs
@subsection Operations on libraries
@c NODE ライブラリの操作

@c EN
There are several procedures you can use to check if
certain libraries and/or modules are installed in the system.

In the following descriptions, @var{pattern} is either a
symbol or a string.  If it is a symbol, it specifies
a module name (e.g. @code{foo.bar}).  If it is 
a string, it specifies a partial pathname of the library
(e.g. @code{"foo/bar"}), which will be searched under
library search paths.
You can also use glob-like metacharacters '@code{*}' and 
'@code{?}' in @var{pattern}.
@c JP
ある特定のライブラリおよび/あるいはモジュールがシステムにインストールされ
ているかどうかをチェックするための手続きがいくつかあります。

以下の説明の中では、@var{pattern}はシンボルまたは文字列です。シンボル
である場合にはモジュール名(たとえば、@code{foo.bar})を指定します。
文字列である場合にはライブラリの部分パス(たとえば、@code{"foo/bar"})を
指定します。これはライブラリサーチパス以下で検索されます。
@c COMMON

@defun library-fold pattern proc seed :key paths strict? allow-duplicates?
@c EN
A basic iterator for library/module files.
This procedure searches Scheme program files which matches
@var{pattern}, under directories listed in @var{paths} 
(the default is the standard file load paths, @code{*load-path*}).
For each matched file, it calls @var{proc} with three arguments:
the matched module or library name, the full path of the program
file, and the state value.  @var{Seed} is used as the initial
state value, and the value @var{proc} returns is used as the state
value for the next call of @var{proc}.  The value returned from
the last @var{proc} becomes the return value of @code{library-fold}.
@c JP
ライブラリ/モジュールファイルに対する基本イテレータ。この手続きは
@var{pattern} にマッチする Scheme のプログラムファイルを検索します。
検索は @var{paths} (デフォルトは標準のファイルロードパス、
@code{*load-path*})にリストされたディレクトリ以下でおこなわれます。
マッチしたファイル毎に、@var{proc} が、そのマッチしたモジュール名あるいは
ライブラリ名、そのプログラムファイルのフルパス、状態値、の3つの引数を
ともなって呼びだされます。@var{seed}は、初期状態値として使われ、
@var{proc} が返す値は次の @var{proc} の呼出し時に状態値として使われます。
最後の @var{proc} から返された値は @code{library-fold} の値として返ります。
@c COMMON

@c EN

@c JP
@c COMMON

@c EN
If @var{pattern} is a symbol and the keyword argument @var{strict?}
is @code{#t} (which is the default), this procedure calls
@code{library-has-module?} on the files whose name seems to
match the given pattern of module name, in order to find out
the file really implements the module.  It can be a time consuming
process if you try to match large number of modules; you can pass
@code{#f} to @var{strict?} to avoid the extra check.
If @var{pattern} is a string, matching is done only for file names
so @var{strict?} is ignored.
@c JP
@var{pattern} がシンボルでかつ、キーワード引数 @var{strict?} が
@code{#t} (デフォルト値)であれば、この手続きは
あたえられたモジュール名のパターンにマッチするようにみえるファイル名に
たいして @code{library-has-module?} を適用して、
本当にそのモジュールを実装しているファイルを見付けます。
大量のモジュールにマッチさせようとすると、時間がかる可能性があります。
@code{#f} を @var{strict?} に渡すことで、余分なチェックを回避できます。
@var{pattern} が文字列だった場合、照合はファイル名に対してのみ行われ、
@var{strict?}は無視されます。
@c COMMON

@c EN
By default, if there are more than one files that have the same name
that matches @var{pattern} in @var{paths}, only the first
one appears in @var{paths} is taken.  This gives you
the file you'll get if you use @code{require} or @code{use}
for that library.  If you want to iterate all of matching files,
pass @code{#t} to the @var{allow-duplicates?} keyword argument.

Here are some examples (the result may differ in your environment).
@c JP
デフォルトでは、@var{path} 中の @var{pattern} にマッチする同じ名前をもつ
2つ以上のファイルがあるばあい、@var{path} に最初に出現したものだけが
採用されます。そのライブラリに対して、@code{require} あるいは
@code{use} を用いたをつかった場合に得られるのはこのファイルです。
すべてのマッチしたファイルについて反復したければ、@var{allow-duplicates?}
キーワード引数に @code{#t} を渡します。
@c COMMON
@c EN
@example
(library-fold 'srfi-1 acons '())
 @result{} ((srfi-1 . "../lib/srfi-1.scm"))

(library-fold "srfi-1" acons '())
 @result{} (("srfi-1" . "../lib/srfi-1.scm"))

;; Note the returned list is in a reverse order of
;; how @code{acons} is called.
(library-fold 'srfi-1 acons '() :allow-duplicates? #t)
 @result{} ((srfi-1 . "/usr/share/gauche/0.7.1/lib/srfi-1.scm")
   (srfi-1 . "../lib/srfi-1.scm"))

;; In the following cases, the module name doesn't match,
;; but the filename does.
(library-fold 'srfi-19.* acons '())
 @result{} ()

(library-fold "srfi-19/*" acons '())
 @result{} (("srfi-19/read-tai" . "../lib/srfi-19/read-tai.scm")
   ("srfi-19/format" . "../lib/srfi-19/format.scm"))

;; Finds available dbm implementations
(library-fold 'dbm.* acons '())
 @result{} ((dbm.cdb . "/usr/share/gauche/0.7.1/lib/dbm/cdb.scm")
   (dbm.gdbm . "../lib/dbm/gdbm.scm")
   (dbm.ndbm . "../lib/dbm/ndbm.scm")
   (dbm.odbm . "../lib/dbm/odbm.scm"))
@end example
@c JP
@example
(library-fold 'srfi-1 acons '())
 @result{} ((srfi-1 . "../lib/srfi-1.scm"))

(library-fold "srfi-1" acons '())
 @result{} (("srfi-1" . "../lib/srfi-1.scm"))

;; @code{acons} が呼ばれるのとは逆順のリストが
;; 返ることに注意してください
(library-fold 'srfi-1 acons '() :allow-duplicates? #t)
 @result{} ((srfi-1 . "/usr/share/gauche/0.7.1/lib/srfi-1.scm")
   (srfi-1 . "../lib/srfi-1.scm"))

;; 以下の場合は、モジュール名ではマッチしませんが、
;; ファイル名ではマッチします
(library-fold 'srfi-19.* acons '())
 @result{} ()

(library-fold "srfi-19/*" acons '())
 @result{} (("srfi-19/read-tai" . "../lib/srfi-19/read-tai.scm")
   ("srfi-19/format" . "../lib/srfi-19/format.scm"))

;; 利用可能な dbm の実装を見付けます
(library-fold 'dbm.* acons '())
 @result{} ((dbm.cdb . "/usr/share/gauche/0.7.4.2/lib/dbm/cdb.scm")
   (dbm.gdbm . "../lib/dbm/gdbm.scm")
   (dbm.ndbm . "../lib/dbm/ndbm.scm")
   (dbm.odbm . "../lib/dbm/odbm.scm"))
@end example
@c COMMON
@end defun

@defun library-map pattern proc :key paths allow-duplicates? strict?
@defunx library-for-each pattern proc :key paths allow-duplicates? strict?
@c EN
@code{Map} and @code{for-each} version of iterator over matched
libraries/modules.  See @code{library-fold} above for detailed
operation of matching and the meanings of keyword arguments.

@var{Proc} receives two arguments, the matched module/library name
and full path of the file.  @code{Library-map} returns a list
of results of @var{proc}.  @code{Library-for-each} discards
the results.
@c JP
マッチしたライブラリ/モジュール上のイテレータの @code{map}版および
@code{for-each}版。照合操作とキーワード引数の詳細については上述の
@code{library-fold}を参照してください。

@var{proc}は、マッチしたモジュール/ファイル名と、そのファイルの
フルパスの 2 つの引数をうけとります。@code{library-for-each} は
結果を捨てます。
@c COMMON

@example
(library-map 'srfi-4 list :allow-duplicates? #t)
 @result{} ((srfi-4 "../lib/srfi-4.scm")
            (srfi-4 "/usr/share/gauche/0.7.1/lib/srfi-4.scm"))

(library-map 'dbm.* (lambda (m p) m))
 @result{} (dbm.odbm dbm.ndbm dbm.gdbm dbm.cdb)
@end example
@end defun

@defun library-exists? mod/path :key paths force-search? strict?
@c EN
Search a library or a module specified by @var{mod/path}, 
and returns a true value if it finds one.  @var{Paths} and @var{strict?}
keyword arguments have the same meaning as @code{library-fold}.

Unlike the iterator procedures above, this procedure first
checks loaded libraries and modules in the calling process,
and returns true if it finds @var{mod/path} in it,
without looking into the filesystem.   Passing @code{#t} to
@var{force-search?} keyword arguments skips the checking of
loaded libraries and modules.
@c JP
@var{mod/path} で指定されたライブラリあるいはモジュールを検索し、
もしあれば、真値を返します。キーワード引数 @var{paths} および 
@var{strict?} は @code{library-fold} のそれと同じ意味です。

上述のイテレータ手続きとはちがい、この手続きは呼び出しの過程で
最初に既にロードされているライブラリおよびモジュールをチェックします。
もしそのときに @var{mod/path} を見つけたら、真値を返し、ファイル
システムを見にいくことはありません。キーワード引数 @var{force-search?}
に @code{#t} を渡せば、すでにロードされいるライブラリおよびモジュール
のチェックはスキップされます。
@c COMMON
@end defun


@defun library-has-module? path module
@c EN
Returns @code{#t} iff a file specified by @var{path} exists and 
appears to implement a module named by @code{module}.  @var{path} must be
an actual filename.
@c JP
@var{path} で指定したファイルが存在し、かつ、@code{module} で名指しされた
モジュールが実装されている場合でその場合に限り、@code{#t} を返します。
@var{path} は実際のファイル名でなければなりません。
@c COMMON

@example
(library-has-module? "./test/foo/bar.scm" 'foo.bar)
 @result{} #t ;; @r{if ./test/foo/bar.scm implements module foo.bar}.
@end example

@c EN
This procedure assumes a typical layout of the source code
to determine if the given file implements the module, i.e.,
it reads the first form of the code and see if it is a
@code{define-module} form that is defining the given module.
@c JP
この手続きは典型的なソースコードの配置を仮定して、与えられたファイルが
そのモジュールを実装しているかどうかを決定します。すなわち、
まずそのコードのフォームを読み、与えられたモジュールを定義している
@code{define-module} フォームかどうかを見ます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Comparison and sorting, System interface, Loading Programs, Core library
@section Comparison and sorting
@c NODE 比較とソート

@defun compare obj1 obj2
@c EN
A general comparison procedure.  Returns -1 if @var{obj1} is less than
@var{obj2}, 0 if @var{obj1} is equal to @var{obj2}, and 1 if @var{obj1}
is greater than @var{obj2}.  Signals an error if @var{obj1} and @var{obj2}
are incomparable.

Some built-in types are handled by this procedure reflecting ``natural''
order of comparison.  Other built-in types are generally
uncomparable.  For Scheme-defined classes, this procedure calls
a generic function @code{object-compare}.
@c JP
一般的な比較手続きです。@var{obj1}が@var{obj2}より小さければ-1を、
等しければ0を、大きければ1を返します。@var{obj1}と@var{obj2}が
比較できない場合はエラーとなります。

いくつかの組み込み型は「自然な」比較順を用いて比較されます。
他の組み込み型は通常比較不可能です。Schemeで定義されたクラスについては、
この手続きはジェネリックファンクション@code{object-compare}を
呼び出します。
@c COMMON
@end defun

@deffn {Generic Function} object-compare obj1 obj2
@c EN
Specializing this generic function extends @code{compare} procedure
for user-defined classes.
@c JP
このジェネリックファンクションを特殊化することで
@code{compare}手続きをユーザ定義クラスに対して動作するように拡張できます。
@c COMMON
@end deffn

@defun sort seq :optional cmpfn
@defunx sort! seq :optional cmpfn
@c EN
Sorts elements in a sequence @var{seq} (a list or a vector) 
in ascending order and returns the sorted sequence.
@code{sort!} destructively reuses the original sequence.
The sorting order is specified by @code{cmpfn}, which is
a procedure takes two elements of @var{seq}, and returns @code{#t}
if the first argument strictly precedes the second.
@c JP
シーケンス@var{seq}(リストかベクタ)の要素を昇順にソートし、
ソートされたシーケンスを返します。
@code{sort!}は、オリジナルのシーケンスを破壊的に再利用します。
ソート順は@code{cmpfn}で指定されます。@code{cmpfn}は@var{seq}のふたつの要素を
引数に取り、最初の要素が厳密に2番目の要素より先行するものの場合は
@code{#t}を返す手続きです。
@c COMMON

@c EN
Note that it is not guaranteed that, after @code{sort!},
@var{seq} points to a sorted sequence.
if @var{seq} is a list, the first pair of the original
@var{seq} may no longer be the first in the sorted sequence.
Always use the returned value of @code{sort!}.
@c JP
@code{sort!}の後で@var{seq}が必ずしもソート済みのシーケンスを
指すとは限らないことに注意してください。
@var{seq}がリストの場合、オリジナルのリストの最初のペアが
ソート済みリストでも最初に来るとは限りません。
常に@code{sort!}の戻り値を使うようにしてください。
@c COMMON

@example
(sort '(("Chopin" "Frederic") 
        ("Liszt" "Franz")
        ("Alkan" "Charles-Valentin"))
      (lambda (x y) (string<? (car x) (car y))))
  @result{} (("Alkan" "Charles-Valentin")
      ("Chopin" "Frederic")
      ("Liszt" "Franz"))
@end example

@c EN
When @var{cmpfn} is omitted, the @code{compare} procedure
is used to determine which element is @emph{less}.
@c JP
@var{cmpfn}が省略された場合は@code{compare}手続きが
どちらの要素がより「小さい」かを判定するのに使われます。
@c COMMON

@c EN
In the current implementation, quicksort and heapsort
algorithm is used when @var{cmpfn} is omitted,
and merge sort algorithm is used when @var{cmpfn} is given.
This might be changed later.
@c JP
現在の実装では、@var{cmpfn}が省略された場合は
クィックソートとヒープソートを使い、
@var{cmpfn}が与えられた場合はマージソートを使っています。
これは将来変更されるかもしれません。
@c COMMON

@c EN
If you want to keep a sorted set of objects to which you
add objects one at at time, you can also use treemaps
(@xref{Treemaps}).
@c JP
なお、オブジェクトをひとつづつ集合に追加しつつ、常にソートされた
状態に保ちたい場合は、treemapの使用を考えても良いでしょう (@ref{Treemaps}参照)。
@c COMMON
@end defun

@defun stable-sort seq :optional cmpfn
@defunx stable-sort! seq :optional cmpfn
@c EN
Sort a sequence @var{seq} (a list or a vector), using stable sort algorithm
(currently they are using merge sort).  
The sorting order is specified by @code{cmpfn}, which is
a procedure takes two elements of @var{list}, and returns @code{#t}
if the first argument strictly precedes the second.
@c JP
安定ソートアルゴリズム(現時点ではマージソート)を使って、並び @var{seq}
(リストまたはベクタ)をソートします。ソート順は @code{cmpfn} で指定します。
@code{cmpfn} は @var{list} のふたつの要素を引数として取る関数で、
厳密に、最初の引数が第二の引数の前にくるものである場合に @code{#t}
を返します。
@c COMMON
@end defun

@defun sort-by seq key :optional cmpfn
@defunx sort-by! seq key :optional cmpfn
@defunx stable-sort-by seq key :optional cmpfn
@defunx stable-sort-by! seq key :optional cmpfn
@c EN
Sorts @var{seq}, by comparing the key values obtained by
applying the @var{key} procedure to each element of @var{seq}.
The code @code{(stable-sort-by seq key cmp)} returns the same result
as the following code:

@example
(stable-sort seq (lambda (a b) (cmp (key a) (key b))))
@end example

Besides more compact notation, @code{sort-by} family procedures
guarantee that @var{key} procedure is called at most the number
of elements in @var{seq}.  In the above example using @code{stable-sort},
@var{key} may be called @var{n}log@var{n} or even more times
where @var{n} is the number of elements in @var{seq}.
So @code{sort-by} etc. are good if the @var{key} procedure is
a relatively heavy operation.

The trade-off is the space; @code{sort-by} family consumes
extra space to save all the key values, which is proportional
to the number of elements.
@c JP
@var{key}をシーケンス@var{seq}の各要素に適用して得られる値の比較をもとに
@var{seq}をソートします。@code{(stable-sort-by seq key cmp)}は次のコードと
同じ結果を返します:

@example
(stable-sort seq (lambda (a b) (cmp (key a) (key b))))
@end example

よりコンパクトに書けるという以外に、
@code{sort-by}族の手続きは@var{key}手続きをたかだか@var{seq}の要素数
しか呼び出さないという性質があります。上記の@code{stable-sort}を
使った例では、@var{key}は@var{seq}の要素数を@var{n}とする時
@var{n}log@var{n} 回以上呼び出される可能性があります。
したがって、@code{sort-by}族は@var{key}手続きが比較的高価な場合に
威力を発揮します。

トレードオフは空間です。@code{sort-by}族はあらかじめ比較対象となる
値を計算しておくために、@var{seq}の要素数に比例した余分なメモリを
必要とします。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node System interface, Development helper API, Comparison and sorting, Core library
@section System interface
@c NODE システムインタフェース

@c EN
Gauche supports most of POSIX.1 functions and other system functions
popular among Unix variants as built-in procedures.
@c JP
GaucheはPOSIX.1の多くの関数と、さまざまなUnixで共通して使われているシステム関数へのインタフェースを
組込み手続きとして提供しています。
@c COMMON

@c EN
Lots of Scheme implementations provide some sort of system interface
under various APIs.  Some are just called by different names
(e.g, @code{delete-file} or @code{remove-file} or @code{unlink} to delete
a file), some do more abstraction introducing new Scheme objects.
Instead of just picking one of such interfaces, I decided to implement
Gauche's system interface API in two layers; the lower level layer,
described in this section, follows the operating system's API
as close as possible.  On top of that, the higher-level APIs are
provided, with considering compatibility to the existing systems.
@c JP
多くのScheme実装はいろいろな形で何らかのシステムインタフェースを提供
しています。名前だけが違うもの(例：@code{delete-file}、@code{remove-file}
、@code{unlink}) もあれば、新しいSchemeオブジェクトを導入して
抽象化を行っているものもあります。Gaucheでは、既存のAPIのどれかを
そのまま真似るのではなく、2つのレイヤを提供することにしました。
この章で述べられる低レベルレイヤは、OSのインタフェースに似せたものを実装します。
その上に、既存のシステムと互換性のある高レベルのインタフェースが実装されます。
@c COMMON

@c EN
The low level system interface has the name @code{sys-}@var{name}
and usually correspond to the system call @var{name}.
I tried to keep the interface similar whenever reasonable.
@c JP
@code{sys-}@var{name}という名前を持つ手続きは、多くの場合、
システムコール@var{name}に対応しています。
可能な限り、インタフェースが似るようにしました。
@c COMMON

@c EN
Gauche restarts a system call after it is interrupted by a signal.
See @ref{Signal} for the details.
@c JP
なお、Gaucheはシステムコールがシグナルによって割り込まれた場合、
システムコールをリスタートします。詳しくは@ref{Signal}を参照して下さい。
@c COMMON

@c EN
If you are familiar with system programming in C,
see also @ref{C to Scheme mapping}, which shows
correspondence between C standard library functions
and Gauche procedures.
@c JP
Cによるシステムプログラミングに慣れている方は、
@ref{C to Scheme mapping}も参考にして下さい。
Cの標準ライブラリとGaucheの手続きとの対応が示してあります。
@c COMMON

@menu
* Program termination::         
* Environment Inquiry::         
* Filesystems::                 
* Unix groups and users::       
* Locale::                      
* Signal::                      
* System inquiry::              
* Time::                        
* Process management::          
* I/O multiplexing::            
* Miscellaneous system calls::  
@end menu

@node Program termination, Environment Inquiry, System interface, System interface
@subsection Program termination
@c NODE プログラムの終了

@c EN
Gauche has a few ways to terminate itself (other than returning
from @code{main}).  The @code{exit} procedure is a graceful way
with all proper cleanups.  @code{sys-exit} and @code{sys-abort}
may be used in emergency where proper cleanup is impossible.
@c JP
Gaucheは(@code{main}から返る以外に)自分自身を終了させる方法をいくつか
提供しています。@code{exit}手続きが、正しいクリーンアップを行って
優雅に終了する方法です。一方、正しいクリーンアップが不可能な非常事態には
@code{sys-exit}か@code{sys-abort}を使います。
@c COMMON


@defun exit :optional (code 0) (fmtstr #f) args @dots{}
[POSIX]
@c EN
Terminates the current process with the exit code @var{code}.
@var{Code} must be zero or positive exact integer.
When a string is given to @var{fmtstr}, it is passed to
@code{format} (@xref{Output}), with the rest arguments @var{args},
to produce a message to the standard error port
(@emph{not} the current error port; see @ref{Common port operations}).
@c JP
現在のプロセスを終了し、@var{code}を終了コードにします。
@var{code}はゼロもしくは正の正確な整数でなければなりません。
@var{fmtstr}文字列が与えられた場合、それは残りの引数@var{args}と
ともに@code{format}に渡され、standard error portにメッセージとして
印字されます (@code{current-error-port}ではありません。
@ref{Common port operations}参照。また、@code{format}については
@ref{Output}参照。)
@c COMMON

@c EN
In fact, the exitting procedure is a bit more complicated.
The precise steps of exitting is as follow.
@c JP
実のところ、プロセス終了の手続きはもう少し複雑です。
正確な段階を次に説明します。
@c COMMON

@enumerate 
@item
@c EN
The value of parameter @code{exit-handler} is checked.  
If it is not @code{#f}, the value is called as a procedure
with three arguments: @var{code}, @var{fmtstr}, and a list of rest
arguments.  It is the default procedure of @code{exit-handler}
that prints out the message to the standard error port.
If an error occurs within exit handler, it is captured and
discarded.  Other exceptions are not caught.
@c JP
パラメータ@code{exit-handler}の値がチェックされます。
もしそれが@code{#f}でなければ、それは3引数の手続きとみなされ、
@var{code}、@var{fmtstr}、そして残りの引数のリストを引数として
呼び出されます。実はメッセージを標準エラー出力に出しているのは
デフォルトの@code{exit-handler}です。
終了ハンドラの中でエラーが起きた場合、そのエラーは捕捉され捨てられます。
エラー以外の例外は捕捉されません。
@c COMMON

@item
@c EN
The @var{after} thunks of the active dynamic winds are invoked.
Any exceptions raised in @var{after} thunks are captured and discarded.
@c JP
アクティブな@code{dynamic-wind}の@var{after}サンクが順に呼び出されます。
@var{after}サンク中で発生した例外は捕捉され捨てられます。
@c COMMON

@item
@c EN
The clean-up handlers registered via C API @code{Scm_AddCleanupHandler}
are invoked.  These are usually responsible for under-the-hood cleanup
jobs for each application that embeds Gauche.  From the Scheme world 
there's not much to care.
@c JP
C APIの@code{Scm_AddCleanupHandler}で登録されたクリーンアップハンドラが
呼ばれます。このハンドラは通常、Gaucheを内蔵しているアプリケーション特有の
クリーンアップをするために使われます。Schemeの世界からはあまり気にする必要は
ないでしょう。
@c COMMON

@item
@c EN
The unclosed output buffered ports are flushed.
@c JP
まだ閉じられていない出力ポートのバッファが掃き出されます。
@c COMMON

@item
@c EN
The process exits with @var{code} as an exit code, via @code{exit(3)}.
@c JP
@code{exit(3)}を呼び、プロセスは@var{code}を終了コードとして終了します。
@c COMMON
@end enumerate

@c EN
The @code{exit-handler} mechanism allows the application to hook its
exit operation.   Note that it is not for simple cleanup jobs; 
@code{dynamic-wind}, @code{guard} or @code{unwind-protect} are more appropriate.   
@code{exit-handler} is for more specific use just upon application exit.
For example, GUI applications may want to post a dialog
instead of printing to stderr.

For this reason, the library code shouldn't change @code{exit-handler};
only the application knows what to do when it exits.

Another useful case is when you
want to call a third-party code which calls @code{exit} inside.  In
that case you may swap the @code{exit-handler} for the one
that raises a non-error exception while calling the third-party code.
Non-error exception isn't caught in @code{exit}, effectivelly
interrupts the steps explained above.   (Yet the @var{after} thunks
of dynamic handlers are processed just like normal exception 
handling case.)
Your appication code can then capture the exception.
You can use @code{parameterize}
to swap @code{exit-handler} dynamically
and thread-safely (@xref{Parameters}).
@c JP
@code{exit-handler}のメカニズムはアプリケーションが終了処理をフックすることを
可能にします。ただし、単純なクリーンアップ処理のためのものではありません
(クリーンアップ処理には
@code{dynamic-wind}, @code{guard}あるいは@code{unwind-protect}を使う方が
適切です。)
@code{exit-handler}はもっと「アプリケーションの終了」という特定の事態に
対して何か処理を行いたい場合に使います。
例えばGUIアプリケーションはメッセージを標準エラー出力ではなく
ダイアログとして表示する、というようなことです。

従って、ライブラリコードは@code{exit-handler}に触るべきではありません。
アプリケーションの終了時に何をすべきかを知っているのはアプリケーション自身なのですから。

別の使いどころとしては、サードパーティ製のコードで中で@code{exit}が
呼ばれる可能性のあるものを安全に呼び出したいという場合があります。
そのコードを呼び出している間だけ、@code{exit-handler}を
エラーではない例外を発生させる手続きへと差し替えます。
エラーではない例外は@code{exit}では捕捉されないので、実質的に
上で説明したような終了処理のステップは中断されることになります
(但し、ダイナミックハンドラの@var{after}サンクは通常の例外発生時と
同じように処理されます)。
アプリケーションコードの方でその例外を捕捉してやればよいのです。
@code{parameterize}を使えば@code{exit-handler}を動的に、
かつスレッドセーフに差し替えることが容易になります
(@ref{Parameters}参照)。
@c COMMON

@example
(guard (e [(eq? e 'exit-called) (handle-exit-as-desired)])
  (parameterize ((exit-handler (lambda (c f a) (raise 'exit-called))))
    (call-third-party-library)))
@end example

@c EN
Generally, calling @code{exit} while other threads are running
should be avoided, since it only rewinds the dynamic handlers active
in the calling threads, and other threads will be killed abruptly.
If you have to do so for some reason,
you may be able to use @code{exit-handler} to tell to other threads
that the application is exitting.  (There's no general way, and
Gauche doesn't even have a list of all running threads; it's application's
responsibility).
@c JP
一般的に、他のスレッドが走っている時に@code{exit}を呼ぶことは推奨されません。
@code{exit}手続きは該当スレッド上でアクティブなダイナミックハンドラしか巻き
戻さないので、他のスレッドはいきなり終了させられてしまいます。
しかし@code{exit}を呼ばざるを得ない場合には、
@code{exit-handler}を使って他のスレッドにアプリケーションが終了しつつあることを
伝えられるかもしれません (但しGauche自身は走っているスレッドのリストといった
情報は持っていないので、アプリケーションごとに固有のロジックを実装する必要が
あります。)
@c COMMON

@c EN
Note on design: Some languages integrates exit handling
into exception handling, treating exit as a kind of exception.
It is a tempting idea, so much that we've tried it.  It didn't
work out well in Gauche; a big annoyance was that when 
an @var{after} thunk raised an exception during
rewinding @code{dynamic-wind}s, it shadowed the original
@emph{exit} exception.
@c JP
設計に関する覚書: 終了を一種の例外とすることで、
終了処理を例外処理と統合している言語もあります。
良いアイディアに思えたので我々もそのような実装を試してみましたが、
Gaucheではうまくいきませんでした。大きな理由のひとつは、
@code{dynamic-wind}の巻き戻し中に@var{after}で例外が
発生すると、その例外がもともとの「終了」例外を隠してしまうことでした。
@c COMMON
@end defun

@defun exit-handler :optional new-handler
@c EN
When called without argument, returns the value of the current exit
handler.  When called with an argument, sets @var{new-handler} as the
value of the exit handler, and returns the previous value of the
exit handler.    @var{new-handler} must be a procedure that takes
three arguments, or @code{#f}.

The value of exit handler is thread-specific, and the default value
is inherited from the value of the current exit handler of the parent
thread.  @code{exit-handler} can be used as if it's a parameter
in the @code{parameterize} macro (@xref{Parameters}).
@c JP
引数なしで呼ばれた場合、現在のexit handlerの値を返します。
引数つきで呼ばれた場合は、@var{new-handler}を現在のexit handlerの
値とし、以前の値を返します。@var{new-handler}は3つの引数をとる
手続きか、@code{#f}でなければなりません。

exit handlerの値はスレッドごとに固有で、デフォルト値はスレッドが作られた時点の
親スレッドのexit handlerの値から引き継がれます。
@code{exit-handler}はあたかもパラメータのように@code{parameterize}マクロで
使うことができます (@ref{Parameters}参照)。
@c COMMON
@end defun



@defun sys-exit code
[POSIX]
@c EN
Terminates the current process with the exit code @var{code}.
@var{Code} must be zero or positive exact integer.
This procedure calls @code{_exit(2)} directly.
No cleanup is done.  Unflushed file output is discarded.
@c JP
現在のプロセスを終了し、@var{code}を終了コードにします。
@var{code}はゼロもしくは正の正確な整数でなければなりません。
この手続きは@code{_exit(2)}を直接コールします。
クリーンアップは一切行われません。
フラッシュされてないファイルバッファの内容は捨てられます。
@c COMMON
@end defun

@defun sys-abort
[POSIX]
@c EN
Calls POSIX abort().  This usually terminates the running process 
and dumps core.  No cleanup is done.
@c JP
POSIXのabort()を呼びます。通常、現在のプロセスは終了され、コアダンプされます。
クリーンアップは一切行われません。
@c COMMON
@end defun

@node Environment Inquiry, Filesystems, Program termination, System interface
@subsection Environment Inquiry
@c NODE 環境の問い合わせ

@defun sys-getenv name
[POSIX]
@c EN
Returns the value of the environment variable @var{name} as a string,
or @code{#f} if the environment variable is not defined.
(@xref{Accessing environment variables}).
@c JP
環境変数@var{name}の値を文字列で返します。もし@var{name}が定義されていなければ、
@code{#f}が返ります。
@c COMMON
@end defun

@defun sys-environ
@c EN
Returns the current environment as a list of strings.  Each string
is a form of @code{NAME=VALUE}, where @code{NAME} is the name of
the environment variable and @code{VALUE} is its value.  @code{NAME}
never contains a character @code{#\=}.  This is useful when you want
to obtail the all enviroment variables of the current process.
Use @code{sys-getenv} if you want to query a specific environment
variable.
@c JP
現在の環境を文字列のリストとして返します。それぞれの文字列は
@code{NAME=VALUE}というフォーマットになっています。ここで@code{NAME}は
環境変数名、@code{VALUE}はその値です。@code{NAME}が文字@code{#\=}を含
むことはありません。この手続きは現在のプロセスの環境変数をすべて取得し
たい場合に便利です。特定の環境変数の値が欲しい場合には
@code{sys-getenv}を使ってください。
@c COMMON
@end defun

@defun sys-environ->alist :optional envlist
@c EN
A convenience procedure for @code{sys-environ}.  When the list of
environment strings (like what @code{sys-environ} returns) is given
to @var{envlist}, this procedure splits name and value of
each environment variable and returns an assoc list.
@c JP
@code{sys-environ}の便利版。環境リスト(@code{sys-environ}が返すような
形式のもの)を@var{envlist}として与えると、この手続きは各環境変数を名前
と値に分けて連想リストにして返します。
@c COMMON

@c EN
When @var{envlist} is omitted, this procedure calls @code{sys-environ}
to get the current environment variables.
@c JP
@var{envlist}を省略すると、この手続きは@code{sys-environ}を呼んで現在
の環境変数を取得します。
@c COMMON

@example
(sys-environ->alist '("A=B" "C=D=E"))
  => (("A" . "B") ("C" . "D=E"))
@end example
@end defun


@defun sys-setenv name value &optional overwrite
@defunx sys-putenv name=value
@var{sys-setenv} inserts an environment variable @var{name} with
the value @var{value}.
Both @var{name} and @var{value} must be a string.
If the optional argument @var{overwrite} is @code{#f} (default),
the enviornment is untouched if a variable with @var{name} already
exists.   If @var{overwrite} is @code{#t}, the variable is overwritten.

Fir @code{sys-putenv}, you have to give a single string
with the form of @code{NAME=VALUE}, that is, concatenating @var{name}
and @var{value} with @code{#\=}.  If the enviornmet variable with
the same name exists, it will be overwritten.

These API reflects POSIX @code{setenv(3)} and @code{putenv(3)}.
However, unlike @code{putenv(3)}, modifying the string passed
to @code{sys-putenv} afterwards won't affect the environment.

These procedures are only available when a feature identifier
@code{gauche.sys.setenv} exists.  Use @code{cond-expand}
(@xref{Feature conditional}) to check their availability.

@example
(cond-expand
 [gauche.sys.setenv 
   ... use sys-setenv or sys-putenv ... ]
 [else
   ... fallback code ...])
@end example
@end defun

@defun sys-unsetenv name
@defunx sys-clearenv
Remove the environment variable with @var{name} (@code{sys-unsetenv}),
or all enviornment variables.  @code{sys-clearenv} is handy
when you need to run subprocess, but you cannot trust the inherited
environment.

These procedures are only available when a feature identifier
@code{gauche.sys.unsetenv} exists.  Use @code{cond-expand}
(@xref{Feature conditional}) to check their availability.

@example
(cond-expand
 [gauche.sys.unsetenv 
   ... use sys-unsetenv or sys-clearenv ... ]
 [else
   ... fallback code ...])
@end example
@end defun


@c EN
SRFI-98 (@xref{Accessing environment variables}) also defines
a subset of above procedures to access to the environment variables.
Portable programs may want to use them instead.
@c JP
SRFI-98 (@ref{Accessing environment variables}参照) にも、
環境変数を読み出すための、上記の手続きのサブセットにあたるものが
定義されています。ポータブルなコードにしたければそちらも見てみてください。
@c COMMON


@defun gauche-version
@defunx gauche-architecture
@defunx gauche-library-directory
@defunx gauche-architecture-directory
@defunx gauche-site-library-directory
@defunx gauche-site-architecture-directory
@c EN
These functions returns a string that tells information about Gauche
interpreter itself.
@c JP
これらの手続きはGaucheインタプリタの情報を文字列で返します。
@c COMMON
@end defun

@node Filesystems, Unix groups and users, Environment Inquiry, System interface
@subsection Filesystems
@c NODE ファイルシステム

@c EN
System calls that deal with filesystems.
See also @ref{Filesystem utilities}, which defines high-level APIs
on top of the procedures described here.
@c JP
ファイルシステムに関するシステムコール群です。
ここで述べる手続きの上に、より高レベルなAPIがモジュール@code{file.util}として
実装されています。@ref{Filesystem utilities}を参照して下さい。
@c COMMON

@menu
* Directories::                 
* Directory manipulation::      
* Pathnames::                   
* File stats::                  
* Other file operations::       
@end menu

@node Directories, Directory manipulation, Filesystems, Filesystems
@subsubsection Directories
@c NODE ディレクトリ

@c EN
See also @ref{Directory utilities} for high-level API.
@c JP
高レベルAPIに関しては@ref{Directory utilities}も参照して下さい。
@c COMMON

@defun sys-readdir path
@c EN
@var{path} must be a string that denotes valid pathname of an existing
directory.  This function returns a list of strings of the directory
entries.  The returned list is not sorted.  An error is signalled
if @var{path} doesn't exists or is not a directory.
@c JP
@var{path}は存在するディレクトリを示すパス名でなければなりません。
この手続きはディレクトリの全エントリを文字列のリストとして返します。
リストはソートされません。@var{path}が存在しなかったり、ディレクトリでなかった場合は
エラーとなります。
@c COMMON
@end defun

@defun glob pattern :key separator folder
@defunx sys-glob pattern :key separator folder
@c EN
Provides a traditional Unix glob(3) functionality;
returns a list of pathnames that matches the given @var{pattern}.
@c JP
伝統的なUnixのglob(3)の機能を提供します。この手続きは@var{pattern}とマッ
チするパス名のリストを返します。
@c COMMON

@c EN
This feature used to be a wrapper of system-provided @code{glob} function,
hence it was named @code{sys-glob}.  However, as of Gauche version 0.8.12,
it was reimplemented in Scheme on top of other system calls, to overcome
incompatibilies between platforms and for the opportunity to put
more functionalities.  So we renamed it @code{glob}.
The old name @code{sys-glob} is kept for compatibility, but new
programs should use @code{glob}.
@c JP
この機能は、かつてはプラットフォームが提供する@code{glob}関数をラップする
もので、@code{sys-glob}という名前でした。しかし、プラットフォーム間の非互
換性を解消し機能の追加を容易にするために、Gauche 0.8.12以降、システムコー
ルの上にSchemeで再実装されています。そのため、@code{glob}と改名してあ
ります。古い方の名前@code{sys-glob}は互換性のために残してありますが、
新たにプログラムを書くときは@code{glob}を使ってください。
@c COMMON

@c EN
The @var{pattern} argument may be a single @emph{glob pattern}, or
a list of glob patterns.  If a list is given, pathnames that matches
any one of the pattern are returned.  If you're a unix user,
you already know how it works.
@c JP
引数@var{pattern}は単一の@emph{グロブパターン}もしくは、グ
ロブパターンのリストです。リストが渡されたときには、
最低1つのパターンにマッチするパス名がすべて返されます。
Unixのユーザならglobの動作は馴染み深いものでしょう。
@c COMMON

@example
gosh> (glob "*.scm")
("test.scm" "ext.scm")
gosh> (glob "src/*.[ch]")
("src/ext.c" "src/ext.h")
gosh> (glob '("*.scm" "src/*.c"))
("src/ext.c" "test.scm" "ext.scm")
@end example

@c EN
Unlike shell's glob, if there's no matching pathnames, @code{()} is returned.
@c JP
シェルのグロブとはちがって、マッチするパス名がないときは、@code{()}が返ります。
@c COMMON

@c EN
In fact, globbing is a very useful tool to search hierarchical
data structure in general, not limited to the filesystems.
So the @code{glob} function is implemented separately from
the filesystem.  Using keyword arguments,
you can glob from any kind of tree data structure.
It is just that their default values are set to look at
the filesystems.
@c JP
グロブはファイルシステムに限らず階層的なデータ構造を検索するのに非常に便利なツールです。
したがって、@code{glob}関数はファイルシステムからは切り離して実装されています。
キーワード引数を使うことで、どのようなツリー状のデータ構造からでもグロブできます。
デフォルト値がファイルシステム用に設定されているにすぎません。
@c COMMON

@c EN
The @var{separator} argument should be a char-set, and used
to split the @var{pattern} into components.  Its default is
@code{#[/]}.  It is not used to the actual pathnames to match.
@c JP
引数@var{separator}は文字の集合を与えます。これを使って@var{pattern}を
コンポーネントに分割します。デフォルトは@code{#[/]}です。実際のパス名
をマッチさせるのには使われません。
@c COMMON

@c EN
The @var{folder} is a procedure that walks through the data
structure.  It is called with five arguments:
@c JP
@var{folder}はデータ構造をトラバースするための手続きです。この手続きは
引数を5つとります。
@c COMMON

@example
(folder @var{proc} @var{seed} @var{parent} @var{regexp} @var{non-leaf?})
@end example

@c EN
@var{proc} is a procedure that takes two arguments.  The @var{folder}
should call @var{proc} with every node in the @var{parent} whose
component name matches @var{regexp}, passing around the seed value
just like @code{fold}.  It should return the final value returned
by @var{proc}.  For example, if @code{cons} is given to @var{proc}
and @code{()} is given to @var{seed}, the return value of the folder
is a list of nodes that matches the @var{regexp}.
@c JP
@var{proc}は引数を2つ取る手続きです。@var{folder}は、@var{parent}内で
コンポーネントとなる名前が@var{regexp}とマッチする各ノードと、
@code{fold}と同様に順に渡されるシード値とで、@var{proc}を呼びます。
@var{folder}は@var{proc}が最後に返した値を返します。たとえば、
@code{cons}が@var{proc}として、@code{()}が@var{seed}として渡されれば、
folder手続きが返す値は@var{regexp}とマッチするノードのリストになります。
@c COMMON

@c EN
The representation of a node is up to the implementation of
@var{folder}.  It can be a
pathname, or some sort of objects, or anything.  The @code{glob}
procedure does not care what it is; the @code{glob} procedure
merely passes the node to subsequent call to @code{folder} as
@var{parent} argument, or returns a list of nodes as the result.
@c JP
ノードの表現がどうなるかは@var{folder}の実装によります。
パス名であったり、オブジェクトであったりするかもしれません。
@code{glob}手続きはノードの表現については感知しません。
@code{glob}手続きがやることはノードを次に呼ぶ
@code{folder}に@var{parent}引数として渡して、
その結果のノードリストを返すだけです。
@c COMMON

@c EN
The @var{parent} argument is basically a node, and
@var{folder} traverses its children to find the match.
The exception is the initial call of @var{folder}---
at the beginning @code{glob} knows nothing about each node.
When @code{glob} needs to match an absolute path, it
passes @code{#t}, and when @code{glob} needs to match a relative path,
it passes @code{#f}, as the initial @var{parent} value.
@c JP
@var{parent}引数は基本的にはノードで、@var{folder}はその子ノードを
対象にマッチするものを探索します。
例外は最初に@var{folder}が呼ばれる時です。その時点では@code{glob}は
ノードについて何も知らないので、
絶対パスでマッチをかける場合は@code{#t}を、
相対パスでマッチをかける場合は@code{#f}を最初の@var{parent}の値として渡します。
@c COMMON

@c EN
The @var{regexp} argument is used to filter the child nodes.
It should be matched against the component name of the child,
not including its directory names.  As a special case, it can
be a symbol @code{dir}; if that's the case, the folder should
return @var{node} itself, but it may indicate @var{node}
@emph{as a directory}; e.g. if @var{node} is represented as a pathname,
the folder returns a pathname with trailing directory separator.
As special cases,
if @var{node} is a boolean value and @var{regexp} is @code{dir},
the folder should return the node representing root node or
current node, respectively; e.g. if @var{node} is represented
as a pathname, the folder may return @code{"/"} and @code{"./"}
for those cases.
@c JP
@var{regexp}引数は子ノードをフィルターするのに使い、ディレクトリ名を含
まない、子のコンポーネントである名前に対して照合されるものです。特別な
場合として、シンボル@code{dir}にすることができます。この場合は、folder
は@var{node}そのものを返し、@var{node}は@emph{ディレクトリ}と見なされ
ます。すなわち、@var{node}がパス名を表わす場合には、folderはディレクト
リ区切り子が最後に付いたパス名を返します。
特別な場合として、@var{node}がブール値でかつ
@var{regexp}が@code{dir}である場合、folderはルートノードをあらわすノー
ドあるいはカレントノードを返すことになっています。すなわち、@var{node}
はパス名を表す場合、folderは@code{"/"}または@code{"./"}を返します。
@c COMMON

@c EN
The @var{non-leaf} argument is a boolean flag.  If it is true,
the filter should omit the leaf nodes from the result (e.g. only
include the directories).
@c JP
@var{non-leaf}引数はブール値フラッグです。真なら、フィルタは結果からリー
フノードをのぞきます(すなわち、ディレクトリだけが含まれるようになり
ます)。
@c COMMON

@c EN
Now, here's the precise spec of glob pattern matching.
@c JP
ここからはグロブパターンマッチングの細かい仕様をみていきます。
@c COMMON

@c EN
Each glob pattern is a string to match pathname-like strings.
@c JP
各グロブパターンはパス名様式文字列にマッチする文字列です。
@c COMMON

@c EN
A pathname-like string is a string consists of one or more
@emph{components}, separated by @emph{separator}s.
The default separator is @code{#[/]}; you can change it
with @var{separator} keyword argument.
A component cannot contain separators, and cannot
be a null string.  Consecutive separators are
regarded as a single separator.  A pathname-like
string optionally begins with, and/or ends with a separator character.
@c JP
パス名様式文字列は1つ以上の@emph{セパレータ}で区切られた
@emph{コンポーネント}から構成される文字列です。
デフォルトのセパレータは@code{#[/]}です。キーワード引数@var{separator}
を使うとこれを変更できます。コンポーネントにはセパレータを含められませ
ん。また空文字列にすることもできません。連続したセパレータは単一のセパ
レータとみなされます。パス名様式の文字列は状況に応じてセパレータから始
めたり、セパレータで終端したりできます(両方をやるのも可)。
@c COMMON

@c EN
A glob pattern also consists of components and separator
characters.  In a component, following characters/syntax have special
meanings.
@c JP
グロブパターンもコンポーネントとセパレータ文字から構成されます。コンポー
ネントにおいては、以下の文字、構文は特別な意味を持ちます。
@c COMMON

@table @code
@item *
@c EN
When it appears at the beginning of a component, it matches
zero or more characters except a period (@code{.}).  And it
won't match if the component of the input string begins with 
a period.

Otherwise, it matches zero or more sequence of any characters.
@c JP
これがコンポーネントの先頭に表われた場合、0個以上のピリオド(@code{.})
を除く文字にマッチします。入力文字列のコンポーネントがピリオドではじま
るような文字列の場合にはマッチしません。

先頭以外の場所では、0個以上の文字の列にマッチします。
@c COMMON

@item **
@c EN
If a component is just @code{**}, it matches zero or more
number of components that match @code{*}.  For example, @code{src/**/*.h}
matches all of the following patterns.
@c JP
コンポーネントが@code{**}だけの場合、これは@code{*}にマッチする0個以上の
コンポーネントにマッチします。例えば@code{src/**/*.h}は
次のようなパターン全てにマッチします。
@c COMMON
@example
src/*.h
src/*/*.h
src/*/*/*.h
src/*/*/*/*.h
...
@end example

@item ?
@c EN
When it appears at the beginning of a component, it matches
a character except a period (@code{.}).  Othewrise, it matches
any single character.
@c JP
コンポーネントの先頭にあらわれた場合、ピリオド(@code{.})以外の一文字に
マッチします。先頭以外の場所では任意の一文字にマッチします。
@c COMMON

@item [@i{chars}]
@c EN
Specifies a character set.  Matches any one of the set.
The syntax of @i{chars} is the same as Gauche's character set
syntax (@xref{Character set}).  For the compatibility of the
traditional glob, the @code{!} character can be used to complement
the character set, e.g. @code{[!abc]} is the same as @code{[^abc]}.
@c JP
文字の集合を指定します。その集合に含まれる文字のどれかにマッチします。
@i{chars}の構文はGaucheの文字集合を表す構文と同じです
(@ref{Character set}参照)。伝統的なグロブとの互換性のために、@code{!}
文字をつかって、補集合で文字集合を表わすこともできるようになっています。
すなわち、@code{[!abc]}は@code{[^abc]}と同じです。
@c COMMON
@end table
@end defun

@defun glob-fold pattern proc seed :key separator folder
@c EN
This is actually a low-level construct of the glob function.
Actually, @var{glob} is simply written like this:
@c JP
これはグロブ関数の低レベル版です。実際@var{glob}は以下のように書いたの
と同じです。
@c COMMON
@example
(define (glob patterns . opts)
  (apply glob-fold patterns cons '() opts))
@end example

@c EN
The meaning of @var{pattern}, @var{separator} and @var{folder}
is the same as explained above.  
@c JP
@var{pattern}、@var{separator}および@var{folder}の意味を前述のものと同
じです。
@c COMMON

@c EN
For each pathname that matches @var{pattern}, @code{glob-fold}
calls @var{proc} with the pathname and a seed value.  The initial
seed value is @var{seed}, and the value @var{proc} returns becomes
the next seed value.  The result of the last call to @var{proc} 
becomes the result of @code{glob-fold}.  If there's no matching
pathnames, @var{proc} is never called and @var{seed} is returned.
@c JP
@var{pattern}にパス名ごとに@code{glob-fold}は@var{proc}をパス名とシー
ド値で呼びます。最初のシード値は@var{seed}で、@var{proc}が返す値は次の
シード値になります。最後の@var{proc}の呼び出し結果は@code{glob-fold}の
結果となります。マッチするパス名が存在しないときは、@var{proc}は呼ばれ
ずに、@var{seed}が返ります。
@c COMMON
@end defun

@defun make-glob-fs-fold :key root-path current-path
@c EN
This is a utility function to generate a procedure suitable to
pass the @var{folder} keyword argument of @code{glob-fold} and @code{glob}.
Without arguments, this returns the same procedure which is used
in @code{glob-fold} and @code{glob} by default.
@c JP
これは@code{glob-fold}や@code{glob}の@var{folder}キーワード引数に
渡せる形の手続きを作るユーティリティ手続きです。
引数を渡さなければ、@code{glob-fold}や@code{glob}がデフォルトで使うのと
同じ手続きが返ります。
@c COMMON

@c EN
The keyword arguments @var{root-path} and @var{current-path} specify
the paths where @code{glob-fold} starts to search.
@c JP
キーワード引数@var{root-path}および@var{current-path}はそれぞれ、
@code{glob-fold}が探索を開始するディレクトリを指定します。
@c COMMON

@example
gosh> (glob "/tmp/*.scm")
("/tmp/x.scm" "/tmp/y.scm")
gosh> (glob "/*.scm" 
            :folder (make-glob-fs-fold :root-path "/tmp"))
("/tmp/x.scm" "/tmp/y.scm")
gosh> (glob "*.scm" 
            :folder (make-glob-fs-fold :current-path "/tmp"))
("/tmp/x.scm" "/tmp/y.scm")
@end example
@end defun

@c EN
@xref{File stats}, to check if a path is actually a directory.
@c JP
パスがディレクトリかどうかチェックする方法は、@ref{File stats}を参照してください。
@c COMMON

@node Directory manipulation, Pathnames, Directories, Filesystems
@subsubsection Directory manipulation
@c NODE ディレクトリ操作

@defun sys-remove filename
[POSIX] 
@c EN
If @var{filename} is a file it is removed.
On some systems this may also work on an empty directory,
but portable scripts shouldn't depend on it.
@c JP
@var{filename}がファイルであればそれを消去します。
システムによっては@var{filename}が空のディレクトリであっても動作しますが、
移植性を気にする場合はその動作に依存しない方が良いでしょう。
@c COMMON
@end defun

@defun sys-rename old new
[POSIX]
@c EN
Renames a file @var{old} to @var{new}.  The new name
can be in different directory from the old name, but both paths
must be on the same device.
@c JP
ファイル@var{old}を@var{new}にリネームします。新しい名前は
古い名前と異なるディレクトリにあってもかまいませんが、両者は同じデバイス上に
なければなりません。
@c COMMON
@end defun

@defun sys-tmpnam
[POSIX]
@c EN
Creates a file name which is supposedly unique, and returns it.
This is in POSIX, but its use is discouraged because of potential
security risk.  Use @code{sys-mkstemp} below if possible.
@c JP
ユニークなファイル名を作成して返します。この関数はPOSIXに含まれていますが、
セキュリティ上の問題が指摘されており、使わない方が良いとされています。
可能なら下にあげる@code{sys-mkstemp}を使って下さい。
@c COMMON
@end defun

@defun sys-mkstemp template
@c EN
Creates and opens a file that has unique name, and returns two values;
opened port and the created filename.  The file is created exclusively,
avoiding race conditions.   @var{template} is used as the prefix
of the file.  Unlike Unix's mkstemp, you don't need padding characters.
The file is opened for writing, and its permission is set to 600.
@c JP
ユニークな名前を持つファイルを作成してオープンし、オープンされたポートとファイル名の
二つの値を返します。ファイルは排他的に作成されるため、レースコンディションは起こりません。
@var{template}はファイル名のプレフィックスに使われます。Unixのmkstempと違って、
パディングキャラクタをつける必要はありません。ファイルは書き込み用としてオープンされ、
パーミッションは600にセットされます。
@c COMMON
@end defun

@defun sys-link existing new
[POSIX] 
@c EN
Creates a hard link named @var{new} to the existing file @var{existing}.
@c JP
既存のファイル@var{existing}に対し、@var{new}という名のハードリンクを作成します。
@c COMMON
@end defun

@defun sys-unlink pathname
[POSIX]
@c EN
Removes @var{pathname}.  It can't be a directory.
Returns @code{#t} if it is successfully removed, or
@var{#f} if @var{pathname} doesn't exist.
An error is signalled otherwise.
@c JP
@var{pathname}で示されるファイルを消去します。
@var{pathname}はディレクトリであってはなりません。
もし消去に成功したら@code{#t}が、@var{pathname}が存在しなければ@code{#f}が返されます。
他の場合はエラーが通知されます。
@c COMMON
@end defun

@defun sys-symlink existing new
@c EN
Creates a symbolic link named @var{new} to the pathname @var{existing}.
On systems that doesn't support symbolic links,
this function is unbound.
@c JP
@var{existing}を指す@var{new}という名のシンボリックを作成します。
シンボリックリンクをサポートしないシステムでは、この手続きは定義されません。
@c COMMON
@end defun

@defun sys-readlink path
@c EN
If a file specified by @var{path} is a symbolic link, its content is
returned.  If @var{path} doesn't exist or is not a symbolic link, an
error is signalled.
On systems that don't support symbolic links,
this function is unbound.
@c JP
@var{path}で示されるファイルがシンボリックリンクならば、それが指すパスを返します。
もし@var{path}が存在しなかったり、シンボリックリンクでなければ、エラーが通知されます。
シンボリックリンクをサポートしないシステムでは、この手続きは定義されません。
@c COMMON
@end defun

@defun sys-mkdir pathname mode
[POSIX] 
@c EN
Makes a directory @var{pathname} with mode @var{mode}.
(Note that @var{mode} is masked by the current umask;
see @code{sys-umask} below).
The parent directory of @var{pathname} must exist and be writable
by the process.  To create intermediate directories at once, use
@code{make-directory*} in @code{file.util} (@ref{Directory utilities}).
@c JP
ディレクトリ@var{pathname}をモード@var{mode}で作成します。
(@var{mode}はさらにumaskでマスクされることに注意して下さい；下の@code{sys-umask}
参照)。
@var{pathname}の親ディレクトリは存在して、プロセスが書き込めるようになっていなければ
なりません。中間のディレクトリも一度に作成するには、
@code{file.util}の@code{make-directory*}が使えます
(@ref{Directory utilities})。
@c COMMON
@end defun

@defun sys-rmdir pathname
[POSIX]
@c EN
Removes a directory @var{pathname}.  The directory must be empty.
To remove a directory with its contents, use @code{remove-directory*}
in @code{file.util} (@ref{Directory utilities}).
@c JP
ディレクトリ@var{pathname}を消去します。ディレクトリは空でなければなりません。
ディレクトリの内容も一緒に消去するには、@code{file.util}の@code{remove-directory*}
が使えます(@ref{Directory utilities})。
@c COMMON
@end defun

@defun sys-umask :optional mode
[POSIX] 
@c EN
Sets umask setting to @var{mode}.  Returns previous umask setting.
If @var{mode} is omitted or @code{#f}, just returns the current umask without
changing it.
See @code{man umask} for more details.
@c JP
umaskを@var{mode}にセットします。変更される前のumaskを返します。
@var{mode}が省略されるか@code{#f}が渡された場合、
現在のumaskを変更せずにその値を返します。
umaskについては@code{man umask}を参照してください。
@c COMMON
@end defun

@node Pathnames, File stats, Directory manipulation, Filesystems
@subsubsection Pathnames
@c NODE パス名

@c EN
See also @ref{Pathname utilities}, for high-level APIs.
@c JP
高レベルのAPIに関しては@ref{Pathname utilities}も参照して下さい。
@c COMMON

@defun sys-normalize-pathname pathname :key absolute expand canonicalize
@c EN
Converts @var{pathname} according to the way specified by keyword arguments.
More than one keyword argument can be specified.
@c JP
与えられたキーワード引数によって@var{pathname}を以下のように変換します。
キーワード引数は同時に複数指定できます。
@c COMMON
@table @code
@item absolute
@c EN
  If this keyword argument is given and true, and @var{pathname} is not
  an absolute pathname, it is converted to an absolute pathname by
  appending the current working directory in front of @var{pathname}.
@c JP
  このキーワード引数に真の値が与えられて、@var{pathname}が絶対パスでない場合、
  @var{pathname}の前にプロセスのワーキングディレクトリを足して絶対パスにします。
@c COMMON
@item expand
@c EN
  If this keyword argument is given and true, and @var{pathname} begins
  with `@code{~}', it is expanded as follows:
@c JP
  このキーワード引数に真の値が与えられて、@var{pathname}が`@code{~}' で始まっていた
  場合、以下のように展開されます。
@c COMMON
@itemize @bullet
@item
@c EN
    If @var{pathname} is consisted entirely by ``@code{~}'', or begins
    with ``@code{~/}'', then the character ``@code{~}'' is replaced
    for the pathname of the current user's home directory.
@c JP
    @var{pathname}が``@code{~}''のみであるか、または``@code{~/}''で始まっている
    場合、文字``@code{~}''が現在のプロセスのユーザのホームディレクトリに置き換えられます。
@c COMMON
@item
@c EN
    Otherwise, characters following `@code{~}' until either `@code{/}' or
    the end of @var{pathname} are taken as a user name, and the user's
    home directory is replaced in place of it.  If there's no such
    user, an error is signalled.
@c JP
    上記以外の場合、`@code{~}'以降、`@code{/}'か@var{pathname}の終端までの文字列
    がユーザ名とみなされ、そのユーザのホームディレクトリに置換されます。もし該当するユーザが
    いなければエラーとなります。
@c COMMON
@end itemize
@item canonicalize
@c EN
  Tries to remove pathname components ``@code{.}'' and ``@code{..}''.
  The pathname interpretation is done purely in textural level, i.e.
  it doesn't access filesystem to see the conversion reflects the
  real files.  It may be a problem if there's a symbolic links to
  other directory in the path.
@c JP
  パス名から ``@code{.}'' や ``@code{..}'' を除き、単純化します。
  この操作は実際のファイルシステムを参照せずに行われます。元のパス名がディレクトリへの
  シンボリックリンクを含んでいた場合、単純化されたパス名は正しくないかもしれません。
@c COMMON
@end table
@end defun

@defun sys-basename pathname
@defunx sys-dirname pathname
@c EN
@code{sys-basename} returns a basename, that is the last component of
@var{pathname}.  @code{sys-dirname} returns the components of @var{pathname}
but the last one.   If @var{pathname} has a trailing `@code{/}', 
it is simply ignored.
@c JP
@code{sys-basename}は与えられたパスのベース名、すなわち最後のコンポーネントを返します。
@code{sys-dirname}は与えられたパスのディレクトリ名、すなわち最後のコンポーネント以外の
コンポーネントを返します。@var{pathname}の末尾が`@code{/}'である場合、その文字は
無視されます。
@c COMMON
@example
(sys-basename "foo/bar/bar.z") @result{} "bar.z"
(sys-basename "coo.scm") @result{} "coo.scm"
(sys-basename "x/y/") @result{} "y"
(sys-dirname "foo/bar/bar.z") @result{} "foo/bar"
(sys-dirname "coo.scm") @result{} "."
(sys-dirname "x/y/") @result{} "x"
@end example
@c EN
These functions doesn't check if @var{pathname} really exists.
@c JP
この手続きは@var{pathname}が存在するかどうかはチェックしません。
@c COMMON

@c EN
Some boundary cases:
@c JP
特殊なケース：
@c COMMON
@example
(sys-basename "") @result{} ""
(sys-dirname "") @result{} "."

(sys-basename "/") @result{} ""
(sys-dirname "/") @result{} "/"
@end example
@c EN
Note: The above behavior is the same as Perl's @code{basename} and
@code{dirname}.   On some systems, the command @code{basename}
may return @code{"/"} for the argument @code{"/"}, and
@code{"."} for the argument @code{"."}.
@c JP
註：このふるまいはPerlの@code{basename}および@code{dirname}と同様です。
システムによっては、コマンドの@code{basename}は@code{"/"}に対して@code{"/"}を、
@code{"."}に対して@code{"."}を返すものがあります。
@c COMMON
@end defun

@defun sys-realpath pathname
@c EN
@code{sys-realpath} returns an absolute pathname of @var{pathname}
that does not include ``@code{.}'', ``@code{..}'' or symbolic links.
If @var{pathname} does not exist, it includes a dangling symbolic
link, or the caller doesn't have enough permission to access to
the path, an error is signalled.
@c JP
@code{sys-realpath}は``@code{.}'', ``@code{..}''およびシンボリックリン
クを含まない@var{pathname}の絶対パスを返します。@var{pathname}自体が存在しなかったり、
存在しないパスを指すシンボリックリンクが含まれていたり、関連するパスへのアクセス権限が
不足している場合はエラーが通知されます。
@c COMMON

@c EN
Note: the POSIX @code{realpath(3)} function is known to be unsafe, so
Gauche avoids using it and implements @code{sys-realpath} in its own.
@c JP
注：POSIXの@code{realpath(3)}は安全でない場合があるので、
Gaucheは内部でCランタイムの@code{realpath}を呼ばずに、
独自に@code{sys-realpath}の機能を実装しています。
@c COMMON
@end defun

@defun sys-tmpdir
@c EN
Returns the default directory name suitable to put temporary files.

On Unix-like systems, the environment variable @code{TMPDIR} and @code{TMP}
are first checked, then falls back to @code{/tmp}.

On Windows-native systems, it uses @code{GetTempPath} Windows API.
It checks environment variables @code{TMP}, @code{TEMP}, and 
@code{USERPROFILE} in this order, and falls back to Windows system
directory.

On both platforms, the returned pathname may not exist, or
may not be writable by the calling process.

In general, user programs and libraries are recommended to use
@code{temporary-directory} (@xref{Directory utilities}) instead;
@code{sys-tmpdir} should be used only
if you now the raw value the platform provides.
@c JP
一時ファイルを置くためのデフォルトのディレクトリ名を返します。

Unix系システムでは、環境変数@code{TMPDIR}と@code{TMP}がこの順でチェックされ、
フォールバックとして@code{/tmp}が返されます。

Windowsネイティブの環境では、@code{GetTempPath} Windows APIを呼びます。
これは環境変数@code{TMP}、@code{TEMP}、@code{USERPROFILE}を順に調べ、
いずれも定義されていなければWindowsシステムディレクトリを返します。

いずれのプラットフォームでも、返されたパス名は存在しないかもしれず、
また書き込み可能ではないかもしれないことに注意してください。

一般的に、ユーザプログラムやライブラリは@code{temporary-directory} 
(@ref{Directory utilities}参照) の方を利用するのが良いでしょう。
@code{sys-tmpdir}はプラットフォームが推奨する生の値を知りたい場合に
限り使ってください。
@c COMMON
@end defun

@node File stats, Other file operations, Pathnames, Filesystems
@subsubsection File stats
@c NODE ファイルの状態

@c EN
See also @ref{File attribute utilities}, for high-level APIs.
@c JP
高レベルのAPIに関しては@ref{File attribute utilities}も参照して下さい。
@c COMMON

@defun file-exists? path
@defunx file-is-regular? path
@defunx file-is-directory? path
@c EN
Returns true if @var{path} exists, is a regular file, or is a directory,
respectively.   The latter two returns false if @var{path} doesn't
exist at all.

These functions are built on top of primitive
system interfaces described below; I provide these for convenience
and compatibility (STk has the same functions).
@c JP
それぞれ、@var{path}が存在するか、存在してそれがレギュラーファイルであるか、
存在してそれがディレクトリであれば@code{#t}を返します。

これらの手続きは便利であり、STkとの互換性もあるので定義されていますが、
実体は下に説明されている低レベル手続きの上に作成されています。
@c COMMON
@end defun

@deftp {Builtin Class} <sys-stat>
@clindex sys-stat
@c EN
An object that represents @code{struct stat}, attributes of an
entry in the filesystem.   It has the following read-only slots.
@c JP
ファイルシステム内のエントリの属性を表す、@code{struct stat}のラッパー
オブジェクトです。以下に示す読みだし専用のスロットを持ちます。
@c COMMON

@defivar <sys-stat> type
@c EN
A symbol represents the type of the file.
@c JP
ファイルのタイプを示すシンボルです。
@c COMMON
@c EN
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{regular} @tab a regular file
@item @code{directory} @tab a directory
@item @code{character} @tab a character device
@item @code{block} @tab a block device
@item @code{fifo} @tab a fifo
@item @code{symlink} @tab a symbolic link
@item @code{socket} @tab a socket
@end multitable
@c JP
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{regular} @tab 通常のファイル
@item @code{directory} @tab ディレクトリ
@item @code{character} @tab キャラクタデバイス
@item @code{block} @tab ブロックデバイス
@item @code{fifo} @tab FIFO
@item @code{symlink} @tab シンボリックリンク
@item @code{socket} @tab ソケット
@end multitable
@c COMMON
@c EN
If the file type is none of the above, @code{#f} is returned.
@c JP
以上のどれにも当てはまらない場合は@code{#f}が返されます。
@c COMMON

@c EN
Note: Some operating systems don't have the @code{socket} file type
and returns @code{fifo} for socket files.   Portable programs should
check both possibilities to see if the given file is a socket.
@c JP
注：いくつかのオペレーティングシステムでは@code{socket}ファイルタイプを
@code{fifo}と区別せず、どちらに対しても@code{fifo}を返します。
ポータブルなプログラムを書くときは注意して下さい。
@c COMMON
@end defivar

@defivar <sys-stat> perm
@c EN
An exact integer for permission bits of @code{struct stat}.
It is the same as lower 9-bits of "mode" slot; provided for the convenience.
@c JP
パーミッションビットマスク。"mode"スロットの下位9ビットと同じですが、
便利なので独立したスロットとして提供されます。
@c COMMON
@end defivar

@defivar <sys-stat> mode
@defivarx <sys-stat> ino
@defivarx <sys-stat> dev
@defivarx <sys-stat> rdev
@defivarx <sys-stat> nlink
@defivarx <sys-stat> uid
@defivarx <sys-stat> gid
@defivarx <sys-stat> size
@c EN
An exact integer for those information of @code{struct stat}.
@c JP
@code{struct stat}の該当するフィールドの値。正確な整数です。
@c COMMON
@end defivar

@defivar <sys-stat> atime
@defivarx <sys-stat> mtime
@defivarx <sys-stat> ctime
@c EN
A number of seconds since Unix Epoch for those information of @code{struct stat}.
@c JP
@code{struct stat}の該当するフィールドの値を、Unix Epochからの秒数で。
@c COMMON
@end defivar
@end deftp

@defun sys-stat path
@defunx sys-fstat port-or-fd
[POSIX]
@c EN
Returns a @code{<sys-stat>} object of @var{path}, or
the underlying file of @var{port-or-fd}, which 
may be a port or a positive exact integer file descriptor, respectively.

If @var{path} is a symbolic link, a stat of the file the link points
to is returned from @code{sys-stat}.

If @var{port-or-fd} is not associated to a file, @code{sys-fstat} returns
@code{#f}.
@c JP
与えられたパス名@var{path}、またはポートかファイルディスクリプタ
@var{port-or-fd}で示されるファイルの情報を@code{<sys-stat>}オブジェクトで
返します。

@code{sys-stat}は、@var{path}がシンボリックリンクであった場合は
リンクの指す先のファイルに関する情報を返します。

@code{sys-fstat}は、@var{port-or-fd}がファイルに関係ないポートであった
場合は@code{#f}を返します。
@c COMMON
@end defun

@defun sys-lstat path
@c EN
Like @code{sys-stat}, but it returns a stat of a symbolic link
if @var{path} is a symbolic link.
@c JP
@code{sys-stat}と同じですが、@var{path}がシンボリックリンクであった
場合はリンクそのものの情報を返します。
@c COMMON
@end defun

@example
gosh> (describe (sys-stat "gauche.h"))
#<<sys-stat> 0x815af70> is an instance of class <sys-stat>
slots:
  type      : regular
  perm      : 420
  mode      : 33188
  ino       : 845140
  dev       : 774
  rdev      : 0
  nlink     : 1
  uid       : 400
  gid       : 100
  size      : 79549
  atime     : 1020155914
  mtime     : 1020152005
  ctime     : 1020152005
@end example

@defun sys-stat->mode stat
@defunx sys-stat->ino stat
@defunx sys-stat->dev stat
@defunx sys-stat->rdev stat
@defunx sys-stat->nlink stat
@defunx sys-stat->size stat
@defunx sys-stat->uid stat
@defunx sys-stat->gid stat
@defunx sys-stat->atime stat
@defunx sys-stat->mtime stat
@defunx sys-stat->ctime stat
@defunx sys-stat->file-type stat
@strong{Deprecated}.
@c EN
Use @code{slot-ref} to access information of @code{<sys-stat>} object.
@c JP
@code{<sys-stat>}オブジェクトの情報にアクセスするには@code{slot-ref}を
使って下さい。
@c COMMON
@end defun

@defun sys-access pathname amode
[POSIX]
@c EN
Returns a boolean value of indicating whether access of @var{pathname}
is allowed in @var{amode}.   This procedure signals an error
if used in a suid/sgid program (see the note below).
@var{amode} can be a combinations (logical or) of
following predefined flags.
@c JP
@var{pathname}へのアクセスが
@var{mode}に示されるモードで許可されているかどうかを示す真偽値を返します。
この手続きは、suid/sgidプログラムで使われるとエラーとなります(下記註参照)。
@var{mode}は以下に示す定数のコンビネーション(logical or)です。
@c COMMON
@table @code
@item R_OK
@vindex R_OK
@c EN
Checks whether @var{pathname} is readable by the current user.
@c JP
@var{pathname}をカレントユーザが読み出し可能かどうか
@c COMMON
@item W_OK
@vindex W_OK
@c EN
Checks whether @var{pathname} is writable by the current user.
@c JP
@var{pathname}へカレントユーザが書き込み可能かどうか
@c COMMON
@item X_OK
@vindex X_OK
@c EN
Checks whether @var{pathname} is executable (or searchable in case
@var{pathname} is a directory) by the current user.
@c JP
@var{pathname}をカレントユーザが実行可能かどうか(@var{pathname}が
ディレクトリの場合はサーチ可能かどうか)
@c COMMON
@item F_OK
@vindex F_OK
@c EN
Checks whether @var{pathname} exists or not, regardless of
the access permissions of @var{pathname}.  (But you need to have
access permissions of the directories containing @var{pathname}).
@c JP
@var{pathname}のパーミッションフラグにかかわらず、@var{pathname}が
存在するかどうか (但し@var{pathname}があるディレクトリの読みだし許可は必要)。
@c COMMON
@end table

@c EN
@emph{Note:} Access(2) is known to be a security hole if used
in suid/sgid program to check the real user's priviledge of
accessing the file.
@c JP
@emph{註:} access(2)は、suid/sgidプログラム中で
実ユーザの権限を確かめるために使われた場合、セキュリティホールと
なります。
@c COMMON
@end defun

@defun sys-chmod path mode
@defunx sys-fchmod port-or-fd mode
@c EN
Change the mode of the file named @var{path} or an opened
file specified by @var{port-or-fd} to @var{mode}.
@var{mode} must be a small positive integer whose lower 9 bits
specifies POSIX style permission.
@c JP
名前@var{path}を持つ、もしくは@var{port-or-fd}で指定される
ファイルのパーミッションビットを@var{mode}に変更します。
@var{mode}は小さな正の正確な整数で、POSIXスタイルのパーミッションビットマスク
でなければなりません。
@c COMMON
@end defun

@defun sys-chown path owner-id group-id
@c EN
Change the owner and/or group of the file named @var{path}
to @var{owner-id} and @var{group-id} respectively.
@var{owner-id} and @var{group-id} must be an exact integer.
If either of them is -1, the corresponding ownership is not changed.
@c JP
ファイル@var{path}のオーナーとグループを@var{owner-id}と@var{gruop-id}
で示されるものに変更します。@var{owner-id}と@var{gruop-id}は正確な整数で
なければなりません。どちらかに-1が渡された場合は、対応する情報は変更されません。
@c COMMON
@end defun

@defun sys-utime path :optional atime mtime
@c EN
Change the file's access time and modification time to @var{atime}
and @var{mtime}, respectively.   If @var{atime} and @var{mtime} is
omitted, they are set to the current time.
See also @code{touch-file} (@xref{File operations}).
@c JP
ファイルのアクセスタイムと変更タイムを@var{atime}と@var{mtime}が示す
値にセットします。@var{atime}と@var{mtime}が省略された場合は現在の時刻が
使われます。
@ref{File operations}の@code{touch-file}も参照して下さい。
@c COMMON
@end defun

@node Other file operations,  , File stats, Filesystems
@subsubsection Other file operations
@c NODE 他のファイル操作

@defun sys-chdir dir
[POSIX]
@c EN
An interface to @code{chdir(2)}. 
See also @code{current-directory} (@xref{Directory utilities}).
@c JP
@code{chdir(2)}へのインタフェースです。
@code{current-directory}(@ref{Directory utilities})も参照して下さい。
@c COMMON
@end defun

@defun sys-pipe :key (buffering :line)
@c EN
[POSIX] Creates a pipe, and returns two ports.
The first returned port is an input port and the second is an output port.
The data put to the output port can be read from the input port.
@c JP
[POSIX] パイプを作り、ポートを2つ返します。
最初に返されるポートは入力ポートで、2番目に返されるポートは出力ポートです。
出力ポートへ書き出したデータは、入力ポートから読み込めます。
@c COMMON

@c EN
@var{Buffering} can be @code{:full}, @code{:line} or @code{:none}, 
and specifies the buffering mode of the ports opened on the pipe.
@xref{File ports}, for details of the buffering mode.
The default mode is sufficient for typical cases.
@c JP
@var{buffering}は@code{:full}、@code{:line}、@code{:none}のいずれかで、
パイプ上に開かれたポートのバッファリングモードを指定します。
バッファリングモードの詳細については、@ref{File ports}を参照して下さい。
通常のケースでは、デフォルトのモードで間に合うでしょう。
@c COMMON

@example
(receive (in out) (sys-pipe)
  (display "abc\n" out)
  (flush out)
  (read-line in)) @result{} "abc"
@end example

@c EN
Note: the returned value is changed from version 0.3.15, in which
@code{sys-pipe} returned a list of two ports.
@c JP
注意: 戻り値はバージョン0.3.15から変更されています。それまでは、
@code{sys-pipe}は2つのポートのリストを返します。
@c COMMON
@end defun

@defun sys-mkfifo path mode
@c EN
[POSIX] creates a fifo (named pipe) with a name @var{path} and mode
@var{mode}.  @var{Mode} must be a positive exact integer to represent
the file mode.
@c JP
[POSIX] 名前が@var{path}でモードが@var{mode}のFIFO(名前付きパイプ)を
作ります。@var{mode}はファイルのモードを表す正の正確整数でなければ
なりません。
@c COMMON
@end defun

@defun sys-isatty port-or-fd
@c EN
[POSIX] @var{port-or-fd} may be a port or an integer file descriptor.
Returns @code{#t} if the port is connected to the console, @code{#f}
otherwise.
@c JP
[POSIX] @var{port-or-fd}はポートか整数のファイルディスクリプタです。
ポートがコンソールに接続されていれば@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun sys-ttyname port-or-fd
@c EN
[POSIX] @var{port-or-fd} may be a port or an integer file descriptor.
Returns the name of the terminal connected to the port,
or @code{#f} if the port is not connected to a terminal.
@c JP
[POSIX] @var{port-or-fd}はポートか整数のファイルディスクリプタです。
ポートに接続された端末の名前か、ポートが端末に接続されていなければ
@code{#f}を返します。
@c COMMON
@end defun

@defun sys-truncate path length
@defunx sys-ftruncate port-or-fd length
[POSIX]
@c EN
Truncates a regular file named by @var{path} or referenced by @var{port-or-fd}
to a size of @var{length} bytes.
If the file is larger than @var{length} bytes, the extra data is discarded.
If the file is smaller than that, zero is padded.
@c JP
@var{path}あるいは@var{port-or-fd}によって指定される通常ファイルの長さを
@var{length}にします。
ファイルが@var{length}より長かった場合、余分なデータは捨てられます。
ファイルが@var{length}より短かった場合、残りの部分にはゼロが詰められます。
@c COMMON
@end defun

@node Unix groups and users, Locale, Filesystems, System interface
@subsection Unix groups and users
@c NODE Unixのグループとユーザ

@subsubheading Unix groups

@deftp {Builtin Class} <sys-group>
@clindex sys-group
@c EN
Unix group information.  Has following slots.
@c JP
Unixのグループの情報です。以下のスロットを持ちます。
@c COMMON

@defivar <sys-group> name
@c EN
Group name.
@c JP
グループ名。
@c COMMON
@end defivar

@defivar <sys-group> gid
@c EN
Group id.
@c JP
グループID
@c COMMON
@end defivar

@defivar <sys-group> passwd
@c EN
Group password.
@c JP
グループパスワード。
@c COMMON
@end defivar

@defivar <sys-group> mem
@c EN
List of user names who are in this group.
@c JP
このグループに属するユーザ名のリスト。
@c COMMON
@end defivar

@end deftp

@defun sys-getgrgid gid
@defunx sys-getgrnam name
[POSIX]
@c EN
Returns @code{<sys-group>} object from an integer group id @var{gid}
or a group name @var{name}, respectively.
If the specified group doesn't exist, @code{#f} is returned.
@c JP
グループID@var{gid}もしくはグループ名@var{name}で示されるグループの情報を
@code{<sys-group>}で返します。該当するグループが存在しない場合は
@code{#f}が返されます。
@c COMMON
@end defun

@defun sys-gid->group-name gid
@defunx sys-group-name->gid name
@c EN
Convenience function to convert between group id and group name.
@c JP
グループIDとグループ名を相互変換する便利な手続きです。
@c COMMON
@end defun

@subsubheading Unix users

@deftp {Builtin Class} <sys-passwd>
@clindex sys-passwd
@c EN
Unix user information.  Has following slots.
@c JP
Unixのユーザの情報です。以下のスロットを持ちます。
@c COMMON

@defivar <sys-passwd> name
@c EN
User name.
@c JP
ユーザ名。
@c COMMON
@end defivar

@defivar <sys-passwd> uid
@c EN
User ID.
@c JP
ユーザID
@c COMMON
@end defivar

@defivar <sys-passwd> gid
@c EN
User's primary group id.
@c JP
ユーザのプライマリグループID。
@c COMMON
@end defivar

@defivar <sys-passwd> passwd
@c EN
User's (encrypted) password.  If the system uses the shadow password file,
you just get obscure string like "x".
@c JP
ユーザの(暗号化された)パスワード。システムがシャドウパスワードファイルを
使っている場合は、 "x" のような無意味な文字列が入っています。
@c COMMON
@end defivar

@defivar <sys-passwd> gecos
@c EN
Gecos field.
@c JP
Gecosフィールド。
@c COMMON
@end defivar

@defivar <sys-passwd> dir
@c EN
User's home directory.
@c JP
ユーザのホームディレクトリ。
@c COMMON
@end defivar

@defivar <sys-passwd> shell
@c EN
User's login shell.
@c JP
ユーザのログインシェル。
@c COMMON
@end defivar

@defivar <sys-passwd> class
@c EN
User's class (only available on some systems).
@c JP
ユーザのクラス。(特定のシステムでのみ有効)。
@c COMMON
@end defivar

@end deftp

@defun sys-getpwuid uid
@defunx sys-getpwnam name
[POSIX]
@c EN
Returns @code{<sys-passwd>} object from an integer user id @var{uid}
or a user name @var{name}, respectively.
If the specified user doesn't exist, @code{#f} is returned.
@c JP
ユーザID@var{uid}もしくはユーザ名@var{name}で示されるユーザの情報を
@code{<sys-passwd>}で返します。該当するユーザが存在しない場合は
@code{#f}が返されます。
@c COMMON
@end defun

@defun sys-uid->user-name uid
@defunx sys-user-name->uid name
@c EN
Convenience functions to convert between user id and user name.
@c JP
ユーザIDとユーザ名を相互変換する便利な手続きです。
@c COMMON
@end defun


@subsubheading Password encryption

@defun sys-crypt key salt
@c EN
This is the interface to @code{crypt(3)}.   @var{Key} and @var{salt}
must be a string, and an encrypted string is returned.
On systems where @code{crypt(3)} is not available, call to this
function signals an error.

This routine is only for the code that needs to check password
against the system's password database.
If you are building user database on your own, you @emph{must} use
@code{crypt.bcrypt} module (@xref{Password hashing}) instead of 
this routine.
@c JP
これは、@code{crypt(3)}へのインターフェースです。@var{key}と@var{salt}は
文字列でなければならず、暗号化された文字列が返されます。
@code{crypt(3)}が利用できないシステムでこの関数を呼ぶとエラーが通知されます。

このルーチンは、システムのパスワードデータベースを使ってパスワードチェックを
しなければならない時以外に使うべきではありません。独自のパスワードデータベースを
新たに作る場合は、@code{crypt.bcrypt}モジュール(@ref{Password hashing})を
使ってください。
@c COMMON
@end defun

@node Locale, Signal, Unix groups and users, System interface
@subsection Locale
@c NODE ロケール

@defun sys-setlocale category locale
[POSIX]
@c EN
Sets the locale of the category @var{category} to the locale @var{locale}.
@var{category} must be an exact integer; the following pre-defined
variables are available.  @var{locale} must be a string locale name.
Returns the locale name on success, or @code{#f} if the system
couldn't change the locale.
@c JP
カテゴリー@var{category}のロケールを@var{locale}にセットします。
@var{category}は整数でなければなりません；以下の変数が@var{category}の
ために定義されています。@var{locale}はロケールを表す文字列です。
成功した場合は新しいロケール名を、ロケールが変更できなかった場合は@code{#f}を
返します。
@c COMMON
@end defun

@defvar  LC_ALL
@defvarx LC_COLLATE
@defvarx LC_CTYPE
@defvarx LC_MONETARY
@defvarx LC_NUMERIC
@defvarx LC_TIME
@c EN
Predefined variables for possible @var{category} value of
@code{sys-setlocale}.
@c JP
@code{sys-setlocale}の@var{category}に渡せる数値を定義しています。
@c COMMON
@end defvar

@defun sys-localeconv
[POSIX]
@c EN
Returns an assoc list of various information for formatting numbers
in the current locale.
@c JP
現在のロケールで数値をフォーマットする際に必要な様々な情報をassoc listに
して返します。
@c COMMON
@end defun

@c EN
An example session.  It may differ on your system settings.
@c JP
例を示します。あなたのシステム設定によっては異なる結果になるかもしれません。
@c COMMON
@example
(sys-localeconv)
 @result{}
   ((decimal_point . ".") (thousands_sep . "")
    (grouping . "") (int_curr_symbol . "")
    (currency_symbol . "") (mon_decimal_point . "")
    (mon_thousands_sep . "") (mon_grouping . "")
    (positive_sign . "") (negative_sign . "")
    (int_frac_digits . 127) (frac_digits . 127)
    (p_cs_precedes . #t) (p_sep_by_space . #t)
    (n_cs_precedes . #t) (n_sep_by_space . #t)
    (p_sign_posn . 127) (n_sign_posn . 127))

(sys-setlocale LC_ALL "fr_FR")
 @result{} "fr_FR"

(sys-localeconv)
 @result{}
  ((decimal_point . ",") (thousands_sep . "")
   (grouping . "") (int_curr_symbol . "FRF ")
   (currency_symbol . "F") (mon_decimal_point . ",")
   (mon_thousands_sep . " ") (mon_grouping . "\x03\x03")
   (positive_sign . "") (negative_sign . "-")
   (int_frac_digits . 2) (frac_digits . 2)
   (p_cs_precedes . #f) (p_sep_by_space . #t)
   (n_cs_precedes . #f) (n_sep_by_space . #t)
   (p_sign_posn . 1) (n_sign_posn . 1))
@end example

@node Signal, System inquiry, Locale, System interface
@subsection Signal
@c NODE  シグナル

@c EN
Gauche can send out operating system's signals to the other processes
(including itself) and can handle the incoming signals.
@c JP
Gaucheでは、OSのシグナルを自分自身や他のプロセスに送ったり、
送られたシグナルを処理することができます。
@c COMMON

@c EN
In multithread environment, all threads share the signal
handlers, and each thread has its own signal mask.
See @ref{Signals and threads}, for details.
@c JP
マルチスレッド環境では、全てのスレッドがシグナルハンドラを共有し、
各スレッドが独自のシグナルマスクを持ちます。
詳しくは@ref{Signals and threads}を参照して下さい。
@c COMMON

@c EN
When a system call is interrupted by a signal,
and a programmer defines a handler for the signal that doesn't transfer
control to other context, the system call is restarted after
the handler returns.  
@c JP
システムコールがシグナルによって割り込まれ、
プログラマがシグナルハンドラをセットしており、そのハンドラが別コンテキストに
制御を移さずに戻った場合、そのシステムコールはハンドラからの復帰後に
リスタートされます。
@c COMMON

@c EN
On Windows native platforms, signals don't work except
some limited support of @code{sys-kill}.
@c JP
Windowsネイティブ環境では、@code{sys-kill}の限定的なサポートを
除いてシグナルは動作しません。
@c COMMON

@menu
* Signals and signal sets::     
* Sending signals::             
* Handling signals::            
* Masking and waiting signals::  
* Signals and threads::         
@end menu

@node Signals and signal sets, Sending signals, Signal, Signal
@subsubsection Signals and signal sets
@c NODE シグナルとシグナルセット

@c EN
Each signal is referred by its signal number (a small integer)
defined on the underlying operating system.
Variables are pre-defined to the system's signal number.
System's signal numbers may be architecture dependent, so you should
use those variables rather than using literal integers.
@c JP
シグナルはオペレーティングシステムで定義された小さな整数値で表現されます。
システムのシグナル番号に束縛された変数が定義されています。
システムのシグナル番号はアーキテクチャによって異なるので、
なるべく変数を利用するようにして下さい。
@c COMMON

@defvar  SIGABRT
@defvarx SIGALRM
@defvarx SIGCHLD
@defvarx SIGCONT
@defvarx SIGFPE
@defvarx SIGHUP
@defvarx SIGILL
@defvarx SIGINT
@defvarx SIGKILL
@defvarx SIGPIPE
@defvarx SIGQUIT
@defvarx SIGSEGV
@defvarx SIGSTOP
@defvarx SIGTERM
@defvarx SIGTSTP
@defvarx SIGTTIN
@defvarx SIGTTOU
@defvarx SIGUSR1
@defvarx SIGUSR2
@c EN
These variables are bound to the signal numbers of POSIX signals.
@c JP
これらの変数はPOSIXで定義された対応するシグナルの番号に束縛されています。
@c COMMON
@end defvar

@defvar  SIGTRAP
@defvarx SIGIOT
@defvarx SIGBUS
@defvarx SIGSTKFLT
@defvarx SIGURG
@defvarx SIGXCPU
@defvarx SIGXFSZ
@defvarx SIGVTALRM
@defvarx SIGPROF
@defvarx SIGWINCH
@defvarx SIGPOLL
@defvarx SIGIO
@defvarx SIGPWR
@c EN
These variables are bound to the signal numbers of system-dependent
signals.  Not all of them may be defined on some systems.
@c JP
これらの変数はシステム依存のシグナル番号に束縛されています。
全てのシステムで全てのシグナルがサポートされているわけではありません。
@c COMMON
@end defvar

@c EN
Besides each signal numbers, you can refer to a set of signals
using a @code{<sys-sigset>} object.
It can be used to manipulate the signal mask, and to install a signal
handler to a set of signals at once.
@c JP
それぞれのシグナル番号の他に、@code{<sys-sigset>}オブジェクトを使って
シグナルの集合を扱うことができます。シグナルの集合はシグナルマスクを操作したり、
ひとつのシグナルハンドラを多数のシグナルに同時に設定したりする際に使えます。
@c COMMON

@deftp {Class} <sys-sigset>
@clindex sys-sigset
@c EN
A set of signals.   An empty sigset can be created by
@c JP
シグナルの集合を表します。空のシグナルの集合は次の式で作成できます：
@c COMMON
@example
(make <sys-sigset>) @result{} #<sys-sigset []>
@end example
@end deftp

@defun sys-sigset signal @dots{}
@c EN
Creates and returns an instance of @code{<sys-sigset>}
with members @var{signal} @dots{}.  Each @var{signal} 
may be either a signal number, another @code{<sys-sigset>}
object, or @code{#t} for all available signals.
@c JP
@var{signal} @dots{}をメンバーとする@code{<sys-sigset>}の
インスタンスを作成して返します。
各@var{signal}にはシグナル番号、他の@code{<sys-sigset>}オブジェクト、あるいは
@code{#t}を渡すことができます。@code{#t}を渡した場合は全てのシグナルが
対象となります。
@c COMMON

@example
(sys-sigset SIGHUP SIGINT) @result{} #<sys-sigset [HUP|INT]>
@end example
@end defun

@defun sys-sigset-add! sigset signal @dots{}
@defunx sys-sigset-delete! sigset signal @dots{}
@c EN
@var{Sigset} must be a @code{<sys-sigset>} object.
Those procedures adds and removes the specified signals from
@var{sigset} respectively, and returns the result.  @var{sigset} itself
is also modified.

@var{signal} may be either a signal number, another @code{<sys-sigset>}
object, or @code{#t} for all available signals.
@c JP
@var{sigset}は@code{<sys-sigset>}オブジェクトでなければなりません。
これらの手続きは@var{sigset}に指定されたシグナルを追加、
もしくは@var{sigset}から指定されたシグナルを削除します。
変更された@var{sigset}が返されます。

@var{signal}にはシグナル番号、他の@code{<sys-sigset>}オブジェクト、あるいは
@code{#t}を渡すことができます。@code{#t}を渡した場合は全てのシグナルが
対象となります。
@c COMMON
@end defun

@defun sys-sigset-fill! sigset
@defunx sys-sigset-empty! sigset
@c EN
Fills @var{sigset} by all available signals, or empties @var{sigset}.
@c JP
システムで定義された全てのシグナルを@var{sigset}にセット、
もしくは@var{sigset}を空にします。
@c COMMON
@end defun

@defun sys-signal-name signal
@c EN
Returns the human-readable name of the given signal number.
(Note that signal numbers are system-dependent.)
@c JP
シグナル番号の名前を返します。(シグナル番号はシステムに依存します)。
@c COMMON

@example
(sys-signal-name 2) @result{} "SIGINT"
@end example
@end defun

@node Sending signals, Handling signals, Signals and signal sets, Signal
@subsubsection Sending signals
@c NODE シグナルの送出

@c EN
To send a signal, you can use @code{sys-kill} which works like
@code{kill(2)}.
@c JP
シグナルを送るには、@code{sys-kill}を使うことができます。
これはシステムの@code{kill(2)}のように動作します。
@c COMMON

@defun sys-kill pid sig
[POSIX]
@c EN
Sends a signal @var{sig} to the specified process(es).  @var{Sig}
must be a positive exact integer.  @var{pid} is an exact integer and
specifies the target process(es):
@c JP
シグナル@var{sig}を指定されたプロセス(群)に送ります。
@var{sig}は正確な正整数でなければなりません。@var{pid}は正確な整数でなければ
ならず、次のルールで対象となるプロセスを指定します。
@c COMMON
@itemize @bullet
@item
@c EN
If @var{pid} is positive, it is the target process id.
@c JP
@var{pid}が正ならば、それがそのまま対象となるプロセスIDです。
@c COMMON
@item
@c EN
If @var{pid} is zero, the signal is sent to every process in the process
group of the current process.
@c JP
@var{pid}がゼロならば、シグナルは現在のプロセスのプロセスグループ内の全ての
プロセスに送られます。
@c COMMON
@item
@c EN
If @var{pid} is less than -1, the signal is sent to every process in
the process group @var{-pid}.
@c JP
@var{pid}が-1より小さければ、シグナルはプロセスグループIDが@var{-pid}である
全てのプロセスに送られます。
@c COMMON
@end itemize

@c EN
On Windows native platforms, @code{sys-kill} may take positive integer
or a process handle (@code{<win:handle>} instance) as @var{pid}.
Only @code{SIGKILL}, @code{SIGINT} and @code{SIGABRT} are allowed
as @var{sig}; Gauche uses @code{TerminateProcess} to terminate
the target process for @code{SIGKILL},
and sends the target process
@code{CTRL_C_EVENT} and @code{CTRL_BREAK_EVENT} for
@code{SIGINT} and @code{SIGABRT}, respectively.
@c JP
Windowsネイティブ環境では、@code{sys-kill}は@var{pid}に正整数か
プロセスハンドル(@code{<win:handle>}のインスタンス)を取ります。
@var{sig}がサポートするのは@code{SIGKILL}、@code{SIGINT}、@code{SIGABRT}
のみです。@code{SIGKILL}に対しては@code{TerminateProcess}を使って
対象プロセスを終了させます。@code{SIGINT}と@code{SIGABRT}に対しては
対象プロセスにそれぞれ@code{CTRL_C_EVENT}と@code{CTRL_BREAK_EVENT}を
送ります。
@c COMMON
@end defun

@c EN
There's no Scheme equivalence for @code{raise()}, but you can use
@code{(sys-kill (sys-getpid) @var{sig})}.
@c JP
POSIXの@var{raise()}に対応するScheme関数はありませんが、
@code{(sys-kill (sys-getpid) @var{sig})} で同じことができます。
@c COMMON

@node Handling signals, Masking and waiting signals, Sending signals, Signal
@subsubsection Handling signals
@c NODE シグナルの処理

@c EN
You can register signal handling procedures in Scheme.
(In multithread environment, signal handlers are shared by all
threads; see @ref{Signals and threads} for details).
@c JP
Schemeでシグナルを処理する手続きを登録できます。
(マルチスレッド環境では、シグナルハンドラの設定は全てのスレッドで共有されます。
@ref{Signals and threads}を参照して下さい)。
@c COMMON

@c EN
When a signal is delivered to the Scheme process, the VM just records it
and processes it later at a 'safe point' where the state of VM is consistent.
We call the signal is @emph{pending} when it is registered by the VM
but not processed yet.
@c JP
シグナルがSchemeプロセスに送られると、VMはそれを記録し、
VMの状態が一貫している「安全なポイント」に達した時に処理します。
シグナルがVMに記録され、しかしまだ処理されていない状態を、
シグナルが保留されていると呼ぶことにします。
@c COMMON

@c EN
(Note that this makes handling of some signals such as @code{SIGILL}
useless, for the process can't continue sensible execution after
recording the signal).
@c JP
(このメカニズムのため、@code{SIGILL}のようなシグナルはSchemeレベルでは
処理できません。そのシグナルを記録した後でプロセスが意味のある処理を続行できない
からです)。
@c COMMON

@c EN
If the same signal is delivered more than once before VM processes
the first one, the second one and later have no effect.  (This is consistent
to the traditioncal Unix signal model.)  In other words,
for each VM loop a signal handler can be invoked at most once per
each signal.
@c JP
VMがシグナルを処理する前に同じシグナルが到着した場合、後に到着した方の
シグナルは無効になります。(これは伝統的なUnixのシグナル処理と同様です)。
言い替えれば、各VM loop毎に、シグナルハンドラは各シグナルについて
たかだか1回しか呼ばれません。
@c COMMON

@c EN
When too many signals of the same kind are pending, 
Gauche assumes something has
gone wrong (e.g. infinite loop inside C-routine) and aborts the
process.  The default of this limit is set rather low (3), to allow
unresponsive interactive script to be terminated by typing Ctrl-C
three times.  Note that the counter is individual for each signal;
Gauche won't abort if one @code{SIGHUP} and two @code{SIGINT}s are
pending, for example.  You can change this limit by 
@code{set-signal-pending-limit} described below.
@c JP
同じシグナルがたくさん保留された状態になった場合、
Gaucheは異常事態が起きたとみなし (例えばCルーチンで無限ループに
入った等)、プロセスをabortします。デフォルトではこの限界は
かなり低い値(3)に設定されています。これは、インタラクティブスクリプトが
反応しなくなった場合にCtrl-Cを3回打てば強制終了できる、という場合を
想定しているためです。この限界を調べるカウンタはシグナル毎にあるので、
例えば@code{SIGHUP}がひとつ、@code{SIGINT}がふたつ保留になった、
といった場合はabortしません。この限界は下で述べる@code{set-signal-pending-limit}
で変更することができます。
@c COMMON

@c EN
When you're using the @code{gosh} interpreter, the default
behavior for each signal is as in the following table.
@c JP
@code{gosh}インタプリタを使っている場合、デフォルトでのシグナルの処理は
次のように設定されています。
@c COMMON

@table @code
@item SIGABRT, SIGILL, SIGKILL, SIGCONT, SIGSTOP, SIGSEGV, SIGBUS
@c EN
Cannot be handled in Scheme.  @code{Gosh} follows the system's
default behavior.
@c JP
Schemeでは処理できません。@code{gosh}ではこれらのシグナルを受けると
システムのデフォルトの動作をします。
@c COMMON
@item SIGCHLD, SIGTSTP, SIGTTIN, SIGTTOU, SIGWINCH
@c EN
No signal handles are installed for these signals by @code{gosh},
       so the process follows the system's default behavior.
       Scheme programs can install its own signal handler if necessary.
@c JP
@code{gosh}は初期状態ではこれらのシグナルのハンドラを設定せず、
       システムのデフォルトの振るまいに任せます。Schemeプログラムは必要ならば
       これらのシグナルのハンドラを設定できます。
@c COMMON
@item SIGHUP, SIGQUIT, SIGTERM
@c EN
@code{Gosh} installs a signal handler for these signals
       that exits from the application with code 0.
@c JP
@code{gosh}はこれらのシグナルに対して、終了コード0でアプリケーションを
       終了するシグナルハンドラをセットします。
@c COMMON
@item SIGPWR, SIGXCPU, SIGUSR1, SIGUSR2
@c EN
On Linux platforms with thread support, these signals are used
       by the system and not available for Scheme.  On other systems,
       these signals behaves the same as described below.
@c JP
Linuxプラットフォームでスレッドを使用している場合は、
       これらのシグナルはシステムで使用されるため、Schemeからは使用できません。
       他のシステムではこれらのシグナルは下記の「他のシグナル」と同じ動作と
       なります。
@c COMMON
@c EN
@item other signals
@code{Gosh} installs the default signal handler, which raises
@code{<unhandled-signal-error>} condition (see @ref{Conditions}).
Scheme programs can override it by its own signal handler.
@c JP
@item 他のシグナル
@code{gosh}はデフォルトのシグナルハンドラを設定します。
デフォルトのシグナルハンドラは@code{<unhandled-signal-error>}コンディションを
通知します(@ref{Conditions}参照)。
Schemeプログラムはシグナル毎に独自のハンドラを設定することが可能です。
@c COMMON
@end table

@c EN
If you're using Gauche embedded in some other application,
it may redefine the default behavior.
@c JP
@code{gosh}でなく、他のアプリケーションに埋め込まれたGaucheを使っている場合、
Schemeレベルでのシグナルの使用をアプリケーションが制限している場合があります。
@c COMMON

@c EN
Use the following procedures to get/set signal handlers from Scheme.
@c JP
Schemeからシグナルハンドラを設定するには以下の手続きを使って下さい。
@c COMMON

@defun set-signal-handler! signals handler :optional sigmask
@c EN
@var{Signals} may be a single signal number or a @code{<sys-sigset>}
object, and @var{handler} should be either @code{#t}, @code{#f},
@code{#<undef>}, or a procedure that takes one argument.
If @var{handler} is a procedure, it will be called when the process
receives one of specified signal(s), with the received signal
number as an argument.

By default, the signals in @var{signals} are blocked
(in addition to the signal mask in effect at that time) during
@var{handler} is executed, so that @var{handler} won't be
reentered by the same signal(s).  You can provide 
a @code{<sys-sigset>} object to the @var{sigmask} arg
to specify the signals to be blocked explicitly.
Note that the signal mask
is per-thread; if more than one thread unblocks a signal, the handler
may still be invoked during execution of the handler (in other thread)
even if you specify @var{sigmask}.  You have to set the threads'
signal mask properly to avoid such situation.

It is safe to do anything in @var{handler}, including throwing
an error or invoking continuation captured elsewhere.  (However,
continuations captured inside @var{handler} will be invalid
once you return from @var{handler}).
@c JP
@var{signals}はシグナル番号か@code{<sys-sigset>}オブジェクト、
@var{handler}は@code{#t}、@code{#f}、@code{#<undef>}、
一つの引数を取る手続きのいずれかでなければなりません。
@var{handler}が手続きの場合、プロセスが指定されたシグナル(のうちのいずれか)を
受けた時に、そのシグナル番号を引数として@var{handler}が呼ばれます。

デフォルトでは、@var{handler}は、@var{signals}に含まれる
シグナルが(その時点で有効なシグナルマスクに加えて)ブロックされた状態で
実行されます。オプショナルな@var{sigmask}引数に
@code{<sys-sigset>}オブジェクトを渡すことで、
ブロックすべきシグナルを明示することもできます。
ただ、シグナルマスクはスレッド毎であることに注意して下さい。
もし複数のスレッドがあるシグナルをブロックしていない場合、例え@var{sigmask}
を指定していたとしても、ひとつのスレッドで@var{handler}を実行中に
別のスレッドで並行して@var{handler}が呼ばれる可能性はあります。
各スレッドのシグナルマスクを適切に設定することでそのようなケースを
避けるようにして下さい。

@var{handler}の中でできる操作にはほとんど制限がありません。
@var{handler}からエラーを投げたり、他の場所で補捉された継続を呼ぶことも
できます。但し、@var{handler}内で補捉した継続は@var{handler}から
戻った時点で無効になります。
@c COMMON

@c EN
If @var{handler} is @code{#t}, the operating system's default 
behavior is set to the specified signal(s).  If @var{handler}
is @code{#f}, the specified signals(s) will be ignored.
@c JP
@var{handler}が@code{#t}の場合、指定されたシグナルにはオペレーティングシステムの
デフォルトの振るまいが設定されます。
@var{handler}が@code{#f}の場合、指定されたシグナルは無視されます。
@c COMMON

@c EN
If @var{handler} is @code{#<undef>} (@xref{Undefined values}),
it indicates Gauche to leave the current OS's signal handler as it is.
This value isn't as much use in @code{set-signal-handler!} as
in @code{get-signal-handler}: If @code{#<undef>} is passed
to @code{set-signal-handler!}, it immeidately returns without
modifying anything.   However, if you get @code{#<undef>}
from @code{get-signal-handler}, you can know that the 
signal handler behavior hasn't been modified by Gauche.
(Note that once Gauche ever installs a signal handler,
there is no way to revert back to make @code{get-signal-handler}
reutrn @code{#<undef>}).
@c JP
@var{handler}が@code{#<undef>}
(@ref{Undefined values}参照) であった場合は、
Gaucheはその時点のOSレベルのシグナルハンドラを変更しません。
この引数は@code{set-signal-handler!}に対してはあまり
意味を持ちません; 何もせずに返るだけだからです。
しかし、@code{get-signal-handler}で@code{#<undef>}が
返った場合、Gaucheがそのシグナルハンドラを一度もいじっていないことを
示します。
(一度でもGaucheがシグナルハンドラをインストールした場合、
@code{get-signal-handler}が@code{#<undef>}を再び
返すことはありません。)
@c COMMON

@c EN
Note that signal handler setting is shared among threads in
multithread enviornment.  The handler is called from the thread
which is received the signal.  See @ref{Signals and threads}
for details.
@c JP
マルチスレッドプログラムでは、
シグナルハンドラの設定はスレッド間で共有されることに注意して下さい。
ハンドラはシグナルを受けたスレッドで実行されます。
詳しくは@ref{Signals and threads}を参照して下さい。
@c COMMON
@end defun

@defun get-signal-handler signum
@defunx get-signal-handler-mask signum
@c EN
Returns the handler setting, or signal mask setting, of a signal @var{signum},
respectively.  See @code{set-signal-handler!} for the meaning of
the return value of @code{get-signal-handler}.
@c JP
シグナル@var{signum}に設定されたハンドラもしくはシグナルマスクを
それぞれ返します。@code{get-signal-handler}が返す値の意味については
@code{set-signal-handler!}を参照してください。
@c COMMON
@end defun

@defun get-signal-handlers
@c EN
Returns an associative list of all signal handler settings.
Car of each element of returned list is a @code{<sys-sigset>} object,
and cdr of it is the handler (a procedure or a boolean value)
of the signals in the set.
@c JP
現在の全てのシグナルハンドラの設定を連想リストにして返します。
返されるリストの各要素のcarには@code{<sys-sigset>}オブジェクトが、
cdrにはそれらのシグナルに対応するハンドラ(手続きもしくはブール値)がセットされて
います。
@c COMMON
@end defun

@defun get-signal-pending-limit
@defunx set-signal-pending-limit limit
@c EN
Gets/sets the maximum number of pending signals per each signal type.
If the number of pending signals exceeds this limit, Gauche aborts
the process.  See the explanation at the beginning of this section
for the details.  @var{Limit} must be a nonnegative exact integer.
In the current implementaiton the maximum number of @var{limit} is 255.
Setting limit to zero makes the number of pending signals unlimited.
@c JP

@c COMMON
@end defun


@defmac with-signal-handlers (handler-clause @dots{}) thunk
@c EN
A convenience macro to install signal handlers temporarily
during execution of @var{thunk}.
(Note: though this is convenient, this has certain dangerous
properties described below.  Use with caution.)
@c JP
@var{thunk}の実行中だけシグナルハンドラを一時的に設定する便利なマクロです
(このマクロは便利ですが下に述べるような多少危険な性質もあるので、
注意して使って下さい)。
@c COMMON

@c EN
Each @var{Handler-clause} may be one of the following forms.
@table @code
@item (@var{signals} @var{expr} @dots{})
@var{Signals} must be an expression that will yield either a signal,
a list of signals, or a @code{<sys-sigset>} object.
Installs a signal handler for @var{signals} that evaluates
@var{expr} @dots{} when one of the signals in @var{signals} is delivered.

@item (@var{signals} => @var{handler})
This form sets the handler of @var{signals} to @var{handler},
where @var{handler} should be either @code{#t}, @code{#f}
or a procedure that takes one argument.

If @var{handler} is a procedure, it will be called when the process
receives one of specified signal(s), with the received signal
number as an argument.
If @var{handler} is @code{#t}, the operating system's default 
behavior is set to the specified signal(s).  If @var{handler}
is @code{#f}, the specified signals(s) will be ignored.
@end table
@c JP
@var{handler-clause}は以下のいずれかの形式です
@table @code
@item (@var{signals} @var{expr} @dots{})
@var{signals}は、評価された時に単独のシグナル番号、シグナル番号のリスト、
あるいは@code{<sys-sigset>}オブジェクトを生成する式でなければなりません。
@var{signals}に含まれるシグナルを受け取った時に、@var{expr} @dots{}を
評価するようなハンドラを設定します。

@item (@var{signals} => @var{handler})
@var{signals}は上と同じです。@var{signals}に含まれるシグナルに
対して、処理@var{handler}を設定します。

@var{handler}は@code{#t}、@code{#f}、一つの引数を取る手続きのいずれか
でなければなりません。
@var{handler}が手続きの場合、プロセスが指定されたシグナル(のうちのいずれか)を
受けた時に、そのシグナル番号を引数として@var{handler}が呼ばれます。
@var{handler}が@code{#t}の場合、指定されたシグナルにはオペレーティングシステムの
デフォルトの振るまいが設定されます。
@var{handler}が@code{#f}の場合、指定されたシグナルは無視されます。
@end table
@c COMMON

@c EN
When the control exits from @var{thunk}, the signal handler setting
before @code{with-signal-handlers} are recovered.
@c JP
@var{thunk}から制御が抜けた時に、@code{with-signal-handlers}が呼ばれた時点での
シグナルハンドラが再設定されます。
@c COMMON

@c EN
@emph{CAVEAT:} If you're setting more than one signal handlers,
they are installed in serial.  If a signal is delivered before
all the handlers are installed, the signal handler state may be
left inconsistent.  Also note that the handler setting is a global state;
you can't set "thread local" handler by @code{with-signal-handlers},
although the form may be misleading.
@c JP
@emph{注意：} このフォームで一つ以上のシグナルハンドラを設定する場合、
それらは順にシステムに設定されます。全てのハンドラの設定が終る前に
シグナルが届いた場合、シグナルハンドラの設定や再設定が不完全なままになる
かもしれません。また、シグナルハンドラはグローバルな設定であり、
「スレッドローカル」なハンドラを設定することはできませんが、
@code{with-signal-handlers}の形式はそれを誤解させるかもしれません。
@c COMMON
@end defmac

@node Masking and waiting signals, Signals and threads, Handling signals, Signal
@subsubsection Masking and waiting signals
@c NODE シグナルのマスクと待機

@c EN
A Scheme program can set a signal mask, which is a set of signals
to be blocked from delivery.   If a signal is delivered
which is completely blocked in the process, the signal becomes
"pending".  The pending signal may be delivered once the signal
mask is changed not to block the specified signal.
(However, it depends on the operating system whether the pending
signals are queued or not.)
@c JP
Schemeプログラムで、送出がブロックされるシグナルの集合であるシグナルマスク
をセットできます。プロセスで完全にブロックされるシグナルが送出されると、
そのシグナルは``保留''となります。保留されたシグナルは、指定されたシグナルを
ブロックしないようにシグナルマスクが変更されると送出されるかもしれません。
(しかし、保留されたシグナルがキューに入れられるかどうかはオペレーティング
システムに依存します。)
@c COMMON

@c EN
In multithread environment, each thread has its own signal mask.
@c JP
マルチスレッドの環境では、スレッド毎に独自のシグナルマスクを持ちます。
@c COMMON

@defun sys-sigmask how mask
@c EN
Modifies the current thread's signal mask, and returns the previous
signal mask.   @var{Mask} should be a @code{<sys-sigset>} object
to specify the new mask, or @code{#f} if you just want to query
the current mask without modifying one.

If you give @code{<sys-sigset>} object to @var{mask},
@var{how} argument should be one of the following
integer constants:
@c JP
現在のスレッドのシグナルマスクを変更し、以前のシグナルマスクを返します。
@var{mask}には新しいマスクを指定する@code{<sys-sigset>}オブジェクトか、
あるいはマスクを変更せず現在のマスクを得るだけなら@code{#f}を渡します。

@var{mask}に@code{<sys-sigset>}オブジェクトを渡した場合、
引数@var{how}は以下の整数定数のうちの1つでなければなりません。
@c COMMON
@table @code
@item SIG_SETMASK
@c EN
Sets @var{mask} as the thread's signal mask.
@c JP
@var{mask}をそのスレッドのシグナルマスクとしてセットします。
@c COMMON
@item SIG_BLOCK
@c EN
Adds signals in @var{mask} to the thread's signal mask.
@c JP
そのスレッドのシグナルマスクに@var{mask}にあるシグナルを追加します。
@c COMMON
@item SIG_UNBLOCK
@c EN
Removes signals in @var{mask} from the thread's signal mask.
@c JP
そのスレッドのシグナルマスクから@var{mask}にあるシグナルを削除します。
@c COMMON
@end table
@end defun

@defun sys-sigsuspend mask
@c EN
Atomically sets thread's signal mask to @var{mask} and
suspends the calling thread.  When a signal that is not blocked
and has a signal handler installed is delivered, the associated
handler is called, then @code{sys-sigsuspend} returns.
@c JP
アトミックに、スレッドのシグナルマスクを@var{mask}にセットし、
呼び出しているスレッドを一時停止します。ブロックされておらずシグナル
ハンドラがインストールされているシグナルが送出されると、関連
付けられたハンドラが呼ばれ、@code{sys-sigsuspend}は戻ります。
@c COMMON
@end defun

@defun sys-sigwait mask
[POSIX]
@c EN
@var{Mask} must be a @code{<sys-sigset>} object.
If any of signals in @var{mask} is/are pending in the OS,
atomically clears one of them and returns the signal number
of the cleared one.   If there's no signal in @var{mask}
pending, @code{sys-sigwait} blocks until any of the signals
in @var{mask} arrives.

You have to block all signals in @var{mask} in all threads
before calling @code{sys-sigwait}.  If there's a thread
that doesn't block the signals, the behavior of 
@code{sys-sigwait} is undefined.

Note: @code{Sys-sigwait} uses system's @code{sigwait} function,
whose behavior is not defined if there's a signal
handler on the signals it waits.  To avoid complication,
@code{sys-sigwait} resets the handlers set to the signals
included in @var{mask} before calling @code{sigwait} to @code{SIG_DFL},
and restores them after @code{sigwait} returns.  If another thread
changes signal handlers while @code{sys-sigwait} is waiting,
the behavior is undefined; you shouldn't do that.
@c JP
@var{mask}は@code{<sys-sigset>}オブジェクトでなければなりません。
アトミックに、保留されたシグナルから@var{mask}にあるシグナルの1つを
クリアし、クリアしたシグナルの番号を返します。@var{mask}にある
シグナルが1つも保留されていなければ、@code{sys-sigwait}はシグナルが
届くまでブロックします。

@code{sys-sigwait}を呼ぶ前に、@var{mask}にある全てのシグナルを、
全スレッドからブロックしておく必要があります。シグナルをブロックして
いないスレッドがある場合、@code{sys-sigwait}の動作は未定義です。

註：@code{sys-sigwait}はシステムの@code{sigwait}関数を呼び出しますが、
この関数は待つべきシグナルにシグナルハンドラが設定されていた場合の
振る舞いが未定義となっています。困ったことになるのを避けるために、
@code{sys-sigwait}はまず@var{mask}に含まれるシグナルに
ハンドラが設定されていたらそれを@code{SIG_DFL}にリセットしてから
@code{sigwait}を呼び出し、それが戻った後でハンドラを元に戻します。
@code{sys-sigwait}が待っている間に他のスレッドでシグナルハンドラを
変更してはいけません。そうした場合の動作は不定です。
@c COMMON
@end defun

@node Signals and threads,  , Masking and waiting signals, Signal
@subsubsection Signals and threads
@c NODE シグナルとスレッド

@c EN
The semantics of signals looks a bit complicated in the multithread
environment.   Nevertheless, it is pretty comprehensible once
you remember a small number of rules.  Besides,
Gauche sets up the default behavior easy to use,
while allowing programmers to do tricky stuff.
@c JP
シグナルのセマンティクスはマルチスレッド環境では少々複雑に見えます。
しかし、いくつかのルールを覚えてしまえば、とても理解しやすいものでも
あります。さらにGaucheでは、プログラマの簡単に使えるようにデフォルトの
振る舞いをセットアップしています。
@c COMMON

@c EN
If you don't want to be bothered by the details, just remember
one thing, with one sidenote.
@strong{By default}, signals are handled by the
primordial (main) thread.  However, if the main thread
is suspended on mutex or condition variable,
the signal may not be handled at all, so be careful.
@c JP
細かいことは知りたくないという場合は、
次の1つのことだけを覚えておいて下さい。
@strong{デフォルトでは}、シグナルはメインスレッドで処理されます。
しかし、メインスレッドがmutexや条件変数で一時停止している場合は、
シグナルは全く処理されないので注意が必要です。
@c COMMON

@c EN
Now, if you are curious about the details, here are the rules:
@c JP
詳細に興味がある場合は、ここにルールがあります。
@c COMMON
@itemize @bullet
@item
@c EN
The signal handler setting is shared by all threads.
@c JP
シグナルハンドラのセッティングは、全てのスレッドで共有されます。
@c COMMON
@item
@c EN
The signal mask is thread-specific.
@c JP
シグナルマスクはスレッド固有です。
@c COMMON
@item
@c EN
If a process receives an asynchronous signal (think it as a signal
delivered from other processes), one thread is chosen, out of
threads which don't block that signal.
@c JP
プロセスが非同期のシグナルを受け取ったら(他のプロセスからシグナルが
送出されたと考えて下さい)、そのシグナルをブロックしていないスレッドの
うちから任意の1つのスレッドが選ばれます。
@c COMMON
@item
@c EN
The signal handler is run on the chosen thread.
However, if the chosen thread is waiting for acquiring a mutex lock
or a condition variable, the handling of signal will be delayed
until the thread is restarted.   Signal delivery itself doesn't
restart the thread.
@c JP
シグナルハンドラは選択されたスレッドにおいて実行されます。
しかし、選択されたスレッドがmutexのロックの獲得や条件変数を待っている
場合は、シグナルの処理はそのスレッドが再開するまで遅延されます。
シグナルの送出自体はスレッドを再開しません。
@c COMMON
@end itemize

@c EN
Now, these rules have several implications.
@c JP
これらのルールにはいくつかの暗黙の了解があります。
@c COMMON

@c EN
If there are more than one thread that don't block a particular
signal, you can't know which thread receives the signal.
Such a situation is much less useful in Gauche than C programs
because of the fact that the signal handling can be delayed indefinitely
if the receiver thread is waiting on mutex or condition variable.
So, it is recommended to make sure, for each signal, there is only one
thread that can receive it.
@c JP
特定のシグナルをブロックしないスレッドが1つ以上ある場合、
どのスレッドがそのシグナルを受け取るかを知る術はありません。
そのような状況は、GaucheにおいてはCプログラムよりもさらに不便です。
なぜなら、受信側のスレッドがmutexや条件変数で待機している場合、
シグナル処理は無期限に遅延されうるからです。
したがって、それぞれのシグナルについて、それを受け取ることのできるスレッドが
常にただの1つしかないようにすることを推奨します。
@c COMMON

@c EN
In Gauche, all threads created by @code{make-thread}
(@xref{Thread procedures}) blocks all the signals by default
(except the reserved ones).   This lets all the signals
to be directed to the primordial (main) thread.
@c JP
Gaucheでは、@code{make-thread}(@ref{Thread procedures}参照)
で作られた全てのスレッドは、デフォルトで全てのシグナル(予約済みを除く)
をブロックします。これは、全てのシグナルがメインスレッドへ
送られるということです。
@c COMMON

@c EN
Another strategy is to create a thread dedicated for handling
signals.  To do so, you have to block the signals in the
primordial thread, then create the signal-handling thread,
and within that thread you unblock all the signals.
Such a thread can just loop on @code{sys-pause}.
@c JP
もう1つの戦略は、シグナル処理のみを行うスレッドを作る方法です。

もしシステムが@code{sys-sigwait}をサポートしていれば、ハンドル
したい全てのシグナルを全てのスレッドでブロックしておき、シグナル
処理専用のスレッドで@code{sys-sigwait}を呼び出してシグナルの
受信を待つことができます。@code{sys-sigwait}の返り値がシグナル番号
なので、その値でディスパッチしてください。この方法ではシグナル
ハンドラが呼び出されることはありません。

@code{sys-sigwait}を使わないのであれば、メインスレッドでシグナルを
ブロックして、シグナル処理専用スレッドを作り、そのスレッドで全ての
シグナルを受け付けることができます。そのようなスレッドは@code{sys-pause}
で単にループしていれば良いでしょう。@code{sys-pause}がシグナルで中断
されると、シグナルハンドラがシグナル処理専用スレッドで呼び出されます。
@c COMMON

@example
(thread-start!
  (make-thread
    (lambda ()
      (sys-sigmask SIG_SETMASK (make <sys-sigset>)) ;;empty mask
      (let loop () (sys-pause) (loop)))))
@end example

@c EN
Complicated application may want to control per-thread signal
handling precisely.   You can do so, just make sure that
at any moment only the designated thread unblocks the desired
signal.
@c JP
複雑なアプリケーションでは、正確にスレッド毎のシグナル処理を
制御したいかもしれません。それは、いつでも、指定されたスレッドのみが
望むシグナルをブロックしないようにすれば、可能です。
@c COMMON

@node System inquiry, Time, Signal, System interface
@subsection System inquiry
@c NODE システムへの問い合わせ

@defun sys-uname
@c EN
[POSIX] Returns a list of five elements,
@code{(@var{sysname} @var{nodename} @var{release} @var{version} @var{machine})}.
@c JP
[POSIX] 次の5要素のリストを返します。
@code{(@var{sysname} @var{nodename} @var{release} @var{version} @var{machine})}。
@c COMMON
@end defun

@defun sys-gethostname
@c EN
Returns the host name.  If the system doesn't have gethostname(),
the second element of the list returned by @code{sys-uname} is used.
@c JP
ホスト名を返します。システムでgethostname()が使えない場合、
@code{sys-uname}が返すリストの2番目の要素が使われます。
@c COMMON
@end defun

@defun sys-getdomainname
@c EN
Returns the domain name.  If the system doesn't have getdomainname(),
@code{"localdomain"} is returned.
@c JP
ドメイン名を返します。システムでgetdomainname()が使えない場合、
@code{"localdomain"}が返されます。
@c COMMON
@end defun

@defun sys-getcwd
@c EN
[POSIX] Returns the current working directory by a string.
If the current working directory couldn't be obtained from the system,
an error is signalled.   See also @code{sys-chdir}
 (@xref{Other file operations}), @code{current-directory}
(@xref{Directory utilities}).
@c JP
[POSIX] 現在の作業ディレクトリを文字列で返します。
システムから現在の作業ディレクトリが得られない場合は、エラーが通知されます。
@code{sys-chdir}(@ref{Other file operations}参照)、@code{current-directory}
(@ref{Directory utilities}参照)も参照して下さい。
@c COMMON
@end defun

@defun sys-getgid
@defunx sys-getegid
@c EN
[POSIX] Returns integer value of real and effective group id of the
current process, respectively.
Use @code{sys-gid->group-name} or @code{sys-getgrgid} to obtain 
the group's name and other information associated to the returned
group id (@xref{Unix groups and users}).
@c JP
[POSIX] 現在のプロセスの実グループIDと実効グループIDをそれぞれ整数で返します。
返されたグループIDからグループ名その他の情報を得るには
@code{sys-gid->group-name}や@code{sys-getgrgid}を使って下さい
(@ref{Unix groups and users}参照)。
@c COMMON
@end defun

@defun sys-setgid gid
@c EN
[POSIX] Sets the effective group id of the current process.
@c JP
[POSIX] 現在のプロセスの実効グループIDをセットします。
@c COMMON
@end defun

@defun sys-getuid
@defunx sys-geteuid
@c EN
[POSIX] Returns integer value of real and effective user id of the
current process, respectively.
Use @code{sys-uid->user-name} or @code{sys-getpwuid} to obtain 
the user's name and other information associated to the returned
user id (@xref{Unix groups and users}).
@c JP
[POSIX] 現在のプロセスの実ユーザIDと実効ユーザIDをそれぞれ整数で返します。
返されたユーザIDからユーザ名その他の情報を得るには
@code{sys-uid->user-name}や@code{sys-getpwuid}を使って下さい
(@ref{Unix groups and users}参照)。
@c COMMON
@end defun

@defun sys-setuid uid
@c EN
[POSIX] Sets the effective user id of the current process.
@c JP
[POSIX] 現在のプロセスの実効ユーザIDをセットします。
@c COMMON
@end defun

@defun sys-getgroups
@c EN
[POSIX] Returns a list of integer ids of supplementary groups.
@c JP
[POSIX] 補助的なグループのIDの整数のリストを返します。
@c COMMON
@end defun

@defun sys-getlogin
@c EN
[POSIX] Returns a string of the name of the user logged in on the
controlling terminal of the current process.
If the system can't determine the information, @code{#f} is returned.
@c JP
[POSIX] 現在のプロセスの制御端末にログインしているユーザの名前を文字列で
返します。システムがその情報を決定できない場合、@code{#f}が返されます。
@c COMMON
@end defun

@defun sys-getpgrp
@c EN
[POSIX] Returns a process group id of the current process.
@c JP
[POSIX] 現在のプロセスのプロセスグループIDを返します。
@c COMMON
@end defun

@c @defun sys-setpgrp
@c Sets the process group id of the current process to the current
@c process id.   Equivalent to @code{sys-setpgid(0, 0)}.
@c @end defun

@defun sys-getpgid pid
@c EN
Returns a process group id of the process specified by @var{pid}.
If @var{pid} is zero, the current process is used.
@c JP
@var{pid}で指定されたプロセスのプロセスグループIDを返します。
@var{pid}が0の場合、現在のプロセスが使われます。
@c COMMON

@c EN
Note that @code{getpgid()} call is not in POSIX.  If the system
doesn't have @var{getpgid()}, @var{sys-getpgid} still works if
@var{pid} is zero (it just calls @code{sys-getpgrp}), but signals
an error if @var{pid} is not zero.
@c JP
@code{getpgid()}はPOSIXではないことに注意して下さい。
システムに@var{getpgid()}がない場合、@var{pid}が0ならば
@var{sys-getpgid}がまだ動作しますが(それは単に@code{sys-getpgrp}を呼びます)
、@var{pid}が0でない場合はエラーが通知されます。
@c COMMON
@end defun

@defun sys-setpgid pid pgid
@c EN
[POSIX] Sets the process group id of the process @var{pid} to @var{pgid}.
If @var{pid} is zero, the process ID of the
current process is used.  If @var{pgid} is zero, the process ID
of the process specified by @code{pid} is used.  (Hence
@code{sys-setpgid(0, 0)} sets the process group id of the
current process to the current process id).
@c JP
[POSIX] プロセス@var{pid}のプロセスグループIDを@var{pgid}にセットします。
@var{pid}が0ならば、現在のプロセスのプロセスIDが使われます。
@var{pgid}が0ならば、@code{pid}で指定されたプロセスのプロセスIDが
使われます。
(したがって、@code{sys-getpgid(0, 0)}は、現在のプロセスのプロセス
グループIDを現在のプロセスIDにセットします。)
@c COMMON
@end defun

@defun sys-setsid
@c EN
[POSIX] Creates a new session if the calling process is
not a process group leader.
@c JP
[POSIX] 呼んでいるプロセスがプロセスグループリーダでなければ、
新しいセッションを作ります。
@c COMMON
@end defun

@defun sys-getpid
@defunx sys-getppid
@c EN
[POSIX] Returns the current process id and the parent process id,
respectively.
@c JP
[POSIX] 現在のプロセスIDと親プロセスのIDをそれぞれ返します。
@c COMMON
@end defun

@defun sys-times
[POSIX]
@end defun

@defun sys-ctermid
@c EN
[POSIX]  Returns the name of the controlling terminal of the process.
This may be just a @code{"/dev/tty"}.   See also @code{sys-ttyname}.
@c JP
[POSIX] プロセスの制御端末の名前を返します。
これは単に@code{``/dev/tty''}かもしれません。@code{sys-ttyname}も参照して下さい。
@c COMMON
@end defun

@defun sys-getrlimit resource
@defunx sys-setrlimit resource current :optional maximum
[POSIX] Get and set resource limits respectively.
@var{Resource} is an integer constant to specify the resource
of concern.  The following constants are defined.
(The constants marked as bsd and/or linux indicates that they
are not defined in POSIX but defined in BSD and/or Linux.
Other systems may or may not have them.  Consult @code{getrlimit}
manpage of your system for the details.)

@example
RLIMIT_AS                      RLIMIT_CORE
RLIMIT_CPU                     RLIMIT_DATA
RLIMIT_FSIZE                   RLIMIT_LOCKS
RLIMIT_MEMLOCK (bsd/linux)     RLIMIT_MSGQUEUE (linux)
RLIMIT_NICE (linux)            RLIMIT_NOFILE
RLIMIT_NPROC (bsd/linux)       RLIMIT_RSS (bsd/linux)
RLIMIT_RTPRIO (linux)          RLIMIT_SIGPENDING (linux)
RLIMIT_SBSIZE                  RLIMIT_STACK
RLIMIT_OFILE
@end example
@end defun


@defun sys-strerror errno
@c EN
@var{Errno} must be an exact nonnegative integer representing
a system error number.  This function returns a string describing
the error.
@c JP
@var{error}はシステムエラー番号を表現する非負正確整数でなければなりま
せん。この関数はエラーを説明する文字列を返します。
@c COMMON

@c EN
To represent @var{errno}, the following constants are defined.
Each constant is bound to an exact integer representing the system's
error number.  Note that the actual value may differ among systems,
and some of these constants may not be defined on some systems.
@c JP
@var{errno}を表現するのに、以下の定義済み定数が使えます。各定数はシス
テムエラーを表現する非負正確整数に束縛されています。実際の値はシステム
ごとに違い、またシステムによっては定義されていない定数があるということ
に注意してください。
@c COMMON

@example
E2BIG             EHOSTDOWN         ENETDOWN          ENXIO
EACCES            EHOSTUNREACH      ENETRESET         EOPNOTSUPP
EADDRINUSE        EIDRM             ENETUNREACH       EOVERFLOW
EADDRNOTAVAIL     EILSEQ            ENFILE            EPERM
EADV              EINPROGRESS       ENOANO            EPFNOSUPPORT
EAFNOSUPPORT      EINTR             ENOBUFS           EPIPE
EAGAIN            EINVAL            ENOCSI            EPROTO
EALREADY          EIO               ENODATA           EPROTONOSUPPORT
EBADE             EISCONN           ENODEV            EPROTOTYPE
EBADF             EISDIR            ENOENT            ERANGE
EBADFD            EISNAM            ENOEXEC           EREMCHG
EBADMSG           EKEYEXPIRED       ENOKEY            EREMOTE
EBADR             EKEYREJECTED      ENOLCK            EREMOTEIO
EBADRQC           EKEYREVOKED       ENOLINK           ERESTART
EBADSLT           EL2HLT            ENOMEDIUM         EROFS
EBFONT            EL2NSYNC          ENOMEM            ESHUTDOWN
EBUSY             EL3HLT            ENOMSG            ESOCKTNOSUPPORT
ECANCELED         EL3RST            ENONET            ESPIPE
ECHILD            ELIBACC           ENOPKG            ESRCH
ECHRNG            ELIBBAD           ENOPROTOOPT       ESRMNT
ECOMM             ELIBEXEC          ENOSPC            ESTALE
ECONNABORTED      ELIBMAX           ENOSR             ESTRPIPE
ECONNREFUSED      ELIBSCN           ENOSTR            ETIME
ECONNRESET        ELNRNG            ENOSYS            ETIMEDOUT
EDEADLK           ELOOP             ENOTBLK           ETOOMANYREFS
EDEADLOCK         EMEDIUMTYPE       ENOTCONN          ETXTBSY
EDESTADDRREQ      EMFILE            ENOTDIR           EUCLEAN
EDOM              EMLINK            ENOTEMPTY         EUNATCH
EDOTDOT           EMSGSIZE          ENOTNAM           EUSERS
EDQUOT            EMULTIHOP         ENOTSOCK          EWOULDBLOCK
EEXIST            ENAMETOOLONG      ENOTTY            EXDEV
EFAULT            ENAVAIL           ENOTUNIQ          EXFULL
EFBIG
@end example
@end defun

@node Time, Process management, System inquiry, System interface
@subsection Time
@c NODE 時間

@c EN
Gauche has two representations of time, one is compatible to POSIX API,
and the other is compatible to SRFI-18, SRFI-19 and SRFI-21.
Most procedures accept both representations; if not, the representation
the procedure accepts is indicated as either 'POSIX time' or 'SRFI time'.
@c JP
Gaucheでは時間は2種類の表現を持ちます。ひとつはPOSIX APIとコンパチブルな
表現で、もう一つはSRFI-18、SRFI-19、SRFI-21とコンパチブルな表現です。
多くの手続きはどちらの表現も理解しますが、そうでない場合は
適用可能な表現を'POSIX time'または'SRFI time'と表記します。
@c COMMON

@c EN
POSIX time is represented by a real number which is a number of seconds
since Unix Epoch (Jan 1, 1970, 0:00:00GMT).
Procedure @code{sys-time}, which corresponds to POSIX @code{time(2)},
returns this time representation.
@c JP
POSIX timeは実数で、Unix Epoch(Jan 1, 1970, 0:00:00GMT)からの秒数で
表現されます。POSIXの@code{time(2)}に対応する@code{sys-time}手続きは
この表現を返します。
@c COMMON

@c EN
SRFI-compatible time is represented by an object of @code{<time>} class,
which keeps seconds and nanoseconds, as well as the type of the time
(UTC, TAI, duration, process time, etc).
@code{Current-time} returns this representation.
@c JP
SRFI互換の時間は@code{<time>}クラスのインスタンスとして表現され、
秒、およびナノ秒のスロットを持ちます。
また、時間の種別(UTC、TAI、期間、プロセス時間、他)も保持しています。
@code{Current-time}はこの表現を返します。
@c COMMON

@subsubheading POSIX time

@defun sys-time
@c EN
[POSIX] Returns the current time in POSIX time
(the time since Epoch (00:00:00 UTC, January 1, 1970),
measured in seconds).  It may be a non-integral number, depending on
the architecture.

Note that POSIX's definition of ``seconds since the Epoch'' doesn't
take leap seconds into account.
@c JP
[POSIX] 現在の時間を POSIX 時間(エポック(00:00:00 UTC, January 1, 1970)
からの秒数)で返します。マシンのアーキテクチャによっては、不正確数で
あるかもしれません。
@c COMMON
@end defun

@defun sys-gettimeofday
@c EN
Returns two values.  The first value is a number of seconds,
and the second value is a fraction in a number of microseconds,
since 1970/1/1 0:00:00 UTC.   If the system doesn't have
@code{gettimeofday} call, this function calls @code{time()};
in that case, microseconds portion is always zero.
@c JP
2つの値を返します。1970/1/1 0:00:00 UTC を基準として、
1つ目の値は秒数、2つ目の値は端数をマイクロ秒で表したものです。
システムが @code{gettimeofday} 呼び出しをサポートしていない場合、
この手続きは @code{time()} を呼び出し、その場合はマイクロ秒の
部分はいつも 0 です。
@c COMMON
@end defun

@deftp {Builtin Class} <sys-tm>
@clindex sys-tm
@c EN
Represents @code{struct tm}, a calendar date.  It has the following slots.
@c JP
カレンダーである、@code{struct tm} を表します。以下のスロットを持ちます。
@c COMMON
@defivar <sys-tm> sec
@c EN
Seconds. 0-61.
@c JP
秒。0-61。
@c COMMON
@end defivar
@defivar <sys-tm> min
@c EN
Minutes. 0-59.
@c JP
分。0-59。
@c COMMON
@end defivar
@defivar <sys-tm> hour
@c EN
Hours.  0-23.
@c JP
時。0-23。
@c COMMON
@end defivar
@defivar <sys-tm> mday
@c EN
Day of the month, counting from 1.  1-31.
@c JP
月の日。1 から数える。1-31。
@c COMMON
@end defivar
@defivar <sys-tm> mon
@c EN
Month, counting from 0.  0-11.
@c JP
月。0 から数える。0-11。
@c COMMON
@end defivar
@defivar <sys-tm> year
@c EN
Years since 1900, e.g. 102 for the year 2002.
@c JP
1900年からの年数。例えば、102 なら 2002年。
@c COMMON
@end defivar
@defivar <sys-tm> wday
@c EN
Day of the week.  Sunday = 0 .. Saturday = 6.
@c JP
曜日。日曜は 0 .. 土曜は 6。
@c COMMON
@end defivar
@defivar <sys-tm> yday
@c EN
Day of the year.  January 1 = 0 .. December 31 = 364 or 365.
@c JP
1年の中での日数。1月1日は 0 .. 12月31日は 364 か 365。
@c COMMON
@end defivar
@defivar <sys-tm> isdst
@c EN
A flag that indicates if the daylight saving time is in effect.
Positive if DST is in effect, zero if not, or negative if unknown.
@c JP
夏時間が有効であるかどうかを指定するフラグ。有効なら正の数、無効なら 0、
分からなければ負の数。
@c COMMON
@end defivar
@end deftp

@defun sys-gmtime time
@defunx sys-localtime time
@c EN
[POSIX] Converts @var{time} to @code{<sys-tm>} object, represented in GMT
or local timezone, respectively.   @var{Time} can be either POSIX-time or
SRFI-time.
@c JP
[POSIX] @var{time} を @code{<sys-tm>} オブジェクトに変換します。
標準時での表現かローカルタイムゾーンでの表現かで使い分けます。
@var{Time} は POSIX 時間か SRFI 時間です。
@c COMMON
@end defun

@defun sys-ctime time
@c EN
[POSIX] Converts @var{time} to it string representation, using POSIX ctime().
@var{Time} can be either POSIX-time or SRFI-time.
@c JP
[POSIX] @var{time} を POSIX の ctime() を使って文字列表現に変換します。
@var{Time} は POSIX 時間か SRFI 時間です。
@c COMMON
@end defun

@defun sys-difftime time1 time0
@c EN
[POSIX] Returns the difference of two times in the real number of seconds.
@var{Time0} and @var{time1} can be either POSIX-time or SRFI-time.
@c JP
[POSIX] 2つの時間の差を、秒の実数で返します。@var{Time0} と@var{time1} は
POSIX 時間か SRFI 時間です。
@c COMMON
@end defun

@defun sys-asctime tm
@c EN
[POSIX] Converts @code{<sys-tm>} object @var{tm} to a string representation.
@c JP
[POSIX] @code{<sys-tm>} オブジェクトである @var{tm} を文字列表現に変換します。
@c COMMON
@end defun

@defun sys-strftime format tm
@c EN
[POSIX] Converts @code{<sys-tm>} object @var{tm} to a string representation,
according to a format string @var{format}.
@c JP
[POSIX] @code{<sys-tm>} オブジェクトである @var{tm} を、フォーマット文字列
@var{format} に従って文字列表現に変換します。
@c COMMON
@end defun

@defun sys-mktime tm
@c EN
[POSIX] Converts @code{<sys-tm>} object @var{tm}, expressed as local time,
to the POSIX-time (number of seconds since Epoch).
@c JP
[POSIX] ローカルタイムとして表現された @code{<sys-tm>} オブジェクトである
@var{tm} を POSIX 時間(エポックからの秒数)に変換します。
@c COMMON
@end defun

@defun sys-tm->alist tm
(Deprecated function)
@end defun


@subsubheading SRFI time

@deftp {Builtin Class} <time>
@c EN
The @code{<time>} object also represents a point of time.
@c JP
ある時刻を表す@code{<time>}オブジェクトです。
@c COMMON

@clindex time
@defivar <time> type
@c EN
Indicates time type.  @code{time-utc} is the default, and that
represents the number of seconds since Unix Epoch.
SRFI-19 (@xref{Time data types and procedures}) adds more types.
@c JP
timeの型を表します。デフォルトは@code{time-utc}で、Unixエポックからの
秒数を表します。SRFI-19(@ref{Time data types and procedures}参照)
ではさらに型が追加されています。
@c COMMON
@end defivar
@defivar <time> second
@c EN
Second part of the time.
@c JP
timeの秒の部分です。
@c COMMON
@end defivar
@defivar <time> nanosecond
@c EN
Nanosecond part of the time.
@c JP
timeのナノ秒の部分です。
@c COMMON
@end defivar
@end deftp

@defun current-time
@c EN
[SRFI-18][SRFI-21]
Returns the @code{<time>} object representing the current time in
@code{time-utc}.   @xref{Time data types and procedures}, for
it redefines @code{current-time} to allow optional argument to
specify time type.
@c JP
[SRFI-18][SRFI-21]
現在の時間を@code{time-utc}で表す@code{<time>}オブジェクトを返します。
@ref{Time data types and procedures}では、@code{current-time}が再定義され、
timeの型を指定するオプショナル引数を受け付けるようにされています。
@c COMMON
@end defun

@defun time? obj
@c EN
[SRFI-18][SRFI-19][SRFI-21]
Returns @code{#t} if @var{obj} is a time object.
@c JP
[SRFI-18][SRFI-19][SRFI-21]
@var{obj}がtimeオブジェクトなら@code{#t}を返します。
@c COMMON
@end defun

@defun time->seconds time
@defunx seconds->time seconds
@c EN
[SRFI-18][SRFI-21]
Converts between time object and the number of seconds (POSIX-time).
@var{Time} argument of @code{time->seconds} has to be a @code{<time>} object.
@c JP
[SRFI-18][SRFI-21]
timeオブジェクトと秒数(POSIX時間)を変換します。
@code{time->seconds}の引数@var{time}は、@code{<time>}オブジェクトで
なければなりません。
@c COMMON
@end defun


@node Process management, I/O multiplexing, Time, System interface
@subsection Process management
@c NODE プロセス管理

@c EN
The following procedures provide pretty raw, direct interface
to the system calls.
See also @ref{High Level Process Interface}, which provides
more convenient process handling on top of these primitives.
@c JP
以下の手続きは、システムコールに対する直接的なインタフェースを提供します。
@ref{High Level Process Interface}も合わせて参照して下さい。
より高レベルの便利な手続きが定義されています。
@c COMMON

@subsubheading Fork and exec

@defun sys-system command
@c EN
[POSIX]
Runs @var{command} in a subprocess.   @var{command} is usually passed
to @code{sh}, so the shell metacharacters are interpreted.
@c JP
[POSIX]
サブプロセスで@var{command}を実行します。@var{command}は通常、
@code{sh}へ渡されるので、シェルのメタキャラクタは解釈されます。
@c COMMON

@c EN
This function returns an integer value @code{system()} returned.
Since POSIX doesn't define what @code{system()} returns, you can't
interpret the returned value in a portable way.
@c JP
この関数は、@code{system()}が返した整数値を返します。
POSIXは@code{system()}が何を返すかを定義していないので、
戻り値をポータブルな方法で解釈することができません。
@c COMMON

@c EN
On Windows native platforms this will pass the argument to @code{cmd.exe}.
@c JP
Windowsネイティブな環境では、引数は@code{cmd.exe}に渡されます。
@c COMMON
@end defun

@defun sys-fork
@c EN
[POSIX]
Fork the current process.  Returns 0 if you're in the child process,
and a child process' pid if you're in the parent process.
All the opened file descriptors are shared between the parent and
the child.  See @code{fork(2)} of your system for details.
@c JP
[POSIX]
現在のプロセスをフォークします。子プロセスにいるならば0が返り、
親プロセスにいるならば子プロセスのプロセスIDが返ります。
全ての開かれているファイルディスクリプタは、親プロセスと子プロセスで
共有されます。詳細は、システムの@code{fork(2)}を参照して下さい。
@c COMMON

@c EN
If the child process runs some Scheme code and exits instead of
calling @code{sys-exec}, it should call @code{sys-exit} 
instead of @code{exit} to terminate itself.
Normal exit call tries to flush the file
buffers, and on some OS it messes up the parent's file buffers.
@c JP
子プロセスが@code{sys-exec}を呼ぶ代わりにSchemeコードを実行して
終了する場合は、@code{exit}ではなく@code{sys-exit}を呼ぶ必要があります。
通常のexitの呼び出しはファイルバッファのフラッシュを試み、
OSによっては親のファイルバッファを混乱させるでしょう。
@c COMMON

@c EN
It should be noted that @code{sys-fork} is not safe when 
multiple threads are running.  Because @code{fork(2)} copies
the process' memory image which includes any mutex state,
a mutex which is locked by another thread at the time of @code{sys-fork}
remains locked in the child process, nevertheless the child process
doesn't have the thread that unlock it!
(This applies to the internal mutexes as well, so even you don't
use Scheme mutex explicitly, this situation can always happen.)

If what you want is to spawn another program in a multi-threaded application,
use @code{sys-fork-and-exec} explained below.
If you absolutely need to run Scheme code in the
child process, a typical technique is that you fork a manager process
at the beginning of application, and whenever you need a new process
you ask the manager process to fork one for you.
@c JP
@code{sys-fork}は複数のスレッドが走っている時には安全ではないことに
注意してください。@code{fork(2)}システムコールはプロセスのメモリイメージを
複製しますが、それには他のスレッドでロックされているmutexも含まれます。
もし@code{sys-fork}の瞬間に他のスレッドが何かをロックしていたとすれば、
子プロセスでもその資源はロックされたままになりますが、
その時子プロセスはもはやその資源をアンロックするスレッドを持っていません。
(これは内部で使っているmutexにも起こり得るため、Schemeレベルでmutexを
全く使っていないとしても防ぐことはできません)。

やりたいことが、マルチスレッドアプリケーションで別プログラムをspawnする
ことであるなら、下に説明する@code{sys-fork-and-exec}を使ってください。
どうしても別プロセスでSchemeコードを走らせたいのなら、よくある方法は、
アプリケーションの起動後すぐにマネージャプロセスとなる子プロセスをfork
しておき、新たなプロセスが欲しくなったらそのマネージャプロセスに
forkを依頼するという方法です。
@c COMMON

@c EN
This procedure is not available on Windows native platforms.
@c JP
Windowsネイティブな環境ではこの手続きは使えません。
@c COMMON
@end defun

@defun sys-exec command args :key directory iomap sigmask
@c EN
[POSIX+]
Execute @var{command} with @var{args}, a list of arguments.
The current process image is replaced by @var{command},
so this function never returns.
@c JP
[POSIX+]
@var{command}を引数のリストである@var{args}を伴って実行します。
現在のプロセスイメージは@var{command}に置き換えられるので、
この関数は戻りません。
@c COMMON

@c EN
All elements of @var{args} must be strings.  The first element of
@var{args} is used as @code{argv[0]}, i.e. the program name.
@c JP
@var{args}の全ての要素は文字列でなければなりません。
@var{args}の最初の要素は、@code{argv[0]}、すなわちプログラム名として
使われます。
@c COMMON

@c EN
The keyword argument @var{directory} must be a string of a
directory name or @code{#f}.
If it is a string, @code{sys-exec} change current working directory
there before executing the program.
@c JP
キーワード引数@var{directory}は文字列によるディレクトリ名
か@code{#f}でなければなりません。
文字列だった場合、@code{sys-exec}はプログラムを実行する前に
カレントワーキングディレクトリを指定ディレクトリに移動します。
@c COMMON

@c EN
The @var{iomap} keyword argument, when provided, specifies how the
open file descriptors are treated.  It must be the following format:
@c JP
キーワード引数の@var{iomap}は、与えられた場合は、開かれている
ファイルディスクリプタがどのように扱われるかを指定します。
この引数は以下のフォーマットでなければなりません。
@c COMMON
@example
((@i{to-fd} . @i{from-port-or-fd}) @dots{})
@end example
@c EN
@i{To-fd} must be an integer,
and @i{from-port-or-fd} must be an integer file descriptor or a port.
Each element of the list makes the file descriptor of @i{from-port-or-fd}
of the current process be mapped to the file descriptor @i{to-fd}
in the executed process.
@c JP
@i{to-fd}は整数でなければならず、@i{from-port-or-fd}は整数のファイル
ディスクリプタかポートでなければなりません。
リストのそれぞれの要素は、現在のプロセスの@i{from-port-or-fd}の
ファイルディスクリプタを、実行されているプロセスのファイルディスクリプタ
@i{to-fd}にマップさせます。
@c COMMON

@c EN
If @var{iomap} is provided,
any file descriptors other than specified in the iomap list will be closed
before @code{exec()}.  Otherwise, all file descriptors in the current
process remain open.
@c JP
@var{iomap}が与えられると、iomapリストで指定されていないいかなるファイル
ディスクリプタも@code{exec()}の前に閉じられます。さもなければ、現在のプロセスの
全てのファイルディスクリプタは開かれたままになります。
@c COMMON

@example
(sys-exec "ls" '("ls" "-l")) @result{} ;; ls is executed.

(let ((out (open-output-file "ls.out")))
  (sys-exec "ls" '("ls" "-l") :iomap `((2 . 1) (1 . ,out)))
   @result{}
  ;; ls is executed, with its stderr redirected
  ;; to the current process's stdout, and its
  ;; stdout redirected to the file "ls.out".
@end example

@c EN
The @var{sigmask} keyword argument can be an instance of @code{<sys-sigset>}
or @code{#f} (@xref{Signal}, for the details of signal masks).
If it is an instance of @code{<sys-sigset>}, the signal mask of calling
thread is replaced by it just before @code{exec(2)} is called.
It is useful, for example, to run an external program from a thread where
all signals are blocked (which is the default; see @ref{Signals and threads}).
Without setting @var{sigmask}, the @code{exec}ed process inherits 
calling thread's signal mask and become a process that blocks all signals,
which is not very convenient in most cases.
@c JP
@var{sigmask}キーワード引数には、@code{<sys-sigset>}のインスタンスか
@code{#f}を渡すことができます (シグナルマスクについては@xref{Signal}を
参照して下さい)。@code{<sys-sigset>}のインスタンスを渡した場合、
この関数を呼び出したスレッドのシグナルマスクが、@code{exec(2)}を呼ぶ
直前にそれによって置き換えられます。
これは、全てのシグナルをブロックしているスレッドから外部プログラムを走らせる
ような場合に便利です (@ref{Signals and threads}で述べるように、
新たなスレッドは全てのシグナルをデフォルトでブロックします)。
このような場合に@var{sigmask}を設定しないと、@code{exec}されたプロセスは
スレッドのシグナルマスクを継承し、ほとんどのシグナルを受け付けないプロセスと
なってしまうからです。通常、それはあまり便利ではありません。
@c COMMON

@c EN
When @code{sys-exec}
encounters an error, most of the time it raises an error condition.
Once the file descriptors are permuted, however, it would be impractical
to handle errors in reasonable way (you don't even know stderr is still
available!), so Gauche simply exits on the error.
@c JP
@code{sys-exec}がエラーに遭遇すると、たいていの場合エラー条件を投げます。
しかし一旦ファイルディスクリプタの順番が変えられると、合理的な方法でエラーを処理する
ことは実行不可能です(標準エラーがまだ有効かどうかさえ知る術がありません)。
したがって、その場合はGaucheはエラー時には単に終了するだけです。
@c COMMON

@c EN
On Windows native platforms, only redirections of stdin, stdout and stderr
are handled.   Singal mask is ignored, for Windows doesn't have
singals as the means of interprocess communication.
@c JP
Windowsネイティブ環境では、標準入力、標準出力、標準エラー出力に
関するリダイレクションのみが処理されます。Windowsはプロセス間通信としての
シグナルをサポートしないので、シグナルマスクは無視されます。
@c COMMON
@end defun

@defun sys-fork-and-exec command args :key directory iomap sigmask detached
@c EN
Like @code{sys-exec}, but executes @code{fork(2)} just before
remapping I/O, altering signal mask and call @code{execvp(2)}.
Returns child's process id.  The meanings of arguments are
the same as @code{sys-exec}.

It is strongly recommended to use this procedure instead of
@code{sys-fork} and @code{sys-exec} combination when you need
to spawn another program while other threads are running.
No memory allocation nor lock acquisition is done between
@code{fork(2)} and @code{execvp(2)},
so it's pretty safe in the multithreaded environment.
@c JP
@code{sys-exec}と同じですが、ファイルディスクリプタとシグナルマスクを変更して
@code{execvp(2)}を実行する直前に、@code{fork(2)}を実行します。
子プロセスのプロセスidを返します。引数の意味は@code{sys-exec}と同じです。

他のスレッドが走っている環境下で別プログラムをspawnしたい場合は、
@code{sys-fork}と@code{sys-exec}を別々に使うのではなく、
この手続きを使ってください。
この手続き中では、@code{fork(2)}と@code{execvp(2)}の間で
メモリアロケーションもロックの獲得も行われないため、
マルチスレッド環境で実行しても安全になっています。
@c COMMON

@c EN
On Windows native platforms, this procedure returns a
Windows handle object (@code{<win:handle>}) of the created
process instead of an integer process ID.  See below for
Windows process handle specific API.

Like @code{sys-exec}, only redirections of stdin, stdout and stderr
are handled on Windows native platforms.
@c JP
Windowsネイティブ環境では、この手続きはプロセスIDではなく
作られたプロセスに対するWindowsのハンドルオブジェクト 
(@code{<win:handle>}) を返します。Windowsプロセスハンドル
特有の手続きについては後に述べます。

また、@code{sys-exec}同様、Windowsネイティブ環境では、標準入力、標準出力、標準エラー出力に
関するリダイレクションのみが処理されます。
@c COMMON

@c EN
When a true value is given to the @var{detached} keyword argument,
the executed process is detached from the current process group
and belongs to its own group.
That is, it won't be affected to the signal sent to the process group
the caller process currently belongs to.
It is a part of the common idioms to start a daemon process.

On Unix platforms, besides the executed process gets its own session
by @code{setsid(2)}, it performs extra @code{fork(3)} to make its
parent be the @code{init} process (pid=1).
(Note: It means the running process is actually a grandchild of the
calling process, although that relationship isn't preserved.
The returned pid is the running process's one,
not the intermediate process that exits immediately.)

On Windows native platforms,
this flag causes the new process to be
created with the @code{CREATE_NEW_PROCESS_GROUP} creation flag.
@c JP
@var{detached}キーワード引数に真の値が与えられた場合、
実行されるプロセスは現在のプロセスグループからは切り離されます。
つまり、現在のプロセスグループに送られるシグナルを、新しいプロセスは受け取りません。
この動作はデーモンプロセスを作る際の標準的な手順のひとつです。

Unixでは、実行されるプロセスが@code{setsid(2)}を呼んで
独自のセッションを作るだけでなく、余分な@code{fork(2)}
を実行することで親を@code{init}プロセス (pid=1) に切り替えます。
(つまり、実行されるプロセスは実は呼び出すプロセスの孫にあたります。
親子関係はなくなりますが。返されるpidは実際に走っているこのプロセスのもので、
すぐに終了する中間プロセスのものではありません。)

実行されるプロセスの親が
また。Windowsネイティブ環境では、
実行されるプロセスが新たに作られたプロセスグループに属します。

Windowsネイティブ環境では、このフラグがあると
プロセス作成時に@code{CREATE_NEW_PROCESS_GROUP}フラグが使われます。
@c COMMON
@end defun

@subsubheading Wait

@defun sys-wait
@c EN
[POSIX] Calls system's @code{wait(2)}.  The process suspends its execution
until one of the child terminates.  Returns two exact integer values,
the first one is the child's process id, and the second is a status code.
The status code can be interpreted by the following functions.
@c JP
[POSIX] システムの@code{wait(2)}を呼びます。プロセスは、子プロセスの1つが
終了するまでその実行を一時停止します。2つの正確整数、1つ目は子プロセスのID、
2つ目はステータスコードを返します。ステータスコードは以下の関数によって
解釈できます。
@c COMMON
@end defun

@defun sys-waitpid pid :key nohang untraced
@c EN
[POSIX] This is an interface to @code{waitpid(3)}, an extended version of
wait.
@c JP
[POSIX] これは、waitの拡張バージョンである、@code{waitpid(3)}への
インターフェースです。
@c COMMON

@c EN
@var{pid} is an exact integer specifying which child(ren) to be waited.
If it is a positive integer,
it waits fot that specific child.  If it is zero, it waits for any
member of this process group.  If it is -1, it waits for any child process.
If it is less than -1, it waits for any child process whose process group
id is equal to the absolute value of @var{pid}.
@c JP
@var{pid}は、待つべき子プロセスを指定する正確な整数です。正の整数ならば、
特定の子プロセスを待ちます。0ならば、このプロセスグループのいずれかの
メンバを待ちます。-1ならば、いずれかの子プロセスを待ちます。
-1よりも小さければ、プロセスグループIDが@var{pid}の絶対値と等しいいずれかの
子プロセスを待ちます。
@c COMMON

@c EN
If there's no child process to wait, or a specific @var{pid} is
given but it's not a child process of the current process,
an error (@code{<system-error>}, @code{ECHILD}) is signalled.
@c JP
待つべき子プロセスが存在しない場合や、@var{pid}に具体的なプロセスIDが
与えられたがそれが現在のプロセスの子プロセスで内場合は
エラー(@code{<system-error>}, @code{ECHILD})となります。
@c COMMON


@c EN
The calling process suspends until one of those child process is terminated,
unless true is specified to the keyword argument @var{nohang}.
@c JP
キーワード引数@var{nohang}に真値が指定されていなければ、
呼んでいるプロセスは、それらの子プロセスのうちの1つが終了するまで一時停止します。
@c COMMON

@c EN
If true is specified to the keyword argument @var{untraced},
the status of stopped child process can be also returned.
@c JP
キーワード引数@var{untraced}に真値が指定されていれば、
停止した子プロセスのステータスも返ります。
@c COMMON

@c EN
The return values are two exact integers, the first one is the child
process id, and the second is a status code.  If @var{nohang} is true and
no child process status is available, the first value is zero.
@c JP
戻り値は2つの正確整数で、1つ目は子プロセスのID、2つ目はステータスコードです。
@var{nohang}が真で子プロセスのステータスが利用できない場合は、1つ目の値は0です。
@c COMMON

@c EN
On Windows native platforms, this procedure may also accept
a Windows process handle (@code{<win:handle>}) object as @var{pid} to
wait the specific process.  You can pass @code{-1} as @var{pid}
to wait for any children, but you cannot wait for a specific
process group.
@c JP
Windowsネイティブ環境では、この関数は@var{pid}にWindowsプロセスハンドル
(@code{<win:handle>})オブジェクトを受け取ることもできます。
その場合はそのハンドルの指すプロセスの終了を待ちます。
また、@code{-1}を渡していずれかの子プロセスの終了を待つこともできますが、
特定のプロセスグループの中の子プロセスを待つことはできません。
@c COMMON
@end defun

@defun sys-wait-exited? status
@defunx sys-wait-exit-status status
@c EN
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-wait} or @code{sys-waitpid}.
@code{sys-wait-exited?} returns @code{#t} if the child process is 
terminated normally.   @code{sys-wait-exit-status} returns the exit
code the child process passed to @code{exit(2)}, or the return value
of @code{main()}.
@c JP
[POSIX]
引数は@code{sys-wait}か@code{sys-waitpid}の2番目の値として返される
終了ステータスです。子プロセスが正常終了したら、@code{sys-wait-exited?}は
@code{#t}を返します。@code{sys-wait-exit-status}は、子プロセスが
@code{exit(2)}に渡した終了コードか、@code{main()}の戻り値を返します。
@c COMMON
@end defun

@defun sys-wait-signaled? status
@defunx sys-wait-termsig status
@c EN
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-wait} or @code{sys-waitpid}.
@code{sys-wait-signaled?} returns @code{#t} if the child process
is terminated by an uncaught signal.
@code{sys-wait-termsig} returns the signal number that terminated the child.
@c JP
[POSIX]
引数は、@code{sys-wait}か@code{sys-waitpid}の2つ目の戻り値である終了ステータスです。
子プロセスが捕捉されないシグナルで終了した場合は、@code{sys-wait-signaled?}は
@code{#t}を返します。
@code{sys-wait-termsig}は、子プロセスを終了したシグナルの番号を返します。
@c COMMON
@end defun

@defun sys-wait-stopped? status
@defunx sys-wait-stopsig status
@c EN
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-waitpid}.
@code{sys-wait-stopped?} returns @code{#t} if the child process is
stopped.   This status can be caught only by @code{sys-waitpid} with
true @var{untraced} argument.  @code{sys-wait-stopsig} returns the
signum number that stopped the child.
@c JP
[POSIX]
引数は、@code{sys-waitpid}の2つ目の戻り値である終了ステータスです。
子プロセスが停止されれば、@code{sys-wait-stopped?}は@code{#t}を
返します。このステータスは、@code{sys-waitpid}が@var{untraced}引数に
真値を持っている場合にのみ捕捉されます。@code{sys-wait-stopsig}は
子プロセスを停止させたシグナルの番号を返します。
@c COMMON
@end defun

@c EN
On Windows native platforms, exit code is not structured as on Unix.
You cannot distinguish a process being exitted voluntarily or
by forced termination.  Gauche uses exit code @code{#xff09} to
terminate other process with @code{sys-kill},
and the above @code{sys-wait-*} procedures are adjusted accordingly,
so that @code{sys-wait-signaled?} can likely to be used to check
whether if the child process is terminated by Gauche.
(@xref{Signal}, for the details of signal support on Windows.)
@code{Sys-wait-stopped?} never returns true
on Windows native platforms (yet).
@c JP
Windowsネイティブ環境では、終了コードはUnixのように構造化されておらず、
プロセスが自発的に終了したか強制的に終了させられたかを判断する一般的な方法は
ありません。Gauche自身は他のプロセスを@code{sys-kill}で
終了させる場合に終了コード@code{#xff09}を送り、上の@code{sys-wait-*}
手続きもそれに合わせてあります。従ってGaucheによって終了させられたプロセスでは
@code{sys-wait-signaled?}でそのことを検出できる可能性が高いでしょう。
(Windows上のシグナルのサポートについては@ref{Signal}を参照してください。)
Windowsネイティブ環境では、@code{sys-wait-stopped?}が真を返すことは
(今のところ)ありません。
@c COMMON

@subsubheading Windows specific utilities

The following procedures are to access Windows process handle.
They are only available on Windows native platforms.

@defun sys-win-process? obj
[Windows] Returns @code{#t} iff @var{obj} is a Windows process handle object.
@end defun

@defun sys-win-process-pid handle
[Windows] Returns an integer PID of the process represented by 
a Windows process handle @var{handle}.  An error is signalled
if @var{handle} is not a valid Windows process handle.

Note that the API to get a pid from a process handle is only
provided on or after Windows XP SP1.  If you call this
procedure on Windows version before that, @code{-1} will be
returned.
@end defun


@node I/O multiplexing, Miscellaneous system calls, Process management, System interface
@subsection I/O multiplexing
@c NODE I/Oの多重化

@c EN
The interface functions for @code{select(2)}.
The higher level interface is provided on top of these
primitives; see @ref{Simple dispatcher}.
@c JP
@code{select(2)}へのインターフェース関数です。
これらのプリミティブの上に構築された高次元のインターフェースが
提供されています。@ref{Simple dispatcher}を
参照して下さい。
@c COMMON

@deftp {Builtin Class} <sys-fdset>
@clindex sys-fdset
@c EN
Represents @code{fd_set}, a set of file descriptors.  You can make
an empty file descriptor set by make method:
@c JP
ファイルディスクリプタの集合である@code{fd_set}を表します。
makeメソッドによって、空のファイルディスクリプタの集合を作れます。
@c COMMON
@example
(make <sys-fdset>)
@end example
@end deftp

@defun sys-fdset elt @dots{}
@c EN
Creates a new @code{<sys-fdset>} instance with file descriptors
specified by @var{elt} @dots{}.  Each @var{elt} can be an
integer file descriptor, a port, or a @code{<sys-fdset>} instance.
In the last case, the descriptors in the given fdset is copied
to the new fdset.
@c JP
@var{elt} @dots{}で指定されたファイルディスクリプタを持つ
新たな@code{<sys-fdset>}のインスタンスを作成して返します。
各@var{elt}は、ファイルディスクリプタを指定する整数、ポート、
もしくは@code{<sys-fdset>}のインスタンスでなければなりません。
最後の場合は、与えられたfdsetに含まれるディスクリプタが
新たなfdsetにコピーされます。
@c COMMON
@end defun

@defun sys-fdset-ref fdset port-or-fd
@defunx sys-fdset-set! fdset port-or-fd flag
@c EN
Gets and sets specific file descriptor bit of @var{fdset}.
@var{port-or-fd} may be a port or an integer file descriptor.
If @var{port-or-fd} is a port that doesn't have associated file descriptor,
@code{sys-fdset-ref} returns @code{#f}, and @code{sys-fdset-set!} doesn't
modify @var{fdset}.  @var{flag} must be a boolean value.
@c JP
@var{fdset}の特定のファイルディスクリプタビットを取得・セットできます。
@var{port-or-fd}は関連付けられたファイルディスクリプタを持っていないポートで、
@code{sys-fdset-ref}は@code{#f}を返し、@code{sys-fdset-set!}は@var{fdset}を
変更しません。@var{flag}は真偽値でなければなりません。
@c COMMON

@c EN
You can use generic setter of @code{sys-fdset-ref} as this:
@c JP
下記のように、@code{sys-fdset-ref}のジェネリックなセッタが使えます。
@c COMMON
@example
(set! (sys-fdset-ref fdset port-or-fd) flag)
  @equiv{} (sys-fdset-set! fdset port-or-fd flag)
@end example
@end defun

@defun sys-fdset-copy! dest-fdset src-fdset
@c EN
Copies the content of @var{src-fdset} into @var{dest-fdset}.
Returns @var{dest-fdset}.
@c JP
@var{src-fdset}の内容を@var{dest-fdset}にコピーします。
@var{dest-fdset}を返します。
@c COMMON
@end defun

@defun sys-fdset-clear! fdset
@c EN
Empties and returns @var{fdset}.
@c JP
@var{fdset}の内容をクリアし、それ自身を返します。
@c COMMON
@end defun

@defun sys-fdset->list fdset
@defunx list->sys-fdset fds
@c EN
Converts an fdset to a list of integer file descriptors and vice versa.
In fact, @code{list->sys-fdset} works just like
@code{(lambda (fds) (apply sys-fdset fds))}, so it accepts ports
and other fdsets as well as integer file descriptors.
@c JP
fdsetを整数のファイルディスクリプタのリストに変換し、またその逆を行います。
実際は、@code{list->sys-fdset}は
@code{(lambda (fds) (apply sys-fdset fds))} のように動作するため、
整数のファイルディスクリプタ以外にポートや他のfdsetを与えることもできます。
@c COMMON
@end defun

@defun sys-fdset-max-fd fdset
@c EN
Returns the maximum file descriptor number in @var{fdset}.
@c JP
@var{fdset}にある最大のファイルディスクリプタ番号を返します。
@c COMMON
@end defun

@defun sys-select readfds writefds exceptfds :optional timeout
@defunx sys-select! readfds writefds exceptfds :optional timeout
@c EN
Waits for a set of file descriptors to change status.
@var{readfds}, @var{writefds}, and @var{exceptfds} are @code{<fdset>}
objects to represent a set of file descriptors to watch.
File descriptors in @var{readfds} are watched to see if characters
are ready to be read.   File descriptors in @var{writefds} are
watched if writing to them is ok.  File descriptors in @var{exceptfds}
are watched for exceptions.  You can pass @code{#f} to one or more
of those arguments if you don't care about watching the condition.
@c JP
ステータスを変更するためにファイルディスクリプタの集合を待ちます。
@var{readfds}、@var{writefds}、@var{exceptfds}は、注目するファイル
ディスクリプタの集合を表す@code{<fdset>}オブジェクトです。
@var{readfds}にあるファイルディスクリプタは、文字を読み込む準備が
出来たかどうかを検査するために監視されています。
@var{writefds}にあるファイルディスクリプタはそこへ書き込むことができる
ようになったか監視されています。@var{exceptfds}にあるファイルディスクリプタは
例外のために監視されています。条件を監視する必要がない場合は、これらの引数の
1つ以上に@code{#f}を渡すことができます。
@c COMMON

@c EN
@var{timeout} specifies maximum time @code{sys-select} waits for
the condition change.  It can be a real number, for number of microseconds,
or a list of two integers, the first is the number of seconds and
the second is the number of microseconds.  If you pass @code{#f},
@code{sys-select} waits indefinitely.
@c JP
@var{timeout}は@code{sys-select}が条件の変更を待つ最大の時間を指定します。
それは、マイクロ秒を表す実数か、1つ目が秒数で2つ目がマイクロ秒である
2つの整数からなるリストです。@code{#f}を渡すと、@code{sys-select}は
永久に待ちます。
@c COMMON

@c EN
@code{sys-select} returns four values.  The first value is a number
of descriptors it detected status change.  It may be zero if 
timeout expired.  The second, third and fourth values are @code{<fdset>}
object that contains a set of descriptors that changed status
for reading, writing, and exception, respectively.
If you passed @code{#f} to one or more of @var{readfds},
@var{writefds} and @var{exceptfds}, the corresponding return value
is @code{#f}.
@c JP
@code{sys-select}は4つの値を返します。1つ目の値は、ステータスの変更を
検知したディスクリプタの数です。timeoutが経過したら0になるでしょう。
2、3、4番目の値は、それぞれ読み込み、書き出し、例外のステータスを変更
するディスクリプタの集合を含む@code{<fdset>}オブジェクトです。
@var{readfds}、@var{writefds}、@var{exceptfds}のうちの1つ以上に@code{#f}を
渡すと、対応する戻り値は@code{#f}になります。
@c COMMON

@c EN
@code{sys-select!} variant works the same as @code{sys-select}, except
it modifies the passed @code{<fdset>} arguments.
@code{sys-select} creates new @code{<fdset>} objects and
doesn't modify its arguments.
@c JP
@code{sys-select!}の仲間は、それが渡された引数@code{<fdset>}を変更することを
除けば、@code{sys-select}と同じように動作します。
@code{sys-select}は、新しい@code{<fdset>}オブジェクトを作り、その
引数を変更しません。
@c COMMON
@end defun


@node Miscellaneous system calls,  , I/O multiplexing, System interface
@subsection Miscellaneous system calls
@c NODE その他のシステムコール

@defun sys-pause
@c EN
[POSIX]
Suspends the process until it receives a signal whose
action is to either execute a signal-catching function or to terminate
the process.  This function only returns when the signal-catching
function returns.  The returned value is undefined.
@c JP
[POSIX]
シグナルキャッチ関数の実行かプロセスの終了を指示するシグナルを
受け取るまでプロセスを一時停止します。この関数は、シグナルキャッチ関数が
戻ったときにのみ戻ります。戻り値は未定義です。
@c COMMON

@c EN
Note that just calling @code{pause()} doesn't suffice the above semantics
in Scheme-level.  Internally this procedure calls @code{sigsuspend()}
with the current signal mask.
@c JP
Schemeレベルでは、@code{pause()}を呼ぶだけでは上記のセマンティクスを
満足しません。内部的にこの手続きは現在のシグナルマスクを伴って、
@code{sigsuspend()}を呼びます。
@c COMMON
@end defun

@defun sys-alarm seconds
@c EN
[POSIX] Arranges a SIGALRM signal to be delivered after @var{seconds}.
The previous settings of the alarm clock is cancelled.  Passing zero
to @var{seconds} doesn't schedule new alarm.
Returns the number of seconds remaining until previously scheduled
alarm was due to be delivered (or zero if no alarm is active).
@c JP
[POSIX] SIGALRMシグナルが@var{seconds}秒後に送出されるように準備します。
以前のアラームクロックのセッティングはキャンセルされます。
@var{seconds}に0を渡すと、新しいアラームをスケジューリングしません。
以前にスケジューリングされていたアラームが送出されるまでの残り時間を
秒数で返します(アラームがアクティブでない場合は0を返します)。
@c COMMON
@end defun

@defun sys-sleep seconds
@c EN
[POSIX] Suspends the process until the specified number of seconds elapses,
or the process receives a signal.  Returns zero if it sleeps well,
or the number of unslept seconds if it is woke up by a signal.
@c JP
[POSIX] 指定された秒数が経過するまで、あるいはプロセスがシグナルを受け取るまで
スレッドを一時停止します。指定時間が満了した場合は0を返し、
シグナルによって一時停止が解除された場合は、満了までの秒数を返します。
@c 満了は完了の方がよいかも?
@c COMMON

@c EN
To be portable across POSIX implementation, keep @var{seconds} less than
65536.
@c JP
POSIX実装間でポータブルにするためには、@var{seconds}を65536より小さく保って
下さい。
@c COMMON
@end defun

@defun sys-nanosleep nanoseconds
@c EN
[POSIX] 
Suspends the process until the specified number of nanoseconds elapses,
or the process receives a signal.  The argument @var{nanoseconds} can be
a @code{<time>} object (@xref{Time}), or a real number.
Returns @code{#f} if @var{nanoseconds} elapsed, or a @code{<time>}
object that indicates the remaining time if @code{sys-nanosleep}
is interrupted by a signal.
@c JP
[POSIX]
指定されたナノ秒が経過するか、シグナルを受け取るまでプロセスを一時停止します。
引数@var{nanoseconds}は@code{<time>}オブジェクト(@ref{Time}参照)か
実数です。@var{nanoseconds}が経過したら@code{#f}を返し、
@code{sys-nanosleep}がシグナルによって割り込まれると残りの時間を表す
@code{<time>}オブジェクトを返します。
@c COMMON

@example
;@r{wait for 0.5 sec}
(sys-nanosleep 500000000)

;@r{wait for 1.3 sec}
(sys-nanosleep (make <time> :second 1 :nanosecond 300000000))
@end example

@c EN
Note: On Windows native platforms, this function is emulated using
@code{Sleep}.  The argument is rounded up to millisecond resolution, 
and it won't be interrupted by a signal.
@c JP
Windowsネイティブ環境では、この関数は@code{Sleep}によってエミュレートされます。
引数はミリ秒の単位に切り上げられます。またシグナルによって中断されることはありません。
@c COMMON
@end defun

@defun sys-random
@defunx sys-srandom seed
@c EN
A pseudo random number generator.
@code{sys-random} returns a random number between 0 and a positive
integer @var{rand_max}, inclusive.  This is a straightforward
interface to @code{random(3)}.  If the underlying system doesn't have
@code{random(3)}, @code{lrand48(3)} is used.
@c JP
擬似的な乱数ジェネレータです。
@code{sys-random}は0から@var{rand_max}(それ自体を含む)までの間で乱数を
返します。これは@code{random(3)}への直接的なインターフェースです。
システムに@code{random(3)}がない場合、@code{lrand48(3)}が使われます。
@c COMMON

@c EN
@code{sys-srandom} sets the seed of the random number generator.
It uses either @code{srandom(3)} or @code{srand48(3)}, depending on
the system.
@c JP
@code{sys-srandom}は乱数ジェネレータの種をセットします。
システムによって、@code{srandom(3)}か@code{srand48(3)}を使います。
@c COMMON

@c EN
The intention of these functions are to provide an off-the-stock handy
random number generator (RNG) for applications that doesn't
sensitive to the quality and/or speed of RNG.  For serious statistics
analysis, use Mersenne Twister RNG in @code{math.mt-random}
module (@xref{Mersenne-Twister random number generator}).
@c JP
これらの関数の意図は、乱数ジェネレータ(RNG; random number generator)の
品質や速度を気にしないアプリケーションに、簡便なRNGを提供することです。
本格的な統計分析には、@code{math.mt-random}モジュールのMersenne Twister RNGを
使って下さい(@ref{Mersenne-Twister random number generator}参照)。
@c COMMON
@end defun

@defvar RAND_MAX
@c EN
Bound to a positive integer that @code{sys-random} may return.
@c JP
@code{sys-random}が返す正の整数に束縛されます。
@c COMMON
@end defvar

@defun sys-get-osfhandle port-or-fd
[Windows] This procedure is only available on Windows native platforms.
Returns a Windows file handle associated to the given port or
integer file descriptor.   Throws an error if the given argument
does not have associated file handle.
@end defun


@c ----------------------------------------------------------------------
@node Development helper API,  , System interface, Core library
@section Development helper API
@c NODE 開発補助API

@c EN
Gauche has some basic built-in APIs to help developers
to analyze the program.
@c JP
Gauche には開発者がプログラムを解析するための基本的な組込みAPIがあります。
@c COMMON

@menu
* Debugging aid::               
* Profiler API::                
@end menu

@node Debugging aid, Profiler API, Development helper API, Development helper API
@subsection Debugging aid
@c NODE デバッグ補助

@defmac debug-print expr
@c EN
This macro prints @var{expr} in a source form, then evaluates it,
then prints out the result(s), and returns them.
@c JP
このマクロは@var{expr}をそのフォームのまま印字してから、その式を評価し、
評価の結果を印字し、その値を返します。
@c COMMON

@c EN
The special reader syntax @code{#?=@var{expr}} is expanded into
@code{(debug-print @var{expr})}.  See @ref{Debugging}, for the
details.
@c JP
特殊リーダー構文 @code{#?=@var{expr}} は
@code{(debug-print @var{expr})} に展開されます。
詳細については @ref{Debugging} を参照してください。
@c COMMON
@end defmac

@deffn {Parameter} debug-print-width
@c EN
This parameter specifies the maximum width of information to be 
printed by @code{debug-print}.  If the information takes more
columns than the value of this parameter, it is truncated.
@c JP
このパラメータは@code{debug-print}が印字する情報の最大幅を指定するもの
です。このパラメータが保持する値よりも大きいカラム数の情報は丸められま
す。
@c COMMON

@c EN
To show all the information, set @code{#f} to this parameter.
@c JP
すべての情報を表示したければ、このパラメータに@code{#f}を設定してくだ
さい。
@c COMMON
@end deffn

@defun debug-source-info obj
@c EN
Retrieves source information attached to @var{obj}.
The source information is returned as a list of source file name
and an integer line number.  If no source information is available
in @var{obj}, @code{#f} is returned.
@c JP
@var{obj}に付加されているソースコード情報を検索します。ソースコード情
報とはソースコードファイル名と行番号のリストです。@var{obj}にソースコー
ド情報が付加されていなければ、@code{#f}が返されます。
@c COMMON
@end defun


@defun disasm closure
@c EN
Disassemble the compiled body of @var{closure} and print it.
It may not be very useful unless you're tracking a compiler bug, 
or trying to tune the program to its limit.
@c JP
コンパイル済の@var{closure}の本体部分をディスアセンブルして印字します。
これはコンパイラのバグをなんとかしようという場合か、限界まで
チューンしようとしないかぎりは役には立たないでしょう。
@c COMMON

@c EN
If you're reading the disassembler output, keep in mind that
the compiled code vector may have some dead code; they are produced
by the jump optimization, but the compiler doesn't bother to eliminate
them.
@c JP
このディスアセンブラの出力結果を読む場合には、コンパイルされたコードに
はデッドコードが含まれている可能性があることを心してください。デッドコー
ドはジャンプ最適化によって生成されるのですが、コンパイラはこれをわざわ
ざ除去することはしていません。
@c COMMON
@end defun

@node Profiler API,  , Debugging aid, Development helper API
@subsection Profiler API
@c NODE プロファイラAPI

@c EN
These are the functions to control Gauche's built-in profiler.
See @ref{Using profiler} for the explanation of the profiler.
@c JP
ここに挙げている関数は、Gauche の組込みプロファイラを制御するためのも
のです。プロファイラの説明については @ref{Using profiler} を参照してく
ださい。 
@c COMMON

@c EN
Note that the profiler doesn't work correctly yet in multi-threaded
program.
@c JP
注意：現時点ではプロファイラはマルチスレッドプログラムでは正しく動作し
ません。
@c COMMON

@defun profiler-start
@c EN
Starts the sampling profiler.   If the profiler is already started,
nothing is done.
@c JP
標本化プロファイラを始動します。プロファイラが既に始動しいる場合
には何もしません。
@c COMMON
@end defun

@defun profiler-stop
@c EN
Stop the sampling profiler, and save the sampled data into
the internal structure.   If there are already saved sampled data,
the newly obtained data is added to it.
If the profiler isn't running, nothing is done.
@c JP
標本化プロファイラを停止し、標本データを内部データ構
造に保存します。既に標本データが保存されていた場合には、新
しく収集された標本データがその後に追加されます。もしプロファイラが動いてい
なかった場合には何もしません。
@c COMMON
@end defun

@defun profiler-reset
@c EN
Stop the profiler if it is running.  Then discard the
saved sampled data.
@c JP
もしプロファイラが動いていればそれを停止し、保存されていた標本データ
を破棄します。

@c COMMON
@end defun

@defun profiler-show :key sort-by max-rows
@c EN
Show the saved sampled data.  
@c JP
格納されている標本データを表示します。
@c COMMON

@c EN
The keyword argument @var{sort-by} may be one of the symbols
@code{time}, @code{count}, or @code{time-per-call}, to specify
how the result should be sorted.  The default is @code{time}.
@c JP
キーワード引数 @var{sort-by} は指定する場合は、@code{time}、
@code{count} または @code{time-per-call} のどれかひとつです。
これで結果の整列順を指定します。デフォルトでは @code{time}です。
@c COMMON

@c EN
The keyword argument @var{max-rows} specifies the max number of
rows to be shown.  If it is @code{#f}, all the data is shown.
@c JP
キーワード引数 @var{max-rows} では結果を表示する最大行数を指定します。
この値が @code{#f} であればすべてのデータが表示されます。
@c COMMON
@end defun

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
