1881 lines
44 KiB
Plaintext
1881 lines
44 KiB
Plaintext
.so ../util/tmac.scheme
|
|
.Ul
|
|
.ds R "R\*(^4RS
|
|
.TL
|
|
Elk \*- The Extension Language Kit
|
|
.sp .5
|
|
Scheme Reference
|
|
.AU
|
|
Oliver Laumann
|
|
.
|
|
.Ch "Introduction"
|
|
.
|
|
.PP
|
|
This reference manual lists the primitive procedures, special forms,
|
|
and other facilities implemented by the Scheme interpreter included
|
|
in Elk.
|
|
This \f2kernel\fP functionality can be augmented by applications
|
|
using Elk as their extension language implementation or by
|
|
reusable Elk extensions (such as the UNIX or X11 extensions included
|
|
in the distribution).
|
|
The predefined Elk extensions and the C/C++ programmer's interface
|
|
to Elk are described in separate documents.
|
|
.PP
|
|
Only the procedures and special forms that are not defined by the
|
|
official Scheme language specification ``\*R'' (William Clinger and
|
|
Jonathan Rees (editors), \f2Revised\*(^4 Report on the Algorithmic
|
|
Language Scheme\fP, 1991) are described in detail.
|
|
The language features that are part of the official language are only
|
|
mentioned without a description or examples.
|
|
.
|
|
.Ch "Lambda Expressions, Procedures"
|
|
.
|
|
.Sy lambda formals body
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr procedure-lambda procedure
|
|
.LP
|
|
Returns a copy of the \f2lambda\fP expression which has been
|
|
evaluated to create the given procedure.
|
|
.br
|
|
Example:
|
|
.Ss
|
|
(define (square x) (* x x))
|
|
(procedure-lambda square) ==> (lambda (x) (* x x))
|
|
.Se
|
|
.
|
|
.Pr procedure? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr primitive? obj
|
|
.LP
|
|
Returns #t if \f2obj\fP is a primitive procedure, #f otherwise.
|
|
.
|
|
.Pr compound? obj
|
|
.LP
|
|
Returns #t if \f2obj\fP is a compound procedure (a procedure that
|
|
has been created by evaluating a lambda expression), #f otherwise.
|
|
.
|
|
.Ch "Local Bindings"
|
|
.
|
|
.[[
|
|
.Sy let bindings body
|
|
.Sy let* bindings body
|
|
.Sy letrec bindings body
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Fluid Binding"
|
|
.
|
|
.Sy fluid-let bindings body
|
|
.LP
|
|
\f2bindings\fP is of the form ((\f2variable\*1\fP \f2init1\fP) ...).
|
|
The \f2init\fPs are temporarily assigned to the \f2variable\fPs
|
|
and the \f2body\fP is executed.
|
|
The variables must be bound in an enclosing scope.
|
|
When the body is exited normally or by invoking a control point,
|
|
the old values of the variables are restored.
|
|
In the latter case, when the control returns back to the body
|
|
of the fluid-let by invocation of a control point created within
|
|
the body, the bindings are changed again to the values they had
|
|
when the body exited.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
((lambda (x)
|
|
(+ x (fluid-let ((x 3)) x))) 1) ==> 4
|
|
.Se
|
|
.Ss
|
|
(fluid-let ((print-length 2))
|
|
(write '(a b c d))) ==> '(a b ...)
|
|
.Se
|
|
.Ss
|
|
(define (errset thunk)
|
|
(call-with-current-continuation
|
|
(lambda (catch)
|
|
(fluid-let
|
|
((error-handler
|
|
(lambda msg (catch #f))))
|
|
(list (thunk))))))
|
|
.sp
|
|
(errset (lambda () (+ 1 2))) ==> (3)
|
|
(errset (lambda () (/ 1 0))) ==> #f
|
|
.Se
|
|
.
|
|
.Ch "Definitions"
|
|
.
|
|
.[[
|
|
.Sy define variable expression
|
|
.Sy define (variable formals) body
|
|
.Sy define (variable . formal) body
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Returns a symbol, the identifier that has been bound.
|
|
Definitions may appear anywhere within a local body (e.\|g.\& a lambda
|
|
body or a \f2let\fP).
|
|
If the \f2expression\fP is omitted, \f2void\fP (the non-printing
|
|
object) is used.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define nil #f)
|
|
.Se
|
|
.Ss
|
|
(define ((f x) y) (cons x y))
|
|
(define (g x) ((f x) 5))
|
|
(g 'a) ==> (a . 5)
|
|
.Se
|
|
.
|
|
.Ch "Assignment"
|
|
.
|
|
.Sy set! variable expression
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Returns the previous value of \f2variable\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define-macro (swap x y)
|
|
`(set! ,x (set! ,y ,x)))
|
|
.Se
|
|
.
|
|
.Ch "Procedure Application"
|
|
.
|
|
.Sy operator operand\*1 ...
|
|
.LP
|
|
See \*R.
|
|
\f2operator\fP can be a macro (see below).
|
|
.
|
|
.Pr apply arg\*1 ... args
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Quotation, Quasiquotation"
|
|
.
|
|
.[[
|
|
.Sy quote datum
|
|
.br
|
|
.ie \n(.U \f3'\fP\f2datum\fP
|
|
.el .tl ,\f3'\fP\f2datum\fP,,\f3syntax\fP,
|
|
.br
|
|
.ie \n(.U \f2constant\fP
|
|
.el .tl ,\f2constant\fP,,\f3syntax\fP
|
|
.]]
|
|
.Id constant
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Sy quasiquote expression
|
|
.Sy unquote expression
|
|
.Sy unquote-splicing expression
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Sequencing"
|
|
.
|
|
.Sy begin expression\*1 expression\*2 ...
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Sy begin1 expression\*1 expression\*2 ...
|
|
.LP
|
|
Identical to \f2begin\fP, except that the result of the first
|
|
\f2expression\fP is returned.
|
|
.
|
|
.Ch "Conditionals"
|
|
.
|
|
.[[
|
|
.Sy if test consequent alternate
|
|
.Sy if test consequent
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
In the first form, \f2alternate\fP can be a sequence of expressions
|
|
(implicit \f2begin\fP).
|
|
.
|
|
.Sy case key clause\*1 clause\*2 ...
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Each \f2clause\fP not beginning with \f2else\fP can be of the form
|
|
.DS
|
|
((\f2datum\*1\fP ...) \f2expression\*1\fP \f2expression\*2\fP ...)
|
|
.DE
|
|
or
|
|
.DS
|
|
(\f2datum\fP \f2expression\*1\fP \f2expression\*2\fP ...)
|
|
.DE
|
|
In the latter case, the \f2key\fP is matched against the \f2datum\fP.
|
|
.
|
|
.Sy cond clause\*1 clause\*2 ...
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Sy and test\*1 ...
|
|
.Sy or test\*1 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Booleans"
|
|
.
|
|
.Pr not obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr boolean? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Iteration"
|
|
.
|
|
.Sy let variable bindings body
|
|
.LP
|
|
``Named \f2let\fP''.
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr map procedure list\*1 list\*2 ...
|
|
.Pr for-each procedure list\*1 list\*2 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
\f2for-each\fP returns the empty list.
|
|
.
|
|
.Sy do initializations test body
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Continuations"
|
|
.
|
|
.Pr call-with-current-continuation procedure
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr control-point? obj
|
|
.LP
|
|
Returns #t if \f2obj\fP is a control point (a continuation),
|
|
#f otherwise.
|
|
.
|
|
.Pr dynamic-wind thunk thunk thunk
|
|
.LP
|
|
\f2dynamic-wind\fP is a generalization of the
|
|
.Ix unwind-protect
|
|
\f2unwind-protect\fP facility provided by many Lisp systems.
|
|
.br
|
|
All three arguments are procedures of no arguments.
|
|
In the normal case, all three thunks are applied in order.
|
|
The first thunk is also applied when the body (the second thunk)
|
|
is entered by the application of a control point created within
|
|
the body (by means of
|
|
.Ix call-with-current-continuation
|
|
\f2call-with-current-continuation\fP).
|
|
Similarly, the third thunk is also applied whenever the body is
|
|
exited by invocation of a control point created outside the body.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define-macro (unwind-protect body . unwind-forms)
|
|
`(dynamic-wind
|
|
(lambda () #f)
|
|
(lambda () ,body)
|
|
(lambda () ,@unwind-forms)))
|
|
.Se
|
|
.Ss
|
|
(let ((f (open-input-file "foo")))
|
|
(dynamic-wind
|
|
(lambda () #f)
|
|
(lambda () \f2do something with\fP f)
|
|
(lambda () (close-input-port f))))
|
|
.Se
|
|
.
|
|
.Ch "Delayed Evaluation"
|
|
.
|
|
.[[
|
|
.Sy delay expression
|
|
.Pr force promise
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr promise? obj
|
|
.LP
|
|
Returns #t if \f2obj\fP is a promise, an object returned by the
|
|
application of \f2delay\fP.
|
|
Otherwise #f is returned.
|
|
.
|
|
.Ch "Equivalence Predicates"
|
|
.
|
|
.[[
|
|
.Pr eq? obj\*1 obj\*2
|
|
.Pr eqv? obj\*1 obj\*2
|
|
.Pr equal? obj\*1 obj\*2
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Pairs and Lists"
|
|
.
|
|
.Pr cons obj\*1 obj\*2
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr car pair
|
|
.Pr cdr pair
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr cxr pair pattern
|
|
.LP
|
|
\f2pattern\fP is either a symbol or a string consisting of a combination
|
|
of the characters `a' and `d'.
|
|
It encodes a sequence of \f2car\fP and \f2cdr\fP operations;
|
|
each `a' denotes the application of \f2car\fP, and each `d' denotes
|
|
the application of \f2cdr\fP.
|
|
For example, \f2(cxr p "ada")\fP is equivalent to \f2(cadar p)\fP.
|
|
.
|
|
.Pr caar pair
|
|
.br
|
|
...
|
|
.br
|
|
.Pr cddddr pair
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr set-car! pair obj
|
|
.Pr set-cdr! pair obj
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Both procedures return \f2obj\fP.
|
|
.
|
|
.Pr make-list k obj
|
|
.LP
|
|
Returns a list of length \f2k\fP initialized with \f2obj\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(make-list 0 'a) ==> ()
|
|
(make-list 2 (make-list 2 1)) ==> ((1 1) (1 1))
|
|
.Se
|
|
.
|
|
.Pr list obj ...
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr length list
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr list-ref list k
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr list-tail list k
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr last-pair list
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr append list ...
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr append! list ...
|
|
.LP
|
|
Like \f2append\fP, except that the original
|
|
arguments are modified (destructive \f2append\fP).
|
|
The cdr of each argument is changed to point to the next argument.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define x '(a b))
|
|
(append x '(c d)) ==> (a b c d)
|
|
x ==> (a b)
|
|
(append! x '(c d)) ==> (a b c d)
|
|
x ==> (a b c d)
|
|
.Se
|
|
.
|
|
.Pr reverse list
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr reverse! list
|
|
.LP
|
|
Destructive \f2reverse\fP.
|
|
.
|
|
.[[
|
|
.Pr memq obj list
|
|
.Pr memv obj list
|
|
.Pr member obj list
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr assq obj alist
|
|
.Pr assv obj alist
|
|
.Pr assoc obj alist
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr null? obj
|
|
.Pr pair? obj
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr list? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Numbers"
|
|
.
|
|
.[[
|
|
.Pr = z\*1 z\*2 ...
|
|
.Pr < z\*1 z\*2 ...
|
|
.Pr > z\*1 z\*2 ...
|
|
.Pr <= z\*1 z\*2 ...
|
|
.Pr >= z\*1 z\*2 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr 1+ z
|
|
.Pr -1+ z
|
|
.]]
|
|
.LP
|
|
Returns \f2z\fP plus 1 or \f2z\fP minus 1, respectively.
|
|
.
|
|
.Pr 1- z
|
|
.LP
|
|
A synonym for \f2-1+\fP (for backwards compatibility).
|
|
.
|
|
.[[
|
|
.Pr + z\*1 ...
|
|
.Pr * z\*1 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr - z\*1 z\*2 ...
|
|
.Pr / z\*1 z\*2 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr zero? z
|
|
.Pr positive? z
|
|
.Pr negative? z
|
|
.Pr odd? z
|
|
.Pr even? z
|
|
.Pr exact? z
|
|
.Pr inexact? z
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr abs z
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr quotient n\*1 n\*2
|
|
.Pr remainder n\*1 n\*2
|
|
.Pr modulo n\*1 n\*2
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr gcd n\*1 ...
|
|
.Pr lcm n\*1 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr floor x
|
|
.Pr ceiling x
|
|
.Pr truncate x
|
|
.Pr round x
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr sqrt z
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr expt z\*1 z\*2
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr exp z
|
|
.Pr log z
|
|
.Pr sin z
|
|
.Pr cos z
|
|
.Pr tan z
|
|
.Pr asin z
|
|
.Pr acos z
|
|
.Pr atan z
|
|
.Pr atan y x
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr min x\*1 x\*2 ...
|
|
.Pr max x\*1 x\*2 ...
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr random
|
|
.LP
|
|
Returns an integer pseudo-random number in the range from 0 to
|
|
.ie \n(.U 2^31-1.
|
|
.el 2\v'-.3m'\s-131\s0\v'.3m'-1.
|
|
.
|
|
.Pr srandom n
|
|
.LP
|
|
Sets the random number generator to the starting point \f2n\fP.
|
|
\f2srandom\fP returns \f2n\fP.
|
|
.
|
|
.[[
|
|
.Pr number? obj
|
|
.Pr complex? obj
|
|
.Pr real? obj
|
|
.Pr rational? obj
|
|
.Pr integer? obj
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr exact\(mi>inexact z
|
|
.Pr inexact\(mi>exact z
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr number\(mi>string number
|
|
.Pr number\(mi>string number radix
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr string\(mi>number string
|
|
.Pr string\(mi>number string radix
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Characters"
|
|
.
|
|
.[[
|
|
.Pr char\(mi>integer char
|
|
.Pr integer\(mi>char n
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr char-upper-case? char
|
|
.Pr char-lower-case? char
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr char-alphabetic? char
|
|
.Pr char-numeric? char
|
|
.Pr char-whitespace? char
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr char-upcase char
|
|
.Pr char-downcase char
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr char=? char\*1 char\*2
|
|
.Pr char<? char\*1 char\*2
|
|
.Pr char>? char\*1 char\*2
|
|
.Pr char<=? char\*1 char\*2
|
|
.Pr char>=? char\*1 char\*2
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr char-ci=? char\*1 char\*2
|
|
.Pr char-ci<? char\*1 char\*2
|
|
.Pr char-ci>? char\*1 char\*2
|
|
.Pr char-ci<=? char\*1 char\*2
|
|
.Pr char-ci>=? char\*1 char\*2
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr char? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Ch "Strings"
|
|
.
|
|
.Pr string char ...
|
|
.LP
|
|
Returns a string containing the specified characters.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(string) ==> ""
|
|
(string #\ea #\espace #\eb) ==> "a b"
|
|
.Se
|
|
.
|
|
.Pr string? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr make-string k char
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr string-length string
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr string-ref string k
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr string-set! string k char
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Returns the previous value of element \f2k\fP of the given string.
|
|
.
|
|
.Pr substring string start end
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr string-copy string
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr string-append string ...
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr list\(mi>string chars
|
|
.Pr string\(mi>list string
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr string-fill! string char
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Returns \f2string\fP.
|
|
.
|
|
.Pr substring-fill! string start end char
|
|
.LP
|
|
Stores \f2char\fP in every element of \f2string\fP from \f2start\fP
|
|
(inclusive) to \f2end\fP (exclusive).
|
|
Returns \f2string\fP.
|
|
.
|
|
.[[
|
|
.Pr string=? string\*1 string\*2
|
|
.Pr string<? string\*1 string\*2
|
|
.Pr string>? string\*1 string\*2
|
|
.Pr string<=? string\*1 string\*2
|
|
.Pr string>=? string\*1 string\*2
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr string-ci=? string\*1 string\*2
|
|
.Pr string-ci<? string\*1 string\*2
|
|
.Pr string-ci>? string\*1 string\*2
|
|
.Pr string-ci<=? string\*1 string\*2
|
|
.Pr string-ci>=? string\*1 string\*2
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr substring? string\*1 string\*2
|
|
.Pr substring-ci? string\*1 string\*2
|
|
.]]
|
|
.LP
|
|
If \f2string\*1\fP is a substring of \f2string\*2\fP, these
|
|
procedures return the starting position of the first occurrence of the
|
|
substring within \f2string\*2\fP.
|
|
Otherwise #f is returned.
|
|
\f2substring-ci?\fP is the case insensitive version of \f2substring?\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define s "Hello world")
|
|
(substring? "foo" x) ==> #f
|
|
(substring? "hello" x) ==> #f
|
|
(substring-ci? "hello" x) ==> 0
|
|
(substring? "!" x) ==> 11
|
|
.Se
|
|
.
|
|
.Ch "Vectors"
|
|
.
|
|
.Pr vector? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr make-vector k
|
|
.Pr make-vector k fill
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr vector obj ...
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr vector-length vector
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr vector-ref vector k
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr vector-set! vector k obj
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Returns the previous value of element \f2k\fP of the vector.
|
|
.
|
|
.[[
|
|
.Pr vector\(mi>list vector
|
|
.Pr list\(mi>vector list
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr vector-fill! vector fill
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Returns \f2vector\fP.
|
|
.
|
|
.Pr vector-copy vector
|
|
.LP
|
|
Returns a copy of \f2vector\fP.
|
|
.
|
|
.Ch "Symbols"
|
|
.
|
|
.[[
|
|
.Pr string\(mi>symbol string
|
|
.Pr symbol\(mi>string symbol
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr put symbol key value
|
|
.Pr put symbol key
|
|
.]]
|
|
.LP
|
|
Associates \f2value\fP with \f2key\fP in the
|
|
.Ix "property list"
|
|
property list of the given symbol.
|
|
\f2key\fP must be a symbol.
|
|
Returns \f2key\fP.
|
|
.br
|
|
If \f2value\fP is omitted, the property is removed from the symbol's
|
|
property list.
|
|
.
|
|
.Pr get symbol key
|
|
.LP
|
|
Returns the value associated with \f2key\fP in the
|
|
.Ix "property list"
|
|
property list of \f2symbol\fP.
|
|
\f2key\fP must be a symbol.
|
|
If no value is associated with \f2key\fP in the symbol's property
|
|
list, #f is returned.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(put 'norway 'capital "Oslo")
|
|
(put 'norway 'continent "Europe")
|
|
(get 'norway 'capital) ==> "Oslo"
|
|
.Se
|
|
.
|
|
.Pr symbol-plist symbol
|
|
.LP
|
|
Returns a copy of the
|
|
.Ix "property list"
|
|
property list of \f2symbol\fP as an \f2alist\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(put 'norway 'capital "Oslo")
|
|
(put 'norway 'continent "Europe")
|
|
(symbol-plist 'norway)
|
|
==> ((capital . "Oslo") (continent . "Europe"))
|
|
(symbol-plist 'foo) ==> ()
|
|
.Se
|
|
.
|
|
.Pr symbol? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr oblist
|
|
.LP
|
|
Returns a list of lists containing all currently interned symbols.
|
|
Each sublist represents a bucket of the interpreters internal
|
|
hash array.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define (apropos what)
|
|
(let ((ret ()))
|
|
(do ((tail (oblist) (cdr tail))) ((null? tail))
|
|
(do ((l (car tail) (cdr l))) ((null? l))
|
|
(if (substring? what (symbol->string (car l)))
|
|
(set! ret (cons (car l) ret)))))
|
|
ret))
|
|
.Se
|
|
.Ss
|
|
(apropos "let") ==> (let* let letrec fluid-let)
|
|
(apropos "make") ==> (make-list make-vector make-string)
|
|
(apropos "foo") ==> ()
|
|
.Se
|
|
.
|
|
.Ch "Environments"
|
|
.
|
|
.Pr the-environment
|
|
.LP
|
|
Returns the current environment.
|
|
.
|
|
.Pr global-environment
|
|
.LP
|
|
Returns the global environment (the ``root'' environment in which
|
|
all predefined procedures are bound).
|
|
.
|
|
.Pr environment\(mi>list environment
|
|
.LP
|
|
Returns a list representing the specified environment.
|
|
The list is a list of \f2frames\fP, each frame is a list of bindings
|
|
(an \f2alist\fP).
|
|
The car of the list represents the most recently established environment.
|
|
The list returned by \f2environment\(mi>list\fP can contain cycles.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(let ((x 1) (y 2))
|
|
(car (environment->list
|
|
(the-environment)))) ==> ((y . 2) (x . 1))
|
|
.Se
|
|
.Ss
|
|
((lambda (foo)
|
|
(caar (environment->list
|
|
(the-environment)))) "abc") ==> (foo . "abc")
|
|
.Se
|
|
.Ss
|
|
(eq?
|
|
(car (last-pair (environment->list
|
|
(the-environment))))
|
|
(car (environment->list
|
|
(global-environment)))) ==> #t
|
|
.Se
|
|
.
|
|
.[[
|
|
.Pr procedure-environment procedure
|
|
.Pr promise-environment promise
|
|
.Pr control-point-environment control-point
|
|
.]]
|
|
.LP
|
|
Returns the environment in which the the body of the \f2procedure\fP
|
|
is evaluated, the environment in which a value for the \f2promise\fP
|
|
is computed when \f2force\fP is applied to it, or the environment in
|
|
which the \f2control-point\fP has been created, respectively.
|
|
.
|
|
.Pr environment? obj
|
|
.LP
|
|
Returns #t if \f2obj\fP is an environment, #f otherwise.
|
|
.
|
|
.Ch "Ports and Files"
|
|
.LP
|
|
Generally, a
|
|
.Ix "file name"
|
|
file name can either be a string or a symbol.
|
|
If a symbol is given, it is converted into a string by applying
|
|
.Ix symbol\(mi>string
|
|
\f2symbol\(mi>string\fP.
|
|
A
|
|
.Ix tilde
|
|
tilde at the beginning of a file name is expanded according
|
|
to the rules employed by the C-Shell (see \f2csh\fP(1)).
|
|
.LP
|
|
Elk adds a third type of ports, \f2input-output\fP (bidirectional) ports.
|
|
Both \f2input-port?\fP and \f2output-port?\fP return #t when applied
|
|
to an input-output port, and both input primitives and output
|
|
primitives may be applied to input-output ports.
|
|
An input-output port (in fact, \f2any\fP port) may be closed with any of
|
|
the primitives \f2close-input-port\fP and \f2close-output-port\fP.
|
|
.LP
|
|
The only way to create an input-output-port is by means of the procedure
|
|
.Ix open-input-output-file
|
|
\f2open-input-output-file\fP.
|
|
Extensions may provide additional means to create bidirectional ports.
|
|
.
|
|
.[[
|
|
.Pr call-with-input-file file procedure
|
|
.Pr call-with-output-file file procedure
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr input-port? obj
|
|
.Pr output-port? obj
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr current-input-port
|
|
.Pr current-output-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr with-input-from-file file thunk
|
|
.Pr with-output-to-file file thunk
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
\f2file\fP can be a string as well as a symbol.
|
|
.
|
|
.[[
|
|
.Pr open-input-file file
|
|
.Pr open-output-file file
|
|
.Pr open-input-output-file file
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
\f2file\fP can be a string as well as a symbol.
|
|
\f2open-input-output-file\fP opens the file for reading and writing
|
|
and returns an input-output port; the file must exist and is not
|
|
truncated.
|
|
.
|
|
.[[
|
|
.Pr close-input-port port
|
|
.Pr close-output-port port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.br
|
|
Calls to \f2close-input-port\fP and \f2close-output-port\fP are ignored
|
|
when applied to string ports or to ports connected with the standard
|
|
input or standard output of the process.
|
|
.
|
|
.[[
|
|
.Pr clear-output-port
|
|
.Pr clear-output-port output-port
|
|
.]]
|
|
.LP
|
|
If the argument is omitted, it defaults to the current output port.
|
|
.br
|
|
In case of ``buffered'' output, this procedure is used to discard
|
|
all characters that have been
|
|
output to the port but have not yet been sent to the file associated
|
|
with the port.
|
|
.
|
|
.[[
|
|
.Pr flush-output-port
|
|
.Pr flush-output-port output-port
|
|
.]]
|
|
.LP
|
|
If the argument is omitted, it defaults to the current output port.
|
|
.br
|
|
In case of ``buffered'' output, this procedure is used to force
|
|
all characters that have been output to the port to be printed
|
|
immediately.
|
|
This may be necessary to force output that is not terminated with a newline
|
|
to appear on the terminal.
|
|
An output port is flushed automatically when it is closed.
|
|
.
|
|
.[[
|
|
.Pr clear-input-port
|
|
.Pr clear-input-port input-port
|
|
.]]
|
|
.LP
|
|
If the argument is omitted, it defaults to the current input port.
|
|
.br
|
|
In case of ``buffered'' input,
|
|
this procedure discards all characters that have already been read
|
|
from the file associated with the port but have not been processed
|
|
using \f2read\fP or similar procedures.
|
|
.
|
|
.Pr port-file-name port
|
|
.LP
|
|
Returns the name of the file associated with \f2port\fP if it is
|
|
a file port, #f otherwise.
|
|
.
|
|
.Pr port-line-number
|
|
.LP
|
|
Returns the current line number of a file input port or string input
|
|
port, i.\|e.\& the number of newline characters that have been read from
|
|
this port plus one.
|
|
``Unreading'' a newline character decrements the line number, but it
|
|
never drops below one.
|
|
The result of applying \f2port-line-number\fP to an output port is
|
|
undefined.
|
|
.
|
|
.Pr tilde-expand file
|
|
.LP
|
|
If \f2file\fP starts with a tilde, performs tilde expansion as
|
|
described above and returns the result of the expansion
|
|
(a string); returns \f2file\fP otherwise.
|
|
\f2file\fP is a string or a symbol.
|
|
.
|
|
.Pr file-exists? file
|
|
.LP
|
|
Returns #t if \f2file\fP is accessible, #f otherwise.
|
|
\f2file\fP is a string or a symbol; tilde expansion is not performed.
|
|
.
|
|
.Ch "Input"
|
|
.
|
|
.[[
|
|
.Pr read
|
|
.Pr read input-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr read-char
|
|
.Pr read-char input-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr read-string
|
|
.Pr read-string input-port
|
|
.]]
|
|
.LP
|
|
If the argument is omitted, it defaults to the current input port.
|
|
.br
|
|
Returns the rest of the current input line as a string (not
|
|
including the terminating newline).
|
|
.
|
|
.[[
|
|
.Pr unread-char char
|
|
.Pr unread-char char input-port
|
|
.]]
|
|
.LP
|
|
If the second argument is omitted, it defaults to the current input port.
|
|
.br
|
|
Pushes \f2char\fP back on the stream of input characters.
|
|
It is \f2not\fP an error for \f2char\fP not to be the last character
|
|
read from the port.
|
|
It is undefined whether more than one character can be pushed back without
|
|
an intermittent read operation, and whether a character can be pushed
|
|
back before something has been read from the port.
|
|
The procedure returns \f2char\fP.
|
|
.
|
|
.[[
|
|
.Pr peek-char
|
|
.Pr peek-char input-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.LP
|
|
\f2peek-char\fP uses \f2unread-char\fP to push back the character.
|
|
.
|
|
.Pr eof-object? obj
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.Pr char-ready? input-port
|
|
.LP
|
|
See \*R.
|
|
.LP
|
|
\f2char-ready\fP cannot be implemented correctly based on C FILE pointers.
|
|
In the current version, \f2char-ready\fP can return #f although
|
|
a call to \f2read-char\fP would not block.
|
|
.
|
|
.Ch "Output"
|
|
.
|
|
.[[
|
|
.Va print-length
|
|
.Va print-depth
|
|
.]]
|
|
.LP
|
|
These variables are defined in the global environment.
|
|
They control the maximum length and maximum depth, respectively, of
|
|
a list or vector that is printed.
|
|
If one of the variables is not bound to an integer, or if its value
|
|
exceeds a certain, large maximum value (which is at least 2^20),
|
|
a default value is taken.
|
|
The default value for \f2print-length\fP is 1000, and the default
|
|
value for \f2print-depth\fP is 20.
|
|
Negative values of \f2print-length\fP and \f2print-depth\fP are
|
|
treated as ``unlimited'', i.\|e.\& output is not truncated.
|
|
.
|
|
.[[
|
|
.Pr write obj
|
|
.Pr write obj output-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr display obj
|
|
.Pr display obj output-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr write-char char
|
|
.Pr write-char char output-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr newline
|
|
.Pr newline output-port
|
|
.]]
|
|
.LP
|
|
See \*R.
|
|
.
|
|
.[[
|
|
.Pr print obj
|
|
.Pr print obj output-port
|
|
.]]
|
|
.LP
|
|
If the second argument is omitted, it defaults to the current output port.
|
|
.br
|
|
Prints \f2obj\fP using \f2write\fP and then prints a newline.
|
|
\f2print\fP returns \f2void\fP.
|
|
.
|
|
.Pr format destination format-string obj ...
|
|
.LP
|
|
Prints the third and the following arguments according to the
|
|
specifications in the string \f2format-string\fP.
|
|
Characters from the format string are copied to the output.
|
|
When a tilde is encountered in the format string, the tilde and
|
|
the immediately following character are replaced in the output
|
|
as follows:
|
|
.IP "~s"
|
|
is replaced by the printed representation of the next \f2obj\fP
|
|
in the sense of \f2write\fP.
|
|
.IP "~a"
|
|
is replaced by the printed representation of the next \f2obj\fP
|
|
in the sense of \f2display\fP.
|
|
.IP "~~"
|
|
is replaced by a single tilde.
|
|
.IP "~%"
|
|
is replaced by a newline.
|
|
.LP
|
|
An error is signaled if fewer \f2obj\fPs are provided than
|
|
required by the given format string.
|
|
If the format string ends in a tilde, the tilde is ignored.
|
|
.LP
|
|
If \f2destination\fP is #t, the output is sent to the current
|
|
output port; if #f is given, the output is returned as a string;
|
|
otherwise, \f2destination\fP must be an output or input-output port.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(format #f "Hello world!") ==> "Hello world"
|
|
(format #f "~s world!" "Hello") ==> "\e"Hello\e" world"
|
|
(format #f "~a world!" "Hello") ==> "Hello world"
|
|
(format #f "Hello~a") ==> "Hello!"
|
|
.Se
|
|
.Ss
|
|
(define (flat-size s)
|
|
(fluid-let ((print-length 1000) (print-depth 100))
|
|
(string-length (format #f "~a" s))))
|
|
.Se
|
|
.Ss
|
|
(flat-size 1.5) ==> 3
|
|
(flat-size '(a b c)) ==> 7
|
|
.Se
|
|
.
|
|
.Ch "String Ports"
|
|
.LP
|
|
.Ix "string ports"
|
|
String ports are similar to file ports, except that characters are
|
|
appended to a string instead of being sent to a file, or taken
|
|
from a string instead of being read from a file.
|
|
It is not necessary to close string ports.
|
|
When an string input port has reached the end of the input string,
|
|
successive read operations return end-of-file.
|
|
.
|
|
.Pr open-input-string string
|
|
.LP
|
|
Returns a new string input port initialized with \f2string\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define p (open-input-string "Hello world!"))
|
|
(read-char p) ==> #\eH
|
|
(read p) ==> ello
|
|
(read p) ==> world!
|
|
(read p) ==> \f2end of file\fP
|
|
.Se
|
|
.Ss
|
|
(define p (open-input-string "(cons 'a 'b)"))
|
|
(eval (read p)) ==> (a . b)
|
|
.Se
|
|
.
|
|
.Pr open-output-string
|
|
.LP
|
|
Returns a new string output port.
|
|
.
|
|
.Pr get-output-string string-output-port
|
|
.LP
|
|
Returns the string currently associated with the specified string
|
|
output port.
|
|
As a side-effect, the string is reset to zero length.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define p (open-output-string))
|
|
(display '(a b c) p)
|
|
(get-output-string p) ==> "(a b c)"
|
|
(get-output-string p) ==> ""
|
|
.Se
|
|
.Ss
|
|
(define (flat-size s)
|
|
(let ((p (open-output-string)))
|
|
(display s p)
|
|
(string-length (get-output-string p))))
|
|
.Se
|
|
.
|
|
.Ch "Loading"
|
|
.
|
|
.[[
|
|
.Pr load file
|
|
.Pr load file environment
|
|
.]]
|
|
.LP
|
|
Loads a source file or one or more object files.
|
|
If the file contains source code, the expressions in the file are
|
|
read and evaluated.
|
|
If a file contains
|
|
.Ix "object code"
|
|
object code, the contents of the file is linked
|
|
together with the running interpreter and with additional libraries
|
|
that are specified by the variable
|
|
.Ix load-libraries
|
|
\f2load-libraries\fP (see below).
|
|
Names of
|
|
.Ix "object files"
|
|
object files must have the
|
|
.Ix suffix
|
|
suffix ``.o''.
|
|
\f2load\fP returns \f2void\fP.
|
|
.LP
|
|
\f2file\fP must be either a string or a symbol or a list of strings
|
|
or symbols.
|
|
If it is a list, all elements of the list must be the names of object files.
|
|
In this case, all object files are linked by a single run of the
|
|
.Ix linker
|
|
linker.
|
|
.br
|
|
If an optional \f2environment\fP is specified, the contents of the file
|
|
is evaluated in this environment instead of the current environment.
|
|
.LP
|
|
Loading of object files is not supported on some platforms.
|
|
On the platforms where it is supported, the feature
|
|
.Ix feature
|
|
.Ix elk:load-object
|
|
\f2elk:load-object\fP is provided by the interpreter on startup (see
|
|
``Features'' below).
|
|
.br
|
|
Example:
|
|
.Ss
|
|
(fluid-let ((load-noisily? #t))
|
|
(load 'test.scm))
|
|
.Se
|
|
.
|
|
.Va load-path
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
It is bound to a list of directories in which files to be loaded are
|
|
searched for.
|
|
Each element of the list (a string or a symbol) is used in turn as
|
|
a prefix for the file name passed to \f2load\fP until opening succeeds.
|
|
Elements of \f2load-path\fP that are not of type string or symbol are ignored.
|
|
.LP
|
|
If the value of \f2load-path\fP is not a list of at least one valid
|
|
component, or if the name of the file to be loaded starts with ``/''
|
|
or with ``~'', it is opened directly.
|
|
.LP
|
|
The initial value of \f2load-path\fP is a list of the three elements
|
|
``.'' (i.\|e.\& the current directory), ``$scheme_dir'', and ``$lib_dir'';
|
|
$scheme_dir and $lib_dir are the directories into which
|
|
the runtime Scheme files and object files are installed (typically
|
|
``/usr/elk/runtime/scm'' and ``/usr/elk/runtime/obj''; defined in
|
|
the installation's
|
|
.Ix "site file"
|
|
site file).
|
|
.
|
|
.Va load-noisily?
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
When a file is loaded and the value of \f2load-noisily?\fP is true,
|
|
the result of the evaluation of each expression is printed.
|
|
The initial value of \f2load-noisily?\fP is #f.
|
|
.
|
|
.Va load-libraries
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
If \f2load-libraries\fP is bound to a string, its value specifies
|
|
additional load libraries to be linked together with an
|
|
.Ix "object file"
|
|
object file that is loaded into the interpreter (see \f2load\fP above).
|
|
Its initial value is ``\-lc''.
|
|
.
|
|
.Pr autoload symbol file
|
|
.LP
|
|
Binds \f2symbol\fP in the current environment (as with \f2define\fP).
|
|
When \f2symbol\fP is evaluated the first time, \f2file\fP is loaded.
|
|
The definitions loaded from the file must provide a definition
|
|
for \f2symbol\fP different from \f2autoload\fP, otherwise an error
|
|
is signaled.
|
|
.LP
|
|
\f2file\fP must be either a string or a symbol or a list of strings
|
|
or symbols, in which case all elements of the list must be the names of
|
|
.Ix "object file"
|
|
object files (see \f2load\fP above).
|
|
.
|
|
.Va autoload-notify?
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
If the value of \f2autoload-notify?\fP is true, a message is printed
|
|
whenever evaluation of a symbol triggers autoloading of a file.
|
|
\f2autoload-notify?\fP is bound to #t initially.
|
|
.
|
|
.Ch "Macros"
|
|
.
|
|
.Sy macro formals body
|
|
.LP
|
|
This special form creates a macro.
|
|
The syntax is identical to the syntax of \f2lambda\fP expressions.
|
|
When a macro is called, the actual arguments are bound to
|
|
the formal arguments of the \f2macro\fP expression \f2in the current
|
|
environment\fP (they are \f2not\fP evaluated), then the \f2body\fP is evaluated.
|
|
The result of this evaluation is considered the \f2macro expansion\fP
|
|
and is evaluated in place of the macro call.
|
|
.
|
|
.[[
|
|
.Sy define-macro (variable formals) body
|
|
.Sy define-macro (variable . formal) body
|
|
.]]
|
|
.LP
|
|
Like \f2define\fP, except that \f2macro\fP is used instead of \f2lambda\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define-macro (++ x) `(set! ,x (1+ ,x)))
|
|
(define foo 5)
|
|
foo ==> 5
|
|
(++ foo)
|
|
foo ==> 6
|
|
.Se
|
|
.Ss
|
|
(define-macro (while test . body)
|
|
`(let loop ()
|
|
(cond (,test ,@body (loop)))))
|
|
.Se
|
|
.
|
|
.Pr macro? obj
|
|
.LP
|
|
Returns #t if \f2obj\fP is a macro, #f otherwise.
|
|
.
|
|
.Pr macro-body macro
|
|
.LP
|
|
Returns a copy of the \f2macro\fP expression which has been evaluated to
|
|
created the given macro (similar to
|
|
.Ix procedure-lambda
|
|
\f2procedure-lambda\fP).
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define-macro (++ x) `(set! ,x (1+ ,x)))
|
|
.sp
|
|
(macro-body ++)
|
|
==> (macro (x) (quasiquote (set! (unquote x) (1+ (unquote x)))))
|
|
.Se
|
|
.
|
|
.Pr macro-expand list
|
|
.LP
|
|
If the expression \f2list\fP is a macro call, the macro call
|
|
is expanded.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define-macro (++ x) `(set! ,x (1+ ,x)))
|
|
.sp
|
|
(macro-expand '(++ foo)) ==> (set! foo (1+ foo))
|
|
.Se
|
|
.sp
|
|
The following function can be used to expand \f2all\fP macro calls
|
|
in an expression, i.\|e.\& not only at the outermost level:
|
|
.Ss
|
|
(define (expand form)
|
|
(if (or (not (pair? form)) (null? form))
|
|
form
|
|
(let ((head (expand (car form)))
|
|
(args (expand (cdr form)))
|
|
(result))
|
|
(if (and (symbol? head) (bound? head))
|
|
(begin
|
|
(set! result (macro-expand (cons head args)))
|
|
(if (not (equal? result form))
|
|
(expand result)
|
|
result))
|
|
(cons head args)))))
|
|
.Se
|
|
.
|
|
.Ch "Error and Exception Handling"
|
|
.
|
|
.Va error-handler
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
When an error occurs or when the procedure \f2error\fP is invoked
|
|
and the variable \f2error-handler\fP is bound to a compound procedure
|
|
(the \f2error handler\fP), the interpreter invokes this procedure.
|
|
The error handler is called with an object (either the first argument
|
|
that has been passed to \f2error\fP or a symbol identifying the
|
|
primitive procedure that has caused the error), and an error
|
|
message consisting of a format string
|
|
and a list of objects suitable to be passed to
|
|
.Ix format
|
|
\f2format\fP.
|
|
.LP
|
|
Typically, a user-defined error handler prints the error message and then
|
|
calls a control point that has been created outside the error handler.
|
|
If the error handler terminates normally or if \f2error-handler\fP
|
|
is not bound to a procedure, the error message is printed in a
|
|
default way, and then a
|
|
.Ix reset
|
|
\f2reset\fP is performed.
|
|
.
|
|
.Va interrupt-handler
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
When an interrupt occurs (typically as a result of typing the
|
|
interrupt character on the keyboard), and the variable
|
|
\f2interrupt-handler\fP is bound to a procedure (the \f2interrupt
|
|
handler\fP), this procedure is called with no arguments.
|
|
If \f2interrupt-handler\fP is not bound to a procedure or if
|
|
the procedure terminates normally, a message is printed, and a
|
|
.Ix reset
|
|
\f2reset\fP is performed.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(set! interrupt-handler
|
|
(lambda ()
|
|
(newline)
|
|
(backtrace)
|
|
(reset)))
|
|
.Se
|
|
.
|
|
.[[
|
|
.Pr disable-interrupts
|
|
.Pr enable-interrupts
|
|
.]]
|
|
.LP
|
|
\f2disable-interrupts\fP causes
|
|
.Ix signals
|
|
signals to be blocked from delivery to
|
|
the interpreter; \f2enable-interrupts\fP enables delivery of signals.
|
|
These functions control delivery of keyboard-generated interrupt signals
|
|
(see \f2interrupt-handler\fP above) as well as additional signals used by
|
|
extensions (such as the alarm signal).
|
|
The interpreter automatically blocks delivery of signals during critical
|
|
operations, such as garbage collection.
|
|
Signals are enabled on startup after initialization has completed.
|
|
.LP
|
|
A call to \f2enable-interrupts\fP immediately delivers signals that have
|
|
been generated while signals were disabled, but blocked signals are not
|
|
queued.
|
|
On platforms that support neither POSIX-style nor BSD-style reliable
|
|
signals, \f2disable-interrupts\fP causes signals to be ignored (as
|
|
opposed to blocking them until the next call to \f2enable-interrupts\fP).
|
|
.LP
|
|
Calls to \f2disable-interrupts\fP and \f2enable-interrupts\fP can be
|
|
nested.
|
|
The functions maintain a count indicating the number of calls
|
|
to \f2enable-interrupts\fP that it takes to return from a nested
|
|
\f2disable-interrupts\fP invocation to the topmost level (i.\|e.\& to
|
|
actually enable delivery of signals again).
|
|
Both functions return this nesting level as an integer.
|
|
.LP
|
|
Example: the following loop ensures that delivery of signals is enabled,
|
|
regardless of the current nesting depth of \f2disable-interrupts\fP calls:
|
|
.Ss
|
|
(let loop ((intr-level (enable-interrupts)))
|
|
(if (positive? intr-level)
|
|
(loop (enable-interrupts))))
|
|
|
|
.Se
|
|
.LP
|
|
.Ix dynamic-wind
|
|
\f2dynamic-wind\fP can be used to write a macro
|
|
.Ix with-interrupts-disabled
|
|
\f2with-interrupts-disabled\fP to protect a
|
|
.Ix "critical section"
|
|
critical section of code from being interrupted by a signal:
|
|
.Ss
|
|
(define-macro (with-interrupts-disabled . body)
|
|
`(dynamic-wind
|
|
(lambda () (disable-interrupts))
|
|
(lambda () ,@body)
|
|
(lambda () (enable-interrupts))))
|
|
.Se
|
|
.
|
|
.Pr error obj string obj ...
|
|
.LP
|
|
Signals an error.
|
|
The arguments of \f2error\fP are passed to the
|
|
.Ix error-handler
|
|
\f2error-handler\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(define (foo sym)
|
|
(if (not (symbol? sym))
|
|
(error 'foo "argument not a symbol: ~s" sym))
|
|
...
|
|
.Se
|
|
.
|
|
.[[
|
|
.Va top-level-control-point
|
|
.Pr reset
|
|
.]]
|
|
.LP
|
|
\f2reset\fP performs a reset by calling the control point to which the
|
|
variable \f2top-level-control-point\fP is bound in the global environment.
|
|
The control point is called with the argument #t.
|
|
If \f2top-level-control-point\fP is not bound to a control point,
|
|
or does not exist at all,
|
|
an error message is printed and the interpreter is terminated.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(if (call-with-current-continuation
|
|
(lambda (x)
|
|
(fluid-let ((top-level-control-point x))
|
|
\0\0\0\0\0\0\0\0\0\0\f2do\0something\fP
|
|
#f)))
|
|
(print "Got a reset!"))
|
|
.Se
|
|
.
|
|
.[[
|
|
.Pr exit
|
|
.Pr exit n
|
|
.]]
|
|
.LP
|
|
Terminates the interpreter.
|
|
The optional argument \f2n\fP indicates the
|
|
.Ix "exit code"
|
|
exit code; it defaults to zero.
|
|
.
|
|
.Ch "Garbage Collection"
|
|
.LP
|
|
The interpreter supports two
|
|
.Ix "garbage collector"
|
|
garbage collectors: the
|
|
.Ix "garbage collector, stop-and-copy"
|
|
stop-and-copy garbage collector that was part of older versions of Elk, and a
|
|
.Ix "garbage collector, generational"
|
|
.Ix "garbage collector, incremental"
|
|
generational, incremental garbage collector.
|
|
.LP
|
|
If generational garbage collection has been selected, Scheme objects
|
|
surviving two garbage collections will not be touched again until
|
|
there is only a certain amount of memory left on the heap, triggering
|
|
a full garbage collection.
|
|
Particularly in applications with large amounts of Scheme code or
|
|
constant data, partial garbage collections run much faster than full
|
|
garbage collections.
|
|
In contrast to the stop-and-copy garbage collector, the generational
|
|
garbage collector is not limited to a pre-allocated amount of
|
|
heap; it will expand the heap in steps of 1 MB if the free space left
|
|
after a full garbage collection falls below a certain amount.
|
|
.LP
|
|
Another feature of the generational garbage collector (available on
|
|
some platforms only) is the ability to do incremental garbage
|
|
collection.
|
|
Starting a garbage collection does not interrupt the application until
|
|
the garbage collector is done.
|
|
Instead, the collector returns control to the application almost
|
|
immediately.
|
|
To synchronize between the garbage collection and the running
|
|
application, the code makes use of the \f2mprotect\fP system call.
|
|
.
|
|
.Pr garbage-collect-status strategy mode
|
|
.LP
|
|
\f2garbage-collect-status\fP is used to select a garbage collector
|
|
and an optional, garbage collector specific mode of operation, and
|
|
to query the currently enabled garbage collector and mode.
|
|
.LP
|
|
\f2strategy\fP is a symbol identifying a garbage collector.
|
|
Permitted values are \f2stop-and-copy\fP and \f2generational\fP
|
|
(future version of Elk may support additional garbage collectors).
|
|
The optional \f2mode\fP argument may be specified if the \f2strategy\fP
|
|
argument is equal to \f2generational\fP.
|
|
Currently, only the symbol \f2incremental\fP may be used for the
|
|
\f2mode\fP argument to enable incremental garbage collection.
|
|
.LP
|
|
The current version of the interpreter does not support dynamic
|
|
switching between the stop-and-copy and the generational, incremental
|
|
garbage collector at runtime.
|
|
Instead, a garbage collector has to be selected at compile time
|
|
(by setting the \f2generational_gc\fP variable in the installation's
|
|
.Ix "site file"
|
|
site file to either \f2yes\fP or \f2no\fP).
|
|
Thus, \f2garbage-collect-status\fP can currently only be used to query
|
|
the garbage collector and, if the generational, incremental garbage
|
|
collector has been selected, to enable and disable incremental
|
|
garbage collection (this restriction may be removed in future versions).
|
|
.LP
|
|
\f2garbage-collect-status\fP returns a list of symbols indicating
|
|
the currently enabled garbage collector and mode.
|
|
This list resembles the arguments to \f2garbage-collect-status\fP,
|
|
i.\|e.\& the first element of the list one of the symbols
|
|
\f2stop-and-copy\fP and \f2generational\fP, and an optional, second
|
|
symbol (\f2incremental\fP) may be present if the first symbol is
|
|
equal to \f2generational\fP.
|
|
.LP
|
|
If \f2garbage-collect-status\fP is invoked with no arguments, or if
|
|
the desired garbage collector or mode of operation cannot be enabled
|
|
(either because selection of a strategy at runtime is not supported,
|
|
of because the mode of operation cannot be supported), the primitive
|
|
just returns the currently active strategy and mode.
|
|
.
|
|
.Pr collect
|
|
.LP
|
|
Causes a garbage collection.
|
|
Even if incremental garbage collection has been enabled, \f2collect\fP
|
|
always performs a full garbage collection run.
|
|
.
|
|
.Pr collect-incremental
|
|
.LP
|
|
This primitive is only present if the generational
|
|
garbage collector has been selected.
|
|
An error is signaled if \f2collect-incremental\fP is
|
|
invoked and incremental garbage collection has not been enabled,
|
|
i.\|e.\& if a call to \f2garbage-collect-status\fP would return
|
|
the list \f2(generational)\fP.
|
|
.LP
|
|
\f2collect-incremental\fP starts an incremental garbage
|
|
collection and then returns immediately.
|
|
If an incremental garbage collection is already in progress,
|
|
\f2collect-incremental\fP triggers one incremental
|
|
garbage collection step, i.\|e.\& scans a few more pages of memory,
|
|
and then returns immediately.
|
|
The primitive returns true if the incremental garbage collection
|
|
has been finished, false otherwise.
|
|
.LP
|
|
If incremental garbage collection is disabled by a call to
|
|
\f2(garbage-collect-status 'generational)\fP while an incremental
|
|
garbage collection run is in progress, the next call to
|
|
\f2collect-incremental\fP finishes the incremental garbage collection run
|
|
and returns #t; further calls to \f2collect-incremental\fP will
|
|
signal an error.
|
|
.
|
|
.Va garbage-collect-notify?
|
|
.LP
|
|
This variable is defined in the global environment.
|
|
If the value of \f2garbage-collect-notify?\fP is true,
|
|
a message indicating the amount of free memory on the heap and
|
|
the size of the heap are displayed whenever a stop-and-copy garbage
|
|
collection is performed.
|
|
If the generational, incremental garbage collector has been enabled,
|
|
the amount of reclaimed memory is displayed on each garbage
|
|
collection run, and a message is displayed each time the heap
|
|
is expanded by the garbage collector.
|
|
\f2garbage-collect-notify?\fP is bound to #t initially.
|
|
.
|
|
.Ch "Features"
|
|
.
|
|
.Pr feature? symbol
|
|
.LP
|
|
Returns #t if \f2symbol\fP is a feature, i.\|e.\& \f2provide\fP has
|
|
been called to indicate that the feature \f2symbol\fP is present;
|
|
#f otherwise.
|
|
.
|
|
.Pr provide symbol
|
|
.LP
|
|
Indicates that the feature \f2symbol\fP is present.
|
|
Returns \f2void\fP.
|
|
.
|
|
.[[
|
|
.Pr require symbol
|
|
.Pr require symbol file
|
|
.Pr require symbol file environment
|
|
.]]
|
|
.LP
|
|
If the feature \f2symbol\fP is not present (i.\|e.
|
|
(feature? \f2symbol\fP) evaluates to #f), \f2file\fP is loaded.
|
|
A message is displayed prior to loading the file if the value of the
|
|
global variable \f2autoload-notify?\fP is true.
|
|
If the feature is still not present after the file has been loaded,
|
|
an error is signaled.
|
|
.LP
|
|
If the \f2file\fP argument is omitted, it defaults to \f2symbol\fP;
|
|
if \f2symbol\fP does not end in a
|
|
.Ix suffix
|
|
suffix (i.\|e.\& does not contain a dot character), the suffix \f2.scm\fP
|
|
is appended to obtain a file name.
|
|
.LP
|
|
If an \f2environment\fP argument is supplied, the file is loaded
|
|
into given environment.
|
|
If the \f2environment\fP argument is omitted, it defaults to the
|
|
current environment.
|
|
.LP
|
|
\f2file\fP must be either a string or a symbol or a list of strings
|
|
or symbols, in which case all elements of the list must be the names
|
|
of object files (see \f2load\fP above).
|
|
.
|
|
.Pr features
|
|
.LP
|
|
Returns the currently provided features a list of symbols.
|
|
.
|
|
.Ch "Miscellaneous"
|
|
.
|
|
.Pr dump file
|
|
.LP
|
|
Writes a snapshot of the running interpreter to \f2file\fP and
|
|
returns #f.
|
|
When \f2file\fP is executed, execution of the interpreter resumes such
|
|
that the call to \f2dump\fP returns #t
|
|
(i.e., \f2dump\fP actually returns twice).
|
|
\f2dump\fP closes all ports except the current input and current
|
|
output port.
|
|
.LP
|
|
This primitive is not supported on platforms that are not capable
|
|
of creating an executable file from the memory image of the
|
|
running process.
|
|
If \f2dump\fP is available, the
|
|
.Ix feature
|
|
.Ix elk:dump
|
|
feature \f2elk:dump\fP is provided by the interpreter on startup
|
|
(see ``Features'' above).
|
|
.
|
|
.[[
|
|
.Pr eval list
|
|
.Pr eval list environment
|
|
.]]
|
|
.LP
|
|
Evaluates the expression \f2list\fP in the specified environment.
|
|
If \f2environment\fP is omitted, the expression is evaluated
|
|
in the current environment.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(let ((car 1))
|
|
(eval 'car (global-environment))) ==> \f2primitive\fP \f1car\fP
|
|
.Se
|
|
.Ss
|
|
(define x 1)
|
|
(define env
|
|
(let ((x 2)) (the-environment)))
|
|
(eval 'x) ==> 1
|
|
(eval 'x env) ==> 2
|
|
.Se
|
|
.
|
|
.Pr bound? symbol
|
|
.LP
|
|
Returns #t if \f2symbol\fP is bound in the current environment,
|
|
#f otherwise.
|
|
.
|
|
.Pr type obj
|
|
.LP
|
|
Returns a symbol indicating the type of \f2obj\fP.
|
|
.br
|
|
Examples:
|
|
.Ss
|
|
(type 13782343423544) ==> integer
|
|
(type 1.5e8) ==> real
|
|
(type (lambda (x y) (cons x y))) ==> compound
|
|
(type #\ea) ==> character
|
|
(type '(a b c)) ==> pair
|
|
(type '()) ==> null
|
|
(type (read
|
|
(open-input-string ""))) ==> end-of-file
|
|
.Se
|
|
.
|
|
.Pr void? obj
|
|
.LP
|
|
Returns true if \f2obj\fP is the non-printing object, false otherwise.
|
|
.
|
|
.Pr command-line-args
|
|
.LP
|
|
Returns the command line arguments of the interpreter's invocation,
|
|
a list of strings.
|
|
.
|
|
.Ch "\*R Language Features not Implemented by Elk"
|
|
.IP \(bu
|
|
Rational and complex numbers are not supported.
|
|
.IP \(bu
|
|
Radix prefixes (#b, #o, #d, and #x) for real numbers are currently
|
|
not implemented.
|
|
.IP \(bu
|
|
The exponent markers \f2s\fP, \f2f\fP, \f2d\fP, and \f2l\fP are not
|
|
implemented; the character \f2#\fP is not permitted in place of digits
|
|
in numerical constants.
|
|
.IP \(bu
|
|
\f2char-ready\fP
|
|
.Ix char-ready
|
|
is not implemented correctly (see above).
|
|
.IP \(bu
|
|
\f2transcript-on\fP and \f2transcript-off\fP are not implemented.
|
|
.LP
|