@node Introduction, Concepts, Top, Top
@chapter Introduction
@c NODE はじめに

@c EN
This is a users' guide and reference manual of
the Gauche Scheme.
Here I tried to describe the implementation precisely,
sometimes referring to background design choices.
@c JP
本書はGauche Schemeに関する、ユーザのためのガイドと
リファレンスです。なるべくGaucheの実装を正確に記述することを
目的として、時には背景となる設計上の選択も含めて説明しています。
@c COMMON

@c EN
The target readers are those who already know Scheme and
want to write useful programs in Gauche.
For those who are new to Scheme, it'll be easier to start
from some kind of tutorial.  I'm planning to write one.
@c JP
したがって、既にSchemeを知っていてGaucheの全機能を活用して
プログラムを書きたいという読者を対象にしています。
Schemeに触れるのが初めての読者は、何らかのチュートリアルを併用すると
良いでしょう。私もいずれチュートリアルめいたものを書くつもりです。
@c COMMON

@c EN
This manual only deals with Scheme side of things.  Gauche has
another face, a C interface.   Details of it will be discussed
in a separate document.  See @file{gauche-dev.texi} in the source
distribution for the work-in-progress of such document.
Those who want to use Gauche as an embedded language, or want
to write an extension, need that volume.
@c JP
このマニュアルでは、GaucheのScheme言語としての面のみを扱います。
GaucheはC言語から呼べる汎用リスト処理ライブラリとしての側面も持っていますが、
それは別ドキュメントで解説されます。配布ソース中の@file{gauche-dev.texi}に
書きかけのドキュメントがあります。
Gaucheを組み込み言語として使いたい、
もしくはGaucheをC言語で拡張したいという読者はそのドキュメントが必要となります。
@c COMMON

@c EN
For the Scheme side, I tried to make this manual self-contained
for the reader's convenience, i.e. as far as you want to look up
Gauche's features you don't need to refer to other documents.
For example, description of functions defined in the standard
documents are included in this manual, instead of saying
``see the standard document''.   However, this document is not a verbatim
copy of the standard documents; sometimes I omit detailed
discussions for brevity.
I put pointers to the original documents, so please consult them if you
need to refer to the standards.
@c JP
Scheme言語としての側面に関しては、なるべくこのマニュアル一冊でリファレンスとしての
用が足りるように記述しました。標準に定められている関数でも、こちらのマニュアルだけで
使うのに必要な事項を知ることができます。但し、このマニュアルは標準文書の替わりには
なりません。記述を短くするために理論的な背景などは省略してあります。
オリジナルのドキュメントへのポインタを参考文献の項に上げておきましたので、
必要に応じて参照して下さい。
@c COMMON

