program.texi

@node Programming in Gauche, Core syntax, Concepts, Top
@chapter  Programming in Gauche
@c NODE Gaucheでのプログラミング

@menu
* Invoking Gosh::
* Interactive development::
* Writing Scheme scripts::
* Debugging::
* Platform-dependent features::
* Profiling and tuning::
* Auxiliary programs::
* Writing Gauche modules::
* Using extension packages::
* Building standalone executables::
@end menu

@node Invoking Gosh, Interactive development, Programming in Gauche, Programming in Gauche
@section Invoking Gosh
@c NODE Gaucheを起動する

@c EN
Gauche can be used either as an independent Scheme scripting engine
or as an embedded Scheme library.   An interactive interpreter
which comes with Gauche distribution is a program named @code{gosh}.
@c JP
Gaucheは独立したSchemeスクリプティングエンジンとしても、組み込みのSchemeライブラリとしても
使うことができます。Gaucheのディストリビューションには、@code{gosh}という
インタラクティブなインタプリタが附属しています。
@c COMMON

@deftp {Program} gosh [options] [scheme-file arg @dots{}]
@c EN
Gauche's interpreter.   Without @var{scheme-file}, @code{gosh} works
interactively, i.e. it reads a Scheme expression from the standard input,
evaluates it, and prints the result, and repeat that until it reads EOF or
is terminated.
@c JP
Gaucheのインタプリタです。  @var{scheme-file}が与えられなければ、
@code{gosh}はインタラクティブに動作します。すなわち、標準入力からScheme式を読み込み、
それを評価して結果をプリントするという動作を、EOFを読むか明示的に終了させられるまで
続けます。
@c COMMON

@c EN
If @code{gosh} is invoked without @var{scheme-file}, but the input
is not a terminal, it enters read-eval-print loop but not writes
out a prompt while waiting input form.  This is useful when you
pipe Scheme program into @code{gosh}.  You can force this behavior
or suppress this behavior by @code{-b} and @code{-i} options.
@c JP
もし@var{scheme-file}が与えられておらず、しかし入力が端末でない場合、
@code{gosh}はread-eval-printループに入りますが、入力待ちの際にプロンプトを
表示しません。これはScheme式をパイプで@var{gosh}に処理させる場合に便利です。
@code{-b}または@code{-i}オプションでこの動作を強制的にonまたはoffできます。
@c COMMON

@c EN
If @var{scheme-file} is specified, @code{gosh} runs it as a
Scheme program and exit.
@xref{Writing Scheme scripts}, for details.
@c JP
@var{scheme-file}が与えられた場合、@code{gosh}はそれをSchemeプログラムとして
ロードし、終了します。この動作に関しては@ref{Writing Scheme scripts}を参照して
下さい。
@c COMMON
@end deftp

@c EN
@subheading Command-line options
@c JP
@subheading コマンドラインオプション
@c COMMON

@c EN
The following command line options are recognized by @code{gosh}.
The first command line argument which doesn't begin with `@minus{}'
is recognized as the script file.  If you want to specify a file
that begins with a minus sign, use a dummy option `@code{--}'.
@c JP
@code{gosh}には以下のようなコマンドラインオプションがあります。
`@minus{}' で始まらない最初のコマンドライン引数がスクリプトファイルと認識されます。
スクリプトファイル名が `@minus{}' で始まっている可能性がある場合は、ダミーオプション
`@code{--}' をスクリプトファイル名の前に置いて下さい。
@c COMMON

@deftp {Command Option} -I path
@c EN
Prepends @var{path} to the load path list.
You can specify this option more than once to add multiple paths.
@c JP
@var{path}をロードパスのリストの最初に加えます。このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -A path
@c EN
Appends @var{path} to the tail of the load path list.
You can specify this option more than once to add multiple paths.
@c JP
@var{path}をロードパスのリストの末尾に加えます。このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -q
@c EN
Makes @code{gosh} not to load the default initialization file.
@c JP
@code{gosh}が起動時にシステムの初期化ファイルをロードしないようにします。
@c COMMON
@end deftp

@deftp {Command Option} -V
@c EN
Prints the @code{gosh} version and exits.
@c JP
@code{gosh}のバージョンを表示して終了します。
@c COMMON
@end deftp

@deftp {Command Option} -v version
@c EN
If @var{version} is not the running @code{gosh}'s version, execute the
specified version of @code{gosh} instead if it is installed.
This is useful when you want to invoke specific version of Gauche.
Note that @var{version} must be 0.9.6 or later.
@c JP
@var{version}が実行された@code{gosh}のバージョンでなく、かつ指定されたバージョンの
Gaucheがシステムにインストールされていた場合、指定バージョンの@code{gosh}をかわりに起動します。
これは、Gaucheのバージョンを特定して実行したい場合に便利です。
なお、この機能で指定できる@var{version}は0.9.6かそれ以降のみです。
@c COMMON
@end deftp


@deftp {Command Option} -u module
@c EN
Use @var{module}.  Before starting execution of @var{scheme-file} or entering
the read-eval-print loop, the specified module is @var{use}d, i.e.
it is loaded and imported (@xref{Defining and selecting modules}, for details of @code{use}).
You can specify this option more than once to use multiple modules.
@c JP
起動後、インタラクティブなread-eval-printループに入る前、もしくは@var{scheme-file}
をロードする前に@var{module}を``use''します。つまりそのモジュールがロードされ
インポートされます。(@code{use}の詳細については@ref{Defining and selecting modules}を参照して下さい。)
このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -l file
@c EN
Load @var{file} before starting execution of @var{scheme-file} or entering
the read-eval-print loop.   The file is loaded in the same way as
@code{load} (@pxref{Loading Scheme file}).
You can specify this option more than once to load multiple files.
@c JP
起動後、インタラクティブなread-eval-printループに入る前、もしくは@var{scheme-file}
をロードする前に@var{file}をロードします。ロードの詳細については@ref{Loading Scheme file}
を参照して下さい。このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -L file
@c EN
Load @var{file} like @code{-l}, but if @var{file} does not exist,
this silently ignores it instead of reporting an error.
This option can also be specified multiple times.
@c JP
@code{-l}オプションと同様に@var{file}をロードしますが、
@var{file}が見つからなかった場合はエラーを報告せずに黙って無視します。
このオプションも複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -e scheme-expression
@c EN
Evaluate @var{scheme-expression}
before starting execution of @var{scheme-file} or entering
the read-eval-print loop.   Evaluation is done in the
@var{interaction-environment} (@pxref{Eval and repl}).
You can specify this option more than once to evaluate multiple expressions.
@c JP
起動後、インタラクティブなread-eval-printループに入る前、もしくは@var{scheme-file}
をロードする前に@var{scheme-expression}を評価します。評価は
@var{interaction-environment}中で行われます(@ref{Eval and repl}参照)。
このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -E scheme-expression
@c EN
Same as -e, except the @var{scheme-expression} is read
as if it is surrounded by parenthesis.  For example:
@c JP
オプション-eとほぼ同じですが、@var{scheme-expression}は
それが括弧で囲まれているかのように読まれます。
このオプションは複数指定できます。例：
@c COMMON
@example
% gosh -umath.const -E"print (sin (* pi/180 15))" -Eexit
0.25881904510252074
@end example
@end deftp

@deftp {Command Option} -b
@c EN
Batch. Does not print prompts even if the input is a terminal.
@c JP
バッチ。入力が端末であってもプロンプトを出さないようにします。
@c COMMON
@end deftp

@deftp {Command Option} -i
@c EN
Interactive. Print prompts even if the input is not a terminal.
@c JP
インタラクティブ。入力が端末で無くてもプロンプトを出すようにします。
@c COMMON
@end deftp

@deftp {Command Option} -m module
@c EN
When a script file is given,
this option makes the module named @var{module} in which
the @code{main} procedure is looked for, instead of the @code{user} module.
See @ref{Writing Scheme scripts} for the details of executing scripts.

If the named module doesn't exist after loading the script,
an error is signaled.

This is useful to write a Scheme module that can also be executed
as a script.
@c JP
スクリプトファイルが与えられた場合に、@code{main}手続きを
探すモジュールを指定します。デフォルトでは@code{user}モジュールが探されます。
スクリプトの実行について詳しくは@ref{Writing Scheme scripts}を見てください。

@var{module}で指定されたモジュールが、スクリプトファイルのロード後にも
存在しない場合は、エラーが報告されます。

このオプションは、スクリプトとしても使えるようなSchemeモジュールを書く際に便利です。
@c COMMON
@end deftp

@deftp {Command Option} -f compiler-option
@c EN
This option controls compiler and runtime behavior.  For now we have
following options available:
@table @asis
@item case-fold
Ignore case for symbols.
@item include-verbose
Reports whenever a file is included.
Useful to check precisely which files are included in what order.

@item load-verbose
Reports whenever a file is loaded.
Useful to check precisely which files are loaded in what order.
@item no-inline
Prohibits the compiler from inlining procedures and constants. Equivalent to
no-inline-globals, no-inline-locals, no-inline-constants
and no-inline-setters combined.
@item no-inline-constants
Prohibits the compiler from inlining constants.
@item no-inline-globals
Prohibits the compiler from inlining global procedures.
@item no-inline-locals
Prohibits the compiler from inlining local procedures.
@item no-inline-setters
Prohibits the compiler from inlining setters.
@item no-lambda-lifting-pass
Prohibits the compiler from running lambda-lifting pass.
@item no-post-inline-pass
Prohibits the compiler from running post-inline optimization pass.
@item no-source-info
Don't keep source information for debugging.  Consumes less memory.
@item safe-string-cursors
String cursors used on wrong strings will raise an error. This may
cause performance problems because all cursors will be allocated on
heap. @xref{String cursors}.
@item test
Adds "@code{../src}" and "@code{../lib}" to the load path before loading
initialization file.  This is useful when you want to test the
compiled @code{gosh} REPL without installing it.
@item warn-legacy-syntax
Warns if the reader sees legacy hex-escape syntax in string literals.
@xref{Reader lexical mode}.
@xref{Case-sensitivity}.
@end table
@c JP
このオプションはコンパイラとランタイムの動作に影響を与えます。
今のところ、次のオプションのみが@var{compiler-option}として有効です。
@table @asis
@item no-inline
一切のインライン展開を行いません。このオプションは以下の no-inline-globals
no-inline-locals および no-inline-constants を同時に指定したのと等価です。
@item no-inline-globals
大域(global)関数のインライン展開を展開を行ないません。
@item no-inline-locals
局所(local)関数のインライン展開を展開を行ないません。
@item no-inline-constants
定数のインライン展開を行ないません。
@item no-post-inline-pass
インライン展開後に再び最適化パスを走らせるのを抑止します。
@item no-lambda-lifting-pass
lambda lifting最適化パスを抑止します。
@item no-source-info
デバッグのためのソースファイル情報を保持しません。メモリの使用量は小さくなります。
@item load-verbose
ファイルがロードされる時にそれを報告します。
正確にどのファイルがどういう順序でロードされているかを調べるのに便利です。
@item include-verbose
ファイルがincludeされる時にそれを報告します。
正確にどのファイルがどういう順序でincludeされているかを調べるのに便利です。
@item warn-legacy-syntax
文字列リテラル中に古い形式の16進数エスケープ形式があったら警告します。
@ref{Reader lexical mode} を参照して下さい。
@item case-fold
シンボルの大文字小文字を区別しません。
@ref{Case-sensitivity} を参照して下さい。
@item test
"@code{../src}" と "@code{../lib}" を、初期化ファイルを読む前に
ロードパスに加えます。これは、作成された@code{gosh}をインストールせずに
実行してみるのに便利です。
@end table
@c COMMON
@end deftp

@deftp {Command Option} -p profiler-option
@c EN
Turn on the profiler.  The following @var{profiler-option} is recognized:
@c JP
プロファイラを有効にします。以下のような@var{profiler-option}が
今のところサポートされています。
@c COMMON

@table @code
@item time
@c EN
Records and reports time spent on function calls and number of times
each function is called.
@c JP
関数中で費された時間と、各関数が呼ばれた回数を記録して報告します。
@c COMMON
@item load
@c EN
Records and reports time spent on loading each modules.
Useful to tune start-up time of the scripts.
(Results are in elapsed time).
@c JP
各モジュールをロードするのにかかった時間を記録して報告します。
スクリプトの起動時間をチューンするのに便利です
(実経過時間が報告されます)。
@c COMMON
@end table

@c EN
See @ref{Using profiler} for the details of the profiler.
@c JP
詳しくは@ref{Using profiler}を参照して下さい。
@c COMMON
@end deftp

@deftp {Command Option} -r standard-revision
@c EN
Start @code{gosh} with an environment of the specified revision
of Scheme standard.  Currently only 7 is supported as
@var{standar-revision}.

By default, @code{gosh} starts with @code{user} module, which inherits
@code{gauche} module.  That means you can use whole Gauche core
procedures by default without explicitly declaring it.

Proper R7RS code always begins with either @code{define-library}
or R7RS-style @code{import} form, and Gauche recognizes it and
automatically switch to R7RS environments so that R7RS scripts and libraries
can be executed by Gauche without special options.
However, users who are learning R7RS Scheme may be confused
when the initial environment doesn't look like R7RS.

By giving @code{-r7} option, @code{gosh} starts with @code{r7rs.user} module
that extends the @code{r7rs} module, which defines two R7RS forms,
@code{import} and @code{define-library}.

If you invoke @code{gosh} into an interactive REPL mode with @code{-r7} option,
all standard R7RS-small libraries (except @code{(scheme r5rs)}) are already
imported for your convenience.

@xref{Library modules - R7RS standard libraries}, for the details on
how Gauche supports R7RS.

(Note: The @code{-r7} option doesn't change reader lexical mode
(@pxref{Reader lexical mode}) to @code{strict-r7}.  That's because
using @code{strict-r7} mode by default prevents many Gauche code
from being loaded.)
@c JP
@code{gosh}を、指定されたリビジョンのScheme標準環境で起動します。
現在のバージョンでは@var{standard-revision}として7のみがサポートされます。

デフォルトでは、@code{gosh}起動時のモジュールは@code{user}モジュールで、
これは@code{gauche}モジュールを継承しています。すなわち、特に何も指定しないでも
Gaucheのコア関数は全て使えるようになっています。

正しいR7RSプログラムは常に@code{define-library}フォームか
R7RS式の@code{import}フォームで始まり、Gaucheはそれらを見つけると
自動的にR7RS環境へと切り替えるので、特になにもしなくても
R7RSスクリプトやライブラリを使うことはできます。
しかし、R7RS Schemeを勉強中のユーザにとっては、最初に入る環境が
R7RSでないと混乱してしまうかもしれません。

@code{-r7}オプションが与えられると、@code{gosh}は起動時のモジュールを
@code{r7rs.user}モジュールにします。これは@code{r7rs}モジュールを継承した
もので、@code{import}と@code{define-library}だけが定義されています。

@code{-r7}をつけた@code{gosh}を対話REPLとして起動した場合は、簡便のために
@code{(scheme r5rs)}を除く全てのR7RS-smallライブラリが
importされた状態になっています。

GaucheがR7RSをどのようにサポートしているかの詳細については
@ref{Library modules - R7RS standard libraries}を参照してください。

(註: @code{-r7}オプションは、リーダ字句モードを@code{strict-r7}に
替えることはしません。@code{strict-r7}モードをデフォルトにすると、
多くのGaucheコードをロードすることができなくなるからです。リーダ字句モードについては
@ref{Reader lexical mode}を参照してください。)
@c COMMON
@end deftp


@deftp {Command Option} @code{--}
@c EN
When @code{gosh} sees this option, it stops processing the options
and takes next command line argument as a script file.  It is useful
in case if you have a script file that begins with a minus sign,
although it is not generally recommended.
@c JP
このオプションに出会うと、@code{gosh}はオプションの解析を止めて、その次の引数を
無条件に@var{scheme-file}であると見倣します。@var{scheme-file}がマイナス記号で
始まっている場合に必要です。
@c COMMON
@end deftp

@c EN
The options -I, -A, -l, -u, -e and -E are processes in the order
of appearance.  For example, adding a load path by -I affects the
-l and -u option after it but not before it.
@c JP
オプション-I, -A, -l, -u, -e 及び -E は、それらがコマンドライン引数として
出現した順に処理されます。例えば、-Iにより追加されるロードパスは
それ以降の-lや-uオプションに影響を与えますが、それ以前のものには影響を
与えません。
@c COMMON

@c EN
@subheading Environment variables
@c JP
@subheading 環境変数
@c COMMON

@c EN
The following environment variables are recognized:
@c JP
以下の環境変数を認識します。
@c COMMON

