Gauche Users’ Reference

This is a reference manual of Gauche, an R7RS Scheme implementation. This manual is for version 0.9.5.

1. Introduction

This is a users’ guide and reference manual of the Gauche Scheme system. Here I tried to describe the implementation precisely, sometimes referring to background design choices.

The target readers are those who already know Scheme and want to write useful programs in Gauche. For those who are new to Scheme, it’ll be easier to start from some kind of tutorial. I’m planning to write one.

This manual only deals with Scheme side of things. Gauche has another face, a C interface. Details of it will be discussed in a separate document to be written. Those who want to use Gauche as an embedded language, or want to write an extension, need that volume.

For the Scheme side, I tried to make this manual self-contained for the reader’s convenience, i.e. as far as you want to look up Gauche’s features you don’t need to refer to other documents. For example, description of functions defined in the standard documents are included in this manual, instead of saying “see the standard document”. However, this document is not a verbatim copy of the standard documents; sometimes I omit detailed discussions for brevity. I put pointers to the original documents, so please consult them if you need to refer to the standards.

If you’re reading this document off-line, you may find the most recent version on the web:

http://practical-scheme.net/gauche/.

1.1 Overview of Gauche

Gauche is a Scheme script engine; it reads Scheme programs, compiles it on-the-fly and executes it on a virtual machine. Gauche conforms the language standard "Revised^7 Report on the Algorithmic Language Scheme" (R7RS), and supports various common libraries defined in SRFIs (http://srfi.schemers.org).

The goal of Gauche is to provide a handy tool for programmers and system administrators to handle daily works conveniently and efficiently in the production environment.

There are lots of Scheme implementations available, and each of them has its design emphasis and weaknesses. Gauche is designed with emphasis on the following criteria.

Quick startup

One of the situation Gauche is aiming at is in the production environment, where you write ten-lines throw-away script that may invoked very frequently. This includes CGI scripts as well. Gauche provides frequently used common features as a part of rich built-in functions or precompiled Scheme libraries that can be loaded very quickly.

Fully utilizing multi-core

Gauche supports native threads on most platforms. The internals are fully aware of preemptive/concurrent threads (that is, no “giant global lock”), so that you can utilize multiple cores on your machine.

Multibyte strings

We can no longer live happily in ASCII-only or 1-byte-per-character world. The practical language implementations are required to handle multibyte (wide) characters. Gauche supports multibyte strings natively, providing robust and consistent support than ad hoc library-level implementation. See section Multibyte strings, for details.

Integrated object system

A powerful CLOS-like object system with MetaObject protocol (mostly compatible with STklos and Guile) is provided.

System interface

Although Scheme abstracts lots of details of the machine, sometimes you have to bypass these high-level layers and go down to the basement to make things work. Gauche has built-in support of most of POSIX.1 system calls. Other modules, such as networking module, usually provide both high-level abstract interface and low-level interface close to system calls.

Enhanced I/O

No real application can be written without dealing with I/O. Scheme neatly abstracts I/O as a port, but defines least operations on it. Gauche uses a port object as a unified abstraction, providing utility functions to operate on the underlying I/O system. See section Input and Output, for the basic I/O support.

Extended language

Gauche is not just an implementation of Scheme; it has some language-level enhancements. For example, lazy sequences allows you to have lazy data structures that behaves as if they’re ordinary lists (except that they’re realized lazily). It is different from library-level lazy structure implementation such as streams (srfi-41), in a sense that you can use any list-processing procedures on lazy sequences. It enables programs to use lazy algorithms more liberally.

1.2 Notations

1.2.1 Entry format

In this manual, each entry is represented like this:

Category: foo arg1 arg2

[spec] Description of foo …

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

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.

The description of the entry follows the entry line. If the specification of the entry comes from some standard, its origin is noted in the bracket at the beginning of the description. The following origins are noted:

[R7RS]

[R7RS+]

[R6RS]

[R6RS+]

[R5RS]

[R5RS+]

The entry works as specified in R7RS, R6RS or R5RS, respectively. If a plus sign is appended such as "[R7RS+]", the entry has extended functionality.

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.

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.

2. Concepts

In this chapter I describe a few Gauche’s design concepts that help you to understand how Gauche works.

2.1 Standard conformance

Gauche conforms "Revised^7 Report of Algorithmic Language Scheme," (R7RS) including optional syntax and procedures, with a few exceptions explained below.

• Gauche has a keyword object, expressed as a name prefixed by a colon (e.g. :key). It evaluates to itself, and used extensively when passing so-called keyword arguments (see section Making Procedures).

  R7RS requires names starting with colon to be read as a symbol. In the current version of Gauche, keywords aren’t symbols by default; they are of disjoint types. With an enviornment variable GAUCHE_KEYWORD_IS_SYMBOL, you can make Gauche treat keywords and symbols the same. See section Keywords, for the details. The plan is that we move to fully R7RS compliant in future, but this change could break existing code, so we have migration period. We recommend setting the environment variable now for newly written code.

• Continuations created in a certain situation (specifically, inside a Scheme code that is called from external C routine) have limited extent (See section Continuations, for details).
• Full numeric tower (integer, rational, real and complex numbers) are supported, but rationals are only exact, and complex numbers are always inexact.

Note that, since Gauche predates R7RS, most existing Gauche source code doesn’t follow the R7RS program/library structure. Gauche can read both traditional Gauche modules/scripts and R7RS programs/libraries seamlessly. See section Library modules - R7RS integration, for the details of how R7RS is integrated into Gauche.

Gauche also supports the following SRFIs (Scheme Request for Implementation).

SRFI-0, Feature-based conditional expansion construct.

Built-in. See section Feature conditional.

SRFI-1, List library.

Supported by the module srfi-1. See section srfi-1 - List library. (Some of SRFI-1 procedures are built-in).

SRFI-2, AND-LET*: an AND with local bindings, a guarded LET* special form.

Supported natively. See section Binding constructs.

SRFI-4, Homogeneous numeric vector datatypes.

The module gauche.uvector provides a superset of srfi-4 procedures, including arithmetic operations and generic interface on the SRFI-4 vectors. See section gauche.uvector - Uniform vectors.

SRFI-5, A compatible let form with signatures and rest arguments

Supported by the module srfi-5. See section srfi-5 - A compatible let form with signatures and rest arguments.

SRFI-6, Basic String Ports.

SRFI-6 procedures are built-in. See section String ports.

SRFI-7, Feature-based program configuration language

Supported as an autoloaded macro. See section srfi-7 - Feature-based program configuration language.

SRFI-8, receive: Binding to multiple values.

Syntax receive is built-in. See section Binding constructs.

SRFI-9, Defining record types.

Supported by the module gauche.record. See section gauche.record - Record types.

SRFI-10, Sharp-comma external form.

Built-in. See section Read-time constructor.

SRFI-11, Syntax for receiving multiple values.

Supported by the module srfi-11. See section srfi-11 - Let-values.

SRFI-13, String library

Supported by the module srfi-13. See section srfi-13 - String library. (Some of SRFI-13 procedures are built-in).

SRFI-14, Character-set library

Character-set object and a few SRFI-14 procedures are built-in. See section Character Set. Complete set of SRFI-14 is supported by the module srfi-14. See section srfi-14 - Character-set library.

SRFI-16, Syntax for procedures of variable arity (case-lambda)

Built-in. See section Making Procedures.

SRFI-17, Generalized set!

Built-in. See section Assignments.

SRFI-18, Multithreading support

Some SRFI-18 features are built-in, and the rest is in gauche.threads module. See section gauche.threads - Threads.

SRFI-19, Time Data Types and Procedures.

Time data type is Gauche built-in (see section Time). Complete set of SRFI-19 is supported by the module srfi-19. See section srfi-19 - Time data types and procedures.

SRFI-22, Running Scheme scripts on Unix

Supported. See section Writing Scheme scripts.

SRFI-23, Error reporting mechanism.

Built-in. See section Signaling exceptions.

SRFI-25, Multi-dimensional array primitives.

Supported by the module gauche.array, which defines superset of SRFI-25. See section gauche.array - Arrays.

SRFI-26, Notation for specializing parameters without currying.

As an autoloaded macro. See section Making Procedures.

SRFI-27, Sources of Random Bits.

Supported by the module srfi-27. See section srfi-27 - Sources of Random Bits.

SRFI-28, Basic format strings.

Gauche’s built-in format procedure is a superset of SRFI-28 format. See section Output.

SRFI-29, Localization

Supported by the module srfi-29. See section srfi-29 - Localization.

SRFI-30, Nested multi-line comments.

Supported by the native reader. See section Lexical structure.

SRFI-31, A special form rec for recursive evaluation

Defined as an autoloaded macro. See section Binding constructs.

SRFI-34, Exception Handling for Programs

Built-in. See section Exceptions. (However, Gauche implements srfi-18’s semantics of raise literally, which differs slightly from srfi-34’s. This may be changed in future.)

SRFI-35, Conditions

Built-in. See section Conditions.

SRFI-36, I/O Conditions

Partly supported. See section Conditions.

SRFI-37, args-fold: a program argument processor

Supported by the module srfi-37. See section srfi-37 - args-fold: a program argument processor.

SRFI-38, External Representation for Data With Shared Structure

Built-in. See Reading data and Output.

SRFI-39, Parameter objects

Supported by the module gauche.parameter. See section gauche.parameter - Parameters.

SRFI-40, A Library of Streams

Supported by the module util.stream. See section util.stream - Stream library.

SRFI-42, Eager comprehensions

Supported by the module srfi-42. See section srfi-42 - Eager comprehensions.

SRFI-43, Vector library

Supported by the module srfi-43. See section srfi-43 - Vector library (legacy).

SRFI-45, Primitives for Expressing Iterative Lazy Algorithms

Built-in. See section Lazy evaluation.

SRFI-46, Basic Syntax-rules Extensions

Built-in. See section Hygienic macros.

SRFI-55, require-extension

Supported as an autoloaded macro. See section srfi-55 - Requiring extensions.

SRFI-60, Integers as bits

Most procedures are built-in: See section Bitwise operations. The complete support is in srfi-60 module: See section srfi-60 - Integers as bits.

SRFI-61, A more general cond clause

Supported natively. See section Conditionals.

SRFI-62, S-expression comments

Supported by the native reader. See section Lexical structure.

SRFI-69, Basic hash tables

Supported by the module srfi-69 (see section srfi-69 - Basic hash tables). Note that Gauche provides built-in hashtable support (see section Hashtables). They just use different names in some procedures.

SRFI-78, Lightweight testing

Supported by the module srfi-78. Since Gauche already has its own test framework (see section gauche.test - Unit Testing), this is mainly for third-party modules that adopt srfi-78 for testing.

SRFI-87, => in case clauses

Supported natively. See section Conditionals.

SRFI-95, Sorting and merging

Supported natively. See section Sorting and merging.

SRFI-98, An interface to access environment variables

Supported by the module srfi-98. See section srfi-98 - Accessing environment variables.

SRFI-99, ERR5RS Records

Supported by the module gauche.record. See section gauche.record - Record types.

SRFI-106, Basic socket interface

Supported by the module srfi-106. See section srfi-106 - Basic socket interface.

SRFI-111, Boxes

Supported by the module srfi-111. See section srfi-111 - Boxes.

SRFI-112, Environment inquiry

Supported by the module srfi-112. See section srfi-112 - Environment inquiry.

SRFI-113, Sets and Bags

Supported by the module srfi-113. See section srfi-113 - Sets and bags.

SRFI-114, Comparators

Some of the features are built-in (see section Basic comparators). Full srfi spec is supported by the module srfi-114 (see section srfi-114 - Comparators).

SRFI-117, Queues based on lists.

Supported by the module srfi-117, which is implemented on top of data.queue. (see section srfi-117 - Queues based on lists)

SRFI-118, Simple adjustable-size strings

Supported by the module srfi-118. (see section srfi-118 - Simple adjustable-size strings)

SRFI-121, Generators

Gauche’s gauche.generator is superset of srfi-121 (see section gauche.generator - Generators).

SRFI-128, Comparators (reduced)

Built-in. See section Basic comparators, for the details.

SRFI-131, ERR5RS Record Syntax (reduced)

This srfi is a pure subset of srfi-99, and gauche.record’s define-record-type covers it. See section gauche.record - Record types.

SRFI-133, Vector library (R7RS-compatible)

Supported by the module srfi-133. See section srfi-133 - Vector library.

SRFI-134, Immutable Deques

The module data.ideque is compatible to srfi-134. See section data.ideque - Immutable deques.

2.2 Multibyte strings

Traditionally, a string is considered as a simple array of bytes. Programmers tend to imagine a string as a simple array of characters (though a character may occupy more than one byte). It’s not the case in Gauche.

Gauche supports multibyte string natively, which means characters are represented by variable number of bytes in a string. Gauche retains semantic compatibility of Scheme string, so such details can be hidden, but it’ll be helpful if you know a few points.

A string object keeps a type tag and a pointer to the storage of the string body. The storage of the body is managed in a sort of “copy-on-write” way—if you take substring, e.g. using directly by substring or using regular expression matcher, or even if you copy a string by copy-string, the underlying storage is shared (the “anchor” of the string is different, so the copied string is not eq? to the original string). The actual string is copied only if you destructively modify it.

Consequently the algorithm like pre-allocating a string by make-string and filling it with string-set! becomes extremely inefficient in Gauche. Don’t do it. (It doesn’t work with mulitbyte strings anyway). Sequential access of string is much more efficient using string ports (see section String ports).

String search primitives such as string-scan (see section String utilities) and regular expression matcher (see section Regular expressions) can return a matched string directly, without using index access at all.

You can choose internal encoding scheme at the time of compiling Gauche. At runtime, a procedure gauche-character-encoding can be used to query the internal encoding. At compile time, you can use a feature identifier to check the internal encoding. (see section Using platform-dependent features.) Currently, the following internal encodings are supported.

utf-8

UTF-8 encoding of Unicode. This is the default. The feature identifier gauche.ces.utf8 indicates Gauche is compiled with this internal encoding.

euc-jp

EUC-JP encoding of ASCII, JIS X 0201 kana, JIS X 0212 and JIS X 0213:2000 Japanese character set. The feature identifier gauche.ces.eucjp indicates Gauche is compiled with this internal encoding.

sjis

Shift-JIS encoding of JIS X 0201 kana and JIS X 0213:2000 Japanese character set. For source-code compatibility, the character code between 0 and 0x7f is mapped to ASCII. The feature identifier gauche.ces.sjis indicates Gauche is compiled with this internal encoding.

none

8-bit fixed-length character encoding, with the code between 0 and 0x7f matches ASCII. It’s up to the application to interpret the string with certain character encodings. The feature identifier gauche.ces.none indicates Gauche is compiled with this internal encoding.

Conversions from other encoding scheme is provided as a special port. See section gauche.charconv - Character Code Conversion, for details.

The way to specify the encoding of source programs will be explained in the next section.

2.3 Multibyte scripts

You can use characters other than us-ascii not only in literal strings and characters, but in comments, symbol names, literal regular expressions, and so on.

By default, Gauche assumes a Scheme program is written in its internal character encoding. It is fine as far as you’re writing scripts to use your own environment, but it becomes a problem if somebody else tries to use your script and finds out you’re using different character encoding than his/hers.

So, if Gauche finds a comment something like the following within the first two lines of the program source, it assumes the rest of the source code is written in <encoding-name>, and does the appropriate character encoding conversion to read the source code:

;; coding: <encoding-name>

More precisely, a comment in either first or second line that matches a regular expression #/coding[:=]\s*([\w.-]+)/ is recognized, and the first submatch is taken as an encoding name. If there are multiple matches, only the first one is effective. The first two lines must not contain characters other than us-ascii in order for this mechanism to work.

The following example tells Gauche that the script is written in EUC-JP encoding. Note that the string "-*-" around the coding would be recognized by Emacs to select the buffer’s encoding appropriately.

#!/usr/bin/gosh
;; -*- coding: euc-jp -*-

... script written in euc-jp ...

Internally, the handling of this magic comment is done by a special type of port. See Coding-aware ports for the details. See also Loading Scheme file for how to disable this feature.

2.4 Case-sensitivity

Historically, most Lisp-family languages are case-insensitive for symbols. Scheme departed from this tradition since R6RS, and the symbols are read in case-sensitive way. (Note that symbols have been case-sensitive internally even in R5RS Scheme; case-insensitivity is about readers.)

Gauche reads and writes symbols in case-sensitive manner by default, too. However, to support legacy code, you can set the reader to case-insensitive mode, in the following ways:

Use #!fold-case reader directive

When Gauche sees a token #!fold-case during reading a program, the reader switches to case-insensitive mode. A token #!no-fold-case has an opposite effect—to make the reader case-sensitive. These tokens affect the port from which they are read, and are in effect until EOF or another instance of these tokens are read. See Lexical structure for more details on #! syntax. This is the way defined in R6RS and R7RS.

Use -fcase-fold command-line argument

Alternatively, you can give a command-line argument -fcase-fold to the gosh command (see section Invoking Gosh). In this mode, the reader folds uppercase characters in symbols to lowercase ones. If a symbol name contains uppercase characters, it is written out using |-escape (see section Symbols).

2.5 Integrated Object System

Gauche has a STklos-style object system, similar to CLOS. If you have used some kind of object oriented (OO) languages, you’ll find it easy to understand the basic usage:

;; Defines a class point, that has x and y coordinate
(define-class point ()
  ((x :init-value 0)
   (y :init-value 0))
  )

(define-method move ((p point) dx dy)
  (inc! (slot-ref p 'x) dx)
  (inc! (slot-ref p 'y) dy))

(define-method write-object ((p point) port)
  (format port "[point ~a ~a]"
          (slot-ref p 'x)
          (slot-ref p 'y)))

However, if you are familiar with mainstream OO languages but new to CLOS-style object system, Gauche’s object system may look strange when you look deeper into it. Here I describe several characteristics of Gauche object system quickly. See section Object system, for details.

Everything is an object (if you care)

You have seen this tagline for the other languages. And yes, in Gauche, everything is an object in the sense that you can query its class, and get various meta information of the object at run time. You can also define a new method on any class, including built-in ones.

Note that, however, in CLOS-like paradigm it doesn’t really matter whether everything is an object or not, because of the following characteristics:

Method is dispatched by all of its arguments.

Unlike other object-oriented languages such as C++, Objective-C, Python, Ruby, etc., in which a method always belong to a single class, a Gauche method doesn’t belong to a specific class.

For example, suppose you define a numeric vector class <num-vector> and a numeric matrix class <num-matrix>. You can define a method product with all possible combinations of those type of arguments:

(product <num-vector> <num-matrix>) (product <num-matrix> <num-vector>) (product <num-vector> <num-vector>) (product <num-matrix> <num-matrix>) (product <number> <num-vector>) (product <number> <num-matrix>) (product <number> <number>)

Each method belongs to neither <num-vector> class nor <num-matrix> class.

Since a method is not owned by a class, you can always define your own method on the existing class (except a few cases that the system prohibits altering pre-defined methods). The above example already shows it; you can make product method work on the built-in class <number>. That is why I said it doesn’t make much sense to discuss whether everything is object or not in CLOS-style object system.

To step into the details a bit, the methods are belong to a generic function, which is responsible for dispatching appropriate methods.

Class is also an instance.

By default, a class is also an instance of class <class>, and a generic function is an instance of class <generic>. You can subclass <class> to customize how a class is initialized or how its slots are accessed. You can subclass <generic> to customize how the applicable methods are selected, which order those methods are called, etc. The mechanism is called metaobject protocol. Metaobject protocol allows you to extend the language by the language itself.

To find examples, see the files lib/gauche/singleton.scm and lib/gauche/mop/validator.scm included in the distribution. You can also read lib/gauche/mop/object.scm, which actually defines how a class is defined in Gauche. For more details about metaobject protocol, see MOP.

Class doesn’t create namespace

In the mainstream OO language, a class often creates its own namespace. This isn’t the case in CLOS-style object system. In Gauche, a namespace is managed by the module system which is orthogonal to the object system.

2.6 Module system

Gauche has a simple module system that allows modularlized development of large software.

A higher level interface is simple enough from the user’s point of view. It works like this: When you want to use the features provided by module foo, you just need to say (use foo) in your code. This form is a macro and interpreted at compile time. Usually it loads the files that defines foo’s features, and imports the external APIs into the calling module.

The use mechanism is built on top of two independent lower mechanisms, namespace separation and file loading mechanism. Those two lower mechanisms can be used separately, although it is much more convenient when used together.

The use mechanism is not transitive; that is, if a module B uses a module A, and a module C uses the module B, C doesn’t see the bindings in A. It is because B and A is not in the is-a relationship. Suppose the module A implements a low-level functionality and the module B implements a high-level abstraction; if C is using B, what C wants to see is just a high-level abstraction, and doesn’t concern how B implements such functionality. If C wants to access low-level stuff, C has to use A explicitly.

There is another type of relationship, though. You might want to take an exiting module A, and add some interface to it and provide the resulting module B as an extension of A. In such a case, B is-a A, and it’d be natural that the module that uses B can also see A’s bindings. In Gauche, it is called module inheritance and realized by extend form.

The following sections in this manual describes modules in details.

• Writing Gauche modules explains the convention of writing modules.
• Modules describes special forms and macros to define and to use modules, along the built-in functions to introspect module internals.

2.7 Compilation

Gauche is a Scheme interpreter, in the sense that it reads a Scheme form at a time and evaluates it. Actually, Gauche compiles every toplevel form into an intermediate form before executing.

Built-in syntaxes and macros are recognized and expanded at the compilation time. Some built-in procedures are expanded in-line as far as the compiler can see the global binding is not altered at the time the form is compiled.

This raises a few problems you should care.

load is done at run time.

load is a procedure in Gauche, therefore evaluated at run time. If the loaded program defines a macro, which is available for the compiler after the toplevel form containing load is evaluated. So, suppose foo.scm defines a macro foo, and you use the macro like this:

;; in ``foo.scm'' (define-syntax foo (syntax-rules () ((_ arg) (quote arg)))) ;; in your program (begin (load "foo") (foo (1 2 3))) ⇒ error, bad procedure: `1' (load "foo") (foo (1 2 3)) ⇒ '(1 2 3)

The (begin (load ...)) form fails, because the compiler doesn’t know foo is a special form at the compilation time and compiles (1 2 3) as if it is a normal procedure call. The latter example works, however, since the execution of the toplevel form (load "foo") is done before (foo (1 2 3)) is compiled.

To avoid this kind of subtleties, use require or use to load a program fragments. Those are recognized by the compiler.

require is done at compile time

On the other hand, since require and use is recognized by the compiler, the specified file is loaded even if the form is in the conditional expression. If you really need to load a file on certain condition, use load or do dispatch in macro (e.g. cond-expand form (see section Feature conditional).)

3. Programming in Gauche

3.1 Invoking Gosh

Gauche can be used either as an independent Scheme interpreter or as an embedded Scheme library. The 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 section 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: -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 section 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 section 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 section 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:

no-inline

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

no-inline-globals

Prohibits the compiler from inlining global procedures.

no-inline-locals

Prohibits the compiler from inlining local procedures.

no-inline-constants

Prohibits the compiler from inlining constants.

no-post-inline-pass

Prohibits the compiler from running post-inline optimization pass.

no-lambda-lifting-pass

Prohibits the compiler from running lambda-lifting pass.

load-verbose

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

include-verbose

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

warn-legacy-syntax

Warns if the reader sees leagacy hex-escape syntax in string literals. See section Reader lexical mode.

no-source-info

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

case-fold

Ignore case for symbols. See section Case-sensitivity.

test

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

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 section Library modules - R7RS integration, for the details on how Gauche supports R7RS.

(Note: The -r7 option doesn’t change reader lexiacl mode (see section 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_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 section Loading Scheme file, for the details of how Gauche finds files to load.

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 section Load dynamic library, for the details of how Gauche finds dynamically loadable objects.

Environment variable: GAUCHE_AVAILABLE_PROCESSORS

You can get the number of system’s processors by sys-available-processors (see section 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_KEYWORD_DISJOINT

Environment variable: GAUCHE_KEYWORD_IS_SYMBOL

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

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 section Pathnames, for the details.

Environment variable: GAUCHE_SUPPRESS_WARNING

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

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. However, this console would be of little use, since it would dissapear once the script exits, and the user wouldn’t be likely to have enough time to look at it. If you associate Scheme scripts to gosh-noconsole.exe instead, you can avoid this annoying 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’.

3.2 Interactive development

When gosh is invoked without any script files, it goes into interactive read-eval-print loop (REPL).

To exit the interpreter, type EOF (usually Control-D in Unix terminals) or evaluate (exit).

In the interactive session, gosh loads gauche.interactive module (see section gauche.interactive - Utilities for interactive session) for the convenience. The module also loads a file ‘.gaucherc’ under the user’s home directory if it exists. You may put settings there that would help interactive debugging. (As of Gauche release 0.7.3, ‘.gaucherc’ is no longer loaded when gosh is run in script mode.)

Note that ‘.gaucherc’ is always loaded in the user module, even if gosh is invoked with -r7 option. The file itself is a Gauche-specific feature, so you don’t need to consider portability in it.

I recommend you to run gosh inside Emacs, for it has rich features useful to interact with internal Scheme process. Put the following line to your ‘.emacs’ file:

(setq scheme-program-name "gosh -i")

And you can run gosh by <M-x run-scheme>.

If you want to use multibyte characters in the interaction, make sure your terminal’s settings is in sync with gosh’s internal character encodings.

3.2.1 Working in REPL

When you enter REPL, Gauche prompts you to enter a Scheme expression:

gosh>

After you complete a Scheme expression and type ENTER, the result of evaluation is printed.

gosh> (+ 1 2)
3
gosh> 

The REPL session binds the last three results of evaluation in the global variables *1, *2 and *3. You can use the previous results via those history variables in subsequent expressions.

gosh> *1
3
gosh> (+ *2 3)
6

If the Scheme expression yields multiple values (see section Multiple values), they are printed one by one.

gosh> (min&max 1 -1 8 3)
-1
8
gosh> 

The history variable *1, *2 and *3 only binds the first value. A list of all values are bound to *1+, *2+ and *3+.

gosh> *1
-1
gosh> *2+
(-1 8)

(Note that, when you evaluate *1 in the above example, the history is shifted—so you need to use *2+ to refer to the result of (min&max 1 -1 8 3).)

The *history procedure shows the value of history variables:

gosh> (*history)
*1: (-1 8)
*2: -1
*3: -1
gosh> 

As a special case, if an evaluation yields zero values, history isn’t updated. The *history procedure returns no values, so merely looking at the history won’t change the history itself.

gosh> (*history)
*1: (-1 8)
*2: -1
*3: -1
gosh> (values)
gosh> (*history)
*1: (-1 8)
*2: -1
*3: -1

Finally, a global variable *e is bound to the last uncaught error condition object.

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

(The error stack trace may differ depending on your installation.)

In REPL prompt, you can also enter special top-level commands for common tasks. Top-level commands are not Scheme expressions, not even S-expressions. They work like traditional line-oriented shell commands instead.

Top-level commands are prefixed by comma to be distinguished from ordinary Scheme expressions. To see what commands are available, just type ,help and return.

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

 ,a|apropos  Show the names of global bindings that match the regexp.
 ,cd         Change the current directory.
 ,doc|info   Show info document for an entry of NAME.
 ,d|describe Describe the object.
 ,history    Show REPL history.
 ,h|help     Show the help message of the command.
 ,pwd        Print working directory.
 ,source     Show source code of the procedure if it's available.

To see the help of each individual commands, give the command name (without comma) to the help command:

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

The ,d (or ,describe) top-level command describes the given Scheme object or the last result if no object is given. Let’s try some:

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

In the above example, first we evaluated (sys-stat "/home"), which returns <sys-stat> object. The subsequent ,d top-level command describes the returned <sys-stat> object.

The description depends on the type of objects. Some types of objects shows extra information. If you describe an exact integer, it shows alternative interpretations of the number:

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

If you describe a symbol, its known bindings is shown.

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

If you describe a procedure, and its source code location is known, that is also shown (see the Defined at... line):

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

Let’s see a couple of other top-level commands. The ,info command shows the manual entry of the given procedure, variable, syntax, module or a class. (The text is searched from the installed info document of Gauche. If you get an error, check if the info document is properly installed.)

gosh> ,info append
 -- Function: append list ...
     [R7RS] Returns a list consisting of the elements of the first LIST
     followed by the elements of the other lists.  The resulting list is
     always newly allocated, except that it shares structure with the
     last list argument.  The last argument may actually be any object;
     an improper list results if the last argument is not a proper list.

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

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

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

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

The ,a command (or ,apropos) shows the global identifiers matches the given name or regexp:

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

Note: The apropos command only shows the symbols that has loaded into the current process. On the other hand, the info command searches info document, regardless of the named entity has loaded into the current process or not.

Note: If you invoke gosh with -q option, which tells gosh not to load the initialization files, you still get a REPL prompt but no fancy features such as history variables are available. Those convenience features are implemented in gauche.interactive module, which isn’t loaded with -q option.

3.3 Writing Scheme scripts

When a Scheme program file is given to gosh, it makes the user module as the current module, binds a global variable *argv* to the list of the remaining command-line arguments, and then loads the Scheme program. If the first line of scheme-file begins with two character sequence “#!”, the entire line is ignored by gosh. This is useful to write a Scheme program that works as an executable script in unix-like systems.

Typical Gauche script has the first line like these

#!/usr/local/bin/gosh
  or,
#!/usr/bin/env gosh
  or,
#!/bin/sh
:; exec gosh -- $0 "$@"

The second and third form uses a “shell trampoline” technique so that the script works as far as gosh is in the PATH. The third form is useful when you want to pass extra arguments to gosh, for typically #!-magic of executable scripts has limitations for the number of arguments to pass the interpreter.

After the file is successfully loaded, gosh calls a procedure named ‘main’ if it is defined in the user module. Main receives a single argument, a list of command line arguments. Its first element is the script name itself.

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

If the main procedure is not defined, gosh exits after loading the script file.

Although you can still write the program main body as toplevel expressions, like shell scripts or Perl scripts, it is much convenient to use this ‘main’ convention, for you can load the script file interactively to debug.

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

For example, you write a Scheme module foo and within it, you define the main procedure. You don’t need to export it. If the file is loaded as a module, the main procedure doesn’t do anything. But if you specify -m foo option and give the file as a Scheme script to gosh, then the main procedure is invoked after loading the script. You can code tests or small example application in such an alternate main procedure.

Although the argument of the main procedure is the standard way to receive the command-line arguments, there are a couple of other ways to access to the info. See section Command-line arguments, for the details.

Now I show several simple examples below. First, this script works like cat(1), without any command-line option processing and error handling.

#!/usr/bin/env gosh

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

The following script is a simple grep command.

#!/usr/bin/env gosh

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

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

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

See also gauche.parseopt - Parsing command-line options, for a convenient way to parse command-line options.

3.4 Debugging

Gauche doesn’t have much support for debugging yet. The idea of good debugging interfaces are welcome.

For now, the author uses the classic ’debug print stub’ technique when necessary. Gauche’s reader supports special syntaxes beginning with #?, to print the intermediate value.

The syntax #?=expr shows expr itself before evaluating it, and prints its result(s) after evaluation.

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

Note: If the debug stub is evaluated in a thread other than the primordial thread (see section gauche.threads - Threads), the output includes a number to distinguish which thread it is generated. In the following example, #<thread ...> and the prompt is the output of REPL in the primordial thread, but followig #?=[1]... and #?-[1]... are the debug output from the thread created by make-thread. The number is for debugging only— they differ for each thread, but other than that there’s no meaning.

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

The syntax #?,(proc arg …) is specifically for procedure call; it prints the value of arguments right before calling proc, and prints the result(s) of call afterwards.

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

Internally, the syntax #?=x and #?,x are read as (debug-print x) and (debuf-funcall x), respectively, and the macros debug-print and debug-funcall handles the actual printing. See section Debugging aid, for more details.

The reasons of special syntax are: (1) It’s easy to insert the debug stub, for you don’t need to enclose the target expression by extra parenthesis, and (2) It’s easy to find and remove those stabs within the editor.

3.5 Using platform-dependent features

Gauche tries to provide low-level APIs close to what the underlying system provides, but sometimes they vary among systems. For example, POSIX does not require symlink, so some systems may lack sys-symlink (see section Directory manipulation). Quite a few unix-specific system functions are not available on Windows platform. To allow writing a portable program across those platforms, Gauche uses cond-expand (see section Feature conditional) extensively. A set of extended feature-identifiers is provided to check availability of specific features. For example, on systems that has symlink, a feature identifier gauche.sys.symlink is defined. So you can write a code that can switch based on the availability of sys-symlink as follows:

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

If you’re familiar with system programming in C, you can think it equivalent to the following C idiom:

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

There are quite a few such feature identifiers; each identifier is explained in the maunal entry of the procedures that depend on the feature. Here we list a few important ones:

gauche

This feature identifier is always defined. It is useful when you write Scheme code portable across multiple implementations.

gauche.os.windows

Defined on Windows native platform. Note that cygwin does not define this feature identifier (but see below).

gauche.os.cygwin

Defined on Cygwin.

gauche.sys.threads

Defined if Gauche is compiled with thread support. See section gauche.threads - Threads.

gauche.sys.pthreads

gauche.sys.wthreads

Defined to indicate the underlying thread implementation when Gauche has thread support. See section gauche.threads - Threads.

gauche.net.ipv6

Defined if Gauche is compiled with IPv6 support.

gauche.ces.utf8

gauche.ces.eucjp

gauche.ces.sjis

gauche.ces.none

Either one of these feature identifiers is defined, according to the compile-time option of Gauche’s internal character encoding. See section Multibyte strings, for the details of the internal character encoding.

Because cond-expand is a macro, the body of clauses are expanded into toplevel if cond-expand itself is in toplevel. That means you can switch toplevel definitions:

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

Or even conditionally "use" the modules:

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

The traditional technique of testing a toplevel binding (using global-variable-bound?, see section Module introspection) doesn’t work well in this case, since the use form takes effect at compile time. It is strongly recommended to use cond-expand whenever possible.

Currently the set of feature identifiers are fixed at the build time of Gauche, so it’s less flexible than C preprocessor conditionals. We have a plan to extend this feature to enable adding new feature identifiers; but such feature can complicate semantics when compilation and execution is interleaved, so we’re carefully assessing the effects now.

A couple of notes:

Feature identifiers are not variables. They can only be used within the feature-requirement part of cond-expand (see Feature conditional for the complete definition of feature requirements).

By the definition of srfi-0, cond-expand raises an error if no feature requirements are satisfied and there’s no else clause. A rule of thumb is to provide else clause always, even it does nothing (like the above example that has empty else clause).

3.6 Profiling and tuning

If you find your script isn’t running fast enough, there are several possibilities to improve its performance.

It is always a good idea to begin with finding which part of the code is consuming the execution time. Gauche has a couple of basic tools to help it. A built-in sampling profiler, explained in the following subsection, can show how much time is spent in each procedure, and how many times it is called. The gauche.time module (gauche.time - Measure timings) provides APIs to measure execution time of specific parts of the code.

Optimization is specialization—you look for the most common patterns of execution, and put a special path to support those patterns efficiently. Gauche itself is no exception, so there are some patterns Gauche can handle very efficiently, while some patterns it cannot. The next subsection, Performance tips, will give you some tips of how to adapt your code to fit the patterns Gauche can execute well.

3.6.1 Using profiler

As of 0.8.4, Gauche has a built-in profiler. It is still experimental quality and only be tested on Linux. It isn’t available for all platforms. It works only in single-thread applications for now.

To use the profiler non-interactively, give -ptime command-line option to gosh.

% gosh -ptime your-script.scm

After the execution of ‘your-script.scm’ is completed, Gauche prints out the table of functions with its call count and its consumed time, sorted by the total consumed time.

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

Note that the time profiler uses statistic sampling. Every 10ms the profiler interrupts the process and records the function that is executed then. Compared to the individual execution time per function call, which is the order of nanoseconds, this sampling rate is very sparse. However, if we run the program long enough, we can expect the distribution of samples per each function approximately reflects the distribution of time spent in each function.

Keep in mind that the number is only approximation; the number of sample counts for a function may easily vary if the program deals with different data sets. It should also be noted that, for now, GC time is included in the function in which GC is triggered. This sometimes causes a less important function to "float up" to near-top of the list. To know the general pattern, it is a good custom to run the program with several different data sets.

On the other hand, the call count is accurate since Gauche actually counts each call.

Because all functions are basically anonymous in Scheme, the ’name’ field of the profiler result is only a hint. The functions bound at toplevel is generally printed with the global variable name it is bound at the first time. Internal functions are printed as a list of names, reflecting the nesting of functions. Methods are also printed as a list of the name and specializers.

The profiler has its own overhead; generally the total process time will increase 20-30%. If you want to turn on the profiler selectively, or you’re running a non-stop server program and want to obtain the statistics without exiting the server, you can call the profiler API from your program; see Profiler API, for the details.

3.6.2 Performance tips

Don’t guess, just benchmark. It is the first rule of performance tuning. Especially for the higher-level languages like Scheme, what impacts on performance greatly depends on the implementation. Certain operations that are very cheap on an implementation may be costly on others. Gauche has such implementation-specific characteristics, and to know some of them would help to see what to look out in the benchmark results.

"80% of execution time is spent in 20% of the code" is another old saying. Don’t obscure your code by "potential" optimization that has little impact on the actual execution. We describe some tips below, but it doesn’t mean you need to watch them all the time. It is better to keep most of the code clean and easy to understand, and only do tricks on the innermost loop.

Ports: To satisfy the specification of SRFI-18 (Threading), every call to I/O primitives of Gauche locks the port. This overhead may be visible if the application does a lot of I/O with smaller units (e.g. every bytes). The primitives that deals with larger unit, such as read and read-uvector, are less problematic, since usually they just lock the port once per call and do all the low-level I/O without the lock overhead. (Note: this doesn’t mean those primitives guarantee to lock the port throughout the execution of the function; furthermore, the port locking feature is optimized for the case that port accesses rarely collide. If you know it is possible that more than one threads read from or write to the same port, it is your responsibility to use mutex explicitly to avoid the collision.)

If you find out the locking is indeed a bottleneck, there are couple of things you can consider: (1) Try using the larger-unit primitives, instead of calling the smaller-unit ones. (2) Use with-port-locking (see Port and threads) to lock the port in larger context.

Strings: Because of the multibyte strings, two operations are particularly heavy in Gauche: string mutation and indexed string access. It is a design choice; we encourage the programming style that avoids those operations. When you sequentially access the string, string ports (see String ports) provide a cleaner and more efficient way. When you search and retrieve a substring, there are various higher-level primitives are provided (see String utilities, Regular expressions, and srfi-13 - String library, for example). If you’re using strings to represent an octet sequence, use uniform vectors (see gauche.uvector - Uniform vectors) instead.

Deep recursion: Gauche’s VM uses a stack for efficient local frame allocation. If recursion goes very deep (depending on the code, but usually several hundreds to a thousand), the stack overflows and Gauche moves the content of the stack into the heap. This incurs some overhead. If you observe a performance degradation beyond a certain amount of data, check out this possibility.

Generic functions: Because of its dynamic nature, generic function calls are slower than procedure calls. Not only because of the runtime dispatch overhead, but also because Gauche’s compile-time optimizer can’t do much optimization for generic function calls. You don’t need to avoid generic functions because of performance reasons in general, but if you do find single function call consuming a large part of execution time and it is calling a generic function in its inner loop—then it may be worth to modify it.

Redefining builtin functions: Gauche inlines some builtin functions if they are not redefined. Although sometimes it is useful to redefine basic functions, you may want to limit the effect. For example, put redefined functions in a separate module and use the module in the code that absolutely needs those functions replaced.

Closure creation: When you create a closure, its closing environment is copied to the heap. This overhead is small, but it still may be visible when a closure is created within an innermost loop that is called millions of times. If you suspect this is a problem, try disassemble the function. Gauche’s compiler uses some basic techniques of closure analysis to avoid creating closures for typical cases, in which case you see the local function’s bodies are inlined. If you see a CLOSURE instruction, though, it means a closure is created.

This list isn’t complete, and may change when Gauche’s implementation is improved, so don’t take this as fixed features. We’ll adjust it occasionally.

3.7 Writing Gauche modules

Gauche’s libraries are organized by modules. Although Gauche can load any valid Scheme programs, there is a convention that Gauche’s libraries follow. When you write a chunk of Scheme code for Gauche, it is convenient to make it a module, so that it can be shared and/or reused.

Usually a module is contained in a file, but you can make a multi-file module. First I explain the structure of a single-file module. The following template is the convention used in Gauche’s libraries.

;; Define the module interface
(define-module foo
  (use xxx)
  (use yyy)
  (export foo1 foo2 foo3)
  )
;; Enter the module
(select-module foo)

… module body …

This file must be saved as “foo.scm” in some directory in the *load-path*.

The define-module form creates a module foo. It also loads and imports some other modules by ‘use’ macros, and declares which symbols the foo module exports, by ‘export’ syntax. (See section Defining and selecting modules, for detailed specification of those syntaxes).

Those use forms or export forms are not required to appear in the define-module form, but it is a good convention to keep them in there at the head of the file so that it is visually recognizable which modules foo depends and which symbols it exports.

The second form, ‘select-module’, specifies the rest of the file is evaluated in the module foo you just defined. Again, this is just a convention; you can write entire module body inside define-module. However, I think it is error-prone, for the closing parenthesis can be easily forgotten or the automatic indentation mechanism of editor will be confused.

After select-module you can write whatever Scheme expression. It is evaluated in the selected module, foo. Only the bindings of the exported symbols will be directly accessible from outside.

So, that’s it. Other programs can use your module by just saying ‘(use foo)’. If you want to make your module available on your site, you can put it to the site library location, which can be obtained by

(gauche-site-library-directory)

in gosh, or

gauche-config --sitelibdir

from shell.

If you feel like to conserve global module name space, you can organize modules hierarchically. Some Gauche libraries already does so. See section Library modules - Overview, for examples. For example, text.tr module is implemented in “text/tr.scm” file. Note that the pathname separator ‘/’ in the file becomes a period in the module name.

3.8 Using extension packages

Building and installing packages

Gauche comes with some amount of libraries, but they aren’t enough at all to use Gauche in the production environment. There are number of additional libraries available. We call them extension packages, or simply packages. Each package usually provides one or more modules that adds extra functionality. Most of the packages provide binding to other C libraries, such as graphics libraries or database clients. If the package has some C code, it is likely that you need to compile it on your machine with the installed Gauche system.

Usually a package is in the form of compressed tarball, and the standard "ungzip + untar + configure + make + make install" sequence does the job. Read the package’s document, for you may be able to tailor the library for your own needs by giving command-line options to the configure script.

From Gauche 0.8, an utility script called gauche-package is installed for the convenience. It automates the build and install process of packages.

Suppose you have downloaded a package ‘Package-1.0.tar.gz’. If the package follows the convention, all you have to do is to type this:

$ gauche-package install Package-1.0.tar.gz

It ungzips and untars the package, cd into the ‘Package-1.0’ subdirectory, run configure, make, and make install. By default, gauche-package untars the tarball in the current working directory. You can change it by a customization file; see below.

If you need a special priviledge to install the files, you can use --install-as option which runs make install part via the sudo program.

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

If it doesn’t work for you, you can just build the package by gauche-package build Package-1.0.tar.gz, then manually cd to the ‘Package-1.0’ directory and run make install.

You can give configuration options via -C or --configure-options command-line argument, like this:

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

If the package has adopted the new package description file, it can remember the configuration options you have specified, and it will automatically reuse them when you install the package again. (If you’re a package developer, check out ‘examples/spigot/README’ file in the Gauche source tree to see how to cooperate with Gauche’s package management system.)

If you don’t have a tarball in your local directory, but you know the URL where you can download it, you can directly give the URL to gauche-package. It understands http and ftp, and uses either wget or ncftpget to download the tarball, then runs configure and make.

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

Customizing gauche-package

The gauche-package program reads ‘~/.gauche-package’ if it exists. It must contain an associative list of parameters. It may look like this:

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

The following is a list of recognized parameters. If the program isn’t given in the configuration file, gauche-package searches PATH to find one.

build-dir

A directory where the tarball is extracted. If URL is given, the downloaded file is also placed in this directory.

bzip2

Path to the program bzip2.

cat

Path to the program cat.

make

Path to the program make.

ncftpget

Path to the program ncftpget.

rm

Path to the program rm.

sudo

Path to the program sudo.

tar

Path to the program tar.

wget

Path to the program wget.

4. Core syntax

4.1 Lexical structure

Gauche extends R7RS Scheme lexical parser in some ways. Besides, because of historical reasons, a few of the default lexical syntax may conflict R7RS specification. You can set a reader mode to make it R7RS compliant.

Hash-bang directives

Tokens beginning with #! may have special meanings to the reader. R7RS defines two of such directives—#!fold-case and #!no-fold-case, which switches whether symbols are read in case-folding or non-case-folding mode, respectively.

see section Hash-bang token below, for all the directives Gauche has.

Square brackets

Gauche adopts the R6RS syntax that regards [] the same as (). Both kind of parentheses are equivalent, but the kind of corresponding open and close parentheses must match. Some seasoned Lisper may frown on them, but it helps visually distinguish different roles of parentheses.

A general convention is to use [] for groupings other than function and macro application. If such grouping nests, however, use () for outer groupings. Examples:

(cond [(test1 x) (y z)] [(test2 x) (s t)] [else (u v)]) (let ([x (foo a b)] [y (bar c d)]) (baz x y))

It is purely optional, so you don’t need to use them if you don’t like them. R7RS doesn’t adopt this syntax and leaves [] for extensions, so it is safe to stick to () in portable R7RS programs. (If the reader is in strict-r7 mode, an error is signalled when [] is used. See section Reader lexical mode, for the details.)

Scheme-specific modes of some editors (e.g. Quack on Emacs) allows you to type just ) and inserts either ] or ) depending on which kind parenthesis it is closing. We recommend using such modes if you use this convention.

Symbol names

Symbol names are case sensitive by default (see section Case-sensitivity). Symbol name can begin with digits, ’+’ or ’-’, as long as the entire token doesn’t consist valid number syntax. Other weird characters can be included in a symbol name by surrounding it with ’|’, e.g. ’|this is a symbol|’. See section Symbols, for details.

Numeric literals

Either integral part or fraction part of inexact real numbers can be omitted if it is zero, i.e. 30., .25, -.4 are read as real numbers. The number reader recognizes ’#’ as insignificant digits. Complex numbers can be written both in the rectangular format (e.g. 1+0.3i) and in the polar format (e.g. 3.0@1.57). Inexact real numbers include the positive infinity, the negative infinity, and NaN, which are represented as +inf.0, -inf.0 and +nan.0, respectively. (-nan.0 is also read as NaN.)

As an extension of Gauche, a character _ can be inserted in or around a sequence of digits in number literals, as far as the literal is explicitly prefixed (#e, #x, etc). Those _’s are just ignored. It is to improve readability, e.g. #b1100_1010_1111_1110.

Gauche also adopts Common-Lisp style radix prefixed numeric literals, e.g. #3r120 (120 in base-3, 15 in decimal). Radix between 2 and 36 are recognized; alphabetic letters a-zA-Z are used beyond decimal.

For the polar notation of complex numbers, Gauche allows the suffix pi to denote the phase by multiples of pi. The Scheme syntax use radians for the phase, but you can only approximate pi with the floating point numbers, so it can’t represent round numbers except zero angle.

gosh> 2@3.141592653589793 -2.0+2.4492935982947064e-16i

With the pi suffix, you can get a round numbers.

gosh> 2@1pi -2.0 gosh> 2@0.5pi 0.0+2.0i gosh> 2@-0.5pi 0.0-2.0i

Hex character escapes

You can denote a character using hexadecimal notation of the character code in some literals; specifically, character literals, charcter set literals, string literals, symbols, regular expression literals.

R7RS adopted a hex escape notation \xNNNN; for strings and symbols surrounded by vertical bars, and #\xNNNN for characters. The number of digits is variable, and the character code is Unicode codepoint.

Gauche had been using two types of escapes; \u and \x. In general, u is for Unicode codepoint, while x is for the character code in the internal encoding. Besides, except character literals, we used fixed number of digits, instead of using the terminator ; as in R7RS.

Since 0.9.4, we interpret \x-escape as R7RS whenever if it consists a valid R7RS hex-escape, and if not, try to interpret it as legacy Gauche hex-escape.

Although rarely, there are cases that can interpreted both in R7RS syntax and legacy Gauche syntax, but yielding different characters. Reading legacy files with such literals in the current Gauche may cause unexpected behavior. You can switch the reader mode so that it becomes backward-compatible. See section Reader lexical mode, for the details.

Extended sharp syntax

Many more special tokens begins with ’#’ are defined. See the table below.

4.1.1 Sharp syntax

The table below lists sharp-syntaxes.

4.1.2 Hash-bang token

A character sequence #! has two completely different semantics, depending on how and where it occurs.

If a file begins with #!/ or #! (hash, bang, and a space), then the reader assumes it is an interpreter line (shebang) of a script and ignores the rest of characters until the end of line. (Actually the source doesn’t need to be a file. The reader checks whether it is the beginning of a port.)

Other than the above case, #!identifier is read as a token with special meanings. This kind token can be a special directive for the reader, instead of read as a datum.

By default, the following tokens are recognized.

#!fold-case

#!no-fold-case

Switches the reader’s case sensitivity; #!fold-case makes the reader case insensitive, and #!no-fold-case makes it case sensitive. (Also see Case-sensitivity).

#!r6rs

This token is introduced in R6RS and used to indicate the program strictly conforms R6RS. Gauche doesn’t conform R6RS, but currently it just issues warning when it sees #!r6rs token, and it keeps reading on.

#!r7rs

Make the reader strict-r7 mode, that complies R7RS. See section Reader lexical mode, for the details.

#!gauche-legacy

Make the reader legacy mode, that is compatible to Gauche 0.9.3 and before. See section Reader lexical mode, for the details.

4.2 Literals

Special Form: quote datum

[R7RS] Evaluates to datum.

(quote x) ⇒ x (quote (1 2 3)) ⇒ (1 2 3)

Reader Syntax: 'datum

[R7RS] Equivalent to (quote datum).

'x ⇒ x '(1 2 3) ⇒ (1 2 3)

Note: RnRS says it is an error to alter the value of a literal expression. Gauche doesn’t check constant-ness of pairs and vectors, and does not signal an error if you modify them using the destructive procedures such as set-car! and vector-set!. Doing so will cause unexpected results. Gauche does check constant-ness of strings, and signals an error if you try to alter a constant string.

4.3 Making Procedures

Special Form: lambda formals body …

Special Form: ^ formals body …

[R7RS+] Evaluates to a procedure. The environment in effect when this expression is evaluated is stored in the procedure. When the procedure is called, body is evaluated sequentially in the stored environment extended by the bindings of the formal arguments, and returns the value(s) of the last expression in the body.

^ is a concise alias of lambda. It is Gauche’s extension.

(lambda (a b) (+ a b)) ⇒ procedure that adds two arguments ((lambda (a b) (+ a b)) 1 2) ⇒ 3 ((^(a b) (+ a b)) 1 2) ⇒ 3

Gauche also extends R7RS lambda to take extended syntax in formals to specify optional and keyword arguments easily. The same functionality can be written in pure R7RS, with parsing variable-length arguments explicitly, but the code tends to be longer and verbose. It is recommended to use extended syntax unless you’re writing portable code.

Formals should have one of the following forms:

• (variable …) : The procedure takes a fixed number of arguments. The actual arguments are bound to the corresponding variables.

  ((lambda (a) a) 1) ⇒ 1 ((lambda (a) a) 1 2) ⇒ error - wrong number of arguments

• variable : The procedure takes any number of arguments. The actual arguments are collected to form a new list and bound to the variable.

  ((lambda a a) 1 2 3) ⇒ (1 2 3)

• (variable_0 … variable_N-1 . variable_N) : The procedure takes at least N arguments. The actual arguments up to N is bound to the corresponding variables. If more than N arguments are given, the rest arguments are collected to form a new list and bound to variable_N.

  ((lambda (a b . c) (print "a=" a " b=" b " c=" c)) 1 2 3 4 5) ⇒ prints a=1 b=2 c=(3 4 5)

• (variable … extended-spec …) : Extended argument specification. Zero or more variables that specifies required formal arguments, followed by an extended spec, a list beginning with a keyword :optional, :key or :rest.

  The extended-spec part consists of the optional argument spec, the keyword argument spec and the rest argument spec. They can appear in any combinations.

  :optional optspec …

  Specifies optional arguments. Each optspec can be either one of the following forms:

  variable (variable init-expr)

  The variable names the formal argument, which is bound to the value of the actual argument if given, or the value of the expression init-expr otherwise. If optspec is just a variable, and the actual argument is not given to it, then variable will be bound to #<undef> (see section Undefined values).

  The expression init-expr is only evaluated if the actual argument for variable is not given. The scope in which init-expr is evaluated includes the preceding formal arguments.

  ((lambda (a b :optional (c (+ a b))) (list a b c)) 1 2) ⇒ (1 2 3) ((lambda (a b :optional (c (+ a b))) (list a b c)) 1 2 -1) ⇒ (1 2 -1) ((lambda (a b :optional c) (list a b c)) 1 2) ⇒ (1 2 #<undef>) ((lambda (:optional (a 0) (b (+ a 1))) (list a b)) ) ⇒ (0 1)

  The procedure signals an error if more actual arguments than the number of required and optional arguments are given, unless it also has :key or :rest argument spec.

  ((lambda (:optional a b) (list a b)) 1 2 3) ⇒ error - too many arguments ((lambda (:optional a b :rest r) (list a b r)) 1 2 3) ⇒ (1 2 (3))

  :key keyspec … [:allow-other-keys [variable]]

  Specifies keyword arguments. Each keyspec can be either one of the following forms.

  variable (variable init-expr) ((keyword variable) init-expr)

  The variable names the formal argument, which is bound to the actual argument given with the keyword of the same name as variable. When the actual argument is not given, init-expr is evaluated and the result is bound to variable in the second and third form, or #<undef> is bound in the first form.

  (define f (lambda (a :key (b (+ a 1)) (c (+ b 1))) (list a b c))) (f 10) ⇒ (10 11 12) (f 10 :b 4) ⇒ (10 4 5) (f 10 :c 8) ⇒ (10 11 8) (f 10 :c 1 :b 3) ⇒ (10 3 1)

  With the third form you can name the formal argument differently from the keyword to specify the argument.

  ((lambda (:key ((:aa a) -1)) a) :aa 2) ⇒ 2

  By default, the procedure with keyword argument spec raises an error if a keyword argument with an unrecognized keyword is given. Giving :allow-other-keys in the formals suppresses this behavior. If you give variable after :allow-other-keys, the list of unrecognized keywords and their arguments are bound to it. Again, see the example below will help to understand the behavior.

  ((lambda (:key a) a) :a 1 :b 2) ⇒ error - unknown keyword :b ((lambda (:key a :allow-other-keys) a) :a 1 :b 2) ⇒ 1 ((lambda (:key a :allow-other-keys z) (list a z)) :a 1 :b 2) ⇒ (1 (:b 2))

  When used with :optional argument spec, the keyword arguments are searched after all the optional arguments are bound.

  ((lambda (:optional a b :key c) (list a b c)) 1 2 :c 3) ⇒ (1 2 3) ((lambda (:optional a b :key c) (list a b c)) :c 3) ⇒ (:c 3 #<undef>) ((lambda (:optional a b :key c) (list a b c)) 1 :c 3) ⇒ error - keyword list not even

  :rest variable

  Specifies the rest argument. If specified without :optional argument spec, a list of remaining arguments after required arguments are taken is bound to variable. If specified with :optional argument spec, the actual arguments are first bound to required and all optional arguments, and the remaining arguments are bound to variable.

  ((lambda (a b :rest z) (list a b z)) 1 2 3 4 5) ⇒ (1 2 (3 4 5)) ((lambda (a b :optional c d :rest z) (list a b c d z)) 1 2 3 4 5) ⇒ (1 2 3 4 (5)) ((lambda (a b :optional c d :rest z) (list a b c d z)) 1 2 3) ⇒ (1 2 3 #<undef> ())

  When the rest argument spec is used with the keyword argument spec, both accesses the same list of actual argument—the remaining arguments after required and optional arguments are taken.

  ((lambda (:optional a :rest r :key k) (list a r k)) 1 :k 3) ⇒ (1 (:k 3) 3)

  See also let-optionals*, let-keywords and let-keywords* macros in Optional argument parsing for an alternative way to receive optional/keyword arguments within the spec of R7RS.

Macro: ^c body …

A shorthand notation of (lambda (c) body …). where c can be any character in #[_a-z].

(map (^x (* x x)) '(1 2 3 4 5)) ⇒ (1 4 9 16 25)

Macro: cut expr-or-slot expr-or-slot2 …

Macro: cute expr-or-slot expr-or-slot2 …

[SRFI-26] Convenience macros to notate a procedure compactly. This form can be used to realize partial application, a.k.a sectioning or projection.

Each expr-or-slot must be either an expression or a symbol <>, indicating a ’slot’. The last expr-or-slot can be a symbol <...>, indicating a ’rest-slot’. Cut expands into a lambda form that takes as many arguments as the number of slots in the given form, and whose body is an expression

(expr-or-slot expr-or-slot2 …)

where each occurrence of <> is replaced to the corresponding argument. In case there is a rest-slot symbol, the resulting procedure is also of variable arity, and all the extra arguments are passed to the call of expr-or-slot. See the fourth example below.

(cut cons (+ a 1) <>) ≡ (lambda (x2) (cons (+ a 1) x2)) (cut list 1 <> 3 <> 5) ≡ (lambda (x2 x4) (list 1 x2 3 x4 5)) (cut list) ≡ (lambda () (list)) (cut list 1 <> 3 <...>) ≡ (lambda (x2 . xs) (apply list 1 x2 3 xs)) (cut <> a b) ≡ (lambda (f) (f a b)) ;; Usage (map (cut * 2 <>) '(1 2 3 4)) (for-each (cut write <> port) exprs)

Cute is a variation of cut that evaluates expr-or-slots before creating the procedure.

(cute cons (+ a 1) <>) ≡ (let ((xa (+ a 1))) (lambda (x2) (cons xa x2)))

Gauche provides a couple of different ways to write partial applications concisely; see the $ macro below, and also the pa$ procedure (see section Combinators).

Macro: $ arg …

A macro to chain applications, hinted from Haskell’s $ operator (although the meaning is different). Within the macro arguments arg …, $ delimits the last argument. For example, the following code makes the last argument for the procedure f to be (g c d …)

($ f a b $ g c d ...) ≡ (f a b (g c d ...))

The $ notation can be chained.

($ f a b $ g c d $ h e f ...) ≡ (f a b (g c d (h e f ...)))

If $* appears in the argument list instead of $, it fills the rest of the arguments, instead of just the last argument.

($ f a b $* g c d ...) ≡ (apply f a b (g c d ...)) ($ f a b $* g $ h $* hh ...) ≡ (apply f a b (g (apply h (hh ...))))

Furthermore, if the argument list ends with $ or $*, the whole expression becomes a procedure expecting the last argument(s).

($ f a b $ g c d $ h e f $) ≡ (lambda (arg) (f a b (g c d (h e f arg)))) ≡ (.$ (cut f a b <>) (cut g c d <>) (cut h e f <>)) ($ f a b $ g c d $ h e f $*) ≡ (lambda args (f a b (g c d (apply h e f args)))) ≡ (.$ (cut f a b <>) (cut g c d <>) (cut h e f <...>))

The more functional the code becomes, the more you tempted to write it as a chain of nested function calls. Scheme’s syntax can get awkward in such code. Close parentheses tend to clutter at the end of expressions. Inner applications tends to pushed toward right columns with the standard indentation rules. Compare the following two code functionally equivalent to each other:

(intersperse ":" (map transform-it (delete-duplicates (map cdr (group-sequence input))))) ($ intersperse ":" $ map transform-it $ delete-duplicates $ map cdr $ group-sequence input)

It is purely a matter of taste, and also this kind of syntax sugars can be easily abused. Use with care, but it may work well if used sparingly, like spices.

As a corner case, if neither $ nor $* appear in the argument list, it just calls the function.

($ f a b c) ≡ (f a b c)

Macro: case-lambda clause …

[R7RS][SRFI-16] Each clause should have the form (formals expr …), where formals is a formal arguments list as for lambda.

This expression evaluates to a procedure that accepts a variable number of arguments and is lexically scoped in the same manner as procedures resulting from lambda expressions. When the procedure is called with some arguments, then the first clause for which the arguments agree with formals is selected, where agreement is specified as for the formals of a lambda expression. The variables of formals are bound to the given arguments, and the expr … are evaluated within the environment.

It is an error for the arguments not to agree with the formals of any clause.

4.4 Assignments

Special Form: set! symbol expression

Special Form: set! (proc arg …) expression

[R7RS][SRFI-17] First, expression is evaluated. In the first form, the binding of symbol is modified so that next reference of symbol will return the result of expression. If symbol is not locally bound, the global variable named symbol must already exist, or an error is signaled.

The second form is a “generalized set!” specified in SRFI-17. It is a syntactic sugar of the following form.

((setter proc) arg … expression)

Note the order of the arguments of the setter method differs from CommonLisp’s setf.

Some examples:

(define x 3) (set! x (list 1 2)) x ⇒ (1 2) (set! (car x) 5) x ⇒ (5 2)

Macro: set!-values (var …) expr

Sets values of multiple variables at once. Expr must yield as many values as var …. Each value is set to the corresponding var.

(define a 0) (define b 1) (set!-values (a b) (values 3 4)) a ⇒ 3 b ⇒ 4 (set!-values (a b) (values b a)) a ⇒ 4 b ⇒ 3

Function: setter proc

[SRFI-17] Returns a setter procedure associated to the procedure proc. If no setter is associated to proc, its behavior is undefined.

A setter procedure g of a procedure f is such that when used as (g a b … v), the next evaluation of (f a b …) returns v.

To associate a setter procedure to another procedure, you can use the setter of setter, like this:

(set! (setter f) g)

A procedure’s setter can be “locked” to it. System default setters, like set-car! for car, is locked and can’t be set by the above way. In order to lock a setter to a user defined procedure, use getter-with-setter below.

If proc is not a procedure, a setter generic function of object-apply is returned; it allows the applicable object extension to work seamlessly with the generalized set!. See section Applicable objects, for the details.

Function: has-setter? proc

Returns #t if a setter is associated to proc.

Function: getter-with-setter get set

[SRFI-17] Takes two procedure get and set. Returns a new procedure which does the same thing as get, and its setter is locked to set.

The intention of this procedure is, according to the SRFI-17 document, to allow implementations to inline setters efficiently. Gauche hasn’t implement such optimization yet.

A few macros that adopts the same semantics of generalized set! are also provided. They are built on top of set!.

Macro: push! place item

Conses item and the value of place, then sets the result to place. place is either a variable or a form (proc arg …), as the second argument of set!. The result of this form is undefined.

(define x (list 2)) (push! x 3) x ⇒ (3 2) (push! (cdr x) 4) x ⇒ (3 4 2)

When place is a list, it roughly expands like the following.

(push! (foo x y) item) ≡ (let ((tfoo foo) (tx x) (ty y)) ((setter tfoo) tx ty (cons item (tfoo tx ty))))

Note: Common Lisp’s push macro takes its argument reverse order. I adopted this order since it is consistent with other destructive operations. Perl’s push function takes the same argument order, but it appends item at the end of the array (Perl’s unshift is closer to push!). You can use a queue (see section data.queue - Queue) if you need a behavior of Perl’s push.

Macro: pop! place

Retrieves the value of place, sets its cdr back to place and returns its car.

(define x (list 1 2 3)) (pop! x) ⇒ 1 x ⇒ (2 3) (define x (vector (list 1 2 3))) x ⇒ #((1 2 3)) (pop! (vector-ref x 0)) ⇒ 1 x ⇒ #((2 3))

Note: This works the same as Common Lisp’s pop. Perl’s pop pops value from the end of the sequence; its shift does the same thing as pop!.

Macro: inc! place :optional delta

Macro: dec! place :optional delta

Evaluates the value of place. It should be a number. Adds (inc!) or subtracts (dec!) delta to/from it, and then stores the result to place. The default value of delta is 1.

This is like Common Lisp’s incf and decf, except that you can’t use the result of inc! and dec!.

Macro: update! place proc

Generalized form of push! etc. Proc must be a procedure which takes one argument and returns one value. The original value of place is passed to the proc, then its result is set to place.

(define a (cons 2 3)) (update! (car a) (lambda (v) (* v 3))) a ⇒ (6 . 3) (update! (cdr a) (cut - <> 3)) a ⇒ (6 . 0)

4.5 Conditionals

Special Form: if test consequent alternative

Special Form: if test consequent

[R7RS] Test is evaluated. If it yields a true value, consequent is evaluated. Otherwise, alternative is evaluated. If alternative is not provided, it results undefined value.

(if (number? 3) 'yes 'no) ⇒ yes (if (number? #f) 'yes 'no) ⇒ no (let ((x '(1 . 2))) (if (pair? x) (values (car x) (cdr x)) (values #f #f))) ⇒ 1 and 2

Special Form: cond clause1 clause2 …

[R7RS][SRFI-61] Each clause must be the form

(test expr …) (test => expr) (test guard => expr) (else expr expr2 …)

The last form can appear only as the last clause.

cond evaluates test of each clauses in order, until it yields a true value. Once it yields true, if the clause is the first form, the corresponding exprs are evaluated and the result(s) of last expr is(are) returned; if the clause is the second form, the expr is evaluated and it must yield a procedure that takes one argument. Then the result of test is passed to it, and the result(s) it returns will be returned.

The third form is specified in SRFI-61. In this form, test can yield arbitrary number of values. The result(s) of test is(are) passed to guard; if it returns a true value, expr is applied with an equivalent argument list, and its result(s) is(are) returned. If guard returns #f, the evaluation proceeds to the next clause.

If no test yields true, and the last clause is not the fourth form (else clause), an undefined value is returned.

If the last clause is else clause and all tests are failed, exprs in the else clause are evaluated, and its last expr’s result(s) is(are) returned.

(cond ((> 3 2) 'greater) ((< 3 2) 'less)) ⇒ greater (cond ((> 3 3) 'greater) ((< 3 3) 'less) (else 'equal)) ⇒ equal (cond ((assv 'b '((a 1) (b 2))) => cadr) (else #f)) ⇒ 2

Special Form: case key clause1 clause2 …

[R7RS][SRFI-87] Key may be any expression. Each clause should have the form

((datum ...) expr expr2 …) ((datum ...) => proc)

where each datum is an external representation of some object. All the datums must be distinct. The last clause may be an “else clause,” which has the form

(else expr expr2 …) (else => proc)

First, key is evaluated and its result is compared against each datum. If the result of evaluating key is equivalent (using eqv?, see section Equality), to a datum, then the expressions in the corresponding clause are evaluated sequentially, and the result(s) of the last expression in the clause is(are) returned from the case expression. The forms containing => are specified in SRFI-87. In these forms, the result of key is passed to proc, and its result(s) is(are) returned from the case expression.

If the result of evaluating key is different from every datum, then if there is an else clause its expressions are evaluated and the result(s) of the last is(are) the result(s) of the case expression; otherwise the result of the case expression is undefined.

(case (* 2 3) ((2 3 5 7) 'prime) ((1 4 6 8 9) 'composite)) ⇒ composite (case (car '(c d)) ((a) 'a) ((b) 'b)) ⇒ undefined (case (car '(c d)) ((a e i o u) 'vowel) ((w y) 'semivowel) (else 'consonant)) ⇒ consonant (case 6 ((2 4 6 8) => (cut + <> 1)) (else => (cut - <> 1))) ⇒ 7 (case 5 ((2 4 6 8) => (cut + <> 1)) (else => (cut - <> 1))) ⇒ 4

Macro: ecase key clause1 clause2 …

This works exactly like case, except when there’s no else clause and the value of key expression doesn’t match any of datums provided in clauses. While case form returns undefined value for such case, ecase raises an error.

It is taken from Common Lisp. It’s a convenient form when you want to detect when unexpected value is passed just in case.

(ecase 5 ((1) 'a) ((2 3) 'b) ((4) 'c)) ⇒ ERROR: ecase test fell through: got 5, expecting one of (1 2 3 4)

Special Form: and test …

[R7RS] The test expressions are evaluated from left to right, and the value of the first expression that evaluates to a false value is returned. Any remaining expressions are not evaluated. If all the expressions evaluate to true values, the value of the last expression is returned. If there are no expressions then #t is returned.

(and (= 2 2) (> 2 1)) ⇒ #t (and (= 2 2) (< 2 1)) ⇒ #f (and 1 2 'c '(f g)) ⇒ (f g) (and) ⇒ #t

Special Form: or test …

[R7RS] The test expressions are evaluated from left to right, and the value of the first expression that evaluates to a true value is returned. Any remaining expressions are not evaluated. If all expressions evaluate to false values, the value of the last expression is returned. If there are no expressions then #f is returned.

(or (= 2 2) (> 2 1)) ⇒ #t (or (= 2 2) (< 2 1)) ⇒ #t (or #f #f #f) ⇒ #f (or (memq 'b '(a b c)) (/ 3 0)) ⇒ (b c)

Special Form: when test expr1 expr2 …

Special Form: unless test expr1 expr2 …

[R7RS] Evaluates test. If it yields true value (or false in case of unless), expr1 and expr2 … are evaluated sequentially, and the result(s) of the last evaluation is(are) returned. Otherwise, undefined value is returned.

4.6 Binding constructs

Special Form: let ((var expr) …) body …

Special Form: let* ((var expr) …) body …

Special Form: letrec ((var expr) …) body …

Special Form: letrec* ((var expr) …) body …

[R7RS] Creates a local scope where var … are bound to the value of expr …, then evaluates body …. vars must be symbols, and there shouldn’t be a duplication. The value(s) of the last expression of body … becomes the value(s) of this form.

The four forms differ in terms of the scope and the order exprs are evaluated. Let evaluates exprs before (outside of) let form. The order of evaluation of exprs is undefined, and the compiler may reorder those exprs freely for optimization. Let* evaluates exprs, in the order they appears, and each expr is evaluated in the scope where vars before it are bound.

Letrec evaluates exprs, in an undefined order, in the environment where vars are already bound (to an undefined value, initially). letrec is necessary to define mutually recursive local procedures. Finally, letrec* uses the same scope rule as letrec, and it evaluates expr in the order of appearance.

(define x 'top-x) (let ((x 3) (y x)) (cons x y)) ⇒ (3 . top-x) (let* ((x 3) (y x)) (cons x y)) ⇒ (3 . 3) (let ((cons (lambda (a b) (+ a b))) (list (lambda (a b) (cons a (cons b 0))))) (list 1 2)) ⇒ (1 2 . 0) (letrec ((cons (lambda (a b) (+ a b))) (list (lambda (a b) (cons a (cons b 0))))) (list 1 2)) ⇒ 3

You need to use letrec* if evaluation of one expr requires the value of var that appears before the expr. In the following example, calculating the value of a and b requires the value of cube, so you need letrec*. (Note the difference from the above example, where calculating the value of list doesn’t need to take the value of cons bound in the same letrec. The value of cons isn’t required until list is actually applied.)

(letrec* ((cube (lambda (x) (* x x x))) (a (+ (cube 1) (cube 12))) (b (+ (cube 9) (cube 10)))) (= a b)) ⇒ #t

This example happens to work with letrec in the current Gauche, but it is not guaranteed to keep working in future. You just should not rely on evaluation order when you use letrec. In retrospect, it would be a lot simpler if we only have letrec*. Unfortunately letrec preceded for long time in Scheme history and it’s hard to remove that. Besides, letrec does have more opportunities to optimize than letrec*.

Macro: let1 var expr body …

A convenient macro when you have only one variable. Expanded as follows.

(let ((var expr)) body …)

Macro: if-let1 var expr then

Macro: if-let1 var expr then else

This macro simplifies the following idiom:

(let1 var expr (if var then else))

Macro: rlet1 var expr body …

This macro simplifies the following idiom:

(let1 var expr body … var)

Macro: and-let* (binding …) body …

[SRFI-2] In short, it works like let*, but returns #f immediately whenever the expression in bindings evaluates to #f.

Each binding should be one of the following form:

(variable expression)

The expression is evaluated; if it yields true value, the value is bound to variable, then proceed to the next binding. If no more bindings, evaluates body …. If expression yieds #f, stops evaluation and returns #f from and-let*.

(expressionx)

In this form, variable is omitted. Expression is evaluated and the result is used just to determine whether we continue or stop further evaluation.

bound-variable

In this form, bound-variable should be an identifier denoting a bound variable. If its value is not #f, we continue the evaluation of the clauses.

Let’s see some examples. The following code searches key from an assoc-list alist and returns its value if found.

(and-let* ((entry (assoc key alist))) (cdr entry))

If arg is a string representation of an exact integer, returns its value; otherwise, returns 0:

(or (and-let* ((num (string->number arg)) ( (exact? num) ) ( (integer? num) )) num) 0)

The following is a hypothetical code that searches a certain server port number from a few possibilities (environment variable, configuration file, ...)

(or (and-let* ((val (sys-getenv "SERVER_PORT"))) (string->number val)) (and-let* ((portfile (expand-path "~/.server_port")) ( (file-exists? portfile) ) (val (call-with-input-string portfile port->string))) (string->number val)) 8080) ; default

Macro: and-let1 var test exp1 exp2 …

Evaluates test, and if it isn’t #f, binds var to it and evaluates exp1 exp2 …. Returns the result(s) of the last expression. If test evaluates to #f, returns #f.

This can be easily written by and-let* or if-let1 as follows. However, we’ve written this idiom so many times that it deserves another macro.

(and-let1 var test exp1 exp2 …) ≡ (and-let* ([var test]) exp1 exp2 …) ≡ (if-let1 var test (begin exp1 exp2 …) #f)

Macro: fluid-let ((var val) …) body …

A macro that emulates dynamic scoped variables. Vars must be variables bound in the scope including fluid-let form. Vals are expressions. Fluid-let first evaluates vals, then evaluates body …, with binding vars to the corresponding values during the dynamic scope of body ….

Note that, in multithreaded environment, the change of the value of vars are visible from all the threads. This form is provided mainly for the porting convenience. Use parameter objects instead (see section gauche.parameter - Parameters) for thread-local dynamic state.

(define x 0) (define (print-x) (print x)) (fluid-let ((x 1)) (print-x)) ⇒ ;; prints 1

Special Form: receive formals expression body …

[SRFI-8] This is the way to receive multiple values. Formals can be a (maybe-improper) list of symbols. Expression is evaluated, and the returned value(s) are bound to formals like the binding of lambda formals, then body … are evaluated.

(define (divrem n m) (values (quotient n m) (remainder n m))) (receive (q r) (divrem 13 4) (list q r)) ⇒ (3 1) (receive all (divrem 13 4) all) ⇒ (3 1) (receive (q . rest) (divrem 13 4) (list q rest)) ⇒ (3 (1))

See also call-with-values in Multiple values which is the procedural equivalent of receive. You can use define-values (see section Definitions) to bind multiple values to variables simultaneously. Also let-values and let*-values in SRFI-11 (srfi-11 - Let-values) provides let-like syntax with multiple values.

Macro: rec var expr

Macro: rec (name . vars) expr …

[SRFI-31] A macro to evaluate an expression with recursive reference.

In the first form, evaluates expr while var in expr is bound to the result of expr. The second form is equivalent to the followings.

(rec name (lambda vars expr …))

Some examples:

;; constant infinite stream (rec s (cons 1 (delay s))) ;; factorial function (rec (f n) (if (zero? n) 1 (* n (f (- n 1)))))

4.7 Sequencing

Special Form: begin form …

[R7RS] Evaluates forms sequentially, and returns the last result(s).

Begin doesn’t introduce new scope like let, that is, you can’t place "internal define" at the beginning of forms generally. Semantically begin behaves as if forms are spliced into the surrounding context. For example, toplevel expression like the following is the same as two toplevel definitions:

(begin (define x 1) (define y 2))

Here’s a trickier example:

(let () (begin (define x 2) (begin (define y 3) )) (+ x y)) ≡ (let () (define x 2) (define y 3) (+ x y))

Macro: begin0 exp0 exp1 …

Evaluates exp0, exp1, …, then returns the result(s) of exp0. The name is taken from MzScheme. This is called prog1 in CommonLisp.

Unlike begin, this does creates a new scope, for the begin0 form is expanded as follows.

(receive tmp exp0 exp1 … (apply values tmp))

4.8 Iteration

Special Form: do ((variable init [step]) …) (test expr …) body …

[R7RS]

1. Evaluates init … and binds variable … to each result. The following steps are evaluated under the environment where variables are bound.
2. Evaluate test. If it yields true, evaluates expr … and returns the result(s) of last expr.
3. Otherwise, evaluates body … for side effects.
4. Then evaluates step … and binds each result to a fresh variable …, and repeat from the step 2.

The following example loops 10 times while accumulating each value of i to j and returns it.

(do ((i 0 (+ i 1)) (j 0 (+ i j))) ((= i 10) j) (print j)) ⇒ 45 ; also prints intermediate values of j

If step is omitted, the previous value of variable is carried over. When there’s no expr, the non-false value returned by test becomes the value of the do expression.

Since do syntax uses many parentheses, some prefer using square brackets as well as parentheses to visually distinguish the groupings. A common way is to group each variable binding, and the test clause, by square brackets.

(do ([i 0 (+ i 1)] [j 0 (+ i j)]) [(= i 10) j] (print j))

Note: Unlike Common Lisp (and “for loops” in many languages), variable is freshly bound for each iteration. The following example loops 5 times and creates a list of closures, each of which closes the variable i. When you call each closures, you can see that each of them closes different i at the time of the iteration they were created.

(define closures (do ([i 0 (+ i 1)] [c '() (cons (^[] i) c)]) [(= i 5) (reverse c)] )) ((car closures)) ⇒ 0 ((cadr closures)) ⇒ 1

Special Form: let name ((var init) …) body …

[R7RS] This variation of let is called “named let”. It creates the following procedure and binds it to name, then calls it with init ….

(lambda (var …) body …)

This syntax itself isn’t necessarily related to iteration. However, the whole point of named let is that the above lambda expression is within the scope of name—that is, you can call name recursively within body. Hence this is used very often to write a loop by recursion (thus, often the procedure is named loop, as in the following example.)

(let loop ([x 0] [y '()]) (if (= x 10) y (loop (+ x 1) (cons x y)))) ⇒ (9 8 7 6 5 4 3 2 1 0)

Of course you don’t need to loop with a named let; you can call name in non-tail position, pass name to other higher-order procedure, etc. Named let exists since it captures a very common pattern of local recursive procedures. Some Schemers even prefer named let to do, for the better flexibility.

The following rewrite rule precisely explains the named let semantics. The tricky use of letrec in the expansion is to make proc visible from body … but not from init ….

(let proc ((var init) …) body …) ≡ ((letrec ((proc (lambda (var …) body …))) proc) init …)

Macro: dotimes ([variable] expr [result]) body …

Macro: dolist ([variable] expr [result]) body …

Imported from Common Lisp. The full form are expanded as follows:

(dotimes (variable expr result) body …) ≡ (do ((limit expr) (variable 0 (+ variable 1))) ((>= variable expr) result) body …) (dolist (variable expr result) body …) ≡ (begin (for-each (lambda (variable) body …) expr) (let ((variable '())) result))

(The reason we bind variable to () to evaluate result in dolist is the CL compatibility.)

You can omit result, or both result and variable. That is, if the first argument has two elements, they’re variable and expr. In which case, the result of these forms is undefined.

If both result and variable are omitted, these forms just repeatedly executes body … number of times determined by expr.

;; print "a" 10 times. (dotimes (10) (print "a")) ;; print "a" (length lst) times. (dolist (lst) (print "a"))

See also srfi-42 - Eager comprehensions, which provides rich way to iterate.

Macro: while expr body …

Macro: while expr => var body …

Macro: while expr guard => var body …

Var is an identifier and guard is a procedure that takes one argument.

In the first form, expr is evaluated, and if it yields a true value, body … are evaluated. It is repeated while expr yields true value.

In the second form, var is bound to a result of expr in the scope of body ….

In the third form, the value expr yields are passed to guard, and the execution of body … is repeated while guard returns a true value. var is bound to the result of expr.

The return value of while form itself isn’t specified.

(let ((a '(0 1 2 3 4))) (while (pair? a) (write (pop! a)))) ⇒ prints "01234" (let ((a '(0 1 2 3 #f 5 6))) (while (pop! a) integer? => var (write var))) ⇒ prints "0123"

Macro: until expr body …

Macro: until expr guard => var body …

Like while, but the condition is reversed. That is, the first form repeats evaluation of expr and body … until expr yields true. In the second form, the result of expr is passed to guard, and the execution is repeated until it returns true. Var is bound to the result of expr.

(The second form without guard isn’t useful in until, since var would always be bound to #f).

The return value of until form itself isn’t specified.

(let ((a '(0 1 2 3 4))) (until (null? a) (write (pop! a)))) ⇒ prints "01234" (until (read-char) eof-object? => ch (write-char ch)) ⇒ reads from stdin and writes char until EOF is read

4.9 Quasiquotation

Special Form: quasiquote template

[R7RS] Quasiquotation is a convenient way to build a structure that has some fixed parts and some variable parts. See the explanation below.

Reader Syntax: `template

[R7RS] The syntax `x is read as (quasiquote x).

Special Form: unquote datum …

Special Form: unquote-splicing datum …

[R7RS] These syntaxes have meaning only when they appear in the template of quasiquoted form. R5RS says nothing about these syntaxes appear outside of quasiquote. Gauche signals an error in such case, for it usually indicates you forget quasiquote somewhere.

R5RS only allows unquote and unquote-splicing to take a single argument; it is undefined if you have (unquote) or (unquote x y) inside quasiquoted form. R6RS allows zero or multi-arguments, and Gauche follows that.

Reader Syntax: ,datum

Reader Syntax: ,@datum

[R7RS] The syntaxes ,x and ,@x are read as (unquote x) and (unquote-splicing x), respectively.

Quasiquote basics

Suppose you want to create a list (foo bar x y), where foo and bar are symbols, and x and y are the value determined at runtime. (For the sake of explanation, let’s assume we have variables x and y that provides those values.) One way to do that is to call the function list explicitly.

(let ((x 0) (y 1))
  (list 'foo 'bar x y)) ⇒ (foo bar 0 1)

You can do the same thing with quasiquote, like this:

(let ((x 0) (y 1))
  `(foo bar ,x ,y))  ⇒ (foo bar 0 1)

The difference between the two notations is that the explicit version quotes the parts that you want to insert literally into the result, while the quasiquote version unquotes the parts that you don’t want to quote.

The quasiquote version gets simpler and more readable when you have lots of static parts with scattered variable parts in your structure.

That’s why quasiquote is frequently used with legacy macros, which are basically a procedure that create program fragments from variable parts provided as macro arguments. See the simple-minded my-if macro that expands to cond form:

(define-macro (my-if test then else)
  `(cond (,test ,then)
         (else ,else)))

(macroexpand '(my-if (< n 0) n (- n)))
  ⇒ (cond ((< n 0) n) (else (- n)))

Note the two elses in the macro definition; one isn’t unquoted, thus appears liteally in the output, while another is unquoted and the corresponding macro argument is inserted in its place.

Of course you can use quasiquotes unrelated to macros. It is a general way to construct structures. Some even prefer using quasiquote to explicit construction even most of the structure is variable, for quasiquoted form can be more concise. Gauche also tries to minimize runtime allocation for quasiquoted forms, so it may potentially be more efficient; see "How static are quasiquoted forms?" below.

Splicing

When (unquote-splicing expr) appears in a quasiquoted form, expr must evaluate to a list, which is spliced into the surrounding context. It’s easier to see examples:

(let ((x '(1 2 3)))
  `(a ,@x b)) ⇒ (a 1 2 3 b)

(let ((x '(1 2 3)))
  `(a ,x b)) ⇒ (a (1 2 3) b)

(let ((x '(1 2 3)))
  `#(a ,@x b)) ⇒ #(a 1 2 3 b)

Compare the unquote version and unquote-splicing version. Splicing also works within a vector.

Multi-argument unquotes

If unquote or unquote-splicing takes multiple arguments, they are interpreted as if each of its arguments are unquoted or unquote-spliced.

;; This is the same result as `(,(+ 1 2) ,(+ 2 3) ,(+ 3 4))
`((unquote (+ 1 2) (+ 2 3) (+ 3 4)))
  ⇒ (3 5 7)

;; This is the same result as
;;   `(,@(list 1 2) ,@(list 2 3) ,@(list 3 4))
`((unquote-splicing (list 1 2) (list 2 3) (list 3 4)))
  ⇒ (1 2 2 3 3 4)

;; Edge cases
`((unquote))          ⇒ ()
`((unquote-splicing)) ⇒ ()

It is an error for zero or multiple argument unquote/unquote-splicing forms appear which you cannot splice multiple forms into.

;; Multiple arguments unquotes are error in non-splicing context
`(unquote 1 2)          ⇒ error
`(unquote-splicing 1 2) ⇒ error

Note that the abbreviated notations ,x and ,@x are only for single-argument forms. You have to write unquote or unquote-splicing explicitly for zero or multiple argument forms; thus you don’t usually need to use them. These forms are supported mainly to make the nested unquoting forms such as ,,@ and ,@,@—R5RS cannot handle the case the inner unquote-splicing form expands into zero or multiple forms.

How static are quasiquoted forms?

When quasiquoted form contains variable parts, what happens at runtime is just the same as when an explicit form is used: `(,x ,y) is evaluated exactly like (list x y). However, Gauche tries to minimize runtime allocation when a quasiquoted form has static parts.

First of all, if there’s no variable parts in quasiquoted form, like `(a b c), the entire form is allocated statically. If there is a static tail in the structure, it is also allocated statically; e.g. `((,x a b) (,y c d)) works like (list (cons x '(a b)) (cons y '(c d))).

Furthermore, when an unquoted expression is a constant expression, Gauche embeds it into the static form. If you’ve defined a constant like (define-constant x 3), then the form `(,x ,(+ x 1)) is compiled as the constant '(3 4). (See Definitions, for the explanation of define-constant form.)

In general it is hard to say which part of quasiquoted form is compiled as a static datum and which part is not, so you shouldn’t write a code that assumes some parts of the structure returned from quasiquote are freshly allocated. In other words, you better avoid mutating such structures.

4.10 Definitions

Special Form: define variable expression

Special Form: define (variable . formals) body …

[R7RS+] This form has different meanings in the toplevel (without no local bindings) or inside a local scope.

On toplevel, it defines a global binding to a symbol variable. In the first form, it globally binds a symbol variable to the value of expression, in the current module.

(define x (+ 1 2)) x ⇒ 3 (define y (lambda (a) (* a 2))) (y 8) ⇒ 16

The second form is a syntactic sugar of defining a procedure. It is equivalent to the following form.

(define (name . args) body …) ≡ (define name (lambda args body …))

If the form appears inside a local scope (internal define), this introduce a local binding of the variable.

Internal defines can appear in the beginning of body of lambda or other forms that introduces local bindings. They are equivalent to a letrec* form, as shown below.

(lambda (a b) (define (cube x) (* x x x)) (define (square x) (* x x)) (+ (cube a) (square b))) ≡ (lambda (a b) (letrec* ([cube (lambda (x) (* x x x))] [square (lambda (x) (* x x))]) (+ (cube a) (square b))))

Since internal defines are essentially a letrec* form, you can write mutually recursive local functions, and you can use preceding bindings introduced in the same scope to calculate the value to be defined. However, you can’t use a binding that is introduced after an internal define form to calculate its value; if you do so, Gauche may not report an error immediately, but you may get strange errors later on.

(lambda (a) (define x (* a 2)) (define y (+ x 1)) ; ok to use x to calculate y (* a y)) (lambda (a) ;; You can refer to even? in odd?, since the value of even? ;; isn't used at the time odd? is defined; it is only used ;; when odd? is called. (define (odd? x) (or (= x 1) (not (even? (- x 1))))) (define (even? x) (or (= x 0) (not (odd? (- x 1))))) (odd? a)) (lambda (a) ;; This is not ok, for defining y needs to use the value ;; of x. However, you may not get an error immediately. (define y (+ x 1)) (define x (* a 2)) (* a y))

Inside the body of binding constructs, internal defines must appear before any expression of the same level. The following code isn’t allowed, for an expression (print a) precedes the define form.

(lambda (a) (print a) (define (cube x) (* x x x)) ; error! (cube a))

It is also invalid to put no expressions but internal defines inside the body of binding constructs, although Gauche don’t report an error.

Note that begin (see section Sequencing) doesn’t introduce a new scope. Defines in the begin act as if begin and surrounding parenthesis are not there. Thus these two forms are equivalent.

(let ((x 0)) (begin (define (foo y) (+ x y))) (foo 3)) ≡ (let ((x 0)) (define (foo y) (+ x y)) (foo 3))

Macro: define-values (var …) expr

Macro: define-values (var var1 … . var2) expr

Macro: define-values var expr

[R7RS] Expr is evaluated, and each value of the result is bound to each vars. In the first form, it is an error unless expr yields the same number of values as vars.

(define-values (lo hi) (min&max 3 -1 15 2)) lo ⇒ -1 hi ⇒ 15

In the second form, expr may yield as many values as var var1 … or more; the excess values are made into a list and bound to var2.

(define-values (a b . c) (values 1 2 3 4)) a ⇒ 1 b ⇒ 2 c ⇒ (3 4)

In the last form, all the values yielded by expr are gathered to a list and bound to var.

(define-values qr (quotient&remainder 23 5)) qr ⇒ (4 3)

You can use define-values wherever define is allowed; that is, you can mix define-values in internal defines.

(define (foo . args) (define-values (lo hi) (apply min&max args)) (define len (length args)) (list len lo hi)) (foo 1 4 9 3 0 7) ⇒ (6 0 9)

See section srfi-11 - Let-values.

Special Form: define-constant variable expression

Special Form: define-constant (variable . formals) body …

This form is only effective in toplevel. Like top-level define, but that the compiler assumes the value of variable won’t change and generates optimized code.

An error is signaled when you use set! to change the value of variable. It is allowed to redefine variable, but a warning is printed.

There’s no “internal define-constant”, since the compiler can figure out whether a local binding is mutated, and optimize code accordingly, without a help of declarations.

Special Form: define-in-module module variable expression

Special Form: define-in-module module (variable . formals) body …

This form must appear in the toplevel. It creates a global binding of variable in module, which must be either a symbol of the module name or a module object. If module is a symbol, the named module must exist.

Expression is evaluated in the current module.

The second form is merely a syntactic sugar of:

(define-in-module module variable (lambda formals body …))

Note: to find out if a symbol has definition (global binding) in the current module, you can use global-variable-bound? (see section Module introspection).

4.11 Inclusions

Special Form: include filename …

Special Form: include-ci filename …

[R7RS] Reads filename … at compile-time, and insert their contents as if the forms are placed in the includer’s source file, surrounded by begin. The include form reads files as is, while include-ci reads files in case-insensitive way, as if #!fold-case is specified in the beginning of the file (see section Case-sensitivity).

The coding magic comment in each file is honored while reading that file (see section Multibyte scripts).

If filename is absolute, the file is just searched. If it is relative, the file is first searched relative to the file contaning the include form, then the directories in *load-path* are tried.

Example: Suppose a file ‘a.scm’ contains the following code:

(define x 0) (define y 1)

You can include this file into another source, like this:

(define (foo) (include "a.scm") (list x y))

It works as if the source is written as follows:

(define (foo) (begin (define x 0) (define y 1)) (list x y))

(Note: In version 0.9.4, include behaved differently when pathname begins with either ./ or ../—in which case the file is searched relative to the current working directory of the compiler. It is rather an artifact of include sharing file search routine with load. But unlike load, which is a run-time operation, using relative path to the current directory won’t make much sense for include, so we changed the behavior in 0.9.5.)

Gauche has other means to incorporate source code from another files. Here’s the comparison.

require (use and extend calls require internally)

• Both require and include work at compile-time.
• Require works only in toplevel context, while include can be anywhere.
• Require reads the file only once (second and later require on the same file becomes no-op), while include reads the file every place it appears.
• The file is searched from *load-path*. The location of the file require form appears doesn’t matter. (You can add directories relative to the requiring file using the :relative flag in add-load-path, though).
• Even if the current module is changed by select-module inside the required file, it is only effective while the required file is read. On the other hand, include inserts any S-expressions in the included file to the place include appears, so the effect of select-module persists after include form (Note: Encoding magic comment and #!fold-case/#!no-fold-case are dealt with by the reader, so those effect is contained in the file even with include).
• It is forbidden to the file loaded by require to insert a toplevel binding without specifying a module. In other words, the file you require should generally use define-module, select-module or define-library. See section Require and provide, for further discussion. On the other hand, include has no such restrictions.

load

• Works at runtime, while include works at compile-time.
• Works only in toplevel context, while include can be anywhere.
• The file is searched from *load-path*.
• As the case with require, change of the current module won’t persist after load.

Usually, require (or use and extend) are better way to incorporate sources in other files. The include form is mainly for the tricks that can’t be acheved with require. For example, you have a third-party R5RS code and you want to wrap it with Gauche module system. Using include, you place the following small source file along the third-party code, and you can load the code with (use third-party-module) without changing the original code at all.

(define-module third-party-module
  (export proc ...)
  (include "third-party-source.scm"))

4.12 Feature conditional

The cond-expand macro

Sometimes you need to have a different piece of code depending on available features provided by the implemantation and/or platform. For example, you may want to switch behavior depending on whether networking is available, or to embed an implementation specific procedures in otherwise-portable code.

In C, you use preprocessor directives such as #ifdef. In Common Lisp, you use reader macro #+ and #-. In Scheme, you have cond-expand:

Macro: cond-expand (feature-requirement command-or-definition …) …

[SRFI-0][R7RS] This macro expands to command-or-definition … if feature-requirement is supported by the current platform.

feature-requirement must be in the following syntax:

feature-requirement : feature-identifier | (and feature-requirement …) | (or feature-requirement …) | (not feature-requirement) | (library library-name)

The macro tests each feature-requirement in order, and if one is satisfied, the macro itself expands to the corresponding command-or-definition ….

The last clause may have else in the position of feature-requirement, to make the clause expanded if none of the previous feature requirement is fulfilled.

If there’s neither a satisfying clause nor else clause, cond-expand form throws an error. It is to detect the case early that the platform doesn’t have required features. If the feature you’re testing is optional, that is, your program works without the feature as well, add empty else clause as follows.

(cond-expand [feature expr] ; some optional feature [else])

feature-identifier is a symbol that indicates a feature. If such a feature is supported in the current platform, it satisfies the feature-requirement. You can do boolean combination of feature-requirements to compose more complex conditions.

The form (library library-name) is added in R7RS, and it is fulfilled when the named library is available. Since this is R7RS construct, you have to use R7RS-style library name— list of symbols/integers, e.g. (gauche net) instead of gauche.net.

Here’s a typical example: Suppose you want to have implementation-specific part for Gauche, Chicken Scheme and ChibiScheme. Most modern Scheme impelementations defines a feature-identifier to identify itself. You can write the conditional part as follows:

(cond-expand [gauche (gauche-specific-code)] [(or chicken chibi) (chicken-chibi-specific-code)] [else (fallback-code)] )

It is important that the conditions of cond-expand is purely examined at the macro-expansion time, and unfulfilled clauses are discarded. Thus, for example, you can include macro calls or language extensions that may not be recognized on some implementations. You can also conditionally define global bindings.

Compare that to cond, which examines conditions at runtime. If you include unsupported macro call in one of the conditions, it may raise an error at macro expansion time, even if that clause will never be executed on the platform. Also, it is not possible to conditionally define global bindings using cond.

There’s a caveat, though. Suppose you want to save the result of macro expansion, and run the expanded result later on other platforms. The result code is based on the features of the platform the macro expansion takes place, which may not agree with the features of the platform the code will run. (This issue always arises in cross-compiling situation in general.)

See below for the list of feature identifiers defined in Gauche.

Gauche-specific feature identifiers

gauche

gauche-X.X.X

Indicates you’re running on Gauche. It is useful to put Gauche-specific code in a portable program. X.X.X is the gauche’s version (e.g. gauche-0.9.4), in case you want to have code for specific Gauche version. (Such feature identifier is suggested by R7RS; but it might not be useful if we don’t have means to compare versions. Something to consider in future versions.)

gauche.os.windows

gauche.os.cygwin

Defined on Windows-native platform and Cygwin/Windows platform, respectively. If neither is defined you can assume it’s a unix variant. (Cygwin is supposedly unix variant, but corners are different enough to deserve it’s own feature identifier.)

gauche.ces.utf8

gauche.ces.eucjp

gauche.ces.sjis

gauche.ces.none

Either one of these is defined based on Gauche’s native character encoding scheme. See section Multibyte strings, for the details.

gauche.net.tls

Defined if the runtime supports TLS in networking.

gauche.net.ipv6

Defined if the runtime supports IPv6. Note that this only indicates Gauche has been built with IPv6 support; the OS may not allow IPv6 features, in that case you’ll get system error when you try to use IPv6.

gauche.sys.threads

gauche.sys.pthreads

gauhce.sys.wthreads

If the runtime supports multithreading, gauche.sys.threads is defined (see section gauche.threads - Threads). Multithreading is based on either POSIX pthreads or Windows threads. The former defines gauche.sys.pthreads, and the latter defines gauche.sys.wthreads.

gauche.sys.sigwait

gauche.sys.setenv

gauche.sys.unsetenv

gauche.sys.clearenv

gauche.sys.getloadavg

gauche.sys.getrlimit

gauche.sys.lchown

gauche.sys.getpgid

gauche.sys.nanosleep

gauhce.sys.crypt

gauche.sys.symlink

gauche.sys.readlink

gauche.sys.select

gauche.sys.fcntl

gauche.sys.syslog

gauche.sys.setlogmask

gauche.sys.openpty

gauche.sys.forkpty

Those are defined based on the availability of these system features of the platform.

R7RS feature identifiers

r7rs

Indicates the implementation complies r7rs.

exact-closed

Exact arithmetic operations are closed; that is, dividing an exact number by a non-zero exact number always yields an exact number.

ieee-float

Using IEEE floating-point number internally. Full unicode support.

ratios

Rational number support

posix

windows

Either one is defined, according to the platform.

big-endian

little-endian

Either one is defined, according to the platform.

4.13 Modules

This section describes the semantics of Gauche modules and its API. See also Writing Gauche modules, for the conventions Gauche is using for its modules.

For R7RS programs, they are called “libraries” and have different syntax than Gauche modules. See section R7RS library form, for the details.

4.13.1 Module semantics

Module is an object that maps symbols onto bindings, and affects the resolution of global variable reference.

Unlike CommonLisp’s packages, which map names to symbols, in Gauche symbols are eq? in principle if two have the same name (except uninterened symbols; see section Symbols). However, Gauche’s symbol doesn’t have a ’value’ slot in it. From a given symbol, a module finds its binding that keeps a value. Different modules can associate different bindings to the same symbol, that yield different values.

;; Makes two modules A and B, and defines a global variable 'x' in them
(define-module A (define x 3))
(define-module B (define x 4))

;;  #<symbol 'x'> ---[module A]--> #<binding that has 3>
(with-module A x) ⇒ 3

;;  #<symbol 'x'> ---[module B]--> #<binding that has 4>
(with-module B x) ⇒ 4

A module can export a part or all of its bindings for other module to use. A module can import other modules, and their exported bindings become visible to the module. A module can import any number of modules.

(define-module A
  (export pi)
  (define pi 3.1416))

(define-module B
  (export e)
  (define e 2.71828))

(define-module C
  (import A B))

(select-module C)
(* pi e) ⇒ 8.539748448

A module can also be inherited, that is, you can extend the existing module by inheriting it and adding new bindings and exports. From the new module, all ancestor’s bindings (including non-exported bindings) are visible. (A new module inherits the gauche module by default, which is why the built-in procedures and syntax of gauche are available in the new module). From outside, the new module looks like having all exported bindings of the original module plus the newly defined and exported bindings.

;; Module A defines and exports deg->rad.
;; A binding of pi is not exported.
(define-module A
  (export deg->rad)
  (define pi 3.1416)   ;; not exported
  (define (deg->rad deg) (* deg (/ pi 180))))

;; Module Aprime defines and exports rad->deg.
;; The binding of pi is visible from inside Aprime.
(define-module Aprime
  (extend A)
  (export rad->deg)
  (define (rad->deg rad) (* rad (/ 180 pi))))

;; Module C imports Aprime.
(define-module C
  (import Aprime)
  ;; Here, both deg->rad and rad->deg are visible,
  ;; but pi is not visible.
  )

At any moment of the compilation, there is one "current module" available, and the global variable reference is looked for from the module. If there is a visible binding of the variable, the variable reference is compiled to the access of the binding. If the compiler can’t find a visible binding, it marks the variable reference with the current module, and delays the resolution of binding at the time the variable is actually used. That is, when the variable is referenced at run time, the binding is again looked for from the marked module (not the current module at the run time) and if found, the variable reference code is replaced for the the code to access the binding. If the variable reference is not found even at run time, an ’undefined variable’ error is signaled.

Once the appropriate binding is found for the global variable, the access to the binding is hard-wired in the compiled code and the global variable resolution will never take place again.

The definition special form such as define and define-syntax inserts the binding to the current module. Thus it may shadow the binding of imported or inherited modules.

The resolution of binding of a global variable happens like this. First, the current module is searched. Then, each imported module is taken in the reverse order of import, and searched, including each module’s ancestors. Note that import is not transitive; imported module list is not chased recursively. Finally, ancestors of the current module are searched in order.

This order is important when more than one modules defines the same name and your module imports both. Assuming your module don’t define that name, if you first import a module A then a module B, you’ll see B’s binding.

If you import A, then B, then A again, the last import takes precedence; that is, you’ll see A’s binding.

If two modules you want to use exports bindings of the same name and you want to access both, you can add prefix to either one (or both). See section Using modules, for the details.

4.13.2 Modules and libraries

Modules are run-time data structure; you can procedurally create modules with arbitrary names at run-time.

However, most libraries use modules to create their own namespace, so that they can control which bindings to be visible from library users. (This “library” is a general term, broader than R7RS “library”).

Usually a library is provided in the form of one or more Scheme source file(s), so it is convenient to have a convention to map module names to file names, and vice versa; then, you can load a library file and import its module by one action with use macro, for example.

For the time being, Gauche uses a simple rules for this mapping: Module names are organized hierarchically, using period ‘.’ for separator, e.g. gauche.mop.validator. If such a module is requested and doesn’t exist in the current running environment, Gauche maps the module name to a pathname by replacing periods to directory separator, i.e. gauche/mop/validator, and look for gauche/mop/validator.scm in the load paths.

Note that this is just a default behavior. Theoretically, one Scheme source file may contain multiple modules, or one module implementation may span to multiple files. In future, there may be some hook to customize this mapping for special cases. So, when you are writing routines that deal with modules and library files, do not apply the above default rule blindly. Gauche provides two procedures, module-name->path and path->module-name, to do mapping for you (see Module introspection, for details).

4.13.3 Defining and selecting modules

Special Form: define-module name body …

Name must be a symbol. If a module named name does not exist, create one. Then evaluates body sequentially in the module.

Special Form: select-module name

Makes a module named name as the current module. It is an error if no module named name exists.

If select-module is used in the Scheme file, its effect is limited inside the file, i.e. even if you load/require a file that uses select-module internally, the current module of requirer is not affected.

Special Form: with-module name body …

Evaluates body sequentially in the module named name. Returns the last result(s). If no module named name, an error is signaled.

Special Form: current-module

Evaluates to the current module in the compile context. Note that this is a special form, not a function. Module in Gauche is statically determined at compile time.

(define-module foo (export get-current-module) (define (get-current-module) (module-name (current-module)))) (define-module bar (import foo) (get-current-module)) ⇒ foo ; not bar

4.13.4 Using modules

Special Form: export spec …

[R7RS] Makes bindings specified by each spec available to modules that imports the current module.

Each spec can be either one of the following forms, where name and exported-name are symbols.

name

The binding with name is exported.

(rename name exported-name)

The binding with name is exported under an alias exported-name.

spec

Note: In Gauche, export is just a special form you can put in the middle of the program, whereas R7RS defines export as a library declaration, that can only appear immediately below define-library form. See section R7RS library form, for the details.

Special Form: export-all

Makes all bindings in the current module available to modules that imports it.

Special Form: import import-spec …

Makes all or some exported bindings in the module specified by import-spec available in the current module. The syntax of import-spec is as follows.

<import-spec> : <module-name> | (<module-name> <import-option> ...) <import-option> : :only (<symbol> ...) | :except (<symbol> ...) | :rename ((<symbol> <symbol>) ...) | :prefix <symbol> <module-name> : <symbol>

The module named by module-name should exist when the compiler sees this special form.

Imports are not transitive. The modules that module-names are importing are not automatically imported to the current module. This keeps modules’ modularity; a library module can import whatever modules it needs without worrying about polluting the namespace of the user of the module.

import-option can be used to change how the bindings are imported. With :only, only the bindings with the names listed in <symbol> … are imported. With :except, the exported bindings except the ones with the listed names are imported. With :rename, the binding of each name in the first of two-symbol list is renamed to the second of it. With :prefix, the exported bindings are visible with the names that are prefixed by the symbol to the original names. Without import options, all the exported bindings are imported without a prefix.

(define-module M (export x y) (define x 1) (define y 2) (define z 3)) (import M) x ⇒ 1 z ⇒ error. z is not exported from M (import (M :only (y))) x ⇒ error. x is not in :only list. (import (M :except (y))) y ⇒ error. y is excluded by :except. (import (M :prefix M:)) x ⇒ error M:x ⇒ 1 M:y ⇒ 2

If more than one import option are given, it is processed as the order of appearance. That is, if :prefix comes first, then :only or :except has to list the name with prefix.

Note: R7RS has import form, which has slightly differnent syntax and semantics. See section Three import forms, for the details.

Macro: use name :key only except rename prefix

A convenience macro that combines module imports and on-demand file loading. Basically, (use foo) is equivalent to the following two forms:

(require "foo") (import foo)

That is, it loads the library file named “foo” (if not yet loaded) which defines a module named foo in it, and then import the module foo into the current module.

The keyword argument only, except, and prefix are passed to import as the import options.

(use srfi-1 :only (iota) :prefix srfi-1:) (srfi-1:iota 3) ⇒ (0 1 2)

Although the files and modules are orthogonal concept, it is practically convenient to separate files by modules. Gauche doesn’t force you to do so, and you can always use require and import separately. However, all modules provided with Gauche are arranged so that they can be used by use macro.

If a module is too big to fit in one file, you can split them into several subfiles and one main file. The main file defines the module, and either loads, requires, or autoloads subfiles.

Actually, the file pathname of the given module name is obtained by the procedure module-name->path below. The default rule is to replace periods ‘.’ in the name for ‘/’; for example, (use foo.bar.baz) is expanded to:

(require "foo/bar/baz") (import foo.bar.baz)

This is not very Scheme-ish way, but nevertheless convenient. In future, there may be some mechanism to customize this mapping.

The file to be use’d must have explict module selection to have any toplevel definitions (usually via define-module/select-module pair or define-library). If you get an error saying “Attempted to create a binding in a sealed module: module: #<module gauche.require-base>”, that’s because the file lacks module selection. See section Require and provide, for further discussion.

4.13.5 Module inheritance

The export-import mechanism doesn’t work well in some cases, such as:

• You want to create a module that is mostly the same as the existing one, but adding or altering some definitions.
• You wrote a bunch of related modules that are often used together, and not want your users to repeat a bunch of ’use’ forms every time they use your module.

You can use module inheritance in these cases.

Macro: extend module-name …

Makes the current module inherit from named modules. The current inheritance information is altered by the inheritance information calculated from given modules.

A new module inherits from gauche module when created. If you put (extend scheme) in that module, for example, the module resets to inherit directly from scheme module that has only bindings defined in R5RS, hence, after the export form, you can’t use ’import’ or any other gauche-specific bindings in the module.

If a named module is not defined yet, extend tries to load it, using the same convention use macro does.

A module can inherit multiple modules, exactly the same way as a class can inherit from multiple classes. The resolution of order of inheritance needs to be explained a bit.

Each module has a module precedence list, which lists modules in the order of how they are searched. When the module inherits multiple modules, module precedence lists of inherited modules are merged into a single list, keeping the constraints that: (1) if a module A appears before module B in some module precedence list, A has to appear before B in the resulting module precedence list; and (2) if a module A appears before module B in extend form, A has to appear before B in the resulting module precedence list. If no precedence list can be constructed with these constraints, an error is signaled.

For example, suppose you wrote a library in modules mylib.base, mylib.util and mylib.system. You can bundle those modules into one module by creating a module mylib, as follows:

(define-module mylib
  (extend mylib.system mylib.util mylib.base))

The user of your module just says (use mylib) and all exported symbols from three submodules become available.

4.13.6 Module introspection

This subsection lists procedures that operates on modules at run-time. With these procedures you can introspect the modules, create new modules procedurally, or check the existence of certain modules/libraries, for example. However, don’t forget that modules are primarily compile-time structures. Tweaking modules at run-time is only for those who know what they are doing.

Builtin Class: <module>

A module class.

Function: module? obj

Returns true if obj is a module.

Function: find-module name

Returns a module object whose name is a symbol name. If the named module doesn’t exist, #f is returned.

Function: make-module name :key if-exists

Creates and returns a module that has symbol name. If the named module already exists, the behavior is specified by if-exists keyword argument. If it is :error (default), an error is signaled. If it is #f, #f is returned.

Note that creating modules on-the-fly isn’t usually necessary for ordinal scripts, since to execute already written program requires modules to be specified by name, i.e. syntax define-module, import, extend, with-module all take module names, not module objects. It is because module are inherently compile-time structures. However, there are some cases that dynamically created modules are useful, especially the program itself is dynamically created. You can pass a module to eval to compile and evaluate such dynamically created programs in it (see section Eval and repl).

You can also pass #f to name to create anonymous module. Anonymous modules can’t be looked up by find-module, nor can be imported or inherited (since import and extend take module names, not modules). It is useful when you want to have a temporary, segregated namespace dynamically—for example, you can create an anonymous module to evaluate code fragments sent from other program, and discards the module when the connection is terminated. Anonymous modules are not registered in the system dictionary and are garbage collected when nobody keeps reference to it.

R7RS provides another way to create a transient module with environment procedure. see section scheme.eval - R7RS eval for the details.

Function: all-modules

Returns a list of all named modules. Anonymous modules are not included.

Function: module-name module

Function: module-imports module

Function: module-exports module

Function: module-table module

Accessors of a module object. Returns the name of the module (a symbol), list of imported modules, list of exported symbols, and a hash table that maps symbols to bindings, of the module are returned, respectively.

If the module exports all symbols, module-exports returns #t.

It is an error to pass a non-module object.

Function: module-parents module

Function: module-precedence-list module

Returns the information of module inheritance. Module-parents returns the modules module directly inherits from. Module-precedence-list returns the module precedence list of module (see section Module inheritance).

Function: global-variable-bound? module symbol

Returns true if symbol’s global binding is visible from module. Module must be a module object or a symbol name of an existing module.

Note: there used to be the symbol-bound? procedure to check whether a global variable is bound. It is deprecated and the new code should use global-variable-bound? instead. The reason of change is that because of the name symbol-bound? and the fact that it assumes current-module by default, it gives an illusion as if a global bound value is somewhat ’stored’ in a symbol itself (like CommonLisp’s model). It caused a lot of confusion when the current module differs between compile-time and runtime. The new name and API made it clear that you are querying module’s property.

Function: global-variable-ref module symbol :optional default

Returns a value globally bound to the symbol visible from module. Module must be a module object or a symbol name of an existing module. If there’s no visible global binding from module for symbol, an error is signaled, unless the default argument is provided, in which case it is returned instead.

Function: module-name->path symbol

Converts a module name symbol to a fragment of pathname string (which you use for require and provide).

Function: path->module-name string

Reverse function of module-name->path.

If you want to find out specific libraries and/or modules are installed in the system and available from the program, see Operations on libraries.

4.13.7 Predefined modules

Several modules are predefined in Gauche.

Builtin Module: null

This module corresponds to the null environment referred in R5RS. This module contains only syntactic bindings of R5RS syntax.

Builtin Module: scheme

This module contains all the binding of null module, and the binding of procedures defined in R5RS.

Note that if you change the current module to null or scheme by select-module, there will be no way to switch back to other modules, since module-related syntaxes and procedures are not visible from null and scheme modules.

Builtin Module: gauche

This module contains all the bindings of scheme module, plus Gauche specific built-in procedures.

Builtin Module: user

This module is the default module the user code is compiled. all the bindings of gauche module is imported.

Builtin Module: gauche.keyword

Builtin Module: keyword

When Gauche is running with GAUCHE_KEYWORD_IS_SYMBOL mode keywords (symbols beginning with :) is automatically bound to itself in these modules. (see section Keywords, for the details.)

The keyword module doesn’t export those bindings, while gauche.keyword does. The former is intended to be used internally; the programmer need to know the latter.

If you use the default module inheritance, you don’t need to use this module, since the keyword module is included in the inheritance chain. If you don’t inherit gauche module, however, importing the gauche.keyword module gives you access to the keywords without quotes. For example, R7RS programs and libraries would require either (import (gauche keyword)) or (import (gauche base)) (the latter inherits gauche.keyword), or you have to quote all keywords.

The followig R7RS program imports gauche.base; it makes gauche built-in identifiers, and all self-bound keywords, available:

;; R7RS program (import (scheme base) (gauche base)) ; import gauche builtins and keywords ;; You can use :directory without quote, for it is bound to itself. (sys-exec "ls" '("ls" "-l") :directory "/")

If you use more sophisitcated import tricks, however, keep in mind that keywords are just imported symbols if GAUCHE_KEYWORD_IS_SYMBOL is set. The following code imports Gauche builtin identifiers with prefix gauche/. That causes keywords, imported via inheritance, also get the same prefix; if you don’t want to bother adding prefix to all keywords or quote them, import gauche.keyword separately.

;; R7RS program (import (scheme base) (prefix (gauche base) gauche/) ; use gauche builting with gauche/ prefix (gauche keyword)) ; imports keywords ;; Without importing gauche.keyword, ;; you need to write ':directory (gauche/sys-exec "ls" '("ls" "-l") :directory "/")

5. Macros

Macro of Lisp-family language is very different feature from ones of other languages, such as C preprocessor macros. It allows you to extend the original language syntax. You can use macros to change Gauche syntax so that you can run a Scheme program written to other Scheme implementations, and you can even design your own mini-language to solve your problem easily.

Gauche supports hygienic macros, which allows to write safe macros by avoiding name collisions. If you know traditional Lisp macros but new to hygienic macros, they might seem confusing at first. We have an introductory section (Why hygienic?) for those who are not familiar with hygienic macros; if you know what they are, you can skip the section.

5.1 Why hygienic?

Lisp macro is a programmatic transformation of source code. A macro transformer is a procedure that takes a subtree of source code, and returns a reconstructed tree of source code.

The traditional Lisp macros take the input source code as an S-expression, and returns the output as another S-expression. Gauche supports that type of macro, too, with define-macro form. Here’s the simple definition of when with the traditional macro.

(define-macro (when test . body)
  `(if ,test (begin ,@body)))

For example, if the macro is used as (when (zero? x) (print "zero") 'zero), the above macro transformer rewrites it to (if (zero? x) (begin (print "zero") 'zero)). So far, so good.

But what if the when macro is used in an environment where the names begin or if is bound to nonstandard values?

(let ([begin list])
  (when (zero? x) (print "zero") 'zero))

The expanded result would be as follows:

(let ([begin list])
  (if (zero? x) (begin (print "zero") 'zero)))

This obviously won’t work as the macro writer intended, since begin in the expanded code refers to the locally bound name.

This is a form of variable capture. Note that, when Lisp people talk about variable capture of macros, it often means another form of capture, where the temporary variables inserted by a macro would unintentionally capture the variables passed to the macro. That kind of variable capture can be avoided easily by naming the temporary variables something that never conflict, using gensym.

On the other hand, the kind of variable capture in the above example can’t be avoided by gensym, because (let ([begin list]) ...) part isn’t under macro writer’s control. As a macro writer, you can do nothing to prevent the conflict, just hoping the macro user won’t do such a thing. Sure, rebinding begin is a crazy idea that nobody perhaps wants to do, but it can happen on any global variable, even the ones you define for your library.

Various Lisp dialects have tried to address this issue in different ways. Common Lisp somewhat relies on the common sense of the programmer—you can use separate packages to reduce the chance of accidental conflict but can’t prevent the user from binding the name in the same package. (The Common Lisp spec says it is undefined if you locally rebind names of CL standard symbols; but it doesn’t prevent you from locally rebinding symbols that are provided by user libraries.)

Clojure introduced a way to directly refer to the toplevel variables by a namespace prefix, so it can bypass whatever local bindings of the same name (also, it has a sophisticated quasiquote form that automatically renames free variables to refer to the toplevel ones). It works, as far as there are no local macros. With local macros, you need a way to distinguish different local bindings of the same name, as we see in the later examples. Clojure’s way can only distinguish between local and toplevel bindings. It’s ok for Clojure which doesn’t have local macros, but in Scheme, we prefer uniform and orthogonal axioms—if functions can be defined locally with lexical scope, why not macros?

Let’s look at the local macro with lexical scope. For the sake of explanation, suppose we have hypothetical local macro binding form, let-macro, that binds a local identifiers to a macro transformer. (We don’t actually have let-macro; what we have is let-syntax and letrec-syntax, which have slightly different way to call macro transformers. But here let-macro may be easier to understand as it is similar to define-macro.)

(let ([f (^x (* x x))])
  (let-macro ([m (^[expr1 expr2] `(+ (f ,expr1) (f ,expr2)))])
    (let ([f (^x (+ x x))])
      (m 3 4))))    ; [1]

The local identifier m is bound to a macro transformer that takes two expressions, and returns an S-expression. So, the (m 3 4) form [1] would be expanded into (+ (f 3) (f 4)). Let’s rewrite the above expression with the expanded form. (After expansion, we no longer need let-macro form, so we don’t include it.)

(let ([f (^x (* x x))])
  (let ([f (^x (+ x x))])
    (+ (f 3) (f 4))))  ; [2]

Now, the question. Which binding f in the expanded form [2] should refer? If we literally interpret the expansion, it would refer to the inner binding (^x (+ x x)). However, following the Scheme’s scoping principle, the outer code should be fully understood regardless of innter code:

(let ([f (^x (* x x))])
  (let-macro ([m (^[expr1 expr2] `(+ (f ,expr1) (f ,expr2)))])
    ;; The code here isn't expected to accidentally alter
    ;; the behavior defined outside.
    ))

The macro writer may not know the inner let shadows the binding of f (the inner forms may be included, or may be changed by other person who didn’t fully realize the macro expansion needs to refer outer f).

To ensure the local macro to work regardless of what’s placed inside let-macro, we need a sure way to refer the outer f in the result of macro expansion. The basic idea is to “mark” the names inserted by the macro transformer m—which are f and +—so that we can distinguish two f’s.

For example, if we would rewrite the entire form and renames corresponding local identifiers as follows:

(let ([f_1 (^x (* x x))])
  (let-macro ([m (^[expr1 expr2] `(+ (f_1 ,expr1) (f_1 ,expr2)))])
    (let ([f_2 (^x (+ x x))])
      (m 3 4))))

Then the naive expansion would correctly preserve scopes; that is, expansion of m refers f_1, which wouldn’t conflict with inner name f_2:

(let ([f_1 (^x (* x x))])
  (let ([f_2 (^x (+ x x))])
    (+ (f_1 3) (f_1 4))))

(You may notice that this is similar to lambda calculus treating lexical bindings with higher order functions.)

The above example deal with avoiding f referred from the macro definition (which is, in fact, f_1) from being shadowed by the binding of f at the macro use (which is f_2).

Another type of variable capture (the one most often talked about, and can be avoided by gensym) is that a variable in macro use site is shadowed by the binding introduced by a macro definition. We can apply the same renaming strategy to avoid that type of capture, too. Let’s see the following example:

(let ([f (^x (* x x))])
  (let-macro ([m (^[expr1] `(let ([f (^x (+ x x))]) (f ,expr1)))])
    (m (f 3))))

The local macro inserts binding of f into the expansion. The macro use (m (f 3)) also contains a reference to f, which should be the outer f, since the macro use is lexically outside of the let inserted by the macro.

We could rename f’s according to its lexical scope:

(let ([f_1 (^x (* x x))])
  (let-macro ([m (^[expr1] `(let ([f_2 (^x (+ x x))]) (f_2 ,expr1)))])
    (m (f_1 3))))

Then expansion unambiguously distinguish two f’s.

(let ([f_1 (^x (* x x))])
  (let ([f_2 (^x (+ x x))])
    (f_2 (f_1 3))))

This is, in principle, what hygienic macro is about (well, almost). In reality, we don’t rename everything in batch. One caveat is in the latter example—we statically renamed f to f_2, but it is possible that the macro recursively calls itself, and we have to distinguish f’s introduced in every individual expansion of m. So macro expansion and renaming should work together.

There are multiple strategies to implement it, and the Scheme standard doesn’t want to bind implementations to single specific strategy. The standard only states the properties the macro system should satisfy, in two concise sentences:

If a macro transformer inserts a binding for an identifier (variable or keyword), the identifier will in effect be renamed throughout its scope to avoid conflicts with other identifiers.

If a macro transformer inserts a free reference to an identifier, the reference refers to the binding that was visible where the transformer was specified, regardless of any local bindings that surround the use of the macro.

Just from reading this, it may not be obvious how to realize those properties, and the existing hygienic macro mechanisms (e.g. syntax-rules) hide the “how” part. That’s probably one of the reason some people feel hygienic macros are difficult to grasp. It’s like continuations—its description is concise but at first you have no idea how it works; then, through experience, you become familiarized yourself to it, and then you reread the original description and understand it says exactly what it is.

This introduction may not answer how the hygienic macro realizes those properties, but I hope it showed what it does and why it is needed. In the following chapters we introduce a couple of hygienic macro mechanisms Gauche supports, with examples, so that you can familiarize yourself to the concept.

5.2 Hygienic macros

Macro bindings

The following forms establish bindings of name and a macro transformer created by transformer-spec. The binding introduced by these forms shadows a binding of name established in outer scope, if there’s any.

For toplevel bindings, it will shadow bindings of name imported or inherited from other modules (see section Modules). (Note: This toplevel shadowing behavior is Gauche’s extension; in R7RS, you shouldn’t redefine imported bindings, so the portable code should avoid it.)

The effect is undefined if you bind the same name more than once in the same scope.

The transformer-spec can be either one of syntax-rules form, er-macro-transformer form, or another macro keyword or syntactic keyword. We’ll explain them later.

Special Form: define-syntax name transformer-spec

[R7RS] If this form appears in toplevel, it binds toplevel name to a macro transformer defined by transformer-spec.

If this form appears in the declaration part of body of lambda (internal define-syntax), let and other similar forms, it binds name locally within that body. Internal define-syntaxes are converted to letrec-syntax, just like internal defines are converted to letrec*.

Special Form: let-syntax ((name transformer-spec) …) body

Special Form: letrec-syntax ((name transformer-spec) …) body

[R7RS] Defines local macros. Each name is bound to a macro transformer as specified by the corresponding transformer-spec, then body is expanded. With let-syntax, transformer-spec is evaluated with the scope surrounding let-syntax, while with letrec-syntax the bindings of names are included in the scope where transformer-spec is evaluated. Thus letrec-syntax allows mutually recursive macros.

Transformer specs

The trasformer-spec is a special expression that evaluates to a macro transformer. It is evaluated in a different phase than the other expressions, since macro transformers must be executed during compiling. So there are some restrictions.

At this moment, only one of the following expressions are allowed:

1. A syntax-rules form. This is called “high-level” macro, for it uses pattern matching entirely, which is basically a different declarative language from Scheme, thus putting the complication of the phasing and hygiene issues completely under the hood. Some kind of macros are easier to write in syntax-rules. See section Syntax-rules pattern langauge, for further description.
2. An er-macro-transformer form. This employs explicit-renaming (ER) macro, where you can use arbitrary Scheme code to transform the program, with required renaming to keep hygienity. The legacy Lisp macro can also be written with ER macro if you don’t use renaming. See section Explicit-renaming macro transformer, for the details.
3. Macro or syntax keyword. This is Gauche’s extension, and can be used to define alias of existing macro or syntax keyword.

   (define-syntax si if) (define écrivez write) (si (< 2 3) (écrivez "oui"))

5.2.1 Syntax-rules pattern langauge

Special Form: syntax-rules (literal …) clause1 clause2 …

Special Form: syntax-rules ellipsis (literal …) clause1 clause2 …

[R7RS] This specifies a macro transformer by pattern matching.

5.2.2 Explicit-renaming macro transformer

Special Form: er-macro-transformer procedure-expr

Creates a macro transformer from the given procedure-expr. The created macro transformer has to be bound to the syntactic keyword by define-syntax, let-syntax or letrec-syntax. Other use of macro transformers is undefined.

The procedure-expr must evaluate to a procedure that takes three arguments; form, rename and id=?.

The form argument receives the S-expression of the macro call. The procedure-expr must return an S-expression as the result of macro expansion. This part is pretty much like the traditional lisp macro. In fact, if you ignore rename and id=?, the semantics is the same as the traditional (unhygienic) macro. See the following example (Note the use of match; it is a good tool to decompose macro input):

(use util.match) ;; Unhygienic 'when-not' macro (define-syntax when-not (er-macro-transformer (^[form rename id=?] (match form [(_ test expr1 expr ...) `(if (not ,test) (begin ,expr1 ,@expr))] [_ (error "malformed when-not:" form)])))) (macroexpand '(when-not (foo) (print "a") 'boo)) ⇒ (if (not (foo)) (begin (print "a") 'boo))

This is ok as long as you know you don’t need hygiene—e.g. when you only use this macro locally in your code, knowning all the macro call site won’t contain name conflicts. However, if you provide your when-not macro for general use, you have to protect namespace pollution around the macro use. For example, you want to make sure your macro work even if it is used as follows:

(let ((not values)) (when-not #t (print "This shouldn't be printed")))

The rename argument passed to procedure-expr is a procedure that takes a symbol (or, to be precise, a symbol or an identifier) and effectively renames it to a unique identifier that keeps identity within the macro definition environment and won’t be affected in the macro use environment.

As a rule of thumb, you have to pass all new identifiers you insert into macro output to the rename procedure to keep hygiene. In our when-not macro, we insert if, not and begin into the macro output, so our hygienic macro would look like this:

(define-syntax when-not (er-macro-transformer (^[form rename id=?] (match form [(_ test expr1 expr ...) `(,(rename 'if) (,(rename 'not) ,test) (,(rename 'begin) ,expr1 ,@expr))] [_ (error "malformed when-not:" form)]))))

This is cumbersome and makes it hard to read the macro, so Gauche provides an auxiliary macro quasirename, which works like quasiquote but renaming identifiers in the form. See the entry of quasirename below for the details. You can write the hygienic when-not as follows:

(define-syntax when-not (er-macro-transformer (^[form rename id=?] (match form [(_ test expr1 expr ...) (quasirename rename (if (not ,test) (begin ,expr1 ,@expr)))] [_ (error "malformed when-not:" form)]))))

You can intentionally break hyginene by inserting a symbol without renaming. The following code implements anaphoric when, meaning the result of the test expression is available in the expr1 exprs … with the name it. Since the binding of the identifier it does not exist in the macro use site, but rather injected into the macro use site by the macro expander, it is unhygienic.

(define-syntax awhen (er-macro-transformer (^[form rename id=?] (match form [(_ test expr1 expr ...) `(,(rename 'let1) it ,test ; 'it' is not renamed (,(rename 'begin) ,expr1 ,@expr))]))))

If you use quasirename, you can write ,'it to prevent it from being renamed:

(define-syntax awhen (er-macro-transformer (^[form rename id=?] (match form [(_ test expr1 expr ...) (quasirename rename (let1 ,'it ,test (begin ,expr1 ,@expr)))]))))

Here’s an example:

(awhen (find odd? '(0 2 8 7 4)) (print "Found odd number:" it)) ⇒ prints Found odd number:7

Finally, the id=? argument to the procedure-expr is a procedure that takes two arguments, and returns #t iff both are identifiers and either both are referring to the same binding or both are free. It can be used to compare literal syntactic keyword (e.g. else in cond and case forms) hygienically.

The following if=> macro behaves like if, except that it accepts (if=> test => procedure) syntax, in which procedure is called with the value of test if it is not false. The symbol => must match hygienically, that is, it must refer to the same binding as in the macro definition.

(define-syntax if=> (er-macro-transformer (^[form rename id=?] (match form [(_ test a b) (if (id=? (rename '=>) a) (quasirename rename (let ((t ,test)) (if t (,b t)))) (quasirename rename (if ,test ,a ,b)))]))))

The call (rename '=>) returns an identifier that captures the binding of => in the macro definition, and using id=? with the thing passed to the macro argument checks if both refer to the same binding.

(if=> 3 => list) ⇒ (3) (if=> #f => list) ⇒ #<undef> ;; If the second argument isn't =>, if=> behaves like ordinary if: (if=> #t 1 2) ⇒ 1 ;; The binding of => in macro use environment differs from ;; the macro definition environment, so this if=> behaves like ;; ordinary if, instead of recognizing literal =>. (let ((=> 'oof)) (if=> 3 => list)) ⇒ oof

Macro: quasirename renamer form

It works like quasiquote, except that the symbols and identifiers that appear in the “literal” portion of form (i.e. outside of unquote and unquote-splicing) are replaced by the result of applying rename on themselves.

For example, a form:

(quasirename r (a ,b c "d"))

would be equivalent to write:

(list (r 'a) b (r 'c) "d")

This is not specifically tied to macros; the renamer can be any procedure that takes one symbol or identifier argument:

(quasirename (^[x] (symbol-append 'x: x)) (+ a ,(+ 1 2) 5)) ⇒ (x:+ x:a 3 5)

However, it comes pretty handy to construct the result form in ER macros. Compare the following two:

(use util.match) ;; using quasirename (define-syntax swap (er-macro-transformer (^[f r c] (match f [(_ a b) (quasirename r (let ((tmp ,a)) (set! ,a ,b) (set! ,b tmp)))])))) ;; not using quasirename (define-syntax swap (er-macro-transformer (^[f r c] (match f [(_ a b) `((r'let) (((r'tmp) ,a)) ((r'set!) ,a ,b) ((r'set!) ,b (r'tmp)))]))))

5.3 Traditional macros

Special Form: define-macro name procedure

Special Form: define-macro (name . formals) body …

Defines name to be a global macro whose transformer is procedure. The second form is a shorthand notation of the following form:

(define-macro name (lambda formals body …))

When a form (name arg …) is seen by the compiler, it calls procedure with arg …. When procedure returns, the compiler inserts the returned form in place of the original form, and compile it again.

5.4 Macro expansion

Function: macroexpand form

Function: macroexpand-1 form

If form is a list and its first element is a variable globally bound to a macro, macroexpand-1 invokes its macro transformer and returns the expanded form. Otherwise, returns form as is.

macroexpand repeats macroexpand-1 until the form can’t be expanded.

These procedures can be used to expand globally defined macros.

Function: macroexpand-all form

Fully expand macros inside form. The result only contains function calls and Gauche’s built-in syntax. The form is assumed to be a toplevel form within the current module. (See section Module semantics, for the concept of the current module. It can be tricky, for sometimes the current module differ between compile-time and run-time.)

Any local variables introduced in form is renamed to avoid collision. Since each local variable has unique name, all let forms become letrec forms (we can safely replace let with letrec if no bindings introduced by let shadows outer bindings.)

NB: If a macro in form inserts a reference to a global variable which belongs to other module, the information is lost in the current implementation. There are a few ways to address this issue; we may leave such reference as an identifier object, convert it to with-module form, or introduce a special syntax to represent such case. It’s undecided currently, so do not rely too much on the current behavior. For the time being, it’s best to use this feature only for interactive macro testing.

(macroexpand-all '(letrec-syntax [(when-not (syntax-rules () [(_ test . body) (if test #f (begin . body))]))] (let ([if list]) (define x (expt foo)) (let1 x 3 (when-not (bar) (if x)))))) ⇒ (letrec ((if.0 list)) (letrec ((x.1 (expt foo))) (letrec ((x.2 '3)) (if (bar) '#f (if.0 x.2)))))

Special Form: %macroexpand form

Special Form: %macroexpand-1 form

5.5 Macro utilities

Macro: syntax-error msg arg …

Macro: syntax-errorf fmt arg …

Signal an error. They are same as error and errorf (see section Signaling exceptions), except that the error is signaled at macro-expansion time (i.e. compile time) rather than run time.

They are useful to tell the user the wrong usage of macro in the comprehensive way, instead of the cryptic error from the macro transformer. Because of the purpose, arg … are first passed to unwrap-syntax described below, to strip off the internal syntactic binding informations.

(define-syntax my-macro (syntax-rules () ((_ a b) (foo2 a b)) ((_ a b c) (foo3 a b c)) ((_ . ?) (syntax-error "malformed my-macro" (my-macro . ?))))) (my-macro 1 2 3 4) ⇒ error: "malformed my-macro: (mymacro 1 2 3 4)"

Function: unwrap-syntax form

Removes internal syntactic information from form. In order to implement a hygienic macro, macro transformer replaces symbols in the macro form for identifiers, which captures the syntactic environment where they are defined. Although it is necessary information for the compiler, it is rather confusing for users if it appears in the messages. This function replaces occurrences of identifiers in form to the original symbols.

6. Core library

6.1 Types and classes

Scheme is a dynamically and strongly typed language. That is, every value knows its type at run-time, and the type determines what kind of operations can be applied on the value.

In Gauche, classes are used to describe types. A class is also an object you can handle at runtime. You can also create a new class in order to have objects with distinct types.

Since R6RS, Scheme got a standard way to define a new type, through define-record-type. You can use record types in Gauche as well, via gauche.record module. See section gauche.record - Record types. Internally a record type is implemented as a class.

In this section we introduce the most basic interface to the Gauche’s type system. See section Object system, for the details of how to define your own classes and creates values (instances).

Predefined classes are bound to a global variable; Gauche’s convention is to name the variable that holds a class with brackets < and >, e.g. <string>. (It’s nothing syntactically special with these brackets; they’re valid characters to consist of variable names). We’ll introduce classes for each built-in type as we go through this chapter. Here are a few basic classes to start with:

Builtin Class: <top>

This class represents the supertype of all the types in Gauche. That is, for any class X, (subtype? X <top>) is #t, and for any object x, (is-a? x <top>) is #t.

Builtin Class: <bottom>

This class represents the subtype of all the types in Gauche. For any class X, (subtype? <bottom> X) is #t, and for any object x, (is-a? x <bottom>) is #f.

There’s no instance of <bottom>.

Note: Although <bottom> is subtype of other types, the class precedence list (CPL) of <bottom> only contains <bottom> and <top>. It’s because it isn’t always possible to calculate a linear list of all the types. Even if it is possible, it would be expensive to check and update the CPL of <bottom> every time a new class is defined or an existing class is redefined. Procedures subtype? and is-a? treat <bottom> specially.

One of use case of <bottom> is applicable? procedure. See section Procedure class and applicability.

Builtin Class: <object>

This class represents a supertype of all user-defined classes.

Function: class-of obj

Returns a class metaobject of obj.

(class-of 3) ⇒ #<class <integer>> (class-of "foo") ⇒ #<class <string>> (class-of <integer>) ⇒ #<class <class>>

Note: In Gauche, you can redefine existing user-defined classes. If the new definition has different configuration of the instance, class-of on existing instance triggers instance updates; see section Class redefinition for the details. Using current-class-of suppresses instance updates (see section Accessing instance).

Function: is-a? obj class

Returns true if obj is an instance of class or an instance of descendants of class.

(is-a? 3 <integer>) ⇒ #t (is-a? 3 <real>) ⇒ #t (is-a? 5+3i <real>) ⇒ #f (is-a? :foo <symbol>) ⇒ #f

Note: If obj’s class has been redefined, is-a? also triggers instance update. See Class redefinition for the details.

Function: subtype? sub super

Returns #t if a class sub is a subclass of a class super (includes the case that sub is super). Otherwise, returns #f.

(The name subtype? is taken from Common Lisp’s procedure subtypep.)

6.2 Equality and comparison

Comparing two objects seems trivial, but if you look into deeper, there are lots of subtleties hidden in the corners. What should it mean if two procedures are equal to each other? How to order two complex numbers? It all depends on your purpose; there’s no single generic answer. So Scheme (and Gauche) provides several options, as well as the way to make your own.

6.2.1 Equality

Scheme has three different general equality test predicates. Other than these, some types have their own comparison predicates.

Function: eq? obj1 obj2

[R7RS] This is the fastest and finest predicate. Returns #t if obj1 and obj2 are identical objects—that is, if they represents the same object on memory or in a register. Notably, you can compare two symbols with eq? to check if they are the same or not. You can think eq? as a pointer comparison for any heap-allocated objects.

Booleans can be compared with eq?, but you can’t compare characters and numbers reliably—objects with the same numerical value may or may not eq? to each other. If you identity comparison needs to include those objects, use eqv? below.

(eq? #t #t) ⇒ #t (eq? #t #f) ⇒ #f (eq? 'a 'a) ⇒ #t (eq? 'a 'b) ⇒ #f (eq? (list 'a) (list 'a)) ⇒ #f (let ((x (list 'a))) (eq? x x)) ⇒ #t

Function: eqv? obj1 obj2

[R7RS] When obj1 and obj2 are both exact or both inexact numbers (except NaN), eqv? returns #t iff (= obj1 obj2) is true. When obj1 and obj2 are both characters, eqv? returns #t iff (char=? obj1 obj2) is true. Otherwise, eqv? is the same as eq? on Gauche.

(eqv? #\a #\a) ⇒ #t (eqv? #\a #\b) ⇒ #f (eqv? 1.0 1.0) ⇒ #t (eqv? 1 1) ⇒ #t (eqv? 1 1.0) ⇒ #f (eqv? (list 'a) (list 'a)) ⇒ #f (let ((x (list 'a))) (eqv? x x)) ⇒ #t

Note that comparison of NaNs has some peculiarity. Any numeric comparison fails if there’s at least one NaN in its argument. Therefore, (= +nan.0 +nan.0) is always #f. However, Gauche may return #t for (eq? +nan.0 +nan.0) or (eqv? +nan.0 +nan.0).

Function: equal? obj1 obj2

[R7RS+] If obj1 and obj2 are both aggregate types, equal? compares its elements recursively. Otherwise, equal? behaves the same as eqv?.

If obj1 and obj2 are not eqv? to each other, not of builtin types, and the class of both objects are the same, equal? calls the generic function object-equal?. By defining the method, users can extend the behavior of equal? for user-defined classes.

(equal? (list 1 2) (list 1 2)) ⇒ #t (equal? "abc" "abc") ⇒ #t (equal? 100 100) ⇒ #t (equal? 100 100.0) ⇒ #f

Note: This procedure correctly handles the case when both obj1 and obj2 have cycles through pairs and vectors, as required by R6RS and R7RS. However, if the cycle involves user-defined classes, equal? may fail to terminate.

Generic Function: object-equal? obj1 obj2

This generic function is called when equal? is called on the objects it doesn’t know about. You can define this method on your class so that equal? can check equivalence. This method is supposed to return #t if obj1 is equal to obj2, #f otherwise. If you want to check equivalence of elements recursively, do not call object-equal? directly; call equal? on each element.

(define-class <foo> () ((x :init-keyword :x) (y :init-keyword :y))) (define-method object-equal? ((a <foo>) (b <foo>)) (and (equal? (slot-ref a 'x) (slot-ref b 'x)) (equal? (slot-ref a 'y) (slot-ref b 'y)))) (equal? (make <foo> :x 1 :y (list 'a 'b)) (make <foo> :x 1 :y (list 'a 'b))) ⇒ #t (equal? (make <foo> :x 1 :y (make <foo> :x 3 :y 4)) (make <foo> :x 1 :y (make <foo> :x 3 :y 4))) ⇒ #t

Method: object-equal? (obj1 <top>) (obj2 <top>)

This method catches equal? between two objects of a user-defined classe, in case the user doesn’t define a specialized method for the class.

When called, it scans the registered default comparators that can handle both obj1 and obj2, and if it finds one, use the comparator’s equality predicate to see if two arguments are equal to each other. When no matching comparators are found, it just returns #f. See section Predefined comparators, about the default comparators: Look for the entries of default-comparator and comparator-register-default!.

Note: If you define object-equal? with exactly the same specializers of this method, you’ll replace it and that breaks default-comparator operation. Future versions of Gauche will prohibit such redefinition. For now, be careful not to redefine it accidentally.

Sometimes you want to test if two aggregate structures are topologically equal, i.e., if one has a shared substructure, the other has a shared substructure in the same way. Equal? can’t handle it; module util.isomorph provides a procedure isomorphic? which does the job (see section util.isomorph - Determine isomorphism).

6.2.2 Comparison

Equality only concern about whether two objects are equivalent or not. However, sometimes we want to see the order among objects. Again, there’s no single “universal order”. It doesn’t make mathematical sense to ask if one complex number is greater than another, but having some artificial order is useful when you want a consistent result of sorting a list of objects including numbers.

Function: compare obj1 obj2

A general comparison procedure. Returns -1 if obj1 is less than obj2, 0 if obj1 is equal to obj2, and 1 if obj1 is greater than obj2.

If obj1 and obj2 are incomparable, an error is signalled. However, compare defines total order between most Scheme objects, so that you can use it on wide variety of objects. The definition is upper-compatible to the order defined in srfi-114.

Some built-in types are handled by this procedure reflecting “natural” order of comparison if any (e.g. real numbers are compared by numeric values, characters are compared by char< etc.) For convenience, it also defines superficial order between objects that doesn’t have natural order; complex numbers are ordered first by their real part, then their imaginary part, for example. That is, 1+i comes before 2-i, which comes before 2, which comes before 2+i.

Boolean false comes before boolean true.

Lists are ordered by dictionary order: Take the common prefix. If either one is () and the other is not, () comes first. If both tails are not empty, compare the heads of the tails. (This makes empty list the “smallest” of all lists).

Vectors (including uniform vectors) are compared first by their lengths, and if they are the same, elements are compared from left to right. Note that it’s different from lists and strings.

(compare '(1 2 3) '(1 3)) ⇒ -1 ; (1 2 3) is smaller (compare '#(1 2 3) '#(1 3)) ⇒ 1 ; #(1 3) is smaller (compare "123" "13") ⇒ -1 ; "123" is smaller

If two objects are of subclasses of <object>, a generic function object-compare is called.

If two objects are of different types and at least one of them isn’t <object>, then they are ordered by their types. Srfi-114 defines the order of builtin types as follows:

1. Empty list.
2. Pairs.
3. Booleans.
4. Characters.
5. Strings.
6. Symbols.
7. Numbers.
8. Vectors.
9. Uniform vectors (u8 < s8 < u16 < s16 < u32 < s32 < u64 < s64 < f16 < f32 < f64)
10. All other objects.

Generic Function: object-compare obj1 obj2

Specializing this generic function extends compare procedure for user-defined classes.

This method must return either -1 (obj1 precedes obj2), 0 (obj1 equals to obj2), 1 (obj1 succeeds obj2), or #f (obj1 and obj2 cannot be ordered).

Method: object-compare (obj1 <top>) (obj2 <top>)

This method catches compare between two objects of a user-defined class, in case the user doesn’t define a specialized method for the class.

When called, it scans the registered default comparators that can handle both obj1 and obj2, and if it finds one, use the comparator’s compare procedure to determine the order of obj1 and obj2. When no matching comparators are found, it returns #f, meaning two objects can’t be ordered. See section Predefined comparators, about the default comparators: Look for the entries of default-comparator and comparator-register-default!.

Note: If you define object-compare with exactly the same specializers of this method, you’ll replace it and that breaks default-comparator operation. Future versions of Gauche will prohibit such redefinition. For now, be careful not to redefine it accidentally.

Function: eq-compare obj1 obj2

Returns -1 (less than), 0 (equal to) or 1 (greater than) according to a certain total ordering of obj1 and obj2. Both arguments can be any Scheme objects, and can be different type of objects. The following properties are guaranteed.

• (eq-compare x y) is 0 iff (eq? x y) is #t.
• The result is consistent within a single run of the process (but may differ between runs).

Other than these, no actual semantics are given to the ordering.

This procedure is useful when you need to order arbitrary Scheme objects, but you don’t care the actual order as far as it’s consistent.