For Development HEAD DRAFTSearch (procedure/syntax/module):

3.1 Invoking Gosh

Gauche can be used either as an independent Scheme scripting engine or as an embedded Scheme library. An interactive interpreter which comes with Gauche distribution is a program named gosh.

Program: gosh [options] [scheme-file arg …]

Gauche’s interpreter. Without scheme-file, gosh works interactively, i.e. it reads a Scheme expression from the standard input, evaluates it, and prints the result, and repeat that until it reads EOF or is terminated.

If gosh is invoked without scheme-file, but the input is not a terminal, it enters read-eval-print loop but not writes out a prompt while waiting input form. This is useful when you pipe Scheme program into gosh. You can force this behavior or suppress this behavior by -b and -i options.

If scheme-file is specified, gosh runs it as a Scheme program and exit. See Writing Scheme scripts, for details.

Command-line options

The following command line options are recognized by gosh. The first command line argument which doesn’t begin with ‘−’ is recognized as the script file. If you want to specify a file that begins with a minus sign, use a dummy option ‘--’.

Command Option: -I path

Prepends path to the load path list. You can specify this option more than once to add multiple paths.

Command Option: -A path

Appends path to the tail of the load path list. You can specify this option more than once to add multiple paths.

Command Option: -q

Makes gosh not to load the default initialization file.

Command Option: -V

Prints the gosh version and exits.

Command Option: -v version

If version is not the running gosh’s version, execute the specified version of gosh instead if it is installed. This is useful when you want to invoke specific version of Gauche. Note that version must be 0.9.6 or later.

Command Option: -u module

Use module. Before starting execution of scheme-file or entering the read-eval-print loop, the specified module is used, i.e. it is loaded and imported (See Defining and selecting modules, for details of use). You can specify this option more than once to use multiple modules.

Command Option: -l file

Load file before starting execution of scheme-file or entering the read-eval-print loop. The file is loaded in the same way as load (see Loading Scheme file). You can specify this option more than once to load multiple files.

Command Option: -L file

Load file like -l, but if file does not exist, this silently ignores it instead of reporting an error. This option can also be specified multiple times.

Command Option: -e scheme-expression

Evaluate scheme-expression before starting execution of scheme-file or entering the read-eval-print loop. Evaluation is done in the interaction-environment (see Eval and repl). You can specify this option more than once to evaluate multiple expressions.

Command Option: -E scheme-expression

Same as -e, except the scheme-expression is read as if it is surrounded by parenthesis. For example:

% gosh -umath.const -E"print (sin (* pi/180 15))" -Eexit
0.25881904510252074
Command Option: -b

Batch. Does not print prompts even if the input is a terminal.

Command Option: -i

Interactive. Print prompts even if the input is not a terminal.

Command Option: -m module

When a script file is given, this option makes the module named module in which the main procedure is looked for, instead of the user module. See Writing Scheme scripts for the details of executing scripts.

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

This is useful to write a Scheme module that can also be executed as a script.

Command Option: -f compiler-option

This option controls compiler and runtime behavior. For now we have following options available:

case-fold

Ignore case for symbols.

include-verbose

Reports whenever a file is included. Useful to check precisely which files are included in what order.

load-verbose

Reports whenever a file is loaded. Useful to check precisely which files are loaded in what order.

no-inline

Prohibits the compiler from inlining procedures and constants. Equivalent to no-inline-globals, no-inline-locals, no-inline-constants and no-inline-setters combined.

no-inline-constants

Prohibits the compiler from inlining constants.

no-inline-globals

Prohibits the compiler from inlining global procedures.

no-inline-locals

Prohibits the compiler from inlining local procedures.

no-inline-setters

Prohibits the compiler from inlining setters.

no-lambda-lifting-pass

Prohibits the compiler from running lambda-lifting pass.

no-post-inline-pass

Prohibits the compiler from running post-inline optimization pass.

no-source-info

Don’t keep source information for debugging. Consumes less memory.

safe-string-cursors

String cursors used on wrong strings will raise an error. This may cause performance problems because all cursors will be allocated on heap. See String cursors.

test

Adds "../src" and "../lib" to the load path before loading initialization file. This is useful when you want to test the compiled gosh REPL without installing it.

warn-legacy-syntax

Warns if the reader sees legacy hex-escape syntax in string literals. See Reader lexical mode. See Case-sensitivity.

Command Option: -p profiler-option

Turn on the profiler. The following profiler-option is recognized:

time

Records and reports time spent on function calls and number of times each function is called.

load

Records and reports time spent on loading each modules. Useful to tune start-up time of the scripts. (Results are in elapsed time).

See Using profiler for the details of the profiler.

Command Option: -r standard-revision

Start gosh with an environment of the specified revision of Scheme standard. Currently only 7 is supported as standar-revision.

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

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

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

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

See Library modules - R7RS standard libraries, for the details on how Gauche supports R7RS.

(Note: The -r7 option doesn’t change reader lexical mode (see Reader lexical mode) to strict-r7. That’s because using strict-r7 mode by default prevents many Gauche code from being loaded.)

Command Option: --

When gosh sees this option, it stops processing the options and takes next command line argument as a script file. It is useful in case if you have a script file that begins with a minus sign, although it is not generally recommended.

