Debian Codegraph @

doc/program.texi

raw
1 @node Programming in Gauche, Core syntax, Concepts, Top
2 @chapter Programming in Gauche
3 @c NODE Gaucheでのプログラミング
4
5 @menu
6 * Invoking Gosh::
7 * Interactive development::
8 * Writing Scheme scripts::
9 * Debugging::
10 * Platform-dependent features::
11 * Profiling and tuning::
12 * Auxiliary programs::
13 * Writing Gauche modules::
14 * Using extension packages::
15 * Building standalone executables::
16 @end menu
17
18 @node Invoking Gosh, Interactive development, Programming in Gauche, Programming in Gauche
19 @section Invoking Gosh
20 @c NODE Gaucheを起動する
21
22 @c EN
23 Gauche can be used either as an independent Scheme scripting engine
24 or as an embedded Scheme library. An interactive interpreter
25 which comes with Gauche distribution is a program named @code{gosh}.
26 @c JP
27 Gaucheは独立したSchemeスクリプティングエンジンとしても、組み込みのSchemeライブラリとしても
28 使うことができます。Gaucheのディストリビューションには、@code{gosh}という
29 インタラクティブなインタプリタが附属しています。
30 @c COMMON
31
32 @deftp {Program} gosh [options] [scheme-file arg @dots{}]
33 @c EN
34 Gauche's interpreter. Without @var{scheme-file}, @code{gosh} works
35 interactively, i.e. it reads a Scheme expression from the standard input,
36 evaluates it, and prints the result, and repeat that until it reads EOF or
37 is terminated.
38 @c JP
39 Gaucheのインタプリタです。 @var{scheme-file}が与えられなければ、
40 @code{gosh}はインタラクティブに動作します。すなわち、標準入力からScheme式を読み込み、
41 それを評価して結果をプリントするという動作を、EOFを読むか明示的に終了させられるまで
42 続けます。
43 @c COMMON
44
45 @c EN
46 If @code{gosh} is invoked without @var{scheme-file}, but the input
47 is not a terminal, it enters read-eval-print loop but not writes
48 out a prompt while waiting input form. This is useful when you
49 pipe Scheme program into @code{gosh}. You can force this behavior
50 or suppress this behavior by @code{-b} and @code{-i} options.
51 @c JP
52 もし@var{scheme-file}が与えられておらず、しかし入力が端末でない場合、
53 @code{gosh}はread-eval-printループに入りますが、入力待ちの際にプロンプトを
54 表示しません。これはScheme式をパイプで@var{gosh}に処理させる場合に便利です。
55 @code{-b}または@code{-i}オプションでこの動作を強制的にonまたはoffできます。
56 @c COMMON
57
58 @c EN
59 If @var{scheme-file} is specified, @code{gosh} runs it as a
60 Scheme program and exit.
61 @xref{Writing Scheme scripts}, for details.
62 @c JP
63 @var{scheme-file}が与えられた場合、@code{gosh}はそれをSchemeプログラムとして
64 ロードし、終了します。この動作に関しては@ref{Writing Scheme scripts}を参照して
65 下さい。
66 @c COMMON
67 @end deftp
68
69 @menu
70 * Gosh command-line options::
71 * Environment variables::
72 * Windows-specific executable::
73 @end menu
74
75 @node Gosh command-line options, Environment variables, Invoking Gosh, Invoking Gosh
76 @subsection Command-line options
77 @c NODE コマンドラインオプション
78
79 @c EN
80 The following command line options are recognized by @code{gosh}.
81 The first command line argument which doesn't begin with `@minus{}'
82 is recognized as the script file. If you want to specify a file
83 that begins with a minus sign, use a dummy option `@code{--}'.
84 @c JP
85 @code{gosh}には以下のようなコマンドラインオプションがあります。
86 `@minus{}' で始まらない最初のコマンドライン引数がスクリプトファイルと認識されます。
87 スクリプトファイル名が `@minus{}' で始まっている可能性がある場合は、ダミーオプション
88 `@code{--}' をスクリプトファイル名の前に置いて下さい。
89 @c COMMON
90
91 @deftp {Command Option} -I path
92 @c EN
93 Prepends @var{path} to the load path list.
94 You can specify this option more than once to add multiple paths.
95 @c JP
96 @var{path}をロードパスのリストの最初に加えます。このオプションは複数指定できます。
97 @c COMMON
98 @end deftp
99
100 @deftp {Command Option} -A path
101 @c EN
102 Appends @var{path} to the tail of the load path list.
103 You can specify this option more than once to add multiple paths.
104 @c JP
105 @var{path}をロードパスのリストの末尾に加えます。このオプションは複数指定できます。
106 @c COMMON
107 @end deftp
108
109 @deftp {Command Option} -q
110 @c EN
111 Makes @code{gosh} not to load the default initialization file.
112 @c JP
113 @code{gosh}が起動時にシステムの初期化ファイルをロードしないようにします。
114 @c COMMON
115 @end deftp
116
117 @deftp {Command Option} -V
118 @c EN
119 Prints the @code{gosh} version, and various configuration information
120 (SRFI-176). See @code{version-alist} for the details of configuration
121 parameters @pxref{Environment inquiry}.
122 You can control what info to be shown by the environment variable
123 @code{GAUCHE_VERSION_INFO_EXCLUSION} (@pxref{Environment variables}).
124 section below.
125 @c JP
126 @code{gosh}のバージョンおよび様々なコンフィグレーション情報を表示します
127 (SRFI-176)。コンフィグレーション情報については@code{version-alist}を見てください
128 (@ref{Environment inquiry})。
129 どういった情報を表示するかは、環境変数@code{GAUCHE_VERSION_INFO_EXCLUSION}で
130 カスタマイズできます。@ref{Environment variables}参照。
131 @c COMMON
132 @end deftp
133
134 @deftp {Command Option} -v version
135 @c EN
136 If @var{version} is not the running @code{gosh}'s version, execute the
137 specified version of @code{gosh} instead if it is installed.
138 This is useful when you want to invoke specific version of Gauche.
139 Note that @var{version} must be 0.9.6 or later.
140 @c JP
141 @var{version}が実行された@code{gosh}のバージョンでなく、かつ指定されたバージョンの
142 Gaucheがシステムにインストールされていた場合、指定バージョンの@code{gosh}をかわりに起動します。
143 これは、Gaucheのバージョンを特定して実行したい場合に便利です。
144 なお、この機能で指定できる@var{version}は0.9.6かそれ以降のみです。
145 @c COMMON
146
147 @c EN
148 If the specified version isn't installed on the system, @code{gosh} exits
149 with a message. If you add @code{:} before @var{version}, however,
150 @code{gosh} falls back to itself when it can't find the given version.
151 @c JP
152 指定のバージョンのGaucheがシステムにインストールされていない場合、@code{gosh}は
153 メッセージを出して終了します。これを避けたい場合、@var{version}の前に@code{:}を
154 加えると、Gaucheは指定バージョンが見つからない場合は自分自身の実行を続けます。
155 @c COMMON
156
157 @example
158 # Suppose you don't have version 0.9.13 on your machine.
159 $ gosh -v 0.9.13
160 No installed Gauche with version 0.9.13 under /usr/lib/.
161 $ gosh -v :0.9.13
162 WARNING: No installed Gauche with version 0.9.13 under /usr/lib/. Using the current version.
163 gosh$ (gauche-version)
164 "0.9.15"
165 @end example
166 @end deftp
167
168
169 @deftp {Command Option} -u module
170 @c EN
171 Use @var{module}. Before starting execution of @var{scheme-file} or entering
172 the read-eval-print loop, the specified module is @var{use}d, i.e.
173 it is loaded and imported (@xref{Defining and selecting modules}, for details of @code{use}).
174 You can specify this option more than once to use multiple modules.
175 @c JP
176 起動後、インタラクティブなread-eval-printループに入る前、もしくは@var{scheme-file}
177 をロードする前に@var{module}を``use''します。つまりそのモジュールがロードされ
178 インポートされます。(@code{use}の詳細については@ref{Defining and selecting modules}を参照して下さい。)
179 このオプションは複数指定できます。
180 @c COMMON
181 @end deftp
182
183 @deftp {Command Option} -l file
184 @c EN
185 Load @var{file} before starting execution of @var{scheme-file} or entering
186 the read-eval-print loop. The file is loaded in the same way as
187 @code{load} (@pxref{Loading Scheme file}).
188 You can specify this option more than once to load multiple files.
189 @c JP
190 起動後、インタラクティブなread-eval-printループに入る前、もしくは@var{scheme-file}
191 をロードする前に@var{file}をロードします。ロードの詳細については@ref{Loading Scheme file}
192 を参照して下さい。このオプションは複数指定できます。
193 @c COMMON
194 @end deftp
195
196 @deftp {Command Option} -L file
197 @c EN
198 Load @var{file} like @code{-l}, but if @var{file} does not exist,
199 this silently ignores it instead of reporting an error.
200 This option can also be specified multiple times.
201 @c JP
202 @code{-l}オプションと同様に@var{file}をロードしますが、
203 @var{file}が見つからなかった場合はエラーを報告せずに黙って無視します。
204 このオプションも複数指定できます。
205 @c COMMON
206 @end deftp
207
208 @deftp {Command Option} -e scheme-expression
209 @c EN
210 Evaluate @var{scheme-expression}
211 before starting execution of @var{scheme-file} or entering
212 the read-eval-print loop. Evaluation is done in the
213 @var{interaction-environment} (@pxref{Eval and repl}).
214 You can specify this option more than once to evaluate multiple expressions.
215 @c JP
216 起動後、インタラクティブなread-eval-printループに入る前、もしくは@var{scheme-file}
217 をロードする前に@var{scheme-expression}を評価します。評価は
218 @var{interaction-environment}中で行われます(@ref{Eval and repl}参照)。
219 このオプションは複数指定できます。
220 @c COMMON
221 @end deftp
222
223 @deftp {Command Option} -E scheme-expression
224 @c EN
225 Same as -e, except the @var{scheme-expression} is read
226 as if it is surrounded by parenthesis. For example:
227 @c JP
228 オプション-eとほぼ同じですが、@var{scheme-expression}は
229 それが括弧で囲まれているかのように読まれます。
230 このオプションは複数指定できます。例:
231 @c COMMON
232 @example
233 % gosh -umath.const -E"print (sin (* pi/180 15))" -Eexit
234 0.25881904510252074
235 @end example
236 @end deftp
237
238 @deftp {Command Option} -b
239 @c EN
240 Batch. Does not print prompts even if the input is a terminal.
241 @c JP
242 バッチ。入力が端末であってもプロンプトを出さないようにします。
243 @c COMMON
244 @end deftp
245
246 @deftp {Command Option} -i
247 @c EN
248 Interactive. Print prompts even if the input is not a terminal.
249 @c JP
250 インタラクティブ。入力が端末で無くてもプロンプトを出すようにします。
251 @c COMMON
252 @end deftp
253
254 @deftp {Command Option} -m module
255 @c EN
256 When a script file is given,
257 this option makes the module named @var{module} in which
258 the @code{main} procedure is looked for, instead of the @code{user} module.
259 See @ref{Writing Scheme scripts} for the details of executing scripts.
260
261 If the named module doesn't exist after loading the script,
262 an error is signaled.
263
264 This is useful to write a Scheme module that can also be executed
265 as a script.
266 @c JP
267 スクリプトファイルが与えられた場合に、@code{main}手続きを
268 探すモジュールを指定します。デフォルトでは@code{user}モジュールが探されます。
269 スクリプトの実行について詳しくは@ref{Writing Scheme scripts}を見てください。
270
271 @var{module}で指定されたモジュールが、スクリプトファイルのロード後にも
272 存在しない場合は、エラーが報告されます。
273
274 このオプションは、スクリプトとしても使えるようなSchemeモジュールを書く際に便利です。
275 @c COMMON
276 @end deftp
277
278 @deftp {Command Option} -f compiler-option
279 @c EN
280 This option controls compiler and runtime behavior. For now we have
281 following options available:
282 @table @asis
283 @item case-fold
284 Ignore case for symbols. @xref{Case-sensitivity}.
285 @item include-verbose
286 Reports whenever a file is included.
287 Useful to check precisely which files are included in what order.
288 @item load-verbose
289 Reports whenever a file is loaded.
290 Useful to check precisely which files are loaded in what order.
291 @item no-inline
292 Prohibits the compiler from inlining procedures and constants. Equivalent to
293 no-inline-globals, no-inline-locals, no-inline-constants
294 and no-inline-setters combined.
295 @item no-inline-constants
296 Prohibits the compiler from inlining constants.
297 @item no-inline-globals
298 Prohibits the compiler from inlining global procedures.
299 @item no-inline-locals
300 Prohibits the compiler from inlining local procedures.
301 @item no-inline-setters
302 Prohibits the compiler from inlining setters.
303 @item no-lambda-lifting-pass
304 Prohibits the compiler from running lambda-lifting pass.
305 @item no-post-inline-pass
306 Prohibits the compiler from running post-inline optimization pass.
307 @item no-source-info
308 Don't keep source information for debugging. Consumes less memory.
309 @item safe-string-cursors
310 String cursors used on wrong strings will raise an error. This may
311 catch bugs but decreases performance
312 because all cursors will be allocated on heap. @xref{String cursors}.
313 @item test
314 This option allows you to run @code{gosh} when you build it, without
315 installing it. If given, this adds @code{../lib}, @code{../libsrc},
316 and @code{../src}, relative to the place @code{gosh} is, to
317 the load path before loading initialization file.
318 @item warn-legacy-syntax
319 Warns if the reader sees legacy hex-escape syntax in string literals.
320 @xref{Reader lexical mode}.
321 @xref{Case-sensitivity}.
322 @end table
323 @c JP
324 このオプションはコンパイラとランタイムの動作に影響を与えます。
325 今のところ、次のオプションのみが@var{compiler-option}として有効です。
326 @table @asis
327 @item case-fold
328 シンボルの大文字小文字を区別しません。
329 @ref{Case-sensitivity} を参照して下さい。
330 @item include-verbose
331 ファイルがincludeされる時にそれを報告します。
332 正確にどのファイルがどういう順序でincludeされているかを調べるのに便利です。
333 @item load-verbose
334 ファイルがロードされる時にそれを報告します。
335 正確にどのファイルがどういう順序でロードされているかを調べるのに便利です。
336 @item no-inline
337 一切のインライン展開を行いません。このオプションは以下の no-inline-globals、
338 no-inline-locals、no-inline-constants、no-inline-setters
339 を同時に指定したのと等価です。
340 @item no-inline-constants
341 定数のインライン展開を行ないません。
342 @item no-inline-globals
343 大域(global)関数のインライン展開を展開を行ないません。
344 @item no-inline-locals
345 局所(local)関数のインライン展開を展開を行ないません。
346 @item no-inline-setters
347 セッター関数のインライン展開を行いません。
348 @item no-lambda-lifting-pass
349 lambda lifting最適化パスを抑止します。
350 @item no-post-inline-pass
351 インライン展開後に再び最適化パスを走らせるのを抑止します。
352 @item no-source-info
353 デバッグのためのソースファイル情報を保持しません。メモリの使用量は小さくなります。
354 @item safe-string-cursors
355 文字列カーソルをそのカーソルが作られた文字列以外の文字列に使おうとした時に
356 エラーを投げます。バグを検出できますが、文字列カーソルが常にヒープアロケートされる
357 ので性能は低下します。@ref{String cursors}参照。
358 @item test
359 Gaucheをソースツリーからコンパイルしたまま、
360 インストールせずに実行するためのオプションです。
361 このオプションが指定されると、@code{gosh}は初期化ファイルを読む前に、
362 @code{gosh}のあるディレクトリからの相対パスで
363 @code{../lib}、@code{../libsrc}、@code{../src} をロードパスに加えます。
364 @item warn-legacy-syntax
365 文字列リテラル中に古い形式の16進数エスケープ形式があったら警告します。
366 @ref{Reader lexical mode} を参照して下さい。
367 @end table
368 @c COMMON
369 @end deftp
370
371 @deftp {Command Option} -p profiler-option
372 @c EN
373 Turn on the profiler. The following @var{profiler-option} is recognized:
374 @c JP
375 プロファイラを有効にします。以下のような@var{profiler-option}が
376 今のところサポートされています。
377 @c COMMON
378
379 @table @code
380 @item time
381 @c EN
382 Records and reports time spent on function calls and number of times
383 each function is called.
384 @c JP
385 関数中で費された時間と、各関数が呼ばれた回数を記録して報告します。
386 @c COMMON
387 @item load
388 @c EN
389 Records and reports time spent on loading each modules.
390 Useful to tune start-up time of the scripts.
391 (Results are in elapsed time).
392 @c JP
393 各モジュールをロードするのにかかった時間を記録して報告します。
394 スクリプトの起動時間をチューンするのに便利です
395 (実経過時間が報告されます)。
396 @c COMMON
397 @end table
398
399 @c EN
400 See @ref{Using profiler} for the details of the profiler.
401 @c JP
402 詳しくは@ref{Using profiler}を参照して下さい。
403 @c COMMON
404 @end deftp
405
406 @deftp {Command Option} -r standard-revision
407 @c EN
408 Start @code{gosh} with an environment of the specified revision
409 of Scheme standard. Currently only 7 is supported as
410 @var{standar-revision}.
411
412 By default, @code{gosh} starts with @code{user} module, which inherits
413 @code{gauche} module. That means you can use whole Gauche core
414 procedures by default without explicitly declaring it.
415
416 Proper R7RS code always begins with either @code{define-library}
417 or R7RS-style @code{import} form, and Gauche recognizes it and
418 automatically switch to R7RS environments so that R7RS scripts and libraries
419 can be executed by Gauche without special options.
420 However, users who are learning R7RS Scheme may be confused
421 when the initial environment doesn't look like R7RS.
422
423 By giving @code{-r7} option, @code{gosh} starts with @code{r7rs.user} module
424 that extends the @code{r7rs} module, which defines two R7RS forms,
425 @code{import} and @code{define-library}.
426
427 If you invoke @code{gosh} into an interactive REPL mode with @code{-r7} option,
428 all standard R7RS-small libraries (except @code{(scheme r5rs)}) are already
429 imported for your convenience.
430
431 @xref{Library modules - R7RS standard libraries}, for the details on
432 how Gauche supports R7RS.
433
434 (Note: The @code{-r7} option doesn't change reader lexical mode
435 (@pxref{Reader lexical mode}) to @code{strict-r7}. That's because
436 using @code{strict-r7} mode by default prevents many Gauche code
437 from being loaded.)
438 @c JP
439 @code{gosh}を、指定されたリビジョンのScheme標準環境で起動します。
440 現在のバージョンでは@var{standard-revision}として7のみがサポートされます。
441
442 デフォルトでは、@code{gosh}起動時のモジュールは@code{user}モジュールで、
443 これは@code{gauche}モジュールを継承しています。すなわち、特に何も指定しないでも
444 Gaucheのコア関数は全て使えるようになっています。
445
446 正しいR7RSプログラムは常に@code{define-library}フォームか
447 R7RS式の@code{import}フォームで始まり、Gaucheはそれらを見つけると
448 自動的にR7RS環境へと切り替えるので、特になにもしなくても
449 R7RSスクリプトやライブラリを使うことはできます。
450 しかし、R7RS Schemeを勉強中のユーザにとっては、最初に入る環境が
451 R7RSでないと混乱してしまうかもしれません。
452
453 @code{-r7}オプションが与えられると、@code{gosh}は起動時のモジュールを
454 @code{r7rs.user}モジュールにします。これは@code{r7rs}モジュールを継承した
455 もので、@code{import}と@code{define-library}だけが定義されています。
456
457 @code{-r7}をつけた@code{gosh}を対話REPLとして起動した場合は、簡便のために
458 @code{(scheme r5rs)}を除く全てのR7RS-smallライブラリが
459 importされた状態になっています。
460
461 GaucheがR7RSをどのようにサポートしているかの詳細については
462 @ref{Library modules - R7RS standard libraries}を参照してください。
463
464 (註: @code{-r7}オプションは、リーダ字句モードを@code{strict-r7}に
465 替えることはしません。@code{strict-r7}モードをデフォルトにすると、
466 多くのGaucheコードをロードすることができなくなるからです。リーダ字句モードについては
467 @ref{Reader lexical mode}を参照してください。)
468 @c COMMON
469 @end deftp
470
471
472 @deftp {Command Option} @code{--}
473 @c EN
474 When @code{gosh} sees this option, it stops processing the options
475 and takes next command line argument as a script file. It is useful
476 in case if you have a script file that begins with a minus sign,
477 although it is not generally recommended.
478 @c JP
479 このオプションに出会うと、@code{gosh}はオプションの解析を止めて、その次の引数を
480 無条件に@var{scheme-file}であると見倣します。@var{scheme-file}がマイナス記号で
481 始まっている場合に必要です。
482 @c COMMON
483 @end deftp
484
485 @c EN
486 The options -I, -A, -l, -u, -e and -E are processes in the order
487 of appearance. For example, adding a load path by -I affects the
488 -l and -u option after it but not before it.
489 @c JP
490 オプション-I, -A, -l, -u, -e 及び -E は、それらがコマンドライン引数として
491 出現した順に処理されます。例えば、-Iにより追加されるロードパスは
492 それ以降の-lや-uオプションに影響を与えますが、それ以前のものには影響を
493 与えません。
494 @c COMMON
495
496 @node Environment variables, Windows-specific executable, Gosh command-line options, Invoking Gosh
497 @subsection Environment variables
498 @c NODE 環境変数
499
500 @c EN
501 The following environment variables are recognized:
502 @c JP
503 以下の環境変数を認識します。
504 @c COMMON
505
506 @deftp {Environment variable} GAUCHE_AVAILABLE_PROCESSORS
507 @c EN
508 You can get the number of system's processors by
509 @code{sys-available-processors} (@pxref{Environment inquiry});
510 libraries/programs may use this info to optimize number of
511 parallel threads. But you might change that, for testing
512 and benchmarking---e.g. a program automatically uses
513 8 threads if there are 8 cores, but you might want to run it
514 with 1, 2, 4 threads as well to see the effect of parallelization.
515 This environment variable overrides
516 the return value of @code{sys-available-processors}.
517 @c JP
518 @code{sys-available-processors} でシステムのプロセッサ数を
519 取得できます(@ref{Environment inquiry}参照)。
520 ライブラリやプログラムの中には、その数に基づいて並行に走るスレッド数を
521 調整するものがあります。けれども、テストやベンチマークでその数を
522 変えたいと思うことがあるかもしれません。例えば、8コア上では自動的に
523 8スレッド使うプログラムがあったとして、並列化の効果を見るためにその
524 プログラムを1,2,4スレッドで走らせてベンチマークを取る、といった場合です。
525 この環境変数は、@code{sys-available-processors}が返す値を上書きします。
526 @c COMMON
527 @end deftp
528
529 @deftp {Environment variable} GAUCHE_CHECK_UNDEFINED_TEST
530 @c EN
531 Warn if @code{#<undef>} is used in the test expression of branch.
532
533 In boolean context, @code{#<undef>} counts true. It is also
534 often the case that a procedure returns @code{#<undef>} when
535 the return value doesn't matter, and you shouldn't rely on
536 the value that is supposed not to matter--the procedure may
537 change the return value in future (which should be ok, since
538 the value shouldn't have mattered), which can cause unintentional
539 and hard-to-track bugs.
540 @xref{Undefined values}, for the details.
541
542 We strongly recommend users to turn on this warning. In future,
543 we plan to make this default.
544 @c JP
545 @code{#<undef>}が条件式のテスト式に使われた場合に警告を出します。
546
547 真偽値判定では@code{#<undef>}は真とみなされます。しかし、
548 @code{#<undef>}を返す手続きはしばしば、
549 「戻り値に意味はない」ことを示すためにそれを返しています。
550 戻り値に意味がないなら、その値に依存したコードを書くべきではありません。
551 もし、手続きが将来、もともと意味が無いのだからと戻り値を変えた場合に、
552 @code{#<undef>}に依存してたコードは壊れる可能性があります。
553 詳しくは@ref{Undefined values}を参照してください。
554
555 この機能はなるべくONにしておくようにお勧めします。
556 将来はデフォルトで警告を出すようにする予定です。
557 @c COMMON
558 @end deftp
559
560
561 @deftp {Environment variable} GAUCHE_DYNLOAD_PATH
562 @c EN
563 You can specify additional load paths for dynamically loaded
564 objects by this environment variable, delimiting the paths by '@code{:}'.
565 The paths are appended before the system default load paths.
566
567 @xref{Loading dynamic library}, for the details of how Gauche
568 finds dynamically loadable objects.
569 @c JP
570 この変数によって、動的にロードするオブジェクト用の追加ロードパスを
571 指定できます。パスは '@code{:}' で区切ります。
572 この変数によって指定されたパスはシステムのデフォルトのロードパスの前に
573 連結されます。
574
575 Gaucheが動的にロードするオブジェクトファイルを探す方法については
576 @ref{Loading dynamic library}を参照してください。
577 @c COMMON
578 @end deftp
579
580 @deftp {Environment variable} GAUCHE_EDITOR
581 @deftpx {Environment variable} EDITOR
582 @c EN
583 This is used by @code{ed} procedure in @code{gauche.interactive} module.
584 @xref{Interactive session}, for the details.
585 @c JP
586 これは@code{gauche.interactive}モジュールの@code{ed}手続きで使われます。
587 詳しくは@ref{Interactive session}を参照してください。
588 @c COMMON
589 @end deftp
590
591 @deftp {Environment variable} GAUCHE_HISTORY_FILE
592 @c EN
593 Specifies the filename where the REPL history is saved.
594 If this environment variable is not set, history is saved
595 in @file{~/.gosh_history}. If this environment variable
596 is set but an empty string, history isn't saved.
597 If the process is suid/sgid-ed, history won't be saved.
598 @c JP
599 REPLのヒストリがセーブされるファイル名を指定します。
600 この環境変数が定義されていなければ、ヒストリは@file{~/.gosh_history}にセーブされます。
601 この環境変数が定義されており、しかし空文字列だった場合はヒストリはセーブされません。
602 (また、プロセスがsuid/sgidされている場合もヒストリは保存されません)。
603 @c COMMON
604 @end deftp
605
606 @deftp {Environment variable} GAUCHE_KEYWORD_DISJOINT
607 @deftpx {Environment variable} GAUCHE_KEYWORD_IS_SYMBOL
608 @c EN
609 These two environment variables affect whether keywords are treated
610 as symbols or not. @xref{Keywords}, for the details.
611 @c JP
612 この二つの環境変数は、キーワードがシンボルとして扱われるかどうかに影響します。
613 詳しくは@ref{Keywords}を参照してください。
614 @c COMMON
615 @end deftp
616
617 @deftp {Environment variable} GAUCHE_LEGACY_DEFINE
618 @c EN
619 Make the behavior of toplevel @code{define} the same as
620 0.9.8 and before.
621 It allows certain legacy programs that aren't valid R7RS.
622 @xref{Into the Scheme-Verse}, for the details.
623 @c JP
624 トップレベルの@code{define}の振る舞いを0.9.8およびそれ以前のものに
625 合わせます。これは、厳密にはR7RSに従わない、古いコードを走らせる必要が
626 ある場合に使ってください。詳しくは
627 @ref{Into the Scheme-Verse}参照。
628 @c COMMON
629 @end deftp
630
631 @deftp {Environment variable} GAUCHE_LOAD_PATH
632 @c EN
633 You can specify additional load paths by this environment
634 variable, delimiting the paths by '@code{:}'.
635 The paths are appended before the system default load paths.
636
637 @xref{Loading Scheme file}, for the details of how Gauche finds
638 files to load.
639 @c JP
640 この環境変数によって、追加するロードパスを指定できます。
641 パスは '@code{:}' で区切ります。
642 この変数によって指定されたパスはシステムのデフォルトのロードパスの前に
643 連結されます。
644
645 GaucheがロードするSchemeファイルを見つける方法について詳しくは
646 @ref{Loading Scheme file}を参照してください。
647 @c COMMON
648 @end deftp
649
650 @deftp {Environment variable} GAUCHE_MUTABLE_LITERALS
651 @c EN
652 Allow literal lists and vectors to be mutated. Such code isn't a
653 valid Scheme program and causes an error,
654 but Gauche didn't enforce the restriction
655 on 0.9.9 and before, so some legacy code may accidentally mutates
656 literals. Set this environment variables to run such old programs.
657 @xref{Literals}, for the details.
658 @c JP
659 リテラルリストとリテラルベクタの改変を許します。
660 そういったコードは正しいSchemeプログラムではなく、今のGaucheはエラーを投げますが、
661 0.9.9とそれ以前のバージョンではリテラルリストとリテラルベクタの変更はチェックされて
662 いませんでした。うっかりリテラルを変更してしまっている古いコードを走らせたい場合のみ
663 この環境変数をセットしてください。詳しくは@ref{Literals}参照。
664 @c COMMON
665 @end deftp
666
667 @deftp {Environment variable} GAUCHE_NO_READ_EDIT
668 @c EN
669 Disable line-editor on REPL prompt, even the terminal is capable.
670 You can also turn it off with @code{-fno-read-edit} command-line option,
671 or @code{,edit off} toplevel commands during REPL session.
672 @xref{Interactive development}, for the details of line editing.
673 @c JP
674 REPLプロンプトでの行編集機能をオフにします。
675 行編集機能はまた、@code{-fno-read-edit}コマンドラインオプションや、
676 REPLセッション中の @code{,edit off} トップレベルコマンドでも切ることができます。
677 詳しくは@ref{Interactive development}を参照してください。
678 @c COMMON
679 @end deftp
680
681 @deftp {Environment variable} GAUCHE_QUASIRENAME_MODE
682 @c EN
683 This affects @code{quasirename} behavior, to keep the backward
684 compatibility with 0.9.7 and before.
685 @xref{Explicit-renaming macro transformer}, for the details.
686 @c JP
687 これは@code{quasirename}の振る舞いに影響を与え、
688 0.9.7以前との互換性のために使われます。詳しくは
689 @ref{Explicit-renaming macro transformer}を参照してください。
690 @c COMMON
691 @end deftp
692
693
694 @deftp {Environment variable} GAUCHE_REPL_NO_PPRINT
695 @c EN
696 This is used by @code{gauche.interactive} module to suppress
697 pretty-printing on REPL prompt.
698 @xref{Interactive development}, for the details.
699 @c JP
700 これはREPLプロンプトでプリティプリントを抑制するために
701 @code{gauche.interactive}で使われます。
702 詳しくは@ref{Interactive development}を参照してください。
703 @c COMMON
704 @end deftp
705
706 @deftp {Environment variable} GAUCHE_SUPPRESS_WARNING
707 @c EN
708 Suppress system warnings (@code{WARNING: ...}). Not generally recommended;
709 use only if you absolutely need to.
710 @c JP
711 システムの警告(@code{WARNING: ...})を抑止します。気軽に使うべきではありません。
712 どうしても必要な場合のみ使ってください。
713 @c COMMON
714 @end deftp
715
716 @deftp {Environment variable} GAUCHE_TEST_RECORD_FILE
717 @c EN
718 This is used by @code{gauche.test} module (@pxref{Unit testing}).
719 If defined, names a file the test processes
720 keep the total statistics.
721 @c JP
722 @code{gauche.test}モジュールで使われます(@ref{Unit testing}参照)。
723 定義されていた場合、その値を名前とするファイルにテストの統計が記録されます。
724 @c COMMON
725 @end deftp
726
727 @deftp {Environment variable} GAUCHE_TEST_REPORT_ERROR
728 @c EN
729 This is used by @code{gauche.test} module (@pxref{Unit testing}).
730 If defined, reports stack trace to stderr
731 when the test thunk raises an error (even when it is expected).
732 Useful for diagnosis of unexpected errors.
733 @c JP
734 @code{gauche.test}モジュールで使われます(@ref{Unit testing}参照)。
735 定義されていた場合、テストのthunkがエラーを報告した場合に、
736 スタックトレースを標準エラー出力に表示します
737 (エラーがもともと期待されているテストでも出力されます)。
738 予想外のエラー発生の原因を調べるのに便利です。
739 @c COMMON
740 @end deftp
741
742 @deftp {Environment variable} GAUCHE_VERSION_INFO_EXCLSION
743 @c EN
744 The value must be a comma-separated keys in @code{version-alist}
745 (@pxref{Environment inquiry}).
746 The keys listed here are excluded from the output of @code{gosh -V}.
747 For example, the following setting omits @code{scheme.path} and
748 @code{build.configure} from output of @code{gosh -V}. Those values
749 may contain username and/or project names, and there may be cases
750 when you don't want make them to be public accidentally, by attaching
751 output of @code{gosh -V} to a bug report or something.
752 @c JP
753 値は@code{version-alist}に現れるキーをコンマ区切りで並べたものです
754 (@ref{Environment inquiry}参照)。ここに挙げられたキーは、@code{gosh -V}
755 の出力から除外されます。例えば次の設定は、@code{gosh -V}の出力に
756 @code{scheme.path}と@code{build.configure}を含めません。
757 これらの値はユーザ名やプロジェクト名を含んでいる場合がありますが、
758 バグレポート等に@code{gosh -V}の結果を含める時に、
759 それらをうっかり公開してしまわないようにしたい、という場合などに便利です。
760 @c COMMON
761 @example
762 GAUCHE_VERSION_INFO_EXCLUSION=scheme.path,build.configure
763 @end example
764 @end deftp
765
766 @deftp {Environment variable} TMP
767 @deftpx {Environment variable} TMPDIR
768 @deftpx {Environment variable} TEMP
769 @deftpx {Environment variable} USERPROFILE
770 @c EN
771 These may affect the return value of @code{sys-tmpdir}.
772 Different environment variables may be used on different platforms.
773 @xref{Pathnames}, for the details.
774 @c JP
775 これらは@code{sys-tmpdir}の返り値に影響を与えます。プラットフォームによって
776 参照される環境変数は異なります。@ref{Pathnames}を参照してください。
777 @c COMMON
778 @end deftp
779
780 @node Windows-specific executable, , Environment variables, Invoking Gosh
781 @subsection Windows-specific executable
782 @c NODE Windows特有の実行ファイル
783
784 @c EN
785 On Windows-native platforms (mingw), two interpreter executables are
786 installed. @code{gosh.exe} is compiled as a Windows console
787 application and works just like ordinary @code{gosh}; that is,
788 it primarily uses standard i/o for communication.
789 Another executable, @code{gosh-noconsole.exe}, is compiled
790 as a Windows no-console (GUI) application. It is not attached
791 to a console when it is started. Its standard input is connected
792 to the @code{NUL} device. Its standard output and standard error
793 output are special ports which open a new console when something
794 is written to them for the first time. (NB: This magic only works
795 for output via Scheme ports; direct output from low-level C libraries
796 will be discarded.)
797 @c JP
798 Windowsネイティブ環境(mingw)では、インタプリタとしてふたつの
799 実行ファイルがインストールされます。
800 @code{gosh.exe}はWindowsコンソールアプリケーションとしてコンパイルされ、
801 普通の@code{gosh}のように、標準入出力を第一の通信手段とします。
802 もう一つの実行ファイル@code{gosh-noconsole.exe}はWindows非コンソールアプリケーション
803 としてコンパイルされています。こちらは起動時にコンソールに接続されません。
804 標準入力は@code{NUL}デバイスに接続されます。標準出力と標準エラー出力は
805 特殊なポートに接続され、最初に書き込みがあった時点で新たなコンソールが作られて
806 出力されます。(このトリックはSchemeポート経由の出力のみで動きます。
807 低レベルのCライブラリが標準出力や標準エラー出力に直接書き出したデータは捨てられます)。
808 @c COMMON
809
810 @c EN
811 The main purpose of @code{gosh-noconsole.exe} is for Windows
812 scripting. If a Scheme script were associated to @code{gosh.exe}
813 and invoked from Explorer, it would always open a new
814 console window, which is extremely annoying.
815 If you associate Scheme scripts to @code{gosh-noconsole.exe} instead,
816 you can avoid console from popping up.
817 @c JP
818 @code{gosh-noconsole.exe}の目的は、Windows上でのスクリプティングです。
819 Schemeスクリプトがもし@code{gosh.exe}に関連付けられていたとしたら、
820 Explorerからそのスクリプトを起動するたびに、
821 必ず新しいコンソールウィンドウが開くので非常に煩わしいです。
822 Schemeスクリプトを@code{gosh-noconsole.exe}に
823 関連づけておけば、この煩わしいコンソールの出現を抑制できます。
824 @c COMMON
825
826 @c EN
827 If you're using the official Windows installer, Scheme scripts
828 (@file{*.scm}) have already associated to @code{gosh-noconsole.exe}
829 and you can invoke them by double-clicking on Explorer.
830 Check out some examples under @file{C:\Program Files\Gauche\examples}.
831 @c JP
832 Windows版のオフィシャルのインストーラを使ってGaucheをインストールしたなら、
833 Schemeスクリプト(@file{*.scm})は既に@code{gosh-noconsole.exe}に
834 関連づけられているので、ExplorerからSchemeスクリプトをダブルクリックすれば
835 Schemeプログラムを走らせることができます。
836 @file{C:\Program Files\Gauche\examples}の下にいくつかサンプルが
837 あります
838 @c COMMON
839
840 @c ----------------------------------------------------------------------
841 @node Interactive development, Writing Scheme scripts, Invoking Gosh, Programming in Gauche
842 @section Interactive development
843 @c NODE インタラクティブな開発
844
845 @c EN
846 When @code{gosh} is invoked without any script files,
847 it goes into interactive read-eval-print loop (REPL).
848 @c JP
849 スクリプトファイルが与えられなかった場合、
850 @code{gosh}はインタラクティブなread-eval-printループ(REPL)に入ります。
851 @c COMMON
852
853 @c EN
854 To exit the interpreter, type EOF (usually Control-D in Unix terminals)
855 or evaluate @code{(exit)}.
856 @c JP
857 インタプリタを終了するには、EOF文字(Unix端末では通常Control-D)をタイプするか、
858 @code{(exit)}を評価します。
859 @c COMMON
860
861 @c EN
862 In the interactive session, @code{gosh} loads and
863 imports @code{gauche.interactive}
864 module (@pxref{Interactive session}) into @code{user} module, for the
865 convenience. Also, if there's a file @file{.gaucherc} under
866 the user's home directory.
867 You may put settings there that would help interactive debugging.
868 (As of Gauche release 0.7.3,
869 @file{.gaucherc} is no longer loaded when @code{gosh} is run
870 in script mode.)
871
872 Note that @file{.gaucherc} is always loaded in the @code{user} module,
873 even if @code{gosh} is invoked with @code{-r7} option. The file
874 itself is a Gauche-specific feature, so you don't need to consider
875 portability in it.
876 @c JP
877 インタラクティブセッションでは、@code{gosh}は
878 @code{gauche.interactive}モジュールをロードして@code{user}モジュールにインポートします
879 (@ref{Interactive session}参照)。
880 また、ユーザーのホームディレクトリに@file{.gaucherc}という
881 ファイルがあればそれもロードされます。
882 インタラクティブデバッグに便利な設定をそこに書いておくことができます。
883 (Gauche release 0.7.3から、@file{.gaucherc}はgoshがスクリプトモードで
884 起動された時は読まれなくなりました。)
885
886 @code{.gaucherc}は常に@code{user}モジュールへとロードされます
887 (@code{gosh}が@code{-r7}オプションつきで起動されていてもそうです)。
888 @code{.gaucherc}を自動で読み込む、という機能自体がGauche特有の機能ですから、
889 そこでポータビリティを考慮する必要はないわけです。
890 @c COMMON
891
892 @c EN
893 I recommend you to run @code{gosh} inside Emacs, for it has
894 rich features useful to interact with internal Scheme process.
895 Put the following line to your @file{.emacs} file:
896 @example
897 (setq scheme-program-name "gosh -i")
898 @end example
899 And you can run @code{gosh} by @key{M-x run-scheme}.
900 @c JP
901 @code{gosh}をEmacs内部で走らせることをお勧めします。
902 EmacsはSchemeサブプロセスを操作するための豊富な機能を持っています。
903 次の行を@file{.emacs}に加えておくと、@key{M-x run-scheme} で
904 Emacsのバッファ内で@code{gosh}が走ります。
905 @example
906 (setq scheme-program-name "gosh -i")
907 @end example
908 @c COMMON
909
910 @c EN
911 If you run @code{gosh} in the terminal with capability of cursor control,
912 a basic line-editing feature is available in the REPL session.
913 @xref{Input editing}, for the details.
914 @c JP
915 カーソル制御可能な端末で@code{gosh}を走らせた場合、
916 REPLセッションで簡単な行編集が使えます。
917 詳しくは@ref{Input editing}を参照してください。
918 @c COMMON
919
920 @c EN
921 If you want to use multibyte characters in the interaction,
922 make sure your terminal's settings is in sync with @code{gosh}'s
923 internal character encodings.
924 @c JP
925 対話環境でマルチバイト文字を使う場合は、端末の文字エンコーディングを@code{gosh}の
926 内部エンコーディングと合わせるようにして下さい。
927 @c COMMON
928
929 @menu
930 * Working in REPL::
931 * Input editing::
932 @end menu
933
934 @node Working in REPL, Input editing, Interactive development, Interactive development
935 @subsection Working in REPL
936 @c NODE REPLでの開発
937
938 @c EN
939 When you enter REPL, Gauche prompts you to enter a Scheme expression:
940 @c JP
941 REPLに入ると、Gaucheはプロンプトを出してScheme式の入力を待ちます。
942 @c COMMON
943
944 @example
945 gosh>
946 @end example
947
948 @c EN
949 (If you enable input editing, the prompt shows @code{gosh$} instead
950 of @code{gosh>}. @xref{Input editing}, for the details.)
951 @c JP
952 (入力編集機能をオンにしている場合は、プロンプトが@code{gosh>}ではなく
953 @code{gosh$}になります。詳しくは@ref{Input editing}を参照してください。)
954 @c COMMON
955
956 @c EN
957 After you complete a Scheme expression and type ENTER,
958 the result of evaluation is printed.
959 @c JP
960 完全なScheme式を入力してENTERをタイプすると、そのS式の評価結果が表示されます。
961 @c COMMON
962
963 @example
964 gosh> @i{(+ 1 2)}
965 3
966 gosh>
967 @end example
968
969 @c EN
970 The REPL session binds the last three results of evaluation
971 in the global variables @code{*1}, @code{*2} and @code{*3}.
972 You can use the previous results via those history variables
973 in subsequent expressions.
974 @c JP
975 REPLセッションは、過去3回分の評価結果をグローバル変数
976 @code{*1}、@code{*2}、@code{*3} に束縛します。これらのヒストリ変数を
977 使って、以前の結果を後続の式の中で使えます。
978 @c COMMON
979
980 @example
981 gosh> @i{*1}
982 3
983 gosh> @i{(+ *2 3)}
984 6
985 @end example
986
987 @c EN
988 If the Scheme expression yields multiple values
989 (@pxref{Multiple values}), they are printed one by one.
990 @c JP
991 Scheme式が複数の値を返した場合
992 (@ref{Multiple values}参照)は、各値が順に表示されます。
993 @c COMMON
994
995 @example
996 gosh> @i{(min&max 1 -1 8 3)}
997 -1
998 8
999 gosh>
1000 @end example
1001
1002 @c EN
1003 The history variable @code{*1}, @code{*2} and @code{*3} only
1004 binds the first value. A list of all values are bound to
1005 @code{*1+}, @code{*2+} and @code{*3+}.
1006 @c JP
1007 式が多値を返しても、変数@code{*1}、@code{*2}、@code{*3}
1008 に束縛されるのは最初の値のみです。しかし別のグローバル変数
1009 @code{*1+}、@code{*2+}、@code{*3+}に、全ての値をリストにしたものが
1010 束縛されています。
1011 @c COMMON
1012
1013 @example
1014 gosh> @i{*1}
1015 -1
1016 gosh> @i{*2+}
1017 (-1 8)
1018 @end example
1019
1020 @c EN
1021 (Note that, when you evaluate @code{*1} in the above example, the
1022 history is shifted---so you need to use @code{*2+} to refer to the
1023 result of @code{(min&max 1 -1 8 3)}.)
1024 @c JP
1025 (上の例で、@code{*1}を評価した時点でヒストリがひとつずれてしまっていることに
1026 注意してください。@code{(min&max 1 -1 8 3)}の結果を見るためには
1027 @code{*2+}を参照する必要があります。)
1028 @c COMMON
1029
1030 @c EN
1031 The @code{*history} procedure shows the value of history variables:
1032 @c JP
1033 手続き@code{*history}はヒストリ変数の値を表示します。
1034 @c COMMON
1035
1036 @example
1037 gosh> @i{(*history)}
1038 *1: (-1 8)
1039 *2: -1
1040 *3: -1
1041 gosh>
1042 @end example
1043
1044 @c EN
1045 As a special case, if an evaluation yields zero values, history
1046 isn't updated. The @code{*history} procedure returns
1047 no values, so merely looking at the history won't change the history
1048 itself.
1049 @c JP
1050 特別な場合として、式の評価がゼロ個の値を返した場合は、ヒストリ変数は更新されません。
1051 @code{*history}手続きはゼロ個の値を返すので、ヒストリを見るだけでヒストリが
1052 進んでしまうということはありません。
1053 @c COMMON
1054
1055 @example
1056 gosh> @i{(*history)}
1057 *1: (-1 8)
1058 *2: -1
1059 *3: -1
1060 gosh> (values)
1061 gosh> @i{(*history)}
1062 *1: (-1 8)
1063 *2: -1
1064 *3: -1
1065 @end example
1066
1067
1068 @c EN
1069 Finally, a global variable @code{*e} is bound to the last uncaught
1070 error condition object.
1071 @c JP
1072 最後に、評価途中で捕捉されないエラーが発生した場合は、エラーコンディションオブジェクトが
1073 グローバル変数@code{*e}に束縛されます。
1074 @c COMMON
1075
1076 @example
1077 gosh> @i{(filter odd? '(1 2 x 4 5))}
1078 *** ERROR: integer required, but got x
1079 Stack Trace:
1080 _______________________________________
1081 0 (eval expr env)
1082 At line 173 of "/usr/share/gauche-0.9/0.9.3.3/lib/gauche/interactive.scm"
1083 gosh> @i{*e}
1084 #<error "integer required, but got x">
1085 @end example
1086
1087 @c EN
1088 (The error stack trace may differ depending on your installation.)
1089 @c JP
1090 (エラースタックトレースの表示はインストールの状況によって異なる場合があります。)
1091 @c COMMON
1092
1093 @c EN
1094 In REPL prompt, you can also enter special @emph{top-level commands}
1095 for common tasks. Top-level commands are not Scheme
1096 expressions, not even S-expressions.
1097 They work like traditional line-oriented shell commands instead.
1098 @c JP
1099 REPLプロンプトではまた、よくある仕事のために、特別な@emph{トップレベルコマンド}を
1100 入力することもできます。トップレベルコマンドはScheme式ではありませんし、S式でさえ
1101 ありません。むしろ、伝統的な行指向のシェルコマンドのように動作します。
1102 @c COMMON
1103
1104 @c EN
1105 Top-level commands are prefixed by comma to be distinguished from
1106 ordinary Scheme expressions. To see what commands are available,
1107 just type @code{,help} and return.
1108 @c JP
1109 トップレベルコマンドは通常のScheme式と区別するために、コンマで始まります。
1110 どういったコマンドが使えるかを見るには、@code{,help}とタイプしてリターンを
1111 入力してみてください。
1112 @c COMMON
1113
1114 @example
1115 gosh> ,help
1116 You're in REPL (read-eval-print-loop) of Gauche shell.
1117 Type a Scheme expression to evaluate.
1118 A word preceded with comma has special meaning. Type ,help <cmd>
1119 to see the detailed help for <cmd>.
1120 Commands can be abbreviated as far as it is not ambiguous.
1121
1122 ,apropos|a Show the names of global bindings that match the regexp.
1123 ,cd Change the current directory.
1124 ,describe|d Describe the object.
1125 ,help|h Show the help message of the command.
1126 ,history Show REPL history.
1127 ,info|doc Show info document for an entry of NAME, or search entries by REGEXP.
1128 ,load|l Load the specified file.
1129 ,print-all|pa
1130 Print previous result (*1) without abbreviation.
1131 ,print-mode|pm
1132 View/set print-mode of REPL.
1133 ,pwd Print working directory.
1134 ,reload|r Reload the specified module, using gauche.reload.
1135 ,sh Run command via shell.
1136 ,source Show source code of the procedure if it's available.
1137 ,use|u Use the specified module. Same as (use module option ...).
1138 @end example
1139
1140 @c EN
1141 To see the help of each individual commands, give the command name
1142 (without comma) to the @code{help} command:
1143 @c JP
1144 それぞれのコマンド特有のヘルプを見るには、コンマを含まないコマンド名を
1145 @code{help}コマンドに与えてください。
1146 @c COMMON
1147
1148 @example
1149 gosh> ,help d
1150 Usage: d|describe [object]
1151 Describe the object.
1152 Without arguments, describe the last REPL result.
1153 @end example
1154
1155 @c EN
1156 The @code{,d} (or @code{,describe}) top-level command describes
1157 the given Scheme object
1158 or the last result if no object is given. Let's try some:
1159 @c JP
1160 @code{,d} (あるいは@code{,describe})トップレベルコマンドは与えられたSchemeオブジェクト、
1161 または何もオブジェクトが与えられなければ直前の結果のオブジェクトについて、
1162 その説明を表示します。ちょっと試してみましょう。
1163 @c COMMON
1164
1165 @example
1166 gosh> (sys-stat "/home")
1167 #<<sys-stat> 0x2d6adc0>
1168 gosh> ,d
1169 #<<sys-stat> 0x2d6adc0> is an instance of class <sys-stat>
1170 slots:
1171 type : directory
1172 perm : 493
1173 mode : 16877
1174 ino : 2
1175 dev : 2081
1176 rdev : 0
1177 nlink : 9
1178 uid : 0
1179 gid : 0
1180 size : 208
1181 atime : 1459468837
1182 mtime : 1401239524
1183 ctime : 1401239524
1184 @end example
1185
1186 @c EN
1187 In the above example, first we evaluated @code{(sys-stat "/home")},
1188 which returns @code{<sys-stat>} object. The subsequent @code{,d} top-level
1189 command describes the returned @code{<sys-stat>} object.
1190 @c JP
1191 上の例では、まず@code{(sys-stat "/home")}を評価して、結果として
1192 @code{<sys-stat>}オブジェクトが返ってきました。続く@code{,d}コマンドによって
1193 その@code{<sys-stat>}オブジェクトの詳細が表示されています。
1194 @c COMMON
1195
1196 @c EN
1197 The description depends on the type of objects. Some types of
1198 objects shows extra information. If you describe an exact integer,
1199 it shows alternative interpretations of the number:
1200 @c JP
1201 表示される情報はオブジェクトの型に依存します。型によっては、追加の情報が
1202 表示される場合もあります。例えば正確な整数を@code{describe}すると、
1203 いくつかの異なる解釈が示されます。
1204 @c COMMON
1205
1206 @example
1207 gosh> ,d 1401239524
1208 1401239524 is an instance of class <integer>
1209 (#x538537e4, ~ 1.3Gi, 2014-05-28T01:12:04Z as unix-time)
1210 gosh> ,d 48
1211 48 is an instance of class <integer>
1212 (#x30, #\0 as char, 1970-01-01T00:00:48Z as unix-time)
1213 @end example
1214
1215 @c EN
1216 If you describe a symbol, its known bindings is shown.
1217 @c JP
1218 シンボルを@code{describe}すると、分かっている束縛が示されます。
1219 @c COMMON
1220
1221 @example
1222 gosh> ,d 'filter
1223 filter is an instance of class <symbol>
1224 Known bindings for variable filter:
1225 In module `gauche':
1226 #<closure (filter pred lis)>
1227 In module `gauche.collection':
1228 #<generic filter (2)>
1229 @end example
1230
1231 @c EN
1232 If you describe a procedure, and its source code location is known,
1233 that is also shown (see the @code{Defined at...} line):
1234 @c JP
1235 手続きを@code{describe}した場合、もし分かっていればそのソースコード上の
1236 場所も表示されます(@code{Defined at ...}の行):
1237 @c COMMON
1238
1239 @example
1240 gosh> ,d string-interpolate
1241 #<closure (string-interpolate str :optional (legacy? #f))> is an
1242 instance of class <procedure>
1243 Defined at "../lib/gauche/interpolate.scm":64
1244 slots:
1245 required : 1
1246 optional : #t
1247 optcount : 1
1248 locked : #f
1249 currying : #f
1250 constant : #f
1251 info : (string-interpolate str :optional (legacy? #f))
1252 setter : #f
1253 @end example
1254
1255 @c EN
1256 Let's see a couple of other top-level commands. The @code{,info}
1257 command shows the manual entry of the given procedure, variable, syntax,
1258 module or a class. (The text is searched from the installed
1259 info document of Gauche. If you get an error, check if the
1260 info document is properly installed.)
1261 @c JP
1262 他のトップレベルコマンドも見てみましょう。@code{,info}コマンドは
1263 手続き、変数、構文、モジュールもしくはクラス名が与えられると、そのドキュメントを
1264 表示します。(テキストはシステムにインストールされたGaucheのinfoドキュメントから
1265 検索されます。もしエラーが出た場合は、infoドキュメントが正しくインストール
1266 されているかどうか確認してください。)
1267 @c COMMON
1268
1269 @example
1270 gosh> ,info append
1271 -- Function: append list ...
1272 [R7RS base] Returns a list consisting of the elements of the first
1273 LIST followed by the elements of the other lists. The resulting
1274 list is always newly allocated, except that it shares structure
1275 with the last list argument. The last argument may actually be any
1276 object; an improper list results if the last argument is not a
1277 proper list.
1278
1279 gosh> ,info srfi.19
1280 -- Module: srfi.19
1281 This SRFI defines various representations of time and date, and
1282 conversion methods among them.
1283
1284 On Gauche, time object is supported natively by '<time>' class
1285 (*note Time::). Date object is supported by '<date>' class
1286 described below.
1287
1288 gosh> ,info <list>
1289 -- Builtin Class: <list>
1290 An abstract class represents lists. A parent class of '<null>' and
1291 '<pair>'. Inherits '<sequence>'.
1292
1293 Note that a circular list is also an instance of the '<list>'
1294 class, while 'list?' returns false on the circular lists and dotted
1295 lists.
1296 (use srfi.1)
1297 (list? (circular-list 1 2)) => #f
1298 (is-a? (circular-list 1 2) <list>) => #t
1299 @end example
1300
1301 @c EN
1302 You can also give a regexp pattern to @code{,info} command
1303 (@pxref{Regular expressions}).
1304 It shows the entries in the document that match the pattern.
1305 @c JP
1306 また、@code{,info}コマンドに正規表現のパターンを与えることもできます
1307 (@ref{Regular expressions}参照)。
1308 その場合、パターンにマッチするドキュメントの項目の一覧が表示されます。
1309 @c COMMON
1310
1311 @example
1312 gosh> ,info #/^string-.*\?/
1313 string-ci<=? Full string case conversion:44
1314 String comparison:19
1315 string-ci<? Full string case conversion:43
1316 String comparison:18
1317 string-ci=? Full string case conversion:42
1318 String comparison:17
1319 string-ci>=? Full string case conversion:46
1320 String comparison:21
1321 string-ci>? Full string case conversion:45
1322 String comparison:20
1323 string-immutable? String Predicates:9
1324 string-incomplete? String Predicates:12
1325 string-null? SRFI-13 String predicates:6
1326 string-prefix-ci? SRFI-13 String prefixes & suffixes:28
1327 string-prefix? SRFI-13 String prefixes & suffixes:26
1328 string-suffix-ci? SRFI-13 String prefixes & suffixes:29
1329 string-suffix? SRFI-13 String prefixes & suffixes:27
1330 @end example
1331
1332 @c EN
1333 The @code{,a} command (or @code{,apropos}) shows the global identifiers
1334 matches the given name or regexp:
1335 @c JP
1336 @code{,a} (または@code{,apropos}) は、与えられた名前や正規表現に
1337 マッチするグローバルな識別子を表示します。
1338 @c COMMON
1339
1340 @example
1341 gosh> ,a filter
1342 filter (gauche)
1343 filter! (gauche)
1344 filter$ (gauche)
1345 filter-map (gauche)
1346 @end example
1347
1348 @c EN
1349 Note: The @code{apropos} command looks for symbols from the
1350 current process---that is, it only shows names that have been loaded
1351 and imported.
1352 But it also mean it can show any name as far as it exists in the
1353 current process, regardless of whether it's a documented API or an
1354 internal entry.
1355
1356 On the other hand, the @code{info}
1357 command searches info document, regardless of the named entity
1358 has loaded into the current process or not. It doesn't show
1359 undocumented APIs.
1360
1361 You can think that @code{apropos} is an introspection tool,
1362 while @code{info} is a document browsing tool.
1363 @c JP
1364 註: @code{apropos}コマンドは現在のプロセス中から名前を探します。
1365 つまり、既にロードされインポートされた名前しか表示しません。
1366 それは同時に、ロードされてさえいれば、ドキュメントのある公式なAPIか
1367 内部的な非公式なエントリかにかかわらず表示されるということでもあります。
1368
1369 一方、@code{info}コマンドは現在のプロセスにロードされているかどうか
1370 とは関係なく、infoドキュメントから検索します。ドキュメントされていない
1371 APIにはヒットしません。
1372
1373 @code{apropos}はイントロスペクションのツール、
1374 @code{info}はドキュメント参照のツールと考えると良いでしょう。
1375 @c COMMON
1376
1377 @c EN
1378 When the result of evaluation is a huge nested structure,
1379 it may take too long to display the result. Gauche actually set
1380 a limit of length and depth in displaying structures, so you might
1381 occasionally see the very long or deep list is trucated, with
1382 @dots{} to show there are more items, or @code{#} to show a subtree
1383 is omitted
1384 (Try evaluating @code{(make-list 100)} on REPL).
1385 @c JP
1386 評価結果が巨大な構造になる場合、それを表示するのに時間がかかりすぎる問題があります。
1387 Gaucheはデフォルトで、表示する構造の長さと深さに制限を設けているので、
1388 非常に長い、あるいは深い構造を表示しようとした場合に、@dots{}によって後の方が
1389 省略されたり、@code{#}によって深い構造が省略されたりします
1390 (REPLで@code{(make-list 100)}を評価してみてください。)
1391 @c COMMON
1392
1393 @c EN
1394 You can type @code{,pa} (or @code{,print-all}) toplevel REPL command
1395 to fully redisplay the previous result without omission.
1396 @c JP
1397 直前の結果を省略無しで再表示するには @code{,pa} (もしくは@code{,print-all})
1398 トップレベルREPLコマンドをタイプしてください。
1399 @c COMMON
1400
1401 @c EN
1402 By default, REPL prints out the result using @emph{pretty print}:
1403 @c JP
1404 デフォルトでは、REPLはネストした構造を@emph{プリティプリント}します:
1405 @c COMMON
1406
1407 @example
1408 gosh> ,u sxml.ssax
1409 gosh> (call-with-input-file "src/Info.plist" (cut ssax:xml->sxml <> '()))
1410 (*TOP*
1411 (*PI* xml "version=\"1.0\" encoding=\"UTF-8\"")
1412 (plist
1413 (|@@| (version "1.0"))
1414 (dict (key "CFBundleDevelopmentRegion") (string "English")
1415 (key "CFBundleExecutable") (string "Gauche") (key "CFBundleIconFile")
1416 (string) (key "CFBundleIdentifier") (string "com.schemearts.gauche")
1417 (key "CFBundleInfoDictionaryVersion") (string "6.0")
1418 (key "CFBundlePackageType") (string "FMWK") (key "CFBundleSignature")
1419 (string "????") (key "CFBundleVersion") (string "1.0")
1420 (key "NSPrincipalClass") (string))))
1421 @end example
1422
1423 @c EN
1424 If you want to turn off pretty printing for some reason,
1425 type @code{,pm pretty #f} (or @code{,print-mode pretty #f}) on the
1426 toplevel prompt, or start @code{gosh} with the environment variable
1427 @code{GAUCHE_REPL_NO_PPRINT} set.
1428 @c JP
1429 何らかの理由でプリティプリントをoffにしたい場合は、
1430 トップレベルプロンプトで@code{,pm pretty #f}
1431 (あるいは@code{,print-mode pretty #f})と打つか、
1432 環境変数@code{GAUCHE_REPL_NO_PPRINT}をセットして@code{gosh}を起動してください。
1433 @c COMMON
1434
1435 @c EN
1436 Type @code{,pm default} to make print mode back to default.
1437 For more details, type @code{,help pm}.
1438 @c JP
1439 プリントモードをデフォルトに戻すには@code{,pm default}とタイプします。
1440 より詳しくは@code{,help pm}を見てください。
1441 @c COMMON
1442
1443 @c EN
1444 Note: If you invoke @code{gosh} with @code{-q} option, which tells
1445 @code{gosh} not to load the initialization files, you still get
1446 a REPL prompt but no fancy features such as history variables
1447 are available. Those convenience features are implemented in
1448 @code{gauche.interactive} module, which isn't loaded with @code{-q}
1449 option.
1450 @c JP
1451 註: @code{gosh}を@code{-q}オプション (初期化ファイルをロードしない) で
1452 起動した場合もREPLに入りますが、そこではヒストリ変数などは使えません。
1453 REPLの便利機能は@code{gauche.interactive}モジュールで実装されていますが、
1454 @code{-q}オプションをつけると@code{gauche.interactive}がロードされないからです。
1455 @c COMMON
1456
1457 @node Input editing, , Working in REPL, Interactive development
1458 @subsection Input editing
1459 @c NODE 入力の編集
1460
1461 @c EN
1462 When you run @code{gosh} in a terminal capable of cursor control,
1463 you can edit input expressions.
1464 If input editing mode is on, the REPL prompt ends with @code{$}, such
1465 as @code{gosh$}, instead of @code{gosh>}.
1466 @c JP
1467 @code{gosh}がカーソル制御可能な端末で起動された場合、入力編集が可能です。
1468 入力編集モードが有効であれば、REPLのプロンプトが@code{$}で終わります。
1469 例えばデフォルトでは@code{gosh>}のかわりに@code{gosh$}になります。
1470 @c COMMON
1471
1472 @c EN
1473 (NB: Currently Gauche only supports terminals with vt100-like escape
1474 sequence, or Windows console. If the terminal type isn't recognized
1475 as one of them,
1476 it falls back to non-editing mode. You can tell which mode it is
1477 from the prompt.)
1478 @c JP
1479 (註: 今のところ、Gaucheはvt100系のエスケープシーケンスを認識する端末か、
1480 Windows consoleのみをサポートします。端末タイプがそれらでなかった場合は、
1481 入力編集の無いモードになります。プロンプトでどちらのモードにいるかわかります。)
1482 @c COMMON
1483
1484 @c EN
1485 The input editing feature is still under development. If you stumbled
1486 with a serious bug, you can turn it off by setting an environment
1487 variable @code{GAUCHE_NO_READ_EDIT}, or giving @code{-fno-read-edit} option
1488 to @code{gosh}, or type @code{,edit off} on REPL.
1489 @c JP
1490 入力編集機能はまだ開発途上です。もし重大なバグに当たって編集機能をオフにしたければ、
1491 環境変数@code{GAUCHE_NO_READ_EDIT}を設定するか、
1492 @code{gosh}を @code{-fno-read-edit} オプションつきで起動するか、
1493 REPLで @code{,edit off} とタイプしてください。
1494 @c COMMON
1495
1496 @c EN
1497 The key binding is similar to Emacs. Eventually we'll provide customization
1498 feature. Before going into details, here's a few quick useful tips.
1499 @c JP
1500 キーバインディングはEmacsと似ています。いずれカスタマイズする機能も提供する予定です。
1501 詳細に立ち入る前に、知っておくと良いヒントをいくつか。
1502 @c COMMON
1503
1504 @itemize @bullet
1505 @item
1506 @c EN
1507 If the screen is garbled somehow, type @code{C-l} (control+l) to clear and
1508 redisplay.
1509 @c JP
1510 スクリーンがぐちゃぐちゃになってしまったら、@code{C-l} (control+l) で
1511 スクリーンがクリアされ、入力中の式が再表示されます。
1512 @c COMMON
1513 @item
1514 @c EN
1515 If you want to turn off editing during REPL session, use @code{,edit off}
1516 toplevel command.
1517 @c JP
1518 REPLセッション中に入力編集モードを切りたくなったら、トップレベルコマンド
1519 @code{,edit off} が使えます。
1520 @c COMMON
1521 @item
1522 @c EN
1523 The input editor only sends a complete S-expression to the evaluator. If
1524 somehow you want to send the current input as-is (or, in case the editor
1525 has a bug and don't allow you to send a complete S-expression), type
1526 @code{C-M-x} (control-meta-x) to force sending the current input to the
1527 evaluator.
1528 @c JP
1529 入力編集は、完全なS式が入力されて初めてそれを評価器に送ります。
1530 現在の入力をそのままとにかく送りたい場合 (あるいは、入力編集機能のバグで
1531 S式が完結しているのに送ってくれない場合) は、@code{C-M-x} (control-meta-x) を
1532 タイプすると強制的に現在の編集内容が評価器に送られます。
1533 @c COMMON
1534 @item
1535 @c EN
1536 You can type @code{M-h h} to see a brief summary of editor features,
1537 @code{M-h b} to see the list of keymap, or
1538 @code{M-h k} + keystroke to see the help of the key.
1539 (@code{C-h} is the same as backspace).
1540 @c JP
1541 @code{M-h h}で簡単な編集機能のサマリを、
1542 @code{M-h b}でキーマップのリストを、
1543 そして@code{M-h k}に続いてキーを打つことでそのキーの機能のヘルプを見ることができます。
1544 (ヘルプが@code{C-h}でないのは、backspaceと同じキーコードだからです。)
1545 @c COMMON
1546 @item
1547 @c EN
1548 If you suspend @code{gosh}, then resume it by shell's job control feature
1549 (e.g. @code{C-z}, then @code{fg}).
1550 type ENTER to regain editing screen.
1551 @c JP
1552 もしシェルのジョブコントロール機能で@code{gosh}を一回止めてからまた再開した場合
1553 (@code{C-z}で止めて@code{fg}で再開するなど)、ENTERをタイプすることで
1554 編集画面がリストアされます。
1555 @c COMMON
1556 @end itemize
1557
1558 @c EN
1559 @subsubheading Cursor movement
1560 @c JP
1561 @subsubheading カーソル移動
1562 @c COMMON
1563
1564 @c EN
1565 @code{C-f} (forward) and @code{C-b} (backward) moves the cursor forward
1566 and backward character-wise. @code{C-p} (previous) and @code{C-n} (next)
1567 moves character to previous or next line, if the input already has
1568 multiple lines, or moves to previous or next history.
1569 @c JP
1570 @code{C-f} (forward) と @code{C-b} (backward) はカーソルを一文字前あるいは
1571 一文字後に移動します。@code{C-p} (previous) と @code{C-n} (next) は
1572 カーソルを一行前あるいは一行後に移動します。移動方向に行が無ければ、
1573 入力バッファが一つ前または一つ後のヒストリに置き換わります。
1574 @c COMMON
1575
1576 @c EN
1577 @code{M-f} and @code{M-b} move the cursor forward and backward, word-wise.
1578 @c JP
1579 @code{M-f}と@code{M-b}は単語単位でカーソルを前後に移動します。
1580 @c COMMON
1581
1582 @c EN
1583 @code{C-a} and @code{C-e} to move to the beginning and end of the line,
1584 @code{M-<} and @code{M->} to move to the beginning and end of of the input.
1585 @c JP
1586 @code{C-a}と@code{C-e}は行の先頭または末尾に、
1587 @code{M-<}と@code{M->}は入力バッファの最初または最後にカーソルを移動します。
1588 @c COMMON
1589
1590 @subsubheading Undo
1591
1592 @c EN
1593 @code{C-_} is undo the edit. You can keep typing @code{C-_} to
1594 undo the edits you've made.
1595 We follow the Emacs model of undo
1596 semantics, which allows ``undoing undoes''.
1597 For the detailed algorithm, see the comment at the bottom of
1598 @file{lib/text/line-edit.scm}
1599 in the source tree.
1600 @c JP
1601 直前の変更をundoするには@code{C-_}を使います。@code{C-_}を続けてタイプすれば
1602 どんどん編集をundoできます。undoのモデルはEmacsと同じで、つまり
1603 [undo自体をundoする]こともできます。
1604 詳しいアルゴリズムは、ソースの@file{lib/text/line-edit.scm}末尾の
1605 コメントを見てください。
1606 @c COMMON
1607
1608 @c EN
1609 @subsubheading Kill and yank
1610 @c JP
1611 @subsubheading killとyank
1612 @c COMMON
1613
1614 @c EN
1615 @code{C-k} removes characters from the cursor to the end of line.
1616 If the cursor is at the end of the line though, it removes the newline
1617 character (so that next line is combined to the current line).
1618 @c JP
1619 @code{C-k}はカーソルから行末までの文字を取り除きます。もしカーソルが既に
1620 行末にあったら、改行文字そのものを取り除きます(つまり、次の行が現在の行の後に
1621 接続されます)。
1622 @c COMMON
1623
1624 @c EN
1625 @code{M-d} removes a word that contains the cursor, or a word
1626 immediately after the cursor if it is not on a word.
1627 @c JP
1628 @code{M-d}はカーソルが単語の中にあればその単語を、そうでなければ直後の単語を
1629 取り除きます。
1630 @c COMMON
1631
1632 @c EN
1633 @code{C-@@} set a mark to the current cursor position. @code{C-w} removes
1634 chracters between the cursor and the mark.
1635 @c JP
1636 @code{C-@@}はカーソル位置をマークします。その後、@code{C-w}で
1637 その時点のカーソルとマークの間の文字を取り除けます。
1638 @c COMMON
1639
1640 @c EN
1641 The characters removed by those commands are saved
1642 in the buffer called ``kill-ring''.
1643 They can be recalled at the cursor position by @code{C-y} (yank).
1644 If you press @code{M-y} immediately followed by @code{C-y}, you can
1645 go back to the older killed characters.
1646 @c JP
1647 これらのコマンドで取り除かれた文字は、``kill-ring'' と呼ばれるバッファに
1648 セーブされていて、@code{C-y}をタイプするとカーソル位置に復元することができます。
1649 @code{C-y}の後に続けて@code{M-y}をタイプしてゆくと、``kill-ring''にセーブされた
1650 さらに古い内容へと遡って復元することができます。
1651 @c COMMON
1652
1653 @c EN
1654 @subsubheading Interpolation
1655 @c JP
1656 @subsubheading 補完
1657 @c COMMON
1658
1659 @c EN
1660 Typing TAB in or immediately after a partially typed word completes it.
1661 If there are multiple candidates, it completes up to the commom prefix,
1662 and typing TAB again shows the list of candidates.
1663
1664 What's to be completed depends on the context. If it is at the toplevel
1665 command (a word after a comma on a prompt),
1666 it complets toplevel commands. If it is argument
1667 of @code{,load} toplevel command, it completes pathnames.
1668 If it is argument of @code{,use} or @code{,reload} toplevel commands,
1669 it completes module names. In other contexts, it completes global bindings
1670 visible from the current module.
1671
1672 For symbols and module names, segmented completion is possible; e.g.
1673 @code{c-w-c-c} completes to @code{call-with-current-continuation}.
1674
1675 Currently the completion mechanism is hardcoded. We may add a way to
1676 customize it in future.
1677 @c JP
1678 部分的にタイプされた単語の中、もしくは直後にTABを打つと単語が補完されます。
1679 複数の候補がある場合、共通するプレフィクスが補完され、そこで続けてTABを打つと候補がリストされます。
1680
1681 何が補完されるかは文脈によります。トップレベルコマンド
1682 (プロンプトにおいてコンマの後に続く単語)の場合はトップレベルコマンドが、
1683 @code{,load}トップレベルコマンドの引数であればパス名が、
1684 @code{,use}や@code{,reload}トップレベルコマンドの引数であればモジュール名が、
1685 そしてその他の文脈では現在のモジュールから見えるグローバル束縛があるシンボルです。
1686
1687 シンボルとモジュール名については、区切られた単語による補完が可能です。
1688 例えば@code{c-w-c-c}は@code{call-with-current-continuation}に補完されます。
1689
1690 今のところ、補完メカニズムはハードコードされています。いずれカスタマイズできるように
1691 するかもしれません。
1692 @c COMMON
1693
1694 @c EN
1695 @subsubheading Finishing input
1696 @c JP
1697 @subsubheading 入力の終了
1698 @c COMMON
1699
1700 @c EN
1701 @code{RET} (or @code{C-m}) inserts a newline if the input isn't
1702 a complete S-expresson. If the input is already a complete S-expression,
1703 however, it sends the entire input to the evaluator, no matter where
1704 the cursor is. If you want to insert a newline in a complete S-expression,
1705 you can use @code{C-j}.
1706 @c JP
1707 入力のS式がまだ完結していなければ、@code{RET} (@code{C-m}) は入力に改行文字を
1708 挿入します。もしS式が完結していれば、カーソルがどこにあっても@code{RET} (@code{C-m})は
1709 入力を評価機に送ります。もし完結したS式の途中に改行を追加したい場合は
1710 @code{C-j}をタイプしてください。
1711 @c COMMON
1712
1713 @c EN
1714 @code{M-C-x} sends the current input regardless that the input is
1715 a complete S-expression or not.
1716 @c JP
1717 S式が完結しているかどうかにかかわらず入力を評価したい場合は、
1718 @code{M-C-x}をタイプしてください。
1719 @c COMMON
1720
1721 @c EN
1722 @subsubheading History
1723 @c JP
1724 @subsubheading ヒストリ
1725 @c COMMON
1726
1727 @c EN
1728 Input history is remembered and recalled by @code{M-p} (prev-history)
1729 and @code{M-n} (next-history).
1730 The cursor movement command @code{C-p} and @code{C-n} also moves to
1731 the previous or next history if it is pressed when the cursor is
1732 at the beginning or the end of the input lines.
1733 @c JP
1734 入力のヒストリは保存されていて、@code{M-p} (prev-history)と
1735 @code{M-n} (next-history)で呼び出すことができます。
1736 カーソル上下移動の@code{C-p}と@code{C-n}も、現在の入力バッファを越えて移動しようとすると
1737 前または後のヒストリを呼び出します。
1738 @c COMMON
1739
1740 @c EN
1741 The input interrupted by @code{C-c} isn't remembered.
1742 @c JP
1743 @code{C-c}で中断された入力はヒストリに保存されません。
1744 @c COMMON
1745
1746 @c EN
1747 By default, the input is saved to a file @file{~/.gosh_history} when the
1748 REPL is terminated normally, and reloaded when the next REPL is invoked.
1749 The name of the history file can be changed by the environment variable
1750 @code{GAUCHE_HISTORY_FILE}. If the environment variable is defined to an
1751 empty string, however, the history won't be saved.
1752 @c JP
1753 デフォルトでは、入力ヒストリはREPLが正常終了する際に@file{~/.gosh_history}され、
1754 次にREPLが起動する際に読み込まれます。
1755 ヒストリを保存するファイル名は環境変数@code{GAUCHE_HISTORY_FILE}で変更できます。
1756 また、この環境変数が空文字列にセットされていれば、ヒストリは保存されません。
1757 @c COMMON
1758
1759 @c EN
1760 @subsubheading Miscellaneous
1761 @c JP
1762 @subsubheading その他
1763 @c COMMON
1764
1765 @c EN
1766 @code{C-g} cancels the current multi-key sequences.
1767 @c JP
1768 @code{C-g}は複数キーシーケンスをキャンセルします。
1769 @c COMMON
1770
1771 @c EN
1772 @code{C-c} cancels the current input.
1773 @c JP
1774 @code{C-c}は現在の入力をキャンセルします。
1775 @c COMMON
1776
1777 @c EN
1778 @code{C-t} transpose characters at and before the cursor.
1779 @c JP
1780 @code{C-t}はカーソルとその前の文字を入れ替えます。
1781 @c COMMON
1782
1783 @c EN
1784 @code{C-q} reads the next keystroke and insert it into the input as is.
1785 @c JP
1786 @code{C-q}は次のキーストロークを読み取ってそれを入力にそのまま挿入します。
1787 @c COMMON
1788
1789 @c EN
1790 @code{M-(} inserts a pair of parentheses, and locate a cursor inside them.
1791 @c JP
1792 @code{M-(}は対になった括弧を挿入し、カーソルを括弧の間に置きます。
1793 @c COMMON
1794
1795 @c EN
1796 @code{C-l} clears the screen and redraws the current input buffer.
1797 @c JP
1798 @code{C-l}は画面をクリアし、入力バッファを再表示します。
1799 @c COMMON
1800
1801 @c ----------------------------------------------------------------------
1802 @node Writing Scheme scripts, Debugging, Interactive development, Programming in Gauche
1803 @section Writing Scheme scripts
1804 @c NODE Schemeスクリプトを書く
1805
1806 @c EN
1807 When a Scheme program file is given to @code{gosh}, it
1808 makes the @code{user} module as the current module,
1809 binds a global variable @code{*argv*} to the list of the remaining
1810 command-line arguments, and then loads the Scheme program.
1811 If the first line of @var{scheme-file} begins with two character
1812 sequence ``@code{#!}'', the entire line is ignored by @code{gosh}.
1813 This is useful to write a Scheme program that works as an executable
1814 script in unix-like systems.
1815 @c JP
1816 @code{gosh}のコマンドラインにSchemeプログラムのファイル名が渡された場合、
1817 @code{gosh}は@code{user}モジュールをカレントモジュールとし、
1818 それ以降のコマンドライン引数のリストをグローバル変数@code{*argv*}に束縛して、
1819 Schemeプログラムをロードします。もし@var{scheme-file}の最初の行が``@code{#!}''で始まって
1820 いたら、その行は無視されます。これにより、Unix系のシステムで実行可能なSchemeスクリプト
1821 を書くことが出来ます。
1822 @c COMMON
1823
1824 @c EN
1825 Typical Gauche script has the first
1826 line like these
1827
1828 @example
1829 #!/usr/local/bin/gosh
1830 @r{or,}
1831 #!/usr/bin/env gosh
1832 @r{or,}
1833 #!/bin/sh
1834 #|
1835 exec gosh -- $0 "$@@"
1836 |#
1837 @end example
1838
1839 The second and third form uses a ``shell trampoline'' technique
1840 so that the script works as far as @code{gosh} is in the PATH.
1841 The third form is useful when you want to pass extra arguments
1842 to @code{gosh}, for typically @code{#!}-magic of executable scripts
1843 has limitations for the number of arguments to pass the interpreter.
1844 @c JP
1845 典型的なGaucheスクリプトの最初の行は次のようなものです。
1846
1847 @example
1848 #!/usr/local/bin/gosh
1849 @r{または,}
1850 #!/usr/bin/env gosh
1851 @r{または,}
1852 #!/bin/sh
1853 #|
1854 exec gosh -- $0 "$@@"
1855 |#
1856 @end example
1857
1858 後の2つは「シェルトランポリン」テクニックを用いて、@code{gosh}がPATHにあるディレクトリの
1859 どこかにあれば起動できるようにしています。3番目の方法は、
1860 @code{gosh}にいくつかコマンドラインオプションを渡したい時に便利です。
1861 @c COMMON
1862
1863 @c EN
1864 After the file is successfully loaded, @code{gosh} calls a
1865 procedure named `@code{main}' if it is defined in the user module.
1866 @code{Main} receives a single argument, a list of command line
1867 arguments. Its first element is the script name itself.
1868
1869 When @code{main} returns, and its value is an integer, @code{gosh}
1870 uses it for exit code of the program.
1871 Otherwise, @code{gosh} exits with exit code 70 (@code{EX_SOFTWARE}).
1872 This behavior is compatible with the SRFI-22.
1873
1874 If the @code{main} procedure is not defined, @code{gosh} exits
1875 after loading the script file.
1876 @c JP
1877 ファイルが正常にロードされたら、@code{gosh}は
1878 userモジュールに `@code{main}' という手続きが定義されているかどうか調べ、
1879 定義されていればそれを呼びます。@code{main}には、スクリプトへの引数のリストが
1880 唯一の引数として渡されます。リストの最初の要素はスクリプトファイル名です。
1881
1882 @code{main}が整数の値を返したら、@code{gosh}はその値を終了ステータスとして終了します。
1883 @code{main}が整数以外の値を返した場合は@code{gosh}は終了ステータス70
1884 (@code{EX_SOFTWARE})で終了します。このふるまいはSRFI-22と互換です。
1885
1886 @code{main}が定義されていなければ@code{gosh}はロード後にそのままステータス0で
1887 終了します。
1888 @c COMMON
1889
1890 @c EN
1891 Although you can still write the program
1892 main body as toplevel expressions, like shell scripts or Perl scripts,
1893 it is much convenient to use this `@code{main}' convention, for
1894 you can load the script file interactively to debug.
1895 @c JP
1896 シェルスクリプトやPerlスクリプトと同じように、スクリプトのボディに直接
1897 実行される式を書くこともできますが、なるべく `@code{main}' を使った方法を
1898 使うことをお薦めします。そうすると、スクリプトをインタプリタにインタラクティブに
1899 ロードしてデバッグすることもできます。
1900 @c COMMON
1901
1902 @c EN
1903 Using @code{-m} command-line option, you can make @code{gosh} call
1904 @code{main} procedure defined in a module other than the @code{user}
1905 module. It is sometimes handy to write a Scheme module that can
1906 also be executed as a script.
1907
1908 For example, you write a Scheme module @code{foo}
1909 and @emph{within it}, you define the @code{main} procedure.
1910 You don't need to export it. If the file is loaded as a module,
1911 the @code{main} procedure doesn't do anything. But if you
1912 specify @code{-m foo} option and give the file as a Scheme script
1913 to @code{gosh}, then
1914 the @code{main} procedure is invoked after loading the script.
1915 You can code tests or small example application in such an
1916 alternate main procedure.
1917 @c JP
1918 @code{-m}コマンドラインオプションを使えば、@code{user}モジュール以外の
1919 モジュールで定義された@code{main}手続きをスクリプトのメイン関数として
1920 呼ぶことができます。Schemeモジュールを、Schemeスクリプトとしても使えるように
1921 したい場合に便利です。
1922
1923 例えば、@code{foo}というSchemeモジュールを書いて、@emph{その中で}
1924 @code{main}関数を定義しておきます。この@code{main}関数はexportしないでおきます。
1925 このファイルがモジュールとしてロードされた場合、この@code{main}関数は
1926 外からは見えないので何もしません。しかし、@code{gosh}に@code{-m foo}オプションを
1927 与えて、このファイルをスクリプトファイルとして指定すれば、ファイルをロードした後に
1928 @code{main}手続きが呼ばれます。その中には、
1929 テストだとかモジュールのサンプルアプリケーションを書いておくことができるでしょう。
1930 @c COMMON
1931
1932 @c EN
1933 @emph{Note on R7RS Scripts}: If the script is written in R7RS Scheme
1934 (which can be distinguished by the first @code{import} declaration,
1935 @pxref{Three forms of import}), it is read into @code{r7rs.user}
1936 module and its @code{main} isn't called.
1937 You can give @code{-mr7rs.main} command-line argument to call
1938 the @code{main} function in R7RS script.
1939 Alternatively, as specified in SRFI-22, if the script interpreter's
1940 basename is @file{scheme-r7rs}, we assume the script is R7RS SRFI-22 script
1941 and calls @code{main} in @code{r7rs.user} module rather than @code{user}
1942 module. We don't install such an alias, but you can manually
1943 make symbolic link or just copy @file{gosh} binary as @file{scheme-r7rs}.
1944 @c JP
1945 @emph{R7RSスクリプトに関する註}: スクリプトがR7RS Schemeで書かれている場合
1946 (先頭にR7RSの@code{import}があることで区別されます。
1947 詳しくは@ref{Three forms of import}参照)、
1948 スクリプト本体は@code{r7rs.user}へと読み込まれるため、
1949 @code{main}は自動的には呼ばれません。
1950 コマンドライン引数@code{-mr7rs.main}を指定することで、
1951 R7RSスクリプトの@code{main}を実行できます。
1952 別の方法として、SRFI-22に指定されているように、
1953 スクリプトインタプリタのbasenameが@file{scheme-r7rs}であった場合、
1954 スクリプトはR7RSで書かれたSRFI-22形式であると見なされ、
1955 @code{user}モジュールのかわりに@code{r7rs.user}モジュールの@code{main}が呼ばれます。
1956 そのような別名は自動的にはインストールされませんが、
1957 @file{gosh}に@file{scheme-r7rs}という名前でシンボリックリンクを張るか、
1958 コピーすることができるでしょう。
1959 @c COMMON
1960
1961 @c EN
1962 Although the argument of the @code{main} procedure is the standard way
1963 to receive the command-line arguments, there are a couple of other
1964 ways to access to the info. @xref{Command-line arguments}, for the
1965 details.
1966 @c JP
1967 コマンドライン引数を受け取る標準的な方法は、@code{main}関数の引数としてですが、
1968 他にもコマンドライン引数にアクセスする方法が提供されています。詳しくは
1969 @ref{Command-line arguments}を参照してください。
1970 @c COMMON
1971
1972 @c EN
1973 Now I show several simple examples below.
1974 First, this script works like @code{cat(1)}, without any command-line
1975 option processing and error handling.
1976 @c JP
1977 ではいくつか簡単な例を示しましょう。最初の例はUnixの@code{cat(1)}コマンドを模するものです。
1978 エラー処理やコマンドラインオプションの処理は行っていません。
1979 @c COMMON
1980
1981 @example
1982 #!/usr/bin/env gosh
1983
1984 (define (main args) ;@r{entry point}
1985 (if (null? (cdr args))
1986 (copy-port (current-input-port) (current-output-port))
1987 (for-each (lambda (file)
1988 (call-with-input-file file
1989 (lambda (in)
1990 (copy-port in (current-output-port)))))
1991 (cdr args)))
1992 0)
1993 @end example
1994
1995 @c EN
1996 The following script is a simple grep command.
1997 @c JP
1998 次のスクリプトは簡単なgrepコマンドです。
1999 @c COMMON
2000
2001 @example
2002 #!/usr/bin/env gosh
2003
2004 (define (usage program-name)
2005 (format (current-error-port)
2006 "Usage: ~a regexp file ...\n" program-name)
2007 (exit 2))
2008
2009 (define (grep rx port)
2010 (with-input-from-port port
2011 (lambda ()
2012 (port-for-each
2013 (lambda (line)
2014 (when (rxmatch rx line)
2015 (format #t "~a:~a: ~a\n"
2016 (port-name port)
2017 (- (port-current-line port) 1)
2018 line)))
2019 read-line))))
2020
2021 (define (main args)
2022 (if (null? (cdr args))
2023 (usage (car args))
2024 (let ((rx (string->regexp (cadr args))))
2025 (if (null? (cddr args))
2026 (grep rx (current-input-port))
2027 (for-each (lambda (f)
2028 (call-with-input-file f
2029 (lambda (p) (grep rx p))))
2030 (cddr args)))))
2031 0)
2032 @end example
2033
2034 @c EN
2035 See also @ref{Parsing command-line options}, for a convenient way to
2036 parse command-line options.
2037 @c JP
2038 また、@ref{Parsing command-line options}を使うと手軽にコマンドラインオプション
2039 を処理することができます。
2040 @c COMMON
2041
2042 @c ----------------------------------------------------------------------
2043 @node Debugging, Platform-dependent features, Writing Scheme scripts, Programming in Gauche
2044 @section Debugging
2045 @c NODE デバッグ
2046
2047 @c EN
2048 Gauche doesn't have much support for debugging yet.
2049 The idea of good debugging interfaces are welcome.
2050 @c JP
2051 Gaucheにはまだデバッグをサポートする機能があまり実装されていません。
2052 デバッギングのインタフェースに関して良いアイディアがあればお寄せください。
2053 @c COMMON
2054
2055 @c EN
2056 For now, the author uses the classic 'debug print stub' technique
2057 when necessary. Gauche's reader supports special syntaxes
2058 beginning with @code{#?}, to print the intermediate value.
2059 @c JP
2060 今のところ、作者は必要な時は古典的な「プリントスタブ」方式を使っています。
2061 Gaucheのリーダには、中間の結果を出力するために、
2062 @code{#?}で始まるいくつかの構文が用意されています。
2063 @c COMMON
2064
2065 @c EN
2066 The syntax @code{#?=@var{expr}} shows @var{expr} itself before
2067 evaluating it, and prints its result(s) after evaluation.
2068 @c JP
2069 構文@code{#?=@var{expr}}は、@var{expr}を評価する前にまずその式自体を
2070 表示し、評価後にその結果(複数の場合もあります)を表示します。
2071 @c COMMON
2072
2073 @example
2074 gosh> #?=(+ 2 3)
2075 #?="(stdin)":1:(+ 2 3)
2076 #?- 5
2077 5
2078 gosh> #?=(begin (print "foo") (values 'a 'b 'c))
2079 #?="(stdin)":2:(begin (print "foo") (values 'a 'b 'c))
2080 foo
2081 #?- a
2082 #?+ b
2083 #?+ c
2084 a
2085 b
2086 c
2087 @end example
2088
2089 @c EN
2090 Note: If the debug stub is evaluated in a thread other than
2091 the primordial thread (@pxref{Threads}), the output
2092 includes a number to distinguish which thread it is generated.
2093 In the following example, @code{#<thread ...>} and the prompt
2094 is the output of REPL in the primordial thread,
2095 but following @code{#?=[1]...} and @code{#?-[1]...} are
2096 the debug output from the thread created by @code{make-thread}.
2097 The number is for debugging only---
2098 they differ for each thread, but other than that there's no meaning.
2099 @c JP
2100 註: デバッグスタブが原始スレッド(@ref{Threads}参照)以外のスレッドで評価された場合、
2101 スタブの出力には、どのスレッドから出力されたかを示す番号がつけられます。
2102 次の例では、@code{#<thread ...>}およびプロンプトが原始スレッドのREPLの
2103 出力ですが、続く@code{#?=[1]...}と@code{#?-[1]...}は
2104 @code{make-thread}により作られたスレッドからのデバッグ出力です。
2105 この番号はデバッグ時にスレッドを区別するためだけのもので、スレッド毎に異なりますが、
2106 それ以外の意味はありません。
2107 @c COMMON
2108
2109 @example
2110 gosh> (use gauche.threads)
2111 gosh> (thread-start! (make-thread (^[] #?=(+ 2 3))))
2112 #<thread #f (1) runnable 0xf51400>
2113 gosh> #?=[1]"(standard input)":1:(+ 2 3)
2114 #?-[1] 5
2115 @end example
2116
2117 @c EN
2118 The syntax @code{#?,(@var{proc} @var{arg} @dots{})} is specifically
2119 for procedure call; it prints the value of arguments right before
2120 calling @var{proc}, and prints the result(s) of call afterwards.
2121 @c JP
2122 構文@code{#?,(@var{proc} @var{arg} @dots{})}は特に手続き呼び出しのための
2123 ものです。@var{proc}を呼ぶ直前に引数の値を表示し、@var{proc}から返ってきたら
2124 戻り値(複数の場合もあります)を表示します。
2125 @c COMMON
2126
2127 @example
2128 gosh> (define (fact n)
2129 (if (zero? n)
2130 1
2131 (* n #?,(fact (- n 1)))))
2132 fact
2133 #?,"(standard input)":4:calling `fact' with args:
2134 #?,> 4
2135 #?,"(standard input)":4:calling `fact' with args:
2136 #?,> 3
2137 #?,"(standard input)":4:calling `fact' with args:
2138 #?,> 2
2139 #?,"(standard input)":4:calling `fact' with args:
2140 #?,> 1
2141 #?,"(standard input)":4:calling `fact' with args:
2142 #?,> 0
2143 #?- 1
2144 #?- 1
2145 #?- 2
2146 #?- 6
2147 #?- 24
2148 120
2149 @end example
2150
2151 @c EN
2152 Internally, the syntax @code{#?=@var{x}} and @code{#?,@var{x}} are read
2153 as @code{(debug-print @var{x})} and @code{(debuf-funcall @var{x})},
2154 respectively, and the macros @code{debug-print} and @code{debug-funcall}
2155 handles the actual printing. @xref{Debugging aid}, for more details.
2156
2157 The reasons of special syntax are: (1) It's easy to insert the
2158 debug stub, for you don't need to enclose the target expression by
2159 extra parenthesis, and
2160 (2) It's easy to find and remove those stabs within the editor.
2161 @c JP
2162 内部的には、構文@code{#?=@var{x}}と@code{#?,@var{x}}はそれぞれ単に
2163 @code{(debug-print @var{x})}および@code{(debuf-funcall @var{x})}と読まれ、
2164 実際の表示についてはマクロ@code{debug-print}と@code{debug-funcall}が
2165 処理します。詳しくは@ref{Debugging aid}を参照してください。
2166
2167 特別な構文を用意した理由は、(1)目的の式にデバッグスタブを付加するのに、
2168 式全体を余分な括弧でくくらなくて良いのですぐできる
2169 (2)デバッグスタブをエディタで探したり取り除いたりするのが極めて簡単、というものです。
2170 @c COMMON
2171
2172 @c EN
2173 Simple debug stubs may produce too many output, and you may
2174 want to limit them when certain conditions are met. A reader syntax
2175 @code{#??=@var{test} @var{expr}} and
2176 @code{#??,@var{test} @var{procedure-call}} works much like
2177 @code{#??=@var{expr}} and @code{#?,@var{procedure-call}}, but
2178 only when @var{test} yields true:
2179 @c JP
2180 単純なデバッグスタブではしばしば大量にデバッグ出力が出てしまうので、
2181 特定の条件に合致した時のみ出力を見たいことがあるかもしれません。
2182 リーダー構文@code{#??=@var{test} @var{expr}}と
2183 @code{#??,@var{test} @var{procedure-call}}は、
2184 @var{test}が真に評価される時だけそれぞれ
2185 @code{#??=@var{expr}}および@code{#?,@var{procedure-call}}のように
2186 動作します。
2187 @c COMMON
2188
2189 @example
2190 (define (fib n)
2191 (if (< n 2)
2192 1
2193 #??,(= n 5) (+ (fib (- n 1)) (fib (- n 2)))))
2194
2195 gosh> (fib 7)
2196 #?,calling `+' with args:
2197 #?,> 5
2198 #?,> 3
2199 #?- 8
2200 #?,calling `+' with args:
2201 #?,> 5
2202 #?,> 3
2203 #?- 8
2204 21
2205 @end example
2206
2207 @c EN
2208 Internally, @code{#??=@var{test} @var{expr}} and
2209 @code{#??,@var{test} @var{procedure-call}} are expanded to
2210 macro calls @code{(debug-print-conditionally @var{test} @var{expr})}
2211 and @code{(debug-funcallt-conditionally @var{test} @var{procedure-call})}.
2212 @c JP
2213 内部的には、@code{#??=@var{test} @var{expr}}と
2214 @code{#??,@var{test} @var{procedure-call}}はそれぞれマクロ呼び出し
2215 @code{(debug-print-conditionally @var{test} @var{expr})}と
2216 @code{(debug-funcallt-conditionally @var{test} @var{procedure-call})}に
2217 展開されます。
2218 @c COMMON
2219
2220
2221 @c ----------------------------------------------------------------------
2222 @node Platform-dependent features, Profiling and tuning, Debugging, Programming in Gauche
2223 @section Using platform-dependent features
2224 @c NODE プラットフォーム依存の機能
2225
2226 @c EN
2227 Gauche tries to provide low-level APIs close to what the underlying
2228 system provides, but sometimes they vary among systems. For example,
2229 POSIX does not require @code{symlink}, so some systems may lack
2230 @code{sys-symlink} (@pxref{Directory manipulation}). Quite a few
2231 unix-specific system functions are not available on Windows platform.
2232 @c JP
2233 GaucheではOSが提供するAPIに近い低レベルAPIを提供するようにしています。
2234 しかし、システムごとに扱いの違うものがあります。たとえば、POSIXでは
2235 @code{symlink}は必須ではありませんので、システムによっては
2236 @code{sys-symlink} (@ref{Directory manipulation}参照)がありません。
2237 UNIX系のシステム関数は少なからずWindowsでは使えません。
2238
2239 @c EN
2240 To allow writing a portable program across those platforms, Gauche
2241 uses @code{cond-expand} (@pxref{Feature conditional}) extensively.
2242 A set of extended @emph{feature-identifier}s is provided to check
2243 availability of specific features. For example, on systems that
2244 has @code{symlink}, a feature identifier @code{gauche.sys.symlink}
2245 is defined. So you can write a code that can switch based on
2246 the availability of @code{sys-symlink} as follows:
2247 @c JP
2248 プラットフォーム間でポータブルなプログラムを書くために、Gaucheでは
2249 頻繁に@code{cond-expand} を使います(@ref{Feature conditional}参照)。
2250 拡張された@emph{機能識別子(feature-identifier)}が提供されており、これ
2251 を使って特定の機能が利用可能かどうかチェックできます。たとえば、
2252 @code{symlink}があるシステムでは機能識別子@code{gauche.sys.symlink}が
2253 定義されます。したがって、以下のように@code{sys-symlink}が利用できるか
2254 どうかによって、コードをスイッチするようなプログラムを書けます。
2255 @c COMMON
2256
2257 @example
2258 (cond-expand
2259 (gauche.sys.symlink
2260 ... code that uses sys-symlink ...)
2261 (else
2262 ... alternative code ...)
2263 )
2264 @end example
2265
2266 @c EN
2267 If you're familiar with system programming in C, you can think
2268 it equivalent to the following C idiom:
2269 @c JP
2270 Cのシステムプログラミングに詳しいなら、上のコードは以下のCのイディオム
2271 と同じだとみなせます。
2272 @c COMMON
2273
2274 @example
2275 #if defined(HAVE_SYMLINK)
2276 ... code that uses symlink ...
2277 #else
2278 ... alternative code ...
2279 #endif
2280 @end example
2281
2282 @c EN
2283 There are quite a few such feature identifiers; each identifier is
2284 explained in the manual entry of the procedures that depend on the feature.
2285 Here we list a few important ones:
2286 @c JP
2287 このような機能識別子はたくさんあり、それぞれの識別子についてはこのマニュ
2288 アル中のその機能に依存した手続きの項目で説明しています。特に重要なもの
2289 を以下にリストアップしておきます。
2290 @c COMMON
2291
2292 @table @code
2293 @item gauche
2294 @c EN
2295 This feature identifier is always defined. It is useful when you
2296 write Scheme code portable across multiple implementations.
2297 @c JP
2298 この機能識別子は常に定義されています。Gauche以外のSchemeの実装とも互換
2299 性のあるコードを書くときに使えます。
2300 @c COMMON
2301 @item gauche.os.windows
2302 @c EN
2303 Defined on Windows native platform. Note that cygwin does not define
2304 this feature identifier (but see below).
2305 @c JP
2306 Windowsネイティブプラットフォームで定義されます。cygwinでは
2307 この機能識別子は定義されません (下記も参照)。
2308 @c COMMON
2309 @item gauche.os.cygwin
2310 @c EN
2311 Defined on Cygwin.
2312 @c JP
2313 Cygwin上で定義されます。
2314 @c COMMON
2315 @item gauche.sys.pthreads
2316 @itemx gauche.sys.wthreads
2317 @c EN
2318 Defined to indicate the underlying thread implementation.
2319 @xref{Threads}.
2320 @c JP
2321 スレッドの具体的な実装を示すために定義されます。
2322 詳細は@ref{Threads}を参照してください。
2323 @c COMMON
2324 @item gauche.net.ipv6
2325 @c EN
2326 Defined if Gauche is compiled with IPv6 support.
2327 @c JP
2328 GaucheがIPv6をサポートするようにコンパイルされている場合に定義されます。
2329 @c COMMON
2330 @end table
2331
2332 @c EN
2333 Because @code{cond-expand} is a macro, the body of clauses
2334 are expanded into toplevel if @code{cond-expand} itself is in
2335 toplevel. That means you can switch toplevel definitions:
2336 @c JP
2337 @code{cond-expand}はマクロなので、@code{cond-expand}自身がトップレベル
2338 にあれば、節の本体はトップレベルで展開されます。これはトップレベルの定
2339 義をスイッチできるということです。
2340 @c COMMON
2341
2342 @example
2343 (cond-expand
2344 (gauche.os.windows
2345 (define (get-current-user)
2346 ... get current username ...))
2347 (else
2348 (define (get-current-user)
2349 (sys-uid->user-name (sys-getuid)))))
2350 @end example
2351
2352 @c EN
2353 Or even conditionally "use" the modules:
2354 @c JP
2355 あるいは条件によってモジュールを使いわけられます。
2356 @c COMMON
2357
2358 @example
2359 (cond-expand
2360 (gauche.os.windows
2361 (use "my-windows-compatibility-module"))
2362 (else))
2363 @end example
2364
2365 @c EN
2366 The traditional technique of testing a toplevel binding
2367 (using @code{module-binds?}, @pxref{Module introspection})
2368 doesn't work well in this case, since
2369 the @code{use} form takes effect at compile time.
2370 It is strongly recommended to use @code{cond-expand} whenever possible.
2371 @c JP
2372 トップレベルの束縛をチェックするような旧いテクニック
2373 (@code{module-binds?}を使う, @ref{Module introspection}参照)
2374 は実行時に効果を持つので、コンパイル時に解釈される@code{use}
2375 を切り替えるのはうまくいきません。
2376 可能なかぎり、@code{cond-expand}を使うことを推奨します。
2377 @c COMMON
2378
2379 @c EN
2380 Currently the set of feature identifiers are fixed at the build
2381 time of Gauche, so it's less flexible than C preprocessor conditionals.
2382 We have a plan to extend this feature to enable adding new feature
2383 identifiers; but such feature can complicate semantics when compilation
2384 and execution is interleaved, so we're carefully assessing the effects now.
2385 @c JP
2386 現時点では機能識別子集合はGaucheのコンパイル時に固定されます。つまり、
2387 Cのプリプロセッサを使った条件分岐よりも柔軟性に劣ります。この機能を拡
2388 張してあとから機能識別子を追加できるようにする計画ですが、この機能拡張
2389 はコンパイルと実行が細切れに入れ替わる場合のセマンティクスを複雑にしてしまう可
2390 能性があり、現在その影響を慎重にみきわめている最中です。
2391 @c COMMON
2392
2393 @c EN
2394 A couple of notes:
2395 @c JP
2396 いくつか注意事項があります。
2397 @c COMMON
2398
2399 @c EN
2400 Feature identifiers are not variables. They can only be used
2401 within the @var{feature-requirement} part of @code{cond-expand}
2402 (see @ref{Feature conditional} for the complete definition of
2403 feature requirements).
2404 @c JP
2405 機能識別子は変数ではありません。@code{cond-expand}の
2406 @var{feature-requirement}部の内部でのみ利用可能です(機能要求の定義全般
2407 については@ref{Feature conditional}を見てください)。
2408 @c COMMON
2409
2410 @c EN
2411 By the definition of SRFI-0, @code{cond-expand} raises an error
2412 if no feature requirements are satisfied and there's no @code{else}
2413 clause. A rule of thumb is to provide @code{else} clause always,
2414 even it does nothing (like the above example that has empty @code{else}
2415 clause).
2416 @c JP
2417 SRFI-0の定義により、機能要求が満されず、かつ@code{else}節がない
2418 場合には@code{cond-expand}はエラーをあげます。常に@code{else}を書いて
2419 おくのがよいでしょう。 上の例のように、@code{else}節でなにもしないとき
2420 でも、空の@code{else}節を書くのがよいでしょう。
2421 @c COMMON
2422
2423 @c ----------------------------------------------------------------------
2424 @node Profiling and tuning, Auxiliary programs, Platform-dependent features, Programming in Gauche
2425 @section Profiling and tuning
2426 @c NODE プロファイリングとチューニング
2427
2428 @c EN
2429 If you find your script isn't running fast enough,
2430 there are several possibilities to improve its performance.
2431 @c JP
2432 自分のスクリプトのスピードが十分に出ないというときには、
2433 性能を改善するポイントとして考えられる点がいくつかあります。
2434 @c COMMON
2435
2436 @c EN
2437 It is always a good idea to begin with finding which part
2438 of the code is consuming the execution time. Gauche has
2439 a couple of basic tools to help it. A built-in sampling profiler,
2440 explained in the following subsection, can show how much time
2441 is spent in each procedure, and how many times it is called.
2442 The @code{gauche.time} module (@ref{Measure timings}) provides
2443 APIs to measure execution time of specific parts of the code.
2444 @c JP
2445 どんなときでも、実行時間を食いつぶしているコード部分を見つけるというの
2446 を先ず最初にやるのがよいでしょう。Gauche にはこの作業を補助する基本的
2447 なツールが2つあります。組込のサンプリングプロファイラ(これについては次
2448 の節で説明します)を使えば各手続きでどれほどの時間がかかり、その手続き
2449 が何回呼ばれたかを表示できます。@code{gauche.time} モジュール
2450 (@ref{Measure timings}) ではコードの中の特定の部分の実行にかかる時間を
2451 測定するためのAPIが提供されています。
2452 @c COMMON
2453
2454 @c EN
2455 Optimization is specialization---you look for the most common
2456 patterns of execution, and put a special path to support those
2457 patterns efficiently. Gauche itself is no exception, so there
2458 are some patterns Gauche can handle very efficiently, while
2459 some patterns it cannot. The next subsection, @ref{Performance tips},
2460 will give you some tips of how to adapt your code to fit
2461 the patterns Gauche can execute well.
2462 @c JP
2463 最適化というのは特殊化ということでもあります。もっともよく使われる
2464 実行のパターンを探して、そこを効率よく実行する専用のパスを設けることで
2465 す。Gauche 自身も例外ではありません。したがって、Gaucheが効率よく実行
2466 できるパターンがいくつかありますし、また一方では効率よく実行できないパ
2467 ターンもあります。次の節では、@ref{Performance tips} では Gauche が効
2468 率良く実行できるパターンにコードをあわせるチョットしたコツを教えましょう。
2469 @c COMMON
2470
2471 @menu
2472 * Using profiler::
2473 * Performance tips::
2474 @end menu
2475
2476 @node Using profiler, Performance tips, Profiling and tuning, Profiling and tuning
2477 @subsection Using profiler
2478 @c NODE プロファイラを使う
2479
2480 @c EN
2481 As of 0.8.4, Gauche has a built-in profiler. It is still experimental
2482 quality and only be tested on Linux. It isn't available for all
2483 platforms. It works only in single-thread applications for now.
2484 @c JP
2485 0.8.4 から Gauche は組込みのプロファイラを備えています。これは
2486 現時点ではまだ実験的なもので、Linux 上でしかテストしていません。すべてのプ
2487 ラットフォームで利用できるわけではありませんし、シングルスレッドの
2488 アプリケーションでしか動きません。
2489 @c COMMON
2490
2491 @c EN
2492 To use the profiler non-interactively, give @code{-ptime}
2493 command-line option to gosh.
2494 @c JP
2495 非対話環境でこのプロファイラを使うには、gosh のコマンドラインオプショ
2496 ンとして @code{-ptime}を指定してください。
2497 @c COMMON
2498
2499 @example
2500 % gosh -ptime your-script.scm
2501 @end example
2502
2503 @c EN
2504 After the execution of @file{your-script.scm} is completed, Gauche prints
2505 out the table of functions with its call count and its consumed time,
2506 sorted by the total consumed time.
2507 @c JP
2508 @file{your-script.scm} の実行完了後、Gauche は各関数についてその呼び出し回数
2509 および消費時間を示した表を印字します。この表は総消費時間の順でソートさ
2510 れています。
2511 @c COMMON
2512
2513 @smallexample
2514 Profiler statistics (total 1457 samples, 14.57 seconds)
2515 num time/ total
2516 Name calls call(ms) samples
2517 ---------------------------------------------------+------+-------+-----------
2518 combinations* 237351 0.0142 337( 23%)
2519 (lset-difference #f) 1281837 0.0020 256( 17%)
2520 (make-anchor make-anchor) 3950793 0.0005 198( 13%)
2521 member 4627246 0.0004 190( 13%)
2522 filter 273238 0.0030 81( 5%)
2523 every 1315131 0.0004 59( 4%)
2524 (lset-difference #f #f) 1281837 0.0004 54( 3%)
2525 (make-entry make-entry) 730916 0.0005 40( 2%)
2526 (clear? #f) 730884 0.0005 33( 2%)
2527 (initialize #f) 599292 0.0005 32( 2%)
2528 fold 237307 0.0013 30( 2%)
2529 acons 806406 0.0004 29( 1%)
2530 clear? 33294 0.0084 28( 1%)
2531 (combinations* #f) 805504 0.0002 15( 1%)
2532 (make-exit make-exit) 730884 0.0002 15( 1%)
2533 lset-difference 237318 0.0006 15( 1%)
2534 reverse! 475900 0.0001 6( 0%)
2535 (fold <top> <top> <list>) 237323 0.0003 6( 0%)
2536 procedure? 238723 0.0002 4( 0%)
2537 pair? 237307 0.0001 3( 0%)
2538 :
2539 :
2540 @end smallexample
2541
2542 @c EN
2543 Note that the time profiler uses statistic sampling. Every 10ms
2544 the profiler interrupts the process and records the function that is
2545 executed then. Compared to the individual execution time per
2546 function call, which is the order of nanoseconds, this sampling rate
2547 is very sparse. However, if we run the program long enough,
2548 we can expect the distribution of samples per each function
2549 approximately reflects the distribution of time spent in each function.
2550 @c JP
2551 時間プロファイラは統計的標本化をおこなっていることに注意してください。
2552 プロファイラは10ミリ秒ごとにプロセスに割込んで、その時点で実行されてい
2553 る関数を記録します。ナノ秒オーダの関数呼出しごとの個別の実行時間に比べる
2554 と、このサンプリングレートはかなり粗いものです。しかしながら、プロ
2555 グラムの実行時間が長ければ、各関数ごとの標本分布は関数ごとの消費時間を
2556 ほぼ反映しているだろうと期待できます。
2557 @c COMMON
2558
2559 @c EN
2560 Keep in mind that the number is only approximation; the number
2561 of sample counts for a function may easily vary if the program deals
2562 with different data sets. It should also be noted that, for now, GC
2563 time is included in the function in which GC is triggered.
2564 This sometimes causes a less important function to "float up" to
2565 near-top of the list.
2566 To know the general pattern, it is a good custom to run the program
2567 with several different data sets.
2568 @c JP
2569 数字はあくまで近似にすぎないこと
2570 を心にとめておいてください。ひとつの関数あたりの標本数はプログラムが扱
2571 うデータが違えば、すぐに変化してしまうことがあります。
2572 また、今のところGCにかかる時間はGCがトリガされた関数の実行時間に
2573 算入されてしまっていることに注意して下さい。これによって、あまり
2574 重要でない関数がリストの上位に浮かびあがってくることがあります。
2575 一般的なパターンを知るには、プログラムをいろいろなデータで走らせて
2576 みると良いでしょう。
2577 @c COMMON
2578
2579 @c EN
2580 On the other hand, the call count is accurate since Gauche actually
2581 counts each call.
2582 @c JP
2583 一方、関数呼び出し回数のカウントは正確なものです。これは Gauche は
2584 実際の呼出しごとにカウントしているからです。
2585 @c COMMON
2586
2587 @c EN
2588 Because all functions are basically anonymous in Scheme, the 'name' field of
2589 the profiler result is only a hint. The functions bound at toplevel
2590 is generally printed with the global variable name it is bound at
2591 the first time. Internal functions are printed as a list of names,
2592 reflecting the nesting of functions. Methods are also printed as a
2593 list of the name and specializers.
2594 @c JP
2595 Schemeでは基本的にすべての関数は無名なので、プロファイル結果の'name'
2596 フィールドはヒントにすぎません。トップレベルで束縛されている関数につい
2597 ては通常それが最初に束縛されたグローバル変数名が印字されます。内部関数
2598 については関数の入れ子構造を反映して名前のリストが印字されます。
2599 メソッドは、名前と特定化子のリストとして印字されます。
2600 @c COMMON
2601
2602 @c EN
2603 The profiler has its own overhead; generally the total
2604 process time will increase 20-30%.
2605 If you want to turn on the profiler selectively, or you're running
2606 a non-stop server program and want to obtain the statistics without
2607 exiting the server, you can call the profiler API from your program;
2608 see @ref{Profiler API}, for the details.
2609 @c JP
2610 プロファイラはそれ自身にオーバヘッドがあります。通常は、処理時間が
2611 20-30% 増加します。プロファイラを選択的にオンにしたい場合や、
2612 停止しないサーバプログラムを走らせていて、そのサーバを停止することなく、
2613 統計を取りたいような場合には、プログラムからプロファイラ APIを呼ぶこと
2614 ができます。詳細については @ref{Profiler API} を参照してください。
2615 @c COMMON
2616
2617 @node Performance tips, , Using profiler, Profiling and tuning
2618 @subsection Performance tips
2619 @c NODE パフォーマンスに関するヒント
2620
2621 @c EN
2622 Don't guess, just benchmark. It is the first rule of
2623 performance tuning. Especially for the higher-level languages
2624 like Scheme, what impacts on performance greatly depends on
2625 the implementation. Certain operations that are very cheap
2626 on an implementation may be costly on others.
2627 Gauche has such implementation-specific characteristics, and
2628 to know some of them would help to see what to look out in
2629 the benchmark results.
2630 @c JP
2631 「論より run 」これがパフォーマンスチューニングの第一法則です。
2632 Scheme のような高級言語では、何がパフォーマンスに強い影響を
2633 与えるかはことのほかその実装に大きく依存し、ある処理系では
2634 とても安価な操作が別の処理系ではとても高価になり得ます。
2635 Gauche にもそのようなパフォーマンスに関する実装特有の特徴があり、
2636 それらのうちのいくつかを知っておくことは、ベンチマークの結果の
2637 どこに着目すべきかを知るうえで助けになるでしょう。
2638 @c COMMON
2639
2640 @c EN
2641 "80% of execution time is spent in 20% of the code" is another
2642 old saying. Don't obscure your code by "potential" optimization
2643 that has little impact on the actual execution. We describe some
2644 tips below, but it doesn't mean you need to watch them all the time.
2645 It is better to keep most of the code clean and easy to understand,
2646 and only do tricks on the innermost loop.
2647 @c JP
2648 「ソースコードの2割が実行時間の8割を消費する」というのも古くから
2649 言われています。実際の実行時間に大した影響を及ぼさないところを
2650 下手にいじくってプログラムをわかりづらくすることは避けましょう。
2651 これからいくつかのヒントを述べますが、これらのことを四六時中気にして
2652 プログラミングしなければならないということではありません。
2653 むしろ、出来るだけ明瞭でわかりやすいプログラムを心がけ、ループの一番深いところ
2654 (もっとも時間を消費するところ)でこれらのトリックを使うのが良いでしょう。
2655 @c COMMON
2656
2657 @c EN
2658 @strong{Ports}: To satisfy the specification of SRFI-18 (Threading),
2659 every call to I/O primitives of Gauche locks the port.
2660 This overhead may be visible if the application does a lot of I/O
2661 with smaller units (e.g. every bytes). The primitives that deals
2662 with larger unit, such as @code{read} and @code{read-uvector}, are less
2663 problematic, since usually they just lock the port once per call and do
2664 all the low-level I/O without the lock overhead.
2665 (Note: this doesn't mean those primitives @emph{guarantee}
2666 to lock the port throughout the execution of the function;
2667 furthermore, the port locking feature is optimized for the case
2668 that port accesses rarely collide. If you know it is possible that
2669 more than one threads read from or write to the same port, it is
2670 your responsibility to use mutex explicitly to avoid the collision.)
2671 @c JP
2672 @strong{Ports}: SRFI-18 (スレッド) の仕様を満たすために
2673 Gauche のすべての入出力基本関数はポートをロックします。
2674 このオーバーヘッドは小単位(例えばバイト毎)の入出力を行なう
2675 アプリケーションでは無視できないでしょう。
2676 入出力基本関数は通常呼びだし毎にポートをロックし、そこからの
2677 下位レベルの入出力はロックのオーバーヘッドの影響を受けずに
2678 行なわれます。ですから @code{read} や@code{read-uvector}
2679 などのより大きな単位で入出力を行なう基本関数では問題と
2680 なることが少なくなります。
2681 (注意:これらの基本関数が常にポートをロックしつづけることを
2682 保証するものではないことに注意してください。また、ポートのロックは
2683 競合がほとんど発生しない場合に最適化されています。
2684 ポートへのアクセスが複数のスレッドで競合する可能性がある場合は、
2685 アプリケーション側でmutexを明示的に用いて競合を避けてください。)
2686 @c COMMON
2687
2688 @c EN
2689 If you find out the locking is indeed a bottleneck, there are couple
2690 of things you can consider: (1) Try using the larger-unit primitives,
2691 instead of calling the smaller-unit ones. (2) Use @code{with-port-locking}
2692 (see @ref{Port and threads}) to lock the port in larger context.
2693 @c JP
2694 ポートロックが実際に問題となった場合、二つばかり対処策が考えられます。
2695 (1) より大きな単位で入出力を行なう。(2) @code{with-port-locking}
2696 (@ref{Port and threads} 参照)を使ってより広範囲でポートをロックする。
2697 @c COMMON
2698
2699 @c EN
2700 @strong{Strings}: Because of the multibyte strings, two operations
2701 are particularly heavy in Gauche: string mutation and indexed string access.
2702 It is a design choice; we encourage the programming style that
2703 avoids those operations. When you sequentially access the string,
2704 string ports (see @ref{String ports}) provide a cleaner and
2705 more efficient way.
2706 When you search and retrieve a substring, there are various
2707 higher-level primitives are provided (see @ref{String utilities},
2708 @ref{Regular expressions}, and @ref{String library}, for example).
2709 If you're using strings to represent an octet sequence, use uniform
2710 vectors (see @ref{Uniform vectors}) instead.
2711 @c JP
2712 @strong{文字列}: 多バイト文字列の取扱いのため、Gauche では文字列の
2713 変更とインデックスによるアクセスが特に高価な操作となります。
2714 これは意図的な設計です。 Gauche ではこの二つの操作を避けたプログラミングを
2715 推奨しています。 文字列の中の文字を順にアクセスするには
2716 (インデックスを使わずに)文字列ポート(@ref{String ports}参照)を使うと
2717 より明瞭かつ効率的なプログラムとなり、一方サーチして部分文字列をとり出す
2718 といった操作には、多彩な高レベル関数が用意されています。
2719 (例えば @ref{String utilities}、@ref{Regular expressions}、
2720 @ref{String library} 等を参照。) バイト列を表現するのに
2721 文字列を使っていたなら、代わりにユニフォームベクタ(@ref{Uniform vectors}
2722 参照)を使いましょう。
2723 @c COMMON
2724
2725 @c EN
2726 @strong{Deep recursion}: Gauche's VM uses a stack for efficient
2727 local frame allocation. If recursion goes very deep (depending on
2728 the code, but usually several hundreds to a thousand), the stack
2729 overflows and Gauche moves the content of the stack into the heap.
2730 This incurs some overhead. If you observe a performance degradation
2731 beyond a certain amount of data, check out this possibility.
2732 @c JP
2733 @strong{深い再帰}: Gauche の仮想機械(VM)は効率的な
2734 ローカルフレーム割り当てのためにスタックを使っています。
2735 再帰が深くなって(プログラムにもよりますが、大体数百回から千回)
2736 スタックがオーバーフローするとスタックの内容をヒープに退避するという
2737 オーバーヘッドが生じます。 あるデータ量を越えたところでパフォーマンスの
2738 低下が見られたならば、深い再帰がないか調べてみて下さい。
2739 @c COMMON
2740
2741 @c EN
2742 @strong{Generic functions}: Because of its dynamic nature, generic
2743 function calls are slower than procedure calls. Not only because
2744 of the runtime dispatch overhead, but also because Gauche's compile-time
2745 optimizer can't do much optimization for generic function calls.
2746 You don't need to avoid generic functions because of performance
2747 reasons in general, but if you do find single function call consuming
2748 a large part of execution time and it is calling a generic
2749 function in its inner loop---then it may be worth to modify it.
2750 @c JP
2751 @strong{Generic functions}: Generic function の持つ動的な性質の
2752 ため、これらの呼び出しは通常の手続き呼び出しより遅くなります。
2753 実行時のディスパッチのオーバヘッドだけでなく、
2754 VM コードへのコンパイル時にたいして最適化が行えないためです。
2755 パフォーマンスのために Generic function の利用をどんな場合にも避ける
2756 という必要はありませんが、もしある一つの関数が実行時間の大部分を
2757 占めていて、その関数が Generic function を内部で呼び出しているなら
2758 それを使わないように変更してみる価値はあるでしょう。
2759 @c COMMON
2760
2761 @c EN
2762 @strong{Redefining builtin functions}: Gauche inlines some builtin
2763 functions if they are not redefined. Although sometimes it is useful
2764 to redefine basic functions, you may want to limit the effect.
2765 For example, put redefined functions in a separate module and
2766 use the module in the code that absolutely needs those functions
2767 replaced.
2768 @c JP
2769 @strong{組込み関数の再定義}:
2770 Gauche のコンパイラはいくつかの組込み関数を(それらが再定義されていなければ)
2771 インライン展開します。 基本関数を再定義するのは時には便利ですが、
2772 限られた範囲にとどめておいた方がよいでしょう。
2773 やり方は、再定義をどこか別のモジュールに集めておき、どうしても再定義
2774 バージョンが必要なときに限ってそのモジュール use するというように
2775 しておけばよいでしょう。
2776 @c COMMON
2777
2778 @c EN
2779 @strong{Closure creation}: When you create a closure, its closing environment
2780 is copied to the heap. This overhead is small, but it still may be
2781 visible when a closure is created within an innermost loop that is
2782 called millions of times. If you suspect this is a problem,
2783 try disassemble the function. Gauche's compiler uses some basic
2784 techniques of closure analysis to avoid creating closures for
2785 typical cases, in which case you see the local function's bodies
2786 are inlined. If you see a @code{CLOSURE} instruction, though, it
2787 means a closure is created.
2788 @c JP
2789 @strong{クロージャの作成}: クロージャを作成するとそれが持つ環境がヒープに
2790 コピーされます。 オーバーヘッドは小さいですが、何百万回も呼ばれるような
2791 ループの中で作成されれば無視できなくなるでしょう。そんな疑いがあれば
2792 その関数を逆アセンブルしてみましょう。 Gauche のコンパイラはクロージャの
2793 簡単な解析を行ない生成をなるべく避けるようになっています。そのような場合
2794 局所関数の本体はインライン展開されています。逆アセンブルのコードに
2795 @code{CLOSURE}命令が含まれていれば、残念ながらクロージャが生成されます。
2796 @c COMMON
2797
2798 @c EN
2799 This list isn't complete, and may change when Gauche's implementation
2800 is improved, so don't take this as fixed features.
2801 We'll adjust it occasionally.
2802 @c JP
2803 これらのヒント集は完全でないし、Gauche の改良とともに変わっていくでしょう。
2804 ですから、固定された特徴だとは思わないで下さい。
2805 このヒント集は今後、折を見て実装に対応させて更新してゆきます。
2806 @c COMMON
2807
2808 @c ----------------------------------------------------------------------
2809 @node Auxiliary programs, Writing Gauche modules, Profiling and tuning, Programming in Gauche
2810 @section Auxiliary programs
2811 @c NODE 補助プログラム
2812
2813 @c EN
2814 When you install Gauche, you'll get several auxiliary programs
2815 that help developing Gauche applications.
2816 @c JP
2817 Gaucheをインストールすると、Gaucheでの開発に役立ついくつかの補助プログラムも
2818 インストールされます。
2819 @c COMMON
2820
2821 @table @code
2822 @item gauche-config
2823 @c EN
2824 This program can be used to query various configuation parameters of
2825 installed Gauche.
2826 @c JP
2827 インストールされたGaucheのコンフィグレーションパラメータを問い合わせるプログラムです。
2828 @c COMMON
2829 @item gauche-package
2830 @c EN
2831 Extension package manager. It can be used to install extension
2832 packages and query installed extensions' parameters. You can also use this to
2833 start writing your own extensions.
2834 @c JP
2835 拡張パッケージマネージャ。拡張パッケージをインストールし、またインストールされた
2836 拡張の設定を問い合わせることができます。
2837 自分で新たな拡張を書く際にも使えます。
2838 @c COMMON
2839 @item gauche-install
2840 @c EN
2841 An alternative @code{install} program. Gauche extensions can use
2842 this instead of system's @code{install} command, so that they don't
2843 need to worry about differences among platforms.
2844 @c JP
2845 @code{install}プログラムの代替。Gauche拡張モジュールは、システムの@code{install}
2846 コマンドのかわりにこのプログラムを使えば、プラットフォームごとの細かい違いを
2847 気にする必要がなくなります。
2848 @c COMMON
2849 @item gauche-compile-r7rs
2850 @c EN
2851 This program can be used to create an executable binary from
2852 Gauche scripts.
2853 @c JP
2854 このプログラムはGaucheスクリプトから実行可能バイナリを作るのに使えます。
2855 @c COMMON
2856 @item gauche-cesconv
2857 @end table
2858
2859 @c EN
2860 Additionally, if you configure Gauche with @code{--enable-shared-commands},
2861 the following programs are also installed.
2862 @c JP
2863 さらに、Gaucheのconfigure時に@code{--enable-shared-commands}を渡すと、
2864 以下のプログラムも追加でインストールされます。
2865 @c COMMON
2866
2867 @table @code
2868 @item scheme-r7rs
2869 @itemx scheme-srfi-0
2870 @itemx scheme-srfi-7
2871 @c EN
2872 Those are the names of Scheme interpreter suggeted by SRFI-22.
2873 They are symlinked to @code{gosh}.
2874 @c JP
2875 これらはSRFI-22で推奨されているSchemeインタプリタの標準名です。
2876 @code{gosh}へのシンボリックリンクになります。 
2877 @c COMMON
2878 @item compile-r7rs
2879 @c EN
2880 This is the name of Scheme compiler recommended by SRFI-138.
2881 It is symlinked to @code{gauche-compile-r7rs}.
2882 @c JP
2883 これはSRFI-138で推奨されているSchemeコンパイラ名です。
2884 @code{gauche-compile-r7rs}へのシンボリックリンクになります。
2885 @c COMMON
2886 @end table
2887
2888 @c EN
2889 Since these are common names in the Scheme world, keep in mind that
2890 other Scheme implementations
2891 may already have installed programs with the same name.
2892 @c JP
2893 これらの名前はScheme界で共通のため、他のScheme処理系が同じ名前のプログラムを既に
2894 インストールしているかもしれないことに留意してください。
2895 @c COMMON
2896
2897 @c ----------------------------------------------------------------------
2898 @menu
2899 * Command to query configuration::
2900 * Command to manage extension packages::
2901 * Command to install files::
2902 * Comamnd to compile scripts::
2903 @end menu
2904
2905 @node Command to query configuration, Command to manage extension packages, Auxiliary programs, Auxiliary programs
2906 @subsection @code{gauche-config} - Query configuration
2907 @c NODE 設定を問い合わせる, @code{gauche-config} - 設定を問い合わせる
2908
2909 @deftp {Program} gauche-config [option]
2910 Without options, prints the command usage. With an option, prints
2911 the string associated to the option, which is determined at configuration
2912 time.
2913
2914 Here are some examples. Note that output may vary on your platform.
2915
2916 @itemize @bullet
2917 @item
2918 Print the running architecture:
2919 @example
2920 $ gauche-config --arch
2921 x86_64-pc-linux-gnu
2922 @end example
2923
2924 @item
2925 Print the library flags required to link programs using Gauche:
2926
2927 @example
2928 $ gauche-config -l
2929 -lgauche-0.98 -lmbedtls -lcrypt -lrt -lm -lpthread
2930 @end example
2931
2932 @item
2933 Print the include path flags required to comple Gauche extension.
2934
2935 @example
2936 $ gauche-config -I
2937 -I/usr/lib/gauche-0.98/0.9.15/include
2938 @end example
2939 @end itemize
2940
2941 The command accepts the following arguments. You can only give at most
2942 one.
2943
2944 @c xinclude man-gauche-config.texi
2945
2946 @end deftp
2947
2948
2949 @node Command to manage extension packages, Command to install files, Command to query configuration, Auxiliary programs
2950 @subsection @code{gauche-package} - Manage extension packages
2951 @c NODE 拡張パッケージの管理, @code{gauche-package} - 拡張パッケージの管理
2952
2953 @deftp {Program} gauche-package command [arg @dots{}]
2954 This command can be used to build and install Gauche extensions,
2955 query installed ones, and help start building new ones.
2956 It has several subcommands, which can be listed with
2957 @code{gauche-package help}.
2958 @end deftp
2959
2960
2961 @node Command to install files, Comamnd to compile scripts, Command to manage extension packages, Auxiliary programs
2962 @subsection @code{gauche-install} - Install files
2963 @c NODE ファイルのインストール, @code{gauche-install} - ファイルのインストール
2964
2965 @deftp {Program} gauche-install [options] file dest
2966 @deftpx {Program} gauche-install [options] file @dots{} dir
2967 @deftpx {Program} gauche-install -d [options] dir @dots{}
2968 @deftpx {Program} gauche-install -T dir [options] file @dots{}
2969 @deftpx {Program} gauche-install -U dir [options] file @dots{}
2970 This command can be used to install files. It is upper-compatible
2971 to BSD @code{install} command and can be used as drop-in replacement.
2972 Notably, the first three command invocation format are compatible
2973 with BSD install.
2974 It has several more features that keeps @code{Makefile} concise.
2975
2976 The first and second invocation format copies @var{file}(s) to @var{dest}
2977 (a file pathname) or @var{dir} (an existing directory). You can
2978 specify permissons, owners, etc. Basically it's a fancier @code{cp}.
2979
2980 The third format creates @var{dir}(s) if they don't exist. Basically
2981 it's a fancier @code{mkdir -p}.
2982
2983 The fourth format copies @var{file} @dots{} to @var{dir}. It differs
2984 from the second format in the sense that relative pathname of @var{file}
2985 is preserved. That is, if you run the following command:
2986
2987 @example
2988 gauche-install -T /usr/local/mytool foo.scm bar/baz.scm
2989 @end example
2990
2991 It creates @file{/usr/local/mytool/foo.scm} and
2992 @file{/usr/local/mytool/bar/baz.scm}. With the second format, the
2993 subdirectory @code{bar} won't be created. This format is handy
2994 when you want to install a bunch of subtrees.
2995
2996 The fifth format uninstall files which would be installed with @code{-T}
2997 option. Simply change @code{-T} option to @code{-U} option and you'll
2998 clean the files.
2999
3000 The following command-line arguments are recognized.
3001
3002 @table @option
3003 @item -C
3004 @itemx --canonical-suffix
3005 If installed file has a suffix @file{.sci}, replace
3006 it for @file{.scm}. This is Gauche specific convention.
3007 @item -T dir
3008 @itemx --target dir
3009 Installs files to the @var{dir}, creating paths if needed.
3010 Partial path of files are preserved. (4th format only)
3011 @item -U dir
3012 @itemx --uninstall dir
3013 Reverse the effect of @code{-T}, e.g. removes files from its
3014 destination @var{dir}.
3015 @item -S dir
3016 @itemx --srcdir dir
3017 Look for @var{file} @dots{} within @var{dir}; useful if @code{VPATH} is used.
3018 @item --shebang path
3019 Adds @code{#!@var{path}} before the file contents.
3020 Useful to install scripts.
3021 @item -d
3022 @itemx --directory
3023 Creates directories. (3rd format only).
3024 @item -m mode
3025 @itemx --mode mode
3026 Change mode of the installed file.
3027 @item -p prefix
3028 @itemx --strip-prefix prefix
3029 Strip prefix dirs from @var{file} @dots{} before
3030 installation. (4th/5th format only).
3031 @item -o owner
3032 @itemx --owner owner
3033 Change owner of the installed file(s).
3034 @item -g group
3035 @itemx --group group
3036 Change group of the installed file(s).
3037 @item -v
3038 @itemx --verbose
3039 Work verbosely
3040 @item -d
3041 @itemx --dry-run
3042 Just prints what actions are to be done, but won't execute them.
3043 @end table
3044 @end deftp
3045
3046
3047 @node Comamnd to compile scripts, , Command to install files, Auxiliary programs
3048 @subsection @code{gauche-compile-r7rs} - Compile scripts
3049 @c NODE スクリプトのコンパイル, @code{gauche-compie-r7rs} - スクリプトのコンパイル
3050
3051 For Gauche-specific programs, we have @code{tools/build-standalone} Scheme
3052 script (@pxref{Building standalone executables}). We recommend
3053 that script, for it is more featureful.
3054
3055 The @code{gauche-compile-r7rs} and @code{compile-r7rs} script is provided
3056 so that you can invoke a 'Scheme compiler' with a standardized manner.
3057 It may be handy if other tools (e.g. IDE) need to invoke a Scheme
3058 compiler as a subprocess.
3059
3060 This interface is defined in SRFI-138, which also suggests the name
3061 @code{compile-r7rs}. We only install @code{gauche-compile-r7rs} by
3062 default so that we won't accidentally clobber other implementation's
3063 program, but if you give @code{--enable-shared-commands} option to
3064 @code{configure} script, a symbolic link @code{compile-r7rs} is created.
3065
3066 @deftp {Program} gauche-compile-r7rs [options] script.scm
3067 @deftpx {Program} compile-r7rs [options] script.scm
3068 Compile a Scheme source file @code{script.scm} and produce an
3069 executable binary. The @code{compile-r7rs} is only installed
3070 if Gauche is configured with @code{--enable-shared-commands}.
3071
3072 Note: SRFI-138 states that if the environment variable
3073 @code{COMPILE_R7RS} is defined, it is assumed to a pathname of another
3074 program and is executed instead of Gauche's @code{compile-r7rs}.
3075 We think the feature is rather confusing than convenient, so we
3076 don't support it. If you want to run alternative implementation's
3077 compiler, there are more explicit means such as running it directly
3078 or change @code{PATH}.
3079
3080 The following command-line arguments are recognized.
3081
3082 @table @option
3083 @item -I path
3084 @itemx -A path
3085 Prepend or append @var{path} to the path list the referenced
3086 libraries are searched. These options can be specified multiple times.
3087
3088 @item -o outfile
3089 Specifies output executable filename. When omitted, @code{a.out}
3090 (on POSIX systems) or @code{a.exe} (on Windows) are used.
3091
3092 @item -D feature-id
3093 Adds @code{feature-id} to the list of feature identifiers.
3094 This is to switch code conditionally in the source with
3095 @code{cond-expand}.
3096 This option can be specified multiple times.
3097
3098 Note that this does @emph{not} enable certain features. So you
3099 shouldn't specify system-reserved feature identifiers
3100 (@pxref{Platform-dependent features}). This is also different
3101 from @code{-D} option of @code{tools/build-standalone}.
3102 @end table
3103 @end deftp
3104
3105
3106 @c ----------------------------------------------------------------------
3107 @node Writing Gauche modules, Using extension packages, Auxiliary programs, Programming in Gauche
3108 @section Writing Gauche modules
3109 @c NODE Gaucheのモジュールを書く
3110
3111 @c EN
3112 Gauche's libraries are organized by modules. Although Gauche
3113 can load any valid Scheme programs, there is a convention that
3114 Gauche's libraries follow. When you write a chunk of Scheme
3115 code for Gauche, it is convenient to make it a module,
3116 so that it can be shared and/or reused.
3117 @c JP
3118 Gaucheのライブラリはモジュール毎に整理されています。Gaucheはどんな形式でも、
3119 有効なScheme式が書かれてさえいればロードすることができますが、
3120 Gaucheのライブラリは一定の形式を保って書かれています。
3121 Gauche用にまとまったSchemeコードを書いたら、それをモジュール形式にしておくと
3122 再利用がしやすくなるでしょう。
3123 @c COMMON
3124
3125 @c EN
3126 Usually a module is contained in a file, but you can make
3127 a multi-file module.
3128 First I explain the structure of a single-file module.
3129 The following template is the convention used in Gauche's libraries.
3130 @c JP
3131 通常ひとつのファイルで
3132 ひとつのモジュールを定義しますが、モジュールを複数のファイルに分けることもできます。
3133 まずひとつのファイルでモジュールを定義する方法を説明します。
3134 Gaucheのライブラリで使われているテンプレートは次のような形式です。
3135 @c COMMON
3136
3137 @example
3138 @c EN
3139 ;; Define the module interface
3140 @c JP
3141 ;; モジュールのインタフェースの定義
3142 @c COMMON
3143 (define-module foo
3144 (use xxx)
3145 (use yyy)
3146 (export foo1 foo2 foo3)
3147 )
3148 @c EN
3149 ;; Enter the module
3150 @c JP
3151 ;; モジュール本体
3152 @c COMMON
3153 (select-module foo)
3154
3155 @dots{} module body @dots{}
3156
3157 @end example
3158
3159 @c EN
3160 This file must be saved as ``foo.scm'' in some directory in the
3161 @code{*load-path*}.
3162 @c JP
3163 このファイルは``foo.scm''という名で、@code{*load-path*}にあるディレクトリの
3164 いずれかに置かれなければなりません。
3165 @c COMMON
3166
3167 @c EN
3168 The @code{define-module} form creates a module @code{foo}.
3169 It also loads and imports some other modules by `@code{use}' macros,
3170 and declares which symbols the @code{foo} module exports, by `@code{export}'
3171 syntax.
3172 (See section @ref{Defining and selecting modules}, for detailed specification of those
3173 syntaxes).
3174 @c JP
3175 まず、@code{define-module}フォームがモジュール@code{foo}を作成します。
3176 @code{define-module}フォーム内で、このモジュールが依存している他のモジュール
3177 を `@code{use}' マクロを使ってロードし、このモジュールがエクスポートするシンボルを
3178 `@code{export}' 構文を使って指定します。(これらの構文の詳細は@ref{Defining and selecting modules}を
3179 参照して下さい)。
3180 @c COMMON
3181
3182 @c EN
3183 Those @code{use} forms or @code{export} forms are not required to appear
3184 in the @code{define-module} form, but it is a good convention to keep
3185 them in there at the head of the file so that it is visually recognizable
3186 which modules @code{foo} depends and which symbols it exports.
3187 @c JP
3188 これらの@code{use}フォームや@code{export}フォームは必ずしも@code{define-module}
3189 フォームの先頭に置く必要はありませんが、このようにファイルの最初の方に固めておくことで、
3190 @code{foo}が依存しているモジュール群や@code{foo}が提供するシンボル等が
3191 一覧しやすくなります。
3192 @c COMMON
3193
3194 @c EN
3195 The second form, `@code{select-module}',
3196 specifies the rest of the file is evaluated in the
3197 module @code{foo} you just defined. Again, this is just a
3198 convention; you can write entire module body inside @code{define-module}.
3199 However, I think it is error-prone, for the closing parenthesis
3200 can be easily forgotten or the automatic indentation mechanism of
3201 editor will be confused.
3202 @c JP
3203 次の、`@code{select-module}' フォームにより、それ以降のScheme式が
3204 モジュール@code{foo}の中で評価されます。モジュールの内容を全て@code{define-module}の中に
3205 書いてしまうことも出来ますが、最後の括弧を閉じ忘れやすいことや、エディタのインデントが
3206 狂うことなどから、あまりお薦めしません。
3207 @c COMMON
3208
3209 @c EN
3210 After @code{select-module} you can write whatever Scheme expression.
3211 It is evaluated in the selected module, @code{foo}. Only the bindings
3212 of the exported symbols will be directly accessible from outside.
3213 @c JP
3214 @code{select-module}フォームの後には、モジュールの内容であるScheme式を自由に書けます。
3215 それらはモジュール@code{foo}の中で評価されます。モジュール内で定義するトップレベルの
3216 束縛のうち、明示的に`export'で指定されたシンボルのみが、このモジュールをインポートする他の
3217 モジュールから見えます。
3218 @c COMMON
3219
3220 @c EN
3221 So, that's it. Other programs can use your module by just saying
3222 `@code{(use foo)}'. If you want to make your module available on your site,
3223 you can put it to the site library location, which can be obtained by
3224 @example
3225 (gauche-site-library-directory)
3226 @end example
3227 in gosh, or
3228 @example
3229 gauche-config --sitelibdir
3230 @end example
3231 from shell.
3232 @c JP
3233 これで、他のプログラムは `@code{(use foo)}' とするだけでこのモジュールの機能が
3234 利用可能になります。もしモジュールをサイト全体で利用できるようにしたければ、@code{gosh}内で
3235 @example
3236 (gauche-site-library-directory)
3237 @end example
3238 を評価して得られるディレクトリに@code{foo.scm}を置いて下さい。
3239 @c COMMON
3240
3241 @c EN
3242 If you feel like to conserve global module name space, you can organize
3243 modules hierarchically. Some Gauche libraries already does so.
3244 @xref{Library modules - Overview}, for examples.
3245 For example, @code{text.tr} module is implemented in ``text/tr.scm'' file.
3246 Note that the pathname separator `/' in the file becomes a period in the
3247 module name.
3248 @c JP
3249 モジュールの名前空間のトップに新たなモジュールを追加するのに気が引ける場合は、
3250 モジュールを階層的に構成することもできます。Gaucheのモジュールの多くは既に階層的に
3251 構成されています。具体的なモジュール例は@ref{Library modules - Overview}を参照して下さい。
3252 例えば、@code{text.tr}モジュールは ``@code{text/tr.scm}'' ファイルに
3253 実装されています。パス名の区切り文字`/'がモジュール名ではピリオドになることに
3254 注意して下さい。
3255 @c COMMON
3256
3257 @c ----------------------------------------------------------------------
3258 @node Using extension packages, Building standalone executables, Writing Gauche modules, Programming in Gauche
3259 @section Using extension packages
3260 @c NODE 拡張パッケージの使用
3261
3262 @c EN
3263 @subheading Building and installing packages
3264 @c JP
3265 @subheading パッケージの構築とインストール
3266 @c COMMON
3267
3268 @c EN
3269 Gauche comes with some amount of libraries, but they aren't
3270 enough at all to use Gauche in the production environment.
3271 There are number of additional libraries available. We call them
3272 @emph{extension packages}, or simply packages. Each package
3273 usually provides one or more modules that adds extra
3274 functionality. Most of the packages provide
3275 binding to other C libraries, such as graphics libraries
3276 or database clients. If the package has some C code,
3277 it is likely that you need to compile it on your machine with
3278 the installed Gauche system.
3279 @c JP
3280 Gauche にはまとまったライブラリが付属していますが、
3281 Gauche をプロダクション環境で利用するのにはとても十分とはいえません。
3282 利用可能な追加ライブラリもいくつもあります。こうしたライブラリを
3283 @emph{拡張パッケージ}、あるいは単にパッケージといいます。それぞれの
3284 パッケージは追加機能を提供するひとつあるいはそれ以上のモジュールを
3285 提供します。ほとんどのパッケージは別のCのライブラリへのバインディングを
3286 提供しています。たとえば、グラフィックスライブラリとかデータベース
3287 クライアントなどです。もし、パッケージがいくぶんでもCのコードを含む
3288 場合は、利用するマシン上で、既にインストールされている Gauche システムを
3289 使って、そのコードをコンパイルする必要があります。
3290 @c COMMON
3291
3292 @c EN
3293 Usually a package is in the form of compressed tarball, and the standard
3294 "ungzip + untar + configure + make + make install" sequence does the job.
3295 Read the package's document, for you may be able to tailor
3296 the library for your own needs by giving command-line options
3297 to the @code{configure} script.
3298 @c JP
3299 通常、パッケージは圧縮 tarball の形式になっています。標準的には、
3300 「gzの解凍 + tarの展開 + configure + make + make install」とやればよいように
3301 なっています。パッケージのドキュメントを読めば、必要に応じて、
3302 @code{configure} スクリプトに与えるコマンドラインオプションで
3303 ライブラリを調整できるようになっています。
3304 @c COMMON
3305
3306 @c EN
3307 From Gauche 0.8, an utility script called @code{gauche-package} is
3308 installed for the convenience. It automates the build and install
3309 process of packages.
3310 @c JP
3311 Gauche 0.8 より、@code{gauche-package} というユーティリティスクリプトが
3312 インストールされるようになっています。これはパッケージの構築と
3313 インストールを自動化します。
3314 @c COMMON
3315
3316 @c EN
3317 Suppose you have downloaded a package @file{Package-1.0.tar.gz}.
3318 If the package follows the convention, all you have to do is
3319 to type this:
3320 @c JP
3321 @file{Package-1.0.tar.gz} というパッケージをダウンロードしてきた
3322 としましょう。もし、このパッケージが慣例に従っていれば、やることは
3323 @c COMMON
3324
3325 @example
3326 $ gauche-package install Package-1.0.tar.gz
3327 @end example
3328
3329 @c EN
3330 It ungzips and untars the package, @code{cd} into the @file{Package-1.0}
3331 subdirectory, run configure, make, and make install.
3332 By default, @code{gauche-package} untars the tarball in the current
3333 working directory. You can change it by a customization file; see below.
3334 @c JP
3335 とタイプするだけです。
3336 これで、gzip圧縮ファイルの解凍、tarアーカイブファイルの展開、
3337 @file{Package-1.0} サブディレクトリへの移動、configure スクリプトの
3338 実行、make、make install が行われます。デフォルトでは、
3339 @code{gauche-package} はカレントディレクトリに tarball を展開します。
3340 これをカスタマイズファイル(後述)で変更することができます。
3341 @c COMMON
3342
3343 @c EN
3344 If you need a special privilege to install the files, you can
3345 use @code{--install-as} option which runs @code{make install} part via
3346 the @code{sudo} program.
3347 @c JP
3348 ファイルをインストールするのに特別な権限が必要な場合には、
3349 @code{--install-as} というオプションを使うと、@code{make install}
3350 部分が、@code{sudo} を使って実行されます。
3351 @c COMMON
3352
3353 @example
3354 $ gauche-package install --install-as=root Package-1.0.tar.gz
3355 @end example
3356
3357 @c EN
3358 If it doesn't work for you, you can just build the package
3359 by @code{gauche-package build Package-1.0.tar.gz}, then
3360 manually cd to the @file{Package-1.0} directory and run
3361 @code{make install}.
3362 @c JP
3363 上手くいかない場合には、@code{gauche-package build Package-1.0.tar.gz}
3364 とやってパッケージの構築だけすることもできます。この場合、手で
3365 @file{Package-1.0} ディレクトリに移動して、@code{make install} を
3366 実行します。
3367 @c COMMON
3368
3369 @c EN
3370 You can give configuration options via @code{-C} or @code{--configure-options}
3371 command-line argument, like this:
3372 @c JP
3373 設定オプションを @code{-C} あるいは @code{--configure-options}
3374 というコマンドライン引数で与えられます。たとえば、
3375 @c COMMON
3376
3377 @example
3378 $ gauche-package install -C "--prefix=/usr/local" Package-1.0.tar.gz
3379 @end example
3380
3381 @c EN
3382 If the package has adopted the new package description file,
3383 it can remember the configuration options you have specified, and
3384 it will automatically reuse them when you install the package
3385 again. (If you're a package developer, check out
3386 @file{examples/spigot/README} file in the Gauche source tree
3387 to see how to cooperate with Gauche's package management system.)
3388 @c JP
3389 もしパッケージがこの新しい記述ファイルを採用しているなら、
3390 以前に指定した設定オプションを記憶していて、そのパッケージを
3391 再度インストールするときには、自動的にそれを再利用します。
3392 (パッケージ開発者の方は、Gauche のソースツリーにある、
3393 @file{examples/spigot/README} ファイルをチェックアウトすれば、
3394 どのように Gauche のパッケージマネージメントシステムがやっているかを
3395 見られます。)
3396 @c COMMON
3397
3398 @c EN
3399 If you don't have a tarball in your local directory, but you know
3400 the URL where you can download it, you can directly give the URL
3401 to @code{gauche-package}. It understands @code{http} and @code{ftp},
3402 and uses either @code{wget} or @code{ncftpget} to download the tarball,
3403 then runs configure and make.
3404 @c JP
3405 tarball がローカルディレクトリにない場合でも、ダウンロードしてくる
3406 URL を知っているなら、その URL を直接 @code{gauche-package} に与える
3407 ことができます。@code{gauche-package} は @code{http} および @code{ftp}
3408 を理解し、@code{wget} か @code{ncftpget} のどちらかを使って、その
3409 tarball をダウンロードし、configure および make を実行します。
3410 @c COMMON
3411
3412 @example
3413 $ gauche-package install http://www.example.com/Package-1.0.tar.gz
3414 @end example
3415
3416 @c EN
3417 @subheading Customizing @code{gauche-package}
3418 @c JP
3419 @subheading @code{gauche-package} のカスタマイズ
3420 @c COMMON
3421
3422 @c EN
3423 The @code{gauche-package} program reads @file{~/.gauche-package} if
3424 it exists. It must contain an associative list of parameters.
3425 It may look like this:
3426 @c JP
3427 @code{gauche-package} プログラムは @file{~/.gauche-package} があれば、
3428 それを読みます。このファイルにはパラメータの連想リストが含まれて
3429 いなければなりません。こんな感じです。
3430 @c COMMON
3431
3432 @example
3433 (
3434 (build-dir . "/home/shiro/tmp")
3435 (gzip . "/usr/local/bin/gzip")
3436 (bzip2 . "/usr/local/bin/bzip2")
3437 (tar . "/usr/local/bin/gtar")
3438 )
3439 @end example
3440
3441 @c EN
3442 The following is a list of recognized parameters.
3443 If the program isn't given in the configuration file, @code{gauche-package}
3444 searches @code{PATH} to find one.
3445 @c JP
3446 以下は、認識されるパラメータのリストです。
3447 設定ファイルにプログラムが与えられていなければ、@code{gauche-package}
3448 は @code{PATH} を探します。
3449 @c COMMON
3450
3451 @c EN
3452 @table @code
3453 @item build-dir
3454 A directory where the tarball is extracted. If URL is given,
3455 the downloaded file is also placed in this directory.
3456 @item bzip2
3457 Path to the program @code{bzip2}.
3458 @item cat
3459 Path to the program @code{cat}.
3460 @item make
3461 Path to the program @code{make}.
3462 @item ncftpget
3463 Path to the program @code{ncftpget}.
3464 @item rm
3465 Path to the program @code{rm}.
3466 @item sudo
3467 Path to the program @code{sudo}.
3468 @item tar
3469 Path to the program @code{tar}.
3470 @item wget
3471 Path to the program @code{wget}.
3472 @end table
3473 @c JP
3474 @table @code
3475 @item build-dir
3476 tarball が展開されるディレクトリ。もし、URL が与えられれば、
3477 ダウンロードされたファイルはこのディレクトリに置かれます。
3478 @item bzip2
3479 @code{bzip2} プログラムへのパス
3480 @item cat
3481 @code{cat} プログラムへのパス
3482 @item make
3483 @code{make} プログラムへのパス
3484 @item ncftpget
3485 @code{ncftpget} プログラムへのパス
3486 @item rm
3487 @code{rm} プログラムへのパス
3488 @item sudo
3489 @code{sudo} プログラムへのパス
3490 @item tar
3491 @code{tar} プログラムへのパス
3492 @item wget
3493 @code{wget} プログラムへのパス
3494 @end table
3495 @c COMMON
3496
3497 @c ----------------------------------------------------------------------
3498 @node Building standalone executables, , Using extension packages, Programming in Gauche
3499 @section Building standalone executables
3500 @c NODE スタンドアロン実行可能ファイルの作成
3501
3502 @c EN
3503 When you want to distribute your Gauche scripts or applications,
3504 the users need to install Gauche runtime on their machine.
3505 Although it is always the case for any language implementations---you need
3506 Java runtime to run Java applications, or C runtime to run
3507 C applications---it may be an extra effort to ask users to install
3508 not-so-standard language runtimes.
3509 @c JP
3510 Gaucheで作ったスクリプトやアプリケーションを配布する場合、
3511 ユーザはGaucheのランタイムを手元のマシンにインストールする必要があります。
3512 これは原理的にはどんな言語でも同じことです--Javaアプリケーションを使うなら
3513 Javaランタイムが必要ですし、Cアプリケーションを使うならCランタイムが必要です。
3514 けれどもGaucheのようなマイナーな言語処理系のランタイムをインストールしてくれることを
3515 ユーザにお願いするのは、ややハードルが高いでしょう。
3516 @c COMMON
3517
3518 @c EN
3519 To ease distribution of Gauche applications, you can create a
3520 stand-alone executable. It statically links entire Gauche system
3521 so that it runs by just copying the executable file.
3522 @c JP
3523 Gaucheのアプリケーションの配布を簡単にするために、
3524 スタンドアロン実行ファイルを作ることができます。
3525 これは、Gaucheシステム全体をスタティックリンクし、
3526 ファイルひとつコピーすれば使えるような実行ファイルを生成します。
3527 @c COMMON
3528
3529 @c EN
3530 Gauche also provides a @code{compile-r7rs} program that is compliant
3531 with the command-line interface presented in SRFI 138
3532 (@url{https://srfi.schemers.org/srfi-138/srfi-138.html}).
3533 @xref{Comamnd to compile scripts}, for the details.
3534 @c JP
3535 Gaucheはまた、SRFI 138が定義するコマンドラインインターフェイスに
3536 準拠する@code{compile-r7rs}スクリプトも提供します。
3537 (@url{https://srfi.schemers.org/srfi-138/srfi-138.html})
3538 詳しくは@ref{Comamnd to compile scripts}を参照してください。
3539 @c COMMON
3540
3541 @c EN
3542 @subheading Quick recipe
3543 @c JP
3544 @subheading 簡単な使い方
3545 @c COMMON
3546
3547 @c EN
3548 To generate a standalone executable, just give your script file
3549 to the @file{tools/build-standalone} script, which is installed as a
3550 part of Gauche.
3551 @c JP
3552 スタンドアロンな実行可能ファイルを作るには、Gaucheのインストール時に一緒に
3553 インストールされる@file{tools/build-standalone}にスクリプトファイルを与えるだけです。
3554 @c COMMON
3555
3556 @example
3557 gosh tools/build-standalone yourscript.scm
3558 @end example
3559
3560 @c EN
3561 It will create an executable file @code{yourscript} (or @code{yourscript.exe}
3562 on Windows) in the current directory.
3563 @c JP
3564 これで、実行可能ファイル@code{yourscript} (Windowsでは@code{yourscript.exe})
3565 がカレントディレクトリに作られます。
3566 @c COMMON
3567
3568 @c EN
3569 To specify the output name different from the script name,
3570 give @code{-o} option:
3571 @c JP
3572 スクリプト名とは別に実行ファイル名を指定したい場合は@code{-o}オプションを使います。
3573 @c COMMON
3574
3575 @example
3576 gosh tools/build-standalone -o yourcommand yourscript.scm
3577 @end example
3578
3579 @c EN
3580 When your script needs supporting library files, you should list
3581 those files as well:
3582 @c JP
3583 スクリプトが他のサポートライブラリコードを必要とする場合は、
3584 そのライブラリファイルも一緒に指定します。
3585 @c COMMON
3586
3587 @example
3588 gosh tools/build-standalone yourscript.scm lib/library1.scm lib/library2.scm
3589 @end example
3590
3591 @c EN
3592 The library file paths need to be relative to the respective load path.
3593 See the explanation of @code{-I} option below.
3594 @c JP
3595 ライブラリファイルのパス名は、@code{load}がそのファイルを見つけられるような、
3596 ロードパスからの相対パスである必要があります。
3597 詳しくは下の@code{-I}オプションの説明を見てください。
3598 @c COMMON
3599
3600 @c EN
3601 @subheading Catches
3602 @c JP
3603 @subheading 注意点
3604 @c COMMON
3605
3606 @c EN
3607 There are a few things you should be aware of.
3608 @c JP
3609 いくつか、気をつけなければならないことがあります。
3610 @c COMMON
3611
3612 @itemize
3613 @item
3614 @c EN
3615 The size of the binary tend to be large, since it contains the entire
3616 Gauche system regardless of whether your application use it or not.
3617 You can strip down the size if you need to, but you need to rebuild
3618 Gauche library to do so. See @file{doc/HOWTO-standalone.txt} in the
3619 source tree for the details.
3620 @c JP
3621 アプリケーションが使うかどうかに関わらず、バイナリにはGaucheシステム全てが含まれるので、
3622 バイナリのサイズはかなり大きくなります。
3623 サイズが問題になるなら使わないライブラリを削除することもできますが、
3624 それにはGaucheライブラリをリビルドしなければなりません。詳しくは
3625 ソースツリーにある@file{doc/HOWTO-standalone.txt}を参照してください。
3626 @c COMMON
3627
3628 @item
3629 @c EN
3630 The generated binary still depends on external dynamically linked
3631 libraries, such as libpthread. The exact dependency may differ
3632 how Gauche is configured, and can be checked
3633 by running system-provided tools,
3634 such as @code{ldd} on most Unix systems and MinGW or @code{otool -L} on OSX,
3635 on the generated standalone binaries.
3636 You may want to ensure the users have required libraries.
3637 @c JP
3638 作られたバイナリファイルは、libpthreadなど外部の動的ライブラリには依存します。
3639 具体的にどのライブラリに依存するかはプラットフォームとGaucheのコンフィグレーションによります。
3640 確かめるには、生成されたバイナリファイルに対してシステムのツール
3641 (多くのUnixやMinGWなら@code{ldd}、OSXなら@code{otool -L}など)を
3642 走らせて下さい。
3643 ユーザ環境にもそれらの動的ライブラリが入っている必要があります。
3644 @c COMMON
3645
3646 @item
3647 @c EN
3648 Currently we don't yet have a convenient way to statically link
3649 extension libraries. We're working on it.
3650 @c JP
3651 Gaucheの拡張ライブラリをスタティックリンクする機能についてはまだ開発中です。
3652 @c COMMON
3653
3654 @item
3655 @c EN
3656 If Gauche is configured to use gdbm, it is linked to the standalone binary
3657 by default, hence the binary itself is covered by GPL. In case if you
3658 need to distribute binaries under BSD license, you need to give
3659 @code{-D GAUCHE_STATIC_EXCLUDE_GDBM} flag to @code{tools/build-standalone}.
3660 It makes @code{tools/build-standalone} not to link gdbm (and your script won't
3661 be able to use it).
3662 @c JP
3663 Gaucheがgdbmを使うようにコンフィグされていた場合、実行可能ファイルにもgdbmが
3664 スタティックリンクされるので、実行可能ファイルの配布ライセンスがGPLになります。
3665 もしGPLでなくBSDライセンスで配布したい場合は、@code{tools/build-standalone}スクリプトに
3666 @code{-D GAUCHE_STATIC_EXCLUDE_GDBM}フラグを与えてください。
3667 そうするとgdbmはリンクされなくなります(その場合、スクリプトからgdbmは使えません)。
3668 @c COMMON
3669
3670 @item
3671 @c EN
3672 If you build Gauche with mbedTLS support (if you have libmbedtls on
3673 your machine, Gauche include its support by default), the resulting standalone
3674 binary also depends on libmbedtls DSO files. If you're not sure mbedTLS
3675 DSO files are available on target machines, you can exclude
3676 @code{rfc.tls.mbed} module by giving
3677 @code{-D GAUCHE_STATIC_EXCLUDE_MBED} flag to @code{tools/build-standalone}.
3678 @c JP
3679 もしGaucheがmbedTLSサポートつきでビルドされていた場合
3680 (libmbedtlsがシステムにインストールされていると、デフォルトでそのサポートはonになります)、
3681 作られるスタンドアローンバイナリはlibmbedtls DSOファイルに依存します。
3682 ターゲットマシンにmbedTLSがインストールされているとは限らない場合は、
3683 @code{tools/build-standalone}に@code{-D GAUCHE_STATIC_EXCLUDE_MBED}フラグを与えることで、
3684 @code{rfc.tls.mbed}モジュールへの依存を除外することができます。
3685 @c COMMON
3686
3687 @end itemize
3688
3689 @menu
3690 * Using build-standalone::
3691 @end menu
3692
3693 @node Using build-standalone, , Building standalone executables, Building standalone executables
3694 @subsection Using build-standalone
3695 @c NODE build-standaloneスクリプトを使う
3696
3697 @deftp {Program} {gosh tools/build-standalone} [options] script-file [library-file @dots{}]
3698 @c EN
3699 Create a stand-alone binary to execute a Gauche program in @var{script-file}.
3700 It is executed as if it is run as @code{gosh script-file}, with a few
3701 differences.
3702 @c JP
3703 @var{script-file}に記されたGaucheプログラムを実行するスタンドアロンの
3704 バイナリ実行可能ファイルを生成します。作られた実行可能ファイルを実行すると、
3705 多少の違いを除いては、あたかも@code{gosh script-file}を実行したのと同じ動作になります。
3706 @c COMMON
3707
3708 @c EN
3709 The main thing is that since @var{script-file} is no longer
3710 loaded from file, code that references paths relative to @var{script-file} won't
3711 work. One example is @code{(add-load-path dir :relative)}
3712 (@pxref{Loading Scheme file}). Auxiliary library files required by
3713 @var{script-file} must be explicitly
3714 listed as @var{library-file} @dots{}, so that
3715 they are bundled together into the executable.
3716 @c JP
3717 違いの重要な点は、実行可能ファイルでは@var{script-file}がファイルシステムからロード
3718 されないため、@var{script-file}のパスからの相対パスで何かを参照しているコードは
3719 動かなくなるということです。例えば@code{(add-load-path dir :relative)}
3720 で補助ライブラリを参照しているような場合です(@ref{Loading Scheme file}参照)。
3721 @var{script-file}に必要な補助ライブラリはコマンドラインの@var{library-file} @dots{}に
3722 明示的に与えられなければなりません。それらは実行可能ファイルに同梱されます。
3723 @c COMMON
3724 @end deftp
3725
3726 @c EN
3727 The following command-line options are recognized.
3728 @c JP
3729 以下のコマンドラインオプションが使えます。
3730 @c COMMON
3731
3732 @deftp {Command Option} -o outfile
3733 @c EN
3734 Specifies output executable filename. When omitted, the basename of
3735 @var{script-file} without extension is used.
3736 (Or, on Windows, swapping extension with @code{.exe}).
3737 @c JP
3738 出力される実行可能ファイルの名前を指定します。省略された場合は@var{script-file}の
3739 basenameから拡張子を除いたものになります。
3740 (Windowsの場合は拡張子を@code{.exe}に変えたもの)
3741 @c COMMON
3742 @end deftp
3743
3744 @deftp {Command Option} -D var[=val]
3745 @c EN
3746 Add C preprocessor definitions while compiling the generated C code.
3747 An important use case of this option is to exclude gdbm dependency
3748 from the generated binaries, by specifying
3749 @code{-D GAUCHE_STATIC_EXCLUDE_GDBM}. Note that you need a whitespace
3750 between @code{-D} and @var{var}.
3751
3752 This option can be specified multiple times.
3753 @c JP
3754 中間で生成されるCコードをコンパイルする際に、Cプリプロセッサ定義を追加します。
3755 使用例のひとつは、@code{-D GAUCHE_STATIC_EXCLUDE_GDBM}を指定することで
3756 生成される実行可能ファイルからgdbmへの依存を取り除くというものです。
3757 @code{-D}と@var{var}の間に空白が必要なことに注意してください。
3758
3759 このオプションは複数指定できます。
3760 @c COMMON
3761 @end deftp
3762
3763 @deftp {Command Option} -I load-path
3764 @c EN
3765 Specifies the load path where @var{library-file} @dots{} are searched.
3766 The names given to @var{library-file} must match how they are @code{load}ed
3767 or @code{use}d. If such paths are not relative to the directory
3768 you run @code{tools/build-standalone}, you have to tell where to find
3769 those libraries with this option.
3770
3771 For example, suppose you have this structure:
3772 @c JP
3773 @var{library-file} @dots{}が検索されるロードパスを指定します。
3774 @var{library-file}に与えられるパス名は、それらをロードするために
3775 @code{load}や@code{use}に与えられるパス名と一致している必要があります。
3776 もし@code{tools/build-standalone}を走らせるディレクトリから見て
3777 これらのファイルが置かれている相対パスが必要なものと違っていた場合、
3778 このオプションを指定してどのディレクトリからの相対でファイルを探すかを
3779 教えてやらないとなりません。
3780
3781 例えばソースが次のとおり構成されていたとしましょう。
3782 @c COMMON
3783
3784 @example
3785 project/src/
3786 +----- main.scm
3787 | (use myscript.util)
3788 +----- myscript/util.scm
3789 (define-module myscript.util ...)
3790 @end example
3791
3792 @c EN
3793 If you run @code{tools/build-standalone} in the directory as @file{src},
3794 you can just say this:
3795 @c JP
3796 @code{tools/build-standalone}を@file{src}の下で実行する場合は、
3797 単に次のとおり実行すれば済みます。
3798 @c COMMON
3799
3800 @example
3801 gosh tools/build-standalone main.scm myscript/util.scm
3802 @end example
3803
3804 @c EN
3805 But if you run it under @file{project}, you need to say this:
3806 @c JP
3807 しかし、@file{project}の下で実行する場合は次のようにしなければなりません。
3808 @c COMMON
3809
3810 @example
3811 gosh tools/build-standalone -I src src/main.scm myscript/util.scm
3812 @end example
3813
3814 @c EN
3815 Another example; you have a separate library directory:
3816 @c JP
3817 別の例を挙げましょう。ライブラリのディレクトリが分かれている場合です。
3818 @c COMMON
3819
3820 @example
3821 project/
3822 +----- src/main.scm
3823 | (use myscript.util)
3824 +----- lib/myscript/util.scm
3825 (define-module myscript.util ...)
3826 @end example
3827
3828 @c EN
3829 If you run @code{tools/build-standalone} in @file{src}, you say this:
3830 @c JP
3831 @code{tools/build-standalone}を@file{src}以下で走らせる場合は次のようにします。
3832 @c COMMON
3833
3834 @example
3835 gosh tools/build-standalone -I ../lib main.scm myscript/util.scm
3836 @end example
3837
3838 @c EN
3839 Or, if you run it in @file{project}, you say this:
3840 @c JP
3841 @file{project}以下で走らせる場合はこうなります。
3842 @c COMMON
3843
3844 @example
3845 gosh tools/build-standalone -I lib src/main.scm myscript/util.scm
3846 @end example
3847
3848 @c EN
3849 This option can be specified multiple times.
3850 @c JP
3851 このオプションは複数指定できます。
3852 @c COMMON
3853 @end deftp
3854
3855 @deftp {Command Option} --header-dir dir
3856 @deftpx {Command Option} --library-dir dir
3857 @c EN
3858 These tells @code{tools/build-standalone} where to find Gauche C headers
3859 and static libraries.
3860
3861 If you've installed Gauche on your system, @code{tools/build-standalone}
3862 automatically finds these from the installed directory and you don't
3863 need to worry about them. Use these option only when
3864 you need to use Gauche runtime that's not installed.
3865 @c JP
3866 これらのオプションは@code{tools/build-standalone}が必要なGaucheのCヘッダファイルや
3867 スタティックライブラリをどこから探すかを指定します。
3868
3869 Gaucheが既にシステムにインストール済みであれば、@code{tools/build-standalone}は
3870 インストールされたディレクトリから自動的に必要なファイルを探すので、
3871 このオプションを気にする必要はありません。インストールしていないGaucheのランタイムを
3872 利用したい場合のみこれらのオプションを指定してください。
3873 @c COMMON
3874 @end deftp
3875
3876
3877 @c Local variables:
3878 @c mode: texinfo
3879 @c coding: utf-8
3880 @c end: