Notations (Gauche Users’ Reference)

1.2 Notations

1.2.1 Entry format

In this manual, each entry is represented like this:

Category: foo arg1 arg2 ¶: [spec]{module} Description of foo …

Category denotes the category of the entry foo. The following categories will appear in this manual:

Function	A Scheme function.
Special Form	A special form (in the R7RS term, “syntax”).
Macro	A macro.
Module	A module
Class	A class.
Generic Function	A generic function
Method	A method
Reader Syntax	A lexical syntax that is interpreted by the reader.
Parameter	A parameter, an object to realize dynamically-bound variables. See Parameters and dynamic states, for the details.
Dynamic state	A procedure that follows a protocol to manage the state by dynamic scope. See Parameters and dynamic states, for the details.
Generic application	In Gauche, you can “apply” a non-procedure object to arguments as if it is a procedure (see Applicable objects, for the details). This entry explains the behavior of an object applied to arguments.
Subprocess argument	This appears in `do-process` and `run-process` to explain their keyword argument (see Running subprocess)
EC Qualifier	This is for SRFI-42 Eager Comprehension qualifiers. (see `srfi.42` - Eager comprehensions).

For functions, special forms and macros, the entry may be followed by one or more arguments. In the argument list, the following notations may appear:

arg …: Indicates zero or more arguments.
:optional x y z
:optional (x x-default) (y y-default) z: Indicates it may take up to three optional arguments. The second form specifies default values to x and y. This is Gauche’s enhancement to Scheme; see Making procedures for the definition of complete argument list syntax.
:key x y z
:key (x x-default) (y y-default) z: Indicates it may take keyword arguments x, y and z. The second form shows the default values for x and y. This is also Gauche’s enhancement to Scheme; see Making procedures for the definition of complete argument list syntax.
:rest args: Indicates it may take rest arguments. This is also Gauche’s enhancement to Scheme; see Making procedures for the definition of complete argument list syntax.

Following the entry line, we may indicate the specification the entry comes from, and/or the module the entry is provided when it’s not built-in.

The specification is shown in brackets. You’ll see the following variations.

[R7RS], [R7RS library]: It is defined in R7RS. If the entry is about a procedure, a syntax or a macro, library is also shown to indicate the name is exported from the scheme.library module (or the (scheme library) library, in R7RS terms).
[R7RS+], [R7RS+ library]: It is defined in R7RS, but extended by Gauche, e.g. accepting more optional arguments or different type of arguments. The description contains how it is extended from R7RS. When you’re writing a portable program, you need to be careful not to use Gauche-specific features.
[R6RS], [R6RS+], [R5RS], [R5RS+]: It is defined in R6RS or R5RS. The plus sign means it has extended by Gauche. Since R7RS is mostly upward-compatible to R5RS, and has a lot in common with R6RS, we mark an entry as R5RS or R6RS only if it is not a part of R7RS.
[SRFI-n], [SRFI-n+]: The entry works as specified in SRFI-n. If it is marked as "[SRFI-n+]", the entry has additional functionality.
[POSIX]: The API of the entry reflects the API specified in POSIX.

The module is shown in curly-braces. If the module isn’t shown, it is built-in for Gauche. (Note: When you’re writing R7RS code, Gauche built-ins are available through (gauche base) module, see gauche.base - Importing gauche built-ins).

Some entries may be available from more than one modules through re-exporting or module inheritance. We only list the primary module in that case.

Here’s an actual entry for an example:

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

This shows the function utf8->string is specified by R7RS, in (scheme base) library. Gauche originally provides it from gauche.unicode module. You can import the function from either one, but in general, it’s good to use (import (scheme base)) when writing R7RS code, and (use gauche.unicode) when writing Gauche code. See R7RS integration, for the details of differences in writing in R7RS and Gauche.

1.2.2 Names and namespaces

Since R6RS, you can split toplevel definitions of Scheme programs into multiple namespaces. In the standards such namespaces are called libraries. Gauche predates R6RS and has been calling them modules, and we use the latter throughout this manual.

(Note: RnRS libraries are more abstract concept than Gauche’s modules; RnRS defines libraries in a way that they can be implemented in various ways, and it just happens that Gauche realises the library semantics using modules. When you write a portable R7RS library, be aware not to rely on Gauche-specific module semantics. Especially, RnRS libraries are more static than Gauche modules; you cannot add definitions to exiting libraries within RnRS, for example.)

Sometimes the same name is used for multiple definitions in different modules. If we need to distinguish those names, we prefix the name with the module name and a hash sign. For example, gauche#lambda means lambda defined in gauche module. This does not mean you can write gauche#lambda in the source code, though: This notation is just for explanation.