In Scheme, procedures are fundamental blocks to build a program (see Making Procedures). A procedure represents a certain computation, possibly parameterized, and can be applied to the actual arguments to execute the computation. Scheme also provides the means to extract the continuation of the current computation and wraps it in a procedure (see Continuations).
Gauche extends the concept of procedure application, allowing
you to apply any object as if it’s a procedure;
for example, you can set up Gauche to
("abc" 2) can be a valid application syntax.
See Applicable objects, for the details.
|• Procedure class and applicability:|
|• Universal accessor:|
|• Optional argument parsing:|
|• Procedure arity:|
|• Applicable objects:|
|• Multiple values:|
|• Folding generated values:|
Represents a procedure. Ordinary Scheme procedures created by
is an instance of this class, as well as built-in primitive procedures
written in C. Note that, in Gauche, other type of objects can behave
as a procedure; so checking whether an object is a procedure or not doesn’t
mean much unless you want to mess around with Gauche internals.
#t if obj is inherently applicable
#f otherwise. By inherently applicable
we mean Gauche unconditionally understands that obj can be called
as a procedure; an instance of
<procedure> is so,
as well as generic functions (
<generic>) and methods (
See Generic function and method, for the details.
Since you can make any type of objects applicable at any time
(see Applicable objects), the fact that
#f doesn’t mean that the object cannot be applied.
To check if an object can be applied or not, use
Calls a procedure proc with a list of arguments,
(arg1 … . args).
The last argument args must be a proper list.
Returns (a) value(s) proc returns.
(apply list 'a 'b '(c d e)) ⇒ (a b c d e) (apply + 1 2 '(3 4 5)) ⇒ 15
Checks if obj can be called with the types of arguments
listed in class …. That is,
(applicable? foo <string> <integer>) returns
then you can call
(foo "x" -2), for example.
(It doesn’t mean you won’t get an error;
foo may be accept
only nonnegative integers, which you cannot tell from the result of
applicable?. But if
Gauche won’t complain “foo is not applicable” when you call
This procedure takes applicable objects into account. So, for example,
(applicable? #/a/ <string>) returns
#t, for the regular
expressions are applicable to a string (see Regular expressions).
For generic functions,
#t if it has
at least one method such that each of its specifiers is a superclass
of the corresponding class argument given to
(define-method foo ((x <sequence>) (y <integer>)) #f) (applicable? foo <sequence> <integer>) ⇒ #t (applicable? foo <string> <integer>) ⇒ #t (applicable? foo <hash-table> <integer>) ⇒ #f (applicable? foo <string> <real>) ⇒ #f
The second example returns
a subclass of
the third example returns
isn’t a subclass of
<sequence>. The fourth example
<real> isn’t a subclass of
Traditional Scheme procedures (such as ones created by
only cares the number of arguments but not their types; it accepts
any type as far as the number of arguments matches. To check such
a condition, pass
<top> as the argument class. (
a superclass of all classes.)
(applicable? cons <top> <top>) ⇒ #t
If you want to check an object is applicable to a certain
number of some class of arguments, you can pass
as the argument class instead. (
<bottom> is a subclass of all
(define-method foo ((x <sequence>) (y <integer>)) #f) (applicable? foo <top> <top>) ⇒ #f (applicable? foo <bottom> <bottom>) ⇒ #t
See Types and classes, for the details of
Gauche’s type handling.
~ can be used to access a part of various
;; Access to an element of a sequence by index (~ '(a b c) 0) ⇒ a (~ '#(a b c) 2) ⇒ c (~ "abc" 1) ⇒ #\b (~ '#u8(10 20 30) 1) ⇒ 20 ;; Access to an element of a collection by key (~ (hash-table 'eq? '(a . 1) '(b . 2)) 'a) ⇒ 1 ;; Access to a slot of an object by slot name (~ (sys-localtime (sys-time)) 'hour) ⇒ 20
The access can be chained:
(~ '#((a b c) (d e f) (g h i)) 1 2) ⇒ f (~ (hash-table 'eq? '(a . "abc") '(d . "def")) 'a 2) ⇒ #\c
You can think
~ as left-associative, that is,
(~ x k j) ≡ (~ (~ x k) j)
and so on.
The generalized setter
set! can be used with
replace the specified element.
(define z (vector 'a 'b 'c)) (set! (~ z 1) 'Z) z ⇒ #(a Z c) (define z (vector (list (vector 'a 'b 'c) (vector 'd 'e 'f) (vector 'g 'h 'i)) (list (vector 'a 'b 'c) (vector 'd 'e 'f) (vector 'g 'h 'i)))) z ⇒ #((#(a b c) #(d e f) #(g h i)) (#(a b c) #(d e f) #(g h i))) (set! (~ z 1 2 0) 'Z) z ⇒ #((#(a b c) #(d e f) #(g h i)) (#(a b c) #(d e f) #(Z h i)))
Internally, a call to
~ is implemented by a generic
ref. See Object system for more about
Many aggregate types defines a specialized method of these
to provide uniform access and mutation. Meaning of
optional arguments args of
on each specialized method,
but it is common that the first optional argument of
is a fallback value, which is to be returned when
object doesn’t have a meaningful association with key.
The manual entry of each aggregate type shows the specialized method and its semantics in detail.
~ can be understood as follows:
(define ~ (getter-with-setter (case-lambda [(obj selector) (ref obj selector)] [(obj selector . more) (apply ~ (ref obj selector) more)]) (case-lambda [(obj selector val) ((setter ref) obj selector val)] [(obj selector selector2 . rest) (apply (setter ~) (ref obj selector) selector2 rest)])))
(Gauche may use some short-cut for optimization, though, so this code may not reflect the actual implementation.)
Gauche has some primitive procedures that allows combinatory programming.
Partial application. Returns a procedure, and when it is
called with arguments m …, it is equivalent to call
(proc arg … m …).
(define add3 (pa$ + 3)) (add3 4) ⇒ 7 (map (pa$ * 2) '(1 2 3)) ⇒ (2 4 6)
cute defined in SRFI-26 provide
a similar abstraction, with a bit more flexible but less compact
notation. See Making Procedures.
Partial application versions of
(define map2* (map$ (pa$ * 2))) (map2* '(1 2 3)) ⇒ (2 4 6)
Partial application versions of some srfi-1 procedures (see List library).
Combine procedures. All arguments must be procedures.
When two procedures are given,
(.$ f g) is equivalent to
the following code:
(lambda args (call-with-values (lambda () (apply g args)) f))
When more than two arguments are passed, they are composed as follows:
(.$ f g h ...) ≡ (.$ (.$ f g) h ...)
(define not-zero? (.$ not zero?)) (not-zero? 3) ⇒ #t (not-zero? 0) ⇒ #f (define dot-product (.$ (apply$ +) (map$ *))) (dot-product '(1 2 3) '(4 5 6)) ⇒ 32
A couple of edge cases: if only one argument is given, the argument
itself is returned. If no arguments are given, the procedure
Note: The name
.$ comes from the fact that
commonly used for function composition in literatures and some
programming languages, and that Gauche uses suffix
indicate combinators. However, since it is not a valid R7RS
identifier, portable programs may want to use the alias
with which you can easily add a portable definition using
Returns a procedure that reverses the meaning of the predicate pred. That is, for the arguments for which pred returns true return false, and vice versa.
(map (complement even?) '(1 2 3)) ⇒ '(#t #f #t) (map (complement =) '(1 2 3) '(1 1 3)) ⇒ '(#f #t #f) ((complement (lambda () #f))) ⇒ #t
Returns a procedure which applies given argument(s) to
each predicate pred. If any pred returns
#f value, the value is returned. If all the preds
#f is returned.
(define string-or-symbol? (any-pred string? symbol?)) (string-or-symbol? "abc") ⇒ #t (string-or-symbol? 'abc) ⇒ #t (string-or-symbol? 3) ⇒ #f (define <> (any-pred < >)) (<> 3 4) ⇒ #t (<> 3 3) ⇒ #f ((any-pred (cut memq <> '(a b c)) (cut memq <> '(1 2 3))) 'b) ⇒ '(b c)
Returns a procedure which applies given argument(s) to
each predicate pred. If every pred returns
#f value, the value returned by the last pred
is returned. If any pred returns
#f without calling further preds.
((every-pred odd? positive?) 3) ⇒ #t ((every-pred odd? positive?) 4) ⇒ #f ((every-pred odd? positive?) -3) ⇒ #f (define safe-length (every-pred list? length)) (safe-length '(a b c)) ⇒ 3 (safe-length "aaa") ⇒ #f
Gauche supports optional and keyword arguments in extended lambda syntax (see Making Procedures). However, you can also use the following macros to parse optional and keyword arguments, without relying Gauche’s extension.
(define (foo a b :optional (c #f) (d 'none)) body ...) ;; is roughly equivalent to ... (define (foo a b . args) (let-optionals* args ((c #f) (d 'none)) body ...))
Explicitly parsing the extended arguments may be useful for portable programs, since it is rather straightforward to implement those macros rather than extend lambda syntax.
Those macros can also be useful to factor out common argument parsing routines.
Given a list of values restargs, binds variables according to var-spec, then evaluates body.
Var-spec can be either a symbol, or a list of two elements and its car is a symbol. The symbol is the bound variable name. The values in restargs are bound to the symbol in order. If there are not as many values in restargs as var-spec, the rest of symbols are bound to the default values, determined as follows: If var-spec is just a symbol, the default value is undefined. If var-spec is a list, the default value is the result of evaluation of the second element of the list. In the latter case the second element is only evaluated when there are not enough arguments. The binding proceeds in the order of var-spec, so the second element may refer to the bindings of previous var-spec.
In the second form, restvar must be a symbol and bound to the list of values whatever left from restargs after binding to var-spec.
It is not an error if restarg has more values than var-specs. The extra values are simply ignored in the first form.
(define (proc x . args) (let-optionals* args ((a 'a) (b 'b) (c 'c)) (list x a b c))) (proc 0) ⇒ (0 a b c) (proc 0 1) ⇒ (0 1 b c) (proc 0 1 2) ⇒ (0 1 2 c) (proc 0 1 2 3) ⇒ (0 1 2 3) (define (proc2 . args) (let-optionals* args ((a 'a) . b) (list a b))) (proc2) ⇒ (a ()) (proc2 0) ⇒ (0 ()) (proc2 0 1) ⇒ (0 (1)) (proc2 0 1 2) ⇒ (0 (1 2)) (define (proc3 . args) (let-optionals* args ((a 0) (b (+ a 1)) (c (+ b 1))) (list a b c))) (proc3) ⇒ (0 1 2) (proc3 8) ⇒ (8 9 10) (proc3 8 2) ⇒ (8 2 3) (proc3 8 2 -1) ⇒ (8 2 -1)
This is a short version of let-optionals* where you have only one optional argument. Given the optional argument list restargs, this macro returns the value of optional argument if one is given, or the result of default otherwise. Default is not evaluated unless restargs is an empty list.
(define (proc x . maybe-opt) (let ((option (get-optional maybe-opt #f))) (list x option))) (proc 0) ⇒ (0 #f) (proc 0 1) ⇒ (0 1)
This macro is for keyword arguments. Var-spec can be one of the following forms:
If the restarg contains keyword which has the same name as symbol, binds symbol to the corresponding value. If such a keyword doesn’t appear in restarg, binds symbol to the result of expr.
(symbol keyword expr)
If the restarg contains keyword keyword, binds symbol to the corresponding value. If such a keyword doesn’t appear in restarg, binds symbol to the result of expr.
The default value expr is only evaluated when the keyword is not given to the restarg.
If you use the first form,
let-keyword throws an error
restarg contains a keyword argument that is not listed
When you want to allow keyword arguments other than listed in
var-specs, use the second form.
In the second form, restvar must be either a symbol or
If it is a symbol, it is bound to a list of keyword arguments
that are not processed by var-specs. If it is
such keyword arguments are just ignored.
(define (proc x . options) (let-keywords options ((a 'a) (b :beta 'b) (c 'c) . rest) (list x a b c rest))) (proc 0) ⇒ (0 a b c ()) (proc 0 :a 1) ⇒ (0 1 b c ()) (proc 0 :beta 1) ⇒ (0 a 1 c ()) (proc 0 :beta 1 :c 3 :unknown 4) ⇒ (0 a 1 3 (:unknown 4))
let-keywords, but the binding is done in the order of
var-specs. So each expr can refer to the variables bound by
Interface to query procedure’s arity. The API is taken from MzScheme (PLT Scheme).
Given procedure proc, returns an integer, an arity-at-least object, or a list of integer(s) and arity-at-least objects.
An integer result indicates proc takes exactly that number
of arguments. An arity-at-least indicates proc takes
arguments. The list indicates there are multiple procedures
with different arities.
Since one can add methods to an existing procedure or generic function
at any moment in Gauche, the value returned by
indicates the current state of the procedure. It will change
if new method is added to the procedure/generic-function.
(arity cons) ⇒ 2 (arity list) ⇒ #<arity-at-least 0> (arity make) ⇒ (#<arity-at-least 1>)
Returns true if obj is an arity-at-least object.
Returns the number of required arguments the arity-at-least object indicates.
If a procedure proc can take k arguments, returns
Gauche has a special hook to make an arbitrary object applicable.
If an object that is neither a procedure nor a generic function
is applied to some arguments,
the object and the arguments are passed to a generic function
This can be explained better by examples.
For example, suppose you try to evaluate the following expression:
The operator evaluates to a string, which is neither a procedure nor a generic function. So Gauche interprets the expression as if it were like this:
(object-apply "abcde" 2)
Gauche doesn’t define a method of
object-apply that takes
<integer> by default, so this signals an error.
However, if you define such a method:
(define-method object-apply ((s <string>) (i <integer>)) (string-ref s i))
Then the first expression works as if a string is applied on the integer:
("abcde" 2) ⇒ #\c
This mechanism works on almost all occasions where a procedure is allowed.
(apply "abcde" '(1)) ⇒ (#\b) (map "abcde" '(3 2 1)) ⇒ (#\d #\c #\b)
Among Gauche built-in objects,
<regexp> object and
<regmatch> object have
See Regular expressions.
If a form of applying an applicable object appears in the first position
set! form, this method is called, that is:
(set! (object arg …) value) ⇒ ((setter object-apply) object arg … value)
Encapsulates the current continuation to a procedure
(“continuation procedure”), and calls proc with it.
When proc returns, its value becomes
When the continuation procedure is invoked with zero or more arguments
somewhere, the further calculation is abandoned and
with the arguments given to the continuation procedure.
First class continuation is one of the most distinct feature of Scheme, but this margin is too small to contain explanation. Please consult to the appropriate documents.
There’s a nontrivial interaction between C language runtime and Scheme continuation. Suppose the following scenario:
It is no problem to invoke the continuation, but if the control is about to return to the Scheme routine to the C runtime (that is, to execute step 3 again), an error is signaled as follows.
*** ERROR: attempt to return from a ghost continuation.
This is because C routines don’t expect the calling function to return more than once. The C stack frame on which the Scheme callback was originally called is likely to be deallocated or modified at the time the continuation is invoked.
If you think of a continuation as a chain of control frames, growing from root towards upward, you can imagine that, once a control returns to the C world, the chain is cut at the boundary. You can still execute such rootless continuations, but you have to move the control away from it before it tries to return to its root that no longer exists. You can call another continuation, or raise an exception, for example.
Using partial continuations (or delimited continuations) is another way to avoid such complications. See Partial continuations.
This macro expands to :
(call/cc (lambda (var) body …)).
The API is taken from PLT Scheme.
This is a primitive to manage dynamic environment.
Dynamic environment is a set of states which are kept during execution
of a certain expression. For example, the current output ports
are switched during execution of
They can be nested dynamically, as opposed to
the lexical environment, in which nesting is determined statically
from the program source.
Before, body and after are all procedures with
In normal situation,
dynamic-wind calls before, then body,
then after, then returns whatever value(s) body returned.
The intention is that the before thunk sets up the dynamic environment for execution of body, and the after thunk restores it to the previous state.
If a control flow goes out from body by invoking a continuation
captured outside of the dynamic scope of
(for example, an error is signaled in body),
after is called.
If a control flow goes into body by invoking a continuation
captured inside body from outside of the dynamic
dynamic-wind, before is called.
(letrec ((paths '()) (c #f) (add (lambda (s) (push! paths s)))) (dynamic-wind (lambda () (add 'connect)) (lambda () (add (call/cc (lambda (c0) (set! c c0) 'talk1)))) (lambda () (add 'disconnect))) (if (< (length paths) 4) (c 'talk2) (reverse paths))) ⇒ (connect talk1 disconnect connect talk2 disconnect)
Note: Since after is guaranteed to be called when
an error causes body to abort, it may appear tempting
dynamic-wind to use resource clean-up, just like
try-catch construct in Java. It’s not for that.
Since the control may return to body, the situation
dynamic-wind handles should be considered more like
a context switch.
For resource clean-up, you can use exception handling mechanism
unwind-protect (see Handling exceptions),
which is built on top of
As a rule of thumb, after should do things that can be reverted by before, such as manipulating error handler stack (instead of actually handling errors).
Returns obj … as multiple values.
Caller can capture multiple values by a built-in syntax
receive (Binding constructs), or the R5Rs procedure
call-with-values described below.
See also Let-values.
(values 1 2) ⇒ 1 and 2
[R7RS] Call a procedure producer with no argument. Then applies a procedure consumer on the value(s) producer returned. Returns the value(s) consumer returns.
(call-with-values (lambda () (values 1 2)) cons) ⇒ (1 . 2)
Returns k-th value of what mv-expr returns. Conceptually, it is the same as the following code.
(call-with-values (lambda () mv-expr) (lambda r (list-ref r k)))
This macro uses shortcuts for the typical cases like k is zero.
Similar to Common Lisp’s
nth-value, but the argument order
is flipped to match other Scheme’s
Evaluates mv-expr, puts all the results into a list
and returns it. It is called
(values->list (div-and-mod 10 3)) ⇒ (3 1) (values->list 1) ⇒ (1)
Sometimes a procedure is used as a generator of a series
of values, by yielding one value at a time. Customary an EOF
object is used to mark the end of the series. For example,
read-char is such a procedure that yields a series
of characters, terminated by EOF.
Since it is such a handy abstraction, Gauche provides a set of utilities (see Generators) to construct and generators out of various sources, including other generators.
The generated values needs to be consumed eventually. Here we
provide several procedures to do that. These are useful
when combined with input procedures like
read, so we
have them built-in instead of putting them in a separate module.
fold on the generated values by generator
procedures gen gen2 … (See Walking over lists,
for the details of
When one generator is given, for each value v generated by gen,
proc is called as
(proc v r), where
r is the current accumulated result; the initial value of the
accumulated result is seed,
and the return value from proc becomes the next accumulated result.
When gen returns EOF, the accumulated result at that time is returned
When more than one generator is given, proc is
(proc v1 v2 … r),
where v1, v2 … are the values yielded from
gen, gen2, …, respectively, and r is
the current accumulated result. The iteration terminates when
any one of the generators returns EOF.
(with-input-from-string "a b c d e" (cut generator-fold cons 'z read)) ⇒ (e d c b a . z)
fold-right on the generated values by generator
procedures gen gen2 … (see Walking over lists,
for the details of
This is provided for completeness, but it isn’t a good way to handle generators; in order to combine values right-associatively, we should read all the values from the generators (until any one of the generator returns EOF), then start calling proc as
(proc v0_0 v1_0 ... (proc v0_1 v1_1 ... (proc v0_n v1_n ... seed) ...))
where vn_m is the m-th value yielded by n-th generator.
(with-input-from-string "a b c d e" (cut generator-fold-right cons 'z read)) ⇒ (a b c d e . z)
As you see, keeping all intermediate values kind of defeats the benefit of generators.
A generator version of
for-each. Repeatedly applies proc on
the values yielded by gen, gen2 … until any one of
the generators yields EOF. The values returned from proc are discarded.
This is a handy procedure to consume generated values with side effects.
A generator version of
map. Repeatedly applies proc on
the values yielded by gen, gen2 … until any one of
the generators yields EOF. The values returned from proc
are collected into a list and returned.
(with-input-from-string "a b c d e" (cut generator-map symbol->string read)) ⇒ ("a" "b" "c" "d" "e")
The same effects can be achieved by combining
gmap (see Generator operations). This procedure
is provided for the backward compatibility.
(generator->list (gmap proc gen gen2 …))
Returns the first item from the generator gen that satisfies the predicate pred.
The following example returns the first line matching the regexp
#/XYZ/ from the file foo.txt.
(with-input-from-file "foo.txt" (cut generator-find #/XYZ/ read-line))
Note: If you want to pick all the lines matching the regexp,
you can use