The options -I, -A, -l, -u, -e and -E are processes in the order of appearance. For example, adding a load path by -I affects the -l and -u option after it but not before it.

Environment variables

The following environment variables are recognized:

Environment variable: GAUCHE_AVAILABLE_PROCESSORS

You can get the number of system’s processors by sys-available-processors (see Environment inquiry); libraries/programs may use this info to optimize number of parallel threads. But you might change that, for testing and benchmarking—e.g. a program automatically uses 8 threads if there are 8 cores, but you might want to run it with 1, 2, 4 threads as well to see the effect of parallelization. This environment variable overrides the return value of sys-available-processors.

Environment variable: GAUCHE_CHECK_UNDEFINED_TEST

Warn if #<undef> is used in the test expression of branch.

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

We strongly recommend users to turn on this warning. In future, we plan to make this default.

Environment variable: GAUCHE_DYNLOAD_PATH

You can specify additional load paths for dynamically loaded objects by this environment variable, delimiting the paths by ’:’. The paths are appended before the system default load paths.

See Load dynamic library, for the details of how Gauche finds dynamically loadable objects.

Environment variable: GAUCHE_EDITOR
Environment variable: EDITOR

This is used by ed procedure in gauche.interactive module. See gauche.interactive - Utilities for interactive session, for the details.

Environment variable: GAUCHE_HISTORY_FILE

Specifies the filename where the REPL history is saved. If this environment varible is not set, history is saved in ~/.gosh_history. If this environment variable is set but an empty string, history isn’t saved. If the process is suid/sgid-ed, history won’t be saved.

Environment variable: GAUCHE_KEYWORD_DISJOINT
Environment variable: GAUCHE_KEYWORD_IS_SYMBOL

These two environment variables affect whether keywords are treated as symbols or not. See Keywords, for the details.

Environment variable: GAUCHE_LEGACY_DEFINE

Make the behavior of toplevel define the same as 0.9.8 and before. It allows certain legacy programs that aren’t valid R7RS. See Into the Scheme-Verse, for the details.

Environment variable: GAUCHE_LOAD_PATH

You can specify additional load paths by this environment variable, delimiting the paths by ’:’. The paths are appended before the system default load paths.

See Loading Scheme file, for the details of how Gauche finds files to load.

Environment variable: GAUCHE_MUTABLE_LITERALS

Allow literal lists and vectors to be mutated. Such code isn’t a valid Scheme program and causes an error, but Gauche didn’t enforce the restriction on 0.9.9 and before, so some legacy code may accidentally mutates literals. Set this environment variables to run such old programs. See Literals, for the details.

Environment variable: GAUCHE_NO_READ_EDIT

Disable line-editor on REPL prompt, even the terminal is capable. You can also turn it off with -fno-read-edit command-line option, or ,edit off toplevel commands during REPL session. See Interactive development, for the details of line editing.

Environment variable: GAUCHE_QUASIRENAME_MODE

This affects quasirename behavior, to keep the backward compatibility with 0.9.7 and before. See Explicit-renaming macro transformer, for the details.

Environment variable: GAUCHE_REPL_NO_PPRINT

This is used by gauche.interactive module to suppress pretty-printing on REPL prompt. See Interactive development, for the details.

Environment variable: GAUCHE_SUPPRESS_WARNING

Suppress system warnings (WARNING: ...). Not generally recommended; use only if you absolutely need to.

Environment variable: GAUCHE_TEST_RECORD_FILE

This is used by gauche.test module (see gauche.test - Unit Testing). If defined, names a file the test processes keep the total statistics.

Environment variable: GAUCHE_TEST_REPORT_ERROR

This is used by gauche.test module (see gauche.test - Unit Testing). If defined, reports stack trace to stderr when the test thunk raises an error (even when it is expected). Useful for diagnosis of unexpected errors.

Environment variable: TMP
Environment variable: TMPDIR
Environment variable: TEMP
Environment variable: USERPROFILE

These may affect the return value of sys-tmpdir. Different environment variables may be used on different platforms. See Pathnames, for the details.

Windows-specific executable

On Windows-native platforms (mingw), two interpreter executables are installed. gosh.exe is compiled as a Windows console application and works just like ordinary gosh; that is, it primarily uses standard i/o for communication. Another executable, gosh-noconsole.exe, is compiled as a Windows no-console (GUI) application. It is not attached to a console when it is started. Its standard input is connected to the NUL device. Its standard output and standard error output are special ports which open a new console when something is written to them for the first time. (NB: This magic only works for output via Scheme ports; direct output from low-level C libraries will be discarded.)

The main purpose of gosh-noconsole.exe is for Windows scripting. If a Scheme script were associated to gosh.exe and invoked from Explorer, it would always open a new console window, which is extremely annoying. If you associate Scheme scripts to gosh-noconsole.exe instead, you can avoid console from popping up.

If you’re using the official Windows installer, Scheme scripts (*.scm) have already associated to gosh-noconsole.exe and you can invoke them by double-clicking on Explorer. Check out some examples under C:\Program Files\Gauche\examples.



For Development HEAD DRAFTSearch (procedure/syntax/module):
DRAFT