@c EN
If you're reading this document off-line, you may find the most
recent version on the web:
@c JP
もしあなたがこのマニュアルをオフラインで読んでいるなら、
時々下記のURLをチェックしてみて下さい。更新があるかもしれません。
@c COMMON
@example
@uref{https://practical-scheme.net/gauche/}.
@end example

@c JP
なお、本マニュアルの日本語版製作には、
佐藤 誠 氏、山下 伸夫 氏の協力を頂きました。
@c COMMON

@menu
* Overview of Gauche::
* Notations::
@end menu

@node Overview of Gauche, Notations, Introduction, Introduction
@section Overview of Gauche
@c NODE  Gaucheの概要

@c EN
Gauche is a Scheme script engine; it reads Scheme programs,
compiles it on-the-fly and executes it on a virtual machine.
Gauche conforms the language standard
"Revised^7 Report on the Algorithmic Language Scheme"
(@uref{https://standards.scheme.org/official/r7rs.pdf}),
and supports various common libraries defined in SRFIs
(@uref{https://srfi.schemers.org}).
@c JP
GaucheはScheme言語のスクリプトエンジンです。
Schemeプログラムを読み込み、直ちにコンパイルして仮想マシンで実行します。
Scheme言語の標準である、"Revised^7 Report on the Algorithmic Language Scheme"
(@uref{https://standards.scheme.org/official/r7rs.pdf})
に準拠しています。また、SRFI
(@uref{https://srfi.schemers.org}) に規定されている数多くのライブラリを
サポートしています。
@c COMMON

@c EN
The goal of Gauche is to provide a handy tool for
programmers and system administrators to handle
daily works conveniently and efficiently in the production environment.
@c JP
Gaucheは、プログラマやシステム管理者がこなす日常の雑事を
効率よくSchemeで書けるようにすることを目的として設計されています。
@c COMMON

@c EN
There are lots of Scheme implementations available, and each
of them has its design emphasis and weaknesses.  Gauche is
designed with emphasis on the following criteria.
@c JP
世の中には多くのSchemeの実装がありますが、
それぞれの実装には長所と短所があります。
Gaucheが長所とするべく重点を置いているのは次のようなポイントです。
@c COMMON

@table @b
@c EN
@item Quick startup
@c JP
@item 立ち上りが速いこと
@c COMMON
@c EN
One of the situation Gauche is aiming at is in the production
environment, where you write ten-lines throw-away script that
may invoked very frequently.  This includes CGI scripts as well.
Gauche provides frequently used common features as a part of rich built-in
functions or precompiled Scheme libraries that can be loaded very quickly.
@c JP
Gaucheが想定している用途のひとつは、プロダクション環境でちょろっと
10行スクリプトをでっちあげて、それが非常に頻繁に呼ばれるようなケースです。
CGIスクリプトなどもそうです。
Gaucheは頻繁に使われる共通の機能については、豊富な組み込み関数として、
あるいはプリコンパイルされ素早くロードできるSchemeライブラリとして提供しています。
@c COMMON

@c EN
@item Fully utilizing multi-core
@c JP
@item マルチコアの完全な活用
@c COMMON
@c EN
Gauche supports native threads on most platforms.
The internals are fully aware of preemptive/concurrent threads
(that is, no ``giant global lock''),
so that you can utilize multiple cores on your machine.
@c JP
Gaucheは多くのプラットフォームでネイティブスレッドをサポートしています。
内部は全てプリエンプティブな並行スレッドを意識してかかれており
(つまり、「巨大なひとつのロック」はありません)、
複数のコアを存分に活用できるようになっています。
@c COMMON

@c EN
@item Multibyte strings
@c JP
@item マルチバイト文字列
@c COMMON
@c EN
We can no longer live happily in ASCII-only or 1-byte-per-character world.
The practical language implementations are required to handle
multibyte (wide) characters.
Gauche supports multibyte strings natively, providing robust and
consistent support than @i{ad hoc} library-level implementation.
@xref{Multibyte strings}, for details.
@c JP
文字列が1バイトキャラクタのみを扱っていれば良かった時代は過ぎ去りました。
現代のプログラミングシステムは、様々なエンコーディングによるマルチバイト文字／文字列を
自然に扱える必要があります。
Gaucheは内部的に文字列を全て、コンパイル時に選択したエンコーディングの
マルチバイト文字列として扱います。後から付け足したライブラリレベルでの
マルチバイト文字列のサポートよりも、一貫性がありロバストな文字列操作が可能になっています。
詳しくは@ref{Multibyte strings}を参照してください。
@c COMMON

@c EN
@item Integrated object system
@c JP
@item 統合されたオブジェクトシステム
@c COMMON
@c EN
A powerful CLOS-like object system with MetaObject protocol
(mostly compatible with STklos and Guile) is provided.
@c JP
CLOSライクなメタオブジェクトプロトコルを備えた強力なオブジェクトシステム
が組み込んであります。STklosやGuileのオブジェクトシステムとかなり互換性があります。
@c COMMON

@c EN
@item System interface
@c JP
@item システムインタフェース
@c COMMON
@c EN
Although Scheme abstracts lots of details of the machine,
sometimes you have to bypass these high-level layers and
go down to the basement to make things work.
Gauche has built-in support of most of POSIX.1 system calls.
Other modules, such as networking module, usually provide
both high-level abstract interface and low-level interface
close to system calls.
@c JP
Schemeは計算機の詳細の多くを抽象化しますが、プログラムを書いていると、
それらの高レベル層をバイパスして地下室に降りて作業しなければならないような時が
あります。GaucheはPOSIX.1システムコールのほとんどを組み込みでサポートします。
また、ネットワーキングモジュールなど他のシステム関連モジュールは通常、
高レベルの抽象的なインタフェースと低レベルのシステムコールに近いインタフェースを
両方提供します。
@c COMMON

@c EN
@item Enhanced I/O
@c JP
@item 強化された入出力
@c COMMON
@c EN
No real application can be written without dealing with I/O.
Scheme neatly abstracts I/O as a port, but defines least operations on it.
Gauche uses a port object as a unified abstraction, providing
utility functions to operate on the underlying I/O system.
@xref{Input and output}, for the basic I/O support.
@c JP
本物のアプリケーションはI/O無しでは成り立ちません。
SchemeはI/Oをポートとして簡潔に抽象化していますが、
標準のSchemeには最低限の操作しか定義されていません。
Gaucheはポートオブジェクトを入出力のための統合された抽象化オブジェクトと考え、
それを通して下位のI/Oシステム層にアクセスするユーティリティ関数を提供しています。
@ref{Input and output}を参照して下さい。
@c COMMON

@c EN
@item Extended language
@c JP
@item 拡張された言語
@c COMMON
@c EN
Gauche is not just an implementation of Scheme; it has some
language-level enhancements.  For example, @emph{lazy sequences}
allows you to have lazy data structures that behaves as if
they're ordinary lists (except that they're realized lazily).
It is different from library-level lazy structure implementation such as
streams (SRFI-41), in a sense that you can use any list-processing
procedures on lazy sequences.  It enables programs to use
lazy algorithms more liberally.
@c JP
Gaucheは単なるScheme実装というだけでなく、言語レベルでいくつかの拡張が施されています。
例えば、@emph{遅延シーケンス}によって、あたかもそれが(遅延して実体化される点を除いて)
普通のリストであるかのように振るまう遅延データ構造を扱うことが可能になります。
あらゆるリスト処理を使用できるという意味で、遅延シーケンスは、
例えばストリーム(SRFI-41)のようにライブラリレベルで
実装した遅延構造とは異なります。
これによって、遅延アルゴリズムをよりふんだんに使用したプログラミングが可能になります。
@c COMMON
@end table


@node Notations,  , Overview of Gauche, Introduction
@section Notations
@c NODE 表記について

@menu
* Entry format::
* Names and namespaces::
@end menu

@node Entry format, Names and namespaces, Notations, Notations
@subsection Entry format
@c NODE 項目の形式

@c EN
In this manual, each entry is represented like this:

@deftp {Category} foo arg1 arg2
[spec]@{module@} Description of foo @dots{}
@end deftp
@c JP
このマニュアルでは、各項目は次のようなフォーマットで表記されています。

@deftp {カテゴリ} foo arg1 arg2
[spec]@{module@} fooの説明
@end deftp
@c COMMON

@c EN
@var{Category} denotes the category of the entry @b{foo}.
The following categories will appear in this manual:
@c JP
@var{カテゴリ} は項目@b{foo}の種別を示します。
次のようなカテゴリがあります。
@c COMMON

@multitable @columnfractions .4 .6
@item Function
@c EN
@tab A Scheme function.
@c JP
@tab Scheme手続き
@c COMMON
@item Special Form
@c EN
@tab A special form (in the R7RS term, ``syntax'').
@c JP
@tab 特殊形式 (R7RSでは「構文」)
@c COMMON
@item Macro
@c EN
@tab A macro.
@c JP
@tab マクロ
@c COMMON
@item Module
@c EN
@tab A module
@c JP
@tab モジュール
@c COMMON
@item Class
@c EN
@tab A class.
@c JP
@tab クラス
@c COMMON
@item Generic Function
@c EN
@tab A generic function
@c JP
@tab ジェネリックファンクション
@c COMMON
@item Method
@c EN
@tab A method
@c JP
@tab メソッド
@c COMMON
@item Reader Syntax
@c EN
@tab A lexical syntax that is interpreted by the reader.
@c JP
@tab リーダによって解釈される構文要素
@c COMMON
@item Parameter
@c EN
@tab A parameter, an object to realize dynamically-bound variables.
@xref{Parameters and dynamic states}, for the details.
@c JP
@tab パラメータ。動的束縛を実現するオブジェクト。
詳しくは@ref{Parameters and dynamic states}参照。
@c COMMON
@item Dynamic state
@c EN
@tab A procedure that follows a protocol to manage the state by
dynamic scope.
@xref{Parameters and dynamic states}, for the details.
@c JP
@tab 動的状態。動的スコープで状態を切り替えるプロトコルに従う手続きです。
詳しくは@ref{Parameters and dynamic states}参照。
@c COMMON
@item Generic application
@c EN
@tab In Gauche, you can ``apply'' a non-procedure object to arguments
as if it is a procedure (@pxref{Applicable objects}, for the details).
This entry explains the behavior of an object applied to arguments.
@c JP
@tab Gaucheでは、手続きでないオブジェクトをあたかも手続きのように
引数に「適用」することができます(詳しくは@ref{Applicable objects}を参照してください)。
このエントリは、オブジェクトが引数に適用された時のふるまいを説明します。
@c COMMON
@item Subprocess argument
@c EN
@tab This appears in @code{do-process} and @code{run-process} to explain
their keyword argument (@pxref{Running subprocess})
@c JP
@tab これは@code{do-process}と@code{run-process}のキーワード引数の
説明で使われます (@ref{Running subprocess}参照)。
@c COMMON
@item EC Qualifier
@c EN
@tab This is for SRFI-42 Eager Comprehension qualifiers.
(@pxref{Eager comprehensions}).
@c JP
@tab これはSRFI-42の先行評価的内包表記(Eager Comprehension)における
qualifierの説明に使われます
(@ref{Eager comprehensions})参照。
@c COMMON
@end multitable

@c EN
For functions, special forms and macros, the entry may be followed
by one or more arguments.  In the argument list, the following notations
may appear:
@c JP
手続き、特殊形式、マクロに関しては、エントリの後に引数の仕様が示されます。
引数リストの中には次のような表記が現れることがあります。
@c COMMON

@table @code
@item arg @dots{}
@c EN
Indicates zero or more arguments.
@c JP
ゼロ個以上の可変個の引数。
@c COMMON
@item :optional @var{x} @var{y} @var{z}
@itemx :optional (@var{x} @var{x-default}) (@var{y} @var{y-default}) @var{z}
@c EN
Indicates it may take up to three optional arguments.
The second form specifies default values to @var{x} and @var{y}.
This is Gauche's enhancement to Scheme; see @ref{Making procedures}
for the definition of complete argument list syntax.
@c JP
省略可能な引数の表記。この例では3つまでの省略可能な引数が取られることを示します。
2番目の形式では@var{x}と@var{y}について省略された場合の既定値も示しています。
この形式の引数表記は、Schemeに対するGaucheの独自拡張です。
完全な仕様については@ref{Making procedures}を参照してください。
@c COMMON
@item :key @var{x} @var{y} @var{z}
@itemx :key (@var{x} @var{x-default}) (@var{y} @var{y-default}) @var{z}
@c EN
Indicates it may take keyword arguments @var{x}, @var{y} and @var{z.}
The second form shows the default values for @var{x} and @var{y}.
This is also Gauche's enhancement to Scheme; see @ref{Making procedures}
for the definition of complete argument list syntax.
@c JP
キーワード引数の表記。この例では@var{x}、@var{y}、@var{z}の3つのキーワード引数を
取ることが示されます。2番目の形式では@var{x}と@var{y}について省略された場合の
既定値も示しています。
この形式の引数表記も、Schemeに対するGaucheの独自拡張です。
完全な仕様については@ref{Making procedures}を参照してください。
@c COMMON
@item :rest @var{args}
@c EN
Indicates it may take rest arguments.
This is also Gauche's enhancement to Scheme; see @ref{Making procedures}
for the definition of complete argument list syntax.
@c JP
残りの引数全てがリストになって@var{args}に束縛されることを示します。
この形式の引数表記も、Schemeに対するGaucheの独自拡張です。
完全な仕様については@ref{Making procedures}を参照してください。
@c COMMON
@end table

@c EN
Following the entry line, we may indicate the specification the
entry comes from, and/or the module the entry is provided when
it's not built-in.
@c JP
項目の行に続いて、もし項目が特定の標準に準拠している場合はその標準が示され、
また項目が組み込みでない場合はその項目を提供するモジュールが示されます。
@c COMMON

@c EN
The specification is shown in brackets.  You'll see the following variations.
@c JP
標準は角括弧でくくって表示されます。以下の標準があります。
@c COMMON

@table @asis
@item [R7RS], [R7RS @i{library}]
@c EN
It is defined in R7RS.  If the entry is about a procedure, a syntax or a
macro, @i{library} is also shown to indicate
the name is exported from the @code{scheme.@i{library}} module
(or the @code{(scheme @i{library})} library, in R7RS terms).
@c JP
R7RSで定義されています。このエントリが手続き、構文、マクロについてものならば、
@i{library}も合わせて示されます。これは、
その名前が@code{scheme.@i{library}}モジュール
(R7RS用語では、@code{(scheme @i{library})}ライブラリ)
からエクスポートされてていることを示します。
@c COMMON
@item [R7RS+], [R7RS+ @i{library}]
@c EN
It is defined in R7RS, but extended by Gauche, e.g. accepting more
optional arguments or different type of arguments.
The description
contains how it is extended from R7RS.  When you're writing a portable
program, you need to be careful not to use Gauche-specific features.
@c JP
R7RSで定義されていますが、Gauche独自の拡張(より多くの省略可能引数を受け付けたり、
異なる型の引数についても動作したりなど)があります。
説明部分で、R7RSからどう拡張されているかが記述されます。
ポータブルなプログラムを書いている時は、Gauche独自拡張の機能を使わないように
注意してください。
@c COMMON
@item [R6RS], [R6RS+], [R5RS], [R5RS+]
@c EN
It is defined in R6RS or R5RS.  The plus sign means it has extended by Gauche.
Since R7RS is mostly upward-compatible to R5RS, and has a lot
in common with R6RS, we mark an entry as R5RS or R6RS only if
it is not a part of R7RS.
@c JP
R6RSやR5RSで定義されています。
プラス記号がついている場合は、Gauche独自の機能が追加されていることを示します。

R7RSはほぼR5RSの上位互換であり、R6RSとも多くの機能を共有しているので、
R5RS、R6RSの表示はそれらがR7RSに含まれていない場合のみ記されます。
@c COMMON
@item [SRFI-@var{n}], [SRFI-@var{n}+]
@c EN
The entry works as specified in SRFI-@var{n}.  If it is marked as
"[SRFI-@var{n}+]", the entry has additional functionality.
@c JP
この項目はSRFI-@var{n}に定義されるように動作します。
"[SRFI-@var{n}+]"とマークされている場合は
SRFI-@var{n}の仕様に上位互換な形で追加の機能が実装されていることを示します。
@c COMMON
@item [POSIX]
@c EN
The API of the entry reflects the API specified in POSIX.
@c JP
この項目はPOSIXのAPIを反映していることを示します。
@c COMMON
@end table

@c EN
The module is shown in curly-braces.  If the module isn't shown,
it is built-in for Gauche.  (Note: When you're writing R7RS code,
Gauche built-ins are available through @code{(gauche base)} module,
@pxref{Importing gauche built-ins}).

Some entries may be available from more than one modules through
re-exporting or module inheritance.  We only list the primary module
in that case.
@c JP
モジュールは@{@}内に示されます。モジュールが示されていない項目は、
Gaucheの組み込みです。(R7RSコードを書いている場合、Gaucheの組み込みは
@code{(gauche base)}モジュールで提供されます。
詳しくは@ref{Importing gauche built-ins}参照)。

項目によっては、再エクスポートやモジュール継承によって、
複数のモジュールから提供されるものもあります。
その場合、元になるモジュールが示されます。
@c COMMON

@c EN
Here's an actual entry for an example:
@c JP
例として、実際のエントリのひとつはこんな具合です:
@c COMMON

@example
 -- Function: utf8->string u8vector :optional start end
     [R7RS base] @{gauche.unicode@} Converts a sequence of utf8 octets in
     U8VECTOR to a string.  Optional START and/or END argument(s) will
     limit the range of the input.
@end example

@c EN
This shows the function @code{utf8->string} is specified by R7RS, in
@code{(scheme base)} library.  Gauche originally provides it from
@code{gauche.unicode} module.  You can import the function from either
one, but in general, it's good to use @code{(import (scheme base))}
when writing R7RS code, and @code{(use gauche.unicode)} when writing
Gauche code.  @xref{R7RS integration}, for the details of differences
in writing in R7RS and Gauche.
@c JP
これは、関数@code{utf8->string}はR7RSで定義され、
ライブラリ@code{(scheme base)}にある名前となっており、
Gaucheではもともと@code{gauche.unicode}モジュールで提供されている、ということを示します。
実際に使う場合は、どちらからインポートしても構いません。
一般的には、R7RSコードを書いている時には@code{(import (scheme base))}を、
Gaucheコードを書いている時には@code{(use gauche.unicode)}を使うと良いでしょう。
R7RSとGaucheでの作法の違いについては@ref{R7RS integration}を参照してください。
@c COMMON


@node Names and namespaces,  , Entry format, Notations
@subsection Names and namespaces
@c NODE 名前と名前空間

@c EN
Since R6RS, you can split toplevel definitions of Scheme programs
into multiple namespaces.  In the standards such namespaces are called
@emph{libraries}.  Gauche predates R6RS and has been calling
them @emph{modules}, and we use the latter throughout this manual.
@c JP
R6RSから、Schemeプログラムのトップレベル定義を複数の名前空間に分けて
書くことができるようになりました。Schemeの言語標準では名前空間を
@emph{ライブラリ}と呼んでいます。GaucheはR6RSより前から名前空間を
サポートし、@emph{モジュール}と呼んできました。本マニュアルでは
従来どおり@emph{モジュール}という呼称を使います。
@c COMMON

@c EN
(Note: RnRS libraries are more abstract concept than Gauche's
modules; RnRS defines libraries in a way that they can be implemented
in various ways, and it just happens that Gauche realises the library
semantics using modules.  When you write a portable R7RS library,
be aware not to rely on Gauche-specific module semantics.  Especially,
RnRS libraries are more static than Gauche modules; you cannot
add definitions to exiting libraries within RnRS, for example.)
@c JP
(註: RnRSライブラリは、厳密に言えばGaucheのモジュールよりも抽象的な概念です。
RnRSでは処理系がライブラリを様々な方法で実装できるように規定しています。
Gaucheではたまたま、モジュールという仕組みを使ってRnRSライブラリのの概念が
実現されているということです。ポータブルなR7RSライブラリを書く時は、
Gauche特有のモジュールのセマンティクスに依存しないように気をつけてください。
特に、RnRSライブラリはGaucheのモジュールよりも静的です。
例えばRnRSの規格内では、既に存在するライブラリに定義を追加することはできません。)
@c COMMON

@c EN
Sometimes the same name is used for multiple definitions in
different modules.  If we need to distinguish those names,
we prefix the name with the module name and a hash sign.
For example, @code{gauche#lambda} means @code{lambda}
defined in @code{gauche} module.  This does not mean
you can write @code{gauche#lambda} in the source code,
though: This notation is just for explanation.
@c JP
時に、同じ名前に対して異なるモジュールで別々の定義が与えられることがあります。
それらを区別する必要がある時は、本マニュアルでは名前の前にモジュール名と
ハッシュ記号をつけて表記します。例えば、@code{gauche#lambda}は
@code{gauche}モジュールで定義された@code{lambda}を指します。
これはあくまで説明のための表記で、
ソースコードに@code{gauche#lambda}と書けるわけではないことに
注意してください。
@c COMMON


@c @node Structure of this document,  , Notations, Introduction
@c @section Structure of this document
@c @c NODE 本書の構成

@c @c EN

@c @c JP
@c @c COMMON

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