@deftp {Environment variable} GAUCHE_AVAILABLE_PROCESSORS
@c EN
You can get the number of system's processors by
@code{sys-available-processors} (@pxref{Environment inquiry});
libraries/programs may use this info to optimize number of
parallel threads.  But you might change that, for testing
and benchmarking---e.g. a program automatically uses
8 threads if there are 8 cores, but you might want to run it
with 1, 2, 4 threads as well to see the effect of parallelization.
This environment variable overrides
the return value of @code{sys-available-processors}.
@c JP
@code{sys-available-processors} でシステムのプロセッサ数を
取得できます(@ref{Environment inquiry}参照)。
ライブラリやプログラムの中には、その数に基づいて並行に走るスレッド数を
調整するものがあります。けれども、テストやベンチマークでその数を
変えたいと思うことがあるかもしれません。例えば、8コア上では自動的に
8スレッド使うプログラムがあったとして、並列化の効果を見るためにその
プログラムを1,2,4スレッドで走らせてベンチマークを取る、といった場合です。
この環境変数は、@code{sys-available-processors}が返す値を上書きします。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_CHECK_UNDEFINED_TEST
@c EN
Warn if @code{#<undef>} is used in the test expression of branch.

In boolean context, @code{#<undef>} counts true.  It is also
often the case that a procedure returns @code{#<undef>} when
the return value doesn't matter, and you shouldn't rely on
the value that is supposed not to matter--the procedure may
change the return value in future (which should be ok, since
the value shouldn't have mattered), which can cause unintentional
and hard-to-track bugs.
@xref{Undefined values}, for the details.

We strongly recommend users to turn on this warning.  In future,
we plan to make this default.
@c JP
@code{#<undef>}が条件式のテスト式に使われた場合に警告を出します。

真偽値判定では@code{#<undef>}は真とみなされます。しかし、
@code{#<undef>}を返す手続きはしばしば、
「戻り値に意味はない」ことを示すためにそれを返しています。
戻り値に意味がないなら、その値に依存したコードを書くべきではありません。
もし、手続きが将来、もともと意味が無いのだからと戻り値を変えた場合に、
@code{#<undef>}に依存してたコードは壊れる可能性があります。
詳しくは@ref{Undefined values}を参照してください。

この機能はなるべくONtにしておくようにお勧めします。
将来はデフォルトで警告を出すようにする予定です。
@c COMMON
@end deftp


@deftp {Environment variable} GAUCHE_DYNLOAD_PATH
@c EN
You can specify additional load paths for dynamically loaded
objects by this environment variable, delimiting the paths by '@code{:}'.
The paths are appended before the system default load paths.

@xref{Loading dynamic library}, for the details of how Gauche
finds dynamically loadable objects.
@c JP
この変数によって、動的にロードするオブジェクト用の追加ロードパスを
指定できます。パスは '@code{:}' で区切ります。
この変数によって指定されたパスはシステムのデフォルトのロードパスの前に
連結されます。

Gaucheが動的にロードするオブジェクトファイルを探す方法については
@ref{Loading dynamic library}を参照してください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_EDITOR
@deftpx {Environment variable} EDITOR
@c EN
This is used by @code{ed} procedure in @code{gauche.interactive} module.
@xref{Interactive session}, for the details.
@c JP
これは@code{gauche.interactive}モジュールの@code{ed}手続きで使われます。
詳しくは@ref{Interactive session}を参照してください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_HISTORY_FILE
@c EN
Specifies the filename where the REPL history is saved.
If this environment varible is not set, history is saved
in @file{~/.gosh_history}.  If this environment variable
is set but an empty string, history isn't saved.
If the process is suid/sgid-ed, history won't be saved.
@c JP
REPLのヒストリがセーブされるファイル名を指定します。
この環境変数が定義されていなければ、ヒストリは@file{~/.gosh_history}にセーブされます。
この環境変数が定義されており、しかし空文字列だった場合はヒストリはセーブされません。
(また、プロセスがsuid/sgidされている場合もヒストリは保存されません)。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_KEYWORD_DISJOINT
@deftpx {Environment variable} GAUCHE_KEYWORD_IS_SYMBOL
@c EN
These two environment variables affect whether keywords are treated
as symbols or not.  @xref{Keywords}, for the details.
@c JP
この二つの環境変数は、キーワードがシンボルとして扱われるかどうかに影響します。
詳しくは@ref{Keywords}を参照してください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_LEGACY_DEFINE
@c EN
Make the behavior of toplevel @code{define} the same as
0.9.8 and before.
It allows certain legacy programs that aren't valid R7RS.
@xref{Into the Scheme-Verse}, for the details.
@c JP
トップレベルの@code{define}の振る舞いを0.9.8およびそれ以前のものに
合わせます。これは、厳密にはR7RSに従わない、古いコードを走らせる必要が
ある場合に使ってください。詳しくは
@ref{Into the Scheme-Verse}参照。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_LOAD_PATH
@c EN
You can specify additional load paths by this environment
variable, delimiting the paths by '@code{:}'.
The paths are appended before the system default load paths.

@xref{Loading Scheme file}, for the details of how Gauche finds
files to load.
@c JP
この環境変数によって、追加するロードパスを指定できます。
パスは '@code{:}' で区切ります。
この変数によって指定されたパスはシステムのデフォルトのロードパスの前に
連結されます。

GaucheがロードするSchemeファイルを見つける方法について詳しくは
@ref{Loading Scheme file}を参照してください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_MUTABLE_LITERALS
@c EN
Allow literal lists and vectors to be mutated.  Such code isn't a
valid Scheme program and causes an error,
but Gauche didn't enforce the restriction
on 0.9.9 and before, so some legacy code may accidentally mutates
literals.  Set this environment variables to run such old programs.
@xref{Literals}, for the details.
@c JP
リテラルリストとリテラルベクタの改変を許します。
そういったコードは正しいSchemeプログラムではなく、今のGaucheはエラーを投げますが、
0.9.9とそれ以前のバージョンではリテラルリストとリテラルベクタの変更はチェックされて
いませんでした。うっかりリテラルを変更してしまっている古いコードを走らせたい場合のみ
この環境変数をセットしてください。詳しくは@ref{Literals}参照。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_NO_READ_EDIT
@c EN
Disable line-editor on REPL prompt, even the terminal is capable.
You can also turn it off with @code{-fno-read-edit} command-line option,
or @code{,edit off} toplevel commands during REPL session.
@xref{Interactive development}, for the details of line editing.
@c JP
REPLプロンプトでの行編集機能をオフにします。
行編集機能はまた、@code{-fno-read-edit}コマンドラインオプションや、
REPLセッション中の @code{,edit off} トップレベルコマンドでも切ることができます。
詳しくは@ref{Interactive development}を参照してください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_QUASIRENAME_MODE
@c EN
This affects @code{quasirename} behavior, to keep the backward
compatibility with 0.9.7 and before.
@xref{Explicit-renaming macro transformer}, for the details.
@c JP
これは@code{quasirename}の振る舞いに影響を与え、
0.9.7以前との互換性のために使われます。詳しくは
@ref{Explicit-renaming macro transformer}を参照してください。
@c COMMON
@end deftp


@deftp {Environment variable} GAUCHE_REPL_NO_PPRINT
@c EN
This is used by @code{gauche.interactive} module to suppress
pretty-printing on REPL prompt.
@xref{Interactive development}, for the details.
@c JP
これはREPLプロンプトでプリティプリントを抑制するために
@code{gauche.interactive}で使われます。
詳しくは@ref{Interactive development}を参照してください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_SUPPRESS_WARNING
@c EN
Suppress system warnings (@code{WARNING: ...}).  Not generally recommended;
use only if you absolutely need to.
@c JP
システムの警告(@code{WARNING: ...})を抑止します。気軽に使うべきではありません。
どうしても必要な場合のみ使ってください。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_TEST_RECORD_FILE
@c EN
This is used by @code{gauche.test} module (@pxref{Unit testing}).
If defined, names a file the test processes
keep the total statistics.
@c JP
@code{gauche.test}モジュールで使われます(@ref{Unit testing}参照)。
定義されていた場合、その値を名前とするファイルにテストの統計が記録されます。
@c COMMON
@end deftp

@deftp {Environment variable} GAUCHE_TEST_REPORT_ERROR
@c EN
This is used by @code{gauche.test} module (@pxref{Unit testing}).
If defined, reports stack trace to stderr
when the test thunk raises an error (even when it is expected).
Useful for diagnosis of unexpected errors.
@c JP
@code{gauche.test}モジュールで使われます(@ref{Unit testing}参照)。
定義されていた場合、テストのthunkがエラーを報告した場合に、
スタックトレースを標準エラー出力に表示します
(エラーがもともと期待されているテストでも出力されます)。
予想外のエラー発生の原因を調べるのに便利です。
@c COMMON
@end deftp


@deftp {Environment variable} TMP
@deftpx {Environment variable} TMPDIR
@deftpx {Environment variable} TEMP
@deftpx {Environment variable} USERPROFILE
@c EN
These may affect the return value of @code{sys-tmpdir}.
Different environment variables may be used on different platforms.
@xref{Pathnames}, for the details.
@c JP
これらは@code{sys-tmpdir}の返り値に影響を与えます。プラットフォームによって
参照される環境変数は異なります。@ref{Pathnames}を参照してください。
@c COMMON
@end deftp


@c EN
@subheading Windows-specific executable
@c JP
@subheading Windows特有の実行ファイル
@c COMMON

@c EN
On Windows-native platforms (mingw), two interpreter executables are
installed.  @code{gosh.exe} is compiled as a Windows console
application and works just like ordinary @code{gosh}; that is,
it primarily uses standard i/o for communication.
Another executable, @code{gosh-noconsole.exe}, is compiled
as a Windows no-console (GUI) application.  It is not attached
to a console when it is started.  Its standard input is connected
to the @code{NUL} device.  Its standard output and standard error
output are special ports which open a new console when something
is written to them for the first time.  (NB: This magic only works
for output via Scheme ports; direct output from low-level C libraries
will be discarded.)
@c JP
Windowsネイティブ環境(mingw)では、インタプリタとしてふたつの
実行ファイルがインストールされます。
@code{gosh.exe}はWindowsコンソールアプリケーションとしてコンパイルされ、
普通の@code{gosh}のように、標準入出力を第一の通信手段とします。
もう一つの実行ファイル@code{gosh-noconsole.exe}はWindows非コンソールアプリケーション
としてコンパイルされています。こちらは起動時にコンソールに接続されません。
標準入力は@code{NUL}デバイスに接続されます。標準出力と標準エラー出力は
特殊なポートに接続され、最初に書き込みがあった時点で新たなコンソールが作られて
出力されます。(このトリックはSchemeポート経由の出力のみで動きます。
低レベルのCライブラリが標準出力や標準エラー出力に直接書き出したデータは捨てられます)。
@c COMMON

@c EN
The main purpose of @code{gosh-noconsole.exe} is for Windows
scripting.   If a Scheme script were associated to @code{gosh.exe}
and invoked from Explorer, it would always open a new
console window, which is extremely annoying.
If you associate Scheme scripts to @code{gosh-noconsole.exe} instead,
you can avoid console from popping up.
@c JP
@code{gosh-noconsole.exe}の目的は、Windows上でのスクリプティングです。
Schemeスクリプトがもし@code{gosh.exe}に関連付けられていたとしたら、
Explorerからそのスクリプトを起動するたびに、
必ず新しいコンソールウィンドウが開くので非常に煩わしいです。
Schemeスクリプトを@code{gosh-noconsole.exe}に
関連づけておけば、この煩わしいコンソールの出現を抑制できます。
@c COMMON

@c EN
If you're using the official Windows installer, Scheme scripts
(@file{*.scm}) have already associated to @code{gosh-noconsole.exe}
and you can invoke them by double-clicking on Explorer.
Check out some examples under @file{C:\Program Files\Gauche\examples}.
@c JP
Windows版のオフィシャルのインストーラを使ってGaucheをインストールしたなら、
Schemeスクリプト(@file{*.scm})は既に@code{gosh-noconsole.exe}に
関連づけられているので、ExplorerからSchemeスクリプトをダブルクリックすれば
Schemeプログラムを走らせることができます。
@file{C:\Program Files\Gauche\examples}の下にいくつかサンプルが
あります
@c COMMON

@c ----------------------------------------------------------------------
@node Interactive development, Writing Scheme scripts, Invoking Gosh, Programming in Gauche
@section Interactive development
@c NODE  インタラクティブな開発

@c EN
When @code{gosh} is invoked without any script files,
it goes into interactive read-eval-print loop (REPL).
@c JP
スクリプトファイルが与えられなかった場合、
@code{gosh}はインタラクティブなread-eval-printループ(REPL)に入ります。
@c COMMON

@c EN
To exit the interpreter, type EOF (usually Control-D in Unix terminals)
or evaluate @code{(exit)}.
@c JP
インタプリタを終了するには、EOF文字(Unix端末では通常Control-D)をタイプするか、
@code{(exit)}を評価します。
@c COMMON

@c EN
In the interactive session, @code{gosh} loads and
imports @code{gauche.interactive}
module (@pxref{Interactive session}) into @code{user} module, for the
convenience.  Also, if there's a file @file{.gaucherc} under
the user's home directory.
You may put settings there that would help interactive debugging.
(As of Gauche release 0.7.3,
@file{.gaucherc} is no longer loaded when @code{gosh} is run
in script mode.)

Note that @file{.gaucherc} is always loaded in the @code{user} module,
even if @code{gosh} is invoked with @code{-r7} option.  The file
itself is a Gauche-specific feature, so you don't need to consider
portability in it.
@c JP
インタラクティブセッションでは、@code{gosh}は
@code{gauche.interactive}モジュールをロードして@code{user}モジュールにインポートします
(@ref{Interactive session}参照)。
また、ユーザーのホームディレクトリに@file{.gaucherc}という
ファイルがあればそれもロードされます。
インタラクティブデバッグに便利な設定をそこに書いておくことができます。
(Gauche release 0.7.3から、@file{.gaucherc}はgoshがスクリプトモードで
起動された時は読まれなくなりました。)

@code{.gaucherc}は常に@code{user}モジュールへとロードされます
(@code{gosh}が@code{-r7}オプションつきで起動されていてもそうです)。
@code{.gaucherc}を自動で読み込む、という機能自体がGauche特有の機能ですから、
そこでポータビリティを考慮する必要はないわけです。
@c COMMON

@c EN
I recommend you to run @code{gosh} inside Emacs, for it has
rich features useful to interact with internal Scheme process.
Put the following line to your @file{.emacs} file:
@example
(setq scheme-program-name "gosh -i")
@end example
And you can run @code{gosh} by @key{M-x run-scheme}.
@c JP
@code{gosh}をEmacs内部で走らせることをお勧めします。
EmacsはSchemeサブプロセスを操作するための豊富な機能を持っています。
次の行を@file{.emacs}に加えておくと、@key{M-x run-scheme} で
Emacsのバッファ内で@code{gosh}が走ります。
@example
(setq scheme-program-name "gosh -i")
@end example
@c COMMON

@c EN
If you run @code{gosh} in the terminal with capability of cursor control,
a basic line-editing feature is available in the REPL session.
@xref{Input editing}, for the details.
@c JP
カーソル制御可能な端末で@code{gosh}を走らせた場合、
REPLセッションで簡単な行編集が使えます。
詳しくは@ref{Input editing}を参照してください。
@c COMMON

@c EN
If you want to use multibyte characters in the interaction,
make sure your terminal's settings is in sync with @code{gosh}'s
internal character encodings.
@c JP
対話環境でマルチバイト文字を使う場合は、端末の文字エンコーディングを@code{gosh}の
内部エンコーディングと合わせるようにして下さい。
@c COMMON

@menu
* Working in REPL::
* Input editing::
@end menu

@node Working in REPL, Input editing, Interactive development, Interactive development
@subsection Working in REPL
@c NODE REPLでの開発

@c EN
When you enter REPL, Gauche prompts you to enter a Scheme expression:
@c JP
REPLに入ると、Gaucheはプロンプトを出してScheme式の入力を待ちます。
@c COMMON

@example
gosh>
@end example

@c EN
(If you enable input editing, the prompt shows @code{gosh$} instead
of @code{gosh>}.  @xref{Input editing}, for the details.)
@c JP
(入力編集機能をオンにしている場合は、プロンプトが@code{gosh>}ではなく
@code{gosh$}になります。詳しくは@ref{Input editing}を参照してください。)
@c COMMON

@c EN
After you complete a Scheme expression and type ENTER,
the result of evaluation is printed.
@c JP
完全なScheme式を入力してENTERをタイプすると、そのS式の評価結果が表示されます。
@c COMMON

@example
gosh> @i{(+ 1 2)}
3
gosh>
@end example

@c EN
The REPL session binds the last three results of evaluation
in the global variables @code{*1}, @code{*2} and @code{*3}.
You can use the previous results via those history variables
in subsequent expressions.
@c JP
REPLセッションは、過去3回分の評価結果をグローバル変数
@code{*1}、@code{*2}、@code{*3} に束縛します。これらのヒストリ変数を
使って、以前の結果を後続の式の中で使えます。
@c COMMON

@example
gosh> @i{*1}
3
gosh> @i{(+ *2 3)}
6
@end example

@c EN
If the Scheme expression yields multiple values
(@pxref{Multiple values}), they are printed one by one.
@c JP
Scheme式が複数の値を返した場合
(@ref{Multiple values}参照)は、各値が順に表示されます。
@c COMMON

@example
gosh> @i{(min&max 1 -1 8 3)}
-1
8
gosh>
@end example

@c EN
The history variable @code{*1}, @code{*2} and @code{*3} only
binds the first value.  A list of all values are bound to
@code{*1+}, @code{*2+} and @code{*3+}.
@c JP
式が多値を返しても、変数@code{*1}、@code{*2}、@code{*3}
に束縛されるのは最初の値のみです。しかし別のグローバル変数
@code{*1+}、@code{*2+}、@code{*3+}に、全ての値をリストにしたものが
束縛されています。
@c COMMON

@example
gosh> @i{*1}
-1
gosh> @i{*2+}
(-1 8)
@end example

@c EN
(Note that, when you evaluate @code{*1} in the above example, the
history is shifted---so you need to use @code{*2+} to refer to the
result of @code{(min&max 1 -1 8 3)}.)
@c JP
(上の例で、@code{*1}を評価した時点でヒストリがひとつずれてしまっていることに
注意してください。@code{(min&max 1 -1 8 3)}の結果を見るためには
@code{*2+}を参照する必要があります。)
@c COMMON

@c EN
The @code{*history} procedure shows the value of history variables:
@c JP
手続き@code{*history}はヒストリ変数の値を表示します。
@c COMMON

@example
gosh> @i{(*history)}
*1: (-1 8)
*2: -1
*3: -1
gosh>
@end example

@c EN
As a special case, if an evaluation yields zero values, history
isn't updated.   The @code{*history} procedure returns
no values, so merely looking at the history won't change the history
itself.
@c JP
特別な場合として、式の評価がゼロ個の値を返した場合は、ヒストリ変数は更新されません。
@code{*history}手続きはゼロ個の値を返すので、ヒストリを見るだけでヒストリが
進んでしまうということはありません。
@c COMMON

@example
gosh> @i{(*history)}
*1: (-1 8)
*2: -1
*3: -1
gosh> (values)
gosh> @i{(*history)}
*1: (-1 8)
*2: -1
*3: -1
@end example


@c EN
Finally, a global variable @code{*e} is bound to the last uncaught
error condition object.
@c JP
最後に、評価途中で捕捉されないエラーが発生した場合は、エラーコンディションオブジェクトが
グローバル変数@code{*e}に束縛されます。
@c COMMON

@example
gosh> @i{(filter odd? '(1 2 x 4 5))}
*** ERROR: integer required, but got x
Stack Trace:
_______________________________________
  0  (eval expr env)
        At line 173 of "/usr/share/gauche-0.9/0.9.3.3/lib/gauche/interactive.scm"
gosh> @i{*e}
#<error "integer required, but got x">
@end example

@c EN
(The error stack trace may differ depending on your installation.)
@c JP
(エラースタックトレースの表示はインストールの状況によって異なる場合があります。)
@c COMMON

@c EN
In REPL prompt, you can also enter special @emph{top-level commands}
for common tasks.  Top-level commands are not Scheme
expressions, not even S-expressions.
They work like traditional line-oriented shell commands instead.
@c JP
REPLプロンプトではまた、よくある仕事のために、特別な@emph{トップレベルコマンド}を
入力することもできます。トップレベルコマンドはScheme式ではありませんし、S式でさえ
ありません。むしろ、伝統的な行指向のシェルコマンドのように動作します。
@c COMMON

@c EN
Top-level commands are prefixed by comma to be distinguished from
ordinary Scheme expressions.  To see what commands are available,
just type @code{,help} and return.
@c JP
トップレベルコマンドは通常のScheme式と区別するために、コンマで始まります。
どういったコマンドが使えるかを見るには、@code{,help}とタイプしてリターンを
入力してみてください。
@c COMMON

@example
gosh> ,help
You're in REPL (read-eval-print-loop) of Gauche shell.
Type a Scheme expression to evaluate.
A word preceded with comma has special meaning.  Type ,help <cmd>
to see the detailed help for <cmd>.
Commands can be abbreviated as far as it is not ambiguous.

 ,apropos|a  Show the names of global bindings that match the regexp.
 ,cd         Change the current directory.
 ,describe|d Describe the object.
 ,help|h     Show the help message of the command.
 ,history    Show REPL history.
 ,info|doc   Show info document for an entry of NAME, or search entries by REGEXP.
 ,load|l     Load the specified file.
 ,print-all|pa
             Print previous result (*1) without abbreviation.
 ,print-mode|pm
             View/set print-mode of REPL.
 ,pwd        Print working directory.
 ,reload|r   Reload the specified module, using gauche.reload.
 ,sh         Run command via shell.
 ,source     Show source code of the procedure if it's available.
 ,use|u      Use the specified module.  Same as (use module option ...).
@end example

@c EN
To see the help of each individual commands, give the command name
(without comma) to the @code{help} command:
@c JP
それぞれのコマンド特有のヘルプを見るには、コンマを含まないコマンド名を
@code{help}コマンドに与えてください。
@c COMMON

@example
gosh> ,help d
Usage: d|describe [object]
Describe the object.
Without arguments, describe the last REPL result.
@end example

@c EN
The @code{,d} (or @code{,describe}) top-level command describes
the given Scheme object
or the last result if no object is given.  Let's try some:
@c JP
@code{,d} (あるいは@code{,describe})トップレベルコマンドは与えられたSchemeオブジェクト、
または何もオブジェクトが与えられなければ直前の結果のオブジェクトについて、
その説明を表示します。ちょっと試してみましょう。
@c COMMON

@example
gosh> (sys-stat "/home")
#<<sys-stat> 0x2d6adc0>
gosh> ,d
#<<sys-stat> 0x2d6adc0> is an instance of class <sys-stat>
slots:
  type      : directory
  perm      : 493
  mode      : 16877
  ino       : 2
  dev       : 2081
  rdev      : 0
  nlink     : 9
  uid       : 0
  gid       : 0
  size      : 208
  atime     : 1459468837
  mtime     : 1401239524
  ctime     : 1401239524
@end example

@c EN
In the above example, first we evaluated @code{(sys-stat "/home")},
which returns @code{<sys-stat>} object.  The subsequent @code{,d} top-level
command describes the returned @code{<sys-stat>} object.
@c JP
上の例では、まず@code{(sys-stat "/home")}を評価して、結果として
@code{<sys-stat>}オブジェクトが返ってきました。続く@code{,d}コマンドによって
その@code{<sys-stat>}オブジェクトの詳細が表示されています。
@c COMMON

@c EN
The description depends on the type of objects.  Some types of
objects shows extra information.  If you describe an exact integer,
it shows alternative interpretations of the number:
@c JP
表示される情報はオブジェクトの型に依存します。型によっては、追加の情報が
表示される場合もあります。例えば正確な整数を@code{describe}すると、
いくつかの異なる解釈が示されます。
@c COMMON

@example
gosh> ,d 1401239524
1401239524 is an instance of class <integer>
  (#x538537e4, ~ 1.3Gi, 2014-05-28T01:12:04Z as unix-time)
gosh> ,d 48
48 is an instance of class <integer>
  (#x30, #\0 as char, 1970-01-01T00:00:48Z as unix-time)
@end example

@c EN
If you describe a symbol, its known bindings is shown.
@c JP
シンボルを@code{describe}すると、分かっている束縛が示されます。
@c COMMON

@example
gosh> ,d 'filter
filter is an instance of class <symbol>
Known bindings for variable filter:
  In module `gauche':
    #<closure (filter pred lis)>
  In module `gauche.collection':
    #<generic filter (2)>
@end example

@c EN
If you describe a procedure, and its source code location is known,
that is also shown (see the @code{Defined at...} line):
@c JP
手続きを@code{describe}した場合、もし分かっていればそのソースコード上の
場所も表示されます(@code{Defined at ...}の行):
@c COMMON

@example
gosh> ,d string-interpolate
#<closure (string-interpolate str :optional (legacy? #f))> is an
instance of class <procedure>
Defined at "../lib/gauche/interpolate.scm":64
slots:
  required  : 1
  optional  : #t
  optcount  : 1
  locked    : #f
  currying  : #f
  constant  : #f
  info      : (string-interpolate str :optional (legacy? #f))
  setter    : #f
@end example

@c EN
Let's see a couple of other top-level commands.  The @code{,info}
command shows the manual entry of the given procedure, variable, syntax,
module or a class.  (The text is searched from the installed
info document of Gauche.  If you get an error, check if the
info document is properly installed.)
@c JP
他のトップレベルコマンドも見てみましょう。@code{,info}コマンドは
手続き、変数、構文、モジュールもしくはクラス名が与えられると、そのドキュメントを
表示します。(テキストはシステムにインストールされたGaucheのinfoドキュメントから
検索されます。もしエラーが出た場合は、infoドキュメントが正しくインストール
されているかどうか確認してください。)
@c COMMON

@example
gosh> ,info append
 -- Function: append list ...
     [R7RS base] Returns a list consisting of the elements of the first
     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.

gosh> ,info srfi.19
 -- Module: srfi.19
     This SRFI defines various representations of time and date, and
     conversion methods among them.

     On Gauche, time object is supported natively by '<time>' class
     (*note Time::).  Date object is supported by '<date>' class
     described below.

gosh> ,info <list>
 -- Builtin Class: <list>
     An abstract class represents lists.  A parent class of '<null>' and
     '<pair>'.  Inherits '<sequence>'.

     Note that a circular list is also an instance of the '<list>'
     class, while 'list?' returns false on the circular lists and dotted
     lists.
          (use srfi.1)
          (list? (circular-list 1 2)) => #f
          (is-a? (circular-list 1 2) <list>) => #t
@end example

@c EN
You can also give a regexp pattern to @code{,info} command
(@pxref{Regular expressions}).
It shows the entries in the document that match the pattern.
@c JP
また、@code{,info}コマンドに正規表現のパターンを与えることもできます
(@ref{Regular expressions}参照)。
その場合、パターンにマッチするドキュメントの項目の一覧が表示されます。
@c COMMON

@example
gosh> ,info #/^string-.*\?/
string-ci<=?             Full string case conversion:44
                         String comparison:19
string-ci<?              Full string case conversion:43
                         String comparison:18
string-ci=?              Full string case conversion:42
                         String comparison:17
string-ci>=?             Full string case conversion:46
                         String comparison:21
string-ci>?              Full string case conversion:45
                         String comparison:20
string-immutable?        String Predicates:9
string-incomplete?       String Predicates:12
string-null?             SRFI-13 String predicates:6
string-prefix-ci?        SRFI-13 String prefixes & suffixes:28
string-prefix?           SRFI-13 String prefixes & suffixes:26
string-suffix-ci?        SRFI-13 String prefixes & suffixes:29
string-suffix?           SRFI-13 String prefixes & suffixes:27
@end example

@c EN
The @code{,a} command (or @code{,apropos}) shows the global identifiers
matches the given name or regexp:
@c JP
@code{,a} (または@code{,apropos}) は、与えられた名前や正規表現に
マッチするグローバルな識別子を表示します。
@c COMMON

@example
gosh> ,a filter
filter                         (gauche)
filter!                        (gauche)
filter$                        (gauche)
filter-map                     (gauche)
@end example

@c EN
Note: The @code{apropos} command looks for symbols from the
current process---that is, it only shows names that have been loaded
and imported.
But it also mean it can show any name as far as it exists in the
current process, regardless of whether it's a documented API or an
internal entry.

On the other hand, the @code{info}
command searches info document, regardless of the named entity
has loaded into the current process or not.  It doesn't show
undocumented APIs.

You can think that @code{apropos} is an introspection tool,
while @code{info} is a document browsing tool.
@c JP
註: @code{apropos}コマンドは現在のプロセス中から名前を探します。
つまり、既にロードされインポートされた名前しか表示しません。
それは同時に、ロードされてさえいれば、ドキュメントのある公式なAPIか
内部的な非公式なエントリかにかかわらず表示されるということでもあります。

一方、@code{info}コマンドは現在のプロセスにロードされているかどうか
とは関係なく、infoドキュメントから検索します。ドキュメントされていない
APIにはヒットしません。

@code{apropos}はイントロスペクションのツール、
@code{info}はドキュメント参照のツールと考えると良いでしょう。
@c COMMON

@c EN
When the result of evaluation is a huge nested structure,
it may take too long to display the result.  Gauche actually set
a limit of length and depth in displaying structures, so you might
occasionally see the very long or deep list is trucated, with
@dots{} to show there are more items, or @code{#} to show a subtree
is omitted
(Try evaluating @code{(make-list 100)} on REPL).
@c JP
評価結果が巨大な構造になる場合、それを表示するのに時間がかかりすぎる問題があります。
Gaucheはデフォルトで、表示する構造の長さと深さに制限を設けているので、
非常に長い、あるいは深い構造を表示しようとした場合に、@dots{}によって後の方が
省略されたり、@code{#}によって深い構造が省略されたりします
(REPLで@code{(make-list 100)}を評価してみてください。)
@c COMMON

@c EN
You can type @code{,pa} (or @code{,print-all}) toplevel REPL command
to fully redisplay the previous result without omission.
@c JP
直前の結果を省略無しで再表示するには @code{,pa} (もしくは@code{,print-all})
トップレベルREPLコマンドをタイプしてください。
@c COMMON

@c EN
By default, REPL prints out the result using @emph{pretty print}:
@c JP
デフォルトでは、REPLはネストした構造を@emph{プリティプリント}します:
@c COMMON

@example
gosh> ,u sxml.ssax
gosh> (call-with-input-file "src/Info.plist" (cut ssax:xml->sxml <> '()))
(*TOP*
 (*PI* xml "version=\"1.0\" encoding=\"UTF-8\"")
 (plist
  (|@@| (version "1.0"))
  (dict (key "CFBundleDevelopmentRegion") (string "English")
   (key "CFBundleExecutable") (string "Gauche") (key "CFBundleIconFile")
   (string) (key "CFBundleIdentifier") (string "com.schemearts.gauche")
   (key "CFBundleInfoDictionaryVersion") (string "6.0")
   (key "CFBundlePackageType") (string "FMWK") (key "CFBundleSignature")
   (string "????") (key "CFBundleVersion") (string "1.0")
   (key "NSPrincipalClass") (string))))
@end example

@c EN
If you want to turn off pretty printing for some reason,
type @code{,pm pretty #f} (or @code{,print-mode pretty #f}) on the
toplevel prompt, or start @code{gosh} with the environment variable
@code{GAUCHE_REPL_NO_PPRINT} set.
@c JP
何らかの理由でプリティプリントをoffにしたい場合は、
トップレベルプロンプトで@code{,pm pretty #f}
(あるいは@code{,print-mode pretty #f})と打つか、
環境変数@code{GAUCHE_REPL_NO_PPRINT}をセットして@code{gosh}を起動してください。
@c COMMON

@c EN
Type @code{,pm default} to make print mode back to default.
For more details, type @code{,help pm}.
@c JP
プリントモードをデフォルトに戻すには@code{,pm default}とタイプします。
より詳しくは@code{,help pm}を見てください。
@c COMMON

@c EN
Note: If you invoke @code{gosh} with @code{-q} option, which tells
@code{gosh} not to load the initialization files, you still get
a REPL prompt but no fancy features such as history variables
are available.  Those convenience features are implemented in
@code{gauche.interactive} module, which isn't loaded with @code{-q}
option.
@c JP
註: @code{gosh}を@code{-q}オプション (初期化ファイルをロードしない) で
起動した場合もREPLに入りますが、そこではヒストリ変数などは使えません。
REPLの便利機能は@code{gauche.interactive}モジュールで実装されていますが、
@code{-q}オプションをつけると@code{gauche.interactive}がロードされないからです。
@c COMMON

@node Input editing,  , Working in REPL, Interactive development
@subsection Input editing
@c NODE 入力の編集

@c EN
When you run @code{gosh} in a terminal capable of cursor control,
you can edit input expressions.
If input editing mode is on, the REPL prompt ends with @code{$}, such
as @code{gosh$}, instead of @code{gosh>}.
@c JP
@code{gosh}がカーソル制御可能な端末で起動された場合、入力編集が可能です。
入力編集モードが有効であれば、REPLのプロンプトが@code{$}で終わります。
例えばデフォルトでは@code{gosh>}のかわりに@code{gosh$}になります。
@c COMMON

@c EN
(NB: Currently Gauche only supports terminals with vt100-like escape
sequence, or Windows console.  If the terminal type isn't recognized
as one of them,
it falls back to non-editing mode.  You can tell which mode it is
from the prompt.)
@c JP
(註: 今のところ、Gaucheはvt100系のエスケープシーケンスを認識する端末か、
Windows consoleのみをサポートします。端末タイプがそれらでなかった場合は、
入力編集の無いモードになります。プロンプトでどちらのモードにいるかわかります。)
@c COMMON

@c EN
The input editing feature is still under development.  If you stumbled
with a serious bug, you can turn it off by setting an environment
variable @code{GAUCHE_NO_READ_EDIT}, or giving @code{-fno-read-edit} option
to @code{gosh}, or type @code{,edit off} on REPL.
@c JP
入力編集機能はまだ開発途上です。もし重大なバグに当たって編集機能をオフにしたければ、
環境変数@code{GAUCHE_NO_READ_EDIT}を設定するか、
@code{gosh}を @code{-fno-read-edit} オプションつきで起動するか、
REPLで @code{,edit off} とタイプしてください。
@c COMMON

@c EN
The key binding is similar to Emacs.  Eventually we'll provide customization
feature.  Before going into details, here's a few quick useful tips.
@c JP
キーバインディングはEmacsと似ています。いずれカスタマイズする機能も提供する予定です。
詳細に立ち入る前に、知っておくと良いヒントをいくつか。
@c COMMON

@itemize @bullet
@item
@c EN
If the screen is garbled somehow, type @code{C-l} (control+l) to clear and
redisplay.
@c JP
スクリーンがぐちゃぐちゃになってしまったら、@code{C-l} (control+l) で
スクリーンがクリアされ、入力中の式が再表示されます。
@c COMMON
@item
@c EN
If you want to turn off editing during REPL session, use @code{,edit off}
toplevel command.
@c JP
REPLセッション中に入力編集モードを切りたくなったら、トップレベルコマンド
@code{,edit off} が使えます。
@c COMMON
@item
@c EN
The input editor only sends a complete S-expression to the evaluator.  If
somehow you want to send the current input as-is (or, in case the editor
has a bug and don't allow you to send a complete S-expression), type
@code{C-M-x} (control-meta-x) to force sending the current input to the
evaluator.
@c JP
入力編集は、完全なS式が入力されて初めてそれを評価器に送ります。
現在の入力をそのままとにかく送りたい場合 (あるいは、入力編集機能のバグで
S式が完結しているのに送ってくれない場合) は、@code{C-M-x} (control-meta-x) を
タイプすると強制的に現在の編集内容が評価器に送られます。
@c COMMON
@item
@c EN
You can type @code{M-h h} to see a brief summary of editor features,
@code{M-h b} to see the list of keymap, or
@code{M-h k} + keystroke to see the help of the key.
(@code{C-h} is the same as backspace).
@c JP
@code{M-h h}で簡単な編集機能のサマリを、
@code{M-h b}でキーマップのリストを、
そして@code{M-h k}に続いてキーを打つことでそのキーの機能のヘルプを見ることができます。
(ヘルプが@code{C-h}でないのは、backspaceと同じキーコードだからです。)
@c COMMON
@item
@c EN
If you suspend @code{gosh}, then resume it by shell's job control feature
(e.g. @code{C-z}, then @code{fg}).
type ENTER to regain editing screen.
@c JP
もしシェルのジョブコントロール機能で@code{gosh}を一回止めてからまた再開した場合
(@code{C-z}で止めて@code{fg}で再開するなど)、ENTERをタイプすることで
編集画面がリストアされます。
@c COMMON
@end itemize

@c EN
@subsubheading Cursor movement
@c JP
@subsubheading カーソル移動
@c COMMON

@c EN
@code{C-f} (forward) and @code{C-b} (backward) moves the cursor forward
and backward character-wise.  @code{C-p} (previous) and @code{C-n} (next)
moves character to previous or next line, if the input already has
multiple lines, or moves to previous or next history.
@c JP
@code{C-f} (forward) と @code{C-b} (backward) はカーソルを一文字前あるいは
一文字後に移動します。@code{C-p} (previous) と @code{C-n} (next) は
カーソルを一行前あるいは一行後に移動します。移動方向に行が無ければ、
入力バッファが一つ前または一つ後のヒストリに置き換わります。
@c COMMON

@c EN
@code{M-f} and @code{M-b} move the cursor forward and backward, word-wise.
@c JP
@code{M-f}と@code{M-b}は単語単位でカーソルを前後に移動します。
@c COMMON

@c EN
@code{C-a} and @code{C-e} to move to the beginning and end of the line,
@code{M-<} and @code{M->} to move to the beginning and end of of the input.
@c JP
@code{C-a}と@code{C-e}は行の先頭または末尾に、
@code{M-<}と@code{M->}は入力バッファの最初または最後にカーソルを移動します。
@c COMMON

@subsubheading Undo

@c EN
@code{C-_} is undo the edit.  You can keep typing @code{C-_} to
undo the edits you've made.
We follow the Emacs model of undo
semantics, which allows ``undoing undoes''.
For the detailed algorithm, see the comment at the bottom of
@file{lib/text/line-edit.scm}
in the source tree.
@c JP
直前の変更をundoするには@code{C-_}を使います。@code{C-_}を続けてタイプすれば
どんどん編集をundoできます。undoのモデルはEmacsと同じで、つまり
[undo自体をundoする]こともできます。
詳しいアルゴリズムは、ソースの@file{lib/text/line-edit.scm}末尾の
コメントを見てください。
@c COMMON

@c EN
@subsubheading Kill and yank
@c JP
@subsubheading killとyank
@c COMMON

@c EN
@code{C-k} removes characters from the cursor to the end of line.
If the cursor is at the end of the line though, it removes the newline
character (so that next line is combined to the current line).
@c JP
@code{C-k}はカーソルから行末までの文字を取り除きます。もしカーソルが既に
行末にあったら、改行文字そのものを取り除きます(つまり、次の行が現在の行の後に
接続されます)。
@c COMMON

@c EN
@code{M-d} removes a word that contains the cursor, or a word
immediately after the cursor if it is not on a word.
@c JP
@code{M-d}はカーソルが単語の中にあればその単語を、そうでなければ直後の単語を
取り除きます。
@c COMMON

@c EN
@code{C-@@} set a mark to the current cursor position.  @code{C-w} removes
chracters between the cursor and the mark.
@c JP
@code{C-@@}はカーソル位置をマークします。その後、@code{C-w}で
その時点のカーソルとマークの間の文字を取り除けます。
@c COMMON

@c EN
The characters removed by those commands are saved
in the buffer called ``kill-ring''.
They can be recalled at the cursor position by @code{C-y} (yank).
If you press @code{M-y} immediately followed by @code{C-y}, you can
go back to the older killed characters.
@c JP
これらのコマンドで取り除かれた文字は、``kill-ring'' と呼ばれるバッファに
セーブされていて、@code{C-y}をタイプするとカーソル位置に復元することができます。
@code{C-y}の後に続けて@code{M-y}をタイプしてゆくと、``kill-ring''にセーブされた
さらに古い内容へと遡って復元することができます。
@c COMMON

@c EN
@subsubheading Interpolation
@c JP
@subsubheading 補完
@c COMMON

@c EN
Typing TAB in or immediately after a partially typed word completes it.
If there are multiple candidates, it completes up to the commom prefix,
and typing TAB again shows the list of candidates.

What's to be completed depends on the context.  If it is at the toplevel
command (a word after a comma on a prompt),
it complets toplevel commands.  If it is argument
of @code{,load} toplevel command, it completes pathnames.
If it is argument of @code{,use} or @code{,reload} toplevel commands,
it completes module names.  In other contexts, it completes global bindings
visible from the current module.

For symbols and module names, segmented completion is possible; e.g.
@code{c-w-c-c} completes to @code{call-with-current-continuation}.

Currently the completion mechanism is hardcoded.  We may add a way to
customize it in future.
@c JP
部分的にタイプされた単語の中、もしくは直後にTABを打つと単語が補完されます。
複数の候補がある場合、共通するプレフィクスが補完され、そこで続けてTABを打つと候補がリストされます。

何が補完されるかは文脈によります。トップレベルコマンド
(プロンプトにおいてコンマの後に続く単語)の場合はトップレベルコマンドが、
@code{,load}トップレベルコマンドの引数であればパス名が、
@code{,use}や@code{,reload}トップレベルコマンドの引数であればモジュール名が、
そしてその他の文脈では現在のモジュールから見えるグローバル束縛があるシンボルです。

シンボルとモジュール名については、区切られた単語による補完が可能です。
例えば@code{c-w-c-c}は@code{call-with-current-continuation}に補完されます。

今のところ、補完メカニズムはハードコードされています。いずれカスタマイズできるように
するかもしれません。
@c COMMON

@c EN
@subsubheading Finishing input
@c JP
@subsubheading 入力の終了
@c COMMON

@c EN
@code{RET} (or @code{C-m}) inserts a newline if the input isn't
a complete S-expresson.  If the input is already a complete S-expression,
however, it sends the entire input to the evaluator, no matter where
the cursor is.  If you want to insert a newline in a complete S-expression,
you can use @code{C-j}.
@c JP
入力のS式がまだ完結していなければ、@code{RET} (@code{C-m}) は入力に改行文字を
挿入します。もしS式が完結していれば、カーソルがどこにあっても@code{RET} (@code{C-m})は
入力を評価機に送ります。もし完結したS式の途中に改行を追加したい場合は
@code{C-j}をタイプしてください。
@c COMMON

@c EN
@code{M-C-x} sends the current input regardless that the input is
a complete S-expression or not.
@c JP
S式が完結しているかどうかにかかわらず入力を評価したい場合は、
@code{M-C-x}をタイプしてください。
@c COMMON

@c EN
@subsubheading History
@c JP
@subsubheading ヒストリ
@c COMMON

@c EN
Input history is remembered and recalled by @code{M-p} (prev-history)
and @code{M-n} (next-history).
The cursor movement command @code{C-p} and @code{C-n} also moves to
the previous or next history if it is pressed when the cursor is
at the beginning or the end of the input lines.
@c JP
入力のヒストリは保存されていて、@code{M-p} (prev-history)と
@code{M-n} (next-history)で呼び出すことができます。
カーソル上下移動の@code{C-p}と@code{C-n}も、現在の入力バッファを越えて移動しようとすると
前または後のヒストリを呼び出します。
@c COMMON

@c EN
The input interrupted by @code{C-c} isn't remembered.
@c JP
@code{C-c}で中断された入力はヒストリに保存されません。
@c COMMON

@c EN
By default, the input is saved to a file @file{~/.gosh_history} when the
REPL is terminated normally, and reloaded when the next REPL is invoked.
The name of the history file can be changed by the environment variable
@code{GAUCHE_HISTORY_FILE}.  If the environment variable is defined to an
empty string, however, the history won't be saved.
@c JP
デフォルトでは、入力ヒストリはREPLが正常終了する際に@file{~/.gosh_history}され、
次にREPLが起動する際に読み込まれます。
ヒストリを保存するファイル名は環境変数@code{GAUCHE_HISTORY_FILE}で変更できます。
また、この環境変数が空文字列にセットされていれば、ヒストリは保存されません。
@c COMMON

@c EN
@subsubheading Miscellaneous
@c JP
@subsubheading その他
@c COMMON

@c EN
@code{C-g} cancels the current multi-key sequences.
@c JP
@code{C-g}は複数キーシーケンスをキャンセルします。
@c COMMON

@c EN
@code{C-c} cancels the current input.
@c JP
@code{C-c}は現在の入力をキャンセルします。
@c COMMON

@c EN
@code{C-t} transpose characters at and before the cursor.
@c JP
@code{C-t}はカーソルとその前の文字を入れ替えます。
@c COMMON

@c EN
@code{C-q} reads the next keystroke and insert it into the input as is.
@c JP
@code{C-q}は次のキーストロークを読み取ってそれを入力にそのまま挿入します。
@c COMMON

@c EN
@code{M-(} inserts a pair of parentheses, and locate a cursor inside them.
@c JP
@code{M-(}は対になった括弧を挿入し、カーソルを括弧の間に置きます。
@c COMMON

@c EN
@code{C-l} clears the screen and redraws the current input buffer.
@c JP
@code{C-l}は画面をクリアし、入力バッファを再表示します。
@c COMMON

@c ----------------------------------------------------------------------
@node Writing Scheme scripts, Debugging, Interactive development, Programming in Gauche
@section Writing Scheme scripts
@c NODE Schemeスクリプトを書く

@c EN
When a Scheme program file is given to @code{gosh}, it
makes the @code{user} module as the current module,
binds a global variable @code{*argv*} to the list of the remaining
command-line arguments, and then loads the Scheme program.
If the first line of @var{scheme-file} begins with two character
sequence ``@code{#!}'', the entire line is ignored by @code{gosh}.
This is useful to write a Scheme program that works as an executable
script in unix-like systems.
@c JP
@code{gosh}のコマンドラインにSchemeプログラムのファイル名が渡された場合、
@code{gosh}は@code{user}モジュールをカレントモジュールとし、
それ以降のコマンドライン引数のリストをグローバル変数@code{*argv*}に束縛して、
Schemeプログラムをロードします。もし@var{scheme-file}の最初の行が``@code{#!}''で始まって
いたら、その行は無視されます。これにより、Unix系のシステムで実行可能なSchemeスクリプト
を書くことが出来ます。
@c COMMON

@c EN
Typical Gauche script has the first
line like these

@example
#!/usr/local/bin/gosh
  @r{or,}
#!/usr/bin/env gosh
  @r{or,}
#!/bin/sh
#|
exec gosh -- $0 "$@@"
|#
@end example

The second and third form uses a ``shell trampoline'' technique
so that the script works as far as @code{gosh} is in the PATH.
The third form is useful when you want to pass extra arguments
to @code{gosh}, for typically @code{#!}-magic of executable scripts
has limitations for the number of arguments to pass the interpreter.
@c JP
典型的なGaucheスクリプトの最初の行は次のようなものです。

@example
#!/usr/local/bin/gosh
  @r{または,}
#!/usr/bin/env gosh
  @r{または,}
#!/bin/sh
#|
exec gosh -- $0 "$@@"
|#
@end example

後の2つは「シェルトランポリン」テクニックを用いて、@code{gosh}がPATHにあるディレクトリの
どこかにあれば起動できるようにしています。3番目の方法は、
@code{gosh}にいくつかコマンドラインオプションを渡したい時に便利です。
@c COMMON

@c EN
After the file is successfully loaded, @code{gosh} calls a
procedure named `@code{main}' if it is defined in the user module.
@code{Main} receives a single argument, a list of command line
arguments.  Its first element is the script name itself.

When @code{main} returns, and its value is an integer, @code{gosh}
uses it for exit code of the program.
Otherwise, @code{gosh} exits with exit code 70 (@code{EX_SOFTWARE}).
This behavior is compatible with the SRFI-22.

If the @code{main} procedure is not defined, @code{gosh} exits
after loading the script file.
@c JP
ファイルが正常にロードされたら、@code{gosh}は
userモジュールに `@code{main}' という手続きが定義されているかどうか調べ、
定義されていればそれを呼びます。@code{main}には、スクリプトへの引数のリストが
唯一の引数として渡されます。リストの最初の要素はスクリプトファイル名です。

@code{main}が整数の値を返したら、@code{gosh}はその値を終了ステータスとして終了します。
@code{main}が整数以外の値を返した場合は@code{gosh}は終了ステータス70
(@code{EX_SOFTWARE})で終了します。このふるまいはSRFI-22と互換です。

@code{main}が定義されていなければ@code{gosh}はロード後にそのままステータス0で
終了します。
@c COMMON

@c EN
Although you can still write the program
main body as toplevel expressions, like shell scripts or Perl scripts,
it is much convenient to use this `@code{main}' convention, for
you can load the script file interactively to debug.
@c JP
シェルスクリプトやPerlスクリプトと同じように、スクリプトのボディに直接
実行される式を書くこともできますが、なるべく `@code{main}' を使った方法を
使うことをお薦めします。そうすると、スクリプトをインタプリタにインタラクティブに
ロードしてデバッグすることもできます。
@c COMMON

@c EN
Using @code{-m} command-line option, you can make @code{gosh} call
@code{main} procedure defined in a module other than the @code{user}
module.  It is sometimes handy to write a Scheme module that can
also be executed as a script.

For example, you write a Scheme module @code{foo}
and @emph{within it}, you define the @code{main} procedure.
You don't need to export it.  If the file is loaded as a module,
the @code{main} procedure doesn't do anything.  But if you
specify @code{-m foo} option and give the file as a Scheme script
to @code{gosh}, then
the @code{main} procedure is invoked after loading the script.
You can code tests or small example application in such an
alternate main procedure.
@c JP
@code{-m}コマンドラインオプションを使えば、@code{user}モジュール以外の
モジュールで定義された@code{main}手続きをスクリプトのメイン関数として
呼ぶことができます。Schemeモジュールを、Schemeスクリプトとしても使えるように
したい場合に便利です。

例えば、@code{foo}というSchemeモジュールを書いて、@emph{その中で}
@code{main}関数を定義しておきます。この@code{main}関数はexportしないでおきます。
このファイルがモジュールとしてロードされた場合、この@code{main}関数は
外からは見えないので何もしません。しかし、@code{gosh}に@code{-m foo}オプションを
与えて、このファイルをスクリプトファイルとして指定すれば、ファイルをロードした後に
@code{main}手続きが呼ばれます。その中には、
テストだとかモジュールのサンプルアプリケーションを書いておくことができるでしょう。
@c COMMON

@c EN
@emph{Note on R7RS Scripts}: If the script is written in R7RS Scheme
(which can be distinguished by the first @code{import} declaration,
@pxref{Three forms of import}), it is read into @code{r7rs.user}
module and its @code{main} isn't called.
You can give @code{-mr7rs.main} command-line argument to call
the @code{main} function in R7RS script.
Alternatively, as specified in SRFI-22, if the script interpreter's
basename is @file{scheme-r7rs}, we assume the script is R7RS SRFI-22 script
and calls @code{main} in @code{r7rs.user} module rather than @code{user}
module.  We don't install such an alias, but you can manually
make symbolic link or just copy @file{gosh} binary as @file{scheme-r7rs}.
@c JP
@emph{R7RSスクリプトに関する註}: スクリプトがR7RS Schemeで書かれている場合
(先頭にR7RSの@code{import}があることで区別されます。
詳しくは@ref{Three forms of import}参照)、
スクリプト本体は@code{r7rs.user}へと読み込まれるため、
@code{main}は自動的には呼ばれません。
コマンドライン引数@code{-mr7rs.main}を指定することで、
R7RSスクリプトの@code{main}を実行できます。
別の方法として、SRFI-22に指定されているように、
スクリプトインタプリタのbasenameが@file{scheme-r7rs}であった場合、
スクリプトはR7RSで書かれたSRFI-22形式であると見なされ、
@code{user}モジュールのかわりに@code{r7rs.user}モジュールの@code{main}が呼ばれます。
そのような別名は自動的にはインストールされませんが、
@file{gosh}に@file{scheme-r7rs}という名前でシンボリックリンクを張るか、
コピーすることができるでしょう。
@c COMMON

@c EN
Although the argument of the @code{main} procedure is the standard way
to receive the command-line arguments, there are a couple of other
ways to access to the info.  @xref{Command-line arguments}, for the
details.
@c JP
コマンドライン引数を受け取る標準的な方法は、@code{main}関数の引数としてですが、
他にもコマンドライン引数にアクセスする方法が提供されています。詳しくは
@ref{Command-line arguments}を参照してください。
@c COMMON

@c EN
Now I show several simple examples below.
First, this script works like @code{cat(1)}, without any command-line
option processing and error handling.
@c JP
ではいくつか簡単な例を示しましょう。最初の例はUnixの@code{cat(1)}コマンドを模するものです。
エラー処理やコマンドラインオプションの処理は行っていません。
@c COMMON

@example
#!/usr/bin/env gosh

(define (main args)   ;@r{entry point}
  (if (null? (cdr args))
      (copy-port (current-input-port) (current-output-port))
      (for-each (lambda (file)
                  (call-with-input-file file
                    (lambda (in)
                      (copy-port in (current-output-port)))))
                (cdr args)))
  0)
@end example

@c EN
The following script is a simple grep command.
@c JP
次のスクリプトは簡単なgrepコマンドです。
@c COMMON

@example
#!/usr/bin/env gosh

(define (usage program-name)
  (format (current-error-port)
          "Usage: ~a regexp file ...\n" program-name)
  (exit 2))

(define (grep rx port)
  (with-input-from-port port
    (lambda ()
      (port-for-each
       (lambda (line)
         (when (rxmatch rx line)
           (format #t "~a:~a: ~a\n"
                   (port-name port)
                   (- (port-current-line port) 1)
                   line)))
       read-line))))

(define (main args)
  (if (null? (cdr args))
      (usage (car args))
      (let ((rx (string->regexp (cadr args))))
        (if (null? (cddr args))
            (grep rx (current-input-port))
            (for-each (lambda (f)
                        (call-with-input-file f
                          (lambda (p) (grep rx p))))
                      (cddr args)))))
  0)
@end example

@c EN
See also @ref{Parsing command-line options}, for a convenient way to
parse command-line options.
@c JP
また、@ref{Parsing command-line options}を使うと手軽にコマンドラインオプション
を処理することができます。
@c COMMON

@c ----------------------------------------------------------------------
@node Debugging, Platform-dependent features, Writing Scheme scripts, Programming in Gauche
@section Debugging
@c NODE デバッグ

@c EN
Gauche doesn't have much support for debugging yet.
The idea of good debugging interfaces are welcome.
@c JP
Gaucheにはまだデバッグをサポートする機能があまり実装されていません。
デバッギングのインタフェースに関して良いアイディアがあればお寄せください。
@c COMMON

@c EN
For now, the author uses the classic 'debug print stub' technique
when necessary.  Gauche's reader supports special syntaxes
beginning with @code{#?}, to print the intermediate value.
@c JP
今のところ、作者は必要な時は古典的な「プリントスタブ」方式を使っています。
Gaucheのリーダには、中間の結果を出力するために、
@code{#?}で始まるいくつかの構文が用意されています。
@c COMMON

@c EN
The syntax @code{#?=@var{expr}} shows @var{expr} itself before
evaluating it, and prints its result(s) after evaluation.
@c JP
構文@code{#?=@var{expr}}は、@var{expr}を評価する前にまずその式自体を
表示し、評価後にその結果(複数の場合もあります)を表示します。
@c COMMON

@example
gosh> #?=(+ 2 3)
#?="(stdin)":1:(+ 2 3)
#?-    5
5
gosh> #?=(begin (print "foo") (values 'a 'b 'c))
#?="(stdin)":2:(begin (print "foo") (values 'a 'b 'c))
foo
#?-    a
#?+    b
#?+    c
a
b
c
@end example

@c EN
Note: If the debug stub is evaluated in a thread other than
the primordial thread (@pxref{Threads}), the output
includes a number to distinguish which thread it is generated.
In the following example, @code{#<thread ...>} and the prompt
is the output of REPL in the primordial thread,
but following @code{#?=[1]...} and @code{#?-[1]...} are
the debug output from the thread created by @code{make-thread}.
The number is for debugging only---
they differ for each thread, but other than that there's no meaning.
@c JP
註: デバッグスタブが原始スレッド(@ref{Threads}参照)以外のスレッドで評価された場合、
スタブの出力には、どのスレッドから出力されたかを示す番号がつけられます。
次の例では、@code{#<thread ...>}およびプロンプトが原始スレッドのREPLの
出力ですが、続く@code{#?=[1]...}と@code{#?-[1]...}は
@code{make-thread}により作られたスレッドからのデバッグ出力です。
この番号はデバッグ時にスレッドを区別するためだけのもので、スレッド毎に異なりますが、
それ以外の意味はありません。
@c COMMON

@example
gosh> (use gauche.threads)
gosh> (thread-start! (make-thread (^[] #?=(+ 2 3))))
#<thread #f (1) runnable 0xf51400>
gosh> #?=[1]"(standard input)":1:(+ 2 3)
#?-[1]    5
@end example

@c EN
The syntax @code{#?,(@var{proc} @var{arg} @dots{})} is specifically
for procedure call; it prints the value of arguments right before
calling @var{proc}, and prints the result(s) of call afterwards.
@c JP
構文@code{#?,(@var{proc} @var{arg} @dots{})}は特に手続き呼び出しのための
ものです。@var{proc}を呼ぶ直前に引数の値を表示し、@var{proc}から返ってきたら
戻り値(複数の場合もあります)を表示します。
@c COMMON

@example
gosh> (define (fact n)
        (if (zero? n)
            1
            (* n #?,(fact (- n 1)))))
fact
#?,"(standard input)":4:calling `fact' with args:
#?,> 4
#?,"(standard input)":4:calling `fact' with args:
#?,> 3
#?,"(standard input)":4:calling `fact' with args:
#?,> 2
#?,"(standard input)":4:calling `fact' with args:
#?,> 1
#?,"(standard input)":4:calling `fact' with args:
#?,> 0
#?-    1
#?-    1
#?-    2
#?-    6
#?-    24
120
@end example

@c EN
Internally, the syntax @code{#?=@var{x}} and @code{#?,@var{x}} are read
as @code{(debug-print @var{x})} and @code{(debuf-funcall @var{x})},
respectively, and the macros @code{debug-print} and @code{debug-funcall}
handles the actual printing.  @xref{Debugging aid}, for more details.

The reasons of special syntax are: (1) It's easy to insert the
debug stub, for you don't need to enclose the target expression by
extra parenthesis, and
(2) It's easy to find and remove those stabs within the editor.
@c JP
内部的には、構文@code{#?=@var{x}}と@code{#?,@var{x}}はそれぞれ単に
@code{(debug-print @var{x})}および@code{(debuf-funcall @var{x})}と読まれ、
実際の表示についてはマクロ@code{debug-print}と@code{debug-funcall}が
処理します。詳しくは@ref{Debugging aid}を参照してください。

特別な構文を用意した理由は、(1)目的の式にデバッグスタブを付加するのに、
式全体を余分な括弧でくくらなくて良いのですぐできる
(2)デバッグスタブをエディタで探したり取り除いたりするのが極めて簡単、というものです。
@c COMMON

@c EN
Simple debug stubs may produce too many output, and you may
want to limit them when certain conditions are met.  A reader syntax
@code{#??=@var{test} @var{expr}} and
@code{#??,@var{test} @var{procedure-call}} works much like
@code{#??=@var{expr}} and @code{#?,@var{procedure-call}}, but
only when @var{test} yields true:
@c JP
単純なデバッグスタブではしばしば大量にデバッグ出力が出てしまうので、
特定の条件に合致した時のみ出力を見たいことがあるかもしれません。
リーダー構文@code{#??=@var{test} @var{expr}}と
@code{#??,@var{test} @var{procedure-call}}は、
@var{test}が真に評価される時だけそれぞれ
@code{#??=@var{expr}}および@code{#?,@var{procedure-call}}のように
動作します。
@c COMMON

@example
(define (fib n)
  (if (< n 2)
    1
    #??,(= n 5) (+ (fib (- n 1)) (fib (- n 2)))))

gosh> (fib 7)
#?,calling `+' with args:
#?,> 5
#?,> 3
#?-    8
#?,calling `+' with args:
#?,> 5
#?,> 3
#?-    8
21
@end example

@c EN
Internally, @code{#??=@var{test} @var{expr}} and
@code{#??,@var{test} @var{procedure-call}} are expanded to
macro calls @code{(debug-print-conditionally @var{test} @var{expr})}
and @code{(debug-funcallt-conditionally @var{test} @var{procedure-call})}.
@c JP
内部的には、@code{#??=@var{test} @var{expr}}と
@code{#??,@var{test} @var{procedure-call}}はそれぞれマクロ呼び出し
@code{(debug-print-conditionally @var{test} @var{expr})}と
@code{(debug-funcallt-conditionally @var{test} @var{procedure-call})}に
展開されます。
@c COMMON


@c ----------------------------------------------------------------------
@node Platform-dependent features, Profiling and tuning, Debugging, Programming in Gauche
@section Using platform-dependent features
@c NODE プラットフォーム依存の機能

@c EN
Gauche tries to provide low-level APIs close to what the underlying
system provides, but sometimes they vary among systems.  For example,
POSIX does not require @code{symlink}, so some systems may lack
@code{sys-symlink} (@pxref{Directory manipulation}).  Quite a few
unix-specific system functions are not available on Windows platform.
@c JP
GaucheではOSが提供するAPIに近い低レベルAPIを提供するようにしています。
しかし、システムごとに扱いの違うものがあります。たとえば、POSIXでは
@code{symlink}は必須ではありませんので、システムによっては
@code{sys-symlink} (@ref{Directory manipulation}参照)がありません。
UNIX系のシステム関数は少なからずWindowsでは使えません。

@c EN
To allow writing a portable program across those platforms, Gauche
uses @code{cond-expand} (@pxref{Feature conditional}) extensively.
A set of extended @emph{feature-identifier}s is provided to check
availability of specific features.  For example, on systems that
has @code{symlink}, a feature identifier @code{gauche.sys.symlink}
is defined.   So you can write a code that can switch based on
the availability of @code{sys-symlink} as follows:
@c JP
プラットフォーム間でポータブルなプログラムを書くために、Gaucheでは
頻繁に@code{cond-expand} を使います(@ref{Feature conditional}参照)。
拡張された@emph{機能識別子(feature-identifier)}が提供されており、これ
を使って特定の機能が利用可能かどうかチェックできます。たとえば、
@code{symlink}があるシステムでは機能識別子@code{gauche.sys.symlink}が
定義されます。したがって、以下のように@code{sys-symlink}が利用できるか
どうかによって、コードをスイッチするようなプログラムを書けます。
@c COMMON

@example
(cond-expand
 (gauche.sys.symlink
   ... code that uses sys-symlink ...)
 (else
   ... alternative code ...)
 )
@end example

@c EN
If you're familiar with system programming in C, you can think
it equivalent to the following C idiom:
@c JP
Cのシステムプログラミングに詳しいなら、上のコードは以下のCのイディオム
と同じだとみなせます。
@c COMMON

@example
#if defined(HAVE_SYMLINK)
... code that uses symlink ...
#else
... alternative code ...
#endif
@end example

@c EN
There are quite a few such feature identifiers; each identifier is
explained in the manual entry of the procedures that depend on the feature.
Here we list a few important ones:
@c JP
このような機能識別子はたくさんあり、それぞれの識別子についてはこのマニュ
アル中のその機能に依存した手続きの項目で説明しています。特に重要なもの
を以下にリストアップしておきます。
@c COMMON

@table @code
@item gauche
@c EN
This feature identifier is always defined.  It is useful when you
write Scheme code portable across multiple implementations.
@c JP
この機能識別子は常に定義されています。Gauche以外のSchemeの実装とも互換
性のあるコードを書くときに使えます。
@c COMMON
@item gauche.os.windows
@c EN
Defined on Windows native platform.  Note that cygwin does not define
this feature identifier (but see below).
@c JP
Windowsネイティブプラットフォームで定義されます。cygwinでは
この機能識別子は定義されません (下記も参照)。
@c COMMON
@item gauche.os.cygwin
@c EN
Defined on Cygwin.
@c JP
Cygwin上で定義されます。
@c COMMON
@item gauche.sys.pthreads
@itemx gauche.sys.wthreads
@c EN
Defined to indicate the underlying thread implementation.
@xref{Threads}.
@c JP
スレッドの具体的な実装を示すために定義されます。
詳細は@ref{Threads}を参照してください。
@c COMMON
@item gauche.net.ipv6
@c EN
Defined if Gauche is compiled with IPv6 support.
@c JP
GaucheがIPv6をサポートするようにコンパイルされている場合に定義されます。
@c COMMON
@end table

@c EN
Because @code{cond-expand} is a macro, the body of clauses
are expanded into toplevel if @code{cond-expand} itself is in
toplevel.  That means you can switch toplevel definitions:
@c JP
@code{cond-expand}はマクロなので、@code{cond-expand}自身がトップレベル
にあれば、節の本体はトップレベルで展開されます。これはトップレベルの定
義をスイッチできるということです。
@c COMMON

@example
(cond-expand
 (gauche.os.windows
  (define (get-current-user)
    ... get current username ...))
 (else
  (define (get-current-user)
    (sys-uid->user-name (sys-getuid)))))
@end example

@c EN
Or even conditionally "use" the modules:
@c JP
あるいは条件によってモジュールを使いわけられます。
@c COMMON

@example
(cond-expand
 (gauche.os.windows
   (use "my-windows-compatibility-module"))
 (else))
@end example

@c EN
The traditional technique of testing a toplevel binding
(using @code{module-binds?}, @pxref{Module introspection})
doesn't work well in this case, since
the @code{use} form takes effect at compile time.
It is strongly recommended to use @code{cond-expand} whenever possible.
@c JP
トップレベルの束縛をチェックするような旧いテクニック
(@code{module-binds?}を使う, @ref{Module introspection}参照)
は実行時に効果を持つので、コンパイル時に解釈される@code{use}
を切り替えるのはうまくいきません。
可能なかぎり、@code{cond-expand}を使うことを推奨します。
@c COMMON

@c EN
Currently the set of feature identifiers are fixed at the build
time of Gauche, so it's less flexible than C preprocessor conditionals.
We have a plan to extend this feature to enable adding new feature
identifiers; but such feature can complicate semantics when compilation
and execution is interleaved, so we're carefully assessing the effects now.
@c JP
現時点では機能識別子集合はGaucheのコンパイル時に固定されます。つまり、
Cのプリプロセッサを使った条件分岐よりも柔軟性に劣ります。この機能を拡
張してあとから機能識別子を追加できるようにする計画ですが、この機能拡張
はコンパイルと実行が細切れに入れ替わる場合のセマンティクスを複雑にしてしまう可
能性があり、現在その影響を慎重にみきわめている最中です。
@c COMMON

@c EN
A couple of notes:
@c JP
いくつか注意事項があります。
@c COMMON

@c EN
Feature identifiers are not variables.  They can only be used
within the @var{feature-requirement} part of @code{cond-expand}
(see @ref{Feature conditional} for the complete definition of
feature requirements).
@c JP
機能識別子は変数ではありません。@code{cond-expand}の
@var{feature-requirement}部の内部でのみ利用可能です(機能要求の定義全般
については@ref{Feature conditional}を見てください)。
@c COMMON

@c EN
By the definition of SRFI-0, @code{cond-expand} raises an error
if no feature requirements are satisfied and there's no @code{else}
clause.  A rule of thumb is to provide @code{else} clause always,
even it does nothing (like the above example that has empty @code{else}
clause).
@c JP
SRFI-0の定義により、機能要求が満されず、かつ@code{else}節がない
場合には@code{cond-expand}はエラーをあげます。常に@code{else}を書いて
おくのがよいでしょう。 上の例のように、@code{else}節でなにもしないとき
でも、空の@code{else}節を書くのがよいでしょう。
@c COMMON

@c ----------------------------------------------------------------------
@node Profiling and tuning, Auxiliary programs, Platform-dependent features, Programming in Gauche
@section Profiling and tuning
@c NODE プロファイリングとチューニング

@c EN
If you find your script isn't running fast enough,
there are several possibilities to improve its performance.
@c JP
自分のスクリプトのスピードが十分に出ないというときには、
性能を改善するポイントとして考えられる点がいくつかあります。
@c COMMON

@c EN
It is always a good idea to begin with finding which part
of the code is consuming the execution time.   Gauche has
a couple of basic tools to help it.  A built-in sampling profiler,
explained in the following subsection, can show how much time
is spent in each procedure, and how many times it is called.
The @code{gauche.time} module (@ref{Measure timings}) provides
APIs to measure execution time of specific parts of the code.
@c JP
どんなときでも、実行時間を食いつぶしているコード部分を見つけるというの
を先ず最初にやるのがよいでしょう。Gauche にはこの作業を補助する基本的
なツールが2つあります。組込のサンプリングプロファイラ(これについては次
の節で説明します)を使えば各手続きでどれほどの時間がかかり、その手続き
が何回呼ばれたかを表示できます。@code{gauche.time} モジュール
(@ref{Measure timings}) ではコードの中の特定の部分の実行にかかる時間を
測定するためのAPIが提供されています。
@c COMMON

@c EN
Optimization is specialization---you look for the most common
patterns of execution, and put a special path to support those
patterns efficiently.  Gauche itself is no exception, so there
are some patterns Gauche can handle very efficiently, while
some patterns it cannot.  The next subsection, @ref{Performance tips},
will give you some tips of how to adapt your code to fit
the patterns Gauche can execute well.
@c JP
最適化というのは特殊化ということでもあります。もっともよく使われる
実行のパターンを探して、そこを効率よく実行する専用のパスを設けることで
す。Gauche 自身も例外ではありません。したがって、Gaucheが効率よく実行
できるパターンがいくつかありますし、また一方では効率よく実行できないパ
ターンもあります。次の節では、@ref{Performance tips} では Gauche が効
率良く実行できるパターンにコードをあわせるチョットしたコツを教えましょう。
@c COMMON

@menu
* Using profiler::
* Performance tips::
@end menu

@node Using profiler, Performance tips, Profiling and tuning, Profiling and tuning
@subsection Using profiler
@c NODE プロファイラを使う

@c EN
As of 0.8.4, Gauche has a built-in profiler.  It is still experimental
quality and only be tested on Linux.  It isn't available for all
platforms.   It works only in single-thread applications for now.
@c JP
0.8.4 から Gauche は組込みのプロファイラを備えています。これは
現時点ではまだ実験的なもので、Linux 上でしかテストしていません。すべてのプ
ラットフォームで利用できるわけではありませんし、シングルスレッドの
アプリケーションでしか動きません。
@c COMMON

@c EN
To use the profiler non-interactively, give @code{-ptime}
command-line option to gosh.
@c JP
非対話環境でこのプロファイラを使うには、gosh のコマンドラインオプショ
ンとして @code{-ptime}を指定してください。
@c COMMON

@example
% gosh -ptime your-script.scm
@end example

@c EN
After the execution of @file{your-script.scm} is completed, Gauche prints
out the table of functions with its call count and its consumed time,
sorted by the total consumed time.
@c JP
@file{your-script.scm} の実行完了後、Gauche は各関数についてその呼び出し回数
および消費時間を示した表を印字します。この表は総消費時間の順でソートさ
れています。
@c COMMON

@smallexample
Profiler statistics (total 1457 samples, 14.57 seconds)
                                                    num    time/    total
Name                                                calls  call(ms) samples
---------------------------------------------------+------+-------+-----------
combinations*                                       237351  0.0142   337( 23%)
(lset-difference #f)                               1281837  0.0020   256( 17%)
(make-anchor make-anchor)                          3950793  0.0005   198( 13%)
member                                             4627246  0.0004   190( 13%)
filter                                              273238  0.0030    81(  5%)
every                                              1315131  0.0004    59(  4%)
(lset-difference #f #f)                            1281837  0.0004    54(  3%)
(make-entry make-entry)                             730916  0.0005    40(  2%)
(clear? #f)                                         730884  0.0005    33(  2%)
(initialize #f)                                     599292  0.0005    32(  2%)
fold                                                237307  0.0013    30(  2%)
acons                                               806406  0.0004    29(  1%)
clear?                                               33294  0.0084    28(  1%)
(combinations* #f)                                  805504  0.0002    15(  1%)
(make-exit make-exit)                               730884  0.0002    15(  1%)
lset-difference                                     237318  0.0006    15(  1%)
reverse!                                            475900  0.0001     6(  0%)
(fold <top> <top> <list>)                           237323  0.0003     6(  0%)
procedure?                                          238723  0.0002     4(  0%)
pair?                                               237307  0.0001     3(  0%)
 :
 :
@end smallexample

@c EN
Note that the time profiler uses statistic sampling.  Every 10ms
the profiler interrupts the process and records the function that is
executed then.   Compared to the individual execution time per
function call, which is the order of nanoseconds, this sampling rate
is very sparse.  However, if we run the program long enough,
we can expect the distribution of samples per each function
approximately reflects the distribution of time spent in each function.
@c JP
時間プロファイラは統計的標本化をおこなっていることに注意してください。
プロファイラは10ミリ秒ごとにプロセスに割込んで、その時点で実行されてい
る関数を記録します。ナノ秒オーダの関数呼出しごとの個別の実行時間に比べる
と、このサンプリングレートはかなり粗いものです。しかしながら、プロ
グラムの実行時間が長ければ、各関数ごとの標本分布は関数ごとの消費時間を
ほぼ反映しているだろうと期待できます。
@c COMMON

@c EN
Keep in mind that the number is only approximation; the number
of sample counts for a function may easily vary if the program deals
with different data sets.   It should also be noted that, for now, GC
time is included in the function in which GC is triggered.
This sometimes causes a less important function to "float up" to
near-top of the list.
To know the general pattern, it is a good custom to run the program
with several different data sets.
@c JP
数字はあくまで近似にすぎないこと
を心にとめておいてください。ひとつの関数あたりの標本数はプログラムが扱
うデータが違えば、すぐに変化してしまうことがあります。
また、今のところGCにかかる時間はGCがトリガされた関数の実行時間に
算入されてしまっていることに注意して下さい。これによって、あまり
重要でない関数がリストの上位に浮かびあがってくることがあります。
一般的なパターンを知るには、プログラムをいろいろなデータで走らせて
みると良いでしょう。
@c COMMON

@c EN
On the other hand, the call count is accurate since Gauche actually
counts each call.
@c JP
一方、関数呼び出し回数のカウントは正確なものです。これは Gauche は
実際の呼出しごとにカウントしているからです。
@c COMMON

@c EN
Because all functions are basically anonymous in Scheme, the 'name' field of
the profiler result is only a hint.  The functions bound at toplevel
is generally printed with the global variable name it is bound at
the first time.  Internal functions are printed as a list of names,
reflecting the nesting of functions.  Methods are also printed as a
list of the name and specializers.
@c JP
Schemeでは基本的にすべての関数は無名なので、プロファイル結果の'name'
フィールドはヒントにすぎません。トップレベルで束縛されている関数につい
ては通常それが最初に束縛されたグローバル変数名が印字されます。内部関数
については関数の入れ子構造を反映して名前のリストが印字されます。
メソッドは、名前と特定化子のリストとして印字されます。
@c COMMON

@c EN
The profiler has its own overhead; generally the total
process time will increase 20-30%.
If you want to turn on the profiler selectively, or you're running
a non-stop server program and want to obtain the statistics without
exiting the server, you can call the profiler API from your program;
see @ref{Profiler API}, for the details.
@c JP
プロファイラはそれ自身にオーバヘッドがあります。通常は、処理時間が
20-30% 増加します。プロファイラを選択的にオンにしたい場合や、
停止しないサーバプログラムを走らせていて、そのサーバを停止することなく、
統計を取りたいような場合には、プログラムからプロファイラ APIを呼ぶこと
ができます。詳細については @ref{Profiler API} を参照してください。
@c COMMON

@node Performance tips,  , Using profiler, Profiling and tuning
@subsection Performance tips
@c NODE パフォーマンスに関するヒント

@c EN
Don't guess, just benchmark.  It is the first rule of
performance tuning.  Especially for the higher-level languages
like Scheme, what impacts on performance greatly depends on
the implementation.  Certain operations that are very cheap
on an implementation may be costly on others.
Gauche has such implementation-specific characteristics, and
to know some of them would help to see what to look out in
the benchmark results.
@c JP
「論より run 」これがパフォーマンスチューニングの第一法則です。
Scheme のような高級言語では、何がパフォーマンスに強い影響を
与えるかはことのほかその実装に大きく依存し、ある処理系では
とても安価な操作が別の処理系ではとても高価になり得ます。
Gauche にもそのようなパフォーマンスに関する実装特有の特徴があり、
それらのうちのいくつかを知っておくことは、ベンチマークの結果の
どこに着目すべきかを知るうえで助けになるでしょう。
@c COMMON

@c EN
"80% of execution time is spent in 20% of the code" is another
old saying.  Don't obscure your code by "potential" optimization
that has little impact on the actual execution.  We describe some
tips below, but it doesn't mean you need to watch them all the time.
It is better to keep most of the code clean and easy to understand,
and only do tricks on the innermost loop.
@c JP
「ソースコードの2割が実行時間の8割を消費する」というのも古くから
言われています。実際の実行時間に大した影響を及ぼさないところを
下手にいじくってプログラムをわかりづらくすることは避けましょう。
これからいくつかのヒントを述べますが、これらのことを四六時中気にして
プログラミングしなければならないということではありません。
むしろ、出来るだけ明瞭でわかりやすいプログラムを心がけ、ループの一番深いところ
(もっとも時間を消費するところ)でこれらのトリックを使うのが良いでしょう。
@c COMMON

@c EN
@strong{Ports}: To satisfy the specification of SRFI-18 (Threading),
every call to I/O primitives of Gauche locks the port.
This overhead may be visible if the application does a lot of I/O
with smaller units (e.g. every bytes).   The primitives that deals
with larger unit, such as @code{read} and @code{read-uvector}, are less
problematic, since usually they just lock the port once per call and do
all the low-level I/O without the lock overhead.
(Note: this doesn't mean those primitives @emph{guarantee}
to lock the port throughout the execution of the function;
furthermore, the port locking feature is optimized for the case
that port accesses rarely collide.  If you know it is possible that
more than one threads read from or write to the same port, it is
your responsibility to use mutex explicitly to avoid the collision.)
@c JP
@strong{Ports}: SRFI-18 (スレッド) の仕様を満たすために
Gauche のすべての入出力基本関数はポートをロックします。
このオーバーヘッドは小単位(例えばバイト毎)の入出力を行なう
アプリケーションでは無視できないでしょう。
入出力基本関数は通常呼びだし毎にポートをロックし、そこからの
下位レベルの入出力はロックのオーバーヘッドの影響を受けずに
行なわれます。ですから @code{read} や@code{read-uvector}
などのより大きな単位で入出力を行なう基本関数では問題と
なることが少なくなります。
(注意：これらの基本関数が常にポートをロックしつづけることを
保証するものではないことに注意してください。また、ポートのロックは
競合がほとんど発生しない場合に最適化されています。
ポートへのアクセスが複数のスレッドで競合する可能性がある場合は、
アプリケーション側でmutexを明示的に用いて競合を避けてください。)
@c COMMON

@c EN
If you find out the locking is indeed a bottleneck, there are couple
of things you can consider: (1) Try using the larger-unit primitives,
instead of calling the smaller-unit ones.  (2) Use @code{with-port-locking}
(see @ref{Port and threads}) to lock the port in larger context.
@c JP
ポートロックが実際に問題となった場合、二つばかり対処策が考えられます。
(1) より大きな単位で入出力を行なう。(2) @code{with-port-locking}
(@ref{Port and threads} 参照)を使ってより広範囲でポートをロックする。
@c COMMON

@c EN
@strong{Strings}: Because of the multibyte strings, two operations
are particularly heavy in Gauche: string mutation and indexed string access.
It is a design choice; we encourage the programming style that
avoids those operations.  When you sequentially access the string,
string ports (see @ref{String ports}) provide a cleaner and
more efficient way.
When you search and retrieve a substring, there are various
higher-level primitives are provided (see @ref{String utilities},
@ref{Regular expressions}, and @ref{String library}, for example).
If you're using strings to represent an octet sequence, use uniform
vectors (see @ref{Uniform vectors}) instead.
@c JP
@strong{文字列}: 多バイト文字列の取扱いのため、Gauche では文字列の
変更とインデックスによるアクセスが特に高価な操作となります。
これは意図的な設計です。 Gauche ではこの二つの操作を避けたプログラミングを
推奨しています。 文字列の中の文字を順にアクセスするには
(インデックスを使わずに)文字列ポート(@ref{String ports}参照)を使うと
より明瞭かつ効率的なプログラムとなり、一方サーチして部分文字列をとり出す
といった操作には、多彩な高レベル関数が用意されています。
(例えば @ref{String utilities}、@ref{Regular expressions}、
 @ref{String library} 等を参照。)  バイト列を表現するのに
文字列を使っていたなら、代わりにユニフォームベクタ(@ref{Uniform vectors}
参照)を使いましょう。
@c COMMON

@c EN
@strong{Deep recursion}: Gauche's VM uses a stack for efficient
local frame allocation.  If recursion goes very deep (depending on
the code, but usually several hundreds to a thousand), the stack
overflows and Gauche moves the content of the stack into the heap.
This incurs some overhead.  If you observe a performance degradation
beyond a certain amount of data, check out this possibility.
@c JP
@strong{深い再帰}: Gauche の仮想機械(VM)は効率的な
ローカルフレーム割り当てのためにスタックを使っています。
再帰が深くなって(プログラムにもよりますが、大体数百回から千回)
スタックがオーバーフローするとスタックの内容をヒープに退避するという
オーバーヘッドが生じます。 あるデータ量を越えたところでパフォーマンスの
低下が見られたならば、深い再帰がないか調べてみて下さい。
@c COMMON

@c EN
@strong{Generic functions}: Because of its dynamic nature, generic
function calls are slower than procedure calls.  Not only because
of the runtime dispatch overhead, but also because Gauche's compile-time
optimizer can't do much optimization for generic function calls.
You don't need to avoid generic functions because of performance
reasons in general, but if you do find single function call consuming
a large part of execution time and it is calling a generic
function in its inner loop---then it may be worth to modify it.
@c JP
@strong{Generic functions}: Generic function の持つ動的な性質の
ため、これらの呼び出しは通常の手続き呼び出しより遅くなります。
実行時のディスパッチのオーバヘッドだけでなく、
VM コードへのコンパイル時にたいして最適化が行えないためです。
パフォーマンスのために Generic function の利用をどんな場合にも避ける
という必要はありませんが、もしある一つの関数が実行時間の大部分を
占めていて、その関数が Generic function を内部で呼び出しているなら
それを使わないように変更してみる価値はあるでしょう。
@c COMMON

@c EN
@strong{Redefining builtin functions}: Gauche inlines some builtin
functions if they are not redefined.  Although sometimes it is useful
to redefine basic functions, you may want to limit the effect.
For example, put redefined functions in a separate module and
use the module in the code that absolutely needs those functions
replaced.
@c JP
@strong{組込み関数の再定義}:
Gauche のコンパイラはいくつかの組込み関数を(それらが再定義されていなければ)
インライン展開します。 基本関数を再定義するのは時には便利ですが、
限られた範囲にとどめておいた方がよいでしょう。
やり方は、再定義をどこか別のモジュールに集めておき、どうしても再定義
バージョンが必要なときに限ってそのモジュール use するというように
しておけばよいでしょう。
@c COMMON

@c EN
@strong{Closure creation}: When you create a closure, its closing environment
is copied to the heap.  This overhead is small, but it still may be
visible when a closure is created within an innermost loop that is
called millions of times.   If you suspect this is a problem,
try disassemble the function.   Gauche's compiler uses some basic
techniques of closure analysis to avoid creating closures for
typical cases, in which case you see the local function's bodies
are inlined.  If you see a @code{CLOSURE} instruction, though, it
means a closure is created.
@c JP
@strong{クロージャの作成}: クロージャを作成するとそれが持つ環境がヒープに
コピーされます。 オーバーヘッドは小さいですが、何百万回も呼ばれるような
ループの中で作成されれば無視できなくなるでしょう。そんな疑いがあれば
その関数を逆アセンブルしてみましょう。 Gauche のコンパイラはクロージャの
簡単な解析を行ない生成をなるべく避けるようになっています。そのような場合
局所関数の本体はインライン展開されています。逆アセンブルのコードに
@code{CLOSURE}命令が含まれていれば、残念ながらクロージャが生成されます。
@c COMMON

@c EN
This list isn't complete, and may change when Gauche's implementation
is improved, so don't take this as fixed features.
We'll adjust it occasionally.
@c JP
これらのヒント集は完全でないし、Gauche の改良とともに変わっていくでしょう。
ですから、固定された特徴だとは思わないで下さい。
このヒント集は今後、折を見て実装に対応させて更新してゆきます。
@c COMMON

@c ----------------------------------------------------------------------
@node Auxiliary programs, Writing Gauche modules, Profiling and tuning, Programming in Gauche
@section Auxiliary programs
@c NODE 補助プログラム

When you install Gauche, you'll get several auxiliary programs
that help developing Gauche applications.

@table @code
@item gauche-config
This program can be used to query various configuation parameters of
installed Gauche.
@item gauche-package
Extension package manager.  It can be used to install extension
packages and query their parameters.  You can also use this to
start writing your own extensions.
@item gauche-install
An alternative @code{install} program.  Gauche extensions can use
this instead of system's @code{install} command, so that they don't
need to worry about differences among platforms.
@item gauche-compile-r7rs
This program can be used to create an executable binary from
Gauche scripts.
@item gauche-cesconv
@end table

Additionally, if you configure Gauche with @code{--enable-shared-commands},
the following programs are also installed.

@table @code
@item scheme-r7rs
@itemx scheme-srfi-0
@itemx scheme-srfi-7
Those are the names of Scheme interpreter suggeted by SRFI-22.
They are symlinked to @code{gosh}.
@item compile-r7rs
This is the name of Scheme compiler recommended by SRFI-138.
It is symlinked to @code{gauche-compile-r7rs}.
@end table

@c ----------------------------------------------------------------------
@menu
* Command to query configuration::
* Command to manage extension packages::
* Command to install files::
* Comamnd to compile scripts::
@end menu

@node Command to query configuration, Command to manage extension packages, Auxiliary programs, Auxiliary programs
@subsection @code{gauche-config} - Query configuration
@c NODE 設定を問い合わせる, @code{gauche-config} - 設定を問い合わせる

@deftp {Program} gauche-config [option]
Without options, prints the command usage.  With an option, prints
the string associated to the option, which is determined at configuration
time.

Here are some examples.  Note that output may vary on your platform.

@itemize @bullet
@item
Print the running architecture:
@example
$ gauche-config --arch
x86_64-pc-linux-gnu
@end example

@item
Print the library flags required to link programs using Gauche:

@example
$ gauche-config -l
-lgauche-0.98 -lmbedtls -lcrypt -lrt -lm  -lpthread
@end example

@item
Print the include path flags required to comple Gauche extension.

@example
$ gauche-config -I
-I/usr/lib/gauche-0.98/0.9.15/include
@end example
@end itemize

The command accepts the following arguments.  You can only give at most
one.

@c xinclude man-gauche-config.texi

@end deftp


@node Command to manage extension packages, Command to install files, Command to query configuration, Auxiliary programs
@subsection @code{gauche-package} - Manage extension packages
@c NODE 拡張パッケージの管理, @code{gauche-package} - 拡張パッケージの管理

@deftp {Program} gauche-package command [arg @dots{}]
This command can be used to build and install Gauche extensions,
query installed ones, and help start building new ones.
It has several subcommands, which can be listed with
@code{gauche-package help}.
@end deftp


@node Command to install files, Comamnd to compile scripts, Command to manage extension packages, Auxiliary programs
@subsection @code{gauche-install} - Install files
@c NODE ファイルのインストール, @code{gauche-install} - ファイルのインストール

@deftp {Program} gauche-install [options] file dest
@deftpx {Program} gauche-install [options] file @dots{} dir
@deftpx {Program} gauche-install -d [options] dir @dots{}
@deftpx {Program} gauche-install -T dir [options] file @dots{}
@deftpx {Program} gauche-install -U dir [options] file @dots{}
This command can be used to install files.  It is upper-compatible
to BSD @code{install} command and can be used as drop-in replacement.
Notably, the first three command invocation format are compatible
with BSD install.
It has several more features that keeps @code{Makefile} concise.

The first and second invocation format copies @var{file}(s) to @var{dest}
(a file pathname) or @var{dir} (an existing directory).  You can
specify permissons, owners, etc.  Basically it's a fancier @code{cp}.

The third format creates @var{dir}(s) if they don't exist.  Basically
it's a fancier @code{mkdir -p}.

The fourth format copies @var{file} @dots{} to @var{dir}.  It differs
from the second format in the sense that relative pathname of @var{file}
is preserved.  That is, if you run the following command:

@example
gauche-install -T /usr/local/mytool foo.scm bar/baz.scm
@end example

It creates @file{/usr/local/mytool/foo.scm} and
@file{/usr/local/mytool/bar/baz.scm}.  With the second format, the
subdirectory @code{bar} won't be created.  This format is handy
when you want to install a bunch of subtrees.

The fifth format uninstall files which would be installed with @code{-T}
option.  Simply change @code{-T} option to @code{-U} option and you'll
clean the files.

The following command-line arguments are recognized.

@table @option
@item -C
@itemx --canonical-suffix
If installed file has a suffix @file{.sci}, replace
it for @file{.scm}.   This is Gauche specific convention.
@item -T dir
@itemx --target dir
Installs files to the @var{dir}, creating paths if needed.
Partial path of files are preserved. (4th format only)
@item -U dir
@itemx --uninstall dir
Reverse the effect of @code{-T}, e.g. removes files from its
destination @var{dir}.
@item -S dir
@itemx --srcdir dir
Look for @var{file} @dots{}  within @var{dir}; useful if @code{VPATH} is used.
@item --shebang path
Adds @code{#!@var{path}} before the file contents.
Useful to install scripts.
@item -d
@itemx --directory
Creates directories.  (3rd format only).
@item -m mode
@itemx --mode mode
Change mode of the installed file.
@item -p prefix
@itemx --strip-prefix prefix
Strip prefix dirs from @var{file} @dots{} before
installation. (4th/5th format only).
@item -o owner
@itemx --owner owner
Change owner of the installed file(s).
@item -g group
@itemx --group group
Change group of the installed file(s).
@item -v
@itemx --verbose
Work verbosely
@item -d
@itemx --dry-run
Just prints what actions are to be done, but won't execute them.
@end table
@end deftp


@node Comamnd to compile scripts,  , Command to install files, Auxiliary programs
@subsection @code{gauche-compile-r7rs} - Compile scripts
@c NODE スクリプトのコンパイル, @code{gauche-compie-r7rs} - スクリプトのコンパイル

For Gauche-specific programs, we have @code{tools/build-standalone} Scheme
script (@pxref{Building standalone executables}).  We recommend
that script, for it is more featureful.

The @code{gauche-compile-r7rs} and @code{compile-r7rs} script is provided
so that you can invoke a 'Scheme compiler' with a standardized manner.
It may be handy if other tools (e.g. IDE) need to invoke a Scheme
compiler as a subprocess.

This interface is defined in SRFI-138, which also suggests the name
@code{compile-r7rs}.  We only install @code{gauche-compile-r7rs} by
default so that we won't accidentally clobber other implementation's
program, but if you give @code{--enable-shared-commands} option to
@code{configure} script, a symbolic link @code{compile-r7rs} is created.

@deftp {Program} gauche-compile-r7rs [options] script.scm
@deftpx {Program} compile-r7rs [options] script.scm
Compile a Scheme source file @code{script.scm} and produce an
executable binary.  The @code{compile-r7rs} is only installed
if Gauche is configured with @code{--enable-shared-commands}.

Note: SRFI-138 states that if the environment variable
@code{COMPILE_R7RS} is defined, it is assumed to a pathname of another
program and is executed instead of Gauche's @code{compile-r7rs}.
We think the feature is rather confusing than convenient, so we
don't support it.  If you want to run alternative implementation's
compiler, there are more explicit means such as running it directly
or change @code{PATH}.

The following command-line arguments are recognized.

@table @option
@item -I path
@itemx -A path
Prepend or append @var{path} to the path list the referenced
libraries are searched.  These options can be specified multiple times.

@item -o outfile
Specifies output executable filename.  When omitted, @code{a.out}
(on POSIX systems) or @code{a.exe} (on Windows) are used.

@item -D feature-id
Adds @code{feature-id} to the list of feature identifiers.
This is to switch code conditionally in the source with
@code{cond-expand}.
This option can be specified multiple times.

Note that this does @emph{not} enable certain features.  So you
shouldn't specify system-reserved feature identifiers
(@pxref{Platform-dependent features}).  This is also different
from @code{-D} option of @code{tools/build-standalone}.
@end table
@end deftp


@c ----------------------------------------------------------------------
@node Writing Gauche modules, Using extension packages, Auxiliary programs, Programming in Gauche
@section Writing Gauche modules
@c NODE Gaucheのモジュールを書く

@c EN
Gauche's libraries are organized by modules.   Although Gauche
can load any valid Scheme programs, there is a convention that
Gauche's libraries follow.    When you write a chunk of Scheme
code for Gauche, it is convenient to make it a module,
so that it can be shared and/or reused.
@c JP
Gaucheのライブラリはモジュール毎に整理されています。Gaucheはどんな形式でも、
有効なScheme式が書かれてさえいればロードすることができますが、
Gaucheのライブラリは一定の形式を保って書かれています。
Gauche用にまとまったSchemeコードを書いたら、それをモジュール形式にしておくと
再利用がしやすくなるでしょう。
@c COMMON

@c EN
Usually a module is contained in a file, but you can make
a multi-file module.
First I explain the structure of a single-file module.
The following template is the convention used in Gauche's libraries.
@c JP
通常ひとつのファイルで
ひとつのモジュールを定義しますが、モジュールを複数のファイルに分けることもできます。
まずひとつのファイルでモジュールを定義する方法を説明します。
Gaucheのライブラリで使われているテンプレートは次のような形式です。
@c COMMON

@example
@c EN
;; Define the module interface
@c JP
;; モジュールのインタフェースの定義
@c COMMON
(define-module foo
  (use xxx)
  (use yyy)
  (export foo1 foo2 foo3)
  )
@c EN
;; Enter the module
@c JP
;; モジュール本体
@c COMMON
(select-module foo)

@dots{} module body @dots{}

@end example

@c EN
This file must be saved as ``foo.scm'' in some directory in the
@code{*load-path*}.
@c JP
このファイルは``foo.scm''という名で、@code{*load-path*}にあるディレクトリの
いずれかに置かれなければなりません。
@c COMMON

@c EN
The @code{define-module} form creates a module @code{foo}.
It also loads and imports some other modules by `@code{use}' macros,
and declares which symbols the @code{foo} module exports, by `@code{export}'
syntax.
(See section @ref{Defining and selecting modules}, for detailed specification of those
syntaxes).
@c JP
まず、@code{define-module}フォームがモジュール@code{foo}を作成します。
@code{define-module}フォーム内で、このモジュールが依存している他のモジュール
を `@code{use}' マクロを使ってロードし、このモジュールがエクスポートするシンボルを
`@code{export}' 構文を使って指定します。(これらの構文の詳細は@ref{Defining and selecting modules}を
参照して下さい)。
@c COMMON

@c EN
Those @code{use} forms or @code{export} forms are not required to appear
in the @code{define-module} form, but it is a good convention to keep
them in there at the head of the file so that it is visually recognizable
which modules @code{foo} depends and which symbols it exports.
@c JP
これらの@code{use}フォームや@code{export}フォームは必ずしも@code{define-module}
フォームの先頭に置く必要はありませんが、このようにファイルの最初の方に固めておくことで、
@code{foo}が依存しているモジュール群や@code{foo}が提供するシンボル等が
一覧しやすくなります。
@c COMMON

@c EN
The second form, `@code{select-module}',
specifies the rest of the file is evaluated in the
module @code{foo} you just defined.   Again, this is just a
convention; you can write entire module body inside @code{define-module}.
However, I think it is error-prone, for the closing parenthesis
can be easily forgotten or the automatic indentation mechanism of
editor will be confused.
@c JP
次の、`@code{select-module}' フォームにより、それ以降のScheme式が
モジュール@code{foo}の中で評価されます。モジュールの内容を全て@code{define-module}の中に
書いてしまうことも出来ますが、最後の括弧を閉じ忘れやすいことや、エディタのインデントが
狂うことなどから、あまりお薦めしません。
@c COMMON

@c EN
After @code{select-module} you can write whatever Scheme expression.
It is evaluated in the selected module, @code{foo}.   Only the bindings
of the exported symbols will be directly accessible from outside.
@c JP
@code{select-module}フォームの後には、モジュールの内容であるScheme式を自由に書けます。
それらはモジュール@code{foo}の中で評価されます。モジュール内で定義するトップレベルの
束縛のうち、明示的に`export'で指定されたシンボルのみが、このモジュールをインポートする他の
モジュールから見えます。
@c COMMON

@c EN
So, that's it.   Other programs can use your module by just saying
`@code{(use foo)}'.   If you want to make your module available on your site,
you can put it to the site library location, which can be obtained by
@example
(gauche-site-library-directory)
@end example
in gosh, or
@example
gauche-config --sitelibdir
@end example
from shell.
@c JP
これで、他のプログラムは `@code{(use foo)}' とするだけでこのモジュールの機能が
利用可能になります。もしモジュールをサイト全体で利用できるようにしたければ、@code{gosh}内で
@example
(gauche-site-library-directory)
@end example
を評価して得られるディレクトリに@code{foo.scm}を置いて下さい。
@c COMMON

@c EN
If you feel like to conserve global module name space, you can organize
modules hierarchically.   Some Gauche libraries already does so.
@xref{Library modules - Overview}, for examples.
For example, @code{text.tr} module is implemented in ``text/tr.scm'' file.
Note that the pathname separator `/' in the file becomes a period in the
module name.
@c JP
モジュールの名前空間のトップに新たなモジュールを追加するのに気が引ける場合は、
モジュールを階層的に構成することもできます。Gaucheのモジュールの多くは既に階層的に
構成されています。具体的なモジュール例は@ref{Library modules - Overview}を参照して下さい。
例えば、@code{text.tr}モジュールは ``@code{text/tr.scm}'' ファイルに
実装されています。パス名の区切り文字`/'がモジュール名ではピリオドになることに
注意して下さい。
@c COMMON

@c ----------------------------------------------------------------------
@node Using extension packages, Building standalone executables, Writing Gauche modules, Programming in Gauche
@section Using extension packages
@c NODE 拡張パッケージの使用

@c EN
@subheading Building and installing packages
@c JP
@subheading パッケージの構築とインストール
@c COMMON

@c EN
Gauche comes with some amount of libraries, but they aren't
enough at all to use Gauche in the production environment.
There are number of additional libraries available.   We call them
@emph{extension packages}, or simply packages.  Each package
usually provides one or more modules that adds extra
functionality.   Most of the packages provide
binding to other C libraries, such as graphics libraries
or database clients.   If the package has some C code,
it is likely that you need to compile it on your machine with
the installed Gauche system.
@c JP
Gauche にはまとまったライブラリが付属していますが、
Gauche をプロダクション環境で利用するのにはとても十分とはいえません。
利用可能な追加ライブラリもいくつもあります。こうしたライブラリを
@emph{拡張パッケージ}、あるいは単にパッケージといいます。それぞれの
パッケージは追加機能を提供するひとつあるいはそれ以上のモジュールを
提供します。ほとんどのパッケージは別のCのライブラリへのバインディングを
提供しています。たとえば、グラフィックスライブラリとかデータベース
クライアントなどです。もし、パッケージがいくぶんでもCのコードを含む
場合は、利用するマシン上で、既にインストールされている Gauche システムを
使って、そのコードをコンパイルする必要があります。
@c COMMON

@c EN
Usually a package is in the form of compressed tarball, and the standard
"ungzip + untar + configure + make + make install" sequence does the job.
Read the package's document, for you may be able to tailor
the library for your own needs by giving command-line options
to the @code{configure} script.
@c JP
通常、パッケージは圧縮 tarball の形式になっています。標準的には、
「gzの解凍 + tarの展開 + configure + make + make install」とやればよいように
なっています。パッケージのドキュメントを読めば、必要に応じて、
@code{configure} スクリプトに与えるコマンドラインオプションで
ライブラリを調整できるようになっています。
@c COMMON

@c EN
From Gauche 0.8, an utility script called @code{gauche-package} is
installed for the convenience.  It automates the build and install
process of packages.
@c JP
Gauche 0.8 より、@code{gauche-package} というユーティリティスクリプトが
インストールされるようになっています。これはパッケージの構築と
インストールを自動化します。
@c COMMON

@c EN
Suppose you have downloaded a package @file{Package-1.0.tar.gz}.
If the package follows the convention, all you have to do is
to type this:
@c JP
@file{Package-1.0.tar.gz} というパッケージをダウンロードしてきた
としましょう。もし、このパッケージが慣例に従っていれば、やることは
@c COMMON

@example
$ gauche-package install Package-1.0.tar.gz
@end example

@c EN
It ungzips and untars the package, @code{cd} into the @file{Package-1.0}
subdirectory, run configure, make, and make install.
By default, @code{gauche-package} untars the tarball in the current
working directory.  You can change it by a customization file; see below.
@c JP
とタイプするだけです。
これで、gzip圧縮ファイルの解凍、tarアーカイブファイルの展開、
@file{Package-1.0} サブディレクトリへの移動、configure スクリプトの
実行、make、make install が行われます。デフォルトでは、
@code{gauche-package} はカレントディレクトリに tarball を展開します。
これをカスタマイズファイル(後述)で変更することができます。
@c COMMON

@c EN
If you need a special privilege to install the files, you can
use @code{--install-as} option which runs @code{make install} part via
the @code{sudo} program.
@c JP
ファイルをインストールするのに特別な権限が必要な場合には、
@code{--install-as} というオプションを使うと、@code{make install}
部分が、@code{sudo} を使って実行されます。
@c COMMON

@example
$ gauche-package install --install-as=root Package-1.0.tar.gz
@end example

@c EN
If it doesn't work for you, you can just build the package
by @code{gauche-package build Package-1.0.tar.gz}, then
manually cd to the @file{Package-1.0} directory and run
@code{make install}.
@c JP
上手くいかない場合には、@code{gauche-package build Package-1.0.tar.gz}
とやってパッケージの構築だけすることもできます。この場合、手で
@file{Package-1.0} ディレクトリに移動して、@code{make install} を
実行します。
@c COMMON

@c EN
You can give configuration options via @code{-C} or @code{--configure-options}
command-line argument, like this:
@c JP
設定オプションを @code{-C} あるいは @code{--configure-options}
というコマンドライン引数で与えられます。たとえば、
@c COMMON

@example
$ gauche-package install -C "--prefix=/usr/local" Package-1.0.tar.gz
@end example

@c EN
If the package has adopted the new package description file,
it can remember the configuration options you have specified, and
it will automatically reuse them when you install the package
again.  (If you're a package developer, check out
@file{examples/spigot/README} file in the Gauche source tree
to see how to cooperate with Gauche's package management system.)
@c JP
もしパッケージがこの新しい記述ファイルを採用しているなら、
以前に指定した設定オプションを記憶していて、そのパッケージを
再度インストールするときには、自動的にそれを再利用します。
(パッケージ開発者の方は、Gauche のソースツリーにある、
@file{examples/spigot/README} ファイルをチェックアウトすれば、
どのように Gauche のパッケージマネージメントシステムがやっているかを
見られます。)
@c COMMON

@c EN
If you don't have a tarball in your local directory, but you know
the URL where you can download it, you can directly give the URL
to @code{gauche-package}.  It understands @code{http} and @code{ftp},
and uses either @code{wget} or @code{ncftpget} to download the tarball,
then runs configure and make.
@c JP
tarball がローカルディレクトリにない場合でも、ダウンロードしてくる
URL を知っているなら、その URL を直接 @code{gauche-package} に与える
ことができます。@code{gauche-package} は @code{http} および @code{ftp}
を理解し、@code{wget} か @code{ncftpget} のどちらかを使って、その
tarball をダウンロードし、configure および make を実行します。
@c COMMON

@example
$ gauche-package install http://www.example.com/Package-1.0.tar.gz
@end example

@c EN
@subheading Customizing @code{gauche-package}
@c JP
@subheading @code{gauche-package} のカスタマイズ
@c COMMON

@c EN
The @code{gauche-package} program reads @file{~/.gauche-package} if
it exists.  It must contain an associative list of parameters.
It may look like this:
@c JP
@code{gauche-package} プログラムは @file{~/.gauche-package} があれば、
それを読みます。このファイルにはパラメータの連想リストが含まれて
いなければなりません。こんな感じです。
@c COMMON

@example
(
 (build-dir . "/home/shiro/tmp")
 (gzip      . "/usr/local/bin/gzip")
 (bzip2     . "/usr/local/bin/bzip2")
 (tar       . "/usr/local/bin/gtar")
)
@end example

@c EN
The following is a list of recognized parameters.
If the program isn't given in the configuration file, @code{gauche-package}
searches @code{PATH} to find one.
@c JP
以下は、認識されるパラメータのリストです。
設定ファイルにプログラムが与えられていなければ、@code{gauche-package}
は @code{PATH} を探します。
@c COMMON

@c EN
@table @code
@item build-dir
A directory where the tarball is extracted.  If URL is given,
the downloaded file is also placed in this directory.
@item bzip2
Path to the program @code{bzip2}.
@item cat
Path to the program @code{cat}.
@item make
Path to the program @code{make}.
@item ncftpget
Path to the program @code{ncftpget}.
@item rm
Path to the program @code{rm}.
@item sudo
Path to the program @code{sudo}.
@item tar
Path to the program @code{tar}.
@item wget
Path to the program @code{wget}.
@end table
@c JP
@table @code
@item build-dir
tarball が展開されるディレクトリ。もし、URL が与えられれば、
ダウンロードされたファイルはこのディレクトリに置かれます。
@item bzip2
@code{bzip2} プログラムへのパス
@item cat
@code{cat} プログラムへのパス
@item make
@code{make} プログラムへのパス
@item ncftpget
@code{ncftpget} プログラムへのパス
@item rm
@code{rm} プログラムへのパス
@item sudo
@code{sudo} プログラムへのパス
@item tar
@code{tar} プログラムへのパス
@item wget
@code{wget} プログラムへのパス
@end table
@c COMMON

@c ----------------------------------------------------------------------
@node Building standalone executables,  , Using extension packages, Programming in Gauche
@section Building standalone executables
@c NODE スタンドアロン実行可能ファイルの作成

@c EN
When you want to distribute your Gauche scripts or applications,
the users need to install Gauche runtime on their machine.
Although it is always the case for any language implementations---you need
Java runtime to run Java applications, or C runtime to run
C applications---it may be an extra effort to ask users to install
not-so-standard language runtimes.
@c JP
Gaucheで作ったスクリプトやアプリケーションを配布する場合、
ユーザはGaucheのランタイムを手元のマシンにインストールする必要があります。
これは原理的にはどんな言語でも同じことです--Javaアプリケーションを使うなら
Javaランタイムが必要ですし、Cアプリケーションを使うならCランタイムが必要です。
けれどもGaucheのようなマイナーな言語処理系のランタイムをインストールしてくれることを
ユーザにお願いするのは、ややハードルが高いでしょう。
@c COMMON

@c EN
To ease distribution of Gauche applications, you can create a
stand-alone executable.  It statically links entire Gauche system
so that it runs by just copying the executable file.
@c JP
Gaucheのアプリケーションの配布を簡単にするために、
スタンドアロン実行ファイルを作ることができます。
これは、Gaucheシステム全体をスタティックリンクし、
ファイルひとつコピーすれば使えるような実行ファイルを生成します。
@c COMMON

@c EN
Gauche also provides a @code{compile-r7rs} program that is compliant
with the command-line interface presented in SRFI 138
(@url{https://srfi.schemers.org/srfi-138/srfi-138.html}).
@xref{Comamnd to compile scripts}, for the details.
@c JP
Gaucheはまた、SRFI 138が定義するコマンドラインインターフェイスに
準拠する@code{compile-r7rs}スクリプトも提供します。
(@url{https://srfi.schemers.org/srfi-138/srfi-138.html})
詳しくは@ref{Comamnd to compile scripts}を参照してください。
@c COMMON

@c EN
@subheading Quick recipe
@c JP
@subheading 簡単な使い方
@c COMMON

@c EN
To generate a standalone executable, just give your script file
to the @file{tools/build-standalone} script, which is installed as a
part of Gauche.
@c JP
スタンドアロンな実行可能ファイルを作るには、Gaucheのインストール時に一緒に
インストールされる@file{tools/build-standalone}にスクリプトファイルを与えるだけです。
@c COMMON

@example
gosh tools/build-standalone yourscript.scm
@end example

@c EN
It will create an executable file @code{yourscript} (or @code{yourscript.exe}
on Windows) in the current directory.
@c JP
これで、実行可能ファイル@code{yourscript} (Windowsでは@code{yourscript.exe})
がカレントディレクトリに作られます。
@c COMMON

@c EN
To specify the output name different from the script name,
give @code{-o} option:
@c JP
スクリプト名とは別に実行ファイル名を指定したい場合は@code{-o}オプションを使います。
@c COMMON

@example
gosh tools/build-standalone -o yourcommand yourscript.scm
@end example

@c EN
When your script needs supporting library files, you should list
those files as well:
@c JP
スクリプトが他のサポートライブラリコードを必要とする場合は、
そのライブラリファイルも一緒に指定します。
@c COMMON

@example
gosh tools/build-standalone yourscript.scm lib/library1.scm lib/library2.scm
@end example

@c EN
The library file paths need to be relative to the respective load path.
See the explanation of @code{-I} option below.
@c JP
ライブラリファイルのパス名は、@code{load}がそのファイルを見つけられるような、
ロードパスからの相対パスである必要があります。
詳しくは下の@code{-I}オプションの説明を見てください。
@c COMMON

@c EN
@subheading Catches
@c JP
@subheading 注意点
@c COMMON

@c EN
There are a few things you should be aware of.
@c JP
いくつか、気をつけなければならないことがあります。
@c COMMON

@itemize
@item
@c EN
The size of the binary tend to be large, since it contains the entire
Gauche system regardless of whether your application use it or not.
You can strip down the size if you need to, but you need to rebuild
Gauche library to do so.  See @file{doc/HOWTO-standalone.txt} in the
source tree for the details.
@c JP
アプリケーションが使うかどうかに関わらず、バイナリにはGaucheシステム全てが含まれるので、
バイナリのサイズはかなり大きくなります。
サイズが問題になるなら使わないライブラリを削除することもできますが、
それにはGaucheライブラリをリビルドしなければなりません。詳しくは
ソースツリーにある@file{doc/HOWTO-standalone.txt}を参照してください。
@c COMMON

@item
@c EN
The generated binary still depends on external dynamically linked
libraries, such as libpthread.  The exact dependency may differ
how Gauche is configured, and can be checked
by running system-provided tools,
such as @code{ldd} on most Unix systems and MinGW or @code{otool -L} on OSX,
on the generated standalone binaries.
You may want to ensure the users have required libraries.
@c JP
作られたバイナリファイルは、libpthreadなど外部の動的ライブラリには依存します。
具体的にどのライブラリに依存するかはプラットフォームとGaucheのコンフィグレーションによります。
確かめるには、生成されたバイナリファイルに対してシステムのツール
(多くのUnixやMinGWなら@code{ldd}、OSXなら@code{otool -L}など)を
走らせて下さい。
ユーザ環境にもそれらの動的ライブラリが入っている必要があります。
@c COMMON

@item
@c EN
Currently we don't yet have a convenient way to statically link
extension libraries.  We're working on it.
@c JP
Gaucheの拡張ライブラリをスタティックリンクする機能についてはまだ開発中です。
@c COMMON

@item
@c EN
If Gauche is configured to use gdbm, it is linked to the standalone binary
by default, hence the binary itself is covered by GPL.  In case if you
need to distribute binaries under BSD license, you need to give
@code{-D GAUCHE_STATIC_EXCLUDE_GDBM} flag to @code{tools/build-standalone}.
It makes @code{tools/build-standalone} not to link gdbm (and your script won't
be able to use it).
@c JP
Gaucheがgdbmを使うようにコンフィグされていた場合、実行可能ファイルにもgdbmが
スタティックリンクされるので、実行可能ファイルの配布ライセンスがGPLになります。
もしGPLでなくBSDライセンスで配布したい場合は、@code{tools/build-standalone}スクリプトに
@code{-D GAUCHE_STATIC_EXCLUDE_GDBM}フラグを与えてください。
そうするとgdbmはリンクされなくなります(その場合、スクリプトからgdbmは使えません)。
@c COMMON

@item
@c EN
If you build Gauche with mbedTLS support (if you have libmbedtls on
your machine, Gauche include its support by default), the resulting standalone
binary also depends on libmbedtls DSO files.  If you're not sure mbedTLS
DSO files are available on target machines, you can exclude
@code{rfc.tls.mbed} module by giving
@code{-D GAUCHE_STATIC_EXCLUDE_MBED} flag to @code{tools/build-standalone}.
@c JP
もしGaucheがmbedTLSサポートつきでビルドされていた場合
(libmbedtlsがシステムにインストールされていると、デフォルトでそのサポートはonになります)、
作られるスタンドアローンバイナリはlibmbedtls DSOファイルに依存します。
ターゲットマシンにmbedTLSがインストールされているとは限らない場合は、
@code{tools/build-standalone}に@code{-D GAUCHE_STATIC_EXCLUDE_MBED}フラグを与えることで、
@code{rfc.tls.mbed}モジュールへの依存を除外することができます。
@c COMMON

@end itemize

@menu
* Using build-standalone::
@end menu

@node Using build-standalone,  , Building standalone executables, Building standalone executables
@subsection Using build-standalone
@c NODE build-standaloneスクリプトを使う

@deftp {Program} {gosh tools/build-standalone} [options] script-file [library-file @dots{}]
@c EN
Create a stand-alone binary to execute a Gauche program in @var{script-file}.
It is executed as if it is run as @code{gosh script-file}, with a few
differences.
@c JP
@var{script-file}に記されたGaucheプログラムを実行するスタンドアロンの
バイナリ実行可能ファイルを生成します。作られた実行可能ファイルを実行すると、
多少の違いを除いては、あたかも@code{gosh script-file}を実行したのと同じ動作になります。
@c COMMON

@c EN
The main thing is that since @var{script-file} is no longer
loaded from file, code that references paths relative to @var{script-file} won't
work.  One example is @code{(add-load-path dir :relative)}
(@pxref{Loading Scheme file}).  Auxiliary library files required by
@var{script-file} must be explicitly
listed as @var{library-file} @dots{}, so that
they are bundled together into the executable.
@c JP
違いの重要な点は、実行可能ファイルでは@var{script-file}がファイルシステムからロード
されないため、@var{script-file}のパスからの相対パスで何かを参照しているコードは
動かなくなるということです。例えば@code{(add-load-path dir :relative)}
で補助ライブラリを参照しているような場合です(@ref{Loading Scheme file}参照)。
@var{script-file}に必要な補助ライブラリはコマンドラインの@var{library-file} @dots{}に
明示的に与えられなければなりません。それらは実行可能ファイルに同梱されます。
@c COMMON
@end deftp

@c EN
The following command-line options are recognized.
@c JP
以下のコマンドラインオプションが使えます。
@c COMMON

@deftp {Command Option} -o outfile
@c EN
Specifies output executable filename.  When omitted, the basename of
@var{script-file} without extension is used.
(Or, on Windows, swapping extension with @code{.exe}).
@c JP
出力される実行可能ファイルの名前を指定します。省略された場合は@var{script-file}の
basenameから拡張子を除いたものになります。
(Windowsの場合は拡張子を@code{.exe}に変えたもの)
@c COMMON
@end deftp

@deftp {Command Option} -D var[=val]
@c EN
Add C preprocessor definitions while compiling the generated C code.
An important use case of this option is to exclude gdbm dependency
from the generated binaries, by specifying
@code{-D GAUCHE_STATIC_EXCLUDE_GDBM}.  Note that you need a whitespace
between @code{-D} and @var{var}.

This option can be specified multiple times.
@c JP
中間で生成されるCコードをコンパイルする際に、Cプリプロセッサ定義を追加します。
使用例のひとつは、@code{-D GAUCHE_STATIC_EXCLUDE_GDBM}を指定することで
生成される実行可能ファイルからgdbmへの依存を取り除くというものです。
@code{-D}と@var{var}の間に空白が必要なことに注意してください。

このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} -I load-path
@c EN
Specifies the load path where @var{library-file} @dots{} are searched.
The names given to @var{library-file} must match how they are @code{load}ed
or @code{use}d.  If such paths are not relative to the directory
you run @code{tools/build-standalone}, you have to tell where to find
those libraries with this option.

For example, suppose you have this structure:
@c JP
@var{library-file} @dots{}が検索されるロードパスを指定します。
@var{library-file}に与えられるパス名は、それらをロードするために
@code{load}や@code{use}に与えられるパス名と一致している必要があります。
もし@code{tools/build-standalone}を走らせるディレクトリから見て
これらのファイルが置かれている相対パスが必要なものと違っていた場合、
このオプションを指定してどのディレクトリからの相対でファイルを探すかを
教えてやらないとなりません。

例えばソースが次のとおり構成されていたとしましょう。
@c COMMON

@example
project/src/
    +----- main.scm
    |          (use myscript.util)
    +----- myscript/util.scm
               (define-module myscript.util ...)
@end example

@c EN
If you run @code{tools/build-standalone} in the directory as @file{src},
you can just say this:
@c JP
@code{tools/build-standalone}を@file{src}の下で実行する場合は、
単に次のとおり実行すれば済みます。
@c COMMON

@example
gosh tools/build-standalone main.scm myscript/util.scm
@end example

@c EN
But if you run it under @file{project}, you need to say this:
@c JP
しかし、@file{project}の下で実行する場合は次のようにしなければなりません。
@c COMMON

@example
gosh tools/build-standalone -I src src/main.scm myscript/util.scm
@end example

@c EN
Another example; you have a separate library directory:
@c JP
別の例を挙げましょう。ライブラリのディレクトリが分かれている場合です。
@c COMMON

@example
project/
    +----- src/main.scm
    |          (use myscript.util)
    +----- lib/myscript/util.scm
               (define-module myscript.util ...)
@end example

@c EN
If you run @code{tools/build-standalone} in @file{src}, you say this:
@c JP
@code{tools/build-standalone}を@file{src}以下で走らせる場合は次のようにします。
@c COMMON

@example
gosh tools/build-standalone -I ../lib main.scm myscript/util.scm
@end example

@c EN
Or, if you run it in @file{project}, you say this:
@c JP
@file{project}以下で走らせる場合はこうなります。
@c COMMON

@example
gosh tools/build-standalone -I lib src/main.scm myscript/util.scm
@end example

@c EN
This option can be specified multiple times.
@c JP
このオプションは複数指定できます。
@c COMMON
@end deftp

@deftp {Command Option} --header-dir dir
@deftpx {Command Option} --library-dir dir
@c EN
These tells @code{tools/build-standalone} where to find Gauche C headers
and static libraries.

If you've installed Gauche on your system, @code{tools/build-standalone}
automatically finds these from the installed directory and you don't
need to worry about them.   Use these option only when
you need to use Gauche runtime that's not installed.
@c JP
これらのオプションは@code{tools/build-standalone}が必要なGaucheのCヘッダファイルや
スタティックライブラリをどこから探すかを指定します。

Gaucheが既にシステムにインストール済みであれば、@code{tools/build-standalone}は
インストールされたディレクトリから自動的に必要なファイルを探すので、
このオプションを気にする必要はありません。インストールしていないGaucheのランタイムを
利用したい場合のみこれらのオプションを指定してください。
@c COMMON
@end deftp


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